From 41fa2cd76746b7bb7bb48f9746b11a252627c3ed Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Fri, 3 Apr 2026 15:54:08 -0700 Subject: [PATCH] docs: add detailed ecosystem implementation docs --- .../ECOSYSTEM_CONTRACT_TEST_STRATEGY.md | 108 +++++++ docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md | 292 ++++++++++++++++++ .../ECOSYSTEM_IMPLEMENTATION_TRACKER.md | 24 +- docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md | 125 ++++++++ .../ECOSYSTEM_VERIFICATION_MATRIX.md | 105 +++++++ docs/ecosystem/README.md | 5 +- 6 files changed, 652 insertions(+), 7 deletions(-) create mode 100644 docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md create mode 100644 docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md create mode 100644 docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md create mode 100644 docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md diff --git a/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md b/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md new file mode 100644 index 00000000..15245a6d --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md @@ -0,0 +1,108 @@ +# Ecosystem Contract Test Strategy + +> **Status:** Draft +> **Owner:** `learning_ai_common_plat` +> **Purpose:** Define how shared artifact, runtime, approval, and event contracts are tested across repos without relying on manual interpretation. + +--- + +## 1. Problem + +Shared docs are not enough. + +If multiple repos implement the same contract differently, the ecosystem will drift even if each repo passes its own local tests. + +We need contract tests that verify: + +- producers emit the expected shape +- consumers accept the expected shape +- changes to shared contracts are intentional and visible + +--- + +## 2. Strategy + +Use a three-part model: + +1. **canonical fixtures** + - shared JSON examples owned in `learning_ai_common_plat` +2. **producer conformance tests** + - repo-specific tests that emit contract-shaped outputs +3. **consumer compatibility tests** + - repo-specific tests that ingest canonical fixtures + +--- + +## 3. Initial Contract Test Targets + +### Artifact contract + +- transcript artifact fixture +- note artifact fixture +- memory artifact fixture +- agent-output artifact fixture + +### Runtime contract + +- session fixture +- task fixture +- todo fixture +- dispatch fixture +- approval checkpoint fixture + +### Approval contract + +- approval request fixture +- approval decision fixture +- degraded-device policy case + +### Event contract + +- transcript created event +- artifact linked event +- plan generated event +- agent run completed event + +--- + +## 4. Recommended Location + +Canonical fixtures should eventually live in: + +- `learning_ai_common_plat/docs/ecosystem/fixtures/` for human-readable examples +- `learning_ai_common_plat/packages/...` or `services/...` for executable validation once implementation begins + +--- + +## 5. Required Repo Behavior + +Every consuming or producing repo should: + +1. import or mirror the canonical fixture set +2. validate against the canonical shape +3. fail clearly when contract drift occurs +4. reference the shared contract doc version in tests or fixtures + +--- + +## 6. Phase-1 Contract Test Scope + +- [ ] artifact schema fixture validation +- [ ] event envelope fixture validation +- [ ] runtime session and task fixture validation +- [ ] approval record fixture validation +- [ ] one producer and one consumer test for each of the two golden flows + +--- + +## 7. Implementation Checklist + +- [ ] choose canonical fixture storage location +- [ ] define JSON fixture naming convention +- [ ] define validation approach per contract +- [ ] define how repos import or copy fixtures +- [ ] define CI/manual verification expectations + +Commits: + +- initial draft: pending diff --git a/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md b/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md new file mode 100644 index 00000000..9c58f33d --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md @@ -0,0 +1,292 @@ +# Ecosystem Event Taxonomy + +> **Status:** Draft +> **Owner:** `learning_ai_common_plat` +> **Purpose:** Define the canonical event vocabulary for cross-product activity, agent execution, approvals, artifacts, and downstream replay. + +--- + +## 1. Why This Exists + +The ecosystem cannot implement reliable cross-product automation, timelines, approvals, or ActionTrail replay without a shared event language. + +Right now, each product can describe similar actions differently: + +- LysnrAI may say "transcript created" +- NoteLett may say "note saved" +- Cowork may say "run completed" +- FlowMonk may say "plan executed" +- ActionTrail may say "action approved" + +That fragmentation breaks: + +- personal timeline aggregation +- cross-repo analytics +- approval policy evaluation +- replay/audit continuity +- artifact provenance + +This document defines the common event naming and payload rules. + +--- + +## 2. Design Principles + +1. Events must describe facts, not UI wording. +2. Event names must be stable and implementation-neutral. +3. Event envelopes must be consistent across products. +4. Product-specific data belongs in typed payload sections, not in ad hoc top-level fields. +5. Event consumers should be able to reason about provenance and replay from the envelope alone. + +--- + +## 3. Canonical Event Envelope + +Every ecosystem event should include: + +```ts +type EcosystemEvent = { + eventId: string; + eventName: string; + eventVersion: number; + occurredAt: string; + productId: string; + sourceSurface: string; + userId?: string | null; + orgId?: string | null; + sessionId?: string | null; + runId?: string | null; + artifactId?: string | null; + actor: { + actorType: 'user' | 'agent' | 'system' | 'device'; + actorId?: string | null; + }; + trace: { + correlationId?: string | null; + causationId?: string | null; + parentEventId?: string | null; + }; + payload: Record; +}; +``` + +Required rules: + +- `eventName` is dot-separated, lowercase, verb-last only when needed +- `eventVersion` starts at `1` +- `payload` is event-specific +- `trace` exists even if values are null + +--- + +## 4. Event Naming Convention + +Pattern: + +`..` + +Examples: + +- `capture.transcript.created` +- `artifact.note.updated` +- `agent.run.started` +- `agent.run.completed` +- `approval.action.approved` +- `trust.device.degraded` +- `plan.routine.generated` + +Rules: + +1. Use nouns for domains and entities. +2. Use past-tense-like state facts only when the event is the completed fact. +3. Avoid UI terms like `button_clicked`. +4. Avoid product names in event names. Product identity belongs in `productId`. + +--- + +## 5. Domain Groups + +### 5.1 Capture events + +- `capture.transcript.created` +- `capture.voice_note.created` +- `capture.browser_clip.created` +- `capture.document.ingested` +- `capture.image.ingested` + +### 5.2 Artifact events + +- `artifact.created` +- `artifact.updated` +- `artifact.deleted` +- `artifact.linked` +- `artifact.visibility_changed` +- `artifact.promoted` + +### 5.3 Memory and note events + +- `memory.entry.created` +- `memory.entry.refined` +- `memory.entry.accepted` +- `note.block.created` +- `note.block.updated` +- `note.block.linked` + +### 5.4 Planning and routine events + +- `plan.created` +- `plan.updated` +- `plan.task.generated` +- `plan.routine.generated` +- `plan.habit.generated` +- `routine.started` +- `routine.completed` + +### 5.5 Agent runtime events + +- `agent.session.created` +- `agent.session.resumed` +- `agent.task.created` +- `agent.todo.updated` +- `agent.run.started` +- `agent.run.paused` +- `agent.run.completed` +- `agent.run.failed` +- `agent.dispatch.received` +- `agent.dispatch.accepted` + +### 5.6 Approval and trust events + +- `approval.action.requested` +- `approval.action.approved` +- `approval.action.denied` +- `approval.action.expired` +- `trust.identity.level_changed` +- `trust.device.level_changed` +- `trust.device.degraded` +- `trust.device.blocked` + +### 5.7 Audit and safety events + +- `audit.action.logged` +- `safety.injection.detected` +- `safety.unattended_action.blocked` +- `safety.policy.violation_detected` + +### 5.8 Billing and entitlement events + +- `usage.metered` +- `usage.limit_reached` +- `entitlement.granted` +- `entitlement.revoked` + +--- + +## 6. High-Priority Events For Phase 1 + +These should be implemented first because they unlock the initial cross-product flows: + +- [ ] `capture.transcript.created` +- [ ] `artifact.created` +- [ ] `artifact.linked` +- [ ] `memory.entry.created` +- [ ] `plan.created` +- [ ] `plan.routine.generated` +- [ ] `plan.habit.generated` +- [ ] `agent.run.started` +- [ ] `agent.run.completed` +- [ ] `approval.action.requested` +- [ ] `approval.action.approved` +- [ ] `trust.device.level_changed` + +Commits: + +- pending + +--- + +## 7. Required Producer Responsibilities + +Every producing repo must: + +1. emit canonical event names +2. include the standard envelope fields +3. include correlation/causation metadata when available +4. preserve product-specific detail in `payload` +5. avoid leaking secrets or raw sensitive material in event payloads + +--- + +## 8. Required Consumer Responsibilities + +Consumers such as ActionTrail, timeline services, approval engines, and analytics systems must: + +1. accept unknown future event names gracefully +2. branch by `eventName` and `eventVersion` +3. preserve raw envelopes for replay and diagnostics +4. avoid assuming one product source + +--- + +## 9. Example Event + +```json +{ + "eventId": "evt_01", + "eventName": "capture.transcript.created", + "eventVersion": 1, + "occurredAt": "2026-04-03T22:15:00.000Z", + "productId": "lysnrai", + "sourceSurface": "desktop", + "userId": "user_123", + "artifactId": "art_456", + "actor": { + "actorType": "user", + "actorId": "user_123" + }, + "trace": { + "correlationId": "corr_abc", + "causationId": null, + "parentEventId": null + }, + "payload": { + "durationMs": 42150, + "language": "en", + "transcriptSource": "microphone" + } +} +``` + +--- + +## 10. Open Decisions + +1. Should event storage be append-only everywhere or normalized into a shared event store? +2. Which events should also create artifacts automatically? +3. Which runtime events should be considered user-visible versus audit-only? +4. What is the retention policy for high-volume low-risk events? +5. Should local-only products emit a reduced event set when offline? + +--- + +## 11. Acceptance Criteria + +1. The initial transcript -> note -> memory flow can be represented using canonical events. +2. The initial plan -> routine -> habit flow can be represented using canonical events. +3. Cowork execution and ActionTrail replay can share event names without repo-specific translation hacks. +4. Approval policy evaluation can key off shared event names instead of product-local ones. + +--- + +## 12. Implementation Checklist + +- [ ] finalize the canonical envelope +- [ ] finalize the phase-1 event list +- [ ] define versioning rules +- [ ] define payload examples for first adopters +- [ ] define storage and retention expectations +- [ ] define producer and consumer validation rules + +Commits: + +- initial draft: pending diff --git a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md index 3f230dc0..16a4f18a 100644 --- a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md +++ b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md @@ -45,7 +45,10 @@ Example: | `ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md` | in-progress | `learning_ai_common_plat` | draft stub exists, schema decisions still open | `eae3409` | | `ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md` | in-progress | `learning_ai_common_plat` | draft stub exists, runtime normalization still open | `eae3409` | | `ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md` | in-progress | `learning_ai_common_plat` | draft stub exists, policy matrix still needs hardening | `eae3409` | -| `ECOSYSTEM_EVENT_TAXONOMY.md` | not-started | `learning_ai_common_plat` | next required spec | — | +| `ECOSYSTEM_EVENT_TAXONOMY.md` | in-progress | `learning_ai_common_plat` | draft exists, phase-1 event set still needs refinement | pending current commit | +| `ECOSYSTEM_OWNERSHIP_MATRIX.md` | in-progress | `learning_ai_common_plat` | temporary four-party ownership model added | pending current commit | +| `ECOSYSTEM_VERIFICATION_MATRIX.md` | in-progress | `learning_ai_common_plat` | draft verification model added | pending current commit | +| `ECOSYSTEM_CONTRACT_TEST_STRATEGY.md` | in-progress | `learning_ai_common_plat` | draft contract-test model added | pending current commit | | `ECOSYSTEM_MARKETPLACE_UNIFICATION.md` | not-started | `learning_ai_common_plat` | depends on artifact/runtime conventions | — | | `ECOSYSTEM_PERSONAL_TIMELINE_PRD.md` | not-started | `learning_ai_common_plat` | depends on artifacts + events | — | @@ -74,7 +77,16 @@ Example: - `eae3409` - [ ] Draft event taxonomy Commits: - - pending + - pending current commit +- [x] Draft temporary ownership matrix + Commits: + - pending current commit +- [x] Draft verification matrix + Commits: + - pending current commit +- [x] Draft contract-test strategy + Commits: + - pending current commit ### First implementation tracks @@ -108,10 +120,10 @@ Example: ## 4. Current Gaps Before Broad Implementation -- [ ] event taxonomy spec is missing +- [ ] event taxonomy needs phase-1 event list hardening - [ ] no shared adoption docs exist yet under `docs/ecosystem/adoption/` -- [ ] no repo ownership matrix exists yet -- [ ] no verification matrix exists yet -- [ ] no contract-test strategy is documented yet +- [ ] ownership model is temporary and must be revised if the team changes +- [ ] verification matrix needs repo-level test ownership +- [ ] contract-test strategy needs fixture location and validation tooling decisions These should be resolved before claiming the ecosystem docs are fully implementation-ready. diff --git a/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md b/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md new file mode 100644 index 00000000..87535843 --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md @@ -0,0 +1,125 @@ +# Ecosystem Ownership Matrix + +> **Status:** Draft +> **Owner Model:** temporary four-party operating model +> **Parties:** User, Codex, Windsurf, Cursor +> **Purpose:** Clarify who owns what for ecosystem planning, implementation, review, and tracking. + +--- + +## 1. Current Operating Reality + +For now, the ecosystem is effectively operated by four parties: + +1. **You** + Product owner, final technical decider, integration sponsor, and release authority. +2. **Codex** + High-power architecture and implementation driver for complex cross-repo work. +3. **Windsurf** + Medium-power execution partner for bounded implementation, iterative follow-through, and repo-local work. +4. **Cursor** + Lower-power execution and assistance layer for narrower or more guided tasks. + +This document assumes no larger team structure exists yet. + +--- + +## 2. Role Definitions + +### You + +Own: + +- final priorities +- architectural direction approval +- repo strategy decisions +- acceptance of cross-product behavior changes +- release/push/go-live calls + +### Codex + +Own: + +- ecosystem architecture +- shared-contract definition +- cross-repo sequencing +- difficult implementation plans +- higher-risk refactors and integration strategy +- documentation system-of-record quality + +### Windsurf + +Own: + +- bounded implementation chunks +- repo-local follow-through +- structured doc updates +- medium-complexity verification and completion loops + +### Cursor + +Own: + +- smaller scoped implementation assistance +- local productivity tasks +- narrow edits under strong guidance +- low-risk follow-up changes + +--- + +## 3. Responsibility Matrix + +| Work Type | You | Codex | Windsurf | Cursor | +| ---------------------------------- | --- | ----- | -------- | ------ | +| ecosystem strategy | A | R | C | C | +| shared contracts | A | R | C | C | +| cross-repo implementation planning | A | R | C | C | +| high-complexity integration work | A | R | C | I | +| medium repo-local implementation | C | C | R | I | +| low-risk guided edits | C | C | C | R | +| tracker and commit-link hygiene | A | R | C | C | +| final push/go-live decision | A | C | I | I | + +Legend: + +- `A` = accountable +- `R` = responsible +- `C` = consulted +- `I` = informed + +--- + +## 4. Repo Ownership Bias + +This is not exclusive ownership. It is the default lead bias. + +| Repo Area | Default Lead | +| ----------------------------------------- | --------------------------------- | +| `learning_ai_common_plat/docs/ecosystem/` | Codex | +| shared contract docs | Codex | +| implementation tracker updates | Codex | +| product-local adoption docs | Windsurf or Cursor under guidance | +| final prioritization and acceptance | You | + +--- + +## 5. Practical Rules + +1. If a change affects more than one repo or defines a shared contract, Codex should lead. +2. If a change is bounded to one repo and the contract is already clear, Windsurf can lead. +3. Cursor should be used only for narrower, strongly-scoped work until the ecosystem contracts harden further. +4. You remain the final authority on tradeoffs and sequencing. +5. Every major ecosystem task should be visible in the tracker with one clear owner. + +--- + +## 6. Implementation Checklist + +- [ ] confirm this temporary four-party ownership model +- [ ] add repo adoption owners as work expands +- [ ] add handoff conventions between Codex, Windsurf, and Cursor +- [ ] revise this doc if the team structure changes + +Commits: + +- initial draft: pending diff --git a/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md b/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md new file mode 100644 index 00000000..2ffd6eca --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md @@ -0,0 +1,105 @@ +# Ecosystem Verification Matrix + +> **Status:** Draft +> **Owner:** `learning_ai_common_plat` +> **Purpose:** Define how ecosystem work is verified before it is considered complete. + +--- + +## 1. Principle + +A cross-product feature is not done when one repo compiles. + +It is done when: + +1. the shared contract is updated +2. the producing repo emits the expected behavior +3. the consuming repo handles it correctly +4. the tracker reflects the implementing commit(s) + +--- + +## 2. Verification Layers + +### Layer 1: Doc verification + +- contract doc updated +- checklist updated +- tracker updated +- open decisions called out if unresolved + +### Layer 2: Contract verification + +- schema/type examples compile or validate +- sample payloads are present +- event names and field names are stable + +### Layer 3: Producer verification + +- source repo emits or stores the expected contract shape +- unit/integration tests added where appropriate + +### Layer 4: Consumer verification + +- downstream repo accepts and uses the contract correctly +- no translation hacks or undocumented fallback behavior + +### Layer 5: End-to-end flow verification + +- the actual user journey works across repo boundaries + +--- + +## 3. Phase-1 Golden Flow Checks + +### Transcript -> Note -> Memory + +- [ ] transcript artifact created +- [ ] note artifact created or linked +- [ ] memory artifact created or proposed +- [ ] canonical events emitted +- [ ] provenance preserved across all steps +- [ ] tracker updated with commit links + +### Plan -> Routine -> Habit + +- [ ] plan artifact exists +- [ ] routine generated from plan +- [ ] habit generated from plan +- [ ] canonical events emitted +- [ ] user-visible flow validated +- [ ] tracker updated with commit links + +### Cowork -> Trail -> Notes -> Memory + +- [ ] agent run logged +- [ ] output artifact generated +- [ ] ActionTrail can replay or inspect the run +- [ ] downstream note or memory artifacts linked +- [ ] approval trail preserved where required +- [ ] tracker updated with commit links + +--- + +## 4. Required Completion Evidence + +For every major implementation item, attach: + +1. commit hash(es) +2. affected repos +3. verification commands or tests +4. residual risks +5. tracker update + +--- + +## 5. Implementation Checklist + +- [ ] finalize phase-1 golden flow checks +- [ ] define repo-level verification owners +- [ ] define minimum evidence for “done” +- [ ] add links from tracker rows to verification evidence + +Commits: + +- initial draft: pending diff --git a/docs/ecosystem/README.md b/docs/ecosystem/README.md index 98dae477..03c077dd 100644 --- a/docs/ecosystem/README.md +++ b/docs/ecosystem/README.md @@ -16,9 +16,12 @@ Recommended structure: - [`ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md) — strategy, opportunities, gaps, priorities - [`ECOSYSTEM_IMPLEMENTATION_TRACKER.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md) — canonical execution tracker with checkboxes and commit references - [`ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md) — canonical artifact model -- `ECOSYSTEM_EVENT_TAXONOMY.md` — shared events and action-log contract +- [`ECOSYSTEM_EVENT_TAXONOMY.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md) — shared events and action-log contract - [`ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md) — shared session, todo, resume, dispatch semantics - [`ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md) — approvals, trust levels, device posture +- [`ECOSYSTEM_OWNERSHIP_MATRIX.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md) — temporary four-party ownership model +- [`ECOSYSTEM_VERIFICATION_MATRIX.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md) — what “done” means for cross-product features +- [`ECOSYSTEM_CONTRACT_TEST_STRATEGY.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md) — how to prevent contract drift across repos - `ECOSYSTEM_MARKETPLACE_UNIFICATION.md` — shared marketplace model - `ECOSYSTEM_PERSONAL_TIMELINE_PRD.md` — unified user activity stream - [`adoption/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/adoption) — per-product adoption notes