fraim 2.0.345 → 2.0.348

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

@@ -0,0 +1,162 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeLearningOutcomes = void 0;
+exports.recordOutcomeAssessment = recordOutcomeAssessment;
+exports.readOutcomeAssessments = readOutcomeAssessments;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const learning_usage_store_1 = require("../../../src/local-mcp-server/learning-usage-store");
+const owner_identity_1 = require("./owner-identity");
+const proposal_queue_1 = require("./proposal-queue");
+const completion_state_1 = require("./completion-state");
+const artifact_paths_1 = require("../artifact-paths");
+const learning_source_record_1 = require("../learning-usage/learning-source-record");
+const corpus_audit_1 = require("./corpus-audit");
+const outcome_types_1 = require("./outcome-types");
+var outcome_types_2 = require("./outcome-types");
+Object.defineProperty(exports, "summarizeLearningOutcomes", { enumerable: true, get: function () { return outcome_types_2.summarizeLearningOutcomes; } });
+const { learningEntryBlocks, learningEntryMetadata, learningEntryIdentity } = require('./entry-format');
+function resolveAssessmentHomes(run, input, options) {
+    const homes = new Map();
+    for (const owner of [run.owner, input.learning.owner, ...input.sourceRefs.map(source => source.owner)]) {
+        const home = options.resolveHome(owner);
+        (0, owner_identity_1.assertSameOwner)(owner, home.owner);
+        homes.set((0, owner_identity_1.ownerKey)(owner), home);
+    }
+    return homes;
+}
+function resolveAssessmentSources(input, homes) {
+    return input.sourceRefs.map(ref => {
+        const home = homes.get((0, owner_identity_1.ownerKey)(ref.owner));
+        const originalFile = (0, owner_identity_1.configuredArtifactPath)(home, node_path_1.default.join((0, owner_identity_1.ownerArtifactRoot)(home), ref.relativePath));
+        let file = originalFile;
+        if (!node_fs_1.default.existsSync(file)) {
+            const paths = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+            const archive = (0, completion_state_1.sourcePathKey)(node_path_1.default.dirname(file)) === (0, completion_state_1.sourcePathKey)(paths.raw) ? paths.archiveRaw
+                : (0, completion_state_1.sourcePathKey)(node_path_1.default.dirname(file)) === (0, completion_state_1.sourcePathKey)(paths.retrospectives) ? paths.archiveRetrospectives : undefined;
+            if (archive)
+                file = (0, owner_identity_1.configuredArtifactPath)(home, node_path_1.default.join(archive, node_path_1.default.basename(file)));
+        }
+        return { ref, home, file, archived: file !== originalFile };
+    });
+}
+function verifyAssessmentLearning(input, home, target) {
+    if (!node_fs_1.default.existsSync(target) || node_fs_1.default.lstatSync(target).isSymbolicLink())
+        throw new Error('assessment-learning-missing');
+    const entries = learningEntryBlocks(node_fs_1.default.readFileSync(target, 'utf8')).map(block => ({ ...block, ...learningEntryIdentity(block.text) }));
+    if (entries.some(block => block.ambiguous))
+        throw new Error('assessment-learning-missing-or-ambiguous');
+    const blocks = entries.filter(block => block.id === input.learning.entryId);
+    if (blocks.length !== 1)
+        throw new Error('assessment-learning-missing-or-ambiguous');
+    const domain = blocks[0].text.match(/^\*\*Domain\*\*:\s*([^\r\n]+)$/m)?.[1].trim();
+    (0, owner_identity_1.assertLearningTargetPath)(input.learning, domain);
+    const occurrences = (0, corpus_audit_1.collectLearningCorpus)([home], [input.learning.learningSubject]).entries.filter(entry => {
+        if (entry.ref.entryId !== input.learning.entryId)
+            return false;
+        try {
+            (0, owner_identity_1.assertLearningTargetPath)({ ...entry.ref, learningSubject: input.learning.learningSubject });
+            return true;
+        }
+        catch {
+            return false;
+        } // Shared org guidance is a distinct subject in a Project home.
+    });
+    if (occurrences.length !== 1)
+        throw new Error('assessment-learning-identity-ambiguous');
+    const metadata = learningEntryMetadata(blocks[0].text);
+    const introduced = metadata['First synthesized'] || metadata['First recorded'];
+    if (!introduced || !Number.isFinite(Date.parse(introduced)))
+        throw new Error('guidance-date-unavailable');
+    if (Date.parse(introduced) > Date.parse(input.observedAt) || Date.parse(introduced) > Date.parse(input.guidanceExistedAt))
+        throw new Error('guidance-after-incident');
+}
+function verifyAssessmentSources(sources, state) {
+    for (const source of sources) {
+        if (!node_fs_1.default.existsSync(source.file) || node_fs_1.default.lstatSync(source.file).isSymbolicLink())
+            throw new Error('assessment-source-unavailable');
+        const body = node_fs_1.default.readFileSync(source.file, 'utf8');
+        // Normal archival only fills this existing frontmatter field; source identity and all evidence bytes remain bound.
+        const originalBody = source.archived ? body.replace(/^(synthesized:)[^\r\n]*/m, '$1') : body;
+        if ((0, proposal_queue_1.hashContent)(body) !== source.ref.sha256 && (0, proposal_queue_1.hashContent)(originalBody) !== source.ref.sha256)
+            throw new Error('assessment-source-hash-conflict');
+        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, source.file, (0, owner_identity_1.ownerArtifactRoot)(source.home), source.home.contentRoot);
+        if (parsed.status !== 'valid')
+            throw new Error(`invalid-assessment-source: ${parsed.reason}`);
+        if (parsed.record.sourceId !== source.ref.sourceId
+            || !(0, completion_state_1.sourceAuthorAllowed)(state, parsed.record.author, source.home.owner))
+            throw new Error('invalid-assessment-source');
+    }
+}
+function replayAssessment(run, state, pending, prior) {
+    if (pending?.digest === prior.digest)
+        run.commitOutcomeAssessment(prior.digest, state.sequence);
+    return prior;
+}
+function commitAssessment(transaction) {
+    const { run, input, state, pending, options, home, target, sources } = transaction;
+    // File locks also coordinate callers with different Manager coordination paths.
+    // Refresh after acquiring them, before recording any recoverable intent.
+    const prior = (0, learning_usage_store_1.readAssessedOutcomes)(undefined, { key: (0, outcome_types_1.assessmentKey)(input) })[0];
+    if (prior && (0, outcome_types_1.assessmentContent)(prior) === (0, outcome_types_1.assessmentContent)(input))
+        return replayAssessment(run, state, pending, prior);
+    const reservations = (0, completion_state_1.readRunReservations)([run.directory, ...options.runDirectories], run.file);
+    if (reservations.assessmentKeys.includes((0, outcome_types_1.assessmentKey)(input)))
+        throw new Error('assessment-reserved-by-pending-run');
+    if ((prior?.digest ?? null) !== input.expectedPriorDigest)
+        throw new Error('stale-assessment-conflict');
+    verifyAssessmentLearning(input, home, target);
+    verifyAssessmentSources(sources, state);
+    const record = pending ?? { ...structuredClone(input), revision: (prior?.revision ?? 0) + 1,
+        assessedAt: new Date().toISOString(), reviewer: state.reviewer, runId: state.runId, digest: '' };
+    record.digest = (0, outcome_types_1.outcomeAssessmentDigest)(record);
+    if (!pending)
+        run.prepareOutcomeAssessment(record, state.sequence, sources.map(source => source.file));
+    options.afterStage?.('assessment-prepared');
+    const persisted = (0, learning_usage_store_1.recordAssessedOutcome)(record);
+    options.afterStage?.('assessment-stored');
+    run.commitOutcomeAssessment(record.digest, run.read().sequence);
+    options.afterStage?.('assessment-committed');
+    return persisted;
+}
+function withAssessmentFileLocks(transaction) {
+    const files = [...new Set([transaction.target, ...transaction.sources.map(source => source.file)])].sort();
+    const locked = (index) => index < files.length
+        ? (0, proposal_queue_1.withFileLock)(files[index], () => locked(index + 1)) : commitAssessment(transaction);
+    return locked(0);
+}
+/** Commit semantic judgments supplied by Sleep; no prose, title or retrospective-ID matching. */
+function recordOutcomeAssessment(run, input, expectedSequence, options) {
+    (0, outcome_types_1.validateOutcomeAssessmentInput)(input);
+    (0, owner_identity_1.assertLearningTargetPath)(input.learning);
+    return (0, proposal_queue_1.withFileLock)(options.coordinationFile || node_path_1.default.join(run.directory, 'owner-application'), () => {
+        const state = run.read();
+        if (!Number.isInteger(expectedSequence) || state.sequence !== expectedSequence)
+            throw new Error('stale-sequence');
+        if (state.finalization || state.checkpoint?.receipt.finalizationState === 'pending')
+            throw new Error('finalization-started');
+        const homes = resolveAssessmentHomes(run, input, options);
+        if (!(0, completion_state_1.sourceAuthorAllowed)(state, input.learning.learningSubject, input.learning.owner))
+            throw new Error('assessment-subject-conflict');
+        const prior = (0, learning_usage_store_1.readAssessedOutcomes)(undefined, { key: (0, outcome_types_1.assessmentKey)(input) })[0];
+        const pending = state.pendingOutcomeAssessments?.find(record => (0, outcome_types_1.assessmentKey)(record) === (0, outcome_types_1.assessmentKey)(input));
+        if (pending && (0, outcome_types_1.assessmentContent)(pending) !== (0, outcome_types_1.assessmentContent)(input))
+            throw new Error('pending-assessment-conflict');
+        // Exact replay remains valid after sources have archived and detailed evidence expires.
+        if (prior && (0, outcome_types_1.assessmentContent)(prior) === (0, outcome_types_1.assessmentContent)(input))
+            return replayAssessment(run, state, pending, prior);
+        if ((prior?.digest ?? null) !== input.expectedPriorDigest)
+            throw new Error('stale-assessment-conflict');
+        const home = homes.get((0, owner_identity_1.ownerKey)(input.learning.owner));
+        const target = (0, owner_identity_1.ownerArtifactPath)(home, input.learning.relativePath);
+        const sources = resolveAssessmentSources(input, homes);
+        return withAssessmentFileLocks({ run, input, state, pending, options, home, target, sources });
+    });
+}
+/** Durable usage history outlives transient run journals, receipts and original source retention. */
+function readOutcomeAssessments(homes, principal) {
+    return (0, learning_usage_store_1.readAssessedOutcomes)(undefined, { owners: homes.map(home => home.owner), principal });
+}

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

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

