@archmax-ai/harness 0.0.0

package/dist/sessions/summary.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { hasUsage } from "../core/usage.js";
+import { isReservedRootName } from "../core/zones.js";
+import { classifyStatus, parkedStateOf, usageSummarySchema, variableEntrySchema, } from "../workflow/state.js";
+import { parentSessionIdOf } from "./scope.js";
+/**
+ * Project a session's latest checkpoint into a {@link SessionSummary} using only
+ * `getTuple`, so it works for **any** `BaseCheckpointSaver`. Session resolution
+ * depends on this answer being real: `null` means "this session has not run yet".
+ */
+export async function summarizeCheckpointedSession(checkpointer, sessionId) {
+    const tuple = await checkpointer.getTuple({ configurable: { thread_id: sessionId } });
+    if (!tuple)
+        return null;
+    const values = (tuple.checkpoint.channel_values ?? {});
+    const pendingDecision = values.pendingDecision;
+    const pendingInput = values.pendingInput;
+    const parkedAt = parkedStateOf(pendingDecision) || parkedStateOf(pendingInput);
+    const status = typeof values.status === "string" ? values.status : undefined;
+    // Parsed rather than cast: an older or malformed checkpoint reads as "none"
+    // instead of failing a listing.
+    const parsedVariables = z.record(z.string(), variableEntrySchema).safeParse(values.variables);
+    const variables = parsedVariables.success ? parsedVariables.data : undefined;
+    const parsedUsage = usageSummarySchema.safeParse(values.usage);
+    const usage = parsedUsage.success ? parsedUsage.data : undefined;
+    const parent = parentSessionIdOf(sessionId);
+    return {
+        sessionId,
+        status,
+        classification: classifyStatus(status),
+        workflowState: typeof values.workflowState === "string" ? values.workflowState : undefined,
+        specHash: typeof values.specHash === "string" ? values.specHash : undefined,
+        ...(parkedAt ? { state: parkedAt, node: parkedAt } : {}),
+        ...(typeof pendingInput?.reason === "string" ? { waitReason: pendingInput.reason } : {}),
+        ...(typeof pendingInput?.resumeAt === "string" ? { resumeAt: pendingInput.resumeAt } : {}),
+        ...(variables && Object.keys(variables).length > 0 ? { variables } : {}),
+        ...(usage && hasUsage(usage) ? { usage } : {}),
+        ...(parent ? { parentSessionId: parent } : {}),
+    };
+}
+/**
+ * Enumerate durable sessions by listing the session store's root (one
+ * `<sessionId>/` folder per session) and projecting each latest checkpoint.
+ * Runs outside any bound session, so the listing is the raw store root: reserved
+ * root names (authored mounts, `_specs/`, session areas) and sessions without a
+ * readable checkpoint are skipped.
+ */
+export async function listSessions(workspace, checkpointer) {
+    const entries = await workspace.listDir("");
+    const sessionIds = entries
+        .map((entry) => String(entry.path ?? "").replace(/\/+$/, "").split("/").pop() ?? "")
+        .filter((sessionId) => sessionId && !isReservedRootName(sessionId));
+    const summaries = await Promise.all(sessionIds.map((id) => summarizeCheckpointedSession(checkpointer, id)));
+    return summaries.filter((summary) => summary !== null);
+}
+//# sourceMappingURL=summary.js.map

package/dist/sessions/summary.js.map

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

