fraim-hub 2.0.340 → 2.0.341

package/dist/src/core/proposal-set-contract.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * Proposal Set Contract Validation (Issue #1857)
+ *
+ * The Hub renders the manager's learning review batch from this payload. Before
+ * this contract it rendered from prose: `tfParsePendingProposals` scanned an
+ * employee turn for a `## Pending Review` heading and `#### [P-LEVEL]` lines that
+ * no job or skill was ever instructed to emit, so the review surface #1876
+ * shipped rendered nothing for a real run.
+ *
+ * Two findings from the design spikes shape what this file checks.
+ *
+ * First, failing loudly is the behavior under test. A wire-shaped proposal whose
+ * field names did not match what the card reads rendered a card with its body
+ * silently missing and threw nothing. A contract that rejects the payload and
+ * names the field is recoverable; one that renders a degraded card is not.
+ *
+ * Second, the size caps are measured rather than chosen. Across 4,779 recorded
+ * `seekMentoring` calls in the raw host archives, the largest evidence object this
+ * system has ever carried is 6,044 bytes (median 506, p95 1,859). A proposal costs
+ * roughly 700 bytes once its 80-word reader budget and identity fields are counted,
+ * so a proposal set is the largest payload this channel will carry and the bound
+ * has to be explicit rather than discovered in production.
+ *
+ * Lives in src/core so the local MCP proxy, the Hub and the evals import the same
+ * validator, per architecture 4.2.1 — the same pattern as `handoff-contracts.ts`,
+ * `quality-evidence.ts` and `test-evidence-contract.ts`.
+ *
+ * Primary call site: src/local-mcp-server/stdio-server.ts seekMentoring handler.
+ * The Hub keeps its own normalizer as well; the two do different jobs. This one
+ * tells the agent what to fix in one round. The normalizer protects the render
+ * from a payload that reached the Hub by some other path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SUPPRESSED_PER_SET = exports.MAX_PROPOSALS_PER_SET = exports.PROPOSAL_CHANGE_TYPES = exports.SUPPRESSION_KINDS = exports.PROPOSAL_RUN_SCOPES = void 0;
+exports.rankProposals = rankProposals;
+exports.validateProposalSet = validateProposalSet;
+/** Scopes a run can be asked for. Decides which corpus an approval lands in. */
+exports.PROPOSAL_RUN_SCOPES = ['manager', 'project', 'org'];
+/** How a claim came to be suppressed, so R7's report does not describe a
+ *  claim the manager promoted to a rule as one they refused. */
+exports.SUPPRESSION_KINDS = ['refused', 'superseded'];
+/** What kind of change a proposal makes to the corpus. */
+exports.PROPOSAL_CHANGE_TYPES = ['new', 'update', 'cold'];
+/**
+ * Maximum proposals in one set. Derived from the measured envelope above, not
+ * chosen: at roughly 700 bytes per proposal this keeps a full set inside twice
+ * the largest evidence payload the channel has ever carried. Raising it should
+ * follow a re-measurement, which `test-1857-proposal-set-contract.ts` pins.
+ */
+exports.MAX_PROPOSALS_PER_SET = 12;
+/** Maximum suppressed entries reported in one batch. Each is a single line. */
+exports.MAX_SUPPRESSED_PER_SET = 25;
+/** Reader-field length bound. The authoring skill already budgets 80 words across
+ *  title and the four reader values; this is the byte-level backstop. */
+const MAX_READER_FIELD = 600;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isText = (v) => typeof v === 'string' && v.trim().length > 0;
+/**
+ * Fields that are audit metadata rather than review material. R10 is an invariant
+ * about influence, not storage: the manager's card is not a place for a score, a
+ * source path or an originating job to arrive by accident. Rejecting them at the
+ * boundary is cheaper than auditing every render site later.
+ */
+const FORBIDDEN_PROPOSAL_FIELDS = ['trace', 'sourceRefs', 'sourceHashes', 'content', 'score'];
+function validateEntry(entry, index, errors) {
+    const at = `evidence.proposalSet.proposals[${index}]`;
+    if (!isObject(entry)) {
+        errors.push(`${at} must be an object`);
+        return;
+    }
+    for (const field of ['proposalId', 'claimKey', 'family']) {
+        if (!isText(entry[field]))
+            errors.push(`${at}.${field} must be a non-empty string`);
+    }
+    if (!Number.isInteger(entry.revision) || entry.revision < 1) {
+        errors.push(`${at}.revision must be a positive integer`);
+    }
+    for (const field of ['title', 'takeaway']) {
+        if (!isText(entry[field])) {
+            errors.push(`${at}.${field} must be a non-empty string; the card renders it`);
+        }
+        else if (entry[field].length > MAX_READER_FIELD) {
+            errors.push(`${at}.${field} exceeds ${MAX_READER_FIELD} characters`);
+        }
+    }
+    if (entry.example !== undefined && typeof entry.example !== 'string') {
+        errors.push(`${at}.example must be a string when present`);
+    }
+    if (entry.suggestionReason !== undefined) {
+        if (typeof entry.suggestionReason !== 'string') {
+            errors.push(`${at}.suggestionReason must be a string when present`);
+        }
+        else if (entry.suggestionReason.length > MAX_READER_FIELD) {
+            errors.push(`${at}.suggestionReason exceeds ${MAX_READER_FIELD} characters`);
+        }
+    }
+    if (!exports.PROPOSAL_RUN_SCOPES.includes(entry.suggestedLevel)) {
+        errors.push(`${at}.suggestedLevel must be one of ${exports.PROPOSAL_RUN_SCOPES.join(', ')}`);
+    }
+    if (!exports.PROPOSAL_CHANGE_TYPES.includes(entry.changeType)) {
+        errors.push(`${at}.changeType must be one of ${exports.PROPOSAL_CHANGE_TYPES.join(', ')}`);
+    }
+    if (!Number.isInteger(entry.recurrences) || entry.recurrences < 0) {
+        errors.push(`${at}.recurrences must be a non-negative integer`);
+    }
+    for (const field of FORBIDDEN_PROPOSAL_FIELDS) {
+        if (entry[field] !== undefined) {
+            errors.push(`${at}.${field} is audit metadata and must not be sent to the review surface`);
+        }
+    }
+    if (entry.reopening !== undefined) {
+        const r = entry.reopening;
+        const ra = `${at}.reopening`;
+        if (!isObject(r)) {
+            errors.push(`${ra} must be an object`);
+        }
+        else {
+            if (!isText(r.rejectedAt))
+                errors.push(`${ra}.rejectedAt must be a non-empty string`);
+            if (!isText(r.reason)) {
+                errors.push(`${ra}.reason must be a non-empty string; a reopening quotes the original decision`);
+            }
+            if (!Number.isInteger(r.countAtRejection) || r.countAtRejection < 0) {
+                errors.push(`${ra}.countAtRejection must be a non-negative integer`);
+            }
+        }
+    }
+}
+function validateSuppressed(entry, index, errors) {
+    const at = `evidence.proposalSet.suppressed[${index}]`;
+    if (!isObject(entry)) {
+        errors.push(`${at} must be an object`);
+        return;
+    }
+    for (const field of ['claimKey', 'family', 'rejectedAt', 'reason']) {
+        if (!isText(entry[field]))
+            errors.push(`${at}.${field} must be a non-empty string`);
+    }
+    if (!exports.SUPPRESSION_KINDS.includes(entry.kind)) {
+        errors.push(`${at}.kind must be one of ${exports.SUPPRESSION_KINDS.join(', ')}`);
+    }
+    if (!Number.isInteger(entry.newSourceCount) || entry.newSourceCount < 0) {
+        errors.push(`${at}.newSourceCount must be a non-negative integer`);
+    }
+}
+/**
+ * Validates `evidence.proposalSet`. Returns null when valid or absent, or an array
+ * of messages each naming the exact field, so the agent fixes it in one round
+ * rather than guessing.
+ *
+ * Absent is valid: a review phase with nothing to review emits no set. An empty
+ * `proposals` array is also valid and means the same thing, which keeps a run that
+ * suppressed everything able to report its suppressions.
+ */
+/**
+ * Order a batch by accumulated evidence strength (Issue #1857 R3).
+ *
+ * An undecided proposal is not a chore that expires; it comes back, and it comes
+ * back stronger or it does not. A flat list makes every row look equally
+ * deserving of the manager's attention, which is how a claim with eleven
+ * occurrences ends up below one with two because it happened to be authored
+ * later. Ordering is the whole reason "leave it for now" is a position rather
+ * than a deferral: the next batch shows the manager what changed.
+ *
+ * Recurrences is the primary key because it is the accumulated evidence itself.
+ * Growth since the last review breaks ties, so between two claims at the same
+ * count the one that is still happening leads. `proposalId` breaks the remainder,
+ * so the same batch always renders in the same order and a manager re-opening a
+ * run does not find the rows rearranged.
+ *
+ * Applied on the Hub's own read rather than trusted from the agent: the order the
+ * manager sees should not depend on how a model happened to sort its output.
+ */
+function rankProposals(proposals) {
+    const growth = (p) => typeof p.recurrencesAtLastReview === 'number' ? p.recurrences - p.recurrencesAtLastReview : 0;
+    return [...proposals].sort((a, b) => b.recurrences - a.recurrences
+        || growth(b) - growth(a)
+        || a.proposalId.localeCompare(b.proposalId));
+}
+function validateProposalSet(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    const errors = [];
+    if (!isObject(raw)) {
+        return ['evidence.proposalSet must be an object'];
+    }
+    if (!exports.PROPOSAL_RUN_SCOPES.includes(raw.runScope)) {
+        errors.push(`evidence.proposalSet.runScope must be one of ${exports.PROPOSAL_RUN_SCOPES.join(', ')}`);
+    }
+    if (!Array.isArray(raw.proposals)) {
+        errors.push('evidence.proposalSet.proposals must be an array');
+    }
+    else if (raw.proposals.length > exports.MAX_PROPOSALS_PER_SET) {
+        errors.push(`evidence.proposalSet.proposals holds ${raw.proposals.length} entries, past the ` +
+            `${exports.MAX_PROPOSALS_PER_SET} a single batch may carry; present the strongest first and ` +
+            'report the remainder so the manager knows the batch was split');
+    }
+    else {
+        raw.proposals.forEach((entry, index) => validateEntry(entry, index, errors));
+    }
+    if (raw.suppressed !== undefined) {
+        if (!Array.isArray(raw.suppressed)) {
+            errors.push('evidence.proposalSet.suppressed must be an array when present');
+        }
+        else if (raw.suppressed.length > exports.MAX_SUPPRESSED_PER_SET) {
+            errors.push(`evidence.proposalSet.suppressed exceeds ${exports.MAX_SUPPRESSED_PER_SET} entries`);
+        }
+        else {
+            raw.suppressed.forEach((entry, index) => validateSuppressed(entry, index, errors));
+        }
+    }
+    return errors.length > 0 ? errors : null;
+}

package/dist/src/core/run-recovery-state.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeRunStateKey = safeRunStateKey;
+const crypto_1 = require("crypto");
+/** UUIDs retain their documented filenames; other IDs cannot become paths or device names. */
+function safeRunStateKey(id) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)
+        ? id : `id-${(0, crypto_1.createHash)('sha256').update(id).digest('hex')}`;
+}

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

