@eir-labs/coltrane 0.4.0

package/dist/src/mcp.js

@@ -0,0 +1,125 @@
+import { zodToMcpProps, AgentSchema, StandardSchema, SkillSchema, DomainTypeSchema } from "./genome_schema.js";
+// A property value is either a bare JSON-schema type name (the common case) or a full schema
+// fragment — needed for fields that are honestly nullable, e.g. a measurement the engine has no
+// data to compute (#238). Declaring those as plain "number" is the same lie as returning 1.0.
+const obj = (props) => ({
+    type: "object",
+    properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, typeof v === "string" ? { type: v } : v])),
+});
+const nullable = (type) => ({ type: [type, "null"] });
+// Select named fields from a generated prop map (preserving their derived JSON types).
+const pickProps = (src, keys) => Object.fromEntries(keys.filter((k) => src[k] !== undefined).map((k) => [k, src[k]]));
+// type_register's surface is the AUTHORED projection of DomainTypeSchema (the single source) — field
+// types are generated, so they can't drift from the schema; version/status are server-assigned (not
+// authored), and `reason` is approval metadata. (type_extend is an extension DELTA — fields_to_add is
+// not a restatement of the type record — so there's nothing to derive there.)
+const DT_AUTHORED = pickProps(zodToMcpProps(DomainTypeSchema), ["slug", "extends", "domain", "schema", "required_fields"]);
+export const MCP_TOOLS = [
+    { slug: "type_resolve", category: "understand", input_schema: obj({ core_type: "string", domain: "string", semantic_description: "string", required_fields: "array" }), output_schema: obj({ action: "string", candidates: "array", recommendation: "object" }) },
+    { slug: "type_browse", category: "understand", input_schema: obj({ domain: "string", extends: "string", min_usage: "number", status: "string" }), output_schema: obj({ types: "array", stats: "object" }) },
+    { slug: "tool_registry_browse", category: "understand", input_schema: obj({ category: "string", usage_min: "number", unused_since: "string" }), output_schema: obj({ tools: "array", usage_stats: "array", dependency_map: "object" }) },
+    { slug: "output_query", category: "understand", input_schema: obj({ domain_type: "string", gig_id: "string", agent_slug: "string", data_filter: "object" }), output_schema: obj({ outputs: "array", total_count: "number" }) },
+    { slug: "output_trace", category: "understand", input_schema: obj({ output_id: "string", direction: "string", max_depth: "number" }), output_schema: obj({ graph: "object", root_signals: "array", terminal_outputs: "array" }) },
+    { slug: "charter_read", category: "understand", input_schema: obj({ company_id: "string" }), output_schema: obj({ products: "array", goals: "array", pain_points: "array", tech_stack: "array", access_grants: "array" }) },
+    // #217 — advertised contract == handler. The five filters src/server.ts actually reads, and
+    // the two keys it actually returns. The old {company_id, domain} in / {gigs,
+    // performance_summary} out overlapped the handler in neither direction, so a client
+    // following the surface got an UNFILTERED DUMP of the audit trail and then looked for a key
+    // that was never returned.
+    { slug: "execution_history_read", category: "understand", input_schema: obj({ gig_id: "string", standard_slug: "string", genome_hash: "string", after: "string", before: "string" }), output_schema: obj({ executions: "array", count: "number" }) },
+    { slug: "access_grant_check", category: "understand", input_schema: obj({ company_id: "string", resource_uri: "string", required_permissions: "array" }), output_schema: obj({ granted: "boolean", missing_permissions: "array", expires_in: "number" }) },
+    { slug: "type_register", category: "build", input_schema: obj({ ...DT_AUTHORED, reason: "string" }), output_schema: obj({ registered: "boolean", domain_type_id: "string", version: "number" }) },
+    { slug: "type_extend", category: "build", input_schema: obj({ slug: "string", domain: "string", fields_to_add: "object", reason: "string" }), output_schema: obj({ new_version: "number", changelog_entry: "string" }) },
+    { slug: "agent_define", category: "build", input_schema: obj(zodToMcpProps(AgentSchema)), output_schema: obj({ agent_profile_id: "string", validation_result: "object" }) },
+    { slug: "agent_evolve", category: "build", input_schema: obj({ slug: "string", changes: "object", reason: "string", evidence: "object" }), output_schema: obj({ new_version: "number", cascade_check: "object" }) },
+    { slug: "standard_compose", category: "build", input_schema: obj(zodToMcpProps(StandardSchema)), output_schema: obj({ standard_id: "string", validation_result: "object" }) },
+    // #239 — `basis`/`sample_size` say WHERE the estimate came from (a measured mean of real runs,
+    // the standard's real structure, or a per-slug guess). estimated_duration_ms is the key the
+    // handler actually returns; the old `estimated_duration` was never present on a response.
+    { slug: "standard_simulate", category: "build", input_schema: obj({ standard_slug: "string", mock_input: "object", depth: "string" }), output_schema: obj({ phases: "array", estimated_cost: "number", estimated_duration_ms: "number", basis: "string", sample_size: "number" }) },
+    // #237 — `depth` is read now (and rejected when unrecognized); the response echoes the depth
+    // the run actually took, so "I ran a cheap iteration" is verifiable rather than assumed.
+    { slug: "gig_dispatch", category: "run", input_schema: obj({ standard_slug: "string", input: "object", depth: "string", company_id: "string", wait: "boolean" }), output_schema: obj({ gig_id: "string", status: "string", depth: "string", manifest: "object" }) },
+    { slug: "gig_monitor", category: "run", input_schema: obj({ gig_id: "string" }), output_schema: obj({ status: "string", phases_complete: "number", current_phase: "string", chairs: "array", outputs_so_far: "array" }) },
+    { slug: "gig_logs", category: "understand", input_schema: obj({ gig_id: "string", role: "string", type: "string", tail: "number" }), output_schema: obj({ gig_id: "string", roles: "array", count: "number", events: "array" }) },
+    // #251 — `status` is the field both existing tests actually assert and it was not advertised.
+    // `aborted` now means "this call delivered a cancellation to a live run", not "we looked at
+    // the stores and guessed"; `cancellable` says whether this server could reach the run at all.
+    { slug: "gig_abort", category: "run", input_schema: obj({ gig_id: "string", reason: "string" }), output_schema: obj({ status: "string", aborted: "boolean", cancellable: "boolean", cleanup_result: "object" }) },
+    { slug: "output_write", category: "run", input_schema: obj({ core_type: "string", domain_type: "string", data: "object", input_refs: "array", refs: "array" }), output_schema: obj({ output_id: "string", validation_result: "object" }) },
+    { slug: "agent_validate_pipeline", category: "improve", input_schema: obj({ agents: "array", standard_slug: "string" }), output_schema: obj({ valid: "boolean", graph: "object", unsatisfied_inputs: "array", illegal_progressions: "array" }) },
+    // #238 — success_rate and trend are NULLABLE, because the engine genuinely cannot compute
+    // them (a failed gig writes no ledger row, so the denominator does not exist) and a hardcoded
+    // 1.0 is a fabricated measurement presented as a measurement. The `*_basis` strings say why.
+    // `cost_usd` is real settled spend off the gig rows (#195), not an output count.
+    { slug: "health_check", category: "improve", input_schema: obj({ entity_type: "string", kind: "string", slug: "string", window: "string" }), output_schema: obj({ entity: "string", kind: "string", output_count: "number", execution_count: "number", usage: "number", success_rate: nullable("number"), success_rate_basis: "string", cost: "number", cost_usd: "number", cost_basis: "string", trend: nullable("string"), trend_basis: "string", recommendations: "array" }) },
+    // #255 — the integrity fields are ADVERTISED, not just returned. This tool's whole purpose
+    // is that an operator can ask whether the system is healthy; a damage report they cannot
+    // discover from the schema is only marginally better than one that is never computed.
+    { slug: "system_health", category: "improve", input_schema: obj({ window: "string" }), output_schema: obj({ gigs_run: "number", cost: "number", type_stats: "object", agent_stats: "object", tool_stats: "object", bottlenecks: "array", budget: "object", load_errors: "array", ledger_integrity: "object", outputs_integrity: "object", counts_complete: "boolean", counts_complete_basis: "string" }) },
+    // genome_reload — Rob #130. Re-reads agents/standards/types/skills/evals from
+    // disk and updates the live deps in place (no MCP server restart needed).
+    // Returns the diff vs the prior state, plus any load_errors from the new genome.
+    { slug: "genome_reload", category: "improve", input_schema: obj({}), output_schema: obj({ reloaded: "boolean", changes: "object", load_errors: "array" }) },
+    // server_restart — Rob #N / PR #141. Picks up new server bytes after
+    // npm run build without ending the Claude Code conversation. This entry
+    // exists so coltrane's own introspection (tool_inspect, system_audit)
+    // sees the tool — but the server itself never executes it. The relay
+    // parent-process catches `tools/call server_restart` before it reaches
+    // the child server, kills + respawns the child, and replies. If the
+    // server-side handler below is ever reached, the relay is misconfigured
+    // (typically: COLTRANE_SERVER_DIRECT=1 was set, bypassing the relay).
+    { slug: "server_restart", category: "improve", input_schema: obj({}), output_schema: obj({ restarted: "boolean", note: "string" }) },
+    { slug: "system_audit", category: "improve", input_schema: obj({ scope: "string", check: "string" }), output_schema: obj({ findings: "array" }) },
+    { slug: "proposal_create", category: "improve", input_schema: obj({ change_type: "string", target: "string", changes: "object", reason: "string", evidence: "object" }), output_schema: obj({ proposal_id: "string", cascade_impact: "object" }) },
+    { slug: "tool_propose", category: "improve", input_schema: obj({ slug: "string", type: "string", spec: "object", reason: "string" }), output_schema: obj({ proposal_id: "string" }) },
+    // tool_register — close the propose→register loop. Adds a slug to the live
+    // tool registry so subsequent agent_define calls can grant scope to it.
+    // Without this, propose-only governance is half-built: there is no path to
+    // legitimately admit a tool, and the rejection gate becomes a permanent block.
+    { slug: "tool_register", category: "improve", input_schema: obj({ slug: "string", type: "string", spec: "object", category: "string" }), output_schema: obj({ registered: "boolean", slug: "string" }) },
+    { slug: "tool_deprecate_propose", category: "improve", input_schema: obj({ slug: "string", reason: "string", usage_stats: "object" }), output_schema: obj({ proposal_id: "string", affected_agents: "array" }) },
+    { slug: "capability_research", category: "improve", input_schema: obj({ need: "string", context: "object" }), output_schema: obj({ approaches: "array", mcp_options: "array", recommendation: "object" }) },
+    { slug: "session_review_write", category: "improve", input_schema: obj({ gig_id: "string", output_id: "string", agent_slug: "string", agent_version: "number", quality_score: "number", quality_scores: "object", domain: "string", notes: "string" }), output_schema: obj({ review_id: "string", recorded: "boolean" }) },
+    { slug: "learning_synthesize", category: "improve", input_schema: obj({ agent_slug: "string", min_reviews: "number", since: "string", auto_propose: "boolean" }), output_schema: obj({ agent_slug: "string", review_count: "number", evidence_sufficient: "boolean", summary: "object", proposal_id: "string" }) },
+    { slug: "agent_promote", category: "build", input_schema: obj({ slug: "string", status: "string" }), output_schema: obj({ slug: "string", status: "string", promoted: "boolean" }) },
+    { slug: "standard_promote", category: "build", input_schema: obj({ slug: "string", status: "string" }), output_schema: obj({ slug: "string", status: "string", promoted: "boolean" }) },
+    { slug: "skill_define", category: "build", input_schema: obj(zodToMcpProps(SkillSchema)), output_schema: obj({ skill_id: "string", content_hash: "string" }) },
+    { slug: "skill_promote", category: "build", input_schema: obj({ slug: "string", status: "string" }), output_schema: obj({ slug: "string", status: "string", promoted: "boolean" }) },
+    { slug: "charter_suggest_update", category: "manage_context", input_schema: obj({ company_id: "string", field: "string", current_value: "string", suggested_value: "string", evidence: "object" }), output_schema: obj({ proposal_id: "string" }) },
+];
+// Lifecycle promotion order — forward-only. agent/standard share the same chain;
+// skill includes the explicit `testing` step before active.
+export const AGENT_STATUS_ORDER = ["draft", "review", "approved", "active", "retired"];
+export const STANDARD_STATUS_ORDER = ["draft", "active", "retired"];
+export const SKILL_STATUS_ORDER = ["draft", "testing", "active", "retired"];
+export class PromotionError extends Error {
+}
+/** Validate a forward-only transition through the given status chain. Throws on
+ * unknown current/target or any backward/sideways move. Idempotent (current = target). */
+export function checkPromotion(current, target, order) {
+    const ci = order.indexOf(current);
+    const ti = order.indexOf(target);
+    if (ci < 0)
+        throw new PromotionError(`unknown current status "${current}"`);
+    if (ti < 0)
+        throw new PromotionError(`unknown target status "${target}"`);
+    if (ti < ci)
+        throw new PromotionError(`cannot promote backwards: ${current} → ${target}`);
+}
+const ALWAYS_APPROVAL = new Set([
+    "tool_propose",
+    "tool_deprecate_propose",
+    "charter_suggest_update",
+]);
+const APPROVAL_IF_BREAKING = new Set(["type_register", "type_extend"]);
+export function requiresApproval(q) {
+    if (ALWAYS_APPROVAL.has(q.slug))
+        return true;
+    if (APPROVAL_IF_BREAKING.has(q.slug))
+        return q.change_class === "breaking";
+    if (q.slug === "proposal_create")
+        return q.target_kind === "permissions";
+    return false;
+}
+//# sourceMappingURL=mcp.js.map

