@eir-labs/coltrane 0.5.1 → 0.7.2

package/dist/src/chart.d.ts

@@ -0,0 +1,254 @@
+import { type ChartInput, type ChartOutput, type ChartEdgeOutput, type ChartApprovalGateOutput, type VenueOutput } from "./genome_schema.js";
+import type { Agent, Standard } from "./composition.js";
+import { type OutputRecord } from "./outputs.js";
+import { type GigResult, type RunDeps } from "./runtime.js";
+export type Chart = ChartOutput;
+export type ChartMovement = Chart["movements"][number];
+export type ChartEdge = ChartEdgeOutput;
+export type ChartApprovalGate = ChartApprovalGateOutput;
+/** The room a performance is held in. Its shape is `VenueSchema` (one Zod source); its only engine
+ *  behaviour today is the ceiling rule below, which is why the type surfaces from this module. */
+export type Venue = VenueOutput;
+/** A movement with its standard RESOLVED — the composition's output, and what a run walks. */
+export interface ResolvedMovement {
+    movement_id: string;
+    standard: Standard;
+    runtime_fills: Record<string, unknown>;
+    seatings: Chart["movements"][number]["seatings"];
+}
+/** How an edge was classified by R6. A `conditional` edge may legitimately carry nothing. */
+export interface ClassifiedEdge {
+    from_movement: string;
+    to_movement: string;
+    output_type: string;
+    kind: "hard" | "conditional";
+}
+/** One refusal, located. Never a bare boolean: a chart is refused FOR something, at a place. */
+export interface ChartViolation {
+    /** "R0".."R9" — the rule that fired, so a caller can act on the class of defect. */
+    rule: string;
+    detail: string;
+    movement_id?: string;
+    edge?: {
+        from_movement: string;
+        to_movement: string;
+        output_type: string;
+    };
+    gate_id?: string;
+}
+/** Everything a performance needs, and nothing it has not been checked for. */
+export interface ChartPlan {
+    chart: Chart;
+    movements: readonly ResolvedMovement[];
+    /** Topological order over edges ∪ gate ordering — the order `runChart` walks. */
+    order: readonly string[];
+    edges_classified: readonly ClassifiedEdge[];
+    chart_hash: string;
+}
+export type ChartComposition = (ChartPlan & {
+    ok: true;
+    violations: readonly ChartViolation[];
+}) | {
+    ok: false;
+    violations: readonly ChartViolation[];
+};
+export interface ChartComposeInput {
+    chart: ChartInput;
+    /** The caller's genome. A movement's standard resolves here or the movement is a dead name. */
+    standards: ReadonlyMap<string, Standard>;
+    /** For R3: a seating names an agent, and an agent that does not exist is a dead seat. */
+    agents?: ReadonlyMap<string, Agent> | undefined;
+    /**
+     * For R10: the rooms this caller knows. A chart that names a `venue` is composable ONLY against a
+     * map that holds it — an unresolvable ceiling is not an absent ceiling, so a caller who knows no
+     * venues cannot compose a chart that names one. A chart with no `venue` never consults this.
+     */
+    venues?: ReadonlyMap<string, Venue> | undefined;
+    /**
+     * The types the chart's DISPATCH PAYLOAD will carry — the third way an entry slot can be filled
+     * (R7), beside an incoming hard edge and a movement's `runtime_fills`.
+     *
+     * Declared at compose time on purpose. A payload is a dispatch-time fact, but "which types this
+     * performance is seeded with" is an authoring-time DECISION, exactly as a standard declares its
+     * `input_types` rather than discovering them at t=0. Absent = the chart declares no payload, and
+     * a required entry slot with no edge and no fill is a dead slot.
+     */
+    payload_types?: readonly string[] | undefined;
+}
+/** One movement, no edges, no gates: the single-standard gig, wearing the chart's clothes. */
+export declare function isDegenerateChart(chart: {
+    movements: readonly unknown[];
+    edges?: readonly unknown[];
+    approval_gates?: readonly unknown[];
+}): boolean;
+/**
+ * The arrangement's identity.
+ *
+ * MOVEMENT lines (sorted by movement_id) fold `movement_id` with the movement's standard
+ * projection; EDGE lines (sorted) fold the endpoints, the type and the declared `optional` flag;
+ * GATE lines fold the arrangement's human seats. Declaration order therefore cannot move the hash,
+ * and the same standards arranged differently cannot share it.
+ *
+ * The standard projection is `genomeHash(standard)` ITSELF, deliberately: the spec asked for "the
+ * same field set genomeHash folds today", and the only way to guarantee those are the same bytes —
+ * now and after the next change to that field set — is to call the same function. It is also what
+ * makes the degenerate short-circuit below an exact identity rather than a coincidence.
+ */
+export declare function chartHash(plan: {
+    movements: readonly ResolvedMovement[];
+    chart: {
+        edges?: readonly ChartEdge[] | undefined;
+        approval_gates?: readonly ChartApprovalGate[] | undefined;
+    };
+}): string;
+/**
+ * Desugar a bare `standard_slug` into the chart it always was.
+ *
+ * `chart_slug == movement_id == standard_slug`, no edges, no gates, and the dispatch payload
+ * becomes the movement's `runtime_fills`. Every existing caller path is preserved because a
+ * single-standard gig IS this chart.
+ */
+export declare function degenerateChart(standard_slug: string, gig_input?: Record<string, unknown>): Chart;
+/**
+ * The dispatch target refine: EXACTLY ONE of `standard_slug` / `chart_slug`.
+ *
+ * Both optional at the outer level (so no existing caller's shape breaks) and refined to
+ * exactly-one, because "a standard AND a chart" names two performances and "neither" names none.
+ */
+export declare function dispatchTarget(args: {
+    standard_slug?: string | undefined;
+    chart_slug?: string | undefined;
+}): {
+    ok: true;
+    kind: "standard" | "chart";
+    slug: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The effective tool set of one agent in one room: its OWN grants, intersected with the room's
+ * equipment. Grants are returned as the agent declared them (scoping intact) and matched on their
+ * BASE name, because that is how every other grant resolution in the engine matches — a room that
+ * holds `Bash` holds `Bash(npx vitest run:*)`.
+ *
+ * The direction is the whole point: this can only ever return a subset of `agent.allowed_tools`. A
+ * tool present in the room and absent from the charter does not appear, so a venue cannot hand a
+ * player authority its charter never claimed.
+ */
+export declare function venueEffectiveTools(agent: Agent, venue: Venue): string[];
+/**
+ * The types a chart's SOURCE movements are seeded with — the honest answer to R7 at load time.
+ *
+ * R7 refuses a movement whose required outside input has no provider: no incoming hard edge, no
+ * `runtime_fills` entry, and not declared on the dispatch payload. The payload is a dispatch-time
+ * fact, so a LOADER cannot know it — and a loader that passed nothing would make every chart whose
+ * first movement declares a gig contract unloadable, which is not a defect in the chart.
+ *
+ * So the load-time answer is this: a movement with NO incoming edge is a boundary movement, seeded
+ * from outside the arrangement, and its standard's own `input_types` — the standard's declaration
+ * that these types enter from elsewhere (#177) — are what the payload is expected to carry. An
+ * INTERIOR movement gets nothing from here, so the dead slot R7 exists for (movement B needs a type
+ * and nothing upstream produces it) still fires at load.
+ *
+ * The strict check happens where the payload is a fact: `gig_dispatch` re-composes the chart with
+ * the real payload's keys, so a dispatch that does not actually carry the seed is refused there.
+ */
+export declare function chartEntrySeedTypes(chart: Chart, standards: ReadonlyMap<string, Standard>): string[];
+export declare function composeChart(input: ChartComposeInput): ChartComposition;
+/** The chart's own checkpoint: which movements completed, and what the performance has spent. */
+export declare function chartCheckpointId(gig_id: string): string;
+/**
+ * A movement's gig id.
+ *
+ * The degenerate chart's movement runs under the chart's own id, unchanged — same outputs file,
+ * same checkpoint, same ledger row id a single-standard dispatch always had. A real arrangement
+ * gives each movement its own id, so one movement's checkpoint, header and row cannot be another's.
+ *
+ * The spec left open whether the movements of one chart should instead SHARE a gig id, so that
+ * `OutputStore.trace` — scoped to a single gig — would walk the whole performance. That question
+ * is now ANSWERED THE OTHER WAY: the ids stay separate (a movement keeps its own checkpoint,
+ * header and row) and the STORE learned the id scheme instead. `performanceRoot` reads a
+ * performance off a movement's gig id, so `trace` walks the whole arrangement and LABELS each
+ * node with the movement it lived in. The composition is the one owner of how the id is built;
+ * the store is the one owner of how it is read back apart.
+ */
+export declare function movementGigId(plan: {
+    chart: Chart;
+}, gig_id: string, movement_id: string): string;
+/** Where a movement's own checkpoint lives. Equal to the gig id, as `runGig` expects. */
+export declare function movementCheckpointId(plan: {
+    chart: Chart;
+}, gig_id: string, movement_id: string): string;
+export interface ChartMovementRun {
+    movement_id: string;
+    standard_slug: string;
+    gig_id: string;
+    /** `skipped` = restored from the chart checkpoint; it played in an earlier attempt. */
+    status: "complete" | "skipped" | "awaiting_approval" | "budget_exhausted";
+    result?: GigResult;
+    /** What this movement handed on: its sealed outputs, or the ones a resume restored. */
+    outputs: readonly OutputRecord[];
+    /** Real settled model spend for this movement. 0 when no invoker reported cost. */
+    spent_usd: number;
+}
+export interface ChartResult {
+    chart_slug: string;
+    chart_hash: string;
+    gig_id: string;
+    status: "complete" | "awaiting_approval" | "budget_exhausted";
+    movements: readonly ChartMovementRun[];
+    /**
+     * Present iff parked: WHOSE seat the performance is waiting on, and where.
+     *
+     * `gate_id` is present for an ARRANGEMENT-level gate (approved through `approvals[gate_id]`) and
+     * absent when a movement parked at its own within-movement human chair (`approvals[role]`). The
+     * two are different offices and the reply says which, rather than calling a chair role a gate id.
+     */
+    awaiting?: {
+        movement_id: string;
+        chair: string;
+        gate_id?: string;
+        phase?: string;
+    };
+    /**
+     * Gate approvals that STAND for this performance — a yes is a record, not a message.
+     *
+     * Includes an approval sealed in an earlier attempt and restored here, because the fact an
+     * operator needs is "this gate is answered", and re-sealing it on every resume would put two
+     * yeses in the chain for one decision.
+     */
+    gates_approved?: ReadonlyArray<{
+        gate_id: string;
+        chair: string;
+        approved_by: string;
+        output_id: string;
+    }>;
+    /** Cumulative real spend across every movement of this performance. */
+    spent_usd: number;
+    /** Present when the chart declares an envelope. Names the boundary a refusal happened at. */
+    budget?: {
+        total_usd: number;
+        spent_usd: number;
+        exhausted_at_movement?: string;
+    };
+    /** Present when this run resumed an earlier attempt at the same performance. */
+    resumed?: {
+        movements: string[];
+        outputs: number;
+    };
+}
+/**
+ * Perform the chart: walk the movements in topological order, one `runGig` each.
+ *
+ * The boundaries are where everything interesting happens, because a boundary is the last place a
+ * stop is free:
+ *   - the incoming edges' carriers are gathered and handed to the sink as SEALED RECORDS (so its
+ *     provenance reaches back across the boundary, rather than a payload copy that says it came
+ *     from nowhere),
+ *   - an approval gate parks the performance — checkpointed, drained as `awaiting_approval`,
+ *     nothing hollow sealed — exactly as an in-standard human chair does,
+ *   - the budget envelope is compared against real settled spend BEFORE the next movement starts,
+ *   - and the movement that just finished is recorded, so a resume never re-derives it.
+ */
+export declare function runChart(plan: ChartPlan, chartInput: Record<string, unknown>, deps: RunDeps): Promise<ChartResult>;