fraim 2.0.346 → 2.0.349

package/dist/registry/scripts/learning/run-record.js

@@ -0,0 +1,895 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunRecord = exports.RECOVERY_DIRECTORIES = exports.decodeCompletion = exports.canonical = void 0;
+exports.bindCleanupItem = bindCleanupItem;
+exports.validateDeliveryReader = validateDeliveryReader;
+exports.completedRunActions = completedRunActions;
+exports.actionDigest = actionDigest;
+exports.readRunRecord = readRunRecord;
+exports.readSupportedRunRecord = readSupportedRunRecord;
+exports.assertNoRunSyncConflicts = assertNoRunSyncConflicts;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const proposal_queue_1 = require("./proposal-queue");
+const entry_authoring_1 = require("./entry-authoring");
+const owner_identity_1 = require("./owner-identity");
+const corpus_audit_1 = require("./corpus-audit");
+const outcome_types_1 = require("./outcome-types");
+const completion_state_1 = require("./completion-state");
+var completion_state_2 = require("./completion-state");
+Object.defineProperty(exports, "canonical", { enumerable: true, get: function () { return completion_state_2.canonicalJournal; } });
+var completion_state_3 = require("./completion-state");
+Object.defineProperty(exports, "decodeCompletion", { enumerable: true, get: function () { return completion_state_3.decodeCompletion; } });
+exports.RECOVERY_DIRECTORIES = ['review-queue', 'review-archive', 'review-evidence', 'archive'];
+function bindCleanupItem(item, home) {
+    if (item.location)
+        (0, owner_identity_1.assertSameOwner)(item.location.owner, home.owner);
+    const relativePath = node_path_1.default.relative(home.contentRoot, item.path).replace(/\\/g, '/');
+    if (!exports.RECOVERY_DIRECTORIES.some(directory => relativePath.startsWith(`learnings/${directory}/`)))
+        throw new Error('cleanup-owner-unresolved');
+    const file = (0, owner_identity_1.ownerArtifactPath)(home, relativePath);
+    if (node_path_1.default.resolve(item.path) !== file)
+        throw new Error('cleanup-owner-unresolved');
+    for (let current = file; current !== node_path_1.default.dirname(node_path_1.default.resolve(home.root)); current = node_path_1.default.dirname(current)) {
+        try {
+            if (node_fs_1.default.lstatSync(current).isSymbolicLink())
+                throw new Error('cleanup-link-conflict');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (current === node_path_1.default.dirname(current))
+            throw new Error('cleanup-owner-unresolved');
+    }
+    return { ...item, path: file, location: { owner: home.owner, relativePath } };
+}
+function sameCleanupIdentity(a, b) {
+    return node_path_1.default.resolve(a.path) === node_path_1.default.resolve(b.path) || !!(a.location && b.location
+        && (0, completion_state_1.canonicalJournal)(a.location) === (0, completion_state_1.canonicalJournal)(b.location) && a.sha256 === b.sha256);
+}
+function validateDeliveryReader(reader) { validateReader(reader, false); }
+function validateReader(reader, historical) {
+    if (!reader || typeof reader !== 'object')
+        throw new Error('unsupported-capability-reader');
+    if (reader.kind === 'team-context' && Object.keys(reader).sort().join(',') === 'key,kind'
+        && ['org', 'manager', 'orgRules', 'managerRules', 'projectContext', 'projectBrief', 'projectRules', 'projectQa'].includes(reader.key))
+        return;
+    if (reader.kind === 'workspace-config' && Object.keys(reader).sort().join(',') === 'expectedValue,key,kind'
+        && ['learning.scoreThreshold', 'learning.usage.firingLogLimit', 'learning.usage.offerLogLimit', ...(historical ? ['learning.usage.retirementOfferThreshold'] : [])].includes(reader.key)
+        && Number.isFinite(reader.expectedValue) && reader.expectedValue > 0
+        && (reader.key === 'learning.scoreThreshold' || Number.isInteger(reader.expectedValue)))
+        return;
+    throw new Error('unsupported-capability-reader');
+}
+/**
+ * Issue #1857 R6 and D2.
+ *
+ * `basis` records who reached the decision. A suppression inherited from a
+ * matching earlier rejection is a decision the software made, and recording it
+ * with only a `reviewer` makes it indistinguishable from one the manager made.
+ * That is an audit-integrity problem rather than a cosmetic one: the suppression
+ * report tells the manager what was decided on their behalf, and it can only be
+ * honest if the record knows the difference. `predecessorId` names the rejection
+ * an inherited decision came from, so the report can cite it.
+ *
+ * `kind` separates the two things a rejection can mean. The manager can refuse a
+ * claim, or they can discard a queued learning because a rule or skill now owns
+ * it, which `learning-review-presentation` step 6 records as a reject. Both
+ * suppress future proposals, so without this the report would tell the manager
+ * they refused a claim they actually promoted.
+ */
+/**
+ * Issue #1857: the provenance fields are optional so records written before this
+ * change stay valid, but a half-filled pair is not. An inherited decision without
+ * its predecessor cannot be cited in the suppression report, and a `kind` on an
+ * approval is meaningless.
+ */
+function validDecisionProvenance(d) {
+    if (d.basis !== undefined && d.basis !== 'manager' && d.basis !== 'inherited')
+        return false;
+    if (d.basis === 'inherited' && (typeof d.predecessorId !== 'string' || !d.predecessorId.trim()))
+        return false;
+    if (d.predecessorId !== undefined && d.basis !== 'inherited')
+        return false;
+    if (d.kind !== undefined && (d.action !== 'reject' || (d.kind !== 'refused' && d.kind !== 'superseded')))
+        return false;
+    return true;
+}
+/** Only terminal, attributable actions with terminal dependencies belong in a receipt. */
+function completedRunActions(state) {
+    const remaining = new Map(Object.values(state.actions).filter(action => action.decision
+        && (action.decision.action === 'reject' ? !action.application : action.application?.stage === 'applied')
+        && action.sourceRefs.every(ref => action.sourceHashes?.[ref])).map(action => [action.actionId, action]));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [id, action] of remaining)
+            if (action.dependencies.some(dependency => !remaining.has(dependency))) {
+                remaining.delete(id);
+                changed = true;
+            }
+    }
+    return [...remaining.values()];
+}
+const idPattern = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,159}$/;
+function actionDigest(action) {
+    const { decision: _decision, application: _application, digest: _digest, ...revision } = action;
+    return (0, proposal_queue_1.hashContent)((0, completion_state_1.canonicalJournal)(revision));
+}
+function checkRef(ref) {
+    (0, owner_identity_1.validateOwner)(ref?.owner);
+    if (!ref.relativePath || node_path_1.default.isAbsolute(ref.relativePath) || ref.relativePath.includes('\\') || ref.relativePath.split('/').some(p => !p || p === '..' || p === '.') || ref.relativePath.includes(':'))
+        throw new Error('invalid-artifact-path');
+}
+function reviewedInput(input) {
+    const fields = ['kind', 'operation', 'claimKey', 'evidenceFingerprint', 'sourceRefs', 'sourceHashes', 'target', 'source', 'sourceHash', 'destinationHash', 'copies', 'content', 'specification', 'delivery', 'dependencies', 'verification'];
+    const result = {};
+    for (const key of fields)
+        if (input[key] !== undefined)
+            result[key] = structuredClone(input[key]);
+    return result;
+}
+function validateAction(action, historical = false) {
+    if (!['learning', 'capability'].includes(action.kind) || !['insert', 'update', 'move', 'remove', 'deliver', 'reconcile'].includes(action.operation))
+        throw new Error('invalid-action');
+    if (action.source !== undefined && action.operation !== 'move')
+        throw new Error('invalid-action-source');
+    checkRef(action.target);
+    if (action.source)
+        checkRef(action.source);
+    if (!action.claimKey?.trim() || !action.evidenceFingerprint?.trim() || !Array.isArray(action.sourceRefs) || !action.sourceRefs.length || action.sourceRefs.some(s => typeof s !== 'string' || !s))
+        throw new Error('invalid-action-evidence');
+    if (action.sourceHashes && (Object.entries(action.sourceHashes).some(([ref, hash]) => !action.sourceRefs.includes(ref) || !/^[a-f0-9]{64}$/.test(hash))))
+        throw new Error('invalid-source-hashes');
+    if (!Array.isArray(action.dependencies) || new Set(action.dependencies).size !== action.dependencies.length || !Array.isArray(action.verification) || !action.verification.length)
+        throw new Error('invalid-action-dependencies');
+    if (action.kind === 'learning') {
+        if (!/^L-[a-f0-9]{10}$/.test(action.target.entryId || ''))
+            throw new Error('invalid-entry-id');
+        if (action.operation !== 'remove') {
+            (0, entry_authoring_1.validateEntry)(action.content);
+            if (action.content.domain.status !== 'resolved')
+                throw new Error('needs-domain');
+            (0, owner_identity_1.assertLearningTargetPath)(action.target, action.content.domain.value);
+        }
+        if (action.operation === 'deliver')
+            throw new Error('invalid-learning-operation');
+    }
+    else {
+        if (action.operation !== 'deliver' || !action.specification?.trim())
+            throw new Error('capability-delivery-specification-required');
+        if (action.delivery !== undefined) {
+            if (!/^[a-f0-9]{64}$/.test(action.delivery.expectedHash) || !Array.isArray(action.delivery.callers))
+                throw new Error('invalid-capability-delivery');
+            if (action.delivery.reader !== undefined) {
+                // Historic revisions retain exact approval bytes; current proposals and execution use the active reader contract.
+                validateReader(action.delivery.reader, historical);
+                if (action.delivery.callers.length)
+                    throw new Error('invalid-capability-reader-callers');
+                if (action.delivery.reader.kind === 'workspace-config' && (action.target.owner.level !== 'Project' || action.target.relativePath !== 'config.json'))
+                    throw new Error('invalid-workspace-config-target');
+            }
+            else if (!action.delivery.callers.length)
+                throw new Error('invalid-capability-delivery');
+            if (action.target.owner.level === 'Project' && action.target.relativePath === 'config.json' && action.delivery.reader?.kind !== 'workspace-config')
+                throw new Error('workspace-config-reader-required');
+            for (const caller of action.delivery.callers)
+                checkRef(caller);
+        }
+    }
+    if (['update', 'move', 'remove'].includes(action.operation) && !/^[a-f0-9]{64}$/.test(action.sourceHash || action.destinationHash || ''))
+        throw new Error('source-hash-required');
+    if (action.operation === 'move' && (!action.source || action.source.entryId !== action.target.entryId || (0, completion_state_1.canonicalJournal)(action.source) === (0, completion_state_1.canonicalJournal)(action.target)))
+        throw new Error('invalid-move');
+    if (action.operation === 'reconcile') {
+        if (action.kind !== 'learning' || action.source || !Array.isArray(action.copies) || !action.copies.length
+            || (action.destinationHash !== undefined && !/^[a-f0-9]{64}$/.test(action.destinationHash)))
+            throw new Error('invalid-reconciliation');
+        const keys = new Set([(0, corpus_audit_1.corpusEntryKey)({ ref: action.target, sha256: '' })]);
+        for (const copy of action.copies) {
+            checkRef(copy.ref);
+            const key = (0, corpus_audit_1.corpusEntryKey)({ ref: copy.ref, sha256: copy.sha256 });
+            if (copy.ref.entryId !== action.target.entryId || keys.has(key) || !/^[a-f0-9]{64}$/.test(copy.sha256)
+                || !/^learnings\/.+-(preferences|mistake-patterns|validated-patterns|manager-coaching)(\.cold)?\.md$/.test(copy.ref.relativePath))
+                throw new Error('invalid-reconciliation');
+            keys.add(key);
+        }
+    }
+    else if (action.copies !== undefined)
+        throw new Error('invalid-reconciliation');
+}
+function validateApplication(action, application) {
+    if (!application || !['prepared', 'written', 'published', 'applied'].includes(application.stage) || !Array.isArray(application.steps))
+        throw new Error('invalid-application');
+    const refs = action.kind === 'learning' ? [action.target, ...(action.operation === 'move' ? [action.source] : action.copies?.map(copy => copy.ref) || [])] : [];
+    if (application.steps.length !== refs.length)
+        throw new Error('invalid-application-targets');
+    for (const [index, step] of application.steps.entries()) {
+        const after = index > 0 || action.operation === 'remove' ? null : (0, entry_authoring_1.renderEntry)(action.target.entryId, action.content).trimEnd();
+        const expectedHash = index > 0 ? action.operation === 'reconcile' ? action.copies[index - 1].sha256 : action.sourceHash : action.destinationHash || (action.operation !== 'move' ? action.sourceHash : undefined);
+        if ((0, completion_state_1.canonicalJournal)(step.ref) !== (0, completion_state_1.canonicalJournal)(refs[index]) || step.after !== after
+            || (index === 0 && (['insert', 'move'].includes(action.operation) || (action.operation === 'reconcile' && !action.destinationHash)) ? step.before !== null : typeof step.before !== 'string' || (0, proposal_queue_1.hashContent)(step.before) !== expectedHash)
+            || (step.published && !step.written) || (application.stage === 'applied' && !step.published))
+            throw new Error('invalid-application-targets');
+        const prior = action.application?.steps[index];
+        if (prior && (prior.before !== step.before || prior.after !== step.after || (0, completion_state_1.canonicalJournal)(prior.ref) !== (0, completion_state_1.canonicalJournal)(step.ref)
+            || (prior.written && !step.written) || (prior.published && !step.published)))
+            throw new Error('invalid-application-transition');
+    }
+    if (action.application?.stage === 'applied' && application.stage !== 'applied')
+        throw new Error('invalid-application-transition');
+}
+function validateReconciliation(item, state) {
+    (0, owner_identity_1.validateOwner)(item.owner);
+    if (!item.sourceRef || !node_path_1.default.isAbsolute(item.sourceRef) || !/^[a-f0-9]{64}$/.test(item.sourceHash)
+        || !exports.RECOVERY_DIRECTORIES.some(directory => item.relativePath?.startsWith(`learnings/${directory}/`))
+        || /[\\:]/.test(item.relativePath) || item.relativePath.split('/').some(part => !part || part === '.' || part === '..')
+        || !['accounted', 'unrelated', 'raw-source'].includes(item.disposition) || !item.rationale?.trim()
+        || item.reviewer !== state.reviewer || !Array.isArray(item.preservedDecisions) || item.preservedDecisions.some(value => typeof value !== 'string' || !value.trim())
+        || !Array.isArray(item.actionIds) || new Set(item.actionIds).size !== item.actionIds.length || !Array.isArray(item.actionBindings)
+        || item.actionBindings.length !== item.actionIds.length)
+        throw new Error('invalid-source-reconciliation');
+    for (const [index, id] of item.actionIds.entries()) {
+        const action = state.actions[id];
+        const binding = item.actionBindings[index];
+        if (!action?.decision || action.decision.digest !== action.digest || binding.actionId !== id || binding.revision !== action.revision || binding.digest !== action.digest
+            || !action.sourceRefs.some(ref => ref.replace(/\\/g, '/') === item.sourceRef.replace(/\\/g, '/') && action.sourceHashes?.[ref] === item.sourceHash))
+            throw new Error('reconciliation-action-conflict');
+    }
+}
+function replay(file) {
+    const journal = (0, completion_state_1.readRunJournal)(file);
+    if (journal.format === 'historical')
+        throw new completion_state_1.UnsupportedRunHistoryError();
+    let state;
+    for (const event of journal.events) {
+        const { type, data } = event.payload;
+        if (!state) {
+            if (type !== 'created' || data.schemaVersion !== 1 || !idPattern.test(data.runId) || !data.reviewer)
+                throw new Error('invalid-run');
+            (0, owner_identity_1.validateOwner)(data.owner);
+            if (data.completionDirectory !== undefined)
+                validateCompletionDirectory(data.completionDirectory, data.owner);
+            state = { schemaVersion: 1, runId: data.runId, owner: data.owner, reviewer: data.reviewer, sequence: 0, actions: {}, appliedOrder: [], sourceDispositions: [], cleanup: [], reconciliations: [], pendingReviewActionIds: [],
+                ...(data.completionDirectory !== undefined ? { completionDirectory: data.completionDirectory } : {}),
+                ...(data.sourceParticipants !== undefined ? { sourceParticipants: (0, completion_state_1.normalizeSourceParticipants)(data.sourceParticipants, data.owner) } : {}),
+                ...(data.corpusAuditRequired === true ? { corpusAuditRequired: true } : {}) };
+        }
+        else if (type === 'action') {
+            validateAction(data, true);
+            if (!idPattern.test(data.actionId) || !Number.isInteger(data.revision) || data.revision < 1 || actionDigest(data) !== data.digest)
+                throw new Error('invalid-revision');
+            const prior = state.actions[data.actionId];
+            if (data.revision !== (prior?.revision || 0) + 1 || prior?.application || data.application || data.decision)
+                throw new Error('invalid-revision-transition');
+            state.actions[data.actionId] = data;
+        }
+        else if (type === 'decision') {
+            const action = state.actions[data.actionId];
+            const d = data.decision;
+            if (!action || action.application || d.revision !== action.revision || d.digest !== action.digest || d.reviewer !== state.reviewer || !['approve', 'reject'].includes(d.action) || typeof d.reason !== 'string' || !d.reason.trim() || (d.revisitCondition !== undefined && (d.action !== 'reject' || typeof d.revisitCondition !== 'string' || !d.revisitCondition.trim())) || !validDecisionProvenance(d))
+                throw new Error('invalid-decision');
+            action.decision = d;
+        }
+        else if (type === 'decision-batch') {
+            if (!Array.isArray(data) || !data.length || new Set(data.map(item => item.actionId)).size !== data.length)
+                throw new Error('invalid-batch-decision');
+            for (const item of data) {
+                const action = state.actions[item.actionId];
+                const decision = item.decision;
+                if (!action || action.application || decision.action !== 'approve' || decision.revision !== action.revision || decision.digest !== action.digest || decision.reviewer !== state.reviewer || !decision.reason)
+                    throw new Error('invalid-batch-decision');
+            }
+            for (const item of data)
+                state.actions[item.actionId].decision = item.decision;
+        }
+        else if (type === 'application') {
+            const action = state.actions[data.actionId];
+            if (!action || action.decision?.action !== 'approve' || data.digest !== action.digest || !['prepared', 'written', 'published', 'applied'].includes(data.application?.stage))
+                throw new Error('invalid-application');
+            validateApplication(action, data.application);
+            action.application = data.application;
+            if (action.application?.stage === 'applied')
+                state.appliedOrder = [...state.appliedOrder.filter(id => id !== action.actionId), action.actionId];
+        }
+        else if (type === 'reconciliation') {
+            const { reconciliation, cleanup } = data;
+            validateReconciliation(reconciliation, state);
+            state.reconciliations = state.reconciliations.filter(item => item.sourceRef !== reconciliation.sourceRef).concat(reconciliation);
+            state.cleanup = state.cleanup.filter(item => item.path !== cleanup.path).concat(cleanup);
+        }
+        else if (type === 'assessment-prepared') {
+            (0, outcome_types_1.validateOutcomeAssessmentRecord)(data.record);
+            if (data.record.runId !== state.runId || data.record.reviewer !== state.reviewer
+                || !Array.isArray(data.sourcePaths) || data.sourcePaths.length !== data.record.sourceRefs.length || data.sourcePaths.some((file) => typeof file !== 'string' || !node_path_1.default.isAbsolute(file))
+                || [...(state.outcomeAssessments ?? []), ...(state.pendingOutcomeAssessments ?? [])].some(item => item.digest === data.record.digest))
+                throw new Error('invalid-assessment-transition');
+            state.pendingOutcomeAssessments = [...(state.pendingOutcomeAssessments ?? []), data.record];
+        }
+        else if (type === 'assessment-committed') {
+            const prepared = state.pendingOutcomeAssessments?.find(item => item.digest === data.digest);
+            if (!prepared)
+                throw new Error('invalid-assessment-transition');
+            state.outcomeAssessments = [...(state.outcomeAssessments ?? []), prepared];
+            state.pendingOutcomeAssessments = state.pendingOutcomeAssessments.filter(item => item.digest !== data.digest);
+        }
+        else if (type === 'corpus-audit') {
+            (0, corpus_audit_1.validateCorpusAudit)(data, state.reviewer);
+            state.corpusAudit = data;
+        }
+        else if (type === 'disposition')
+            state.sourceDispositions.push(data);
+        else if (type === 'cleanup')
+            state.cleanup.push(data);
+        else if (type === 'source-completion') {
+            (0, completion_state_1.validateProcessedSources)(data);
+            if (state.processedSources?.some(prior => !data.some((item) => (0, completion_state_1.canonicalJournal)(item) === (0, completion_state_1.canonicalJournal)(prior))))
+                throw new Error('completion-sources-conflict');
+            state.processedSources = data;
+        }
+        else if (type === 'checkpoint') {
+            const receipt = (0, completion_state_1.decodeCompletion)(`<!-- fraim-sleep-decisions:v1 -->\n\x60\x60\x60json\n${JSON.stringify(data.receipt)}\n\x60\x60\x60\n<!-- /fraim-sleep-decisions -->`, { runId: state.runId, owner: state.owner });
+            if (!receipt.deferred || !/^[a-f0-9]{64}$/.test(data.evidenceHash))
+                throw new Error('invalid-checkpoint');
+            for (const item of [...receipt.decisions, ...receipt.deferred.actions])
+                if (state.actions[item.actionId]?.digest !== item.digest || state.actions[item.actionId]?.revision !== item.revision)
+                    throw new Error('checkpoint-action-conflict');
+            const completed = completedRunActions(state);
+            if (receipt.decisions.length !== completed.length || receipt.decisions.some(item => !completed.some(action => action.actionId === item.actionId
+                && (0, completion_state_1.canonicalJournal)(action.decision) === (0, completion_state_1.canonicalJournal)(item.decision) && (0, completion_state_1.canonicalJournal)(action.target) === (0, completion_state_1.canonicalJournal)(item.target))))
+                throw new Error('checkpoint-action-conflict');
+            if ((0, completion_state_1.canonicalJournal)(receipt.processedSources) !== (0, completion_state_1.canonicalJournal)(state.processedSources))
+                throw new Error('completion-sources-conflict');
+            if ((0, completion_state_1.canonicalJournal)(receipt.outcomeAssessments) !== (0, completion_state_1.canonicalJournal)(state.outcomeAssessments))
+                throw new Error('completion-assessments-conflict');
+            state.checkpoint = data;
+            if (receipt.finalizationState === 'complete' && !state.deferredHistory?.some(prior => (0, completion_state_1.canonicalJournal)(prior) === (0, completion_state_1.canonicalJournal)(receipt.deferred)))
+                state.deferredHistory = [...(state.deferredHistory || []), receipt.deferred];
+        }
+        else if (type === 'finalization')
+            state.finalization = data;
+        else if (type === 'deferred-attempt') {
+            (0, completion_state_1.validateDeferredAttempt)(data);
+            if (!state.checkpoint || state.checkpoint.receipt.finalizationState !== 'complete' || state.checkpoint.evidenceHash !== data.evidenceHash
+                || (data.deferred !== undefined && (0, completion_state_1.canonicalJournal)(state.checkpoint.receipt.deferred) !== (0, completion_state_1.canonicalJournal)(data.deferred)))
+                throw new Error('deferred-attempt-conflict');
+            state.deferredAttempts = [...(state.deferredAttempts ?? []), data];
+        }
+        else
+            throw new Error('unknown-journal-event');
+        state.sequence = event.sequence;
+    }
+    if (!state)
+        throw new Error('empty-journal');
+    state.pendingReviewActionIds = Object.values(state.actions).filter(action => !action.decision).map(action => action.actionId);
+    return { state, events: journal.events, lastHash: journal.lastHash };
+}
+function readRunRecord(file) { return replay(file).state; }
+/** Enumeration skips only recognized historical records; current corruption must remain visible. */
+function readSupportedRunRecord(file) {
+    try {
+        return readRunRecord(file);
+    }
+    catch (error) {
+        if (error instanceof completion_state_1.UnsupportedRunHistoryError)
+            return undefined;
+        throw error;
+    }
+}
+function assertNoRunSyncConflicts(directory, runId) {
+    if (node_fs_1.default.existsSync(directory) && node_fs_1.default.readdirSync(directory).some(name => name.startsWith(runId + ' ') && /jsonl/i.test(name)))
+        throw new Error('journal-sync-conflict');
+}
+/** One append-only record holds every reviewed revision, decision and recovery step. */
+function validateCompletionDirectory(directory, owner) {
+    if (typeof directory !== 'string' || !node_path_1.default.isAbsolute(directory) || /[\x00-\x1f]/.test(directory))
+        throw new Error('invalid-completion-directory');
+    const relative = node_path_1.default.relative((0, completion_state_1.sourcePathKey)(owner.path), (0, completion_state_1.sourcePathKey)(directory));
+    if (!relative || relative === '..' || relative.startsWith('..' + node_path_1.default.sep) || node_path_1.default.isAbsolute(relative))
+        throw new Error('invalid-completion-directory');
+}
+class RunRecord {
+    constructor(directory, runId, owner, reviewer, completionDirectory = directory) {
+        this.directory = directory;
+        this.runId = runId;
+        this.owner = owner;
+        this.reviewer = reviewer;
+        this.completionDirectory = completionDirectory;
+        (0, owner_identity_1.validateOwner)(owner);
+        if (!idPattern.test(runId) || !reviewer?.trim())
+            throw new Error('invalid-run-context');
+        validateCompletionDirectory(completionDirectory, owner);
+        this.file = node_path_1.default.join(directory, runId + '.queue.jsonl');
+        this.completionFile = node_path_1.default.join(completionDirectory, runId + '-completion.md');
+        for (const file of [this.file, this.completionFile])
+            if (node_fs_1.default.existsSync(file) && node_fs_1.default.lstatSync(file).isSymbolicLink())
+                throw new Error('run-path-link-conflict');
+    }
+    read() {
+        assertNoRunSyncConflicts(this.directory, this.runId);
+        const state = readRunRecord(this.file);
+        (0, owner_identity_1.assertSameOwner)(this.owner, state.owner);
+        if (state.runId !== this.runId || state.reviewer !== this.reviewer)
+            throw new Error('run-context-mismatch');
+        this.assertCompletionDirectory(state);
+        return state;
+    }
+    assertCompletionDirectory(state) {
+        if ((0, completion_state_1.sourcePathKey)(state.completionDirectory ?? this.directory) !== (0, completion_state_1.sourcePathKey)(this.completionDirectory))
+            throw new Error('completion-evidence-path-changed');
+    }
+    append(type, data, operationId = (0, node_crypto_1.randomUUID)()) {
+        const prior = node_fs_1.default.existsSync(this.file) ? replay(this.file) : undefined;
+        if (prior)
+            this.assertCompletionDirectory(prior.state);
+        const payload = { type, data };
+        const event = { sequence: (prior?.state.sequence || 0) + 1, previousHash: prior?.lastHash || '', operationId, payloadHash: (0, proposal_queue_1.hashContent)((0, completion_state_1.canonicalJournal)(payload)), payload };
+        const fd = node_fs_1.default.openSync(this.file, 'a', 0o600);
+        try {
+            node_fs_1.default.writeSync(fd, (0, completion_state_1.canonicalJournal)(event) + '\n');
+            node_fs_1.default.fsyncSync(fd);
+        }
+        finally {
+            node_fs_1.default.closeSync(fd);
+        }
+    }
+    create(sourceParticipants) {
+        const grants = sourceParticipants === undefined ? undefined : (0, completion_state_1.normalizeSourceParticipants)(sourceParticipants, this.owner);
+        return (0, proposal_queue_1.withFileLock)(this.file, () => {
+            if (node_fs_1.default.existsSync(this.file)) {
+                const state = this.read();
+                if (grants !== undefined && (0, completion_state_1.canonicalJournal)(grants) !== (0, completion_state_1.canonicalJournal)(state.sourceParticipants ?? []))
+                    throw new Error('source-participants-conflict');
+                return state;
+            }
+            if (node_fs_1.default.existsSync(this.completionFile))
+                throw new Error('run-completed');
+            this.append('created', { schemaVersion: 1, runId: this.runId, owner: this.owner, reviewer: this.reviewer, completionDirectory: node_path_1.default.resolve(this.completionDirectory), ...(this.owner.level === 'Manager' ? { corpusAuditRequired: true } : {}), ...(grants !== undefined ? { sourceParticipants: grants } : {}) });
+            return this.read();
+        });
+    }
+    mutate(expectedSequence, fn) {
+        return (0, proposal_queue_1.withFileLock)(this.file, () => {
+            const state = this.read();
+            if (!Number.isInteger(expectedSequence) || state.sequence !== expectedSequence)
+                throw new Error('stale-sequence');
+            if (state.finalization || state.checkpoint?.receipt.finalizationState === 'pending')
+                throw new Error('finalization-started');
+            return fn(state);
+        });
+    }
+    prepareOutcomeAssessment(record, expectedSequence, sourcePaths) {
+        (0, outcome_types_1.validateOutcomeAssessmentRecord)(record);
+        if (!Array.isArray(sourcePaths) || sourcePaths.length !== record.sourceRefs.length || sourcePaths.some(file => !node_path_1.default.isAbsolute(file)))
+            throw new Error('invalid-assessment-sources');
+        this.mutate(expectedSequence, state => {
+            if (record.runId !== state.runId || record.reviewer !== state.reviewer)
+                throw new Error('run-context-mismatch');
+            if ([...(state.outcomeAssessments ?? []), ...(state.pendingOutcomeAssessments ?? [])].some(item => item.digest === record.digest))
+                return;
+            this.append('assessment-prepared', { record, sourcePaths });
+        });
+    }
+    commitOutcomeAssessment(digest, expectedSequence) {
+        this.mutate(expectedSequence, state => {
+            if (state.outcomeAssessments?.some(item => item.digest === digest))
+                return;
+            if (!state.pendingOutcomeAssessments?.some(item => item.digest === digest))
+                throw new Error('assessment-not-prepared');
+            this.append('assessment-committed', { digest });
+        });
+    }
+    propose(input, expectedSequence) {
+        input = reviewedInput(input);
+        validateAction(input);
+        return this.mutate(expectedSequence, state => {
+            for (const dependency of input.dependencies)
+                if (!state.actions[dependency])
+                    throw new Error('missing-dependency');
+            const prior = Object.values(state.actions).find(a => a.claimKey === input.claimKey && a.evidenceFingerprint === input.evidenceFingerprint && (0, owner_identity_1.ownerKey)(a.target.owner) === (0, owner_identity_1.ownerKey)(input.target.owner));
+            if (prior)
+                return prior;
+            for (const name of node_fs_1.default.readdirSync(this.directory).filter(n => n.endsWith('-completion.md'))) {
+                const history = node_fs_1.default.readFileSync(node_path_1.default.join(this.directory, name), 'utf8');
+                let completed;
+                try {
+                    completed = (0, completion_state_1.decodeCompletion)(history);
+                }
+                catch {
+                    continue;
+                } // Historical formats are interpreted by the agent, not imported here.
+                if (completed.decisions.some(d => d.claimKey === input.claimKey && d.evidenceFingerprint === input.evidenceFingerprint && (0, owner_identity_1.ownerKey)(d.owner) === (0, owner_identity_1.ownerKey)(input.target.owner)))
+                    throw new Error('already-reviewed: unchanged evidence');
+            }
+            const action = { ...structuredClone(input), actionId: (0, node_crypto_1.randomUUID)(), revision: 1 };
+            action.digest = actionDigest(action);
+            this.append('action', action);
+            return action;
+        });
+    }
+    edit(actionId, revision, input, expectedSequence) {
+        input = reviewedInput(input);
+        validateAction(input);
+        return this.mutate(expectedSequence, state => {
+            const prior = state.actions[actionId];
+            if (!prior || prior.revision !== revision)
+                throw new Error('stale-revision');
+            if (state.checkpoint?.receipt.decisions.some(item => item.actionId === actionId))
+                throw new Error('action-completed');
+            if (prior.application)
+                throw new Error('application-started');
+            if (prior.content && input.content && (0, completion_state_1.canonicalJournal)(prior.content.trace) !== (0, completion_state_1.canonicalJournal)(input.content.trace))
+                throw new Error('immutable-history');
+            if (prior.target.entryId !== input.target.entryId)
+                throw new Error('immutable-entry-id');
+            if (input.dependencies.includes(actionId) || input.dependencies.some(id => !state.actions[id]))
+                throw new Error('invalid-dependencies');
+            const reaches = (id, visited = new Set()) => {
+                if (id === actionId)
+                    return true;
+                if (visited.has(id))
+                    return false;
+                visited.add(id);
+                return state.actions[id]?.dependencies.some(dependency => reaches(dependency, visited)) || false;
+            };
+            if (input.dependencies.some(id => reaches(id)))
+                throw new Error('dependency-cycle');
+            const action = { ...structuredClone(input), actionId, revision: revision + 1 };
+            action.digest = actionDigest(action);
+            this.append('action', action);
+            return action;
+        });
+    }
+    decide(actionId, revision, decision, expectedSequence) {
+        return this.mutate(expectedSequence, state => {
+            const action = state.actions[actionId];
+            if (!action || action.revision !== revision)
+                throw new Error('stale-revision');
+            if (state.checkpoint?.receipt.decisions.some(item => item.actionId === actionId))
+                throw new Error('action-completed');
+            if (action.application || decision.reviewer !== state.reviewer || typeof decision.reason !== 'string' || !decision.reason.trim() || !['approve', 'reject'].includes(decision.action) || (decision.revisitCondition !== undefined && (decision.action !== 'reject' || typeof decision.revisitCondition !== 'string' || !decision.revisitCondition.trim())) || !validDecisionProvenance(decision))
+                throw new Error('invalid-decision');
+            this.append('decision', { actionId, decision: { ...decision, revision, digest: action.digest, at: new Date().toISOString() } });
+            return this.read().actions[actionId];
+        });
+    }
+    decideBatch(tuples, reviewer, reason, expectedSequence) {
+        return this.mutate(expectedSequence, state => {
+            if (reviewer !== state.reviewer || !reason.trim() || !tuples.length || new Set(tuples.map(t => t.actionId)).size !== tuples.length)
+                throw new Error('invalid-batch-decision');
+            for (const tuple of tuples) {
+                const action = state.actions[tuple.actionId];
+                if (!action || action.application || action.revision !== tuple.revision || action.digest !== tuple.digest)
+                    throw new Error('stale-batch-decision');
+                if (state.checkpoint?.receipt.decisions.some(item => item.actionId === tuple.actionId))
+                    throw new Error('action-completed');
+            }
+            // One event makes batch approval interruption-atomic.
+            this.append('decision-batch', tuples.map(tuple => ({ actionId: tuple.actionId, decision: { action: 'approve', revision: tuple.revision, digest: tuple.digest, reviewer, reason, at: new Date().toISOString() } })));
+            return this.read();
+        });
+    }
+    recoverTail(expectedPrefixHash) {
+        return (0, proposal_queue_1.withFileLock)(this.file, () => {
+            const raw = node_fs_1.default.readFileSync(this.file, 'utf8');
+            if (raw.endsWith('\n'))
+                return this.read();
+            const end = raw.lastIndexOf('\n') + 1;
+            const prefix = raw.slice(0, end);
+            if (!end || (0, proposal_queue_1.hashContent)(prefix) !== expectedPrefixHash)
+                throw new Error('recovery-prefix-conflict');
+            // Validate the intact prefix through the same replay parser before truncating.
+            const temporary = this.file + '.recovery-check';
+            try {
+                node_fs_1.default.writeFileSync(temporary, prefix, { flag: 'wx' });
+                this.assertCompletionDirectory(replay(temporary).state);
+            }
+            finally {
+                if (node_fs_1.default.existsSync(temporary))
+                    node_fs_1.default.unlinkSync(temporary);
+            }
+            const fd = node_fs_1.default.openSync(this.file, 'r+');
+            try {
+                node_fs_1.default.ftruncateSync(fd, Buffer.byteLength(prefix));
+                node_fs_1.default.fsyncSync(fd);
+            }
+            finally {
+                node_fs_1.default.closeSync(fd);
+            }
+            return this.read();
+        });
+    }
+    progress(actionId, application) {
+        const state = this.read();
+        const action = state.actions[actionId];
+        if (!action || action.decision?.action !== 'approve' || action.decision.digest !== action.digest)
+            throw new Error('not-approved');
+        validateApplication(action, application);
+        this.append('application', { actionId, digest: action.digest, application });
+    }
+    recordCleanup(item, expectedSequence) {
+        // The normal run location supplies an unambiguous same-owner home for
+        // direct registrations. Cross-owner reconciliations bind their resolved home explicitly.
+        if (!item.location) {
+            const root = node_fs_1.default.realpathSync.native(this.owner.path);
+            for (const contentRoot of [node_path_1.default.join(root, 'personalized-employee'), root]) {
+                const relative = node_path_1.default.relative(contentRoot, item.path).replace(/\\/g, '/');
+                if (exports.RECOVERY_DIRECTORIES.some(directory => relative.startsWith(`learnings/${directory}/`))) {
+                    item = bindCleanupItem(item, { owner: this.owner, level: this.owner.level, root, contentRoot, backend: 'local-folder', requiresPublish: false });
+                    break;
+                }
+            }
+        }
+        this.mutate(expectedSequence, () => this.append('cleanup', item));
+    }
+    /** Record agent interpretation only after exact source identity and current decisions are bound. */
+    reconcileSource(input, home, expectedSequence) {
+        (0, owner_identity_1.assertSameOwner)(input.owner, home.owner);
+        const file = (0, owner_identity_1.ownerArtifactPath)(home, input.relativePath);
+        const cleanup = bindCleanupItem({ path: file, sha256: input.sha256,
+            outcome: input.disposition === 'accounted' ? 'pending' : 'retained',
+            reason: input.disposition === 'accounted' ? 'reviewed-source' : input.disposition }, home);
+        if (!node_fs_1.default.lstatSync(file).isFile() || (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(file, 'utf8')) !== input.sha256)
+            throw new Error('source-content-conflict');
+        return this.mutate(expectedSequence, state => {
+            const reconciliation = {
+                sourceRef: file, sourceHash: input.sha256, owner: input.owner, relativePath: input.relativePath,
+                disposition: input.disposition, rationale: input.rationale, preservedDecisions: input.preservedDecisions, reviewer: input.reviewer,
+                actionIds: input.actionIds, actionBindings: (input.actionIds || []).map(actionId => {
+                    const action = state.actions[actionId];
+                    if (!action)
+                        throw new Error('reconciliation-action-missing');
+                    return { actionId, revision: action.revision, digest: action.digest };
+                }),
+            };
+            validateReconciliation(reconciliation, state);
+            this.append('reconciliation', { reconciliation, cleanup });
+            return this.read();
+        });
+    }
+    assertReconciliations() {
+        const state = this.read();
+        for (const item of state.reconciliations)
+            validateReconciliation(item, state);
+    }
+    prepareSourceCompletion(sources, expectedSequence, extend = false) {
+        (0, completion_state_1.validateProcessedSources)(sources);
+        this.mutate(expectedSequence, state => {
+            if (state.processedSources && (0, completion_state_1.canonicalJournal)(state.processedSources) !== (0, completion_state_1.canonicalJournal)(sources) && (!extend || state.processedSources.some(prior => !sources.some(item => (0, completion_state_1.canonicalJournal)(item) === (0, completion_state_1.canonicalJournal)(prior)))))
+                throw new Error('completion-sources-conflict');
+            if ((0, completion_state_1.canonicalJournal)(state.processedSources) !== (0, completion_state_1.canonicalJournal)(sources))
+                this.append('source-completion', sources);
+        });
+    }
+    recordCorpusAudit(input, expectedSequence) {
+        return this.mutate(expectedSequence, state => {
+            const audit = structuredClone(input);
+            for (const disposition of audit.dispositions)
+                disposition.actionBindings = disposition.actionIds.map(id => {
+                    const action = state.actions[id];
+                    if (!action)
+                        throw new Error('corpus-audit-action-missing');
+                    const refs = [action.target, ...(action.source ? [action.source] : []), ...(action.copies?.map(copy => copy.ref) || [])];
+                    if (!refs.some(ref => (0, corpus_audit_1.corpusEntryKey)({ ref, sha256: '' }) === (0, corpus_audit_1.corpusEntryKey)(disposition)))
+                        throw new Error('corpus-audit-action-unrelated');
+                    return { actionId: id, revision: action.revision, digest: action.digest };
+                });
+            (0, corpus_audit_1.validateCorpusAudit)(audit, state.reviewer);
+            this.append('corpus-audit', audit);
+            return this.read();
+        });
+    }
+    complete(summary, inventory, afterStage, verifyApplied, retrospective, finishSources, deferred) {
+        return (0, proposal_queue_1.withFileLock)(this.file, () => {
+            assertNoRunSyncConflicts(this.directory, this.runId);
+            const inspect = () => {
+                const items = new Map();
+                for (const item of inventory()) {
+                    const key = node_path_1.default.resolve(item.path);
+                    const prior = items.get(key);
+                    if (prior && (0, completion_state_1.canonicalJournal)(prior) !== (0, completion_state_1.canonicalJournal)(item))
+                        throw new Error('cleanup-inventory-conflict');
+                    if (item.outcome === 'retained' && item.reason !== 'unrelated' && item.reason !== 'raw-source')
+                        throw new Error('cleanup-unresolved');
+                    items.set(key, item);
+                }
+                return [...items.values()];
+            };
+            const finishedInventory = () => {
+                const items = inspect();
+                if (items.some(item => item.outcome === 'pending'))
+                    throw new Error('cleanup-incomplete');
+                return items;
+            };
+            if (!node_fs_1.default.existsSync(this.file)) {
+                const result = (0, completion_state_1.decodeCompletion)(node_fs_1.default.readFileSync(this.completionFile, 'utf8'), { runId: this.runId, owner: this.owner });
+                if (result.finalizationState !== 'complete')
+                    throw new Error('incomplete-finalization');
+                if ((0, completion_state_1.canonicalJournal)(result.retrospective) !== (0, completion_state_1.canonicalJournal)(retrospective))
+                    throw new Error('completion-retrospective-conflict');
+                verifyApplied?.(true);
+                finishedInventory();
+                return result;
+            }
+            const state = this.read();
+            if (state.pendingOutcomeAssessments?.length && !deferred)
+                throw new Error('assessment-processing-pending');
+            if (!summary?.trim() || summary.includes('fraim-sleep-decisions'))
+                throw new Error('invalid-completion-summary');
+            const actions = deferred ? completedRunActions(state) : Object.values(state.actions);
+            if (deferred) {
+                (0, completion_state_1.validateDeferredWork)(deferred);
+                const ids = new Set(actions.map(action => action.actionId));
+                if ((0, completion_state_1.canonicalJournal)(deferred.actions.map(item => [item.actionId, item.revision, item.digest])) !== (0, completion_state_1.canonicalJournal)(Object.values(state.actions).filter(action => !ids.has(action.actionId)).map(action => [action.actionId, action.revision, action.digest])))
+                    throw new Error('checkpoint-action-conflict');
+            }
+            else {
+                if (state.corpusAuditRequired && !state.corpusAudit)
+                    throw new Error('corpus-audit-required');
+                this.assertReconciliations();
+                if (actions.some(a => !a.decision || (a.decision.action === 'approve' && a.application?.stage !== 'applied') || (a.decision.action !== 'approve' && a.application)))
+                    throw new Error('run-unfinished');
+            }
+            if (actions.some(action => action.sourceRefs.some(ref => !action.sourceHashes?.[ref])))
+                throw new Error('source-hashes-required: record the actual source hash before completion');
+            if ((deferred || state.corpusAudit || actions.some(action => action.application)) && !verifyApplied)
+                throw new Error('completion-verifier-required');
+            verifyApplied?.();
+            const snapshot = deferred ? [] : inspect();
+            const reconciliationHistory = actions.filter(action => action.operation === 'reconcile' && action.application?.stage === 'applied').map(action => ({
+                actionId: action.actionId, revision: action.revision, digest: action.digest, target: action.target,
+                resultHash: (0, proposal_queue_1.hashContent)(action.application.steps[0].after),
+                occurrences: action.application.steps.filter(step => step.before !== null).map(step => ({ ref: step.ref, sha256: (0, proposal_queue_1.hashContent)(step.before), before: step.before })),
+            }));
+            const result = {
+                schemaVersion: 1, runId: this.runId, owner: this.owner, finalizationState: 'pending',
+                decisions: actions.map(a => ({ actionId: a.actionId, revision: a.revision, digest: a.digest, owner: a.target.owner, target: a.target, claimKey: a.claimKey, evidenceFingerprint: a.evidenceFingerprint, sourceRefs: a.sourceRefs, decision: a.decision, dependencies: a.dependencies.map(id => ({ actionId: id, outcome: state.actions[id].decision?.action === 'approve' ? 'applied' : 'rejected' })), ...(a.application?.publicationRef ? { publicationRef: a.application.publicationRef } : {}) })),
+                sourceDispositions: actions.flatMap(a => a.sourceRefs.map(sourceRef => ({ sourceRef, sourceHash: a.sourceHashes[sourceRef], outcome: a.decision.action === 'approve' ? 'applied' : 'rejected', actionId: a.actionId }))),
+                cleanup: snapshot,
+                ...(state.processedSources ? { processedSources: state.processedSources } : {}),
+                ...(state.sourceParticipants !== undefined ? { sourceParticipants: state.sourceParticipants } : {}),
+                ...(state.outcomeAssessments?.length ? { outcomeAssessments: state.outcomeAssessments } : {}),
+                ...(retrospective ? { retrospective } : {}),
+                ...(deferred ? { deferred } : {
+                    ...(state.reconciliations.length ? { reconciliations: state.reconciliations } : {}),
+                    ...(state.corpusAudit ? { corpusAudit: state.corpusAudit } : {}),
+                    ...(reconciliationHistory.length ? { reconciliationHistory } : {}),
+                    ...(state.deferredHistory?.length ? { deferredHistory: state.deferredHistory } : {}),
+                    ...(state.deferredAttempts?.length ? { deferredAttempts: state.deferredAttempts } : {}),
+                }),
+            };
+            let narrative = `---\nartifactKind: work-evidence\ncontainsFeedback: ${actions.length > 0}\ndate: ${new Date().toISOString().slice(0, 10)}\n---\n# Sleep completion: ${this.runId}\n\n${summary}\n\nApplied: ${actions.filter(a => a.application?.stage === 'applied').length}; rejected: ${actions.filter(a => a.decision?.action === 'reject').length}.\n\n## Decisions and source disposition\n\n`;
+            // Submission and feedback already own this path before the completion receipt exists.
+            const existingEvidence = node_fs_1.default.existsSync(this.completionFile) ? node_fs_1.default.readFileSync(this.completionFile, 'utf8') : undefined;
+            const hasReceipt = existingEvidence?.includes('fraim-sleep-decisions');
+            if (existingEvidence && !hasReceipt) {
+                const header = existingEvidence.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+                if (!header || (header[1].match(/^artifactKind:/gm) || []).length !== 1 || !/^artifactKind: work-evidence\s*$/m.test(header[1])
+                    || (header[1].match(/^containsFeedback:/gm) || []).length !== 1 || !/^containsFeedback: (true|false)\s*$/m.test(header[1]))
+                    throw new Error('completion-evidence-conflict');
+                narrative = existingEvidence + `\n\n## Sleep completion: ${this.runId}\n\n${summary}\n\n## Decisions and source disposition\n\n`;
+            }
+            let trailingHistory = '\n';
+            const writeEvidence = () => {
+                if (actions.length)
+                    narrative = narrative.replace(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/, header => header.replace(/^containsFeedback: false[ \t]*(?=\r?$)/m, 'containsFeedback: true'));
+                const encoded = JSON.stringify(result, null, 2).split('<').join(String.raw `\u003c`);
+                const body = narrative + `<!-- fraim-sleep-decisions:v1 -->\n\x60\x60\x60json\n${encoded}\n\x60\x60\x60\n<!-- /fraim-sleep-decisions -->` + trailingHistory;
+                (0, completion_state_1.decodeCompletion)(body, { runId: this.runId, owner: this.owner });
+                const previousEvidenceHash = node_fs_1.default.existsSync(this.completionFile) ? (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(this.completionFile, 'utf8')) : undefined;
+                // A replacement intent names both recoverable states. A crash before
+                // or after the atomic rename can resume without accepting a third state.
+                if (deferred)
+                    this.append('checkpoint', { evidenceHash: (0, proposal_queue_1.hashContent)(body), previousEvidenceHash, receipt: result });
+                else if (previousEvidenceHash)
+                    this.append('finalization', { evidenceHash: (0, proposal_queue_1.hashContent)(body), previousEvidenceHash });
+                (0, proposal_queue_1.atomicWrite)(this.completionFile, body);
+                const verified = node_fs_1.default.readFileSync(this.completionFile, 'utf8');
+                if ((0, proposal_queue_1.hashContent)(verified) !== (0, proposal_queue_1.hashContent)(body))
+                    throw new Error('completion-write-conflict');
+                (0, completion_state_1.decodeCompletion)(verified, { runId: this.runId, owner: this.owner });
+                if (!deferred && !previousEvidenceHash)
+                    this.append('finalization', { evidenceHash: (0, proposal_queue_1.hashContent)(body) });
+            };
+            if (node_fs_1.default.existsSync(this.completionFile) && hasReceipt) {
+                const body = node_fs_1.default.readFileSync(this.completionFile, 'utf8');
+                const prior = (0, completion_state_1.decodeCompletion)(body, { runId: this.runId, owner: this.owner });
+                if (!deferred && !prior.deferred && prior.finalizationState === 'complete' && (0, completion_state_1.canonicalJournal)(prior.retrospective) !== (0, completion_state_1.canonicalJournal)(retrospective))
+                    throw new Error('completion-retrospective-conflict');
+                if (!deferred && state.finalization && ![state.finalization.evidenceHash, state.finalization.previousEvidenceHash].includes((0, proposal_queue_1.hashContent)(body)))
+                    throw new Error('completion-evidence-conflict');
+                if (deferred || prior.deferred) {
+                    if (!state.checkpoint || ![state.checkpoint.evidenceHash, state.checkpoint.previousEvidenceHash].includes((0, proposal_queue_1.hashContent)(body))
+                        || prior.decisions.some(item => !result.decisions.some(current => (0, completion_state_1.canonicalJournal)(current) === (0, completion_state_1.canonicalJournal)(item)))
+                        || prior.processedSources?.some(item => !result.processedSources?.some(current => (0, completion_state_1.canonicalJournal)(current) === (0, completion_state_1.canonicalJournal)(item))))
+                        throw new Error('completion-decisions-conflict');
+                }
+                else if ((0, completion_state_1.canonicalJournal)(prior.decisions) !== (0, completion_state_1.canonicalJournal)(result.decisions) || (0, completion_state_1.canonicalJournal)(prior.sourceDispositions) !== (0, completion_state_1.canonicalJournal)(result.sourceDispositions) || (0, completion_state_1.canonicalJournal)(prior.reconciliations) !== (0, completion_state_1.canonicalJournal)(result.reconciliations) || (0, completion_state_1.canonicalJournal)(prior.processedSources) !== (0, completion_state_1.canonicalJournal)(result.processedSources) || (0, completion_state_1.canonicalJournal)(prior.corpusAudit) !== (0, completion_state_1.canonicalJournal)(result.corpusAudit) || (0, completion_state_1.canonicalJournal)(prior.reconciliationHistory) !== (0, completion_state_1.canonicalJournal)(result.reconciliationHistory) || (0, completion_state_1.canonicalJournal)(prior.outcomeAssessments) !== (0, completion_state_1.canonicalJournal)(result.outcomeAssessments))
+                    throw new Error('completion-decisions-conflict');
+                if (deferred && prior.finalizationState === 'complete' && (0, completion_state_1.canonicalJournal)({ ...prior, finalizationState: 'pending' }) === (0, completion_state_1.canonicalJournal)(result)) {
+                    finishSources?.();
+                    verifyApplied?.();
+                    this.append('deferred-attempt', { at: new Date().toISOString(), evidenceHash: (0, proposal_queue_1.hashContent)(body), reason: 'verified-subset-unchanged' });
+                    return prior;
+                }
+                // While pending, the agent may update process evidence and the
+                // retrospective to explain a failed completion attempt. Exact
+                // approved actions stay fixed; the replacement intent binds new bytes.
+                narrative = body.slice(0, body.indexOf('<!-- fraim-sleep-decisions:v1 -->'));
+                if (prior.deferred && (!deferred || (0, completion_state_1.canonicalJournal)({ ...prior, finalizationState: 'pending' }) !== (0, completion_state_1.canonicalJournal)(result)))
+                    narrative += `\n## Recovery completion\n\n${summary}\n\n`;
+                trailingHistory = body.slice(body.indexOf('<!-- /fraim-sleep-decisions -->') + '<!-- /fraim-sleep-decisions -->'.length);
+                if (!deferred && !prior.deferred && prior.finalizationState === 'complete' && !snapshot.some(item => item.outcome === 'pending')) {
+                    finishedInventory();
+                    finishSources?.();
+                    verifyApplied?.(true);
+                    node_fs_1.default.unlinkSync(this.file);
+                    return prior;
+                }
+                if (!deferred && !prior.deferred && prior.finalizationState === 'complete' && snapshot.some(item => item.outcome === 'pending'))
+                    throw new Error('cleanup-content-reappeared');
+                // The fresh inventory authorizes every remaining deletion. Never
+                // execute a path merely because it appeared in prior evidence.
+                for (const item of deferred ? [] : prior.cleanup) {
+                    const found = snapshot.find(current => sameCleanupIdentity(item, current));
+                    if (!found)
+                        throw new Error('cleanup-inventory-missing');
+                    if ((item.outcome === 'deleted' || item.outcome === 'absent') && found.outcome === 'pending')
+                        throw new Error('cleanup-content-reappeared');
+                    if (found.outcome === 'absent' && item.outcome === 'deleted')
+                        found.outcome = 'deleted';
+                }
+            }
+            writeEvidence();
+            afterStage?.('evidence');
+            finishSources?.();
+            afterStage?.('sources');
+            if (!deferred) {
+                for (const item of result.cleanup) {
+                    if (item.outcome !== 'pending')
+                        continue;
+                    const authorized = inspect().find(current => node_path_1.default.resolve(current.path) === node_path_1.default.resolve(item.path));
+                    if (!authorized || !['pending', 'absent'].includes(authorized.outcome) || authorized.sha256 !== item.sha256)
+                        throw new Error('cleanup-authorization-changed');
+                    if (node_fs_1.default.existsSync(item.path)) {
+                        if (!item.sha256 || (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(item.path, 'utf8')) !== item.sha256)
+                            throw new Error('cleanup-content-conflict');
+                        node_fs_1.default.unlinkSync(item.path);
+                        item.outcome = 'deleted';
+                    }
+                    else
+                        item.outcome = 'absent';
+                    writeEvidence();
+                    afterStage?.('cleanup');
+                }
+                const finalInventory = finishedInventory();
+                const completed = new Map(result.cleanup.map(item => [node_path_1.default.resolve(item.path), item]));
+                for (const item of finalInventory)
+                    if (!completed.has(node_path_1.default.resolve(item.path)))
+                        result.cleanup.push(item);
+            }
+            else
+                verifyApplied?.();
+            result.finalizationState = 'complete';
+            writeEvidence();
+            afterStage?.('complete-evidence');
+            const binding = deferred ? this.read().checkpoint : this.read().finalization;
+            if ((0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(this.completionFile, 'utf8')) !== binding?.evidenceHash)
+                throw new Error('completion-evidence-conflict');
+            // Complete attests this receipt's terminal subset. Only full coverage permits retiring run recovery.
+            if (!deferred) {
+                finishedInventory();
+                finishSources?.();
+                verifyApplied?.(true);
+                node_fs_1.default.unlinkSync(this.file);
+            }
+            return result;
+        });
+    }
+}
+exports.RunRecord = RunRecord;