@nifrajs/testing 2.11.0 → 2.12.0

package/dist/trajectory.js

@@ -0,0 +1,200 @@
+import { runAgent, } from "@nifrajs/agent";
+import { createToolBudget } from "@nifrajs/core/tool-contract";
+import { createFailureLab } from "./failure-lab.js";
+const DEFAULT_SEED = 0x4e_49_46_52;
+const FAULT_KINDS = [
+    "tool-error",
+    "malformed-model-output",
+    "budget-pressure",
+    "approval-denial",
+    "cancellation",
+];
+/** Record the transcript emitted by a turn without adding a second execution recording path. */
+export async function createTrajectoryTranscript(transcript, options = {}) {
+    validateAgentTranscript(transcript);
+    const payload = {
+        version: 1,
+        turn: transcript,
+        ...(options.faultProfile === undefined ? {} : { faultProfile: options.faultProfile }),
+        ...(options.seed === undefined ? {} : { seed: options.seed }),
+    };
+    return Object.freeze({ ...payload, version: 1, digest: await digest(payload) });
+}
+/** Alias that reads naturally at a call site which has just completed a run. */
+export const recordTrajectory = createTrajectoryTranscript;
+export async function runTrajectory(definition, input, ports, options) {
+    const result = await runAgent(definition, input, ports, options);
+    const transcript = await createTrajectoryTranscript(result.transcript);
+    return Object.freeze({ result, transcript });
+}
+/**
+ * Replay a recorded run with local model decisions and dry-run tools. The supplied model port is
+ * never called. Fault schedules use the existing deterministic failure-lab controller.
+ */
+export async function replayTrajectory(definition, input, ports, transcript, options) {
+    validateAgentTranscript(transcript.turn);
+    const profile = options.faultProfile;
+    const seed = options.seed ?? DEFAULT_SEED;
+    const lab = createFailureLab({ seed, schedule: profile?.schedule ?? [] });
+    const faults = profile?.faults ?? [];
+    const counts = new Map();
+    const controller = new AbortController();
+    if (ports.signal?.aborted === true)
+        controller.abort();
+    ports.signal?.addEventListener("abort", () => controller.abort(), { once: true });
+    let responseIndex = 0;
+    let idSequence = 0;
+    const takeFault = (point, kind) => {
+        for (const candidateKind of kind === undefined ? FAULT_KINDS : [kind]) {
+            const key = `${point}:${candidateKind}`;
+            const occurrence = (counts.get(key) ?? 0) + 1;
+            counts.set(key, occurrence);
+            const fault = faults.find((candidate) => candidate.point === point &&
+                candidate.kind === candidateKind &&
+                (candidate.occurrence ?? 1) === occurrence);
+            if (fault !== undefined)
+                return fault;
+        }
+        return undefined;
+    };
+    const model = {
+        complete: async () => {
+            lab.checkpoint("trajectory.model");
+            const fault = takeFault("model");
+            if (fault?.kind === "malformed-model-output")
+                return { kind: "invalid" };
+            if (fault?.kind === "cancellation") {
+                controller.abort();
+                throw new Error("trajectory cancellation");
+            }
+            if (fault?.kind === "budget-pressure")
+                throw new Error("trajectory budget pressure");
+            const response = transcript.turn.responses[responseIndex++];
+            if (response === undefined)
+                throw new Error("trajectory transcript ended");
+            return lab.provider("trajectory.model", () => response);
+        },
+    };
+    const tools = definition.tools.map((tool) => wrapTool(tool, lab, () => takeFault("tool")));
+    const replayDefinition = { ...definition, tools };
+    let effectiveApproval = ports.approval;
+    if (effectiveApproval !== undefined) {
+        const approval = effectiveApproval;
+        effectiveApproval = {
+            request: async (request) => {
+                const fault = takeFault("effect", "approval-denial");
+                if (fault !== undefined)
+                    return { status: "denied", reason: "trajectory fault" };
+                return approval.request(request);
+            },
+        };
+    }
+    const pressuredBudget = createToolBudget({ limits: { calls: 0 } });
+    const effectivePorts = {
+        ...ports,
+        model,
+        dryRun: true,
+        signal: controller.signal,
+        idFactory: () => `trajectory-${seed}-${++idSequence}`,
+        ...(effectiveApproval === undefined ? {} : { approval: effectiveApproval }),
+        ...(faults.some((fault) => fault.kind === "budget-pressure")
+            ? { budget: pressuredBudget }
+            : {}),
+    };
+    const result = await runAgent(replayDefinition, input, effectivePorts, {
+        state: options.state,
+        ...(options.maxTurns === undefined ? {} : { maxTurns: options.maxTurns }),
+        ...(options.goal === undefined ? {} : { goal: options.goal }),
+    });
+    const invariantResults = checkTrajectoryInvariants(result);
+    const regressionIds = await Promise.all(invariantResults.map((invariant) => trajectoryRegressionId(transcript, profile?.name ?? "none", invariant.id)));
+    return Object.freeze({
+        result,
+        transcript,
+        faults: lab.evidence(),
+        invariants: Object.freeze(invariantResults),
+        regressionIds: Object.freeze(regressionIds),
+    });
+}
+export function checkTrajectoryInvariants(result, options = {}) {
+    const evidence = result.evidence;
+    const committedTools = evidence.filter((item) => item.kind === "tool" && item.outcome === "committed");
+    const ledger = committedTools.every((item) => typeof item.ledgerHead === "string" && item.ledgerHead.length > 0);
+    const deniedEffects = new Set(evidence
+        .filter((item) => item.code === "capability_denied" && item.effectId !== undefined)
+        .map((item) => item.effectId));
+    const capability = committedTools.every((item) => item.effectId === undefined || !deniedEffects.has(item.effectId));
+    const bounded = evidence.length <= (options.maxSteps ?? 256) &&
+        (result.status === "completed" || result.status === "suspended");
+    const resumable = result.status !== "suspended" ||
+        (result.state.status === "suspended" && result.pending.effectId.length > 0);
+    const snapshots = options.budgetSnapshots ?? [];
+    const budget = snapshots.every((snapshot, index) => {
+        const values = Object.values(snapshot);
+        if (values.some((value) => !Number.isFinite(value) || value < 0))
+            return false;
+        if (index === 0)
+            return true;
+        const previous = snapshots[index - 1] ?? {};
+        return Object.entries(snapshot).every(([axis, value]) => value <= (previous[axis] ?? value));
+    });
+    return Object.freeze([
+        { id: "ledger-evidence", ok: ledger, ...(ledger ? {} : { code: "effect_without_ledger" }) },
+        {
+            id: "capability-admission",
+            ok: capability,
+            ...(capability ? {} : { code: "capability_admission_failed" }),
+        },
+        { id: "budget-monotonic", ok: budget, ...(budget ? {} : { code: "budget_negative" }) },
+        { id: "bounded-stop", ok: bounded, ...(bounded ? {} : { code: "stop_bound_exceeded" }) },
+        {
+            id: "resumable-suspension",
+            ok: resumable,
+            ...(resumable ? {} : { code: "suspension_not_resumable" }),
+        },
+    ]);
+}
+export function assertTrajectoryInvariants(result, options = {}) {
+    const failures = checkTrajectoryInvariants(result, options).filter((invariant) => !invariant.ok);
+    if (failures.length > 0)
+        throw new Error(`trajectory invariants failed: ${failures.map((invariant) => invariant.code ?? invariant.id).join(",")}`);
+}
+export async function trajectoryRegressionId(transcript, faultProfile, invariant) {
+    if (faultProfile.trim() === "")
+        throw new TypeError("trajectory: fault profile name is required");
+    return digest({ transcript: transcript.digest, faultProfile, invariant });
+}
+function wrapTool(tool, lab, nextFault) {
+    return Object.freeze({
+        ...tool,
+        execute: async (input, context) => {
+            lab.checkpoint(`trajectory.tool.${tool.name}`);
+            const fault = nextFault();
+            if (fault?.kind === "tool-error" || fault?.kind === "budget-pressure")
+                throw new Error("trajectory tool fault");
+            if (fault?.kind === "cancellation")
+                throw new Error("trajectory cancellation");
+            lab.checkpoint(`trajectory.effect.${tool.name}`);
+            return tool.execute(input, context);
+        },
+    });
+}
+function validateAgentTranscript(value) {
+    if (value === null ||
+        typeof value !== "object" ||
+        value.version !== 1 ||
+        typeof value.turnId !== "string" ||
+        !Array.isArray(value.responses) ||
+        !Array.isArray(value.evidence)) {
+        throw new TypeError("trajectory: invalid agent transcript");
+    }
+}
+async function digest(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw new TypeError("trajectory: value is not serializable");
+    const bytes = new TextEncoder().encode(serialized);
+    const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return [...hash].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=trajectory.js.map

package/dist/trajectory.js.map

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

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@nifrajs/testing",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Contract-derived adversarial tests, runtime-matrix response conformance, and cookie-aware in-process sessions for Nifra apps.",
   "keywords": [
     "bun",
     "typescript",
     "nifra",
-    "web-framework",
-    "full-stack",
     "testing",
-    "ssr"
+    "contract-testing",
+    "property-testing",
+    "fuzzing",
+    "conformance",
+    "adversarial"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -42,9 +44,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@nifrajs/client": "2.11.0",
-    "@nifrajs/core": "2.11.0",
-    "@nifrajs/mock": "2.11.0"
+    "@nifrajs/client": "2.12.0",
+    "@nifrajs/agent": "2.12.0",
+    "@nifrajs/core": "2.12.0",
+    "@nifrajs/mcp": "2.12.0",
+    "@nifrajs/mock": "2.12.0"
   },
   "peerDependencies": {
     "zod": ">=4.0.0"

package/src/fault-profile.ts

@@ -0,0 +1,174 @@
+import {
+  type FailureDirective,
+  type FailureEvidence,
+  type FailureReplay,
+  type FailureScenario,
+  runFailureScenario,
+} from "./failure-lab.ts"
+
+/** A named adapter profile composed from the deterministic failure laboratory. */
+export interface FaultProfile {
+  readonly name: string
+  readonly scenarios: readonly FaultProfileScenario[]
+  /** Optional trajectory faults consumed by the agent trajectory harness. */
+  readonly faults?: readonly FaultProfileFault[]
+  /** Existing deterministic failure-lab schedule shared by trajectory runs. */
+  readonly schedule?: readonly FailureDirective[]
+}
+
+export type FaultProfileFaultKind =
+  | "tool-error"
+  | "malformed-model-output"
+  | "budget-pressure"
+  | "approval-denial"
+  | "cancellation"
+
+export interface FaultProfileFault {
+  readonly point: "model" | "tool" | "effect"
+  readonly kind: FaultProfileFaultKind
+  readonly occurrence?: number
+}
+
+export interface FaultProfileScenario extends FailureScenario<unknown> {
+  readonly id: string
+  readonly description: string
+}
+
+export interface FaultProfileScenarioReport {
+  readonly id: string
+  readonly description: string
+  readonly ok: boolean
+  readonly replay: FailureReplay
+  readonly evidence: readonly FailureEvidence[]
+  readonly error?: { readonly name: string; readonly kind?: string }
+}
+
+export interface FaultProfileReport {
+  readonly name: string
+  readonly ok: boolean
+  readonly scenarios: readonly FaultProfileScenarioReport[]
+}
+
+export interface RunFaultProfileOptions {
+  readonly seed?: number
+  readonly schedule?: readonly FailureDirective[]
+}
+
+const PROFILE_NAME = /^[a-z][a-z0-9._-]{0,127}$/
+
+function validateProfile(profile: FaultProfile): FaultProfile {
+  if (!PROFILE_NAME.test(profile.name)) {
+    throw new TypeError(`fault profile: invalid name ${JSON.stringify(profile.name)}`)
+  }
+  if (!Array.isArray(profile.scenarios) || profile.scenarios.length === 0) {
+    throw new TypeError("fault profile: at least one scenario is required")
+  }
+  if (profile.faults !== undefined) {
+    const seenFaults = new Set<string>()
+    for (const fault of profile.faults) {
+      if (fault.point !== "model" && fault.point !== "tool" && fault.point !== "effect") {
+        throw new TypeError("fault profile: invalid trajectory fault point")
+      }
+      if (
+        ![
+          "tool-error",
+          "malformed-model-output",
+          "budget-pressure",
+          "approval-denial",
+          "cancellation",
+        ].includes(fault.kind)
+      ) {
+        throw new TypeError("fault profile: invalid trajectory fault kind")
+      }
+      if (
+        fault.occurrence !== undefined &&
+        (!Number.isSafeInteger(fault.occurrence) || fault.occurrence < 1)
+      ) {
+        throw new RangeError("fault profile: trajectory fault occurrence must be positive")
+      }
+      const identity = `${fault.point}:${fault.kind}:${fault.occurrence ?? 1}`
+      if (seenFaults.has(identity))
+        throw new Error(`fault profile: duplicate trajectory fault ${identity}`)
+      seenFaults.add(identity)
+    }
+  }
+  const ids = new Set<string>()
+  const scenarios = profile.scenarios.map((scenario) => {
+    if (!PROFILE_NAME.test(scenario.id)) {
+      throw new TypeError(`fault profile: invalid scenario id ${JSON.stringify(scenario.id)}`)
+    }
+    if (ids.has(scenario.id)) {
+      throw new Error(`fault profile: duplicate scenario id ${JSON.stringify(scenario.id)}`)
+    }
+    if (scenario.description.trim() === "") {
+      throw new Error(`fault profile: scenario ${JSON.stringify(scenario.id)} needs a description`)
+    }
+    if (typeof scenario.execute !== "function" || typeof scenario.verify !== "function") {
+      throw new TypeError(
+        `fault profile: scenario ${JSON.stringify(scenario.id)} is not executable`,
+      )
+    }
+    ids.add(scenario.id)
+    return Object.freeze({
+      ...scenario,
+      description: scenario.description.trim(),
+    })
+  })
+  return Object.freeze({
+    name: profile.name,
+    scenarios: Object.freeze(scenarios),
+    ...(profile.faults === undefined
+      ? {}
+      : { faults: Object.freeze(profile.faults.map((fault) => Object.freeze({ ...fault }))) }),
+    ...(profile.schedule === undefined ? {} : { schedule: Object.freeze([...profile.schedule]) }),
+  })
+}
+
+/** Validate and freeze a reusable fault profile. */
+export function defineFaultProfile(profile: FaultProfile): FaultProfile {
+  return validateProfile(profile)
+}
+
+/** Run every profile scenario with the same deterministic seed and failure schedule. */
+export async function runFaultProfile(
+  profile: FaultProfile,
+  options: RunFaultProfileOptions = {},
+): Promise<FaultProfileReport> {
+  const checked = validateProfile(profile)
+  const scenarios: FaultProfileScenarioReport[] = []
+  for (const scenario of checked.scenarios) {
+    const result = await runFailureScenario(scenario, {
+      ...(options.seed === undefined ? {} : { seed: options.seed }),
+      schedule: options.schedule ?? [],
+    })
+    scenarios.push({
+      id: scenario.id,
+      description: scenario.description,
+      ok: result.ok,
+      replay: result.replay,
+      evidence: result.evidence,
+      ...(result.error === undefined ? {} : { error: result.error }),
+    })
+  }
+  return Object.freeze({
+    name: checked.name,
+    ok: scenarios.every((scenario) => scenario.ok),
+    scenarios: Object.freeze(scenarios),
+  })
+}
+
+/** A small smoke profile for consumers that only need to verify the harness wiring. */
+export const referenceFaultProfile = defineFaultProfile({
+  name: "reference",
+  scenarios: [
+    {
+      id: "checkpoint",
+      name: "reference-checkpoint",
+      description: "the reference adapter reaches a deterministic checkpoint",
+      execute(lab) {
+        lab.checkpoint("reference.checkpoint")
+      },
+      verify: () => true,
+    },
+  ],
+})

package/src/idempotency.ts

@@ -0,0 +1,89 @@
+import type { SealedEffectLedger } from "@nifrajs/core/ledger"
+
+export type EffectLedger = SealedEffectLedger
+
+export interface IdempotencyDivergence {
+  readonly step: number
+  readonly field: string
+  readonly first: unknown
+  readonly second: unknown
+}
+
+export interface IdempotencyProof {
+  readonly ok: boolean
+  readonly divergences: readonly IdempotencyDivergence[]
+}
+
+interface CanonicalLedger {
+  readonly method: string
+  readonly path: string
+  readonly declared: readonly string[]
+  readonly entries: readonly Readonly<Record<string, unknown>>[]
+}
+
+function canonicalize(ledger: EffectLedger): CanonicalLedger {
+  return {
+    method: ledger.method,
+    path: ledger.path,
+    declared: [...ledger.declared],
+    entries: ledger.entries.map((entry) => {
+      const value: Record<string, unknown> = {
+        seq: entry.seq,
+        ...(entry.effectId === undefined ? {} : { effectId: entry.effectId }),
+        capability: entry.capability,
+        phase: entry.phase,
+        ...(entry.target === undefined ? {} : { target: entry.target }),
+        ...(entry.cost === undefined ? {} : { cost: entry.cost }),
+        ...(entry.digest === undefined ? {} : { digest: entry.digest }),
+        ...(entry.error === undefined ? {} : { error: entry.error }),
+      }
+      return value
+    }),
+  }
+}
+
+function flatten(value: unknown, path = ""): Array<{ path: string; value: unknown }> {
+  if (Array.isArray(value))
+    return value.flatMap((item, index) => flatten(item, `${path}[${index}]`))
+  if (typeof value === "object" && value !== null) {
+    return Object.entries(value).flatMap(([key, item]) =>
+      flatten(item, path ? `${path}.${key}` : key),
+    )
+  }
+  return [{ path, value }]
+}
+
+/** Run a token-only effect workload repeatedly and report the first stable replay differences. */
+export async function proveIdempotency(options: {
+  readonly run: () => Promise<EffectLedger> | EffectLedger
+  readonly runs?: number
+}): Promise<IdempotencyProof> {
+  const runs = options.runs ?? 2
+  if (!Number.isSafeInteger(runs) || runs < 2)
+    throw new RangeError("idempotency runs must be at least 2")
+  const ledgers: CanonicalLedger[] = []
+  for (let index = 0; index < runs; index++) ledgers.push(canonicalize(await options.run()))
+  const first = flatten(ledgers[0])
+  const divergences: IdempotencyDivergence[] = []
+  for (let run = 1; run < ledgers.length; run++) {
+    const current = flatten(ledgers[run])
+    const max = Math.max(first.length, current.length)
+    for (let step = 0; step < max; step++) {
+      const left = first[step]
+      const right = current[step]
+      if (
+        left?.path === right?.path &&
+        JSON.stringify(left?.value) === JSON.stringify(right?.value)
+      )
+        continue
+      divergences.push({
+        step,
+        field: left?.path ?? right?.path ?? "ledger",
+        first: left?.value,
+        second: right?.value,
+      })
+      break
+    }
+  }
+  return Object.freeze({ ok: divergences.length === 0, divergences: Object.freeze(divergences) })
+}

package/src/index.ts

@@ -65,6 +65,24 @@ export {
   type FailureScenarioReport,
   runFailureScenario,
 } from "./failure-lab.ts"
+export {
+  defineFaultProfile,
+  type FaultProfile,
+  type FaultProfileFault,
+  type FaultProfileFaultKind,
+  type FaultProfileReport,
+  type FaultProfileScenario,
+  type FaultProfileScenarioReport,
+  type RunFaultProfileOptions,
+  referenceFaultProfile,
+  runFaultProfile,
+} from "./fault-profile.ts"
+export {
+  type EffectLedger,
+  type IdempotencyDivergence,
+  type IdempotencyProof,
+  proveIdempotency,
+} from "./idempotency.ts"
 export {
   assertIncidentReplays,
   type CapturedRequest,
@@ -82,3 +100,26 @@ export {
   shapeOf,
 } from "./incident.ts"
 export { type AppLike, type TestSession, type TestSessionOptions, testSession } from "./session.ts"
+export {
+  httpToolAdapter,
+  inProcessToolAdapter,
+  mcpToolAdapter,
+  testToolAdapter,
+} from "./tool-contract.ts"
+export {
+  assertTrajectoryInvariants,
+  type CreateTrajectoryTranscriptOptions,
+  checkTrajectoryInvariants,
+  createTrajectoryTranscript,
+  type ReplayTrajectoryOptions,
+  recordTrajectory,
+  replayTrajectory,
+  runTrajectory,
+  type TrajectoryInvariantId,
+  type TrajectoryInvariantOptions,
+  type TrajectoryInvariantResult,
+  type TrajectoryReplayResult,
+  type TrajectoryRun,
+  type TrajectoryTranscript,
+  trajectoryRegressionId,
+} from "./trajectory.ts"