@oscharko-dev/keiko-workflows 0.2.0

package/dist/promptEnhancer/index.js

@@ -0,0 +1,282 @@
+// Prompt Enhancer workflow authority (Epic #1307, Issue #1314; ADR-0044 §1/§3/§4).
+//
+// This module owns the governed `analyze → plan → optimize → validate → evidence-record-input`
+// lifecycle. It composes the deterministic, provider-neutral primitives shipped by #1309–#1313 into a
+// single content-light wire response. The core run remains pure apart from SHA-256 hashing; callers
+// that persist evidence supply the clock and store at their boundary.
+//
+// Model-Gateway routing (AC3). The enhancer never calls a live model — every primitive is
+// deterministic and the Enhanced Prompt is provider-neutral. The optional `modelId` the caller intends
+// to dispatch the result to downstream is resolved against the Model-Gateway config (a configured
+// provider check); when no gateway config is present or the model is not a configured provider, the
+// result still succeeds and `modelRouting` reports the degraded state (graceful handling). The enhancer
+// itself is never blocked by an unavailable model.
+import { analyzePrompt, asEnhancedPromptId, asPromptEnhancementRequestId, normalizePromptDraft, validatePromptEnhancementRequest, PROMPT_ENHANCEMENT_DEFAULT_CANDIDATE_COUNT, PROMPT_ENHANCER_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts";
+import { findConfiguredCapability, PromptEnhancer, } from "@oscharko-dev/keiko-model-gateway";
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+// Thrown when the (server-built) domain request fails the #1309 structural validator. Carries only the
+// deterministic, content-free validator messages (they never echo raw user input). The route maps it
+// to a 400. Distinct from the wire-request validator so the route can report the originating gate.
+export class PromptEnhancementInputError extends Error {
+    errors;
+    constructor(errors) {
+        super("Prompt enhancement request failed domain validation.");
+        this.name = "PromptEnhancementInputError";
+        this.errors = errors;
+    }
+}
+// Thrown when the caller disconnects before the enhancement completes. Carries no payload; the route
+// maps it to a 499 (client closed request). Lets the deterministic pipeline cooperate with cancellation
+// even though it never blocks on a model (AC: cancellation).
+export class PromptEnhancementCancelledError extends Error {
+    constructor() {
+        super("Prompt enhancement request was cancelled.");
+        this.name = "PromptEnhancementCancelledError";
+    }
+}
+export function promptEnhancementGatewayRoutingConfig(config) {
+    if (config === undefined) {
+        return undefined;
+    }
+    return {
+        providers: config.providers.map((provider) => ({ modelId: provider.modelId })),
+        ...(config.capabilities === undefined ? {} : { capabilities: config.capabilities }),
+    };
+}
+const throwIfCancelled = (signal) => {
+    if (signal?.aborted === true) {
+        throw new PromptEnhancementCancelledError();
+    }
+};
+// Clamp the requested candidate count into [1, gateway MAX_CANDIDATE_COUNT]. The wire validator already
+// bounded the value to [1, PROMPT_ENHANCEMENT_MAX_CANDIDATE_COUNT]; this additionally honors the
+// gateway's own bound so the surface can never widen the optimization envelope.
+const clampCandidateCount = (requested) => {
+    const base = requested === undefined || !Number.isInteger(requested) || requested < 1
+        ? PROMPT_ENHANCEMENT_DEFAULT_CANDIDATE_COUNT
+        : requested;
+    return Math.min(base, PromptEnhancer.MAX_CANDIDATE_COUNT);
+};
+// A stable, content-free request id derived from the normalized draft + the request shaping options. A
+// hash keeps the pipeline deterministic (identical request → identical id) and never embeds raw input,
+// a path-traversal fragment, or a control character, so it passes the branded-id validator.
+const deriveRequestId = (normalized, missingInformationStrategy, profilePreference, locale, hasConnectedContext, attachmentCount) => `pe-req-${sha256Hex([
+    normalized,
+    missingInformationStrategy,
+    profilePreference,
+    locale,
+    hasConnectedContext === undefined ? "" : String(hasConnectedContext),
+    attachmentCount === undefined ? "" : String(attachmentCount),
+].join("\u0000")).slice(0, 48)}`;
+const resolveModelRouting = (request, config) => {
+    const requestedModelId = request.modelId;
+    if (requestedModelId === undefined) {
+        return { availability: "not-requested", reason: "no-model-requested" };
+    }
+    if (config === undefined) {
+        return { availability: "unavailable", reason: "no-gateway-config", requestedModelId };
+    }
+    const isConfiguredProvider = config.providers.some((provider) => provider.modelId === requestedModelId);
+    if (!isConfiguredProvider) {
+        return { availability: "unavailable", reason: "model-not-configured", requestedModelId };
+    }
+    const resolved = findConfiguredCapability(config, requestedModelId);
+    if (resolved?.kind !== "chat") {
+        return { availability: "unavailable", reason: "model-not-chat-capable", requestedModelId };
+    }
+    return {
+        availability: "available",
+        reason: "model-available",
+        requestedModelId,
+        resolvedModelId: requestedModelId,
+        costClass: resolved.costClass,
+    };
+};
+const resolveGroundingReadiness = (request, required) => {
+    if (!required) {
+        return { status: "not-required", reason: "no-grounding-required" };
+    }
+    if (request.hasConnectedContext === true || (request.attachmentCount ?? 0) > 0) {
+        return { status: "ready", reason: "connected-context-present" };
+    }
+    return {
+        status: "unavailable",
+        reason: "missing-concrete-scope",
+        notice: "This prompt requires grounding, but no connected workspace scope or attachment was supplied.",
+    };
+};
+const NOT_RECORDED_EVIDENCE = {
+    status: "not-recorded",
+    reason: "evidence-store-not-configured",
+};
+const NO_SCORED_CANDIDATE_ERROR_MESSAGE = "Prompt candidate optimization produced no scored candidate.";
+// Normalize + guard the draft, mint the branded ids, build and re-validate the domain request, and run
+// the deterministic analyzer. Throws PromptEnhancementInputError on an empty draft or domain-validation
+// failure. Factored out of runPromptEnhancement to keep each function within the complexity/size bounds.
+function prepareEnhancement(request) {
+    const missingInformationStrategy = request.missingInformationStrategy ?? "clarify";
+    const normalized = normalizePromptDraft(request.text);
+    // Self-contained guard so the reusable orchestrator never analyzes an empty draft even if a future
+    // caller skips the wire validator. A draft empty after control-stripping + NFKC carries no signal.
+    if (normalized.trim().length === 0) {
+        throw new PromptEnhancementInputError(["request text must not be empty after normalization"]);
+    }
+    const inputFingerprintSha256 = sha256Hex(normalized);
+    const requestId = asPromptEnhancementRequestId(deriveRequestId(normalized, missingInformationStrategy, request.profilePreference ?? "", request.locale ?? "", request.hasConnectedContext, request.attachmentCount));
+    const input = {
+        text: request.text,
+        ...(request.hasConnectedContext === undefined
+            ? {}
+            : { hasConnectedContext: request.hasConnectedContext }),
+        ...(request.attachmentCount === undefined ? {} : { attachmentCount: request.attachmentCount }),
+    };
+    const domainRequest = {
+        schemaVersion: PROMPT_ENHANCER_SCHEMA_VERSION,
+        requestId,
+        input,
+        missingInformationStrategy,
+        ...(request.profilePreference === undefined
+            ? {}
+            : { profilePreference: request.profilePreference }),
+        ...(request.locale === undefined ? {} : { locale: request.locale }),
+    };
+    const validation = validatePromptEnhancementRequest(domainRequest);
+    if (!validation.ok) {
+        throw new PromptEnhancementInputError(validation.errors);
+    }
+    return { analysis: analyzePrompt(validation.value), input, inputFingerprintSha256 };
+}
+const isNoScoredCandidateError = (error) => error instanceof Error && error.message === NO_SCORED_CANDIDATE_ERROR_MESSAGE;
+function buildRejectedFailSafeSelection(prepared, request, originalError) {
+    const { analysis, input } = prepared;
+    const plan = PromptEnhancer.planPromptEnhancement(analysis, {
+        ...(request.profilePreference === undefined
+            ? {}
+            : { profilePreference: request.profilePreference }),
+    });
+    const candidateId = asEnhancedPromptId(`${analysis.requestId}-safety-fail-safe`);
+    const prompt = PromptEnhancer.generateEnhancedPrompt({
+        promptId: candidateId,
+        analysis,
+        plan,
+        input,
+    });
+    const scorecard = PromptEnhancer.scorePromptCandidate({
+        candidateId,
+        profile: plan.selectedProfile,
+        prompt,
+        plan,
+        analysis,
+    });
+    const safety = PromptEnhancer.assessPromptSafety({ prompt, analysis, input });
+    if (safety.decision !== "rejected") {
+        throw originalError;
+    }
+    return {
+        winner: scorecard,
+        ranked: [scorecard],
+        rankedPrompts: [prompt],
+        winnerSafetyAssessment: safety,
+        rejected: [],
+    };
+}
+function selectPromptCandidate(prepared, request) {
+    const { analysis, input } = prepared;
+    try {
+        return PromptEnhancer.optimizePromptCandidates({
+            analysis,
+            input,
+            bounds: { candidateCount: clampCandidateCount(request.candidateCount) },
+            ...(request.profilePreference === undefined
+                ? {}
+                : { profilePreference: request.profilePreference }),
+        });
+    }
+    catch (error) {
+        if (!isNoScoredCandidateError(error)) {
+            throw error;
+        }
+        return buildRejectedFailSafeSelection(prepared, request, error);
+    }
+}
+export function runPromptEnhancement(request, deps) {
+    throwIfCancelled(deps.signal);
+    const prepared = prepareEnhancement(request);
+    const { analysis, inputFingerprintSha256 } = prepared;
+    throwIfCancelled(deps.signal);
+    const selection = selectPromptCandidate(prepared, request);
+    throwIfCancelled(deps.signal);
+    const enhancedPrompt = selection.rankedPrompts[0];
+    if (enhancedPrompt === undefined) {
+        throw new Error("Prompt enhancement optimization produced no prompt.");
+    }
+    const renderedPrompt = PromptEnhancer.renderEnhancedPromptText(enhancedPrompt);
+    return {
+        schemaVersion: PROMPT_ENHANCER_SCHEMA_VERSION,
+        promptId: enhancedPrompt.promptId,
+        inputFingerprintSha256,
+        analysis,
+        enhancedPrompt,
+        renderedPrompt,
+        candidates: {
+            winnerCandidateId: selection.winner.candidateId,
+            scorecards: selection.ranked,
+            rejected: selection.rejected,
+        },
+        safety: selection.winnerSafetyAssessment,
+        modelRouting: resolveModelRouting(request, deps.gatewayRoutingConfig),
+        groundingReadiness: resolveGroundingReadiness(request, enhancedPrompt.groundingPlan.required),
+        evidence: NOT_RECORDED_EVIDENCE,
+    };
+}
+function evidenceStatus(decision) {
+    if (decision === "accepted")
+        return "validated";
+    if (decision === "rejected")
+        return "rejected";
+    return "requires-human-review";
+}
+function evidenceCandidateRows(candidates) {
+    return candidates.scorecards.map((scorecard) => ({
+        candidateId: scorecard.candidateId,
+        profile: scorecard.profile,
+        aggregateScore: scorecard.aggregateScore,
+        estimatedTokens: scorecard.estimatedTokens,
+        selected: scorecard.candidateId === candidates.winnerCandidateId,
+    }));
+}
+function evidenceModelMetadata(routing, winnerProfile) {
+    return {
+        deterministic: true,
+        ...(routing.resolvedModelId === undefined ? {} : { modelId: routing.resolvedModelId }),
+        ...(winnerProfile === undefined ? {} : { profile: winnerProfile }),
+    };
+}
+function runIdForEvidence(result, recordedAt) {
+    return `pe-run-${sha256Hex([result.analysis.requestId, result.promptId, result.inputFingerprintSha256, recordedAt].join("\u0000")).slice(0, 32)}`;
+}
+export function buildPromptEnhancementRecordInput(options) {
+    const { rawInput, result, recordedAt } = options;
+    const winnerProfile = result.candidates.scorecards.find((scorecard) => scorecard.candidateId === result.candidates.winnerCandidateId)?.profile;
+    return {
+        runId: runIdForEvidence(result, recordedAt),
+        recordedAt,
+        requestId: result.analysis.requestId,
+        status: evidenceStatus(result.safety.decision),
+        originalInput: rawInput,
+        enhancedPromptId: result.promptId,
+        enhancedPromptText: result.renderedPrompt,
+        appliedSafetyRules: result.enhancedPrompt.safetyRules,
+        appliedGroundingDirectives: result.enhancedPrompt.groundingPlan.directives,
+        assumptions: result.analysis.missingContext.flatMap((item) => item.kind === "assumption" ? [item.statement] : []),
+        candidateScores: evidenceCandidateRows(result.candidates),
+        safety: {
+            decision: result.safety.decision,
+            verificationStatus: result.safety.verificationStatus,
+            requiresHumanReview: result.safety.requiresHumanReview,
+            findingCodes: result.safety.findings.map((finding) => finding.code),
+            leastPrivilege: result.safety.leastPrivilege,
+        },
+        modelMetadata: evidenceModelMetadata(result.modelRouting, winnerProfile),
+    };
+}

package/dist/qualityIntelligence/__tests__/fixtures/runEntryFixtures.d.ts

@@ -0,0 +1,30 @@
+import { type QualityIntelligence as QI } from "@oscharko-dev/keiko-contracts";
+import { createInMemoryQualityIntelligenceLocalStore, type QualityIntelligenceEvidenceManifest, type QualityIntelligenceLocalStore } from "@oscharko-dev/keiko-evidence";
+import type { QualityIntelligenceClock, QualityIntelligenceRunEventSink } from "../../runtimeCommon.js";
+import type { QualityIntelligenceModelRoutedTestDesignDeps } from "../../modelRoutedTestDesign.js";
+export declare const CLOCK: QualityIntelligenceClock;
+export declare const PROVENANCE: {
+    readonly envelopeIds: readonly ["env-1"];
+    readonly auditSummaryId: QualityIntelligenceEvidenceManifest["provenanceRefs"]["auditSummaryId"];
+};
+export declare const ENVELOPE: QI.QualityIntelligenceSourceEnvelope;
+export declare function makePlan(id: string): QI.QualityIntelligenceRunPlan;
+export declare function makeAtom(id: string): QI.QualityIntelligenceEvidenceAtom;
+export declare function ingestedAtomsFixture(): readonly {
+    atom: QI.QualityIntelligenceEvidenceAtom;
+    canonicalText: string;
+}[];
+export declare function candidatesFor(runId: string, atoms: readonly QI.QualityIntelligenceEvidenceAtom[]): readonly QI.QualityIntelligenceTestCaseCandidate[];
+export interface RecordingSink {
+    readonly sink: QualityIntelligenceRunEventSink;
+    readonly events: () => readonly QI.QualityIntelligenceRunEvent[];
+    readonly kinds: () => readonly string[];
+    readonly stageNames: () => readonly string[];
+    /** Ordered "kind" / "kind:stageName" tokens — the human-readable lifecycle trace. */
+    readonly trace: () => readonly string[];
+}
+export declare function recordingSink(): RecordingSink;
+export declare const MODEL_OUTPUT_TWO: string;
+export declare function modelRoutedDeps(store: QualityIntelligenceLocalStore, sink: QualityIntelligenceRunEventSink): QualityIntelligenceModelRoutedTestDesignDeps;
+export { createInMemoryQualityIntelligenceLocalStore };
+//# sourceMappingURL=runEntryFixtures.d.ts.map

package/dist/qualityIntelligence/__tests__/fixtures/runEntryFixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runEntryFixtures.d.ts","sourceRoot":"","sources":["../../../../src/qualityIntelligence/__tests__/fixtures/runEntryFixtures.ts"],"names":[],"mappings":"AAOA,OAAO,EAAuB,KAAK,mBAAmB,IAAI,EAAE,EAAE,MAAM,+BAA+B,CAAC;AACpG,OAAO,EACL,2CAA2C,EAC3C,KAAK,mCAAmC,EACxC,KAAK,6BAA6B,EACnC,MAAM,8BAA8B,CAAC;AAMtC,OAAO,KAAK,EACV,wBAAwB,EACxB,+BAA+B,EAChC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,4CAA4C,EAAE,MAAM,gCAAgC,CAAC;AAGnG,eAAO,MAAM,KAAK,EAAE,wBAElB,CAAC;AAEH,eAAO,MAAM,UAAU;;6BAGC,mCAAmC,CAAC,gBAAgB,CAAC,CAAC,gBAAgB,CAAC;CACrF,CAAC;AAEX,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,iCAUxB,CAAC;AAEH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,CAAC,0BAA0B,CAOlE;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,CAAC,+BAA+B,CASvE;AAED,wBAAgB,oBAAoB,IAAI,SAAS;IAC/C,IAAI,EAAE,EAAE,CAAC,+BAA+B,CAAC;IACzC,aAAa,EAAE,MAAM,CAAC;CACvB,EAAE,CAQF;AAID,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,EAAE,CAAC,+BAA+B,EAAE,GACnD,SAAS,EAAE,CAAC,oCAAoC,EAAE,CAQpD;AAGD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,SAAS,EAAE,CAAC,2BAA2B,EAAE,CAAC;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAC7C,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,wBAAgB,aAAa,IAAI,aAAa,CAoB7C;AAID,eAAO,MAAM,gBAAgB,QAiB3B,CAAC;AAEH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,6BAA6B,EACpC,IAAI,EAAE,+BAA+B,GACpC,4CAA4C,CAW9C;AAED,OAAO,EAAE,2CAA2C,EAAE,CAAC"}

package/dist/qualityIntelligence/__tests__/fixtures/runEntryFixtures.js

@@ -0,0 +1,114 @@
+// Shared fixtures + harness for the QI run-entry regression suite (Epic #270, Issue #273).
+//
+// Mirrors the captureSink / PLAN / PROVENANCE shapes used by runLifecycleCancellation.test.ts and
+// modelRoutedTestDesign.test.ts so the new lifecycle / contract / cancellation tests reuse one
+// canonical set of fixtures instead of reinventing per file. NOTE: this file is a TEST helper, not
+// package source — it is intentionally NOT exported from any package index.ts.
+import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import { createInMemoryQualityIntelligenceLocalStore, } from "@oscharko-dev/keiko-evidence";
+import { deriveIntent, designTestCaseCandidates, regressionDefault, } from "@oscharko-dev/keiko-quality-intelligence";
+// Deterministic clock so persisted completedAt / event timestamps never depend on wall time.
+export const CLOCK = Object.freeze({
+    nowIso: () => "2026-06-08T00:01:00.000Z",
+});
+export const PROVENANCE = {
+    envelopeIds: ["env-1"],
+    auditSummaryId: "audit-273-test",
+};
+export const ENVELOPE = Object.freeze({
+    id: QualityIntelligence.asQualityIntelligenceSourceEnvelopeId("env-1"),
+    kind: "human-context",
+    displayLabel: "Audit source",
+    localRef: "env-1",
+    provenance: {
+        origin: "requirements",
+        registeredAt: "2026-06-08T00:00:00.000Z",
+        integrityHashSha256Hex: "b".repeat(64),
+    },
+});
+export function makePlan(id) {
+    return {
+        id: QualityIntelligence.asQualityIntelligenceRunId(id),
+        requestedAt: "2026-06-08T00:00:00.000Z",
+        plannerKind: "model-routed",
+        stages: [],
+    };
+}
+export function makeAtom(id) {
+    return {
+        id: QualityIntelligence.asQualityIntelligenceEvidenceAtomId(id),
+        kind: "requirement",
+        sourceEnvelopeId: QualityIntelligence.asQualityIntelligenceSourceEnvelopeId("env-1"),
+        canonicalHashSha256Hex: "a".repeat(64),
+        redactionStatus: "not-required",
+        lifecycleStatus: "draft",
+    };
+}
+export function ingestedAtomsFixture() {
+    return [
+        {
+            atom: makeAtom("atom-1"),
+            canonicalText: "REQ-1: Lock the account after five failed logins.",
+        },
+        { atom: makeAtom("atom-2"), canonicalText: "REQ-2: Reset the counter after a success." },
+    ];
+}
+// Real domain candidates derived from atoms (status "proposed"), so coverage-review / validation /
+// refinement entries receive schema-valid candidates without hand-rolling the shape.
+export function candidatesFor(runId, atoms) {
+    const intent = deriveIntent([ENVELOPE], regressionDefault);
+    return designTestCaseCandidates({
+        runId: QualityIntelligence.asQualityIntelligenceRunId(runId),
+        intent,
+        atoms,
+        profile: regressionDefault,
+    });
+}
+export function recordingSink() {
+    const events = [];
+    return {
+        sink: { emit: (e) => void events.push(e) },
+        events: () => events,
+        kinds: () => events.map((e) => e.payload.kind),
+        stageNames: () => events
+            .map((e) => e.payload)
+            .filter((p) => "stageName" in p)
+            .map((p) => p.stageName),
+        trace: () => events.map((e) => {
+            const p = e.payload;
+            return "stageName" in p ? `${p.kind}:${p.stageName}` : p.kind;
+        }),
+    };
+}
+// Deterministic model output (two candidates) for the model-routed entry — copied shape from
+// modelRoutedTestDesign.test.ts so the two suites agree on the fixture.
+export const MODEL_OUTPUT_TWO = JSON.stringify([
+    {
+        title: "Test atom 1 behavior",
+        steps: ["Navigate to the feature", "Trigger the atom-1 action"],
+        expectedResults: ["The atom-1 behavior occurs"],
+        priority: "P2",
+        riskClass: "regression",
+        derivedFromEvidenceIndexes: [1],
+    },
+    {
+        title: "Test atom 2 behavior",
+        steps: ["Navigate to the feature", "Trigger the atom-2 action"],
+        expectedResults: ["The atom-2 behavior occurs"],
+        priority: "P2",
+        riskClass: "regression",
+        derivedFromEvidenceIndexes: [2],
+    },
+]);
+export function modelRoutedDeps(store, sink) {
+    return {
+        sink,
+        evidenceStore: store,
+        candidatesSink: { record: () => undefined },
+        generate: {
+            generate: () => Promise.resolve({ rawText: MODEL_OUTPUT_TWO, modelCallCount: 1, modelId: "test-model" }),
+        },
+        clock: CLOCK,
+    };
+}
+export { createInMemoryQualityIntelligenceLocalStore };

package/dist/qualityIntelligence/cancellation.d.ts

@@ -0,0 +1,20 @@
+export interface QualityIntelligenceStageCancellationHandle {
+    readonly signal: AbortSignal;
+    readonly cancel: (reason?: string) => void;
+    readonly dispose: () => void;
+}
+/**
+ * Compose a parent cancellation signal with a freshly minted stage controller.
+ * If the parent is already aborted, the returned signal is aborted immediately.
+ * The handle's `dispose()` MUST be called once the stage finishes so the parent
+ * listener is removed (otherwise long-running runs leak DOM listeners across
+ * stages on the same parent signal).
+ */
+export declare function composeStageCancellation(parent: AbortSignal | undefined): QualityIntelligenceStageCancellationHandle;
+/**
+ * Returns true when the supplied signal has been aborted. Pure helper around
+ * the standard DOM property so the run entries do not sprinkle the property
+ * access at every cooperative cancellation check.
+ */
+export declare function isCancelled(signal: AbortSignal | undefined): boolean;
+//# sourceMappingURL=cancellation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/cancellation.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,0CAA0C,CA8B5C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAEpE"}

package/dist/qualityIntelligence/cancellation.js

@@ -0,0 +1,55 @@
+// Cancellation bridge between the harness AbortSignal world and the QI dispatcher
+// (Epic #270, Issue #273, ADR-0023 D6).
+//
+// The harness threads a single AbortSignal through workflows. The QI dispatcher
+// (#279) accepts an optional AbortSignal too. This adapter is a thin helper that
+// composes a parent signal with a per-stage AbortController so an individual
+// stage can be cancelled without disturbing the rest of the run. No timers; no
+// IO; pure DOM/Node primitives only.
+/**
+ * Compose a parent cancellation signal with a freshly minted stage controller.
+ * If the parent is already aborted, the returned signal is aborted immediately.
+ * The handle's `dispose()` MUST be called once the stage finishes so the parent
+ * listener is removed (otherwise long-running runs leak DOM listeners across
+ * stages on the same parent signal).
+ */
+export function composeStageCancellation(parent) {
+    const controller = new AbortController();
+    if (parent !== undefined) {
+        if (parent.aborted) {
+            controller.abort(parent.reason);
+        }
+        else {
+            const onParentAbort = () => {
+                controller.abort(parent.reason);
+            };
+            parent.addEventListener("abort", onParentAbort, { once: true });
+            return Object.freeze({
+                signal: controller.signal,
+                cancel: (reason) => {
+                    controller.abort(reason);
+                },
+                dispose: () => {
+                    parent.removeEventListener("abort", onParentAbort);
+                },
+            });
+        }
+    }
+    return Object.freeze({
+        signal: controller.signal,
+        cancel: (reason) => {
+            controller.abort(reason);
+        },
+        dispose: () => {
+            /* no parent listener was attached */
+        },
+    });
+}
+/**
+ * Returns true when the supplied signal has been aborted. Pure helper around
+ * the standard DOM property so the run entries do not sprinkle the property
+ * access at every cooperative cancellation check.
+ */
+export function isCancelled(signal) {
+    return signal?.aborted ?? false;
+}

package/dist/qualityIntelligence/descriptors.d.ts

@@ -0,0 +1,41 @@
+import type { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+export type QualityIntelligenceWorkflowId = "qi:test-design" | "qi:coverage-review" | "qi:validation" | "qi:artifact-refinement";
+export interface QualityIntelligenceWorkflowLimits {
+    /** Wall-clock soft limit per stage (advisory, used to bound dispatcher waits). */
+    readonly stageTimeoutMs: number;
+    /** Total candidates a single test-design run may emit (truncated past). */
+    readonly maxCandidatesPerRun: number;
+    /** Total findings a single validation run may emit (truncated past). */
+    readonly maxFindingsPerRun: number;
+    /**
+     * Maximum model gateway dispatches the GENERATION stage(s) may make per run. The adversarial
+     * test-quality judge (Epic #736) is governed by its own `maxJudgeCallsPerRun` budget instead,
+     * because it makes one dispatch per candidate and must score every candidate (Issue #747).
+     */
+    readonly maxModelCallsPerRun: number;
+    /**
+     * Maximum model gateway dispatches the adversarial test-quality judge may make per run
+     * (Epic #736, Issue #747). One dispatch per candidate; defaults to the candidate cap so a
+     * realistic run is judged in full while a pathological run can never dispatch an unbounded
+     * number of judge calls. Candidates beyond this ceiling receive deterministic weak judge findings,
+     * so the run still accounts for every candidate without dispatching unbounded calls.
+     */
+    readonly maxJudgeCallsPerRun: number;
+}
+export declare const QUALITY_INTELLIGENCE_DEFAULT_WORKFLOW_LIMITS: QualityIntelligenceWorkflowLimits;
+export interface QualityIntelligenceWorkflowDescriptor {
+    readonly workflowId: QualityIntelligenceWorkflowId;
+    readonly displayName: string;
+    readonly description: string;
+    readonly stageNames: readonly string[];
+    readonly emittedEventKinds: readonly QualityIntelligence.QualityIntelligenceRunEventKind[];
+    readonly defaultLimits: QualityIntelligenceWorkflowLimits;
+    readonly preferredCostClass: "low" | "medium" | "high";
+}
+export declare const QI_TEST_DESIGN_WORKFLOW_DESCRIPTOR: QualityIntelligenceWorkflowDescriptor;
+export declare const QI_COVERAGE_REVIEW_WORKFLOW_DESCRIPTOR: QualityIntelligenceWorkflowDescriptor;
+export declare const QI_VALIDATION_WORKFLOW_DESCRIPTOR: QualityIntelligenceWorkflowDescriptor;
+export declare const QI_ARTIFACT_REFINEMENT_WORKFLOW_DESCRIPTOR: QualityIntelligenceWorkflowDescriptor;
+export declare const QUALITY_INTELLIGENCE_WORKFLOW_DESCRIPTORS: readonly QualityIntelligenceWorkflowDescriptor[];
+export declare function findQualityIntelligenceWorkflowDescriptor(workflowId: QualityIntelligenceWorkflowId): QualityIntelligenceWorkflowDescriptor;
+//# sourceMappingURL=descriptors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/descriptors.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,MAAM,MAAM,6BAA6B,GACrC,gBAAgB,GAChB,oBAAoB,GACpB,eAAe,GACf,wBAAwB,CAAC;AAE7B,MAAM,WAAW,iCAAiC;IAChD,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,eAAO,MAAM,4CAA4C,EAAE,iCAOvD,CAAC;AAEL,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,UAAU,EAAE,6BAA6B,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,mBAAmB,CAAC,+BAA+B,EAAE,CAAC;IAC3F,QAAQ,CAAC,aAAa,EAAE,iCAAiC,CAAC;IAC1D,QAAQ,CAAC,kBAAkB,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CACxD;AAsCD,eAAO,MAAM,kCAAkC,EAAE,qCAW7C,CAAC;AAEL,eAAO,MAAM,sCAAsC,EAAE,qCAWjD,CAAC;AAEL,eAAO,MAAM,iCAAiC,EAAE,qCAW5C,CAAC;AAEL,eAAO,MAAM,0CAA0C,EAAE,qCAWrD,CAAC;AAEL,eAAO,MAAM,yCAAyC,EAAE,SAAS,qCAAqC,EAMlG,CAAC;AAEL,wBAAgB,yCAAyC,CACvD,UAAU,EAAE,6BAA6B,GACxC,qCAAqC,CAOvC"}

package/dist/qualityIntelligence/descriptors.js

@@ -0,0 +1,105 @@
+// Quality Intelligence workflow descriptors (Epic #270, Issue #273, ADR-0023 D6).
+//
+// Four reviewable QI workflows executed through `@oscharko-dev/keiko-harness` and
+// `@oscharko-dev/keiko-workflows`. Each descriptor enumerates the deterministic
+// stage sequence, the emitted event kinds, and the typed limits the run entry
+// honours. NO model SDK reaches this module: stage runtime composes the gateway
+// dispatcher seam shipped in #279.
+//
+// Structurally inspired by Test Intelligence reference (TI) workflow staging,
+// but the Keiko port stays envelope-shaped, descriptor-driven, and free of
+// any TI runtime / IR.
+//
+// The descriptors here are pure value records — they intentionally do NOT
+// instantiate the WorkflowDescriptor shape from `../descriptor.js` because that
+// shape is tuned to the apply/dry-run developer-assist workflows (#8/#9) and
+// would force fictional input slots onto QI runs. The QI surface re-exports
+// `QualityIntelligenceWorkflowDescriptor` from this file directly.
+export const QUALITY_INTELLIGENCE_DEFAULT_WORKFLOW_LIMITS = Object.freeze({
+    stageTimeoutMs: 45_000,
+    maxCandidatesPerRun: 256,
+    maxFindingsPerRun: 512,
+    maxModelCallsPerRun: 32,
+    maxJudgeCallsPerRun: 256,
+});
+const FROZEN_DEFAULT_LIMITS = QUALITY_INTELLIGENCE_DEFAULT_WORKFLOW_LIMITS;
+function freezeStringArray(values) {
+    return Object.freeze([...values]);
+}
+function freezeEventKinds(values) {
+    return Object.freeze([...values]);
+}
+function freezeDescriptor(descriptor) {
+    return Object.freeze({
+        ...descriptor,
+        stageNames: freezeStringArray(descriptor.stageNames),
+        emittedEventKinds: freezeEventKinds(descriptor.emittedEventKinds),
+        defaultLimits: descriptor.defaultLimits,
+    });
+}
+// Shared run-lifecycle envelope event kinds. Every QI workflow emits this set;
+// stage-specific extra kinds are added per descriptor below.
+const LIFECYCLE_EVENT_KINDS = [
+    "run:queued",
+    "run:started",
+    "stage:started",
+    "stage:completed",
+    "stage:failed",
+    "run:succeeded",
+    "run:failed",
+    "run:cancelled",
+];
+export const QI_TEST_DESIGN_WORKFLOW_DESCRIPTOR = freezeDescriptor({
+    workflowId: "qi:test-design",
+    displayName: "Quality Intelligence — Test Design",
+    description: "Draft test-case candidates, adversarially judge their quality, build coverage map, validate, " +
+        "persist evidence. Stages: plan, candidates, judge, coverage, validate, finalize.",
+    stageNames: ["plan", "candidates", "judge", "coverage", "validate", "finalize"],
+    emittedEventKinds: [...LIFECYCLE_EVENT_KINDS, "candidate:proposed", "finding:recorded"],
+    defaultLimits: FROZEN_DEFAULT_LIMITS,
+    preferredCostClass: "medium",
+});
+export const QI_COVERAGE_REVIEW_WORKFLOW_DESCRIPTOR = freezeDescriptor({
+    workflowId: "qi:coverage-review",
+    displayName: "Quality Intelligence — Coverage Review",
+    description: "Build and report a coverage map across existing candidates and atoms. " +
+        "Stages: plan, analyse, report.",
+    stageNames: ["plan", "analyse", "report"],
+    emittedEventKinds: [...LIFECYCLE_EVENT_KINDS],
+    defaultLimits: FROZEN_DEFAULT_LIMITS,
+    preferredCostClass: "low",
+});
+export const QI_VALIDATION_WORKFLOW_DESCRIPTOR = freezeDescriptor({
+    workflowId: "qi:validation",
+    displayName: "Quality Intelligence — Validation",
+    description: "Run schema/logic validators and optional model judges over existing candidates, reconcile, persist. " +
+        "Stages: plan, run-judges, reconcile, report.",
+    stageNames: ["plan", "run-judges", "reconcile", "report"],
+    emittedEventKinds: [...LIFECYCLE_EVENT_KINDS, "finding:recorded"],
+    defaultLimits: FROZEN_DEFAULT_LIMITS,
+    preferredCostClass: "high",
+});
+export const QI_ARTIFACT_REFINEMENT_WORKFLOW_DESCRIPTOR = freezeDescriptor({
+    workflowId: "qi:artifact-refinement",
+    displayName: "Quality Intelligence — Artifact Refinement",
+    description: "Refine existing candidates by re-applying the policy profile and deduplication, then validate. " +
+        "Stages: plan, refine, validate, report.",
+    stageNames: ["plan", "refine", "validate", "report"],
+    emittedEventKinds: [...LIFECYCLE_EVENT_KINDS, "candidate:proposed", "finding:recorded"],
+    defaultLimits: FROZEN_DEFAULT_LIMITS,
+    preferredCostClass: "medium",
+});
+export const QUALITY_INTELLIGENCE_WORKFLOW_DESCRIPTORS = Object.freeze([
+    QI_TEST_DESIGN_WORKFLOW_DESCRIPTOR,
+    QI_COVERAGE_REVIEW_WORKFLOW_DESCRIPTOR,
+    QI_VALIDATION_WORKFLOW_DESCRIPTOR,
+    QI_ARTIFACT_REFINEMENT_WORKFLOW_DESCRIPTOR,
+]);
+export function findQualityIntelligenceWorkflowDescriptor(workflowId) {
+    for (const descriptor of QUALITY_INTELLIGENCE_WORKFLOW_DESCRIPTORS) {
+        if (descriptor.workflowId === workflowId) {
+            return descriptor;
+        }
+    }
+    throw new Error(`Unknown Quality Intelligence workflow id: ${workflowId}`);
+}