toilscript 0.1.37 → 0.1.38

package/dist/importmap.json

@@ -1,7 +1,7 @@
 {
   "imports": {
-    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.37/dist/toilscript.js",
-    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.37/dist/cli.js",
+    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.38/dist/toilscript.js",
+    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.38/dist/cli.js",
     "binaryen": "https://cdn.jsdelivr.net/npm/binaryen@130.0.0-nightly.20260609/index.js",
     "long": "https://cdn.jsdelivr.net/npm/long@5.3.2/index.js"
   }

package/dist/toilscript.generated.d.ts

@@ -4318,11 +4318,31 @@ declare module "types:toilscript/src/dbcatalog" {
      * `schema_version`: a hash over the ORDERED field layout (name, type, is_array),
      * NOT the value-type name. Adding, removing, retyping, or REORDERING a field
      * changes it - so the runtime can tell a compatible (append-only) change from a
-     * breaking one, instead of silently misreading old rows. (Flat, like toildb's
-     * `SchemaDescriptor::layout_hash`: a change to a NESTED `@data` type's own fields
-     * does not bump the parent - that lands with recursive layouts later.)
+     * breaking one, instead of silently misreading old rows.
+     *
+     * RECURSIVE into nested `@data` types: when a field's `typeName` is a KNOWN
+     * `@data` type (a key of `typeMap`) and not already on the `seen` set (cycle
+     * guard), the SAME running hash continues over that nested type's fields - so a
+     * breaking change to a NESTED type bumps the OUTER `schema_version` and can be
+     * `@migrate`d (instead of being refuse-only). This MUST stay byte-identical to
+     * toildb's `SchemaDescriptor::layout_hash` (the runtime side): the algorithm,
+     * the `seen` add/remove, and the declaration-order traversal are pinned in lock
+     * step. A FLAT type (no field whose type is in `typeMap`) hashes to the SAME
+     * value as the old flat hash, so existing pinned vectors stay green; an absent
+     * `typeMap` (undefined) is flat/back-compatible.
+     *
+     * `typeMap` MUST contain the SAME set of `@data` types as the runtime's
+     * `toildb.types` registry (collection value types + their nested types, EXCLUDING
+     * old `*.migration.ts` shapes), or the two hashes diverge: a nested field whose
+     * type is absent from the map on either side is treated as a LEAF on both sides.
      */
-    export function layoutHash(fields: FieldLayout[]): number;
+    export function layoutHash(fields: FieldLayout[], typeMap?: Map<string, FieldLayout[]> | null, seen?: Set<string> | null): number;
+    /** The recursion type map for `layoutHash`: every `@data` type the runtime's
+     *  `toildb.types` registry also contains (collection value types + their nested
+     *  types), EXCLUDING old `*.migration.ts` shapes (which the runtime registry
+     *  excludes by design). Both sides must recurse through the SAME set, so a
+     *  nested field whose type is NOT here is a leaf on both sides. */
+    export function recursionTypeMap(sources: Source[]): Map<string, FieldLayout[]>;
     /** Extract the encoded field layout of a `@data` class, in declaration order,
      *  mirroring `injectDataCodec` (skip static; `Array<T>` -> element + array flag;
      *  else scalar/string/`Uint8Array`/nested-`@data` by its type name). */
@@ -4339,10 +4359,14 @@ declare module "types:toilscript/src/dbcatalog" {
         sourceInternalPath: string;
     }
     /** Every `@migrate` function across the (non-library) sources. `layouts` maps a
-     *  `@data` class name to its field layout, for the old-version hash. A migration
-     *  whose param/return is not a single named type, or whose old type has no
-     *  layout, is skipped. */
-    export function collectMigrations(sources: Source[], layouts: Map<string, FieldLayout[]>): DataMigration[];
+     *  `@data` class name to its field layout, for the old-version hash. `typeMap`
+     *  (optional) is the recursion type map (see [`recursionTypeMap`]) so the old
+     *  version hashes RECURSIVELY through its nested `@data` fields - matching the
+     *  `schema_version` that old layout was deployed under (or the migratable old
+     *  version would never match a deployed recursive hash). Absent = flat. A
+     *  migration whose param/return is not a single named type, or whose old type
+     *  has no layout, is skipped. */
+    export function collectMigrations(sources: Source[], layouts: Map<string, FieldLayout[]>, typeMap?: Map<string, FieldLayout[]> | null): DataMigration[];
     /** A resolved chain that migrates a stored OLD value all the way to a target
      *  type: decode `oldType`, then apply `steps` in order (each `@migrate`). For a
      *  direct migration `steps` has one entry; a chain `V0 -> V1 -> V2` has two. */