@volter/twin 0.1.0

package/dist/src/plan.js

@@ -0,0 +1,151 @@
+// Apply plan (the twins architecture notes → "Plan"). The Terraform-plan /
+// pull-request object for non-code systems: a reviewable, replayable proposal of
+// exactly what a push/apply will do — which local transactions, the provider
+// calls + idempotency keys, destructive flags, expected confirmations, conflicts
+// (failed preconditions), and whether approval is required. No real push happens
+// from an implicit action list; it executes a plan. `applyPlan` is the gated
+// orchestrator: recompute requiresApproval from the plan's own data (never trust
+// the stored bit) → refuse a stale base → acquire lease → push each call through
+// phases → release.
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pendingActions, projectResources } from "./actions.js";
+import { isBaseStale } from "./refs.js";
+import { acquireLease, releaseLease } from "./lease.js";
+import { pushTransaction } from "./pushLedger.js";
+import { readJsonFile, worldPaths } from "./storage.js";
+function resourcesById(service, root) {
+    return new Map(projectResources(service, root).map((r) => [`${r.type}:${r.id}`, r]));
+}
+function preconditionFailure(action, byId) {
+    for (const p of action.preconditions ?? []) {
+        const resource = byId.get(`${p.subject.type}:${p.subject.id}`);
+        const actual = resource ? resource[p.field] : undefined;
+        const ok = evalPrecondition(p, actual);
+        if (!ok)
+            return `${p.subject.type}:${p.subject.id}.${p.field} ${p.op}${p.value !== undefined ? ` ${JSON.stringify(p.value)}` : ''}`;
+    }
+    return null;
+}
+function evalPrecondition(p, actual) {
+    switch (p.op) {
+        case 'exists': return actual !== undefined;
+        case 'not_exists': return actual === undefined;
+        case 'eq':
+        case 'version_eq': return Object.is(actual, p.value);
+        case 'neq': return !Object.is(actual, p.value);
+        default: return false;
+    }
+}
+/** Pending transactions whose preconditions would fail against current projected state. */
+export function pendingConflicts(service, root) {
+    const byId = resourcesById(service, root);
+    const out = [];
+    for (const action of pendingActions(service, root)) {
+        const failure = preconditionFailure(action, byId);
+        if (failure)
+            out.push({ actionId: action.id, reason: `precondition would fail: ${failure}` });
+    }
+    return out;
+}
+/**
+ * Build a reviewable apply plan from a fork's pending transactions. `mapper` is the
+ * vendor-specific action→provider-call mapping; actions it returns null for are
+ * omitted. Conflicts are pending actions whose preconditions fail against current
+ * projected state. Approval is required if any call is destructive or any conflict exists.
+ */
+export function buildApplyPlan(opts) {
+    const pending = pendingActions(opts.service, opts.root);
+    const byId = resourcesById(opts.service, opts.root);
+    const providerCalls = [];
+    const conflicts = [];
+    for (const action of pending) {
+        const failure = preconditionFailure(action, byId);
+        if (failure) {
+            conflicts.push({ actionId: action.id, reason: `precondition would fail: ${failure}` });
+            continue;
+        }
+        const mapped = opts.mapper(action);
+        if (mapped)
+            providerCalls.push({ actionId: action.id, ...mapped });
+    }
+    return {
+        id: opts.id, service: opts.service, forkId: opts.forkId, baseRemoteRef: opts.baseRemoteRef,
+        transactions: pending.map((a) => a.id), providerCalls, conflicts,
+        requiresApproval: conflicts.length > 0 || providerCalls.some((c) => c.destructive),
+        createdAt: opts.createdAt,
+    };
+}
+function plansDir(service, root) {
+    return join(worldPaths(service, root).dir, 'plans');
+}
+export function writePlan(plan, root) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(plan.id))
+        throw new Error(`invalid plan id: ${plan.id}`);
+    const path = join(plansDir(plan.service, root), `${plan.id}.json`);
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(plan, null, 2)}\n`);
+    return plan;
+}
+export function readPlan(service, id, root) {
+    const path = join(plansDir(service, root), `${id}.json`);
+    return existsSync(path) ? readJsonFile(path) : null;
+}
+export function listPlans(service, root) {
+    const dir = plansDir(service, root);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => readJsonFile(join(dir, f)));
+}
+/**
+ * Whether a plan requires approval before it may be applied — recomputed from the
+ * plan's OWN `providerCalls`/`conflicts`, the exact rule `buildApplyPlan` uses to set
+ * the field in the first place. `applyPlan` calls this instead of trusting
+ * `plan.requiresApproval`: that field lives on plan JSON that is neither signed nor
+ * otherwise authenticated, so a hand-edited file (or a hand-built plan object) that
+ * flips the boolean to `false` must not be able to skip the approval gate — only
+ * removing the destructive calls/conflicts themselves does.
+ */
+export function planRequiresApproval(plan) {
+    return plan.conflicts.length > 0 || plan.providerCalls.some((c) => c.destructive);
+}
+/**
+ * Enact a plan against the real provider — the gated push path. Refuses an
+ * unapproved plan (approval requirement recomputed from the plan's own data, never
+ * trusted off the stored bit) and a push whose base has gone stale (the live
+ * remote ref moved since `plan.baseRemoteRef` was recorded) before any provider
+ * call or lease acquisition — zero side effects either way. Then acquires an apply
+ * lease for the plan's baseRemoteRef (single-writer), drives every provider call
+ * through the push phases via the injected writeFn (the only real I/O), then
+ * releases the lease.
+ */
+export async function applyPlan(plan, writeFn, opts) {
+    if (planRequiresApproval(plan) && !opts.approve)
+        throw new Error(`plan ${plan.id} requires approval (conflicts or destructive calls); pass approve:true to apply`);
+    const localRefView = { service: plan.service, forkId: plan.forkId, baseRemoteRef: plan.baseRemoteRef, recordedAt: plan.createdAt };
+    if (isBaseStale(localRefView, opts.root) && !opts.overrideStaleBase) {
+        throw new Error(`plan ${plan.id} base (${plan.baseRemoteRef.provider}/${plan.baseRemoteRef.name}) is stale — the remote ref advanced since this plan's base was recorded; rebase and rebuild the plan, or pass overrideStaleBase:true to apply anyway`);
+    }
+    const lease = acquireLease({
+        service: plan.service, provider: plan.baseRemoteRef.provider, remoteRef: plan.baseRemoteRef, planId: plan.id,
+        holder: opts.holder, id: opts.leaseId, acquiredAt: opts.acquiredAt, expiresAt: opts.expiresAt, now: opts.acquiredAt, root: opts.root,
+    });
+    const pushed = [];
+    const skipped = [];
+    const actionsById = new Map(pendingActions(plan.service, opts.root).map((a) => [a.id, a]));
+    try {
+        for (const call of plan.providerCalls) {
+            const action = actionsById.get(call.actionId);
+            if (!action) {
+                skipped.push(call.actionId);
+                continue;
+            }
+            const record = await pushTransaction({ service: plan.service, action: { id: action.id, subject: action.subject, fields: action.fields ?? {}, correlationId: action.correlationId }, provider: call.provider, operation: call.operation, idempotencyKey: call.idempotencyKey, occurredAt: opts.occurredAt, root: opts.root }, () => writeFn(call));
+            pushed.push(record);
+        }
+    }
+    finally {
+        releaseLease(plan.service, lease.id, { at: opts.occurredAt, root: opts.root });
+    }
+    return { planId: plan.id, leaseId: lease.id, pushed, skipped };
+}

