@retrace-dev/core 0.1.0

package/dist/schema.js

@@ -0,0 +1,177 @@
+/**
+ * Retrace core schema — the six dimensions of provenance:
+ * WHO (actor) · WHAT (action + artifacts + change) · WHEN (timestamp/seq)
+ * WHERE (location) · WHY (intent + caused_by) · HOW (method)
+ * plus integrity (hash chain).
+ *
+ * Deliberately close to W3C PROV (Agent / Activity / Entity) so we can export later.
+ */
+import { z } from "zod";
+export const ActorType = z.enum(["human", "agent", "system"]);
+export const Actor = z.object({
+    type: ActorType,
+    /** Stable identifier: email, agent name, service id */
+    id: z.string().min(1),
+    display_name: z.string().optional(),
+    /** For agents: model + version that performed the action */
+    model: z.string().optional(),
+    version: z.string().optional(),
+    /** Delegation: an agent acting for a human, or a sub-agent for a parent agent */
+    on_behalf_of: z.string().optional(),
+});
+/** Small controlled verb vocabulary. `other` requires `action_detail`. */
+export const Action = z.enum([
+    "created",
+    "edited",
+    "deleted",
+    "read",
+    "executed",
+    "approved",
+    "rejected",
+    "sent",
+    "received",
+    "moved",
+    "renamed",
+    "instructed",
+    "committed",
+    "merged",
+    "other",
+]);
+/**
+ * PROV role of an artifact within an event: was it an input the activity `used`, an output it `generated`, or `both`
+ * (read then rewritten). Optional — absence means "unspecified" and is a legal, permanent state: events sealed before
+ * this field existed are never backfilled or re-hashed (absence is information).
+ *   Export mapping (for a future prov exporter): used → prov:used (Activity→Entity), generated → prov:wasGeneratedBy
+ *   (Entity→Activity), both → both edges, absent → degrades to prov:wasInfluencedBy.
+ *   Distinct from `derived_from`, which is Entity→Entity (prov:wasDerivedFrom) and unchanged. Invalidation (a deleted
+ *   artifact, prov:wasInvalidatedBy) is deliberately NOT a role — a deleted ref stays absent until that is a first-class edge.
+ */
+export const ArtifactRole = z.enum(["used", "generated", "both"]);
+export const ArtifactRef = z.object({
+    /** Stable id for the thing being worked on, e.g. "repo:slcwitit/rpg#src/fight.ts" or "doc:abc123" */
+    id: z.string().min(1),
+    kind: z.string().optional(), // file, doc, dataset, pr, message, decision, ...
+    label: z.string().optional(),
+    /** Lineage: this artifact was derived from these */
+    derived_from: z.array(z.string()).optional(),
+    /** PROV: input (used) / output (generated) / both. Body-only, hash-covered on new events; see ArtifactRole. */
+    role: ArtifactRole.optional(),
+});
+/**
+ * Default role of an artifact ref for an action verb, for when the caller says nothing. `undefined` = leave absent.
+ *   read → used · created/committed/merged → generated · edited/moved/renamed → both (the prior state is read, the new
+ *   one written) · executed/sent/received/approved/rejected → used (the thing run/sent/reviewed was an input; an OUTPUT
+ *   such as a deployment or report must be said by the caller) · deleted/instructed/other → absent.
+ * Adapters stamp what they authoritatively know and only fall back to this where the verb alone is the truth.
+ */
+export function defaultArtifactRole(action) {
+    switch (action) {
+        case "read": return "used";
+        case "created":
+        case "committed":
+        case "merged": return "generated";
+        case "edited":
+        case "moved":
+        case "renamed": return "both";
+        case "executed":
+        case "sent":
+        case "received":
+        case "approved":
+        case "rejected": return "used";
+        default: return undefined; // deleted, instructed, other
+    }
+}
+/** Fill `role` from defaultArtifactRole ONLY where a ref has none — a caller-supplied role is never overwritten. Refs
+ *  that get no default come back as they were (no `role` key, so hashes of role-less inputs are unaffected). */
+export function applyDefaultRoles(action, artifacts) {
+    const def = defaultArtifactRole(action);
+    return artifacts.map((a) => (a.role !== undefined || def === undefined ? a : { ...a, role: def }));
+}
+export const Change = z.object({
+    before_hash: z.string().optional(),
+    after_hash: z.string().optional(),
+    diff: z.string().optional(),
+    summary: z.string().optional(),
+});
+export const Location = z.object({
+    /** repo path, doc section, URL, table, etc. */
+    path: z.string().optional(),
+    url: z.string().optional(),
+    environment: z.string().optional(), // prod, staging, local, ...
+    device: z.string().optional(),
+    system: z.string().optional(), // github, gdocs, cursor, claude-code, ...
+    /** Run/session id of the producing process (backlog #15; body-only, like every location field). On the MCP path
+     *  this is the harness's own session id when it exposes one (CLAUDE_CODE_SESSION_ID or GROK_SESSION_ID), so the same string appears on
+     *  events from the agent AND on the commits it drives. It is a *session* key — subagents share it — not a per-run id. */
+    session: z.string().optional(),
+    /** The MCP client that drove the write, verbatim from the `initialize` handshake as "<name>@<version>" — e.g.
+     *  "claude-code@2.1.250", "cursor-vscode@1.7.3". Server-stamped only: it is evidence ABOUT the writer, so the
+     *  writer may not assert it (see SERVER_ONLY in the MCP server). */
+    client: z.string().optional(),
+    /** IDE / agent-development environment hosting the actor, e.g. "orca". Deliberately distinct from `system` (the tool
+     *  that produced the event, "claude-code") and from `client` (which build of it): the IDE is the app AROUND both, and
+     *  neither of the other two can express it. Only stamped when the IDE identifies itself in the environment. */
+    ide: z.string().optional(),
+    /** Isolated workspace within `ide` — an Orca worktree id, a codespace or devcontainer name. This is what tells two
+     *  parallel agents apart when they run the same project, on the same host, as the same actor. */
+    workspace: z.string().optional(),
+    /** Whether the producing process had a controlling terminal: "tty" = a human at a keyboard, "agent" = spawned by a
+     *  harness with none. Linux-only today (read from /proc/self/stat); absent everywhere else, and absence is a legal
+     *  permanent state. EVIDENCE, never authority — it must not override the actor determination. */
+    surface: z.enum(["tty", "agent"]).optional(),
+});
+export const Method = z.object({
+    tool: z.string().optional(), // e.g. "Edit", "git commit", "gdocs-ui"
+    /** Reference to instruction/prompt that drove this (id, hash, or short text) */
+    instruction: z.string().optional(),
+    params: z.record(z.unknown()).optional(),
+    automated: z.boolean().optional(),
+    tokens: z.number().int().nonnegative().optional(),
+    cost_usd: z.number().nonnegative().optional(),
+});
+/** What a client submits. Server fills in id/seq/hash/prev_hash. */
+export const EventInput = z.object({
+    project: z.string().min(1),
+    actor: Actor,
+    action: Action,
+    action_detail: z.string().optional(),
+    artifacts: z.array(ArtifactRef).min(1),
+    change: Change.optional(),
+    timestamp: z.string().datetime({ offset: true }).optional(),
+    duration_ms: z.number().int().nonnegative().optional(),
+    location: Location.optional(),
+    /** WHY — free text reason */
+    intent: z.string().optional(),
+    /** WHY — causal parent (event id). The instruction that led to this action. */
+    caused_by: z.string().optional(),
+    method: Method.optional(),
+    /** Client-provided idempotency key */
+    idempotency_key: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+});
+export const Event = EventInput.extend({
+    id: z.string().min(1),
+    seq: z.number().int().nonnegative(),
+    timestamp: z.string().datetime({ offset: true }),
+    prev_hash: z.string(),
+    hash: z.string(),
+    received_at: z.string().datetime({ offset: true }),
+});
+/**
+ * The schema surface a build understands, derived from the zod shapes themselves so it can never drift from the code.
+ *
+ * This exists because the failure it detects is SILENT: `POST /events` re-parses with `EventInput.safeParse`, and zod
+ * strips keys it does not know, so a producer running newer code than the deployment loses those fields with no error
+ * anywhere — the event is accepted, sealed and hashed without them. It has happened twice (`location.session`,
+ * `bacabed`; `location.client`/`ide`/`workspace`/`surface`, 2026-08-28), both times found by eye.
+ * `GET /api` publishes this, and `npm run check-deploy` diffs a deployment against the local build.
+ */
+export function schemaSurface() {
+    return {
+        event: Object.keys(EventInput.shape).sort(),
+        location: Object.keys(Location.shape).sort(),
+        artifact: Object.keys(ArtifactRef.shape).sort(),
+        actions: [...Action.options].sort(),
+    };
+}
+export const GENESIS_HASH = "0".repeat(64);

