@oscharko-dev/keiko-contracts 0.2.0

package/dist/editor-session.d.ts

@@ -0,0 +1,31 @@
+export declare const EDITOR_SESSION_SCHEMA_VERSION: "1";
+export interface EditorDocumentVersion {
+    readonly sizeBytes: number;
+    readonly modifiedAt: number;
+    readonly contentHash: string;
+}
+export interface EditorSessionAiProvenance {
+    readonly modelId: string;
+    readonly gatewayPolicyVersion: string;
+    readonly promptHash: string;
+    readonly requestId: string;
+}
+export interface EditorDocumentSession {
+    readonly schemaVersion: typeof EDITOR_SESSION_SCHEMA_VERSION;
+    readonly version: EditorDocumentVersion;
+    readonly aiProvenance?: EditorSessionAiProvenance;
+}
+export type EditorSessionErrorCode = "UNSUPPORTED_FILE" | "FILE_TOO_LARGE" | "WRITE_CONFLICT" | "DENIED" | "STALE_SESSION";
+export declare const EDITOR_SESSION_ERROR_CODES: readonly EditorSessionErrorCode[];
+export interface EditorSessionValidationOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface EditorSessionValidationFail {
+    readonly ok: false;
+    readonly errors: readonly string[];
+}
+export type EditorSessionValidation<T> = EditorSessionValidationOk<T> | EditorSessionValidationFail;
+export declare function isEditorDocumentVersion(value: unknown): value is EditorDocumentVersion;
+export declare function parseEditorDocumentVersion(value: unknown): EditorSessionValidation<EditorDocumentVersion>;
+//# sourceMappingURL=editor-session.d.ts.map

package/dist/editor-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-session.d.ts","sourceRoot":"","sources":["../src/editor-session.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,6BAA6B,EAAG,GAAY,CAAC;AAK1D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAMD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAID,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAC;IAC7D,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,yBAAyB,CAAC;CACnD;AAMD,MAAM,MAAM,sBAAsB,GAC9B,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,QAAQ,GACR,eAAe,CAAC;AAEpB,eAAO,MAAM,0BAA0B,EAAE,SAAS,sBAAsB,EAM9D,CAAC;AAMX,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AACD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AACD,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,yBAAyB,CAAC,CAAC,CAAC,GAAG,2BAA2B,CAAC;AA0BpG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAOtF;AAID,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,uBAAuB,CAAC,qBAAqB,CAAC,CAyBhD"}

package/dist/editor-session.js

