@allocator-one/rcl 4.5.8 → 4.5.12

package/dist/telemetry/reviewer-delivery.js

@@ -4,21 +4,61 @@ import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { z } from 'zod';
 import { isReviewerArtifact } from '../report/reviewer-artifact.js';
-import { withRecoveryLock, syncDirectory, writeExclusiveBytes } from '../evidence/original-run/journal.js';
+import { MAX_RECOVERY_CHECKPOINT_BYTES, MAX_RECOVERY_DOCUMENT_BYTES, openJournal, withRecoveryLock, syncDirectory, writeExclusiveBytes } from '../evidence/original-run/journal.js';
 import { prepareLockRoot, inspectRecoveryDirectory } from '../evidence/original-run/lock-path.js';
 import { platformPath, readStable, sha256 } from './recovery/files.js';
 import { normalizeUrl } from './credentials.js';
 import { MAX_ARTIFACT_BYTES, MAX_ENVELOPE_BYTES, validateRunEnvelope } from './envelope-validation.js';
+import { MAX_RESPONSE_BYTES } from './sink.js';
 export const REVIEWER_OUTBOX_DIR = 'reviewer-outbox';
 const uuid = z.string().regex(/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}(?![\s\S])/i);
 const digest = z.string().regex(/^[0-9a-f]{64}(?![\s\S])/);
 const reference = z.object({ sha256: digest, bytes: z.number().int().min(0).max(MAX_ARTIFACT_BYTES) }).strict();
 const manifestSchema = z.object({ version: z.literal(1), runId: uuid, host: z.string(), credentialKind: z.enum(['login', 'env']),
     envelope: reference, report_json: reference, report_md: reference.optional(), reviewer: reference }).strict();
