@opendatalabs/personal-server-ts-core 1.34.1 → 1.35.0

package/dist/replication/transport.d.ts

@@ -0,0 +1,236 @@
+import { z } from "zod";
+export { REPLICA_MAX_FRAGMENTS, REPLICA_MAX_BLOB_BYTES, REPLICA_FRAGMENT_OVERHEAD_BYTES, replicaFramedBytesBound, } from "./limits.js";
+import { type ReplicaBatchFacts } from "./writer-identity.js";
+export { REPLICA_SCOPE_PREFIX, isReplicaScope } from "./namespace.js";
+/** Nesting that no manifest or fragment reaches. */
+export declare const REPLICA_MAX_JSON_DEPTH = 16;
+/**
+ * Structural characters (`[`, `{`, `,` and `:`) of a manifest at the
+ * fragment limit, with room for its statement. A small document of tiny
+ * values allocates far more than its size, so this is bounded before parsing.
+ */
+export declare const REPLICA_MAX_JSON_TOKENS: number;
+export declare const predecessorSchema: z.ZodObject<{
+    batch: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>;
+export declare const replicaFragmentSchema: z.ZodObject<{
+    format: z.ZodLiteral<"vana-pdpp-replica-fragment">;
+    version: z.ZodLiteral<3>;
+    owner: z.ZodString;
+    writer: z.ZodString;
+    batch: z.ZodString;
+    sequence: z.ZodNumber;
+    previous: z.ZodNullable<z.ZodObject<{
+        batch: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    collectedAt: z.ZodString;
+    digest: z.ZodString;
+    totalBytes: z.ZodNumber;
+    count: z.ZodNumber;
+    index: z.ZodNumber;
+    offset: z.ZodNumber;
+    chunkDigest: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strict>;
+export type ReplicaFragment = z.infer<typeof replicaFragmentSchema>;
+export type Predecessor = z.infer<typeof predecessorSchema>;
+/**
+ * One fragment's entry in its batch manifest: the sha256 of the exact
+ * encrypted object and its length. The digest is also the storage address,
+ * so a receiver checks fetched bytes against the finalized manifest before
+ * it decrypts them.
+ */
+export declare const manifestEntrySchema: z.ZodObject<{
+    digest: z.ZodString;
+    bytes: z.ZodNumber;
+}, z.core.$strict>;
+export type ManifestEntry = z.infer<typeof manifestEntrySchema>;
+/**
+ * The one registered object of a batch. Its DPv2 slot is the writer's scope at
+ * the next free version. It lists every fragment, in index order, by digest
+ * and size, and carries the batch statement signed by the writer's server
+ * key, which covers every other field and the slot. The version is a
+ * publication slot, not the batch sequence: a batch that cannot be framed
+ * takes no slot, so its successors still publish.
+ */
+export declare const replicaManifestSchema: z.ZodObject<{
+    format: z.ZodLiteral<"vana-pdpp-replica-manifest">;
+    version: z.ZodLiteral<1>;
+    owner: z.ZodString;
+    writer: z.ZodString;
+    batch: z.ZodString;
+    sequence: z.ZodNumber;
+    previous: z.ZodNullable<z.ZodObject<{
+        batch: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    collectedAt: z.ZodString;
+    digest: z.ZodString;
+    totalBytes: z.ZodNumber;
+    fragments: z.ZodArray<z.ZodObject<{
+        digest: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>>;
+    authority: z.ZodObject<{
+        chainId: z.ZodNumber;
+        statement: z.ZodObject<{
+            owner: z.ZodString;
+            server: z.ZodString;
+            serverId: z.ZodString;
+            environment: z.ZodEnum<{
+                dev: "dev";
+                prod: "prod";
+            }>;
+            writerNonce: z.ZodString;
+            version: z.ZodNumber;
+            batch: z.ZodString;
+            sequence: z.ZodNumber;
+            previous: z.ZodString;
+            previousBatch: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"">]>;
+            collectedAt: z.ZodString;
+            digest: z.ZodString;
+            totalBytes: z.ZodNumber;
+            count: z.ZodNumber;
+            fragments: z.ZodString;
+        }, z.core.$strict>;
+        signature: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ReplicaManifest = z.infer<typeof replicaManifestSchema>;
+/** An unregistered, content-addressed fragment ready for storage. */
+export interface PreparedFragment {
+    /** The writer scope whose key encrypts the fragment. */
+    scope: string;
+    index: number;
+    plaintext: Uint8Array;
+    encrypted: Uint8Array;
+    /** sha256 of `encrypted`: the manifest entry and the storage address. */
+    digest: string;
+}
+/** A batch manifest ready for storage and its single registration. */
+export interface PreparedManifest {
+    scope: string;
+    /** The DPv2 version this manifest registers, claimed when the batch is prepared. */
+    version: number;
+    plaintext: Uint8Array;
+    encrypted: Uint8Array;
+    dataHash: `0x${string}`;
+    metadataHash: `0x${string}`;
+}
+/** One stable scope per writer. Each batch appends one version to it. */
+export declare function replicaScope(writer: string): string;
+/** The writer of a replica scope, or undefined for any other name. */
+export declare function replicaWriterOf(scope: string): string | undefined;
+/** Storage key of a content-addressed fragment. Never registered. */
+export declare function replicaFragmentKey(scope: string, fragmentDigest: string): string;
+/** Storage key of a manifest: the ordinary DPv2 `<scope>/<version>` key. */
+export declare function replicaManifestKey(scope: string, version: number): string;
+export declare function replicaDigest(bytes: Uint8Array): string;
+export declare function toBase64(bytes: Uint8Array): string;
+export declare function fromBase64(value: string): Uint8Array;
+export declare function replicaMetadataHash(scope: string, collectedAt: string, sizeBytes: number): `0x${string}`;
+/**
+ * A manifest that can never be valid at its slot, with the refusal of the
+ * first check it fails. The caller has already matched its bytes to the
+ * slot's finalized commitment, so the refusal is terminal.
+ */
+export declare class ReplicaManifestRefused extends Error {
+    readonly reason: "signature_invalid" | "partition_mismatch" | "writer_mismatch" | "manifest_invalid";
+    constructor(reason: "signature_invalid" | "partition_mismatch" | "writer_mismatch" | "manifest_invalid");
+}
+/** Replica JSON over a bound that no writer reaches. */
+export declare class ReplicaJsonRefused extends Error {
+    constructor();
+}
+export interface ParsedReplicaJson {
+    encoded: string;
+    value: unknown;
+}
+/**
+ * Parse replica JSON. One pass without recursion bounds nesting and
+ * structural tokens before `JSON.parse` allocates anything, so the recursive
+ * work after it (schemas, `canonicalJson`) stays inside those bounds. Throws
+ * ReplicaJsonRefused over a bound, and the parser's own error for bytes that
+ * are not UTF-8 JSON.
+ */
+export declare function parseReplicaJson(plaintext: Uint8Array): ParsedReplicaJson;
+/**
+ * The most encrypted fragment bytes a batch of `totalBytes` needs in `count`
+ * fragments: the base64 of every chunk plus a fixed overhead per fragment.
+ */
+/** The facts a manifest at `version` claims; its statement must sign exactly these. */
+export declare function replicaManifestFacts(manifest: Omit<ReplicaManifest, "authority">, version: number): ReplicaBatchFacts;
+export declare function decodeReplicaFragment(plaintext: Uint8Array, scope: string, owner: string): ReplicaFragment;
+/** Fragment decoding after the shared receive boundary's bounded parse. */
+export declare function decodeParsedReplicaFragment({ encoded, value }: ParsedReplicaJson, scope: string, owner: string): ReplicaFragment;
+/** Exact framing size without allocating a base64 content string or encrypting. */
+export declare function replicaFragmentPlaintextByteLength(input: Omit<ReplicaFragment, "format" | "version" | "chunkDigest" | "content"> & {
+    chunkBytes: number;
+}): number;
+/** The single fragment encoder shared by buffered and streaming publishers.
+ * Freeze returned bytes before I/O: encryption is randomized. */
+export declare function prepareReplicaFragment(input: {
+    owner: string;
+    writer: string;
+    batch: string;
+    sequence: number;
+    previous: Predecessor | null;
+    collectedAt: string;
+    digest: string;
+    totalBytes: number;
+    count: number;
+    index: number;
+    offset: number;
+    chunk: Uint8Array;
+    encrypt: (scope: string, bytes: Uint8Array) => Promise<Uint8Array>;
+}): Promise<PreparedFragment>;
+/**
+ * Encode, sign, check and encrypt the manifest of a fully prepared batch for
+ * its registration at `version`. `sign` receives the facts of exactly this
+ * manifest and slot.
+ */
+export declare function prepareReplicaManifest(input: {
+    owner: string;
+    writer: string;
+    version: number;
+    batch: string;
+    sequence: number;
+    previous: Predecessor | null;
+    collectedAt: string;
+    digest: string;
+    totalBytes: number;
+    fragments: readonly ManifestEntry[];
+    sign: (facts: ReplicaBatchFacts) => Promise<unknown>;
+    encrypt: (scope: string, bytes: Uint8Array) => Promise<Uint8Array>;
+}): Promise<PreparedManifest>;
+/**
+ * Decode manifest plaintext. A received manifest goes through
+ * `receiveReplicaManifest`, which matches its bytes to the slot's finalized
+ * commitment first. The caller then authorizes its statement against
+ * `replicaManifestFacts(manifest, version)`; this check binds only owner and
+ * writer scope. Throws ReplicaManifestRefused and nothing else.
+ */
+export declare function decodeReplicaManifest(plaintext: Uint8Array, scope: string, owner: string): ReplicaManifest;
+/** `decodeReplicaManifest` after `parseReplicaJson`. Throws ReplicaManifestRefused and nothing else. */
+export declare function decodeParsedReplicaManifest({ encoded, value }: ParsedReplicaJson, scope: string, owner: string): ReplicaManifest;
+/**
+ * Check a decoded fragment against the entry of its finalized manifest. The
+ * fetched bytes already hash to the entry, so a mismatch here is a writer
+ * fault, never storage damage.
+ */
+export declare function fragmentMatchesManifest(fragment: ReplicaFragment, manifest: ReplicaManifest, index: number): boolean;
+export declare function fragmentReplicaPayload(input: {
+    owner: string;
+    writer: string;
+    batch: string;
+    sequence: number;
+    previous: Predecessor | null;
+    bytes: Uint8Array;
+    collectedAt: string;
+    encrypt: (scope: string, bytes: Uint8Array) => Promise<Uint8Array>;
+    maxBlobBytes?: number;
+    targetChunkBytes?: number;
+}): Promise<PreparedFragment[]>;
+//# sourceMappingURL=transport.d.ts.map

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

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

package/dist/replication/transport.js

@@ -0,0 +1,440 @@
+import { z } from "zod";
+import { DataFileEnvelopeSchema } from "@opendatalabs/vana-sdk/browser";
+import { sha256, keccak256, stringToHex } from "viem";
+import { canonicalJson } from "./envelope.js";
+import { ReplicaFramingUnsupported } from "./outcome.js";
+import { REPLICA_MAX_FRAGMENTS, REPLICA_MAX_BLOB_BYTES, replicaFramedBytesBound, } from "./limits.js";
+export { REPLICA_MAX_FRAGMENTS, REPLICA_MAX_BLOB_BYTES, REPLICA_FRAGMENT_OVERHEAD_BYTES, replicaFramedBytesBound, } from "./limits.js";
+import { replicaBatchAuthoritySchema, } from "./writer-identity.js";
+/** Reserved across ordinary reads, grants, inventory, MCP and legacy sync. */
+import { REPLICA_SCOPE_PREFIX } from "./namespace.js";
+export { REPLICA_SCOPE_PREFIX, isReplicaScope } from "./namespace.js";
+/** Nesting that no manifest or fragment reaches. */
+export const REPLICA_MAX_JSON_DEPTH = 16;
+/**
+ * Structural characters (`[`, `{`, `,` and `:`) of a manifest at the
+ * fragment limit, with room for its statement. A small document of tiny
+ * values allocates far more than its size, so this is bounded before parsing.
+ */
+export const REPLICA_MAX_JSON_TOKENS = 8 * REPLICA_MAX_FRAGMENTS + 4096;
+const token = z.string().regex(/^[a-f0-9]{32}$/);
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const integer = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+export const predecessorSchema = z.strictObject({ batch: token, digest });
+export const replicaFragmentSchema = z.strictObject({
+    format: z.literal("vana-pdpp-replica-fragment"),
+    /**
+     * Version 3 is stored unregistered and is trusted only through the signed
+     * manifest that names its digest, so it carries no statement of its own.
+     * Versions 1 and 2 were registered one fragment per scope.
+     */
+    version: z.literal(3),
+    owner: z.string().min(1),
+    writer: token,
+    batch: token,
+    sequence: integer.min(1),
+    previous: predecessorSchema.nullable(),
+    collectedAt: z.string().datetime({ offset: true }),
+    digest,
+    totalBytes: integer.min(1),
+    count: integer.min(1).max(REPLICA_MAX_FRAGMENTS),
+    index: integer,
+    offset: integer,
+    chunkDigest: digest,
+    content: z.string(),
+});
+/**
+ * One fragment's entry in its batch manifest: the sha256 of the exact
+ * encrypted object and its length. The digest is also the storage address,
+ * so a receiver checks fetched bytes against the finalized manifest before
+ * it decrypts them.
+ */
+export const manifestEntrySchema = z.strictObject({
+    digest,
+    bytes: integer.min(1).max(REPLICA_MAX_BLOB_BYTES),
+});
+/**
+ * The one registered object of a batch. Its DPv2 slot is the writer's scope at
+ * the next free version. It lists every fragment, in index order, by digest
+ * and size, and carries the batch statement signed by the writer's server
+ * key, which covers every other field and the slot. The version is a
+ * publication slot, not the batch sequence: a batch that cannot be framed
+ * takes no slot, so its successors still publish.
+ */
+export const replicaManifestSchema = z.strictObject({
+    format: z.literal("vana-pdpp-replica-manifest"),
+    version: z.literal(1),
+    owner: z.string().min(1),
+    writer: token,
+    batch: token,
+    sequence: integer.min(1),
+    previous: predecessorSchema.nullable(),
+    collectedAt: z.string().datetime({ offset: true }),
+    digest,
+    totalBytes: integer.min(1),
+    fragments: z.array(manifestEntrySchema).min(1).max(REPLICA_MAX_FRAGMENTS),
+    /** The batch statement signed by the writer's server key (host contract §3.3). */
+    authority: replicaBatchAuthoritySchema,
+});
+/** One stable scope per writer. Each batch appends one version to it. */
+export function replicaScope(writer) {
+    token.parse(writer);
+    return `${REPLICA_SCOPE_PREFIX}.${writer}`;
+}
+/** The writer of a replica scope, or undefined for any other name. */
+export function replicaWriterOf(scope) {
+    const writer = scope.slice(REPLICA_SCOPE_PREFIX.length + 1);
+    return scope === `${REPLICA_SCOPE_PREFIX}.${writer}` &&
+        token.safeParse(writer).success
+        ? writer
+        : undefined;
+}
+/** Storage key of a content-addressed fragment. Never registered. */
+export function replicaFragmentKey(scope, fragmentDigest) {
+    digest.parse(fragmentDigest);
+    return `${scope}/fragments/${fragmentDigest.slice("sha256:".length)}`;
+}
+/** Storage key of a manifest: the ordinary DPv2 `<scope>/<version>` key. */
+export function replicaManifestKey(scope, version) {
+    integer.min(1).parse(version);
+    return `${scope}/${version}`;
+}
+export function replicaDigest(bytes) {
+    return `sha256:${sha256(bytes).slice(2)}`;
+}
+export function toBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 8192)
+        binary += Reflect.apply(String.fromCharCode, null, bytes.subarray(i, i + 8192));
+    return btoa(binary);
+}
+export function fromBase64(value) {
+    if (typeof value !== "string")
+        throw new Error("noncanonical base64");
+    const binary = atob(value);
+    // atob validates the alphabet and padding placement, but accepts whitespace,
+    // omitted padding and nonzero unused bits. Reject those without re-encoding
+    // the whole decoded object into another binary string and base64 string.
+    if (value.length !== 4 * Math.ceil(binary.length / 3) ||
+        /[\t\n\f\r ]/.test(value))
+        throw new Error("noncanonical base64");
+    const remainder = binary.length % 3;
+    if (remainder) {
+        const padding = 3 - remainder;
+        const last = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".indexOf(value[value.length - padding - 1]);
+        // Two '=' leave four unused bits; one '=' leaves two unused bits.
+        if ((last & (padding === 2 ? 15 : 3)) !== 0)
+            throw new Error("noncanonical base64");
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+export function replicaMetadataHash(scope, collectedAt, sizeBytes) {
+    return keccak256(stringToHex(JSON.stringify({ scope, collectedAt, sizeBytes })));
+}
+/**
+ * A manifest that can never be valid at its slot, with the refusal of the
+ * first check it fails. The caller has already matched its bytes to the
+ * slot's finalized commitment, so the refusal is terminal.
+ */
+export class ReplicaManifestRefused extends Error {
+    reason;
+    constructor(reason) {
+        super(`replica manifest refused: ${reason}`);
+        this.reason = reason;
+        this.name = "ReplicaManifestRefused";
+    }
+}
+/** Replica JSON over a bound that no writer reaches. */
+export class ReplicaJsonRefused extends Error {
+    constructor() {
+        super("replica JSON over its depth or token bound");
+        this.name = "ReplicaJsonRefused";
+    }
+}
+/**
+ * Parse replica JSON. One pass without recursion bounds nesting and
+ * structural tokens before `JSON.parse` allocates anything, so the recursive
+ * work after it (schemas, `canonicalJson`) stays inside those bounds. Throws
+ * ReplicaJsonRefused over a bound, and the parser's own error for bytes that
+ * are not UTF-8 JSON.
+ */
+export function parseReplicaJson(plaintext) {
+    const encoded = new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
+    let depth = 0;
+    let tokens = 0;
+    let quoted = false;
+    for (let index = 0; index < encoded.length; index++) {
+        const code = encoded.charCodeAt(index);
+        if (quoted) {
+            if (code === 0x5c)
+                index++;
+            else if (code === 0x22)
+                quoted = false;
+            continue;
+        }
+        if (code === 0x22)
+            quoted = true;
+        else if (code === 0x5d || code === 0x7d)
+            depth--;
+        else if (code === 0x5b || code === 0x7b || code === 0x2c || code === 0x3a) {
+            if (++tokens > REPLICA_MAX_JSON_TOKENS ||
+                ((code === 0x5b || code === 0x7b) && ++depth > REPLICA_MAX_JSON_DEPTH))
+                throw new ReplicaJsonRefused();
+        }
+    }
+    return { encoded, value: JSON.parse(encoded) };
+}
+/**
+ * The most encrypted fragment bytes a batch of `totalBytes` needs in `count`
+ * fragments: the base64 of every chunk plus a fixed overhead per fragment.
+ */
+/** The facts a manifest at `version` claims; its statement must sign exactly these. */
+export function replicaManifestFacts(manifest, version) {
+    return {
+        version,
+        batch: manifest.batch,
+        sequence: manifest.sequence,
+        previous: manifest.previous,
+        collectedAt: manifest.collectedAt,
+        digest: manifest.digest,
+        totalBytes: manifest.totalBytes,
+        fragments: manifest.fragments,
+    };
+}
+export function decodeReplicaFragment(plaintext, scope, owner) {
+    return decodeParsedReplicaFragment(parseReplicaJson(plaintext), scope, owner);
+}
+/** Fragment decoding after the shared receive boundary's bounded parse. */
+export function decodeParsedReplicaFragment({ encoded, value }, scope, owner) {
+    const wrapper = DataFileEnvelopeSchema.parse(value);
+    const fragment = replicaFragmentSchema.parse(wrapper.data.fragment);
+    if (canonicalJson(wrapper) !== encoded ||
+        wrapper.scope !== scope ||
+        wrapper.collectedAt !== fragment.collectedAt ||
+        fragment.owner !== owner ||
+        scope !== replicaScope(fragment.writer) ||
+        fragment.index >= fragment.count ||
+        (fragment.sequence === 1) !== (fragment.previous === null))
+        throw new Error("invalid replica fragment binding");
+    const chunk = fromBase64(fragment.content);
+    if (!chunk.length ||
+        fragment.offset + chunk.length > fragment.totalBytes ||
+        replicaDigest(chunk) !== fragment.chunkDigest)
+        throw new Error("corrupt replica fragment");
+    return fragment;
+}
+function encodeFragmentPlaintext(fragment) {
+    return new TextEncoder().encode(canonicalJson({
+        version: "1.0",
+        scope: replicaScope(fragment.writer),
+        collectedAt: fragment.collectedAt,
+        data: { fragment },
+    }));
+}
+/** Exact framing size without allocating a base64 content string or encrypting. */
+export function replicaFragmentPlaintextByteLength(input) {
+    const { chunkBytes, ...fields } = input;
+    return (encodeFragmentPlaintext({
+        ...fields,
+        format: "vana-pdpp-replica-fragment",
+        version: 3,
+        chunkDigest: `sha256:${"0".repeat(64)}`,
+        content: "",
+    }).length +
+        4 * Math.ceil(chunkBytes / 3));
+}
+/** The single fragment encoder shared by buffered and streaming publishers.
+ * Freeze returned bytes before I/O: encryption is randomized. */
+export async function prepareReplicaFragment(input) {
+    const scope = replicaScope(input.writer);
+    const fragment = replicaFragmentSchema.parse({
+        format: "vana-pdpp-replica-fragment",
+        version: 3,
+        owner: input.owner,
+        writer: input.writer,
+        batch: input.batch,
+        sequence: input.sequence,
+        previous: input.previous,
+        collectedAt: input.collectedAt,
+        digest: input.digest,
+        totalBytes: input.totalBytes,
+        count: input.count,
+        index: input.index,
+        offset: input.offset,
+        chunkDigest: replicaDigest(input.chunk),
+        content: toBase64(input.chunk),
+    });
+    const plaintext = encodeFragmentPlaintext(fragment);
+    // Validate writer/address/order grammar even for locally prepared inputs.
+    decodeReplicaFragment(plaintext, scope, input.owner);
+    const encrypted = await input.encrypt(scope, plaintext);
+    return {
+        scope,
+        index: input.index,
+        plaintext,
+        encrypted,
+        digest: replicaDigest(encrypted),
+    };
+}
+/**
+ * Encode, sign, check and encrypt the manifest of a fully prepared batch for
+ * its registration at `version`. `sign` receives the facts of exactly this
+ * manifest and slot.
+ */
+export async function prepareReplicaManifest(input) {
+    const scope = replicaScope(input.writer);
+    const unsigned = replicaManifestSchema.omit({ authority: true }).parse({
+        format: "vana-pdpp-replica-manifest",
+        version: 1,
+        owner: input.owner,
+        writer: input.writer,
+        batch: input.batch,
+        sequence: input.sequence,
+        previous: input.previous,
+        collectedAt: input.collectedAt,
+        digest: input.digest,
+        totalBytes: input.totalBytes,
+        fragments: input.fragments.map((f) => ({
+            digest: f.digest,
+            bytes: f.bytes,
+        })),
+    });
+    const manifest = {
+        ...unsigned,
+        authority: await input.sign(replicaManifestFacts(unsigned, input.version)),
+    };
+    const plaintext = new TextEncoder().encode(canonicalJson({
+        version: "1.0",
+        scope,
+        collectedAt: input.collectedAt,
+        data: { manifest },
+    }));
+    decodeReplicaManifest(plaintext, scope, input.owner);
+    const encrypted = await input.encrypt(scope, plaintext);
+    return {
+        scope,
+        version: integer.min(1).parse(input.version),
+        plaintext,
+        encrypted,
+        dataHash: keccak256(plaintext),
+        metadataHash: replicaMetadataHash(scope, input.collectedAt, encrypted.length),
+    };
+}
+/**
+ * Decode manifest plaintext. A received manifest goes through
+ * `receiveReplicaManifest`, which matches its bytes to the slot's finalized
+ * commitment first. The caller then authorizes its statement against
+ * `replicaManifestFacts(manifest, version)`; this check binds only owner and
+ * writer scope. Throws ReplicaManifestRefused and nothing else.
+ */
+export function decodeReplicaManifest(plaintext, scope, owner) {
+    let parsed;
+    try {
+        parsed = parseReplicaJson(plaintext);
+    }
+    catch {
+        throw new ReplicaManifestRefused("manifest_invalid");
+    }
+    return decodeParsedReplicaManifest(parsed, scope, owner);
+}
+/** `decodeReplicaManifest` after `parseReplicaJson`. Throws ReplicaManifestRefused and nothing else. */
+export function decodeParsedReplicaManifest({ encoded, value }, scope, owner) {
+    try {
+        const wrapper = DataFileEnvelopeSchema.safeParse(value);
+        if (!wrapper.success || canonicalJson(wrapper.data) !== encoded)
+            throw new ReplicaManifestRefused("manifest_invalid");
+        if (wrapper.data.scope !== scope)
+            throw new ReplicaManifestRefused("writer_mismatch");
+        const claimed = wrapper.data.data.manifest;
+        const parsed = replicaManifestSchema.safeParse(claimed);
+        if (!parsed.success)
+            throw new ReplicaManifestRefused(typeof claimed === "object" &&
+                claimed !== null &&
+                !replicaBatchAuthoritySchema.safeParse(claimed.authority).success
+                ? "signature_invalid"
+                : "manifest_invalid");
+        const manifest = parsed.data;
+        if (manifest.owner !== owner)
+            throw new ReplicaManifestRefused("partition_mismatch");
+        if (scope !== replicaScope(manifest.writer))
+            throw new ReplicaManifestRefused("writer_mismatch");
+        if (wrapper.data.collectedAt !== manifest.collectedAt ||
+            (manifest.sequence === 1) !== (manifest.previous === null) ||
+            new Set(manifest.fragments.map((entry) => entry.digest)).size !==
+                manifest.fragments.length ||
+            manifest.fragments.length > manifest.totalBytes ||
+            manifest.fragments.reduce((sum, f) => sum + f.bytes, 0) >
+                replicaFramedBytesBound(manifest.totalBytes, manifest.fragments.length))
+            throw new ReplicaManifestRefused("manifest_invalid");
+        return manifest;
+    }
+    catch (error) {
+        // Pure checks of authentic bytes: whatever they throw is terminal.
+        if (error instanceof ReplicaManifestRefused)
+            throw error;
+        throw new ReplicaManifestRefused("manifest_invalid");
+    }
+}
+/**
+ * Check a decoded fragment against the entry of its finalized manifest. The
+ * fetched bytes already hash to the entry, so a mismatch here is a writer
+ * fault, never storage damage.
+ */
+export function fragmentMatchesManifest(fragment, manifest, index) {
+    return (fragment.owner === manifest.owner &&
+        fragment.writer === manifest.writer &&
+        fragment.batch === manifest.batch &&
+        fragment.sequence === manifest.sequence &&
+        canonicalJson(fragment.previous) === canonicalJson(manifest.previous) &&
+        fragment.collectedAt === manifest.collectedAt &&
+        fragment.digest === manifest.digest &&
+        fragment.totalBytes === manifest.totalBytes &&
+        fragment.count === manifest.fragments.length &&
+        fragment.index === index);
+}
+export async function fragmentReplicaPayload(input) {
+    const cap = input.maxBlobBytes ?? REPLICA_MAX_BLOB_BYTES;
+    if (!Number.isSafeInteger(cap) ||
+        cap < 1 ||
+        cap > REPLICA_MAX_BLOB_BYTES ||
+        !input.bytes.length)
+        throw new RangeError("invalid replica size limit");
+    let chunkSize = input.targetChunkBytes ?? 4 * 1024 * 1024;
+    if (!Number.isSafeInteger(chunkSize) || chunkSize < 1)
+        throw new RangeError("invalid chunk size");
+    const digest = replicaDigest(input.bytes);
+    while (true) {
+        const count = Math.ceil(input.bytes.length / chunkSize);
+        if (count > REPLICA_MAX_FRAGMENTS)
+            throw new ReplicaFramingUnsupported(count, REPLICA_MAX_FRAGMENTS, "fragment_count");
+        const parts = [];
+        let oversized = 0;
+        for (let index = 0; index < count; index++) {
+            const offset = index * chunkSize;
+            const chunk = input.bytes.subarray(offset, offset + chunkSize);
+            const part = await prepareReplicaFragment({
+                ...input,
+                digest,
+                totalBytes: input.bytes.length,
+                count,
+                index,
+                offset,
+                chunk,
+            });
+            if (part.encrypted.length > cap) {
+                oversized = part.encrypted.length;
+                break;
+            }
+            parts.push(part);
+        }
+        if (!oversized)
+            return parts;
+        if (chunkSize === 1)
+            throw new ReplicaFramingUnsupported(oversized, cap);
+        chunkSize = Math.max(1, Math.floor(chunkSize / 2));
+    }
+}
+//# sourceMappingURL=transport.js.map