@eir-labs/coltrane 0.4.0

package/dist/src/canonical_form.d.ts

@@ -0,0 +1,55 @@
+export declare const CANONICAL_FORM_VERSION = "1.1";
+export declare function canonJson(value: unknown): string;
+export declare function canonText(value: string): string;
+export declare function sha256Hex(bytes: string | Buffer): string;
+export declare function fileHashJson(value: unknown): string;
+export declare function fileHashText(text: string): string;
+export interface FileEntry {
+    relpath: string;
+    hash: string;
+}
+export declare function definitionHash(files: readonly FileEntry[]): string;
+/**
+ * Content-address an output for the run_fingerprint. Folds the *semantic* fields
+ * (type identity + producing agent/phase + data) and deliberately EXCLUDES
+ * run-instance noise — `id`, `gig_id`, `created_at`, `input_refs` are all fresh
+ * UUIDs/timestamps per run. Hashing those made two byte-identical runs produce
+ * different fingerprints, so an honest replay never matched and was
+ * indistinguishable from a tamper. With this, identical content → identical hash
+ * (replay reproduces), different content → different hash (tamper is caught).
+ */
+export declare function outputContentHash(rec: {
+    core_type: string;
+    domain_type: string;
+    domain_type_version: number;
+    domain: string;
+    primitive: string;
+    phase?: string | undefined;
+    agent_slug: string;
+    data: unknown;
+}): string;
+export interface RunFingerprintInput {
+    genome_hash: string;
+    model_version: string;
+    canonical_form_version: string;
+    eval_scores: Readonly<Record<string, number>>;
+    output_hashes: readonly string[];
+    /**
+     * #246 — eval slugs that resolved to NO eval definition. An unresolvable slug scores 0.0 for
+     * back-compat, which is byte-identical to an eval that ran and genuinely failed; without this
+     * term a typo would bake into the reproducibility key as though a real contract had been
+     * evaluated and found wanting. Contributes a line ONLY when non-empty, so every fingerprint
+     * over a fully-resolved run stays byte-identical to what it was before this field existed.
+     */
+    unresolved_evals?: readonly string[];
+}
+export declare function runFingerprint(input: RunFingerprintInput): string;
+export type DependencyClass = "type" | "agent" | "standard" | "skill" | "eval";
+export interface DirectDependency {
+    class: DependencyClass;
+    slug: string;
+    effective_hash: string;
+}
+export declare const EMPTY_DEPENDENCY_HASH = "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945";
+export declare function dependencyHash(deps: readonly DirectDependency[]): string;
+export declare function effectiveHash(content_hash: string, dependency_hash: string): string;

package/dist/src/canonical_form.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+export const CANONICAL_FORM_VERSION = "1.1";
+const EXCLUDED_FIELDS = new Set(["content_hash", "materialized_at", "last_seen"]);
+export function canonJson(value) {
+    return JSON.stringify(stripAndSortKeys(value));
+}
+export function canonText(value) {
+    const lf = value.replace(/\r\n/g, "\n");
+    return lf.replace(/\n+$/, "") + "\n";
+}
+function stripAndSortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(stripAndSortKeys);
+    if (value !== null && typeof value === "object") {
+        const sorted = {};
+        for (const k of Object.keys(value).sort()) {
+            if (EXCLUDED_FIELDS.has(k))
+                continue;
+            sorted[k] = stripAndSortKeys(value[k]);
+        }
+        return sorted;
+    }
+    return value;
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function fileHashJson(value) {
+    return sha256Hex(canonJson(value));
+}
+export function fileHashText(text) {
+    return sha256Hex(canonText(text));
+}
+export function definitionHash(files) {
+    const sorted = [...files].sort((a, b) => (a.relpath < b.relpath ? -1 : a.relpath > b.relpath ? 1 : 0));
+    const manifest = JSON.stringify(sorted.map((f) => [f.relpath, f.hash]));
+    return sha256Hex(manifest);
+}
+/**
+ * Content-address an output for the run_fingerprint. Folds the *semantic* fields
+ * (type identity + producing agent/phase + data) and deliberately EXCLUDES
+ * run-instance noise — `id`, `gig_id`, `created_at`, `input_refs` are all fresh
+ * UUIDs/timestamps per run. Hashing those made two byte-identical runs produce
+ * different fingerprints, so an honest replay never matched and was
+ * indistinguishable from a tamper. With this, identical content → identical hash
+ * (replay reproduces), different content → different hash (tamper is caught).
+ */
+export function outputContentHash(rec) {
+    return sha256Hex(canonJson({
+        core_type: rec.core_type,
+        domain_type: rec.domain_type,
+        domain_type_version: rec.domain_type_version,
+        domain: rec.domain,
+        primitive: rec.primitive,
+        phase: rec.phase,
+        agent_slug: rec.agent_slug,
+        data: rec.data,
+    }));
+}
+export function runFingerprint(input) {
+    const scoreLines = Object.keys(input.eval_scores)
+        .sort()
+        .map((k) => `${k}:${input.eval_scores[k]}`);
+    const outputLines = [...input.output_hashes].sort();
+    const lines = [
+        `genome_hash:${input.genome_hash}`,
+        `model_version:${input.model_version}`,
+        `canonical_form_version:${input.canonical_form_version}`,
+        `eval_scores:${scoreLines.join(",")}`,
+        `output_hashes:${outputLines.join(",")}`,
+    ];
+    if (input.unresolved_evals?.length) {
+        lines.push(`unresolved_evals:${[...input.unresolved_evals].sort().join(",")}`);
+    }
+    return sha256Hex(lines.join("\n") + "\n");
+}
+export const EMPTY_DEPENDENCY_HASH = "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945";
+export function dependencyHash(deps) {
+    const sorted = [...deps]
+        .map((d) => [d.class, d.slug, d.effective_hash])
+        .sort((a, b) => {
+        if (a[0] !== b[0])
+            return a[0] < b[0] ? -1 : 1;
+        if (a[1] !== b[1])
+            return a[1] < b[1] ? -1 : 1;
+        return 0;
+    });
+    return sha256Hex(JSON.stringify(sorted));
+}
+export function effectiveHash(content_hash, dependency_hash) {
+    return sha256Hex(`${CANONICAL_FORM_VERSION}|${content_hash}|${dependency_hash}`);
+}
+//# sourceMappingURL=canonical_form.js.map

