@almadar/core 11.0.0 → 11.1.0

package/dist/{chunk-3URQAGD7.js → chunk-5YTPYMPZ.js}

@@ -1,4 +1,4 @@
-import { isEventResponse } from './chunk-MTBEBSNO.js';
+import { isEventResponse } from './chunk-Z7BI7DE7.js';
 import { EventPayloadSchema } from './chunk-347APWFM.js';
 import { EventIdSchema, TraitIdSchema, OrbitalIdSchema } from './chunk-VG7BRFUD.js';
 import { JsonValueSchema } from './chunk-7GHJU5WI.js';
@@ -50,7 +50,8 @@ var HostAskCompletionSchema = z.object({
   entityId: z.string().optional(),
   key: z.string().optional(),
   success: z.string().optional(),
-  failure: z.string().optional()
+  failure: z.string().optional(),
+  onMessage: z.string().optional()
 }).strict();
 var ClientHostAskTupleSchema = z.union([
   z.tuple([z.literal("host-ask"), z.string(), z.array(JsonValueSchema)]),
@@ -94,5 +95,5 @@ var LiveBroadcastItemSchema = z.object({
 });
 
 export { BusEventSourceSchema, ClientEffectTupleSchema, ClientHostAskTupleSchema, ClientNavigateBackTupleSchema, ClientNavigateTupleSchema, ClientRenderUITupleSchema, DeliveryRecordSchema, DispatchLogSchema, EmittedEventSchema, EventStreamItemSchema, HostAskCompletionSchema, LIFECYCLE_EVENTS, LiveBroadcastItemSchema, MountSeedSchema, OrbitalRegisterResponseSchema, ServerTopologySchema, UNMOUNT_EVENT, normalizeEventKey, tickEventKey };
-//# sourceMappingURL=chunk-3URQAGD7.js.map
-//# sourceMappingURL=chunk-3URQAGD7.js.map
+//# sourceMappingURL=chunk-5YTPYMPZ.js.map
+//# sourceMappingURL=chunk-5YTPYMPZ.js.map

package/dist/chunk-5YTPYMPZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types/bus.ts"],"names":[],"mappings":"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","file":"chunk-5YTPYMPZ.js","sourcesContent":["/**\n * Bus Event Types (framework concept)\n *\n * Canonical event shape for Almadar's cross-package event bus. Hoisted into\n * `@almadar/core` so `@almadar/ui`, `@almadar/runtime`, and generated code\n * all agree on the same structure. Replaces the previously divergent\n * `KFlowEvent` (ui) and `RuntimeEvent` (runtime) definitions.\n *\n * @packageDocumentation\n */\n\nimport { z } from \"zod\";\nimport { EventPayloadSchema, SExprDataSchema, type EventPayload, type SExpr } from \"./expression.js\";\nimport { OrbitalIdSchema, TraitIdSchema, EventIdSchema, type OrbitalId, type TraitId, type EventId } from \"./identity.js\";\nimport { RowSetRefSchema, type RowSetRef } from \"./row-set.js\";\nimport { EntityRowSchema, type EntityRow } from \"./entity.js\";\nimport { RawUserClaimsSchema, type RawUserClaims, type UserContext } from \"./user.js\";\nimport type { RowQueryPage } from \"../service-types.js\";\nimport { ServerEffectResultSchema, type ServerEffectResult } from \"./effect-result.js\";\nimport type { ExternalInput } from \"../access/contract.js\";\nimport { JsonValueSchema, type JsonObject, type JsonValue } from \"./json.js\";\nimport { isEventResponse, type ClientEffectByTrait, type HostAskCompletion, type EventRequest, type EventResponse, type FrameDelta, type HopEffect, type HopEffectStatus, type TransitionHop, type TransitionRejection, type TransitionRejectionCode } from \"../generated/kernel-wire.js\";\n\nexport type { ClientEffectByTrait, HopEffect, HopEffectStatus, TransitionHop, TransitionRejection, TransitionRejectionCode };\n\n/**\n * Declared event key. A trait's event names (INIT, SAVE, CLOSE,\n * CONFIRM_REMOVE, ...) flow through the orbital schema and the UI as\n * strings; this alias marks \"this string is a declared event key, not\n * arbitrary text.\"\n *\n * Component props typed as `EventKey` are detected by the pattern-sync\n * tool (`tools/almadar-pattern-sync/parser.ts`) via a TS-type lookup and\n * marked as `kind: \"event\"` in the patterns registry\n * (`@almadar/patterns`). Consumers of the registry — the Rust compiler's\n * inline phase and the `@almadar/runtime` preprocess — read that marker\n * to apply call-site `events: { OLD: NEW }` renames to render-ui trees\n * without name-matching heuristics.\n *\n * Plain alias over `string`. Not branded because event keys originate\n * from user data at runtime (orb schema literals, bus emits), so cast\n * friction would buy nothing. The value of the alias is at the type\n * surface — it's a marker the pattern-sync tool can find via\n * `getSymbolAtLocation`.\n */\nexport type EventKey = string;\n\n/**\n * Phantom-typed brand for declarative bus-emit props on UI components.\n *\n * Used by component authors to BOTH mark a prop as a bus-event reference\n * AND document the payload shape that the component will fire onto the\n * bus when that prop is bound. Authors write:\n *\n *     // Tabs.tsx\n *     export interface TabsProps {\n *       tabChangeEvent?: EventEmit<{ tabId: string }>;\n *     }\n *\n * Consumers see only the structural `string` (no UX impact: passing a\n * literal `\"TAB_CHANGED\"` keeps working). The phantom `P` parameter\n * carries the bus-payload schema at the type level for pattern-sync to\n * extract.\n *\n * Pattern-sync (`tools/almadar-pattern-sync/parser.ts`) detects this\n * brand via TS type-lookup (mirrors how it detects `EventKey`) and\n * writes two registry fields per prop:\n * - `kind: \"event-ref\"` — the discriminant rules read in lolo / orb\n *   validator to know \"this prop's string value is a bus event name.\"\n * - `emitPayloadSchema` — the structural shape of `P`, serialized as\n *   the same JSON-Schema-shaped record Almadar uses for trait\n *   `payloadSchema`. Validator rules cross-check this against the\n *   trait's declared `emits { EVENT { ... } }` payload to catch mismatches\n *   at parse / validate time instead of runtime.\n *\n * Example payload bus emission inside the component (no wrapper —\n * `EventEmit<P>` erases to `string`):\n *\n *     if (tabChangeEvent) eventBus.emit(`UI:${tabChangeEvent}`, { tabId });\n *\n * The brand is structurally an unused optional readonly property; TS\n * never asks for it at construction, so authors and consumers never\n * see it.\n */\nexport type EventEmit<P> = string & { readonly __emitPayload?: P };\n\n/**\n * Phantom-typed brand for declarative bus-listen props on UI components.\n *\n * Mirror of `EventEmit<P>`. Used by future patterns where a UI component\n * subscribes to a bus event and forwards its payload upward via prop\n * (e.g. an editor pattern that listens for `EXTERNAL_RESET` and exposes\n * the consumed payload to the parent). Pattern-sync detects this brand\n * the same way as `EventEmit<P>` and writes:\n * - `kind: \"event-listen\"` (or a sub-discriminant of `event-ref`)\n * - `listenPayloadSchema` with the structural shape of `P`\n *\n * Validator rules use this to verify the trait the prop is bound to\n * actually emits a payload of the expected shape.\n *\n * Reserved for symmetry; no @almadar/ui component uses it as of this\n * commit. Add usages incrementally as patterns require them.\n */\nexport type EventListen<P> = string & { readonly __listenPayload?: P };\n\n// NOTE: The phantom entity-inlet brands `EntityInlet`/`EntityRecord`/\n// `EntityCollection` were removed in the entity-row clean slate. There is now\n// ONE entity type — `EntityRow` (`./entity`), used directly: a single record is\n// `EntityRow`, a collection is `readonly EntityRow[]`. pattern-sync detects an\n// entity prop by the `EntityRow` type identity and derives record-vs-collection\n// from array-vs-not, so no brand is needed.\n\n/**\n * Identifies the origin of a bus event. Used by cross-trait listeners to\n * filter emits from specific orbitals, traits, transitions, or ticks.\n *\n * `transition` and `tick` are optional runtime-internal details; most\n * consumers only care about `orbital` and `trait`.\n */\nexport type BusEventSource = {\n  orbital?: string;\n  /** V4 dual-carry id sibling of `orbital` — stable across an orbital rename. */\n  orbitalId?: OrbitalId;\n  trait?: string;\n  /** V4 dual-carry id sibling of `trait` — stable across a trait rename. */\n  traitId?: TraitId;\n  /** V4 dual-carry id of the emitted event — stable across an event rename. */\n  eventId?: EventId;\n  transition?: string;\n  tick?: string;\n  /**\n   * True when the orbital bridge re-broadcasts an event onto the bus\n   * (any source — both echoes of the dispatched event and server-side\n   * cascade emits via `(emit X)` / `fetch.emit.success`). Cross-trait\n   * listeners filter on this flag so the click-time qualified emit\n   * (which has no `fromBridge`) doesn't double-fire alongside the\n   * post-server bridge confirmation. See `dispatched` for the narrower\n   * \"echo of the just-dispatched event\" signal.\n   */\n  fromBridge?: boolean;\n  /**\n   * True ONLY for bridge echoes the receiving tab already processed, so\n   * the originating trait's self-subscription skips them instead of\n   * re-dispatching its own echo (infinite loop / double execution).\n   * Set by path 1 of useOrbitalBridge (compiled shell — echo of the\n   * just-dispatched event; server-side cascade emits there carry\n   * `fromBridge: true` but NOT `dispatched`, so they still reach the\n   * source trait's transition handler, e.g. `loading -> browsing` on a\n   * fetch's `emit.success`) and by ServerBridge (runtime path — stamped\n   * on exactly one response-cascade echo per event the dispatch delivered\n   * locally on the bare key, `stampLocallyDeliveredEchoes`; server-only\n   * results stay unstamped). Cross-trait `listens` never filter on this\n   * flag, so their delivery is unaffected. Push-leg events from OTHER\n   * tabs (multiplayer) are never stamped.\n   */\n  dispatched?: boolean;\n  /**\n   * The client that originated the dispatch whose effects emitted this\n   * event (from `EventRequest.clientId`); absent for headless\n   * dispatches (ticks, circuit-router probes, walkers). The server-side\n   * listens fan-out skips client-originated cascade emits — under dual\n   * execution the originating client relays every cascade hop through the\n   * bridge itself, so the server dispatching the same hop double-ran it\n   * (one Send persisted two rows). Headless topology keeps the fan-out:\n   * there is no client to drive the circuit.\n   */\n  originClientId?: string;\n  /**\n   * Per-activation key a UI control stamps on the event it emits, so it can\n   * show its own busy state for exactly as long as the dispatches that event\n   * started are in flight (`@almadar/ui` lib/pendingDispatch). Never set by\n   * the bridge or the server.\n   */\n  pendingKey?: string;\n  /**\n   * Set by a server-role kernel on a `persist` effect's `emit.success` envelope: the one emit a live-push\n   * host (`setLiveBroadcastSink`) also fans out to every other connected client.\n   */\n  persistSuccess?: boolean;\n  /**\n   * The row of the emitting trait's entity that made the emit, when the trait's rows are addressed by a `per`\n   * listener. A listener with a `per` clause evaluates its own key; one without ignores this.\n   */\n  instanceKey?: string;\n};\n\n// The third type param is `object` on schemas nesting a branded-id\n// `.refine(<type predicate>)` field: the refine's parsed INPUT is a plain\n// `string`, not the branded output type, so the input/output-equal default\n// `z.ZodType<T>` mis-typechecks. `object` is what the wire actually carries\n// (a JSON body) — never `unknown`.\n\n/** The delivery a transition is processing: `@event`, and one element of `@prevEvents` (Runtime Spec Clause 5.5). */\nexport type DeliveryRecord = {\n  event: string;\n  payload?: EventPayload;\n  source: BusEventSource;\n};\n\n/** A trait's log so far in a dispatch that began elsewhere (`@prevEvents` / `@prevStates`), carried on the request. */\nexport type DispatchLog = {\n  prevEvents: DeliveryRecord[];\n  prevStates: string[];\n};\n\n/** Zod twin of `BusEventSource`. */\nexport const BusEventSourceSchema: z.ZodType<BusEventSource, object> = z.object({\n  orbital: z.string().optional(),\n  orbitalId: OrbitalIdSchema.optional(),\n  trait: z.string().optional(),\n  traitId: TraitIdSchema.optional(),\n  eventId: EventIdSchema.optional(),\n  transition: z.string().optional(),\n  tick: z.string().optional(),\n  fromBridge: z.boolean().optional(),\n  dispatched: z.boolean().optional(),\n  originClientId: z.string().optional(),\n  pendingKey: z.string().optional(),\n  persistSuccess: z.boolean().optional(),\n  instanceKey: z.string().optional(),\n});\n\n/** Zod twin of `DeliveryRecord`. */\nexport const DeliveryRecordSchema: z.ZodType<DeliveryRecord, object> = z.object({\n  event: z.string(),\n  payload: EventPayloadSchema.optional(),\n  source: BusEventSourceSchema,\n});\n\n/** Zod twin of `DispatchLog`. */\nexport const DispatchLogSchema: z.ZodType<DispatchLog, object> = z.object({\n  prevEvents: z.array(DeliveryRecordSchema),\n  prevStates: z.array(z.string()),\n});\n\n/**\n * An event flowing on the bus.\n *\n * The `source` field is structured so cross-trait listeners can match\n * `event.source?.orbital === 'X' && event.source?.trait === 'Y'` without\n * parsing a delimiter.\n */\nexport type BusEvent = {\n  /** Event type identifier (e.g., 'CartItemLoaded', 'TASK_COMPLETED') */\n  type: EventKey;\n  /** Optional structured payload */\n  payload?: EventPayload;\n  /** Timestamp when the event was emitted */\n  timestamp: number;\n  /** Optional origin info for filtering */\n  source?: BusEventSource;\n};\n\n/** Bus event listener callback. */\nexport type BusEventListener = (event: BusEvent) => void;\n\n/** Returned by `on()` / `once()` to detach a listener. */\nexport type Unsubscribe = () => void;\n\n/**\n * One event a transition's effects emitted, carried back to the client to\n * re-dispatch (in order) so the state machine advances through the\n * cascade without server-side recursion. Named/shaped to match the\n * generated compiled-path `EmittedEvent` (orbital-shell-typescript's\n * `shared/types.ts`) so the two execution paths agree on one shape.\n */\nexport type EmittedEvent = {\n  event: string;\n  payload?: EventPayload;\n  source?: BusEventSource;\n};\n\n/** Zod twin of `EmittedEvent`. Third type param `object`, see `BusEventSourceSchema`. */\nexport const EmittedEventSchema: z.ZodType<EmittedEvent, object> = z.object({\n  event: z.string(),\n  payload: EventPayloadSchema.optional(),\n  source: BusEventSourceSchema.optional(),\n});\n\n// ============================================================================\n// Client-effect wire grammar\n// ============================================================================\n\n/**\n * Client-side effect tuple shipped in `EventResponse.clientEffectsByTrait`.\n * Restricted to the effect kinds the client knows how to apply to the\n * UI: render-ui (slot mutation, including the `toast` slot that carries\n * what used to be the separate notify effect) and navigate (route change).\n * Server-only effects (persist, set, fetch, ...) execute on the server and\n * surface their results via `effectResults` and `emittedEvents`, not here.\n *\n * Shape note: `render-ui` takes a slot and a pattern (G-CROSS-257); `navigate`'s\n * optional argument may surface as `null` rather than absent (an empty slot is `null` on the wire: `JSON.stringify` and the Rust serializer both write it). The local union spells those\n * variants out explicitly so consumers (ServerBridge.tsx parser, debugger\n * inspector) get accurate completions instead of `unknown[]`.\n *\n * `slot` is a plain `string` in this wire shape (not `UISlot`'s literal\n * union) because the runtime forwards the raw string from the trait's\n * `(render-ui slot ...)` SExpr without re-validating against the registry —\n * registry validation lives in `orbital validate` / `lolo` parse, not here.\n */\nexport type ClientRenderUITuple = ['render-ui', string, JsonObject | null];\n\nexport type ClientNavigateTuple =\n  | ['navigate', string]\n  | ['navigate', string, Record<string, string> | null]\n  | ['navigate', string, Record<string, string> | null, { crumb?: string }];\n\nexport type ClientNavigateBackTuple = ['navigate-back'];\n\n/** A `runsOn: client` host-port effect (`auth/sign-out`, `audio/*`) the client host answers; its arguments are resolved. */\nexport type ClientHostAskTuple = ['host-ask', string, JsonValue[]] | ['host-ask', string, JsonValue[], HostAskCompletion];\n\n/** The return address of a `host-ask` (EXEC-DIST-13/14): the generated wire type, one copy. */\nexport type { HostAskCompletion };\n\nexport type ClientEffectTuple =\n  | ClientRenderUITuple\n  | ClientNavigateTuple\n  | ClientNavigateBackTuple\n  | ClientHostAskTuple;\n\n/** Zod twin of `ClientRenderUITuple`. */\nexport const ClientRenderUITupleSchema = z.tuple([z.literal('render-ui'), z.string(), z.record(z.string(), JsonValueSchema).nullable()]);\n\n/** Zod twin of `ClientNavigateTuple` — one variant per fixed arity (2/3/4), unioned. */\nexport const ClientNavigateTupleSchema = z.union([\n  z.tuple([z.literal('navigate'), z.string()]),\n  z.tuple([z.literal('navigate'), z.string(), z.record(z.string(), z.string()).nullable()]),\n  z.tuple([\n    z.literal('navigate'),\n    z.string(),\n    z.record(z.string(), z.string()).nullable(),\n    z.object({ crumb: z.string().optional() }),\n  ]),\n]);\n\n/** Zod twin of `ClientNavigateBackTuple`. */\nexport const ClientNavigateBackTupleSchema = z.tuple([z.literal('navigate-back')]);\n\n/** Zod twin of `ClientHostAskTuple`. */\nexport const HostAskCompletionSchema = z.object({\n  trait: z.string(),\n  entityId: z.string().optional(),\n  key: z.string().optional(),\n  success: z.string().optional(),\n  failure: z.string().optional(),\n  onMessage: z.string().optional(),\n}).strict();\n\nexport const ClientHostAskTupleSchema = z.union([\n  z.tuple([z.literal('host-ask'), z.string(), z.array(JsonValueSchema)]),\n  z.tuple([z.literal('host-ask'), z.string(), z.array(JsonValueSchema), HostAskCompletionSchema]),\n]);\n\n/** Zod twin of `ClientEffectTuple`. */\nexport const ClientEffectTupleSchema: z.ZodType<ClientEffectTuple> = z.union([\n  ClientRenderUITupleSchema,\n  ClientNavigateTupleSchema,\n  ClientNavigateBackTupleSchema,\n  ClientHostAskTupleSchema,\n]);\n\n// ============================================================================\n// Event dispatch wire (single owner — canonical = the TS runtime)\n// ============================================================================\n\n/** The lifecycle events a trait runs when it enters a page (the first it handles). */\nexport const LIFECYCLE_EVENTS = [\"INIT\", \"LOAD\", \"$MOUNT\"] as const;\n\n/** Wire-only event a client sends when a trait leaves the page; the server stops counting it as mounted. */\nexport const UNMOUNT_EVENT = '$UNMOUNT';\n\n/** An event key without its `UI:` bus prefix. */\nexport function normalizeEventKey(eventKey: string): string {\n  if (!eventKey) return '';\n  return eventKey.startsWith('UI:') ? eventKey.slice(3) : eventKey;\n}\n\n/** The event a tick firing carries on the wire (`EventRequest.event` of a `runTick` leg). */\nexport function tickEventKey(tickName: string): string {\n  return `$TICK_${tickName}`;\n}\nexport type LifecycleEvent = (typeof LIFECYCLE_EVENTS)[number];\n\n/** One trait of a mount batch and the lifecycle event it runs. */\nexport type MountSeed = {\n  trait: string;\n  event: LifecycleEvent;\n};\n\nexport const MountSeedSchema = z.object({ trait: z.string(), event: z.enum(LIFECYCLE_EVENTS) });\n\n/**\n * A request on the outside-client input channel (`POST /:orbital/inputs`): an\n * API caller, an agent acting as the user, an MCP client. Only an event the\n * target trait declares as an external input (`listens { EVENT -> external { … } }`)\n * is dispatched; anything else is refused with `not-an-external-input`.\n */\nexport type ExternalInputRequest = {\n  targetTrait: string;\n  event: string;\n  payload?: EventPayload;\n  user?: RawUserClaims;\n  entityId?: string;\n};\n\nexport type EventStreamItem =\n  | { type: 'event'; data: EmittedEvent; timestamp: number }\n  | { type: 'effect'; data: ClientEffectTuple; timestamp: number }\n  | { type: 'complete'; data: EventResponse; timestamp: number }\n  | { type: 'error'; data: { message: string }; timestamp: number };\n\nexport const EventStreamItemSchema = z.union([\n  z.object({ type: z.literal('event'), data: EmittedEventSchema, timestamp: z.number() }),\n  z.object({ type: z.literal('effect'), data: ClientEffectTupleSchema, timestamp: z.number() }),\n  z.object({ type: z.literal('complete'), data: z.custom<EventResponse>((v) => JsonValueSchema.safeParse(v).success && isEventResponse(JsonValueSchema.parse(v))), timestamp: z.number() }),\n  z.object({ type: z.literal('error'), data: z.object({ message: z.string() }), timestamp: z.number() }),\n]);\n\n/** How a host answered a `program/dispatch` event request: the response, or the route's failure code and status. */\nexport type DispatchRequestOutcome =\n  | { ok: true; response: EventResponse; streamItems?: EventStreamItem[] }\n  | { ok: false; error: string; code: string; status: number };\n\n/**\n * What a host lends one service call so the service can act in the running app\n * AS THE CALLER (an agent operating the app for the signed-in user): the\n * declared inputs, the outside-client input channel, and a read that applies the\n * entity's `@read` policy. Built per call, bound to the caller's identity and\n * position; every dispatch is a full, ordinary dispatch (guards, policies,\n * listens). The interpreter and the compiled server each supply one.\n */\nexport interface ServiceHostPorts {\n  /** The orbital and trait whose `call-service` is running. */\n  caller: { orbital: string; trait: string };\n  inputs(): ExternalInput[];\n  /** The entities `read` serves: every persisted entity of the program (`readableEntitiesOf`). */\n  readableEntities(): string[];\n  dispatchInput(orbital: string, request: Omit<ExternalInputRequest, 'user'>): Promise<EventResponse>;\n  read(entity: string): Promise<EntityRow[]>;\n  /**\n   * A `program/dispatch` event request (owner, 2026-10-21): dispatch `request` on `orbital` as the HTTP events\n   * route does (`input: true` admits only a declared external input, as the inputs route). `request` is what the kernel\n   * parsed (`EventRequest::from_dispatch`); its `user` is the dispatch's viewer when the call names one.\n   * A host that does not serve event requests leaves it out.\n   */\n  supportsDispatchStream?: true;\n  dispatchRequest?(orbital: string, request: EventRequest, input: boolean, stream?: boolean): Promise<DispatchRequestOutcome>;\n  /** A `program/dispatch { inbound }` delivery through the inbound route, credential check and answer path. */\n  deliverInbound?(name: string, delivery: { headers: Readonly<Record<string, string>>; rawBody: string }): Promise<{ status: number; body: string }>;\n  /** The host's last `steps` traced dispatch steps, oldest first; a host that keeps no trace leaves it out. */\n  trace?(steps: number): JsonValue[];\n  /** 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. */\n  resolveRows?(reference: RowSetRef, clientId: string | undefined): Promise<RowQueryPage>;\n  /**\n   * Deliver one message of the running call to the caller's tab, live, as the\n   * call site's `emit.onMessage` event source-stamped to the caller. A no-op\n   * when the call site declares no `onMessage`.\n   */\n  message(payload: EventPayload): void;\n}\n\n// ============================================================================\n// Register wire (client → server schema registration)\n// ============================================================================\n\n/**\n * Where circuit state lives between events (`docs/Almadar_Runtime_Stateless_Stateful_PLAN.md` §1a):\n * `'stateless'` = the client carries it on every request, `'stateful'` = the server holds it.\n */\nexport type ServerTopology = 'stateless' | 'stateful';\n\nexport const ServerTopologySchema = z.enum(['stateless', 'stateful']);\n\n/** `POST /register` response. `topology` absent = a server that predates the declaration. */\nexport interface OrbitalRegisterResponse {\n  success: boolean;\n  topology?: ServerTopology;\n  message?: string;\n  orbitals?: string[];\n  error?: string;\n}\n\nexport const OrbitalRegisterResponseSchema: z.ZodType<OrbitalRegisterResponse, object> = z.object({\n  success: z.boolean(),\n  topology: ServerTopologySchema.optional(),\n  message: z.string().optional(),\n  orbitals: z.array(z.string()).optional(),\n  error: z.string().optional(),\n});\n\n// ============================================================================\n// Live broadcast wire (server → other connected clients)\n// ============================================================================\n\n/**\n * One persist-envelope success emit, handed to the live-broadcast sink\n * (`OrbitalServerRuntime.setLiveBroadcastSink`) and relayed to every OTHER\n * connected client. Fired only from the `persist` effect's `emit:{success}`\n * envelope (batch and single-op) — never from the generic emit funnel — so\n * transport layers can fan it out without matching on event names. Promoted\n * from `@almadar/runtime`'s own `LiveBroadcastItem` (canonical per Program\n * A's \"converge on the TS runtime\" ruling) so `orbital-server`'s `GET\n * /api/events` broadcast mirrors the same shape.\n */\nexport interface LiveBroadcastItem {\n  event: string;\n  payload?: EventPayload;\n  source: BusEventSource;\n  /** `clientId` of the request that produced this emit; excluded from delivery by the transport. */\n  originClientId?: string;\n}\n\n/** Zod twin of `LiveBroadcastItem`. Third type param `object`, see `BusEventSourceSchema`. */\nexport const LiveBroadcastItemSchema: z.ZodType<LiveBroadcastItem, object> = z.object({\n  event: z.string(),\n  payload: EventPayloadSchema.optional(),\n  source: BusEventSourceSchema,\n  originClientId: z.string().optional(),\n});\n"]}