@sentropic/h2a-runtime 0.98.7-rc.1 → 0.98.7-rc.3

package/dist/vendor/engram-live/pr-sync.js

@@ -0,0 +1,411 @@
+// @sentropic/engram-live/pr-sync — P1 neutral PR/object sync engine
+// (spec/SPEC_LIVE_GIT_INDEXING.md §§4–5; plan/09 P1).
+//
+// Pagination/overlap/full-sweep reconciliation plus neutral PR/object jobs
+// over INJECTED ports only: the GitHub page transport and the durable
+// persistence are host-supplied fakes here (H/S implement production sides).
+// Engram performs no network call, persists no token, invokes no
+// repository-selected credential helper, and applies no count or age limit:
+// every page is consumed, every state indexed, nothing erased.
+import { PR_END_PROOF, validatePrPage, validatePrSyncCursor, validatePullRequestFact, } from "./contracts.js";
+/** Neutral PR sync extractor version (checkpoints are per version). */
+export const PR_SYNC_EXTRACTOR_VERSION = "engram-live/pr-sync/1";
+/**
+ * Overlap re-ask on incremental retries (milliseconds): the resume window
+ * re-reads recently updated PRs so a page that moved during enumeration is
+ * deduplicated instead of lost. Pure constant, consumed by hosts.
+ */
+export const PR_SYNC_OVERLAP_MS = 5 * 60 * 1000;
+export class PrSyncError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "PrSyncError";
+        this.kind = kind;
+    }
+}
+/**
+ * Identity of one persisted observation: the complete observed fact. Two
+ * rows sharing one head OID but differing by state, draft flag, refs, base,
+ * merge evidence or timestamp are different observations and all persist;
+ * only a byte-identical repeat collapses. The (PR, head OID) key is reserved
+ * for object-job deduplication (objectJobIdentityKey), never for dropping
+ * observations.
+ */
+export function observationIdentityKey(fact) {
+    const mergeOid = fact.mergeOid ?? null;
+    return JSON.stringify([
+        fact.repositoryOwner,
+        fact.repositoryRepo,
+        fact.number,
+        fact.state,
+        fact.isDraft,
+        fact.updatedAt,
+        fact.headOid.algorithm,
+        fact.headOid.oid,
+        fact.headRef,
+        fact.baseOid.algorithm,
+        fact.baseOid.oid,
+        fact.baseRef,
+        mergeOid === null ? null : [mergeOid.algorithm, mergeOid.oid],
+        fact.mergeStrategy ?? null,
+    ]);
+}
+/**
+ * Identity of one object-acquisition job: the PR plus the observed head OID.
+ * Two jobs for one PR with different heads are different rows; recording
+ * head B never replaces head A's job, failures or receipts.
+ */
+export function objectJobIdentityKey(job) {
+    return `${job.repositoryOwner}/${job.repositoryRepo}#${job.prNumber}@${job.headOid.algorithm}:${job.headOid.oid}`;
+}
+/**
+ * Deduplicate exact observation repeats by complete observation identity,
+ * keeping one row per distinct fact. Observations whose metadata differs
+ * (state, base, merge evidence, timestamp, …) are all kept: this is the
+ * persistence rule (nothing erased), not the current view.
+ */
+export function deduplicatePrObservations(items) {
+    const kept = new Map();
+    for (const item of items) {
+        const checked = validatePullRequestFact(item);
+        if (!checked.ok) {
+            throw new PrSyncError("protocol", `invalid PR item #${item.number}: ${checked.errors.join("; ")}`);
+        }
+        const key = observationIdentityKey(item);
+        if (!kept.has(key)) {
+            kept.set(key, item);
+        }
+    }
+    return [...kept.values()].sort((left, right) => left.number - right.number || left.updatedAt - right.updatedAt);
+}
+/**
+ * Current view over observations: one row per PR identity
+ * (owner/repo/number), keeping the newest updatedAt record. Computed
+ * separately AFTER every distinct observation is retained, so the live head
+ * never erases the observed history.
+ */
+export function deduplicatePrPageItems(items) {
+    const newest = new Map();
+    for (const item of items) {
+        const checked = validatePullRequestFact(item);
+        if (!checked.ok) {
+            throw new PrSyncError("protocol", `invalid PR item #${item.number}: ${checked.errors.join("; ")}`);
+        }
+        const key = `${item.repositoryOwner}/${item.repositoryRepo}#${item.number}`;
+        const previous = newest.get(key);
+        if (previous === undefined || item.updatedAt >= previous.updatedAt) {
+            newest.set(key, item);
+        }
+    }
+    return [...newest.values()].sort((left, right) => left.number - right.number);
+}
+/**
+ * Refuse any row that does not belong to the requested repository: the
+ * stored cursor and every received observation must carry the canonical
+ * requested identity before any persistence or completion. A foreign row is
+ * a protocol failure, never a silent adoption.
+ */
+export function assertSameRepository(expected, owner, repo, what) {
+    if (owner !== expected.owner || repo !== expected.repo) {
+        throw new PrSyncError("protocol", `${what} targets ${owner}/${repo} but the requested repository is ${expected.owner}/${expected.repo} (foreign rows never persist, foreign sweeps never complete)`);
+    }
+}
+/**
+ * ETag position key: one validator per (filter, cursor) position inside the
+ * repository pass, so page N's ETag is never replayed for page M.
+ */
+export function etagPositionKey(cursor, updatedAtSince) {
+    return `${updatedAtSince === null ? "-" : String(updatedAtSince)}|${cursor === null ? "<start>" : cursor}`;
+}
+/**
+ * Require the explicit end-of-list proof: hasMore false without endProof is
+ * a protocol failure, never a silent completion. hasMore true without a
+ * continuation cursor is the same failure class.
+ */
+export function requireEndOfListProof(page) {
+    const checked = validatePrPage(page);
+    if (!checked.ok) {
+        throw new PrSyncError("protocol", `invalid PR page: ${checked.errors.join("; ")}`);
+    }
+    if (page.hasMore === false && page.endProof !== PR_END_PROOF) {
+        throw new PrSyncError("protocol", `PR sweep ends without end-of-list proof (hasMore false without endProof "${PR_END_PROOF}")`);
+    }
+    if (page.hasMore === true && (page.nextCursor === null || page.nextCursor.length === 0)) {
+        throw new PrSyncError("protocol", "PR sweep continues without a continuation cursor (hasMore true without nextCursor)");
+    }
+}
+/**
+ * S mapping rule: metadata receipts never acknowledge a failed private
+ * object acquisition. True only when every job is acquired AND verified:
+ * the acquired OID equals the observed head OID, no residual error stands,
+ * and known counters agree exactly (a partial count never acknowledges).
+ */
+export function canAcknowledgePrObjects(jobs) {
+    if (jobs.length === 0)
+        return false;
+    return jobs.every((job) => {
+        if (job.state !== "acquired")
+            return false;
+        if (job.acquiredOid === undefined || job.acquiredOid === null)
+            return false;
+        if (job.acquiredOid.algorithm !== job.headOid.algorithm || job.acquiredOid.oid !== job.headOid.oid)
+            return false;
+        if ((job.lastError ?? null) !== null)
+            return false;
+        const total = job.totalCommits ?? null;
+        const acquired = job.acquiredCommits ?? null;
+        if (total !== null && total <= 0)
+            return false;
+        if (total !== null && (acquired === null || acquired !== total))
+            return false;
+        return true;
+    });
+}
+function staleCoverage(kind, lastSuccessAt, message) {
+    const state = kind === "auth_required" || kind === "unavailable" ? "unavailable" : "stale";
+    return [
+        {
+            axis: "pr-metadata",
+            state,
+            reason: `${kind}: ${message}; last success preserved, resume automatically with stale coverage`,
+            ...(lastSuccessAt !== null ? { lastSuccessAt } : {}),
+        },
+        {
+            axis: "object-availability",
+            state: "unavailable",
+            reason: `object jobs untouched by the metadata ${kind}; failed jobs stay failed until acquired`,
+            ...(lastSuccessAt !== null ? { lastSuccessAt } : {}),
+        },
+        {
+            axis: "pr-attribution",
+            state: "partial",
+            reason: "attribution stays pinned to the last observed bounds while the transport is down",
+            ...(lastSuccessAt !== null ? { lastSuccessAt } : {}),
+        },
+    ];
+}
+/**
+ * Recreate the pending object job of every persisted observation that has
+ * none: after an interruption between saveObservation and recordObjectJob,
+ * the observation is durable but its acquisition is not. The resume — this
+ * pass's start and its proven end — heals that gap for retained observations,
+ * even ones this sweep does not re-observe.
+ */
+async function ensureObjectJobsForObservations(persistence, repository) {
+    const observations = await persistence.listObservations(repository);
+    if (observations.length === 0)
+        return;
+    const jobs = await persistence.listObjectJobs(repository);
+    const known = new Set(jobs.map((job) => objectJobIdentityKey(job)));
+    for (const item of observations) {
+        const key = objectJobIdentityKey({
+            repositoryOwner: item.repositoryOwner,
+            repositoryRepo: item.repositoryRepo,
+            prNumber: item.number,
+            headOid: item.headOid,
+        });
+        if (known.has(key))
+            continue;
+        await persistence.recordObjectJob({
+            repositoryOwner: item.repositoryOwner,
+            repositoryRepo: item.repositoryRepo,
+            prNumber: item.number,
+            headOid: item.headOid,
+            state: "pending",
+            attempts: 0,
+            lastError: null,
+            acquiredOid: null,
+            totalCommits: null,
+            acquiredCommits: null,
+        });
+        known.add(key);
+    }
+}
+/**
+ * Run one neutral PR sync pass: full pagination with overlap/dedup, durable
+ * cursor advance only after proven completion, object jobs recorded as
+ * pending independently of metadata, failures preserving last success with
+ * stale coverage and durable retry state for automatic resume.
+ */
+export async function runPrSyncPass(input, ports) {
+    const previous = await ports.persistence.loadCursor(input.repository);
+    if (previous !== null) {
+        const checked = validatePrSyncCursor(previous);
+        if (!checked.ok) {
+            throw new PrSyncError("protocol", `invalid stored PR cursor: ${checked.errors.join("; ")}`);
+        }
+        assertSameRepository(input.repository, previous.repositoryOwner, previous.repositoryRepo, "stored PR cursor");
+    }
+    const updatedAtSince = input.sweepKind === "incremental" && previous?.updatedAtCursor !== null && previous?.updatedAtCursor !== undefined
+        ? Math.max(0, previous.updatedAtCursor - PR_SYNC_OVERLAP_MS)
+        : null;
+    // Validators stay bound to their position: one ETag per (filter, cursor).
+    // A scalar lastEtag from an older cursor is never replayed: without a
+    // recorded position it could validate the wrong page, so the request goes
+    // out unconditionally instead.
+    // Resume heals a prior interruption between saveObservation and
+    // recordObjectJob before any new page lands.
+    await ensureObjectJobsForObservations(ports.persistence, input.repository);
+    const etags = { ...(previous?.etagsByCursor ?? {}) };
+    const seen = [];
+    const seenKeys = new Set();
+    let exactDuplicates = 0;
+    let cursor = null;
+    let pages = 0;
+    let lastEtag = previous?.lastEtag ?? null;
+    let maxUpdatedAt = previous?.updatedAtCursor ?? null;
+    const keepFailureCursor = async (kind, attempts, nextAfter) => {
+        const kept = {
+            repositoryOwner: input.repository.owner,
+            repositoryRepo: input.repository.repo,
+            updatedAtCursor: previous?.updatedAtCursor ?? null,
+            lastSuccessAt: previous?.lastSuccessAt ?? null,
+            lastEtag,
+            etagsByCursor: { ...etags },
+            sweepKind: input.sweepKind,
+            pendingRetry: { kind, attempts, nextAfter },
+        };
+        await ports.persistence.saveCursor(kept);
+        return kept;
+    };
+    for (;;) {
+        const position = etagPositionKey(cursor, updatedAtSince);
+        let result;
+        try {
+            result = await ports.transport.fetchPage({
+                repository: input.repository,
+                cursor,
+                updatedAtSince,
+                etag: etags[position] ?? null,
+            });
+        }
+        catch (error) {
+            const kind = "offline";
+            const kept = await keepFailureCursor(kind, (previous?.pendingRetry?.attempts ?? 0) + 1, input.now + 60_000);
+            const observations = await ports.persistence.listObservations(input.repository);
+            return {
+                state: "stale",
+                observations,
+                cursor: kept,
+                coverage: staleCoverage(kind, kept.lastSuccessAt, error instanceof Error ? error.message : String(error)),
+                stats: { pages, itemsSeen: seen.length, unique: 0, duplicates: exactDuplicates, observations: observations.length, objectJobsPending: 0 },
+            };
+        }
+        if (result.ok === false) {
+            const kept = await keepFailureCursor(result.kind, (previous?.pendingRetry?.attempts ?? 0) + 1, input.now + (result.retryAfterMs ?? 60_000));
+            const observations = await ports.persistence.listObservations(input.repository);
+            return {
+                state: "stale",
+                observations,
+                cursor: kept,
+                coverage: staleCoverage(result.kind, kept.lastSuccessAt, result.message),
+                stats: { pages, itemsSeen: seen.length, unique: 0, duplicates: exactDuplicates, observations: observations.length, objectJobsPending: 0 },
+            };
+        }
+        // Proven page first: every page is validated, and the terminator proof
+        // is enforced per page so a truncated sweep never completes silently.
+        const pageChecked = validatePrPage(result.page);
+        if (!pageChecked.ok) {
+            throw new PrSyncError("protocol", `invalid PR page: ${pageChecked.errors.join("; ")}`);
+        }
+        // Repository identity precedes any persistence: foreign rows never land.
+        for (const item of result.page.items) {
+            assertSameRepository(input.repository, item.repositoryOwner, item.repositoryRepo, `PR #${item.number} observation`);
+        }
+        // Per-page checkpoint: every distinct observation and its object job are
+        // persisted now, so a later failure keeps the received pages. Only the
+        // global success cursor waits for the proven end of list.
+        for (const item of result.page.items) {
+            seen.push(item);
+            const key = observationIdentityKey(item);
+            if (seenKeys.has(key)) {
+                exactDuplicates += 1;
+                continue;
+            }
+            seenKeys.add(key);
+            await ports.persistence.saveObservation(item);
+            if (maxUpdatedAt === null || item.updatedAt > maxUpdatedAt)
+                maxUpdatedAt = item.updatedAt;
+            // Object jobs advance independently and per OID: a new head OID adds a
+            // pending job while the previous head's job — its failures and receipts
+            // included — stays untouched. Metadata success never marks a job
+            // acquired or failed.
+            const jobs = await ports.persistence.listObjectJobs(input.repository);
+            const existing = jobs.find((job) => job.prNumber === item.number
+                && job.headOid.algorithm === item.headOid.algorithm
+                && job.headOid.oid === item.headOid.oid);
+            if (existing === undefined) {
+                await ports.persistence.recordObjectJob({
+                    repositoryOwner: item.repositoryOwner,
+                    repositoryRepo: item.repositoryRepo,
+                    prNumber: item.number,
+                    headOid: item.headOid,
+                    state: "pending",
+                    attempts: 0,
+                    lastError: null,
+                    acquiredOid: null,
+                    totalCommits: null,
+                    acquiredCommits: null,
+                });
+            }
+        }
+        pages += 1;
+        if (result.page.etag !== undefined && result.page.etag !== null) {
+            lastEtag = result.page.etag;
+            etags[position] = result.page.etag;
+        }
+        if (result.page.hasMore === false) {
+            requireEndOfListProof(result.page);
+            break;
+        }
+        requireEndOfListProof({ ...result.page, hasMore: true, nextCursor: result.page.nextCursor });
+        cursor = result.page.nextCursor;
+    }
+    // The current view (newest per PR) is computed separately after every
+    // distinct observation has been retained.
+    const current = deduplicatePrPageItems(seen);
+    const cursorOut = {
+        repositoryOwner: input.repository.owner,
+        repositoryRepo: input.repository.repo,
+        updatedAtCursor: maxUpdatedAt,
+        lastSuccessAt: input.now,
+        lastEtag,
+        etagsByCursor: { ...etags },
+        sweepKind: input.sweepKind,
+        pendingRetry: null,
+    };
+    // Proven end heals an interruption inside this sweep: every persisted
+    // observation leaves with its acquisition job before completion.
+    await ensureObjectJobsForObservations(ports.persistence, input.repository);
+    await ports.persistence.saveCursor(cursorOut);
+    const observations = await ports.persistence.listObservations(input.repository);
+    const jobs = await ports.persistence.listObjectJobs(input.repository);
+    const pending = jobs.filter((job) => job.state !== "acquired").length;
+    const objectsAcknowledged = canAcknowledgePrObjects(jobs);
+    return {
+        state: "complete",
+        observations,
+        cursor: cursorOut,
+        coverage: [
+            { axis: "pr-metadata", state: "current", reason: `full sweep proven with ${PR_END_PROOF} over ${pages} pages`, lastSuccessAt: input.now },
+            {
+                axis: "object-availability",
+                state: objectsAcknowledged ? "current" : "unavailable",
+                reason: objectsAcknowledged
+                    ? "every object job acquired and verified against its observed head"
+                    : `${jobs.length} object job(s), ${pending} pending or failed or unverified: metadata success completes no object job`,
+                lastSuccessAt: input.now,
+            },
+            { axis: "pr-attribution", state: "partial", reason: "attribution pins per-PR bounds separately (see pr-attribution)", lastSuccessAt: input.now },
+        ],
+        stats: {
+            pages,
+            itemsSeen: seen.length,
+            unique: current.length,
+            duplicates: exactDuplicates,
+            observations: observations.length,
+            objectJobsPending: pending,
+        },
+    };
+}

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

