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

package/dist/replication/outcome.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Closed outcome algebra for replication work. Every phase of the durable
+ * coordinator returns exactly one of these. Diagnostics are closed codes and
+ * bounded cause chains: exception text never crosses this boundary.
+ */
+import type { ReplicaAuthorityRefusal } from "./writer-identity.js";
+export type ReplicaPhase = "retain" | "prepare" | "publish" | "discover" | "download" | "fetch" | "revalidate" | "import" | "reconcile";
+/** What a Wait waits for. A key is stable across restarts. */
+export type ReplicaDependency = {
+    kind: "registration";
+    key: string;
+    reason: "own_key_conflict" | "version_squat";
+} | {
+    kind: "predecessor";
+    key: string;
+} | {
+    kind: "finality";
+    key: string;
+    checkedBlock: string;
+}
+/** A writer's registration intent is unresolved at this publication slot. */
+ | {
+    kind: "registration_pending";
+    key: string;
+    version: number;
+    since: number;
+    checkedBlock?: string;
+    /** Next evidence check for a successor waiting on this registration. */
+    nextCheckAt?: number;
+}
+/** Sender preparation cannot proceed; unknown failures still use Retry backoff. */
+ | {
+    kind: "preparation";
+    key: string;
+    reason: "unknown" | "upload_started" | "all_ops_unsupported";
+} | {
+    kind: "fragments";
+    key: string;
+} | {
+    kind: "mapping";
+    key: string;
+} | {
+    kind: "declaration";
+    key: string;
+} | {
+    kind: "blob";
+    key: string;
+} | {
+    kind: "reset";
+    key: string;
+}
+/** The gateway roster for a server address could not be read. */
+ | {
+    kind: "roster";
+    key: string;
+}
+/**
+ * Every retained copy of a batch is disproved and the refetch budget is
+ * spent (copy_conflict_unresolved). A new finalized fact for the batch
+ * wakes it; otherwise only the owner can resolve it.
+ */
+ | {
+    kind: "owner";
+    key: string;
+};
+export declare const dependencyKey: (dependency: ReplicaDependency) => string;
+/** Why a transient attempt failed. Never exception text. */
+export type ReplicaProblem = "evidence_unavailable" | "registration_unconfirmed" | "head_unavailable" | "publish_failed" | "download_failed" | "resource_busy" | "commitment_mismatch" | "payload_invalid" | "import_failed" | "prepare_failed" | "retain_failed" | "discovery_failed" | "reconcile_failed" | "deadline_exceeded" | "storage_failed" | "unknown";
+/** Error class name plus optional code per level, at most four levels deep. */
+export interface ReplicaCause {
+    name: string;
+    code?: string;
+    cause?: ReplicaCause;
+}
+/** Structured, bounded cause chain. Reads class names and codes, never messages. */
+export declare function replicaCause(error: unknown, depth?: number): ReplicaCause;
+/** A failure whose closed problem code the thrower knows. */
+export declare class ReplicaProblemError extends Error {
+    readonly problem: ReplicaProblem;
+    readonly code: ReplicaProblem;
+    constructor(problem: ReplicaProblem, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A framing Unsupported, separate from sender input and resource admission.
+ * Thrown where encrypted framing exceeds the storage cap. The preparer may retry a
+ * smaller chunk size; at the smallest size framing is proven impossible.
+ */
+export declare class ReplicaFramingUnsupported extends Error {
+    readonly actual: number;
+    readonly limit: number;
+    /**
+     * fragment_bytes: one encrypted fragment exceeds the cap. fragment_count:
+     * too many fragments. manifest_bytes: the encrypted manifest exceeds the cap.
+     */
+    readonly dimension: "fragment_bytes" | "fragment_count" | "manifest_bytes";
+    readonly code = "replica_framing_unsupported";
+    constructor(actual: number, limit: number, 
+    /**
+     * fragment_bytes: one encrypted fragment exceeds the cap. fragment_count:
+     * too many fragments. manifest_bytes: the encrypted manifest exceeds the cap.
+     */
+    dimension?: "fragment_bytes" | "fragment_count" | "manifest_bytes");
+}
+export type ReplicaAdmission = {
+    reason: "operation_encoding_unsupported";
+} | {
+    reason: "replica_framing_unsupported";
+    actual: number;
+    limit: number;
+    /** The admitted capability the decision was measured against. */
+    capability: string;
+} | {
+    reason: "resource_unsupported";
+    limit: string;
+    limitsVersion: number;
+};
+export interface ReplicaQuarantineProof {
+    reason: "immutable_registration_conflict"
+    /** Finalized facts contradict a batch, or its writer chain is terminal. */
+     | "finalized_conflict" | "batch_equivocation" | "source_binding_conflict" | "local_mapping_conflict"
+    /**
+     * A finalized manifest is over the storage cap, compressed, outside the
+     * writers' OpenPGP profile or the JSON bounds, or its authentic bytes
+     * decode to an invalid statement.
+     */
+     | "manifest_invalid"
+    /**
+     * Storage has no object at a fragment address of a finalized manifest.
+     * Storage reads are strongly consistent and the writer stores every
+     * fragment before it registers the manifest.
+     */
+     | "fragment_missing"
+    /** Fetched fragment bytes or their content disagree with the finalized manifest. */
+     | "fragment_mismatch"
+    /** Writer authority (host contract §3.4). None of these touch writer state. */
+     | ReplicaAuthorityRefusal;
+    key: string;
+}
+export interface ReplicaReceipt {
+    phase: ReplicaPhase;
+    key: string;
+}
+/** A phase verdict. Retry has no deadline yet: the schedule assigns it. */
+export type ReplicaPhaseOutcome = {
+    tag: "progress";
+    receipt: ReplicaReceipt;
+} | {
+    tag: "wait";
+    dependency: ReplicaDependency;
+} | {
+    tag: "retry";
+    problem: ReplicaProblem;
+    cause?: ReplicaCause;
+} | {
+    tag: "quarantine";
+    proof: ReplicaQuarantineProof;
+} | {
+    tag: "unsupported";
+    admission: ReplicaAdmission;
+};
+/** The durable outcome after scheduling. */
+export type ReplicaOutcome = Exclude<ReplicaPhaseOutcome, {
+    tag: "retry";
+}> | {
+    tag: "retry";
+    problem: ReplicaProblem;
+    cause?: ReplicaCause;
+    nextEligible: number;
+};
+/** The persisted reason code of an outcome. */
+export declare function outcomeReason(outcome: ReplicaPhaseOutcome): string;
+/** Map any thrown value to Retry. Only a typed problem code chooses the problem. */
+export declare function retryFromError(error: unknown, fallback: ReplicaProblem): Extract<ReplicaPhaseOutcome, {
+    tag: "retry";
+}>;
+//# sourceMappingURL=outcome.d.ts.map

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

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

package/dist/replication/outcome.js

@@ -0,0 +1,83 @@
+/**
+ * Closed outcome algebra for replication work. Every phase of the durable
+ * coordinator returns exactly one of these. Diagnostics are closed codes and
+ * bounded cause chains: exception text never crosses this boundary.
+ */
+export const dependencyKey = (dependency) => `${dependency.kind}:${dependency.key}`;
+const MAX_CAUSE_DEPTH = 4;
+const safe = (value) => value.replace(/[^\w.:-]/g, "").slice(0, 64);
+/** Structured, bounded cause chain. Reads class names and codes, never messages. */
+export function replicaCause(error, depth = 1) {
+    if (!(error instanceof Error))
+        return { name: error === null ? "null" : typeof error };
+    const code = error.code;
+    const cause = error.cause;
+    return {
+        name: safe(error.name) || "Error",
+        ...((typeof code === "string" || typeof code === "number") && {
+            code: safe(String(code)),
+        }),
+        ...(cause !== undefined &&
+            depth < MAX_CAUSE_DEPTH && { cause: replicaCause(cause, depth + 1) }),
+    };
+}
+/** A failure whose closed problem code the thrower knows. */
+export class ReplicaProblemError extends Error {
+    problem;
+    code;
+    constructor(problem, options) {
+        super(problem, options);
+        this.problem = problem;
+        this.name = "ReplicaProblemError";
+        this.code = problem;
+    }
+}
+/**
+ * A framing Unsupported, separate from sender input and resource admission.
+ * Thrown where encrypted framing exceeds the storage cap. The preparer may retry a
+ * smaller chunk size; at the smallest size framing is proven impossible.
+ */
+export class ReplicaFramingUnsupported extends Error {
+    actual;
+    limit;
+    dimension;
+    code = "replica_framing_unsupported";
+    constructor(actual, limit, 
+    /**
+     * fragment_bytes: one encrypted fragment exceeds the cap. fragment_count:
+     * too many fragments. manifest_bytes: the encrypted manifest exceeds the cap.
+     */
+    dimension = "fragment_bytes") {
+        super("replica_framing_unsupported");
+        this.actual = actual;
+        this.limit = limit;
+        this.dimension = dimension;
+        this.name = "ReplicaFramingUnsupported";
+    }
+}
+/** The persisted reason code of an outcome. */
+export function outcomeReason(outcome) {
+    switch (outcome.tag) {
+        case "progress":
+            return outcome.receipt.phase;
+        case "wait":
+            return outcome.dependency.kind === "registration"
+                ? outcome.dependency.reason
+                : outcome.dependency.kind;
+        case "retry":
+            return outcome.problem;
+        case "quarantine":
+            return outcome.proof.reason;
+        case "unsupported":
+            return outcome.admission.reason;
+    }
+}
+/** Map any thrown value to Retry. Only a typed problem code chooses the problem. */
+export function retryFromError(error, fallback) {
+    return {
+        tag: "retry",
+        problem: error instanceof ReplicaProblemError ? error.problem : fallback,
+        cause: replicaCause(error),
+    };
+}
+//# sourceMappingURL=outcome.js.map

package/dist/replication/outcome.js.map

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

package/dist/replication/payload.d.ts

@@ -0,0 +1,39 @@
+import { type ReplicaEffect } from "./effects.js";
+export declare const REPLICA_PAYLOAD_CHUNK_BYTES: number;
+/** The tables, for a host whose storage does not create them already. */
+export declare const REPLICA_PAYLOAD_MIGRATION = "\nCREATE TABLE IF NOT EXISTS pdpp_binary_manifests (\n namespace TEXT NOT NULL, blob_id TEXT NOT NULL, size_bytes INTEGER NOT NULL,\n PRIMARY KEY(namespace,blob_id));\nCREATE TABLE IF NOT EXISTS pdpp_binary_chunks (\n namespace TEXT NOT NULL, blob_id TEXT NOT NULL, position INTEGER NOT NULL, bytes BLOB NOT NULL,\n PRIMARY KEY(namespace,blob_id,position));\n";
+export declare function deleteReplicaPayload(key: string): ReplicaEffect<void>;
+export interface ReplicaPayloadWriter {
+    write(bytes: Uint8Array): ReplicaEffect<void>;
+    /** Publish the manifest, after the last chunk. Returns the size. */
+    finish(): ReplicaEffect<number>;
+}
+/** Drop any bytes under `key`, then write fresh ones. */
+export declare function replicaPayloadWriter(key: string): ReplicaEffect<ReplicaPayloadWriter>;
+/** The published size, or undefined when absent or malformed. */
+export declare function replicaPayloadLength(key: string): ReplicaEffect<number | undefined>;
+/** Chunk `position` of `key`, checked against the published size. */
+export declare function replicaPayloadChunk(key: string, position: number, offset: number, size: number): ReplicaEffect<Uint8Array>;
+/**
+ * Stream a payload one chunk per storage call, so no transaction spans the
+ * consumer's awaits. `run` is the host's one-effect runner.
+ */
+export declare function readReplicaPayload(run: <T>(effect: ReplicaEffect<T>) => T | Promise<T>, key: string): AsyncGenerator<Uint8Array>;
+/** Where a chunked read resumes: a chunk row and a byte offset inside it. */
+export interface ReplicaPayloadCursor {
+    position: number;
+    offset: number;
+}
+/**
+ * Exactly `length` bytes of the payload under `key` from `from`, and the
+ * cursor after them. Rows may have any length, so a caller that reads a
+ * payload in parts keeps the returned cursor and never seeks by arithmetic.
+ * Memory is `length`.
+ */
+export declare function readReplicaPayloadWindow(key: string, from: ReplicaPayloadCursor, length: number): ReplicaEffect<{
+    bytes: Uint8Array;
+    next: ReplicaPayloadCursor;
+}>;
+/** In the caller's transaction: do the bytes under `key` hash to `digest`? */
+export declare function verifyReplicaPayload(key: string, digest: string, size: number): ReplicaEffect<boolean>;
+//# sourceMappingURL=payload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/replication/payload.ts"],"names":[],"mappings":"AASA,OAAO,EAAO,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,2BAA2B,QAAY,CAAC;AAGrD,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,4WAOrC,CAAC;AAEF,wBAAiB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAWtE;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC9C,oEAAoE;IACpE,MAAM,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;CACjC;AAED,yDAAyD;AACzD,wBAAiB,oBAAoB,CACnC,GAAG,EAAE,MAAM,GACV,aAAa,CAAC,oBAAoB,CAAC,CAmCrC;AAED,iEAAiE;AACjE,wBAAiB,oBAAoB,CACnC,GAAG,EAAE,MAAM,GACV,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,CASnC;AAED,qEAAqE;AACrE,wBAAiB,mBAAmB,CAClC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,aAAa,CAAC,UAAU,CAAC,CAe3B;AAcD;;;GAGG;AACH,wBAAuB,kBAAkB,CACvC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACpD,GAAG,EAAE,MAAM,GACV,cAAc,CAAC,UAAU,CAAC,CAW5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAiB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,oBAAoB,EAC1B,MAAM,EAAE,MAAM,GACb,aAAa,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC,CAuClE;AAED,8EAA8E;AAC9E,wBAAiB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,aAAa,CAAC,OAAO,CAAC,CAgBxB"}

package/dist/replication/payload.js

@@ -0,0 +1,137 @@
+/**
+ * Retained batch payloads, as storage effects over the binary chunk tables
+ * (`pdpp_binary_chunks`, `pdpp_binary_manifests`) in their `payload`
+ * namespace. Node's `pdpp-binary-chunks.ts` owns the same tables for every
+ * namespace; the `payload` namespace never had a legacy whole-value table,
+ * so its rows mean the same on both hosts.
+ */
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+import { sql } from "./effects.js";
+export const REPLICA_PAYLOAD_CHUNK_BYTES = 64 * 1024;
+const NAMESPACE = "payload";
+/** The tables, for a host whose storage does not create them already. */
+export const REPLICA_PAYLOAD_MIGRATION = `
+CREATE TABLE IF NOT EXISTS pdpp_binary_manifests (
+ namespace TEXT NOT NULL, blob_id TEXT NOT NULL, size_bytes INTEGER NOT NULL,
+ PRIMARY KEY(namespace,blob_id));
+CREATE TABLE IF NOT EXISTS pdpp_binary_chunks (
+ namespace TEXT NOT NULL, blob_id TEXT NOT NULL, position INTEGER NOT NULL, bytes BLOB NOT NULL,
+ PRIMARY KEY(namespace,blob_id,position));
+`;
+export function* deleteReplicaPayload(key) {
+    yield* sql.run("DELETE FROM pdpp_binary_chunks WHERE namespace=? AND blob_id=?", NAMESPACE, key);
+    yield* sql.run("DELETE FROM pdpp_binary_manifests WHERE namespace=? AND blob_id=?", NAMESPACE, key);
+}
+/** Drop any bytes under `key`, then write fresh ones. */
+export function* replicaPayloadWriter(key) {
+    yield* deleteReplicaPayload(key);
+    let size = 0, position = 0;
+    return {
+        *write(bytes) {
+            for (let offset = 0; offset < bytes.length; offset += REPLICA_PAYLOAD_CHUNK_BYTES) {
+                const part = bytes.subarray(offset, offset + REPLICA_PAYLOAD_CHUNK_BYTES);
+                yield* sql.run("INSERT INTO pdpp_binary_chunks VALUES (?,?,?,?)", NAMESPACE, key, position++, part);
+                size += part.length;
+            }
+        },
+        *finish() {
+            yield* sql.run("INSERT INTO pdpp_binary_manifests VALUES (?,?,?)", NAMESPACE, key, size);
+            return size;
+        },
+    };
+}
+/** The published size, or undefined when absent or malformed. */
+export function* replicaPayloadLength(key) {
+    const manifest = yield* sql.get("SELECT size_bytes AS size FROM pdpp_binary_manifests WHERE namespace=? AND blob_id=?", NAMESPACE, key);
+    return manifest && Number.isSafeInteger(manifest.size) && manifest.size >= 0
+        ? manifest.size
+        : undefined;
+}
+/** Chunk `position` of `key`, checked against the published size. */
+export function* replicaPayloadChunk(key, position, offset, size) {
+    const row = yield* sql.get("SELECT bytes FROM pdpp_binary_chunks WHERE namespace=? AND blob_id=? AND position=?", NAMESPACE, key, position);
+    if (!row ||
+        !row.bytes.length ||
+        row.bytes.length > REPLICA_PAYLOAD_CHUNK_BYTES ||
+        offset + row.bytes.length > size)
+        throw new Error("corrupt binary chunks");
+    return row.bytes;
+}
+function* assertNoExcess(key, position) {
+    if (yield* sql.get("SELECT 1 FROM pdpp_binary_chunks WHERE namespace=? AND blob_id=? AND position>=? LIMIT 1", NAMESPACE, key, position))
+        throw new Error("excess binary chunks");
+}
+/**
+ * Stream a payload one chunk per storage call, so no transaction spans the
+ * consumer's awaits. `run` is the host's one-effect runner.
+ */
+export async function* readReplicaPayload(run, key) {
+    const size = await run(replicaPayloadLength(key));
+    if (size === undefined)
+        throw new Error("missing binary bytes");
+    let offset = 0, position = 0;
+    while (offset < size) {
+        const bytes = await run(replicaPayloadChunk(key, position++, offset, size));
+        offset += bytes.length;
+        yield bytes;
+    }
+    await run(assertNoExcess(key, position));
+}
+/**
+ * Exactly `length` bytes of the payload under `key` from `from`, and the
+ * cursor after them. Rows may have any length, so a caller that reads a
+ * payload in parts keeps the returned cursor and never seeks by arithmetic.
+ * Memory is `length`.
+ */
+export function* readReplicaPayloadWindow(key, from, length) {
+    const size = yield* replicaPayloadLength(key);
+    if (size === undefined ||
+        !Number.isSafeInteger(length) ||
+        length < 1 ||
+        !Number.isSafeInteger(from.position) ||
+        from.position < 0 ||
+        !Number.isSafeInteger(from.offset) ||
+        from.offset < 0)
+        throw new Error("missing binary bytes");
+    const bytes = new Uint8Array(length);
+    let filled = 0;
+    let { position, offset } = from;
+    while (filled < length) {
+        const row = yield* sql.get("SELECT bytes FROM pdpp_binary_chunks WHERE namespace=? AND blob_id=? AND position=?", NAMESPACE, key, position);
+        if (!row ||
+            !row.bytes.length ||
+            row.bytes.length > REPLICA_PAYLOAD_CHUNK_BYTES ||
+            offset >= row.bytes.length)
+            throw new Error("corrupt binary chunks");
+        const take = Math.min(row.bytes.length - offset, length - filled);
+        bytes.set(row.bytes.subarray(offset, offset + take), filled);
+        filled += take;
+        offset += take;
+        if (offset === row.bytes.length) {
+            position++;
+            offset = 0;
+        }
+    }
+    return { bytes, next: { position, offset } };
+}
+/** In the caller's transaction: do the bytes under `key` hash to `digest`? */
+export function* verifyReplicaPayload(key, digest, size) {
+    if ((yield* replicaPayloadLength(key)) !== size)
+        return false;
+    const hash = sha256.create();
+    try {
+        let offset = 0, position = 0;
+        while (offset < size) {
+            const bytes = yield* replicaPayloadChunk(key, position++, offset, size);
+            offset += bytes.length;
+            hash.update(bytes);
+        }
+        yield* assertNoExcess(key, position);
+    }
+    catch {
+        return false;
+    }
+    return `sha256:${bytesToHex(hash.digest())}` === digest;
+}
+//# sourceMappingURL=payload.js.map

package/dist/replication/payload.js.map

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

package/dist/replication/preparation.d.ts

@@ -0,0 +1,42 @@
+import { type ReplicaOperation } from "./envelope.js";
+import { ReplicaResourceLimitError, type ReplicaResourceLimits } from "./limits.js";
+import type { ReplicaAdmission } from "./outcome.js";
+/** Created only by an enabled worker, alongside the admission schema. */
+export declare const REPLICA_PREPARATION_MIGRATION = "\nCREATE TABLE IF NOT EXISTS pdpp_transport_preparation (\n batch TEXT PRIMARY KEY, version INTEGER NOT NULL,\n state TEXT NOT NULL CHECK(state IN ('preparing','prep_failed_permanent','rebuilding','prep_failed_unknown','prepared','released')),\n wait_json TEXT);\nCREATE TABLE IF NOT EXISTS pdpp_transport_operation_outcomes (\n batch TEXT NOT NULL, position INTEGER NOT NULL, operation_json TEXT,\n writer_id TEXT, operation_id TEXT,\n encoding_failed INTEGER NOT NULL DEFAULT 0, outcome TEXT, reason TEXT, admission_json TEXT,\n PRIMARY KEY(batch,position));\nCREATE TABLE IF NOT EXISTS pdpp_transport_upload_attempts (\n batch TEXT NOT NULL, kind TEXT NOT NULL, position INTEGER NOT NULL, started_at INTEGER NOT NULL,\n PRIMARY KEY(batch,kind,position));\n";
+export type ReplicaPreparationState = "preparing" | "prep_failed_permanent" | "rebuilding" | "prep_failed_unknown" | "prepared" | "released";
+export type ReplicaPreparation = {
+    batch: string;
+    version: number;
+    state: ReplicaPreparationState;
+    wait_json: string | null;
+};
+export type RetainedPreparationOperation = {
+    position: number;
+    operation_json: string | null;
+    encoding_failed: number;
+};
+/** This error is minted only at the sender's own operation-encoding boundary. */
+export declare class ReplicaPreparationInputError extends Error {
+    readonly positions: readonly number[];
+    constructor(positions: readonly number[]);
+}
+export type ReplicaPreparationFailure = {
+    kind: "permanent";
+    admission: ReplicaAdmission;
+    positions?: readonly number[];
+} | {
+    kind: "unknown";
+};
+/** No message matching, generic RangeError, crypto error or I/O error is permanent. */
+export declare function classifyReplicaPreparationError(error: unknown): ReplicaPreparationFailure;
+/** An invalid operation retains its position, never a lossy JSON replacement. */
+export declare function snapshotReplicaOperation(operation: ReplicaOperation): {
+    operation_json: string | null;
+    encoding_failed: number;
+};
+/** Attribute each sender-owned streamed limit to the op that crosses it. */
+export declare function preparationOperationFailures(rows: readonly RetainedPreparationOperation[], limits: ReplicaResourceLimits): {
+    positions: number[];
+    error: ReplicaPreparationInputError | ReplicaResourceLimitError;
+} | undefined;
+//# sourceMappingURL=preparation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preparation.d.ts","sourceRoot":"","sources":["../../src/replication/preparation.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,yBAAyB,EACzB,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,yEAAyE;AACzE,eAAO,MAAM,6BAA6B,4vBAazC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAC/B,WAAW,GACX,uBAAuB,GACvB,YAAY,GACZ,qBAAqB,GACrB,UAAU,GACV,UAAU,CAAC;AACf,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,uBAAuB,CAAC;IAC/B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AACF,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,iFAAiF;AACjF,qBAAa,4BAA6B,SAAQ,KAAK;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE;gBAA5B,SAAS,EAAE,SAAS,MAAM,EAAE;CAIlD;AAED,MAAM,MAAM,yBAAyB,GACjC;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,GACD;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,uFAAuF;AACvF,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,yBAAyB,CA2B3B;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,gBAAgB,GAAG;IACrE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CACzB,CAMA;AAED,4EAA4E;AAC5E,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,SAAS,4BAA4B,EAAE,EAC7C,MAAM,EAAE,qBAAqB,GAE3B;IACE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,EAAE,4BAA4B,GAAG,yBAAyB,CAAC;CACjE,GACD,SAAS,CA6EZ"}

package/dist/replication/preparation.js

@@ -0,0 +1,118 @@
+import { canonicalJson, replicaOperationSchema, } from "./envelope.js";
+import { REPLICA_LIMITS_VERSION, ReplicaResourceLimitError, } from "./limits.js";
+/** Created only by an enabled worker, alongside the admission schema. */
+export const REPLICA_PREPARATION_MIGRATION = `
+CREATE TABLE IF NOT EXISTS pdpp_transport_preparation (
+ batch TEXT PRIMARY KEY, version INTEGER NOT NULL,
+ state TEXT NOT NULL CHECK(state IN ('preparing','prep_failed_permanent','rebuilding','prep_failed_unknown','prepared','released')),
+ wait_json TEXT);
+CREATE TABLE IF NOT EXISTS pdpp_transport_operation_outcomes (
+ batch TEXT NOT NULL, position INTEGER NOT NULL, operation_json TEXT,
+ writer_id TEXT, operation_id TEXT,
+ encoding_failed INTEGER NOT NULL DEFAULT 0, outcome TEXT, reason TEXT, admission_json TEXT,
+ PRIMARY KEY(batch,position));
+CREATE TABLE IF NOT EXISTS pdpp_transport_upload_attempts (
+ batch TEXT NOT NULL, kind TEXT NOT NULL, position INTEGER NOT NULL, started_at INTEGER NOT NULL,
+ PRIMARY KEY(batch,kind,position));
+`;
+/** This error is minted only at the sender's own operation-encoding boundary. */
+export class ReplicaPreparationInputError extends Error {
+    positions;
+    constructor(positions) {
+        super("replica operation cannot be encoded");
+        this.positions = positions;
+        this.name = "ReplicaPreparationInputError";
+    }
+}
+/** No message matching, generic RangeError, crypto error or I/O error is permanent. */
+export function classifyReplicaPreparationError(error) {
+    if (error instanceof ReplicaPreparationInputError)
+        return {
+            kind: "permanent",
+            positions: error.positions,
+            admission: { reason: "operation_encoding_unsupported" },
+        };
+    if (error instanceof ReplicaResourceLimitError &&
+        [
+            "operation_count",
+            "operation_bytes",
+            "single_blob_bytes",
+            "aggregate_blob_bytes",
+            "aggregate_ciphertext_bytes",
+            "total_bytes",
+        ].includes(error.limit))
+        return {
+            kind: "permanent",
+            admission: {
+                reason: "resource_unsupported",
+                limit: error.limit,
+                limitsVersion: REPLICA_LIMITS_VERSION,
+            },
+        };
+    return { kind: "unknown" };
+}
+/** An invalid operation retains its position, never a lossy JSON replacement. */
+export function snapshotReplicaOperation(operation) {
+    // A parser must not silently strip input fields. A false parse proves an
+    // input problem; an exception here remains unknown and must never drop it.
+    if (!replicaOperationSchema.safeParse(operation).success)
+        return { operation_json: null, encoding_failed: 1 };
+    return { operation_json: canonicalJson(operation), encoding_failed: 0 };
+}
+/** Attribute each sender-owned streamed limit to the op that crosses it. */
+export function preparationOperationFailures(rows, limits) {
+    const encoding = rows
+        .filter((row) => row.encoding_failed)
+        .map((row) => row.position);
+    if (encoding.length)
+        return {
+            positions: encoding,
+            error: new ReplicaPreparationInputError(encoding),
+        };
+    const acceptedBlobs = new Set();
+    let blobBytes = 0;
+    let count = 0;
+    const failures = [];
+    for (const row of rows) {
+        const op = JSON.parse(row.operation_json);
+        const blobs = op.kind === "upsert"
+            ? op.blobs
+            : op.kind === "blob-claim"
+                ? [op.blob]
+                : [];
+        const newBlobs = [
+            ...new Map(blobs
+                .filter((blob) => !acceptedBlobs.has(blob.blobId))
+                .map((blob) => [blob.blobId, blob])).values(),
+        ];
+        const newBytes = newBlobs.reduce((n, blob) => n + blob.sizeBytes, 0);
+        const bytes = new TextEncoder().encode(row.operation_json).length;
+        const oversizedBlob = blobs.find((blob) => blob.sizeBytes > limits.maxSingleBlobBytes);
+        const error = count >= limits.maxOperations
+            ? new ReplicaResourceLimitError("operation_count", count + 1, limits.maxOperations)
+            : bytes > limits.maxOperationBytes
+                ? new ReplicaResourceLimitError("operation_bytes", bytes, limits.maxOperationBytes)
+                : oversizedBlob
+                    ? new ReplicaResourceLimitError("single_blob_bytes", oversizedBlob.sizeBytes, limits.maxSingleBlobBytes)
+                    : blobBytes + newBytes > limits.maxBlobTotalBytes
+                        ? new ReplicaResourceLimitError("aggregate_blob_bytes", blobBytes + newBytes, limits.maxBlobTotalBytes)
+                        : undefined;
+        if (error) {
+            failures.push({ position: row.position, error });
+            continue;
+        }
+        count++;
+        blobBytes += newBytes;
+        for (const blob of newBlobs)
+            acceptedBlobs.add(blob.blobId);
+    }
+    // Settle one reason per transition; a subsequent pass checks the survivors.
+    const first = failures[0];
+    return (first && {
+        positions: failures
+            .filter((failure) => failure.error.limit === first.error.limit)
+            .map((failure) => failure.position),
+        error: first.error,
+    });
+}
+//# sourceMappingURL=preparation.js.map

package/dist/replication/preparation.js.map

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