# Ecosystem Shared Artifact Schema

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

---

## 1. Problem

Multiple repos produce durable user-value objects:

- LysnrAI transcripts
- NoteLett notes
- MindLyst memory entries
- FlowMonk plans
- ChronoMind routines
- ActionTrail audit records
- PeakPulse sessions
- Cowork generated reports and file outputs

Today these are product-local objects. The ecosystem needs one canonical artifact shape so:

- artifacts can be linked, searched, and retrieved consistently
- provenance can be preserved
- agent outputs can become user-editable assets
- one user action can create downstream value across products

---

## 2. Goals

1. Define one envelope schema shared across all products.
2. Preserve product-specific payloads inside a canonical wrapper.
3. Support provenance, lineage, and visibility rules.
4. Support human-created, machine-created, and mixed artifacts.
5. Support cloud-first and local-first storage models.

## 3. Non-Goals

1. Replacing product-local domain schemas entirely.
2. Forcing one storage backend for all products.
3. Removing product-specific UX or metadata.

---

## 4. Proposed Canonical Shape

Every artifact should include:

- `id`
- `artifactType`
- `productId`
- `sourceSurface`
- `title`
- `summary`
- `createdAt`
- `updatedAt`
- `createdBy`
- `ownership`
- `visibility`
- `status`
- `tags`
- `links`
- `provenance`
- `payload`

Example types:

- `transcript`
- `note`
- `memory`
- `plan`
- `routine`
- `habit-checkin`
- `trail-report`
- `route-session`
- `agent-output`
- `document`
- `digest`

---

## 5. Minimum Envelope Fields

```ts
type ArtifactEnvelope = {
  id: string;
  artifactType: string;
  productId: string;
  sourceSurface: string;
  title: string | null;
  summary: string | null;
  createdAt: string;
  updatedAt: string;
  createdBy: {
    actorType: 'user' | 'agent' | 'system' | 'mixed';
    actorId: string | null;
  };
  ownership: {
    userId: string;
    orgId?: string | null;
  };
  visibility: {
    scope: 'private' | 'org' | 'shared' | 'local-only';
    allowedProducts?: string[];
  };
  status: string;
  tags: string[];
  links: ArtifactLink[];
  provenance: ArtifactProvenance;
  payload: Record<string, unknown>;
};

type ArtifactLink = {
  relation:
    | 'derived-from'
    | 'summarizes'
    | 'generated-task'
    | 'generated-routine'
    | 'generated-memory'
    | 'evidence-for'
    | 'review-of'
    | 'attached-to';
  targetArtifactId: string;
};

type ArtifactProvenance = {
  originProductId: string;
  originActionId?: string | null;
  sessionId?: string | null;
  runId?: string | null;
  approvalId?: string | null;
  lineage: Array<{
    stepType: string;
    productId: string;
    actorType: 'user' | 'agent' | 'system';
    timestamp: string;
  }>;
};
```

---

## 6. First Adopters

Phase 1 adopters:

1. `learning_voice_ai_agent`
2. `learning_ai_notes`
3. `learning_multimodal_memory_agents`
4. `learning_ai_flowmonk`
5. `learning_ai_trails`
6. `oss/learning_ai_claw-cowork`

---

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

---

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

---

## 9. Implementation Checklist

- [x] finalize canonical envelope field names and required/optional splits
- [x] define first 5 artifact types in stable form
- [x] define link relation vocabulary
- [x] define provenance minimum payload
- [ ] define storage/binary attachment rules
- [ ] define migration strategy for first adopters
- [x] add examples for LysnrAI, NoteLett, and MindLyst
- [ ] add examples for Cowork and ActionTrail

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:

- `eae3409` drafted the initial stub
- `76f1b47` added Phase 1 artifact schemas and canonical fixtures