package/dist/src/canonical_form.js.map

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

package/dist/src/charter.d.ts

@@ -0,0 +1,37 @@
+import type { AccessGrant } from "./access_grant.js";
+export type SubjectType = "company" | "lab" | "solo" | "oss" | "other";
+export interface Product {
+    name: string;
+    type: string;
+    url: string;
+    description: string;
+}
+export interface NorthStar {
+    goal: string;
+    priority: "low" | "medium" | "high" | "critical";
+    timeframe: string;
+    metrics: readonly string[];
+}
+export interface Charter {
+    subject_name: string;
+    subject_type: SubjectType;
+    charter: string;
+    north_stars: readonly NorthStar[];
+    products: readonly Product[];
+    pain_points: readonly string[];
+    tech_stack: readonly string[];
+    existing_tools: readonly string[];
+    access_grants: readonly AccessGrant[];
+}
+export interface ValidationIssue {
+    path: string;
+    reason: string;
+}
+export interface CharterValidation {
+    valid: boolean;
+    issues: readonly ValidationIssue[];
+}
+export declare class CharterError extends Error {
+}
+export declare function validateCharter(ctx: unknown): CharterValidation;
+export declare function loadCharter(value: unknown): Charter;

package/dist/src/charter.js

@@ -0,0 +1,86 @@
+export class CharterError extends Error {
+}
+const VALID_PRIORITIES = new Set(["low", "medium", "high", "critical"]);
+const VALID_SUBJECT_TYPES = new Set([
+    "company",
+    "lab",
+    "solo",
+    "oss",
+    "other",
+]);
+export function validateCharter(ctx) {
+    const issues = [];
+    if (typeof ctx !== "object" || ctx === null) {
+        return { valid: false, issues: [{ path: "$", reason: "context must be an object" }] };
+    }
+    const c = ctx;
+    if (typeof c.subject_name !== "string" || c.subject_name.length === 0) {
+        issues.push({ path: "subject_name", reason: "required non-empty string" });
+    }
+    if (typeof c.subject_type !== "string" ||
+        !VALID_SUBJECT_TYPES.has(c.subject_type)) {
+        issues.push({
+            path: "subject_type",
+            reason: `must be one of ${[...VALID_SUBJECT_TYPES].join("|")}`,
+        });
+    }
+    if (typeof c.charter !== "string" || c.charter.length === 0) {
+        issues.push({ path: "charter", reason: "required non-empty string (mission / purpose)" });
+    }
+    if (!Array.isArray(c.north_stars)) {
+        issues.push({ path: "north_stars", reason: "required array of NorthStar" });
+    }
+    else {
+        c.north_stars.forEach((ns, i) => {
+            const n = ns;
+            if (typeof n.goal !== "string" || n.goal.length === 0) {
+                issues.push({ path: `north_stars[${i}].goal`, reason: "required non-empty string" });
+            }
+            if (typeof n.priority !== "string" || !VALID_PRIORITIES.has(n.priority)) {
+                issues.push({
+                    path: `north_stars[${i}].priority`,
+                    reason: `must be one of ${[...VALID_PRIORITIES].join("|")}`,
+                });
+            }
+            if (typeof n.timeframe !== "string") {
+                issues.push({ path: `north_stars[${i}].timeframe`, reason: "required string" });
+            }
+            if (!Array.isArray(n.metrics)) {
+                issues.push({ path: `north_stars[${i}].metrics`, reason: "required array" });
+            }
+        });
+    }
+    if (!Array.isArray(c.products)) {
+        issues.push({ path: "products", reason: "required array" });
+    }
+    else {
+        c.products.forEach((p, i) => {
+            const pp = p;
+            for (const k of ["name", "type", "url", "description"]) {
+                if (typeof pp[k] !== "string") {
+                    issues.push({ path: `products[${i}].${k}`, reason: "required string" });
+                }
+            }
+        });
+    }
+    for (const k of ["pain_points", "tech_stack", "existing_tools"]) {
+        if (!Array.isArray(c[k])) {
+            issues.push({ path: k, reason: "required array of strings" });
+        }
+        else if (c[k].some((x) => typeof x !== "string")) {
+            issues.push({ path: k, reason: "elements must all be strings" });
+        }
+    }
+    if (!Array.isArray(c.access_grants)) {
+        issues.push({ path: "access_grants", reason: "required array of AccessGrant" });
+    }
+    return { valid: issues.length === 0, issues };
+}
+export function loadCharter(value) {
+    const r = validateCharter(value);
+    if (!r.valid) {
+        throw new CharterError(`invalid Charter: ${r.issues.map((i) => `${i.path}: ${i.reason}`).join("; ")}`);
+    }
+    return value;
+}
+//# sourceMappingURL=charter.js.map

