@almadar/shell-runtime 0.0.0-stage → 0.1.0

package/dist/runtime/entities/mockStoreSeed.d.ts

@@ -0,0 +1,56 @@
+import { PersistenceAdapter, UserContext, Entity, OrbitalSchema } from '@almadar/core';
+import { StdMockSeed, SeedOwnerJournal } from './std-mock-seed.js';
+import '../../kernel/engine.js';
+import '../../kernel/host.js';
+import '../../effects/in-flight-calls.js';
+import '../../service/service-provider.js';
+import '../../kernel/program-effects.js';
+import '../../kernel/http.js';
+import '../../kernel/beacon.js';
+import '../../credentials/store.js';
+import '../../kernel/decode.js';
+import '@almadar/core/kernel-wire';
+import '../../kernel/os-port.js';
+import '../../kernel/wire.js';
+
+/**
+ * The one mock-store seed both JS hosts of a mock program run. The native `std-mock-seed` program decides the rows,
+ * the owner columns and who owns them, and writes them through the kernel; this module binds the declared collections
+ * and hands the program the app's resolved schema.
+ *
+ * @packageDocumentation
+ */
+
+interface MockSeedHost {
+    /** The kernel running the std seed program. */
+    seeder: StdMockSeed;
+    persistence: PersistenceAdapter;
+    /** The clock mock dates and seed stamps resolve against, in epoch milliseconds. */
+    nowMs: number;
+}
+interface MockSeedViewer {
+    /** Whether the host named the viewer; when it did not, the viewer is the declared `defaultPersona` (anonymous when none). */
+    namedByHost: boolean;
+    /** The viewer at evaluation time. */
+    current: () => UserContext | undefined;
+    /** Whether the `[identity]` entity (the persona roster) seeds now; a host that seeds it elsewhere passes false. */
+    seedIdentity: boolean;
+}
+interface MockSeeded {
+    viewer: UserContext | undefined;
+    /** The owner cells the seed stamped, kept for a later persona restamp. */
+    journal: SeedOwnerJournal;
+}
+/** Tells the store each server-persisted entity's declared `[persistent: tbl]` collection (EXEC-STORE-1). */
+declare function bindDeclaredCollections(store: PersistenceAdapter, entities: readonly Entity[]): void;
+/**
+ * A whole program's mock store, seeded for the viewer. A named viewer owns the rows from the first seed; otherwise
+ * the roster seeds unstamped and the viewer is the identity row the declared `defaultPersona` names, whose tracked
+ * owner cells restamp to it; with no `defaultPersona` the viewer is anonymous and nothing restamps.
+ */
+declare function seedMockStore(host: MockSeedHost, schema: OrbitalSchema, viewer: MockSeedViewer): Promise<MockSeeded>;
+/** Re-point the seeded owner cells at `user` after a persona switch; the rows are the store's current ones. */
+declare function restampMockOwner(host: MockSeedHost, schema: OrbitalSchema, journal: SeedOwnerJournal, user: UserContext): Promise<SeedOwnerJournal>;
+
+export { bindDeclaredCollections, restampMockOwner, seedMockStore };
+export type { MockSeedHost, MockSeedViewer, MockSeeded };

package/dist/runtime/entities/mockStoreSeed.js

@@ -0,0 +1,3 @@
+export { bindDeclaredCollections, restampMockOwner, seedMockStore } from '../../chunk-JFWFDUTR.js';
+import '../../chunk-HMK6YMQS.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/entities/seedBrowserStore.d.ts

