@starci/hfs 4.7.32 → 4.7.34

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

@@ -0,0 +1,127 @@
+// Provider receipt SQL participates in the machine writer's existing fenced transactions.
+
+// 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'));
+
+/** 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 };
+}

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

@@ -0,0 +1,76 @@
+// Read-only joins of a native dispatch and its accepted goal grant; no prompt text grants authority.
+import { canonicalJSON } from '../canonical-json.mjs';
+import { sha256 } from '../digest.mjs';
+import { byCodeUnit } from '../by-code-unit.mjs';
+import { pathKey } from '../../scripts/lib/path-key.mjs';
+
+const denied = reason => ({ ok: false, reason });
+const parse = text => { try { return JSON.parse(text); } catch { return null; } };
+
+/**
+ * Verify a provider-plan grant against the exact live job, latest attempt, filed admission and
+ * current owner-approved goal. The native caller-binding owner supplies `caller`; argv does not.
+ * This verifies retained conversation acceptance, not cryptographic human identity.
+ */
+export function provisionGoalGrant(db, { caller, operationId, planSha, ledgerId, repoRoot, worktree }) {
+  const guard = caller?.guard;
+  if (!guard || caller.seat || guard.schema !== 'starci/op-guard@1' || guard.role !== 'op'
+    || caller.classification?.role !== 'op' || caller.classification.jobId !== guard.jobId
+    || caller.classification.workflowId !== guard.workflowId
+    || guard.workflowId === 'supervisor' || guard.terminal !== caller.terminal
+    || !guard.jobId || !guard.op || !guard.ledgerRepo || !guard.workflowWorktree
+    || pathKey(guard.ledgerRepo) !== pathKey(repoRoot) || pathKey(guard.workflowWorktree) !== pathKey(worktree)
+    || (caller.ledgerId !== undefined && caller.ledgerId !== ledgerId)
+    || (caller.workflowId !== undefined && caller.workflowId !== guard.workflowId))
+    return denied('provision-native-caller-unverified');
+  const job = db.prepare('SELECT * FROM jobs WHERE job_id=?').get(guard.jobId);
+  const attempt = db.prepare('SELECT * FROM op_attempts WHERE job_id=? ORDER BY attempt_id DESC LIMIT 1').get(guard.jobId);
+  const attemptId = attempt?.attempt_id;
+  if (!Number.isSafeInteger(attemptId) || attemptId < 1
+    || (caller.attemptId !== undefined && Number(caller.attemptId) !== attemptId)
+    || (caller.dispatchId !== undefined && caller.dispatchId !== attempt.dispatch_id)) return denied('provision-native-attempt-unverified');
+  if (job?.kind !== 'op' || job.status !== 'running' || job.workflow_id !== guard.workflowId || job.op_id !== guard.op
+    || !attempt || attempt.job_id !== guard.jobId || attempt.workflow_id !== guard.workflowId
+    || attempt.op_id !== guard.op || !attempt.dispatch_id || attempt.terminal_handle !== caller.terminal
+    || attempt.managed !== 1 || attempt.started_at === null || attempt.attested_at === null
+    || attempt.reported_at !== null || attempt.settled_at !== null || attempt.released_at !== null || attempt.end_state !== null
+    || !attempt.worktree_path || pathKey(attempt.worktree_path) !== pathKey(worktree))
+    return denied('provision-native-attempt-stale');
+  const workflow = db.prepare('SELECT * FROM workflows WHERE workflow_id=?').get(guard.workflowId);
+  const goal = db.prepare('SELECT * FROM goals WHERE workflow_id=? ORDER BY revision DESC LIMIT 1').get(guard.workflowId);
+  const unit = db.prepare('SELECT * FROM work_units WHERE workflow_id=? AND unit_id=?').get(guard.workflowId, job.unit_id);
+  const goalJson = parse(goal?.json), payload = parse(job.payload_json);
+  if (workflow?.phase !== 'running' || workflow.archived_at !== null || goal?.approved_by !== 'owner'
+    || !goal.markdown?.trim() || !goal.goal_identity || workflow.goal_identity !== goal.goal_identity || !goalJson || goalJson.provisional === true
+    || !unit || unit.goal_revision !== goal.revision || unit.current_job_id !== job.job_id
+    || payload?.goal_binding?.revision !== goal.revision || payload?.goal_binding?.identity !== goal.goal_identity)
+    return denied('provision-goal-grant-stale');
+  const contract = db.prepare('SELECT * FROM contracts WHERE attempt_id=?').get(attemptId);
+  const context = parse(contract?.context_json), packet = context?.packet;
+  if (contract?.workflow_id !== guard.workflowId || contract.job_id !== job.job_id || !contract.markdown?.trim()
+    || packet?.op !== guard.op || packet.context?.workflow?.id !== guard.workflowId
+    || packet.context?.workflow?.goal_revision !== goal.revision || packet.context?.workflow?.goal_identity !== goal.goal_identity
+    || context.contract?.schema !== 'starci/contract-version@1' || context.contract?.op !== guard.op
+    || !/^[a-f0-9]{64}$/u.test(context.contract?.digest ?? '') || !context.worktree || pathKey(context.worktree) !== pathKey(worktree)
+    || !job.lease_token || context.lease?.token !== job.lease_token || !context.lease?.fencing || typeof context.lease.fencing !== 'object' || Array.isArray(context.lease.fencing))
+    return denied('provision-filed-contract-unverified');
+  const leases = db.prepare('SELECT resource_key,generation,token,expires_at FROM leases WHERE job_id=?').all(job.job_id);
+  const fencing = context.lease.fencing;
+  if (Object.keys(fencing).length !== leases.length || leases.some(lease => fencing[lease.resource_key] !== job.generation
+    || lease.generation !== job.generation || lease.token !== job.lease_token || lease.expires_at <= Date.now()))
+    return denied('provision-filed-contract-unverified');
+  const grants = goalJson.provisionGrants, approval = goalJson.provisionGrantsApproval;
+  if (!Array.isArray(grants) || new Set(grants.map(grant => grant?.operation)).size !== grants.length || grants.some(grant => !grant || Object.keys(grant).sort(byCodeUnit).join(',') !== 'digest,op,operation'
+    || typeof grant.op !== 'string' || typeof grant.operation !== 'string' || !/^[a-f0-9]{64}$/u.test(grant.digest ?? '')))
+    return denied('provision-goal-grant-unsupported');
+  if (approval?.source !== 'owner-goal-entry' || approval.digest !== sha256(canonicalJSON(grants))
+    || approval.assurance !== 'conversation-context-not-authenticated') return denied('provision-goal-grant-unaccepted');
+  if (goal.revision === 0 ? goal.approval_ref !== approval.digest
+    : goal.approval_ref !== goalJson.revision?.approvalToken || !/^rev-[a-f0-9]{64}$/u.test(goal.approval_ref ?? ''))
+    return denied('provision-goal-grant-unaccepted');
+  const matches = grants.filter(grant => grant.op === guard.op && grant.operation === operationId && grant.digest === planSha);
+  if (matches.length !== 1) return denied('provision-goal-grant-missing');
+  return { ok: true, kind: 'owner-goal', workflow: guard.workflowId, goalRevision: goal.revision,
+    goalIdentity: goal.goal_identity, op: guard.op, job: job.job_id, attempt: attemptId,
+    dispatch: attempt.dispatch_id, operation: operationId, digest: planSha, assurance: approval.assurance };
+}

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