package/dist/testing/assertions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Host-side evaluation of a case's assertions against a driven turn's
+ * {@link SessionView}. Every assertion the case format offers is a hard failure —
+ * including `grade`, whose declared `atLeast` is the author's bar, not a note —
+ * so a record's `status` is the only thing verdict reduction and the CLI's
+ * test view need to read.
+ */
+import type { SessionView } from "../workflow/session-view.js";
+import type { AssertionRecord } from "./runner.js";
+import type { CaseExpectation } from "./case-schema.js";
+import { type JudgeEvidence, type JudgeResult } from "./grade.js";
+/** Scores one closed-QA criterion (wired to the suite's grading model). */
+export type GradeFn = (criteria: string, evidence: JudgeEvidence) => Promise<JudgeResult>;
+/** Whether a failure of this assertion kind halts the rest of the case. */
+export declare function haltsCaseOnFailure(assert: CaseExpectation["assert"]): boolean;
+/**
+ * Describe an assertion step that never ran. One record per step, never one per
+ * token: an un-run `reply` with three tokens would have produced three records,
+ * but the engine did not run it and does not invent outcomes it never computed.
+ */
+export declare function notExecutedRecord(expect: CaseExpectation, step: number): AssertionRecord;
+/**
+ * Evaluate one turn's expectations. `step` is the index, in the case
+ * document's flat `steps` list, of the step these entries came from; every
+ * record produced here is stamped with it, so attribution never depends on
+ * how many records an expectation happens to emit. The optional `grade`
+ * scores `grade` entries; when absent (no `tests.judge` in workflow.yaml), a
+ * grade entry records an actionable failure instead of silently passing.
+ */
+export declare function evaluateExpectations(entries: readonly CaseExpectation[], view: SessionView, step: number, grade?: GradeFn): Promise<AssertionRecord[]>;

package/dist/testing/assertions.js

