@volter/twin 0.1.0 → 0.1.1

package/dist/src/connector.d.ts

@@ -1,106 +0,0 @@
-import type { SubjectFields } from './shadow.js';
-import type { WorldServiceEvent } from './types.js';
-export type ConnectorObservation = {
-    subject: {
-        type: string;
-        id: string;
-    };
-    /** Current field values; the runner diffs them against the shadow state. */
-    observed: SubjectFields;
-    /** Provider update timestamp (ISO); drives cursor advancement. */
-    occurredAt: string;
-    external?: {
-        provider: string;
-        id: string;
-        url?: string;
-    };
-    /**
-     * Extra append-only events tied to this observation (comments, reviews,
-     * …). Appended idempotently — the connector encodes identity (including
-     * content hashes for mutable bodies) in id/idempotencyKey.
-     */
-    events?: WorldServiceEvent[];
-};
-export type WorldConnector = {
-    service: string;
-    /** Cursor filename under the service's cursors/ dir (default poll.json). */
-    cursorFile?: string;
-    /** Seed the shadow from historical event types (default: deltas only). */
-    shadowExtractor?: (event: WorldServiceEvent) => SubjectFields | null;
-    /**
-     * Fetch observations whose provider timestamp advanced past the cursor
-     * (empty cursor = from the beginning). `limit` is a runaway-fetch safety
-     * cap, not a page size: the connector reports `truncated: true` when the
-     * cap was hit so the runner holds the cursor.
-     */
-    fetchSince(input: {
-        cursor: string;
-        limit: number;
-        root: string;
-    }): Promise<{
-        observations: ConnectorObservation[];
-        truncated: boolean;
-    }>;
-};
-export type ConnectorPollResult = {
-    service: string;
-    cursorBefore: string | null;
-    cursorAfter: string | null;
-    truncated: boolean;
-    fetched: number;
-    deltasAppended: number;
-    eventsAppended: number;
-    changedSubjects: string[];
-};
-export declare function pollCursorPath(service: string, root?: string, cursorFile?: string): string;
-export declare function loadPollCursor(service: string, root?: string, cursorFile?: string): string;
-export declare function savePollCursor(service: string, after: string, root?: string, cursorFile?: string): void;
-export declare function runConnectorPoll(connector: WorldConnector, options?: {
-    root?: string;
-    cursor?: string;
-    limit?: number;
-}): Promise<ConnectorPollResult>;
-import type { ShadowState } from './shadow.js';
-export type SweepConnector = {
-    service: string;
-    shadowExtractor?: (event: WorldServiceEvent) => SubjectFields | null;
-    /** Which tracked subjects to re-observe this sweep. */
-    selectSubjects(input: {
-        subjects: Array<{
-            type: string;
-            id: string;
-        }>;
-        shadow: ShadowState;
-        sweepAll: boolean;
-    }): Array<{
-        type: string;
-        id: string;
-    }>;
-    /** Fetch the subject's current field state; null = fetch error. */
-    fetchSubject(subject: {
-        type: string;
-        id: string;
-    }): Promise<{
-        observed: SubjectFields;
-        occurredAt: string;
-        external?: {
-            provider: string;
-            id: string;
-            url?: string;
-        };
-    } | null>;
-};
-export type ConnectorSweepResult = {
-    service: string;
-    subjects: number;
-    polled: number;
-    deltasAppended: number;
-    errors: number;
-    changedSubjects: string[];
-    sweepAll: boolean;
-};
-export declare function runConnectorSweep(connector: SweepConnector, options?: {
-    root?: string;
-    limit?: number;
-    sweepAll?: boolean;
-}): Promise<ConnectorSweepResult>;

package/dist/src/connector.js

