@volter/twin 0.1.0

package/src/control-plane.ts

@@ -0,0 +1,66 @@
+// The CONTROL PLANE — the legitimately-shared thing across twins.
+//
+// This is the uniform contract + operator surface every twin is *driven* through:
+// the same way to serve/read/write, switch modes, see `status`, build a `plan`,
+// `push`/apply (with explicit phases), hold a `lease`, manage the event-queue
+// lifecycle, track remote refs, and run Git-like fork operations. An operator or
+// agent learns ONE way to drive any twin.
+//
+// What this is NOT: a "kernel" that makes every twin *implement its world the same
+// way*. Twins are implemented per-vendor (their exact API + query semantics). The
+// data-plane mechanics they reuse (event log, projection, shadow/delta, egress,
+// connectors — exported from the package root) are **optional libraries**, like a
+// UI library a visualizer may pick — not a mandate. See
+// `the twins architecture notes` → "share the control plane, not the
+// implementation".
+//
+// Barrel only: re-exports the control-plane surface as one cohesive thing. Consume
+// it as a namespace via `import { controlPlane } from '@volter/twin'`.
+
+// serve/read/write surface (how a twin is driven): one twin, readable always,
+// writable unless started read-only (writes land as local actions)
+export { applyTwinWrite, createTwinServer, resolveTwinRead, twinResources } from './serve.ts';
+export type { TwinResource, TwinWriteResult } from './serve.ts';
+
+// status
+export { formatStatus, worldStatus } from './status.ts';
+export type { WorldStatus } from './status.ts';
+
+// plan + apply orchestration
+export { applyPlan, buildApplyPlan, listPlans, pendingConflicts, planRequiresApproval, readPlan, writePlan } from './plan.ts';
+export type { ActionMapper, ApplyResult, ProviderCall, WorldApplyPlan } from './plan.ts';
+
+// push ledger + phases
+export { abandonPush, appendPushRecord, latestPushByActionId, listPushLedger, pushTransaction, unconfirmedPushes, UnreconciledPushError } from './pushLedger.ts';
+export type { PushOutcome, PushStatus, WorldPushRecord } from './pushLedger.ts';
+
+// apply leases (single-writer per checkpoint)
+export { acquireLease, activeLease, isLeaseActive, LeaseHeldError, listLeases, releaseLease } from './lease.ts';
+export type { WorldApplyLease } from './lease.ts';
+
+// remote refs / checkpoints + stale-base guard
+export { isBaseStale, listRemoteRefs, readLocalRef, readRemoteRef, writeLocalRef, writeRemoteRef } from './refs.ts';
+export type { WorldLocalRef, WorldRemoteRef } from './refs.ts';
+
+// event-queue lifecycle (queued/committed/ignored/superseded/poisoned)
+export {
+  commitPendingQueue, commitQueueRow, ignoreQueueRow, listQueueWithStatus,
+  pendingQueueRows, poisonQueueRow, queueCounts, queueRowStatus, setQueueRowStatus, supersedeQueueRow,
+} from './queueLifecycle.ts';
+export type { QueueCounts, QueueRowStatus, QueueRowWithStatus, QueueStatusTransition } from './queueLifecycle.ts';
+
+// confirm/revert ops (transaction → observed-event mapping)
+export { confirmAction } from './actions.ts';
+
+// fork operations (rebase/merge/cherry-pick/reset/discard) + three-way reconcile
+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';
+
+// sync direction (pull/push selected resources) — the bidirectional surface
+export { currentResources, syncPull, syncPush } from './sync.ts';
+export type { PullResult, PushItemResult, PushResult, SyncResource } from './sync.ts';

package/src/egress.ts

@@ -0,0 +1,355 @@
+import { createHash } from 'node:crypto';
+import { appendEvent, appendEventLocked, createEvent, eventsLockPath, listEvents, withFileLock, worldPaths } from './storage.ts';
+import type { WorldServiceEvent } from './types.ts';
+
+export const WRITE_INTENT_SUFFIX = '.write.intent';
+export const WRITE_RESULT_SUFFIX = '.write.result';
+
+export function isEgressEventType(type: string): boolean {
+  return type.endsWith(WRITE_INTENT_SUFFIX) || type.endsWith(WRITE_RESULT_SUFFIX);
+}
+
+export type EgressActor = {
+  kind: 'human' | 'agent' | 'bot' | 'system';
+  id?: string;
+  name?: string;
+};
+
+export type EgressWriteRequest = {
+  service: string;
+  /** Provider operation name, e.g. 'chat.postMessage', 'issueCreate'. */
+  operation: string;
+  /** external.provider value for result events, e.g. 'slack', 'github', 'linear'. */
+  provider: string;
+  subject: { type: string; id: string };
+  /**
+   * Stable key for the logical action. Two calls with the same key are the
+   * same action: a completed write is replayed from the ledger, never re-sent.
+   */
+  idempotencyKey: string;
+  actor?: EgressActor;
+  /** Request payload summary recorded on the intent event. Never put secrets here. */
+  data?: Record<string, unknown>;
+};
+
+export type EgressWriteOutcome = {
+  externalId: string;
+  url?: string;
+  data?: Record<string, unknown>;
+};
+
+export type EgressWriteResult = {
+  /** 'performed' = writeFn ran this call; 'replayed' = ledger already had a success. */
+  status: 'performed' | 'replayed';
+  intentEventId: string;
+  resultEventId: string;
+  attempt: number;
+  outcome: EgressWriteOutcome;
+};
+
+export type EgressLedgerEntry = {
+  intent: WorldServiceEvent;
+  results: WorldServiceEvent[];
+  succeeded: boolean;
+};
+
+export class UnreconciledWriteIntentError extends Error {
+  readonly intentEventId: string;
+
+  constructor(intentEventId: string, message: string) {
+    super(message);
+    this.name = 'UnreconciledWriteIntentError';
+    this.intentEventId = intentEventId;
+  }
+}
+
+function egressHash(request: EgressWriteRequest): string {
+  return createHash('sha256')
+    .update(`${request.service}\u001f${request.operation}\u001f${request.idempotencyKey}`)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function intentIdempotencyKey(request: EgressWriteRequest): string {
+  return `egress:${request.service}:${request.operation}:${request.idempotencyKey}:intent`;
+}
+
+function resultIdempotencyKey(request: EgressWriteRequest, attempt: number): string {
+  return `egress:${request.service}:${request.operation}:${request.idempotencyKey}:result:${attempt}`;
+}
+
+function defaultActor(actor?: EgressActor): EgressActor {
+  return actor ?? { kind: 'agent' };
+}
+
+function ledgerFor(service: string, root?: string): Map<string, EgressLedgerEntry> {
+  const entries = new Map<string, EgressLedgerEntry>();
+  const resultsByCausation = new Map<string, WorldServiceEvent[]>();
+  for (const event of listEvents(service, root)) {
+    if (event.type.endsWith(WRITE_INTENT_SUFFIX)) {
+      entries.set(event.id, { intent: event, results: [], succeeded: false });
+    } else if (event.type.endsWith(WRITE_RESULT_SUFFIX) && event.causationId) {
+      const bucket = resultsByCausation.get(event.causationId) ?? [];
+      bucket.push(event);
+      resultsByCausation.set(event.causationId, bucket);
+    }
+  }
+  for (const [intentId, results] of resultsByCausation) {
+    const entry = entries.get(intentId);
+    if (!entry) continue;
+    entry.results = results;
+    entry.succeeded = results.some((result) => result.data.status === 'success');
+  }
+  return entries;
+}
+
+function buildIntentEvent(request: EgressWriteRequest): WorldServiceEvent {
+  const hash = egressHash(request);
+  return createEvent({
+    id: `${request.service}${WRITE_INTENT_SUFFIX}:${hash}`,
+    service: request.service,
+    type: `${request.service}${WRITE_INTENT_SUFFIX}`,
+    idempotencyKey: intentIdempotencyKey(request),
+    occurredAt: new Date().toISOString(),
+    origin: 'agent',
+    actor: defaultActor(request.actor),
+    subject: request.subject,
+    correlationId: `${request.service}${WRITE_INTENT_SUFFIX}:${hash}`,
+    data: {
+      operation: request.operation,
+      provider: request.provider,
+      egressKey: request.idempotencyKey,
+      ...(request.data ?? {}),
+    },
+  });
+}
+
+export function recordWriteIntent(request: EgressWriteRequest, root?: string): WorldServiceEvent {
+  return appendEvent(buildIntentEvent(request), root).event;
+}
+
+function recordWriteResult(input: {
+  request: EgressWriteRequest;
+  intentEventId: string;
+  attempt: number;
+  status: 'success' | 'failed';
+  outcome?: EgressWriteOutcome;
+  error?: string;
+  root?: string;
+}): WorldServiceEvent {
+  const { request, intentEventId, attempt, status, outcome, error, root } = input;
+  const hash = egressHash(request);
+  const result = createEvent({
+    id: `${request.service}${WRITE_RESULT_SUFFIX}:${hash}:${attempt}`,
+    service: request.service,
+    type: `${request.service}${WRITE_RESULT_SUFFIX}`,
+    idempotencyKey: resultIdempotencyKey(request, attempt),
+    occurredAt: new Date().toISOString(),
+    origin: 'agent',
+    actor: defaultActor(request.actor),
+    subject: request.subject,
+    causationId: intentEventId,
+    correlationId: intentEventId,
+    ...(status === 'success' && outcome
+      ? {
+          external: {
+            provider: request.provider,
+            id: outcome.externalId,
+            ...(outcome.url ? { url: outcome.url } : {}),
+          },
+        }
+      : {}),
+    data: {
+      operation: request.operation,
+      provider: request.provider,
+      egressKey: request.idempotencyKey,
+      status,
+      attempt,
+      ...(outcome?.data ?? {}),
+      ...(error ? { error } : {}),
+    },
+  });
+  return appendEvent(result, root).event;
+}
+
+function replayOutcome(result: WorldServiceEvent): EgressWriteOutcome {
+  const { operation: _operation, provider: _provider, egressKey: _key, status: _status, attempt: _attempt, ...rest } = result.data;
+  return {
+    externalId: result.external?.id ?? '',
+    ...(result.external?.url ? { url: result.external.url } : {}),
+    data: rest,
+  };
+}
+
+// TWIN-58: same-process in-flight de-dup, keyed by (root, service, intentId). Two
+// callers racing the SAME idempotencyKey must invoke writeFn exactly once between
+// them; the SECOND caller awaits the FIRST's outcome and replays it rather than
+// redoing (or erroring out of) its own ledger-check. Populated synchronously,
+// before the first `await` in the winning call, so a caller that starts executing
+// immediately after (same microtask turn or later) is guaranteed to observe it.
+const inFlightWrites = new Map<string, Promise<EgressWriteResult>>();
+
+function inFlightKey(service: string, intentId: string, root?: string): string {
+  return `${root ?? ''}:${service}:${intentId}`;
+}
+
+// Explicit discriminated-union return type for the withFileLock callback below.
+// Left to plain inference, TS unifies the two return-statement shapes through the
+// `withFileLock<T>(lockPath, fn: () => T): T` generic in a way that widens
+// `claim.replay` to `EgressWriteResult | undefined` even after a `'replay' in
+// claim` check; naming the union explicitly makes the narrowing exact.
+type LockClaim = { replay: EgressWriteResult } | { intent: WorldServiceEvent; attempt: number };
+
+/**
+ * Perform an external write through the egress ledger.
+ *
+ * Ordering: a write.intent event is durably appended BEFORE the provider call,
+ * and a write.result event is appended after it (success or failure). A crash
+ * between the two leaves an intent without results; by default the next call
+ * with the same idempotencyKey refuses to re-send (UnreconciledWriteIntentError)
+ * because the provider may or may not have applied the write. After verifying
+ * the external state, callers retry with onUnreconciled: 'retry'.
+ *
+ * A ledger entry with a success result is terminal: the call returns the
+ * recorded outcome without invoking writeFn. Failed attempts may be retried;
+ * each attempt appends its own numbered result event.
+ *
+ * Concurrency (TWIN-58): the ledger-check + intent-append span runs under
+ * `withFileLock` on the SAME events lock `appendEvent` itself uses (egress.ts has
+ * no lock of its own to invent — reusing the events lock is what makes this
+ * atomic against a concurrent appendEvent/commitQueuedEvents too, not just a
+ * concurrent performExternalWrite). Without this, two concurrent calls with the
+ * same idempotencyKey could both read "no entry" and both invoke writeFn — the
+ * vendor receiving the write twice despite this function's contract that a
+ * completed write is replayed, never re-sent (see actions.ts:121-123 for the same
+ * check-then-append-under-one-lock reasoning applied to the action log). The
+ * `writeFn` call itself deliberately stays OUTSIDE the lock (it's arbitrary,
+ * possibly slow, real I/O — holding a file lock across it would serialize every
+ * write to the service, not just same-key ones); `inFlightWrites` covers the
+ * in-process race for the span the lock can't (an async call can't hold a
+ * synchronous lock across its own `await`).
+ */
+export async function performExternalWrite(
+  request: EgressWriteRequest,
+  writeFn: () => Promise<EgressWriteOutcome>,
+  options: { root?: string; onUnreconciled?: 'fail' | 'retry' } = {},
+): Promise<EgressWriteResult> {
+  const { root, onUnreconciled = 'fail' } = options;
+  const hash = egressHash(request);
+  const intentId = `${request.service}${WRITE_INTENT_SUFFIX}:${hash}`;
+  const flightKey = inFlightKey(request.service, intentId, root);
+
+  // Another in-process call already owns this idempotencyKey's write — replay its
+  // outcome (or its failure) instead of racing it.
+  const inFlight = inFlightWrites.get(flightKey);
+  if (inFlight) {
+    const settled = await inFlight;
+    return { ...settled, status: 'replayed' };
+  }
+
+  const paths = worldPaths(request.service, root);
+  const claim = withFileLock<LockClaim>(eventsLockPath(paths), () => {
+    const ledger = ledgerFor(request.service, root);
+    const existing = ledger.get(intentId);
+
+    if (existing) {
+      const success = existing.results.find((result) => result.data.status === 'success');
+      if (success) {
+        return {
+          replay: {
+            status: 'replayed' as const,
+            intentEventId: intentId,
+            resultEventId: success.id,
+            attempt: Number(success.data.attempt) || existing.results.length,
+            outcome: replayOutcome(success),
+          },
+        };
+      }
+      if (existing.results.length === 0 && onUnreconciled === 'fail') {
+        throw new UnreconciledWriteIntentError(
+          intentId,
+          `Write intent ${intentId} has no result event — the provider call may or may not have happened. ` +
+          `Verify external state, then retry with onUnreconciled: 'retry'.`,
+        );
+      }
+    }
+
+    const intent = existing?.intent ?? appendEventLocked(buildIntentEvent(request), paths).event;
+    const attempt = (existing?.results.length ?? 0) + 1;
+    return { intent, attempt };
+  });
+
+  if ('replay' in claim) return claim.replay;
+  const { intent, attempt } = claim;
+
+  // Register the in-flight promise BEFORE the first await below (synchronous from
+  // here), so a same-process concurrent call for this key — however soon it runs —
+  // finds it rather than re-entering the lock/ledger-check itself.
+  let resolveFlight!: (result: EgressWriteResult) => void;
+  let rejectFlight!: (error: unknown) => void;
+  const flight = new Promise<EgressWriteResult>((resolve, reject) => {
+    resolveFlight = resolve;
+    rejectFlight = reject;
+  });
+  // A rejection here is only ever "unhandled" when no concurrent caller happened to
+  // be waiting on this exact key — the normal (non-concurrent) case. Attach a no-op
+  // handler so that case doesn't surface as an unhandled rejection; a real waiter
+  // (the `await inFlight` above) still observes the SAME rejection independently.
+  flight.catch(() => {});
+  inFlightWrites.set(flightKey, flight);
+
+  try {
+    let outcome: EgressWriteOutcome;
+    try {
+      outcome = await writeFn();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      recordWriteResult({ request, intentEventId: intent.id, attempt, status: 'failed', error: message, root });
+      rejectFlight(error);
+      throw error;
+    }
+
+    const result = recordWriteResult({ request, intentEventId: intent.id, attempt, status: 'success', outcome, root });
+    const performed: EgressWriteResult = {
+      status: 'performed',
+      intentEventId: intent.id,
+      resultEventId: result.id,
+      attempt,
+      outcome,
+    };
+    resolveFlight(performed);
+    return performed;
+  } finally {
+    inFlightWrites.delete(flightKey);
+  }
+}
+
+/** Intents with no result event at all — crash candidates needing reconciliation. */
+export function listUnreconciledWriteIntents(service: string, root?: string): WorldServiceEvent[] {
+  return Array.from(ledgerFor(service, root).values())
+    .filter((entry) => entry.results.length === 0)
+    .map((entry) => entry.intent);
+}
+
+/** Full intent/result ledger for a service, keyed by intent event id. */
+export function listEgressLedger(service: string, root?: string): EgressLedgerEntry[] {
+  return Array.from(ledgerFor(service, root).values());
+}
+
+/**
+ * Echo lookup: did we produce this external object? Inbound events whose
+ * external id matches a recorded successful write are our own writes coming back.
+ */
+export function findWriteResultByExternal(
+  service: string,
+  provider: string,
+  externalId: string,
+  root?: string,
+): WorldServiceEvent | null {
+  for (const event of listEvents(service, root)) {
+    if (!event.type.endsWith(WRITE_RESULT_SUFFIX)) continue;
+    if (event.data.status !== 'success') continue;
+    if (event.external?.provider === provider && event.external.id === externalId) return event;
+  }
+  return null;
+}

package/src/fork.ts

@@ -0,0 +1,256 @@
+// 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.ts';
+import { appendAction, listActions, pendingActions, TwinActionPreconditionError } from './actions.ts';
+import type { TwinAction } from './actions.ts';
+import { pendingConflicts } from './plan.ts';
+import { listPushLedger } from './pushLedger.ts';
+import type { PushStatus } from './pushLedger.ts';
+import { twinResources } from './serve.ts';
+import type { TwinResource } from './serve.ts';
+import { appendEvent, listEvents, readJsonFile, worldPaths } from './storage.ts';
+import type { WorldServiceEvent } from './types.ts';
+
+export type ForkMeta = {
+  service: string;
+  forkedAt: string;
+  baseRoot: string;
+  baseEventCount: number;
+  baseLatestEventId: string | null;
+  // The base twin's resources at fork time — the divergence baseline.
+  baseline: TwinResource[];
+};
+
+// Fields that are bookkeeping, not vendor data — excluded from divergence diffs.
+const META_FIELDS = new Set(['id', 'type', 'updatedAt']);
+
+function forkMetaPath(service: string, root: string): string {
+  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: {
+  service: string;
+  toRoot: string;
+  fromRoot?: string;
+  occurredAt: string;
+}): ForkMeta {
+  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: ForkMeta = {
+    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: string, root: string): ForkMeta {
+  const path = forkMetaPath(service, root);
+  if (!existsSync(path)) throw new Error(`not a fork (no fork-meta.json) for ${service}: ${root}`);
+  return readJsonFile<ForkMeta>(path);
+}
+
+export function isFork(service: string, root: string): boolean {
+  return existsSync(forkMetaPath(service, root));
+}
+
+export type FieldDivergence = { before: unknown; after: unknown };
+export type SubjectDivergence = { id: string; type: string; changed: Record<string, FieldDivergence> };
+export type ForkDivergence = {
+  service: string;
+  baseCount: number;
+  currentCount: number;
+  created: TwinResource[]; // present now, absent at fork time
+  changed: SubjectDivergence[]; // field-level changes to pre-existing subjects
+};
+
+/** What changed in the fork relative to its recorded base. */
+export function forkDivergence(service: string, forkRoot: string): ForkDivergence {
+  const meta = readForkMeta(service, forkRoot);
+  const baseById = new Map(meta.baseline.map((r) => [r.id, r]));
+  const current = twinResources(service, forkRoot);
+  const created: TwinResource[] = [];
+  const changed: SubjectDivergence[] = [];
+
+  for (const cur of current) {
+    const base = baseById.get(cur.id);
+    if (!base) {
+      created.push(cur);
+      continue;
+    }
+    const fieldChanges: Record<string, FieldDivergence> = {};
+    const keys = new Set([...Object.keys(base), ...Object.keys(cur)].filter((k) => !META_FIELDS.has(k)));
+    for (const key of keys) {
+      const before = (base as Record<string, unknown>)[key];
+      const after = (cur as Record<string, unknown>)[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 };
+}
+
+export type ForkAudit = {
+  ok: boolean;
+  // local actions in the fork (the work done locally — never touches the vendor).
+  localActions: number;
+  // real writes seen across BOTH real-write channels: egress ledger entries
+  // (direct performExternalWrite / syncPush) plus push-ledger rows that reached
+  // (or attempted) the provider via pushTransaction / applyPlan. `ok: true` means
+  // no real write has happened from this fork YET — it is not a claim that this
+  // fork structurally cannot push (it can, by design).
+  realWrites: number;
+  breaches: string[];
+};
+
+// 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: ReadonlySet<PushStatus> = 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: string, forkRoot: string): ForkAudit {
+  const egressLedger = listEgressLedger(service, forkRoot);
+  const pushBreachActionIds = new Set<string>();
+  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: string): void {
+  rmSync(forkRoot, { recursive: true, force: true });
+}
+
+// ── Git-like fork operations (the twins architecture notes → "Fork Operations").
+// rebase / merge / cherry-pick / revert / discard|reset, all over the TRANSACTION
+// history, never canonical provider events. (revert is the action-log `revert` op;
+// discard is discardFork above.)
+
+export type CopyResult = { copied: TwinAction[]; conflicts: Array<{ actionId: string; reason: string }> };
+
+/**
+ * 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: { service: string; fromRoot: string; toRoot: string; actionIds: string[]; occurredAt: string }): CopyResult {
+  const wanted = new Set(opts.actionIds);
+  const src = listActions(opts.service, opts.fromRoot).filter((a) => a.op === 'set' && wanted.has(a.id));
+  const copied: TwinAction[] = [];
+  const conflicts: CopyResult['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: { service: string; intoRoot: string; fromRoot: string; occurredAt: string; force?: boolean }): CopyResult {
+  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: { service: string; root: string; occurredAt: string }): number {
+  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: { service: string; root: string; freshEvents: WorldServiceEvent[] }): { applied: number; conflicts: Array<{ actionId: string; reason: string }> } {
+  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) };
+}