@almadar/shell-runtime 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,76 @@
+import { AwaitingRegistry } from './awaiting.js';
+import { StateBook } from './state-book.js';
+import { EntityRow, EventPayload, TraitDefinition } from '@almadar/core';
+import { RollbackCause, TransitionObserver } from './trait-types.js';
+import '@almadar/core/kernel-wire';
+
+/**
+ * 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;
+}
+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>;
+    /** Embedded child → the payload its composer last composed it with (sticky `@callsitePayload`). */
+    readonly callsitePayloads: Map<string, EventPayload>;
+    /** 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, TraitSnapshot };

package/dist/client/circuit-store.js

@@ -0,0 +1,4 @@
+export { createMemoryCircuitStore } from '../chunk-ODJCZ27I.js';
+import '../chunk-Q2H75UYT.js';
+import '../chunk-HC6ERSAH.js';
+import '../chunk-MLKGABMK.js';

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

@@ -0,0 +1,113 @@
+import { OrbitalEventResponse, OrbitalEventRequest, DispatchMode, 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: OrbitalEventResponse;
+    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<OrbitalEventResponse, 'clientEffects' | '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<OrbitalEventResponse, 'clientEffects' | 'clientEffectsByTrait'> | undefined>;
+}
+/** Per-dispatch hooks: `onLocal` sees the locally-evaluated response before its server leg is sent. */
+interface ClientDispatchHooks {
+    onLocal?: (local: OrbitalEventResponse) => void;
+}
+/** Mount hooks: `onLocal` sees each seed's local response before the mount leg is sent. */
+interface ClientMountHooks {
+    onLocal?: (trait: string, local: OrbitalEventResponse) => void;
+}
+/** 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: OrbitalEventResponse;
+    }>;
+    /** 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<OrbitalEventResponse, 'clientEffects' | 'clientEffectsByTrait'>;
+    emittedEvents: OrbitalEventResponse['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: OrbitalEventRequest, 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: OrbitalEventRequest): 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: OrbitalEventRequest, response: OrbitalEventResponse): Promise<ClientKernelOutcome>;
+    /**
+     * 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<OrbitalEventRequest, 'payload' | 'entityId' | 'clientId' | 'locale'>): 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: OrbitalEventResponse, traceHops: boolean, notify: boolean): Promise<void>;
+}
+
+export type { ClientDispatchHooks, 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,5 @@
+import { OrbitalSchema, ExternalInputRequest, OrbitalEventRequest, OrbitalEventResponse } from '@almadar/core';
+
+declare function dispatchDeclaredInput(schema: OrbitalSchema | null | undefined, orbitalName: string, request: ExternalInputRequest, send: (orbitalName: string, request: OrbitalEventRequest) => Promise<OrbitalEventResponse>): Promise<OrbitalEventResponse>;
+
+export { dispatchDeclaredInput };

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

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

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

@@ -0,0 +1,5 @@
+import { OrbitalSchema, InboundDelivery, OrbitalEventRequest, OrbitalEventResponse, InboundAnswer } from '@almadar/core';
+
+declare function dispatchInbound(schema: OrbitalSchema | null | undefined, name: string, delivery: InboundDelivery, send: (orbitalName: string, request: OrbitalEventRequest) => Promise<OrbitalEventResponse>, credential: (name: string) => Promise<string | null | undefined>): Promise<InboundAnswer>;
+
+export { dispatchInbound };

package/dist/client/inbound-dispatch.js

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

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

@@ -0,0 +1,26 @@
+import { OrbitalEventResponse } from '@almadar/core';
+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';
+import '@almadar/core/kernel-wire';
+
+/**
+ * The view's side of a dispatch the in-process kernel already ran: report its executed hops to the observer,
+ * mirror its states, rows 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).
+ */
+
+declare function mirrorResponse(store: CircuitStore, frameKeyOf: (trait: string) => string | undefined, response: OrbitalEventResponse): void;
+declare function traceResponse(observer: TransitionObserver | undefined, response: OrbitalEventResponse): void;
+interface LocalFoldOptions {
+    store: CircuitStore;
+    frameKeyOf(trait: string): string | undefined;
+    observer?: TransitionObserver;
+}
+declare function createLocalFold(opts: LocalFoldOptions): LocalFoldKernel;
+
+export { createLocalFold, mirrorResponse, traceResponse };
+export type { LocalFoldOptions };