@@ -0,0 +1,28 @@
+import { PersistenceAdapter, OrbitalEntity } from '@almadar/core';
+import { MockSeedRun, StdMockSeed } from './std-mock-seed.js';
+import '../../kernel/engine.js';
+import '../../kernel/host.js';
+import '../../effects/in-flight-calls.js';
+import '../../service/service-provider.js';
+import '../../kernel/program-effects.js';
+import '../../kernel/http.js';
+import '../../kernel/beacon.js';
+import '../../credentials/store.js';
+import '../../kernel/decode.js';
+import '@almadar/core/kernel-wire';
+import '../../kernel/os-port.js';
+import '../../kernel/wire.js';
+
+/**
+ * The one seed rule for browser-stored entities (`[persistent: x, browser]`): an EMPTY store gets the rows the native
+ * `std-mock-seed` program selects for the viewer's locale (the entity's written-out rows, or generated rows when it
+ * declares `mock`), written by that program through the kernel. Rows the user already has are never overwritten.
+ */
+
+interface BrowserSeedHost extends Pick<MockSeedRun, 'nowMs'> {
+    seeder: StdMockSeed;
+}
+declare function seedBrowserStore(store: PersistenceAdapter, entities: readonly OrbitalEntity[], locale: string | undefined, host: BrowserSeedHost): Promise<void>;
+
+export { seedBrowserStore };
+export type { BrowserSeedHost };

package/dist/runtime/entities/seedBrowserStore.js

@@ -0,0 +1,2 @@
+export { seedBrowserStore } from '../../chunk-T775TUCD.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/entities/std-mock-seed.d.ts

@@ -0,0 +1,87 @@
+import { UserContext, OrbitalSchema, EntityRow, PersistenceAdapter } from '@almadar/core';
+import { KernelEngine } from '../../kernel/engine.js';
+import '../../kernel/host.js';
+import '../../effects/in-flight-calls.js';
+import '../../service/service-provider.js';
+import '../../kernel/program-effects.js';
+import '../../kernel/http.js';
+import '../../kernel/beacon.js';
+import '../../credentials/store.js';
+import '../../kernel/decode.js';
+import '@almadar/core/kernel-wire';
+import '../../kernel/os-port.js';
+import '../../kernel/wire.js';
+
+/**
+ * The host side of the native `std-mock-seed` program. Sampling, owner provenance and persona restamp are decided by
+ * that program on the kernel (`DATASET_INPUT`, `RESTAMP_INPUT`), which also writes the rows and owner changes through
+ * the kernel's `persist batch`; this module only forwards its inputs and reads its typed answers.
+ *
+ * @packageDocumentation
+ */
+
+/** The kernel running the std seed program (`app.forkProgram(seedProgram)`); only dispatch is used. */
+type MockSeedEngine = Pick<KernelEngine, 'evaluate'>;
+interface SeedOwnerCell {
+    store: string;
+    id: string;
+    column: string;
+}
+interface SeedOwnerJournal {
+    viewerId: string;
+    stamped: SeedOwnerCell[];
+    deferred: SeedOwnerCell[];
+}
+interface SeedOwnerChange extends SeedOwnerCell {
+    kind: 'set' | 'rekey';
+    ownerId: string;
+}
+interface SeededDataset {
+    /** Rows by declared collection. */
+    stores: Record<string, EntityRow[]>;
+    journal: SeedOwnerJournal;
+}
+interface SeedRestamp {
+    journal: SeedOwnerJournal;
+    changes: SeedOwnerChange[];
+}
+/** The seeding values a program declares: the std-mock-seed config knobs, as the app's composition sets them, else the atom's defaults. */
+interface SeedConfig {
+    count: number;
+    seed: number;
+    /** The identity row id the viewer is when the host names none; empty means anonymous. */
+    defaultPersona: string;
+    restampOnPersona: boolean;
+}
+interface MockSeedRun {
+    /** The clock relative mock dates and seed stamps resolve against, in epoch milliseconds. */
+    nowMs: number;
+    /** The viewer the dataset's owner columns are stamped for; absent, the rows seed unstamped. */
+    viewerId?: string;
+    locale?: string;
+}
+declare class StdMockSeed {
+    private readonly engine;
+    readonly config: SeedConfig;
+    private readonly user?;
+    constructor(engine: MockSeedEngine, config: SeedConfig, user?: UserContext | undefined);
+    private ask;
+    /** Sample the program's dataset (`DATASET_INPUT`). */
+    dataset(program: OrbitalSchema, run: MockSeedRun): Promise<SeededDataset>;
+    /**
+     * Re-point the dataset's tracked owner cells at `viewer` (`RESTAMP_INPUT`); `stores` are the current authoritative rows.
+     * `firstOwner` marks the stamp right after seeding; a persona switch restamps only when the program's
+     * `restampOnPersona` config says so, otherwise it answers no changes.
+     */
+    restamp(program: OrbitalSchema, stores: Record<string, EntityRow[]>, journal: SeedOwnerJournal, viewer: UserContext, firstOwner: boolean): Promise<SeedRestamp>;
+}
+/**
+ * The seeding values as `.lolo` declares them: the std-mock-seed program's own config defaults, overlaid by the
+ * config an app's composition of it sets (an orbital that `uses` std-mock-seed and references its MockSeed trait).
+ */
+declare function declaredSeedConfig(seedProgram: OrbitalSchema, app?: OrbitalSchema): SeedConfig;
+/** The current rows of every collection the program declares, as the restamp takes them. */
+declare function readSeededStores(persistence: PersistenceAdapter, program: OrbitalSchema): Promise<Record<string, EntityRow[]>>;
+
+export { StdMockSeed, declaredSeedConfig, readSeededStores };
+export type { MockSeedEngine, MockSeedRun, SeedConfig, SeedOwnerCell, SeedOwnerChange, SeedOwnerJournal, SeedRestamp, SeededDataset };

