@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/retentionEnforcement.d.ts

@@ -0,0 +1,13 @@
+import { type QualityIntelligenceRunDeletedEvent } from "@oscharko-dev/keiko-evidence";
+export type QiRetentionAuditSink = (event: QualityIntelligenceRunDeletedEvent) => void;
+export interface EnforceQiRetentionOptions {
+    readonly evidenceDir: string;
+    readonly now?: (() => number) | undefined;
+    readonly auditSink?: QiRetentionAuditSink | undefined;
+}
+/**
+ * Run QI run-retention once at server startup. Best-effort: any fault is swallowed so it never
+ * crashes bootstrap. Forwards each deletion receipt's audit event to `auditSink` exactly once.
+ */
+export declare function enforceQiRetentionAtStartup(options: EnforceQiRetentionOptions): void;
+//# sourceMappingURL=retentionEnforcement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retentionEnforcement.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/retentionEnforcement.ts"],"names":[],"mappings":"AAmBA,OAAO,EAEL,KAAK,kCAAkC,EACxC,MAAM,8BAA8B,CAAC;AAOtC,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,kCAAkC,KAAK,IAAI,CAAC;AAQvF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IAE1C,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;CACvD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAgBpF"}

package/dist/qualityIntelligence/retentionEnforcement.js

@@ -0,0 +1,47 @@
+// QI retention-enforcement bootstrap seam (Issue #1323 AC4 — make retention policy ids operational).
+//
+// keiko-evidence ships the pure decision + hardened deletion + the `enforceQualityIntelligenceRetentionPolicy`
+// orchestrator, but it is a LEAF: it never touches the audit ledger (ADR-0019 trust-rule 6). This
+// module is the server-owned wrapper that (a) passes the SAME server-owned companion suffixes + figma
+// snapshot side-file root the user-initiated DELETE route uses (single source of truth in
+// retentionRoutes.ts), and (b) forwards every deletion receipt's audit event to an injectable sink.
+//
+// It is called ONCE per server instance from `buildUiHandlerDeps` (lazy, no timer — a setInterval
+// would race the filesystem-backed store). It is best-effort and CRASH-AWARE: it never throws into
+// bootstrap (mirrors migrateLocalConfigCredentials), so a transient fs fault simply re-runs next start.
+//
+// NOTE (audit visibility): keiko-server has no global persistent QI audit ledger today — the
+// user-initiated DELETE route "forwards" its receipt by returning it in the HTTP response to the
+// caller. The bootstrap purge has no HTTP caller, so the default sink is a no-op: production startup
+// purge receipts are currently DROPPED pending a future audit-ledger wiring (recorded in ADR-0048).
+// The sink is injectable so tests assert forwarding and a future ledger can be wired in one place.
+import { join } from "node:path";
+import { enforceQualityIntelligenceRetentionPolicy, } from "@oscharko-dev/keiko-evidence";
+import { QI_SNAPSHOT_SIDE_FILE_ROOT_SUBDIR, QI_SUBDIR, SERVER_OWNED_COMPANION_SUFFIXES, } from "./retentionRoutes.js";
+// Default sink: drop the event. keiko-server has no global persistent QI audit ledger today (see
+// module note); production startup purge receipts are currently DROPPED pending a future ledger.
+const noopAuditSink = (_event) => {
+    // Intentionally no-op until a persistent QI audit ledger seam exists (ADR-0048 follow-up).
+};
+/**
+ * Run QI run-retention once at server startup. Best-effort: any fault is swallowed so it never
+ * crashes bootstrap. Forwards each deletion receipt's audit event to `auditSink` exactly once.
+ */
+export function enforceQiRetentionAtStartup(options) {
+    const sink = options.auditSink ?? noopAuditSink;
+    try {
+        const { receipts } = enforceQualityIntelligenceRetentionPolicy({
+            evidenceDir: options.evidenceDir,
+            now: options.now,
+            companionSuffixes: SERVER_OWNED_COMPANION_SUFFIXES,
+            sideFileRoot: join(options.evidenceDir, QI_SUBDIR, QI_SNAPSHOT_SIDE_FILE_ROOT_SUBDIR),
+        });
+        for (const receipt of receipts) {
+            sink(receipt.auditEvent);
+        }
+    }
+    catch {
+        // Best-effort bootstrap side-effect: a transient fs fault leaves the store untouched and the
+        // next startup retries. Never propagates into server construction.
+    }
+}

