fraim 2.0.346 → 2.0.349

package/dist/src/cli/learning/queue-operations.js

@@ -0,0 +1,199 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveQueueHome = resolveQueueHome;
+exports.resolveReaderCorpusRoots = resolveReaderCorpusRoots;
+exports.runQueueCommand = runQueueCommand;
+/** Packaged learning queue operations and home resolvers. */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("./runtime");
+const completion_state_1 = require("../../../registry/scripts/learning/completion-state");
+const artifact_paths_1 = require("../../../registry/scripts/artifact-paths");
+const entry_authoring_1 = require("../../../registry/scripts/learning/entry-authoring");
+const owner_identity_1 = require("../../../registry/scripts/learning/owner-identity");
+const run_record_1 = require("../../../registry/scripts/learning/run-record");
+const run_application_1 = require("../../../registry/scripts/learning/run-application");
+const run_publication_1 = require("../../../registry/scripts/learning/run-publication");
+const corpus_audit_1 = require("../../../registry/scripts/learning/corpus-audit");
+const outcome_assessment_1 = require("../../../registry/scripts/learning/outcome-assessment");
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+const pack_home_1 = require("../utils/pack-home");
+const user_config_1 = require("../utils/user-config");
+const local_registry_resolver_1 = require("../../core/utils/local-registry-resolver");
+function resolveQueueHome(projectPath, level) {
+    return (0, owner_identity_1.resolveOwnerHome)(projectPath, level, { runtimeModule: runtime_1.runtimeModuleStatic });
+}
+function resolveReaderCorpusRoots(projectPath) {
+    const manager = (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false });
+    const portable = (0, project_fraim_paths_1.getConfiguredPortableLearningsDir)(projectPath);
+    const same = (left, right) => node_path_1.default.resolve(left) === node_path_1.default.resolve(right);
+    const roots = manager.synced ? [] : [node_path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'manager', 'learnings')];
+    if (same(portable, node_path_1.default.join(manager.contentRoot, 'learnings')) || !same(portable, (0, project_fraim_paths_1.getUserFraimLearningsDir)()))
+        roots.push(portable);
+    return [...new Set(roots)];
+}
+function evidenceDirectory(home) {
+    const directory = node_path_1.default.join((0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot).evidence, 'sleep');
+    (0, owner_identity_1.configuredArtifactPath)(home, directory);
+    return directory;
+}
+const journalDirectory = (home) => (0, artifact_paths_1.resolveRunJournalDirectory)(home.root);
+async function runQueueCommand(argv) {
+    const arg = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; };
+    const action = arg('--action');
+    const projectPath = node_path_1.default.resolve(arg('--projectPath') || process.cwd());
+    const principal = arg('--owner');
+    if (!principal)
+        throw new Error('session-principal-required: pass the authenticated FRAIM owner');
+    const level = (arg('--level') || 'Manager');
+    if (level === 'Project' && action !== 'list' && action !== 'show' && action !== 'assessments')
+        throw new Error('run-home-required: personal Sleep records belong to Manager; use Org for organizational synthesis');
+    const home = resolveQueueHome(projectPath, level);
+    const directory = journalDirectory(home);
+    const runId = arg('--runId');
+    const resolveHome = (owner) => { const found = resolveQueueHome(projectPath, owner.level); (0, owner_identity_1.assertSameOwner)(owner, found.owner); return found; };
+    const configuredHomes = () => {
+        const homes = [resolveQueueHome(projectPath, 'Project'), resolveQueueHome(projectPath, 'Manager')];
+        if ((0, user_config_1.readUserFraimConfig)().organization)
+            homes.push(resolveQueueHome(projectPath, 'Org'));
+        return homes;
+    };
+    if (action === 'assessments') {
+        const records = (0, outcome_assessment_1.readOutcomeAssessments)(level === 'Manager' ? configuredHomes() : [home], principal);
+        // Cross-participant read authority belongs to an explicit live Org run, never merely to the selected level.
+        if (level === 'Org' && runId) {
+            const state = new run_record_1.RunRecord(directory, runId, home.owner, principal, evidenceDirectory(home)).read();
+            for (const grant of state.sourceParticipants ?? [])
+                records.push(...(0, outcome_assessment_1.readOutcomeAssessments)([resolveHome(grant.owner)], grant.author));
+        }
+        return { assessments: [...new Map(records.map(record => [record.digest, record])).values()] };
+    }
+    if (action === 'list' && !runId)
+        return { runs: node_fs_1.default.existsSync(directory) ? node_fs_1.default.readdirSync(directory).filter(n => n.endsWith('.queue.jsonl')).flatMap(n => {
+                const state = (0, run_record_1.readSupportedRunRecord)(node_path_1.default.join(directory, n));
+                if (!state)
+                    return [];
+                (0, owner_identity_1.assertSameOwner)(home.owner, state.owner);
+                if (state.reviewer !== principal)
+                    throw new Error('run-context-mismatch');
+                return [state];
+            }) : [] };
+    if (!runId)
+        throw new Error('run-context-required: provide --runId; legacy queue mutations are disabled');
+    const inspecting = action === 'show' || action === 'list';
+    const recorded = inspecting && node_fs_1.default.existsSync(directory) && node_fs_1.default.readdirSync(directory).includes(runId + '.queue.jsonl')
+        ? (0, run_record_1.readSupportedRunRecord)((0, owner_identity_1.configuredArtifactPath)(home, node_path_1.default.join(directory, runId + '.queue.jsonl'))) : null;
+    const completionDirectory = recorded?.completionDirectory ?? (level === 'Project' ? directory : evidenceDirectory(home));
+    (0, owner_identity_1.configuredArtifactPath)(home, completionDirectory);
+    const run = new run_record_1.RunRecord(directory, runId, home.owner, principal, completionDirectory);
+    const expectedSequence = Number(arg('--expectedSequence'));
+    const id = arg('--actionId') || '';
+    const revision = Number(arg('--revision'));
+    const inputFile = arg('--inputFile');
+    const input = inputFile ? JSON.parse(node_fs_1.default.readFileSync(inputFile, 'utf8')) : undefined;
+    if (action === 'create') {
+        const participants = input?.sourceParticipants === undefined ? undefined : (0, completion_state_1.normalizeSourceParticipants)(input.sourceParticipants, home.owner);
+        for (const participant of participants ?? [])
+            (0, owner_identity_1.assertSameOwner)(participant.owner, resolveQueueHome(projectPath, participant.owner.level).owner);
+        return { ...run.create(participants), evidencePath: run.completionFile.replace(/\\/g, '/') };
+    }
+    if (input?.sourceParticipants !== undefined)
+        throw new Error('source-participants-create-only');
+    if (action === 'recover')
+        return run.recoverTail(input?.expectedPrefixHash);
+    if (action === 'list' || action === 'show')
+        return node_fs_1.default.existsSync(run.file)
+            ? { ...run.read(), evidencePath: run.completionFile.replace(/\\/g, '/') }
+            : { missing: true, runId };
+    if (action === 'propose' || action === 'edit') {
+        if (!input)
+            throw new Error('input-required');
+        if (input.kind === 'learning' && input.operation !== 'remove') {
+            if (!input.target.entryId)
+                input.target.entryId = 'L-' + (0, node_crypto_1.randomUUID)().replace(/-/g, '').slice(0, 10);
+            const managerHome = (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false });
+            const orgHome = (0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false });
+            const resolver = new local_registry_resolver_1.LocalRegistryResolver({ workspaceRoot: projectPath, managerLocalRoot: managerHome.contentRoot, managerCacheRoot: managerHome.contentRoot, orgCacheRoot: orgHome.contentRoot, remoteContentResolver: async () => { throw new Error('job-definition-unavailable'); } });
+            if (input.content?.domain?.basis !== 'manager') {
+                for (const origin of input.content.trace.originatingJobs) {
+                    origin.registryPath ||= await resolver.findRegistryPath('jobs', origin.name);
+                    const definition = await resolver.resolveFile(origin.registryPath).catch(() => null);
+                    if (definition?.content)
+                        origin.content = definition.content;
+                }
+                input.content.domain = (0, entry_authoring_1.deriveDomain)(input.content.trace.originatingJobs);
+                for (const origin of input.content.trace.originatingJobs)
+                    delete origin.content;
+            }
+        }
+        return action === 'propose' ? run.propose(input, expectedSequence) : run.edit(id, revision, input, expectedSequence);
+    }
+    if (action === 'decide' && input?.tuples)
+        return run.decideBatch(input.tuples, arg('--reviewer') || '', arg('--reason') || '', expectedSequence);
+    if (action === 'decide')
+        return run.decide(id, revision, { action: arg('--decision'), reviewer: arg('--reviewer') || '', reason: arg('--reason') || '', ...(arg('--revisitCondition') ? { revisitCondition: arg('--revisitCondition') } : {}) }, expectedSequence);
+    if (action === 'assess') {
+        if (!input)
+            throw new Error('input-required');
+        const homes = configuredHomes();
+        const runDirectories = homes.map(journalDirectory);
+        const coordinationFile = node_path_1.default.join(journalDirectory(homes.find(item => item.level === 'Manager')), 'owner-application');
+        return (0, outcome_assessment_1.recordOutcomeAssessment)(run, input, expectedSequence, { resolveHome, homes, runDirectories, coordinationFile });
+    }
+    if (action === 'audit-corpus') {
+        const state = run.read();
+        const current = (0, corpus_audit_1.collectLearningCorpus)(configuredHomes(), [principal, ...(state.sourceParticipants?.map(grant => grant.author) || [])], resolveReaderCorpusRoots(projectPath));
+        if (!current.complete && input?.allowDeferred !== true)
+            throw new Error('corpus-incomplete');
+        if (!input?.snapshot || input.snapshot.fingerprint !== current.fingerprint)
+            throw new Error('corpus-audit-stale');
+        return run.recordCorpusAudit({ snapshot: current, reviewer: input.reviewer, dispositions: input.dispositions, ...(input.allowDeferred === true ? { partial: true } : {}) }, expectedSequence);
+    }
+    if (action === 'apply') {
+        const state = run.read();
+        const proposed = state.actions[id];
+        const homes = configuredHomes();
+        const runDirectories = homes.map(journalDirectory);
+        const coordinationFile = node_path_1.default.join(journalDirectory(homes.find(item => item.level === 'Manager')), 'owner-application');
+        (0, run_application_1.reserveRunAction)(run, id, revision, expectedSequence, { resolveHome, runDirectories, coordinationFile, homes, readerRoots: () => resolveReaderCorpusRoots(projectPath) });
+        const applySequence = run.read().sequence;
+        const capability = proposed?.kind === 'capability' ? await (0, run_publication_1.verifyCapabilityDelivery)(proposed, { ...input, operationKey: `${runId}-${id}-${revision}` }, { projectPath, resolveHome, runtimeModule: runtime_1.runtimeModuleStatic, runtimeModulePath: runtime_1.runtimeModulePathStatic }) : undefined;
+        const capabilities = new Map();
+        if (capability)
+            capabilities.set(id, capability);
+        for (const dependencyId of proposed?.dependencies || []) {
+            const dependency = state.actions[dependencyId];
+            if (dependency?.kind !== 'capability')
+                continue;
+            capabilities.set(dependencyId, await (0, run_publication_1.verifyCapabilityDelivery)(dependency, { publicationRef: dependency.application?.publicationRef, operationKey: `${runId}-${dependencyId}-${dependency.revision}` }, { projectPath, resolveHome, runtimeModule: runtime_1.runtimeModuleStatic, runtimeModulePath: runtime_1.runtimeModulePathStatic }));
+        }
+        return (0, run_application_1.applyRunAction)(run, id, revision, applySequence, {
+            resolveHome, runDirectories, coordinationFile, homes, readerRoots: () => resolveReaderCorpusRoots(projectPath),
+            publish: (file, targetHome, key, hash, proof) => (0, run_publication_1.publishRunFile)(projectPath, file, targetHome, key, hash, runtime_1.runtimeModulePathStatic, proof),
+            verifyCapability: candidate => capabilities.get(candidate.actionId),
+        });
+    }
+    if (action === 'complete') {
+        if (!Array.isArray(input?.analyzedSources))
+            throw new Error('analyzed-sources-required');
+        const homes = configuredHomes();
+        const capabilities = new Map();
+        if (node_fs_1.default.existsSync(run.file))
+            for (const candidate of Object.values(run.read().actions)) {
+                if (candidate.kind === 'capability' && candidate.application?.stage === 'applied')
+                    capabilities.set(candidate.actionId, await (0, run_publication_1.verifyCapabilityDelivery)(candidate, { publicationRef: candidate.application.publicationRef, operationKey: `${runId}-${candidate.actionId}-${candidate.revision}` }, { projectPath, resolveHome, runtimeModule: runtime_1.runtimeModuleStatic, runtimeModulePath: runtime_1.runtimeModulePathStatic }));
+            }
+        return (0, run_application_1.completeRun)(run, input?.summary, homes, { resolveHome, homes, readerRoots: () => resolveReaderCorpusRoots(projectPath), runDirectories: homes.map(journalDirectory), retrospective: input?.retrospective, analyzedSources: input.analyzedSources,
+            allowDeferred: input?.allowDeferred === true, deferredSources: input?.deferredSources,
+            publish: (file, targetHome, key, hash, proof) => (0, run_publication_1.publishRunFile)(projectPath, file, targetHome, key, hash, runtime_1.runtimeModulePathStatic, proof),
+            verifyCapability: candidate => capabilities.get(candidate.actionId),
+        });
+    }
+    if (action === 'reconcile-source')
+        return run.reconcileSource(input, resolveHome(input.owner), expectedSequence);
+    throw new Error('invalid-action');
+}

