@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/epicWidth.js

@@ -0,0 +1,238 @@
+import { UNOBSERVED_HINT } from './waveConcurrency.js';
+/**
+ * Does this factory build in parallel, or has every epic it closed been narrow?
+ *
+ * The wave commands each answer half a question and all four share a boundary:
+ * `wave schedule` says how wide a plan could run, `wave check` admits a wave,
+ * `wave audit` reads one log back to see whether the admission was honoured,
+ * and `epic close` writes that reading permanently into `epic-closed`. Every
+ * one of them is scoped to the session the operator happens to be standing in.
+ * The claim this repo actually makes — that a project here is built by many
+ * agents working a plan's tasks at the same time — is a claim about the
+ * workshop, and nothing could be asked it.
+ *
+ * So this folds closes rather than waves. Two reasons, and the second is the
+ * one that matters:
+ *
+ * 1. A close outlives its lineage. The `wave-admitted` and `dispatch_decision`
+ *    events behind it sit in whichever session ran the build, and an operator
+ *    asking about the factory is not standing in any of them. The width was
+ *    copied into the close precisely so it would still be there afterwards.
+ *
+ * 2. Re-deriving cannot see a close that measured nothing. `auditWaveConcurrency`
+ *    reports the waves that exist; it has no way to report an epic whose close
+ *    carried no width at all — an older close from before the field, or one
+ *    whose record could not be read. Those closes are the honest answer to
+ *    "how much of this do you actually know", and a summary that silently
+ *    omitted them would report a factory of three measured epics exactly as
+ *    confidently as a factory of three hundred.
+ */
+const CLOSED_EVENT_TYPE = 'epic-closed';
+/** The verdicts an epic can be graded on, widest first — see {@link gradeOf}. */
+const BEST_FIRST = [
+    'parallel',
+    'partial',
+    'serialized',
+    'single',
+    'unobserved',
+];
+const ALL_VERDICTS = [
+    ...BEST_FIRST,
+    'unwaved',
+    'unmeasured',
+    'unreadable',
+];
+/**
+ * Said when no close carried a width anybody could read.
+ *
+ * The distinction this hint exists to protect is the one an exit code cannot
+ * carry: "every epic closed narrow" and "no epic was ever measured" are
+ * opposite states of knowledge, and a factory that has never measured itself
+ * must not be able to read as a healthy one.
+ */
+export const UNMEASURED_HINT = 'No close read here carried a width. Either these epics were closed before `smith epic close` ' +
+    'recorded one, or the closes were written by hand — close a current epic with `smith epic ' +
+    'close`, or read a live log back with `smith wave audit --session <id>`.';
+/** Nothing was recorded, or nothing readable was. */
+function blank(verdict, problem) {
+    return {
+        verdict,
+        waves: 0,
+        byVerdict: Object.fromEntries(BEST_FIRST.map((v) => [v, 0])),
+        widest: { declared: 0, observed: 0 },
+        unobserved: [],
+        problem,
+    };
+}
+function countsFrom(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const source = raw;
+    const counts = {};
+    for (const verdict of BEST_FIRST) {
+        const n = source[verdict];
+        // A missing key is not read as zero. The close projects all five even at
+        // zero (D-126), so an absent one means this is not a width record at all,
+        // and defaulting it would turn a malformed payload into a confident count.
+        if (typeof n !== 'number' || !Number.isFinite(n) || n < 0)
+            return null;
+        counts[verdict] = n;
+    }
+    return counts;
+}
+function widthFrom(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const { declared, observed } = raw;
+    if (typeof declared !== 'number' || typeof observed !== 'number')
+        return null;
+    return { declared, observed };
+}
+/**
+ * The epic's verdict is the BEST any of its waves reached, not the worst.
+ *
+ * The question this answers is whether the epic ever ran wide. An epic that
+ * ran three waves in parallel and one serially is the factory working, and
+ * grading it by its narrowest wave would report every real build as a failure
+ * — which is how a signal becomes a constant and then becomes noise. The
+ * serial wave is not thereby hidden: `EpicWidthSummary.serialized` names the
+ * epic and the exit code still fails on it. The verdict summarises the epic;
+ * it does not speak for every wave inside it.
+ */
+function gradeOf(counts, waves) {
+    if (waves === 0)
+        return 'unwaved';
+    for (const verdict of BEST_FIRST)
+        if (counts[verdict] > 0)
+            return verdict;
+    // Unreachable: every wave carries one of the five. Reported rather than
+    // guessed, because a count that adds up to nothing is a malformed record.
+    return 'unwaved';
+}
+/** Read one close's recorded width, or say why it could not be read. */
+function widthOf(payload) {
+    const summary = payload.summary;
+    const raw = typeof summary === 'object' && summary !== null
+        ? summary.concurrency
+        : undefined;
+    // Absent and explicitly null are the same answer — nobody measured — and
+    // they are BOTH different from a record of zero waves. An older close
+    // predating the field has no key; a close that measured and found no wave
+    // projects `waves: 0`. Collapsing those would let the factory's unmeasured
+    // history read as a history of epics that simply never cut a wave.
+    if (raw === undefined || raw === null)
+        return blank('unmeasured', null);
+    if (typeof raw !== 'object') {
+        return blank('unreadable', `epic-width.malformed-record: concurrency is not an object`);
+    }
+    const record = raw;
+    const counts = countsFrom(record.verdicts);
+    const widest = widthFrom(record.widest);
+    if (typeof record.waves !== 'number' || counts === null || widest === null) {
+        return blank('unreadable', 'epic-width.malformed-record: the recorded concurrency has no readable waves, verdicts or widest');
+    }
+    // The close's own refusal, carried through rather than re-judged. `epic
+    // close` catches an unreadable wave record so the close is not lost over it
+    // (D-21); reading that as a measured zero here would undo exactly that care.
+    const problem = typeof record.problem === 'string' ? record.problem : null;
+    return {
+        verdict: problem !== null ? 'unreadable' : gradeOf(counts, record.waves),
+        waves: record.waves,
+        byVerdict: counts,
+        widest,
+        unobserved: Array.isArray(record.unobserved)
+            ? record.unobserved.filter((id) => typeof id === 'string')
+            : [],
+        problem,
+    };
+}
+function str(value) {
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * Fold every `epic-closed` in these events into one closed epic each.
+ *
+ * Keyed on the payload's `epic_id` and never on `task_id`, and last close
+ * wins — both rules `foldEpics` already keeps, for the reasons it documents:
+ * the dogfood close used an unreserved `<epic>/epic` task id that would mint a
+ * phantom epic here, and re-closing an epic is a correction rather than a
+ * second epic.
+ */
+export function readClosedEpicWidths(events) {
+    const byId = new Map();
+    for (const { event_id, record } of events) {
+        if (record.event_type !== CLOSED_EVENT_TYPE)
+            continue;
+        const payload = record.payload;
+        const epicId = str(payload.epic_id);
+        // No epic id means no epic to speak for. Inferring one is the phantom-card
+        // inference D-43 exists to prevent.
+        if (epicId === null)
+            continue;
+        byId.set(epicId, {
+            epicId,
+            eventId: event_id,
+            closedAt: record.ts,
+            sessionId: record.session_id,
+            project: record.project ?? null,
+            closedBy: str(payload.closed_by) ?? 'unspecified',
+            machineVerdict: str(payload.machine_verdict),
+            ...widthOf(payload),
+        });
+    }
+    return [...byId.values()];
+}
+/**
+ * Score the factory.
+ *
+ * Exit 1 is a closed epic whose record holds a `serialized` wave — admitted
+ * wider than one task and never running two at once. It is the same fact
+ * `wave audit` exits 1 on, deliberately: an operator who learned that code has
+ * learned this one, and a second rule for the same failure is a second answer
+ * waiting to disagree.
+ *
+ * What is NOT exit 1, and the discipline this depends on: a narrow epic. An
+ * epic whose tasks genuinely depend on one another has nothing to run side by
+ * side, and `unwaved` and `single` are not faults. Failing on those would fire
+ * on every honest serial build in the repo, and a code that fires on
+ * everything is routed to /dev/null inside a week — taking the serialized one
+ * with it.
+ *
+ * Exit 2 is the `judge escalations` shape: nothing was judged. Either an
+ * admitted wave has no work behind it — a declaration with nothing under it,
+ * which epic.ts already tells the judge is the refutable case — or no close
+ * carried a width at all, which is the state an empty factory is in and must
+ * never be able to report as a healthy one.
+ */
+export function summariseEpicWidth(events) {
+    const epics = readClosedEpicWidths(events).sort((a, b) => a.closedAt === b.closedAt
+        ? a.epicId.localeCompare(b.epicId)
+        : b.closedAt.localeCompare(a.closedAt));
+    const verdicts = Object.fromEntries(ALL_VERDICTS.map((v) => [v, 0]));
+    for (const epic of epics)
+        verdicts[epic.verdict] += 1;
+    const serialized = epics.filter((e) => e.byVerdict.serialized > 0).map((e) => e.epicId);
+    const unobserved = epics
+        .filter((e) => e.byVerdict.unobserved > 0 || e.unobserved.length > 0)
+        .map((e) => e.epicId);
+    const unmeasured = epics
+        .filter((e) => e.verdict === 'unmeasured' || e.verdict === 'unreadable')
+        .map((e) => e.epicId);
+    // "Judged" means a width was read and there was a wave in it. An epic that
+    // measured zero waves is measured and is not evidence either way, so it
+    // cannot on its own turn an unmeasured factory into a passing one.
+    const judged = epics.some((e) => e.problem === null && e.waves > 0);
+    return {
+        epics,
+        verdicts,
+        widest: {
+            declared: epics.reduce((max, e) => Math.max(max, e.widest.declared), 0),
+            observed: epics.reduce((max, e) => Math.max(max, e.widest.observed), 0),
+        },
+        serialized,
+        unobserved,
+        unmeasured,
+        hint: unobserved.length > 0 ? UNOBSERVED_HINT : judged ? '' : UNMEASURED_HINT,
+        exitCode: serialized.length > 0 ? 1 : unobserved.length > 0 || !judged ? 2 : 0,
+    };
+}

package/factory/orchestrator/dist/errorIssues.js

@@ -0,0 +1,249 @@
+import { createHash } from 'node:crypto';
+/** A `Record` over every `GateBlockedReason`, not a switch with a default: a reason missing from `GateBlockedReason` fails to compile here. */
+const GATE_BLOCKED_ERROR_CLASSES = {
+    'schema-invalid': 'gate.blocked.schema-invalid',
+    'artifacts-missing': 'gate.blocked.artifacts-missing',
+    'not-committed': 'gate.blocked.not-committed',
+    'deps-missing': 'gate.blocked.deps-missing',
+    'judges-outstanding': 'gate.blocked.judges-outstanding',
+    'grader-invalid': 'gate.blocked.grader-invalid',
+    'grader-fail': 'gate.blocked.grader-fail',
+    'tests-failed': 'gate.blocked.tests-failed',
+    'coverage-evidence': 'gate.blocked.coverage-evidence',
+    findings: 'gate.blocked.findings',
+};
+/** Exported for the table-driven test: the ten reasons, read off the table above rather than hand-copied a second time. */
+export const GATE_BLOCKED_REASONS = Object.keys(GATE_BLOCKED_ERROR_CLASSES);
+/** A blocked gate and a failed task carry no payload-level severity; both block a task outright, matching taxonomy.yml's `S2-major`. */
+const BLOCKING_SEVERITY = 'S2-major';
+const GATE_OUTCOME_EVENT_TYPE = 'gate-outcome';
+const ERROR_LOGGED_EVENT_TYPE = 'error-logged';
+const TASK_ADDED_EVENT_TYPE = 'task-added';
+/**
+ * Source 2: `task_status: failed` is set in exactly one place in the whole
+ * projector, `db/projector.ts`'s `case 'task-added'` arm copying
+ * `p.task_status` verbatim -- every other case assigns a hardcoded literal,
+ * never a payload-derived value. So this source is always a `task-added`
+ * event whose own payload already declares `task_status: 'failed'`, and
+ * carries no failure discriminator beyond that.
+ */
+const TASK_FAILED_ERROR_CLASS = 'task.failed';
+/** Default project for an event stamped with none (events.ts's documented convention; the writer never sets it, only read helpers default it). */
+const DEFAULT_PROJECT = 'black-smith';
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * One event to a `Candidate`, `'ignore'` when it is not one of the three
+ * sources at all, or `null` when it matches a source's shape but is missing
+ * a required field (malformed, counted by the caller as `skipped`).
+ */
+function toCandidate(event) {
+    const { record } = event;
+    const payload = record.payload ?? {};
+    const project = asString(record.project) ?? DEFAULT_PROJECT;
+    const sessionId = asString(record.session_id);
+    const planVersion = asNumber(record.plan_version) ?? null;
+    const ts = asString(record.ts);
+    if (record.event_type === GATE_OUTCOME_EVENT_TYPE) {
+        if (payload.outcome !== 'blocked')
+            return 'ignore';
+        const reasonRaw = asString(payload.reason);
+        const taskRef = asString(record.task_id);
+        if (!sessionId || !ts || !taskRef || !reasonRaw)
+            return null;
+        if (!(reasonRaw in GATE_BLOCKED_ERROR_CLASSES))
+            return null;
+        const reason = reasonRaw;
+        return {
+            project,
+            source: 'gate-outcome',
+            errorClass: GATE_BLOCKED_ERROR_CLASSES[reason],
+            taskRef,
+            severity: BLOCKING_SEVERITY,
+            eventId: event.event_id,
+            ts,
+            sessionId,
+            epicId: null,
+            planVersion,
+        };
+    }
+    if (record.event_type === ERROR_LOGGED_EVENT_TYPE) {
+        const errorClass = asString(payload.error);
+        const severity = asString(payload.severity);
+        const taskRef = asString(record.task_id) ?? asString(payload.task_ref);
+        if (!sessionId || !ts || !taskRef || !errorClass || !severity)
+            return null;
+        return {
+            project,
+            source: 'error-logged',
+            errorClass,
+            taskRef,
+            severity,
+            eventId: event.event_id,
+            ts,
+            sessionId,
+            epicId: null,
+            planVersion,
+        };
+    }
+    if (record.event_type === TASK_ADDED_EVENT_TYPE) {
+        if (payload.task_status !== 'failed')
+            return 'ignore';
+        const taskRef = asString(record.task_id);
+        if (!sessionId || !ts || !taskRef)
+            return null;
+        const epicId = asString(payload.epic_id) ?? null;
+        return {
+            project,
+            source: 'task-failed',
+            errorClass: TASK_FAILED_ERROR_CLASS,
+            taskRef,
+            severity: BLOCKING_SEVERITY,
+            eventId: event.event_id,
+            ts,
+            sessionId,
+            epicId,
+            planVersion,
+        };
+    }
+    return 'ignore';
+}
+/**
+ * The first 16 hex characters of a SHA-256 over the NUL-joined tuple
+ * `project`, `source`, `error_class`, `task_ref`. Deliberately excludes
+ * session id, epic id, plan version, event id and timestamp -- those are
+ * exactly the fields that change across repeated rounds of one broken gate,
+ * and including any of them would open one issue per round instead of one.
+ */
+function computeFingerprint(project, source, errorClass, taskRef) {
+    const material = [project, source, errorClass, taskRef].join('\0');
+    return createHash('sha256').update(material).digest('hex').slice(0, 16);
+}
+/**
+ * Fold a stored event sequence into reportable errors. Pure: two calls with
+ * identical input return byte-identical output. `now` is threaded in rather
+ * than read off the clock; nothing in this contract branches on it yet.
+ */
+export function foldErrorEvents(events, now, isProjectEnabled) {
+    void now;
+    const candidates = [];
+    let skipped = 0;
+    for (const event of events) {
+        const outcome = toCandidate(event);
+        if (outcome === 'ignore')
+            continue;
+        if (outcome === null) {
+            skipped += 1;
+            continue;
+        }
+        if (!isProjectEnabled(outcome.project))
+            continue;
+        candidates.push(outcome);
+    }
+    const groups = new Map();
+    for (const candidate of candidates) {
+        const fingerprint = computeFingerprint(candidate.project, candidate.source, candidate.errorClass, candidate.taskRef);
+        const group = groups.get(fingerprint);
+        if (group)
+            group.push(candidate);
+        else
+            groups.set(fingerprint, [candidate]);
+    }
+    const reports = [];
+    for (const [fingerprint, group] of groups) {
+        const latest = group.reduce((a, b) => b.ts > a.ts || (b.ts === a.ts && b.eventId > a.eventId) ? b : a);
+        for (const candidate of group) {
+            reports.push({
+                fingerprint,
+                project: candidate.project,
+                source: candidate.source,
+                error_class: candidate.errorClass,
+                task_ref: candidate.taskRef,
+                severity: latest.severity,
+                latest_event_id: latest.eventId,
+                timestamp: latest.ts,
+                session_id: latest.sessionId,
+                epic_id: latest.epicId,
+                plan_version: latest.planVersion,
+            });
+        }
+    }
+    return { reports, skipped };
+}
+// Rendering -- metadata and pointers only, safe by construction. Both
+// renderers take the same shape of typed record, built from an ErrorReport,
+// never a raw source event: neither signature has a free-text field.
+/** The fixed literal format of the machine-readable fingerprint line, exported so the dedup search and the renderer read the same constant. */
+export const FINGERPRINT_LINE_PREFIX = 'Fingerprint: ';
+function fingerprintLine(fingerprint) {
+    return `${FINGERPRINT_LINE_PREFIX}${fingerprint}`;
+}
+/** The local, read-only command an operator runs to see the detail this body/comment deliberately omit. */
+function smithEventCommand(sessionId) {
+    return `smith event tail ${sessionId} --lineage`;
+}
+/** Builds a body-renderer input record from a folded report -- the record's key set is the allowlist; nothing else can reach `renderBody`. */
+export function toIssueBodyFields(report) {
+    return {
+        latest_event_id: report.latest_event_id,
+        task_ref: report.task_ref,
+        error_class: report.error_class,
+        severity: report.severity,
+        session_id: report.session_id,
+        epic_id: report.epic_id,
+        plan_version: report.plan_version,
+        project: report.project,
+        source: report.source,
+        fingerprint: report.fingerprint,
+    };
+}
+/** Builds a comment-renderer input record from a folded report -- same allowlist-by-construction guarantee, same mechanism. */
+export function toIssueCommentFields(report) {
+    return {
+        latest_event_id: report.latest_event_id,
+        timestamp: report.timestamp,
+        session_id: report.session_id,
+        epic_id: report.epic_id,
+        plan_version: report.plan_version,
+        fingerprint: report.fingerprint,
+    };
+}
+/** The issue title: stable, human-first, derived only from allowlisted fields. */
+export function renderTitle(fields) {
+    return `${fields.task_ref}: ${fields.error_class}`;
+}
+/** Issue body -- metadata and pointers only, opened once per fingerprint. */
+export function renderBody(fields) {
+    return [
+        `Task: ${fields.task_ref}`,
+        `Error class: ${fields.error_class}`,
+        `Severity: ${fields.severity}`,
+        `Session: ${fields.session_id}`,
+        `Epic: ${fields.epic_id ?? '(none)'}`,
+        `Plan version: ${fields.plan_version ?? '(unknown)'}`,
+        `Project: ${fields.project}`,
+        `Source: ${fields.source}`,
+        fingerprintLine(fields.fingerprint),
+        '',
+        'Read the detail locally:',
+        `\`${smithEventCommand(fields.session_id)}\``,
+    ].join('\n');
+}
+/** Issue comment -- the higher-volume write path (five rounds of one broken gate write one body and four comments). Same allowlist construction. */
+export function renderComment(fields) {
+    return [
+        `New occurrence: ${fields.latest_event_id}`,
+        `Timestamp: ${fields.timestamp}`,
+        `Session: ${fields.session_id}`,
+        `Epic: ${fields.epic_id ?? '(none)'}`,
+        `Plan version: ${fields.plan_version ?? '(unknown)'}`,
+        fingerprintLine(fields.fingerprint),
+        '',
+        'Read the detail locally:',
+        `\`${smithEventCommand(fields.session_id)}\``,
+    ].join('\n');
+}

package/factory/orchestrator/dist/errors.js

@@ -0,0 +1,11 @@
+/** Shared typed-error base for every orchestrator module (one pattern, reused). */
+export class SmithError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.details = Object.freeze({ ...details });
+    }
+}