@juzser/blacksmith 0.4.0 → 0.5.0

package/factory/orchestrator/dist/budgetAlarm.js

@@ -1,26 +1,72 @@
+// Epic spend against budgets.yml's `epic.alarm_ratio` — the consumer that
+// number never had (P9-33, closing D-12's "no" row).
+//
+// `epic.alarm_ratio: 0.7` has been in the policy since Phase 1. It parses into
+// BudgetPolicy, budgets.test.ts asserts it, and no production path reads it.
+// Its only real host was a sentence in SKILL.md telling a human to keep an eye
+// on the number — which is to say the alarm fired when someone remembered to
+// look.
+//
+// This module is the check that the two audits before it (dispatchAudit.ts,
+// escalation.ts) established the shape for: a pure function over the event log,
+// a status union with an explicit unverifiable, and a paired CLI verb that
+// exits 1. It differs from them in one way that changes the whole design.
+//
+// MONOTONICITY. Those audits ask whether a rule was obeyed, and a gap in the
+// record leaves the answer genuinely unknown in both directions. This one asks
+// how much an epic spent, and every gap in the record can only make the real
+// bill *bigger*. Measured spend is therefore a floor, never a total, and the
+// two directions are not symmetric:
+//
+//   * A crossing is a fact. If the tokens we can see already exceed the alarm,
+//     the tokens we cannot see do not un-exceed it. Report it, hole or no hole.
+//   * A non-crossing is a claim about the record, not about the world. "Under
+//     the alarm" is only honest when the *upper* bound is under it too.
+//
+// So the report carries two numbers per epic. `measuredTokens` is what the log
+// actually recorded. `projectedTokens` adds, for every dispatch the measured
+// number does not already account for, the cap budgets.yml declares for that
+// role — which is one cap per re-dispatch, not one per task (D-171). A role
+// the policy prices nowhere cannot be added to the ceiling at all — and a
+// ceiling with a hole in it is not a ceiling, so the epic goes unverifiable
+// rather than under.
+//
+// A cap is not a bound, though, and that is the third hole (D-188). The gate
+// records a task budget overrun and does not block on one, so a dispatch is
+// free to spend past its declared cap — dogfood's did, by an order of
+// magnitude: `envkit-mcp-surface/task-2-path-guard` recorded a single coder
+// round at 1,484,000 tokens against a 150,000 coder cap, and budgets.yml's own
+// comment cites that run as the reason the epic cap was raised. Once an epic
+// has been *measured* spending more on one task than the projection charges an
+// unmeasured dispatch, its own log has falsified the price list the projection
+// is built from, and the result is an estimate wearing a ceiling's name. So a
+// task over that price counts as a hole too: the epic still gets its numbers,
+// it just no longer gets to clear on them.
+//
+// The gap this makes visible is D-9's. On dogfood-envkit-1 the epic's declared
+// task budgets summed to 545,000 against a 2,000,000 cap — 27%, comfortably
+// under the 1,400,000 alarm — while the run's real projection was several times
+// that. The plan-quorum budget trigger, the one automated check meant to catch
+// "this plan is too expensive", measures the smaller half of the bill. Judge
+// tokens are in no task result and never will be: a judge returns findings, not
+// a Result. Anything that reads only `task-result-recorded` is reading the
+// builder's half and calling it the total.
+import { PRICED_ROLES, roleCapTokens } from './budgets.js';
 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.
+ * The priced roles whose tokens reach a Result, and so `task-result-recorded`.
+ * Every other priced role (the judges, planner, security-reviewer, auditor)
+ * produces findings or a plan whose spend reaches no result event, so it is
+ * always projected. A role budgets.yml prices nowhere (merger, uiux, scribe,
+ * wave-runner) is reported rather than assumed free — see rolesWithoutCap.
  */
-const JUDGE_ROLES = ['spec-reviewer', 'reviewer', 'verifier', 'grader'];
+const WORKER_ROLES = ['coder', 'researcher', 'tester'];
 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' };