package/dist/src/cli/learning/runtime.js

@@ -0,0 +1,82 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeModuleStatic = runtimeModuleStatic;
+exports.runtimeModulePathStatic = runtimeModulePathStatic;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const projectFraimPaths = __importStar(require("../../core/utils/project-fraim-paths"));
+const packHome = __importStar(require("../utils/pack-home"));
+const userConfig = __importStar(require("../utils/user-config"));
+const localRegistryResolver = __importStar(require("../../core/utils/local-registry-resolver"));
+const learningContextBuilder = __importStar(require("../../local-mcp-server/learning-context-builder"));
+const learningUsageStore = __importStar(require("../../local-mcp-server/learning-usage-store"));
+const MODULE_MAP = {
+    'core/utils/project-fraim-paths': projectFraimPaths,
+    'cli/utils/pack-home': packHome,
+    'cli/utils/user-config': userConfig,
+    'core/utils/local-registry-resolver': localRegistryResolver,
+    'local-mcp-server/learning-context-builder': learningContextBuilder,
+    'local-mcp-server/learning-usage-store': learningUsageStore,
+};
+/**
+ * Static adapter satisfying the runtimeModule(projectPath, relative) interface.
+ * Resolves canonical packaged modules without installation-layout discovery.
+ */
+function runtimeModuleStatic(_projectPath, relative) {
+    const mod = MODULE_MAP[relative];
+    if (mod === undefined)
+        throw new Error(`runtime-unavailable: no static module for '${relative}' — add it to src/cli/learning/runtime.ts`);
+    return mod;
+}
+/**
+ * Static path resolver satisfying the runtimeModulePath(projectPath, relative) interface.
+ * Returns the absolute path to the compiled (or source) module file.
+ *
+ * __dirname is dist/src/cli/learning/ (compiled) or src/cli/learning/ (tsx).
+ * Two levels up lands at dist/src/ or src/, from which relative resolves correctly.
+ */
+function runtimeModulePathStatic(_projectPath, relative) {
+    const compiled = node_path_1.default.join(__dirname, '..', '..', relative + '.js');
+    if (node_fs_1.default.existsSync(compiled))
+        return compiled;
+    const source = node_path_1.default.join(__dirname, '..', '..', relative + '.ts');
+    if (node_fs_1.default.existsSync(source))
+        return source;
+    throw new Error(`runtime-unavailable: no static module path for '${relative}'`);
+}

