@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/taskEvents.js

@@ -0,0 +1,399 @@
+import { appendEdge, appendEvent, readLineageEvents, } from './events.js';
+import { resolveTaskId } from './plan.js';
+import { taskBranchName } from './worktree.js';
+function envelope(ctx, eventType, payload, taskId) {
+    return {
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'system',
+        event_type: eventType,
+        plan_version: ctx.planVersion,
+        causal_parent: ctx.causalParent,
+        payload,
+        ...(taskId ? { task_id: taskId } : {}),
+        ...(ctx.project ? { project: ctx.project } : {}),
+    };
+}
+/**
+ * The project this write belongs to: what the caller declared, else what the
+ * plan does.
+ *
+ * D-232. Every plan file under factory/specs/ carries a `project`, and until
+ * now nothing at runtime read it -- `plan ingest` handed the plan straight to
+ * emitTasksAdded, which used it for the epic id and the task specs and let the
+ * project fall on the floor. Every event of a demo-rpg run therefore landed
+ * with no project at all, and db/queries.ts's projectOf() resolves an absent
+ * one to the default: a whole epic filed under black-smith, missing from the
+ * board of the project it was actually part of.
+ *
+ * The plan is the fallback and not an override, because a caller holding a
+ * project knows something the file cannot -- and an absent value stays absent
+ * rather than becoming the default here, which is events.ts's rule: the log
+ * records what was stamped, and the read helpers do the resolving.
+ */
+function planScoped(ctx, plan) {
+    const project = ctx.project ?? plan.project;
+    return project === undefined ? ctx : { ...ctx, project };
+}
+function addedPayload(plan, task) {
+    const budget = task.budget;
+    // A task spec is a `Record<string, unknown>`, so its `epic_id` is only a
+    // string by convention. `taskBranchName` needs a real one, and a task
+    // carrying anything else belongs to the plan's epic by default.
+    const epicId = typeof task.epic_id === 'string' ? task.epic_id : plan.epic_id;
+    return {
+        epic_id: epicId,
+        case: task.case,
+        origin: task.origin,
+        task_status: task.task_status,
+        plan_version: task.plan_version,
+        objective: task.objective,
+        claims: task.claims,
+        budget_tokens: budget?.tokens,
+        // D-23/P9-12. Declared here rather than derived by the reader: the board
+        // wants a branch link the moment a task is added, which is well before a
+        // worktree exists, and worktree.ts's convention is the one that decides
+        // what `smith worktree create` will actually cut. Reading it off the same
+        // function that creates it means the two cannot say different things.
+        branch: taskBranchName(epicId, task.task_id),
+    };
+}
+/**
+ * Collect the task ids that already have an event of `eventType` in this
+ * session's LINEAGE. Ingesting a plan twice — a re-run, a resumed session, v2
+ * of a plan that carries v1's tasks forward — must not double-write history,
+ * and the log itself is the only honest record of what has already been said.
+ *
+ * The lineage and not one session, since D-119: "a resumed session" is exactly
+ * the case a session-scoped read got wrong. Re-ingesting the plan from a
+ * continuation found none of the parent's `task-added` events and wrote the
+ * whole plan a second time, which is the double-write this guard is for.
+ */
+async function idsAlreadyEmitted(eventType, ctx, opts) {
+    const events = await readLineageEvents(ctx.sessionId, opts);
+    const ids = new Set();
+    for (const { record } of events) {
+        if (record.event_type === eventType && record.task_id)
+            ids.add(record.task_id);
+    }
+    return ids;
+}
+/**
+ * The highest `plan_version` each task id has already been *added* under.
+ *
+ * D-18. `idsAlreadyEmitted` answers "has this id been added at all", which is
+ * the wrong question after an amendment: `draftNextVersion` supersedes a task
+ * by REUSING its id (D-121), so v(n+1) carries the dead copy beside a live one
+ * at the higher version. Keyed on the id alone, that live record is invisible,
+ * the amended task keeps the `plan_version` it was first added under, and
+ * `satisfiedAmendments` (epic.ts) — which requires `planVersion >= version` for
+ * every id the amendment names — can never discharge the finding that forced
+ * the amendment. Epic 1 read that deadlock as "ingest was never run"; running
+ * it correctly, at both versions, still deadlocks without this.
+ *
+ * A missing or non-numeric `plan_version` reads as `-Infinity`, so a task added
+ * before this field was carried is re-added once by any plan that names one
+ * rather than being frozen out.
+ */
+async function addedPlanVersions(ctx, opts) {
+    const events = await readLineageEvents(ctx.sessionId, opts);
+    const highest = new Map();
+    for (const { record } of events) {
+        if (record.event_type !== 'task-added' || !record.task_id)
+            continue;
+        const raw = record.payload.plan_version;
+        const version = typeof raw === 'number' && Number.isFinite(raw) ? raw : Number.NEGATIVE_INFINITY;
+        const seen = highest.get(record.task_id);
+        if (seen === undefined || version > seen)
+            highest.set(record.task_id, version);
+    }
+    return highest;
+}
+/**
+ * Read the lineage's log as a register of tasks — every id a `task-added`
+ * has introduced, with the claims it was introduced with.
+ *
+ * D-48/P9-31: a follow-up minted by `findings raise` exists in the log and in
+ * no plan file, so the log has to be readable as a register or that task is
+ * unaddressable by every producer that resolves through a plan. Claims are
+ * carried, not just ids: a wave admitting a task with an empty claim set has
+ * admitted a task allowed to touch nothing, which fails at the first edit
+ * rather than at admission, where the mistake actually is. They are carried
+ * AS WRITTEN for the same reason: substituting `[]` for a claims value this
+ * could not read handed `validateWave` the one claim set that overlaps
+ * nothing, so an unreadable task was admitted as a disjoint one.
+ *
+ * Later events win on a repeated id (a re-add carries the newer claims), and
+ * first-appearance order is kept so the register reads in log order.
+ *
+ * Lineage-wide (D-119). This register is what makes a follow-up task
+ * addressable at all, and a task the parent session minted does not stop
+ * existing because the epic continued somewhere else — a claims check that
+ * cannot find the task it is checking is a claims check that passes.
+ */
+export async function readAddedTasks(
+// Reading takes only the session — a caller that is not writing should not
+// have to invent a causal parent to ask what exists.
+ctx, opts = {}) {
+    const events = await readLineageEvents(ctx.sessionId, opts);
+    const byId = new Map();
+    for (const { record } of events) {
+        if (record.event_type !== 'task-added' || !record.task_id)
+            continue;
+        byId.set(record.task_id, { taskId: record.task_id, claims: record.payload?.claims });
+    }
+    return [...byId.values()];
+}
+/**
+ * One record per task id, in plan order: the id's live spec, or its last
+ * record when every record for the id is dead.
+ *
+ * D-184. `plan.tasks` is not a backlog. `draftNextVersion` keeps each
+ * superseded copy of a task *beside* the record that replaced it, under the
+ * same `task_id` (D-121), so a v(n+1) file is routinely longer than the work
+ * it describes — envkit-mcp-surface's plan-v5.json holds 13 records for 5
+ * live tasks, four ids appearing three times each. This is the same rule
+ * `liveSpec`/`livePlanTasks` apply in plan.ts, and for the same reason D-126
+ * gave: reading the raw list answers with whichever copy happened to be
+ * written last. It is repeated here rather than imported because the dead
+ * ids matter to this caller — `livePlanTasks` drops them, and an id whose
+ * every record is dead is exactly the one that needs a `task-superseded`.
+ */
+function specsToIngest(plan) {
+    const seen = new Set();
+    const specs = [];
+    for (const t of plan.tasks) {
+        if (seen.has(t.task_id))
+            continue;
+        seen.add(t.task_id);
+        const records = plan.tasks.filter((r) => r.task_id === t.task_id);
+        const live = records.filter((r) => r.task_status !== 'superseded');
+        // Last, not first: among the records still alive the later one is the
+        // amendment, which is what `liveSpec` means by "the live spec". `?? t`
+        // is unreachable — `records` always holds `t` — and is written rather
+        // than asserted so the array access needs no cast to stay honest.
+        const pool = live.length > 0 ? live : records;
+        specs.push(pool[pool.length - 1] ?? t);
+    }
+    return specs;
+}
+/**
+ * Write the plan's backlog into the log: one `task-added` per task id the
+ * session has not already recorded, plus a `task-superseded` for any id the
+ * plan has no live spec left for (a v(n+1) cut records that as plan state,
+ * and the projector needs it as an event to reach the same conclusion).
+ *
+ * Per id, not per record — see `specsToIngest`. Emitting the dead copies too
+ * would say two false things at once: that a task the plan still lists as
+ * `todo` was superseded, and that a 5-task backlog is 13 tasks.
+ *
+ * Returns only the events it actually appended, so a caller can report "5
+ * added, 0 already present" truthfully rather than guessing from the plan.
+ */
+export async function emitTasksAdded(plan, ctx, opts = {}) {
+    const added = await addedPlanVersions(ctx, opts);
+    const superseded = await idsAlreadyEmitted('task-superseded', ctx, opts);
+    const scoped = planScoped(ctx, plan);
+    const written = [];
+    // The ids the plan marks as superseded-and-replaced: a dead record beside a
+    // live one under the same id is how `draftNextVersion` records an amendment.
+    const supersededIds = new Set(plan.tasks.filter((r) => r.task_status === 'superseded').map((r) => r.task_id));
+    for (const task of specsToIngest(plan)) {
+        const taskId = task.task_id;
+        // Re-add only when the live spec has genuinely moved forward: an id absent
+        // from the log, or one whose live record now carries a HIGHER plan_version
+        // than anything added for it. Equal versions stay idempotent — the same
+        // plan ingested twice is still one `task-added` — and a lower version is a
+        // stale file, not an amendment, so it is ignored rather than honoured.
+        const recorded = added.get(taskId);
+        const liveVersion = task.plan_version;
+        // D-18b. A higher version alone is not enough: `draftNextVersion` restamps
+        // EVERY task with the new plan_version, carried ones included, so keying on
+        // the number would re-add tasks whose spec never changed. The amendment's
+        // own marker is what counts — an id the amendment touched carries a dead
+        // record beside its live one, which is exactly what `supersededIds` holds.
+        const amended = recorded !== undefined &&
+            supersededIds.has(taskId) &&
+            typeof liveVersion === 'number' &&
+            liveVersion > recorded;
+        if (recorded === undefined || amended) {
+            written.push(await appendEvent(envelope(scoped, 'task-added', addedPayload(plan, task), taskId), opts));
+        }
+        if (task.task_status === 'superseded' && !superseded.has(taskId)) {
+            written.push(await appendEvent(envelope(scoped, 'task-superseded', { epic_id: plan.epic_id }, taskId), opts));
+        }
+    }
+    return written;
+}
+/** One arrow's identity in the log: who depends on whom, and in what sense. */
+function edgeKey(task, dependsOn, edgeType) {
+    return `${task}\u0000${dependsOn}\u0000${edgeType}`;
+}
+/**
+ * The edges this session's LINEAGE has already recorded, keyed by the triple
+ * `edgeKey` spells rather than by task id the way `idsAlreadyEmitted` is.
+ *
+ * A task has as many arrows as it has dependencies, so a task-keyed register
+ * would record the first and drop the rest. And the third component is not
+ * decoration: demo-rpg-chapter-reading's plan-v1 declares both an `artifact`
+ * and a `claim-order` handoff between the same two tasks, which are two
+ * different claims about one pair and belong in the log as two events.
+ *
+ * The lineage and not one session, for D-119's reason -- a resumed session
+ * re-ingests the plan it was resumed into, and a session-scoped read would
+ * see none of what its parent already wrote.
+ */
+async function edgesAlreadyRecorded(ctx, opts) {
+    const events = await readLineageEvents(ctx.sessionId, opts);
+    const keys = new Set();
+    for (const { record } of events) {
+        if (record.event_type !== 'edge-recorded' || !record.task_id || !record.edge)
+            continue;
+        const dependsOn = record.payload.depends_on;
+        if (typeof dependsOn !== 'string')
+            continue;
+        keys.add(edgeKey(record.task_id, dependsOn, record.edge.edge_type));
+    }
+    return keys;
+}
+/**
+ * Write the plan's DAG into the log: one `edge-recorded` per dependency the
+ * plan declares that this lineage has not already recorded.
+ *
+ * D-254. `emitTasksAdded` above ingests the nodes; this ingests the arrows,
+ * and until it existed nothing in production ever wrote an `edge-recorded`
+ * event at all. The consequence was not a missing feature but a wrong answer:
+ * the db's `edges` table was empty in every real session, so the Flow page
+ * drew a DAG with no dependencies and laid all 26 tasks out in a single wave,
+ * and the Roadmap's mini-timeline reported `dependencyReady` for every next-up
+ * task -- vacuously true over an empty dependency list. The scheduler was
+ * never wrong, because it reads `plan.edges` from the file directly; only
+ * every surface an operator looks at was.
+ *
+ * Both ends are resolved against the plan before anything is appended, so a
+ * plan whose DAG names a task it does not contain is refused whole. That is
+ * `emitWaveAdmitted`'s rule and `validatePlan`'s rule; an arrow written to a
+ * ghost would be dropped silently by every reader instead of seen by anyone.
+ */
+export async function emitEdgesRecorded(plan, ctx, opts = {}) {
+    const resolved = plan.edges.map((e) => ({
+        task: resolveTaskId(plan, e.task),
+        dependsOn: resolveTaskId(plan, e.dependsOn),
+        edge_type: e.edge_type,
+        edge_provenance: e.edge_provenance,
+    }));
+    const recorded = await edgesAlreadyRecorded(ctx, opts);
+    const scoped = planScoped(ctx, plan);
+    const written = [];
+    for (const edge of resolved) {
+        const key = edgeKey(edge.task, edge.dependsOn, edge.edge_type);
+        // Guards the plan against itself as well as against a re-ingest: an edge
+        // the file states twice verbatim says nothing the first one did not.
+        if (recorded.has(key))
+            continue;
+        recorded.add(key);
+        written.push(await appendEdge(envelope(scoped, 'edge-recorded', { epic_id: plan.epic_id, depends_on: edge.dependsOn }, edge.task), { edge_type: edge.edge_type, edge_provenance: edge.edge_provenance }, opts));
+    }
+    return written;
+}
+/**
+ * Record that a wave was admitted. Every id is resolved against the plan and
+ * the log's own register BEFORE anything is appended, so a wave naming one
+ * task that does not exist is refused whole rather than half-written — a
+ * partially admitted wave is precisely the state that has no owner and no way
+ * back. The register is read here rather than passed in (D-48/P9-31) so no
+ * caller can forget it and quietly lose the ability to admit a follow-up.
+ */
+export async function emitWaveAdmitted(plan, typedIds, ctx, opts = {}, budget) {
+    const logged = (await readAddedTasks(ctx, opts)).map((t) => t.taskId);
+    const taskIds = typedIds.map((typed) => resolveTaskId(plan, typed, logged));
+    return appendEvent(envelope(planScoped(ctx, plan), 'wave-admitted', {
+        epic_id: plan.epic_id,
+        task_ids: taskIds,
+        ...(budget ? { budget } : {}),
+    }), opts);
+}
+/**
+ * Record that one task's branch landed on the integration branch. One event
+ * per task, carrying a single-element `task_ids`, rather than one event per
+ * wave: a merge queue that gets three tasks in and fails on the fourth has
+ * genuinely merged three, and the log should say so. A wave-shaped event
+ * could only be written after the whole wave finished, which is exactly when
+ * a crash would lose it.
+ *
+ * `filesChanged` is what the merge actually rewrote (P9-15). Optional because
+ * only the queue can compute it and only after the merge commit exists; a
+ * caller that cannot supply it writes the event without the field rather than
+ * with an empty list, so "no file list here" and "this merge changed nothing"
+ * stay distinguishable to the staleness check reading them back.
+ */
+export async function emitWaveMerged(taskId, ctx, opts = {}, filesChanged) {
+    const payload = { task_ids: [taskId] };
+    if (filesChanged !== undefined)
+        payload.files_changed = [...filesChanged];
+    return appendEvent(envelope(ctx, 'wave-merged', payload, taskId), opts);
+}
+/**
+ * Record that a task is blocked by a classified error. `error` must be a
+ * taxonomy error class — appendEvent enforces that, and a `coordination.`
+ * prefix is what makes the projector escalate rather than block, so a
+ * mis-typed class is a wrong status, not just a wrong label.
+ */
+export async function emitTaskBlocked(taskId, error, ctx, opts = {}) {
+    return appendEvent(envelope(ctx, 'error-logged', {
+        error: error.error,
+        severity: error.severity,
+        task_ref: taskId,
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+    }, taskId), opts);
+}
+/**
+ * The id of the follow-up task an unownable finding opens against its epic
+ * (D-41/P9-24). Derived from the fingerprint so it is stable: re-running the
+ * same gate over the same evidence re-derives the same id and
+ * `emitFollowUpTask` recognises it as already written, rather than minting a
+ * second task for one bug.
+ *
+ * The `followup-` prefix keeps it clear of db/projector.ts's `isReservedRef`
+ * guard, which drops any id whose last segment is `integration` or a
+ * `plan-v<n>` plan ref — a follow-up that the projector refused to
+ * materialise would block nothing.
+ */
+export function followUpTaskId(epicId, fingerprint) {
+    return `${epicId}/followup-${fingerprint.slice(0, 8)}`;
+}
+/**
+ * Record a follow-up task for a finding no open task can own: the file's
+ * owner already merged, two tasks claim it equally, or nobody claims it at
+ * all. `origin: escalation` because that is literally what happened — the
+ * gate could not settle it and handed it up to the epic.
+ *
+ * Returns null when the session already carries this task, so a re-run is a
+ * no-op rather than a duplicate. The task is `todo`, which is not terminal-OK,
+ * so epic.ts's `summarizeEpic` blocks the epic verdict on it until an operator
+ * plans or waives it — the "blocks the epic verdict instead of an unrelated
+ * diff" half of P9-24, using the machinery that was already there.
+ */
+export async function emitFollowUpTask(input, ctx, opts = {}) {
+    const added = await idsAlreadyEmitted('task-added', ctx, opts);
+    if (added.has(input.taskId))
+        return null;
+    return appendEvent(envelope(ctx, 'task-added', {
+        epic_id: input.epicId,
+        case: 'bugfix',
+        origin: 'escalation',
+        task_status: 'todo',
+        plan_version: ctx.planVersion,
+        objective: input.objective,
+        claims: input.claims,
+    }, input.taskId), opts);
+}
+/**
+ * Record that a task was replaced by a later plan version. Resolves against
+ * the log's register too (D-48/P9-31): superseding is one of the two terminal
+ * exits a follow-up needs, and a follow-up is never in the plan.
+ */
+export async function emitTaskSuperseded(plan, typed, ctx, opts = {}) {
+    const logged = (await readAddedTasks(ctx, opts)).map((t) => t.taskId);
+    const taskId = resolveTaskId(plan, typed, logged);
+    return appendEvent(envelope(planScoped(ctx, plan), 'task-superseded', { epic_id: plan.epic_id }, taskId), opts);
+}

