@eir-labs/coltrane 0.8.0 → 0.8.1

package/dist/src/change_set_branch.d.ts

@@ -0,0 +1,131 @@
+/** The institution's protected main line — the branch Law C gates, and a change-set branch is NOT. */
+export declare const PROTECTED_MAIN_LINE = "main";
+/** The namespace prefix that marks a change-set branch. */
+export declare const CHANGE_SET_BRANCH_PREFIX = "changeset/";
+/** The standard the trigger dispatches when a RED spec PR is merged into the change-set branch. */
+export declare const IMPLEMENTATION_STANDARD = "software-change-pr-v1";
+/**
+ * Derive the change-set branch name from the ORIGINATING (spec) gig id — never the current gig id.
+ * Format: `changeset/<full-originating-gig-uuid>[/<slug>]`. The full UUID is the SOLE key
+ * (truncation would forfeit the collision-freedom the branch exists to guarantee); the slug is
+ * decorative, rides alongside for humans, and is OUTSIDE the key.
+ */
+export declare function deriveChangeSetBranch(originatingGigId: string, slug?: string): string;
+/** Parse the ORIGINATING gig id back out of a change-set branch name (the slug is ignored). */
+export declare function parseOriginatingGig(branchName: string): string;
+/** Whether a name is a well-formed change-set branch (prefix + a parseable originating gig id). */
+export declare function isChangeSetBranch(branchName: string): boolean;
+/** The base branch the RED spec PR targets: the change-set branch derived from the originating gig. */
+export declare function specPrBase(originatingGigId: string): string;
+/** The base branch the GREEN implementation PR targets: the SAME change-set branch it branched from. */
+export declare function implPrBase(changeSetBranch: string): string;
+export type CreateOutcome = {
+    created: true;
+    reused: false;
+    branch: string;
+} | {
+    created: false;
+    reused: true;
+    branch: string;
+};
+/**
+ * Create-if-absent / reuse-if-present. A resumed gig that re-publishes MUST reuse the existing
+ * change-set branch, never fork a second one and never clobber/force-reset the first.
+ */
+export declare function ensureChangeSetBranch(branch: string, existingBranches: readonly string[]): CreateOutcome;
+export type PublishGate = {
+    ok: true;
+} | {
+    ok: false;
+    refusal: "dead-branch";
+    base: string;
+};
+/**
+ * Pre-flight, at the same altitude as runtime.ts's missing-gig-input hard stop: a publish that
+ * would seal a pull-request whose base branch does not exist on the remote is refused as a DEAD
+ * NAME — nothing is sealed. Same defect class the engine already refuses for dead tool-grants.
+ */
+export declare function assertBasePublishable(base: string, remoteBranches: readonly string[]): PublishGate;
+export interface ChangeRequestBranchCarrier {
+    /** The change-set branch the implementation run must work on. Additive optional field. */
+    change_set_branch?: string;
+}
+export type BranchResolution = {
+    ok: true;
+    branch: string;
+} | {
+    ok: false;
+    refusal: "branch-absent-but-expected";
+};
+/**
+ * Resolve the branch the implementation run works on. It is CARRIED in the change-request; the
+ * working-tree branch is NOT consulted (inference is how a run lands on the wrong branch
+ * silently). Absent-but-expected is a hard stop, not a guess.
+ */
+export declare function resolveImplementationBranch(req: ChangeRequestBranchCarrier, workingTreeBranch: string): BranchResolution;
+export interface RedSpecMergedEvent {
+    /** The change-set branch the RED spec PR was merged into. The idempotency key. */
+    change_set_branch: string;
+    /** The originating (spec) gig id the branch is keyed by. */
+    originating_gig_id: string;
+    /** GitHub's X-GitHub-Delivery id — at-least-once delivery, so this only guards literal re-sends. */
+    delivery_id: string;
+}
+export interface EnqueuedImplementation {
+    standard: string;
+    change_request: ChangeRequestBranchCarrier & Record<string, unknown>;
+}
+/**
+ * The trigger consumer. Its ONLY job is at-most-once ENQUEUE keyed on the change-set branch: the
+ * queue's atomic claim/lease already gives at-most-once RUN. Firing twice (a duplicate
+ * X-GitHub-Delivery, or a different delivery of the same logical event) must enqueue nothing the
+ * second time — the branch already carries an in-flight implementation gig.
+ */
+export declare class ChangeSetTrigger {
+    /** Enqueued implementations keyed on the change-set branch — the idempotency key, not the delivery id. */
+    private readonly byBranch;
+    /** Handle one 'RED spec PR merged into the change-set branch' event. */
+    handle(event: RedSpecMergedEvent): void;
+    /** The implementation gigs enqueued for a change-set branch — 0 or exactly 1. */
+    enqueued(changeSetBranch: string): readonly EnqueuedImplementation[];
+}
+export type ChangeSetState = "none" | "red" | "green" | "retired";
+export type LifecycleCommand = {
+    kind: "create";
+} | {
+    kind: "merge-red";
+} | {
+    kind: "merge-green";
+} | {
+    kind: "promote-to-main";
+} | {
+    kind: "retire";
+    by: string;
+};
+/** A merge the machine performed while applying a command — action + the branch it targeted. */
+export interface MergeAttempt {
+    action: "merge-red" | "merge-green" | "promote-to-main";
+    target_branch: string;
+}
+export interface RetirementRecord {
+    branch: string;
+    by: string;
+}
+/**
+ * The change-set branch as a state machine. The load-bearing invariants: a red merge (the spec or
+ * the implementation PR) is NEVER performed against the protected main line (Law C composition),
+ * the branch is retired at most once, and every retirement is RECORDED, never silent.
+ */
+export declare class ChangeSetBranchMachine {
+    private readonly changeSetBranch;
+    private _state;
+    private readonly _retirements;
+    constructor(changeSetBranch: string);
+    state(): ChangeSetState;
+    /** Apply a command; return the merge attempts it performed (so a test can assert their targets). */
+    apply(cmd: LifecycleCommand): readonly MergeAttempt[];
+    /** How many times this branch has been retired (must never exceed 1). */
+    retiredCount(): number;
+    /** The recorded retirement events — length must equal retiredCount(); a silent retire is refused. */
+    retirementLog(): readonly RetirementRecord[];
+}

