fraim-hub 2.0.345 → 2.0.348

package/dist/registry/scripts/learning/completion-state.js

@@ -4,10 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMPLETION_END = exports.COMPLETION_START = exports.UnsupportedRunHistoryError = exports.sourcePathKey = void 0;
+exports.validateDeferredAttempt = validateDeferredAttempt;
+exports.validateDeferredWork = validateDeferredWork;
 exports.cycleRetrospectivePath = cycleRetrospectivePath;
 exports.validateProcessedSources = validateProcessedSources;
 exports.canonicalJournal = canonicalJournal;
 exports.readRunJournal = readRunJournal;
+exports.readRunReservations = readRunReservations;
 exports.readSourceReservations = readSourceReservations;
 exports.normalizeSourceParticipants = normalizeSourceParticipants;
 exports.sourceAuthorAllowed = sourceAuthorAllowed;
@@ -16,6 +19,34 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_crypto_1 = require("node:crypto");
 const artifact_paths_1 = require("../artifact-paths");
+const corpus_audit_1 = require("./corpus-audit");
+const outcome_types_1 = require("./outcome-types");
+function validateDeferredAttempt(value) {
+    if (!keys(value, ['at', 'evidenceHash', 'deferred', 'reason']) || !text(value.at) || !Number.isFinite(Date.parse(value.at)) || !hash(value.evidenceHash))
+        throw new Error('invalid-deferred-attempt');
+    // Older journals embedded the checkpoint snapshot; keep accepting those exact records.
+    if (value.deferred !== undefined && value.reason === undefined)
+        validateDeferredWork(value.deferred);
+    else if (value.deferred !== undefined || !text(value.reason))
+        throw new Error('invalid-deferred-attempt');
+}
+function validateDeferredWork(value) {
+    if (!keys(value, ['actions', 'sources', 'corpusComplete', 'corpusErrors']) || value.corpusComplete !== false || !Array.isArray(value.actions) || !Array.isArray(value.sources))
+        throw new Error('invalid-deferred-work');
+    if (value.corpusErrors !== undefined && (!Array.isArray(value.corpusErrors) || value.corpusErrors.some(item => !keys(item, ['path', 'reason']) || !text(item.path) || !node_path_1.default.isAbsolute(item.path) || !text(item.reason))))
+        throw new Error('invalid-deferred-work');
+    const actions = new Set(), sources = new Set();
+    for (const item of value.actions) {
+        if (!keys(item, ['actionId', 'revision', 'digest', 'reason']) || !text(item.actionId) || !Number.isInteger(item.revision) || item.revision < 1 || !hash(item.digest) || !text(item.reason) || actions.has(item.actionId))
+            throw new Error('invalid-deferred-work');
+        actions.add(item.actionId);
+    }
+    for (const item of value.sources) {
+        if (!keys(item, ['path', 'owner', 'reason', 'sha256']) || !text(item.path) || !node_path_1.default.isAbsolute(item.path) || /[\x00-\x1f]/.test(item.path) || !ownerValid(item.owner) || !text(item.reason) || (item.sha256 !== undefined && !hash(item.sha256)) || sources.has((0, exports.sourcePathKey)(item.path)))
+            throw new Error('invalid-deferred-work');
+        sources.add((0, exports.sourcePathKey)(item.path));
+    }
+}
 const sourcePathKey = (file) => {
     const value = node_path_1.default.resolve(file).replace(/\\/g, '/');
     return process.platform === 'win32' ? value.toLowerCase() : value;
@@ -144,9 +175,10 @@ function readRunJournal(file) {
     }
     return { events, lastHash, format: 'current' };
 }
