lanka 1.2.0 → 2.0.0

package/dist/_extend/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../../src/viewmodel/_internal/create-lanka-access-tracker/createLankaAccessTracker.ts","../../src/viewmodel/_factories/create-lanka-view-subscription/createLankaViewSubscription.ts","../../src/viewmodel/_internal/lanka-vm-recipes/lankaVMRecipes.ts","../../src/viewmodel/_factories/define-lanka-vm/defineLankaVM.ts","../../src/viewmodel/_factories/resolve-lanka-vm/resolveLankaVM.ts"],"sourcesContent":["import { lankaBlindSpotRegistry } from \"../lanka-blind-spot-registry/lankaBlindSpotRegistry\";\nimport type { ILankaReadableVM } from \"../../_interfaces/ILankaReadableVM\";\n\nexport interface ILankaAccessTracker<TState extends object> {\n\t/**\n\t * The state as a recording Proxy: every key read off it is remembered.\n\t *\n\t * Cached by the IDENTITY of the state it wrapped, so a second read while\n\t * nothing has changed hands back the same proxy — and therefore the same\n\t * recorded keys — rather than starting the recording over.\n\t *\n\t * A ViewModel that turned tracking off gets the state itself, and every\n\t * change then notifies. That is its decision, not a fallback: it turned\n\t * tracking off because it DERIVES what the screen shows, and a recording that\n\t * cannot see those reads would skip renders the screen needs.\n\t */\n\tread(): TState;\n\t/**\n\t * Whether a change touches anything this reader actually looked at.\n\t *\n\t * A reader that has looked at NOTHING yet is notified of everything: it has\n\t * not had the chance to record a key, and staying silent would mean its first\n\t * render never arrives.\n\t */\n\tshouldNotify(next: TState, prev: TState): boolean;\n\t/**\n\t * Says, in development, that a change was skipped — so the framework can warn\n\t * if the screen reads the changed key through a getter.\n\t *\n\t * Called by a binding exactly when `shouldNotify` answered `false`. In\n\t * production, and for a ViewModel with no trap, it does nothing.\n\t */\n\treportSkipped(next: TState, prev: TState): void;\n\t/**\n\t * The state itself, never the proxy.\n\t *\n\t * For a render that happens once and is thrown away — a server snapshot. There\n\t * is nothing to skip on a second render that will not happen, so recording\n\t * reads would be work whose result nothing consults.\n\t */\n\treadPlain(): TState;\n\t/** The keys read so far. Handed to the blind-spot diagnostic, which names them. */\n\treadonly trackedKeys: ReadonlySet<string>;\n}\n\nconst asRecord = (state: object): Record<string, unknown> => state as Record<string, unknown>;\n\n/**\n * A view of `state` that records the keys a READER depends on.\n *\n * Three things are excluded, and each was found by a reader going deaf rather\n * than by review. What they have in common is that none of them can ever make\n * `shouldNotify` answer true — so recording one cannot cause a render, and can\n * only switch off the rule that a reader who has read NOTHING hears about\n * everything.\n *\n * **Symbols.** `shouldNotify` compares keys by name, so a recorded symbol could\n * never be consulted, and every symbol a runtime asks for while inspecting an\n * object would join the set.\n *\n * **Keys the state does not have.** A framework probes an unfamiliar object\n * before it will hold it: Vue's `shallowRef` reads `__v_isRef`, a promise\n * resolution reads `then`, React reads `$$typeof`. Each went through this proxy\n * and was recorded, and `undefined === undefined` on every later comparison.\n * That is what made `defineLankaStore(vm)` deaf to its own first change — the\n * ONE key it had recorded was `__v_isRef`, and a template reading a real key\n * during its first render is what hid it everywhere else.\n *\n * **Functions.** An action is one object for the life of the store, so a\n * recorded action can never differ. `await store.load()` before any other read\n * is the shape that found it. A state key holding a function that genuinely\n * changes is the case this gives up, and it is the right one: a callback living\n * in state is state two readers cannot agree about, and every ViewModel here and\n * in the applications keeps its functions in actions.\n */\nconst recordReadsInto = <TState extends object>(state: TState, keys: Set<string>): TState =>\n\tnew Proxy(state, {\n\t\tget(target, prop, receiver) {\n\t\t\tconst value = Reflect.get(target, prop, receiver) as unknown;\n\n\t\t\tif (\n\t\t\t\ttypeof prop === \"string\" &&\n\t\t\t\ttypeof value !== \"function\" &&\n\t\t\t\tObject.hasOwn(target, prop)\n\t\t\t) {\n\t\t\t\tkeys.add(prop);\n\t\t\t}\n\n\t\t\treturn value;\n\t\t},\n\t});\n\n/**\n * The recording one reader currently holds, rebuilt when the state moves.\n *\n * Its own unit because it is the stateful half: a proxy, the keys it has\n * collected, and the identity of the state it was made for. What is left around\n * it is a comparison and a report, neither of which remembers anything.\n */\nconst trackedReadOf = <TState extends object>(read: () => TState) => {\n\tlet keys = new Set<string>();\n\tlet state: TState | null = null;\n\tlet proxy: TState | null = null;\n\n\treturn {\n\t\tkeys: (): ReadonlySet<string> => keys,\n\n\t\tcurrent: (): TState => {\n\t\t\tconst next = read();\n\t\t\tif (state === next && proxy) return proxy;\n\n\t\t\t// A FRESH set per state: the keys a reader looks at can change between\n\t\t\t// renders — a branch stops being taken, a list empties — and keeping the\n\t\t\t// old ones would re-render for a key nobody reads any more, forever.\n\t\t\tkeys = new Set<string>();\n\t\t\tstate = next;\n\t\t\tproxy = recordReadsInto(next, keys);\n\n\t\t\treturn proxy;\n\t\t},\n\t};\n};\n\n/** Whether the two states disagree on any of the keys a reader looked at. */\nconst anyKeyMoved = (keys: ReadonlySet<string>, next: object, prev: object): boolean => {\n\tconst nextRecord = asRecord(next);\n\tconst prevRecord = asRecord(prev);\n\n\tfor (const key of keys) {\n\t\tif (!Object.is(nextRecord[key], prevRecord[key])) return true;\n\t}\n\n\treturn false;\n};\n\n/**\n * Which state keys one reader looked at, and whether a change touched them.\n *\n * This is the whole of access tracking, and it is deliberately ignorant of how\n * anybody subscribes. A component re-renders only for keys it READ off the proxy\n * this returns; every framework asks that question the same way and answers it\n * with a different mechanism — `useSyncExternalStore`, a `shallowRef`, a signal —\n * so the question lives here and the mechanism lives in the binding.\n *\n * **This is the one piece of core a binding author needs.** It is published\n * through `lanka/extend` for exactly that: a binding is then a subscription, a\n * render trigger and these four calls, and the behaviour a consumer sees is the\n * framework's rather than each binding's re-reading of it. Canon:\n * `skills/parity/SKILL.md`.\n *\n * ## One tracker per reader, not per store\n *\n * The recorded keys are the property of whoever did the reading. Two components\n * over one ViewModel read different keys and must re-render for different\n * changes, so each holds its own tracker — which is also why this is a factory\n * with closed-over state rather than a set of pure functions over a shared map:\n * the lifetime of the recording is exactly the lifetime of the reader.\n *\n * ## The blind spot this cannot see, and reports instead\n *\n * Tracking sees reads made DIRECTLY off the proxy. A key reached only inside a\n * derived getter — an action calling `get()` — is invisible here, so a change to\n * it answers `shouldNotify` with `false` and the screen does not move. That is\n * what `reportSkipped` is for: core kept a trap for this ViewModel, and in\n * development it names the ViewModel and the key rather than leaving a frozen\n * screen with no error anywhere.\n */\nexport const createLankaAccessTracker = <TState extends object>(\n\tviewModel: ILankaReadableVM<TState>,\n): ILankaAccessTracker<TState> => {\n\tconst trap = lankaBlindSpotRegistry.of(viewModel);\n\tconst isTracked = viewModel.isAccessTracked;\n\tconst tracked = trackedReadOf(() => viewModel.getState());\n\n\treturn {\n\t\tget trackedKeys(): ReadonlySet<string> {\n\t\t\treturn isTracked ? tracked.keys() : new Set<string>();\n\t\t},\n\n\t\tread(): TState {\n\t\t\treturn isTracked ? tracked.current() : viewModel.getState();\n\t\t},\n\n\t\tshouldNotify(next: TState, prev: TState): boolean {\n\t\t\tif (!isTracked) return true;\n\n\t\t\tconst keys = tracked.keys();\n\n\t\t\treturn keys.size === 0 || anyKeyMoved(keys, next, prev);\n\t\t},\n\n\t\treportSkipped(next: TState, prev: TState): void {\n\t\t\ttrap?.report(new Set(tracked.keys()), asRecord(next), asRecord(prev));\n\t\t},\n\n\t\treadPlain(): TState {\n\t\t\treturn viewModel.getState();\n\t\t},\n\t};\n};\n","import { createLankaAccessTracker } from \"../../_internal/create-lanka-access-tracker/createLankaAccessTracker\";\nimport type { ILankaReadableVM } from \"../../_interfaces/ILankaReadableVM\";\n\n/** One reader's live view of a ViewModel. */\nexport interface ILankaViewSubscription<TState extends object> {\n\t/**\n\t * The current state, RECORDED.\n\t *\n\t * Every key read off it is remembered, which is what lets the next change be\n\t * skipped when it touched none of them. Call it again on every read: it asks\n\t * the ViewModel for its state each time, so it is never a snapshot.\n\t */\n\tread: () => TState;\n\t/** Releases the subscription. */\n\tstop: () => void;\n}\n\n/**\n * The TRACKED half of a view binding, minus the framework.\n *\n * The tracked half, and not the whole: all five shipped members also publish a\n * selector arm, which this deliberately does not serve — the reason is below,\n * under \"Why it does not take a selector\".\n *\n * ```ts\n * // a binding for a framework this repository has never heard of\n * export const useMyFrameworkVM = (viewModel) => {\n * \tconst view = createLankaViewSubscription(viewModel, () => invalidate());\n * \tonTeardown(view.stop);\n *\n * \treturn view.read;\n * };\n * ```\n *\n * Subscribe, ask whether the change touched anything this reader looked at,\n * report the skip so the blind-spot diagnostic can fire, and hand back a read\n * that records. Five packages wrote those four steps out by hand, identically —\n * and five copies of a decision diverge on the day one of them gains a line.\n *\n * ## What a caller still owns\n *\n * `onChange` and the teardown, which are the only framework-shaped things left.\n * That is the seam: a binding says how its framework is WOKEN and when a reader\n * has gone, and everything about which changes are worth waking for is here.\n *\n * ## Why it does not take a selector\n *\n * A selector BYPASSES tracking — the selector decides, and there is nothing to\n * record — so a subscription that took one would be two mechanisms behind one\n * name, each right half the time. A binding with a selector arm calls\n * `createLankaAccessTracker` directly, which is what the shelf's members do, and\n * the four steps are worth writing out where they genuinely differ.\n *\n * ## What it is not\n *\n * Not a store, not a cache, not a second place state lives. It holds a tracker\n * and an unsubscribe, and everything it answers comes from the ViewModel on the\n * call.\n */\nexport const createLankaViewSubscription = <TState extends object>(\n\tviewModel: ILankaReadableVM<TState>,\n\tonChange: () => void,\n): ILankaViewSubscription<TState> => {\n\tconst tracker = createLankaAccessTracker(viewModel);\n\n\tconst stop = viewModel.subscribe((next, prev) => {\n\t\tif (!tracker.shouldNotify(next, prev)) {\n\t\t\t// No update will follow. If the changed key is linked to this reader\n\t\t\t// through a getter it read, the screen froze — and in development core\n\t\t\t// names the ViewModel and the key rather than leaving it silent.\n\t\t\ttracker.reportSkipped(next, prev);\n\t\t\treturn;\n\t\t}\n\n\t\tonChange();\n\t});\n\n\treturn { read: () => tracker.read(), stop };\n};\n","import type { ILankaReadableVM } from \"../../_interfaces/ILankaReadableVM\";\n\n/** What a definition actually holds, kept where a consumer cannot reach it. */\nexport interface ILankaVMRecipe {\n\treadonly name: string;\n\treadonly build: () => ILankaReadableVM<object>;\n}\n\n/**\n * What `defineLankaVM` writes and `resolveLankaVM` reads.\n *\n * One object rather than two exported maps, because a file here holds one\n * runtime identity — and because the two halves are one mechanism: a recipe\n * nobody can resolve and an instance map keyed by nothing are each meaningless\n * alone.\n *\n * ## Weak at both ends, and both ends matter\n *\n * `recipes` is weak so a definition dropped by its module takes its recipe with\n * it. `instances` is weak in the SCOPE so a finished request's ViewModels go\n * when its scope does, and weak in the DEFINITION because the published type\n * invites `defineLankaVM({...})` written inline in a component or a loop — in a\n * browser the scope key is the framework instance and lives as long as the tab,\n * so a strong inner map would hold every inline definition and its ViewModel\n * for the life of the page.\n */\nexport const lankaVMRecipes = {\n\trecipes: new WeakMap<object, ILankaVMRecipe>(),\n\tinstances: new WeakMap<object, WeakMap<object, ILankaReadableVM<object>>>(),\n\n\t/** The instances belonging to one scope, created on first use. */\n\tforScope(scope: object): WeakMap<object, ILankaReadableVM<object>> {\n\t\tconst existing = this.instances.get(scope);\n\n\t\tif (existing) return existing;\n\n\t\tconst created = new WeakMap<object, ILankaReadableVM<object>>();\n\n\t\tthis.instances.set(scope, created);\n\n\t\treturn created;\n\t},\n};\n","import { lankaVMRecipes } from \"../../_internal/lanka-vm-recipes/lankaVMRecipes\";\nimport type { ILankaReadableVM } from \"../../_interfaces/ILankaReadableVM\";\n\n/**\n * The brand that makes a definition impossible to write by hand.\n *\n * Not exported, and that is the whole mechanism. A structural interface with\n * `name` and `build` on it would let a consumer author one, and the moment one\n * does, `ILankaVMDefinition` stops being a type the framework implements and\n * becomes a PORT — after which every member added to it is a compile error in\n * code nobody touched. Publishing an opaque type costs one line and keeps the\n * option space: a `dispose`, a `scope` field, even a call signature so that\n * `missionsVM()` could mean `resolveLankaVM(missionsVM)`, all stay additive.\n */\ndeclare const LANKA_VM_DEFINITION: unique symbol;\n\n/**\n * A ViewModel that has not been built yet.\n *\n * Hold it, pass it, type against it. There is nothing on it to call, because\n * calling it is `resolveLankaVM`'s job and a definition built by hand would be\n * an instance outside every scope's map.\n */\nexport interface ILankaVMDefinition<TViewModel extends ILankaReadableVM<object>> {\n\treadonly [LANKA_VM_DEFINITION]: TViewModel;\n}\n\n/**\n * Declares a ViewModel WITHOUT building it.\n *\n * ## When NOT to use this\n *\n * A browser-only application needs none of it. One module is one instance per\n * TAB there, so a module-level `createLankaVM` is still the shape, and wrapping\n * the nine factories in this one buys nothing but a lookup per read. Reach for\n * it when the same ViewModel has to exist on a SERVER, where one module is one\n * instance per PROCESS — shared by every user connected to it, so the first\n * request to write a draft into it serves that draft to the next stranger.\n *\n * ```ts\n * export const missionsVM = defineLankaVM({\n * \tname: \"MissionsVM\",\n * \tbuild: () => createLankaVM({ … }),\n * });\n * ```\n *\n * ## What it is not\n *\n * Not a tenth way to write a ViewModel. `build` returns whatever the nine\n * existing factories return and nothing here reaches inside it — a definition\n * adds a lifetime and takes nothing away.\n *\n * Not lazy in the sense `createLazyLankaVM` is. That one defers the STORE until\n * first read and still has one per module; this defers WHICH INSTANCE, and the\n * two compose.\n */\nexport const defineLankaVM = <TViewModel extends ILankaReadableVM<object>>(config: {\n\tname: string;\n\tbuild: () => TViewModel;\n}): ILankaVMDefinition<TViewModel> => {\n\tconst definition = Object.freeze({});\n\n\tlankaVMRecipes.recipes.set(definition, config);\n\n\treturn definition as ILankaVMDefinition<TViewModel>;\n};\n","import {\n\tgetActiveLankaScope,\n\thasLankaScopeResolver,\n\trequireActiveRuntime,\n} from \"../../../_internal/active-runtime/activeRuntime\";\nimport { lankaScenarioBootstrap } from \"../../../scenario/lanka-scenario-bootstrap/LankaScenarioBootstrap\";\nimport { lankaVMRecipes } from \"../../_internal/lanka-vm-recipes/lankaVMRecipes\";\nimport type { ILankaVMDefinition } from \"../define-lanka-vm/defineLankaVM\";\nimport type { ILankaReadableVM } from \"../../_interfaces/ILankaReadableVM\";\n\n/**\n * The instance of a definition that belongs to the CURRENT scope.\n *\n * Called twice in one scope it answers the same instance; called in two scopes\n * it answers two, and neither can see the other's state. In a browser there is\n * one scope for the life of the tab, so this is the module-level ViewModel a\n * consumer already knows — written once and correct on a server as well.\n *\n * ## It throws outside a scope, and that is the feature\n *\n * On a server the answer comes from the SCOPE seam rather than from the active\n * runtime, and the difference is not academic. `runInLankaServerScope` creates\n * its instance inside the scope and `createLanka` activates every instance it\n * builds, so during a request the process pointer and the scope's runtime are\n * the same object — keying on the runtime would make \"inside a request\" and\n * \"after one ended\" indistinguishable, and a call made after would be handed the\n * last stranger's ViewModel.\n *\n * So: a scope resolver installed and answering `null` means this ran outside\n * every request, and that fails loudly. No fallback, for the same reason\n * `requireActiveRuntime` has none — a wrong answer here is one user's data in\n * another user's page, and it would surface three layers from the call.\n *\n * ## Why the build is wrapped\n *\n * `ALankaVM.build()` declares a ViewModel that has scenario handlers into a\n * PROCESS-wide list, so that every instance ever created adopts it. That is\n * right for a module-level ViewModel and catastrophic for a scoped one: the list\n * would grow per request forever, and request N+1 would adopt request N's\n * ViewModel and run N's handlers against N's gateways. `buildScoped` is the seam\n * that keeps a scoped declaration out of it.\n */\nexport const resolveLankaVM = <TViewModel extends ILankaReadableVM<object>>(\n\tdefinition: ILankaVMDefinition<TViewModel>,\n): TViewModel => {\n\tconst recipe = lankaVMRecipes.recipes.get(definition);\n\n\tif (!recipe) {\n\t\tthrow new Error(\n\t\t\t\"resolveLankaVM was given something defineLankaVM did not make. A definition \" +\n\t\t\t\t\"is opaque on purpose: build it with defineLankaVM rather than by hand.\",\n\t\t);\n\t}\n\n\tconst runtime = requireActiveRuntime();\n\tconst scope = getActiveLankaScope();\n\n\tif (hasLankaScopeResolver() && !scope) {\n\t\tthrow new Error(\n\t\t\t`resolveLankaVM(\"${recipe.name}\") ran outside every scope. A scope resolver is ` +\n\t\t\t\t\"installed, which on a server means this code ran outside a request — and a \" +\n\t\t\t\t\"ViewModel resolved there would be the previous request's. Do this work inside \" +\n\t\t\t\t\"the scope, or start one.\",\n\t\t);\n\t}\n\n\t// The runtime when nothing knows about scopes: a browser tab is one scope for\n\t// its whole life, and the instance is what identifies it.\n\tconst instances = lankaVMRecipes.forScope(scope ?? runtime);\n\tconst held = instances.get(definition);\n\n\tif (held) return held as TViewModel;\n\n\tconst built = lankaScenarioBootstrap.buildScoped(() => recipe.build());\n\n\tinstances.set(definition, built);\n\n\treturn built as TViewModel;\n};\n"],"mappings":"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","names":[]}

