@siftline/core 0.0.2 → 0.1.0

package/README.md

@@ -1,16 +1,43 @@
 # @siftline/core
 
-The Siftline engine: recipes, rules, fixtures and the judge wrapper.
+The Siftline Engine: Recipes, the Judge, Rules, Fixtures and the Decision format.
 
-This package is a walking skeleton. It exports a placeholder constant, its own version
-and a placeholder fake client, which is enough to prove the build, type, test, pack and
-publish path. The Engine itself lands next.
+```sh
+npm install @siftline/core @typesafe-ai/sdk
+```
 
 ```ts
-import { PLACEHOLDER, VERSION } from "@siftline/core";
-import { createFakeTypeSafeClient } from "@siftline/core/testing";
+import { choice, createJudge, defineRecipe, noul, serializeDecision } from "@siftline/core";
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+
+const recipe = defineRecipe({
+  name: "support-inbox",
+  version: 1,
+  model: "jev-1.13.0",
+  questions: {
+    category: choice("Which category best describes this message?", {
+      complaint: "The sender is unhappy with the product or service",
+      question: "The sender asks how something works",
+      other: "Anything else, including spam and thanks",
+    }),
+    wants_human: noul("Does the sender ask to speak to a person?"),
+  },
+});
+
+const client = new TypeSafeClient({ apiKey: process.env.TYPESAFE_API_KEY });
+const judge = createJudge({ client, retry: "patient" });
+const decision = await judge({ id: "msg-1", state: "…" }, recipe);
+
+console.log(serializeDecision(decision));
 ```
 
