@volter/twin 0.1.0 → 0.1.1

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { keepProcessAlive } from './lifecycle.ts';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { hasFlag, optionValue } from './args.ts';
@@ -28,8 +29,11 @@ import {
   listRemoteRefs,
   pendingActions,
   pendingConflicts,
+  buildLocalActionPlan,
+  recordPlanReview,
   createTwinProxy,
   getPack,
+  runEmitCli,
 } from './index.ts';
 import { readForkMeta } from './fork.ts';
 import { twinResources } from './serve.ts';
@@ -45,11 +49,16 @@ function jsonField(stdout: string, path: string): string {
   }
   // Comma-separated paths compose an id from multiple fields, joined with ':'
   // (e.g. --id-field channel,ts → "C123:1718000.42").
-  const parts = path.split(',').map((segmentPath) => {
+  // NB: these locals are deliberately NOT named `segment`/`segmentPath`. The architecture
+  // guardrail forbids any vendor's pack name appearing as a bare identifier anywhere in the
+  // kernel, and `segment` became a vendor pack name — a generic word colliding with a vendor is
+  // exactly the substring trap ADDING_A_TWIN warns about, and it turns a kernel-local variable
+  // into a false "kernel branches on vendor identity" report.
+  const parts = path.split(',').map((fieldPath) => {
     let value = parsed;
-    for (const segment of segmentPath.trim().split('.')) {
+    for (const key of fieldPath.trim().split('.')) {
       if (!value || typeof value !== 'object' || Array.isArray(value)) return '';
-      value = (value as Record<string, unknown>)[segment];
+      value = (value as Record<string, unknown>)[key];
     }
     return typeof value === 'string' || typeof value === 'number' ? String(value) : '';
   });
@@ -73,13 +82,18 @@ Resources:
   paths        show
   egress       write, ledger, unreconciled
   validate     (egress reconciliation; annotations are a tracker concern now)
-  status       <service>   plan <service>   refs <service>
+  status       <service>   plan <service>   review <service>   refs <service>
   scrub        <service> | --all   [--force] [--root <path>]   delete pulled data at rest
+  emit         <service> --list | <service> <event.type> <subject-id> [--root <path>]
+               deliver a signed vendor event synthesized from twin state (pack-provided;
+               the standing surface is the pack bin, e.g. \`world-stripe emit ...\`)
 
 Examples:
   world events append --file /tmp/event.json
   world events list chat --json
   world state rebuild chat
+  world plan chat --root <project>
+  world review chat --plan-id <exact-id> --decision approved|rejected --actor-id <id> [--reason <text>] --root <project>
   world validate [--root <path>] [--services chat,github]
   world egress write chat --operation message.send --provider slack \\
     --subject-type channel --subject-id dev --key case:ENG-1:approval-request \\
@@ -156,9 +170,24 @@ async function main(): Promise<void> {
     // The provider-call mapping is a vendor-pack concern (see buildApplyPlan).
     const service = action;
     if (!service) throw new Error('world plan: missing service');
-    const transactions = pendingActions(service).map((a) => ({ id: a.id, operation: a.operation, subject: a.subject }));
-    const conflicts = pendingConflicts(service);
-    print({ service, transactions, conflicts, requiresApproval: conflicts.length > 0 }, true);
+    const root = optionValue(rest, '--root') || undefined;
+    print(buildLocalActionPlan(service, root), true);
+    return;
+  }
+
+  if (resource === 'review') {
+    const service = action;
+    if (!service) throw new Error('world review: missing service');
+    const expectedTransactionSetId = optionValue(rest, '--plan-id');
+    if (!expectedTransactionSetId) throw new Error('world review: --plan-id is required (run `world plan <service>` and review that exact id)');
+    const decision = optionValue(rest, '--decision');
+    if (decision !== 'approved' && decision !== 'rejected') throw new Error('world review: --decision must be approved or rejected');
+    const actorId = optionValue(rest, '--actor-id');
+    if (!actorId) throw new Error('world review: --actor-id is required');
+    const actorKind = optionValue(rest, '--actor-kind', 'human');
+    if (actorKind !== 'human' && actorKind !== 'agent') throw new Error('world review: --actor-kind must be human or agent');
+    const root = optionValue(rest, '--root') || undefined;
+    print(recordPlanReview({ service, expectedTransactionSetId, decision, actor: { kind: actorKind, id: actorId }, reason: optionValue(rest, '--reason') || undefined, root }), true);
     return;
   }
 
@@ -182,7 +211,7 @@ async function main(): Promise<void> {
     if (once) { print(resolveTwinRead(service, once), true); return; }
     const server = createTwinServer({ service, readOnly, ...(port ? { port } : {}) });
     process.stdout.write(`state inspection for ${service}${readOnly ? ' (read-only)' : ''} at http://127.0.0.1:${server.port} (generic reads — NOT the vendor API)\n`);
-    await new Promise(() => {}); // serve until killed
+    await keepProcessAlive(); // serve until killed
   }
 
   // Browser zero-edit injection: a dev proxy in front of your app that forwards
@@ -227,7 +256,7 @@ async function main(): Promise<void> {
     const proxy = createTwinProxy({ target, map, ...(port ? { port } : {}) });
     const pairs = Object.entries(map).map(([v, r]) => `${v}(${r.apiPathPrefix})→${r.origin}`).join(', ');
     process.stdout.write(`twin proxy on http://127.0.0.1:${proxy.port} → ${target} (forwarding ${pairs})\n`);
-    await new Promise(() => {}); // serve until killed
+    await keepProcessAlive(); // serve until killed
   }
 
   // NOTE: `world annotations` moved to the tracker — annotations are a tracker
@@ -390,6 +419,27 @@ async function main(): Promise<void> {
     return;
   }
 
+  // The DELIVER verb: `volter-twin emit <service> …` fires a vendor-shaped, SIGNED event
+  // synthesized from current twin state at the app's registered webhook endpoint(s).
+  // Vendor synthesis lives in the pack (TwinPack.emitter) — the kernel never imports packs,
+  // so this only works in a consumer process that registered the pack; the standing operator
+  // surface is the pack's own bin (`world-stripe emit …`), like the mirror UIs.
+  if (resource === 'emit') {
+    const service = action;
+    if (!service) throw new Error('volter-twin emit: missing service (e.g. `volter-twin emit stripe --list`)');
+    const emitter = getPack(service)?.emitter;
+    if (!emitter) {
+      throw new Error(
+        `volter-twin emit: no emitter is registered for "${service}" in this process. ` +
+          `Emit is vendor knowledge and lives in the pack — run \`world-${service} emit --list\` / ` +
+          `\`world-${service} emit <event.type> <subject-id> [--root DIR]\` (packs without emitter ` +
+          `support say so loudly there), or register the ${service} pack (registerPack) before using this verb.`,
+      );
+    }
+    process.exitCode = await runEmitCli(emitter, rest);
+    return;
+  }
+
   // Mirror UIs moved to the per-vendor twin packages (modular). Point users there.
   if (resource === 'mirror') {
     throw new Error(`world mirror: vendor mirror UIs live in their own packages now — run \`world-${action ?? '<vendor>'} mirror\` (e.g. world-stripe / world-linear / world-jira / world-github / world-slack).`);
@@ -404,7 +454,7 @@ async function main(): Promise<void> {
     const port = Number(optionValue(rest, '--port', '0')) || undefined;
     const server = createVisualizerServer({ service, ...(port ? { port } : {}) });
     process.stdout.write(`${service} twin visualizer at http://127.0.0.1:${server.port}\n`);
-    await new Promise(() => {});
+    await keepProcessAlive();
     return;
   }
 

package/src/connector.ts

@@ -14,8 +14,18 @@
 //    landing at exactly that timestamp after the poll is not excluded by a
 //    strictly-greater filter; the overlap re-fetch is free (unchanged
 //    observations append nothing)
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+//  - PULL POSTURE (the rule that is not a comment): both runners are CADENCE runners — a cursor
+//    exists so the poll can be repeated, a sweep exists so subjects can be re-observed. So each
+//    one asserts the vendor's declared pull posture BEFORE `fetchSince`/`fetchSubject` is ever
+//    called: a refused vendor issues ZERO vendor requests. `connector.vendor` is required (a
+//    pack descriptor, or a registered vendor id) because an unnamed vendor cannot be checked, and
+//    an unchecked scheduled pull is how a rate-fragile vendor gets locked out. A one-off,
+//    human-asked pull of an on-demand vendor is still allowed — pass `trigger: 'explicit'`, which
+//    is a deliberate, greppable statement rather than the default.
+import { join } from 'node:path';
+import { getActiveWorldStore } from './world-store.ts';
+import { assertContinuousPullAllowed, DEFAULT_PULL_TRIGGER } from './packRegistry.ts';
+import type { PullTrigger, PullVendor } from './packRegistry.ts';
 import { buildShadowState, recordObservedDelta } from './shadow.ts';
 import type { SubjectFields } from './shadow.ts';
 import { appendEvent, readJsonFile, rebuildGenericState, worldPaths } from './storage.ts';
@@ -38,6 +48,13 @@ export type ConnectorObservation = {
 
 export type WorldConnector = {
   service: string;
+  /**
+   * WHICH VENDOR this connector pulls — the pack descriptor (preferred: it carries its own
+   * posture) or a vendor id registered via `registerPack`. Required, and deliberately separate
+   * from `service`: a world's service name is the caller's word (a chat world may be served by any
+   * chat vendor), while the posture is a fact about the VENDOR's rate limits.
+   */
+  vendor: PullVendor;
   /** Cursor filename under the service's cursors/ dir (default poll.json). */
   cursorFile?: string;
   /** Seed the shadow from historical event types (default: deltas only). */
@@ -71,23 +88,25 @@ export function pollCursorPath(service: string, root?: string, cursorFile = 'pol
 
 export function loadPollCursor(service: string, root?: string, cursorFile?: string): string {
   const path = pollCursorPath(service, root, cursorFile);
-  if (!existsSync(path)) return '';
+  if (!getActiveWorldStore().exists(path)) return '';
   return readJsonFile<{ after?: string }>(path).after ?? '';
 }
 
 export function savePollCursor(service: string, after: string, root?: string, cursorFile?: string): void {
   const path = pollCursorPath(service, root, cursorFile);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify({ after, updatedAt: new Date().toISOString() }, null, 2)}\n`);
+  getActiveWorldStore().write(path, `${JSON.stringify({ after, updatedAt: new Date().toISOString() }, null, 2)}\n`);
 }
 
 export async function runConnectorPoll(
   connector: WorldConnector,
-  options: { root?: string; cursor?: string; limit?: number } = {},
+  options: { root?: string; cursor?: string; limit?: number; trigger?: PullTrigger } = {},
 ): Promise<ConnectorPollResult> {
   const root = options.root;
   const service = connector.service;
   const limit = options.limit ?? 10000;
+  // BEFORE any I/O: a scheduled poll of a vendor that may only be pulled on demand is refused
+  // here, with the cursor untouched and not one vendor request issued.
+  if ((options.trigger ?? DEFAULT_PULL_TRIGGER) === 'scheduled') assertContinuousPullAllowed(connector.vendor);
   const cursorBefore = options.cursor ?? loadPollCursor(service, root, connector.cursorFile);
 
   const { observations, truncated } = await connector.fetchSince({ cursor: cursorBefore, limit, root: root ?? process.env.PROJECT_ROOT ?? process.cwd() });
@@ -149,6 +168,8 @@ import type { ShadowState } from './shadow.ts';
 
 export type SweepConnector = {
   service: string;
+  /** WHICH VENDOR this sweep re-observes — see `WorldConnector.vendor`. Required, same reason. */
+  vendor: PullVendor;
   shadowExtractor?: (event: WorldServiceEvent) => SubjectFields | null;
   /** Which tracked subjects to re-observe this sweep. */
   selectSubjects(input: {
@@ -176,12 +197,14 @@ export type ConnectorSweepResult = {
 
 export async function runConnectorSweep(
   connector: SweepConnector,
-  options: { root?: string; limit?: number; sweepAll?: boolean } = {},
+  options: { root?: string; limit?: number; sweepAll?: boolean; trigger?: PullTrigger } = {},
 ): Promise<ConnectorSweepResult> {
   const root = options.root;
   const service = connector.service;
   const limit = options.limit ?? 200;
   const sweepAll = options.sweepAll ?? false;
+  // Same guard, same place: before a single `fetchSubject` goes out.
+  if ((options.trigger ?? DEFAULT_PULL_TRIGGER) === 'scheduled') assertContinuousPullAllowed(connector.vendor);
 
   const generic = loadState<GenericWorldState>(service, root);
   const allSubjects = Object.values(generic?.subjects ?? {}).map((subject) => {

package/src/control-plane.ts

@@ -26,12 +26,28 @@ export type { TwinResource, TwinWriteResult } from './serve.ts';
 export { formatStatus, worldStatus } from './status.ts';
 export type { WorldStatus } from './status.ts';
 
+// the changeset primitive + the ledger diff (operational VCS v0): mark a base, diff the
+// delta since it, freeze it into a content-addressed changeset, replay it into another world
+export {
+  buildChangeset,
+  captureMarker,
+  changesetContentHash,
+  changesetHashMatches,
+  diffLedgers,
+  formatChangeset,
+  formatLedgerDelta,
+  formatReplayReport,
+  replayChangeset,
+  worldBootMarker,
+} from './changeset.ts';
+export type { Changeset, ChangesetAction, LedgerDelta, LedgerRef, ReplayReport, ReplayTarget, WorldMarker } from './changeset.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 { abandonPush, appendPushRecord, assertFastForward, latestPushByActionId, listPushLedger, NonFastForwardPushError, pushTransaction, unconfirmedPushes, UnreconciledPushError } from './pushLedger.ts';
 export type { PushOutcome, PushStatus, WorldPushRecord } from './pushLedger.ts';
 
 // apply leases (single-writer per checkpoint)

package/src/emit.ts

@@ -0,0 +1,242 @@
+// The DELIVER verb (`emit`) — fire a vendor-shaped, SIGNED webhook/event at the app under
+// test, synthesized from CURRENT TWIN STATE, without hand-constructing the envelope or the
+// signature. The engine here is vendor-agnostic; everything vendor-shaped (which event types
+// exist, which twin resource supplies `data.object`, where registered endpoints + signing
+// secrets live in state, how a delivery is signed) is a pack's knowledge, declared as a
+// `TwinEmitter` and registered on its `TwinPack.emitter` (same argument as `browserRouting`:
+// vendor knowledge in the descriptor, kernel stays vendor-agnostic).
+//
+// The operator surface is the PACK's bin (`world-stripe emit …`), exactly like the mirror
+// UIs — the kernel never imports packs, so `volter-twin emit <service>` only works when a
+// consumer registered the pack in-process, and otherwise fails loudly pointing at the
+// vendor bin. Unlike the twin's own background emission on state changes (fire-and-forget,
+// vendor-faithful), an explicit DELIVER is an operator asking for exactly this delivery, so
+// every failure here is LOUD: unknown event type, unknown subject, no registered endpoint,
+// and non-2xx delivery responses all throw / report instead of being swallowed.
+
+/** One event type a pack can synthesize, and the twin resource type that supplies its payload. */
+export type EmittableEvent = {
+  type: string;
+  /** twin resource type whose current state becomes the event payload (`data.object` for Stripe). */
+  subjectType: string;
+  description?: string;
+};
+
+/** A delivery destination registered IN TWIN STATE (at rest — the emit CLI runs in its own
+ *  process, so in-memory registries don't count; endpoints must be resolvable from the root). */
+export type EmitEndpoint = {
+  /** the vendor resource id of the registration (e.g. Stripe `we_…`), when it has one. */
+  id?: string;
+  url: string;
+  /** event-type subscriptions; `*` wildcards supported. Absent ⇒ subscribed to everything. */
+  enabledEvents?: string[];
+};
+
+/** A fully built, signed delivery for one endpoint: exact body bytes + headers to POST. */
+export type SynthesizedDelivery = {
+  /** the exact payload string — the signature covers THESE bytes, do not re-serialize. */
+  payload: string;
+  headers: Record<string, string>;
+  /** the synthesized event envelope (for reporting/assertions). */
+  event: Record<string, unknown>;
+};
+
+/** What a pack declares to support `emit` — see `TwinPack.emitter`. All state reads take the
+ *  same `root` every pack verb takes, so the CLI composes with worlds unchanged. */
+export type TwinEmitter = {
+  vendor: string;
+  /** the emittable catalog (drives `--list` and the unknown-event error). */
+  events(): EmittableEvent[];
+  /** endpoints registered in twin state (e.g. Stripe webhook_endpoint rows). */
+  endpoints(root?: string): EmitEndpoint[];
+  /** subject ids present in state for a subject type (drives `--list` + unknown-subject errors). */
+  subjects(subjectType: string, root?: string): string[];
+  /** synthesize the signed delivery for one endpoint. MUST throw loudly on an unknown subject. */
+  synthesize(opts: { type: string; subjectId: string; endpoint: EmitEndpoint; root?: string; occurredAt?: string }): SynthesizedDelivery;
+};
+
+export type EmitDeliveryResult = {
+  endpoint: EmitEndpoint;
+  ok: boolean;
+  /** HTTP status when the POST completed; absent when the request itself failed. */
+  status?: number;
+  error?: string;
+  event: Record<string, unknown>;
+};
+
+export type EmitReport = {
+  vendor: string;
+  type: string;
+  subjectId: string;
+  deliveries: EmitDeliveryResult[];
+  /** true only when EVERY delivery reached its endpoint and got a 2xx back. */
+  ok: boolean;
+};
+
+/** Vendor wildcard subscription match (Stripe semantics: `*` matches all;
+ *  `invoice.*` matches every invoice event; otherwise exact). */
+export function eventSubscriptionMatches(pattern: string, type: string): boolean {
+  if (pattern === '*') return true;
+  if (pattern.endsWith('.*')) return type.startsWith(pattern.slice(0, -1));
+  return pattern === type;
+}
+
+function endpointSubscribed(endpoint: EmitEndpoint, type: string): boolean {
+  if (!endpoint.enabledEvents || endpoint.enabledEvents.length === 0) return true;
+  return endpoint.enabledEvents.some((p) => eventSubscriptionMatches(p, type));
+}
+
+/** The `--list` view: everything emittable right now — event types, the subject ids present in
+ *  state for each subject type, and the registered endpoints. Pure state read. */
+export function listEmittable(emitter: TwinEmitter, root?: string): {
+  vendor: string;
+  events: Array<EmittableEvent & { subjects: string[] }>;
+  endpoints: EmitEndpoint[];
+} {
+  const subjectsByType = new Map<string, string[]>();
+  const events = emitter.events().map((e) => {
+    let subjects = subjectsByType.get(e.subjectType);
+    if (!subjects) {
+      subjects = emitter.subjects(e.subjectType, root);
+      subjectsByType.set(e.subjectType, subjects);
+    }
+    return { ...e, subjects };
+  });
+  return { vendor: emitter.vendor, events, endpoints: emitter.endpoints(root) };
+}
+
+/**
+ * DELIVER: synthesize the event for (`type`, `subjectId`) from current twin state and POST it,
+ * signed, to every registered endpoint subscribed to that event type (or the one endpoint
+ * `endpoint` names by url or id). Loud failures:
+ *   • event type the pack can't synthesize → throws, listing the emittable types;
+ *   • unknown subject id → the pack's synthesize throws (listing available ids);
+ *   • no registered/subscribed endpoint → throws (register one via the vendor API first);
+ *   • a delivery that errors or comes back non-2xx → reported per-endpoint, report.ok=false.
+ * `fetchFn` is the delivery seam (tests inject; default real fetch).
+ */
+export async function emitTwinEvent(
+  emitter: TwinEmitter,
+  opts: {
+    type: string;
+    subjectId: string;
+    root?: string;
+    /** restrict delivery to the endpoint with this url or vendor id. */
+    endpoint?: string;
+    occurredAt?: string;
+    fetchFn?: (url: string, init: { method: string; headers: Record<string, string>; body: string }) => Promise<{ status: number }>;
+  },
+): Promise<EmitReport> {
+  const catalog = emitter.events();
+  const known = catalog.find((e) => e.type === opts.type);
+  if (!known) {
+    throw new Error(
+      `emit: the ${emitter.vendor} pack cannot synthesize "${opts.type}". Emittable event types:\n  ${catalog.map((e) => `${e.type} (subject: ${e.subjectType})`).join('\n  ')}`,
+    );
+  }
+
+  const all = emitter.endpoints(opts.root);
+  if (all.length === 0) {
+    throw new Error(
+      `emit: no ${emitter.vendor} webhook endpoint is registered in twin state — nothing to deliver to. ` +
+        `Register one through the vendor API first (for Stripe: POST /v1/webhook_endpoints with url + enabled_events).`,
+    );
+  }
+  let targets = all.filter((e) => endpointSubscribed(e, opts.type));
+  if (opts.endpoint) {
+    targets = targets.filter((e) => e.url === opts.endpoint || e.id === opts.endpoint);
+    if (targets.length === 0) {
+      throw new Error(
+        `emit: no registered endpoint matches "${opts.endpoint}" for event "${opts.type}". Registered endpoints:\n  ${all.map((e) => `${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n  ')}`,
+      );
+    }
+  }
+  if (targets.length === 0) {
+    throw new Error(
+      `emit: ${all.length} endpoint(s) registered but none subscribes to "${opts.type}". Registered endpoints:\n  ${all.map((e) => `${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n  ')}`,
+    );
+  }
+
+  const fetchFn = opts.fetchFn ?? (async (url: string, init: { method: string; headers: Record<string, string>; body: string }) => {
+    const res = await fetch(url, init);
+    return { status: res.status };
+  });
+
+  const deliveries: EmitDeliveryResult[] = [];
+  for (const endpoint of targets) {
+    // synthesize PER ENDPOINT: signatures are per-endpoint secrets (real Stripe signs each
+    // delivery with the destination endpoint's own whsec). Unknown subject throws here — loudly.
+    const built = emitter.synthesize({ type: opts.type, subjectId: opts.subjectId, endpoint, ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}) });
+    try {
+      const res = await fetchFn(endpoint.url, { method: 'POST', headers: built.headers, body: built.payload });
+      deliveries.push({ endpoint, ok: res.status >= 200 && res.status < 300, status: res.status, event: built.event, ...(res.status >= 200 && res.status < 300 ? {} : { error: `endpoint responded ${res.status}` }) });
+    } catch (error) {
+      deliveries.push({ endpoint, ok: false, error: error instanceof Error ? error.message : String(error), event: built.event });
+    }
+  }
+  return { vendor: emitter.vendor, type: opts.type, subjectId: opts.subjectId, deliveries, ok: deliveries.every((d) => d.ok) };
+}
+
+/**
+ * Shared CLI glue so every pack's `emit` verb behaves identically:
+ *   world-<vendor> emit --list [--root DIR] [--json]
+ *   world-<vendor> emit <event.type> <subject-id> [--root DIR] [--endpoint URL|ID] [--at ISO] [--json]
+ * Returns the process exit code (0 delivered; 1 loud failure / any failed delivery; 2 usage).
+ */
+export async function runEmitCli(
+  emitter: TwinEmitter,
+  argv: string[],
+  io: { out: (s: string) => void; err: (s: string) => void } = { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s) },
+): Promise<number> {
+  const flags = new Map<string, string>();
+  const positional: string[] = [];
+  let list = false;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--list') list = true;
+    else if (a === '--json') json = true;
+    else if (a.startsWith('--')) {
+      flags.set(a, argv[i + 1] ?? '');
+      i += 1;
+    } else positional.push(a);
+  }
+  const root = flags.get('--root');
+
+  if (list) {
+    const view = listEmittable(emitter, root);
+    if (json) {
+      io.out(`${JSON.stringify(view, null, 2)}\n`);
+    } else {
+      io.out(`emittable ${view.vendor} events (synthesized from current twin state):\n`);
+      for (const e of view.events) {
+        io.out(`  ${e.type}  (subject: ${e.subjectType}${e.subjects.length ? ` — ${e.subjects.join(', ')}` : ' — none in state'})\n`);
+      }
+      io.out(view.endpoints.length === 0
+        ? 'no webhook endpoints registered — deliveries have nowhere to go.\n'
+        : `endpoints:\n${view.endpoints.map((e) => `  ${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n')}\n`);
+    }
+    return 0;
+  }
+
+  const [type, subjectId] = positional;
+  if (!type || !subjectId) {
+    io.err(`Usage: world-${emitter.vendor} emit --list [--root DIR] [--json]\n       world-${emitter.vendor} emit <event.type> <subject-id> [--root DIR] [--endpoint URL|ID] [--at ISO] [--json]\n`);
+    return 2;
+  }
+  try {
+    const endpointFlag = flags.get('--endpoint');
+    const at = flags.get('--at');
+    const report = await emitTwinEvent(emitter, { type, subjectId, ...(root !== undefined ? { root } : {}), ...(endpointFlag !== undefined ? { endpoint: endpointFlag } : {}), ...(at !== undefined ? { occurredAt: at } : {}) });
+    if (json) io.out(`${JSON.stringify(report, null, 2)}\n`);
+    else {
+      for (const d of report.deliveries) {
+        io.out(`${d.ok ? 'delivered' : 'FAILED'} ${report.type} (${String(d.event.id ?? '')}) → ${d.endpoint.url}${d.status !== undefined ? ` [${d.status}]` : ''}${d.error ? ` — ${d.error}` : ''}\n`);
+      }
+    }
+    return report.ok ? 0 : 1;
+  } catch (error) {
+    io.err(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}

package/src/fork.ts

@@ -20,8 +20,8 @@
 //
 // 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 { getActiveWorldStore } from './world-store.ts';
 import { listEgressLedger } from './egress.ts';
 import { appendAction, listActions, pendingActions, TwinActionPreconditionError } from './actions.ts';
 import type { TwinAction } from './actions.ts';
@@ -62,7 +62,7 @@ export function forkTwin(opts: {
   occurredAt: string;
 }): ForkMeta {
   const { service, toRoot, fromRoot } = opts;
-  if (existsSync(forkMetaPath(service, toRoot))) {
+  if (getActiveWorldStore().exists(forkMetaPath(service, toRoot))) {
     throw new Error(`fork target already initialized for ${service}: ${toRoot}`);
   }
   const baseEvents = listEvents(service, fromRoot);
@@ -78,18 +78,18 @@ export function forkTwin(opts: {
     baseLatestEventId: baseEvents.length ? baseEvents[baseEvents.length - 1]!.id : null,
     baseline,
   };
-  writeFileSync(forkMetaPath(service, toRoot), `${JSON.stringify(meta, null, 2)}\n`);
+  getActiveWorldStore().write(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}`);
+  if (!getActiveWorldStore().exists(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));
+  return getActiveWorldStore().exists(forkMetaPath(service, root));
 }
 
 export type FieldDivergence = { before: unknown; after: unknown };
@@ -189,7 +189,7 @@ export function auditForkNoRealWrites(service: string, forkRoot: string): ForkAu
 
 /** Remove a fork root entirely (the fork is throwaway by design). */
 export function discardFork(forkRoot: string): void {
-  rmSync(forkRoot, { recursive: true, force: true });
+  getActiveWorldStore().remove(forkRoot);
 }
 
 // ── Git-like fork operations (the twins architecture notes → "Fork Operations").
@@ -210,7 +210,12 @@ export function cherryPickActions(opts: { service: string; fromRoot: string; toR
   const copied: TwinAction[] = [];
   const conflicts: CopyResult['conflicts'] = [];
   for (const a of src) {
-    try { copied.push(appendAction({ ...a, occurredAt: opts.occurredAt }, opts.toRoot)); }
+    // The source root's shadowBasis names events in the SOURCE's log — stripped so the
+    // appender re-stamps against the target root's own mirror (R14). NB appendAction does
+    // not dedupe ids (pre-existing): a re-run cherry-pick appends duplicate rows, and the
+    // push gate binds to the FIRST copy's (older, safer) basis.
+    const { shadowBasis: _foreignBasis, ...rest } = a;
+    try { copied.push(appendAction({ ...rest, 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 };
@@ -248,6 +253,13 @@ export function resetFork(opts: { service: string; root: string; occurredAt: str
  * 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").
+ *
+ * R14 note: this is the FETCH step of "fetch + reconcile" — it does NOT refresh pending
+ * actions' shadowBasis (rows are append-only). A pending action whose subject the fresh
+ * events touched stays push-refused until it is reverted and re-authored over the new
+ * mirror (re-authoring stamps a fresh basis), or pushed with onDrift:'force' after a
+ * reviewed reconcile decided the twin's value wins. There is no rebase of the action
+ * itself — append-only history is the audit.
  */
 export function rebaseFork(opts: { service: string; root: string; freshEvents: WorldServiceEvent[] }): { applied: number; conflicts: Array<{ actionId: string; reason: string }> } {
   let applied = 0;