@eir-labs/coltrane 0.4.0

package/dist/src/pricing.js

@@ -0,0 +1,16 @@
+export const DEPTH_MULTIPLIER = { skim: 0.5, quick: 0.75, standard: 1.0, deep: 2.0 };
+export const MODEL_MULTIPLIER = { economy: 0.5, standard: 1.0, premium: 2.0 };
+// The admissible depth values, derived from the multiplier table so the two cannot drift.
+// #237 — `depth` was advertised on gig_dispatch and silently discarded; a dispatch-time depth
+// now has to BE one of these or the call fails loudly, because "silently ran at full depth"
+// is exactly the failure the parameter existed to prevent.
+export const DEPTHS = Object.keys(DEPTH_MULTIPLIER);
+export function isDepth(v) {
+    return typeof v === "string" && DEPTHS.includes(v);
+}
+export function computeCredits(input) {
+    return (input.base_cost * DEPTH_MULTIPLIER[input.depth] * MODEL_MULTIPLIER[input.model_tier] +
+        input.agents * 0.5 +
+        input.external_tool_calls * 0.1);
+}
+//# sourceMappingURL=pricing.js.map

package/dist/src/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/pricing.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAW,CAAC;AAC9F,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAW,CAAC;AAKvF,0FAA0F;AAC1F,8FAA8F;AAC9F,4FAA4F;AAC5F,2DAA2D;AAC3D,MAAM,CAAC,MAAM,MAAM,GAAqB,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAY,CAAC;AACjF,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAK,MAA4B,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAUD,MAAM,UAAU,cAAc,CAAC,KAAkB;IAC/C,OAAO,CACL,KAAK,CAAC,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,UAAU,CAAC;QACpF,KAAK,CAAC,MAAM,GAAG,GAAG;QAClB,KAAK,CAAC,mBAAmB,GAAG,GAAG,CAChC,CAAC;AACJ,CAAC"}

package/dist/src/registry.d.ts

@@ -0,0 +1,46 @@
+import { type DomainTypeOutput } from "./genome_schema.js";
+import type { LoadedGenome } from "./loader.js";
+export declare const RESOLVE_WEIGHTS: {
+    readonly field_coverage: 0.4;
+    readonly usage_gravity: 0.15;
+    readonly downstream_satisfaction: 0.2;
+    readonly domain_affinity: 0.15;
+    readonly recency: 0.1;
+};
+export type DomainType = Pick<DomainTypeOutput, "slug" | "extends" | "domain" | "schema" | "required_fields">;
+export interface ResolveQuery {
+    extends: string;
+    domain: string;
+    required_fields: string[];
+}
+export interface ResolveResult {
+    score: number;
+    action: "use" | "extend" | "create";
+    candidates: DomainType[];
+}
+export interface OutputToValidate {
+    core_type: string;
+    domain_type: string;
+    input_refs?: string[];
+    data: Record<string, unknown>;
+}
+export interface RegistryValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export interface Registry {
+    registerType(def: DomainType): {
+        registered: true;
+        version: number;
+    };
+    resolveType(query: ResolveQuery): ResolveResult;
+    validate(output: OutputToValidate): RegistryValidationResult;
+    listTypes(): DomainType[];
+    replaceTypes(defs: readonly DomainType[]): {
+        added: string[];
+        modified: string[];
+        removed: string[];
+    };
+}
+export declare function createRegistry(initial?: DomainType[]): Registry;
+export declare function loadRegistry(genome: LoadedGenome): Registry;

package/dist/src/registry.js