package/dist/qualityIntelligence/retentionRoutes.d.ts

@@ -0,0 +1,8 @@
+import type { RouteContext, RouteResult, RouteDefinition } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+export declare const SERVER_OWNED_COMPANION_SUFFIXES: readonly string[];
+export declare const QI_SUBDIR = "qi";
+export declare const QI_SNAPSHOT_SIDE_FILE_ROOT_SUBDIR = "figma-snapshots";
+export declare function handleQiDeleteRun(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare const QI_RETENTION_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=retentionRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retentionRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/retentionRoutes.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAShD,eAAO,MAAM,+BAA+B,EAAE,SAAS,MAAM,EAM5D,CAAC;AAMF,eAAO,MAAM,SAAS,OAAO,CAAC;AAC9B,eAAO,MAAM,iCAAiC,oBAAoB,CAAC;AAOnE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CA+BrF;AAED,eAAO,MAAM,wBAAwB,EAAE,SAAS,eAAe,EAE9D,CAAC"}

package/dist/qualityIntelligence/retentionRoutes.js

@@ -0,0 +1,74 @@
+// Quality Intelligence run-deletion BFF route (Epic #270, Issue #282 follow-up; ADR-0023 D8).
+//
+//   * DELETE /api/quality-intelligence/runs/:id — delete a run and ALL its local companions
+//
+// ADR-0023 (lines ~487-492) assigns the deletion-control wiring to the consuming epic: a UI/BFF
+// delete action -> `deleteQualityIntelligenceRun` (the hardened keiko-evidence primitive) passing
+// the SERVER-owned `companionSuffixes`. This route is that wiring. It passes EVERY server-owned
+// companion so a deleted run leaves no orphaned customer-derived content (Stop-Condition b:
+// lifecycle must not bypass retention semantics): `.review.json` (reviewer labels + the append-only
+// review audit log, Issue #282), the three figma connector companions, the figma snapshot record,
+// and the figma snapshot side-file directory. `.candidates.json` is evidence-owned and always swept
+// by the primitive. CSRF is enforced by the dispatch layer for mutating methods.
+import { join } from "node:path";
+import { deleteQualityIntelligenceRun, loadQualityIntelligenceRun, } from "@oscharko-dev/keiko-evidence";
+// Companion artifacts written alongside the run manifest under `qi/` that are owned by HIGHER layers
+// (keiko-server), not by keiko-evidence. The primitive ALWAYS sweeps the evidence-owned
+// `.candidates.json`; these must be passed explicitly or a deleted run orphans them. Kept in one
+// place so a new server-owned companion is added here rather than rediscovered per call site.
+// Exported as the SINGLE SOURCE OF TRUTH for server-owned QI companion suffixes so both the
+// user-initiated DELETE route AND the bootstrap retention seam (retentionEnforcement.ts) sweep the
+// identical set — a new server-owned companion is added here once.
+export const SERVER_OWNED_COMPANION_SUFFIXES = [
+    ".review.json", // Issue #282 — reviewer labels + append-only review audit log
+    ".figma-codegen.json", // Epic #750 — figma code-generation companion
+    ".figma-audit.json", // Epic #750 — figma connector audit companion
+    ".figma-consent.json", // Epic #750 — figma consent companion
+    ".figma-snapshot.json", // Epic #750 — figma snapshot record
+];
+// The QI evidence sub-directory and the figma snapshot side-file sub-directory, mirrored from
+// keiko-evidence (`QI_SUBDIR` / `SIDE_FILE_SUBDIR`). `sideFileRoot` lets the primitive remove
+// `<evidenceDir>/qi/figma-snapshots/<runId>/` (binary snapshot side-files) alongside the manifest.
+// Exported for reuse by the bootstrap retention seam (single source of truth).
+export const QI_SUBDIR = "qi";
+export const QI_SNAPSHOT_SIDE_FILE_ROOT_SUBDIR = "figma-snapshots";
+const errorResult = (status, code, message) => ({
+    status,
+    body: { error: { code, message } },
+});
+export function handleQiDeleteRun(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.");
+    }
+    try {
+        // Not-found is an explicit 404 (the primitive itself is idempotent and would report "absent",
+        // but the BFF gives the caller a clear signal that nothing was there to delete).
+        if (loadQualityIntelligenceRun(id, { evidenceDir }) === undefined) {
+            return errorResult(404, "QI_NOT_FOUND", "Quality Intelligence run not found.");
+        }
+        const receipt = deleteQualityIntelligenceRun(id, {
+            evidenceDir,
+            companionSuffixes: SERVER_OWNED_COMPANION_SUFFIXES,
+            sideFileRoot: join(evidenceDir, QI_SUBDIR, QI_SNAPSHOT_SIDE_FILE_ROOT_SUBDIR),
+        });
+        return {
+            status: 200,
+            body: {
+                runId: receipt.runId,
+                status: receipt.status,
+                removedCompanionSuffixes: receipt.removedCompanionSuffixes,
+            },
+        };
+    }
+    catch {
+        return errorResult(500, "QI_DELETE_FAILED", "Failed to delete the Quality Intelligence run.");
+    }
+}
+export const QI_RETENTION_ROUTE_GROUP = [
+    { method: "DELETE", pattern: "/api/quality-intelligence/runs/:id", handler: handleQiDeleteRun },
+];

