@volter/twin 0.1.0 → 0.1.1

package/dist/src/plan.d.ts

@@ -1,97 +0,0 @@
-import type { TwinAction } from './actions.js';
-import type { WorldRemoteRef } from './refs.js';
-import type { PushOutcome, WorldPushRecord } from './pushLedger.js';
-export type ProviderCall = {
-    actionId: string;
-    provider: string;
-    operation: string;
-    input: Record<string, unknown>;
-    idempotencyKey: string;
-    destructive: boolean;
-    expectedConfirmation: {
-        subject: {
-            type: string;
-            id: string;
-        };
-        eventType: string;
-        matcher: Record<string, unknown>;
-    };
-};
-export type WorldApplyPlan = {
-    id: string;
-    service: string;
-    forkId: string;
-    baseRemoteRef: WorldRemoteRef;
-    transactions: string[];
-    providerCalls: ProviderCall[];
-    conflicts: Array<{
-        actionId: string;
-        reason: string;
-    }>;
-    requiresApproval: boolean;
-    createdAt: string;
-};
-/** Map a local transaction commit → the provider call that materializes it (vendor-specific). Return null to skip. */
-export type ActionMapper = (action: TwinAction) => Omit<ProviderCall, 'actionId'> | null;
-/** Pending transactions whose preconditions would fail against current projected state. */
-export declare function pendingConflicts(service: string, root?: string): Array<{
-    actionId: string;
-    reason: string;
-}>;
-/**
- * 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 declare function buildApplyPlan(opts: {
-    service: string;
-    forkId: string;
-    baseRemoteRef: WorldRemoteRef;
-    mapper: ActionMapper;
-    id: string;
-    createdAt: string;
-    root?: string;
-}): WorldApplyPlan;
-export declare function writePlan(plan: WorldApplyPlan, root?: string): WorldApplyPlan;
-export declare function readPlan(service: string, id: string, root?: string): WorldApplyPlan | null;
-export declare function listPlans(service: string, root?: string): WorldApplyPlan[];
-export type ApplyResult = {
-    planId: string;
-    leaseId: string;
-    pushed: WorldPushRecord[];
-    skipped: string[];
-};
-/**
- * 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 declare function planRequiresApproval(plan: WorldApplyPlan): boolean;
-/**
- * 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 declare function applyPlan(plan: WorldApplyPlan, writeFn: (call: ProviderCall) => Promise<PushOutcome>, opts: {
-    holder: {
-        kind: 'agent' | 'human' | 'system';
-        id: string;
-    };
-    leaseId: string;
-    acquiredAt: string;
-    expiresAt: string;
-    occurredAt: string;
-    approve?: boolean;
-    overrideStaleBase?: boolean;
-    root?: string;
-}): Promise<ApplyResult>;

package/dist/src/plan.js

@@ -1,151 +0,0 @@
-// 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

@@ -1,25 +0,0 @@
-/** 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

@@ -1,152 +0,0 @@
-// 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

@@ -1,81 +0,0 @@
-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

@@ -1,130 +0,0 @@
-// 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);
-}