64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
# 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`
|