@allocator-one/rcl 4.5.3 → 4.5.4

package/README.md

@@ -437,6 +437,7 @@ commands are documented in
 | --- | --- |
 | `rcl converge-report` | Dedupe a round report against earlier rounds, enforce the round cap, classify findings (`new` / `repeat` / `suppressed` / `regating`); refuses inconclusive reviewer health |
 | `rcl converge-verdict` | Record fixed/dismissed verdicts and report the round's resolution |
+| `rcl converge-reconcile-history` | Authenticate and append a reconciliation receipt for an exact historical guarded launch after `lastLaunch` advanced |
 | `rcl converge-stale` | Audited disposition of a healthy or reconciled delivered-hard-failure report that became stale before admission |
 | `rcl converge-gap` | Audited record of one evidenced missing terminal report |
 | `rcl converge-rejected` | Audited disposition of a report rejected locally before delivery |
@@ -452,6 +453,14 @@ verifiable and can be
 followed by a changed-input version 3 disposition only after that exact marker
 upgrade.
 
+If a published version 1 marker belongs to a retained version 2 stale receipt
+but a later launch has already replaced `lastLaunch`, use
+`converge-reconcile-history`. Preview prints one reviewed manifest to stdout and
+its SHA-256 to stderr. Apply accepts only those pinned bytes, re-reads every
+local source and the complete live server projection under the target lock,
+and appends a historical audit receipt. It never admits findings, claims an
+attempt or calls a reviewer.
+
 ---
 
 ## Configuration

package/dist/converge/historical-delivery-reconciliation-schema.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+export declare const historicalServerProjectionSchema: z.ZodObject<{
+    origin: z.ZodString;
+    runId: z.ZodString;
+    provenance: z.ZodLiteral<"live">;
+    receivedAt: z.ZodString;
+    cycleId: z.ZodString;
+    repoVerified: z.ZodLiteral<true>;
+    isCrossRepository: z.ZodLiteral<false>;
+    headVerified: z.ZodString;
+    target: z.ZodObject<{
+        kind: z.ZodEnum<{
+            patch: "patch";
+            pr: "pr";
+        }>;
+        repo: z.ZodString;
+        prNumber: z.ZodNumber;
+        headSha: z.ZodString;
+        baseSha: z.ZodString;
+        diffSha256: z.ZodString;
+    }, z.core.$strict>;
+    converge: z.ZodObject<{
+        target: z.ZodString;
+        attempt: z.ZodNumber;
+        round: z.ZodNumber;
+    }, z.core.$strict>;
+    report: z.ZodObject<{
+        declaredSha256: z.ZodString;
+        declaredBytes: z.ZodNumber;
+        stored: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const historicalDeliveryReconciliationManifestSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"rcl-historical-delivery-reconciliation">;
+    version: z.ZodLiteral<1>;
+    operationId: z.ZodString;
+    createdAt: z.ZodString;
+    gitCommonDir: z.ZodString;
+    target: z.ZodString;
+    runId: z.ZodString;
+    nativeStateSha256: z.ZodString;
+    attemptStateSha256: z.ZodString;
+    sourceStaleManifestSha256s: z.ZodArray<z.ZodString>;
+    successor: z.ZodObject<{
+        runId: z.ZodString;
+        attempt: z.ZodNumber;
+        round: z.ZodNumber;
+        headSha: z.ZodString;
+        inputSha256: z.ZodString;
+    }, z.core.$strict>;
+    reconciliation: z.ZodObject<{
+        version: z.ZodLiteral<2>;
+        runId: z.ZodString;
+        reportJsonSha256: z.ZodString;
+        headSha: z.ZodString;
+        inputSha256: z.ZodString;
+        attempt: z.ZodNumber;
+        round: z.ZodNumber;
+        claimPid: z.ZodNumber;
+        cycleId: z.ZodNullable<z.ZodString>;
+        reconciledAt: z.ZodString;
+    }, z.core.$strict>;
+    baseSha: z.ZodString;
+    diffSha256: z.ZodString;
+    reviewerHealth: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        policy: z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            fraction: z.ZodNumber;
+            seatCount: z.ZodNumber;
+            minimumSuccessful: z.ZodNumber;
+        }, z.core.$strict>;
+        successfulSeats: z.ZodNumber;
+    }, z.core.$strict>;
+    server: z.ZodObject<{
+        origin: z.ZodString;
+        runId: z.ZodString;
+        provenance: z.ZodLiteral<"live">;
+        receivedAt: z.ZodString;
+        cycleId: z.ZodString;
+        repoVerified: z.ZodLiteral<true>;
+        isCrossRepository: z.ZodLiteral<false>;
+        headVerified: z.ZodString;
+        target: z.ZodObject<{
+            kind: z.ZodEnum<{
+                patch: "patch";
+                pr: "pr";
+            }>;
+            repo: z.ZodString;
+            prNumber: z.ZodNumber;
+            headSha: z.ZodString;
+            baseSha: z.ZodString;
+            diffSha256: z.ZodString;
+        }, z.core.$strict>;
+        converge: z.ZodObject<{
+            target: z.ZodString;
+            attempt: z.ZodNumber;
+            round: z.ZodNumber;
+        }, z.core.$strict>;
+        report: z.ZodObject<{
+            declaredSha256: z.ZodString;
+            declaredBytes: z.ZodNumber;
+            stored: z.ZodLiteral<true>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    serverProjectionSha256: z.ZodString;
+}, z.core.$strict>;
+export type HistoricalDeliveryReconciliationManifest = z.infer<typeof historicalDeliveryReconciliationManifestSchema>;
+export declare const historicalDeliveryReconciliationReceiptSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"rcl-historical-delivery-reconciliation-receipt">;
+    version: z.ZodLiteral<1>;
+    operationId: z.ZodString;
+    runId: z.ZodString;
+    manifestSha256: z.ZodString;
+    beforeStateSha256: z.ZodString;
+    afterStateSha256: z.ZodString;
+    attemptStateSha256: z.ZodString;
+    sourceStaleManifestSha256s: z.ZodArray<z.ZodString>;
+    serverProjectionSha256: z.ZodString;
+}, z.core.$strict>;
+export type HistoricalDeliveryReconciliationReceipt = z.infer<typeof historicalDeliveryReconciliationReceiptSchema>;
+export interface HistoricalDeliveryReconciliationEntry {
+    manifestJson: string;
+    manifestSha256: string;
+}
+export declare function historicalDeliveryManifest(entry: HistoricalDeliveryReconciliationEntry): HistoricalDeliveryReconciliationManifest;
+export declare function validateHistoricalDeliveryReconciliationAudit(value: {
+    target?: string;
+    historicalDeliveryReconciliationAudit?: HistoricalDeliveryReconciliationEntry[];
+    historicalDeliveryReconciliationAuditCount?: number;
+}): void;

