@volter/twin 0.1.0

package/dist/src/fork.js

@@ -0,0 +1,206 @@
+// Fork mode for twins (the twins architecture notes): a deliberate,
+// auditable divergence from a known base.
+//
+// simulator already accepts local writes; fork ADDS three things on top:
+//   1. a KNOWN BASE — snapshot the source twin's state at fork time, into an
+//      isolated root, so the fork starts byte-identical to its base (copy-on-write).
+//   2. DIVERGENCE — diff the fork's current state against that recorded base
+//      (what an agent changed while working in the fork).
+//   3. a CHECKABLE REAL-WRITE AUDIT: local writes in a fork stay in the action
+//      log and never touch the vendor — but a fork is NOT forbidden from pushing
+//      for real (that's the whole "fork it... push selected changes back" arc,
+//      via `applyPlan`/`pushTransaction` or `syncPush`); the fork boundary is a
+//      sandbox for local work, not a guarantee no real write can ever happen from
+//      it. `auditForkNoRealWrites` is therefore a checkable REPORT — has any real
+//      write happened from this fork SO FAR? — not a structural impossibility
+//      proof, and it has to look at every channel a real write can travel
+//      through: the egress ledger (direct `performExternalWrite`/`syncPush`
+//      calls) AND the push ledger (`pushTransaction`/`applyPlan`). Missing either
+//      channel makes `ok: true` a fabricated green on a fork that pushed.
+//
+// Convergence (rebase onto a fresh pull / push the divergence to real) is the
+// separate `reconcile` concern and is not implemented here.
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { listEgressLedger } from "./egress.js";
+import { appendAction, listActions, pendingActions, TwinActionPreconditionError } from "./actions.js";
+import { pendingConflicts } from "./plan.js";
+import { listPushLedger } from "./pushLedger.js";
+import { twinResources } from "./serve.js";
+import { appendEvent, listEvents, readJsonFile, worldPaths } from "./storage.js";
+// Fields that are bookkeeping, not vendor data — excluded from divergence diffs.
+const META_FIELDS = new Set(['id', 'type', 'updatedAt']);
+function forkMetaPath(service, root) {
+    return join(dirname(worldPaths(service, root).events), 'fork-meta.json');
+}
+/**
+ * Create a fork of `service` from `fromRoot` into the fresh isolated `toRoot`.
+ * Copies the base event log so the fork folds to identical state, then records
+ * the baseline. `occurredAt` is supplied by the caller (deterministic; no clock).
+ */
+export function forkTwin(opts) {
+    const { service, toRoot, fromRoot } = opts;
+    if (existsSync(forkMetaPath(service, toRoot))) {
+        throw new Error(`fork target already initialized for ${service}: ${toRoot}`);
+    }
+    const baseEvents = listEvents(service, fromRoot);
+    // Copy the base log into the fork root (copy-on-write: the fork owns its log).
+    for (const event of baseEvents)
+        appendEvent(event, toRoot);
+    const baseline = twinResources(service, toRoot).sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const meta = {
+        service,
+        forkedAt: opts.occurredAt,
+        baseRoot: fromRoot ?? '',
+        baseEventCount: baseEvents.length,
+        baseLatestEventId: baseEvents.length ? baseEvents[baseEvents.length - 1].id : null,
+        baseline,
+    };
+    writeFileSync(forkMetaPath(service, toRoot), `${JSON.stringify(meta, null, 2)}\n`);
+    return meta;
+}
+export function readForkMeta(service, root) {
+    const path = forkMetaPath(service, root);
+    if (!existsSync(path))
+        throw new Error(`not a fork (no fork-meta.json) for ${service}: ${root}`);
+    return readJsonFile(path);
+}
+export function isFork(service, root) {
+    return existsSync(forkMetaPath(service, root));
+}
+/** What changed in the fork relative to its recorded base. */
+export function forkDivergence(service, forkRoot) {
+    const meta = readForkMeta(service, forkRoot);
+    const baseById = new Map(meta.baseline.map((r) => [r.id, r]));
+    const current = twinResources(service, forkRoot);
+    const created = [];
+    const changed = [];
+    for (const cur of current) {
+        const base = baseById.get(cur.id);
+        if (!base) {
+            created.push(cur);
+            continue;
+        }
+        const fieldChanges = {};
+        const keys = new Set([...Object.keys(base), ...Object.keys(cur)].filter((k) => !META_FIELDS.has(k)));
+        for (const key of keys) {
+            const before = base[key];
+            const after = cur[key];
+            if (JSON.stringify(before) !== JSON.stringify(after))
+                fieldChanges[key] = { before, after };
+        }
+        if (Object.keys(fieldChanges).length > 0)
+            changed.push({ id: cur.id, type: cur.type, changed: fieldChanges });
+    }
+    created.sort((a, b) => (a.id < b.id ? -1 : 1));
+    changed.sort((a, b) => (a.id < b.id ? -1 : 1));
+    return { service, baseCount: meta.baseline.length, currentCount: current.length, created, changed };
+}
+// A push-ledger row at any of these statuses means writeFn was actually invoked
+// (or its outcome recorded) — a real provider call, not just a locally-queued
+// intent. 'attempted' is written unconditionally right before writeFn runs, so
+// its presence alone already implies every later status is also a real write;
+// listed explicitly (rather than "anything past intent") so the set reads as a
+// deliberate audit policy, not an artifact of the phase ordering. 'abandoned'
+// and bare 'intent' are excluded: those mean writeFn was never called.
+const PUSH_REAL_WRITE_STATUSES = new Set([
+    'attempted', 'provider_accepted', 'observed_confirmed', 'projection_suppressed', 'confirmed', 'succeeded', 'failed',
+]);
+/**
+ * Report whether the fork has made any real write SO FAR (R18 model + TWIN-52):
+ * local fork work lives in the ACTION log and never reaches the vendor on its
+ * own, so a real write can only have happened through one of the two channels
+ * that touch the vendor —
+ *   - the egress ledger (`performExternalWrite`, and `syncPush` which is built
+ *     on it): any entry there is a completed or attempted direct write.
+ *   - the push ledger (`pushTransaction`, and `applyPlan` which drives it): any
+ *     row whose status reached `attempted` or further is a real provider call
+ *     that was made (or is unreconciled — see UnreconciledPushError — which is
+ *     itself "may have happened", so it counts as a breach too).
+ * Reading only the egress ledger (the old implementation) missed the push
+ * channel entirely: a fork that pushed via `applyPlan`/`pushTransaction` (the
+ * canonical arc in examples/lifecycle.ts) audited as `{ok:true, realWrites:0}`,
+ * a fabricated green. This is a checkable AUDIT of what happened, not a
+ * guarantee that nothing can — pushing for real from a fork is a supported
+ * operation, not a violation.
+ */
+export function auditForkNoRealWrites(service, forkRoot) {
+    const egressLedger = listEgressLedger(service, forkRoot);
+    const pushBreachActionIds = new Set();
+    for (const row of listPushLedger(service, forkRoot)) {
+        if (PUSH_REAL_WRITE_STATUSES.has(row.status))
+            pushBreachActionIds.add(row.actionId);
+    }
+    const breaches = [...egressLedger.map((e) => e.intent.id), ...pushBreachActionIds];
+    return {
+        ok: egressLedger.length === 0 && pushBreachActionIds.size === 0,
+        localActions: pendingActions(service, forkRoot).length,
+        realWrites: egressLedger.length + pushBreachActionIds.size,
+        breaches,
+    };
+}
+/** Remove a fork root entirely (the fork is throwaway by design). */
+export function discardFork(forkRoot) {
+    rmSync(forkRoot, { recursive: true, force: true });
+}
+/**
+ * cherry-pick: copy selected `set` transaction commits from one fork into another.
+ * A commit whose precondition fails in the target is reported as a conflict, not
+ * applied (the rest still copy).
+ */
+export function cherryPickActions(opts) {
+    const wanted = new Set(opts.actionIds);
+    const src = listActions(opts.service, opts.fromRoot).filter((a) => a.op === 'set' && wanted.has(a.id));
+    const copied = [];
+    const conflicts = [];
+    for (const a of src) {
+        try {
+            copied.push(appendAction({ ...a, occurredAt: opts.occurredAt }, opts.toRoot));
+        }
+        catch (e) {
+            if (e instanceof TwinActionPreconditionError)
+                conflicts.push({ actionId: a.id, reason: e.message });
+            else
+                throw e;
+        }
+    }
+    return { copied, conflicts };
+}
+/**
+ * merge: combine another fork's ACTIVE (pending) transaction history into this one.
+ * Requires compatible bases (same base latest-event id) unless `force`. Failed
+ * preconditions surface as conflicts.
+ */
+export function mergeForks(opts) {
+    const into = readForkMeta(opts.service, opts.intoRoot);
+    const from = readForkMeta(opts.service, opts.fromRoot);
+    if (!opts.force && into.baseLatestEventId !== from.baseLatestEventId) {
+        throw new Error(`merge: incompatible fork bases (${into.baseLatestEventId} vs ${from.baseLatestEventId}); rebase first or pass force`);
+    }
+    const ids = pendingActions(opts.service, opts.fromRoot).map((a) => a.id);
+    return cherryPickActions({ service: opts.service, fromRoot: opts.fromRoot, toRoot: opts.intoRoot, actionIds: ids, occurredAt: opts.occurredAt });
+}
+/**
+ * reset: suppress all local projections non-destructively by appending a revert for
+ * every pending transaction (history is retained — unlike discardFork, which deletes
+ * the root). Returns how many transactions were reset.
+ */
+export function resetFork(opts) {
+    const pending = pendingActions(opts.service, opts.root);
+    for (const a of pending) {
+        appendAction({ id: `revert:${a.id}`, service: opts.service, op: 'revert', subject: a.subject, occurredAt: opts.occurredAt, revertsActionId: a.id }, opts.root);
+    }
+    return pending.length;
+}
+/**
+ * rebase: commit fresh remote observations onto the fork's base, then replay active
+ * local transactions over the new base. Transactions whose preconditions now fail
+ * are returned as conflicts (the doc's "failed preconditions become conflicts").
+ */
+export function rebaseFork(opts) {
+    let applied = 0;
+    for (const ev of opts.freshEvents)
+        if (appendEvent(ev, opts.root).appended)
+            applied += 1;
+    return { applied, conflicts: pendingConflicts(opts.service, opts.root) };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,42 @@
+export * as controlPlane from './control-plane.js';
+export { clearRegistry, getPack, hasPack, listPacks, registerPack } from './packRegistry.js';
+export type { PackTransport, TwinPack } from './packRegistry.js';
+export { GenericWorldStateSchema, WorldActorSchema, WorldExternalRefSchema, WorldServiceEventSchema, WorldSubjectSchema, } from './schemas.js';
+export { findWriteResultByExternal, isEgressEventType, listEgressLedger, listUnreconciledWriteIntents, performExternalWrite, recordWriteIntent, UnreconciledWriteIntentError, WRITE_INTENT_SUFFIX, WRITE_RESULT_SUFFIX, } from './egress.js';
+export type { EgressActor, EgressLedgerEntry, EgressWriteOutcome, EgressWriteRequest, EgressWriteResult, } from './egress.js';
+export { loadWorldConfig, } from './worldConfig.js';
+export type { WorldConfig, WorldServiceConfig, } from './worldConfig.js';
+export { buildShadowState, DELTA_TYPE_SUFFIX, diffSubjectFields, hashFieldValue, recordObservedDelta, } from './shadow.js';
+export type { DeltaObservation, DeltaResult, FieldChange, ShadowState, SubjectFieldExtractor, SubjectFields, SubjectShadow, } from './shadow.js';
+export { appendDurable, appendEvent, commitQueuedEvents, createEvent, emptyGenericState, enqueueEvent, genericWorldReducer, listEvents, listQueuedEvents, loadState, readJsonFile, rebuildGenericState, rebuildState, scrubService, scrubWorld, stateDirName, withFileLock, worldPaths, worldStateRoot, } from './storage.js';
+export type { AppendEventResult, CommitQueuedEventsResult, GenericWorldState, EnqueueEventResult, QueuedWorldServiceEvent, WorldPaths, WorldReducer, WorldServiceEvent, } from './types.js';
+export type { ScrubResult } from './storage.js';
+export { loadPollCursor, pollCursorPath, runConnectorPoll, runConnectorSweep, savePollCursor, } from './connector.js';
+export type { ConnectorObservation, ConnectorPollResult, ConnectorSweepResult, SweepConnector, WorldConnector, } from './connector.js';
+export { discoverWorldServices, summarizeWorldFindings, validateWorld, validateWorldService, } from './validate.js';
+export type { WorldValidationFinding, WorldValidationReport, WorldValidationSummary, } from './validate.js';
+export { applyTwinWrite, createTwinServer, resolveTwinRead, twinResources, } from './serve.js';
+export type { TwinResource, } from './serve.js';
+export { createTwinProxy } from './proxy.js';
+export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.js';
+export { auditForkNoRealWrites, cherryPickActions, discardFork, forkDivergence, forkTwin, isFork, mergeForks, rebaseFork, readForkMeta, resetFork, } from './fork.js';
+export type { CopyResult, ForkAudit, ForkDivergence, ForkMeta, SubjectDivergence } from './fork.js';
+export { isCleanlyReconcilable, reconcile, reconcileRequiresApproval } from './reconcile.js';
+export type { FieldDecision, ReconcilePlan, ReconcilePolicy, SubjectReconcile, } from './reconcile.js';
+export { currentResources, syncPull, syncPush } from './sync.js';
+export type { PullResult, PushItemResult, PushResult, SyncResource } from './sync.js';
+export { createVisualizerServer, renderTwinHtml } from './visualizer.js';
+export { appendAction, appendTransactionCommit, confirmAction, listActions, listTransactionCommits, pendingActions, pendingEmits, pendingTransactionCommits, projectResources, TwinActionPreconditionError, } from './actions.js';
+export type { ActionProjection, ProjectedDelivery, ProjectedResource, ProjectedResourcePatch, ProjectedResourceRef, TwinAction, TwinActionOp, TwinActionPrecondition, TwinActionPreconditionOp, TwinActionRevertSpec, TwinTransactionCommit, TwinTransactionCommitOp, TwinTransactionPrecondition, TwinTransactionRevertSpec, } from './actions.js';
+export { isBaseStale, listRemoteRefs, readLocalRef, readRemoteRef, writeLocalRef, writeRemoteRef } from './refs.js';
+export type { WorldLocalRef, WorldRemoteRef } from './refs.js';
+export { commitPendingQueue, commitQueueRow, ignoreQueueRow, listQueueWithStatus, pendingQueueRows, poisonQueueRow, queueCounts, queueRowStatus, setQueueRowStatus, supersedeQueueRow, } from './queueLifecycle.js';
+export type { QueueCounts, QueueRowStatus, QueueRowWithStatus, QueueStatusTransition } from './queueLifecycle.js';
+export { abandonPush, appendPushRecord, latestPushByActionId, listPushLedger, pushTransaction, unconfirmedPushes, UnreconciledPushError } from './pushLedger.js';
+export type { PushOutcome, PushStatus, WorldPushRecord } from './pushLedger.js';
+export { acquireLease, activeLease, isLeaseActive, LeaseHeldError, listLeases, releaseLease } from './lease.js';
+export type { WorldApplyLease } from './lease.js';
+export { applyPlan, buildApplyPlan, listPlans, pendingConflicts, planRequiresApproval, readPlan, writePlan } from './plan.js';
+export type { ActionMapper, ApplyResult, ProviderCall, WorldApplyPlan } from './plan.js';
+export { formatStatus, worldStatus } from './status.js';
+export type { WorldStatus } from './status.js';

package/dist/src/index.js

@@ -0,0 +1,52 @@
+// @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.js";
+// 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.js";
+export { GenericWorldStateSchema, WorldActorSchema, WorldExternalRefSchema, WorldServiceEventSchema, WorldSubjectSchema, } from "./schemas.js";
+// 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.js";
+export { loadWorldConfig, } from "./worldConfig.js";
+export { buildShadowState, DELTA_TYPE_SUFFIX, diffSubjectFields, hashFieldValue, recordObservedDelta, } from "./shadow.js";
+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.js";
+export { loadPollCursor, pollCursorPath, runConnectorPoll, runConnectorSweep, savePollCursor, } from "./connector.js";
+export { discoverWorldServices, summarizeWorldFindings, validateWorld, validateWorldService, } from "./validate.js";
+export { applyTwinWrite, createTwinServer, resolveTwinRead, twinResources, } from "./serve.js";
+export { createTwinProxy } from "./proxy.js";
+export { auditForkNoRealWrites, cherryPickActions, discardFork, forkDivergence, forkTwin, isFork, mergeForks, rebaseFork, readForkMeta, resetFork, } from "./fork.js";
+export { isCleanlyReconcilable, reconcile, reconcileRequiresApproval } from "./reconcile.js";
+export { currentResources, syncPull, syncPush } from "./sync.js";
+export { createVisualizerServer, renderTwinHtml } from "./visualizer.js";
+export { appendAction, appendTransactionCommit, confirmAction, listActions, listTransactionCommits, pendingActions, pendingEmits, pendingTransactionCommits, projectResources, TwinActionPreconditionError, } from "./actions.js";
+// ── 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.js";
+export { commitPendingQueue, commitQueueRow, ignoreQueueRow, listQueueWithStatus, pendingQueueRows, poisonQueueRow, queueCounts, queueRowStatus, setQueueRowStatus, supersedeQueueRow, } from "./queueLifecycle.js";
+export { abandonPush, appendPushRecord, latestPushByActionId, listPushLedger, pushTransaction, unconfirmedPushes, UnreconciledPushError } from "./pushLedger.js";
+export { acquireLease, activeLease, isLeaseActive, LeaseHeldError, listLeases, releaseLease } from "./lease.js";
+export { applyPlan, buildApplyPlan, listPlans, pendingConflicts, planRequiresApproval, readPlan, writePlan } from "./plan.js";
+export { formatStatus, worldStatus } from "./status.js";

package/dist/src/lease.d.ts

@@ -0,0 +1,50 @@
+import type { WorldRemoteRef } from './refs.js';
+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 declare class LeaseHeldError extends Error {
+    readonly held: WorldApplyLease;
+    constructor(held: WorldApplyLease);
+}
+export declare function listLeases(service: string, root?: string): WorldApplyLease[];
+export declare function isLeaseActive(lease: WorldApplyLease, now: string): boolean;
+/** The active lease (if any) for a provider/checkpoint, given the current time. */
+export declare function activeLease(service: string, provider: string, refName: string, now: string, root?: string): WorldApplyLease | null;
+/**
+ * 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 declare 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;
+export declare function releaseLease(service: string, id: string, opts?: {
+    root?: string;
+    at?: string;
+}): WorldApplyLease;

package/dist/src/lease.js

@@ -0,0 +1,80 @@
+// 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 { readJsonFile, withFileLock, worldPaths } from "./storage.js";
+export class LeaseHeldError extends Error {
+    held;
+    constructor(held) {
+        super(`apply lease already held for ${held.provider}/${held.remoteRef.name} by ${held.holder.kind}:${held.holder.id} (lease ${held.id})`);
+        this.held = held;
+        this.name = 'LeaseHeldError';
+    }
+}
+function leasesDir(service, root) {
+    return join(worldPaths(service, root).dir, 'leases');
+}
+function leasePath(service, id, root) {
+    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, root) {
+    return join(leasesDir(service, root), 'acquire.lock');
+}
+export function listLeases(service, root) {
+    const dir = leasesDir(service, root);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => readJsonFile(join(dir, f)));
+}
+export function isLeaseActive(lease, now) {
+    return !lease.releasedAt && lease.expiresAt > now;
+}
+/** The active lease (if any) for a provider/checkpoint, given the current time. */
+export function activeLease(service, provider, refName, now, root) {
+    return listLeases(service, root).find((l) => l.provider === provider && l.remoteRef.name === refName && isLeaseActive(l, now)) ?? null;
+}
+function writeLease(lease, root) {
+    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) {
+    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, id, opts = {}) {
+    const path = leasePath(service, id, opts.root);
+    if (!existsSync(path))
+        throw new Error(`no such lease: ${id}`);
+    const lease = readJsonFile(path);
+    return writeLease({ ...lease, releasedAt: opts.at ?? new Date().toISOString() }, opts.root);
+}

package/dist/src/packRegistry.d.ts

@@ -0,0 +1,34 @@
+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;
+    };
+};
+/** Register (or replace) a pack descriptor. Returns it. */
+export declare function registerPack(pack: TwinPack): TwinPack;
+export declare function getPack(vendor: string): TwinPack | undefined;
+/** All registered packs, sorted by vendor (deterministic). */
+export declare function listPacks(): TwinPack[];
+export declare function hasPack(vendor: string): boolean;
+/** Clear the registry (tests). */
+export declare function clearRegistry(): void;

