@almadar/core 10.58.0 → 10.59.0

package/dist/index-DMUBu17o.d.ts

@@ -0,0 +1,3178 @@
+import { b3 as PageTraitRef, O as OrbitalSchema, bh as ThemeDefinition, aa as Orbital, c as Page, N as DomainContext, a as OrbitalDefinition } from './schema-CVTOy4at.js';
+import { F as FieldValue, E as EntityField, a as EntityPersistence, bp as ServiceParams, e as Entity, f as EntityRow, A as AnyPatternConfig, O as OrbitalId, T as TraitId, b as EventId, c as Effect } from './effect-CK9fn56C.js';
+import { S as SExpr, R as RuntimeValue, d as EventPayloadValue, J as JsonValue, a as EventPayload, L as LogMeta, g as JsonObject, T as ToolArgs, c as EvalContext } from './expression-Fk8bQWef.js';
+import { z } from 'zod';
+import { a as TraitReference, g as Trait, L as ListenSource, D as DeclaredTraitConfig, b as TraitConfig, C as ConfigFieldDeclaration, S as State, ae as Transition, r as Event, e as TraitConfigValue, Y as TraitCategory, as as TraitScope } from './trait-BjPraUgs.js';
+import { T as TraitOverlay, R as RuleOverlay, J as JsonSchema, c as FactoryConfigTier } from './types-Dopw3s2O.js';
+import { MakeTraitRefOpts, EventWiringEntry, LayoutStrategy } from './builders.js';
+
+/**
+ * S-Expression Bindings
+ *
+ * Defines binding types and utilities for S-expression context.
+ * Bindings are references to values that are resolved at runtime.
+ *
+ * Core Bindings:
+ * - @entity - The linked entity for this trait (e.g., @entity.health)
+ * - @payload - Event payload data (e.g., @payload.amount)
+ * - @state - Current state machine state
+ * - @now - Current timestamp (Date.now())
+ *
+ * Entity Bindings:
+ * - @EntityName.field - Reference to singleton/runtime entity (e.g., @GameConfig.gravity)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Schema for a binding string.
+ * Validates that the string starts with @ and has valid format.
+ */
+declare const BindingSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * Binding documentation for LLM prompts and validation messages.
+ *
+ * IMPORTANT: Keep synchronized with CORE_BINDINGS in expression.ts
+ */
+declare const BINDING_DOCS: {
+    readonly entity: {
+        readonly description: "Reference to the linked entity for this trait";
+        readonly examples: readonly ["@entity.health", "@entity.x", "@entity.status"];
+        readonly requiresPath: true;
+    };
+    readonly payload: {
+        readonly description: "Reference to the event payload data";
+        readonly examples: readonly ["@payload.amount", "@payload.targetId", "@payload.action"];
+        readonly requiresPath: true;
+    };
+    readonly state: {
+        readonly description: "Current state machine state name";
+        readonly examples: readonly ["@state"];
+        readonly requiresPath: false;
+    };
+    readonly now: {
+        readonly description: "Current timestamp in milliseconds";
+        readonly examples: readonly ["@now"];
+        readonly requiresPath: false;
+    };
+    readonly config: {
+        readonly description: "Trait configuration values";
+        readonly examples: readonly ["@config.apiEndpoint", "@config.theme"];
+        readonly requiresPath: true;
+    };
+    readonly computed: {
+        readonly description: "Computed/calculated values";
+        readonly examples: readonly ["@computed.total", "@computed.isValid"];
+        readonly requiresPath: true;
+    };
+    readonly trait: {
+        readonly description: "Trait context data";
+        readonly examples: readonly ["@trait.name", "@trait.category"];
+        readonly requiresPath: true;
+    };
+    readonly user: {
+        readonly description: "Authenticated user / agent context for ownership and role-based gating";
+        readonly examples: readonly ["@user.id", "@user.role"];
+        readonly requiresPath: true;
+    };
+    readonly callsitePayload: {
+        readonly description: "Call-site-captured event payload — emitted by the compiler's inline-trait hoisting when an extracted render block captured @payload; resolved at the composing effect by the runtime BindingResolver";
+        readonly examples: readonly ["@callsitePayload.error", "@callsitePayload.row"];
+        readonly requiresPath: true;
+    };
+    readonly pages: {
+        readonly description: "Render-resolved schema sigil — the host orbital's pages as a NavItem[] array (href = page.path, label = page.name). Substituted from the OrbitalSchema before codegen; never survives as a live binding.";
+        readonly examples: readonly ["@pages"];
+        readonly requiresPath: false;
+    };
+    readonly currentTheme: {
+        readonly description: "Render-resolved schema sigil — the host orbital's active data-theme key, derived from Orbital.theme. Substituted from the OrbitalSchema before codegen; never survives as a live binding.";
+        readonly examples: readonly ["@currentTheme"];
+        readonly requiresPath: false;
+    };
+};
+/**
+ * Validation rules for bindings in different contexts.
+ */
+declare const BINDING_CONTEXT_RULES: {
+    readonly guard: {
+        readonly allowed: readonly ["entity", "payload", "state", "now", "config", "user"];
+        readonly description: "Guards can access entity fields, event payload, current state, time, the call-site trait config (@config.X), and the authenticated user context (@user.id, @user.role) for ownership / role gates. Config access lets atoms write mode-aware guards — e.g. std-modal's OPEN can require @payload.row only when @config.mode equals \"edit\", letting create-mode legitimately fire OPEN with no row. Like effects, @config.X is substituted at molecule/organism inline time with the literal call-site value; at atom-scope validate, @config is allowed-but-unresolved.";
+    };
+    readonly effect: {
+        readonly allowed: readonly ["entity", "payload", "state", "now", "trait", "config", "user", "callsitePayload", "pages", "currentTheme"];
+        readonly description: "Effects can access and modify entity fields, use payload data, embed another trait's live frame via @trait.X inside render-ui children, read trait config values (@config.X) for atoms parameterized by their call-site, and read the authenticated user context (@user.id, @user.role). At molecule/organism inline time, @config.X is substituted with the literal value from the call-site config block; at atom-scope validate, @config is allowed-but-unresolved. @callsitePayload.X is the call-site-captured event payload emitted by the compiler's inline-trait hoisting (a hoisted render block that captured @payload); it is resolved at the composing effect by the runtime BindingResolver.";
+    };
+    readonly tick: {
+        readonly allowed: readonly ["entity", "state", "now", "config", "user"];
+        readonly description: "Ticks can access entity fields, current state, time, trait config (@config.X) for parameterized atoms, and the authenticated user context (@user.id, @user.role). Same substitution semantics as guards/effects.";
+    };
+};
+type BindingContext = keyof typeof BINDING_CONTEXT_RULES;
+/**
+ * Tag property of a `RenderBindingMarker`. `$`-prefixed so it can never
+ * collide with a pattern prop key (prop keys are camelCase identifiers).
+ */
+declare const RENDER_BINDING_MARKER: "$renderBinding";
+/**
+ * A render-ui prop leaf that is evaluated at RENDER time, not at flush time.
+ *
+ * The interpreted path's executor carries `@entity`-dependent leaves into
+ * slot content as these markers instead of resolving them eagerly; the
+ * renderer (`@almadar/ui`'s SlotContentRenderer) resolves each marker
+ * against the live entity store on every render — the same model the
+ * compiled shell uses (state-based JSX reading `fields?.X` per React
+ * render). Payload-dependent leaves are never deferred: `@payload` is
+ * event-scoped and does not exist at render time.
+ *
+ * A `type` (not `interface`) so it carries an implicit index signature and
+ * stays assignable to the `SExpr` record branch at guard call sites.
+ */
+type RenderBindingMarker = {
+    readonly [RENDER_BINDING_MARKER]: true;
+    /** The raw prop expression: a binding string (`'@entity.hp'`, embedded
+     * form `'HP: @entity.hp'`) or an S-expression tree. */
+    readonly expression: SExpr;
+};
+/** Narrow an arbitrary prop value to a `RenderBindingMarker`. */
+declare function isRenderBindingMarker(value: RuntimeValue): value is RenderBindingMarker;
+/**
+ * Does this raw prop expression reference `@entity` anywhere (pure binding,
+ * embedded-binding string, nested S-expression, or object tree)? Marker
+ * objects count as entity-referencing by construction.
+ */
+declare function containsEntityBinding(value: SExpr): boolean;
+/**
+ * Does this raw prop expression reference the event payload (`@payload` /
+ * `@callsitePayload`) anywhere? Such leaves stay flush-time evaluated —
+ * the payload does not exist at render time.
+ */
+declare function containsPayloadBinding(value: SExpr): boolean;
+/**
+ * Check if a binding is valid in a given context.
+ *
+ * @param binding - Parsed binding
+ * @param context - Context where binding is used
+ * @returns Error message if invalid, null if valid
+ */
+declare function validateBindingInContext(binding: {
+    type: 'core' | 'entity';
+    root: string;
+}, context: BindingContext): string | null;
+/**
+ * Get all valid binding examples for a context.
+ *
+ * @param context - Context to get examples for
+ * @returns Array of example binding strings
+ */
+declare function getBindingExamples(context: BindingContext): string[];
+
+/**
+ * Binding root classification
+ *
+ * The prefix of an `@X.path` binding expression identifies which runtime
+ * context resolves the rest of the path. This type is the TS-side mirror
+ * of `OirBindingRoot` in `orbital-core`'s IR; publishing it from
+ * `@almadar/core` lets the codegen, the runtime binding resolver, and
+ * the verifier's schema walker all refer to the same narrow union.
+ *
+ * Distinct from {@link ParsedBinding.root} (which is a plain string): use
+ * `BindingRoot` whenever you need exhaustiveness over the known prefixes.
+ *
+ * - `entity`: `@entity.field` — the trait's linked entity (first row on
+ *   the client, `getById` result on the server).
+ * - `payload`: `@payload.x` — the last event's payload.
+ * - `state`: `@state.x` — the state machine's `state` slot (rare;
+ *   mostly used for guard/effect contexts).
+ * - `config`: `@config.x` — the trait ref's merged config from the
+ *   molecule call site.
+ * - `user`: `@user.x` — authenticated user / agent context.
+ * - `trait`: `@trait.x` — render-time reference to another trait's
+ *   mounted view. Resolved by `<TraitFrame>` at runtime, not by the
+ *   SExpression compiler.
+ * - `item`: `@item.x` — iterator variable inside a `map` / repeat
+ *   pattern.
+ * - `now`: `@now` — current timestamp (ISO string).
+ * - `computed`: `@computed.x` — evaluator-computed value (Phase 4.5).
+ * - `other`: catch-all for unknown prefixes or entity-reference
+ *   bindings (`@User.name`, `@_item`).
+ *
+ * @packageDocumentation
+ */
+
+type BindingRoot = 'entity' | 'payload' | 'state' | 'config' | 'user' | 'trait' | 'item' | 'now' | 'computed' | 'other';
+/** Every known binding root, in a stable order — useful for exhaustiveness checks. */
+declare const BINDING_ROOTS: readonly BindingRoot[];
+/**
+ * Narrow a raw binding-root string (e.g. the `root` field of
+ * `ParsedBinding` from `./expression.ts`) to a `BindingRoot`. Returns
+ * `'other'` for entity-reference roots like `@User.name` or unknown
+ * prefixes.
+ */
+declare function toBindingRoot(root: string): BindingRoot;
+/**
+ * A trait reference string of the form `@trait.<TraitName>`. Used as the
+ * value type for `trait`-typed config fields. The runtime + compiled codegen
+ * both substitute this with embedded trait UI at render time.
+ *
+ * Branded as a literal-template type so TS narrows on use; consumers should
+ * call {@link isTraitFieldRef} to validate runtime values before assignment.
+ */
+type TraitFieldRef = `@trait.${string}`;
+/** Type guard: narrow an unknown value to {@link TraitFieldRef}. */
+declare function isTraitFieldRef(value: RuntimeValue): value is TraitFieldRef;
+/** Zod schema for {@link TraitFieldRef} values. Useful when validating analyzer
+ *  JSON or recipe overrides at runtime boundaries. */
+declare const TraitFieldRefSchema: z.ZodString;
+
+/**
+ * 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;
+}
+/**
+ * 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;
+
+/**
+ * Validation error types — the shape emitted by every
+ * `.orb` / `.lolo` validator pass.
+ *
+ * `ValidationError` is the wire shape: `{ code, path, message, suggestion? }`.
+ * `code` is `ValidationErrorCode`, which is an OPEN `string` to let the
+ * Rust validator emit new codes without an `@almadar/core` rev. The
+ * `KNOWN_VALIDATION_ERROR_CODES` const documents the codes currently
+ * emitted by the validator + lolo lower pipeline (extracted from
+ * `orbital-rust/crates/orbital-compiler/src/phases/validation/` +
+ * `orbital-rust/crates/orbital-lolo/src/`).
+ *
+ * Consumers that want to narrow a code to the closed known set use
+ * `KnownValidationErrorCode`:
+ *
+ * ```ts
+ * if (err.code in KNOWN_VALIDATION_ERROR_CODES) {
+ *   // err.code is now narrowable to KnownValidationErrorCode for
+ *   // exhaustive switch handling.
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * One validation diagnostic emitted by the validator / lolo lower pipeline.
+ *
+ * - `code`: machine-readable identifier (see `KNOWN_VALIDATION_ERROR_CODES`).
+ * - `path`: JSON pointer-like path into the failing schema location,
+ *   e.g. `'orbitals[0].traits[2].stateMachine.transitions[1].effects[0]'`.
+ * - `message`: human-readable description of the failure.
+ * - `suggestion`: optional hint the validator may add to help the
+ *   author / LLM fix the issue.
+ */
+interface ValidationError {
+    code: ValidationErrorCode;
+    path: string;
+    message: string;
+    suggestion?: string;
+}
+/**
+ * Validation error code — open `string` for forward-compat with the
+ * Rust validator's evolving code set. Narrow to the closed known set
+ * via `KnownValidationErrorCode` when exhaustive handling is needed.
+ */
+type ValidationErrorCode = string;
+/**
+ * The result of a single validator pass: a boolean verdict plus the errors
+ * and warnings (the validator wire shape, `ValidationError`).
+ *
+ * Distinct from `ValidationResults` (app.ts): that is the Firestore-persisted
+ * app-document shape keyed on `ValidationIssue` (with `severity` + array path
+ * + `validatedAt`). This `ValidationResult` is the in-process pass result keyed
+ * on `ValidationError` (code + JSON-pointer string path + `suggestion`).
+ * `ok === true` iff there are zero errors AND zero warnings.
+ */
+interface ValidationResult {
+    ok: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+/**
+ * Closed set of validation codes the Rust validator + lolo lower
+ * pipeline currently emit. Source-tagged: codes are extracted from
+ * `orbital-rust/crates/orbital-compiler/src/phases/validation/**.rs`
+ * and `orbital-rust/crates/orbital-lolo/src/**.rs`. Keep this in sync
+ * with the Rust side; mismatches are caught by the Rust validator's
+ * own unit tests, which assert the emitted code-set matches an
+ * exported manifest.
+ *
+ * Categories (prefix → meaning):
+ * - `ORB_BINDING_*` — binding (`@entity.X`, `@payload.Y`, ...) issues
+ * - `ORB_E_*` / `ORB_EFF_*` / `ORB_EMIT_*` — entity / effect / emit
+ * - `ORB_GEN_*` — generic / cross-cutting structure
+ * - `ORB_O_*` / `ORB_P_*` / `ORB_S_*` / `ORB_SM_*` / `ORB_T_*` —
+ *   orbital / page / schema / state-machine / trait
+ * - `ORB_QUERY_*` — query / search behaviors
+ * - `ORB_RUI_*` — render-UI binding + prop validation
+ * - `ORB_SLOT_*` — UI-slot conflict / contention
+ * - `ORB_SVC_*` / `ORB_UI_*` — service / UI primitives
+ * - `ORB_X_*` — cross-orbital constraints (listens, emits, IDs)
+ * - `ORB_ID_*` — V4 dual-carry id integrity (unknown ref, name/kind
+ *   mismatch, ledger orphan)
+ */
+declare const KNOWN_VALIDATION_ERROR_CODES: {
+    readonly ORB_BINDING_ENTITY_FIELD_NEVER_SET: "ORB_BINDING_ENTITY_FIELD_NEVER_SET";
+    readonly ORB_BINDING_ENTITY_FIELD_NOT_FOUND: "ORB_BINDING_ENTITY_FIELD_NOT_FOUND";
+    readonly ORB_BINDING_INVALID_FIELD_NAME: "ORB_BINDING_INVALID_FIELD_NAME";
+    readonly ORB_BINDING_INVALID_FORMAT: "ORB_BINDING_INVALID_FORMAT";
+    readonly ORB_BINDING_INVALID_PATH: "ORB_BINDING_INVALID_PATH";
+    readonly ORB_BINDING_NOW_NO_PATH: "ORB_BINDING_NOW_NO_PATH";
+    readonly ORB_BINDING_PAYLOAD_FIELD_UNDECLARED: "ORB_BINDING_PAYLOAD_FIELD_UNDECLARED";
+    readonly ORB_BINDING_PAYLOAD_IN_TICK: "ORB_BINDING_PAYLOAD_IN_TICK";
+    readonly ORB_BINDING_PAYLOAD_TYPE_INCOMPATIBLE: "ORB_BINDING_PAYLOAD_TYPE_INCOMPATIBLE";
+    readonly ORB_BINDING_SET_TARGET_MISSING_PATH: "ORB_BINDING_SET_TARGET_MISSING_PATH";
+    readonly ORB_BINDING_STATE_NO_PATH: "ORB_BINDING_STATE_NO_PATH";
+    readonly ORB_BINDING_TRAIT_CYCLE: "ORB_BINDING_TRAIT_CYCLE";
+    readonly ORB_BINDING_TRAIT_INVALID_FORMAT: "ORB_BINDING_TRAIT_INVALID_FORMAT";
+    readonly ORB_BINDING_TRAIT_INVALID_POSITION: "ORB_BINDING_TRAIT_INVALID_POSITION";
+    readonly ORB_BINDING_TRAIT_MISSING_NAME: "ORB_BINDING_TRAIT_MISSING_NAME";
+    readonly ORB_BINDING_TRAIT_SELF_REFERENCE: "ORB_BINDING_TRAIT_SELF_REFERENCE";
+    readonly ORB_BINDING_TRAIT_UNKNOWN: "ORB_BINDING_TRAIT_UNKNOWN";
+    readonly ORB_BINDING_UNKNOWN_ENTITY: "ORB_BINDING_UNKNOWN_ENTITY";
+    readonly ORB_BINDING_UNKNOWN_ROOT: "ORB_BINDING_UNKNOWN_ROOT";
+    readonly ORB_E_DUPLICATE_FIELD: "ORB_E_DUPLICATE_FIELD";
+    readonly ORB_E_EMPTY_ENUM_VALUES: "ORB_E_EMPTY_ENUM_VALUES";
+    readonly ORB_E_INVALID_FIELD_NAME: "ORB_E_INVALID_FIELD_NAME";
+    readonly ORB_E_INVALID_FIELD_TYPE: "ORB_E_INVALID_FIELD_TYPE";
+    readonly ORB_E_INVALID_RELATION: "ORB_E_INVALID_RELATION";
+    readonly ORB_E_LITERAL_UNION_DEFAULT_MISMATCH: "ORB_E_LITERAL_UNION_DEFAULT_MISMATCH";
+    readonly ORB_E_MISSING_COLLECTION: "ORB_E_MISSING_COLLECTION";
+    readonly ORB_E_MISSING_NAME: "ORB_E_MISSING_NAME";
+    readonly ORB_E_NO_FIELDS: "ORB_E_NO_FIELDS";
+    readonly ORB_EFF_CALL_SERVICE_MISSING_ACTION: "ORB_EFF_CALL_SERVICE_MISSING_ACTION";
+    readonly ORB_EFF_CALL_SERVICE_MISSING_HANDLERS: "ORB_EFF_CALL_SERVICE_MISSING_HANDLERS";
+    readonly ORB_EFF_CALL_SERVICE_MISSING_SERVICE: "ORB_EFF_CALL_SERVICE_MISSING_SERVICE";
+    readonly ORB_EFF_EMIT_INVALID_NAME: "ORB_EFF_EMIT_INVALID_NAME";
+    readonly ORB_EFF_EMIT_KEY_INVALID: "ORB_EFF_EMIT_KEY_INVALID";
+    readonly ORB_EFF_EMIT_UNDECLARED_EVENT: "ORB_EFF_EMIT_UNDECLARED_EVENT";
+    readonly ORB_EFF_FETCH_INVALID_ENTITY: "ORB_EFF_FETCH_INVALID_ENTITY";
+    readonly ORB_EFF_FETCH_INVALID_INCLUDE: "ORB_EFF_FETCH_INVALID_INCLUDE";
+    readonly ORB_EFF_MISSING_FETCH_FOR_ENTITY: "ORB_EFF_MISSING_FETCH_FOR_ENTITY";
+    readonly ORB_EFF_MISSING_REQUIRED_EMIT: "ORB_EFF_MISSING_REQUIRED_EMIT";
+    readonly ORB_EFF_NAVIGATE_MISSING_PAYLOAD: "ORB_EFF_NAVIGATE_MISSING_PAYLOAD";
+    readonly ORB_EFF_NAVIGATE_TARGET_UNREACHABLE: "ORB_EFF_NAVIGATE_TARGET_UNREACHABLE";
+    readonly ORB_EFF_SET_INVALID_BINDING: "ORB_EFF_SET_INVALID_BINDING";
+    readonly ORB_EFF_SET_PAYLOAD_NOT_ALLOWED: "ORB_EFF_SET_PAYLOAD_NOT_ALLOWED";
+    readonly ORB_EFF_SLOT_CONFLICT: "ORB_EFF_SLOT_CONFLICT";
+    readonly ORB_EFF_UNKNOWN_TYPE: "ORB_EFF_UNKNOWN_TYPE";
+    readonly ORB_EMIT_DECLARED_BUT_UNFIRED: "ORB_EMIT_DECLARED_BUT_UNFIRED";
+    readonly ORB_EMIT_PAYLOAD_EXTRA_FIELD: "ORB_EMIT_PAYLOAD_EXTRA_FIELD";
+    readonly ORB_EMIT_PAYLOAD_FIELD_TYPE_MISMATCH: "ORB_EMIT_PAYLOAD_FIELD_TYPE_MISMATCH";
+    readonly ORB_EMIT_PAYLOAD_MISSING_REQUIRED: "ORB_EMIT_PAYLOAD_MISSING_REQUIRED";
+    readonly ORB_EMIT_SUCCESS_PAYLOAD_RETURN_MISMATCH: "ORB_EMIT_SUCCESS_PAYLOAD_RETURN_MISMATCH";
+    readonly ORB_GEN_DUPLICATE: "ORB_GEN_DUPLICATE";
+    readonly ORB_GEN_INVALID_REFERENCE: "ORB_GEN_INVALID_REFERENCE";
+    readonly ORB_GEN_INVALID_VALUE: "ORB_GEN_INVALID_VALUE";
+    readonly ORB_GEN_MISSING_FIELD: "ORB_GEN_MISSING_FIELD";
+    readonly ORB_O_MISSING_PAGES: "ORB_O_MISSING_PAGES";
+    readonly ORB_P_DUPLICATE_PATH: "ORB_P_DUPLICATE_PATH";
+    readonly ORB_P_EMPTY_TRAITS: "ORB_P_EMPTY_TRAITS";
+    readonly ORB_P_INVALID_PATH: "ORB_P_INVALID_PATH";
+    readonly ORB_P_INVALID_TRAIT_REF: "ORB_P_INVALID_TRAIT_REF";
+    readonly ORB_P_INVALID_VIEW_TYPE: "ORB_P_INVALID_VIEW_TYPE";
+    readonly ORB_P_MISSING_NAME: "ORB_P_MISSING_NAME";
+    readonly ORB_P_MISSING_PATH: "ORB_P_MISSING_PATH";
+    readonly ORB_P_MISSING_TRAITS: "ORB_P_MISSING_TRAITS";
+    readonly ORB_P_SECTIONS_FORBIDDEN: "ORB_P_SECTIONS_FORBIDDEN";
+    readonly ORB_QUERY_MISSING_RECOMMENDED: "ORB_QUERY_MISSING_RECOMMENDED";
+    readonly ORB_QUERY_MISSING_SEARCH: "ORB_QUERY_MISSING_SEARCH";
+    readonly ORB_QUERY_UNKNOWN_SINGLETON: "ORB_QUERY_UNKNOWN_SINGLETON";
+    readonly ORB_QUERY_UNSUPPORTED_PATTERN: "ORB_QUERY_UNSUPPORTED_PATTERN";
+    readonly ORB_QUERY_UNUSED_SINGLETON: "ORB_QUERY_UNUSED_SINGLETON";
+    readonly ORB_RUI_BINDING_TYPE_MISMATCH: "ORB_RUI_BINDING_TYPE_MISMATCH";
+    readonly ORB_RUI_ELEMENT_SHAPE_MISMATCH: "ORB_RUI_ELEMENT_SHAPE_MISMATCH";
+    readonly ORB_RUI_EVENT_BINDING_PAYLOAD_MISMATCH: "ORB_RUI_EVENT_BINDING_PAYLOAD_MISMATCH";
+    readonly ORB_RUI_INVALID_FIELD_PATH: "ORB_RUI_INVALID_FIELD_PATH";
+    readonly ORB_RUI_INVALID_ITEM_ACTION: "ORB_RUI_INVALID_ITEM_ACTION";
+    readonly ORB_RUI_INVALID_PATTERN: "ORB_RUI_INVALID_PATTERN";
+    readonly ORB_RUI_INVALID_PROP: "ORB_RUI_INVALID_PROP";
+    readonly ORB_RUI_INVALID_SLOT: "ORB_RUI_INVALID_SLOT";
+    readonly ORB_RUI_MISSING_ACTION: "ORB_RUI_MISSING_ACTION";
+    readonly ORB_RUI_MISSING_PATTERN_TYPE: "ORB_RUI_MISSING_PATTERN_TYPE";
+    readonly ORB_RUI_MISSING_REQUIRED_PROP: "ORB_RUI_MISSING_REQUIRED_PROP";
+    readonly ORB_RUI_PROP_TYPE_MISMATCH: "ORB_RUI_PROP_TYPE_MISMATCH";
+    readonly ORB_RUI_UNKNOWN_ITEM_ACTION_PROP: "ORB_RUI_UNKNOWN_ITEM_ACTION_PROP";
+    readonly ORB_S_EMPTY_VERSION: "ORB_S_EMPTY_VERSION";
+    readonly ORB_S_MISSING_NAME: "ORB_S_MISSING_NAME";
+    readonly ORB_S_NO_ORBITALS: "ORB_S_NO_ORBITALS";
+    readonly ORB_SLOT_CONTENTION: "ORB_SLOT_CONTENTION";
+    readonly ORB_SLOT_CONTENTION_RUNTIME: "ORB_SLOT_CONTENTION_RUNTIME";
+    readonly ORB_SLOT_HUD_NON_GAME: "ORB_SLOT_HUD_NON_GAME";
+    readonly ORB_SLOT_INVALID_NAME: "ORB_SLOT_INVALID_NAME";
+    readonly ORB_SLOT_INVALID_NESTING: "ORB_SLOT_INVALID_NESTING";
+    readonly ORB_SLOT_MAIN_NOT_COVERED: "ORB_SLOT_MAIN_NOT_COVERED";
+    readonly ORB_SLOT_PRIORITY_CONFLICT: "ORB_SLOT_PRIORITY_CONFLICT";
+    readonly ORB_SVC_DUPLICATE_NAME: "ORB_SVC_DUPLICATE_NAME";
+    readonly ORB_SVC_INVALID_INTEGRATOR: "ORB_SVC_INVALID_INTEGRATOR";
+    readonly ORB_SVC_INVALID_URL: "ORB_SVC_INVALID_URL";
+    readonly ORB_SVC_MISSING_BASE_URL: "ORB_SVC_MISSING_BASE_URL";
+    readonly ORB_SVC_MISSING_CAPABILITIES: "ORB_SVC_MISSING_CAPABILITIES";
+    readonly ORB_SVC_MISSING_EVENTS: "ORB_SVC_MISSING_EVENTS";
+    readonly ORB_SVC_MISSING_SERVER_PATH: "ORB_SVC_MISSING_SERVER_PATH";
+    readonly ORB_SVC_RESERVED_EVENT: "ORB_SVC_RESERVED_EVENT";
+    readonly ORB_SVC_UNKNOWN_TYPE: "ORB_SVC_UNKNOWN_TYPE";
+    readonly ORB_T_CONFIG_OBJECT_ARRAY_FORBIDDEN: "ORB_T_CONFIG_OBJECT_ARRAY_FORBIDDEN";
+    readonly ORB_T_CONFIG_SHAPE_MISMATCH: "ORB_T_CONFIG_SHAPE_MISMATCH";
+    readonly ORB_T_CONFIG_TIER_INVALID: "ORB_T_CONFIG_TIER_INVALID";
+    readonly ORB_T_DEPRECATED_UI: "ORB_T_DEPRECATED_UI";
+    readonly ORB_T_DUPLICATE_NAME: "ORB_T_DUPLICATE_NAME";
+    readonly ORB_T_DUPLICATE_STATE: "ORB_T_DUPLICATE_STATE";
+    readonly ORB_T_DUPLICATE_TRANSITION: "ORB_T_DUPLICATE_TRANSITION";
+    readonly ORB_T_ENTITY_NAME_SHADOWS_TRAIT_UNION: "ORB_T_ENTITY_NAME_SHADOWS_TRAIT_UNION";
+    readonly ORB_T_EVENT_TYPE_WRONG_KIND: "ORB_T_EVENT_TYPE_WRONG_KIND";
+    readonly ORB_T_EVT_DUPLICATE: "ORB_T_EVT_DUPLICATE";
+    readonly ORB_T_EVT_EXTERNAL_MISSING_PAYLOAD: "ORB_T_EVT_EXTERNAL_MISSING_PAYLOAD";
+    readonly ORB_T_EVT_INVALID_NAME: "ORB_T_EVT_INVALID_NAME";
+    readonly ORB_T_EVT_SCOPE_MISMATCH: "ORB_T_EVT_SCOPE_MISMATCH";
+    readonly ORB_T_EVT_TICK_UNDECLARED: "ORB_T_EVT_TICK_UNDECLARED";
+    readonly ORB_T_EVT_UNDECLARED: "ORB_T_EVT_UNDECLARED";
+    readonly ORB_T_INIT_MISSING_FETCH: "ORB_T_INIT_MISSING_FETCH";
+    readonly ORB_T_INVALID_CATEGORY: "ORB_T_INVALID_CATEGORY";
+    readonly ORB_T_INVALID_FORMAT: "ORB_T_INVALID_FORMAT";
+    readonly ORB_T_INVALID_PATTERN_DEFAULT: "ORB_T_INVALID_PATTERN_DEFAULT";
+    readonly ORB_T_INVALID_SLOT_DEFAULT: "ORB_T_INVALID_SLOT_DEFAULT";
+    readonly ORB_T_INVALID_TRANSITION: "ORB_T_INVALID_TRANSITION";
+    readonly ORB_T_MISSING_INIT_TRANSITION: "ORB_T_MISSING_INIT_TRANSITION";
+    readonly ORB_T_MISSING_RENDER_UI: "ORB_T_MISSING_RENDER_UI";
+    readonly ORB_T_MULTIPLE_INITIAL_STATES: "ORB_T_MULTIPLE_INITIAL_STATES";
+    readonly ORB_T_NO_INITIAL_STATE: "ORB_T_NO_INITIAL_STATE";
+    readonly ORB_T_TYPE_ANNOTATION_MISMATCH: "ORB_T_TYPE_ANNOTATION_MISMATCH";
+    readonly ORB_T_TYPE_COMPOSITION_CONFLICT: "ORB_T_TYPE_COMPOSITION_CONFLICT";
+    readonly ORB_T_TYPE_CYCLE: "ORB_T_TYPE_CYCLE";
+    readonly ORB_T_TYPE_KIND_MISMATCH: "ORB_T_TYPE_KIND_MISMATCH";
+    readonly ORB_T_TYPE_UNKNOWN: "ORB_T_TYPE_UNKNOWN";
+    readonly ORB_T_TYPE_UNKNOWN_PARAM: "ORB_T_TYPE_UNKNOWN_PARAM";
+    readonly ORB_T_TYPE_WRONG_ARG_COUNT: "ORB_T_TYPE_WRONG_ARG_COUNT";
+    readonly ORB_T_UNDEFINED_EVENT: "ORB_T_UNDEFINED_EVENT";
+    readonly ORB_T_UNDEFINED_TRAIT: "ORB_T_UNDEFINED_TRAIT";
+    readonly ORB_UI_ICON_EMPTY: "ORB_UI_ICON_EMPTY";
+    readonly ORB_UI_ICON_INVALID_FORMAT: "ORB_UI_ICON_INVALID_FORMAT";
+    readonly ORB_UI_ICON_NOT_FOUND: "ORB_UI_ICON_NOT_FOUND";
+    readonly ORB_X_CIRCULAR_DEPENDENCY: "ORB_X_CIRCULAR_DEPENDENCY";
+    readonly ORB_X_CROSS_EMITTER_DECLARED_PAYLOAD_MISMATCH: "ORB_X_CROSS_EMITTER_DECLARED_PAYLOAD_MISMATCH";
+    readonly ORB_X_DUPLICATE_ENTITY: "ORB_X_DUPLICATE_ENTITY";
+    readonly ORB_X_EVENT_COLLISION: "ORB_X_EVENT_COLLISION";
+    readonly ORB_X_INTERNAL_EVENT_EXPOSED: "ORB_X_INTERNAL_EVENT_EXPOSED";
+    readonly ORB_X_LISTEN_SOURCE_UNRESOLVED: "ORB_X_LISTEN_SOURCE_UNRESOLVED";
+    readonly ORB_X_MISSING_ORBITAL_NAME: "ORB_X_MISSING_ORBITAL_NAME";
+    readonly ORB_X_ORPHAN_LISTENER: "ORB_X_ORPHAN_LISTENER";
+    readonly ORB_X_PAYLOAD_MISMATCH: "ORB_X_PAYLOAD_MISMATCH";
+    readonly ORB_X_RENDER_UI_EVENT_LITERAL_STALE: "ORB_X_RENDER_UI_EVENT_LITERAL_STALE";
+    readonly ORB_X_UNRESOLVED_PATTERN_FIELD_REF: "ORB_X_UNRESOLVED_PATTERN_FIELD_REF";
+    readonly ORB_X_UNUSED_EMISSION: "ORB_X_UNUSED_EMISSION";
+    readonly ORB_ID_UNKNOWN_REF: "ORB_ID_UNKNOWN_REF";
+    readonly ORB_ID_NAME_MISMATCH: "ORB_ID_NAME_MISMATCH";
+    readonly ORB_ID_KIND_MISMATCH: "ORB_ID_KIND_MISMATCH";
+    readonly ORB_ID_LEDGER_ORPHAN: "ORB_ID_LEDGER_ORPHAN";
+};
+/**
+ * Narrow union of the codes documented in `KNOWN_VALIDATION_ERROR_CODES`.
+ * Use this in exhaustive `switch` handlers; use the broader
+ * `ValidationErrorCode` (open `string`) anywhere a fresh validator-side
+ * code could plausibly arrive.
+ */
+type KnownValidationErrorCode = typeof KNOWN_VALIDATION_ERROR_CODES[keyof typeof KNOWN_VALIDATION_ERROR_CODES];
+/**
+ * Type guard: is the given code a known one? After the guard returns
+ * true, the code can be narrowed to `KnownValidationErrorCode` via a
+ * separate cast, because the type system can't track `in` against
+ * `as const` records without an explicit narrowing helper.
+ */
+declare function isKnownValidationErrorCode(code: ValidationErrorCode): boolean;
+
+/**
+ * Plan & Analysis Types
+ *
+ * Lifted from @almadar-io/rabit's coordinator types. These are the
+ * language-level contracts for the planner/analysis pipeline — the
+ * session/* and workspace/* substrate operators produce and consume
+ * these shapes. Defined here (not in rabit) so both the compiled path
+ * (orbital-rust codegen → @almadar/server) and the interpreted path
+ * (@almadar/runtime) reference the same types without depending on rabit.
+ *
+ * @packageDocumentation
+ */
+
+type ClarificationLevel = 'organism' | 'molecule' | 'atom_trait';
+interface ClarificationCandidate {
+    id: string;
+    label: string;
+    description: string;
+    whyThisFits: string;
+}
+interface Clarification {
+    level: ClarificationLevel;
+    scope: {
+        orbitalName?: string;
+        traitName?: string;
+    };
+    question: string;
+    candidates: ClarificationCandidate[];
+    skipDefault: string;
+    skippable: true;
+}
+interface AnalysisPageOverride {
+    name: string;
+    path?: string;
+    linkedEntity?: string;
+    traits?: PageTraitRef[];
+}
+interface ExtraTraitRef extends Pick<TraitReference, 'ref' | 'name' | 'linkedEntity' | 'config' | 'events' | 'listens' | 'emitsScope'> {
+    from: string;
+    as: string;
+}
+interface AnalysisOrbitalParams {
+    fields?: EntityField[];
+    pagePath?: string;
+    persistence?: EntityPersistence;
+    entityName?: string;
+    collection?: string;
+    traitOverrides?: Record<string, Pick<MakeTraitRefOpts, 'config' | 'linkedEntity' | 'events' | 'name' | 'emitsScope' | 'listens'>>;
+    extraTraits?: ExtraTraitRef[];
+    pages?: AnalysisPageOverride[];
+}
+interface AnalysisOrbital {
+    orbitalName: string;
+    suggestedBehavior: string | null;
+    entityName?: string;
+    pageNames?: ReadonlyArray<string>;
+    params?: AnalysisOrbitalParams;
+    traitOverlay?: TraitOverlay;
+    paletteTopics?: string[];
+    primitiveHints?: string[];
+}
+interface AnalysisRename {
+    oldName: string;
+    newName: string;
+}
+interface ComplexityAssessment {
+    score: number;
+    category: 'simple' | 'moderate' | 'complex';
+    reasoning: string;
+    detectedEntities?: string[];
+    detectedFeatures?: string[];
+}
+interface AnalysisResult {
+    userRequest: string;
+    complexity: ComplexityAssessment;
+    route: 'direct' | 'direct_with_questions' | 'decompose';
+    organism: string;
+    appName: string;
+    organismReason: string;
+    orbitals: AnalysisOrbital[];
+    renames?: AnalysisRename[];
+    deletedOrbitals?: string[];
+    ruleOverlay?: RuleOverlay;
+    estimatedMinutes?: number;
+    schema: OrbitalSchema;
+    wiring?: EventWiringEntry[];
+    layout?: LayoutStrategy | 'detect';
+    themeOverrides?: Partial<ThemeDefinition>;
+    pendingClarifications?: Clarification[];
+}
+interface SpawnResult {
+    orbitalName: string;
+    ok: boolean;
+    traitNames: ReadonlyArray<string>;
+    error?: string;
+    durationMs: number;
+}
+type PlanSnapshotStatus = 'proposed' | 'confirmed' | 'built' | 'failed';
+interface PlanSnapshot {
+    schemaVersion: 1;
+    status: PlanSnapshotStatus;
+    builtAt: string;
+    organism: string | null;
+    appName: string | null;
+    organismReason: string | null;
+    complexity: ComplexityAssessment | null;
+    themeOverrides: Partial<ThemeDefinition>;
+    ruleOverlay: RuleOverlay | null;
+    orbitals: ReadonlyArray<AnalysisOrbital>;
+    renames: ReadonlyArray<AnalysisRename>;
+    deletedOrbitals: ReadonlyArray<string>;
+    priorBuiltOrbitals: ReadonlyArray<AnalysisOrbital>;
+    spawnedOrbitalResults: ReadonlyArray<SpawnResult>;
+    skippedOrbitalNames: ReadonlyArray<string>;
+    pendingClarifications: ReadonlyArray<Clarification>;
+    paletteTopics?: string[];
+}
+/**
+ * Runtime guard for `PlanSnapshot` — narrows interpreter-produced `unknown`
+ * values at the `WorkspaceContext.writePlan` boundary. Discriminates on the
+ * snapshot envelope (schemaVersion, status, roster arrays), not deep contents.
+ */
+declare function isPlanSnapshot(value: RuntimeValue): value is PlanSnapshot;
+interface ComposeOptions {
+    appName?: string;
+    wiring?: EventWiringEntry[];
+    layout?: LayoutStrategy | 'auto';
+    themeOverrides?: Partial<ThemeDefinition>;
+}
+interface GitHubRepo {
+    id: number;
+    name: string;
+    full_name: string;
+    owner: {
+        login: string;
+    };
+    private: boolean;
+    html_url: string;
+    description: string | null;
+    default_branch: string;
+    clone_url: string;
+}
+interface GitHubIssue {
+    id: number;
+    number: number;
+    title: string;
+    body: string | null;
+    state: 'open' | 'closed';
+    html_url: string;
+    user: {
+        login: string;
+    };
+    created_at: string;
+    updated_at: string;
+}
+
+/**
+ * Agent Types
+ *
+ * Defines the AgentContext interface and related types for the agent/* operator namespace.
+ * These types are the contract between operators (language) and implementation (runtime).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Categories for agent memories.
+ */
+type AgentMemoryCategory = 'preference' | 'correction' | 'pattern-affinity' | 'entity-template' | 'error-resolution';
+/**
+ * A single memory record stored by the agent.
+ */
+interface AgentMemoryRecord {
+    /** Unique memory identifier */
+    id: string;
+    /** Memory content (natural language) */
+    content: string;
+    /** Memory category */
+    category: AgentMemoryCategory;
+    /** Strength value (0.0-1.0), decays over time unless pinned */
+    strength: number;
+    /** Whether this memory is pinned (immune to decay) */
+    pinned: boolean;
+    /** Memory scope */
+    scope: 'global' | 'project';
+    /** ISO timestamp of last access */
+    lastAccessedAt: string;
+    /** ISO timestamp of creation */
+    createdAt: string;
+}
+/**
+ * Strategy for context compaction.
+ */
+type AgentCompactStrategy = 'hybrid' | 'summarize' | 'truncate' | 'extract';
+/**
+ * Result of a context compaction operation.
+ */
+interface AgentCompactResult {
+    /** Token count before compaction */
+    before: number;
+    /** Token count after compaction */
+    after: number;
+    /** Strategy used */
+    strategy: AgentCompactStrategy;
+    /** Optional summary generated during compaction */
+    summary?: string;
+}
+/**
+ * Options for agent/generate calls.
+ */
+interface AgentGenerateOptions {
+    /** LLM provider override */
+    provider?: string;
+    /** Model override */
+    model?: string;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+}
+/**
+ * A message in an LLM tool-calling conversation.
+ */
+interface LlmMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    /** Present on assistant messages that called tools. */
+    toolCalls?: ReadonlyArray<LlmToolCall>;
+    /** Present on tool-role messages — matches the preceding toolCall's id. */
+    toolCallId?: string;
+}
+/**
+ * A tool call requested by the assistant.
+ */
+interface LlmToolCall {
+    id: string;
+    name: string;
+    /** JSON-encoded arguments string (as returned by the LLM). */
+    arguments: string;
+}
+/**
+ * A tool definition passed to llm/call-tools.
+ */
+interface LlmToolDef {
+    name: string;
+    description: string;
+    /** JSON Schema describing the tool's parameters. */
+    parameters: JsonSchema;
+}
+/**
+ * Result of llm/call-tools.
+ */
+interface LlmCallToolsResult {
+    /** The assistant's text response (may be empty when only tool_calls fired). */
+    content: string;
+    /** Tool calls the assistant requested, if any. */
+    toolCalls?: ReadonlyArray<LlmToolCall>;
+    /** Token usage from the call. */
+    usage: LlmTokenUsage;
+}
+/**
+ * Token usage from an LLM call.
+ */
+interface LlmTokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/**
+ * Result from agent/search-code.
+ */
+interface AgentCodeSearchResult {
+    /** Repository name (owner/repo) */
+    repo: string;
+    /** File path within the repository */
+    path: string;
+    /** URL to the file */
+    url: string;
+}
+/** Result of behavior/instantiate (factory path) or subagent build. */
+interface BuilderResult {
+    method: string;
+    orbitalName: string;
+    success: boolean;
+    orbitalPath?: string;
+    traitCount?: number;
+    traitNames?: string[];
+    transitionCount?: number;
+    childCount?: number;
+    error?: string;
+}
+/** Result of validate/validate for a single orbital or the composed schema. */
+interface ValidateResult {
+    valid: boolean;
+    errorCount: number;
+    errors: ValidationError[];
+    orbitalName?: string;
+}
+/** Result of compose/compose-all. */
+interface ComposeAllResult {
+    orbitalCount: number;
+    composedPath: string;
+    success: boolean;
+    layout?: string;
+    wiringConnections?: number;
+}
+/** Result of compose/compose-children (recursive builds). */
+interface ComposeChildrenResult {
+    parentName: string;
+    childCount: number;
+    orbitalName: string;
+    success: boolean;
+}
+/** Result of the repair service. */
+interface RepairResult {
+    orbitalName: string;
+    success: boolean;
+    attempt: number;
+    paramsChanged: boolean;
+    error?: string;
+}
+/** Result of lolo/emit-body (free-lolo path). */
+interface LoloEmitResult {
+    orbitalName: string;
+    success: boolean;
+    loloSource: string;
+    error?: string;
+}
+/** Result of the planner service. */
+interface PlannerResult {
+    organism: string;
+    operationCount: number;
+    pendingQuestions: boolean;
+    cached: boolean;
+    success: boolean;
+    error?: string;
+}
+/** Result of the executor (spawn-subagents). */
+interface ExecutePlanResult {
+    dispatchedOrbitals: string[];
+    noopForBuild: boolean;
+    success: boolean;
+    error?: string;
+}
+/** Result of dispatch-updates. */
+interface DispatchUpdatesResult {
+    updatedOrbitals: string[];
+    updateCount: number;
+    success: boolean;
+}
+/** Discriminated union of all substrate service-call results. */
+type ServiceCallResult = BuilderResult | ValidateResult | ComposeAllResult | ComposeChildrenResult | RepairResult | LoloEmitResult | PlannerResult | ExecutePlanResult | DispatchUpdatesResult;
+/** A single entry in an orbital's session history (build/conversation log). */
+interface SessionHistoryEntry {
+    /** Role of the entry's author (e.g. 'user', 'assistant', 'system') */
+    role: string;
+    /** Entry content (natural language or structured description) */
+    content: string;
+    /** Epoch milliseconds when the entry was recorded */
+    timestamp: number;
+}
+/**
+ * Runtime guard for `SessionHistoryEntry` — narrows interpreter-produced
+ * `unknown` values at the `SessionContext.appendHistory` boundary.
+ */
+declare function isSessionHistoryEntry(value: RuntimeValue): value is SessionHistoryEntry;
+/**
+ * AgentContext is the runtime contract for agent/* operators.
+ *
+ * The evaluator dispatches agent/* operators to methods on this interface.
+ * Pure methods (usable in guards) return synchronously.
+ * Effect methods return Promises.
+ *
+ * When ctx.agent is undefined, operators return safe defaults ([], 0, false, "").
+ * Implementations live in @almadar-io/agent-runtime (Phase 2B).
+ */
+interface AgentContext {
+    recall(query: string, limit?: number): AgentMemoryRecord[];
+    memories(category?: AgentMemoryCategory): AgentMemoryRecord[];
+    memoryStrength(id: string): number;
+    isPinned(id: string): boolean;
+    memorize(content: string, category: AgentMemoryCategory, scope?: 'global' | 'project'): Promise<string>;
+    forget(id: string): Promise<void>;
+    pin(id: string): Promise<void>;
+    reinforce(id: string): Promise<void>;
+    decay(): Promise<number>;
+    provider(): string;
+    model(): string;
+    generate(prompt: string, options?: AgentGenerateOptions): Promise<string>;
+    switchProvider(provider: string, model?: string): void;
+    tools(): string[];
+    invoke(toolName: string, args: ServiceParams): Promise<EventPayloadValue>;
+    tokenCount(): number;
+    contextUsage(): number;
+    compact(strategy?: AgentCompactStrategy): Promise<AgentCompactResult>;
+    sessionId(): string;
+    fork(label?: string): Promise<string>;
+    label(text: string): void;
+    searchCode(query: string, language?: string): Promise<AgentCodeSearchResult[]>;
+}
+/** Backs the llm/* operators (6 ops). */
+interface LlmContext {
+    generate(prompt: string, options?: {
+        json?: boolean;
+        maxTokens?: number;
+        provider?: string;
+        model?: string;
+    }): Promise<string>;
+    callTools(messages: LlmMessage[], tools: LlmToolDef[]): Promise<LlmCallToolsResult>;
+    embed(texts: string[]): Promise<number[][]>;
+    tokenCount(): number;
+    switchProvider(provider: string, model?: string): void;
+    compact(strategy?: string): Promise<{
+        before: number;
+        after: number;
+    }>;
+}
+/** Backs the workspace/* operators (11 ops). */
+interface WorkspaceContext {
+    readOrbital(name: string): Promise<Orbital>;
+    writeOrbital(name: string, content: Orbital): Promise<void>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    exists(path: string): boolean;
+    listOrbitals(): string[];
+    readSchema(): Promise<OrbitalSchema>;
+    writeSchema(schema: OrbitalSchema): Promise<void>;
+    readPlan(): Promise<PlanSnapshot>;
+    writePlan(plan: PlanSnapshot): Promise<void>;
+    archiveOrbital(name: string): Promise<void>;
+}
+/** Backs the session/* operators (9 ops). */
+interface SessionContext {
+    readSpec(orbitalName: string): Promise<Orbital>;
+    writeSpec(orbitalName: string, spec: Orbital): Promise<void>;
+    readMemory(orbitalName: string): Promise<AgentMemoryRecord[]>;
+    writeMemory(orbitalName: string, memory: AgentMemoryRecord[]): Promise<void>;
+    readHistory(orbitalName: string): Promise<SessionHistoryEntry[]>;
+    appendHistory(orbitalName: string, entry: SessionHistoryEntry): Promise<void>;
+    readErrors(orbitalName: string): Promise<string[]>;
+    writeErrors(orbitalName: string, errors: string[]): Promise<void>;
+    readAnalysis(orbitalName: string): Promise<AnalysisResult>;
+}
+/** Backs the memory/* operators (3 ops). */
+interface MemoryContext {
+    recall(query: string, limit?: number): AgentMemoryRecord[];
+    store(content: string, category?: string, strength?: number): Promise<string>;
+    list(category?: string): AgentMemoryRecord[];
+}
+/** Backs the trace/* operators (2 ops). */
+interface TraceContext {
+    emit(event: string, payload?: EventPayloadValue): void;
+    log(message: string, level?: 'log' | 'warn' | 'error', data?: EventPayloadValue): void;
+}
+/** Backs the integration/* operators (3 ops). */
+interface IntegrationContext {
+    http(method: string, url: string, body?: FieldValue, headers?: Record<string, string>): Promise<JsonValue>;
+    githubGetRepo(owner: string, repo: string): Promise<GitHubRepo>;
+    githubCreateIssue(owner: string, repo: string, title: string, body?: string): Promise<GitHubIssue>;
+}
+
+/**
+ * Interaction Model Types
+ *
+ * Defines how users interact with entities in the application.
+ * Used to drive trait selection and UI slot usage.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Create flow - how new items are created
+ */
+type CreateFlow = 'modal' | 'page' | 'inline' | 'none';
+/**
+ * Edit flow - how items are edited
+ */
+type EditFlow = 'modal' | 'page' | 'inline' | 'none';
+/**
+ * View flow - how item details are viewed
+ */
+type ViewFlow = 'drawer' | 'page' | 'modal' | 'inline' | 'none';
+/**
+ * Delete flow - how items are deleted
+ */
+type DeleteFlow = 'confirm' | 'instant' | 'none';
+/**
+ * List interaction - what happens when clicking list items
+ */
+type ListInteraction = 'click-to-view' | 'click-to-edit' | 'inline-edit';
+/**
+ * InteractionModel - defines how users interact with entities.
+ *
+ * This drives:
+ * - Which traits to attach (EntityManagement, ModalEdit, etc.)
+ * - How render_ui effects target slots (modal, drawer, page)
+ * - What UI patterns to use
+ */
+interface InteractionModel {
+    /** How new items are created */
+    createFlow: CreateFlow;
+    /** How items are edited */
+    editFlow: EditFlow;
+    /** How item details are viewed */
+    viewFlow: ViewFlow;
+    /** How items are deleted */
+    deleteFlow: DeleteFlow;
+    /** What happens when clicking list items */
+    listInteraction?: ListInteraction;
+    /** Enable bulk actions (select multiple, delete all) */
+    bulkActions?: boolean;
+    /** Enable real-time updates */
+    realtime?: boolean;
+}
+declare const InteractionModelSchema: z.ZodObject<{
+    createFlow: z.ZodEnum<["modal", "page", "inline", "none"]>;
+    editFlow: z.ZodEnum<["modal", "page", "inline", "none"]>;
+    viewFlow: z.ZodEnum<["drawer", "page", "modal", "inline", "none"]>;
+    deleteFlow: z.ZodEnum<["confirm", "instant", "none"]>;
+    listInteraction: z.ZodOptional<z.ZodEnum<["click-to-view", "click-to-edit", "inline-edit"]>>;
+    bulkActions: z.ZodOptional<z.ZodBoolean>;
+    realtime: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    createFlow: "page" | "none" | "inline" | "modal";
+    editFlow: "page" | "none" | "inline" | "modal";
+    viewFlow: "page" | "none" | "inline" | "modal" | "drawer";
+    deleteFlow: "none" | "instant" | "confirm";
+    bulkActions?: boolean | undefined;
+    listInteraction?: "click-to-view" | "click-to-edit" | "inline-edit" | undefined;
+    realtime?: boolean | undefined;
+}, {
+    createFlow: "page" | "none" | "inline" | "modal";
+    editFlow: "page" | "none" | "inline" | "modal";
+    viewFlow: "page" | "none" | "inline" | "modal" | "drawer";
+    deleteFlow: "none" | "instant" | "confirm";
+    bulkActions?: boolean | undefined;
+    listInteraction?: "click-to-view" | "click-to-edit" | "inline-edit" | undefined;
+    realtime?: boolean | undefined;
+}>;
+/**
+ * Default interaction models for each domain type
+ */
+declare const DEFAULT_INTERACTION_MODELS: Record<string, InteractionModel>;
+/**
+ * Gets the interaction model for a domain.
+ *
+ * Retrieves the appropriate interaction model configuration based on the
+ * specified domain. Falls back to the business model if no specific
+ * domain match is found.
+ *
+ * @param {string} domain - Domain name (e.g., 'healthcare', 'education')
+ * @returns {InteractionModel} Interaction model configuration
+ *
+ * @example
+ * getInteractionModelForDomain('healthcare'); // returns healthcare-specific model
+ * getInteractionModelForDomain('unknown'); // returns business fallback model
+ */
+declare function getInteractionModelForDomain(domain: string): InteractionModel;
+type InteractionModelInput = z.input<typeof InteractionModelSchema>;
+
+/**
+ * Pattern Type for Orbital Units
+ *
+ * Re-exports pattern type definitions from @almadar/core/patterns,
+ * which is the single source of truth for all pattern types.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Zod schema for pattern types.
+ * Accepts any string - validation against full registry happens at runtime.
+ */
+declare const PatternTypeSchema: z.ZodString;
+
+/**
+ * Changeset & Snapshot Types
+ *
+ * Unified types for schema change tracking, snapshots, and removal categorization.
+ * Used by @almadar/server for Firestore storage and by consumers for type safety.
+ */
+
+/**
+ * Value attached to a SchemaChange entry's `before` / `after`.
+ *
+ * Either a JSON-shaped LLM payload (`EventPayloadValue`), a single schema
+ * fragment (`Orbital`, `Trait`, `Entity`, `Page`, `OrbitalSchema`), or an
+ * array of such fragments. Mirrors the exact shapes the builder's changeset
+ * writers actually persist when adding/replacing a slice of the schema.
+ */
+type ChangesetValue = EventPayloadValue | OrbitalSchema | Orbital | Trait | Entity | Page | Orbital[] | Trait[] | Entity[] | Page[];
+/**
+ * A single change within a changeset.
+ */
+interface SchemaChange {
+    id: string;
+    operation: 'add' | 'modify' | 'remove' | 'rename';
+    target: string;
+    path: (string | number)[];
+    before?: ChangesetValue;
+    after?: ChangesetValue;
+    description: string;
+    reason?: string;
+    dependsOn?: string[];
+}
+/**
+ * Author of a changeset.
+ */
+interface ChangeAuthor {
+    type: 'agent' | 'user';
+    id?: string;
+    name?: string;
+}
+/**
+ * Summary statistics for a changeset.
+ */
+interface ChangeSummary {
+    added: number;
+    modified: number;
+    removed: number;
+    description: string;
+}
+/**
+ * Complete changeset document.
+ * Stored at: users/{uid}/apps/{appId}/changesets/{changeSetId}
+ */
+interface ChangeSetDocument {
+    id: string;
+    version: number;
+    timestamp: number;
+    source: 'requirements-agent' | 'builder-agent' | 'user' | 'auto-fix';
+    author: ChangeAuthor;
+    trigger?: string;
+    changes: SchemaChange[];
+    summary: ChangeSummary;
+    status: 'applied' | 'reverted' | 'pending';
+    description: string;
+}
+/**
+ * Schema snapshot document.
+ * Stored at: users/{uid}/apps/{appId}/snapshots/{snapshotId}
+ */
+interface SnapshotDocument {
+    id: string;
+    timestamp: number;
+    schema: OrbitalSchema;
+    reason: string;
+    version?: number;
+}
+/**
+ * Removals categorized by severity.
+ */
+interface CategorizedRemovals {
+    /** States, pages, entities — always require confirmation */
+    critical: SchemaChange[];
+    /** Fields, actions — auto-snapshotted */
+    standard: SchemaChange[];
+    /** Transitions, guards — tracked */
+    minor: SchemaChange[];
+    /** Implicit content removal within pages */
+    pageContentReductions: PageContentReduction[];
+}
+/**
+ * Detected reduction in page content (components, actions, displays removed).
+ */
+interface PageContentReduction {
+    pageName: string;
+    componentsRemoved: number;
+    actionsRemoved: number;
+    displaysRemoved: number;
+    before: {
+        sections: number;
+        actions: number;
+    };
+    after: {
+        sections: number;
+        actions: number;
+    };
+    isSignificant: boolean;
+}
+/**
+ * History metadata stored in main app document for quick access.
+ */
+interface HistoryMeta {
+    latestSnapshotId?: string;
+    latestChangeSetId?: string;
+    snapshotCount: number;
+    changeSetCount: number;
+}
+/**
+ * Validation metadata stored in main app document for quick access.
+ */
+interface ValidationMeta {
+    errorCount: number;
+    warningCount: number;
+    validatedAt: number;
+}
+/**
+ * What kind of .orb concept changed between two schema versions.
+ * Used by canvas focus derivation, CLI narration, selective re-verification.
+ */
+type SemanticChangeKind = 'orbital-added' | 'orbital-removed' | 'entity-fields-changed' | 'trait-added' | 'trait-removed' | 'state-machine-changed' | 'guard-changed' | 'effect-changed' | 'render-ui-changed' | 'event-wiring-changed' | 'page-changed' | 'behavior-composed';
+/**
+ * A semantic change between two OrbitalSchema versions.
+ * Identifies WHAT concept changed and WHERE in the schema.
+ */
+interface SemanticSchemaChange {
+    kind: SemanticChangeKind;
+    orbitalName: string;
+    traitName?: string;
+    transitionEvent?: string;
+    fieldName?: string;
+}
+
+/**
+ * App-Level Types
+ *
+ * Types for app summaries, stats, and save operations.
+ */
+
+/**
+ * GitHub repository link metadata stored in Firestore.
+ * Enables GitHub as the source of truth for schema files.
+ */
+interface GitHubLink {
+    repoUrl: string;
+    owner: string;
+    repo: string;
+    defaultBranch: string;
+    connectedAt: number;
+    schemaFile?: string;
+}
+/**
+ * Dashboard stats derived from schema.
+ */
+interface StatsView {
+    states: number;
+    events: number;
+    pages: number;
+    entities: number;
+    transitions: number;
+}
+/**
+ * App summary for list views.
+ */
+interface AppSummary {
+    id: string;
+    name: string;
+    description?: string;
+    updatedAt: number;
+    createdAt: number;
+    stats: StatsView;
+    domain?: {
+        category: string;
+        subDomain?: string;
+    };
+    /**
+     * Canonical domain classification + vocabulary projected onto the list
+     * view. Same shape as `OrbitalSchema.domainContext`.
+     */
+    domainContext?: DomainContext;
+    hasValidationErrors: boolean;
+    github?: GitHubLink;
+}
+/**
+ * Options for saving a schema.
+ */
+interface SaveOptions {
+    confirmRemovals?: boolean;
+    snapshotReason?: string;
+    skipProtection?: boolean;
+    expectedVersion?: number;
+    source?: 'requirements-agent' | 'builder-agent' | 'manual';
+}
+/**
+ * Result of saving a schema.
+ */
+interface SaveResult {
+    success: boolean;
+    requiresConfirmation?: boolean;
+    removals?: CategorizedRemovals;
+    error?: string;
+    snapshotId?: string;
+}
+/**
+ * Context attached to validation issues originating from LLM output.
+ * Mirrors the `LLMErrorContext` shapes used by `@almadar/validation`
+ * and the builder's fix-prompt pipeline.
+ */
+interface LLMErrorContext {
+    /** Preview of the raw LLM output */
+    rawValuePreview?: string;
+    /** Expected type or structure */
+    expectedType?: string;
+    /** Actual type received */
+    actualType?: string;
+    /** Where the error originated */
+    source?: {
+        agent: 'requirements' | 'builder' | 'view-planner';
+        operation: string;
+        promptHash?: string;
+    };
+    tokenUsage?: {
+        prompt: number;
+        completion: number;
+    };
+}
+/**
+ * Validation issue with optional LLM context.
+ */
+interface ValidationIssue {
+    code: string;
+    message: string;
+    path: (string | number)[];
+    severity: 'error' | 'warning' | 'info';
+    suggestion?: string;
+    llmContext?: LLMErrorContext;
+}
+/**
+ * Validation results.
+ */
+interface ValidationResults {
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+    validatedAt: number;
+}
+/**
+ * Validation document stored in subcollection.
+ */
+interface ValidationDocument {
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+    validatedAt: number;
+}
+
+/**
+ * Service Contract Types
+ *
+ * Formalizes the two public surfaces of an Almadar service:
+ * 1. Call-Service Contract — what the .orb schema can invoke on the TypeScript package
+ * 2. Event Contract — what events enter/leave the service
+ *
+ * Plus internal-but-standardized patterns:
+ * 3. StoreContract — database abstraction boundary
+ * 4. LazyService — singleton lifecycle pattern
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * All known service action names across all contracts.
+ * Kept in sync with `tools/almadar-service-sync/services-registry.json`.
+ *
+ * Persist operations are listed separately because they also appear
+ * as `EffectResult.action` for persist effects.
+ */
+type PersistActionName = "create" | "update" | "delete" | "list" | "query";
+/**
+ * Union of all service action names across the registered service contracts.
+ */
+type ServiceActionName = PersistActionName | "get" | "getById" | "set" | "remove" | "size" | "generate" | "classify" | "extract" | "summarize" | "send" | "sendMessage" | "sendSMS" | "sendWhatsApp" | "authorize" | "revoke" | "token" | "refresh" | "userinfo" | "register" | "cloneRepo" | "commit" | "createBranch" | "createPR" | "getPRComments" | "pull" | "push" | "build" | "compile" | "compileSchema" | "run" | "validate" | "validateSchema" | "publish" | "enqueue" | "dequeue" | "cancel" | "upload" | "download" | "getSignedUrl" | "search" | "getIssue" | "listIssues" | "generateAll" | "generateDomainLanguage" | "generateFix" | "generateOrbitals" | "cancelGeneration" | "getGenerationHistory" | "recordGeneration" | "startSpan" | "endSpan" | "getSpan" | "recordMetric" | "getMetrics" | "increment" | "logs" | "addEvent" | "emit" | "findEmitters" | "findListeners" | "getListenerCounts" | "getChannel" | "subscribe" | "getUserPreferences" | "updateUserPreferences" | "getThreadHistory" | "listDocuments" | "fetchDocument" | "getVideo" | "createPaymentIntent" | "confirmPayment" | "refund" | "complete" | "fail" | "expire" | "resume" | "status" | "stop" | "lock" | "unlock" | "clear";
+/**
+ * Action definition for a service contract.
+ *
+ * - `params` is bus-payload-shaped (`ServiceParams`): JSON-serializable
+ *   key/value bag with optional nesting. Service contracts override this
+ *   with stricter shapes via the generic position on `ServiceContract`.
+ *
+ * - `result` is JSON-serializable too (`EventPayloadValue`): a primitive,
+ *   `null`/`undefined`, an array of values, or an `EventPayload` object.
+ *   This is the same recursive shape the bus accepts when an effect's
+ *   `success` event fires with the call-service result, so no boundary
+ *   widening is needed when the runtime forwards the value.
+ */
+interface ServiceAction {
+    params: ServiceParams;
+    result: EventPayloadValue;
+}
+/**
+ * What `["call-service", "name", "action", {...}]` actually calls at runtime.
+ * Each service defines its action map as a Record<string, ServiceAction>.
+ *
+ * @example
+ * ```typescript
+ * type LLMActions = {
+ *   generate: {
+ *     params: { userPrompt: string; model: string; maxTokens: number };
+ *     result: { content: string; tokensUsed: number; latencyMs: number };
+ *   };
+ * };
+ *
+ * class LLMService implements ServiceContract<LLMActions> {
+ *   async execute(action, params) { ... }
+ * }
+ * ```
+ */
+interface ServiceContract<Actions extends Record<string, ServiceAction>> {
+    execute<A extends keyof Actions & string>(action: A, params: Actions[A]["params"]): Promise<Actions[A]["result"]>;
+}
+/**
+ * Event contract — what events the service emits/listens with typed payloads.
+ * Derived from the `.orb` schema's `emits` and `listens` declarations.
+ *
+ * @example
+ * ```typescript
+ * type LLMEventMap = {
+ *   AGENT_LLM_REQUEST: { requestId: string; prompt: string };
+ *   LLM_RESPONSE: { requestId: string; content: string; tokensUsed: number };
+ *   LLM_ERROR: { requestId: string; error: string };
+ * };
+ *
+ * const events: ServiceEvents<LLMEventMap> = getEventBus();
+ * events.emit('LLM_RESPONSE', { requestId: '1', content: '...', tokensUsed: 42 });
+ * ```
+ */
+interface ServiceEvents<EventMap extends Record<string, EventPayload>> {
+    emit<E extends keyof EventMap & string>(event: E, payload: EventMap[E]): void;
+    on<E extends keyof EventMap & string>(event: E, handler: (payload: EventMap[E]) => void): () => void;
+}
+/**
+ * Create a typed view of an untyped EventBus. Wraps the raw EventBus
+ * with compile-time type checking while keeping runtime behavior identical.
+ *
+ * @example
+ * ```typescript
+ * type LLMEventMap = {
+ *   LLM_RESPONSE: { requestId: string; content: string };
+ *   LLM_ERROR: { requestId: string; error: string };
+ * };
+ *
+ * const typedBus = createTypedEventBus<LLMEventMap>(getServerEventBus());
+ * typedBus.emit('LLM_RESPONSE', { requestId: '1', content: '...' }); // type-safe
+ * typedBus.on('LLM_ERROR', (payload) => { payload.error; }); // payload is typed
+ * ```
+ */
+/**
+ * Creates a typed event bus from an untyped bus implementation.
+ *
+ * This wrapper adds TypeScript type safety to event emission and listening.
+ * The generic `EventMap` defines the shape of all events and their payloads.
+ *
+ * @template EventMap - Type mapping event names to their payload types
+ * @param {Object} bus - Untyped event bus implementation
+ * @param {Function} bus.emit - Function to emit events
+ * @param {Function} bus.on - Function to listen to events
+ * @returns {ServiceEvents<EventMap>} Typed event bus interface
+ *
+ * @example
+ * interface MyEvents {
+ *   'user.created': { id: string; name: string };
+ *   'user.deleted': { id: string };
+ * }
+ *
+ * const typedBus = createTypedEventBus<MyEvents>(rawBus);
+ * typedBus.emit('user.created', { id: '123', name: 'Alice' });
+ */
+declare function createTypedEventBus<EventMap extends Record<string, EventPayload>>(bus: {
+    emit(event: string, payload?: unknown, meta?: LogMeta): void;
+    on(event: string, handler: (payload: unknown, meta?: LogMeta) => void): () => void;
+}): ServiceEvents<EventMap>;
+/** Filter operator for store queries. */
+type StoreFilterOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "contains";
+/** A single filter clause for store queries. */
+interface StoreFilter<T> {
+    field: keyof T & string;
+    op: StoreFilterOp;
+    value: unknown;
+}
+/**
+ * Database abstraction boundary. Services receive `StoreContract<T>`,
+ * not raw database clients. Swappable per database engine.
+ *
+ * @example
+ * ```typescript
+ * interface LLMRequest { id: string; prompt: string; status: string }
+ *
+ * class FirestoreLLMRequestStore implements StoreContract<LLMRequest> {
+ *   async getById(id) { ... }
+ *   async create(data) { ... }
+ *   async update(id, data) { ... }
+ *   async delete(id) { ... }
+ *   async query(filters) { ... }
+ * }
+ * ```
+ */
+interface StoreContract<T extends {
+    id: string;
+}> {
+    getById(id: string): Promise<T | null>;
+    create(data: Omit<T, "id">): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<T>;
+    delete(id: string): Promise<void>;
+    query(filters: StoreFilter<T>[]): Promise<T[]>;
+}
+/**
+ * Standardized singleton lifecycle. Replaces ad-hoc
+ * `let x = null; export function getX()` patterns.
+ *
+ * @example
+ * ```typescript
+ * const llmClient = createLazyService(() => new LLMClient({ apiKey: process.env.LLM_KEY }));
+ *
+ * // In request handler:
+ * const client = llmClient.get(); // created on first call, cached after
+ *
+ * // In test teardown:
+ * llmClient.reset(); // next get() creates a fresh instance
+ * ```
+ */
+interface LazyService<T> {
+    /** Get the singleton instance (creates on first call). */
+    get(): T;
+    /** Reset the singleton (next get() creates fresh). For test isolation. */
+    reset(): void;
+}
+/**
+ * Create a lazy singleton from a factory function.
+ *
+ * Creates a service that lazily initializes on first access and caches the instance.
+ * Useful for expensive resources like database connections or API clients.
+ *
+ * @template T - The type of service to create
+ * @param {() => T} factory - Factory function that creates the service instance
+ * @returns {LazyService<T>} Lazy service with get() and reset() methods
+ *
+ * @example
+ * const dbService = createLazyService(() => new DatabaseClient(config));
+ * const db = dbService.get(); // Initializes on first call
+ */
+declare function createLazyService<T>(factory: () => T): LazyService<T>;
+
+/**
+ * Transition source state specification.
+ * - string: Single state name (e.g., 'Idle')
+ * - '*': Wildcard - matches any current state
+ * - string[]: Array of states - matches any of the listed states
+ */
+type TransitionFrom = string | '*' | string[];
+interface ResolvedField {
+    name: string;
+    type: string;
+    tsType: string;
+    description?: string;
+    /** Field default — JSON-shaped, mirroring `EntityField.default`. */
+    default?: JsonValue;
+    required: boolean;
+    /** Validation constraints carried from the schema (enum whitelist). */
+    validation?: {
+        enum?: string[];
+    };
+    /** Enum values for enum or constrained string fields */
+    values?: string[];
+    /** Enum values (alias for values, for compatibility) */
+    enumValues?: string[];
+    /** Relation configuration for foreign key references */
+    relation?: {
+        entity: string;
+        cardinality?: string;
+        field?: string;
+    };
+}
+interface ResolvedEntity {
+    name: string;
+    description?: string;
+    icon?: string;
+    collection: string;
+    fields: ResolvedField[];
+    /** Whether this entity only exists in runtime (not persisted to Firestore) */
+    runtime?: boolean;
+    /** Whether this entity's state is shared across every bound trait (vs a per-trait copy). Orthogonal to `runtime`. */
+    shared?: boolean;
+    /** Whether this entity has pre-authored instances in the schema */
+    hasInstances?: boolean;
+    /** Pre-authored instances from the schema (seed data or static reference data) */
+    instances?: EntityRow[];
+    /** Default field values from schema (for spawning singletons) */
+    defaults?: Record<string, FieldValue>;
+    usedByTraits: string[];
+    usedByPages: string[];
+}
+interface ResolvedEntityBinding {
+    /** Binding name in code */
+    name: string;
+    /** Entity being bound */
+    entity: ResolvedEntity;
+    /** CRUD operations to generate */
+    operations: ('list' | 'get' | 'create' | 'update' | 'delete')[];
+}
+interface ResolvedTraitState {
+    name: string;
+    isInitial: boolean;
+    isFinal: boolean;
+}
+interface ResolvedTraitEvent {
+    key: string;
+    name: string;
+    payload?: Record<string, string>;
+}
+interface ResolvedTraitTransition {
+    /** Source state(s): string, '*' for wildcard, or array of states */
+    from: TransitionFrom;
+    to: string;
+    event: string;
+    guard?: SExpr;
+    effects: SExpr[];
+}
+interface ResolvedTraitGuard {
+    name: string;
+    condition: SExpr;
+}
+interface ResolvedTraitTick {
+    name: string;
+    /**
+     * `number` (ms), `'frame'`, a duration string (`'5s'`/`'1m'`/`'1h'`), or a
+     * 5-field cron expression (`'0 9 * * *'`) — `schema-to-ir.ts`'s
+     * `interval: tick.interval || 0` passes the source schema's raw
+     * `string | number` straight through with no normalization, so this must
+     * match that reality rather than the narrower `number | 'frame'` it used
+     * to declare (which made every non-'frame' string an unchecked cast at
+     * every consumer).
+     */
+    interval: number | string;
+    guard?: SExpr;
+    effects: SExpr[];
+    priority: number;
+    appliesTo: string[];
+}
+interface ResolvedTraitListener {
+    event: string;
+    triggers: string;
+    guard?: SExpr;
+    /** `with { ... }` payload rewrite: `{ targetField: SExpr }`, evaluated against the source payload. */
+    payloadMapping?: Record<string, SExpr>;
+    /** Source scoping (see `ListenSource` in types/trait). */
+    source?: ListenSource;
+}
+interface ResolvedTraitDataEntity {
+    name: string;
+    fields: ResolvedField[];
+    runtime: boolean;
+    singleton: boolean;
+}
+/**
+ * UI binding for interaction traits - maps states to presentations
+ */
+interface ResolvedTraitUIBinding {
+    [stateName: string]: {
+        /** Presentation type: modal, drawer, popover, inline, confirm-dialog */
+        presentation: string;
+        /** Content pattern(s) to render */
+        content: AnyPatternConfig | AnyPatternConfig[];
+        /** Presentation props */
+        props?: {
+            size?: string;
+            position?: string;
+            title?: string;
+            closable?: boolean;
+            width?: string;
+            showProgress?: boolean;
+            step?: number;
+            totalSteps?: number;
+        };
+    };
+}
+/**
+ * Fully resolved trait - expanded from schema OR library.
+ * The compiler generates code from this structure universally,
+ * without knowing which specific trait it is.
+ */
+interface ResolvedTrait {
+    /** Unique trait identifier */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Where this trait came from */
+    source: 'schema' | 'library' | 'inline';
+    /** Category for organizing traits */
+    category?: 'lifecycle' | 'temporal' | 'validation' | 'notification' | 'integration' | 'interaction' | 'agent' | 'game-core' | 'game-character' | 'game-ai' | 'game-combat' | 'game-items' | 'game-cards' | 'game-board' | 'game-puzzle';
+    states: ResolvedTraitState[];
+    events: ResolvedTraitEvent[];
+    transitions: ResolvedTraitTransition[];
+    guards: ResolvedTraitGuard[];
+    ticks: ResolvedTraitTick[];
+    listens: ResolvedTraitListener[];
+    dataEntities: ResolvedTraitDataEntity[];
+    /**
+     * Atom-declared linked entity. The atom (e.g. std-pagination)
+     * declares which entity its `@entity.X` bindings resolve against
+     * (e.g. `PagedItem`). Distinct from the call-site rebind on
+     * `ResolvedTraitBinding.linkedEntity`, which a molecule may use
+     * to override the atom's default. Either side may be undefined
+     * for traits that don't bind any entity (pure interaction).
+     */
+    linkedEntity?: string;
+    /**
+     * The trait's DECLARED `config { }` schema (per-field
+     * `{ type, default? }`). Drives `@config.X` substitution: each
+     * field's `default` seeds the binding context behind any caller-
+     * supplied call-site `config: { ... }` override on the trait
+     * reference. Authored on the atom; flows through verbatim from
+     * `Trait.config`.
+     *
+     * (Caller-supplied call-site overrides live on the page-trait
+     * binding's `config: TraitConfig` — see `ResolvedTraitBinding`.)
+     */
+    config?: DeclaredTraitConfig;
+    ui?: ResolvedTraitUIBinding;
+}
+/**
+ * Trait binding on a page - links a resolved trait to the page
+ */
+interface ResolvedTraitBinding {
+    /** Reference name */
+    ref?: string;
+    /** Fully resolved trait */
+    trait: ResolvedTrait;
+    /** Entity this trait operates on (if any) */
+    linkedEntity?: string;
+    /** Instance configuration */
+    config?: TraitConfig;
+}
+interface ResolvedPattern {
+    /** Pattern type (e.g., 'page-header', 'entity-list', 'game-canvas') */
+    type: string;
+    /** Pattern configuration */
+    config: AnyPatternConfig;
+    /** Shell component to use */
+    shellComponent?: string;
+}
+interface ResolvedSectionEvent {
+    event: string;
+    action: string;
+    target?: string;
+}
+interface ResolvedSection {
+    /** Section identifier */
+    id: string;
+    /** Resolved pattern */
+    pattern: ResolvedPattern;
+    /** Events emitted by this section */
+    events: ResolvedSectionEvent[];
+    /** Position in page layout */
+    position?: number;
+    /** Entity binding for this section */
+    binding?: ResolvedEntityBinding;
+}
+interface ResolvedNavigation {
+    event?: string;
+    from?: string;
+    to: string;
+    trigger?: string;
+    params?: Record<string, string>;
+    label?: string;
+    path?: string;
+    icon?: string;
+}
+interface ResolvedPage {
+    /** Page identifier */
+    name: string;
+    /** URL path */
+    path: string;
+    /** Feature folder name */
+    featureName: string;
+    /** Layout component */
+    layout?: string;
+    /** View type (dashboard, list, detail, create, edit) */
+    viewType?: 'dashboard' | 'list' | 'detail' | 'create' | 'edit';
+    /** Resolved sections */
+    sections: ResolvedSection[];
+    /** Resolved trait bindings */
+    traits: ResolvedTraitBinding[];
+    /** Entity data bindings */
+    entityBindings: ResolvedEntityBinding[];
+    /** Navigation wiring */
+    navigation: ResolvedNavigation[];
+    /** Singleton entities to spawn on this page (runtime singletons) */
+    singletonEntities: ResolvedEntity[];
+}
+/**
+ * Complete resolved IR - all references expanded
+ */
+interface ResolvedIR {
+    /** App name */
+    appName: string;
+    /** App description */
+    description?: string;
+    /** App version */
+    version?: string;
+    /** All resolved entities (Map for lookup) */
+    entities: Map<string, ResolvedEntity>;
+    /** All resolved traits (Map for lookup) */
+    traits: Map<string, ResolvedTrait>;
+    /** All resolved pages (Map for lookup) */
+    pages: Map<string, ResolvedPage>;
+    /** Entity bindings (used for data hook generation) */
+    entityBindings: ResolvedEntityBinding[];
+    /** Raw data entities (used for instance data generation) */
+    rawEntities?: Entity[];
+    /** Generation timestamp */
+    generatedAt: string;
+}
+/**
+ * Create an empty resolved trait with defaults
+ */
+declare function createEmptyResolvedTrait(name: string, source: 'schema' | 'library' | 'inline'): ResolvedTrait;
+/**
+ * Create an empty resolved page with defaults
+ */
+declare function createEmptyResolvedPage(name: string): ResolvedPage;
+/**
+ * Infer TypeScript type from schema type
+ */
+declare function inferTsType(schemaType: string): string;
+/**
+ * Create a resolved field with TypeScript type inference
+ */
+declare function createResolvedField(field: {
+    name: string;
+    type: string;
+    description?: string;
+    default?: JsonValue;
+    required?: boolean;
+    validation?: {
+        enum?: string[];
+    };
+    values?: string[];
+}): ResolvedField;
+/**
+ * Type guard to check if an object is a ResolvedIR.
+ *
+ * Validates that an unknown value conforms to the ResolvedIR structure.
+ * Checks for required properties and correct types. Used for runtime
+ * type checking and validation.
+ *
+ * @param {unknown} ir - Value to check
+ * @returns {boolean} True if value is ResolvedIR, false otherwise
+ *
+ * @example
+ * if (isResolvedIR(schema)) {
+ *   // Type-safe access to ResolvedIR properties
+ *   console.log('Valid IR:', schema.appName);
+ * }
+ */
+declare function isResolvedIR(ir: RuntimeValue): ir is ResolvedIR;
+
+/**
+ * Context Extensions (framework concept)
+ *
+ * Open interface for consumer-supplied context that flows through guards,
+ * effects, and evaluation. Generated code imports `ContextExtensions`
+ * instead of `Record<string, unknown>` / `unknown` for the extensions bag,
+ * so downstream type-checking verifies that every read of a context key
+ * lines up with a declared interface member.
+ *
+ * Declaration-merging pattern — consumers augment this interface with
+ * their own optional fields:
+ *
+ * ```ts
+ * declare module '@almadar/core' {
+ *   interface ContextExtensions {
+ *     agent?: AgentContext;
+ *     auth?: AuthContext;
+ *   }
+ * }
+ * ```
+ *
+ * With no augmentation the interface is `{}` — `ctx.extensions.foo` is
+ * a type error, which is the desired behavior: if the codegen hits a
+ * context field that nobody declared, the consumer project is expected
+ * to add the declaration rather than widen to `unknown`.
+ *
+ * @packageDocumentation
+ */
+interface ContextExtensions {
+}
+
+/**
+ * Bus Event Types (framework concept)
+ *
+ * Canonical event shape for Almadar's cross-package event bus. Hoisted into
+ * `@almadar/core` so `@almadar/ui`, `@almadar/runtime`, and generated code
+ * all agree on the same structure. Replaces the previously divergent
+ * `KFlowEvent` (ui) and `RuntimeEvent` (runtime) definitions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 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's response-cascade
+     * re-emit (runtime path — every response entry echoes this tab's own
+     * dispatch, already delivered locally via the click-time qualified
+     * emit / bare-cascade subscription; cross-trait `listens` don't 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;
+}
+/**
+ * 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;
+
+/**
+ * Verification Types (framework concept)
+ *
+ * The `window.__orbitalVerification` bridge is the single observation
+ * point Playwright-based verifiers (`orbital-verify`, `runtime-verify`,
+ * `@almadar-io/verify`) use to read runtime state out of a live app.
+ * Its shape was previously duplicated between `@almadar/ui`'s
+ * `verificationRegistry.ts` (producer) and `@almadar-io/verify`'s
+ * `state-bridge.ts` (consumer). Every added field had to be mirrored
+ * by hand; one side drifting silently broke the other.
+ *
+ * Hoisting the wire types into `@almadar/core` closes that gap the same
+ * way {@link BusEvent} closed the UI/runtime event-shape drift. The
+ * registry still owns the state machine, the schedule, and the window
+ * exposure — this module owns only the shapes both sides agree on.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Outcome of a single verification check. `warn` is non-fatal in the
+ * overall pass/fail tally; `pending` means the check has been registered
+ * but not yet resolved.
+ */
+type CheckStatus = "pass" | "fail" | "pending" | "warn";
+interface VerificationCheck {
+    id: string;
+    label: string;
+    status: CheckStatus;
+    details?: string;
+    /** Timestamp (ms since epoch) when the status last changed. */
+    updatedAt: number;
+}
+/**
+ * Trace of a single effect as it ran on a transition. `args` are the
+ * effect tuple's trailing S-expressions; consumers narrow via `type`
+ * before inspecting.
+ */
+interface EffectTrace {
+    type: string;
+    /** For fetch/persist effects: the entity the effect addresses. */
+    entityName?: string;
+    args: SExpr[];
+    status: "executed" | "failed" | "skipped";
+    error?: string;
+    durationMs?: number;
+}
+/** What the server returned for a forwarded event. */
+interface ServerResponseTrace {
+    orbitalName: string;
+    success: boolean;
+    clientEffects: number;
+    dataEntities: Record<string, number>;
+    emittedEvents: string[];
+    error?: string;
+    timestamp: number;
+}
+interface TransitionTrace {
+    id: string;
+    traitName: string;
+    from: string;
+    to: string;
+    event: string;
+    guardExpression?: string;
+    guardResult?: boolean;
+    effects: EffectTrace[];
+    /** Populated when the event round-tripped to the server. */
+    serverResponse?: ServerResponseTrace;
+    timestamp: number;
+}
+interface BridgeHealth {
+    connected: boolean;
+    eventsForwarded: number;
+    eventsReceived: number;
+    lastError?: string;
+    lastHeartbeat: number;
+}
+interface VerificationSummary {
+    totalChecks: number;
+    passed: number;
+    failed: number;
+    warnings: number;
+    pending: number;
+}
+/**
+ * Per-trait state snapshot exposed to the verifier so it can assert
+ * that reducer data (populated by fetch/persist transitions) and the
+ * last dispatched payload land in the DOM correctly (VG4/VG6/VG11a/b/c).
+ *
+ * Mirrors what `useTraitStateMachine` / generated trait logic hooks
+ * keep internally, without the verifier having to parse rendered text.
+ */
+interface TraitStateSnapshot {
+    /** Trait name as declared in the schema. */
+    traitName: string;
+    /** Current state machine state. */
+    currentState: string;
+    /** Declared state names for this trait (non-empty for healthy refs). */
+    states: string[];
+    /** Declared event keys for this trait (non-empty for healthy refs). */
+    events: string[];
+    /**
+     * Entity data keyed by entity name. Uses {@link EntityRow} — the
+     * canonical persisted-entity shape the server returns and the trait
+     * reducer stores. Consumers that need full field-level types can cast
+     * down to the generated entity (e.g. `data['CartItem'] as CartItem[]`).
+     * Snapshot-on-read; mutating the returned arrays does not affect the
+     * live reducer.
+     */
+    data: Record<string, EntityRow[]>;
+    /** Payload of the last event the state machine processed, if any. */
+    lastPayload?: EventPayload;
+    /**
+     * Last event the walker (or a UI click) dispatched into this trait.
+     * Used by VG11a to resolve `@payload.X` expected values.
+     */
+    lastEventDispatched?: {
+        event: string;
+        payload?: EventPayload;
+        source?: BusEventSource;
+        timestamp: number;
+    };
+    /**
+     * Bus events received from the server's `emittedEvents` cascade
+     * since the last user dispatch. VG4 compares the length against the
+     * number of `emit: { success/failure: ... }` entries on the
+     * triggering transition.
+     */
+    cascadeReceived: Array<{
+        event: string;
+        payload?: EventPayload;
+        timestamp: number;
+    }>;
+}
+interface VerificationSnapshot {
+    checks: VerificationCheck[];
+    transitions: TransitionTrace[];
+    bridge: BridgeHealth | null;
+    summary: VerificationSummary;
+    /**
+     * Per-trait reducer snapshots. Empty on older runtimes that predate
+     * the Foundation 1 expansion; non-empty once any trait hook has
+     * registered a snapshot getter.
+     */
+    traits: TraitStateSnapshot[];
+}
+/** Asset load status exposed for canvas-based game verification. */
+type AssetLoadStatus = "loaded" | "failed" | "pending";
+/**
+ * Entry recorded on the verification event log. The registry ring-buffers
+ * the log to the last `MAX_EVENT_LOG` entries (evicting the oldest, never
+ * the recent tail) so long runs don't grow unbounded — see
+ * `verificationRegistry` and `eventLogDropped`.
+ */
+interface EventLogEntry {
+    type: string;
+    payload?: EventPayload;
+    timestamp: number;
+}
+/**
+ * A drawable descriptor as exposed over the verification bridge. The
+ * concrete `DrawableNode` union lives downstream in `@almadar/ui`
+ * (`lib/drawable/paintDispatch.ts`) and cannot be imported here without
+ * inverting the dependency axis; the bridge contract carries the `type`
+ * discriminant (`draw-sprite`, `draw-shape`, …) that verifiers narrow on.
+ */
+interface DrawableDescriptor {
+    type: string;
+}
+/**
+ * The object attached to `window.__orbitalVerification`. Every optional
+ * member is wired up by a corresponding `bind*` / `register*` call on
+ * the registry (e.g. `bindEventBus` populates `sendEvent`). Consumers
+ * should null-check before calling — an older bundle might expose only
+ * the core readers.
+ */
+interface OrbitalVerificationAPI {
+    getSnapshot: () => VerificationSnapshot;
+    getChecks: () => VerificationCheck[];
+    getTransitions: () => TransitionTrace[];
+    getBridge: () => BridgeHealth | null;
+    getSummary: () => VerificationSummary;
+    /** Wait for a specific event to be processed. Resolves to null on timeout. */
+    waitForTransition: (event: string, timeoutMs?: number) => Promise<TransitionTrace | null>;
+    /**
+     * Send an event into the runtime. Requires {@link bindEventBus} (in
+     * `@almadar/ui`) to have run at least once. Payload typed as
+     * {@link EventPayload} so callers can't slip non-bus-shaped data in.
+     *
+     * `traitScope` is the qualified `Orbital.Trait` (or `App.Trait`)
+     * scope that bus listeners subscribe under. The bridge constructs
+     * `UI:${traitScope}.${event}` and emits that on the bus, matching
+     * the codegen-emitted subscription keys (gap #13). When omitted,
+     * the legacy bare-prefix form `UI:${event}` is used — kept only
+     * for system-scope events like `UI:NOTIFY`; trait-driven dispatch
+     * MUST pass a `traitScope`.
+     */
+    sendEvent?: (event: string, payload?: EventPayload, traitScope?: string) => void;
+    /** Current state name for a given trait, if known. */
+    getTraitState?: (traitName: string) => string | undefined;
+    /** Per-trait reducer snapshots (VG4/VG6/VG11a/b/c). */
+    getTraitSnapshots?: () => TraitStateSnapshot[];
+    /** Canvas frame capture. Populated by game organisms on mount. */
+    captureFrame?: () => string | null;
+    /** Last neutral drawables list received by the active canvas host. */
+    getLastDrawables?: () => DrawableDescriptor[] | null;
+    /** Asset-url → load-status map. Populated by game organisms. */
+    assetStatus?: Record<string, AssetLoadStatus>;
+    /** Rolling event bus log. Populated by `bindEventBus`. */
+    eventLog?: EventLogEntry[];
+    /**
+     * Per-page-load nonce, set once when `bindEventBus` creates the log
+     * (and bumped by `clearEventLog`). A verifier reading the log across
+     * hermetic page reloads uses this — not the array length — to detect a
+     * reset: the length can coincidentally refill to the same count after a
+     * reload, which silently drops the post-reload delta. The epoch changing
+     * is the only reliable reset signal.
+     */
+    eventLogEpoch?: string;
+    /**
+     * Count of entries evicted from the FRONT of the ring-buffered log this
+     * page (see `MAX_EVENT_LOG`). The absolute index of `eventLog[i]` is
+     * `eventLogDropped + i`, so a verifier can cursor by absolute position
+     * even after eviction — the recent (driven) tail is never silently lost.
+     */
+    eventLogDropped?: number;
+    /** Clear the event log in place (also bumps `eventLogEpoch`). */
+    clearEventLog?: () => void;
+}
+
+/**
+ * Canonical SSE event types for the Almadar agent wire.
+ *
+ * These events are emitted by the rabit runtime (internal package
+ * `@almadar-io/rabit`) and consumed by public SDK clients. Because the rabit
+ * package is private, the SDK-relevant subset of the event surface is hoisted
+ * here into `@almadar/core` so public consumers can type their `onEvent`
+ * callbacks without depending on a private package.
+ *
+ * Rules for this file:
+ *   - Use only types already exported by `@almadar/core`.
+ *   - Do not import from `@almadar-io/rabit` or any other private package.
+ *   - Keep the discriminated union exhaustive over the included event types.
+ */
+
+type SSEEventType = 'start' | 'message' | 'tool_call' | 'tool_result' | 'todo_update' | 'todo_detail' | 'file_operation' | 'file_written' | 'schema_update' | 'generation_log' | 'subagent_event' | 'subagent_start' | 'subagent_progress' | 'subagent_complete' | 'interrupt' | 'error' | 'cancelled' | 'complete' | 'app_created' | 'schema_phase_validated' | 'schema_phase_update' | 'orbital_added' | 'orbital_schema_complete' | 'process_start' | 'process_complete' | 'process_error' | 'process_repair' | 'process_repair_complete' | 'params_repair_emitted' | 'changeset_recorded' | 'snapshot_created';
+interface SSEEventBase {
+    type: SSEEventType;
+    timestamp: number;
+}
+interface StartEvent extends SSEEventBase {
+    type: 'start';
+    data: {
+        threadId: string;
+        skill: string;
+        workDir: string;
+    };
+}
+interface MessageEvent extends SSEEventBase {
+    type: 'message';
+    data: {
+        content: string;
+        role: 'assistant' | 'user' | 'system';
+        isComplete: boolean;
+    };
+}
+interface ToolCallEvent extends SSEEventBase {
+    type: 'tool_call';
+    data: {
+        tool: string;
+        args: ToolArgs;
+    };
+}
+interface ToolResultEvent extends SSEEventBase {
+    type: 'tool_result';
+    data: {
+        tool: string;
+        result: JsonValue;
+        success: boolean;
+    };
+}
+interface TodoUpdateEvent extends SSEEventBase {
+    type: 'todo_update';
+    data: {
+        todos: Array<{
+            id: string;
+            task: string;
+            status: 'pending' | 'in_progress' | 'completed';
+        }>;
+    };
+}
+type TodoActivityType = 'thinking' | 'tool_call' | 'tool_result' | 'code_change';
+interface TodoDetailEvent extends SSEEventBase {
+    type: 'todo_detail';
+    data: {
+        todoId: string;
+        activityType: TodoActivityType;
+        content: string;
+        tool?: string;
+        args?: ToolArgs;
+        success?: boolean;
+        filePath?: string;
+        diff?: string;
+    };
+}
+interface FileOperationEvent extends SSEEventBase {
+    type: 'file_operation';
+    data: {
+        operation: 'ls' | 'read_file' | 'write_file' | 'edit_file';
+        path: string;
+        success: boolean;
+    };
+}
+interface FileWrittenEvent extends SSEEventBase {
+    type: 'file_written';
+    data: {
+        path: string;
+        fileType: 'schema' | 'orbital' | 'memory' | 'domain' | 'other';
+        orbitalName?: string;
+    };
+}
+interface SchemaUpdateEvent extends SSEEventBase {
+    type: 'schema_update';
+    data: {
+        appId: string;
+        version: number;
+        schema: OrbitalSchema;
+        isNew: boolean;
+        snapshotId?: string;
+        changesetId?: string;
+    };
+}
+interface GenerationLogEvent extends SSEEventBase {
+    type: 'generation_log';
+    data: {
+        level: 'info' | 'warn' | 'error' | 'debug';
+        message: string;
+        data?: JsonObject;
+        orbitalName?: string;
+    };
+}
+interface SubagentEvent extends SSEEventBase {
+    type: 'subagent_event';
+    data: {
+        orbitalName: string;
+        orbitalIndex: number;
+        totalOrbitals: number;
+        event: {
+            type: Exclude<SSEEventType, 'subagent_event'>;
+            data: JsonObject;
+            timestamp: number;
+        };
+    };
+}
+interface SubagentStartEvent extends SSEEventBase {
+    type: 'subagent_start';
+    data: {
+        subagentId: string;
+        name: string;
+        role: string;
+        orbitalName?: string;
+        parentId?: string;
+        task: string;
+    };
+}
+interface SubagentProgressEvent extends SSEEventBase {
+    type: 'subagent_progress';
+    data: {
+        subagentId: string;
+        orbitalName?: string;
+        message: string;
+        toolCall?: {
+            tool: string;
+            argsPreview?: string;
+        };
+    };
+}
+interface SubagentCompleteEvent extends SSEEventBase {
+    type: 'subagent_complete';
+    data: {
+        subagentId: string;
+        orbitalName?: string;
+        success: boolean;
+        durationMs: number;
+        summary?: string;
+    };
+}
+interface InterruptEvent extends SSEEventBase {
+    type: 'interrupt';
+    data: {
+        threadId: string;
+        actionRequests: Array<{
+            tool: string;
+            args: ToolArgs;
+            allowedDecisions: ('approve' | 'edit' | 'reject')[];
+            description?: string;
+        }>;
+    };
+}
+interface ErrorEvent extends SSEEventBase {
+    type: 'error';
+    data: {
+        error: string;
+        code?: string;
+        /** Orbital names that failed, when a generation run ends in failure. */
+        failedOrbitals?: string[];
+        /** Typed validate/failure lines backing `error` (same format as `cache_demoted.errors`). */
+        errors?: string[];
+    };
+}
+interface CancelledEvent extends SSEEventBase {
+    type: 'cancelled';
+    data: {
+        threadId: string;
+        message: string;
+    };
+}
+interface CompleteEvent extends SSEEventBase {
+    type: 'complete';
+    data: {
+        threadId: string;
+        skill: string;
+        workDir: string;
+        schemaGenerated: boolean;
+        appCompiled: boolean;
+        schema?: OrbitalSchema;
+        appId?: string;
+        schemaPersisted?: boolean;
+        snapshotId?: string;
+        changesetId?: string;
+    };
+}
+interface AppCreatedEvent extends SSEEventBase {
+    type: 'app_created';
+    data: {
+        appId: string;
+        name?: string;
+        orbitalCount?: number;
+        fromOrbitalPersistence?: boolean;
+    };
+}
+interface SchemaPhaseValidatedEvent extends SSEEventBase {
+    type: 'schema_phase_validated';
+    data: {
+        appId: string;
+        success: boolean;
+        errors?: JsonValue[];
+    };
+}
+interface SchemaPhaseUpdateEvent extends SSEEventBase {
+    type: 'schema_phase_update';
+    data: JsonObject;
+}
+interface OrbitalAddedEvent extends SSEEventBase {
+    type: 'orbital_added';
+    data: {
+        appId: string;
+        orbitalName: string;
+        orbitalIndex: number;
+        totalOrbitals: number;
+        isNew?: boolean;
+        orbitalSchema?: OrbitalDefinition;
+    };
+}
+interface OrbitalSchemaCompleteEvent extends SSEEventBase {
+    type: 'orbital_schema_complete';
+    data: {
+        appId: string;
+        totalOrbitals: number;
+        orbitalNames: string[];
+    };
+}
+interface ProcessStartEvent extends SSEEventBase {
+    type: 'process_start';
+    data: {
+        orbitalName: string;
+        method: 'deterministic' | 'llm';
+        behavior?: string;
+    };
+}
+interface ProcessCompleteEvent extends SSEEventBase {
+    type: 'process_complete';
+    data: {
+        orbitalName: string;
+        method: 'deterministic' | 'llm';
+        traitCount?: number;
+        transitionCount?: number;
+        duration?: number;
+    };
+}
+interface ProcessErrorEvent extends SSEEventBase {
+    type: 'process_error';
+    data: {
+        orbitalName: string;
+        method: 'deterministic' | 'llm';
+        error: string;
+        /** Typed validate/failure lines for this orbital (from `orbital_failed.errors`). */
+        errors?: string[];
+    };
+}
+interface ProcessRepairEvent extends SSEEventBase {
+    type: 'process_repair';
+    data: {
+        orbitalName: string;
+        errorCount: number;
+        attempt: number;
+    };
+}
+interface ProcessRepairCompleteEvent extends SSEEventBase {
+    type: 'process_repair_complete';
+    data: {
+        orbitalName: string;
+    };
+}
+interface ParamsRepairEmittedEvent extends SSEEventBase {
+    type: 'params_repair_emitted';
+    data: {
+        orbitalName: string;
+        attempt: number;
+    };
+}
+interface ChangesetRecordedEvent extends SSEEventBase {
+    type: 'changeset_recorded';
+    data: {
+        appId: string;
+        changesetId: string;
+        version: number;
+        trackingMode: 'initial' | 'update';
+        summary: {
+            added: number;
+            modified: number;
+            removed: number;
+        };
+        source?: string;
+    };
+}
+interface SnapshotCreatedEvent extends SSEEventBase {
+    type: 'snapshot_created';
+    data: {
+        appId: string;
+        snapshotId: string;
+        version: number;
+        reason: string;
+    };
+}
+type SSEEvent = StartEvent | MessageEvent | ToolCallEvent | ToolResultEvent | TodoUpdateEvent | TodoDetailEvent | FileOperationEvent | FileWrittenEvent | SchemaUpdateEvent | GenerationLogEvent | SubagentEvent | SubagentStartEvent | SubagentProgressEvent | SubagentCompleteEvent | InterruptEvent | ErrorEvent | CancelledEvent | CompleteEvent | AppCreatedEvent | SchemaPhaseValidatedEvent | SchemaPhaseUpdateEvent | OrbitalAddedEvent | OrbitalSchemaCompleteEvent | ProcessStartEvent | ProcessCompleteEvent | ProcessErrorEvent | ProcessRepairEvent | ProcessRepairCompleteEvent | ParamsRepairEmittedEvent | ChangesetRecordedEvent | SnapshotCreatedEvent;
+
+/**
+ * Living Orbital Schema — Golden Data Structure type system.
+ *
+ * The Living layer treats an `OrbitalSchema` as a heterogeneous attributed
+ * graph: every vertex (orbital, entity, trait, state, transition, page, field,
+ * event, effect, config-knob) carries a `SemanticAnnotation` + an embedding
+ * vector, and the whole object can embed / validate / compile / similarity-
+ * search / evolve itself. These are the canonical TYPE definitions shared by
+ * the masar (Python) implementation and any TS implementation (rabit, Phase 5);
+ * the numeric implementation lives outside @almadar/core.
+ *
+ * See `docs/Almadar_Masar_Golden_Data_Structure.md` §II/§III/§VIII. Existing
+ * core vocabulary is reused, never re-defined: `SchemaChange`/`SemanticChangeKind`
+ * (changeset.ts) back the evolution delta, `ValidationError`/`ValidationResult`
+ * (validation.ts) back `validate()`, and the per-vertex payloads ARE the existing
+ * structural types.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Decision-kind tier for the annotation layer. SUPERSET of the validator-
+ * enforced `FactoryConfigTier` (`domain`/`policy`/`infra`/`presentation`/
+ * `internal`), adding `essential` and `customization` for non-knob (event)
+ * vertices that still carry the old vocabulary. Every `FactoryConfigTier`
+ * value must be a member so `widenTier` stays a valid identity widen.
+ */
+type AnnotationTier = "essential" | "domain" | "policy" | "infra" | "presentation" | "customization" | "internal";
+/** Widen a knob's `FactoryConfigTier` into the annotation-layer `AnnotationTier`. */
+declare function widenTier(tier: FactoryConfigTier): AnnotationTier;
+/**
+ * The natural-language metadata attached to every living vertex — the text that
+ * gets embedded for `similar()`/`match_intent()`. Today these four members live
+ * scattered inline across core types (`EntityField.description`/`synonyms`,
+ * `Event`/`TraitEventContract`.`description`/`synonyms`/`tier`,
+ * `FactoryConfigParam.label`/`description`/`synonyms`/`tier`); `SemanticAnnotation`
+ * is the uniform bundle of them, generalized to every vertex.
+ */
+interface SemanticAnnotation {
+    description: string;
+    synonyms: string[];
+    label: string;
+    tier: AnnotationTier;
+}
+/**
+ * A dense semantic embedding. In-memory form is `Float32Array`; the at-rest
+ * JSON form (e.g. rabit's `knob-embeddings.json`) is `number[]`.
+ */
+type SemanticVector = Float32Array;
+/** A probability in `[0, 1]`. */
+type Probability = number;
+/** Whether a semantic gate's transition is open, closed, or ~0.5 ambiguous. */
+type GateState = "open" | "closed" | "ambiguous";
+/** The typed vertex kinds of the living attributed graph (§II.1 `V_*`). */
+type VertexType = "orbital" | "entity" | "trait" | "state" | "transition" | "page" | "field" | "event" | "effect" | "value";
+/**
+ * A stable, structural, embedding-independent vertex id (path style, e.g.
+ * `orb:Cart/trt:AddItem/st:Open`). Re-embedding never changes it.
+ */
+type VertexId = string;
+/** The typed directed edge kinds of the living attributed graph (§II.1 `E_*`). */
+type EdgeType = "belongs_to" | "has_trait" | "has_state" | "has_transition" | "from_state" | "to_state" | "on_event" | "emits" | "listens" | "cross_orbital" | "has_effect" | "effect_seq" | "data_flow" | "ref_in_effect" | "has_page" | "has_field" | "ref";
+/**
+ * An effect vertex's payload. Effects are positional S-expression tuples
+ * (`Effect`), so the synthesized coordinates (operator, owning transition,
+ * positional index) carry the addressing the raw tuple lacks.
+ */
+interface EffectPayload {
+    sexpr: Effect;
+    operator: string;
+    transitionId: VertexId;
+    index: number;
+}
+/**
+ * A config-knob vertex's payload — joins a `Trait.config` dict key with its
+ * declaration (no single core type carries both).
+ */
+interface KnobPayload {
+    name: string;
+    declaration: ConfigFieldDeclaration;
+    traitId: VertexId;
+}
+/** The union of every kind of vertex payload (the existing structural types). */
+type VertexPayload = OrbitalDefinition | Entity | Trait | State | Transition | Page | EntityField | Event | EffectPayload | KnobPayload;
+/**
+ * One vertex of the living graph: a structural payload plus its annotation and
+ * embedding. Identity is `id` (structural); annotation/embedding are derived.
+ */
+interface LivingVertex<P extends VertexPayload = VertexPayload> {
+    id: VertexId;
+    vtype: VertexType;
+    payload: P;
+    annotation: SemanticAnnotation;
+    /** Lazily populated — undefined until the schema's `embed()` runs. */
+    embedding?: SemanticVector;
+}
+type LivingOrbital = LivingVertex<OrbitalDefinition>;
+type LivingEntity = LivingVertex<Entity>;
+type LivingTrait = LivingVertex<Trait>;
+type LivingState = LivingVertex<State>;
+type LivingTransition = LivingVertex<Transition>;
+type LivingPage = LivingVertex<Page>;
+type LivingField = LivingVertex<EntityField>;
+type LivingEvent = LivingVertex<Event>;
+type LivingEffect = LivingVertex<EffectPayload>;
+type LivingValue = LivingVertex<KnobPayload>;
+/**
+ * One directed edge. `via` carries the transition vertex for the ternary
+ * `has_transition(from, via, to)` decomposition; `seq` carries the ordering for
+ * `effect_seq`.
+ */
+interface LivingEdge {
+    etype: EdgeType;
+    src: VertexId;
+    dst: VertexId;
+    via?: VertexId;
+    seq?: number;
+}
+/**
+ * A single evolution step over the living graph. `modified` reuses the canonical
+ * `SchemaChange` (changeset.ts) rather than inventing a parallel operation enum;
+ * `intent` is the natural-language delta that caused the change.
+ */
+interface EvolutionDelta {
+    added: VertexId[];
+    removed: VertexId[];
+    modified: SchemaChange[];
+    intent: string;
+}
+/** One immutable entry in a living schema's evolution lineage (§6.2). */
+interface LineageEntry {
+    root: string;
+    parent: string;
+    delta: EvolutionDelta;
+    intent: string;
+    time: number;
+    valid: boolean;
+}
+/** The result of simulating one effect's S-expression (§4.6) — pure, no I/O. */
+interface EffectResult {
+    result: SExpr;
+    sideEffects: string[];
+    emittedEvents: string[];
+}
+/**
+ * The operation surface of a living orbital schema. This interface is the shared
+ * CONTRACT; the numeric implementation (embedding, cosine, validator shelling)
+ * is language-specific. `compile()` is the bridge back to the canonical
+ * `OrbitalSchema` (the ML surface — annotations beyond `description`, embeddings,
+ * gates — is stripped).
+ */
+interface LivingOrbitalSchema {
+    orbitals: LivingOrbital[];
+    addOrbital(name: string): LivingOrbital;
+    removeOrbital(name: string): void;
+    getOrbital(name: string): LivingOrbital;
+    annotations: Map<VertexId, SemanticAnnotation>;
+    embeddings: Map<VertexId, SemanticVector>;
+    embed(): void;
+    compile(): OrbitalSchema;
+    validate(): ValidationResult;
+    similar(query: string | SemanticVector, k: number, type?: VertexType): LivingVertex[];
+    matchIntent(intent: string, threshold?: number): {
+        vertex: LivingVertex;
+        score: number;
+    }[];
+    predictConfig(intent: string, trait: Trait): Record<string, TraitConfigValue>;
+    predictPresence(intent: string): Set<string>;
+    suggestOrbital(intent: string): LivingOrbital[];
+    suggestEntity(intent: string): LivingEntity[];
+    suggestTrait(intent: string): LivingTrait[];
+    evolve(intentDelta: string): LivingOrbitalSchema;
+    compose(other: LivingOrbitalSchema): LivingOrbitalSchema;
+    repair(errors: ValidationError[]): LivingOrbitalSchema;
+    wireEvents(source: LivingEvent, target: LivingEvent): void;
+    findWiringGaps(): LivingEvent[];
+    simulateEffect(effect: LivingEffect, context: EvalContext): EffectResult;
+    simulateInteraction(effect: LivingEffect, path: string[]): {
+        event: LivingEvent;
+        payload: EventPayload;
+    };
+    traceDataFlow(transition: LivingTransition, inputEntity: LivingEntity): LivingEffect[];
+    evaluateGates(intentEmbedding: SemanticVector): Map<VertexId, GateState[]>;
+    sampleTrajectory(intentEmbedding: SemanticVector, steps: number): LivingVertex[];
+    lineage: LineageEntry[];
+    checkout(hash: string): LivingOrbitalSchema;
+    diff(hash1: string, hash2: string): EvolutionDelta;
+}
+
+/**
+ * Parsed AST — LLM-emit relaxed views of the canonical orbital types.
+ *
+ * Every `Parsed*` type mirrors its canonical counterpart in this module
+ * (`Trait`, `StateMachine`, `Transition`, `State`, `Event`, `OrbitalDefinition`,
+ * `PageRefObject`, etc.) but loosens required fields to optional. The
+ * loosening exists for one reason: the LLM can emit a partial orbital
+ * (mid-stream, mid-tool-call, mid-LoLo lowering) and consumer code
+ * needs to walk it WITHOUT casting to the strict canonical type before
+ * every field access.
+ *
+ * Discipline:
+ *
+ * - **No `unknown`.** Every field has a concrete type, sourced from
+ *   this same module where the type already exists (`EntityField`,
+ *   `EntityPersistence`, `TraitCategory`, `TraitScope`, `SExpr`,
+ *   `PageTraitRef`, `TraitEventContract`, `TraitEventListener`).
+ *
+ * - **No index signatures.** If the LLM emits a key the schema doesn't
+ *   know about, the validator rejects it. The `Parsed*` types do not
+ *   pretend to accept unknown keys at the type level.
+ *
+ * - **Required fields stay required.** `name` on `ParsedOrbital` is
+ *   required because no orbital can exist without one. `name` /
+ *   `linkedEntity` on `ParsedTrait` are required because the orbital
+ *   compiler rejects traits missing either. Only fields the LLM
+ *   legitimately omits during construction are optional.
+ *
+ * Use site: walkers that observe an orbital before it's fully
+ * validated. Construct it as `ParsedOrbital`, narrow to
+ * `OrbitalDefinition` after validation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Top-level orbital as the LLM emits it. Relaxed view of
+ * `OrbitalDefinition`: traits and pages may be partial, the domain
+ * context + design hints may be missing.
+ */
+interface ParsedOrbital {
+    name: string;
+    entity: ParsedEntity;
+    traits: ParsedTrait[];
+    pages: ParsedPage[];
+    domainContext?: ParsedDomainContext;
+    design?: ParsedDesign;
+}
+/**
+ * Entity nucleus of an orbital. `name` + `fields` are required; the
+ * factory canonical defaults can fill `persistence` and `collection`
+ * when omitted.
+ */
+interface ParsedEntity {
+    name: string;
+    fields: EntityField[];
+    persistence?: EntityPersistence;
+    collection?: string;
+}
+/**
+ * One trait on an orbital. `name` + `linkedEntity` are required (the
+ * compiler rejects either omission); state machine + scope + category
+ * are filled by defaults when the LLM doesn't specify them.
+ */
+interface ParsedTrait {
+    name: string;
+    linkedEntity: string;
+    category?: TraitCategory;
+    scope?: TraitScope;
+    description?: string;
+    config?: ParsedTraitConfig;
+    emits?: ParsedEmitDeclaration[];
+    listens?: ParsedListenDeclaration[];
+    stateMachine?: ParsedStateMachine;
+    capabilities?: string[];
+}
+/**
+ * Trait `config { }` block — the LLM-emit shape carries each declared
+ * config key as a typed value drawn from the JSON primitive set. A
+ * stricter view (`DeclaredTraitConfig` in `trait.ts`) captures the
+ * authored field descriptors with type+default+label+tier metadata;
+ * `ParsedTraitConfig` is the in-flight value map.
+ */
+type ParsedTraitConfig = {
+    [key: string]: string | number | boolean | null | ReadonlyArray<string | number | boolean | null>;
+};
+/**
+ * State-machine of a trait. Every field optional because the LLM may
+ * emit the trait header before its body. A canonical
+ * `StateMachine` (`state-machine.ts`) requires at least one state +
+ * one transition.
+ */
+interface ParsedStateMachine {
+    states?: ParsedState[];
+    events?: ParsedEvent[];
+    transitions?: ParsedTransition[];
+    initial?: string;
+}
+/**
+ * One state of a `ParsedStateMachine`. Mirrors `State` from
+ * `state-machine.ts` with name optional during construction.
+ */
+interface ParsedState {
+    name?: string;
+    isInitial?: boolean;
+}
+/**
+ * One event of a `ParsedStateMachine`. Mirrors `Event` from
+ * `state-machine.ts`. `payloadSchema` is the canonical shape — an
+ * array of `EntityField`s describing the event's payload.
+ */
+interface ParsedEvent {
+    key?: string;
+    name?: string;
+    payloadSchema?: EntityField[];
+}
+/**
+ * One transition of a `ParsedStateMachine`. `effects` + `guard` use
+ * `SExpr` from `expression.ts` — the canonical S-expression shape the
+ * runtime evaluates.
+ */
+interface ParsedTransition {
+    from?: string;
+    to?: string;
+    event?: string;
+    effects?: SExpr[];
+    guard?: SExpr;
+}
+/**
+ * Trait-emit declaration. Aliases `TraitEventContract` from
+ * `trait.ts` with every field optional. The canonical contract
+ * carries `event`, `scope`, `payload`; here all three are optional so
+ * an in-flight emit (just the name, no payload yet) types correctly.
+ */
+interface ParsedEmitDeclaration {
+    event?: string;
+    scope?: 'internal' | 'external';
+    payload?: EntityField[];
+}
+/**
+ * Trait-listen declaration. Mirrors `TraitEventListener` from
+ * `trait.ts` with the source remap and trigger key optional.
+ */
+interface ParsedListenDeclaration {
+    event?: string;
+    triggers?: string;
+    scope?: 'internal' | 'external';
+    payloadMapping?: {
+        [key: string]: SExpr;
+    };
+}
+/**
+ * One page entry on an orbital. Mirrors `PageRefObject` /
+ * `OrbitalPage`; `path` is the URL, `name` is the canonical
+ * identifier the molecule references.
+ */
+interface ParsedPage {
+    path?: string;
+    name?: string;
+    primaryEntity?: string;
+    traits?: PageTraitRef[];
+}
+/**
+ * Domain-context decorations the analyzer attaches to an orbital
+ * (vocabulary, category, original request). Mirrors `DomainContext`
+ * from `domain.ts` for the fields used in the parsed-AST surface; the
+ * full `DomainContext` carries semantic-role overlays + custom-pattern
+ * maps too, which the LLM doesn't emit in this surface.
+ */
+interface ParsedDomainContext {
+    request?: string;
+    category?: string;
+    vocabulary?: {
+        [key: string]: string;
+    };
+}
+/**
+ * Design hints (style + UX cues) the analyzer attaches. Mirrors
+ * `DesignPreferences` from `domain.ts`.
+ */
+interface ParsedDesign {
+    style?: string;
+    uxHints?: {
+        [key: string]: string;
+    };
+}
+
+/**
+ * Render-UI structural editing — the single canonical pattern-tree navigator,
+ * mutators, and overlay application. Promoted out of apps/builder so the studio
+ * client, rabit's contextual-edit path, and the overlay replay share ONE
+ * implementation (no shadow copies).
+ *
+ * Operates on the SERIALIZABLE structural pattern node — the resolved `.orb`
+ * render-ui shape (`{ type, children, ...props }`, props are strings/numbers/
+ * booleans/bindings/arrays). It never holds function-typed props: those exist
+ * only in the React-component `AnyPatternConfig`, never in resolved IR. A node
+ * to insert/swap is built as a structural literal and validated against the
+ * pattern registry by the caller — `AnyPatternConfig` is never assigned in.
+ */
+
+/** A serializable value inside a render-ui pattern node. No functions. */
+type PatternValue = string | number | boolean | Date | null | undefined | PatternNode | readonly PatternValue[];
+/** One node in a render-ui pattern tree as it appears in resolved `.orb`. */
+interface PatternNode {
+    type?: string;
+    children?: PatternNode[];
+    [prop: string]: PatternValue | PatternNode[] | undefined;
+}
+type EditFocusLevel = 'node' | 'slot' | 'field' | 'effect' | 'trait' | 'page' | 'orbital';
+/** A pointed-at element. Plain data — constructible with or without a DOM. */
+interface EditFocus {
+    level: EditFocusLevel;
+    orbital: string;
+    trait?: string;
+    transition?: string;
+    state?: string;
+    slot?: string;
+    path?: string;
+    patternType?: string;
+    entity?: string;
+    source?: string;
+    label: string;
+}
+type RenderUiPatchOp = 'replace' | 'insert' | 'remove' | 'set-prop' | 'rebind';
+interface RenderUiPatchAddress {
+    trait: string;
+    transition: string;
+    state?: string;
+    slot: string;
+    /** patternPath, e.g. `root.children.2`. For `insert`, the PARENT path. */
+    path: string;
+}
+interface RenderUiPatch {
+    op: RenderUiPatchOp;
+    address: RenderUiPatchAddress;
+    /** Structural fingerprint of the pre-edit node, used to re-anchor the patch
+     *  if a later factory rebuild shifts `address.path`. */
+    fingerprint?: string;
+    /** For `replace` / `insert`: the concrete node to place. */
+    node?: PatternNode;
+    /** For `insert`: index within the parent's children (default: append). */
+    index?: number;
+    /** For `set-prop` / `rebind`: the prop key. */
+    prop?: string;
+    /** For `set-prop`: the new value. For `rebind`: pass the binding via `value`. */
+    value?: PatternValue;
+}
+/** Navigate a dot-separated path (`root`, `root.children.0`, …) to a node. */
+declare function navigatePatternPath(root: PatternNode, path: string): PatternNode | null;
+/** Set a prop on the node at `path`. Returns false if the path misses. */
+declare function setPropAtPath(root: PatternNode, path: string, prop: string, value: PatternValue): boolean;
+/** Replace the node at a child path (`<parent>.children.<i>`) with `node`. */
+declare function replaceChildAtPath(root: PatternNode, path: string, node: PatternNode): boolean;
+/** Insert `node` into the parent's `children` at `index` (clamped to end). */
+declare function insertChildAtPath(root: PatternNode, parentPath: string, index: number, node: PatternNode): boolean;
+/** Remove the node at a child path. */
+declare function removeChildAtPath(root: PatternNode, path: string): boolean;
+/** Deterministic structural fingerprint of a node (excludes child contents;
+ *  identifies the base node so a patch can re-anchor after a path shift). */
+declare function fingerprintNode(node: PatternNode): string;
+interface RenderOverlayResult {
+    applied: number;
+    /** Patches whose target node could not be resolved (path gone + fingerprint
+     *  unmatched). Surfaced as `patch_stale` — never silently dropped. */
+    stale: RenderUiPatch[];
+}
+/**
+ * Replay render-ui patches onto a resolved orbital, in place. Deterministic:
+ * given the same base + patches, produces the same tree. Patches that cannot be
+ * anchored are returned in `stale` (never silently dropped or misapplied).
+ */
+declare function applyRenderOverlay(orbital: OrbitalDefinition, patches: readonly RenderUiPatch[]): RenderOverlayResult;
+
+export { DEFAULT_INTERACTION_MODELS as $, ANONYMOUS_USER as A, BINDING_CONTEXT_RULES as B, type ChangesetValue as C, type BridgeHealth as D, type BuilderResult as E, type BusEvent as F, type BusEventListener as G, type BusEventSource as H, type CancelledEvent as I, type ChangeAuthor as J, type ChangeSetDocument as K, type ChangeSummary as L, type ChangesetRecordedEvent as M, type CheckStatus as N, type Clarification as O, type PageContentReduction as P, type ClarificationCandidate as Q, type ResolvedIR as R, type SchemaChange as S, type ClarificationLevel as T, type CompleteEvent as U, type ComplexityAssessment as V, type ComposeAllResult as W, type ComposeChildrenResult as X, type ComposeOptions as Y, type ContextExtensions as Z, type CreateFlow as _, type ResolvedEntity as a, type OrbitalSchemaCompleteEvent as a$, DEFAULT_VIEWER as a0, DEV_TOKEN_PREFIX as a1, type DeleteFlow as a2, type DispatchUpdatesResult as a3, type DrawableDescriptor as a4, type EdgeType as a5, type EditFlow as a6, type EditFocus as a7, type EditFocusLevel as a8, type EffectPayload as a9, type LLMErrorContext as aA, type LazyService as aB, type LineageEntry as aC, type ListInteraction as aD, type LivingEdge as aE, type LivingEffect as aF, type LivingEntity as aG, type LivingEvent as aH, type LivingField as aI, type LivingOrbital as aJ, type LivingOrbitalSchema as aK, type LivingPage as aL, type LivingState as aM, type LivingTrait as aN, type LivingTransition as aO, type LivingValue as aP, type LivingVertex as aQ, type LlmCallToolsResult as aR, type LlmContext as aS, type LlmMessage as aT, type LlmTokenUsage as aU, type LlmToolCall as aV, type LlmToolDef as aW, type LoloEmitResult as aX, type MemoryContext as aY, type MessageEvent as aZ, type OrbitalAddedEvent as a_, type EffectResult as aa, type EffectTrace as ab, type ErrorEvent as ac, type EventEmit as ad, type EventKey as ae, type EventListen as af, type EventLogEntry as ag, type EvolutionDelta as ah, type ExecutePlanResult as ai, type ExtraTraitRef as aj, type FileOperationEvent as ak, type FileWrittenEvent as al, type GateState as am, type GenerationLogEvent as an, type GitHubIssue as ao, type GitHubLink as ap, type GitHubRepo as aq, type HistoryMeta as ar, type IntegrationContext as as, type InteractionModel as at, type InteractionModelInput as au, InteractionModelSchema as av, type InterruptEvent as aw, KNOWN_VALIDATION_ERROR_CODES as ax, type KnobPayload as ay, type KnownValidationErrorCode as az, type ResolvedPage as b, type ServiceAction as b$, type OrbitalVerificationAPI as b0, type ParamsRepairEmittedEvent as b1, type ParsedDesign as b2, type ParsedDomainContext as b3, type ParsedEmitDeclaration as b4, type ParsedEntity as b5, type ParsedEvent as b6, type ParsedListenDeclaration as b7, type ParsedOrbital as b8, type ParsedPage as b9, type ResolvedEntityBinding as bA, type ResolvedField as bB, type ResolvedNavigation as bC, type ResolvedPattern as bD, type ResolvedSection as bE, type ResolvedSectionEvent as bF, type ResolvedTraitBinding as bG, type ResolvedTraitDataEntity as bH, type ResolvedTraitEvent as bI, type ResolvedTraitGuard as bJ, type ResolvedTraitListener as bK, type ResolvedTraitState as bL, type ResolvedTraitTick as bM, type ResolvedTraitTransition as bN, type ResolvedTraitUIBinding as bO, type SSEEvent as bP, type SSEEventBase as bQ, type SSEEventType as bR, type SaveOptions as bS, type SaveResult as bT, type SchemaPhaseUpdateEvent as bU, type SchemaPhaseValidatedEvent as bV, type SchemaUpdateEvent as bW, type SemanticAnnotation as bX, type SemanticChangeKind as bY, type SemanticVector as bZ, type ServerResponseTrace as b_, type ParsedState as ba, type ParsedStateMachine as bb, type ParsedTrait as bc, type ParsedTraitConfig as bd, type ParsedTransition as be, type PatternNode as bf, PatternTypeSchema as bg, type PatternValue as bh, type PersistActionName as bi, type PlanSnapshot as bj, type PlanSnapshotStatus as bk, type PlannerResult as bl, type Probability as bm, type ProcessCompleteEvent as bn, type ProcessErrorEvent as bo, type ProcessRepairCompleteEvent as bp, type ProcessRepairEvent as bq, type ProcessStartEvent as br, RENDER_BINDING_MARKER as bs, type RawUserClaims as bt, type RenderBindingMarker as bu, type RenderOverlayResult as bv, type RenderUiPatch as bw, type RenderUiPatchAddress as bx, type RenderUiPatchOp as by, type RepairResult as bz, type ResolvedTrait as c, isKnownValidationErrorCode as c$, type ServiceActionName as c0, type ServiceCallResult as c1, type ServiceContract as c2, type ServiceEvents as c3, type SessionContext as c4, type SessionHistoryEntry as c5, type SnapshotCreatedEvent as c6, type SnapshotDocument as c7, type SpawnResult as c8, type StartEvent as c9, type ValidationMeta as cA, type ValidationResult as cB, type ValidationResults as cC, type VerificationCheck as cD, type VerificationSnapshot as cE, type VerificationSummary as cF, type VertexId as cG, type VertexPayload as cH, type VertexType as cI, type ViewFlow as cJ, type WorkspaceContext as cK, applyRenderOverlay as cL, containsEntityBinding as cM, containsPayloadBinding as cN, createEmptyResolvedPage as cO, createEmptyResolvedTrait as cP, createLazyService as cQ, createResolvedField as cR, createTypedEventBus as cS, decodeDevIdentityToken as cT, encodeDevIdentityToken as cU, findPersonaInRoster as cV, fingerprintNode as cW, getBindingExamples as cX, getInteractionModelForDomain as cY, inferTsType as cZ, insertChildAtPath as c_, type StatsView as ca, type StoreContract as cb, type StoreFilter as cc, type StoreFilterOp as cd, type SubagentCompleteEvent as ce, type SubagentEvent as cf, type SubagentProgressEvent as cg, type SubagentStartEvent as ch, type TodoActivityType as ci, type TodoDetailEvent as cj, type TodoUpdateEvent as ck, type ToolCallEvent as cl, type ToolResultEvent as cm, type TraceContext as cn, type TraitFieldRef as co, TraitFieldRefSchema as cp, type TraitStateSnapshot as cq, type TransitionFrom as cr, type TransitionTrace as cs, type Unsubscribe as ct, type UserContext as cu, type ValidateResult as cv, type ValidationDocument as cw, type ValidationError as cx, type ValidationErrorCode as cy, type ValidationIssue as cz, type CategorizedRemovals as d, isPlanSnapshot as d0, isRenderBindingMarker as d1, isResolvedIR as d2, isSessionHistoryEntry as d3, isTraitFieldRef as d4, navigatePatternPath as d5, normalizeUserContext as d6, personaFromIdentityRow as d7, removeChildAtPath as d8, replaceChildAtPath as d9, resolveDefaultViewer as da, resolvePersonaSpec as db, setPropAtPath as dc, toBindingRoot as dd, validateBindingInContext as de, widenTier as df, type SemanticSchemaChange as e, type AgentCodeSearchResult as f, type AgentCompactResult as g, type AgentCompactStrategy as h, type AgentContext as i, type AgentGenerateOptions as j, type AgentMemoryCategory as k, type AgentMemoryRecord as l, type AnalysisOrbital as m, type AnalysisOrbitalParams as n, type AnalysisPageOverride as o, type AnalysisRename as p, type AnalysisResult as q, type AnnotationTier as r, type AppCreatedEvent as s, type AppSummary as t, type AssetLoadStatus as u, BINDING_DOCS as v, BINDING_ROOTS as w, type BindingContext as x, type BindingRoot as y, BindingSchema as z };