package/factory/orchestrator/dist/taskId.js

@@ -0,0 +1,126 @@
+// The one place that knows what a task id is shaped like (D-49/P9-10).
+//
+// Task ids are "<epic>/<bare>" — plan.ts mints them, worktree.ts branches on
+// them, findings.ts and the projector group by them. Four call sites derived
+// the epic with `taskId.split('/')[0]`, and that expression has no failure
+// mode: given an unqualified "task-0" it returns "task-0" and the caller
+// reads it as an epic named "task-0". Nothing throws, nothing logs, and the
+// comparison against the real epic quietly misses — the dogfood epic showed
+// up in `smith epic verdict` as "has no tasks in the event log" while three
+// tasks sat in it.
+//
+// So the derivation lives here once, and its unqualified answer is `null`,
+// not a plausible lie. A caller that cannot proceed without an epic asks
+// requireEpicOfTaskId() and gets a typed error naming the id.
+import { SmithError } from './errors.js';
+export class TaskIdError extends SmithError {
+}
+const SEPARATOR = '/';
+/**
+ * Split a task id into its epic and bare halves, or null when it has no
+ * usable epic segment. Both halves must be non-empty: "/task-2" and "epic-1/"
+ * are malformed, not qualified.
+ *
+ * The bare half keeps every remaining separator ("epic-1/followup-ab/extra"
+ * -> epic "epic-1", bare "followup-ab/extra"): the epic is the FIRST segment
+ * by definition, and re-joining epic + bare must round-trip the input.
+ *
+ * D-135: the `string` in the signature is a claim, not a guarantee. Every id
+ * that reaches these helpers has been through a JSONL round-trip, where a
+ * field the writer never set arrives as `undefined` and TypeScript is no
+ * longer watching. `undefined.indexOf` threw a bare TypeError with no code
+ * and no id in it, from inside a reader three call frames from the bad
+ * record. A non-string names no epic, which is exactly what `null` says.
+ */
+function split(taskId) {
+    if (typeof taskId !== 'string')
+        return null;
+    const index = taskId.indexOf(SEPARATOR);
+    if (index <= 0)
+        return null;
+    const epicId = taskId.slice(0, index);
+    const bare = taskId.slice(index + 1);
+    return bare.length === 0 ? null : { epicId, bare };
+}
+/** The epic a task id names, or null when the id does not name one. */
+export function epicOfTaskId(taskId) {
+    return split(taskId)?.epicId ?? null;
+}
+/** Whether `epicOfTaskId` can answer for this id. */
+export function isQualifiedTaskId(taskId) {
+    return split(taskId) !== null;
+}
+/**
+ * The id without its epic prefix; an unqualified id is already bare.
+ *
+ * A non-string answers `''` rather than falling through to `?? taskId`, which
+ * would hand the caller back a non-string through a `: string` signature —
+ * the same class of lie this module exists to stop. `''` is safe at every
+ * comparison site because no real task id is empty, so it can never make two
+ * distinct records look like the same task.
+ */
+export function bareTaskId(taskId) {
+    if (typeof taskId !== 'string')
+        return '';
+    return split(taskId)?.bare ?? taskId;
+}
+/**
+ * Whether two task ids name the same task, across both spellings.
+ *
+ * D-130. `task_id` is written both qualified ("<epic>/<task>") and bare
+ * ("<task>") for the same task — D-46/P9-10 fixed the producers, but the log
+ * is append-only, so every session opened before that fix carries both, and
+ * they interleave rather than splitting cleanly at a cutover point. A raw
+ * `!==` therefore answered a query by the canonical id with a well-formed
+ * SUBSET of the task's history, and a short answer is indistinguishable from
+ * a complete one unless the caller already knows the true count.
+ *
+ * Two qualified ids are still compared whole: "epic-a/task-2" and
+ * "epic-b/task-2" are different tasks that happen to share a bare name, and
+ * folding them together would trade a silent omission for a silent merge.
+ * Only when at least one side is bare — where the epic is genuinely unknown
+ * rather than different — do the bare halves decide it.
+ *
+ * D-143 moved the rule here from `events.ts`, where it was private and only
+ * `filterEvents` could reach it while the findings fold went on comparing
+ * raw. The rule is about what a task id *means*, so it belongs to the module
+ * that owns that question — the same reason `epicOfTaskId` lives here rather
+ * than at its four original call sites.
+ */
+export function taskIdsMatch(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string' || a === '' || b === '')
+        return false;
+    if (a === b)
+        return true;
+    if (isQualifiedTaskId(a) && isQualifiedTaskId(b))
+        return false;
+    return bareTaskId(a) === bareTaskId(b);
+}
+/**
+ * `<epicId>/<taskId>`, idempotent when the id already carries that epic.
+ *
+ * Throws rather than double-prefixing when the id is qualified under a
+ * different epic: `smith/epic-2/epic-1/task-2` is not a branch name anyone
+ * meant, and the mismatch is a real disagreement between two producers about
+ * which epic owns the task — worth an error, not a silent pick.
+ */
+export function qualifyTaskId(epicId, taskId) {
+    const parts = split(taskId);
+    if (parts === null)
+        return `${epicId}${SEPARATOR}${taskId}`;
+    if (parts.epicId === epicId)
+        return taskId;
+    throw new TaskIdError('task-id.epic-mismatch', `Task id "${taskId}" is already qualified under epic "${parts.epicId}"; cannot re-qualify it under "${epicId}".`, { task_id: taskId, epic_id: epicId, qualified_under: parts.epicId });
+}
+/**
+ * The epic, or a typed error. For call sites where an epic is structurally
+ * required — a follow-up task id, a branch name — and inventing one would
+ * produce a valid-looking artifact pointed at nothing.
+ */
+export function requireEpicOfTaskId(taskId) {
+    const epicId = epicOfTaskId(taskId);
+    if (epicId === null) {
+        throw new TaskIdError('task-id.unqualified', `Task id "${taskId}" carries no epic. Task ids are "<epic>/<task>" (plan.ts/worktree.ts); an epic cannot be derived from this one.`, { task_id: taskId });
+    }
+    return epicId;
+}