package/dist/client/local-fold.js

@@ -0,0 +1,2 @@
+export { createLocalFold, mirrorResponse, traceResponse } from '../chunk-QQRDUMB2.js';
+import '../chunk-MLKGABMK.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,2 @@
+export { DEFAULT_THEME_KEY, appNavItems, inlineNavItems, sigilThemeKey } from '../chunk-UP6GGGAN.js';
+import '../chunk-MLKGABMK.js';

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

@@ -0,0 +1,37 @@
+import { TraitDefinition, EventId } from '@almadar/core';
+import { TransitionObserver, TraitState, RollbackCause } from './trait-types.js';
+import '@almadar/core/kernel-wire';
+
+/** 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;
+/**
+ * Every transition out of `currentState` on the event, in declaration order. An event id is compared with a
+ * transition's own id when both carry one, so an arm still matches after its event was renamed.
+ */
+declare function findMatchingTransitions(trait: TraitDefinition, currentState: string, eventKey: string, eventId?: EventId): TraitDefinition['transitions'];
+/** The first transition out of `currentState` on the event, ignoring guards. */
+declare function findTransition(trait: TraitDefinition, currentState: string, eventKey: string, eventId?: EventId): TraitDefinition['transitions'][0] | undefined;
+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>;
+    /** Whether the trait has an arm on the event from its current state. */
+    canHandleEvent(traitName: string, eventKey: string, entityId?: string, eventId?: EventId): boolean;
+    /**
+     * The lifecycle event an embedded child can be repainted with: the one it handles from its current state,
+     * provided every matching arm stays in that state and only renders.
+     */
+    repaintLifecycleEvent(traitName: string, entityId?: string): string | undefined;
+    /** 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, findMatchingTransitions, findTransition };

package/dist/client/state-book.js

@@ -0,0 +1,2 @@
+export { StateBook, createInitialTraitState, findInitialState, findMatchingTransitions, findTransition } from '../chunk-Q2H75UYT.js';
+import '../chunk-MLKGABMK.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,2 @@
+export { TraitMountError } from '../chunk-IOPUS6Q5.js';
+import '../chunk-MLKGABMK.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,14 @@
+/**
+ * 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 { STORE_BOOTSTRAP_ENV_VARS, allCredentialEnvVars };

package/dist/credentials/env-vars.js

@@ -0,0 +1,3 @@
+export { STORE_BOOTSTRAP_ENV_VARS, allCredentialEnvVars } from '../chunk-Q7JK4KY7.js';
+import '../chunk-NAECVIAR.js';
+import '../chunk-MLKGABMK.js';

package/dist/credentials/scope.d.ts

@@ -0,0 +1,50 @@
+import { CredentialStore } from './store.js';
+import '@almadar/core';
+
+/** 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: CredentialStore, fn: () => T): T;
+    getStore(): CredentialStore | 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: CredentialStore, 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: CredentialStore): void;
+/** The installed store, for the credentials admin service. */
+declare function getInstalledCredentialStore(): CredentialStore | null;
+declare function getEffectiveCredentialStore(): CredentialStore | 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,2 @@
+export { CREDENTIALS_SOURCE_ENV, credentialModeFromEnv, credentialsFromStoreOnly, getEffectiveCredentialStore, getInstalledCredentialStore, getModeControl, installCredentialScopeStorage, installCredentialStore, installModeControl, resolveCredentialRef, runWithCredentialScope, uninstallCredentialStore } from '../chunk-HLOUDLPI.js';
+import '../chunk-MLKGABMK.js';