package/dist/src/charter.js.map

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

package/dist/src/circle_of_fifths.d.ts

@@ -0,0 +1,27 @@
+export declare const KEYS: readonly ["C", "G", "D", "A", "E", "B", "Gb", "Db", "Ab", "Eb", "Bb", "F"];
+export type Key = (typeof KEYS)[number];
+/**
+ * Shortest distance along the circle of fifths between two keys.
+ * Returns 0..6 (6 = tritone-apart). Adjacent keys = 1.
+ */
+export declare function circleOfFifthsDistance(a: Key, b: Key): number;
+/**
+ * Adjacent keys on the circle (one step in either direction).
+ * C ↔ G, C ↔ F, etc. Smooth modulation pairs.
+ */
+export declare function adjacentKeys(k: Key): readonly Key[];
+/**
+ * The relative minor for each major key (parallel by 3 fifths down).
+ * Provided for completeness; the validation logic treats relative-minor
+ * modulation as zero-cost (same key signature).
+ */
+export declare const RELATIVE_MINOR: Readonly<Record<Key, string>>;
+/**
+ * Modulation classification used by sim-verify. A jsong that moves from key A
+ * to key B is "lawful" if the move is within MODULATION_THRESHOLD (default 1,
+ * i.e., adjacent on the circle, including relative-minor equivalence).
+ * Above the threshold = "jarring" — drift signal unless explicitly bridged.
+ */
+export declare const MODULATION_THRESHOLD = 1;
+export type ModulationKind = "stay" | "lawful" | "jarring";
+export declare function classifyModulation(from: Key, to: Key, threshold?: number): ModulationKind;

package/dist/src/circle_of_fifths.js

