@eir-labs/coltrane 0.8.0 → 0.9.0

package/dist/src/runtime.d.ts

@@ -1,5 +1,7 @@
 import type { Standard, Agent, Chair } from "./composition.js";
 import { type ToolProviderRegistry } from "./tool_providers.js";
+import { type Realization } from "./venue_realize.js";
+import type { Venue } from "./chart.js";
 export declare const CORE_TO_PRIMITIVE: Record<string, Agent["primitives"][number]>;
 import { type CheckpointStore, type ReuseStore, type PriorBudgetState } from "./reuse.js";
 import type { OutputStore, OutputRecord } from "./outputs.js";
@@ -9,6 +11,7 @@ import type { SkillRecord, EvalRecord } from "./loader.js";
 export interface AgentInvocationContext {
     agent: Agent;
     phase: string;
+    gig_id?: string | undefined;
     inputs: readonly OutputRecord[];
     gig_input: Record<string, unknown>;
     output_types?: readonly string[];
@@ -17,6 +20,10 @@ export interface AgentInvocationContext {
     onEvent?: (ev: AgentStreamEvent) => void;
     signal?: AbortSignal | undefined;
     depth?: Depth | undefined;
+    realization?: Realization | undefined;
+    venue?: Venue | undefined;
+    turn_budget?: number | undefined;
+    turn_reserve?: number | undefined;
 }
 export interface AgentStreamEvent {
     type: string;
@@ -65,6 +72,12 @@ export type GigProgressEvent = {
     phase: string;
     role: string;
     event: AgentStreamEvent;
+} | {
+    type: "budget_state";
+    phase: string;
+    role: string;
+    agent_state: BudgetState["agent_state"];
+    pool_remaining: number;
 } | {
     type: "gig_resumed";
     from_gig_id: string;
@@ -247,6 +260,23 @@ export interface RunDeps {
      */
     toolProviders?: ToolProviderRegistry | undefined;
     mcpServerConfigs?: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * The slug of the venue that confines this gig's chairs. When set, runGig resolves it against
+     * `venues` and calls `resolveAndRealize` BEFORE the first chair is invoked; ANY refusal
+     * (unknown-venue, credential-breach, ceiling-empty, wildcard-door, install-digest-mismatch,
+     * standing-without-cadence) fails the gig closed — nothing is sealed, no chair runs — exactly as
+     * an unresolvable tool grant rejects. The resulting room is threaded onto every chair's
+     * `AgentInvocationContext.realization`, so the spawn is confined by construction. Absent = a
+     * venue-less dispatch, byte-identical to every run before this wire existed.
+     */
+    venue?: string | undefined;
+    /** The venues this gig may name, slug → contract. A slug the map does not hold is a dead name and
+     *  fails closed with `unknown-venue`. Absent = an empty map (any named venue is a dead name). */
+    venues?: ReadonlyMap<string, Venue> | undefined;
+    /** Credential CLASSES detected present in the ambient environment, handed to the realize gauntlet:
+     *  any class present but NOT declared by the venue's `credential_surface` is a breach that fails
+     *  the gig closed. Absent = none present (deny-by-default: an empty surface admits nothing). */
+    credentialsPresent?: string[] | undefined;
 }
 /**
  * Per-gig cost-budget input. Honors budget-state.json schema (PR #56). Only
@@ -280,6 +310,29 @@ export interface BudgetInput {
     base_cost?: number;
     /** per-byte multiplier on consumed-input size, in append units. Default 0.1. */
     k?: number;
+    /**
+     * #turn-budget — the gig-level reserve POOL, in turns: a shared quantity a budget-exhausted chair
+     * draws from, capped per chair by its own `turn_reserve`. This dispatch-payload value is the
+     * PRIMARY source and OVERRIDES `Standard.reserve_pool` deterministically when both are present
+     * (no max, no sum). Orthogonal to `opening`/`base_cost`/`k` — those are append-units, this is
+     * turns, and a draw moves `pool_remaining` only, never `spent`/`balance`. Absent → the standard
+     * default, then 0 (no pool). Distinct from 0 only in that 0 could equally be an authored empty
+     * pool; either way a chair reaching for a reserve finds nothing and is recorded as starved.
+     */
+    pool?: number;
+}
+/**
+ * #turn-budget — one attributable draw against the gig reserve pool. `denied` marks a chair that
+ * reached for a reserve an empty pool could not give — starvation is a RECORDED state, never a
+ * silent no-op. `granted` is 0 on a denied draw; `pool_remaining_after` is the pool level once this
+ * draw (or non-draw) settled, so the ledger reads as a monotone draw-down.
+ */
+export interface ReserveDraw {
+    /** The drawing chair's role — the attribution the raw invoker event omits, sourced from context. */
+    role: string;
+    granted: number;
+    pool_remaining_after: number;
+    denied?: boolean;
 }
 /**
  * Per-gig budget snapshot. Mirrors fields of domain_types/budget-state.json
@@ -319,6 +372,19 @@ export interface BudgetState {
      * 0 when no invoker reported cost (stubbed invokers, skill-only gigs).
      */
     settled_usd: number;
+    /**
+     * #turn-budget — turns remaining in the gig reserve pool (Item 2). Seeded from the dispatch
+     * `pool` (else `Standard.reserve_pool`, else 0), drawn down as chairs cross into reserve, never
+     * negative and never re-increased in v0 (strict draw-down, no preemption). Orthogonal to the
+     * append-unit ledger above: a draw moves ONLY this number.
+     */
+    pool_remaining: number;
+    /**
+     * #turn-budget — the attributable draw ledger (Item 2). One record per chair that reached for a
+     * reserve, granted or denied, so a post-run reader can see who drew, how much, and what the pool
+     * had left — and so a starved chair is visible rather than a silent no-op.
+     */
+    draws: ReserveDraw[];
 }
 /** One chair that did not run, and what stood in for it. */
 export interface SkippedChair {

package/dist/src/runtime.js

@@ -9,6 +9,7 @@ import { executeSkillAsync } from "./skill_subprocess.js";
 import { loadSkillPackage } from "./skills.js";
 import { resolveModel } from "./claude_invoker.js";
 import { resolveAgentGrants } from "./tool_providers.js";
+import { resolveAndRealize } from "./venue_realize.js";
 // core type → the process primitive that produces it (reverse of PRIMITIVE_OUTPUT_TYPE).
 // A skill-backed chair seals its output as this primitive/core when its output_contract is
 // a core type.
@@ -278,6 +279,31 @@ export async function runGig(standard, gigInput, deps) {
     // Both halves of reuse need it at t=0 — it is the field that decides whether two runs are
     // the same pipeline, and a gate that fires after the money is spent is not a gate.
     const genome_hash = genomeHash(standard);
+    // ── VENUE → DISPATCH WIRE ──────────────────────────────────────────────────────────────────
+    // When the gig names a venue, resolve + realize it ONCE, BEFORE any chair is invoked. The room is
+    // an ENFORCED performance space: `resolveAndRealize` runs the ordered gauntlet (dead name, wildcard
+    // door, standing-without-cadence, install-digest, credential-breach, per-seat ceiling) and returns
+    // a fail-closed refusal on the first breach. A refusal ABORTS the gig here — no chair spawns,
+    // nothing is sealed, no ledger row is written — exactly as an unresolvable tool grant rejects.
+    // The successful room is threaded onto every chair's ctx (below) so the spawn is confined by
+    // construction, and torn down at each chair's lifecycle end.
+    let gigRealization;
+    let gigVenue;
+    if (deps.venue !== undefined) {
+        const realization = resolveAndRealize(deps.venue, {
+            venues: new Map(deps.venues ?? []),
+            seats: standard.agents.map((agent) => ({ agent })),
+            ambientEnv: {},
+            ...(deps.credentialsPresent ? { credentialsPresent: deps.credentialsPresent } : {}),
+            gigId: gig_id,
+        });
+        if (!realization.ok) {
+            throw new RuntimeError(`venue "${deps.venue}" refused this gig fail-closed: ${realization.refusal.code} — ${realization.refusal.detail}`);
+        }
+        gigRealization = realization;
+        // realize() only returns ok once the slug resolved, so the venue is present in the map.
+        gigVenue = deps.venues?.get(deps.venue);
+    }
     // Hash the gig input LAZILY. Three callers want it now (#196's provenance backfill, the
     // resume identity, and the reuse key) but a hostile or circular payload must not be
     // canonicalized on a run that never needs it — which is every run that uses none of the
@@ -483,6 +509,10 @@ export async function runGig(standard, gigInput, deps) {
     };
     // Budget state. When deps.budget is undefined, enforcement is OFF (back-compat).
     // When present, we track an in-memory BudgetState mirroring budget-state.json.
+    // #turn-budget — the gig reserve pool opens from the dispatch payload FIRST, then the standard's
+    // default, then 0. `??` (not max/sum) so the dispatch declaration wins deterministically when both
+    // are present and absent stays distinct from a declared 0.
+    const poolOpening = deps.budget?.pool ?? standard.reserve_pool ?? 0;
     const budget = deps.budget
         ? {
             opening: deps.budget.opening,
@@ -496,8 +526,16 @@ export async function runGig(standard, gigInput, deps) {
             k: deps.budget.k ?? 0.1,
             unit: "append-units",
             settled_usd: 0,
+            pool_remaining: poolOpening,
+            draws: [],
         }
         : null;
+    // #turn-budget — reserve turns HELD by prepared-but-not-yet-settled chairs, the pool's mirror of
+    // the append-unit `reserved` above. `prepareChair` runs synchronously for the whole ready batch
+    // before any invoke, so an offer computed against `pool_remaining - poolReserved` cannot let two
+    // parallel chairs over-lend the same turns. A grant converts the hold to a real draw-down; a
+    // no-draw or denial releases it. Conservation therefore holds for every ordering, not by luck.
+    let poolReserved = 0;
     // #232 — cost RESERVED by chairs that passed the gate but have not settled. `prepareChair`
     // runs eagerly for the whole ready batch, so the gate must see its batch siblings' holds;
     // but a hold is not spend. It converts to `spent` only when the invocation succeeds, and is
@@ -978,6 +1016,79 @@ export async function runGig(standard, gigInput, deps) {
                 for (const ch of ready)
                     remaining.delete(ch.role);
             }
+            // ── EXAMINE⇄AMEND ─────────────────────────────────────────────────────────────
+            // The verify seat's verdict is not the last word when the standard budgets examine
+            // rounds. If a VERIFY chair in this phase sealed a FAILING verdict (the one canonical
+            // fail signal every Verdict carries: pass === false), re-run the maker(s) it judged —
+            // the AMEND, with the failing verdict fed back so the fix targets what actually failed —
+            // and re-verify, up to max_examine_rounds, stopping the instant the verdict passes.
+            // Rounds spent without a pass leave the last, failing verdict standing: the loop iterates
+            // to green, it never launders red into green. depends_on chairs read their inputs from
+            // producedByRole, so replacing the maker's record there is what makes the re-verify judge
+            // the amended artifact rather than the original.
+            const examineRounds = standard.max_examine_rounds ?? 0;
+            if (examineRounds > 0) {
+                const allChairs = standard.phases.flatMap((p) => p.chairs);
+                const phaseNameOf = (role) => standard.phases.find((p) => p.chairs.some((c) => c.role === role))?.name ?? phase.name;
+                const primitivesOf = (slug) => standard.agents.find((a) => a.slug === slug)?.primitives ?? [];
+                const dropFromProduced = (recs) => {
+                    for (const r of recs) {
+                        const idx = produced.indexOf(r);
+                        if (idx >= 0)
+                            produced.splice(idx, 1);
+                    }
+                };
+                const failingVerdict = (role) => (producedByRole.get(role) ?? []).find((r) => (deps.outputs.coreTypeOf(r.domain_type) ?? "") === "Verdict" &&
+                    r.data.pass === false);
+                for (const vch of phase.chairs) {
+                    if (!primitivesOf(vch.agent_slug).includes("VERIFY"))
+                        continue;
+                    let verdict = failingVerdict(vch.role);
+                    if (!verdict)
+                        continue; // no verdict, or it passed — nothing to amend
+                    // The maker(s) to amend are the dependencies that produced the ARTIFACT this verdict
+                    // judged — keyed on the chair's Artifact OUTPUT, not the agent's primitive set. A
+                    // multi-primitive agent (e.g. one seat plans, another writes) must have only its writing
+                    // seat re-run; the plan is settled for the run and is not amended.
+                    const producesArtifact = (c) => {
+                        const out = c.output_contract[0];
+                        return !!out && (deps.outputs.coreTypeOf(out) ?? "") === "Artifact";
+                    };
+                    const makers = vch.depends_on
+                        .map((role) => allChairs.find((c) => c.role === role))
+                        .filter((c) => !!c && producesArtifact(c));
+                    if (makers.length === 0)
+                        continue; // nothing to re-run — a verify with no maker to amend
+                    for (let round = 1; round <= examineRounds && verdict; round++) {
+                        checkpoint();
+                        emit({ type: "phase_start", phase: `${phase.name}:amend#${round}`, roles: [...makers.map((m) => m.role), vch.role] });
+                        const feedback = verdict;
+                        // AMEND: each maker re-runs with the failing verdict fed in as an extra input, so
+                        // the seat that built the change fixes the exact thing the verify caught.
+                        for (const mk of makers) {
+                            const prep = prepareChair(mk, phaseNameOf(mk.role));
+                            if (!prep.inputs.includes(feedback))
+                                prep.inputs.push(feedback);
+                            const recs = await invokeAndWriteChair(prep);
+                            dropFromProduced(producedByRole.get(mk.role) ?? []);
+                            producedByRole.set(mk.role, recs);
+                            produced.push(...recs);
+                            noteCheckpointRole(mk.role, phaseNameOf(mk.role), recs);
+                        }
+                        // RE-VERIFY the amended artifact.
+                        const vprep = prepareChair(vch, phase.name);
+                        const vrecs = await invokeAndWriteChair(vprep);
+                        dropFromProduced(producedByRole.get(vch.role) ?? []);
+                        producedByRole.set(vch.role, vrecs);
+                        produced.push(...vrecs);
+                        noteCheckpointRole(vch.role, phase.name, vrecs);
+                        if (budget)
+                            budget.settled_usd = usage.total_cost_usd;
+                        saveCheckpoint();
+                        verdict = failingVerdict(vch.role); // undefined once it passes → loop ends
+                    }
+                }
+            }
         }
         // Resolve a chair's declared output types into seal-specs (type → core → primitive).
         function outputSpecsFor(domainTypes, fallbackPrimitive) {
@@ -1294,10 +1405,27 @@ export async function runGig(standard, gigInput, deps) {
                 reserved += cost;
                 reservedCost = cost;
             }
+            // #turn-budget — RESERVE OFFER. Only a chair that DECLARED a `turn_reserve` reaches for the pool;
+            // one that declared none threads no ctx.turn_reserve, so the invoker's own opts-level reserve is
+            // undisturbed (the #329 continuation path). When a budget is enforced the offer is capped to what
+            // the pool can still lend (min(own reserve, pool_remaining - poolReserved)) and HELD; with no
+            // budget there is no pool to cap against, so the declared reserve threads through directly.
+            let reserveOffer;
+            if (chair.turn_reserve !== undefined && !lookup?.hit) {
+                if (budget) {
+                    const poolAvailable = Math.max(0, budget.pool_remaining - poolReserved);
+                    reserveOffer = Math.min(chair.turn_reserve, poolAvailable);
+                    poolReserved += reserveOffer;
+                }
+                else {
+                    reserveOffer = chair.turn_reserve;
+                }
+            }
             return {
                 chair, phaseName, agent, primitive, domain_type, output_specs, inputs, skills,
                 missing_skills: missing, producer_slug: agent.slug, domain,
                 ...(reservedCost !== undefined ? { cost: reservedCost } : {}),
+                ...(reserveOffer !== undefined ? { reserve_offer: reserveOffer } : {}),
                 ...(lookup ? { reuse_key: lookup.key } : {}),
                 ...(lookup?.hit ? { reuse_hit: lookup.hit } : {}),
             };
@@ -1332,6 +1460,11 @@ export async function runGig(standard, gigInput, deps) {
                 settleChairCost(p, false);
                 throw e;
             }
+            finally {
+                // Venue → dispatch wire: tear the room down at the chair lifecycle end. `teardown()` is
+                // idempotent and a no-op when no venue was named, so a venue-less gig is unaffected.
+                gigRealization?.teardown();
+            }
         }
         async function executeChair(p) {
             const { chair, phaseName, inputs, skills, output_specs, producer_slug, domain } = p;
@@ -1428,22 +1561,89 @@ export async function runGig(standard, gigInput, deps) {
                 // try for the same reason: a chair killed by #250's abort still started, and still cost.
                 const sink = makeUsageSink();
                 startedInvocations++;
+                // #turn-budget — reserve-draw interception (Items 2 & 3), all at this ONE seat so the
+                // observable cannot drift. `reserveHeld` is what prepareChair offered and held against
+                // `poolReserved`; `drew` records whether the chair actually crossed into its reserve; `settled`
+                // guards the hold so it is converted (grant) or released (no-draw / denial) exactly once.
+                const reserveHeld = p.reserve_offer ?? 0;
+                let drew = false;
+                let reserveSettled = false;
+                const releaseHold = () => {
+                    if (reserveSettled)
+                        return;
+                    poolReserved -= reserveHeld;
+                    reserveSettled = true;
+                };
                 try {
                     data = await deps.invoke({
-                        agent, phase: phaseName, inputs, gig_input: gigInput, skills,
+                        agent, phase: phaseName, gig_id, inputs, gig_input: gigInput, skills,
                         missing_skills: p.missing_skills, // #241 — what did NOT resolve, so the prompt can't assert it
                         output_types: output_specs.map((s) => s.domain_type), // #174 — the chair's promised subset
                         // #250 level 2 + #237 — the cancellation signal and the run's depth reach the invocation
                         // itself, so an invoker can kill its child and shape what it asks the model for.
                         ...(deps.signal ? { signal: deps.signal } : {}),
                         ...(deps.depth ? { depth: deps.depth } : {}),
-                        onEvent: (ev) => { sink.fold(ev); emit({ type: "agent_event", phase: phaseName, role: chair.role, event: ev }); },
+                        // #turn-budget — the chair's own turn budget threads through exactly as `depth` does; the
+                        // reserve is the pool-capped OFFER, not the raw declaration, and is present only when the
+                        // chair declared a reserve (so a reserve-less chair leaves the invoker's opts-level default
+                        // untouched — the #329 continuation path stays byte-identical).
+                        ...(p.chair.turn_budget !== undefined ? { turn_budget: p.chair.turn_budget } : {}),
+                        ...(p.reserve_offer !== undefined ? { turn_reserve: p.reserve_offer } : {}),
+                        // The venue → dispatch wire: thread the realized room onto the chair's ctx ONLY when a
+                        // venue resolved, so the invoker narrows the spawn by construction; both fields stay
+                        // absent otherwise (the venue-less path is unchanged).
+                        ...(gigRealization && gigVenue ? { realization: gigRealization, venue: gigVenue } : {}),
+                        onEvent: (ev) => {
+                            sink.fold(ev);
+                            emit({ type: "agent_event", phase: phaseName, role: chair.role, event: ev });
+                            if (!budget)
+                                return;
+                            // A chair crossed its budget into a granted reserve. Set `yielding` (D1: one condition
+                            // at two scales — the gig is yielding IFF a seated chair is drawing reserve), convert the
+                            // held offer into a real pool draw-down, and record the attributable draw. `granted` is
+                            // the amount we HELD (min(own reserve, pool-at-prep)), not the event's self-report, so
+                            // the pool can never be lent past what it holds.
+                            if (ev.type === "budget_reserve_granted") {
+                                drew = true;
+                                const granted = reserveHeld;
+                                if (!reserveSettled) {
+                                    poolReserved -= reserveHeld;
+                                    reserveSettled = true;
+                                }
+                                budget.pool_remaining -= granted;
+                                budget.agent_state = "yielding";
+                                budget.draws.push({ role: chair.role, granted, pool_remaining_after: budget.pool_remaining });
+                                emit({ type: "budget_state", phase: phaseName, role: chair.role, agent_state: "yielding", pool_remaining: budget.pool_remaining });
+                            }
+                            else if (ev.type === "budget_reserve_denied") {
+                                // The chair reached for a reserve an empty pool could not give. Record the starvation
+                                // (never silent) and release the — necessarily zero — hold. The gig is NOT yielding: a
+                                // denied reach is not a draw, so the biconditional stays false.
+                                releaseHold();
+                                budget.draws.push({ role: chair.role, granted: 0, pool_remaining_after: budget.pool_remaining, denied: true });
+                            }
+                        },
                     });
                 }
+                catch (e) {
+                    // The chair spent its reserve (and the pool) WITHOUT landing → depleted (O12/INV16). Only a
+                    // chair that actually drew moves to depleted; a plain failure keeps its own error semantics.
+                    if (budget && drew)
+                        budget.agent_state = "depleted";
+                    releaseHold();
+                    throw e;
+                }
                 finally {
                     if (sink.attributed())
                         attributedInvocations++;
                 }
+                // The drawing chair LANDED within its reserve → clear yielding back to `active` (O12/INV16).
+                // The gig-end success path then settles it; an idle chair that held but never drew releases here.
+                if (budget && drew && budget.agent_state === "yielding") {
+                    budget.agent_state = "active";
+                    emit({ type: "budget_state", phase: phaseName, role: chair.role, agent_state: "active", pool_remaining: budget.pool_remaining });
+                }
+                releaseHold();
                 // Runtime output_contract check: every type the chair promised must be covered by the
                 // bound agent's declared output_types (compose-time mirror; a hand-rolled literal could
                 // still ship a mismatch).