feat: scaffold deterministic replay baseline framework by dgarson · Pull Request #92 · dgarson/clawdbot

dgarson · 2026-02-23T07:39:15Z

What

Kick off the deterministic replay implementation with an additive baseline in src/replay/.

Added:

Event contracts and schema types for deterministic replay.
Deterministic clock helper and in-memory replay recorder.
Minimal scenario entrypoint with sequence-checking utilities.
Baseline tests for determinism and constraint validation.
Short implementation notes in _shared/specs/bs-tim-4-deterministic-replay-kickoff-notes.md.

How to Test

pnpm vitest run src/replay
pnpm vitest run src/replay/recorder.test.ts src/replay/runner.test.ts

Known Limitations / Next Milestones

Recorder is in-memory only (no persistence to .replay bundle yet).
No session/LLM/tool pipeline wiring yet (scaffold only).
No CLI surface yet.
Planned follow-ons:
1. Wire recorder to real session event producers (LLM/tool/IO).
2. Add manifest/events persistence layer.
3. Implement playback modes (verify/inspect/headless/compare).
4. Add replay CLI (openclaw replay ...).

dgarson · 2026-02-23T08:29:08Z

Routing: Tim → review

PR #92 — Deterministic replay baseline scaffold (Nate). Targets feat/deterministic-replay.

Tim: review for correctness of event contracts and schema types. Check the deterministic clock helper and replay recorder design — these are foundational and hard to change later. If the types look right, approve and merge to the megabranch. Barry/Jerry: also welcome to review before Tim.

dgarson · 2026-02-23T08:34:01Z

Run Codex sweep first, then request final architecture review.

dgarson · 2026-02-23T08:37:16Z

dr-003 Progress Update

I finished milestone dr-003 on top of nate/deterministic-replay-kickoff:

Added typed manifest schema + version constants in src/replay/types.ts:
- REPLAY_SCHEMA_VERSION, REPLAY_MANIFEST_MIN_VERSION, REPLAY_MANIFEST_LATEST_VERSION, REPLAY_MANIFEST_SUPPORTED_VERSIONS
- ReplayEventCategorySchema, ReplayEventKeySchema, ReplayEventInputSchema, ReplayEventSchema, ReplaySessionMetadataSchema, ReplayManifestStatsSchema, ReplayManifestSchemaV1, ReplayManifestSchema
- parseReplayManifest, parseReplayManifestJSON, serializeReplayManifest
Wired schema validation into recorder output (src/replay/recorder.ts) so finalize() now returns a parsed/validated manifest.
Exported manifest schema/version symbols through src/replay/index.ts.
Added src/replay/types.test.ts with serialization + validation coverage:
- validates round-trip via schema + JSON helpers
- rejects unsupported version payloads
- rejects malformed payloads
- asserts version constants consistency
Added brief evolution docs in src/replay/README.md describing backward-compatible schema versioning and migration strategy.

Architecture notes

Current wire contract is a discriminated union on schemaVersion; extending to V2 later should be additive by adding ReplayManifestSchemaV2 and keeping old version schemas in the union.
ReplayManifestSchema validation now provides a single choke-point for manifest compatibility and makes later migration logic straightforward.
Version constants are intentionally explicit and exported for CI/config checks and tooling.

Open risks

The manifest parser currently rejects unknown top-level keys/shape changes (strict()); this is intentional for integrity but means any previously tolerated extras would require explicit schema evolution.
REPLAY_MANIFEST_SUPPORTED_VERSIONS currently contains only 1; future schema additions must update this list alongside version constants consistently.
Full pnpm check still fails in workspace due pre-existing markdown formatting issues in unrelated files (not introduced by this milestone), but pnpm vitest run src/replay passes including new tests.

…elpers Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling

dgarson · 2026-02-23T09:16:14Z

I’ve added a separate session-level concern for deterministic replay in PR #98 (barry/replay-session-manifest → feat/deterministic-replay).

This adds:

ReplaySessionManifest, ReplaySessionEvent, ReplaySessionEventLog types in src/sessions/replay-manifest.ts
Serialization helpers and factory functions
exportSessionManifest stub (placeholder for future integration)