@@ -0,0 +1,231 @@
+import { deepEqual, partialMatch } from "../core/match.js";
+import { judgeEvidenceFromView } from "./grade.js";
+import { resolvePath } from "../machine/variables.js";
+/**
+ * The **structural** assertions: the ones that assert where the session went.
+ * Once one of them fails, every later step would drive or grade a session the
+ * case no longer describes — a `decide` after a failed `parked` cannot succeed,
+ * and a `reply` check after a failed `reachedState` grades the wrong state's
+ * output — so a failure here halts the case.
+ *
+ * The content assertions (`reply`, `calledTool`, `notCalledTool`, `usedNoTools`,
+ * `grade`) are deliberately absent: a wrong reply is a defect in the turn, not
+ * evidence that the session stopped being the one under test.
+ */
+const STRUCTURAL_ASSERTS = new Set([
+    "succeeded",
+    "parked",
+    "reachedState",
+    "trail",
+    "noTraversal",
+    "triggerArrival",
+    "variables",
+]);
+/** Whether a failure of this assertion kind halts the rest of the case. */
+export function haltsCaseOnFailure(assert) {
+    return STRUCTURAL_ASSERTS.has(assert);
+}
+/**
+ * Describe an assertion step that never ran. One record per step, never one per
+ * token: an un-run `reply` with three tokens would have produced three records,
+ * but the engine did not run it and does not invent outcomes it never computed.
+ */
+export function notExecutedRecord(expect, step) {
+    return {
+        kind: expect.assert,
+        threshold: expect.assert === "grade" ? expect.atLeast : null,
+        pass: false,
+        status: "not-executed",
+        step,
+    };
+}
+/**
+ * Every assistant message in the view, newest last. Reply assertions match
+ * against this whole transcript rather than only the final reply: a session
+ * that parks at a human state often closes with a short "moving on" message
+ * while the substantive answer came one message earlier.
+ */
+function assistantTranscript(view) {
+    const parts = [];
+    for (const e of view.events) {
+        if (e.type === "message.completed" && e.data && e.data.message) {
+            parts.push(String(e.data.message));
+        }
+    }
+    if (parts.length === 0 && view.reply)
+        parts.push(String(view.reply));
+    return parts.join("\n");
+}
+function tokenMatches(token, text) {
+    return token.regex ? token.regex.test(text) : text.includes(token.raw);
+}
+function matchesToolCall(calls, name, input, status) {
+    return calls.some((c) => c.name === name &&
+        (status === undefined || c.status === status) &&
+        (input === undefined || partialMatch(input, c.input)));
+}
+function trailOf(view) {
+    return Array.isArray(view.auditTrail) ? view.auditTrail : [];
+}
+/**
+ * Evaluate one turn's expectations. `step` is the index, in the case
+ * document's flat `steps` list, of the step these entries came from; every
+ * record produced here is stamped with it, so attribution never depends on
+ * how many records an expectation happens to emit. The optional `grade`
+ * scores `grade` entries; when absent (no `tests.judge` in workflow.yaml), a
+ * grade entry records an actionable failure instead of silently passing.
+ */
+export async function evaluateExpectations(entries, view, step, grade) {
+    const records = [];
+    const trail = trailOf(view);
+    // Closes over `step`, so it is the single place a deterministic record is
+    // built and there is no way to build one without its step or its status.
+    const gate = (kind, pass, detail) => ({
+        kind,
+        threshold: null,
+        pass,
+        status: pass ? "passed" : "failed",
+        step,
+        ...(detail !== undefined ? { detail } : {}),
+    });
+    for (const entry of entries) {
+        switch (entry.assert) {
+            case "succeeded":
+                records.push(gate("succeeded", !view.failed && !view.parked));
+                break;
+            case "parked":
+                // A bare `parked` accepts either channel; a pinned one must match the
+                // channel — and, when named, the state — the session actually suspended in.
+                records.push(gate("parked", view.parked &&
+                    (entry.channel === undefined || view.parkedChannel === entry.channel) &&
+                    (entry.node === undefined || view.node === entry.node), [entry.channel, entry.node].filter(Boolean).join(" in ") || undefined));
+                break;
+            case "reachedState":
+                // Committed transitions only (any kind except `trigger`): the arrival
+                // step is recorded before the entry state's `before` gate runs, so a
+                // vetoed-entry session never "reaches" the state the gate refused.
+                records.push(gate("reachedState", trail.some((s) => s.kind !== "trigger" && s.to === entry.state), entry.state));
+                break;
+            case "reply": {
+                const transcript = assistantTranscript(view);
+                for (const token of entry.includes) {
+                    records.push(gate("reply.includes", tokenMatches(token, transcript), token.raw));
+                }
+                for (const token of entry.excludes) {
+                    records.push(gate("reply.excludes", !tokenMatches(token, transcript), token.raw));
+                }
+                break;
+            }
+            case "calledTool":
+                records.push(gate("calledTool", matchesToolCall(view.toolCalls, entry.name, entry.input), entry.name));
+                break;
+            case "notCalledTool":
+                records.push(gate("notCalledTool", !matchesToolCall(view.toolCalls, entry.name, entry.input), entry.name));
+                break;
+            case "blockedTool":
+                // Refused by governance — the run view separates a policy rejection
+                // from a tool that ran and failed, so a case can assert the guard fired
+                // rather than infer it from an absence (which is what `notCalledTool`
+                // measures: an agent that never reached for the thing tested nothing).
+                records.push(gate("blockedTool", matchesToolCall(view.toolCalls, entry.name, entry.input, "rejected"), entry.name));
+                break;
+            case "usedNoTools":
+                records.push(gate("usedNoTools", view.toolCalls.length === 0));
+                break;
+            case "ranWorkflow": {
+                // Read from the trail, not from tool calls: a script's delegation never
+                // appears among the model's calls, and the trail's `sub-workflow` step
+                // is the session's whole durable record of the dispatch either way.
+                const matching = trail.filter((s) => s.kind === "sub-workflow" &&
+                    s.workflow === entry.workflow &&
+                    (s.status ?? "ok") === entry.status);
+                const ok = entry.count === undefined ? matching.length > 0 : matching.length === entry.count;
+                records.push(gate("ranWorkflow", ok, `${entry.workflow} (${entry.status}${entry.count === undefined ? "" : `, ${matching.length}/${entry.count}`})`));
+                break;
+            }
+            case "trail": {
+                const matching = trail.filter((s) => (entry.to === undefined || s.to === entry.to) &&
+                    (entry.stepKind === undefined || s.kind === entry.stepKind) &&
+                    (entry.reason === undefined || s.reason === entry.reason));
+                const wanted = [
+                    ...(entry.to !== undefined ? [`to=${entry.to}`] : []),
+                    ...(entry.stepKind !== undefined ? [`kind=${entry.stepKind}`] : []),
+                    ...(entry.reason !== undefined ? [`reason=${entry.reason}`] : []),
+                ].join(" ");
+                records.push(gate("trail", matching.length === entry.count, `${wanted} expected ${entry.count}, saw ${matching.length}`));
+                break;
+            }
+            case "noTraversal":
+                // A veto at entry leaves nothing but trigger-arrival steps.
+                records.push(gate("noTraversal", trail.every((s) => s.kind === "trigger"), "no committed transitions"));
+                break;
+            case "triggerArrival":
+                records.push(gate("triggerArrival", trail.some((s) => s.kind === "trigger" && s.reason === entry.trigger), entry.trigger));
+                break;
+            case "variables": {
+                for (const [name, expected] of Object.entries(entry.expect)) {
+                    const stored = view.variables?.[name];
+                    const path = entry.path?.[name];
+                    const label = path ? `${name}.${path}` : name;
+                    if (stored === undefined) {
+                        records.push(gate("variables", false, `${label} (not set)`));
+                        continue;
+                    }
+                    const actual = path ? resolvePath(stored.value, path.split(".")) : stored.value;
+                    if (path && actual === undefined) {
+                        records.push(gate("variables", false, `${label} (path does not resolve)`));
+                        continue;
+                    }
+                    const matched = deepEqual(actual, expected);
+                    records.push(gate("variables", matched, matched
+                        ? label
+                        : `${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`));
+                    const wantLocked = entry.locked?.[name];
+                    if (wantLocked !== undefined) {
+                        records.push(gate("variables", stored.locked === wantLocked, `${name} locked=${wantLocked} (actual ${stored.locked})`));
+                    }
+                }
+                break;
+            }
+            case "grade": {
+                const record = {
+                    kind: "grade.closedQA",
+                    threshold: entry.atLeast,
+                    pass: false,
+                    status: "failed",
+                    score: 0,
+                    detail: entry.closedQA,
+                    step,
+                };
+                if (!grade) {
+                    record.detail = `${entry.closedQA} (grading model unavailable: declare 'tests: { judge: ... }' in workflow.yaml)`;
+                }
+                else {
+                    try {
+                        // The grader scores the turn's evidence — its final reply plus the
+                        // chronological record of what it did to get there — built from the
+                        // same view every other assertion on this step reads, so a `grade`
+                        // and a `calledTool` here can never disagree about what happened.
+                        const result = await grade(entry.closedQA, judgeEvidenceFromView(view));
+                        record.score = Math.max(0, Math.min(1, Number(result.score ?? 0)));
+                        if (result.reason)
+                            record.detail = `${entry.closedQA}: ${result.reason}`;
+                    }
+                    catch (err) {
+                        record.detail = `${entry.closedQA}: ${err.message}`;
+                    }
+                }
+                // The case author's declared bar decides, not the grading model's own
+                // boolean: `atLeast` is what the verdict compares against, so deciding
+                // the record any other way lets a record contradict the verdict shown
+                // beside it. A miss fails the case like any other assertion.
+                record.status = (record.score ?? 0) >= entry.atLeast ? "passed" : "failed";
+                record.pass = record.status === "passed";
+                records.push(record);
+                break;
+            }
+        }
+    }
+    return records;
+}
+//# sourceMappingURL=assertions.js.map

