comisai 1.0.42 → 1.0.45

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-signals-fields.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Field readers + redaction helpers for `toIncidentSignals`
+ * (`obs-explain-signals.ts`).
+ *
+ * Defensive reads (every on-disk record is `Record<string, unknown>`) plus the
+ * two depth-independent SECURITY projections the normalizer relies on:
+ *   - `relativizeDiskPath` — an absolute host path (`/Users/…/.comis/…`) is
+ *     collapsed to the workspace-relative tail; the absolute path is never
+ *     emitted.
+ *   - `previewAndDigest` — `errorPreview` is a bounded, credential-redacted
+ *     HEAD slice; the full body is captured only as `resultDigest`. A wrapped
+ *     EXTERNAL/untrusted body (whose HEAD carries a prompt-injection marker) is
+ *     collapsed WHOLESALE to a digest reference.
+ *
+ * @module
+ */
+import type { IncidentSignals } from "@comis/core";
+import { type IncidentVoiceSignal } from "./obs-explain-voice-fold.js";
+export type { IncidentVoiceSignal } from "./obs-explain-voice-fold.js";
+/** The reconstructed image-generation turn (the non-optional shape of
+ *  `IncidentSignals["image"]`). */
+export type IncidentImageSignal = NonNullable<IncidentSignals["image"]>;
+/** VIS-04 (187): the reconstructed vision turn (the non-optional shape of
+ *  `IncidentSignals["vision"]`). */
+export type IncidentVisionSignal = NonNullable<IncidentSignals["vision"]>;
+/** OBS-04 (192): the reconstructed video-generation turn (the non-optional
+ *  shape of `IncidentSignals["videoGenerated"]`). */
+export type IncidentVideoSignal = NonNullable<IncidentSignals["videoGenerated"]>;
+export declare function asString(v: unknown): string | undefined;
+export declare function asNumber(v: unknown): number | undefined;
+/** Keep only string entries of an array payload field (non-array → empty).
+ * Defensive read for record fields that cross the provider/MCP-influenced
+ * trust boundary into admin-facing verdict text (T-175-17). */
+export declare function asStringArray(v: unknown): string[];
+/**
+ * Relativize an offload disk path so the absolute host path is never emitted.
+ * Absolute host paths (`/Users/…/.comis/…`) collapse to the tail after the
+ * last `.comis/`; already-relative pointers pass through; an unrecognizable
+ * absolute path collapses to a `<offloaded>` placeholder.
+ */
+export declare function relativizeDiskPath(diskPath: string | undefined): string;
+/** Build a redaction-safe, bounded preview + a digest of the full body. */
+export declare function previewAndDigest(errorText: string | undefined): {
+    errorPreview: string;
+    resultDigest: string;
+    resultBytes: number;
+};
+/** The seq-aware fold state: the reconstructed image turn + the `seq` of the
+ *  record that last SET `outcome` (the terminal record). IN-04 (186): the fold
+ *  is driven by the record stream's `seq`, NOT array order, so only a record
+ *  with a `seq` ≥ the last outcome-setting record can overwrite `outcome`. */
+export interface ImageFoldState {
+    signal: IncidentImageSignal | undefined;
+    /** The seq at which `outcome` was last set (a terminal generated/failed). */
+    outcomeSeq: number;
+}
+/**
+ * OBS-03/OBS-04 (186): fold one `image.*` trajectory record into the
+ * reconstructed image-generation turn (extracted from `toIncidentSignals` to
+ * keep that module ≤500). Pure: takes the prior fold state + the record's
+ * `type`/`data`/`seq` and returns the new state. The terminal `image.generated`
+ * / `image.failed` record sets `outcome` (+ cost/model on success, errorKind on
+ * failure — the cost rides image.generated, Route a); `image.delivered` flips
+ * `delivered`; `image.requested` seeds a conservative `outcome:"failed"` block
+ * so a turn aborting before a terminal record still surfaces. Returns `prev`
+ * unchanged for a non-image type. Content-free reads (ids/labels/numbers only).
+ *
+ * IN-04 (186): the fold is SEQ-AWARE — a terminal `image.generated`/`image.failed`
+ * only overwrites `outcome` when its `seq` is ≥ the seq of the last
+ * outcome-setting record. Today the handler always emits in lifecycle order and
+ * the recorder appends in emit order (file order == lifecycle order), so this is
+ * a robustness guard against any future reordering: a lower-seq transient
+ * `image.failed` arriving after a higher-seq terminal `image.generated` no longer
+ * flips a delivered success to failed. `image.requested` (the seed) does not set
+ * `outcomeSeq`, so the first real terminal record always wins.
+ */
+export declare function accumulateImageRecord(prev: ImageFoldState, type: string, data: Record<string, unknown>, seq: number): ImageFoldState;
+/** VIS-04 (187): the seq-aware fold state for the reconstructed vision turn +
+ *  the `seq` of the record that last SET `outcome` (the terminal record).
+ *  Mirrors `ImageFoldState` (IN-04): the fold is driven by the record stream's
+ *  `seq`, NOT array order, so only a record with a `seq` ≥ the last
+ *  outcome-setting record can overwrite `outcome`. */
+export interface VisionFoldState {
+    signal: IncidentVisionSignal | undefined;
+    /** The seq at which `outcome` was last set (a terminal completed/failed). */
+    outcomeSeq: number;
+}
+/**
+ * VIS-04 (187): fold one `media.vision.*` trajectory record into the
+ * reconstructed vision turn (the analog of `accumulateImageRecord`, in this
+ * helper to keep `obs-explain-signals.ts` ≤500). Pure: takes the prior fold
+ * state + the record's `type`/`data`/`seq` and returns the new state. The
+ * terminal `media.vision.completed` / `media.vision.failed` record sets
+ * `outcome` (+ mainProvider/model/costUsd/path on success — the cost rides
+ * completed, Route a; errorKind/path on failure); `media.vision.requested` seeds
+ * a conservative `outcome:"failed"` block so a turn aborting before a terminal
+ * record still surfaces an honest failed vision block. Returns `prev` unchanged
+ * for a non-vision type. Content-free reads (asString/asNumber — ids/labels/
+ * numbers/path only; never an image byte, prompt, or answer; T-187-12).
+ *
+ * SEQ-AWARE (IN-04): a terminal completed/failed only overwrites `outcome` when
+ * its `seq` is ≥ the seq of the last outcome-setting record — a stale lower-seq
+ * `media.vision.failed` arriving after a higher-seq `media.vision.completed` no
+ * longer flips an ok turn to failed. `media.vision.requested` (the seed) does
+ * not set `outcomeSeq`, so the first real terminal record always wins.
+ */
+export declare function accumulateVisionRecord(prev: VisionFoldState, type: string, data: Record<string, unknown>, seq: number): VisionFoldState;
+/** OBS-04 (192): the seq-aware fold state for the reconstructed video turn +
+ *  the `seq` of the record that last SET `outcome` (the terminal record).
+ *  Mirrors `VisionFoldState`/`ImageFoldState` (IN-04): the fold is driven by the
+ *  record stream's `seq`, NOT array order, so only a record with a `seq` ≥ the
+ *  last outcome-setting record can overwrite `outcome`. */
+export interface VideoFoldState {
+    signal: IncidentVideoSignal | undefined;
+    /** The seq at which `outcome` was last set (a terminal generated/failed). */
+    outcomeSeq: number;
+}
+/**
+ * OBS-04 (192): fold one `video.*` trajectory record into the reconstructed
+ * video-generation turn (the analog of `accumulateVisionRecord`, in this helper
+ * to keep `obs-explain-signals.ts` ≤500). Pure: takes the prior fold state + the
+ * record's `type`/`data`/`seq` and returns the new state. The terminal
+ * `video.generated` / `video.failed` record sets `outcome` (+ model/costUsd/
+ * estimatedCostUsd/durationSecs on success — the cost rides generated, Route a;
+ * errorKind on failure); `video.delivered` flips the `delivered` latch (the
+ * `image.delivered` precedent); `video.requested` seeds a conservative
+ * `outcome:"failed"` block (so a turn aborting before a terminal still surfaces)
+ * and `video.submitted` adds the `jobId` (the OBS-04 stitch handle). Returns
+ * `prev` unchanged for a non-video type. Content-free reads (asString/asNumber —
+ * ids/labels/numbers only; never the prompt, the bytes, or a provider message;
+ * T-192-06). `sizeBytes` rides the LOG/event but NOT the report block (only
+ * durationSecs/cost/model — matching the `videoGenerated` Zod).
+ *
+ * SEQ-AWARE (IN-04): a terminal generated/failed only overwrites `outcome` when
+ * its `seq` is ≥ the seq of the last outcome-setting record — a stale lower-seq
+ * record arriving after a higher-seq terminal no longer flips the outcome. The
+ * `video.requested`/`video.submitted` seeds do not set `outcomeSeq`, so the
+ * first real terminal record always wins (background-completion: the off-turn
+ * `video.generated` arrives at a HIGHER seq than the in-turn `video.submitted`).
+ */
+export declare function accumulateVideoRecord(prev: VideoFoldState, type: string, data: Record<string, unknown>, seq: number): VideoFoldState;
+/** The mutable media-fold slice the record normalizer (`toIncidentSignals`)
+ *  carries — the four seq-aware folds (`image.*` 186, `media.vision.*` 187,
+ *  `video.*` 192, `media.stt.*`/`media.tts.*` 196) + their outcome-seqs + the
+ *  running seq counter. Structurally a subset of `Acc`; typed here so
+ *  `applyMediaRecord` owns ALL switch-case groups and keeps
+ *  `obs-explain-signals.ts` ≤500 (extraction, NOT an allowlist bump). */
+export interface MediaFoldSlice {
+    image?: IncidentImageSignal;
+    imageOutcomeSeq: number;
+    vision?: IncidentVisionSignal;
+    visionOutcomeSeq: number;
+    video?: IncidentVideoSignal;
+    videoOutcomeSeq: number;
+    voice?: IncidentVoiceSignal;
+    voiceOutcomeSeq: number;
+    /** The running monotonic seq counter (for records lacking an explicit seq). */
+    seq: number;
+}
+/**
+ * VIS-04 / OBS-04 / OBS-02: if `type` is an `image.*`, `media.vision.*`,
+ * `video.*`, or `media.stt.*`/`media.tts.*` lifecycle record, fold it into
+ * `slice` (mutating the matching signal + outcomeSeq) and return `true`; otherwise
+ * return `false` (the normalizer falls through to its other cases). Drives each
+ * fold by the record's `seq` (IN-04 — not array order; records lacking a seq fall
+ * back to the running counter, monotonic by arrival). Extracted from
+ * `toIncidentSignals` so the four record classes share one dispatcher (their case
+ * bodies were byte-identical boilerplate) — and so the `video.*`/`media.stt.*`/
+ * `media.tts.*` arms live HERE, keeping `obs-explain-signals.ts` ≤500 (the
+ * WARNING-1 file-size budget).
+ */
+export declare function applyMediaRecord(slice: MediaFoldSlice, type: string, data: Record<string, unknown>, recSeq: number): boolean;

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-signals-fields.js