package/dist/src/cli/learning/usage.js

@@ -0,0 +1,277 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runUsageCommand = runUsageCommand;
+/** Explicit historical diagnostics and maintenance through the canonical packaged runtime. */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const learning_entry_format_1 = require("../../local-mcp-server/learning-entry-format");
+const learning_usage_analysis_1 = require("../../local-mcp-server/learning-usage-analysis");
+const learning_usage_store_1 = require("../../local-mcp-server/learning-usage-store");
+const learning_usage_verify_1 = require("../../local-mcp-server/learning-usage-verify");
+const pack_home_1 = require("../utils/pack-home");
+const COMMANDS = {
+    report: runReport,
+    'stamp-ids': runStampIds,
+    prune: runPrune,
+    verify: runVerify,
+};
+/** Preserve matching snapshot, checkpoint and journal files during explicit recovery. */
+const REBUILD_NOTE = "Keep `learning-usage.json`, its `.checkpoint` backup, `events/` and any conflict copies. After consolidation, the snapshot and checkpoint backup preserve lifetime counters and already-counted source markers; the remaining journal cannot rebuild that history. A missing or torn snapshot is read from its checkpoint backup automatically. Restore matching checkpoint and journal files from backup if both copies are damaged. Inspect split identities and conflict copies before repairing them; do not delete the snapshot to clear a warning.";
+/** Historical retention bounds never participate in outcome assessment decisions. */
+function readStore(workspaceRoot) {
+    return (0, learning_usage_store_1.readUsageStore)(undefined, { limits: (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot), refreshSnapshot: 'never' });
+}
+function parseArgv(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === '--help' || command === '-h') {
+        printHelp();
+        process.exit(command ? 0 : 1);
+    }
+    if (!Object.prototype.hasOwnProperty.call(COMMANDS, command)) {
+        throw new Error(`Unknown learning-usage command: ${command}`);
+    }
+    const options = {};
+    for (let i = 0; i < rest.length; i++) {
+        const raw = rest[i];
+        if (!raw.startsWith('--'))
+            throw new Error(`Unexpected positional argument: ${raw}`);
+        const eq = raw.indexOf('=');
+        const key = camelCase(eq >= 0 ? raw.slice(2, eq) : raw.slice(2));
+        const next = eq >= 0 ? raw.slice(eq + 1) : rest[i + 1];
+        const isBoolean = eq < 0 && (next === undefined || next.startsWith('--'));
+        const value = parseOptionValue(key, isBoolean ? true : next);
+        if (!isBoolean && eq < 0)
+            i++;
+        if (key === 'dir') {
+            options.dir = [...arrayOption(options.dir), String(value)];
+        }
+        else {
+            options[key] = value;
+        }
+    }
+    return { command, options };
+}
+function parseOptionValue(key, value) {
+    if (key !== 'apply' && key !== 'json')
+        return value;
+    if (value === true || value === 'true')
+        return true;
+    if (value === false || value === 'false')
+        return false;
+    throw new Error(`Invalid boolean for --${key}: expected true or false.`);
+}
+function camelCase(value) {
+    return value.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function arrayOption(value) {
+    return Array.isArray(value) ? value : value === undefined ? [] : [String(value)];
+}
+function resolveWorkspaceRoot(options) {
+    return node_path_1.default.resolve(options.workspaceRoot || options.root || process.cwd());
+}
+function emit(payload, json, text) {
+    process.stdout.write(json ? `${JSON.stringify(payload, null, 2)}\n` : `${text()}\n`);
+}
+function runReport(options) {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const report = (0, learning_usage_analysis_1.buildUsageReport)(readStore(workspaceRoot));
+    emit(report, options.json, () => [
+        `Historical outcomes, last observed ${report.lastObservedAt ?? 'unknown'}.`,
+        ...report.historicalOutcomes.map(entry => `${entry.title}: ${entry.fired} recorded uses; last recorded use ${entry.lastFired ?? 'unknown'}.`),
+    ].join('\n'));
+}
+function stampFile(filePath, fileType, apply) {
+    const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const { out, stamped, alreadyStamped } = stampLines(content.split(/\r?\n/), fileType);
+    if (apply && stamped > 0)
+        node_fs_1.default.writeFileSync(filePath, out.join(eol), 'utf8');
+    return { file: filePath, entriesStamped: stamped, entriesAlreadyStamped: alreadyStamped };
+}
+function entryHasId(lines, index) {
+    const headingRe = (0, learning_entry_format_1.learningEntryHeadingRegex)();
+    const idRe = (0, learning_entry_format_1.learningEntryIdLineRegex)();
+    for (let j = index + 1; j < lines.length; j++) {
+        if (headingRe.test(lines[j]))
+            break;
+        if (idRe.test(lines[j].trim()))
+            return true;
+    }
+    return false;
+}
+function stampLines(lines, fileType) {
+    const headingRe = (0, learning_entry_format_1.learningEntryHeadingRegex)();
+    const out = [];
+    let stamped = 0;
+    let alreadyStamped = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        out.push(line);
+        const header = line.match(headingRe);
+        if (!header)
+            continue;
+        if (entryHasId(lines, i)) {
+            alreadyStamped++;
+            continue;
+        }
+        const title = header[2].trim();
+        if (!title)
+            continue;
+        if (lines[i + 1] !== undefined && lines[i + 1].trim() === '') {
+            out.push('');
+            out.push(`**Id**: ${(0, learning_entry_format_1.generateLearningEntryId)(fileType, title)}`);
+            i++;
+        }
+        else {
+            out.push(`**Id**: ${(0, learning_entry_format_1.generateLearningEntryId)(fileType, title)}`);
+        }
+        stamped++;
+    }
+    return { out, stamped, alreadyStamped };
+}
+function fileTypeFromName(fileName) {
+    for (const type of ['mistake-patterns', 'preferences', 'validated-patterns', 'manager-coaching']) {
+        if (fileName.includes(type))
+            return type;
+    }
+    return null;
+}
+function defaultStampDirs(workspaceRoot) {
+    const dirs = [node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings')];
+    for (const level of ['org', 'manager']) {
+        try {
+            dirs.push(node_path_1.default.join((0, pack_home_1.resolvePackHome)(level, { migrateLegacy: false }).contentRoot, 'learnings'));
+        }
+        catch {
+            // A pack home that does not resolve is simply not stamped. Visible in the
+            // printed directory list rather than failing the command.
+        }
+    }
+    return [...new Set(dirs)];
+}
+function runStampIds(options) {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    // Stamping is explicit; the dry run preserves every source byte.
+    const dirs = arrayOption(options.dir).length
+        ? arrayOption(options.dir).map((d) => node_path_1.default.resolve(d))
+        : defaultStampDirs(workspaceRoot);
+    const results = [];
+    for (const dir of dirs) {
+        if (!node_fs_1.default.existsSync(dir))
+            continue;
+        for (const fileName of node_fs_1.default.readdirSync(dir)) {
+            if (!fileName.endsWith('.md'))
+                continue;
+            const fileType = fileTypeFromName(fileName);
+            if (!fileType)
+                continue;
+            results.push(stampFile(node_path_1.default.join(dir, fileName), fileType, Boolean(options.apply)));
+        }
+    }
+    const payload = {
+        apply: Boolean(options.apply),
+        filesScanned: results.length,
+        entriesStamped: results.reduce((sum, r) => sum + r.entriesStamped, 0),
+        entriesAlreadyStamped: results.reduce((sum, r) => sum + r.entriesAlreadyStamped, 0),
+        files: results,
+    };
+    emit(payload, options.json, () => [
+        `${payload.apply ? 'Stamped' : 'Would stamp'} ${payload.entriesStamped} entries across ${payload.filesScanned} files in ${dirs.length} directories:`,
+        ...dirs.map((d) => `  ${d}`),
+        `${payload.entriesAlreadyStamped} entries already carry an id.`,
+        payload.apply ? '' : 'Re-run with --apply to write the changes.',
+    ].filter(Boolean).join('\n'));
+}
+function runPrune(options) {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const result = (0, learning_usage_store_1.pruneUsageStore)(limits);
+    emit({ ...result, storePath: (0, learning_usage_store_1.resolveUsageStorePath)(), limits }, options.json, () => result.maintenanceStatus === 'deferred' ? `Maintenance deferred; history unchanged. ${result.evidence?.observations.join(', ') ?? ''}`
+        : `Pruned ${result.prunedOfferRecords} offer records and ${result.prunedFiringRecords} firing records across ${result.entries} entries. Aggregates unchanged.`);
+}
+function mb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function verificationStorageLines(report) {
+    const lines = [];
+    if (report.storeCopies.length === 0) {
+        lines.push('  one store file, no unmerged copies');
+    }
+    else {
+        lines.push(`  ${report.storeCopies.length} unmerged store copies beside the canonical snapshot:`);
+        for (const copy of report.storeCopies) {
+            lines.push(`    ${copy.path}: ${copy.readable ? `${copy.entries} entries, ${copy.offers} offers, ${copy.firings} firings` : `unreadable (${copy.error ?? 'unknown error'})`}`);
+        }
+        lines.push('    Nothing reads these. Preserve them and the checkpoint backup for inspection; do not delete snapshots to clear this warning.');
+    }
+    lines.push(`  event logs folded: ${report.eventLogs.length === 0 ? 'none' : report.eventLogs.map((l) => `${l.machineId} (${l.bytes} bytes)`).join(', ')}`);
+    for (const [machineId, lag] of Object.entries(report.checkpointLag)) {
+        lines.push(`  checkpoint lag for ${machineId}: ${lag} bytes${lag > 0 ? ' behind the log head' : ''}`);
+    }
+    lines.push(report.compactionAdvised
+        ? `  log size ${mb(report.totalLogBytes)} is past the ${mb(report.compactionAdvisoryBytes)} point where a cold fold stops fitting the context-injection budget. Run \`fraim learning usage prune\` to consolidate processed events into the snapshot and checkpoint backup, then clear them independently of retention.`
+        : `  log size ${mb(report.totalLogBytes)} of ${mb(report.compactionAdvisoryBytes)} before compaction is worth running.`);
+    if (report.rebuildAdvised)
+        lines.push('', REBUILD_NOTE);
+    return lines;
+}
+function verificationSummaryLines(report) {
+    return [
+        `Usage record: ${report.entries} entries at ${report.snapshotPath}`,
+        `Current model: ${report.currentModel ?? 'unknown'}`,
+        ...(report.evidence ? [`Evidence: ${report.evidence.status}. ${report.evidence.observations.join(', ')}.`,
+            ...(report.evidence.recovery ? [`Recovered from ${report.evidence.recovery}; primary replacement was not persisted by this read.`] : [])] : []),
+        '',
+        'Identity',
+        report.twinPairs.length === 0
+            ? '  none: no lesson is tracked under two keys'
+            : `  ${report.twinPairs.length} lessons tracked under two keys. Its offers and its firings are on different records, so every count about it is partial.`,
+        report.unmatchedTitleKeys.length === 0
+            ? '  every title-keyed record has been matched or has no twin'
+            : `  ${report.unmatchedTitleKeys.length} title-keyed records have no id twin. Expected for entries no tier has stamped; run \`stamp-ids\` to reduce it.`,
+        '',
+        'Counters',
+        '  Offer accounting is retired; historical offer balance is not assessed.',
+        report.caseVariantModelBuckets.length === 0
+            ? '  none: no model bucket differs only by case'
+            : `  ${report.caseVariantModelBuckets.length} model buckets differ only by case. Historical outcome attribution uses multiple spellings of one model; no current effectiveness conclusion is drawn.`,
+        report.unknownModelAttribution.length === 0
+            ? '  none: every firing carries the model that attested it'
+            : `  ${report.unknownModelAttribution.length} entries have incomplete model attribution. Affected model conclusions are withheld. The cause is not established; unknown historical attribution cannot be inferred from the current model.`,
+        '',
+        'Storage',
+    ];
+}
+function runVerify(options) {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const report = (0, learning_usage_verify_1.buildVerifyReport)({
+        snapshotPath: (0, learning_usage_store_1.resolveUsageStorePath)(),
+        limits: (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot),
+        currentModel: options.model ?? undefined,
+    });
+    emit(report, options.json, () => {
+        const lines = verificationSummaryLines(report);
+        lines.push(...verificationStorageLines(report));
+        lines.push('', 'Nothing here blocks anything. This is what the record can and cannot currently prove.');
+        return lines.join('\n');
+    });
+}
+function printHelp() {
+    process.stdout.write([
+        'Usage: fraim learning usage <command> [options]',
+        '',
+        'Commands:',
+        '  report           Show last-known historical outcomes',
+        '  stamp-ids        Add stable Id lines to learning entries',
+        '  prune            Apply usage-log retention limits',
+        '  verify           Report what the usage record can and cannot prove',
+        '',
+    ].join('\n'));
+}
+function runUsageCommand(argv) {
+    const parsed = parseArgv(argv);
+    COMMANDS[parsed.command](parsed.options);
+}

package/dist/src/core/fraim-config-schema.generated.js

@@ -222,9 +222,6 @@ exports.FRAIM_CONFIG_SCHEMA = {
                         },
                         "offerLogLimit": {
                             "kind": "number"
-                        },
-                        "retirementOfferThreshold": {
-                            "kind": "number"
                         }
                     }
                 }