package/dist/converge/historical-delivery-reconciliation-schema.js

@@ -0,0 +1,111 @@
+import { isDeepStrictEqual } from 'node:util';
+import { z } from 'zod';
+import { reviewerHealthSchema, strongDeliveryReconciliationSchema } from './launch-record.js';
+import { decodeRecoveryDocument } from '../evidence/original-run/decode.js';
+import { serializeRecoveryDocument } from '../evidence/original-run/journal.js';
+import { sha256 } from '../telemetry/recovery/files.js';
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const commit = z.string().regex(/^[a-f0-9]{40}$/);
+const uuid = z.string().uuid();
+export const historicalServerProjectionSchema = z.object({
+    origin: z.string().url(),
+    runId: uuid,
+    provenance: z.literal('live'),
+    receivedAt: z.string().datetime({ offset: true }),
+    cycleId: uuid,
+    repoVerified: z.literal(true),
+    isCrossRepository: z.literal(false),
+    headVerified: z.string().min(1),
+    target: z.object({
+        kind: z.enum(['pr', 'patch']),
+        repo: z.string().min(1),
+        prNumber: z.number().int().positive().safe(),
+        headSha: commit,
+        baseSha: commit,
+        diffSha256: digest,
+    }).strict(),
+    converge: z.object({
+        target: z.string().min(1),
+        attempt: z.number().int().positive().safe(),
+        round: z.number().int().positive().safe(),
+    }).strict(),
+    report: z.object({
+        declaredSha256: digest,
+        declaredBytes: z.number().int().nonnegative().safe(),
+        stored: z.literal(true),
+    }).strict(),
+}).strict();
+export const historicalDeliveryReconciliationManifestSchema = z.object({
+    kind: z.literal('rcl-historical-delivery-reconciliation'),
+    version: z.literal(1),
+    operationId: uuid,
+    createdAt: z.string().datetime({ offset: true }),
+    gitCommonDir: z.string().min(1),
+    target: z.string().min(1),
+    runId: uuid,
+    nativeStateSha256: digest,
+    attemptStateSha256: digest,
+    sourceStaleManifestSha256s: z.array(digest).min(1).max(100).refine(values => new Set(values).size === values.length && isDeepStrictEqual(values, [...values].sort()), 'Historical stale manifest digests must be unique and sorted'),
+    successor: z.object({
+        runId: uuid,
+        attempt: z.number().int().positive().safe(),
+        round: z.number().int().positive().safe(),
+        headSha: commit,
+        inputSha256: digest,
+    }).strict(),
+    reconciliation: strongDeliveryReconciliationSchema,
+    baseSha: commit,
+    diffSha256: digest,
+    reviewerHealth: reviewerHealthSchema,
+    server: historicalServerProjectionSchema,
+    serverProjectionSha256: digest,
+}).strict();
+export const historicalDeliveryReconciliationReceiptSchema = z.object({
+    kind: z.literal('rcl-historical-delivery-reconciliation-receipt'),
+    version: z.literal(1),
+    operationId: uuid,
+    runId: uuid,
+    manifestSha256: digest,
+    beforeStateSha256: digest,
+    afterStateSha256: digest,
+    attemptStateSha256: digest,
+    sourceStaleManifestSha256s: z.array(digest).min(1).max(100),
+    serverProjectionSha256: digest,
+}).strict();
+const historicalDeliveryReconciliationEntrySchema = z.object({
+    manifestJson: z.string().max(128 * 1024), manifestSha256: digest,
+}).strict();
+export function historicalDeliveryManifest(entry) {
+    const parsedEntry = historicalDeliveryReconciliationEntrySchema.parse(entry);
+    if (sha256(parsedEntry.manifestJson) !== parsedEntry.manifestSha256)
+        throw new Error('historical_delivery_reconciliation_manifest_digest_mismatch');
+    const manifest = historicalDeliveryReconciliationManifestSchema.parse(decodeRecoveryDocument(parsedEntry.manifestJson));
+    if (parsedEntry.manifestJson !== serializeRecoveryDocument(manifest)) {
+        throw new Error('historical_delivery_reconciliation_manifest_noncanonical');
+    }
+    return manifest;
+}
+export function validateHistoricalDeliveryReconciliationAudit(value) {
+    const audit = value.historicalDeliveryReconciliationAudit;
+    if (audit === undefined) {
+        if (value.historicalDeliveryReconciliationAuditCount !== undefined) {
+            throw new Error('historical_delivery_reconciliation_audit_count_mismatch');
+        }
+        return;
+    }
+    if (!Array.isArray(audit) || audit.length === 0 || audit.length > 10_000 ||
+        value.historicalDeliveryReconciliationAuditCount !== audit.length) {
+        throw new Error('historical_delivery_reconciliation_audit_count_mismatch');
+    }
+    const operations = new Set();
+    const runs = new Set();
+    for (const entry of audit) {
+        const manifest = historicalDeliveryManifest(entry);
+        if (manifest.target !== value.target || operations.has(manifest.operationId) || runs.has(manifest.runId)) {
+            throw new Error('historical_delivery_reconciliation_audit_duplicate');
+        }
+        operations.add(manifest.operationId);
+        runs.add(manifest.runId);
+    }
+}
+//# sourceMappingURL=historical-delivery-reconciliation-schema.js.map

