@nifrajs/coding-agent 3.2.0

package/dist/orchestration/evidence-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Evidence-only run stores. A store keeps a bounded live window of the most recent
+ * {@link RunEvidence} records, a set of order-independent aggregates (completed node ids, artifact
+ * refs, counters), and an order-independent terminal digest - never the whole stream, so a 100k-event
+ * run stays bounded in memory. Every record is re-parsed through {@link parseRunEvidence} on the way
+ * in, so a payload-bearing or oversized record cannot be written through either store: the parser is
+ * the privacy gate, not the caller's discipline.
+ *
+ * There is no dependency on `FileSessionStore` or any session machinery: these stores hold run
+ * evidence only, and the file store persists exactly the content-free record it parsed.
+ */
+import type { ArtifactRef, RunEvidence } from "@nifrajs/agent-protocol";
+/** Terminal tally of a run's evidence stream. Counts only; no payloads. */
+export interface EvidenceCounters {
+    readonly total: number;
+    readonly started: number;
+    readonly completed: number;
+    readonly failed: number;
+}
+/** A bounded, evidence-only run store. Append is fail-closed; reads are content-free aggregates. */
+export interface EvidenceStore {
+    /** Parse, tally, and persist one record. Throws on a payload-bearing or oversized record. */
+    append(record: RunEvidence): Promise<void>;
+    /** Total records appended (not the live-window size). */
+    readonly count: number;
+    /** The most recent records, oldest first, capped at the configured window. */
+    live(): readonly RunEvidence[];
+    counters(): EvidenceCounters;
+    /** Distinct node ids that reached `completed`, sorted for determinism. */
+    completedNodeIds(): readonly string[];
+    /** Every artifact ref referenced by the stream, in append order. */
+    artifacts(): readonly ArtifactRef[];
+    /** Order-independent SHA-256 of the run's outcome multiset (parallel order cannot change it). */
+    digest(): Promise<string>;
+}
+export interface MemoryEvidenceStoreOptions {
+    /** Records retained in the live window. Older records fall out; aggregates still count them. */
+    readonly maxLive?: number;
+}
+/** A fully in-memory bounded store. Keeps a window plus aggregates; never the whole stream. */
+export declare class MemoryEvidenceStore implements EvidenceStore {
+    private readonly accumulator;
+    constructor(options?: MemoryEvidenceStoreOptions);
+    append(record: RunEvidence): Promise<void>;
+    get count(): number;
+    live(): readonly RunEvidence[];
+    counters(): EvidenceCounters;
+    completedNodeIds(): readonly string[];
+    artifacts(): readonly ArtifactRef[];
+    digest(): Promise<string>;
+}
+export interface FileEvidenceStoreOptions {
+    /** Append-only newline-delimited file. One canonical JSON record per line, in append order. */
+    readonly path: string;
+    readonly maxLive?: number;
+}
+/**
+ * A bounded store that also appends each parsed record as one canonical-JSON line to a file, in
+ * deterministic append order. The record is normalized (and so a forbidden-content record is
+ * rejected) BEFORE the line is written, so the file never receives a payload. The append uses the
+ * `a` flag, so each record is one O_APPEND write.
+ */
+export declare class FileEvidenceStore implements EvidenceStore {
+    private readonly accumulator;
+    private readonly path;
+    constructor(options: FileEvidenceStoreOptions);
+    append(record: RunEvidence): Promise<void>;
+    get count(): number;
+    live(): readonly RunEvidence[];
+    counters(): EvidenceCounters;
+    completedNodeIds(): readonly string[];
+    artifacts(): readonly ArtifactRef[];
+    digest(): Promise<string>;
+}
+//# sourceMappingURL=evidence-store.d.ts.map