@@ -0,0 +1,78 @@
+// 12-key topology for the song-substrate. Each key is a tonic + its scale.
+// The circle of fifths arranges them in a ring where adjacent keys share 6 of
+// 7 scale notes (smooth modulation) and tritone-apart keys share 1 of 7
+// (jarring). This file exposes the 12 key names, their position on the circle,
+// and distance helpers — pure data + arithmetic, no LLM dependency.
+export const KEYS = [
+    "C",
+    "G",
+    "D",
+    "A",
+    "E",
+    "B",
+    "Gb",
+    "Db",
+    "Ab",
+    "Eb",
+    "Bb",
+    "F",
+];
+const KEY_INDEX = new Map(KEYS.map((k, i) => [k, i]));
+/**
+ * Shortest distance along the circle of fifths between two keys.
+ * Returns 0..6 (6 = tritone-apart). Adjacent keys = 1.
+ */
+export function circleOfFifthsDistance(a, b) {
+    const ia = KEY_INDEX.get(a);
+    const ib = KEY_INDEX.get(b);
+    if (ia === undefined || ib === undefined) {
+        throw new Error(`unknown key: ${ia === undefined ? a : b}`);
+    }
+    const raw = Math.abs(ia - ib);
+    return Math.min(raw, KEYS.length - raw);
+}
+/**
+ * Adjacent keys on the circle (one step in either direction).
+ * C ↔ G, C ↔ F, etc. Smooth modulation pairs.
+ */
+export function adjacentKeys(k) {
+    const i = KEY_INDEX.get(k);
+    if (i === undefined)
+        throw new Error(`unknown key: ${k}`);
+    const right = KEYS[(i + 1) % KEYS.length];
+    const left = KEYS[(i - 1 + KEYS.length) % KEYS.length];
+    return [left, right];
+}
+/**
+ * The relative minor for each major key (parallel by 3 fifths down).
+ * Provided for completeness; the validation logic treats relative-minor
+ * modulation as zero-cost (same key signature).
+ */
+export const RELATIVE_MINOR = {
+    C: "Am",
+    G: "Em",
+    D: "Bm",
+    A: "F#m",
+    E: "C#m",
+    B: "G#m",
+    Gb: "Ebm",
+    Db: "Bbm",
+    Ab: "Fm",
+    Eb: "Cm",
+    Bb: "Gm",
+    F: "Dm",
+};
+/**
+ * Modulation classification used by sim-verify. A jsong that moves from key A
+ * to key B is "lawful" if the move is within MODULATION_THRESHOLD (default 1,
+ * i.e., adjacent on the circle, including relative-minor equivalence).
+ * Above the threshold = "jarring" — drift signal unless explicitly bridged.
+ */
+export const MODULATION_THRESHOLD = 1;
+export function classifyModulation(from, to, threshold = MODULATION_THRESHOLD) {
+    if (from === to)
+        return "stay";
+    const d = circleOfFifthsDistance(from, to);
+    return d <= threshold ? "lawful" : "jarring";
+}
+//# sourceMappingURL=circle_of_fifths.js.map

package/dist/src/circle_of_fifths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circle_of_fifths.js","sourceRoot":"","sources":["../../src/circle_of_fifths.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8EAA8E;AAC9E,wEAAwE;AACxE,+EAA+E;AAC/E,oEAAoE;AAEpE,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,GAAG;IACH,GAAG;IACH,GAAG;IACH,GAAG;IACH,GAAG;IACH,GAAG;IACH,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,GAAG;CACK,CAAC;AAIX,MAAM,SAAS,GAA6B,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhF;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,CAAM,EAAE,CAAM;IACnD,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,gBAAgB,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,CAAM;IACjC,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAE,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAE,CAAC;IACxD,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkC;IAC3D,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,KAAK;IACR,CAAC,EAAE,KAAK;IACR,CAAC,EAAE,KAAK;IACR,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,CAAC,EAAE,IAAI;CACR,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAItC,MAAM,UAAU,kBAAkB,CAAC,IAAS,EAAE,EAAO,EAAE,YAAoB,oBAAoB;IAC7F,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,MAAM,CAAC;IAC/B,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC"}

package/dist/src/claude_invoker.d.ts

