@volter/twin 0.1.0

package/src/index.ts

@@ -0,0 +1,222 @@
+// @volter/twin — SHARED LIBRARIES a twin is built FROM. This is a library, NOT a
+// framework/"kernel": it does not own the request lifecycle and a pack is not required to
+// implement any contract here — a pack COMPOSES the vendor-INDEPENDENT mechanics it needs and
+// presents its own vendor's exact API + semantics (see ARCHITECTURE.md; "share the
+// vendor-independent mechanics, not the implementation — no false cross-vendor uniformity").
+// Two groupings, kept distinct on purpose:
+//   1. the OPERATOR CONTROL PLANE — what you DRIVE A TWIN'S STATE WITH (status/plan/push+phases/
+//      lease/refs/queue-lifecycle/fork-ops). Operator-facing (the `volter-twin` CLI), NOT a
+//      contract packs implement. Available cohesively as the `controlPlane` namespace below.
+//   2. the DATA-PLANE LIBRARIES a twin reuses (event log, projection, shadow/delta, egress,
+//      connectors). Vendor-independent mechanics; reuse them rather than reimplement (the
+//      durable log + projection ARE the product's state core, the same for every vendor).
+// (Annotations + source books are tracker concerns — @volter/tracker, not here.)
+// The flat exports below remain for back-compat; new code can lean on the split.
+export * as controlPlane from './control-plane.ts';
+// Conformance/validation tooling (capability + spec + recorded-diff + UI harnesses and
+// the spec derivers) is NOT part of the runtime kernel — it lives in @volter/twin-tooling,
+// a dev dependency. A twin runs without it; only tests and the conformance scripts use it.
+// Pack registry — vendor twins self-describe (TwinPack) so tooling discovers them.
+export { clearRegistry, getPack, hasPack, listPacks, registerPack } from './packRegistry.ts';
+export type { PackTransport, TwinPack } from './packRegistry.ts';
+
+export {
+  GenericWorldStateSchema,
+  WorldActorSchema,
+  WorldExternalRefSchema,
+  WorldServiceEventSchema,
+  WorldSubjectSchema,
+} from './schemas.ts';
+// NOTE: source books (event→tracker-source mapping) moved OUT of the world — it was
+// the last tracker coupling. It now lives at `@volter/tracker/world-source-books`,
+// so `@volter/twin` is a pure twin runtime.
+export {
+  findWriteResultByExternal,
+  isEgressEventType,
+  listEgressLedger,
+  listUnreconciledWriteIntents,
+  performExternalWrite,
+  recordWriteIntent,
+  UnreconciledWriteIntentError,
+  WRITE_INTENT_SUFFIX,
+  WRITE_RESULT_SUFFIX,
+} from './egress.ts';
+export type {
+  EgressActor,
+  EgressLedgerEntry,
+  EgressWriteOutcome,
+  EgressWriteRequest,
+  EgressWriteResult,
+} from './egress.ts';
+export {
+  loadWorldConfig,
+} from './worldConfig.ts';
+export type {
+  WorldConfig,
+  WorldServiceConfig,
+} from './worldConfig.ts';
+export {
+  buildShadowState,
+  DELTA_TYPE_SUFFIX,
+  diffSubjectFields,
+  hashFieldValue,
+  recordObservedDelta,
+} from './shadow.ts';
+export type {
+  DeltaObservation,
+  DeltaResult,
+  FieldChange,
+  ShadowState,
+  SubjectFieldExtractor,
+  SubjectFields,
+  SubjectShadow,
+} from './shadow.ts';
+export {
+  appendDurable,
+  appendEvent,
+  commitQueuedEvents,
+  createEvent,
+  emptyGenericState,
+  enqueueEvent,
+  genericWorldReducer,
+  listEvents,
+  listQueuedEvents,
+  loadState,
+  readJsonFile,
+  rebuildGenericState,
+  rebuildState,
+  // Scrub: delete pulled data at rest (TWIN-45) — the honest, plain-`rm` counterpart to
+  // sync pull's fold-into-the-log. See docs/DATA_AT_REST.md for the full data-at-rest story.
+  scrubService,
+  scrubWorld,
+  stateDirName,
+  // The kernel's cross-process mutual-exclusion primitive (exclusive-create lockfile with
+  // stale-holder reclaim). Public so world-runtime can guard concurrent `upWorld` claims of
+  // one instance dir with the SAME lock semantics the event log uses (TWIN-36).
+  withFileLock,
+  worldPaths,
+  worldStateRoot,
+} from './storage.ts';
+export type {
+  AppendEventResult,
+  CommitQueuedEventsResult,
+  GenericWorldState,
+  EnqueueEventResult,
+  QueuedWorldServiceEvent,
+  WorldPaths,
+  WorldReducer,
+  WorldServiceEvent,
+} from './types.ts';
+export type { ScrubResult } from './storage.ts';
+export {
+  loadPollCursor,
+  pollCursorPath,
+  runConnectorPoll,
+  runConnectorSweep,
+  savePollCursor,
+} from './connector.ts';
+export type {
+  ConnectorObservation,
+  ConnectorPollResult,
+  ConnectorSweepResult,
+  SweepConnector,
+  WorldConnector,
+} from './connector.ts';
+export {
+  discoverWorldServices,
+  summarizeWorldFindings,
+  validateWorld,
+  validateWorldService,
+} from './validate.ts';
+export type {
+  WorldValidationFinding,
+  WorldValidationReport,
+  WorldValidationSummary,
+} from './validate.ts';
+export {
+  applyTwinWrite,
+  createTwinServer,
+  resolveTwinRead,
+  twinResources,
+} from './serve.ts';
+export type {
+  TwinResource,
+} from './serve.ts';
+export { createTwinProxy } from './proxy.ts';
+export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.ts';
+export {
+  auditForkNoRealWrites,
+  cherryPickActions,
+  discardFork,
+  forkDivergence,
+  forkTwin,
+  isFork,
+  mergeForks,
+  rebaseFork,
+  readForkMeta,
+  resetFork,
+} from './fork.ts';
+export type { CopyResult, ForkAudit, ForkDivergence, ForkMeta, SubjectDivergence } from './fork.ts';
+export { isCleanlyReconcilable, reconcile, reconcileRequiresApproval } from './reconcile.ts';
+export type {
+  FieldDecision,
+  ReconcilePlan,
+  ReconcilePolicy,
+  SubjectReconcile,
+} from './reconcile.ts';
+export { currentResources, syncPull, syncPush } from './sync.ts';
+export type { PullResult, PushItemResult, PushResult, SyncResource } from './sync.ts';
+export { createVisualizerServer, renderTwinHtml } from './visualizer.ts';
+export {
+  appendAction,
+  appendTransactionCommit,
+  confirmAction,
+  listActions,
+  listTransactionCommits,
+  pendingActions,
+  pendingEmits,
+  pendingTransactionCommits,
+  projectResources,
+  TwinActionPreconditionError,
+} from './actions.ts';
+export type {
+  ActionProjection,
+  ProjectedDelivery,
+  ProjectedResource,
+  ProjectedResourcePatch,
+  ProjectedResourceRef,
+  TwinAction,
+  TwinActionOp,
+  TwinActionPrecondition,
+  TwinActionPreconditionOp,
+  TwinActionRevertSpec,
+  TwinTransactionCommit,
+  TwinTransactionCommitOp,
+  TwinTransactionPrecondition,
+  TwinTransactionRevertSpec,
+} from './actions.ts';
+// ── Operator control plane (R19/R20): remote refs, queue lifecycle, push ledger,
+// apply leases, plan, status. (the twins architecture notes)
+export { isBaseStale, listRemoteRefs, readLocalRef, readRemoteRef, writeLocalRef, writeRemoteRef } from './refs.ts';
+export type { WorldLocalRef, WorldRemoteRef } from './refs.ts';
+export {
+  commitPendingQueue,
+  commitQueueRow,
+  ignoreQueueRow,
+  listQueueWithStatus,
+  pendingQueueRows,
+  poisonQueueRow,
+  queueCounts,
+  queueRowStatus,
+  setQueueRowStatus,
+  supersedeQueueRow,
+} from './queueLifecycle.ts';
+export type { QueueCounts, QueueRowStatus, QueueRowWithStatus, QueueStatusTransition } from './queueLifecycle.ts';
+export { abandonPush, appendPushRecord, latestPushByActionId, listPushLedger, pushTransaction, unconfirmedPushes, UnreconciledPushError } from './pushLedger.ts';
+export type { PushOutcome, PushStatus, WorldPushRecord } from './pushLedger.ts';
+export { acquireLease, activeLease, isLeaseActive, LeaseHeldError, listLeases, releaseLease } from './lease.ts';
+export type { WorldApplyLease } from './lease.ts';
+export { applyPlan, buildApplyPlan, listPlans, pendingConflicts, planRequiresApproval, readPlan, writePlan } from './plan.ts';
+export type { ActionMapper, ApplyResult, ProviderCall, WorldApplyPlan } from './plan.ts';
+export { formatStatus, worldStatus } from './status.ts';
+export type { WorldStatus } from './status.ts';

