fraim 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-authoring.js

@@ -0,0 +1,181 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveDomain = deriveDomain;
+exports.readerWordCount = readerWordCount;
+exports.validateEntry = validateEntry;
+exports.renderEntry = renderEntry;
+exports.isLearningScaffolding = isLearningScaffolding;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// Relative to the shipped helper, never to the job's working directory.
+const map = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(__dirname, 'learning-domains.json'), 'utf8'));
+function deriveDomain(origins) {
+    const unknown = (reason) => ({ status: 'needs-domain', value: null, reason, mapVersion: map.mapVersion });
+    if (!origins.length)
+        return unknown('No originating job recorded');
+    const decisions = [];
+    for (const origin of origins) {
+        let declaration;
+        const frontmatter = origin.content?.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---/);
+        if (frontmatter) {
+            try {
+                declaration = JSON.parse(frontmatter[1]).domain;
+            }
+            catch {
+                declaration = frontmatter[1].match(/^domain:\s*["']?([\w-]+)/m)?.[1];
+            }
+        }
+        if (declaration !== undefined) {
+            if (declaration !== 'global' && !map.domains.includes(String(declaration)))
+                return unknown(`Invalid domain declaration for ${origin.name}`);
+            decisions.push({ value: String(declaration), basis: 'job-declaration' });
+            continue;
+        }
+        const clean = origin.registryPath?.replace(/\\/g, '/').replace(/^\/?registry\//, '');
+        const category = clean?.match(/^jobs\/(?:ai-employee\/|ai-manager\/|personalized-employee\/)?([^/]+)\/[^/]+\.md$/)?.[1];
+        if (!category)
+            return unknown(`No mapped job path for ${origin.name}`);
+        const value = map.jobDomainMap[category] || (map.globalJobCategories.includes(category) ? 'global' : null);
+        if (!value)
+            return unknown(`Unmapped category for ${origin.name}`);
+        decisions.push({ value, basis: 'category' });
+    }
+    if (new Set(decisions.map(d => d.value)).size !== 1)
+        return unknown('Originating jobs span multiple domains');
+    return { status: 'resolved', ...decisions[0], mapVersion: map.mapVersion };
+}
+function readerText(entry) {
+    return [entry.title, entry.takeaway, entry.why, entry.example, entry.next].join(' ');
+}
+function readerWordCount(entry) {
+    const plain = readerText(entry).replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/[*_`~#]/g, '').trim();
+    return plain ? plain.split(/\s+/u).length : 0;
+}
+function validateEntry(entry) {
+    if (!entry || !['P-CRITICAL', 'P-HIGH', 'P-MED', 'P-LOW'].includes(entry.severity))
+        throw new Error('invalid-entry: severity');
+    for (const field of ['title', 'takeaway', 'why', 'example', 'next']) {
+        if (typeof entry[field] !== 'string' || !entry[field].trim() || /[\r\n\0]/.test(entry[field]))
+            throw new Error(`invalid-entry: ${field}`);
+    }
+    if (readerWordCount(entry) > 80)
+        throw new Error('invalid-entry: 80-word budget exceeded');
+    // Domain wording and whether an identifier is essential require semantic
+    // authoring review/evals; a vocabulary regex rejects legitimate lessons.
+    if (!entry.domain || !Number.isInteger(entry.domain.mapVersion))
+        throw new Error('invalid-entry: domain');
+    if (entry.domain.status === 'resolved') {
+        if (!['global', ...map.domains].includes(entry.domain.value) || !['category', 'job-declaration', 'manager'].includes(entry.domain.basis))
+            throw new Error('invalid-entry: domain');
+    }
+    else if (entry.domain.status !== 'needs-domain' || entry.domain.value !== null || !entry.domain.reason)
+        throw new Error('invalid-entry: domain');
+    const trace = entry.trace;
+    if (!trace || !Number.isFinite(trace.score) || !Number.isInteger(trace.recurrences) || trace.recurrences < 1 || !Array.isArray(trace.originatingJobs) || !Array.isArray(trace.sources))
+        throw new Error('invalid-entry: trace');
+    for (const date of [trace.lastSeen, trace.firstRecorded, ...(trace.firstSynthesized ? [trace.firstSynthesized] : [])]) {
+        if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date) || new Date(date).toISOString().slice(0, 10) !== date)
+            throw new Error('invalid-entry: date');
+    }
+    if (trace.firstRecorded > trace.lastSeen)
+        throw new Error('invalid-entry: source dates');
+    if (!trace.originatingJobs.every(job => typeof job.name === 'string' && job.name.length > 0 && (job.registryPath === null || typeof job.registryPath === 'string')))
+        throw new Error('invalid-entry: origins');
+    if (!trace.sources.every(source => typeof source === 'string'))
+        throw new Error('invalid-entry: sources');
+}
+function renderEntry(entryId, entry) {
+    validateEntry(entry);
+    if (!/^L-[a-f0-9]{10}$/.test(entryId))
+        throw new Error('invalid-entry: Id');
+    if (entry.domain.status !== 'resolved')
+        throw new Error('needs-domain');
+    const trace = entry.trace;
+    const line = (value) => value.replace(/[\r\n\0]+/g, ' ');
+    // Metadata stays on standalone lines for existing learning readers.
+    return [
+        `### [${entry.severity}] ${entry.title}`, '',
+        `**Takeaway**: ${entry.takeaway}`, `**Why this matters**: ${entry.why}`,
+        `**Example**: ${entry.example}`, `**What to do next**: ${entry.next}`, '**Technical trace**:',
+        `**Id**: ${entryId}`, `**Domain**: ${entry.domain.value}`,
+        `**Originating job**: ${line(trace.originatingJobs.map(job => job.registryPath || job.name).join('; '))}`,
+        `**Domain basis**: ${entry.domain.basis}; map ${entry.domain.mapVersion}`,
+        `**Score**: ${trace.score}`, `**Last seen**: ${trace.lastSeen}`,
+        `**Recurrences**: ${trace.recurrences}`, `**First recorded**: ${trace.firstRecorded}`,
+        ...(trace.firstSynthesized ? [`**First synthesized**: ${trace.firstSynthesized}`] : []),
+        `**Sources**: ${line(trace.sources.join('; '))}`,
+        // Investigation detail stays in evidence; active guidance retains only provenance metadata.
+        '',
+    ].join('\n');
+}
+/** Recognize only known generated family preambles; unknown prose remains user content. */
+function isLearningScaffolding(body, familyPath) {
+    const name = node_path_1.default.basename(familyPath);
+    const match = name.match(/-(preferences|mistake-patterns|validated-patterns|manager-coaching)(\.cold)?\.md$/);
+    if (!match)
+        return false;
+    const family = match[1];
+    const title = family.replace(/-/g, ' ');
+    const cold = !!match[2];
+    const descriptions = {
+        preferences: ['This file captures durable communication and interaction preferences observed across sessions.', 'This file captures working preferences common across multiple users. Run `organizational-learning-synthesis` to populate it.'],
+        'mistake-patterns': ['This file is an execution playbook for future agents. Keep it focused on durable behavior and decision quality.', 'This file captures recurring failure modes observed across multiple users in the org. Run `organizational-learning-synthesis` to populate it.'],
+        'validated-patterns': ['This file captures validated decisions, near-misses that were caught, and moments where past learnings successfully fired. These are behaviors to reinforce.'],
+        'manager-coaching': ['This file captures coaching and reflections about your management of AI agents - patterns you have developed (or been coached on) that make you a more effective practitioner. The audience is **you**, not the AI agent.', 'This file captures coaching patterns shared across managers in the org - guidance that managers have received or developed about how to work effectively with AI agents. The audience is the human manager, not the AI agent. Run `organizational-learning-synthesis` to populate it.'],
+    };
+    const heading = (value) => {
+        if (['# Learnings', '# Synthesized Learnings'].includes(value) || (family === 'mistake-patterns' && value === '# Prioritized Learnings'))
+            return true;
+        if (!value.startsWith('# '))
+            return false;
+        let text = value.slice(2);
+        const author = text.match(/ [\-\u2014] ([a-zA-Z0-9@._+-]+)$/);
+        if (author) {
+            if (!name.startsWith(author[1] + '-'))
+                return false;
+            text = text.slice(0, -author[0].length);
+        }
+        if (/^Cold-Tier /i.test(text)) {
+            if (!cold)
+                return false;
+            text = text.slice(10);
+        }
+        if (/^Org /i.test(text)) {
+            if (!name.startsWith('org-'))
+                return false;
+            text = text.slice(4);
+        }
+        const domain = text.match(/ \(([a-zA-Z][a-zA-Z -]*)\)$/);
+        if (domain) {
+            if (!name.toLowerCase().endsWith('-' + domain[1].toLowerCase().replace(/ /g, '-') + '-' + family + (cold ? '.cold' : '') + '.md'))
+                return false;
+            text = text.slice(0, -domain[0].length);
+        }
+        text = text.toLowerCase().replace(/-/g, ' ');
+        if (text === title)
+            return true;
+        const prefix = text.endsWith(' ' + title) ? text.slice(0, -title.length - 1).replace(/ /g, '-') : '';
+        return !!prefix && name.toLowerCase().endsWith('-' + prefix + '-' + family + (cold ? '.cold' : '') + '.md');
+    };
+    return body.split(/\r?\n/).every(line => {
+        const value = line.trim();
+        if (!value || value === '---' || heading(value) || descriptions[family].includes(value) || /^Last (?:synthesized|updated): \d{4}-\d{2}-\d{2}$/.test(value))
+            return true;
+        if (cold && (value === 'Entries whose effective score has fallen below the injection threshold. They stay readable and return to the active file the first time their problem recurs.'
+            || /^Entries below the active-tier score threshold \(\d+(?:\.\d+)?\)\. Preserved for re-activation if recurrence rises\.$/.test(value)))
+            return true;
+        const sections = {
+            'mistake-patterns': ['## Severity Definitions', '## Critical Priorities', '- Critical: recurring across 3+ users, causes customer impact or significant rework.', '- Important: recurring across 2+ users, degrades quality or velocity.', '- Monitor: emerging pattern, not yet widespread but worth tracking.', '- Critical: recurring failure mode that causes rework, trust loss, or architectural mistakes.', '- Important: meaningful quality risk that frequently degrades output.', '- Monitor: lower-frequency risk to track and prevent from growing.'],
+            'validated-patterns': ['## Severity Definitions', '## Patterns to Reinforce', '- HIGH: validated decision that prevented major rework or unblocked a high-stakes path (reusable across many future contexts).', '- MED: validated context-specific judgment call (reusable when same context recurs).', '- LOW: validated micro-correctness (useful but narrow).'],
+        };
+        if (sections[family]?.includes(value))
+            return true;
+        const domain = value.match(/^([A-Za-z][A-Za-z-]*)-domain (manager coaching|validated patterns)\. (.+)$/);
+        const detail = family === 'manager-coaching' ? 'Feedback for how the manager should continue or improve managing AI on ' + domain?.[1].toLowerCase() + ' work.' : 'Durable judgment calls and successful unusual-but-correct decisions worth reproducing.';
+        return !!domain && domain[2] === title && name.toLowerCase().endsWith('-' + domain[1].toLowerCase() + '-' + family + '.md')
+            && domain[3] === detail + ' These load only when an ' + domain[1].toLowerCase() + '-domain job runs.';
+    });
+}

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 };