package/dist/registry/scripts/learning/owner-identity.js

@@ -0,0 +1,148 @@
+"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.assertLearningTargetPath = assertLearningTargetPath;
+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');
+}
+/** Shared authored-family identity check. Handwritten entries can omit Domain metadata. */
+function assertLearningTargetPath(ref, domain) {
+    const subject = ref.owner.level === 'Org' ? 'org' : ref.learningSubject;
+    if (!subject || !/^[a-zA-Z0-9@._+-]+$/.test(subject))
+        throw new Error('learning-subject-required');
+    const escaped = subject.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = ref.relativePath.match(new RegExp(`^learnings/${escaped}-((?:[a-z][a-z-]*-)?)(preferences|mistake-patterns|validated-patterns|manager-coaching)(\\.cold)?\\.md$`));
+    if (!match || (domain !== undefined && match[1] !== (domain === 'global' ? '' : domain + '-')))
+        throw new Error('domain-target-mismatch: learning subject, domain and family must match its file');
+}
+/** 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/registry/scripts/learning/proposal-queue.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashContent = void 0;
+exports.atomicWrite = atomicWrite;
+exports.withFileLock = withFileLock;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const hashContent = (text) => (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
+exports.hashContent = hashContent;
+function atomicWrite(file, text) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const temporary = file + '.' + (0, node_crypto_1.randomUUID)() + '.tmp';
+    try {
+        node_fs_1.default.writeFileSync(temporary, text, { encoding: 'utf8', flag: 'wx' });
+        const fd = node_fs_1.default.openSync(temporary, 'r+');
+        try {
+            node_fs_1.default.fsyncSync(fd);
+        }
+        finally {
+            node_fs_1.default.closeSync(fd);
+        }
+        node_fs_1.default.renameSync(temporary, file);
+    }
+    finally {
+        if (node_fs_1.default.existsSync(temporary))
+            node_fs_1.default.unlinkSync(temporary);
+    }
+}
+function withFileLock(file, fn) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    let fd;
+    try {
+        fd = node_fs_1.default.openSync(file + '.lock', 'wx');
+    }
+    catch {
+        // Serialize recovery so two contenders cannot unlink each other's new lock.
+        let recovery;
+        try {
+            recovery = node_fs_1.default.openSync(file + '.lock.recovery', 'wx');
+        }
+        catch {
+            throw new Error('busy: lock recovery is already in progress');
+        }
+        try {
+            const owner = JSON.parse(node_fs_1.default.readFileSync(file + '.lock', 'utf8'));
+            let stale = false;
+            if (owner.host === (0, node_os_1.hostname)() && Number.isInteger(owner.pid) && owner.pid > 0) {
+                try {
+                    process.kill(owner.pid, 0);
+                }
+                catch (error) {
+                    stale = error.code === 'ESRCH';
+                }
+            }
+            if (!stale)
+                throw new Error('busy');
+            node_fs_1.default.unlinkSync(file + '.lock');
+            fd = node_fs_1.default.openSync(file + '.lock', 'wx');
+        }
+        catch {
+            throw new Error('busy: reconcile outstanding lock before retry');
+        }
+        finally {
+            node_fs_1.default.closeSync(recovery);
+            node_fs_1.default.unlinkSync(file + '.lock.recovery');
+        }
+    }
+    node_fs_1.default.writeFileSync(fd, JSON.stringify({ pid: process.pid, host: (0, node_os_1.hostname)(), at: new Date().toISOString() }));
+    try {
+        return fn();
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+        node_fs_1.default.unlinkSync(file + '.lock');
+    }
+}