package/dist/src/mcp.js.map

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

package/dist/src/modulation_path.d.ts

@@ -0,0 +1,42 @@
+import { type Key, type ModulationKind } from "./circle_of_fifths.js";
+export interface PhaseStep {
+    phase: string;
+    key: Key;
+}
+export interface PathTransition {
+    from_phase: string;
+    to_phase: string;
+    from_key: Key;
+    to_key: Key;
+    distance: number;
+    kind: ModulationKind;
+}
+export interface ModulationPath {
+    steps: readonly PhaseStep[];
+    transitions: readonly PathTransition[];
+    starts_in: Key;
+    ends_in: Key;
+}
+export declare class ModulationPathError extends Error {
+}
+export declare function buildPath(steps: readonly PhaseStep[]): ModulationPath;
+/**
+ * Lawful-only: every transition is either stay or lawful (no jarring jumps).
+ * Used by the validation tensor as ONE channel-read — not a global verdict.
+ */
+export declare function isLawful(path: ModulationPath): boolean;
+/**
+ * Count jarring transitions. Returned as a number, not a boolean, so a
+ * validator can weight it inside a tensor instead of collapsing to pass/fail.
+ */
+export declare function jarringCount(path: ModulationPath): number;
+/**
+ * Total distance traveled along the trajectory. Sum of per-step circle-of-fifths
+ * distances. NOT a verdict — a feature for the validation tensor.
+ */
+export declare function totalTravel(path: ModulationPath): number;
+/**
+ * Did the path return to its starting key (closed loop)? Cadence-shaped:
+ * a song that resolves to where it began. Feature, not verdict.
+ */
+export declare function returnsHome(path: ModulationPath): boolean;