package/dist/_internal/index.d.ts

@@ -1,19 +1,72 @@
-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';
+export { I as ILankaRuntime, T as TLankaRuntimeResolver, a as TLankaScopeResolver, g as getLankaProcessRuntime, s as setActiveLankaRuntime, b as setLankaRuntimeResolver, c as setLankaScopeResolver } from '../activeRuntime-BO-qY0yY.js';
+import { a as TLankaValidationResult } from '../lankaStandardValidator-BUFnysK0.js';
+import '../ILankaScenarioVM-DpKFL3iE.js';
+import '../LankaScenarioLocator-Dki2Es3O.js';
+import '../ILankaScenarioMetadata-Dj4GCqmX.js';
+import '../ALankaGateway-BrVPaZN5.js';
+import '../LankaSharedStoreLocator-jsz_gnUm.js';
 import '../ALankaSharedStore-B7uepuuk.js';
 import 'zustand/vanilla';
 import '../ILankaRuntimeConfig-Vl436GWK.js';
 import '../lankaHttpInFlight-Bk1eIuSx.js';
 import '../lankaRequestMiddleware-DAC5kCb7.js';
+import '@standard-schema/spec';
+import '../ILankaFieldError-D5931-vT.js';
 
 declare function generateUuid(): string;
 
+/**
+ * What to say when a validator is handed a schema from another library.
+ *
+ * ## Why this is not three sentences in three packages
+ *
+ * `@lankajs/yup`, `@lankajs/typebox` and `@lankajs/effect` each refuse a schema
+ * they do not own, and each has to answer the same follow-up: is this a schema at
+ * all, and if so whose? The answer is identical in all three because the
+ * SITUATION is identical — only the lead differs, because only the marker each
+ * looked for differs.
+ *
+ * Written three times it was three copies, and `check:composition` said so. Made
+ * deliberately different to satisfy the gate it would have been worse: three
+ * wordings of one fact, and a consumer who met two of them would be entitled to
+ * think they meant different things.
+ *
+ * ## Why `lanka/internal` and not the facade
+ *
+ * This tier exists for exactly this: "a sibling package needs these and must not
+ * reach into another package's `src/`". It promises nothing beyond a patch, which
+ * is the right promise for a sentence.
+ *
+ * A facade `isStandardSchema` was proposed first and refused, for a reason worth
+ * keeping: it would answer `true` for every yup schema, and `lankaStandardValidator`
+ * throws on every yup schema. A consumer writing `if (isStandardSchema(s))
+ * validate(s, …)` would have written the exact bug the family works to prevent,
+ * and the name would have told them it was safe.
+ */
+declare const lankaForeignSchemaMessage: (schema: unknown, { lead }: {
+    lead: string;
+}) => string;
+
+/**
+ * The strict path, built from the safe one.
+ *
+ * `ILankaValidator` publishes two methods over one answer: `validateSafe`
+ * returns an outcome, and `validate` is that outcome with the failure raised.
+ * Every implementation of the port therefore writes the same five lines, and
+ * three of them in this repository did — `check:composition` counted them.
+ *
+ * It is a GENERIC over the outcome rather than a helper returning `unknown`,
+ * which is the whole reason it can be shared: `@lankajs/typebox` returns
+ * `Static<TSchema>` and `@lankajs/effect` returns `Schema.Schema.Type<TAlias>`,
+ * and a helper that erased those would have cost each package its inference —
+ * a worse trade than the duplication it removed.
+ *
+ * `lanka/internal` because a sibling package needs it and must not reach into
+ * core's `src/`. It promises nothing beyond a patch, which is right for five
+ * lines that only restate what the port already says.
+ */
+declare const lankaValueOrThrow: <TOutput>(result: TLankaValidationResult<TOutput>, context: string) => TOutput;
+
 /**
  * Reads `key` from a record and returns it only if the value is a string.
  * Returns `undefined` for missing or non-string values.
@@ -40,4 +93,4 @@ declare const getStringField: (data: Record<string, unknown>, key: string) => st
  */
 declare const isRecord: (value: unknown) => value is Record<string, unknown>;
 
