@genrojs/bag 0.10.3 → 0.11.1

package/README.md

@@ -1,5 +1,9 @@
 # genro-bag-js
 
+Current release: **0.11.1**. Fixes deletion origin propagation in `popNode`, `pop` and `delItem`.
+
+> **0.11.0 — breaking API:** read the [ingestion and scheduling migration note](docs/migration-ingestion.md) before upgrading dependent projects.
+
 TypeScript/JavaScript port of [genro-bag](https://github.com/nicofirst1/genro-bag) - hierarchical data container with XML serialization, Builder pattern, and Compiler system.
 
 ## Status

package/docs/migration-ingestion.md

@@ -0,0 +1,218 @@
+# Python 0.28.0 / JavaScript 0.11.0: explicit ingestion and no internal scheduling (breaking API)
+
+This release changes Python and JavaScript together. Downstream projects must
+review constructors, population calls, JSON readers, persisted Bag payloads and
+scheduled resolver/subscription usage before upgrading. Related: [genro-bag #69](https://github.com/genro-org/genro-bag/issues/69).
+
+## Constructor and replacement
+
+```python
+bag = Bag(source, recursive=True)
+bag.fill_from(source, recursive=True)  # replaces content; returns bag
+```
+
+```javascript
+const bag = new Bag(source, {recursive: true});
+bag.fillFrom(source, {recursive: true}); // replaces content; returns bag
+```
+
+The root must be a dictionary/plain JS object, list/array, or `None`/`null`.
+Omitting the source creates an empty Bag; omitting it in `fill_from`/`fillFrom`
+clears the existing Bag. JS also treats `undefined` as an omitted source.
+A Bag, tuple, scalar, serialized string, bytes, path, open file or URL is not a
+valid constructor/population source. Unsupported inputs, including `0`, `False`
+and `""`, raise an explicit error. Use `bag.deepcopy()` to copy a Bag.
+
+With the default `recursive=True`, every nested dictionary/list is converted to
+a fresh Bag. With `recursive=False`, only the root is converted: nested
+containers remain the original shared objects. Other leaves are always shared,
+including dates, Decimal values, binary buffers, class instances and existing
+Bag values. Existing Bags keep their contents; their internal lists are not
+reinterpreted. This is conversion, not a general deep copy. The existing
+`deepcopy()` method copies Bag structure and resolvers; it does not promise to
+clone every arbitrary leaf object.
+
+Python uses `dict` and `list` (including subclasses); tuples are leaves. JS uses
+arrays and objects whose prototype is `Object.prototype` or `null`. Other class
+instances are leaves. No custom-type registry is consulted during conversion.
+Normal resolver objects retain Bag's existing resolver attachment semantics.
+
+```python
+source = {"items": [{"name": "Ada"}]}
+Bag(source)["items.r_00.name"]                  # "Ada"
+Bag(source, recursive=False)["items"] is source["items"]  # True
+```
+
+Repeated references on different branches produce separate converted Bags.
+Cycles in dictionaries/lists raise an error identifying the conversion path
+when recursion is enabled. Shallow ingestion does not traverse nested cycles.
+Preparation failures in `fill_from`/`fillFrom` leave the old content intact;
+successful attached replacement retains the existing single update event.
+Listener failures after the replacement commits are not rolled back.
+
+## Literal labels and list order
+
+Dictionary keys must be strings and are inserted literally. `"a.b"`, `"?attr"`,
+`"#0"` and the empty string are labels, not path expressions. Existing path-based
+accessors still have their usual syntax: use node iteration or positional access
+to inspect labels that contain path/query syntax. Assign paths explicitly with
+`set_item`/`setItem` when you intend to create branches.
+
+List labels start at zero and use `r_` plus a zero-padded index. Width is
+`len(str(number_of_elements)) + 1`, calculated separately for each list:
+
+| List length | Labels |
+| --- | --- |
+| 5 | `r_00` … `r_04` |
+| 25 | `r_000` … `r_024` |
+| 150 | `r_0000` … `r_0149` |
+
+This preserves initial order under lexicographic sorting. Labels are not
+renumbered when a Bag is edited later. Converting a different-sized list may
+choose another width. Empty dictionaries and lists both become empty Bags.
+Lists of tuples/arrays are data, never implicit node descriptions.
+
+## One reader for JSON and TYTX
+
+```python
+Bag.from_tytx(text, recursive=True, sign_key=None)
+Bag.from_tytx(binary, transport="msgpack", recursive=False)
+```
+
+```javascript
+Bag.fromTytx(text, {recursive: true});
+Bag.fromTytx(binary, 'msgpack', {recursive: false});
+```
+
+Ordinary JSON and generic TYTX dictionaries/lists use the constructor's
+conversion rules. Typed values encoded by TYTX are restored before conversion.
+Ordinary JSON cannot restore dates or decimals that were reduced to ordinary
+strings by its producer. Scalar roots are rejected, including JSON `null`.
+
+A serialized Bag is explicitly identified by its type marker (`::X` for Bag).
+It is reconstructed with its labels, attributes, tags and resolvers; `recursive`
+does not reinterpret its stored list/dictionary values. The Python reader
+continues to verify resolver signatures when `sign_key` is supplied, including
+registered Bag payloads decoded through TYTX. Signed resolver tokens remain
+opaque in JS and can return unchanged to Python.
+
+`from_json` / `fromJson` is deprecated and now delegates to the new reader.
+Python emits `DeprecationWarning`; JS warns once per module instance. The alias
+accepts serialized input, not native objects. `list_joiner` / `listJoiner` is
+removed from this API. Normal fields such as `label`, `value`, `attr`, `resolver`
+and `rows` have no special meaning in generic input.
+
+## Serialized Bag format
+
+`bag.to_tytx()` / `bag.toTytx()` now emits the outer Bag marker exactly once.
+Generic `genro_tytx.to_tytx(bag)` / `toTytx(bag)` uses separate registry payload
+hooks and produces the same type identity. MessagePack uses TYTX custom-type
+extension 4, carrying the Bag suffix and its JSON TYTX payload.
+
+Within Bag rows, parent paths are arrays of literal label segments; compact
+path dictionaries also contain segment arrays. This distinguishes a label
+`"a.b"` from two labels `"a"`, `"b"`. The marked reader still accepts the old
+string parent paths inside an explicitly marked payload.
+
+Old **unmarked** `{rows: ...}` payloads are now generic application dictionaries.
+For a known old JSON Bag file, migrate offline by adding its `::X` marker; never
+infer that an arbitrary input is a Bag from a `rows` key. For old MessagePack Bag
+files, read with the previous release and write the new format with an explicit
+migration tool. Keep payload provenance and resolver-signature requirements.
+
+Existing custom Bag subtype registrations must register the payload hooks with
+TYTX's `register_type` / `registerType`, not register the public marked methods:
+
+```python
+register_type(MyBag, MyBag.__tytx_suffix__,
+              lambda bag: bag._to_tytx_payload(), MyBag._from_tytx_payload)
+```
+
+```javascript
+registerType(MyBag, MyBag.tytxSuffix,
+    bag => bag._toTytxPayload(), payload => MyBag._fromTytxPayload(payload));
+```
+
+`to_json` / `toJson` still exports the historical node-description format.
+It is **not** the inverse of the deprecated reader anymore. Use the TYTX pair
+for a Bag round trip. The Python Genropy compatibility adapter retains the
+historical node-description decoder and its signature checks.
+
+## Call-site migration
+
+| Old use | New use |
+| --- | --- |
+| `Bag(other_bag)` | `other_bag.deepcopy()` |
+| `Bag(text)` / `fill_from(text)` | `Bag.from_tytx(text)` or `Bag.from_xml(text)` |
+| `Bag(path)` / `fill_from(path)` | `Bag.from_file(path)` in Python |
+| Native dict/list passed to `from_json` / `fromJson` | Constructor |
+| Array kept as a value by the old constructor | Explicit `recursive=False`, or assign using `set_item` / `setItem` |
+| `to_json` → `from_json` Bag round trip | `to_tytx` → `from_tytx` |
+| Implicit node descriptions in lists | Explicit `set_item` / `setItem` calls |
+| Old numeric or field-prefixed list paths | New padded `r_…` labels |
+
+No `from_data`/`fromData` or `from_nodes`/`fromNodes` is introduced. Compression
+and whole-document authentication are a separate TYTX proposal (#59).
+
+## No internal scheduling
+
+Bag and its resolvers no longer schedule background work. This applies in both
+Python and JavaScript:
+
+- `subscribe` and `unsubscribe` reject `timer` and `interval` options. The `tmr`
+  event and its propagation have been removed.
+- Resolver construction rejects `interval` and `reactive`, including
+  `interval=None` / `null` and `reactive=False` / `false`. Remove obsolete
+  defaults from custom resolver classes and previously serialized descriptors.
+  Reissue signed descriptors on the server; do not edit signed client tokens.
+- `reset()` takes no arguments. `reset(refresh=True)` and JS
+  `reset({refresh: true})` raise `TypeError` instead of scheduling a reload.
+- Attaching, detaching, expiring or invalidating a resolver never loads it.
+  Attribute changes are used on the next explicit read. A read updates the
+  cache silently; it does not emit a value-change event.
+- Mutation subscriptions remain synchronous. Python keeps the synchronous resolver contract published in 0.23.0; JS also
+  accepts explicit asynchronous reads. Passive TTL caches, infinite caches and
+  explicit invalidation remain.
+  Retry delays belong to a requested load; they do
+  not start a background polling task.
+
+The application owns polling, cancellation, error handling and publication.
+For example, an application scheduler can call this function:
+
+```python
+def poll_once(resolver, output_bag):
+    resolver.reset()
+    value = resolver()
+    output_bag.set_item('result', value)  # Explicit mutation notifies subscribers
+```
+
+```javascript
+async function pollOnce(resolver, outputBag) {
+    resolver.reset();
+    const value = await resolver.resolve();
+    outputBag.setItem('result', value);
+}
+```
+
+Use a separate output node for published results. Explicitly writing a resolved
+value can replace an existing resolver attached to that destination node.
+
+In JS, node attributes now override resolver defaults on the next read, matching
+Python. Explicit call parameters still take precedence. Cache sentinels remain aligned with the published versions: both Python and JS
+use a negative TTL for infinite caching and reject boolean cache durations.
+Python's synchronous parameter preparation, readonly cache semantics, fired
+events and TYTX `__cls` subtype metadata from releases through 0.27.0 are preserved.
+
+Python retains `replace(Bag)` and explicit legacy codecs (`legacy_mode=True`).
+Its deprecated camelCase `fillFrom` remains a compatibility source loader;
+the modern `fill_from` accepts native dictionaries/lists only. Old constructor
+keyword items must become a dictionary: `Bag(name="Ada")` becomes
+`Bag({"name": "Ada"})`. Node tuples must be inserted explicitly with `set_item`;
+use the GenroPy adapter when the historical polymorphic constructor is required.
+
+
+## Validation and dependency note
+
+Both implementations use TYTX 0.16.2. Python requires Toolbox >=0.18.0; obsolete
+timer imports have been removed. Validation runs against Toolbox 0.18.0 without
+falling back to 0.14.

package/docs/python-alignment.md

@@ -154,3 +154,15 @@ Zero, false and empty strings are preserved in either mode. `Bag.setItem`
 forwards its existing null-removal option when constructing a new node as well
 as when updating one. This is an optional argument and a propagation bug fix,
 not a new default policy. See `constructor-null-attributes.test.js`.
+
+
+## Passive resolvers and application scheduling
+
+Bag does not own a scheduler in either language. Resolver `interval` and
+`reactive` options and subscription `timer` / `interval` options raise TypeError.
+`reset()` only invalidates the cache, with no refresh argument. Attachment,
+attribute changes and TTL expiry do not start background loads. Node attributes
+override resolver defaults on the next read; explicit call parameters have the
+highest priority. Applications schedule polling and publish results with
+`setItem` when observers need a mutation event. See the
+[migration note](migration-ingestion.md#no-internal-scheduling).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genrojs/bag",
-  "version": "0.10.3",
+  "version": "0.11.1",
   "description": "JavaScript port of genro-bag - hierarchical data container",
   "type": "module",
   "main": "./src/index.js",
@@ -18,7 +18,8 @@
     "README.md",
     "LICENSE",
     "NOTICE",
-    "docs/python-alignment.md"
+    "docs/python-alignment.md",
+    "docs/migration-ingestion.md"
   ],
   "scripts": {
     "test": "node --test tests/*.test.js",
@@ -41,7 +42,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@genrojs/tytx": "^0.16.1",
+    "@genrojs/tytx": "^0.16.2",
     "@msgpack/msgpack": "^3.1.3",
     "@xmldom/xmldom": "^0.9.12",
     "big.js": "^7.0.1"

package/src/bag.js

@@ -2,7 +2,8 @@
 
 import { BagNodeContainer } from './bag-node-container.js';
 import { BagNode } from './bag-node.js';
-import { toTytx as tytxEncode, fromTytx as tytxDecode, registerClass, getRegisteredType, getSubtypeDict, setSubtypeDict } from '@genrojs/tytx';
+import { toTytx as tytxEncode, fromTytx as tytxDecode, registerType, getRegisteredType, getSubtypeDict, setSubtypeDict } from '@genrojs/tytx';
+import { encode as msgpackEncode, ExtData } from '@msgpack/msgpack';
 import { DOMParser as XmlDOMParser } from '@xmldom/xmldom';
 import { BagCbResolver, BagResolver } from './resolver.js';
 import { BagSerializationError, encodeResolver, decodeResolver, encodeAttrs, decodeAttrs } from './resolver-wire.js';
@@ -10,9 +11,9 @@ import { CLS_ATTRIBUTE, getClsMarker, getInheritedClass, getSubtypeClass } from
 
 // Resolver caches are not structural branches on the wire: the descriptor
 // owns that node, and serializing cached descendants would orphan them.
-function* serializationNodes(bag, prefix = '') {
+function* serializationNodes(bag, prefix = []) {
     for (const node of bag) {
-        const path = prefix ? `${prefix}.${node.label}` : node.label;
+        const path = [...prefix, node.label];
         yield [path, node];
         const value = node.getValue(true);
         if (!node.resolver && value instanceof Bag) yield* serializationNodes(value, path);
@@ -35,6 +36,28 @@ function xmlDateText(value) {
     return timestamp;
 }
 
+function isDictionary(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+function wireValue(value) {
+    if (typeof value === 'string') return value.includes('::') ? `${value}::T` : value;
+    if (Array.isArray(value)) return value.map(wireValue);
+    if (isDictionary(value)) return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, wireValue(v)]));
+    return value;
+}
+
+function ingestionOptions(options) {
+    if (!isDictionary(options)) throw new TypeError('Bag options must be an object');
+    const { recursive = true } = options;
+    if (typeof recursive !== 'boolean') throw new TypeError('recursive must be a boolean');
+    return recursive;
+}
+
+let warnedFromJson = false;
+
 /**
  * Bag - Hierarchical data container with path-based access.
  *
@@ -48,9 +71,10 @@ export class Bag {
     /**
      * Create a new Bag.
      *
-     * @param {Object} [source=null] - Optional dict to initialize from.
+     * @param {Object|Array|null} [source=null] - In-memory data with literal string labels.
+     * @param {{recursive?: boolean}} [options={}] - Convert nested containers (default true).
      */
-    constructor(source = null) {
+    constructor(source = null, options = {}) {
         this._nodes = new BagNodeContainer();
         this._backref = false;
         this._parent = null;
@@ -61,8 +85,9 @@ export class Bag {
         this._insSubscribers = {};
         this._delSubscribers = {};
 
-        if (source) {
-            this._loadSource(source);
+        ingestionOptions(options);
+        if (source !== null && source !== undefined) {
+            this.fillFrom(source, options);
         }
     }
 
@@ -432,7 +457,7 @@ export class Bag {
         if (p >= 0) {
             const node = this._nodes.pop(p);
             if (this.backref) {
-                this._onNodeDeleted(node, p, reason);
+                this._onNodeDeleted(node, p, null, reason);
             }
             return node;
         }
@@ -717,7 +742,11 @@ export class Bag {
      * @param {Function} [options.delete] - Callback for delete events.
      * @param {Function} [options.any] - Callback for all events.
      */
-    subscribe(subscriberId, { update = null, insert = null, delete: del = null, any = null } = {}) {
+    subscribe(subscriberId, options = {}) {
+        if (Object.hasOwn(options, 'timer') || Object.hasOwn(options, 'interval')) {
+            throw new TypeError('Timer subscriptions were removed. Schedule polling in the application.');
+        }
+        const { update = null, insert = null, delete: del = null, any = null } = options;
         if (!this.backref) {
             this.setBackref();
         }
@@ -737,7 +766,11 @@ export class Bag {
      * @param {boolean} [options.delete=false] - Remove delete subscription.
      * @param {boolean} [options.any=false] - Remove all subscriptions.
      */
-    unsubscribe(subscriberId, { update = false, insert = false, delete: del = false, any = false } = {}) {
+    unsubscribe(subscriberId, options = {}) {
+        if (Object.hasOwn(options, 'timer') || Object.hasOwn(options, 'interval')) {
+            throw new TypeError('Timer subscriptions were removed. Schedule polling in the application.');
+        }
+        const { update = false, insert = false, delete: del = false, any = false } = options;
         if (update || any) {
             delete this._updSubscribers[subscriberId];
         }
@@ -1633,57 +1666,56 @@ export class Bag {
      * @param {Object} data - Object where keys become labels and values become node values.
      * @private
      */
-    _fillFromDict(data) {
-        this.clear();
-        for (const [key, value] of Object.entries(data)) {
-            if (value !== null && typeof value === 'object' && !Array.isArray(value)
-                    && !(value instanceof Bag) && !(value instanceof BagNode)) {
-                this.setItem(key, this.createChildBag()._loadSource(value));
-            } else {
-                this.setItem(key, value);
-            }
-        }
+    _appendLiteral(label, value, attr = null, resolver = null, nodeTag = null) {
+        if (typeof label !== 'string') throw new TypeError('Bag labels must be strings');
+        const node = new this.nodeClass(this, label, null, attr, resolver, nodeTag, null, false);
+        if (value instanceof BagResolver) node.resolver = value;
+        else node._value = value;
+        this._nodes._dict[label] = node;
+        this._nodes._list.push(node);
+        return node;
     }
 
-    /**
-     * Fill this Bag from a source (another Bag or plain object).
-     *
-     * Prepares replacement contents before changing this Bag:
-     * - If source is null/undefined: no-op
-     * - If source is a Bag: copies all nodes (deep copy for nested Bags)
-     * - If source is a plain object: keys become labels, values become node values.
-     *   Nested objects are recursively converted to Bags.
-     *
-     * Preparation errors leave this Bag unchanged. Attached Bags emit one
-     * upd_value event after replacement, carrying the previous content.
-     * Listener exceptions propagate after the replacement has committed.
-     *
-     * @param {Bag|Object|null} source - Source to fill from.
-     * @returns {Bag} This Bag (for chaining).
-     *
-     * @example
-     * const bag = new Bag();
-     * bag.replace(new Bag({ a: 1, b: { c: 2 } }));
-     * // bag has 'a' = 1, 'b' = Bag with 'c' = 2
-     *
-     * const other = new Bag();
-     * other.setItem('x', 10);
-     * bag.replace(other);
-     * // bag now has only 'x' = 10
-     */
-    _loadSource(source) {
-        if (source == null) return this;
-        const prepared = this.createChildBag();
-        if (source instanceof Bag) {
-            prepared._fillFromBag(source);
-        } else if (typeof source === 'object' && !Array.isArray(source)) {
-            prepared._fillFromDict(source);
-        } else {
-            return this;
+    /** Replace in-memory data atomically. None/null clears; leaves stay shared. */
+    fillFrom(source = null, options = {}) {
+        const recursive = ingestionOptions(options);
+        if (source != null && !isDictionary(source) && !Array.isArray(source)) {
+            throw new TypeError('Bag source must be a dictionary, array or null');
         }
+        const prepared = this.createChildBag();
+        const active = new Set();
+        const populate = (bag, data, path) => {
+            if (active.has(data)) throw new TypeError(`Cyclic Bag source at ${path}`);
+            active.add(data);
+            try {
+                const width = Array.isArray(data) ? String(data.length).length + 1 : 0;
+                const entries = Array.isArray(data)
+                    ? Array.from(data, (value, i) => [`r_${String(i).padStart(width, '0')}`, value])
+                    : Object.entries(data);
+                if (!Array.isArray(data) && Object.getOwnPropertySymbols(data)
+                    .some(key => Object.prototype.propertyIsEnumerable.call(data, key))) {
+                    throw new TypeError(`Bag labels must be strings at ${path}`);
+                }
+                for (const [label, item] of entries) {
+                    let value = item;
+                    if (recursive && (isDictionary(value) || Array.isArray(value))) {
+                        value = this.createChildBag();
+                        populate(value, item, `${path}[${JSON.stringify(label)}]`);
+                    }
+                    bag._appendLiteral(label, value);
+                }
+            } finally {
+                active.delete(data);
+            }
+        };
+        if (source != null) populate(prepared, source, '$');
         return this._replacePrepared(prepared);
     }
 
+    _loadSource(source, options = {}) {
+        return this.fillFrom(source, options);
+    }
+
     /** Replace all contents from a Bag, preserving identity. Returns this. */
     replace(other) {
         if (!(other instanceof Bag)) throw new TypeError('Bag.replace expects a Bag');
@@ -1787,11 +1819,12 @@ export class Bag {
         let codeCounter = 0;
         // Class of each branch by path: a node's parent class decides whether
         // its branch needs __cls (parentBag is null when the backref is off).
-        const pathToClass = new Map([['', this.constructor]]);
+        const pathToClass = new Map([['[]', this.constructor]]);
 
         for (const [path, node] of serializationNodes(this)) {
-            const lastDot = path.lastIndexOf('.');
-            const parentPath = lastDot >= 0 ? path.slice(0, lastDot) : '';
+            const parentPath = path.slice(0, -1);
+            const pathKey = JSON.stringify(path);
+            const parentKey = JSON.stringify(parentPath);
 
             const nodeValue = node.getValue(true);
 
@@ -1803,29 +1836,29 @@ export class Bag {
             } else if (nodeValue instanceof Bag) {
                 const cls = nodeValue.constructor;
                 const suffix = cls.tytxSuffix;
-                pathToClass.set(path, cls);
-                branchCls = getClsMarker(cls, getInheritedClass(pathToClass.get(parentPath), suffix));
+                pathToClass.set(pathKey, cls);
+                branchCls = getClsMarker(cls, getInheritedClass(pathToClass.get(parentKey), suffix));
                 value = `::${suffix}`;
             } else if (nodeValue === null) {
                 value = '::NN';
             } else {
-                value = nodeValue;
+                value = wireValue(nodeValue);
             }
 
             if (node.attr && Object.hasOwn(node.attr, CLS_ATTRIBUTE)) {
                 throw new BagSerializationError(
                     `node '${path}': the attribute '${CLS_ATTRIBUTE}' is reserved for the Bag class name`);
             }
-            const attr = encodeAttrs(node.attr);
+            const attr = encodeAttrs(wireValue(node.attr));
             if (branchCls !== null) attr[CLS_ATTRIBUTE] = branchCls;
             const tag = node.nodeTag;
 
             if (compact) {
-                const parentRef = parentPath ? pathToCode[parentPath] : null;
+                const parentRef = parentPath.length ? pathToCode[parentKey] : null;
                 yield [parentRef, node.label, tag, value, attr];
 
                 if (nodeValue instanceof Bag) {
-                    pathToCode[path] = codeCounter;
+                    pathToCode[pathKey] = codeCounter;
                     pathRegistry[codeCounter] = path;
                     codeCounter++;
                 }
@@ -1847,6 +1880,16 @@ export class Bag {
      * @returns {string|Uint8Array} Serialized data.
      */
     toTytx(transport = 'json', compact = false) {
+        const payload = this._toTytxPayload(compact);
+        const suffix = this.constructor.tytxSuffix;
+        if (transport === 'json') return `${payload}::${suffix}`;
+        if (transport === 'msgpack') {
+            return msgpackEncode(new ExtData(4, new TextEncoder().encode(`${suffix}:${payload}`)));
+        }
+        throw new TypeError(`Unsupported transport: ${transport}`);
+    }
+
+    _toTytxPayload(compact = false) {
         let data;
 
         if (compact) {
@@ -1861,8 +1904,10 @@ export class Bag {
         const rootCls = getClsMarker(rootClass, getInheritedClass(null, rootClass.tytxSuffix));
         if (rootCls !== null) data[CLS_ATTRIBUTE] = rootCls;
 
-        const tytxTransport = transport === 'json' ? null : transport;
-        return tytxEncode(data, tytxTransport);
+        data.rows = data.rows.map(([parent, label, tag, value, attr]) =>
+            [wireValue(parent), wireValue(label), wireValue(tag), value, attr]);
+        if (data.paths) data.paths = wireValue(data.paths);
+        return tytxEncode(data);
     }
 
     /**
@@ -1872,13 +1917,31 @@ export class Bag {
      * @param {string} [transport='json'] - Input format: 'json' or 'msgpack'.
      * @returns {Bag} Reconstructed Bag.
      */
-    static fromTytx(data, transport = 'json') {
+    static fromTytx(data, transport = 'json', options = {}) {
+        if (isDictionary(transport)) { options = transport; transport = 'json'; }
+        ingestionOptions(options);
+        if (typeof data !== 'string' && !(data instanceof Uint8Array)) {
+            throw new TypeError('fromTytx requires serialized text or bytes');
+        }
+        if (transport !== 'json' && transport !== 'msgpack') {
+            throw new TypeError(`Unsupported transport: ${transport}`);
+        }
+        if (transport === 'json' && data instanceof Uint8Array) data = new TextDecoder().decode(data);
+        const decoded = tytxDecode(data, transport === 'json' ? null : transport);
+        if (decoded instanceof Bag) return decoded;
+        if (!isDictionary(decoded) && !Array.isArray(decoded)) {
+            throw new TypeError('fromTytx requires a dictionary, array or typed Bag root');
+        }
+        return new this(decoded, options);
+    }
+
+    static _fromTytxPayload(data) {
         // The payload alone decides the class of the root: without __cls it is
         // the class registered for the suffix (Bag for "X"), whatever this is.
         const suffix = this.tytxSuffix;
         // The registry passes an empty payload for a structural branch marker.
         if (data === '') return new (getInheritedClass(null, suffix))();
-        const parsed = tytxDecode(data, transport === 'json' ? null : transport);
+        const parsed = tytxDecode(data);
         if (!parsed || !Array.isArray(parsed.rows)) {
             throw new BagSerializationError('Invalid TYTX Bag: expected rows');
         }
@@ -1888,7 +1951,7 @@ export class Bag {
             ? getSubtypeClass(suffix, parsed[CLS_ATTRIBUTE])
             : getInheritedClass(null, suffix);
         const bag = new rootClass();
-        const pathToBag = new Map([['', bag]]);
+        const pathToBag = new Map([['[]', bag]]);
 
         for (const row of parsed.rows) {
             if (!Array.isArray(row) || row.length !== 5) {
@@ -1902,18 +1965,15 @@ export class Bag {
                 }
                 parentPath = parentRef === null ? '' : paths[parentRef];
             }
-            if (!pathToBag.has(parentPath)) {
+            if (typeof parentPath === 'string') parentPath = parentPath ? parentPath.split('.') : [];
+            if (!Array.isArray(parentPath)) throw new BagSerializationError('Invalid TYTX parent path');
+            const parentKey = JSON.stringify(parentPath);
+            if (!pathToBag.has(parentKey)) {
                 throw new BagSerializationError(`Missing or undecodable TYTX parent branch: ${parentPath}`);
             }
-            const parentBag = pathToBag.get(parentPath);
-            const fullPath = parentPath ? `${parentPath}.${label}` : label;
+            const parentBag = pathToBag.get(parentKey);
+            const fullPath = JSON.stringify([...parentPath, label]);
             let value = rawValue;
-            // MessagePack does not rescan text. Only Bag-owned empty markers
-            // are structural: arbitrary scalar decoders must never run here.
-            if (transport === 'msgpack' && typeof value === 'string' && value.startsWith('::')) {
-                const cls = getRegisteredType(value.slice(2));
-                if (cls === Bag || cls?.prototype instanceof Bag) value = tytxDecode(value);
-            }
             const resolver = decodeResolver(value);
             const attr = decodeAttrs(rawAttr);
             const branchCls = Object.hasOwn(attr, CLS_ATTRIBUTE) ? attr[CLS_ATTRIBUTE] : null;
@@ -1929,10 +1989,8 @@ export class Bag {
             } else if (branchCls !== null) {
                 throw new BagSerializationError(
                     `node '${fullPath}': the attribute '${CLS_ATTRIBUTE}' is reserved for the Bag class name of a branch`);
-            } else if (value === '::NN') {
-                value = null;
             }
-            const node = parentBag.setItem(label, resolver || value, attr);
+            const node = parentBag._appendLiteral(label, resolver ? null : value, attr, resolver);
             node.nodeTag = tag ?? null;
         }
         return bag;
@@ -2198,7 +2256,7 @@ export class Bag {
         const text = await response.text();
 
         if (contentType.includes('json')) {
-            return Bag.fromJson(text);
+            return Bag.fromTytx(text);
         }
         if (contentType.includes('xml')) {
             return Bag.fromXml(text);
@@ -2209,7 +2267,7 @@ export class Bag {
             return Bag.fromXml(text);
         }
         if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
-            return Bag.fromJson(text);
+            return Bag.fromTytx(text);
         }
         throw new BagException(`Unsupported content-type: ${contentType}`);
     }
@@ -2262,79 +2320,17 @@ export class Bag {
     }
 
     /**
-     * Deserialize JSON to Bag.
-     *
-     * Accepts JSON string, dict, or list. Recursively converts nested
-     * structures to Bag hierarchy.
-     *
-     * @param {string|Object|Array} source - JSON string, dict or list to parse.
-     * @param {string} [listJoiner=null] - If provided, join string arrays with this separator.
-     * @returns {Bag} Deserialized Bag.
+     * Deprecated alias of fromTytx: serialized text only, no node heuristics.
+     * @deprecated Use fromTytx, or new Bag(data) for native dictionaries/arrays.
+     * @param {string|Uint8Array} source
+     * @param {{recursive?: boolean}} [options={}]
      */
-    static fromJson(source, listJoiner = null) {
-        if (typeof source === 'string') {
-            source = tytxDecode(source);
+    static fromJson(source, options = {}) {
+        if (!warnedFromJson) {
+            console.warn('Bag.fromJson is deprecated; use Bag.fromTytx');
+            warnedFromJson = true;
         }
-
-        if (!Array.isArray(source) && typeof source !== 'object') {
-            source = { value: source };
-        }
-
-        return Bag._fromJsonRecursive(source, listJoiner);
-    }
-
-    /**
-     * Recursively convert JSON data to Bag (internal).
-     * @private
-     */
-    static _fromJsonRecursive(data, listJoiner = null) {
-        if (data instanceof Bag) return data;
-        if (Array.isArray(data)) {
-            // listJoiner: join string arrays into a single string
-            if (listJoiner !== null && data.every(item => typeof item === 'string')) {
-                return data.join(listJoiner);
-            }
-
-            if (data.length === 0) {
-                return new Bag();
-            }
-
-            // Check if list items have 'label' key (Bag node format)
-            if (typeof data[0] === 'object' && data[0] !== null && 'label' in data[0]) {
-                const result = new Bag();
-                for (const item of data) {
-                    const label = item.label;
-                    const value = Bag._fromJsonRecursive(item.value, listJoiner);
-                    const attr = decodeAttrs(item.attr);
-                    const node = result.setItem(label, value, attr);
-                    node.nodeTag = item.tag ?? null;
-                    const resolver = decodeResolver(item.resolver);
-                    if (resolver) node.resolver = resolver;
-                }
-                return result;
-            }
-
-            // Generic list -> Bag with r_N keys
-            const result = new Bag();
-            for (let n = 0; n < data.length; n++) {
-                result.setItem(`r_${n}`, Bag._fromJsonRecursive(data[n], listJoiner));
-            }
-            return result;
-        }
-
-        if (typeof data === 'object' && data !== null) {
-            if (Object.keys(data).length === 0) {
-                return new Bag();
-            }
-            const result = new Bag();
-            for (const [k, v] of Object.entries(data)) {
-                result.setItem(k, Bag._fromJsonRecursive(v, listJoiner));
-            }
-            return result;
-        }
-
-        // Scalar value
-        return data;
+        return this.fromTytx(source, 'json', options);
     }
 
     // -------------------------------------------------------------------------
@@ -2511,7 +2507,7 @@ export class BagException extends Error {
 BagResolver.registerBagClass(Bag);
 
 // Shared TYTX registry: subclasses register their own wire suffix explicitly.
-registerClass(Bag);
+registerType(Bag, 'X', bag => bag._toTytxPayload(), payload => Bag._fromTytxPayload(payload));
 // Bag is the base class of the "X" type: its name must be in the subtype
 // dictionary like every subclass that travels as "::X" with a __cls name.
 setSubtypeDict(Bag.tytxSuffix, { ...getSubtypeDict(Bag.tytxSuffix), Bag });

package/src/index.d.ts

@@ -20,7 +20,11 @@ export const RETRY_POLICIES: {
 
 /** Options shared by every resolver. */
 export interface BagResolverOptions {
-    /** Cache duration in ms. 0 disables the cache, a negative value never expires. */
+    /** Removed: schedule polling in the application. */
+    interval?: never;
+    /** Removed: invalidate and read explicitly. */
+    reactive?: never;
+    /** Cache duration in seconds. 0 disables the cache, a negative value never expires. */
     cacheTime?: number;
     /** If true, the resolved value is not stored in the node. */
     readOnly?: boolean;
@@ -85,7 +89,8 @@ export class BagSerializationError extends Error {
 export class Bag implements Iterable<BagNode> {
     /** Wire suffix of the base class in the TYTX registry. */
     static tytxSuffix: string;
-    constructor(source?: Record<string, any> | Bag | null);
+    constructor(source?: Record<string, any> | any[] | null, options?: { recursive?: boolean });
+    fillFrom(source?: Record<string, any> | any[] | null, options?: { recursive?: boolean }): this;
 
     parent: Bag | null;
     parentNode: BagNode | null;
@@ -158,12 +163,13 @@ export class Bag implements Iterable<BagNode> {
     traverse(): Generator<BagNode>;
 
     toTytx(transport?: 'json' | 'msgpack', compact?: boolean): string | Uint8Array;
-    static fromTytx(data: string | Uint8Array, transport?: 'json' | 'msgpack'): Bag;
+    static fromTytx(data: string | Uint8Array, transport?: 'json' | 'msgpack' | { recursive?: boolean }, options?: { recursive?: boolean }): Bag;
     toXml(options?: ToXmlOptions): string;
     static fromXml(source: string, options?: FromXmlOptions): Bag;
     static fromUrl(url: string, options?: FromUrlOptions): Promise<Bag>;
     toJson(typed?: boolean): string;
-    static fromJson(source: string | Record<string, any> | any[], listJoiner?: string | null): Bag;
+    /** @deprecated Use fromTytx for text and the constructor for native data. */
+    static fromJson(source: string | Uint8Array, options?: { recursive?: boolean }): Bag;
     toStringTree(isStatic?: boolean): string;
     toString(isStatic?: boolean): string;
 }
@@ -240,6 +246,7 @@ export class BagResolver {
     init(): void;
     setNode(node: BagNode | null): void;
     onSetResolver(node: BagNode): void;
+    /** Invalidate the cache; reload only on the next explicit read. No refresh option. */
     reset(): void;
     resolve(options?: { static?: boolean; [key: string]: any }): any;
     load(kwargs?: Record<string, any>): any;

package/src/resolver.js

@@ -11,6 +11,8 @@
  *   - cacheTime = 0: never cache, always resolve
  *   - cacheTime < 0: cache forever (resolve once)
  *
+ * Resolvers never schedule background loads. reset() reloads on the next read.
+ *
  * Retry Policy:
  *   - retryPolicy = null -> NO retry (default)
  *   - retryPolicy = 'network' -> use predefined RETRY_POLICIES.network
@@ -160,6 +162,11 @@ export class BagResolver {
     constructor(kwargs = {}) {
         const defaults = this.constructor.classKwargs;
         const merged = { ...defaults, ...kwargs };
+        for (const option of ['interval', 'reactive']) {
+            if (Object.hasOwn(merged, option)) {
+                throw new TypeError(`Removed resolver option: ${option}. Schedule updates in the application; use reset() and read explicitly.`);
+            }
+        }
 
         // Extract internal params
         this.cacheTime = merged.cacheTime;
@@ -282,7 +289,10 @@ export class BagResolver {
     /**
      * Reset the cache, forcing next resolve to call load().
      */
-    reset() {
+    reset(...args) {
+        if (args.length) {
+            throw new TypeError('reset() takes no arguments. It invalidates the cache for the next explicit read.');
+        }
         this._lastUpdate = null;
         this._lastEffectiveFingerprint = null;
     }
@@ -342,7 +352,7 @@ export class BagResolver {
         if (this._node && this._node.attr) {
             const internalParams = this.constructor.internalParams;
             for (const [key, value] of Object.entries(this._node.attr)) {
-                if (!internalParams.has(key) && !(key in kwargs)) {
+                if (!internalParams.has(key)) {
                     kwargs[key] = value;
                 }
             }
@@ -435,8 +445,8 @@ export class BagResolver {
             if (result.startsWith('<') && BagClass.fromXml) {
                 return BagClass.fromXml(result);
             }
-            if ((result.startsWith('{') || result.startsWith('[')) && BagClass.fromJson) {
-                return BagClass.fromJson(result);
+            if ((result.startsWith('{') || result.startsWith('[')) && BagClass.fromTytx) {
+                return BagClass.fromTytx(result);
             }
         }
         return result;