From 617d970718c5858d00460331ac01156b2c2cedb1 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 4 Apr 2026 16:45:58 -0700 Subject: [PATCH] docs(ecosystem): harden artifact lifecycle and event taxonomy --- docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md | 73 +++++++++++- .../ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md | 109 ++++++++++++++++-- 2 files changed, 173 insertions(+), 9 deletions(-) diff --git a/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md b/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md index 7759e753..ba0327ce 100644 --- a/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md +++ b/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md @@ -1,6 +1,6 @@ # Ecosystem Event Taxonomy -> **Status:** Phase 1 baseline implemented +> **Status:** Hardened baseline > **Owner:** `learning_ai_common_plat` > **Purpose:** Define the canonical event vocabulary for cross-product activity, agent execution, approvals, artifacts, and downstream replay. @@ -185,9 +185,77 @@ Current implementation note: - `entitlement.granted` - `entitlement.revoked` +### 5.9 Timeline and review events + +- `timeline.item.materialized` +- `timeline.item.hidden` +- `timeline.item.restored` +- `review.session.started` +- `review.session.completed` + +### 5.10 Marketplace and distribution events + +- `marketplace.listing.published` +- `marketplace.listing.updated` +- `marketplace.listing.deprecated` +- `marketplace.asset.installed` +- `marketplace.asset.uninstalled` + +### 5.11 Identity and auth events + +- `identity.session.created` +- `identity.session.step_up_required` +- `identity.session.step_up_completed` +- `identity.session.revoked` + +### 5.12 Notification and delivery events + +- `delivery.notification.queued` +- `delivery.notification.sent` +- `delivery.notification.failed` +- `delivery.digest.generated` + +### 5.13 Local-first and sync events + +- `sync.state.changed` +- `sync.artifact.enqueued` +- `sync.artifact.reconciled` +- `sync.conflict.detected` + --- -## 6. High-Priority Events For Phase 1 +## 6. Phase Coverage + +### 6.1 Implemented baseline + +- [x] `capture.transcript.created` +- [x] `artifact.created` +- [x] `artifact.linked` +- [x] `memory.entry.created` +- [x] `agent.run.started` +- [x] `agent.run.completed` +- [x] `approval.action.requested` +- [x] `approval.action.approved` +- [x] `approval.action.denied` +- [x] `audit.action.logged` + +### 6.2 Canonical-but-not-yet-broadly-adopted families + +- [ ] planning-specific event families beyond the artifact seam +- [ ] trust and identity transition events +- [ ] marketplace publication and installation events +- [ ] notification and digest events +- [ ] sync and local-first lifecycle events + +### 6.3 Reserved For Later Adoption + +- [ ] timeline materialization and hiding events +- [ ] delivery failure and retry detail events +- [ ] richer safety policy decision events + +--- + +## 7. High-Priority Events For Early Adoption These should be implemented first because they unlock the initial cross-product flows: @@ -210,6 +278,7 @@ Commits: - `76f1b47` added canonical Phase 1 event schemas and example payloads - `78918fb` extended canonical artifact payloads so Phase 2 can reuse `artifact.created` and `artifact.linked` for `plan`, `routine`, and `habit` - `e6b58b7` extended canonical artifact payloads so Phase 3 can reuse `artifact.created` for `trail-report` and preserve the audited note -> memory seam without introducing a second event family +- `ab50831` tracked broader taxonomy hardening as remaining work --- diff --git a/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md b/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md index 0204b5f2..d98e354c 100644 --- a/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md +++ b/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md @@ -1,6 +1,6 @@ # Ecosystem Shared Artifact Schema -> **Status:** Phase 3 baseline implemented +> **Status:** Hardened baseline > **Owner:** `learning_ai_common_plat` > **Purpose:** Define the canonical cross-product artifact model so notes, transcripts, plans, memories, trails, routes, and agent outputs can interoperate cleanly. @@ -160,34 +160,128 @@ Phase 2 adopters: --- -## 7. Key Open Decisions +## 7. Storage And Lifecycle Rules + +The canonical envelope does not force one backend, but it does require consistent lifecycle semantics. + +### 7.1 Storage classes + +Every artifact should be classified into one of these storage classes: + +- `primary-record` + - the canonical user-facing artifact record + - examples: note, plan, memory, routine +- `derived-record` + - generated from other artifacts or events but still retained as a first-class object + - examples: trail-report, digest, agent-output +- `ephemeral-cache` + - regenerable helper artifact that may be dropped without lineage loss + - examples: intermediate summaries, transient extraction output +- `binary-attachment` + - large file/blob stored through metadata indirection + - examples: audio, screenshots, exported reports + +### 7.2 Retention rules + +- `primary-record` + - retain until user deletion, legal deletion requirement, or explicit archival policy +- `derived-record` + - retain while upstream artifacts still exist unless product policy intentionally purges it +- `ephemeral-cache` + - safe to expire automatically if provenance and regeneration inputs remain +- `binary-attachment` + - may use external blob storage, but the artifact envelope must retain the reference metadata + +### 7.3 Versioning rules + +- the envelope may evolve independently from product payload versions +- `payload` should carry a product-local version when the artifact type is likely to evolve incompatibly +- migrations must preserve: + - `id` + - `artifactType` + - `ownership` + - `provenance` + - `links` + +### 7.4 Binary attachment rules + +Binary artifacts should not inline the binary content in the canonical envelope. Instead: + +- store file metadata in `payload` or `links` +- include: + - content type + - logical filename + - byte size when known + - blob/storage reference + - integrity hash when feasible +- preserve enough metadata for downstream access control and audit + +### 7.5 Deletion and archival rules + +- deleting an artifact should not silently delete downstream lineage evidence +- tombstones or archived metadata should preserve: + - `id` + - `artifactType` + - `productId` + - `ownership` + - minimal provenance +- archival may hide payload details while keeping the lineage graph intact + +## 8. Migration Strategy For First Adopters + +Phase-based migration should be incremental, not all-or-nothing. + +1. wrap product-local objects in the canonical envelope without replacing local schemas +2. emit canonical links and provenance first +3. backfill stable artifact IDs only when needed for downstream consumers +4. move binary/file references behind metadata indirection where needed +5. only after that, tighten product-local persistence or indexing around the shared model + +First-adopter guidance: + +- LysnrAI + - transcript artifact is the canonical record; audio remains a binary attachment reference +- NoteLett + - note remains the primary record; transcript and trail relationships are represented through links +- MindLyst + - memory proposal is a derived record until accepted into a stronger user-owned memory shape +- FlowMonk, ChronoMind, EffoRise + - plan, routine, and habit remain product-local domain records wrapped in canonical artifact envelopes +- ActionTrail + - trail-report remains a derived record with strong provenance back to Cowork audit actions +- Cowork + - generated report or exported file should use `agent-output` plus attachment metadata when file-backed + +## 9. Key Open Decisions 1. Should artifact IDs be globally unique UUIDs or product-prefixed IDs? 2. Which fields belong in the envelope vs product payload? 3. Should `payload` be versioned per artifact type? 4. How should local-only artifacts from `learning_ai_local_memory_gpt` be represented without leaking sync assumptions? -5. How should binary/file artifacts be referenced: inline metadata vs blob indirection? +5. What is the minimum tombstone shape when a user deletes a previously linked artifact? --- -## 8. Acceptance Criteria +## 10. Acceptance Criteria 1. A LysnrAI transcript can be wrapped as an artifact without losing transcript-specific metadata. 2. A NoteLett note can link back to a transcript artifact. 3. A MindLyst memory can record provenance to source transcript/note artifacts. 4. A Cowork output can be stored as an `agent-output` artifact and later opened in NoteLett. 5. ActionTrail can render provenance from the envelope alone. +6. Products can classify artifacts by storage class without changing the envelope shape. +7. Binary artifacts can be referenced without embedding raw file contents in the envelope. --- -## 9. Implementation Checklist +## 11. Implementation Checklist - [x] finalize canonical envelope field names and required/optional splits - [x] define first 8 artifact types in stable form - [x] define link relation vocabulary - [x] define provenance minimum payload -- [ ] define storage/binary attachment rules -- [ ] define migration strategy for first adopters +- [x] define storage/binary attachment rules +- [x] define migration strategy for first adopters - [x] add examples for LysnrAI, NoteLett, and MindLyst - [x] add contract-backed examples for FlowMonk, ChronoMind, and EffoRise - [x] add examples for Cowork and ActionTrail @@ -203,3 +297,4 @@ Commits: - `76f1b47` added Phase 1 artifact schemas and canonical fixtures - `78918fb` added Phase 2 artifact schemas for `plan`, `routine`, and `habit` - `e6b58b7` added Phase 3 `trail-report` schema coverage and examples for Cowork/ActionTrail +- `ab50831` tracked artifact lifecycle hardening as remaining work