@starci/hfs 4.11.21 → 4.12.0

package/runtime/engine/db/provider-reservations.d.mts

@@ -0,0 +1,169 @@
+import type { StoreHandle } from './sqlite-types.mjs';
+/** The part of the machine module this one is built from: the refusal check, the JSON helpers and the id generator. */
+export interface ReservationDeps {
+    need(ok: unknown, message: string, code?: string): void;
+    parse<T = unknown>(text: string | null | undefined): T | null;
+    toJson(value: unknown): string | null;
+    hex(bytes: number): string;
+}
+/** One provider/account slot reservation as the store reports it. */
+export interface ProviderReservation {
+    id: string;
+    fence: number;
+    attemptId: string;
+    provider: string;
+    account: string;
+    model: string;
+    role: string;
+    state: string;
+    slots: number;
+    amountUnit: 'concurrent-launch';
+    maxParallel: number;
+    handle: string | null;
+    pid: number | null;
+    launchIdentity: string | null;
+    hostRequestId: string | null;
+    createdAt: number;
+    updatedAt: number;
+    scope: unknown;
+    estimate: unknown;
+    quota: unknown;
+    override: unknown;
+    releasedAt: number | null;
+    proof: unknown;
+}
+type HostReceipt = Record<string, any>;
+/** The host's affirmation that a replayed worker start left no effect. */
+export interface HostAffirmation {
+    requestId?: string;
+    kind?: string;
+    replayed?: boolean;
+    outcome?: string;
+    effectState?: string;
+    receipt?: HostReceipt;
+}
+/** The proof a caller presents to observe or release a reservation: what it saw end, bound to the receipt's own identity. */
+export interface ReservationProof {
+    kind?: string;
+    confirmed?: boolean;
+    handle?: string | null;
+    pid?: number | null;
+    receiptUpdatedAt?: number;
+    restartedAt?: number;
+    hostRequestId?: string;
+    requestState?: string;
+    dispatchId?: string;
+    dispatchStatus?: string;
+    processVerdict?: string;
+    terminalProof?: string;
+    launchIdentity?: string;
+    scopeId?: unknown;
+    effectState?: string;
+    hostAffirmation?: HostAffirmation;
+}
+/** The Dispatch states in which the worker has ended (Orca's own terminal states of a Dispatch). */
+export declare const ENDED_DISPATCH_STATES: readonly string[];
+/** The options of providerReservations. */
+export interface ReservationFilter {
+    provider?: string | null | undefined;
+    account?: string | null | undefined;
+    activeOnly?: boolean;
+    tier?: string | null;
+    limit?: number | string | null;
+}
+/** The options of reserveProvider. */
+export interface ReserveOptions {
+    provider?: string;
+    account?: string;
+    attemptId?: string;
+    role?: string;
+    model?: string;
+    maxParallel?: number;
+    scope?: unknown;
+    quota?: unknown;
+    estimate?: unknown;
+    override?: unknown;
+}
+/** The identity of one fenced reservation. */
+export interface ReservationKey {
+    id?: string | undefined;
+    fence?: number | undefined;
+    attemptId?: string | undefined;
+}
+/** The options of markProviderReservation. */
+export interface MarkOptions extends ReservationKey {
+    provider?: string;
+    account?: string;
+    model?: string;
+    role?: string;
+    state?: string;
+    launchIdentity?: string | null;
+    hostRequestId?: string | null;
+    handle?: string | null;
+    pid?: number | null;
+}
+export declare function providerReservationMethods(deps: ReservationDeps): {
+    reserveProvider: (m: StoreHandle, { provider, account, attemptId, role, model, maxParallel, scope, quota, estimate, override }?: ReserveOptions) => {
+        ok: boolean;
+        reason: string;
+        reservation: ProviderReservation | null;
+        reused?: never;
+        running?: never;
+        maxParallel?: never;
+    } | {
+        ok: boolean;
+        reason: string;
+        reused: boolean;
+        reservation: ProviderReservation | null;
+        running?: never;
+        maxParallel?: never;
+    } | {
+        ok: boolean;
+        reason: string;
+        running: number;
+        maxParallel: number;
+        reservation?: never;
+        reused?: never;
+    };
+    providerReservations: (m: StoreHandle, { provider, account, activeOnly, tier, limit }?: ReservationFilter) => ProviderReservation[];
+    providerReservationUsage: (m: StoreHandle, { provider, account }?: {
+        provider?: string | null | undefined;
+        account?: string;
+    }) => {
+        running: number;
+        reservations: ProviderReservation[];
+        observed: true;
+    };
+    markProviderReservation: (m: StoreHandle, { id, fence, attemptId, provider, account, model, role, state, launchIdentity, hostRequestId, handle, pid }?: MarkOptions) => {
+        ok: boolean;
+        reason: string;
+        reservation?: never;
+    } | {
+        ok: boolean;
+        reason: string;
+        reservation: ProviderReservation | null;
+    } | {
+        ok: boolean;
+        reservation: ProviderReservation | null;
+        reason?: never;
+    };
+    releaseProviderReservation: (m: StoreHandle, { id, fence, attemptId, proof }?: ReservationKey & {
+        proof?: ReservationProof | null;
+    }) => {
+        ok: boolean;
+        reason: string;
+        reused?: never;
+        reservation?: never;
+    } | {
+        ok: boolean;
+        reused: boolean;
+        reservation: ProviderReservation | null;
+        reason?: never;
+    } | {
+        ok: boolean;
+        reason: string;
+        reservation: ProviderReservation | null;
+        reused?: never;
+    };
+};
+export {};

