lanka 1.0.1 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 **◆ core** · Core
 
-> Ten subsystems, two peer dependencies, five extension points.
+> Twelve subsystems, two peer dependencies, five extension points.
 
 One, unscoped. Everything depends on it; it depends on nothing.
 
@@ -16,7 +16,8 @@ One, unscoped. Everything depends on it; it depends on nothing.
 | --- | --- | --- |
 | `useRequestMiddleware(mw)` | wrap every request | yes |
 | `inFlight.subscribe(fn)` | observe the number of requests on the wire | yes |
-| `lankaEventBus.addMiddleware` | intercept bus events | yes |
+| `lankaEventBus.addMiddleware` | intercept bus events, and stop one | yes |
+| `lankaEventBus.addObserver` | hear what became of each dispatch | yes |
 | `LankaLogger sinks` | where log output goes | yes |
 | `use(plugin)` | register a whole plugin | yes |
 
@@ -46,6 +47,7 @@ the seal on `internal`, and catches a subsystem added as a folder and forgotten
 - `src/mock/`
 - `src/errors/`
 - `src/scenario/`
+- `src/stream/`
 - `src/viewmodel/`
 - `src/logger/`
 - `src/internal/` — **not exported.** Refactored without a major.
@@ -226,7 +228,7 @@ to rename.
 
 `ViewModel` shortens to `VM` in class, factory and type names: `ALankaVM` and
 `createLankaVM` are written in every screen file — the same ViewModel reached from
-either style, one of the nine roles `skills/parity/SKILL.md` governs.
+either style, one of the roles `skills/parity/SKILL.md` governs.
 
 Three names stay bare — `isRecord`, `getStringField`, `generateUuid`. They are pure
 utilities over ordinary values; a collision there is resolved at the import site, which

package/dist/{ALankaGateway-ExlRGT3D.d.ts → ALankaGateway-CkW1LbKE.d.ts}

@@ -1,5 +1,34 @@
 import { I as ILankaValidator } from './lankaStandardValidator-CL-r-zEV.js';
 
+/**
+ * `RequestInit`, with the body a JSON API actually sends.
+ *
+ * `RequestInit["body"]` is `BodyInit | null` — a string, a `FormData`, a blob,
+ * bytes. It is what `fetch` accepts and it is NOT what a gateway method writes:
+ * every one of them writes `body: { name, email }`, an object, and lets the
+ * transport encode it.
+ *
+ * The framework's transport has always encoded that object. The TYPE never
+ * admitted it, and the cost was not a cast at the call site — it was a fork. A
+ * consumer could not write `body: { … }` against `RequestInit`, so they declared
+ * their own options type; declaring it made every shipped transport
+ * unassignable, because those were fixed to `RequestInit`; so they wrote a
+ * transport too, and with it a base URL, a CSRF header and an auth refresh the
+ * framework already had. One wrong type produced a re-implementation of three
+ * packages.
+ *
+ * `unknown` rather than a union of the encodable shapes: the transport decides
+ * by INSPECTING the value, and a type listing what it accepts would have to be
+ * kept in step with that inspection by hand. What is not a `BodyInit` is JSON —
+ * that is the whole rule, and it needs no enumeration.
+ */
+type TLankaRequestInit = Omit<RequestInit, "body"> & {
+    /**
+     * Anything. A `BodyInit` travels as given; everything else is encoded as JSON.
+     */
+    body?: unknown;
+};
+
 /**
  * Transport options plus what core controls.
  *
@@ -26,7 +55,7 @@ type TLankaExecuteOptions<TOptions> = TOptions & {
  * is how development without a backend works, and a request that ignored it
  * would silently disable mock mode for the gateway holding it.
  */
