@almadar/runtime 6.71.0 → 6.73.0

package/dist/{OrbitalServerRuntime-DnDJhpLS.d.ts → OrbitalServerRuntime-BiEntWd-.d.ts}

@@ -1,6 +1,6 @@
 import { Router } from 'express';
-import { I as IEventBus, R as RuntimeEvent, a as EventListener, U as Unsubscribe, T as TraitDefinition, b as RuntimeConfig, c as TransitionObserver, d as TraitState, C as ConfigContext, e as TransitionResult, f as EvaluationContextExtensions, E as EffectHandlers } from './types-BaD_ox7e.js';
-import { EventPayload, EventId, EntityRow, UserContext, Orbital, ServiceCallResult, TraitConfig, DeclaredTraitConfig, Entity, OrbitalSchema, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, RawUserClaims, OrbitalDefinition, TraitTick } from '@almadar/core';
+import { I as IEventBus, R as RuntimeEvent, a as EventListener, U as Unsubscribe, T as TraitDefinition, b as RuntimeConfig, c as TransitionObserver, d as TraitState, C as ConfigContext, e as TransitionResult, f as EvaluationContextExtensions, B as BindingContext, g as EffectContext, S as ServiceCallContext, E as EffectHandlers } from './types-CWaIuEQn.js';
+import { EventPayload, EventId, EntityRow, UserContext, ServiceParams, EntityAccessPolicies, Orbital, ServiceCallResult, TraitConfig, DeclaredTraitConfig, Entity, OrbitalSchema, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, RawUserClaims, OrbitalDefinition, TraitTick } from '@almadar/core';
 
 /**
  * EventBus - Platform-Agnostic Pub/Sub Implementation
@@ -85,6 +85,15 @@ declare class EventBus implements IEventBus {
  * @packageDocumentation
  */
 
+/**
+ * Mount-time lifecycle event kinds, in the order a trait is checked for
+ * support (`canHandleEvent`) — shared by the client hook's mount effect
+ * (`useTraitStateMachine`) and the server's capture-child re-render
+ * (`OrbitalServerRuntime.rerenderCallsiteCaptureChildren`), which both need
+ * to find "the lifecycle transition" for a trait that never advances past
+ * its own INIT/LOAD/$MOUNT self-loop.
+ */
+declare const LIFECYCLE_EVENTS: readonly ["INIT", "LOAD", "$MOUNT"];
 /**
  * Find the initial state for a trait definition.
  */
@@ -355,6 +364,191 @@ declare class StateMachineManager {
     resetAll(): void;
 }
 
