@volter/twin 0.1.0

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

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

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

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

@@ -0,0 +1,264 @@
+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;
+}

package/dist/src/fork.d.ts

@@ -0,0 +1,126 @@
+import type { TwinAction } from './actions.js';
+import type { TwinResource } from './serve.js';
+import type { WorldServiceEvent } from './types.js';
+export type ForkMeta = {
+    service: string;
+    forkedAt: string;
+    baseRoot: string;
+    baseEventCount: number;
+    baseLatestEventId: string | null;
+    baseline: TwinResource[];
+};
+/**
+ * Create a fork of `service` from `fromRoot` into the fresh isolated `toRoot`.
+ * Copies the base event log so the fork folds to identical state, then records
+ * the baseline. `occurredAt` is supplied by the caller (deterministic; no clock).
+ */
+export declare function forkTwin(opts: {
+    service: string;
+    toRoot: string;
+    fromRoot?: string;
+    occurredAt: string;
+}): ForkMeta;
+export declare function readForkMeta(service: string, root: string): ForkMeta;
+export declare function isFork(service: string, root: string): boolean;
+export type FieldDivergence = {
+    before: unknown;
+    after: unknown;
+};
+export type SubjectDivergence = {
+    id: string;
+    type: string;
+    changed: Record<string, FieldDivergence>;
+};
+export type ForkDivergence = {
+    service: string;
+    baseCount: number;
+    currentCount: number;
+    created: TwinResource[];
+    changed: SubjectDivergence[];
+};
+/** What changed in the fork relative to its recorded base. */
+export declare function forkDivergence(service: string, forkRoot: string): ForkDivergence;
+export type ForkAudit = {
+    ok: boolean;
+    localActions: number;
+    realWrites: number;
+    breaches: string[];
+};
+/**
+ * Report whether the fork has made any real write SO FAR (R18 model + TWIN-52):
+ * local fork work lives in the ACTION log and never reaches the vendor on its
+ * own, so a real write can only have happened through one of the two channels
+ * that touch the vendor —
+ *   - the egress ledger (`performExternalWrite`, and `syncPush` which is built
+ *     on it): any entry there is a completed or attempted direct write.
+ *   - the push ledger (`pushTransaction`, and `applyPlan` which drives it): any
+ *     row whose status reached `attempted` or further is a real provider call
+ *     that was made (or is unreconciled — see UnreconciledPushError — which is
+ *     itself "may have happened", so it counts as a breach too).
+ * Reading only the egress ledger (the old implementation) missed the push
+ * channel entirely: a fork that pushed via `applyPlan`/`pushTransaction` (the
+ * canonical arc in examples/lifecycle.ts) audited as `{ok:true, realWrites:0}`,
+ * a fabricated green. This is a checkable AUDIT of what happened, not a
+ * guarantee that nothing can — pushing for real from a fork is a supported
+ * operation, not a violation.
+ */
+export declare function auditForkNoRealWrites(service: string, forkRoot: string): ForkAudit;
+/** Remove a fork root entirely (the fork is throwaway by design). */
+export declare function discardFork(forkRoot: string): void;
+export type CopyResult = {
+    copied: TwinAction[];
+    conflicts: Array<{
+        actionId: string;
+        reason: string;
+    }>;
+};
+/**
+ * cherry-pick: copy selected `set` transaction commits from one fork into another.
+ * A commit whose precondition fails in the target is reported as a conflict, not
+ * applied (the rest still copy).
+ */
+export declare function cherryPickActions(opts: {
+    service: string;
+    fromRoot: string;
+    toRoot: string;
+    actionIds: string[];
+    occurredAt: string;
+}): CopyResult;
+/**
+ * merge: combine another fork's ACTIVE (pending) transaction history into this one.
+ * Requires compatible bases (same base latest-event id) unless `force`. Failed
+ * preconditions surface as conflicts.
+ */
+export declare function mergeForks(opts: {
+    service: string;
+    intoRoot: string;
+    fromRoot: string;
+    occurredAt: string;
+    force?: boolean;
+}): CopyResult;
+/**
+ * reset: suppress all local projections non-destructively by appending a revert for
+ * every pending transaction (history is retained — unlike discardFork, which deletes
+ * the root). Returns how many transactions were reset.
+ */
+export declare function resetFork(opts: {
+    service: string;
+    root: string;
+    occurredAt: string;
+}): number;
+/**
+ * rebase: commit fresh remote observations onto the fork's base, then replay active
+ * local transactions over the new base. Transactions whose preconditions now fail
+ * are returned as conflicts (the doc's "failed preconditions become conflicts").
+ */
+export declare function rebaseFork(opts: {
+    service: string;
+    root: string;
+    freshEvents: WorldServiceEvent[];
+}): {
+    applied: number;
+    conflicts: Array<{
+        actionId: string;
+        reason: string;
+    }>;
+};