@eir-labs/coltrane 0.4.0

package/dist/src/ledger.d.ts

@@ -0,0 +1,225 @@
+export interface GigUsage {
+    input_tokens: number;
+    output_tokens: number;
+    total_cost_usd: number;
+    /** actual model id → its spend (the model that ran, not just the configured tier). */
+    by_model: Record<string, {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    }>;
+    /** Model invocations this gig STARTED (skill-backed chairs run no model and are not counted). */
+    invocations?: number;
+    /** Of those, how many produced no usable usage payload. Their spend is UNKNOWN, not zero. */
+    unattributed_invocations?: number;
+    /** Set ONLY when unattributed_invocations > 0: the scalars above are a LOWER BOUND. */
+    partial?: true;
+    /** Set ONLY when ≥1 attributed invocation carried no `modelUsage` breakdown: `by_model` does
+     *  not account for the whole of `total_cost_usd` and is itself a LOWER BOUND. */
+    by_model_partial?: true;
+}
+/**
+ * The ledger records three classes of event, not one (#212).
+ *
+ * v1 modelled exactly one — *a gig finished* — so every other event class was smuggled into
+ * that shape: the event kind stuffed into `standard_slug`, the event class into a `:`-prefix
+ * on `gig_id`, and the sentinel `"n/a"` into the identity fields, with the payload dropped
+ * entirely. Seven of twelve append sites wrote `"n/a"`.
+ *
+ * The discriminated union makes that unrepresentable rather than merely discouraged:
+ * `genome_hash`/`run_fingerprint` exist ONLY on `kind:"gig"`, so there is nowhere to put a
+ * sentinel on a promotion or an abort.
+ */
+export type LedgerEntryKind = "gig" | "genome_mutation" | "governance";
+export declare const LEDGER_SCHEMA_VERSION = 2;
+interface LedgerEntryBase {
+    schema_version: typeof LEDGER_SCHEMA_VERSION;
+    /** This ROW's identity. v1 overloaded `gig_id` for it, which is why non-gig rows needed a
+     *  synthetic `promote:<uuid>` / `abort:<gid>` namespace. */
+    entry_id: string;
+    kind: LedgerEntryKind;
+    output_hashes: readonly string[];
+    started_at: string;
+    finished_at: string;
+    /** Set ONLY by the read-side v1 upgrade. Without this marker the upgrade would launder a
+     *  known gap into apparent completeness — the same class of dishonesty as `"n/a"` itself. */
+    legacy?: true;
+    /**
+     * WHO asked for this. Optional, caller-supplied, and **provenance only**.
+     *
+     * The ledger already answers *what produced this and from what* — `content_sha`,
+     * `input_shas`, `skill_provenance`, `genome_hash`, `run_fingerprint`. It answered *who
+     * initiated it* nowhere. `principal` is the same category of fact as the rest of that list,
+     * which is the whole reason it sits on the base rather than on one arm: a run, a genome
+     * mutation, and a governance act can each have an initiator.
+     *
+     * **This is NOT an access control, and must not be read as one.** The engine records it and
+     * never looks at it: it is deliberately absent from `LedgerQuery`, no read handler consults
+     * it, and nothing filters on it. That is the architecture, not an oversight —
+     * `src/hooks.ts:1-9` states the engine provides "ONLY these types + the loop… ZERO built-in
+     * hooks… Everything opinionated lives in the wrapper." Tenancy enforcement is the consumer's
+     * job. If you are here because you want rows scoped by principal, that scoping belongs in
+     * the wrapper reading the ledger, not in the engine writing it.
+     *
+     * Landed inside the v1→v2 bump precisely because it is free here: additive, unset by every
+     * current call site, and needing no new upgrade arm. Adding it after v2 shipped would have
+     * cost a `schema_version: 3` and a second arm in `upgradeV1` for a purely additive field.
+     */
+    principal?: string;
+}
+/** A run completed. The only class that carries reproducibility identity. */
+export interface GigLedgerEntry extends LedgerEntryBase {
+    kind: "gig";
+    gig_id: string;
+    standard_slug: string;
+    genome_hash: string;
+    run_fingerprint: string;
+    usage?: GigUsage;
+}
+/** A definition entered the substrate. Identity is the canonical hash chain, NOT a run
+ *  fingerprint — src/genome_writer.ts used to copy `effective_hash` into both, which was a
+ *  small lie: an effective hash is not a run fingerprint. */
+export interface GenomeMutationLedgerEntry extends LedgerEntryBase {
+    kind: "genome_mutation";
+    /** agent_define | agent_evolve | standard_compose | type_register | type_extend | skill_define */
+    event: string;
+    /** WHICH definition was sealed. v1 buried this in a `:`-delimited gig_id. */
+    subject_slug: string;
+    content_hash: string;
+    dependency_hash?: string;
+    effective_hash: string;
+}
+/** A governance act: a promotion, a registration, a review, a proposal, an abort. */
+export interface GovernanceLedgerEntry extends LedgerEntryBase {
+    kind: "governance";
+    event: string;
+    /** WHICH entity the act was about — the promoted slug, the registered tool, the reviewed
+     *  agent. v1 recorded none of these. */
+    subject_slug: string;
+    /** The real gig this act concerns (an abort, a review). First-class so `query({subject_gig_id})`
+     *  answers "what happened to gig X" — v1 filed aborts under a synthetic `abort:<gid>` that
+     *  exact-equality filtering could never return (#213). */
+    subject_gig_id?: string;
+    /** The payload. v1 dropped it entirely, leaving a durable trail of content-free UUIDs. */
+    detail?: Record<string, unknown>;
+}
+export type LedgerEntry = GigLedgerEntry | GenomeMutationLedgerEntry | GovernanceLedgerEntry;
+export interface LedgerQuery {
+    kind?: LedgerEntryKind;
+    event?: string;
+    subject_slug?: string;
+    subject_gig_id?: string;
+    gig_id?: string;
+    standard_slug?: string;
+    genome_hash?: string;
+    effective_hash?: string;
+    after?: string;
+    before?: string;
+}
+/** One damaged line, located. Skip-and-REPORT: silently dropping a row would let corruption
+ *  hide an entry, which is the wrong remedy for an audit trail (contrast src/outputs.ts:180-184). */
+export interface LedgerCorruption {
+    line_no: number;
+    reason: string;
+    preview: string;
+}
+export interface LedgerIntegrityReport {
+    ok: boolean;
+    path: string;
+    entries: number;
+    corrupt: LedgerCorruption[];
+}
+/** Filters that can only ever match a gig row: the discriminator itself, or a field that
+ *  exists solely on the gig arm. Narrowing on these is what lets `query({gig_id})[0].usage`
+ *  type-check without a cast at every read site. */
+export type GigOnlyQuery = (LedgerQuery & {
+    kind: "gig";
+}) | (LedgerQuery & {
+    gig_id: string;
+}) | (LedgerQuery & {
+    standard_slug: string;
+}) | (LedgerQuery & {
+    genome_hash: string;
+});
+export interface Ledger {
+    append(entry: LedgerEntry): void;
+    query(filter?: LedgerQuery): LedgerEntry[];
+    count(filter?: LedgerQuery): number;
+    /**
+     * #255 — is this audit trail whole, and if not, where is the damage.
+     *
+     * On the INTERFACE deliberately. `FileLedger` had it as a class method only, so a
+     * consumer holding a `Ledger` could not ask the question without narrowing — which is
+     * why tests/ledger_integrity.test.ts had to cast through `Record<string, unknown>` to
+     * reach it, and why `system_health` surfaced nothing. An audit trail that cannot be
+     * asked whether it is intact is not an audit trail.
+     *
+     * Every implementation answers, including one that cannot tear: "in-memory, so there is
+     * nothing to corrupt" is an ANSWER. A missing method is a gap, and gaps get assumed away.
+     */
+    integrity(): LedgerIntegrityReport;
+}
+export declare class LedgerError extends Error {
+}
+export declare const isGig: (e: LedgerEntry) => e is GigLedgerEntry;
+export declare const isGenomeMutation: (e: LedgerEntry) => e is GenomeMutationLedgerEntry;
+export declare const isGovernance: (e: LedgerEntry) => e is GovernanceLedgerEntry;
+/**
+ * Resolve the ledger file. `COLTRANE_LEDGER_PATH` wins; otherwise `<root>/.coltrane/ledger.jsonl`.
+ *
+ * Genome-scoped, deliberately NOT `$HOME`-global like `defaultOutputsPersistDir` (#210): a
+ * `genome_hash` is only meaningful relative to a genome and `standard_slug` is not namespaced,
+ * so a global ledger would interleave rows from every genome the operator has ever run and
+ * `query({standard_slug})` would return unrelated genomes' runs as one history. Outputs
+ * tolerate a global root only because they are sharded into per-gig_id files.
+ * `.gitignore` already carries `.coltrane/`.
+ */
+export declare function defaultLedgerPath(root?: string): string;
+/**
+ * THE shared validator. Both implementations call this; the duplicated guard triplet it
+ * replaces (v1 `src/ledger.ts:56-58` and `:102-104`) is how the MemoryLedger/FileLedger
+ * immutability divergence in #214 crept in unnoticed.
+ */
+export declare function validateEntry(entry: LedgerEntry): void;
+export declare class FileLedger implements Ledger {
+    private readonly path;
+    constructor(path: string);
+    append(entry: LedgerEntry): void;
+    /** Single read pass shared by query / count / integrity, so the three can never disagree
+     *  about what the file contains (v1 `count()` never parsed, so it reported a healthy total
+     *  for a ledger `query()` could not open). */
+    private read;
+    query(filter: GigOnlyQuery): GigLedgerEntry[];
+    query(filter: LedgerQuery & {
+        kind: "genome_mutation";
+    }): GenomeMutationLedgerEntry[];
+    query(filter: LedgerQuery & {
+        kind: "governance";
+    }): GovernanceLedgerEntry[];
+    query(filter?: LedgerQuery): LedgerEntry[];
+    count(filter?: LedgerQuery): number;
+    /**
+     * Skip-and-REPORT. A silent skip (the src/outputs.ts:180-184 shape) is the wrong remedy for
+     * an audit trail: it lets a single corrupted byte delete a row with no trace. `query()`
+     * keeps serving the intact rows; this is how an operator learns the ledger is damaged.
+     */
+    integrity(): LedgerIntegrityReport;
+}
+export declare class MemoryLedger implements Ledger {
+    private readonly entries;
+    constructor();
+    append(entry: LedgerEntry): void;
+    query(filter: GigOnlyQuery): GigLedgerEntry[];
+    query(filter: LedgerQuery & {
+        kind: "genome_mutation";
+    }): GenomeMutationLedgerEntry[];
+    query(filter: LedgerQuery & {
+        kind: "governance";
+    }): GovernanceLedgerEntry[];
+    query(filter?: LedgerQuery): LedgerEntry[];
+    count(filter?: LedgerQuery): number;
+    /** Nothing is parsed from bytes here, so there is no torn-line failure mode to report.
+     *  `path` is empty because there is no file — not because we failed to find one. */
+    integrity(): LedgerIntegrityReport;
+}
+export {};