@@ -709,7 +706,6 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "learning.usage",
     "learning.usage.firingLogLimit",
     "learning.usage.offerLogLimit",
-    "learning.usage.retirementOfferThreshold",
     "artifactPaths",
     "artifactPaths.evidence",
     "artifactPaths.rawLearnings",

package/dist/src/core/utils/local-registry-resolver.js

@@ -50,6 +50,7 @@ class LocalRegistryResolver {
     constructor(options) {
         this.workspaceRoot = options.workspaceRoot;
         this.effectiveFraimDir = options.effectiveFraimDir;
+        this.userLevelOnly = options.userLevelOnly ?? false;
         this.remoteContentResolver = options.remoteContentResolver;
         this.parser = new inheritance_parser_1.InheritanceParser(options.maxDepth);
         this.shouldFilter = options.shouldFilter;
@@ -87,7 +88,14 @@ class LocalRegistryResolver {
      * Check if a local override exists for the given path
      */
     hasLocalOverride(path) {
-        return (0, fs_1.existsSync)(this.getOverridePath(path));
+        return !this.userLevelOnly && (0, fs_1.existsSync)(this.getOverridePath(path));
+    }
+    /** Whether an effective personalized layer should replace a remote baseline response. */
+    hasPersonalizedOverride(path) {
+        return this.hasLocalOverride(path)
+            || this.readManagerLocalOverlayFile(path) !== null
+            || this.readManagerOverlayFile(path) !== null
+            || this.readOrgOverlayFile(path) !== null;
     }
     /**
      * Find the actual relative path for a registry item by searching subdirectories.
@@ -108,11 +116,11 @@ class LocalRegistryResolver {
             // `jobs/<category>/<name>.md`, so the job was reported not found even
             // though the file existed.
             const searchRoots = [
-                this.getFraimPath('personalized-employee', dir),
+                ...(!this.userLevelOnly ? [this.getFraimPath('personalized-employee', dir)] : []),
                 (0, path_1.join)(this.managerLocalRoot, dir),
                 (0, path_1.join)(this.managerCacheRoot, dir),
                 (0, path_1.join)(this.orgCacheRoot, dir),
-                (0, path_1.join)(this.workspaceRoot, 'registry', dir),
+                ...(!this.userLevelOnly ? [(0, path_1.join)(this.workspaceRoot, 'registry', dir)] : []),
                 // Installed projects discover categorized capabilities in machine catalogs.
                 this.getSyncedCatalogRoot('ai-employee', dir),
                 ...(type !== 'skills' ? [this.getSyncedCatalogRoot('ai-manager', dir)] : []),
@@ -326,6 +334,8 @@ class LocalRegistryResolver {
         }
     }
     readWorkspaceRegistryFile(path) {
+        if (this.userLevelOnly)
+            return null;
         const normalizedPath = path.replace(/\\/g, '/').replace(/^\/+/, '');
         const registryRoot = (0, path_1.join)(this.workspaceRoot, 'registry');
         const registryPath = (0, path_1.join)(registryRoot, ...normalizedPath.split('/'));