+/**
+ * PersistenceAdapter — the storage contract for runtime effect handlers.
+ *
+ * The server-side runtime and the in-browser mock runtime both invoke
+ * `fetch` / `persist` / `ref` / `deref` / `swap!` effects against an
+ * implementation of this interface. Extracted from
+ * `OrbitalServerRuntime.ts` so it can be imported by browser code that
+ * cannot depend on the server module (which pulls in express).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Storage contract for CRUD operations on runtime entity rows.
+ *
+ * Implementations:
+ * - `InMemoryPersistence` (this file) — simple Map-backed store, used by
+ *   the browser mock runtime and as the default when an adapter is not
+ *   supplied to `OrbitalServerRuntime`.
+ * - `MockPersistenceAdapter` — in-memory with faker-generated seed data
+ *   for realistic preview content.
+ * - Consumer-provided (e.g. Firestore, Postgres) for production servers.
+ */
+interface PersistenceAdapter {
+    create(entityType: string, data: EntityRow): Promise<{
+        id: string;
+    }>;
+    update(entityType: string, id: string, data: EntityRow): Promise<void>;
+    delete(entityType: string, id: string): Promise<void>;
+    getById(entityType: string, id: string): Promise<EntityRow | null>;
+    list(entityType: string): Promise<EntityRow[]>;
+}
+/**
+ * Simple in-memory persistence for dev/testing and offline previews.
+ * Keys each entity collection by type, rows by generated string id.
+ */
+declare class InMemoryPersistence implements PersistenceAdapter {
+    private data;
+    private idCounter;
+    /**
+     * Seed the store with pre-existing rows.
+     *
+     * Accepts either a plain `Record<entityType, EntityRow[]>` or an iterable
+     * of `[entityType, EntityRow[]]` entries. Rows without an `id` get one
+     * generated at insert time; rows with an `id` keep it (so re-seeding
+     * after a schema rebuild preserves identities used in render bindings).
+     */
+    seed(seedData: Record<string, EntityRow[]> | Iterable<[string, EntityRow[]]>): void;
+    create(entityType: string, data: EntityRow): Promise<{
+        id: string;
+    }>;
+    update(entityType: string, id: string, data: EntityRow): Promise<void>;
+    delete(entityType: string, id: string): Promise<void>;
+    getById(entityType: string, id: string): Promise<EntityRow | null>;
+    list(entityType: string): Promise<EntityRow[]>;
+    /**
+     * Snapshot the entire store as a plain object (entityType → rows).
+     * Useful for feeding a fresh render-time binding layer with the
+     * current persistence view.
+     */
+    snapshot(): Record<string, EntityRow[]>;
+}
+
+/**
+ * ServerEffectHandlers — reusable factory for the server-side effect layer.
+ *
+ * Mirrors the handlers built inline in
+ * `OrbitalServerRuntime.executeEffects` so both the real server runtime
+ * AND the in-browser mock runtime (`@almadar/ui` OrbPreview autoMock) can
+ * share the same `fetch` / `persist` / `set` / `ref` / `deref` / `swap!` /
+ * `atomic` / `callService` semantics against a `PersistenceAdapter`.
+ *
+ * Browser-safe: only imports core + this package's browser-safe modules.
+ * Does NOT import express/Node, so it is reachable from `@almadar/ui`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Minimal event-bus contract the server handlers need. Narrower than the
+ * full `IEventBus` so clients with a React-context bus (only `emit` is
+ * relevant for effect dispatch) can hand it in without adapter code.
+ */
+interface ServerEffectEventBus {
+    emit(event: string, payload?: EventPayload, source?: {
+        orbital?: string;
+        trait?: string;
+    }): void;
+}
+/**
+ * Result entry recorded for each effect invocation. Mirrors the server
+ * runtime's `EffectResult`. Callers who want telemetry pass an array that
+ * the factory appends to; otherwise it's unused.
+ */
+interface ServerBatchSummary {
+    operations: EntityRow[];
+    completedCount: number;
+    totalCount: number;
+}
+interface ServerEffectResult {
+    effect: "set" | "persist" | "call-service" | "fetch" | "ref" | "deref" | "swap" | "atomic";
+    action?: string;
+    entityType?: string;
+    /** Entity row for CRUD/set/swap, the batch summary for `persist batch`, the raw service result for `call-service`. */
+    data?: EntityRow | ServerBatchSummary | EventPayload | null;
+    success: boolean;
+    /**
+     * Set when a persist failed because an access policy rejected it or the
+     * write resolved no row key — mirrors `OrbitalServerRuntime.EffectResult`
+     * so the offline-preview and real-server persist paths report the same
+     * denial discriminator to the verification trace.
+     */
+    denied?: true;
+    error?: string;
+}
+interface CreateServerEffectHandlersOptions {
+    /** Persistent store backing `fetch` / `persist` / `ref` / `deref` / `swap`. */
+    persistence: PersistenceAdapter;
+    /** Event bus that `emit` delegates to. Only `.emit()` is required. */
+    eventBus: ServerEffectEventBus;
+    /** The trait's linked entity type (used as the default for persist/set). */
+    entityType: string;
+    /** Current entity row id (used by `set`, `persist update/delete` fallback). */
+    entityId?: string;
+    /**
+     * Binding object passed to inner `atomic` evaluator. When absent, atomic
+     * effects still run but have no access to `@entity` / `@payload` bindings.
+     */
+    bindings?: BindingContext;
+    /** Effect context passed to the inner `atomic` executor. */
+    context?: EffectContext;
+    /** Per-event result sink. Optional — telemetry only. */
+    effectResults?: ServerEffectResult[];
+    /**
+     * Per-event fetched-data cache. `fetch` writes here so downstream UI
+     * renderers can resolve `@entity` bindings from the latest load without
+     * a separate round-trip.
+     */
+    fetchedData?: Record<string, EntityRow[]>;
+    /** Per-event emit log. Optional — telemetry only. */
+    emittedEvents?: Array<{
+        event: string;
+        payload?: EventPayload;
+    }>;
+    /** Source stamp applied to all emits. */
+    source?: {
+        orbital?: string;
+        trait?: string;
+    };
+    /** Consumer-supplied `call-service` handler. When absent, calls warn and return null. */
+    callService?: (service: string, action: string, params?: ServiceParams, context?: ServiceCallContext) => Promise<EventPayload | null>;
+    /**
+     * The declared `@read`/`@create`/`@update`/`@delete` directives, keyed by
+     * entity name. Build it with `entityAccessTable(schema)` from `@almadar/core`.
+     *
+     * Optional: a caller that holds no schema (the client offline-preview path)
+     * passes nothing and gets today's unrestricted behavior. A preview is not a
+     * security boundary — the generated server is, and that one always has the
+     * policies compiled in.
+     */
+    entityAccess?: ReadonlyMap<string, EntityAccessPolicies>;
+    /** Verbose logging. */
+    debug?: boolean;
+}
+/**
+ * Build the full server-side effect handler set bound to a persistence
+ * adapter. The returned object satisfies `EffectHandlers` and can be
+ * handed directly to `EffectExecutor`.
+ *
+ * Scope: one handler object per transition — capture `entityId`,
+ * `bindings`, `context`, and the sink arrays at build time. For a new
+ * transition, call this factory again.
+ *
+ * Intentionally does NOT implement:
+ * - `renderUI` / `notify` / `navigate` — these are client-side, provided
+ *   by `createClientEffectHandlers`. A mock runtime merges both handler
+ *   sets.
+ * - `os/watch-*` observers — these are a no-op outside the server.
+ * - Schema-aware relation cardinality / on-delete cascades — those live
+ *   in `OrbitalServerRuntime` and depend on the full registered schema.
+ *   Clients that need them can wrap the persist handler with their own
+ *   validation.
+ */
+declare function createServerEffectHandlers(opts: CreateServerEffectHandlersOptions): EffectHandlers;
+
 /**
  * Agent Substrate Handlers — Server-Side Only
  *
@@ -487,6 +681,12 @@ interface LoadedOrbital {
      * outside it. Mirrors the compiled path's `AliasEntry.orbitals`.
      */
     orbitals?: Orbital[];
