@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.
Files changed (135) hide show
  1. package/dist/behavior-package.d.ts +49 -11
  2. package/dist/behavior-package.js +1 -1
  3. package/dist/{orbital-CkFdDS9f.d.ts → builders-BdgbY7Th.d.ts} +5828 -6917
  4. package/dist/builders.d.ts +6 -6
  5. package/dist/builders.js +7 -6
  6. package/dist/{bus-CcbB__oo.d.ts → bus-C0hFDNFR.d.ts} +262 -354
  7. package/dist/chunk-347APWFM.js +286 -0
  8. package/dist/chunk-347APWFM.js.map +1 -0
  9. package/dist/chunk-5WQ3U7NJ.js +2363 -0
  10. package/dist/chunk-5WQ3U7NJ.js.map +1 -0
  11. package/dist/chunk-5YTPYMPZ.js +99 -0
  12. package/dist/chunk-5YTPYMPZ.js.map +1 -0
  13. package/dist/chunk-66Q5VX2F.js +3810 -0
  14. package/dist/chunk-66Q5VX2F.js.map +1 -0
  15. package/dist/chunk-7GHJU5WI.js +39 -0
  16. package/dist/chunk-7GHJU5WI.js.map +1 -0
  17. package/dist/chunk-B4MNHGBP.js +8 -0
  18. package/dist/chunk-B4MNHGBP.js.map +1 -0
  19. package/dist/chunk-E4T2MQAV.js +24 -0
  20. package/dist/chunk-E4T2MQAV.js.map +1 -0
  21. package/dist/chunk-ENOCKYGA.js +412 -0
  22. package/dist/chunk-ENOCKYGA.js.map +1 -0
  23. package/dist/chunk-FGT5OS2Y.js +918 -0
  24. package/dist/chunk-FGT5OS2Y.js.map +1 -0
  25. package/dist/chunk-GF7KCLNR.js +3284 -0
  26. package/dist/chunk-GF7KCLNR.js.map +1 -0
  27. package/dist/chunk-PNGFWLHD.js +1567 -0
  28. package/dist/chunk-PNGFWLHD.js.map +1 -0
  29. package/dist/{chunk-X4SC7FGF.js → chunk-RGACZEYC.js} +99 -96
  30. package/dist/chunk-RGACZEYC.js.map +1 -0
  31. package/dist/{chunk-RYPVOI6H.js → chunk-SNZYN7UA.js} +2541 -433
  32. package/dist/{chunk-RYPVOI6H.js.map → chunk-SNZYN7UA.js.map} +1 -1
  33. package/dist/{chunk-KDMV222Q.js → chunk-TDNQT3M3.js} +304 -373
  34. package/dist/chunk-TDNQT3M3.js.map +1 -0
  35. package/dist/chunk-VG7BRFUD.js +152 -0
  36. package/dist/chunk-VG7BRFUD.js.map +1 -0
  37. package/dist/chunk-Z7BI7DE7.js +1293 -0
  38. package/dist/chunk-Z7BI7DE7.js.map +1 -0
  39. package/dist/{domain-Dz3jP-UM.d.ts → domain-Cpmja5ak.d.ts} +55 -55
  40. package/dist/{effect-CiEVLsZz.d.ts → effect-DZaXwSAz.d.ts} +283 -453
  41. package/dist/{effect-result-Bebwu9yT.d.ts → effect-result-1HpXgeBc.d.ts} +656 -851
  42. package/dist/{expression-D0Fs0riG.d.ts → expression-DirYKz-f.d.ts} +5 -13
  43. package/dist/factory/index.d.ts +7 -144
  44. package/dist/factory/index.js +8 -8
  45. package/dist/factory-runtime/index.d.ts +7 -6
  46. package/dist/factory-runtime/index.js +527 -8
  47. package/dist/factory-runtime/index.js.map +1 -1
  48. package/dist/fixtures.d.ts +9 -11
  49. package/dist/fixtures.js +12 -8
  50. package/dist/fixtures.js.map +1 -1
  51. package/dist/i18n/index.d.ts +15 -19
  52. package/dist/i18n/index.js +2 -1
  53. package/dist/{index-BC-Jycqj.d.ts → index-D7SxwNdv.d.ts} +34 -734
  54. package/dist/index.d.ts +92 -247
  55. package/dist/index.js +322 -986
  56. package/dist/index.js.map +1 -1
  57. package/dist/kernel-wire.d.ts +3 -3
  58. package/dist/kernel-wire.js +3 -79
  59. package/dist/kernel-wire.js.map +1 -1
  60. package/dist/language/constructs.json +22 -2
  61. package/dist/language/program-types.json +203 -22
  62. package/dist/language/protocols.json +46 -0
  63. package/dist/language/ui-vocabulary.json +1697 -0
  64. package/dist/language/validation-codes.json +1222 -1212
  65. package/dist/language/vocabulary.json +44 -8
  66. package/dist/language-data.d.ts +7 -4
  67. package/dist/language-data.js +20 -14
  68. package/dist/language-data.js.map +1 -1
  69. package/dist/patterns/component-mapping.json +11 -1
  70. package/dist/patterns/definitions.d.ts +2 -2
  71. package/dist/patterns/definitions.js +1 -1
  72. package/dist/patterns/event-contracts.json +1 -15
  73. package/dist/patterns/game-font-families.json +13 -0
  74. package/dist/patterns/index.d.ts +24 -120
  75. package/dist/patterns/index.js +3 -3
  76. package/dist/patterns/pattern-tile-geometry.json +1065 -0
  77. package/dist/patterns/patterns-registry.json +2539 -431
  78. package/dist/patterns/registry.json +2539 -431
  79. package/dist/trait-sRjIivFq.d.ts +3519 -0
  80. package/dist/types/index.d.ts +9 -10
  81. package/dist/types/index.js +11 -5
  82. package/dist/{types-DGwrltUF.d.ts → types-C6_yPMpn.d.ts} +3 -3
  83. package/fixtures/events-wire/client-effects-by-trait/response.json +0 -18
  84. package/fixtures/events-wire/client-effects-provenance/response.json +0 -18
  85. package/fixtures/events-wire/effect-results-every-kind/response.json +2 -27
  86. package/fixtures/events-wire/navigate-1/response.json +8 -5
  87. package/fixtures/events-wire/navigate-2/response.json +11 -8
  88. package/fixtures/events-wire/navigate-3/response.json +14 -11
  89. package/fixtures/events-wire/navigate-back/response.json +7 -4
  90. package/fixtures/events-wire/render-ui-3/response.json +12 -9
  91. package/fixtures/events-wire/render-ui-clear/response.json +0 -7
  92. package/fixtures/events-wire/sse-stream/response.json +0 -20
  93. package/fixtures/events-wire/sse-stream/stream.json +0 -20
  94. package/fixtures/events-wire/stateless-traits/response.json +14 -5
  95. package/fixtures/kernel-wire/golden/basic-entity.json +1687 -0
  96. package/fixtures/kernel-wire/golden/entity-rerender.json +743 -0
  97. package/fixtures/kernel-wire/golden/rollback.json +793 -0
  98. package/fixtures/kernel-wire/golden/tick-counter.json +1538 -0
  99. package/fixtures/kernel-wire/golden/two-orbital-chore.json +847 -0
  100. package/fixtures/kernel-wire/golden/two-orbital-task.json +457 -0
  101. package/fixtures/kernel-wire/played-step.json +136 -0
  102. package/fixtures/kernel-wire/scripts/basic-entity.json +28 -0
  103. package/fixtures/kernel-wire/scripts/entity-rerender.json +13 -0
  104. package/fixtures/kernel-wire/scripts/rollback.json +53 -0
  105. package/fixtures/kernel-wire/scripts/tick-counter.json +26 -0
  106. package/fixtures/kernel-wire/scripts/two-orbital-chore.json +9 -0
  107. package/fixtures/kernel-wire/scripts/two-orbital-task.json +9 -0
  108. package/package.json +28 -19
  109. package/dist/builders-DmZE5By0.d.ts +0 -2663
  110. package/dist/chunk-45I2O4SJ.js +0 -4646
  111. package/dist/chunk-45I2O4SJ.js.map +0 -1
  112. package/dist/chunk-6LR43Z5E.js +0 -3061
  113. package/dist/chunk-6LR43Z5E.js.map +0 -1
  114. package/dist/chunk-GIUA3NUJ.js +0 -809
  115. package/dist/chunk-GIUA3NUJ.js.map +0 -1
  116. package/dist/chunk-GTY53NS5.js +0 -1908
  117. package/dist/chunk-GTY53NS5.js.map +0 -1
  118. package/dist/chunk-JOHDVS6J.js +0 -1614
  119. package/dist/chunk-JOHDVS6J.js.map +0 -1
  120. package/dist/chunk-KDMV222Q.js.map +0 -1
  121. package/dist/chunk-QRHJUS3D.js +0 -23
  122. package/dist/chunk-QRHJUS3D.js.map +0 -1
  123. package/dist/chunk-QUOTJULD.js +0 -4009
  124. package/dist/chunk-QUOTJULD.js.map +0 -1
  125. package/dist/chunk-V5VNGRVU.js +0 -66
  126. package/dist/chunk-V5VNGRVU.js.map +0 -1
  127. package/dist/chunk-X4SC7FGF.js.map +0 -1
  128. package/dist/entityAccess-BPSz1i2n.d.ts +0 -80
  129. package/dist/mock/index.d.ts +0 -153
  130. package/dist/mock/index.js +0 -190
  131. package/dist/mock/index.js.map +0 -1
  132. package/dist/schema-T5RT5s6H.d.ts +0 -282
  133. package/dist/state-machine/index.d.ts +0 -359
  134. package/dist/state-machine/index.js +0 -3
  135. package/dist/state-machine/index.js.map +0 -1