-export { generateUuid, getStringField, isRecord };
+export { generateUuid, getStringField, isRecord, lankaForeignSchemaMessage, lankaValueOrThrow };

package/dist/_internal/index.js

@@ -1,10 +1,17 @@
+import {
+  LankaValidationError
+} from "../chunk-CRIRTOLB.js";
 import {
   getStringField,
   isRecord
 } from "../chunk-J5LA3Q6D.js";
+import "../chunk-G32H73QY.js";
 import {
-  setLankaRuntimeResolver
-} from "../chunk-BGVDPDX4.js";
+  getLankaProcessRuntime,
+  setActiveLankaRuntime,
+  setLankaRuntimeResolver,
+  setLankaScopeResolver
+} from "../chunk-XGMXT4XZ.js";
 
 // src/_internal/generate-uuid/generateUuid.ts
 function generateUuid() {
@@ -25,10 +32,34 @@ function generateUuid() {
     return (c === "x" ? r : r & 3 | 8).toString(16);
   });
 }
+
+// src/_internal/lanka-foreign-schema-message/lankaForeignSchemaMessage.ts
+var lankaForeignSchemaMessage = (schema, { lead }) => {
+  const indexable = schema !== null && (typeof schema === "object" || typeof schema === "function");
+  if (indexable && "~standard" in schema) {
+    return `${lead} It does carry \`~standard\`, so it belongs to another library in \`modules/validators/\` \u2014 validate it with that package's validator, or with \`lankaStandardValidator\`.`;
+  }
+  return `${lead} Either it is not a schema at all, or it belongs to a library with its own package in \`modules/validators/\`.`;
+};
+
+// src/_internal/lanka-value-or-throw/lankaValueOrThrow.ts
+var lankaValueOrThrow = (result, context) => {
+  if (result.success) return result.data;
+  throw new LankaValidationError(
+    `Validation failed for ${context}`,
+    result.errors,
+    result.fields
+  );
+};
 export {
   generateUuid,
+  getLankaProcessRuntime,
   getStringField,
   isRecord,
-  setLankaRuntimeResolver
+  lankaForeignSchemaMessage,
+  lankaValueOrThrow,
+  setActiveLankaRuntime,
+  setLankaRuntimeResolver,
+  setLankaScopeResolver
 };
 //# sourceMappingURL=index.js.map