@@ -0,0 +1,373 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Field readers + redaction helpers for `toIncidentSignals`
+ * (`obs-explain-signals.ts`).
+ *
+ * Defensive reads (every on-disk record is `Record<string, unknown>`) plus the
+ * two depth-independent SECURITY projections the normalizer relies on:
+ *   - `relativizeDiskPath` — an absolute host path (`/Users/…/.comis/…`) is
+ *     collapsed to the workspace-relative tail; the absolute path is never
+ *     emitted.
+ *   - `previewAndDigest` — `errorPreview` is a bounded, credential-redacted
+ *     HEAD slice; the full body is captured only as `resultDigest`. A wrapped
+ *     EXTERNAL/untrusted body (whose HEAD carries a prompt-injection marker) is
+ *     collapsed WHOLESALE to a digest reference.
+ *
+ * @module
+ */
+import { fingerprint, sanitizeLogString } from "@comis/core";
+// OBS-02 (196): the voice fold lives in a sibling (the obs-handlers/* 500-line cap);
+// applyMediaRecord dispatches the media.stt.*/media.tts.* arms to it.
+import { accumulateVoiceRecord } from "./obs-explain-voice-fold.js";
+/** Hard cap on every `errorPreview` — the long body is never carried whole. */
+const MAX_ERROR_PREVIEW = 200;
+/** Perf bound: never scan more than 2 KB to produce a ≤200-char preview
+ * (sanitizeLogString self-bounds ReDoS at its own 1 MB cap). Slicing the body
+ * before sanitize avoids running the credential-regex over a 50 KB body just to
+ * keep 200 chars. Generous vs. MAX_ERROR_PREVIEW so the sanitizer still sees
+ * enough context to redact. */
+const RAW_BODY_SCAN_BOUND = 2_000;
+/**
+ * Markers that identify an EXTERNAL, UNTRUSTED tool body (the `wrapExternalContent`
+ * envelope Comis prepends to web/email/webhook content, which carries a
+ * prompt-injection block). When a failure body is wrapped untrusted content, even
+ * a 200-char HEAD slice begins with this marker — so the length cap alone leaks
+ * the injection header. The preview of such a body is collapsed WHOLESALE to a
+ * digest reference; the full body stays addressable via `resultDigest`
+ * (T-153-14, depth-independent — the consumer never sees the marker or its
+ * directives). Matched on the bounded slice (post-cap), never the raw body.
+ */
+const UNTRUSTED_CONTENT_MARKER_RE = /SECURITY NOTICE|UNTRUSTED source/i;
+export function asString(v) {
+    return typeof v === "string" ? v : undefined;
+}
+export function asNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+/** Keep only string entries of an array payload field (non-array → empty).
+ * Defensive read for record fields that cross the provider/MCP-influenced
+ * trust boundary into admin-facing verdict text (T-175-17). */
+export function asStringArray(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+/**
+ * Relativize an offload disk path so the absolute host path is never emitted.
+ * Absolute host paths (`/Users/…/.comis/…`) collapse to the tail after the
+ * last `.comis/`; already-relative pointers pass through; an unrecognizable
+ * absolute path collapses to a `<offloaded>` placeholder.
+ */
+export function relativizeDiskPath(diskPath) {
+    if (diskPath === undefined || diskPath.length === 0)
+        return "<offloaded>";
+    const marker = ".comis/";
+    const idx = diskPath.lastIndexOf(marker);
+    if (idx >= 0)
+        return diskPath.slice(idx + marker.length);
+    // Already-relative pointer (no leading slash) is safe to keep verbatim.
+    if (!diskPath.startsWith("/"))
+        return diskPath;
+    // Absolute path that does not pass through .comis/ — never emit it whole.
+    return "<offloaded>";
+}
+/** Build a redaction-safe, bounded preview + a digest of the full body. */
+export function previewAndDigest(errorText) {
+    const body = errorText ?? "";
+    const resultBytes = Buffer.byteLength(body, "utf8");
+    const resultDigest = fingerprint(body);
+    // Pre-bound BEFORE sanitize (ReDoS guard on oversized bodies), then redact,
+    // then hard-cap at MAX_ERROR_PREVIEW. The full body lives only in the digest.
+    const capped = sanitizeLogString(body.slice(0, RAW_BODY_SCAN_BOUND)).slice(0, MAX_ERROR_PREVIEW);
+    // Untrusted-content guard (T-153-14): a wrapped EXTERNAL body leads with the
+    // "SECURITY NOTICE" injection marker, so the HEAD slice would inline it.
+    // Collapse the preview to a digest reference — the body is still addressable
+    // via resultDigest. Depth-independent (this runs before any depth bounding).
+    const errorPreview = UNTRUSTED_CONTENT_MARKER_RE.test(capped)
+        ? "[redacted:untrusted-content digest:" + resultDigest + "]"
+        : capped;
+    return { errorPreview, resultDigest, resultBytes };
+}
+/**
+ * OBS-03/OBS-04 (186): fold one `image.*` trajectory record into the
+ * reconstructed image-generation turn (extracted from `toIncidentSignals` to
+ * keep that module ≤500). Pure: takes the prior fold state + the record's
+ * `type`/`data`/`seq` and returns the new state. The terminal `image.generated`
+ * / `image.failed` record sets `outcome` (+ cost/model on success, errorKind on
+ * failure — the cost rides image.generated, Route a); `image.delivered` flips
+ * `delivered`; `image.requested` seeds a conservative `outcome:"failed"` block
+ * so a turn aborting before a terminal record still surfaces. Returns `prev`
+ * unchanged for a non-image type. Content-free reads (ids/labels/numbers only).
+ *
+ * IN-04 (186): the fold is SEQ-AWARE — a terminal `image.generated`/`image.failed`
+ * only overwrites `outcome` when its `seq` is ≥ the seq of the last
+ * outcome-setting record. Today the handler always emits in lifecycle order and
+ * the recorder appends in emit order (file order == lifecycle order), so this is
+ * a robustness guard against any future reordering: a lower-seq transient
+ * `image.failed` arriving after a higher-seq terminal `image.generated` no longer
+ * flips a delivered success to failed. `image.requested` (the seed) does not set
+ * `outcomeSeq`, so the first real terminal record always wins.
+ */
+export function accumulateImageRecord(prev, type, data, seq) {
+    const signal = prev.signal;
+    switch (type) {
+        case "image.requested": {
+            const provider = asString(data.provider);
+            const next = signal ?? { provider: provider ?? "", outcome: "failed", delivered: false };
+            if (provider !== undefined && next.provider.length === 0)
+                next.provider = provider;
+            return { signal: next, outcomeSeq: prev.outcomeSeq };
+        }
+        case "image.generated": {
+            // Seq-aware terminal: a stale (lower-seq) record never overwrites a newer
+            // outcome. The carried `delivered` is preserved regardless of seq (it is a
+            // monotonic latch set by image.delivered, not a terminal outcome).
+            if (signal !== undefined && seq < prev.outcomeSeq)
+                return prev;
+            return {
+                signal: {
+                    provider: asString(data.provider) ?? signal?.provider ?? "",
+                    outcome: "ok",
+                    delivered: signal?.delivered ?? false,
+                    ...(asString(data.model) !== undefined ? { model: asString(data.model) } : {}),
+                    ...(asNumber(data.costUsd) !== undefined ? { costUsd: asNumber(data.costUsd) } : {}),
+                    // WR-02 (186): carry the degraded-delivery flag (false on a persist-
+                    // failed but base64-delivered generation — still a charged outcome:"ok").
+                    ...(typeof data.persisted === "boolean" ? { persisted: data.persisted } : {}),
+                },
+                outcomeSeq: seq,
+            };
+        }
+        case "image.delivered": {
+            const next = signal ?? { provider: "", outcome: "ok", delivered: false };
+            next.delivered = data.delivered === true;
+            return { signal: next, outcomeSeq: prev.outcomeSeq };
+        }
+        case "image.failed": {
+            if (signal !== undefined && seq < prev.outcomeSeq)
+                return prev;
+            const errorKind = asString(data.errorKind);
+            return {
+                signal: {
+                    provider: asString(data.provider) ?? signal?.provider ?? "",
+                    outcome: "failed",
+                    delivered: signal?.delivered ?? false,
+                    ...(errorKind !== undefined ? { errorKind } : {}),
+                },
+                outcomeSeq: seq,
+            };
+        }
+        default:
+            return prev;
+    }
+}
+/**
+ * VIS-04 (187): fold one `media.vision.*` trajectory record into the
+ * reconstructed vision turn (the analog of `accumulateImageRecord`, in this
+ * helper to keep `obs-explain-signals.ts` ≤500). Pure: takes the prior fold
+ * state + the record's `type`/`data`/`seq` and returns the new state. The
+ * terminal `media.vision.completed` / `media.vision.failed` record sets
+ * `outcome` (+ mainProvider/model/costUsd/path on success — the cost rides
+ * completed, Route a; errorKind/path on failure); `media.vision.requested` seeds
+ * a conservative `outcome:"failed"` block so a turn aborting before a terminal
+ * record still surfaces an honest failed vision block. Returns `prev` unchanged
+ * for a non-vision type. Content-free reads (asString/asNumber — ids/labels/
+ * numbers/path only; never an image byte, prompt, or answer; T-187-12).
+ *
+ * SEQ-AWARE (IN-04): a terminal completed/failed only overwrites `outcome` when
+ * its `seq` is ≥ the seq of the last outcome-setting record — a stale lower-seq
+ * `media.vision.failed` arriving after a higher-seq `media.vision.completed` no
+ * longer flips an ok turn to failed. `media.vision.requested` (the seed) does
+ * not set `outcomeSeq`, so the first real terminal record always wins.
+ */
+export function accumulateVisionRecord(prev, type, data, seq) {
+    const signal = prev.signal;
+    switch (type) {
+        case "media.vision.requested": {
+            const provider = asString(data.provider);
+            const next = signal ?? { provider: provider ?? "", outcome: "failed" };
+            if (provider !== undefined && next.provider.length === 0)
+                next.provider = provider;
+            return { signal: next, outcomeSeq: prev.outcomeSeq };
+        }
+        case "media.vision.completed": {
+            // Seq-aware terminal: a stale (lower-seq) record never overwrites a newer
+            // outcome.
+            if (signal !== undefined && seq < prev.outcomeSeq)
+                return prev;
+            const mainProvider = asString(data.mainProvider);
+            const model = asString(data.model);
+            const costUsd = asNumber(data.costUsd);
+            const path = asString(data.path);
+            return {
+                signal: {
+                    provider: asString(data.provider) ?? signal?.provider ?? "",
+                    outcome: "ok",
+                    ...(mainProvider !== undefined ? { mainProvider } : {}),
+                    ...(model !== undefined ? { model } : {}),
+                    ...(costUsd !== undefined ? { costUsd } : {}),
+                    ...(path !== undefined ? { path: path } : {}),
+                },
+                outcomeSeq: seq,
+            };
+        }
+        case "media.vision.failed": {
+            if (signal !== undefined && seq < prev.outcomeSeq)
+                return prev;
+            const mainProvider = asString(data.mainProvider);
+            const errorKind = asString(data.errorKind);
+            const path = asString(data.path);
+            return {
+                signal: {
+                    provider: asString(data.provider) ?? signal?.provider ?? "",
+                    outcome: "failed",
+                    ...(mainProvider !== undefined ? { mainProvider } : {}),
+                    ...(errorKind !== undefined ? { errorKind } : {}),
+                    ...(path !== undefined ? { path: path } : {}),
+                },
+                outcomeSeq: seq,
+            };
+        }
+        default:
+            return prev;
+    }
+}
+/**
+ * OBS-04 (192): fold one `video.*` trajectory record into the reconstructed
+ * video-generation turn (the analog of `accumulateVisionRecord`, in this helper
+ * to keep `obs-explain-signals.ts` ≤500). Pure: takes the prior fold state + the
+ * record's `type`/`data`/`seq` and returns the new state. The terminal
+ * `video.generated` / `video.failed` record sets `outcome` (+ model/costUsd/
+ * estimatedCostUsd/durationSecs on success — the cost rides generated, Route a;
+ * errorKind on failure); `video.delivered` flips the `delivered` latch (the
+ * `image.delivered` precedent); `video.requested` seeds a conservative
+ * `outcome:"failed"` block (so a turn aborting before a terminal still surfaces)
+ * and `video.submitted` adds the `jobId` (the OBS-04 stitch handle). Returns
+ * `prev` unchanged for a non-video type. Content-free reads (asString/asNumber —
+ * ids/labels/numbers only; never the prompt, the bytes, or a provider message;
+ * T-192-06). `sizeBytes` rides the LOG/event but NOT the report block (only
+ * durationSecs/cost/model — matching the `videoGenerated` Zod).
+ *
+ * SEQ-AWARE (IN-04): a terminal generated/failed only overwrites `outcome` when
+ * its `seq` is ≥ the seq of the last outcome-setting record — a stale lower-seq
+ * record arriving after a higher-seq terminal no longer flips the outcome. The
+ * `video.requested`/`video.submitted` seeds do not set `outcomeSeq`, so the
+ * first real terminal record always wins (background-completion: the off-turn
+ * `video.generated` arrives at a HIGHER seq than the in-turn `video.submitted`).
+ */
+export function accumulateVideoRecord(prev, type, data, seq) {
+    const signal = prev.signal;
+    switch (type) {
+        case "video.requested":
+        case "video.submitted": {
+            const provider = asString(data.provider);
+            const jobId = asString(data.jobId);
+            const next = signal ?? { provider: provider ?? "", outcome: "failed", delivered: false };
+            if (provider !== undefined && next.provider.length === 0)
+                next.provider = provider;
+            if (jobId !== undefined)
+                next.jobId = jobId;
+            return { signal: next, outcomeSeq: prev.outcomeSeq };
+        }
+        case "video.generated": {
+            // Seq-aware terminal: a stale (lower-seq) record never overwrites a newer
+            // outcome. The carried `delivered`/`jobId` are preserved regardless of seq
+            // (delivered is a monotonic latch; jobId ties the off-turn completion back).
+            if (signal !== undefined && seq < prev.outcomeSeq)
+                return prev;
+            const model = asString(data.model);
+            const costUsd = asNumber(data.costUsd);
+            const estimatedCostUsd = asNumber(data.estimatedCostUsd);
+            const durationSecs = asNumber(data.durationSecs);
+            return {
+                signal: {
+                    provider: asString(data.provider) ?? signal?.provider ?? "",
+                    outcome: "ok",
+                    delivered: signal?.delivered ?? false,
+                    ...(signal?.jobId !== undefined ? { jobId: signal.jobId } : {}),
+                    ...(model !== undefined ? { model } : {}),
+                    ...(costUsd !== undefined ? { costUsd } : {}),
+                    ...(estimatedCostUsd !== undefined ? { estimatedCostUsd } : {}),
+                    ...(durationSecs !== undefined ? { durationSecs } : {}),
+                },
+                outcomeSeq: seq,
+            };
+        }
+        case "video.delivered": {
+            const next = signal ?? { provider: "", outcome: "ok", delivered: false };
+            next.delivered = data.delivered === true;
+            return { signal: next, outcomeSeq: prev.outcomeSeq };
+        }
+        case "video.failed": {
+            if (signal !== undefined && seq < prev.outcomeSeq)
+                return prev;
+            const errorKind = asString(data.errorKind);
+            return {
+                signal: {
+                    provider: asString(data.provider) ?? signal?.provider ?? "",
+                    outcome: "failed",
+                    delivered: signal?.delivered ?? false,
+                    ...(signal?.jobId !== undefined ? { jobId: signal.jobId } : {}),
+                    ...(errorKind !== undefined ? { errorKind } : {}),
+                },
+                outcomeSeq: seq,
+            };
+        }
+        default:
+            return prev;
+    }
+}
+/**
+ * VIS-04 / OBS-04 / OBS-02: if `type` is an `image.*`, `media.vision.*`,
+ * `video.*`, or `media.stt.*`/`media.tts.*` lifecycle record, fold it into
+ * `slice` (mutating the matching signal + outcomeSeq) and return `true`; otherwise
+ * return `false` (the normalizer falls through to its other cases). Drives each
+ * fold by the record's `seq` (IN-04 — not array order; records lacking a seq fall
+ * back to the running counter, monotonic by arrival). Extracted from
+ * `toIncidentSignals` so the four record classes share one dispatcher (their case
+ * bodies were byte-identical boilerplate) — and so the `video.*`/`media.stt.*`/
+ * `media.tts.*` arms live HERE, keeping `obs-explain-signals.ts` ≤500 (the
+ * WARNING-1 file-size budget).
+ */
+export function applyMediaRecord(slice, type, data, recSeq) {
+    switch (type) {
+        case "image.requested":
+        case "image.generated":
+        case "image.delivered":
+        case "image.failed": {
+            const folded = accumulateImageRecord({ signal: slice.image, outcomeSeq: slice.imageOutcomeSeq }, type, data, recSeq);
+            slice.image = folded.signal;
+            slice.imageOutcomeSeq = folded.outcomeSeq;
+            return true;
+        }
+        case "media.vision.requested":
+        case "media.vision.completed":
+        case "media.vision.failed": {
+            const folded = accumulateVisionRecord({ signal: slice.vision, outcomeSeq: slice.visionOutcomeSeq }, type, data, recSeq);
+            slice.vision = folded.signal;
+            slice.visionOutcomeSeq = folded.outcomeSeq;
+            return true;
+        }
+        case "video.requested":
+        case "video.submitted":
+        case "video.generated":
+        case "video.delivered":
+        case "video.failed": {
+            const folded = accumulateVideoRecord({ signal: slice.video, outcomeSeq: slice.videoOutcomeSeq }, type, data, recSeq);
+            slice.video = folded.signal;
+            slice.videoOutcomeSeq = folded.outcomeSeq;
+            return true;
+        }
+        case "media.stt.requested":
+        case "media.stt.completed":
+        case "media.stt.failed":
+        case "media.tts.requested":
+        case "media.tts.completed":
+        case "media.tts.failed": {
+            const folded = accumulateVoiceRecord({ signal: slice.voice, outcomeSeq: slice.voiceOutcomeSeq }, type, data, recSeq);
+            slice.voice = folded.signal;
+            slice.voiceOutcomeSeq = folded.outcomeSeq;
+            return true;
+        }
+        default:
+            return false;
+    }
+}

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-signals.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `toIncidentSignals` — the X3 dual-shape normalizer.
+ *
+ * Collapses two on-disk telemetry record shapes into one `IncidentSignals` view
+ * the assembler (Plan 03) + heuristic registry (Plan 05) consume: the LOG shape
+ * (raw Pino lines, PRE Phase-150 — no `traceSchema`, keyed on `msg`, detail from
+ * `errorText`/`httpStatus`/`errorKind`) and the EVENT shape (structured
+ * trajectory events, POST Phase-151 — `traceSchema:"comis-trajectory"`, keyed on
+ * `type`, detail from `data`).
+ *
+ * SECURITY (depth-independent): raw bodies are NEVER inlined — `errorPreview` is
+ * the ReDoS-pre-bounded `sanitizeLogString(...).slice(0, MAX_ERROR_PREVIEW)` and
+ * the full body is captured only by `resultDigest = fingerprint(...)`; an offload
+ * `diskPath` is relativized (the absolute host path is never emitted). The 678
+ * misclassification signal derives from LOG EVIDENCE ONLY (zero
+ * `classifiedFailureBy` reads — the field is absent in that fixture).
+ *
+ * @module
+ */
+import type { IncidentSignals } from "@comis/core";
+/** Minimum same-tool failures for a breaker/repeated-failure signal. Used by
+ * the heuristic registry (Plan 05); surfaced here for one source of truth. */
+export declare const BREAKER_N = 5;
+/**
+ * Normalize a heterogeneous record stream (raw log lines AND/OR structured
+ * trajectory events) into one `IncidentSignals` view.
+ *
+ * The 678 `hasMisclassificationSignal` derivation uses log evidence only:
+ * a tool with BOTH ≥1 success and ≥`MISCLASS_N` failures whose failure body
+ * carried a status/200/403 token. No `classifiedFailureBy` is consulted.
+ */
+export declare function toIncidentSignals(records: Array<Record<string, unknown>>): IncidentSignals;