package/factory/orchestrator/dist/taxonomy.js

@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { SmithError } from './errors.js';
+import { TAXONOMY_PATH } from './paths.js';
+export class TaxonomyError extends SmithError {
+}
+const NON_DIMENSION_KEYS = new Set(['version', 'rules', 'error']);
+// Fields required on a record that are references/collections, not taxonomy
+// tags themselves — presence (non-empty) is enough, no dimension lookup.
+// `model` (P9-23) is required but deliberately open: model ids turn over
+// monthly, and a closed dimension would either reject next month's model or
+// — the likelier outcome — get the field quietly dropped from dispatches
+// instead of the taxonomy being bumped. Presence is what the asymmetry
+// check needs; the exact value is only ever compared against another value.
+const PRESENCE_ONLY_FIELDS = new Set(['task_ref', 'provenance_event_ids', 'model']);
+/** The `error` dimension is validated as a `group.class` pair, not a flat tag. */
+const ERROR_CLASS_FIELD = 'error';
+export function parseTaxonomy(yamlText) {
+    const doc = parseYaml(yamlText);
+    if (!doc || typeof doc !== 'object') {
+        throw new TaxonomyError('taxonomy.invalid-document', 'Taxonomy YAML did not parse to a mapping.');
+    }
+    const version = doc.version;
+    if (typeof version !== 'number') {
+        throw new TaxonomyError('taxonomy.invalid-document', 'Taxonomy is missing a numeric `version`.');
+    }
+    const errorNode = doc.error;
+    if (!errorNode || typeof errorNode !== 'object') {
+        throw new TaxonomyError('taxonomy.invalid-document', 'Taxonomy is missing the `error` group block.');
+    }
+    const errorGroups = {};
+    for (const [group, classes] of Object.entries(errorNode)) {
+        if (!Array.isArray(classes)) {
+            throw new TaxonomyError('taxonomy.invalid-document', `error group "${group}" must be an array of classes.`);
+        }
+        errorGroups[group] = classes.map(String);
+    }
+    const dimensions = {};
+    for (const [key, value] of Object.entries(doc)) {
+        if (NON_DIMENSION_KEYS.has(key))
+            continue;
+        if (!Array.isArray(value))
+            continue;
+        dimensions[key] = value.map(String);
+    }
+    const rulesNode = doc.rules;
+    const requiredDimensions = rulesNode?.required_dimensions ?? {};
+    if (Object.keys(requiredDimensions).length === 0) {
+        throw new TaxonomyError('taxonomy.invalid-document', 'Taxonomy is missing rules.required_dimensions.');
+    }
+    return { version, dimensions, errorGroups, requiredDimensions };
+}
+export function loadTaxonomy(filePath = TAXONOMY_PATH) {
+    const text = readFileSync(filePath, 'utf8');
+    return parseTaxonomy(text);
+}
+/** Validate a single tag value against one taxonomy dimension. Never silently passes. */
+export function validateTag(taxonomy, dimension, value) {
+    const allowed = taxonomy.dimensions[dimension];
+    if (!allowed) {
+        throw new TaxonomyError('taxonomy.unknown-dimension', `Unknown taxonomy dimension "${dimension}".`, { dimension });
+    }
+    if (!allowed.includes(value)) {
+        throw new TaxonomyError('taxonomy.unknown-tag', `Unknown value "${value}" for taxonomy dimension "${dimension}".`, { dimension, value, allowed });
+    }
+}
+/** Validate a grouped error class, always logged/referenced as `group.class`. */
+export function validateErrorClass(taxonomy, value) {
+    const parts = value.split('.');
+    if (parts.length !== 2 || parts[0] === '' || parts[1] === '') {
+        throw new TaxonomyError('taxonomy.invalid-error-class-format', `Error class "${value}" must be in "group.class" form.`, { value });
+    }
+    const [group, cls] = parts;
+    const classes = taxonomy.errorGroups[group];
+    if (!classes) {
+        throw new TaxonomyError('taxonomy.unknown-error-group', `Unknown error group "${group}".`, {
+            group,
+            value,
+        });
+    }
+    if (!classes.includes(cls)) {
+        throw new TaxonomyError('taxonomy.unknown-error-class', `Unknown error class "${cls}" in group "${group}".`, { group, class: cls, value, allowed: classes });
+    }
+}
+/**
+ * Enforce the required-dimensions-per-record-type rules (taxonomy.yml `rules:`
+ * block). Checks presence of every required field, then validates each
+ * field's value against its taxonomy dimension (or the group.class rule for
+ * the `error` field, or mere non-empty presence for reference-only fields).
+ */
+export function validateRequiredDimensions(taxonomy, recordType, record) {
+    const required = taxonomy.requiredDimensions[recordType];
+    if (!required) {
+        throw new TaxonomyError('taxonomy.unknown-record-type', `Unknown record type "${recordType}" — no required-dimensions rule for it.`, { recordType });
+    }
+    for (const field of required) {
+        const value = record[field];
+        const isEmpty = value === undefined ||
+            value === null ||
+            value === '' ||
+            (Array.isArray(value) && value.length === 0);
+        if (isEmpty) {
+            throw new TaxonomyError('taxonomy.missing-required-dimension', `Record type "${recordType}" is missing required field "${field}".`, { recordType, field });
+        }
+        if (PRESENCE_ONLY_FIELDS.has(field))
+            continue;
+        if (field === ERROR_CLASS_FIELD) {
+            validateErrorClass(taxonomy, String(value));
+            continue;
+        }
+        validateTag(taxonomy, field, String(value));
+    }
+}