suaveplan/openspec/archive/2026-04-24-enterprise-undo-2/proposal.md

OpenSpec Change: enterprise-undo

• Change ID: enterprise-undo
• Package: @suaveplan/undo
• Category: universal
• Target path: universal/control-flow/undo
• Status: IN PROGRESS
• Date: 2026-04-23
• Reference spec: /mnt/s/web/suaveplan/enterprise/undo.md

Summary

Greenfield implementation of @suaveplan/undo for the genesis branch. Ships a full undo/redo engine with branching history, async commands, history compression, selective undo, and command merging. All public API from the main-branch reference implementation is preserved. Genesis adds structured errors (UNDO.* codes via @suaveplan/error), Zod option schemas, EventBusLike integration for UndoStack change notifications, Clock injection for BranchingHistory timestamps, OTel counters/histograms, property-based tests (fast-check), and mitata benchmarks. The package depends on @suaveplan/diff for invertPatch/applyPatch inside createPatchCommand — no reimplementation of JSON Patch operations.

Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

Available workspace deps on genesis

Package	Catalog / version	Role
@suaveplan/error	workspace:^	Structured error base class + defineCodes
@suaveplan/types	workspace:^	Clock (timestamps in BranchingHistory), EventBusLike (UndoStack events), IdGenerator (command IDs)
@suaveplan/events	workspace:^	Concrete EventBus implementation; injected into UndoStack
@suaveplan/diff	workspace:^	diff, applyPatch, invertPatch — powers createPatchCommand
zod	catalog:forms	Zod schemas for all option types
@opentelemetry/api	catalog:observability	Counters, histograms, spans
tslib	catalog:build	TypeScript helpers

Dev deps (all catalog:testing): vitest, @vitest/coverage-istanbul, fast-check, mitata.

Preserved public API surface (from main branch)

Command primitives

• createCommand<T>(label, execute, undo, metadata?) → Command<T>
• composeCommands<T>(label, commands) → Command<T>
• executeCommand<T>(state, command) → T
• undoCommand<T>(state, command) → T
• createPatchCommand<T>(label, state, newState, metadata?) → PatchCommand<T> — uses @suaveplan/diff's diff + invertPatch; no local reimplementation
• estimateCommandSize<T>(command) → number

Type guards

• isPatchCommand<T>(cmd) → cmd is PatchCommand<T>
• isAsyncCommand<T>(cmd) → cmd is AsyncCommand<T>

Sync linear stack

• class UndoStack<T> — push, pushState, undo, redo, beginTransaction, clear, reset, snapshot, getUndoStack, getRedoStack; getters: current, canUndo, canRedo, undoSize, redoSize, activeBranchId

Branching history

• class BranchingHistory<T> — push, pushState, undo, redo, switchBranch, getBranch, deleteBranch, beginTransaction, snapshot; getters: current, canUndo, canRedo, activeBranchId, branches

Async command API

• createAsyncCommand<T>(label, execute, undo, metadata?) → AsyncCommand<T>
• composeAsyncCommands<T>(label, commands) → AsyncCommand<T>
• executeAsyncCommand<T>(state, command) → Promise<T>
• undoAsyncCommand<T>(state, command) → Promise<T>
• class AsyncUndoStack<T> — async push, undo, redo, beginTransaction (returns AsyncTransactionHandle<T>), clear, reset, snapshot; same getters as UndoStack

History compression

• class HistoryCompressor<T>(options) — compress(stack) → CompressionResult & { stack: UndoStack<T> }; getters: compressionDepth, maxHistorySize
• compressHistory<T>(stack, options) → CompressionResult & { stack: UndoStack<T> }

Selective undo

• class SelectiveUndoStack<T> extends UndoStack<T> — undoById(commandId), getDependents(commandId), canUndoById(commandId) → SelectiveUndoResult<T>

Command merging

• class CommandMerger<T>(options?, predicate?) — canMerge(a, b), add(command), flush(), reset(); getters: hasPending, pendingCount

