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

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

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:

- [x] `capture.transcript.created`
- [x] `artifact.created`
- [x] `artifact.linked`
- [x] `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`
- `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

---

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

- [x] finalize the canonical envelope for Phase 1
- [x] finalize the phase-1 event list for transcript -> note -> memory
- [ ] define versioning rules
- [x] 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`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/packages/events/src/ecosystem.ts)
- [`packages/events/fixtures/ecosystem/phase1`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/packages/events/fixtures/ecosystem/phase1)

Commits:

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