+    /**
+     * The loaded schema's own app-level `config`, when it declares one.
+     * Traits from this orbital must resolve against THIS config, not the
+     * consumer's — omitted (never `undefined`) when the schema declares none.
+     */
+    schemaConfig?: DeclaredTraitConfig;
     /** Source path/URL (resolved) */
     sourcePath: string;
     /** Original import path */
@@ -654,6 +854,8 @@ interface ResolveOptions extends LoaderOptions {
     skipExternalLoading?: boolean;
     /** Custom schema loader instance (optional, defaults to ExternalOrbitalLoader) */
     loader?: SchemaLoader;
+    /** The schema's declared `config {}` — the outermost rung of the forwarded-config chain (§4.5). */
+    schemaConfig?: DeclaredTraitConfig;
 }
 
 /**
@@ -791,69 +993,6 @@ declare function parseNamespacedEvent(eventName: string): {
     event: string;
 };
 
-/**
- * PersistenceAdapter — the storage contract for runtime effect handlers.
- *
- * The server-side runtime and the in-browser mock runtime both invoke
- * `fetch` / `persist` / `ref` / `deref` / `swap!` effects against an
- * implementation of this interface. Extracted from
- * `OrbitalServerRuntime.ts` so it can be imported by browser code that
- * cannot depend on the server module (which pulls in express).
- *
- * @packageDocumentation
- */
-
-/**
- * Storage contract for CRUD operations on runtime entity rows.
- *
- * Implementations:
- * - `InMemoryPersistence` (this file) — simple Map-backed store, used by
- *   the browser mock runtime and as the default when an adapter is not
- *   supplied to `OrbitalServerRuntime`.
- * - `MockPersistenceAdapter` — in-memory with faker-generated seed data
- *   for realistic preview content.
- * - Consumer-provided (e.g. Firestore, Postgres) for production servers.
- */
-interface PersistenceAdapter {
-    create(entityType: string, data: EntityRow): Promise<{
-        id: string;
-    }>;
-    update(entityType: string, id: string, data: EntityRow): Promise<void>;
-    delete(entityType: string, id: string): Promise<void>;
-    getById(entityType: string, id: string): Promise<EntityRow | null>;
-    list(entityType: string): Promise<EntityRow[]>;
-}
-/**
- * Simple in-memory persistence for dev/testing and offline previews.
- * Keys each entity collection by type, rows by generated string id.
- */
-declare class InMemoryPersistence implements PersistenceAdapter {
-    private data;
-    private idCounter;
-    /**
-     * Seed the store with pre-existing rows.
-     *
-     * Accepts either a plain `Record<entityType, EntityRow[]>` or an iterable
-     * of `[entityType, EntityRow[]]` entries. Rows without an `id` get one
-     * generated at insert time; rows with an `id` keep it (so re-seeding
-     * after a schema rebuild preserves identities used in render bindings).
-     */
-    seed(seedData: Record<string, EntityRow[]> | Iterable<[string, EntityRow[]]>): void;
-    create(entityType: string, data: EntityRow): Promise<{
-        id: string;
-    }>;
-    update(entityType: string, id: string, data: EntityRow): Promise<void>;
-    delete(entityType: string, id: string): Promise<void>;
-    getById(entityType: string, id: string): Promise<EntityRow | null>;
-    list(entityType: string): Promise<EntityRow[]>;
-    /**
-     * Snapshot the entire store as a plain object (entityType → rows).
-     * Useful for feeding a fresh render-time binding layer with the
-     * current persistence view.
-     */
-    snapshot(): Record<string, EntityRow[]>;
-}
-
 /**
  * OrbitalServerRuntime - Dynamic Server-Side Orbital Execution
  *
@@ -1050,31 +1189,13 @@ interface OrbitalEventResponse {
         effect: ClientEffectTuple;
     }>;
     /** Results from server-side effects (persist, call-service, set) */