package/dist/src/proxy.d.ts

@@ -0,0 +1,25 @@
+/** How one vendor's browser SDK is routed to its twin. Supplied by the caller. */
+export interface VendorRoute {
+    /** The vendor's twin origin, e.g. http://127.0.0.1:12111 */
+    origin: string;
+    /** Same-origin browser API path that belongs to this vendor, e.g. '/v1/' */
+    apiPathPrefix: string;
+    /** Absolute API host to strip from the vendor's browser loader so calls become
+     *  same-origin (e.g. 'https://api.stripe.com'). Omit if the SDK already calls same-origin. */
+    loaderHost?: string;
+}
+export interface TwinProxyOptions {
+    /** Your app's origin, e.g. http://localhost:3000 */
+    target: string;
+    /** vendor → routing. */
+    map: Record<string, VendorRoute>;
+    /** Extra local service origins whose redirects should be rewritten back to this proxy origin. */
+    redirectOrigins?: string[];
+    /** Listen port (0 = ephemeral). */
+    port?: number;
+}
+export interface TwinProxy {
+    port: number;
+    stop(): void;
+}
+export declare function createTwinProxy(opts: TwinProxyOptions): TwinProxy;

package/dist/src/proxy.js

@@ -0,0 +1,152 @@
+// Zero-edit browser injection: a dev proxy you put in front of your app so the
+// browser's vendor SDK calls share the SAME twin the backend uses — no app edits.
+//
+//   volter-twin proxy --target http://localhost:3000 \
+//     --map stripe=http://127.0.0.1:12111 --route stripe=/v1/ --loader-host stripe=https://api.stripe.com
+//
+// The browser loads your app through the proxy. Requests to a configured vendor's
+// browser API path (its `apiPathPrefix`, e.g. Stripe's /v1/…) are forwarded to that
+// vendor's twin; everything else passes through to your app. For vendors whose browser
+// SDK loads from a CDN and calls an absolute host (its `loaderHost`, e.g. Stripe.js →
+// api.stripe.com), the proxy rewrites the loader so its calls become same-origin and get
+// forwarded too. This kernel module is VENDOR-AGNOSTIC: the per-vendor routing values are
+// DATA supplied by the caller (sourced from each pack's `TwinPack.browserRouting`), never a
+// hardcoded vendor table.
+import http from 'node:http';
+import net from 'node:net';
+function vendorForPath(path, map) {
+    for (const [vendor, route] of Object.entries(map)) {
+        if (path.startsWith(route.apiPathPrefix))
+            return vendor;
+    }
+    return null;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Strip `loaderHost` (a full origin, e.g. 'https://api.stripe.com') from `text` so its
+ * calls become same-origin — but ONLY where it appears as a complete host, not as a
+ * blind substring. A plain `split(loaderHost).join('')` (the prior implementation) is
+ * NOT position-aware: it removes the substring wherever it occurs, including as a
+ * PREFIX of a longer, different host — e.g. 'https://api.stripe.com.evil.example/x'
+ * contains 'https://api.stripe.com' as a literal substring, and a naive strip corrupts
+ * it into '.evil.example/x' (the true host is stripe.com.evil.example, not stripe.com;
+ * same substring bug would also mangle a subdomain like sandbox.api.stripe.com if the
+ * scheme weren't part of the match). Position-aware fix: only strip a match that is NOT
+ * immediately followed by a domain-continuing character (letter/digit/dot/hyphen) —
+ * that character means the matched text is a prefix of a longer host, not the whole
+ * host, so it is left untouched.
+ */
+function stripLoaderHost(text, loaderHost) {
+    const pattern = new RegExp(`${escapeRegExp(loaderHost)}(?![A-Za-z0-9.-])`, 'g');
+    return text.replace(pattern, '');
+}
+function rewriteLocation(location, req, origins) {
+    if (!location || Array.isArray(location))
+        return location;
+    const host = req.headers.host;
+    if (!host)
+        return location;
+    const proxyOrigin = `http://${host}`;
+    for (const origin of origins) {
+        const normalized = origin.replace(/\/$/, '');
+        if (location === normalized)
+            return proxyOrigin;
+        if (location.startsWith(`${normalized}/`))
+            return `${proxyOrigin}${location.slice(normalized.length)}`;
+    }
+    return location;
+}
+function forwardTo(origin, req, res, rewrite, redirectOrigins = []) {
+    const target = new URL(req.url || '/', origin);
+    const headers = { ...req.headers, host: target.host };
+    delete headers['accept-encoding']; // so we can rewrite uncompressed bodies
+    const upstream = http.request(target, { method: req.method, headers }, (up) => {
+        if ((up.statusCode ?? 0) >= 300 && (up.statusCode ?? 0) < 400) {
+            const responseHeaders = { ...up.headers };
+            // `location` is single-valued, so rewriteLocation returns string|undefined here (never an array).
+            responseHeaders.location = rewriteLocation(responseHeaders.location, req, [origin, ...redirectOrigins]);
+            delete responseHeaders['transfer-encoding'];
+            delete responseHeaders['content-length'];
+            res.writeHead(up.statusCode || 302, responseHeaders);
+            res.end();
+            up.resume();
+            return;
+        }
+        const chunks = [];
+        up.on('data', (c) => chunks.push(c));
+        up.on('error', () => res.destroyed || res.end());
+        up.on('end', () => {
+            const body = Buffer.concat(chunks);
+            const out = rewrite ? rewrite(body, up.headers) : body;
+            const responseHeaders = { ...up.headers };
+            delete responseHeaders['content-length'];
+            delete responseHeaders['content-encoding'];
+            delete responseHeaders['transfer-encoding'];
+            responseHeaders['content-length'] = String(Buffer.byteLength(out));
+            res.writeHead(up.statusCode || 502, responseHeaders);
+            res.end(out);
+        });
+    });
+    upstream.on('error', (error) => {
+        if (res.headersSent) {
+            res.destroy(error);
+            return;
+        }
+        res.writeHead(502, { 'content-type': 'text/plain' });
+        res.end(`twin proxy upstream error: ${error.message}`);
+    });
+    req.pipe(upstream);
+}
+export function createTwinProxy(opts) {
+    const map = {};
+    for (const [vendor, route] of Object.entries(opts.map))
+        map[vendor] = { ...route, origin: route.origin.replace(/\/$/, '') };
+    const redirectOrigins = (opts.redirectOrigins ?? []).map((origin) => origin.replace(/\/$/, ''));
+    const server = http.createServer((req, res) => {
+        const path = req.url || '/';
+        const vendor = vendorForPath(path, map);
+        if (vendor) {
+            forwardTo(map[vendor].origin, req, res, undefined, redirectOrigins); // browser vendor API call → the twin
+            return;
+        }
+        // Otherwise pass through to the app, rewriting vendor loaders so their calls come back here.
+        forwardTo(opts.target, req, res, (body, headers) => {
+            const contentType = String(headers['content-type'] || '');
+            if (!contentType.includes('javascript') && !contentType.includes('html'))
+                return body;
+            let text = body.toString('utf8');
+            for (const route of Object.values(map)) {
+                if (route.loaderHost)
+                    text = stripLoaderHost(text, route.loaderHost);
+            }
+            return Buffer.from(text, 'utf8');
+        }, redirectOrigins);
+    });
+    // WebSocket / HTTP upgrade passthrough to the app.
+    server.on('upgrade', (req, socket, head) => {
+        const target = new URL(req.url || '/', opts.target);
+        const upstream = net.connect(Number(target.port || 80), target.hostname, () => {
+            upstream.write(`${req.method} ${target.pathname}${target.search} HTTP/${req.httpVersion}\r\n`);
+            for (const [name, value] of Object.entries(req.headers))
+                upstream.write(`${name}: ${value}\r\n`);
+            upstream.write('\r\n');
+            upstream.write(head);
+            upstream.pipe(socket);
+            socket.pipe(upstream);
+        });
+        const killSocket = () => { if (!socket.destroyed)
+            socket.destroy(); };
+        const killUpstream = () => { if (!upstream.destroyed)
+            upstream.destroy(); };
+        upstream.on('error', killSocket);
+        socket.on('error', killUpstream);
+        socket.on('close', killUpstream);
+        upstream.on('close', killSocket);
+    });
+    server.listen(opts.port ?? 0, '127.0.0.1');
+    const address = server.address();
+    const port = address && typeof address === 'object' ? address.port : (opts.port ?? 0);
+    return { port, stop: () => server.close() };
+}

package/dist/src/pushLedger.d.ts

@@ -0,0 +1,81 @@
+import type { SubjectFields } from './shadow.js';
+export type PushStatus = 'intent' | 'attempted' | 'provider_accepted' | 'succeeded' | 'failed' | 'observed_confirmed' | 'projection_suppressed' | 'confirmed' | 'abandoned';
+export type WorldPushRecord = {
+    id: string;
+    service: string;
+    actionId: string;
+    provider: string;
+    operation: string;
+    status: PushStatus;
+    idempotencyKey: string;
+    createdAt: string;
+    external?: {
+        id?: string;
+        url?: string;
+        rawRef?: string;
+    };
+    confirmedByEventId?: string;
+    error?: string;
+    data?: Record<string, unknown>;
+    /** Request-scoped correlation id (D3), inherited from the action being pushed —
+     *  every phase row for one push carries the SAME id as the action row it drives,
+     *  so an action row and its push-ledger rows join on this id alone (no reliance
+     *  on actionId, which is a different, id-shaped field with its own naming
+     *  convention). Falls back to a fresh id only if the action predates D3. */
+    correlationId?: string;
+};
+export type PushOutcome = {
+    externalId: string;
+    url?: string;
+    data?: Record<string, unknown>;
+};
+export declare function appendPushRecord(record: WorldPushRecord, root?: string): WorldPushRecord;
+export declare function listPushLedger(service: string, root?: string): WorldPushRecord[];
+/** Latest phase per push id (append order is the tiebreak). */
+export declare function latestPushByActionId(service: string, root?: string): Map<string, WorldPushRecord>;
+/** Pushes that returned provider_accepted but have not yet been observed_confirmed. */
+export declare function unconfirmedPushes(service: string, root?: string): WorldPushRecord[];
+export declare class UnreconciledPushError extends Error {
+    readonly pushId: string;
+    constructor(pushId: string, message: string);
+}
+/**
+ * Drive one local transaction commit through the push phases against the real
+ * provider via the injected writeFn (the ONLY real I/O — kernel holds no creds).
+ * On success it confirms the action into an observed event (confirmAction), which
+ * suppresses the local projection so state isn't double-counted. Idempotent: a
+ * previously-confirmed push for the same id replays without calling writeFn.
+ *
+ * Crash parity with egress.ts (performExternalWrite): the "is there a prior row,
+ * and is it terminal / unreconciled" read plus the fresh intent+attempted append
+ * run under ONE file-lock acquisition (TWIN-56), so two callers racing to push the
+ * same action id can't both observe "no attempt yet" and both append attempt rows.
+ * By default (onUnreconciled: 'fail') a latest row of `attempted` with nothing
+ * after it — a crash mid-flight, or a racing caller that lost the lock — refuses
+ * with UnreconciledPushError instead of blindly re-invoking writeFn. Pass
+ * onUnreconciled: 'retry' only after verifying external state.
+ */
+export declare function pushTransaction(opts: {
+    service: string;
+    action: {
+        id: string;
+        subject: {
+            type: string;
+            id: string;
+        };
+        fields: SubjectFields;
+        correlationId?: string;
+    };
+    provider: string;
+    operation: string;
+    idempotencyKey: string;
+    occurredAt: string;
+    root?: string;
+    onUnreconciled?: 'fail' | 'retry';
+}, writeFn: () => Promise<PushOutcome>): Promise<WorldPushRecord>;
+/** Mark a push intent abandoned (e.g. operator decided not to push). */
+export declare function abandonPush(service: string, actionId: string, opts?: {
+    root?: string;
+    at?: string;
+    reason?: string;
+}): WorldPushRecord;

package/dist/src/pushLedger.js

@@ -0,0 +1,130 @@
+// Push ledger + phases (the twins architecture notes → "Push Ledger Packet").
+// Records replication of a local transaction commit to the real provider, separate
+// from observed events and the action log. A push walks explicit phases —
+//   intent → attempted → provider_accepted → observed_confirmed
+//          → projection_suppressed → confirmed   (or failed / abandoned)
+// `provider_accepted` (the API call returned) is NOT confirmation; confirmation is
+// when the real provider fact is committed as an observed event and linked back to
+// the action (via confirmAction), at which point the local projection is suppressed.
+// Real I/O enters only through the injected writeFn (auth boundary). Append-only;
+// current status = the latest row per push id. Idempotent: a confirmed push replays.
+//
+// Crash parity with egress.ts: a crash mid-flight (process dies while writeFn is in
+// flight) leaves the latest row `attempted` with nothing after it — we don't know
+// whether the provider call landed. Re-sending blind risks a silent double-apply
+// against a non-idempotent vendor operation, so pushTransaction refuses
+// (UnreconciledPushError) unless the caller verifies external state and passes
+// onUnreconciled: 'retry' (mirrors egress.ts's UnreconciledWriteIntentError).
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { confirmAction } from "./actions.js";
+import { appendDurable, twinLog, withFileLock, worldPaths } from "./storage.js";
+function ledgerPath(service, root) {
+    return join(worldPaths(service, root).dir, 'push-ledger.jsonl');
+}
+/** Lock guarding the push ledger's read-then-append critical sections (TWIN-56):
+ *  the same file-lock primitive events/actions use, so two callers racing to push
+ *  the same action can't both read "no prior attempt" and both append duplicate
+ *  attempt rows. */
+function ledgerLockPath(service, root) {
+    return `${ledgerPath(service, root)}.lock`;
+}
+export function appendPushRecord(record, root) {
+    const path = ledgerPath(record.service, root);
+    mkdirSync(join(path, '..'), { recursive: true });
+    appendDurable(path, `${JSON.stringify(record)}\n`);
+    twinLog('push.append', { service: record.service, id: record.id, actionId: record.actionId, status: record.status, correlationId: record.correlationId });
+    return record;
+}
+export function listPushLedger(service, root) {
+    const path = ledgerPath(service, root);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, 'utf8').split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+}
+/** Latest phase per push id (append order is the tiebreak). */
+export function latestPushByActionId(service, root) {
+    const latest = new Map();
+    for (const r of listPushLedger(service, root))
+        latest.set(r.actionId, r); // later rows overwrite
+    return latest;
+}
+/** Pushes that returned provider_accepted but have not yet been observed_confirmed. */
+export function unconfirmedPushes(service, root) {
+    return [...latestPushByActionId(service, root).values()].filter((r) => r.status === 'provider_accepted' || r.status === 'attempted');
+}
+const TERMINAL = ['confirmed', 'projection_suppressed', 'succeeded'];
+export class UnreconciledPushError extends Error {
+    pushId;
+    constructor(pushId, message) {
+        super(message);
+        this.name = 'UnreconciledPushError';
+        this.pushId = pushId;
+    }
+}
+/**
+ * Drive one local transaction commit through the push phases against the real
+ * provider via the injected writeFn (the ONLY real I/O — kernel holds no creds).
+ * On success it confirms the action into an observed event (confirmAction), which
+ * suppresses the local projection so state isn't double-counted. Idempotent: a
+ * previously-confirmed push for the same id replays without calling writeFn.
+ *
+ * Crash parity with egress.ts (performExternalWrite): the "is there a prior row,
+ * and is it terminal / unreconciled" read plus the fresh intent+attempted append
+ * run under ONE file-lock acquisition (TWIN-56), so two callers racing to push the
+ * same action id can't both observe "no attempt yet" and both append attempt rows.
+ * By default (onUnreconciled: 'fail') a latest row of `attempted` with nothing
+ * after it — a crash mid-flight, or a racing caller that lost the lock — refuses
+ * with UnreconciledPushError instead of blindly re-invoking writeFn. Pass
+ * onUnreconciled: 'retry' only after verifying external state.
+ */
+export async function pushTransaction(opts, writeFn) {
+    const { service, action, provider, operation, idempotencyKey, occurredAt, root, onUnreconciled = 'fail' } = opts;
+    const pushId = `push:${service}:${action.id}`;
+    // Inherit the action's correlationId (D3) so every phase row this push writes joins
+    // back to the action row on that id alone. Actions appended after D3 always carry
+    // one (appendAction/appendActionIfAbsent stamp it); the fallback only covers an
+    // action object built by hand without going through those (e.g. an older ledger).
+    const correlationId = action.correlationId ?? randomUUID();
+    const base = { id: pushId, service, actionId: action.id, provider, operation, idempotencyKey, createdAt: occurredAt, correlationId };
+    // Read (prior status) + decide (terminal replay / unreconciled refusal) + the
+    // fresh intent/attempted append, all under one lock — the atomic critical
+    // section a cross-process race would otherwise be able to interleave (TWIN-56).
+    const early = withFileLock(ledgerLockPath(service, root), () => {
+        const prior = latestPushByActionId(service, root).get(action.id);
+        if (prior && TERMINAL.includes(prior.status))
+            return prior; // idempotent replay
+        if (prior && prior.status === 'attempted' && onUnreconciled === 'fail') {
+            throw new UnreconciledPushError(pushId, `Push ${pushId} has an 'attempted' row with no result after it — the provider call may or may not have happened. ` +
+                `Verify external state, then retry with onUnreconciled: 'retry'.`);
+        }
+        appendPushRecord({ ...base, status: 'intent' }, root);
+        appendPushRecord({ ...base, status: 'attempted' }, root);
+        return null;
+    });
+    if (early)
+        return early;
+    let outcome;
+    try {
+        outcome = await writeFn();
+    }
+    catch (error) {
+        return appendPushRecord({ ...base, status: 'failed', error: error instanceof Error ? error.message : String(error) }, root);
+    }
+    appendPushRecord({ ...base, status: 'provider_accepted', external: { id: outcome.externalId, ...(outcome.url ? { url: outcome.url } : {}) }, ...(outcome.data ? { data: outcome.data } : {}) }, root);
+    // Confirm: append the observed provider fact + map it back, suppressing the local projection.
+    const { observedEventId } = confirmAction({ service, actionId: action.id, subject: action.subject, fields: action.fields, occurredAt, root });
+    appendPushRecord({ ...base, status: 'observed_confirmed', external: { id: outcome.externalId }, confirmedByEventId: observedEventId }, root);
+    appendPushRecord({ ...base, status: 'projection_suppressed', confirmedByEventId: observedEventId }, root);
+    return appendPushRecord({ ...base, status: 'confirmed', external: { id: outcome.externalId }, confirmedByEventId: observedEventId }, root);
+}
+/** Mark a push intent abandoned (e.g. operator decided not to push). */
+export function abandonPush(service, actionId, opts = {}) {
+    const prior = latestPushByActionId(service, opts.root).get(actionId);
+    return appendPushRecord({
+        id: `push:${service}:${actionId}`, service, actionId, provider: prior?.provider ?? '', operation: prior?.operation ?? '',
+        idempotencyKey: prior?.idempotencyKey ?? `abandon:${actionId}`, createdAt: opts.at ?? new Date().toISOString(),
+        status: 'abandoned', ...(opts.reason ? { error: opts.reason } : {}),
+    }, opts.root);
+}

package/dist/src/queueLifecycle.d.ts

@@ -0,0 +1,62 @@
+import type { QueuedWorldServiceEvent } from './types.js';
+export type QueueRowStatus = 'queued' | 'committed' | 'ignored' | 'superseded' | 'poisoned';
+export type QueueStatusTransition = {
+    queueId: string;
+    status: QueueRowStatus;
+    at: string;
+    reason?: string;
+    /** for committed rows: the canonical event id it produced. */
+    eventId?: string;
+    /** for superseded rows: the row that replaced it. */
+    supersededBy?: string;
+};
+export type QueueRowWithStatus = {
+    row: QueuedWorldServiceEvent;
+    status: QueueRowStatus;
+    transition?: QueueStatusTransition;
+};
+export declare function setQueueRowStatus(service: string, queueId: string, status: QueueRowStatus, opts?: {
+    root?: string;
+    at?: string;
+    reason?: string;
+    eventId?: string;
+    supersededBy?: string;
+}): QueueStatusTransition;
+export declare function queueRowStatus(service: string, queueId: string, root?: string): QueueRowStatus;
+/** Every queue row with its current lifecycle status. */
+export declare function listQueueWithStatus(service: string, root?: string): QueueRowWithStatus[];
+/** Rows still awaiting a decision (status === 'queued'). */
+export declare function pendingQueueRows(service: string, root?: string): QueuedWorldServiceEvent[];
+export type QueueCounts = Record<QueueRowStatus, number>;
+export declare function queueCounts(service: string, root?: string): QueueCounts;
+/** Commit a single queued row into the canonical event log + stamp `committed`. */
+export declare function commitQueueRow(service: string, queueId: string, opts?: {
+    root?: string;
+    at?: string;
+}): {
+    appended: boolean;
+    eventId?: string;
+};
+export declare function ignoreQueueRow(service: string, queueId: string, opts?: {
+    root?: string;
+    at?: string;
+    reason?: string;
+}): QueueStatusTransition;
+export declare function supersedeQueueRow(service: string, queueId: string, supersededBy: string, opts?: {
+    root?: string;
+    at?: string;
+    reason?: string;
+}): QueueStatusTransition;
+export declare function poisonQueueRow(service: string, queueId: string, opts?: {
+    root?: string;
+    at?: string;
+    reason?: string;
+}): QueueStatusTransition;
+/** Commit all rows currently `queued`, in deterministic provider-time order; stamps committed. */
+export declare function commitPendingQueue(service: string, opts?: {
+    root?: string;
+    at?: string;
+}): {
+    committed: number;
+    eventIds: string[];
+};