learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md

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

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

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

Current implementation location:

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

Commits:

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