+`decision.answers.category` is `"complaint" | "question" | "other"`, not `string`: the
+Recipe's labels travel through the types.
+
+The guide and the full reference live at
+[docs.siftline.dev](https://docs.siftline.dev/docs/packages/core). `@siftline/core/testing`
+ships the scripted, replay and recording clients tests judge with.
+
 ESM only. Node 22.14 or newer.
 
 ## Licence

package/dist/client-B_yz9_JS.d.mts

@@ -0,0 +1,162 @@
+import { z } from "zod";
+//#region src/recipe.d.ts
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/** The SDK's `EntryType`: prose, a JSON object or a JSON array. */
+type EntryType = string | {
+  [key: string]: JsonValue;
+} | JsonValue[] | null;
+/** `instructions` is required on every Question, so the SDK's `null` is out. */
+type Entry = Exclude<EntryType, null>;
+type ChoiceCriteria = {
+  [label: string]: EntryType;
+};
+type ScoreCriteria = readonly [EntryType, EntryType, ...EntryType[]];
+interface ChoiceQuestion<T extends ChoiceCriteria = ChoiceCriteria> {
+  type: "choice";
+  instructions: Entry;
+  criteria: T;
+}
+interface NoulQuestion {
+  type: "noul";
+  instructions: Entry;
+  criteria?: {
+    true?: EntryType;
+    false?: EntryType;
+  };
+}
+interface ScoreQuestion<T extends ScoreCriteria = ScoreCriteria> {
+  type: "score";
+  instructions: Entry;
+  criteria: T;
+}
+type Question = ChoiceQuestion | NoulQuestion | ScoreQuestion;
+interface Questions {
+  [name: string]: Question;
+}
+declare function choice<const T extends ChoiceCriteria>(instructions: Entry, criteria: T): ChoiceQuestion<T>;
+declare function noul(instructions: Entry, criteria?: NoulQuestion["criteria"]): NoulQuestion;
+declare function score<const T extends ScoreCriteria>(instructions: Entry, criteria: T): ScoreQuestion<T>;
+declare const questionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<"choice">;
+  instructions: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>;
+  criteria: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>>;
+}, z.core.$strict>, z.ZodObject<{
+  type: z.ZodLiteral<"noul">;
+  instructions: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>;
+  criteria: z.ZodOptional<z.ZodObject<{
+    true: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>>;
+    false: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+  type: z.ZodLiteral<"score">;
+  instructions: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>;
+  criteria: z.ZodTuple<[z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>], z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>>;
+}, z.core.$strict>], "type">;
+declare const recipeSchema: z.ZodObject<{
+  format: z.ZodLiteral<1>;
+  name: z.ZodString;
+  version: z.ZodNumber;
+  model: z.ZodString;
+  reviewThreshold: z.ZodNumber;
+  questions: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    instructions: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>;
+    criteria: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>>;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"noul">;
+    instructions: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>;
+    criteria: z.ZodOptional<z.ZodObject<{
+      true: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>>;
+      false: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"score">;
+    instructions: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>;
+    criteria: z.ZodTuple<[z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>], z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>]>>;
+  }, z.core.$strict>], "type">>;
+}, z.core.$strict>;
+/** `questions` is core's `Questions`, not `z.infer`: the parsed shape erases the literals. */
+type Recipe<Q extends Questions = Questions> = Omit<z.infer<typeof recipeSchema>, "questions"> & {
+  questions: Q;
+};
+interface DefineRecipeInput<Q extends Questions> {
+  name: string;
+  version: number;
+  model: string;
+  reviewThreshold?: number;
+  questions: Q;
+}
+/** Returns the object it built, not `parse`'s copy, whose type is the erased `Recipe`. */
+declare function defineRecipe<const Q extends Questions>(input: DefineRecipeInput<Q>): Recipe<Q>;
+declare function parseRecipe(text: string): Recipe;
+declare function serializeRecipe(recipe: Recipe): string;
+//#endregion
+//#region src/client.d.ts
+/** A Choice answer as the wire returns it; `probabilities` key order is not the Recipe's. */
+interface ChoiceResponse {
+  readonly type: "choice";
+  readonly choice: string;
+  readonly confidence: number;
+  readonly probabilities: {
+    readonly [label: string]: number;
+  };
+}
+/** A Noul answer. The wire carries no `confidence`; the Judge derives one. */
+interface NoulResponse {
+  readonly type: "noul";
+  readonly noul: number;
+}
+interface ScoreResponse {
+  readonly type: "score";
+  /** Expected value across the rubric, not a level index. The answer is the argmax. */
+  readonly score: number;
+  readonly confidence: number;
+  readonly probabilities: {
+    readonly [index: string]: number;
+  };
+  /** Echoed criteria. Core never reads it, so its shape is the API's business. */
+  readonly legend?: unknown;
+}
+type AnswerResponse = ChoiceResponse | NoulResponse | ScoreResponse;
+/** The wire shape, `usage` in snake case. The Judge camel-cases it into the Decision. */
+interface SystemOneResult {
+  readonly model: string;
+  readonly answers: {
+    readonly [name: string]: AnswerResponse;
+  };
+  readonly usage: {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+  };
+}
+interface SystemOneRequest {
+  state: EntryType;
+  questions: Questions;
+  model: string;
+}
+/** The slice of the SDK's retry policy the Judge sets. The client owns the rest. */
+interface RetryPolicy {
+  readonly maxRetries: number;
+  readonly backoffMaxMs: number;
+  readonly maxRetryAfterMs: number;
+}
+interface SystemOneCallOptions {
+  retry?: Partial<RetryPolicy>;
+  signal?: AbortSignal;
+  timeout?: number;
+}
+/**
+ * The only thing core asks of a client. Declared here, never imported from the SDK, so core
+ * publishes no dependency on it.
+ *
+ * `systemOne` is a function-typed property, not a method: under `strictFunctionTypes` that
+ * checks parameters contravariantly, so `types.test-d.ts` proving `TypeSafeClient` assignable
+ * to this interface proves something. A method signature would be bivariant.
+ */
+interface SystemOneClient {
+  systemOne: (request: SystemOneRequest, options?: SystemOneCallOptions) => Promise<SystemOneResult>;
+}
+//#endregion
+export { defineRecipe as C, recipeSchema as D, questionSchema as E, score as O, choice as S, parseRecipe as T, Question as _, ScoreResponse as a, ScoreCriteria as b, SystemOneRequest as c, ChoiceQuestion as d, DefineRecipeInput as f, NoulQuestion as g, JsonValue as h, RetryPolicy as i, serializeRecipe as k, SystemOneResult as l, EntryType as m, ChoiceResponse as n, SystemOneCallOptions as o, Entry as p, NoulResponse as r, SystemOneClient as s, AnswerResponse as t, ChoiceCriteria as u, Questions as v, noul as w, ScoreQuestion as x, Recipe as y };

