@@ -85,6 +85,101 @@ declare function auth(target: Object, propertyKey: string | symbol, descriptor:
8585/** Declare the authenticated-user type (`@user class User { ... }`); enables `AuthService.getUser()`. */
8686declare function user ( target : Function ) : void ;
8787
88+ // --- L4 daemon (@daemon / @scheduled) + streams (@stream + lifecycle hooks),
89+ // handled natively by the compiler; typed here so editors accept the bare forms ---
90+
91+ /** Marks the single L4 daemon class: instantiated once on the global cold box,
92+ * its instance fields preserved for the box lifetime. At most one `@daemon` per
93+ * project. May declare a zero-arg `onStart(): void`, run once at boot. Cold
94+ * artifact only (a `@daemon` is a compile error in the hot/request build). */
95+ declare function daemon ( target : Function ) : void ;
96+
97+ /** Declares a `@daemon` method as a scheduled task fired on each due tick. `spec`
98+ * is an interval (`"30s"` / `"5m"` / `"1h"` / `"1d"`) or a 5-field cron string
99+ * (e.g. `"15 9 * * 1-5"`, weekdays 9:15). The handler must be `(): void` (no parameters, no return). */
100+ declare function scheduled ( spec : string ) : ( target : Object , propertyKey : string | symbol , descriptor : TypedPropertyDescriptor < any > ) => void ;
101+
102+ /** Stream placement scope for `@stream({ scope })`: `Regional` (0, L2) or
103+ * `Continental` (1, L3). Values match the runtime stream codec. */
104+ declare enum StreamScope { Regional , Continental }
105+
106+ /** Optional `@stream` config object. Set `message` to a `@data` class to receive
107+ * decoded packets; omit it for the raw-bytes default (`StreamPacket`). */
108+ interface StreamOptions {
109+ scope ?: StreamScope ;
110+ message ?: Function ;
111+ maxFrameBytes ?: i32 ;
112+ ingressRingBytes ?: i32 ;
113+ }
114+
115+ /** Marks a class as a stream protocol handler (runs on L2/L3 nodes). Its
116+ * `@connect`/`@message`/`@close`/`@disconnect`/`@channel` methods are the
117+ * lifecycle hooks. A project that uses `@stream` may NOT declare any `@service`
118+ * or `@remote` anywhere (compiler-enforced). Hot/stream artifact only. */
119+ declare function stream ( target : Function ) : void ;
120+ declare function stream ( options : StreamOptions ) : ( target : Function ) => void ;
121+
122+ /** Stream lifecycle-hook method decorators on a `@stream` class. `@connect` runs
123+ * on open (returns `StreamOutbound`); `@message` handles an inbound packet;
124+ * `@close` is a graceful close; `@disconnect` is an abrupt transport loss;
125+ * `@channel` receives an opt-in fanned-out channel message. */
126+ declare function connect ( target : Object , propertyKey : string | symbol , descriptor : TypedPropertyDescriptor < any > ) : void ;
127+ declare function message ( target : Object , propertyKey : string | symbol , descriptor : TypedPropertyDescriptor < any > ) : void ;
128+ declare function close ( target : Object , propertyKey : string | symbol , descriptor : TypedPropertyDescriptor < any > ) : void ;
129+ declare function disconnect ( target : Object , propertyKey : string | symbol , descriptor : TypedPropertyDescriptor < any > ) : void ;
130+ declare function channel ( target : Object , propertyKey : string | symbol , descriptor : TypedPropertyDescriptor < any > ) : void ;
131+
132+ // Stream handler argument/return types. Ambient (like the bignum natives below):
133+ // the compiler/runtime provides the real classes; declared here so `@stream`
134+ // handler signatures type-check in any editor.
135+
136+ /** The connection-open context passed to `@connect`. Read-only. */
137+ declare class StreamInbound {
138+ get connectionId ( ) : u64 ;
139+ get streamName ( ) : string ;
140+ get remoteIp ( ) : string ;
141+ get path ( ) : string ;
142+ header ( name : string ) : string ;
143+ }
144+
145+ /** The accept/reject + optional first-frame decision returned by
146+ * `@connect` / `@message`. */
147+ declare class StreamOutbound {
148+ static accept ( ) : StreamOutbound ;
149+ static reply ( body : Uint8Array ) : StreamOutbound ;
150+ static reject ( reason : u16 ) : StreamOutbound ;
151+ static empty ( ) : StreamOutbound ;
152+ }
153+
154+ /** The close context passed to `@close` (a graceful or host-initiated close,
155+ * distinct from `@disconnect`). */
156+ declare class StreamConnectionEvent {
157+ get connectionId ( ) : u64 ;
158+ get reason ( ) : u16 ;
159+ get durationMs ( ) : u64 ;
160+ }
161+
162+ /** The default (raw-bytes) `@message` parameter: a thin view over the host
163+ * ingress ring. The ring slot is reused after the hook returns, so copy via
164+ * `bytes()` to retain. */
165+ declare class StreamPacket {
166+ get connectionId ( ) : u64 ;
167+ get length ( ) : i32 ;
168+ bytes ( ) : Uint8Array ;
169+ at ( i : i32 ) : u8 ;
170+ }
171+
172+ /** The fanned-out channel message passed to `@channel`: the channel name plus
173+ * the raw published bytes (no decode). */
174+ declare class StreamChannelMessage {
175+ get connectionId ( ) : u64 ;
176+ get channelHash ( ) : u32 ;
177+ get channelName ( ) : string ;
178+ get length ( ) : i32 ;
179+ bytes ( ) : Uint8Array ;
180+ at ( i : i32 ) : u8 ;
181+ }
182+
88183// --- ToilDB (@database / @collection + the @query/@action/... function kinds),
89184// handled natively by the compiler; typed here so editors accept the bare forms ---
90185
0 commit comments