@almadar/core 10.129.0 → 11.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/behavior-package.d.ts +49 -11
- package/dist/behavior-package.js +1 -1
- package/dist/{orbital-CkFdDS9f.d.ts → builders-BdgbY7Th.d.ts} +5828 -6917
- package/dist/builders.d.ts +6 -6
- package/dist/builders.js +7 -6
- package/dist/{bus-CcbB__oo.d.ts → bus-C0hFDNFR.d.ts} +262 -354
- package/dist/chunk-347APWFM.js +286 -0
- package/dist/chunk-347APWFM.js.map +1 -0
- package/dist/chunk-5WQ3U7NJ.js +2363 -0
- package/dist/chunk-5WQ3U7NJ.js.map +1 -0
- package/dist/chunk-5YTPYMPZ.js +99 -0
- package/dist/chunk-5YTPYMPZ.js.map +1 -0
- package/dist/chunk-66Q5VX2F.js +3810 -0
- package/dist/chunk-66Q5VX2F.js.map +1 -0
- package/dist/chunk-7GHJU5WI.js +39 -0
- package/dist/chunk-7GHJU5WI.js.map +1 -0
- package/dist/chunk-B4MNHGBP.js +8 -0
- package/dist/chunk-B4MNHGBP.js.map +1 -0
- package/dist/chunk-E4T2MQAV.js +24 -0
- package/dist/chunk-E4T2MQAV.js.map +1 -0
- package/dist/chunk-ENOCKYGA.js +412 -0
- package/dist/chunk-ENOCKYGA.js.map +1 -0
- package/dist/chunk-FGT5OS2Y.js +918 -0
- package/dist/chunk-FGT5OS2Y.js.map +1 -0
- package/dist/chunk-GF7KCLNR.js +3284 -0
- package/dist/chunk-GF7KCLNR.js.map +1 -0
- package/dist/chunk-PNGFWLHD.js +1567 -0
- package/dist/chunk-PNGFWLHD.js.map +1 -0
- package/dist/{chunk-X4SC7FGF.js → chunk-RGACZEYC.js} +99 -96
- package/dist/chunk-RGACZEYC.js.map +1 -0
- package/dist/{chunk-RYPVOI6H.js → chunk-SNZYN7UA.js} +2541 -433
- package/dist/{chunk-RYPVOI6H.js.map → chunk-SNZYN7UA.js.map} +1 -1
- package/dist/{chunk-KDMV222Q.js → chunk-TDNQT3M3.js} +304 -373
- package/dist/chunk-TDNQT3M3.js.map +1 -0
- package/dist/chunk-VG7BRFUD.js +152 -0
- package/dist/chunk-VG7BRFUD.js.map +1 -0
- package/dist/chunk-Z7BI7DE7.js +1293 -0
- package/dist/chunk-Z7BI7DE7.js.map +1 -0
- package/dist/{domain-Dz3jP-UM.d.ts → domain-Cpmja5ak.d.ts} +55 -55
- package/dist/{effect-CiEVLsZz.d.ts → effect-DZaXwSAz.d.ts} +283 -453
- package/dist/{effect-result-Bebwu9yT.d.ts → effect-result-1HpXgeBc.d.ts} +656 -851
- package/dist/{expression-D0Fs0riG.d.ts → expression-DirYKz-f.d.ts} +5 -13
- package/dist/factory/index.d.ts +7 -144
- package/dist/factory/index.js +8 -8
- package/dist/factory-runtime/index.d.ts +7 -6
- package/dist/factory-runtime/index.js +527 -8
- package/dist/factory-runtime/index.js.map +1 -1
- package/dist/fixtures.d.ts +9 -11
- package/dist/fixtures.js +12 -8
- package/dist/fixtures.js.map +1 -1
- package/dist/i18n/index.d.ts +15 -19
- package/dist/i18n/index.js +2 -1
- package/dist/{index-BC-Jycqj.d.ts → index-D7SxwNdv.d.ts} +34 -734
- package/dist/index.d.ts +92 -247
- package/dist/index.js +322 -986
- package/dist/index.js.map +1 -1
- package/dist/kernel-wire.d.ts +3 -3
- package/dist/kernel-wire.js +3 -79
- package/dist/kernel-wire.js.map +1 -1
- package/dist/language/constructs.json +22 -2
- package/dist/language/program-types.json +203 -22
- package/dist/language/protocols.json +46 -0
- package/dist/language/ui-vocabulary.json +1697 -0
- package/dist/language/validation-codes.json +1222 -1212
- package/dist/language/vocabulary.json +44 -8
- package/dist/language-data.d.ts +7 -4
- package/dist/language-data.js +20 -14
- package/dist/language-data.js.map +1 -1
- package/dist/patterns/component-mapping.json +11 -1
- package/dist/patterns/definitions.d.ts +2 -2
- package/dist/patterns/definitions.js +1 -1
- package/dist/patterns/event-contracts.json +1 -15
- package/dist/patterns/game-font-families.json +13 -0
- package/dist/patterns/index.d.ts +24 -120
- package/dist/patterns/index.js +3 -3
- package/dist/patterns/pattern-tile-geometry.json +1065 -0
- package/dist/patterns/patterns-registry.json +2539 -431
- package/dist/patterns/registry.json +2539 -431
- package/dist/trait-sRjIivFq.d.ts +3519 -0
- package/dist/types/index.d.ts +9 -10
- package/dist/types/index.js +11 -5
- package/dist/{types-DGwrltUF.d.ts → types-C6_yPMpn.d.ts} +3 -3
- package/fixtures/events-wire/client-effects-by-trait/response.json +0 -18
- package/fixtures/events-wire/client-effects-provenance/response.json +0 -18
- package/fixtures/events-wire/effect-results-every-kind/response.json +2 -27
- package/fixtures/events-wire/navigate-1/response.json +8 -5
- package/fixtures/events-wire/navigate-2/response.json +11 -8
- package/fixtures/events-wire/navigate-3/response.json +14 -11
- package/fixtures/events-wire/navigate-back/response.json +7 -4
- package/fixtures/events-wire/render-ui-3/response.json +12 -9
- package/fixtures/events-wire/render-ui-clear/response.json +0 -7
- package/fixtures/events-wire/sse-stream/response.json +0 -20
- package/fixtures/events-wire/sse-stream/stream.json +0 -20
- package/fixtures/events-wire/stateless-traits/response.json +14 -5
- package/fixtures/kernel-wire/golden/basic-entity.json +1687 -0
- package/fixtures/kernel-wire/golden/entity-rerender.json +743 -0
- package/fixtures/kernel-wire/golden/rollback.json +793 -0
- package/fixtures/kernel-wire/golden/tick-counter.json +1538 -0
- package/fixtures/kernel-wire/golden/two-orbital-chore.json +847 -0
- package/fixtures/kernel-wire/golden/two-orbital-task.json +457 -0
- package/fixtures/kernel-wire/played-step.json +136 -0
- package/fixtures/kernel-wire/scripts/basic-entity.json +28 -0
- package/fixtures/kernel-wire/scripts/entity-rerender.json +13 -0
- package/fixtures/kernel-wire/scripts/rollback.json +53 -0
- package/fixtures/kernel-wire/scripts/tick-counter.json +26 -0
- package/fixtures/kernel-wire/scripts/two-orbital-chore.json +9 -0
- package/fixtures/kernel-wire/scripts/two-orbital-task.json +9 -0
- package/package.json +28 -19
- package/dist/builders-DmZE5By0.d.ts +0 -2663
- package/dist/chunk-45I2O4SJ.js +0 -4646
- package/dist/chunk-45I2O4SJ.js.map +0 -1
- package/dist/chunk-6LR43Z5E.js +0 -3061
- package/dist/chunk-6LR43Z5E.js.map +0 -1
- package/dist/chunk-GIUA3NUJ.js +0 -809
- package/dist/chunk-GIUA3NUJ.js.map +0 -1
- package/dist/chunk-GTY53NS5.js +0 -1908
- package/dist/chunk-GTY53NS5.js.map +0 -1
- package/dist/chunk-JOHDVS6J.js +0 -1614
- package/dist/chunk-JOHDVS6J.js.map +0 -1
- package/dist/chunk-KDMV222Q.js.map +0 -1
- package/dist/chunk-QRHJUS3D.js +0 -23
- package/dist/chunk-QRHJUS3D.js.map +0 -1
- package/dist/chunk-QUOTJULD.js +0 -4009
- package/dist/chunk-QUOTJULD.js.map +0 -1
- package/dist/chunk-V5VNGRVU.js +0 -66
- package/dist/chunk-V5VNGRVU.js.map +0 -1
- package/dist/chunk-X4SC7FGF.js.map +0 -1
- package/dist/entityAccess-BPSz1i2n.d.ts +0 -80
- package/dist/mock/index.d.ts +0 -153
- package/dist/mock/index.js +0 -190
- package/dist/mock/index.js.map +0 -1
- package/dist/schema-T5RT5s6H.d.ts +0 -282
- package/dist/state-machine/index.d.ts +0 -359
- package/dist/state-machine/index.js +0 -3
- package/dist/state-machine/index.js.map +0 -1
|
@@ -1,10 +1,9 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
7
|
-
import { J as JsonSchema } from './types-DGwrltUF.js';
|
|
2
|
+
import { E as EventPayloadValue, c as EventPayload, L as LogMeta, R as RuntimeValue, a as JsonObject, J as JsonValue } from './expression-DirYKz-f.js';
|
|
3
|
+
import { c as EntityRow, i as FieldValue, j as ServiceParams, O as OrbitalId, T as TraitId, b as EventId } from './effect-DZaXwSAz.js';
|
|
4
|
+
import { V as Viewer, H as HostAskCompletion, a as EventResponse, E as EventRequest } from './effect-result-1HpXgeBc.js';
|
|
5
|
+
import { P as PayloadField } from './trait-sRjIivFq.js';
|
|
6
|
+
import { J as JsonSchema } from './types-C6_yPMpn.js';
|
|
8
7
|
|
|
9
8
|
/**
|
|
10
9
|
* Service Contract Types
|
|
@@ -140,7 +139,7 @@ interface StoreFilter<T> {
|
|
|
140
139
|
value: FieldValue | undefined;
|
|
141
140
|
}
|
|
142
141
|
/** One page of rows from a store: filters, then search, then sort, then the page. */
|
|
143
|
-
|
|
142
|
+
type RowPageRequest<T> = {
|
|
144
143
|
/** 1-indexed. */
|
|
145
144
|
page: number;
|
|
146
145
|
pageSize: number;
|
|
@@ -150,12 +149,12 @@ interface RowPageRequest<T> {
|
|
|
150
149
|
searchFields?: readonly string[];
|
|
151
150
|
sortBy?: string;
|
|
152
151
|
sortOrder?: "asc" | "desc";
|
|
153
|
-
}
|
|
154
|
-
|
|
152
|
+
};
|
|
153
|
+
type RowPage<T> = {
|
|
155
154
|
rows: T[];
|
|
156
155
|
/** Rows matching the filters and search, across all pages. */
|
|
157
156
|
total: number;
|
|
158
|
-
}
|
|
157
|
+
};
|
|
159
158
|
/** The comparison members of `StoreFilterOp`. */
|
|
160
159
|
type RowCompareOp = Extract<StoreFilterOp, "==" | "!=" | "<" | "<=" | ">" | ">=">;
|
|
161
160
|
/**
|
|
@@ -200,25 +199,25 @@ type RowPredicate = {
|
|
|
200
199
|
value: boolean;
|
|
201
200
|
};
|
|
202
201
|
/** One sort key. Missing and null values sort last in both directions; ties break by `id` ascending. A query with no `order` is ordered by `createdAt` ascending, then `id` (EXEC-FETCH-1). */
|
|
203
|
-
|
|
202
|
+
type RowOrder = {
|
|
204
203
|
field: string;
|
|
205
204
|
direction: "asc" | "desc";
|
|
206
|
-
}
|
|
205
|
+
};
|
|
207
206
|
/**
|
|
208
207
|
* A vector-similarity query: up to `k` rows ordered by descending cosine similarity of `field` to `vector`
|
|
209
208
|
* (EXEC-FETCH-2). A row whose field is absent, null or of zero norm is skipped; a stored vector that is not a
|
|
210
209
|
* `[number]` of the query's length, a zero-norm query or a non-positive `k` fails.
|
|
211
210
|
*/
|
|
212
|
-
|
|
211
|
+
type RowNearest = {
|
|
213
212
|
field: string;
|
|
214
213
|
vector: number[];
|
|
215
214
|
k: number;
|
|
216
|
-
}
|
|
215
|
+
};
|
|
217
216
|
/**
|
|
218
217
|
* A pushed-down query: rows matching `policy` AND `filter`, ordered, then windowed. `policy` is the
|
|
219
218
|
* entity's `@read` predicate already specialised to the viewer; `filter` is the call-site filter.
|
|
220
219
|
*/
|
|
221
|
-
|
|
220
|
+
type RowQuery = {
|
|
222
221
|
policy?: RowPredicate;
|
|
223
222
|
filter?: RowPredicate;
|
|
224
223
|
/** Absent = `createdAt` ascending, then `id` ascending (EXEC-FETCH-1). */
|
|
@@ -230,7 +229,7 @@ interface RowQuery {
|
|
|
230
229
|
total?: RowTotalMode;
|
|
231
230
|
/** The nearest `k` rows among those `policy` and `filter` admit. Excludes `order`, `offset` and `limit`; `total` is the count returned. */
|
|
232
231
|
nearest?: RowNearest;
|
|
233
|
-
}
|
|
232
|
+
};
|
|
234
233
|
/** The answer to a `RowQuery`: the window, and `total` = every match before the window. */
|
|
235
234
|
type RowQueryPage = RowPage<EntityRow>;
|
|
236
235
|
/** Value kinds a store can compare, in `compare`/`member`/`hasElement` operands. */
|
|
@@ -238,14 +237,14 @@ type RowValueKind = "string" | "number" | "boolean" | "date" | "null";
|
|
|
238
237
|
/** Every operator a `RowPredicate` leaf can carry. */
|
|
239
238
|
type RowOperator = RowCompareOp | "member" | "hasElement" | "contains";
|
|
240
239
|
/** The value kinds one operator accepts on a store; an operator not listed accepts every kind. */
|
|
241
|
-
|
|
240
|
+
type OperatorValueKinds = {
|
|
242
241
|
operator: RowOperator;
|
|
243
242
|
valueKinds: RowValueKind[];
|
|
244
|
-
}
|
|
243
|
+
};
|
|
245
244
|
/** Whether `total` counts every match (`exact`, the default) or the store may skip the count (`none`). */
|
|
246
245
|
type RowTotalMode = "exact" | "none";
|
|
247
246
|
/** What an adapter's `queryPage` honours for one entity type. */
|
|
248
|
-
|
|
247
|
+
type QueryCapabilities = {
|
|
249
248
|
leaves: ("compare" | "member" | "hasElement" | "contains" | "isNull")[];
|
|
250
249
|
combinators: ("all" | "any" | "not")[];
|
|
251
250
|
compareOps: RowCompareOp[];
|
|
@@ -265,12 +264,12 @@ interface QueryCapabilities {
|
|
|
265
264
|
idsOnly?: boolean;
|
|
266
265
|
/** `nearest` is pushed down: the store ranks by cosine similarity itself (EXEC-FETCH-2). */
|
|
267
266
|
nearest?: boolean;
|
|
268
|
-
}
|
|
267
|
+
};
|
|
269
268
|
/** The answer to a `queryIds`: the window's ids in order, and `total` as in `RowQueryPage`. */
|
|
270
|
-
|
|
269
|
+
type RowIdPage = {
|
|
271
270
|
ids: string[];
|
|
272
271
|
total: number;
|
|
273
|
-
}
|
|
272
|
+
};
|
|
274
273
|
/**
|
|
275
274
|
* One write. `create` fails (`duplicate-id`) when its id is taken. `upsert` creates the row or replaces it
|
|
276
275
|
* whole by id (`created` / `updated`), keeping the existing `createdAt`. `update` changes an existing row only
|
|
@@ -336,12 +335,12 @@ type RowWriteOutcome = {
|
|
|
336
335
|
* not attempted and have no outcome (a run of plain `persist` effects).
|
|
337
336
|
*/
|
|
338
337
|
type RowWriteFailureMode = "atomic" | "stop";
|
|
339
|
-
|
|
338
|
+
type RowWriteBatch = {
|
|
340
339
|
ops: RowWriteOp[];
|
|
341
340
|
onFailure: RowWriteFailureMode;
|
|
342
|
-
}
|
|
341
|
+
};
|
|
343
342
|
/** What an adapter's `writeWhere`/`writeBatch` honours for one entity type. */
|
|
344
|
-
|
|
343
|
+
type WriteCapabilities = {
|
|
345
344
|
/** The guard predicates the store can test; a `Pick` of the query capabilities. */
|
|
346
345
|
guards: Pick<QueryCapabilities, "leaves" | "combinators" | "compareOps">;
|
|
347
346
|
/** `writeWhere` tests the guard and the existence of the row in one step. */
|
|
@@ -356,7 +355,7 @@ interface WriteCapabilities {
|
|
|
356
355
|
rekey?: boolean;
|
|
357
356
|
/** The store commits rows the kernel decided (`commitRows`) and holds no write semantics (EXEC-STORE-5). */
|
|
358
357
|
commitRows?: boolean;
|
|
359
|
-
}
|
|
358
|
+
};
|
|
360
359
|
/** What a compare-and-commit does to one row the kernel read. */
|
|
361
360
|
type RowCommitWrite = {
|
|
362
361
|
kind: "keep";
|
|
@@ -367,12 +366,12 @@ type RowCommitWrite = {
|
|
|
367
366
|
kind: "delete";
|
|
368
367
|
};
|
|
369
368
|
/** One row of a compare-and-commit: the version the kernel read (`null` when absent) and what it writes (EXEC-STORE-5). */
|
|
370
|
-
|
|
369
|
+
type RowCommit = {
|
|
371
370
|
entityType: string;
|
|
372
371
|
id: string;
|
|
373
372
|
expected: EntityRow | null;
|
|
374
373
|
write: RowCommitWrite;
|
|
375
|
-
}
|
|
374
|
+
};
|
|
376
375
|
/**
|
|
377
376
|
* Storage contract for CRUD operations on entity rows. The runtime's effect
|
|
378
377
|
* handlers and every database backend (`@almadar/db`) speak this interface.
|
|
@@ -475,12 +474,12 @@ declare function createLazyService<T>(factory: () => T): LazyService<T>;
|
|
|
475
474
|
* A fetched page by reference: `ids` = the window in order, `total` = matches before the window at
|
|
476
475
|
* dispatch time, `query` = what produced it (its predicates, incl. the @read policy, re-count `total`; order and window are ignored).
|
|
477
476
|
*/
|
|
478
|
-
|
|
477
|
+
type RowSetRef = {
|
|
479
478
|
entityType: string;
|
|
480
479
|
ids: string[];
|
|
481
480
|
total: number;
|
|
482
481
|
query: RowQuery;
|
|
483
|
-
}
|
|
482
|
+
};
|
|
484
483
|
declare const RowSetRefSchema: z.ZodType<RowSetRef>;
|
|
485
484
|
/** Tag property of a `RowSetMarker`; `$`-prefixed so it never collides with a pattern prop key. */
|
|
486
485
|
declare const ROW_SET_MARKER: "$rowSet";
|
|
@@ -493,65 +492,195 @@ declare function rowSetMarker(ref: RowSetRef): RowSetMarker;
|
|
|
493
492
|
declare function isRowSetMarker(value: RuntimeValue): value is RowSetMarker;
|
|
494
493
|
|
|
495
494
|
/**
|
|
496
|
-
*
|
|
497
|
-
*
|
|
498
|
-
*
|
|
499
|
-
*
|
|
500
|
-
*
|
|
501
|
-
*
|
|
495
|
+
* Authenticated user context — what `@user.x` resolves against.
|
|
496
|
+
*
|
|
497
|
+
* The canonical shape for the `user` binding root, shared by both execution
|
|
498
|
+
* paths: the JS interpreter resolves `@user.id` through
|
|
499
|
+
* `EvaluationContext.user`, and the compiled shell emits `user?.id` against the
|
|
500
|
+
* `UserContext` its `@app/shared` re-exports from here.
|
|
501
|
+
*
|
|
502
|
+
* `id` is the field the behavior library reads for ownership scoping and `role`
|
|
503
|
+
* the field it reads for capability gating. Auth providers that name the subject
|
|
504
|
+
* `uid` must normalize at their boundary — {@link normalizeUserContext} does that.
|
|
502
505
|
*
|
|
503
506
|
* @packageDocumentation
|
|
504
507
|
*/
|
|
505
508
|
|
|
506
509
|
/**
|
|
507
|
-
*
|
|
508
|
-
*
|
|
509
|
-
*
|
|
510
|
+
* What a host's auth provider has resolved the viewer to be — from session
|
|
511
|
+
* resolution only, never from an interactive sign-in action: `pending` until
|
|
512
|
+
* the session is known; `anonymous` / `authenticated` once it is; `failed`
|
|
513
|
+
* when connecting or resolving the session failed; `unavailable` when the host
|
|
514
|
+
* has no sign-in configured. An `access: authenticated` page mounts only on
|
|
515
|
+
* `authenticated`.
|
|
510
516
|
*/
|
|
511
|
-
type
|
|
512
|
-
interface ExternalInput {
|
|
513
|
-
orbital: string;
|
|
514
|
-
trait: string;
|
|
515
|
-
event: string;
|
|
516
|
-
payloadSchema: PayloadField[];
|
|
517
|
-
description?: string;
|
|
518
|
-
synonyms?: string;
|
|
519
|
-
tier?: string;
|
|
520
|
-
}
|
|
521
|
-
declare function externalInputsOf(schema: OrbitalSchema): ExternalInput[];
|
|
517
|
+
type ViewerAuthority = 'pending' | 'anonymous' | 'authenticated' | 'failed' | 'unavailable';
|
|
522
518
|
/**
|
|
523
|
-
* The
|
|
524
|
-
*
|
|
525
|
-
*
|
|
526
|
-
* (`orbital-shell-typescript` `orbital_route.rs`).
|
|
519
|
+
* The `@user` binding: a {@link Viewer} held flat. Its named fields are the viewer's; each claim is a key holding its
|
|
520
|
+
* JSON value, readable as `@user.<claim>`. The Rust twin of the conversion is `orbital_core_base::viewer`
|
|
521
|
+
* (`Viewer::from_user` / `Viewer::to_user`).
|
|
527
522
|
*/
|
|
528
|
-
|
|
529
|
-
|
|
523
|
+
type UserContext = Omit<Viewer, 'claims'> & {
|
|
524
|
+
[key: string]: FieldValue;
|
|
525
|
+
};
|
|
526
|
+
/** Zod twin of the generated {@link Viewer}: the record a `.lolo` program names as `Viewer`. */
|
|
527
|
+
declare const ViewerSchema: z.ZodType<Viewer>;
|
|
530
528
|
/**
|
|
531
|
-
* The
|
|
532
|
-
*
|
|
533
|
-
*
|
|
534
|
-
* `orbital-compiler` `config_type.rs` `EventRefIndex::check`.
|
|
529
|
+
* The identity of an unauthenticated viewer. A resolvable object rather than
|
|
530
|
+
* `undefined` so a role predicate evaluates to a definite `false` instead of
|
|
531
|
+
* comparing against nothing.
|
|
535
532
|
*/
|
|
536
|
-
declare
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
533
|
+
declare const ANONYMOUS_USER: UserContext;
|
|
534
|
+
/** Provider-shaped identity claims, before normalization. */
|
|
535
|
+
type RawUserClaims = {
|
|
536
|
+
id?: string;
|
|
537
|
+
uid?: string;
|
|
538
|
+
email?: string | null;
|
|
539
|
+
name?: string | null;
|
|
540
|
+
displayName?: string | null;
|
|
541
|
+
/** Absent or `null` when the token carries none, as the kernel's `Viewer.role` (`Option`). */
|
|
542
|
+
role?: string | null;
|
|
543
|
+
permissions?: string[] | null;
|
|
544
|
+
} & {
|
|
545
|
+
[key: string]: FieldValue;
|
|
546
|
+
};
|
|
547
|
+
/** Zod twin of `RawUserClaims` — the wire shape of `EventRequest.user`. */
|
|
548
|
+
declare const RawUserClaimsSchema: z.ZodType<RawUserClaims>;
|
|
549
|
+
/**
|
|
550
|
+
* Normalize provider claims into a {@link UserContext}.
|
|
551
|
+
*
|
|
552
|
+
* Firebase (and most OIDC providers) name the subject `uid` and the display name
|
|
553
|
+
* `displayName`, while every `.lolo` behavior reads `@user.id` / `@user.name`.
|
|
554
|
+
* Without this normalization `@user.id` is `undefined` against a fully
|
|
555
|
+
* authenticated request and every ownership filter silently matches no rows.
|
|
556
|
+
* `uid` is preserved so `@user.uid` keeps working.
|
|
557
|
+
*
|
|
558
|
+
* Returns `undefined` for absent or subject-less claims so callers can
|
|
559
|
+
* distinguish "no auth ran" from "anonymous"; use {@link ANONYMOUS_USER} where a
|
|
560
|
+
* definite identity is required.
|
|
561
|
+
*/
|
|
562
|
+
declare function normalizeUserContext(claims: RawUserClaims | null | undefined): UserContext | undefined;
|
|
563
|
+
/**
|
|
564
|
+
* Turn a row of an app's `[identity]` entity into a viewer.
|
|
565
|
+
*
|
|
566
|
+
* There is no separate persona shape: an identity row IS the persona
|
|
567
|
+
* (`Almadar_LOLO_Identity.md` §4.3), so this only guards the one field the
|
|
568
|
+
* behavior library requires — a non-empty string `id` — and passes every other
|
|
569
|
+
* declared field through as a `@user.<field>` claim. Rows without a usable id
|
|
570
|
+
* yield `undefined` rather than a persona nobody can own rows as.
|
|
571
|
+
*/
|
|
572
|
+
declare function personaFromIdentityRow(row: Record<string, FieldValue | undefined>): UserContext | undefined;
|
|
573
|
+
/** Look a persona up in a roster by id, or by role when no id matches. */
|
|
574
|
+
declare function findPersonaInRoster(roster: readonly UserContext[], idOrRole: string): UserContext | undefined;
|
|
575
|
+
/**
|
|
576
|
+
* Resolve a persona spec — a bare id/role (`Person Id 3`, `moderator`) or a full
|
|
577
|
+
* JSON `UserContext` — into a viewer. This is the `ALMADAR_PERSONA` contract,
|
|
578
|
+
* shared by every host that presents an app as somebody.
|
|
579
|
+
*
|
|
580
|
+
* The roster is the app's OWN declared personas — the seeded rows of its
|
|
581
|
+
* `[identity]` entity (`Almadar_LOLO_Identity.md` §4.3) — supplied by the host
|
|
582
|
+
* that has them in hand (the runtime's live store on the interpreter path, the
|
|
583
|
+
* schema-derived seed rows on the compiled path). There is no global roster:
|
|
584
|
+
* an app without an `[identity]` entity resolves only JSON-form specs.
|
|
585
|
+
*
|
|
586
|
+
* Throws on anything unresolvable rather than returning `undefined`: "no persona"
|
|
587
|
+
* and "persona silently ignored" look identical on screen, so a bad spec must
|
|
588
|
+
* fail at boot instead of rendering as nobody.
|
|
589
|
+
*/
|
|
590
|
+
declare function resolvePersonaSpec(spec: string, roster: readonly UserContext[]): UserContext;
|
|
591
|
+
|
|
592
|
+
declare const ExternalInputSchema: z.ZodObject<{
|
|
593
|
+
orbital: z.ZodString;
|
|
594
|
+
trait: z.ZodString;
|
|
595
|
+
event: z.ZodString;
|
|
596
|
+
payloadSchema: z.ZodArray<z.ZodType<PayloadField, unknown, z.core.$ZodTypeInternals<PayloadField, unknown>>>;
|
|
597
|
+
description: z.ZodOptional<z.ZodString>;
|
|
598
|
+
synonyms: z.ZodOptional<z.ZodString>;
|
|
599
|
+
tier: z.ZodOptional<z.ZodString>;
|
|
600
|
+
}, z.core.$strip>;
|
|
601
|
+
/** A declared input: what an outside client may send which trait. */
|
|
602
|
+
type ExternalInput = z.infer<typeof ExternalInputSchema>;
|
|
603
|
+
/** One declared handler: the trait and event a hook name is delivered to, and the event that answers. */
|
|
604
|
+
declare const InboundRouteSchema: z.ZodObject<{
|
|
605
|
+
name: z.ZodString;
|
|
606
|
+
orbital: z.ZodString;
|
|
607
|
+
trait: z.ZodString;
|
|
608
|
+
event: z.ZodString;
|
|
609
|
+
answer: z.ZodString;
|
|
610
|
+
verifies: z.ZodOptional<z.ZodObject<{
|
|
611
|
+
header: z.ZodString;
|
|
612
|
+
credential: z.ZodString;
|
|
613
|
+
}, z.core.$strip>>;
|
|
614
|
+
}, z.core.$strip>;
|
|
615
|
+
type InboundRoute = z.infer<typeof InboundRouteSchema>;
|
|
616
|
+
/** What a host carries of one request: its headers and its body text exactly as received. */
|
|
617
|
+
interface InboundDelivery {
|
|
618
|
+
headers: Readonly<Record<string, string | undefined>>;
|
|
619
|
+
rawBody: string;
|
|
547
620
|
}
|
|
621
|
+
/** The HTTP answer the host writes: the status and the JSON text of the body. */
|
|
622
|
+
declare const InboundAnswerSchema: z.ZodObject<{
|
|
623
|
+
status: z.ZodNumber;
|
|
624
|
+
body: z.ZodString;
|
|
625
|
+
stderr: z.ZodOptional<z.ZodString>;
|
|
626
|
+
headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
627
|
+
}, z.core.$strip>;
|
|
628
|
+
type InboundAnswer = z.infer<typeof InboundAnswerSchema>;
|
|
629
|
+
/** The kernel's answer to "which handler does this hook name": the route, or the answer to write for a hook it does not serve. */
|
|
630
|
+
declare const InboundFoundSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
631
|
+
route: z.ZodObject<{
|
|
632
|
+
name: z.ZodString;
|
|
633
|
+
orbital: z.ZodString;
|
|
634
|
+
trait: z.ZodString;
|
|
635
|
+
event: z.ZodString;
|
|
636
|
+
answer: z.ZodString;
|
|
637
|
+
verifies: z.ZodOptional<z.ZodObject<{
|
|
638
|
+
header: z.ZodString;
|
|
639
|
+
credential: z.ZodString;
|
|
640
|
+
}, z.core.$strip>>;
|
|
641
|
+
}, z.core.$strip>;
|
|
642
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
643
|
+
answer: z.ZodObject<{
|
|
644
|
+
status: z.ZodNumber;
|
|
645
|
+
body: z.ZodString;
|
|
646
|
+
stderr: z.ZodOptional<z.ZodString>;
|
|
647
|
+
headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
648
|
+
}, z.core.$strip>;
|
|
649
|
+
}, z.core.$strip>]>;
|
|
650
|
+
/** An inbound hook event named on a client-facing route: the trait that handles it and the refusal message. */
|
|
651
|
+
declare const InboundOnlySchema: z.ZodNullable<z.ZodObject<{
|
|
652
|
+
trait: z.ZodString;
|
|
653
|
+
message: z.ZodString;
|
|
654
|
+
}, z.core.$strip>>;
|
|
655
|
+
/** A list of names (the readable entities). */
|
|
656
|
+
declare const NameListSchema: z.ZodArray<z.ZodString>;
|
|
657
|
+
/** A name, or null when the program has none (the `[identity]` entity, the owner of an entity). */
|
|
658
|
+
declare const OptionalNameSchema: z.ZodNullable<z.ZodString>;
|
|
659
|
+
/** One way a value misses its declared payload (the kernel's `payloadIssues`). */
|
|
660
|
+
declare const PayloadIssueSchema: z.ZodObject<{
|
|
661
|
+
path: z.ZodString;
|
|
662
|
+
reason: z.ZodEnum<{
|
|
663
|
+
unknown: "unknown";
|
|
664
|
+
missing: "missing";
|
|
665
|
+
"wrong-type": "wrong-type";
|
|
666
|
+
"not-one-of": "not-one-of";
|
|
667
|
+
}>;
|
|
668
|
+
expected: z.ZodOptional<z.ZodString>;
|
|
669
|
+
}, z.core.$strip>;
|
|
670
|
+
type PayloadIssue = z.infer<typeof PayloadIssueSchema>;
|
|
671
|
+
/** The JSON Schema of a declared payload (the kernel's `payloadSchemaToJsonSchema`). */
|
|
672
|
+
declare const PayloadJsonSchemaSchema: z.ZodType<JsonSchema>;
|
|
673
|
+
|
|
548
674
|
/**
|
|
549
|
-
*
|
|
550
|
-
*
|
|
551
|
-
*
|
|
552
|
-
*
|
|
675
|
+
* Bus Event Types (framework concept)
|
|
676
|
+
*
|
|
677
|
+
* Canonical event shape for Almadar's cross-package event bus. Hoisted into
|
|
678
|
+
* `@almadar/core` so `@almadar/ui`, `@almadar/runtime`, and generated code
|
|
679
|
+
* all agree on the same structure. Replaces the previously divergent
|
|
680
|
+
* `KFlowEvent` (ui) and `RuntimeEvent` (runtime) definitions.
|
|
681
|
+
*
|
|
682
|
+
* @packageDocumentation
|
|
553
683
|
*/
|
|
554
|
-
declare function payloadIssues(fields: readonly PayloadField[], value: EventPayloadValue): PayloadIssue[];
|
|
555
684
|
|
|
556
685
|
/**
|
|
557
686
|
* Declared event key. A trait's event names (INIT, SAVE, CLOSE,
|
|
@@ -641,7 +770,7 @@ type EventListen<P> = string & {
|
|
|
641
770
|
* `transition` and `tick` are optional runtime-internal details; most
|
|
642
771
|
* consumers only care about `orbital` and `trait`.
|
|
643
772
|
*/
|
|
644
|
-
|
|
773
|
+
type BusEventSource = {
|
|
645
774
|
orbital?: string;
|
|
646
775
|
/** V4 dual-carry id sibling of `orbital` — stable across an orbital rename. */
|
|
647
776
|
orbitalId?: OrbitalId;
|
|
@@ -680,7 +809,7 @@ interface BusEventSource {
|
|
|
680
809
|
dispatched?: boolean;
|
|
681
810
|
/**
|
|
682
811
|
* The client that originated the dispatch whose effects emitted this
|
|
683
|
-
* event (from `
|
|
812
|
+
* event (from `EventRequest.clientId`); absent for headless
|
|
684
813
|
* dispatches (ticks, circuit-router probes, walkers). The server-side
|
|
685
814
|
* listens fan-out skips client-originated cascade emits — under dual
|
|
686
815
|
* execution the originating client relays every cascade hop through the
|
|
@@ -701,20 +830,23 @@ interface BusEventSource {
|
|
|
701
830
|
* host (`setLiveBroadcastSink`) also fans out to every other connected client.
|
|
702
831
|
*/
|
|
703
832
|
persistSuccess?: boolean;
|
|
704
|
-
|
|
833
|
+
/**
|
|
834
|
+
* The row of the emitting trait's entity that made the emit, when the trait's rows are addressed by a `per`
|
|
835
|
+
* listener. A listener with a `per` clause evaluates its own key; one without ignores this.
|
|
836
|
+
*/
|
|
837
|
+
instanceKey?: string;
|
|
838
|
+
};
|
|
705
839
|
/** The delivery a transition is processing: `@event`, and one element of `@prevEvents` (Runtime Spec Clause 5.5). */
|
|
706
|
-
|
|
840
|
+
type DeliveryRecord = {
|
|
707
841
|
event: string;
|
|
708
842
|
payload?: EventPayload;
|
|
709
843
|
source: BusEventSource;
|
|
710
|
-
}
|
|
844
|
+
};
|
|
711
845
|
/** A trait's log so far in a dispatch that began elsewhere (`@prevEvents` / `@prevStates`), carried on the request. */
|
|
712
|
-
|
|
846
|
+
type DispatchLog = {
|
|
713
847
|
prevEvents: DeliveryRecord[];
|
|
714
848
|
prevStates: string[];
|
|
715
|
-
}
|
|
716
|
-
/** The evaluator value of a delivery record: `source` carries exactly the ten `BusEventSource` fields that are set. */
|
|
717
|
-
declare function deliveryRecordValue(record: DeliveryRecord): EventPayload;
|
|
849
|
+
};
|
|
718
850
|
/** Zod twin of `BusEventSource`. */
|
|
719
851
|
declare const BusEventSourceSchema: z.ZodType<BusEventSource, object>;
|
|
720
852
|
/** Zod twin of `DeliveryRecord`. */
|
|
@@ -728,7 +860,7 @@ declare const DispatchLogSchema: z.ZodType<DispatchLog, object>;
|
|
|
728
860
|
* `event.source?.orbital === 'X' && event.source?.trait === 'Y'` without
|
|
729
861
|
* parsing a delimiter.
|
|
730
862
|
*/
|
|
731
|
-
|
|
863
|
+
type BusEvent = {
|
|
732
864
|
/** Event type identifier (e.g., 'CartItemLoaded', 'TASK_COMPLETED') */
|
|
733
865
|
type: EventKey;
|
|
734
866
|
/** Optional structured payload */
|
|
@@ -737,7 +869,7 @@ interface BusEvent {
|
|
|
737
869
|
timestamp: number;
|
|
738
870
|
/** Optional origin info for filtering */
|
|
739
871
|
source?: BusEventSource;
|
|
740
|
-
}
|
|
872
|
+
};
|
|
741
873
|
/** Bus event listener callback. */
|
|
742
874
|
type BusEventListener = (event: BusEvent) => void;
|
|
743
875
|
/** Returned by `on()` / `once()` to detach a listener. */
|
|
@@ -749,15 +881,15 @@ type Unsubscribe = () => void;
|
|
|
749
881
|
* generated compiled-path `EmittedEvent` (orbital-shell-typescript's
|
|
750
882
|
* `shared/types.ts`) so the two execution paths agree on one shape.
|
|
751
883
|
*/
|
|
752
|
-
|
|
884
|
+
type EmittedEvent = {
|
|
753
885
|
event: string;
|
|
754
886
|
payload?: EventPayload;
|
|
755
887
|
source?: BusEventSource;
|
|
756
|
-
}
|
|
888
|
+
};
|
|
757
889
|
/** Zod twin of `EmittedEvent`. Third type param `object`, see `BusEventSourceSchema`. */
|
|
758
890
|
declare const EmittedEventSchema: z.ZodType<EmittedEvent, object>;
|
|
759
891
|
/**
|
|
760
|
-
* Client-side effect tuple shipped in `
|
|
892
|
+
* Client-side effect tuple shipped in `EventResponse.clientEffectsByTrait`.
|
|
761
893
|
* Restricted to the effect kinds the client knows how to apply to the
|
|
762
894
|
* UI: render-ui (slot mutation, including the `toast` slot that carries
|
|
763
895
|
* what used to be the separate notify effect) and navigate (route change).
|
|
@@ -774,138 +906,56 @@ declare const EmittedEventSchema: z.ZodType<EmittedEvent, object>;
|
|
|
774
906
|
* `(render-ui slot ...)` SExpr without re-validating against the registry —
|
|
775
907
|
* registry validation lives in `orbital validate` / `lolo` parse, not here.
|
|
776
908
|
*/
|
|
777
|
-
type ClientRenderUITuple = ['render-ui', string,
|
|
909
|
+
type ClientRenderUITuple = ['render-ui', string, JsonObject | null];
|
|
778
910
|
type ClientNavigateTuple = ['navigate', string] | ['navigate', string, Record<string, string> | null] | ['navigate', string, Record<string, string> | null, {
|
|
779
911
|
crumb?: string;
|
|
780
912
|
}];
|
|
781
913
|
type ClientNavigateBackTuple = ['navigate-back'];
|
|
782
|
-
|
|
914
|
+
/** A `runsOn: client` host-port effect (`auth/sign-out`, `audio/*`) the client host answers; its arguments are resolved. */
|
|
915
|
+
type ClientHostAskTuple = ['host-ask', string, JsonValue[]] | ['host-ask', string, JsonValue[], HostAskCompletion];
|
|
916
|
+
|
|
917
|
+
type ClientEffectTuple = ClientRenderUITuple | ClientNavigateTuple | ClientNavigateBackTuple | ClientHostAskTuple;
|
|
783
918
|
/** Zod twin of `ClientRenderUITuple`. */
|
|
784
|
-
declare const ClientRenderUITupleSchema: z.ZodTuple<[z.ZodLiteral<"render-ui">, z.ZodString, z.ZodType<
|
|
919
|
+
declare const ClientRenderUITupleSchema: z.ZodTuple<[z.ZodLiteral<"render-ui">, z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>], null>;
|
|
785
920
|
/** Zod twin of `ClientNavigateTuple` — one variant per fixed arity (2/3/4), unioned. */
|
|
786
921
|
declare const ClientNavigateTupleSchema: z.ZodUnion<readonly [z.ZodTuple<[z.ZodLiteral<"navigate">, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"navigate">, z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>], null>, z.ZodTuple<[z.ZodLiteral<"navigate">, z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>, z.ZodObject<{
|
|
787
922
|
crumb: z.ZodOptional<z.ZodString>;
|
|
788
923
|
}, z.core.$strip>], null>]>;
|
|
789
924
|
/** Zod twin of `ClientNavigateBackTuple`. */
|
|
790
925
|
declare const ClientNavigateBackTupleSchema: z.ZodTuple<[z.ZodLiteral<"navigate-back">], null>;
|
|
926
|
+
/** Zod twin of `ClientHostAskTuple`. */
|
|
927
|
+
declare const HostAskCompletionSchema: z.ZodObject<{
|
|
928
|
+
trait: z.ZodString;
|
|
929
|
+
entityId: z.ZodOptional<z.ZodString>;
|
|
930
|
+
key: z.ZodOptional<z.ZodString>;
|
|
931
|
+
success: z.ZodOptional<z.ZodString>;
|
|
932
|
+
failure: z.ZodOptional<z.ZodString>;
|
|
933
|
+
onMessage: z.ZodOptional<z.ZodString>;
|
|
934
|
+
}, z.core.$strict>;
|
|
935
|
+
declare const ClientHostAskTupleSchema: z.ZodUnion<readonly [z.ZodTuple<[z.ZodLiteral<"host-ask">, z.ZodString, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>], null>, z.ZodTuple<[z.ZodLiteral<"host-ask">, z.ZodString, z.ZodArray<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>, z.ZodObject<{
|
|
936
|
+
trait: z.ZodString;
|
|
937
|
+
entityId: z.ZodOptional<z.ZodString>;
|
|
938
|
+
key: z.ZodOptional<z.ZodString>;
|
|
939
|
+
success: z.ZodOptional<z.ZodString>;
|
|
940
|
+
failure: z.ZodOptional<z.ZodString>;
|
|
941
|
+
onMessage: z.ZodOptional<z.ZodString>;
|
|
942
|
+
}, z.core.$strict>], null>]>;
|
|
791
943
|
/** Zod twin of `ClientEffectTuple`. */
|
|
792
944
|
declare const ClientEffectTupleSchema: z.ZodType<ClientEffectTuple>;
|
|
793
|
-
/**
|
|
794
|
-
* Client → server event dispatch request. The single upstream owner of
|
|
795
|
-
* this shape — both the JS interpreter (`@almadar/runtime`'s
|
|
796
|
-
* `OrbitalEventRequest`) and the compiled path's generated `EventRequest`
|
|
797
|
-
* (orbital-shell-typescript's `shared/types.ts`, mirrored 1:1 in
|
|
798
|
-
* `orbital-core`) carry the same fields, so the two execution paths cannot
|
|
799
|
-
* drift.
|
|
800
|
-
*/
|
|
801
|
-
interface OrbitalEventRequest {
|
|
802
|
-
event: string;
|
|
803
|
-
/**
|
|
804
|
-
* V4 dual-carry id sibling of `event` — the fired event's id, when known
|
|
805
|
-
* (e.g. threaded from a `listens[].triggersId`). Optional; absent means
|
|
806
|
-
* the state machine dispatches by name only (legacy).
|
|
807
|
-
*/
|
|
808
|
-
eventId?: EventId;
|
|
809
|
-
payload?: EventPayload;
|
|
810
|
-
entityId?: string;
|
|
811
|
-
/**
|
|
812
|
-
* Scoped-listen delivery: dispatch to THIS trait only. A listens-matched
|
|
813
|
-
* trigger is addressed to the listening trait; without this, a trigger
|
|
814
|
-
* renamed to INIT broadcast orbital-wide and re-ran every trait's
|
|
815
|
-
* initializer (R-SCOPED-LISTEN-INIT-RENAME-FREEZE re-fire cascade).
|
|
816
|
-
*/
|
|
817
|
-
targetTrait?: string;
|
|
818
|
-
/** Provider claims for `@user` bindings, normalized by `normalizeUserContext`. */
|
|
819
|
-
user?: RawUserClaims;
|
|
820
|
-
/** Per-tab client identity (UUID) — excludes this request's origin from live-broadcast delivery. */
|
|
821
|
-
clientId?: string;
|
|
822
|
-
/**
|
|
823
|
-
* The viewer's locale (one of the program's declared `locales`): servers
|
|
824
|
-
* evaluate `i18n/t` and `@locale` with it. Absent means the program's first
|
|
825
|
-
* declared locale.
|
|
826
|
-
*/
|
|
827
|
-
locale?: string;
|
|
828
|
-
/**
|
|
829
|
-
* Broadcast-class marker (T6, docs/Almadar_Tick_Loop.md §3a): the name of
|
|
830
|
-
* the tick that emitted this event. Tick-stamped dispatches are
|
|
831
|
-
* latest-state broadcasts — the client fires them without awaiting the
|
|
832
|
-
* response, and the server relays them to OTHER tabs coalesced
|
|
833
|
-
* (newest-per-key) at a snapshot rate instead of 1:1.
|
|
834
|
-
*/
|
|
835
|
-
tick?: string;
|
|
836
|
-
/** Emitting trait for a tick-stamped dispatch — builds the relay's BusEventSource (sourceless emits are dropped client-side). */
|
|
837
|
-
sourceTrait?: string;
|
|
838
|
-
/**
|
|
839
|
-
* Run one firing of a tick at the data authority: the trait's tick named `tick` runs its
|
|
840
|
-
* effects there, as `event` + `targetTrait` runs a transition. A browser-run tick sends one
|
|
841
|
-
* for its data effects on browser-stored entities (a tick has no event to replay under);
|
|
842
|
-
* `event` is the tick's synthetic key `$TICK_<tick>`. Owner ruling 2026-10-12 (drift D-1).
|
|
843
|
-
*/
|
|
844
|
-
runTick?: {
|
|
845
|
-
trait: string;
|
|
846
|
-
tick: string;
|
|
847
|
-
};
|
|
848
|
-
/**
|
|
849
|
-
* Stateless addressing: the traits this dispatch runs against, each with
|
|
850
|
-
* the scope it dispatches `from` (a single-element array is the common
|
|
851
|
-
* case; a listens fan-out that crosses traits carries more than one). The
|
|
852
|
-
* compiled server is stateless-per-trait too (`handlers.rs:510-532` seeds
|
|
853
|
-
* state from `currentState`) — this generalizes that mechanism instead of
|
|
854
|
-
* the retired single `currentState`/`fields` pair. `event` is the event
|
|
855
|
-
* that trait fired on in a cascade (the seed's own is `event` above); where
|
|
856
|
-
* the leg runs follows it.
|
|
857
|
-
*/
|
|
858
|
-
traits?: Array<{
|
|
859
|
-
trait: string;
|
|
860
|
-
from: string;
|
|
861
|
-
event?: string;
|
|
862
|
-
}>;
|
|
863
|
-
/**
|
|
864
|
-
* The dispatching traits' current `@entity` frames (declared defaults <
|
|
865
|
-
* fetched row < `[shared]` frame), keyed by trait name. The server layers
|
|
866
|
-
* each row over the one it resolves via `resolveEntityView` so guards and
|
|
867
|
-
* effects read the same values the client does.
|
|
868
|
-
*/
|
|
869
|
-
entityByTrait?: Record<string, EntityRow>;
|
|
870
|
-
/** The orbital/behavior name this dispatch targets, for stateless multi-orbital addressing. */
|
|
871
|
-
behavior?: string;
|
|
872
|
-
/** `@event` for the target when this request continues a dispatch that began on the client; absent = a direct dispatch. */
|
|
873
|
-
delivery?: DeliveryRecord;
|
|
874
|
-
/** The target trait's log so far in that dispatch; absent = empty. */
|
|
875
|
-
dispatchLog?: DispatchLog;
|
|
876
|
-
/**
|
|
877
|
-
* A mount batch: one request mounts several traits of the orbital, each
|
|
878
|
-
* running its OWN lifecycle event, in list order, with the shared
|
|
879
|
-
* `payload`. `traits`/`entityByTrait` keep their stateless-addressing
|
|
880
|
-
* meaning; `event` carries the first seed's event.
|
|
881
|
-
*/
|
|
882
|
-
mount?: MountSeed[];
|
|
883
|
-
/** Where this leg runs, set by the kernel (EXEC-DIST-6): `browser` for browser-stored rows only, else `server`. */
|
|
884
|
-
residence?: 'browser' | 'server';
|
|
885
|
-
}
|
|
886
945
|
/** The lifecycle events a trait runs when it enters a page (the first it handles). */
|
|
887
|
-
/**
|
|
888
|
-
* Host-level UI events: handled by the app host, never by a trait, so a
|
|
889
|
-
* component inside a trait scope emits them bare (`UI:NAVIGATE`), not
|
|
890
|
-
* qualified to its trait. `NAVIGATE` moves the router; `SIGN_OUT` ends the
|
|
891
|
-
* viewer's session.
|
|
892
|
-
*/
|
|
893
|
-
declare const SYSTEM_UI_EVENTS: readonly ["NAVIGATE", "SIGN_OUT"];
|
|
894
|
-
type SystemUiEvent = (typeof SYSTEM_UI_EVENTS)[number];
|
|
895
|
-
declare function isSystemUiEvent(event: string): event is SystemUiEvent;
|
|
896
946
|
declare const LIFECYCLE_EVENTS: readonly ["INIT", "LOAD", "$MOUNT"];
|
|
897
947
|
/** Wire-only event a client sends when a trait leaves the page; the server stops counting it as mounted. */
|
|
898
948
|
declare const UNMOUNT_EVENT = "$UNMOUNT";
|
|
899
949
|
/** An event key without its `UI:` bus prefix. */
|
|
900
950
|
declare function normalizeEventKey(eventKey: string): string;
|
|
901
|
-
/** The event a tick firing carries on the wire (`
|
|
951
|
+
/** The event a tick firing carries on the wire (`EventRequest.event` of a `runTick` leg). */
|
|
902
952
|
declare function tickEventKey(tickName: string): string;
|
|
903
953
|
type LifecycleEvent = (typeof LIFECYCLE_EVENTS)[number];
|
|
904
954
|
/** One trait of a mount batch and the lifecycle event it runs. */
|
|
905
|
-
|
|
955
|
+
type MountSeed = {
|
|
906
956
|
trait: string;
|
|
907
957
|
event: LifecycleEvent;
|
|
908
|
-
}
|
|
958
|
+
};
|
|
909
959
|
declare const MountSeedSchema: z.ZodObject<{
|
|
910
960
|
trait: z.ZodString;
|
|
911
961
|
event: z.ZodEnum<{
|
|
@@ -914,23 +964,19 @@ declare const MountSeedSchema: z.ZodObject<{
|
|
|
914
964
|
$MOUNT: "$MOUNT";
|
|
915
965
|
}>;
|
|
916
966
|
}, z.core.$strip>;
|
|
917
|
-
/** Structured reason one trait (or the whole dispatch) did not transition. */
|
|
918
|
-
type TransitionRejectionCode = 'no-matching-transition' | 'guard-rejected' | 'no-dispatchable-traits' | 'not-an-external-input' | 'inbound-only-event'
|
|
919
|
-
/** An effect of the trait's transition threw; its later effects did not run. */
|
|
920
|
-
| 'effect-failed';
|
|
921
967
|
/**
|
|
922
968
|
* A request on the outside-client input channel (`POST /:orbital/inputs`): an
|
|
923
969
|
* API caller, an agent acting as the user, an MCP client. Only an event the
|
|
924
970
|
* target trait declares as an external input (`listens { EVENT -> external { … } }`)
|
|
925
971
|
* is dispatched; anything else is refused with `not-an-external-input`.
|
|
926
972
|
*/
|
|
927
|
-
|
|
973
|
+
type ExternalInputRequest = {
|
|
928
974
|
targetTrait: string;
|
|
929
975
|
event: string;
|
|
930
976
|
payload?: EventPayload;
|
|
931
977
|
user?: RawUserClaims;
|
|
932
978
|
entityId?: string;
|
|
933
|
-
}
|
|
979
|
+
};
|
|
934
980
|
type EventStreamItem = {
|
|
935
981
|
type: 'event';
|
|
936
982
|
data: EmittedEvent;
|
|
@@ -941,7 +987,7 @@ type EventStreamItem = {
|
|
|
941
987
|
timestamp: number;
|
|
942
988
|
} | {
|
|
943
989
|
type: 'complete';
|
|
944
|
-
data:
|
|
990
|
+
data: EventResponse;
|
|
945
991
|
timestamp: number;
|
|
946
992
|
} | {
|
|
947
993
|
type: 'error';
|
|
@@ -960,7 +1006,7 @@ declare const EventStreamItemSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
|
960
1006
|
timestamp: z.ZodNumber;
|
|
961
1007
|
}, z.core.$strip>, z.ZodObject<{
|
|
962
1008
|
type: z.ZodLiteral<"complete">;
|
|
963
|
-
data: z.
|
|
1009
|
+
data: z.ZodCustom<EventResponse, EventResponse>;
|
|
964
1010
|
timestamp: z.ZodNumber;
|
|
965
1011
|
}, z.core.$strip>, z.ZodObject<{
|
|
966
1012
|
type: z.ZodLiteral<"error">;
|
|
@@ -972,7 +1018,7 @@ declare const EventStreamItemSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
|
972
1018
|
/** How a host answered a `program/dispatch` event request: the response, or the route's failure code and status. */
|
|
973
1019
|
type DispatchRequestOutcome = {
|
|
974
1020
|
ok: true;
|
|
975
|
-
response:
|
|
1021
|
+
response: EventResponse;
|
|
976
1022
|
streamItems?: EventStreamItem[];
|
|
977
1023
|
} | {
|
|
978
1024
|
ok: false;
|
|
@@ -997,15 +1043,16 @@ interface ServiceHostPorts {
|
|
|
997
1043
|
inputs(): ExternalInput[];
|
|
998
1044
|
/** The entities `read` serves: every persisted entity of the program (`readableEntitiesOf`). */
|
|
999
1045
|
readableEntities(): string[];
|
|
1000
|
-
dispatchInput(orbital: string, request: Omit<ExternalInputRequest, 'user'>): Promise<
|
|
1046
|
+
dispatchInput(orbital: string, request: Omit<ExternalInputRequest, 'user'>): Promise<EventResponse>;
|
|
1001
1047
|
read(entity: string): Promise<EntityRow[]>;
|
|
1002
1048
|
/**
|
|
1003
1049
|
* A `program/dispatch` event request (owner, 2026-10-21): dispatch `request` on `orbital` as the HTTP events
|
|
1004
|
-
* route does (`input: true` admits only a declared external input, as the inputs route). `request
|
|
1005
|
-
* dispatch's viewer when the call names one.
|
|
1050
|
+
* route does (`input: true` admits only a declared external input, as the inputs route). `request` is what the kernel
|
|
1051
|
+
* parsed (`EventRequest::from_dispatch`); its `user` is the dispatch's viewer when the call names one.
|
|
1052
|
+
* A host that does not serve event requests leaves it out.
|
|
1006
1053
|
*/
|
|
1007
1054
|
supportsDispatchStream?: true;
|
|
1008
|
-
dispatchRequest?(orbital: string, request:
|
|
1055
|
+
dispatchRequest?(orbital: string, request: EventRequest, input: boolean, stream?: boolean): Promise<DispatchRequestOutcome>;
|
|
1009
1056
|
/** A `program/dispatch { inbound }` delivery through the inbound route, credential check and answer path. */
|
|
1010
1057
|
deliverInbound?(name: string, delivery: {
|
|
1011
1058
|
headers: Readonly<Record<string, string>>;
|
|
@@ -1016,6 +1063,8 @@ interface ServiceHostPorts {
|
|
|
1016
1063
|
}>;
|
|
1017
1064
|
/** The host's last `steps` traced dispatch steps, oldest first; a host that keeps no trace leaves it out. */
|
|
1018
1065
|
trace?(steps: number): JsonValue[];
|
|
1066
|
+
/** A `program/resolve-rows` ask: `reference` resolved for the identity bound to `clientId`'s session (none: the anonymous viewer), `@read` applied by the kernel's one resolver. */
|
|
1067
|
+
resolveRows?(reference: RowSetRef, clientId: string | undefined): Promise<RowQueryPage>;
|
|
1019
1068
|
/**
|
|
1020
1069
|
* Deliver one message of the running call to the caller's tab, live, as the
|
|
1021
1070
|
* call site's `emit.onMessage` event source-stamped to the caller. A no-op
|
|
@@ -1023,139 +1072,6 @@ interface ServiceHostPorts {
|
|
|
1023
1072
|
*/
|
|
1024
1073
|
message(payload: EventPayload): void;
|
|
1025
1074
|
}
|
|
1026
|
-
/**
|
|
1027
|
-
* Why a dispatched trait (or the whole request) did not transition —
|
|
1028
|
-
* G-RUNTIME-023. `statesDeclaringEvent` lists the states whose transition
|
|
1029
|
-
* table DOES declare the event, which makes a stale client-supplied `from`
|
|
1030
|
-
* self-explanatory in a stateless response.
|
|
1031
|
-
*/
|
|
1032
|
-
interface TransitionRejection {
|
|
1033
|
-
code: TransitionRejectionCode;
|
|
1034
|
-
trait?: string;
|
|
1035
|
-
from?: string;
|
|
1036
|
-
event?: string;
|
|
1037
|
-
statesDeclaringEvent?: string[];
|
|
1038
|
-
transition?: string;
|
|
1039
|
-
guard?: unknown;
|
|
1040
|
-
/** `effect-failed`: the thrown error's message. */
|
|
1041
|
-
error?: string;
|
|
1042
|
-
}
|
|
1043
|
-
/** How one authored effect of an executed hop ran. */
|
|
1044
|
-
type HopEffectStatus = 'executed' | 'failed' | 'skipped';
|
|
1045
|
-
/** One authored effect of a hop: its operator head, its arguments as authored, and how it ran. */
|
|
1046
|
-
interface HopEffect {
|
|
1047
|
-
type: string;
|
|
1048
|
-
args: SExpr[];
|
|
1049
|
-
status: HopEffectStatus;
|
|
1050
|
-
error?: string;
|
|
1051
|
-
}
|
|
1052
|
-
/**
|
|
1053
|
-
* One executed hop of a dispatch (the seed's, a same-trait cascade step's, a listener delivery's), in
|
|
1054
|
-
* dispatch order: what a `TransitionObserver` hears. `guardResult` is `true` when the fired arm's guard
|
|
1055
|
-
* held and absent for an unguarded arm.
|
|
1056
|
-
*/
|
|
1057
|
-
interface TransitionHop {
|
|
1058
|
-
trait: string;
|
|
1059
|
-
from: string;
|
|
1060
|
-
to: string;
|
|
1061
|
-
event: string;
|
|
1062
|
-
/** The arm that fired, by its position among the state's arms for the event. */
|
|
1063
|
-
firedArm?: number;
|
|
1064
|
-
guardResult?: boolean;
|
|
1065
|
-
effects: HopEffect[];
|
|
1066
|
-
/** The payload and `@entity` before and after the hop, when a verifier asked the kernel to record them. */
|
|
1067
|
-
observed?: HopObservation;
|
|
1068
|
-
}
|
|
1069
|
-
/**
|
|
1070
|
-
* One client effect paired with the trait that produced it and, when the
|
|
1071
|
-
* producer knows it, the transition that fired: that transition's own event
|
|
1072
|
-
* key (for a listens delivery, the triggered event, not the source emit) and
|
|
1073
|
-
* the state it fired from. A client stamps render provenance from these.
|
|
1074
|
-
*/
|
|
1075
|
-
interface ClientEffectByTrait {
|
|
1076
|
-
traitName: string;
|
|
1077
|
-
effect: ClientEffectTuple;
|
|
1078
|
-
event?: string;
|
|
1079
|
-
fromState?: string;
|
|
1080
|
-
/** The payload an embedded `@callsitePayload` child was composed with — sticky, so a later repaint of the child resolves its captures the same way. */
|
|
1081
|
-
callsitePayload?: EventPayload;
|
|
1082
|
-
/** Set when the paint is a repaint a renderer must act on beyond the content: the rows a reference in it points at changed (EXEC-RENDER-3). */
|
|
1083
|
-
repaint?: RepaintReason;
|
|
1084
|
-
}
|
|
1085
|
-
/**
|
|
1086
|
-
* Server → client event dispatch response. Mirrors the compiled path's
|
|
1087
|
-
* generated `EventResponse` (orbital-shell-typescript's `shared/types.ts`,
|
|
1088
|
-
* mirrored 1:1 in `orbital-core`'s `effects/response.rs`) — canonical = the
|
|
1089
|
-
* TS runtime's `OrbitalEventResponse` (`@almadar/runtime`'s
|
|
1090
|
-
* `OrbitalServerRuntime.ts`).
|
|
1091
|
-
*/
|
|
1092
|
-
interface OrbitalEventResponse {
|
|
1093
|
-
success: boolean;
|
|
1094
|
-
transitioned: boolean;
|
|
1095
|
-
/** Whole-orbital state snapshot, keyed by trait name. */
|
|
1096
|
-
states: Record<string, string>;
|
|
1097
|
-
/**
|
|
1098
|
-
* Events emitted during processing, in declaration order. ALWAYS present
|
|
1099
|
-
* (`[]` when none) — the compiled Hono path used to omit this field on a
|
|
1100
|
-
* no-cascade response, which forced every consumer to optional-chain a
|
|
1101
|
-
* field that is really always there.
|
|
1102
|
-
*
|
|
1103
|
-
* Each entry carries a `source: BusEventSource` so the client-side
|
|
1104
|
-
* ServerBridge can re-broadcast on the qualified `UI:Orbital.Trait.EVENT`
|
|
1105
|
-
* bus key. Without source the re-broadcast skips the entry and downstream
|
|
1106
|
-
* listeners (e.g. ContactBrowse waiting for ContactLoaded after a fetch)
|
|
1107
|
-
* never fire — the dashboard-layout that ContactLoaded renders disappears.
|
|
1108
|
-
*/
|
|
1109
|
-
emittedEvents: EmittedEvent[];
|
|
1110
|
-
/** Fetched/queried entity collections this response carries, keyed by entity name. */
|
|
1111
|
-
data?: Record<string, EntityRow[]>;
|
|
1112
|
-
/** Fetched pages delivered by reference (`deliver: ids`), keyed by entity name. */
|
|
1113
|
-
dataRefs?: Record<string, RowSetRef>;
|
|
1114
|
-
/**
|
|
1115
|
-
* `@entity` fields this transition's server-side `set` effects wrote,
|
|
1116
|
-
* post-effect, keyed by trait name — the response-side twin of the
|
|
1117
|
-
* request's `entityByTrait`. The client merges them over its own effect
|
|
1118
|
-
* results (server wins).
|
|
1119
|
-
*/
|
|
1120
|
-
entityByTrait?: Record<string, EntityRow>;
|
|
1121
|
-
/** Client-side effects to execute (render-ui, navigate). */
|
|
1122
|
-
clientEffects?: ClientEffectTuple[];
|
|
1123
|
-
/**
|
|
1124
|
-
* Same effects as `clientEffects`, paired with the producing trait name.
|
|
1125
|
-
* Consumers that need per-trait attribution (e.g. `<TraitFrame>` resolving
|
|
1126
|
-
* `@trait.X` bindings) read from this field; legacy consumers ignore it
|
|
1127
|
-
* and continue with the flat `clientEffects` array unchanged.
|
|
1128
|
-
*
|
|
1129
|
-
* Same length and ordering as `clientEffects`; entries are 1:1 by index.
|
|
1130
|
-
*/
|
|
1131
|
-
clientEffectsByTrait?: ClientEffectByTrait[];
|
|
1132
|
-
/** Results from server-side effects (persist, call-service, set). */
|
|
1133
|
-
effectResults?: ServerEffectResult[];
|
|
1134
|
-
/** Guard that failed, addressed as `"<Trait>.<event>"`, for debugging. */
|
|
1135
|
-
guardFailed?: string;
|
|
1136
|
-
/**
|
|
1137
|
-
* Structured per-trait / per-request rejection reasons (G-RUNTIME-023) —
|
|
1138
|
-
* present only when nothing transitioned. Supersedes the `guardFailed`
|
|
1139
|
-
* string (kept for backcompat) with a machine-readable shape.
|
|
1140
|
-
*/
|
|
1141
|
-
rejections?: TransitionRejection[];
|
|
1142
|
-
/**
|
|
1143
|
-
* Names of traits DROPPED from a stateless cascade because the cross-trait
|
|
1144
|
-
* worklist hit its safety-valve cap (G-RUNTIME-027) — the response's
|
|
1145
|
-
* states/effects/entity rows are INCOMPLETE for these traits. Absent when
|
|
1146
|
-
* the whole worklist ran. Surfaced so the truncation is observable
|
|
1147
|
-
* (previously the tail of any page over ~20 traits silently never
|
|
1148
|
-
* executed).
|
|
1149
|
-
*/
|
|
1150
|
-
cascadeTruncated?: string[];
|
|
1151
|
-
/** Every executed hop of the dispatch, in order (the server role's trace); absent when none ran. */
|
|
1152
|
-
transitions?: TransitionHop[];
|
|
1153
|
-
error?: string;
|
|
1154
|
-
}
|
|
1155
|
-
/** Zod twin of `OrbitalEventRequest`. Third type param `object`, see `BusEventSourceSchema`. */
|
|
1156
|
-
declare const OrbitalEventRequestSchema: z.ZodType<OrbitalEventRequest, object>;
|
|
1157
|
-
/** Zod twin of `OrbitalEventResponse`. Third type param `object`, see `BusEventSourceSchema`. */
|
|
1158
|
-
declare const OrbitalEventResponseSchema: z.ZodType<OrbitalEventResponse, object>;
|
|
1159
1075
|
/**
|
|
1160
1076
|
* Where circuit state lives between events (`docs/Almadar_Runtime_Stateless_Stateful_PLAN.md` §1a):
|
|
1161
1077
|
* `'stateless'` = the client carries it on every request, `'stateful'` = the server holds it.
|
|
@@ -1193,14 +1109,6 @@ interface LiveBroadcastItem {
|
|
|
1193
1109
|
}
|
|
1194
1110
|
/** Zod twin of `LiveBroadcastItem`. Third type param `object`, see `BusEventSourceSchema`. */
|
|
1195
1111
|
declare const LiveBroadcastItemSchema: z.ZodType<LiveBroadcastItem, object>;
|
|
1196
|
-
/** @deprecated use {@link OrbitalEventRequest}. Kept until every referrer migrates (Program A wave A8). */
|
|
1197
|
-
type EventDispatchRequest = OrbitalEventRequest;
|
|
1198
|
-
/** @deprecated use {@link OrbitalEventRequestSchema}. */
|
|
1199
|
-
declare const EventDispatchRequestSchema: z.ZodType<OrbitalEventRequest, object, z.core.$ZodTypeInternals<OrbitalEventRequest, object>>;
|
|
1200
|
-
/** @deprecated use {@link OrbitalEventResponse}. Kept until every referrer migrates (Program A wave A8). */
|
|
1201
|
-
type EventDispatchResponse = OrbitalEventResponse;
|
|
1202
|
-
/** @deprecated use {@link OrbitalEventResponseSchema}. */
|
|
1203
|
-
declare const EventDispatchResponseSchema: z.ZodType<OrbitalEventResponse, object, z.core.$ZodTypeInternals<OrbitalEventResponse, object>>;
|
|
1204
1112
|
|
|
1205
|
-
export {
|
|
1206
|
-
export type {
|
|
1113
|
+
export { PayloadJsonSchemaSchema as $, ANONYMOUS_USER as A, InboundFoundSchema as G, HostAskCompletionSchema as H, InboundOnlySchema as J, InboundRouteSchema as M, LIFECYCLE_EVENTS as N, LiveBroadcastItemSchema as Q, MountSeedSchema as S, NameListSchema as T, OptionalNameSchema as W, OrbitalRegisterResponseSchema as Y, PayloadIssueSchema as _, ROW_SET_MARKER as a3, RawUserClaimsSchema as a5, UNMOUNT_EVENT as aA, ViewerSchema as aD, createLazyService as aF, createTypedEventBus as aG, findPersonaInRoster as aH, isRowSetMarker as aI, normalizeEventKey as aJ, normalizeUserContext as aK, personaFromIdentityRow as aL, resolvePersonaSpec as aM, rowSetMarker as aN, tickEventKey as aO, RowSetRefSchema as aj, ServerTopologySchema as ar, BusEventSourceSchema as d, ClientEffectTupleSchema as e, ClientHostAskTupleSchema as g, ClientNavigateBackTupleSchema as i, ClientNavigateTupleSchema as k, ClientRenderUITupleSchema as m, DeliveryRecordSchema as n, DispatchLogSchema as p, EmittedEventSchema as r, EventStreamItemSchema as v, ExternalInputSchema as y, InboundAnswerSchema as z };
|
|
1114
|
+
export type { BusEvent as B, ClientEffectTuple as C, DeliveryRecord as D, EventStreamItem as E, InboundDelivery as F, InboundAnswer as I, InboundRoute as K, LiveBroadcastItem as L, LazyService as O, LifecycleEvent as P, MountSeed as R, UserContext as U, OperatorValueKinds as V, OrbitalRegisterResponse as X, PayloadIssue as Z, EmittedEvent as a, PersistActionName as a0, PersistenceAdapter as a1, QueryCapabilities as a2, RawUserClaims as a4, RowCommit as a6, RowCommitWrite as a7, RowCompareOp as a8, RowIdPage as a9, Unsubscribe as aB, ViewerAuthority as aC, WriteCapabilities as aE, RowOperator as aa, RowOrder as ab, RowPage as ac, RowPageRequest as ad, RowPredicate as ae, RowQuery as af, RowQueryPage as ag, RowSetMarker as ah, RowSetRef as ai, RowTotalMode as ak, RowValueKind as al, RowWriteBatch as am, RowWriteFailureMode as an, RowWriteOp as ao, RowWriteOutcome as ap, ServerTopology as aq, ServiceAction as as, ServiceActionName as at, ServiceContract as au, ServiceEvents as av, ServiceHostPorts as aw, StoreContract as ax, StoreFilter as ay, StoreFilterOp as az, BusEventListener as b, BusEventSource as c, ClientHostAskTuple as f, ClientNavigateBackTuple as h, ClientNavigateTuple as j, ClientRenderUITuple as l, DispatchLog as o, DispatchRequestOutcome as q, EventEmit as s, EventKey as t, EventListen as u, ExternalInput as w, ExternalInputRequest as x };
|