-interface ILankaRequest<TOptions = RequestInit> {
+interface ILankaRequest<TOptions = TLankaRequestInit> {
     /**
      * Sends the request and returns the value the caller asked for.
      *
@@ -68,7 +97,15 @@ interface IALankaGatewayConfig<TOptions> {
      * reads it.
      */
     queryParamsHandler?: TLankaQueryBuilder;
-    /** Validation service (DI). May be replaced for tests / migration. */
+    /**
+     * The validator a method checks a response body with. Defaults to
+     * `lankaStandardValidator`.
+     *
+     * Reachable as `this.validationService` in a class and as
+     * `validationService` in the functional context. A test hands one that
+     * records what it was asked; a migration hands one that accepts a shape the
+     * new schema does not yet.
+     */
     validationService?: ILankaValidator;
     /**
      * Enable mock mode. If undefined, reads from infrastructure flags (isMockMode).
@@ -77,9 +114,18 @@ interface IALankaGatewayConfig<TOptions> {
     useMock?: boolean;
 }
 
-declare abstract class ALankaGateway<TOptions = RequestInit> {
+declare abstract class ALankaGateway<TOptions = TLankaRequestInit> {
     protected requestExecutor: ILankaRequest<TOptions>;
     protected queryParamsHandler: TLankaQueryBuilder;
+    /**
+     * The validator a method checks a response body with.
+     *
+     * `config.validationService` when one was given, the Standard Schema port
+     * otherwise. It used to be accepted by the config and read by nothing: a
+     * consumer handing a test double to the gateway got the real validator and no
+     * error, which is the worst kind of ignored option — it looks honoured.
+     */
+    protected readonly validationService: ILankaValidator;
     protected readonly useMock: boolean;
     protected readonly basePath: string;
     protected constructor(config: IALankaGatewayConfig<TOptions>);
@@ -119,4 +165,4 @@ declare abstract class ALankaGateway<TOptions = RequestInit> {
     protected setQueryParamsHandler(handler: TLankaQueryBuilder): void;
 }
 
-export { ALankaGateway as A, type IALankaGatewayConfig as I, type TLankaExecuteOptions as T, type ILankaRequest as a, type TLankaQueryBuilder as b, type TLankaQueryParams as c };
+export { ALankaGateway as A, type IALankaGatewayConfig as I, type TLankaExecuteOptions as T, type TLankaRequestInit as a, type ILankaRequest as b, type TLankaQueryBuilder as c, type TLankaQueryParams as d };

package/dist/{ILankaScenarioMetadata-Bu-yggTZ.d.ts → ILankaScenarioMetadata-GoWWNEQL.d.ts}

@@ -1,4 +1,4 @@
-import { a as ILankaScenario } from './ILankaScenarioVM-DuCyPoyT.js';
+import { a as ILankaScenario } from './ILankaScenarioVM-DUsI-fSc.js';
 
 /**
  * Metadata about a registered scenario

package/dist/{ILankaScenarioVM-DuCyPoyT.d.ts → ILankaScenarioVM-DUsI-fSc.d.ts}

@@ -35,6 +35,17 @@ interface ILankaEventLog {
     eventType: string;
     /** ISO timestamp of when the event was dispatched. */
     timestamp: string;
+    /**
+     * Where this record falls in the order the bus saw events, counting from one.
+     *
+     * What `getEventLogs()` orders by, and the reason it can: a timestamp has
+     * millisecond resolution, and a burst dispatches many events inside one, so
+     * two records of one millisecond cannot be told apart by their time.
+     *
+     * Optional because a record built by anything other than the bus has no
+     * place in that order.
+     */
+    sequence?: number;
     /** The payload data of the event. */
     data: unknown;
     /** Optional captured stack trace (if enabled). */
@@ -77,6 +88,60 @@ type TLankaEventBusDecision = "pass" | {
  */
 type TLankaEventBusMiddleware<T> = (eventType: string, data: T) => TLankaEventBusDecision;
 
+/**
+ * What became of one dispatch, after the whole chain has run.
+ *
+ * The counterpart of `TLankaEventBusDecision`: a middleware RETURNS a decision,
+ * and the bus REPORTS an outcome. The two are deliberately symmetrical, and the
+ * asymmetry that matters is that an outcome cannot change anything.
+ */
+interface ILankaEventBusOutcome {
+    eventType: string;
+    /**
+     * Delivered to the subscribers, stopped by a middleware, or refused by the
+     * event's own schema.
+     *
+     * A union rather than an `enum`: a fourth outcome is then additive, which
+     * `skills/surface/SKILL.md` §6d.5 is about.
+     */
+    outcome: "delivered" | "stopped" | "invalid";
+    /**
+     * How many subscribers the event had when it was dispatched.
+     *
+     * The AUDIENCE, not the recipients: "three subscribers never heard it" is the
+     * sentence a stopped event needs, and a count that went to zero on a stop
+     * could not say it.
+     */
+    subscribers: number;
+    /** The reason a middleware gave, when one stopped it. */
+    stoppedBy?: string;
+}
+
+/**
+ * Something watching what became of each dispatch.
+ *
+ * ## Why this is not a middleware
+ *
+ * A middleware runs in a CHAIN and sees only what happened before it. The first
+ * one registered — which is what a diagnostic tool ends up being, since it is
+ * installed at bootstrap — cannot see a later middleware's decision to stop an
+ * event, so "which middleware stopped it" was a question nothing could answer.
+ * `@lankajs/plugin-devtools` carried a `stoppedBy` field that no code path ever
+ * filled, and its guide documented it.
+ *
+ * An observer runs ONCE per dispatch, after the chain, and its return value is
+ * ignored — it cannot decide anything. That is what keeps a diagnostic tool
+ * incapable of changing what it diagnoses, by construction rather than by
+ * discipline.
+ *
+ * ## Why the parameter is one object
+ *
+ * `skills/surface/SKILL.md` §6d.9: a callback's parameters are one object, so
+ * the day the bus learns to report how long delivery took, nobody's handler
+ * silently receives a different third argument.
+ */
+type TLankaEventBusObserver = (outcome: ILankaEventBusOutcome) => void;
+
 /**
  * How many recent values to replay to a new subscriber.
  *
@@ -88,12 +153,26 @@ declare class LankaEventBusInstance {
     private registry;
     /** Middleware registered on this instance. */
     private middlewares;
+    /**
+     * What is watching the OUTCOME of each dispatch — see `TLankaEventBusObserver`.
+     *
+     * An array rather than a set for one reason: `dispatch` reads `.length` on
+     * every event, and that check is what keeps an unobserved bus paying nothing.
+     */
+    private observers;
     /** Default maximum number of logs kept per event type. */
     private defaultMaxLogs;
     /** Internal timers for replay batching (avoid multiple replays in the same tick). */
     private pendingReplayTimers;
     /** Whether event logging is enabled. */
     private isEnableLogs;
+    /**
+     * How many events this bus has logged, ever — the order records are read in.
+     *
+     * Incremented only while logging is on, which is off by default, so a bus
+     * nobody is inspecting pays nothing for it.
+     */
+    private dispatchCount;
     /** Configures the bus, e.g. logging. Called once at application start. */
     enableLogs(): void;
     disableLogs(): void;
@@ -162,7 +241,28 @@ declare class LankaEventBusInstance {
     /** Removes previously added middleware. */
     removeMiddleware<T>(mw: TLankaEventBusMiddleware<T>): void;
     /**
-     * Log of dispatched events.
+     * Watches what became of each dispatch. An extension point — the sixth.
+     *
+     * An observer never decides: its return value is ignored, and a throw from it
+     * is logged rather than surfaced. A diagnostic tool that could stop an event
+     * would make "I disabled the inspector and it started working" a sentence
+     * somebody says.
+     */
+    addObserver(observer: TLankaEventBusObserver): void;
+    /** Removes a previously added observer. */
+    removeObserver(observer: TLankaEventBusObserver): void;
+    /**
+     * Log of dispatched events, oldest first, `limit` most recent kept.
+     *
+     * ## Why the records are sorted rather than concatenated
+     *
+     * They are held per event TYPE, so that each type keeps its own `maxLogs`
+     * and a chatty event cannot push a quiet one's history out. Concatenating
+     * those lists puts every record of one type before every record of the next,
+     * and `slice(-limit)` then answers the tail of whichever type the registry
+     * happened to hold last — not the most recent events at all. On a bus with
+     * one event type nothing looked wrong; on a real one the log was a
+     * chronology that had never been in chronological order.
      *
      * @param eventType Limit to one type
      * @param limit How many recent records to return
@@ -172,8 +272,21 @@ declare class LankaEventBusInstance {
     clearEvent(eventType: string): void;
     /** Removes every event and any scheduled replays. */
     clearAllEvents(): void;
-    /** Full bus reset: events and middleware. */
+    /** Full bus reset: events, middleware and observers. */
     reset(): void;
+    /**
+     * Tells the observers what became of a dispatch.
+     *
+     * The empty-list check is the whole reason a bus nobody watches pays nothing
+     * for this: `dispatch` is a hot path, and an iteration over an empty array on
+     * every event would be a cost paid by every application for a feature almost
+     * none of them installs. Measured in `LankaEventBusInstance.bench.ts`.
+     *
+     * An observer that throws is logged and the next one still runs — the same
+     * treatment a subscriber gets, and for the same reason: a diagnostic tool must
+     * not be able to break the application it is diagnosing.
+     */
+    private report;
     /**
      * Marks the last log record with the reason it was stopped.
      *
@@ -257,4 +370,4 @@ interface ILankaScenarioVM {
     resetScenario(): void;
 }
 
-export { type ILankaScenarioVM as I, LankaEventBusInstance as L, type TLankaReplayRequest as T, type ILankaScenario as a, type ILankaEventMetadata as b, type TLankaEventBusMiddleware as c, type ILankaEventLog as d, type TLankaEventBusDecision as e };
+export { type ILankaScenarioVM as I, LankaEventBusInstance as L, type TLankaReplayRequest as T, type ILankaScenario as a, type ILankaEventMetadata as b, type TLankaEventBusMiddleware as c, type TLankaEventBusObserver as d, type ILankaEventLog as e, type ILankaEventBusOutcome as f, type TLankaEventBusDecision as g };

package/dist/{LankaScenarioLocator-CLkq4MaJ.d.ts → LankaScenarioLocator-D86TIwiu.d.ts}

@@ -1,6 +1,6 @@
-import { a as ILankaScenario, I as ILankaScenarioVM } from './ILankaScenarioVM-DuCyPoyT.js';
-import { I as ILankaScenarioMetadata } from './ILankaScenarioMetadata-Bu-yggTZ.js';
-import { A as ALankaGateway } from './ALankaGateway-ExlRGT3D.js';
+import { a as ILankaScenario, I as ILankaScenarioVM } from './ILankaScenarioVM-DUsI-fSc.js';
+import { I as ILankaScenarioMetadata } from './ILankaScenarioMetadata-GoWWNEQL.js';
+import { A as ALankaGateway } from './ALankaGateway-CkW1LbKE.js';
 import { A as ALankaLocator } from './LankaSharedStoreLocator-zS2kLu-S.js';
 
 /**
@@ -31,7 +31,8 @@ declare class LankaScenariosRegistry {
      */
     register(scenario: ILankaScenario<unknown>): boolean;
     /**
-     * Unregister a scenario
+     * Removes a scenario, calling its `cleanup` if it declared one.
+     *
      * @param scenarioName Name of the scenario to unregister
      * @returns true if unregistered successfully, false if not found
      */
@@ -61,7 +62,11 @@ declare class LankaScenariosRegistry {
     /** Every registered ViewModel. */
     getAllViewModels(): ILankaScenarioVM[];
     /**
-     * Clears every registered scenario. Required by tests.
+     * Removes every scenario, calling each one's `cleanup`.
+     *
+     * What `dispose()` and the between-tests reset go through: `initialize` ran
+     * for every scenario at bootstrap, and this is the one moment its mirror
+     * image can run for all of them.
      */
     clear(): void;
 }

package/dist/_extend/index.d.ts

@@ -1,11 +1,11 @@
-export { L as LankaGatewayLocator, a as LankaScenarioLocator, b as LankaScenarioVMRegistry, c as LankaScenariosRegistry } from '../LankaScenarioLocator-CLkq4MaJ.js';
+export { L as LankaGatewayLocator, a as LankaScenarioLocator, b as LankaScenarioVMRegistry, c as LankaScenariosRegistry } from '../LankaScenarioLocator-D86TIwiu.js';
 import { a as ILankaLocator } from '../LankaSharedStoreLocator-zS2kLu-S.js';
 export { A as ALankaLocator, L as LankaSharedStoreLocator, b as LankaSingletonLocator } from '../LankaSharedStoreLocator-zS2kLu-S.js';
 export { c as createLankaScope } from '../createLankaScope-BiFxNQgl.js';
 export { c as composeLankaRequestMiddleware } from '../lankaRequestMiddleware-DAC5kCb7.js';
-import '../ILankaScenarioVM-DuCyPoyT.js';
-import '../ILankaScenarioMetadata-Bu-yggTZ.js';
-import '../ALankaGateway-ExlRGT3D.js';
+import '../ILankaScenarioVM-DUsI-fSc.js';
+import '../ILankaScenarioMetadata-GoWWNEQL.js';
+import '../ALankaGateway-CkW1LbKE.js';
 import '../lankaStandardValidator-CL-r-zEV.js';
 import '@standard-schema/spec';
 import '../ALankaSharedStore-B7uepuuk.js';

package/dist/_extend/index.js

@@ -2,11 +2,11 @@ import {
   LankaGatewayLocator,
   LankaScenarioLocator,
   createLankaScope
-} from "../chunk-MYZQYOMD.js";
+} from "../chunk-5MAQVBI2.js";
 import {
   LankaScenarioVMRegistry,
   LankaScenariosRegistry
-} from "../chunk-YXI4OQEV.js";
+} from "../chunk-O5ROO7QF.js";
 import {
   composeLankaRequestMiddleware
 } from "../chunk-YR4MZXMU.js";

package/dist/_internal/index.d.ts

@@ -1,8 +1,8 @@
-export { I as ILankaRuntime, T as TLankaRuntimeResolver, s as setLankaRuntimeResolver } from '../activeRuntime-DT4gB16d.js';
-import '../ILankaScenarioVM-DuCyPoyT.js';
-import '../LankaScenarioLocator-CLkq4MaJ.js';
-import '../ILankaScenarioMetadata-Bu-yggTZ.js';
-import '../ALankaGateway-ExlRGT3D.js';
+export { I as ILankaRuntime, T as TLankaRuntimeResolver, s as setLankaRuntimeResolver } from '../activeRuntime-B336NU5I.js';
+import '../ILankaScenarioVM-DUsI-fSc.js';
+import '../LankaScenarioLocator-D86TIwiu.js';
+import '../ILankaScenarioMetadata-GoWWNEQL.js';
+import '../ALankaGateway-CkW1LbKE.js';
 import '../lankaStandardValidator-CL-r-zEV.js';
 import '@standard-schema/spec';
 import '../LankaSharedStoreLocator-zS2kLu-S.js';

package/dist/{activeRuntime-DT4gB16d.d.ts → activeRuntime-B336NU5I.d.ts}

@@ -1,5 +1,5 @@
-import { L as LankaEventBusInstance, I as ILankaScenarioVM } from './ILankaScenarioVM-DuCyPoyT.js';
-import { c as LankaScenariosRegistry, b as LankaScenarioVMRegistry, L as LankaGatewayLocator, a as LankaScenarioLocator } from './LankaScenarioLocator-CLkq4MaJ.js';
+import { L as LankaEventBusInstance, I as ILankaScenarioVM } from './ILankaScenarioVM-DUsI-fSc.js';
+import { c as LankaScenariosRegistry, b as LankaScenarioVMRegistry, L as LankaGatewayLocator, a as LankaScenarioLocator } from './LankaScenarioLocator-D86TIwiu.js';
 import { b as ILankaRuntimeConfig } from './ILankaRuntimeConfig-Vl436GWK.js';
 import { I as ILankaInFlightCounter } from './lankaHttpInFlight-Bk1eIuSx.js';
 import { T as TLankaRequestMiddleware } from './lankaRequestMiddleware-DAC5kCb7.js';

package/dist/bootstrap/index.d.ts

@@ -1,150 +1,19 @@
-import { I as ILankaScope } from '../createLankaScope-BiFxNQgl.js';
-import { I as ILankaRuntime } from '../activeRuntime-DT4gB16d.js';
-import { a as ILankaHost, I as ILankaFlags } from '../ILankaRuntimeConfig-Vl436GWK.js';
-import { T as TLankaRequestMiddleware } from '../lankaRequestMiddleware-DAC5kCb7.js';
+import { c as ILankaPlugin, e as ILankaServiceConfig, I as ILankaBootstrapConfig, a as ILankaInstance } from '../createLanka-DI1CSy2Q.js';
+export { b as ILankaInstanceConfig, d as ILankaScenarioBootstrapConfig, f as createLanka } from '../createLanka-DI1CSy2Q.js';
+import { I as ILankaFlags, a as ILankaHost } from '../ILankaRuntimeConfig-Vl436GWK.js';
+export { I as ILankaScope } from '../createLankaScope-BiFxNQgl.js';
+import '../activeRuntime-B336NU5I.js';
+import '../ILankaScenarioVM-DUsI-fSc.js';
+import '../LankaScenarioLocator-D86TIwiu.js';
+import '../ILankaScenarioMetadata-GoWWNEQL.js';
+import '../ALankaGateway-CkW1LbKE.js';
+import '../lankaStandardValidator-CL-r-zEV.js';
+import '@standard-schema/spec';
 import '../LankaSharedStoreLocator-zS2kLu-S.js';
 import '../ALankaSharedStore-B7uepuuk.js';
 import 'zustand/vanilla';
-import '../ILankaScenarioVM-DuCyPoyT.js';
-import '../LankaScenarioLocator-CLkq4MaJ.js';
-import '../ILankaScenarioMetadata-Bu-yggTZ.js';
-import '../ALankaGateway-ExlRGT3D.js';
-import '../lankaStandardValidator-CL-r-zEV.js';
-import '@standard-schema/spec';
 import '../lankaHttpInFlight-Bk1eIuSx.js';
-
-/**
- * A plugin is an extension core knows by SHAPE rather than by name.
- *
- * ## Plugin versus module
- *
- * A module is called by the application (`app → module`) and core does not know
- * it exists. A plugin sits on the path core itself walks (`app → core → plugin`).
- * The test question: does core need a hook for this to work? No — then it is a
- * module, and making it a plugin costs more, because the hook has to be supported
- * forever.
- *
- * ## Why `install` receives the instance
- *
- * So a plugin has no private route to the framework. Everything it can do comes
- * from the instance it was given, which means two instances in one process (a
- * test beside the app) do not share its configuration.
- */
-interface ILankaPlugin {
-    /**
-     * The name the plugin is recognised by. Registering the same name twice is
-     * rejected: two copies of a retry policy would silently double the request
-     * count.
-     */
-    readonly name: string;
-    /**
-     * Installation. The returned function removes everything the plugin installed
-     * and is called when the plugin is removed and when the instance is disposed.
-     */
-    install: (lanka: ILankaInstance) => (() => void) | void;
-}
-
-/**
- * A framework instance: all framework state in one object.
- *
- * What instance-scoped state buys: two apps in one process (micro-frontends,
- * Storybook beside the app) no longer share a bus, locator caches and mock mode;
- * SSR does not reuse state between different users' requests; and test isolation
- * rests on construction rather than on a global `beforeEach` reaching into
- * internal registries.
- *
- * **Ambient facades** — `lankaEventBus.dispatch`, `lankaSingletons.foo`,
- * `getLankaFlags()`, `lankaHttpInFlight` — resolve THE ONE active instance
- * (`internal/activeRuntime.ts`). Isolation belongs to whoever holds an instance;
- * a facade cannot offer it.
- *
- * One thing stays at module level deliberately: `ALankaScenario` collects
- * constructed scenarios into a static pool. That is a REGISTRY OF DEFINITIONS,
- * not runtime state — the classes come from one `@lanka_di/Scenarios` barrel and
- * both instances must see the same list. Splitting it would be divergence.
- */
-interface ILankaInstance extends ILankaRuntime {
-    /**
-     * Adds a wrapper around every request. Returns a function that removes it.
-     *
-     * This is how `@lankajs/plugin-http` installs retry, the idempotency key, the
-     * CSRF header and auth refresh.
-     */
-    useRequestMiddleware(middleware: TLankaRequestMiddleware): () => void;
-    /** Default timeout for every request of this instance. */
-    setRequestTimeout(timeoutMs: number | undefined): void;
-    /** Resolves a service in the root scope — for the instance's whole lifetime. */
-    resolve<TInstance>(propertyName: string): TInstance;
-    /**
-     * Creates a scope: a lifetime shorter than the application's.
-     *
-     * An object created in a scope goes away with it.
-     */
-    createScope(): ILankaScope;
-    /**
-     * Registers a plugin. Returns a function that removes it.
-     *
-     * The fifth and last extension point. An extension point declared before
-     * anything plugs into it describes an imagined need while costing real
-     * support, so this one arrived with the FIRST plugin.
-     */
-    use(plugin: ILankaPlugin): () => void;
-    /** Runs services and the scenario layer. Idempotent. */
-    bootstrap(config?: ILankaBootstrapConfig): Promise<void>;
-    /** Has bootstrap already run? */
-    isBootstrapped(): boolean;
-    /** Makes this instance the one ambient facades resolve to. */
-    activate(): void;
-    /**
-     * Removes subscriptions, clears registries and, if this instance was active,
-     * clears the pointer. Returns the framework to its pre-bootstrap state.
-     */
-    dispose(): void;
-}
-interface ILankaInstanceConfig {
-    host: ILankaHost;
-    flags?: ILankaFlags;
-}
-interface ILankaServiceConfig {
-    name?: string;
-    init: () => void | Promise<void>;
-    sync?: boolean;
-    priority?: number;
-    /**
-     * A failure of this service does not abort bootstrap.
-     *
-     * Without the flag one failed service takes the WHOLE phase with it: the async
-     * phase because of `Promise.all`, the sync phase because later tasks never run.
-     * Wrapping the failure in a swallowing `try/catch` is worse still — the app
-     * starts with a partially executed plan and does not know it.
-     */
-    optional?: boolean;
-    /**
-     * How long to wait for the service. Overrunning counts as a failure.
-     *
-     * Without a deadline a service that never settles holds bootstrap forever and
-     * the app never paints its first screen. Failing is more honest than waiting:
-     * an optional service is skipped, a required one names itself.
-     */
-    timeoutMs?: number;
-}
-interface ILankaScenarioBootstrapConfig {
-    sync?: boolean;
-    priority?: number;
-}
-interface ILankaBootstrapConfig {
-    services?: ILankaServiceConfig[];
-    scenarios?: ILankaScenarioBootstrapConfig;
-}
-/**
- * Creates an instance and makes it active.
- *
- * Activating on creation is the deliberate default: there is almost always one
- * app and the facades must work immediately. A second instance takes the
- * pointer — the last one created serves the facades. Callers needing another
- * order call `activate()` explicitly.
- */
-declare function createLanka(config: ILankaInstanceConfig): ILankaInstance;
+import '../lankaRequestMiddleware-DAC5kCb7.js';
 
 /** What `startLanka` takes beyond the host, all of it optional. */
 interface ILankaStartOptions {
@@ -239,4 +108,4 @@ declare abstract class ALankaPlugin implements ILankaPlugin {
     install(lanka: ILankaInstance): () => void;
 }
 
-export { ALankaPlugin, type ILankaBootstrapConfig, type ILankaInstance, type ILankaInstanceConfig, type ILankaPlugin, type ILankaScenarioBootstrapConfig, ILankaScope, type ILankaServiceConfig, type ILankaStartOptions, type TLankaStartConfig, createLanka, resetActiveLanka, startLanka };
+export { ALankaPlugin, ILankaBootstrapConfig, ILankaInstance, ILankaPlugin, ILankaServiceConfig, type ILankaStartOptions, type TLankaStartConfig, resetActiveLanka, startLanka };

package/dist/bootstrap/index.js

@@ -3,10 +3,10 @@ import {
   createLanka,
   resetActiveLanka,
   startLanka
-} from "../chunk-63ST2UKP.js";
-import "../chunk-HZAIAGWS.js";
-import "../chunk-MYZQYOMD.js";
-import "../chunk-YXI4OQEV.js";
+} from "../chunk-LMKLLEHA.js";
+import "../chunk-UGXSGQPW.js";
+import "../chunk-5MAQVBI2.js";
+import "../chunk-O5ROO7QF.js";
 import "../chunk-XESL274R.js";
 import "../chunk-UJEC7H6K.js";
 import "../chunk-UE2C76OR.js";

package/dist/{chunk-MYZQYOMD.js → chunk-5MAQVBI2.js}

@@ -1,7 +1,7 @@
 import {
   ALankaScenario,
   LankaScenariosRegistry
-} from "./chunk-YXI4OQEV.js";
+} from "./chunk-O5ROO7QF.js";
 import {
   ALankaLocator,
   caseConvert,
@@ -24,6 +24,23 @@ var LankaGatewayLocator = class extends ALankaLocator {
 
 // src/locator/scenario/lanka-scenario-locator/LankaScenarioLocator.ts
 import * as ScenariosModule from "@lanka_di/Scenarios";
+var findScenarioClassByInstanceName = (scenarioName) => {
+  const pooled = ALankaScenario.getAutoRegisteredScenarios();
+  for (const value of Object.values(ScenariosModule)) {
+    if (typeof value !== "function" || !value.prototype) continue;
+    const Class = value;
+    const instance = pooled.find((scenario) => scenario.constructor === Class) ?? construct(Class);
+    if (instance?.name === scenarioName) return Class;
+  }
+  return void 0;
+};
+var construct = (Class) => {
+  try {
+    return new Class();
+  } catch {
+    return void 0;
+  }
+};
 var LankaScenarioLocator = class extends ALankaLocator {
   /**
    * The registry is read LAZILY rather than in a field initialiser.
@@ -46,19 +63,7 @@ var LankaScenarioLocator = class extends ALankaLocator {
             return ScenarioClass;
           }
         }
-        for (const value of Object.values(ScenariosModule)) {
-          if (typeof value === "function" && value.prototype) {
-            try {
-              const instance = new value();
-              if (instance.name === scenarioName) {
-                return value;
-              }
-            } catch {
-              continue;
-            }
-          }
-        }
-        return void 0;
+        return findScenarioClassByInstanceName(scenarioName);
       },
       getInstanceByName: (scenarioName) => {
         const registered = this.registry.getScenarioByName(scenarioName);
@@ -131,4 +136,4 @@ export {
   LankaScenarioLocator,
   createLankaScope
 };
-//# sourceMappingURL=chunk-MYZQYOMD.js.map
+//# sourceMappingURL=chunk-5MAQVBI2.js.map

package/dist/chunk-5MAQVBI2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/locator/gateway/lanka-gateway-locator/LankaGatewayLocator.ts","../src/locator/scenario/lanka-scenario-locator/LankaScenarioLocator.ts","../src/locator/_factories/create-lanka-scope/createLankaScope.ts"],"sourcesContent":["import * as GatewaysModule from \"@lanka_di/Gateways\";\nimport type { ALankaGateway } from \"../../../gateway/_abstractions/lanka-gateway/ALankaGateway\";\nimport { ALankaLocator } from \"../../_abstractions/lanka-locator/ALankaLocator\";\nimport { findExportedClass } from \"../../_internal/find-exported-class/findExportedClass\";\n\n/**\n * Resolves a gateway by property name (camelCase) or class name (PascalCase),\n * constructing it lazily and caching the instance.\n *\n * Adding a gateway takes one export line in `@lanka_di/Gateways`: types are\n * inferred and nothing is registered.\n */\nexport class LankaGatewayLocator extends ALankaLocator<ALankaGateway<unknown>> {\n\tconstructor() {\n\t\tsuper({\n\t\t\tfindClassByName: (gatewayName: string) =>\n\t\t\t\tfindExportedClass<ALankaGateway<unknown>>(GatewaysModule, gatewayName),\n\t\t\tnotFoundError: (gatewayName, propertyName) =>\n\t\t\t\t`Gateway \"${gatewayName}\" (accessed as \"${propertyName}\") not found. ` +\n\t\t\t\t`Make sure the gateway class extends ALankaGateway and is exported from lankaGateways.ts.`,\n\t\t});\n\t}\n}\n","import { LankaScenariosRegistry } from \"../../../scenario/_registries/lanka-scenarios-registry/LankaScenariosRegistry\";\nimport { ILankaScenario } from \"../../../scenario/_interfaces/ILankaScenario\";\nimport { ALankaScenario } from \"../../../scenario/_abstractions/lanka-scenario/ALankaScenario\";\nimport { ALankaLocator } from \"../../_abstractions/lanka-locator/ALankaLocator\";\n/**\n * Classes come from the consumer's barrel.\n *\n * Adding one is ONE export line: types are inferred, autocomplete works, and no\n * list has to be maintained.\n */\nimport * as ScenariosModule from \"@lanka_di/Scenarios\";\n\n/**\n * The barrel's class whose INSTANCE carries this name, when the export key does\n * not.\n *\n * A pooled instance answers for its class without constructing another: the\n * pool is never drained, so a lookup that constructed every class on every miss\n * grew it by the whole barrel each time a bad name was asked for. Only a class\n * the pool has never seen is constructed here — once, and it joins the pool.\n */\nconst findScenarioClassByInstanceName = (\n\tscenarioName: string,\n): (new () => ILankaScenario<unknown>) | undefined => {\n\tconst pooled = ALankaScenario.getAutoRegisteredScenarios();\n\n\tfor (const value of Object.values(ScenariosModule)) {\n\t\tif (typeof value !== \"function\" || !value.prototype) continue;\n\n\t\tconst Class = value as new () => ALankaScenario<unknown>;\n\t\tconst instance =\n\t\t\tpooled.find((scenario) => scenario.constructor === Class) ?? construct(Class);\n\t\tif (instance?.name === scenarioName) return Class;\n\t}\n\n\treturn undefined;\n};\n\n/** A new instance, or `undefined` for an export that is not constructible. */\nconst construct = (\n\tClass: new () => ALankaScenario<unknown>,\n): ALankaScenario<unknown> | undefined => {\n\ttry {\n\t\treturn new Class();\n\t} catch {\n\t\treturn undefined;\n\t}\n};\n\n/**\n * Resolves scenarios by property name (camelCase) or scenario name\n * (PascalCase).\n *\n * Looks in the registry, then in the self-registration pool, and failing both\n * constructs the scenario from the consumer's barrel on first use.\n */\nexport class LankaScenarioLocator extends ALankaLocator<ILankaScenario<unknown>> {\n\t/**\n\t * The registry is read LAZILY rather than in a field initialiser.\n\t *\n\t * The locator is constructed INSIDE `createLanka`, before the instance becomes\n\t * active. A field initialiser would ask for the active instance at that moment\n\t * and fail with \"no instance yet\" while the instance being created is on the\n\t * stack. Deferred reading resolves it: by the first scenario resolution an\n\t * active instance exists.\n\t */\n\tprivate get registry(): LankaScenariosRegistry {\n\t\treturn LankaScenariosRegistry.getInstance();\n\t}\n\n\tconstructor() {\n\t\tsuper({\n\t\t\tfindClassByName: (scenarioName: string) => {\n\t\t\t\t// By export key first: an instance name does not always survive minification.\n\t\t\t\tif (scenarioName in ScenariosModule) {\n\t\t\t\t\t// `as unknown` before the guards, exactly as in the singleton locator.\n\t\t\t\t\t// An EMPTY barrel — what the scaffolder writes, and what a new project\n\t\t\t\t\t// has until its first scenario — makes the module's keys `never`, so\n\t\t\t\t\t// an indexed access is `never` and reading `.prototype` off it does\n\t\t\t\t\t// not compile.\n\t\t\t\t\tconst ScenarioClass = ScenariosModule[\n\t\t\t\t\t\tscenarioName as keyof typeof ScenariosModule\n\t\t\t\t\t] as unknown;\n\t\t\t\t\tif (\n\t\t\t\t\t\ttypeof ScenarioClass === \"function\" &&\n\t\t\t\t\t\t\"prototype\" in ScenarioClass &&\n\t\t\t\t\t\tScenarioClass.prototype\n\t\t\t\t\t) {\n\t\t\t\t\t\treturn ScenarioClass as new () => ILankaScenario<unknown>;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\t// Fallback: look up by instance name.\n\t\t\t\treturn findScenarioClassByInstanceName(scenarioName);\n\t\t\t},\n\t\t\tgetInstanceByName: (scenarioName: string) => {\n\t\t\t\t// The registry first.\n\t\t\t\tconst registered = this.registry.getScenarioByName(scenarioName);\n\t\t\t\tif (registered) {\n\t\t\t\t\treturn registered;\n\t\t\t\t}\n\n\t\t\t\t// Then those that registered themselves.\n\t\t\t\tconst autoRegistered = ALankaScenario.getAutoRegisteredScenarios();\n\t\t\t\tconst scenario = autoRegistered.find((s) => s.name === scenarioName);\n\n\t\t\t\tif (scenario) {\n\t\t\t\t\tif (!this.registry.isRegistered(scenarioName)) {\n\t\t\t\t\t\tthis.registry.register(scenario);\n\t\t\t\t\t}\n\t\t\t\t\treturn scenario;\n\t\t\t\t}\n\n\t\t\t\t// Then finding the class by name and constructing it.\n\t\t\t\treturn undefined;\n\t\t\t},\n\t\t\tcreateInstance: (ScenarioClass) => {\n\t\t\t\tconst instance = new ScenarioClass();\n\t\t\t\tconst scenarioName = instance.name;\n\t\t\t\tif (!this.registry.isRegistered(scenarioName)) {\n\t\t\t\t\tthis.registry.register(instance);\n\t\t\t\t}\n\t\t\t\treturn instance;\n\t\t\t},\n\t\t\tnotFoundError: (scenarioName, propertyName) =>\n\t\t\t\t`Scenario \"${scenarioName}\" (accessed as \"${propertyName}\") not found. ` +\n\t\t\t\t`Make sure the scenario class extends ALankaScenario and has name=\"${scenarioName}\".`,\n\t\t});\n\t}\n}\n","import { caseConvert } from \"../../../_internal/case-convert/caseConvert\";\nimport { lankaLogger } from \"../../../logger/lanka-logger/LankaLogger\";\nimport type { LankaSingletonLocator } from \"../../singleton/lanka-singleton-locator/LankaSingletonLocator\";\n\n/**\n * A service lifetime other than \"as long as the application lives\".\n *\n * Everything resolved through `lankaSingletons.*` is a singleton for the life of\n * the app. Per-route, per-session and per-modal lifetimes otherwise rest on\n * discipline: every ViewModel calling `resetScenario()` and writing its own\n * `onReset`, in any of which it can be forgotten.\n *\n * A scope provides the same by construction: an object created in it goes away\n * with it, and nobody has to remember.\n *\n * ## What a scope does NOT do\n *\n * It does not shadow root objects and does not take them on close. It takes only\n * ITS OWN — the ones it created. A scope taking others' would be more dangerous\n * than no scopes at all: closing a screen would break the app.\n */\nexport interface ILankaScope {\n\t/** Resolves a service in this scope, creating it on first use. */\n\tresolve<TInstance>(propertyName: string): TInstance;\n\t/** Disposes everything this scope created and closes it. Idempotent. */\n\tdispose(): void;\n\t/** Whether the scope is closed. */\n\tisDisposed(): boolean;\n}\n\n/** A service may have a `dispose` — or may not. */\ninterface IMaybeDisposable {\n\tdispose?: () => void;\n}\n\nexport function createLankaScope(singletons: LankaSingletonLocator): ILankaScope {\n\tconst instances = new Map<string, unknown>();\n\tlet disposed = false;\n\n\treturn {\n\t\tresolve<TInstance>(propertyName: string): TInstance {\n\t\t\tif (disposed) {\n\t\t\t\t// Resolving from a closed scope is almost always a reference leaked from\n\t\t\t\t// an already-unmounted screen. Silently handing out an object would\n\t\t\t\t// extend the life of what was closed, invisibly.\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`The scope is closed: \"${propertyName}\" can no longer be resolved in it. ` +\n\t\t\t\t\t\t`This is usually a scope reference that outlived the screen that created it.`,\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst className = caseConvert(propertyName, \"pascalCase\");\n\t\t\tif (instances.has(className)) return instances.get(className) as TInstance;\n\n\t\t\t// The class comes from the root locator while the OBJECT is created here:\n\t\t\t// a scope is a different lifetime, not a different set of services.\n\t\t\tconst instance = singletons.createScopedInstance(className, propertyName);\n\t\t\tinstances.set(className, instance);\n\t\t\treturn instance as TInstance;\n\t\t},\n\n\t\tdispose(): void {\n\t\t\tif (disposed) return;\n\t\t\tdisposed = true;\n\n\t\t\tfor (const [name, instance] of instances) {\n\t\t\t\tconst disposable = instance as IMaybeDisposable;\n\t\t\t\tif (typeof disposable.dispose !== \"function\") continue;\n\t\t\t\ttry {\n\t\t\t\t\tdisposable.dispose();\n\t\t\t\t} catch (error) {\n\t\t\t\t\t// One failure must not leave the rest alive: that is exactly what a\n\t\t\t\t\t// scope exists to prevent.\n\t\t\t\t\tlankaLogger.printBootstrapLog(\n\t\t\t\t\t\t`Failed to dispose \"${name}\" in the scope`,\n\t\t\t\t\t\terror instanceof Error ? error.message : String(error),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tinstances.clear();\n\t\t},\n\n\t\tisDisposed: () => disposed,\n\t};\n}\n"],"mappings":"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","names":[]}