package/dist/credentials/seed.d.ts

@@ -0,0 +1,21 @@
+import { CredentialStore } from './store.js';
+import '@almadar/core';
+
+/** One credential the app declares: the service group it belongs to and the env var / credential name. */
+interface DeclaredCredential {
+    readonly service: string;
+    readonly envVar: string;
+}
+/** The kernel export that decides a seed (`credential_admin::seed_plan`): the rows to copy, never a value. */
+interface CredentialSeedKernel {
+    credentialSeedPlan(declaredJson: string, heldJson: string, presentJson: string): string;
+}
+/**
+ * The boot of `ALMADAR_CREDENTIALS_SOURCE=store`: the kernel plans which declared credentials the store lacks and the env
+ * holds, and this copies each into the store, so the env stays the way to hand a deployment its first keys. A name
+ * declared twice seeds once, a held row is never overwritten. Returns the count.
+ */
+declare function seedCredentialStore(store: CredentialStore, declared: readonly DeclaredCredential[], env: Record<string, string | undefined>, kernel: CredentialSeedKernel): Promise<number>;
+
+export { seedCredentialStore };
+export type { CredentialSeedKernel, DeclaredCredential };

package/dist/credentials/seed.js

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

package/dist/credentials/store.d.ts

@@ -0,0 +1,110 @@
+import { PersistenceAdapter, CredentialIdentity } from '@almadar/core';
+
+/** Entity type the credential rows persist under (never a `.lolo`-declared entity). */
+declare const CREDENTIAL_ENTITY_TYPE = "AlmadarIntegrationCredential";
+/** 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 (I-28):
+ * decryption tries the row's stamped key, `rotate()` re-encrypts every row
+ * under the current key, then the previous key is retired from the env.
+ */
+declare const CREDENTIAL_PREVIOUS_MASTER_KEY_ENV = "ALMADAR_CREDENTIAL_MASTER_KEY_PREVIOUS";
+/** The slice of the persistence contract the credential store uses. */
+type CredentialPersistence = Pick<PersistenceAdapter, 'create' | 'update' | 'delete' | 'list'>;
+/** Entity type the shared one-use values (a pending OAuth grant) persist under. */
+declare const DERIVED_ENTITY_TYPE = "AlmadarKernelDerivedSecret";
+/** What an adapter also offers when it can share one-use values across instances: a read by id, and a conditional delete where the store has one. */
+type DerivedPersistence = Pick<PersistenceAdapter, 'getById'> & Partial<Pick<PersistenceAdapter, 'writeWhere' | 'writeCapabilities'>>;
+/** Masked view of one stored credential — safe to return to a settings page. */
+interface CredentialEntry {
+    service: string;
+    envVar: string;
+    last4: string;
+    updatedAt: number;
+    principal?: CredentialIdentity['principal'];
+}
+/**
+ * Tenant-scoped (app-wide) credential store: one AES-256-GCM-encrypted row
+ * per (service, envVar) through the host's persistence adapter, master key
+ * `ALMADAR_CREDENTIAL_MASTER_KEY` held alone in the platform secret store.
+ *
+ * Resolution contract: credential keys ARE env-var names (the same names
+ * `serviceCredentials` declares and `connectionRef` carries), so a stored
+ * value transparently shadows its env counterpart — store → env →
+ * unconfigured, everywhere.
+ *
+ * `warm()` decrypts all rows into memory so resolution stays synchronous;
+ * every write re-warms the affected entry and notifies subscribers (the
+ * `RuntimeIntegrationManager` re-configures on that signal, so new keys go
+ * live without a restart).
+ */
+declare class CredentialStore {
+    private readonly adapter;
+    private readonly masterKeyHex;
+    private readonly previousKeyHex;
+    private readonly byIdentity;
+    private readonly listeners;
+    private warmed;
+    constructor(adapter: CredentialPersistence, masterKey?: string, previousMasterKey?: string);
+    /** True when a valid master key is present (writes and decryption enabled). */
+    get enabled(): boolean;
+    /** Subscribe to credential changes; returns an unsubscribe function. */
+    subscribe(listener: (principal?: string) => void): () => void;
+    private notify;
+    private encrypt;
+    private decryptWithKey;
+    /**
+     * Decrypt one row, selecting the key by the row's stamped `keyId` (I-28):
+     * current key first, then the rotation-window previous key. Legacy rows
+     * (no `keyId`) try current then previous. Returns null when no held key
+     * decrypts the row — the row is unreadable, never silently wrong (GCM
+     * auth tags make a wrong-key success impossible).
+     */
+    private decryptRow;
+    /**
+     * Load and decrypt every stored row into memory. Returns the number of
+     * resolvable credentials. Without a master key nothing decrypts (rows are
+     * left in place, resolution falls through to env).
+     */
+    warm(): Promise<number>;
+    /** Resolve one credential by env-var name (warmed values only). */
+    resolve(envVar: string, principal?: string): string | undefined;
+    /** The non-secret account label stored in the clear beside a credential's ciphertext; undefined when its row carries none. */
+    label(envVar: string, principal?: string): string | undefined;
+    /** All warmed values as an env-shaped map, for merging over the process env. */
+    snapshotEnv(): Record<string, string>;
+    /** Masked entries for display — never includes plaintext. */
+    entries(principal?: string): CredentialEntry[];
+    /**
+     * Upsert one credential (encrypts, persists, re-warms the entry, notifies). `label` is a non-secret account name kept
+     * in the clear in the row beside the ciphertext; left out, the row's label stays as it is.
+     */
+    set(service: string, envVar: string, value: string, principal?: string, label?: string): Promise<CredentialEntry>;
+    /**
+     * Re-encrypt every readable row under the CURRENT master key (I-28).
+     * Rotation window: deploy the new key as `ALMADAR_CREDENTIAL_MASTER_KEY`
+     * with the old one as `..._PREVIOUS`, call `rotate()`, then retire the
+     * previous key. Rows no held key can read are counted, never dropped.
+     */
+    rotate(): Promise<{
+        rotated: number;
+        alreadyCurrent: number;
+        unreadable: number;
+    }>;
+    /** Whether one-use values are shared through the adapter: a master key and an adapter that reads a row by id. */
+    get sharesDerived(): boolean;
+    /** Keep `value` encrypted in the adapter until `expiresAt` (epoch ms) so any instance on the same store can take it once. */
+    holdDerived(name: string, value: string, expiresAt: number, principal?: string): Promise<void>;
+    /**
+     * Remove and return a held value. Where the adapter has a conditional delete only the instance whose delete
+     * lands gets the value; elsewhere the delete is unconditional, so two instances racing for one state can both
+     * read it. An expired value is consumed and not returned.
+     */
+    takeDerived(name: string, principal: string | undefined, now: number): Promise<string | undefined>;
+    /** Delete one credential row; resolution falls back to env afterwards. */
+    remove(envVar: string, principal?: string): Promise<boolean>;
+}
+
+export { CREDENTIAL_ENTITY_TYPE, CREDENTIAL_MASTER_KEY_ENV, CREDENTIAL_PREVIOUS_MASTER_KEY_ENV, CredentialStore, DERIVED_ENTITY_TYPE };
+export type { CredentialEntry, CredentialPersistence, DerivedPersistence };

package/dist/credentials/store.js

@@ -0,0 +1,2 @@
+export { CREDENTIAL_ENTITY_TYPE, CREDENTIAL_MASTER_KEY_ENV, CREDENTIAL_PREVIOUS_MASTER_KEY_ENV, CredentialStore, DERIVED_ENTITY_TYPE } from '../chunk-NAECVIAR.js';
+import '../chunk-MLKGABMK.js';