@@ -0,0 +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);
+}
+
+/** 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;
+}
+
+/** 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;
+}

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

@@ -0,0 +1,146 @@
+// Standalone operation writes are reached only through the ledger writer's typed namespace.
+import { sha256 } from '../digest.mjs';
+import { provisionGoalGrant } from './provision-authority.mjs';
+import { describeSchema, readSchemaObjects } from './machine-schema.mjs';
+
+const failures = new WeakSet();
+const need = (condition, code) => {
+  if (!condition) { const error = Object.assign(new Error(code), { code }); failures.add(error); throw error; }
+};
+/** Recognize only this writer's fixed invariant refusals; arbitrary database errors stay private. */
+export const isProvisionOperationFailure = error => typeof error === 'object' && error !== null && failures.has(error);
+
+const SCHEMA_FAILURE = 'STARCI_LEDGER_SCHEMA_REFUSED';
+const SCHEMA_BEGIN = '-- starci:provision-schema:begin';
+const SCHEMA_END = '-- starci:provision-schema:end';
+const identifierKey = name => name.toLowerCase();
+const provisionName = name => identifierKey(name).startsWith('provision_');
+
+function canonicalProvisionSchema(canonicalSql) {
+  const begin = canonicalSql.indexOf(SCHEMA_BEGIN), end = canonicalSql.indexOf(SCHEMA_END);
+  need(begin >= 0 && end > begin && canonicalSql.lastIndexOf(SCHEMA_BEGIN) === begin
+    && canonicalSql.lastIndexOf(SCHEMA_END) === end, SCHEMA_FAILURE);
+  const canonical = describeSchema(canonicalSql);
+  const objects = canonical.objects.filter(row => provisionName(row.name));
+  const names = new Set(objects.map(row => identifierKey(row.name)));
+  const tables = new Set(objects.filter(row => row.type === 'table').map(row => identifierKey(row.name)));
+  const blobRefs = canonical.blobRefs.filter(row => tables.has(identifierKey(row.table_name)));
+  need(objects.length > 0 && tables.size > 0 && blobRefs.length > 0, SCHEMA_FAILURE);
+  return { sql: canonicalSql.slice(begin + SCHEMA_BEGIN.length, end), objects, names, tables, blobRefs };
+}
+
+function provisionSchemaState(db, schema) {
+  const all = readSchemaObjects(db);
+  need(['blobs', 'blob_ref_columns'].every(name => all.some(row => row.type === 'table' && row.name === name)), SCHEMA_FAILURE);
+  return {
+    objects: all.filter(row => provisionName(row.name) || schema.names.has(identifierKey(row.name)) || schema.tables.has(identifierKey(row.tbl_name))),
+    blobRefs: db.prepare('SELECT table_name,column_name FROM blob_ref_columns ORDER BY table_name,column_name').all()
+      .filter(row => provisionName(row.table_name) || schema.tables.has(identifierKey(row.table_name))),
+  };
+}
+
+function exactProvisionSchema(actual, expected) {
+  const objects = rows => JSON.stringify(rows.map(row => [row.type, row.name, row.tbl_name, row.identity]));
+  return objects(actual.objects) === objects(expected.objects)
+    && JSON.stringify(actual.blobRefs) === JSON.stringify(expected.blobRefs);
+}
+
+/** Install only a wholly absent canonical domain inside the ledger's fenced write transaction. */
+function ensureProvisionSchema(db, schema) {
+  const before = provisionSchemaState(db, schema);
+  if (before.objects.length || before.blobRefs.length) {
+    need(exactProvisionSchema(before, schema), SCHEMA_FAILURE);
+    return;
+  }
+  db.exec(schema.sql);
+  need(exactProvisionSchema(provisionSchemaState(db, schema), schema), SCHEMA_FAILURE);
+}
+
+/** Read one provider operation; older compatible ledgers without this additive store return null. */
+export function provisionOperation(db, operationId) {
+  if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='provision_operations'").get()) return null;
+  return db.prepare('SELECT * FROM provision_operations WHERE operation_id=?').get(operationId) ?? null;
+}
+
+/** Prior completed operations bind the exact public plan, including credential references and destination. */
+export function priorProvisionOperations(db, { planSha, excludeId }) {
+  return db.prepare("SELECT * FROM provision_operations WHERE plan_sha=? AND operation_id<>? AND state IN ('applied','verified') ORDER BY updated_at DESC LIMIT 1")
+    .all(planSha, excludeId);
+}
+
+function journal(db, row, kind, at) {
+  const prior = db.prepare('SELECT digest FROM provision_events WHERE operation_id=? ORDER BY seq DESC LIMIT 1').get(row.operation_id)?.digest ?? null;
+  const digest = sha256(JSON.stringify([prior, row.operation_id, kind, row.state, row.receipt_sha, at]));
+  db.prepare('INSERT INTO provision_events(operation_id,kind,state,receipt_sha,prev_digest,digest,created_at) VALUES(?,?,?,?,?,?,?)')
+    .run(row.operation_id, kind, row.state, row.receipt_sha, prior, digest, at);
+  return row;
+}
+
+/** Prepare immutable intent. A reused identifier must retain the exact original plan and target. */
+function prepareProvisionOperation(db, { operationId, action, targetId, transport, endpointIdentity, coordinationKey, planSha, at = Date.now() }) {
+  need(typeof operationId === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9-]{0,127}$/u.test(operationId), 'provision-operation-id-invalid');
+  const previous = provisionOperation(db, operationId);
+  if (previous) {
+    need(previous.action === action && previous.transport === transport && previous.endpoint_identity === endpointIdentity
+      && previous.coordination_key === coordinationKey && previous.plan_sha === planSha, 'provision-operation-intent-conflict');
+    return previous;
+  }
+  db.prepare("INSERT INTO provision_operations(operation_id,action,target_id,transport,endpoint_identity,coordination_key,plan_sha,state,code,created_at,updated_at) VALUES(?,?,?,?,?,?,?,'planned','plan-prepared',?,?)")
+    .run(operationId, action, targetId, transport, endpointIdentity, coordinationKey, planSha, at, at);
+  return journal(db, provisionOperation(db, operationId), 'prepared', at);
+}
+
+/** Record the native terminal's scoped acceptance; a digest flag alone never reaches this writer. */
+function acceptProvisionOperation(db, { operationId, planSha, at = Date.now() }) {
+  const row = provisionOperation(db, operationId);
+  need(row && row.plan_sha === planSha, 'provision-plan-digest-mismatch');
+  need(['planned', 'accepted', 'unknown', 'partial'].includes(row.state), 'provision-accept-state-refused');
+  if (row.accepted_by === 'owner-terminal') return row;
+  db.prepare("UPDATE provision_operations SET state=CASE WHEN state='planned' THEN 'accepted' ELSE state END,accepted_by='owner-terminal',approval_ref=?,accepted_at=?,updated_at=?,code='owner-plan-accepted' WHERE operation_id=?")
+    .run(planSha, at, at, operationId);
+  return journal(db, provisionOperation(db, operationId), 'accepted', at);
+}
+
+/** Consume an exact accepted goal grant after the native binding check, rejoining current rows atomically. */
+function authorizeProvisionGrant(db, { operationId, planSha, caller, ledgerId, repoRoot, worktree, authoritySha, at = Date.now() }) {
+  const authority = provisionGoalGrant(db, { operationId, planSha, caller, ledgerId, repoRoot, worktree });
+  need(authority.ok, 'provision-goal-grant-refused');
+  const row = provisionOperation(db, operationId);
+  need(row && row.plan_sha === planSha, 'provision-plan-digest-mismatch');
+  db.prepare("UPDATE provision_operations SET state=CASE WHEN state='planned' THEN 'accepted' ELSE state END,accepted_by='owner-goal',approval_ref=?,accepted_at=COALESCE(accepted_at,?),updated_at=? WHERE operation_id=?")
+    .run(authoritySha, at, at, operationId);
+  return journal(db, provisionOperation(db, operationId), 'goal-authorized', at);
+}
+
+/** Atomically claim one accepted execution or explicit unknown-outcome reconciliation. */
+function claimProvisionOperation(db, { operationId, planSha, reconcile = false, at = Date.now(), pid = process.pid }) {
+  const row = provisionOperation(db, operationId);
+  need(row && row.plan_sha === planSha && row.accepted_at !== null, 'provision-acceptance-required');
+  need(reconcile ? ['unknown', 'partial', 'running'].includes(row.state) : row.state === 'accepted', 'provision-reconcile-required');
+  db.prepare("UPDATE provision_operations SET state='running',owner_pid=?,generation=generation+1,updated_at=?,code=? WHERE operation_id=?")
+    .run(pid, at, reconcile ? 'reconciliation-started' : 'execution-started', operationId);
+  return journal(db, provisionOperation(db, operationId), reconcile ? 'reconciling' : 'started', at);
+}
+
+/** Persist safe checkpoints and terminal receipts under the execution generation that owns them. */
+function updateProvisionOperation(db, { operationId, generation, state = 'running', receiptSha = null, metadataSha = null, writeAck = false, code, at = Date.now(), pid = process.pid }) {
+  const row = provisionOperation(db, operationId);
+  need(row?.state === 'running' && row.generation === generation && row.owner_pid === pid, 'provision-executor-stale');
+  need(['running', 'applied', 'verified', 'failed', 'unknown', 'partial'].includes(state), 'provision-state-invalid');
+  db.prepare('UPDATE provision_operations SET state=?,receipt_sha=COALESCE(?,receipt_sha),metadata_sha=COALESCE(?,metadata_sha),write_ack=MAX(write_ack,?),code=?,updated_at=? WHERE operation_id=?')
+    .run(state, receiptSha, metadataSha, writeAck ? 1 : 0, code, at, operationId);
+  return journal(db, provisionOperation(db, operationId), state === 'running' ? 'checkpoint' : 'finished', at);
+}
+
+/** Canonical schema text is injected once; schema work stays lazy inside the existing typed transaction. */
+export function provisionWrites(canonicalSql) {
+  let schema;
+  return Object.freeze({
+    prepareProvisionOperation(db, args) {
+      schema ??= canonicalProvisionSchema(canonicalSql);
+      ensureProvisionSchema(db, schema);
+      return prepareProvisionOperation(db, args);
+    },
+    acceptProvisionOperation, authorizeProvisionGrant, claimProvisionOperation, updateProvisionOperation,
+  });
+}