package/dist/runtime/entities/std-mock-seed.js

@@ -0,0 +1,2 @@
+export { StdMockSeed, declaredSeedConfig, readSeededStores } from '../../chunk-HMK6YMQS.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/evaluation/local-store-transport.d.ts

@@ -0,0 +1,68 @@
+import { OrbitalSchema, PersistenceAdapter, OnDeviceModelPorts, BrowserTabPort, MessageCatalogs, UserContext, RowSetRef, RowQueryPage } from '@almadar/core';
+import { EffectHandlers } from '../types.js';
+import { KernelEngine } from '../../kernel/engine.js';
+import { KernelHostPorts } from '../../kernel/host.js';
+import { HttpPorts } from '../../kernel/http.js';
+import { KernelModule } from '../../kernel/wire.js';
+import { EventTransport } from '../../client/EventTransport.js';
+import '../../service/default-call-service.js';
+import '../../service/service-provider.js';
+import '../../kernel/program-effects.js';
+import '../effects/composition/compose-behaviors.js';
+import '../effects/composition/event-wiring.js';
+import '../effects/composition/layout-strategy.js';
+import '../effects/composition/pipe.js';
+import '../../effects/in-flight-calls.js';
+import '../../kernel/beacon.js';
+import '../../credentials/store.js';
+import '../../kernel/decode.js';
+import '@almadar/core/kernel-wire';
+import '../../kernel/os-port.js';
+
+/**
+ * An in-process transport over a local store: every request runs on the kernel opened over that store
+ * (`openLocalKernel`), and this host answers its I/O. The offline preview and the browser-stored side of a
+ * residence-routed host both use it.
+ */
+
+interface LocalKernelOptions {
+    /** The initialised `@almadar/kernel` module. */
+    kernel: KernelModule;
+    /** The language bundle as JSON (`LanguageBundle`), installed into `kernel` before it opens: a browser has no `node_modules` to read it from. */
+    language: string;
+    schema: OrbitalSchema;
+    /** Every row the kernel reads and writes (`localStorePersistence` over a browser store). */
+    persistence: PersistenceAdapter;
+    /** Answers every `call-service`; absent, the default provider. */
+    callService?: EffectHandlers['callService'];
+    /** The running app lent to `call-service` providers; absent, a provider reads the rows its viewer may read and dispatches no input. */
+    servicePorts?: KernelHostPorts['servicePorts'];
+    /** Where a follow-on call's outcome is dispatched; absent, nowhere. */
+    deferCallOutcome?: KernelHostPorts['deferCallOutcome'];
+    pageFacts?: KernelHostPorts['pageFacts'];
+    http?: HttpPorts;
+    onDevice?: OnDeviceModelPorts;
+    tabs?: BrowserTabPort;
+    /** The program's message catalogs, so `i18n/t` resolves for the request's locale. */
+    messages?: MessageCatalogs;
+}
+/** A local store's rows as the kernel holds them: browser-stored entities in `store`, every other entity in `memory` (a native `MemoryStore` adapter). */
+declare function localStorePersistence(schema: OrbitalSchema, store: PersistenceAdapter, memory: PersistenceAdapter): PersistenceAdapter;
+/** A kernel over a local store, answering its I/O with `persistence` and the given ports. */
+declare function openLocalKernel(options: LocalKernelOptions): KernelEngine;
+interface LocalStoreTransportOptions {
+    /** The kernel the requests run on (`openLocalKernel`), or its promise while the kernel module loads. */
+    kernelEngine: KernelEngine | Promise<KernelEngine>;
+    /** The viewer every request runs as, or its promise while the host resolves it (a mock store's seeded persona). */
+    user?: UserContext | Promise<UserContext | undefined>;
+    /** Releases the host's request queue while a `call-service` awaits its provider. */
+    outsideEventQueue?: <T>(work: () => Promise<T>) => Promise<T>;
+    /** The program the kernel runs; given, the transport resolves row-set references on that kernel. */
+    schema?: OrbitalSchema;
+}
+declare function createLocalStoreTransport(options: LocalStoreTransportOptions): EventTransport;
+/** `reference` resolved on a local kernel for `user`: the kernel applies the viewer's `@read`, the host answers its row reads. */
+declare function resolveLocalRows(engine: KernelEngine, schema: OrbitalSchema, user: UserContext | undefined, reference: RowSetRef): Promise<RowQueryPage>;
+
+export { createLocalStoreTransport, localStorePersistence, openLocalKernel, resolveLocalRows };
+export type { LocalKernelOptions, LocalStoreTransportOptions };