This is complementary to the replay bundle format in src/replay/types.ts — session-level metadata vs bundle format. Tests pass, build succeeds.

…elpers Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling

…elpers (#98) Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling

dgarson · 2026-02-23T14:22:54Z

Architecture Review (Tim)

Target: feat/deterministic-replay ✓ — Correctly targeted.

Content Review:

clock.ts — Clean deterministic/realtime clock abstraction with configurable start/step
recorder.ts — InMemoryReplayRecorder with sink attachment, enable/disable toggle, constraint validation
runner.ts — Scenario execution with fingerprint generation, JSONL export
types.ts — Core types (ReplayEvent, ReplayManifest, constraint check results)

Code Quality:

Good separation of concerns between clock, recording, and execution
Constraint validation detects sequence mismatches with detailed violation reporting
Environment capture (nodeVersion, platform, architecture) for reproducibility
Event fingerprinting enables deterministic replay verification

Tests: Comprehensive coverage in recorder.test.ts covering:

Deterministic sequence numbering and timestamps
Sink registration for replay contracts
Disabled mode (no-op)
Sequence mismatch detection

Verdict: ✅ LGTM — Solid foundation for deterministic replay. Ready to merge.

Merging now.

dgarson · 2026-02-23T14:24:01Z

Update: ⚠️ This PR has merge conflicts with the target branch and cannot be merged as-is. The branch needs to be rebased against feat/deterministic-replay to resolve conflicts.

Once conflicts are resolved, this is ready to merge.

Merged feat/deterministic-replay into nate/deterministic-replay-kickoff. All four add/add conflicts resolved by taking the base branch as the authoritative version, which is a strict superset: adds zod schemas, parse/serialize helpers, REPLAY_EVENT_CATEGORIES constant, DEFAULT_REPLAY_CATEGORIES normalization in recorder.finalize(), and new test files (types.test.ts, manifest.test.ts). Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

…elpers Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling

…elpers (#98) Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling

* feat: scaffold deterministic replay framework * feat(replay): add manifest schema validation helpers * feat(sessions): add replay session manifest types and serialization helpers Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling * feat(replay): parse replay events and normalize recording categories * feat(sessions): add replay session manifest types and serialization helpers (#98) Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling * docs: add deterministic replay architecture and TDD plan (#108) * feat: scaffold deterministic replay framework * feat(replay): add manifest schema validation helpers * feat(sessions): add replay session manifest types and serialization helpers Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling * feat(replay): parse replay events and normalize recording categories * feat(sessions): add replay session manifest types and serialization helpers (#98) Add session-level replay manifest types distinct from the replay bundle format in src/replay/types.ts (Nate's work in PR #92). - ReplaySessionManifest: session metadata for replay-capable sessions - ReplaySessionEvent: session-level events in the replay lifecycle - ReplaySessionEventLog: collection of session events - Serialization helpers: parse/serialize functions - Factory functions: createReplaySessionId, createReplaySessionManifest, createReplaySessionEvent - exportSessionManifest stub: placeholder for future storage integration Add 43 focused tests covering: - Schema validation for all types - Serialization round-trips - Factory function behavior - Edge cases and error handling * docs: add deterministic replay architecture and TDD plan (#108) * Replay: harden recorder and deterministic clock edge cases (#182)

feat: scaffold deterministic replay framework

22f7b3c

dgarson mentioned this pull request Feb 23, 2026

feat(sessions): add replay session manifest types and serialization helpers #98

Merged

dgarson closed this Feb 24, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: scaffold deterministic replay baseline framework#92

feat: scaffold deterministic replay baseline framework#92
dgarson wants to merge 2 commits intofeat/deterministic-replayfrom
nate/deterministic-replay-kickoff

dgarson commented Feb 23, 2026 •

edited

Loading

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

dgarson commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How to Test

Known Limitations / Next Milestones

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

dgarson commented Feb 23, 2026

dr-003 Progress Update

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

dgarson commented Feb 23, 2026

Architecture Review (Tim)

Uh oh!

dgarson commented Feb 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dgarson commented Feb 23, 2026 •

edited

Loading