@almadar/core 10.129.0 → 11.0.0
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-BhnofAik.d.ts} +5966 -7116
- package/dist/builders.d.ts +6 -6
- package/dist/builders.js +7 -6
- package/dist/{bus-CcbB__oo.d.ts → bus-BrRFWDQK.d.ts} +270 -354
- package/dist/chunk-347APWFM.js +286 -0
- package/dist/chunk-347APWFM.js.map +1 -0
- package/dist/chunk-3URQAGD7.js +98 -0
- package/dist/chunk-3URQAGD7.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-KDMV222Q.js → chunk-F6KHUW7T.js} +304 -373
- package/dist/chunk-F6KHUW7T.js.map +1 -0
- package/dist/chunk-FGT5OS2Y.js +918 -0
- package/dist/chunk-FGT5OS2Y.js.map +1 -0
- package/dist/chunk-FQLEAMAB.js +24 -0
- package/dist/chunk-FQLEAMAB.js.map +1 -0
- package/dist/chunk-HEXOGHQ4.js +3264 -0
- package/dist/chunk-HEXOGHQ4.js.map +1 -0
- package/dist/chunk-JCD6GLBX.js +412 -0
- package/dist/chunk-JCD6GLBX.js.map +1 -0
- package/dist/{chunk-QUOTJULD.js → chunk-MGLG2XLD.js} +20 -219
- package/dist/chunk-MGLG2XLD.js.map +1 -0
- package/dist/chunk-MTBEBSNO.js +1293 -0
- package/dist/chunk-MTBEBSNO.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-UZPYYI37.js} +524 -26
- package/dist/{chunk-RYPVOI6H.js.map → chunk-UZPYYI37.js.map} +1 -1
- package/dist/chunk-VG7BRFUD.js +152 -0
- package/dist/chunk-VG7BRFUD.js.map +1 -0
- package/dist/chunk-Y2DYZPP5.js +2329 -0
- package/dist/chunk-Y2DYZPP5.js.map +1 -0
- package/dist/chunk-ZEI7C32D.js +1566 -0
- package/dist/chunk-ZEI7C32D.js.map +1 -0
- package/dist/{domain-Dz3jP-UM.d.ts → domain-CfKPpXCP.d.ts} +51 -51
- package/dist/{effect-result-Bebwu9yT.d.ts → effect-result-DPERsn_v.d.ts} +641 -851
- package/dist/{effect-CiEVLsZz.d.ts → effect-wP-IdRt2.d.ts} +236 -443
- 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-DomgmRBG.d.ts} +29 -729
- package/dist/index.d.ts +69 -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 +1205 -1215
- 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/index.d.ts +24 -120
- package/dist/patterns/index.js +3 -3
- package/dist/patterns/patterns-registry.json +522 -24
- package/dist/patterns/registry.json +522 -24
- package/dist/trait-CzG9M89M.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-BHlTjwWd.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.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-wP-IdRt2.js';
|
|
4
|
+
import { V as Viewer, a as EventResponse, E as EventRequest } from './effect-result-DPERsn_v.js';
|
|
5
|
+
import { P as PayloadField } from './trait-CzG9M89M.js';
|
|
6
|
+
import { J as JsonSchema } from './types-BHlTjwWd.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,64 @@ 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
|
+
* The return address of a `host-ask` that declared `emit` routes (EXEC-DIST-13): the host answers once by dispatching
|
|
918
|
+
* the event of the outcome it reached to `trait` (on `entityId` when the frame is a row); an absent route fires nothing.
|
|
919
|
+
*/
|
|
920
|
+
type HostAskCompletion = {
|
|
921
|
+
trait: string;
|
|
922
|
+
entityId?: string;
|
|
923
|
+
key?: string;
|
|
924
|
+
success?: string;
|
|
925
|
+
failure?: string;
|
|
926
|
+
};
|
|
927
|
+
type ClientEffectTuple = ClientRenderUITuple | ClientNavigateTuple | ClientNavigateBackTuple | ClientHostAskTuple;
|
|
783
928
|
/** Zod twin of `ClientRenderUITuple`. */
|
|
784
|
-
declare const ClientRenderUITupleSchema: z.ZodTuple<[z.ZodLiteral<"render-ui">, z.ZodString, z.ZodType<
|
|
929
|
+
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
930
|
/** Zod twin of `ClientNavigateTuple` — one variant per fixed arity (2/3/4), unioned. */
|
|
786
931
|
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
932
|
crumb: z.ZodOptional<z.ZodString>;
|
|
788
933
|
}, z.core.$strip>], null>]>;
|
|
789
934
|
/** Zod twin of `ClientNavigateBackTuple`. */
|
|
790
935
|
declare const ClientNavigateBackTupleSchema: z.ZodTuple<[z.ZodLiteral<"navigate-back">], null>;
|
|
936
|
+
/** Zod twin of `ClientHostAskTuple`. */
|
|
937
|
+
declare const HostAskCompletionSchema: z.ZodObject<{
|
|
938
|
+
trait: z.ZodString;
|
|
939
|
+
entityId: z.ZodOptional<z.ZodString>;
|
|
940
|
+
key: z.ZodOptional<z.ZodString>;
|
|
941
|
+
success: z.ZodOptional<z.ZodString>;
|
|
942
|
+
failure: z.ZodOptional<z.ZodString>;
|
|
943
|
+
}, z.core.$strict>;
|
|
944
|
+
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<{
|
|
945
|
+
trait: z.ZodString;
|
|
946
|
+
entityId: z.ZodOptional<z.ZodString>;
|
|
947
|
+
key: z.ZodOptional<z.ZodString>;
|
|
948
|
+
success: z.ZodOptional<z.ZodString>;
|
|
949
|
+
failure: z.ZodOptional<z.ZodString>;
|
|
950
|
+
}, z.core.$strict>], null>]>;
|
|
791
951
|
/** Zod twin of `ClientEffectTuple`. */
|
|
792
952
|
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
953
|
/** 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
954
|
declare const LIFECYCLE_EVENTS: readonly ["INIT", "LOAD", "$MOUNT"];
|
|
897
955
|
/** Wire-only event a client sends when a trait leaves the page; the server stops counting it as mounted. */
|
|
898
956
|
declare const UNMOUNT_EVENT = "$UNMOUNT";
|
|
899
957
|
/** An event key without its `UI:` bus prefix. */
|
|
900
958
|
declare function normalizeEventKey(eventKey: string): string;
|
|
901
|
-
/** The event a tick firing carries on the wire (`
|
|
959
|
+
/** The event a tick firing carries on the wire (`EventRequest.event` of a `runTick` leg). */
|
|
902
960
|
declare function tickEventKey(tickName: string): string;
|
|
903
961
|
type LifecycleEvent = (typeof LIFECYCLE_EVENTS)[number];
|
|
904
962
|
/** One trait of a mount batch and the lifecycle event it runs. */
|
|
905
|
-
|
|
963
|
+
type MountSeed = {
|
|
906
964
|
trait: string;
|
|
907
965
|
event: LifecycleEvent;
|
|
908
|
-
}
|
|
966
|
+
};
|
|
909
967
|
declare const MountSeedSchema: z.ZodObject<{
|
|
910
968
|
trait: z.ZodString;
|
|
911
969
|
event: z.ZodEnum<{
|
|
@@ -914,23 +972,19 @@ declare const MountSeedSchema: z.ZodObject<{
|
|
|
914
972
|
$MOUNT: "$MOUNT";
|
|
915
973
|
}>;
|
|
916
974
|
}, 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
975
|
/**
|
|
922
976
|
* A request on the outside-client input channel (`POST /:orbital/inputs`): an
|
|
923
977
|
* API caller, an agent acting as the user, an MCP client. Only an event the
|
|
924
978
|
* target trait declares as an external input (`listens { EVENT -> external { … } }`)
|
|
925
979
|
* is dispatched; anything else is refused with `not-an-external-input`.
|
|
926
980
|
*/
|
|
927
|
-
|
|
981
|
+
type ExternalInputRequest = {
|
|
928
982
|
targetTrait: string;
|
|
929
983
|
event: string;
|
|
930
984
|
payload?: EventPayload;
|
|
931
985
|
user?: RawUserClaims;
|
|
932
986
|
entityId?: string;
|
|
933
|
-
}
|
|
987
|
+
};
|
|
934
988
|
type EventStreamItem = {
|
|
935
989
|
type: 'event';
|
|
936
990
|
data: EmittedEvent;
|
|
@@ -941,7 +995,7 @@ type EventStreamItem = {
|
|
|
941
995
|
timestamp: number;
|
|
942
996
|
} | {
|
|
943
997
|
type: 'complete';
|
|
944
|
-
data:
|
|
998
|
+
data: EventResponse;
|
|
945
999
|
timestamp: number;
|
|
946
1000
|
} | {
|
|
947
1001
|
type: 'error';
|
|
@@ -960,7 +1014,7 @@ declare const EventStreamItemSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
|
960
1014
|
timestamp: z.ZodNumber;
|
|
961
1015
|
}, z.core.$strip>, z.ZodObject<{
|
|
962
1016
|
type: z.ZodLiteral<"complete">;
|
|
963
|
-
data: z.
|
|
1017
|
+
data: z.ZodCustom<EventResponse, EventResponse>;
|
|
964
1018
|
timestamp: z.ZodNumber;
|
|
965
1019
|
}, z.core.$strip>, z.ZodObject<{
|
|
966
1020
|
type: z.ZodLiteral<"error">;
|
|
@@ -972,7 +1026,7 @@ declare const EventStreamItemSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
|
972
1026
|
/** How a host answered a `program/dispatch` event request: the response, or the route's failure code and status. */
|
|
973
1027
|
type DispatchRequestOutcome = {
|
|
974
1028
|
ok: true;
|
|
975
|
-
response:
|
|
1029
|
+
response: EventResponse;
|
|
976
1030
|
streamItems?: EventStreamItem[];
|
|
977
1031
|
} | {
|
|
978
1032
|
ok: false;
|
|
@@ -997,15 +1051,16 @@ interface ServiceHostPorts {
|
|
|
997
1051
|
inputs(): ExternalInput[];
|
|
998
1052
|
/** The entities `read` serves: every persisted entity of the program (`readableEntitiesOf`). */
|
|
999
1053
|
readableEntities(): string[];
|
|
1000
|
-
dispatchInput(orbital: string, request: Omit<ExternalInputRequest, 'user'>): Promise<
|
|
1054
|
+
dispatchInput(orbital: string, request: Omit<ExternalInputRequest, 'user'>): Promise<EventResponse>;
|
|
1001
1055
|
read(entity: string): Promise<EntityRow[]>;
|
|
1002
1056
|
/**
|
|
1003
1057
|
* 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.
|
|
1058
|
+
* route does (`input: true` admits only a declared external input, as the inputs route). `request` is what the kernel
|
|
1059
|
+
* parsed (`EventRequest::from_dispatch`); its `user` is the dispatch's viewer when the call names one.
|
|
1060
|
+
* A host that does not serve event requests leaves it out.
|
|
1006
1061
|
*/
|
|
1007
1062
|
supportsDispatchStream?: true;
|
|
1008
|
-
dispatchRequest?(orbital: string, request:
|
|
1063
|
+
dispatchRequest?(orbital: string, request: EventRequest, input: boolean, stream?: boolean): Promise<DispatchRequestOutcome>;
|
|
1009
1064
|
/** A `program/dispatch { inbound }` delivery through the inbound route, credential check and answer path. */
|
|
1010
1065
|
deliverInbound?(name: string, delivery: {
|
|
1011
1066
|
headers: Readonly<Record<string, string>>;
|
|
@@ -1016,6 +1071,8 @@ interface ServiceHostPorts {
|
|
|
1016
1071
|
}>;
|
|
1017
1072
|
/** The host's last `steps` traced dispatch steps, oldest first; a host that keeps no trace leaves it out. */
|
|
1018
1073
|
trace?(steps: number): JsonValue[];
|
|
1074
|
+
/** 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. */
|
|
1075
|
+
resolveRows?(reference: RowSetRef, clientId: string | undefined): Promise<RowQueryPage>;
|
|
1019
1076
|
/**
|
|
1020
1077
|
* Deliver one message of the running call to the caller's tab, live, as the
|
|
1021
1078
|
* call site's `emit.onMessage` event source-stamped to the caller. A no-op
|
|
@@ -1023,139 +1080,6 @@ interface ServiceHostPorts {
|
|
|
1023
1080
|
*/
|
|
1024
1081
|
message(payload: EventPayload): void;
|
|
1025
1082
|
}
|
|
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
1083
|
/**
|
|
1160
1084
|
* Where circuit state lives between events (`docs/Almadar_Runtime_Stateless_Stateful_PLAN.md` §1a):
|
|
1161
1085
|
* `'stateless'` = the client carries it on every request, `'stateful'` = the server holds it.
|
|
@@ -1193,14 +1117,6 @@ interface LiveBroadcastItem {
|
|
|
1193
1117
|
}
|
|
1194
1118
|
/** Zod twin of `LiveBroadcastItem`. Third type param `object`, see `BusEventSourceSchema`. */
|
|
1195
1119
|
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
1120
|
|
|
1205
|
-
export {
|
|
1206
|
-
export type {
|
|
1121
|
+
export { PayloadIssueSchema as $, ANONYMOUS_USER as A, InboundAnswerSchema as F, InboundFoundSchema as J, InboundOnlySchema as K, InboundRouteSchema as N, LIFECYCLE_EVENTS as O, LiveBroadcastItemSchema as R, MountSeedSchema as T, NameListSchema as V, OptionalNameSchema as X, OrbitalRegisterResponseSchema as Z, PayloadJsonSchemaSchema as a0, ROW_SET_MARKER as a4, RawUserClaimsSchema as a6, UNMOUNT_EVENT as aB, ViewerSchema as aE, createLazyService as aG, createTypedEventBus as aH, findPersonaInRoster as aI, isRowSetMarker as aJ, normalizeEventKey as aK, normalizeUserContext as aL, personaFromIdentityRow as aM, resolvePersonaSpec as aN, rowSetMarker as aO, tickEventKey as aP, RowSetRefSchema as ak, ServerTopologySchema as as, 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, HostAskCompletionSchema as z };
|
|
1122
|
+
export type { BusEvent as B, ClientEffectTuple as C, DeliveryRecord as D, EventStreamItem as E, InboundDelivery as G, HostAskCompletion as H, InboundAnswer as I, LiveBroadcastItem as L, InboundRoute as M, LazyService as P, LifecycleEvent as Q, MountSeed as S, UserContext as U, OperatorValueKinds as W, OrbitalRegisterResponse as Y, PayloadIssue as _, EmittedEvent as a, PersistActionName as a1, PersistenceAdapter as a2, QueryCapabilities as a3, RawUserClaims as a5, RowCommit as a7, RowCommitWrite as a8, RowCompareOp as a9, StoreFilterOp as aA, Unsubscribe as aC, ViewerAuthority as aD, WriteCapabilities as aF, RowIdPage as aa, RowOperator as ab, RowOrder as ac, RowPage as ad, RowPageRequest as ae, RowPredicate as af, RowQuery as ag, RowQueryPage as ah, RowSetMarker as ai, RowSetRef as aj, RowTotalMode as al, RowValueKind as am, RowWriteBatch as an, RowWriteFailureMode as ao, RowWriteOp as ap, RowWriteOutcome as aq, ServerTopology as ar, ServiceAction as at, ServiceActionName as au, ServiceContract as av, ServiceEvents as aw, ServiceHostPorts as ax, StoreContract as ay, StoreFilter 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 };
|