@kontourai/flow-agents 3.12.0 → 4.0.0

package/src/narrative/statements.ts

@@ -0,0 +1,423 @@
+import { createHash } from "node:crypto";
+import type { UnavailableReason } from "./integrity.js";
+import { parseSourceId } from "./source-ids.js";
+
+export type StatementClass = "observed" | "deterministic_derived" | "summarizer_inferred" | "agent_stated";
+export type ObservedResult = "pass" | "fail" | "ambiguous";
+
+// #622: hard length cap on a stated-intent purpose. A bounded single-clause
+// purpose (enforced by the strict text()+atomic() guards below) may never grow
+// into a free-form reasoning dump, so the cap is deliberately small.
+export const AGENT_STATED_PURPOSE_MAX_LENGTH = 200;
+
+// #622 (review HIGH R2): a hard length cap on a stated-intent actor. An actor is
+// an identifier-shaped attribution key (see identifier() below), never a place to
+// smuggle prose or prohibited-assertion keywords past the proposition scan.
+export const AGENT_STATED_ACTOR_MAX_LENGTH = 120;
+
+// #622 (review HIGH R2): the FULL Unicode line/paragraph separator class. `\r`/`\n`
+// alone let a caller chain clauses with U+2028 (LINE SEPARATOR) / U+2029 (PARAGRAPH
+// SEPARATOR) or any other `\p{Zl}`/`\p{Zp}` code point. Every clause-separator guard
+// below rejects this whole class, not just the ASCII line breaks.
+const UNICODE_LINE_SEPARATORS = /[\r\n\u2028\u2029\p{Zl}\p{Zp}]/u;
+
+// #622 (review HIGH R2, second pass): the single-clause guard below must reject clause
+// separators STRUCTURALLY, not via a blocklist of the few code points named in the first
+// finding. A single clause may only contain letters/digits/ordinary punctuation joined by a
+// single ASCII space; every other whitespace, zero-width/format control, and clause-joining
+// punctuation or terminator is a separator.
+//   - NON_SPACE_WHITESPACE: any whitespace that is NOT a plain U+0020 space (tab, VT U+000B,
+//     FF U+000C, CR, LF, NBSP U+00A0, U+2028/9, every other \p{Zs}/\p{Zl}/\p{Zp}).
+//   - HIDDEN_FORMAT_CHARS: any invisible / non-rendering code point that could hide a clause
+//     break without tripping the whitespace rule. Rejects the WHOLE Unicode "Other" category
+//     \p{C} (Cc control incl. NEL U+0085, Cf format incl. soft-hyphen U+00AD, ALM U+061C, the
+//     zero-width block, bidi embeds/overrides U+202A\u2013202E AND isolates U+2066\u20132069, the
+//     deprecated-format block U+206A\u2013206F, BOM U+FEFF, Mongolian U+180E; plus Cs/Co/Cn), and
+//     the invisible marks/fillers that are NOT \p{C}: the whole \p{Variation_Selector} property
+//     (U+FE00\u2013FE0F, U+180B\u2013180D, U+E0100\u2013E01EF \u2014 invisible, \p{C}=false), combining grapheme
+//     joiner U+034F, Hangul fillers U+115F/U+1160/U+3164/U+FFA0, and Khmer invisible vowels
+//     U+17B4/U+17B5. (Second pass: explicit-range blocklist missed isolates/ALM/NEL/SHY/CGJ \u2014
+//     switched to categorical \p{C}. Third pass: \p{C} still missed the Variation_Selector
+//     class \u2014 added the property. Ordinary combining accents (\p{Mn} on caf\u00e9/na\u00efve) render on
+//     their base and are deliberately NOT rejected.)
+//   - CLAUSE_PUNCTUATION: colon, semicolon, ellipsis (U+2026/U+22EF), any Unicode dash
+//     (U+2012\u20132015), and a spaced ASCII hyphen " - " used as a clause dash (intra-word
+//     hyphens like `test-suite` have no surrounding spaces and are allowed).
+//   - NON_ASCII_TERMINATOR: any non-ASCII Sentence_Terminal (ideographic U+3002, fullwidth
+//     U+FF01/FF1F, Arabic U+061F/06D4, Devanagari danda, \u2026) \u2014 these never appear intra-word in
+//     a short English purpose, so they are rejected anywhere. ASCII . ! ? are handled by the
+//     "terminator + whitespace + more text" rule so a trailing period / `v1.2` still pass.
+//   - CLAUSE_COORDINATORS: clause-joining adverbs NOT already caught by atomic()'s
+//     and|but|then|while|or|so list (also/however/additionally/furthermore/afterward(s)/
+//     meanwhile/thereafter). "next"/"plus"/"finally" are deliberately EXCLUDED \u2014 they are
+//     plausible intra-clause object words and would over-reject legitimate purposes.
+const NON_SPACE_WHITESPACE = /[^\S ]/u;
+const HIDDEN_FORMAT_CHARS = /[\p{C}\p{Variation_Selector}\u034f\u115f\u1160\u17b4\u17b5\u3164\uffa0]/u;
+const CLAUSE_PUNCTUATION = /[;:\u2026\u22ef\u2012-\u2015]| - /u;
+const NON_ASCII_TERMINATOR = /(?=\P{ASCII})\p{Sentence_Terminal}/u;
+const CLAUSE_COORDINATORS = /\s(also|however|additionally|furthermore|afterwards?|meanwhile|thereafter)\s/i;
+
+export interface StatementRule {
+  id: string;
+  version: string;
+  inputs: string[];
+}
+
+export interface Statement {
+  id: string;
+  class: StatementClass;
+  proposition: string;
+  source_refs: string[];
+  turn_ref?: number;
+  actor?: string;
+  rule?: StatementRule;
+  // #622: only ever the literal `true`, and only on an `agent_stated` statement.
+  // A typed self-report flag — NOT prose — that marks the proposition as the
+  // agent's own stated purpose (self-report, never proof).
+  self_report?: true;
+}
+
+export type NarrativeStatementErrorCode =
+  | "invalid_input"
+  | "invalid_source_ref"
+  | "invalid_rule"
+  | "non_atomic_proposition";
+
+export class NarrativeStatementError extends Error {
+  readonly name = "NarrativeStatementError";
+
+  constructor(
+    readonly code: NarrativeStatementErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function fail(code: NarrativeStatementErrorCode, message: string): never {
+  throw new NarrativeStatementError(code, message);
+}
+
+function text(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.length === 0) return fail("invalid_input", `${label} must be a non-empty string`);
+  if (/`/.test(value) || UNICODE_LINE_SEPARATORS.test(value) || value.includes("; ")) return fail("non_atomic_proposition", `${label} must not contain clause separators or backticks`);
+  return value;
+}
+
+// The summarizer connective's proposition is a fully-formed sentence supplied by the
+// caller (the orchestrator, from generated prose) that MAY legitimately contain
+// backtick-quoted spans (quoting an underlying atomic proposition verbatim, per R2's
+// inherited-never-upgraded discipline). It is therefore only non-empty-checked here;
+// the shared `atomic()` scan (below, backtick-stripped skeleton) still enforces the
+// single-clause/no-clause-separator discipline exactly like every other constructor.
+function nonEmptyText(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.length === 0) return fail("invalid_input", `${label} must be a non-empty string`);
+  if (UNICODE_LINE_SEPARATORS.test(value)) return fail("non_atomic_proposition", `${label} must not contain line breaks`);
+  return value;
+}
+
+// #622 (review HIGH R2): the strict single-clause bound for a stated purpose.
+// text()/atomic() reject the conjunction / "; " / backtick / line-break classes,
+// but a purpose could still chain clauses with SENTENCE TERMINATORS ("delete the
+// audit trail. cover tracks"), COMMA LISTS ("cover tracks, avoid detection, ..."),
+// or Unicode line/paragraph separators. This guard closes that class at construct.
+// Rule (documented, defensible): a sentence terminator (. ! ?) that is FOLLOWED by
+// more text starts a second clause and is rejected; a single trailing terminator on
+// one short clause (e.g. "ship the fix.") is allowed. At most one comma is tolerated
+// (a single subordinate aside) — two or more comma-separated segments is a list /
+// clause chain and is rejected. The full Unicode separator class is rejected too.
+function singleClause(value: string, label: string): void {
+  if (NON_SPACE_WHITESPACE.test(value)) return fail("non_atomic_proposition", `${label} must be a single clause (no whitespace other than single spaces)`);
+  if (HIDDEN_FORMAT_CHARS.test(value)) return fail("non_atomic_proposition", `${label} must be a single clause (no zero-width or format-control characters)`);
+  if (CLAUSE_PUNCTUATION.test(value)) return fail("non_atomic_proposition", `${label} must be a single clause (no colon/semicolon/dash/ellipsis clause separators)`);
+  if (NON_ASCII_TERMINATOR.test(value)) return fail("non_atomic_proposition", `${label} must be a single clause (no non-ASCII sentence terminators)`);
+  if (/[.!?]\s+\S/u.test(value)) return fail("non_atomic_proposition", `${label} must be a single clause (no sentence-terminated sub-clauses)`);
+  if ((value.match(/,/gu)?.length ?? 0) >= 2) return fail("non_atomic_proposition", `${label} must be a single clause (no comma-chained sub-clauses)`);
+  if (CLAUSE_COORDINATORS.test(value)) return fail("non_atomic_proposition", `${label} must be a single clause (no clause-joining coordinators)`);
+}
+
+// Review H3: identifier-shaped inputs (tool names, event types, agent ids,
+// paths) must not be able to smuggle prose into a proposition — a charset
+// constraint kills the injection class wholesale instead of chasing
+// conjunction blacklists. Free text (commands) is backtick-quoted by the
+// templates and excluded from the atomicity scan instead.
+const IDENTIFIER = /^[A-Za-z0-9._:@#/\\-]+$/;
+function identifier(value: unknown, label: string): string {
+  const checked = text(value, label);
+  if (!IDENTIFIER.test(checked)) return fail("invalid_input", `${label} must be identifier-shaped (no spaces or prose): ${checked}`);
+  return checked;
+}
+
+function sourceRefs(values: readonly string[]): string[] {
+  if (!Array.isArray(values) || values.length === 0) return fail("invalid_source_ref", "source_refs must contain at least one fa1 source ID");
+  return values.map((value) => {
+    try {
+      parseSourceId(value);
+      return value;
+    } catch {
+      return fail("invalid_source_ref", `invalid narrative source reference: ${String(value)}`);
+    }
+  });
+}
+
+function atomic(proposition: string): string {
+  // Review H3: the atomicity scan runs over the template SKELETON — backtick-
+  // quoted free-text spans (commands) are excluded, so a command containing
+  // English conjunctions cannot trip it, while nothing outside quotes may
+  // introduce a second clause via any common conjunction.
+  const skeleton = proposition.replace(/`[^`]*`/g, "`_`");
+  if (UNICODE_LINE_SEPARATORS.test(skeleton) || skeleton.includes("; ") || /\s(and|but|then|while|or|so)\s/i.test(skeleton)) {
+    return fail("non_atomic_proposition", "statement proposition must contain exactly one clause");
+  }
+  return proposition;
+}
+
+function statementId(statementClass: StatementClass, proposition: string, refs: readonly string[]): string {
+  const identity = JSON.stringify([statementClass, proposition, [...refs].sort()]);
+  // Review M1: 16 hex chars (64 bits) — 8 was collision-plausible at realistic
+  // statement volumes (~1% at 9.3k statements).
+  return createHash("sha256").update(identity, "utf8").digest("hex").slice(0, 16);
+}
+
+function construct(input: {
+  class: StatementClass;
+  proposition: string;
+  sourceRefs: readonly string[];
+  turnRef?: number;
+  actor?: string;
+  rule?: StatementRule;
+  selfReport?: true;
+  id?: string;
+}): Statement {
+  const refs = sourceRefs(input.sourceRefs);
+  const proposition = atomic(input.proposition);
+  if ((input.class === "observed" || input.class === "summarizer_inferred" || input.class === "agent_stated") && input.rule) {
+    return fail("invalid_rule", `${input.class} statements must not carry a rule`);
+  }
+  if (input.class === "deterministic_derived" && !input.rule) return fail("invalid_rule", "deterministic_derived statements require a rule");
+  // #622: an agent_stated annotation is a typed self-report. It MUST carry an
+  // attributed actor and the required literal self_report:true, and ONLY the
+  // agent_stated class may carry that flag — no other class can masquerade as a
+  // self-report, and a self-report can never be anonymous.
+  if (input.class === "agent_stated") {
+    if (input.actor === undefined) return fail("invalid_input", "agent_stated statements require an actor");
+    if (input.selfReport !== true) return fail("invalid_input", "agent_stated statements require self_report: true");
+  } else if (input.selfReport !== undefined) {
+    return fail("invalid_input", "self_report is only valid on agent_stated statements");
+  }
+  if (input.turnRef !== undefined && (!Number.isSafeInteger(input.turnRef) || input.turnRef < -1)) {
+    return fail("invalid_input", "turn_ref must be a safe turn ordinal");
+  }
+
+  let rule: StatementRule | undefined;
+  if (input.rule) {
+    const inputs = sourceRefs(input.rule.inputs);
+    if (inputs.some((sourceId) => !refs.includes(sourceId))) return fail("invalid_rule", "rule inputs must be a subset of source_refs");
+    rule = { id: text(input.rule.id, "rule.id"), version: text(input.rule.version, "rule.version"), inputs };
+  }
+
+  const actor = input.actor === undefined ? undefined : text(input.actor, "actor");
+  const id = input.id !== undefined ? identifier(input.id, "id") : statementId(input.class, proposition, refs);
+  return {
+    id,
+    class: input.class,
+    proposition,
+    source_refs: refs,
+    ...(input.turnRef !== undefined ? { turn_ref: input.turnRef } : {}),
+    ...(actor !== undefined ? { actor } : {}),
+    ...(rule ? { rule } : {}),
+    ...(input.selfReport === true ? { self_report: true as const } : {}),
+  };
+}
+
+export function observedCommand(input: {
+  sourceId: string;
+  command: string;
+  observedResult: ObservedResult;
+  exitCode: number | null;
+  actor?: string;
+}): Statement {
+  const command = text(input.command, "command");
+  if (!["pass", "fail", "ambiguous"].includes(input.observedResult)) return fail("invalid_input", "observedResult is invalid");
+  if (input.exitCode !== null && !Number.isSafeInteger(input.exitCode)) return fail("invalid_input", "exitCode must be an integer or null");
+  if (input.observedResult === "pass" && input.exitCode !== 0) return fail("invalid_input", "a passing observation requires exitCode 0");
+  if (input.observedResult !== "pass" && input.exitCode === 0) return fail("invalid_input", "exitCode 0 requires a passing observation");
+  const result = input.observedResult === "ambiguous" ? "complete ambiguously" : input.observedResult;
+  const exit = input.exitCode === null ? "unknown" : String(input.exitCode);
+  return construct({
+    class: "observed",
+    proposition: `Command \`${command}\` was observed to ${result} (exit ${exit})`,
+    sourceRefs: [input.sourceId],
+    ...(input.actor !== undefined ? { actor: input.actor } : {}),
+  });
+}
+
+export function observedToolAction(input: {
+  sourceId: string;
+  toolName: string;
+  eventType: string;
+  actor?: string;
+}): Statement {
+  return construct({
+    class: "observed",
+    proposition: `Tool ${identifier(input.toolName, "toolName")} emitted event ${identifier(input.eventType, "eventType")}`,
+    sourceRefs: [input.sourceId],
+    ...(input.actor !== undefined ? { actor: input.actor } : {}),
+  });
+}
+
+export function observedDelegation(input: {
+  sourceId: string;
+  agentId?: string | null;
+  targets?: string[];
+}): Statement {
+  const actor = input.agentId == null || input.agentId === "" ? "unattributed" : identifier(input.agentId, "agentId");
+  const targets = input.targets?.map((target) => identifier(target, "target")) ?? [];
+  const proposition = targets.length > 0
+    ? `Agent ${actor} delegated work to ${targets.join(", ")}`
+    : `Agent ${actor} delegated work`;
+  return construct({ class: "observed", proposition, sourceRefs: [input.sourceId], actor });
+}
+
+export function observedFileCreation(input: { sourceId: string; path: string }): Statement {
+  // Re-review H3 regression fix: paths are legitimately space-bearing free
+  // text (the fa1 file scope is percent-encoded), so they quote like commands
+  // rather than passing the identifier charset — injection stays impossible
+  // because the atomicity scan runs over the backtick-stripped skeleton.
+  return construct({
+    class: "observed",
+    proposition: `File \`${text(input.path, "path")}\` was observed to be created`,
+    sourceRefs: [input.sourceId],
+  });
+}
+
+export function derivedRetry(input: {
+  sourceIds: string[];
+  command: string;
+  attempts: number;
+  ruleInputs: string[];
+}): Statement {
+  if (!Number.isSafeInteger(input.attempts) || input.attempts < 2) return fail("invalid_input", "attempts must be an integer of at least two");
+  const command = text(input.command, "command");
+  return construct({
+    class: "deterministic_derived",
+    proposition: `Command \`${command}\` was retried across ${input.attempts} attempts`,
+    sourceRefs: input.sourceIds,
+    rule: { id: "retry-detection", version: "v1", inputs: input.ruleInputs },
+  });
+}
+
+export function derivedNoOpTurn(input: { turnRef: number; sourceIds: string[] }): Statement {
+  if (!Number.isSafeInteger(input.turnRef) || input.turnRef < -1) return fail("invalid_input", "turnRef must be a safe turn ordinal");
+  return construct({
+    class: "deterministic_derived",
+    proposition: `Turn ${input.turnRef} was classified as a no-op`,
+    sourceRefs: input.sourceIds,
+    turnRef: input.turnRef,
+    rule: { id: "no-op-turn", version: "v1", inputs: input.sourceIds },
+  });
+}
+
+export function derivedTimeout(input: { sourceId: string; operation: string; timeoutMs?: number }): Statement {
+  // Review H2a: the timeout fact is material with or without a recorded duration.
+  if (input.timeoutMs !== undefined && (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 0)) return fail("invalid_input", "timeoutMs must be a non-negative safe integer when present");
+  const budget = input.timeoutMs === undefined ? "its timeout (duration unknown)" : `its ${input.timeoutMs} ms timeout`;
+  return construct({
+    class: "deterministic_derived",
+    proposition: `Operation \`${text(input.operation, "operation")}\` exceeded ${budget}`,
+    sourceRefs: [input.sourceId],
+    rule: { id: "timeout-detection", version: "v1", inputs: [input.sourceId] },
+  });
+}
+
+export function derivedUnavailableSource(input: { sourceId: string; reason: UnavailableReason }): Statement {
+  if (!["expired", "redacted", "unauthorized", "not_captured", "corrupt"].includes(input.reason)) {
+    return fail("invalid_input", "reason is not a supported unavailable-source reason");
+  }
+  return construct({
+    class: "deterministic_derived",
+    proposition: `Source ${input.sourceId} was unavailable because ${text(input.reason, "reason")}`,
+    sourceRefs: [input.sourceId],
+    rule: { id: "unavailable-source", version: "v1", inputs: [input.sourceId] },
+  });
+}
+
+// #614: the model-assisted prose renderer's connective class. A summarizer_inferred
+// statement carries generated connective text (never a raw model claim standing alone —
+// the dormant PROHIBITED_ASSERTIONS/grounding-check:summary checks in grounding-validator.ts
+// are the enforcement layer) and MUST cite the real fa1 source_refs of the atomic
+// (observed/deterministic_derived) statements it summarizes -- never a fabricated or
+// statement-id-shaped reference. No `rule`: that field is deterministic_derived-only.
+export function summarizerInferredConnective(input: {
+  id?: string;
+  proposition: string;
+  source_refs: string[];
+  turn_ref?: number;
+  actor?: string;
+}): Statement {
+  return construct({
+    class: "summarizer_inferred",
+    proposition: nonEmptyText(input.proposition, "proposition"),
+    sourceRefs: input.source_refs,
+    ...(input.turn_ref !== undefined ? { turnRef: input.turn_ref } : {}),
+    ...(input.actor !== undefined ? { actor: input.actor } : {}),
+    ...(input.id !== undefined ? { id: input.id } : {}),
+  });
+}
+
+// #622: the agent's STATED purpose for a material action — a typed self-report
+// (never proof, never gate evidence). Modeled on summarizerInferredConnective
+// but deliberately using the STRICT text()+atomic() guards (NOT the relaxed
+// nonEmptyText path) plus a hard length cap AND a single-clause bound: a
+// multi-clause / reasoning-dump / sentence-chained / comma-listed / over-length
+// purpose is rejected AT CONSTRUCT TIME (review HIGH R2). There is no
+// reasoning/alternatives/hidden_alternative field — the field allowlist forbids
+// free-form chain-of-thought (R2). The purpose cites exactly the material
+// action's fa1 source (sourceId); self_report:true and an attributed actor are
+// REQUIRED (enforced in construct()). The `actor` is constrained to the strict
+// identifier charset + a hard length cap (review HIGH R2): it is an attribution
+// KEY, never a place to smuggle prose or prohibited-assertion keywords past the
+// proposition scan (grounding-validator additionally scans the actor).
+export function agentStatedIntent(input: {
+  sourceId: string;
+  purpose: string;
+  actor: string;
+  turnRef?: number;
+}): Statement {
+  const purpose = text(input.purpose, "purpose");
+  if (purpose.length > AGENT_STATED_PURPOSE_MAX_LENGTH) {
+    return fail("invalid_input", `purpose must be at most ${AGENT_STATED_PURPOSE_MAX_LENGTH} characters`);
+  }
+  singleClause(purpose, "purpose");
+  const actor = identifier(input.actor, "actor");
+  if (actor.length > AGENT_STATED_ACTOR_MAX_LENGTH) {
+    return fail("invalid_input", `actor must be at most ${AGENT_STATED_ACTOR_MAX_LENGTH} characters`);
+  }
+  return construct({
+    class: "agent_stated",
+    proposition: `Agent stated the purpose of this action is to ${purpose}`,
+    sourceRefs: [input.sourceId],
+    actor,
+    selfReport: true,
+    ...(input.turnRef !== undefined ? { turnRef: input.turnRef } : {}),
+  });
+}
+
+// #622: the deterministic fallback emitted where at-action intent capture is not
+// supported (or no purpose survives the policy filter). A deterministic_derived
+// statement whose proposition is derived ONLY from the active gate reference —
+// NEVER a fabricated agent rationale. Structurally distinct from agent_stated
+// (a different class carrying a rule and NO self_report flag), so the fallback
+// can never be mistaken for a self-report the agent did not make (R4).
+export function workflowDerivedPurpose(input: {
+  activeGateRef: string;
+  objectiveRef?: string;
+}): Statement {
+  const refs = input.objectiveRef ? [input.activeGateRef, input.objectiveRef] : [input.activeGateRef];
+  return construct({
+    class: "deterministic_derived",
+    proposition: `Intent for this action was derived from active gate reference ${input.activeGateRef}`,
+    sourceRefs: refs,
+    rule: { id: "workflow-derived-purpose", version: "v1", inputs: [input.activeGateRef] },
+  });
+}

package/src/narrative/turn-spine.ts

@@ -0,0 +1,99 @@
+export const TURN_SPINE_RULE_ID = "turn-spine/v1" as const;
+export const QUARANTINE_SESSION_ID = "quarantine" as const;
+
+export interface ResolvedTelemetryRecord {
+  sourceId: string;
+  record: Record<string, unknown>;
+}
+
+export interface TurnBoundary {
+  derived: boolean;
+  rule_id?: typeof TURN_SPINE_RULE_ID;
+}
+
+export interface Turn {
+  ordinal: number;
+  sessionId: string;
+  turnId?: string;
+  boundary: TurnBoundary;
+  sources: string[];
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function hookTurnId(record: Record<string, unknown>): string | undefined {
+  const hook = record["hook"];
+  if (!hook || typeof hook !== "object" || Array.isArray(hook)) return undefined;
+  return nonEmptyString((hook as Record<string, unknown>)["turn_id"]);
+}
+
+/** Correlate frozen telemetry records without consulting a live runtime store. */
+export function buildTurnSpine(records: readonly ResolvedTelemetryRecord[]): Turn[] {
+  const turns: Turn[] = [];
+  const explicitBySession = new Map<string, Map<string, Turn>>();
+  const derivedBySession = new Map<string, Turn>();
+  const quarantineSources: string[] = [];
+
+  const createTurn = (sessionId: string, turnId?: string): Turn => {
+    const boundary: TurnBoundary = turnId
+      ? { derived: false }
+      : { derived: true, rule_id: TURN_SPINE_RULE_ID };
+    const turn: Turn = {
+      ordinal: turns.length,
+      sessionId,
+      ...(turnId ? { turnId } : {}),
+      boundary,
+      sources: [],
+    };
+    turns.push(turn);
+    return turn;
+  };
+
+  for (const input of records) {
+    const sessionId = nonEmptyString(input.record?.["session_id"]);
+    if (!sessionId) {
+      quarantineSources.push(input.sourceId);
+      continue;
+    }
+
+    const turnId = hookTurnId(input.record);
+    if (turnId) {
+      let byTurnId = explicitBySession.get(sessionId);
+      if (!byTurnId) {
+        byTurnId = new Map<string, Turn>();
+        explicitBySession.set(sessionId, byTurnId);
+      }
+      let turn = byTurnId.get(turnId);
+      if (!turn) {
+        turn = createTurn(sessionId, turnId);
+        byTurnId.set(turnId, turn);
+      }
+      turn.sources.push(input.sourceId);
+      // Review H1: an explicit turn is a boundary for the session's derived
+      // spine too — close any active derived turn so a later spine-less event
+      // starts a fresh turn instead of merging across this boundary.
+      derivedBySession.delete(sessionId);
+      continue;
+    }
+
+    let turn = derivedBySession.get(sessionId);
+    if (!turn || input.record["event_type"] === "turn.user") {
+      turn = createTurn(sessionId);
+      derivedBySession.set(sessionId, turn);
+    }
+    turn.sources.push(input.sourceId);
+  }
+
+  if (quarantineSources.length > 0) {
+    turns.push({
+      ordinal: -1,
+      sessionId: QUARANTINE_SESSION_ID,
+      boundary: { derived: true, rule_id: TURN_SPINE_RULE_ID },
+      sources: quarantineSources,
+    });
+  }
+
+  return turns;
+}

package/src/tools/build-universal-bundles.ts

@@ -454,6 +454,14 @@ function copySharedContent(targetRoot: string, targetName: string, token: string
   const commonBuilt = path.join(root, "build/src/tools/common.js");
   if (fs.existsSync(commonBuilt)) writeText(path.join(targetRoot, "scripts/common.mjs"), readText(commonBuilt));
   copyTree(path.join(root, "build/src"), path.join(targetRoot, "build/src"), targetName, token);
+  // #620: ship the build-only capability-declarations JSON inside each bundle so an
+  // installed economics-record emitter (and hooks) can read it at build/generated/
+  // relative to the bundle root. It is generated unconditionally by `npm run build`
+  // (the tsc build's --json-only step) and is never committed (build/ is gitignored).
+  const capabilityDeclJson = path.join(root, "build/generated/capability-declarations.json");
+  if (fs.existsSync(capabilityDeclJson)) {
+    writeText(path.join(targetRoot, "build/generated/capability-declarations.json"), readText(capabilityDeclJson));
+  }
 }
 function installScript(label: string, capability: BundleCapability, defaultDestDisplay: string, token?: string, destFallbackShell?: string, mergeConfig?: { configRelPath: string; managedConfigRelPath: string; runtime: string; version: string }, stampConfig?: { runtime: string; version: string }): string {
   const replaceBlock = token ? `\nexport DEST\nfind "$DEST" \\( -path "$DEST/AGENTS.md" -o -path "$DEST/CLAUDE.md" \\) -prune -o -type f \\( -name '*.json' -o -name '*.md' -o -name '*.sh' -o -name '*.js' -o -name '*.ts' -o -name '*.yaml' -o -name '*.yml' \\) -print0 | xargs -0 perl -0pi -e 's#${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}#$ENV{DEST}#g'` : "";