@signal-tree/angular 15.3.1 → 15.4.2

package/README.md

@@ -185,9 +185,21 @@ construction, not arbitrary later writes or foreign reactivity from other librar
 
 ## Transaction failures
 
-Read [Transaction failures and current v15 limitations](https://github.com/JBorgia/signal-tree/blob/fix/15.3.1-link-rollback-and-strand/docs/guides/transaction-failures-v15.md)
+Read [Transaction failure policy and the 15.3.1 failure inventory](https://github.com/JBorgia/signal-tree/blob/v15.3.1/docs/guides/transaction-failures-v15.md)
 before combining transactions, undo, or persistence. Explicit rollback refusal
 leaves state unchanged and the handle pending but releases consequences in v15. The
-unreleased 15.3.1 candidate commits surviving writes on automatic refusal
+15.3.1 release commits surviving writes on automatic refusal
 before a handle returns and still throws. An error does not guarantee undo;
 never blindly retry the entire operation.
+
+## Independent editors and connections
+
+Keep shared records in an owned tree. Give each independently closable editor or
+connection its own lifetime; native local form state may be enough for a draft.
+A declared EntityMap supports dynamic data membership, not runtime installation
+of composite slices. Separate trees do not share transactions or undo history.
+Destroy directly created trees at their ownership boundary.
+
+See the [owned sessions guide](../../docs/guides/owned-sessions.md) for the Angular
+reference demo, stale-save policy, same-ID replacement and cleanup tests. Use this
+package’s own reactive/lifecycle integration when applying the pattern.

package/llms.txt

@@ -1,7 +1,11 @@
 # SignalTree
 
-SignalTree is framework-neutral reactive application state with causal
-semantics. The public v15 construction model is
+This reference describes the 15.4.2 package version, with explicitly marked
+15.3.1 comparisons. Consult the [npm package page](https://www.npmjs.com/package/@signal-tree/kernel?activeTab=versions)
+for published versions.
+
+SignalTree keeps nested state, entity identity, transactions, undo, external
+updates and reactive publication consistent across frameworks. The v15 construction model is
 `signalTree(initialState, { derived, enhancers })`; state is read through
 `tree.$`.
 
@@ -94,9 +98,15 @@ locations and observes selected state through `useSignalTree(owner, selector)`.
 EntityMap query and field leaves follow the same carrier rule; EntityMap command
 methods such as `setAll()` and `updateOne()` do not change.
 
+Replace atomic values through their location. In-place mutation of a returned
+object, array, Map or Set is not a recorded write; restoration does not provide
+deep-copy isolation for mutable payloads.
+
 Plain objects normally become traversable branches. `leaf(value)` explicitly
-ends topology so an object remains one atomic location. Callable values always
-use `leaf()` because a bare function argument is the updater syntax:
+ends topology so an object remains one atomic location. Declare function-valued
+fields with `leaf(fn)`. At a callable write boundary, use `leaf(fn)` to distinguish
+a stored function from an updater. Native Angular `.set(fn)` assigns the function
+directly, as shown below:
 
 ```typescript
 import { signalTree, leaf } from '@signal-tree/angular';
@@ -189,7 +199,8 @@ of the same model.
 ## Canonical Sources
 
 - `AGENTS.md` — contributor and consumer rules
-- `RELEASE-1.0.md` — v15 release invariants and current release state
+- `RELEASE-CURRENT.md` — active candidate, current release work and blockers
+- `RELEASE-1.0.md` — historical derivations, failures and prior checkpoints
 - `README.md` — public package overview
 - `packages/kernel/README.md` — kernel API and examples
 - `packages/angular/README.md` — Angular realization
@@ -203,25 +214,104 @@ of the same model.
 
 ## Transaction failure guidance
 
-The guide below links to the active v15 candidate branch because `main` tracks
-v16. The absolute repository URL also works independently of the hosted
-`llms.txt` path; the demo does not serve this guide at `/docs/guides/`. The
-candidate documentation and release publication are pending; this branch link
-is not evidence that 15.3.1 has shipped.
+The failure behavior in this section describes published SignalTree 15.3.1.
+The release-tag link below is fixed to 15.3.1 to preserve that historical
+comparison; it is not a list of defects in 15.4.0. Check versioned changes against
+the installed version; source changes do not update an existing tarball.
 
-Read [Transaction failures and current v15 limitations](https://github.com/JBorgia/signal-tree/blob/fix/15.3.1-link-rollback-and-strand/docs/guides/transaction-failures-v15.md)
+Read [Transaction failures and limitations in 15.3.1](https://github.com/JBorgia/signal-tree/blob/v15.3.1/docs/guides/transaction-failures-v15.md)
 before generating optimistic writes or persistence. Explicit `pending.rollback()`
 refusal leaves state unchanged and the handle pending, but releases consequences
-in existing v15. In the unreleased 15.3.1 candidate, automatic refusal before a
+in existing v15. In 15.3.1, automatic refusal before a
 handle returns records surviving writes as committed, retains eligible undo
 history, releases consequences, and still throws. Successful automatic rollback
 reverses recorded writes. Error does not guarantee undo: never blindly retry the
-whole operation or use `undo()`/`jumpTo()` for request reconciliation. Removing a
-pending-created row after a confirmed edit does not necessarily clear its
-rollback dependency. Recoverable pending refusal is a v16 target, not v15 API.
-
-Candidate containment covers deferred write subscribers and transaction turn
+whole operation or use `undo()`/`jumpTo()` for request reconciliation. Since
+15.4.2, a pending-created or pending-rekeyed row removed by settled later work
+no longer blocks rollback; a pending-created row confirmed work edited and kept
+still refuses, so removal is not a general recovery strategy. After a rejection,
+`undo()` of a later write can restore the rejected transaction's speculative
+value. Recoverable pending refusal is a v16 target, not v15 API.
+
+15.3.1 containment covers deferred write subscribers and transaction turn
 listeners, not all framework effects. Vue watcher failures differ between
 development and production; an enclosing Solid `batch()` can defer errors until
-after a handle returns. The guide lists the remaining Link, branch-key,
-coalesce, pending undo, ordering, notification, and retention failures.
+after a handle returns. The guide lists the Link, branch-key, coalesce, pending undo, ordering,
+notification, and retention failures documented for 15.3.1.
+
+
+## Collection identity and independent store instances
+
+Declare the store structure and enhancers at construction. `entityMap()` supports
+dynamic entity membership; it is not an API for installing new composite slices
+with nested marker/enhancer lifecycles. Component/dialog-owned trees are valid:
+create one per independent editing session, and call `destroy()` at its owner’s
+teardown. A repeated entity ID is not an editing-session ID.
+
+`setAll()` is replacement by key. Repeated incoming keys collapse to the last
+value for that key, not distinct rows. Use a required stable ID where available;
+validate missing IDs at ingress rather than assigning a shared fallback. Numeric
+and string keys remain distinct. Do not depend on a development warning to reject
+invalid input. Version 15.3.1 does not warn for non-null duplicate incoming keys.
+
+Version 15.4.0 checks `setAll()` staging after user callbacks.
+If an interceptor or ID selector changes collection membership, keys or order,
+the outer replacement refuses before applying its staged writes. The callback's
+already-completed writes remain. Field-only callback writes do not trigger this
+structural refusal. Prefer interceptors that validate or transform input instead
+of changing the same collection's topology.
+
+In published 15.3.1, calling Link `settled()` immediately after a write can return
+before the newly queued send finishes. Version 15.4.0 repairs this same-turn race:
+`settled()` waits for the send queued by the preceding write. It is still not proof
+of backend durability, and one generic delay is not a universal synchronization
+barrier. The repair does not change the published 15.3.1 artifact.
+
+## Choosing ownership for editors and devices
+
+See `docs/guides/owned-sessions.md` and the demo `/owned-sessions`. Keep shared
+entities in one owned tree. Give each independent editor a unique session ID and
+a local draft (native form state or a separate tree); do not key drafts only by
+entity ID. Validate against the current application revision and entity lifetime
+before applying. Refuse stale saves while keeping the draft, and never silently
+retarget it to a replacement record. These are application policies, not kernel
+MVCC or remote concurrency protection. A backend must enforce its own version
+check. The demo's Apply locally does not acknowledge a server write.
+
+Each connection owns its subscription and tree. Register cleanup and guard late
+callbacks. Destroy that session when closed and all remaining sessions at owner
+teardown. Keep resources out of serializable rows. Combine display with computed
+reads over a registry, not copied state, root grafting or Link mirroring.
+
+Do not invent dynamic slice APIs, draft/fork primitives, or cross-tree settlement.
+Use one framework import root. Angular and Solid write `leaf.set(value)`, Vue
+writes `leaf.value = value`, and React/neutral write `leaf(value)`. The demo is
+Angular-specific evidence, not a cross-framework lifecycle proof.
+
+## Runtime observation (15.4.0)
+
+Tooling can use `transactionLifecycleReader`, `restorationReader`,
+`entityMembershipReader`, and `linkStateReader` from
+`@signal-tree/kernel/internals`. Each reader exposes a current `snapshot()` and
+`subscribe(listener)` for subsequent events. `stateLocationReader(tree).locate()`
+maps an effect's or write's position, entity lifetime and `fieldSegments` to its
+current structured location, or `undefined` when no longer reachable. Missing capability is not empty
+history. These readers do not install enhancers or retain terminal history.
+
+Use actual tree + collection + entity lifetime identity and typed keys; displayed
+paths are labels and must never be split into addressing segments. Confirmation
+means local settlement, never server acceptance. Link queued jobs are reconciliation
+work, not a FIFO of application values. A tool recording these events owns its
+bounded retention and must show interruptions, omissions and unsupported sources.
+Unsubscribe on view teardown and destroy bounded-lifetime trees. See
+[Runtime observation in 15.4.0](https://github.com/JBorgia/signal-tree/blob/v15.4.0/docs/guides/runtime-observation.md) for contracts and examples.
+
+## Observer failures during undo and rollback (15.4.2)
+
+A reactive observer can throw after undo, redo or transaction rollback has
+already applied. SignalTree completes the operation's bookkeeping and rethrows
+the original value; a throw alone does not establish that state was unchanged.
+Reusing that error in a later failure before application does not make the later
+operation successful. Check current state and settlement/history status when
+handling failures. This does not provide atomic recovery for arbitrary user
+callbacks that partially mutate state before throwing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signal-tree/angular",
-  "version": "15.3.1",
+  "version": "15.4.2",
   "description": "Angular realization for SignalTree.",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,7 +25,7 @@
     "llms.txt"
   ],
   "dependencies": {
-    "@signal-tree/kernel": "15.3.1"
+    "@signal-tree/kernel": "15.4.2"
   },
   "peerDependencies": {
     "@angular/core": "^20.0.0 || ^21.0.0 || ^22.0.0",