package/dist/index.d.mts

@@ -1,14 +1,341 @@
-//#region src/index.d.ts
+import { C as defineRecipe, D as recipeSchema, E as questionSchema, O as score, S as choice, T as parseRecipe, _ as Question, a as ScoreResponse, b as ScoreCriteria, c as SystemOneRequest, d as ChoiceQuestion, f as DefineRecipeInput, g as NoulQuestion, h as JsonValue, i as RetryPolicy, k as serializeRecipe, l as SystemOneResult, m as EntryType, n as ChoiceResponse, o as SystemOneCallOptions, p as Entry, r as NoulResponse, s as SystemOneClient, t as AnswerResponse, u as ChoiceCriteria, v as Questions, w as noul, x as ScoreQuestion, y as Recipe } from "./client-B_yz9_JS.mjs";
+import { z } from "zod";
+//#region src/decision.d.ts
+/** The Engine's whole view of an item. Sender, source and raw payload stay with the caller. */
+interface Record {
+  id: string;
+  state: EntryType;
+  trimmed?: boolean;
+}
+/** Strict: an unknown key is a bad Record, not a field to ignore. */
+export declare const recordSchema: z.ZodType<Record>;
+type IndexOf<S extends readonly unknown[]> = number extends S["length"] ? number : Extract<keyof S, `${number}`> extends `${infer N extends number}` ? N : never;
+type AnswerFor<Qn> = Qn extends {
+  type: "choice";
+  criteria: infer C;
+} ? keyof C & string : Qn extends {
+  type: "noul";
+} ? boolean : Qn extends {
+  type: "score";
+  criteria: infer S extends readonly unknown[];
+} ? IndexOf<S> : never;
+/** One answer with its literal erased: a label, a boolean or a level index. */
+type AnswerValue = string | boolean | number;
+/** Choice → label, Noul → boolean, Score → level index. Shared with Fixture `expect`. */
+type Answers<Q extends Questions = Questions> = { [K in keyof Q]: AnswerFor<Q[K]>; };
+type EvidenceFor<Qn> = Qn extends {
+  type: "choice";
+  criteria: infer C;
+} ? {
+  confidence: number;
+  probabilities: { [L in keyof C]: number; };
+} : Qn extends {
+  type: "noul";
+} ? {
+  probability: number;
+  confidence: number;
+} : Qn extends {
+  type: "score";
+  criteria: infer S extends readonly unknown[];
+} ? {
+  score: number;
+  confidence: number;
+  probabilities: { [I in IndexOf<S>]: number; };
+} : never;
+/** The model's evidence for one Question. Bare `Evidence` is the union of the three shapes. */
+type Evidence<Qn extends Question = Question> = EvidenceFor<Qn>;
+interface Decision<Q extends Questions = Questions> {
+  format: 1;
+  id: string;
+  recordId: string;
+  recipe: {
+    name: string;
+    version: number;
+  };
+  model: string;
+  judgedAt: string;
+  trimmed: boolean;
+  answers: Answers<Q>;
+  questions: { [K in keyof Q]: Evidence<Q[K]>; };
+  confidence: number;
+  review: boolean;
+  rule: string | null;
+  action: string | null;
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+}
+export declare const decisionSchema: z.ZodObject<{
+  format: z.ZodLiteral<1>;
+  id: z.ZodString;
+  recordId: z.ZodString;
+  recipe: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodNumber;
+  }, z.core.$strict>;
+  model: z.ZodString;
+  judgedAt: z.ZodISODateTime;
+  trimmed: z.ZodBoolean;
+  answers: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>>;
+  questions: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    probability: z.ZodNumber;
+    confidence: z.ZodNumber;
+  }, z.core.$strict>, z.ZodObject<{
+    score: z.ZodNumber;
+    confidence: z.ZodNumber;
+    probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+  }, z.core.$strict>, z.ZodObject<{
+    confidence: z.ZodNumber;
+    probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+  }, z.core.$strict>]>>;
+  confidence: z.ZodNumber;
+  review: z.ZodBoolean;
+  rule: z.ZodNullable<z.ZodString>;
+  action: z.ZodNullable<z.ZodString>;
+  usage: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+export declare function parseDecision(line: string): Decision;
+/** The only writer. One compact line, no trailing newline, and nothing is rounded. */
+export declare function serializeDecision(decision: Decision): string;
+//#endregion
+//#region src/errors.d.ts
+/** Cloud's error union, plus `action_build`, which only the toolkit raises. */
+type SiftlineErrorCode = "jev_exhausted" | "jev_error" | "fixture_invalid" | "action_failed" | "action_build";
+/** The base every toolkit error extends, in core and in `@siftline/actions`. */
+export declare class SiftlineError extends Error {
+  readonly code: SiftlineErrorCode;
+  readonly retryable: boolean;
+  constructor(message: string, code: SiftlineErrorCode, retryable: boolean, options?: ErrorOptions);
+}
+//#endregion
+//#region src/rules.d.ts
+export declare const ruleConditionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  question: z.ZodString;
+  comparator: z.ZodLiteral<"is">;
+  value: z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>;
+}, z.core.$strict>, z.ZodObject<{
+  question: z.ZodString;
+  comparator: z.ZodLiteral<"isOneOf">;
+  value: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  question: z.ZodString;
+  comparator: z.ZodLiteral<"atLeast">;
+  value: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+  question: z.ZodString;
+  comparator: z.ZodLiteral<"atMost">;
+  value: z.ZodNumber;
+}, z.core.$strict>], "comparator">;
+export declare const ruleSchema: z.ZodObject<{
+  id: z.ZodString;
+  condition: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    question: z.ZodString;
+    comparator: z.ZodLiteral<"is">;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>;
+  }, z.core.$strict>, z.ZodObject<{
+    question: z.ZodString;
+    comparator: z.ZodLiteral<"isOneOf">;
+    value: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    question: z.ZodString;
+    comparator: z.ZodLiteral<"atLeast">;
+    value: z.ZodNumber;
+  }, z.core.$strict>, z.ZodObject<{
+    question: z.ZodString;
+    comparator: z.ZodLiteral<"atMost">;
+    value: z.ZodNumber;
+  }, z.core.$strict>], "comparator">;
+  action: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+type ConditionFor<K, Qn> = Qn extends {
+  type: "choice";
+  criteria: infer C;
+} ? {
+  question: K;
+  comparator: "is";
+  value: keyof C & string;
+} | {
+  question: K;
+  comparator: "isOneOf";
+  value: (keyof C & string)[];
+} : Qn extends {
+  type: "noul";
+} ? {
+  question: K;
+  comparator: "is";
+  value: boolean;
+} : Qn extends {
+  type: "score";
+  criteria: infer S extends readonly unknown[];
+} ? {
+  question: K;
+  comparator: "is" | "atLeast" | "atMost";
+  value: IndexOf<S>;
+} : never;
+type RuleCondition<Q extends Questions = Questions> = { [K in keyof Q & string]: ConditionFor<K, Q[K]>; }[keyof Q & string];
+interface Rule<Q extends Questions = Questions> {
+  id: string;
+  condition: RuleCondition<Q>;
+  action: string | null;
+}
+/** What a Decision carries after routing: the Rule that matched and the Action it names. */
+interface Routing {
+  rule: string | null;
+  action: string | null;
+}
+/** One stale Rule, keyed by its id. `validateRules` is the only producer. */
+interface RuleProblem {
+  rule: string;
+  problem: string;
+}
+/** Pure, first match wins, no review gate. Cloud runs it again on corrected answers. */
+export declare function evaluateRules(answers: Answers, rules: Rule[]): Routing;
 /**
- * The published version of `@siftline/core`, baked in at build time.
- *
- * Changesets bumps `package.json`; this constant follows it without a second edit.
+ * `NoInfer` keeps `Q` coming from the Decision alone, so an unannotated Rule literal is checked
+ * against it instead of widening it. Inside a generic body TS cannot see that `Rule<Q>` narrows
+ * `Rule`, so the public signature is an overload and the implementation is erased.
  */
