@tickernelz/paperclip-pro-adapter-utils 2026.925.0

package/dist/acpx-engine/run-contracts.d.ts

@@ -0,0 +1,413 @@
+import type { AcpRuntime, AcpRuntimeHandle } from "acpx/runtime";
+import type { AdapterExecutionTarget, AdapterExecutionTargetPaperclipBridgeHandle, AdapterExecutionTargetProcessSessionBridgeHandle, PreparedAdapterExecutionTargetRuntime } from "@tickernelz/paperclip-pro-adapter-utils/execution-target";
+import type { WorkspaceRestoreOutcome } from "../workspace-restore-merge.js";
+/**
+ * The closed set of run resources the ledger can hold. The set is fixed; a new
+ * resource needs a new member here and a payload in `RunResourcePayloads`.
+ *
+ * `acp_runtime` is a composite of the runtime, the session handle, and the
+ * child process. `runtime.close()` is the one release boundary for all three.
+ *
+ * These are NOT resources and never enter the ledger: `sessionKey`, the
+ * environment lease, the realized execution target, the cleanup registrations,
+ * the reuse-store entries, the three OTel spans, the turn timer, the child
+ * stderr flush state, and the idle timers.
+ */
+export type ResourceId = "acp_runtime" | "staged_runtime" | "control_bridge" | "agent_bridge" | "managed_home" | "staging_lease";
+/**
+ * The outcome the ledger records for a resource when it leaves the ledger.
+ * `finalized` means the run released the resource here. `transferred` means the
+ * run handed ownership to settlement.
+ */
+export type ResourceDisposition = "finalized" | "transferred";
+/**
+ * The lifetime a cleanup belongs to.
+ *
+ * A `startup_rollback` cleanup runs only when startup fails, to undo a partial
+ * bring-up. A `per_run` cleanup runs at settlement, at the end of the run. A
+ * successful `seal()` promotes each promotable `startup_rollback` entry to
+ * `per_run`, because the resource now lives through the whole run.
+ */
+export type CleanupScope = "startup_rollback" | "per_run";
+/**
+ * The `acp_runtime` composite. `runtime.close()` releases the runtime, the
+ * session handle, and the child process together. Maps to the runtime, the
+ * session handle, and the spawned child that `execute.ts` builds in
+ * `buildRuntime`.
+ */
+export interface AcpRuntimeResource {
+    readonly runtime: AcpRuntime;
+    readonly sessionHandle: AcpRuntimeHandle;
+    /** The pid of the spawned agent child, or null before the first spawn. */
+    readonly childProcessPid: number | null;
+}
+/**
+ * The staged in-sandbox runtime and its one-time host-side cleanup. Maps to
+ * `AcpxPreparedRuntime.stagedRuntime` and `remoteStagingDispose`.
+ */
+export interface StagedRuntimeResource {
+    readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;
+    /** Remove the host-side staged temp. Fired only when the stage is dropped. */
+    readonly disposeStaged: () => Promise<void>;
+}
+/**
+ * The per-adapter managed-home seam. Maps to
+ * `AcpxPreparedRuntime.remoteManagedHomeTeardown` and `remoteStagingEnvDelta`.
+ */
+export interface ManagedHomeResource {
+    /**
+     * Per-run copy-back hook. Runs the auth copy-back and the workspace restore
+     * on every exit path. Resolves to the workspace-restore outcome — never
+     * rejects — so the run coordinator can surface a failed restore on the run
+     * record without changing the run's exit code or status.
+     */
+    readonly teardown: () => Promise<WorkspaceRestoreOutcome>;
+    /** The env keys the seam mutated on this run. */
+    readonly envDelta: Record<string, string>;
+}
+/**
+ * The per-session staging lease. Maps to
+ * `AcpxPreparedRuntime.sessionStagingLeaseRelease`.
+ */
+export interface StagingLeaseResource {
+    /** Release the staging lease so a later overlapping run can re-stage. */
+    readonly release: () => void;
+}
+/**
+ * Maps each resource id to its payload. The `control_bridge` is the Paperclip
+ * control-plane bridge; the `agent_bridge` is the agent process-session bridge.
+ */
+export interface RunResourcePayloads {
+    readonly acp_runtime: AcpRuntimeResource;
+    readonly staged_runtime: StagedRuntimeResource;
+    readonly control_bridge: AdapterExecutionTargetPaperclipBridgeHandle;
+    readonly agent_bridge: AdapterExecutionTargetProcessSessionBridgeHandle;
+    readonly managed_home: ManagedHomeResource;
+    readonly staging_lease: StagingLeaseResource;
+}
+/** One resource the caller registers into the ledger. */
+export interface RunResourceRegistration<Id extends ResourceId = ResourceId> {
+    readonly id: Id;
+    readonly payload: RunResourcePayloads[Id];
+    readonly scope: CleanupScope;
+    /**
+     * Marks a `startup_rollback` entry that `seal()` promotes to `per_run`.
+     * Default true. Set false to pin the entry as rollback-only. Ignored for a
+     * `per_run` entry.
+     */
+    readonly promotable?: boolean;
+    /**
+     * The ledger calls this once when it finalizes or transfers the resource. It
+     * records the disposition. It runs no release itself.
+     */
+    readonly onDisposition?: (disposition: ResourceDisposition) => void;
+}
+/** One resource the settlement claim carries out of the ledger. */
+export interface SettledResourceEntry<Id extends ResourceId = ResourceId> {
+    readonly id: Id;
+    readonly payload: RunResourcePayloads[Id];
+    readonly scope: CleanupScope;
+    readonly disposition: ResourceDisposition;
+}
+declare const READY_RUN_RESOURCES: unique symbol;
+declare const CONSUMED_RUN_RESOURCES: unique symbol;
+/**
+ * The sealed, validated resource set. Only `AcquiredRunResources.seal()`
+ * produces this brand. The turn reads its resources through this handle.
+ */
+export interface ReadyRunResources {
+    readonly [READY_RUN_RESOURCES]: true;
+    /** The payload for a resource id, or undefined when the slot is empty. */
+    get<Id extends ResourceId>(id: Id): RunResourcePayloads[Id] | undefined;
+    /** The scope of a resource id after promotion, or undefined when empty. */
+    scopeOf(id: ResourceId): CleanupScope | undefined;
+    /** True when the slot holds a resource. */
+    has(id: ResourceId): boolean;
+    /** The required ids that `seal()` validated. */
+    readonly sealed: readonly ResourceId[];
+}
+/**
+ * The one-time settlement claim. Only `AcquiredRunResources.takeForSettlement()`
+ * produces this brand. Settlement releases the resources this claim carries.
+ */
+export interface ConsumedRunResources {
+    readonly [CONSUMED_RUN_RESOURCES]: true;
+    /** The resources, each with its final scope and disposition. */
+    entries(): readonly SettledResourceEntry[];
+}
+/**
+ * The write surface the startup path holds while it acquires resources.
+ * `register` is the only writer. `seal` and `takeForSettlement` end the write
+ * phase. The state machine is `open -> sealed -> consumed` or `open ->
+ * consumed`.
+ */
+export interface AcquiredRunResources {
+    register<Id extends ResourceId>(registration: RunResourceRegistration<Id>): void;
+    seal(required: readonly ResourceId[]): ReadyRunResources;
+    takeForSettlement(): ConsumedRunResources;
+}
+/** The error the ledger throws on an out-of-order or duplicate operation. */
+export declare class LedgerStateError extends Error {
+    constructor(message: string);
+}
+/**
+ * The four phases a pre-turn failure can occur in. A pre-turn failure happens
+ * after the ledger acquires resources but before the turn runs.
+ */
+export interface PreTurnFailedCause {
+    readonly kind: "pre_turn_failed";
+    readonly phase: "runtime_create" | "handshake" | "session_handle_missing" | "session_configuration";
+    readonly error: Error;
+}
+/** The turn ran and failed with an error. */
+export interface TurnFailedCause {
+    readonly kind: "turn_failed";
+    readonly error: Error;
+}
+/** The caller cancelled the turn. */
+export interface TurnCancelledCause {
+    readonly kind: "turn_cancelled";
+    readonly reason: string;
+}
+/** The turn hit its wall-clock timeout. */
+export interface TurnTimedOutCause {
+    readonly kind: "turn_timed_out";
+    readonly timeoutSec: number;
+}
+/** A cause that the turn itself produced. Disjoint from `PreTurnFailedCause`. */
+export type TurnCause = TurnFailedCause | TurnCancelledCause | TurnTimedOutCause;
+/** Any cause that leads a run into settlement. */
+export type SettlementCause = PreTurnFailedCause | TurnCause;
+/**
+ * Startup produced a ready runtime. The turn can run against these resources.
+ */
+export interface StartupReady {
+    readonly kind: "ready";
+    readonly resources: ReadyRunResources;
+    readonly context: AcpRunContext;
+}
+/**
+ * Startup failed after it acquired resources, so the run must settle them. A
+ * build failure and a partial-bridge failure do NOT reach here — they throw,
+ * and the coordinator owns that rollback (Phase 20).
+ */
+export interface StartupSettle {
+    readonly kind: "settle";
+    readonly cause: PreTurnFailedCause;
+    readonly resources: ConsumedRunResources;
+}
+export type StartupResult = StartupReady | StartupSettle;
+/**
+ * The turn finished and released everything in place. It carries no resources,
+ * so settlement has nothing to do.
+ */
+export interface FinalizedTurn {
+    readonly kind: "finalized";
+}
+/** The turn failed. Settlement releases the carried resources. */
+export interface FailedTurn {
+    readonly kind: "failed";
+    readonly cause: TurnFailedCause;
+    readonly resources: ConsumedRunResources;
+}
+/** The caller cancelled the turn. Settlement releases the carried resources. */
+export interface CancelledTurn {
+    readonly kind: "cancelled";
+    readonly cause: TurnCancelledCause;
+    readonly resources: ConsumedRunResources;
+}
+/** The turn timed out. Settlement releases the carried resources. */
+export interface TimedOutTurn {
+    readonly kind: "timed_out";
+    readonly cause: TurnTimedOutCause;
+    readonly resources: ConsumedRunResources;
+}
+/** The four ways a turn completes. Only `FinalizedTurn` is resourceless. */
+export type TurnCompletion = FinalizedTurn | FailedTurn | CancelledTurn | TimedOutTurn;
+/** The host site runs on the host. The sandbox site runs in a remote runner. */
+export type RunSiteKind = "host" | "sandbox";
+/**
+ * The synchronous plan a site produces before the fingerprint build. `plan()`
+ * must be synchronous, because `sessionCwd` is a fingerprint input.
+ */
+export interface SitePlan {
+    /**
+     * The cwd the session binds to and the fingerprint reads. `placeWorkspace` is
+     * not its source; the site derives it before it places the workspace.
+     */
+    readonly sessionCwd: string;
+    /**
+     * The host-only spawn cwd for the relay proxy on the remote process-session
+     * lane. Undefined on every other lane. Maps to `AcpxPreparedRuntime.
+     * hostSpawnCwd`.
+     */
+    readonly spawnCwd: string | undefined;
+    /** True only for a sandbox target, where the run emits real OTel spans. */
+    readonly tracingEnabled: boolean;
+}
+/** One referenced project whose staging into the sandbox failed. */
+export interface ReferencedProjectStagingFailure {
+    readonly projectId: string;
+    /** The failure reason. A reader of the run sees why the project dropped. */
+    readonly error: string;
+}
+/**
+ * The result of placing the workspace. Carries the referenced-project staging
+ * failures the run reports back on its result.
+ */
+export interface PlacedWorkspace {
+    readonly referencedProjectStagingFailures: readonly ReferencedProjectStagingFailure[];
+}
+/** The transport handles the site started for the run. */
+export interface RunSiteTransport {
+    readonly controlBridge: AdapterExecutionTargetPaperclipBridgeHandle | null;
+    readonly agentBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null;
+}
+/** What the host site's store can save: the live runtime and session handle. */
+export interface HostReuseCandidate {
+    readonly runtime: AcpRuntime;
+    readonly sessionHandle: AcpRuntimeHandle;
+}
+/** What the sandbox site's store can save: the staged files. */
+export interface SandboxReuseCandidate {
+    readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;
+}
+export type RunSiteReuseCandidate = HostReuseCandidate | SandboxReuseCandidate;
+/** Construction options for a `SessionReuseStore`. */
+export interface SessionReuseStoreOptions {
+    /**
+     * The optional per-entry idle timeout, in milliseconds. When set, `evictIdle`
+     * drops an entry that stayed idle longer than this bound.
+     */
+    readonly idleMs?: number;
+}
+/**
+ * The per-site store that saves a reuse candidate across runs. The store is
+ * generic in the saved type, so a generic `save` cannot know what a site saves.
+ * `RunSite.reuseCandidate()` names the concrete type per site.
+ */
+export interface SessionReuseStore<T> {
+    borrow(sessionKey: string): T | undefined;
+    save(sessionKey: string, entry: T): void;
+    /**
+     * Identity-guarded removal that fires the idempotent release. It removes the
+     * key synchronously, so a later reuse never reads a discarded entry. It
+     * returns a promise the caller can await when the release must finish before
+     * the run releases a downstream resource (e.g. the staging lease).
+     */
+    discard(sessionKey: string): void | Promise<void>;
+    /**
+     * Run-start idle sweep. It removes each stale key synchronously, so
+     * `buildRuntime` never reuses an expired entry. It returns a promise the
+     * caller can await so the sweep completes before the run reads the cache.
+     */
+    evictIdle(now: number): void | Promise<void>;
+}
+/**
+ * A run site. The host site and the sandbox site differ in what they place,
+ * what transport they start, and what their store saves.
+ */
+export interface RunSite<TReuse extends RunSiteReuseCandidate = RunSiteReuseCandidate> {
+    readonly kind: RunSiteKind;
+    /** Synchronous. Runs before the fingerprint build. */
+    plan(context: AcpRunContext): SitePlan;
+    placeWorkspace(context: AcpRunContext): Promise<PlacedWorkspace>;
+    startTransport(context: AcpRunContext): Promise<RunSiteTransport>;
+    reuse(): SessionReuseStore<TReuse>;
+    /** Names the concrete candidate this site's store can save. */
+    reuseCandidate(resources: ReadyRunResources): TReuse;
+    syncBack(context: AcpRunContext): Promise<void>;
+}
+export type AcpxRunMode = "persistent" | "oneshot";
+export type AcpxPermissionMode = "approve-all" | "approve-reads" | "deny-all";
+export type AcpxNonInteractivePermissions = "deny" | "fail";
+/** One MCP server, in the shape the fingerprint reads. */
+export interface McpServerIdentity {
+    readonly name: string;
+    readonly url: string;
+    readonly connectionId: string;
+}
+/** The Paperclip Claude settings the fingerprint reads. */
+export interface PaperclipClaudeSettingsIdentity {
+    readonly allow: readonly string[];
+    readonly additionalDirectories: readonly string[];
+    readonly defaultMode: string;
+}
+/**
+ * The 17 fields the session fingerprint hashes. Company, agent, and task
+ * identifiers are NOT here; they scope the outer session key only (see
+ * `SessionKeyIdentity`). A change to any field here invalidates a warm handle
+ * or a resumable session and forces a fresh launch.
+ */
+export interface SessionFingerprintIdentity {
+    readonly acpxAgent: string;
+    readonly agentCommand: string;
+    readonly cwd: string;
+    readonly mode: AcpxRunMode;
+    readonly permissionMode: AcpxPermissionMode;
+    readonly nonInteractivePermissions: AcpxNonInteractivePermissions;
+    readonly requestedModel: string;
+    readonly requestedThinkingEffort: string;
+    readonly fastMode: boolean;
+    readonly remoteExecutionIdentity: Record<string, unknown> | null;
+    readonly additionalSourcesIdentity: Record<string, unknown>;
+    readonly skillsIdentity: Record<string, unknown>;
+    readonly skillPromptInstructions: string;
+    readonly paperclipClaudeSettings: PaperclipClaudeSettingsIdentity | null;
+    readonly mcpServers: readonly McpServerIdentity[];
+    readonly secretManifestHash: string;
+    readonly adapterEnvHash: string;
+}
+/**
+ * The company, agent, and task parts of the session key. The key form is
+ * `paperclip:companyId:agentId:taskKey:fingerprint`. These parts stay out of
+ * the fingerprint hash.
+ */
+export interface SessionKeyIdentity {
+    readonly companyId: string;
+    readonly agentId: string;
+    readonly taskKey: string;
+}
+declare const RUN_SCOPED_CONTRIBUTION: unique symbol;
+declare const LAUNCH_ENVIRONMENT: unique symbol;
+/**
+ * A launch-environment contribution that lives for one run only. The run API
+ * key and every bridge token are run-scoped. The brand makes this type
+ * non-transferable: no reuse payload type can hold it (Amendment B).
+ */
+export interface RunScopedContribution {
+    readonly scope: "run";
+    readonly env: Record<string, string>;
+    readonly [RUN_SCOPED_CONTRIBUTION]: true;
+}
+/**
+ * A launch-environment contribution that lives for the whole session. The Codex
+ * auth copy-back material is session-scoped.
+ */
+export interface SessionScopedContribution {
+    readonly scope: "session";
+    readonly env: Record<string, string>;
+}
+export type LaunchEnvironmentContribution = RunScopedContribution | SessionScopedContribution;
+/**
+ * The finalized launch environment. Only `finalizeLaunchEnvironment()`
+ * (Phase 17) produces this brand. No reuse payload type can hold it.
+ */
+export interface LaunchEnvironment {
+    readonly [LAUNCH_ENVIRONMENT]: true;
+    readonly env: Readonly<Record<string, string>>;
+}
+/**
+ * The context the coordinator threads through the run. The site reads the
+ * execution target for its effective capabilities.
+ */
+export interface AcpRunContext {
+    readonly executionTarget: AdapterExecutionTarget;
+    readonly fingerprintIdentity: SessionFingerprintIdentity;
+    readonly keyIdentity: SessionKeyIdentity;
+    readonly fingerprint: string;
+    readonly sessionKey: string;
+    readonly launchEnvironment: LaunchEnvironment;
+}
+export {};
+//# sourceMappingURL=run-contracts.d.ts.map