package/dist/testing/assertions.js.map

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

package/dist/testing/case-document.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The case document model: the parsed shape a case file yields, the error a
+ * malformed one raises, and the path conventions that name a case and its
+ * fixtures. The grammar that produces it lives in `case-schema.ts`.
+ */
+import type { ToolMockSpec } from "../core/tool-mocks.js";
+/** A validation failure in a case document, addressed by file and location. */
+export declare class CaseSchemaError extends Error {
+    readonly file: string;
+    constructor(file: string, at: string | null, detail: string);
+}
+export interface CaseTriggerDecl {
+    id: string;
+}
+/** A workspace seed entry: inline content, or content copied from a file. */
+export type CaseWorkspaceEntry = {
+    source: "inline";
+    content: unknown;
+} | {
+    source: "file";
+    from: string;
+};
+/** A reply-content token: a plain substring or a compiled `/pattern/flags`. */
+export interface ReplyToken {
+    raw: string;
+    regex?: RegExp;
+}
+export type CaseExpectation = {
+    assert: "succeeded";
+} | {
+    assert: "parked";
+    channel?: "decision" | "input";
+    node?: string;
+} | {
+    assert: "reachedState";
+    state: string;
+} | {
+    assert: "reply";
+    includes: ReplyToken[];
+    excludes: ReplyToken[];
+} | {
+    assert: "calledTool";
+    name: string;
+    input?: Record<string, unknown>;
+} | {
+    assert: "notCalledTool";
+    name: string;
+    input?: Record<string, unknown>;
+}
+/** A call governance **refused** — the agent tried and was blocked. */
+ | {
+    assert: "blockedTool";
+    name: string;
+    input?: Record<string, unknown>;
+} | {
+    assert: "usedNoTools";
+} | {
+    assert: "ranWorkflow";
+    workflow: string;
+    status: "ok" | "error";
+    count?: number;
+} | {
+    assert: "trail";
+    to?: string;
+    stepKind?: string;
+    reason?: string;
+    count: number;
+} | {
+    assert: "noTraversal";
+} | {
+    assert: "triggerArrival";
+    trigger: string;
+} | {
+    assert: "variables";
+    expect: Record<string, unknown>;
+    path?: Record<string, string>;
+    locked?: Record<string, boolean>;
+}
+/** A model-scored assertion: the declared `atLeast` is the bar. */
+ | {
+    assert: "grade";
+    closedQA: string;
+    atLeast: number;
+}
+/** @deprecated `judge:` is parsed as `grade`; this member exists so a host's exhaustive switch keeps compiling for one release. It never occurs at runtime. */
+ | {
+    assert: "judge";
+    closedQA: string;
+    atLeast: number;
+};
+export type CaseAction = {
+    action: "send";
+    message: string;
+} | {
+    action: "decide";
+    to: string;
+    comment?: string;
+} | {
+    action: "deliver";
+    trigger: string;
+    variables?: Record<string, unknown>;
+};
+/** One entry of the flat `steps` list: an action, or an assertion bound to the nearest action above it. */
+export type CaseStep = {
+    kind: "action";
+    action: CaseAction;
+} | {
+    kind: "assert";
+    expect: CaseExpectation;
+};
+export interface CaseDocument {
+    /** Workspace-relative case file path (the case id source). */
+    file: string;
+    /** The case id: the file path relative to the tests dir, minus the extension. */
+    id: string;
+    /** Short one-line label for the case — what the CLI prints beside its verdict. */
+    title: string;
+    /** One or two sentences: the scenario driven and what is asserted. */
+    description: string;
+    skip?: string;
+    trigger?: CaseTriggerDecl;
+    /** Variables seeded for every driven turn — the case's own seeds. */
+    variables?: Record<string, unknown>;
+    workspace: Record<string, CaseWorkspaceEntry>;
+    mocks: ToolMockSpec[];
+    steps: CaseStep[];
+}
+export declare const TEST_FILE_EXTENSIONS: readonly [".test.yaml", ".test.yml"];
+/** Whether a path names a YAML case file. */
+export declare function isTestFile(path: string): boolean;
+/** Strip the `.test.yaml`/`.test.yml` extension from a case file path. */
+export declare function stripTestExtension(path: string): string;
+/** The case id for a file: its path relative to the tests dir, minus extension. */
+export declare function caseIdForFile(file: string, testsDir: string): string;
+/** Every `from:` reference a case declares, for fixture-existence checks. */
+export declare function collectFileReferences(doc: CaseDocument): string[];
+/**
+ * Reject a `from:` path that escapes the tests directory. Returns the
+ * normalized tests/-relative path.
+ */
+export declare function normalizeFixturePath(from: string, file: string): string;