package/dist/src/change_set_branch.js

@@ -0,0 +1,179 @@
+// SEAM — the change-set branch subsystem, authored as explicitly-stubbed THROWING signatures.
+//
+// This file exists so the RED spec COMPILES (`tsc` / `npm run build` green) while every
+// assertion in tests/change_set/** reds because the ENFORCEMENT is absent — never because a
+// symbol is missing or a type does not line up. It is the same discipline
+// src/institution_enforcement.ts uses on branch spec/coltrane-enforces-its-laws and
+// src/venue_realize.ts uses on the venue-realization branches: real signatures, real return
+// types, bodies that throw. No behaviour is implemented here. The implementation pipeline
+// (software-change-pr-v1, running off the change-set branch) is what turns these red tests green.
+//
+// The subsystem: a change set is one identity that outlives every commit and spans TWO gigs —
+// the spec-drafting gig that opens the RED spec, and the DIFFERENT implementation gig that turns
+// it green. It can therefore be keyed only by the ORIGINATING (spec) gig. Prior art:
+//   - Gerrit Change-Id — a stable id above the commit, associating many patch sets with one
+//     logical change; its per-target-branch scoping is exactly why a 1:1 branch↔gig assumption
+//     breaks (git-review Documentation/user-changeid.html).
+//   - Graphite stacked diffs — a PR whose base is another branch (not main) is a normal,
+//     mergeable workflow, so the RED spec PR and the GREEN implementation PR can both target the
+//     change-set branch and main never sees red.
+//   - git-check-ref-format(1) — a UUID and a hyphen/underscore slug are both legal ref
+//     components, so `changeset/<uuid>[/<slug>]` is a well-formed ref.
+const STUB = "change_set_branch: enforcement not implemented (RED spec seam)";
+/** The institution's protected main line — the branch Law C gates, and a change-set branch is NOT. */
+export const PROTECTED_MAIN_LINE = "main";
+/** The namespace prefix that marks a change-set branch. */
+export const CHANGE_SET_BRANCH_PREFIX = "changeset/";
+/** The standard the trigger dispatches when a RED spec PR is merged into the change-set branch. */
+export const IMPLEMENTATION_STANDARD = "software-change-pr-v1";
+// ── Branch identity: derived from the ORIGINATING gig, round-trippable, injective ───────────────
+/**
+ * Derive the change-set branch name from the ORIGINATING (spec) gig id — never the current gig id.
+ * Format: `changeset/<full-originating-gig-uuid>[/<slug>]`. The full UUID is the SOLE key
+ * (truncation would forfeit the collision-freedom the branch exists to guarantee); the slug is
+ * decorative, rides alongside for humans, and is OUTSIDE the key.
+ */
+export function deriveChangeSetBranch(originatingGigId, slug) {
+    // The full gig id is the SOLE key segment; the slug, when present, rides in a SEPARATE ref
+    // component after it, so parsing (which reads only the first segment after the prefix) ignores it.
+    const key = `${CHANGE_SET_BRANCH_PREFIX}${originatingGigId}`;
+    return slug ? `${key}/${slug}` : key;
+}
+/** Parse the ORIGINATING gig id back out of a change-set branch name (the slug is ignored). */
+export function parseOriginatingGig(branchName) {
+    // Strip the namespace, then take the FIRST path component: that is the key. A trailing slug is a
+    // later component and is dropped. A gig UUID carries no "/", so it survives the split whole.
+    const rest = branchName.slice(CHANGE_SET_BRANCH_PREFIX.length);
+    return rest.split("/")[0];
+}
+/** Whether a name is a well-formed change-set branch (prefix + a parseable originating gig id). */
+export function isChangeSetBranch(branchName) {
+    if (!branchName.startsWith(CHANGE_SET_BRANCH_PREFIX))
+        return false;
+    return parseOriginatingGig(branchName).length > 0;
+}
+// ── Publish targets: both PRs target the change-set branch, never the protected main line ───────
+/** The base branch the RED spec PR targets: the change-set branch derived from the originating gig. */
+export function specPrBase(originatingGigId) {
+    return deriveChangeSetBranch(originatingGigId);
+}
+/** The base branch the GREEN implementation PR targets: the SAME change-set branch it branched from. */
+export function implPrBase(changeSetBranch) {
+    // The implementation branches FROM and targets the SAME change-set branch — an identity, not a
+    // re-derivation, so `implPrBase(specPrBase(g)) === specPrBase(g)` holds structurally.
+    return changeSetBranch;
+}
+/**
+ * Create-if-absent / reuse-if-present. A resumed gig that re-publishes MUST reuse the existing
+ * change-set branch, never fork a second one and never clobber/force-reset the first.
+ */
+export function ensureChangeSetBranch(branch, existingBranches) {
+    // Present ⇒ reuse (never fork a second, never clobber/force-reset the first); absent ⇒ create.
+    return existingBranches.includes(branch)
+        ? { created: false, reused: true, branch }
+        : { created: true, reused: false, branch };
+}
+/**
+ * Pre-flight, at the same altitude as runtime.ts's missing-gig-input hard stop: a publish that
+ * would seal a pull-request whose base branch does not exist on the remote is refused as a DEAD
+ * NAME — nothing is sealed. Same defect class the engine already refuses for dead tool-grants.
+ */
+export function assertBasePublishable(base, remoteBranches) {
+    // A base absent from the remote is a DEAD NAME — refused before any PR is sealed, the same
+    // fail-closed altitude as a dead tool-grant. Present ⇒ the publish may proceed.
+    return remoteBranches.includes(base) ? { ok: true } : { ok: false, refusal: "dead-branch", base };
+}
+/**
+ * Resolve the branch the implementation run works on. It is CARRIED in the change-request; the
+ * working-tree branch is NOT consulted (inference is how a run lands on the wrong branch
+ * silently). Absent-but-expected is a hard stop, not a guess.
+ */
+export function resolveImplementationBranch(req, workingTreeBranch) {
+    // The branch is CARRIED in the change-request. The working tree is NEVER consulted (inference is
+    // how a run lands on the wrong branch silently), so `workingTreeBranch` is deliberately unused.
+    void workingTreeBranch;
+    if (req.change_set_branch === undefined || req.change_set_branch.length === 0) {
+        return { ok: false, refusal: "branch-absent-but-expected" };
+    }
+    return { ok: true, branch: req.change_set_branch };
+}
+/**
+ * The trigger consumer. Its ONLY job is at-most-once ENQUEUE keyed on the change-set branch: the
+ * queue's atomic claim/lease already gives at-most-once RUN. Firing twice (a duplicate
+ * X-GitHub-Delivery, or a different delivery of the same logical event) must enqueue nothing the
+ * second time — the branch already carries an in-flight implementation gig.
+ */
+export class ChangeSetTrigger {
+    /** Enqueued implementations keyed on the change-set branch — the idempotency key, not the delivery id. */
+    byBranch = new Map();
+    /** Handle one 'RED spec PR merged into the change-set branch' event. */
+    handle(event) {
+        // At-most-once ENQUEUE keyed on the branch: once a branch carries an in-flight implementation,
+        // every later delivery — a duplicate id or a fresh delivery of the same logical event — is a
+        // no-op. The queue's atomic claim/lease is what gives at-most-once RUN; this guards the enqueue.
+        if (this.byBranch.has(event.change_set_branch))
+            return;
+        this.byBranch.set(event.change_set_branch, {
+            standard: IMPLEMENTATION_STANDARD,
+            change_request: { change_set_branch: event.change_set_branch },
+        });
+    }
+    /** The implementation gigs enqueued for a change-set branch — 0 or exactly 1. */
+    enqueued(changeSetBranch) {
+        const one = this.byBranch.get(changeSetBranch);
+        return one ? [one] : [];
+    }
+}
+/**
+ * The change-set branch as a state machine. The load-bearing invariants: a red merge (the spec or
+ * the implementation PR) is NEVER performed against the protected main line (Law C composition),
+ * the branch is retired at most once, and every retirement is RECORDED, never silent.
+ */
+export class ChangeSetBranchMachine {
+    changeSetBranch;
+    _state = "none";
+    _retirements = [];
+    constructor(changeSetBranch) {
+        this.changeSetBranch = changeSetBranch;
+        void this.changeSetBranch;
+    }
+    state() {
+        return this._state;
+    }
+    /** Apply a command; return the merge attempts it performed (so a test can assert their targets). */
+    apply(cmd) {
+        switch (cmd.kind) {
+            case "create":
+                // Creating the branch is not a merge — it produces no MergeAttempt.
+                return [];
+            case "merge-red":
+                // The RED spec PR merges INTO the change-set branch — NEVER the protected main line.
+                this._state = "red";
+                return [{ action: "merge-red", target_branch: this.changeSetBranch }];
+            case "merge-green":
+                // The GREEN implementation PR merges INTO the change-set branch — again never main.
+                this._state = "green";
+                return [{ action: "merge-green", target_branch: this.changeSetBranch }];
+            case "promote-to-main":
+                // The ONLY main-targeting merge: the final change-set→main PR, merged by the governor on
+                // green CI. It is not a red merge, so it composes with Law C rather than contradicting it.
+                return [{ action: "promote-to-main", target_branch: PROTECTED_MAIN_LINE }];
+            case "retire":
+                // At-most-once, and always RECORDED — a second retire is a no-op, never a silent delete.
+                if (this._retirements.length === 0) {
+                    this._retirements.push({ branch: this.changeSetBranch, by: cmd.by });
+                    this._state = "retired";
+                }
+                return [];
+        }
+    }
+    /** How many times this branch has been retired (must never exceed 1). */
+    retiredCount() {
+        return this._retirements.length;
+    }
+    /** The recorded retirement events — length must equal retiredCount(); a silent retire is refused. */
+    retirementLog() {
+        return this._retirements;
+    }
+}
+//# sourceMappingURL=change_set_branch.js.map

