@eir-labs/coltrane 0.5.1 → 0.7.2

package/dist/src/output_mirror.js

@@ -0,0 +1,381 @@
+// Two-tier output persistence + retrieval — the reliable local mirror MCP traverses.
+//
+// The bug this closes: a CLI-dispatched gig sealed outputs to disk, but the payloads were not
+// reliably retrievable through the MCP surface. This module makes every sealed output land in a
+// content-addressed local store under `.coltrane/` (gitignored) that MCP reads seamlessly with
+// NO remote configured, and — only when an append credential is present — ALSO drains the same
+// record to a remote row + artifact store.
+//
+// Two tiers, by design:
+//   • TIER 1 — a compact, queryable METADATA row, ALWAYS. id, gig_id, agent, phase, primitive,
+//     domain_type, content_sha, a short preview, a storage_ref, cost/tokens, created_at. This
+//     alone supports high-level traversal (`output_query`/`output_trace`) without loading a
+//     single payload.
+//   • TIER 2 — the full PAYLOAD, as a content-addressed artifact, fetched only on the deeper
+//     second pass (`readPayload`, or `output_query { include_data:true }`).
+//
+// OSS stays pure: with no drain credential in the environment, ONLY the local tier runs and no
+// new npm dependency is touched (the remote row goes over `fetch`; the optional Postgres path is
+// a guarded dynamic import that is never reached unless a PG connection string is set).
+import * as fs from "node:fs";
+import * as path from "node:path";
+const ARTIFACT_SUBDIR = path.join("outputs", "artifacts");
+const META_SUBDIR = path.join("outputs", "meta");
+// Where the local mirror lives. `COLTRANE_MIRROR_DIR` overrides (tests, sandboxes); otherwise
+// `<genomeRoot>/.coltrane` — beside the ledger, gitignored, so a CLI and an MCP server rooted at
+// the same repo share one store and MCP retrieval traverses exactly what the CLI sealed.
+export function defaultMirrorDir(root) {
+    const override = process.env["COLTRANE_MIRROR_DIR"];
+    if (override && override.length > 0)
+        return override;
+    return path.join(root ?? process.cwd(), ".coltrane");
+}
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+function appendJsonl(file, row) {
+    ensureDir(path.dirname(file));
+    fs.appendFileSync(file, JSON.stringify(row) + "\n", "utf8");
+}
+// A short, deterministic summary of the payload for the Tier-1 row. Never throws.
+export function outputPreview(data) {
+    try {
+        const s = JSON.stringify(data);
+        return s.length <= 200 ? s : s.slice(0, 197) + "...";
+    }
+    catch {
+        return "";
+    }
+}
+const makePreview = outputPreview;
+/** The repo-relative artifact path for a content_sha — the Tier-1 row's local `storage_ref`. */
+export function mirrorStorageRef(content_sha) {
+    return path.join(ARTIFACT_SUBDIR, `${content_sha.replace(/[^0-9a-zA-Z._-]/g, "_")}.json`);
+}
+function metaOf(rec, storage_ref) {
+    return {
+        id: rec.id,
+        gig_id: rec.gig_id,
+        agent_slug: rec.agent_slug,
+        from_role: rec.from_role,
+        phase: rec.phase,
+        primitive: rec.primitive,
+        core_type: rec.core_type,
+        domain_type: rec.domain_type,
+        domain_type_version: rec.domain_type_version,
+        domain: rec.domain,
+        content_sha: rec.content_sha,
+        input_refs: rec.input_refs,
+        input_shas: rec.input_shas,
+        cost_usd: rec.cost_usd,
+        tokens_used: rec.tokens_used,
+        duration_ms: rec.duration_ms,
+        model: rec.model,
+        model_tier: rec.model_tier,
+        created_at: rec.created_at,
+        preview: makePreview(rec.data),
+        storage_ref,
+    };
+}
+function readJsonlRows(file) {
+    if (!fs.existsSync(file))
+        return [];
+    const rows = [];
+    for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            rows.push(JSON.parse(t));
+        }
+        catch {
+            // Forgiving read (a torn append should not take the whole traversal offline). The
+            // store's own `integrity()` is the surface that REPORTS damage; here we keep serving.
+        }
+    }
+    return rows;
+}
+export function createOutputMirror(mirrorRoot) {
+    const artifactsDir = path.join(mirrorRoot, ARTIFACT_SUBDIR);
+    const metaDir = path.join(mirrorRoot, META_SUBDIR);
+    function artifactPath(content_sha) {
+        // Content-addressed: a filename-safe form of the sha. Two byte-identical payloads dedupe.
+        const safe = content_sha.replace(/[^0-9a-zA-Z._-]/g, "_");
+        return path.join(artifactsDir, `${safe}.json`);
+    }
+    const storageRef = mirrorStorageRef;
+    function writeArtifact(rec) {
+        const file = artifactPath(rec.content_sha);
+        // Content-addressed → if it already exists, the bytes are identical; skip the rewrite.
+        if (fs.existsSync(file))
+            return;
+        ensureDir(path.dirname(file));
+        fs.writeFileSync(file, JSON.stringify({ content_sha: rec.content_sha, id: rec.id, data: rec.data }), "utf8");
+    }
+    function metaFile(gig_id) {
+        return path.join(metaDir, `${gig_id}.jsonl`);
+    }
+    return {
+        root: mirrorRoot,
+        persist(rec) {
+            const ref = storageRef(rec.content_sha);
+            // TIER 2 first, so the Tier-1 row never points at an artifact that is not there yet.
+            writeArtifact(rec);
+            // TIER 1 — the always-on compact row.
+            appendJsonl(metaFile(rec.gig_id), metaOf(rec, ref));
+            // REMOTE, credential-gated. Fire-and-forget: a finished gig is not failed because a
+            // remote append could not be reached. OSS with no credential never enters this path.
+            if (remoteConfigured()) {
+                void drainRemote(rec).catch((e) => {
+                    if (process.env["COLTRANE_DRAIN_DEBUG"]) {
+                        console.warn(`[output_mirror] remote drain failed: ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                });
+            }
+        },
+        queryMeta(filter) {
+            // A FRESH read every call — this is what makes a long-lived MCP server see a gig sealed by
+            // a separate CLI process. No `fullyHydrated`-style latch lives here on purpose.
+            if (!fs.existsSync(metaDir))
+                return [];
+            const gigId = filter?.gig_id;
+            const files = gigId
+                ? [metaFile(gigId)]
+                : fs.readdirSync(metaDir).filter((f) => f.endsWith(".jsonl")).map((f) => path.join(metaDir, f));
+            const out = [];
+            for (const file of files)
+                out.push(...readJsonlRows(file));
+            return out;
+        },
+        readPayload(sel) {
+            let content_sha = sel.content_sha;
+            let meta;
+            if (!content_sha && sel.id) {
+                // Resolve id → content_sha via the Tier-1 rows (fresh scan).
+                meta = this.queryMeta().find((m) => m.id === sel.id);
+                content_sha = meta?.content_sha;
+            }
+            else if (content_sha) {
+                meta = this.queryMeta().find((m) => m.content_sha === content_sha);
+            }
+            if (!content_sha)
+                return undefined;
+            const file = artifactPath(content_sha);
+            if (fs.existsSync(file)) {
+                try {
+                    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+                    return { meta, data: parsed.data };
+                }
+                catch {
+                    return { meta };
+                }
+            }
+            // Local miss — the artifact may live only in the remote store (a mirror pulled from a peer).
+            // Best-effort remote fetch when configured; otherwise nothing to return.
+            return meta ? { meta } : undefined;
+        },
+    };
+}
+// ── REMOTE TIER — append-only, credential-gated. Never a service_role key (see the TODO). ──────
+//
+// Two credential shapes are accepted, whichever is present drives the write:
+//   (a) COLTRANE_DRAIN_KEY  — a per-consumer ISSUED, scoped append key. The Tier-1 row is POSTed
+//       to PostgREST (`coltrane_outputs`) and the Tier-2 payload uploaded to Storage, both with
+//       this key. Uses `fetch` only — no new npm dependency.
+//   (b) COLTRANE_DRAIN_PG   — a Postgres connection string for a scoped append role. The row is
+//       written over a direct `pg` connection (a guarded dynamic import; `pg` is NOT a declared
+//       dependency, so this path is unreachable — and harmless — unless the operator both sets
+//       the env AND installs the driver).
+//
+// COLTRANE_DRAIN_URL is the PostgREST + Storage project base URL (deployment-supplied, no host
+// baked in here) for the (a) REST paths. COLTRANE_DRAIN_BUCKET names the Storage bucket
+// (default "coltrane-artifacts").
+function remoteConfigured() {
+    return Boolean(process.env["COLTRANE_DRAIN_KEY"] || process.env["COLTRANE_DRAIN_PG"]);
+}
+function drainBody(rec) {
+    const body = {
+        id: rec.id,
+        gig_id: rec.gig_id,
+        agent_slug: rec.agent_slug,
+        phase: rec.phase,
+        primitive: rec.primitive,
+        core_type: rec.core_type,
+        domain_type: rec.domain_type,
+        domain_type_version: rec.domain_type_version,
+        domain: rec.domain,
+        content_sha: rec.content_sha,
+        data: rec.data,
+        input_shas: rec.input_shas,
+        cost_usd: rec.cost_usd,
+        tokens_used: rec.tokens_used,
+        duration_ms: rec.duration_ms,
+        created_at: rec.created_at,
+    };
+    return body;
+}
+async function drainRemote(rec) {
+    const key = process.env["COLTRANE_DRAIN_KEY"];
+    if (key) {
+        await drainViaPostgrest(rec, key);
+        return;
+    }
+    const pgConn = process.env["COLTRANE_DRAIN_PG"];
+    if (pgConn) {
+        await drainViaPg(rec, pgConn);
+        return;
+    }
+}
+async function drainViaPostgrest(rec, key) {
+    const base = (process.env["COLTRANE_DRAIN_URL"] ?? "").replace(/\/$/, "");
+    if (!base)
+        throw new Error("COLTRANE_DRAIN_KEY is set but COLTRANE_DRAIN_URL (project base) is missing");
+    // TIER 1 — the metadata+data row into `coltrane_outputs` (columns already exist in the schema).
+    const rowRes = await fetch(`${base}/rest/v1/coltrane_outputs`, {
+        method: "POST",
+        headers: {
+            apikey: key,
+            Authorization: `Bearer ${key}`,
+            "Content-Type": "application/json",
+            Prefer: "resolution=merge-duplicates,return=minimal",
+        },
+        body: JSON.stringify(drainBody(rec)),
+    });
+    if (!rowRes.ok)
+        throw new Error(`coltrane_outputs POST ${rowRes.status}`);
+    // TIER 2 — the payload artifact into Storage, content-addressed by sha (idempotent upsert).
+    const bucket = process.env["COLTRANE_DRAIN_BUCKET"] ?? "coltrane-artifacts";
+    const objectPath = `${rec.gig_id}/${rec.content_sha}.json`;
+    const artRes = await fetch(`${base}/storage/v1/object/${bucket}/${objectPath}`, {
+        method: "POST",
+        headers: {
+            apikey: key,
+            Authorization: `Bearer ${key}`,
+            "Content-Type": "application/json",
+            "x-upsert": "true",
+        },
+        body: JSON.stringify({ content_sha: rec.content_sha, id: rec.id, data: rec.data }),
+    });
+    // A duplicate object (already uploaded for this sha) is success, not failure.
+    if (!artRes.ok && artRes.status !== 409)
+        throw new Error(`storage POST ${artRes.status}`);
+}
+async function drainViaPg(rec, conn) {
+    // Guarded dynamic import — `pg` is intentionally NOT a declared dependency, so the string is
+    // indirected to keep tsc from resolving it, and any failure to load surfaces as a drain error
+    // (fire-and-forget at the call site) rather than a hard crash.
+    const moduleName = "pg";
+    let pg;
+    try {
+        pg = await import(moduleName);
+    }
+    catch {
+        throw new Error("COLTRANE_DRAIN_PG is set but the 'pg' driver is not installed — install it in the consuming " +
+            "deployment, or use COLTRANE_DRAIN_KEY (PostgREST) instead. OSS ships no pg dependency.");
+    }
+    const Client = pg.Client;
+    if (!Client)
+        throw new Error("'pg' loaded but exposes no Client");
+    const client = new Client({ connectionString: conn });
+    await client.connect();
+    try {
+        const b = drainBody(rec);
+        await client.query(`insert into coltrane_outputs
+         (id, gig_id, agent_slug, phase, primitive, domain_type, domain_type_version, domain, content_sha, data, input_shas, cost_usd, tokens_used, duration_ms, created_at)
+       values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15)
+       on conflict (id) do nothing`, [
+            b["id"], b["gig_id"], b["agent_slug"], b["phase"], b["primitive"], b["domain_type"],
+            b["domain_type_version"], b["domain"], b["content_sha"], JSON.stringify(b["data"]),
+            b["input_shas"], b["cost_usd"], b["tokens_used"], b["duration_ms"], b["created_at"],
+        ]);
+    }
+    finally {
+        await client.end();
+    }
+}
+/** The sink row, derived entirely from the run's own record (engine "complete" → sink "completed"). */
+export function gigHeaderBody(rec) {
+    const started = rec.started_at ? Date.parse(rec.started_at) : NaN;
+    const finished = rec.finished_at ? Date.parse(rec.finished_at) : NaN;
+    const duration = Number.isFinite(started) && Number.isFinite(finished) ? finished - started : null;
+    const tokens = rec.usage && (rec.usage.input_tokens !== undefined || rec.usage.output_tokens !== undefined)
+        ? (rec.usage.input_tokens ?? 0) + (rec.usage.output_tokens ?? 0)
+        : null;
+    const manifest = {};
+    if (rec.outputs_count !== undefined)
+        manifest["output_count"] = rec.outputs_count;
+    if (rec.error !== undefined)
+        manifest["error"] = rec.error;
+    return {
+        id: rec.gig_id,
+        standard_slug: rec.standard_slug,
+        status: rec.status === "complete" ? "completed" : rec.status,
+        genome_hash: rec.genome_hash ?? null,
+        run_fingerprint: rec.run_fingerprint ?? null,
+        started_at: rec.started_at ?? null,
+        completed_at: rec.finished_at ?? null,
+        total_cost_usd: rec.usage?.total_cost_usd ?? null,
+        total_tokens: tokens,
+        total_duration_ms: duration,
+        manifest,
+    };
+}
+/** Drain the header. Silent no-op when no drain credential is configured. */
+export async function drainGigHeader(rec) {
+    if (!remoteConfigured())
+        return;
+    const key = process.env["COLTRANE_DRAIN_KEY"];
+    if (key) {
+        const base = (process.env["COLTRANE_DRAIN_URL"] ?? "").replace(/\/$/, "");
+        if (!base)
+            throw new Error("COLTRANE_DRAIN_KEY is set but COLTRANE_DRAIN_URL (drain service base) is missing");
+        const res = await fetch(`${base}/rest/v1/coltrane_gigs`, {
+            method: "POST",
+            headers: {
+                apikey: key,
+                Authorization: `Bearer ${key}`,
+                "Content-Type": "application/json",
+                Prefer: "resolution=merge-duplicates,return=minimal",
+            },
+            body: JSON.stringify(gigHeaderBody(rec)),
+        });
+        if (!res.ok)
+            throw new Error(`coltrane_gigs POST ${res.status}`);
+        return;
+    }
+    const pgConn = process.env["COLTRANE_DRAIN_PG"];
+    if (pgConn) {
+        const moduleName = "pg";
+        const pg = (await import(moduleName));
+        if (!pg.Client)
+            throw new Error("'pg' loaded but exposes no Client");
+        const client = new pg.Client({ connectionString: pgConn });
+        await client.connect();
+        try {
+            const b = gigHeaderBody(rec);
+            await client.query(`insert into coltrane_gigs (id, standard_slug, status, genome_hash, run_fingerprint, started_at, completed_at, total_cost_usd, total_tokens, total_duration_ms, manifest)
+         values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
+         on conflict (id) do update set
+           standard_slug = excluded.standard_slug, status = excluded.status,
+           genome_hash = excluded.genome_hash, run_fingerprint = excluded.run_fingerprint,
+           started_at = excluded.started_at, completed_at = excluded.completed_at,
+           total_cost_usd = excluded.total_cost_usd, total_tokens = excluded.total_tokens,
+           total_duration_ms = excluded.total_duration_ms, manifest = excluded.manifest`, [
+                b["id"], b["standard_slug"], b["status"], b["genome_hash"], b["run_fingerprint"],
+                b["started_at"], b["completed_at"], b["total_cost_usd"], b["total_tokens"],
+                b["total_duration_ms"], JSON.stringify(b["manifest"]),
+            ]);
+        }
+        finally {
+            await client.end();
+        }
+    }
+}
+// TODO(scoped-credential): the remote tier expects an APPEND-ONLY credential — either a
+// per-consumer issued key (COLTRANE_DRAIN_KEY) whose grant is exactly "insert a coltrane_outputs
+// row + upload an artifact object" and nothing else, or a Postgres role (COLTRANE_DRAIN_PG)
+// scoped to INSERT on coltrane_outputs only. A service_role key MUST NOT be used here. Issuing
+// that scoped credential (a Supabase RLS insert policy for the key's role, and a Storage bucket
+// policy allowing upsert to the artifacts bucket) is deployment work that lives outside this OSS
+// repo; this module only consumes whichever env credential is present.
+//# sourceMappingURL=output_mirror.js.map

package/dist/src/output_mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output_mirror.js","sourceRoot":"","sources":["../../src/output_mirror.ts"],"names":[],"mappings":"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"}

package/dist/src/outputs.d.ts

@@ -1,4 +1,5 @@
 import type { Registry } from "./registry.js";
+import type { OutputMirror } from "./output_mirror.js";
 export declare const REF_RELATIONS: readonly ["derived_from", "validates", "challenges", "refines", "triggers", "contains"];
 export type RefRelation = (typeof REF_RELATIONS)[number];
 export interface OutputRecord {
@@ -96,6 +97,61 @@ export interface OutputWrite {
         cache_key: string;
     } | undefined;
 }
+/** The infix that separates a performance root from a movement id. Carries dots on BOTH sides so
+ *  it cannot occur in a bare uuid, and `.m` alone cannot be mistaken for it. */
+export declare const MOVEMENT_ID_INFIX = ".m.";
+/** A movement's gig id, from the performance's id and the movement's. */
+export declare function composeMovementGigId(gig_id: string, movement_id: string): string;
+/**
+ * The performance a gig id belongs to. A plain gig id is its own root.
+ *
+ * Split at the FIRST infix, not the last: `composeChart`'s R1 admits `[A-Za-z0-9._-]+` for a
+ * movement_id, so a movement may itself contain `.m.` — and only a first-occurrence split puts
+ * two siblings of one performance under the same root.
+ */
+export declare function performanceRoot(gig_id: string): string;
+/** Which movement a gig id names, or undefined when it names none (a plain gig, or a
+ *  degenerate chart, whose one movement runs under the performance's own id). */
+export declare function movementOfGigId(gig_id: string): string | undefined;
+/** Which way `trace` walks. `upstream` (the default) is the ancestor closure. */
+export type TraceDirection = "upstream" | "downstream" | "both";
+/**
+ * Where a traced record LIVED. Present only when there is something to say: a record sealed under
+ * a plain gig id, reached from a seed in that same gig, carries none of these — which is what
+ * keeps a single-standard gig's trace byte-identical to what it was before charts existed.
+ */
+export interface TraceLabels {
+    /** The movement whose gig sealed this record. Absent when its gig id names no movement. */
+    movement?: string | undefined;
+    /** The performance this record's gig belongs to. Absent when its gig id names no movement. */
+    performance_gig_id?: string | undefined;
+    /** Set when this node's gig_id differs from the seed's — the walk CROSSED a boundary to reach
+     *  it. Crossing is never silent: a consumer reads it off the node. */
+    crossed?: true | undefined;
+    /** Never set. The discriminant against `TraceMissingNode`. */
+    missing?: undefined;
+}
+/** A record the walk resolved, labelled with where it lived. */
+export type TraceRecordNode = OutputRecord & TraceLabels;
+/**
+ * A reference the chain makes and this store cannot resolve — the upstream movement drained
+ * remotely and was never local, or a row was lost.
+ *
+ * It is a NAMED terminal, never a dropped edge. Silently skipping it is the #248 defect exactly:
+ * the engine would report a SHORTER CHAIN as if it were the whole chain. The `content_sha` comes
+ * from the referring record's `input_shas` — engine-stamped at seal time, which is why the hole
+ * can be named rather than guessed at. It is `""` only when the reference carries no sha at all
+ * (a hand-authored `output_refs` edge, which records no hash).
+ */
+export interface TraceMissingNode {
+    /** The output id the chain referenced. */
+    id: string;
+    content_sha: string;
+    missing: true;
+    /** The record that referenced it — so an operator knows where the hole is. */
+    referenced_by: string;
+}
+export type TraceNode = TraceRecordNode | TraceMissingNode;
 export interface OutputRef {
     id: string;
     from_output_id: string;
@@ -155,9 +211,28 @@ export interface OutputStore {
     all(): readonly OutputRecord[];
     addRef(from_output_id: string, to_output_id: string, relation: RefRelation, primitive: string): OutputRef;
     refs(): readonly OutputRef[];
+    /**
+     * E6: walk the provenance graph from a seed record. Returns the reachable closure, cycle-safe,
+     * EXCLUDING the seed itself.
+     *
+     * `direction` — `upstream` (the default) follows `input_refs` plus `derived_from`/`refines`
+     * edges to the ancestors; `downstream` follows the reverse of `input_refs` to the descendants;
+     * `both` is their union, each node once.
+     *
+     * `max_depth` caps the walk at N hops from the seed. `0` returns nothing.
+     *
+     * SCOPE — the PERFORMANCE, not one gig and not the whole store. A movement's gig id is
+     * `<performance>.m.<movement>`, so the walk follows an edge into any gig of the same
+     * performance and LABELS the node with where it lived (`TraceLabels`). It refuses an edge into
+     * an unrelated gig: a hand-authored reference between two performances is out of family, and
+     * surfacing it would be the cross-gig leak PR #85 closed.
+     *
+     * A reference this store cannot resolve is returned as a `TraceMissingNode`, never dropped.
+     */
     trace(id: string, opts?: {
         max_depth?: number;
-    }): OutputRecord[];
+        direction?: TraceDirection;
+    }): TraceNode[];
     findings(): Finding[];
     coreTypeOf(typeSlug: string): string | null;
     /**
@@ -194,6 +269,7 @@ export interface OutputStore {
 }
 export interface OutputStoreOptions {
     persistDir?: string | undefined;
+    mirror?: OutputMirror | undefined;
 }
 export declare function defaultOutputsPersistDir(): string;
 export declare function createOutputStore(registry: Registry, options?: OutputStoreOptions): OutputStore;