fraim 2.0.346 → 2.0.348

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

@@ -8,6 +8,7 @@ exports.ownerPath = ownerPath;
 exports.validateOwner = validateOwner;
 exports.ownerKey = ownerKey;
 exports.assertSameOwner = assertSameOwner;
+exports.assertLearningTargetPath = assertLearningTargetPath;
 exports.resolveOwnerHome = resolveOwnerHome;
 exports.ownerArtifactPath = ownerArtifactPath;
 exports.configuredArtifactPath = configuredArtifactPath;
@@ -34,6 +35,16 @@ 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);

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');
+    }
+}