package/dist/src/change_set_branch.js.map

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

package/dist/src/claude_invoker.d.ts

@@ -24,7 +24,22 @@ export declare const DEPTH_MAX_TOOL_CALLS: Partial<Record<Depth, number>>;
  * ever needs to differ from the seal's again, that difference must be argued here.
  */
 export declare function promptSchemaFor(registry: Registry | undefined, slug: string | undefined): Record<string, unknown> | undefined;
-export declare function buildPrompt(ctx: AgentInvocationContext, outputSchema?: Record<string, unknown>, outputSchemas?: Record<string, Record<string, unknown> | undefined>): string;
+/**
+ * When set, the Task layer tells the chair to seal each output IN-BAND by calling `output_write`
+ * (the write-boundary tool) rather than printing final-text JSON for the invoker to parse. The
+ * tool runs the full seal predicate and returns its verdict in-band, so the agent self-corrects
+ * within its own single run — there is no invoker re-prompt. Absent → the legacy text-seal Task
+ * (unchanged, so every buildPrompt fixture stays stable).
+ */
+export interface OutputWriteSeal {
+    via: "output_write";
+    gig_id: string;
+    agent_slug: string;
+    phase: string;
+    /** domain_type slug → its core_type, so the agent passes the right `core_type` to output_write. */
+    core_by_type: Record<string, string>;
+}
+export declare function buildPrompt(ctx: AgentInvocationContext, outputSchema?: Record<string, unknown>, outputSchemas?: Record<string, Record<string, unknown> | undefined>, seal?: OutputWriteSeal): 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
@@ -37,6 +52,23 @@ export declare class ModelOutputParseError extends Error {
     readonly excerpt: string;
     constructor(message: string, candidateCount: number, raw: string);
 }
