@almadar/shell-runtime 0.0.0-stage → 1.0.0

package/dist/client/circuit-store.d.ts

@@ -0,0 +1,87 @@
+import { AwaitingRegistry } from './awaiting.js';
+import { StateBook } from './state-book.js';
+import { EntityRow, TraitDefinition } from '@almadar/core';
+import { FrameDelta } from '@almadar/core/kernel-wire';
+import { RollbackCause, TransitionObserver } from './trait-types.js';
+
+/**
+ * CircuitStore — P2, `docs/Almadar_Runtime_Stateless_Stateful_PLAN.md` §4.2.
+ *
+ * The browser client's circuit state: each trait's state and entity frame as the kernel last reported them.
+ *
+ * `snapshot`/`restore` are the JS twin of orbital-core's
+ * `RuntimeKernel::snapshot_trait`/`restore_trait` (`runtime/kernel.rs`) — the
+ * `runtimeOptimistic` rollback point. `subscribe`/`getVersion` let a later
+ * React adapter drive `useSyncExternalStore` off this store without the
+ * store knowing anything about React.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A trait instance's state + entity frame at a point in time — the twin of
+ * orbital-core's `TraitSnapshot { state, entity }`. `frame` is `undefined`
+ * when the trait had no frame row yet (mirrors Rust's `Value::Null` case:
+ * restoring must leave the row absent, not invent one).
+ */
+interface TraitSnapshot {
+    state: string;
+    frame: EntityRow | undefined;
+}
+/**
+ * What a frame delta did to the store: `applied`; `stale` (its version is behind the one painted: dropped, so an
+ * old repaint never overwrites a newer value); `gap` (it starts past the painted version: nothing applied, the
+ * caller asks the kernel for `framesSince(frameVersion)` and applies the snapshot).
+ */
+type FrameOutcome = 'applied' | 'stale' | 'gap';
+interface CircuitStore {
+    /** Each trait's state as the kernel last reported it. */
+    readonly states: StateBook;
+    /** The entity-frame map (`(set @entity.X)` writes), keyed by
+     *  `IndexedTrait.frameKey`. */
+    readonly frames: Map<string, EntityRow>;
+    /** The version of the kernel's frame record this store has painted. */
+    readonly frameVersion: number;
+    /**
+     * Paint the kernel's frame delta (EXEC-DIST-7): ops land only at the version they start from, and a snapshot
+     * (`from` 0 with a leading `clear`) always lands. The store merges nothing by its own rules.
+     */
+    applyFrames(delta: FrameDelta): FrameOutcome;
+    /** Traits awaiting a server round trip (per-trait subscriptions; see `AwaitingRegistry`). */
+    readonly awaiting: AwaitingRegistry;
+    /**
+     * Capture `trait`'s current state + its frame row, for a
+     * `runtimeOptimistic` dispatch's pre-commit rollback point. `frameKey`
+     * defaults to `trait` (the non-`[shared]`-entity case); a caller holding
+     * the trait's `IndexedTrait.frameKey` (the `[shared]` case) passes it
+     * explicitly so the snapshot reads the SAME row the dispatch will write.
+     */
+    snapshot(trait: string, entityId?: string, frameKey?: string): TraitSnapshot;
+    /**
+     * Roll `trait` back to a prior snapshot: state via a reconcile write (no
+     * guard evaluation — `rollbackState`, which reports the hop to the observer), frame via REPLACE (never merge — an
+     * optimistic commit may have added fields since the snapshot that a merge
+     * would keep, the same reasoning as `RuntimeKernel::restore_trait`).
+     */
+    restore(trait: string, entityId: string | undefined, snapshot: TraitSnapshot, frameKey: string | undefined, cause: RollbackCause): void;
+    /**
+     * Notify subscribers that circuit state changed. Callers (the client
+     * role, `client-role.ts`) call this ONCE after a dispatch/fold finishes
+     * writing state — the store never fires this on its own.
+     */
+    notify(): void;
+    /** `useSyncExternalStore`-shaped subscription. Returns the unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Monotonic version, bumped by every `notify()` call. */
+    getVersion(): number;
+}
+/**
+ * The one in-memory `CircuitStore` implementation. Per-request (stateless
+ * server) or long-lived (stateful server, browser client) is only a
+ * question of how long the caller HOLDS the returned store — the
+ * implementation itself carries no lifetime opinion.
+ */
+declare function createMemoryCircuitStore(traits?: readonly TraitDefinition[], observer?: TransitionObserver): CircuitStore;
+
+export { createMemoryCircuitStore };
+export type { CircuitStore, FrameOutcome, TraitSnapshot };

