@zanii/certify 0.5.0 → 0.6.0

package/dist/suite.d.ts

@@ -4,6 +4,7 @@ import scenariosSchema from "./schemas/scenarios.schema.json";
 import suiteSchema from "./schemas/suite.schema.json";
 import { type SandboxDelegationPolicy } from "./sandbox-delegation.ts";
 import { type NormalizationPolicy } from "./normalization.ts";
+import { type TrajectorySuite } from "./trajectory.ts";
 export interface TeamReceiptPolicy {
     /** Explicitly trusted participants and their delegation-root owner keys; $agent denotes the tested agent. */
     members: {
@@ -247,8 +248,11 @@ export declare function validateSuite(suite: unknown, categories?: readonly stri
 export declare function validateScenarios(library: unknown, categories?: readonly string[]): ProfileCheck;
 /** scenarios.md section 3: the cases a library's scenarios run as (title and source dropped). */
 export declare function scenarioCases(library: ScenarioLibrary): SuiteCase[];
-/** The cases of a suite or a scenario library. */
-export declare const casesOf: (doc: Suite | ScenarioLibrary) => SuiteCase[];
+export type SuiteDocument = Suite | ScenarioLibrary | TrajectorySuite;
+/** Explicit additive dispatch; validateSuite keeps its original v1-only contract. */
+export declare function validateSuiteDocument(value: unknown, categories?: readonly string[]): ProfileCheck;
+/** Keep complete case objects, including trajectory fixtures, through maps/snapshots. */
+export declare const casesOf: (doc: SuiteDocument) => SuiteCase[];
 /**
  * Section 3: `jcsHash` of `{v: 1, suites}` with every loaded suite and scenario library sorted by
  * id. Throws when one is invalid, or when two share an id or a case (scenario) id.

package/dist/suite.js

@@ -7,6 +7,7 @@ import suiteSchema from "./schemas/suite.schema.json" with { type: "json" };
 import { isDid, isInt, isIso, isObj, ms, sortedUnique } from "./shared.js";
 import { verifySandboxDelegationPolicy } from "./sandbox-delegation.js";
 import { normalizationPolicyReasons } from "./normalization.js";
+import { validateTrajectorySuite } from "./trajectory.js";
 /** Section 2: the field each kind needs. */
 const FIELD = { not_contains: ["values"], contains_any: ["values"], tool_not_called: ["tools"], max_tool_calls: ["n"], all: ["checks"], judged: ["rubric"], within_delegation: [], no_scope_escalation: [], team_receipt: ["tool", "threshold"] };
 const ARGS = ["values", "tools", "n", "checks", "rubric", "tool", "threshold", "invocation", "policy"];
@@ -412,8 +413,24 @@ export function validateScenarios(library, categories) {
 export function scenarioCases(library) {
     return library.scenarios.map(({ title: _t, source: _s, ...c }) => c);
 }
-/** The cases of a suite or a scenario library. */
-export const casesOf = (doc) => (doc.type === "certify.scenarios" ? doc.scenarios : doc.cases);
+/** Explicit additive dispatch; validateSuite keeps its original v1-only contract. */
+export function validateSuiteDocument(value, categories) {
+    if (isObj(value) && value.type === "certify.suite")
+        return validateSuite(value, categories);
+    if (isObj(value) && value.type === "certify.scenarios")
+        return validateScenarios(value, categories);
+    if (isObj(value) && value.type === "certify.trajectory-suite")
+        return validateTrajectorySuite(value, categories);
+    return { ok: false, errors: ["$: unsupported suite document type"] };
+}
+/** Keep complete case objects, including trajectory fixtures, through maps/snapshots. */
+export const casesOf = (doc) => {
+    if (doc.type === "certify.scenarios")
+        return doc.scenarios;
+    if (doc.type === "certify.suite" || doc.type === "certify.trajectory-suite")
+        return doc.cases;
+    throw new Error("unsupported suite document type");
+};
 /**
  * Section 3: `jcsHash` of `{v: 1, suites}` with every loaded suite and scenario library sorted by
  * id. Throws when one is invalid, or when two share an id or a case (scenario) id.
@@ -422,7 +439,7 @@ export function suiteSnapshot(suites) {
     const ids = new Set();
     const cases = new Set();
     for (const s of suites) {
-        const r = isObj(s) && s.type === "certify.scenarios" ? validateScenarios(s) : validateSuite(s);
+        const r = validateSuiteDocument(s);
         const id = isObj(s) ? String(s.id) : "?";
         if (!r.ok)
             throw new Error(`suite ${id}: ${r.errors[0]}`);

package/dist/trajectory.d.ts

@@ -0,0 +1,216 @@
+import { type ProfileCheck } from "./profile.ts";
+import { type SuiteCase } from "./suite.ts";
+import type { NormalizationPolicy } from "./normalization.ts";
+import trajectorySchema from "./schemas/trajectory.schema.json";
+import { type TranscriptProvenance } from "./transcript-provenance.ts";
+export type TrajectoryScalar = string | number | boolean | null;
+export type TrajectoryState = {
+    key: string;
+    value: TrajectoryScalar;
+}[];
+export type TrajectoryRef = {
+    source: "literal";
+    value: TrajectoryScalar;
+} | {
+    source: "state" | "arg";
+    key: string;
+};
+export interface TrajectoryCondition {
+    left: TrajectoryRef;
+    op: "eq" | "ne" | "gte" | "lte";
+    right: TrajectoryRef;
+}
+export interface TrajectoryEffect {
+    op: "set" | "add";
+    key: string;
+    value: TrajectoryRef;
+}
+export interface TrajectoryArgument {
+    name: string;
+    type: "string" | "integer" | "boolean";
+    required: boolean;
+    enum?: TrajectoryScalar[];
+    minimum?: number;
+    maximum?: number;
+    max_length?: number;
+}
+export interface TrajectoryRule {
+    when: TrajectoryCondition[];
+    outcome: "ok" | "error";
+    result: string;
+    effects: TrajectoryEffect[];
+}
+export interface TrajectoryTool {
+    name: string;
+    description: string;
+    arguments: TrajectoryArgument[];
+    requires: TrajectoryCondition[];
+    rules: TrajectoryRule[];
+    spend?: {
+        amount_arg: string;
+        currency_arg: string;
+    };
+    idempotency_arg?: string;
+}
+export interface TrajectoryBudget {
+    max_rounds: number;
+    max_calls: number;
+    max_batch: number;
+    max_ms: number;
+    max_exchanges: number;
+    max_sent_bytes: number;
+    max_received_bytes: number;
+    max_reply_bytes: number;
+    max_result_bytes: number;
+    max_state_bytes: number;
+    max_trace_bytes: number;
+    currency: string;
+    max_spend_minor: number;
+}
+export interface TrajectoryCase extends SuiteCase {
+    fixture: {
+        initial_state: TrajectoryState;
+        tools: TrajectoryTool[];
+    };
+    budget: TrajectoryBudget;
+    terminal: {
+        any_of: TrajectoryCondition[][];
+        forbidden_outbound: string[];
+    };
+    transcript?: TranscriptProvenance;
+    family_id?: string;
+}
+export interface TrajectorySuite {
+    v: 1;
+    type: "certify.trajectory-suite";
+    purpose: "practice" | "certification";
+    visibility: "public" | "held-out";
+    mode: "simulated_workflow";
+    id: string;
+    version: number;
+    profiles?: string[];
+    cases: TrajectoryCase[];
+    rubrics?: {
+        id: string;
+        title: {
+            en: string;
+            ar: string;
+        };
+        pass: {
+            en: string;
+            ar: string;
+        };
+        fail: {
+            en: string;
+            ar: string;
+        };
+    }[];
+}
+export interface TrajectoryCall {
+    call_id: string;
+    name: string;
+    raw_arguments: string;
+}
+export type TrajectoryEvent = {
+    kind: "assistant";
+    round: number;
+    text: string;
+} | {
+    kind: "rejected_batch";
+    round: number;
+    raw_calls: string;
+    finding: string;
+} | {
+    kind: "tool";
+    round: number;
+    call_id: string;
+    name: string;
+    raw_arguments: string;
+    arguments: Record<string, TrajectoryScalar> | null;
+    outcome: "ok" | "error" | "blocked" | "replayed";
+    applied: boolean;
+    result: string;
+    state_before: string;
+    state_after: string;
+    spend_minor: number;
+    findings: string[];
+};
+export interface TrajectoryTrace {
+    v: 1;
+    type: "certify.trajectory-trace";
+    purpose: "practice" | "certification";
+    mode: "simulated_workflow";
+    case_id: string;
+    case_hash: string;
+    initial_state_hash: string;
+    final_state: TrajectoryState;
+    events: TrajectoryEvent[];
+    terminal: {
+        reason: "completed" | "budget" | "cancelled" | "provider_error" | "lab_error" | "invalid_call";
+        complete: boolean;
+    };
+    usage: {
+        rounds: number;
+        calls: number;
+        exchanges: number;
+        sent_bytes: number;
+        received_bytes: number;
+        elapsed_ms: number;
+        spend_minor: number;
+        currency: string;
+    };
+}
+export interface TrajectoryCheck {
+    passed: boolean;
+    completion: boolean;
+    safety: boolean;
+    evidence_complete: boolean;
+    lab_error: boolean;
+    final_answer: "pass" | "fail" | "pending";
+    findings: string[];
+}
+export declare const TRAJECTORY_LIMITS: Readonly<{
+    suite_bytes: 1048576;
+    cases: 64;
+    state_keys: 64;
+    tools: 16;
+    arguments: 16;
+    rules: 16;
+    conditions: 16;
+    effects: 16;
+    max_rounds: 10;
+    max_calls: 16;
+    max_batch: 4;
+    max_ms: 60000;
+    max_exchanges: 64;
+    max_sent_bytes: 2097152;
+    max_received_bytes: 2097152;
+    max_reply_bytes: 65536;
+    max_result_bytes: 16384;
+    max_state_bytes: 65536;
+    max_trace_bytes: 262144;
+}>;
+/** Discriminator for already validated cases, never an alternative to document validation. */
+export declare function isTrajectoryCase(value: unknown): value is TrajectoryCase;
+/** Canonical state identity ignores declaration order, never state values. */
+export declare function trajectoryStateHash(state: TrajectoryState): string;
+export declare function trajectoryCaseHash(c: TrajectoryCase): string;
+export declare function trajectorySuiteHash(suite: TrajectorySuite): string;
+/** Only local declarations become offered tools; no duplicated tool authority on the case wire. */
+export declare function trajectoryTools(c: TrajectoryCase): NonNullable<SuiteCase["tools"]>;
+/** Arguments are already decoded JSON; callers preserve the original raw string separately. */
+export declare function validateTrajectoryArguments(tool: TrajectoryTool, args: unknown): ProfileCheck;
+/** Closed flat JSON parser also rejects duplicate keys that JSON.parse would silently overwrite. */
+export declare function parseTrajectoryArguments(tool: TrajectoryTool, raw: string): ProfileCheck & {
+    arguments: Record<string, TrajectoryScalar> | null;
+};
+export declare function resolveTrajectoryRef(ref: TrajectoryRef, state: TrajectoryState, args?: Record<string, TrajectoryScalar>): TrajectoryScalar;
+export declare function trajectoryConditions(conditions: readonly TrajectoryCondition[], state: TrajectoryState, args?: Record<string, TrajectoryScalar>): boolean;
+export declare function validateTrajectorySuite(value: unknown, categories?: readonly string[]): ProfileCheck;
+export declare function validateTrajectoryTrace(value: unknown): ProfileCheck;
+/** Replay is required for evidence completeness; imported claimed effects/findings alone prove nothing. */
+export declare function checkTrajectory(c: TrajectoryCase, value: unknown, options?: {
+    replay?: (c: TrajectoryCase, trace: TrajectoryTrace) => ProfileCheck;
+    normalizationPolicy?: NormalizationPolicy;
+}): TrajectoryCheck;
+export { trajectorySchema };