@peerbit/trusted-network 6.0.103 → 6.0.105

package/dist/src/v2-policy-engine.js

@@ -0,0 +1,812 @@
+import { deserialize, serialize } from "@dao-xyz/borsh";
+import { DecryptedThing, PublicSignKey, verify } from "@peerbit/crypto";
+import { Entry, EntryV0, NO_ENCODING } from "@peerbit/log";
+import { compare, equals } from "uint8arrays";
+import { NetworkDescriptorV2, PolicySnapshotBodyV2, PolicySubjectBindingV2, TRUSTED_NETWORK_V2_KNOWN_ROLE_BITS, TRUSTED_NETWORK_V2_MAX_POLICY_ENTRY_BYTES, assertNetworkDescriptorV2, decodePolicySnapshotBodyV2, digestPolicySnapshotBodyV2, } from "./v2.js";
+/**
+ * Internal policy reducer for the non-activatable TrustedNetwork v2 scaffold.
+ *
+ * The reducer intentionally is not exported from the package entry point. It
+ * retains one accepted snapshot, a bounded pending working set, and (after
+ * equivocation) two child proofs. Historical snapshots are supplied by the
+ * resolver instead of being accumulated in memory.
+ */
+const DEFAULT_MAX_PENDING_POLICIES_V2 = 64;
+const PENDING_POLICY_ACCOUNTING_OVERHEAD_V2 = 64;
+const MAX_PENDING_POLICY_ACCOUNTED_BYTES_V2 = TRUSTED_NETWORK_V2_MAX_POLICY_ENTRY_BYTES * 2 +
+    PENDING_POLICY_ACCOUNTING_OVERHEAD_V2;
+const DEFAULT_MAX_PENDING_POLICY_BYTES_V2 = MAX_PENDING_POLICY_ACCOUNTED_BYTES_V2;
+const DEFAULT_POLICY_RESOLUTION_TIMEOUT_MS_V2 = 10 * 1000;
+const MAX_TIMER_DELAY_MS_V2 = 0x7fffffff;
+const MAX_UNAVAILABLE_REASON_LENGTH_V2 = 512;
+const copyBytes = (bytes) => Uint8Array.from(bytes);
+const bytesKey = (bytes) => {
+    let key = "";
+    for (const byte of bytes)
+        key += byte.toString(16).padStart(2, "0");
+    return key;
+};
+const compareKeys = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const copyPublicKey = (key) => deserialize(serialize(key), PublicSignKey);
+const publicKeyId = (key) => bytesKey(serialize(key));
+const copyBinding = (binding) => new PolicySubjectBindingV2({
+    signingKey: copyPublicKey(binding.signingKey),
+    roles: binding.roles,
+});
+const copyBody = (body) => new PolicySnapshotBodyV2({
+    networkId: copyBytes(body.networkId),
+    sequence: body.sequence,
+    previousPolicyDigest: copyBytes(body.previousPolicyDigest),
+    bindings: body.bindings.map(copyBinding),
+});
+const copySnapshot = (snapshot) => ({
+    body: copyBody(snapshot.body),
+    digest: copyBytes(snapshot.digest),
+    digestKey: snapshot.digestKey,
+    entryBytes: copyBytes(snapshot.entryBytes),
+    accountedBytes: snapshot.accountedBytes,
+});
+const validationMessage = (error) => error instanceof Error ? error.message : String(error);
+const boundedUnavailableReason = (reason) => reason.slice(0, MAX_UNAVAILABLE_REASON_LENGTH_V2);
+class PolicyDependencyUnavailableErrorV2 extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PolicyDependencyUnavailableErrorV2";
+    }
+}
+const capturePolicySnapshotEntryBytesV2 = (entryBytes) => {
+    if (!(entryBytes instanceof Uint8Array)) {
+        throw new Error("Policy snapshot must use canonical EntryV0 bytes");
+    }
+    if (entryBytes.byteLength === 0) {
+        throw new Error("Policy snapshot must use EntryV0");
+    }
+    if (entryBytes.byteLength > TRUSTED_NETWORK_V2_MAX_POLICY_ENTRY_BYTES) {
+        throw new Error(`Policy snapshot entry must contain 1-${TRUSTED_NETWORK_V2_MAX_POLICY_ENTRY_BYTES} bytes`);
+    }
+    // Apply the protocol byte ceiling before this first copy, decode, or crypto
+    // operation. The retained copy also prevents caller mutation during awaits.
+    return copyBytes(entryBytes);
+};
+const authenticateCapturedPolicySnapshotEntryV2 = async (canonicalEntryBytes, descriptor) => {
+    const authenticatedEntry = deserialize(canonicalEntryBytes, Entry);
+    if (!(authenticatedEntry instanceof EntryV0)) {
+        throw new Error("Policy snapshot must use EntryV0");
+    }
+    if (!equals(canonicalEntryBytes, serialize(authenticatedEntry))) {
+        throw new Error("Policy snapshot entry encoding is not canonical");
+    }
+    if (!(authenticatedEntry._meta instanceof DecryptedThing)) {
+        throw new Error("Policy snapshot metadata must be public");
+    }
+    if (!(authenticatedEntry._payload instanceof DecryptedThing)) {
+        throw new Error("Policy snapshot payload must be public");
+    }
+    if (authenticatedEntry._signatures === undefined ||
+        authenticatedEntry._signatures.signatures.length !== 1) {
+        throw new Error("Policy snapshot must contain exactly one signature");
+    }
+    if (!(authenticatedEntry._signatures.signatures[0] instanceof DecryptedThing)) {
+        throw new Error("Policy snapshot signature must be public");
+    }
+    authenticatedEntry.init({ encoding: NO_ENCODING });
+    const signatures = await authenticatedEntry.getSignatures();
+    if (signatures.length !== 1) {
+        throw new Error("Policy snapshot must resolve exactly one signature");
+    }
+    const signature = signatures[0];
+    if (!equals(serialize(signature.publicKey), serialize(descriptor.policyAuthority))) {
+        throw new Error("Policy snapshot signer is not the policy authority");
+    }
+    if (!(await verify(signature, authenticatedEntry.getSignableBytes()))) {
+        throw new Error("Policy snapshot authority signature is invalid");
+    }
+    const payload = await authenticatedEntry.getPayloadValue();
+    if (!(payload instanceof Uint8Array)) {
+        throw new Error("Policy snapshot payload must contain canonical body bytes");
+    }
+    const body = decodePolicySnapshotBodyV2(copyBytes(payload), descriptor);
+    const digest = digestPolicySnapshotBodyV2(body);
+    return {
+        body: copyBody(body),
+        digest: copyBytes(digest),
+        digestKey: bytesKey(digest),
+        entryBytes: canonicalEntryBytes,
+        accountedBytes: canonicalEntryBytes.byteLength +
+            serialize(body).byteLength +
+            PENDING_POLICY_ACCOUNTING_OVERHEAD_V2,
+    };
+};
+export const authenticatePolicySnapshotEntryV2 = async (entryBytes, descriptor) => {
+    assertNetworkDescriptorV2(descriptor);
+    return authenticateCapturedPolicySnapshotEntryV2(capturePolicySnapshotEntryBytesV2(entryBytes), descriptor);
+};
+const projectionFromSnapshot = (snapshot) => ({
+    sequence: snapshot.body.sequence,
+    digest: copyBytes(snapshot.digest),
+    bindings: snapshot.body.bindings.map(copyBinding),
+});
+const forkProofFromSnapshot = (snapshot) => ({
+    sequence: snapshot.body.sequence,
+    digest: copyBytes(snapshot.digest),
+    entryBytes: copyBytes(snapshot.entryBytes),
+});
+const copyForkChildProof = (proof) => ({
+    sequence: proof.sequence,
+    digest: copyBytes(proof.digest),
+    entryBytes: copyBytes(proof.entryBytes),
+});
+const compareForkChildProofs = (left, right) => {
+    const digestOrder = compare(left.digest, right.digest);
+    return digestOrder === 0
+        ? compare(left.entryBytes, right.entryBytes)
+        : digestOrder;
+};
+const copyProjection = (projection) => ({
+    sequence: projection.sequence,
+    digest: copyBytes(projection.digest),
+    bindings: projection.bindings.map(copyBinding),
+});
+const copyForkEvidence = (evidence) => ({
+    commonParent: copyProjection(evidence.commonParent),
+    children: [
+        copyForkChildProof(evidence.children[0]),
+        copyForkChildProof(evidence.children[1]),
+    ],
+});
+export class TrustedNetworkV2PolicyReducer {
+    descriptor;
+    resolvePolicyEntry;
+    resolveTimeoutMs;
+    maxPending;
+    maxPendingPolicyBytes;
+    lifecycleController = new AbortController();
+    externalSignal;
+    externalAbortListener;
+    acceptedHead;
+    projectedRoles = new Map();
+    pending = new Map();
+    // Recovery is bound to this exact candidate. Unrelated admissions may enter
+    // the bounded pending set but can never restore ACTIVE authorization.
+    unavailable;
+    fork;
+    admissionTail = Promise.resolve();
+    constructor(properties) {
+        assertNetworkDescriptorV2(properties.descriptor);
+        const maxPending = properties.maxPending ?? DEFAULT_MAX_PENDING_POLICIES_V2;
+        if (!Number.isSafeInteger(maxPending) || maxPending < 1) {
+            throw new Error("maxPending must be a positive safe integer");
+        }
+        const maxPendingPolicyBytes = properties.maxPendingPolicyBytes ?? DEFAULT_MAX_PENDING_POLICY_BYTES_V2;
+        if (!Number.isSafeInteger(maxPendingPolicyBytes) ||
+            maxPendingPolicyBytes < 1 ||
+            maxPendingPolicyBytes > MAX_PENDING_POLICY_ACCOUNTED_BYTES_V2) {
+            throw new Error(`maxPendingPolicyBytes must be a positive safe integer no greater than ${MAX_PENDING_POLICY_ACCOUNTED_BYTES_V2}`);
+        }
+        const resolveTimeoutMs = properties.resolveTimeoutMs ?? DEFAULT_POLICY_RESOLUTION_TIMEOUT_MS_V2;
+        if (!Number.isSafeInteger(resolveTimeoutMs) ||
+            resolveTimeoutMs < 1 ||
+            resolveTimeoutMs > MAX_TIMER_DELAY_MS_V2) {
+            throw new Error(`resolveTimeoutMs must be a positive safe integer no greater than ${MAX_TIMER_DELAY_MS_V2}`);
+        }
+        this.descriptor = deserialize(serialize(properties.descriptor), NetworkDescriptorV2);
+        this.resolvePolicyEntry = properties.resolvePolicyEntry;
+        this.resolveTimeoutMs = resolveTimeoutMs;
+        this.maxPending = maxPending;
+        this.maxPendingPolicyBytes = maxPendingPolicyBytes;
+        if (properties.signal?.aborted) {
+            this.lifecycleController.abort();
+        }
+        else if (properties.signal !== undefined) {
+            this.externalSignal = properties.signal;
+            this.externalAbortListener = () => {
+                this.externalSignal = undefined;
+                this.externalAbortListener = undefined;
+                this.lifecycleController.abort();
+            };
+            this.externalSignal.addEventListener("abort", this.externalAbortListener, { once: true });
+        }
+    }
+    get state() {
+        if (this.lifecycleController.signal.aborted)
+            return "HALTED";
+        if (this.fork !== undefined)
+            return "FORKED";
+        if (this.unavailable !== undefined)
+            return "UNAVAILABLE";
+        return this.acceptedHead === undefined ? "EMPTY" : "ACTIVE";
+    }
+    get head() {
+        return this.acceptedHead === undefined
+            ? undefined
+            : projectionFromSnapshot(this.acceptedHead);
+    }
+    get forkEvidence() {
+        return this.fork === undefined ? undefined : copyForkEvidence(this.fork);
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+    get pendingBytes() {
+        let total = 0;
+        for (const { snapshot } of this.pending.values()) {
+            total += snapshot.accountedBytes;
+        }
+        return total;
+    }
+    get pendingDigests() {
+        return [...this.pending.values()]
+            .sort((a, b) => compareKeys(a.snapshot.digestKey, b.snapshot.digestKey))
+            .map(({ snapshot }) => copyBytes(snapshot.digest));
+    }
+    rolesFor(subject) {
+        return this.projectedRoles.get(publicKeyId(subject)) ?? 0;
+    }
+    isAuthorized(subject, roles) {
+        if (this.state !== "ACTIVE" ||
+            !Number.isInteger(roles) ||
+            roles === 0 ||
+            (roles & ~TRUSTED_NETWORK_V2_KNOWN_ROLE_BITS) !== 0) {
+            return false;
+        }
+        return (this.rolesFor(subject) & roles) === roles;
+    }
+    abort() {
+        if (this.externalSignal !== undefined &&
+            this.externalAbortListener !== undefined) {
+            this.externalSignal.removeEventListener("abort", this.externalAbortListener);
+        }
+        this.externalSignal = undefined;
+        this.externalAbortListener = undefined;
+        this.lifecycleController.abort();
+    }
+    fetchHints() {
+        const unique = new Map();
+        for (const { missingParentDigest } of this.pending.values()) {
+            unique.set(bytesKey(missingParentDigest), missingParentDigest);
+        }
+        if (this.unavailable !== undefined) {
+            unique.set(bytesKey(this.unavailable.acceptedAncestorDigest), this.unavailable.acceptedAncestorDigest);
+        }
+        return [...unique.entries()]
+            .sort(([a], [b]) => compareKeys(a, b))
+            .map(([, digest]) => ({
+            kind: "policy-parent",
+            digest: copyBytes(digest),
+        }));
+    }
+    result(status, reason, evictedPolicyDigests) {
+        return {
+            status,
+            reason,
+            head: this.head,
+            fetchHints: this.fetchHints(),
+            pendingCount: this.pending.size,
+            pendingBytes: this.pendingBytes,
+            evictedPolicyDigests: evictedPolicyDigests === undefined
+                ? undefined
+                : evictedPolicyDigests.map(copyBytes),
+        };
+    }
+    forkedResult() {
+        return this.result("forked", "Policy authority signed competing children");
+    }
+    haltedResult() {
+        return this.result("halted", "Policy reducer lifecycle is aborted");
+    }
+    unavailableResult(retention) {
+        const blockedCandidateRetained = this.unavailable !== undefined &&
+            this.pending.has(this.unavailable.candidateDigestKey);
+        const recoverable = (retention?.retained ?? true) && blockedCandidateRetained;
+        const reason = recoverable
+            ? this.unavailable.reason
+            : blockedCandidateRetained
+                ? "Policy pending capacity did not retain this candidate"
+                : "Policy reducer remains unavailable because pending capacity did not retain the blocked candidate";
+        return this.result(recoverable ? "unavailable" : "capacity", reason, retention?.evictedPolicyDigests);
+    }
+    completedDrainResult(outcome) {
+        if (outcome?.status === "forked")
+            return this.forkedResult();
+        if (outcome?.status === "halted")
+            return this.haltedResult();
+        return outcome?.status === "unavailable"
+            ? this.unavailableResult(outcome)
+            : undefined;
+    }
+    project(snapshot) {
+        this.acceptedHead = copySnapshot(snapshot);
+        this.projectedRoles = new Map(snapshot.body.bindings.map((binding) => [
+            publicKeyId(binding.signingKey),
+            binding.roles,
+        ]));
+    }
+    retainCanonicalHeadEntry(snapshot) {
+        if (this.acceptedHead?.digestKey === snapshot.digestKey &&
+            compare(snapshot.entryBytes, this.acceptedHead.entryBytes) < 0) {
+            this.acceptedHead = copySnapshot(snapshot);
+        }
+    }
+    async resolveExternalSnapshot(digest) {
+        if (this.lifecycleController.signal.aborted) {
+            throw new PolicyDependencyUnavailableErrorV2("Policy resolver lifecycle is aborted");
+        }
+        const attemptController = new AbortController();
+        let timedOut = false;
+        const abortFromLifecycle = () => attemptController.abort();
+        this.lifecycleController.signal.addEventListener("abort", abortFromLifecycle, { once: true });
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            attemptController.abort();
+        }, this.resolveTimeoutMs);
+        const abortError = () => new PolicyDependencyUnavailableErrorV2(timedOut
+            ? `Policy resolver timed out after ${this.resolveTimeoutMs} ms`
+            : "Policy resolver attempt was aborted");
+        let rejectOnAbort;
+        const abortPromise = new Promise((_resolve, reject) => {
+            rejectOnAbort = () => {
+                reject(abortError());
+            };
+            attemptController.signal.addEventListener("abort", rejectOnAbort, {
+                once: true,
+            });
+        });
+        const resolution = Promise.resolve().then(async () => {
+            if (attemptController.signal.aborted)
+                throw abortError();
+            const entryBytes = await this.resolvePolicyEntry(copyBytes(digest), {
+                signal: attemptController.signal,
+            });
+            // A resolver may ignore cancellation. Do not spend decode or signature
+            // verification work on bytes that arrive after this attempt expired.
+            if (attemptController.signal.aborted)
+                throw abortError();
+            if (entryBytes === undefined)
+                return undefined;
+            const snapshot = await authenticatePolicySnapshotEntryV2(entryBytes, this.descriptor);
+            if (!equals(snapshot.digest, digest)) {
+                throw new Error("Policy resolver returned the wrong body digest");
+            }
+            return snapshot;
+        });
+        // Promise.race installs handlers, but this explicit observer documents and
+        // preserves consumption if the resolver settles after its deadline.
+        void resolution.then(() => undefined, () => undefined);
+        try {
+            return await Promise.race([resolution, abortPromise]);
+        }
+        catch (error) {
+            if (error instanceof PolicyDependencyUnavailableErrorV2)
+                throw error;
+            throw new PolicyDependencyUnavailableErrorV2(`Policy resolver dependency is unavailable: ${validationMessage(error)}`);
+        }
+        finally {
+            clearTimeout(timeout);
+            this.lifecycleController.signal.removeEventListener("abort", abortFromLifecycle);
+            if (rejectOnAbort !== undefined) {
+                attemptController.signal.removeEventListener("abort", rejectOnAbort);
+            }
+        }
+    }
+    async resolveSnapshot(digest, cache) {
+        const digestKey = bytesKey(digest);
+        if (this.acceptedHead?.digestKey === digestKey) {
+            return copySnapshot(this.acceptedHead);
+        }
+        const pending = this.pending.get(digestKey);
+        if (pending !== undefined)
+            return copySnapshot(pending.snapshot);
+        let resolution = cache?.get(digestKey);
+        if (resolution === undefined) {
+            resolution = this.resolveExternalSnapshot(digest);
+            cache?.set(digestKey, resolution);
+        }
+        const snapshot = await resolution;
+        return snapshot === undefined ? undefined : copySnapshot(snapshot);
+    }
+    async parentOf(child, cache) {
+        if (child.body.sequence === 0n) {
+            return {
+                status: "reject",
+                digest: copyBytes(child.body.previousPolicyDigest),
+                reason: "Genesis policy has no parent",
+            };
+        }
+        let parent;
+        try {
+            parent = await this.resolveSnapshot(child.body.previousPolicyDigest, cache);
+        }
+        catch (error) {
+            return {
+                status: "unavailable",
+                digest: copyBytes(child.body.previousPolicyDigest),
+                reason: `Policy parent dependency is unavailable: ${validationMessage(error)}`,
+            };
+        }
+        if (parent === undefined) {
+            return {
+                status: "missing",
+                digest: copyBytes(child.body.previousPolicyDigest),
+            };
+        }
+        if (child.body.sequence !== parent.body.sequence + 1n) {
+            return {
+                status: "reject",
+                digest: copyBytes(child.body.previousPolicyDigest),
+                reason: "Policy sequence is not contiguous with its parent",
+            };
+        }
+        return { status: "found", parent };
+    }
+    candidateAncestryResult(resolution) {
+        return resolution.status === "unavailable"
+            ? {
+                status: "missing",
+                digest: copyBytes(resolution.digest),
+                reason: resolution.reason,
+            }
+            : resolution;
+    }
+    acceptedAncestryUnavailable(resolution) {
+        return {
+            status: "unavailable",
+            digest: copyBytes(resolution.digest),
+            reason: resolution.status === "missing"
+                ? "Accepted policy ancestry is unavailable from the resolver"
+                : resolution.status === "unavailable"
+                    ? `Accepted policy ancestry is unavailable: ${resolution.reason}`
+                    : `Accepted policy ancestry validation failed: ${resolution.reason}`,
+        };
+    }
+    async evaluate(candidate) {
+        const resolutionCache = new Map();
+        if (this.acceptedHead === undefined) {
+            let cursor = candidate;
+            while (cursor.body.sequence !== 0n) {
+                const parent = await this.parentOf(cursor, resolutionCache);
+                if (parent.status !== "found") {
+                    return this.candidateAncestryResult(parent);
+                }
+                cursor = parent.parent;
+            }
+            return { status: "accept" };
+        }
+        let candidateCursor = candidate;
+        let acceptedCursor = this.acceptedHead;
+        let candidateChild;
+        let acceptedChild;
+        while (candidateCursor.body.sequence > acceptedCursor.body.sequence) {
+            candidateChild = candidateCursor;
+            const parent = await this.parentOf(candidateCursor, resolutionCache);
+            if (parent.status !== "found") {
+                return this.candidateAncestryResult(parent);
+            }
+            candidateCursor = parent.parent;
+        }
+        while (acceptedCursor.body.sequence > candidateCursor.body.sequence) {
+            acceptedChild = acceptedCursor;
+            const parent = await this.parentOf(acceptedCursor, resolutionCache);
+            if (parent.status !== "found") {
+                return this.acceptedAncestryUnavailable(parent);
+            }
+            acceptedCursor = parent.parent;
+        }
+        while (!equals(candidateCursor.digest, acceptedCursor.digest)) {
+            if (candidateCursor.body.sequence === 0n ||
+                acceptedCursor.body.sequence === 0n) {
+                return {
+                    status: "reject",
+                    reason: "Policy branches do not share the descriptor genesis",
+                };
+            }
+            candidateChild = candidateCursor;
+            acceptedChild = acceptedCursor;
+            const [candidateParent, acceptedParent] = await Promise.all([
+                this.parentOf(candidateCursor, resolutionCache),
+                this.parentOf(acceptedCursor, resolutionCache),
+            ]);
+            if (acceptedParent.status !== "found") {
+                return this.acceptedAncestryUnavailable(acceptedParent);
+            }
+            if (candidateParent.status !== "found") {
+                return this.candidateAncestryResult(candidateParent);
+            }
+            candidateCursor = candidateParent.parent;
+            acceptedCursor = acceptedParent.parent;
+        }
+        if (candidateChild === undefined) {
+            return { status: "duplicate" };
+        }
+        if (acceptedChild === undefined) {
+            return { status: "accept" };
+        }
+        if (equals(candidateChild.digest, acceptedChild.digest)) {
+            return { status: "duplicate" };
+        }
+        return {
+            status: "fork",
+            commonParent: candidateCursor,
+            candidateChild,
+            acceptedChild,
+        };
+    }
+    setFork(evaluation) {
+        this.project(evaluation.commonParent);
+        const children = [
+            forkProofFromSnapshot(evaluation.candidateChild),
+            forkProofFromSnapshot(evaluation.acceptedChild),
+        ].sort(compareForkChildProofs);
+        this.fork = {
+            commonParent: projectionFromSnapshot(evaluation.commonParent),
+            children,
+        };
+        this.unavailable = undefined;
+        this.pending.clear();
+    }
+    retainCanonicalForkChild(snapshot) {
+        if (this.fork === undefined)
+            return;
+        const byDigest = new Map();
+        for (const proof of [
+            ...this.fork.children,
+            forkProofFromSnapshot(snapshot),
+        ]) {
+            const digestKey = bytesKey(proof.digest);
+            const retained = byDigest.get(digestKey);
+            if (retained === undefined ||
+                compare(proof.entryBytes, retained.entryBytes) < 0) {
+                byDigest.set(digestKey, copyForkChildProof(proof));
+            }
+        }
+        const canonical = [...byDigest.values()]
+            .sort(compareForkChildProofs)
+            .slice(0, 2);
+        if (canonical.length !== 2)
+            return;
+        this.fork.children = [canonical[0], canonical[1]];
+    }
+    observeAfterFork(snapshot) {
+        if (this.fork === undefined || this.acceptedHead === undefined)
+            return;
+        const commonParent = this.acceptedHead;
+        if (snapshot.body.sequence !== commonParent.body.sequence + 1n ||
+            !equals(snapshot.body.previousPolicyDigest, commonParent.digest)) {
+            return;
+        }
+        // This bounded kernel deliberately retains only the canonical two direct
+        // child proofs. Durable storage of every authenticated fork observation is
+        // an outer-layer responsibility for a later integration slice.
+        this.retainCanonicalForkChild(snapshot);
+    }
+    addPending(snapshot, missingParentDigest) {
+        const existing = this.pending.get(snapshot.digestKey);
+        if (existing !== undefined) {
+            existing.missingParentDigest = copyBytes(missingParentDigest);
+            if (snapshot.accountedBytes <= this.maxPendingPolicyBytes &&
+                compare(snapshot.entryBytes, existing.snapshot.entryBytes) < 0) {
+                existing.snapshot = copySnapshot(snapshot);
+            }
+            return { retained: true, evictedPolicyDigests: [] };
+        }
+        if (snapshot.accountedBytes > this.maxPendingPolicyBytes) {
+            return {
+                retained: false,
+                evictedPolicyDigests: [copyBytes(snapshot.digest)],
+            };
+        }
+        this.pending.set(snapshot.digestKey, {
+            snapshot: copySnapshot(snapshot),
+            missingParentDigest: copyBytes(missingParentDigest),
+        });
+        const ordered = [...this.pending.entries()].sort(([a], [b]) => compareKeys(a, b));
+        const retainedKeys = new Set(ordered.slice(0, this.maxPending).map(([key]) => key));
+        const evictedPolicyDigests = [];
+        for (const [key, pending] of ordered) {
+            if (retainedKeys.has(key))
+                continue;
+            evictedPolicyDigests.push(copyBytes(pending.snapshot.digest));
+            this.pending.delete(key);
+        }
+        return {
+            retained: retainedKeys.has(snapshot.digestKey),
+            evictedPolicyDigests,
+        };
+    }
+    enterUnavailable(snapshot, evaluation) {
+        const retention = this.addPending(snapshot, evaluation.digest);
+        this.unavailable = {
+            acceptedAncestorDigest: copyBytes(evaluation.digest),
+            candidateDigestKey: snapshot.digestKey,
+            reason: boundedUnavailableReason(evaluation.reason),
+        };
+        return retention;
+    }
+    async drainPending() {
+        if (this.lifecycleController.signal.aborted) {
+            return { status: "halted" };
+        }
+        let accepted = false;
+        let progress = true;
+        while (progress &&
+            this.pending.size > 0 &&
+            this.fork === undefined &&
+            this.unavailable === undefined) {
+            progress = false;
+            const ordered = [...this.pending.values()].sort((a, b) => compareKeys(a.snapshot.digestKey, b.snapshot.digestKey));
+            for (const pending of ordered) {
+                if (!this.pending.has(pending.snapshot.digestKey))
+                    continue;
+                const evaluation = await this.evaluate(pending.snapshot);
+                if (this.lifecycleController.signal.aborted) {
+                    return { status: "halted" };
+                }
+                if (evaluation.status === "missing") {
+                    pending.missingParentDigest = copyBytes(evaluation.digest);
+                    continue;
+                }
+                if (evaluation.status === "unavailable") {
+                    const retention = this.enterUnavailable(pending.snapshot, evaluation);
+                    return { status: "unavailable", ...retention };
+                }
+                this.pending.delete(pending.snapshot.digestKey);
+                progress = true;
+                if (evaluation.status === "accept") {
+                    this.project(pending.snapshot);
+                    accepted = true;
+                }
+                else if (evaluation.status === "fork") {
+                    this.setFork(evaluation);
+                    return { status: "forked" };
+                }
+            }
+        }
+        return accepted ? { status: "accepted" } : undefined;
+    }
+    enqueueAdmission(operation) {
+        const result = this.admissionTail.then(async () => {
+            if (this.lifecycleController.signal.aborted) {
+                return this.haltedResult();
+            }
+            const admission = await operation();
+            return this.lifecycleController.signal.aborted
+                ? this.haltedResult()
+                : admission;
+        });
+        this.admissionTail = result.then(() => { }, (_reason) => { });
+        return result;
+    }
+    ingest(entryBytes) {
+        if (this.lifecycleController.signal.aborted) {
+            return Promise.resolve(this.haltedResult());
+        }
+        let capturedEntryBytes;
+        try {
+            // Capture at the API boundary, before this admission waits behind earlier
+            // work. Otherwise a caller could mutate a queued entry before validation.
+            capturedEntryBytes = capturePolicySnapshotEntryBytesV2(entryBytes);
+        }
+        catch (error) {
+            const reason = validationMessage(error);
+            return this.enqueueAdmission(async () => this.result("rejected", reason));
+        }
+        return this.enqueueAdmission(() => this.ingestOne(capturedEntryBytes));
+    }
+    retryUnavailable() {
+        return this.enqueueAdmission(() => this.retryUnavailableOne());
+    }
+    async ingestOne(entryBytes) {
+        let snapshot;
+        try {
+            snapshot = await authenticateCapturedPolicySnapshotEntryV2(entryBytes, this.descriptor);
+        }
+        catch (error) {
+            return this.result("rejected", validationMessage(error));
+        }
+        if (this.lifecycleController.signal.aborted)
+            return this.haltedResult();
+        if (this.fork !== undefined) {
+            this.observeAfterFork(snapshot);
+            return this.result("halted", "Policy reducer is halted by authority equivocation");
+        }
+        this.retainCanonicalHeadEntry(snapshot);
+        if (this.unavailable !== undefined) {
+            if (this.acceptedHead?.digestKey === snapshot.digestKey) {
+                return this.result("unavailable", this.unavailable.reason);
+            }
+            const existingPending = this.pending.get(snapshot.digestKey);
+            if (existingPending !== undefined) {
+                this.addPending(snapshot, existingPending.missingParentDigest);
+                return this.result("unavailable", this.unavailable.reason);
+            }
+            const retention = this.addPending(snapshot, this.unavailable.acceptedAncestorDigest);
+            return this.unavailableResult(retention);
+        }
+        const existingPending = this.pending.get(snapshot.digestKey);
+        if (existingPending !== undefined) {
+            this.addPending(snapshot, existingPending.missingParentDigest);
+            return this.result("pending", "Policy snapshot is already pending");
+        }
+        const evaluation = await this.evaluate(snapshot);
+        if (this.lifecycleController.signal.aborted)
+            return this.haltedResult();
+        if (evaluation.status === "reject") {
+            return this.result("rejected", evaluation.reason);
+        }
+        if (evaluation.status === "duplicate") {
+            return this.result("duplicate");
+        }
+        if (evaluation.status === "fork") {
+            this.setFork(evaluation);
+            return this.forkedResult();
+        }
+        if (evaluation.status === "unavailable") {
+            const retention = this.enterUnavailable(snapshot, evaluation);
+            return this.unavailableResult(retention);
+        }
+        if (evaluation.status === "missing") {
+            const pending = this.addPending(snapshot, evaluation.digest);
+            return this.result(pending.retained ? "pending" : "capacity", pending.retained
+                ? (evaluation.reason ?? "Policy parent is missing")
+                : "Policy pending capacity did not retain this candidate", pending.evictedPolicyDigests);
+        }
+        this.project(snapshot);
+        return (this.completedDrainResult(await this.drainPending()) ??
+            this.result("accepted"));
+    }
+    async retryUnavailableOne() {
+        if (this.lifecycleController.signal.aborted)
+            return this.haltedResult();
+        if (this.fork !== undefined) {
+            return this.result("halted", "Policy reducer is halted by authority equivocation");
+        }
+        const unavailable = this.unavailable;
+        if (unavailable === undefined) {
+            return this.result("duplicate", "Policy reducer is not unavailable");
+        }
+        const pending = this.pending.get(unavailable.candidateDigestKey);
+        if (pending === undefined) {
+            return this.result("capacity", "Unavailable comparison candidate is not retained; re-ingest it before retrying");
+        }
+        const evaluation = await this.evaluate(pending.snapshot);
+        if (this.lifecycleController.signal.aborted)
+            return this.haltedResult();
+        if (evaluation.status === "unavailable") {
+            pending.missingParentDigest = copyBytes(evaluation.digest);
+            this.unavailable = {
+                acceptedAncestorDigest: copyBytes(evaluation.digest),
+                candidateDigestKey: pending.snapshot.digestKey,
+                reason: boundedUnavailableReason(evaluation.reason),
+            };
+            return this.result("unavailable", this.unavailable.reason);
+        }
+        this.unavailable = undefined;
+        let status;
+        let reason;
+        if (evaluation.status === "missing") {
+            pending.missingParentDigest = copyBytes(evaluation.digest);
+            status = "pending";
+            reason = evaluation.reason ?? "Policy parent is missing";
+        }
+        else {
+            this.pending.delete(pending.snapshot.digestKey);
+            if (evaluation.status === "fork") {
+                this.setFork(evaluation);
+                return this.forkedResult();
+            }
+            if (evaluation.status === "accept") {
+                this.project(pending.snapshot);
+                status = "accepted";
+            }
+            else if (evaluation.status === "duplicate") {
+                status = "duplicate";
+            }
+            else {
+                status = "rejected";
+                reason = evaluation.reason;
+            }
+        }
+        return (this.completedDrainResult(await this.drainPending()) ??
+            this.result(status, reason));
+    }
+}
+//# sourceMappingURL=v2-policy-engine.js.map