package/dist/acpx-engine/run-contracts.d.ts.map

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

package/dist/acpx-engine/run-contracts.js

@@ -0,0 +1,20 @@
+// Contract types for the ACPX run coordinator refactor.
+//
+// This module declares the types only. No production code consumes them yet.
+// Each placeholder type maps to a field that `AcpxPreparedRuntime` carries in
+// `execute.ts` today. The later coordinator phases move the ownership of those
+// fields onto these contracts one seam at a time.
+//
+// Two brands (`ReadyRunResources`, `ConsumedRunResources`) mark a resource set
+// that only the resource ledger can produce. Two more brands mark a run-scoped
+// launch contribution and the finalized launch environment. A brand is a private
+// `unique symbol`, so no other module can build a branded value by a plain
+// object literal. Only the module that owns the symbol returns the value.
+/** The error the ledger throws on an out-of-order or duplicate operation. */
+export class LedgerStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LedgerStateError";
+    }
+}
+//# sourceMappingURL=run-contracts.js.map

package/dist/acpx-engine/run-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-contracts.js","sourceRoot":"","sources":["../../src/acpx-engine/run-contracts.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,+EAA+E;AAC/E,kDAAkD;AAClD,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,iFAAiF;AACjF,2EAA2E;AAC3E,0EAA0E;AA4L1E,6EAA6E;AAC7E,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/acpx-engine/run-contracts.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-contracts.test.d.ts.map

