octopus-replay 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+**English** | [简体中文](CHANGELOG.zh-CN.md)
+
+# Changelog
+
+All notable changes to Replay are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+semantic versioning once it reaches 1.0.
+
+## [0.1.0] — 2026-07-03
+
+First public release.
+
+### Added
+- **Record / replay / verify harness** — `record(scenario, handler, opts?)`
+  runs a handler and captures a golden `Recording`; `replay(recording, handler)`
+  re-runs it under frozen nondeterminism (pure — no live clock, RNG, or network)
+  and returns a `Transcript`; `verifyDeterminism(recording, handler)` replays a
+  (possibly changed) handler and returns
+  `{ ok, expectedHash, actualHash, divergence? }`, pointing at the first output
+  that differs. `toScenario`, `diffTranscripts`, `diffRecordings`, and
+  `formatDivergence` round out the surface.
+- **Canonical hashing** — `stableStringify` (object keys sorted at every depth),
+  `canonicalHash` (SHA-256), `canonicalEqual`, and `cloneJson`. Non-finite
+  numbers, `undefined`, functions, and cycles are rejected, so a "successful"
+  hash never hides silent data loss. This is the byte-for-byte equality
+  foundation.
+- **Deterministic sources** — `steppingClock` and `sequenceClock` for
+  `ctx.now()`, and a seeded mulberry32 PRNG `seededRandom` for `ctx.random()`,
+  so a recording can be captured without ever touching the wall clock or platform
+  RNG.
+- **`ReplayContext` with a recorded IO tape** — handlers read all nondeterminism
+  through `ctx.now()`, `ctx.random()`, and `ctx.respond(key, produce)`. On record
+  `produce` runs and its result is taped; on replay the tape is returned and
+  `produce` is never called. Over-reading a tape throws a `DeterminismError`,
+  surfaced by verify as a divergence.
+- **Recording format v1** (`RECORDING_VERSION = "1"`) — `serializeRecording`,
+  `parseRecording`, and `assertRecording` write, read, and validate the on-disk
+  shape (`meta`, `events`, `clock`, `random`, `responses`, and a `transcript`
+  with `entries` + `hash`). A malformed file throws a `RecordingFormatError`.
+- **Source adapters** — `fromJsonl` (NDJSON/JSONL logs, with an optional
+  `select`), `fromEvents` (a plain event array), and `fromWebhookFixtures`
+  (captured webhook deliveries, ordered deterministically by `receivedAt`).
+- **CLI** (`octopus-replay`) — `record`, `verify`, `run`, and `diff` commands;
+  `--handler` (default-exported handler module), `-o/--out`, `--seed`,
+  `--clock-start`, `--clock-step`. Exit codes: `0` ok, `1` divergence / verify
+  failed, `2` usage or IO error.
+- **Zero runtime dependencies**, Node ≥ 22, Apache-2.0. Ships bilingual docs
+  (English canonical + `*.zh-CN.md` siblings), README badges, a design doc, and
+  `SECURITY.md` / `CONTRIBUTING.md` / `CODE_OF_CONDUCT.md`.

package/CHANGELOG.zh-CN.md