-/** Only exact, hash-chain-verified current archive plans reserve files. Older plans are outside this lifecycle. */
-function readSourceReservations(runDirectories, excludingRunFile) {
+/** Current archive plans and prepared assessments share one verified reservation inventory. */
+function readRunReservations(runDirectories, excludingRunFile) {
     const reserved = new Set();
+    const assessmentKeys = new Set();
     for (const directory of new Set(runDirectories.map(dir => node_path_1.default.resolve(dir)))) {
         let names;
         try {
@@ -167,6 +199,23 @@ function readSourceReservations(runDirectories, excludingRunFile) {
                 const journal = readRunJournal(file);
                 if (journal.format === 'historical')
                     continue;
+                const assessmentSources = new Map();
+                for (const event of journal.events) {
+                    if (event.payload.type === 'assessment-prepared') {
+                        const { record, sourcePaths } = event.payload.data;
+                        (0, outcome_types_1.validateOutcomeAssessmentRecord)(record);
+                        if (!Array.isArray(sourcePaths) || sourcePaths.length !== record.sourceRefs.length || sourcePaths.some(file => typeof file !== 'string' || !node_path_1.default.isAbsolute(file)))
+                            throw new Error('invalid-assessment-sources');
+                        assessmentSources.set(record.digest, { paths: sourcePaths, key: (0, outcome_types_1.assessmentKey)(record) });
+                    }
+                    else if (event.payload.type === 'assessment-committed')
+                        assessmentSources.delete(event.payload.data.digest);
+                }
+                for (const reservation of assessmentSources.values()) {
+                    assessmentKeys.add(reservation.key);
+                    for (const source of reservation.paths)
+                        reserved.add((0, exports.sourcePathKey)(source));
+                }
                 for (const event of journal.events)
                     if (event.payload.type === 'source-completion') {
                         for (const source of event.payload.data) {
@@ -182,7 +231,10 @@ function readSourceReservations(runDirectories, excludingRunFile) {
             }
         }
     }
-    return [...reserved].sort();
+    return { sources: [...reserved].sort(), assessmentKeys: [...assessmentKeys].sort() };
+}
+function readSourceReservations(runDirectories, excludingRunFile) {
+    return readRunReservations(runDirectories, excludingRunFile).sources;
 }
 exports.COMPLETION_START = '<!-- fraim-sleep-decisions:v1 -->';
 exports.COMPLETION_END = '<!-- /fraim-sleep-decisions -->';
@@ -233,7 +285,7 @@ function decodeCompletion(markdown, expected = {}) {
     catch {
         fail();
     }
-    if (!keys(state, ['schemaVersion', 'runId', 'owner', 'finalizationState', 'decisions', 'sourceDispositions', 'cleanup', 'reconciliations', 'retrospective', 'processedSources', 'sourceParticipants']) || state.schemaVersion !== 1 || !text(state.runId) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(state.runId) || !ownerValid(state.owner)
+    if (!keys(state, ['schemaVersion', 'runId', 'owner', 'finalizationState', 'decisions', 'sourceDispositions', 'cleanup', 'reconciliations', 'retrospective', 'processedSources', 'sourceParticipants', 'corpusAudit', 'reconciliationHistory', 'deferred', 'deferredHistory', 'deferredAttempts', 'outcomeAssessments']) || state.schemaVersion !== 1 || !text(state.runId) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(state.runId) || !ownerValid(state.owner)
         || !['pending', 'complete'].includes(state.finalizationState) || !Array.isArray(state.decisions) || !Array.isArray(state.sourceDispositions) || !Array.isArray(state.cleanup))
         fail();
     if ((expected.runId && expected.runId !== state.runId) || (expected.owner && !sameOwner(expected.owner, state.owner)))
@@ -248,8 +300,31 @@ function decodeCompletion(markdown, expected = {}) {
         fail();
     if (state.processedSources !== undefined)
         validateProcessedSources(state.processedSources);
+    if (state.outcomeAssessments !== undefined) {
+        if (!Array.isArray(state.outcomeAssessments))
+            fail();
+        const digests = new Set();
+        for (const assessment of state.outcomeAssessments) {
+            (0, outcome_types_1.validateOutcomeAssessmentRecord)(assessment);
+            if (assessment.runId !== state.runId || digests.has(assessment.digest))
+                fail();
+            digests.add(assessment.digest);
+        }
+    }
     if (state.sourceParticipants !== undefined)
         normalizeSourceParticipants(state.sourceParticipants, state.owner);
+    if (state.deferred !== undefined)
+        validateDeferredWork(state.deferred);
+    if (state.deferredHistory !== undefined) {
+        if (!Array.isArray(state.deferredHistory))
+            fail();
+        state.deferredHistory.forEach(validateDeferredWork);
+    }
+    if (state.deferredAttempts !== undefined) {
+        if (!Array.isArray(state.deferredAttempts))
+            fail();
+        state.deferredAttempts.forEach(validateDeferredAttempt);
+    }
     const ids = new Set();
     for (const item of state.decisions) {
         if (!keys(item, ['actionId', 'revision', 'digest', 'owner', 'claimKey', 'evidenceFingerprint', 'sourceRefs', 'decision', 'publicationRef', 'target', 'dependencies']) || !text(item.actionId) || ids.has(item.actionId) || !Number.isInteger(item.revision) || item.revision < 1 || !hash(item.digest) || !ownerValid(item.owner)
@@ -281,6 +356,50 @@ function decodeCompletion(markdown, expected = {}) {
             fail();
     }
     const decisions = new Map(state.decisions.map((item) => [item.actionId, item]));
+    if (state.deferred?.actions.some((item) => decisions.has(item.actionId)))
+        fail();
+    if (state.corpusAudit !== undefined) {
+        try {
+            (0, corpus_audit_1.validateCorpusAudit)(state.corpusAudit);
+        }
+        catch {
+            fail();
+        }
+        for (const item of state.corpusAudit.dispositions)
+            for (const binding of item.actionBindings) {
+                const decision = decisions.get(binding.actionId);
+                if (!decision || decision.digest !== binding.digest || decision.revision !== binding.revision || decision.decision.reviewer !== state.corpusAudit.reviewer)
+                    fail();
+            }
+    }
+    if (state.reconciliationHistory !== undefined) {
+        if (!Array.isArray(state.reconciliationHistory))
+            fail();
+        const seen = new Set();
+        const validRef = (ref) => keys(ref, ['owner', 'relativePath', 'entryId', 'learningSubject']) && ownerValid(ref.owner)
+            && typeof ref.relativePath === 'string' && ref.relativePath.startsWith('learnings/') && !ref.relativePath.includes('\\') && !ref.relativePath.includes(':')
+            && !ref.relativePath.split('/').some((part) => !part || part === '.' || part === '..') && /^L-[a-f0-9]{10}$/.test(ref.entryId)
+            && (ref.learningSubject === undefined || text(ref.learningSubject));
+        for (const history of state.reconciliationHistory) {
+            const decision = decisions.get(history.actionId);
+            if (!keys(history, ['actionId', 'revision', 'digest', 'target', 'resultHash', 'occurrences']) || !decision || seen.has(history.actionId)
+                || decision.decision.action !== 'approve' || history.revision !== decision.revision || history.digest !== decision.digest
+                || !validRef(history.target) || canonicalJournal(history.target) !== canonicalJournal(decision.target) || !hash(history.resultHash)
+                || !Array.isArray(history.occurrences) || !history.occurrences.length)
+                fail();
+            seen.add(history.actionId);
+            const locations = new Set();
+            for (const occurrence of history.occurrences) {
+                if (!keys(occurrence, ['ref', 'sha256', 'before']) || !validRef(occurrence.ref) || occurrence.ref.entryId !== history.target.entryId
+                    || !text(occurrence.before) || !hash(occurrence.sha256) || (0, node_crypto_1.createHash)('sha256').update(occurrence.before).digest('hex') !== occurrence.sha256)
+                    fail();
+                const location = canonicalJournal([occurrence.ref.owner, occurrence.ref.relativePath]);
+                if (locations.has(location))
+                    fail();
+                locations.add(location);
+            }
+        }
+    }
     const outcome = (item) => item.decision.action === 'approve' ? 'applied' : 'rejected';
     const dispositions = new Set();
     for (const source of state.sourceDispositions) {

package/dist/registry/scripts/learning/corpus-audit.js

@@ -0,0 +1,205 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.corpusEntryKey = corpusEntryKey;
+exports.collectLearningCorpus = collectLearningCorpus;
+exports.validateCorpusAudit = validateCorpusAudit;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const owner_identity_1 = require("./owner-identity");
+const { learningEntryBlocks, learningEntryIdentity, isLearningEntryId } = require('./entry-format');
+const stable = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+    ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
+const hash = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
+const keys = (value, allowed) => !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(key => allowed.includes(key));
+function corpusEntryKey(entry) {
+    return (0, owner_identity_1.ownerKey)(entry.ref.owner) + ':' + entry.ref.relativePath + ':' + (entry.ref.entryId ?? `unassigned:${entry.occurrence}`);
+}
+function corpusFingerprint(homes, entries) { return hash(stable({ homes, entries })); }
+/** Only persisted identity and bytes are mechanical; audience and semantic conflicts require review. */
+function collectLearningCorpus(homes, subjects, readerRoots = []) {
+    const entries = [], errors = [], seen = new Set();
+    const identities = [...new Map(homes.map(home => [(0, owner_identity_1.ownerKey)(home.owner), home.owner])).values()].sort((a, b) => (0, owner_identity_1.ownerKey)(a).localeCompare((0, owner_identity_1.ownerKey)(b)));
+    const escaped = [...new Set([...subjects, 'org'])].map(subject => subject.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const family = new RegExp(`^(?:${escaped.join('|')})-(?:[a-z][a-z-]*-)?(?:preferences|mistake-patterns|validated-patterns|manager-coaching)(\\.cold)?\\.md$`);
+    const excluded = new Set(['raw', 'retrospectives', 'archive', 'review-queue', 'review-archive', 'review-evidence']);
+    for (const home of [...homes].sort((a, b) => (0, owner_identity_1.ownerKey)(a.owner).localeCompare((0, owner_identity_1.ownerKey)(b.owner)))) {
+        const walk = (directory) => {
+            try {
+                if (node_fs_1.default.lstatSync(directory).isSymbolicLink())
+                    throw new Error('symlink-corpus-not-followed');
+                for (const item of node_fs_1.default.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                    const file = node_path_1.default.join(directory, item.name);
+                    if (item.isSymbolicLink()) {
+                        if (!excluded.has(item.name))
+                            errors.push({ path: file.replace(/\\/g, '/'), reason: 'symlink-corpus-not-followed' });
+                        continue;
+                    }
+                    if (item.isDirectory()) {
+                        if (!excluded.has(item.name))
+                            walk(file);
+                        continue;
+                    }
+                    if (!family.test(item.name))
+                        continue;
+                    try {
+                        if (item.isSymbolicLink())
+                            throw new Error('symlink-corpus-not-followed');
+                        const real = node_fs_1.default.realpathSync(file);
+                        const key = process.platform === 'win32' ? real.toLowerCase() : real;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        const relativePath = node_path_1.default.relative(home.contentRoot, file).replace(/\\/g, '/');
+                        (0, owner_identity_1.ownerArtifactPath)(home, relativePath);
+                        const body = node_fs_1.default.readFileSync(file, 'utf8');
+                        if (/^<{7}/m.test(body))
+                            throw new Error('corpus-merge-conflict');
+                        const blocks = learningEntryBlocks(body), ids = new Set();
+                        let unassigned = 0;
+                        for (const block of blocks) {
+                            // Match the runtime reader's handwritten identity contract.
+                            // Approved mutations still use the author's narrower generated-ID schema.
+                            const { id, ambiguous } = learningEntryIdentity(block.text);
+                            if (ambiguous || (id && ids.has(id))
+                                || !/^#{2,6}\s+\[P-(CRITICAL|HIGH|MED|LOW)\]\s+\S/.test(block.text)) {
+                                errors.push({ path: file.replace(/\\/g, '/'), reason: 'ambiguous-corpus-entry' });
+                                continue;
+                            }
+                            if (id)
+                                ids.add(id);
+                            entries.push({ ref: { owner: home.owner, relativePath, ...(id ? { entryId: id } : {}) }, sha256: hash(block.text),
+                                ...(!id ? { occurrence: unassigned++ } : {}) });
+                        }
+                    }
+                    catch (error) {
+                        errors.push({ path: file.replace(/\\/g, '/'), reason: error.code || error.message });
+                    }
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    errors.push({ path: directory.replace(/\\/g, '/'), reason: error.code || error.message });
+            }
+        };
+        try {
+            walk((0, owner_identity_1.ownerArtifactPath)(home, 'learnings'));
+        }
+        catch (error) {
+            errors.push({ path: home.contentRoot, reason: error.message });
+        }
+    }
+    // Legacy reader locations are explicitly discoverable but cannot acquire a
+    // writable OwnerRef just by being present. Report every unowned family file.
+    const inspectReaderRoot = (directory) => {
+        try {
+            if (node_fs_1.default.lstatSync(directory).isSymbolicLink())
+                throw new Error('symlink-corpus-not-followed');
+            for (const item of node_fs_1.default.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                const file = node_path_1.default.join(directory, item.name);
+                if (excluded.has(item.name))
+                    continue;
+                if (item.isSymbolicLink()) {
+                    errors.push({ path: file.replace(/\\/g, '/'), reason: 'symlink-corpus-not-followed' });
+                    continue;
+                }
+                if (item.isDirectory()) {
+                    inspectReaderRoot(file);
+                    continue;
+                }
+                if (!family.test(item.name))
+                    continue;
+                try {
+                    const real = node_fs_1.default.realpathSync(file), key = process.platform === 'win32' ? real.toLowerCase() : real;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    errors.push({ path: file.replace(/\\/g, '/'), reason: 'reader-live-home-unowned' });
+                }
+                catch (error) {
+                    errors.push({ path: file.replace(/\\/g, '/'), reason: error.code || error.message });
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                errors.push({ path: directory.replace(/\\/g, '/'), reason: error.code || error.message });
+        }
+    };
+    for (const directory of [...new Set(readerRoots)].sort()) {
+        // An explicit configured alias of an owned learning root is already scanned.
+        try {
+            const key = (file) => { const real = node_fs_1.default.realpathSync(file); return process.platform === 'win32' ? real.toLowerCase() : real; };
+            const real = key(directory);
+            if (homes.some(home => { try {
+                return key(node_path_1.default.join(home.contentRoot, 'learnings')) === real;
+            }
+            catch {
+                return false;
+            } }))
+                continue;
+        }
+        catch { /* Missing/unreadable roots are handled by the scanner below. */ }
+        inspectReaderRoot(directory);
+    }
+    entries.sort((a, b) => corpusEntryKey(a).localeCompare(corpusEntryKey(b)));
+    const groups = new Map();
+    for (const entry of entries)
+        if (entry.ref.entryId)
+            groups.set(entry.ref.entryId, [...(groups.get(entry.ref.entryId) || []), entry]);
+    const duplicates = [...groups].filter(([, occurrences]) => occurrences.length > 1).map(([entryId, occurrences]) => ({ entryId, occurrences })).sort((a, b) => a.entryId.localeCompare(b.entryId));
+    return { schemaVersion: 1, homes: identities, entries, duplicates, fingerprint: corpusFingerprint(identities, entries), complete: !errors.length, errors };
+}
+/** Shared by journal replay and the strict compact receipt decoder. No filesystem access. */
+function validateCorpusAudit(audit, reviewer) {
+    const fail = () => { throw new Error('invalid-corpus-audit'); };
+    if (!keys(audit, ['snapshot', 'reviewer', 'dispositions', 'partial']) || typeof audit.reviewer !== 'string' || !audit.reviewer.trim() || (reviewer && audit.reviewer !== reviewer) || (audit.partial !== undefined && audit.partial !== true)
+        || !keys(audit.snapshot, ['schemaVersion', 'homes', 'entries', 'duplicates', 'fingerprint', 'complete', 'errors']) || audit.snapshot.schemaVersion !== 1 || typeof audit.snapshot.complete !== 'boolean' || (!audit.partial && !audit.snapshot.complete) || !Array.isArray(audit.snapshot.errors) || (!audit.partial && audit.snapshot.errors.length)
+        || audit.snapshot.errors.some(item => !keys(item, ['path', 'reason']) || typeof item.path !== 'string' || !node_path_1.default.isAbsolute(item.path) || typeof item.reason !== 'string' || !item.reason.trim())
+        || !Array.isArray(audit.snapshot.homes) || !Array.isArray(audit.snapshot.entries) || !Array.isArray(audit.dispositions))
+        fail();
+    const snapshot = audit.snapshot;
+    for (const owner of snapshot.homes)
+        (0, owner_identity_1.validateOwner)(owner);
+    if (new Set(snapshot.homes.map(owner_identity_1.ownerKey)).size !== snapshot.homes.length || snapshot.fingerprint !== corpusFingerprint(snapshot.homes, snapshot.entries))
+        fail();
+    const entries = new Map();
+    for (const entry of snapshot.entries) {
+        if (!keys(entry, ['ref', 'sha256', 'occurrence']) || !keys(entry.ref, ['owner', 'relativePath', 'entryId']))
+            fail();
+        (0, owner_identity_1.validateOwner)(entry.ref?.owner);
+        if (!snapshot.homes.some(owner => (0, owner_identity_1.ownerKey)(owner) === (0, owner_identity_1.ownerKey)(entry.ref.owner))
+            || (entry.ref.entryId === undefined ? !Number.isSafeInteger(entry.occurrence) || entry.occurrence < 0 : !isLearningEntryId(entry.ref.entryId) || entry.occurrence !== undefined)
+            || !/^learnings\//.test(entry.ref.relativePath) || /[\\:]/.test(entry.ref.relativePath) || entry.ref.relativePath.split('/').some(part => !part || part === '.' || part === '..')
+            || !/^[a-f0-9]{64}$/.test(entry.sha256) || entries.has(corpusEntryKey(entry)))
+            fail();
+        entries.set(corpusEntryKey(entry), entry);
+    }
+    const groups = new Map();
+    for (const entry of snapshot.entries)
+        if (entry.ref.entryId)
+            groups.set(entry.ref.entryId, [...(groups.get(entry.ref.entryId) || []), entry]);
+    const duplicates = [...groups].filter(([, occurrences]) => occurrences.length > 1).map(([entryId, occurrences]) => ({ entryId, occurrences })).sort((a, b) => a.entryId.localeCompare(b.entryId));
+    if (stable(snapshot.duplicates) !== stable(duplicates))
+        fail();
+    if (audit.dispositions.length !== entries.size)
+        fail();
+    const seen = new Set();
+    for (const item of audit.dispositions) {
+        if (!keys(item, ['ref', 'sha256', 'occurrence', 'outcome', 'rationale', 'actionIds', 'actionBindings']) || !keys(item.ref, ['owner', 'relativePath', 'entryId']))
+            fail();
+        const key = corpusEntryKey(item);
+        if (seen.has(key) || entries.get(key)?.sha256 !== item.sha256 || entries.get(key)?.occurrence !== item.occurrence || !['retained', 'action'].includes(item.outcome)
+            || typeof item.rationale !== 'string' || !item.rationale.trim() || !Array.isArray(item.actionIds) || new Set(item.actionIds).size !== item.actionIds.length
+            || (item.outcome === 'retained' ? item.actionIds.length !== 0 : item.actionIds.length === 0)
+            || !Array.isArray(item.actionBindings) || item.actionBindings.length !== item.actionIds.length)
+            fail();
+        for (const [index, binding] of item.actionBindings.entries())
+            if (!keys(binding, ['actionId', 'revision', 'digest']) || binding.actionId !== item.actionIds[index] || !Number.isInteger(binding.revision) || binding.revision < 1 || !/^[a-f0-9]{64}$/.test(binding.digest))
+                fail();
+        seen.add(key);
+    }
+}

package/dist/registry/scripts/learning/entry-format.js

@@ -1,5 +1,14 @@
 'use strict';
 
+const LEARNING_ENTRY_ID_LINE = /^\*\*Id\*\*:\s*(L-[0-9A-Za-z]{6,24})\s*$/;
+function isLearningEntryId(value) { return typeof value === 'string' && /^L-[0-9A-Za-z]{6,24}$/.test(value); }
+/** Reader/corpus identity accepts stable handwritten IDs; approved mutation IDs remain narrower below. */
+function learningEntryIdentity(content) {
+    const declarations = content.split(/\r?\n/).map(line => line.trim()).filter(line => /^\*\*Id\*\*:/i.test(line));
+    const id = declarations[0]?.match(LEARNING_ENTRY_ID_LINE)?.[1] ?? null;
+    return { id: declarations.length === 1 ? id : null, ambiguous: declarations.length > 0 && (!id || declarations.length !== 1) };
+}
+
 // Read the shared author's current entry format for identity and update guards.
 function learningEntryBlocks(body) {
     const headings = [...body.matchAll(/^#{2,6}\s+\[P-[A-Z]+\].*$/gm)];
@@ -24,4 +33,4 @@ function learningEntryMetadata(content) {
     return metadata;
 }
 
-module.exports = { learningEntryMetadata, learningEntryBlocks };
+module.exports = { learningEntryMetadata, learningEntryBlocks, learningEntryIdentity, isLearningEntryId, LEARNING_ENTRY_ID_LINE };

package/dist/registry/scripts/learning/outcome-types.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesOutcomeScope = matchesOutcomeScope;
+exports.assessmentKey = assessmentKey;
+exports.assessmentContent = assessmentContent;
+exports.outcomeAssessmentDigest = outcomeAssessmentDigest;
+exports.validateOutcomeAssessmentInput = validateOutcomeAssessmentInput;
+exports.validateOutcomeAssessmentRecord = validateOutcomeAssessmentRecord;
+exports.summarizeLearningOutcomes = summarizeLearningOutcomes;
+const node_crypto_1 = require("node:crypto");
+const owner_identity_1 = require("./owner-identity");
+const { isLearningEntryId } = require('./entry-format');
+function matchesOutcomeScope(record, scope) {
+    return (scope.key === undefined || assessmentKey(record) === scope.key)
+        && (scope.principal === undefined || record.learning.learningSubject === scope.principal)
+        && (scope.owners === undefined || scope.owners.some(owner => (0, owner_identity_1.ownerKey)(owner) === (0, owner_identity_1.ownerKey)(record.learning.owner)));
+}
+const canonical = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+    ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
+const text = (value) => typeof value === 'string' && !!value.trim() && !/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(value);
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const relative = (value) => text(value) && !/[\\:\x00-\x1f]/.test(value) && value.split('/').every(part => !!part && part !== '.' && part !== '..');
+const date = (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z)?$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value.slice(0, 10);
+/** Semantic identity comes from Sleep; paths are provenance, never a title or move-sensitive join. */
+function assessmentKey(input) {
+    return canonical([(0, owner_identity_1.ownerKey)(input.learning.owner), input.learning.learningSubject, input.learning.entryId, input.incidentId]);
+}
+function assessmentContent(input) {
+    return canonical({ learning: input.learning, incidentId: input.incidentId, observedAt: input.observedAt, outcome: input.outcome,
+        reportedHelp: input.reportedHelp, explicitlySkipped: input.explicitlySkipped,
+        sourceRefs: [...input.sourceRefs].sort((a, b) => canonical(a).localeCompare(canonical(b))), rationale: input.rationale,
+        guidanceExistedAt: input.guidanceExistedAt });
+}
+function outcomeAssessmentDigest(record) {
+    return (0, node_crypto_1.createHash)('sha256').update(canonical({ content: assessmentContent(record), revision: record.revision,
+        expectedPriorDigest: record.expectedPriorDigest, reviewer: record.reviewer })).digest('hex');
+}
+function validateOutcomeAssessmentInput(input) {
+    if (!input || !input.learning)
+        throw new Error('invalid-outcome-assessment');
+    (0, owner_identity_1.validateOwner)(input.learning.owner);
+    if (!relative(input.learning.relativePath) || !isLearningEntryId(input.learning.entryId)
+        || !text(input.learning.learningSubject) || !text(input.incidentId) || input.incidentId.length > 512
+        || !date(input.observedAt) || !date(input.guidanceExistedAt)
+        || !['success', 'miss', 'unknown'].includes(input.outcome) || typeof input.reportedHelp !== 'boolean'
+        || typeof input.explicitlySkipped !== 'boolean' || !text(input.rationale)
+        || (input.expectedPriorDigest !== null && !hash(input.expectedPriorDigest))
+        || !Array.isArray(input.sourceRefs) || !input.sourceRefs.length)
+        throw new Error('invalid-outcome-assessment');
+    if (input.reportedHelp && input.outcome !== 'success' || input.explicitlySkipped && input.outcome !== 'miss')
+        throw new Error('invalid-outcome-qualification');
+    if (Date.parse(input.guidanceExistedAt) > Date.parse(input.observedAt))
+        throw new Error('guidance-after-incident');
+    for (const source of input.sourceRefs) {
+        if (!source)
+            throw new Error('invalid-assessment-source');
+        (0, owner_identity_1.validateOwner)(source.owner);
+        if (!relative(source.relativePath) || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(source.sourceId)
+            || !hash(source.sha256))
+            throw new Error('invalid-assessment-source');
+    }
+    if (new Set(input.sourceRefs.map(source => canonical([(0, owner_identity_1.ownerKey)(source.owner), source.sourceId]))).size !== input.sourceRefs.length)
+        throw new Error('duplicate-assessment-source');
+}
+function validateOutcomeAssessmentRecord(record) {
+    validateOutcomeAssessmentInput(record);
+    if (!Number.isInteger(record.revision) || record.revision < 1 || !date(record.assessedAt)
+        || !text(record.reviewer) || !text(record.runId) || record.digest !== outcomeAssessmentDigest(record))
+        throw new Error('invalid-outcome-record');
+}
+function summarizeLearningOutcomes(records, learning) {
+    const selected = new Map();
+    for (const record of records) {
+        if ((0, owner_identity_1.ownerKey)(record.learning.owner) !== (0, owner_identity_1.ownerKey)(learning.owner) || record.learning.entryId !== learning.entryId
+            || record.learning.learningSubject !== learning.learningSubject)
+            continue;
+        validateOutcomeAssessmentRecord(record);
+        const key = assessmentKey(record), prior = selected.get(key);
+        if (!prior || record.revision > prior.revision)
+            selected.set(key, record);
+        else if (record.revision === prior.revision && record.digest !== prior.digest)
+            throw new Error('assessment-history-conflict');
+    }
+    if (!selected.size)
+        return undefined;
+    const current = [...selected.values()], observed = current.map(record => record.observedAt).sort();
+    return { success: current.filter(record => record.outcome === 'success').length,
+        reportedHelp: current.filter(record => record.outcome === 'success' && record.reportedHelp).length,
+        miss: current.filter(record => record.outcome === 'miss').length, unknown: current.filter(record => record.outcome === 'unknown').length,
+        firstObservedAt: observed[0], lastObservedAt: observed[observed.length - 1], assessedAt: current.map(record => record.assessedAt).sort().at(-1) };
+}