trace-weave

Japanese version: README.ja.md

Finite-trace temporal test oracle framework based on LTLf for TypeScript.

trace-weave lets you describe temporal properties over event traces and verify them against finite executions. It is designed for cases where single-step assertions are too weak, such as request/response ordering, bounded eventuality, and value correlation across events.

Runnable repository examples live in examples/README.md. The full guide map is in docs/README.md. The AI-agent install guide is in docs/skills.md.

Requirements

• Node.js 20 or later
• ESM-only package

Node Support Policy

• trace-weave 0.x supports Node.js 20 or later.
• Node.js 20 support remains in place through the upstream Node.js 20 end-of-life date, April 30, 2026.
• After April 30, 2026, a later release may raise the minimum supported version to Node.js 22 or later. Any such change will be called out in the release notes.

Installation

npm install @atsumell/trace-weave

Optional peer dependencies:

npm install fast-check vitest

Quick Example

import { predicate, always, implies, eventually } from "@atsumell/trace-weave/builder";
import { predicateId } from "@atsumell/trace-weave/core";
import { runOracle } from "@atsumell/trace-weave/monitor";

type AppEvent = { type: string };

const isRequest = predicateId("isRequest");
const isResponse = predicateId("isResponse");

const formula = always(
  implies(predicate(isRequest), eventually(predicate(isResponse))),
);

const result = runOracle(
  formula,
  {
    predicates: {
      [isRequest]: (event) => event.type === "request",
      [isResponse]: (event) => event.type === "response",
    },
    selectors: {},
  },
  [{ type: "request" }, { type: "response" }],
);

console.log(result.verdict); // "satisfied"

Modules

• @atsumell/trace-weave/core: IDs, types, verdict algebra, runtime interfaces
• @atsumell/trace-weave/builder: temporal formula builders
• @atsumell/trace-weave/compiler: compile, validate, and print formula documents
• @atsumell/trace-weave/monitor: batch and online evaluation
• @atsumell/trace-weave/patterns: higher-level temporal patterns
• @atsumell/trace-weave/fast-check: property-based testing helpers
• @atsumell/trace-weave/vitest: custom matchers
• @atsumell/trace-weave/ai: report formatting and AI-oriented helpers

Development

npm run lint
npm run skills:validate
npm run typecheck
npm test
npm run build
npm run pack:smoke

Documentation

• Docs Index
• Getting Started
• Examples
• AI Skill
• Formulas
• Monitor
• Patterns
• Capture
• fast-check Integration
• Vitest Integration
• AI Integration
• API Reference

License

MIT