@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/runRegistry.d.ts

@@ -0,0 +1,31 @@
+import type { QualityIntelligenceUiRunSummary } from "@oscharko-dev/keiko-contracts";
+export type QiActiveRunStatus = "running" | "succeeded" | "failed" | "cancelled";
+interface QiActiveRun {
+    readonly runId: string;
+    status: QiActiveRunStatus;
+    readonly requestedAt: string;
+    readonly controller: AbortController;
+    totals: {
+        candidates: number;
+        findings: number;
+        exports: number;
+    };
+}
+export declare class QiRunRegistry {
+    private readonly runs;
+    /** Register a starting run and return its AbortController so the executor can wire cancellation. */
+    register(runId: string, requestedAt: string): AbortController;
+    updateTotals(runId: string, totals: Partial<QiActiveRun["totals"]>): void;
+    /** Mark terminal and drop the run from the active set (it is now durable in evidence). */
+    complete(runId: string, status: Exclude<QiActiveRunStatus, "running">): void;
+    /** Request cancellation. Returns false when the run is unknown/already finished. */
+    cancel(runId: string): boolean;
+    isActive(runId: string): boolean;
+    /** Active-run summaries for merging into the run list (status always "running"). */
+    listActiveSummaries(): readonly QualityIntelligenceUiRunSummary[];
+    /** Test seam: clear all active runs. */
+    reset(): void;
+}
+export declare const qiRunRegistry: QiRunRegistry;
+export {};
+//# sourceMappingURL=runRegistry.d.ts.map

package/dist/qualityIntelligence/runRegistry.d.ts.map

@@ -0,0 +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;IAYjE,wCAAwC;IACxC,KAAK,IAAI,IAAI;CAId;AAGD,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/dist/qualityIntelligence/runRegistry.js