+/**
+ * A chair completed its run but sealed NONE of its promised outputs through `output_write`.
+ * Distinct from ModelOutputParseError (a text-seal chair that emitted no parseable answer): this
+ * is the output_write-seal path, where the boundary that adjudicates a payload against its full
+ * output contract is the chair's own in-band `output_write` call (validated by the engine's
+ * checkWritable, corrected in-band by the agent), NOT a re-prompt from this invoker. A chair that
+ * never gets a single write past that boundary produced nothing this invoker can hand back.
+ *
+ * The runtime's own floor check (executeChair, `missingRequired`) also catches a shortfall and is
+ * the authority on which promised types were merely optional; this error is the earlier, chair-
+ * local signal that the write boundary sealed nothing at all.
+ */
+export declare class ModelOutputContractError extends Error {
+    readonly slug: string;
+    readonly reason: string;
+    constructor(slug: string, reason: string);
+}
 export interface ExtractJsonOptions {
     /**
      * Keys the answer is expected to carry. A candidate matches only if it contains **all**
@@ -93,6 +125,21 @@ export declare function extractJson(text: string, opts?: ExtractJsonOptions): Re
  *    no signal, so refuse to guess between rival candidates.
  */
 export declare function extractOptionsForChair(sealTypes: readonly string[], schema: Record<string, unknown> | undefined): ExtractJsonOptions;
+/**
+ * Extract the chair's sealed payloads from a stream-json stdout, keyed by the chair's seal types.
+ * Returns the blob shape the runtime already consumes (a key per domain_type, or the bare data for
+ * a lone single-output write), so executeChair seals it through its one boundary unchanged.
+ */
+/** A child that exited non-zero, carrying the stdout it produced before dying.
+ *
+ *  The stream is not incidental to the error — for a chair stopped by its tool budget it holds
+ *  validated payloads, and discarding it destroys work the engine had already adjudicated as good.
+ *  Exported because the injected-run seam (`opts.run`) is how tests reproduce a non-zero exit. */
+export declare class ChildExitError extends Error {
+    readonly stdout: string;
+    constructor(message: string, stdout: string);
+}
+export declare function captureOutputWrites(stdout: string, sealTypes: readonly string[]): Record<string, unknown>;
 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). */