package/dist/client/circuit-store.js

@@ -0,0 +1,3 @@
+export { createMemoryCircuitStore } from '../chunk-N7HYNKK6.js';
+import '../chunk-A2JJT4GA.js';
+import '../chunk-HC6ERSAH.js';

package/dist/client/client-kernel.d.ts

@@ -0,0 +1,134 @@
+import { EventResponse, EventRequest, DispatchMode, EmittedEvent, MountSeed, TransitionRejection } from '@almadar/core';
+import { CircuitStore } from './circuit-store.js';
+import './awaiting.js';
+import './state-book.js';
+import './trait-types.js';
+import '@almadar/core/kernel-wire';
+
+/**
+ * The contract of a client kernel: what a view dispatches into and what it gets back. `@almadar/ui`'s kernel client
+ * (over `@almadar/kernel/client`) implements it.
+ */
+
+/** One `ClientKernel.dispatch()` call's settled outcome. */
+interface ClientKernelOutcome {
+    response: EventResponse;
+    mode: DispatchMode;
+    /**
+     * True when `onLocal` already received the local arm's response (the leg
+     * was posted). `serverEffects` then holds only what the server's fold
+     * added — the local ones were painted before the round trip.
+     */
+    localPainted?: boolean;
+    serverEffects?: Pick<EventResponse, 'clientEffectsByTrait'>;
+    /**
+     * A tick-lane dispatch: what its post's fold added on top of the local run,
+     * once the post settles (undefined when a newer firing superseded it). The
+     * drain never waits on it; the caller paints it when it lands.
+     */
+    tickSettled?: Promise<Pick<EventResponse, 'clientEffectsByTrait'> | undefined>;
+}
+/** Per-dispatch hooks: `onLocal` sees the locally-evaluated response before its server leg is sent. */
+interface ClientDispatchHooks {
+    onLocal?: (local: EventResponse) => void;
+}
+/** Mount hooks: `onLocal` sees each seed's local response before the mount leg is sent. */
+interface ClientMountHooks {
+    onLocal?: (trait: string, local: EventResponse) => void;
+}
+/** What the kernel answered to an emit that entered from outside it: the cascade it ran, with its paint and its emits. */
+interface ClientEmitOutcome {
+    response: EventResponse;
+}
+/** One `ClientKernel.dispatchMount()` call's settled outcome. */
+interface ClientMountOutcome {
+    /** Each seed's local run, in seed order (already painted through `onLocal`). */
+    seeds: Array<{
+        trait: string;
+        event: string;
+        mode: DispatchMode;
+        local: EventResponse;
+    }>;
+    /** Whether any mount leg was posted. */
+    posted: boolean;
+    success: boolean;
+    error?: string;
+    /** Per-trait effect failures the posted legs reported (`effect-failed`). */
+    rejections: TransitionRejection[];
+    /** What the posted legs added: the server's effects and the emits the client had not run. */
+    serverEffects: Pick<EventResponse, 'clientEffectsByTrait'>;
+    emittedEvents: EventResponse['emittedEvents'];
+}
+interface ClientKernel {
+    /**
+     * Enqueue one event. FIFO per kernel: this entry's local dispatch → post
+     * (per the posting rule) → fold → `store.notify()` all complete before the
+     * next queued entry's local dispatch begins — the twin of orbital-client's
+     * `ClientKernel::dispatch` being called serially off one queue, ported to
+     * JS's single-threaded-but-concurrent-microtask model where two `dispatch`
+     * calls made back to back would otherwise interleave.
+     *
+     * A `request.tick`-stamped entry coalesces onto a pending entry with the
+     * SAME `(event, targetTrait)` that is itself tick-stamped — same contract
+     * as `@almadar/ui`'s `lib/event-queue-coalesce.ts` `enqueueEvent` (see
+     * that file's tests, mirrored in `client-kernel.test.ts`): only the
+     * pending entry's `payload` is replaced (its FIFO slot and every other
+     * field are kept), a sourceless/non-tick entry is never coalesced, and an
+     * entry already shifted off the queue (in flight) is never a coalesce
+     * target. Every caller coalesced onto the same pending entry resolves to
+     * that ONE entry's eventual outcome.
+     *
+     * A tick-stamped entry resolves after its LOCAL dispatch; its post goes
+     * out on a per-(event, trait) newest-wins lane outside the FIFO, with no
+     * rollback, so a tick round trip never delays a command.
+     */
+    dispatch(request: EventRequest, hooks?: ClientDispatchHooks): Promise<ClientKernelOutcome>;
+    /**
+     * Dispatch a server-pushed live message of THIS client's own running
+     * request (`PushTarget` `origin`). Outside the FIFO, because the request
+     * producing it is the entry the FIFO is waiting on; progress dispatches run
+     * one at a time, in push order, and never mark traits awaiting.
+     */
+    dispatchProgress(request: EventRequest): Promise<ClientKernelOutcome>;
+    /**
+     * Show the result of a dispatch the host ran on its own (`EventTransport.subscribeHostDispatches`):
+     * the host's states, rows and render land in this view. Nothing runs here and nothing is posted,
+     * so the dispatch's effects happen once, on the host. Host dispatches fold one at a time, in order.
+     */
+    foldHostDispatch(request: EventRequest, response: EventResponse): Promise<ClientKernelOutcome>;
+    /**
+     * Hand the kernel an emit that happened outside it (a bus emit with no dispatch behind it, a server push). The kernel
+     * decides who hears it: the emitter's own arm and every declared `listens` route (EXEC-DISP). Nothing is routed here.
+     */
+    deliverEmit(emitted: EmittedEvent): Promise<ClientEmitOutcome>;
+    /**
+     * Hand the kernel an emit another client made (a server push): it reaches its declared `listens` routes only, guards and
+     * payload mapping included. The emitter's own arm does not run here, and neither the emit's `dispatched` stamp nor the
+     * host's fan-out narrows who hears it.
+     */
+    deliverToListeners(emitted: EmittedEvent): Promise<ClientEmitOutcome>;
+    /**
+     * Hand the kernel the live message of this client's own running call, whose emitter already ran its own arm as that call's
+     * progress dispatch: it reaches its declared `listens` routes like `deliverToListeners`, except that a route back to the
+     * emitter under the emitted name is that arm again and does not run twice.
+     */
+    deliverOriginEmit(emitted: EmittedEvent): Promise<ClientEmitOutcome>;
+    /**
+     * Mount several traits in ONE FIFO entry: every seed's local arm runs and
+     * paints, then one `mount` leg per owning orbital is posted and folded.
+     */
+    dispatchMount(seeds: readonly MountSeed[], hooks?: ClientMountHooks, base?: Pick<EventRequest, 'payload' | 'entityId' | 'clientId' | 'locale' | 'route'>): Promise<ClientMountOutcome>;
+    readonly store: CircuitStore;
+}
+/**
+ * Show the result of a dispatch THIS kernel already ran (a tick frame's aggregate response or one of its
+ * cascade dispatches): the response's states, rows and paint land in the view's store. Nothing runs and
+ * nothing is posted: the in-process kernel owns the state, so (unlike `foldHostDispatch`) the server fold
+ * (`applyServerResponse`) is never called. `traceHops` reports the response's executed hops to the transition
+ * observer; a frame's aggregate response carries tick hops the kernel's tick observer already reported. `notify` wakes the store's subscribers after the fold; a frame folds several responses and notifies on the last only.
+ */
+interface LocalFoldKernel {
+    foldLocalResponse(response: EventResponse, traceHops: boolean, notify: boolean): Promise<void>;
+}
+
+export type { ClientDispatchHooks, ClientEmitOutcome, ClientKernel, ClientKernelOutcome, ClientMountHooks, ClientMountOutcome, LocalFoldKernel };

package/dist/client/client-kernel.js

@@ -0,0 +1 @@
+import '../chunk-LZIOTBFX.js';

package/dist/client/declared-input-dispatch.d.ts

@@ -0,0 +1,22 @@
+import { ExternalInputRequest, EventRequest, EventResponse } from '@almadar/core';
+import { KernelEngine } from '../kernel/engine.js';
+import '@almadar/core/kernel-wire';
+import '../kernel/host.js';
+import '../effects/in-flight-calls.js';
+import '../service/service-provider.js';
+import '../kernel/program-effects.js';
+import '../kernel/secret-ports.js';
+import '../credentials/vault.js';
+import '../kernel/wire.js';
+import '../kernel/os-port.js';
+
+/**
+ * The dispatcher for declared external inputs. The server runtime and the in-process host (a
+ * browser extension's worker) both route outside-client inputs through it: the kernel says whether the
+ * input is declared, an undeclared one is refused identically everywhere and a declared one is an ordinary
+ * event addressed to its trait.
+ */
+
+declare function dispatchDeclaredInput(contract: Pick<KernelEngine, 'findExternalInput'>, orbitalName: string, request: ExternalInputRequest, send: (orbitalName: string, request: EventRequest) => Promise<EventResponse>): Promise<EventResponse>;
+
+export { dispatchDeclaredInput };

