toilscript 0.1.36 → 0.1.38

package/dist/importmap.json

@@ -1,7 +1,7 @@
 {
   "imports": {
-    "toilscript": "https://cdn.jsdelivr.net/npm/toilscript@0.1.36/dist/toilscript.js",
-    "toilscript/cli": "https://cdn.jsdelivr.net/npm/toilscript@0.1.36/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

@@ -2994,8 +2994,30 @@ declare module "types:toilscript/src/parser" {
         /** Finishes parsing. */
         finish(): void;
         weaveDataMigrations(): void;
-        /** Replace `newType`'s generated `decodeInto` with a version-dispatching one. */
+        /** Enforce the migration-file convention (folder AND extension): every `@migrate`
+         *  must live in a `*.migration.ts` file under a `migrations/` directory. Keeping
+         *  migrations in one discoverable place is what lets the build auto-parse them and
+         *  the weave inject the cross-file imports; a stray `@migrate` elsewhere would not
+         *  be discovered (silently never run), so it is a hard error. */
+        private checkMigrationLocations;
+        /** Replace `target`'s generated `decodeInto` with a version-dispatching one: a
+         *  row at any chain-reachable old version is decoded as its shape and run forward
+         *  through every transform until it reaches `target`. */
         private weaveDecodeInto;
+        /** Record that `sym` (an old `@data` shape or a transform fn) must be imported
+         *  into the value type's source from `srcPath`. A blank or same-file source is a
+         *  no-op (the symbol is already in scope). Deduped per source via parallel arrays. */
+        private addMigrationImport;
+        /** Internal path of the source declaring the `@data` class `name`, or "" if it
+         *  isn't a known `@data` type (then there is nothing to import). */
+        private typeSourcePath;
+        /** A `"./.."`-style module specifier from importing file `fromInternal` to target
+         *  module `toInternal` (both extension-less internal paths), e.g.
+         *  `("models/User","migrations/User.migration") -> "../migrations/User.migration"`. */
+        private relativeModulePath;
+        /** Copy the fields a delta-step's old and new layouts SHARE (same name + type +
+         *  array-ness) from `prevVar` into `nextVar`. */
+        private migrationCarry;
         private checkToilDbKinds;
         /** Map every `@database` class (incl. inside namespaces) to its
          *  collection-name -> handle-family-name. */
@@ -4296,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). */
@@ -4314,17 +4356,37 @@ declare module "types:toilscript/src/dbcatalog" {
         fnName: string;
         oldVersion: number;
         delta: boolean;
+        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. */
+    export class MigrationChain {
+        oldType: string;
+        oldVersion: number;
+        steps: DataMigration[];
+    }
+    /** Every old type that reaches `target` through a chain of `@migrate` edges, with
+     *  the ordered transforms to apply. A backward breadth-first walk of the migration
+     *  graph (edges OLD -> NEW), so the SHORTEST chain wins and cycles terminate; a
+     *  direct migration is just a one-step chain. This is what lets a row written under
+     *  version 0 reach the current version 2 via `0->1` then `1->2`. */
+    export function chainsTo(target: string, migrations: DataMigration[]): MigrationChain[];
     /**
      * Build the `toildb.catalog` section bytes, or `null` if the program declares
      * no `@database`.
      */
     export function buildToilDbCatalog(program: Program): Uint8Array | null;
+    export function buildToilDbTypes(program: Program): Uint8Array | null;
 }
 declare module "types:toilscript/src/passes/pass" {
     /**