package/dist/acpx-engine/run-contracts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-contracts.test.d.ts","sourceRoot":"","sources":["../../src/acpx-engine/run-contracts.test.ts"],"names":[],"mappings":""}

package/dist/acpx-engine/run-contracts.test.js

@@ -0,0 +1,57 @@
+// Compile-time type tests for the run contracts.
+//
+// The real assertion in each test is that this file compiles. A `@ts-expect-error`
+// marks an assignment that MUST fail to typecheck; if it starts to compile, tsc
+// reports the unused directive and the typecheck fails. The runtime body only
+// keeps vitest happy, so each test names the property it proves.
+import { describe, expect, it } from "vitest";
+describe("run contracts", () => {
+    it("test_a_turn_cause_is_not_assignable_where_pre_turn_failed_cause_is_required", () => {
+        function requiresPreTurn(_cause) { }
+        const turnCause = { kind: "turn_failed", error: new Error("boom") };
+        // A turn cause has a different `kind` and no `phase`, so it is not
+        // assignable where a `PreTurnFailedCause` is required.
+        // @ts-expect-error a TurnCause is not a PreTurnFailedCause.
+        requiresPreTurn(turnCause);
+        expect(turnCause.kind).toBe("turn_failed");
+    });
+    it("test_only_seal_produces_ready_run_resources_and_only_take_for_settlement_produces_consumed_run_resources", () => {
+        // The assertions live in an unexecuted function so tsc checks the types
+        // without a runtime call on a synthetic ledger.
+        function _assertBrands(ledger) {
+            // `seal()` is the only source of a `ReadyRunResources`;
+            // `takeForSettlement()` is the only source of a `ConsumedRunResources`.
+            const ready = ledger.seal([]);
+            const consumed = ledger.takeForSettlement();
+            // The two brands are distinct: neither result is assignable to the other.
+            // @ts-expect-error a ReadyRunResources is not a ConsumedRunResources.
+            const _crossA = ready;
+            // @ts-expect-error a ConsumedRunResources is not a ReadyRunResources.
+            const _crossB = consumed;
+            // A plain object cannot stand in for a branded result; it lacks the
+            // private brand that only `seal()` / `takeForSettlement()` can set.
+            // @ts-expect-error missing the private ready brand.
+            const _fakeReady = {
+                get: () => undefined,
+                scopeOf: () => undefined,
+                has: () => false,
+                sealed: [],
+            };
+            // @ts-expect-error missing the private consumed brand.
+            const _fakeConsumed = { entries: () => [] };
+            void ready;
+            void consumed;
+            void _crossA;
+            void _crossB;
+            void _fakeReady;
+            void _fakeConsumed;
+        }
+        void _assertBrands;
+        expect(true).toBe(true);
+    });
+    it("test_session_fingerprint_identity_has_no_company_agent_or_task_member", () => {
+        const _ok = true;
+        expect(_ok).toBe(true);
+    });
+});
+//# sourceMappingURL=run-contracts.test.js.map

