@juzser/blacksmith 0.2.0 → 0.4.0

package/factory/orchestrator/dist/errorIssues.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { isLaterEvent } from './eventOrder.js';
 /** 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',
@@ -19,6 +20,10 @@ 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';
+/** `agents-registry.ts`'s `DISPATCH_EVENT_TYPE`, hand-restated rather than
+ * imported -- this module's only imports are `node:crypto` and two local,
+ * type-only siblings, on purpose (see the file banner). */
+const DISPATCH_DECISION_EVENT_TYPE = 'dispatch_decision';
 /**
  * Source 2: `task_status: failed` is set in exactly one place in the whole
  * projector, `db/projector.ts`'s `case 'task-added'` arm copying
@@ -28,8 +33,6 @@ const TASK_ADDED_EVENT_TYPE = 'task-added';
  * 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;
 }
@@ -37,18 +40,14 @@ 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`).
+ * The sources, keyed by the event type each one reads. A table rather than a
+ * chain of `if`s so that ISSUE_CANDIDATE_EVENT_TYPES below can be read off
+ * it: a fourth source cannot be folded without appearing here, and appearing
+ * here is what puts it in the roster.
  */
-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) {
+const CANDIDATE_READERS = Object.freeze({
+    [GATE_OUTCOME_EVENT_TYPE]: (event, { payload, project, sessionId, planVersion, ts }) => {
+        const { record } = event;
         if (payload.outcome !== 'blocked')
             return 'ignore';
         const reasonRaw = asString(payload.reason);
@@ -70,8 +69,9 @@ function toCandidate(event) {
             epicId: null,
             planVersion,
         };
-    }
-    if (record.event_type === ERROR_LOGGED_EVENT_TYPE) {
+    },
+    [ERROR_LOGGED_EVENT_TYPE]: (event, { payload, project, sessionId, planVersion, ts }) => {
+        const { record } = event;
         const errorClass = asString(payload.error);
         const severity = asString(payload.severity);
         const taskRef = asString(record.task_id) ?? asString(payload.task_ref);
@@ -89,8 +89,9 @@ function toCandidate(event) {
             epicId: null,
             planVersion,
         };
-    }
-    if (record.event_type === TASK_ADDED_EVENT_TYPE) {
+    },
+    [TASK_ADDED_EVENT_TYPE]: (event, { payload, project, sessionId, planVersion, ts }) => {
+        const { record } = event;
         if (payload.task_status !== 'failed')
             return 'ignore';
         const taskRef = asString(record.task_id);
@@ -109,9 +110,168 @@ function toCandidate(event) {
             epicId,
             planVersion,
         };
+    },
+});
+/**
+ * The event types this fold reads candidates from — read off the table above
+ * rather than hand-copied a second time, the way GATE_BLOCKED_REASONS is.
+ * cli.ts scopes `--epic`/`--since` with it and passes everything else
+ * through as history; typed there instead, a source added here and not there
+ * would be reported outside the window the operator asked about.
+ */
+export const ISSUE_CANDIDATE_EVENT_TYPES = new Set(Object.keys(CANDIDATE_READERS));
+/** The row's task ref, off the envelope first and the payload second -- the same two places every `CandidateReader` above already looks. */
+function candidateTaskRef(record) {
+    const payload = (record.payload ?? {});
+    return asString(record.task_id) ?? asString(payload.task_ref);
+}
+/**
+ * Event types allowed to stamp a session's project for
+ * `sessionProjectStamps` below: the issue candidates themselves, plus
+ * `task-added` and `dispatch_decision` rows recording where a task was
+ * planned or dispatched. Deliberately excludes `issue-reported` and every
+ * other reporter-authored row -- those carry this module's own *guess* at a
+ * row's project (see `appendIssueReported` in `issueReporter.ts`), not an
+ * independent origin stamp, so folding them back in here would let one run's
+ * guess leak into the next run's resolution of an unrelated, unstamped row
+ * in the same session.
+ */
+const ORIGIN_STAMP_EVENT_TYPES = new Set([
+    ...ISSUE_CANDIDATE_EVENT_TYPES,
+    DISPATCH_DECISION_EVENT_TYPE,
+]);
+/**
+ * The session's project, from its origin-stamped rows only -- and only when
+ * every one of them agrees. Real sessions mix dozens of stamped rows with
+ * unstamped ones (evidence: a foreign project's session stamps some events
+ * and not others); a unanimous stamped sibling in the same session is strong
+ * evidence for an unstamped one. A session whose origin stamps disagree
+ * tells us nothing safe to guess, so it answers unresolved rather than
+ * picking whichever stamp happened to come first.
+ */
+function sessionProjectStamps(events) {
+    const bySession = new Map();
+    for (const { record } of events) {
+        if (!ORIGIN_STAMP_EVENT_TYPES.has(record.event_type))
+            continue;
+        const project = asString(record.project);
+        if (project === undefined)
+            continue;
+        const seen = bySession.get(record.session_id);
+        if (seen)
+            seen.add(project);
+        else
+            bySession.set(record.session_id, new Set([project]));
     }
-    return 'ignore';
+    const stamps = new Map();
+    for (const [sessionId, projects] of bySession) {
+        if (projects.size !== 1)
+            continue;
+        const [project] = projects;
+        if (project !== undefined)
+            stamps.set(sessionId, project);
+    }
+    return stamps;
 }
+function taskAddedKey(sessionId, taskId) {
+    return `${sessionId}\u0000${taskId}`;
+}
+/** `task-added`'s own `payload.epic_id`, keyed by session and task id, so a bare ref (no epic segment) can still be widened to `<epic>/<ref>` before asking the resolver. */
+function taskAddedEpicIds(events) {
+    const out = new Map();
+    for (const { record } of events) {
+        if (record.event_type !== TASK_ADDED_EVENT_TYPE)
+            continue;
+        const taskId = asString(record.task_id);
+        const epicId = asString(record.payload?.epic_id);
+        if (taskId !== undefined && epicId !== undefined) {
+            out.set(taskAddedKey(record.session_id, taskId), epicId);
+        }
+    }
+    return out;
+}
+/**
+ * Widens a per-epic `ResolveProjectForTaskRef` into a `RowProjectResolver`
+ * with three session-scoped fallbacks a single task ref cannot answer alone,
+ * tried strictly in this order (S2-c):
+ *
+ * 1. `resolveProject`, the strict/direct resolver -- a bare ref (no epic
+ *    segment) tried again as `<epic>/<ref>` using the same session's own
+ *    `task-added` row when the bare ref alone cannot answer.
+ * 2. The session stamp: the ONE project every origin-stamped row in the same
+ *    session agrees on (`sessionProjectStamps`), when unanimous.
+ * 3. `selfFallback`, tried last and only when neither of the above could
+ *    answer -- same widening as step 1.
+ *
+ * Self-fallback sits last on purpose: it is "no plan says otherwise, and a
+ * plan exists locally for this epic, so guess this factory's own name" --
+ * the weakest of the three signals. A session's OWN unanimous stamp naming a
+ * DIFFERENT project is stronger evidence than that guess, and must not be
+ * overridden by it just because the same session also has an unrelated,
+ * unstamped row whose epic happens to have a local, unlabeled plan. Before
+ * this order existed, the self-fallback was folded into `resolveProject`
+ * itself (step 1) and so always outran the session stamp.
+ *
+ * Exported so `issueReporter.ts`'s `priorOpenReports` can apply the identical
+ * fallback to the same event snapshot.
+ */
+export function withSessionFallback(events, resolveProject, selfFallback = () => null) {
+    const stamps = sessionProjectStamps(events);
+    const epicIds = taskAddedEpicIds(events);
+    const tryResolve = (resolve, taskRef, sessionId) => {
+        if (taskRef === undefined)
+            return null;
+        const direct = resolve(taskRef);
+        if (direct !== null)
+            return direct;
+        if (sessionId === undefined)
+            return null;
+        const epicId = epicIds.get(taskAddedKey(sessionId, taskRef));
+        if (epicId === undefined)
+            return null;
+        return resolve(`${epicId}/${taskRef}`);
+    };
+    return (taskRef, sessionId) => {
+        const direct = tryResolve(resolveProject, taskRef, sessionId);
+        if (direct !== null)
+            return direct;
+        if (sessionId !== undefined) {
+            const stamp = stamps.get(sessionId);
+            if (stamp !== undefined)
+                return stamp;
+        }
+        return tryResolve(selfFallback, taskRef, sessionId);
+    };
+}
+/** One event to a `Candidate`, or `'ignore'` when no source claims its event type at all. */
+function toCandidate(event, resolveRow) {
+    const { record } = event;
+    const read = CANDIDATE_READERS[record.event_type];
+    if (!read)
+        return 'ignore';
+    const stamped = asString(record.project);
+    const taskRef = candidateTaskRef(record);
+    const sessionId = asString(record.session_id);
+    const project = stamped ?? resolveRow(taskRef, sessionId);
+    return read(event, {
+        payload: record.payload ?? {},
+        project,
+        sessionId,
+        planVersion: asNumber(record.plan_version) ?? null,
+        ts: asString(record.ts),
+    });
+}
+/**
+ * A row whose project cannot be resolved at all still needs a stable
+ * fingerprint-grouping key -- otherwise two unrelated foreign projects'
+ * rows sharing `(source, error_class, task_ref)` would incorrectly group
+ * together and leak one row's session/epic/severity metadata onto the
+ * other's report, inside this factory's own private log (both rows are
+ * always skipped before anything is filed publicly, but the log itself
+ * should stay correct). `task_ref` alone already disambiguates in practice
+ * (refs are namespaced by epic id), so a single fixed sentinel is enough.
+ */
+const UNRESOLVED_PROJECT_FINGERPRINT_KEY = '\u0000unresolved-project\u0000';
 /**
  * The first 16 hex characters of a SHA-256 over the NUL-joined tuple
  * `project`, `source`, `error_class`, `task_ref`. Deliberately excludes
@@ -120,27 +280,52 @@ function toCandidate(event) {
  * 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');
+    const material = [
+        project ?? UNRESOLVED_PROJECT_FINGERPRINT_KEY,
+        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.
+ *
+ * `resolveProject` and `selfFallback` both default to "no answer" so the
+ * ~50 existing call sites across this module's own tests and
+ * `issueReporter.ts`'s need no change. An unstamped row still unresolved
+ * after `withSessionFallback`'s three fallbacks reports `project: null`
+ * rather than this factory's own name -- `isProjectEnabled` is never asked
+ * about a row it cannot identify, and the decision to skip filing it
+ * belongs to `issueReporter.ts`, the one caller that goes on to call `gh`.
+ *
+ * `scopeEvents` defaults to `events` itself -- the session-stamp/`task-added`
+ * maps `withSessionFallback` builds read the same rows this fold iterates,
+ * same as before this parameter existed. A caller that narrows `events` to a
+ * candidate WINDOW (`cli.ts`'s `--epic`/`--since`) passes the full, unscoped
+ * lineage here instead (S3), so a session-mate's stamp sitting outside that
+ * window still counts as evidence for a row inside it -- scoping which rows
+ * get REPORTED must not also scope which rows get CONSULTED, or the same
+ * unstamped row resolves to a different project (and hashes a different
+ * fingerprint, S1-b) depending on whether the caller happened to pass
+ * `--epic`.
  */
-export function foldErrorEvents(events, now, isProjectEnabled) {
+export function foldErrorEvents(events, now, isProjectEnabled, resolveProject = () => null, selfFallback = () => null, scopeEvents = events) {
     void now;
+    const resolveRow = withSessionFallback(scopeEvents, resolveProject, selfFallback);
     const candidates = [];
     let skipped = 0;
     for (const event of events) {
-        const outcome = toCandidate(event);
+        const outcome = toCandidate(event, resolveRow);
         if (outcome === 'ignore')
             continue;
         if (outcome === null) {
             skipped += 1;
             continue;
         }
-        if (!isProjectEnabled(outcome.project))
+        if (outcome.project !== null && !isProjectEnabled(outcome.project))
             continue;
         candidates.push(outcome);
     }
@@ -155,7 +340,7 @@ export function foldErrorEvents(events, now, isProjectEnabled) {
     }
     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);
+        const latest = group.reduce((a, b) => (isLaterEvent(b, a) ? b : a));
         for (const candidate of group) {
             reports.push({
                 fingerprint,
@@ -225,7 +410,7 @@ export function renderBody(fields) {
         `Session: ${fields.session_id}`,
         `Epic: ${fields.epic_id ?? '(none)'}`,
         `Plan version: ${fields.plan_version ?? '(unknown)'}`,
-        `Project: ${fields.project}`,
+        `Project: ${fields.project ?? '(unknown)'}`,
         `Source: ${fields.source}`,
         fingerprintLine(fields.fingerprint),
         '',

package/factory/orchestrator/dist/eventOrder.js

@@ -0,0 +1,102 @@
+// The log-order vocabulary, split out of events.ts (the log's I/O hub) so a
+// pure reader can order events without pulling in filesystem access.
+// errorIssues.ts is that reader: task-2's purity clauses keep it free of any
+// runtime import from `./events.js`, so this module has NO import statement
+// at all — not even `./errors.js` — and its transitive import graph is
+// empty.
+/**
+ * Split an event id into the session that owns it and its line index.
+ *
+ * Event ids have always been `<session-id>#<index>` — that shape is what makes
+ * a cross-session reference resolvable at all (P9-7): given only the id, a
+ * reader knows which log file to open. Splitting on the LAST `#` keeps a
+ * session id that happens to contain one from silently resolving to the wrong
+ * session.
+ *
+ * This is the ONE parser of that shape. Unlike `parseEventId` in
+ * `events.ts` (the throwing wrapper callers reach for at the log's edges),
+ * this never throws — it returns `null` for anything malformed, including a
+ * non-string reached through a cast, so a pure comparator can stay total.
+ */
+export function tryParseEventId(eventId) {
+    if (typeof eventId !== 'string')
+        return null;
+    const cut = eventId.lastIndexOf('#');
+    const sessionId = cut === -1 ? '' : eventId.slice(0, cut);
+    const rawIndex = eventId.slice(cut + 1);
+    // Number.parseInt would accept "3abc"; an event id is exact or it is a typo.
+    const index = /^\d+$/.test(rawIndex) ? Number(rawIndex) : Number.NaN;
+    if (cut === -1 || sessionId.length === 0 || Number.isNaN(index))
+        return null;
+    return { sessionId, index };
+}
+/**
+ * Where an event sits in the order the log actually wrote it.
+ *
+ * An event id is `<session-id>#<index>` and the index is the event's line in
+ * its session's log, so within a session this *is* the order rather than a
+ * proxy for it. Across sessions the logs are separate files that nothing
+ * interleaves, so the session id is here to make the answer the same on every
+ * call, not because one session precedes another.
+ *
+ * Total where tryParseEventId returns null, and the fallback is unreachable
+ * by construction — every id this sees came out of readEvents() or a
+ * projection of it, and readEvents builds each one as `<session>#<index>`. It
+ * is here because the readers on top of this are a dashboard `/api/pulse`
+ * polls every 5s and two audits the operator runs on a whole log, and an id
+ * that somehow would not parse should sort somewhere rather than take the
+ * caller down with it. Where it lands is deliberately modest: an event whose
+ * place in the log is unreadable does not get to win a tie on it.
+ */
+function logOrderOf(eventId) {
+    return tryParseEventId(eventId) ?? { sessionId: eventId, index: -1 };
+}
+/**
+ * The order the log wrote two events in: negative when `a` came first,
+ * positive when `b` did, zero only for the same event.
+ *
+ * `ts` is stamped at millisecond resolution (`appendEvent` in `events.ts`
+ * stamps it), so a burst of appends routinely shares one: the test fixture's
+ * own last two events tie in roughly one build in three, and a gate outcome
+ * and the retry dispatched in answer to it are written back to back. Nothing
+ * else in the record carries the sequence — `events_raw` has no such column
+ * and the JSONL line has no such field — so on a tie `ts` has nothing left to
+ * say, and nothing downstream of it does either. A `>` between two tied rows
+ * is not a decision, it is whichever the scan reached first; `ORDER BY ts` is
+ * the same non-answer spelled in SQL, since SQLite promises nothing about
+ * tied rows and hands them back in physical order, which changes the moment a
+ * row is rewritten; and a JS `.sort()` whose comparator returns 0 throughout
+ * is stable, so it keeps that same scan order and passes it off as
+ * chronology.
+ *
+ * The log index behind the event id is what actually decides, and it has to
+ * be read as a number: ordered as text — which is what `ORDER BY ts,
+ * event_id` does — `#9` sorts after `#10`, so the tiebreaker inverts as soon
+ * as a session's log passes ten events.
+ *
+ * It lives here, below `events.ts`, rather than in any one reader because
+ * more than one of them asks this question: the dashboard queries fold and
+ * sort rows, escalation.ts walks a task's rounds looking for the dispatch on
+ * either side of one, and errorIssues.ts's pure fold needs the same answer
+ * without importing the fs hub that owns the log's I/O. Every ordering a
+ * reader would call chronological routes through here, so that no two of them
+ * can answer the same question about the same two events differently — which
+ * is exactly what happened when the callers spelled the comparison
+ * themselves, with opposite operators.
+ */
+export function compareLogOrder(a, b) {
+    if (a.ts !== b.ts)
+        return a.ts < b.ts ? -1 : 1;
+    const left = logOrderOf(a.eventId);
+    const right = logOrderOf(b.eventId);
+    if (left.sessionId !== right.sessionId)
+        return left.sessionId < right.sessionId ? -1 : 1;
+    return left.index - right.index;
+}
+/**
+ * Whether `a` is the later of two events — the one a reader means by "what
+ * just happened".
+ */
+export function isLaterEvent(a, b) {
+    return compareLogOrder(a, b) > 0;
+}

package/factory/orchestrator/dist/events.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync } from 'node:fs';
 import { appendFile, mkdir, open, readFile, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { SmithError } from './errors.js';
+import { tryParseEventId } from './eventOrder.js';
 import { STATE_EVENTS_DIR } from './paths.js';
 import { compileSchemas, validateRecord } from './schemas.js';
 import { taskIdsMatch } from './taskId.js';
@@ -17,6 +18,11 @@ export class EventError extends SmithError {
  * the literal is a second thing to keep in step.
  */
 export const ROOT_EVENT_TYPE = 'session-start';
+// `compareLogOrder`, `isLaterEvent` and `ParsedEventId` now live in
+// `eventOrder.ts`, a leaf with no import statement, so a pure reader (the
+// error fold in errorIssues.ts) can order events without importing this
+// fs hub.
+export { compareLogOrder, isLaterEvent } from './eventOrder.js';
 /**
  * Split an event id into the session that owns it and its line index.
  *
@@ -25,6 +31,10 @@ export const ROOT_EVENT_TYPE = 'session-start';
  * reader knows which log file to open. Splitting on the LAST `#` keeps a
  * session id that happens to contain one from silently resolving to the wrong
  * session.
+ *
+ * The parse itself lives in `eventOrder.ts` (`tryParseEventId`, which never
+ * throws); this wrapper is the one place that turns a malformed id into the
+ * `events.malformed-event-id` error every caller of `parseEventId` expects.
  */
 export function parseEventId(eventId) {
     // Typed as a string and reached with whatever the writer sent. `smith event
@@ -37,87 +47,11 @@ export function parseEventId(eventId) {
     if (typeof eventId !== 'string') {
         throw new EventError('events.malformed-event-id', `${JSON.stringify(eventId) ?? String(eventId)} (${typeof eventId}) is not an event id. The form is <session-id>#<index>, e.g. dogfood-envkit-1#42.`, { event_id: eventId });
     }
-    const cut = eventId.lastIndexOf('#');
-    const sessionId = cut === -1 ? '' : eventId.slice(0, cut);
-    const rawIndex = eventId.slice(cut + 1);
-    // Number.parseInt would accept "3abc"; an event id is exact or it is a typo.
-    const index = /^\d+$/.test(rawIndex) ? Number(rawIndex) : Number.NaN;
-    if (cut === -1 || sessionId.length === 0 || Number.isNaN(index)) {
+    const parsed = tryParseEventId(eventId);
+    if (parsed === null) {
         throw new EventError('events.malformed-event-id', `"${eventId}" is not an event id. The form is <session-id>#<index>, e.g. dogfood-envkit-1#42.`, { event_id: eventId });
     }
-    return { sessionId, index };
-}
-/**
- * Where an event sits in the order the log actually wrote it.
- *
- * An event id is `<session-id>#<index>` and the index is the event's line in
- * its session's log, so within a session this *is* the order rather than a
- * proxy for it. Across sessions the logs are separate files that nothing
- * interleaves, so the session id is here to make the answer the same on every
- * call, not because one session precedes another.
- *
- * Total where parseEventId throws, and the fallback is unreachable by
- * construction — every id this sees came out of readEvents() or a projection
- * of it, and readEvents builds each one as `<session>#<index>`. It is here
- * because the readers on top of this are a dashboard `/api/pulse` polls every
- * 5s and two audits the operator runs on a whole log, and an id that somehow
- * would not parse should sort somewhere rather than take the caller down with
- * it. Where it lands is deliberately modest: an event whose place in the log
- * is unreadable does not get to win a tie on it.
- */
-function logOrderOf(eventId) {
-    try {
-        return parseEventId(eventId);
-    }
-    catch {
-        return { sessionId: eventId, index: -1 };
-    }
-}
-/**
- * The order the log wrote two events in: negative when `a` came first,
- * positive when `b` did, zero only for the same event.
- *
- * `ts` is stamped at millisecond resolution (appendEvent, just below), so a
- * burst of appends routinely shares one: the test fixture's own last two
- * events tie in roughly one build in three, and a gate outcome and the retry
- * dispatched in answer to it are written back to back. Nothing else in the
- * record carries the sequence — `events_raw` has no such column and the JSONL
- * line has no such field — so on a tie `ts` has nothing left to say, and
- * nothing downstream of it does either. A `>` between two tied rows is not a
- * decision, it is whichever the scan reached first; `ORDER BY ts` is the same
- * non-answer spelled in SQL, since SQLite promises nothing about tied rows and
- * hands them back in physical order, which changes the moment a row is
- * rewritten; and a JS `.sort()` whose comparator returns 0 throughout is
- * stable, so it keeps that same scan order and passes it off as chronology.
- *
- * The log index behind the event id is what actually decides, and it has to be
- * read as a number: ordered as text — which is what `ORDER BY ts, event_id`
- * does — `#9` sorts after `#10`, so the tiebreaker inverts as soon as a
- * session's log passes ten events.
- *
- * It lives beside parseEventId rather than in any one reader because more than
- * one of them asks this question: the dashboard queries fold and sort rows,
- * escalation.ts walks a task's rounds looking for the dispatch on either side
- * of one. Every ordering a reader would call chronological routes through
- * here, so that no two of them can answer the same question about the same two
- * events differently — which is exactly what happened when the callers spelled
- * the comparison themselves, with opposite operators.
- */
-export function compareLogOrder(a, b) {
-    if (a.ts !== b.ts)
-        return a.ts < b.ts ? -1 : 1;
-    const left = logOrderOf(a.eventId);
-    const right = logOrderOf(b.eventId);
-    if (left.sessionId !== right.sessionId)
-        return left.sessionId < right.sessionId ? -1 : 1;
-    return left.index - right.index;
-}
-/**
- * Whether `a` is the later of two events — the one a reader means by "what
- * just happened".
- */
-export function isLaterEvent(a, b) {
-    return compareLogOrder(a, b) > 0;
+    return parsed;
 }
 /**
  * The task an event names, read from both places one can be written.
@@ -517,7 +451,7 @@ const TYPED_PAYLOAD_SCHEMAS = {
 /**
  * The one field of a `task-result-recorded` payload a reader iterates. The
  * projector writes `artifacts[]` into rows inside the session's transaction,
- * so an object here (csb-audit-1#100 carried `{ claude_half, external_half,
+ * so an object here (a dogfood run's event #100 carried `{ claude_half, external_half,
  * repair_brief }`) rolled back the whole session and the dashboard drew
  * nothing for it. Pinning only this field is deliberate: the full result
  * schema is not enforced on the event, because real logs carry many
@@ -537,8 +471,28 @@ function validateResultArtifactsShape(record) {
         errors: [{ path: '/artifacts', message: `must be an array, got ${typeof artifacts}` }],
     });
 }
+/**
+ * `error-logged`'s task_id (D-245: envelope or payload, envelope wins) names
+ * exactly one task, the same rule taxonomy.ts enforces for `task_ref` — but
+ * `task_id` is schema-typed as a plain string, so no taxonomy rule ever sees
+ * it, and a comma-joined "epic-1/task-1,epic-1/task-2" passed straight
+ * through. db/projector.ts's fold read that string as a single task id and
+ * minted a phantom row for it that stayed `todo` forever. Checked here,
+ * beside validateResultArtifactsShape, for the same reason: the shape a
+ * later reader assumes is not one the event schema or taxonomy already rule
+ * out.
+ */
+function validateErrorLoggedTaskIdShape(record) {
+    if (record.event_type !== 'error-logged')
+        return;
+    const taskId = eventTaskId(record);
+    if (taskId === null || !taskId.includes(','))
+        return;
+    throw new EventError('events.multi-value-task-id', `Event "error-logged" names more than one task in its task_id ("${taskId}"). Log one error-logged event per task instead.`, { event_type: record.event_type, task_id: taskId });
+}
 function validateTypedPayload(schemas, taxonomy, record) {
     validateResultArtifactsShape(record);
+    validateErrorLoggedTaskIdShape(record);
     const schemaName = TYPED_PAYLOAD_SCHEMAS[record.event_type];
     if (schemaName === undefined)
         return;
@@ -590,19 +544,47 @@ async function validateCausalParent(input, opts, existing) {
         throw new EventError('events.unknown-causal-parent', `causal_parent "${input.causal_parent}" does not reference an existing event in session "${parent.sessionId}" (it holds ${parentEvents.length}).`, { causal_parent: input.causal_parent, session_id: parent.sessionId });
     }
 }
+// EventInput requires causal_parent, so inside the orchestrator undefined is
+// unreachable. It is reachable from outside: every event appended through the
+// CLI crosses a JSON boundary where the type guarantees nothing, and omitting
+// a field is the likeliest way a hand-written event is malformed. This used
+// to compare against `null` alone, so an omitted parent fell through into
+// parseEventId(undefined) and reached the caller as a raw TypeError with no
+// `code` — the one shape produced by accident was the one shape with nothing
+// to branch on. Normalise once so every caller reads the same guard.
+function requireCausalParentPresence(eventType, causalParent) {
+    if (causalParent === null && eventType !== ROOT_EVENT_TYPE) {
+        throw new EventError('events.missing-causal-parent', `causal_parent may only be null for "${ROOT_EVENT_TYPE}" events (got event_type "${eventType}").`, { event_type: eventType });
+    }
+}
+/**
+ * Validate an event's envelope — the same causal_parent checks `appendEvent`
+ * runs immediately before it writes — without appending anything.
+ *
+ * `queue.ts`'s `step`/`batchStep` and `integration.ts`'s check suite each do
+ * real work of their own (a rebase and a no-ff merge; a full check run) ahead
+ * of their own first append, so a bad `--causal-parent` used to surface only
+ * there — after the git work had already landed for real, with no event to
+ * show for it. A retry then found the branch already advanced and reported it
+ * as stuck. Calling this first, before any of that work starts, means a bad
+ * envelope is refused with nothing done yet to undo.
+ *
+ * Only the causal_parent rules and the session-id shape are checked here. The
+ * event schema, the taxonomy and typed payloads are not: a caller whose payload
+ * could fail those must not treat a pass as "the append will succeed".
+ */
+export async function validateEventEnvelope(input, opts = {}) {
+    const causalParent = input.causal_parent ?? null;
+    requireCausalParentPresence(input.event_type, causalParent);
+    if (causalParent === null)
+        return;
+    const filePath = logPath(input.session_id, opts);
+    const existing = await readEventsAtPath(filePath, input.session_id);
+    await validateCausalParent(input, opts, existing);
+}
 async function appendEventLocked(input, opts, filePath) {
-    // EventInput requires causal_parent, so inside the orchestrator undefined is
-    // unreachable. It is reachable from outside: every event appended through the
-    // CLI crosses a JSON boundary where the type guarantees nothing, and omitting
-    // a field is the likeliest way a hand-written event is malformed. Both guards
-    // below used to compare against `null` alone, so an omitted parent fell
-    // through them into parseEventId(undefined) and reached the caller as a raw
-    // TypeError with no `code` — the one shape produced by accident was the one
-    // shape with nothing to branch on. Normalise once so both guards read it.
     const causalParent = input.causal_parent ?? null;
-    if (causalParent === null && input.event_type !== ROOT_EVENT_TYPE) {
-        throw new EventError('events.missing-causal-parent', `causal_parent may only be null for "${ROOT_EVENT_TYPE}" events (got event_type "${input.event_type}").`, { event_type: input.event_type });
-    }
+    requireCausalParentPresence(input.event_type, causalParent);
     await mkdir(path.dirname(filePath), { recursive: true });
     const existing = await readEventsAtPath(filePath, input.session_id);
     if (causalParent !== null) {

package/factory/orchestrator/dist/findingContext.js

@@ -1,5 +1,5 @@
 import { claimCoversPath } from './claims.js';
-import { listFindings } from './findings.js';
+import { listFindings, OPEN_FOR_DISPATCH } from './findings.js';
 /**
  * The spliced block's delimiters, exported for the same two reasons
  * lessons.ts exports its own: a caller composing a dispatch prompt needs to
@@ -8,18 +8,6 @@ import { listFindings } from './findings.js';
  */
 export const FINDING_BLOCK_BEGIN = '<!-- BEGIN OPEN FINDINGS -->';
 export const FINDING_BLOCK_END = '<!-- END OPEN FINDINGS -->';
-/**
- * Which statuses are "open" for the purpose of dispatch context.
- *
- * `raised` and `confirmed` only. `refuted`, `waived`, `fix-verified`,
- * `amended` and `expired` are closed. `fix-pending`/`fix-landed` are *already
- * someone's assignment* — surfacing one to a second coder is how two diffs end
- * up fixing one finding, and the second one lands as an unrequested change.
- * `amend-pending` (D-127) is open elsewhere but not here for that same reason:
- * it already names the tasks that discharge it, and the fix belongs in those
- * tasks' diffs, not in whatever task is being dispatched now.
- */
-export const OPEN_FOR_DISPATCH = ['raised', 'confirmed'];
 /**
  * Prompt-facing text for one field. Same two guarantees as lessons.ts's
  * `flatten`, and for the same reason — this text is going INTO a prompt: