@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/editRoutes.js

@@ -0,0 +1,293 @@
+// Quality Intelligence inline-edit BFF route (Epic #712, Issue #726).
+//
+//   * POST /api/quality-intelligence/runs/:id/edit — edit a generated candidate's fields inline
+//
+// Updates the candidate row in place inside the MUTABLE candidates artifact (redacted, with
+// provenance appended to `editedRevisions[]`) and records an `edit` audit entry. The IMMUTABLE run
+// manifest (`<runId>.qi.json`) is never touched. CSRF is enforced by the dispatch layer for POST
+// (mirrors reviewRoutes); the body is capped at 16KB and every field is validated before persist.
+import { applyQualityIntelligenceCandidateEdit, loadQualityIntelligenceRun, } from "@oscharko-dev/keiko-evidence";
+import { QualityIntelligence, } from "@oscharko-dev/keiko-contracts";
+import { normaliseCandidateText } from "@oscharko-dev/keiko-quality-intelligence";
+import { appendEditAudit, candidateReviewStateOf, loadRunReviewState } from "./reviewStore.js";
+const MAX_BODY_BYTES = 16 * 1024;
+const MAX_TITLE_LEN = 256;
+const MAX_LIST_ITEMS = 100;
+const MAX_LABEL_LEN = 80;
+const PRIORITIES = new Set(QualityIntelligence.QUALITY_INTELLIGENCE_PRIORITIES);
+const RISK_CLASSES = new Set(QualityIntelligence.QUALITY_INTELLIGENCE_RISK_CLASSES);
+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);
+});
+const errorResult = (status, code, message) => ({
+    status,
+    body: { error: { code, message } },
+});
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+// A list field is an array (≤ MAX_LIST_ITEMS) of non-blank strings. `minItems` separates the two
+// domain shapes: steps and expected results are the load-bearing body of a test case and must carry
+// at least one entry (clearing them produces an empty, meaningless test case → reject); preconditions
+// and tags are legitimately optional and may be cleared. Blank ("") items are rejected for every list
+// field (a blank step / tag is never meaningful), keeping the persisted body clean.
+const isListField = (value, minItems) => Array.isArray(value) &&
+    value.length >= minItems &&
+    value.length <= MAX_LIST_ITEMS &&
+    value.every((item) => typeof item === "string" && item.length > 0);
+const isValidTitle = (value) => typeof value === "string" && value.length >= 1 && value.length <= MAX_TITLE_LEN;
+// Per-field validators keyed by field name. Keeping the branching in a data table (not a switch)
+// holds the validator helper's cyclomatic complexity low while still rejecting any malformed value.
+const FIELD_VALIDATORS = {
+    title: isValidTitle,
+    preconditions: (value) => isListField(value, 0),
+    steps: (value) => isListField(value, 1),
+    expectedResults: (value) => isListField(value, 1),
+    priority: (value) => typeof value === "string" && PRIORITIES.has(value),
+    riskClass: (value) => typeof value === "string" && RISK_CLASSES.has(value),
+    tags: (value) => isListField(value, 0),
+};
+// Validate one editable field. Returns `false` for a malformed value so the caller rejects the whole
+// edit (no partial persist). Unknown keys are ignored by the caller (only EDITABLE_KEYS are read).
+function isValidField(key, value) {
+    return FIELD_VALIDATORS[key]?.(value) ?? false;
+}
+const EDITABLE_KEYS = [
+    "title",
+    "preconditions",
+    "steps",
+    "expectedResults",
+    "priority",
+    "riskClass",
+    "tags",
+];
+function parseEditorLabel(value) {
+    if (typeof value !== "string")
+        return undefined;
+    // Strip bidi/zero-width/control spoofing code points (+ NFKC + trim) before length-capping so the
+    // persisted provenance `editorLabel` and the `.review.json` `reviewerLabel` (both derived from this
+    // one value) get the same content-safety treatment as generated candidate text. A label of only
+    // format characters normalises to "" and is rejected as a missing reviewer label.
+    const cleaned = normaliseCandidateText(value);
+    return cleaned.length > 0 ? cleaned.slice(0, MAX_LABEL_LEN) : undefined;
+}
+// The editable fields whose value is an array of candidate body-text lines. `title` (single string)
+// and the closed enums (priority / riskClass) are handled separately in normaliseEditedValue.
+const TEXT_LIST_KEYS = new Set([
+    "preconditions",
+    "steps",
+    "expectedResults",
+    "tags",
+]);
+// Strip bidi / zero-width / control spoofing code points (+ NFKC + trim) from every human-supplied
+// text field BEFORE validation, so an inline edit persists through the SAME candidate-text
+// normalisation as the generation path (parseGeneratedCandidates → normaliseCandidateText — the
+// documented single chokepoint for persisted candidate text). Closed enums (priority / riskClass) and
+// any non-string shape pass through untouched; their validators reject anything off-list. A title or
+// list item whose only content was format characters normalises to "" and is then rejected by the
+// non-blank validators (an actionable 400) rather than persisted as junk. Normalising first also means
+// MAX_TITLE_LEN is measured on the cleaned text, so padding a title with zero-width marks cannot
+// smuggle it past the length cap.
+function normaliseEditedValue(key, value) {
+    if (key === "title") {
+        return typeof value === "string" ? normaliseCandidateText(value) : value;
+    }
+    if (TEXT_LIST_KEYS.has(key) && Array.isArray(value)) {
+        // `Array.isArray` narrows `unknown` to `any[]`; widen back to `unknown[]` so each item is typed
+        // (no unsafe `any`). Non-string items pass through for the list validator to reject.
+        return value.map((item) => typeof item === "string" ? normaliseCandidateText(item) : item);
+    }
+    return value;
+}
+function collectEditedFields(edited) {
+    const collected = {};
+    let fieldCount = 0;
+    for (const key of EDITABLE_KEYS) {
+        const raw = edited[key];
+        if (raw === undefined)
+            continue;
+        const value = normaliseEditedValue(key, raw);
+        if (!isValidField(key, value))
+            return { ok: false, invalidField: key };
+        collected[key] = value;
+        fieldCount += 1;
+    }
+    return fieldCount > 0
+        ? { ok: true, fields: collected }
+        : { ok: false, invalidField: undefined };
+}
+// Returns the parsed edit, or a field-specific rejection message so the reviewer learns WHICH field
+// is invalid (a generic "edit is invalid" is not actionable). Any failing field rejects the whole
+// edit (no partial persist).
+function parseEdit(body) {
+    const candidateId = body.candidateId;
+    if (typeof candidateId !== "string" || candidateId.trim().length === 0) {
+        return { ok: false, message: "A candidate id is required." };
+    }
+    const editorLabel = parseEditorLabel(body.editorLabel);
+    if (editorLabel === undefined) {
+        return { ok: false, message: "A non-empty reviewer label is required." };
+    }
+    const edited = body.edited;
+    if (!isObject(edited)) {
+        return { ok: false, message: "An `edited` object with the changed fields is required." };
+    }
+    const collected = collectEditedFields(edited);
+    if (!collected.ok) {
+        return {
+            ok: false,
+            message: collected.invalidField === undefined
+                ? "At least one editable field must be supplied."
+                : `The "${collected.invalidField}" field is empty or invalid.`,
+        };
+    }
+    return { ok: true, edit: { candidateId, edited: collected.fields, editorLabel } };
+}
+async function readEdit(req) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch {
+        return { ok: false, result: errorResult(413, "QI_BODY_TOO_LARGE", "Edit body is too large.") };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "Edit body is not valid JSON."),
+        };
+    }
+    if (!isObject(parsed)) {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "Edit body must be an object."),
+        };
+    }
+    const edit = parseEdit(parsed);
+    if (!edit.ok) {
+        return { ok: false, result: errorResult(400, "QI_BAD_EDIT", edit.message) };
+    }
+    return { ok: true, edit: edit.edit };
+}
+// Project the edited row for the immediate POST response. This intentionally omits `weakTestFlag`
+// (the adversarial-judge badge): that flag is derived from the run MANIFEST findings, not the
+// candidate row, and recomputing it here would duplicate the run-detail GET's manifest read
+// (uiRoutes.ts) and risk drift. AC1 scopes "reflected" to the next run-detail fetch, where the GET
+// projection re-attaches `weakTestFlag`; clients refresh the badge from that fetch.
+function projectCandidate(row, evidenceDir, runId) {
+    const reviewArtifact = loadRunReviewState(runId, evidenceDir);
+    return {
+        id: row.id,
+        title: row.title,
+        preconditions: row.preconditions,
+        steps: row.steps,
+        expectedResults: row.expectedResults,
+        priority: row.priority,
+        riskClass: row.riskClass,
+        tags: row.tags,
+        status: row.status,
+        reviewState: candidateReviewStateOf(reviewArtifact, row.id),
+        derivedFromAtomIds: row.derivedFromAtomIds,
+    };
+}
+// Apply a validated edit (redacted, in-place), append the audit entry, and project the updated
+// candidate for the wire. Split out of the handler to keep the handler within the line budget.
+function recordEdit(runId, edit, evidenceDir, deps) {
+    const result = applyQualityIntelligenceCandidateEdit({
+        runId,
+        candidateId: edit.candidateId,
+        editedFields: edit.edited,
+        provenance: {
+            editedAt: new Date().toISOString(),
+            editedBy: "human",
+            editorLabel: edit.editorLabel,
+        },
+        evidenceDir,
+        redact: deps.redactor,
+    });
+    if (!result.ok) {
+        if (result.reason === "no-edited-fields") {
+            return errorResult(400, "QI_BAD_EDIT", "At least one editable field must be supplied.");
+        }
+        if (result.reason === "artifact-not-found") {
+            // The run manifest exists but its candidates companion is missing — a distinct, observable
+            // failure (corruption / partial state) rather than an unknown candidate id.
+            return errorResult(404, "QI_CANDIDATES_NOT_FOUND", "No candidates artifact exists for this run.");
+        }
+        return errorResult(404, "QI_NOT_FOUND", "Candidate not found for this run.");
+    }
+    if (result.changed) {
+        // Append the consolidated `.review.json` audit entry. The atomic, per-edit record is the
+        // `editedRevisions[]` provenance just written WITH the candidate change (a single candidates.json
+        // write inside applyQualityIntelligenceCandidateEdit); this is a second, separate companion write.
+        // If it throws (e.g. disk failure) the outer handler returns 500, but the edit is still recorded
+        // in editedRevisions[] provenance — an edit is never fully unaudited. The trade-off: the
+        // consolidated audit log can lag the per-artifact provenance on a partial-write failure, and a
+        // retry with identical fields is a no-op (changed === false) that won't backfill it. Cross-artifact
+        // write atomicity is a tracked follow-up; it is not introduced here to avoid touching the shared
+        // companion store used by every QI route.
+        appendEditAudit({
+            runId,
+            evidenceDir,
+            candidateId: edit.candidateId,
+            reviewerLabel: edit.editorLabel,
+            now: new Date().toISOString(),
+            redact: deps.redactor,
+        });
+    }
+    return {
+        status: 200,
+        body: { candidate: projectCandidate(result.candidate, evidenceDir, runId) },
+    };
+}
+export async function handleQiEditCandidate(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 parsed = await readEdit(ctx.req);
+    if (!parsed.ok)
+        return parsed.result;
+    try {
+        if (loadQualityIntelligenceRun(id, { evidenceDir }) === undefined) {
+            return errorResult(404, "QI_RUN_NOT_FOUND", "Quality Intelligence run not found.");
+        }
+        return recordEdit(id, parsed.edit, evidenceDir, deps);
+    }
+    catch {
+        return errorResult(500, "QI_EDIT_FAILED", "Failed to record the candidate edit.");
+    }
+}
+export const QI_EDIT_ROUTE_GROUP = [
+    {
+        method: "POST",
+        pattern: "/api/quality-intelligence/runs/:id/edit",
+        handler: handleQiEditCandidate,
+    },
+];