package/dist/client/declared-input-dispatch.js

@@ -0,0 +1 @@
+export { dispatchDeclaredInput } from '../chunk-LKWYCYX5.js';

package/dist/client/inbound-dispatch.d.ts

@@ -0,0 +1,24 @@
+import { InboundDelivery, EventRequest, EventResponse, InboundAnswer } from '@almadar/core';
+import { KernelEngine } from '../kernel/engine.js';
+import '@almadar/core/kernel-wire';
+import '../kernel/host.js';
+import '../effects/in-flight-calls.js';
+import '../service/service-provider.js';
+import '../kernel/program-effects.js';
+import '../kernel/secret-ports.js';
+import '../credentials/vault.js';
+import '../kernel/wire.js';
+import '../kernel/os-port.js';
+
+/**
+ * The dispatcher for inbound deliveries (EXEC-INBOUND-1). A host carries `{name, headers,
+ * rawBody}` from `/api/hooks/<name>`; the kernel decides whether the name is served, what payload the
+ * handler event is delivered with and what answer the handler's emit of its `answers` event is; this
+ * delivers the event through the host's own dispatch and writes what the kernel said.
+ */
+
+type InboundContract = Pick<KernelEngine, 'findInbound' | 'inboundPayload' | 'inboundAnswer' | 'credentialUnset' | 'dispatchFailed'>;
+declare function dispatchInbound(contract: InboundContract, name: string, delivery: InboundDelivery, send: (orbitalName: string, request: EventRequest) => Promise<EventResponse>, credential: (name: string) => Promise<string | null | undefined>): Promise<InboundAnswer>;
+
+export { dispatchInbound };
+export type { InboundContract };

package/dist/client/inbound-dispatch.js

@@ -0,0 +1 @@
+export { dispatchInbound } from '../chunk-P2N6K2IV.js';

package/dist/client/local-fold.d.ts

@@ -0,0 +1,33 @@
+import { EventResponse } from '@almadar/core';
+import { FrameDelta } from '@almadar/core/kernel-wire';
+import { LocalFoldKernel } from './client-kernel.js';
+import { CircuitStore } from './circuit-store.js';
+import { TransitionObserver } from './trait-types.js';
+import './awaiting.js';
+import './state-book.js';
+
+/**
+ * The view's side of a dispatch the in-process kernel already ran: report its executed hops to the observer,
+ * paint its states, frame delta and sticky callsite payloads into the `CircuitStore`, then notify subscribers.
+ * One implementation for every response the kernel produces (a dispatch, a mount seed, a posted leg's fold,
+ * a tick frame).
+ */
+
+/** A snapshot of the kernel's frames for a painter at `since` (the kernel's `framesSince`). */
+type FramesSince = (since: number) => FrameDelta;
+/** Paint a response's states. Rows are the kernel's frame delta, painted by [`paintFrames`]. */
+declare function paintStates(store: CircuitStore, response: EventResponse): void;
+/** Paint the kernel's frame delta; on a version gap, ask the kernel for the snapshot and paint that. */
+declare function paintFrames(store: CircuitStore, delta: FrameDelta | undefined, framesSince: FramesSince): void;
+/** Paint a response the in-process kernel produced: its states, payloads and frames. */
+declare function paintResponse(store: CircuitStore, framesSince: FramesSince, response: EventResponse): void;
+declare function traceResponse(observer: TransitionObserver | undefined, response: EventResponse): void;
+interface LocalFoldOptions {
+    store: CircuitStore;
+    framesSince: FramesSince;
+    observer?: TransitionObserver;
+}
+declare function createLocalFold(opts: LocalFoldOptions): LocalFoldKernel;
+
+export { createLocalFold, paintFrames, paintResponse, paintStates, traceResponse };
+export type { FramesSince, LocalFoldOptions };