@@ -0,0 +1,199 @@
+import Ajv from "ajv";
+import { CORE_TYPES } from "./core_types.js";
+import { CANONICAL_CORE_TYPES } from "./canonical_core_types.js";
+// Base-type property inheritance (docs/genome-extension.md). A domain type extending
+// a core type inherits the core's schema PROPERTIES — the base fields are "around at
+// runtime" because the core is always loaded — so a subtype instance may carry them.
+// The subtype OVERLOADS (same-named field wins) and EXTENDS (adds new fields). The 6
+// cores are immutable, so we read their properties straight from the canonical set.
+const CORE_SCHEMA_PROPS = Object.fromEntries(CANONICAL_CORE_TYPES.map((c) => [
+    c.slug,
+    (c.schema.properties ?? {}),
+]));
+export const RESOLVE_WEIGHTS = {
+    field_coverage: 0.4,
+    usage_gravity: 0.15,
+    downstream_satisfaction: 0.2,
+    domain_affinity: 0.15,
+    recency: 0.1,
+};
+function isCoreType(slug) {
+    return CORE_TYPES.includes(slug);
+}
+export function createRegistry(initial = []) {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    const types = new Map();
+    for (const def of initial)
+        types.set(def.slug, def);
+    function score(query) {
+        const candidates = [...types.values()].filter((t) => t.extends === query.extends);
+        if (candidates.length === 0)
+            return { score: 0, action: "create", candidates: [] };
+        let best = 0;
+        for (const c of candidates) {
+            const covered = query.required_fields.filter((f) => c.required_fields.includes(f)).length;
+            const coverage = query.required_fields.length === 0 ? 1 : covered / query.required_fields.length;
+            const affinity = c.domain === query.domain ? 1 : 0;
+            // usage_gravity, downstream_satisfaction, recency default to 1 until usage stats exist
+            const s = 100 *
+                (RESOLVE_WEIGHTS.field_coverage * coverage +
+                    RESOLVE_WEIGHTS.usage_gravity * 1 +
+                    RESOLVE_WEIGHTS.downstream_satisfaction * 1 +
+                    RESOLVE_WEIGHTS.domain_affinity * affinity +
+                    RESOLVE_WEIGHTS.recency * 1);
+            if (s > best)
+                best = s;
+        }
+        const action = best >= 80 ? "use" : best >= 50 ? "extend" : "create";
+        return { score: best, action, candidates };
+    }
+    return {
+        registerType(def) {
+            if (!isCoreType(def.extends)) {
+                throw new Error(`extends must be a core type, got "${def.extends}"`);
+            }
+            const resolved = score({ extends: def.extends, domain: def.domain, required_fields: def.required_fields });
+            if (resolved.score >= 80) {
+                throw new Error(`reuse enforcement: an existing type scores ${resolved.score} (>=80)`);
+            }
+            types.set(def.slug, def);
+            return { registered: true, version: 1 };
+        },
+        resolveType(query) {
+            return score(query);
+        },
+        replaceTypes(defs) {
+            const before = new Map(types);
+            const added = [];
+            const modified = [];
+            const removed = [];
+            types.clear();
+            for (const def of defs) {
+                if (!isCoreType(def.extends))
+                    continue; // soft-skip; mirrors loader's stance
+                types.set(def.slug, def);
+                const prior = before.get(def.slug);
+                if (!prior)
+                    added.push(def.slug);
+                else if (JSON.stringify(prior) !== JSON.stringify(def))
+                    modified.push(def.slug);
+            }
+            for (const slug of before.keys()) {
+                if (!types.has(slug))
+                    removed.push(slug);
+            }
+            return { added, modified, removed };
+        },
+        validate(output) {
+            // Rob #133 — domain_type is OPTIONAL. Empty / missing means the output
+            // is freeform vs. its core type (Interpretation, Plan, Artifact, …) but
+            // doesn't conform to any registered domain schema. Examples that need
+            // this: a discover-phase domain-model document, an analytical plan that
+            // doesn't fit a typed plan-shape yet. The core_type discipline still
+            // holds; only the domain-schema strictness is bypassed.
+            if (!output.domain_type)
+                return { valid: true, errors: [] };
+            // A bare CORE type as the domain_type is a freeform output of that core (e.g. a
+            // skill-backed chair that produces a plain Signal, no domain subtype). The core_type
+            // discipline still holds; there's just no domain schema to enforce — same as above.
+            // "Still holds" is now a fact rather than a claim: outputs.write runs validateOutput
+            // on every seal, so a bare core meets the same substance floor as its subtypes (#227).
+            if (isCoreType(output.domain_type))
+                return { valid: true, errors: [] };
+            const dt = types.get(output.domain_type);
+            if (!dt)
+                return { valid: false, errors: [`unknown domain_type "${output.domain_type}"`] };
+            // Inherit the base core type's properties, then let the subtype overload + extend.
+            //
+            // MAINTAINER RULING (#227) — "There's no subtype thing. It's all the way top to
+            // bottom." This REPLACES the stance that used to be documented here: that a core's
+            // base fields are "available, not forced" on a subtype, so `required` stays the
+            // subtype's own and existing instances that carry no base field still validate.
+            //
+            // That stance is wrong. Every core carries ONE substance floor — the declared field
+            // that makes its output answerable to someone else (Signal.source, Interpretation.claims,
+            // Plan.steps, Judgment.criteria, Artifact.validation_criteria, Verdict.checks) — and
+            // that floor is FORCED on every sealed output of that core, bare core or domain
+            // subtype alike. See src/output_validation.ts for the table and the per-core reasoning.
+            //
+            // The forcing lives at the seal boundary (outputs.write → validateOutput), not here,
+            // for a reason: it must hold on the paths this function deliberately does not reach —
+            // an absent domain_type (line 140), a bare core type as the domain_type (line 144),
+            // and a subtype that overloads an inherited floor away (#230). Enforcing it here as
+            // well would leave those three holes open. What this function still owns is the
+            // subtype's OWN declared contract; `required` below stays the subtype's own because
+            // the core's floor is already enforced unconditionally one layer out — not because
+            // base fields are optional.
+            const baseProps = CORE_SCHEMA_PROPS[dt.extends] ?? {};
+            const ownProps = dt.schema.properties ?? {};
+            // #200 — honor the type's declared additionalProperties. Closed-by-default
+            // stays the discipline (undeclared → false), but a type that opts into open
+            // extension with `additionalProperties: true` accepts agent-added contextual
+            // fields at seal instead of aborting the terminal chair.
+            const additionalProperties = dt.schema.additionalProperties ?? false;
+            // #229 — a type's required fields may be declared in EITHER place, and both are
+            // honored. Two authoring conventions exist in the genome and nothing reconciles
+            // them: most types populate `required_fields` and leave `schema.required` empty;
+            // the hand-authored seeding/bootstrap types do the reverse. Reading only
+            // `required_fields` (as this did) silently discarded the declaration of every type
+            // in the second group, so `{}` sealed as a well-formed instance of a type declaring
+            // 3-6 required fields.
+            //
+            // UNION, not precedence. `type_extend` (src/server.ts:609) resolves the same
+            // ambiguity as `schema.required ?? required_fields`, but precedence is the wrong
+            // rule at seal time: it makes one declaration silently void the other. No type in
+            // the genome populates both today, so the two rules are indistinguishable on
+            // current data — which is exactly why the safer rule should be the one that gets
+            // frozen in. Everything an author wrote down is enforced.
+            const declaredRequired = [
+                ...new Set([
+                    ...((dt.schema.required) ?? []),
+                    ...dt.required_fields,
+                ]),
+            ];
+            const schema = {
+                type: "object",
+                properties: { ...baseProps, ...ownProps },
+                required: declaredRequired,
+                additionalProperties,
+            };
+            const validateFn = ajv.compile(schema);
+            const ok = validateFn(output.data);
+            // Preserve instancePath + keyword in the error projection so operators see
+            // the failing field path, not just a type-class message. For property-level
+            // failures Ajv puts the field in `params.missingProperty` (required) or
+            // in `instancePath` (type mismatch) or `params.additionalProperty` (extras).
+            return {
+                valid: ok === true,
+                errors: (validateFn.errors ?? []).map((e) => {
+                    const path = e.instancePath ?? "";
+                    const keyword = e.keyword ?? "";
+                    const message = e.message ?? "invalid";
+                    const params = e.params ?? {};
+                    const missing = typeof params["missingProperty"] === "string"
+                        ? ` '${params["missingProperty"]}'`
+                        : "";
+                    const additional = typeof params["additionalProperty"] === "string"
+                        ? ` '${params["additionalProperty"]}'`
+                        : "";
+                    const fieldHint = path ? ` at ${path}` : "";
+                    return `${keyword}${fieldHint}: ${message}${missing}${additional}`.trim();
+                }),
+            };
+        },
+        listTypes() {
+            return [...types.values()];
+        },
+    };
+}
+export function loadRegistry(genome) {
+    const defs = [...genome.domain_types.values()].map((d) => ({
+        slug: d.slug,
+        extends: d.extends,
+        domain: d.domain,
+        schema: d.schema,
+        required_fields: [...d.required_fields],
+    }));
+    return createRegistry(defs);
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAC;AAEtB,OAAO,EAAE,UAAU,EAAiB,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAGjE,qFAAqF;AACrF,qFAAqF;AACrF,qFAAqF;AACrF,qFAAqF;AACrF,oFAAoF;AACpF,MAAM,iBAAiB,GAAsD,MAAM,CAAC,WAAW,CAC7F,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC9B,CAAC,CAAC,IAAI;IACN,CAAE,CAAC,CAAC,MAAmD,CAAC,UAAU,IAAI,EAAE,CAAC;CAC1E,CAAC,CACH,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,cAAc,EAAE,GAAG;IACnB,aAAa,EAAE,IAAI;IACnB,uBAAuB,EAAE,GAAG;IAC5B,eAAe,EAAE,IAAI;IACrB,OAAO,EAAE,GAAG;CACJ,CAAC;AA4CX,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAQ,UAAgC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,UAAwB,EAAE;IACvD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,OAAO;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAEpD,SAAS,KAAK,CAAC,KAAmB;QAChC,MAAM,UAAU,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC;QAClF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QACnF,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC1F,MAAM,QAAQ,GAAG,KAAK,CAAC,eAAe,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC;YACjG,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACnD,uFAAuF;YACvF,MAAM,CAAC,GACL,GAAG;gBACH,CAAC,eAAe,CAAC,cAAc,GAAG,QAAQ;oBACxC,eAAe,CAAC,aAAa,GAAG,CAAC;oBACjC,eAAe,CAAC,uBAAuB,GAAG,CAAC;oBAC3C,eAAe,CAAC,eAAe,GAAG,QAAQ;oBAC1C,eAAe,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;YACjC,IAAI,CAAC,GAAG,IAAI;gBAAE,IAAI,GAAG,CAAC,CAAC;QACzB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC7C,CAAC;IAED,OAAO;QACL,YAAY,CAAC,GAAG;YACd,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC;YACvE,CAAC;YACD,MAAM,QAAQ,GAAG,KAAK,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC;YAC3G,IAAI,QAAQ,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,8CAA8C,QAAQ,CAAC,KAAK,SAAS,CAAC,CAAC;YACzF,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACzB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC1C,CAAC;QACD,WAAW,CAAC,KAAK;YACf,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,YAAY,CAAC,IAAI;YACf,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;YAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAa,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAa,EAAE,CAAC;YAC7B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC;oBAAE,SAAS,CAAC,qCAAqC;gBAC7E,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBACzB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACnC,IAAI,CAAC,KAAK;oBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;qBAC5B,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;oBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClF,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBACjC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3C,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QACtC,CAAC;QACD,QAAQ,CAAC,MAAM;YACb,uEAAuE;YACvE,wEAAwE;YACxE,sEAAsE;YACtE,wEAAwE;YACxE,qEAAqE;YACrE,wDAAwD;YACxD,IAAI,CAAC,MAAM,CAAC,WAAW;gBAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;YAC5D,gFAAgF;YAChF,qFAAqF;YACrF,oFAAoF;YACpF,qFAAqF;YACrF,uFAAuF;YACvF,IAAI,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;YACvE,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YACzC,IAAI,CAAC,EAAE;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,wBAAwB,MAAM,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;YAC1F,mFAAmF;YACnF,EAAE;YACF,gFAAgF;YAChF,mFAAmF;YACnF,gFAAgF;YAChF,gFAAgF;YAChF,EAAE;YACF,oFAAoF;YACpF,0FAA0F;YAC1F,qFAAqF;YACrF,gFAAgF;YAChF,wFAAwF;YACxF,EAAE;YACF,qFAAqF;YACrF,sFAAsF;YACtF,oFAAoF;YACpF,oFAAoF;YACpF,gFAAgF;YAChF,oFAAoF;YACpF,mFAAmF;YACnF,4BAA4B;YAC5B,MAAM,SAAS,GAAG,iBAAiB,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACtD,MAAM,QAAQ,GAAI,EAAE,CAAC,MAAmD,CAAC,UAAU,IAAI,EAAE,CAAC;YAC1F,2EAA2E;YAC3E,4EAA4E;YAC5E,6EAA6E;YAC7E,yDAAyD;YACzD,MAAM,oBAAoB,GACvB,EAAE,CAAC,MAA6C,CAAC,oBAAoB,IAAI,KAAK,CAAC;YAClF,gFAAgF;YAChF,gFAAgF;YAChF,iFAAiF;YACjF,yEAAyE;YACzE,mFAAmF;YACnF,oFAAoF;YACpF,uBAAuB;YACvB,EAAE;YACF,6EAA6E;YAC7E,iFAAiF;YACjF,kFAAkF;YAClF,6EAA6E;YAC7E,iFAAiF;YACjF,0DAA0D;YAC1D,MAAM,gBAAgB,GAAG;gBACvB,GAAG,IAAI,GAAG,CAAC;oBACT,GAAG,CAAC,CAAE,EAAE,CAAC,MAAkC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;oBAC5D,GAAG,EAAE,CAAC,eAAe;iBACtB,CAAC;aACH,CAAC;YACF,MAAM,MAAM,GAAG;gBACb,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE;gBACzC,QAAQ,EAAE,gBAAgB;gBAC1B,oBAAoB;aACrB,CAAC;YACF,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACvC,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACnC,2EAA2E;YAC3E,4EAA4E;YAC5E,wEAAwE;YACxE,6EAA6E;YAC7E,OAAO;gBACL,KAAK,EAAE,EAAE,KAAK,IAAI;gBAClB,MAAM,EAAE,CAAC,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,YAAY,IAAI,EAAE,CAAC;oBAClC,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;oBAChC,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,SAAS,CAAC;oBACvC,MAAM,MAAM,GAAI,CAAC,CAAC,MAA8C,IAAI,EAAE,CAAC;oBACvE,MAAM,OAAO,GAAG,OAAO,MAAM,CAAC,iBAAiB,CAAC,KAAK,QAAQ;wBAC3D,CAAC,CAAC,KAAK,MAAM,CAAC,iBAAiB,CAAW,GAAG;wBAC7C,CAAC,CAAC,EAAE,CAAC;oBACP,MAAM,UAAU,GAAG,OAAO,MAAM,CAAC,oBAAoB,CAAC,KAAK,QAAQ;wBACjE,CAAC,CAAC,KAAK,MAAM,CAAC,oBAAoB,CAAW,GAAG;wBAChD,CAAC,CAAC,EAAE,CAAC;oBACP,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC5C,OAAO,GAAG,OAAO,GAAG,SAAS,KAAK,OAAO,GAAG,OAAO,GAAG,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC;gBAC5E,CAAC,CAAC;aACH,CAAC;QACJ,CAAC;QACD,SAAS;YACP,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,MAAM,IAAI,GAAiB,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvE,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAiC;QAC3C,eAAe,EAAE,CAAC,GAAG,CAAC,CAAC,eAAe,CAAC;KACxC,CAAC,CAAC,CAAC;IACJ,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC"}

package/dist/src/runtime.d.ts

@@ -0,0 +1,304 @@
+import type { Standard, Agent, Chair } from "./composition.js";
+import type { OutputStore, OutputRecord } from "./outputs.js";
+import { type Ledger, type GigUsage } from "./ledger.js";
+import type { Depth } from "./pricing.js";
+import type { SkillRecord, EvalRecord } from "./loader.js";
+export interface AgentInvocationContext {
+    agent: Agent;
+    phase: string;
+    inputs: readonly OutputRecord[];
+    gig_input: Record<string, unknown>;
+    output_types?: readonly string[];
+    skills?: readonly SkillRecord[];
+    missing_skills?: readonly string[];
+    onEvent?: (ev: AgentStreamEvent) => void;
+    signal?: AbortSignal | undefined;
+    depth?: Depth | undefined;
+}
+export interface AgentStreamEvent {
+    type: string;
+    tool?: string | undefined;
+    text?: string | undefined;
+    raw?: unknown;
+}
+export type GigProgressEvent = {
+    type: "phase_start";
+    phase: string;
+    roles: string[];
+} | {
+    type: "chair_start";
+    phase: string;
+    role: string;
+    producer: string;
+} | {
+    type: "chair_complete";
+    phase: string;
+    role: string;
+    producer: string;
+    /** types actually SEALED */
+    output_types: string[];
+    duration_ms: number;
+    /** #243 — types the chair's output_contract PROMISED. Equal to output_types when the
+     *  chair delivered everything; the difference is what `missing_output_types` names. */
+    promised_output_types?: string[];
+    /** #243 — promised but not sealed. Legal (conditional outputs) but never silent. */
+    missing_output_types?: string[];
+    /** #240 — `*_sha` fields the engine could not tie to any consumed input or the gig
+     *  payload. Sealed as "" rather than guessed; listed here so the gap is visible. */
+    unresolved_sha_fields?: string[];
+} | {
+    type: "chair_failed";
+    phase: string;
+    role: string;
+    error: string;
+} | {
+    type: "skills_unresolved";
+    phase: string;
+    role: string;
+    agent: string;
+    missing: string[];
+} | {
+    type: "agent_event";
+    phase: string;
+    role: string;
+    event: AgentStreamEvent;
+} | {
+    type: "gig_complete";
+    outputs: number;
+} | {
+    type: "gig_failed";
+    error: string;
+} | {
+    type: "gig_aborted";
+    reason: string;
+};
+export type AgentInvoker = (ctx: AgentInvocationContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+export interface ChairSelectionView {
+    phase: string;
+    ready: readonly Chair[];
+    produced: readonly OutputRecord[];
+    budget: Readonly<BudgetState> | null;
+    standard: Standard;
+}
+export type ChairSelector = (view: ChairSelectionView) => readonly Chair[] | Promise<readonly Chair[]>;
+export interface RunDeps {
+    outputs: OutputStore;
+    ledger: Ledger;
+    invoke: AgentInvoker;
+    model_version?: string | undefined;
+    skills?: ReadonlyMap<string, SkillRecord> | undefined;
+    skill_dirs?: ReadonlyMap<string, string> | undefined;
+    evals?: ReadonlyMap<string, EvalRecord> | undefined;
+    /**
+     * Optional cost-budget input. When omitted (default), no budget enforcement
+     * runs — preserving v0 back-compat. When present, the runtime tracks
+     * per-gig BudgetState matching budget-state.json schema: balance =
+     * opening - spent + credit.
+     *
+     * The cycle is RESERVE → SETTLE (#232). At chair-prep the runtime computes
+     * cost-of-append (base + k*size(input)) and compares it against
+     * `balance - reserved`; short → BudgetExhausted. Passing chairs RESERVE the
+     * cost. `spent` moves only when a chair's invocation SUCCEEDS, which is what
+     * the contract always claimed and what the code did not do: prep runs
+     * eagerly for the whole ready batch, so a batch member tripping the gate
+     * used to leave every earlier member of that batch charged for work no
+     * invoker ever started.
+     *
+     * The final BudgetState is returned in GigResult.budget_state, and is also
+     * attached to a BudgetExhausted / mid-gig error so a FAILED gig can still
+     * report what it cost.
+     */
+    budget?: BudgetInput | undefined;
+    onProgress?: ((ev: GigProgressEvent) => void) | undefined;
+    gig_id?: string | undefined;
+    selectChairs?: ChairSelector | undefined;
+    /**
+     * #249/#250 — the cancellation seam. Abort it and the run stops at its next checkpoint
+     * (between phases and between dispatch batches) and rejects with `GigAborted`. The same
+     * signal is threaded into every AgentInvocationContext, so an invoker that wires it to its
+     * subprocess also stops the in-flight chair. Absent = an uncancellable run (the v0 shape).
+     *
+     * Known bound: a SKILL-backed chair runs `spawnSync` (src/skill_subprocess.ts), which
+     * blocks the event loop, so an abort delivered while one is executing is not even RECEIVED
+     * until it returns. Skill chairs are therefore a hard uncancellable window of up to their
+     * declared `meta.timeout_ms` (default 120s). Deliberate for now — see #253.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * #237 — the depth this gig was dispatched at, threaded to every invocation so it reaches
+     * the thing that actually spends. Absent = each agent's own `depth_profile` stands.
+     */
+    depth?: Depth | undefined;
+}
+/**
+ * Per-gig cost-budget input. Honors budget-state.json schema (PR #56). Only
+ * `opening` is required for v0 enforcement; the rest are recomputed.
+ *
+ * COST FORMULA (v0, tunable):
+ *   cost = base_cost + k * size_bytes(input)
+ *   defaults: base_cost = 1, k = 0.1
+ *
+ * Where size_bytes(input) = JSON.stringify(canonical context).length.
+ *
+ * WHAT THIS IS AND IS NOT (#233). `opening`/`spent`/`balance` are SYNTHETIC APPEND UNITS —
+ * see `BudgetState.unit`. They are not dollars and were never converted to dollars; an
+ * `opening: 1000` that reads like a dollar figure to an operator is a coincidence of scale.
+ * The real, settled figure is `BudgetState.settled_usd`, reconciled from the model's own
+ * `result` events at each batch boundary. Two honest limits on the synthetic gate:
+ *
+ *   1. It is a proxy for prompt size, not a price. It has no model tier, no output side, no
+ *      skills/charter/schema bytes — only the agent slug, phase, consumed input CONTENT and
+ *      the gig payload. It is a rate limiter on context growth, nothing more.
+ *   2. A USD figure cannot gate a chair before that chair runs, because `prepareChair` runs
+ *      for the WHOLE ready batch before any invocation — a chair cannot see its batch
+ *      siblings' settled cost. So reconciliation happens at BATCH BOUNDARIES, and any dollar
+ *      bound built on it would be a cap plus one batch of slack, never a hard stop. No such
+ *      bound is wired: there is no per-chair dollar estimator, and inventing one would be
+ *      guessing. `settled_usd` reports; it does not enforce.
+ */
+export interface BudgetInput {
+    opening: number;
+    /** base cost per agent invocation, in append units. Default 1. */
+    base_cost?: number;
+    /** per-byte multiplier on consumed-input size, in append units. Default 0.1. */
+    k?: number;
+}
+/**
+ * Per-gig budget snapshot. Mirrors fields of domain_types/budget-state.json
+ * (PR #56) that are runtime-tractable in v0. balance = opening - spent + credit.
+ *
+ * The `agent_state` mirrors the budget-state.json enum:
+ *   active           — currently spending, balance > cost-of-next-append
+ *   yielding         — below cost-of-next-append, paused (used when partial)
+ *   depleted         — balance <= 0 OR < cost-of-next-append, hard stop
+ *   awaiting_grade   — work shipped, external grader contacted (v0 unused)
+ *   settled          — cycle closed, closing populated (v0 set on success)
+ */
+export interface BudgetState {
+    opening: number;
+    /** Cost of chairs that ACTUALLY RAN AND SUCCEEDED. Reserved-but-unsettled cost is not here. */
+    spent: number;
+    credit: number;
+    balance: number;
+    agent_state: "active" | "yielding" | "depleted" | "awaiting_grade" | "settled";
+    /** Slug of the agent whose invocation tripped depletion. null when solvent. */
+    depleted_agent: string | null;
+    /** Wall-clock when balance first crossed below cost-of-next-append. null while solvent. */
+    depleted_at: string | null;
+    base_cost: number;
+    k: number;
+    /**
+     * #233 — the denomination of opening/spent/balance/base_cost/k, stated rather than assumed.
+     * These are a synthetic proxy for consumed context bytes. They are NOT dollars, and nothing
+     * converts between the two. Read `settled_usd` for money.
+     */
+    unit: "append-units";
+    /**
+     * #233 — REAL settled model spend for this gig so far, in USD, reconciled from the invokers'
+     * own `result` events at each dispatch-batch boundary. This is the number `src/ledger.ts`
+     * calls settled spend; the budget gate above never used it, even though it was live and
+     * in-scope. Reporting only — see the BudgetInput docstring for why it cannot gate.
+     * 0 when no invoker reported cost (stubbed invokers, skill-only gigs).
+     */
+    settled_usd: number;
+}
+export interface GigResult {
+    gig_id: string;
+    standard_slug: string;
+    genome_hash: string;
+    run_fingerprint: string;
+    outputs: readonly OutputRecord[];
+    eval_scores: Record<string, number>;
+    /**
+     * #246 — declared eval_slugs that resolved to NO eval definition. They still appear in
+     * `eval_scores` at 0.0 (back-compat: callers key off presence), but a 0.0 that means
+     * "no such eval" is not the same claim as a 0.0 that means "the contract did not hold",
+     * and the two used to be indistinguishable — including inside `run_fingerprint`.
+     * Present only when non-empty.
+     */
+    unresolved_evals?: readonly string[];
+    /**
+     * #243 — chairs that sealed FEWER types than their output_contract promised. The runtime
+     * treats output_contract as a selector, not a floor, because a keyed output can legitimately
+     * be conditional. For a chair with a downstream consumer the shortfall surfaces as an
+     * input_contract failure; for a TERMINAL chair nothing consumes it and the promise used to
+     * evaporate into `status: "complete"`. Recording it is not enforcement — see the note at the
+     * seal loop. Present only when non-empty.
+     */
+    unfulfilled_outputs?: ReadonlyArray<{
+        role: string;
+        phase: string;
+        missing: readonly string[];
+    }>;
+    status: "complete";
+    /** Final budget snapshot. Present only when a budget was supplied. */
+    budget_state?: BudgetState;
+    /** Settled model spend (#195). Present when ≥1 real model invocation ran this gig. */
+    usage?: GigUsage;
+}
+/**
+ * #236 — settled spend used to be discarded on every failed gig: `usage` was written only on
+ * the success path, and the async dispatcher's `.catch` set status/error and nothing else. A
+ * gig that burned $6 across four chairs and died on the fifth reported zero dollars, everywhere
+ * — and failed gigs are exactly the ones whose cost an operator most needs. runGig now attaches
+ * the partial accounting to whatever it throws; these read it back safely.
+ */
+export declare function partialGigUsage(e: unknown): GigUsage | undefined;
+export declare function partialBudgetState(e: unknown): BudgetState | undefined;
+export declare class RuntimeError extends Error {
+}
+/**
+ * Raised when a gig is cancelled through `RunDeps.signal` (#249). Distinct from RuntimeError
+ * so a caller can tell "an operator stopped this" from "this crashed" — #251's point that a
+ * killed gig surfacing as `failed` with a kill-shaped error is indistinguishable from a
+ * genuine crash.
+ *
+ * Carries the spend accrued BEFORE the cancellation. Today abort does nothing, so the gig
+ * completes and its cost IS recorded; a fix that kills children without capturing accrued
+ * usage would improve cost control while regressing accounting. The dispatcher folds this
+ * onto the run state so `gig_monitor` still answers "what did this cost me".
+ */
+export declare class GigAborted extends Error {
+    readonly gig_id: string;
+    readonly reason: string;
+    readonly usage: GigUsage | undefined;
+    readonly outputs: readonly OutputRecord[];
+    constructor(gig_id: string, reason: string, usage: GigUsage | undefined, outputs: readonly OutputRecord[]);
+}
+/** The human-readable cause behind an AbortSignal, whatever shape the aborter used. */
+export declare function abortReasonText(signal: AbortSignal): string;
+/**
+ * Raised when a gig's budget cannot cover the next agent's cost-of-append.
+ * Carries the agent_slug, the available balance, and the required cost so
+ * the caller can render the exact reason. The in-memory BudgetState is
+ * also attached for downstream telemetry.
+ */
+export declare class BudgetExhausted extends Error {
+    readonly agent_slug: string;
+    readonly balance: number;
+    readonly cost: number;
+    readonly state: BudgetState;
+    constructor(agent_slug: string, balance: number, cost: number, state: BudgetState);
+}
+/**
+ * Cost-of-append for an agent invocation, in synthetic append units (see BudgetState.unit).
+ * Deterministic function of the input context size — same input → same cost. Keeps cost
+ * calculation inside the runtime (not the invoker) so budget enforcement cannot be spoofed by
+ * a misbehaving invoker.
+ *
+ * #233 — this used to serialize `input_ids`: the UUIDs of the upstream outputs a chair
+ * consumes, not their data. An upstream output contributed exactly 36 bytes whether it was a
+ * one-line signal or a 40-page draft, so the proxy was not even monotonic in the thing that
+ * drives real cost. It now measures the CONTENT the invoker actually receives.
+ *
+ * Still excluded, honestly: resolved skills, the agent charter, type schemas, model tier,
+ * max_tool_calls, and the entire output side. This is a rate limiter on consumed context, not
+ * a price. Money is `BudgetState.settled_usd`.
+ */
+export declare function computeAppendCost(ctx: {
+    agent: Agent;
+    phase: string;
+    inputs: readonly OutputRecord[];
+    gig_input: Record<string, unknown>;
+}, base_cost: number, k: number): number;
+export declare function runGig(standard: Standard, gigInput: Record<string, unknown>, deps: RunDeps): Promise<GigResult>;