V3.0.0

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [master, 'v[0-9]+.*']
+  pull_request:
+    branches: [master, 'v[0-9]+.*']
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint
+      - run: pnpm run typecheck
+      - run: pnpm run test:coverage
+      - run: pnpm run build

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Docs
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Install website dependencies
+        run: pnpm --dir website install --frozen-lockfile
+      - name: Build docs site
+        run: pnpm run docs
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run typecheck
+      - run: pnpm run lint
+      - run: pnpm test
+      - run: pnpm run build
+      - run: pnpm publish --provenance --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

.gitignore

@@ -3,6 +3,16 @@
 dist/
 lib/
 
+# Generated site (typedoc / starlight)
+.site/
+website/dist/
+website/node_modules/
+website/.astro/
+website/src/content/docs/api/
+
+# Local planning docs
+docs/.local/
+
 # Work in Progress
 wip/
 bak/

.npmignore

@@ -1 +1,4 @@
 .github
+.site
+docs
+website

.npmrc

@@ -0,0 +1,3 @@
+public-hoist-pattern[]=*eslint*
+public-hoist-pattern[]=*prettier*
+public-hoist-pattern[]=@typescript-eslint/*

.nvmrc

@@ -0,0 +1 @@
+22

CHANGELOG.md

@@ -1,5 +1,47 @@
 # Change Log
 
+<a name="3.0.0"></a>
+# [3.0.0](https://github.com/abrisene/acausal/compare/v3.0.0...v2.0.1) (2025-11-08)
+
+### Breaking Changes
+
+* **Build Output**: Changed from `lib/` to `dist/` directory
+* **Modular Structure**: Markov chain source split into `src/structures/markov/` with separate files for chain, batch, blend, multi-dim, types, utils, defaults
+* **Removed `ScaledMarkovChain`**: Needs full rewrite; use `MultiDimMarkovChain` for structured states
+* **Removed analysis/export methods**: `extractPatterns()`, `findSimilar()`, `exportAsGraph()`, `diff()`, `toJSON()`, `rankByLikelihood()`, `isAnomaly()`, `withSelector()` removed from `MarkovChain`
+* **Removed `IMarkovChain` interface** and `StateId` type
+* **`MarkovChainConstructor` is no longer generic** (was `MarkovChainConstructor<T>`)
+* **`interpolate()` restricted to same type parameter** (was `<U extends string>` with unsafe cast)
+* **`MultiDimMarkovChain` constructor changed**: `stateKey` now accepts `string | StateKeyFunction<T>`; string keys are looked up in a named-function registry
+* **Node.js**: Minimum version now 18+ (was 14+)
+* **TypeScript**: Upgraded to 5.6.3 with stricter type checking
+
+### Features
+
+* **Generic Types**: `MarkovChain<T extends string = string>`, `Distribution<T extends string = string>`
+* **Batch Operations**: `MarkovChainBatch` class for efficient bulk `addSequence`/`addEdge`
+* **Chain Blending**: `MarkovChain.blend()` and `interpolate()` with 5 strategies (arithmetic, geometric, harmonic, max, min)
+* **Static Dual-API**: `MarkovChain.blendDTOs()`, `MarkovChain.score()`, `MarkovChain.getStats()` operate on DTOs without requiring instances
+* **Sequence Scoring**: `score()` returns log probability, perplexity, and validity
+* **Constraint-Based Generation**: `MCConstraints` with minLength, maxLength, mustContain, mustNotContain, pattern, validator, maxRetries
+* **MultiDimMarkovChain**: Structured state spaces with named-function registry for serializable state keys
+* **MultiDimMarkovChain Serialization**: `serialize()` / `fromDTO()` round-trip, `registerStateKey()` / `getStateKey()` for portable state key functions
+* **Utility Methods**: `hasGram()`, `getGramsByOrder()`, `getStats()`
+
+### Bug Fixes
+
+* **Gram frequency**: `addEdge` now correctly increments gram frequency
+* **`clone(0)`**: `Random.clone(0)` preserves zero use count
+* **Constraint retry**: Failed constraint retries return last attempt, not empty array
+* **Null safety**: Proper null checks throughout with `noUncheckedIndexedAccess`
+
+### Internal
+
+* Replaced `tsc` with `tsup` for ESM/CJS dual output
+* Modern TypeScript 5.6.3 with strict mode
+* Vitest with native ESM support
+* 95% test coverage threshold enforced
+
 <a name="2.0.1"></a>
 ## [2.0.1](https://github.com/abrisene/acausal/compare/v2.0.1...v2.0.0) (2021-09-08)
 * Added "Analyze" function to Markov Chains.
@@ -15,7 +57,7 @@
 * Full conversion to Typescript.
 * Rewrote Markov Chain class.
 * Rewrote "Transition Matrix" class, now named "Distribution".
-* Wrote "Random" class, which wraps `random-js`.
+* Wrote "Random" class, backed by an internal MT19937 PRNG implementation.
 * Rewrote Unit Tests.
 * Test Coverage at > 99%
 * Removed file loading utilities - these should be a separate module, or written ad hoc as needed with implementations.

CLAUDE.md

@@ -0,0 +1,96 @@
+# acausal
+
+TypeScript library for weighted random distributions, Markov chains, and seeded PRNG. Used for procedural generation, name generators, game systems, and stochastic modeling.
+
+## Design Philosophy
+
+These are non-negotiable architectural constraints:
+
+- **Static clone-on-write / Mutable instances**: Static methods clone the DTO, mutate the clone, and return the new DTO. Instance methods (e.g. `addSequence`, `add`, `remove`) delegate to statics, reassign internal state, and return `this` for chaining — the instance is mutated in place. Use `.clone()` before mutating if you need to preserve the original. `Immutable*` variants (`ImmutableMarkovChain`, `ImmutableDistribution`, `ImmutableMultiDimMarkovChain`) return new instances from mutating methods for functional patterns and safe sharing. `MarkovChainBatch` remains valuable for avoiding N static-level clones in bulk operations.
+- **Dual API**: Every feature has both an instance method and a static method that operates on raw DTOs. Instance methods delegate to statics. Example: `chain.generate(opts)` wraps `MarkovChain.generate({ model: chain.dto, ...opts })`.
+- **Portable DTOs**: All classes serialize to/from plain JSON objects (`serialize()` / constructor from DTO). Models can be stored, transferred over the network, and rebuilt without the original training data.
+- **Minimal dependencies**: Only `scalr` (weight normalization). The PRNG is an internal MT19937 implementation.
+
+## Architecture
+
+```
+src/
+  index.ts                          # Barrel: constants, services, structures, types
+  types.ts                          # WeightedDistribution (shared base type)
+  constants/index.ts                # MT_PREWARM, delimiters, max order default
+  services/
+    mersenne-twister.ts             # Internal MT19937 PRNG engine
+    random.ts                       # Random class (wraps MT engine)
+    sampler.ts                      # RandomSampler (statistical distributions)
+  structures/
+    distribution.ts                 # Distribution<T> + ImmutableDistribution<T>
+    markov/
+      markov-chain.ts               # MarkovChain<T> core class (mutable instances)
+      immutable-markov-chain.ts     # ImmutableMarkovChain<T> (returns new instances)
+      batch.ts                      # MarkovChainBatch<T> (bulk add sequences/edges)
+      blend.ts                      # blendMultipleDistributions() (5 strategies)
+      multi-dim-chain.ts            # MultiDimMarkovChain<T> (mutable instances)
+      immutable-multi-dim-chain.ts  # ImmutableMultiDimMarkovChain<T>
+      utils.ts                      # Module-level gram dictionary mutation functions
+      types.ts                      # All Markov type definitions
+      defaults.ts                   # Default options and empty DTOs
+      index.ts                      # Controlled barrel export
+  __tests__/
+    distribution.spec.ts
+    markov.spec.ts
+    random.spec.ts
+    sampler.spec.ts
+```
+
+## Key Patterns
+
+### Gram Structure
+An n-gram state with bidirectional transitions. Grams have an `id` (states joined by delimiter `⏐`), `order`, `frequency`, and two `DistributionSourceDTO` objects (`last`, `next`) for backward/forward transitions.
+
+### Delimiters
+- Start: `○` (U+25CB)
+- Gram separator: `⏐` (U+23F0)
+- End: `◍` (U+25CD)
+
+Defined in `constants/index.ts`. These mark sequence boundaries in gram IDs.
+
+### MultiDimMarkovChain Registry
+Uses a named-function registry (`registerStateKey` / `getStateKey`) so that state key functions can be serialized by name and looked up at deserialization time. The DTO stores `stateKeyName: string`, not the function itself.
+
+### Blend Strategies
+`blend.ts` supports 5 strategies: `arithmetic`, `geometric`, `harmonic`, `max`, `min`. Geometric/harmonic fall back to arithmetic when values are zero (mathematically correct — can't compute geometric mean of zero).
+
+## Build & Test
+
+```bash
+pnpm run build          # tsup → dist/ (ESM + CJS + .d.ts)
+pnpm run typecheck      # tsc --noEmit
+pnpm test               # vitest
+pnpm run test:coverage  # vitest --coverage (thresholds: 85% branch, 95% lines/funcs/stmts)
+pnpm run lint           # gts lint
+pnpm run docs           # typedoc (deployed via CI to GitHub Pages)
+```
+
+**Build** uses tsup (see `tsup.config.ts`). Output is ESM + CJS dual format targeting ES2022. The `onSuccess` hook runs `tsc --noEmit` after build.
+
+**Test** uses Vitest with native ESM support. No special Node flags needed.
+
+**CI** runs on GitHub Actions: lint, typecheck, test (Node 18/20/22 matrix), and build. Docs deploy to GitHub Pages on version tags. Releases publish to npm with provenance.
+
+**TypeScript** extends `gts/tsconfig-google.json` with strict mode, `noUncheckedIndexedAccess`, and bundler module resolution.
+
+## Important Implementation Details
+
+- **MT19937 engine** (`mersenne-twister.ts`): Full reference implementation with `seed()`, `seedWithArray()`, `next()`, `discard()`. Helper functions: `integer()` (rejection sampling to avoid modulo bias), `real()` (53-bit resolution using two 32-bit draws), `pick()`, `bool()`, `createEntropy()`.
+- **Random class** tracks a `uses` counter that increments with each draw. Serializing `{ seed, uses }` and replaying `discard(uses)` reproduces exact engine state.
+- **Distribution** maintains dual representation: raw `source` weights (human-readable) and `normal` weights (probabilities summing to 1.0). Normalization uses `scalr`.
+- **MarkovChain generation** uses dynamic order adjustment when `strict: false` — if no gram exists at the target order, it decrements until a match is found.
+- **MarkovChainBatch** accumulates sequences/edges, then `commit()` applies them all at once to produce a new `MarkovChain<T>`.
+- **RandomSampler** (`sampler.ts`): Statistical distribution sampling built on `Random`. Provides `normal()` (Box-Muller), `truncatedNormal()` (clamped), `exponential()`, `poisson()`, `binomial()`, `geometric()`, `beta()`, `gamma()` (Marsaglia-Tsang), `weibull()`, `cauchy()`, `logistic()`, `logNormal()`. Also provides `sampleDistribution(params)` for data-driven sampling from typed distribution parameter objects (`DistributionParams`). All methods are deterministic given the same seed.
+
+## Common Gotchas
+
+- Don't share `Random` engine instances between cloned chains — use `engine.clone()` to create independent copies.
+- `MCAnalyzeOptions` extends `Omit<MCGeneratorOptions, 'constraints'>` — constraints are intentionally excluded from analysis.
+- The `GramDictionary` and `MCDelimitersShort` types are internal but exported for advanced use cases. They are not part of the stable public API.
+- `scalr` is the only runtime dependency. Do not add new dependencies without strong justification.