fraim 2.0.345 → 2.0.346

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

@@ -16,6 +16,7 @@ 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 sourcePathKey = (file) => {
     const value = node_path_1.default.resolve(file).replace(/\\/g, '/');
     return process.platform === 'win32' ? value.toLowerCase() : value;
@@ -233,7 +234,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']) || 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)))
@@ -281,6 +282,48 @@ function decodeCompletion(markdown, expected = {}) {
             fail();
     }
     const decisions = new Map(state.decisions.map((item) => [item.actionId, item]));
+    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 } = 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 declarations = block.text.split(/\r?\n/).map(line => line.trim()).filter(line => /^\*\*Id\*\*:/i.test(line));
+                            const id = declarations[0]?.match(/^\*\*Id\*\*:\s*(L-[0-9A-Za-z]{6,24})\s*$/)?.[1] ?? null;
+                            if ((declarations.length && (!id || declarations.length !== 1)) || (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']) || typeof audit.reviewer !== 'string' || !audit.reviewer.trim() || (reviewer && audit.reviewer !== reviewer)
+        || !keys(audit.snapshot, ['schemaVersion', 'homes', 'entries', 'duplicates', 'fingerprint', 'complete', 'errors']) || audit.snapshot.schemaVersion !== 1 || audit.snapshot.complete !== true || !Array.isArray(audit.snapshot.errors) || audit.snapshot.errors.length
+        || !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 : !/^L-[0-9A-Za-z]{6,24}$/.test(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/owner-identity.js

@@ -0,0 +1,137 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ownerArtifactRoot = void 0;
+exports.ownerPath = ownerPath;
+exports.validateOwner = validateOwner;
+exports.ownerKey = ownerKey;
+exports.assertSameOwner = assertSameOwner;
+exports.resolveOwnerHome = resolveOwnerHome;
+exports.ownerArtifactPath = ownerArtifactPath;
+exports.configuredArtifactPath = configuredArtifactPath;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** A recorded home path is immutable; moving storage requires a newly reviewed run. */
+function ownerPath(root) {
+    const absolute = node_path_1.default.resolve(root).replace(/\\/g, '/');
+    return process.platform === 'win32' ? absolute.toLowerCase() : absolute;
+}
+function validateOwner(owner) {
+    if (!owner || !['Project', 'Manager', 'Org'].includes(owner.level)
+        || Object.keys(owner).some(key => !['level', 'path'].includes(key))
+        || typeof owner.path !== 'string' || !node_path_1.default.isAbsolute(owner.path)
+        || /[\x00-\x1f]/.test(owner.path) || owner.path !== ownerPath(owner.path)) {
+        throw new Error('owner-unresolved: a canonical absolute home path is required');
+    }
+}
+function ownerKey(owner) {
+    validateOwner(owner);
+    return JSON.stringify([owner.level, owner.path]);
+}
+function assertSameOwner(expected, actual) {
+    if (ownerKey(expected) !== ownerKey(actual))
+        throw new Error('owner-path-conflict: the approved home differs from the configured path');
+}
+/** Pure read: resolve existing configured homes without migration or identity configuration. */
+function resolveOwnerHome(projectPath, level, options) {
+    const load = (relative) => options.runtimeModule(projectPath, relative);
+    const paths = load('core/utils/project-fraim-paths');
+    let home;
+    if (level === 'Project') {
+        const root = paths.getWorkspaceFraimPath(projectPath);
+        home = { root, artifactRoot: node_path_1.default.resolve(projectPath), contentRoot: node_path_1.default.join(root, 'personalized-employee'), requiresPublish: false, backend: 'project' };
+    }
+    else {
+        if (!['Manager', 'Org'].includes(level))
+            throw new Error('owner-unresolved: invalid owner level');
+        const configFile = node_path_1.default.join(paths.getUserFraimDirPath(), 'config.json');
+        let config;
+        try {
+            config = node_fs_1.default.existsSync(configFile) ? JSON.parse(node_fs_1.default.readFileSync(configFile, 'utf8')) : {};
+        }
+        catch {
+            throw new Error('home-unavailable: user configuration is invalid');
+        }
+        if (!config || typeof config !== 'object' || Array.isArray(config))
+            throw new Error('home-unavailable: user configuration is invalid');
+        const raw = level === 'Manager' ? config.managerStorage : config.organization;
+        if (raw !== undefined && (!raw || typeof raw !== 'object' || Array.isArray(raw)
+            || !['git', 'local-folder', 'fraim-cloud', 'single-machine'].includes(raw.backend)
+            || (raw.backend === 'git' && (typeof raw.gitUrl !== 'string' || !raw.gitUrl.trim()))
+            || (raw.backend === 'local-folder' && (typeof raw.localPath !== 'string' || !raw.localPath.trim())))) {
+            throw new Error('home-unavailable: invalid configured storage home');
+        }
+        const resolved = load('cli/utils/pack-home').resolvePackHome(level === 'Manager' ? 'manager' : 'org', { migrateLegacy: false });
+        home = { root: resolved.root, contentRoot: resolved.contentRoot, requiresPublish: resolved.requiresPublish, backend: resolved.backend, ...(resolved.gitUrl ? { gitUrl: resolved.gitUrl } : {}) };
+    }
+    const owner = { level, path: ownerPath(home.root) };
+    if (options.expectedOwner)
+        assertSameOwner(options.expectedOwner, owner);
+    if (!node_fs_1.default.existsSync(home.root) || !node_fs_1.default.statSync(home.root).isDirectory()
+        || (home.backend === 'git' && !node_fs_1.default.existsSync(node_path_1.default.join(home.root, '.git')))) {
+        throw new Error('home-unavailable: configured home is not available locally');
+    }
+    return { ...home, level, owner };
+}
+/** Resolve a relative artifact without permitting lexical or realpath escapes, including junctions. */
+function ownerArtifactPath(home, relativePath) {
+    assertSameOwner(home.owner, { level: home.level, path: ownerPath(home.root) });
+    if (!relativePath || node_path_1.default.isAbsolute(relativePath) || relativePath.includes('\\')
+        || relativePath.includes(':') || relativePath.split('/').some(part => !part || part === '.' || part === '..')) {
+        throw new Error('invalid-artifact-path');
+    }
+    // Shared project capabilities live in the repository registry, outside its personalized pack.
+    const shared = home.level === 'Project' && relativePath.startsWith('registry/');
+    const containmentRoot = shared ? node_path_1.default.dirname(home.root) : home.root;
+    // The workspace configuration has one explicit reference; arbitrary parent paths stay forbidden.
+    const workspaceConfig = home.level === 'Project' && relativePath === 'config.json';
+    const contentRoot = shared ? containmentRoot : workspaceConfig ? home.root : home.contentRoot;
+    const target = node_path_1.default.resolve(contentRoot, relativePath);
+    const existingAncestor = (file) => {
+        let current = file;
+        while (!node_fs_1.default.existsSync(current)) {
+            const parent = node_path_1.default.dirname(current);
+            if (parent === current)
+                throw new Error('home-unavailable');
+            current = parent;
+        }
+        return current;
+    };
+    const realRoot = node_fs_1.default.realpathSync(containmentRoot);
+    const ancestor = node_fs_1.default.realpathSync(existingAncestor(target));
+    const relative = node_path_1.default.relative(realRoot, ancestor);
+    if (relative === '..' || relative.startsWith('..' + node_path_1.default.sep) || node_path_1.default.isAbsolute(relative))
+        throw new Error('invalid-artifact-path: escaped owner home');
+    // Also reject escaping a content root via a symlink to a sibling in the pack.
+    if (node_fs_1.default.existsSync(contentRoot)) {
+        const contentRelative = node_path_1.default.relative(node_fs_1.default.realpathSync(contentRoot), ancestor);
+        if (contentRelative === '..' || contentRelative.startsWith('..' + node_path_1.default.sep) || node_path_1.default.isAbsolute(contentRelative))
+            throw new Error('invalid-artifact-path: escaped content root');
+    }
+    return target;
+}
+/** Explicit artifact base; never infer a project from its personalized directory. */
+const ownerArtifactRoot = (home) => home.artifactRoot ?? home.root;
+exports.ownerArtifactRoot = ownerArtifactRoot;
+/** Configured artifacts may sit outside the personalized pack, but never outside their owner. */
+function configuredArtifactPath(home, file) {
+    assertSameOwner(home.owner, { level: home.level, path: ownerPath(home.root) });
+    const root = node_path_1.default.resolve((0, exports.ownerArtifactRoot)(home));
+    const target = node_path_1.default.resolve(file);
+    const relative = node_path_1.default.relative(root, target);
+    if (!relative || relative === '..' || relative.startsWith('..' + node_path_1.default.sep) || node_path_1.default.isAbsolute(relative))
+        throw new Error('invalid-artifact-path: escaped owner home');
+    for (let current = target; ownerPath(current) !== ownerPath(root); current = node_path_1.default.dirname(current)) {
+        try {
+            if (node_fs_1.default.lstatSync(current).isSymbolicLink())
+                throw new Error('invalid-artifact-path: linked artifact');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return target;
+}

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -186,7 +186,7 @@ function resolvePersonalLearningFile(repoBase, managerCacheBase, managerCacheDis
  * before the change, and the same shadowing applied to company families.
  *
  * Returning all tiers lets the context block list each present path and lets the
- * Hub merge entries with the project entry winning only on a title collision.
+ * Hub retain each current occurrence without treating title collisions as authority.
  */
 function resolvePersonalLearningFileTiers(repoBase, managerCacheBase, managerCacheDisplayBase, globalBase, globalDisplayBase, fileName) {
     const tiers = [];
@@ -723,19 +723,12 @@ function resolveOrgLearningFileTiers(repoLearningsBase, fileName) {
     return tiers;
 }
 /**
- * Issue #1002 R4: merge entries across tiers. Lowest precedence first in, so a
- * later tier overwrites on an identical title and nothing is duplicated. Entries
- * whose titles do not collide all survive, which is the whole point: promoting
- * one entry must not hide the rest of its family.
+ * Keep every current occurrence visible. A title is not identity and neither
+ * tier order nor equal IDs authorize discarding a conflicting revision.
+ * Reconciliation belongs to the reviewed learning application flow.
  */
 function mergeLearningEntriesAcrossTiers(tiers) {
-    const byTitle = new Map();
-    for (const tier of tiers) {
-        for (const entry of tier.entries) {
-            byTitle.set(entry.title.trim().toLowerCase(), entry);
-        }
-    }
-    return [...byTitle.values()];
+    return tiers.flatMap(tier => tier.entries);
 }
 const CONTEXT_CATEGORIES = {
     mistake: { ft: 'mistake-patterns', gated: true, label: '(entries above score threshold)' },
@@ -919,7 +912,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
         if (hasL2 || hasL1) {
             section += 'Read the listed synthesized learning files before continuing, then apply the relevant patterns and preferences in this job.\n';
             if (multiTier) {
-                section += 'A family listed at more than one level is combined, not replaced: apply every entry, and where the same entry title appears at two levels apply the more specific one (project over manager).\n';
+                section += 'A family listed at more than one level is combined, not replaced. Stable IDs identify lessons; equal titles do not establish identity. Conflicting copies require explicit reconciliation: do not choose a revision by scope, timestamp, count, or title. Preserve approved decisions and useful refinements; unresolved conflicting claims are not authority for action.\n';
             }
             if (coachPresent) {
                 section += 'Treat manager-coaching as feedback for how the manager should continue or improve managing AI, not as agent instruction.\n';
@@ -929,7 +922,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
     else if (hasL2 || hasL1) {
         section += 'Read the listed synthesized learning files before continuing, then use this synthesized learning context throughout the session.\n';
         if (multiTier) {
-            section += 'A family listed at more than one level is combined, not replaced: apply every entry, and where the same entry title appears at two levels apply the more specific one (project over manager).\n';
+            section += 'A family listed at more than one level is combined, not replaced. Stable IDs identify lessons; equal titles do not establish identity. Conflicting copies require explicit reconciliation: do not choose a revision by scope, timestamp, count, or title. Preserve approved decisions and useful refinements; unresolved conflicting claims are not authority for action.\n';
         }
         if (coachPresent) {
             section += 'Manager-coaching entries are manager-facing feedback, not instructions for the AI to follow.\n';
@@ -1019,27 +1012,10 @@ function enumerateFileEntries(file, threshold, usageClock, now) {
  * listed. `aboveThreshold` is what separates active guidance from the dormant
  * rollup. Nothing here depends on the agent reading anything.
  *
- * ## Issue #1752 A2 — one lesson, one offer, stamped or not
- *
- * This deduped by usage key, which sounds like the same thing as the context
- * reader's rule and is not. `resolveOrgLearningFileTiers` deliberately returns
- * both the org pack copy and the repo-local copy of an org family, because #1002
- * R4 requires that a promoted entry not hide the rest of its family. The context
- * reader then merges those tiers with `mergeLearningEntriesAcrossTiers`, keyed on
- * the normalized title, so the agent sees one lesson. Keying the offer record on
- * `id ?? titleUsageKey(...)` instead meant that a lesson carrying an `**Id**` line
- * in one tier and not the other produced two keys, and both were recorded.
- *
- * That is defect 4 in #1752, and it is why `standing --changes-only` could
- * recommend promoting and demoting the same lesson in one response: the
- * title-keyed twin collected the offers while the id-keyed one collected the
- * firings (the firing path never split, because `buildEntryIndex` dedups by
- * identity first-wins). Measured live: five titles emitting two keys each in a
- * single derived offer batch.
- *
- * So group by the same normalized title the context reader groups by, resolve one
- * identity per group preferring whichever tier carries an id, and let the later
- * tier win on content exactly as before.
+ * Offers use stable identity, independently of ownership reconciliation. A repeated
+ * ID records one offer, but equal titles with different IDs remain distinct.
+ * Unstamped legacy entries retain their existing title usage key; that fallback
+ * never grants a stamped entry authority over a different identity.
  */
 function collectOfferedLearningEntries(workspaceRoot, userId, forJob, domain) {
     const roots = getLearningRoots(workspaceRoot);
@@ -1048,13 +1024,10 @@ function collectOfferedLearningEntries(workspaceRoot, userId, forJob, domain) {
     const usageClock = resolveUsageClock(workspaceRoot);
     const now = new Date();
     const resolved = resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJob, domain);
-    // Grouped by family plus normalized title, which is what `titleUsageKey`
-    // already computes. Two families holding the same title are two lessons, and
-    // that is the existing rule rather than a new one.
     const byLesson = new Map();
     for (const file of [...resolved.l2, ...resolved.l1]) {
         for (const entry of enumerateFileEntries(file, threshold, usageClock, now)) {
-            const lessonKey = (0, learning_usage_store_1.titleUsageKey)(entry.fileType, entry.title);
+            const lessonKey = entry.id ?? (0, learning_usage_store_1.titleUsageKey)(entry.fileType, entry.title);
             const group = byLesson.get(lessonKey);
             if (group)
                 group.push(entry);
@@ -1064,17 +1037,9 @@ function collectOfferedLearningEntries(workspaceRoot, userId, forJob, domain) {
     }
     const out = [];
     for (const group of byLesson.values()) {
-        // Later tier wins for content, unchanged precedence.
-        const winner = group[group.length - 1];
-        // The id comes from whichever tier carries one, because `stamp-ids` has not
-        // reached the org and manager pack homes for every corpus yet. Latest wins
-        // when more than one tier is stamped.
-        const id = group.reduce((found, entry) => entry.id ?? found, null);
-        out.push({
-            ...winner,
-            id,
-            key: (0, learning_usage_store_1.resolveEntryIdentity)({ id, fileType: winner.fileType, title: winner.title }).key,
-        });
+        // This is an offer counter, not a choice of authoritative guidance.
+        const entry = group[0];
+        out.push({ ...entry, aboveThreshold: group.some(item => item.aboveThreshold) });
     }
     return out;
 }
@@ -1461,7 +1426,7 @@ function readLearningEntryTitles(filePath) {
  *
  * Issue #1002: two changes from the original.
  *
- * R4: counts sum across every level that holds a family, deduped by entry title,
+ * R4: counts sum across every level that holds a family,
  * rather than counting only the winning file. Under the old first-wins read a
  * family present at two levels was counted once, so the Brain under-reported
  * exactly the case this issue introduces.
@@ -1483,26 +1448,27 @@ function countPreservedLearnings(workspaceRoot, userId) {
         }
         return titles.size;
     };
-    // Same for a personal family, and reported per level so the Brain can show
-    // where each entry actually lives. A title present at both levels counts
-    // once, at the project level, matching which entry the agent applies.
+    // Count current occurrences at their actual owner; reconciliation, not a
+    // title match, determines whether a redundant copy may be removed.
     const countPersonalFamilyByLevel = (fileName) => {
         const tiers = resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, fileName);
-        const projectTitles = new Set();
-        const managerTitles = new Set();
+        const seenFiles = new Set();
+        const counts = { manager: 0, project: 0 };
         for (const tier of tiers) {
-            for (const t of readLearningEntryTitles(tier.path)) {
-                if (tier.level === 'project')
-                    projectTitles.add(t);
-                else
-                    managerTitles.add(t);
+            let file;
+            try {
+                file = (0, fs_1.realpathSync)(tier.path);
+            }
+            catch {
+                continue;
             }
+            if (seenFiles.has(file))
+                continue;
+            seenFiles.add(file);
+            const owner = tier.level === 'project' ? 'project' : 'manager';
+            counts[owner] += countLearningEntries(tier.path);
         }
-        // A promoted entry lives at the project level; do not also count it as the
-        // manager's, or the two tiles would double-report the same lesson.
-        for (const t of projectTitles)
-            managerTitles.delete(t);
-        return { manager: managerTitles.size, project: projectTitles.size };
+        return counts;
     };
     const PERSONAL_WORK_TYPES = ['mistake-patterns', 'preferences', 'validated-patterns'];
     const ORG_TYPES = ['mistake-patterns', 'preferences', 'manager-coaching', 'validated-patterns'];
@@ -1803,6 +1769,8 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
                 current.score = null;
                 current.injected = true;
             }
+            if (tier === 'cold')
+                current.injected = false;
             out.push(current);
         }
         current = null;
@@ -1926,7 +1894,7 @@ function readRejectedProposals(workspaceRoot, userId) {
                 ? proposal.claimKey
                 : parts[1] || heading[2];
             // The same claim can appear in more than one configured base. The first
-            // base that carries it wins, matching how the tier merge resolves.
+            // base supplies display metadata for that same recorded decision.
             const key = `${claimKey}:${String(decision.at || '')}`;
             if (seen.has(key))
                 continue;
@@ -1966,7 +1934,7 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
         for (const cat of ['avoid', 'preference', 'repeat', 'coaching']) {
             const fileType = exports.CATEGORY_TO_FILETYPE[cat];
             const f = `org-${fileType}.md`;
-            // org pack home first, repo-local override second; repo-local wins on title collision.
+            // Keep occurrences from both homes; title matches do not grant authority.
             out.push(...parseTiers(resolveOrgLearningFileTiers(roots.repoLearningsBase, f), cat));
             // #806: domain-scoped org learnings — union from both locations.
             const allDomainFiles = [
@@ -1990,46 +1958,18 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
         }
         return out;
     }
-    // manager + reverse: use the same three-tier resolution as buildLearningContextSection.
+    // The library is an ownership view, not the combined runtime context.
     const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
     const cats = scope === 'reverse' ? ['coaching'] : ['avoid', 'preference', 'repeat'];
-    if (level === 'project') {
-        // Project level: repo-local only (single tier, no merge needed).
-        for (const cat of cats) {
-            const fileType = exports.CATEGORY_TO_FILETYPE[cat];
-            const f = `${resolvedUserId}-${fileType}.md`;
-            out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, f), `${REPO_LEARNINGS_REL}/${f}`, cat, 'project', 'global', 'hot', threshold, usageClock, usageStats));
-            const coldF = `${resolvedUserId}-${fileType}${COLD_FILE_SUFFIX}.md`;
-            if ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, coldF))) {
-                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, coldF), `${REPO_LEARNINGS_REL}/${coldF}`, cat, 'project', 'global', 'cold', threshold, usageClock, usageStats));
-            }
-            for (const { fileName, domain } of listDomainLearningFiles(roots.repoLearningsBase, resolvedUserId, fileType)) {
-                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'project', domain, 'hot', threshold, usageClock, usageStats));
-            }
-        }
-        return out;
-    }
-    // machine level: all three personal tiers (managerCacheBase, globalPersonalBase, repoLearningsBase).
-    // Cold siblings are read from each tier that has the hot file.
     for (const cat of cats) {
         const fileType = exports.CATEGORY_TO_FILETYPE[cat];
-        const f = `${resolvedUserId}-${fileType}.md`;
-        const tiers = resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, f);
-        out.push(...parseTiers(tiers, cat, 'hot'));
-        // Cold sibling from each tier that has the hot file.
-        const coldF = `${resolvedUserId}-${fileType}${COLD_FILE_SUFFIX}.md`;
-        const coldTiers = resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, coldF);
-        out.push(...parseTiers(coldTiers, cat, 'cold'));
-        // #806: domain files from managerHomeBase and repo base.
-        const domainDirs = [roots.globalPersonalBase, roots.managerCacheBase, roots.repoLearningsBase];
-        const seenDomain = new Set();
-        for (const dir of domainDirs) {
-            for (const { fileName, domain } of listDomainLearningFiles(dir, resolvedUserId, fileType)) {
-                if (seenDomain.has(fileName))
-                    continue;
-                seenDomain.add(fileName);
-                const domTiers = resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, fileName);
-                out.push(...parseTiers(domTiers, cat, 'hot', domain));
+        for (const domain of ['global', ...learning_domains_1.LEARNING_DOMAINS]) {
+            const domainPart = domain === 'global' ? '' : `-${domain}`;
+            for (const storageTier of ['hot', 'cold']) {
+                const suffix = storageTier === 'cold' ? COLD_FILE_SUFFIX : '';
+                const fileName = `${resolvedUserId}${domainPart}-${fileType}${suffix}.md`;
+                const tiers = resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, fileName).filter(t => level === 'project' ? t.level === 'project' : t.level !== 'project');
+                out.push(...parseTiers(tiers, cat, storageTier, domain));
             }
         }
     }
@@ -2097,12 +2037,22 @@ function applyLearningEntryChange(workspaceRoot, userId, ref, action, payload) {
         write(preamble + nl + nl + block);
         return { ok: true, path: filePath };
     }
-    const targetIdx = starts.findIndex((s) => {
-        const m = lines[s].match(headingRe);
-        return m && m[2].trim() === (payload.originalTitle || '').trim();
+    if (payload.originalId !== undefined && (typeof payload.originalId !== 'string' || !/^L-[0-9A-Za-z]{6,24}$/.test(payload.originalId))) {
+        throw new Error('Invalid learning entry identity');
+    }
+    const matches = starts.map((start, index) => ({ start, index })).filter(({ start, index }) => {
+        if (payload.originalId !== undefined) {
+            const end = index + 1 < starts.length ? starts[index + 1] : lines.length;
+            const ids = lines.slice(start + 1, end).map(line => line.trim().match(LEARNING_ENTRY_ID_LINE)).filter(Boolean);
+            return ids.length === 1 && ids[0][1] === payload.originalId;
+        }
+        return lines[start].match(headingRe)?.[2].trim() === (payload.originalTitle || '').trim();
     });
-    if (targetIdx === -1)
-        throw new Error(`Learning entry not found: "${payload.originalTitle}"`);
+    if (!matches.length)
+        throw new Error(`Learning entry not found: "${payload.originalId ?? payload.originalTitle}"`);
+    if (matches.length !== 1)
+        throw new Error('Learning entry is ambiguous; reconcile duplicate identities or select a unique entry');
+    const targetIdx = matches[0].index;
     const start = starts[targetIdx];
     const end = targetIdx + 1 < starts.length ? starts[targetIdx + 1] : lines.length;
     if (action === 'delete') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.345",
+  "version": "2.0.346",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {
@@ -12,6 +12,8 @@
     "dist/registry/scripts/learning/learning-domains.json",
     "dist/registry/scripts/learning/entry-format.js",
     "dist/registry/scripts/learning/completion-state.js",
+    "dist/registry/scripts/learning/corpus-audit.js",
+    "dist/registry/scripts/learning/owner-identity.js",
     "dist/src/local-mcp-server/",
     "dist/src/cli/",
     "!dist/src/cli/fraim-hub.js",