-    effectResults?: EffectResult[];
+    effectResults?: ServerEffectResult[];
     error?: string;
 }
 /**
  * Result of a server-side effect execution.
  * Closes the circuit by returning effect outcomes to the client.
  */
-interface EffectResult {
-    /** Effect type that was executed */
-    effect: 'persist' | 'call-service' | 'set' | 'ref' | 'deref' | 'swap' | 'atomic';
-    /** Action performed (e.g., 'create', 'update', 'delete' for persist) */
-    action?: string;
-    /** Entity type affected (for persist/set/ref/deref/swap) */
-    entityType?: string;
-    /** Result data from the effect (entity row for CRUD, summary for batch) */
-    data?: EntityRow | {
-        operations: EntityRow[];
-        completedCount: number;
-        totalCount: number;
-    };
-    /** Whether the effect succeeded */
-    success: boolean;
-    /** Error message if failed */
-    error?: string;
-}
 /**
  * Loader configuration for resolving `uses` imports
  */
@@ -1170,7 +1291,11 @@ declare class OrbitalServerRuntime {
     protected orbitals: Map<string, RegisteredOrbital>;
     private eventBus;
     private config;
-    private persistence;
+    /** The bound persistence adapter (mock/in-memory/consumer-supplied). Public
+     *  so a test can inspect committed rows honestly — `(runtime as any)
+     *  .persistence` was the alternative, and that cast is what this field
+     *  visibility replaces. */
+    readonly persistence: PersistenceAdapter;
     private listenerCleanups;
     private tickBindings;
     private readonly tickScheduler;
@@ -1208,6 +1333,15 @@ declare class OrbitalServerRuntime {
      * `declaredDefaults` and ahead of `callSiteOverride`.
      */
     private resolvedTraitConfigs;
+    /**
+     * Referrer trait name → the DIRECT children (via `@trait.X`) that need
+     * their lifecycle transition re-run under the referrer's `callsitePayload`
+     * whenever the referrer's own transition fires — computed once per
+     * `register()` via `@almadar/core`'s `collectCallsiteCaptureChildren`
+     * (merged across every orbital in the schema, same flattening
+     * `resolvedTraitConfigs` uses). See `rerenderCallsiteCaptureChildren`.
+     */
+    private callsiteCaptureChildrenByTrait;
     constructor(config?: OrbitalServerRuntimeConfig);
     /**
      * Lazily wire the OS-level effect handlers (fs/net/child_process), merging
@@ -1258,6 +1392,14 @@ declare class OrbitalServerRuntime {
      * that lives on only one execution path is not a feature.
      */
     private applyIdentityOwnerFields;
+    /**
+     * Merge `collectCallsiteCaptureChildren` across every orbital in the
+     * schema into ONE flat referrer-trait-name → children map — same
+     * flattening `resolvedTraitConfigs` uses, safe because trait names are
+     * unique within one running schema (the compose/resolve pipeline already
+     * relies on that for `configByTrait` and `resolvedTraitConfigs`).
+     */
+    private buildCallsiteCaptureChildrenByTrait;
     /**
      * Register an OrbitalSchema synchronously (for backward compatibility).
      * Note: This version doesn't wait for instance seeding to complete.
@@ -1519,6 +1661,35 @@ declare class OrbitalServerRuntime {
      * Execute effects from a transition
      */
     private executeEffects;
+    /**
+     * Re-run a JSX-hoisted inline child trait's (`@trait.X`) lifecycle
+     * transition under `callsitePayload` — the payload of the transition that
+     * just composed it — so its `@callsitePayload.<field>` captures reflect
+     * the composing event instead of staying frozen at whatever the child
+     * captured at its own mount-time INIT (a child renders once at mount and
+     * never again on its own).
+     *
+     * `this.callsiteCaptureChildrenByTrait` (built at `register()` via
+     * `@almadar/core`'s `collectCallsiteCaptureChildren`) gives `traitName`'s
+     * DIRECT children that need this — either because the child itself
+     * captures, or because it is a pass-through to a capturing descendant.
+     * The child's lifecycle event (INIT/LOAD/$MOUNT) is re-dispatched
+     * TARGETED at just that trait, from its CURRENT state (the same
+     * guard-aware `sendEvent`/`canHandleEvent` lookup a mount-time INIT
+     * uses), then its effects run through the SAME `executeEffects` used
+     * everywhere else, with `payload: {}` (a lifecycle event carries none)
+     * and `callsitePayload` set so `@callsitePayload.*` resolves — pushing
+     * into the SAME `clientEffects`/`clientEffectsByTrait`/`effectResults`
+     * so the child's refreshed frame reaches the sidecar under its own trait
+     * name. Recurses into the child's own entry in the same map (still under
+     * the SAME `callsitePayload` — the capture resolves up the embed chain to
+     * the nearest transition that actually has one) for grandchildren;
+     * `visited` guards against a malformed embed graph cycling on itself.
+     * Never goes through `processOrbitalEvent` (that would be re-entrant) —
+     * calls this internal executor directly, exactly like every other
+     * transition's effects.
+     */
+    private rerenderCallsiteCaptureChildren;
     /**
      * Populate relation fields on entities
      *
@@ -1550,6 +1721,7 @@ declare class OrbitalServerRuntime {
      * Routes:
      * - GET  /              - List registered orbitals
      * - GET  /:orbital      - Get orbital info and current states
+     * - GET  /:orbital/entities/:entityType - Full mock-store row set (verification/tooling only)
      * - POST /:orbital/events - Send event to orbital (includes data from `fetch` effects)
      */
     router(): Router;
@@ -1591,4 +1763,4 @@ declare class OrbitalServerRuntime {
  */
 declare function createOrbitalServerRuntime(config?: OrbitalServerRuntimeConfig): OrbitalServerRuntime;
 
-export { normalizeEventKey as A, parseNamespacedEvent as B, preprocessSchema as C, processEvent as D, type EntitySharingMap as E, type ClientEffectTuple as F, type ClientNavigateBackTuple as G, type ClientNavigateTuple as H, type ImportChainLike as I, type ClientNotifyTuple as J, type ClientRenderUITuple as K, type LoadResult as L, type EffectResult as M, type LiveBroadcastItem as N, type OrbitalEventRequest as O, type PersistenceAdapter as P, type LoaderConfig as Q, type RegisteredOrbital as R, type SchemaLoader as S, OrbitalServerRuntime as T, type UnifiedLoaderOptions as U, type RuntimeTraitTick as V, createOrbitalServerRuntime as W, type LoadedSchema as a, type LoadedOrbital as b, EventBus as c, type EventNamespaceMap as d, InMemoryPersistence as e, type OrbitalEventResponse as f, type OrbitalServerRuntimeConfig as g, type PreprocessOptions as h, type PreprocessResult as i, type PreprocessedSchema as j, type ProcessEventOptions as k, type RuntimeOrbital as l, type RuntimeOrbitalSchema as m, type RuntimeTrait as n, StateMachineManager as o, collectDeclaredConfigDefaults as p, collectDeclaredEntityDefaults as q, createInitialTraitState as r, findInitialState as s, findTransition as t, getIsolatedCollectionName as u, getNamespacedEvent as v, isBrowser as w, isElectron as x, isNamespacedEvent as y, isNode as z };
+export { isElectron as A, isNamespacedEvent as B, type CreateServerEffectHandlersOptions as C, isNode as D, type EntitySharingMap as E, normalizeEventKey as F, parseNamespacedEvent as G, preprocessSchema as H, type ImportChainLike as I, processEvent as J, type ClientEffectTuple as K, type LoadResult as L, type ClientNavigateBackTuple as M, type ClientNavigateTuple as N, type OrbitalEventRequest as O, type PersistenceAdapter as P, type ClientNotifyTuple as Q, type RegisteredOrbital as R, type SchemaLoader as S, type ClientRenderUITuple as T, type UnifiedLoaderOptions as U, type LiveBroadcastItem as V, type LoaderConfig as W, OrbitalServerRuntime as X, type RuntimeTraitTick as Y, createOrbitalServerRuntime as Z, type LoadedSchema as a, type LoadedOrbital as b, EventBus as c, type EventNamespaceMap as d, InMemoryPersistence as e, LIFECYCLE_EVENTS as f, type OrbitalEventResponse as g, type OrbitalServerRuntimeConfig as h, type PreprocessOptions as i, type PreprocessResult as j, type PreprocessedSchema as k, type ProcessEventOptions as l, type RuntimeOrbital as m, type RuntimeOrbitalSchema as n, type RuntimeTrait as o, type ServerEffectResult as p, StateMachineManager as q, collectDeclaredConfigDefaults as r, collectDeclaredEntityDefaults as s, createInitialTraitState as t, createServerEffectHandlers as u, findInitialState as v, findTransition as w, getIsolatedCollectionName as x, getNamespacedEvent as y, isBrowser as z };

package/dist/OrbitalServerRuntime.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-export { F as ClientEffectTuple, G as ClientNavigateBackTuple, H as ClientNavigateTuple, J as ClientNotifyTuple, K as ClientRenderUITuple, M as EffectResult, e as InMemoryPersistence, N as LiveBroadcastItem, Q as LoaderConfig, O as OrbitalEventRequest, f as OrbitalEventResponse, T as OrbitalServerRuntime, g as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, V as RuntimeTraitTick, p as collectDeclaredConfigDefaults, W as createOrbitalServerRuntime } from './OrbitalServerRuntime-DnDJhpLS.js';
-import './types-BaD_ox7e.js';
+export { K as ClientEffectTuple, M as ClientNavigateBackTuple, N as ClientNavigateTuple, Q as ClientNotifyTuple, T as ClientRenderUITuple, e as InMemoryPersistence, V as LiveBroadcastItem, W as LoaderConfig, O as OrbitalEventRequest, g as OrbitalEventResponse, X as OrbitalServerRuntime, h as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, m as RuntimeOrbital, n as RuntimeOrbitalSchema, o as RuntimeTrait, Y as RuntimeTraitTick, r as collectDeclaredConfigDefaults, Z as createOrbitalServerRuntime } from './OrbitalServerRuntime-BiEntWd-.js';
+import './types-CWaIuEQn.js';
 import '@almadar/core';