package/dist/testing/case-document.js

@@ -0,0 +1,51 @@
+/** A validation failure in a case document, addressed by file and location. */
+export class CaseSchemaError extends Error {
+    file;
+    constructor(file, at, detail) {
+        super(`${file}: ${at ? `${at}: ` : ""}${detail}`);
+        this.name = "CaseSchemaError";
+        this.file = file;
+    }
+}
+export const TEST_FILE_EXTENSIONS = [".test.yaml", ".test.yml"];
+/** Whether a path names a YAML case file. */
+export function isTestFile(path) {
+    return TEST_FILE_EXTENSIONS.some((ext) => path.endsWith(ext));
+}
+/** Strip the `.test.yaml`/`.test.yml` extension from a case file path. */
+export function stripTestExtension(path) {
+    for (const ext of TEST_FILE_EXTENSIONS) {
+        if (path.endsWith(ext))
+            return path.slice(0, -ext.length);
+    }
+    return path;
+}
+/** The case id for a file: its path relative to the tests dir, minus extension. */
+export function caseIdForFile(file, testsDir) {
+    const rel = file.startsWith(`${testsDir}/`) ? file.slice(testsDir.length + 1) : file;
+    return stripTestExtension(rel);
+}
+/** Every `from:` reference a case declares, for fixture-existence checks. */
+export function collectFileReferences(doc) {
+    return Object.values(doc.workspace).flatMap((entry) => entry.source === "file" ? [entry.from] : []);
+}
+/**
+ * Reject a `from:` path that escapes the tests directory. Returns the
+ * normalized tests/-relative path.
+ */
+export function normalizeFixturePath(from, file) {
+    const out = [];
+    for (const segment of from.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            throw new CaseSchemaError(file, null, `'from: ${from}' escapes the tests directory`);
+        }
+        out.push(segment);
+    }
+    if (from.startsWith("/") || out.length === 0) {
+        throw new CaseSchemaError(file, null, `'from: ${from}' must be a tests/-relative file path`);
+    }
+    return out.join("/");
+}
+//# sourceMappingURL=case-document.js.map

