@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/waivers.js

@@ -0,0 +1,228 @@
+import { SmithError } from './errors.js';
+import { appendEvent, readLineageEvents } from './events.js';
+import { listFindings, preWaiverStatus, staleFindings, transition } from './findings.js';
+export class WaiverError extends SmithError {
+}
+/**
+ * Only S3/S4 findings are ever waived (severity.yml waiver_semantics) —
+ * single source of truth, reused by findings.ts's transition() so `→ waived`
+ * is gated the same way everywhere it can be reached (direct transition
+ * call or via a waiver grant).
+ */
+export const WAIVABLE_SEVERITIES = ['S3-minor', 'S4-nit'];
+/** finding_status values transition() allows a "waived" edge from (findings.ts LEGAL_TRANSITIONS). */
+const WAIVABLE_STATUSES = ['raised', 'confirmed'];
+/**
+ * Fold waiver-granted/waiver-denied events for one fingerprint: the last
+ * decision wins (a denial can, in principle, be revisited by a later grant
+ * — the log keeps both, this just answers "is it waived right now").
+ *
+ * Over the lineage since D-119: a waiver is granted against a FINGERPRINT, and
+ * findings.ts folds those over the lineage now, so a session-scoped answer here
+ * would re-raise a finding the operator already waived the moment an epic
+ * continued in a new session. "Last decision wins" is decided on the merged
+ * order, which is `ts` between sessions and append order within one.
+ */
+export async function isWaived(fingerprint, ref, opts = {}) {
+    const events = await readLineageEvents(ref.sessionId, opts);
+    let waived = false;
+    for (const { record } of events) {
+        const payload = record.payload;
+        if (payload.fingerprint !== fingerprint)
+            continue;
+        if (record.event_type === 'waiver-granted')
+            waived = true;
+        else if (record.event_type === 'waiver-denied')
+            waived = false;
+    }
+    return waived;
+}
+/**
+ * Has the operator recorded ANY waiver decision for this fingerprint (granted
+ * or denied)? Lineage-wide, for isWaived's reason (D-119): a decision recorded
+ * in the parent session is still a decision.
+ */
+async function hasDecision(fingerprint, ref, opts) {
+    const events = await readLineageEvents(ref.sessionId, opts);
+    return events.some(({ record }) => {
+        const payload = record.payload;
+        return (payload.fingerprint === fingerprint &&
+            (record.event_type === 'waiver-granted' || record.event_type === 'waiver-denied'));
+    });
+}
+/**
+ * Every finding sharing `fingerprint` that is still open (raised/confirmed,
+ * a waivable severity) is transitioned to `waived` with `waiver_id` set to
+ * the granting event's id — otherwise a granted waiver never shows up on
+ * finding_status and kanban/analytics/queue consumers that trust it see the
+ * finding as open forever. Findings the state machine can't legally move
+ * (already terminal, or a non-S3/S4 severity that somehow shares this
+ * fingerprint) are left alone; this is reconciliation, not a mandate.
+ */
+async function reconcileFindingsToWaived(fingerprint, waiverEventId, ctx, opts) {
+    const findings = await listFindings(ctx.sessionId, {}, opts);
+    const reconcilable = findings.filter((f) => f.fingerprint === fingerprint &&
+        WAIVABLE_SEVERITIES.includes(f.severity) &&
+        WAIVABLE_STATUSES.includes(f.finding_status));
+    const transitionCtx = { ...ctx, causalParent: waiverEventId };
+    for (const finding of reconcilable) {
+        await transition(finding.finding_id, 'waived', transitionCtx, opts, {
+            waiverId: waiverEventId,
+        });
+    }
+}
+export async function grantWaiver(fingerprint, operatorNote, ctx, opts = {}) {
+    const waiverEvent = await appendEvent({
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'user',
+        event_type: 'waiver-granted',
+        plan_version: ctx.planVersion,
+        causal_parent: ctx.causalParent,
+        payload: { fingerprint, operator_note: operatorNote },
+    }, opts);
+    await reconcileFindingsToWaived(fingerprint, waiverEvent.event_id, ctx, opts);
+    return waiverEvent;
+}
+/**
+ * The mirror of reconcileFindingsToWaived, and it exists for the same reason
+ * (D-180). A denial that follows a grant revokes it — isWaived() folds
+ * last-decision-wins and answers "not waived" the moment it lands — but the
+ * findings that grant closed stayed at `waived` regardless: discretionary at
+ * the epic gate, absent from pendingBatch because a decision exists, and
+ * unreachable by `finding transition` because `waived` was terminal. The
+ * operator's reversal changed nothing anyone downstream could see.
+ *
+ * Only findings this session's log actually shows at `waived` are touched, and
+ * each goes back to the status its own grant recorded as from_status. A
+ * finding waived under some other fingerprint is not this denial's business.
+ */
+async function reconcileFindingsFromWaived(fingerprint, denialEventId, ctx, opts) {
+    const findings = await listFindings(ctx.sessionId, {}, opts);
+    const reopenable = findings.filter((f) => f.fingerprint === fingerprint && f.finding_status === 'waived');
+    const transitionCtx = { ...ctx, causalParent: denialEventId };
+    for (const finding of reopenable) {
+        const to = await preWaiverStatus(finding.finding_id, ctx.sessionId, opts);
+        // A `waived` finding whose grant left no from_status is not something this
+        // reconciliation can place, so it is left where it is: a guessed status
+        // here either credits a verification that never ran or discards one that
+        // did. Only transitions written before from_status existed can produce it.
+        if (to === undefined)
+            continue;
+        await transition(finding.finding_id, to, transitionCtx, opts, {
+            waiverRevokedBy: denialEventId,
+        });
+    }
+}
+export async function denyWaiver(fingerprint, operatorNote, ctx, opts = {}) {
+    const denialEvent = await appendEvent({
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'user',
+        event_type: 'waiver-denied',
+        plan_version: ctx.planVersion,
+        causal_parent: ctx.causalParent,
+        payload: { fingerprint, operator_note: operatorNote },
+    }, opts);
+    await reconcileFindingsFromWaived(fingerprint, denialEvent.event_id, ctx, opts);
+    return denialEvent;
+}
+/**
+ * S3/S4 findings for one epic that have no waiver decision yet, grouped for
+ * a single batched operator prompt (architecture §11: never re-ask). Not
+ * "all S3/S4 ever raised" — a finding already granted or denied is settled
+ * and never resurfaces here.
+ */
+export async function pendingBatch(epic, ref, opts = {}) {
+    const findings = await listFindings(ref.sessionId, { epic }, opts);
+    const pending = [];
+    for (const finding of findings) {
+        if (!WAIVABLE_SEVERITIES.includes(finding.severity))
+            continue;
+        if (await hasDecision(finding.fingerprint, ref, opts))
+            continue;
+        pending.push(finding);
+    }
+    return pending;
+}
+/**
+ * Apply a batch of operator waiver answers. Validates every fingerprint
+ * against a real finding in this session, AND (for `granted` decisions)
+ * that every finding sharing that fingerprint sits at a waivable severity
+ * (S3/S4) — all before writing anything. A batch referencing an unknown
+ * fingerprint, or attempting to grant a waiver over a non-waivable
+ * (S1/S2) finding, fails entirely (typed error), rather than partially
+ * applying. This is a stricter, operator-facing policy check on top of
+ * grantWaiver()'s own lower-level reconciliation, which — reached directly,
+ * not through this batch API — still only ever moves the WAIVABLE findings
+ * sharing a fingerprint to `waived` and leaves any non-waivable sibling
+ * alone (see waivers.test.ts).
+ *
+ * Without this gate, grantWaiver() would append `waiver-granted` for a
+ * fingerprint whose only finding is S2 — isWaived() folds that event
+ * regardless of severity, so the operator's answer would stand on the record
+ * as having settled a merge-blocking finding it was never allowed to be asked
+ * about, while the finding itself stays open forever (reconcileFindingsToWaived
+ * leaves non-waivable findings alone, by design). Since D-196, raiseFinding no
+ * longer suppresses a re-raise at a non-waivable severity, so the damage stops
+ * at the record rather than reaching the next round's gate — but a waiver that
+ * settles nothing is still not a waiver, and the batch refuses to write one.
+ *
+ * A `granted` decision is additionally refused when the finding's evidence is
+ * stale — a wave has merged over its file since it was raised or last
+ * re-verified (P9-15). The operator is answering a question about code that
+ * no longer exists; the remedy is `smith findings reverify`, which is named in
+ * the error. Denials are allowed through: a denial closes nothing and grants
+ * nothing, so blocking it would only strand the batch.
+ */
+export async function applyBatch(decisions, ctx, opts = {}) {
+    const findings = await listFindings(ctx.sessionId, {}, opts);
+    const findingsByFingerprint = new Map();
+    for (const f of findings) {
+        const list = findingsByFingerprint.get(f.fingerprint) ?? [];
+        list.push(f);
+        findingsByFingerprint.set(f.fingerprint, list);
+    }
+    // Computed once for the batch, and only when it can matter: a batch of pure
+    // denials never reads the merge history at all.
+    const stale = decisions.some((d) => d.decision === 'granted')
+        ? await staleFindings(ctx.sessionId, opts)
+        : new Map();
+    for (const decision of decisions) {
+        const owning = findingsByFingerprint.get(decision.fingerprint);
+        if (!owning) {
+            throw new WaiverError('waivers.unknown-fingerprint', `No finding with fingerprint "${decision.fingerprint}" in session "${ctx.sessionId}".`, { fingerprint: decision.fingerprint });
+        }
+        if (decision.decision === 'granted') {
+            const nonWaivable = owning.filter((f) => !WAIVABLE_SEVERITIES.includes(f.severity));
+            if (nonWaivable.length > 0) {
+                throw new WaiverError('waivers.non-waivable-severity', `Fingerprint "${decision.fingerprint}" has finding(s) at a non-waivable severity ` +
+                    `(${nonWaivable.map((f) => f.severity).join(', ')}) — only ${WAIVABLE_SEVERITIES.join('/')} findings can be waived.`, { fingerprint: decision.fingerprint, severities: nonWaivable.map((f) => f.severity) });
+            }
+            for (const finding of owning) {
+                const evidence = stale.get(finding.finding_id);
+                if (!evidence)
+                    continue;
+                throw new WaiverError('waivers.stale-evidence', `Finding "${finding.finding_id}" is anchored to ${evidence.filePath}, which task ` +
+                    `"${evidence.mergedTaskId}" has merged over since the finding was raised (matched by ` +
+                    `${evidence.basis}: ${evidence.matched}). Its evidence describes code that no longer ` +
+                    'exists, so this waiver would answer a question about a deleted file. Re-read it first: ' +
+                    `smith findings reverify --finding ${finding.finding_id}`, {
+                    fingerprint: decision.fingerprint,
+                    findingId: finding.finding_id,
+                    filePath: evidence.filePath,
+                    mergedTaskId: evidence.mergedTaskId,
+                    basis: evidence.basis,
+                });
+            }
+        }
+    }
+    const results = [];
+    for (const decision of decisions) {
+        if (decision.decision === 'granted') {
+            results.push(await grantWaiver(decision.fingerprint, decision.operatorNote, ctx, opts));
+        }
+        else {
+            results.push(await denyWaiver(decision.fingerprint, decision.operatorNote, ctx, opts));
+        }
+    }
+    return results;
+}

