@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/runExecution.js

@@ -0,0 +1,180 @@
+// Quality Intelligence run execution orchestrator (Epic #270, Issue #273/#278/#279/#280).
+//
+// The single seam that turns a validated start-run request into a completed, persisted QI run:
+// ingest sources → resolve a test-design generation strategy (structured model, chat-only model, or
+// deterministic no-model baseline) → build the generation port → run the model-routed test-design
+// workflow (which emits the QI run-event envelope, validates, and persists the manifest + candidate
+// artifact). Route-agnostic: the caller supplies an event callback (wired to SSE) and an
+// AbortSignal (wired to the run registry for cancellation).
+import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import { ALL_POLICY_PROFILES, regressionDefault, } from "@oscharko-dev/keiko-quality-intelligence";
+import { createNodeQualityIntelligenceLocalStore, recordQualityIntelligenceCandidates, } from "@oscharko-dev/keiko-evidence";
+import { runQualityIntelligenceModelRoutedTestDesign, } from "@oscharko-dev/keiko-workflows";
+import { currentRedactionSecrets } from "../deps.js";
+import { ingestInlineSourcesAsync, QiIngestionError } from "./runIngestion.js";
+import { makeCapsuleResolver } from "./capsuleAdapter.js";
+import { makeFigmaSnapshotLoader, makeFigmaVisionHintProvider } from "./figmaSnapshotAdapter.js";
+import { createQiGenerationPort, QiGenerationError } from "./generationPort.js";
+import { createQiJudgePort, QiJudgeError } from "./judgePort.js";
+import { resolveModelForQiCapability, resolveQiTestDesignSelection } from "./modelSelection.js";
+// Mirrors the stages the model-routed workflow actually emits (descriptors.ts stageNames), so the
+// run plan the UI renders matches the live stage:started/completed events — including the
+// adversarial test-quality judge (Epic #736).
+const PLAN_STAGES = Object.freeze([
+    { name: "plan", descriptor: "qi:plan" },
+    { name: "candidates", descriptor: "qi:model-generate" },
+    { name: "judge", descriptor: "qi:judge" },
+    { name: "coverage", descriptor: "qi:coverage" },
+    { name: "validate", descriptor: "qi:validate" },
+    { name: "finalize", descriptor: "qi:finalize" },
+]);
+function resolveProfile(profileId) {
+    if (profileId === undefined || profileId.trim().length === 0)
+        return regressionDefault;
+    return ALL_POLICY_PROFILES.find((p) => p.id === profileId) ?? regressionDefault;
+}
+function resolveExecutionStrategy(deps, request) {
+    const selection = resolveQiTestDesignSelection(deps, request.modelId);
+    // Seeded runs without an explicit model are release evidence. If automatic routing would pick a
+    // model that cannot apply the seed, prefer the deterministic structural baseline over
+    // nondeterministic model/judge augmentation. Explicit model requests keep their existing
+    // attribution contract and persist `seedUsed: null` when the model cannot apply the seed.
+    if (request.modelId === undefined &&
+        request.seed !== undefined &&
+        (selection.kind === "baseline" || selection.capability.supportsSeeding !== true)) {
+        return {
+            generate: createQiGenerationPort(deps, { kind: "baseline" }),
+        };
+    }
+    if (selection.kind === "model") {
+        return {
+            modelId: selection.modelId,
+            generate: createQiGenerationPort(deps, {
+                kind: "model",
+                modelId: selection.modelId,
+                requestedSeed: request.seed,
+            }),
+        };
+    }
+    return {
+        generate: createQiGenerationPort(deps, { kind: "baseline" }),
+    };
+}
+function buildAccepted(input, ingestion, modelId) {
+    return {
+        runId: input.runId,
+        requestedAt: input.registeredAt,
+        sourceCount: ingestion.sourceSummaries.length,
+        atomCount: ingestion.ingestedAtoms.length,
+        ...(modelId !== undefined ? { modelId } : {}),
+        droppedSourceCount: ingestion.droppedSourceCount,
+        skippedSources: ingestion.skippedSources,
+    };
+}
+function buildRunPlan(input) {
+    return {
+        id: QualityIntelligence.asQualityIntelligenceRunId(input.runId),
+        requestedAt: input.registeredAt,
+        plannerKind: "model-routed",
+        stages: PLAN_STAGES,
+    };
+}
+/**
+ * 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 async function executeQiRun(input) {
+    const evidenceDir = input.deps.evidenceDir;
+    if (evidenceDir === undefined) {
+        throw new QiGenerationError("QI_NO_EVIDENCE_DIR", "The evidence directory is not configured.");
+    }
+    // The capsule resolver owns a SQLite handle; close it in a finally so a thrown ingestion/generation
+    // never leaks it. The run body is extracted so this entrypoint stays within the line budget.
+    const capsuleResolver = makeCapsuleResolver(input.deps);
+    try {
+        return await runResolvedQi(input, evidenceDir, capsuleResolver);
+    }
+    finally {
+        capsuleResolver?.close();
+    }
+}
+async function runResolvedQi(input, evidenceDir, capsuleResolver) {
+    const { deps, runId, request } = input;
+    let ingestionModelGatewayCallCount = 0;
+    const ingestion = await ingestInlineSourcesAsync({
+        request,
+        runId,
+        registeredAt: input.registeredAt,
+        capsuleResolver,
+        figmaSnapshotLoader: makeFigmaSnapshotLoader(deps),
+        figmaVision: makeFigmaVisionHintProvider(deps, undefined, {
+            onGatewayCallAttempt: () => {
+                ingestionModelGatewayCallCount += 1;
+            },
+        }),
+    });
+    const { modelId, generate } = resolveExecutionStrategy(deps, request);
+    const judge = buildJudgePortForModelRun(deps, modelId, request.modelId);
+    const profile = resolveProfile(request.profileId);
+    input.onAccepted(buildAccepted(input, ingestion, modelId));
+    return await runQualityIntelligenceModelRoutedTestDesign({
+        plan: buildRunPlan(input),
+        envelopes: ingestion.envelopes,
+        ingestedAtoms: ingestion.ingestedAtoms,
+        provenanceRefs: ingestion.provenanceRefs,
+        profile,
+    }, buildWorkflowDeps({
+        deps,
+        runId,
+        evidenceDir,
+        modelId,
+        initialModelGatewayCallCount: ingestionModelGatewayCallCount,
+        generate,
+        judge,
+        onEvent: input.onEvent,
+        signal: input.signal,
+    }));
+}
+function buildJudgePortForModelRun(deps, modelId, requestedModelId) {
+    if (modelId === undefined)
+        return undefined;
+    const judgeSelection = resolveModelForQiCapability(deps, "qi:judge-logic", requestedModelId);
+    if (judgeSelection.kind === "unavailable")
+        return undefined;
+    try {
+        return createQiJudgePort(deps, judgeSelection.modelId);
+    }
+    catch (error) {
+        if (error instanceof QiJudgeError) {
+            throw new QiGenerationError(error.code, error.message);
+        }
+        throw error;
+    }
+}
+function buildWorkflowDeps(args) {
+    const { runId, evidenceDir } = args;
+    const redact = args.deps.redactor;
+    return {
+        sink: { emit: args.onEvent },
+        evidenceStore: createNodeQualityIntelligenceLocalStore(evidenceDir),
+        initialModelGatewayCallCount: args.initialModelGatewayCallCount,
+        candidatesSink: {
+            record: (candidates, generatedAt) => {
+                recordQualityIntelligenceCandidates({
+                    runId,
+                    generatedAt,
+                    candidates,
+                    evidenceDir,
+                    redact,
+                });
+            },
+        },
+        generate: args.generate,
+        judge: args.judge,
+        redaction: { additionalSecrets: currentRedactionSecrets(args.deps) },
+        signal: args.signal,
+    };
+}
+export { QiIngestionError, QiGenerationError };

package/dist/qualityIntelligence/runIngestion.d.ts

@@ -0,0 +1,70 @@
+import { type QualityIntelligence as QI } from "@oscharko-dev/keiko-contracts";
+import type { QualityIntelligenceIngestedAtom } from "@oscharko-dev/keiko-workflows";
+import type { QualityIntelligenceInlineSource, QualityIntelligenceStartRunRequest } from "@oscharko-dev/keiko-contracts";
+import type { CapsuleResolver } from "./capsuleAdapter.js";
+import type { FigmaSnapshotLoader, FigmaVisionHintProvider } from "./figmaSnapshotAdapter.js";
+export declare class QiIngestionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface QiSourceSummary {
+    readonly label: string;
+    readonly kind: QualityIntelligenceInlineSource["kind"];
+    readonly atomCount: number;
+}
+/**
+ * A connected source that could not be ingested (empty, denied, binary, unavailable capsule, …) and
+ * was SKIPPED so the remaining sources still produce a run (Epic #729 N+1 resilience / Chat parity).
+ * Carries only a sanitised label + the safe coded reason — never source content. The run still fails
+ * (re-raising the first coded error) when EVERY source is skipped.
+ */
+export interface QiSkippedSource {
+    readonly label: string;
+    readonly kind: QualityIntelligenceInlineSource["kind"];
+    readonly code: string;
+    readonly message: string;
+}
+export interface QiIngestionResult {
+    readonly envelopes: readonly QI.QualityIntelligenceSourceEnvelope[];
+    readonly ingestedAtoms: readonly QualityIntelligenceIngestedAtom[];
+    readonly provenanceRefs: {
+        readonly envelopeIds: readonly string[];
+        readonly auditSummaryId: QI.QualityIntelligenceAuditSummaryId;
+    };
+    readonly sourceSummaries: readonly QiSourceSummary[];
+    /** Number of sources dropped because the request exceeded MAX_QI_SOURCES (Epic #729). */
+    readonly droppedSourceCount: number;
+    /**
+     * Sources that ingested to nothing usable and were skipped (a subset of the connected sources),
+     * so the healthy sources still produced the run (Epic #729 N+1 resilience). Empty on the happy path.
+     */
+    readonly skippedSources: readonly QiSkippedSource[];
+}
+export declare const envelopeIdFor: (index: number, label: string, content: string) => QI.QualityIntelligenceSourceEnvelopeId;
+export interface IngestInlineSourcesInput {
+    readonly request: QualityIntelligenceStartRunRequest;
+    readonly runId: string;
+    readonly registeredAt: string;
+    /**
+     * Drift-only mode: an existing run whose current source is now empty must still be comparable so all
+     * old candidates classify as orphaned-stale. Initial run creation keeps the strict non-empty guard.
+     */
+    readonly allowEmpty?: boolean | undefined;
+    /** Optional capsule resolver (Epic #710, Issue #717). Absent → capsule sources throw QI_CAPSULE_UNAVAILABLE. */
+    readonly capsuleResolver?: CapsuleResolver | undefined;
+    /**
+     * Optional Figma-snapshot loader (Epic #750, Issue #754). Absent → figma-snapshot sources throw
+     * QI_FIGMA_SNAPSHOT_UNAVAILABLE. Reads ONLY the stored snapshot; never contacts Figma.
+     */
+    readonly figmaSnapshotLoader?: FigmaSnapshotLoader | undefined;
+    /**
+     * Optional capability-routed image-input provider (Issue #754/#810). For figma-snapshot sources
+     * hints are additive and never override the deterministic structural baseline. For pure image
+     * sources the same provider must produce the textual image description; absent/empty output makes
+     * that image source unavailable instead of pretending a text-only model saw the screenshot.
+     */
+    readonly figmaVision?: FigmaVisionHintProvider | undefined;
+}
+export declare function ingestInlineSources(input: IngestInlineSourcesInput): QiIngestionResult;
+export declare function ingestInlineSourcesAsync(input: IngestInlineSourcesInput): Promise<QiIngestionResult>;
+//# sourceMappingURL=runIngestion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runIngestion.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runIngestion.ts"],"names":[],"mappings":"AAUA,OAAO,EAAuB,KAAK,mBAAmB,IAAI,EAAE,EAAE,MAAM,+BAA+B,CAAC;AAuBpG,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AACrF,OAAO,KAAK,EACV,+BAA+B,EAC/B,kCAAkC,EACnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AA4C9F,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,IAAI,EAAE,MAAM,CAAC;gBACjB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC,MAAM,CAAC,CAAC;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC,MAAM,CAAC,CAAC;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,iCAAiC,EAAE,CAAC;IACpE,QAAQ,CAAC,aAAa,EAAE,SAAS,+BAA+B,EAAE,CAAC;IACnE,QAAQ,CAAC,cAAc,EAAE;QACvB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC,iCAAiC,CAAC;KAC/D,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE,SAAS,eAAe,EAAE,CAAC;IACrD,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,eAAe,EAAE,CAAC;CACrD;AAuHD,eAAO,MAAM,aAAa,GACxB,OAAO,MAAM,EACb,OAAO,MAAM,EACb,SAAS,MAAM,KACd,EAAE,CAAC,mCAKL,CAAC;AA+0CF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,kCAAkC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,gHAAgH;IAChH,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC/D;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC;CAC5D;AA8ID,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,iBAAiB,CAmDtF;AAED,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAyC5B"}