@volter/twin 0.1.0

package/dist/src/storage.js

@@ -0,0 +1,535 @@
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { GenericWorldStateSchema, WorldServiceEventSchema, } from "./schemas.js";
+function nowIso() {
+    return new Date().toISOString();
+}
+function projectRoot(root) {
+    return resolve(root || process.env.PROJECT_ROOT || process.cwd());
+}
+/**
+ * Name of the per-project state directory holding world data
+ * (`<root>/<stateDir>/world/...`). Defaults to `.volter`; hosts that need a
+ * different directory set VOLTER_STATE_DIR. Every path in this package must
+ * go through worldStateRoot — never the literal.
+ */
+export function stateDirName() {
+    return process.env.VOLTER_STATE_DIR || '.volter';
+}
+export function worldStateRoot(root) {
+    return join(projectRoot(root), stateDirName(), 'world');
+}
+function assertServiceName(service) {
+    if (!/^[A-Za-z0-9_-]+$/.test(service)) {
+        throw new Error(`Invalid world service name: ${service}`);
+    }
+    return service;
+}
+export function worldPaths(service, root) {
+    const safeService = assertServiceName(service);
+    const resolvedRoot = projectRoot(root);
+    const dir = join(worldStateRoot(root), safeService);
+    return {
+        root: resolvedRoot,
+        service: safeService,
+        dir,
+        events: join(dir, 'events.jsonl'),
+        state: join(dir, 'state.json'),
+        resources: join(dir, 'resources'),
+        cursors: join(dir, 'cursors'),
+        ingests: join(dir, 'ingests'),
+        eventQueue: join(dir, 'event-queue.jsonl'),
+    };
+}
+function readJsonl(path) {
+    if (!existsSync(path))
+        return [];
+    const rows = [];
+    for (const [index, line] of readFileSync(path, 'utf8').split('\n').entries()) {
+        if (!line.trim())
+            continue;
+        try {
+            rows.push(JSON.parse(line));
+        }
+        catch (error) {
+            throw new Error(`${path}:${index + 1}: invalid JSONL row: ${error.message}`);
+        }
+    }
+    return rows;
+}
+/** Read + parse a whole-file JSON sidecar, citing the path on a parse failure (mirrors
+ *  readJsonl's `${path}:...` error shape). Callers own existence semantics — this parses a
+ *  file that is expected to exist; guard with existsSync first when absence is allowed. */
+export function readJsonFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${path}: invalid JSON: ${error.message}`);
+    }
+}
+/**
+ * Append `data` to `path`. When VOLTER_DURABLE=1, `fsyncSync` the file after the write so
+ * the appended record survives an OS crash / power loss — not just a process crash.
+ *
+ * Default (VOLTER_DURABLE unset) is OFF: `appendFileSync` is a completed write syscall, so a
+ * *process* crash after it returns still leaves the record on the log (the OS owns the page
+ * cache). The window this leaves open is a **kernel-panic / power loss** between the write
+ * landing in the page cache and the fs flushing it to stable storage — a torn or lost tail
+ * record. That crash window matters more once real pulled staging data lives in these files
+ * (purpose 2), so hosts that need durability opt in with VOLTER_DURABLE=1 at the cost of an
+ * fsync per append. See ARCHITECTURE.md D1.
+ */
+export function appendDurable(path, data) {
+    const fd = openSync(path, 'a');
+    try {
+        appendFileSync(fd, data);
+        if (process.env.VOLTER_DURABLE === '1')
+            fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Opt-in structured stderr logging for the audit trail (ARCHITECTURE-REVIEW-TODOS D3):
+ * one line per action-log append and per push-ledger row, so "who reviewed the change
+ * that caused this real write" is mechanically greppable from a single log stream via
+ * `correlationId`. Off by default — mirrors the VOLTER_DURABLE opt-in policy above: no
+ * always-on I/O, never on the default path. Set VOLTER_TWIN_LOG=1 to enable.
+ */
+export function twinLog(kind, details) {
+    if (process.env.VOLTER_TWIN_LOG !== '1')
+        return;
+    console.error(`[twin:${kind}]`, JSON.stringify(details));
+}
+function appendJsonl(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    appendDurable(path, `${JSON.stringify(value)}\n`);
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** 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;
+function readLockHolder(lockPath) {
+    try {
+        return JSON.parse(readFileSync(lockPath, 'utf8'));
+    }
+    catch {
+        return null; // missing, empty (mid-write), or malformed
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH → no such process (dead); EPERM → exists but not ours to signal (alive)
+        return error.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) {
+    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;
+}
+/** Run `fn` holding an exclusive cross-process file lock (the same primitive the event log
+ *  uses). Used to make read-then-append critical sections atomic across processes. 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. */
+export function withFileLock(lockPath, fn) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const started = Date.now();
+    let fd = null;
+    while (fd === null) {
+        try {
+            fd = openSync(lockPath, 'wx');
+        }
+        catch (error) {
+            const code = error.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.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() })}\n`);
+    }
+    catch { /* ignore */ }
+    try {
+        return fn();
+    }
+    finally {
+        closeSync(fd);
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* already reclaimed by a stale-lock sweep */ }
+    }
+}
+function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    renameSync(tmp, path);
+}
+export function listEvents(service, root) {
+    const paths = worldPaths(service, root);
+    return readJsonl(paths.events).map((row) => WorldServiceEventSchema.parse(row));
+}
+const eventsIndexCache = new Map();
+function eventsFileStamp(eventsPath) {
+    if (!existsSync(eventsPath))
+        return { size: 0, mtimeMs: 0 };
+    const stat = statSync(eventsPath);
+    return { size: stat.size, mtimeMs: stat.mtimeMs };
+}
+function eventsIndexFor(eventsPath) {
+    const { size, mtimeMs } = eventsFileStamp(eventsPath);
+    const cached = eventsIndexCache.get(eventsPath);
+    if (cached && cached.size === size && cached.mtimeMs === mtimeMs)
+        return cached;
+    const index = { size, mtimeMs, ids: new Set(), keys: new Set() };
+    for (const row of readJsonl(eventsPath)) {
+        if (typeof row.id === 'string')
+            index.ids.add(row.id);
+        if (typeof row.idempotencyKey === 'string')
+            index.keys.add(row.idempotencyKey);
+    }
+    eventsIndexCache.set(eventsPath, index);
+    return index;
+}
+/** Targeted fetch of one event row by id or idempotencyKey (rare duplicate path). */
+function findEventRow(eventsPath, id, idempotencyKey) {
+    for (const row of readJsonl(eventsPath)) {
+        if (row.id === id || row.idempotencyKey === idempotencyKey) {
+            return WorldServiceEventSchema.parse(row);
+        }
+    }
+    return null;
+}
+function ensureEventDirs(paths) {
+    mkdirSync(paths.dir, { recursive: true });
+    mkdirSync(paths.resources, { recursive: true });
+    mkdirSync(paths.cursors, { recursive: true });
+    mkdirSync(paths.ingests, { recursive: true });
+}
+/** Exported so other modules that share a service's events log (e.g. egress.ts,
+ *  TWIN-58) can serialize their own critical sections on the SAME lock appendEvent
+ *  itself uses, instead of inventing a second, uncoordinated lockfile. */
+export function eventsLockPath(paths) {
+    return join(paths.dir, 'events.jsonl.lock');
+}
+/**
+ * The append body, assuming the caller already holds `eventsLockPath(paths)`. Split
+ * out so `commitQueuedEvents` can run a whole batch of appends (and the rebuild that
+ * follows them) under ONE lock acquisition instead of nesting a fresh `withFileLock`
+ * per row — `withFileLock` is not reentrant, so re-acquiring it from inside an
+ * already-held lock in the same process would just spin to its own timeout. Also
+ * exported for egress.ts (TWIN-58): performExternalWrite's ledger-check +
+ * intent-append span holds `eventsLockPath` itself, so it must append through this
+ * already-locked path rather than the public `appendEvent` (which would try to
+ * re-acquire the same lock and spin to its own timeout).
+ */
+export function appendEventLocked(parsed, paths) {
+    const index = eventsIndexFor(paths.events);
+    if (index.ids.has(parsed.id) || index.keys.has(parsed.idempotencyKey)) {
+        const duplicate = findEventRow(paths.events, parsed.id, parsed.idempotencyKey);
+        if (!duplicate)
+            throw new Error(`World events index out of sync for ${paths.events}; delete nothing — rerun to rebuild`);
+        // observedAt (delivery time), occurredAt (poll-based connectors use
+        // poll-cycle time, not the resource's own timestamp), and external.url
+        // (a convenience pointer — provider URLs embed mutable title slugs,
+        // e.g. Linear) are metadata, not event identity: re-observations
+        // differing only there are duplicates, not conflicts.
+        // external.provider/id ARE identity.
+        const stripMetadata = (event) => {
+            const { observedAt: _observedAt, occurredAt: _occurredAt, external, ...content } = event;
+            if (!external)
+                return content;
+            const { url: _url, ...externalIdentity } = external;
+            return { ...content, external: externalIdentity };
+        };
+        if (JSON.stringify(stripMetadata(duplicate)) !== JSON.stringify(stripMetadata(parsed))) {
+            throw new Error(`Conflicting duplicate ${parsed.service} event: ${parsed.id} / ${parsed.idempotencyKey} conflicts with ${duplicate.id}`);
+        }
+        return { event: duplicate, appended: false, duplicateOf: duplicate.id };
+    }
+    appendJsonl(paths.events, parsed);
+    const stamp = eventsFileStamp(paths.events);
+    index.ids.add(parsed.id);
+    index.keys.add(parsed.idempotencyKey);
+    index.size = stamp.size;
+    index.mtimeMs = stamp.mtimeMs;
+    return { event: parsed, appended: true };
+}
+export function appendEvent(event, root) {
+    const parsed = WorldServiceEventSchema.parse(event);
+    const paths = worldPaths(parsed.service, root);
+    ensureEventDirs(paths);
+    return withFileLock(eventsLockPath(paths), () => appendEventLocked(parsed, paths));
+}
+function queuedEventId(event) {
+    return `queue:${event.service}:${event.idempotencyKey}`;
+}
+export function listQueuedEvents(service, root) {
+    const paths = worldPaths(service, root);
+    return readJsonl(paths.eventQueue);
+}
+export function enqueueEvent(event, options = {}) {
+    const parsed = WorldServiceEventSchema.parse(event);
+    const paths = worldPaths(parsed.service, options.root);
+    mkdirSync(paths.dir, { recursive: true });
+    mkdirSync(paths.ingests, { recursive: true });
+    const queued = {
+        id: options.id ?? queuedEventId(parsed),
+        service: parsed.service,
+        receivedAt: options.receivedAt ?? nowIso(),
+        source: options.source ?? 'listener',
+        event: parsed,
+    };
+    return withFileLock(join(paths.dir, 'event-queue.jsonl.lock'), () => {
+        const existing = readJsonl(paths.eventQueue);
+        const duplicate = existing.find((candidate) => candidate.id === queued.id || candidate.event.idempotencyKey === queued.event.idempotencyKey);
+        if (duplicate)
+            return { queued: duplicate, appended: false, duplicateOf: duplicate.id };
+        appendJsonl(paths.eventQueue, queued);
+        return { queued, appended: true };
+    });
+}
+/**
+ * Commit queued (webhook/listener) events into the canonical log, then rebuild the
+ * generic projection — spanning BOTH under the SAME events-lock acquisition (D7).
+ * Appending each event and rebuilding state.json are two separate durable writes;
+ * without a shared lock, a concurrent commit/append on another process could
+ * interleave between "this commit's last append" and "this commit's rebuild",
+ * so the rebuilt state.json would not correspond to exactly this commit's view of
+ * the log. Holding one lock across the whole sequence rules that out: no other
+ * appendEvent/commitQueuedEvents call for this service can run until both the
+ * appends AND the rebuild here have completed. (A single-process crash between the
+ * last durable append and the rebuild can still leave state.json one rebuild behind
+ * — that window is inherent to a two-file update with no WAL, and is unaffected by
+ * locking; it is closed by the next successful commit/rebuild, which always starts
+ * from the durably-appended log, so no event is ever lost, only state.json's
+ * projection is briefly stale.)
+ */
+export function commitQueuedEvents(service, options = {}) {
+    const paths = worldPaths(service, options.root);
+    ensureEventDirs(paths);
+    const queued = listQueuedEvents(service, options.root).sort((a, b) => a.event.occurredAt.localeCompare(b.event.occurredAt) || a.receivedAt.localeCompare(b.receivedAt) || a.id.localeCompare(b.id));
+    const limit = options.limit ?? queued.length;
+    return withFileLock(eventsLockPath(paths), () => {
+        let committed = 0;
+        let skipped = 0;
+        const eventIds = [];
+        for (const row of queued.slice(0, limit)) {
+            const parsed = WorldServiceEventSchema.parse(row.event);
+            const result = appendEventLocked(parsed, paths);
+            if (result.appended) {
+                committed += 1;
+                eventIds.push(result.event.id);
+            }
+            else {
+                skipped += 1;
+            }
+        }
+        if (committed > 0)
+            rebuildGenericState(service, options.root);
+        return { service, queued: Math.min(queued.length, limit), committed, skipped, eventIds };
+    });
+}
+// NOTE: annotation read/write (listAnnotations/addAnnotation/createAnnotation) moved
+// to @volter/tracker/world-annotations — annotations are a tracker concern.
+export function genericWorldReducer(state, event) {
+    const key = `${event.subject.type}:${event.subject.id}`;
+    return GenericWorldStateSchema.parse({
+        ...state,
+        eventCount: state.eventCount + 1,
+        latestEventId: event.id,
+        subjects: {
+            ...state.subjects,
+            [key]: {
+                type: event.subject.type,
+                id: event.subject.id,
+                latestEventId: event.id,
+                latestType: event.type,
+                updatedAt: event.occurredAt || event.observedAt,
+            },
+        },
+    });
+}
+export function emptyGenericState(service) {
+    return {
+        version: 1,
+        service: assertServiceName(service),
+        rebuiltAt: nowIso(),
+        eventCount: 0,
+        subjects: {},
+    };
+}
+export function rebuildState(service, initialState, reducer, root) {
+    const paths = worldPaths(service, root);
+    const state = listEvents(service, root).reduce(reducer, initialState);
+    writeJsonAtomic(paths.state, state);
+    return state;
+}
+export function rebuildGenericState(service, root) {
+    return rebuildState(service, emptyGenericState(service), genericWorldReducer, root);
+}
+export function loadState(service, root) {
+    const paths = worldPaths(service, root);
+    if (!existsSync(paths.state))
+        return null;
+    return readJsonFile(paths.state);
+}
+export function createEvent(input) {
+    return WorldServiceEventSchema.parse({
+        schemaVersion: 1,
+        observedAt: nowIso(),
+        ...input,
+    });
+}
+/** Filenames/dirnames ANY control-plane src module ever writes inside a single
+ *  service's state dir (see worldPaths) — plus the lockfiles withFileLock creates
+ *  next to a log and the `.tmp`/`.stale.*` sidecars its atomic-write/reclaim paths
+ *  use. storage.ts itself only accounts for events.jsonl/event-queue.jsonl/
+ *  state.json/resources/cursors/ingests; the rest are written by other modules
+ *  that share the same service dir (actions.ts, pushLedger.ts, plan.ts, lease.ts,
+ *  refs.ts, fork.ts, queueLifecycle.ts) — this set MUST stay in sync with every
+ *  one of them so scrubService never demands --force for an ordinary twin. */
+const KNOWN_SERVICE_ENTRIES = new Set([
+    'events.jsonl',
+    'events.jsonl.lock',
+    'event-queue.jsonl',
+    'event-queue.jsonl.lock',
+    'state.json',
+    'resources',
+    'cursors',
+    'ingests',
+    // actions.ts: the local transaction-commit log + its lock.
+    'actions.jsonl',
+    'actions.jsonl.lock',
+    // pushLedger.ts: the push-phase ledger for real-vendor replication.
+    'push-ledger.jsonl',
+    // queueLifecycle.ts: the append-only status ledger over event-queue.jsonl rows.
+    'event-queue-status.jsonl',
+    // fork.ts: fork metadata (base snapshot + divergence baseline) for a fork root.
+    'fork-meta.json',
+    // plan.ts: one JSON file per apply plan, under plans/<planId>.json.
+    'plans',
+    // lease.ts: one JSON file per apply lease, under leases/<leaseId>.json.
+    'leases',
+    // refs.ts: remote/local checkpoint refs, under refs/remote/<provider>/<name>.json
+    // and refs/local/<forkId>.json.
+    'refs',
+]);
+function isKnownServiceEntry(name) {
+    return KNOWN_SERVICE_ENTRIES.has(name) || name.endsWith('.tmp') || /\.stale\.\d+\.\d+$/.test(name);
+}
+/** A service dir "looks like" one of ours when every entry in it is something
+ *  storage.ts is known to create. A directory that doesn't exist yet trivially
+ *  looks fine (scrub will just no-op on it). */
+function looksLikeServiceStateDir(dir) {
+    if (!existsSync(dir))
+        return true;
+    return readdirSync(dir).every((entry) => isKnownServiceEntry(entry));
+}
+/** The whole world dir "looks like" ours when every entry in it is itself a
+ *  directory that looks like a service state dir (each service gets one subdir
+ *  under worldStateRoot — see worldPaths). */
+function looksLikeWorldStateDir(dir) {
+    if (!existsSync(dir))
+        return true;
+    return readdirSync(dir).every((entry) => {
+        const full = join(dir, entry);
+        return statSync(full).isDirectory() && looksLikeServiceStateDir(full);
+    });
+}
+/** Every file under `dir`, path relative to `dir`, depth-first. Used to report
+ *  exactly what scrub is about to remove before it removes it. */
+function listFilesRecursive(dir, base = dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listFilesRecursive(full, base));
+        else
+            out.push(full.slice(base.length + 1));
+    }
+    return out;
+}
+function scrubDir(dir, label, looksLike, options) {
+    if (!existsSync(dir)) {
+        return { target: dir, removed: [], message: `nothing to scrub: ${label} (${dir}) does not exist` };
+    }
+    if (!options.force && !looksLike(dir)) {
+        throw new Error(`world scrub: refusing to remove "${dir}" — it does not look like a world state directory ` +
+            `(unexpected contents). Pass --force (or { force: true }) to scrub it anyway.`);
+    }
+    const removed = listFilesRecursive(dir);
+    rmSync(dir, { recursive: true, force: true });
+    return { target: dir, removed, message: `scrubbed ${label}: removed ${removed.length} file(s) under ${dir}` };
+}
+/** Delete one service's pulled data at rest: its event log, queued events,
+ *  rebuilt state.json, and any resources/cursors/ingests sidecars — everything
+ *  `worldPaths(service)` points at. Refuses (unless `force`) when the dir holds
+ *  anything storage.ts didn't put there. */
+export function scrubService(service, options = {}) {
+    const paths = worldPaths(service, options.root);
+    return scrubDir(paths.dir, `service "${service}"`, looksLikeServiceStateDir, options);
+}
+/** Delete the ENTIRE world state dir (`<root>/<stateDir>/world`) — every
+ *  service's pulled data at once. Refuses (unless `force`) when any entry in it
+ *  isn't itself a recognizable per-service state dir. */
+export function scrubWorld(options = {}) {
+    const dir = worldStateRoot(options.root);
+    return scrubDir(dir, 'entire world state dir', looksLikeWorldStateDir, options);
+}

