@almadar/shell-runtime 0.1.0 → 1.0.0

package/dist/runtime/effects/composition/pipe.d.ts

@@ -1,25 +0,0 @@
-/**
- * Pipe Behaviors
- *
- * Left-to-right composition. Each step receives the previous result as its
- * first argument and returns the value handed to the next step.
- *
- * @packageDocumentation
- */
-/**
- * A single step in a behavior pipeline.
- */
-type PipeStep<I, O> = (input: I) => O;
-/**
- * Apply a series of transformation steps to a seed value, left to right.
- * Each step receives the previous step's output as its first argument.
- *
- * @example
- * ```ts
- * pipeBehaviors(1, (n) => n + 1, (n) => n * 10); // -> 20
- * ```
- */
-declare function pipeBehaviors<T>(seed: T, ...steps: Array<PipeStep<T, T>>): T;
-
-export { pipeBehaviors };
-export type { PipeStep };

package/dist/runtime/effects/composition/pipe.js

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

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

@@ -1,56 +0,0 @@
-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

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

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

@@ -1,28 +0,0 @@
-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

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

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

@@ -1,87 +0,0 @@
-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

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

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

@@ -1,77 +0,0 @@
-/**
- * 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

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

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

@@ -1,25 +0,0 @@
-/**
- * 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

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

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

@@ -1,20 +0,0 @@
-/**
- * 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

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

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

@@ -1,34 +0,0 @@
-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

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

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

@@ -1,16 +0,0 @@
-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

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

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

@@ -1,35 +0,0 @@
-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

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