@sentropic/h2a-runtime 0.98.6 → 0.98.7-rc.2

package/dist/vendor/engram-live/registration.js

@@ -0,0 +1,358 @@
+// Vendored from rhanka/engram@545a57b8911ab108e84fa1778e0f268fe11bf1de: engram-live/registration.ts.
+// Compiled with TypeScript 5.9.3 (ES2022/NodeNext, declarations); do not hand-edit.
+// @sentropic/engram-live/registration — pure neutral registration helpers
+// (spec/SPEC_LIVE_GIT_INDEXING.md §§2–3, 10, 12; plan/09 L6a; owner Q4 A).
+//
+// Pure functions over ./contracts.js DTOs: declaration creation, revision,
+// revocation, the ONE canonical clone/worktree/declaration identity
+// derivation, clone equality and lifecycle classification. No host state, no
+// storage, no network, no projection provider: every function is
+// deterministic over its arguments, never mutates its inputs, and keeps no
+// module-level mutable state. Durable declarations, replay, cancellation
+// and purge execution belong to the h2a (H) and cluster-mesh/sentropic (S)
+// hosts consuming the contract documented in ./contracts.js.
+//
+// Both seats mint their opaque ids through these functions (canonicalIdKey
+// in ./contracts.js + the sha256 minting below): identical identity
+// components give byte-identical cloneId/worktreeId/declarationId on every
+// side, so identity equality is comparison by canonical identifier. h2a
+// identifiers persisted before this freeze were derived from
+// newline-joined components; re-derive and rewrite them locally
+// (see the MIGRATION note in ./contracts.js).
+import { createHash } from "node:crypto";
+import { ID_PREFIXES, IDENTITY_UNCERTAINTY_STATES, canonicalIdKey, isIdentityUncertaintyState, isNonActivatingLifecycleKind, isRevocationReason, normalizeCommonDirRealpath, validateCloneIdentity, validateDeclarationRevocation, validateWorkspaceDeclaration, validateWorktreeIdentity, INITIAL_BINDING_REVISION, INITIAL_DECLARATION_REVISION, } from "./contracts.js";
+const LIVE_DECLARATION_PATCH_KEYS = [
+    "authorizedRoots",
+    "policyVersion",
+    "serverWorkspaceId",
+    "serverIssuer",
+    "bindingRevision",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isCloneIdReference(value) {
+    return isNonEmptyString(value) && value.startsWith(ID_PREFIXES.clone);
+}
+function isWorktreeIdReference(value) {
+    return isNonEmptyString(value) && value.startsWith(ID_PREFIXES.worktree);
+}
+function sha256Hex(canonical) {
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+function checkUncertainty(uncertainty) {
+    const states = [...(uncertainty ?? [])];
+    if (states.some((state) => !isIdentityUncertaintyState(state))) {
+        throw new Error(`identity uncertainty states must be one of ${IDENTITY_UNCERTAINTY_STATES.join(", ")}`);
+    }
+    return states;
+}
+/**
+ * Create the initial live declaration for one workspace. Requires the
+ * explicit "live" capability and the full identity triangle
+ * (declarationId/cloneId/worktreeId, minted by the canonical derivation
+ * below): any other opt-in value (bind, upload, session kinds) is refused,
+ * so no lifecycle event can implicitly activate live. The declaration
+ * revision starts at the frozen INITIAL_DECLARATION_REVISION.
+ */
+export function createLiveDeclaration(input) {
+    if (!isRecord(input)) {
+        throw new Error("createLiveDeclaration requires a declaration input object");
+    }
+    const declaration = {
+        tenant: input.tenant,
+        principal: input.principal,
+        ...(input.hostFingerprint !== undefined ? { hostFingerprint: input.hostFingerprint } : {}),
+        identityUncertainty: [...input.identityUncertainty],
+        declarationId: input.declarationId,
+        cloneId: input.cloneId,
+        worktreeId: input.worktreeId,
+        authorizedRoots: [...input.authorizedRoots],
+        liveCapability: input.liveCapability,
+        policyVersion: input.policyVersion,
+        declarationRevision: INITIAL_DECLARATION_REVISION,
+        ...(input.serverWorkspaceId !== undefined ? { serverWorkspaceId: input.serverWorkspaceId } : {}),
+        ...(input.serverIssuer !== undefined ? { serverIssuer: input.serverIssuer } : {}),
+        ...(input.bindingRevision !== undefined ? { bindingRevision: input.bindingRevision } : {}),
+    };
+    if (input.bindingRevision !== undefined && input.bindingRevision !== INITIAL_BINDING_REVISION) {
+        throw new Error(`createLiveDeclaration requires the first product binding to carry bindingRevision ${INITIAL_BINDING_REVISION} (FROZEN L6a convention; rebinds and revalidations grow strictly from there)`);
+    }
+    const checked = validateWorkspaceDeclaration(declaration);
+    if (!checked.ok) {
+        throw new Error(`invalid live workspace declaration: ${checked.errors.join("; ")}`);
+    }
+    return declaration;
+}
+/**
+ * Revise a declaration as a pure revision increment. The revision grows by
+ * exactly one; tenant, principal, hostFingerprint, the identity triangle
+ * and the live capability are immutable. The product binding is the
+ * complete (serverWorkspaceId, serverIssuer, bindingRevision) triplet.
+ * A revision outside the binding (roots, policy version) PRESERVES the
+ * binding: no renewal is imposed. Only a change of serverWorkspaceId or
+ * serverIssuer, or an explicit bindingRevision revalidation, renews the
+ * binding — and then strictly increasingly: the first binding carries
+ * exactly INITIAL_BINDING_REVISION, and every rebind/revalidation carries
+ * a strictly greater bindingRevision; binding revisions never go
+ * backwards. The host must additionally refuse to redirect in-flight
+ * collection/publication when a rebind lands.
+ */
+export function reviseLiveDeclaration(previous, patch) {
+    const previousCheck = validateWorkspaceDeclaration(previous);
+    if (!previousCheck.ok) {
+        throw new Error(`invalid previous declaration: ${previousCheck.errors.join("; ")}`);
+    }
+    if (!isRecord(patch)) {
+        throw new Error("reviseLiveDeclaration requires a patch object");
+    }
+    const patchRecord = patch;
+    for (const key of Object.keys(patchRecord)) {
+        if (!LIVE_DECLARATION_PATCH_KEYS.includes(key)) {
+            throw new Error(`reviseLiveDeclaration refuses patch key "${key}": identity fields are immutable across revisions`);
+        }
+    }
+    const workspaceChanged = patch.serverWorkspaceId !== undefined &&
+        patch.serverWorkspaceId !== previous.serverWorkspaceId;
+    const issuerChanged = patch.serverIssuer !== undefined &&
+        patch.serverIssuer !== previous.serverIssuer;
+    const bindingTouched = patch.bindingRevision !== undefined || workspaceChanged || issuerChanged;
+    // A revision outside the product binding preserves it; only a workspace or
+    // issuer change, or an explicit revalidation, renews it — strictly
+    // increasingly, starting the first binding at INITIAL_BINDING_REVISION.
+    let nextBindingRevision = previous.bindingRevision;
+    if (bindingTouched) {
+        if (patch.bindingRevision === undefined) {
+            throw new Error("reviseLiveDeclaration requires a fresh strictly increasing bindingRevision when the server workspace or issuer changes (revalidation)");
+        }
+        if (previous.bindingRevision === undefined) {
+            if (patch.bindingRevision !== INITIAL_BINDING_REVISION) {
+                throw new Error(`reviseLiveDeclaration requires the first product binding to carry bindingRevision ${INITIAL_BINDING_REVISION} (FROZEN L6a convention)`);
+            }
+        }
+        else if (patch.bindingRevision <= previous.bindingRevision) {
+            throw new Error("reviseLiveDeclaration requires a strictly increasing bindingRevision (binding revisions are monotonic)");
+        }
+        nextBindingRevision = patch.bindingRevision;
+    }
+    const next = {
+        ...previous,
+        authorizedRoots: patch.authorizedRoots !== undefined ? [...patch.authorizedRoots] : [...previous.authorizedRoots],
+        policyVersion: patch.policyVersion !== undefined ? patch.policyVersion : previous.policyVersion,
+        serverWorkspaceId: patch.serverWorkspaceId !== undefined
+            ? patch.serverWorkspaceId
+            : previous.serverWorkspaceId,
+        serverIssuer: patch.serverIssuer !== undefined ? patch.serverIssuer : previous.serverIssuer,
+        bindingRevision: nextBindingRevision,
+        declarationRevision: previous.declarationRevision + 1,
+    };
+    const checked = validateWorkspaceDeclaration(next);
+    if (!checked.ok) {
+        throw new Error(`invalid revised declaration: ${checked.errors.join("; ")}`);
+    }
+    return next;
+}
+/**
+ * Revoke exactly one declaration as a pure private-purge request. The
+ * returned DTO names the single target by its opaque declarationId and
+ * carries the declaration's cloneId/worktreeId attachment and revision, so
+ * the recipient can never confuse two declarations of one tenant that
+ * happen to share public fingerprints or revisions. The host stops work,
+ * rejects delayed jobs and purges private snapshots, derived indexes and
+ * decryptability, while preserving authorized committed history.
+ * Revocation deletes no committed facts.
+ */
+export function revokeLiveDeclaration(declaration, reason) {
+    const checked = validateWorkspaceDeclaration(declaration);
+    if (!checked.ok) {
+        throw new Error(`invalid declaration: ${checked.errors.join("; ")}`);
+    }
+    if (!isRevocationReason(reason)) {
+        throw new Error(`invalid revocation reason: ${String(reason)}`);
+    }
+    const revocation = {
+        declarationId: declaration.declarationId,
+        tenant: declaration.tenant,
+        cloneId: declaration.cloneId,
+        worktreeId: declaration.worktreeId,
+        declarationRevision: declaration.declarationRevision,
+        reason,
+        requestPrivatePurge: {
+            purgePrivateSnapshots: true,
+            purgeDerivedIndexes: true,
+            revokeDecryptability: true,
+            preserveCommittedHistory: true,
+        },
+    };
+    const revocationCheck = validateDeclarationRevocation(revocation);
+    if (!revocationCheck.ok) {
+        throw new Error(`invalid revocation: ${revocationCheck.errors.join("; ")}`);
+    }
+    return revocation;
+}
+/**
+ * Derive the clone identity for one common-dir — the ONE canonical clone
+ * derivation. The key components (hostScope, normalized common-dir
+ * realpath, common-dir project fingerprint) serialize through
+ * canonicalIdKey (unambiguous, NUL-refusing) and hash to the opaque
+ * cloneId: equal fingerprints under different realpaths derive distinct
+ * clones, while linked worktrees sharing one common-dir derive the same
+ * clone. The fingerprint may be absent only under explicit
+ * "missing_history" uncertainty; the hostScope + realpath components keep
+ * clones distinct even then (LIVE §12). The realpath stays host-local;
+ * only cloneId is shared. Deterministic and free of I/O.
+ */
+export function deriveCloneIdentity(input) {
+    if (!isRecord(input)) {
+        throw new Error("deriveCloneIdentity requires a clone input object");
+    }
+    if (!isNonEmptyString(input.hostScope)) {
+        throw new Error("deriveCloneIdentity requires a non-empty hostScope");
+    }
+    if (!isNonEmptyString(input.commonDirRealpath)) {
+        throw new Error("deriveCloneIdentity requires a non-empty commonDirRealpath");
+    }
+    const uncertainty = checkUncertainty(input.identityUncertainty);
+    if (input.commonDirProjectFingerprint !== undefined &&
+        !isNonEmptyString(input.commonDirProjectFingerprint)) {
+        throw new Error("deriveCloneIdentity requires a non-empty commonDirProjectFingerprint when present");
+    }
+    if (input.commonDirProjectFingerprint === undefined &&
+        !uncertainty.includes("missing_history")) {
+        throw new Error('deriveCloneIdentity omits commonDirProjectFingerprint only under explicit "missing_history" uncertainty');
+    }
+    if (input.oidAlgorithm !== "sha1" && input.oidAlgorithm !== "sha256") {
+        throw new Error('deriveCloneIdentity requires oidAlgorithm "sha1" or "sha256"');
+    }
+    const normalizedRealpath = normalizeCommonDirRealpath(input.commonDirRealpath);
+    // canonicalIdKey refuses NUL inside any component.
+    const canonical = canonicalIdKey("clone", [
+        input.hostScope,
+        normalizedRealpath,
+        input.commonDirProjectFingerprint ?? "",
+    ]);
+    const identity = {
+        hostScope: input.hostScope,
+        commonDirRealpath: normalizedRealpath,
+        ...(input.commonDirProjectFingerprint !== undefined
+            ? { commonDirProjectFingerprint: input.commonDirProjectFingerprint }
+            : {}),
+        cloneId: `${ID_PREFIXES.clone}${sha256Hex(canonical)}`,
+        oidAlgorithm: input.oidAlgorithm,
+        identityUncertainty: [...uncertainty],
+    };
+    const checked = validateCloneIdentity(identity);
+    if (!checked.ok) {
+        throw new Error(`invalid derived clone identity: ${checked.errors.join("; ")}`);
+    }
+    return identity;
+}
+/**
+ * Derive the identity of one worktree under an already derived clone —
+ * the ONE canonical worktree derivation. Worktrees of one clone share
+ * cloneId and keep an isolated host-scoped worktreeId plus per-worktree
+ * git-dir, fingerprint and path. The worktree fingerprint may be absent
+ * only under explicit "missing_history" uncertainty (LIVE §12).
+ */
+export function deriveWorktreeIdentity(input) {
+    if (!isRecord(input)) {
+        throw new Error("deriveWorktreeIdentity requires a worktree input object");
+    }
+    if (!isRecord(input.clone) || !isCloneIdReference(input.clone.cloneId)) {
+        throw new Error("deriveWorktreeIdentity requires a derived clone carrying a canonical cloneId");
+    }
+    if (!isNonEmptyString(input.hostScope)) {
+        throw new Error("deriveWorktreeIdentity requires a non-empty hostScope");
+    }
+    if (!isNonEmptyString(input.worktreePath)) {
+        throw new Error("deriveWorktreeIdentity requires a non-empty worktreePath");
+    }
+    if (!isNonEmptyString(input.gitDir)) {
+        throw new Error("deriveWorktreeIdentity requires a non-empty gitDir");
+    }
+    const uncertainty = checkUncertainty(input.identityUncertainty);
+    if (input.worktreeFingerprint !== undefined &&
+        !isNonEmptyString(input.worktreeFingerprint)) {
+        throw new Error("deriveWorktreeIdentity requires a non-empty worktreeFingerprint when present");
+    }
+    if (input.worktreeFingerprint === undefined && !uncertainty.includes("missing_history")) {
+        throw new Error('deriveWorktreeIdentity omits worktreeFingerprint only under explicit "missing_history" uncertainty');
+    }
+    const canonical = canonicalIdKey("worktree", [input.hostScope, input.gitDir]);
+    const identity = {
+        cloneId: input.clone.cloneId,
+        worktreeId: `${ID_PREFIXES.worktree}${sha256Hex(canonical)}`,
+        worktreePath: input.worktreePath,
+        gitDir: input.gitDir,
+        ...(input.worktreeFingerprint !== undefined
+            ? { worktreeFingerprint: input.worktreeFingerprint }
+            : {}),
+        identityUncertainty: [...uncertainty],
+    };
+    const checked = validateWorktreeIdentity(identity);
+    if (!checked.ok) {
+        throw new Error(`invalid derived worktree identity: ${checked.errors.join("; ")}`);
+    }
+    return identity;
+}
+/**
+ * Derive the identity of one declaration — the ONE canonical declaration
+ * derivation. One declaration per activated worktree: the declarationId
+ * binds the host scope, the clone and the worktree, so two worktrees of
+ * one clone (and two clones of one project) derive distinct declarationIds
+ * even without fingerprints. Stable across every revision of the same
+ * declaration. Deterministic and free of I/O.
+ */
+export function deriveDeclarationIdentity(input) {
+    if (!isRecord(input)) {
+        throw new Error("deriveDeclarationIdentity requires a declaration identity input object");
+    }
+    if (!isRecord(input.clone) || !isCloneIdReference(input.clone.cloneId)) {
+        throw new Error("deriveDeclarationIdentity requires a derived clone carrying a canonical cloneId");
+    }
+    if (!isRecord(input.worktree) || !isWorktreeIdReference(input.worktree.worktreeId)) {
+        throw new Error("deriveDeclarationIdentity requires a derived worktree carrying a canonical worktreeId");
+    }
+    if (!isNonEmptyString(input.hostScope)) {
+        throw new Error("deriveDeclarationIdentity requires a non-empty hostScope");
+    }
+    const canonical = canonicalIdKey("declaration", [
+        input.hostScope,
+        input.clone.cloneId,
+        input.worktree.worktreeId,
+    ]);
+    const identity = {
+        declarationId: `${ID_PREFIXES.declaration}${sha256Hex(canonical)}`,
+        cloneId: input.clone.cloneId,
+        worktreeId: input.worktree.worktreeId,
+    };
+    return identity;
+}
+/**
+ * Decide whether two clone references denote the same clone, by canonical
+ * identifier only: the cloneId minted by the shared canonical derivation is
+ * the clone identity, so the comparison is an equivalence (transitive and
+ * consistent between full DTOs and opaque references). Throws when either
+ * reference lacks a cloneId — equality is never guessed from components.
+ */
+export function isSameClone(a, b) {
+    if (!isNonEmptyString(a.cloneId) || !isNonEmptyString(b.cloneId)) {
+        throw new Error("isSameClone compares canonical clone ids: both references must carry a non-empty cloneId");
+    }
+    return a.cloneId === b.cloneId;
+}
+/**
+ * Classify a host lifecycle event against live declarations. Bind, upload,
+ * code-workspace creation and session open/end never activate or remove a
+ * declaration: the only outcome is "no-activation-change". Unknown kinds
+ * are refused.
+ */
+export function classifyLifecycleEvent(kind) {
+    if (!isNonActivatingLifecycleKind(kind)) {
+        throw new Error(`unknown lifecycle kind: ${String(kind)}`);
+    }
+    return "no-activation-change";
+}

package/dist/vendor/engram-live/retention.d.ts

@@ -0,0 +1,56 @@
+// Vendored from rhanka/engram@545a57b8911ab108e84fa1778e0f268fe11bf1de: engram-live/retention.ts.
+// Compiled with TypeScript 5.9.3 (ES2022/NodeNext, declarations); do not hand-edit.
+import { type LiveScope, type RetentionCoverageReportDto, type RetentionReceiptDto, type RetentionReceiptQuery, type RetentionRequestDto, type SelectedRootDto } from "./contracts.js";
+export declare class RetentionError extends Error {
+    constructor(message: string);
+}
+/**
+ * THE injected retention port (plan/09 R1: a port, never a base). Engram
+ * defines the contract only; h2a implements durable acquisition and the
+ * private store behind it. Receipts are scoped by tenant + clone and
+ * durable across passes; the port never carries file content.
+ */
+export interface RetentionPort {
+    recordRequest(request: RetentionRequestDto): Promise<{
+        received: true;
+    }>;
+    recordReceipt(receipt: RetentionReceiptDto): Promise<{
+        received: true;
+    }>;
+    loadReceipts(query: RetentionReceiptQuery): Promise<{
+        receipts: readonly RetentionReceiptDto[];
+    }>;
+}
+export interface RetentionPassInput {
+    readonly roots: readonly SelectedRootDto[];
+    readonly scope: LiveScope;
+    /** Injected evaluation time for requestedAt (ms); the engine reads no clock. */
+    readonly now: number;
+}
+export interface RetentionPassStats {
+    readonly requests: number;
+    readonly receipts: number;
+    readonly missing: number;
+}
+export interface RetentionPassOutcome {
+    /** "complete": every request has its scoped durable receipt. "gaps": otherwise. */
+    readonly state: "complete" | "gaps";
+    readonly requests: readonly RetentionRequestDto[];
+    readonly coverage: readonly RetentionCoverageReportDto[];
+    readonly stats: RetentionPassStats;
+}
+/**
+ * Derive one retention request per distinct root OID, sorted by OID.
+ * Pure and total over valid inputs: no count cap, no age filter, no
+ * pruning — an old default branch, an expired window branch kept as a
+ * previously-ingested root, a PR head of any state and a detached HEAD
+ * each yield exactly one request.
+ */
+export declare function deriveRetentionRequests(roots: readonly SelectedRootDto[], scope: LiveScope, now: number): RetentionRequestDto[];
+/**
+ * Run one retention pass: record every request, then require every scoped
+ * durable receipt. Deterministic over the injected inputs; the port is the
+ * only effect. A receipt satisfies a request only under the exact same
+ * tenant, clone, algorithm and OID; cross-scope receipts never satisfy.
+ */
+export declare function runRetentionPass(input: RetentionPassInput, port: RetentionPort): Promise<RetentionPassOutcome>;

package/dist/vendor/engram-live/retention.js

@@ -0,0 +1,179 @@
+// Vendored from rhanka/engram@545a57b8911ab108e84fa1778e0f268fe11bf1de: engram-live/retention.ts.
+// Compiled with TypeScript 5.9.3 (ES2022/NodeNext, declarations); do not hand-edit.
+// @sentropic/engram-live/retention — R1 private retention of every ingested root
+// (spec/SPEC_LIVE_GIT_INDEXING.md §4, A02/A04; plan/09 R1).
+//
+// The neutral retention engine. Engram derives one scoped retention request
+// per distinct ingested root OID and requires one scoped durable receipt
+// before any reconstructible-coverage claim:
+//
+//   1. derive the requests from the L2b selected roots (./refs.js): default
+//      branch even when old, active local/remote branches, PR heads of all
+//      states, detached worktree HEADs, previously ingested roots — with no
+//      commit-count and no commit-age limit, and nothing ever erased here;
+//   2. record every request through the INJECTED retention port (a port,
+//      never a base; engram owns no database and no object store);
+//   3. load the scoped durable receipts from that same port and classify
+//      coverage: every request needs its tenant + clone receipt; a missing
+//      receipt is an explicit object-availability gap, never a silent
+//      current claim.
+//
+// Neutrality: this module imports ONLY ./contracts.js (data-pure DTOs and
+// validators). No h2a, no cluster-mesh, no sentropic, no storage driver,
+// no network, no filesystem, no clock read — the evaluation time `now` is
+// injected, and durability comes from the host port alone.
+//
+// Host contract (H: live-object-store.ts, delegate.ts — NOT implemented
+// here): h2a consumes RetentionRequestDto through RetentionPort, acquires
+// the pinned committed objects into its protected private Git store under
+// private refs (no writes into the observed clone, no borrowed alternates
+// store, no repository-controlled programs), then records a
+// RetentionReceiptDto with an opaque coordinated-backup backupRef for L8.
+// If removal wins the acquisition race, H records no receipt and the engine
+// reports the gap; quotas pause further work without deleting protected
+// roots. P1 reuses this facility for PR roots. Uncommitted plaintext never
+// enters a request or a receipt: requests carry OIDs only, by construction.
+import { RETENTION_COVERAGE_AXIS, validateLiveScope, validateQualifiedOid, validateRetentionReceipt, validateRetentionRequest, } from "./contracts.js";
+export class RetentionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RetentionError";
+    }
+}
+function checkScope(scope) {
+    const checked = validateLiveScope(scope);
+    if (!checked.ok) {
+        throw new RetentionError(`invalid retention scope: ${checked.errors.join("; ")}`);
+    }
+    if (scope.worktree !== undefined) {
+        throw new RetentionError("retention scope must be clone-scoped: worktree must be absent (retention is per tenant + clone)");
+    }
+}
+function checkNow(now) {
+    if (typeof now !== "number" || !Number.isSafeInteger(now) || now <= 0) {
+        throw new RetentionError("retention pass requires a positive safe-integer now (milliseconds)");
+    }
+}
+/**
+ * Derive one retention request per distinct root OID, sorted by OID.
+ * Pure and total over valid inputs: no count cap, no age filter, no
+ * pruning — an old default branch, an expired window branch kept as a
+ * previously-ingested root, a PR head of any state and a detached HEAD
+ * each yield exactly one request.
+ */
+export function deriveRetentionRequests(roots, scope, now) {
+    checkScope(scope);
+    checkNow(now);
+    // Immutable snapshot: the caller-owned scope object may be shared and
+    // mutated while the pass awaits the port; every derived request carries
+    // the pass-entry scope, never a later mutation.
+    const frozen = { tenant: scope.tenant, clone: scope.clone };
+    const seen = new Set();
+    const requests = [];
+    for (const root of roots) {
+        const checked = validateQualifiedOid(root.qualifiedOid);
+        if (!checked.ok) {
+            throw new RetentionError(`invalid root OID ${root.qualifiedOid.oid}: ${checked.errors.join("; ")}`);
+        }
+        if (seen.has(root.qualifiedOid.oid))
+            continue;
+        seen.add(root.qualifiedOid.oid);
+        if (root.sources.length === 0) {
+            throw new RetentionError(`root ${root.qualifiedOid.oid} carries no provenance source`);
+        }
+        const first = root.sources[0];
+        const refBacked = root.sources.find((source) => source.refName !== null);
+        const request = {
+            scope: { tenant: frozen.tenant, clone: frozen.clone },
+            algorithm: root.qualifiedOid.algorithm,
+            oid: root.qualifiedOid.oid,
+            firstSignal: first.signal,
+            refName: refBacked !== undefined ? refBacked.refName : null,
+            requestedAt: now,
+        };
+        const valid = validateRetentionRequest(request);
+        if (!valid.ok) {
+            throw new RetentionError(`derived invalid retention request for ${request.oid}: ${valid.errors.join("; ")}`);
+        }
+        requests.push(request);
+    }
+    requests.sort((left, right) => left.oid.localeCompare(right.oid));
+    return requests;
+}
+function receiptKey(receipt) {
+    return `${receipt.scope.tenant}:${receipt.scope.clone}:${receipt.algorithm}:${receipt.oid}`;
+}
+/**
+ * Run one retention pass: record every request, then require every scoped
+ * durable receipt. Deterministic over the injected inputs; the port is the
+ * only effect. A receipt satisfies a request only under the exact same
+ * tenant, clone, algorithm and OID; cross-scope receipts never satisfy.
+ */
+export async function runRetentionPass(input, port) {
+    checkScope(input.scope);
+    checkNow(input.now);
+    // Immutable snapshot taken before the first await: the caller-owned
+    // input.scope object may be shared and mutated while the pass awaits the
+    // port. Every query, receipt check and missing-key below uses this
+    // pass-entry scope; re-reading input.scope after an await would let a
+    // foreign-scope receipt falsely satisfy a request (false acquittement).
+    const scope = { tenant: input.scope.tenant, clone: input.scope.clone };
+    const requests = deriveRetentionRequests(input.roots, scope, input.now);
+    for (const request of requests) {
+        await port.recordRequest(request);
+    }
+    const algorithms = new Set();
+    for (const request of requests)
+        algorithms.add(request.algorithm);
+    const receipts = [];
+    if (algorithms.size === 0) {
+        return { state: "complete", requests, coverage: [], stats: { requests: 0, receipts: 0, missing: 0 } };
+    }
+    for (const algorithm of algorithms) {
+        const loaded = await port.loadReceipts({ scope, algorithm });
+        for (const receipt of loaded.receipts) {
+            const checked = validateRetentionReceipt(receipt);
+            if (!checked.ok) {
+                throw new RetentionError(`invalid retention receipt for ${receipt.oid}: ${checked.errors.join("; ")}`);
+            }
+            // The port is scoped by the query, but the engine re-checks scope:
+            // a foreign receipt that slipped through never satisfies a request.
+            if (receipt.scope.tenant !== scope.tenant || receipt.scope.clone !== scope.clone)
+                continue;
+            if (receipt.algorithm !== algorithm)
+                continue;
+            receipts.push(receipt);
+        }
+    }
+    const byKey = new Map();
+    for (const receipt of receipts)
+        byKey.set(receiptKey(receipt), receipt);
+    const missing = [];
+    for (const request of requests) {
+        const key = `${scope.tenant}:${scope.clone}:${request.algorithm}:${request.oid}`;
+        if (!byKey.has(key))
+            missing.push({ algorithm: request.algorithm, oid: request.oid });
+    }
+    missing.sort((left, right) => left.oid.localeCompare(right.oid));
+    if (missing.length === 0) {
+        return {
+            state: "complete",
+            requests,
+            coverage: [],
+            stats: { requests: requests.length, receipts: byKey.size, missing: 0 },
+        };
+    }
+    const preview = missing.slice(0, 3).map((entry) => entry.oid.slice(0, 12)).join(", ");
+    return {
+        state: "gaps",
+        requests,
+        coverage: [{
+                axis: RETENTION_COVERAGE_AXIS,
+                state: "unavailable",
+                reason: `private retention incomplete: ${missing.length} of ${requests.length} ingested root(s) without a scoped durable retention receipt (${preview}…); no reconstructible coverage is claimed and nothing was pruned`,
+                cause: "missing-receipt",
+                missing,
+            }],
+        stats: { requests: requests.length, receipts: byKey.size, missing: missing.length },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/h2a-runtime",
-  "version": "0.98.6",
+  "version": "0.98.7-rc.2",
   "type": "module",
   "exports": {
     ".": {
@@ -54,6 +54,6 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "node ../../scripts/clean-workspace-dist.mjs && tsc -b --force"
+    "build": "node ../../scripts/clean-workspace-dist.mjs && tsc -b --force && node ../../scripts/copy-vendored-engram-live.mjs"
   }
 }