@agentplat/mesh 0.3.0-alpha.4 → 0.3.0-beta.1

package/dist/durability.js

@@ -0,0 +1,749 @@
+import { canonicalizeMeshJsonBytes, validateSignedMeshEnvelope, } from "@agentplat/mesh-protocol";
+export const MESH_DURABILITY_SCHEMA_VERSION = 2;
+export const MESH_PREVIOUS_DURABILITY_SCHEMA_VERSION = 1;
+export const MESH_DURABLE_ENVELOPE_FORMAT = "application/vnd.agentplat.mesh-envelope+json";
+export const MESH_DURABLE_OPAQUE_SNAPSHOT_FORMAT = "application/json";
+export const MESH_DURABLE_LEGACY_OPAQUE_SNAPSHOT_FORMAT = "application/json; profile=legacy-opaque";
+export const MESH_DURABLE_JOURNAL_VERSION = 1;
+export const MESH_DURABLE_GENESIS_DIGEST = "sha256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
+/** Creates an inert worker. Work starts only through an explicit run method. */
+export function createMeshDurableWorker(options) {
+    if (!options ||
+        !options.repository ||
+        typeof options.processInbox !== "function" ||
+        typeof options.deliverOutbox !== "function") {
+        throw new TypeError("Mesh durable worker dependencies are required");
+    }
+    const scope = normalizeMeshDurableScope(options.scope);
+    const workerId = boundedIdentifier(options.workerId, "workerId");
+    const inboxBatchSize = boundedInteger(options.inboxBatchSize ?? 16, "inboxBatchSize", 256);
+    const outboxBatchSize = boundedInteger(options.outboxBatchSize ?? 16, "outboxBatchSize", 256);
+    const leaseDurationMs = boundedInteger(options.leaseDurationMs ?? 30_000, "leaseDurationMs", 3_600_000);
+    const failureRetryAfterMs = boundedInteger(options.failureRetryAfterMs ?? 1_000, "failureRetryAfterMs", 3_600_000);
+    const runInboxBatch = async (signal) => {
+        if (signal?.aborted)
+            return emptyBatch();
+        const records = await options.repository.claimInbox({
+            scope,
+            workerId,
+            limit: inboxBatchSize,
+            leaseDurationMs,
+        });
+        let completed = 0;
+        let conflicted = 0;
+        let failed = 0;
+        for (const inbox of records) {
+            if (signal?.aborted)
+                break;
+            try {
+                assertInboxClaim(inbox, scope, workerId);
+                const snapshot = await options.repository.loadSnapshot(scope);
+                const processed = await options.processInbox({
+                    scope,
+                    inbox,
+                    snapshot,
+                    signal,
+                });
+                const normalized = normalizeProcessorResult(processed, scope, inbox);
+                const commit = await options.repository.commitInboxTransition({
+                    inbox,
+                    expectedSnapshotRevision: snapshot?.revision ?? 0,
+                    transitionId: normalized.transitionId ?? `inbox:${inbox.messageId}`,
+                    outcome: normalized.outcome,
+                    ...(normalized.outcome === "applied"
+                        ? { nextState: normalized.nextState }
+                        : { reasonCode: normalized.reasonCode }),
+                    journal: normalized.journal ?? [],
+                    outbox: normalized.outcome === "applied" ? (normalized.outbox ?? []) : [],
+                });
+                if (commit.committed)
+                    completed += 1;
+                else {
+                    conflicted += 1;
+                    workerDiagnostic(options, {
+                        kind: "inbox.commit_conflict",
+                        recordId: inbox.messageId,
+                        code: commit.code,
+                    });
+                }
+            }
+            catch {
+                failed += 1;
+                workerDiagnostic(options, {
+                    kind: "inbox.processor_failure",
+                    recordId: inbox.messageId,
+                });
+                const abandoned = await options.repository
+                    .abandonInbox({
+                    inbox,
+                    retryAfterMs: failureRetryAfterMs,
+                    reasonCode: "processor_failure",
+                })
+                    .catch(() => false);
+                if (abandoned) {
+                    workerDiagnostic(options, {
+                        kind: "inbox.abandoned",
+                        recordId: inbox.messageId,
+                    });
+                }
+            }
+        }
+        return Object.freeze({
+            claimed: records.length,
+            completed,
+            conflicted,
+            failed,
+        });
+    };
+    const runOutboxBatch = async (signal) => {
+        if (signal?.aborted)
+            return emptyBatch();
+        const records = await options.repository.claimOutbox({
+            scope,
+            workerId,
+            limit: outboxBatchSize,
+            leaseDurationMs,
+        });
+        let completed = 0;
+        let conflicted = 0;
+        let failed = 0;
+        for (const outbox of records) {
+            if (signal?.aborted)
+                break;
+            let settlement;
+            try {
+                assertOutboxClaim(outbox, scope, workerId);
+                settlement = normalizeSettlement(await options.deliverOutbox(outbox, signal));
+            }
+            catch {
+                failed += 1;
+                workerDiagnostic(options, {
+                    kind: "outbox.delivery_failure",
+                    recordId: outbox.effectId,
+                });
+                settlement = {
+                    disposition: "retryable",
+                    retryAfterMs: failureRetryAfterMs,
+                    reasonCode: "delivery_failure",
+                };
+            }
+            const settled = await options.repository
+                .settleOutbox({ outbox, settlement })
+                .catch(() => false);
+            if (settled)
+                completed += 1;
+            else {
+                conflicted += 1;
+                workerDiagnostic(options, {
+                    kind: "outbox.settle_conflict",
+                    recordId: outbox.effectId,
+                });
+            }
+        }
+        return Object.freeze({
+            claimed: records.length,
+            completed,
+            conflicted,
+            failed,
+        });
+    };
+    const runOnce = async (signal) => {
+        const inbox = await runInboxBatch(signal);
+        const outbox = signal?.aborted
+            ? emptyBatch()
+            : await runOutboxBatch(signal);
+        return Object.freeze({ inbox, outbox });
+    };
+    return Object.freeze({
+        runInboxBatch,
+        runOutboxBatch,
+        runOnce,
+        async start({ signal, idleDelayMs = 100, }) {
+            const idle = boundedInteger(idleDelayMs, "idleDelayMs", 60_000);
+            while (!signal.aborted) {
+                const result = await runOnce(signal);
+                if (!signal.aborted &&
+                    result.inbox.claimed === 0 &&
+                    result.outbox.claimed === 0) {
+                    await abortableDelay(idle, signal);
+                }
+            }
+        },
+    });
+}
+export function normalizeMeshDurableScope(scope) {
+    if (!scope || typeof scope !== "object") {
+        throw new TypeError("Mesh durable scope is required");
+    }
+    const keys = Object.keys(scope).sort();
+    if (keys.length !== 4 ||
+        keys[0] !== "instanceId" ||
+        keys[1] !== "meshId" ||
+        keys[2] !== "peerId" ||
+        keys[3] !== "tenantId") {
+        throw new TypeError("Mesh durable scope must have an exact shape");
+    }
+    return Object.freeze({
+        tenantId: boundedIdentifier(scope.tenantId, "tenantId"),
+        meshId: boundedIdentifier(scope.meshId, "meshId"),
+        peerId: boundedIdentifier(scope.peerId, "peerId"),
+        instanceId: boundedIdentifier(scope.instanceId, "instanceId"),
+    });
+}
+/**
+ * Creates an immutable, exact-format snapshot codec registry. Codec selection
+ * never guesses from state shape and every decode verifies the stored digest.
+ */
+export function createMeshDurableSnapshotCodecRegistry(codecs, options = {}) {
+    if (!Array.isArray(codecs) || codecs.length < 1 || codecs.length > 64) {
+        throw new RangeError("Mesh snapshot codec count is outside its range");
+    }
+    const registered = new Map();
+    for (const codec of codecs) {
+        if (!codec ||
+            typeof codec !== "object" ||
+            typeof codec.encode !== "function" ||
+            typeof codec.decode !== "function") {
+            throw new TypeError("Mesh snapshot codec is invalid");
+        }
+        const descriptor = normalizeSnapshotDescriptor(codec.descriptor);
+        if (registered.has(descriptor.format)) {
+            throw new TypeError("Mesh snapshot codec format is duplicated");
+        }
+        const versions = codec.readableSchemaVersions ?? [descriptor.schemaVersion];
+        if (!Array.isArray(versions) ||
+            versions.length < 1 ||
+            versions.length > 64) {
+            throw new RangeError("Mesh snapshot readable schema count is outside its range");
+        }
+        const readable = new Set();
+        for (const version of versions) {
+            const normalized = snapshotSchemaVersion(version);
+            if (readable.has(normalized)) {
+                throw new TypeError("Mesh snapshot readable schema is duplicated");
+            }
+            readable.add(normalized);
+        }
+        if (!readable.has(descriptor.schemaVersion)) {
+            throw new TypeError("Mesh snapshot codec must read its current schema");
+        }
+        const encodeSnapshot = codec.encode;
+        const decodeSnapshot = codec.decode;
+        const migrateSnapshot = codec.migrate;
+        registered.set(descriptor.format, Object.freeze({
+            descriptor,
+            readable,
+            encode: (value) => encodeSnapshot(value),
+            decode: (state, schemaVersion) => decodeSnapshot(state, schemaVersion),
+            ...(migrateSnapshot === undefined
+                ? {}
+                : {
+                    migrate: (state, fromSchemaVersion) => migrateSnapshot(state, fromSchemaVersion),
+                }),
+        }));
+    }
+    const encode = async (format, value) => {
+        const registration = requireSnapshotCodec(registered, format);
+        return snapshotEncoding(registration.descriptor, registration.encode(value), options);
+    };
+    const decode = async (snapshot) => {
+        const metadata = snapshotMetadata(snapshot);
+        const registration = requireSnapshotCodec(registered, metadata.format);
+        if (!registration.readable.has(metadata.schemaVersion)) {
+            throw new TypeError("Mesh snapshot schema version is unsupported");
+        }
+        const actualDigest = await computeMeshDurableValueDigest(snapshot.state, options);
+        if (actualDigest !== snapshot.stateDigest) {
+            throw new TypeError("Mesh snapshot state digest does not match");
+        }
+        return deepFreezeDurableValue(registration.decode(cloneSnapshotState(snapshot.state, options.protocolOptions), metadata.schemaVersion));
+    };
+    const migrate = async (snapshot) => {
+        const metadata = snapshotMetadata(snapshot);
+        const registration = requireSnapshotCodec(registered, metadata.format);
+        await decode(snapshot);
+        if (metadata.schemaVersion === registration.descriptor.schemaVersion) {
+            return snapshotEncoding(registration.descriptor, snapshot.state, options);
+        }
+        if (registration.migrate === undefined) {
+            throw new TypeError("Mesh snapshot migration is unavailable");
+        }
+        const first = registration.migrate(cloneSnapshotState(snapshot.state, options.protocolOptions), metadata.schemaVersion);
+        const second = registration.migrate(cloneSnapshotState(snapshot.state, options.protocolOptions), metadata.schemaVersion);
+        const firstCanonical = canonicalSnapshotBytes(first, options.protocolOptions);
+        const secondCanonical = canonicalSnapshotBytes(second, options.protocolOptions);
+        if (!bytesEqual(firstCanonical, secondCanonical)) {
+            throw new TypeError("Mesh snapshot migration is nondeterministic");
+        }
+        const decoded = registration.decode(cloneSnapshotState(first, options.protocolOptions), registration.descriptor.schemaVersion);
+        const normalized = registration.encode(deepFreezeDurableValue(decoded));
+        if (!bytesEqual(firstCanonical, canonicalSnapshotBytes(normalized, options.protocolOptions))) {
+            throw new TypeError("Mesh snapshot migration is not canonical");
+        }
+        return snapshotEncoding(registration.descriptor, normalized, options);
+    };
+    return Object.freeze({
+        formats: Object.freeze([...registered.keys()].sort()),
+        encode,
+        decode,
+        migrate,
+    });
+}
+export async function computeMeshDurableValueDigest(value, options = {}) {
+    const canonical = canonicalizeMeshJsonBytes(value, options.protocolOptions);
+    if (!canonical.ok) {
+        throw new TypeError("Mesh durable value must be bounded strict JSON");
+    }
+    const buffer = new ArrayBuffer(canonical.value.byteLength);
+    new Uint8Array(buffer).set(canonical.value);
+    const digest = await (options.crypto ?? globalThis.crypto).subtle.digest("SHA-256", buffer);
+    return `sha256:${base64Url(new Uint8Array(digest))}`;
+}
+export async function createMeshDurableJournalEntry(input) {
+    const scope = normalizeMeshDurableScope(input.scope);
+    const sequence = boundedInteger(input.sequence, "journal sequence", Number.MAX_SAFE_INTEGER);
+    const snapshotRevision = nonNegativeInteger(input.snapshotRevision, "snapshot revision");
+    const draft = normalizeJournalDraft(input.draft);
+    assertDigest(input.previousDigest, "previous digest");
+    assertDigest(input.snapshotDigest, "snapshot digest");
+    boundedIdentifier(input.transitionId, "transitionId");
+    if (input.inboxMessageId !== undefined) {
+        assertMessageId(input.inboxMessageId);
+    }
+    assertTimestamp(input.occurredAt, "occurredAt");
+    const schemaVersion = input.schemaVersion ?? MESH_DURABILITY_SCHEMA_VERSION;
+    if (schemaVersion !== MESH_PREVIOUS_DURABILITY_SCHEMA_VERSION &&
+        schemaVersion !== MESH_DURABILITY_SCHEMA_VERSION) {
+        throw new TypeError("Mesh durability schema version is unsupported");
+    }
+    const document = {
+        schemaVersion,
+        ...(schemaVersion === MESH_DURABILITY_SCHEMA_VERSION
+            ? { journalVersion: MESH_DURABLE_JOURNAL_VERSION }
+            : {}),
+        scope: {
+            tenantId: scope.tenantId,
+            meshId: scope.meshId,
+            peerId: scope.peerId,
+            instanceId: scope.instanceId,
+        },
+        sequence,
+        previousDigest: input.previousDigest,
+        transitionId: input.transitionId,
+        ...(input.inboxMessageId === undefined
+            ? {}
+            : { inboxMessageId: input.inboxMessageId }),
+        snapshotRevision,
+        snapshotDigest: input.snapshotDigest,
+        entryId: draft.entryId,
+        kind: draft.kind,
+        ...(draft.reasonCode === undefined ? {} : { reasonCode: draft.reasonCode }),
+        occurredAt: input.occurredAt,
+    };
+    const digest = await computeMeshDurableValueDigest(document, {
+        crypto: input.crypto,
+    });
+    return Object.freeze({
+        schemaVersion,
+        ...(schemaVersion === MESH_DURABILITY_SCHEMA_VERSION
+            ? { journalVersion: MESH_DURABLE_JOURNAL_VERSION }
+            : {}),
+        scope,
+        sequence,
+        previousDigest: input.previousDigest,
+        digest,
+        transitionId: input.transitionId,
+        ...(input.inboxMessageId === undefined
+            ? {}
+            : { inboxMessageId: input.inboxMessageId }),
+        snapshotRevision,
+        snapshotDigest: input.snapshotDigest,
+        entryId: draft.entryId,
+        kind: draft.kind,
+        ...(draft.reasonCode === undefined ? {} : { reasonCode: draft.reasonCode }),
+        occurredAt: input.occurredAt,
+    });
+}
+export async function verifyMeshDurableJournal(input) {
+    if ((input.anchorDigest === undefined) !==
+        (input.anchorSequence === undefined) ||
+        (input.expectedHeadDigest === undefined) !==
+            (input.expectedHeadSequence === undefined)) {
+        throw new TypeError("Mesh durable journal anchor is incomplete");
+    }
+    let previousDigest = input.anchorDigest ?? MESH_DURABLE_GENESIS_DIGEST;
+    let sequence = input.anchorSequence ?? 0;
+    assertDigest(previousDigest, "anchor digest");
+    nonNegativeInteger(sequence, "anchor sequence");
+    if (input.expectedHeadDigest !== undefined) {
+        assertDigest(input.expectedHeadDigest, "expected head digest");
+        nonNegativeInteger(input.expectedHeadSequence, "expected head sequence");
+    }
+    for (const entry of input.entries) {
+        if (entry.sequence !== sequence + 1 ||
+            entry.previousDigest !== previousDigest ||
+            (entry.schemaVersion === MESH_DURABILITY_SCHEMA_VERSION
+                ? entry.journalVersion !== MESH_DURABLE_JOURNAL_VERSION
+                : entry.journalVersion !== undefined)) {
+            return false;
+        }
+        const rebuilt = await createMeshDurableJournalEntry({
+            scope: entry.scope,
+            sequence: entry.sequence,
+            previousDigest: entry.previousDigest,
+            transitionId: entry.transitionId,
+            inboxMessageId: entry.inboxMessageId,
+            snapshotRevision: entry.snapshotRevision,
+            snapshotDigest: entry.snapshotDigest,
+            draft: entry,
+            occurredAt: entry.occurredAt,
+            crypto: input.crypto,
+            schemaVersion: entry.schemaVersion,
+        });
+        if (rebuilt.digest !== entry.digest)
+            return false;
+        previousDigest = entry.digest;
+        sequence = entry.sequence;
+    }
+    return (input.expectedHeadDigest === undefined ||
+        (previousDigest === input.expectedHeadDigest &&
+            sequence === input.expectedHeadSequence));
+}
+function normalizeProcessorResult(result, scope, inbox) {
+    if (!result || typeof result !== "object") {
+        throw new TypeError("Mesh durable processor result is required");
+    }
+    if (result.transitionId !== undefined) {
+        boundedIdentifier(result.transitionId, "transitionId");
+    }
+    const journal = Object.freeze((result.journal ?? []).map(normalizeJournalDraft));
+    if (journal.length > 64) {
+        throw new RangeError("Mesh durable transition journal is too large");
+    }
+    if (result.outcome === "rejected") {
+        boundedReason(result.reasonCode);
+        if ("outbox" in result || "nextState" in result) {
+            throw new TypeError("Rejected durable transition cannot change state");
+        }
+        return Object.freeze({
+            outcome: "rejected",
+            ...(result.transitionId ? { transitionId: result.transitionId } : {}),
+            reasonCode: result.reasonCode,
+            journal,
+        });
+    }
+    if (result.outcome !== "applied" || result.nextState === undefined) {
+        throw new TypeError("Applied durable transition requires nextState");
+    }
+    const canonical = canonicalizeMeshJsonBytes(result.nextState);
+    if (!canonical.ok) {
+        throw new TypeError("Mesh durable nextState must be bounded strict JSON");
+    }
+    const outbox = Object.freeze((result.outbox ?? []).map((draft) => normalizeOutboundDraft(draft, scope, inbox)));
+    if (outbox.length > 256) {
+        throw new RangeError("Mesh durable transition outbox is too large");
+    }
+    return Object.freeze({
+        outcome: "applied",
+        ...(result.transitionId ? { transitionId: result.transitionId } : {}),
+        nextState: result.nextState,
+        journal,
+        outbox,
+    });
+}
+function normalizeOutboundDraft(draft, scope, inbox) {
+    if (!draft || typeof draft !== "object") {
+        throw new TypeError("Mesh durable outbound draft is invalid");
+    }
+    boundedIdentifier(draft.effectId, "effectId");
+    const validated = validateSignedMeshEnvelope(draft.envelope);
+    if (!validated.ok ||
+        validated.value.tenantId !== scope.tenantId ||
+        validated.value.meshId !== scope.meshId ||
+        validated.value.sender.peerId !== scope.peerId ||
+        validated.value.sender.instanceId !== scope.instanceId) {
+        throw new TypeError("Mesh durable outbound envelope scope is invalid");
+    }
+    if (draft.targetPeerId !== undefined) {
+        boundedIdentifier(draft.targetPeerId, "targetPeerId");
+        if (validated.value.audience.kind === "peer" &&
+            validated.value.audience.peerId !== draft.targetPeerId) {
+            throw new TypeError("Mesh durable outbound target is invalid");
+        }
+    }
+    if (validated.value.audience.kind === "mesh" &&
+        draft.targetPeerId === undefined) {
+        throw new TypeError("Mesh durable topic outbox requires targetPeerId");
+    }
+    if (validated.value.messageId === inbox.messageId) {
+        throw new TypeError("Mesh durable outbound messageId must be distinct");
+    }
+    return Object.freeze({
+        effectId: draft.effectId,
+        envelope: validated.value,
+        ...(draft.targetPeerId === undefined
+            ? {}
+            : { targetPeerId: draft.targetPeerId }),
+    });
+}
+function normalizeJournalDraft(draft) {
+    if (!draft || typeof draft !== "object") {
+        throw new TypeError("Mesh durable journal draft is invalid");
+    }
+    boundedIdentifier(draft.entryId, "journal entryId");
+    boundedReason(draft.kind, "journal kind");
+    if (draft.reasonCode !== undefined)
+        boundedReason(draft.reasonCode);
+    return Object.freeze({
+        entryId: draft.entryId,
+        kind: draft.kind,
+        ...(draft.reasonCode === undefined ? {} : { reasonCode: draft.reasonCode }),
+    });
+}
+function normalizeSettlement(settlement) {
+    if (!settlement || typeof settlement !== "object") {
+        throw new TypeError("Mesh durable outbox settlement is invalid");
+    }
+    if (settlement.reasonCode !== undefined)
+        boundedReason(settlement.reasonCode);
+    if (settlement.disposition === "retryable") {
+        return Object.freeze({
+            disposition: "retryable",
+            retryAfterMs: boundedInteger(settlement.retryAfterMs, "retryAfterMs", 3_600_000),
+            ...(settlement.reasonCode === undefined
+                ? {}
+                : { reasonCode: settlement.reasonCode }),
+        });
+    }
+    if (settlement.disposition !== "delivered" &&
+        settlement.disposition !== "permanent_rejection") {
+        throw new TypeError("Mesh durable outbox settlement is invalid");
+    }
+    return Object.freeze({
+        disposition: settlement.disposition,
+        ...(settlement.reasonCode === undefined
+            ? {}
+            : { reasonCode: settlement.reasonCode }),
+    });
+}
+function assertInboxClaim(inbox, scope, workerId) {
+    if (inbox.status !== "processing" ||
+        !inbox.claim ||
+        inbox.claim.workerId !== workerId ||
+        !scopeEquals(inbox.scope, scope)) {
+        throw new TypeError("Mesh durable inbox claim is invalid");
+    }
+}
+function assertOutboxClaim(outbox, scope, workerId) {
+    if (outbox.status !== "delivering" ||
+        !outbox.claim ||
+        outbox.claim.workerId !== workerId ||
+        !scopeEquals(outbox.scope, scope)) {
+        throw new TypeError("Mesh durable outbox claim is invalid");
+    }
+}
+function scopeEquals(left, right) {
+    return (left.tenantId === right.tenantId &&
+        left.meshId === right.meshId &&
+        left.peerId === right.peerId &&
+        left.instanceId === right.instanceId);
+}
+function workerDiagnostic(options, diagnostic) {
+    try {
+        options.onDiagnostic?.(Object.freeze(diagnostic));
+    }
+    catch {
+        // Diagnostics never change durable state.
+    }
+}
+function emptyBatch() {
+    return Object.freeze({ claimed: 0, completed: 0, conflicted: 0, failed: 0 });
+}
+function abortableDelay(milliseconds, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, milliseconds);
+        signal.addEventListener("abort", done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+    });
+}
+function boundedIdentifier(value, label) {
+    if (typeof value !== "string" ||
+        value.length < 1 ||
+        new TextEncoder().encode(value).byteLength > 256 ||
+        !/^[A-Za-z0-9][A-Za-z0-9._:@-]*$/u.test(value)) {
+        throw new TypeError(`Mesh durable ${label} is invalid`);
+    }
+    return value;
+}
+function boundedReason(value, label = "reasonCode") {
+    if (typeof value !== "string" ||
+        value.length < 1 ||
+        value.length > 128 ||
+        !/^[a-z0-9][a-z0-9._:-]*$/u.test(value)) {
+        throw new TypeError(`Mesh durable ${label} is invalid`);
+    }
+    return value;
+}
+function assertMessageId(value) {
+    // Protocol message IDs are canonical base64url encodings of 16 bytes. The
+    // final character carries two significant bits and four zero padding bits.
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-]{21}[AQgw]$/u.test(value)) {
+        throw new TypeError("Mesh durable inboxMessageId is invalid");
+    }
+    return value;
+}
+function boundedInteger(value, label, maximum) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+        throw new RangeError(`Mesh durable ${label} is outside its range`);
+    }
+    return value;
+}
+function nonNegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`Mesh durable ${label} is outside its range`);
+    }
+    return value;
+}
+function normalizeSnapshotDescriptor(descriptor) {
+    if (!descriptor || typeof descriptor !== "object") {
+        throw new TypeError("Mesh snapshot descriptor is required");
+    }
+    const keys = Object.keys(descriptor).sort();
+    if (keys.length !== 2 ||
+        keys[0] !== "format" ||
+        keys[1] !== "schemaVersion") {
+        throw new TypeError("Mesh snapshot descriptor must have an exact shape");
+    }
+    return Object.freeze({
+        format: snapshotFormat(descriptor.format),
+        schemaVersion: snapshotSchemaVersion(descriptor.schemaVersion),
+    });
+}
+function snapshotMetadata(snapshot) {
+    if (!snapshot || typeof snapshot !== "object") {
+        throw new TypeError("Mesh snapshot is required");
+    }
+    const keys = Object.keys(snapshot).sort();
+    const expectedKeys = [
+        "committedAt",
+        "revision",
+        "schemaVersion",
+        "scope",
+        "snapshotFormat",
+        "snapshotSchemaVersion",
+        "state",
+        "stateDigest",
+    ];
+    if (keys.length !== expectedKeys.length ||
+        keys.some((key, index) => key !== expectedKeys[index])) {
+        throw new TypeError("Mesh snapshot must have an exact shape");
+    }
+    if (snapshot.snapshotFormat === undefined ||
+        snapshot.snapshotSchemaVersion === undefined) {
+        throw new TypeError("Legacy Mesh snapshot requires an explicit backfill");
+    }
+    if (snapshot.schemaVersion !== MESH_PREVIOUS_DURABILITY_SCHEMA_VERSION &&
+        snapshot.schemaVersion !== MESH_DURABILITY_SCHEMA_VERSION) {
+        throw new TypeError("Mesh snapshot wrapper schema is unsupported");
+    }
+    normalizeMeshDurableScope(snapshot.scope);
+    boundedInteger(snapshot.revision, "snapshot revision", Number.MAX_SAFE_INTEGER);
+    assertTimestamp(snapshot.committedAt, "snapshot committedAt");
+    assertDigest(snapshot.stateDigest, "snapshot state digest");
+    const metadata = {
+        format: snapshotFormat(snapshot.snapshotFormat),
+        schemaVersion: snapshotSchemaVersion(snapshot.snapshotSchemaVersion),
+    };
+    if ((snapshot.schemaVersion === MESH_PREVIOUS_DURABILITY_SCHEMA_VERSION) !==
+        (metadata.format === MESH_DURABLE_LEGACY_OPAQUE_SNAPSHOT_FORMAT)) {
+        throw new TypeError("Mesh snapshot format does not match its wrapper");
+    }
+    return metadata;
+}
+function snapshotFormat(value) {
+    if (typeof value !== "string" ||
+        value.length < 3 ||
+        new TextEncoder().encode(value).byteLength > 256 ||
+        /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new TypeError("Mesh snapshot format is invalid");
+    }
+    return value;
+}
+function snapshotSchemaVersion(value) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 65_535) {
+        throw new RangeError("Mesh snapshot schema version is outside its range");
+    }
+    return value;
+}
+function requireSnapshotCodec(registered, format) {
+    const normalized = snapshotFormat(format);
+    const registration = registered.get(normalized);
+    if (!registration) {
+        throw new TypeError("Mesh snapshot format is unsupported");
+    }
+    return registration;
+}
+async function snapshotEncoding(descriptor, state, options) {
+    const snapshot = cloneSnapshotState(state, options.protocolOptions);
+    return Object.freeze({
+        descriptor,
+        state: snapshot,
+        stateDigest: await computeMeshDurableValueDigest(snapshot, options),
+    });
+}
+function cloneSnapshotState(state, protocolOptions) {
+    const bytes = canonicalSnapshotBytes(state, protocolOptions);
+    return deepFreezeDurableValue(JSON.parse(new TextDecoder().decode(bytes)));
+}
+function canonicalSnapshotBytes(state, protocolOptions) {
+    const canonical = canonicalizeMeshJsonBytes(state, protocolOptions);
+    if (!canonical.ok) {
+        throw new TypeError("Mesh snapshot state must be bounded strict JSON");
+    }
+    return canonical.value;
+}
+function bytesEqual(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    for (let index = 0; index < left.byteLength; index += 1) {
+        if (left[index] !== right[index])
+            return false;
+    }
+    return true;
+}
+function deepFreezeDurableValue(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const nested of Object.values(value))
+            deepFreezeDurableValue(nested);
+    }
+    return value;
+}
+function assertDigest(value, label) {
+    if (typeof value !== "string" || !/^sha256:[A-Za-z0-9_-]{43}$/u.test(value)) {
+        throw new TypeError(`Mesh durable ${label} is invalid`);
+    }
+}
+function assertTimestamp(value, label) {
+    if (typeof value !== "string" ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/u.test(value) ||
+        Number.isNaN(Date.parse(value))) {
+        throw new TypeError(`Mesh durable ${label} is invalid`);
+    }
+}
+function base64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary)
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/u, "");
+}
+//# sourceMappingURL=durability.js.map