package/dist/testing/case-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"case-document.js","sourceRoot":"","sources":["../../src/testing/case-document.ts"],"names":[],"mappings":"AAOA,+EAA+E;AAC/E,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,EAAiB,EAAE,MAAc;QACzD,KAAK,CAAC,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAoED,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,YAAY,EAAE,WAAW,CAAU,CAAC;AAEzE,6CAA6C;AAC7C,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,KAAK,MAAM,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,QAAgB;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrF,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,qBAAqB,CAAC,GAAiB;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CACpD,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAC5C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,IAAY;IAC7D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG;YAAE,SAAS;QAChD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,IAAI,+BAA+B,CAAC,CAAC;QACvF,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,IAAI,uCAAuC,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/dist/testing/case-schema.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { type CaseDocument, type CaseStep } from "./case-document.js";
+export { CaseSchemaError, TEST_FILE_EXTENSIONS, caseIdForFile, collectFileReferences, isTestFile, normalizeFixturePath, stripTestExtension, } from "./case-document.js";
+export type { CaseAction, CaseDocument, CaseExpectation, CaseStep, CaseTriggerDecl, CaseWorkspaceEntry, ReplyToken, } from "./case-document.js";
+/**
+ * Length budgets for the two prose fields. `title` is a label the CLI prints
+ * beside a verdict, so it has to fit a terminal line; `description` states the
+ * scenario and what is asserted in a sentence or two. Longer rationale belongs
+ * in a YAML comment above the document. Measured on whitespace-collapsed text
+ * so a folded (`>-`) and a literal (`|`) block of the same prose score alike.
+ */
+export declare const CASE_TITLE_MAX_LENGTH = 60;
+export declare const CASE_DESCRIPTION_MAX_LENGTH = 200;
+/** Every step key the grammar knows, actions first. `judge` is the deprecated alias of `grade`. */
+export declare const STEP_SCHEMAS: Record<string, z.ZodType<CaseStep>>;
+/** Parse and validate one case document. Throws {@link CaseSchemaError} on any structural violation. */
+export declare function parseCaseDocument(file: string, source: string, testsDir: string): CaseDocument;
+/**
+ * The YAML of a {@link CaseDocument}: the inverse of {@link parseCaseDocument},
+ * in the grammar's own key order (`title`, `description`, `skip`, `trigger`,
+ * `variables`, `workspace`, `mocks`, `steps`), so an editor that parses a file,
+ * edits the document and writes it back changes only what it edited. `file` and
+ * `id` are the file's, not the document's, and are not written. A reply token
+ * keeps its `/pattern/flags` spelling; a `judge` step is written as `grade`.
+ * Comments are not part of the document and are not preserved — a host that
+ * keeps a leading comment re-attaches it. Holds `parse(serialize(doc))` deep-equal
+ * to `doc` for every document the grammar accepts.
+ */
+export declare function serializeCaseDocument(doc: CaseDocument): string;