package/dist/acpx-engine/run-contracts.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-contracts.test.js","sourceRoot":"","sources":["../../src/acpx-engine/run-contracts.test.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,EAAE;AACF,mFAAmF;AACnF,gFAAgF;AAChF,8EAA8E;AAC9E,iEAAiE;AAEjE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAgB9C,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,6EAA6E,EAAE,GAAG,EAAE;QACrF,SAAS,eAAe,CAAC,MAA0B,IAAS,CAAC;QAC7D,MAAM,SAAS,GAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAE/E,mEAAmE;QACnE,uDAAuD;QACvD,4DAA4D;QAC5D,eAAe,CAAC,SAAS,CAAC,CAAC;QAE3B,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0GAA0G,EAAE,GAAG,EAAE;QAClH,wEAAwE;QACxE,gDAAgD;QAChD,SAAS,aAAa,CAAC,MAA4B;YACjD,wDAAwD;YACxD,wEAAwE;YACxE,MAAM,KAAK,GAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACjD,MAAM,QAAQ,GAAyB,MAAM,CAAC,iBAAiB,EAAE,CAAC;YAElE,0EAA0E;YAC1E,sEAAsE;YACtE,MAAM,OAAO,GAAyB,KAAK,CAAC;YAC5C,sEAAsE;YACtE,MAAM,OAAO,GAAsB,QAAQ,CAAC;YAE5C,oEAAoE;YACpE,oEAAoE;YACpE,oDAAoD;YACpD,MAAM,UAAU,GAAsB;gBACpC,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;gBACpB,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS;gBACxB,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK;gBAChB,MAAM,EAAE,EAAE;aACX,CAAC;YACF,uDAAuD;YACvD,MAAM,aAAa,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAElE,KAAK,KAAK,CAAC;YACX,KAAK,QAAQ,CAAC;YACd,KAAK,OAAO,CAAC;YACb,KAAK,OAAO,CAAC;YACb,KAAK,UAAU,CAAC;YAChB,KAAK,aAAa,CAAC;QACrB,CAAC;QAED,KAAK,aAAa,CAAC;QACnB,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;QAM/E,MAAM,GAAG,GAAY,IAAI,CAAC;QAC1B,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/acpx-engine/run-coordinator.d.ts

