@opendatalabs/personal-server-ts-core 1.34.2 → 1.35.1

package/dist/replication/coordinator-state.test-utils.js

@@ -0,0 +1,113 @@
+import { ReplicaCoordinatorConflict, } from "./coordinator.js";
+/** Sequence without awaiting, so a synchronous harness stays synchronous. */
+const then = (value, next) => value instanceof Promise ? value.then(next) : next(value);
+export function replicaCoordinatorStateContract({ test, expect }, open) {
+    const check = (name, run) => test(name, async () => {
+        const h = await open();
+        try {
+            await run(h);
+        }
+        finally {
+            await h.close();
+        }
+    });
+    /** Expect `run` to throw or reject, optionally with a type or message. */
+    async function throws(run, expected) {
+        let thrown;
+        try {
+            await run();
+        }
+        catch (error) {
+            thrown = error ?? new Error("thrown nullish");
+        }
+        expect(thrown !== undefined).toBe(true);
+        if (typeof expected === "string")
+            expect(String(thrown.message).includes(expected)).toBe(true);
+        else if (expected)
+            expect(thrown instanceof expected).toBe(true);
+    }
+    /** One commit through either port kind, awaiting what is asynchronous. */
+    async function commit(port, expected, next, checkpoint) {
+        if ("async" in port && port.async)
+            return port.commit(expected, next, async (context) => checkpoint(context));
+        return port.commit(expected, next, () => {
+            const result = checkpoint(undefined);
+            if (result instanceof Promise)
+                throw new Error("synchronous harness returned a promise");
+            return result;
+        });
+    }
+    const rotation = {
+        nextPhase: "import",
+        writers: { publish: "writer-a" },
+    };
+    check("persists cursor, checkpoint and revision together across adapter recreation", async (h) => {
+        await h.acquire("a");
+        const port = h.port("a");
+        const initial = await port.load();
+        expect(initial.version).toBe(0);
+        expect(initial.writers).toEqual({});
+        const committed = await commit(port, initial, rotation, (tx) => then(h.checkpoint("one", tx), () => 7));
+        expect(committed.result).toBe(7);
+        expect(await h.receipts()).toEqual(["one"]);
+        expect(await h.port("a").load()).toEqual({
+            ...rotation,
+            owner: "a",
+            version: 1,
+        });
+        committed.state.writers.publish = "mutated-return";
+        expect((await h.port("a").load()).writers.publish).toBe("writer-a");
+    });
+    check("a throwing checkpoint rolls back both receipt and cursor", async (h) => {
+        await h.acquire("a");
+        const port = h.port("a");
+        const initial = await port.load();
+        await throws(() => commit(port, initial, rotation, (tx) => then(h.checkpoint("lost", tx), () => {
+            throw new Error("rollback");
+        })), "rollback");
+        expect(await h.receipts()).toEqual([]);
+        expect(await port.load()).toEqual(initial);
+    });
+    check("a cursor-write failure cannot leave a durable receipt", async (h) => {
+        await h.acquire("a");
+        const port = h.port("a");
+        const initial = await port.load();
+        await h.failCursorWrites(true);
+        await throws(() => commit(port, initial, rotation, (tx) => h.checkpoint("lost", tx)));
+        expect(await h.receipts()).toEqual([]);
+        expect(await port.load()).toEqual(initial);
+        await h.failCursorWrites(false);
+        await commit(port, initial, rotation, (tx) => h.checkpoint("retry", tx));
+        expect(await h.receipts()).toEqual(["retry"]);
+        expect((await port.load()).version).toBe(1);
+    });
+    check("a stale revision never runs a checkpoint", async (h) => {
+        await h.acquire("a");
+        const port = h.port("a");
+        const old = await port.load();
+        await commit(port, old, rotation, (tx) => h.checkpoint("new", tx));
+        await throws(() => commit(port, old, rotation, (tx) => h.checkpoint("stale", tx)), ReplicaCoordinatorConflict);
+        expect(await h.receipts()).toEqual(["new"]);
+    });
+    check("active owners contend; a recovered owner rejects old receipts", async (h) => {
+        await h.acquire("a");
+        const old = await h.port("a").load();
+        await throws(() => h.acquire("b"));
+        await throws(() => h.port("b").load(), ReplicaCoordinatorConflict);
+        await h.recover("b");
+        const next = h.port("b");
+        await commit(next, await next.load(), rotation, (tx) => h.checkpoint("b", tx));
+        await throws(() => commit(h.port("a"), old, rotation, (tx) => h.checkpoint("late-a", tx)), ReplicaCoordinatorConflict);
+        expect(await h.receipts()).toEqual(["b"]);
+        expect((await next.load()).version).toBe(1);
+    });
+    check("ownership changed inside a checkpoint rolls back the whole transaction", async (h) => {
+        await h.acquire("a");
+        const port = h.port("a");
+        const initial = await port.load();
+        await throws(() => commit(port, initial, rotation, (tx) => then(h.checkpoint("lost", tx), () => h.recover("b", tx))), ReplicaCoordinatorConflict);
+        expect(await h.receipts()).toEqual([]);
+        expect(await port.load()).toEqual(initial);
+    });
+}
+//# sourceMappingURL=coordinator-state.test-utils.js.map