-export declare const VERSION: string;
+export declare function routeDecision<Q extends Questions>(decision: Decision<Q>, rules: NoInfer<Rule<Q>>[]): Decision<Q>;
+/** The portal's stale-Rule warning. Never runs inside `evaluateRules`. */
+export declare function validateRules(rules: Rule[], recipe: Recipe): RuleProblem[];
+//#endregion
+//#region src/judge.d.ts
+/** The gate's width when the caller sets none (cloud ADR 0005). */
+export declare const DEFAULT_MAX_IN_FLIGHT = 8;
+/** `prompt` is the sync door, `patient` the batch one. The client does the retrying. */
+type RetryMode = "prompt" | "patient";
+type JudgeErrorReason = "max_tokens_exceeded" | "api_usage_error" | "network" | "timeout" | "invalid_answers" | "unknown";
+/**
+ * The client gave up on a 429 or a 529. The fallback delay when `retryAfterMs` is `null`
+ * belongs to the caller.
+ */
+export declare class JudgeExhaustedError extends SiftlineError {
+  readonly retryAfterMs: number | null;
+  constructor(message: string, retryAfterMs: number | null, options?: ErrorOptions);
+}
+/** Everything else a judged call can fail on. The thrown value stays on `cause`. */
+export declare class JudgeError extends SiftlineError {
+  readonly status: number | null;
+  readonly reason: JudgeErrorReason;
+  constructor(message: string, reason: JudgeErrorReason, status: number | null, options?: ErrorOptions);
+}
+interface JudgeCallOptions {
+  /** Overrides the minted `crypto.randomUUID()`, which is what makes a replay byte-stable. */
+  id?: string;
+  signal?: AbortSignal;
+}
+interface Judge {
+  <Q extends Questions>(record: Record, recipe: Recipe<Q>, callOptions?: JudgeCallOptions): Promise<Decision<Q>>;
+}
+interface CreateJudgeOptions {
+  client: SystemOneClient;
+  retry: RetryMode;
+  maxInFlight?: number;
+  now?: () => Date;
+}
+export declare function createJudge(options: CreateJudgeOptions): Judge;
+//#endregion
+//#region src/fixtures.d.ts
+export declare const fixtureSchema: z.ZodObject<{
+  id: z.ZodOptional<z.ZodString>;
+  origin: z.ZodOptional<z.ZodString>;
+  by: z.ZodOptional<z.ZodString>;
+  state: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodNull]>;
+  expect: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>>;
+}, z.core.$strict>;
+/**
+ * One labelled Fixture. `expect` is `Answers<Q>` made partial, so it carries the Recipe's
+ * literal labels and level indices and needs no second mapping.
+ */
+interface Fixture<Q extends Questions = Questions> {
+  state: EntryType;
+  expect: Partial<Answers<Q>>;
+  id?: string;
+  origin?: string;
+  by?: string;
+}
+/** A bad line, named by its 1-based position. Core never reads files, so there is no path. */
+export declare class FixtureParseError extends SiftlineError {
+  readonly line: number;
+  constructor(message: string, line: number, options?: ErrorOptions);
+}
+export declare function parseFixture(line: string): Fixture;
+/** The only writer. One compact line, no trailing newline, absent optionals omitted. */
+export declare function serializeFixture(fixture: Fixture): string;
+export declare function parseFixtures(text: string): Fixture[];
+/** One Fixture that no longer fits its Recipe, keyed by its id or 1-based index. */
+interface FixtureProblem {
+  fixture: string;
+  problem: string;
+}
+export declare class FixtureValidationError extends SiftlineError {
+  readonly problems: FixtureProblem[];
+  constructor(problems: FixtureProblem[], options?: ErrorOptions);
+}
+/** The portal's stale-Fixture warning, and what the runner refuses to start on. */
+export declare function validateFixtures(fixtures: Fixture[], recipe: Recipe): FixtureProblem[];
 /**
- * Walking-skeleton export. It exists so the build, type, test, pack and publish path
- * can be proven before any Engine behaviour is written, and it will be deleted when
- * the first recipe lands.
+ * `NoInfer` keeps `Q` coming from the Recipe alone, so an unannotated Fixture literal is
+ * checked against it instead of widening it. The implementation is erased because inside a
+ * generic body TS cannot see that `Fixture<Q>` narrows `Fixture`.
  */
