@snag-run/core 0.3.0

package/dist/schema.js

@@ -0,0 +1,573 @@
+import { z } from "zod";
+// failure-map/v1 Zod schema — the interop contract shared by the CLI
+// (generation + render) and, later, the backend. Ported from
+// spikes/failure-map/failure-map.schema.json with the cli-v1.md decisions:
+//   - categorical `severity` is DROPPED (scores.severity is the only impact
+//     encoding); the band is derived (see severity.ts).
+//   - discriminated union on node `type` instead of the spike's if/then.
+//   - two schemas: the LLM generation surface ({ nodes, edges }) and the full
+//     engine-assembled document (schema + subject + meta envelope).
+//   - hard validation via superRefine: unique node ids + edge referential
+//     integrity. Soft lint lives in lint.ts.
+const SCHEMA_ID = "failure-map/v1";
+/** The canonical node-id format on the persisted document: lowercase
+ * alphanumerics + underscore. Enforced on the final {@link failureMapSchema}
+ * (the interop contract a renderer/backend relies on), NOT on the generation
+ * surface — see {@link coerceNodeIds}. */
+const NODE_ID_PATTERN = /^[a-z0-9_]+$/;
+const NODE_ID_MESSAGE = "node id must match ^[a-z0-9_]+$";
+/** Node id as the LLM emits it (#280): any non-empty string. The strict
+ * `^[a-z0-9_]+$` form is NOT required here — a single malformed id (uppercase,
+ * `-`, `.`, a `file:line`-style id, …) used to reject the *entire* generated
+ * map at the `generateObject` SDK boundary, and the ~2 retries could not
+ * reliably re-roll a clean one (the whole-map-reject brittleness). Ids are
+ * mechanical identifiers, so {@link coerceNodeIds} repairs them to
+ * {@link NODE_ID_PATTERN} after generation instead of failing. */
+const nodeId = z.string().min(1, "node id must be a non-empty string");
+/**
+ * One FMEA risk factor (integer 1-5). `bounded` chooses the JSON-Schema
+ * encoding: `minimum`/`maximum` (the natural form) when `true`, or a Zod
+ * `.refine()` that carries NO numeric-bound keywords when `false`. The
+ * bounds-free form exists for OpenAI-compatible gateways whose structured-output
+ * validator rejects `minimum`/`maximum` on integers — AssemblyAI's LLM gateway
+ * returns "For 'integer' type, properties maximum, minimum are not supported"
+ * (#231). Both forms validate the 1-5 range identically once the model responds;
+ * only the schema *hint* sent to the model differs.
+ */
+function riskFactor(bounded) {
+    const base = z
+        .number()
+        .int()
+        .describe("FMEA risk factor: integer 1-5 (inclusive)");
+    return bounded
+        ? base.min(1).max(5)
+        : base.refine((n) => n >= 1 && n <= 5, {
+            message: "FMEA risk factor must be between 1 and 5 (inclusive)",
+        });
+}
+function buildScores(bounded) {
+    const factor = riskFactor(bounded);
+    return z.object({ severity: factor, frequency: factor, detection: factor });
+}
+/** FMEA risk factors (each 1-5). RPN = severity * frequency * detection. The
+ * default bounded encoding; see {@link generationSchemaNoNumericBounds} for the
+ * gateway-safe variant (#231). */
+export const scoresSchema = buildScores(true);
+// Fields shared by every node. `.object()` (not `.strict()`) strips unknown
+// keys — this is what lets the spike fixture's legacy categorical `severity`
+// parse while keeping it out of the derived type.
+const baseNodeShape = {
+    id: nodeId,
+    label: z.string(),
+    group: z.string().optional(),
+    sourceRef: z.string().optional(),
+};
+/** A non-failure node on the map (the happy-path spine + branches). */
+export const flowNodeSchema = z.object({
+    ...baseNodeShape,
+    type: z.enum(["step", "decision", "terminal", "recovery"]),
+});
+// The failure-node fields *other than* `scores` — shared by the bounded export
+// below and the bounds-free generation variant (#231) so the two can never
+// drift. `scores` is added separately because it is the only field whose
+// encoding varies by provider.
+const failureNodeShapeSansScores = {
+    ...baseNodeShape,
+    type: z.literal("failure"),
+    /** Coarse failure-mode taxonomy for grouping/coverage (#56). Free-form during
+     * the discovery phase — required so the model reliably populates it, but NOT
+     * an enum yet (the vocabulary is still settling across real maps). */
+    class: z.string(),
+    silent: z.boolean(),
+    handled: z.boolean(),
+    reviewWouldMiss: z.boolean(),
+    trigger: z.string(),
+    manifestation: z.string(),
+    suggestedFix: z.string(),
+    fixEffort: z.enum(["trivial", "small", "medium", "large"]).optional(),
+    /** Engine-stamped stable identity (ADR 0002 seam, #78). A deterministic
+     * SHA-256 fingerprint over normalized semantic fields (`class` + `trigger`
+     * + `manifestation`). Optional for back-compat with already-committed maps
+     * and fixtures; always populated by `assembleDocument` on newly assembled
+     * documents. The LLM never produces this field. */
+    fingerprint: z.string().optional(),
+};
+/** A failure node / failure mode. Carries the required FMEA fields. */
+export const failureNodeSchema = z.object({
+    ...failureNodeShapeSansScores,
+    scores: scoresSchema,
+});
+/** Discriminated union on `type`: failure vs. flow node. */
+export const nodeSchema = z.discriminatedUnion("type", [
+    failureNodeSchema,
+    flowNodeSchema,
+]);
+export const edgeSchema = z.object({
+    from: z.string(),
+    to: z.string(),
+    type: z.enum(["happy", "branch", "recovery", "failure"]),
+    condition: z.string().optional(),
+});
+// Hard validation shared by the generation schema and the full document:
+// unique node ids + edge referential integrity. Both produce a
+// broken/unrenderable artifact, so they reject rather than warn.
+function refineNodesAndEdges(value, ctx) {
+    const seen = new Set();
+    value.nodes.forEach((node, i) => {
+        if (seen.has(node.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `duplicate node id: ${node.id}`,
+                path: ["nodes", i, "id"],
+            });
+        }
+        seen.add(node.id);
+    });
+    value.edges.forEach((edge, i) => {
+        if (!seen.has(edge.from)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `edge references unknown node id in 'from': ${edge.from}`,
+                path: ["edges", i, "from"],
+            });
+        }
+        if (!seen.has(edge.to)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `edge references unknown node id in 'to': ${edge.to}`,
+                path: ["edges", i, "to"],
+            });
+        }
+    });
+}
+const nodesAndEdges = {
+    nodes: z.array(nodeSchema).min(1),
+    edges: z.array(edgeSchema),
+};
+/**
+ * The LLM generation surface: the tight { nodes, edges } analysis the model
+ * produces. Smallest surface = best structured-output reliability.
+ */
+export const generationSchema = z
+    .object(nodesAndEdges)
+    .superRefine(refineNodesAndEdges);
+/**
+ * The bounds-free generation surface (#231): identical to {@link generationSchema}
+ * except the FMEA `scores` carry no JSON-Schema `minimum`/`maximum`. The engine
+ * sends this to OpenAI-compatible gateways (AssemblyAI, …) whose structured-output
+ * validator rejects numeric bounds on integers. The 1-5 range is still enforced —
+ * by the `.refine()` on each factor when this schema parses, and again by the
+ * full document schema (which keeps the bounded `scoresSchema`) on assembly — so
+ * nothing is lost but the in-schema hint to the model.
+ */
+const failureNodeSchemaNoNumericBounds = z.object({
+    ...failureNodeShapeSansScores,
+    scores: buildScores(false),
+});
+const nodeSchemaNoNumericBounds = z.discriminatedUnion("type", [
+    failureNodeSchemaNoNumericBounds,
+    flowNodeSchema,
+]);
+export const generationSchemaNoNumericBounds = z
+    .object({
+    nodes: z.array(nodeSchemaNoNumericBounds).min(1),
+    edges: z.array(edgeSchema),
+})
+    .superRefine(refineNodesAndEdges);
+// --- #272 fix: REQUIRE sourceRef on code-intake failure nodes ---
+//
+// The code-v3 emit prompt forcefully demands a `file:line` citation on every
+// failure node, yet three prompt variants produced ZERO citations — because
+// `sourceRef` is `.optional()` on the base node and structured-output models
+// drop optional fields regardless of the prose (root cause (a) in
+// codemap-sourceref-grounding). The lever the prompt can't pull is the SCHEMA:
+// making the field required compels the model to emit it.
+//
+// Required ONLY for code intakes (`module`/`capability`) and ONLY on the FAILURE
+// arm — spec/doc maps have no source line, and flow (step/decision/…) nodes keep
+// `sourceRef` optional. The hard `file:line`/in-scope validity check stays SOFT
+// (lint.ts `uncited-code-failure`): a non-empty string is all the schema demands,
+// so a slightly-off citation can't fail the whole map (the brittle gate that broke
+// generation). The soft lint then flags hallucinated/out-of-scope refs. These
+// variants mirror the two discriminated-union surfaces above; the flat/strict
+// surface is deliberately left unchanged (it flattens every node to one shape, so
+// requiring sourceRef there would force flow nodes to cite too — revisit when an
+// OpenAI code-intake eval needs it).
+export const REQUIRED_SOURCEREF_MESSAGE = 'every code-map failure node must cite the file:line it lives on — set sourceRef (e.g. "worktree.go:110")';
+/** The failure-node fields (sans `scores`) with `sourceRef` made required. */
+const failureNodeCodeShapeSansScores = {
+    ...failureNodeShapeSansScores,
+    sourceRef: z.string().min(1, REQUIRED_SOURCEREF_MESSAGE),
+};
+function codeGenerationSchema(bounded) {
+    const failureNode = z.object({
+        ...failureNodeCodeShapeSansScores,
+        scores: buildScores(bounded),
+    });
+    const node = z.discriminatedUnion("type", [failureNode, flowNodeSchema]);
+    return z
+        .object({ nodes: z.array(node).min(1), edges: z.array(edgeSchema) })
+        .superRefine(refineNodesAndEdges);
+}
+/** The bounded code-intake generation surface: {@link generationSchema} with a
+ * required `sourceRef` on failure nodes (#272). Sent to providers that accept
+ * integer numeric bounds (anthropic). */
+export const generationSchemaCode = codeGenerationSchema(true);
+/** The bounds-free code-intake generation surface: {@link
+ * generationSchemaNoNumericBounds} with a required `sourceRef` on failure nodes
+ * (#272). Sent to OpenAI-compatible gateways that reject integer bounds. */
+export const generationSchemaCodeNoNumericBounds = codeGenerationSchema(false);
+/**
+ * The STRICT-compatible generation surface (#247). OpenAI strict structured
+ * output (`response_format: json_schema`, `strict: true`) is the token-level
+ * enforcement that stops the model re-emitting nodes — which non-strict gateways
+ * (AssemblyAI) otherwise turn into a duplicate-id hard failure. But strict mode
+ * forbids `oneOf`, and our node {@link nodeSchema} is a discriminated union
+ * (`failure | flow`) which Zod emits as `oneOf` — so strict rejects it outright
+ * (`'oneOf' is not permitted`).
+ *
+ * This surface sidesteps that by FLATTENING the union into a single node object:
+ * one `type` enum (incl. `"failure"`) and the failure-only fields made nullable
+ * (populated for `type: "failure"`, `null` otherwise). No union → no `oneOf`.
+ * It is also bounds-free (strict also rejects integer `minimum`/`maximum`). The
+ * flat output is re-projected onto the canonical discriminated union by
+ * {@link normalizeFlatGeneration} immediately after generation, so the rest of
+ * the engine (envelope, assembly, the full document schema) is unchanged — this
+ * is purely the shape we hand the model, not a new internal node type.
+ */
+// Strict mode forbids integer `minimum`/`maximum`, so the flat factor carries no
+// in-schema bound — that leaves the JSON-Schema `description` as the ONLY in-schema
+// 1-5 signal the model gets (the canonical `riskFactor` describe is otherwise lost
+// on this surface). `normalizeFlatGeneration` re-imposes the hard 1-5 bound after
+// generation, where a violation is a no-retry terminal error — so guiding the model
+// up front matters. The text mirrors `riskFactor` for parity (#247).
+const flatBareFactor = z
+    .number()
+    .int()
+    .describe("FMEA risk factor: integer 1-5 (inclusive)");
+const flatNodeSchema = z.object({
+    id: nodeId,
+    type: z.enum(["step", "decision", "terminal", "recovery", "failure"]),
+    label: z.string(),
+    // Optional-on-the-union fields, made nullable so strict keeps them `required`.
+    group: z.string().nullable(),
+    sourceRef: z.string().nullable(),
+    // Failure-only fields: present for `type: "failure"`, `null` for flow nodes.
+    class: z.string().nullable(),
+    silent: z.boolean().nullable(),
+    handled: z.boolean().nullable(),
+    reviewWouldMiss: z.boolean().nullable(),
+    trigger: z.string().nullable(),
+    manifestation: z.string().nullable(),
+    suggestedFix: z.string().nullable(),
+    fixEffort: z.enum(["trivial", "small", "medium", "large"]).nullable(),
+    scores: z
+        .object({
+        severity: flatBareFactor,
+        frequency: flatBareFactor,
+        detection: flatBareFactor,
+    })
+        .nullable(),
+});
+const flatEdgeSchema = z.object({
+    from: z.string(),
+    to: z.string(),
+    type: z.enum(["happy", "branch", "recovery", "failure"]),
+    condition: z.string().nullable(),
+});
+export const flatGenerationSchema = z.object({
+    nodes: z.array(flatNodeSchema).min(1),
+    edges: z.array(flatEdgeSchema),
+});
+/**
+ * Project a flat strict-mode generation ({@link flatGenerationSchema}) back onto
+ * the canonical discriminated-union {@link Generation}: drop the `null`
+ * failure-only fields from flow nodes, keep them on failure nodes, strip `null`
+ * optionals, then re-validate through {@link generationSchema}. That final parse
+ * re-imposes everything the flat surface relaxed for strict's sake — the 1-5
+ * `scores` bounds, the per-`type` required fields (a `failure` node missing its
+ * `scores`/`class` throws here), unique ids and edge referential integrity — so a
+ * malformed flat map fails exactly as a malformed union map would. `input` is
+ * `unknown` (defence-in-depth for an injected seam): it is parsed through the flat
+ * schema first.
+ */
+export function normalizeFlatGeneration(input) {
+    const flat = flatGenerationSchema.parse(input);
+    const nodes = flat.nodes.map((n) => {
+        const base = {
+            id: n.id,
+            label: n.label,
+            ...(n.group != null ? { group: n.group } : {}),
+            ...(n.sourceRef != null ? { sourceRef: n.sourceRef } : {}),
+        };
+        if (n.type === "failure") {
+            return {
+                ...base,
+                type: "failure",
+                class: n.class,
+                silent: n.silent,
+                handled: n.handled,
+                reviewWouldMiss: n.reviewWouldMiss,
+                trigger: n.trigger,
+                manifestation: n.manifestation,
+                suggestedFix: n.suggestedFix,
+                ...(n.fixEffort != null ? { fixEffort: n.fixEffort } : {}),
+                scores: n.scores,
+            };
+        }
+        return { ...base, type: n.type };
+    });
+    const edges = flat.edges.map((e) => ({
+        from: e.from,
+        to: e.to,
+        type: e.type,
+        ...(e.condition != null ? { condition: e.condition } : {}),
+    }));
+    return generationSchema.parse({ nodes, edges });
+}
+/** Lowercase + collapse every run of non-`[a-z0-9_]` to a single `_`, then trim
+ * leading/trailing `_`. `worktree.go:18` → `worktree_go_18`, `Fail-GitHang` →
+ * `fail_githang`. An id that is all punctuation collapses to `""` and the caller
+ * substitutes a placeholder. */
+function slugifyNodeId(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+/**
+ * Repair LLM-emitted node ids to the canonical {@link NODE_ID_PATTERN} (#280)
+ * and rewrite every edge endpoint with the SAME mapping so references stay
+ * intact (an un-rewritten endpoint would become a dangling edge). Ids are
+ * mechanical identifiers — a bad character should be slugified, never fatal.
+ *
+ * Identity-preserving by construction:
+ * - Distinct raw ids that slugify to the same value are kept distinct (a `_2`,
+ *   `_3`, … suffix on collision), so two nodes never silently merge.
+ * - Equal raw ids map to the same slug, so a genuine duplicate-id still trips
+ *   {@link refineNodesAndEdges} downstream (this does not paper over duplicates).
+ * - An empty slug (all-punctuation id) falls back to `node`.
+ * - An edge endpoint with no matching node id is left as-is, so a dangling edge
+ *   still surfaces as a referential-integrity error rather than being hidden.
+ *
+ * Does NOT touch the semantic `fingerprint` (over class/trigger/manifestation),
+ * so stable identity / reconciliation is unaffected.
+ */
+export function coerceNodeIds(generation) {
+    const mapping = new Map();
+    const used = new Set();
+    // Pass 1: reserve ids ALREADY in canonical form so a valid id is never
+    // displaced by an earlier node whose slug happens to collide with it. This
+    // keeps the assignment independent of node order and makes #280 a pure repair
+    // of the *malformed* ids — the stable ones pass through untouched.
+    for (const node of generation.nodes) {
+        if (NODE_ID_PATTERN.test(node.id) && !mapping.has(node.id)) {
+            used.add(node.id);
+            mapping.set(node.id, node.id);
+        }
+    }
+    // Pass 2: slugify the rest, collision-guarding against the reserved set.
+    for (const node of generation.nodes) {
+        if (mapping.has(node.id))
+            continue; // reserved canonical, or an equal raw id (dup stays a dup)
+        const base = slugifyNodeId(node.id) || "node";
+        let candidate = base;
+        let n = 2;
+        while (used.has(candidate))
+            candidate = `${base}_${n++}`;
+        used.add(candidate);
+        mapping.set(node.id, candidate);
+    }
+    const nodes = generation.nodes.map((node) => ({
+        ...node,
+        id: mapping.get(node.id) ?? node.id,
+    }));
+    const edges = generation.edges.map((edge) => ({
+        ...edge,
+        from: mapping.get(edge.from) ?? edge.from,
+        to: mapping.get(edge.to) ?? edge.to,
+    }));
+    return { nodes, edges };
+}
+// --- #272: a grounding `sourceRef` on failure nodes for CODE intakes ---
+//
+// `sourceRef` is `optional()` on the base node because spec/PRD maps
+// (`subject.kind: document | process | pull_request`) have no source line to
+// cite. For the code intakes (`module`/`capability`) every FAILURE node SHOULD
+// cite the `file:line` that produces it — the lever against the speculative
+// "false-unaddressed" garbage surfaced by the treetop dogfood (#131): a citation
+// collapses the gap between an imagined guard and the code as built. The code-v2
+// prompt requests it; a missing/invalid citation is surfaced as a SOFT lint
+// warning (see lint.ts `uncited-code-failure`), never a hard rejection — hard
+// gating the whole map on every node proved too brittle to generate (one of ~30
+// failure nodes missing a ref fails the whole map; whole-map retry can't repair a
+// single node). The helpers below are the shared validity check for that lint.
+/** Split a code subject's `ref` ("a.go, dir/b.go") into its discovered path set
+ * (#272). Absent/empty ref → empty set (scope unknown: format is still checked,
+ * path membership is not). */
+export function scopePathsFromRef(ref) {
+    if (!ref)
+        return new Set();
+    return new Set(ref
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0));
+}
+/**
+ * Validate a failure node's `sourceRef` as a concrete, in-scope citation (#272).
+ * Returns a human-readable problem (used verbatim as the retry/repair hint the
+ * model sees on a re-prompt) or `null` when the ref is acceptable. A valid ref is
+ * `file:line` (or `file:line-line`) whose `file` is one of the analyzed-scope
+ * paths. When `scopePaths` is empty the path-membership check is skipped (scope
+ * unknown) — the `file:line` shape is still enforced.
+ */
+export function sourceRefProblem(ref, scopePaths) {
+    if (ref == null || ref.trim() === "") {
+        return 'every failure node on a code map must cite the file:line that produces it (set sourceRef, e.g. "worktree.go:110")';
+    }
+    const lastColon = ref.lastIndexOf(":");
+    if (lastColon <= 0 || lastColon === ref.length - 1) {
+        return `sourceRef "${ref}" must be "file:line" — a file path and the line the failure lives on (e.g. "worktree.go:110")`;
+    }
+    const path = ref.slice(0, lastColon);
+    const lineSpec = ref.slice(lastColon + 1);
+    if (!/^\d+(-\d+)?$/.test(lineSpec)) {
+        return `sourceRef "${ref}" must end in a line number ("file:line"); "${lineSpec}" is not a line`;
+    }
+    if (scopePaths.size > 0 && !scopePaths.has(path)) {
+        return `sourceRef "${ref}" cites "${path}", which is not in the analyzed scope — cite one of the files you were given`;
+    }
+    return null;
+}
+/**
+ * The artifact a Snag Map is derived from. `kind` is *what is being analyzed in
+ * the world* — `document` (a design) or `process` (a real business process; the
+ * intake is reserved, not wired yet), or a code grain: `function` ⊂ `module` ⊂
+ * `capability` (the cross-cutting grain spanning modules/boundaries, derived
+ * agentically by-name, #85), with `pull_request` the orthogonal change-axis. The
+ * enum is *additive* — already-committed maps keep validating as kinds are added.
+ */
+export const subjectSchema = z.object({
+    kind: z.enum([
+        "pull_request",
+        "document",
+        "process",
+        "function",
+        "module",
+        "capability",
+    ]),
+    ref: z.string().optional(),
+    title: z.string(),
+    /** Provenance / staleness anchor (#54): the git blob OID of the exact bytes
+     * mapped (`git hash-object <file>`). Optional so docs outside a git repo or
+     * untracked still validate. The CLI computes it; the engine only stamps it
+     * when provided (the engine stays git-free). */
+    sourceSha: z.string().optional(),
+});
+/** The code-intake subject kinds — the grains derived from existing source:
+ * `module` (review scope, {@link deriveCodeSubject}) and `capability` (by-name
+ * discovery, {@link deriveCapabilitySubject}). These are exactly the kinds for
+ * which a failure node MUST cite a `sourceRef` (#272); the spec kinds
+ * (`document`/`process`/`pull_request`) have no single source line to anchor.
+ * (`function` is in the enum but no intake derives it yet — it joins here when
+ * wired.) */
+export function isCodeIntakeKind(kind) {
+    return kind === "module" || kind === "capability";
+}
+/** The harnesses that can drive the engine (#297) — pure provenance, nothing
+ * branches on the value. `snag` is the native CLI on API tokens; `claude-code`
+ * and `codex` are skills/wrappers that drive the same engine on a subscription.
+ * Knowing which produced a map is what makes the native-API-vs-via-harness
+ * quality comparison (eval / model-support work) possible. Additive: a new
+ * harness joins the enum without breaking already-committed maps. */
+export const HARNESSES = ["snag", "claude-code", "codex"];
+/** Default harness when none is declared — the native `snag` CLI. */
+export const DEFAULT_HARNESS = "snag";
+/**
+ * Engine-stamped provenance (never produced by the LLM) — the poor-man's
+ * observability bridge to a future trace server.
+ */
+export const metaSchema = z.object({
+    engineVersion: z.string(),
+    generatedAt: z.string(),
+    /** Which harness drove the engine for this map (#297). `snag` (native CLI,
+     * default) | `claude-code` | `codex`. Provenance only — nothing branches on
+     * it. Optional so already-committed maps without it still validate; always
+     * stamped on newly generated maps (defaulting to `snag`). */
+    harness: z.enum(HARNESSES).optional(),
+    /** API protocol/SDK the map was generated against — Langfuse's "Adapter"
+     * (#55). `anthropic` | `openai` today (was `provider`). */
+    adapter: z.string(),
+    /** User-declared vendor/connection label — Langfuse's "Provider Name" (#55,
+     * e.g. "AssemblyAI", "OpenRouter", "Anthropic"). The engine can't infer the
+     * vendor (it only knows adapter + base URL), so this is optional and
+     * user-supplied. */
+    providerName: z.string().optional(),
+    model: z.string(),
+    /** Resolved provider base URL the map was generated against (provenance).
+     * Optional so existing maps/fixtures without it still validate; always
+     * stamped on newly generated maps. */
+    apiUrl: z.string().url().optional(),
+    promptVersion: z.string(),
+    /** Liveness/degrade flag (#83): TRUE when the agentic gather loop hit its hard
+     * step ceiling without converging, so the map was emitted from possibly
+     * incomplete gathered context. Optional + only stamped when true, so doc-path
+     * maps and already-committed maps omit it and still validate. Surfacing it in
+     * the viewer is a separate slice (#B). */
+    gatherStoppedAtCap: z.boolean().optional(),
+    /** Sampling temperature actually sent to the model (provenance, #173). Optional
+     * + only stamped when a temperature was applied: OpenAI reasoning models
+     * (gpt-5.x, o-series) reject an explicit `temperature`, so the engine omits it
+     * for them and leaves this absent. Already-committed maps without it still
+     * validate. */
+    temperature: z.number().optional(),
+    /** Output-token budget actually sent to the model (provenance, #234). Optional
+     * so already-committed maps without it still validate; always stamped on newly
+     * generated maps (the engine always sends an explicit budget — the AI SDK only
+     * forwards `max_tokens` when we pass it). */
+    maxOutputTokens: z.number().int().positive().optional(),
+    tokenUsage: z.object({
+        input: z.number().int().nonnegative(),
+        output: z.number().int().nonnegative(),
+        total: z.number().int().nonnegative(),
+    }),
+});
+/**
+ * Document-level hard validation: everything {@link refineNodesAndEdges} checks,
+ * PLUS the strict `^[a-z0-9_]+$` node-id format. The id format is enforced HERE
+ * (the persisted contract) rather than on the generation surface so a malformed
+ * model id is repaired by {@link coerceNodeIds} during assembly, not fatal at
+ * generation (#280). A hand-edited / already-committed map with a bad id still
+ * rejects.
+ */
+function refineDocument(value, ctx) {
+    value.nodes.forEach((node, i) => {
+        if (!NODE_ID_PATTERN.test(node.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: NODE_ID_MESSAGE,
+                path: ["nodes", i, "id"],
+            });
+        }
+    });
+    refineNodesAndEdges(value, ctx);
+}
+/** The full persisted failure-map/v1 document: envelope + analysis. */
+export const failureMapSchema = z
+    .object({
+    schema: z.literal(SCHEMA_ID),
+    subject: subjectSchema,
+    meta: metaSchema,
+    ...nodesAndEdges,
+})
+    .superRefine(refineDocument);
+export { SCHEMA_ID };
+/** Parse + validate the LLM generation surface; throws on invalid input. */
+export function parseGeneration(input) {
+    return generationSchema.parse(input);
+}
+/** Parse + validate a full failure-map/v1 document; throws on invalid input. */
+export function parseFailureMap(input) {
+    return failureMapSchema.parse(input);
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/severity.d.ts

@@ -0,0 +1,5 @@
+export declare const SEVERITY_BANDS: readonly ["critical", "high", "medium", "low"];
+export type SeverityBand = (typeof SEVERITY_BANDS)[number];
+/** Derive the categorical band from the 1-5 FMEA severity score. */
+export declare function severityBand(severity: number): SeverityBand;
+//# sourceMappingURL=severity.d.ts.map

package/dist/severity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.d.ts","sourceRoot":"","sources":["../src/severity.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,cAAc,gDAAiD,CAAC;AAC7E,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAK3D"}

package/dist/severity.js

@@ -0,0 +1,16 @@
+// Severity band derivation. `scores.severity` (integer 1-5) is the single
+// source of truth for impact (cli-v1.md "Severity — single source of truth").
+// The categorical band is *dropped from the schema* and derived wherever a
+// label is needed: 5 -> critical, 4 -> high, 3 -> medium, 1-2 -> low.
+export const SEVERITY_BANDS = ["critical", "high", "medium", "low"];
+/** Derive the categorical band from the 1-5 FMEA severity score. */
+export function severityBand(severity) {
+    if (severity >= 5)
+        return "critical";
+    if (severity === 4)
+        return "high";
+    if (severity === 3)
+        return "medium";
+    return "low";
+}
+//# sourceMappingURL=severity.js.map

package/dist/severity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.js","sourceRoot":"","sources":["../src/severity.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,2EAA2E;AAC3E,sEAAsE;AAEtE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAU,CAAC;AAG7E,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IACrC,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACpC,OAAO,KAAK,CAAC;AACf,CAAC"}