@retrace-dev/core 0.1.0

package/dist/github.d.ts

@@ -0,0 +1,30 @@
+/**
+ * GitHub adapter — pure mapping from GitHub webhook payloads (and REST objects) to Retrace EventInputs,
+ * plus HMAC-SHA256 signature verification. Runs in Workers and Node.
+ *
+ * Handled events
+ *   pull_request      opened/reopened → created · synchronize → edited · closed(merged) → merged · closed → other:closed
+ *                     ready_for_review → other:ready_for_review · converted_to_draft → other:converted_to_draft
+ *   pull_request_review  approved → approved · changes_requested → rejected · commented → other:reviewed
+ *   issue_comment (on PR) → sent
+ *   workflow_run      completed → executed (system actor = GitHub Actions)
+ *   push              → skipped by default (the git adapter covers commits); enable with includePush
+ *
+ * Artifact ids line up with the git adapter: `pr:<owner/repo>#<n>`, `commit:<owner/repo>@<sha12>`, `repo:<owner/repo>#<path>`.
+ * WHY: PR body / review body; `caused_by` from a `Retrace-Caused-By: evt_…` line in the PR body.
+ * PROV role (what the webhook authoritatively knows): opened → PR generated · synchronize → PR both · review/comment → PR used ·
+ *   merged → PR used + merge commit generated · workflow_run → run generated, PRs/commit used · push → commit + files generated ·
+ *   closed-unmerged / ready_for_review / converted_to_draft / edited → absent (state changes, not content).
+ */
+import { EventInput, Actor } from "./schema.js";
+export declare function verifyGithubSignature(secret: string, rawBody: string, signatureHeader: string | null): Promise<boolean>;
+export declare function githubActor(user: any, fallback?: string): Actor;
+export interface GithubMapOptions {
+    project?: string;
+    includePush?: boolean;
+    deliveryId?: string;
+}
+/** Map one webhook delivery to zero or more events. `event` = X-GitHub-Event header. */
+export declare function mapGithubWebhook(event: string, payload: any, opts?: GithubMapOptions): EventInput[];
+/** Map a REST /pulls item (+ its reviews) for backfill. */
+export declare function mapGithubPullRest(repoFull: string, pr: any, reviews?: any[], project?: string): EventInput[];

package/dist/github.js

@@ -0,0 +1,112 @@
+const enc = new TextEncoder();
+const subtle = globalThis.crypto.subtle;
+export async function verifyGithubSignature(secret, rawBody, signatureHeader) {
+    if (!signatureHeader?.startsWith("sha256="))
+        return false;
+    const key = await subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await subtle.sign("HMAC", key, enc.encode(rawBody)));
+    const hex = [...mac].map((b) => b.toString(16).padStart(2, "0")).join("");
+    const given = signatureHeader.slice(7).toLowerCase();
+    if (given.length !== hex.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < hex.length; i++)
+        diff |= hex.charCodeAt(i) ^ given.charCodeAt(i);
+    return diff === 0;
+}
+const BOT_RE = /\[bot\]$|^copilot$|^dependabot|^renovate|^github-actions/i;
+export function githubActor(user, fallback = "github") {
+    const login = user?.login ?? fallback;
+    const bot = user?.type === "Bot" || BOT_RE.test(login);
+    const agenty = /copilot|claude|codex|devin|cursor|aider|sweep/i.test(login);
+    return {
+        type: bot ? (agenty ? "agent" : "system") : "human",
+        id: bot ? login : (user?.email ? user.email : `github:${login}`),
+        display_name: user?.name ?? login,
+        ...(agenty ? { model: undefined } : {}),
+    };
+}
+const causedByFrom = (text) => text?.match(/Retrace-Caused-By:\s*(evt_[a-f0-9]+)/i)?.[1];
+const trim = (s, n = 300) => { const t = s?.replace(/^\s*Retrace-[\w-]+:.*$/gim, "").trim(); return t ? (t.length > n ? t.slice(0, n - 1) + "…" : t) : undefined; };
+/** Map one webhook delivery to zero or more events. `event` = X-GitHub-Event header. */
+export function mapGithubWebhook(event, payload, opts = {}) {
+    const repoFull = payload?.repository?.full_name ?? "unknown/unknown";
+    const project = opts.project ?? repoFull;
+    const idem = (suffix) => (opts.deliveryId ? `gh:${opts.deliveryId}` : `gh:${repoFull}:${suffix}`);
+    const where = (url) => ({ system: "github", url });
+    const prArtifact = (pr, role) => ({ id: `pr:${repoFull}#${pr.number}`, kind: "pr", label: `PR #${pr.number} ${pr.title ?? ""}`.trim(), derived_from: pr.head?.sha ? [`commit:${repoFull}@${pr.head.sha.slice(0, 12)}`] : undefined, ...(role ? { role } : {}) });
+    if (event === "pull_request") {
+        const pr = payload.pull_request;
+        const a = payload.action;
+        const base = {
+            project, actor: githubActor(payload.sender), artifacts: [prArtifact(pr)], timestamp: pr.updated_at ?? new Date().toISOString(),
+            location: where(pr.html_url), caused_by: causedByFrom(pr.body), method: { tool: "github", automated: false, params: { action: a, head: pr.head?.ref, base: pr.base?.ref, head_sha: pr.head?.sha, additions: pr.additions, deletions: pr.deletions, changed_files: pr.changed_files } },
+            idempotency_key: idem(`pr${pr.number}:${a}:${pr.updated_at}`), tags: ["github", "pr"],
+        };
+        if (a === "opened" || a === "reopened")
+            return [{ ...base, action: "created", artifacts: [prArtifact(pr, "generated")], intent: trim(pr.body) ?? `Opened PR: ${pr.title}`, change: { summary: `${pr.title} (${pr.head?.ref} → ${pr.base?.ref})`, after_hash: pr.head?.sha } }];
+        if (a === "synchronize")
+            return [{ ...base, action: "edited", artifacts: [prArtifact(pr, "both")], intent: `pushed new commits to PR #${pr.number}`, change: { before_hash: payload.before, after_hash: payload.after, summary: `head ${String(payload.before).slice(0, 7)} → ${String(payload.after).slice(0, 7)}` } }];
+        if (a === "closed") {
+            if (pr.merged)
+                return [{ ...base, actor: githubActor(pr.merged_by ?? payload.sender), action: "merged", timestamp: pr.merged_at ?? base.timestamp, intent: trim(pr.body) ?? `Merged PR #${pr.number}`, change: { summary: `${pr.title} — merged ${pr.head?.ref} into ${pr.base?.ref} (+${pr.additions ?? "?"} −${pr.deletions ?? "?"}, ${pr.changed_files ?? "?"} files)`, after_hash: pr.merge_commit_sha }, artifacts: [prArtifact(pr, "used"), ...(pr.merge_commit_sha ? [{ id: `commit:${repoFull}@${pr.merge_commit_sha.slice(0, 12)}`, kind: "commit", label: `${repoFull}@${pr.merge_commit_sha.slice(0, 7)}`, derived_from: [`pr:${repoFull}#${pr.number}`], role: "generated" }] : [])], tags: ["github", "pr", "merge"] }];
+            return [{ ...base, action: "other", action_detail: "closed", intent: `closed PR #${pr.number} without merging` }];
+        }
+        if (a === "ready_for_review" || a === "converted_to_draft" || a === "edited")
+            return [{ ...base, action: "other", action_detail: a, intent: `${a.replace(/_/g, " ")}: ${pr.title}` }];
+        return [];
+    }
+    if (event === "pull_request_review" && payload.action === "submitted") {
+        const pr = payload.pull_request, r = payload.review;
+        const state = String(r.state).toLowerCase();
+        const action = state === "approved" ? "approved" : state === "changes_requested" ? "rejected" : "other";
+        return [{
+                project, actor: githubActor(r.user ?? payload.sender), action, action_detail: action === "other" ? "reviewed" : undefined,
+                artifacts: [prArtifact(pr, "used")], timestamp: r.submitted_at ?? new Date().toISOString(), location: where(r.html_url ?? pr.html_url),
+                intent: trim(r.body) ?? (state === "approved" ? `approved PR #${pr.number}` : state === "changes_requested" ? `requested changes on PR #${pr.number}` : `reviewed PR #${pr.number}`),
+                caused_by: causedByFrom(r.body) ?? causedByFrom(pr.body), method: { tool: "github-review", automated: false, params: { state, commit: r.commit_id } },
+                idempotency_key: idem(`review${r.id}`), tags: ["github", "review"],
+            }];
+    }
+    if (event === "issue_comment" && payload.action === "created" && payload.issue?.pull_request) {
+        const c = payload.comment, n = payload.issue.number;
+        return [{
+                project, actor: githubActor(c.user ?? payload.sender), action: "sent", artifacts: [{ id: `pr:${repoFull}#${n}`, kind: "pr", label: `PR #${n} ${payload.issue.title ?? ""}`.trim(), role: "used" }],
+                timestamp: c.created_at, location: where(c.html_url), intent: trim(c.body), caused_by: causedByFrom(c.body), method: { tool: "github-comment", automated: false },
+                idempotency_key: idem(`comment${c.id}`), tags: ["github", "comment"],
+            }];
+    }
+    if (event === "workflow_run" && payload.action === "completed") {
+        const w = payload.workflow_run;
+        const prs = w.pull_requests ?? [];
+        return [{
+                project, actor: { type: "system", id: "github-actions", display_name: `GitHub Actions · ${w.name}` }, action: "executed",
+                artifacts: [{ id: `run:${repoFull}#${w.id}`, kind: "workflow_run", label: `${w.name} #${w.run_number}`, role: "generated" }, ...prs.map((p) => ({ id: `pr:${repoFull}#${p.number}`, kind: "pr", label: `PR #${p.number}`, role: "used" })), { id: `commit:${repoFull}@${String(w.head_sha).slice(0, 12)}`, kind: "commit", label: `${repoFull}@${String(w.head_sha).slice(0, 7)}`, role: "used" }],
+                timestamp: w.updated_at, duration_ms: w.run_started_at && w.updated_at ? Date.parse(w.updated_at) - Date.parse(w.run_started_at) : undefined,
+                location: where(w.html_url), intent: `${w.name} on ${w.head_branch}: ${w.conclusion}`, change: { summary: `conclusion: ${w.conclusion}`, after_hash: w.head_sha },
+                method: { tool: "github-actions", automated: true, params: { event: w.event, conclusion: w.conclusion, attempt: w.run_attempt } },
+                idempotency_key: idem(`run${w.id}:${w.run_attempt}`), tags: ["github", "ci", String(w.conclusion)],
+            }];
+    }
+    if (event === "push" && opts.includePush) {
+        return (payload.commits ?? []).map((c) => ({
+            project, actor: { type: "human", id: c.author?.email ?? `github:${c.author?.username}`, display_name: c.author?.name }, action: "committed",
+            artifacts: [{ id: `commit:${repoFull}@${String(c.id).slice(0, 12)}`, kind: "commit", label: `${repoFull}@${String(c.id).slice(0, 7)}`, role: "generated" }, ...[...(c.added ?? []), ...(c.modified ?? []), ...(c.removed ?? [])].map((f) => ({ id: `repo:${repoFull}#${f}`, kind: "file", label: f, role: "generated" }))],
+            timestamp: c.timestamp, location: where(c.url), intent: c.message, method: { tool: "git", automated: false }, idempotency_key: `git:${c.id}`, tags: ["github", "push"],
+        }));
+    }
+    return [];
+}
+/** Map a REST /pulls item (+ its reviews) for backfill. */
+export function mapGithubPullRest(repoFull, pr, reviews = [], project = repoFull) {
+    const fake = { repository: { full_name: repoFull } };
+    const out = [];
+    out.push(...mapGithubWebhook("pull_request", { ...fake, action: "opened", sender: pr.user, pull_request: { ...pr, updated_at: pr.created_at } }, { project }));
+    for (const r of reviews)
+        out.push(...mapGithubWebhook("pull_request_review", { ...fake, action: "submitted", sender: r.user, review: r, pull_request: pr }, { project }));
+    if (pr.merged_at)
+        out.push(...mapGithubWebhook("pull_request", { ...fake, action: "closed", sender: pr.merged_by ?? pr.user, pull_request: { ...pr, merged: true, updated_at: pr.merged_at } }, { project }));
+    else if (pr.state === "closed")
+        out.push(...mapGithubWebhook("pull_request", { ...fake, action: "closed", sender: pr.user, pull_request: { ...pr, merged: false, updated_at: pr.closed_at ?? pr.updated_at } }, { project }));
+    return out.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./schema.js";
+export * from "./chain.js";
+export * from "./store.js";
+export * from "./explain.js";
+export * from "./router.js";
+export * from "./signing.js";
+export * from "./export.js";
+export * from "./report.js";
+export * from "./lineage.js";
+export * from "./github.js";
+export * from "./gdrive.js";
+export * from "./status.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./schema.js";
+export * from "./chain.js";
+export * from "./store.js";
+export * from "./explain.js";
+export * from "./router.js";
+export * from "./signing.js";
+export * from "./export.js";
+export * from "./report.js";
+export * from "./lineage.js";
+export * from "./github.js";
+export * from "./gdrive.js";
+export * from "./status.js";

package/dist/lineage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Artifact lineage graph.
+ *   Nodes: artifacts (+ optionally actors).
+ *   Edges:
+ *     derived   — explicit ArtifactRef.derived_from (strongest signal)
+ *     flow      — causal: event B (caused_by A) touched artifact Y while A touched artifact X, X≠Y  ⇒ X → Y
+ *                 (e.g. human instructs on task T → agent edits file F  ⇒ T → F; agent reads F1 → then creates F2 ⇒ F1 → F2)
+ *     touched   — actor → artifact (only when includeActors)
+ * Pure function of events; the same code runs in the UI (embedded), MCP server and Worker.
+ */
+import { Event } from "./schema.js";
+export interface LineageNode {
+    id: string;
+    type: "artifact" | "actor";
+    label: string;
+    kind?: string;
+    events: number;
+    first_seq: number;
+    last_seq: number;
+    actors?: string[];
+    actions?: Record<string, number>;
+}
+export interface LineageEdge {
+    from: string;
+    to: string;
+    type: "derived" | "flow" | "touched";
+    weight: number;
+    via?: string[];
+}
+export interface Lineage {
+    nodes: LineageNode[];
+    edges: LineageEdge[];
+}
+export interface LineageOptions {
+    includeActors?: boolean;
+    maxVia?: number;
+}
+/**
+ * Latest known label per artifact id: the label on the last event (by seq) that carries one.
+ * Drive "created" events arrive titled "Untitled" and later edits/renames carry the real title,
+ * so anywhere the UI names an artifact it should resolve through this. Events stay untouched —
+ * an individual event keeps its own as-at label.
+ */
+export declare function latestArtifactLabels(events: Pick<Event, "seq" | "artifacts">[]): Map<string, string>;
+export declare function buildLineage(events: Event[], opts?: LineageOptions): Lineage;
+/** Roots → leaves layering by longest path (cycles broken by seq order). Returns node id → layer. */
+export declare function layerLineage(l: Lineage): Map<string, number>;
+export declare function renderLineageDot(l: Lineage): string;
+export declare function renderLineageMermaid(l: Lineage): string;
+export declare function renderLineageText(l: Lineage): string;

package/dist/lineage.js

@@ -0,0 +1,150 @@
+/**
+ * Latest known label per artifact id: the label on the last event (by seq) that carries one.
+ * Drive "created" events arrive titled "Untitled" and later edits/renames carry the real title,
+ * so anywhere the UI names an artifact it should resolve through this. Events stay untouched —
+ * an individual event keeps its own as-at label.
+ */
+export function latestArtifactLabels(events) {
+    const out = new Map();
+    for (const e of [...events].sort((a, b) => a.seq - b.seq))
+        for (const a of e.artifacts)
+            if (a.label)
+                out.set(a.id, a.label);
+    return out;
+}
+export function buildLineage(events, opts = {}) {
+    const maxVia = opts.maxVia ?? 5;
+    const nodes = new Map();
+    const edges = new Map();
+    const byId = new Map(events.map((e) => [e.id, e]));
+    const sorted = [...events].sort((a, b) => a.seq - b.seq);
+    const artNode = (id, label, kind, seq = 0) => {
+        let n = nodes.get("a:" + id);
+        if (!n) {
+            n = { id, type: "artifact", label: label ?? id, kind, events: 0, first_seq: seq, last_seq: seq, actors: [], actions: {} };
+            nodes.set("a:" + id, n);
+        }
+        if (label)
+            n.label = label; // events arrive in seq order, so the last label seen is the latest
+        if (kind && !n.kind)
+            n.kind = kind;
+        return n;
+    };
+    const actorNode = (e) => {
+        const id = e.actor.id;
+        let n = nodes.get("u:" + id);
+        if (!n) {
+            n = { id, type: "actor", label: e.actor.display_name ?? id, kind: e.actor.type, events: 0, first_seq: e.seq, last_seq: e.seq };
+            nodes.set("u:" + id, n);
+        }
+        return n;
+    };
+    const addEdge = (from, to, type, via) => {
+        if (from === to)
+            return;
+        const k = `${type}|${from}|${to}`;
+        let ed = edges.get(k);
+        if (!ed) {
+            ed = { from, to, type, weight: 0, via: [] };
+            edges.set(k, ed);
+        }
+        ed.weight++;
+        if (via && ed.via.length < maxVia)
+            ed.via.push(via);
+    };
+    for (const e of sorted) {
+        for (const a of e.artifacts) {
+            const n = artNode(a.id, a.label, a.kind, e.seq);
+            n.events++;
+            n.last_seq = e.seq;
+            n.first_seq = Math.min(n.first_seq, e.seq);
+            if (!n.actors.includes(e.actor.id))
+                n.actors.push(e.actor.id);
+            n.actions[e.action] = (n.actions[e.action] ?? 0) + 1;
+            for (const src of a.derived_from ?? []) {
+                artNode(src, undefined, undefined, e.seq);
+                addEdge(src, a.id, "derived", e.id);
+            }
+            if (opts.includeActors) {
+                const u = actorNode(e);
+                u.events++;
+                u.last_seq = e.seq;
+                addEdge("u:" + e.actor.id, a.id, "touched", e.id);
+            }
+        }
+        if (e.caused_by) {
+            const parent = byId.get(e.caused_by);
+            if (parent) {
+                for (const pa of parent.artifacts)
+                    for (const ca of e.artifacts)
+                        if (pa.id !== ca.id)
+                            addEdge(pa.id, ca.id, "flow", e.id);
+            }
+        }
+    }
+    return { nodes: [...nodes.values()], edges: [...edges.values()] };
+}
+/** Roots → leaves layering by longest path (cycles broken by seq order). Returns node id → layer. */
+export function layerLineage(l) {
+    const ids = l.nodes.filter((n) => n.type === "artifact").map((n) => n.id);
+    const inc = new Map(ids.map((id) => [id, []]));
+    for (const e of l.edges)
+        if (e.type !== "touched" && inc.has(e.to) && inc.has(e.from))
+            inc.get(e.to).push(e.from);
+    const seq = new Map(l.nodes.map((n) => [n.id, n.first_seq]));
+    const layer = new Map();
+    const visiting = new Set();
+    const depth = (id) => {
+        if (layer.has(id))
+            return layer.get(id);
+        if (visiting.has(id))
+            return 0;
+        visiting.add(id);
+        let d = 0;
+        for (const p of inc.get(id) ?? [])
+            if ((seq.get(p) ?? 0) <= (seq.get(id) ?? 0))
+                d = Math.max(d, depth(p) + 1);
+        visiting.delete(id);
+        layer.set(id, d);
+        return d;
+    };
+    for (const id of ids)
+        depth(id);
+    return layer;
+}
+const q = (s) => JSON.stringify(s);
+export function renderLineageDot(l) {
+    const shape = (n) => n.type === "actor" ? (n.kind === "human" ? "ellipse" : "hexagon") : n.kind === "commit" ? "note" : n.kind === "task" ? "folder" : "box";
+    const lines = ["digraph retrace {", "  rankdir=LR; node [fontname=Helvetica, fontsize=10]; edge [fontsize=9];"];
+    for (const n of l.nodes)
+        lines.push(`  ${q((n.type === "actor" ? "u:" : "") + n.id)} [label=${q(`${n.label}${n.type === "artifact" ? `\n${n.events} event${n.events === 1 ? "" : "s"}` : ""}`)}, shape=${shape(n)}${n.type === "actor" ? ", style=dashed" : ""}];`);
+    for (const e of l.edges)
+        lines.push(`  ${q(e.from)} -> ${q(e.to)} [label=${q(e.type === "derived" ? "derived" : e.type === "flow" ? `flow ×${e.weight}` : "")}${e.type === "derived" ? ", penwidth=2" : e.type === "touched" ? ", style=dashed, color=gray" : ""}];`);
+    lines.push("}");
+    return lines.join("\n");
+}
+export function renderLineageMermaid(l) {
+    const idOf = new Map();
+    let i = 0;
+    const nid = (s) => { if (!idOf.has(s))
+        idOf.set(s, "n" + i++); return idOf.get(s); };
+    const lines = ["graph LR"];
+    for (const n of l.nodes) {
+        const key = (n.type === "actor" ? "u:" : "") + n.id;
+        const lbl = `${n.label}${n.type === "artifact" ? ` (${n.events})` : ""}`.replace(/"/g, "'");
+        lines.push(n.type === "actor" ? `  ${nid(key)}(["${lbl}"])` : `  ${nid(key)}["${lbl}"]`);
+    }
+    for (const e of l.edges)
+        lines.push(`  ${nid(e.from)} ${e.type === "derived" ? "==>" : e.type === "flow" ? "-->" : "-.->"}${e.type === "flow" && e.weight > 1 ? `|×${e.weight}|` : ""} ${nid(e.to)}`);
+    return lines.join("\n");
+}
+export function renderLineageText(l) {
+    const arts = l.nodes.filter((n) => n.type === "artifact");
+    const out = [`${arts.length} artifacts, ${l.edges.length} edges`];
+    for (const n of arts) {
+        const ins = l.edges.filter((e) => e.to === n.id && e.type !== "touched").map((e) => `${e.from} (${e.type})`);
+        const outs = l.edges.filter((e) => e.from === n.id && e.type !== "touched").map((e) => `${e.to} (${e.type})`);
+        out.push(`- ${n.label}${n.kind ? ` [${n.kind}]` : ""} · ${n.events} ev · by ${n.actors?.join(", ")}${ins.length ? `\n    ← ${ins.join("; ")}` : ""}${outs.length ? `\n    → ${outs.join("; ")}` : ""}`);
+    }
+    return out.join("\n");
+}

package/dist/report.d.ts

@@ -0,0 +1,6 @@
+/** Printable provenance report (HTML → "Save as PDF" in any browser). Self-contained, no scripts required. */
+import { ExportBundle, ExportVerdict } from "./export.js";
+export declare function renderReportHtml(bundle: ExportBundle, verdict?: ExportVerdict, opts?: {
+    title?: string;
+    baseUrl?: string;
+}): string;

package/dist/report.js

@@ -0,0 +1,79 @@
+import { latestArtifactLabels } from "./lineage.js";
+import { roleMark } from "./explain.js";
+const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+const actorName = (e) => e.actor.display_name ?? e.actor.id;
+const verb = (e) => (e.action === "other" ? e.action_detail ?? "acted on" : e.action);
+export function renderReportHtml(bundle, verdict, opts = {}) {
+    const title = opts.title ?? `Provenance report — ${bundle.scope.project}${bundle.scope.artifact_id ? " · " + bundle.scope.artifact_id : ""}`;
+    const events = [...bundle.events].sort((a, b) => a.seq - b.seq);
+    const byId = new Map(events.map((e) => [e.id, e]));
+    const labels = latestArtifactLabels(events);
+    const humans = new Set(events.filter((e) => e.actor.type === "human").map((e) => e.actor.id));
+    const agents = new Set(events.filter((e) => e.actor.type === "agent").map((e) => e.actor.id));
+    const arts = new Set(events.flatMap((e) => e.artifacts.map((a) => a.id)));
+    const first = events[0]?.timestamp, last = events.at(-1)?.timestamp;
+    const sigLine = !bundle.signature ? "unsigned" : verdict ? (verdict.signature === "valid" ? "valid" : "INVALID") : "present (not verified here)";
+    const chainLine = bundle.chain.ok ? `intact — ${bundle.chain.checked} of ${bundle.chain.total_events} events verified at export` : `BROKEN at #${bundle.chain.first_bad_seq}: ${bundle.chain.reason}`;
+    const rows = events.map((e) => {
+        const cause = e.caused_by ? byId.get(e.caused_by) : undefined;
+        // each part is escaped individually (intent, actor names, verbs and caused_by ids are caller-supplied) and only
+        // then joined with a literal <br> — the one piece of markup this cell is allowed to contain
+        const why = [e.intent, cause ? `↳ because #${cause.seq} (${actorName(cause)} ${verb(cause)})` : e.caused_by ? `↳ caused by ${e.caused_by}` : ""].filter(Boolean).map(esc).join("<br>");
+        const where = [e.location?.system, e.location?.environment, e.location?.path ?? e.location?.url].filter(Boolean).join(" · ");
+        const how = [e.method?.tool, e.method?.automated == null ? "" : e.method.automated ? "automated" : "manual", e.method?.tokens != null ? `${e.method.tokens} tokens` : ""].filter(Boolean).join(" · ");
+        return `<tr class="${esc(e.actor.type)}">
+      <td class="mono">#${e.seq}<br><small>${esc(new Date(e.timestamp).toISOString().replace("T", " ").slice(0, 19))}Z</small></td>
+      <td><b>${esc(actorName(e))}</b><br><small>${esc(e.actor.type)}${e.actor.model ? " · " + esc(e.actor.model) : ""}${e.actor.on_behalf_of ? "<br>for " + esc(e.actor.on_behalf_of) : ""}</small></td>
+      <td><b>${esc(verb(e))}</b> ${e.artifacts.map((a) => `${roleMark(a.role) ? `<small class="role">${roleMark(a.role)}</small>` : ""}<code>${esc(labels.get(a.id) ?? a.label ?? a.id)}</code>`).join(" ")}${e.change?.summary ? `<br><small>${esc(e.change.summary)}</small>` : ""}</td>
+      <td><small>${esc(where)}</small></td>
+      <td>${why}</td>
+      <td><small>${esc(how)}</small></td>
+      <td class="mono"><small>${esc(e.hash.slice(0, 12))}…</small></td>
+    </tr>`;
+    }).join("\n");
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>
+<style>
+ body{font:12px/1.4 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;color:#111;margin:32px;max-width:1100px}
+ h1{font-size:20px;margin:0 0 4px} h2{font-size:13px;text-transform:uppercase;letter-spacing:.08em;color:#666;margin:22px 0 8px}
+ .meta{display:grid;grid-template-columns:140px 1fr;gap:4px 12px;font-size:12px} .meta .k{color:#666}
+ table{border-collapse:collapse;width:100%;font-size:11.5px} th,td{border-top:1px solid #ddd;padding:6px 6px;vertical-align:top;text-align:left}
+ th{font-size:10.5px;text-transform:uppercase;letter-spacing:.06em;color:#666;border-top:0}
+ tr.human td:first-child{border-left:3px solid #f2a93b} tr.agent td:first-child{border-left:3px solid #5aa9ff} tr.system td:first-child{border-left:3px solid #9aa3b5}
+ code{font-family:ui-monospace,Menlo,Consolas,monospace;font-size:10.5px;background:#f2f3f5;padding:0 3px;border-radius:3px}
+ .mono{font-family:ui-monospace,Menlo,Consolas,monospace} small{color:#555}
+ .role{font-size:8.5px;text-transform:uppercase;letter-spacing:.05em;color:#777;margin-right:2px;vertical-align:middle}
+ .ok{color:#178f4f;font-weight:600} .bad{color:#d1303f;font-weight:600}
+ .box{border:1px solid #ddd;border-radius:6px;padding:10px 12px;background:#fafbfc}
+ .print{position:fixed;top:12px;right:12px;padding:8px 12px;border:1px solid #bbb;border-radius:6px;background:#fff;cursor:pointer}
+ @media print{.print{display:none} body{margin:12mm}}
+</style></head><body>
+<button class="print" onclick="window.print()">Print / Save as PDF</button>
+<h1>${esc(title)}</h1>
+<div><small>Generated ${esc(bundle.generated_at)} · Retrace ${esc(bundle.format)}</small></div>
+
+<h2>Summary</h2>
+<div class="meta">
+  <div class="k">Project</div><div>${esc(bundle.scope.project)}</div>
+  ${bundle.scope.artifact_id ? `<div class="k">Artifact</div><div><code>${esc(bundle.scope.artifact_id)}</code></div>` : ""}
+  <div class="k">Events</div><div>${events.length}${bundle.context_events ? ` (${bundle.context_events} included as causal context)` : ""}${first ? ` — from ${esc(first)} to ${esc(last)}` : ""}</div>
+  <div class="k">Actors</div><div>${[humans.size ? `${humans.size} human${humans.size === 1 ? "" : "s"} (${esc([...humans].join(", "))})` : "", agents.size ? `${agents.size} agent${agents.size === 1 ? "" : "s"} (${esc([...agents].join(", "))})` : ""].filter(Boolean).join("; ") || "—"}</div>
+  <div class="k">Artifacts</div><div>${arts.size}</div>
+  <div class="k">Chain integrity</div><div class="${bundle.chain.ok ? "ok" : "bad"}">${esc(chainLine)}</div>
+  <div class="k">Signature</div><div class="${sigLine === "valid" ? "ok" : sigLine === "INVALID" ? "bad" : ""}">${esc(sigLine)}${bundle.issuer ? ` · Ed25519 key <span class="mono">${esc(bundle.issuer.kid)}</span>${bundle.issuer.name ? " · " + esc(bundle.issuer.name) : ""}` : ""}</div>
+  ${bundle.chain.head_hash ? `<div class="k">Head hash</div><div class="mono">${esc(bundle.chain.head_hash)}</div>` : ""}
+</div>
+
+<h2>Timeline — who · what · where · why · how</h2>
+<table><thead><tr><th>#/when (UTC)</th><th>who</th><th>what</th><th>where</th><th>why</th><th>how</th><th>hash</th></tr></thead><tbody>
+${rows}
+</tbody></table>
+
+<h2>How to verify this report</h2>
+<div class="box">
+  Each event is hashed (SHA-256) together with the previous event's hash, so any alteration or deletion breaks the chain. The JSON bundle this report was rendered from is signed with the issuer's Ed25519 key${bundle.issuer ? ` (kid <span class="mono">${esc(bundle.issuer.kid)}</span>)` : ""}.
+  Verify offline with <code>retrace-export verify bundle.json</code>${opts.baseUrl ? `, or fetch the issuer's public key from <code>${esc(opts.baseUrl)}/.well-known/retrace-pubkey</code>` : ""}.
+  ${bundle.issuer ? `<br><br>Issuer public key (JWK): <span class="mono">${esc(JSON.stringify(bundle.issuer.public_key))}</span>` : ""}
+  ${bundle.signature ? `<br>Signature: <span class="mono" style="word-break:break-all">${esc(bundle.signature)}</span>` : ""}
+</div>
+</body></html>`;
+}

package/dist/router.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Shared HTTP router (fetch API) — used by the Cloudflare Worker and the local Node server.
+ *
+ * Owner routes (auth: Bearer token or ?token= when a token is configured). Per-actor credentials (RETRACE_CREDENTIALS,
+ * Bearer only) may also POST /events and read; "pinned" credentials have their actor stamped by the server (with one
+ * carve-out: an agent credential may record "instructed" roots for its configured on_behalf_of human), "assert"
+ * credentials (git hook, backfill forwarders) may assert only the actors in their allowed_actors list. DELETE/share
+ * stay owner-only.
+ *   GET  /  | /ui                        UI
+ *   GET  /api                            health + the schema surface this build understands (public; see schemaSurface)
+ *   GET  /.well-known/retrace-pubkey     issuer public key (JWK) — public
+ *   POST /events                         append (EventInput)
+ *   GET  /events/:id · /events/:id/why
+ *   GET  /projects · /projects/:p/events?… · /projects/:p/head · /projects/:p/verify · /projects/:p/status
+ *   GET  /projects/:p/export?artifact_id=…      signed JSON bundle
+ *   GET  /projects/:p/report?artifact_id=…      printable HTML report
+ *   GET  /projects/:p/lineage?artifact_id=&format=json|dot|mermaid&actors=1   artifact lineage graph
+ *   POST /projects/:p/share  {artifact_id?, label?, expires_in_days?}   → {share, url}
+ *   DELETE /projects/:p?confirm=:p[&caused_by=evt_…]   delete a project (junk cleanup; confirm must equal the project name) → per-table counts +
+ *                                        an ops-project audit event attributed to ownerActor (RETRACE_OWNER) and linked to caused_by
+ *
+ * Webhooks (auth: HMAC signature, not the bearer token):
+ *   POST /hooks/github?project=<name>     GitHub webhook receiver (pull_request, pull_request_review, issue_comment, workflow_run[, push])
+ *   POST /hooks/gdrive?project=<name>     Google Drive Activity forwarder (Apps Script / retrace-gdrive CLI); bearer-token auth
+ *
+ * Share routes (no auth; scope locked to the share's project/artifact; read-only):
+ *   GET  /s/:id                          UI in shared mode
+ *   GET  /s/:id/meta · /s/:id/events · /s/:id/verify · /s/:id/export · /s/:id/report · /s/:id/lineage
+ */
+import { z } from "zod";
+import { Actor } from "./schema.js";
+import { EventStore } from "./store.js";
+/** A per-actor credential (security review 2026-08-21, backlog #6). Holders can POST /events and read; they cannot
+ *  DELETE or create shares. trust "pinned" (default): the Worker stamps `actor` from the credential — the body may only
+ *  add display_name/version and may not claim human/system, except that an agent credential with `actor.on_behalf_of`
+ *  may record "instructed" roots attributed to exactly that human (see resolveActor). trust "assert": the body actor
+ *  is stored verbatim IF it appears in the credential's allowed_actors list (git hook, backfill, Drive forwarder —
+ *  callers that legitimately relay other people's actions, bounded to the actors they are expected to relay). */
+export declare const Credential: z.ZodObject<{
+    token: z.ZodString;
+    /** Human-readable name, recorded nowhere — for the operator's own bookkeeping */
+    name: z.ZodOptional<z.ZodString>;
+    actor: z.ZodObject<{
+        type: z.ZodEnum<["human", "agent", "system"]>;
+        id: z.ZodString;
+        display_name: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        on_behalf_of: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    }, {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    }>;
+    trust: z.ZodDefault<z.ZodEnum<["pinned", "assert"]>>;
+    /** For assert trust: the ONLY actors this credential may assert on POST /events, matched on exact type + id
+     *  (audit 2026-08-22, P1: an unbounded assert credential could seal events claiming any actor — a human, or the
+     *  pinned agent's id — into any project). Absent or empty = may assert none; routes that map actors server-side
+     *  (/hooks/gdrive) are unaffected. Ignored for pinned trust. */
+    allowed_actors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<["human", "agent", "system"]>;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "human" | "agent" | "system";
+        id: string;
+    }, {
+        type: "human" | "agent" | "system";
+        id: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    actor: {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    };
+    token: string;
+    trust: "pinned" | "assert";
+    name?: string | undefined;
+    allowed_actors?: {
+        type: "human" | "agent" | "system";
+        id: string;
+    }[] | undefined;
+}, {
+    actor: {
+        type: "human" | "agent" | "system";
+        id: string;
+        display_name?: string | undefined;
+        model?: string | undefined;
+        version?: string | undefined;
+        on_behalf_of?: string | undefined;
+    };
+    token: string;
+    name?: string | undefined;
+    trust?: "pinned" | "assert" | undefined;
+    allowed_actors?: {
+        type: "human" | "agent" | "system";
+        id: string;
+    }[] | undefined;
+}>;
+export type Credential = z.infer<typeof Credential>;
+/** Parse the RETRACE_CREDENTIALS secret (JSON array). Throws on malformed config so a bad deploy fails loudly. */
+export declare function parseCredentials(raw?: string | null): Credential[];
+export interface RouterOptions {
+    /** Owner token: full access, body actor stored verbatim. Accepted as Bearer or ?token= (the UI uses the latter). */
+    token?: string;
+    /** Per-actor credentials; see Credential. Bearer only (never ?token=, which leaks into logs). */
+    credentials?: Credential[];
+    signingKey?: JsonWebKey | null;
+    issuerName?: string;
+    /** Public base URL used when building share links (defaults to request origin) */
+    publicUrl?: string;
+    /** GitHub webhook secret; POST /hooks/github?project=… is authenticated by X-Hub-Signature-256 instead of the bearer token */
+    githubSecret?: string;
+    /** Also log `push` commits from GitHub (off by default — the git adapter covers commits, and idempotency keys match anyway) */
+    githubIncludePush?: boolean;
+    /** Project that receives the audit event when a project is deleted (default "retrace") */
+    opsProject?: string;
+    /** Who the owner token is. Owner-only actions (DELETE /projects/:p) are audited as this actor — typically the operator,
+     *  e.g. {type:"human", id:"jordan@example.com"} from RETRACE_OWNER. Unset → {type:"system", id:"worker"}, which says
+     *  only that *the server* did it (security review 2026-08-21, audit-event actor). */
+    ownerActor?: Actor;
+}
+export declare function createHandler(store: EventStore, tokenOrOpts?: string | RouterOptions): (req: Request) => Promise<Response>;