package/factory/orchestrator/dist/waveBudget.js

@@ -0,0 +1,223 @@
+// Wave admission's budget gate, added the same day `epic.max_in_flight_tasks`
+// reached budgets.yml.
+//
+// budgetAlarm.ts (P9-33) made `epic.cap_tokens` and `epic.alarm_ratio`
+// readable, but every reader that gave those numbers stands downstream of the
+// spend it reports: planQuorum's budget trigger and `smith budget alarm` both
+// describe a bill, neither refuses one. `smith wave check` (this module) is
+// the first reader standing upstream of the spend it is judging -- at wave
+// admission, before any task in the wave has been dispatched -- so it is the
+// only one of the three that CAN refuse the spend instead of merely
+// describing it afterward.
+//
+// It reuses checkBudgetAlarm for the epic's measured/projected spend rather
+// than re-deriving either number: a second price list is a second thing that
+// can disagree with the first, and this module has no business owning its
+// own opinion about what a role costs or how a task's tokens are counted.
+// What it adds is the one question checkBudgetAlarm was never asked: given
+// the headroom that leaves under the cap right now, does the wave about to
+// be admitted still fit once its own declared cost is added.
+//
+// This does not revisit D-29's finding for the task gate: a coder cap the
+// worker polices itself is pressure on the very work it is measuring, and it
+// stays advisory for exactly that reason (see budgets.yml's header). An epic
+// cap checked at wave admission is not a stricter version of that same
+// check -- it is a different question asked at a different time. It asks
+// before any task in the wave has started, when there is nothing in flight
+// yet for a refusal to distort. A decision made before the work exists cannot
+// become pressure on the work.
+import { checkBudgetAlarm } from './budgetAlarm.js';
+import { bareTaskId } from './taskId.js';
+/**
+ * The statuses that must stop an admission.
+ *
+ * `unchecked` is deliberately not among them, and the distinction is the
+ * whole reason it exists as a separate status rather than being folded into
+ * `ok`. A session-less `wave check` cannot write a `wave-admitted` event in
+ * the first place -- it has no log to write to -- so it is always advisory,
+ * and refusing it would only stop the operator who asked politely before
+ * committing to anything. What it must not do is answer `ok`: that is one
+ * indistinguishable yes for "checked, and it fits" and "never checked", which
+ * is the exact shape of the bug that made the old guard hook allow everything
+ * on macOS for eight phases.
+ */
+export function blocksAdmission(status) {
+    return status === 'refused' || status === 'over-fan-out' || status === 'unverifiable';
+}
+const NUMBER = new Intl.NumberFormat('en-US');
+function fmt(n) {
+    return NUMBER.format(n);
+}
+function payloadEpicId(payload) {
+    const value = payload.epic_id;
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Bare task ids this epic has admitted and not yet merged, sorted.
+ *
+ * Folded through bareTaskId exactly as checkBudgetAlarm's own accumulators
+ * are (D-46/P9-10): the log is append-only, so a task admitted under its
+ * qualified `<epic>/<task>` spelling can be merged under the bare `<task>`
+ * spelling later in the same session (or the reverse), and a set keyed on
+ * exact string equality would either miss the cancellation or count the one
+ * task twice under its two spellings.
+ */
+export function inFlightTasks(events, epicId) {
+    const admitted = new Set();
+    const merged = new Set();
+    for (const event of events) {
+        const { record } = event;
+        if (record.event_type !== 'wave-admitted' && record.event_type !== 'wave-merged')
+            continue;
+        if (payloadEpicId(record.payload) !== epicId)
+            continue;
+        const taskIds = record.payload.task_ids;
+        if (!Array.isArray(taskIds))
+            continue;
+        const target = record.event_type === 'wave-admitted' ? admitted : merged;
+        for (const taskId of taskIds) {
+            if (typeof taskId === 'string' && taskId.length > 0)
+                target.add(bareTaskId(taskId));
+        }
+    }
+    return [...admitted].filter((taskId) => !merged.has(taskId)).sort();
+}
+function unverifiableDetail(unpricedTasks) {
+    return (`${fmt(unpricedTasks.length)} of the proposed task(s) (${unpricedTasks.join(', ')}) declare ` +
+        `no budget.tokens, so the wave's cost cannot be summed. Price every task before the wave is ` +
+        `admitted -- a wave with an unpriced task is not cheaper, it is unmeasured.`);
+}
+function overFanOutDetail(inFlight, waveTaskCount, maxInFlightTasks) {
+    return (`Admitting this wave would put ${fmt(inFlight + waveTaskCount)} of the epic's tasks in ` +
+        `flight at once (${fmt(inFlight)} already admitted and unmerged, ${fmt(waveTaskCount)} ` +
+        `proposed), past the ${fmt(maxInFlightTasks)} epic.max_in_flight_tasks allows. Merge or ` +
+        `cancel enough in-flight work first, or raise the cap by explicit operator decision.`);
+}
+function refusedDetail(projectedTokens, waveTokens, capTokens) {
+    return (`${fmt(projectedTokens)} tokens projected for this epic plus ${fmt(waveTokens)} declared ` +
+        `for this wave would reach ${fmt(projectedTokens + waveTokens)}, past the ${fmt(capTokens)} ` +
+        `epic.cap_tokens allows. Split the epic at spec time so the remaining work fits, or extend ` +
+        `the cap by explicit operator decision.`);
+}
+function okDetail(headroomTokens, waveTokens, capTokens) {
+    return (`${fmt(waveTokens)} tokens declared for this wave fit within ${fmt(headroomTokens)} of ` +
+        `headroom under the ${fmt(capTokens)} epic.cap_tokens cap.`);
+}
+function uncheckedDetail(waveTokens, capTokens) {
+    return (`${fmt(waveTokens)} tokens declared for this wave fit under the ${fmt(capTokens)} ` +
+        `epic.cap_tokens cap on their own, but no --session was given, so the spend this epic has ` +
+        `already run up could not be read and the real headroom is unknown. Re-run with --session ` +
+        `to have the cap actually checked -- this is not a pass, it is an unasked question.`);
+}
+const NOT_APPLICABLE_DETAIL = 'No epic id was given for this wave, so there is no epic cap to check it against.';
+/**
+ * Whether a wave may be admitted, checked once, before any task in it has
+ * been dispatched.
+ *
+ * Reuses checkBudgetAlarm for the epic's measured/projected spend (see this
+ * file's header) and adds one number of its own: the wave's own declared
+ * cost, summed from `proposed`. Decision order matters and is
+ * first-match-wins:
+ *
+ *   1. not-applicable  -- no epic id was given for the wave at all. Reserved
+ *      for exactly this: an epic with no history yet still has an epic, so
+ *      its first wave is judged on rule 5 below, not this one.
+ *   2. unverifiable    -- some proposed task declares no budget.tokens, so
+ *      the wave's own cost cannot be summed. Checked before the fan-out and
+ *      cap comparisons because neither means anything once one of their
+ *      inputs is missing.
+ *   3. over-fan-out    -- admitting the wave would put more of the epic's
+ *      tasks in flight than epic.max_in_flight_tasks allows.
+ *   4. refused         -- admitting the wave would cross epic.cap_tokens.
+ *      Ranked above `unchecked` on purpose: with no session the epic's prior
+ *      spend reads as zero, so this fires only when the wave's own declared
+ *      cost exceeds the whole cap by itself -- a sound refusal that needs no
+ *      log to reach.
+ *   5. unchecked       -- nothing checkable is wrong, but no session id was
+ *      given, so the epic's spend so far could not be read and the headroom
+ *      the wave was measured against is not the real one.
+ *   6. ok              -- otherwise, including an epic's genuine first wave.
+ *
+ * An epic on its genuine first wave (checkBudgetAlarm finds no prior event
+ * attributing anything to it) reads `measuredTokens: 0, projectedTokens: 0`
+ * -- ok if the wave itself fits under the cap, never not-applicable. A fresh
+ * epic is not an unreadable one, and neither is a session-less check: that
+ * one is `unchecked`, which is not the same as either.
+ */
+export function checkWaveBudget(events, policy, proposed, options) {
+    const capTokens = policy.epic.capTokens;
+    const maxInFlightTasks = policy.epic.maxInFlightTasks;
+    const waveTaskCount = proposed.length;
+    const unpricedTasks = proposed.filter((task) => task.tokens === null).map((task) => task.taskId);
+    const waveTokens = proposed.reduce((sum, task) => sum + (task.tokens ?? 0), 0);
+    if (options.epicId.trim().length === 0) {
+        return {
+            epicId: null,
+            capTokens,
+            measuredTokens: 0,
+            projectedTokens: 0,
+            headroomTokens: capTokens,
+            waveTokens,
+            waveTaskCount,
+            unpricedTasks,
+            inFlightTasks: 0,
+            maxInFlightTasks,
+            status: 'not-applicable',
+            detail: NOT_APPLICABLE_DETAIL,
+        };
+    }
+    const epicId = options.epicId;
+    // No session id means no lineage to read, so checkBudgetAlarm is not asked a
+    // question it cannot answer -- it would fold an empty event list into its
+    // synthetic `*` entry and hand back zeros indistinguishable from a genuine
+    // first wave. The zeros below are the same zeros, but the status that
+    // carries them says which kind they are.
+    const hasSession = options.sessionId.trim().length > 0;
+    const report = hasSession
+        ? checkBudgetAlarm(events, policy, { sessionId: options.sessionId, epicId })
+        : undefined;
+    const epicCheck = report?.epics[0];
+    // checkBudgetAlarm emits a synthetic `epicId: '*'` entry exactly when it
+    // found no event attributing anything to this epic id (its own comment on
+    // the empty-epics-array branch) -- that is this epic's genuine first wave,
+    // not a hole in the record, so it is measured at zero rather than reported
+    // unverifiable.
+    const isFirstWave = epicCheck === undefined || epicCheck.epicId === '*';
+    const measuredTokens = isFirstWave ? 0 : epicCheck.measuredTokens;
+    const projectedTokens = isFirstWave ? 0 : epicCheck.projectedTokens;
+    const headroomTokens = Math.max(0, capTokens - projectedTokens);
+    const inFlight = inFlightTasks(events, epicId).length;
+    const base = {
+        epicId,
+        capTokens,
+        measuredTokens,
+        projectedTokens,
+        headroomTokens,
+        waveTokens,
+        waveTaskCount,
+        unpricedTasks,
+        inFlightTasks: inFlight,
+        maxInFlightTasks,
+    };
+    if (unpricedTasks.length > 0) {
+        return { ...base, status: 'unverifiable', detail: unverifiableDetail(unpricedTasks) };
+    }
+    if (maxInFlightTasks !== null && inFlight + waveTaskCount > maxInFlightTasks) {
+        return {
+            ...base,
+            status: 'over-fan-out',
+            detail: overFanOutDetail(inFlight, waveTaskCount, maxInFlightTasks),
+        };
+    }
+    if (projectedTokens + waveTokens > capTokens) {
+        return {
+            ...base,
+            status: 'refused',
+            detail: refusedDetail(projectedTokens, waveTokens, capTokens),
+        };
+    }
+    if (!hasSession) {
+        return { ...base, status: 'unchecked', detail: uncheckedDetail(waveTokens, capTokens) };
+    }
+    return { ...base, status: 'ok', detail: okDetail(headroomTokens, waveTokens, capTokens) };
+}