package/dist/qualityIntelligence/exportAssembly.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reduce an entry name to a contained, single-segment file name. Defense-in-depth: the run id is
+ * already brand-validated (no "/", "\\", ".." — see keiko-contracts ids.ts) before it reaches this
+ * helper, but the ZIP writer must not depend on its caller for containment. Strips any directory
+ * component, collapses traversal dot-runs, and rejects an empty result.
+ */
+export declare function safeZipEntryName(name: string): string;
+/**
+ * Assembles a deterministic STORE (no-compression) ZIP from the given entries.
+ * DOS date/time fields are zeroed for byte-stable output across runs. Entry names are reduced to a
+ * contained basename so a bundle can never write outside its own archive root.
+ */
+export declare function assembleZipBundle(entries: readonly {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}[]): Uint8Array;
+/**
+ * Assembles a deterministic, multi-page, text-only PDF from the given plain-text body. The entire
+ * body is rendered across as many pages as needed (no truncation). Byte-stable across identical runs.
+ */
+export declare function assemblePdf(body: string, runId: string): Uint8Array;
+//# sourceMappingURL=exportAssembly.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exportAssembly.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/exportAssembly.ts"],"names":[],"mappings":"AA6FA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,EAAE,GACxE,UAAU,CA+BZ;AA+KD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAmDnE"}