@@ -0,0 +1,57 @@
+import type { AcquiredRunResources, ConsumedRunResources, PreTurnFailedCause, ResourceDisposition, ResourceId, StartupReady, StartupResult, TurnCompletion } from "./run-contracts.js";
+/** One resource's final disposition, as the coordinator or settlement records it. */
+export interface ResourceDispositionRecord {
+    readonly id: ResourceId;
+    readonly disposition: ResourceDisposition;
+}
+/** The per-resource disposition report the coordinator records at each end. */
+export interface SettlementDispositionReport {
+    readonly records: readonly ResourceDispositionRecord[];
+}
+/** The cause the coordinator hands to settlement. A clean turn carries no cause. */
+export type SettlementReason = {
+    readonly kind: "pre_turn";
+    readonly cause: PreTurnFailedCause;
+} | {
+    readonly kind: "turn";
+    readonly completion: TurnCompletion;
+};
+/** The outcome the coordinator hands to result reproduction. */
+export type ReproducibleOutcome = SettlementReason;
+/**
+ * The four steps the coordinator sequences, plus the run ledger. The engine
+ * supplies each step; the coordinator owns only the order and the startup
+ * rollback. This keeps the coordinator free of the engine's private run state.
+ */
+export interface RunPlan<TResult> {
+    /** The one run ledger for the attempt. The coordinator creates it (see `runAttempt`). */
+    readonly ledger: AcquiredRunResources;
+    /**
+     * Run the startup sequence. It returns a `ready` or a `settle` result, or it
+     * throws on a build failure or a partial-bridge failure.
+     */
+    startup(): Promise<StartupResult>;
+    /**
+     * Replay the `startup_rollback` entries the partial ledger carries. The
+     * coordinator calls it only on a startup throw, with the claimed entries.
+     */
+    rollbackStartup(consumed: ConsumedRunResources): Promise<void> | void;
+    /** Record the per-resource disposition report at the end of the run. */
+    recordDisposition(report: SettlementDispositionReport): void;
+    /** Run the turn against the ready resources. It never rejects. */
+    runTurn(ready: StartupReady): Promise<TurnCompletion>;
+    /**
+     * Settle the run's resources for the given reason. The one cleanup owner. A
+     * synchronous return adds no awaited boundary, so a step that already settled
+     * inline keeps the caller's timing unchanged.
+     */
+    settle(reason: SettlementReason): void | Promise<void>;
+    /** Reproduce the external result after settlement. */
+    reproduceResult(outcome: ReproducibleOutcome): TResult | Promise<TResult>;
+}
+/**
+ * Run the attempt through the routing table. The coordinator is the one owner of
+ * the startup-to-settlement order.
+ */
+export declare function runAttempt<TResult>(plan: RunPlan<TResult>): Promise<TResult>;
+//# sourceMappingURL=run-coordinator.d.ts.map

