@almadar/core 10.96.0 → 10.99.0

package/dist/bus-BGDM3Xot.d.ts

@@ -0,0 +1,565 @@
+import { F as FieldValue, S as ServerReportedEffect, N as NamespacedEffectName, g as EntityRow, d as OrbitalId, T as TraitId, b as EventId, h as PatternConfig, i as ResolvedPatternProps, A as AnyPatternConfig } from './effect-CW_IT0Jn.js';
+import { z } from 'zod';
+import { a as EventPayloadValue, b as EventPayload } from './expression-DRwzVnMu.js';
+
+/**
+ * Authenticated user context — what `@user.x` resolves against.
+ *
+ * The canonical shape for the `user` binding root, shared by both execution
+ * paths: the JS interpreter resolves `@user.id` through
+ * `EvaluationContext.user`, and the compiled shell emits `user?.id` against the
+ * `UserContext` its `@app/shared` re-exports from here.
+ *
+ * `id` is the field the behavior library reads for ownership scoping and `role`
+ * the field it reads for capability gating. Auth providers that name the subject
+ * `uid` must normalize at their boundary — {@link normalizeUserContext} does that.
+ *
+ * @packageDocumentation
+ */
+
+/** Authenticated user / agent identity behind `@user.x` bindings. */
+interface UserContext {
+    /** Stable subject identifier. `@user.id` — the ownership key. */
+    id: string;
+    /** `@user.email` */
+    email?: string;
+    /** `@user.name` — display name. */
+    name?: string;
+    /** `@user.role` — single role string, compared against a policy's allowed list. */
+    role?: string;
+    /** `@user.permissions` — fine-grained capability strings. */
+    permissions?: string[];
+    /** Additional provider claims, readable as `@user.<claim>`. */
+    [key: string]: FieldValue | undefined;
+}
+/**
+ * The identity of an unauthenticated viewer. A resolvable object rather than
+ * `undefined` so a role predicate evaluates to a definite `false` instead of
+ * comparing against nothing.
+ */
+declare const ANONYMOUS_USER: UserContext;
+/** Provider-shaped identity claims, before normalization. */
+interface RawUserClaims {
+    id?: string;
+    uid?: string;
+    email?: string | null;
+    name?: string;
+    displayName?: string | null;
+    role?: string;
+    permissions?: string[];
+    [key: string]: FieldValue | undefined;
+}
+/** Zod twin of `RawUserClaims` — the wire shape of `OrbitalEventRequest.user`. */
+declare const RawUserClaimsSchema: z.ZodType<RawUserClaims>;
+/**
+ * Normalize provider claims into a {@link UserContext}.
+ *
+ * Firebase (and most OIDC providers) name the subject `uid` and the display name
+ * `displayName`, while every `.lolo` behavior reads `@user.id` / `@user.name`.
+ * Without this normalization `@user.id` is `undefined` against a fully
+ * authenticated request and every ownership filter silently matches no rows.
+ * `uid` is preserved so `@user.uid` keeps working.
+ *
+ * Returns `undefined` for absent or subject-less claims so callers can
+ * distinguish "no auth ran" from "anonymous"; use {@link ANONYMOUS_USER} where a
+ * definite identity is required.
+ */
+declare function normalizeUserContext(claims: RawUserClaims | null | undefined): UserContext | undefined;
+/**
+ * Turn a row of an app's `[identity]` entity into a viewer.
+ *
+ * There is no separate persona shape: an identity row IS the persona
+ * (`Almadar_LOLO_Identity.md` §4.3), so this only guards the one field the
+ * behavior library requires — a non-empty string `id` — and passes every other
+ * declared field through as a `@user.<field>` claim. Rows without a usable id
+ * yield `undefined` rather than a persona nobody can own rows as.
+ */
+declare function personaFromIdentityRow(row: Record<string, FieldValue | undefined>): UserContext | undefined;
+/**
+ * The viewer a host presents when nothing named one.
+ *
+ * Without this, `@user` is `Null` in headless verify and preview, so every
+ * `viewerName: @user.name` binding renders blank and the account menu never
+ * appears — an app that cannot say who you are. Worse, an ownership filter that
+ * works and one that is broken both render an empty table.
+ *
+ * `role` is deliberately EMPTY, not a guess. A default of `admin` would silently
+ * flip which branch renders at the 38 `@user.role` comparisons in the corpus;
+ * an empty role matches no literal, exactly as `Null` did, so this fixes
+ * "undefined at runtime" without changing a single guard outcome.
+ */
+declare const DEFAULT_VIEWER: UserContext;
+/**
+ * The viewer to present an app as when nothing named one.
+ *
+ * `DEFAULT_VIEWER` is synthetic — `viewer-1` is in no app's roster — so under it
+ * every ownership predicate (`@entity.<owner> == @user.id`) matches zero rows and
+ * a correctly-scoped app renders empty tables everywhere. That is indistinguishable
+ * on screen from a broken filter, which is exactly the failure DEFAULT_VIEWER's own
+ * comment warns about.
+ *
+ * So when the app declares an `[identity]` roster, the default viewer is a REAL
+ * member of it. `DEFAULT_VIEWER` remains the fallback for apps that declare no
+ * identity entity, where there is nobody to be.
+ *
+ * Both execution paths share this rule; the Rust twin is
+ * `orbital-core::runtime::persona::resolve_default_viewer`.
+ */
+declare function resolveDefaultViewer(roster: readonly UserContext[]): UserContext;
+/** Look a persona up in a roster by id, or by role when no id matches. */
+declare function findPersonaInRoster(roster: readonly UserContext[], idOrRole: string): UserContext | undefined;
+/**
+ * Resolve a persona spec — a bare id/role (`Person Id 3`, `moderator`) or a full
+ * JSON `UserContext` — into a viewer. This is the `ALMADAR_PERSONA` contract,
+ * shared by every host that presents an app as somebody.
+ *
+ * The roster is the app's OWN declared personas — the seeded rows of its
+ * `[identity]` entity (`Almadar_LOLO_Identity.md` §4.3) — supplied by the host
+ * that has them in hand (the runtime's live store on the interpreter path, the
+ * schema-derived seed rows on the compiled path). There is no global roster:
+ * an app without an `[identity]` entity resolves only JSON-form specs.
+ *
+ * Throws on anything unresolvable rather than returning `undefined`: "no persona"
+ * and "persona silently ignored" look identical on screen, so a bad spec must
+ * fail at boot instead of rendering as nobody.
+ */
+declare function resolvePersonaSpec(spec: string, roster: readonly UserContext[]): UserContext;
+/**
+ * Marks a bearer token as a mocked dev identity rather than a real ID token.
+ * The prefix is deliberately unmistakable: a server accepts these ONLY behind an
+ * explicit dev opt-in, so a production deployment rejects them like any other
+ * malformed token.
+ */
+declare const DEV_TOKEN_PREFIX = "almadar-dev.";
+/**
+ * Encode a viewer as a dev bearer token.
+ *
+ * Carries the WHOLE identity, not just the subject: real Firebase claims have no
+ * `role`, so a server that only reads `uid` leaves every `@user.role` gate inert
+ * even for a signed-in user. URI-encoded JSON keeps the token header-safe (no
+ * spaces or delimiters) and works unchanged in Node and the browser.
+ */
+declare function encodeDevIdentityToken(user: UserContext): string;
+/**
+ * Decode a dev bearer token back into a viewer, or `undefined` if it is not one
+ * / is malformed — callers fail closed rather than inventing an identity.
+ */
+declare function decodeDevIdentityToken(token: string): UserContext | undefined;
+
+/**
+ * Server-side effect result — the wire shape a server-executed effect
+ * (`SERVER_REPORTED_EFFECTS` in `effect.ts`) reports back to the client,
+ * closing the circuit on `OrbitalEventResponse.effectResults`.
+ *
+ * Promoted from `@almadar/runtime`'s `ServerEffectHandlers.ts` (the JS
+ * interpreter's own definition, canonical per `CLAUDE.md`'s "converge on
+ * the TypeScript implementation" ruling) so `@almadar/core` owns the one
+ * shape both execution paths report against.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Result entry recorded for each effect invocation. Mirrors the server
+ * runtime's `EffectResult`. Callers who want telemetry pass an array that
+ * the factory appends to; otherwise it's unused.
+ */
+interface ServerBatchSummary {
+    operations: EntityRow[];
+    completedCount: number;
+    totalCount: number;
+}
+/** Zod twin of `ServerBatchSummary`. */
+declare const ServerBatchSummarySchema: z.ZodType<ServerBatchSummary>;
+interface ServerEffectResult {
+    /**
+     * The reported effect's head (`SERVER_REPORTED_EFFECTS`, derived from the
+     * effect union in `effect.ts`), or `"substrate"` — the one wire grouping
+     * for the namespaced operators (`trace/*`, `memory/*`, `session/*`,
+     * `behavior/*`, `compose/*`), whose head rides `name`.
+     */
+    effect: ServerReportedEffect | "substrate";
+    action?: string;
+    entityType?: string;
+    /** The invoked namespaced operator (e.g. `"memory/store"`), set only on `effect: "substrate"`. */
+    name?: NamespacedEffectName;
+    /** Entity row for CRUD/set/swap, the batch summary for `persist batch`, the raw service/substrate result. */
+    data?: EntityRow | ServerBatchSummary | EventPayloadValue;
+    success: boolean;
+    /**
+     * Set when a persist failed because an access policy rejected it or the
+     * write resolved no row key — mirrors `OrbitalServerRuntime.EffectResult`
+     * so the offline-preview and real-server persist paths report the same
+     * denial discriminator to the verification trace.
+     */
+    denied?: true;
+    error?: string;
+    /** Coded failure reason for a persist that resolved no target row. */
+    code?: "not-found" | "no-row-key";
+}
+/** Zod twin of `ServerEffectResult`. */
+declare const ServerEffectResultSchema: z.ZodType<ServerEffectResult>;
+
+/**
+ * Declared event key. A trait's event names (INIT, SAVE, CLOSE,
+ * CONFIRM_REMOVE, ...) flow through the orbital schema and the UI as
+ * strings; this alias marks "this string is a declared event key, not
+ * arbitrary text."
+ *
+ * Component props typed as `EventKey` are detected by the pattern-sync
+ * tool (`tools/almadar-pattern-sync/parser.ts`) via a TS-type lookup and
+ * marked as `kind: "event"` in the patterns registry
+ * (`@almadar/patterns`). Consumers of the registry — the Rust compiler's
+ * inline phase and the `@almadar/runtime` preprocess — read that marker
+ * to apply call-site `events: { OLD: NEW }` renames to render-ui trees
+ * without name-matching heuristics.
+ *
+ * Plain alias over `string`. Not branded because event keys originate
+ * from user data at runtime (orb schema literals, bus emits), so cast
+ * friction would buy nothing. The value of the alias is at the type
+ * surface — it's a marker the pattern-sync tool can find via
+ * `getSymbolAtLocation`.
+ */
+type EventKey = string;
+/**
+ * Phantom-typed brand for declarative bus-emit props on UI components.
+ *
+ * Used by component authors to BOTH mark a prop as a bus-event reference
+ * AND document the payload shape that the component will fire onto the
+ * bus when that prop is bound. Authors write:
+ *
+ *     // Tabs.tsx
+ *     export interface TabsProps {
+ *       tabChangeEvent?: EventEmit<{ tabId: string }>;
+ *     }
+ *
+ * Consumers see only the structural `string` (no UX impact: passing a
+ * literal `"TAB_CHANGED"` keeps working). The phantom `P` parameter
+ * carries the bus-payload schema at the type level for pattern-sync to
+ * extract.
+ *
+ * Pattern-sync (`tools/almadar-pattern-sync/parser.ts`) detects this
+ * brand via TS type-lookup (mirrors how it detects `EventKey`) and
+ * writes two registry fields per prop:
+ * - `kind: "event-ref"` — the discriminant rules read in lolo / orb
+ *   validator to know "this prop's string value is a bus event name."
+ * - `emitPayloadSchema` — the structural shape of `P`, serialized as
+ *   the same JSON-Schema-shaped record Almadar uses for trait
+ *   `payloadSchema`. Validator rules cross-check this against the
+ *   trait's declared `emits { EVENT { ... } }` payload to catch mismatches
+ *   at parse / validate time instead of runtime.
+ *
+ * Example payload bus emission inside the component (no wrapper —
+ * `EventEmit<P>` erases to `string`):
+ *
+ *     if (tabChangeEvent) eventBus.emit(`UI:${tabChangeEvent}`, { tabId });
+ *
+ * The brand is structurally an unused optional readonly property; TS
+ * never asks for it at construction, so authors and consumers never
+ * see it.
+ */
+type EventEmit<P> = string & {
+    readonly __emitPayload?: P;
+};
+/**
+ * Phantom-typed brand for declarative bus-listen props on UI components.
+ *
+ * Mirror of `EventEmit<P>`. Used by future patterns where a UI component
+ * subscribes to a bus event and forwards its payload upward via prop
+ * (e.g. an editor pattern that listens for `EXTERNAL_RESET` and exposes
+ * the consumed payload to the parent). Pattern-sync detects this brand
+ * the same way as `EventEmit<P>` and writes:
+ * - `kind: "event-listen"` (or a sub-discriminant of `event-ref`)
+ * - `listenPayloadSchema` with the structural shape of `P`
+ *
+ * Validator rules use this to verify the trait the prop is bound to
+ * actually emits a payload of the expected shape.
+ *
+ * Reserved for symmetry; no @almadar/ui component uses it as of this
+ * commit. Add usages incrementally as patterns require them.
+ */
+type EventListen<P> = string & {
+    readonly __listenPayload?: P;
+};
+/**
+ * Identifies the origin of a bus event. Used by cross-trait listeners to
+ * filter emits from specific orbitals, traits, transitions, or ticks.
+ *
+ * `transition` and `tick` are optional runtime-internal details; most
+ * consumers only care about `orbital` and `trait`.
+ */
+interface BusEventSource {
+    orbital?: string;
+    /** V4 dual-carry id sibling of `orbital` — stable across an orbital rename. */
+    orbitalId?: OrbitalId;
+    trait?: string;
+    /** V4 dual-carry id sibling of `trait` — stable across a trait rename. */
+    traitId?: TraitId;
+    /** V4 dual-carry id of the emitted event — stable across an event rename. */
+    eventId?: EventId;
+    transition?: string;
+    tick?: string;
+    /**
+     * True when the orbital bridge re-broadcasts an event onto the bus
+     * (any source — both echoes of the dispatched event and server-side
+     * cascade emits via `(emit X)` / `fetch.emit.success`). Cross-trait
+     * listeners filter on this flag so the click-time qualified emit
+     * (which has no `fromBridge`) doesn't double-fire alongside the
+     * post-server bridge confirmation. See `dispatched` for the narrower
+     * "echo of the just-dispatched event" signal.
+     */
+    fromBridge?: boolean;
+    /**
+     * True ONLY for bridge echoes the receiving tab already processed, so
+     * the originating trait's self-subscription skips them instead of
+     * re-dispatching its own echo (infinite loop / double execution).
+     * Set by path 1 of useOrbitalBridge (compiled shell — echo of the
+     * just-dispatched event; server-side cascade emits there carry
+     * `fromBridge: true` but NOT `dispatched`, so they still reach the
+     * source trait's transition handler, e.g. `loading -> browsing` on a
+     * fetch's `emit.success`) and by ServerBridge (runtime path — stamped
+     * on exactly one response-cascade echo per event the dispatch delivered
+     * locally on the bare key, `stampLocallyDeliveredEchoes`; server-only
+     * results stay unstamped). Cross-trait `listens` never filter on this
+     * flag, so their delivery is unaffected. Push-leg events from OTHER
+     * tabs (multiplayer) are never stamped.
+     */
+    dispatched?: boolean;
+    /**
+     * The client that originated the dispatch whose effects emitted this
+     * event (from `OrbitalEventRequest.clientId`); absent for headless
+     * dispatches (ticks, circuit-router probes, walkers). The server-side
+     * listens fan-out skips client-originated cascade emits — under dual
+     * execution the originating client relays every cascade hop through the
+     * bridge itself, so the server dispatching the same hop double-ran it
+     * (one Send persisted two rows). Headless topology keeps the fan-out:
+     * there is no client to drive the circuit.
+     */
+    originClientId?: string;
+}
+/** Zod twin of `BusEventSource`. */
+declare const BusEventSourceSchema: z.ZodType<BusEventSource, z.ZodTypeDef, object>;
+/**
+ * An event flowing on the bus.
+ *
+ * The `source` field is structured so cross-trait listeners can match
+ * `event.source?.orbital === 'X' && event.source?.trait === 'Y'` without
+ * parsing a delimiter.
+ */
+interface BusEvent {
+    /** Event type identifier (e.g., 'CartItemLoaded', 'TASK_COMPLETED') */
+    type: EventKey;
+    /** Optional structured payload */
+    payload?: EventPayload;
+    /** Timestamp when the event was emitted */
+    timestamp: number;
+    /** Optional origin info for filtering */
+    source?: BusEventSource;
+}
+/** Bus event listener callback. */
+type BusEventListener = (event: BusEvent) => void;
+/** Returned by `on()` / `once()` to detach a listener. */
+type Unsubscribe = () => void;
+/**
+ * One event a transition's effects emitted, carried back to the client to
+ * re-dispatch (in order) so the state machine advances through the
+ * cascade without server-side recursion. Named/shaped to match the
+ * generated compiled-path `EmittedEvent` (orbital-shell-typescript's
+ * `shared/types.ts`) so the two execution paths agree on one shape.
+ */
+interface EmittedEvent {
+    event: string;
+    payload?: EventPayload;
+    source?: BusEventSource;
+}
+/** Zod twin of `EmittedEvent`. Third type param `object`, see `BusEventSourceSchema`. */
+declare const EmittedEventSchema: z.ZodType<EmittedEvent, z.ZodTypeDef, object>;
+/**
+ * Client-side effect tuple shipped in `OrbitalEventResponse.clientEffects`.
+ * Restricted to the effect kinds the client knows how to apply to the
+ * UI: render-ui (slot mutation, including the `toast` slot that carries
+ * what used to be the separate notify effect) and navigate (route change).
+ * Server-only effects (persist, set, fetch, ...) execute on the server and
+ * surface their results via `effectResults` and `emittedEvents`, not here.
+ *
+ * Shape note: the wire form is broader than `RenderUIEffect` /
+ * `NavigateEffect` from `@almadar/core/types/effect.ts` in two places — the
+ * runtime appends an interpolated `props` object plus an optional `priority`
+ * slot to render-ui (slot 4 + 5), and `navigate`'s optional argument may
+ * surface as `undefined` rather than absent. The local union spells those
+ * variants out explicitly so consumers (ServerBridge.tsx parser, debugger
+ * inspector) get accurate completions instead of `unknown[]`.
+ *
+ * `slot` is a plain `string` in this wire shape (not `UISlot`'s literal
+ * union) because the runtime forwards the raw string from the trait's
+ * `(render-ui slot ...)` SExpr without re-validating against the registry —
+ * registry validation lives in `orbital validate` / `lolo` parse, not here.
+ */
+type ClientRenderUITuple = ['render-ui', string, PatternConfig | null] | ['render-ui', string, PatternConfig | null, ResolvedPatternProps] | ['render-ui', string, PatternConfig | null, ResolvedPatternProps | undefined, number | undefined];
+type ClientNavigateTuple = ['navigate', string] | ['navigate', string, Record<string, string> | undefined] | ['navigate', string, Record<string, string> | undefined, {
+    crumb?: string;
+}];
+type ClientNavigateBackTuple = ['navigate-back'];
+type ClientEffectTuple = ClientRenderUITuple | ClientNavigateTuple | ClientNavigateBackTuple;
+/** Zod twin of `ClientRenderUITuple` — one variant per fixed arity (3/4/5), unioned. */
+declare const ClientRenderUITupleSchema: z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"render-ui">, z.ZodString, z.ZodType<AnyPatternConfig | null, z.ZodTypeDef, AnyPatternConfig | null>], null>, z.ZodTuple<[z.ZodLiteral<"render-ui">, z.ZodString, z.ZodType<AnyPatternConfig | null, z.ZodTypeDef, AnyPatternConfig | null>, z.ZodType<ResolvedPatternProps, z.ZodTypeDef, ResolvedPatternProps>], null>, z.ZodTuple<[z.ZodLiteral<"render-ui">, z.ZodString, z.ZodType<AnyPatternConfig | null, z.ZodTypeDef, AnyPatternConfig | null>, z.ZodOptional<z.ZodType<ResolvedPatternProps, z.ZodTypeDef, ResolvedPatternProps>>, z.ZodOptional<z.ZodNumber>], null>]>;
+/** Zod twin of `ClientNavigateTuple` — one variant per fixed arity (2/3/4), unioned. */
+declare const ClientNavigateTupleSchema: z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"navigate">, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"navigate">, z.ZodString, z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>], null>, z.ZodTuple<[z.ZodLiteral<"navigate">, z.ZodString, z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>, z.ZodObject<{
+    crumb: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    crumb?: string | undefined;
+}, {
+    crumb?: string | undefined;
+}>], null>]>;
+/** Zod twin of `ClientNavigateBackTuple`. */
+declare const ClientNavigateBackTupleSchema: z.ZodTuple<[z.ZodLiteral<"navigate-back">], null>;
+/** Zod twin of `ClientEffectTuple`. */
+declare const ClientEffectTupleSchema: z.ZodType<ClientEffectTuple>;
+/**
+ * Client → server event dispatch request. The single upstream owner of
+ * this shape — both the JS interpreter (`@almadar/runtime`'s
+ * `OrbitalEventRequest`) and the compiled path's generated `EventRequest`
+ * (orbital-shell-typescript's `shared/types.ts`, mirrored 1:1 in
+ * `orbital-core`) carry the same fields, so the two execution paths cannot
+ * drift.
+ */
+interface OrbitalEventRequest {
+    event: string;
+    /**
+     * V4 dual-carry id sibling of `event` — the fired event's id, when known
+     * (e.g. threaded from a `listens[].triggersId`). Optional; absent means
+     * the state machine dispatches by name only (legacy).
+     */
+    eventId?: EventId;
+    payload?: EventPayload;
+    entityId?: string;
+    /**
+     * Scoped-listen delivery: dispatch to THIS trait only. A listens-matched
+     * trigger is addressed to the listening trait; without this, a trigger
+     * renamed to INIT broadcast orbital-wide and re-ran every trait's
+     * initializer (R-SCOPED-LISTEN-INIT-RENAME-FREEZE re-fire cascade).
+     */
+    targetTrait?: string;
+    /** Provider claims for `@user` bindings, normalized by `normalizeUserContext`. */
+    user?: RawUserClaims;
+    /** Per-tab client identity (UUID) — excludes this request's origin from live-broadcast delivery. */
+    clientId?: string;
+    /**
+     * Broadcast-class marker (T6, docs/Almadar_Tick_Loop.md §3a): the name of
+     * the tick that emitted this event. Tick-stamped dispatches are
+     * latest-state broadcasts — the client fires them without awaiting the
+     * response, and the server relays them to OTHER tabs coalesced
+     * (newest-per-key) at a snapshot rate instead of 1:1.
+     */
+    tick?: string;
+    /** Emitting trait for a tick-stamped dispatch — builds the relay's BusEventSource (sourceless emits are dropped client-side). */
+    sourceTrait?: string;
+    /**
+     * Stateless addressing: the traits this dispatch runs against, each with
+     * the scope it dispatches `from` (a single-element array is the common
+     * case; a listens fan-out that crosses traits carries more than one). The
+     * compiled server is stateless-per-trait too (`handlers.rs:510-532` seeds
+     * state from `currentState`) — this generalizes that mechanism instead of
+     * the retired single `currentState`/`fields` pair.
+     */
+    traits?: Array<{
+        trait: string;
+        from: string;
+    }>;
+    /**
+     * The dispatching traits' current `@entity` frames (declared defaults <
+     * fetched row < `[shared]` frame), keyed by trait name. The server layers
+     * each row over the one it resolves via `resolveEntityView` so guards and
+     * effects read the same values the client does.
+     */
+    entityByTrait?: Record<string, EntityRow>;
+    /** The orbital/behavior name this dispatch targets, for stateless multi-orbital addressing. */
+    behavior?: string;
+}
+/**
+ * Server → client event dispatch response. Mirrors the compiled path's
+ * generated `EventResponse` (orbital-shell-typescript's `shared/types.ts`,
+ * mirrored 1:1 in `orbital-core`'s `effects/response.rs`) — canonical = the
+ * TS runtime's `OrbitalEventResponse` (`@almadar/runtime`'s
+ * `OrbitalServerRuntime.ts`).
+ */
+interface OrbitalEventResponse {
+    success: boolean;
+    transitioned: boolean;
+    /** Whole-orbital state snapshot, keyed by trait name. */
+    states: Record<string, string>;
+    /**
+     * Events emitted during processing, in declaration order. ALWAYS present
+     * (`[]` when none) — the compiled Hono path used to omit this field on a
+     * no-cascade response, which forced every consumer to optional-chain a
+     * field that is really always there.
+     *
+     * Each entry carries a `source: BusEventSource` so the client-side
+     * ServerBridge can re-broadcast on the qualified `UI:Orbital.Trait.EVENT`
+     * bus key. Without source the re-broadcast skips the entry and downstream
+     * listeners (e.g. ContactBrowse waiting for ContactLoaded after a fetch)
+     * never fire — the dashboard-layout that ContactLoaded renders disappears.
+     */
+    emittedEvents: EmittedEvent[];
+    /** Fetched/queried entity collections this response carries, keyed by entity name. */
+    data?: Record<string, EntityRow[]>;
+    /**
+     * `@entity` fields this transition's server-side `set` effects wrote,
+     * post-effect, keyed by trait name — the response-side twin of the
+     * request's `entityByTrait`. The client merges them over its own effect
+     * results (server wins).
+     */
+    entityByTrait?: Record<string, EntityRow>;
+    /** Client-side effects to execute (render-ui, navigate). */
+    clientEffects?: ClientEffectTuple[];
+    /**
+     * Same effects as `clientEffects`, paired with the producing trait name.
+     * Consumers that need per-trait attribution (e.g. `<TraitFrame>` resolving
+     * `@trait.X` bindings) read from this field; legacy consumers ignore it
+     * and continue with the flat `clientEffects` array unchanged.
+     *
+     * Same length and ordering as `clientEffects`; entries are 1:1 by index.
+     */
+    clientEffectsByTrait?: Array<{
+        traitName: string;
+        effect: ClientEffectTuple;
+    }>;
+    /** Results from server-side effects (persist, call-service, set). */
+    effectResults?: ServerEffectResult[];
+    /** Guard that failed, addressed as `"<Trait>.<event>"`, for debugging. */
+    guardFailed?: string;
+    error?: string;
+}
+/** Zod twin of `OrbitalEventRequest`. Third type param `object`, see `BusEventSourceSchema`. */
+declare const OrbitalEventRequestSchema: z.ZodType<OrbitalEventRequest, z.ZodTypeDef, object>;
+/** Zod twin of `OrbitalEventResponse`. Third type param `object`, see `BusEventSourceSchema`. */
+declare const OrbitalEventResponseSchema: z.ZodType<OrbitalEventResponse, z.ZodTypeDef, object>;
+/**
+ * One persist-envelope success emit, handed to the live-broadcast sink
+ * (`OrbitalServerRuntime.setLiveBroadcastSink`) and relayed to every OTHER
+ * connected client. Fired only from the `persist` effect's `emit:{success}`
+ * envelope (batch and single-op) — never from the generic emit funnel — so
+ * transport layers can fan it out without matching on event names. Promoted
+ * from `@almadar/runtime`'s own `LiveBroadcastItem` (canonical per Program
+ * A's "converge on the TS runtime" ruling) so `orbital-server`'s `GET
+ * /api/events` broadcast mirrors the same shape.
+ */
+interface LiveBroadcastItem {
+    event: string;
+    payload?: EventPayload;
+    source: BusEventSource;
+    /** `clientId` of the request that produced this emit; excluded from delivery by the transport. */
+    originClientId?: string;
+}
+/** Zod twin of `LiveBroadcastItem`. Third type param `object`, see `BusEventSourceSchema`. */
+declare const LiveBroadcastItemSchema: z.ZodType<LiveBroadcastItem, z.ZodTypeDef, object>;
+/** @deprecated use {@link OrbitalEventRequest}. Kept until every referrer migrates (Program A wave A8). */
+type EventDispatchRequest = OrbitalEventRequest;
+/** @deprecated use {@link OrbitalEventRequestSchema}. */
+declare const EventDispatchRequestSchema: z.ZodType<OrbitalEventRequest, z.ZodTypeDef, object>;
+/** @deprecated use {@link OrbitalEventResponse}. Kept until every referrer migrates (Program A wave A8). */
+type EventDispatchResponse = OrbitalEventResponse;
+/** @deprecated use {@link OrbitalEventResponseSchema}. */
+declare const EventDispatchResponseSchema: z.ZodType<OrbitalEventResponse, z.ZodTypeDef, object>;
+
+export { ANONYMOUS_USER as A, type BusEvent as B, type ClientEffectTuple as C, DEFAULT_VIEWER as D, type EmittedEvent as E, ServerEffectResultSchema as F, type Unsubscribe as G, decodeDevIdentityToken as H, encodeDevIdentityToken as I, findPersonaInRoster as J, normalizeUserContext as K, type LiveBroadcastItem as L, personaFromIdentityRow as M, resolveDefaultViewer as N, type OrbitalEventRequest as O, resolvePersonaSpec as P, type RawUserClaims as R, type ServerBatchSummary as S, type UserContext as U, type OrbitalEventResponse as a, type BusEventListener as b, type BusEventSource as c, BusEventSourceSchema as d, ClientEffectTupleSchema as e, type ClientNavigateBackTuple as f, ClientNavigateBackTupleSchema as g, type ClientNavigateTuple as h, ClientNavigateTupleSchema as i, type ClientRenderUITuple as j, ClientRenderUITupleSchema as k, DEV_TOKEN_PREFIX as l, EmittedEventSchema as m, type EventDispatchRequest as n, EventDispatchRequestSchema as o, type EventDispatchResponse as p, EventDispatchResponseSchema as q, type EventEmit as r, type EventKey as s, type EventListen as t, LiveBroadcastItemSchema as u, OrbitalEventRequestSchema as v, OrbitalEventResponseSchema as w, RawUserClaimsSchema as x, ServerBatchSummarySchema as y, type ServerEffectResult as z };