package/dist/client/local-fold.js

@@ -0,0 +1 @@
+export { createLocalFold, paintFrames, paintResponse, paintStates, traceResponse } from '../chunk-QCJWPXLH.js';

package/dist/client/render-sigils.d.ts

@@ -0,0 +1,24 @@
+import { OrbitalDefinition, NavItem, PageRef } from '@almadar/core';
+
+/**
+ * The render sigils `@pages` and `@currentTheme`, assembled one way for every effect
+ * stage (the server's and the index runner's). Mirrors the compiler's resolver.
+ *
+ * @packageDocumentation
+ */
+
+/** The baseline theme `@currentTheme` falls back to when no orbital or app theme is declared. Mirrors the compiler's `DEFAULT_THEME_KEY`. */
+declare const DEFAULT_THEME_KEY = "minimalist-light";
+/**
+ * Map an orbital's inline pages to the `NavItem[]` the `@pages` sigil yields: one
+ * entry per root page that declares `@label` (`href = page.path`, its `@icon` and
+ * `@roles`). References (resolved before any stage runs) and `:param` pages are
+ * skipped — the Rust resolver's filter.
+ */
+declare function inlineNavItems(pages: readonly PageRef[]): NavItem[];
+/** `@pages` is app-wide: the root pages of every orbital, deduped by path, in orbital order. */
+declare function appNavItems(orbitals: Iterable<Pick<OrbitalDefinition, 'pages'>>): NavItem[];
+/** `@currentTheme`: the orbital's declared theme, else the app's theme key, else the baseline. */
+declare function sigilThemeKey(orbitalTheme: OrbitalDefinition['theme'], appThemeKey?: string): string;
+
+export { DEFAULT_THEME_KEY, appNavItems, inlineNavItems, sigilThemeKey };

package/dist/client/render-sigils.js

@@ -0,0 +1 @@
+export { DEFAULT_THEME_KEY, appNavItems, inlineNavItems, sigilThemeKey } from '../chunk-UP6GGGAN.js';

package/dist/client/state-book.d.ts

@@ -0,0 +1,30 @@
+import { TraitDefinition } from '@almadar/core';
+import { TransitionObserver, TraitState, RollbackCause } from './trait-types.js';
+import '@almadar/core/kernel-wire';
+
+/**
+ * The client's record of each trait's state, as the kernel reports it. The kernel decides every transition;
+ * this book only holds the states its responses carry, so a render can read them synchronously.
+ *
+ * @packageDocumentation
+ */
+
+/** The state a trait starts in: the one marked initial, else the first declared. */
+declare function findInitialState(trait: TraitDefinition): string;
+declare function createInitialTraitState(trait: TraitDefinition): TraitState;
+declare class StateBook {
+    private readonly observer?;
+    private readonly traits;
+    private readonly states;
+    constructor(traits?: readonly TraitDefinition[], observer?: TransitionObserver | undefined);
+    /** The trait's state, its initial state until the kernel reports one; `undefined` for a trait not on the page. */
+    getState(traitName: string, entityId?: string): TraitState | undefined;
+    /** Each trait's singleton-scope state. */
+    getAllStates(): Map<string, TraitState>;
+    /** Record the state the kernel reports. No-op for a trait not on the page. */
+    seedState(traitName: string, currentState: string, entityId?: string): void;
+    /** Undo an optimistic commit, reporting the hop back to the observer. */
+    rollbackState(traitName: string, toState: string, entityId: string | undefined, cause: RollbackCause): void;
+}
+
+export { StateBook, createInitialTraitState, findInitialState };

package/dist/client/state-book.js

@@ -0,0 +1 @@
+export { StateBook, createInitialTraitState, findInitialState } from '../chunk-A2JJT4GA.js';