+const putOutcomePhases = ['report_json_put_outcome', 'report_md_put_outcome', 'reviewer_put_outcome'];
+const MAX_PUT_RETRIES_PER_ARTIFACT = 100;
+const MAX_PUT_OUTCOMES_PER_ARTIFACT = 1 + MAX_PUT_RETRIES_PER_ARTIFACT;
+const PUT_COMPLETION_RESERVATION_CHECKPOINTS = 7;
+const PUT_COMPLETION_RESERVATION_BYTES = PUT_COMPLETION_RESERVATION_CHECKPOINTS * MAX_RECOVERY_CHECKPOINT_BYTES;
+const PUT_COMPLETION_AFTER_INTENT_CHECKPOINTS = PUT_COMPLETION_RESERVATION_CHECKPOINTS - 1;
+const PUT_COMPLETION_AFTER_INTENT_BYTES = PUT_COMPLETION_AFTER_INTENT_CHECKPOINTS * MAX_RECOVERY_CHECKPOINT_BYTES;
+// Sink response bodies are bounded before classification. The retained outcome
+// keeps only kind/status/error. Invalid UTF-8 can expand to one three-byte
+// replacement character per input byte, with room for its checkpoint wrapper.
+const MAX_OUTCOME_CHECKPOINT_BYTES = 3 * MAX_RESPONSE_BYTES + 4096;
+function putOutcomeAttempt(phase) {
+    for (const base of putOutcomePhases) {
+        if (phase === base)
+            return { base, attempt: 1 };
+        if (!phase.startsWith(`${base}_`))
+            continue;
+        const suffix = phase.slice(base.length + 1);
+        if (!/^(?:[2-9]|[1-9][0-9]+)$/.test(suffix))
+            return undefined;
+        const attempt = Number(suffix);
+        return Number.isSafeInteger(attempt) && attempt >= 2 ? { base, attempt } : undefined;
+    }
+    return undefined;
+}
+const isOutcomePhase = (phase) => phase === 'activation_post_outcome' || putOutcomeAttempt(phase) !== undefined;
+const operationPhases = new Set(['prepared', 'activation_post_intent', 'activation_post_outcome', ...putOutcomePhases, 'activation_post_uncertain',
+    'envelope_verified', 'report_json_put_intent', 'report_json_verified',
+    'report_md_put_intent', 'report_md_verified', 'reviewer_put_intent',
+    'reviewer_verified', 'recovery_acknowledged', 'complete']);
+const outcomeSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('ok'), http_status: z.number().int() }).strict(),
+    z.object({ kind: z.literal('disabled') }).strict(),
+    z.object({ kind: z.literal('conflict') }).strict(),
+    z.object({ kind: z.literal('rejected'), http_status: z.number().int(), error: z.string() }).strict(),
+    z.object({ kind: z.literal('unavailable'), http_status: z.number().int().optional() }).strict(),
+]);
 const files = { report_json: 'report.json', report_md: 'report.md' };
 const ref = (text) => ({ sha256: sha256(text), bytes: Buffer.byteLength(text) });
 function fail(reason) { throw new Error(`reviewer_delivery_${reason}`); }
 function safeFailure(error) {
+    if (error instanceof Error && error.message === 'recovery_run_locked')
+        return 'reviewer_delivery_recovery_run_locked';
     return error instanceof Error && /^reviewer_delivery_[a-z_]+$/.test(error.message) ? error.message : 'reviewer_delivery_local_refusal';
 }
 function accepted(outcome) {
@@ -59,6 +99,7 @@ async function publish(path, bytes) {
 function validate(entry) {
     const { manifest: m, envelope, artifacts, privateBytes } = entry;
     if (normalizeUrl(m.host) !== m.host || m.envelope.bytes > MAX_ENVELOPE_BYTES || envelope.run.id !== m.runId ||
+        entry.manifestBytes !== JSON.stringify(m) || entry.envelopeBytes !== JSON.stringify(envelope) ||
         validateRunEnvelope(envelope, artifacts).length || !isDeepStrictEqual(ref(entry.envelopeBytes), m.envelope) ||
         !isDeepStrictEqual(ref(artifacts.report_json), m.report_json) || !isDeepStrictEqual(ref(privateBytes), m.reviewer) ||
         (m.report_md === undefined ? artifacts.report_md !== undefined : !isDeepStrictEqual(ref(artifacts.report_md), m.report_md)))
@@ -96,14 +137,16 @@ export class ReviewerDeliveryQueue {
         await this.lock(entry.manifest.runId, async () => { await this.save(entry); });
     }
     /** Initial delivery is the only path allowed to create an as-yet unknown run. */
-    async deliver(input, options = {}) {
+    async deliver(input, options = {}, authorizeTransfer) {
         const entry = this.snapshot(input), request = budget(options);
         await this.lock(entry.manifest.runId, async () => {
+            await this.assertGenericDeliveryAllowed(entry.manifest.runId);
+            await authorizeTransfer?.();
             request();
             await this.save(entry);
             // An existing manifest might belong to an earlier process/principal.
             // Only this invocation's first publication can use the creation path.
-            await this.transfer(await this.load(entry.manifest.runId), input.sink, request, entryWasNew.delete(entry));
+            await this.transfer(await this.load(entry.manifest.runId), input.sink, request, entryWasNew.delete(entry) ? 'initial' : 'retry');
         });
     }
     /** Explicit/current-credential retry; no provider calls or changed run identity. */
@@ -127,11 +170,12 @@ export class ReviewerDeliveryQueue {
                 request();
                 await this.lock(id, async () => {
                     const entry = await this.load(id);
+                    await this.assertGenericDeliveryAllowed(id);
                     if (await this.acknowledged(entry))
                         return;
                     await authorizeTransfer?.();
                     request();
-                    await this.transfer(entry, sink, request, false);
+                    await this.transfer(entry, sink, request, 'retry');
                     summary.delivered.push(entry.manifest.runId);
                 });
             }
@@ -163,6 +207,106 @@ export class ReviewerDeliveryQueue {
             return false;
         }
     }
+    /** Presence alone blocks legacy delivery; malformed retained state must fail closed too. */
+    async hasEntry(runId) {
+        if (!uuid.safeParse(runId).success)
+            return false;
+        try {
+            await lstat(join(this.root, runId.toLowerCase()));
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+    /** Generic retry paths must never bypass an explicit retained activation operation. */
+    async assertGenericDeliveryAllowed(runId) {
+        if (!uuid.safeParse(runId).success)
+            fail('invalid_run');
+        try {
+            await lstat(join(this.root, runId.toLowerCase(), 'activation-intent.json'));
+            fail('explicit_activation_required');
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'reviewer_delivery_explicit_activation_required')
+                throw error;
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    /** Hold the run lock across a selected generic transmission so activation cannot race it. */
+    async withGenericDeliveryAllowed(runId, work) {
+        return this.lock(runId, async () => {
+            await this.assertGenericDeliveryAllowed(runId);
+            return work();
+        });
+    }
+    /** Read-only exact activation proposal derived from authenticated local lineage. */
+    async previewRecovery(selection) {
+        return (await this.prepareRecovery(selection)).preview;
+    }
+    recoveryJournalPath(runId, operationId) {
+        if (!uuid.safeParse(runId).success || !uuid.safeParse(operationId).success)
+            fail('recovery_operation_mismatch');
+        return join(this.root, runId.toLowerCase(), 'recovery.journal');
+    }
+    /** Read-only retained bytes after checkpoint lineage and private outbox authentication. */
+    async prepareRecovery(selection) {
+        if (!selection || typeof selection !== 'object' || !uuid.safeParse(selection.runId).success)
+            fail('invalid_recovery_selection');
+        return this.lock(selection.runId, async () => {
+            const entry = await this.load(selection.runId);
+            return { preview: this.recoveryPreview(entry, selection), envelopeBytes: entry.envelopeBytes,
+                ...(entry.artifacts.report_md === undefined ? {} : { reportMarkdownBytes: entry.artifacts.report_md }) };
+        });
+    }
+    /** Reject conflicting local acknowledgements before notice, journal creation, or transport. */
+    async preflightRecoveryAcknowledgements(selection, preview, operationInput) {
+        if (!selection || typeof selection !== 'object' || !uuid.safeParse(selection.runId).success)
+            fail('invalid_recovery_selection');
+        await this.lock(selection.runId, async () => {
+            const entry = await this.load(selection.runId);
+            if (!isDeepStrictEqual(this.recoveryPreview(entry, selection), preview))
+                fail('recovery_selection_mismatch');
+            if (operationInput === undefined) {
+                await this.assertOrdinaryAcknowledgement(entry);
+                if (await this.optionalPrivateRead(join(entry.directory, 'recovery-acknowledged.json'), 4096) !== undefined) {
+                    fail('immutable_conflict');
+                }
+                return;
+            }
+            const operation = await this.resolveRecoveryOperation(operationInput, selection.runId);
+            this.validateRecoveryOperation(entry, operation);
+            const activationIntent = this.activationIntent(entry, operation);
+            const recoveryAck = this.recoveryAcknowledgement(entry, operation, activationIntent);
+            this.assertRecoveryJournalAcknowledgements(operation, recoveryAck);
+            await this.assertRecoveryAcknowledgements(entry, recoveryAck);
+        });
+    }
+    /** Activate an exact retained entry. Generic flush never receives this creation authority. */
+    async applyRecovery(sink, selection, preview, operationInput, options = {}) {
+        await this.applyRecoveryOperation(sink, selection, preview, () => this.resolveRecoveryOperation(operationInput, selection.runId), options);
+    }
+    async applyRecoveryOperation(sink, selection, preview, resolveOperation, options = {}) {
+        if (!selection || typeof selection !== 'object' || !uuid.safeParse(selection.runId).success)
+            fail('invalid_recovery_selection');
+        const request = budget(options);
+        await this.lock(selection.runId, async () => {
+            const entry = await this.load(selection.runId);
+            const current = this.recoveryPreview(entry, selection);
+            if (!isDeepStrictEqual(current, preview))
+                fail('recovery_selection_mismatch');
+            const operation = await resolveOperation();
+            request();
+            await this.recover(entry, sink, request, operation);
+        });
+    }
+    /** Resume is the same exact operation; server readback decides which writes remain. */
+    async resumeRecovery(sink, selection, preview, operation, options = {}) {
+        await this.applyRecovery(sink, selection, preview, operation, options);
+    }
     snapshot(input) {
         if (!isReviewerArtifact(input.artifact))
             fail('unvalidated_artifact');
@@ -172,13 +316,23 @@ export class ReviewerDeliveryQueue {
         const artifacts = { ...input.artifacts }, privateBytes = input.artifact.bytes;
         const manifest = manifestSchema.parse({ version: 1, runId: envelope.run.id, host: input.sink.baseUrl, credentialKind: input.sink.credentialSource,
             envelope: ref(envelopeBytes), report_json: ref(artifacts.report_json), ...(artifacts.report_md === undefined ? {} : { report_md: ref(artifacts.report_md) }), reviewer: ref(privateBytes) });
-        const entry = { manifest, envelope, envelopeBytes, artifacts, privateBytes, directory: join(this.root, manifest.runId.toLowerCase()) };
+        const entry = { manifest, manifestBytes: JSON.stringify(manifest), envelope, envelopeBytes, artifacts, privateBytes,
+            directory: join(this.root, manifest.runId.toLowerCase()) };
         validate(entry);
         return entry;
     }
     async lock(runId, work) {
         return withRecoveryLock(join(this.root, 'locks'), runId.toLowerCase(), work);
     }
+    async resolveRecoveryOperation(operation, runId) {
+        const manifestPath = platformPath(operation.manifestPath);
+        const retained = await readStable(manifestPath, MAX_RECOVERY_DOCUMENT_BYTES, { sync: true });
+        if (retained.sha256 !== operation.recoveryManifestSha256)
+            fail('manifest_digest_mismatch');
+        return { mode: operation.mode, operationId: operation.operationId,
+            recoveryManifestSha256: operation.recoveryManifestSha256, destination: operation.destination,
+            journal: await openJournal(this.recoveryJournalPath(runId, operation.operationId), operation.recoveryManifestSha256, operation.operationId, operation.mode) };
+    }
     async save(entry) {
         await prepareLockRoot(this.root);
         try {
@@ -199,24 +353,107 @@ export class ReviewerDeliveryQueue {
             if (entry.artifacts[kind] !== undefined)
                 await publish(join(entry.directory, files[kind]), entry.artifacts[kind]);
         // Publish manifest last; a crash before it leaves evidence, never an uploadable partial entry.
-        await publish(join(entry.directory, 'manifest.json'), JSON.stringify(entry.manifest));
+        await publish(join(entry.directory, 'manifest.json'), entry.manifestBytes);
     }
     async load(id) {
         const directory = join(this.root, id.toLowerCase());
         await inspectRecoveryDirectory(directory, true);
-        const manifest = manifestSchema.parse(JSON.parse(await privateRead(join(directory, 'manifest.json'), 4096)));
+        const manifestBytes = await privateRead(join(directory, 'manifest.json'), 4096);
+        const manifest = manifestSchema.parse(JSON.parse(manifestBytes));
         if (manifest.runId.toLowerCase() !== id.toLowerCase())
             fail('invalid_run');
-        const allowed = ['manifest.json', 'envelope.json', 'reviewer-artifact.json', 'report.json', 'acknowledged.json', ...(manifest.report_md ? ['report.md'] : [])];
+        const allowed = ['manifest.json', 'envelope.json', 'reviewer-artifact.json', 'report.json', 'acknowledged.json',
+            'activation-intent.json', 'recovery-acknowledged.json', 'recovery.journal',
+            ...(manifest.report_md ? ['report.md'] : [])];
         if ((await readdir(directory)).some(name => !allowed.includes(name)))
             fail('unknown_file');
         const envelopeBytes = await privateRead(join(directory, 'envelope.json'), MAX_ENVELOPE_BYTES);
-        const entry = { manifest, directory, envelopeBytes, envelope: JSON.parse(envelopeBytes), privateBytes: await privateRead(join(directory, 'reviewer-artifact.json'), MAX_ARTIFACT_BYTES),
+        const entry = { manifest, manifestBytes, directory, envelopeBytes, envelope: JSON.parse(envelopeBytes), privateBytes: await privateRead(join(directory, 'reviewer-artifact.json'), MAX_ARTIFACT_BYTES),
             artifacts: { report_json: await privateRead(join(directory, 'report.json'), MAX_ARTIFACT_BYTES), ...(manifest.report_md ? { report_md: await privateRead(join(directory, 'report.md'), MAX_ARTIFACT_BYTES) } : {}) } };
         validate(entry);
         return entry;
     }
-    ack(entry) { return JSON.stringify({ version: 1, runId: entry.manifest.runId, manifestSha256: sha256(JSON.stringify(entry.manifest)) }); }
+    recoveryPreview(entry, selection) {
+        const report = ref(selection.reportBytes), reviewer = ref(selection.reviewerArtifactBytes);
+        const run = entry.envelope.run;
+        if (typeof selection.target !== 'string' || !selection.target || !/^[a-f0-9]{40}$/.test(selection.headSha) ||
+            selection.runId.toLowerCase() !== entry.manifest.runId.toLowerCase() || run.id !== entry.manifest.runId ||
+            run.converge?.target !== selection.target || run.target.head_sha !== selection.headSha ||
+            selection.reportSha256 !== report.sha256 || selection.reportByteLength !== report.bytes ||
+            selection.reviewerArtifactSha256 !== reviewer.sha256 || selection.reviewerArtifactByteLength !== reviewer.bytes ||
+            entry.artifacts.report_json !== selection.reportBytes || entry.privateBytes !== selection.reviewerArtifactBytes ||
+            !isDeepStrictEqual(entry.envelope.reviewer_recovery, selection.reviewerRecovery) ||
+            !isDeepStrictEqual(entry.manifest.report_json, report) || !isDeepStrictEqual(entry.manifest.reviewer, reviewer)) {
+            fail('recovery_selection_mismatch');
+        }
+        return { version: 1, target: selection.target, runId: entry.manifest.runId, headSha: selection.headSha,
+            host: entry.manifest.host, credentialKind: entry.manifest.credentialKind,
+            manifest: ref(entry.manifestBytes), envelope: { ...entry.manifest.envelope },
+            report_json: { ...entry.manifest.report_json },
+            ...(entry.manifest.report_md ? { report_md: { ...entry.manifest.report_md } } : {}),
+            reviewer: { ...entry.manifest.reviewer } };
+    }
+    ack(entry) { return JSON.stringify({ version: 1, runId: entry.manifest.runId, manifestSha256: sha256(entry.manifestBytes) }); }
+    async optionalPrivateRead(path, limit) {
+        try {
+            return await privateRead(path, limit);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    async assertOrdinaryAcknowledgement(entry) {
+        const bytes = await this.optionalPrivateRead(join(entry.directory, 'acknowledged.json'), 4096);
+        if (bytes !== undefined && bytes !== this.ack(entry))
+            fail('immutable_conflict');
+    }
+    activationIntent(entry, operation) {
+        return JSON.stringify({ version: 1, runId: entry.manifest.runId, operationId: operation.operationId,
+            recoveryManifestSha256: operation.recoveryManifestSha256, envelopeSha256: entry.manifest.envelope.sha256 });
+    }
+    validateRecoveryOperation(entry, operation) {
+        const m = entry.manifest;
+        if (!operation || !uuid.safeParse(operation.operationId).success || !digest.safeParse(operation.recoveryManifestSha256).success ||
+            !operation.journal || (operation.mode !== 'apply' && operation.mode !== 'resume') ||
+            operation.destination.host !== m.host || operation.destination.credentialKind !== m.credentialKind ||
+            operation.destination.activationProtocol !== 1)
+            fail('recovery_operation_mismatch');
+    }
+    recoveryOutcomeDigest(operation) {
+        const outcomes = operation.journal.checkpoints()
+            .filter(checkpoint => isOutcomePhase(checkpoint.phase))
+            .map(checkpoint => {
+            const parsed = outcomeSchema.safeParse(checkpoint.data);
+            if (!parsed.success || !isDeepStrictEqual(parsed.data, checkpoint.data))
+                fail('journal_checkpoint_conflict');
+            return { phase: checkpoint.phase, data: parsed.data };
+        });
+        return sha256(JSON.stringify(outcomes));
+    }
+    recoveryAcknowledgement(entry, operation, activationIntent) {
+        const m = entry.manifest;
+        return JSON.stringify({ version: 1, operationId: operation.operationId,
+            recoveryManifestSha256: operation.recoveryManifestSha256, outboxManifestSha256: sha256(entry.manifestBytes),
+            activationIntentSha256: sha256(activationIntent), journalOutcomesSha256: this.recoveryOutcomeDigest(operation),
+            destination: operation.destination, envelope: m.envelope, report_json: m.report_json,
+            ...(m.report_md ? { report_md: m.report_md } : {}), reviewer: m.reviewer });
+    }
+    assertRecoveryJournalAcknowledgements(operation, recoveryAck) {
+        const acknowledgement = operation.journal.checkpoints().find(checkpoint => checkpoint.phase === 'recovery_acknowledged');
+        if (acknowledgement && !isDeepStrictEqual(acknowledgement.data, JSON.parse(recoveryAck)))
+            fail('journal_checkpoint_conflict');
+        const complete = operation.journal.checkpoints().find(checkpoint => checkpoint.phase === 'complete');
+        if (complete && !isDeepStrictEqual(complete.data, { recovery_ack_sha256: sha256(recoveryAck) }))
+            fail('journal_checkpoint_conflict');
+    }
+    async assertRecoveryAcknowledgements(entry, recoveryAck) {
+        await this.assertOrdinaryAcknowledgement(entry);
+        const bytes = await this.optionalPrivateRead(join(entry.directory, 'recovery-acknowledged.json'), 4096);
+        if (bytes !== undefined && bytes !== recoveryAck)
+            fail('immutable_conflict');
+    }
     async acknowledged(entry) {
         try {
             if (await privateRead(join(entry.directory, 'acknowledged.json'), 4096) !== this.ack(entry))
@@ -229,12 +466,12 @@ export class ReviewerDeliveryQueue {
             throw error;
         }
     }
-    async transfer(entry, sink, request, initial) {
+    async transfer(entry, sink, request, mode) {
         const m = entry.manifest;
         if (sink.baseUrl !== m.host || sink.credentialSource !== m.credentialKind)
             fail('credential_mismatch');
         accepted(await sink.checkReviewerRecovery(request()));
-        let read = initial ? undefined : await sink.getReviewerArtifact(m.runId, m.reviewer, request());
+        let read = mode === 'initial' ? undefined : await sink.getReviewerArtifact(m.runId, m.reviewer, request());
         if (read && read.kind !== 'ok' && read.kind !== 'pending')
             accepted(read);
         // A matching private read is the server's completed admission proof: it
@@ -273,6 +510,357 @@ export class ReviewerDeliveryQueue {
             fail('private_mismatch');
         await publish(join(entry.directory, 'acknowledged.json'), this.ack(entry));
     }
+    async recover(entry, sink, request, operation) {
+        const m = entry.manifest;
+        this.validateRecoveryOperation(entry, operation);
+        if (sink.baseUrl !== m.host || sink.credentialSource !== m.credentialKind)
+            fail('recovery_operation_mismatch');
+        const checkpoints = operation.journal.checkpoints();
+        const phases = new Set();
+        const putAttempts = new Map();
+        const putHistories = new Map();
+        const phasePositions = new Map();
+        for (const [index, checkpoint] of checkpoints.entries()) {
+            if (checkpoint.phase === 'interrupted_checkpoints_retained')
+                continue;
+            const putAttempt = putOutcomeAttempt(checkpoint.phase);
+            if (!operationPhases.has(checkpoint.phase) && putAttempt === undefined)
+                fail('journal_checkpoint_conflict');
+            if (phases.has(checkpoint.phase))
+                fail('journal_checkpoint_conflict');
+            phases.add(checkpoint.phase);
+            phasePositions.set(checkpoint.phase, index);
+            if (isOutcomePhase(checkpoint.phase)) {
+                const parsed = outcomeSchema.safeParse(checkpoint.data);
+                if (!parsed.success || !isDeepStrictEqual(parsed.data, checkpoint.data))
+                    fail('journal_checkpoint_conflict');
+            }
+            if (putAttempt !== undefined) {
+                const expected = (putAttempts.get(putAttempt.base) ?? 0) + 1;
+                if (putAttempt.attempt !== expected)
+                    fail('journal_checkpoint_conflict');
+                putAttempts.set(putAttempt.base, expected);
+                const parsed = outcomeSchema.safeParse(checkpoint.data);
+                if (!parsed.success)
+                    fail('journal_checkpoint_conflict');
+                const history = putHistories.get(putAttempt.base) ?? [];
+                history.push({ index, data: parsed.data });
+                putHistories.set(putAttempt.base, history);
+            }
+        }
+        for (const base of putOutcomePhases) {
+            const prefix = base.slice(0, -'_put_outcome'.length);
+            const intentPosition = phasePositions.get(`${prefix}_put_intent`);
+            const verifiedPosition = phasePositions.get(`${prefix}_verified`);
+            const history = putHistories.get(base) ?? [];
+            if (history.length > 0 && intentPosition === undefined)
+                fail('journal_checkpoint_conflict');
+            if (intentPosition !== undefined && verifiedPosition !== undefined && intentPosition > verifiedPosition) {
+                fail('journal_checkpoint_conflict');
+            }
+            let terminal = false;
+            for (const item of history) {
+                if (item.index < intentPosition || (verifiedPosition !== undefined && item.index > verifiedPosition) || terminal) {
+                    fail('journal_checkpoint_conflict');
+                }
+                if (item.data.kind !== 'unavailable')
+                    terminal = true;
+            }
+            if (history.length > MAX_PUT_OUTCOMES_PER_ARTIFACT)
+                fail('put_retry_limit');
+        }
+        const appendOnce = async (phase, data) => {
+            const normalized = JSON.parse(JSON.stringify(data));
+            const matches = operation.journal.checkpoints().filter(checkpoint => checkpoint.phase === phase);
+            if (matches.length === 0)
+                await operation.journal.append(phase, normalized);
+            else if (matches.length !== 1 || !isDeepStrictEqual(matches[0].data, normalized))
+                fail('journal_checkpoint_conflict');
+        };
+        const appendPutOutcome = async (phase, data) => {
+            if (!putOutcomePhases.includes(phase))
+                fail('journal_checkpoint_conflict');
+            const attempts = operation.journal.checkpoints().filter(checkpoint => putOutcomeAttempt(checkpoint.phase)?.base === phase).length;
+            if (attempts >= MAX_PUT_OUTCOMES_PER_ARTIFACT)
+                fail('put_retry_limit');
+            const attemptPhase = attempts === 0 ? phase : `${phase}_${attempts + 1}`;
+            await operation.journal.append(attemptPhase, JSON.parse(JSON.stringify(data)));
+        };
+        const assertPutMayProceed = (phase) => {
+            const verifiedPhase = `${phase.slice(0, -'_put_outcome'.length)}_verified`;
+            if (operation.journal.checkpoints().some(checkpoint => checkpoint.phase === verifiedPhase))
+                fail('unavailable');
+            const attempts = operation.journal.checkpoints()
+                .filter(checkpoint => putOutcomeAttempt(checkpoint.phase)?.base === phase);
+            const previous = attempts.at(-1);
+            if (!previous)
+                return;
+            const parsed = outcomeSchema.safeParse(previous.data);
+            if (!parsed.success || !isDeepStrictEqual(parsed.data, previous.data))
+                fail('journal_checkpoint_conflict');
+            if (parsed.data.kind === 'unavailable') {
+                if (attempts.length >= MAX_PUT_OUTCOMES_PER_ARTIFACT)
+                    fail('put_retry_limit');
+                return;
+            }
+            fail(parsed.data.kind === 'ok' ? 'unavailable' : 'refused');
+        };
+        const assertPutCapacityBeforeIntent = (prefix) => {
+            const intentExists = operation.journal.checkpoints().some(checkpoint => checkpoint.phase === `${prefix}_put_intent`);
+            operation.journal.assertAppendCapacity(intentExists ? PUT_COMPLETION_AFTER_INTENT_CHECKPOINTS : PUT_COMPLETION_RESERVATION_CHECKPOINTS, intentExists ? PUT_COMPLETION_AFTER_INTENT_BYTES : PUT_COMPLETION_RESERVATION_BYTES);
+        };
+        const assertExisting = (phase, data) => {
+            const checkpoint = operation.journal.checkpoints().find(candidate => candidate.phase === phase);
+            if (checkpoint && !isDeepStrictEqual(checkpoint.data, JSON.parse(JSON.stringify(data))))
+                fail('journal_checkpoint_conflict');
+        };
+        const outcome = (value) => {
+            const rawError = value.error;
+            return { kind: value.kind,
+                ...('httpStatus' in value ? { http_status: value.httpStatus } : {}),
+                ...(rawError !== undefined ? { error: typeof rawError === 'string' ? rawError : 'malformed_response' } : {}) };
+        };
+        const assertDestination = async () => {
+            const capability = accepted(await sink.checkReviewerRecoveryActivation(request()));
+            if (capability.protocol !== operation.destination.activationProtocol ||
+                !isDeepStrictEqual(capability.principal, operation.destination.principal))
+                fail('principal_mismatch');
+        };
+        const privateReadback = async () => sink.getReviewerArtifact(m.runId, m.reviewer, request());
+        const activationIntent = this.activationIntent(entry, operation);
+        const initialRecoveryAck = this.recoveryAcknowledgement(entry, operation, activationIntent);
+        const activationIntentPath = join(entry.directory, 'activation-intent.json');
+        let activationIntentPresent = false;
+        try {
+            if (await privateRead(activationIntentPath, 4096) !== activationIntent)
+                fail('activation_operation_conflict');
+            activationIntentPresent = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const ensureActivationIntent = async () => {
+            if (activationIntentPresent)
+                return;
+            await publish(activationIntentPath, activationIntent);
+            activationIntentPresent = true;
+        };
+        const absent = (value) => value.kind === 'rejected' &&
+            value.httpStatus === 404 && value.error === 'reviewer_artifact_http_404';
+        const inspectOrdinary = async (kind, bytes) => {
+            const read = await sink.getArtifact(m.runId, kind, Buffer.byteLength(bytes), request());
+            if (read.kind === 'ok')
+                return read.value.bytes.equals(Buffer.from(bytes)) ? 'exact' : 'mismatch';
+            if (read.kind === 'rejected' && read.httpStatus === 404)
+                return 'missing';
+            accepted(read);
+            return 'mismatch';
+        };
+        const assertEnvelopeReceipt = (receipt) => {
+            if (receipt.kind === 'recorded')
+                return;
+            if (receipt.kind === 'unavailable')
+                fail('unavailable');
+            fail(receipt.kind === 'absent' ? 'envelope_receipt_absent' : 'envelope_receipt_mismatch');
+        };
+        assertExisting('prepared', { outbox_manifest_sha256: sha256(entry.manifestBytes), destination: operation.destination });
+        assertExisting('activation_post_intent', { envelope: m.envelope });
+        assertExisting('activation_post_uncertain', { reason: 'intent_without_remote_readback' });
+        assertExisting('report_json_put_intent', m.report_json);
+        if (m.report_md)
+            assertExisting('report_md_put_intent', m.report_md);
+        assertExisting('reviewer_put_intent', m.reviewer);
+        assertExisting('envelope_verified', { sha256: m.envelope.sha256, artifacts_declared: entry.envelope.artifacts_declared });
+        assertExisting('report_json_verified', m.report_json);
+        if (m.report_md)
+            assertExisting('report_md_verified', m.report_md);
+        assertExisting('reviewer_verified', m.reviewer);
+        this.assertRecoveryJournalAcknowledgements(operation, initialRecoveryAck);
+        await this.assertRecoveryAcknowledgements(entry, initialRecoveryAck);
+        await assertDestination();
+        let read = await privateReadback();
+        if (read.kind !== 'ok' && read.kind !== 'pending' && !absent(read))
+            accepted(read);
+        if (read.kind === 'ok' && !read.value.bytes.equals(Buffer.from(entry.privateBytes)))
+            fail('private_mismatch');
+        const plannedEnvelopeReceipt = await sink.getRunReceipt(entry.envelope, entry.envelopeBytes, request());
+        if (!absent(read))
+            assertEnvelopeReceipt(plannedEnvelopeReceipt);
+        const hasCheckpoint = (phase) => operation.journal.checkpoints()
+            .some(checkpoint => checkpoint.phase === phase);
+        const appendPlan = [];
+        const putBoundaries = [];
+        const planExact = (phase, data) => {
+            if (!hasCheckpoint(phase))
+                appendPlan.push({ phase, data });
+        };
+        const planOutcome = () => appendPlan.push({ maximumBytes: MAX_OUTCOME_CHECKPOINT_BYTES });
+        const planVerified = (prefix, data) => {
+            planExact(`${prefix}_verified`, data);
+        };
+        const planPut = (prefix, data) => {
+            const intentExists = hasCheckpoint(`${prefix}_put_intent`);
+            const index = appendPlan.length;
+            planExact(`${prefix}_put_intent`, data);
+            planOutcome();
+            planVerified(prefix, data);
+            putBoundaries.push({ index, reservation: intentExists ? PUT_COMPLETION_AFTER_INTENT_CHECKPOINTS :
+                    PUT_COMPLETION_RESERVATION_CHECKPOINTS });
+        };
+        planExact('prepared', { outbox_manifest_sha256: sha256(entry.manifestBytes), destination: operation.destination });
+        const activationUncertain = absent(read) && hasCheckpoint('activation_post_intent');
+        if (absent(read)) {
+            if (activationUncertain)
+                planExact('activation_post_uncertain', { reason: 'intent_without_remote_readback' });
+            else {
+                planExact('activation_post_intent', { envelope: m.envelope });
+                planOutcome();
+            }
+        }
+        if (!activationUncertain)
+            planExact('envelope_verified', {
+                sha256: m.envelope.sha256, artifacts_declared: entry.envelope.artifacts_declared,
+            });
+        for (const kind of ['report_json', 'report_md']) {
+            const bytes = entry.artifacts[kind];
+            if (bytes === undefined)
+                continue;
+            const state = await inspectOrdinary(kind, bytes);
+            if (state === 'mismatch')
+                fail('ordinary_mismatch');
+            if (state === 'missing') {
+                assertPutMayProceed(`${kind}_put_outcome`);
+                if (!activationUncertain)
+                    planPut(kind, m[kind]);
+            }
+            else if (!activationUncertain)
+                planVerified(kind, m[kind]);
+        }
+        if (read.kind === 'pending' || absent(read)) {
+            assertPutMayProceed('reviewer_put_outcome');
+            if (!activationUncertain)
+                planPut('reviewer', m.reviewer);
+        }
+        else if (!activationUncertain)
+            planVerified('reviewer', m.reviewer);
+        if (!activationUncertain) {
+            planExact('recovery_acknowledged', JSON.parse(initialRecoveryAck));
+            planExact('complete', { recovery_ack_sha256: '0'.repeat(64) });
+        }
+        for (const boundary of putBoundaries) {
+            operation.journal.assertAppendPlanCapacity([
+                ...appendPlan.slice(0, boundary.index),
+                ...Array.from({ length: boundary.reservation }, () => ({ maximumBytes: MAX_RECOVERY_CHECKPOINT_BYTES })),
+            ]);
+        }
+        operation.journal.assertAppendPlanCapacity(appendPlan);
+        await appendOnce('prepared', { outbox_manifest_sha256: sha256(entry.manifestBytes), destination: operation.destination });
+        if (absent(read)) {
+            const postIntent = operation.journal.checkpoints().filter(checkpoint => checkpoint.phase === 'activation_post_intent');
+            if (postIntent.length > 0) {
+                await appendOnce('activation_post_intent', { envelope: m.envelope });
+                await appendOnce('activation_post_uncertain', { reason: 'intent_without_remote_readback' });
+                fail('activation_post_uncertain');
+            }
+            // This entry-level immutable intent prevents a second manifest or journal
+            // from granting another POST after any process loss around transport.
+            await ensureActivationIntent();
+            await appendOnce('activation_post_intent', { envelope: m.envelope });
+            await assertDestination();
+            const posted = await sink.postRun(entry.envelope, request(), entry.envelopeBytes);
+            await appendOnce('activation_post_outcome', outcome(posted));
+            read = await privateReadback();
+            if (absent(read)) {
+                await appendOnce('activation_post_uncertain', { reason: 'intent_without_remote_readback' });
+                fail('activation_post_uncertain');
+            }
+        }
+        if (read.kind !== 'ok' && read.kind !== 'pending')
+            accepted(read);
+        if (read.kind === 'ok' && !read.value.bytes.equals(Buffer.from(entry.privateBytes)))
+            fail('private_mismatch');
+        const envelopeReceipt = await sink.getRunReceipt(entry.envelope, entry.envelopeBytes, request());
+        assertEnvelopeReceipt(envelopeReceipt);
+        await appendOnce('envelope_verified', { sha256: m.envelope.sha256, artifacts_declared: entry.envelope.artifacts_declared });
+        for (const kind of ['report_json', 'report_md']) {
+            const bytes = entry.artifacts[kind];
+            if (bytes === undefined)
+                continue;
+            const state = await inspectOrdinary(kind, bytes);
+            if (state === 'exact') {
+                await appendOnce(`${kind}_verified`, m[kind]);
+                continue;
+            }
+            if (state === 'mismatch')
+                fail('ordinary_mismatch');
+            assertPutMayProceed(`${kind}_put_outcome`);
+            assertPutCapacityBeforeIntent(kind);
+            await assertDestination();
+            await ensureActivationIntent();
+            await appendOnce(`${kind}_put_intent`, m[kind]);
+            operation.journal.assertAppendCapacity(PUT_COMPLETION_AFTER_INTENT_CHECKPOINTS, PUT_COMPLETION_AFTER_INTENT_BYTES);
+            const uploaded = await sink.putArtifact(m.runId, kind, bytes, request());
+            await appendPutOutcome(`${kind}_put_outcome`, outcome(uploaded));
+            if (await inspectOrdinary(kind, bytes) !== 'exact') {
+                if (uploaded.kind !== 'ok')
+                    accepted(uploaded);
+                fail('ordinary_mismatch');
+            }
+            await appendOnce(`${kind}_verified`, m[kind]);
+        }
+        read = await privateReadback();
+        if (read.kind !== 'ok' && read.kind !== 'pending')
+            accepted(read);
+        if (read.kind === 'ok' && !read.value.bytes.equals(Buffer.from(entry.privateBytes)))
+            fail('private_mismatch');
+        if (read.kind === 'pending') {
+            assertPutMayProceed('reviewer_put_outcome');
+            assertPutCapacityBeforeIntent('reviewer');
+            await assertDestination();
+            await ensureActivationIntent();
+            await appendOnce('reviewer_put_intent', m.reviewer);
+            operation.journal.assertAppendCapacity(PUT_COMPLETION_AFTER_INTENT_CHECKPOINTS, PUT_COMPLETION_AFTER_INTENT_BYTES);
+            const uploaded = await sink.putReviewerArtifact(m.runId, entry.privateBytes, m.reviewer, request());
+            await appendPutOutcome('reviewer_put_outcome', outcome(uploaded));
+            read = await privateReadback();
+            if (read.kind === 'pending') {
+                if (uploaded.kind !== 'ok')
+                    accepted(uploaded);
+                fail('unavailable');
+            }
+        }
+        if (read.kind !== 'ok' || !read.value.bytes.equals(Buffer.from(entry.privateBytes))) {
+            if (read.kind !== 'ok')
+                accepted(read);
+            fail('private_mismatch');
+        }
+        await appendOnce('reviewer_verified', m.reviewer);
+        // Completion depends on fresh exact readback of every retained server byte,
+        // even when the private artifact was already present after a lost local ACK.
+        for (const kind of ['report_json', 'report_md']) {
+            const bytes = entry.artifacts[kind];
+            if (bytes !== undefined && await inspectOrdinary(kind, bytes) !== 'exact')
+                fail('ordinary_mismatch');
+        }
+        const finalPrivate = await privateReadback();
+        if (finalPrivate.kind !== 'ok' || !finalPrivate.value.bytes.equals(Buffer.from(entry.privateBytes))) {
+            if (finalPrivate.kind === 'pending')
+                fail('unavailable');
+            if (finalPrivate.kind !== 'ok')
+                accepted(finalPrivate);
+            fail('private_mismatch');
+        }
+        await assertDestination();
+        await ensureActivationIntent();
+        const recoveryAck = this.recoveryAcknowledgement(entry, operation, activationIntent);
+        this.assertRecoveryJournalAcknowledgements(operation, recoveryAck);
+        await this.assertRecoveryAcknowledgements(entry, recoveryAck);
+        await publish(join(entry.directory, 'recovery-acknowledged.json'), recoveryAck);
+        await appendOnce('recovery_acknowledged', JSON.parse(recoveryAck));
+        await publish(join(entry.directory, 'acknowledged.json'), this.ack(entry));
+        await appendOnce('complete', { recovery_ack_sha256: sha256(recoveryAck) });
+    }
 }
 // Ephemeral creation authority is never persisted or reconstructed from a manifest.
 const entryWasNew = new WeakSet();