bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add detailed ecosystem implementation docs

Browse Source
This commit is contained in:
Saravana Achu Mac 2026-04-03 15:54:08 -07:00
parent 577c3fa243
commit 41fa2cd767
6 changed files with 652 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md Normal file
View File

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

292
docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md Normal file
View File

@ -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<string, unknown>;
};
```
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:
`<domain>.<entity>.<action>`
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

24
docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md
View File

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

125
docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md Normal file
View File

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

105
docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md Normal file
View File

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

5
docs/ecosystem/README.md
View File

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