@@ -24,6 +24,7 @@ exports.readOrgBrand = readOrgBrand;
 exports.resolveOrgBrandWriteDir = resolveOrgBrandWriteDir;
 exports.countPreservedLearnings = countPreservedLearnings;
 exports.collectBrainLearningDots = collectBrainLearningDots;
+exports.readRejectedProposals = readRejectedProposals;
 exports.readPreservedLearnings = readPreservedLearnings;
 exports.normalizeLearningDomain = normalizeLearningDomain;
 exports.applyLearningEntryChange = applyLearningEntryChange;
@@ -579,6 +580,34 @@ function pendingL0SortKey(fileName) {
     const timestamp = fileName.match(/\d{4}-\d{2}-\d{2}(?:T\d{2}-\d{2}-\d{2})?/);
     return timestamp?.[0] || fileName;
 }
+/**
+ * Issue #1857 R11: how many proposals are waiting for the manager's review.
+ *
+ * This counts directory entries and nothing else. It does not open a proposal, and
+ * deliberately has no access to one: R10 is an invariant about influence rather
+ * than storage, so the employee learns that a backlog exists and which job clears
+ * it, never what any pending claim says.
+ *
+ * The same shape as the pending-L0 line it sits beside, for the same reason: a
+ * count plus the job that clears it is actionable; a list of contents is not.
+ */
+function countPendingProposals(roots, resolvedUserId) {
+    let total = 0;
+    for (const base of [roots.repoLearningsBase, roots.globalPersonalBase]) {
+        if (!base)
+            continue;
+        const queueDir = (0, path_1.join)(base, 'review-queue', resolvedUserId);
+        if (!(0, fs_1.existsSync)(queueDir))
+            continue;
+        try {
+            total += (0, fs_1.readdirSync)(queueDir).filter((name) => name.endsWith('.json')).length;
+        }
+        catch {
+            // An unreadable queue is not worth failing a job's startup over.
+        }
+    }
+    return total;
+}
 function collectPendingL0SourceFiles(workspaceRoot, resolvedUserId, roots) {
     const sources = [];
     const rawPath = (0, path_1.join)(roots.repoLearningsBase, 'raw');
@@ -823,7 +852,11 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
     const l0RetroCount = pendingL0Sources.filter(source => source.kind === 'retrospective').length;
     const hasL2 = l2Files.length > 0;
     const hasL1 = l1Files.length > 0;
-    const hasContent = hasL2 || hasL1 || l0CoachingCount > 0 || l0RetroCount > 0;
+    // Issue #1857 R11. Counted before the gate on purpose: a manager with a full
+    // review queue and an empty corpus is exactly the case where the backlog most
+    // needs saying, and computing it after the early return would silence it there.
+    const pendingProposals = countPendingProposals(roots, resolvedUserId);
+    const hasContent = hasL2 || hasL1 || l0CoachingCount > 0 || l0RetroCount > 0 || pendingProposals > 0;
     if (!hasContent)
         return '';
     let section = forJob
@@ -862,6 +895,13 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
         }
         section += '\n';
     }