package/dist/orchestration/evidence-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-store.d.ts","sourceRoot":"","sources":["../../src/orchestration/evidence-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAIvE,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,oGAAoG;AACpG,MAAM,WAAW,aAAa;IAC5B,6FAA6F;IAC7F,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,8EAA8E;IAC9E,IAAI,IAAI,SAAS,WAAW,EAAE,CAAA;IAC9B,QAAQ,IAAI,gBAAgB,CAAA;IAC5B,0EAA0E;IAC1E,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAAA;IACrC,oEAAoE;IACpE,SAAS,IAAI,SAAS,WAAW,EAAE,CAAA;IACnC,iGAAiG;IACjG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAC1B;AA8GD,MAAM,WAAW,0BAA0B;IACzC,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,+FAA+F;AAC/F,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,OAAO,GAAE,0BAA+B;IAI9C,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,IAAI,SAAS,WAAW,EAAE;IAG9B,QAAQ,IAAI,gBAAgB;IAG5B,gBAAgB,IAAI,SAAS,MAAM,EAAE;IAGrC,SAAS,IAAI,SAAS,WAAW,EAAE;IAG7B,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CAGhC;AAED,MAAM,WAAW,wBAAwB;IACvC,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;gBAEjB,OAAO,EAAE,wBAAwB;IAKvC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhD,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,IAAI,SAAS,WAAW,EAAE;IAG9B,QAAQ,IAAI,gBAAgB;IAG5B,gBAAgB,IAAI,SAAS,MAAM,EAAE;IAGrC,SAAS,IAAI,SAAS,WAAW,EAAE;IAG7B,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CAGhC"}

package/dist/orchestration/evidence-store.js