Types (all re-exported from src/types/undo.types.ts)

Command<T>, PatchCommand<T>, AsyncCommand<T>, StackEntry<T>, Branch<T>, UndoStackOptions, BranchingOptions, UndoStackState<T>, BranchingState<T>, TransactionHandle<T>, AsyncTransactionHandle<T>, CommandMergerOptions, SelectiveUndoOptions, SelectiveUndoResult<T>, DependencyChecker<T>, HistoryCompressorOptions, CompressionResult, MergePredicate<T>

New additions for genesis

Structured errors

UndoError extends SuaveplanError; error codes registered via defineCodes under the UNDO namespace:

Code	Thrown by
UNDO.EMPTY_STACK	undo() / redo() when nothing to undo/redo (optional — currently silent; add when callers need to distinguish)
UNDO.AT_BRANCH_ROOT	BranchingHistory.switchBranch when target branch is not found
UNDO.DEPENDENCY_CONFLICT	SelectiveUndoStack.undoById when conflicts exist and throwOnConflict option is set
UNDO.COMMAND_FAILED	AsyncUndoStack.push/undo/redo when the async command rejects
UNDO.TRANSACTION_ACTIVE	UndoStack.beginTransaction when a transaction is already open
UNDO.TRANSACTION_INACTIVE	TransactionHandle.add/commit/rollback when the transaction was already closed

Zod schemas (sibling *.schemas.ts files)

UndoStackOptionsSchema, BranchingOptionsSchema, HistoryCompressorOptionsSchema, CommandMergerOptionsSchema, SelectiveUndoOptionsSchema — validated at construction time in their respective classes.

EventBusLike integration

UndoStack constructor accepts an optional EventBusLike (from @suaveplan/types). When provided it emits typed events:

Event	Payload
undo:push	{ commandId, label, undoSize }
undo:undo	{ commandId, label, undoSize }
undo:redo	{ commandId, label, redoSize }
undo:clear	{}

Clock injection

BranchingHistory and createCommand / createPatchCommand / createAsyncCommand accept an optional Clock (from @suaveplan/types) so branch createdAt and command timestamp fields are deterministic in tests (no bare Date.now() calls).

IdGenerator injection

createCommand, createPatchCommand, createAsyncCommand, and BranchingHistory._forkRedoEntries accept an optional IdGenerator (from @suaveplan/types) so id fields are deterministic in tests (no bare crypto.randomUUID() calls at module scope).

OTel instrumentation

Counters (via @opentelemetry/api meter undo):

• undo.push.total — labels: stack_type (linear | branching | async | selective)
• undo.undo.total — same labels
• undo.redo.total — same labels
• undo.compress.total

Histograms:

• undo.stack.depth — recorded on every push/undo/redo
• undo.compress.ratio — originalCount / compressedCount recorded on each compression

Property-based tests (fast-check)

• Push → undo → redo round-trip: stack.undo(); stack.redo() restores exact state for any sequence of commands.
• Stack size invariant: undoSize + redoSize equals total pushed (minus truncated).
• compressHistory idempotency: re-compressing an already-compressed stack returns squashedCount === 0 for entries within depth.
• CommandMerger merge associativity: merging [a, b, c] produces the same result regardless of flush timing.
• BranchingHistory branch isolation: switching branches never mutates other branches.

Benchmarks (mitata)

• UndoStack.push / undo / redo — 10 000 cycles with no-op closure commands.
• UndoStack.push / undo / redo — 10 000 cycles with patch commands on a medium-sized JSON object.
• compressHistory on a 1 000-entry stack with compressionDepth: 100.
• BranchingHistory.push + switchBranch — 100 branches of 10 commands each.

Impact

• Adds one new package: universal/control-flow/undo
• Adds one new spec capability: undo
• Depends on: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/diff
• Unblocks: any package requiring undo/redo history (editor tooling, collaborative editing, UI form revert)