package/dist/src/modulation_path.js

@@ -0,0 +1,60 @@
+// The per-gig journey through 12-key space. A modulation path is the song's
+// trajectory: which key it's in at each phase, what kind of move it made to get
+// there. NOT collapsed to a scalar — preserved as a per-phase sequence so a
+// validator can read it as one channel in a multi-channel tensor.
+import { circleOfFifthsDistance, classifyModulation, } from "./circle_of_fifths.js";
+export class ModulationPathError extends Error {
+}
+export function buildPath(steps) {
+    if (steps.length === 0) {
+        throw new ModulationPathError("modulation path requires at least one step");
+    }
+    const transitions = [];
+    for (let i = 1; i < steps.length; i++) {
+        const a = steps[i - 1];
+        const b = steps[i];
+        transitions.push({
+            from_phase: a.phase,
+            to_phase: b.phase,
+            from_key: a.key,
+            to_key: b.key,
+            distance: circleOfFifthsDistance(a.key, b.key),
+            kind: classifyModulation(a.key, b.key),
+        });
+    }
+    return {
+        steps,
+        transitions,
+        starts_in: steps[0].key,
+        ends_in: steps[steps.length - 1].key,
+    };
+}
+/**
+ * Lawful-only: every transition is either stay or lawful (no jarring jumps).
+ * Used by the validation tensor as ONE channel-read — not a global verdict.
+ */
+export function isLawful(path) {
+    return path.transitions.every((t) => t.kind !== "jarring");
+}
+/**
+ * Count jarring transitions. Returned as a number, not a boolean, so a
+ * validator can weight it inside a tensor instead of collapsing to pass/fail.
+ */
+export function jarringCount(path) {
+    return path.transitions.filter((t) => t.kind === "jarring").length;
+}
+/**
+ * Total distance traveled along the trajectory. Sum of per-step circle-of-fifths
+ * distances. NOT a verdict — a feature for the validation tensor.
+ */
+export function totalTravel(path) {
+    return path.transitions.reduce((acc, t) => acc + t.distance, 0);
+}
+/**
+ * Did the path return to its starting key (closed loop)? Cadence-shaped:
+ * a song that resolves to where it began. Feature, not verdict.
+ */
+export function returnsHome(path) {
+    return path.starts_in === path.ends_in;
+}
+//# sourceMappingURL=modulation_path.js.map

