feat: deterministic simulation testing (DST) framework

.changeset/dst-deterministic-simulation-testing.md

@@ -0,0 +1,11 @@
+---
+"effect": minor
+"@effect/vitest": minor
+---
+
+feat: deterministic simulation testing (DST) framework
+
+- Add `stepOne()` to `ControlledScheduler` for fine-grained task execution
+- Add configurable clock source to `FiberId.unsafeMake()` for deterministic fiber identity
+- Add `DSTScheduler` module with seeded PRNG scheduling, deterministic runtime, event logging, and liveness checking
+- Add `it.dst()` test primitive to `@effect/vitest` for multi-seed property-based concurrency testing

packages/dst/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@effect/dst",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Deterministic Simulation Testing with V8 profiling and git blame attribution for Effect",
+  "homepage": "https://effect.website",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Effect-TS/effect.git",
+    "directory": "packages/dst"
+  },
+  "bugs": {
+    "url": "https://github.com/Effect-TS/effect/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "directory": "dist",
+    "linkDirectory": false
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts",
+    "./internal/*": null
+  },
+  "scripts": {
+    "build": "pnpm build-esm && pnpm build-annotate && pnpm build-cjs && build-utils pack-v3",
+    "build-esm": "tsc -b tsconfig.build.json",
+    "build-cjs": "babel build/esm --plugins @babel/transform-export-namespace-from --plugins @babel/transform-modules-commonjs --out-dir build/cjs --source-maps",
+    "build-annotate": "babel build/esm --plugins annotate-pure-calls --out-dir build/esm --source-maps",
+    "check": "tsc -b tsconfig.json",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  },
+  "peerDependencies": {
+    "@effect/platform": "workspace:^",
+    "effect": "workspace:^"
+  },
+  "devDependencies": {
+    "@effect/platform": "workspace:^",
+    "effect": "workspace:^",
+    "vitest": "^3.2.4"
+  }
+}

packages/dst/src/DSTReport.ts

@@ -0,0 +1,76 @@
+/**
+ * DST Report - Developer attribution reports from profiling data.
+ *
+ * Generates reports that correlate CPU time hotspots with the developer
+ * who wrote the code, using V8 profiles + source maps + git blame.
+ *
+ * @since 0.1.0
+ */
+
+export type {
+  /**
+   * A developer's hotspot in the profile.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  DeveloperHotspot,
+  /**
+   * A complete DST report with developer attribution.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  DSTReport,
+  /**
+   * A single hot function frame.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  HotFrame
+} from "./internal/reportGenerator.js"
+
+export {
+  /**
+   * Generate a developer attribution report from annotated profile nodes.
+   *
+   * @since 0.1.0
+   * @category reports
+   */
+  generateReport,
+  /**
+   * Render a DSTReport as JSON for programmatic consumption.
+   *
+   * @since 0.1.0
+   * @category rendering
+   */
+  toJSON,
+  /**
+   * Render a DSTReport as Markdown.
+   *
+   * @since 0.1.0
+   * @category rendering
+   */
+  toMarkdown
+} from "./internal/reportGenerator.js"
+
+export type {
+  /**
+   * An annotated profile node with source map resolution and git blame.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  AnnotatedNode
+} from "./internal/profileAnnotator.js"
+
+export {
+  /**
+   * Annotate all profile nodes with source maps and git blame.
+   *
+   * @since 0.1.0
+   * @category annotation
+   */
+  annotateProfile
+} from "./internal/profileAnnotator.js"

packages/dst/src/DSTRunner.ts

@@ -0,0 +1,43 @@
+/**
+ * DST Runner - Multi-seed test runner with profiling and failure shrinking.
+ *
+ * Iterates over a range of seeds, running each under deterministic
+ * simulation. Optionally captures V8 CPU profiles and annotates with
+ * git blame attribution.
+ *
+ * @since 0.1.0
+ */
+
+export type {
+  /**
+   * Configuration for a DST suite run.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  DSTRunConfig,
+  /**
+   * Result of running a complete DST suite across multiple seeds.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  DSTSuiteResult,
+  /**
+   * Result of a single seed run.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  SeedResult
+} from "./internal/dstRunner.js"
+
+export {
+  /**
+   * Run DST across multiple seeds, collecting results.
+   *
+   * @since 0.1.0
+   * @category execution
+   */
+  runSuite
+} from "./internal/dstRunner.js"