package/dist/acpx-engine/run-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-coordinator.d.ts","sourceRoot":"","sources":["../../src/acpx-engine/run-coordinator.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACf,MAAM,oBAAoB,CAAC;AAE5B,qFAAqF;AACrF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;CAC3C;AAED,+EAA+E;AAC/E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACxD;AAED,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnE,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,OAAO,CAAC,OAAO;IAC9B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAClC;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACtE,wEAAwE;IACxE,iBAAiB,CAAC,MAAM,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAC7D,kEAAkE;IAClE,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACtD;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,sDAAsD;IACtD,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CA+BlF"}

package/dist/acpx-engine/run-coordinator.js

@@ -0,0 +1,63 @@
+// The run coordinator.
+//
+// One `run()` coordinator owns the attempt. It sequences four steps: startup,
+// turn, settlement, and result reproduction. It holds the routing table as
+// data:
+//
+//   * A build failure or a partial-bridge failure throws from startup. The
+//     coordinator's one catch replays the `startup_rollback` entries through the
+//     partial ledger, records the disposition report, and rethrows.
+//   * A runtime-create, handshake, missing-handle, or configuration failure
+//     produces a `settle` result. The coordinator settles the resources, then
+//     reproduces the error result.
+//   * Every other startup outcome produces a `ready` result. The coordinator
+//     runs the turn, settles the resources, then reproduces the turn result.
+//
+// The coordinator has no catch around the turn: the turn never rejects and
+// returns a typed `TurnCompletion` (Phase 21). The external result is reproduced
+// AFTER settlement, so a caller never observes a result before the run releases
+// its resources.
+/**
+ * Run the attempt through the routing table. The coordinator is the one owner of
+ * the startup-to-settlement order.
+ */
+export async function runAttempt(plan) {
+    let startupResult;
+    try {
+        startupResult = await plan.startup();
+    }
+    catch (startupError) {
+        // The coordinator's only catch wraps startup. A build failure and a
+        // partial-bridge failure reach here. Claim the partial ledger, replay its
+        // `startup_rollback` entries, record the disposition report (each entry the
+        // rollback released is `finalized`), and rethrow the original error.
+        const consumed = plan.ledger.takeForSettlement();
+        await plan.rollbackStartup(consumed);
+        plan.recordDisposition(finalizedReport(consumed));
+        throw startupError;
+    }
+    if (startupResult.kind === "settle") {
+        // A pre-turn failure after the ledger acquired resources. Settle the
+        // resources, then reproduce the error result AFTER settlement.
+        const reason = { kind: "pre_turn", cause: startupResult.cause };
+        const settled = plan.settle(reason);
+        if (settled)
+            await settled;
+        return plan.reproduceResult(reason);
+    }
+    // The ready path: run the turn, settle, then reproduce the result. There is no
+    // catch around the turn — `runTurn` never rejects.
+    const completion = await plan.runTurn(startupResult);
+    const reason = { kind: "turn", completion };
+    const settled = plan.settle(reason);
+    if (settled)
+        await settled;
+    return plan.reproduceResult(reason);
+}
+/** Build a disposition report that marks every claimed entry `finalized`. */
+function finalizedReport(consumed) {
+    return {
+        records: consumed.entries().map((entry) => ({ id: entry.id, disposition: "finalized" })),
+    };
+}
+//# sourceMappingURL=run-coordinator.js.map