package/dist/src/modulation_path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modulation_path.js","sourceRoot":"","sources":["../../src/modulation_path.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,gFAAgF;AAChF,4EAA4E;AAC5E,kEAAkE;AAElE,OAAO,EAEL,sBAAsB,EACtB,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AA0B/B,MAAM,OAAO,mBAAoB,SAAQ,KAAK;CAAG;AAEjD,MAAM,UAAU,SAAS,CAAC,KAA2B;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,mBAAmB,CAAC,4CAA4C,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACpB,WAAW,CAAC,IAAI,CAAC;YACf,UAAU,EAAE,CAAC,CAAC,KAAK;YACnB,QAAQ,EAAE,CAAC,CAAC,KAAK;YACjB,QAAQ,EAAE,CAAC,CAAC,GAAG;YACf,MAAM,EAAE,CAAC,CAAC,GAAG;YACb,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;YAC9C,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;SACvC,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,KAAK;QACL,WAAW;QACX,SAAS,EAAE,KAAK,CAAC,CAAC,CAAE,CAAC,GAAG;QACxB,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,GAAG;KACtC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAoB;IAC3C,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAoB;IAC/C,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAoB;IAC9C,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAoB;IAC9C,OAAO,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,OAAO,CAAC;AACzC,CAAC"}