@@ -0,0 +1,183 @@
+/**
+ * Evidence-only run stores. A store keeps a bounded live window of the most recent
+ * {@link RunEvidence} records, a set of order-independent aggregates (completed node ids, artifact
+ * refs, counters), and an order-independent terminal digest - never the whole stream, so a 100k-event
+ * run stays bounded in memory. Every record is re-parsed through {@link parseRunEvidence} on the way
+ * in, so a payload-bearing or oversized record cannot be written through either store: the parser is
+ * the privacy gate, not the caller's discipline.
+ *
+ * There is no dependency on `FileSessionStore` or any session machinery: these stores hold run
+ * evidence only, and the file store persists exactly the content-free record it parsed.
+ */
+import { appendFile } from "node:fs/promises";
+import { assertEvidenceSize, parseRunEvidence } from "@nifrajs/agent-protocol";
+import { canonicalJson } from "./hash.js";
+const DEFAULT_MAX_LIVE = 1024;
+const encoder = new TextEncoder();
+async function sha256Bytes(text) {
+    const digest = await crypto.subtle.digest("SHA-256", encoder.encode(text));
+    return new Uint8Array(digest);
+}
+/**
+ * The identity of one record for the terminal digest: node outcome only. `seq`, `durationMs`, and
+ * `runId` are excluded so two runs of the same plan (or the same plan under a different parallel
+ * schedule) produce an identical digest - the deterministic-eval anchor. Each node emits at most one
+ * record per status, so XOR accumulation never cancels a distinct outcome.
+ */
+function digestKey(record) {
+    return canonicalJson({
+        planDigest: record.planDigest,
+        nodeId: record.nodeId,
+        status: record.status,
+        idempotent: record.idempotent,
+        ...(record.errorCode !== undefined ? { errorCode: record.errorCode } : {}),
+        ...(record.effectKey !== undefined ? { effectKey: record.effectKey } : {}),
+        ...(record.artifacts !== undefined ? { artifacts: record.artifacts } : {}),
+    });
+}
+/** Shared accumulator: bounded ring window plus order-independent aggregates. No payload retained. */
+class EvidenceAccumulator {
+    max;
+    buf = [];
+    head = 0;
+    filled = false;
+    acc = new Uint8Array(32);
+    completed = new Set();
+    artifactRefs = [];
+    totalCount = 0;
+    startedCount = 0;
+    completedCount = 0;
+    failedCount = 0;
+    constructor(maxLive) {
+        if (!Number.isSafeInteger(maxLive) || maxLive < 0)
+            throw new RangeError("evidence store: maxLive must be a non-negative integer");
+        this.max = maxLive;
+    }
+    /** `record` is already parsed and within the size cap. */
+    async add(record) {
+        this.totalCount++;
+        if (record.status === "started")
+            this.startedCount++;
+        else if (record.status === "completed") {
+            this.completedCount++;
+            this.completed.add(record.nodeId);
+        }
+        else
+            this.failedCount++;
+        if (record.artifacts !== undefined)
+            for (const ref of record.artifacts)
+                this.artifactRefs.push(ref);
+        const hash = await sha256Bytes(digestKey(record));
+        for (let i = 0; i < 32; i++)
+            this.acc[i] = this.acc[i] ^ hash[i];
+        this.pushLive(record);
+    }
+    pushLive(record) {
+        if (this.max === 0)
+            return;
+        this.buf[this.head] = record;
+        this.head = (this.head + 1) % this.max;
+        if (this.head === 0)
+            this.filled = true;
+    }
+    get count() {
+        return this.totalCount;
+    }
+    live() {
+        if (!this.filled)
+            return this.buf.slice(0, this.head);
+        return [...this.buf.slice(this.head), ...this.buf.slice(0, this.head)];
+    }
+    counters() {
+        return {
+            total: this.totalCount,
+            started: this.startedCount,
+            completed: this.completedCount,
+            failed: this.failedCount,
+        };
+    }
+    completedNodeIds() {
+        return [...this.completed].sort();
+    }
+    artifacts() {
+        return [...this.artifactRefs];
+    }
+    digest() {
+        let hex = "";
+        for (let i = 0; i < 32; i++)
+            hex += this.acc[i].toString(16).padStart(2, "0");
+        return hex;
+    }
+}
+/** Normalize on the way in: re-parse (content-free gate) then re-check the size cap. */
+function normalize(record) {
+    const parsed = parseRunEvidence(record);
+    assertEvidenceSize(parsed);
+    return parsed;
+}
+/** A fully in-memory bounded store. Keeps a window plus aggregates; never the whole stream. */
+export class MemoryEvidenceStore {
+    accumulator;
+    constructor(options = {}) {
+        this.accumulator = new EvidenceAccumulator(options.maxLive ?? DEFAULT_MAX_LIVE);
+    }
+    async append(record) {
+        await this.accumulator.add(normalize(record));
+    }
+    get count() {
+        return this.accumulator.count;
+    }
+    live() {
+        return this.accumulator.live();
+    }
+    counters() {
+        return this.accumulator.counters();
+    }
+    completedNodeIds() {
+        return this.accumulator.completedNodeIds();
+    }
+    artifacts() {
+        return this.accumulator.artifacts();
+    }
+    async digest() {
+        return this.accumulator.digest();
+    }
+}
+/**
+ * A bounded store that also appends each parsed record as one canonical-JSON line to a file, in
+ * deterministic append order. The record is normalized (and so a forbidden-content record is
+ * rejected) BEFORE the line is written, so the file never receives a payload. The append uses the
+ * `a` flag, so each record is one O_APPEND write.
+ */
+export class FileEvidenceStore {
+    accumulator;
+    path;
+    constructor(options) {
+        this.path = options.path;
+        this.accumulator = new EvidenceAccumulator(options.maxLive ?? DEFAULT_MAX_LIVE);
+    }
+    async append(record) {
+        const parsed = normalize(record);
+        await this.accumulator.add(parsed);
+        await appendFile(this.path, `${canonicalJson(parsed)}\n`, { flag: "a" });
+    }
+    get count() {
+        return this.accumulator.count;
+    }
+    live() {
+        return this.accumulator.live();
+    }
+    counters() {
+        return this.accumulator.counters();
+    }
+    completedNodeIds() {
+        return this.accumulator.completedNodeIds();
+    }
+    artifacts() {
+        return this.accumulator.artifacts();
+    }
+    async digest() {
+        return this.accumulator.digest();
+    }
+}
+//# sourceMappingURL=evidence-store.js.map

package/dist/orchestration/evidence-store.js.map

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

package/dist/orchestration/hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Content-addressing helpers shared by the orchestration module: a SHA-256 hex digest over bytes
+ * and a canonical JSON encoding with sorted object keys so a digest is stable across key order.
+ * Mirrors `@nifrajs/core`'s idempotency fingerprint (the content-free key precedent).
+ */
+/** SHA-256 of `bytes` as lowercase hex. Collision-resistant so a digest cannot be forged from content. */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/** SHA-256 hex of a UTF-8 string. */
+export declare function sha256HexOf(text: string): Promise<string>;
+/** Deterministic JSON with recursively sorted object keys. Arrays keep order. Rejects non-finite numbers. */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/orchestration/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/orchestration/hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,0GAA0G;AAC1G,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAQlE;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEzD;AAED,6GAA6G;AAC7G,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBpD"}