package/dist/client/trait-mount-error.d.ts

@@ -0,0 +1,9 @@
+/** A mount seed's lifecycle dispatch threw: names that trait and event, the original error's message kept. */
+declare class TraitMountError extends Error {
+    readonly trait: string;
+    readonly event: string;
+    readonly original: Error;
+    constructor(trait: string, event: string, original: Error);
+}
+
+export { TraitMountError };

package/dist/client/trait-mount-error.js

@@ -0,0 +1 @@
+export { TraitMountError } from '../chunk-IOPUS6Q5.js';

package/dist/client/trait-types.d.ts

@@ -0,0 +1,67 @@
+import { SExpr, TraitConfig } from '@almadar/core';
+import { HopObservation } from '@almadar/core/kernel-wire';
+
+/**
+ * The client host's view of a trait: its running state, its flat definition, and the observer a
+ * verifier hangs on committed hops. Client-host types, not language contract.
+ */
+
+/**
+ * State of a single trait's state machine
+ */
+interface TraitState {
+    /** Trait name */
+    traitName: string;
+    /** Current state name */
+    currentState: string;
+    /** Previous state (null if initial) */
+    previousState: string | null;
+    /** Last event that caused a transition */
+    lastEvent: string | null;
+    /** Custom context data */
+    context: TraitConfig;
+}
+/**
+ * Observer interface for recording transition and effect traces.
+ * Implement this to wire in the verificationRegistry or other monitoring tools.
+ *
+ * The runtime calls these hooks automatically when transitions execute and
+ * effects complete, enabling runtime verification without tight coupling.
+ */
+interface TransitionObserver {
+    /**
+     * Called after a transition is processed (whether or not it executed).
+     */
+    onTransition(trace: {
+        traitName: string;
+        from: string;
+        to: string;
+        event: string;
+        /** The arm that fired, by its position among the state's arms for the event. */
+        firedArm?: number;
+        guardResult?: boolean;
+        effects: Array<{
+            type: string;
+            args: SExpr[];
+            status: "executed" | "failed" | "skipped";
+            error?: string;
+            durationMs?: number;
+        }>;
+        /** Recorded for a verifier only (`setRecordEntityAfter`): the payload and `@entity` before and after. */
+        observed?: HopObservation;
+    }): void;
+    /**
+     * Called when an optimistic dispatch is undone: the state moved back from
+     * `from` to `to` because the server rejected the leg or never answered.
+     */
+    onRollback?(trace: {
+        traitName: string;
+        from: string;
+        to: string;
+        cause: RollbackCause;
+    }): void;
+}
+/** Why an optimistic dispatch was rolled back. */
+type RollbackCause = 'transport-error' | 'server-rejected';
+
+export type { RollbackCause, TraitState, TransitionObserver };

package/dist/client/trait-types.js

@@ -0,0 +1 @@
+import '../chunk-P53CKOME.js';

package/dist/credentials/env-vars.d.ts

@@ -0,0 +1,18 @@
+/** Env var holding the 64-char-hex AES-256 master key (Secret Manager in production). */
+declare const CREDENTIAL_MASTER_KEY_ENV = "ALMADAR_CREDENTIAL_MASTER_KEY";
+/** Env var holding the PREVIOUS master key during a rotation window: `rotate` re-encrypts every row under the current key, then the previous key is retired. */
+declare const CREDENTIAL_PREVIOUS_MASTER_KEY_ENV = "ALMADAR_CREDENTIAL_MASTER_KEY_PREVIOUS";
+/**
+ * Bootstrap secrets that must NEVER enter store custody: the master key(s)
+ * decrypt the store itself, so seeding them as rows (encrypted under
+ * themselves) or stripping them from the env would be circular.
+ */
+declare const STORE_BOOTSTRAP_ENV_VARS: ReadonlySet<string>;
+/**
+ * Every env var a forked verify/harness process must not inherit so it can never see, and therefore
+ * never spend, a real credential: the store's bootstrap keys. A program's own credentials are declared
+ * in the program (`program_credentials` in the kernel) and held in the store, never in the fork's env.
+ */
+declare function allCredentialEnvVars(): Set<string>;
+
+export { CREDENTIAL_MASTER_KEY_ENV, CREDENTIAL_PREVIOUS_MASTER_KEY_ENV, STORE_BOOTSTRAP_ENV_VARS, allCredentialEnvVars };