package/dist/converge/historical-delivery-reconciliation-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"historical-delivery-reconciliation-schema.js","sourceRoot":"","sources":["../../src/converge/historical-delivery-reconciliation-schema.ts"],"names":[],"mappings":"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"}

package/dist/converge/historical-delivery-reconciliation.d.ts

@@ -0,0 +1,15 @@
+import { type HistoricalDeliveryReconciliationManifest } from './historical-delivery-reconciliation-schema.js';
+import { type ConvergeRunState } from './run-state.js';
+import { getRun } from '../evidence/reads.js';
+import type { HarnessSink } from '../telemetry/sink.js';
+interface HistoricalReconciliationOptions {
+    getRun?: typeof getRun;
+    now?: () => Date;
+}
+/** Print-only qualification; callers may write the returned reviewed manifest separately. */
+export declare function previewHistoricalDeliveryReconciliation(input: unknown, gitCommonDir: string, sink: HarnessSink, options?: HistoricalReconciliationOptions): Promise<HistoricalDeliveryReconciliationManifest>;
+/** Reverify every authority source under the target lock, then append one local receipt atomically. */
+export declare function applyHistoricalDeliveryReconciliation(input: unknown, gitCommonDir: string, sink: HarnessSink, options?: HistoricalReconciliationOptions): Promise<'applied' | 'unchanged'>;
+/** Local fail-closed verification used before claims and report admission. */
+export declare function verifyHistoricalDeliveryReconciliations(common: string, state: ConvergeRunState): Promise<void>;
+export {};