package/dist/runtime/evaluation/local-store-transport.js

@@ -0,0 +1,18 @@
+export { createLocalStoreTransport, localStorePersistence, openLocalKernel, resolveLocalRows } from '../../chunk-VNMG7NKY.js';
+import '../../chunk-4SEK5ER2.js';
+import '../../chunk-UBN5JJKZ.js';
+import '../../chunk-O57GKTYU.js';
+import '../../chunk-CPSQXEJ6.js';
+import '../../chunk-SAS5KKCR.js';
+import '../../chunk-D4XJTBLB.js';
+import '../../chunk-NATGCIVM.js';
+import '../../chunk-HNOAZWFH.js';
+import '../../chunk-53IPZXDP.js';
+import '../../chunk-YO4LWS3I.js';
+import '../../chunk-MZKIL5IN.js';
+import '../../chunk-FWA5K7Q2.js';
+import '../../chunk-VMOBW7RK.js';
+import '../../chunk-RBUMDYFS.js';
+import '../../chunk-HLOUDLPI.js';
+import '../../chunk-QELZ6TEJ.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/evaluation/residence-transport.d.ts

@@ -0,0 +1,15 @@
+import { EventTransport } from '../../client/EventTransport.js';
+import { TraitIndex } from '@almadar/core';
+
+interface ResidenceTransportOptions {
+    /** In-process transport over the browser store. */
+    local: EventTransport;
+    /** The server; absent on a static host. */
+    remote?: EventTransport;
+    /** The program's entities, for where a row-set reference's rows live. */
+    traitIndex: TraitIndex;
+}
+declare function createResidenceTransport(options: ResidenceTransportOptions): EventTransport;
+
+export { createResidenceTransport };
+export type { ResidenceTransportOptions };

package/dist/runtime/evaluation/residence-transport.js

@@ -0,0 +1,2 @@
+export { createResidenceTransport } from '../../chunk-UJHOUZAL.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/evaluation/routed-persistence.d.ts