package/dist/qualityIntelligence/exportAssembly.js

@@ -0,0 +1,352 @@
+// Binary export assembly helpers (Epic #711).
+//
+// Produces deterministic binary artifacts — a minimal text-only PDF and a STORE
+// (no-compression) ZIP — with zero new runtime dependencies. Both formats are
+// assembled by hand to guarantee byte-stable output: no /CreationDate, no UUIDs,
+// no timestamps, no Math.random.
+//
+// PDF determinism: fixed object offsets, static trailer, no metadata objects.
+// ZIP determinism: DOS date/time zeroed, STORE method (no compression), CRC32
+// computed from content bytes, central directory built from the same metadata.
+// ─── Shared ───────────────────────────────────────────────────────────────────
+const TEXT_ENC = new TextEncoder();
+// ─── CRC32 ────────────────────────────────────────────────────────────────────
+const CRC32_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let k = 0; k < 8; k++) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        t[i] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (const byte of bytes) {
+        c = (CRC32_TABLE[(c ^ byte) & 0xff] ?? 0) ^ (c >>> 8);
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+// ─── Little-endian integer helpers ───────────────────────────────────────────
+function u16le(n) {
+    return [n & 0xff, (n >>> 8) & 0xff];
+}
+function u32le(n) {
+    return [n & 0xff, (n >>> 8) & 0xff, (n >>> 16) & 0xff, (n >>> 24) & 0xff];
+}
+// ─── ZIP assembly ─────────────────────────────────────────────────────────────
+const ZIP_LOCAL_HEADER_SIG = [0x50, 0x4b, 0x03, 0x04];
+const ZIP_CENTRAL_SIG = [0x50, 0x4b, 0x01, 0x02];
+const ZIP_EOCD_SIG = [0x50, 0x4b, 0x05, 0x06];
+function buildLocalHeader(name, size, crc) {
+    return [
+        ...ZIP_LOCAL_HEADER_SIG,
+        ...u16le(20), // version needed
+        ...u16le(0), // flags
+        ...u16le(0), // STORE method
+        ...u16le(0), // last mod time (zeroed)
+        ...u16le(0), // last mod date (zeroed)
+        ...u32le(crc),
+        ...u32le(size), // compressed size
+        ...u32le(size), // uncompressed size
+        ...u16le(name.length),
+        ...u16le(0), // extra field length
+        ...name,
+    ];
+}
+function buildCentralEntry(name, size, crc, offset) {
+    return [
+        ...ZIP_CENTRAL_SIG,
+        ...u16le(20), // version made by
+        ...u16le(20), // version needed
+        ...u16le(0), // flags
+        ...u16le(0), // STORE method
+        ...u16le(0), // last mod time (zeroed)
+        ...u16le(0), // last mod date (zeroed)
+        ...u32le(crc),
+        ...u32le(size), // compressed size
+        ...u32le(size), // uncompressed size
+        ...u16le(name.length),
+        ...u16le(0), // extra field length
+        ...u16le(0), // file comment length
+        ...u16le(0), // disk number start
+        ...u16le(0), // internal attributes
+        ...u32le(0), // external attributes
+        ...u32le(offset),
+        ...name,
+    ];
+}
+/**
+ * Reduce an entry name to a contained, single-segment file name. Defense-in-depth: the run id is
+ * already brand-validated (no "/", "\\", ".." — see keiko-contracts ids.ts) before it reaches this
+ * helper, but the ZIP writer must not depend on its caller for containment. Strips any directory
+ * component, collapses traversal dot-runs, and rejects an empty result.
+ */
+export function safeZipEntryName(name) {
+    const base = name
+        .replace(/^.*[\\/]/u, "") // drop any directory prefix (POSIX or Windows separators)
+        .replace(/\.{2,}/gu, "."); // collapse ".." (and longer dot-runs) so no traversal token survives
+    return base.length > 0 ? base : "export.bin";
+}
+/**
+ * Assembles a deterministic STORE (no-compression) ZIP from the given entries.
+ * DOS date/time fields are zeroed for byte-stable output across runs. Entry names are reduced to a
+ * contained basename so a bundle can never write outside its own archive root.
+ */
+export function assembleZipBundle(entries) {
+    const localHeaders = [];
+    const centralEntries = [];
+    const dataChunks = [];
+    const offsets = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const nameBytes = TEXT_ENC.encode(safeZipEntryName(entry.name));
+        const crc = crc32(entry.bytes);
+        const local = buildLocalHeader(nameBytes, entry.bytes.length, crc);
+        offsets.push(offset);
+        localHeaders.push(local);
+        dataChunks.push(entry.bytes);
+        offset += local.length + entry.bytes.length;
+        centralEntries.push(buildCentralEntry(nameBytes, entry.bytes.length, crc, offsets.at(-1) ?? 0));
+    }
+    const centralStart = offset;
+    const centralFlat = centralEntries.flatMap((e) => e);
+    const eocd = [
+        ...ZIP_EOCD_SIG,
+        ...u16le(0), // disk number
+        ...u16le(0), // central dir start disk
+        ...u16le(entries.length), // entries on disk
+        ...u16le(entries.length), // total entries
+        ...u32le(centralFlat.length),
+        ...u32le(centralStart),
+        ...u16le(0), // comment length
+    ];
+    return concatZipBytes(localHeaders, dataChunks, centralFlat, eocd);
+}
+// Interleave [localHeader, data] pairs, then the central directory and EOCD, into one buffer.
+function concatZipBytes(localHeaders, dataChunks, centralFlat, eocd) {
+    const totalLen = localHeaders.reduce((s, h) => s + h.length, 0) +
+        dataChunks.reduce((s, d) => s + d.length, 0) +
+        centralFlat.length +
+        eocd.length;
+    const out = new Uint8Array(totalLen);
+    let pos = 0;
+    for (let i = 0; i < localHeaders.length; i++) {
+        const hdr = localHeaders[i];
+        const dat = dataChunks[i];
+        if (hdr === undefined || dat === undefined)
+            continue;
+        out.set(hdr, pos);
+        pos += hdr.length;
+        out.set(dat, pos);
+        pos += dat.length;
+    }
+    out.set(centralFlat, pos);
+    pos += centralFlat.length;
+    out.set(eocd, pos);
+    return out;
+}
+// ─── PDF assembly ─────────────────────────────────────────────────────────────
+//
+// A minimal, dependency-free, multi-page text PDF. The whole candidate body is rendered (no
+// arbitrary truncation): lines are wrapped to the page width and paginated across as many A4 pages
+// as needed. Text is encoded as single-byte WinAnsi (CP1252) and the Courier font declares
+// /Encoding /WinAnsiEncoding, so German umlauts (ä ö ü Ä Ö Ü ß), the euro sign, and common
+// typographic punctuation render correctly instead of as UTF-8 mojibake. No /CreationDate,
+// no Producer, no random — byte-stable across identical runs.
+const PDF_FONT_SIZE = 10;
+const PDF_LEADING = 14;
+const PDF_MARGIN_X = 50;
+const PDF_TOP_Y = 792; // 842 page height − 50 top margin
+const PDF_BOTTOM_Y = 56; // keep the last baseline above the bottom margin
+const PDF_MAX_CHARS = 80; // Courier @10pt is 6pt/glyph → ~82 glyphs fit in 495pt; 80 leaves a margin
+const PDF_LINES_PER_PAGE = Math.floor((PDF_TOP_Y - PDF_BOTTOM_Y) / PDF_LEADING); // 52
+function pdfStr(s) {
+    return TEXT_ENC.encode(s);
+}
+function escapePdf(s) {
+    return s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+}
+// WinAnsi (CP1252) bytes for the code points that differ from Latin-1 in the 0x80–0x9F window.
+const CP1252_HIGH = {
+    0x20ac: 0x80,
+    0x201a: 0x82,
+    0x0192: 0x83,
+    0x201e: 0x84,
+    0x2026: 0x85,
+    0x2020: 0x86,
+    0x2021: 0x87,
+    0x02c6: 0x88,
+    0x2030: 0x89,
+    0x0160: 0x8a,
+    0x2039: 0x8b,
+    0x0152: 0x8c,
+    0x017d: 0x8e,
+    0x2018: 0x91,
+    0x2019: 0x92,
+    0x201c: 0x93,
+    0x201d: 0x94,
+    0x2022: 0x95,
+    0x2013: 0x96,
+    0x2014: 0x97,
+    0x02dc: 0x98,
+    0x2122: 0x99,
+    0x0161: 0x9a,
+    0x203a: 0x9b,
+    0x0153: 0x9c,
+    0x017e: 0x9e,
+    0x0178: 0x9f,
+};
+// Best-effort ASCII fold for common punctuation outside CP1252, so they degrade legibly (not to '?').
+const PDF_ASCII_FOLD = {
+    0x2010: 0x2d,
+    0x2011: 0x2d,
+    0x2012: 0x2d, // hyphen/figure/non-breaking dashes → '-'
+    0x00a0: 0x20,
+    0x2007: 0x20,
+    0x202f: 0x20, // no-break / figure / narrow spaces → ' '
+};
+function winAnsiByte(cp) {
+    if (cp === 0x09)
+        return 0x20; // tab → space
+    if (cp < 0x20)
+        return 0x3f; // other C0 controls → '?'
+    if (cp <= 0x7e)
+        return cp; // printable ASCII
+    if (cp === 0x7f)
+        return 0x3f; // DEL
+    if (cp >= 0xa0 && cp <= 0xff)
+        return cp; // Latin-1 printable (umlauts, ß, accented letters)
+    return CP1252_HIGH[cp] ?? PDF_ASCII_FOLD[cp] ?? 0x3f;
+}
+function winAnsiEncode(text) {
+    const codePoints = Array.from(text); // iterate by code point (surrogate-safe)
+    const out = new Uint8Array(codePoints.length);
+    for (let i = 0; i < codePoints.length; i++) {
+        out[i] = winAnsiByte(codePoints[i]?.codePointAt(0) ?? 0x3f);
+    }
+    return out;
+}
+// Greedy word-aware wrap to `maxChars`; a single over-long token is hard-broken. Preserves blanks.
+function wrapText(line, maxChars) {
+    if (line.length <= maxChars)
+        return [line];
+    const out = [];
+    let current = "";
+    for (const word of line.split(" ")) {
+        if (word.length > maxChars) {
+            if (current.length > 0)
+                out.push(current);
+            let rest = word;
+            while (rest.length > maxChars) {
+                out.push(rest.slice(0, maxChars));
+                rest = rest.slice(maxChars);
+            }
+            current = rest;
+            continue;
+        }
+        const candidate = current.length === 0 ? word : `${current} ${word}`;
+        if (candidate.length > maxChars) {
+            out.push(current);
+            current = word;
+        }
+        else {
+            current = candidate;
+        }
+    }
+    if (current.length > 0)
+        out.push(current);
+    return out.length > 0 ? out : [""];
+}
+function wrapBody(body) {
+    const out = [];
+    for (const line of body.split(/\r\n|\r|\n/u)) {
+        for (const wrapped of wrapText(line, PDF_MAX_CHARS))
+            out.push(wrapped);
+    }
+    return out;
+}
+function paginate(lines, perPage) {
+    const pages = [];
+    for (let i = 0; i < lines.length; i += perPage) {
+        pages.push(lines.slice(i, i + perPage));
+    }
+    return pages.length > 0 ? pages : [[""]];
+}
+// Build one page's content stream: position the text cursor, then emit each (escaped, WinAnsi) line.
+function buildPageContent(lines) {
+    const chunks = [
+        pdfStr(`BT\n/F1 ${String(PDF_FONT_SIZE)} Tf\n${String(PDF_LEADING)} TL\n`),
+        pdfStr(`${String(PDF_MARGIN_X)} ${String(PDF_TOP_Y)} Td\n`),
+    ];
+    let first = true;
+    for (const line of lines) {
+        chunks.push(pdfStr(first ? "(" : "T* ("));
+        chunks.push(winAnsiEncode(escapePdf(line)));
+        chunks.push(pdfStr(") Tj\n"));
+        first = false;
+    }
+    chunks.push(pdfStr("ET"));
+    return concatBytes(chunks);
+}
+/**
+ * Assembles a deterministic, multi-page, text-only PDF from the given plain-text body. The entire
+ * body is rendered across as many pages as needed (no truncation). Byte-stable across identical runs.
+ */
+export function assemblePdf(body, runId) {
+    const rawLines = [`Run: ${runId}`, "", ...wrapBody(body)];
+    const pages = paginate(rawLines, PDF_LINES_PER_PAGE);
+    const pageObjNums = pages.map((_, i) => 4 + 2 * i);
+    const maxObjNum = 3 + 2 * pages.length;
+    const objects = [
+        pdfStr("1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n"),
+        pdfStr(`2 0 obj\n<< /Type /Pages /Kids [${pageObjNums.map((n) => `${String(n)} 0 R`).join(" ")}]` +
+            ` /Count ${String(pages.length)} >>\nendobj\n`),
+        pdfStr("3 0 obj\n<< /Type /Font /Subtype /Type1 /BaseFont /Courier" +
+            " /Encoding /WinAnsiEncoding >>\nendobj\n"),
+    ];
+    pages.forEach((pageLines, i) => {
+        const pageNum = 4 + 2 * i;
+        const contentNum = pageNum + 1;
+        objects.push(pdfStr(`${String(pageNum)} 0 obj\n<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595 842]` +
+            ` /Contents ${String(contentNum)} 0 R` +
+            ` /Resources << /Font << /F1 3 0 R >> >> >>\nendobj\n`));
+        const content = buildPageContent(pageLines);
+        objects.push(concatBytes([
+            pdfStr(`${String(contentNum)} 0 obj\n<< /Length ${String(content.length)} >>\nstream\n`),
+            content,
+            pdfStr("\nendstream\nendobj\n"),
+        ]));
+    });
+    const header = pdfStr("%PDF-1.4\n");
+    const offsets = [];
+    let pos = header.length;
+    for (const obj of objects) {
+        offsets.push(pos);
+        pos += obj.length;
+    }
+    const xrefOffset = pos;
+    const xref = buildPdfXref(offsets);
+    const trailer = pdfStr(`trailer\n<< /Size ${String(maxObjNum + 1)} /Root 1 0 R >>\n` +
+        `startxref\n${String(xrefOffset)}\n%%EOF\n`);
+    return concatBytes([header, ...objects, xref, trailer]);
+}
+// Build the PDF cross-reference table for the given object byte-offsets (object 0 is the free head).
+function buildPdfXref(offsets) {
+    const rows = offsets.map((o) => `${String(o).padStart(10, "0")} 00000 n `);
+    const lines = ["xref", `0 ${String(offsets.length + 1)}`, "0000000000 65535 f ", ...rows];
+    return pdfStr(lines.join("\n") + "\n");
+}
+// Concatenate byte chunks into a single buffer.
+function concatBytes(chunks) {
+    const totalLen = chunks.reduce((s, c) => s + c.length, 0);
+    const out = new Uint8Array(totalLen);
+    let pos = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, pos);
+        pos += chunk.length;
+    }
+    return out;
+}

package/dist/qualityIntelligence/exportRoutes.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"exportRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/exportRoutes.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA8NhD,wBAAsB,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CA2BjG;AA+HD,eAAO,MAAM,qBAAqB,EAAE,SAAS,eAAe,EAE3D,CAAC"}