@oscharko-dev/keiko 0.2.0-beta.4 → 0.2.0-beta.6

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runIngestion.js

@@ -5,10 +5,11 @@
 // `@oscharko-dev/keiko-quality-intelligence`. The server tier owns IO (it is the only layer that
 // may touch the filesystem); the pure domain owns splitting + hashing. Oversize and unsupported
 // inputs fail with user-actionable errors (#278 AC) before any model prompt is built.
+import { realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
 import { redact, sha256Hex } from "@oscharko-dev/keiko-security";
-import { QualityIntelligenceGeneration, QualityIntelligenceHardening, QualityIntelligenceFigma, } from "@oscharko-dev/keiko-quality-intelligence";
+import { QualityIntelligenceGeneration, QualityIntelligenceHardening, QualityIntelligenceFigma, isUnsafeFormatCodePoint, stripUnsafeFormatChars, } from "@oscharko-dev/keiko-quality-intelligence";
 import { detectWorkspaceAt, discoverWithStats, buildContextPackFromFiles, readWorkspaceFile, isDenied, DEFAULT_CONTEXT_REQUEST, DEFAULT_READ_OPTIONS, WorkspaceError, FileTooLargeError, PathDeniedError, PathEscapeError, WorkspaceReadError, } from "@oscharko-dev/keiko-workspace";
 const MAX_TOTAL_ATOMS = 120;
 const MAX_LABEL_CHARS = 120;
@@ -35,6 +36,9 @@ function perSourceAtomBudget(total, sourceCount) {
 const EVIDENCE_BUDGET_BYTES = 196_608;
 // Never starve a source below this many bytes — a tiny share is still usable context.
 const MIN_SOURCE_BUDGET_BYTES = 4_096;
+// Bound productive vision calls for one Figma snapshot source. The deterministic structural
+// baseline still covers every parseable screen; vision hints are additive and sampled first-in-order.
+const MAX_FIGMA_VISION_AUGMENTED_SCREENS = 12;
 /**
  * Fair per-source UTF-8 byte budget — the byte analogue of {@link perSourceAtomBudget}. Floor-divides
  * the global evidence byte pool across sources (Chat byte-split parity) with a non-zero floor so the
@@ -66,6 +70,34 @@ const CREDENTIAL_LABEL_SHAPES = [
     /\bBearer\s+\S+/giu,
     /-----BEGIN [A-Z ]*PRIVATE KEY-----/gu,
 ];
+// Make a source label single-line AND spoof-safe with one code-point scan (the `no-control-regex`
+// lint rule forbids a control-range regex literal, and a scan is the established in-package idiom —
+// mirrors generationPort.scrubEvidenceText):
+//   - C0 controls (incl. tab/newline/CR) and DEL become a SPACE, so a multi-line or control-laden
+//     label can never glue a second line of content into the streamed displayLabel (#277/#278).
+//   - Bidi overrides/isolates, zero-width/BOM, LRM/RLM, the Arabic letter mark, and C1 controls are
+//     DROPPED outright. These are invisible or reorder surrounding text, so a source filename /
+//     capsule id cannot smuggle a right-to-left or zero-width spoof into the browser-streamed
+//     envelope display surface. The drop set is the SHARED `isUnsafeFormatCodePoint` predicate used
+//     by the candidate-text scrubber (keiko-quality-intelligence stripUnsafeFormatChars), so the
+//     source-label path is symmetric with the persisted/exported candidate-text path (Epic #729;
+//     the bidi/zero-width display-hygiene class of #280/#284). C0/DEL are handled first (→ space)
+//     because a single-line label spaces line breaks rather than gluing them.
+function stripUnsafeLabelChars(value) {
+    let out = "";
+    for (const ch of value) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (cp <= 0x1f || cp === 0x7f) {
+            out += " ";
+            continue;
+        }
+        if (isUnsafeFormatCodePoint(cp)) {
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
 const sanitiseLabel = (label) => {
     // Strip any URL authority — ANY scheme (http, file, s3, ftp, …), not just http(s) — plus the
     // well-known credential token shapes, so a browser-supplied label never carries a URL or secret
@@ -73,6 +105,15 @@ const sanitiseLabel = (label) => {
     let cleaned = label.replace(/[a-z][a-z0-9+.-]*:\/\/\S+/giu, " ");
     for (const shape of CREDENTIAL_LABEL_SHAPES)
         cleaned = cleaned.replace(shape, " ");
+    // Map control characters (newline, CR, tab, NUL, DEL, …) to spaces and DROP bidi-override,
+    // zero-width, BOM, and C1 spoofing code points so a multi-line, control-laden, or
+    // visually-reordered label can never carry a second line of content into — or spoof the reading
+    // order of — the browser-streamed envelope displayLabel. Without the control→space step the
+    // absolute-path basename-collapse below (which splits on "/" only) would keep a trailing
+    // "\n<more content>" glued inside the final path segment, defeating the basename defence; without
+    // the bidi/zero-width drop a crafted filename could reorder the displayed label (#277/#278
+    // envelope display-surface invariant; Epic #729 symmetry with the candidate-text scrubber).
+    cleaned = stripUnsafeLabelChars(cleaned);
     cleaned = cleaned.trim();
     // Collapse an absolute POSIX / Windows-drive / UNC path label to its final segment so the
     // display label never leaks the filesystem layout (the basename is the useful display token).
@@ -86,13 +127,45 @@ const sanitiseLabel = (label) => {
 // Reject a source whose absolute path (any segment) names a denied credential location. isDenied
 // inspects EVERY path segment, so a denied ancestor cannot be hidden by rooting a read deeper. Shared
 // by the folder and single-file paths so both honour the same containment guard (Epic #729 security).
+// Also rejects the symlink variant (assertRealPathNotDenied) so a benign-named link cannot resolve
+// into a protected location.
 function assertNotDenied(absPath, label, noun) {
     if (isDenied(absPath)) {
         throw new QiIngestionError("QI_SOURCE_DENIED", `${noun} "${label}" is in a protected location.`);
     }
+    assertRealPathNotDenied(absPath, label, noun);
+}
+// Defense-in-depth against a symlinked workspace root. The keiko-workspace deny gate (readWorkspaceFile)
+// inspects only the path RELATIVE to the realpath'd root, so a denied segment AT or ABOVE the connected
+// root is invisible to it: a benign-named "~/docs" symlink whose real target is "~/.aws" lets a
+// supported file inside it read through to the model, even though the lexical assertNotDenied above sees
+// only "docs". Re-running the deny gate over the REAL (symlink-resolved) absolute path rejects it. The
+// lexical check above already covers the no-symlink case, so this only ADDS denials when realpath
+// diverges into a protected location; a non-existent target surfaces later as NOT_FOUND, so a failed
+// realpath is a deliberate no-op here. (#713 single-file security review: "deny-list still applies";
+// #729 folder-root parity — both ingest paths share this boundary blind spot.)
+function assertRealPathNotDenied(absPath, label, noun) {
+    let realPath;
+    try {
+        realPath = realpathSync(absPath);
+    }
+    catch {
+        return;
+    }
+    if (realPath !== absPath && isDenied(realPath)) {
+        throw new QiIngestionError("QI_SOURCE_DENIED", `${noun} "${label}" is in a protected location.`);
+    }
 }
-const envelopeIdFor = (index, label, content) => {
-    const digest = sha256Hex(`qi-src-v1|${String(index)}|${label}|${content}`).slice(0, 24);
+// Escape the field delimiter ("|") and the escape character ("\") in each user/path-controlled
+// field so a label or content value can never inject a raw delimiter and forge another source's
+// envelope id. The strictly-increasing loop index already disambiguates sources today; escaping
+// makes the pre-image injective on its own — robust even if the fields were ever reordered —
+// closing the latent cross-source provenance-spoofing surface flagged by the #732 composition
+// security audit. A value with no "\" or "|" encodes to itself, so clean labels/paths keep their
+// existing envelope id (and the atom ids derived from it), preserving re-check stability.
+const escapeEnvelopeField = (value) => value.split("\\").join("\\\\").split("|").join("\\|");
+export const envelopeIdFor = (index, label, content) => {
+    const digest = sha256Hex(`qi-src-v1|${String(index)}|${escapeEnvelopeField(label)}|${escapeEnvelopeField(content)}`).slice(0, 24);
     return QualityIntelligence.asQualityIntelligenceSourceEnvelopeId(`qi-src-${digest}`);
 };
 const REQUIREMENTS_ENVELOPE_PREFIX = "qi-src-req-";
@@ -101,6 +174,7 @@ const requirementsEnvelopeIdFor = (index) => {
     return QualityIntelligence.asQualityIntelligenceSourceEnvelopeId(`${REQUIREMENTS_ENVELOPE_PREFIX}${digest}`);
 };
 const stableLocalRef = (prefix, value) => `${prefix}:${sha256Hex(value).slice(0, 24)}`;
+const replacementGroupIdFor = (envelopeId, stableKey) => sha256Hex(`qi-replace-v1|${String(envelopeId)}|${stableKey}`);
 const auditSummaryIdFor = (runId) => QualityIntelligence.asQualityIntelligenceAuditSummaryId(`qi-audit-${sha256Hex(runId).slice(0, 24)}`);
 function ingestRequirements(source, index, registeredAt) {
     const text = typeof source.text === "string" ? source.text : "";
@@ -125,7 +199,14 @@ function ingestRequirements(source, index, registeredAt) {
         },
         localRef: `req:${String(index)}`,
     };
-    return { envelope, atoms };
+    return {
+        envelope,
+        atoms: atoms.map((entry, ordinal) => Object.freeze({
+            ...entry,
+            replacementGroupId: replacementGroupIdFor(envelopeId, `requirements:${String(index)}`),
+            replacementOrdinal: ordinal,
+        })),
+    };
 }
 const WORKSPACE_BUDGET_BYTES = 196_608;
 const WORKSPACE_MAX_BYTES_PER_FILE = 16_384;
@@ -170,7 +251,7 @@ function documentRequirementAtoms(entry, envelopeId) {
     });
     if (split.length <= 1)
         return Object.freeze([]);
-    return Object.freeze(split.map((requirement) => {
+    return Object.freeze(split.map((requirement, ordinal) => {
         const canonicalText = `${entry.path}\n${requirement.canonicalText}`;
         const atom = {
             kind: "requirement",
@@ -180,7 +261,12 @@ function documentRequirementAtoms(entry, envelopeId) {
             redactionStatus: "redacted",
             lifecycleStatus: "draft",
         };
-        return Object.freeze({ atom: Object.freeze(atom), canonicalText });
+        return Object.freeze({
+            atom: Object.freeze(atom),
+            canonicalText,
+            replacementGroupId: replacementGroupIdFor(envelopeId, `document:${entry.path}`),
+            replacementOrdinal: ordinal,
+        });
     }));
 }
 function atomsForWorkspaceEntry(entry, envelopeId) {
@@ -194,8 +280,8 @@ function atomsForWorkspaceEntry(entry, envelopeId) {
 // entry becomes one content-bearing atom under a single repository-context envelope.
 function ingestWorkspace(source, index, registeredAt, byteBudget) {
     const label = sanitiseLabel(source.label);
-    // Reject a folder whose ROOT names a denied credential location: connecting e.g. ~/.aws or
-    // ~/.docker AS A FOLDER would otherwise ingest credential files whose RELATIVE paths
+    // Reject a folder whose ROOT names a denied credential location (lexically or via a symlinked root):
+    // connecting e.g. ~/.aws AS A FOLDER would otherwise ingest credential files whose RELATIVE paths
     // ("credentials", "config.json") never trip the per-file deny check (#729 security).
     assertNotDenied(resolve(source.path), label, "Folder");
     let workspace;
@@ -332,7 +418,7 @@ function ingestFile(source, index, registeredAt, byteBudget) {
         throw new QiIngestionError("QI_SOURCE_UNSUPPORTED", `File "${label}" is not a supported single-file document.`);
     }
     // Reject any path whose segments name a denied credential directory or file (.ssh, .aws, .env,
-    // *.pem, id_rsa, …) regardless of how the workspace root resolves below.
+    // *.pem, id_rsa, …) — lexically or after symlink resolution — regardless of the workspace root below.
     assertNotDenied(absFile, label, "File");
     const content = readSingleFileContent(absFile, label);
     // keiko-workspace decodes as UTF-8; a NUL byte is the canonical binary marker. A binary file that
@@ -402,7 +488,7 @@ function processCapsuleDocs(docs, byteBudget) {
     const processed = [];
     let totalBytes = 0;
     for (const doc of docs) {
-        const capped = truncateToUtf8Bytes(redact(doc.text), perDocBudget);
+        const capped = truncateToUtf8Bytes(redact(stripUnsafeFormatChars(doc.text)), perDocBudget);
         if (capped.trim().length === 0)
             continue;
         const bytes = utf8ByteLength(capped);
@@ -419,8 +505,9 @@ function processCapsuleDocs(docs, byteBudget) {
 // Build one evidence atom per capsule document. Reuses the workspace atom shape so the model sees
 // structured text (documentId prefix + body), consistent with folder/file sources. The text is
 // already redacted + capped by processCapsuleDocs, so redactionStatus:"redacted" is truthful.
-function capsuleDocAtom(docId, text, envelopeId) {
+function capsuleDocAtom(docId, text, envelopeId, fingerprintText = text) {
     const canonicalText = `${docId}\n${text}`;
+    const fingerprintCanonicalText = `${docId}\n${fingerprintText}`;
     // Derive the atom id from the stable document id only — never its position in the corpus order
     // (Epic #735 drift correctness, mirrors workspaceAtom). A capsule document id (and a Figma
     // screen id) is unique within its envelope, so adding/removing a sibling document never shifts an
@@ -431,7 +518,7 @@ function capsuleDocAtom(docId, text, envelopeId) {
         kind: "document-excerpt",
         id: QualityIntelligence.asQualityIntelligenceEvidenceAtomId(`qi-atom-${digest}`),
         sourceEnvelopeId: envelopeId,
-        canonicalHashSha256Hex: sha256Hex(canonicalText),
+        canonicalHashSha256Hex: sha256Hex(fingerprintCanonicalText),
         redactionStatus: "redacted",
         lifecycleStatus: "draft",
     };
@@ -490,25 +577,67 @@ function ingestCapsuleSet(source, index, registeredAt, resolver, byteBudget) {
         emptyError: `Capsule set "${label}" has no indexed content or could not be opened.`,
     }, byteBudget);
 }
-// ─── Figma snapshot source (Epic #750, Issue #754) ───────────────────────────────
-//
-// A stored Figma Snapshot is ingested into one atom PER SCREEN: the deterministic, model-free
-// structural baseline derived from the screen's Screen-IR (#752), optionally enriched by additive
-// vision hints (capability-routed via #810; degrades to IR-only). Each atom carries screen
-// provenance so a generated test is attributable to its origin screen. The canonical text is
-// redacted before the atom is built (defense in depth — the snapshot is already redacted at persist)
-// and budget-capped exactly like the capsule path so a large board degrades gracefully.
-/** Vision-augment one screen's baseline text without ever overriding it (additive only). */
-function visionAugmentedScreenText(baseline, screen, vision) {
-    const baselineText = QualityIntelligenceFigma.renderBaselineText(baseline);
-    if (vision === undefined)
-        return baselineText;
-    const hints = vision({
+function isPromiseLike(value) {
+    return typeof value.then === "function";
+}
+function collectIrStats(node, stats) {
+    const next = {
+        imageFillCount: stats.imageFillCount + node.imageFills.length,
+        textNodeCount: stats.textNodeCount + (node.text !== undefined && node.text.trim().length > 0 ? 1 : 0),
+        semanticNodeCount: stats.semanticNodeCount +
+            (node.interactionHint === "button" ||
+                node.interactionHint === "input" ||
+                node.interactionHint === "link"
+                ? 1
+                : 0),
+    };
+    return node.children.reduce((acc, child) => collectIrStats(child, acc), next);
+}
+function screenNeedsVisionAugmentation(ir, baseline) {
+    const stats = collectIrStats(ir.root, {
+        imageFillCount: 0,
+        textNodeCount: 0,
+        semanticNodeCount: 0,
+    });
+    const structuralItems = baseline.items.filter((item) => item.category !== "screen-render").length;
+    return (stats.imageFillCount > 0 ||
+        stats.textNodeCount === 0 ||
+        stats.semanticNodeCount === 0 ||
+        structuralItems === 0);
+}
+function figmaVisionRequest(record, screen, baselineText) {
+    return {
+        snapshotRunId: record.runId,
         screenId: screen.screenId,
+        image: screen.image,
         imageRelativePath: screen.image.relativePath,
         baselineText,
-    });
-    return QualityIntelligenceFigma.mergeVisionHints(baselineText, hints).text;
+    };
+}
+function mergeFigmaVisionHints(baselineText, hints) {
+    return {
+        text: QualityIntelligenceFigma.mergeVisionHints(baselineText, hints).text,
+        fingerprintText: baselineText,
+    };
+}
+/** Vision-augment one screen's baseline text without ever overriding it (additive only). */
+function visionAugmentedScreenText(baseline, ir, record, screen, vision) {
+    const baselineText = QualityIntelligenceFigma.renderBaselineText(baseline);
+    if (vision === undefined || !screenNeedsVisionAugmentation(ir, baseline)) {
+        return { text: baselineText, fingerprintText: baselineText };
+    }
+    const hints = vision(figmaVisionRequest(record, screen, baselineText));
+    return isPromiseLike(hints)
+        ? { text: baselineText, fingerprintText: baselineText }
+        : mergeFigmaVisionHints(baselineText, hints);
+}
+async function visionAugmentedScreenTextAsync(baseline, ir, record, screen, vision) {
+    const baselineText = QualityIntelligenceFigma.renderBaselineText(baseline);
+    if (vision === undefined || !screenNeedsVisionAugmentation(ir, baseline)) {
+        return { text: baselineText, fingerprintText: baselineText };
+    }
+    const hints = await vision(figmaVisionRequest(record, screen, baselineText));
+    return mergeFigmaVisionHints(baselineText, hints);
 }
 // Parse every screen's opaque irJson once; an unparseable screen is dropped (never crashes the run).
 function parseScreens(record) {
@@ -540,6 +669,49 @@ function navItemsByScreen(parsed, links) {
 function a11yItemsByScreen(parsed) {
     return QualityIntelligenceFigma.deriveA11yTestItemsByScreen(parsed.map((p) => p.ir));
 }
+function figmaDocumentId(screenId, screenName) {
+    // Correct order (the #734 strip-before-redact rule): strip format chars first to
+    // de-obfuscate any zero-width-split secret, then redact (now catches raw AND ZW-split
+    // secrets → emits "[REDACTED]"), then sanitiseLabel for display safety (collapses
+    // newlines, URLs, paths). Mirrors redactFigmaAtomText = redact(stripUnsafeFormatChars)
+    // below, with sanitiseLabel as the final display-safe step.
+    const safeName = sanitiseLabel(redact(stripUnsafeFormatChars(screenName)));
+    return `${screenId} (${truncateToUtf8Bytes(safeName, MAX_LABEL_CHARS)})`;
+}
+// Strip Unicode bidi-override / zero-width / C1 spoofing code points from the untrusted Figma-derived
+// atom text BEFORE secret redaction. Two reasons for this order (the #734 strip-before-redact rule):
+// stripping first DE-OBFUSCATES a zero-width-split secret so the redactor can still match it, and it
+// removes the bidi/zero-width chars that would otherwise ride a Figma screen name or prototype trigger
+// verbatim into the QI atom text and every downstream export (bidi-spoofing of generated test titles).
+// Symmetric with the candidate-text path (buildRequirementExcerpt) and the source-label path
+// (sanitiseLabel / stripUnsafeLabelChars). TAB/LF/CR are preserved so the multi-line baseline structure
+// stays intact; clean inputs are byte-identical, so the atom hash and budget accounting are unchanged.
+const redactFigmaAtomText = (text) => redact(stripUnsafeFormatChars(text));
+function consumeVisionProviderForScreen(vision, remainingVisionScreens, ir, baseline) {
+    if (vision === undefined ||
+        remainingVisionScreens <= 0 ||
+        !screenNeedsVisionAugmentation(ir, baseline)) {
+        return { provider: undefined, remaining: remainingVisionScreens };
+    }
+    return { provider: vision, remaining: remainingVisionScreens - 1 };
+}
+function corpusDocFromFigmaScreen(row, ir, augmented, perDocBudget) {
+    const capped = truncateToUtf8Bytes(redactFigmaAtomText(augmented.text), perDocBudget);
+    if (capped.trim().length === 0)
+        return undefined;
+    const fingerprintText = truncateToUtf8Bytes(redactFigmaAtomText(augmented.fingerprintText), perDocBudget);
+    return {
+        doc: {
+            documentId: figmaDocumentId(row.screenId, ir.name),
+            text: capped,
+            fingerprintText,
+        },
+        bytes: utf8ByteLength(capped),
+    };
+}
+function figmaDocFitsBudget(docs, totalBytes, nextBytes, perRunBudget) {
+    return docs.length === 0 || totalBytes + nextBytes <= perRunBudget;
+}
 // Derive the redacted, budget-capped canonical text for every parseable screen. Each screen's
 // deterministic structural baseline (#754) is augmented additively with its navigation/flow test
 // items (#811) AND its accessibility test items (#812) — concatenated, neither replacing the other —
@@ -558,18 +730,45 @@ function figmaScreenDocs(record, vision, byteBudget) {
     const a11yItems = a11yItemsByScreen(parsed);
     const docs = [];
     let totalBytes = 0;
+    let remainingVisionScreens = MAX_FIGMA_VISION_AUGMENTED_SCREENS;
     for (const { row, ir } of parsed) {
         const extraItems = [...(navItems.get(ir.id) ?? []), ...(a11yItems.get(ir.id) ?? [])];
         const baseline = QualityIntelligenceFigma.deriveScreenTestBaseline(ir, extraItems);
-        const augmented = visionAugmentedScreenText(baseline, row, vision);
-        const capped = truncateToUtf8Bytes(redact(augmented), perDocBudget);
-        if (capped.trim().length === 0)
+        const visionSlot = consumeVisionProviderForScreen(vision, remainingVisionScreens, ir, baseline);
+        remainingVisionScreens = visionSlot.remaining;
+        const augmented = visionAugmentedScreenText(baseline, ir, record, row, visionSlot.provider);
+        const nextDoc = corpusDocFromFigmaScreen(row, ir, augmented, perDocBudget);
+        if (nextDoc === undefined)
             continue;
-        const bytes = utf8ByteLength(capped);
-        if (docs.length > 0 && totalBytes + bytes > perRunBudget)
+        if (!figmaDocFitsBudget(docs, totalBytes, nextDoc.bytes, perRunBudget))
             break;
-        docs.push({ documentId: `${row.screenId} (${ir.name})`, text: capped });
-        totalBytes += bytes;
+        docs.push(nextDoc.doc);
+        totalBytes += nextDoc.bytes;
+    }
+    return docs;
+}
+async function figmaScreenDocsAsync(record, vision, byteBudget) {
+    const perRunBudget = Math.min(CAPSULE_BUDGET_BYTES, byteBudget);
+    const perDocBudget = Math.min(CAPSULE_MAX_BYTES_PER_DOCUMENT, perRunBudget);
+    const parsed = parseScreens(record);
+    const navItems = navItemsByScreen(parsed, record.links ?? []);
+    const a11yItems = a11yItemsByScreen(parsed);
+    const docs = [];
+    let totalBytes = 0;
+    let remainingVisionScreens = MAX_FIGMA_VISION_AUGMENTED_SCREENS;
+    for (const { row, ir } of parsed) {
+        const extraItems = [...(navItems.get(ir.id) ?? []), ...(a11yItems.get(ir.id) ?? [])];
+        const baseline = QualityIntelligenceFigma.deriveScreenTestBaseline(ir, extraItems);
+        const visionSlot = consumeVisionProviderForScreen(vision, remainingVisionScreens, ir, baseline);
+        remainingVisionScreens = visionSlot.remaining;
+        const augmented = await visionAugmentedScreenTextAsync(baseline, ir, record, row, visionSlot.provider);
+        const nextDoc = corpusDocFromFigmaScreen(row, ir, augmented, perDocBudget);
+        if (nextDoc === undefined)
+            continue;
+        if (!figmaDocFitsBudget(docs, totalBytes, nextDoc.bytes, perRunBudget))
+            break;
+        docs.push(nextDoc.doc);
+        totalBytes += nextDoc.bytes;
     }
     return docs;
 }
@@ -586,7 +785,7 @@ function ingestFigmaSnapshot(source, index, registeredAt, loader, vision, byteBu
     if (docs.length === 0) {
         throw new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}" produced no usable screen baseline.`);
     }
-    const joinedText = docs.map((d) => d.text).join("\n");
+    const joinedFingerprintText = docs.map((d) => d.fingerprintText ?? d.text).join("\n");
     const envelopeId = envelopeIdFor(index, label, source.snapshotRunId);
     // A stored Figma Snapshot is figma evidence, not repository context. Use the dedicated
     // `figma-evidence` envelope kind (#278 AC2 "represented as an explicit connector-backed source"
@@ -599,11 +798,40 @@ function ingestFigmaSnapshot(source, index, registeredAt, loader, vision, byteBu
         provenance: {
             origin: `figma-snapshot:${source.snapshotRunId}`,
             registeredAt,
-            integrityHashSha256Hex: sha256Hex(joinedText),
+            integrityHashSha256Hex: sha256Hex(joinedFingerprintText),
         },
         localRef: stableLocalRef("figma-snapshot", source.snapshotRunId),
     };
-    const atoms = docs.map((d) => capsuleDocAtom(d.documentId, d.text, envelopeId));
+    const atoms = docs.map((d) => capsuleDocAtom(d.documentId, d.text, envelopeId, d.fingerprintText ?? d.text));
+    return { envelope, atoms };
+}
+async function ingestFigmaSnapshotAsync(source, index, registeredAt, loader, vision, byteBudget) {
+    const label = sanitiseLabel(source.label);
+    const record = loader(source.snapshotRunId);
+    if (record === undefined) {
+        throw new QiIngestionError("QI_FIGMA_SNAPSHOT_UNAVAILABLE", `Figma snapshot "${label}" could not be found or read. Build the snapshot first.`);
+    }
+    if (record.screens.length === 0) {
+        throw new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}" has no screens.`);
+    }
+    const docs = await figmaScreenDocsAsync(record, vision, byteBudget);
+    if (docs.length === 0) {
+        throw new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}" produced no usable screen baseline.`);
+    }
+    const joinedFingerprintText = docs.map((d) => d.fingerprintText ?? d.text).join("\n");
+    const envelopeId = envelopeIdFor(index, label, source.snapshotRunId);
+    const envelope = {
+        id: envelopeId,
+        kind: "figma-evidence",
+        displayLabel: label,
+        provenance: {
+            origin: `figma-snapshot:${source.snapshotRunId}`,
+            registeredAt,
+            integrityHashSha256Hex: sha256Hex(joinedFingerprintText),
+        },
+        localRef: stableLocalRef("figma-snapshot", source.snapshotRunId),
+    };
+    const atoms = docs.map((d) => capsuleDocAtom(d.documentId, d.text, envelopeId, d.fingerprintText ?? d.text));
     return { envelope, atoms };
 }
 function ingestOne(source, index, registeredAt, capsuleResolver, figmaSnapshotLoader, figmaVision, byteBudget) {
@@ -631,6 +859,15 @@ function ingestOne(source, index, registeredAt, capsuleResolver, figmaSnapshotLo
             return ingestFigmaSnapshot(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget);
     }
 }
+async function ingestOneAsync(source, index, registeredAt, capsuleResolver, figmaSnapshotLoader, figmaVision, byteBudget) {
+    if (source.kind !== "figma-snapshot") {
+        return ingestOne(source, index, registeredAt, capsuleResolver, figmaSnapshotLoader, figmaVision, byteBudget);
+    }
+    if (figmaSnapshotLoader === undefined) {
+        throw new QiIngestionError("QI_FIGMA_SNAPSHOT_UNAVAILABLE", "Figma-snapshot sources are unavailable: the evidence directory is not configured.");
+    }
+    return ingestFigmaSnapshotAsync(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget);
+}
 /**
  * Ingest one source into the accumulator (Epic #729 N+1 resilience). On a per-source QiIngestionError
  * the source is recorded as skipped and ingestion continues with the rest; a genuine (non-coded) bug
@@ -665,6 +902,56 @@ function ingestSourceInto(acc, source, index, input, budgets) {
         atomCount: taken.length,
     });
 }
+async function ingestSourceIntoAsync(acc, source, index, input, budgets) {
+    let ingested;
+    try {
+        ingested = await ingestOneAsync(source, index, input.registeredAt, input.capsuleResolver, input.figmaSnapshotLoader, input.figmaVision, budgets.byteBudget);
+    }
+    catch (error) {
+        if (!(error instanceof QiIngestionError))
+            throw error;
+        acc.firstSkipError ??= error;
+        acc.skippedSources.push({
+            label: sanitiseLabel(source.label),
+            kind: source.kind,
+            code: error.code,
+            message: error.message,
+        });
+        return;
+    }
+    const { envelope, atoms } = ingested;
+    const take = Math.min(budgets.atomBudget, MAX_TOTAL_ATOMS - acc.ingestedAtoms.length);
+    const taken = take <= 0 ? [] : atoms.slice(0, take);
+    acc.envelopes.push(envelope);
+    acc.ingestedAtoms.push(...taken);
+    acc.sourceSummaries.push({
+        label: envelope.displayLabel,
+        kind: source.kind,
+        atomCount: taken.length,
+    });
+}
+function emptyDriftIngestionResult(input, droppedSourceCount, skippedSources) {
+    return {
+        envelopes: [],
+        ingestedAtoms: [],
+        provenanceRefs: {
+            envelopeIds: [],
+            auditSummaryId: auditSummaryIdFor(input.runId),
+        },
+        sourceSummaries: [],
+        droppedSourceCount,
+        skippedSources,
+    };
+}
+function allowEmptyDriftIngestion(input, acc, droppedSourceCount) {
+    if (input.allowEmpty !== true)
+        return undefined;
+    const blockingSkip = acc.skippedSources.find((source) => source.code !== "QI_SOURCE_EMPTY");
+    if (blockingSkip !== undefined) {
+        throw new QiIngestionError(blockingSkip.code, blockingSkip.message);
+    }
+    return emptyDriftIngestionResult(input, droppedSourceCount, acc.skippedSources);
+}
 export function ingestInlineSources(input) {
     // Read through the typed property in the loop: `Array.isArray` would widen a local binding of the
     // readonly union array to `any[]`, so the guard checks length on the typed property directly.
@@ -699,6 +986,51 @@ export function ingestInlineSources(input) {
         ingestSourceInto(acc, source, i, input, budgets);
     }
     if (acc.ingestedAtoms.length === 0) {
+        const emptyDrift = allowEmptyDriftIngestion(input, acc, droppedSourceCount);
+        if (emptyDrift !== undefined)
+            return emptyDrift;
+        throw (acc.firstSkipError ??
+            new QiIngestionError("QI_SOURCE_EMPTY", "No usable evidence was produced from the sources."));
+    }
+    return {
+        envelopes: acc.envelopes,
+        ingestedAtoms: acc.ingestedAtoms,
+        provenanceRefs: {
+            envelopeIds: acc.envelopes.map((e) => String(e.id)),
+            auditSummaryId: auditSummaryIdFor(input.runId),
+        },
+        sourceSummaries: acc.sourceSummaries,
+        droppedSourceCount,
+        skippedSources: acc.skippedSources,
+    };
+}
+export async function ingestInlineSourcesAsync(input) {
+    const allSources = input.request.sources;
+    if (allSources.length === 0) {
+        throw new QiIngestionError("QI_NO_SOURCES", "At least one source is required to start a run.");
+    }
+    const sources = allSources.slice(0, MAX_QI_SOURCES);
+    const droppedSourceCount = allSources.length - sources.length;
+    const budgets = {
+        atomBudget: perSourceAtomBudget(MAX_TOTAL_ATOMS, sources.length),
+        byteBudget: perSourceByteBudget(sources.length),
+    };
+    const acc = {
+        envelopes: [],
+        ingestedAtoms: [],
+        sourceSummaries: [],
+        skippedSources: [],
+    };
+    for (let i = 0; i < sources.length; i += 1) {
+        const source = sources[i];
+        if (source === undefined)
+            continue;
+        await ingestSourceIntoAsync(acc, source, i, input, budgets);
+    }
+    if (acc.ingestedAtoms.length === 0) {
+        const emptyDrift = allowEmptyDriftIngestion(input, acc, droppedSourceCount);
+        if (emptyDrift !== undefined)
+            return emptyDrift;
         throw (acc.firstSkipError ??
             new QiIngestionError("QI_SOURCE_EMPTY", "No usable evidence was produced from the sources."));
     }

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runRegistry.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runRegistry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAErF,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEjF,UAAU,WAAW;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkC;IAEvD,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,eAAe;IAY7D,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI;IAMzE,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,iBAAiB,EAAE,SAAS,CAAC,GAAG,IAAI;IAM5E,oFAAoF;IACpF,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAO9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC,oFAAoF;IACpF,mBAAmB,IAAI,SAAS,+BAA+B,EAAE;IAUjE,wCAAwC;IACxC,KAAK,IAAI,IAAI;CAId;AAGD,eAAO,MAAM,aAAa,eAAsB,CAAC"}
+{"version":3,"file":"runRegistry.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runRegistry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAErF,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEjF,UAAU,WAAW;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkC;IAEvD,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,eAAe;IAY7D,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI;IAMzE,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,iBAAiB,EAAE,SAAS,CAAC,GAAG,IAAI;IAM5E,oFAAoF;IACpF,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAO9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC,oFAAoF;IACpF,mBAAmB,IAAI,SAAS,+BAA+B,EAAE;IAYjE,wCAAwC;IACxC,KAAK,IAAI,IAAI;CAId;AAGD,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runRegistry.js

@@ -51,6 +51,8 @@ export class QiRunRegistry {
             requestedAt: run.requestedAt,
             completedAt: null,
             totals: { ...run.totals },
+            // An in-flight run is not yet persisted and cannot have been reviewed (Issue #282 FIX A11y-2).
+            reviewState: "open",
         }));
     }
     /** Test seam: clear all active runs. */

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runRoutes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runRoutes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAKV,mCAAmC,EAEpC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,IAAI,EAAE,EAAE,MAAM,+BAA+B,CAAC;AAE/E,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA8N1D,wBAAgB,aAAa,CAC3B,KAAK,EAAE,EAAE,CAAC,2BAA2B,EACrC,MAAM,EAAE,QAAQ,GACf,mCAAmC,CAgBrC;AAoED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,CAAC,CAmBzB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,GAAG,WAAW,CAStF;AAED,eAAO,MAAM,4BAA4B,EAAE,SAAS,eAAe,EAOlE,CAAC"}
+{"version":3,"file":"runRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runRoutes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAKV,mCAAmC,EAGpC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,IAAI,EAAE,EAAE,MAAM,+BAA+B,CAAC;AAG/E,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+N1D,wBAAgB,aAAa,CAC3B,KAAK,EAAE,EAAE,CAAC,2BAA2B,EACrC,MAAM,EAAE,QAAQ,GACf,mCAAmC,CAgBrC;AA8ED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,CAAC,CAoBzB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,GAAG,WAAW,CAStF;AAED,eAAO,MAAM,4BAA4B,EAAE,SAAS,eAAe,EAOlE,CAAC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runRoutes.js

@@ -10,6 +10,7 @@
 import { randomUUID } from "node:crypto";
 import { isAbsolute } from "node:path";
 import { SSE_HEADERS } from "../sse.js";
+import { writeOrDestroy } from "../sse-write.js";
 import { STREAMING, } from "../routes.js";
 import { executeQiRun, QiGenerationError, QiIngestionError } from "./runExecution.js";
 import { qiRunRegistry } from "./runRegistry.js";
@@ -212,6 +213,13 @@ function classifyStartError(error) {
     }
     return { code: "QI_RUN_FAILED", message: "The Quality Intelligence run failed to complete." };
 }
+// Project the internal QiSkippedSource[] (which also carries a free-text `message`) to exactly the
+// wire contract QualityIntelligenceSkippedSource[] ({label, kind, code}). Streaming `message`
+// verbatim would widen the browser-facing SSE surface — the `accepted` frame bypasses deps.redactor,
+// unlike `event` — so it is dropped here (Issue #730).
+function toWireSkippedSources(skipped) {
+    return skipped.map((s) => ({ label: s.label, kind: s.kind, code: s.code }));
+}
 async function streamRunExecution(deps, request, runId, registeredAt, signal, write) {
     const totals = { candidates: 0, findings: 0, exports: 0 };
     let terminal = "failed";
@@ -233,7 +241,7 @@ async function streamRunExecution(deps, request, runId, registeredAt, signal, wr
                         ? { droppedSourceCount: accepted.droppedSourceCount }
                         : {}),
                     ...(accepted.skippedSources.length > 0
-                        ? { skippedSources: accepted.skippedSources }
+                        ? { skippedSources: toWireSkippedSources(accepted.skippedSources) }
                         : {}),
                 });
             },
@@ -263,14 +271,16 @@ export async function handleStartQiRun(ctx, deps) {
         return parsed.result;
     const runId = `qi-run-${randomUUID()}`;
     const registeredAt = new Date().toISOString();
-    ctx.res.writeHead(200, { ...SSE_HEADERS, "X-Accel-Buffering": "no" });
-    const write = (message) => {
-        ctx.res.write(`data: ${JSON.stringify(message)}\n\n`);
-    };
+    // Register and wire the disconnect listener BEFORE writeHead to close the narrow race where a
+    // client disconnects after parsing succeeds but before the response is committed.
     const controller = qiRunRegistry.register(runId, registeredAt);
     ctx.res.on("close", () => {
         controller.abort();
     });
+    ctx.res.writeHead(200, { ...SSE_HEADERS, "X-Accel-Buffering": "no" });
+    const write = (message) => {
+        writeOrDestroy(ctx.res, `data: ${JSON.stringify(message)}\n\n`, controller);
+    };
     await streamRunExecution(deps, parsed.request, runId, registeredAt, controller.signal, write);
     ctx.res.end();
     return STREAMING;