@signaltree/enterprise 13.1.1 → 13.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/enterprise",
-  "version": "13.1.1",
+  "version": "13.2.0",
   "description": "Enterprise optimizations for SignalTree reactive JSON. Diff-based updates, bulk operations, and advanced change tracking for large-scale applications.",
   "license": "BUSL-1.1",
   "type": "module",
@@ -68,7 +68,7 @@
   },
   "peerDependencies": {
     "@angular/core": "^20.0.0 || ^21.0.0 || ^22.0.0",
-    "@signaltree/core": "^13.1.1",
+    "@signaltree/core": "^13.2.0",
     "tslib": "^2.0.0"
   },
   "peerDependenciesMeta": {},

package/skills/using-signaltree/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: using-signaltree
+description: Guides AI agents integrating SignalTree (@signaltree/core and related packages) into Angular 20+ applications. Use when the user mentions SignalTree, @signaltree/core, @signaltree/ng-forms, @signaltree/enterprise, @signaltree/callable-syntax, @signaltree/guardrails, @signaltree/events, @signaltree/realtime, signal tree, reactive state, Angular signals store, or Angular state management; when the user wants to create, read, or update a signalTree() state tree; when the user is choosing enhancers (batching, persistence, time travel, devTools) or markers (entityMap, status, stored, form); or when the user is building reactive forms, syncing realtime data, or wiring event-driven flows on top of Angular signals.
+---
+
+# Using SignalTree
+
+SignalTree: reactive JSON for Angular. State as shape. Signals at every path. Plain state object → `signalTree()` → every leaf = Angular signal via typed `$` proxy. No action creators, reducer functions, or selector functions — mutations live as named methods on an `Ops` service, derivations as `.derived()` tiers.
+
+Mental model:
+
+- Reactive JSON tree: `signalTree(state)` mirrors input shape. Leaves = `WritableSignal<T>`. Branches = typed accessors.
+- `$` proxy: `tree.$.user.profile.name` = signal; `tree.$.user.profile` = group accessor.
+- Read: `tree.$.count()` — subscribes reactive context.
+- Write leaf: `.set(value)` / `.update(fn)`. Write branch (both forms are **deep-merge partial writes** — keys absent from the payload are preserved): `tree.$.user({ name, email })` (partial-merge object) or `tree.$.user((u) => ({ ...u, name }))` (updater function). No dispatch. There is no `tree.set(...)` — the root is callable: `tree(partial)` or `tree(updater)`.
+- Enhancers: `tree.with(batching()).with(devTools())` — order-sensitive.
+- Markers: `entityMap<User>()`, `entityMap<Plant>({ load: loader(fn) })` (cache-aware (single-scope) form), `status()`, `stored(key, defaultValue)`, `form<T>({ initial: T })` — placeholders; `signalTree()` replaces each with its runtime API at that path. Branches are natively callable for reads AND writes (writes are deep-merge partial updates — keys not in the payload are preserved); the `@signaltree/callable-syntax` build-time transform extends call-syntax to **leaf writes** only. Arrays in leaves are `WritableSignal<T[]>` — use `.update(arr => [...arr, x])`, NOT `.push()`.
+
+Don't introduce actions, reducers, action creators, or selectors — they fight the design. No module registration.
+
+**App-wide state always uses one tree.** All domains (auth, settings, tickets, feature flags, …) go into a single `signalTree()` call — never one tree per domain or one tree per service. The pattern:
+
+- `createAppTree()` — composes all domain state factories into one `signalTree()`, wired via an `APP_TREE` `InjectionToken` and a `provideAppTree()` function. **Also export `createBaseState()`** — tests need it to build isolated trees.
+- `AppStore` — a single `providedIn: 'root'` class that injects `APP_TREE`, exposes `readonly $ = this.tree.$`, and namespaces per-domain `Ops` classes under `readonly ops = { … } as const`.
+- `Ops` classes — one per domain (`DriverOps`, `SettingsOps`, …), each `Injectable`, each injecting `APP_TREE` directly for writes. No business logic in `AppStore` itself.
+- **Consumers (components, resolvers, interceptors, guards) inject `AppStore` only** — never an Ops class or `APP_TREE` directly. Reads go through `store.$`; writes go through `store.ops.<domain>.<method>()`.
+- **Ship `provideAppTreeForTesting()` alongside `provideAppTree()` from day one.** `AppStore` is `providedIn: 'root'`, so every `TestBed` that touches it (or any consumer that touches it transitively) will fail with `NG0201: APP_TREE` until tests provide the token. See [`reference/testing.md`](reference/testing.md).
+
+Read [`reference/patterns.md`](reference/patterns.md) for the full wiring before writing any store code.
+
+Component-local state (a single component's ephemeral UI state) is the only case where a tree lives outside `APP_TREE`.
+
+Install:
+
+```bash
+npm install @signaltree/core
+# pnpm: pnpm add @signaltree/core
+```
+
+See [`reference/install.md`](reference/install.md) for optional packages and peer-dependency details.
+
+```ts
+import { signalTree } from '@signaltree/core';
+const tree = signalTree({ counter: 0, user: { name: 'Ada', email: 'ada@example.com' } });
+tree.$.user.name(); // read
+tree.$.counter.set(1); // write leaf
+tree.$.user({ name: 'Grace', email: 'grace@example.com' }); // write branch
+```
+
+`$` proxy exposes signals — `@if`, `@for`, `[value]`, two-way bindings work natively. See [`reference/patterns.md`](reference/patterns.md) for template idioms.
+
+Enhancer / package decision tree — start with `@signaltree/core` alone; add only when you hit the matching problem:
+
+- Group CD notifications → `batching()` from `@signaltree/core`.
+- Persist tree to `localStorage` → `persistence({ key, autoSave, autoLoad, debounceMs })` from `@signaltree/core`. Single leaf → `stored()` marker.
+- `computed()` running too often → use Angular's `computed()` — it already memoizes by reference. SignalTree no longer ships a `memoization` enhancer (removed in 9.0.1); for deep-equality cache keys, derive via your own `computed()` with explicit comparison.
+- Debug history, time travel, Redux DevTools → `timeTravel()` / `devTools({ treeName })` from `@signaltree/core`.
+- Large app, bulk updates slow, diff-based patching → add `@signaltree/enterprise`, compose `enterprise()`. Read [`enterprise/SKILL.md`](enterprise/SKILL.md).
+- Reactive forms (validation, dirty/touched, wizards, FormGroup interop) → add `@signaltree/ng-forms`; on Angular 22+ the same package bridges to **Signal Forms** via `signalForm` from `@signaltree/ng-forms/signals`. Read [`ng-forms/SKILL.md`](ng-forms/SKILL.md).
+- `tree.$.field('value')` sugar over `.set()` → add `@signaltree/callable-syntax` (build-time transform, zero runtime cost). Read [`callable-syntax/SKILL.md`](callable-syntax/SKILL.md).
+- Dev-time perf budgets, memory-leak detection, anti-pattern warnings → add `@signaltree/guardrails` (dev-only; noop in production). Read [`guardrails/SKILL.md`](guardrails/SKILL.md).
+- Event-driven with Zod schemas, idempotency, retries → add `@signaltree/events` (ESM-only, requires Zod). Read [`events/SKILL.md`](events/SKILL.md).
+- Sync tree to Supabase / Firebase / WebSocket → add `@signaltree/realtime`, compose `supabaseRealtime()` or `realtime()`. Read [`realtime/SKILL.md`](realtime/SKILL.md).
+
+Composing enhancers — typical production shape:
+
+```ts
+import { signalTree, batching, devTools } from '@signaltree/core';
+
+interface AppState {
+  counter: number;
+  ui: { theme: 'light' | 'dark' };
+}
+
+const tree = signalTree<AppState>({ counter: 0, ui: { theme: 'light' } })
+  .with(batching({ enabled: true, notificationDelayMs: 0 }))
+  .with(devTools({ treeName: 'AppStore' }));
+```
+
+Cross-package enhancers (`enterprise()`, `guardrails()`, `formBridge()`, `supabaseRealtime(...)`) slot into same chain.
+
+Angular Signal Forms bridge (Angular 22+, v11.6+) — not an enhancer; `signalForm` from `@signaltree/ng-forms/signals` turns a `form()` marker into a Signal Forms `FieldTree` sharing the marker's values signal (one model, no sync loops):
+
+```ts
+import { signalForm } from '@signaltree/ng-forms/signals';
+import { signalTree, form } from '@signaltree/core';
+
+const tree = signalTree({
+  onboarding: { profile: form({ initial: { name: '' } }) },
+});
+const profile = signalForm(tree.$.onboarding.profile); // FieldTree<{ name: string }>
+// template: <input [formField]="profile.name" /> — marker validators run as Signal Forms
+// validators with real error kinds; built-ins emit Angular's branded errors by
+// default (13.2+) — pass { nativeErrors: false } for plain { kind, message }.
+// Async validation is NOT unified — pick ONE authority (marker submit() path OR validateAsync).
+```
+
+Schema-registry overload: `signalForm<TModel>(tree, rootPath, tree.$.subtree)` after `.with(schemas(...))` auto-applies every registered schema under `rootPath`. (`markerSignalForm`/`signalFormBridge` are deprecated 11.5.0 aliases — emit `signalForm`.)
+
+Markers — placed in initial state, replaced by `signalTree()` with fully-typed runtime API:
+
+- `entityMap<T, K>()` — O(1) CRUD: `addOne`, `upsertOne`, `removeOne`, `setAll`, `byId`, `all`, `clear`. Predicates: `.empty()` (the `.isEmpty` alias was removed in v11). Reads: `.count()`, `.has(id)`, `.where(pred)`, `.find(pred)`. Config: `entityMap<T,K>({ selectId, sortComparer })` — v10.5+ `sortComparer` keeps `all()`/`ids()` sorted (`@ngrx/entity` parity). `byId(id).field()` is body-granular (fan-out 1). `.computed('name', all => …)` attaches a derived slice to the collection at declaration; read it as `tree.$.users.name()` — **typed on `tree.$` since v13.2**, no cast, and chainable (each name typed independently). `compute` sees only that collection's `E[]`, so cross-collection/external-state projections stay a normal `computed`/`.derived()`. **Cache-aware / self-loading form (v11.2+, scoped form v11.4+):** wrap a load function with the `loader()` helper and pass it as `load` in config, and `entityMap` gains a loader surface — **use this instead of hand-wiring `entityMap` + `status` + a loader + a load-guard** for any server-backed collection. `loader()` is a separate export from `@signaltree/core`; it's what keeps the loader machinery tree-shakeable — a plain `entityMap()` (no `load`) doesn't pay for it. Config adds: `config.load: loader(() => Observable<E[]> | Promise<E[]>, { staleTime, swr, tags, persist, equal, lazy, clearOnParamsChange })` — `staleTime` (`'30m'`/ms — skip refetch while fresh; default `0` = always stale), `swr` (serve last value while revalidating), `tags` (for `invalidateTag`), `persist` (offline-first hydrate-then-revalidate via a `StorageAdapter`). Methods added: `.load()` (guarded — no-op if fresh OR in-flight, so N callers = one fetch), `.loadOrThrow()` (same guard as `.load()`, but rejects with the loader's error instead of only surfacing it via `.error()` — for imperative await/try-catch call sites; `.load()` never rejects), `.refresh()` (force, still single-in-flight), `.invalidate()` (mark stale — next `load()` refetches). Status: `.loading()`, `.loaded()`, `.error()`, `.lastLoadedAt()`. Tag-based push invalidation: `invalidateTag(tree, 'plants')` marks every collection carrying that tag stale — the clean seam for SSE/SignalR (`@signaltree/realtime`). Auto-loads on first `tree.$` access (unless `loader()`'s `lazy: true`). **Scoped form (v11.4+):** a wrapped loader function that declares a param makes the collection scoped: `entityMap<E, K, P>({ load: loader((p) => api.list$(p)) })` — call `load(params)` with the scope (region/customer/tenant); freshness (`staleTime`) is tracked per scope via `loader()`'s `equal?: (a, b) => boolean` option (default: structural value compare), so a scope change refetches even if the old scope was fresh, and a different scope requested mid-fetch supersedes (last-request-wins). `params()` exposes the loaded scope (typed `Signal<P | undefined>`); `refresh(params?)` forces a reload; `loader()`'s `clearOnParamsChange` option blanks rows on scope change. Scoped collections are always lazy. Single-scope cache (no multi-key LRU yet). (Auto-load is deferred off the render pass, so a non-lazy collection read in a template is NG0600-safe.) There is no separate `entityCollection` marker — a plain `entityMap<T, K>()` (no `load`) is unaffected.
+- `status()` — async op state. Write methods: `setLoading()` / `setLoaded()` / `setError(err)` / `setNotLoaded()` / `reset()`. v10.2 Promise-vocabulary aliases also work: `.start()` (= setLoading), `.setSuccess()` / `.succeed()` (= setLoaded), `.fail(err)` (= setError). Read predicates (canonical, bare names): `.loading()`, `.loaded()`, `.notLoaded()`, `.hasError()`, `.idle()`, `.settled()` — all callable signals, invoke them. (The `is`-prefix aliases were removed in v11.) `.settled()` = `loaded() || hasError()` ("done, stop the spinner"). **In a guard/resolver use `.idle()`** (= `!loading() && !loaded()`, covers NotLoaded AND Error) as the "should I (re)fetch?" predicate — `.notLoaded()` is false in the Error state, so a `.notLoaded()`-gated fetch silently never retries after an error. Prefer `.idle()` over `state() === …` enum comparisons.
+- `asyncSource<T>(config)` — load-and-expose (preferred over `status()` + manual try/catch). Auto-derives `.loading()`, `.error()`, `.data` accessor, `.refresh()` reload.
+- `asyncQuery<TInput, TResult>(config)` — input-driven debounced query with built-in switchMap + dedup pipeline. Drive via `.input.set(value)`; read current result on `.results` / `.data`; status on `.loading()` / `.error()`. Lifecycle: `.rerun()` re-fires with the current input (bypasses dedup), `.reset()` clears state. No `.refresh()` — that's on `asyncSource` only.
+- **Streaming/LLM token output — no exported marker.** An `asyncStream` marker exists in-repo but is experimental and NOT exported from `@signaltree/core` as of 11.x — do not emit `asyncStream` or `createAsyncStreamSignal` (the import fails). `asyncSource`/`asyncQuery` REPLACE per emission (wrong tool for token deltas) — accumulate into a plain leaf instead: `tree.$.reply.update((t) => t + chunk)` inside a `for await` over the SDK's stream. There is no `@signaltree/ai` package — wire your AI SDK in directly. Don't model tokens as a pushed array.
+- `stored(key, default)` — single signal backed by `localStorage`.
+- `form<T>(config: FormConfig<T>)` — tree-integrated form marker, **exported from `@signaltree/core`** (`@signaltree/ng-forms` is a separate FormGroup bridge, not the marker source). Config requires `{ initial: T, validators?, asyncValidators?, wizard? }`. Read the value by calling the marker (`tree.$.profile()`) or via the v10.4 alias `tree.$.profile.data()` — both return `T`. Bare-name accessors: `.dirty`, `.valid`, `.touched`, `.submitting` (NOT `.pristine`, NOT `.isDirty()`); value accessors: `.errors`, `.errorList`. Methods: `.validate()`, `.validateField(field)`, `.touch(field)`, `.submit(handler)` (handles touchAll + validate + submitting toggle + error trap internally).
+
+Audit trail — `createAuditTracker(tree, auditLog, config?)`, **exported from `@signaltree/core`** (v13; `@signaltree/ng-forms/audit` is now a `@deprecated` back-compat re-export — import from core). Framework-agnostic and tree-shakeable (only bundled if imported); not an Angular-forms concern, works on any `signalTree()`. Pushes an `AuditEntry<T>` (`{ timestamp, changes, previousValues?, metadata? }`) into your own `auditLog: AuditEntry<T>[]` array on every state change, and returns an unsubscribe `() => void`. Config: `{ includePreviousValues?, getMetadata?: () => AuditMetadata, filter?: (changes) => boolean, maxEntries? }` (`maxEntries` bounds the log via a ring-buffer trim; `0` = unlimited). Uses `tree.subscribe()` when the tree has one; core `signalTree()` doesn't, so it falls back to ~100ms polling automatically — no extra wiring needed either way. `createAuditCallback(auditLog, getMetadata?)` returns a bare `(previous, current) => void` diff callback for when you already have your own `tree.subscribe()` call site instead.
+
+Full signatures: [`reference/core.md`](reference/core.md).
+
+Deep dives:
+
+- [`reference/core.md`](reference/core.md) — `signalTree()` signatures, `$` proxy, markers, enhancer composition, reads/writes.
+- [`reference/patterns.md`](reference/patterns.md) — idiomatic creation, templates, `computed()`/`effect()` interop, bulk updates, `derivedFrom`, **hybrid migration via legacy facade adapters**, lifetime caveats for root-provided Ops.
+- [`reference/testing.md`](reference/testing.md) — `provideAppTreeForTesting()` recipe, mocking matrix (tree vs ops vs facade), common test-bed pitfalls.
+- [`reference/anti-patterns.md`](reference/anti-patterns.md) — what not to do.
+- [`reference/install.md`](reference/install.md) — Angular version requirement, install commands.
+- [`reference/migration-from-ngrx-signals.md`](reference/migration-from-ngrx-signals.md) — mechanical mapping guide when porting an existing `@ngrx/signals` codebase. Only relevant for `@ngrx/signals` (`signalStore`, `withState`, `rxMethod`) — not classic `@ngrx/store`.
+- [`reference/migration-from-ngrx-store.md`](reference/migration-from-ngrx-store.md) — mechanical mapping guide when porting a **classic `@ngrx/store`** codebase (`createAction`/`createReducer`/`createSelector`/`createEffect`, `@ngrx/entity`, `StoreModule`/`provideStore`). Actions → `Ops` methods, reducers → signal writes, selectors → `computed()`/derived tiers, effects → `asyncSource`/`Ops` observables. Shares the target architecture with the `@ngrx/signals` guide.
+- [`reference/optimal-implementation.md`](reference/optimal-implementation.md) — prescribed file/folder layout, pattern defaults (`entityMap`, multi-tier derived, enhancer baseline), and the migration definition-of-done checklist. **Read this before beginning any non-trivial migration.**
+- [`reference/orchestrating-a-migration.md`](reference/orchestrating-a-migration.md) — process playbook for an orchestrator agent driving one or more implementer subagents through a phased SignalTree adoption. Applies to NgRx Signal Store migration (default), classic NgRx / `BehaviorSubject` / `@Injectable` state migration (with adapted Phase 1 greps), and greenfield adoption (Phase 1 is a no-op). Load when the work spans more than ~5 consumer files, when a single implementer is likely to exhaust its context window, or when the user asks for a phased / supervised rollout.
+
+Sub-skills:
+
+- [`ng-forms/SKILL.md`](ng-forms/SKILL.md)
+- [`enterprise/SKILL.md`](enterprise/SKILL.md)
+- [`callable-syntax/SKILL.md`](callable-syntax/SKILL.md)
+- [`guardrails/SKILL.md`](guardrails/SKILL.md)
+- [`events/SKILL.md`](events/SKILL.md)
+- [`realtime/SKILL.md`](realtime/SKILL.md)
+
+Operating rules:
+
+- Prefer `@signaltree/core` first. Add optional packages only for concrete problems.
+- Never instruct consumers to install `@signaltree/shared`, `@signaltree/types`, or `@signaltree/utils` — private, bundled at build time.
+- Never write to a signal inside `computed()` — read-only; side effects in `effect()` or event handlers.
+- Custom markers: call `registerMarkerProcessor()` before any `signalTree()` call that relies on them.
+- Don't reintroduce Redux-style patterns.
+- When unsure of an API, read `packages/<pkg>/src/` — repo is source of truth.
+- **One tree per application.** If the codebase has multiple existing stores (ngrx, services, etc.), compose them all into a single `signalTree()` behind `APP_TREE`. Creating multiple `signalTree()` instances for app-wide state is always wrong.
+- **A migration is not done until the test suite is green.** Build-green is necessary but not sufficient — the test suite must pass before declaring the migration complete. The most common failure is `NG0201: APP_TREE` in `TestBed`s; fix it via `provideAppTreeForTesting()` ([`reference/testing.md`](reference/testing.md)), not by mocking `AppStore`.
+- **Big-bang migration is the default.** Migrate every domain, delete every legacy store, drop the legacy package from `package.json` in the same PR. The hybrid-facade pattern is a _fallback_ for when PR-size, team-coordination, or release-cadence constraints prevent big-bang — never an end-state. If you ship a hybrid facade, it must include a `// TODO(legacy-facade): remove by <date/release>` and a tracking issue. See [`reference/optimal-implementation.md`](reference/optimal-implementation.md) and [`reference/migration-from-ngrx-signals.md`](reference/migration-from-ngrx-signals.md).
+- **Big-bang means deletion in the same commit.** Standing up the new `AppStore` next to the legacy `signalStore` files is _not_ a migration — it's a hybrid you forgot to finish. Before declaring done, the legacy `*.store.ts` files for every migrated domain must be `rm`-ed (along with their `*.store.spec.ts` siblings and any re-exports), and `grep -rln '@ngrx/signals' <migrated-app-src>/` must return empty. If the grep is non-empty and you are not on the explicit hybrid-fallback path, **stop and finish the deletion before continuing**.
+- **Pattern defaults you must apply** unless the codebase explicitly forbids them:
+  - **`entityMap<T, K>()` for any keyed collection** (anything with `id`/key lookup, membership tests, or cross-references). Plain `T[]` is only correct for ordered, append-only, non-keyed lists.
+  - **Per-domain state files** (`tree/state/<domain>.state.ts`) once the tree has more than two domains. Don't keep all state in one `app-tree.ts`.
+  - **Multi-tier `.derived()` chains in named files** (`tree/derived/tier-<concern>.derived.ts`) once you have ≥ 3 derived concerns or any cross-tier dependency. See [`reference/patterns.md`](reference/patterns.md#splitting-derived-tiers-into-separate-files).
+  - **Enhancer baseline for production trees**: `devTools({ treeName }) + batching() + timeTravel()` minimum. Tests skip enhancers; production does not. (`memoization` was removed in 9.0.1 — use Angular `computed()`.)
+  - **Cross-domain orchestration belongs on `AppStore`**, not on any one Ops class. Single-domain methods belong on Ops; methods that touch ≥ 2 domains belong on `AppStore`.
+- **Definition of done for a migration:** (1) zero imports of the legacy package in the migrated app, (2) legacy package removed from `package.json` (or, if other apps still use it, a tracking ticket exists for removal), (3) test suite green, (4) DevTools shows the new tree under the chosen `treeName`. The full checklist is in [`reference/optimal-implementation.md`](reference/optimal-implementation.md#definition-of-done).

package/skills/using-signaltree/enterprise/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: signaltree-enterprise
+description: Guides AI agents applying @signaltree/enterprise to large SignalTree state for diff-based bulk updates, optimized partial writes, and path-index monitoring. Triggers on @signaltree/enterprise, updateOptimized, bulk updates, large state tree, diff engine, path index, getPathIndex, 500+ signals, enterprise enhancer.
+---
+
+# Using @signaltree/enterprise
+
+Use when the tree has 100s of signals and a single action replaces a large state slice (API hydration, tick-driven snapshots, subtree migrations). Diffs `Partial<T>` and only writes signals whose values changed — 2–5× faster than naive `tree.update()` for large collections. Skip for small/mostly-static trees.
+
+**License: BSL-1.1** (not MIT). Surface this when user is building for production commercial deployment.
+
+Install:
+
+```bash
+npm install @signaltree/core @signaltree/enterprise
+```
+
+Peer: `@angular/core ^20`, `@signaltree/core ^9`. No additional runtime deps.
+
+Apply the enhancer:
+
+```ts
+import { signalTree } from '@signaltree/core';
+import { enterprise } from '@signaltree/enterprise';
+
+const tree = signalTree(initial).with(enterprise());
+```
+
+Bulk replace with `updateOptimized`:
+
+```ts
+import { signalTree } from '@signaltree/core';
+import { enterprise } from '@signaltree/enterprise';
+
+interface State { entities: { id: number }[]; lastSyncAt: string }
+declare const entities: State['entities'];
+const tree = signalTree<State>({ entities: [], lastSyncAt: '' }).with(enterprise());
+
+const result = tree.updateOptimized({
+  entities,
+  lastSyncAt: new Date().toISOString(),
+});
+console.log(`${result.changedPaths.length} paths changed in ${result.duration}ms`);
+```
+
+`updateOptimized` takes `Partial<T>` (not an updater fn). Only diffed keys are touched; other branches are completely untouched.
+
+Diff options:
+
+```ts
+import { signalTree } from '@signaltree/core';
+import { enterprise } from '@signaltree/enterprise';
+
+interface State { entities: { id: number }[] }
+declare const nextEntities: State['entities'];
+const tree = signalTree<State>({ entities: [] }).with(enterprise());
+
+tree.updateOptimized(
+  { entities: nextEntities },
+  {
+    ignoreArrayOrder: true,  // treat arrays as unordered sets — only use when item identity is stable
+    maxDepth: 6,             // stop diffing below this depth; replace whole subtree instead
+    equalityFn: (a, b) =>
+      a === b || (a instanceof Date && b instanceof Date && a.getTime() === b.getTime()),
+    autoBatch: true,
+    batchSize: 500,          // chunk writes to keep microtasks short
+  }
+);
+```
+
+`UpdateResult` shape: `{ changed: boolean, duration: number (ms), changedPaths: string[], stats? }`.
+
+`getPathIndex()` — returns `PathIndex` (dotted paths of every leaf) or `null` before first `updateOptimized` call:
+
+```ts
+import { signalTree } from '@signaltree/core';
+import { enterprise } from '@signaltree/enterprise';
+
+const tree = signalTree({ count: 0 }).with(enterprise());
+const idx = tree.getPathIndex();
+if (idx) { /* use idx with result.changedPaths for heatmaps, etc. */ }
+```
+
+Key contracts:
+- `undefined` at a path = no change. Use `null` (or empty sentinel) to clear explicitly.
+- `getPathIndex()` is `null` until first `updateOptimized` call. Not live between calls — rebuilt on next optimized write.
+- Dynamic paths (added beyond initial shape) are not auto-indexed; force rebuild via `updateOptimized({})`.
+- Keep using `tree.update(...)` for small targeted writes; `updateOptimized` for large `Partial<T>` replacements only.
+
+Gotchas:
+- `ignoreArrayOrder: true` treats arrays as sets — reorders silently missed if item identity isn't stable.
+- `updateOptimized` returns `changed: false` when nothing differed — don't assume it always mutates.
+- `maxDepth` stops recursion at that depth; subtree written as unit. `getPathIndex()` rebuilt after plain `update()` on next optimized write — consistent but not live.
+
+Related: `using-signaltree` (root), `spec-auditing`, `compression`

package/skills/using-signaltree/reference/anti-patterns.md

@@ -0,0 +1,266 @@
+# Anti-patterns
+
+Things not to do with SignalTree, and what to do instead. Each item shows a wrong example and a right one.
+
+> **Note for editors:** `scripts/lint-skills.mjs` type-checks every fenced
+> `ts` / `typescript` / `tsx` block in this directory against the real built
+> `@signaltree/*` packages. To mark a block as an intentional anti-pattern
+> that must not be type-checked (syntax is still parsed), add a
+> `// @skip-lint` comment as the first non-blank line of the block, or add
+> `wrong` / `bad` / `skip` to the fence info string (e.g. ` ```ts wrong `).
+
+## Do not reintroduce actions / reducers / selectors
+
+SignalTree replaces dispatch-plus-reducer pipelines with direct reactive JSON. If you're designing actions and reducers on top of it, you're fighting the design.
+
+```ts
+// ✗ Wrong — Redux-style layer on top of SignalTree
+type Action = { type: 'inc' } | { type: 'reset' };
+
+function reduce(state: { count: number }, action: Action) {
+  switch (action.type) {
+    case 'inc':
+      return { ...state, count: state.count + 1 };
+    case 'reset':
+      return { ...state, count: 0 };
+  }
+}
+```
+
+```ts
+// ✓ Right — mutate the tree directly
+import { signalTree } from '@signaltree/core';
+
+const tree = signalTree({ count: 0 });
+
+function inc() {
+  tree.$.count.update((n) => n + 1);
+}
+function reset() {
+  tree.$.count.set(0);
+}
+```
+
+If you want undo/redo, add `timeTravel()`. If you want DevTools, add `devTools()`. You don't need action types.
+
+## Do not write inside `computed()`
+
+`computed()` must be a pure read. Writing to a signal inside it causes infinite re-computation loops and detached reactivity.
+
+```ts
+// ✗ Wrong — writing inside computed()
+import { computed } from '@angular/core';
+import { signalTree } from '@signaltree/core';
+
+const tree = signalTree({ count: 0, doubled: 0 });
+
+const doubled = computed(() => {
+  const n = tree.$.count() * 2;
+  tree.$.doubled.set(n); // ← never do this
+  return n;
+});
+```
+
+```ts
+// ✓ Right — derive with computed(), or mirror with effect()
+import { computed, effect } from '@angular/core';
+import { signalTree } from '@signaltree/core';
+
+const tree = signalTree({ count: 0 });
+
+// pure derivation
+const doubled = computed(() => tree.$.count() * 2);
+
+// or, if a mirrored leaf is genuinely needed:
+const mirror = signalTree({ doubled: 0 });
+effect(() => mirror.$.doubled.set(tree.$.count() * 2));
+```
+
+## Do not install `@signaltree/shared`, `types`, or `utils`
+
+These are **private, bundled packages** consumed internally by the public `@signaltree/*` packages. Adding them to `dependencies` leads to duplicate module graphs, version skew, and broken type inference.
+
+```jsonc
+// ✗ Wrong — package.json dependencies
+{
+  "dependencies": {
+    "@signaltree/core": "^9.0.0",
+    "@signaltree/shared": "^9.0.0", // ← don't
+    "@signaltree/types": "^9.0.0", // ← don't
+    "@signaltree/utils": "^9.0.0" // ← don't
+  }
+}
+```
+
+```jsonc
+// ✓ Right — only the public packages you actually use
+{
+  "dependencies": {
+    "@signaltree/core": "^9.0.0",
+    "@signaltree/ng-forms": "^9.0.0"
+  }
+}
+```
+
+## Do not register marker processors after tree creation
+
+`registerMarkerProcessor()` must run **before** any `signalTree()` call that relies on the custom marker, otherwise the marker stays in the state object as an unprocessed placeholder.
+
+```ts wrong
+// ✗ Wrong — registration happens too late.
+// Intentional anti-pattern; skipped by the skill lint.
+import { signalTree } from '@signaltree/core';
+import { registerMarkerProcessor } from '@signaltree/core/authoring';
+import { myMarker, MY_MARKER, myProcessor } from './my-marker';
+
+const tree = signalTree({ slot: myMarker() }); // ← processor not registered yet
+registerMarkerProcessor(MY_MARKER, myProcessor);
+```
+
+```ts
+// ✓ Right — register first, then create trees
+import { signalTree } from '@signaltree/core';
+import { registerMarkerProcessor } from '@signaltree/core/authoring';
+import { myMarker, MY_MARKER, myProcessor } from './my-marker';
+
+registerMarkerProcessor(MY_MARKER, myProcessor);
+
+const tree = signalTree({ slot: myMarker() });
+```
+
+## Do not hold stale node references across tree recreations
+
+If you replace a subtree wholesale (`tree.$.user(newObj)`) or rebuild the tree itself, any previously captured node reference may no longer point at the live signal.
+
+```ts
+// ✗ Wrong — capturing a branch accessor then replacing the subtree
+import { signalTree } from '@signaltree/core';
+
+const tree = signalTree({ user: { name: 'Ada' } });
+const userNode = tree.$.user; // captured
+tree.$.user({ name: 'Grace' }); // subtree replaced
+// userNode may be stale now — re-read from tree.$ instead
+```
+
+```ts
+// ✓ Right — re-read through tree.$ when you need the current node
+import { signalTree } from '@signaltree/core';
+
+const tree = signalTree({ user: { name: 'Ada' } });
+tree.$.user({ name: 'Grace' });
+const currentName = tree.$.user.name(); // always reads the live signal
+```
+
+As a rule: pass the `tree` (or a narrow factory-exposed API) rather than long-lived raw node references.
+
+## Do not use branch replacement on subtrees that contain markers
+
+The callable branch form `tree.$.domain(newObj)` replaces the entire subtree with
+a plain object. Any `status()`, `entityMap()`, or custom marker nodes inside that
+subtree are **overwritten** — the marker-backed methods (`setLoading`, `upsertOne`,
+etc.) disappear and the plain value is written in their place.
+
+```ts wrong
+import { signalTree, status, entityMap } from '@signaltree/core';
+
+interface Item {
+  id: number;
+}
+const tree = signalTree({
+  items: { entities: entityMap<Item>(), loading: status() },
+});
+
+// ✗ Wrong — overwrites the marker nodes with plain values
+tree.$.items({ entities: [], loading: { state: 'idle', error: null } });
+// tree.$.items.loading.setLoading is now undefined
+```
+
+```ts
+import { signalTree, status, entityMap } from '@signaltree/core';
+
+interface Item {
+  id: number;
+}
+const tree = signalTree({
+  items: { entities: entityMap<Item>(), loading: status() },
+});
+
+// ✓ Right — update each writable leaf individually
+tree.$.items.entities.clear();
+tree.$.items.loading.setLoading();
+```
+
+This applies to any subtree that contains markers — `status()`, `entityMap()`,
+or custom markers registered via `registerMarkerProcessor`. As a practical rule:
+if a domain slice has markers in it, reset it by calling its individual writable
+leaves rather than replacing the whole branch.
+
+## Do not service-wrap a component-local tree
+
+SignalTree trees can live on a component or in a plain factory function.
+Wrapping a component-local tree in a `providedIn: 'root'` service adds ceremony
+without reactivity benefit and turns a per-component counter into accidental
+global state.
+
+```ts wrong
+// ✗ Wrong — a root service for a component-local counter
+import { Injectable } from '@angular/core';
+import { signalTree } from '@signaltree/core';
+
+@Injectable({ providedIn: 'root' })
+class CounterService {
+  readonly tree = signalTree({ count: 0 });
+}
+```
+
+```ts
+// ✓ Right — component-local is fine
+import { Component } from '@angular/core';
+import { signalTree } from '@signaltree/core';
+
+@Component({ selector: 'app-counter', template: '' })
+class CounterComponent {
+  readonly tree = signalTree({ count: 0 });
+}
+```
+
+## Do not leave the legacy `signalStore` on disk after migrating
+
+This is the single most common failure mode when migrating from `@ngrx/signals`. An agent (or a hurried human) stands up the new `AppStore` + `APP_TREE` + per-domain `Ops`, migrates the consumers, and then **stops** — leaving `driver.store.ts`, `feature-flag.store.ts`, etc. on disk, still importing `@ngrx/signals`, still calling `signalStore({ providedIn: 'root' }, ...)`. That is not a migration. It is a half-finished hybrid that will rot: the legacy stores are still constructed at app boot, still register with DevTools, still hold state, and they silently diverge from the new tree.
+
+**The legacy `*.store.ts` files for every migrated domain must be deleted in the same commit that adds the new `AppStore` shape.** This includes the `.store.spec.ts` sibling and any barrel re-exports that point at the deleted file.
+
+```ts skip
+// ✗ Wrong — new AppStore committed alongside untouched legacy stores
+// src/app/store/app-store.ts                ← new
+// src/app/store/tree/app-tree.ts            ← new
+// src/app/<legacy-path>/driver.store.ts        ← still there, still signalStore(...)
+// src/app/<legacy-path>/feature-flag.store.ts  ← still there, still signalStore(...)
+// src/app/<legacy-path>/plant.store.ts         ← still there, still signalStore(...)
+```
+
+```bash
+# ✓ Right — verify deletion before declaring done.
+# All three must return empty (no output) inside the migrated app:
+grep -rln "from '@ngrx/signals'" <app-src>/
+grep -rln 'signalStore('         <app-src>/
+find <app-src> -name '*.store.ts' -not -path '*/node_modules/*'
+```
+
+If any of those greps returns output and you are not on the explicit hybrid-fallback path documented in [`optimal-implementation.md`](optimal-implementation.md#when-the-hybrid-pattern-is-acceptable), **stop and finish the deletion before committing**. Do not write the migration report, do not push, do not declare success.
+
+The hybrid-facade pattern in [`patterns.md`](patterns.md#hybrid-migration-legacy-facade-adapters-fallback) is the _only_ exception, and it requires a `// TODO(legacy-facade): remove by <date/release>` plus a tracking issue.
+
+### When a shared service IS correct
+
+A shared service is exactly the right shape when the tree is **genuinely**
+shared across components, routes, or the whole app — for example, a single
+application-wide store, an auth/identity store, or a store holding data
+fetched once and reused. That case has its own canonical recipe (and is also
+what migrations from `@ngrx/signals signalStore({ providedIn: 'root' })` map
+onto); see the "Shared service (`providedIn: 'root'`)" and
+"Prefer a single global store" sections in
+[`patterns.md`](patterns.md).
+
+The rule is: let scope drive the decision. Local state → component field.
+Shared state → a service (or a single app-wide store).