+    // Issue #1857 R11. The count, never the content: an unapproved proposal does
+    // not influence this job, and the employee is told only that the manager has a
+    // backlog and which job clears it.
+    if (pendingProposals > 0) {
+        const plural = pendingProposals !== 1;
+        section += `${pendingProposals} proposal${plural ? 's are' : ' is'} waiting for your manager's review; run \`sleep-on-learnings\` to review ${plural ? 'them' : 'it'}.\n\n`;
+    }
     const coachPresent = resolved.coachPresent;
     if (forJob) {
         if (hasL2 || hasL1) {
@@ -1825,6 +1865,93 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
     flush();
     return out;
 }
+/**
+ * Read the rejection history a sleep run writes on completion.
+ *
+ * The file is a sequence of `<!-- sleep-rejection:run:action:revision -->` blocks,
+ * each holding a heading, the manager's reason, an optional revisit condition and
+ * the rejected proposal as JSON. `run-application.ts` writes it; this reads it
+ * back without changing a byte, because the file is also a synthesis input and a
+ * reader that rewrote it would corrupt the next run's history.
+ *
+ * A malformed block is skipped rather than failing the whole read: the manager
+ * losing the view of every rejection because one block is damaged is worse than
+ * the view missing that one.
+ */
+function readRejectedProposals(workspaceRoot, userId) {
+    const roots = getLearningRoots(workspaceRoot);
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
+    if (!resolvedUserId)
+        return [];
+    const out = [];
+    const seen = new Set();
+    const headingRe = /^## (Rejected|Superseded): (.+)$/m;
+    const reasonRe = /^Reason: (.+)$/m;
+    const revisitRe = /^Revisit when: (.+)$/m;
+    const jsonRe = /```json\r?\n([\s\S]*?)\r?\n```/;
+    for (const base of [roots.repoLearningsBase, roots.globalPersonalBase, roots.managerCacheBase]) {
+        if (!base)
+            continue;
+        const file = (0, path_1.join)(base, `${resolvedUserId}-rejected-proposals.md`);
+        if (!(0, fs_1.existsSync)(file))
+            continue;
+        let body;
+        try {
+            body = (0, fs_1.readFileSync)(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const displayPath = file.split('\\').join('/');
+        for (const raw of body.split('<!-- sleep-rejection:').slice(1)) {
+            const end = raw.indexOf('<!-- /sleep-rejection -->');
+            const chunk = end >= 0 ? raw.slice(0, end) : raw;
+            const marker = chunk.slice(0, Math.max(0, chunk.indexOf('-->')));
+            const parts = marker.trim().split(':');
+            const heading = headingRe.exec(chunk);
+            const reason = reasonRe.exec(chunk);
+            const revisit = revisitRe.exec(chunk);
+            const json = jsonRe.exec(chunk);
+            if (!heading || !reason)
+                continue;
+            let proposal = {};
+            if (json) {
+                try {
+                    proposal = JSON.parse(json[1]);
+                }
+                catch {
+                    // Keep the human-readable half; the JSON only enriches it.
+                }
+            }
+            const decision = (proposal.decision || {});
+            const content = (proposal.content || {});
+            const trace = (content.trace || {});
+            const claimKey = typeof proposal.claimKey === 'string' && proposal.claimKey
+                ? 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.
+            const key = `${claimKey}:${String(decision.at || '')}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({
+                claimKey,
+                title: heading[2].trim(),
+                reason: reason[1].trim(),
+                ...(revisit ? { revisitCondition: revisit[1].trim() } : {}),
+                // The heading and the stored decision agree; the heading is what a
+                // manager reading the file sees, so it is the one that governs here.
+                kind: heading[1] === 'Superseded' || decision.kind === 'superseded' ? 'superseded' : 'refused',
+                rejectedAt: typeof decision.at === 'string' ? decision.at : '',
+                ...(typeof trace.recurrences === 'number' ? { recurrencesAtRejection: trace.recurrences } : {}),
+                displayPath,
+            });
+        }
+    }
+    // Newest first: the manager is most often checking what they just said no to.
+    return out.sort((a, b) => String(b.rejectedAt).localeCompare(String(a.rejectedAt)));
+}
 function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine') {
     const roots = getLearningRoots(workspaceRoot);
     const threshold = getScoreThreshold(workspaceRoot);

package/dist/src/local-mcp-server/learning-usage-eligibility.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelAttributionIncomplete = modelAttributionIncomplete;
+exports.countEvidenceProblem = countEvidenceProblem;
+exports.usageEvidenceExclusions = usageEvidenceExclusions;
+const learning_usage_store_1 = require("./learning-usage-store");
+const validCount = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+/** Missing attribution is unknown, including a known bucket beside unattributed history. */
+function modelAttributionIncomplete(record) {
+    const buckets = [record.offered.byModel, record.fired.byModel];
+    if (buckets.some(map => !map || Object.entries(map).some(([name, n]) => !validCount(n) || !(0, learning_usage_store_1.normalizeModelName)(name) || (0, learning_usage_store_1.normalizeModelName)(name) !== name)))
+        return true;
+    return Object.values(record.offered.byModel).reduce((a, b) => a + b, 0) !== record.offered.total
+        || Object.values(record.fired.byModel).reduce((a, b) => a + b, 0)
+            !== record.fired.byOutcome.applied + record.fired.byOutcome.prevented;
+}
+/** Validate counts independently of a cached integrity flag. Never alter the record. */
+function countEvidenceProblem(record, offersEraStart) {
+    const counts = [record.offered.total, record.offered.aboveThreshold, record.fired.total,
+        ...Object.values(record.offered.byModel), ...Object.values(record.fired.byModel),
+        ...Object.values(record.fired.byOutcome)];
+    if (counts.some(n => !validCount(n)) || learning_usage_store_1.FIRING_OUTCOMES.some(outcome => !validCount(record.fired.byOutcome[outcome]))
+        || record.offered.aboveThreshold > record.offered.total
+        || Object.values(record.fired.byOutcome).reduce((a, b) => a + b, 0) !== record.fired.total) {
+        return 'Usage counters are inconsistent.';
+    }
+    const violation = record.integrity ?? (0, learning_usage_store_1.integrityViolation)(record, offersEraStart);
+    if (!offersEraStart && record.offered.total > 0 && record.fired.total > record.offered.total) {
+        return 'Excess uses lack provenance establishing the offer-recording era.';
+    }
+    return violation ? violation.detail : null;
+}
+/** Read-time exclusions follow the actual record, never ambient UI or model state. */
+function usageEvidenceExclusions(store) {
+    const excluded = new Map();
+    for (const key of store.evidence?.excludedKeys ?? [])
+        excluded.set(key, 'Unreadable usage record.');
+    const byTitle = new Map();
+    for (const record of Object.values(store.entries)) {
+        const problem = countEvidenceProblem(record, store.offersEraStart);
+        if (store.evidence?.status === 'unavailable')
+            excluded.set(record.key, 'Usage history is unavailable.');
+        else if (problem)
+            excluded.set(record.key, problem);
+        if (!record.fileType)
+            continue;
+        for (const title of record.titles) {
+            const titleKey = (0, learning_usage_store_1.titleUsageKey)(record.fileType, title);
+            byTitle.set(titleKey, [...new Set([...(byTitle.get(titleKey) ?? []), record.key])]);
+        }
+    }
+    for (const keys of byTitle.values()) {
+        if (keys.length > 1 && keys.some(key => key.startsWith('T:'))) {
+            for (const key of keys)
+                excluded.set(key, 'Ambiguous duplicate usage identity.');
+        }
+    }
+    return excluded;
+}

package/dist/src/local-mcp-server/learning-usage-projection.js

@@ -15,6 +15,7 @@ exports.resolveCurrentModel = resolveCurrentModel;
  * Nothing here writes.
  */
 const learning_usage_store_1 = require("./learning-usage-store");
+const learning_usage_eligibility_1 = require("./learning-usage-eligibility");
 function toLookupValue(record) {
     return {
         key: record.key,
@@ -24,7 +25,7 @@ function toLookupValue(record) {
         firedTotalAttestations: record.fired.total,
         lastFired: record.fired.lastFiredAt,
         lastOffered: record.offered.lastOfferedAt,
-        firedUnder: Object.keys(record.fired.byModel),
+        firedUnder: (0, learning_usage_eligibility_1.modelAttributionIncomplete)(record) ? undefined : Object.keys(record.fired.byModel),
         byOutcome: record.fired.byOutcome,
         log: record.fired.log,
     };
@@ -36,7 +37,10 @@ function toLookupValue(record) {
  */
 function buildUsageLookup(store) {
     const lookup = new Map();
+    const excluded = (0, learning_usage_eligibility_1.usageEvidenceExclusions)(store);
     for (const record of Object.values(store.entries)) {
+        if (excluded.has(record.key))
+            continue;
         const value = toLookupValue(record);
         lookup.set(record.key, value);
         if (record.fileType) {