@@ -1,129 +0,0 @@
-// Connector contract + poll runner for cursor-based world pollers.
-//
-// A connector owns only the provider-specific parts: fetching observations
-// whose provider timestamp advanced past the cursor, mapping them to subject
-// fields, and constructing any extra append-only events (comments, …). The
-// runner owns the invariants every poller must respect:
-//  - shadow-diff recording: an unchanged re-observation appends nothing
-//  - extra events append idempotently (id/idempotencyKey carry identity)
-//  - the cursor only advances after every observation in the batch is
-//    recorded, and NEVER advances on a truncated batch — results arrive
-//    newest-first, so a capped batch cut off OLDER updates and advancing
-//    would skip them forever
-//  - the cursor saves 1ms behind the max observed timestamp so an update
-//    landing at exactly that timestamp after the poll is not excluded by a
-//    strictly-greater filter; the overlap re-fetch is free (unchanged
-//    observations append nothing)
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { buildShadowState, recordObservedDelta } from "./shadow.js";
-import { appendEvent, readJsonFile, rebuildGenericState, worldPaths } from "./storage.js";
-export function pollCursorPath(service, root, cursorFile = 'poll.json') {
-    return join(worldPaths(service, root).cursors, cursorFile);
-}
-export function loadPollCursor(service, root, cursorFile) {
-    const path = pollCursorPath(service, root, cursorFile);
-    if (!existsSync(path))
-        return '';
-    return readJsonFile(path).after ?? '';
-}
-export function savePollCursor(service, after, root, cursorFile) {
-    const path = pollCursorPath(service, root, cursorFile);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify({ after, updatedAt: new Date().toISOString() }, null, 2)}\n`);
-}
-export async function runConnectorPoll(connector, options = {}) {
-    const root = options.root;
-    const service = connector.service;
-    const limit = options.limit ?? 10000;
-    const cursorBefore = options.cursor ?? loadPollCursor(service, root, connector.cursorFile);
-    const { observations, truncated } = await connector.fetchSince({ cursor: cursorBefore, limit, root: root ?? process.env.PROJECT_ROOT ?? process.cwd() });
-    // Shadow folds from the event log; subject state arrives via deltas, so no
-    // snapshot extractor is needed.
-    const shadow = buildShadowState(service, connector.shadowExtractor ?? (() => null), root);
-    let deltasAppended = 0;
-    let eventsAppended = 0;
-    let maxOccurredAt = cursorBefore;
-    const changedSubjects = [];
-    for (const observation of observations) {
-        const result = recordObservedDelta(shadow, {
-            service,
-            subject: observation.subject,
-            observed: observation.observed,
-            occurredAt: observation.occurredAt,
-            ...(observation.external ? { external: observation.external } : {}),
-        }, root);
-        if (result.changed && result.append.appended) {
-            deltasAppended += 1;
-            changedSubjects.push(observation.subject.id);
-        }
-        for (const event of observation.events ?? []) {
-            if (appendEvent(event, root).appended)
-                eventsAppended += 1;
-        }
-        if (!maxOccurredAt || observation.occurredAt > maxOccurredAt)
-            maxOccurredAt = observation.occurredAt;
-    }
-    if (!truncated && maxOccurredAt && maxOccurredAt !== cursorBefore) {
-        savePollCursor(service, new Date(Date.parse(maxOccurredAt) - 1).toISOString(), root, connector.cursorFile);
-    }
-    rebuildGenericState(service, root);
-    return {
-        service,
-        cursorBefore: cursorBefore || null,
-        cursorAfter: truncated ? cursorBefore || null : (maxOccurredAt || null),
-        truncated,
-        fetched: observations.length,
-        deltasAppended,
-        eventsAppended,
-        changedSubjects,
-    };
-}
-// ---------------------------------------------------------------------------
-// Sweep mode: for providers polled by SUBJECT rather than by time cursor
-// (e.g. re-observing the current state of every tracked pull request). The
-// runner owns subject enumeration from the generic world state, the
-// shadow-diff invariant (unchanged re-observations append nothing), and
-// error accounting; the connector owns selection and the per-subject fetch
-// (null = fetch error, counted and reported, never silently dropped).
-import { loadState } from "./storage.js";
-export async function runConnectorSweep(connector, options = {}) {
-    const root = options.root;
-    const service = connector.service;
-    const limit = options.limit ?? 200;
-    const sweepAll = options.sweepAll ?? false;
-    const generic = loadState(service, root);
-    const allSubjects = Object.values(generic?.subjects ?? {}).map((subject) => {
-        const record = subject;
-        return { type: String(record.type ?? ''), id: String(record.id ?? '') };
-    });
-    const shadow = buildShadowState(service, connector.shadowExtractor ?? (() => null), root);
-    const selected = connector.selectSubjects({ subjects: allSubjects, shadow, sweepAll });
-    let polled = 0;
-    let deltasAppended = 0;
-    let errors = 0;
-    const changedSubjects = [];
-    for (const subject of selected) {
-        if (polled >= limit)
-            break;
-        const observation = await connector.fetchSubject(subject);
-        polled += 1;
-        if (!observation) {
-            errors += 1;
-            continue;
-        }
-        const result = recordObservedDelta(shadow, {
-            service,
-            subject,
-            observed: observation.observed,
-            occurredAt: observation.occurredAt,
-            ...(observation.external ? { external: observation.external } : {}),
-        }, root);
-        if (result.changed && result.append.appended) {
-            deltasAppended += 1;
-            changedSubjects.push(subject.id);
-        }
-    }
-    rebuildGenericState(service, root);
-    return { service, subjects: allSubjects.length, polled, deltasAppended, errors, changedSubjects, sweepAll };
-}

package/dist/src/control-plane.d.ts

@@ -1,21 +0,0 @@
-export { applyTwinWrite, createTwinServer, resolveTwinRead, twinResources } from './serve.js';
-export type { TwinResource, TwinWriteResult } from './serve.js';
-export { formatStatus, worldStatus } from './status.js';
-export type { WorldStatus } from './status.js';
-export { applyPlan, buildApplyPlan, listPlans, pendingConflicts, planRequiresApproval, readPlan, writePlan } from './plan.js';
-export type { ActionMapper, ApplyResult, ProviderCall, WorldApplyPlan } from './plan.js';
-export { abandonPush, appendPushRecord, latestPushByActionId, listPushLedger, pushTransaction, unconfirmedPushes, UnreconciledPushError } from './pushLedger.js';
-export type { PushOutcome, PushStatus, WorldPushRecord } from './pushLedger.js';
-export { acquireLease, activeLease, isLeaseActive, LeaseHeldError, listLeases, releaseLease } from './lease.js';
-export type { WorldApplyLease } from './lease.js';
-export { isBaseStale, listRemoteRefs, readLocalRef, readRemoteRef, writeLocalRef, writeRemoteRef } from './refs.js';
-export type { WorldLocalRef, WorldRemoteRef } from './refs.js';
-export { commitPendingQueue, commitQueueRow, ignoreQueueRow, listQueueWithStatus, pendingQueueRows, poisonQueueRow, queueCounts, queueRowStatus, setQueueRowStatus, supersedeQueueRow, } from './queueLifecycle.js';
-export type { QueueCounts, QueueRowStatus, QueueRowWithStatus, QueueStatusTransition } from './queueLifecycle.js';
-export { confirmAction } from './actions.js';
-export { auditForkNoRealWrites, cherryPickActions, discardFork, forkDivergence, forkTwin, isFork, mergeForks, rebaseFork, readForkMeta, resetFork, } from './fork.js';
-export type { CopyResult, ForkAudit, ForkDivergence, ForkMeta, SubjectDivergence } from './fork.js';
-export { isCleanlyReconcilable, reconcile, reconcileRequiresApproval } from './reconcile.js';
-export type { FieldDecision, ReconcilePlan, ReconcilePolicy, SubjectReconcile } from './reconcile.js';
-export { currentResources, syncPull, syncPush } from './sync.js';
-export type { PullResult, PushItemResult, PushResult, SyncResource } from './sync.js';

package/dist/src/control-plane.js

@@ -1,40 +0,0 @@
-// The CONTROL PLANE — the legitimately-shared thing across twins.
-//
-// This is the uniform contract + operator surface every twin is *driven* through:
-// the same way to serve/read/write, switch modes, see `status`, build a `plan`,
-// `push`/apply (with explicit phases), hold a `lease`, manage the event-queue
-// lifecycle, track remote refs, and run Git-like fork operations. An operator or
-// agent learns ONE way to drive any twin.
-//
-// What this is NOT: a "kernel" that makes every twin *implement its world the same
-// way*. Twins are implemented per-vendor (their exact API + query semantics). The
-// data-plane mechanics they reuse (event log, projection, shadow/delta, egress,
-// connectors — exported from the package root) are **optional libraries**, like a
-// UI library a visualizer may pick — not a mandate. See
-// `the twins architecture notes` → "share the control plane, not the
-// implementation".
-//
-// Barrel only: re-exports the control-plane surface as one cohesive thing. Consume
-// it as a namespace via `import { controlPlane } from '@volter/twin'`.
-// serve/read/write surface (how a twin is driven): one twin, readable always,
-// writable unless started read-only (writes land as local actions)
-export { applyTwinWrite, createTwinServer, resolveTwinRead, twinResources } from "./serve.js";
-// status
-export { formatStatus, worldStatus } from "./status.js";
-// plan + apply orchestration
-export { applyPlan, buildApplyPlan, listPlans, pendingConflicts, planRequiresApproval, readPlan, writePlan } from "./plan.js";
-// push ledger + phases
-export { abandonPush, appendPushRecord, latestPushByActionId, listPushLedger, pushTransaction, unconfirmedPushes, UnreconciledPushError } from "./pushLedger.js";
-// apply leases (single-writer per checkpoint)
-export { acquireLease, activeLease, isLeaseActive, LeaseHeldError, listLeases, releaseLease } from "./lease.js";
-// remote refs / checkpoints + stale-base guard
-export { isBaseStale, listRemoteRefs, readLocalRef, readRemoteRef, writeLocalRef, writeRemoteRef } from "./refs.js";
-// event-queue lifecycle (queued/committed/ignored/superseded/poisoned)
-export { commitPendingQueue, commitQueueRow, ignoreQueueRow, listQueueWithStatus, pendingQueueRows, poisonQueueRow, queueCounts, queueRowStatus, setQueueRowStatus, supersedeQueueRow, } from "./queueLifecycle.js";
-// confirm/revert ops (transaction → observed-event mapping)
-export { confirmAction } from "./actions.js";
-// fork operations (rebase/merge/cherry-pick/reset/discard) + three-way reconcile
-export { auditForkNoRealWrites, cherryPickActions, discardFork, forkDivergence, forkTwin, isFork, mergeForks, rebaseFork, readForkMeta, resetFork, } from "./fork.js";
-export { isCleanlyReconcilable, reconcile, reconcileRequiresApproval } from "./reconcile.js";
-// sync direction (pull/push selected resources) — the bidirectional surface
-export { currentResources, syncPull, syncPush } from "./sync.js";

package/dist/src/egress.d.ts

@@ -1,93 +0,0 @@
-import type { WorldServiceEvent } from './types.js';
-export declare const WRITE_INTENT_SUFFIX = ".write.intent";
-export declare const WRITE_RESULT_SUFFIX = ".write.result";
-export declare function isEgressEventType(type: string): boolean;
-export type EgressActor = {
-    kind: 'human' | 'agent' | 'bot' | 'system';
-    id?: string;
-    name?: string;
-};
-export type EgressWriteRequest = {
-    service: string;
-    /** Provider operation name, e.g. 'chat.postMessage', 'issueCreate'. */
-    operation: string;
-    /** external.provider value for result events, e.g. 'slack', 'github', 'linear'. */
-    provider: string;
-    subject: {
-        type: string;
-        id: string;
-    };
-    /**
-     * Stable key for the logical action. Two calls with the same key are the
-     * same action: a completed write is replayed from the ledger, never re-sent.
-     */
-    idempotencyKey: string;
-    actor?: EgressActor;
-    /** Request payload summary recorded on the intent event. Never put secrets here. */
-    data?: Record<string, unknown>;
-};
-export type EgressWriteOutcome = {
-    externalId: string;
-    url?: string;
-    data?: Record<string, unknown>;
-};
-export type EgressWriteResult = {
-    /** 'performed' = writeFn ran this call; 'replayed' = ledger already had a success. */
-    status: 'performed' | 'replayed';
-    intentEventId: string;
-    resultEventId: string;
-    attempt: number;
-    outcome: EgressWriteOutcome;
-};
-export type EgressLedgerEntry = {
-    intent: WorldServiceEvent;
-    results: WorldServiceEvent[];
-    succeeded: boolean;
-};
-export declare class UnreconciledWriteIntentError extends Error {
-    readonly intentEventId: string;
-    constructor(intentEventId: string, message: string);
-}
-export declare function recordWriteIntent(request: EgressWriteRequest, root?: string): WorldServiceEvent;
-/**
- * Perform an external write through the egress ledger.
- *
- * Ordering: a write.intent event is durably appended BEFORE the provider call,
- * and a write.result event is appended after it (success or failure). A crash
- * between the two leaves an intent without results; by default the next call
- * with the same idempotencyKey refuses to re-send (UnreconciledWriteIntentError)
- * because the provider may or may not have applied the write. After verifying
- * the external state, callers retry with onUnreconciled: 'retry'.
- *
- * A ledger entry with a success result is terminal: the call returns the
- * recorded outcome without invoking writeFn. Failed attempts may be retried;
- * each attempt appends its own numbered result event.
- *
- * Concurrency (TWIN-58): the ledger-check + intent-append span runs under
- * `withFileLock` on the SAME events lock `appendEvent` itself uses (egress.ts has
- * no lock of its own to invent — reusing the events lock is what makes this
- * atomic against a concurrent appendEvent/commitQueuedEvents too, not just a
- * concurrent performExternalWrite). Without this, two concurrent calls with the
- * same idempotencyKey could both read "no entry" and both invoke writeFn — the
- * vendor receiving the write twice despite this function's contract that a
- * completed write is replayed, never re-sent (see actions.ts:121-123 for the same
- * check-then-append-under-one-lock reasoning applied to the action log). The
- * `writeFn` call itself deliberately stays OUTSIDE the lock (it's arbitrary,
- * possibly slow, real I/O — holding a file lock across it would serialize every
- * write to the service, not just same-key ones); `inFlightWrites` covers the
- * in-process race for the span the lock can't (an async call can't hold a
- * synchronous lock across its own `await`).
- */
-export declare function performExternalWrite(request: EgressWriteRequest, writeFn: () => Promise<EgressWriteOutcome>, options?: {
-    root?: string;
-    onUnreconciled?: 'fail' | 'retry';
-}): Promise<EgressWriteResult>;
-/** Intents with no result event at all — crash candidates needing reconciliation. */
-export declare function listUnreconciledWriteIntents(service: string, root?: string): WorldServiceEvent[];
-/** Full intent/result ledger for a service, keyed by intent event id. */
-export declare function listEgressLedger(service: string, root?: string): EgressLedgerEntry[];
-/**
- * Echo lookup: did we produce this external object? Inbound events whose
- * external id matches a recorded successful write are our own writes coming back.
- */
-export declare function findWriteResultByExternal(service: string, provider: string, externalId: string, root?: string): WorldServiceEvent | null;

package/dist/src/egress.js

@@ -1,264 +0,0 @@
-import { createHash } from 'node:crypto';
-import { appendEvent, appendEventLocked, createEvent, eventsLockPath, listEvents, withFileLock, worldPaths } from "./storage.js";
-export const WRITE_INTENT_SUFFIX = '.write.intent';
-export const WRITE_RESULT_SUFFIX = '.write.result';
-export function isEgressEventType(type) {
-    return type.endsWith(WRITE_INTENT_SUFFIX) || type.endsWith(WRITE_RESULT_SUFFIX);
-}
-export class UnreconciledWriteIntentError extends Error {
-    intentEventId;
-    constructor(intentEventId, message) {
-        super(message);
-        this.name = 'UnreconciledWriteIntentError';
-        this.intentEventId = intentEventId;
-    }
-}
-function egressHash(request) {
-    return createHash('sha256')
-        .update(`${request.service}\u001f${request.operation}\u001f${request.idempotencyKey}`)
-        .digest('hex')
-        .slice(0, 16);
-}
-function intentIdempotencyKey(request) {
-    return `egress:${request.service}:${request.operation}:${request.idempotencyKey}:intent`;
-}
-function resultIdempotencyKey(request, attempt) {
-    return `egress:${request.service}:${request.operation}:${request.idempotencyKey}:result:${attempt}`;
-}
-function defaultActor(actor) {
-    return actor ?? { kind: 'agent' };
-}
-function ledgerFor(service, root) {
-    const entries = new Map();
-    const resultsByCausation = new Map();
-    for (const event of listEvents(service, root)) {
-        if (event.type.endsWith(WRITE_INTENT_SUFFIX)) {
-            entries.set(event.id, { intent: event, results: [], succeeded: false });
-        }
-        else if (event.type.endsWith(WRITE_RESULT_SUFFIX) && event.causationId) {
-            const bucket = resultsByCausation.get(event.causationId) ?? [];
-            bucket.push(event);
-            resultsByCausation.set(event.causationId, bucket);
-        }
-    }
-    for (const [intentId, results] of resultsByCausation) {
-        const entry = entries.get(intentId);
-        if (!entry)
-            continue;
-        entry.results = results;
-        entry.succeeded = results.some((result) => result.data.status === 'success');
-    }
-    return entries;
-}
-function buildIntentEvent(request) {
-    const hash = egressHash(request);
-    return createEvent({
-        id: `${request.service}${WRITE_INTENT_SUFFIX}:${hash}`,
-        service: request.service,
-        type: `${request.service}${WRITE_INTENT_SUFFIX}`,
-        idempotencyKey: intentIdempotencyKey(request),
-        occurredAt: new Date().toISOString(),
-        origin: 'agent',
-        actor: defaultActor(request.actor),
-        subject: request.subject,
-        correlationId: `${request.service}${WRITE_INTENT_SUFFIX}:${hash}`,
-        data: {
-            operation: request.operation,
-            provider: request.provider,
-            egressKey: request.idempotencyKey,
-            ...(request.data ?? {}),
-        },
-    });
-}
-export function recordWriteIntent(request, root) {
-    return appendEvent(buildIntentEvent(request), root).event;
-}
-function recordWriteResult(input) {
-    const { request, intentEventId, attempt, status, outcome, error, root } = input;
-    const hash = egressHash(request);
-    const result = createEvent({
-        id: `${request.service}${WRITE_RESULT_SUFFIX}:${hash}:${attempt}`,
-        service: request.service,
-        type: `${request.service}${WRITE_RESULT_SUFFIX}`,
-        idempotencyKey: resultIdempotencyKey(request, attempt),
-        occurredAt: new Date().toISOString(),
-        origin: 'agent',
-        actor: defaultActor(request.actor),
-        subject: request.subject,
-        causationId: intentEventId,
-        correlationId: intentEventId,
-        ...(status === 'success' && outcome
-            ? {
-                external: {
-                    provider: request.provider,
-                    id: outcome.externalId,
-                    ...(outcome.url ? { url: outcome.url } : {}),
-                },
-            }
-            : {}),
-        data: {
-            operation: request.operation,
-            provider: request.provider,
-            egressKey: request.idempotencyKey,
-            status,
-            attempt,
-            ...(outcome?.data ?? {}),
-            ...(error ? { error } : {}),
-        },
-    });
-    return appendEvent(result, root).event;
-}
-function replayOutcome(result) {
-    const { operation: _operation, provider: _provider, egressKey: _key, status: _status, attempt: _attempt, ...rest } = result.data;
-    return {
-        externalId: result.external?.id ?? '',
-        ...(result.external?.url ? { url: result.external.url } : {}),
-        data: rest,
-    };
-}
-// TWIN-58: same-process in-flight de-dup, keyed by (root, service, intentId). Two
-// callers racing the SAME idempotencyKey must invoke writeFn exactly once between
-// them; the SECOND caller awaits the FIRST's outcome and replays it rather than
-// redoing (or erroring out of) its own ledger-check. Populated synchronously,
-// before the first `await` in the winning call, so a caller that starts executing
-// immediately after (same microtask turn or later) is guaranteed to observe it.
-const inFlightWrites = new Map();
-function inFlightKey(service, intentId, root) {
-    return `${root ?? ''}:${service}:${intentId}`;
-}
-/**
- * Perform an external write through the egress ledger.
- *
- * Ordering: a write.intent event is durably appended BEFORE the provider call,
- * and a write.result event is appended after it (success or failure). A crash
- * between the two leaves an intent without results; by default the next call
- * with the same idempotencyKey refuses to re-send (UnreconciledWriteIntentError)
- * because the provider may or may not have applied the write. After verifying
- * the external state, callers retry with onUnreconciled: 'retry'.
- *
- * A ledger entry with a success result is terminal: the call returns the
- * recorded outcome without invoking writeFn. Failed attempts may be retried;
- * each attempt appends its own numbered result event.
- *
- * Concurrency (TWIN-58): the ledger-check + intent-append span runs under
- * `withFileLock` on the SAME events lock `appendEvent` itself uses (egress.ts has
- * no lock of its own to invent — reusing the events lock is what makes this
- * atomic against a concurrent appendEvent/commitQueuedEvents too, not just a
- * concurrent performExternalWrite). Without this, two concurrent calls with the
- * same idempotencyKey could both read "no entry" and both invoke writeFn — the
- * vendor receiving the write twice despite this function's contract that a
- * completed write is replayed, never re-sent (see actions.ts:121-123 for the same
- * check-then-append-under-one-lock reasoning applied to the action log). The
- * `writeFn` call itself deliberately stays OUTSIDE the lock (it's arbitrary,
- * possibly slow, real I/O — holding a file lock across it would serialize every
- * write to the service, not just same-key ones); `inFlightWrites` covers the
- * in-process race for the span the lock can't (an async call can't hold a
- * synchronous lock across its own `await`).
- */
-export async function performExternalWrite(request, writeFn, options = {}) {
-    const { root, onUnreconciled = 'fail' } = options;
-    const hash = egressHash(request);
-    const intentId = `${request.service}${WRITE_INTENT_SUFFIX}:${hash}`;
-    const flightKey = inFlightKey(request.service, intentId, root);
-    // Another in-process call already owns this idempotencyKey's write — replay its
-    // outcome (or its failure) instead of racing it.
-    const inFlight = inFlightWrites.get(flightKey);
-    if (inFlight) {
-        const settled = await inFlight;
-        return { ...settled, status: 'replayed' };
-    }
-    const paths = worldPaths(request.service, root);
-    const claim = withFileLock(eventsLockPath(paths), () => {
-        const ledger = ledgerFor(request.service, root);
-        const existing = ledger.get(intentId);
-        if (existing) {
-            const success = existing.results.find((result) => result.data.status === 'success');
-            if (success) {
-                return {
-                    replay: {
-                        status: 'replayed',
-                        intentEventId: intentId,
-                        resultEventId: success.id,
-                        attempt: Number(success.data.attempt) || existing.results.length,
-                        outcome: replayOutcome(success),
-                    },
-                };
-            }
-            if (existing.results.length === 0 && onUnreconciled === 'fail') {
-                throw new UnreconciledWriteIntentError(intentId, `Write intent ${intentId} has no result event — the provider call may or may not have happened. ` +
-                    `Verify external state, then retry with onUnreconciled: 'retry'.`);
-            }
-        }
-        const intent = existing?.intent ?? appendEventLocked(buildIntentEvent(request), paths).event;
-        const attempt = (existing?.results.length ?? 0) + 1;
-        return { intent, attempt };
-    });
-    if ('replay' in claim)
-        return claim.replay;
-    const { intent, attempt } = claim;
-    // Register the in-flight promise BEFORE the first await below (synchronous from
-    // here), so a same-process concurrent call for this key — however soon it runs —
-    // finds it rather than re-entering the lock/ledger-check itself.
-    let resolveFlight;
-    let rejectFlight;
-    const flight = new Promise((resolve, reject) => {
-        resolveFlight = resolve;
-        rejectFlight = reject;
-    });
-    // A rejection here is only ever "unhandled" when no concurrent caller happened to
-    // be waiting on this exact key — the normal (non-concurrent) case. Attach a no-op
-    // handler so that case doesn't surface as an unhandled rejection; a real waiter
-    // (the `await inFlight` above) still observes the SAME rejection independently.
-    flight.catch(() => { });
-    inFlightWrites.set(flightKey, flight);
-    try {
-        let outcome;
-        try {
-            outcome = await writeFn();
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            recordWriteResult({ request, intentEventId: intent.id, attempt, status: 'failed', error: message, root });
-            rejectFlight(error);
-            throw error;
-        }
-        const result = recordWriteResult({ request, intentEventId: intent.id, attempt, status: 'success', outcome, root });
-        const performed = {
-            status: 'performed',
-            intentEventId: intent.id,
-            resultEventId: result.id,
-            attempt,
-            outcome,
-        };
-        resolveFlight(performed);
-        return performed;
-    }
-    finally {
-        inFlightWrites.delete(flightKey);
-    }
-}
-/** Intents with no result event at all — crash candidates needing reconciliation. */
-export function listUnreconciledWriteIntents(service, root) {
-    return Array.from(ledgerFor(service, root).values())
-        .filter((entry) => entry.results.length === 0)
-        .map((entry) => entry.intent);
-}
-/** Full intent/result ledger for a service, keyed by intent event id. */
-export function listEgressLedger(service, root) {
-    return Array.from(ledgerFor(service, root).values());
-}
-/**
- * Echo lookup: did we produce this external object? Inbound events whose
- * external id matches a recorded successful write are our own writes coming back.
- */
-export function findWriteResultByExternal(service, provider, externalId, root) {
-    for (const event of listEvents(service, root)) {
-        if (!event.type.endsWith(WRITE_RESULT_SUFFIX))
-            continue;
-        if (event.data.status !== 'success')
-            continue;
-        if (event.external?.provider === provider && event.external.id === externalId)
-            return event;
-    }
-    return null;
-}