@signal-tree/vue 15.3.1 → 15.4.0

package/README.md

@@ -97,14 +97,26 @@ state used for the server output before hydration.
 
 ## 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.
 
-Candidate containment applies to deferred write subscribers and transaction
+15.3.1 containment applies to deferred write subscribers and transaction
 turn listeners, not all Vue effects. Vue rethrows watcher errors in development
 but logs them in production, so only the former can trigger automatic rollback
 at transaction closure.
+
+## 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.0 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,16 +214,15 @@ 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
@@ -220,8 +230,75 @@ whole operation or use `undo()`/`jumpTo()` for request reconciliation. Removing
 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
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signal-tree/vue",
-  "version": "15.3.1",
+  "version": "15.4.0",
   "description": "Vue observation 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.0"
   },
   "peerDependencies": {
     "tslib": "^2.0.0",