package/runtime/engine/db/ref-value.mjs

@@ -0,0 +1,67 @@
+// ref-value.mjs — the one accessor of a column that holds content or a reference to it (the storage convention: content is a file in the blob store under the runtime state
+// dir, a row holds the reference).
+//
+// A column that may hold content holds either the content inline (the legacy shape, every row written before the convention) or a REFERENCE: the JSON stub machine.sqlite already
+// writes for a value it keeps in the blob store, {"truncated":true,"bytes":<n>,"sha256":"<sha>"} (valid JSON, so it also passes a column's json_valid check). Every handle either
+// store opens installs the resolver below, so a reader that selects such a column gets the content whichever shape the row has; a writer stores content with putContent, which
+// keeps a short value inline and puts a long one in the blob store. A value is resolved byte for byte: the blob holds exactly the text the writer was given.
+import { createRequire } from 'node:module';
+import { getBlob } from './blob.mjs';
+
+const REF = /^\{"truncated":true,"bytes":(\d+),"sha256":"([0-9a-f]{64})"\}$/;
+
+/** Whether a stored value is a reference. */
+export const isRef = (value) => typeof value === 'string' && value.codePointAt(0) === 123 && REF.test(value);
+
+/** The reference string of a blob. */
+export const refOf = (sha, bytes) => JSON.stringify({ truncated: true, bytes, sha256: sha });
+
+/** The {sha, bytes} a reference names, or null. */
+export function parseRef(value) {
+  const match = typeof value === 'string' && value.codePointAt(0) === 123 ? REF.exec(value) : null;
+  return match ? { sha: match[2], bytes: Number(match[1]) } : null;
+}
+
+/** The content behind a stored value: a reference is read from the blob store (utf8), anything else is the content itself. */
+function resolveValue(value) {
+  const ref = parseRef(value);
+  if (!ref) return value;
+  return getBlob(ref.sha).toString('utf8');
+}
+
+
+const resolveRow = (row) => {
+  if (row === null || row === undefined || typeof row !== 'object') return row;
+  for (const key of Object.keys(row)) if (isRef(row[key])) row[key] = resolveValue(row[key]);
+  return row;
+};
+
+/**
+ * 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 const openReadOnlyDb = (file, timeoutMs) => installRefResolver(new (createRequire(import.meta.url)('node:sqlite').DatabaseSync)(file, { readOnly: true, timeout: timeoutMs }));
+
+/** A statement over exact stored cells, for self-contained archives that retain references and their original bytes. */
+export const prepareStored = (db, sql, ...rest) => Object.getPrototypeOf(db).prepare.call(db, sql, ...rest);
+
+export function installRefResolver(db) {
+  if (db.__refResolver) return db;
+  // The prototype's prepare is looked up at each call, so a later change of the driver's own method (a spec's mock, a corruption injection) still applies.
+  db.prepare = (sql, ...rest) => {
+    const statement = prepareStored(db, sql, ...rest);
+    return new Proxy(statement, {
+      get(target, name) {
+        const member = target[name];
+        if (typeof member !== 'function') return member;
+        if (name === 'get') return (...args) => resolveRow(member.apply(target, args));
+        if (name === 'all') return (...args) => member.apply(target, args).map(resolveRow);
+        if (name === 'iterate') return (...args) => (function* resolved(iterator) { for (const row of iterator) yield resolveRow(row); })(member.apply(target, args));
+        return member.bind(target);
+      },
+    });
+  };
+  Object.defineProperty(db, '__refResolver', { value: true });
+  return db;
+}