@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/autonomy.js

@@ -0,0 +1,151 @@
+/**
+ * Which scheduler proposals may run themselves, and which wait for a person.
+ *
+ * The scheduler already decided WHAT is due (architecture §12); this decides
+ * WHO gets to say yes to it. Keeping the two apart is the point: `scheduler.ts`
+ * can be read as "what does the log say is owed" without also encoding trust,
+ * and this file can be read as trust alone.
+ *
+ * It enacts nothing. No dispatch, no worktree, no event — the same doctrine
+ * `daemon.ts` states for the scheduler ("never dispatches an agent, never
+ * merges, never writes to a worktree") and `wave next` follows: compute, hand
+ * back, let the caller act. `smith scheduler admit` prints this and stops, so
+ * the classification can be read, disagreed with, and diffed before anything
+ * moves.
+ *
+ * EVERY RULE HERE CAN ONLY DENY. There is no branch that promotes a proposal
+ * the policy did not already name, so the answer to "what can run without me?"
+ * is the whitelist in scheduler.yml, not this code. A reader who trusts that
+ * sentence never has to audit the file to bound the blast radius, which is the
+ * only reason auto-dispatch is safe to have at all.
+ *
+ * Two consequences worth stating because they are easy to get backwards:
+ *
+ *   - A recheck is whitelisted BY REASON, never by confidence. A
+ *     `RecheckProposal.confidence` is the completed task's confidence, and a
+ *     low one is why the recheck exists at all (`proposeRechecks`:
+ *     `taskConfidence < policy.confidenceThreshold` -> 'low-confidence').
+ *     Applying `MaintenanceProposal`'s floor to it would hold back precisely
+ *     the rechecks that matter and wave through the routine ones. The two
+ *     fields share a name and mean opposite things.
+ *   - The security keywords are crosscheck.yml's list, passed in rather than
+ *     copied, so promoting a word to security-sensitive moves the cross-check
+ *     trigger and this gate together. Matching is case-insensitive substring,
+ *     as `plan_quorum` already matches, and it over-matches on purpose:
+ *     "author" contains "auth". A false positive costs one operator tick; a
+ *     false negative auto-runs a change to an auth path.
+ */
+function firstSecurityHit(fields, keywords) {
+    for (const { field, value } of fields) {
+        const haystack = value.toLowerCase();
+        for (const keyword of keywords) {
+            const needle = keyword.toLowerCase();
+            if (needle.length > 0 && haystack.includes(needle))
+                return { field, value, keyword };
+        }
+    }
+    return null;
+}
+function subjectOf(proposal) {
+    switch (proposal.kind) {
+        case 'recheck':
+            return proposal.epicId
+                ? `recheck of task ${proposal.taskId} (epic ${proposal.epicId})`
+                : `recheck of task ${proposal.taskId}`;
+        case 'maintenance': {
+            const names = proposal.packages.map((p) => p.name);
+            const shown = names.slice(0, 5).join(', ');
+            const rest = names.length > 5 ? `, +${names.length - 5} more` : '';
+            return `maintenance bump of ${names.length} package(s): ${shown}${rest}`;
+        }
+        case 'growth-review-due':
+            return `product-growth review, ${proposal.cadenceDays}-day cadence`;
+    }
+}
+/** The text the security keywords are matched against, named by field so a hit can say where. */
+function securityFields(proposal, ctx) {
+    switch (proposal.kind) {
+        case 'recheck': {
+            const claims = ctx.claimsByTask?.get(proposal.taskId) ?? [];
+            return [
+                ...claims.map((claim) => ({ field: 'claim', value: claim })),
+                { field: 'task id', value: proposal.taskId },
+            ];
+        }
+        case 'maintenance':
+            return proposal.packages.map((p) => ({ field: 'package', value: p.name }));
+        case 'growth-review-due':
+            return [];
+    }
+}
+function classify(proposal, policy, ctx) {
+    if (!policy.enabled) {
+        return {
+            decision: 'operator',
+            code: 'autonomy-disabled',
+            reason: 'scheduler.yml autonomy.enabled is false: every proposal waits for an operator tick.',
+        };
+    }
+    // Ahead of the whitelist, not inside it: architecture §12 puts growth scope
+    // with the operator unconditionally, so listing the kind must not be enough.
+    if (proposal.kind === 'growth-review-due') {
+        return {
+            decision: 'operator',
+            code: 'growth-never-auto',
+            reason: 'A product-growth review proposes SCOPE, and scope is the operator\'s (architecture §12: "product-growth proposals always wait for an operator tick"). Listing the kind in auto_dispatch_kinds changes nothing.',
+        };
+    }
+    if (!policy.autoDispatchKinds.includes(proposal.kind)) {
+        return {
+            decision: 'operator',
+            code: 'kind-not-whitelisted',
+            reason: `scheduler.yml autonomy.auto_dispatch_kinds does not list "${proposal.kind}".`,
+        };
+    }
+    const hit = firstSecurityHit(securityFields(proposal, ctx), ctx.securityKeywords);
+    if (hit) {
+        return {
+            decision: 'operator',
+            code: 'security-surface',
+            reason: `The ${hit.field} "${hit.value}" matches security keyword "${hit.keyword}" (crosscheck.yml plan_quorum.security_keywords). A security surface always waits, whatever the confidence.`,
+        };
+    }
+    if (proposal.kind === 'recheck') {
+        const held = proposal.reasons.filter((r) => !policy.autoDispatchRecheckReasons.includes(r));
+        if (held.length > 0) {
+            return {
+                decision: 'operator',
+                code: 'reason-not-whitelisted',
+                reason: `Reason(s) ${held.map((r) => `"${r}"`).join(', ')} are not in autonomy.auto_dispatch_recheck_reasons. One unlisted reason holds the proposal even when the others are listed: a recheck is dispatched once, and it would carry the unlisted reason with it.`,
+            };
+        }
+        return {
+            decision: 'auto',
+            code: 'admitted',
+            reason: `Every reason (${proposal.reasons.join(', ')}) is whitelisted.`,
+        };
+    }
+    if (proposal.confidence < policy.confidenceFloor) {
+        return {
+            decision: 'operator',
+            code: 'below-confidence-floor',
+            reason: `Confidence ${proposal.confidence} is below autonomy.confidence_floor ${policy.confidenceFloor} — scheduler.ts scores a major-version bump low precisely so a person reads it.`,
+        };
+    }
+    return {
+        decision: 'auto',
+        code: 'admitted',
+        reason: `Confidence ${proposal.confidence} meets autonomy.confidence_floor ${policy.confidenceFloor}, and no package name touches a security keyword.`,
+    };
+}
+/**
+ * Pure: one admission per proposal, in the order given, nothing written and
+ * nothing mutated. The caller decides what to do with the `auto` ones.
+ */
+export function admitProposals(proposals, policy, ctx) {
+    return proposals.map((proposal) => ({
+        proposal,
+        subject: subjectOf(proposal),
+        ...classify(proposal, policy, ctx),
+    }));
+}