@@ -107,14 +154,44 @@ export interface SpawnBounds {
 export interface ClaudeInvokerOptions {
     bin?: string | undefined;
     model?: string | undefined;
+    /**
+     * Turns granted ONCE, as a reserve, to a chair that exhausted its declared turn budget.
+     *
+     * `--max-turns` is a hard CLI bound with no callback, so without this a chair learns its budget
+     * only by dying at it — cut off mid-reach, before it can write the boundary record that says what
+     * it did NOT get to. The reserve turns that silent truncation into a stated one: the chair is told
+     * it is in reserve, how many turns remain, and what it already sealed, and is asked to close out.
+     *
+     * It cannot be delivered in-band. A chair's tools are typically HOST tools (WebSearch, WebFetch)
+     * that the child's own coltrane server never sees, so the engine surface cannot count turns. The
+     * parent sees every turn in the stream, and its only channel into a running child is a new
+     * invocation — hence a continuation rather than a signal.
+     *
+     * ONE extension, never a loop: an unbounded "just a bit more" is not a budget. Unset = the prior
+     * behaviour exactly (keep whatever passed the write boundary, grant nothing).
+     */
+    turn_reserve?: number | 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;
+    run?: ((bin: string, args: string[], spawn: SpawnBounds, env?: Record<string, string>) => string | Promise<string>) | undefined;
     timeout_ms?: number | undefined;
     abort_grace_ms?: number | undefined;
     parent_session_id?: string | undefined;
+    /**
+     * How a model chair produces its sealed output.
+     *  - "output_write" (production): the chair SEALS IN-BAND by calling `output_write` during its
+     *    run. The spawn advertises `mcp__coltrane__output_write` and its coltrane server runs in
+     *    validate-mode (COLTRANE_OUTPUT_WRITE_MODE=validate), so each call adjudicates the payload
+     *    against the FULL seal predicate and returns the verdict in-band — the agent self-corrects
+     *    within its single run. The invoker captures the validated payload from the chair's
+     *    successful output_write calls; the runtime (executeChair) is the ONE sealer.
+     *  - "text" (default, and every injected-run test): the chair prints final-text JSON, which the
+     *    invoker extracts and hands back for the runtime to seal at its boundary. Unchanged legacy
+     *    behaviour, so a bare/test invoker is unaffected.
+     */
+    sealVia?: "text" | "output_write" | undefined;
 }
 /**
  * Default ceiling for a prompt carried as a command-line argument.