package/dist/converge/historical-delivery-reconciliation.js

@@ -0,0 +1,326 @@
+import { randomUUID } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { z } from 'zod';
+import { convergeAttemptStatePath, validateConvergeAttemptState } from './attempt-budget.js';
+import { assertNoPendingFreshReview } from './fresh-review.js';
+import { historicalDeliveryManifest, historicalDeliveryReconciliationManifestSchema, historicalDeliveryReconciliationReceiptSchema, historicalServerProjectionSchema, validateHistoricalDeliveryReconciliationAudit, } from './historical-delivery-reconciliation-schema.js';
+import { strongDeliveryReconciliationSchema } from './launch-record.js';
+import { convergeRunStatePath, loadConvergeRunStateEvidence, writeState, } from './run-state.js';
+import { inspectVerifiedStaleReportReceipts } from './stale-report.js';
+import { readStaleObject, retainStaleFile as retain, selectedStaleFile as selected } from './stale-report-storage.js';
+import { assertDeadOwner } from './terminal-rejection.js';
+import { withRecoveryTarget } from './target-ownership.js';
+import { getRun } from '../evidence/reads.js';
+import { decodeRecoveryDocument } from '../evidence/original-run/decode.js';
+import { serializeRecoveryDocument, syncDirectory } from '../evidence/original-run/journal.js';
+import { inspectRecoveryDirectory, prepareLockRoot } from '../evidence/original-run/lock-path.js';
+import { normalizeUrl } from '../telemetry/credentials.js';
+import { readStable, sha256 } from '../telemetry/recovery/files.js';
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const selectionSchema = z.object({
+    target: z.string().min(1).max(200).refine(value => value.trim() === value),
+    runId: z.string().uuid(),
+}).strict();
+const applySchema = z.object({ manifest: z.string().min(1), manifestSha256: digest }).strict();
+function fail(code) { throw new Error(`historical_delivery_reconciliation_${code}`); }
+function endpoint(value) {
+    const normalized = normalizeUrl(value);
+    if (!normalized)
+        fail('origin_invalid');
+    return normalized;
+}
+function selectedServerProjection(sink, detail, local) {
+    const cycle = local.state.cycle;
+    if (!cycle || endpoint(sink.baseUrl) !== endpoint(cycle.url))
+        fail('server_origin_mismatch');
+    const reports = detail.artifacts?.filter(artifact => artifact.kind === 'report_json') ?? [];
+    const report = reports[0];
+    if (detail.id.toLowerCase() !== local.runId.toLowerCase() || detail.provenance !== 'live' ||
+        detail.repo_verified !== true || detail.is_cross_repository !== false ||
+        typeof detail.head_verified !== 'string' || detail.head_verified.length === 0 ||
+        detail.cycle_id !== cycle.id || reports.length !== 1 || !report ||
+        report.stored !== true || report.declared_sha256 !== local.reportSha256 ||
+        report.declared_bytes !== local.reportBytes || detail.target.kind !== local.targetKind ||
+        detail.target.repo?.toLowerCase() !== cycle.repo.toLowerCase() || detail.target.pr_number !== cycle.prNumber ||
+        detail.target.head_sha !== local.headSha || detail.target.base_sha !== local.baseSha ||
+        detail.target.diff_sha256 !== local.diffSha256 ||
+        detail.converge?.target !== local.target || detail.converge.attempt !== local.attempt ||
+        detail.converge.round !== local.round || typeof detail.received_at !== 'string') {
+        fail('server_binding_mismatch');
+    }
+    const parsed = z.string().datetime({ offset: true }).safeParse(detail.received_at);
+    if (!parsed.success)
+        fail('server_binding_mismatch');
+    return historicalServerProjectionSchema.parse({
+        origin: endpoint(sink.baseUrl), runId: detail.id, provenance: 'live', receivedAt: detail.received_at,
+        cycleId: cycle.id, repoVerified: true, isCrossRepository: false,
+        headVerified: detail.head_verified,
+        target: { kind: detail.target.kind, repo: detail.target.repo, prNumber: detail.target.pr_number,
+            headSha: detail.target.head_sha, baseSha: detail.target.base_sha, diffSha256: detail.target.diff_sha256 },
+        converge: { target: detail.converge.target, attempt: detail.converge.attempt, round: detail.converge.round },
+        report: { declaredSha256: report.declared_sha256, declaredBytes: report.declared_bytes, stored: true },
+    });
+}
+async function readServerProjection(sink, local, options) {
+    const outcome = await (options.getRun ?? getRun)(sink, local.runId, { requireCompleteRead: true });
+    if (outcome.kind !== 'ok')
+        fail(`server_${outcome.kind}`);
+    return selectedServerProjection(sink, outcome.value, local);
+}
+function commonPredecessor(proofs, target, runId) {
+    const matches = proofs.filter((proof) => proof.m.version === 2 &&
+        proof.m.outcome === 'delivered-hard-failure' && proof.m.target === target &&
+        proof.m.runId.toLowerCase() === runId.toLowerCase());
+    if (matches.length === 0)
+        fail('predecessor_not_found');
+    const first = matches[0];
+    const launch = first.previous;
+    const marker = launch.deliveryReconciliation;
+    if (marker?.version !== 1 || launch.status !== 'completed' || launch.hardFailure !== true ||
+        launch.deliveryPending !== false || launch.exitCode !== 4 || !launch.reviewerHealth ||
+        launch.runId !== runId || launch.reportJsonSha256 !== first.m.reportSha256 ||
+        first.m.deliveryReconciliation.version !== 1 || !isDeepStrictEqual(first.m.deliveryReconciliation, marker)) {
+        fail('predecessor_ineligible');
+    }
+    const binding = {
+        target: first.m.target, runId: first.m.runId, reportSha256: first.m.reportSha256,
+        headSha: first.m.previousHeadSha, inputSha256: first.m.previousInputSha256,
+        attempt: first.m.attempt, round: first.m.round, cycleId: first.m.cycleId,
+        marker: first.m.deliveryReconciliation, reviewerHealth: first.m.reviewerHealth,
+        launch, evidence: first.evidence,
+    };
+    for (const proof of matches.slice(1)) {
+        const candidate = {
+            target: proof.m.target, runId: proof.m.runId, reportSha256: proof.m.reportSha256,
+            headSha: proof.m.previousHeadSha, inputSha256: proof.m.previousInputSha256,
+            attempt: proof.m.attempt, round: proof.m.round, cycleId: proof.m.cycleId,
+            marker: proof.m.deliveryReconciliation, reviewerHealth: proof.m.reviewerHealth,
+            launch: proof.previous, evidence: proof.evidence,
+        };
+        if (!isDeepStrictEqual(candidate, binding))
+            fail('predecessor_ambiguous');
+    }
+    return { binding, sourceDigests: matches.map(proof => proof.entry.manifestSha256).sort() };
+}
+async function deriveLocalAuthority(common, target, runId, state, nativeSha256, attemptFile, requireDeadOwner) {
+    validateHistoricalDeliveryReconciliationAudit(state);
+    if (!state.cycle)
+        fail('cycle_missing');
+    const attemptsPath = convergeAttemptStatePath(common, target);
+    const attempts = validateConvergeAttemptState(decodeRecoveryDocument(attemptFile.text), target, attemptsPath);
+    if (!isDeepStrictEqual(attempts.cycle, state.cycle))
+        fail('cycle_mismatch');
+    const proofs = await inspectVerifiedStaleReportReceipts(common, state.staleReportAudit ?? []);
+    const { binding, sourceDigests } = commonPredecessor(proofs, target, runId);
+    if (binding.cycleId !== state.cycle.id || !isDeepStrictEqual(binding.evidence.attempts.cycle, state.cycle)) {
+        fail('cycle_mismatch');
+    }
+    const claim = attempts.attempts.find(record => record.attempt === binding.attempt && record.source === 'claim');
+    if (!claim || claim.pid !== binding.launch.pid || binding.launch.pid !== binding.evidence.attempts.attempts
+        .find(record => record.attempt === binding.attempt && record.source === 'claim')?.pid)
+        fail('attempt_mismatch');
+    if (requireDeadOwner)
+        assertDeadOwner(binding.launch.pid);
+    const reportTarget = binding.evidence.report.run.target;
+    if (!['pr', 'patch'].includes(reportTarget.kind))
+        fail('retained_report_target_kind_mismatch');
+    if (reportTarget.repo?.toLowerCase() !== state.cycle.repo.toLowerCase())
+        fail('retained_report_repository_mismatch');
+    if (reportTarget.pr_number !== state.cycle.prNumber)
+        fail('retained_report_pull_request_mismatch');
+    if (reportTarget.head_sha !== binding.headSha)
+        fail('retained_report_head_mismatch');
+    if (!/^[a-f0-9]{40}$/.test(reportTarget.base_sha ?? ''))
+        fail('retained_report_base_missing');
+    if (!/^[a-f0-9]{64}$/.test(reportTarget.diff_sha256 ?? ''))
+        fail('retained_report_diff_missing');
+    const retainedReport = await readStaleObject(common, binding.reportSha256);
+    const successor = state.lastLaunch;
+    if (!successor?.runId || successor.status !== 'completed' || successor.attempt <= binding.attempt ||
+        successor.runId === binding.runId)
+        fail('successor_missing');
+    const successorClaim = attempts.attempts.find(record => record.attempt === successor.attempt && record.source === 'claim');
+    if (attempts.attemptsUsed !== successor.attempt || !successorClaim || successorClaim.pid !== successor.pid) {
+        fail('successor_attempt_mismatch');
+    }
+    const reconciliation = strongDeliveryReconciliationSchema.parse({ version: 2, runId: binding.runId,
+        reportJsonSha256: binding.reportSha256, headSha: binding.headSha, inputSha256: binding.inputSha256,
+        attempt: binding.attempt, round: binding.round, claimPid: binding.launch.pid, cycleId: state.cycle.id,
+        reconciledAt: '1970-01-01T00:00:00.000Z' });
+    return { common, target, runId, state, nativeSha256, attempts, attemptFile, attemptSha256: attemptFile.sha256,
+        sourceDigests, headSha: binding.headSha, reportSha256: binding.reportSha256, attempt: binding.attempt,
+        round: binding.round, reviewerHealth: binding.reviewerHealth, reconciliation,
+        targetKind: reportTarget.kind, baseSha: reportTarget.base_sha,
+        diffSha256: reportTarget.diff_sha256, reportBytes: retainedReport.raw.byteLength,
+        successor: { runId: successor.runId, attempt: successor.attempt, round: successor.round,
+            headSha: successor.headSha, inputSha256: successor.inputSha256 } };
+}
+async function localAuthority(common, target, runId) {
+    await assertNoPendingFreshReview(common, target);
+    const native = await loadConvergeRunStateEvidence(common, target);
+    if (!native)
+        fail('state_missing');
+    if (native.state.historicalDeliveryReconciliationAudit?.some(entry => historicalDeliveryManifest(entry).runId === runId))
+        fail('already_applied');
+    const attemptFile = await readStable(convergeAttemptStatePath(common, target));
+    return deriveLocalAuthority(common, target, runId, native.state, native.sha256, attemptFile, true);
+}
+function assertServerBinding(local, server) {
+    const cycle = local.state.cycle;
+    if (!cycle || server.origin !== endpoint(cycle.url) || server.runId.toLowerCase() !== local.runId.toLowerCase() ||
+        server.cycleId !== cycle.id || server.target.kind !== local.targetKind ||
+        server.target.repo.toLowerCase() !== cycle.repo.toLowerCase() || server.target.prNumber !== cycle.prNumber ||
+        server.target.headSha !== local.headSha || server.target.baseSha !== local.baseSha ||
+        server.target.diffSha256 !== local.diffSha256 || server.converge.target !== local.target ||
+        server.converge.attempt !== local.attempt || server.converge.round !== local.round ||
+        server.report.declaredSha256 !== local.reportSha256 || server.report.declaredBytes !== local.reportBytes) {
+        fail('retained_server_binding_mismatch');
+    }
+}
+function buildManifest(local, server, operationId, createdAt) {
+    assertServerBinding(local, server);
+    return historicalDeliveryReconciliationManifestSchema.parse({
+        kind: 'rcl-historical-delivery-reconciliation', version: 1, operationId, createdAt,
+        gitCommonDir: local.common, target: local.target, runId: local.runId,
+        nativeStateSha256: local.nativeSha256, attemptStateSha256: local.attemptSha256,
+        sourceStaleManifestSha256s: local.sourceDigests, successor: local.successor,
+        reconciliation: { ...local.reconciliation, reconciledAt: createdAt },
+        baseSha: server.target.baseSha, diffSha256: server.target.diffSha256,
+        reviewerHealth: local.reviewerHealth, server,
+        serverProjectionSha256: sha256(Buffer.from(serializeRecoveryDocument(server))),
+    });
+}
+/** Print-only qualification; callers may write the returned reviewed manifest separately. */
+export async function previewHistoricalDeliveryReconciliation(input, gitCommonDir, sink, options = {}) {
+    const selection = selectionSchema.parse(input);
+    const common = await realpath(resolve(gitCommonDir));
+    const local = await localAuthority(common, selection.target, selection.runId);
+    const server = await readServerProjection(sink, local, options);
+    return buildManifest(local, server, randomUUID(), (options.now ?? (() => new Date()))().toISOString());
+}
+function nextState(before, entry, at) {
+    const { staleReportAudit, staleReportAuditCount, historicalDeliveryReconciliationAudit: audit = [], historicalDeliveryReconciliationAuditCount: _historicalCount, updatedAt: _updatedAt, ...rest } = before;
+    return {
+        ...(staleReportAudit ? { staleReportAudit } : {}), ...rest,
+        historicalDeliveryReconciliationAudit: [...audit, entry],
+        historicalDeliveryReconciliationAuditCount: audit.length + 1,
+        ...(staleReportAuditCount !== undefined ? { staleReportAuditCount } : {}), updatedAt: at,
+    };
+}
+function directory(common, manifest) {
+    return join(common, 'rcl-historical-delivery-reconciliations', manifest.operationId);
+}
+function receiptFor(manifest, manifestSha256, afterStateSha256) {
+    return historicalDeliveryReconciliationReceiptSchema.parse({
+        kind: 'rcl-historical-delivery-reconciliation-receipt', version: 1,
+        operationId: manifest.operationId, runId: manifest.runId, manifestSha256,
+        beforeStateSha256: manifest.nativeStateSha256, afterStateSha256,
+        attemptStateSha256: manifest.attemptStateSha256,
+        sourceStaleManifestSha256s: manifest.sourceStaleManifestSha256s,
+        serverProjectionSha256: manifest.serverProjectionSha256,
+    });
+}
+/** Reverify every authority source under the target lock, then append one local receipt atomically. */
+export async function applyHistoricalDeliveryReconciliation(input, gitCommonDir, sink, options = {}) {
+    const pinned = applySchema.parse(input);
+    const selectedManifest = await readStable(pinned.manifest, 128 * 1024);
+    if (selectedManifest.sha256 !== pinned.manifestSha256)
+        fail('manifest_digest_mismatch');
+    const manifest = historicalDeliveryReconciliationManifestSchema.parse(decodeRecoveryDocument(selectedManifest.text));
+    if (selectedManifest.text !== serializeRecoveryDocument(manifest))
+        fail('manifest_noncanonical');
+    const common = await realpath(resolve(gitCommonDir));
+    if (manifest.gitCommonDir !== common)
+        fail('repository_mismatch');
+    return withRecoveryTarget(common, manifest.target, async (ownership) => {
+        const currentFile = await readStable(convergeRunStatePath(common, manifest.target));
+        const current = await loadConvergeRunStateEvidence(common, manifest.target);
+        if (!current || current.sha256 !== currentFile.sha256)
+            fail('state_missing');
+        validateHistoricalDeliveryReconciliationAudit(current.state);
+        await verifyHistoricalDeliveryReconciliations(common, current.state);
+        const entry = {
+            manifestJson: selectedManifest.text, manifestSha256: selectedManifest.sha256,
+        };
+        const prior = current.state.historicalDeliveryReconciliationAudit?.find(entry => historicalDeliveryManifest(entry).runId === manifest.runId);
+        if (prior) {
+            if (!isDeepStrictEqual(prior, entry))
+                fail('operation_conflict');
+            return 'unchanged';
+        }
+        await assertNoPendingFreshReview(common, manifest.target);
+        if (current.sha256 !== manifest.nativeStateSha256)
+            fail('state_changed');
+        const attemptFile = await readStable(convergeAttemptStatePath(common, manifest.target));
+        const local = await deriveLocalAuthority(common, manifest.target, manifest.runId, current.state, current.sha256, attemptFile, true);
+        const server = await readServerProjection(sink, local, options);
+        assertServerBinding(local, server);
+        const expected = buildManifest(local, server, manifest.operationId, manifest.createdAt);
+        if (!isDeepStrictEqual(expected, manifest))
+            fail('manifest_binding_mismatch');
+        const next = nextState(current.state, entry, manifest.createdAt);
+        validateHistoricalDeliveryReconciliationAudit(next);
+        const afterBytes = Buffer.from(serializeRecoveryDocument(next));
+        const serverBytes = Buffer.from(serializeRecoveryDocument(server));
+        if (sha256(serverBytes) !== manifest.serverProjectionSha256)
+            fail('server_projection_digest_mismatch');
+        const receipt = receiptFor(manifest, selectedManifest.sha256, sha256(afterBytes));
+        const dir = directory(common, manifest);
+        await prepareLockRoot(dirname(dir));
+        await syncDirectory(common);
+        await prepareLockRoot(dir);
+        await syncDirectory(dirname(dir));
+        await retain(join(dir, 'manifest.json'), selectedManifest.raw);
+        await retain(join(dir, 'native-before.json'), currentFile.raw);
+        await retain(join(dir, 'attempts-before.json'), attemptFile.raw);
+        await retain(join(dir, 'server-projection.json'), serverBytes);
+        await retain(join(dir, 'complete.json'), Buffer.from(serializeRecoveryDocument(receipt)));
+        const finalState = await selected(convergeRunStatePath(common, manifest.target), manifest.nativeStateSha256);
+        const finalAttempts = await selected(convergeAttemptStatePath(common, manifest.target), manifest.attemptStateSha256);
+        const finalLocal = await deriveLocalAuthority(common, manifest.target, manifest.runId, decodeRecoveryDocument(finalState.text), finalState.sha256, finalAttempts, true);
+        const finalServer = await readServerProjection(sink, finalLocal, options);
+        assertServerBinding(finalLocal, finalServer);
+        if (!isDeepStrictEqual(buildManifest(finalLocal, finalServer, manifest.operationId, manifest.createdAt), manifest)) {
+            fail('manifest_binding_mismatch');
+        }
+        await verifyHistoricalDeliveryReconciliations(common, next);
+        await writeState(common, next, ownership);
+        await selected(convergeRunStatePath(common, manifest.target), sha256(afterBytes));
+        return 'applied';
+    });
+}
+/** Local fail-closed verification used before claims and report admission. */
+export async function verifyHistoricalDeliveryReconciliations(common, state) {
+    validateHistoricalDeliveryReconciliationAudit(state);
+    const audit = state.historicalDeliveryReconciliationAudit ?? [];
+    if (audit.length === 0)
+        return;
+    const root = join(common, 'rcl-historical-delivery-reconciliations');
+    await inspectRecoveryDirectory(root, true);
+    const prefix = [];
+    for (const entry of audit) {
+        const manifest = historicalDeliveryManifest(entry);
+        const dir = directory(common, manifest);
+        await inspectRecoveryDirectory(dir, true);
+        await selected(join(dir, 'manifest.json'), entry.manifestSha256);
+        const beforeFile = await selected(join(dir, 'native-before.json'), manifest.nativeStateSha256);
+        const before = decodeRecoveryDocument(beforeFile.text);
+        if (!isDeepStrictEqual(before.historicalDeliveryReconciliationAudit ?? [], prefix))
+            fail('audit_prefix');
+        const attemptFile = await selected(join(dir, 'attempts-before.json'), manifest.attemptStateSha256);
+        const serverFile = await selected(join(dir, 'server-projection.json'), manifest.serverProjectionSha256);
+        const server = historicalServerProjectionSchema.parse(decodeRecoveryDocument(serverFile.text));
+        const local = await deriveLocalAuthority(common, manifest.target, manifest.runId, before, beforeFile.sha256, attemptFile, false);
+        assertServerBinding(local, server);
+        if (!isDeepStrictEqual(buildManifest(local, server, manifest.operationId, manifest.createdAt), manifest)) {
+            fail('retained_source_mismatch');
+        }
+        const after = Buffer.from(serializeRecoveryDocument(nextState(before, entry, manifest.createdAt)));
+        const receipt = receiptFor(manifest, entry.manifestSha256, sha256(after));
+        await selected(join(dir, 'complete.json'), sha256(Buffer.from(serializeRecoveryDocument(receipt))));
+        prefix.push(entry);
+    }
+}
+//# sourceMappingURL=historical-delivery-reconciliation.js.map