@almadar/core 5.3.2 → 5.5.0

package/dist/types/index.d.ts

@@ -105,6 +105,49 @@ declare function validateBindingInContext(binding: {
  */
 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;
+
 /**
  * Agent Types
  *
@@ -1101,4 +1144,195 @@ type BusEventListener = (event: BusEvent) => void;
 /** Returned by `on()` / `once()` to detach a listener. */
 type Unsubscribe = () => void;
 
-export { type AgentCodeSearchResult, type AgentCompactResult, type AgentCompactStrategy, type AgentContext, type AgentGenerateOptions, type AgentMemoryCategory, type AgentMemoryRecord, type AppSummary, BINDING_CONTEXT_RULES, BINDING_DOCS, type BindingContext, BindingSchema, type BusEvent, type BusEventListener, type BusEventSource, type CategorizedRemovals, type ChangeAuthor, type ChangeSetDocument, type ChangeSummary, type ContextExtensions, type CreateFlow, DEFAULT_INTERACTION_MODELS, type DeleteFlow, type EditFlow, EntityRow, EventPayload, FieldValue, type GitHubLink, type HistoryMeta, type InteractionModel, type InteractionModelInput, InteractionModelSchema, type LazyService, type ListInteraction, type PageContentReduction, PatternTypeSchema, type PersistActionName, type ResolvedEntity, type ResolvedEntityBinding, type ResolvedField, type ResolvedIR, type ResolvedNavigation, type ResolvedPage, type ResolvedPattern, type ResolvedSection, type ResolvedSectionEvent, type ResolvedTrait, type ResolvedTraitBinding, type ResolvedTraitDataEntity, type ResolvedTraitEvent, type ResolvedTraitGuard, type ResolvedTraitListener, type ResolvedTraitState, type ResolvedTraitTick, type ResolvedTraitTransition, type ResolvedTraitUIBinding, SExpr, type SaveOptions, type SaveResult, type SchemaChange, type SemanticChangeKind, type SemanticSchemaChange, type ServiceAction, type ServiceActionName, type ServiceContract, type ServiceEvents, type SnapshotDocument, type StatsView, type StoreContract, type StoreFilter, type StoreFilterOp, TraitConfig, type TransitionFrom, type Unsubscribe, type ValidationDocument, type ValidationIssue, type ValidationMeta, type ValidationResults, type ViewFlow, createEmptyResolvedPage, createEmptyResolvedTrait, createLazyService, createResolvedField, createTypedEventBus, getAllPatternTypes, getBindingExamples, getInteractionModelForDomain, inferTsType, isResolvedIR, validateBindingInContext };
+/**
+ * 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 left
+ * as `unknown[]` because different effect kinds have different argument
+ * shapes; consumers narrow via `type` before inspecting.
+ */
+interface EffectTrace {
+    type: string;
+    args: unknown[];
+    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 clamps
+ * the log size (see `verificationRegistry`'s internal `MAX_EVENT_LOG`)
+ * so long runs don't grow unbounded.
+ */
+interface EventLogEntry {
+    type: string;
+    payload?: EventPayload;
+    timestamp: number;
+}
+/**
+ * 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.
+     */
+    sendEvent?: (event: string, payload?: EventPayload) => 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;
+    /** Asset-url → load-status map. Populated by game organisms. */
+    assetStatus?: Record<string, AssetLoadStatus>;
+    /** Rolling event bus log. Populated by `bindEventBus`. */
+    eventLog?: EventLogEntry[];
+    /** Clear the event log in place. */
+    clearEventLog?: () => void;
+}
+
+export { type AgentCodeSearchResult, type AgentCompactResult, type AgentCompactStrategy, type AgentContext, type AgentGenerateOptions, type AgentMemoryCategory, type AgentMemoryRecord, type AppSummary, type AssetLoadStatus, BINDING_CONTEXT_RULES, BINDING_DOCS, BINDING_ROOTS, type BindingContext, type BindingRoot, BindingSchema, type BridgeHealth, type BusEvent, type BusEventListener, type BusEventSource, type CategorizedRemovals, type ChangeAuthor, type ChangeSetDocument, type ChangeSummary, type CheckStatus, type ContextExtensions, type CreateFlow, DEFAULT_INTERACTION_MODELS, type DeleteFlow, type EditFlow, type EffectTrace, EntityRow, type EventLogEntry, EventPayload, FieldValue, type GitHubLink, type HistoryMeta, type InteractionModel, type InteractionModelInput, InteractionModelSchema, type LazyService, type ListInteraction, type OrbitalVerificationAPI, type PageContentReduction, PatternTypeSchema, type PersistActionName, type ResolvedEntity, type ResolvedEntityBinding, type ResolvedField, type ResolvedIR, type ResolvedNavigation, type ResolvedPage, type ResolvedPattern, type ResolvedSection, type ResolvedSectionEvent, type ResolvedTrait, type ResolvedTraitBinding, type ResolvedTraitDataEntity, type ResolvedTraitEvent, type ResolvedTraitGuard, type ResolvedTraitListener, type ResolvedTraitState, type ResolvedTraitTick, type ResolvedTraitTransition, type ResolvedTraitUIBinding, SExpr, type SaveOptions, type SaveResult, type SchemaChange, type SemanticChangeKind, type SemanticSchemaChange, type ServerResponseTrace, type ServiceAction, type ServiceActionName, type ServiceContract, type ServiceEvents, type SnapshotDocument, type StatsView, type StoreContract, type StoreFilter, type StoreFilterOp, TraitConfig, type TraitStateSnapshot, type TransitionFrom, type TransitionTrace, type Unsubscribe, type ValidationDocument, type ValidationIssue, type ValidationMeta, type ValidationResults, type VerificationCheck, type VerificationSnapshot, type VerificationSummary, type ViewFlow, createEmptyResolvedPage, createEmptyResolvedTrait, createLazyService, createResolvedField, createTypedEventBus, getAllPatternTypes, getBindingExamples, getInteractionModelForDomain, inferTsType, isResolvedIR, toBindingRoot, validateBindingInContext };

package/dist/types/index.js

@@ -1240,6 +1240,24 @@ function getBindingExamples(context) {
   examples.push("@GameConfig.gravity", "@Filter.searchTerm");
   return examples;
 }
+
+// src/types/binding.ts
+var BINDING_ROOTS = [
+  "entity",
+  "payload",
+  "state",
+  "config",
+  "user",
+  "trait",
+  "item",
+  "now",
+  "computed",
+  "other"
+];
+var KNOWN_ROOTS = new Set(BINDING_ROOTS.filter((r) => r !== "other"));
+function toBindingRoot(root) {
+  return KNOWN_ROOTS.has(root) ? root : "other";
+}
 var InteractionModelSchema = z.object({
   createFlow: z.enum(["modal", "page", "inline", "none"]),
   editFlow: z.enum(["modal", "page", "inline", "none"]),
@@ -1382,6 +1400,6 @@ function isResolvedIR(ir) {
   return typeof r.appName === "string" && r.traits instanceof Map && r.pages instanceof Map;
 }
 
-export { AGENT_DOMAIN_CATEGORIES, ALLOWED_CUSTOM_COMPONENTS, AgentDomainCategorySchema, AnimationDefSchema, AssetMapSchema, AssetMappingSchema, BINDING_CONTEXT_RULES, BINDING_DOCS, BindingSchema, CORE_BINDINGS, ComputedEventContractSchema, ComputedEventListenerSchema, CustomPatternDefinitionSchema, CustomPatternMapSchema, DEFAULT_INTERACTION_MODELS, DesignPreferencesSchema, DesignTokensSchema, DomainCategorySchema, DomainContextSchema, DomainVocabularySchema, ENTITY_ROLES, EffectSchema, EntityCallSchema, EntityFieldSchema, EntityPersistenceSchema, EntityRefSchema, EntityRefStringSchema, EntityRoleSchema, EntitySchema, EntitySemanticRoleSchema, EventListenerSchema, EventPayloadFieldSchema, EventSchema, EventScopeSchema, EventSemanticRoleSchema, EventSourceSchema, ExpressionSchema, FieldFormatSchema, FieldSchema, FieldTypeSchema, GAME_TYPES, GameSubCategorySchema, GameTypeSchema, GuardSchema, InteractionModelSchema, ListenSourceSchema, McpServiceDefSchema, NodeClassificationSchema, OrbitalConfigSchema, OrbitalDefinitionSchema, OrbitalEntitySchema, OrbitalPageSchema, OrbitalPageStrictSchema, OrbitalSchemaSchema, OrbitalTraitRefSchema, OrbitalUnitSchema, OrbitalSchema as OrbitalZodSchema, PageRefObjectSchema, PageRefSchema, PageRefStringSchema, PageSchema, PageTraitRefSchema, PatternTypeSchema, PayloadFieldSchema, RelatedLinkSchema, RelationConfigSchema, RequiredFieldSchema, ResolvedAssetSchema, RestAuthConfigSchema, RestServiceDefSchema, SERVICE_TYPES, SExprAtomSchema, SExprSchema, SemanticAssetRefSchema, ServiceDefinitionSchema, ServiceRefObjectSchema, ServiceRefSchema, ServiceRefStringSchema, ServiceTypeSchema, SocketEventsSchema, SocketServiceDefSchema, StateMachineSchema, StateSchema, StateSemanticRoleSchema, SuggestedGuardSchema, ThemeDefinitionSchema, ThemeRefSchema, ThemeRefStringSchema, ThemeTokensSchema, ThemeVariantSchema, TraitCategorySchema, TraitConfigSchema, TraitConfigValueSchema, TraitDataEntitySchema, TraitEntityFieldSchema, TraitEventContractSchema, TraitEventListenerSchema, TraitRefSchema, TraitReferenceSchema, TraitSchema, TraitTickSchema, TransitionSchema, UISlotSchema, UI_SLOTS, UXHintsSchema, UseDeclarationSchema, UserPersonaSchema, VISUAL_STYLES, ViewTypeSchema, VisualStyleSchema, atomic, callService, collectBindings, createAssetKey, createEmptyResolvedPage, createEmptyResolvedTrait, createLazyService, createResolvedField, createTypedEventBus, deref, deriveCollection, despawn, doEffects, emit, findService, getAllPatternTypes, getArgs, getBindingExamples, getDefaultAnimationsForRole, getInteractionModelForDomain, getOperator, getServiceNames, getTraitConfig, getTraitName, hasService, inferTsType, isBinding, isCircuitEvent, isEffect, isEntityCall, isEntityReference, isEntityReferenceAny, isImportedTraitRef, isInlineTrait, isMcpService, isOrbitalDefinition, isPageReference, isPageReferenceObject, isPageReferenceString, isResolvedIR, isRestService, isRuntimeEntity, isSExpr, isSExprAtom, isSExprCall, isSExprEffect, isServiceReference, isServiceReferenceObject, isSingletonEntity, isSocketService, isThemeReference, isValidBinding, navigate, normalizeTraitRef, notify, parseAssetKey, parseBinding, parseEntityRef, parseImportedTraitRef, parseOrbitalSchema, parsePageRef, parseServiceRef, persist, ref, renderUI, safeParseOrbitalSchema, set, sexpr, spawn, swap, validateAssetAnimations, validateBindingInContext, walkSExpr, watch };
+export { AGENT_DOMAIN_CATEGORIES, ALLOWED_CUSTOM_COMPONENTS, AgentDomainCategorySchema, AnimationDefSchema, AssetMapSchema, AssetMappingSchema, BINDING_CONTEXT_RULES, BINDING_DOCS, BINDING_ROOTS, BindingSchema, CORE_BINDINGS, ComputedEventContractSchema, ComputedEventListenerSchema, CustomPatternDefinitionSchema, CustomPatternMapSchema, DEFAULT_INTERACTION_MODELS, DesignPreferencesSchema, DesignTokensSchema, DomainCategorySchema, DomainContextSchema, DomainVocabularySchema, ENTITY_ROLES, EffectSchema, EntityCallSchema, EntityFieldSchema, EntityPersistenceSchema, EntityRefSchema, EntityRefStringSchema, EntityRoleSchema, EntitySchema, EntitySemanticRoleSchema, EventListenerSchema, EventPayloadFieldSchema, EventSchema, EventScopeSchema, EventSemanticRoleSchema, EventSourceSchema, ExpressionSchema, FieldFormatSchema, FieldSchema, FieldTypeSchema, GAME_TYPES, GameSubCategorySchema, GameTypeSchema, GuardSchema, InteractionModelSchema, ListenSourceSchema, McpServiceDefSchema, NodeClassificationSchema, OrbitalConfigSchema, OrbitalDefinitionSchema, OrbitalEntitySchema, OrbitalPageSchema, OrbitalPageStrictSchema, OrbitalSchemaSchema, OrbitalTraitRefSchema, OrbitalUnitSchema, OrbitalSchema as OrbitalZodSchema, PageRefObjectSchema, PageRefSchema, PageRefStringSchema, PageSchema, PageTraitRefSchema, PatternTypeSchema, PayloadFieldSchema, RelatedLinkSchema, RelationConfigSchema, RequiredFieldSchema, ResolvedAssetSchema, RestAuthConfigSchema, RestServiceDefSchema, SERVICE_TYPES, SExprAtomSchema, SExprSchema, SemanticAssetRefSchema, ServiceDefinitionSchema, ServiceRefObjectSchema, ServiceRefSchema, ServiceRefStringSchema, ServiceTypeSchema, SocketEventsSchema, SocketServiceDefSchema, StateMachineSchema, StateSchema, StateSemanticRoleSchema, SuggestedGuardSchema, ThemeDefinitionSchema, ThemeRefSchema, ThemeRefStringSchema, ThemeTokensSchema, ThemeVariantSchema, TraitCategorySchema, TraitConfigSchema, TraitConfigValueSchema, TraitDataEntitySchema, TraitEntityFieldSchema, TraitEventContractSchema, TraitEventListenerSchema, TraitRefSchema, TraitReferenceSchema, TraitSchema, TraitTickSchema, TransitionSchema, UISlotSchema, UI_SLOTS, UXHintsSchema, UseDeclarationSchema, UserPersonaSchema, VISUAL_STYLES, ViewTypeSchema, VisualStyleSchema, atomic, callService, collectBindings, createAssetKey, createEmptyResolvedPage, createEmptyResolvedTrait, createLazyService, createResolvedField, createTypedEventBus, deref, deriveCollection, despawn, doEffects, emit, findService, getAllPatternTypes, getArgs, getBindingExamples, getDefaultAnimationsForRole, getInteractionModelForDomain, getOperator, getServiceNames, getTraitConfig, getTraitName, hasService, inferTsType, isBinding, isCircuitEvent, isEffect, isEntityCall, isEntityReference, isEntityReferenceAny, isImportedTraitRef, isInlineTrait, isMcpService, isOrbitalDefinition, isPageReference, isPageReferenceObject, isPageReferenceString, isResolvedIR, isRestService, isRuntimeEntity, isSExpr, isSExprAtom, isSExprCall, isSExprEffect, isServiceReference, isServiceReferenceObject, isSingletonEntity, isSocketService, isThemeReference, isValidBinding, navigate, normalizeTraitRef, notify, parseAssetKey, parseBinding, parseEntityRef, parseImportedTraitRef, parseOrbitalSchema, parsePageRef, parseServiceRef, persist, ref, renderUI, safeParseOrbitalSchema, set, sexpr, spawn, swap, toBindingRoot, validateAssetAnimations, validateBindingInContext, walkSExpr, watch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map