packages/dst/src/GitBlame.ts

@@ -0,0 +1,57 @@
+/**
+ * Git Blame Attribution for Effect.
+ *
+ * Maps source file locations to developer attribution data using
+ * `git blame --line-porcelain`. Useful for correlating performance
+ * hotspots with the developer responsible for the code.
+ *
+ * @since 0.1.0
+ */
+
+export type {
+  /**
+   * A single git blame entry for a line of code.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  BlameEntry,
+  /**
+   * A map from "file:line" keys to BlameEntry values.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  BlameMap
+} from "./internal/gitBlame.js"
+
+export {
+  /**
+   * Run `git blame --line-porcelain` for an entire file.
+   *
+   * @since 0.1.0
+   * @category git
+   */
+  blameFile,
+  /**
+   * Run `git blame` for specific line ranges in a file.
+   *
+   * @since 0.1.0
+   * @category git
+   */
+  blameLines,
+  /**
+   * Auto-detect the git repository root.
+   *
+   * @since 0.1.0
+   * @category git
+   */
+  findRepoRoot,
+  /**
+   * Parse git blame --line-porcelain output.
+   *
+   * @since 0.1.0
+   * @category parsing
+   */
+  parseLinePorcelain
+} from "./internal/gitBlame.js"

packages/dst/src/V8Profiler.ts

@@ -0,0 +1,71 @@
+/**
+ * V8 CPU Profiling for Effect.
+ *
+ * Provides Effect-wrapped APIs for capturing V8 CPU profiles during
+ * test execution. Profiles are saved in the standard `.cpuprofile`
+ * format, compatible with Chrome DevTools and other profiling tools.
+ *
+ * @since 0.1.0
+ */
+
+export type {
+  /**
+   * A V8 CPU call frame.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  CallFrame,
+  /**
+   * Metadata attached to a profile capture.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  ProfileMetadata,
+  /**
+   * A node in the V8 CPU profile call tree.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  ProfileNode,
+  /**
+   * Result of a profiled Effect execution.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  ProfileResult,
+  /**
+   * A V8 CPU profile in the standard .cpuprofile format.
+   *
+   * @since 0.1.0
+   * @category models
+   */
+  V8Profile
+} from "./internal/v8Profiler.js"
+
+export {
+  /**
+   * Capture a V8 CPU profile while executing an Effect.
+   *
+   * @since 0.1.0
+   * @category profiling
+   */
+  captureProfile,
+  /**
+   * Compute self-time for each node from the samples/timeDeltas arrays.
+   *
+   * @since 0.1.0
+   * @category profiling
+   */
+  computeSelfTimes,
+  /**
+   * Save a profile to disk as a .cpuprofile JSON file.
+   *
+   * @since 0.1.0
+   * @category profiling
+   */
+  saveProfile
+} from "./internal/v8Profiler.js"

packages/dst/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @effect/dst - Deterministic Simulation Testing with V8 profiling and
+ * git blame attribution for Effect.
+ *
+ * @since 0.1.0
+ */
+
+/**
+ * V8 CPU Profiling
+ *
+ * @since 0.1.0
+ */
+export * as V8Profiler from "./V8Profiler.js"
+
+/**
+ * Git Blame Attribution
+ *
+ * @since 0.1.0
+ */
+export * as GitBlame from "./GitBlame.js"
+
+/**
+ * DST Multi-Seed Runner
+ *
+ * @since 0.1.0
+ */
+export * as DSTRunner from "./DSTRunner.js"
+
+/**
+ * DST Reports and Developer Attribution
+ *
+ * @since 0.1.0
+ */
+export * as DSTReport from "./DSTReport.js"