package/dist/signing.d.ts

@@ -0,0 +1,13 @@
+export interface KeyPairJwk {
+    privateKey: JsonWebKey;
+    publicKey: JsonWebKey;
+    kid: string;
+}
+export declare function generateSigningKey(): Promise<KeyPairJwk>;
+/** kid = first 16 hex of sha256(canonical public jwk {crv,kty,x}) */
+export declare function keyId(pub: JsonWebKey): Promise<string>;
+export declare function publicFromPrivate(priv: JsonWebKey): JsonWebKey;
+export declare function signCanonical(priv: JsonWebKey, value: unknown): Promise<string>;
+export declare function verifyCanonical(pub: JsonWebKey, value: unknown, signature: string): Promise<boolean>;
+/** Parse RETRACE_SIGNING_KEY (JSON JWK, or base64 of it). Returns null when unset. */
+export declare function parseSigningKey(raw?: string | null): JsonWebKey | null;

package/dist/signing.js

@@ -0,0 +1,55 @@
+/**
+ * Ed25519 signing via WebCrypto (Node 22+, Cloudflare Workers, modern browsers).
+ * Keys are JWKs. Private key is passed as JSON in RETRACE_SIGNING_KEY; the public JWK is published at /.well-known/retrace-pubkey.
+ */
+import { canonicalize, sha256Hex } from "./chain.js";
+const subtle = globalThis.crypto.subtle;
+const ALG = { name: "Ed25519" };
+export async function generateSigningKey() {
+    const kp = (await subtle.generateKey(ALG, true, ["sign", "verify"]));
+    const privateKey = await subtle.exportKey("jwk", kp.privateKey);
+    const publicKey = await subtle.exportKey("jwk", kp.publicKey);
+    const kid = await keyId(publicKey);
+    return { privateKey: { ...privateKey, kid }, publicKey: { ...publicKey, kid }, kid };
+}
+/** kid = first 16 hex of sha256(canonical public jwk {crv,kty,x}) */
+export async function keyId(pub) {
+    return (await sha256Hex(canonicalize({ crv: pub.crv, kty: pub.kty, x: pub.x }))).slice(0, 16);
+}
+export function publicFromPrivate(priv) {
+    const { d: _d, key_ops: _k, ...pub } = priv;
+    return { ...pub, key_ops: ["verify"] };
+}
+const b64u = {
+    enc: (buf) => btoa(String.fromCharCode(...new Uint8Array(buf))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""),
+    dec: (s) => Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(s.length / 4) * 4, "=")), (c) => c.charCodeAt(0)),
+};
+export async function signCanonical(priv, value) {
+    const key = await subtle.importKey("jwk", priv, ALG, false, ["sign"]);
+    const sig = await subtle.sign(ALG, key, new TextEncoder().encode(canonicalize(value)));
+    return b64u.enc(sig);
+}
+export async function verifyCanonical(pub, value, signature) {
+    try {
+        const key = await subtle.importKey("jwk", { ...pub, key_ops: ["verify"] }, ALG, false, ["verify"]);
+        return await subtle.verify(ALG, key, b64u.dec(signature), new TextEncoder().encode(canonicalize(value)));
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse RETRACE_SIGNING_KEY (JSON JWK, or base64 of it). Returns null when unset. */
+export function parseSigningKey(raw) {
+    if (!raw)
+        return null;
+    const s = raw.trim();
+    try {
+        return JSON.parse(s);
+    }
+    catch { }
+    try {
+        return JSON.parse(atob(s));
+    }
+    catch { }
+    throw new Error("RETRACE_SIGNING_KEY is not a JWK (JSON or base64 JSON)");
+}

package/dist/status.d.ts

@@ -0,0 +1,49 @@
+import { Event } from "./schema.js";
+import { VerifyResult } from "./chain.js";
+import { EventStore } from "./store.js";
+export type StatusActor = {
+    type: Event["actor"]["type"];
+    id: string;
+    events: number;
+    last_seen: string;
+    models: string[];
+};
+export type StatusIntegration = {
+    system: string;
+    events: number;
+    last_seen: string;
+};
+export type ProjectStatus = {
+    project: string;
+    generated_at: string;
+    integrity: VerifyResult;
+    events: {
+        total: number;
+        last_event_at?: string;
+    };
+    capture: {
+        artifact_refs: number;
+        artifact_refs_without_role: number;
+        agent_events: number;
+        agent_events_without_model: number;
+        instructions: number;
+        instructions_without_followup: number;
+        commits: number;
+        unlinked_commits: number;
+    };
+    causality: {
+        eligible_events: number;
+        rooted_in_human_instruction: number;
+        broken_links: number;
+        unlinked: number;
+        coverage_pct: number;
+    };
+    actors: StatusActor[];
+    integrations: StatusIntegration[];
+};
+type RootState = "rooted" | "broken" | "unlinked";
+/** Does this event's caused_by chain terminate at a human instruction root? */
+export declare function causalRootState(event: Event, byId: Map<string, Event>): RootState;
+export declare function buildProjectStatus(store: EventStore, project: string, now?: Date): Promise<ProjectStatus>;
+export declare function renderProjectStatus(s: ProjectStatus): string;
+export {};

package/dist/status.js

@@ -0,0 +1,85 @@
+import { verifyProject } from "./store.js";
+/** Does this event's caused_by chain terminate at a human instruction root? */
+export function causalRootState(event, byId) {
+    const seen = new Set();
+    let cur = event;
+    while (cur) {
+        if (seen.has(cur.id))
+            return "broken";
+        seen.add(cur.id);
+        if (cur.actor.type === "human" && cur.action === "instructed")
+            return "rooted";
+        if (!cur.caused_by)
+            return "unlinked";
+        cur = byId.get(cur.caused_by);
+        if (!cur)
+            return "broken";
+    }
+    return "broken";
+}
+export async function buildProjectStatus(store, project, now = new Date()) {
+    const events = await store.all(project);
+    const integrity = await verifyProject(store, project);
+    const byId = new Map(events.map((e) => [e.id, e]));
+    const caused = new Set(events.map((e) => e.caused_by).filter((x) => !!x));
+    const eligible = events.filter((e) => e.actor.type === "agent" || e.action === "committed" || e.action === "merged");
+    const roots = eligible.map((e) => causalRootState(e, byId));
+    const count = (s) => roots.filter((x) => x === s).length;
+    const actors = new Map();
+    const integrations = new Map();
+    for (const e of events) {
+        const ak = `${e.actor.type}:${e.actor.id}`;
+        const actor = actors.get(ak) ?? { type: e.actor.type, id: e.actor.id, events: 0, last_seen: e.timestamp, models: [] };
+        actor.events++;
+        if (e.timestamp > actor.last_seen)
+            actor.last_seen = e.timestamp;
+        if (e.actor.model && !actor.models.includes(e.actor.model))
+            actor.models.push(e.actor.model);
+        actors.set(ak, actor);
+        const system = e.location?.system;
+        if (system) {
+            const integration = integrations.get(system) ?? { system, events: 0, last_seen: e.timestamp };
+            integration.events++;
+            if (e.timestamp > integration.last_seen)
+                integration.last_seen = e.timestamp;
+            integrations.set(system, integration);
+        }
+    }
+    const artifactRefs = events.flatMap((e) => e.artifacts);
+    const instructions = events.filter((e) => e.actor.type === "human" && e.action === "instructed");
+    const commits = events.filter((e) => e.action === "committed" || e.action === "merged");
+    const rooted = count("rooted");
+    return {
+        project,
+        generated_at: now.toISOString(),
+        integrity,
+        events: { total: events.length, last_event_at: events.at(-1)?.timestamp },
+        capture: {
+            artifact_refs: artifactRefs.length,
+            artifact_refs_without_role: artifactRefs.filter((a) => a.role === undefined).length,
+            agent_events: events.filter((e) => e.actor.type === "agent").length,
+            agent_events_without_model: events.filter((e) => e.actor.type === "agent" && !e.actor.model).length,
+            instructions: instructions.length,
+            instructions_without_followup: instructions.filter((e) => !caused.has(e.id)).length,
+            commits: commits.length,
+            unlinked_commits: commits.filter((e) => causalRootState(e, byId) !== "rooted").length,
+        },
+        causality: {
+            eligible_events: eligible.length,
+            rooted_in_human_instruction: rooted,
+            broken_links: count("broken"),
+            unlinked: count("unlinked"),
+            coverage_pct: eligible.length ? Math.round(rooted * 1000 / eligible.length) / 10 : 100,
+        },
+        actors: [...actors.values()].map((a) => ({ ...a, models: a.models.sort() })).sort((a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id)),
+        integrations: [...integrations.values()].sort((a, b) => a.system.localeCompare(b.system)),
+    };
+}
+export function renderProjectStatus(s) {
+    const health = s.integrity.ok ? "VERIFIED" : "BROKEN";
+    return `${s.project} — ${health}\n` +
+        `${s.events.total} events · ${s.causality.coverage_pct}% causal coverage · ${s.capture.unlinked_commits}/${s.capture.commits} unlinked commits\n` +
+        `${s.capture.agent_events_without_model}/${s.capture.agent_events} agent events missing model · ${s.capture.instructions_without_followup}/${s.capture.instructions} instructions without follow-up · ${s.capture.artifact_refs_without_role}/${s.capture.artifact_refs} artifact refs missing role\n` +
+        `actors: ${s.actors.map((a) => `${a.type}/${a.id} (${a.events})`).join(", ") || "none"}\n` +
+        `integrations: ${s.integrations.map((i) => `${i.system} (${i.events}, last ${i.last_seen})`).join(", ") || "none"}`;
+}

package/dist/store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Storage interface — implemented by SQLite (MCP server) and D1 (Worker).
+ * SQL schema shared by both lives in SCHEMA_SQL.
+ */
+import { Event, EventInput } from "./schema.js";
+import { VerifyResult } from "./chain.js";
+export interface HistoryQuery {
+    project: string;
+    artifact_id?: string;
+    actor_id?: string;
+    actor_type?: string;
+    action?: string;
+    since?: string;
+    until?: string;
+    text?: string;
+    limit?: number;
+}
+export interface Share {
+    id: string;
+    project: string;
+    artifact_id?: string;
+    label?: string;
+    created_at: string;
+    expires_at?: string;
+    created_by?: string;
+}
+export interface EventStore {
+    head(project: string): Promise<ChainHead | null>;
+    createShare(share: Share): Promise<void>;
+    getShare(id: string): Promise<Share | null>;
+    insert(e: Event): Promise<void>;
+    byIdempotencyKey(project: string, key: string): Promise<Event | null>;
+    get(id: string): Promise<Event | null>;
+    history(q: HistoryQuery): Promise<Event[]>;
+    all(project: string): Promise<Event[]>;
+    projects(): Promise<string[]>;
+    /** Delete every row belonging to a project AND insert `audit` (already sealed onto its own project's chain) in the
+     *  same transaction, so a deletion can never exist without its audit record and vice versa (security review
+     *  2026-08-21, B3). `expectedHead` is the target project's head the caller sealed the audit's `change` fields from:
+     *  the store must check INSIDE the transaction that the head is still exactly that and throw `HeadMovedError`
+     *  (committing nothing) if a write raced the delete, so the immortal audit record can never describe a head or
+     *  event count other than the one actually deleted. Returns per-table deleted counts. Optional — stores without it
+     *  don't serve DELETE /projects/:p. */
+    deleteProject?(project: string, audit: Event, expectedHead: ChainHead): Promise<Record<string, number>>;
+}
+export type ChainHead = {
+    seq: number;
+    hash: string;
+};
+/** Thrown by `deleteProject` when the target project's head no longer matches `expectedHead`: nothing was committed;
+ *  re-read the head, re-seal the audit and retry. */
+export declare class HeadMovedError extends Error {
+    constructor(project: string, expected: ChainHead);
+}
+export declare function isHeadMovedError(e: unknown): e is HeadMovedError;
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS events (\n  id TEXT PRIMARY KEY,\n  project TEXT NOT NULL,\n  seq INTEGER NOT NULL,\n  timestamp TEXT NOT NULL,\n  received_at TEXT NOT NULL,\n  actor_type TEXT NOT NULL,\n  actor_id TEXT NOT NULL,\n  action TEXT NOT NULL,\n  caused_by TEXT,\n  idempotency_key TEXT,\n  prev_hash TEXT NOT NULL,\n  hash TEXT NOT NULL,\n  body TEXT NOT NULL,\n  UNIQUE(project, seq)\n);\nCREATE INDEX IF NOT EXISTS idx_events_project_ts ON events(project, timestamp);\nCREATE INDEX IF NOT EXISTS idx_events_actor ON events(project, actor_id);\nCREATE INDEX IF NOT EXISTS idx_events_idem ON events(project, idempotency_key);\nCREATE TABLE IF NOT EXISTS event_artifacts (\n  event_id TEXT NOT NULL,\n  project TEXT NOT NULL,\n  artifact_id TEXT NOT NULL,\n  PRIMARY KEY (event_id, artifact_id)\n);\nCREATE INDEX IF NOT EXISTS idx_ea_artifact ON event_artifacts(project, artifact_id);\nCREATE TABLE IF NOT EXISTS shares (\n  id TEXT PRIMARY KEY,\n  project TEXT NOT NULL,\n  artifact_id TEXT,\n  label TEXT,\n  created_at TEXT NOT NULL,\n  expires_at TEXT,\n  created_by TEXT\n);\n";
+export declare function newShareId(): string;
+export declare function shareIsLive(s: Share, now?: Date): boolean;
+/** Append an event: idempotent, sealed onto the current chain head. */
+export declare function appendEvent(store: EventStore, input: EventInput): Promise<{
+    event: Event;
+    deduped: boolean;
+}>;
+export declare function verifyProject(store: EventStore, project: string): Promise<VerifyResult>;
+/** Walk caused_by links up to the root — the "why" chain. */
+export declare function explainEvent(store: EventStore, id: string, maxDepth?: number): Promise<Event[]>;

package/dist/store.js

@@ -0,0 +1,84 @@
+import { sealEvent, verifyChain } from "./chain.js";
+/** Thrown by `deleteProject` when the target project's head no longer matches `expectedHead`: nothing was committed;
+ *  re-read the head, re-seal the audit and retry. */
+export class HeadMovedError extends Error {
+    constructor(project, expected) {
+        super(`project "${project}" was written to while being deleted (expected head ${expected.hash} seq ${expected.seq}); re-read its head and retry`);
+        this.name = "HeadMovedError";
+    }
+}
+export function isHeadMovedError(e) {
+    return e instanceof HeadMovedError || e?.name === "HeadMovedError";
+}
+export const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS events (
+  id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  timestamp TEXT NOT NULL,
+  received_at TEXT NOT NULL,
+  actor_type TEXT NOT NULL,
+  actor_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  caused_by TEXT,
+  idempotency_key TEXT,
+  prev_hash TEXT NOT NULL,
+  hash TEXT NOT NULL,
+  body TEXT NOT NULL,
+  UNIQUE(project, seq)
+);
+CREATE INDEX IF NOT EXISTS idx_events_project_ts ON events(project, timestamp);
+CREATE INDEX IF NOT EXISTS idx_events_actor ON events(project, actor_id);
+CREATE INDEX IF NOT EXISTS idx_events_idem ON events(project, idempotency_key);
+CREATE TABLE IF NOT EXISTS event_artifacts (
+  event_id TEXT NOT NULL,
+  project TEXT NOT NULL,
+  artifact_id TEXT NOT NULL,
+  PRIMARY KEY (event_id, artifact_id)
+);
+CREATE INDEX IF NOT EXISTS idx_ea_artifact ON event_artifacts(project, artifact_id);
+CREATE TABLE IF NOT EXISTS shares (
+  id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  artifact_id TEXT,
+  label TEXT,
+  created_at TEXT NOT NULL,
+  expires_at TEXT,
+  created_by TEXT
+);
+`;
+export function newShareId() {
+    const bytes = new Uint8Array(12);
+    globalThis.crypto.getRandomValues(bytes);
+    return "sh_" + [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+export function shareIsLive(s, now = new Date()) {
+    return !s.expires_at || new Date(s.expires_at) > now;
+}
+/** Append an event: idempotent, sealed onto the current chain head. */
+export async function appendEvent(store, input) {
+    if (input.idempotency_key) {
+        const existing = await store.byIdempotencyKey(input.project, input.idempotency_key);
+        if (existing)
+            return { event: existing, deduped: true };
+    }
+    const head = await store.head(input.project);
+    const event = await sealEvent(input, head);
+    await store.insert(event);
+    return { event, deduped: false };
+}
+export async function verifyProject(store, project) {
+    return verifyChain(await store.all(project));
+}
+/** Walk caused_by links up to the root — the "why" chain. */
+export async function explainEvent(store, id, maxDepth = 25) {
+    const chain = [];
+    let cur = await store.get(id);
+    const seen = new Set();
+    while (cur && chain.length < maxDepth && !seen.has(cur.id)) {
+        seen.add(cur.id);
+        chain.push(cur);
+        cur = cur.caused_by ? await store.get(cur.caused_by) : null;
+    }
+    return chain;
+}