fraim 2.0.346 → 2.0.349

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

@@ -0,0 +1,1003 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reserveRunAction = reserveRunAction;
+exports.applyRunAction = applyRunAction;
+exports.completeRun = completeRun;
+exports.completionInventory = completionInventory;
+exports.removeEmptyGenerated = removeEmptyGenerated;
+const node_fs_1 = __importDefault(require("node:fs"));
+const completion_state_1 = require("./completion-state");
+const node_path_1 = __importDefault(require("node:path"));
+const run_record_1 = require("./run-record");
+const owner_identity_1 = require("./owner-identity");
+const proposal_queue_1 = require("./proposal-queue");
+const entry_authoring_1 = require("./entry-authoring");
+const completion_state_2 = require("./completion-state");
+const artifact_paths_1 = require("../artifact-paths");
+const learning_source_record_1 = require("../learning-usage/learning-source-record");
+const corpus_audit_1 = require("./corpus-audit");
+const { learningEntryBlocks, learningEntryMetadata } = require('./entry-format');
+function currentEntry(file, id) {
+    const body = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : '';
+    if (/^<{7}/m.test(body))
+        throw new Error('source-conflict: merge markers');
+    if (!id)
+        return { body, entry: node_fs_1.default.existsSync(file) ? body : null };
+    const blocks = learningEntryBlocks(body);
+    if (blocks.some(b => !b.id))
+        throw new Error('source-conflict: ambiguous learning entry');
+    const matches = blocks.filter(b => b.id === id);
+    if (matches.length > 1)
+        throw new Error('source-conflict: duplicate identity');
+    return { body, entry: matches[0]?.text ?? null };
+}
+function resolved(ref, options) {
+    const home = options.resolveHome(ref.owner);
+    (0, owner_identity_1.assertSameOwner)(ref.owner, home.owner);
+    return { home, file: (0, owner_identity_1.ownerArtifactPath)(home, ref.relativePath) };
+}
+function capabilityGuards(action, proof, options) {
+    if (action.delivery?.reader)
+        (0, run_record_1.validateDeliveryReader)(action.delivery.reader);
+    const snapshots = new Map((proof.localFiles || []).map(item => [node_path_1.default.resolve(item.file), { ...item }]));
+    const required = [action.target, ...(action.delivery?.callers || [])].map(ref => resolved(ref, options).file);
+    if (required.some(file => {
+        const snapshot = snapshots.get(node_path_1.default.resolve(file));
+        return !snapshot || typeof snapshot.realPath !== 'string' || !snapshot.realPath
+            || typeof snapshot.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(snapshot.sha256);
+    }))
+        throw new Error('capability-local-proof-required');
+    if (snapshots.get(node_path_1.default.resolve(required[0]))?.sha256 !== action.delivery?.expectedHash)
+        throw new Error('capability-local-proof-conflict');
+    return [...snapshots.values()].map(item => {
+        const absent = item.realPath === null && item.sha256 === null;
+        if (!absent && (typeof item.realPath !== 'string' || typeof item.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(item.sha256)))
+            throw new Error('capability-local-proof-conflict');
+        return { file: item.file, verify: () => {
+                if (absent) {
+                    try {
+                        node_fs_1.default.lstatSync(item.file);
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT')
+                            return;
+                        throw new Error('capability-local-proof-changed');
+                    }
+                    throw new Error('capability-local-proof-changed');
+                }
+                if (!node_fs_1.default.existsSync(item.file) || node_fs_1.default.realpathSync(item.file) !== item.realPath || (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(item.file, 'utf8')) !== item.sha256)
+                    throw new Error('capability-local-proof-changed');
+            } };
+    });
+}
+function withLocalGuards(guards, operation) {
+    // Locks fail immediately with busy; they never wait on another holder. The
+    // prepared reservation freezes approval before these sorted file locks are
+    // taken. Journal appends use their own short lock; completion acquires the
+    // sorted file set before entering RunRecord.complete's journal transaction.
+    const grouped = new Map();
+    for (const guard of guards)
+        grouped.set(guard.file, [...(grouped.get(guard.file) || []), guard.verify]);
+    const files = [...grouped.keys()].sort();
+    const locked = (index) => index === files.length ? operation() : (0, proposal_queue_1.withFileLock)(files[index], () => {
+        for (const verify of grouped.get(files[index]))
+            verify();
+        return locked(index + 1);
+    });
+    return locked(0);
+}
+function verifyHistory(before, action) {
+    if (!action.content)
+        return;
+    const meta = learningEntryMetadata(before);
+    const trace = action.content.trace;
+    if ((meta['First recorded'] && meta['First recorded'] !== trace.firstRecorded)
+        || (meta['First synthesized'] && meta['First synthesized'] !== trace.firstSynthesized)
+        || Number(meta.Recurrences || 0) > trace.recurrences)
+        throw new Error('immutable-learning-history');
+}
+function prepare(action, options) {
+    const target = resolved(action.target, options);
+    const before = currentEntry(target.file, action.target.entryId).entry;
+    const after = action.operation === 'remove' ? null : (0, entry_authoring_1.renderEntry)(action.target.entryId, action.content).trimEnd();
+    const expected = action.destinationHash || (action.operation !== 'move' ? action.sourceHash : undefined);
+    if (['insert', 'move'].includes(action.operation) || (action.operation === 'reconcile' && !action.destinationHash) ? before !== null : before === null || (0, proposal_queue_1.hashContent)(before) !== expected)
+        throw new Error('source-conflict: reviewed base changed');
+    if (before && action.operation !== 'reconcile')
+        verifyHistory(before, action);
+    const steps = [{ ref: action.target, before, after }];
+    if (action.operation === 'move') {
+        const source = resolved(action.source, options);
+        const old = currentEntry(source.file, action.source.entryId).entry;
+        if (old === null || (0, proposal_queue_1.hashContent)(old) !== action.sourceHash)
+            throw new Error('source-conflict: move source changed');
+        verifyHistory(old, action);
+        steps.push({ ref: action.source, before: old, after: null });
+    }
+    if (action.operation === 'reconcile') {
+        for (const copy of action.copies) {
+            const old = currentEntry(resolved(copy.ref, options).file, copy.ref.entryId).entry;
+            if (old === null || (0, proposal_queue_1.hashContent)(old) !== copy.sha256)
+                throw new Error('source-conflict: reconciliation copy changed');
+            steps.push({ ref: copy.ref, before: old, after: null });
+        }
+        const history = steps.flatMap(step => step.before ? [learningEntryMetadata(step.before)] : []);
+        const earliest = (key) => history.map(item => item[key]).filter(Boolean).sort()[0];
+        const sources = new Set(steps.flatMap(step => step.before?.match(/^\*\*Sources\*\*:\s*([^\r\n]*)$/m)?.[1].split(';').map(value => value.trim()).filter(Boolean) || []));
+        const trace = action.content.trace;
+        if ((earliest('First recorded') && trace.firstRecorded !== earliest('First recorded')) || (earliest('First synthesized') && trace.firstSynthesized !== earliest('First synthesized'))
+            || trace.recurrences < Math.max(...history.map(item => Number(item.Recurrences || 1)))
+            || new Set(trace.sources).size !== trace.sources.length || [...sources].some(source => !trace.sources.includes(source)))
+            throw new Error('immutable-learning-history');
+    }
+    return steps;
+}
+/** The caller holds this file together with all dependency guards in canonical order. */
+function writeStepLocked(step, options) {
+    const { home, file } = resolved(step.ref, options);
+    const { body, entry } = currentEntry(file, step.ref.entryId);
+    if (entry !== step.after) {
+        if (entry !== step.before)
+            throw new Error('source-conflict: recovery observed a third state');
+        const blocks = learningEntryBlocks(body);
+        const match = blocks.find(b => b.id === step.ref.entryId);
+        const updated = match ? body.slice(0, match.start) + (step.after || '') + body.slice(match.end)
+            : body.trimEnd() + (body.trim() ? '\n\n' : '# Learnings\n\n') + (step.after || '') + '\n';
+        (0, proposal_queue_1.atomicWrite)(file, updated);
+        const actual = currentEntry(file, step.ref.entryId);
+        if (actual.entry !== step.after)
+            throw new Error('write-verification-failed');
+        const untouched = blocks.filter(b => b.id !== step.ref.entryId).map(b => b.text);
+        const nowUntouched = learningEntryBlocks(actual.body).filter(b => b.id !== step.ref.entryId).map(b => b.text);
+        if ((0, run_record_1.canonical)(untouched) !== (0, run_record_1.canonical)(nowUntouched))
+            throw new Error('sibling-preservation-failed');
+    }
+    return { home, file, fileHash: (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(file, 'utf8')) };
+}
+function actionKeys(action) { return [action.target, ...(action.source ? [action.source] : []), ...(action.copies?.map(copy => copy.ref) || [])].map(ref => action.kind === 'learning' ? 'learning:' + ref.entryId : (0, owner_identity_1.ownerKey)(ref.owner) + ':' + ref.relativePath); }
+function actionHomes(run, action, options) {
+    const homes = options.homes || [run.owner, action.target.owner, ...(action.source ? [action.source.owner] : []), ...(action.copies?.map(copy => copy.ref.owner) || [])].map(options.resolveHome);
+    return [...new Map(homes.map(home => [(0, owner_identity_1.ownerKey)(home.owner), home])).values()];
+}
+/** Repeated at preparation and before each local write, including resumed removals. */
+function assertReviewedCopies(run, action, options) {
+    if (action.kind !== 'learning')
+        return;
+    const state = run.read();
+    const homes = actionHomes(run, action, options);
+    const corpus = (0, corpus_audit_1.collectLearningCorpus)(homes, [state.reviewer, ...(state.sourceParticipants?.map(grant => grant.author) || [])], options.readerRoots?.());
+    const refs = [action.target, ...(action.operation === 'move' ? [action.source] : action.operation === 'reconcile' ? action.copies.map(copy => copy.ref) : [])];
+    const key = (file) => {
+        let ancestor = node_path_1.default.resolve(file);
+        const missing = [];
+        while (!node_fs_1.default.existsSync(ancestor)) {
+            const parent = node_path_1.default.dirname(ancestor);
+            if (parent === ancestor)
+                throw new Error('home-unavailable');
+            missing.unshift(node_path_1.default.basename(ancestor));
+            ancestor = parent;
+        }
+        const physical = node_path_1.default.join(node_fs_1.default.realpathSync(ancestor), ...missing);
+        return process.platform === 'win32' ? physical.toLowerCase() : physical;
+    };
+    const allowed = new Set(refs.map(ref => key(resolved(ref, options).file)));
+    if (allowed.size !== refs.length)
+        throw new Error('duplicate-physical-learning-target');
+    for (const error of corpus.errors) {
+        // An identifiable malformed sibling cannot hold this identity. Unreadable
+        // or linked paths are never reopened; only contained regular parse-error
+        // files may be inspected to keep independent work moving.
+        if (!['ambiguous-corpus-entry', 'corpus-merge-conflict'].includes(error.reason))
+            throw new Error('corpus-incomplete');
+        try {
+            const home = homes.find(candidate => {
+                const relative = node_path_1.default.relative(candidate.contentRoot, error.path);
+                return relative && relative !== '..' && !relative.startsWith('..' + node_path_1.default.sep) && !node_path_1.default.isAbsolute(relative);
+            });
+            if (!home)
+                throw new Error('corpus-incomplete');
+            const file = (0, owner_identity_1.ownerArtifactPath)(home, node_path_1.default.relative(home.contentRoot, error.path).replace(/\\/g, '/'));
+            const stat = node_fs_1.default.lstatSync(file);
+            if (!stat.isFile() || stat.isSymbolicLink() || allowed.has(key(file)) || node_fs_1.default.readFileSync(file, 'utf8').includes(action.target.entryId))
+                throw new Error('corpus-incomplete');
+        }
+        catch {
+            throw new Error('corpus-incomplete');
+        }
+    }
+    for (const entry of corpus.entries.filter(entry => entry.ref.entryId === action.target.entryId)) {
+        if (!allowed.has(key(resolved(entry.ref, options).file)))
+            throw new Error('unreviewed-learning-copy');
+    }
+}
+function verifyCorpusAudit(run, homes, options) {
+    const state = run.read(), audit = state.corpusAudit;
+    if (!audit) {
+        if (state.corpusAuditRequired && !options.allowDeferred)
+            throw new Error('corpus-audit-required');
+        return !state.corpusAuditRequired;
+    }
+    (0, corpus_audit_1.validateCorpusAudit)(audit, state.reviewer);
+    const current = (0, corpus_audit_1.collectLearningCorpus)(homes, [state.reviewer, ...(state.sourceParticipants?.map(grant => grant.author) || [])], options.readerRoots?.());
+    if (!current.complete && !options.allowDeferred)
+        throw new Error('corpus-incomplete');
+    if ((0, run_record_1.canonical)(current.homes) !== (0, run_record_1.canonical)(audit.snapshot.homes))
+        throw new Error('corpus-audit-homes-changed');
+    const expected = new Map(audit.snapshot.entries.map(entry => [(0, corpus_audit_1.corpusEntryKey)(entry), entry]));
+    const disposition = new Map(audit.dispositions.map(item => [(0, corpus_audit_1.corpusEntryKey)(item), item]));
+    let covered = current.complete;
+    for (const item of audit.dispositions)
+        for (const binding of item.actionBindings) {
+            const action = state.actions[binding.actionId];
+            if (!action || action.revision !== binding.revision || action.digest !== binding.digest)
+                throw new Error('corpus-audit-action-changed');
+        }
+    // Inspection alone does not resolve identity conflicts. Keep every copy tied
+    // to one exact proposal; the ordinary decision gate then preserves pending
+    // work or records an attributed rejection without changing those copies.
+    for (const duplicate of audit.snapshot.duplicates) {
+        const first = disposition.get((0, corpus_audit_1.corpusEntryKey)(duplicate.occurrences[0]));
+        const accounted = first.actionIds.some(id => {
+            const action = state.actions[id];
+            if (action.kind !== 'learning' || action.operation !== 'reconcile')
+                return false;
+            const reviewed = [
+                ...(action.destinationHash ? [{ ref: action.target, sha256: action.destinationHash }] : []),
+                ...action.copies,
+            ];
+            return reviewed.length === duplicate.occurrences.length && duplicate.occurrences.every(entry => disposition.get((0, corpus_audit_1.corpusEntryKey)(entry)).actionIds.includes(id)
+                && reviewed.some(copy => (0, corpus_audit_1.corpusEntryKey)(copy) === (0, corpus_audit_1.corpusEntryKey)(entry) && copy.sha256 === entry.sha256));
+        });
+        if (!accounted && !options.allowDeferred)
+            throw new Error('corpus-duplicate-unresolved');
+        if (!accounted)
+            covered = false;
+    }
+    for (const id of state.appliedOrder) {
+        const action = state.actions[id];
+        if (action.kind !== 'learning')
+            continue;
+        for (const step of action.application.steps) {
+            const key = (0, corpus_audit_1.corpusEntryKey)({ ref: step.ref, sha256: '' });
+            const prior = expected.get(key), inspected = disposition.get(key);
+            if (prior && disposition.has(key) && (!inspected || inspected.outcome !== 'action' || !inspected.actionIds.includes(id)))
+                throw new Error('corpus-audit-action-unreviewed');
+            if (step.after === null)
+                expected.delete(key);
+            else
+                expected.set(key, { ref: { owner: step.ref.owner, relativePath: step.ref.relativePath, entryId: step.ref.entryId }, sha256: (0, proposal_queue_1.hashContent)(step.after) });
+        }
+    }
+    const entries = [...expected.values()].sort((a, b) => (0, corpus_audit_1.corpusEntryKey)(a).localeCompare((0, corpus_audit_1.corpusEntryKey)(b)));
+    if ((0, run_record_1.canonical)(entries) !== (0, run_record_1.canonical)(current.entries)) {
+        if (!options.allowDeferred)
+            throw new Error('corpus-audit-stale');
+        covered = false;
+    }
+    return covered;
+}
+/** Reserve before any external verification/publication; the durable prepared state survives unlocked waits. */
+function reserveRunAction(run, actionId, revision, expectedSequence, options) {
+    (0, proposal_queue_1.withFileLock)(options.coordinationFile || node_path_1.default.join(run.directory, 'owner-application'), () => run.mutate(expectedSequence, state => {
+        const action = state.actions[actionId];
+        if (!action || action.revision !== revision)
+            throw new Error('stale-revision');
+        if (action.decision?.action !== 'approve' || action.decision.digest !== action.digest)
+            throw new Error('not-approved');
+        if (action.delivery?.reader)
+            (0, run_record_1.validateDeliveryReader)(action.delivery.reader);
+        if (action.dependencies.some(id => state.actions[id]?.application?.stage !== 'applied'))
+            throw new Error('dependency-unfinished');
+        for (const directory of new Set([run.directory, ...options.runDirectories])) {
+            if (!node_fs_1.default.existsSync(directory))
+                continue;
+            for (const name of node_fs_1.default.readdirSync(directory).filter(n => n.endsWith('.queue.jsonl'))) {
+                const otherFile = node_path_1.default.join(directory, name);
+                const other = (0, run_record_1.readSupportedRunRecord)(otherFile);
+                if (!other)
+                    continue;
+                for (const candidate of Object.values(other.actions)) {
+                    if (node_path_1.default.resolve(otherFile) === node_path_1.default.resolve(run.file) && candidate.actionId === actionId)
+                        continue;
+                    if (candidate.application && candidate.application.stage !== 'applied' && actionKeys(candidate).some(k => actionKeys(action).includes(k)))
+                        throw new Error('entry-reserved-by-pending-run');
+                }
+            }
+        }
+        // Capabilities must validate ownership even before the resolver starts remote work.
+        if (action.kind === 'capability') {
+            resolved(action.target, options);
+            if (!action.delivery)
+                throw new Error('capability-delivery-review-required');
+        }
+        assertReviewedCopies(run, action, options);
+        if (!action.application)
+            run.progress(actionId, { stage: 'prepared', steps: action.kind === 'learning' ? prepare(action, options) : [] });
+    }));
+    return run.read().actions[actionId];
+}
+function applyRunAction(run, actionId, revision, expectedSequence, options) {
+    reserveRunAction(run, actionId, revision, expectedSequence, options);
+    const reserved = run.read();
+    const dependencyProofs = new Map();
+    for (const dependencyId of reserved.actions[actionId].dependencies) {
+        const dependency = reserved.actions[dependencyId];
+        if (dependency.kind !== 'capability')
+            continue;
+        const delivered = options.verifyCapability?.(dependency);
+        if (!delivered?.published || !delivered.reachable || delivered.contentHash !== dependency.delivery?.expectedHash)
+            throw new Error('dependency-delivery-no-longer-verified');
+        dependencyProofs.set(dependencyId, capabilityGuards(dependency, delivered, options));
+    }
+    options.afterStage?.('prepared');
+    let action = run.read().actions[actionId];
+    if (action.application?.stage === 'applied' && action.kind === 'learning') {
+        for (const step of action.application.steps) {
+            if (currentEntry(resolved(step.ref, options).file, step.ref.entryId).entry !== step.after)
+                throw new Error('source-conflict: applied result changed');
+        }
+        return action;
+    }
+    if (action.kind === 'capability') {
+        const delivered = options.verifyCapability?.(action);
+        if (!delivered?.published || !delivered.reachable || delivered.contentHash !== action.delivery?.expectedHash)
+            throw new Error('capability-publication-or-reachability-pending');
+        withLocalGuards(capabilityGuards(action, delivered, options), () => {
+            if (action.application?.stage !== 'applied')
+                (0, proposal_queue_1.withFileLock)(run.file, () => run.progress(actionId, { stage: 'applied', steps: [], publicationRef: delivered.reference }));
+        });
+        return run.read().actions[actionId];
+    }
+    for (let index = 0; index < action.application.steps.length; index++) {
+        action = run.read().actions[actionId];
+        const step = action.application.steps[index];
+        if (index > 0 && !action.application.steps[index - 1].published)
+            throw new Error('destination-publication-pending');
+        if (step.published) {
+            if (currentEntry(resolved(step.ref, options).file, step.ref.entryId).entry !== step.after)
+                throw new Error('source-conflict: published result changed');
+            continue;
+        }
+        // Keep the confirmed destination stable while removing a move's source.
+        // Both file locks are local and no external publication occurs inside them.
+        const destination = index > 0 ? action.application.steps[0] : undefined;
+        const guards = [];
+        if (destination) {
+            const { file, home } = resolved(destination.ref, options);
+            if (home.requiresPublish) {
+                const proof = options.publish?.(file, home, `${run.runId}-${actionId}-${revision}-0`, (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(file, 'utf8')), { entryId: destination.ref.entryId, after: destination.after });
+                if (!proof?.published)
+                    throw new Error('destination-publication-pending');
+            }
+            guards.push({ file, verify: () => { if (currentEntry(file, destination.ref.entryId).entry !== destination.after)
+                    throw new Error('source-conflict: published result changed'); } });
+        }
+        if (step.after === null)
+            for (const id of action.dependencies) {
+                const dependency = run.read().actions[id];
+                if (dependency.kind !== 'capability')
+                    continue;
+                guards.push(...(dependencyProofs.get(id) || []));
+            }
+        const writeFile = resolved(step.ref, options).file;
+        if (guards.some(guard => node_path_1.default.resolve(guard.file) === node_path_1.default.resolve(writeFile)))
+            throw new Error('dependency-proof-is-removal-target');
+        const written = withLocalGuards([...guards, { file: writeFile, verify: () => undefined }], () => {
+            assertReviewedCopies(run, action, options);
+            return writeStepLocked(step, options);
+        });
+        (0, proposal_queue_1.withFileLock)(run.file, () => {
+            const latest = run.read().actions[actionId];
+            latest.application.steps[index].written = true;
+            latest.application.stage = 'written';
+            run.progress(actionId, latest.application);
+        });
+        options.afterStage?.(`written-${index}`);
+        // External work occurs without local locks. Stable operation keys prevent duplicate publication.
+        const outcome = written.home.requiresPublish
+            ? options.publish?.(written.file, written.home, `${run.runId}-${actionId}-${revision}-${index}`, written.fileHash, { entryId: step.ref.entryId, after: step.after })
+            : { published: true, reference: written.file };
+        if (!outcome)
+            throw new Error('publisher-required');
+        (0, proposal_queue_1.withFileLock)(run.file, () => (0, proposal_queue_1.withFileLock)(written.file, () => {
+            if ((0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(written.file, 'utf8')) !== written.fileHash)
+                throw new Error('source-conflict: changed during publication');
+            const latest = run.read().actions[actionId];
+            Object.assign(latest.application.steps[index], { published: outcome.published, publicationRef: outcome.reference });
+            latest.application.stage = 'published';
+            run.progress(actionId, latest.application);
+        }));
+        options.afterStage?.(`published-${index}`);
+        if (!outcome.published)
+            throw new Error('publication-pending');
+    }
+    (0, proposal_queue_1.withFileLock)(run.file, () => {
+        const latest = run.read().actions[actionId];
+        for (const step of latest.application.steps) {
+            const target = resolved(step.ref, options);
+            if (currentEntry(target.file, step.ref.entryId).entry !== step.after || !step.published)
+                throw new Error('application-verification-failed');
+        }
+        latest.application.stage = 'applied';
+        latest.application.publicationRef = latest.application.steps[0].publicationRef;
+        run.progress(actionId, latest.application);
+    });
+    return run.read().actions[actionId];
+}
+/** Finish the analyzed input batch, independently of whether its proposals were accepted. */
+function sourceCompletion(run, homes, options, afterStage) {
+    const inputs = options.analyzedSources ?? [];
+    if (!Array.isArray(inputs) || inputs.some(item => !item || !node_path_1.default.isAbsolute(item.path) || !/^[a-f0-9]{64}$/.test(item.sha256) || !['raw', 'retrospective'].includes(item.kind)))
+        throw new Error('analyzed-sources-required');
+    const normalized = inputs.map(item => ({ path: node_path_1.default.resolve(item.path), sha256: item.sha256, kind: item.kind })).sort((a, b) => a.path.localeCompare(b.path));
+    if (new Set(normalized.map(item => process.platform === 'win32' ? item.path.toLowerCase() : item.path)).size !== normalized.length)
+        throw new Error('duplicate-analyzed-source');
+    const runHome = options.resolveHome(run.owner);
+    const retrospectiveFile = (0, owner_identity_1.configuredArtifactPath)(runHome, node_path_1.default.join((0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(runHome), runHome.contentRoot).retrospectives, node_path_1.default.basename(options.retrospective.relativePath)));
+    const allowed = (source) => {
+        for (const home of homes) {
+            const configured = options.resolveHome(home.owner);
+            (0, owner_identity_1.assertSameOwner)(home.owner, configured.owner);
+            if ((0, completion_state_2.sourcePathKey)(home.contentRoot) !== (0, completion_state_2.sourcePathKey)(configured.contentRoot) || (0, completion_state_2.sourcePathKey)(home.root) !== (0, completion_state_2.sourcePathKey)(configured.root) || (0, completion_state_2.sourcePathKey)((0, owner_identity_1.ownerArtifactRoot)(home)) !== (0, completion_state_2.sourcePathKey)((0, owner_identity_1.ownerArtifactRoot)(configured)))
+                throw new Error('analyzed-source-outside-home');
+            const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(configured), configured.contentRoot);
+            const sourceDirectory = source.kind === 'raw' ? locations.raw : locations.retrospectives;
+            const archiveDirectory = source.kind === 'raw' ? locations.archiveRaw : locations.archiveRetrospectives;
+            if ((0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(source.path)) !== (0, completion_state_2.sourcePathKey)(sourceDirectory))
+                continue;
+            (0, owner_identity_1.configuredArtifactPath)(configured, source.path);
+            const destination = (0, owner_identity_1.configuredArtifactPath)(configured, node_path_1.default.join(archiveDirectory, node_path_1.default.basename(source.path)));
+            const outsideContent = [sourceDirectory, archiveDirectory].some(directory => {
+                const relative = node_path_1.default.relative(configured.contentRoot, directory);
+                return relative === '..' || relative.startsWith('..' + node_path_1.default.sep) || node_path_1.default.isAbsolute(relative);
+            });
+            return { root: (0, owner_identity_1.ownerArtifactRoot)(configured), contentRoot: configured.contentRoot, owner: configured.owner, destination,
+                layout: { contentRoot: node_path_1.default.resolve(configured.contentRoot).replace(/\\/g, '/'), sourceDirectory, archiveDirectory, ...(outsideContent ? { homeRoot: (0, owner_identity_1.ownerArtifactRoot)(configured) } : {}) } };
+        }
+        throw new Error('analyzed-source-outside-home');
+    };
+    const regular = (file, root) => {
+        for (let current = file;; current = node_path_1.default.dirname(current)) {
+            try {
+                if (node_fs_1.default.lstatSync(current).isSymbolicLink())
+                    throw new Error('analyzed-source-link');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if ((0, completion_state_2.sourcePathKey)(current) === (0, completion_state_2.sourcePathKey)(root))
+                break;
+            if (current === node_path_1.default.dirname(current))
+                throw new Error('analyzed-source-outside-home');
+        }
+    };
+    const stamp = (body, date) => {
+        const header = body.match(/^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+        if (!header || (header[1].match(/^synthesized:/gm) || []).length > 1)
+            throw new Error('retrospective-frontmatter-required');
+        const newline = body.includes('\r\n') ? '\r\n' : '\n';
+        const fields = /^synthesized:/m.test(header[1]) ? header[1].replace(/^synthesized:[^\r\n]*/m, `synthesized: ${date}`) : header[1] + newline + `synthesized: ${date}`;
+        return body.replace(header[0], () => header[0].replace(header[1], () => fields));
+    };
+    run.assertReconciliations();
+    let state = run.read();
+    if (!options.allowDeferred && Object.values(state.actions).some(action => !action.decision || (action.decision.action === 'approve' && action.application?.stage !== 'applied')))
+        throw new Error('run-unfinished');
+    const completedActions = options.allowDeferred ? (0, run_record_1.completedRunActions)(state) : Object.values(state.actions);
+    for (const action of completedActions)
+        for (const ref of action.sourceRefs) {
+            if (!node_path_1.default.isAbsolute(ref))
+                continue;
+            const isInput = homes.some(home => {
+                const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+                return [locations.raw, locations.retrospectives].some(directory => (0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(ref)) === (0, completion_state_2.sourcePathKey)(directory));
+            });
+            if (isInput && !normalized.some(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(ref) && item.sha256 === action.sourceHashes?.[ref])
+                && !(options.allowDeferred && options.deferredSources?.some(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(ref))))
+                throw new Error('analyzed-action-source-missing');
+        }
+    const directories = [...new Set([run.directory, ...options.runDirectories])];
+    const reservations = new Set(normalized.length ? (0, completion_state_2.readSourceReservations)(directories, run.file) : []);
+    for (const source of normalized) {
+        if ((0, completion_state_2.sourcePathKey)(source.path) === (0, completion_state_2.sourcePathKey)(retrospectiveFile))
+            throw new Error('new-retrospective-is-future-input');
+        const { destination, layout } = allowed(source);
+        const recorded = state.processedSources?.find(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(source.path));
+        if (recorded && ((0, completion_state_2.sourcePathKey)(recorded.destination) !== (0, completion_state_2.sourcePathKey)(destination) || (recorded.layout && Object.keys(layout).some(key => typeof recorded.layout[key] !== 'string' || (0, completion_state_2.sourcePathKey)(layout[key]) !== (0, completion_state_2.sourcePathKey)(recorded.layout[key])))))
+            throw new Error('completion-sources-conflict');
+        if (reservations.has((0, completion_state_2.sourcePathKey)(source.path)) || reservations.has((0, completion_state_2.sourcePathKey)(destination)))
+            throw new Error('source-reserved-by-pending-run');
+    }
+    const prior = state.processedSources;
+    const batch = (sources) => sources.map(source => ({ ...source, path: (0, completion_state_2.sourcePathKey)(source.path) })).sort((a, b) => a.path.localeCompare(b.path));
+    if (prior && (0, run_record_1.canonical)(batch(prior.map(({ path, sha256, kind }) => ({ path, sha256, kind })))) !== (0, run_record_1.canonical)(batch(normalized))
+        && (!options.allowDeferred || prior.some(source => !normalized.some(item => (0, completion_state_2.sourcePathKey)(source.path) === (0, completion_state_2.sourcePathKey)(item.path) && source.sha256 === item.sha256 && source.kind === item.kind))))
+        throw new Error('completion-sources-conflict');
+    const date = new Date().toISOString().slice(0, 10);
+    const validateInput = (body, source, root, contentRoot, owner, archivePath) => {
+        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, archivePath ?? source.path, root, contentRoot);
+        if (parsed.status !== 'valid' || parsed.record.kind !== source.kind
+            || !(0, completion_state_1.sourceAuthorAllowed)(state, parsed.record.author, owner)
+            || parsed.record.state !== (archivePath ? 'archived' : 'pending')
+            || (!archivePath && parsed.record.synthesized))
+            throw new Error('invalid-learning-source');
+    };
+    const plans = normalized.map(source => {
+        const recorded = prior?.find(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(source.path));
+        if (recorded)
+            return recorded;
+        const { root, destination, contentRoot, owner, layout } = allowed(source);
+        regular(source.path, root);
+        regular(destination, root);
+        const body = node_fs_1.default.readFileSync(source.path, 'utf8');
+        if ((0, proposal_queue_1.hashContent)(body) !== source.sha256)
+            throw new Error('analyzed-source-changed');
+        validateInput(body, source, root, contentRoot, owner);
+        return { ...source, destination, resultHash: (0, proposal_queue_1.hashContent)(stamp(body, date)), synthesizedAt: date, layout };
+    });
+    if ((0, run_record_1.canonical)(prior) !== (0, run_record_1.canonical)(plans)) {
+        run.prepareSourceCompletion(plans, state.sequence, options.allowDeferred);
+        state = run.read();
+    }
+    afterStage?.('source-plan');
+    if (!run.reviewer || node_path_1.default.basename(run.reviewer) !== run.reviewer || run.reviewer.includes('\\') || run.reviewer.includes(':') || /[\x00-\x1f]/.test(run.reviewer))
+        throw new Error('invalid-rejection-reviewer');
+    const rejectedFile = (0, owner_identity_1.ownerArtifactPath)(runHome, `learnings/${run.reviewer}-rejected-proposals.md`);
+    const rejections = completedActions.filter(action => action.decision?.action === 'reject').map(action => {
+        const marker = `<!-- sleep-rejection:${run.runId}:${action.actionId}:${action.revision} -->`;
+        const end = '<!-- /sleep-rejection -->';
+        const { application: _application, ...proposal } = action;
+        const archivedSources = plans.filter(source => action.sourceRefs.some(ref => node_path_1.default.isAbsolute(ref) && (0, completion_state_2.sourcePathKey)(ref) === (0, completion_state_2.sourcePathKey)(source.path))).map(source => source.destination);
+        // Issue #1857 D2: the heading names which kind of rejection this was.
+        // learning-review-presentation records "a rule or skill now owns this" as a
+        // reject, and heading it "Rejected" reports the manager's own promotion back
+        // to them as a refusal. The decision object below carries `kind` for readers;
+        // this line carries it for the manager.
+        const heading = action.decision.kind === 'superseded' ? 'Superseded' : 'Rejected';
+        const render = (priorArchives) => `${marker}\n## ${heading}: ${action.content?.title || action.claimKey}\n\nReason: ${action.decision.reason}\n${action.decision.revisitCondition ? `\nRevisit when: ${action.decision.revisitCondition}\n` : ''}\n\x60\x60\x60json\n${JSON.stringify({ ...proposal, ...(priorArchives?.length ? { archivedSources: priorArchives } : {}) }, null, 2)}\n\x60\x60\x60\n${end}\n`;
+        const archives = plans.filter(source => archivedSources.includes(source.destination)).map(source => {
+            const archiveMarker = `<!-- sleep-rejection-archive:${run.runId}:${action.actionId}:${action.revision}:${(0, proposal_queue_1.hashContent)(source.destination).slice(0, 16)} -->`;
+            return { marker: archiveMarker, block: `${archiveMarker}\n\x60\x60\x60json\n${JSON.stringify({ actionId: action.actionId, revision: action.revision, digest: action.digest, sourceRef: source.path, sourceHash: source.sha256, archivedSources: [source.destination] }, null, 2)}\n\x60\x60\x60\n<!-- /sleep-rejection-archive -->\n` };
+        });
+        return { marker, end, block: render(), render, archivedSources, archives };
+    });
+    const persistRejections = (includeArchives) => {
+        if (!rejections.length)
+            return;
+        const currentHome = options.resolveHome(run.owner);
+        (0, owner_identity_1.ownerArtifactPath)(currentHome, `learnings/${run.reviewer}-rejected-proposals.md`);
+        regular(rejectedFile, currentHome.root);
+        const previous = node_fs_1.default.existsSync(rejectedFile) ? node_fs_1.default.readFileSync(rejectedFile, 'utf8') : undefined;
+        let body = previous ?? '# Rejected proposals\n\n';
+        for (const item of rejections) {
+            const start = body.indexOf(item.marker);
+            if (start >= 0) {
+                if (body.indexOf(item.marker, start + 1) >= 0)
+                    throw new Error('rejected-proposal-conflict');
+                const end = body.indexOf(item.end, start);
+                const existing = body.slice(start, end + item.end.length + 1);
+                if (existing !== item.block) {
+                    // Older writers embedded archive metadata in the proposal. Verify
+                    // those exact historical bytes without rewriting them on recovery.
+                    let archived;
+                    try {
+                        archived = JSON.parse(existing.match(/\x60\x60\x60json\n([\s\S]*?)\n\x60\x60\x60/)[1]).archivedSources;
+                    }
+                    catch {
+                        throw new Error('rejected-proposal-conflict');
+                    }
+                    if (!Array.isArray(archived) || !archived.length || archived.some(source => !item.archivedSources.includes(source)) || existing !== item.render(archived))
+                        throw new Error('rejected-proposal-conflict');
+                }
+            }
+            else
+                body += '\n' + item.block;
+            if (includeArchives)
+                for (const archive of item.archives) {
+                    const index = body.indexOf(archive.marker);
+                    if (index < 0)
+                        body += '\n' + archive.block;
+                    else if (body.slice(index, index + archive.block.length) !== archive.block || body.indexOf(archive.marker, index + 1) >= 0)
+                        throw new Error('rejected-proposal-conflict');
+                }
+        }
+        if (body !== previous)
+            (0, proposal_queue_1.atomicWrite)(rejectedFile, body);
+    };
+    return {
+        files: plans.flatMap(source => [source.path, source.destination]).concat(rejections.length ? [rejectedFile] : []),
+        finish: () => {
+            if ((0, run_record_1.canonical)(run.read().sourceParticipants) !== (0, run_record_1.canonical)(state.sourceParticipants))
+                throw new Error('source-participants-conflict');
+            persistRejections(false);
+            for (const source of plans) {
+                const { root, destination, contentRoot, owner, layout } = allowed(source);
+                regular(source.path, root);
+                regular(destination, root);
+                if ((0, completion_state_2.sourcePathKey)(destination) !== (0, completion_state_2.sourcePathKey)(source.destination) || (source.layout && Object.keys(layout).some(key => typeof source.layout[key] !== 'string' || (0, completion_state_2.sourcePathKey)(layout[key]) !== (0, completion_state_2.sourcePathKey)(source.layout[key]))))
+                    throw new Error('completion-sources-conflict');
+                const body = node_fs_1.default.existsSync(source.path) ? node_fs_1.default.readFileSync(source.path, 'utf8') : undefined;
+                if (body !== undefined) {
+                    if ((0, proposal_queue_1.hashContent)(body) !== source.sha256)
+                        throw new Error('analyzed-source-changed');
+                    validateInput(body, source, root, contentRoot, owner);
+                }
+                if (!node_fs_1.default.existsSync(destination)) {
+                    if (body === undefined)
+                        throw new Error('analyzed-source-missing');
+                    const result = stamp(body, source.synthesizedAt);
+                    if ((0, proposal_queue_1.hashContent)(result) !== source.resultHash)
+                        throw new Error('completion-sources-conflict');
+                    node_fs_1.default.mkdirSync(node_path_1.default.dirname(destination), { recursive: true });
+                    try {
+                        node_fs_1.default.writeFileSync(destination, result, { flag: 'wx' });
+                    }
+                    catch (error) {
+                        if (error.code !== 'EEXIST')
+                            throw error;
+                    }
+                    afterStage?.('source-write');
+                }
+                regular(destination, root);
+                const archivedBody = node_fs_1.default.readFileSync(destination, 'utf8');
+                if ((0, proposal_queue_1.hashContent)(archivedBody) !== source.resultHash)
+                    throw new Error('source-archive-conflict');
+                validateInput(archivedBody, source, root, contentRoot, owner, destination);
+                afterStage?.('source-verified');
+                if (body !== undefined) {
+                    const currentRunHome = options.resolveHome(run.owner);
+                    (0, owner_identity_1.assertSameOwner)(run.owner, currentRunHome.owner);
+                    const currentRunPaths = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(currentRunHome), currentRunHome.contentRoot);
+                    if ((0, completion_state_2.sourcePathKey)((0, owner_identity_1.ownerArtifactRoot)(currentRunHome)) !== (0, completion_state_2.sourcePathKey)((0, owner_identity_1.ownerArtifactRoot)(runHome))
+                        || (0, completion_state_2.sourcePathKey)(currentRunHome.contentRoot) !== (0, completion_state_2.sourcePathKey)(runHome.contentRoot)
+                        || (0, completion_state_2.sourcePathKey)(node_path_1.default.join(currentRunPaths.evidence, 'sleep')) !== (0, completion_state_2.sourcePathKey)(run.completionDirectory)
+                        || (0, completion_state_2.sourcePathKey)(currentRunPaths.retrospectives) !== (0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(retrospectiveFile)))
+                        throw new Error('completion-artifact-paths-changed');
+                    const current = allowed(source);
+                    if ((0, completion_state_2.sourcePathKey)(current.destination) !== (0, completion_state_2.sourcePathKey)(destination))
+                        throw new Error('completion-sources-conflict');
+                    regular(source.path, root);
+                    regular(destination, root);
+                    if ((0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(destination, 'utf8')) !== source.resultHash)
+                        throw new Error('source-archive-conflict');
+                    if ((0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(source.path, 'utf8')) !== source.sha256)
+                        throw new Error('analyzed-source-changed');
+                    if ((0, run_record_1.canonical)(run.read().sourceParticipants) !== (0, run_record_1.canonical)(state.sourceParticipants))
+                        throw new Error('source-participants-conflict');
+                    node_fs_1.default.unlinkSync(source.path);
+                    afterStage?.('source-unlink');
+                }
+            }
+            persistRejections(true);
+        },
+    };
+}
+/** Verify final delivery outside locks, then keep final artifacts stable during retirement. */
+function completeRun(run, summary, homes, options, afterStage) {
+    // An interrupted assessment defers its own evidence while independent approved work can finish.
+    if (node_fs_1.default.existsSync(run.file)) {
+        const assessmentState = run.read();
+        const pending = assessmentState.pendingOutcomeAssessments ?? [];
+        if (assessmentState.checkpoint?.receipt.deferred && (assessmentState.outcomeAssessments?.length || pending.length))
+            options = { ...options, allowDeferred: true };
+        if (pending.length) {
+            const sources = [...(options.deferredSources ?? [])];
+            for (const assessment of pending)
+                for (const ref of assessment.sourceRefs) {
+                    const home = options.resolveHome(ref.owner);
+                    (0, owner_identity_1.assertSameOwner)(home.owner, ref.owner);
+                    const file = (0, owner_identity_1.configuredArtifactPath)(home, node_path_1.default.join((0, owner_identity_1.ownerArtifactRoot)(home), ref.relativePath));
+                    if (!sources.some(source => (0, completion_state_2.sourcePathKey)(source.path) === (0, completion_state_2.sourcePathKey)(file)))
+                        sources.push({ path: file, owner: ref.owner, sha256: ref.sha256, reason: 'assessment-processing-pending' });
+                }
+            options = { ...options, allowDeferred: true, deferredSources: sources };
+        }
+    }
+    let deferred;
+    let deferredCandidate;
+    if (options.allowDeferred && node_fs_1.default.existsSync(run.file)) {
+        const state = run.read(), completed = new Set((0, run_record_1.completedRunActions)(state).map(action => action.actionId));
+        const actions = Object.values(state.actions).filter(action => !completed.has(action.actionId));
+        const sources = [...(options.deferredSources ?? [])];
+        for (const source of state.checkpoint?.receipt.deferred?.sources ?? []) {
+            if (source.reason === 'assessment-processing-pending' && !state.pendingOutcomeAssessments?.some(assessment => assessment.sourceRefs.some(ref => {
+                const home = options.resolveHome(ref.owner);
+                return (0, completion_state_2.sourcePathKey)(node_path_1.default.join((0, owner_identity_1.ownerArtifactRoot)(home), ref.relativePath)) === (0, completion_state_2.sourcePathKey)(source.path);
+            })))
+                continue;
+            if (!sources.some(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(source.path))
+                && !options.analyzedSources?.some(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(source.path)))
+                sources.push(source);
+        }
+        const sourceHome = (file) => homes.find(home => {
+            const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+            return [locations.raw, locations.retrospectives].some(directory => (0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(file)) === (0, completion_state_2.sourcePathKey)(directory));
+        });
+        for (const action of actions)
+            for (const ref of action.sourceRefs) {
+                if (!node_path_1.default.isAbsolute(ref))
+                    continue;
+                const home = sourceHome(ref);
+                if (home && !sources.some(source => (0, completion_state_2.sourcePathKey)(source.path) === (0, completion_state_2.sourcePathKey)(ref)))
+                    sources.push({ path: ref, owner: home.owner, reason: 'action-processing-pending', ...(action.sourceHashes?.[ref] ? { sha256: action.sourceHashes[ref] } : {}) });
+            }
+        let reservationFailure;
+        try {
+            (0, completion_state_2.readSourceReservations)([...new Set([run.directory, ...options.runDirectories])], run.file);
+        }
+        catch (error) {
+            reservationFailure = error.message;
+        }
+        for (const source of options.analyzedSources ?? []) {
+            if (!source || !node_path_1.default.isAbsolute(source.path) || !/^[a-f0-9]{64}$/.test(source.sha256) || !['raw', 'retrospective'].includes(source.kind))
+                throw new Error('analyzed-sources-required');
+            if (state.processedSources?.some(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(source.path)) || sources.some(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(source.path)))
+                continue;
+            const home = sourceHome(source.path);
+            if (!home)
+                throw new Error('analyzed-source-outside-home');
+            let reason = reservationFailure;
+            if (!reason)
+                try {
+                    (0, owner_identity_1.configuredArtifactPath)(home, source.path);
+                    const body = node_fs_1.default.readFileSync(source.path, 'utf8');
+                    if ((0, proposal_queue_1.hashContent)(body) !== source.sha256)
+                        throw new Error('analyzed-source-changed');
+                    const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, source.path, (0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+                    if (parsed.status !== 'valid' || parsed.record.kind !== source.kind || !(0, completion_state_1.sourceAuthorAllowed)(state, parsed.record.author, home.owner) || parsed.record.state !== 'pending' || parsed.record.synthesized)
+                        throw new Error('invalid-learning-source');
+                    // References may use immutable identity, home-relative locator or
+                    // the selected absolute path. None may archive an unfinished dependency.
+                    const refs = new Set([parsed.record.usageIdentity, parsed.record.sourceId, parsed.record.usageSourceRef,
+                        node_path_1.default.relative(home.contentRoot, source.path).replace(/\\/g, '/'), node_path_1.default.relative((0, owner_identity_1.ownerArtifactRoot)(home), source.path).replace(/\\/g, '/')]);
+                    if (actions.some(action => action.sourceRefs.some(ref => refs.has(ref.replace(/\\/g, '/')) || (node_path_1.default.isAbsolute(ref) && (0, completion_state_2.sourcePathKey)(ref) === (0, completion_state_2.sourcePathKey)(source.path)))))
+                        throw new Error('action-processing-pending');
+                }
+                catch (error) {
+                    reason = error.code || error.message;
+                }
+            if (reason)
+                sources.push({ path: source.path, sha256: source.sha256, owner: home.owner, reason });
+        }
+        const candidate = { actions: actions.map(action => ({ actionId: action.actionId, revision: action.revision, digest: action.digest,
+                reason: !action.decision ? 'awaiting-review' : action.decision.action === 'approve' && action.application?.stage !== 'applied' ? 'application-pending' : 'source-or-dependency-pending' })), sources, corpusComplete: false };
+        (0, completion_state_2.validateDeferredWork)(candidate);
+        for (const source of sources) {
+            const home = sourceHome(source.path);
+            if (!home)
+                throw new Error('deferred-source-outside-home');
+            (0, owner_identity_1.assertSameOwner)(source.owner, home.owner);
+            (0, owner_identity_1.assertSameOwner)(home.owner, options.resolveHome(home.owner).owner);
+        }
+        const omitted = new Set(sources.map(source => (0, completion_state_2.sourcePathKey)(source.path)));
+        const inputs = [...(options.analyzedSources ?? [])].filter(source => !omitted.has((0, completion_state_2.sourcePathKey)(source.path)));
+        for (const source of state.processedSources ?? []) {
+            if (omitted.has((0, completion_state_2.sourcePathKey)(source.path)))
+                throw new Error('completed-source-cannot-be-deferred');
+            if (!inputs.some(input => (0, completion_state_2.sourcePathKey)(input.path) === (0, completion_state_2.sourcePathKey)(source.path)))
+                inputs.push({ path: source.path, sha256: source.sha256, kind: source.kind });
+        }
+        options = { ...options, analyzedSources: inputs, deferredSources: sources };
+        const current = (0, corpus_audit_1.collectLearningCorpus)(homes, [state.reviewer, ...(state.sourceParticipants?.map(grant => grant.author) || [])], options.readerRoots?.());
+        if (current.errors.length)
+            candidate.corpusErrors = current.errors;
+        deferredCandidate = candidate;
+        if (actions.length || sources.length || !current.complete || (state.corpusAuditRequired && !state.corpusAudit))
+            deferred = candidate;
+    }
+    const retrospective = options.retrospective;
+    const retrospectiveHome = options.resolveHome(run.owner);
+    (0, owner_identity_1.assertSameOwner)(run.owner, retrospectiveHome.owner);
+    const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), retrospectiveHome.contentRoot);
+    const retrospectiveDirectory = node_path_1.default.relative((0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), locations.retrospectives).replace(/\\/g, '/');
+    const legacyDirectory = node_path_1.default.relative(retrospectiveHome.contentRoot, locations.retrospectives).replace(/\\/g, '/');
+    const expectedPaths = [retrospectiveDirectory, legacyDirectory].filter(directory => directory.split('/').every(part => part && part !== '.' && part !== '..'))
+        .map(directory => (0, completion_state_2.cycleRetrospectivePath)(run.runId, run.reviewer, run.owner.level, directory));
+    if (!retrospective || !expectedPaths.includes(retrospective.relativePath)
+        || !/^[a-f0-9]{64}$/.test(retrospective.sha256))
+        throw new Error('completion-retrospective-required');
+    if ((0, completion_state_2.sourcePathKey)(run.completionDirectory) !== (0, completion_state_2.sourcePathKey)(node_path_1.default.join(locations.evidence, 'sleep')))
+        throw new Error('completion-evidence-path-changed');
+    const retrospectiveFile = (0, owner_identity_1.configuredArtifactPath)(retrospectiveHome, node_path_1.default.join(locations.retrospectives, node_path_1.default.basename(retrospective.relativePath)));
+    // Completed outputs may subsequently be synthesized or expire under retention.
+    if (!node_fs_1.default.existsSync(run.file))
+        return run.complete(summary, () => [], undefined, undefined, retrospective);
+    const verifyRetrospective = () => {
+        // Meaning, attribution and template fidelity are reviewed by the agent.
+        // This guard binds the actual document, including on interruption retries.
+        const currentLocations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), retrospectiveHome.contentRoot);
+        if ((0, completion_state_2.sourcePathKey)(node_path_1.default.join(currentLocations.evidence, 'sleep')) !== (0, completion_state_2.sourcePathKey)(run.completionDirectory)
+            || (0, completion_state_2.sourcePathKey)(currentLocations.retrospectives) !== (0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(retrospectiveFile)))
+            throw new Error('completion-artifact-paths-changed');
+        (0, owner_identity_1.configuredArtifactPath)(retrospectiveHome, retrospectiveFile);
+        if (!node_fs_1.default.existsSync(retrospectiveFile) || node_fs_1.default.lstatSync(retrospectiveFile).isSymbolicLink())
+            throw new Error('completion-retrospective-missing');
+        const body = node_fs_1.default.readFileSync(retrospectiveFile, 'utf8');
+        if (!body.trim() || (0, proposal_queue_1.hashContent)(body) !== retrospective.sha256)
+            throw new Error('completion-retrospective-changed');
+        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, retrospectiveFile, (0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), retrospectiveHome.contentRoot);
+        if (parsed.status !== 'valid' || parsed.record.kind !== 'retrospective' || parsed.record.author !== run.reviewer || parsed.record.runId !== run.runId || parsed.record.synthesized)
+            throw new Error('completion-retrospective-invalid');
+    };
+    verifyRetrospective();
+    if (!verifyCorpusAudit(run, homes, options) && options.allowDeferred) {
+        deferred = deferredCandidate;
+        if (!deferred.corpusErrors?.length)
+            deferred.corpusErrors = [{ path: run.file, reason: 'corpus-coverage-deferred' }];
+    }
+    // Every participant locks the same sorted configured run directories while reserving.
+    const reservationLocks = options.analyzedSources?.length
+        ? [...new Set([run.directory, ...options.runDirectories].map(directory => node_path_1.default.join(directory, 'source-completion')))].sort() : [];
+    const reserve = (index) => index < reservationLocks.length
+        ? (0, proposal_queue_1.withFileLock)(reservationLocks[index], () => reserve(index + 1)) : sourceCompletion(run, homes, options, afterStage);
+    const sources = reserve(0);
+    const state = run.read();
+    const terminal = new Map();
+    const callerGuards = [];
+    for (const id of state.appliedOrder) {
+        const action = state.actions[id];
+        const steps = action.kind === 'learning' ? action.application.steps : [undefined];
+        for (const [index, step] of steps.entries()) {
+            const ref = step?.ref || action.target;
+            const target = resolved(ref, options);
+            terminal.set(target.file + ':' + (ref.entryId || ''), { action, step, index, ...target });
+        }
+    }
+    const verifyLocal = () => {
+        if (run.read().sequence !== state.sequence)
+            throw new Error('completion-run-changed');
+        for (const item of terminal.values()) {
+            const actual = item.step ? currentEntry(item.file, item.step.ref.entryId).entry : node_fs_1.default.existsSync(item.file) ? (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(item.file, 'utf8')) : null;
+            const expected = item.step ? item.step.after : item.action.delivery?.expectedHash;
+            if (actual !== expected)
+                throw new Error('completion-artifact-changed');
+        }
+    };
+    verifyLocal();
+    const finalEvidence = node_fs_1.default.existsSync(run.completionFile) ? node_fs_1.default.readFileSync(run.completionFile, 'utf8') : undefined;
+    const committed = finalEvidence && (0, proposal_queue_1.hashContent)(finalEvidence) === state.finalization?.evidenceHash
+        && (0, run_record_1.decodeCompletion)(finalEvidence, { owner: run.owner, runId: run.runId }).finalizationState === 'complete';
+    for (const item of terminal.values()) {
+        if (!item.step) {
+            const proof = options.verifyCapability?.(item.action);
+            if (!proof?.published || !proof.reachable || proof.contentHash !== item.action.delivery?.expectedHash)
+                throw new Error('completion-publication-pending');
+            callerGuards.push(...capabilityGuards(item.action, proof, options));
+        }
+        else if (!committed && item.home.requiresPublish) {
+            const proof = options.publish?.(item.file, item.home, `${run.runId}-${item.action.actionId}-${item.action.revision}-${item.index}`, (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(item.file, 'utf8')), { entryId: item.step.ref.entryId, after: item.step.after });
+            if (!proof?.published)
+                throw new Error('completion-publication-pending');
+        }
+    }
+    const auditedFiles = state.corpusAudit?.snapshot.entries.map(entry => resolved(entry.ref, options).file) || [];
+    const files = [...new Set([...terminal.values()].map(item => item.file).concat(auditedFiles, callerGuards.map(guard => guard.file), retrospectiveFile, locations.configPath, sources.files))].sort();
+    const locked = (index) => index < files.length ? (0, proposal_queue_1.withFileLock)(files[index], () => locked(index + 1))
+        : run.complete(summary, () => completionInventory(run, homes), afterStage, finalizing => {
+            verifyRetrospective();
+            verifyCorpusAudit(run, homes, options);
+            // Finalization appends its own evidence intents; approved action data must stay fixed.
+            if ((0, run_record_1.canonical)(run.read().actions) !== (0, run_record_1.canonical)(state.actions))
+                throw new Error('completion-run-changed');
+            if ((0, run_record_1.canonical)(run.read().outcomeAssessments) !== (0, run_record_1.canonical)(state.outcomeAssessments)
+                || (0, run_record_1.canonical)(run.read().pendingOutcomeAssessments) !== (0, run_record_1.canonical)(state.pendingOutcomeAssessments))
+                throw new Error('completion-run-changed');
+            for (const guard of callerGuards)
+                guard.verify();
+            for (const item of terminal.values()) {
+                const actual = item.step ? currentEntry(item.file, item.step.ref.entryId).entry : node_fs_1.default.existsSync(item.file) ? (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(item.file, 'utf8')) : null;
+                if (actual !== (item.step ? item.step.after : item.action.delivery?.expectedHash))
+                    throw new Error('completion-artifact-changed');
+            }
+            if (finalizing && !deferred)
+                completionInventory(run, homes, true);
+        }, retrospective, sources.finish, deferred);
+    verifyLocal();
+    return locked(0);
+}
+/** Inspect every configured home. Only reviewed, hash-bound recovery files are deletion candidates. */
+function completionInventory(run, homes, removeFamilies = false) {
+    const state = node_fs_1.default.existsSync(run.file) ? run.read() : (0, run_record_1.decodeCompletion)(node_fs_1.default.readFileSync(run.completionFile, 'utf8'), { runId: run.runId, owner: run.owner });
+    for (const home of homes)
+        (0, owner_identity_1.ownerArtifactPath)(home, 'learnings');
+    const known = new Map();
+    let recordedCleanup = state.cleanup;
+    if ('finalization' in state && state.finalization && node_fs_1.default.existsSync(run.completionFile)) {
+        const evidence = node_fs_1.default.readFileSync(run.completionFile, 'utf8');
+        if (![state.finalization.evidenceHash, state.finalization.previousEvidenceHash].includes((0, proposal_queue_1.hashContent)(evidence)))
+            throw new Error('completion-evidence-conflict');
+        if (evidence.includes('fraim-sleep-decisions')) {
+            const prior = (0, run_record_1.decodeCompletion)(evidence, { runId: run.runId, owner: run.owner });
+            recordedCleanup = [...prior.cleanup, ...recordedCleanup];
+        }
+    }
+    for (const item of recordedCleanup) {
+        if (!item.location)
+            throw new Error('cleanup-owner-unresolved');
+        const home = homes.find(home => (0, owner_identity_1.ownerKey)(home.owner) === (0, owner_identity_1.ownerKey)(item.location.owner));
+        if (!home)
+            throw new Error('cleanup-owner-unresolved');
+        const file = (0, owner_identity_1.ownerArtifactPath)(home, item.location.relativePath);
+        if (node_path_1.default.resolve(item.path) !== file)
+            throw new Error('cleanup-owner-unresolved');
+        known.set(file, item);
+    }
+    const result = new Map();
+    removeEmptyGenerated(homes, false);
+    const authorize = (file) => {
+        for (const home of homes) {
+            const relative = node_path_1.default.relative(home.contentRoot, file).replace(/\\/g, '/');
+            if (relative.startsWith('../') || relative === '..' || node_path_1.default.isAbsolute(relative))
+                continue;
+            if (!run_record_1.RECOVERY_DIRECTORIES.some(directory => relative.startsWith(`learnings/${directory}/`)))
+                continue;
+            return (0, run_record_1.bindCleanupItem)({ path: file, outcome: 'pending' }, home).path;
+        }
+        throw new Error('cleanup-owner-unresolved: recorded recovery is outside configured owner homes');
+    };
+    for (const [file, item] of known) {
+        if (item.outcome === 'retained') {
+            if (['raw-source', 'unrelated'].includes(item.reason || '')) {
+                const authorized = authorize(file);
+                if (!node_fs_1.default.lstatSync(authorized).isFile() || !item.sha256 || (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(authorized, 'utf8')) !== item.sha256)
+                    throw new Error('cleanup-content-conflict');
+            }
+            continue;
+        }
+        const authorized = authorize(file);
+        try {
+            if (!node_fs_1.default.lstatSync(authorized).isFile())
+                throw new Error('cleanup-link-conflict');
+            if (!item.sha256 || (0, proposal_queue_1.hashContent)(node_fs_1.default.readFileSync(authorized, 'utf8')) !== item.sha256)
+                throw new Error('cleanup-content-conflict');
+            result.set(file, { ...item, path: authorized, outcome: 'pending' });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            result.set(file, { ...item, path: authorized, outcome: 'absent' });
+        }
+    }
+    // Future runs reconcile only recovery explicitly bound in their journal. Old
+    // review directories remain untouched and cannot block a new input batch.
+    removeEmptyGenerated(homes, removeFamilies);
+    return [...result.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+function removeEmptyGenerated(homes, removeFamilies = true) {
+    for (const home of homes) {
+        // Validate the complete ancestor chain before any scaffold mutation.
+        (0, run_record_1.bindCleanupItem)({ path: node_path_1.default.join(home.contentRoot, 'learnings/review-evidence/.cleanup-path-check'), outcome: 'retained' }, home);
+        const learnings = (0, owner_identity_1.ownerArtifactPath)(home, 'learnings');
+        if (!node_fs_1.default.existsSync(learnings))
+            continue;
+        for (const name of node_fs_1.default.readdirSync(learnings)) {
+            if (!removeFamilies)
+                break;
+            if (!/-(preferences|mistake-patterns|validated-patterns|manager-coaching)(\.cold)?\.md$/.test(name))
+                continue;
+            const file = (0, owner_identity_1.ownerArtifactPath)(home, 'learnings/' + name);
+            if (node_fs_1.default.lstatSync(file).isSymbolicLink())
+                throw new Error('cleanup-link-conflict');
+            const body = node_fs_1.default.readFileSync(file, 'utf8');
+            if (!learningEntryBlocks(body).length && (0, entry_authoring_1.isLearningScaffolding)(body, name))
+                node_fs_1.default.unlinkSync(file);
+        }
+        for (const relative of run_record_1.RECOVERY_DIRECTORIES) {
+            const clear = (dir) => {
+                if (!node_fs_1.default.existsSync(dir))
+                    return;
+                for (const item of node_fs_1.default.readdirSync(dir, { withFileTypes: true }))
+                    if (item.isDirectory() && !item.isSymbolicLink())
+                        clear(node_path_1.default.join(dir, item.name));
+                if (!node_fs_1.default.readdirSync(dir).length)
+                    node_fs_1.default.rmdirSync(dir);
+            };
+            const checked = (0, run_record_1.bindCleanupItem)({ path: node_path_1.default.join(home.contentRoot, 'learnings', relative, '.cleanup-path-check'), outcome: 'retained' }, home).path;
+            clear(node_path_1.default.dirname(checked));
+        }
+    }
+}