@@ -0,0 +1,9 @@
+import { PersistenceAdapter } from '@almadar/core';
+
+/**
+ * One persistence over two stores: `stored` entities (a program's browser-stored ones) go to `stored`, every other entity to
+ * `other`. The kernel reads and writes every entity through one adapter; a batch is one store's transaction, so it stays in one.
+ */
+declare function routeByEntity(storedEntities: ReadonlySet<string>, stored: PersistenceAdapter, other: PersistenceAdapter): PersistenceAdapter;
+
+export { routeByEntity };

package/dist/runtime/evaluation/routed-persistence.js

@@ -0,0 +1,2 @@
+export { routeByEntity } from '../../chunk-O57GKTYU.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/events/identity/routing.d.ts

@@ -0,0 +1,84 @@
+import { TraitId, OrbitalId, EventId } from '@almadar/core';
+
+/**
+ * Identity-keyed routing (Almadar Rabit V4, Phase 4 — interpreter path).
+ *
+ * The runtime routes cross-trait events by NAME today: the bus key is the
+ * event name and source filtering compares orbital/trait name strings. A
+ * mid-session rename (a ledger `curName` edit that updates a node's own
+ * display name but deliberately does NOT rewrite the name strings held by
+ * every reference) therefore breaks name routing — the emitter now stamps
+ * the new name while the listener still holds the old one.
+ *
+ * These helpers make routing resolve by ID when the schema carries ids
+ * (ledger-backed, V4), and fall back to name while dual-carry. Ids are the
+ * stable edge keys: a rename never touches a node's id or any `*Id`
+ * reference, so id-routed bindings survive it. Legacy id-free schemas take
+ * the name path unchanged — byte-for-byte the previous behavior.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The bus subscription/delivery key for an event. When an `eventId` is
+ * present the key is the id (namespaced so it can never collide with a
+ * bare event name); otherwise it is the event name (legacy path).
+ *
+ * The event ENVELOPE keeps the human name as its `type` — only the routing
+ * key changes — so observability, the client re-broadcast wire shape, and
+ * wildcard listeners are untouched.
+ */
+declare function eventRouteKey(eventName: string, eventId?: EventId | string): string;
+/** Structured `listens {}` source, carrying V4 dual-carry ids when present. */
+type ListenSourceDescriptor = {
+    kind: 'any';
+} | {
+    kind: 'trait';
+    trait: string;
+    traitId?: TraitId;
+} | {
+    kind: 'orbital';
+    orbital: string;
+    trait: string;
+    orbitalId?: OrbitalId;
+    traitId?: TraitId;
+};
+/**
+ * The subset of a bus event's `source` metadata the matcher reads. Kept
+ * structural (no index signature) so `BusEventSource` assigns to it cleanly.
+ */
+interface RouteSourceMeta {
+    orbital?: string;
+    orbitalId?: OrbitalId;
+    trait?: string;
+    traitId?: TraitId;
+}
+/**
+ * Build a source-scope matcher for a `listens {}` entry.
+ *
+ * ID-first: when the listen source carries the id(s) for its scope, the
+ * matcher compares ids ONLY (exact-match, rename-proof). Otherwise it
+ * compares names against `listenerOrbital` — the exact legacy predicate.
+ * No name-similarity, ever: an id present on one side but absent on the
+ * other is a mismatch, never a fuzzy fallback.
+ */
+declare function buildSourceMatcher(src: ListenSourceDescriptor, listenerOrbital: string): (source: RouteSourceMeta | undefined) => boolean;
+/**
+ * Parse one `listens {}` entry into its bare event name + source matcher.
+ * Relocated here (was module-private to `OrbitalServerRuntime.ts`) so the
+ * stateless `@almadar-io/playground-runtime` path can reuse the EXACT same
+ * matching predicate for its own cross-orbital cascade (Fix A2) instead of
+ * a second, divergent copy — this function only ever depended on
+ * `ListenSourceDescriptor`/`buildSourceMatcher`, both already local to this
+ * module.
+ */
+declare function parseListenSource(listener: {
+    event: string;
+    source?: ListenSourceDescriptor;
+}, listenerOrbital: string): {
+    bareEvent: string;
+    matcher: (source: RouteSourceMeta | undefined) => boolean;
+};
+
+export { buildSourceMatcher, eventRouteKey, parseListenSource };
+export type { ListenSourceDescriptor, RouteSourceMeta };