package/dist/qualityIntelligence/reviewRoutes.d.ts

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

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

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

package/dist/qualityIntelligence/reviewRoutes.js

@@ -0,0 +1,145 @@
+// Quality Intelligence review-action BFF route (Epic #270, Issue #282).
+//
+//   * POST /api/quality-intelligence/runs/:id/review — record a human review decision
+//
+// Applies an explicit, auditable review decision (approve / reject / request-changes / reopen /
+// withdraw) to a run or a single candidate, persisting it to the review companion artifact. Nothing
+// is approved by default; a decision is required to flip state. The route never echoes raw content.
+import { loadQualityIntelligenceRun } from "@oscharko-dev/keiko-evidence";
+import { normaliseCandidateText } from "@oscharko-dev/keiko-quality-intelligence";
+import { applyReviewDecision, QualityIntelligenceReviewTransitionRejected, } from "./reviewStore.js";
+const MAX_BODY_BYTES = 16 * 1024;
+const ACTIONS = new Set([
+    "approve",
+    "reject",
+    "request-changes",
+    "reopen",
+    "withdraw",
+]);
+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 errorResult = (status, code, message) => ({
+    status,
+    body: { error: { code, message } },
+});
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function parseDecision(body) {
+    const action = body.action;
+    if (typeof action !== "string" || !ACTIONS.has(action))
+        return undefined;
+    const candidateId = typeof body.candidateId === "string" ? body.candidateId : undefined;
+    const scope = candidateId !== undefined ? "candidate" : "run";
+    const rawLabel = typeof body.reviewerLabel === "string" ? normaliseCandidateText(body.reviewerLabel) : "";
+    const reviewerLabel = rawLabel.length > 0 ? rawLabel.slice(0, 80) : "reviewer";
+    return {
+        action: action,
+        scope,
+        reviewerLabel,
+        ...(candidateId ? { candidateId } : {}),
+    };
+}
+async function readDecision(req) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch {
+        return {
+            ok: false,
+            result: errorResult(413, "QI_BODY_TOO_LARGE", "Review body is too large."),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "Review body is not valid JSON."),
+        };
+    }
+    if (!isObject(parsed)) {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "Review body must be an object."),
+        };
+    }
+    const decision = parseDecision(parsed);
+    if (decision === undefined) {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_ACTION", "A valid review action is required."),
+        };
+    }
+    return { ok: true, decision };
+}
+export async function handleQiReview(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 readDecision(ctx.req);
+    if (!parsed.ok)
+        return parsed.result;
+    const { decision } = parsed;
+    try {
+        if (loadQualityIntelligenceRun(id, { evidenceDir }) === undefined) {
+            return errorResult(404, "QI_NOT_FOUND", "Quality Intelligence run not found.");
+        }
+        const next = applyReviewDecision({
+            runId: id,
+            evidenceDir,
+            action: decision.action,
+            scope: decision.scope,
+            reviewerLabel: decision.reviewerLabel,
+            now: new Date().toISOString(),
+            redact: deps.redactor,
+            ...(decision.candidateId ? { candidateId: decision.candidateId } : {}),
+        });
+        return {
+            status: 200,
+            body: {
+                runState: next.runState,
+                candidateStates: next.candidateStates,
+                auditCount: next.auditLog.length,
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof QualityIntelligenceReviewTransitionRejected) {
+            return errorResult(409, "QI_REVIEW_TRANSITION_NOT_ALLOWED", `Review transition not permitted: cannot ${error.action} a run/candidate in state "${error.from}".`);
+        }
+        return errorResult(500, "QI_REVIEW_FAILED", "Failed to record the review decision.");
+    }
+}
+export const QI_REVIEW_ROUTE_GROUP = [
+    { method: "POST", pattern: "/api/quality-intelligence/runs/:id/review", handler: handleQiReview },
+];

package/dist/qualityIntelligence/reviewStore.d.ts

@@ -0,0 +1,75 @@
+import { type QualityIntelligence as QI } from "@oscharko-dev/keiko-contracts";
+type ReviewState = QI.QualityIntelligenceReviewState;
+/** Redacts a payload leaf before it is persisted; `deepRedactStrings` preserves string→string. */
+export type ReviewRedactor = (value: unknown) => unknown;
+export declare const QI_REVIEW_SCHEMA_VERSION: 1;
+export type QiReviewAction = "approve" | "reject" | "request-changes" | "reopen" | "withdraw";
+export type QiAuditAction = QiReviewAction | "edit";
+export interface QiReviewAuditEntry {
+    readonly at: string;
+    readonly action: QiAuditAction;
+    readonly scope: "run" | "candidate";
+    readonly candidateId?: string;
+    readonly reviewerLabel: string;
+    readonly fromState: ReviewState;
+    readonly toState: ReviewState;
+}
+export interface QiReviewStateArtifact {
+    readonly qiReviewSchemaVersion: typeof QI_REVIEW_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly runState: ReviewState;
+    readonly candidateStates: Readonly<Record<string, ReviewState>>;
+    readonly auditLog: readonly QiReviewAuditEntry[];
+    readonly lastUpdatedAt: string;
+}
+export declare const loadRunReviewState: (runId: string, evidenceDir: string) => QiReviewStateArtifact | undefined;
+export declare const runReviewStateOf: (artifact: QiReviewStateArtifact | undefined) => ReviewState;
+export declare const candidateReviewStateOf: (artifact: QiReviewStateArtifact | undefined, candidateId: string) => ReviewState;
+/**
+ * Thrown by `applyReviewDecision` when the requested action is not a legal transition from the
+ * current review state. Nothing is persisted and no audit entry is appended — the append-only log
+ * never attests a transition the audited domain declares illegal. The route maps this to a 409.
+ */
+export declare class QualityIntelligenceReviewTransitionRejected extends Error {
+    readonly from: ReviewState;
+    readonly action: QiReviewAction;
+    readonly toState: ReviewState;
+    constructor(from: ReviewState, action: QiReviewAction, toState: ReviewState);
+}
+export interface ApplyReviewDecisionInput {
+    readonly runId: string;
+    readonly evidenceDir: string;
+    readonly action: QiReviewAction;
+    readonly scope: "run" | "candidate";
+    readonly candidateId?: string;
+    readonly reviewerLabel: string;
+    readonly now: string;
+    /** Redacts the reviewer label before it lands in the persisted audit log (Issue #282 FIX M1). */
+    readonly redact: ReviewRedactor;
+}
+/**
+ * Apply a review decision and persist the updated artifact. Validates transition legality first
+ * (FIX A): an illegal transition throws `QualityIntelligenceReviewTransitionRejected` and persists
+ * nothing — no audit entry is ever appended for a rejected transition. On success, appends an
+ * append-only audit entry (with a redacted reviewer label, FIX M1) and returns the new artifact.
+ * The caller is responsible for authorising the action.
+ */
+export declare const applyReviewDecision: (input: ApplyReviewDecisionInput) => QiReviewStateArtifact;
+export interface AppendEditAuditInput {
+    readonly runId: string;
+    readonly evidenceDir: string;
+    readonly candidateId: string;
+    readonly reviewerLabel: string;
+    readonly now: string;
+    /** Redacts the reviewer label before it lands in the persisted audit log (Issue #282 FIX M1). */
+    readonly redact: ReviewRedactor;
+}
+/**
+ * Append an append-only `edit` audit entry for an inline candidate edit. Review state is NOT
+ * transitioned — `fromState`/`toState` are the candidate's existing review state. The reviewer label
+ * is redacted before persist (FIX M1). Persists and returns the updated review artifact (created
+ * empty on first use).
+ */
+export declare const appendEditAudit: (input: AppendEditAuditInput) => QiReviewStateArtifact;
+export {};
+//# sourceMappingURL=reviewStore.d.ts.map

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

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

package/dist/qualityIntelligence/reviewStore.js

@@ -0,0 +1,170 @@
+// Quality Intelligence review-state companion store (Epic #270, Issue #282).
+//
+// The run manifest is immutable evidence; the candidate artifact is the generated body. The MUTABLE
+// human-review/lifecycle decisions (per-candidate + run-level approve / reject / request-changes,
+// plus an append-only audit log) live in a third companion artifact `<runId>.review.json`, managed
+// through the generic contained JSON artifact store from keiko-evidence. Default state is "open" —
+// nothing is approved by default (#282 AC). All reads tolerate a missing artifact.
+import { createNodeContainedJsonArtifactStore, } from "@oscharko-dev/keiko-evidence";
+import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import { QualityIntelligenceReview } from "@oscharko-dev/keiko-quality-intelligence";
+/**
+ * Redact a reviewer label before it lands in the persisted (append-only) audit log. The label is
+ * user-supplied, so a secret-shaped value must be scrubbed at persist time — the `.review.json`
+ * companion otherwise bypasses the QI persist redactor (Issue #282 FIX M1). The live redactor maps
+ * string→string; the non-string fallback keeps the type honest without `any`.
+ */
+const redactLabel = (label, redact) => {
+    const redacted = redact(label);
+    return typeof redacted === "string" ? redacted : label;
+};
+export const QI_REVIEW_SCHEMA_VERSION = 1;
+const REVIEW_SUFFIX = ".review.json";
+const REVIEW_STATES = new Set(QualityIntelligence.QUALITY_INTELLIGENCE_REVIEW_STATES);
+const isReviewState = (value) => typeof value === "string" && REVIEW_STATES.has(value);
+// FIX L1 (Issue #282) — candidate ids are arbitrary strings. Building the candidate-state map over a
+// null-prototype object means a candidate literally named `__proto__` / `constructor` cannot collide
+// with an Object.prototype member (no prototype-pollution, no spurious own-key reads). Behaviour is
+// identical for normal ids.
+const toNullProtoStates = (source) => {
+    const target = Object.create(null);
+    for (const [id, state] of Object.entries(source))
+        target[id] = state;
+    return target;
+};
+const parseArtifact = (value) => {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    if (record.qiReviewSchemaVersion !== QI_REVIEW_SCHEMA_VERSION)
+        return undefined;
+    if (typeof record.runId !== "string" || !isReviewState(record.runState))
+        return undefined;
+    if (typeof record.candidateStates !== "object" || record.candidateStates === null)
+        return undefined;
+    // Rehydrate candidateStates onto a null-proto object so a persisted `__proto__`/`constructor`
+    // candidate id round-trips as an own key rather than the prototype member it was parsed into.
+    const candidateStates = toNullProtoStates(record.candidateStates);
+    return { ...value, candidateStates };
+};
+const storeFor = (evidenceDir) => createNodeContainedJsonArtifactStore(evidenceDir, REVIEW_SUFFIX, { parse: parseArtifact });
+export const loadRunReviewState = (runId, evidenceDir) => storeFor(evidenceDir).load(runId);
+export const runReviewStateOf = (artifact) => artifact?.runState ?? "open";
+export const candidateReviewStateOf = (artifact, candidateId) => {
+    const state = artifact?.candidateStates[candidateId];
+    return isReviewState(state) ? state : "open";
+};
+// ─── Mutation (used by the review-action route, Issue #282) ─────────────────────
+const ACTION_TARGET = {
+    approve: "approved",
+    reject: "rejected",
+    "request-changes": "changes-requested",
+    reopen: "open",
+    withdraw: "withdrawn",
+};
+// FIX A (Issue #282) — legal-transition predicate, resurrecting the audited pure terminal-state
+// check from keiko-quality-intelligence. A transition from `from` via `action` (target `to`) is
+// legal iff:
+//   * to !== from           (reject every no-op, including reopen-from-open), AND
+//   * action === "reopen" OR the source state is not terminal.
+// reopen is the deliberate, audited undo from any non-open state (changes-requested / approved /
+// rejected / withdrawn → open). Every other action (approve / reject / request-changes / withdraw)
+// is legal only from a non-terminal state — this blocks silent illegal flips (approve a rejected,
+// reject an approved) while keeping re-decision possible via an explicit reopen.
+const isLegalTransition = (from, action) => {
+    const to = ACTION_TARGET[action];
+    if (to === from)
+        return false;
+    return action === "reopen" || !QualityIntelligenceReview.isTerminalReviewState(from);
+};
+/**
+ * Thrown by `applyReviewDecision` when the requested action is not a legal transition from the
+ * current review state. Nothing is persisted and no audit entry is appended — the append-only log
+ * never attests a transition the audited domain declares illegal. The route maps this to a 409.
+ */
+export class QualityIntelligenceReviewTransitionRejected extends Error {
+    from;
+    action;
+    toState;
+    constructor(from, action, toState) {
+        super(`Review transition ${from} → ${action} (${toState}) is not permitted.`);
+        this.name = "QualityIntelligenceReviewTransitionRejected";
+        this.from = from;
+        this.action = action;
+        this.toState = toState;
+    }
+}
+const emptyArtifact = (runId, now) => ({
+    qiReviewSchemaVersion: QI_REVIEW_SCHEMA_VERSION,
+    runId,
+    runState: "open",
+    candidateStates: toNullProtoStates({}),
+    auditLog: [],
+    lastUpdatedAt: now,
+});
+/**
+ * Apply a review decision and persist the updated artifact. Validates transition legality first
+ * (FIX A): an illegal transition throws `QualityIntelligenceReviewTransitionRejected` and persists
+ * nothing — no audit entry is ever appended for a rejected transition. On success, appends an
+ * append-only audit entry (with a redacted reviewer label, FIX M1) and returns the new artifact.
+ * The caller is responsible for authorising the action.
+ */
+export const applyReviewDecision = (input) => {
+    const current = loadRunReviewState(input.runId, input.evidenceDir) ?? emptyArtifact(input.runId, input.now);
+    const toState = ACTION_TARGET[input.action];
+    const isCandidate = input.scope === "candidate" && input.candidateId !== undefined;
+    const fromState = isCandidate
+        ? candidateReviewStateOf(current, input.candidateId)
+        : current.runState;
+    if (!isLegalTransition(fromState, input.action)) {
+        throw new QualityIntelligenceReviewTransitionRejected(fromState, input.action, toState);
+    }
+    const candidateStates = isCandidate
+        ? Object.assign(toNullProtoStates(current.candidateStates), { [input.candidateId]: toState })
+        : current.candidateStates;
+    const audit = {
+        at: input.now,
+        action: input.action,
+        scope: input.scope,
+        ...(isCandidate ? { candidateId: input.candidateId } : {}),
+        reviewerLabel: redactLabel(input.reviewerLabel, input.redact),
+        fromState,
+        toState,
+    };
+    const next = {
+        qiReviewSchemaVersion: QI_REVIEW_SCHEMA_VERSION,
+        runId: input.runId,
+        runState: isCandidate ? current.runState : toState,
+        candidateStates,
+        auditLog: [...current.auditLog, audit],
+        lastUpdatedAt: input.now,
+    };
+    storeFor(input.evidenceDir).record(input.runId, next);
+    return next;
+};
+/**
+ * Append an append-only `edit` audit entry for an inline candidate edit. Review state is NOT
+ * transitioned — `fromState`/`toState` are the candidate's existing review state. The reviewer label
+ * is redacted before persist (FIX M1). Persists and returns the updated review artifact (created
+ * empty on first use).
+ */
+export const appendEditAudit = (input) => {
+    const current = loadRunReviewState(input.runId, input.evidenceDir) ?? emptyArtifact(input.runId, input.now);
+    const state = candidateReviewStateOf(current, input.candidateId);
+    const audit = {
+        at: input.now,
+        action: "edit",
+        scope: "candidate",
+        candidateId: input.candidateId,
+        reviewerLabel: redactLabel(input.reviewerLabel, input.redact),
+        fromState: state,
+        toState: state,
+    };
+    const next = {
+        ...current,
+        auditLog: [...current.auditLog, audit],
+        lastUpdatedAt: input.now,
+    };
+    storeFor(input.evidenceDir).record(input.runId, next);
+    return next;
+};

package/dist/qualityIntelligence/runExecution.d.ts

@@ -0,0 +1,36 @@
+import { type QualityIntelligence as QI } from "@oscharko-dev/keiko-contracts";
+import { type QualityIntelligenceRunSummary } from "@oscharko-dev/keiko-workflows";
+import type { QualityIntelligenceStartRunRequest } from "@oscharko-dev/keiko-contracts";
+import { type UiHandlerDeps } from "../deps.js";
+import { QiIngestionError } from "./runIngestion.js";
+import type { QiSkippedSource } from "./runIngestion.js";
+import { QiGenerationError } from "./generationPort.js";
+export interface QiRunAccepted {
+    readonly runId: string;
+    readonly requestedAt: string;
+    readonly sourceCount: number;
+    readonly atomCount: number;
+    readonly modelId?: string | undefined;
+    /** Sources dropped because the request exceeded the 16-source cap (Epic #729). */
+    readonly droppedSourceCount: number;
+    /** Connected sources skipped because they ingested to nothing usable (Epic #729 N+1 resilience). */
+    readonly skippedSources: readonly QiSkippedSource[];
+}
+export interface ExecuteQiRunInput {
+    readonly request: QualityIntelligenceStartRunRequest;
+    readonly runId: string;
+    readonly deps: UiHandlerDeps;
+    readonly registeredAt: string;
+    readonly signal: AbortSignal;
+    readonly onEvent: (event: QI.QualityIntelligenceRunEvent) => void;
+    readonly onAccepted: (accepted: QiRunAccepted) => void;
+}
+/**
+ * Execute a QI run end to end. Throws `QiIngestionError` / `QiGenerationError` (safe, coded) when
+ * the request cannot start; otherwise returns the run summary after the workflow reaches a terminal
+ * state. `onAccepted` fires once, after ingestion + model/judge resolution succeed and before
+ * generation.
+ */
+export declare function executeQiRun(input: ExecuteQiRunInput): Promise<QualityIntelligenceRunSummary>;
+export { QiIngestionError, QiGenerationError };
+//# sourceMappingURL=runExecution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runExecution.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runExecution.ts"],"names":[],"mappings":"AASA,OAAO,EAAuB,KAAK,mBAAmB,IAAI,EAAE,EAAE,MAAM,+BAA+B,CAAC;AAUpG,OAAO,EAEL,KAAK,6BAA6B,EAEnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,+BAA+B,CAAC;AACxF,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAA4B,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EAA0B,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAqBhF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,kFAAkF;IAClF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,oGAAoG;IACpG,QAAQ,CAAC,cAAc,EAAE,SAAS,eAAe,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,kCAAkC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,2BAA2B,KAAK,IAAI,CAAC;IAClE,QAAQ,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;CACxD;AAmED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,6BAA6B,CAAC,CAaxC;AAwGD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,CAAC"}