package/dist/orchestration/hash.js

@@ -0,0 +1,43 @@
+/**
+ * Content-addressing helpers shared by the orchestration module: a SHA-256 hex digest over bytes
+ * and a canonical JSON encoding with sorted object keys so a digest is stable across key order.
+ * Mirrors `@nifrajs/core`'s idempotency fingerprint (the content-free key precedent).
+ */
+const encoder = new TextEncoder();
+/** SHA-256 of `bytes` as lowercase hex. Collision-resistant so a digest cannot be forged from content. */
+export async function sha256Hex(bytes) {
+    // Copy into a fresh ArrayBuffer-backed view so the digest input is a concrete BufferSource
+    // regardless of the caller's backing buffer (SharedArrayBuffer-typed views are rejected).
+    const digest = await crypto.subtle.digest("SHA-256", new Uint8Array(bytes));
+    const view = new Uint8Array(digest);
+    let hex = "";
+    for (let i = 0; i < view.length; i++)
+        hex += view[i].toString(16).padStart(2, "0");
+    return hex;
+}
+/** SHA-256 hex of a UTF-8 string. */
+export function sha256HexOf(text) {
+    return sha256Hex(encoder.encode(text));
+}
+/** Deterministic JSON with recursively sorted object keys. Arrays keep order. Rejects non-finite numbers. */
+export function canonicalJson(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("non-finite JSON number");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    if (typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record)
+            .filter((key) => record[key] !== undefined)
+            .sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    throw new TypeError(`cannot canonicalize ${typeof value}`);
+}
+//# sourceMappingURL=hash.js.map

package/dist/orchestration/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/orchestration/hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;AAEjC,0GAA0G;AAC1G,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAiB;IAC/C,2FAA2F;IAC3F,0FAA0F;IAC1F,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAA;IAC3E,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAA;IACnC,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,IAAK,IAAI,CAAC,CAAC,CAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC9F,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;AACxC,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9E,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAA;QAC1E,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;IAC1F,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,KAAgC,CAAA;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;aAC7B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;aAC1C,IAAI,EAAE,CAAA;QACT,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;IACnG,CAAC;IACD,MAAM,IAAI,SAAS,CAAC,uBAAuB,OAAO,KAAK,EAAE,CAAC,CAAA;AAC5D,CAAC"}