package/dist/runtime/events/identity/routing.js

@@ -0,0 +1,2 @@
+export { buildSourceMatcher, eventRouteKey, parseListenSource } from '../../../chunk-IHQLE5M7.js';
+import '../../../chunk-MLKGABMK.js';

package/dist/runtime/time/TickScheduler.d.ts

@@ -0,0 +1,77 @@
+/**
+ * TickScheduler — a single coalesced clock for every registered tick.
+ *
+ * Replaces "one independent timer per tick" with ONE requestAnimationFrame
+ * accumulator loop (falling back to a single ~60fps `setInterval` where rAF
+ * isn't available, e.g. Node/SSR) that walks every registered tick each pass
+ * and fires whichever one(s) have crossed their own interval — so ticks due
+ * in the same pass commit together instead of on independent, uncoordinated
+ * timers. Each interval tick fires AT MOST ONCE per pass: missed beats are
+ * dropped (the phase remainder is kept, so healthy cadence is unchanged),
+ * because bursting catch-up firings after a slow pass multiplies the work
+ * that made the pass slow — an unbounded accumulator is a spiral-of-death
+ * amplifier that pegs the main thread and starves input. Framework-light:
+ * no React, usable from `OrbitalServerRuntime` (this package) and from
+ * `@almadar/ui`'s `useTraitStateMachine` alike.
+ *
+ * @packageDocumentation
+ */
+interface TickHandle {
+    /** Stop just this tick; the shared loop keeps running for any others still registered. */
+    stop(): void;
+}
+/**
+ * Coalesced tick scheduler. One instance drives every tick registered on it
+ * through a single shared clock.
+ */
+declare class TickScheduler {
+    private ticks;
+    private nextId;
+    private running;
+    private paused;
+    private frameHandle;
+    private readonly hasRaf;
+    constructor();
+    /**
+     * Register a tick. `intervalMs <= 0` means "every pass" (a frame-interval
+     * tick, matching LOLO's `interval: "frame"`). Returns a handle to stop
+     * just this tick.
+     */
+    add(intervalMs: number, onDue: () => void): TickHandle;
+    /**
+     * Register a cron-scheduled tick (`ticks { ... every "0 9 * * *" }`).
+     * Fires at most once per matching calendar minute. Throws if `expression` isn't a valid 5-field cron
+     * string; callers on a path the compiler has already validated (e.g.
+     * generated code) won't hit this, but a raw runtime value might.
+     */
+    addCron(expression: string, onDue: () => void): TickHandle;
+    /** Stop every tick and the shared loop. */
+    stopAll(): void;
+    /** True while the scheduler is paused (no tick callback fires and no backlog accumulates). */
+    get isPaused(): boolean;
+    /**
+     * Halt the shared loop without dropping registered ticks. No `onDue`
+     * fires again until `resume()`. A no-op if already paused.
+     */
+    pause(): void;
+    /**
+     * Restart the shared loop after `pause()`. Every registered tick's phase
+     * is reset (`lastTimestamp = null`) so the paused duration is never
+     * counted as elapsed time — the same "first pass just captures the
+     * timestamp" behavior a freshly `add()`-ed tick gets, which is what keeps
+     * resume from bursting a backlog of missed beats. A no-op if not paused.
+     */
+    resume(): void;
+    private ensureRunning;
+    private maybeStop;
+    /** Cancel the active rAF/interval loop, if any, and clear the running flag. */
+    private stopLoop;
+    private advance;
+    /** Cron ticks check calendar-match at most once a second, deduped per matching minute. */
+    private advanceCron;
+}
+/** Construct a new, independent `TickScheduler`. */
+declare function createTickScheduler(): TickScheduler;
+
+export { TickScheduler, createTickScheduler };
+export type { TickHandle };