package/runtime/engine/db/provider-reservations.mjs

@@ -1,127 +1,149 @@
-// Provider receipt SQL participates in the machine writer's existing fenced transactions.
-
+const oneOf = (list, value) => typeof value === 'string' && list.includes(value);
 // The host restarted after this receipt's last update, so no launch of that update can still run: the proof is bound to the receipt's own
 // update instant (a later progress observation refuses it) and, when the receipt names a host request, to that request's absence in the current runtime.
 const hostRestartedEnd = (row, proof) => proof?.kind === 'host-restarted' && proof.confirmed === true && !row.handle && !row.pid
-  && proof.receiptUpdatedAt === row.updated_at && Number.isFinite(proof.restartedAt) && proof.restartedAt > row.updated_at
-  && (!row.host_request_id || (proof.hostRequestId === row.host_request_id && proof.requestState === 'absent'));
-
+    && proof.receiptUpdatedAt === row.updated_at && typeof proof.restartedAt === 'number' && Number.isFinite(proof.restartedAt) && proof.restartedAt > row.updated_at
+    && (!row.host_request_id || (proof.hostRequestId === row.host_request_id && proof.requestState === 'absent'));
 /** The Dispatch states in which the worker has ended (Orca's own terminal states of a Dispatch). */
 export const ENDED_DISPATCH_STATES = Object.freeze(['failed', 'completed', 'stopped', 'released', 'cancelled']);
-
 // The host request of this receipt resolved to a Dispatch Orca reports ended, whose terminal (when it has one) is gone or disconnected and carries no process.
 const dispatchEndedEnd = (row, proof) => proof?.kind === 'dispatch-ended' && proof.confirmed === true && !row.handle && !row.pid