package/dist/src/sync.d.ts

@@ -0,0 +1,91 @@
+import type { EgressWriteResult } from './egress.js';
+import type { WorldRemoteRef } from './refs.js';
+import type { SubjectFields } from './shadow.js';
+import type { TwinResource } from './serve.js';
+import type { ReconcilePlan } from './reconcile.js';
+export type SyncResource = {
+    type: string;
+    id: string;
+    fields: SubjectFields;
+};
+export type PullResult = {
+    observed: number;
+    deltasAppended: number;
+    unchanged: number;
+};
+/**
+ * Pull: fold a set of externally-observed resources into the twin's event log.
+ * The caller has already fetched them from the real vendor (injected I/O); this
+ * is the pure fold. Only changed fields produce a delta (recordObservedDelta is
+ * a no-op when nothing differs), so re-pulling identical state appends nothing.
+ *
+ * `redact` (TWIN-45 dev/01 — implemented, not just documented) is an optional
+ * transform applied to each resource BEFORE it is folded into the event log, so
+ * a sensitive field never lands on disk in the first place — a redact-on-pull
+ * hook point, not a redaction policy: this library makes zero default redaction
+ * decisions (no built-in "PII field" list, no defaults). The caller supplies the
+ * hook deliberately, shaped for their own vendor/fields. See docs/DATA_AT_REST.md
+ * for the full data-at-rest story (what's implemented here vs. left as
+ * guidance) and for why day-count retention defaults are NOT hardcoded here —
+ * that is a policy call for the human owner, not this library.
+ */
+export declare function syncPull(opts: {
+    service: string;
+    resources: SyncResource[];
+    occurredAt: string;
+    root?: string;
+    actor?: {
+        kind: 'agent' | 'human' | 'bot' | 'system';
+        id?: string;
+    };
+    redact?: (resource: SyncResource) => SyncResource;
+}): PullResult;
+export type PushItemResult = {
+    id: string;
+    type: string;
+    status: EgressWriteResult['status'];
+    externalId?: string;
+};
+export type PushResult = {
+    attempted: number;
+    pushed: PushItemResult[];
+};
+/**
+ * Push: enact a reconcile plan's twin→real changes by calling the injected real
+ * write fn, idempotently via the egress ledger. `write` is the ONLY place a real
+ * vendor API is touched; in tests/offline it's a fake. Re-pushing the same plan
+ * replays (no double-apply) because the egress idempotency key encodes the change.
+ *
+ * Gated the same way `applyPlan` is (TWIN-53 R-K2): `approve` and the lease fields
+ * (`remoteRef`/`holder`/`leaseId`/`acquiredAt`/`expiresAt`) are mandatory options —
+ * there is no implicit-approval, no-lease path. Approval is required when
+ * `reconcileRequiresApproval(plan)` is true (unresolved conflicts, or a
+ * twin-wins push that overwrites a real-side change) and `approve` is not set;
+ * refusal happens before the lease is acquired or `write` is ever called — zero
+ * side effects. The lease is acquired for `remoteRef` before any push and released
+ * (even on error) after.
+ */
+export declare function syncPush(opts: {
+    service: string;
+    plan: ReconcilePlan;
+    write: (item: SyncResource) => Promise<{
+        externalId: string;
+        data?: Record<string, unknown>;
+    }>;
+    remoteRef: WorldRemoteRef;
+    holder: {
+        kind: 'agent' | 'human' | 'system';
+        id: string;
+    };
+    leaseId: string;
+    acquiredAt: string;
+    expiresAt: string;
+    approve: boolean;
+    root?: string;
+    actor?: {
+        kind: 'agent' | 'human' | 'bot' | 'system';
+        id?: string;
+    };
+}): Promise<PushResult>;
+/** Convenience: the twin's current resources as the reconcile `fork`/state input. */
+export declare function currentResources(service: string, root?: string): TwinResource[];