package/dist/runtime/time/TickScheduler.js

@@ -0,0 +1,3 @@
+export { TickScheduler, createTickScheduler } from '../../chunk-CQP5XAX6.js';
+import '../../chunk-CROS2GEX.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/time/cron.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cron expression parsing and matching — the ONE canonical implementation
+ * every engine that schedules a cron-shaped interval delegates to (`OrbitalServerRuntime`,
+ * `TickScheduler`, and generated client codegen). No Node.js dependencies, so
+ * it's safe to import client-side too.
+ *
+ * @packageDocumentation
+ */
+interface CronFields {
+    minute: Set<number>;
+    hour: Set<number>;
+    day: Set<number>;
+    month: Set<number>;
+    weekday: Set<number>;
+}
+declare function parseCronField(field: string, min: number, max: number): Set<number>;
+declare function parseCron(expression: string): CronFields;
+/** Returns true if `expression` is a syntactically valid 5-field cron expression. */
+declare function isValidCronExpression(expression: string): boolean;
+declare function cronMatches(fields: CronFields, date: Date): boolean;
+/** Calendar-minute key for once-per-minute dedup — the same shape `os/watch-cron` uses. */
+declare function cronMinuteKey(date: Date): number;
+
+export { cronMatches, cronMinuteKey, isValidCronExpression, parseCron, parseCronField };
+export type { CronFields };

package/dist/runtime/time/cron.js

