toilscript 0.1.37 → 0.1.39

package/dist/cli.generated.d.ts

@@ -2877,11 +2877,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). */
@@ -2898,10 +2918,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. */
@@ -2922,6 +2946,94 @@ declare module "types:toilscript/src/dbcatalog" {
      */
     export function buildToilDbCatalog(program: Program): Uint8Array | null;
     export function buildToilDbTypes(program: Program): Uint8Array | null;
+    /** Build the `toildb.route_kinds` section bytes, or `null` when no route needs
+     *  an extra runtime DB-policy clamp. The edge already derives the default kind
+     *  from the trusted HTTP method. This section only carries the stricter source
+     *  signal that the method clamp cannot infer: mutating-method routes explicitly
+     *  declared `@query`.
+     *
+     *  Wire format (LE):
+     *    u16 format_version = 1
+     *    u16 n_routes
+     *    per route:
+     *      u8 method          (same values as runtime Methods / request envelope)
+     *      u8 function_kind   (0 = Query)
+     *      str route_pattern  (same normalized pattern emitted into __toilMatch)
+     */
+    export function buildToilDbRouteKinds(program: Program): Uint8Array | null;
+    /** Build the `toilstream.catalog` section bytes, or `null` if the program
+     *  declares no `@stream` class. Per Part 5 (LE):
+     *
+     *    u16 format_version = 1
+     *    u16 n_streams
+     *    per stream:
+     *      str  name
+     *      str  route
+     *      u8   hook_presence_bitmask   (bit0 connect..bit3 disconnect)
+     *      u8   declared_scope          (0 regional/L2, 1 continental/L3)
+     *      u8   message_mode            (0 raw, 1 @data-typed)
+     *      u32  max_frame_bytes         (0 = use plan default)
+     *      u32  ingress_ring_bytes      (0 = host chooses)
+     *      u32  message_value_data_id   (fnv1a(typeName); 0 when raw)
+     *      u32  message_schema_version  (recursive layoutHash; 0 when raw)
+     *      u16  stream_index            (0-based position in this array)
+     */
+    export function buildToilStreamCatalog(program: Program): Uint8Array | null;
+    /** Build the `toildaemon.catalog` section bytes, or `null` if the program
+     *  declares no `@daemon` class. Per Part 5 (LE):
+     *
+     *    u16 format_version = 1
+     *    u8  has_daemon
+     *    u16 n_scheduled
+     *    per task:
+     *      str name
+     *      u16 task_index
+     *      u8  schedule_kind          (0 interval, 1 cron)
+     *      u64 interval_ms
+     *      u64 cron_minute_mask       (bits 0..59)
+     *      u32 cron_hour_mask
+     *      u32 cron_dom_mask
+     *      u16 cron_month_mask
+     *      u8  cron_dow_mask
+     *      u8  overlap_policy         (0 default)
+     *      u8  catchup_policy         (0 default)
+     *      u64 gas_hint
+     *
+     *  Parses each `@scheduled(spec)` argument; fires diagnostics 9010/9011 for a
+     *  missing/non-string arg or an unparseable spec.
+     */
+    export function buildToilDaemonCatalog(program: Program): Uint8Array | null;
+    /** Build the `toil.surface` section bytes (always emitted per artifact). Per
+     *  Part 5 (LE):
+     *
+     *    u16 format_version = 1
+     *    u8  target_mode            (0 hot, 1 cold)
+     *    u8  reserved0              (0)
+     *    u32 surface_flags          (bit0 rest..bit5 render)
+     *    u16 abi_version
+     *    str build_id
+     *    u32 fingerprint
+     *    u32 data_coherence_hash
+     *    u32 pair_coherence_hash
+     *
+     *  `targetMode` "cold" -> 1; "hot" or null (legacy single artifact, treated as
+     *  hot per Part 5) -> 0. The two coherence hashes use the SAME `layoutHash` /
+     *  `recursionTypeMap` machinery as the toildb catalog, so a hot pass and a cold
+     *  pass over the same sources compute identical `data_coherence_hash` and
+     *  `pair_coherence_hash` independently (doc 02 AN-4). `build_id` is empty and
+     *  `abi_version` is 1 in this increment (the toiljs build-identity plumbing and
+     *  the export-name fingerprint component land with the codegen increment).
+     *
+     *  Returns `null` (no section) for a bare AssemblyScript module compiled in
+     *  LEGACY mode (`targetMode == null`) that declares NO Toil surface at all
+     *  (`@rest`/`@stream`/`@daemon`/`@scheduled`/`@database`/`@data`), so an ordinary
+     *  AS compile stays byte-identical (the same gating philosophy as the existing
+     *  `toildb.catalog`, which is absent without `@database`). Part 5 / doc 02 AN-2
+     *  requires the section in every TOIL artifact (including a legacy single-artifact
+     *  toil build, which always carries a toil surface); a non-toil module is not a
+     *  toil artifact. An explicit `--targetMode hot|cold` always emits the section.
+     */
+    export function buildToilSurface(program: Program, targetMode: string | null): Uint8Array | null;
 }
 declare module "types:toilscript/src/parser" {
     /**
@@ -2958,6 +3070,10 @@ declare module "types:toilscript/src/parser" {
         dependees: Map<string, Dependee>;
         /** Normalized paths whose `@rest` runtime import has already been injected. */
         restImportedSources: Set<string>;
+        /** Normalized paths whose `@stream` module-level registry + the single
+         *  `stream_dispatch` export have already been emitted (a project may declare
+         *  several `@stream` classes, but the export is emitted exactly once). */
+        streamExportedSources: Set<string>;
         /** Monotonic id handed to each `@ratelimit` route so the edge can key one
          *  shared limiter per route. Program-wide (one Parser per program), assigned
          *  deterministically in route declaration order. */
@@ -3079,6 +3195,99 @@ declare module "types:toilscript/src/parser" {
          * return; plus a module-level self-registration into the runtime `Rest` router.
          */
         private injectRestController;
+        /**
+         * Synthesize the cold-artifact daemon entry for a `@daemon` class (spec 03
+         * sections 5.2 / 5.6 / 5.7, Reconciliation Part 2 cold exports). Mirrors
+         * `injectRestController`: it scans the class methods once (same source-order
+         * walk the `toildaemon.catalog` builder uses, so `task_index` <-> dispatch
+         * index stay in lockstep), synthesizes a `__tick(task)` dispatcher onto the
+         * class, and emits the two canonical cold module-level exports:
+         *
+         *   `daemon_start(): i32`     - runs once at cold-box boot; instantiates the
+         *                               `@daemon` class, holds the single box-lifetime
+         *                               instance, runs the optional `onStart()`, and
+         *                               returns 0 (negative = Part 3 error bridge).
+         *   `scheduled_tick(task_id: i32): i64` - dispatches `instance.__tick(task_id)`
+         *                               by switching on the catalog `task_index`;
+         *                               returns 0 (negative = Part 3 error bridge).
+         *
+         * Unlike `injectRestController`, the exports are self-contained (they do NOT
+         * route through an external runtime `Daemon` registry import). The injected
+         * `register(...)` in `injectRestController` is pruned when nothing reachable
+         * references it, but a top-level EXPORT that referenced an unresolved runtime
+         * import would be a hard compile error (TS6054), so the host-called exports
+         * are synthesized as plain top-level `export function`s and keep the one
+         * box-lifetime instance in a module-level singleton (doc 03 D1 / section 2:
+         * per-domain state lives in instance fields for the box lifetime).
+         *
+         * Fires diagnostic 9012 for a `@scheduled` method with a non-empty parameter
+         * list or a non-void return type, and the 9008 warning for a `@daemon` class
+         * with zero `@scheduled` tasks (a daemon may legitimately run only `onStart`).
+         */
+        private injectDaemonHandler;
+        /**
+         * Synthesize the hot-artifact stream entry for a `@stream` class (spec 03
+         * sections 5.1 / 5.4, Reconciliation Part 2 hot exports). Mirrors
+         * `injectDaemonHandler`: it scans the class methods once (same source-order
+         * walk the `toilstream.catalog` builder + `streamHookMask` use), classifies
+         * each by lifecycle-hook kind (`@connect`/`@message`/`@close`/`@disconnect`),
+         * synthesizes a `__streamDispatch(event_kind)` dispatcher onto the class, and
+         * emits the canonical hot module-level export:
+         *
+         *   `stream_dispatch(event_kind: i32, stream_id_lo: i32, stream_id_hi: i32): i64`
+         *     - the per-connection event entry, emitted EXACTLY ONCE per module. It
+         *       reconstructs the i64 stream id from the two i32 halves, selects the
+         *       active `@stream` class's dispatch thunk from a module-level registry
+         *       (one entry per `@stream` class, in `toilstream.catalog` `stream_index`
+         *       order), switches on `event_kind` (1 connect / 2 message / 3 close /
+         *       4 disconnect, the FIXED Part 2 ABI values), and returns the hook's
+         *       packed-i64 result (0 = no output / accept; a negative value is the
+         *       Part 3 reject/error bridge, wired with the real ring/StreamOutbound
+         *       runtime in a later increment).
+         *
+         * Each `@stream` class keeps its own MODULE-SINGLETON instance (a resident
+         * per-connection box): the dispatch thunk constructs it on first use and REUSES
+         * it across every later event, so per-connection state in instance fields
+         * persists for the connection lifetime (the ResetMode::None resident box of
+         * `05`). The thunk-array + the single export mirror the spec's `Streams.register`
+         * model, but SELF-CONTAINED (no external runtime import): like
+         * `injectDaemonHandler`, a top-level export referencing an unresolved runtime
+         * import would be a hard compile error (TS6054), so the registry + the export
+         * are plain module-level code emitted once (guarded by `streamExportedSources`,
+         * exactly as `injectRestController` guards its one-per-source import).
+         *
+         * The `event_kind` ids are exactly the `toilstream.catalog` hook bitmask bits
+         * plus one (connect=1 <-> bit0, message=2 <-> bit1, close=3 <-> bit2,
+         * disconnect=4 <-> bit3, matching `streamHookMask` in `dbcatalog.ts`), so the
+         * dispatch and the catalog never schism. `event_kind = 5` (channel, F10) is a
+         * later increment: the base AST carries no `@channel` kind and the catalog mask
+         * is 4-bit, so this shim emits the four lifecycle arms only.
+         *
+         * Active-stream selection (which registry entry a connection routes to) is
+         * owned by the host/ring runtime (spec 5.1: the `Streams` singleton resolves the
+         * stream identity off the ring); this increment routes to the host-selected
+         * index, defaulting to 0, so a single-`@stream` module dispatches exactly and a
+         * multi-`@stream` module compiles to one well-formed export.
+         *
+         * Only hooks the class actually declares get a dispatch arm; an event for an
+         * absent hook falls through to `return 0` (a no-op success per the contract,
+         * never a crash). A hook that declares parameters (the typed `@message`
+         * `@data` arg, or a `StreamInbound`/`StreamPacket` view) is given a no-op arm
+         * here too: the `StreamInbound`/`StreamPacket`/`StreamOutbound` runtime + the
+         * ingress-ring read are owned by toiljs (spec 5.4) and land in a later
+         * increment, so this self-contained shim cannot synthesize those argument
+         * values yet; calling a zero-arg hook directly is the part that compiles and
+         * runs today (every gating/catalog fixture uses the zero-arg/void hook form).
+         *
+         * Fires the 9013 warning for a `@stream` class with zero lifecycle hooks (a
+         * hookless stream can never receive traffic), mirroring the daemon 9008 warning
+         * shape; gating already rejects a hook outside a `@stream`.
+         */
+        private injectStreamHandler;
+        /** True if a function signature takes no parameters and returns `void` (the
+         *  required `@scheduled` handler shape, spec 03 section 3.5). A missing or
+         *  non-`void`-named return type, or any parameter, is false. */
+        private isVoidNoArgSignature;
         /**
          * Bind a `@user` class to `AuthService.getUser()` typing. The lib declares
          * `getUser(): AuthUser | null`; here we inject a `@global` `AuthUser` that
@@ -3319,6 +3528,8 @@ declare module "types:toilscript/src/program" {
         instancesByName: Map<string, Element>;
         /** Function decorated with `@main` (toil module entry point), if any. */
         mainFunction: FunctionPrototype | null;
+        /** Class decorated with `@daemon` (cold L4 entry), if any. At most one per project. */
+        daemonClass: ClassPrototype | null;
         /** Classes wrapping basic types like `i32`. */
         wrapperClasses: Map<Type, Class>;
         /** Managed classes contained in the program, by id. */
@@ -3493,6 +3704,15 @@ declare module "types:toilscript/src/program" {
         getElementByDeclaration(declaration: DeclarationStatement): DeclaredElement | null;
         /** Initializes the program and its elements prior to compilation. */
         initialize(): void;
+        /**
+         * Enforces the project-wide rule that a compilation unit using `@stream` cannot also
+         * declare `@service` or `@remote` anywhere (spec 03 section 4.4). The host loads one
+         * `hot.wasm` whose surface is either a stream node or an RPC service node, never both,
+         * so mixing them is a deploy-time ambiguity caught fail-closed at compile time. Reported
+         * at the offending `@service`/`@remote` site. Skipped in cold mode (neither flag is
+         * admitted there anyway).
+         */
+        private enforceStreamServiceExclusion;
         /** Processes overridden members by this class in a base class. */
         private processOverrides;
         /** Processes a single overridden member by this class in a base class. */
@@ -3651,7 +3871,15 @@ declare module "types:toilscript/src/program" {
         /** Is a `@collection` field within a `@database` class. */
         Collection = 524288,
         /** Is a `@query`/`@action`/`@job`/`@derive`/`@admin` function (ToilDB kind). */
-        DbFunction = 1048576
+        DbFunction = 1048576,
+        /** Is a `@stream` protocol-handler class (L2/L3, hot artifact). */
+        Stream = 2097152,
+        /** Is a `@daemon` L4 always-on entry class (cold artifact, at most one). */
+        Daemon = 4194304,
+        /** Is a `@scheduled(spec)` task method inside a `@daemon` class. */
+        Scheduled = 8388608,
+        /** Is a `@connect`/`@message`/`@close`/`@disconnect` stream lifecycle hook. */
+        StreamHook = 16777216
     }
     export namespace DecoratorFlags {
         /** Translates a decorator kind to the respective decorator flag. */
@@ -6553,7 +6781,14 @@ declare module "types:toilscript/src/ast" {
         Job = 35,
         Derive = 36,
         Migrate = 37,
-        Admin = 38
+        Admin = 38,
+        Daemon = 39,// @daemon       class decorator (L4 entry; at most one per project)
+        Scheduled = 40,// @scheduled(spec)  method decorator inside a @daemon class
+        Stream = 41,// @stream       class decorator (L2/L3 stream protocol handler)
+        Connect = 42,// @connect      method in a @stream class (lifecycle hook)
+        Message = 43,// @message      method in a @stream class (lifecycle hook)
+        Close = 44,// @close        method in a @stream class (lifecycle hook)
+        Disconnect = 45
     }
     export namespace DecoratorKind {
         /** Returns the kind of the specified decorator name node. Defaults to {@link DecoratorKind.CUSTOM}. */
@@ -7886,7 +8121,21 @@ declare module "types:toilscript/src/diagnosticMessages.generated" {
         Multiple_consecutive_numeric_separators_are_not_permitted = 6189,
         This_expression_is_not_callable_because_it_is_a_get_accessor_Did_you_mean_to_use_it_without = 6234,
         _super_must_be_called_before_accessing_this_in_the_constructor_of_a_derived_class = 17009,
-        _super_must_be_called_before_accessing_a_property_of_super_in_the_constructor_of_a_derived_class = 17011
+        _super_must_be_called_before_accessing_a_property_of_super_in_the_constructor_of_a_derived_class = 17011,
+        Decorator_0_is_not_valid_in_the_hot_request_artifact = 9000,
+        Decorator_0_is_not_valid_in_the_cold_daemon_artifact = 9001,
+        Only_one_daemon_class_is_allowed_per_project = 9002,
+        A_project_using_stream_cannot_declare_service_or_remote = 9003,
+        Scheduled_is_only_valid_inside_a_daemon_class = 9004,
+        Stream_hook_0_is_only_valid_inside_a_stream_class = 9005,
+        Duplicate_stream_hook_0 = 9006,
+        Stream_class_0_declares_no_lifecycle_hooks = 9007,
+        Daemon_class_0_declares_no_scheduled_tasks = 9008,
+        Decorator_0_does_not_accept_arguments = 9009,
+        Scheduled_requires_a_single_string_schedule_argument = 9010,
+        Scheduled_spec_0_is_not_a_valid_interval_or_cron_expression = 9011,
+        Scheduled_handler_0_must_take_no_arguments_and_return_void = 9012,
+        Stream_scope_must_be_a_StreamScope_enum_member = 9013
     }
     /** Translates a diagnostic code to its respective string. */
     export function diagnosticCodeToString(code: DiagnosticCode): string;
@@ -9146,6 +9395,9 @@ declare module "types:toilscript/src/compiler" {
         constructor();
         /** WebAssembly target. Defaults to {@link Target.Wasm32}. */
         target: Target;
+        /** Toil compile surface mode. null = legacy single-artifact build (all surfaces allowed,
+         *  matching pre-split behavior). "hot" = request + stream surface. "cold" = daemon surface. */
+        targetMode: string | null;
         /** Runtime type. Defaults to Incremental GC. */
         runtime: Runtime;
         /** If true, indicates that debug information will be emitted by Binaryen. */
@@ -9778,6 +10030,8 @@ declare module "types:toilscript/src/index-wasm" {
     export function setExportStart(options: Options, exportStart: string | null): void;
     /** Sets the `noUnsafe` option. */
     export function setNoUnsafe(options: Options, noUnsafe: boolean): void;
+    /** Sets the `targetMode` option ("hot", "cold", or null for legacy single-artifact). */
+    export function setTargetMode(options: Options, targetMode: string | null): void;
     /** Sets the `lowMemoryLimit` option. */
     export function setLowMemoryLimit(options: Options, lowMemoryLimit: number): void;
     /** Sets the `exportRuntime` option. */