package/dist/_internal/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/_internal/generate-uuid/generateUuid.ts"],"sourcesContent":["export function generateUuid() {\n\tif (typeof crypto !== \"undefined\" && typeof crypto.randomUUID === \"function\") {\n\t\treturn crypto.randomUUID();\n\t}\n\n\tlet d = new Date().getTime();\n\n\tlet d2 =\n\t\t(typeof performance !== \"undefined\" && performance.now && performance.now() * 1000) || 0;\n\n\treturn \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, function (c) {\n\t\tlet r = Math.random() * 16;\n\n\t\tif (d > 0) {\n\t\t\tr = ((d + r) % 16) | 0;\n\t\t\td = Math.floor(d / 16);\n\t\t} else {\n\t\t\tr = ((d2 + r) % 16) | 0;\n\t\t\td2 = Math.floor(d2 / 16);\n\t\t}\n\n\t\treturn (c === \"x\" ? r : (r & 0x3) | 0x8).toString(16);\n\t});\n}\n"],"mappings":";;;;;;;;;AAAO,SAAS,eAAe;AAC9B,MAAI,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe,YAAY;AAC7E,WAAO,OAAO,WAAW;AAAA,EAC1B;AAEA,MAAI,KAAI,oBAAI,KAAK,GAAE,QAAQ;AAE3B,MAAI,KACF,OAAO,gBAAgB,eAAe,YAAY,OAAO,YAAY,IAAI,IAAI,OAAS;AAExF,SAAO,uCAAuC,QAAQ,SAAS,SAAU,GAAG;AAC3E,QAAI,IAAI,KAAK,OAAO,IAAI;AAExB,QAAI,IAAI,GAAG;AACV,WAAM,IAAI,KAAK,KAAM;AACrB,UAAI,KAAK,MAAM,IAAI,EAAE;AAAA,IACtB,OAAO;AACN,WAAM,KAAK,KAAK,KAAM;AACtB,WAAK,KAAK,MAAM,KAAK,EAAE;AAAA,IACxB;AAEA,YAAQ,MAAM,MAAM,IAAK,IAAI,IAAO,GAAK,SAAS,EAAE;AAAA,EACrD,CAAC;AACF;","names":[]}
+{"version":3,"sources":["../../src/_internal/generate-uuid/generateUuid.ts","../../src/_internal/lanka-foreign-schema-message/lankaForeignSchemaMessage.ts","../../src/_internal/lanka-value-or-throw/lankaValueOrThrow.ts"],"sourcesContent":["export function generateUuid() {\n\tif (typeof crypto !== \"undefined\" && typeof crypto.randomUUID === \"function\") {\n\t\treturn crypto.randomUUID();\n\t}\n\n\tlet d = new Date().getTime();\n\n\tlet d2 =\n\t\t(typeof performance !== \"undefined\" && performance.now && performance.now() * 1000) || 0;\n\n\treturn \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, function (c) {\n\t\tlet r = Math.random() * 16;\n\n\t\tif (d > 0) {\n\t\t\tr = ((d + r) % 16) | 0;\n\t\t\td = Math.floor(d / 16);\n\t\t} else {\n\t\t\tr = ((d2 + r) % 16) | 0;\n\t\t\td2 = Math.floor(d2 / 16);\n\t\t}\n\n\t\treturn (c === \"x\" ? r : (r & 0x3) | 0x8).toString(16);\n\t});\n}\n","/**\n * What to say when a validator is handed a schema from another library.\n *\n * ## Why this is not three sentences in three packages\n *\n * `@lankajs/yup`, `@lankajs/typebox` and `@lankajs/effect` each refuse a schema\n * they do not own, and each has to answer the same follow-up: is this a schema at\n * all, and if so whose? The answer is identical in all three because the\n * SITUATION is identical — only the lead differs, because only the marker each\n * looked for differs.\n *\n * Written three times it was three copies, and `check:composition` said so. Made\n * deliberately different to satisfy the gate it would have been worse: three\n * wordings of one fact, and a consumer who met two of them would be entitled to\n * think they meant different things.\n *\n * ## Why `lanka/internal` and not the facade\n *\n * This tier exists for exactly this: \"a sibling package needs these and must not\n * reach into another package's `src/`\". It promises nothing beyond a patch, which\n * is the right promise for a sentence.\n *\n * A facade `isStandardSchema` was proposed first and refused, for a reason worth\n * keeping: it would answer `true` for every yup schema, and `lankaStandardValidator`\n * throws on every yup schema. A consumer writing `if (isStandardSchema(s))\n * validate(s, …)` would have written the exact bug the family works to prevent,\n * and the name would have told them it was safe.\n */\nexport const lankaForeignSchemaMessage = (schema: unknown, { lead }: { lead: string }): string => {\n\t// Object OR function: arktype's schema is callable, with `~standard` on its\n\t// prototype, and a check reading only objects would tell an arktype user\n\t// their schema is not a schema.\n\tconst indexable =\n\t\tschema !== null && (typeof schema === \"object\" || typeof schema === \"function\");\n\n\tif (indexable && \"~standard\" in schema) {\n\t\treturn (\n\t\t\t`${lead} It does carry \\`~standard\\`, so it belongs to another library in ` +\n\t\t\t\"`modules/validators/` — validate it with that package's validator, or with \" +\n\t\t\t\"`lankaStandardValidator`.\"\n\t\t);\n\t}\n\n\treturn (\n\t\t`${lead} Either it is not a schema at all, or it belongs to a library with its ` +\n\t\t\"own package in `modules/validators/`.\"\n\t);\n};\n","import { LankaValidationError } from \"../../validation/lanka-validation-error/LankaValidationError\";\nimport type { TLankaValidationResult } from \"../../validation/_types/TLankaValidationResult\";\n\n/**\n * The strict path, built from the safe one.\n *\n * `ILankaValidator` publishes two methods over one answer: `validateSafe`\n * returns an outcome, and `validate` is that outcome with the failure raised.\n * Every implementation of the port therefore writes the same five lines, and\n * three of them in this repository did — `check:composition` counted them.\n *\n * It is a GENERIC over the outcome rather than a helper returning `unknown`,\n * which is the whole reason it can be shared: `@lankajs/typebox` returns\n * `Static<TSchema>` and `@lankajs/effect` returns `Schema.Schema.Type<TAlias>`,\n * and a helper that erased those would have cost each package its inference —\n * a worse trade than the duplication it removed.\n *\n * `lanka/internal` because a sibling package needs it and must not reach into\n * core's `src/`. It promises nothing beyond a patch, which is right for five\n * lines that only restate what the port already says.\n */\nexport const lankaValueOrThrow = <TOutput>(\n\tresult: TLankaValidationResult<TOutput>,\n\tcontext: string,\n): TOutput => {\n\tif (result.success) return result.data;\n\n\tthrow new LankaValidationError(\n\t\t`Validation failed for ${context}`,\n\t\tresult.errors,\n\t\tresult.fields,\n\t);\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAAO,SAAS,eAAe;AAC9B,MAAI,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe,YAAY;AAC7E,WAAO,OAAO,WAAW;AAAA,EAC1B;AAEA,MAAI,KAAI,oBAAI,KAAK,GAAE,QAAQ;AAE3B,MAAI,KACF,OAAO,gBAAgB,eAAe,YAAY,OAAO,YAAY,IAAI,IAAI,OAAS;AAExF,SAAO,uCAAuC,QAAQ,SAAS,SAAU,GAAG;AAC3E,QAAI,IAAI,KAAK,OAAO,IAAI;AAExB,QAAI,IAAI,GAAG;AACV,WAAM,IAAI,KAAK,KAAM;AACrB,UAAI,KAAK,MAAM,IAAI,EAAE;AAAA,IACtB,OAAO;AACN,WAAM,KAAK,KAAK,KAAM;AACtB,WAAK,KAAK,MAAM,KAAK,EAAE;AAAA,IACxB;AAEA,YAAQ,MAAM,MAAM,IAAK,IAAI,IAAO,GAAK,SAAS,EAAE;AAAA,EACrD,CAAC;AACF;;;ACKO,IAAM,4BAA4B,CAAC,QAAiB,EAAE,KAAK,MAAgC;AAIjG,QAAM,YACL,WAAW,SAAS,OAAO,WAAW,YAAY,OAAO,WAAW;AAErE,MAAI,aAAa,eAAe,QAAQ;AACvC,WACC,GAAG,IAAI;AAAA,EAIT;AAEA,SACC,GAAG,IAAI;AAGT;;;AC1BO,IAAM,oBAAoB,CAChC,QACA,YACa;AACb,MAAI,OAAO,QAAS,QAAO,OAAO;AAElC,QAAM,IAAI;AAAA,IACT,yBAAyB,OAAO;AAAA,IAChC,OAAO;AAAA,IACP,OAAO;AAAA,EACR;AACD;","names":[]}

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

@@ -1,9 +1,9 @@
-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 { L as LankaEventBusInstance, I as ILankaScenarioVM } from './ILankaScenarioVM-DpKFL3iE.js';
+import { L as LankaScenariosRegistry, a as LankaScenarioVMRegistry, b as LankaGatewayLocator, c as LankaScenarioLocator } from './LankaScenarioLocator-Dki2Es3O.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';
-import { b as LankaSingletonLocator, L as LankaSharedStoreLocator } from './LankaSharedStoreLocator-zS2kLu-S.js';
+import { L as LankaSingletonLocator, a as LankaSharedStoreLocator } from './LankaSharedStoreLocator-jsz_gnUm.js';
 
 /**
  * The pointer to the framework instance that ambient facades resolve to.
@@ -67,6 +67,26 @@ interface ILankaRuntime {
  * is the bug: the last request to start would answer for all of them.
  */
 type TLankaRuntimeResolver = () => ILankaRuntime | null;
+/**
+ * How "which SCOPE is this" is answered, which is a different question.
+ *
+ * `TLankaRuntimeResolver` answers which framework INSTANCE serves a call, and on
+ * a server that is one per request. This answers which unit of work the call
+ * belongs to, and the two are not interchangeable: `runInLankaServerScope`
+ * creates its instance INSIDE the scope, and `createLanka` activates every
+ * instance it builds — so the process pointer and the scope's runtime are the
+ * same object during a request, and nothing downstream can tell "inside a
+ * scope" from "after one ended".
+ *
+ * That distinction is what a per-scope lifetime needs. Without it a call made
+ * outside every request resolves against the LAST request's runtime and is
+ * handed the last stranger's state, which is the failure a scope exists to
+ * abolish.
+ *
+ * Core ships no resolver here either, and knows only that the question exists.
+ */
+type TLankaScopeResolver = () => object | null;
+declare function setActiveLankaRuntime(runtime: ILankaRuntime | null): void;
 /**
  * Replaces the strategy, or restores the default one with `null`.
  *
@@ -80,5 +100,32 @@ type TLankaRuntimeResolver = () => ILankaRuntime | null;
  * one answer.
  */
 declare function setLankaRuntimeResolver(resolver: TLankaRuntimeResolver | null): void;
+/**
+ * The PROCESS's own instance, read without asking the strategy.
+ *
+ * `getActiveRuntime` consults the installed resolver and is the answer for
+ * almost everything. This is the one question it cannot answer: what a call
+ * would have resolved to if nobody had installed a resolver at all.
+ *
+ * It exists for a resolver that wants to DEFER. A server's resolver answers from
+ * its request scope, and a process that also holds an ambient instance — a
+ * worker with a cache, a dev server between reloads, a suite between cases —
+ * has a right answer outside every scope that the resolver cannot see. Without
+ * this, the first request in such a process makes every later ambient call fail
+ * for the life of it.
+ *
+ * Not a fallback inside `getActiveRuntime`, deliberately: a resolver that wants
+ * to defer says so, and one that wants a call outside its scope to fail loudly
+ * goes on failing loudly. The choice belongs to whoever knows what a scope is.
+ */
+declare function getLankaProcessRuntime(): ILankaRuntime | null;
+/**
+ * Installs the strategy that says which unit of work a call belongs to.
+ *
+ * Installed by whoever knows what a scope IS — `@lankajs/host` wraps a request
+ * in `AsyncLocalStorage` and answers from its store. A browser installs none,
+ * and that is the right answer there: a tab is one scope for its whole life.
+ */
+declare function setLankaScopeResolver(resolver: TLankaScopeResolver | null): void;
 
-export { type ILankaRuntime as I, type TLankaRuntimeResolver as T, setLankaRuntimeResolver as s };
+export { type ILankaRuntime as I, type TLankaRuntimeResolver as T, type TLankaScopeResolver as a, setLankaRuntimeResolver as b, setLankaScopeResolver as c, getLankaProcessRuntime as g, setActiveLankaRuntime as s };

package/dist/bootstrap/index.d.ts

@@ -1,15 +1,16 @@
-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 { c as ILankaPlugin, e as ILankaServiceConfig, I as ILankaBootstrapConfig, a as ILankaInstance } from '../createLanka-x4oSMs7P.js';
+export { b as ILankaInstanceConfig, d as ILankaScenarioBootstrapConfig, f as createLanka } from '../createLanka-x4oSMs7P.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';
+export { I as ILankaScope } from '../createLankaScope-DomNbEvb.js';
+import '../activeRuntime-BO-qY0yY.js';
+import '../ILankaScenarioVM-DpKFL3iE.js';
+import '../LankaScenarioLocator-Dki2Es3O.js';
+import '../ILankaScenarioMetadata-Dj4GCqmX.js';
+import '../ALankaGateway-BrVPaZN5.js';
+import '../lankaStandardValidator-BUFnysK0.js';
 import '@standard-schema/spec';
-import '../LankaSharedStoreLocator-zS2kLu-S.js';
+import '../ILankaFieldError-D5931-vT.js';
+import '../LankaSharedStoreLocator-jsz_gnUm.js';
 import '../ALankaSharedStore-B7uepuuk.js';
 import 'zustand/vanilla';
 import '../lankaHttpInFlight-Bk1eIuSx.js';

package/dist/bootstrap/index.js

@@ -3,16 +3,15 @@ import {
   createLanka,
   resetActiveLanka,
   startLanka
-} from "../chunk-G3I7QIZR.js";
-import "../chunk-5MAQVBI2.js";
-import "../chunk-UGXSGQPW.js";
-import "../chunk-O5ROO7QF.js";
+} from "../chunk-SZVNPK24.js";
+import "../chunk-UMPSR4US.js";
+import "../chunk-EYDMBI5T.js";
 import "../chunk-XESL274R.js";