@@ -0,0 +1,42 @@
+[English](CHANGELOG.md) | **简体中文**
+
+# 更新日志 (Changelog)
+
+Replay 的所有重要变更都记录于此。格式遵循
+[Keep a Changelog](https://keepachangelog.com/),项目在到达 1.0 后将采用语义化版本。
+
+## [0.1.0] — 2026-07-03
+
+首个公开发布。
+
+### 新增 (Added)
+- **record / replay / verify 测试台** —— `record(scenario, handler, opts?)` 运行
+  处理器并捕获一份黄金 `Recording`;`replay(recording, handler)` 在冻结的不确定性下
+  重跑它(纯的 —— 不触碰真实时钟、RNG 或网络)并返回一份 `Transcript`;
+  `verifyDeterminism(recording, handler)` 回放一个(可能已变更的)处理器并返回
+  `{ ok, expectedHash, actualHash, divergence? }`,指向第一处不同的输出。`toScenario`、
+  `diffTranscripts`、`diffRecordings` 与 `formatDivergence` 补全整个界面。
+- **规范哈希 (Canonical hashing)** —— `stableStringify`(每一层键都排序)、
+  `canonicalHash`(SHA-256)、`canonicalEqual` 与 `cloneJson`。非有限数值、
+  `undefined`、函数与环均被拒绝,因此一次"成功"的哈希绝不掩盖静默的数据丢失。这是
+  逐字节相等的基石。
+- **确定性来源 (Deterministic sources)** —— 用于 `ctx.now()` 的 `steppingClock` 与
+  `sequenceClock`,以及用于 `ctx.random()` 的带种子 mulberry32 PRNG `seededRandom`,
+  使一份录制的捕获可以完全不触碰真实时钟或平台 RNG。
+- **带录制 IO 带子的 `ReplayContext`** —— 处理器经由 `ctx.now()`、`ctx.random()` 与
+  `ctx.respond(key, produce)` 读取一切不确定性。record 时 `produce` 运行且其结果被
+  录带;replay 时返回带子且 `produce` 永不被调用。过度读取带子会抛出
+  `DeterminismError`,由 verify 呈现为一处分歧。
+- **录制格式 v1**(`RECORDING_VERSION = "1"`)—— `serializeRecording`、
+  `parseRecording` 与 `assertRecording` 写入、读取并校验落盘形态(`meta`、`events`、
+  `clock`、`random`、`responses`,以及带 `entries` + `hash` 的 `transcript`)。畸形
+  文件会抛出 `RecordingFormatError`。
+- **源适配器 (Source adapters)** —— `fromJsonl`(NDJSON/JSONL 日志,含可选 `select`)、
+  `fromEvents`(普通事件数组)与 `fromWebhookFixtures`(捕获的 webhook 投递,按
+  `receivedAt` 确定性排序)。
+- **CLI**(`octopus-replay`)—— `record`、`verify`、`run` 与 `diff` 命令;
+  `--handler`(默认导出的处理器模块)、`-o/--out`、`--seed`、`--clock-start`、
+  `--clock-step`。退出码:`0` 正常,`1` 分歧 / 校验失败,`2` 用法或 IO 错误。
+- **零运行时依赖**,Node ≥ 22,Apache-2.0。附带双语文档(英文为准 + `*.zh-CN.md`
+  副本)、README 徽章、设计文档,以及 `SECURITY.md` / `CONTRIBUTING.md` /
+  `CODE_OF_CONDUCT.md`。

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Octoryn
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,290 @@
+**English** | [简体中文](README.zh-CN.md)
+
+# Replay
+
+[![CI](https://github.com/octoryn/octopus-replay/actions/workflows/ci.yml/badge.svg)](https://github.com/octoryn/octopus-replay/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/octoryn/octopus-replay?sort=semver)](https://github.com/octoryn/octopus-replay/releases/latest)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+[![Zero runtime deps](https://img.shields.io/badge/runtime%20deps-0-success.svg)](package.json)
+
+> Make every incident byte-for-byte reproducible. A **determinism harness** for
+> governed event streams — it freezes the clock, randomness, and external IO so a
+> handler replays to a byte-identical transcript.
+
+> **Part of [Octopus Core](https://github.com/octoryn) — the open infrastructure stack for governed AI.** One job per repo, along the agent lifecycle: [Scout](https://github.com/octoryn/octopus-scout) · [Observe](https://github.com/octoryn/octopus-observe) · [Experience](https://github.com/octoryn/octopus-experience) · [Blackboard](https://github.com/octoryn/octopus-blackboard) · [Runtime](https://github.com/octoryn/octopus-runtime) · [Replay](https://github.com/octoryn/octopus-replay) — with [Inspect](https://github.com/octoryn/octopus-inspect) governing every stage.
+>
+> **This repo — Replay · Verify:** Reproduce every agent incident byte-for-byte.
+
+```
+Scenario (logs / fixtures) → record → Recording ── replay ──▶ Transcript
+                                          └────── verify ─────▶ pass / divergence
+```
+
+Capture a golden **recording** from a real incident — the events plus every
+value the handler read from the clock, the RNG, and the network. Re-run it in CI
+and any change that alters governed behavior fails with an **exact pointer** to
+the first output that differs. Same recording, same handler → the same transcript
+hash, on any machine, forever.
+
+## Boundaries
+
+Replay is a **determinism harness, not a JSONL reader**. The log adapter is a
+convenience; the substance is that it *freezes every source of nondeterminism*.
+A handler that reads the clock, randomness, and external IO **only through the
+`ReplayContext`** replays exactly. A handler that reaches for `Date.now()`,
+`Math.random()`, or a live network call directly escapes the harness and will
+diverge — that discipline is the whole point.
+
+Replay **does not** patch globals, intercept `fetch`, or sandbox your code. It
+does not judge whether an output is *correct* — only whether it is *reproducible*.
+It hosts a handler; it is not that handler's dependency.
+
+It **validates** the governed cores (Observe / Runtime / Blackboard) by replaying
+incidents through a handler that wraps them — but it has **zero dependency** on
+any of them. The boundary is the `Handler` signature and the JSON event shape,
+not any package SDK. Replay is testing and proof infrastructure.
+
+It has **zero runtime dependencies** and no dependency on any other Octopus
+package. The repo is fully usable on its own.
+
+## Install & build
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # node --test
+npm run build       # emit dist/
+npm run example     # capture a recording and verify it (see below)
+```
+
+Requires Node ≥ 22.
+
+## Quickstart
+
+A handler is a deterministic function of an event and its context:
+
+```ts
+import type { Handler } from "octopus-replay";
+
+// A tiny governed handler: stamp a time, make a policy roll, do one IO call —
+// each source of nondeterminism read only through `ctx`.
+const handler: Handler = async (event, ctx) => {
+  const receivedAt = ctx.now();               // frozen clock
+  const sampled = ctx.random() < 0.2;         // frozen RNG (20% sampled)
+  const balance = await ctx.respond(          // frozen IO: taped on record,
+    "account.balance",                         // replayed on replay
+    () => 1000 - (event as { amount: number }).amount,
+  );
+  return { receivedAt, sampled, approved: balance >= 0, balance };
+};
+```
+
+Build a scenario, capture a golden recording, then verify:
+
+```ts
+import {
+  fromEvents,
+  record,
+  seededRandom,
+  steppingClock,
+  verifyDeterminism,
+} from "octopus-replay";
+
+const scenario = fromEvents([{ amount: 300 }, { amount: 1000 }, { amount: 50 }], {
+  id: "incident-4211",
+  note: "three charges captured from production",
+});
+
+// Capture a golden recording under deterministic sources.
+const recording = await record(scenario, handler, {
+  sources: { clock: steppingClock(Date.parse("2026-07-03T00:00:00Z"), 1000), random: seededRandom(99) },
+});
+
+// Same handler → byte-for-byte reproducible.
+const good = await verifyDeterminism(recording, handler);
+good.ok; // true — actualHash === expectedHash
+```
+
+When the behavior drifts, the same call catches it with a pointer to the first
+divergence:
+
+```ts
+// A regression: someone flips the approval boundary to `> 0`.
+const changed: Handler = async (event, ctx) => {
+  const receivedAt = ctx.now();
+  const sampled = ctx.random() < 0.2;
+  const balance = await ctx.respond("account.balance", () => 1000 - (event as { amount: number }).amount);
+  return { receivedAt, sampled, approved: balance > 0, balance }; // >= 0 became > 0
+};
+
+const bad = await verifyDeterminism(recording, changed);
+bad.ok;                    // false
+bad.divergence?.seq;       // 1 — the { amount: 1000 } charge, balance 0
+bad.divergence?.expected;  // { …, approved: true,  … }
+bad.divergence?.actual;    // { …, approved: false, … }
+```
+
+This is [`examples/replay-incident.ts`](examples/replay-incident.ts) end to end;
+run it with `npm run example`.
+
+## Use it in CI
+
+Commit a recording as a fixture and let CI catch behavior drift:
+
+1. **Record once** from a real incident (or a hand-built scenario) with
+   `record`, and `serializeRecording` it to a `*.json` fixture committed to the
+   repo.
+2. **Verify on every change** — either `octopus-replay verify recording.json
+   --handler ./handler.js` in CI, or `verifyDeterminism(recording, handler)` in a
+   `node --test` file that asserts `result.ok`.
+
+Any change that alters a governed output makes verify fail with the exact event
+and the expected/actual values — a regression test you got for free the moment
+you captured the incident.
+
+## Bare vs. frozen scenarios
+
+A **bare** scenario is events only — the source adapters (`fromEvents`,
+`fromJsonl`, `fromWebhookFixtures`) return these. `record` runs it against live
+sources (`Date.now` / `Math.random` by default, or the `sources` you inject) and
+**tapes** every value the handler consumes, producing a fully-frozen recording.
+
+A **frozen** scenario already carries its `clock`, `random`, and `responses`
+tapes (e.g. `toScenario(recording)`). `record` re-materializes it from its own
+tapes — no live source is touched. `replay` always runs frozen: it is pure, with
+no live clock, RNG, or network.
+
+## The `ReplayContext` contract
+
+Everything nondeterministic a handler needs must come through the context:
+
+| Member | On record | On replay |
+| ------ | --------- | --------- |
+| `ctx.now()` | reads the live/injected clock, tapes the value | returns the next taped timestamp |
+| `ctx.random()` | reads the live/injected RNG, tapes the value | returns the next taped value |
+| `ctx.respond(key, produce)` | runs `produce()`, tapes its result under `key` | returns the taped result — **`produce` is not called** |
+| `ctx.seq` | 0-based index of the current event | same |
+
+On replay, `produce` never runs — so an IO call that fails, mutates, or is slow
+in production is a no-op during replay. If a handler over-reads a tape (calls
+`now()`/`random()` more often than recorded, or `respond` with an exhausted key),
+the frozen context throws a **`DeterminismError`**, which `verifyDeterminism`
+surfaces as a divergence rather than throwing. That is the harness telling you
+behavior drifted in a way the recording can't reproduce.
+
+## Source adapters
+
+Turn captured production data into a bare scenario:
+
+```ts
+import { fromJsonl, fromEvents, fromWebhookFixtures } from "octopus-replay";
+
+// NDJSON / JSONL event log (one event per line):
+const a = fromJsonl(logText, { select: (line) => (line as { event: unknown }).event });
+
+// A plain array of events:
+const b = fromEvents([{ amount: 300 }, { amount: 50 }]);
+
+// Captured webhook deliveries — ordered deterministically by `receivedAt`:
+const c = fromWebhookFixtures(fixtures, { wrap: true }); // wrap → { id?, headers?, payload }
+```
+
+## Determinism helpers
+
+For driving `record` reproducibly (in tests, examples, and the CLI):
+
+- `seededRandom(seed)` — a mulberry32 PRNG; the same seed yields the same
+  sequence, independent of the platform RNG.
+- `steppingClock(start, step = 1000)` — a clock that starts at `start` and
+  advances by `step` ms per call.
+- `sequenceClock(times)` — returns each timestamp in `times` in turn, and throws
+  when exhausted so a test that over-reads fails loudly.
+
+## Canonical hashing
+
+"Byte-for-byte" is defined against a **canonical** form, so key order, whitespace,
+and number formatting never affect equality:
+
+- `stableStringify(value)` — deterministic JSON with object keys sorted at every
+  depth. Rejects what JSON can't faithfully round-trip: non-finite numbers,
+  `undefined`, functions, and cycles — a "successful" hash never hides silent
+  data loss.
+- `canonicalHash(value)` — the SHA-256 of that encoding (the transcript hash).
+- `canonicalEqual(a, b)` — deep equality via the same encoding, so a diff can
+  never disagree with a hash mismatch.
+- `cloneJson(value)` — a deep clone that also asserts the value is
+  canonicalizable JSON.
+
+## Recording format
+
+A recording serializes to pretty-printed JSON (`RECORDING_VERSION = "1"`), fit to
+commit as a fixture:
+
+```jsonc
+{
+  "meta": { "recordingVersion": "1", "id": "incident-4211", "createdAt": "2026-07-03T00:00:00.000Z", "note": "…" },
+  "events": [ { "seq": 0, "event": { "amount": 300 } }, … ],
+  "clock":  [ 1751500800000, 1751500801000, 1751500802000 ],   // ctx.now()  values, in call order
+  "random": [ 0.63…, 0.11…, 0.94… ],                            // ctx.random() values, in call order
+  "responses": { "account.balance": [ 700, 0, 950 ] },          // ctx.respond() results, per key, in order
+  "transcript": {
+    "entries": [ { "seq": 0, "output": { "approved": true, … } }, … ],
+    "hash": "a1b2c3…"                                            // SHA-256 over the canonical entries
+  }
+}
+```
+
+`serializeRecording` / `parseRecording` / `assertRecording` write, read, and
+validate this shape; a malformed file (bad version, wrong field types) throws a
+`RecordingFormatError`.
+
+## CLI
+
+```bash
+octopus-replay record <scenario> --handler <mod> [-o out.json] [--seed N] [--clock-start MS] [--clock-step MS]
+octopus-replay verify <recording.json> --handler <mod>
+octopus-replay run    <recording.json> --handler <mod>
+octopus-replay diff   <a.json> <b.json>
+```
+
+- **`record`** — run the handler over a scenario and print (or `-o`) a golden
+  recording. Scenario input is a `.jsonl`/`.ndjson` log, a `.json` array of
+  events, or a scenario object. `--seed` drives `ctx.random()` deterministically;
+  `--clock-start`/`--clock-step` drive `ctx.now()`.
+- **`verify`** — replay a recording and check it still matches; prints `✔` or the
+  first divergence.
+- **`run`** — replay a recording and print the resulting transcript JSON.
+- **`diff`** — compare two recordings' transcripts.
+
+The `--handler <mod>` module **default-exports** the `(event, ctx) => output`
+function (a `handler` named export also works). Relative/absolute paths resolve
+from the cwd; bare specifiers resolve as node modules.
+
+**Exit codes:** `0` ok · `1` divergence / verify failed · `2` usage or IO error.
+
+## API surface
+
+- **Harness** — `record(scenario, handler, opts?)`, `replay(recording, handler)`,
+  `toScenario(recording)`.
+- **Verify** — `verifyDeterminism(recording, handler)` →
+  `{ ok, expectedHash, actualHash, divergence? }`, `diffTranscripts`,
+  `diffRecordings`, `formatDivergence`.
+- **Sources** — `fromJsonl`, `fromEvents`, `fromWebhookFixtures`.
+- **Determinism** — `seededRandom`, `steppingClock`, `sequenceClock`.
+- **Hashing** — `stableStringify`, `canonicalHash`, `canonicalEqual`, `cloneJson`.
+- **Format** — `serializeRecording`, `parseRecording`, `assertRecording`,
+  `RECORDING_VERSION`.
+- **Errors** — `DeterminismError`, `RecordingFormatError`.
+
+## Design
+
+The authoritative architecture and contracts live in
+[`docs/DESIGN.md`](docs/DESIGN.md) — the determinism-harness thesis, the
+Scenario → record → Recording → replay/verify pipeline, the `ReplayContext`
+discipline, and the recording format. Read it before making changes; code is
+written against that spec.
+
+## License
+
+[Apache-2.0](LICENSE) © Octoryn.