-  && Boolean(row.host_request_id) && proof.hostRequestId === row.host_request_id
-  && typeof proof.dispatchId === 'string' && proof.dispatchId.length > 0 && ENDED_DISPATCH_STATES.includes(proof.dispatchStatus)
-  && proof.processVerdict === 'none' && (!proof.handle || ['gone', 'disconnected'].includes(proof.terminalProof));
-
-export function providerReservationMethods({ need, parse, toJson, hex }) {
-  // Provider/account slots are shared by all five agent roles. A clock timeout is not exit evidence.
-  const providerReservationRow = (row) => row ? { id: row.id, fence: row.fence, attemptId: row.attempt_id,
-    provider: row.provider, account: row.account, model: row.model, role: row.role, state: row.state,
-    slots: row.slots, amountUnit: 'concurrent-launch', maxParallel: row.max_parallel,
-    handle: row.handle, pid: row.pid, launchIdentity: row.launch_identity, hostRequestId: row.host_request_id, createdAt: row.created_at, updatedAt: row.updated_at,
-    scope: parse(row.scope_json), estimate: parse(row.estimate_json), quota: parse(row.quota_json),
-    override: parse(row.override_json), releasedAt: row.released_at, proof: parse(row.proof_json) } : null;
-  // `tier` keeps the rows whose scope names that tier; `limit` returns the newest rows first (the tier's recent picks).
-  function providerReservations(m, { provider = null, account = null, activeOnly = false, tier = null, limit = null } = {}) {
-    const where = [], args = [];
-    if (tier !== null) { where.push("json_extract(scope_json,'$.tier')=?"); args.push(tier); }
-    if (provider !== null) { where.push('provider=?'); args.push(provider); }
-    if (account !== null) { where.push('account=?'); args.push(account); }
-    if (activeOnly) where.push("state<>'released'");
-    const clause = where.length ? ` WHERE ${where.join(' AND ')}` : '';
-    const order = limit === null ? 'ORDER BY fence' : `ORDER BY fence DESC LIMIT ${Math.trunc(Number(limit)) || 0}`;
-    return m.db.prepare(`SELECT * FROM provider_reservations${clause} ${order}`).all(...args).map(providerReservationRow);
-  }
-  function providerReservationUsage(m, { provider, account = 'default' } = {}) {
-    const reservations = providerReservations(m, { provider, account, activeOnly: true });
-    return { running: reservations.length, reservations, observed: true };
-  }
-  /** Atomic last-slot admission. Replays preserve the original receipt; changed attempt meaning refuses. */
-  function reserveProvider(m, { provider, account = 'default', attemptId, role, model, maxParallel, scope = null, quota = null, estimate = null, override = null } = {}) {
-    need([provider, account, attemptId, model].every((value) => typeof value === 'string' && value.trim()), 'provider reservation needs provider, account, attemptId and concrete model');
-    need(typeof role === 'string' && role.trim(), 'provider reservation needs one agent role'); // The DDL owns the allowed role domain.
-    need(Number.isInteger(maxParallel) && maxParallel >= 0, 'provider reservation needs nonnegative integer maxParallel');
-    return m.transaction((db) => {
-      const existing = db.prepare('SELECT * FROM provider_reservations WHERE attempt_id=?').get(attemptId);
-      if (existing) {
-        if (existing.provider !== provider || existing.account !== account || existing.model !== model || existing.role !== role || existing.scope_json !== toJson(scope))
-          return { ok: false, reason: 'attempt-conflict', reservation: providerReservationRow(existing) };
-        return { ok: existing.state !== 'released', reason: existing.state === 'released' ? 'attempt-released' : 'reserved', reused: true, reservation: providerReservationRow(existing) };
-      }
-      const running = Number(db.prepare("SELECT count(*) n FROM provider_reservations WHERE provider=? AND account=? AND state<>'released'").get(provider, account).n);
-      if (running >= maxParallel) return { ok: false, reason: 'capacity', running, maxParallel };
-      const id = hex(16), at = m.now();
-      const result = db.prepare("INSERT INTO provider_reservations(id,attempt_id,provider,account,model,role,scope_json,state,max_parallel,quota_json,estimate_json,override_json,created_at,updated_at) VALUES(?,?,?,?,?,?,?,'reserved',?,?,?,?,?,?)")
-        .run(id, attemptId, provider, account, model, role, toJson(scope), maxParallel, toJson(quota), toJson(estimate), toJson(override), at, at);
-      db.prepare("INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state) VALUES(?,?,NULL,'reserved')").run(id, at);
-      return { ok: true, reason: 'reserved', reused: false, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE fence=?').get(result.lastInsertRowid)) };
-    });
-  }
-  const fencedProviderRow = (db, { id, fence, attemptId } = {}) => {
-    const row = db.prepare('SELECT * FROM provider_reservations WHERE id=? AND fence=?').get(id ?? '', fence ?? -1);
-    return row && (attemptId === undefined || row.attempt_id === attemptId) ? row : null;
-  };
-  /** Observe launch progress under its original fence; unknown still occupies its slot. */
-  function markProviderReservation(m, { id, fence, attemptId, provider, account, model, role, state, launchIdentity = null, hostRequestId = null, handle = null, pid = null } = {}) {
-    need(['launching', 'live', 'unknown'].includes(state), 'provider reservation observation needs launching, live or unknown');
-    return m.transaction((db) => {
-      const row = fencedProviderRow(db, { id, fence, attemptId });
-      if (!row) return { ok: false, reason: 'fenced' };
-      if (Object.entries({ provider, account, model, role }).some(([key, value]) => value !== undefined && row[key] !== value)) return { ok: false, reason: 'identity-conflict' };
-      if (row.state === 'released') return { ok: false, reason: 'released' };
-      if (state === 'launching' && (typeof launchIdentity !== 'string' || !launchIdentity.trim())) return { ok: false, reason: 'launch-identity-required' };
-      if (launchIdentity !== null && row.launch_identity && row.launch_identity !== launchIdentity) return { ok: false, reason: 'launch-identity-conflict', reservation: providerReservationRow(row) };
-      if (hostRequestId !== null && row.host_request_id && row.host_request_id !== hostRequestId) return { ok: false, reason: 'host-request-conflict', reservation: providerReservationRow(row) };
-      if (state === 'launching' && row.state !== 'reserved' && row.state !== 'launching') return { ok: false, reason: 'state-regression' };
-      if ((row.handle && handle && row.handle !== handle) || (row.pid && pid && row.pid !== pid)) return { ok: false, reason: 'identity-conflict' };
-      const at = m.now();
-      db.prepare('UPDATE provider_reservations SET state=?,launch_identity=coalesce(launch_identity,?),host_request_id=coalesce(host_request_id,?),handle=coalesce(handle,?),pid=coalesce(pid,?),updated_at=? WHERE id=? AND fence=?')
-        .run(state, launchIdentity, hostRequestId, handle, pid, at, id, fence);
-      if (row.state !== state) db.prepare('INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state) VALUES(?,?,?,?)').run(id, at, row.state, state);
-      return { ok: true, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE id=?').get(id)) };
-    });
-  }
-  /** Only the launcher/reconciler's definitive matching exit/no-effect receipt releases capacity. */
-  function releaseProviderReservation(m, { id, fence, attemptId, proof } = {}) {
-    return m.transaction((db) => {
-      const row = fencedProviderRow(db, { id, fence, attemptId });
-      if (!row) return { ok: false, reason: 'fenced' };
-      if (row.state === 'released') return { ok: true, reused: true, reservation: providerReservationRow(row) };
-      const affirmation = proof?.hostAffirmation;
-      const reply = affirmation?.receipt, result = reply?.result;
-      const residual = result?.residualResources ?? result?.worker?.residualResources;
-      const identities = [result, result?.worker, result?.terminal].filter((value) => value && typeof value === 'object');
-      const hostNoEffect = reply && typeof reply === 'object' && !['unknown', 'outcome_unknown'].includes(result?.state)
-        && !['unknown', 'outcome_unknown'].includes(result?.worker?.state)
-        && !(residual && typeof residual === 'object' && Object.keys(residual).length > 0)
-        && !identities.some((value) => ['agentTerminalHandle', 'terminalHandle', 'handle', 'pid', 'processId', 'dispatchId'].some((key) => value[key] !== undefined && value[key] !== null && value[key] !== ''))
-        && (result?.failedStage !== undefined || result?.stage !== undefined || typeof reply.error?.code === 'string' && reply.error.code.trim());
-      const resolvedUnknown = row.state === 'unknown' && row.launch_identity && proof?.launchIdentity === row.launch_identity
-        && row.host_request_id && affirmation?.requestId === row.host_request_id && affirmation.kind === 'worker-start-replay'
-        && affirmation.replayed === true && affirmation.outcome === 'failed' && affirmation.effectState === 'none'
-        && hostNoEffect;
-      const noEffect = proof?.kind === 'failed-before-launch' && proof.confirmed === true && !row.handle && !row.pid
-        && (['reserved', 'launching'].includes(row.state) || resolvedUnknown);
-      const terminalEnded = row.handle && proof?.kind === 'closed' && proof.handle === row.handle
-        && ['gone', 'disconnected'].includes(proof.terminalProof) && ['none', 'stopped'].includes(proof.processVerdict);
-      const processEnded = !row.handle && row.pid && proof?.kind === 'process-exited' && proof.pid === row.pid;
-      const ended = proof?.confirmed === true && (terminalEnded || processEnded)
-        && (!row.pid || proof.pid == null || proof.pid === row.pid);
-      // A kernel reconcile settled this receipt's dispatch to no effect and recorded it durably
-      // (job result + dispatch-reconciled event): the proof carries that dispatch's identity and the
-      // receipt's own attempt scope, so the release is bound to the launch the receipt reserved.
-      const reconciledNoEffect = row.state === 'unknown' && proof?.kind === 'reconciled-no-effect'
-        && proof.confirmed === true && proof.effectState === 'none'
-        && typeof proof.dispatchId === 'string' && proof.dispatchId.trim()
-        && parse(row.scope_json)?.scopeId === proof.scopeId;
-      if (!noEffect && !ended && !reconciledNoEffect && !hostRestartedEnd(row, proof) && !dispatchEndedEnd(row, proof)) return { ok: false, reason: 'exit-unproven', reservation: providerReservationRow(row) };
-      const at = m.now();
-      db.prepare("UPDATE provider_reservations SET state='released',released_at=?,updated_at=?,proof_json=? WHERE id=? AND fence=?").run(at, at, toJson(proof), id, fence);
-      db.prepare("INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state,proof_json) VALUES(?,?,?,'released',?)").run(id, at, row.state, toJson(proof));
-      return { ok: true, reused: false, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE id=?').get(id)) };
-    });
-  }
-  return { reserveProvider, providerReservations, providerReservationUsage, markProviderReservation, releaseProviderReservation };
+    && Boolean(row.host_request_id) && proof.hostRequestId === row.host_request_id
+    && typeof proof.dispatchId === 'string' && proof.dispatchId.length > 0 && oneOf(ENDED_DISPATCH_STATES, proof.dispatchStatus)
+    && proof.processVerdict === 'none' && (!proof.handle || oneOf(['gone', 'disconnected'], proof.terminalProof));
+export function providerReservationMethods(deps) {
+    const { parse, toJson, hex } = deps;
+    function need(ok, message, code) { deps.need(ok, message, code); }
+    // Provider/account slots are shared by all five agent roles. A clock timeout is not exit evidence.
+    const reservationFrom = (row) => ({ id: row.id, fence: row.fence, attemptId: row.attempt_id,
+        provider: row.provider, account: row.account, model: row.model, role: row.role, state: row.state,
+        slots: row.slots, amountUnit: 'concurrent-launch', maxParallel: row.max_parallel,
+        handle: row.handle, pid: row.pid, launchIdentity: row.launch_identity, hostRequestId: row.host_request_id, createdAt: row.created_at, updatedAt: row.updated_at,
+        scope: parse(row.scope_json), estimate: parse(row.estimate_json), quota: parse(row.quota_json),
+        override: parse(row.override_json), releasedAt: row.released_at, proof: parse(row.proof_json) });
+    const providerReservationRow = (row) => row ? reservationFrom(row) : null;
+    // `tier` keeps the rows whose scope names that tier; `limit` returns the newest rows first (the tier's recent picks).
+    function providerReservations(m, { provider = null, account = null, activeOnly = false, tier = null, limit = null } = {}) {
+        const where = [], args = [];
+        if (tier !== null) {
+            where.push("json_extract(scope_json,'$.tier')=?");
+            args.push(tier);
+        }
+        if (provider !== null) {
+            where.push('provider=?');
+            args.push(provider);
+        }
+        if (account !== null) {
+            where.push('account=?');
+            args.push(account);
+        }
+        if (activeOnly)
+            where.push("state<>'released'");
+        const clause = where.length ? ` WHERE ${where.join(' AND ')}` : '';
+        const order = limit === null ? 'ORDER BY fence' : `ORDER BY fence DESC LIMIT ${Math.trunc(Number(limit)) || 0}`;
+        return m.db.prepare(`SELECT * FROM provider_reservations${clause} ${order}`).all(...args).map(reservationFrom);
+    }
+    function providerReservationUsage(m, { provider, account = 'default' } = {}) {
+        const reservations = providerReservations(m, { provider, account, activeOnly: true });
+        return { running: reservations.length, reservations, observed: true };
+    }
+    /** Atomic last-slot admission. Replays preserve the original receipt; changed attempt meaning refuses. */
+    function reserveProvider(m, { provider, account = 'default', attemptId, role, model, maxParallel, scope = null, quota = null, estimate = null, override = null } = {}) {
+        need([provider, account, attemptId, model].every((value) => typeof value === 'string' && value.trim()), 'provider reservation needs provider, account, attemptId and concrete model');
+        need(typeof role === 'string' && role.trim(), 'provider reservation needs one agent role'); // The DDL owns the allowed role domain.
+        need(typeof maxParallel === 'number' && Number.isInteger(maxParallel) && maxParallel >= 0, 'provider reservation needs nonnegative integer maxParallel');
+        return m.transaction((db) => {
+            const existing = db.prepare('SELECT * FROM provider_reservations WHERE attempt_id=?').get(attemptId);
+            if (existing) {
+                if (existing.provider !== provider || existing.account !== account || existing.model !== model || existing.role !== role || existing.scope_json !== toJson(scope))
+                    return { ok: false, reason: 'attempt-conflict', reservation: providerReservationRow(existing) };
+                return { ok: existing.state !== 'released', reason: existing.state === 'released' ? 'attempt-released' : 'reserved', reused: true, reservation: providerReservationRow(existing) };
+            }
+            const running = Number(db.prepare("SELECT count(*) n FROM provider_reservations WHERE provider=? AND account=? AND state<>'released'").get(provider, account)?.n);
+            if (running >= maxParallel)
+                return { ok: false, reason: 'capacity', running, maxParallel };
+            const id = hex(16), at = m.now();
+            const result = db.prepare("INSERT INTO provider_reservations(id,attempt_id,provider,account,model,role,scope_json,state,max_parallel,quota_json,estimate_json,override_json,created_at,updated_at) VALUES(?,?,?,?,?,?,?,'reserved',?,?,?,?,?,?)")
+                .run(id, attemptId, provider, account, model, role, toJson(scope), maxParallel, toJson(quota), toJson(estimate), toJson(override), at, at);
+            db.prepare("INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state) VALUES(?,?,NULL,'reserved')").run(id, at);
+            return { ok: true, reason: 'reserved', reused: false, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE fence=?').get(result.lastInsertRowid)) };
+        });
+    }
+    const fencedProviderRow = (db, { id, fence, attemptId } = {}) => {
+        const row = db.prepare('SELECT * FROM provider_reservations WHERE id=? AND fence=?').get(id ?? '', fence ?? -1);
+        return row && (attemptId === undefined || row.attempt_id === attemptId) ? row : null;
+    };
+    /** Observe launch progress under its original fence; unknown still occupies its slot. */
+    function markProviderReservation(m, { id, fence, attemptId, provider, account, model, role, state, launchIdentity = null, hostRequestId = null, handle = null, pid = null } = {}) {
+        need(oneOf(['launching', 'live', 'unknown'], state), 'provider reservation observation needs launching, live or unknown');
+        return m.transaction((db) => {
+            const row = fencedProviderRow(db, { id, fence, attemptId });
+            if (!row)
+                return { ok: false, reason: 'fenced' };
+            if (Object.entries({ provider, account, model, role }).some(([key, value]) => value !== undefined && row[key] !== value))
+                return { ok: false, reason: 'identity-conflict' };
+            if (row.state === 'released')
+                return { ok: false, reason: 'released' };
+            if (state === 'launching' && (typeof launchIdentity !== 'string' || !launchIdentity.trim()))
+                return { ok: false, reason: 'launch-identity-required' };
+            if (launchIdentity !== null && row.launch_identity && row.launch_identity !== launchIdentity)
+                return { ok: false, reason: 'launch-identity-conflict', reservation: providerReservationRow(row) };
+            if (hostRequestId !== null && row.host_request_id && row.host_request_id !== hostRequestId)
+                return { ok: false, reason: 'host-request-conflict', reservation: providerReservationRow(row) };
+            if (state === 'launching' && row.state !== 'reserved' && row.state !== 'launching')
+                return { ok: false, reason: 'state-regression' };
+            if ((row.handle && handle && row.handle !== handle) || (row.pid && pid && row.pid !== pid))
+                return { ok: false, reason: 'identity-conflict' };
+            const at = m.now();
+            db.prepare('UPDATE provider_reservations SET state=?,launch_identity=coalesce(launch_identity,?),host_request_id=coalesce(host_request_id,?),handle=coalesce(handle,?),pid=coalesce(pid,?),updated_at=? WHERE id=? AND fence=?')
+                .run(state, launchIdentity, hostRequestId, handle, pid, at, id, fence);
+            if (row.state !== state)
+                db.prepare('INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state) VALUES(?,?,?,?)').run(id, at, row.state, state);
+            return { ok: true, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE id=?').get(id)) };
+        });
+    }
+    /** Only the launcher/reconciler's definitive matching exit/no-effect receipt releases capacity. */
+    function releaseProviderReservation(m, { id, fence, attemptId, proof } = {}) {
+        return m.transaction((db) => {
+            const row = fencedProviderRow(db, { id, fence, attemptId });
+            if (!row)
+                return { ok: false, reason: 'fenced' };
+            if (row.state === 'released')
+                return { ok: true, reused: true, reservation: providerReservationRow(row) };
+            const affirmation = proof?.hostAffirmation;
+            const reply = affirmation?.receipt, result = reply?.result;
+            const residual = result?.residualResources ?? result?.worker?.residualResources;
+            const identities = [result, result?.worker, result?.terminal].filter((value) => value && typeof value === 'object');
+            const hostNoEffect = reply && typeof reply === 'object' && !['unknown', 'outcome_unknown'].includes(result?.state)
+                && !['unknown', 'outcome_unknown'].includes(result?.worker?.state)
+                && !(residual && typeof residual === 'object' && Object.keys(residual).length > 0)
+                && !identities.some((value) => ['agentTerminalHandle', 'terminalHandle', 'handle', 'pid', 'processId', 'dispatchId'].some((key) => value[key] !== undefined && value[key] !== null && value[key] !== ''))
+                && (result?.failedStage !== undefined || result?.stage !== undefined || typeof reply.error?.code === 'string' && reply.error.code.trim());
+            const resolvedUnknown = row.state === 'unknown' && row.launch_identity && proof?.launchIdentity === row.launch_identity
+                && row.host_request_id && affirmation?.requestId === row.host_request_id && affirmation?.kind === 'worker-start-replay'
+                && affirmation?.replayed === true && affirmation?.outcome === 'failed' && affirmation?.effectState === 'none'
+                && hostNoEffect;
+            const noEffect = proof?.kind === 'failed-before-launch' && proof.confirmed === true && !row.handle && !row.pid
+                && (['reserved', 'launching'].includes(row.state) || resolvedUnknown);
+            const terminalEnded = row.handle && proof?.kind === 'closed' && proof.handle === row.handle
+                && oneOf(['gone', 'disconnected'], proof.terminalProof) && oneOf(['none', 'stopped'], proof.processVerdict);
+            const processEnded = !row.handle && row.pid && proof?.kind === 'process-exited' && proof.pid === row.pid;
+            const ended = proof?.confirmed === true && (terminalEnded || processEnded)
+                && (!row.pid || proof.pid == null || proof.pid === row.pid);
+            // A kernel reconcile settled this receipt's dispatch to no effect and recorded it durably
+            // (job result + dispatch-reconciled event): the proof carries that dispatch's identity and the
+            // receipt's own attempt scope, so the release is bound to the launch the receipt reserved.
+            const reconciledNoEffect = row.state === 'unknown' && proof?.kind === 'reconciled-no-effect'
+                && proof.confirmed === true && proof.effectState === 'none'
+                && typeof proof.dispatchId === 'string' && proof.dispatchId.trim()
+                && parse(row.scope_json)?.scopeId === proof.scopeId;
+            if (!noEffect && !ended && !reconciledNoEffect && !hostRestartedEnd(row, proof) && !dispatchEndedEnd(row, proof))
+                return { ok: false, reason: 'exit-unproven', reservation: providerReservationRow(row) };
+            const at = m.now();
+            db.prepare("UPDATE provider_reservations SET state='released',released_at=?,updated_at=?,proof_json=? WHERE id=? AND fence=?").run(at, at, toJson(proof), id, fence);
+            db.prepare("INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state,proof_json) VALUES(?,?,?,'released',?)").run(id, at, row.state, toJson(proof));
+            return { ok: true, reused: false, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE id=?').get(id)) };
+        });
+    }
+    return { reserveProvider, providerReservations, providerReservationUsage, markProviderReservation, releaseProviderReservation };
 }

package/runtime/engine/db/provision-lock.d.mts

@@ -0,0 +1,23 @@
+import type { SqlRow, StoreHandle } from './sqlite-types.mjs';
+/**
+ * Release only the exact observed provisioning lock after its PID is absent. A live reused PID
+ * conservatively holds the target. The caller may resume only the same persisted operation's
+ * read-only reconciliation; absence proves neither remote rollback nor absence of provider effects.
+ */
+export declare function releaseObservedProvisionLock(m: StoreHandle, { observed, holder }: {
+    observed?: SqlRow | null;
+    holder?: unknown;
+}): boolean;
+/** Renew only this provisioning operation's exact holder, including inside one shared process. */
+export declare function renewProvisionLock(m: StoreHandle, { name, holder, ttlMs, pid }: {
+    name?: string;
+    holder?: unknown;
+    ttlMs?: unknown;
+    pid?: number;
+}): boolean;
+/** Release only the exact provisioning holder; unrelated native host locks keep their own policy. */
+export declare function releaseProvisionLock(m: StoreHandle, { name, holder, pid }: {
+    name?: string;
+    holder?: unknown;
+    pid?: number;
+}): boolean;

package/runtime/engine/db/provision-lock.mjs

@@ -1,29 +1,29 @@
 // The machine writer owns compare-and-release of an observed dead provisioning executor.
 import { pidAlive } from '../../scripts/lib/pid-alive.mjs';
-
 /**
  * Release only the exact observed provisioning lock after its PID is absent. A live reused PID
  * conservatively holds the target. The caller may resume only the same persisted operation's
  * read-only reconciliation; absence proves neither remote rollback nor absence of provider effects.
  */
 export function releaseObservedProvisionLock(m, { observed, holder }) {
-  if (!observed?.name?.startsWith('provision:') || observed.holder !== holder || observed.state === 'released'
-    || pidAlive(observed.holder_pid)) return false;
-  return m.transaction(db => db.prepare("UPDATE host_locks SET state='released',heartbeat_at=? WHERE name=? AND holder_pid=? AND holder=? AND started_at=? AND heartbeat_at=? AND expires_at=? AND state=?")
-    .run(m.now(), observed.name, observed.holder_pid, observed.holder, observed.started_at, observed.heartbeat_at, observed.expires_at, observed.state).changes === 1);
+    if (!observed?.name?.startsWith('provision:') || observed.holder !== holder || observed.state === 'released'
+        || pidAlive(observed.holder_pid))
+        return false;
+    return m.transaction(db => db.prepare("UPDATE host_locks SET state='released',heartbeat_at=? WHERE name=? AND holder_pid=? AND holder=? AND started_at=? AND heartbeat_at=? AND expires_at=? AND state=?")
+        .run(m.now(), observed.name, observed.holder_pid, observed.holder, observed.started_at, observed.heartbeat_at, observed.expires_at, observed.state).changes === 1);
 }
-
 /** Renew only this provisioning operation's exact holder, including inside one shared process. */
 export function renewProvisionLock(m, { name, holder, ttlMs, pid = process.pid }) {
-  if (!name?.startsWith('provision:') || typeof holder !== 'string' || !Number.isSafeInteger(ttlMs) || ttlMs < 1) return false;
-  const at = m.now();
-  return m.db.prepare("UPDATE host_locks SET heartbeat_at=?,expires_at=? WHERE name=? AND holder_pid=? AND holder=? AND state<>'released'")
-    .run(at, at + ttlMs, name, pid, holder).changes === 1;
+    if (!name?.startsWith('provision:') || typeof holder !== 'string' || typeof ttlMs !== 'number' || !Number.isSafeInteger(ttlMs) || ttlMs < 1)
+        return false;
+    const at = m.now();
+    return m.db.prepare("UPDATE host_locks SET heartbeat_at=?,expires_at=? WHERE name=? AND holder_pid=? AND holder=? AND state<>'released'")
+        .run(at, at + ttlMs, name, pid, holder).changes === 1;
 }
-
 /** Release only the exact provisioning holder; unrelated native host locks keep their own policy. */
 export function releaseProvisionLock(m, { name, holder, pid = process.pid }) {
-  if (!name?.startsWith('provision:') || typeof holder !== 'string') return false;
-  return m.db.prepare("UPDATE host_locks SET state='released',heartbeat_at=? WHERE name=? AND holder_pid=? AND holder=? AND state<>'released'")
-    .run(m.now(), name, pid, holder).changes === 1;
+    if (!name?.startsWith('provision:') || typeof holder !== 'string')
+        return false;
+    return m.db.prepare("UPDATE host_locks SET state='released',heartbeat_at=? WHERE name=? AND holder_pid=? AND holder=? AND state<>'released'")
+        .run(m.now(), name, pid, holder).changes === 1;
 }

package/runtime/engine/db/ref-value.d.mts

@@ -0,0 +1,19 @@
+import type { SqlDb, SqlStatement } from './sqlite-types.mjs';
+/** Whether a stored value is a reference. */
+export declare const isRef: (value: unknown) => value is string;
+/** The reference string of a blob. */
+export declare const refOf: (sha: string, bytes: number) => string;
+/** The {sha, bytes} a reference names, or null. */
+export declare function parseRef(value: unknown): {
+    sha: string;
+    bytes: number;
+} | null;
+/**
+ * Makes every row a statement of `db` returns resolve its reference values: get, all and iterate. The handle is changed in place and returned; a handle that was already
+ * installed is left alone. Other statement methods (run, columns, ...) are the statement's own.
+ */
+/** A SQLite file opened read-only with the given busy timeout, its references resolving. */
+export declare const openReadOnlyDb: (file: string, timeoutMs: number) => SqlDb;
+/** A statement over exact stored cells, for self-contained archives that retain references and their original bytes. */
+export declare const prepareStored: (db: SqlDb, sql: string, ...rest: unknown[]) => SqlStatement;
+export declare function installRefResolver<D extends SqlDb>(db: D): D;