-import "../chunk-UJEC7H6K.js";
+import "../chunk-BHQ2SQ7P.js";
 import "../chunk-UE2C76OR.js";
-import "../chunk-C2HP7CRD.js";
-import "../chunk-D27MREPB.js";
-import "../chunk-BGVDPDX4.js";
+import "../chunk-FII3PW2G.js";
+import "../chunk-7DQUF2QR.js";
+import "../chunk-XGMXT4XZ.js";
 export {
   ALankaPlugin,
   createLanka,

package/dist/cache/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * A resource's address in a read cache: `["order", 7]`, never a joined string.
+ *
+ * Strings, numbers and booleans only — deliberately narrower than `unknown[]`.
+ * `@nanostores/query` accepts `string | number | true` as a key part and cannot
+ * carry an object at all, so a wider type here would be a promise the port
+ * cannot keep on every implementation. An application that wants to key by a
+ * filter object states its parts: `["orders", status, page]`.
+ *
+ * Two structurally equal keys are the same key. Segments are ordered, so
+ * `["order", 1]` and `[1, "order"]` are two resources.
+ */
+type TLankaCacheKey = readonly (string | number | boolean)[];
+
+/**
+ * What a ViewModel calls to avoid asking the server twice.
+ *
+ * A PORT and nothing else: core declares the shape and ships no cache, because
+ * a host framework already carries one and two caches disagree on the first
+ * mutation. Where there is no host — a plain Vite SPA — the slot is empty rather
+ * than taken, and an application fills it with `@lankajs/tanstack-query`,
+ * `@lankajs/nanostores-query`, or an implementation of its own.
+ *
+ * It sits UNDER the ViewModel: the ViewModel calls it, hands it the loader it
+ * got from a gateway, and keeps deciding what a failure means. The screen still
+ * reads one hook.
+ *
+ * ## The clauses an implementation must keep
+ *
+ * Behaviour, not signatures, is where two honest implementations diverge, so
+ * each clause below is a promise and most of them are assertions in
+ * `@lankajs/tool-testing`'s `lankaReadCacheConformance`. Run it; do not read a
+ * member's source.
+ *
+ * 1. `subscribe` does NOT deliver the current value. Use `peek` for that.
+ * 2. `subscribe` delivers only SETTLED data — never a pending or failed state.
+ * 3. The release it answers removes exactly its own listener; a second call
+ *    does nothing.
+ * 4. `peek` answers what is cached, stale or not. It never fetches and never
+ *    throws.
+ * 5. `read` answers from memory while fresh; two concurrent reads of one key
+ *    call `load` once.
+ * 6. `read` rejects with EXACTLY what `load` threw. Wrapping it breaks the
+ *    caller: a ViewModel branches on `LankaError.kind`, and a wrapper turns
+ *    every failure into the screen's.
+ * 7. A failed `read` is not remembered as data; the next one tries again.
+ * 8. `invalidate` resolves after the refetch settles when somebody is
+ *    subscribed, and marks stale without fetching when nobody is.
+ * 9. `write` notifies that key's subscribers before it returns.
+ * 10. `clear` empties everything and notifies nobody.
+ * 11. `cancel` is declared only if it really aborts.
+ * 12. Nothing refetches on its own: only `read` and `invalidate` fetch. A
+ *     background revalidation would change what a form was opened on.
+ *
+ * Four more cannot be checked from inside an implementation, and belong to
+ * whoever wires it: a subscriber must not write the key it observes; on a server
+ * the cache is per REQUEST, never a module-level singleton; one client instance
+ * per application; and the cache never fetches by itself — the loader comes from
+ * a gateway, through a ViewModel.
+ */
+interface ILankaReadCache {
+    /**
+     * The resource: from memory while fresh, otherwise through `load`.
+     *
+     * `load` receives a signal only from an implementation that can cancel —
+     * hence the optional parameter. One that cannot passes nothing, rather than a
+     * signal that can never fire, and `TLankaExecuteOptions.signal` already
+     * accepts `undefined`, so the gateway call is written the same way either way.
+     */
+    read<TData>(key: TLankaCacheKey, load: (signal?: AbortSignal) => Promise<TData>, options?: {
+        staleMs?: number;
+    }): Promise<TData>;
+    /** What the server just answered, in the DOMAIN shape. Subscribers hear before this returns. */
+    write<TData>(key: TLankaCacheKey, data: TData): void;
+    /** Marks the resource stale, and reloads it while somebody is listening. */
+    invalidate(key: TLankaCacheKey): Promise<void>;
+    /** Hears every later change to the resource — not the current value. Answers the release. */
+    subscribe(key: TLankaCacheKey, onData: (data: unknown) => void): () => void;
+    /** What is cached right now, stale or not. Never fetches. */
+    peek<TData>(key: TLankaCacheKey): TData | undefined;
+    /** Empties everything — the end of a session. Notifies nobody. */
+    clear(): void;
+    /**
+     * Stops a load in flight: the screen went away.
+     *
+     * OPTIONAL, because three of the four libraries measured for this port cannot
+     * do it — `@nanostores/query` structurally, since no signal reaches its
+     * fetcher. Absent means "the request finishes and its answer is discarded",
+     * which is wasteful and never wrong. Declaring it as a no-op is worse than
+     * omitting it: a caller would believe the request stopped.
+     *
+     * It belongs to the cache rather than to the ViewModel because the cache owns
+     * deduplication — a second reader joins the first's request in flight, and a
+     * cancellation by the first would tear it out from under the second.
+     */
+    cancel?(key: TLankaCacheKey): void;
+}
+
+export type { ILankaReadCache, TLankaCacheKey };

package/dist/cache/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{chunk-D27MREPB.js → chunk-7DQUF2QR.js}

@@ -1,6 +1,6 @@
 import {
   getActiveRuntime
-} from "./chunk-BGVDPDX4.js";
+} from "./chunk-XGMXT4XZ.js";
 
 // src/config/get-lanka-flags/getLankaFlags.ts
 function getLankaFlags() {
@@ -10,4 +10,4 @@ function getLankaFlags() {
 export {
   getLankaFlags
 };
-//# sourceMappingURL=chunk-D27MREPB.js.map
+//# sourceMappingURL=chunk-7DQUF2QR.js.map

package/dist/{chunk-UJEC7H6K.js → chunk-BHQ2SQ7P.js}

@@ -1,6 +1,6 @@
 import {
   requireActiveRuntime
-} from "./chunk-BGVDPDX4.js";
+} from "./chunk-XGMXT4XZ.js";
 
 // src/gateway/inflight/lankaHttpInFlight.ts
 function createInFlightCounter() {
@@ -36,4 +36,4 @@ export {
   createInFlightCounter,
   lankaHttpInFlight
 };
-//# sourceMappingURL=chunk-UJEC7H6K.js.map
+//# sourceMappingURL=chunk-BHQ2SQ7P.js.map

package/dist/chunk-CRIRTOLB.js

@@ -0,0 +1,27 @@
+import {
+  LankaError
+} from "./chunk-G32H73QY.js";
+
+// src/validation/lanka-validation-error/LankaValidationError.ts
+var LankaValidationError = class _LankaValidationError extends LankaError {
+  constructor(message, errors = [], fields = []) {
+    super({
+      kind: "schema",
+      message,
+      status: 422,
+      issues: errors.length > 0 ? errors : [message],
+      fields: fields.length > 0 ? fields : void 0
+    });
+    this.name = "LankaValidationError";
+    Object.setPrototypeOf(this, _LankaValidationError.prototype);
+  }
+  /** Always present here, unlike the base's optional list. */
+  get errors() {
+    return [...this.issues ?? []];
+  }
+};
+
+export {
+  LankaValidationError
+};
+//# sourceMappingURL=chunk-CRIRTOLB.js.map

package/dist/chunk-CRIRTOLB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/validation/lanka-validation-error/LankaValidationError.ts"],"sourcesContent":["import { LankaError } from \"../../errors/lanka-error/LankaError\";\nimport type { ILankaFieldError } from \"../../errors/_interfaces/ILankaFieldError\";\n\n/**\n * The validation port's failure: a body the schema refused.\n *\n * A `LankaError` of kind `schema`, so that `LankaError.is` and everything built\n * on it — the HTTP policy's error middleware, an application branching on\n * `kind` — see a refused body the way they see the request layer's own\n * \"200 that was not JSON\". It used to extend `Error` directly, and a consumer\n * that told a contract drift from a network failure by `kind` never saw it.\n *\n * `name` stays `LankaValidationError` and `status` stays 422: both are what a\n * consumer's existing `catch` reads, and the message list is `errors`. The same\n * issues arrive a second time as `fields`, with the path in segments, for the\n * consumer that has an input to show each one at.\n */\nexport class LankaValidationError extends LankaError {\n\tconstructor(message: string, errors: string[] = [], fields: readonly ILankaFieldError[] = []) {\n\t\tsuper({\n\t\t\tkind: \"schema\",\n\t\t\tmessage,\n\t\t\tstatus: 422,\n\t\t\tissues: errors.length > 0 ? errors : [message],\n\t\t\tfields: fields.length > 0 ? fields : undefined,\n\t\t});\n\t\tthis.name = \"LankaValidationError\";\n\t\tObject.setPrototypeOf(this, LankaValidationError.prototype);\n\t}\n\n\t/** Always present here, unlike the base's optional list. */\n\toverride get errors(): string[] {\n\t\treturn [...(this.issues ?? [])];\n\t}\n}\n"],"mappings":";;;;;AAiBO,IAAM,uBAAN,MAAM,8BAA6B,WAAW;AAAA,EACpD,YAAY,SAAiB,SAAmB,CAAC,GAAG,SAAsC,CAAC,GAAG;AAC7F,UAAM;AAAA,MACL,MAAM;AAAA,MACN;AAAA,MACA,QAAQ;AAAA,MACR,QAAQ,OAAO,SAAS,IAAI,SAAS,CAAC,OAAO;AAAA,MAC7C,QAAQ,OAAO,SAAS,IAAI,SAAS;AAAA,IACtC,CAAC;AACD,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,sBAAqB,SAAS;AAAA,EAC3D;AAAA;AAAA,EAGA,IAAa,SAAmB;AAC/B,WAAO,CAAC,GAAI,KAAK,UAAU,CAAC,CAAE;AAAA,EAC/B;AACD;","names":[]}