package/dist/orchestration/host.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The OrchestrationHost: the lifecycle owner for a compiled {@link RunPlan}. It does not schedule
+ * work itself - each top-level DAG layer is handed to a kernel {@link WorkflowRunner}, exactly as
+ * {@link compileRunPlan} would fold them into one `sequence`. Driving layer by layer gives a safe
+ * pause boundary (in-flight nodes finish; no new layer starts) and a cancellation seam (the layer's
+ * runner and any bounded subagent share the run's abort signal) without a second engine.
+ *
+ * Every transition is guarded by an explicit state machine: an illegal transition returns a stable
+ * code and mutates nothing. A terminal run is frozen - a late completion from an aborted layer
+ * cannot change its status, counters, or digest. Terminal results expose status, completed node ids,
+ * an order-independent evidence digest, artifact refs, counters, and a failure code only: never a
+ * step output, prompt, or payload.
+ */
+import type { CapabilityDescriptor } from "@nifrajs/agent/registry";
+import type { ArtifactPort, ArtifactRef, RunPlan } from "@nifrajs/agent-protocol";
+import type { StepCatalog } from "./catalog.js";
+import { type OrchestrationLimits } from "./compile.js";
+import { type EvidenceCounters, type EvidenceStore } from "./evidence-store.js";
+import { type HostPolicy } from "./policy.js";
+export type RunState = "submitted" | "running" | "paused" | "succeeded" | "failed" | "cancelled";
+/** Thrown on an illegal lifecycle transition or an unknown run. `code` is stable. */
+export declare class OrchestrationStateError extends Error {
+    readonly code: string;
+    constructor(reason: string, code: string);
+}
+/** Content-free progress view of a run. */
+export interface RunStatus {
+    readonly runId: string;
+    readonly state: RunState;
+    readonly planDigest: string;
+    readonly layerIndex: number;
+    readonly layerCount: number;
+    readonly counters: EvidenceCounters;
+}
+/** Deterministic terminal result. Outcome identity only - no step output, prompt, or payload. */
+export interface RunResult {
+    readonly runId: string;
+    readonly status: "succeeded" | "failed" | "cancelled";
+    readonly planDigest: string;
+    readonly completedNodeIds: readonly string[];
+    readonly evidenceDigest: string;
+    readonly artifacts: readonly ArtifactRef[];
+    readonly counters: EvidenceCounters;
+    readonly failureCode?: string;
+}
+export interface SubmitOptions {
+    /** Caller-supplied for reproducibility; defaults to a per-host monotonic id (no clock, no random). */
+    readonly runId?: string;
+    /** Caller-owned payload sink. Defaults to hash-and-discard. */
+    readonly artifactPort?: ArtifactPort;
+    /** Evidence store for this run. Defaults to a bounded {@link MemoryEvidenceStore}. */
+    readonly store?: EvidenceStore;
+}
+export interface OrchestrationHostOptions {
+    readonly catalog: StepCatalog;
+    readonly limits?: OrchestrationLimits;
+    /** Kernel step ceiling per layer. Generous by default so a full 256-node layer runs. */
+    readonly maxSteps?: number;
+    readonly maxDepth?: number;
+    /**
+     * Authoritative admission policy. When set, {@link OrchestrationHost.admit} refuses any capability
+     * descriptor that asks to run outside the policy's kinds, capability allowlist, isolation floor, or
+     * approval requirement. A descriptor, plan, model, or extension cannot override it.
+     */
+    readonly policy?: HostPolicy;
+}
+/** Owns run lifecycle and evidence projection over the kernel WorkflowRunner. */
+export declare class OrchestrationHost {
+    private readonly catalog;
+    private readonly limits;
+    private readonly maxSteps;
+    private readonly maxDepth;
+    private readonly policy;
+    private readonly vectors;
+    private readonly runs;
+    private counter;
+    constructor(options: OrchestrationHostOptions);
+    /**
+     * Admit a capability descriptor against the host policy before it can be invoked. Throws
+     * {@link OrchestrationStateError} (`E_POLICY_REJECTED`) carrying the admission reason when refused.
+     * With no policy configured this is a passthrough - the host admits nothing it is not told to gate.
+     */
+    admit(descriptor: CapabilityDescriptor): void;
+    /**
+     * Allocate the next monotonic child vector for a live run, addressing a decision boundary the run
+     * pauses on. Strictly increasing per run, so a decision carrying any other vector is provably stale.
+     */
+    openBoundaryVector(runId: string): number;
+    /**
+     * Parse, compile, and register a run in `submitted`. All structural ceilings and capability
+     * authority are enforced here (a `CompileError` with a stable code), so an over-limit or
+     * unauthorized plan never reaches `running`.
+     */
+    submit(source: RunPlan | unknown, options?: SubmitOptions): Promise<string>;
+    /** Content-free progress view. Throws `E_NOT_FOUND` for an unknown run. */
+    inspect(runId: string): RunStatus;
+    /** `submitted` -> `running`. Begins the driver. */
+    start(runId: string): void;
+    /** `running` -> `paused`. Takes effect at the next layer boundary; in-flight nodes finish. */
+    pause(runId: string): void;
+    /** `paused` -> `running`. Releases the layer boundary. */
+    resume(runId: string): void;
+    /**
+     * Cancel from any non-terminal state. Aborts the in-flight layer and any bounded subagent, frees a
+     * paused gate, and freezes the run in `cancelled`. A late completion cannot revive it.
+     */
+    cancel(runId: string): void;
+    /** Terminal result. Throws `E_NOT_TERMINAL` while the run is still live. */
+    result(runId: string): Promise<RunResult>;
+    /** Await the run reaching a terminal state, then return its result. */
+    settled(runId: string): Promise<RunResult>;
+    private require;
+    private transition;
+    private buildResult;
+    private drive;
+    /** Project one kernel event into a content-free evidence record. Frozen once the run is terminal. */
+    private project;
+    /** Walk the plan tree once: node kinds, idempotency flags, and the full id set. */
+    private indexPlan;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/orchestration/host.d.ts.map

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