package/dist/src/ledger.js

@@ -0,0 +1,306 @@
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const LEDGER_SCHEMA_VERSION = 2;
+/** sha256, lowercase — what canonical_form actually emits (src/canonical_form.ts:29-31). */
+const HEX64 = /^[0-9a-f]{64}$/;
+export class LedgerError extends Error {
+}
+// Narrowing helpers for consumers holding the `Ledger` interface (whose query() returns the
+// union). The concrete classes narrow via overload; these cover the interface-typed path.
+export const isGig = (e) => e.kind === "gig";
+export const isGenomeMutation = (e) => e.kind === "genome_mutation";
+export const isGovernance = (e) => e.kind === "governance";
+/**
+ * Resolve the ledger file. `COLTRANE_LEDGER_PATH` wins; otherwise `<root>/.coltrane/ledger.jsonl`.
+ *
+ * Genome-scoped, deliberately NOT `$HOME`-global like `defaultOutputsPersistDir` (#210): a
+ * `genome_hash` is only meaningful relative to a genome and `standard_slug` is not namespaced,
+ * so a global ledger would interleave rows from every genome the operator has ever run and
+ * `query({standard_slug})` would return unrelated genomes' runs as one history. Outputs
+ * tolerate a global root only because they are sharded into per-gig_id files.
+ * `.gitignore` already carries `.coltrane/`.
+ */
+export function defaultLedgerPath(root) {
+    const override = process.env["COLTRANE_LEDGER_PATH"];
+    if (override && override.length > 0)
+        return override;
+    return join(root ?? process.cwd(), ".coltrane", "ledger.jsonl");
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+function requireHex(row, field, kind) {
+    const v = row[field];
+    if (typeof v !== "string" || !HEX64.test(v)) {
+        throw new LedgerError(`${kind} entry requires ${field} to be 64 lowercase hex (sha256); got ${JSON.stringify(v)}. ` +
+            "Non-emptiness was the v1 guard, and it is exactly what let 7 call sites write \"n/a\".");
+    }
+}
+/** Gig identity on a non-gig row is not "discouraged", it is invalid — that is what makes the
+ *  sentinel unrepresentable rather than merely absent by convention. */
+function rejectGigIdentity(row, kind) {
+    for (const field of ["genome_hash", "run_fingerprint"]) {
+        if (row[field] !== undefined) {
+            throw new LedgerError(`${kind} entry must not carry ${field} — reproducibility identity is gig-only. ` +
+                "A promotion is not a run.");
+        }
+    }
+}
+/**
+ * THE shared validator. Both implementations call this; the duplicated guard triplet it
+ * replaces (v1 `src/ledger.ts:56-58` and `:102-104`) is how the MemoryLedger/FileLedger
+ * immutability divergence in #214 crept in unnoticed.
+ */
+export function validateEntry(entry) {
+    const row = entry;
+    const kind = row["kind"];
+    if (kind !== "gig" && kind !== "genome_mutation" && kind !== "governance") {
+        throw new LedgerError(`ledger entry requires kind ∈ {gig, genome_mutation, governance}; got ${JSON.stringify(kind)}`);
+    }
+    if (!isNonEmptyString(row["entry_id"]))
+        throw new LedgerError("ledger entry requires entry_id");
+    if (!isNonEmptyString(row["started_at"]))
+        throw new LedgerError("ledger entry requires started_at");
+    if (!isNonEmptyString(row["finished_at"]))
+        throw new LedgerError("ledger entry requires finished_at");
+    if (!Array.isArray(row["output_hashes"]))
+        throw new LedgerError("ledger entry requires output_hashes");
+    if (kind === "gig") {
+        if (!isNonEmptyString(row["gig_id"]))
+            throw new LedgerError("gig entry requires gig_id");
+        if (!isNonEmptyString(row["standard_slug"]))
+            throw new LedgerError("gig entry requires standard_slug");
+        requireHex(row, "genome_hash", "gig");
+        requireHex(row, "run_fingerprint", "gig");
+        return;
+    }
+    if (!isNonEmptyString(row["event"]))
+        throw new LedgerError(`${kind} entry requires event`);
+    if (!isNonEmptyString(row["subject_slug"])) {
+        throw new LedgerError(`${kind} entry requires subject_slug — WHICH entity the event was about. ` +
+            "v1 recorded a bare UUID and no subject at all.");
+    }
+    rejectGigIdentity(row, kind);
+    if (kind === "genome_mutation") {
+        requireHex(row, "content_hash", "genome_mutation");
+        requireHex(row, "effective_hash", "genome_mutation");
+    }
+}
+/** Deep copy, so neither implementation hands out a live reference (#214). */
+function freezeCopy(entry) {
+    return structuredClone(entry);
+}
+function matches(entry, filter) {
+    const e = entry;
+    if (filter.kind && e["kind"] !== filter.kind)
+        return false;
+    if (filter.event && e["event"] !== filter.event)
+        return false;
+    if (filter.subject_slug && e["subject_slug"] !== filter.subject_slug)
+        return false;
+    if (filter.subject_gig_id && e["subject_gig_id"] !== filter.subject_gig_id)
+        return false;
+    if (filter.gig_id && e["gig_id"] !== filter.gig_id)
+        return false;
+    if (filter.standard_slug && e["standard_slug"] !== filter.standard_slug)
+        return false;
+    if (filter.genome_hash && e["genome_hash"] !== filter.genome_hash)
+        return false;
+    if (filter.effective_hash && e["effective_hash"] !== filter.effective_hash)
+        return false;
+    if (filter.after && String(e["started_at"]) < filter.after)
+        return false;
+    if (filter.before && String(e["started_at"]) > filter.before)
+        return false;
+    return true;
+}
+// ── v1 read-side upgrade ────────────────────────────────────────────────────
+// v1 rows are upgraded to the v2 VIEW on read. The file is NEVER rewritten: an append-only
+// ledger that silently self-heals is indistinguishable from one that was tampered with.
+/** v1 governance rows keyed `standard_slug` to the MCP tool name. */
+const V1_GOVERNANCE_EVENTS = new Set([
+    "charter_suggest_update", "proposal_create", "gig_abort", "tool_register",
+    "agent_promote", "standard_promote", "skill_promote",
+    "session_review_write", "learning_synthesize",
+]);
+const V1_MUTATION_EVENTS = new Set([
+    "agent_define", "agent_evolve", "standard_compose",
+    "type_register", "type_extend", "skill_define",
+]);
+function upgradeV1(row) {
+    const event = typeof row["standard_slug"] === "string" ? row["standard_slug"] : "";
+    const gig_id = typeof row["gig_id"] === "string" ? row["gig_id"] : "";
+    const started_at = typeof row["started_at"] === "string" ? row["started_at"] : "";
+    // NOTE: `principal` is deliberately left undefined here. A v1 row genuinely has no
+    // principal — the field did not exist when it was written — and inventing one (from a
+    // process owner, an env var, "unknown") would fabricate provenance, which is exactly the
+    // dishonesty `legacy: true` exists to prevent. Absent means absent.
+    const base = {
+        schema_version: LEDGER_SCHEMA_VERSION,
+        entry_id: gig_id,
+        output_hashes: Array.isArray(row["output_hashes"]) ? row["output_hashes"] : [],
+        started_at,
+        finished_at: typeof row["finished_at"] === "string" ? row["finished_at"] : started_at,
+        legacy: true,
+    };
+    if (V1_GOVERNANCE_EVENTS.has(event)) {
+        // `abort:<gid>` is the only v1 governance namespace whose subject is recoverable. The
+        // rest genuinely recorded nothing — leaving subject_slug absent is the honest result, and
+        // `legacy: true` is what says so.
+        const subject_gig_id = gig_id.startsWith("abort:") ? gig_id.slice("abort:".length) : undefined;
+        return {
+            ...base, kind: "governance", event,
+            ...(subject_gig_id ? { subject_gig_id } : {}),
+        };
+    }
+    if (V1_MUTATION_EVENTS.has(event)) {
+        const gh = row["genome_hash"];
+        const oh = base.output_hashes;
+        return {
+            ...base, kind: "genome_mutation", event,
+            ...(typeof gh === "string" && HEX64.test(gh) ? { effective_hash: gh } : {}),
+            ...(typeof oh[0] === "string" && HEX64.test(oh[0]) ? { content_hash: oh[0] } : {}),
+        };
+    }
+    // A real run. Identity is carried forward verbatim — never fabricated, never "n/a".
+    const gh = row["genome_hash"];
+    const rf = row["run_fingerprint"];
+    return {
+        ...base, kind: "gig", gig_id,
+        standard_slug: event,
+        ...(typeof gh === "string" && gh !== "n/a" ? { genome_hash: gh } : {}),
+        ...(typeof rf === "string" && rf !== "n/a" ? { run_fingerprint: rf } : {}),
+        ...(row["usage"] ? { usage: row["usage"] } : {}),
+    };
+}
+/** Parse one JSONL line into a v2 row view, or explain why it cannot be. */
+function parseLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch (e) {
+        return { reason: `unparseable JSON: ${e.message}` };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        // `42` and `null` parse fine and would otherwise be handed to execution_history_read as
+        // an "execution" — src/ledger.ts:79 was an unchecked cast.
+        return { reason: `line is ${parsed === null ? "null" : typeof parsed}, not a ledger row` };
+    }
+    const row = parsed;
+    if (row["kind"] === undefined && row["schema_version"] === undefined) {
+        return { entry: upgradeV1(row) };
+    }
+    return { entry: row };
+}
+// Both implementations expose their methods as bound arrow properties rather than prototype
+// methods. `deps.ledger.query` is routinely passed around and destructured, and a detached
+// `const q = ledger.query; q(...)` would otherwise throw on `this` — a footgun with no upside
+// for an object that is always used as a service handle, never as a prototype.
+export class FileLedger {
+    path;
+    constructor(path) {
+        this.path = path;
+        // Bound so a detached `const q = ledger.query; q(...)` works. `deps.ledger` is a service
+        // handle that gets passed around and destructured, never used as a prototype.
+        this.append = this.append.bind(this);
+        this.query = this.query.bind(this);
+        this.count = this.count.bind(this);
+        this.integrity = this.integrity.bind(this);
+        // NOTE: no eager mkdir. bootstrapServerDeps() with no root resolves to process.cwd(), so
+        // constructing the production ledger must not seed `.coltrane/` into the developer's
+        // checkout just because something built a ServerDeps. The directory is created on the
+        // first append instead.
+    }
+    append(entry) {
+        validateEntry(entry);
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            appendFileSync(this.path, JSON.stringify(entry) + "\n");
+        }
+        catch (e) {
+            // Wrap raw fs failures (EACCES / EPERM / EROFS / ENOSPC) in a typed
+            // LedgerError so callers see a structured error, not a leaking SystemError.
+            // The append is stateless — once the path is writable again, a retry on the
+            // same instance succeeds (no cached fd to reset).
+            const sys = e;
+            const err = new LedgerError(`failed to append to ledger at ${this.path}: ${sys.message}`);
+            err.cause = e;
+            if (sys.code !== undefined)
+                err.code = sys.code;
+            throw err;
+        }
+    }
+    /** Single read pass shared by query / count / integrity, so the three can never disagree
+     *  about what the file contains (v1 `count()` never parsed, so it reported a healthy total
+     *  for a ledger `query()` could not open). */
+    read() {
+        const entries = [];
+        const corrupt = [];
+        if (!existsSync(this.path))
+            return { entries, corrupt };
+        const lines = readFileSync(this.path, "utf-8").split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const raw = lines[i];
+            // `.trim()`, not `.length > 0` — a lone `\r` from a CRLF file is length 1 and would
+            // otherwise reach JSON.parse (contrast the v1 filter).
+            const line = raw.trim();
+            if (line.length === 0)
+                continue;
+            const { entry, reason } = parseLine(line);
+            if (entry)
+                entries.push(entry);
+            else
+                corrupt.push({ line_no: i + 1, reason: reason ?? "unreadable", preview: line.slice(0, 120) });
+        }
+        return { entries, corrupt };
+    }
+    query(filter = {}) {
+        return this.read().entries.filter((e) => matches(e, filter));
+    }
+    count(filter = {}) {
+        return this.read().entries.filter((e) => matches(e, filter)).length;
+    }
+    /**
+     * Skip-and-REPORT. A silent skip (the src/outputs.ts:180-184 shape) is the wrong remedy for
+     * an audit trail: it lets a single corrupted byte delete a row with no trace. `query()`
+     * keeps serving the intact rows; this is how an operator learns the ledger is damaged.
+     */
+    integrity() {
+        const { entries, corrupt } = this.read();
+        return { ok: corrupt.length === 0, path: this.path, entries: entries.length, corrupt };
+    }
+}
+export class MemoryLedger {
+    entries = [];
+    constructor() {
+        this.append = this.append.bind(this);
+        this.query = this.query.bind(this);
+        this.count = this.count.bind(this);
+        // #255 — bound like its siblings. The class comment promises BOTH implementations expose
+        // bound methods so a detached `const { integrity } = ledger` cannot throw; FileLedger
+        // binds it and this did not, so destructuring it here died on `this.entries`.
+        this.integrity = this.integrity.bind(this);
+    }
+    append(entry) {
+        validateEntry(entry);
+        // Clone IN: v1 pushed the caller's object, so a caller that reused or mutated an entry
+        // after append() silently rewrote sealed history (#214).
+        this.entries.push(freezeCopy(entry));
+    }
+    query(filter = {}) {
+        // Clone OUT: v1 returned live references, so `ledger.query()[0].genome_hash = "forged"`
+        // rewrote history in place. FileLedger was immune only by accident of serialization —
+        // the two implementations of one interface had different immutability semantics.
+        return this.entries.filter((e) => matches(e, filter)).map(freezeCopy);
+    }
+    count(filter = {}) {
+        return this.entries.filter((e) => matches(e, filter)).length;
+    }
+    /** Nothing is parsed from bytes here, so there is no torn-line failure mode to report.
+     *  `path` is empty because there is no file — not because we failed to find one. */
+    integrity() {
+        return { ok: true, path: "", entries: this.entries.length, corrupt: [] };
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/src/ledger.js.map

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

package/dist/src/loader.d.ts

@@ -0,0 +1,87 @@
+import { type Agent, type AgentDef, type Standard, type PhaseDef } from "./composition.js";
+import { type SkillOutput, type EvalOutput, type DomainTypeOutput } from "./genome_schema.js";
+export interface CoreTypeRecord {
+    slug: string;
+    primitive: string;
+    description: string;
+    schema: object;
+}
+export type DomainTypeRecord = DomainTypeOutput;
+export type AgentFileDef = AgentDef;
+export interface StandardFileDef {
+    slug: string;
+    domain: string;
+    agent_slugs: readonly string[];
+    phases: readonly PhaseDef[];
+    eval_slugs?: readonly string[];
+    input_types?: readonly string[];
+    output_types?: readonly string[];
+    max_examine_rounds?: number;
+    description?: string;
+}
+export type SkillRecord = SkillOutput & {
+    package_dir?: string;
+    code_hash?: string | null;
+    text?: string;
+    body?: string;
+};
+export type EvalRecord = EvalOutput;
+export interface LoadError {
+    readonly kind: "domain_type" | "agent" | "standard" | "skill" | "eval" | "manifest";
+    readonly path: string;
+    readonly slug: string | null;
+    readonly error: string;
+}
+export interface LoadedGenome {
+    core_types: ReadonlyMap<string, CoreTypeRecord>;
+    domain_types: ReadonlyMap<string, DomainTypeRecord>;
+    agents: ReadonlyMap<string, Agent>;
+    standards: Map<string, Standard>;
+    skills: Map<string, SkillRecord>;
+    evals: Map<string, EvalRecord>;
+    load_errors: LoadError[];
+    provenance?: ReadonlyMap<string, string>;
+}
+export declare class GenomeLoadError extends Error {
+}
+export declare function loadGenome(root: string, opts?: {
+    inheritedAgents?: ReadonlyMap<string, Agent>;
+    /** Set by loadLayeredGenome: defer the dangling-skill-binding post-pass to after the
+     *  fold, so a base agent binding a skill the consumer layer supplies isn't false-flagged. */
+    deferSkillBindingCheck?: boolean;
+}): LoadedGenome;
+/**
+ * Resolve a LAYERED genome from a stack of roots, lowest → highest (genome extension
+ * Phase 2 — docs/genome-extension.md). Each root is loaded as a normal genome, then
+ * folded so a higher layer's definitions OVERRIDE a lower layer's by slug, per class.
+ * A consumer extends a base by passing [baseRoot, consumerRoot]: it inherits the base,
+ * adds its own, and overrides where it specializes. `provenance` records which layer
+ * supplied each effective definition. core_types are the immutable 6 (every layer
+ * provides them, seeded or on-disk); the top layer's are used.
+ */
+export declare function loadLayeredGenome(roots: readonly string[]): LoadedGenome;
+/**
+ * Manifest-aware genome load (genome extension Phase 2 — opt-in). A genome root may
+ * declare the base(s) it extends in a `genome.json` manifest: `{ "extends": [<path>] }`
+ * (absolute, or relative to that root). resolveGenome walks the extends chain, flattens
+ * it to a layer stack (bases first, this root last, deduped + cycle-guarded), and resolves
+ * it via loadLayeredGenome. No manifest → a plain single-root load. This is what the
+ * running server (bootstrapServerDeps) calls, so a downstream consumer's declared base
+ * is honored automatically.
+ */
+export declare function resolveGenome(root: string): LoadedGenome;
+/**
+ * Genome cascade check (genome extension Phase 3 — docs/genome-extension.md). Given a
+ * consumer genome and two base versions (`fromBase` it currently validates against,
+ * `toBase` a candidate), report what in the CONSUMER layer breaks when the base advances
+ * — e.g. a consumer standard that composes a base player the new base removed/renamed.
+ *
+ * `broken` = consumer-layer load_errors present against toBase but NOT fromBase (the
+ * base change broke them). `healed` = the inverse (informational). Lets a consumer
+ * decide whether to adopt a new base before pinning to it.
+ */
+export interface CascadeReport {
+    broken: LoadError[];
+    healed: LoadError[];
+}
+export declare function genomeCascadeCheck(consumerRoot: string, fromBase: string, toBase: string): CascadeReport;