# 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`