package/factory/orchestrator/dist/budgetAlarm.js

@@ -0,0 +1,366 @@
+import { eventTaskId } from './events.js';
+import { bareTaskId, epicOfTaskId } from './taskId.js';
+/**
+ * The roles budgets.yml prices under `task.judges` — its line 53 comment is the
+ * enumeration: "# spec-reviewer, reviewer, verifier, grader".
+ *
+ * Hardcoded here rather than added to the YAML as a `roles:` list, for the same
+ * reason escalation.ts derives BUILDER_ROLES from the policy's own prose: the
+ * list is already written down, and a second copy in a different file is a
+ * second thing to keep true. What matters is that a role absent from *both*
+ * this list and the priced worker roles is reported rather than assumed free —
+ * see rolesWithoutCap. `security-reviewer` and `merger` are the live examples:
+ * both appear in budgets.yml's `narrowing_roles`, neither has a declared cap.
+ */
+const JUDGE_ROLES = ['spec-reviewer', 'reviewer', 'verifier', 'grader'];
+function priceRole(role, policy) {
+    if (role === 'coder')
+        return { kind: 'worker', capTokens: policy.task.coder.capTokens };
+    if (role === 'researcher')
+        return { kind: 'worker', capTokens: policy.task.researcher.capTokens };
+    if (JUDGE_ROLES.includes(role))
+        return { kind: 'judge', capTokens: policy.task.judges.capTokens };
+    return { kind: 'unpriced' };
+}
+/**
+ * The most the projection can charge one unmeasured dispatch.
+ *
+ * Read across every priced role rather than off `coder`, which merely happens
+ * to be the largest today: a policy that priced a researcher higher would
+ * otherwise let spend above the real ceiling pass unnamed.
+ */
+function largestDeclaredPrice(policy) {
+    return Math.max(policy.task.coder.capTokens, policy.task.researcher.capTokens, policy.task.judges.capTokens);
+}
+function payloadString(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function payloadNumber(payload, key) {
+    const value = payload[key];
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+/**
+ * Task -> epic, from every trace in the log that carries the edge.
+ *
+ * Two traces, because either can be absent (the P9-32 lesson: an audit that
+ * reads one trace reports that trace's gaps as the world's clean state):
+ *
+ *   1. A qualified id names its own epic — `<epic>/<task>`.
+ *   2. `wave-admitted` / `wave-merged` carry `epic_id` plus the `task_ids` they
+ *      moved, which is the only trace for a bare id.
+ *
+ * Every admitted id is indexed under both its own spelling and its bare form.
+ * dogfood-envkit-1 admitted wave 1 as `envkit-config-loader/task-0-toolchain`
+ * and recorded every one of that task's later events under the bare
+ * `task-0-toolchain` (D-14, deliberately). A map keyed on the admitted spelling
+ * alone attributes none of them.
+ */
+export function readEpicMembership(events) {
+    const membership = new Map();
+    const remember = (taskId, epicId) => {
+        if (!membership.has(taskId))
+            membership.set(taskId, epicId);
+        const bare = bareTaskId(taskId);
+        if (!membership.has(bare))
+            membership.set(bare, epicId);
+    };
+    for (const event of events) {
+        const { record } = event;
+        if (record.event_type === 'wave-admitted' || record.event_type === 'wave-merged') {
+            const epicId = payloadString(record.payload, 'epic_id');
+            const taskIds = record.payload.task_ids;
+            if (epicId !== null && Array.isArray(taskIds)) {
+                for (const taskId of taskIds) {
+                    if (typeof taskId === 'string' && taskId.length > 0)
+                        remember(taskId, epicId);
+                }
+            }
+        }
+        const taskId = eventTaskId(event.record);
+        if (taskId === null)
+            continue;
+        const epicId = epicOfTaskId(taskId);
+        if (epicId !== null)
+            remember(taskId, epicId);
+    }
+    return membership;
+}
+/**
+ * Task -> tokens recorded, from both traces that carry a spend number.
+ *
+ *   1. `task-result-recorded.token_usage.total_tokens` — the worker's own count.
+ *   2. `budget-check-result.tokensUsed` — the gate's copy of that same number.
+ *
+ * The larger of the two wins rather than their sum. They describe one spend: the
+ * gate reads `tokensUsed` off the very result it is checking, so adding them
+ * doubles the bill, and taking either alone reads zero whenever that trace is
+ * the one missing. On dogfood-envkit-1 *both* are missing for every task — the
+ * log holds neither event type — which is what makes measured-only reporting
+ * useless there and the projection load-bearing.
+ *
+ * Max also collapses re-dispatch, which is a different claim and a wrong one.
+ * dogfood-mcp-1 recorded `task-2-path-guard` seven times: three distinct
+ * rounds, each re-recorded under both the qualified and the bare id spelling.
+ * Summing would bill a round two or three times; max bills one round of three.
+ * Both are wrong about the total, and max is the safe direction to be wrong in
+ * only because this map is a floor — the projection is what has to carry the
+ * rounds it drops (D-171).
+ */
+export function readMeasuredSpend(events) {
+    const spend = new Map();
+    const record = (taskId, tokens) => {
+        const seen = spend.get(taskId);
+        if (seen === undefined || tokens > seen)
+            spend.set(taskId, tokens);
+    };
+    for (const event of events) {
+        const taskId = eventTaskId(event.record);
+        if (taskId === null)
+            continue;
+        const { payload, event_type: eventType } = event.record;
+        if (eventType === 'task-result-recorded') {
+            const usage = payload.token_usage;
+            if (usage !== null && typeof usage === 'object') {
+                const total = payloadNumber(usage, 'total_tokens');
+                if (total !== null)
+                    record(taskId, total);
+            }
+            continue;
+        }
+        if (eventType === 'budget-check-result') {
+            const used = payloadNumber(payload, 'tokensUsed');
+            if (used !== null)
+                record(taskId, used);
+        }
+    }
+    return spend;
+}
+const NUMBER = new Intl.NumberFormat('en-US');
+function fmt(n) {
+    return NUMBER.format(n);
+}
+function emptyAccumulator() {
+    return {
+        tasks: new Set(),
+        measuredTasks: new Set(),
+        measuredTokens: 0,
+        projectedFrom: new Map(),
+        rolesWithoutCap: new Set(),
+        tasksOverPrice: new Set(),
+    };
+}
+function decide(measured, projected, alarmTokens, capTokens, hasHoles) {
+    // Order matters, and it is the monotonicity argument in code. A crossing the
+    // log can already prove survives any hole in the log, so it is reported as
+    // the fact it is rather than downgraded to unverifiable by an unrelated
+    // unknown. Only when nothing has crossed does the quality of the record
+    // decide between "under" and "we cannot tell".
+    if (measured >= capTokens)
+        return 'over-cap';
+    if (measured >= alarmTokens)
+        return 'alarm';
+    if (projected >= alarmTokens)
+        return 'at-risk';
+    if (hasHoles)
+        return 'unverifiable';
+    return 'under';
+}
+function describe(check, unattributed, largestPrice) {
+    const head = `${fmt(check.measuredTokens)} tokens measured across ${check.measuredTaskCount} of ` +
+        `${check.taskCount} task(s), ${fmt(check.projectedTokens)} projected, against a ` +
+        `${fmt(check.alarmTokens)} alarm and a ${fmt(check.capTokens)} cap.`;
+    const holes = [];
+    if (check.rolesWithoutCap.length > 0) {
+        holes.push(`budgets.yml declares no cap for ${check.rolesWithoutCap.join(', ')}, so those ` +
+            `dispatches are in neither number`);
+    }
+    if (unattributed > 0) {
+        holes.push(`${unattributed} dispatch(es) name no epic, so their tokens are in nobody's total`);
+    }
+    if (check.tasksOverPrice.length > 0) {
+        holes.push(`${check.tasksOverPrice.join(', ')} measured above the ${fmt(largestPrice)} this ` +
+            `projection charges an unmeasured dispatch, so a cap does not bound one here`);
+    }
+    const holeText = holes.length > 0 ? ` Holes: ${holes.join('; ')}.` : '';
+    switch (check.status) {
+        case 'over-cap':
+            return `${head} Measured spend alone is at or past the cap.${holeText}`;
+        case 'alarm':
+            return (`${head} Measured spend alone has reached the alarm — re-plan the remaining work to ` +
+                `fit, or ask the operator to extend. Unrecorded spend can only add to this.${holeText}`);
+        case 'at-risk':
+            return (`${head} Measured spend is under the alarm but the projected ceiling is not: the ` +
+                `visible half of the bill reads clear while the whole bill does not (D-9).${holeText}`);
+        case 'unverifiable':
+            return (`${head} Neither bound has crossed the alarm, but the projection is not an upper ` +
+                `bound, so "under" would be a claim about the record rather than the spend.${holeText}`);
+        default:
+            return (`${head} The projected ceiling is under the alarm, so the real spend is too.` +
+                ` Measured spend remains a floor: judge tokens never reach a task result.`);
+    }
+}
+/**
+ * Epic spend against `epic.alarm_ratio`, counted from the log.
+ *
+ * Fails the report on anything but `under`, and on an empty epic set: a session
+ * the log attributes no epic to has not been shown to be within budget, it has
+ * been shown to be unreadable. Same reason dispatchAudit.ts emits a synthetic
+ * check for an empty pair set — an empty check set must never be mistaken for
+ * a clean one.
+ */
+export function checkBudgetAlarm(events, policy, options) {
+    const capTokens = policy.epic.capTokens;
+    const alarmRatio = policy.epic.alarmRatio;
+    const alarmTokens = Math.floor(capTokens * alarmRatio);
+    const largestPrice = largestDeclaredPrice(policy);
+    const membership = readEpicMembership(events);
+    const rawSpend = readMeasuredSpend(events);
+    const epicOf = (taskId) => membership.get(taskId) ?? membership.get(bareTaskId(taskId)) ?? null;
+    // Fold spend onto the bare id, so a task recorded under both spellings is one
+    // task with one bill rather than two of each.
+    const spendByTask = new Map();
+    for (const [taskId, tokens] of rawSpend) {
+        const bare = bareTaskId(taskId);
+        const seen = spendByTask.get(bare);
+        if (seen === undefined || tokens > seen)
+            spendByTask.set(bare, tokens);
+    }
+    const inScope = (epicId) => options.epicId === undefined || options.epicId === epicId;
+    const accumulators = new Map();
+    const accumulatorFor = (epicId) => {
+        let acc = accumulators.get(epicId);
+        if (acc === undefined) {
+            acc = emptyAccumulator();
+            accumulators.set(epicId, acc);
+        }
+        return acc;
+    };
+    // An epic's task set comes from evidence a task existed — a wave that
+    // admitted it, spend recorded against it, or a dispatch charged to it. Not
+    // from the membership map, which is deliberately broader: epic-level events
+    // carry synthetic `<epic>/epic` ids (dogfood's `epic-closed` does), and those
+    // belong in the attribution index without inflating a task count.
+    for (const event of events) {
+        const { record } = event;
+        if (record.event_type !== 'wave-admitted' && record.event_type !== 'wave-merged')
+            continue;
+        const epicId = payloadString(record.payload, 'epic_id');
+        const taskIds = record.payload.task_ids;
+        if (epicId === null || !inScope(epicId) || !Array.isArray(taskIds))
+            continue;
+        const acc = accumulatorFor(epicId);
+        for (const taskId of taskIds) {
+            if (typeof taskId === 'string' && taskId.length > 0)
+                acc.tasks.add(bareTaskId(taskId));
+        }
+    }
+    for (const [bare, tokens] of spendByTask) {
+        const epicId = epicOf(bare);
+        if (epicId === null || !inScope(epicId))
+            continue;
+        const acc = accumulatorFor(epicId);
+        acc.tasks.add(bare);
+        acc.measuredTasks.add(bare);
+        acc.measuredTokens += tokens;
+        if (tokens > largestPrice)
+            acc.tasksOverPrice.add(bare);
+    }
+    let unattributedDispatches = 0;
+    const unattributedRoles = new Set();
+    // Tasks whose measured number has already paid for one worker dispatch.
+    const accountedByMeasured = new Set();
+    for (const event of events) {
+        if (event.record.event_type !== 'dispatch_decision')
+            continue;
+        const role = payloadString(event.record.payload, 'agent_role');
+        if (role === null)
+            continue;
+        const taskId = eventTaskId(event.record);
+        const epicId = taskId === null ? null : epicOf(taskId);
+        if (epicId === null) {
+            unattributedDispatches += 1;
+            unattributedRoles.add(role);
+            continue;
+        }
+        if (!inScope(epicId))
+            continue;
+        const acc = accumulatorFor(epicId);
+        if (taskId !== null)
+            acc.tasks.add(bareTaskId(taskId));
+        const pricing = priceRole(role, policy);
+        if (pricing.kind === 'unpriced') {
+            acc.rolesWithoutCap.add(role);
+            continue;
+        }
+        // A judge's tokens are in no result and never will be, so a judge dispatch
+        // is always projected. A worker's are inside a result — but `spendByTask`
+        // holds one number per task, the largest, so it accounts for exactly one of
+        // that task's worker dispatches. Exempting all of them (D-171) put a
+        // re-dispatched round in neither number: the max had discarded its tokens
+        // and the exemption then declined to price them.
+        if (pricing.kind === 'worker' && taskId !== null) {
+            const bare = bareTaskId(taskId);
+            if (spendByTask.has(bare) && !accountedByMeasured.has(bare)) {
+                accountedByMeasured.add(bare);
+                continue;
+            }
+        }
+        acc.projectedFrom.set(role, (acc.projectedFrom.get(role) ?? 0) + pricing.capTokens);
+    }
+    const epics = [...accumulators.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([epicId, acc]) => {
+        const projectedFrom = Object.fromEntries([...acc.projectedFrom.entries()].sort(([a], [b]) => a.localeCompare(b)));
+        const projectedTokens = acc.measuredTokens + Object.values(projectedFrom).reduce((sum, n) => sum + n, 0);
+        const rolesWithoutCap = [...acc.rolesWithoutCap].sort();
+        const tasksOverPrice = [...acc.tasksOverPrice].sort();
+        const status = decide(acc.measuredTokens, projectedTokens, alarmTokens, capTokens, rolesWithoutCap.length > 0 || unattributedDispatches > 0 || tasksOverPrice.length > 0);
+        const partial = {
+            epicId,
+            capTokens,
+            alarmTokens,
+            measuredTokens: acc.measuredTokens,
+            projectedTokens,
+            taskCount: acc.tasks.size,
+            measuredTaskCount: acc.measuredTasks.size,
+            projectedFrom,
+            rolesWithoutCap,
+            tasksOverPrice,
+            status,
+        };
+        return { ...partial, detail: describe(partial, unattributedDispatches, largestPrice) };
+    });
+    if (epics.length === 0) {
+        const partial = {
+            epicId: '*',
+            capTokens,
+            alarmTokens,
+            measuredTokens: 0,
+            projectedTokens: 0,
+            taskCount: 0,
+            measuredTaskCount: 0,
+            projectedFrom: {},
+            rolesWithoutCap: [],
+            tasksOverPrice: [],
+            status: 'unverifiable',
+        };
+        epics.push({
+            ...partial,
+            detail: options.epicId === undefined
+                ? 'No epic in this session has a task the log attributes to it, so there is no ' +
+                    'spend to measure. An unreadable session is not a session within budget.'
+                : `No task in this session is attributed to epic "${options.epicId}". Either the ` +
+                    'id is wrong or the log never recorded the wave that admitted its tasks.',
+        });
+    }
+    return {
+        sessionId: options.sessionId,
+        alarmRatio,
+        capTokens,
+        epics,
+        unattributedDispatches,
+        unattributedRoles: [...unattributedRoles].sort(),
+        ok: epics.every((epic) => epic.status === 'under'),
+    };
+}