package/dist/acpx-engine/run-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-coordinator.js","sourceRoot":"","sources":["../../src/acpx-engine/run-coordinator.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,QAAQ;AACR,EAAE;AACF,2EAA2E;AAC3E,iFAAiF;AACjF,oEAAoE;AACpE,4EAA4E;AAC5E,8EAA8E;AAC9E,mCAAmC;AACnC,6EAA6E;AAC7E,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,iFAAiF;AACjF,gFAAgF;AAChF,iBAAiB;AAgEjB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAU,IAAsB;IAC9D,IAAI,aAA4B,CAAC;IACjC,IAAI,CAAC;QACH,aAAa,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACvC,CAAC;IAAC,OAAO,YAAY,EAAE,CAAC;QACtB,oEAAoE;QACpE,0EAA0E;QAC1E,4EAA4E;QAC5E,qEAAqE;QACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QACjD,MAAM,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,iBAAiB,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;QAClD,MAAM,YAAY,CAAC;IACrB,CAAC;IAED,IAAI,aAAa,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,qEAAqE;QACrE,+DAA+D;QAC/D,MAAM,MAAM,GAAqB,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,CAAC;QAClF,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,OAAO;YAAE,MAAM,OAAO,CAAC;QAC3B,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,+EAA+E;IAC/E,mDAAmD;IACnD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IACrD,MAAM,MAAM,GAAqB,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,OAAO;QAAE,MAAM,OAAO,CAAC;IAC3B,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED,6EAA6E;AAC7E,SAAS,eAAe,CAAC,QAA8B;IACrD,OAAO;QACL,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,WAAoB,EAAE,CAAC,CAAC;KAClG,CAAC;AACJ,CAAC"}

package/dist/acpx-engine/run-coordinator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-coordinator.test.d.ts.map