@@ -0,0 +1,75 @@
+// Governed editor-session contracts (Issue #1197, Epic #1189). These shapes generalize the
+// existing file read/write surface into editor-session metadata so the editor, deterministic
+// diagnostics (#1198), and model-backed completion (#1199) can correlate "the content the user
+// is editing" with "the content the server reasoned over" — without ever echoing file content.
+//
+// This module owns the editor-session / file-state contract namespace for the epic. It is kept
+// disjoint from the language-service namespace (#1198): no name overlaps, no shared types.
+//
+// Leaf-package rules (ADR-0019): pure types and frozen const tables only. No filesystem, no
+// clock, no crypto, no randomness, and no imports of other `@oscharko-dev/keiko-*` packages.
+// The content-free `contentHash` is computed by producers (the BFF) with `node:crypto` and only
+// inspected here as an opaque hex string.
+// Schema version for the editor-session metadata envelope. Bump as a new string member when the
+// shape changes incompatibly; consumers pin against the literal to detect skew.
+export const EDITOR_SESSION_SCHEMA_VERSION = "1";
+export const EDITOR_SESSION_ERROR_CODES = [
+    "UNSUPPORTED_FILE",
+    "FILE_TOO_LARGE",
+    "WRITE_CONFLICT",
+    "DENIED",
+    "STALE_SESSION",
+];
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// A byte count: a non-negative integer. Fractional byte counts can never match the filesystem
+// `stats.size`, so they are rejected up front rather than silently yielding a stale-session 409.
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+// `modifiedAt` mirrors `stats.mtimeMs`, which carries sub-millisecond fractional precision, so it
+// is validated as a finite non-negative number rather than an integer.
+function isFiniteNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isSha256Hex(value) {
+    return typeof value === "string" && SHA256_HEX.test(value);
+}
+// Strict structural guard. Unknown extra keys are tolerated (forward-compatible wire); the three
+// required fields must be present with valid values.
+export function isEditorDocumentVersion(value) {
+    return (isRecord(value) &&
+        isNonNegativeInteger(value.sizeBytes) &&
+        isFiniteNonNegativeNumber(value.modifiedAt) &&
+        isSha256Hex(value.contentHash));
+}
+// Validates an `unknown` payload into an EditorDocumentVersion, reporting one error per failed
+// invariant. The BFF uses this to reject a malformed client-supplied baseVersion with 400.
+export function parseEditorDocumentVersion(value) {
+    if (!isRecord(value)) {
+        return { ok: false, errors: ["baseVersion must be an object"] };
+    }
+    const errors = [];
+    if (!isNonNegativeInteger(value.sizeBytes)) {
+        errors.push("baseVersion.sizeBytes must be a non-negative integer");
+    }
+    if (!isFiniteNonNegativeNumber(value.modifiedAt)) {
+        errors.push("baseVersion.modifiedAt must be a finite non-negative number");
+    }
+    if (!isSha256Hex(value.contentHash)) {
+        errors.push("baseVersion.contentHash must be a lowercase hex SHA-256 string");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return {
+        ok: true,
+        value: {
+            sizeBytes: value.sizeBytes,
+            modifiedAt: value.modifiedAt,
+            contentHash: value.contentHash,
+        },
+    };
+}

package/dist/editor-test-generation.d.ts

@@ -0,0 +1,104 @@
+import { type LanguageDocumentOverlay, type LanguageRange } from "./language-service.js";
+import type { EditorCompletionContextSelectors } from "./editor-completion.js";
+import type { CodingContextWirePack } from "./coding-context.js";
+export declare const EDITOR_TEST_GENERATION_SCHEMA_VERSION: "1";
+export declare const EDITOR_TEST_GENERATION_STABILITY_RUNS: 5;
+export type EditorTestGenerationTargetKind = "file" | "selection" | "symbol" | "changed-file-set" | "frontend-component";
+export declare const EDITOR_TEST_GENERATION_TARGET_KINDS: readonly EditorTestGenerationTargetKind[];
+export interface EditorTestGenerationWireSymbol {
+    readonly name: string;
+    readonly container?: string;
+    readonly range: LanguageRange;
+}
+export type EditorTestGenerationWireTarget = {
+    readonly kind: "file";
+    readonly document: LanguageDocumentOverlay;
+} | {
+    readonly kind: "selection";
+    readonly document: LanguageDocumentOverlay;
+    readonly range: LanguageRange;
+} | {
+    readonly kind: "symbol";
+    readonly document: LanguageDocumentOverlay;
+    readonly symbol: EditorTestGenerationWireSymbol;
+} | {
+    readonly kind: "changed-file-set";
+    readonly documents: readonly LanguageDocumentOverlay[];
+} | {
+    readonly kind: "frontend-component";
+    readonly document: LanguageDocumentOverlay;
+    readonly componentName: string;
+    readonly range?: LanguageRange;
+};
+export interface EditorTestGenerationWireRequest {
+    readonly schemaVersion: typeof EDITOR_TEST_GENERATION_SCHEMA_VERSION;
+    readonly root: string;
+    readonly target: EditorTestGenerationWireTarget;
+    readonly contextBudgetBytes: number;
+    readonly context?: EditorCompletionContextSelectors;
+}
+export type EditorTestGenerationStatus = "disabled" | "deferred" | "generated" | "failed";
+export declare const EDITOR_TEST_GENERATION_STATUSES: readonly EditorTestGenerationStatus[];
+export type EditorTestGenerationAssurance = "unverified" | "assured";
+export declare const EDITOR_TEST_GENERATION_ASSURANCES: readonly EditorTestGenerationAssurance[];
+export type EditorTestGenerationGateState = "passed" | "failed" | "not-run";
+export declare const EDITOR_TEST_GENERATION_GATE_STATES: readonly EditorTestGenerationGateState[];
+export interface EditorTestGenerationFunnel {
+    readonly executionEnabled: boolean;
+    readonly candidatesGenerated: number;
+    readonly candidatesSurfaced: number;
+    readonly stabilityRunsRequired: number;
+    readonly build: EditorTestGenerationGateState;
+    readonly pass: EditorTestGenerationGateState;
+    readonly stability: EditorTestGenerationGateState;
+    readonly coverage: EditorTestGenerationGateState;
+    readonly mutation: EditorTestGenerationGateState;
+    readonly antiTautology: EditorTestGenerationGateState;
+    readonly coverageLineDelta?: number | undefined;
+    readonly coverageBranchDelta?: number | undefined;
+    readonly mutantsKilled?: number | undefined;
+    readonly mutantsTotal?: number | undefined;
+}
+export type EditorTestGenerationWireChangeKind = "added" | "modified" | "deleted";
+export interface EditorTestGenerationWireEdit {
+    readonly range: LanguageRange;
+    readonly newText: string;
+}
+export interface EditorTestGenerationWireFileChange {
+    readonly path: string;
+    readonly changeKind: EditorTestGenerationWireChangeKind;
+    readonly edits: readonly EditorTestGenerationWireEdit[];
+}
+export interface EditorTestGenerationWirePatch {
+    readonly patchId: string;
+    readonly files: readonly EditorTestGenerationWireFileChange[];
+}
+export interface EditorTestGenerationWireProvenance {
+    readonly modelId: string;
+    readonly gatewayPolicyVersion: string;
+    readonly promptHash: string;
+    readonly producedAt: number;
+}
+export interface EditorTestGenerationWireResponse {
+    readonly schemaVersion: typeof EDITOR_TEST_GENERATION_SCHEMA_VERSION;
+    readonly status: EditorTestGenerationStatus;
+    readonly reason?: string;
+    readonly assurance?: EditorTestGenerationAssurance;
+    readonly funnel: EditorTestGenerationFunnel;
+    readonly context?: CodingContextWirePack;
+    readonly patch?: EditorTestGenerationWirePatch;
+    readonly provenance?: EditorTestGenerationWireProvenance;
+    readonly applyableDiff?: string;
+}
+export declare function notRunTestGenerationFunnel(): EditorTestGenerationFunnel;
+export interface EditorTestGenerationParseOk {
+    readonly ok: true;
+    readonly value: EditorTestGenerationWireRequest;
+}
+export interface EditorTestGenerationParseFail {
+    readonly ok: false;
+    readonly errors: readonly string[];
+}
+export type EditorTestGenerationParse = EditorTestGenerationParseOk | EditorTestGenerationParseFail;
+export declare function parseEditorTestGenerationRequest(value: unknown): EditorTestGenerationParse;
+//# sourceMappingURL=editor-test-generation.d.ts.map

package/dist/editor-test-generation.d.ts.map

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

package/dist/editor-test-generation.js

@@ -0,0 +1,211 @@
+// Editor-driven test-generation WIRE contract (Issue #1202, Epic #1189, ADR-0042 D7).
+// These are the request/response shapes the `POST /api/editor/test-generation` BFF route consumes and
+// emits. The route is the governed seam between the browser-tier `@oscharko-dev/keiko-editor`
+// "Generate Tests" action (which renders a reviewable diff only) and the server-owned, gated
+// unit-test-generation workflow (`@oscharko-dev/keiko-workflows`) enriched with governed coding
+// context (#1211, `purpose: "test-generation"`).
+//
+// Wave-2 surface, shipped switched off (ADR-0042 D7). Editor-driven test generation, execution, and
+// verification execute untrusted, model-generated code through an assured pre-filter and are therefore
+// deferred behind a default-off feature flag that may be enabled only once a deny-by-default network
+// egress boundary is enforced and proven by an automated test (`tools.ts` `network: "inherit"`;
+// `limits.ts` `enforced: false`; "Keiko is not a sandbox"). The route therefore exposes two gates:
+//   - `disabled` — the feature flag is off (the v1 default). No retrieval, no model, no execution.
+//   - `deferred` — the feature is enabled but the assured-execution (egress) boundary is not enforced,
+//     so no model-generated code is produced or executed; governed discovery still runs for provenance.
+//   - `generated` — a reviewable candidate patch was produced (reachable only once the egress boundary
+//     is enforced); in v1 every funnel gate is `not-run` and a candidate can only ever be `unverified`.
+//   - `failed` — a content-free, actionable failure; the editor stays usable.
+//
+// Content boundary: the REQUEST carries the in-editor buffer text (the document overlay) — the user's
+// own buffer travelling over the loopback BFF, exactly like the language-service (#1198) and completion
+// (#1199) requests; it is never logged. The RESPONSE is content-free apart from the reviewable patch
+// edits (`newText`), which are the candidate test code the user explicitly reviews and applies into
+// their own workspace: no raw prompt, no raw model reasoning, no retrieved excerpt, no secret. Status,
+// reason, funnel, assurance, provenance, and the coding-context citations are counts, hashes, enum
+// literals, and content-free pointers only (EU AI Act Reg. (EU) 2024/1689 Art. 12 record-keeping).
+//
+// Leaf-package rules (ADR-0019): pure types and frozen const tables plus throw-free validators only.
+// No filesystem, no clock, no crypto, no randomness, and no imports of other `@oscharko-dev/keiko-*`
+// packages. Geometry, the document-overlay shape, and the coding-context selectors/citations are reused
+// from the sibling editor contracts so the test-generation tier shares one stable provenance model with
+// the completion and inline-completion gateways.
+import { isLanguageDocumentOverlay, isLanguagePosition, } from "./language-service.js";
+// Schema version for the test-generation envelope. Bump as a new string member when the shape changes
+// incompatibly; consumers pin against the literal to detect skew.
+export const EDITOR_TEST_GENERATION_SCHEMA_VERSION = "1";
+// The minimum number of stable executions a generated test must survive in the assured pre-filter
+// before it may be surfaced as apply-ready (Review Addendum — Meta "Automated Unit Test Improvement",
+// FSE 2024). Reported in the funnel so a consumer can audit the wave-2 enablement target even while the
+// pre-filter is `not-run`.
+export const EDITOR_TEST_GENERATION_STABILITY_RUNS = 5;
+export const EDITOR_TEST_GENERATION_TARGET_KINDS = [
+    "file",
+    "selection",
+    "symbol",
+    "changed-file-set",
+    "frontend-component",
+];
+export const EDITOR_TEST_GENERATION_STATUSES = [
+    "disabled",
+    "deferred",
+    "generated",
+    "failed",
+];
+export const EDITOR_TEST_GENERATION_ASSURANCES = [
+    "unverified",
+    "assured",
+];
+export const EDITOR_TEST_GENERATION_GATE_STATES = [
+    "passed",
+    "failed",
+    "not-run",
+];
+// Builds the v1 funnel: no execution, every gate `not-run`, no candidates. The single authority for the
+// "switched-off" funnel so the route and its tests cannot drift.
+export function notRunTestGenerationFunnel() {
+    return {
+        executionEnabled: false,
+        candidatesGenerated: 0,
+        candidatesSurfaced: 0,
+        stabilityRunsRequired: EDITOR_TEST_GENERATION_STABILITY_RUNS,
+        build: "not-run",
+        pass: "not-run",
+        stability: "not-run",
+        coverage: "not-run",
+        mutation: "not-run",
+        antiTautology: "not-run",
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+// A LanguageRange is `{ start, end }` of two LanguagePositions. Defined locally because the
+// language-service module exposes only the position guard; this keeps the test-generation contract a
+// leaf with no new shared dependency.
+function isWireRange(value) {
+    return isRecord(value) && isLanguagePosition(value.start) && isLanguagePosition(value.end);
+}
+function isWireSymbol(value) {
+    return (isRecord(value) &&
+        isNonEmptyString(value.name) &&
+        (value.container === undefined || typeof value.container === "string") &&
+        isWireRange(value.range));
+}
+function isOverlayArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every(isLanguageDocumentOverlay);
+}
+// Collects the optional, content-bearing context selectors (identical invariants to the completion
+// gateway). Unknown-typed fields are rejected so a malformed selector cannot silently widen retrieval;
+// an absent `context` is valid.
+function collectContextErrors(context, errors) {
+    if (context === undefined) {
+        return;
+    }
+    if (!isRecord(context)) {
+        errors.push("context must be an object when provided");
+        return;
+    }
+    for (const field of ["queryText", "symbol", "capsuleId", "capsuleSetId"]) {
+        if (context[field] !== undefined && typeof context[field] !== "string") {
+            errors.push(`context.${field} must be a string when provided`);
+        }
+    }
+    if (context.changedFiles !== undefined && !isStringArray(context.changedFiles)) {
+        errors.push("context.changedFiles must be an array of strings when provided");
+    }
+    if (context.capsuleId !== undefined && context.capsuleSetId !== undefined) {
+        errors.push("context must not set both capsuleId and capsuleSetId");
+    }
+}
+// Collects the shape errors for a single-document target (file/selection/symbol/frontend-component).
+function collectScopedTargetErrors(kind, target, errors) {
+    if (!isLanguageDocumentOverlay(target.document)) {
+        errors.push("target.document must be { path, languageId, text }");
+    }
+    if (kind === "selection" && !isWireRange(target.range)) {
+        errors.push("target.range must be { start, end } for a selection target");
+    }
+    if (kind === "symbol" && !isWireSymbol(target.symbol)) {
+        errors.push("target.symbol must be { name, range } for a symbol target");
+    }
+    if (kind === "frontend-component" && !isNonEmptyString(target.componentName)) {
+        errors.push("target.componentName must be a non-empty string for a frontend-component target");
+    }
+}
+// Collects the target-shape errors for one wire target, dispatching on `kind`.
+function collectTargetErrors(target, errors) {
+    if (!isRecord(target)) {
+        errors.push("target must be an object");
+        return;
+    }
+    const kind = target.kind;
+    if (typeof kind !== "string" ||
+        !EDITOR_TEST_GENERATION_TARGET_KINDS.includes(kind)) {
+        errors.push(`target.kind must be one of: ${EDITOR_TEST_GENERATION_TARGET_KINDS.join(", ")}`);
+        return;
+    }
+    if (kind === "changed-file-set") {
+        if (!isOverlayArray(target.documents)) {
+            errors.push("target.documents must be a non-empty array of { path, languageId, text }");
+        }
+        return;
+    }
+    collectScopedTargetErrors(kind, target, errors);
+}
+function collectRequestErrors(value) {
+    const errors = [];
+    if (value.schemaVersion !== EDITOR_TEST_GENERATION_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be ${EDITOR_TEST_GENERATION_SCHEMA_VERSION}`);
+    }
+    if (!isNonEmptyString(value.root)) {
+        errors.push("root must be a non-empty string");
+    }
+    collectTargetErrors(value.target, errors);
+    if (!isNonNegativeInteger(value.contextBudgetBytes)) {
+        errors.push("contextBudgetBytes must be a non-negative integer");
+    }
+    collectContextErrors(value.context, errors);
+    return errors;
+}
+function buildContextSelectors(context) {
+    return {
+        ...(typeof context.queryText === "string" ? { queryText: context.queryText } : {}),
+        ...(typeof context.symbol === "string" ? { symbol: context.symbol } : {}),
+        ...(isStringArray(context.changedFiles) ? { changedFiles: context.changedFiles } : {}),
+        ...(typeof context.capsuleId === "string" ? { capsuleId: context.capsuleId } : {}),
+        ...(typeof context.capsuleSetId === "string" ? { capsuleSetId: context.capsuleSetId } : {}),
+    };
+}
+// Validates an `unknown` payload into an EditorTestGenerationWireRequest, reporting one error per failed
+// invariant. The BFF uses this to reject a malformed request with 400 INVALID_REQUEST. The narrowed
+// `target` is taken verbatim after validation so the discriminated variants stay intact.
+export function parseEditorTestGenerationRequest(value) {
+    if (!isRecord(value)) {
+        return { ok: false, errors: ["request must be an object"] };
+    }
+    const errors = collectRequestErrors(value);
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const context = isRecord(value.context) ? buildContextSelectors(value.context) : undefined;
+    return {
+        ok: true,
+        value: {
+            schemaVersion: EDITOR_TEST_GENERATION_SCHEMA_VERSION,
+            root: value.root,
+            target: value.target,
+            contextBudgetBytes: value.contextBudgetBytes,
+            ...(context !== undefined && Object.keys(context).length > 0 ? { context } : {}),
+        },
+    };
+}

package/dist/evaluations.d.ts

@@ -0,0 +1,75 @@
+import type { NormalizedResponse } from "./gateway.js";
+export type EvaluationDimension = "task-completion" | "patch-correctness" | "test-pass-rate" | "verification-completeness" | "patch-size" | "audit-completeness" | "unsafe-action-rejection";
+export declare const EVALUATION_DIMENSIONS: readonly EvaluationDimension[];
+export interface FixtureOracle {
+    readonly expectedStatuses: readonly string[];
+    readonly expectPatch: boolean;
+    readonly expectVerificationSkip: boolean;
+    readonly maxExpectedChangedFiles: number;
+    readonly maxExpectedPatchBytes: number;
+}
+export type WorkflowKind = "unit-tests" | "bug-investigation";
+export interface EvaluationFixture {
+    readonly name: string;
+    readonly workflowKind: WorkflowKind;
+    readonly workspaceFiles: Record<string, string>;
+    readonly workflowInput: Record<string, unknown>;
+    readonly apply?: boolean | undefined;
+    readonly mockTranscript: readonly (NormalizedResponse | Error)[];
+    readonly dimensions: ReadonlySet<EvaluationDimension>;
+    readonly oracle: FixtureOracle;
+}
+export type DimensionOutcome = "pass" | "fail" | "not-applicable";
+export interface DimensionResult {
+    readonly dimension: EvaluationDimension;
+    readonly outcome: DimensionOutcome;
+    readonly reason?: string | undefined;
+}
+export interface FixtureRunResult {
+    readonly fixtureName: string;
+    readonly workflowKind: WorkflowKind;
+    readonly durationMs: number;
+    readonly dimensionResults: readonly DimensionResult[];
+    readonly report: Record<string, unknown>;
+}
+export interface ScorecardEntry {
+    readonly dimension: EvaluationDimension;
+    readonly passCount: number;
+    readonly failCount: number;
+    readonly notApplicableCount: number;
+    readonly passRate: number | null;
+}
+export interface SurfaceParityCheckResult {
+    readonly check: string;
+    readonly workflowKind: WorkflowKind;
+    readonly passed: boolean;
+    readonly reason?: string | undefined;
+}
+export interface SurfaceParityResult {
+    readonly allPassed: boolean;
+    readonly checks: readonly SurfaceParityCheckResult[];
+}
+export interface LiveRunContext {
+    readonly modelId: string;
+    readonly configDescriptor: string;
+    readonly evidenceRefs: readonly string[];
+}
+export declare const EVAL_SCORECARD_SCHEMA_VERSION: "1";
+export interface ScorecardSummary {
+    readonly totalFixtures: number;
+    readonly fullyPassedFixtures: number;
+    readonly safetyGatePassed: boolean;
+    readonly pilotReadyIndicator: boolean;
+}
+export interface EvalScorecard {
+    readonly schemaVersion: typeof EVAL_SCORECARD_SCHEMA_VERSION;
+    readonly evaluatedAt: string;
+    readonly mode: EvaluationMode;
+    readonly liveRunContext?: LiveRunContext | undefined;
+    readonly dimensions: readonly ScorecardEntry[];
+    readonly surfaceParity: SurfaceParityResult;
+    readonly fixtureResults: readonly FixtureRunResult[];
+    readonly summary: ScorecardSummary;
+}
+export type EvaluationMode = "offline" | "live";
+//# sourceMappingURL=evaluations.d.ts.map

package/dist/evaluations.d.ts.map

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

package/dist/evaluations.js

@@ -0,0 +1,16 @@
+// All evaluation interfaces and type aliases for the Wave 1 evaluation harness (ADR-0012 D6/D8/D11).
+// No runtime logic lives here beyond the frozen schema-version constant the type layer exposes as a
+// value. `readonly` everywhere; optional props are `| undefined` because exactOptionalPropertyTypes
+// is on. Every scorecard shape is plain JSON-serializable so the harness can emit it to stdout/file.
+// The seven scored dimensions in their canonical scorecard order. A scorecard always carries one
+// ScorecardEntry per name here, even when no fixture exercises the dimension (all not-applicable).
+export const EVALUATION_DIMENSIONS = [
+    "task-completion",
+    "patch-correctness",
+    "test-pass-rate",
+    "verification-completeness",
+    "patch-size",
+    "audit-completeness",
+    "unsafe-action-rejection",
+];
+export const EVAL_SCORECARD_SCHEMA_VERSION = "1";