@@ -0,0 +1,66 @@
+// Quality Intelligence in-memory active-run registry (Epic #270, Issue #273/#280).
+//
+// Tracks runs that are CURRENTLY executing so the UI can (a) see a run as "running" in the run list
+// before it lands in evidence and (b) cancel it. Completed runs live in evidence (restart-safe);
+// the registry only holds in-flight runs and is intentionally process-local — on restart, in-flight
+// runs are gone (they were never persisted) while completed runs survive. This is the QI counterpart
+// of the harness RunRegistry, kept separate because QI runs carry the QI run-event envelope.
+export class QiRunRegistry {
+    runs = new Map();
+    /** Register a starting run and return its AbortController so the executor can wire cancellation. */
+    register(runId, requestedAt) {
+        const controller = new AbortController();
+        this.runs.set(runId, {
+            runId,
+            status: "running",
+            requestedAt,
+            controller,
+            totals: { candidates: 0, findings: 0, exports: 0 },
+        });
+        return controller;
+    }
+    updateTotals(runId, totals) {
+        const run = this.runs.get(runId);
+        if (run === undefined)
+            return;
+        run.totals = { ...run.totals, ...totals };
+    }
+    /** Mark terminal and drop the run from the active set (it is now durable in evidence). */
+    complete(runId, status) {
+        const run = this.runs.get(runId);
+        if (run !== undefined)
+            run.status = status;
+        this.runs.delete(runId);
+    }
+    /** Request cancellation. Returns false when the run is unknown/already finished. */
+    cancel(runId) {
+        const run = this.runs.get(runId);
+        if (run === undefined)
+            return false;
+        run.controller.abort();
+        return true;
+    }
+    isActive(runId) {
+        return this.runs.has(runId);
+    }
+    /** Active-run summaries for merging into the run list (status always "running"). */
+    listActiveSummaries() {
+        return [...this.runs.values()].map((run) => ({
+            id: run.runId,
+            status: "running",
+            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. */
+    reset() {
+        for (const run of this.runs.values())
+            run.controller.abort();
+        this.runs.clear();
+    }
+}
+// Process-local singleton shared by the start, cancel, and list routes.
+export const qiRunRegistry = new QiRunRegistry();

package/dist/qualityIntelligence/runRoutes.d.ts

@@ -0,0 +1,16 @@
+import type { QualityIntelligenceRunStreamMessage } from "@oscharko-dev/keiko-contracts";
+import type { QualityIntelligence as QI } from "@oscharko-dev/keiko-contracts";
+import { type HandlerOutcome, type RouteContext, type RouteResult, type RouteDefinition } from "../routes.js";
+import type { Redactor, UiHandlerDeps } from "../deps.js";
+import { executeQiRun } from "./runExecution.js";
+export declare function toStreamEvent(event: QI.QualityIntelligenceRunEvent, redact: Redactor): QualityIntelligenceRunStreamMessage;
+type QiExecutionSummary = Awaited<ReturnType<typeof executeQiRun>>;
+type StreamTotals = Extract<QualityIntelligenceRunStreamMessage, {
+    type: "done";
+}>["totals"];
+export declare function doneFrameForSummary(deps: UiHandlerDeps, runId: string, summary: QiExecutionSummary, totals: StreamTotals): QualityIntelligenceRunStreamMessage;
+export declare function handleStartQiRun(ctx: RouteContext, deps: UiHandlerDeps): Promise<HandlerOutcome>;
+export declare function handleCancelQiRun(ctx: RouteContext, _deps: UiHandlerDeps): RouteResult;
+export declare const QI_RUN_EXECUTION_ROUTE_GROUP: readonly RouteDefinition[];
+export {};
+//# sourceMappingURL=runRoutes.d.ts.map

package/dist/qualityIntelligence/runRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runRoutes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAMV,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;AAC1D,OAAO,EACL,YAAY,EAIb,MAAM,mBAAmB,CAAC;AA4Q3B,wBAAgB,aAAa,CAC3B,KAAK,EAAE,EAAE,CAAC,2BAA2B,EACrC,MAAM,EAAE,QAAQ,GACf,mCAAmC,CAgBrC;AAkBD,KAAK,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC;AACnE,KAAK,YAAY,GAAG,OAAO,CAAC,mCAAmC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;AA0B7F,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,YAAY,GACnB,mCAAmC,CAiBrC;AAuCD,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/dist/qualityIntelligence/runRoutes.js

@@ -0,0 +1,357 @@
+// Quality Intelligence run start + cancel BFF routes (Epic #270, Issue #273/#280).
+//
+//   * POST /api/quality-intelligence/runs        — start a run; responds with an SSE progress stream
+//   * POST /api/quality-intelligence/runs/:id/cancel — cancel an in-flight run
+//
+// The start route validates the body, then writes a `text/event-stream` of
+// `QualityIntelligenceRunStreamMessage`s as the run progresses (accepted → events → done|error).
+// All stream payloads carry only ids / counts / safe enums — never prompts, model output, source
+// content, or credentials. A client disconnect aborts the run via the registry.
+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 { parseFigmaSnapshotScreenIds } from "./figmaSnapshotScreenIds.js";
+import { qiRunRegistry } from "./runRegistry.js";
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+class BodyTooLargeError extends Error {
+}
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let capped = false;
+    req.on("data", (chunk) => {
+        total += chunk.length;
+        if (total > MAX_BODY_BYTES) {
+            if (!capped) {
+                capped = true;
+                chunks.length = 0;
+                reject(new BodyTooLargeError());
+                req.resume();
+            }
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on("end", () => {
+        if (!capped)
+            resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+});
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const errorResult = (status, code, message) => ({
+    status,
+    body: { error: { code, message } },
+});
+function validateCapsuleSource(label, raw) {
+    if (typeof raw.capsuleId !== "string" || raw.capsuleId.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "A capsule source requires a non-empty capsuleId.");
+    }
+    return { kind: "capsule", label, capsuleId: raw.capsuleId };
+}
+function validateCapsuleSetSource(label, raw) {
+    if (typeof raw.capsuleSetId !== "string" || raw.capsuleSetId.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "A capsule-set source requires a non-empty capsuleSetId.");
+    }
+    return { kind: "capsule-set", label, capsuleSetId: raw.capsuleSetId };
+}
+function validateFigmaSnapshotSource(label, raw) {
+    if (typeof raw.snapshotRunId !== "string" || raw.snapshotRunId.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "A figma-snapshot source requires a non-empty snapshotRunId.");
+    }
+    // Single source of truth shared with the re-check route so run/recheck never diverge. An absent
+    // field stays a whole-snapshot source; a present field must be a non-empty, bounded, canonicalised
+    // scope — an explicit empty array is rejected here so it can never silently widen to the whole board.
+    const parsed = parseFigmaSnapshotScreenIds(raw.screenIds);
+    if (!parsed.ok) {
+        return errorResult(400, "QI_BAD_REQUEST", parsed.reason);
+    }
+    return {
+        kind: "figma-snapshot",
+        label,
+        snapshotRunId: raw.snapshotRunId,
+        ...(parsed.screenIds !== undefined ? { screenIds: parsed.screenIds } : {}),
+    };
+}
+function validateImageSource(label, raw) {
+    if (raw.sourceKind !== "figma-snapshot-screen") {
+        return errorResult(400, "QI_BAD_REQUEST", "An image source requires sourceKind figma-snapshot-screen.");
+    }
+    if (typeof raw.snapshotRunId !== "string" || raw.snapshotRunId.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "An image source requires a non-empty snapshotRunId.");
+    }
+    if (typeof raw.screenId !== "string" || raw.screenId.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "An image source requires a non-empty screenId.");
+    }
+    return {
+        kind: "image",
+        label,
+        sourceKind: "figma-snapshot-screen",
+        snapshotRunId: raw.snapshotRunId,
+        screenId: raw.screenId,
+    };
+}
+// Connector sources (Local Knowledge capsule / capsule-set, Figma snapshot). Split out so
+// validateSource stays under the complexity budget as the source-kind union grows (Epic #710/#750).
+function validateConnectorSource(label, raw) {
+    if (raw.kind === "capsule") {
+        return validateCapsuleSource(label, raw);
+    }
+    if (raw.kind === "capsule-set") {
+        return validateCapsuleSetSource(label, raw);
+    }
+    if (raw.kind === "figma-snapshot") {
+        return validateFigmaSnapshotSource(label, raw);
+    }
+    if (raw.kind === "image") {
+        return validateImageSource(label, raw);
+    }
+    return undefined;
+}
+function validateSource(raw) {
+    if (!isObject(raw) || typeof raw.label !== "string")
+        return undefined;
+    const label = raw.label;
+    if (raw.kind === "requirements" && typeof raw.text === "string") {
+        return { kind: "requirements", label, text: raw.text };
+    }
+    if (raw.kind === "workspace" && typeof raw.path === "string") {
+        return { kind: "workspace", label, path: raw.path };
+    }
+    if (raw.kind === "file" && typeof raw.path === "string") {
+        return { kind: "file", label, path: raw.path };
+    }
+    return validateConnectorSource(label, raw);
+}
+function isRouteResult(v) {
+    return isObject(v) && typeof v.status === "number";
+}
+function validateSourceEntry(raw) {
+    const source = validateSource(raw);
+    if (source === undefined) {
+        return errorResult(400, "QI_BAD_SOURCE", "A source entry is malformed.");
+    }
+    // A capsule (or other) field-level validation failure surfaces as a RouteResult — propagate it.
+    if (isRouteResult(source)) {
+        return source;
+    }
+    if (source.kind === "file" && !isAbsolute(source.path)) {
+        return errorResult(400, "QI_BAD_SOURCE", "File source paths must be absolute local paths.");
+    }
+    return source;
+}
+function collectSources(rawSources) {
+    const sources = [];
+    for (const raw of rawSources) {
+        // validateSourceEntry adds the absolute-path guard for file sources (#791) on top of the
+        // shape + capsule validation, surfacing any failure as a RouteResult.
+        const source = validateSourceEntry(raw);
+        if (isRouteResult(source)) {
+            return { ok: false, result: source };
+        }
+        sources.push(source);
+    }
+    return { ok: true, sources };
+}
+function parseOptionalSeed(value) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function buildStartRequest(sources, profileId, modelId, seed) {
+    return {
+        sources,
+        ...(profileId ? { profileId } : {}),
+        ...(modelId ? { modelId } : {}),
+        ...(seed !== undefined ? { seed } : {}),
+    };
+}
+function validateRequest(parsed) {
+    if (!isObject(parsed) || !Array.isArray(parsed.sources) || parsed.sources.length === 0) {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "At least one source is required."),
+        };
+    }
+    const collected = collectSources(parsed.sources);
+    if (!collected.ok)
+        return collected;
+    const profileId = typeof parsed.profileId === "string" ? parsed.profileId : undefined;
+    const modelId = typeof parsed.modelId === "string" ? parsed.modelId : undefined;
+    const seed = parseOptionalSeed(parsed.seed);
+    if (seed === null) {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "Seed must be a non-negative safe integer when provided."),
+        };
+    }
+    return {
+        ok: true,
+        request: buildStartRequest(collected.sources, profileId, modelId, seed),
+    };
+}
+async function parseStartBody(req) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (error) {
+        return error instanceof BodyTooLargeError
+            ? { ok: false, result: errorResult(413, "QI_BODY_TOO_LARGE", "Request body is too large.") }
+            : { ok: false, result: errorResult(400, "QI_BAD_REQUEST", "Could not read request body.") };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "Request body is not valid JSON."),
+        };
+    }
+    return validateRequest(parsed);
+}
+// Exported for unit testing of the reasonSummary redaction backstop (#279 AC3); not part of the
+// package public surface (the QI index re-exports only the route handlers, not this helper).
+export function toStreamEvent(event, redact) {
+    const p = event.payload;
+    return {
+        type: "event",
+        kind: p.kind,
+        sequence: event.sequence,
+        ...("stageName" in p ? { stageName: p.stageName } : {}),
+        ...("candidateId" in p ? { candidateId: String(p.candidateId) } : {}),
+        ...("findingId" in p ? { findingId: String(p.findingId) } : {}),
+        // `reasonSummary` is the only free-text field on the QI event envelope. The workflow already
+        // produces a fail-closed, secret-free summary (see `safeReasonSummary`), but pass it through the
+        // live-payload redactor too so this SSE writer — the one QI surface with no other redaction —
+        // can never stream a credential/endpoint substring should a future code path widen the field
+        // (#279 AC3, defence-in-depth; mirrors the Conversation Center SSE redaction posture).
+        ...("reasonSummary" in p ? { reasonSummary: applyRedactor(redact, p.reasonSummary) } : {}),
+    };
+}
+// Apply the live-payload redactor to a string field. The redactor is typed `(unknown) => unknown`
+// (it walks arbitrary structures); for a string input it returns the redacted string. Fall back to
+// the already-safe input on the impossible non-string return so the field type stays `string`.
+function applyRedactor(redact, value) {
+    const out = redact(value);
+    return typeof out === "string" ? out : value;
+}
+function classifyStartError(error) {
+    if (error instanceof QiIngestionError || error instanceof QiGenerationError) {
+        return { code: error.code, message: error.message };
+    }
+    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 }));
+}
+function writeAcceptedFrame(write, accepted) {
+    write({
+        type: "accepted",
+        runId: accepted.runId,
+        requestedAt: accepted.requestedAt,
+        sourceCount: accepted.sourceCount,
+        atomCount: accepted.atomCount,
+        ...(accepted.droppedSourceCount > 0 ? { droppedSourceCount: accepted.droppedSourceCount } : {}),
+        ...(accepted.skippedSources.length > 0
+            ? { skippedSources: toWireSkippedSources(accepted.skippedSources) }
+            : {}),
+    });
+}
+export function doneFrameForSummary(deps, runId, summary, totals) {
+    // Surface the bounded reasonSummary for BOTH a terminal failed run and a succeeded-but-degraded run
+    // (model/parser fell back to the deterministic baseline). The reason is already safeReasonSummary-
+    // bounded server-side; re-redact defensively before it reaches the wire.
+    const reasonSummary = summary.reasonSummary !== undefined
+        ? applyRedactor(deps.redactor, summary.reasonSummary)
+        : undefined;
+    const degraded = summary.status === "succeeded" && reasonSummary !== undefined ? true : undefined;
+    return {
+        type: "done",
+        runId,
+        status: summary.status,
+        totals,
+        ...(reasonSummary !== undefined ? { reasonSummary } : {}),
+        ...(degraded !== undefined ? { degraded } : {}),
+    };
+}
+async function streamRunExecution(deps, request, runId, registeredAt, signal, write) {
+    const totals = { candidates: 0, findings: 0, exports: 0 };
+    let terminal = "failed";
+    try {
+        const summary = await executeQiRun({
+            request,
+            runId,
+            deps,
+            registeredAt,
+            signal,
+            onAccepted: (accepted) => {
+                writeAcceptedFrame(write, accepted);
+            },
+            onEvent: (event) => {
+                if (event.payload.kind === "candidate:proposed")
+                    totals.candidates += 1;
+                if (event.payload.kind === "finding:recorded")
+                    totals.findings += 1;
+                qiRunRegistry.updateTotals(runId, totals);
+                write(toStreamEvent(event, deps.redactor));
+            },
+        });
+        terminal = summary.status;
+        write(doneFrameForSummary(deps, runId, summary, totals));
+    }
+    catch (error) {
+        const { code, message } = classifyStartError(error);
+        write({ type: "error", code, message });
+    }
+    finally {
+        qiRunRegistry.complete(runId, terminal);
+    }
+}
+export async function handleStartQiRun(ctx, deps) {
+    const parsed = await parseStartBody(ctx.req);
+    if (!parsed.ok)
+        return parsed.result;
+    const runId = `qi-run-${randomUUID()}`;
+    const registeredAt = new Date().toISOString();
+    // 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;
+}
+export function handleCancelQiRun(ctx, _deps) {
+    const { id } = ctx.params;
+    if (id === undefined || id.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "Run id is required.");
+    }
+    const cancelled = qiRunRegistry.cancel(id);
+    return cancelled
+        ? { status: 200, body: { cancelled: true, runId: id } }
+        : errorResult(404, "QI_NOT_ACTIVE", "No in-flight run with that id.");
+}
+export const QI_RUN_EXECUTION_ROUTE_GROUP = [
+    { method: "POST", pattern: "/api/quality-intelligence/runs", handler: handleStartQiRun },
+    {
+        method: "POST",
+        pattern: "/api/quality-intelligence/runs/:id/cancel",
+        handler: handleCancelQiRun,
+    },
+];