+    const capTokens = roleCapTokens(policy, role);
+    if (capTokens === null)
+        return { kind: 'unpriced' };
+    return { kind: WORKER_ROLES.includes(role) ? 'worker' : 'judge', capTokens };
 }
 /**
  * The most the projection can charge one unmeasured dispatch.
@@ -30,7 +76,7 @@ function priceRole(role, policy) {
  * 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);
+    return Math.max(...PRICED_ROLES.map((role) => policy.task[role].capTokens));
 }
 function payloadString(payload, key) {
     const value = payload[key];
@@ -120,22 +166,31 @@ export function readMeasuredSpend(events) {
             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);
-            }
+            const read = readTokenUsage(payload.token_usage);
+            if (read.measured)
+                record(taskId, read.total);
             continue;
         }
         if (eventType === 'budget-check-result') {
             const used = payloadNumber(payload, 'tokensUsed');
-            if (used !== null)
+            if (used !== null && isPlausibleTokenCount(used))
                 record(taskId, used);
         }
     }
     return spend;
 }
+/**
+ * The smallest `total_tokens` a real agent turn plausibly produces. A single
+ * turn runs into the thousands, so a recorded count below this is far more
+ * likely a dispatcher's untouched placeholder (0/0 or 1/1) than a
+ * measurement, and is treated exactly like `{measured: false}` — projected at
+ * the dispatch's cap rather than recorded as spend.
+ */
+const IMPLAUSIBLE_TOKEN_FLOOR = 100;
+/** Shared by every other reader of `token_usage.total_tokens` (db/queries.ts), so the dashboard and stats agree with this alarm about what counts as measured. */
+export function isPlausibleTokenCount(total) {
+    return total >= IMPLAUSIBLE_TOKEN_FLOOR;
+}
 const NUMBER = new Intl.NumberFormat('en-US');
 function fmt(n) {
     return NUMBER.format(n);
@@ -168,8 +223,9 @@ function decide(measured, projected, alarmTokens, capTokens, hasHoles) {
 }
 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.`;
+        `${check.taskCount} task(s) (${check.unmeasuredTaskCount} unmeasured), ` +
+        `${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 ` +
@@ -212,8 +268,16 @@ function describe(check, unattributed, largestPrice) {
 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);
+    // Each epic is judged against budgets.yml sized for its own effort tier.
+    const epicPolicies = new Map();
+    const policyFor = (epicId) => {
+        let found = epicPolicies.get(epicId);
+        if (found === undefined) {
+            found = options.policyForEpic?.(epicId) ?? policy;
+            epicPolicies.set(epicId, found);
+        }
+        return found;
+    };
     const membership = readEpicMembership(events);
     const rawSpend = readMeasuredSpend(events);
     const epicOf = (taskId) => membership.get(taskId) ?? membership.get(bareTaskId(taskId)) ?? null;
@@ -263,7 +327,7 @@ export function checkBudgetAlarm(events, policy, options) {
         acc.tasks.add(bare);
         acc.measuredTasks.add(bare);
         acc.measuredTokens += tokens;
-        if (tokens > largestPrice)
+        if (tokens > largestDeclaredPrice(policyFor(epicId)))
             acc.tasksOverPrice.add(bare);
     }
     let unattributedDispatches = 0;
@@ -288,7 +352,7 @@ export function checkBudgetAlarm(events, policy, options) {
         const acc = accumulatorFor(epicId);
         if (taskId !== null)
             acc.tasks.add(bareTaskId(taskId));
-        const pricing = priceRole(role, policy);
+        const pricing = priceRole(role, policyFor(epicId));
         if (pricing.kind === 'unpriced') {
             acc.rolesWithoutCap.add(role);
             continue;
@@ -311,19 +375,24 @@ export function checkBudgetAlarm(events, policy, options) {
     const epics = [...accumulators.entries()]
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([epicId, acc]) => {
+        const epicPolicy = policyFor(epicId);
+        const epicCap = epicPolicy.epic.capTokens;
+        const epicAlarm = Math.floor(epicCap * epicPolicy.epic.alarmRatio);
+        const largestPrice = largestDeclaredPrice(epicPolicy);
         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 status = decide(acc.measuredTokens, projectedTokens, epicAlarm, epicCap, rolesWithoutCap.length > 0 || unattributedDispatches > 0 || tasksOverPrice.length > 0);
         const partial = {
             epicId,
-            capTokens,
-            alarmTokens,
+            capTokens: epicCap,
+            alarmTokens: epicAlarm,
             measuredTokens: acc.measuredTokens,
             projectedTokens,
             taskCount: acc.tasks.size,
             measuredTaskCount: acc.measuredTasks.size,
+            unmeasuredTaskCount: acc.tasks.size - acc.measuredTasks.size,
             projectedFrom,
             rolesWithoutCap,
             tasksOverPrice,
@@ -332,14 +401,18 @@ export function checkBudgetAlarm(events, policy, options) {
         return { ...partial, detail: describe(partial, unattributedDispatches, largestPrice) };
     });
     if (epics.length === 0) {
+        // An --epic that matched nothing is still reported against that epic's
+        // own tier cap: the default tier's cap would be a number it never had.
+        const emptyPolicy = options.epicId === undefined ? policy : policyFor(options.epicId);
         const partial = {
             epicId: '*',
-            capTokens,
-            alarmTokens,
+            capTokens: emptyPolicy.epic.capTokens,
+            alarmTokens: Math.floor(emptyPolicy.epic.capTokens * emptyPolicy.epic.alarmRatio),
             measuredTokens: 0,
             projectedTokens: 0,
             taskCount: 0,
             measuredTaskCount: 0,
+            unmeasuredTaskCount: 0,
             projectedFrom: {},
             rolesWithoutCap: [],
             tasksOverPrice: [],
@@ -364,3 +437,25 @@ export function checkBudgetAlarm(events, policy, options) {
         ok: epics.every((epic) => epic.status === 'under'),
     };
 }
+/**
+ * The one rule for "was this result's token count measured". Lives beside
+ * `isPlausibleTokenCount` so every reader (this alarm, db/queries.ts, the
+ * gate) imports one module that already owns the floor. Measured means an
+ * object whose `total_tokens` is a plausible number; a bare number, a
+ * `{measured: false}`, a missing total and a placeholder under the floor are
+ * all unmeasured.
+ */
+export function readTokenUsage(tokenUsage) {
+    if (tokenUsage === null || typeof tokenUsage !== 'object')
+        return { measured: false };
+    const usage = tokenUsage;
+    const total = payloadNumber(usage, 'total_tokens');
+    if (total === null || !isPlausibleTokenCount(total))
+        return { measured: false };
+    return {
+        measured: true,
+        total,
+        input: payloadNumber(usage, 'input_tokens'),
+        output: payloadNumber(usage, 'output_tokens'),
+    };
+}