package/dist/credentials/env-vars.js

@@ -0,0 +1 @@
+export { CREDENTIAL_MASTER_KEY_ENV, CREDENTIAL_PREVIOUS_MASTER_KEY_ENV, STORE_BOOTSTRAP_ENV_VARS, allCredentialEnvVars } from '../chunk-VNGXRYFF.js';

package/dist/credentials/scope.d.ts

@@ -0,0 +1,51 @@
+import { CredentialVault } from './vault.js';
+import '@almadar/core';
+import '@almadar/core/kernel-wire';
+
+/** Whether integrations answer with mock data or call their real backends. */
+type CredentialMode = 'mock' | 'real';
+/** The mode an env asks for: `ALMADAR_INTEGRATIONS_MODE=mock` or `USE_MOCK_DATA=true` mean mock. */
+declare function credentialModeFromEnv(env: Record<string, string | undefined>): CredentialMode;
+/** The host's live mode switch, reachable from the kernel's `credential-mode` asks. */
+interface CredentialModeControl {
+    readonly mode: CredentialMode;
+    setMode(mode: CredentialMode): void;
+}
+/** The per-tenant credential scope: a Node host installs AsyncLocalStorage (`@almadar/shell-node`); a browser has none. */
+interface CredentialScopeStorage {
+    run<T>(store: CredentialVault, fn: () => T): T;
+    getStore(): CredentialVault | undefined;
+}
+declare function installCredentialScopeStorage(storage: CredentialScopeStorage): void;
+/**
+ * Run `fn` as one tenant of a multi-tenant host: every credential reference resolved inside it
+ * (across awaits) comes from `store` alone, never from the host's env or installed store.
+ */
+declare function runWithCredentialScope<T>(store: CredentialVault, fn: () => T): T;
+/** The host's mode switch, installed beside its credential store. */
+declare function installModeControl(control: CredentialModeControl): void;
+declare function getModeControl(): CredentialModeControl | null;
+/**
+ * Install the host's credential store as the process-wide resolution source.
+ * Called once at boot (playground / generated server) after the store is
+ * constructed over the host's persistence adapter.
+ */
+declare function installCredentialStore(store: CredentialVault): void;
+/** The installed store, for the credentials admin service. */
+declare function getInstalledCredentialStore(): CredentialVault | null;
+declare function getEffectiveCredentialStore(): CredentialVault | null;
+/** Testing/reset hook. */
+declare function uninstallCredentialStore(): void;
+/** The env var selecting store-only resolution (the kernel rule `credential_admin::SOURCE_VAR`). */
+declare const CREDENTIALS_SOURCE_ENV = "ALMADAR_CREDENTIALS_SOURCE";
+/** Whether `env` selects store-only resolution: exactly `ALMADAR_CREDENTIALS_SOURCE=store`. */
+declare function credentialsFromStoreOnly(env: Record<string, string | undefined>): boolean;
+/**
+ * The one credential-reference resolver: store, then env, then undefined; inside a tenant's
+ * credential scope, that tenant's store only. With `ALMADAR_CREDENTIALS_SOURCE=store` every
+ * name but a host setting answers from the store alone, never from the env. `ref` is an env-var name.
+ */
+declare function resolveCredentialRef(ref: string, env?: Record<string, string | undefined>, principal?: string): string | undefined;
+
+export { CREDENTIALS_SOURCE_ENV, credentialModeFromEnv, credentialsFromStoreOnly, getEffectiveCredentialStore, getInstalledCredentialStore, getModeControl, installCredentialScopeStorage, installCredentialStore, installModeControl, resolveCredentialRef, runWithCredentialScope, uninstallCredentialStore };
+export type { CredentialMode, CredentialModeControl, CredentialScopeStorage };

package/dist/credentials/scope.js

@@ -0,0 +1 @@
+export { CREDENTIALS_SOURCE_ENV, credentialModeFromEnv, credentialsFromStoreOnly, getEffectiveCredentialStore, getInstalledCredentialStore, getModeControl, installCredentialScopeStorage, installCredentialStore, installModeControl, resolveCredentialRef, runWithCredentialScope, uninstallCredentialStore } from '../chunk-HLOUDLPI.js';