@@ -0,0 +1,2 @@
+export { cronMatches, cronMinuteKey, isValidCronExpression, parseCron, parseCronField } from '../../chunk-CROS2GEX.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/time/duration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Duration-string parsing — the one canonical parser for a tick interval
+ * written as `'5ms'`/`'5s'`/`'1m'`/`'1h'` (as opposed to a cron expression;
+ * see `./cron.js`). Shared by `OrbitalServerRuntime` and any client consumer
+ * (`@almadar/ui`'s `useTraitStateMachine`) so both agree on the same
+ * milliseconds for the same string.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Parse a duration string to milliseconds. Supports `'5ms'`/`'5s'`/`'1m'`/`'1h'`,
+ * and a bare number-as-string (assumed ms). Throws on anything else — a
+ * caller should check `isValidCronExpression` first if the string might be
+ * cron-shaped instead.
+ */
+declare function parseDurationString(interval: string): number;
+/** Returns true if `interval` matches the duration-string shape `parseDurationString` accepts. */
+declare function isValidDurationString(interval: string): boolean;
+
+export { isValidDurationString, parseDurationString };

package/dist/runtime/time/duration.js

@@ -0,0 +1,2 @@
+export { isValidDurationString, parseDurationString } from '../../chunk-46RWK2B5.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/traits/OrbitalTraitParsing.d.ts

@@ -0,0 +1,34 @@
+import { TraitDefinition, Trait, TraitConfig, Entity, OrbitalDefinition } from '@almadar/core';
+
+/**
+ * OrbitalTraitParsing — turn a resolved `OrbitalSchema.traits` array into the
+ * `TraitDefinition[]` shape `processEvent` (`StateMachineCore.ts`) consumes.
+ *
+ * Extracted from `OrbitalServerRuntime.register()` (the trait-unwrap +
+ * config-by-trait block) so a SECOND consumer — a stateless, per-request
+ * transition handler that never instantiates the full stateful
+ * `OrbitalServerRuntime` — can reuse the exact same parsing instead of a
+ * second copy. `register()` now calls this too; behavior is unchanged.
+ *
+ * @packageDocumentation
+ */
+
+interface ParsedOrbitalTraits {
+    /** Inline (unwrapped) traits, ready for `processEvent`. */
+    traits: TraitDefinition[];
+    /** The same traits at IR level (`@almadar/core` `Trait`) — `registered.traits`'s shape, kept for callers that need more than states/transitions/listens (e.g. `stateMachine.events` for payload validation). */
+    inlineTraits: Trait[];
+    /** Call-site `config` block per resolved trait name, from `uses` refs. */
+    configByTrait: Map<string, TraitConfig>;
+    /** The orbital's entity, resolved from a string ref / `EntityCall` / inline `Entity`. */
+    entity: Entity;
+}
+/**
+ * Parse `orbital.traits` (already-resolved — no `uses` left to expand) into
+ * `TraitDefinition[]` + the call-site config map, and resolve `orbital.entity`
+ * to a concrete `Entity`. Pure — no I/O, no instance state.
+ */
+declare function parseOrbitalTraits(orbital: OrbitalDefinition): ParsedOrbitalTraits;
+
+export { parseOrbitalTraits };
+export type { ParsedOrbitalTraits };

package/dist/runtime/traits/OrbitalTraitParsing.js

@@ -0,0 +1,2 @@
+export { parseOrbitalTraits } from '../../chunk-SAS5KKCR.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/traits/listen-targets.d.ts

@@ -0,0 +1,16 @@
+import { IndexedTrait, TraitEventListener, EventId, EventPayload, TraitIndex, BusEventSource } from '@almadar/core';
+
+interface CollectedListenerTarget {
+    listenerTrait: string;
+    /** The listener's index entry. */
+    entry: IndexedTrait;
+    /** The matched listener declaration (its `when` already held). */
+    listener: TraitEventListener;
+    triggers: string;
+    triggersId?: EventId;
+    payload: EventPayload | undefined;
+}
+declare function collectListenerTargets(traitIndex: TraitIndex, sourceStamp: BusEventSource | undefined, event: string, payload: EventPayload | undefined): CollectedListenerTarget[];
+
+export { collectListenerTargets };
+export type { CollectedListenerTarget };

package/dist/runtime/traits/listen-targets.js

@@ -0,0 +1,3 @@
+export { collectListenerTargets } from '../../chunk-XB5GYODW.js';
+import '../../chunk-IHQLE5M7.js';
+import '../../chunk-MLKGABMK.js';

package/dist/runtime/traits/trait-index.d.ts

@@ -0,0 +1,35 @@
+import { OrbitalDefinition, TraitIndex } from '@almadar/core';
+
+/**
+ * trait-index — build the per-trait evaluation index ONE time, for every
+ * execution path.
+ *
+ * The index is the composition's view of a resolved schema: for each
+ * trait, its flat `TraitDefinition` (the shape `processEvent` consumes),
+ * its IR-level trait (payload schemas, `emits` contracts), its RESOLVED
+ * linked entity (a trait's `linkedEntity` can name another orbital's
+ * primary or an auxiliary entity — resolved against every orbital's
+ * entities, never stubbed silently), its host orbital's name + V4 id
+ * (emit stamping), and its entity-frame key (the `$shared::<entity>`
+ * group key `OrbitalServerRuntime.sharedFieldKey` computes, resolved here
+ * ONCE from the entity declaration's own `shared` flag instead of
+ * re-walking per lookup).
+ *
+ * Consumers: the unified `evaluateOrbitalEvent` composition (both the
+ * stateful server's session view and the stateless per-request handler's
+ * compiled-behavior cache). Pure — no I/O, no instance state.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Build the trait index from a RESOLVED schema's orbitals (no `uses`
+ * left to expand — the compiler's inline phase already ran). Pure derived
+ * data: safe to cache per schema (the stateless deployment caches one
+ * index per catalog behavior; the stateful server builds one per
+ * registered orbital set).
+ * A trait's config is the kernel's (`traitConfig`), never merged here.
+ */
+declare function buildTraitIndex(orbitals: readonly OrbitalDefinition[]): TraitIndex;
+
+export { buildTraitIndex };

package/dist/runtime/traits/trait-index.js

@@ -0,0 +1,3 @@
+export { buildTraitIndex } from '../../chunk-CPSQXEJ6.js';
+import '../../chunk-SAS5KKCR.js';
+import '../../chunk-MLKGABMK.js';