package/dist/replication/coordinator-state.test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-state.test-utils.js","sourceRoot":"","sources":["../../src/replication/coordinator-state.test-utils.ts"],"names":[],"mappings":"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"}

package/dist/replication/coordinator.d.ts

@@ -0,0 +1,264 @@
+import { type ReplicaAdmission, type ReplicaCause, type ReplicaDependency, type ReplicaOutcome, type ReplicaPhase, type ReplicaPhaseOutcome, type ReplicaProblem, type ReplicaQuarantineProof, type ReplicaReceipt } from "./outcome.js";
+import { type ReplicaBackoff, type ReplicaEligibility, type ReplicaWorkState } from "./schedule.js";
+type MaybePromise<T> = T | Promise<T>;
+export interface ReplicaWorkItem {
+    id: string;
+    phase: ReplicaPhase;
+    writer: string;
+    state: ReplicaWorkState;
+    /** Admission estimate for byte budgets. */
+    bytes?: number;
+    /**
+     * The resumable unit this attempt covers, e.g. the next fragment of a
+     * batch. A step admits an item once per part, so an item that commits one
+     * unit per attempt can take further units in the same step, each charged
+     * on its own. Runs of one item never overlap, whatever their part.
+     */
+    part?: string;
+}
+/**
+ * The result of one attempt. `plan` is this attempt's transactional effect
+ * (checkpoint, receipt, custody). It runs only inside the commit of this very
+ * attempt, so a discarded attempt (deadline, abort) leaves no trace. A plan
+ * may refine the verdict from what it committed.
+ */
+export interface ReplicaAttempt<P = () => ReplicaPhaseOutcome | void> {
+    outcome: ReplicaPhaseOutcome;
+    /** Node plans are callbacks; shared-engine plans are storage effects. */
+    plan?: P;
+    /** Release short-lived resources after this attempt is committed or discarded. */
+    release?: () => void;
+}
+/** Turns a verdict into its durable outcome and state, at settlement time. */
+export type ReplicaSettle = (verdict: ReplicaPhaseOutcome) => {
+    outcome: ReplicaOutcome;
+    state: ReplicaWorkState;
+};
+/**
+ * One phase's durable work: a storage adapter. The coordinator owns the
+ * clock, eligibility, budgets, deadlines and transitions; the adapter owns
+ * selection SQL rendered from the shared eligibility policy and atomic
+ * persistence.
+ */
+export interface ReplicaPhaseHandler<I extends ReplicaWorkItem = ReplicaWorkItem> {
+    phase: ReplicaPhase;
+    /**
+     * Eligible items (see replicaEligibleAt): at most perWriter per writer,
+     * every writer's first item before any writer's second, and writers in
+     * cyclic order starting after `after` (the writer this phase served last).
+     * Oldest first within a writer.
+     */
+    due(eligibility: ReplicaEligibility, limit: {
+        total: number;
+        perWriter: number;
+        after?: string;
+    }): I[];
+    /** Must honour `signal`: after abort it performs no further effect. */
+    run(item: I, signal: AbortSignal): Promise<ReplicaAttempt>;
+    /**
+     * In ONE transaction: run `attempt.plan` (if any), settle the verdict with
+     * `settle`, persist outcome and state. Return the persisted outcome. A throw
+     * persists nothing.
+     */
+    commit(item: I, attempt: ReplicaAttempt, settle: ReplicaSettle): ReplicaOutcome;
+    /** Problem recorded when a plan's transaction fails. */
+    commitProblem?: ReplicaProblem;
+    /**
+     * Earliest eligibility of this phase's durable deadlines (retries, waits),
+     * by the same policy as `due`; undefined when none. Polling sources and
+     * sweeps that run on the host's cadence report only their deadlines.
+     */
+    earliest(eligibility: ReplicaEligibility): number | undefined;
+    /** Make waits on this dependency key due now. Idempotent. */
+    wake?(key: string, now: number): number;
+}
+/**
+ * A phase handler whose storage may answer asynchronously (PS-Lite's native
+ * transaction). A handler that returns plain values runs exactly as a
+ * synchronous one: the coordinator awaits only what is a promise.
+ */
+export interface AsyncReplicaPhaseHandler<I extends ReplicaWorkItem = ReplicaWorkItem, C = unknown, P = unknown> {
+    phase: ReplicaPhase;
+    /**
+     * Eligible items (see replicaEligibleAt): at most perWriter per writer,
+     * every writer's first item before any writer's second, and writers in
+     * cyclic order starting after `after` (the writer this phase served last).
+     * Oldest first within a writer.
+     */
+    due(eligibility: ReplicaEligibility, limit: {
+        total: number;
+        perWriter: number;
+        after?: string;
+    }): MaybePromise<I[]>;
+    /** Must honour `signal`: after abort it performs no further effect. */
+    run(item: I, signal: AbortSignal): Promise<ReplicaAttempt<P>>;
+    /**
+     * In ONE transaction: run `attempt.plan` (if any), settle the verdict with
+     * `settle`, persist outcome and state. Return the persisted outcome. A throw
+     * persists nothing. `context` is the durable state port's transaction,
+     * so the attempt and the rotation commit together.
+     */
+    commit(item: I, attempt: ReplicaAttempt<P>, settle: ReplicaSettle, context: C): MaybePromise<ReplicaOutcome>;
+    /** Problem recorded when a plan's transaction fails. */
+    commitProblem?: ReplicaProblem;
+    /**
+     * Earliest eligibility of this phase's durable deadlines (retries, waits),
+     * by the same policy as `due`; undefined when none. Polling sources and
+     * sweeps that run on the host's cadence report only their deadlines.
+     */
+    earliest(eligibility: ReplicaEligibility): MaybePromise<number | undefined>;
+    /** Make waits on this dependency key due now. Idempotent. */
+    wake?(key: string, now: number): MaybePromise<number>;
+}
+/** A finalized-head hint source. Optional: it can only park finality waits. */
+export interface ReplicaHintPort {
+    head(signal: AbortSignal): Promise<bigint>;
+}
+/**
+ * Await `start()` unless `signal` aborts first. After abort the caller sees a
+ * rejection at once, so it performs no further effect; the underlying call
+ * may still finish, and its value is dropped.
+ */
+export declare function abortable<T>(signal: AbortSignal, start: () => Promise<T>): Promise<T>;
+export interface ReplicaBudget {
+    /** Positive safe integer. Counts admitted attempts, not all storage work. */
+    units: number;
+    /** Positive safe integer; omitted means the finite default below. */
+    bytes?: number;
+}
+export declare const REPLICA_STEP_BYTES: number;
+export declare const REPLICA_REPORT_LIMIT = 256;
+export declare const REPLICA_ATTEMPT_TIMEOUT_MS = 30000;
+export interface ReplicaStep {
+    /** Nonnegative safe-integer milliseconds on the host's scheduling clock. */
+    now: number;
+    budget: ReplicaBudget;
+    signal?: AbortSignal;
+}
+/** Validate before storage, hints, selection or any other effect. */
+export declare function validateReplicaStep(context: ReplicaStep): void;
+/** Stable phase names survive a reordered host construction across restart. */
+export interface ReplicaRotation {
+    nextPhase?: ReplicaPhase;
+    writers: Partial<Record<ReplicaPhase, string>>;
+}
+export interface ReplicaCoordinatorState extends ReplicaRotation {
+    /** Opaque exclusive-owner fence, never a PID or wall-clock lease in core. */
+    owner: string;
+    /** Monotonic compare-and-swap revision within this durable repository. */
+    version: number;
+}
+export declare class ReplicaCoordinatorConflict extends Error {
+    constructor();
+}
+/**
+ * A host adapter must use the SAME transaction for `checkpoint` and rotation.
+ * Check current ownership and revision before calling checkpoint, and again
+ * before commit. On any throw, neither the checkpoint nor cursor may persist.
+ * The callback is synchronous and must not escape or run after commit returns.
+ * Every adapter must pass `replicaCoordinatorStateContract`.
+ */
+export interface ReplicaCoordinatorStatePort {
+    load(): ReplicaCoordinatorState;
+    commit<T>(expected: ReplicaCoordinatorState, next: ReplicaRotation, checkpoint: () => T): {
+        state: ReplicaCoordinatorState;
+        result: T;
+    };
+}
+/**
+ * The same port over an asynchronous transaction (PS-Lite's native one).
+ * `checkpoint` receives that transaction and the port awaits it before the
+ * rotation is written; the same ownership, revision and rollback rules
+ * apply. The callback must not escape or run after commit settles.
+ */
+export interface AsyncReplicaCoordinatorStatePort<C> {
+    readonly async: true;
+    load(): Promise<ReplicaCoordinatorState>;
+    commit<T>(expected: ReplicaCoordinatorState, next: ReplicaRotation, checkpoint: (context: C) => Promise<T>): Promise<{
+        state: ReplicaCoordinatorState;
+        result: T;
+    }>;
+}
+/** Thrown when a synchronous port is handed an asynchronous checkpoint. */
+export declare class ReplicaAsyncCheckpointError extends Error {
+    constructor();
+}
+export interface ProgressReport {
+    /** Diagnostics may be incomplete because the fixed entry cap was reached. */
+    diagnosticsTruncated?: boolean;
+    receipts: ReplicaReceipt[];
+    waits: {
+        id: string;
+        phase: ReplicaPhase;
+        dependency: ReplicaDependency;
+        ageMs?: number;
+    }[];
+    problems: {
+        id: string;
+        phase: ReplicaPhase;
+        problem: ReplicaProblem;
+        cause?: ReplicaCause;
+        nextEligible: number;
+    }[];
+    quarantines: {
+        id: string;
+        phase: ReplicaPhase;
+        proof: ReplicaQuarantineProof;
+    }[];
+    unsupported: {
+        id: string;
+        phase: ReplicaPhase;
+        admission: ReplicaAdmission;
+    }[];
+    /** `now` when admitted work remains; else the earliest durable deadline. */
+    nextWake: number | undefined;
+}
+/** Options shared by both coordinator factories. */
+export interface ReplicaCoordinatorOptions {
+    quantum?: Partial<Record<ReplicaPhase, number>>;
+    /** Items per writer in one selection round. Defaults to one. */
+    perWriter?: number;
+    backoff?: ReplicaBackoff;
+    /** Settlement clock. Defaults to the step's `now`. */
+    clock?: () => number;
+    /** Optional finalized-head hint, read at most every `hintRefreshMs`. */
+    hint?: ReplicaHintPort;
+    hintRefreshMs?: number;
+    /** Positive integer per-run timeout in ms (default 30s); late results are discarded. */
+    deadlineMs?: number;
+    /**
+     * Sweeps that are never finished (e.g. revalidating imported slots). Under
+     * a finite budget they keep their reserved share but take leftover units
+     * only after every other phase, so a sweep cannot crowd out progress.
+     */
+    background?: readonly ReplicaPhase[];
+}
+/**
+ * Selects due work fairly and turns phase verdicts into durable transitions.
+ * The host schedules step(); it never runs another semantic retry loop.
+ */
+export declare function createReplicaCoordinator(input: ReplicaCoordinatorOptions & {
+    phases: ReplicaPhaseHandler[];
+    /** Required for restart fairness; omission is an in-memory-only test seam. */
+    state?: ReplicaCoordinatorStatePort;
+}): {
+    step: (context: ReplicaStep) => Promise<ProgressReport>;
+    onDependencyChanged(key: string, now: number): number;
+};
+/**
+ * The coordinator over handlers and a state port that may answer
+ * asynchronously. Plain values keep the synchronous path, so a synchronous
+ * host (Node) behaves exactly as under `createReplicaCoordinator`. With a
+ * synchronous port, an asynchronous checkpoint is refused inside its
+ * transaction, never committed half-done.
+ */
+export declare function createAsyncReplicaCoordinator<C>(input: ReplicaCoordinatorOptions & {
+    phases: AsyncReplicaPhaseHandler<any, C, any>[];
+    /** Required for restart fairness; omission is an in-memory-only test seam. */
+    state?: ReplicaCoordinatorStatePort | AsyncReplicaCoordinatorStatePort<C>;
+}): {
+    step(context: ReplicaStep): Promise<ProgressReport>;
+    onDependencyChanged(key: string, now: number): MaybePromise<number>;
+};
+export {};
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/replication/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../src/replication/coordinator.ts"],"names":[],"mappings":"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"}