@@ -1,10 +1,9 @@
1
1
  import { z } from 'zod';
2
- import { b as EventPayloadValue, E as EventPayload, L as LogMeta, R as RuntimeValue, S as SExpr, J as JsonValue } from './expression-D0Fs0riG.js';
3
- import { F as FieldValue, d as EntityRow, f as ServiceParams, b as OrbitalId, T as TraitId, c as EventId, P as PatternConfig, A as AnyPatternConfig } from './effect-CiEVLsZz.js';
4
- import { R as RepaintReason, S as ServerEffectResult, H as HopObservation, a as RawUserClaims } from './effect-result-Bebwu9yT.js';
5
- import { O as OrbitalSchema } from './schema-T5RT5s6H.js';
6
- import { P as PayloadField } from './orbital-CkFdDS9f.js';
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
- interface RowPageRequest<T> {
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
- interface RowPage<T> {
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
- interface RowOrder {
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
- interface RowNearest {
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
- interface RowQuery {
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
- interface OperatorValueKinds {
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
- interface QueryCapabilities {
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
- interface RowIdPage {
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
- interface RowWriteBatch {
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
- interface WriteCapabilities {
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
- interface RowCommit {
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
- interface RowSetRef {
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
- * Declared inputs — the events a client outside the program (an API
497
- * caller, an agent acting as the user, an MCP client) may send a trait. Authored
498
- * as `listens { EVENT -> input { … } }`, lowered onto the trait's own
499
- * `stateMachine.events[]` entry as `input: true`. The one owner of that list:
500
- * hosts gate their input channel with it, and clients build their tool lists
501
- * from it. Mirrors `orbital-core/src/runtime/external_inputs.rs`.
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
- * An event written with `listens` addressing (`EVENT`, `Trait.EVENT`,
508
- * `Orbital.Trait.EVENT`) as a value. A service contract param of this type is
509
- * checked by `orb validate` against the program's declared external inputs.
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 EventAddress = string;
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 entities a `call-service` provider acting as the caller may read: every
524
- * persisted entity, once, in schema order. Rows stay filtered by each entity's
525
- * `@read` policy at read time. Mirrors the compiled host's `ENTITY_READS`
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
- declare function readableEntitiesOf(schema: OrbitalSchema): string[];
529
- declare function findExternalInput(schema: OrbitalSchema, orbital: string, trait: string, event: string): ExternalInput | undefined;
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 declared input a `listens`-addressed event names, resolved from the
532
- * calling trait's position: `EVENT` is that trait's own, `Trait.EVENT` a trait
533
- * of its orbital, `Orbital.Trait.EVENT` any orbital. Mirrors the L2 rule in
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 function findInputByAddress(inputs: readonly ExternalInput[], address: string, caller: {
537
- orbital: string;
538
- trait: string;
539
- }): ExternalInput | undefined;
540
- /** A declared payload as the JSON Schema of one object — what a tool-calling model fills. */
541
- declare function payloadSchemaToJsonSchema(fields: readonly PayloadField[]): JsonSchema;
542
- /** One way a value misses its declared payload. */
543
- interface PayloadIssue {
544
- readonly path: string;
545
- readonly reason: 'missing' | 'unknown' | 'wrong-type' | 'not-one-of';
546
- readonly expected?: string;
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
- * Check a value against a declared payload: required fields, primitive and container types,
550
- * closed value sets, declared object shapes (closed) at any depth. An object field without
551
- * declared properties stays open; a type with no JSON shape (`node`, an entity name) is not
552
- * checked beyond its container.
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
- interface BusEventSource {
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 `OrbitalEventRequest.clientId`); absent for headless
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
- interface DeliveryRecord {
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
- interface DispatchLog {
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
- interface BusEvent {
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
- interface EmittedEvent {
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 `OrbitalEventResponse.clientEffects`.
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, PatternConfig | null];
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
- type ClientEffectTuple = ClientRenderUITuple | ClientNavigateTuple | ClientNavigateBackTuple;
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<AnyPatternConfig | null, unknown, z.core.$ZodTypeInternals<AnyPatternConfig | null, unknown>>], null>;
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 (`OrbitalEventRequest.event` of a `runTick` leg). */
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
- interface MountSeed {
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
- interface ExternalInputRequest {
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: OrbitalEventResponse;
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.ZodLazy<z.ZodType<OrbitalEventResponse, object, z.core.$ZodTypeInternals<OrbitalEventResponse, object>>>;
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: OrbitalEventResponse;
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<OrbitalEventResponse>;
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.user` is the
1005
- * dispatch's viewer when the call names one. A host that does not serve event requests leaves it out.
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: OrbitalEventRequest, input: boolean, stream?: boolean): Promise<DispatchRequestOutcome>;
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 { EventStreamItemSchema as A, LIFECYCLE_EVENTS as J, LiveBroadcastItemSchema as N, MountSeedSchema as Q, OrbitalEventRequestSchema as S, OrbitalEventResponseSchema as T, OrbitalRegisterResponseSchema as V, ROW_SET_MARKER as _, createLazyService as aB, createTypedEventBus as aC, deliveryRecordValue as aD, externalInputsOf as aE, findExternalInput as aF, findInputByAddress as aG, isRowSetMarker as aH, isSystemUiEvent as aI, normalizeEventKey as aJ, payloadIssues as aK, payloadSchemaToJsonSchema as aL, readableEntitiesOf as aM, rowSetMarker as aN, tickEventKey as aO, RowSetRefSchema as ac, SYSTEM_UI_EVENTS as aj, ServerTopologySchema as al, UNMOUNT_EVENT as ay, BusEventSourceSchema as e, ClientEffectTupleSchema as g, ClientNavigateBackTupleSchema as i, ClientNavigateTupleSchema as k, ClientRenderUITupleSchema as m, DeliveryRecordSchema as n, DispatchLogSchema as p, EmittedEventSchema as r, EventDispatchRequestSchema as u, EventDispatchResponseSchema as w };
1206
- export type { RowCommit as $, BusEvent as B, ClientEffectTuple as C, DeliveryRecord as D, EventStreamItem as E, ExternalInput as F, ExternalInputRequest as G, HopEffect as H, HopEffectStatus as I, LazyService as K, LiveBroadcastItem as L, LifecycleEvent as M, OrbitalEventRequest as O, MountSeed as P, OperatorValueKinds as R, OrbitalRegisterResponse as U, PayloadIssue as W, PersistActionName as X, PersistenceAdapter as Y, QueryCapabilities as Z, OrbitalEventResponse as a, RowCommitWrite as a0, RowCompareOp as a1, RowIdPage as a2, RowOperator as a3, RowOrder as a4, RowPage as a5, RowPageRequest as a6, RowPredicate as a7, RowQuery as a8, RowQueryPage as a9, WriteCapabilities as aA, RowSetMarker as aa, RowSetRef as ab, RowTotalMode as ad, RowValueKind as ae, RowWriteBatch as af, RowWriteFailureMode as ag, RowWriteOp as ah, RowWriteOutcome as ai, ServerTopology as ak, ServiceAction as am, ServiceActionName as an, ServiceContract as ao, ServiceEvents as ap, ServiceHostPorts as aq, StoreContract as ar, StoreFilter as as, StoreFilterOp as at, SystemUiEvent as au, TransitionHop as av, TransitionRejection as aw, TransitionRejectionCode as ax, Unsubscribe as az, EmittedEvent as b, BusEventListener as c, BusEventSource as d, ClientEffectByTrait as f, ClientNavigateBackTuple as h, ClientNavigateTuple as j, ClientRenderUITuple as l, DispatchLog as o, DispatchRequestOutcome as q, EventAddress as s, EventDispatchRequest as t, EventDispatchResponse as v, EventEmit as x, EventKey as y, EventListen as z };
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 };