-export declare const PLACEHOLDER = "siftline-core-walking-skeleton";
-//#endregion
+export declare function defineFixtures<Q extends Questions>(recipe: Recipe<Q>, fixtures: NoInfer<Fixture<Q>>[]): Fixture<Q>[];
+/** `actual` is `undefined` when the Decision has no answer for the Question. */
+interface Mismatch {
+  question: string;
+  expected: AnswerValue;
+  actual: AnswerValue | undefined;
+}
+/** Pure. Strict equality per type, no tolerance, in `expect` insertion order. */
+export declare function compareAnswers(expect: Partial<Answers>, answers: Answers): Mismatch[];
+interface FixtureResult {
+  index: number;
+  id: string;
+  decision: Decision;
+  expect: Partial<Answers>;
+  mismatches: Mismatch[];
+  review: boolean;
+}
+interface QuestionAccuracy {
+  asserted: number;
+  matched: number;
+  accuracy: number | null;
+}
+interface TestReport {
+  recipe: {
+    name: string;
+    version: number;
+  };
+  model: string;
+  fixtures: FixtureResult[];
+  questions: {
+    [question: string]: QuestionAccuracy;
+  };
+  accuracy: number | null;
+}
+/**
+ * The pure half. A Question absent from a Fixture's `expect` leaves that Question's
+ * denominator; an unsure Decision counts on its answers, because the threshold is a routing
+ * knob and must not hide errors.
+ */
+export declare function scoreResults(results: FixtureResult[], recipe: Recipe): TestReport;
+interface TestRecipeOptions {
+  signal?: AbortSignal;
+  onResult?: (result: FixtureResult) => void;
+}
+/**
+ * Fires every Fixture through the Judge at once and lets the Judge's gate meter concurrency.
+ * The first `JudgeError` or `JudgeExhaustedError` aborts the rest and is rethrown: a partial
+ * accuracy is worse than none.
+ */
+export declare function testRecipe(judge: Judge, recipe: Recipe, fixtures: Fixture[], options?: TestRecipeOptions): Promise<TestReport>;
+//#endregion
+//#region src/index.d.ts
+/** The published version of `@siftline/core`, baked in at build time. */
+export declare const VERSION: string;
+//#endregion
+export { type AnswerResponse, type AnswerValue, type Answers, type ChoiceCriteria, type ChoiceQuestion, type ChoiceResponse, type CreateJudgeOptions, type Decision, type DefineRecipeInput, type Entry, type EntryType, type Evidence, type Fixture, type FixtureProblem, type FixtureResult, type JsonValue, type Judge, type JudgeCallOptions, type JudgeErrorReason, type Mismatch, type NoulQuestion, type NoulResponse, type Question, type QuestionAccuracy, type Questions, type Recipe, type Record, type RetryMode, type RetryPolicy, type Routing, type Rule, type RuleCondition, type RuleProblem, type ScoreCriteria, type ScoreQuestion, type ScoreResponse, type SiftlineErrorCode, type SystemOneCallOptions, type SystemOneClient, type SystemOneRequest, type SystemOneResult, type TestRecipeOptions, type TestReport, choice, defineRecipe, noul, parseRecipe, questionSchema, recipeSchema, score, serializeRecipe };