package/dist/src/packRegistry.js

@@ -0,0 +1,22 @@
+const registry = new Map();
+/** Register (or replace) a pack descriptor. Returns it. */
+export function registerPack(pack) {
+    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) {
+    return registry.get(vendor);
+}
+/** All registered packs, sorted by vendor (deterministic). */
+export function listPacks() {
+    return [...registry.values()].sort((a, b) => a.vendor.localeCompare(b.vendor));
+}
+export function hasPack(vendor) {
+    return registry.has(vendor);
+}
+/** Clear the registry (tests). */
+export function clearRegistry() {
+    registry.clear();
+}

package/dist/src/plan.d.ts

@@ -0,0 +1,97 @@
+import type { TwinAction } from './actions.js';
+import type { WorldRemoteRef } from './refs.js';
+import type { PushOutcome, WorldPushRecord } from './pushLedger.js';
+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;
+/** Pending transactions whose preconditions would fail against current projected state. */
+export declare function pendingConflicts(service: string, root?: string): Array<{
+    actionId: string;
+    reason: string;
+}>;
+/**
+ * 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 declare function buildApplyPlan(opts: {
+    service: string;
+    forkId: string;
+    baseRemoteRef: WorldRemoteRef;
+    mapper: ActionMapper;
+    id: string;
+    createdAt: string;
+    root?: string;
+}): WorldApplyPlan;
+export declare function writePlan(plan: WorldApplyPlan, root?: string): WorldApplyPlan;
+export declare function readPlan(service: string, id: string, root?: string): WorldApplyPlan | null;
+export declare function listPlans(service: string, root?: string): WorldApplyPlan[];
+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 declare function planRequiresApproval(plan: WorldApplyPlan): boolean;
+/**
+ * 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 declare 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>;