@@ -1,4 +1,5 @@
-// Vendored types for the sibling .js — see its provenance header; do not hand-edit.
+// Vendored from rhanka/engram@545a57b8911ab108e84fa1778e0f268fe11bf1de: engram-live/registration.ts.
+// Compiled with TypeScript 5.9.3 (ES2022/NodeNext, declarations); do not hand-edit.
 import { type CloneIdentityDto, type DeclarationRevocationDto, type IdentityUncertaintyState, type NonActivatingLifecycleKind, type OidAlgorithm, type RevocationReason, type WorkspaceDeclarationDto, type WorktreeIdentityDto } from "./contracts.js";
 /** Input for an explicit live declaration (revision starts at INITIAL_DECLARATION_REVISION). */
 export interface CreateLiveDeclarationInput {
@@ -135,4 +136,3 @@ export declare function isSameClone(a: Pick<CloneIdentityDto, "cloneId">, b: Pic
  * are refused.
  */
 export declare function classifyLifecycleEvent(kind: NonActivatingLifecycleKind): "no-activation-change";
-//# sourceMappingURL=registration.d.ts.map

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

@@ -1,7 +1,5 @@
-// Vendored from @sentropic/engram-live 0.1.0 dist/registration.js — same
-// provenance as the sibling contracts.js header (graphify@70ebdfee, pinned
-// tarball sha512 in the GUARD test). Portable: node:crypto plus the sibling
-// contracts.js only. Do not hand-edit.
+// 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).
 //

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.7-rc.1",
+  "version": "0.98.7-rc.3",
   "type": "module",
   "exports": {
     ".": {