package/dist/qualityIntelligence/traceabilityRoutes.d.ts

@@ -0,0 +1,5 @@
+import type { RouteContext, RouteResult, RouteDefinition } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+export declare function handleQiTraceabilityExport(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare const QI_TRACEABILITY_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=traceabilityRoutes.d.ts.map

package/dist/qualityIntelligence/traceabilityRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceabilityRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/traceabilityRoutes.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAyHhD,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CA+CtB;AAED,eAAO,MAAM,2BAA2B,EAAE,SAAS,eAAe,EAMjE,CAAC"}

package/dist/qualityIntelligence/traceabilityRoutes.js

@@ -0,0 +1,173 @@
+// Quality Intelligence requirement↔test traceability export route (Epic #734, Issue #740).
+//
+//   * POST /api/quality-intelligence/runs/:id/traceability — export the persisted coverage matrix
+//     as an audit-ready requirement↔test traceability matrix (CSV or Markdown).
+//
+// A dedicated route (not folded into the generic export route) so the matrix-driven serializer,
+// which needs the coverage matrix rather than the candidate bodies, stays self-contained. The
+// matrix carries refs + status plus an optional already-redacted requirement excerpt (#790); the
+// reverse direction is enriched with the run's redacted candidate titles when the candidate
+// artifact is loadable. The serializers are deterministic and formula-injection safe.
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+import { appendQualityIntelligenceExportRow, loadQualityIntelligenceCandidates, loadQualityIntelligenceRun, } from "@oscharko-dev/keiko-evidence";
+import { QualityIntelligenceExport } from "@oscharko-dev/keiko-quality-intelligence";
+const MAX_BODY_BYTES = 4 * 1024;
+const FORMAT_META = {
+    csv: { contentType: "text/csv", ext: "csv" },
+    markdown: { contentType: "text/markdown", ext: "md" },
+};
+const errorResult = (status, code, message) => ({
+    status,
+    body: { error: { code, message } },
+});
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let capped = false;
+    req.on("data", (chunk) => {
+        total += chunk.length;
+        if (total > MAX_BODY_BYTES) {
+            if (!capped) {
+                capped = true;
+                chunks.length = 0;
+                reject(new Error("body too large"));
+                req.resume();
+            }
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on("end", () => {
+        if (!capped)
+            resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+});
+// Parse the requested format from the (optional) JSON body; defaults to CSV. An unreadable or
+// malformed body falls back to CSV rather than failing — the run id alone is a valid request.
+async function parseFormat(req) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch {
+        return "csv";
+    }
+    if (raw.trim().length === 0)
+        return "csv";
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null) {
+            const fmt = parsed.format;
+            if (fmt === "markdown")
+                return "markdown";
+        }
+    }
+    catch {
+        return "csv";
+    }
+    return "csv";
+}
+// Project persisted matrix rows onto adapter rows; the redacted excerpt (#790) is optional and
+// absent on runs recorded before it existed.
+function toTraceabilityRows(matrix) {
+    return matrix.map((r) => ({
+        atomId: r.atomId,
+        status: r.status,
+        confidence: r.confidence,
+        coveringCandidateIds: r.coveringCandidateIds,
+        ...(r.requirementExcerptRedacted !== undefined
+            ? { requirementExcerptRedacted: r.requirementExcerptRedacted }
+            : {}),
+    }));
+}
+// Candidate id -> redacted title for the tests->requirements direction (#790). Best-effort: a
+// missing/unreadable candidate artifact only drops the titles, never the export.
+function candidateTitlesFor(id, evidenceDir) {
+    const titles = new Map();
+    try {
+        const artifact = loadQualityIntelligenceCandidates(id, { evidenceDir });
+        for (const candidate of artifact?.candidates ?? []) {
+            titles.set(candidate.id, candidate.title);
+        }
+    }
+    catch {
+        // Titles are a display enrichment; the matrix itself is loaded and validated separately.
+    }
+    return titles;
+}
+/**
+ * Best-effort append of an export-evidence row after a successful traceability matrix download
+ * (Epic #734, Issue #740). A failed audit write must NOT withhold the already-computed body from
+ * the caller: the matrix is deterministic, has no external side effect, and the manifest write is
+ * atomic so failures are rare. Swallow on failure rather than turning a 200 into a 500.
+ */
+function recordTraceabilityExportEvidence(id, target, body, evidenceDir) {
+    const row = {
+        id: `qi-export-${sha256Hex(`${id}|${target}`).slice(0, 24)}`,
+        targetAdapter: target,
+        integrityHash: sha256Hex(body),
+        redactionAttested: true,
+        dryRun: false,
+    };
+    try {
+        appendQualityIntelligenceExportRow({ runId: id, export: row }, { evidenceDir });
+    }
+    catch {
+        // intentionally swallowed — see doc comment
+    }
+}
+export async function handleQiTraceabilityExport(ctx, deps) {
+    const { id } = ctx.params;
+    if (id === undefined || id.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "Run id is required.");
+    }
+    const evidenceDir = deps.evidenceDir;
+    if (evidenceDir === undefined) {
+        return errorResult(500, "QI_NO_EVIDENCE_DIR", "The evidence directory is not configured.");
+    }
+    const format = await parseFormat(ctx.req);
+    let manifest;
+    try {
+        manifest = loadQualityIntelligenceRun(id, { evidenceDir });
+    }
+    catch {
+        // CWE-209: never surface the underlying filesystem/parse error detail to the client; a
+        // corrupt or unreadable manifest is reported as an opaque 500 (mirrors uiRoutes.ts).
+        return errorResult(500, "QI_LOAD_FAILED", "Failed to load the Quality Intelligence run.");
+    }
+    if (manifest === undefined) {
+        return errorResult(404, "QI_NOT_FOUND", "Quality Intelligence run not found.");
+    }
+    const matrix = manifest.coverageMatrix ?? [];
+    if (matrix.length === 0) {
+        return errorResult(409, "QI_NO_COVERAGE", "This run has no coverage matrix to export.");
+    }
+    const rows = toTraceabilityRows(matrix);
+    const display = { candidateTitleById: candidateTitlesFor(id, evidenceDir) };
+    const body = format === "markdown"
+        ? QualityIntelligenceExport.adaptToTraceabilityMarkdown(rows, display)
+        : QualityIntelligenceExport.adaptToTraceabilityCsv(rows, display);
+    const target = format === "markdown" ? "traceability-markdown" : "traceability-csv";
+    // Emit audit evidence for the materialised download (Epic #734, Issue #740). Best-effort: see
+    // recordTraceabilityExportEvidence for the swallow rationale.
+    recordTraceabilityExportEvidence(id, target, body, evidenceDir);
+    const meta = FORMAT_META[format];
+    return {
+        status: 200,
+        body: {
+            format,
+            filename: `${id}-traceability.${meta.ext}`,
+            contentType: meta.contentType,
+            byteLen: Buffer.byteLength(body, "utf8"),
+            body,
+        },
+    };
+}
+export const QI_TRACEABILITY_ROUTE_GROUP = [
+    {
+        method: "POST",
+        pattern: "/api/quality-intelligence/runs/:id/traceability",
+        handler: handleQiTraceabilityExport,
+    },
+];

package/dist/qualityIntelligence/uiRoutes.d.ts

@@ -0,0 +1,7 @@
+import type { RouteContext, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+export declare const QI_RUN_LIST_DEFAULT_LIMIT = 100;
+export declare const QI_RUN_LIST_MAX_LIMIT = 500;
+export declare function handleListQiRuns(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleGetQiRun(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+//# sourceMappingURL=uiRoutes.d.ts.map