learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md

Ecosystem Event Taxonomy

Status: Phase 1 baseline implemented 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:

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

Current implementation note:

• Phase 2 reuses canonical artifact.created and artifact.linked with artifactType values plan, routine, and habit.
• Product-specific planning event names remain reserved for later when the ecosystem needs finer-grained plan lifecycle telemetry beyond the artifact seam.

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:

• 41fa2cd drafted the event taxonomy
• 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

---

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

{
  "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 for Phase 1
• finalize the phase-1 event list for transcript -> note -> memory
• define versioning rules
• define payload examples for first adopters
• define storage and retention expectations
• define producer and consumer validation rules

Current implementation location:

• packages/events/src/ecosystem.ts
• packages/events/fixtures/ecosystem/phase1

Commits:

• 41fa2cd drafted the initial version
• 76f1b47 added Phase 1 event schemas and fixtures