docs(ecosystem): harden artifact lifecycle and event taxonomy

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
 
 ---
 

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
+- [x] define storage/binary attachment rules
-- [ ] define migration strategy for first adopters
+- [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