@volter/twin 0.1.0 → 0.1.1

package/src/world-clock.ts

@@ -0,0 +1,33 @@
+// THE WORLD CLOCK — the one piece of physics every twin consults (TWIN-PROGRAMMING-MODEL P3).
+// Time is a GLOBAL fact requiring simultaneous agreement: TTL/expiry logic reads it at serve
+// time, so no seed-side workaround exists. The clock is a FILE, not a service — every twin
+// reads it per request (a tiny local read; the serve-path determinism tooth bans network
+// egress, not filesystem reads), the world runtime owns writing it, and `volter-world clock`
+// is the operator door (set / advance / show). No file, or no env → real wall-clock time,
+// exactly the pre-clock behavior; a world only has scripted time when its operator says so.
+//
+// File format: a single ISO-8601 line (a FROZEN instant). Every read returns exactly that
+// instant — deterministic by construction. Advancing time is an explicit operator act, never
+// a background drift.
+// Read through the ACTIVE WorldStore, not node:fs: the clock file is world state, and a
+// hydrated serverless namespace must carry its frozen instant with it (runtime contract R11–R14
+// — a MemoryWorldStore world that read the clock off the host filesystem would silently
+// serve the HOST's time, the exact two-services-disagreeing-about-now defect below).
+import { getActiveWorldStore } from './world-store.ts';
+
+export const WORLD_CLOCK_ENV = 'TWIN_WORLD_CLOCK_FILE';
+
+/** The world's "now": the frozen instant in the clock file when one is configured and
+ *  parseable; real wall-clock time otherwise. */
+export function worldNow(): string {
+  const file = process.env[WORLD_CLOCK_ENV];
+  if (file && getActiveWorldStore().exists(file)) {
+    const raw = (getActiveWorldStore().read(file) ?? '').trim();
+    const parsed = Date.parse(raw);
+    if (!Number.isNaN(parsed)) return new Date(parsed).toISOString();
+    // A configured-but-corrupt clock is a WORLD defect — fail loudly, never silently drift
+    // back to wall-clock (two services disagreeing about now breaks the world).
+    throw new Error(`world clock: ${file} does not contain a parseable ISO-8601 instant (got ${JSON.stringify(raw.slice(0, 40))})`);
+  }
+  return new Date().toISOString();
+}

package/src/world-store.ts