package/src/lease.ts

@@ -0,0 +1,97 @@
+// Apply leases (the twins architecture notes → "Leases"). Before a push/apply, an
+// operator acquires a lease against a provider/checkpoint so two agents cannot push
+// divergent histories onto the same remote baseline. Invariant: at most one active
+// (unreleased, unexpired) lease per (provider, remoteRef.name). Deterministic:
+// caller supplies id/acquiredAt/expiresAt and `now` for expiry checks (no clock).
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { WorldRemoteRef } from './refs.ts';
+import { readJsonFile, withFileLock, worldPaths } from './storage.ts';
+
+export type WorldApplyLease = {
+  id: string;
+  service: string;
+  provider: string;
+  remoteRef: WorldRemoteRef;
+  planId: string;
+  holder: { kind: 'agent' | 'human' | 'system'; id: string };
+  acquiredAt: string;
+  expiresAt: string;
+  releasedAt?: string;
+};
+
+export class LeaseHeldError extends Error {
+  constructor(readonly held: WorldApplyLease) {
+    super(`apply lease already held for ${held.provider}/${held.remoteRef.name} by ${held.holder.kind}:${held.holder.id} (lease ${held.id})`);
+    this.name = 'LeaseHeldError';
+  }
+}
+
+function leasesDir(service: string, root?: string): string {
+  return join(worldPaths(service, root).dir, 'leases');
+}
+function leasePath(service: string, id: string, root?: string): string {
+  if (!/^[A-Za-z0-9_.-]+$/.test(id)) throw new Error(`invalid lease id: ${id}`);
+  return join(leasesDir(service, root), `${id}.json`);
+}
+/** The cross-process mutual-exclusion lockfile guarding acquireLease's whole
+ *  active-check + write critical section (see acquireLease). One lock per
+ *  service's leases dir — sufficient because the active-lease check itself is
+ *  scoped to (service, provider, refName) and different services never share a dir. */
+function acquireLockPath(service: string, root?: string): string {
+  return join(leasesDir(service, root), 'acquire.lock');
+}
+
+export function listLeases(service: string, root?: string): WorldApplyLease[] {
+  const dir = leasesDir(service, root);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => readJsonFile<WorldApplyLease>(join(dir, f)));
+}
+
+export function isLeaseActive(lease: WorldApplyLease, now: string): boolean {
+  return !lease.releasedAt && lease.expiresAt > now;
+}
+
+/** The active lease (if any) for a provider/checkpoint, given the current time. */
+export function activeLease(service: string, provider: string, refName: string, now: string, root?: string): WorldApplyLease | null {
+  return listLeases(service, root).find((l) => l.provider === provider && l.remoteRef.name === refName && isLeaseActive(l, now)) ?? null;
+}
+
+function writeLease(lease: WorldApplyLease, root?: string): WorldApplyLease {
+  const path = leasePath(lease.service, lease.id, root);
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(lease, null, 2)}\n`);
+  return lease;
+}
+
+/**
+ * Acquire an apply lease. Throws LeaseHeldError if another active lease already
+ * targets the same provider/checkpoint (single-writer). `now` is used only for the
+ * active-conflict check; `acquiredAt`/`expiresAt` are caller-supplied.
+ *
+ * The active-check + write is a single critical section run under `withFileLock`
+ * (the kernel's cross-process mutual-exclusion primitive — see storage.ts) so two
+ * concurrent acquirers targeting the same (service, provider, refName) cannot both
+ * observe "no active lease" and both write: only one holds the lock at a time, and
+ * by the time the second gets it, the first's lease (if it won) is already on disk.
+ */
+export function acquireLease(
+  opts: { service: string; provider: string; remoteRef: WorldRemoteRef; planId: string; holder: WorldApplyLease['holder']; id: string; acquiredAt: string; expiresAt: string; now?: string; root?: string },
+): WorldApplyLease {
+  const now = opts.now ?? opts.acquiredAt;
+  return withFileLock(acquireLockPath(opts.service, opts.root), () => {
+    const held = activeLease(opts.service, opts.provider, opts.remoteRef.name, now, opts.root);
+    if (held && held.id !== opts.id) throw new LeaseHeldError(held);
+    return writeLease({
+      id: opts.id, service: opts.service, provider: opts.provider, remoteRef: opts.remoteRef,
+      planId: opts.planId, holder: opts.holder, acquiredAt: opts.acquiredAt, expiresAt: opts.expiresAt,
+    }, opts.root);
+  });
+}
+
+export function releaseLease(service: string, id: string, opts: { root?: string; at?: string } = {}): WorldApplyLease {
+  const path = leasePath(service, id, opts.root);
+  if (!existsSync(path)) throw new Error(`no such lease: ${id}`);
+  const lease = readJsonFile<WorldApplyLease>(path);
+  return writeLease({ ...lease, releasedAt: opts.at ?? new Date().toISOString() }, opts.root);
+}

package/src/packRegistry.ts

@@ -0,0 +1,60 @@
+// Pack registry (the twins architecture notes → "Optional shared
+// libraries"; #1). A lightweight, dependency-free way for vendor twins to *declare*
+// themselves so tooling can discover them — "add a vendor" gets cheaper. A pack
+// EXPORTS a `TwinPack` descriptor (no import side-effects); a consumer that imports
+// the packs it wants registers them and queries the registry. The kernel never
+// imports packs (no dependency inversion) — discovery is the consumer's choice.
+//
+// This is an optional convenience, NOT a kernel that defines the twin: a pack can
+// ignore the registry entirely. Pure + deterministic.
+export type PackTransport = 'rest' | 'graphql' | 'web-api';
+
+export type TwinPack = {
+  /** vendor id / service, e.g. 'stripe'. */
+  vendor: string;
+  transport: PackTransport;
+  /** subject types the twin serves, e.g. ['customer','charge','payment_intent']. */
+  resources: string[];
+  /** the `world-<vendor>` operator bin, if any. */
+  bin?: string;
+  /** conformance field map { object: { field: type } } — vendored or derived from the spec. */
+  conformanceFields?: Record<string, Record<string, string>>;
+  /** where the exact surface came from (a spec path) — provenance for re-derivation. */
+  specSource?: string;
+  /** one-line human description. */
+  description?: string;
+  /** How this vendor's BROWSER SDK addresses its API — used by the zero-edit dev proxy so
+   *  the kernel proxy stays vendor-agnostic (it forwards/rewrites by these values, never by a
+   *  hardcoded vendor table). `apiPathPrefix`: the same-origin path the browser SDK calls
+   *  (e.g. Stripe.js → '/v1/'). `loaderHost`: the absolute API host to strip from the loaded
+   *  SDK so its calls become same-origin (e.g. 'https://api.stripe.com'). Omit for vendors
+   *  with no browser SDK. */
+  browserRouting?: { apiPathPrefix: string; loaderHost?: string };
+};
+
+const registry = new Map<string, TwinPack>();
+
+/** Register (or replace) a pack descriptor. Returns it. */
+export function registerPack(pack: TwinPack): TwinPack {
+  if (!/^[a-z0-9-]+$/.test(pack.vendor)) throw new Error(`invalid pack vendor id: ${pack.vendor}`);
+  registry.set(pack.vendor, pack);
+  return pack;
+}
+
+export function getPack(vendor: string): TwinPack | undefined {
+  return registry.get(vendor);
+}
+
+/** All registered packs, sorted by vendor (deterministic). */
+export function listPacks(): TwinPack[] {
+  return [...registry.values()].sort((a, b) => a.vendor.localeCompare(b.vendor));
+}
+
+export function hasPack(vendor: string): boolean {
+  return registry.has(vendor);
+}
+
+/** Clear the registry (tests). */
+export function clearRegistry(): void {
+  registry.clear();
+}

package/src/plan.ts

@@ -0,0 +1,190 @@
+// Apply plan (the twins architecture notes → "Plan"). The Terraform-plan /
+// pull-request object for non-code systems: a reviewable, replayable proposal of
+// exactly what a push/apply will do — which local transactions, the provider
+// calls + idempotency keys, destructive flags, expected confirmations, conflicts
+// (failed preconditions), and whether approval is required. No real push happens
+// from an implicit action list; it executes a plan. `applyPlan` is the gated
+// orchestrator: recompute requiresApproval from the plan's own data (never trust
+// the stored bit) → refuse a stale base → acquire lease → push each call through
+// phases → release.
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pendingActions, projectResources } from './actions.ts';
+import type { TwinAction, TwinActionPrecondition } from './actions.ts';
+import { isBaseStale } from './refs.ts';
+import type { WorldLocalRef, WorldRemoteRef } from './refs.ts';
+import { acquireLease, releaseLease } from './lease.ts';
+import { pushTransaction } from './pushLedger.ts';
+import type { PushOutcome, WorldPushRecord } from './pushLedger.ts';
+import type { TwinResource } from './serve.ts';
+import { readJsonFile, worldPaths } from './storage.ts';
+
+export type ProviderCall = {
+  actionId: string;
+  provider: string;
+  operation: string;
+  input: Record<string, unknown>;
+  idempotencyKey: string;
+  destructive: boolean;
+  expectedConfirmation: { subject: { type: string; id: string }; eventType: string; matcher: Record<string, unknown> };
+};
+
+export type WorldApplyPlan = {
+  id: string;
+  service: string;
+  forkId: string;
+  baseRemoteRef: WorldRemoteRef;
+  transactions: string[];
+  providerCalls: ProviderCall[];
+  conflicts: Array<{ actionId: string; reason: string }>;
+  requiresApproval: boolean;
+  createdAt: string;
+};
+
+/** Map a local transaction commit → the provider call that materializes it (vendor-specific). Return null to skip. */
+export type ActionMapper = (action: TwinAction) => Omit<ProviderCall, 'actionId'> | null;
+
+function resourcesById(service: string, root?: string): Map<string, TwinResource> {
+  return new Map(projectResources(service, root).map((r) => [`${r.type}:${r.id}`, r]));
+}
+
+function preconditionFailure(action: TwinAction, byId: Map<string, TwinResource>): string | null {
+  for (const p of action.preconditions ?? []) {
+    const resource = byId.get(`${p.subject.type}:${p.subject.id}`);
+    const actual = resource ? (resource as Record<string, unknown>)[p.field] : undefined;
+    const ok = evalPrecondition(p, actual);
+    if (!ok) return `${p.subject.type}:${p.subject.id}.${p.field} ${p.op}${p.value !== undefined ? ` ${JSON.stringify(p.value)}` : ''}`;
+  }
+  return null;
+}
+function evalPrecondition(p: TwinActionPrecondition, actual: unknown): boolean {
+  switch (p.op) {
+    case 'exists': return actual !== undefined;
+    case 'not_exists': return actual === undefined;
+    case 'eq': case 'version_eq': return Object.is(actual, p.value);
+    case 'neq': return !Object.is(actual, p.value);
+    default: return false;
+  }
+}
+
+/** Pending transactions whose preconditions would fail against current projected state. */
+export function pendingConflicts(service: string, root?: string): Array<{ actionId: string; reason: string }> {
+  const byId = resourcesById(service, root);
+  const out: Array<{ actionId: string; reason: string }> = [];
+  for (const action of pendingActions(service, root)) {
+    const failure = preconditionFailure(action, byId);
+    if (failure) out.push({ actionId: action.id, reason: `precondition would fail: ${failure}` });
+  }
+  return out;
+}
+
+/**
+ * Build a reviewable apply plan from a fork's pending transactions. `mapper` is the
+ * vendor-specific action→provider-call mapping; actions it returns null for are
+ * omitted. Conflicts are pending actions whose preconditions fail against current
+ * projected state. Approval is required if any call is destructive or any conflict exists.
+ */
+export function buildApplyPlan(opts: {
+  service: string;
+  forkId: string;
+  baseRemoteRef: WorldRemoteRef;
+  mapper: ActionMapper;
+  id: string;
+  createdAt: string;
+  root?: string;
+}): WorldApplyPlan {
+  const pending = pendingActions(opts.service, opts.root);
+  const byId = resourcesById(opts.service, opts.root);
+  const providerCalls: ProviderCall[] = [];
+  const conflicts: WorldApplyPlan['conflicts'] = [];
+  for (const action of pending) {
+    const failure = preconditionFailure(action, byId);
+    if (failure) { conflicts.push({ actionId: action.id, reason: `precondition would fail: ${failure}` }); continue; }
+    const mapped = opts.mapper(action);
+    if (mapped) providerCalls.push({ actionId: action.id, ...mapped });
+  }
+  return {
+    id: opts.id, service: opts.service, forkId: opts.forkId, baseRemoteRef: opts.baseRemoteRef,
+    transactions: pending.map((a) => a.id), providerCalls, conflicts,
+    requiresApproval: conflicts.length > 0 || providerCalls.some((c) => c.destructive),
+    createdAt: opts.createdAt,
+  };
+}
+
+function plansDir(service: string, root?: string): string {
+  return join(worldPaths(service, root).dir, 'plans');
+}
+export function writePlan(plan: WorldApplyPlan, root?: string): WorldApplyPlan {
+  if (!/^[A-Za-z0-9_.-]+$/.test(plan.id)) throw new Error(`invalid plan id: ${plan.id}`);
+  const path = join(plansDir(plan.service, root), `${plan.id}.json`);
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(plan, null, 2)}\n`);
+  return plan;
+}
+export function readPlan(service: string, id: string, root?: string): WorldApplyPlan | null {
+  const path = join(plansDir(service, root), `${id}.json`);
+  return existsSync(path) ? readJsonFile<WorldApplyPlan>(path) : null;
+}
+export function listPlans(service: string, root?: string): WorldApplyPlan[] {
+  const dir = plansDir(service, root);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => readJsonFile<WorldApplyPlan>(join(dir, f)));
+}
+
+export type ApplyResult = { planId: string; leaseId: string; pushed: WorldPushRecord[]; skipped: string[] };
+
+/**
+ * Whether a plan requires approval before it may be applied — recomputed from the
+ * plan's OWN `providerCalls`/`conflicts`, the exact rule `buildApplyPlan` uses to set
+ * the field in the first place. `applyPlan` calls this instead of trusting
+ * `plan.requiresApproval`: that field lives on plan JSON that is neither signed nor
+ * otherwise authenticated, so a hand-edited file (or a hand-built plan object) that
+ * flips the boolean to `false` must not be able to skip the approval gate — only
+ * removing the destructive calls/conflicts themselves does.
+ */
+export function planRequiresApproval(plan: WorldApplyPlan): boolean {
+  return plan.conflicts.length > 0 || plan.providerCalls.some((c) => c.destructive);
+}
+
+/**
+ * Enact a plan against the real provider — the gated push path. Refuses an
+ * unapproved plan (approval requirement recomputed from the plan's own data, never
+ * trusted off the stored bit) and a push whose base has gone stale (the live
+ * remote ref moved since `plan.baseRemoteRef` was recorded) before any provider
+ * call or lease acquisition — zero side effects either way. Then acquires an apply
+ * lease for the plan's baseRemoteRef (single-writer), drives every provider call
+ * through the push phases via the injected writeFn (the only real I/O), then
+ * releases the lease.
+ */
+export async function applyPlan(
+  plan: WorldApplyPlan,
+  writeFn: (call: ProviderCall) => Promise<PushOutcome>,
+  opts: { holder: { kind: 'agent' | 'human' | 'system'; id: string }; leaseId: string; acquiredAt: string; expiresAt: string; occurredAt: string; approve?: boolean; overrideStaleBase?: boolean; root?: string },
+): Promise<ApplyResult> {
+  if (planRequiresApproval(plan) && !opts.approve) throw new Error(`plan ${plan.id} requires approval (conflicts or destructive calls); pass approve:true to apply`);
+  const localRefView: WorldLocalRef = { service: plan.service, forkId: plan.forkId, baseRemoteRef: plan.baseRemoteRef, recordedAt: plan.createdAt };
+  if (isBaseStale(localRefView, opts.root) && !opts.overrideStaleBase) {
+    throw new Error(`plan ${plan.id} base (${plan.baseRemoteRef.provider}/${plan.baseRemoteRef.name}) is stale — the remote ref advanced since this plan's base was recorded; rebase and rebuild the plan, or pass overrideStaleBase:true to apply anyway`);
+  }
+  const lease = acquireLease({
+    service: plan.service, provider: plan.baseRemoteRef.provider, remoteRef: plan.baseRemoteRef, planId: plan.id,
+    holder: opts.holder, id: opts.leaseId, acquiredAt: opts.acquiredAt, expiresAt: opts.expiresAt, now: opts.acquiredAt, root: opts.root,
+  });
+  const pushed: WorldPushRecord[] = [];
+  const skipped: string[] = [];
+  const actionsById = new Map(pendingActions(plan.service, opts.root).map((a) => [a.id, a]));
+  try {
+    for (const call of plan.providerCalls) {
+      const action = actionsById.get(call.actionId);
+      if (!action) { skipped.push(call.actionId); continue; }
+      const record = await pushTransaction(
+        { service: plan.service, action: { id: action.id, subject: action.subject, fields: action.fields ?? {}, correlationId: action.correlationId }, provider: call.provider, operation: call.operation, idempotencyKey: call.idempotencyKey, occurredAt: opts.occurredAt, root: opts.root },
+        () => writeFn(call),
+      );
+      pushed.push(record);
+    }
+  } finally {
+    releaseLease(plan.service, lease.id, { at: opts.occurredAt, root: opts.root });
+  }
+  return { planId: plan.id, leaseId: lease.id, pushed, skipped };
+}