OpenSpec Change: enterprise-diff

Change ID: enterprise-diff
Package: @suaveplan/diff
Category: universal
Target path: universal/primitives/diff
Status: PROPOSED
Date: 2026-04-19
Reference spec: /mnt/s/web/suaveplan/enterprise/diff.md

Summary

Greenfield implementation of @suaveplan/diff for the genesis branch. Ships a zero-dependency RFC 6902 JSON Patch engine with structural diffing, patch application/inversion, a linear history manager (undo/redo with branch handling), a sync manager for optimistic concurrency, and a rich path utility module. The package is a leaf — no @suaveplan/* workspace deps — so it unblocks @suaveplan/undo, @suaveplan/crdt, and event-sourcing packages downstream.

Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

Dependencies

Workspace: none (leaf)
External (via catalog): zod → catalog:forms (for wire-format schemas); tslib → catalog:build; @opentelemetry/api → catalog:observability
Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata → catalog:testing

Preserved public API surface (from main)

Core

diff(left, right, options?) — structural diff producing an RFC 6902 Patch
applyPatch(doc, patch, options?) — returns PatchResult with transformed document
revertPatch(doc, patch) — reverts a previously applied patch
invertPatch(patch), invertOperation(op)

Operations

createAdd, createCopy, createMove, createRemove, createReplace, createTest
operationsConflict(a, b), validateOperation(op), validatePatch(patch)

History / sync

createHistory(options?), class History — linear undo/redo with branch truncation
createSync(options?), class SyncManager — push/pull deltas with conflict resolution

Path utilities

parsePath, formatPath, appendPath, concatPaths, comparePaths, pathEquals, isPrefix, parentPath, lastSegment, escapeSegment, unescapeSegment

Utility functions

deepClone, deepEqual, hashValue, stringify, isObject, isPrimitive
getValueAtPath, setValueAtPath, setValueAtPathMut, insertValueAtPath, insertValueAtPathMut, deleteValueAtPath, deleteValueAtPathMut

Types

AddOperation, CopyOperation, MoveOperation, RemoveOperation, ReplaceOperation, TestOperation, BaseOperation, Operation, OperationType, Patch, PatchOptions, PatchResult, PatchError, DiffOptions, ArrayStrategy, Path, PathSegment, JsonPrimitive, JsonValue, HistoryEntry, HistoryState, HistoryOptions, SyncDelta, SyncState, SyncListener, SyncOptions

New genesis additions

Structured errors: DiffError base extends SuaveplanError; codes via defineCodes under DIFF.* (DIFF.INVALID_PATCH, DIFF.TEST_FAILED, DIFF.PATH_INVALID, DIFF.APPLY_FAILED, DIFF.INVERT_FAILED).
Zod schemas for every operation type, Patch, PatchOptions, DiffOptions, HistoryState, SyncDelta (*.schemas.ts siblings).
OTel counters diff.apply.total, diff.apply.failed, histogram diff.apply.duration_ms; diff.diff.duration_ms for diff computation.
Property-based tests (fast-check): applyPatch(doc, diff(a, b)) === b; revertPatch(applyPatch(doc, p), p) === doc; invertPatch(invertPatch(p)) === p.
mitata benchmarks for diff, applyPatch, revertPatch, SyncManager.push.

Impact

Adds one new package: universal/primitives/diff
Adds one new spec capability: diff
Unblocks Tier C: undo, crdt, event-sourcing

3.5 KiB Raw Blame History