@@ -0,0 +1,482 @@
+// WORLD STORE — the transport seam for the control-plane's persistence.
+//
+// The kernel's on-disk surface is a CLOSED SET of synchronous primitives: JSONL
+// append-logs (read-all-rows / append-row), whole-file JSON sidecars
+// (read/write/exists/remove), directory listing, and atomic-write + cross-process
+// file-lock. `WorldStore` names exactly that set, and nothing more. Route the whole
+// kernel through it and the twin persists through ANY backend — the local
+// filesystem today (`FsWorldStore`, the default), an in-memory Map for tests and
+// serverless proofs (`MemoryWorldStore`), a Durable Object / KV / redis tomorrow —
+// without touching a line of twin business logic.
+//
+// The interface is SYNCHRONOUS on purpose. The kernel's internals (append-then-
+// project, read-then-append critical sections) are synchronous, and `clerk-twin.ts`'s
+// request handler is a pure sync function keyed by `root`. Making the store async
+// would ripple `await` through every one of those call sites and change the handler's
+// shape — precisely the blast radius this seam exists to avoid. An async backend is
+// handled at a SEPARATE persistence boundary: `hydrate()` the durable source into a
+// sync store, run the sync kernel, `flush()` back out. See `hydrateInto`/`flushFrom`.
+//
+// NOT in scope, by deliberate carve-out: `rateBudget.ts`'s ledger. That is a
+// client-side guard on REAL vendor calls, keyed by CREDENTIAL and living in the user's
+// home dir (NOT under the project state root) — it is not twin persistence and never
+// runs on the serve path. Its bespoke inode-identity lock and reservation semantics
+// cannot be expressed through this generic seam without weakening them, so it stays on
+// `node:fs`. See its module header.
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname } from 'node:path';
+
+/** Metadata a caller needs about a stored path. `isDirectory` distinguishes a JSON
+ *  sidecar from a per-service subdir (validate/scrub walk on it); `size`+`mtimeMs`
+ *  drive the append-dedupe index's cache-validity check in storage.ts. */
+export type WorldStat = { size: number; mtimeMs: number; isDirectory: boolean };
+
+/**
+ * The synchronous persistence seam. Every path is an ABSOLUTE key the caller already
+ * computed (via `worldPaths`/`worldStateRoot`); the store treats it as an opaque key,
+ * so a single active store partitions cleanly by `root` (the root is embedded in the
+ * key) and no per-root wiring is needed.
+ */
+export interface WorldStore {
+  /** Whole-file read; `null` when the path does not exist. */
+  read(path: string): string | null;
+  /** File content split on `\n` (blank lines and the trailing empty included, so a
+   *  caller can report 1-based row numbers); `[]` when the path does not exist. */
+  readLines(path: string): string[];
+  /** Raw append of exactly `data` (the caller owns any trailing newline). On the fs
+   *  backend this is the VOLTER_DURABLE-aware durable append. Does NOT create parents —
+   *  call `mkdir` first, matching the historical `appendDurable` contract. */
+  append(path: string, data: string): void;
+  /** Non-atomic whole-file write, creating parent dirs. Matches the plain
+   *  `writeFileSync` sidecar writers (cursors, refs, leases, plans, fork-meta). */
+  write(path: string, data: string): void;
+  /** Atomic whole-file write (write-temp-then-rename on fs), creating parent dirs.
+   *  Used where a reader must never observe a half-written document (state.json). */
+  writeAtomic(path: string, data: string): void;
+  /** Does the path exist? */
+  exists(path: string): boolean;
+  /** Recursively remove the path (force; a missing path is not an error). */
+  remove(path: string): void;
+  /** Ensure a directory (and parents) exists. A no-op on backends with implicit dirs. */
+  mkdir(dirPath: string): void;
+  /** Immediate child names of a directory; `[]` when it does not exist. */
+  list(dirPath: string): string[];
+  /** Metadata for a path, or `null` when it does not exist. */
+  stat(path: string): WorldStat | null;
+  /** Run `fn` holding an exclusive lock on `lockPath`, releasing it afterwards. The fs
+   *  backend uses the historical cross-process reclaimable file lock; an in-memory,
+   *  single-instance backend is a synchronous pass-through. */
+  withLock<T>(lockPath: string, fn: () => T): T;
+}
+
+// ── FsWorldStore — the DEFAULT, byte-identical to the historical node:fs behavior ────
+
+/** How long a lock may live before an acquirer treats it as abandoned. Above the 10s
+ *  wait timeout so a live-but-slow holder is never reclaimed out from under itself. */
+const LOCK_STALE_MS = 60_000;
+
+type LockHolder = { pid: number; hostname: string; at: string };
+
+function readLockHolder(lockPath: string): LockHolder | null {
+  try {
+    return JSON.parse(readFileSync(lockPath, 'utf8')) as LockHolder;
+  } catch {
+    return null; // missing, empty (mid-write), or malformed
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // ESRCH → no such process (dead); EPERM → exists but not ours to signal (alive)
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/** A lock is stale when its holder is provably gone (same host + dead pid) or it has
+ *  outlived LOCK_STALE_MS. The age falls back to the lockfile's own mtime when the
+ *  `at` record is unreadable — so a writer that crashed between creating the lock and
+ *  recording itself is still eventually reclaimed, while a freshly-created (recent
+ *  mtime) empty lock is left alone, avoiding a race with the live writer. */
+function lockIsStale(lockPath: string): boolean {
+  const holder = readLockHolder(lockPath);
+  if (holder && holder.hostname === hostname() && Number.isInteger(holder.pid) && !pidAlive(holder.pid)) {
+    return true;
+  }
+  const recordedAt = holder && typeof holder.at === 'string' ? Date.parse(holder.at) : NaN;
+  let stamp = recordedAt;
+  if (!Number.isFinite(stamp)) {
+    try {
+      stamp = statSync(lockPath).mtimeMs;
+    } catch {
+      return false; // lock vanished — let the next openSync settle it
+    }
+  }
+  return Date.now() - stamp > LOCK_STALE_MS;
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * The default store: a thin, faithful pass-through to `node:fs`. Every method preserves
+ * the exact behavior the kernel had before the seam existed — the durable append
+ * (VOLTER_DURABLE), the atomic write (temp + rename), and the reclaimable cross-process
+ * file lock — so the existing twins and the conformance suite are unaffected.
+ */
+export class FsWorldStore implements WorldStore {
+  read(path: string): string | null {
+    if (!existsSync(path)) return null;
+    return readFileSync(path, 'utf8');
+  }
+
+  readLines(path: string): string[] {
+    if (!existsSync(path)) return [];
+    return readFileSync(path, 'utf8').split('\n');
+  }
+
+  append(path: string, data: string): void {
+    // Historical appendDurable: a completed append syscall survives a process crash;
+    // fsync additionally survives kernel-panic/power-loss when VOLTER_DURABLE=1.
+    const fd = openSync(path, 'a');
+    try {
+      appendFileSync(fd, data);
+      if (process.env.VOLTER_DURABLE === '1') fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+  }
+
+  write(path: string, data: string): void {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, data);
+  }
+
+  writeAtomic(path: string, data: string): void {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, data);
+    renameSync(tmp, path);
+  }
+
+  exists(path: string): boolean {
+    return existsSync(path);
+  }
+
+  remove(path: string): void {
+    rmSync(path, { recursive: true, force: true });
+  }
+
+  mkdir(dirPath: string): void {
+    mkdirSync(dirPath, { recursive: true });
+  }
+
+  list(dirPath: string): string[] {
+    if (!existsSync(dirPath)) return [];
+    return readdirSync(dirPath);
+  }
+
+  stat(path: string): WorldStat | null {
+    if (!existsSync(path)) return null;
+    const s = statSync(path);
+    return { size: s.size, mtimeMs: s.mtimeMs, isDirectory: s.isDirectory() };
+  }
+
+  /** Run `fn` holding an exclusive cross-process file lock. The lockfile records
+   *  `{pid, hostname, at}`; a contender that finds a stale lock (dead pid or age >
+   *  LOCK_STALE_MS) reclaims it by atomically renaming it aside — so a crashed holder
+   *  can't wedge the world forever. Reclaim is race-safe: only the process that wins
+   *  the rename clears the stale inode, and the exclusive `wx` create still decides the
+   *  winner. (Moved verbatim from storage.ts `withFileLock`.) */
+  withLock<T>(lockPath: string, fn: () => T): T {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const started = Date.now();
+    let fd: number | null = null;
+    while (fd === null) {
+      try {
+        fd = openSync(lockPath, 'wx');
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== 'EEXIST') throw error;
+        if (lockIsStale(lockPath)) {
+          const holder = readLockHolder(lockPath);
+          const salvage = `${lockPath}.stale.${process.pid}.${Date.now()}`;
+          try {
+            renameSync(lockPath, salvage);
+          } catch (renameError) {
+            if ((renameError as NodeJS.ErrnoException).code === 'ENOENT') continue; // another contender reclaimed it
+            throw renameError;
+          }
+          console.warn(
+            `[world] reclaiming stale storage lock ${lockPath} (held by pid ${holder?.pid ?? '?'} on ${holder?.hostname ?? '?'} since ${holder?.at ?? 'unknown'})`,
+          );
+          try {
+            unlinkSync(salvage);
+          } catch { /* the moved-aside stale inode; safe to leave if unlink fails */ }
+          continue; // retry the exclusive create immediately
+        }
+        if (Date.now() - started > 10_000) {
+          throw new Error(`Timed out waiting for world storage lock: ${lockPath}`);
+        }
+        sleepSync(25);
+      }
+    }
+
+    // Record the holder so a later contender can detect staleness. Best-effort: a write
+    // failure here doesn't weaken exclusivity, only staleness diagnostics.
+    try {
+      writeFileSync(fd, `${JSON.stringify({ pid: process.pid, hostname: hostname(), at: new Date().toISOString() } satisfies LockHolder)}\n`);
+    } catch { /* ignore */ }
+
+    try {
+      return fn();
+    } finally {
+      closeSync(fd);
+      try {
+        unlinkSync(lockPath);
+      } catch { /* already reclaimed by a stale-lock sweep */ }
+    }
+  }
+}
+
+// ── MemoryWorldStore — a Map-backed store; the proof a non-fs transport works ─────────
+
+// A process-global, strictly-increasing stamp source shared by every MemoryWorldStore, so
+// no two writes (across instances or requests) ever collide on `stat().mtimeMs`. See `bump`.
+let memoryStoreClock = 0;
+
+/**
+ * An in-memory store. Files are entries in a `Map<path, string>`; directories are
+ * synthesized from the key set (a path is a directory when it is a strict prefix of a
+ * file key). `withLock` is a synchronous pass-through — a single in-process instance has
+ * no concurrent writers to serialize, so the read-then-append critical sections the
+ * kernel guards are already atomic under the single-threaded event loop.
+ *
+ * This is the portability proof: point the active store here and the entire kernel — and
+ * the clerk twin on top of it — runs with the filesystem untouched.
+ */
+export class MemoryWorldStore implements WorldStore {
+  /** path → content, and path → version stamp driving `stat().mtimeMs`. */
+  private readonly files = new Map<string, string>();
+  private readonly versions = new Map<string, number>();
+  /** The stamp of this store's most recent mutation (0 = never mutated). A serverless
+   *  entry snapshots this before running the sync kernel and flushes ONLY when it moved —
+   *  read-only requests (the common case) then skip the durable write entirely. */
+  private lastMutation = 0;
+
+  mutationStamp(): number {
+    return this.lastMutation;
+  }
+
+  /** Paths whose content changed strictly after `stamp` — the DELTA-FLUSH primitive
+   *  (runtime contract R11b): a serverless entry records `mutationStamp()` at hydration,
+   *  runs the sync kernel, then persists ONLY these paths (plus removals, which the caller
+   *  detects by diffing its hydrated path set against `entries()` — a removed path has no
+   *  version to report). O(paths) scan, O(delta) write. */
+  changedSince(stamp: number): string[] {
+    const changed: string[] = [];
+    for (const [path, version] of this.versions) {
+      if (version > stamp && this.files.has(path)) changed.push(path);
+    }
+    return changed.sort();
+  }
+
+  private bump(path: string): void {
+    // Draw the stamp from a PROCESS-GLOBAL monotonic counter, not a per-instance one.
+    // storage.ts's append-dedupe cache is keyed by path and validated by (size, mtimeMs),
+    // and it persists across requests in a Worker isolate while a fresh MemoryWorldStore is
+    // created per request (the hydrate→sync-kernel→flush shape). A per-instance counter
+    // resets to 0 each request, so two instances could present the SAME (size, mtimeMs) for
+    // one path with DIFFERENT content — serving a stale index (dedupe bypass) or a false
+    // conflict. A global counter makes every write across every instance a distinct,
+    // strictly-increasing stamp, so a cross-instance collision is impossible.
+    this.lastMutation = memoryStoreClock += 1;
+    this.versions.set(path, this.lastMutation);
+  }
+
+  read(path: string): string | null {
+    return this.files.has(path) ? this.files.get(path)! : null;
+  }
+
+  readLines(path: string): string[] {
+    const content = this.files.get(path);
+    return content === undefined ? [] : content.split('\n');
+  }
+
+  append(path: string, data: string): void {
+    this.files.set(path, (this.files.get(path) ?? '') + data);
+    this.bump(path);
+  }
+
+  write(path: string, data: string): void {
+    this.files.set(path, data);
+    this.bump(path);
+  }
+
+  writeAtomic(path: string, data: string): void {
+    // Atomic by nature in a single process: the assignment is indivisible, so no reader
+    // ever observes a partial document.
+    this.files.set(path, data);
+    this.bump(path);
+  }
+
+  exists(path: string): boolean {
+    if (this.files.has(path)) return true;
+    // A directory "exists" when some file lives under it.
+    const prefix = path.endsWith('/') ? path : `${path}/`;
+    for (const key of this.files.keys()) if (key.startsWith(prefix)) return true;
+    return false;
+  }
+
+  remove(path: string): void {
+    let removedAny = false;
+    if (this.files.delete(path)) {
+      this.versions.delete(path);
+      removedAny = true;
+    }
+    const prefix = path.endsWith('/') ? path : `${path}/`;
+    for (const key of [...this.files.keys()]) {
+      if (key.startsWith(prefix)) {
+        this.files.delete(key);
+        this.versions.delete(key);
+        removedAny = true;
+      }
+    }
+    // A pure removal is a mutation too: without this, a request that only deletes state
+    // would read as clean and the delta-flush would never persist the removal (R11b).
+    if (removedAny) this.lastMutation = memoryStoreClock += 1;
+  }
+
+  mkdir(_dirPath: string): void {
+    // Directories are implicit in the key set; nothing to do.
+  }
+
+  list(dirPath: string): string[] {
+    const prefix = dirPath.endsWith('/') ? dirPath : `${dirPath}/`;
+    const children = new Set<string>();
+    for (const key of this.files.keys()) {
+      if (!key.startsWith(prefix)) continue;
+      const rest = key.slice(prefix.length);
+      const slash = rest.indexOf('/');
+      children.add(slash === -1 ? rest : rest.slice(0, slash));
+    }
+    return [...children];
+  }
+
+  stat(path: string): WorldStat | null {
+    const content = this.files.get(path);
+    if (content !== undefined) {
+      return { size: Buffer.byteLength(content, 'utf8'), mtimeMs: this.versions.get(path) ?? 0, isDirectory: false };
+    }
+    if (this.exists(path)) {
+      return { size: 0, mtimeMs: 0, isDirectory: true };
+    }
+    return null;
+  }
+
+  withLock<T>(_lockPath: string, fn: () => T): T {
+    return fn();
+  }
+
+  /** Test/inspection helper: a plain snapshot of every stored file. Not part of the
+   *  `WorldStore` contract — used by `flushFrom` and by tests asserting no fs was touched. */
+  entries(): Record<string, string> {
+    return Object.fromEntries(this.files);
+  }
+}
+
+// ── the active store (the injection point) ───────────────────────────────────────────
+
+let activeStore: WorldStore = new FsWorldStore();
+
+/** The store the kernel currently persists through. Defaults to `FsWorldStore`. */
+export function getActiveWorldStore(): WorldStore {
+  return activeStore;
+}
+
+/** Swap the active store. A serverless/DO/test entry sets a `MemoryWorldStore` (or a
+ *  backend-backed store) here before running the sync kernel, and restores the previous
+ *  one afterwards. Returns the store that was active, so callers can restore it. */
+export function setActiveWorldStore(store: WorldStore): WorldStore {
+  const previous = activeStore;
+  activeStore = store;
+  return previous;
+}
+
+/** Run `fn` with `store` active, restoring the previous store afterwards (even on
+ *  throw). ASYNC-AWARE: when `fn` returns a promise, the restore happens after it
+ *  SETTLES — the first version restored at `fn`'s return, i.e. at an async callback's
+ *  FIRST await, un-scoping the rest of the request (both serverless pack lanes hit this
+ *  independently and hand-rolled the same try/finally, 2026-09-01).
+ *
+ *  CONCURRENCY CAVEAT, stated not hidden: the active store is a module global. Holding it
+ *  across awaits is safe only when store-scoped work is SERIALIZED — one request at a time
+ *  per isolate — which is exactly what the namespace engine provides (twins-host
+ *  namespace-engine.ts, its interleave hammer is the pin). Two unserialized async scopes
+ *  interleaving would bleed stores with or without this helper; use the engine. */
+export function withWorldStore<T>(store: WorldStore, fn: () => Promise<T>): Promise<T>;
+export function withWorldStore<T>(store: WorldStore, fn: () => T): T;
+export function withWorldStore<T>(store: WorldStore, fn: () => T | Promise<T>): T | Promise<T> {
+  const previous = setActiveWorldStore(store);
+  let result: T | Promise<T>;
+  try {
+    result = fn();
+  } catch (error) {
+    setActiveWorldStore(previous);
+    throw error;
+  }
+  if (result instanceof Promise) {
+    return result.finally(() => setActiveWorldStore(previous));
+  }
+  setActiveWorldStore(previous);
+  return result;
+}
+
+// ── async persistence boundary ───────────────────────────────────────────────────────
+//
+// The kernel is synchronous; a durable backend (Durable Object storage, KV, redis, S3)
+// is asynchronous. These two helpers are the ONLY async in the persistence story: a
+// serverless entry `await hydrate()`s the durable snapshot into a sync store, runs the
+// sync kernel (which never awaits), then `await flush()`es the mutated snapshot back.
+// The shapes are proven against `MemoryWorldStore` (see world-store.test.ts); a real DO
+// adapter implements `HydrationSource`/`HydrationSink` over its own async storage.
+
+/** A durable, async source of a world snapshot (path → content). */
+export interface HydrationSource {
+  load(): Promise<Record<string, string>>;
+}
+
+/** A durable, async sink for a world snapshot (path → content). */
+export interface HydrationSink {
+  save(snapshot: Record<string, string>): Promise<void>;
+}
+
+/** Fill `store` from an async durable `source` before the sync kernel runs. */
+export async function hydrateInto(store: MemoryWorldStore, source: HydrationSource): Promise<void> {
+  const snapshot = await source.load();
+  for (const [path, content] of Object.entries(snapshot)) store.write(path, content);
+}
+
+/** Persist `store`'s current contents back to an async durable `sink` after the sync
+ *  kernel has run. */
+export async function flushFrom(store: MemoryWorldStore, sink: HydrationSink): Promise<void> {
+  await sink.save(store.entries());
+}

package/src/worldConfig.ts

@@ -4,9 +4,9 @@
 // define. (The tracker's annotation adapter defines + reads `annotationPolicy` and
 // `browseUrlTemplate` on top of this — those are verification concerns, not the
 // twin's, so they are NOT typed here.)
-import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { worldStateRoot } from './storage.ts';
+import { getActiveWorldStore } from './world-store.ts';
 
 export type WorldServiceConfig = {
   provider?: string;
@@ -20,7 +20,8 @@ export type WorldConfig = {
 
 export function loadWorldConfig(root?: string): WorldConfig {
   const path = join(worldStateRoot(root), 'config.json');
-  if (!existsSync(path)) return { services: {} };
-  const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<WorldConfig>;
+  const raw = getActiveWorldStore().read(path);
+  if (raw === null) return { services: {} };
+  const parsed = JSON.parse(raw) as Partial<WorldConfig>;
   return { ...parsed, services: parsed.services ?? {} };
 }

package/dist/src/actions.d.ts

@@ -1,138 +0,0 @@
-import type { SubjectFields } from './shadow.js';
-import type { TwinResource } from './serve.js';
-export type TwinActionOp = 'set' | 'revert' | 'confirm';
-export type TwinActionPreconditionOp = 'exists' | 'not_exists' | 'eq' | 'neq' | 'version_eq';
-export type TwinActionPrecondition = {
-    subject: {
-        type: string;
-        id: string;
-    };
-    field: string;
-    op: TwinActionPreconditionOp;
-    value?: unknown;
-};
-export type TwinActionRevertSpec = {
-    strategy: 'inverse' | 'suppress' | 'compensating-action';
-    operation?: string;
-    fields?: SubjectFields;
-};
-export type ProjectedResource = {
-    type: string;
-    id: string;
-    fields: SubjectFields;
-};
-export type ProjectedResourcePatch = {
-    type: string;
-    id: string;
-    fields: SubjectFields;
-};
-export type ProjectedResourceRef = {
-    type: string;
-    id: string;
-};
-export type ProjectedDelivery = {
-    kind: 'webhook' | 'event' | 'notification';
-    target: string;
-    payload: Record<string, unknown>;
-};
-export type ActionProjection = {
-    creates?: ProjectedResource[];
-    updates?: ProjectedResourcePatch[];
-    deletes?: ProjectedResourceRef[];
-    emits?: ProjectedDelivery[];
-};
-export type TwinAction = {
-    id: string;
-    service: string;
-    op: TwinActionOp;
-    subject: {
-        type: string;
-        id: string;
-    };
-    occurredAt: string;
-    actor?: {
-        kind: 'agent' | 'human' | 'bot' | 'system';
-        id?: string;
-    };
-    /** Optional vendor operation name, e.g. `issue.update` or `message.send`. */
-    operation?: string;
-    /** Raw operation input (provenance); not projected — `fields`/`projection` carry the state change. */
-    input?: Record<string, unknown>;
-    /** Preconditions are evaluated against the current projected twin state before append. */
-    preconditions?: TwinActionPrecondition[];
-    fields?: SubjectFields;
-    projection?: ActionProjection;
-    revertsActionId?: string;
-    confirmsActionId?: string;
-    observedEventId?: string;
-    /** Optional machine-readable hint for how a UI/pack should construct a revert. */
-    revert?: TwinActionRevertSpec;
-    /**
-     * Request-scoped correlation id (D3 — the purpose-3 audit trail: "who reviewed the
-     * change that caused this real write"). Always present on an appended action —
-     * appendAction/appendActionIfAbsent generate one when the caller doesn't supply it —
-     * and threaded through to the push-ledger row(s) a push against this action produces
-     * (see pushLedger.ts), so an action row and its push-ledger row(s) join on this id
-     * alone, with no dependence on actionId/pushId naming conventions.
-     */
-    correlationId?: string;
-};
-export type TwinTransactionCommit = TwinAction;
-export type TwinTransactionCommitOp = TwinActionOp;
-export type TwinTransactionPrecondition = TwinActionPrecondition;
-export type TwinTransactionRevertSpec = TwinActionRevertSpec;
-export declare class TwinActionPreconditionError extends Error {
-    readonly actionId: string;
-    readonly failed: TwinActionPrecondition;
-    constructor(actionId: string, failed: TwinActionPrecondition);
-}
-export declare function appendAction(action: TwinAction, root?: string): TwinAction;
-/** Append `action` only if no action with the same id already exists — the whole
- *  check-then-append runs under the actions lock, so it's atomic across processes (two
- *  concurrent identical writes converge to ONE action; distinct writes both land). */
-export declare function appendActionIfAbsent(action: TwinAction, root?: string): {
-    action: TwinAction;
-    appended: boolean;
-};
-export declare function appendTransactionCommit(commit: TwinTransactionCommit, root?: string): TwinTransactionCommit;
-export declare function listActions(service: string, root?: string): TwinAction[];
-/**
- * Project the action log over the observed mirror → current twin resources.
- * `set` actions overlay fields (creating subjects that don't exist in the mirror);
- * reverted and confirmed actions are skipped (confirmed facts come from the
- * observed log instead, so they are not projected twice).
- */
-export declare function projectResources(service: string, root?: string): TwinResource[];
-/**
- * Confirm a local action after it was pushed to the real vendor (R18): record the
- * confirmed fields as an OBSERVED event (origin 'external' — it's now real) and
- * append a `confirm` action mapping the local action → that observed event id.
- * Projection then drops the local action (the fact lives in the observed log), so
- * the change is counted exactly once. Returns the observed event id.
- */
-export declare function confirmAction(opts: {
-    service: string;
-    actionId: string;
-    subject: {
-        type: string;
-        id: string;
-    };
-    fields: SubjectFields;
-    occurredAt: string;
-    root?: string;
-}): {
-    observedEventId: string;
-};
-/** Local pending actions (set, not reverted, not yet confirmed) — the divergence from the mirror. */
-export declare function pendingActions(service: string, root?: string): TwinAction[];
-/**
- * Deliveries (webhooks/events/notifications) the active transactions want fired —
- * the `projection.emits` of pending `set` actions, in order. A twin's event layer
- * reads these to know what to deliver; projecting state ignores emits (side effects).
- */
-export declare function pendingEmits(service: string, root?: string): Array<{
-    actionId: string;
-    delivery: ProjectedDelivery;
-}>;
-export declare const listTransactionCommits: typeof listActions;
-export declare const pendingTransactionCommits: typeof pendingActions;