@@ -0,0 +1,102 @@
+import { type AgentInvocationContext, type AgentInvoker } from "./runtime.js";
+import type { Registry } from "./registry.js";
+import type { Depth, ModelTier } from "./pricing.js";
+import { type ToolProviderRegistry } from "./tool_providers.js";
+export declare const MODEL_TIER_MAP: Record<ModelTier, string>;
+export declare const BELBIN_DESCRIPTIONS: Record<string, string>;
+export declare const DEPTH_GUIDANCE: Record<Depth, string>;
+export declare const DEPTH_MAX_TOOL_CALLS: Partial<Record<Depth, number>>;
+export declare function buildPrompt(ctx: AgentInvocationContext, outputSchema?: Record<string, unknown>, outputSchemas?: Record<string, Record<string, unknown> | undefined>): string;
+/**
+ * A typed extraction failure. Carries the number of balanced JSON objects found and a
+ * bounded excerpt of the raw text — previously both throws were bare `Error`s with no
+ * sample, so the operator's entire diagnostic was a V8 offset into a string never
+ * surfaced. The type is also the prerequisite for any future retry policy: runtime.ts
+ * cannot currently tell a retryable parse failure from a non-retryable contract failure.
+ */
+export declare class ModelOutputParseError extends Error {
+    readonly candidateCount: number;
+    readonly excerpt: string;
+    constructor(message: string, candidateCount: number, raw: string);
+}
+export interface ExtractJsonOptions {
+    /**
+     * Keys the answer is expected to carry. A candidate matches only if it contains **all**
+     * of them — a partial match does not score, because "closest wins" is exactly the
+     * guess that produces silent corruption.
+     *
+     * NOTE on derivation (see `extractOptionsForChair`): the two prompt shapes are mutually
+     * exclusive, so schema property names and type slugs are chosen per-shape rather than
+     * merged into one set. A flat union is unsatisfiable under all-must-match semantics —
+     * a single-output answer `{"title":…}` can never also contain the key `finding`.
+     */
+    expectKeys?: readonly string[] | undefined;
+    /**
+     * Set by a caller that has NO key signal at all (a bare-core output type, or a domain
+     * type absent from the registry — the same short-circuit registry.ts:140-146 takes).
+     * One candidate is unambiguous and safe; multiple candidates with nothing to choose
+     * between them is precisely the situation that silently seals the wrong object, so it
+     * fails loudly instead of guessing.
+     */
+    requireUnambiguous?: boolean | undefined;
+}
+/**
+ * Extract the model's answer object from its output.
+ *
+ * Selection policy (a deliberate contract change from "the first balanced object"):
+ *   1. A candidate inside a fenced block beats one outside; among fenced, prefer the last.
+ *   2. Then `expectKeys` — a candidate must contain ALL expected keys to qualify.
+ *   3. Then the LAST surviving candidate, not the first. The prompt demands a single
+ *      object (buildPrompt :146/:153), so an earlier object is evidence of scaffolding.
+ *
+ * A whole-text top-level array is handled explicitly: one element unwraps, more than one
+ * throws rather than silently discarding the array framing and every later element.
+ */
+export declare function extractJson(text: string, opts?: ExtractJsonOptions): Record<string, unknown>;
+/**
+ * Build the extractor's options for a chair from what the invoker already resolved.
+ * Shared by the Claude and Bifrost invokers so the key signal reaches every call site —
+ * behaviour propagates through the shared import, but `expectKeys` does not unless each
+ * site passes it (#221 policy 5).
+ *
+ * The two prompt shapes are mutually exclusive, so the derivation is per-shape:
+ *  - MULTI-output chair — buildPrompt :138-147 asks for a blob keyed by type slug, so the
+ *    slugs are the expected keys.
+ *  - SINGLE-output chair — buildPrompt :148-155 asks for the bare data object, never
+ *    wrapped in {"<type-slug>": …}, so the resolved schema's property names are the
+ *    signal. Unioning the slug in here would make the set unsatisfiable under
+ *    all-must-match semantics and destroy the signal entirely.
+ *  - Neither available (bare core type, or a domain type absent from the registry) —
+ *    no signal, so refuse to guess between rival candidates.
+ */
+export declare function extractOptionsForChair(sealTypes: readonly string[], schema: Record<string, unknown> | undefined): ExtractJsonOptions;
+export declare const DEFAULT_CHAIR_TIMEOUT_MS: number;
+export declare const DEFAULT_ABORT_GRACE_MS = 2000;
+/** How many chair children are alive right now (observability for the shutdown path). */
+export declare function liveChairChildCount(): number;
+/** SIGTERM every live chair child, escalating to SIGKILL after `graceMs`. Returns the count
+ *  signalled. Called on server shutdown so a restart is not an orphaning. */
+export declare function killLiveChairChildren(graceMs?: number): number;
+export interface SpawnBounds {
+    timeout: number;
+    killSignal: "SIGKILL";
+}
+export interface ClaudeInvokerOptions {
+    bin?: string | undefined;
+    model?: string | undefined;
+    registry?: Registry | undefined;
+    mcpServers?: Record<string, unknown> | undefined;
+    toolProviders?: ToolProviderRegistry | undefined;
+    mcpServerConfigs?: Record<string, unknown> | undefined;
+    run?: ((bin: string, args: string[], spawn: SpawnBounds) => string | Promise<string>) | undefined;
+    timeout_ms?: number | undefined;
+    abort_grace_ms?: number | undefined;
+    parent_session_id?: string | undefined;
+}
+export declare function buildInvokerArgs(prompt: string, mcpConfigPath: string, opts: {
+    model?: string | undefined;
+    allowed_tools?: readonly string[] | undefined;
+    disallowed_tools?: readonly string[] | undefined;
+    max_tool_calls?: number | undefined;
+}): string[];
+export declare function makeClaudeInvoker(opts?: ClaudeInvokerOptions): AgentInvoker;