Initial Commit

openspec/archive/2026-04-19-enterprise-diff/proposal.md

@@ -0,0 +1,63 @@
+# 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`