package/dist/src/output_validation.d.ts

@@ -0,0 +1,19 @@
+import { type CoreType } from "./core_types.js";
+export interface OutputCandidate {
+    core_type: CoreType;
+    domain_type: string;
+    data: Record<string, unknown>;
+}
+export interface ValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+export interface SubstanceRule {
+    field: string;
+    /** the declared JSON type of the floor field — decides what "empty" means */
+    shape: "array" | "string";
+    /** for array floors: a property every item must carry as a non-empty string */
+    item_requires?: string;
+}
+export declare const CORE_SUBSTANCE: Readonly<Record<CoreType, SubstanceRule>>;
+export declare function validateOutput(out: OutputCandidate): ValidationResult;

package/dist/src/output_validation.js

@@ -0,0 +1,51 @@
+import { CORE_TYPES } from "./core_types.js";
+export const CORE_SUBSTANCE = {
+    Signal: { field: "source", shape: "string" },
+    Interpretation: { field: "claims", shape: "array" },
+    Plan: { field: "steps", shape: "array" },
+    Judgment: { field: "criteria", shape: "array" },
+    Artifact: { field: "validation_criteria", shape: "array" },
+    Verdict: { field: "checks", shape: "array", item_requires: "method" },
+};
+// Compile-time + load-time guard: every core has a floor. A seventh core (or a rename)
+// cannot land without deciding what makes it substantive.
+for (const core of CORE_TYPES) {
+    if (!CORE_SUBSTANCE[core])
+        throw new Error(`core type "${core}" has no substance invariant`);
+}
+export function validateOutput(out) {
+    const rule = CORE_SUBSTANCE[out.core_type];
+    // An unrecognised core_type is not this function's contract to police (the loader and
+    // the registry own that); it simply has no floor to apply.
+    if (!rule)
+        return { valid: true };
+    const value = out.data[rule.field];
+    if (rule.shape === "array") {
+        if (!Array.isArray(value) || value.length === 0) {
+            return {
+                valid: false,
+                reason: `${out.core_type} requires non-empty ${rule.field}[]`,
+            };
+        }
+        if (rule.item_requires) {
+            for (const item of value) {
+                const got = item?.[rule.item_requires];
+                if (typeof got !== "string" || got.length === 0) {
+                    return {
+                        valid: false,
+                        reason: `${out.core_type}.${rule.field}[*].${rule.item_requires} is required (string)`,
+                    };
+                }
+            }
+        }
+        return { valid: true };
+    }
+    if (typeof value !== "string" || value.length === 0) {
+        return {
+            valid: false,
+            reason: `${out.core_type} requires a non-empty ${rule.field}`,
+        };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=output_validation.js.map

package/dist/src/output_validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output_validation.js","sourceRoot":"","sources":["../../src/output_validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAiB,MAAM,iBAAiB,CAAC;AA2E5D,MAAM,CAAC,MAAM,cAAc,GAA8C;IACvE,MAAM,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE;IAC5C,cAAc,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE;IACnD,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE;IACxC,QAAQ,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE;IAC/C,QAAQ,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE;IAC1D,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE;CACtE,CAAC;AAEF,uFAAuF;AACvF,0DAA0D;AAC1D,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;IAC9B,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,8BAA8B,CAAC,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAoB;IACjD,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3C,sFAAsF;IACtF,2DAA2D;IAC3D,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAElC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEnC,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChD,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,GAAG,GAAG,CAAC,SAAS,uBAAuB,IAAI,CAAC,KAAK,IAAI;aAC9D,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,KAAK,MAAM,IAAI,IAAI,KAAqB,EAAE,CAAC;gBACzC,MAAM,GAAG,GAAI,IAAmD,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;gBACvF,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAChD,OAAO;wBACL,KAAK,EAAE,KAAK;wBACZ,MAAM,EAAE,GAAG,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,aAAa,uBAAuB;qBACvF,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,GAAG,GAAG,CAAC,SAAS,yBAAyB,IAAI,CAAC,KAAK,EAAE;SAC9D,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/src/outputs.d.ts

@@ -0,0 +1,125 @@
+import type { Registry } from "./registry.js";
+export declare const REF_RELATIONS: readonly ["derived_from", "validates", "challenges", "refines", "triggers", "contains"];
+export type RefRelation = (typeof REF_RELATIONS)[number];
+export interface OutputRecord {
+    id: string;
+    core_type: string;
+    domain_type: string;
+    domain_type_version: number;
+    domain: string;
+    gig_id: string;
+    agent_slug: string;
+    from_role?: string | undefined;
+    phase?: string | undefined;
+    primitive: string;
+    data: Record<string, unknown>;
+    content_sha: string;
+    input_refs: string[];
+    input_shas: string[];
+    created_at: string;
+    cost_usd?: number | undefined;
+    tokens_used?: number | undefined;
+    duration_ms?: number | undefined;
+    skill_provenance?: {
+        slug: string;
+        version: number;
+        code_hash: string;
+        tier: number;
+    } | undefined;
+}
+export interface OutputWrite {
+    core_type: string;
+    domain_type: string;
+    domain_type_version?: number | undefined;
+    domain: string;
+    gig_id: string;
+    agent_slug: string;
+    from_role?: string | undefined;
+    phase?: string | undefined;
+    primitive: string;
+    data: Record<string, unknown>;
+    input_refs?: string[] | undefined;
+    /** content_sha of each input_ref (same order) — the real predecessor hashes (#196). When omitted,
+     *  write() resolves them from the store by input_refs id. */
+    input_shas?: string[] | undefined;
+    cost_usd?: number | undefined;
+    tokens_used?: number | undefined;
+    duration_ms?: number | undefined;
+    skill_provenance?: {
+        slug: string;
+        version: number;
+        code_hash: string;
+        tier: number;
+    } | undefined;
+}
+export interface OutputRef {
+    id: string;
+    from_output_id: string;
+    to_output_id: string;
+    relation: RefRelation;
+    primitive: string;
+    created_at: string;
+}
+export interface Finding {
+    id: string;
+    gig_id: string;
+    pattern_key?: string | undefined;
+    severity?: string | undefined;
+    title?: string | undefined;
+    evidence?: string | undefined;
+    location?: string | undefined;
+    recommendation?: string | undefined;
+    is_novel?: boolean | undefined;
+    kpi_impacts?: unknown;
+    status?: string | undefined;
+    agent_role: string;
+    dimension?: string | undefined;
+    created_at: string;
+}
+export declare class OutputStoreError extends Error {
+}
+/**
+ * One unreadable line in a persisted jsonl file. Same vocabulary as the ledger's
+ * `LedgerCorruption` (#211) — two stores in one engine should describe damage the same way.
+ */
+export interface OutputStoreCorruption {
+    path: string;
+    line_no: number;
+    reason: string;
+    preview: string;
+}
+/**
+ * #248 — skip-and-REPORT, the shape PR #256 established for the ledger.
+ *
+ * A silent skip let a torn append (crash mid-write, disk full) delete an output from `all()`,
+ * `trace()` and `output_query` with no signal at all, so the engine reported a SHORTER CHAIN
+ * as if it were the whole chain. That is the exact INVERSE of the ledger's old problem, where
+ * the same situation threw and took the entire audit surface offline. Two stores, opposite
+ * failure modes, neither correct: one hid corruption, the other was destroyed by it. Reads
+ * stay forgiving — the intact rows keep serving — and this is how an operator learns the
+ * store is damaged.
+ */
+export interface OutputStoreIntegrityReport {
+    ok: boolean;
+    /** jsonl files actually read this session. 0 for a purely in-memory store. */
+    scanned: number;
+    corrupt: OutputStoreCorruption[];
+}
+export interface OutputStore {
+    write(o: OutputWrite): OutputRecord;
+    get(id: string): OutputRecord | undefined;
+    all(): readonly OutputRecord[];
+    addRef(from_output_id: string, to_output_id: string, relation: RefRelation, primitive: string): OutputRef;
+    refs(): readonly OutputRef[];
+    trace(id: string, opts?: {
+        max_depth?: number;
+    }): OutputRecord[];
+    findings(): Finding[];
+    coreTypeOf(typeSlug: string): string | null;
+    integrity(): OutputStoreIntegrityReport;
+}
+export interface OutputStoreOptions {
+    persistDir?: string | undefined;
+}
+export declare function defaultOutputsPersistDir(): string;
+export declare function createOutputStore(registry: Registry, options?: OutputStoreOptions): OutputStore;