@warlock.js/core 5.1.0 → 5.2.0

package/CHANGELOG.md

@@ -6,6 +6,149 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 > ⚠ **Versioning: `@warlock.js/*` does not follow SemVer strictly — breaking changes may ship in a minor.** This is a deliberate decision, not an oversight: the framework is pre-adoption and the cost of a major per behaviour fix currently outweighs the benefit. **Pin an exact version or a tilde range (`~4.13.0`) if you need to opt into changes rather than receive them.** Every breaking change is marked **BREAKING** in its entry and summarised in an *Upgrading* section at the top of the release. **This policy will change once the framework has consumers beyond its author.**
 
+## 5.2.0
+
+### Added
+
+- **Connectors can contribute to `warlock build` through an optional static
+  `build` object.** Configured connectors may define ordered, awaited
+  `generate(context)` and `emit(context)` hooks without being booted or started.
+  `generate` can add generated entry imports and a narrow esbuild patch; `emit`
+  can produce non-esbuild artifacts after the server bundle. Unknown contribution
+  keys, duplicate/reserved connector names, generated unresolved imports, and hook
+  failures stop the build instead of producing a partial artifact.
+- **`warlock routes:diff`** — compares the live dev-server page-route surface against
+  the last successful `warlock build`'s snapshot (`page-routes.manifest.json` in the
+  build `outdir`). Boots diagnostically (same fail-loud boot as `warlock routes` /
+  `warlock doctor` — no connectors started), then reports `changed` / `removed` /
+  `added` page routes and exits non-zero on drift; exits `0` with "Page routes match"
+  when the two agree. Refuses to run (with an instruction to run `warlock build`
+  first) when no snapshot exists yet, or when an existing one is malformed. A route
+  whose `path`/`name` moved but whose `source` file didn't is reported as one
+  `changed` line instead of a `removed` + `added` pair.
+
+  **A clean baseline is reported immediately after a successful build.** The manifest
+  is written through the router's own path normalizer, so the catch-all page route is
+  recorded the way the router registers it (`/*`) rather than the way discovery derives
+  it (`*`) — an untouched checkout right after a green `warlock build` reports
+  `Page routes match`, where an earlier draft of this command reported drift on the
+  first run every time.
+
+  ⚠ **What a clean diff does not prove.** The manifest records what each page's route
+  name was *derived* as, not what it was *registered* as: `warlock build` boots no
+  connectors, so it cannot see the API routes a page name may collide with, and the
+  router appends a `.<method>` suffix to a name another method already claimed —
+  which the comparison accepts rather than reporting. `Page routes match` therefore
+  means the page surface has not moved since the build; it does **not** mean no page
+  route name collided at registration. The clean-run output says so in a trailing note,
+  and `warlock routes` shows the names as actually registered
+
+### Changed
+
+- **Incoming routes now match with or without one trailing slash in both
+  development and production.** `/about` and `/about/` dispatch to the same
+  route; `/` remains `/`, query strings are preserved, and case matching is
+  unchanged. Both router paths call the same request-path normalizer before
+  matching instead of relying on different Fastify/find-my-way defaults.
+
+- ⚠ **BREAKING — `http.trustProxy` is validated at boot, and a number is refused.** The
+  accepted shapes are exactly `boolean`, a non-empty string (a single IP/CIDR or several
+  comma-separated), a non-empty `string[]`, and an `(address, hop) => boolean` predicate;
+  a missing or nullish value means `false`. Anything else — a number, `""`, `[]`, an array
+  with a non-string entry, a plain object — now throws a `TypeError` while the HTTP server
+  is being constructed, before Fastify is instantiated, instead of being handed through
+  and silently coerced
+
+  ```
+  Invalid http.trustProxy configuration: expected a boolean, a non-empty IP/CIDR string,
+  a non-empty string array, or a predicate function; received number.
+  ```
+
+  ⚠ **The hop-count shape 4.16.0 introduced and recommended (`http.trustProxy: 2`) no
+  longer boots.** The Fastify version this release builds against evaluates a numeric
+  `trustProxy` as always-false at runtime, so a hop count never walked past your proxies —
+  it silently degraded to "trust nothing" while reading like a configured proxy chain, and
+  `detectIp()` returned the socket peer for every request. Refusing it loudly is the only
+  honest option: **migrate a hop count to a trusted-proxy list (`"10.0.0.0/8"`) or a
+  predicate before upgrading.** `true`, a list, and a predicate are unaffected
+
+- **`warlock build` writes into a temporary directory and promotes it only on success.**
+  The build no longer writes into `outdir` as it goes. It builds into a hidden sibling
+  directory (`.<outdir-basename>.build-<hex>`, same volume so the promotion is a rename),
+  writes a `.warlock-build.json` success marker (`{ status, builtAt }`) as its last step,
+  then swaps the directory into place. **A successful build therefore leaves no stale
+  files** — `outdir` is replaced wholesale rather than merged over, so an artifact a
+  previous build emitted and this one did not is gone. **A failed build leaves no usable
+  `dist`** — the temp directory is removed and the error rethrown without `outdir` ever
+  being touched, so a previous good build survives intact and no half-written one takes
+  its place
+
+- **`warlock start` refuses a `dist` that was not produced by a successful build**, and
+  names that as the reason. It checks for the `.warlock-build.json` marker in `outdir`
+  before spawning anything; missing, unreadable, malformed, or `status !== "success"` all
+  exit `1` on stderr with
+
+  ```
+  ✖ "dist" was not produced by a successful `warlock build` run (no build-success marker found). Run `warlock build` before `warlock start`.
+  ```
+
+  Never built, a build that failed before promotion, and a hand-assembled directory are
+  deliberately not distinguished — the fix for all three is the same command. Previously
+  `start` spawned whatever happened to be sitting in `outdir` and failed somewhere inside
+  the boot instead. ⚠ Ship `outdir` whole: an artifact pipeline that prunes dotfiles
+  strips the marker and makes the build unstartable on the target host
+
+- **`warlock start` surfaces the child process's real output on a failed boot.** The
+  production supervisor forwards every stdout/stderr chunk from the spawned bundle
+  verbatim and live, and its failure summary now reports whether a cause actually arrived:
+  `the cause is printed above, in the application's own output` when output was seen, and
+  `no output was captured from the application process — its cause did not reach this
+  terminal` when none was. It previously pointed at "above" unconditionally, which on a
+  silent child meant pointing at an empty terminal
+
+- **The HTTP connector now preflights its port before binding.** `warlock dev` and
+  `warlock start` both go through `HttpConnector.start()`, which now calls
+  `assertPortIsAvailable(port, host)` immediately before `listen()`. A collision now
+  surfaces as `EADDRINUSE: Port <port> is already in use on <host>. Stop the dev server
+  (or whatever else is listening on port <port>) and run again...` — the code and the
+  port named in the same sentence — instead of a bare `EADDRINUSE` thrown from inside
+  Fastify with no indication of which port it meant. `EACCES` on the port is treated
+  the same way, since "cannot bind" is one problem from the operator's side. The test
+  server (`startHttpTestServer`)
+  already preflighted its port before this release; this brings `dev`/`start` to the
+  same behavior.
+- **`startHttpTestServer()` now runs `Application.runStartupValidators()`** — the
+  same slot `warlock dev` and the generated production `app.ts` already ran it in —
+  after application modules load and before the late-phase connectors (http, socket)
+  bind. A validator registered via `Application.onValidateBoot(...)` that rejects now
+  aborts the test server's boot exactly as it aborts `dev`/`start`, instead of only
+  being enforced outside of tests.
+- **`warlock add web` scaffolds a real, validated API endpoint**, not just a static
+  page. It now also writes `src/app/contact/routes.ts` and
+  `src/app/contact/controllers/contact.controller.ts` (a `POST /api/contact` route
+  validated with `@warlock.js/seal`), and `src/web/home.page.tsx` ships an
+  interactive, localized (en/ar) contact form wired to that route via `@mongez/http`
+  + `@mongez/react-form` + `@mongez/react-localization`. The `web` feature now also
+  installs those three packages as dependencies.
+
+### Fixed
+
+- **Feature definitions no longer carry stale `~4.0.0` defaults for
+  `@warlock.js/*`.** They now use an explicit internal placeholder that
+  `warlock add` must resolve from the installed Core version before invoking a
+  package manager or writing `package.json`. A forgotten resolution therefore
+  fails loudly instead of silently selecting an old framework major.
+- **`startHttpTestServer()` fails loudly instead of silently skipping the preflight**
+  when `http.port` doesn't round-trip through `Number()` (e.g. `HTTP_PORT=03999`,
+  `+3999`, `1e3`, or a value with stray whitespace) — previously it returned early
+  and let the connector reach `listen({ port })` with the unvalidated value and no
+  published port for test workers to resolve.
+- **A race in the mail SES driver** where `getSesMailer()` could read the
+  eagerly-loaded `nodemailer` module before its load promise had settled. It now
+  awaits the in-flight load first (throwing the "nodemailer is not installed"
+  install-instructions error if the load ultimately failed), matching the guard the
+  SMTP path already had.
+
 ## 5.1.0
 
 > **If you use `@warlock.js/web`, upgrade.** React did not execute at all in published

package/esm/application/app.d.mts

@@ -3,7 +3,7 @@ import { DataSource } from "@warlock.js/cascade";
 import { FastifyInstance } from "fastify";
 import { Server } from "socket.io";
 
-//#region ../core/src/application/app.d.ts
+//#region core/src/application/app.d.ts
 type RuntimeApplication = {
   socket: Server;
   http: FastifyInstance;

package/esm/application/app.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.mts","names":[],"sources":["../../../../../../../core/src/application/app.ts"],"mappings":";;;;;;KAMK,kBAAA;EACH,MAAA,EAAQ,MAAA;EACR,IAAA,EAAM,eAAA;EACN,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,UAAA;AAAA;AAAA,cAGC,GAAA,EAAK,kBA4BjB"}
+{"version":3,"file":"app.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/application/app.ts"],"mappings":";;;;;;KAMK,kBAAA;EACH,MAAA,EAAQ,MAAA;EACR,IAAA,EAAM,eAAA;EACN,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,UAAA;AAAA;AAAA,cAGC,GAAA,EAAK,kBA4BjB"}

package/esm/application/app.mjs

@@ -1,6 +1,6 @@
 import { container } from "../container/index.mjs";
 
-//#region ../core/src/application/app.ts
+//#region core/src/application/app.ts
 const app = {
 	/**
 	* Socket Io Instance

package/esm/application/app.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"app.mjs","names":[],"sources":["../../../../../../../core/src/application/app.ts"],"sourcesContent":["import { type DataSource } from \"@warlock.js/cascade\";\nimport { type FastifyInstance } from \"fastify\";\nimport { type Server } from \"socket.io\";\nimport { type Router } from \"../router\";\nimport { container } from \"./../container\";\n\ntype RuntimeApplication = {\n  socket: Server;\n  http: FastifyInstance;\n  router: Router;\n  database: DataSource;\n};\n\nexport const app: RuntimeApplication = {\n  /**\n   * Socket Io Instance\n   * Available only if socket.io config file exists\n   */\n  get socket() {\n    return container.get(\"socket\");\n  },\n  /**\n   * HTTP Server Instance\n   * Available only if http config file exists\n   */\n  get http() {\n    return container.get(\"http.server\");\n  },\n  /**\n   * Router Instance\n   */\n  get router() {\n    return container.get(\"router\");\n  },\n  /**\n   * Database Instance\n   * Available only if database config file exists\n   */\n  get database() {\n    return container.get(\"database.source\");\n  },\n};\n"],"mappings":";;;AAaA,MAAa,MAA0B;;;;;CAKrC,IAAI,SAAS;EACX,OAAO,UAAU,IAAI,QAAQ;CAC/B;;;;;CAKA,IAAI,OAAO;EACT,OAAO,UAAU,IAAI,aAAa;CACpC;;;;CAIA,IAAI,SAAS;EACX,OAAO,UAAU,IAAI,QAAQ;CAC/B;;;;;CAKA,IAAI,WAAW;EACb,OAAO,UAAU,IAAI,iBAAiB;CACxC;AACF"}
+{"version":3,"file":"app.mjs","names":[],"sources":["C:/Work/Warlock.js/core/src/application/app.ts"],"sourcesContent":["import { type DataSource } from \"@warlock.js/cascade\";\nimport { type FastifyInstance } from \"fastify\";\nimport { type Server } from \"socket.io\";\nimport { type Router } from \"../router\";\nimport { container } from \"./../container\";\n\ntype RuntimeApplication = {\n  socket: Server;\n  http: FastifyInstance;\n  router: Router;\n  database: DataSource;\n};\n\nexport const app: RuntimeApplication = {\n  /**\n   * Socket Io Instance\n   * Available only if socket.io config file exists\n   */\n  get socket() {\n    return container.get(\"socket\");\n  },\n  /**\n   * HTTP Server Instance\n   * Available only if http config file exists\n   */\n  get http() {\n    return container.get(\"http.server\");\n  },\n  /**\n   * Router Instance\n   */\n  get router() {\n    return container.get(\"router\");\n  },\n  /**\n   * Database Instance\n   * Available only if database config file exists\n   */\n  get database() {\n    return container.get(\"database.source\");\n  },\n};\n"],"mappings":";;;AAaA,MAAa,MAA0B;;;;;CAKrC,IAAI,SAAS;EACX,OAAO,UAAU,IAAI,QAAQ;CAC/B;;;;;CAKA,IAAI,OAAO;EACT,OAAO,UAAU,IAAI,aAAa;CACpC;;;;CAIA,IAAI,SAAS;EACX,OAAO,UAAU,IAAI,QAAQ;CAC/B;;;;;CAKA,IAAI,WAAW;EACb,OAAO,UAAU,IAAI,iBAAiB;CACxC;AACF"}

package/esm/application/application-config-types.d.mts

@@ -1,4 +1,4 @@
-//#region ../core/src/application/application-config-types.d.ts
+//#region core/src/application/application-config-types.d.ts
 type AppConfigurations = {
   /**
    * App name

package/esm/application/application-config-types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"application-config-types.d.mts","names":[],"sources":["../../../../../../../core/src/application/application-config-types.ts"],"mappings":";KAAY,iBAAA;EAAA;;;EAIV,OAAA;EAAA;;;;;EAMA,UAAA;EAcW;;;;;EARX,OAAA;;;;EAIA,QAAA;;;;EAIA,WAAA;AAAA"}
+{"version":3,"file":"application-config-types.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/application/application-config-types.ts"],"mappings":";KAAY,iBAAA;EAAA;;;EAIV,OAAA;EAAA;;;;;EAMA,UAAA;EAcW;;;;;EARX,OAAA;;;;EAIA,QAAA;;;;EAIA,WAAA;AAAA"}

package/esm/application/application.d.mts

@@ -1,6 +1,6 @@
 import { Environment, RuntimeStrategy } from "../utils/environment.mjs";
 
-//#region ../core/src/application/application.d.ts
+//#region core/src/application/application.d.ts
 /**
  * Snapshot of the global facts known the moment the application finished
  * booting: every connector (early + late) is active and all app files

package/esm/application/application.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.mts","names":[],"sources":["../../../../../../../core/src/application/application.ts"],"mappings":";;;;;AAiBA;;;;KAAY,WAAA;EACV,WAAA,EAAa,WAAA;EACb,eAAA,EAAiB,eAAe;EAAf;;;AAKH;EAAd,cAAA;AAAA;;;;;;KAQU,YAAA,IAAgB,OAAA,EAAS,WAAA,YAAuB,OAAO;AAAA;AAYnE;;;;AAAgD;AAkBhD;;;;AA9BmE,KAYvD,aAAA,gBAA6B,OAAO;AAoBhD;;;;;AAAA,KAFY,gBAAA,gBAAgC,OAAO;AAAA,cAEtC,WAAA;EAwHyB;;;EAAA,gBApHb,SAAA,EAAS,IAAA;EA2OY;;;EAAA,OAtO9B,eAAA,EAAiB,eAAA;EAoVG;;;EAAA,eA/UnB,MAAA;EAViB;;;EAAA,eAejB,WAAA;EAAA;;;;EAAA,eAMA,aAAA;EA2BA;;;;;EAAA,eApBA,SAAA;EA8CG;;;;EAAA,eAxCH,cAAA;EAmEU;;;;;;EAAA,eA3DV,UAAA;EAiIM;;;;EAAA,eA3HN,YAAA;EA2L6B;;;EAAA,eAtL7B,iBAAA;EAqOU;;;EAAA,WAhOP,OAAA;EAiRA;;;EAAA,OA1QJ,kBAAA,CAAmB,QAAA,EAAU,eAAA;EAwRT;;;;;EAAA,WA/QhB,QAAA;EAkTA;;;;;EAAA,OAzSJ,aAAA,CAAc,IAAA;EAqUA;;;;;;;;;;;;;;EAAA,OAnTd,UAAA,CAAW,QAAA,EAAU,YAAA;;;;;SAerB,UAAA,IAAc,OAAA,CAAQ,WAAA;;;;;;;;;;;;;;;SAwBtB,UAAA,CAAW,OAAA,EAAS,WAAA;;;;;iBA+Bb,eAAA;;;;;;;;;;;;;;;;;;;;;;;;SAkCP,cAAA,CAAe,SAAA,EAAW,aAAA;;;;;;;;;;;;;;;;;;SA8BpB,oBAAA,IAAwB,OAAA;;;;;;aAgC1B,cAAA;;;;;;;;;;;;SAeJ,UAAA,CAAW,QAAA,EAAU,gBAAA;;;;;;;;;;SAmBf,gBAAA,IAAoB,OAAA;;;;;iBAmBnB,mBAAA;;;;aAWH,MAAA;;;;aAOA,WAAA,IAAe,WAAA;;;;SAOnB,cAAA,CAAe,GAAA,EAAK,WAAA;;;;aAOhB,YAAA;;;;aAOA,aAAA;;;;aAOA,MAAA;;;;aAOA,QAAA;;;;aAOA,OAAA;;;;aAOA,OAAA;;;;aAOA,WAAA;;;;aAOA,WAAA;;;;aAOA,UAAA;AAAA"}
+{"version":3,"file":"application.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/application/application.ts"],"mappings":";;;;;AAiBA;;;;KAAY,WAAA;EACV,WAAA,EAAa,WAAA;EACb,eAAA,EAAiB,eAAe;EAAf;;;AAKH;EAAd,cAAA;AAAA;;;;;;KAQU,YAAA,IAAgB,OAAA,EAAS,WAAA,YAAuB,OAAO;AAAA;AAYnE;;;;AAAgD;AAkBhD;;;;AA9BmE,KAYvD,aAAA,gBAA6B,OAAO;AAoBhD;;;;;AAAA,KAFY,gBAAA,gBAAgC,OAAO;AAAA,cAEtC,WAAA;EAwHyB;;;EAAA,gBApHb,SAAA,EAAS,IAAA;EA2OY;;;EAAA,OAtO9B,eAAA,EAAiB,eAAA;EAoVG;;;EAAA,eA/UnB,MAAA;EAViB;;;EAAA,eAejB,WAAA;EAAA;;;;EAAA,eAMA,aAAA;EA2BA;;;;;EAAA,eApBA,SAAA;EA8CG;;;;EAAA,eAxCH,cAAA;EAmEU;;;;;;EAAA,eA3DV,UAAA;EAiIM;;;;EAAA,eA3HN,YAAA;EA2L6B;;;EAAA,eAtL7B,iBAAA;EAqOU;;;EAAA,WAhOP,OAAA,CAAA;EAiRA;;;EAAA,OA1QJ,kBAAA,CAAmB,QAAA,EAAU,eAAA;EAwRT;;;;;EAAA,WA/QhB,QAAA,CAAA;EAkTA;;;;;EAAA,OAzSJ,aAAA,CAAc,IAAA;EAqUA;;;;;;;;;;;;;;EAAA,OAnTd,UAAA,CAAW,QAAA,EAAU,YAAA;;;;;SAerB,UAAA,CAAA,GAAc,OAAA,CAAQ,WAAA;;;;;;;;;;;;;;;SAwBtB,UAAA,CAAW,OAAA,EAAS,WAAA;;;;;iBA+Bb,eAAA;;;;;;;;;;;;;;;;;;;;;;;;SAkCP,cAAA,CAAe,SAAA,EAAW,aAAA;;;;;;;;;;;;;;;;;;SA8BpB,oBAAA,CAAA,GAAwB,OAAA;;;;;;aAgC1B,cAAA,CAAA;;;;;;;;;;;;SAeJ,UAAA,CAAW,QAAA,EAAU,gBAAA;;;;;;;;;;SAmBf,gBAAA,CAAA,GAAoB,OAAA;;;;;iBAmBnB,mBAAA;;;;aAWH,MAAA,CAAA;;;;aAOA,WAAA,CAAA,GAAe,WAAA;;;;SAOnB,cAAA,CAAe,GAAA,EAAK,WAAA;;;;aAOhB,YAAA,CAAA;;;;aAOA,aAAA,CAAA;;;;aAOA,MAAA,CAAA;;;;aAOA,QAAA,CAAA;;;;aAOA,OAAA,CAAA;;;;aAOA,OAAA,CAAA;;;;aAOA,WAAA,CAAA;;;;aAOA,WAAA,CAAA;;;;aAOA,UAAA,CAAA;AAAA"}

package/esm/application/application.mjs

@@ -4,7 +4,7 @@ import { BOOT_SIGNAL_VERSION, sendBootSignal } from "./boot-signal.mjs";
 import { getFrameworkVersion } from "../utils/framework-vesion.mjs";
 import { log } from "@warlock.js/logger";
 
-//#region ../core/src/application/application.ts
+//#region core/src/application/application.ts
 const ErrorWithCause = Error;
 var Application = class {
 	static {

package/esm/application/application.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"application.mjs","names":[],"sources":["../../../../../../../core/src/application/application.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { BOOT_SIGNAL_VERSION, sendBootSignal } from \"./boot-signal\";\nimport {\n  environment,\n  setEnvironment,\n  type Environment,\n  type RuntimeStrategy,\n} from \"../utils/environment\";\nimport { getFrameworkVersion } from \"../utils/framework-vesion\";\nimport { appPath, publicPath, rootPath, srcPath, storagePath, uploadsPath } from \"../utils/paths\";\n\n/**\n * Snapshot of the global facts known the moment the application finished\n * booting: every connector (early + late) is active and all app files\n * (locales, events, main, routes) are loaded. Passed to every\n * `Application.onceBooted` listener and resolved from `Application.whenBooted`.\n */\nexport type BootContext = {\n  environment: Environment;\n  runtimeStrategy: RuntimeStrategy;\n  /**\n   * Wall-clock milliseconds the boot took. The dev server measures it; the\n   * production entry omits it.\n   */\n  bootDurationMs?: number;\n};\n\n/**\n * A callback registered through `Application.onceBooted`. May be async — its\n * rejection is caught and logged so a single listener can never break boot or\n * the other listeners.\n */\nexport type BootListener = (context: BootContext) => void | Promise<void>;\n\n/**\n * A callback registered through `Application.onValidateBoot`. May be async —\n * unlike {@link BootListener}, its rejection is NOT caught: it aborts boot.\n *\n * Use this for configuration that makes the application WRONG rather than\n * degraded when missing (a signing secret, a required integration key) — the\n * kind of check that must fail closed. Use `onceBooted` for everything else;\n * that contract stays fire-and-forget on purpose (it is the right behaviour\n * for plugins reacting to boot, not for gating it).\n */\nexport type BootValidator = () => void | Promise<void>;\n\n/**\n * `new Error(message, { cause })` is ES2022, and this package still compiles\n * against the ES2020 lib, where `Error` is typed as taking a message only.\n * Node has supported the option since v16, so this is the type layer\n * catching up with the runtime, not a change in what the code does. Same\n * workaround as `image.ts` (see #16).\n */\ntype ErrorWithCauseConstructor = new (message: string, options: { cause: unknown }) => Error;\n\nconst ErrorWithCause = Error as ErrorWithCauseConstructor;\n\n/**\n * A callback registered through `Application.onShutdown`. Runs once, while the\n * connectors (db, cache, http) are still up, so it can release app-owned\n * resources cleanly. May be async — its rejection is caught and logged.\n */\nexport type ShutdownListener = () => void | Promise<void>;\n\nexport class Application {\n  /**\n   * Project start time regarding the process start time\n   */\n  public static readonly startedAt = new Date(Date.now() - process.uptime() * 1000);\n\n  /**\n   * Runtime strategy\n   */\n  public static runtimeStrategy: RuntimeStrategy;\n\n  /**\n   * Whether the application has finished booting. Flipped once by `markBooted`.\n   */\n  private static booted = false;\n\n  /**\n   * The boot context, set once booted so it can be replayed to late subscribers.\n   */\n  private static bootContext: BootContext | undefined;\n\n  /**\n   * Listeners queued before boot completed, drained in registration order by\n   * `markBooted`.\n   */\n  private static bootListeners: BootListener[] = [];\n\n  /**\n   * Whether `runStartupValidators` has already run. Flipped once, so a\n   * validator registered afterwards is refused instead of silently skipped\n   * or run too late to matter.\n   */\n  private static validated = false;\n\n  /**\n   * Startup validators queued before `runStartupValidators` ran, drained in\n   * registration order.\n   */\n  private static bootValidators: BootValidator[] = [];\n\n  /**\n   * The http port this process actually bound, once it has. Reported in the\n   * readiness signal so a supervisor knows where to send its health check\n   * instead of re-deriving it from config it may not be able to read.\n   * Undefined for an app with no http connector — a queue worker still boots.\n   */\n  private static servedPort: number | undefined;\n\n  /**\n   * Whether the application has begun (or finished) shutting down. Flipped once\n   * by `runShutdownHooks`.\n   */\n  private static shuttingDown = false;\n\n  /**\n   * Teardown callbacks, run once when shutdown begins.\n   */\n  private static shutdownListeners: ShutdownListener[] = [];\n\n  /**\n   * Get framework version\n   */\n  public static get version() {\n    return getFrameworkVersion();\n  }\n\n  /**\n   * Set the runtime strategy\n   */\n  public static setRuntimeStrategy(strategy: RuntimeStrategy) {\n    this.runtimeStrategy = strategy;\n  }\n\n  /**\n   * Whether the application has finished booting — every connector in both\n   * the early and late phases is active and all app files (locales, events,\n   * main, routes) have been loaded.\n   */\n  public static get isBooted(): boolean {\n    return this.booted;\n  }\n\n  /**\n   * Record the http port this process bound.\n   *\n   * @internal The http connector calls this after a successful `listen`.\n   */\n  public static setServedPort(port: number): void {\n    this.servedPort = port;\n  }\n\n  /**\n   * Run a callback once the application is fully booted.\n   *\n   * App files (`main` / `events` / `routes` / locales) are imported BEFORE the\n   * late-phase connectors (http, socket) start, so a listener registered at\n   * import time waits for the whole sequence to finish before it runs. If the\n   * application is already booted, the callback runs on the next microtask —\n   * so a late subscriber never silently misses the event.\n   *\n   * @example\n   * Application.onceBooted(({ environment }) => {\n   *   log.info(\"app\", \"booted\", `ready in ${environment}`);\n   * });\n   */\n  public static onceBooted(listener: BootListener): void {\n    if (this.booted && this.bootContext) {\n      const context = this.bootContext;\n      void this.runBootListener(listener, context);\n\n      return;\n    }\n\n    this.bootListeners.push(listener);\n  }\n\n  /**\n   * Promise form of {@link onceBooted} — resolves with the boot context once\n   * the application is booted, or immediately if it already is.\n   */\n  public static whenBooted(): Promise<BootContext> {\n    if (this.booted && this.bootContext) {\n      return Promise.resolve(this.bootContext);\n    }\n\n    return new Promise<BootContext>((resolve) => {\n      this.onceBooted((context) => resolve(context));\n    });\n  }\n\n  /**\n   * Flip the boot latch and drain every queued listener. The dev server and\n   * the production entry call this once, right after the late phase starts. It\n   * is idempotent — a second call is a no-op, so a double-invoke can never\n   * double-fire listeners.\n   *\n   * Also reports readiness to a supervising parent process — this is the one\n   * moment in the lifecycle where \"the application is serving\" is true, so it\n   * is the only honest source for `warlock start`'s success banner. Sent before\n   * the listeners run: a slow or hanging `onceBooted` listener must not delay\n   * the parent's view of a server that is already accepting requests.\n   *\n   * @internal Framework entry points call this; application code must not.\n   */\n  public static markBooted(context: BootContext): void {\n    if (this.booted) {\n      return;\n    }\n\n    this.booted = true;\n    this.bootContext = context;\n\n    sendBootSignal({\n      type: \"warlock:ready\",\n      version: BOOT_SIGNAL_VERSION,\n      pid: process.pid,\n      at: new Date().toISOString(),\n      environment: context.environment,\n      runtimeStrategy: context.runtimeStrategy,\n      bootDurationMs: context.bootDurationMs,\n      port: this.servedPort,\n    });\n\n    const listeners = this.bootListeners;\n    this.bootListeners = [];\n\n    for (const listener of listeners) {\n      void this.runBootListener(listener, context);\n    }\n  }\n\n  /**\n   * Invoke a single boot listener, isolating its failure so neither boot nor\n   * the remaining listeners are affected.\n   */\n  private static async runBootListener(\n    listener: BootListener,\n    context: BootContext,\n  ): Promise<void> {\n    try {\n      await listener(context);\n    } catch (error) {\n      log.error(\"application\", \"booted-listener\", error as Error);\n    }\n  }\n\n  /**\n   * Register a startup validator — distinct from {@link onceBooted}. A\n   * rejecting validator aborts boot instead of being caught and logged, so\n   * this is where configuration that must fail closed belongs (a signing\n   * secret, a required integration key), not `onceBooted`.\n   *\n   * Must be registered before the framework calls `runStartupValidators` —\n   * typically at module scope in `src/app/main.ts`, the same place a\n   * `BootListener` would be registered. Registering one after validation has\n   * already run throws: by then a rejection could no longer stop the app\n   * from serving, so running it late would silently defeat the guarantee\n   * this hook exists to give.\n   *\n   * @example\n   * Application.onValidateBoot(() => {\n   *   if (!env(\"JWT_SECRET\")) {\n   *     throw new Error(\n   *       \"JWT_SECRET is not set. Sessions cannot be signed without it. \" +\n   *         \"Generate one with `yarn jwt` and put it in .env.\",\n   *     );\n   *   }\n   * });\n   */\n  public static onValidateBoot(validator: BootValidator): void {\n    if (this.validated) {\n      throw new Error(\n        \"Application.onValidateBoot(): startup validators already ran — \" +\n          \"this validator was registered too late to block boot. Register it \" +\n          \"before the framework calls Application.runStartupValidators(), \" +\n          \"typically at module scope in `src/app/main.ts`.\",\n      );\n    }\n\n    this.bootValidators.push(validator);\n  }\n\n  /**\n   * Run every registered startup validator, in registration order, and abort\n   * on the first rejection. Idempotent — a second call is a no-op.\n   *\n   * Distinct from `runBootListener`: a listener's failure is isolated so it\n   * can never break boot; a validator's failure IS the boot failing — that is\n   * the entire point of registering one instead of the other. The thrown\n   * error names the failing validator and the original cause, so whatever\n   * catches it (the dev server's boot try/catch, the production entry's\n   * top-level await) reports which check failed and why, not a bare\n   * rejection.\n   *\n   * @internal Framework entry points call this once app code (main.ts et al)\n   * has loaded and BEFORE late-phase connectors (http, socket) start, so a\n   * failing validator runs before anything can bind a port or accept a\n   * request. Application code must not call this directly.\n   */\n  public static async runStartupValidators(): Promise<void> {\n    if (this.validated) {\n      return;\n    }\n\n    this.validated = true;\n\n    const validators = this.bootValidators;\n    this.bootValidators = [];\n\n    for (const validator of validators) {\n      try {\n        await validator();\n      } catch (error) {\n        const name = validator.name || \"<anonymous>\";\n        const cause = error instanceof Error ? error.message : String(error);\n\n        throw new ErrorWithCause(\n          `Startup validator \"${name}\" rejected boot: ${cause}. ` +\n            `Fix the condition it checks, or remove the validator if it no ` +\n            `longer applies — boot cannot proceed while it fails.`,\n          { cause: error },\n        );\n      }\n    }\n  }\n\n  /**\n   * Whether the application has begun shutting down. Once true, readiness\n   * checks report not-ready so a load balancer drains this instance before the\n   * HTTP server stops accepting requests.\n   */\n  public static get isShuttingDown(): boolean {\n    return this.shuttingDown;\n  }\n\n  /**\n   * Register a teardown callback, run once when the application shuts down —\n   * before the connectors (db, cache, http) are torn down, so it can still use\n   * them. The natural place to close an app-owned resource opened in\n   * `onceBooted`. If shutdown has already begun, the callback runs immediately.\n   *\n   * @example\n   * Application.onShutdown(async () => {\n   *   await myQueueConsumer.stop();\n   * });\n   */\n  public static onShutdown(listener: ShutdownListener): void {\n    if (this.shuttingDown) {\n      void this.runShutdownListener(listener);\n\n      return;\n    }\n\n    this.shutdownListeners.push(listener);\n  }\n\n  /**\n   * Flip the shutdown latch and run every teardown callback. The connectors\n   * manager calls this at the start of shutdown — before any connector is torn\n   * down. Idempotent and error-isolated: each callback is awaited, a thrown one\n   * is logged and does not stop the rest. Listeners run LIFO (reverse of\n   * registration), mirroring resource-unwind order.\n   *\n   * @internal Framework entry points call this; application code must not.\n   */\n  public static async runShutdownHooks(): Promise<void> {\n    if (this.shuttingDown) {\n      return;\n    }\n\n    this.shuttingDown = true;\n\n    const listeners = this.shutdownListeners.reverse();\n    this.shutdownListeners = [];\n\n    for (const listener of listeners) {\n      await this.runShutdownListener(listener);\n    }\n  }\n\n  /**\n   * Invoke a single teardown callback, isolating its failure so the rest still\n   * run and shutdown is never blocked by one bad hook.\n   */\n  private static async runShutdownListener(listener: ShutdownListener): Promise<void> {\n    try {\n      await listener();\n    } catch (error) {\n      log.error(\"application\", \"shutdown-listener\", error as Error);\n    }\n  }\n\n  /**\n   * Get project uptime in milliseconds\n   */\n  public static get uptime(): number {\n    return process.uptime() * 1000;\n  }\n\n  /**\n   * Get the current environment\n   */\n  public static get environment(): Environment {\n    return environment();\n  }\n\n  /**\n   * Set the current environment\n   */\n  public static setEnvironment(env: Environment) {\n    setEnvironment(env);\n  }\n\n  /**\n   * Check if the application is running in production environment\n   */\n  public static get isProduction(): boolean {\n    return this.environment === \"production\";\n  }\n\n  /**\n   * Check if the application is running in development environment\n   */\n  public static get isDevelopment(): boolean {\n    return this.environment === \"development\";\n  }\n\n  /**\n   * Check if the application is running in test environment\n   */\n  public static get isTest(): boolean {\n    return this.environment === \"test\";\n  }\n\n  /**\n   * Get the root path\n   */\n  public static get rootPath(): string {\n    return rootPath();\n  }\n\n  /**\n   * Get the src path\n   */\n  public static get srcPath(): string {\n    return srcPath();\n  }\n\n  /**\n   * Get the app path\n   */\n  public static get appPath(): string {\n    return appPath();\n  }\n\n  /**\n   * Get the storage path\n   */\n  public static get storagePath(): string {\n    return storagePath();\n  }\n\n  /**\n   * Get the uploads path\n   */\n  public static get uploadsPath(): string {\n    return uploadsPath();\n  }\n\n  /**\n   * Get the public path\n   */\n  public static get publicPath(): string {\n    return publicPath();\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"application.mjs","names":[],"sources":["C:/Work/Warlock.js/core/src/application/application.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { BOOT_SIGNAL_VERSION, sendBootSignal } from \"./boot-signal\";\nimport {\n  environment,\n  setEnvironment,\n  type Environment,\n  type RuntimeStrategy,\n} from \"../utils/environment\";\nimport { getFrameworkVersion } from \"../utils/framework-vesion\";\nimport { appPath, publicPath, rootPath, srcPath, storagePath, uploadsPath } from \"../utils/paths\";\n\n/**\n * Snapshot of the global facts known the moment the application finished\n * booting: every connector (early + late) is active and all app files\n * (locales, events, main, routes) are loaded. Passed to every\n * `Application.onceBooted` listener and resolved from `Application.whenBooted`.\n */\nexport type BootContext = {\n  environment: Environment;\n  runtimeStrategy: RuntimeStrategy;\n  /**\n   * Wall-clock milliseconds the boot took. The dev server measures it; the\n   * production entry omits it.\n   */\n  bootDurationMs?: number;\n};\n\n/**\n * A callback registered through `Application.onceBooted`. May be async — its\n * rejection is caught and logged so a single listener can never break boot or\n * the other listeners.\n */\nexport type BootListener = (context: BootContext) => void | Promise<void>;\n\n/**\n * A callback registered through `Application.onValidateBoot`. May be async —\n * unlike {@link BootListener}, its rejection is NOT caught: it aborts boot.\n *\n * Use this for configuration that makes the application WRONG rather than\n * degraded when missing (a signing secret, a required integration key) — the\n * kind of check that must fail closed. Use `onceBooted` for everything else;\n * that contract stays fire-and-forget on purpose (it is the right behaviour\n * for plugins reacting to boot, not for gating it).\n */\nexport type BootValidator = () => void | Promise<void>;\n\n/**\n * `new Error(message, { cause })` is ES2022, and this package still compiles\n * against the ES2020 lib, where `Error` is typed as taking a message only.\n * Node has supported the option since v16, so this is the type layer\n * catching up with the runtime, not a change in what the code does. Same\n * workaround as `image.ts` (see #16).\n */\ntype ErrorWithCauseConstructor = new (message: string, options: { cause: unknown }) => Error;\n\nconst ErrorWithCause = Error as ErrorWithCauseConstructor;\n\n/**\n * A callback registered through `Application.onShutdown`. Runs once, while the\n * connectors (db, cache, http) are still up, so it can release app-owned\n * resources cleanly. May be async — its rejection is caught and logged.\n */\nexport type ShutdownListener = () => void | Promise<void>;\n\nexport class Application {\n  /**\n   * Project start time regarding the process start time\n   */\n  public static readonly startedAt = new Date(Date.now() - process.uptime() * 1000);\n\n  /**\n   * Runtime strategy\n   */\n  public static runtimeStrategy: RuntimeStrategy;\n\n  /**\n   * Whether the application has finished booting. Flipped once by `markBooted`.\n   */\n  private static booted = false;\n\n  /**\n   * The boot context, set once booted so it can be replayed to late subscribers.\n   */\n  private static bootContext: BootContext | undefined;\n\n  /**\n   * Listeners queued before boot completed, drained in registration order by\n   * `markBooted`.\n   */\n  private static bootListeners: BootListener[] = [];\n\n  /**\n   * Whether `runStartupValidators` has already run. Flipped once, so a\n   * validator registered afterwards is refused instead of silently skipped\n   * or run too late to matter.\n   */\n  private static validated = false;\n\n  /**\n   * Startup validators queued before `runStartupValidators` ran, drained in\n   * registration order.\n   */\n  private static bootValidators: BootValidator[] = [];\n\n  /**\n   * The http port this process actually bound, once it has. Reported in the\n   * readiness signal so a supervisor knows where to send its health check\n   * instead of re-deriving it from config it may not be able to read.\n   * Undefined for an app with no http connector — a queue worker still boots.\n   */\n  private static servedPort: number | undefined;\n\n  /**\n   * Whether the application has begun (or finished) shutting down. Flipped once\n   * by `runShutdownHooks`.\n   */\n  private static shuttingDown = false;\n\n  /**\n   * Teardown callbacks, run once when shutdown begins.\n   */\n  private static shutdownListeners: ShutdownListener[] = [];\n\n  /**\n   * Get framework version\n   */\n  public static get version() {\n    return getFrameworkVersion();\n  }\n\n  /**\n   * Set the runtime strategy\n   */\n  public static setRuntimeStrategy(strategy: RuntimeStrategy) {\n    this.runtimeStrategy = strategy;\n  }\n\n  /**\n   * Whether the application has finished booting — every connector in both\n   * the early and late phases is active and all app files (locales, events,\n   * main, routes) have been loaded.\n   */\n  public static get isBooted(): boolean {\n    return this.booted;\n  }\n\n  /**\n   * Record the http port this process bound.\n   *\n   * @internal The http connector calls this after a successful `listen`.\n   */\n  public static setServedPort(port: number): void {\n    this.servedPort = port;\n  }\n\n  /**\n   * Run a callback once the application is fully booted.\n   *\n   * App files (`main` / `events` / `routes` / locales) are imported BEFORE the\n   * late-phase connectors (http, socket) start, so a listener registered at\n   * import time waits for the whole sequence to finish before it runs. If the\n   * application is already booted, the callback runs on the next microtask —\n   * so a late subscriber never silently misses the event.\n   *\n   * @example\n   * Application.onceBooted(({ environment }) => {\n   *   log.info(\"app\", \"booted\", `ready in ${environment}`);\n   * });\n   */\n  public static onceBooted(listener: BootListener): void {\n    if (this.booted && this.bootContext) {\n      const context = this.bootContext;\n      void this.runBootListener(listener, context);\n\n      return;\n    }\n\n    this.bootListeners.push(listener);\n  }\n\n  /**\n   * Promise form of {@link onceBooted} — resolves with the boot context once\n   * the application is booted, or immediately if it already is.\n   */\n  public static whenBooted(): Promise<BootContext> {\n    if (this.booted && this.bootContext) {\n      return Promise.resolve(this.bootContext);\n    }\n\n    return new Promise<BootContext>((resolve) => {\n      this.onceBooted((context) => resolve(context));\n    });\n  }\n\n  /**\n   * Flip the boot latch and drain every queued listener. The dev server and\n   * the production entry call this once, right after the late phase starts. It\n   * is idempotent — a second call is a no-op, so a double-invoke can never\n   * double-fire listeners.\n   *\n   * Also reports readiness to a supervising parent process — this is the one\n   * moment in the lifecycle where \"the application is serving\" is true, so it\n   * is the only honest source for `warlock start`'s success banner. Sent before\n   * the listeners run: a slow or hanging `onceBooted` listener must not delay\n   * the parent's view of a server that is already accepting requests.\n   *\n   * @internal Framework entry points call this; application code must not.\n   */\n  public static markBooted(context: BootContext): void {\n    if (this.booted) {\n      return;\n    }\n\n    this.booted = true;\n    this.bootContext = context;\n\n    sendBootSignal({\n      type: \"warlock:ready\",\n      version: BOOT_SIGNAL_VERSION,\n      pid: process.pid,\n      at: new Date().toISOString(),\n      environment: context.environment,\n      runtimeStrategy: context.runtimeStrategy,\n      bootDurationMs: context.bootDurationMs,\n      port: this.servedPort,\n    });\n\n    const listeners = this.bootListeners;\n    this.bootListeners = [];\n\n    for (const listener of listeners) {\n      void this.runBootListener(listener, context);\n    }\n  }\n\n  /**\n   * Invoke a single boot listener, isolating its failure so neither boot nor\n   * the remaining listeners are affected.\n   */\n  private static async runBootListener(\n    listener: BootListener,\n    context: BootContext,\n  ): Promise<void> {\n    try {\n      await listener(context);\n    } catch (error) {\n      log.error(\"application\", \"booted-listener\", error as Error);\n    }\n  }\n\n  /**\n   * Register a startup validator — distinct from {@link onceBooted}. A\n   * rejecting validator aborts boot instead of being caught and logged, so\n   * this is where configuration that must fail closed belongs (a signing\n   * secret, a required integration key), not `onceBooted`.\n   *\n   * Must be registered before the framework calls `runStartupValidators` —\n   * typically at module scope in `src/app/main.ts`, the same place a\n   * `BootListener` would be registered. Registering one after validation has\n   * already run throws: by then a rejection could no longer stop the app\n   * from serving, so running it late would silently defeat the guarantee\n   * this hook exists to give.\n   *\n   * @example\n   * Application.onValidateBoot(() => {\n   *   if (!env(\"JWT_SECRET\")) {\n   *     throw new Error(\n   *       \"JWT_SECRET is not set. Sessions cannot be signed without it. \" +\n   *         \"Generate one with `yarn jwt` and put it in .env.\",\n   *     );\n   *   }\n   * });\n   */\n  public static onValidateBoot(validator: BootValidator): void {\n    if (this.validated) {\n      throw new Error(\n        \"Application.onValidateBoot(): startup validators already ran — \" +\n          \"this validator was registered too late to block boot. Register it \" +\n          \"before the framework calls Application.runStartupValidators(), \" +\n          \"typically at module scope in `src/app/main.ts`.\",\n      );\n    }\n\n    this.bootValidators.push(validator);\n  }\n\n  /**\n   * Run every registered startup validator, in registration order, and abort\n   * on the first rejection. Idempotent — a second call is a no-op.\n   *\n   * Distinct from `runBootListener`: a listener's failure is isolated so it\n   * can never break boot; a validator's failure IS the boot failing — that is\n   * the entire point of registering one instead of the other. The thrown\n   * error names the failing validator and the original cause, so whatever\n   * catches it (the dev server's boot try/catch, the production entry's\n   * top-level await) reports which check failed and why, not a bare\n   * rejection.\n   *\n   * @internal Framework entry points call this once app code (main.ts et al)\n   * has loaded and BEFORE late-phase connectors (http, socket) start, so a\n   * failing validator runs before anything can bind a port or accept a\n   * request. Application code must not call this directly.\n   */\n  public static async runStartupValidators(): Promise<void> {\n    if (this.validated) {\n      return;\n    }\n\n    this.validated = true;\n\n    const validators = this.bootValidators;\n    this.bootValidators = [];\n\n    for (const validator of validators) {\n      try {\n        await validator();\n      } catch (error) {\n        const name = validator.name || \"<anonymous>\";\n        const cause = error instanceof Error ? error.message : String(error);\n\n        throw new ErrorWithCause(\n          `Startup validator \"${name}\" rejected boot: ${cause}. ` +\n            `Fix the condition it checks, or remove the validator if it no ` +\n            `longer applies — boot cannot proceed while it fails.`,\n          { cause: error },\n        );\n      }\n    }\n  }\n\n  /**\n   * Whether the application has begun shutting down. Once true, readiness\n   * checks report not-ready so a load balancer drains this instance before the\n   * HTTP server stops accepting requests.\n   */\n  public static get isShuttingDown(): boolean {\n    return this.shuttingDown;\n  }\n\n  /**\n   * Register a teardown callback, run once when the application shuts down —\n   * before the connectors (db, cache, http) are torn down, so it can still use\n   * them. The natural place to close an app-owned resource opened in\n   * `onceBooted`. If shutdown has already begun, the callback runs immediately.\n   *\n   * @example\n   * Application.onShutdown(async () => {\n   *   await myQueueConsumer.stop();\n   * });\n   */\n  public static onShutdown(listener: ShutdownListener): void {\n    if (this.shuttingDown) {\n      void this.runShutdownListener(listener);\n\n      return;\n    }\n\n    this.shutdownListeners.push(listener);\n  }\n\n  /**\n   * Flip the shutdown latch and run every teardown callback. The connectors\n   * manager calls this at the start of shutdown — before any connector is torn\n   * down. Idempotent and error-isolated: each callback is awaited, a thrown one\n   * is logged and does not stop the rest. Listeners run LIFO (reverse of\n   * registration), mirroring resource-unwind order.\n   *\n   * @internal Framework entry points call this; application code must not.\n   */\n  public static async runShutdownHooks(): Promise<void> {\n    if (this.shuttingDown) {\n      return;\n    }\n\n    this.shuttingDown = true;\n\n    const listeners = this.shutdownListeners.reverse();\n    this.shutdownListeners = [];\n\n    for (const listener of listeners) {\n      await this.runShutdownListener(listener);\n    }\n  }\n\n  /**\n   * Invoke a single teardown callback, isolating its failure so the rest still\n   * run and shutdown is never blocked by one bad hook.\n   */\n  private static async runShutdownListener(listener: ShutdownListener): Promise<void> {\n    try {\n      await listener();\n    } catch (error) {\n      log.error(\"application\", \"shutdown-listener\", error as Error);\n    }\n  }\n\n  /**\n   * Get project uptime in milliseconds\n   */\n  public static get uptime(): number {\n    return process.uptime() * 1000;\n  }\n\n  /**\n   * Get the current environment\n   */\n  public static get environment(): Environment {\n    return environment();\n  }\n\n  /**\n   * Set the current environment\n   */\n  public static setEnvironment(env: Environment) {\n    setEnvironment(env);\n  }\n\n  /**\n   * Check if the application is running in production environment\n   */\n  public static get isProduction(): boolean {\n    return this.environment === \"production\";\n  }\n\n  /**\n   * Check if the application is running in development environment\n   */\n  public static get isDevelopment(): boolean {\n    return this.environment === \"development\";\n  }\n\n  /**\n   * Check if the application is running in test environment\n   */\n  public static get isTest(): boolean {\n    return this.environment === \"test\";\n  }\n\n  /**\n   * Get the root path\n   */\n  public static get rootPath(): string {\n    return rootPath();\n  }\n\n  /**\n   * Get the src path\n   */\n  public static get srcPath(): string {\n    return srcPath();\n  }\n\n  /**\n   * Get the app path\n   */\n  public static get appPath(): string {\n    return appPath();\n  }\n\n  /**\n   * Get the storage path\n   */\n  public static get storagePath(): string {\n    return storagePath();\n  }\n\n  /**\n   * Get the uploads path\n   */\n  public static get uploadsPath(): string {\n    return uploadsPath();\n  }\n\n  /**\n   * Get the public path\n   */\n  public static get publicPath(): string {\n    return publicPath();\n  }\n}\n"],"mappings":"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"}

package/esm/application/boot-signal.d.mts

@@ -1,6 +1,6 @@
 import { Environment, RuntimeStrategy } from "../utils/environment.mjs";
 
-//#region ../core/src/application/boot-signal.d.ts
+//#region core/src/application/boot-signal.d.ts
 /**
  * The only message type the boot channel carries today. Named rather than
  * inlined because both the sender (`sendBootSignal`) and the receiver

package/esm/application/boot-signal.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"boot-signal.d.mts","names":[],"sources":["../../../../../../../core/src/application/boot-signal.ts"],"mappings":";;;;;AAOA;;;KAAY,cAAA;AAAc;AAS1B;;;;AAAgC;AAUhC;AAnB0B,cASb,mBAAA;;;;;;;;;KAUD,UAAA;EACV,IAAA,EAAM,cAAA;EACN,OAAA,UAKA;EAHA,GAAA,UAIA;EAFA,EAAA;EACA,WAAA,EAAa,WAAA;EACb,eAAA,EAAiB,eAAA;EACjB,cAAA,WAEI;EAAJ,IAAA;AAAA;;;AAY8B;AAoBhC;;;;AAAiD;AA4BjD;cAhDa,mBAAA;;;;;;;AAgDwD;;;;;;;;;;;;iBA5BrD,cAAA,CAAe,MAAkB,EAAV,UAAU;;;;;;;;;;iBA4BjC,YAAA,CAAa,OAAA,YAAmB,OAAA,IAAW,UAAU"}
+{"version":3,"file":"boot-signal.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/application/boot-signal.ts"],"mappings":";;;;;AAOA;;;KAAY,cAAA;AAAc;AAS1B;;;;AAAgC;AAUhC;AAnB0B,cASb,mBAAA;;;;;;;;;KAUD,UAAA;EACV,IAAA,EAAM,cAAA;EACN,OAAA,UAKA;EAHA,GAAA,UAIA;EAFA,EAAA;EACA,WAAA,EAAa,WAAA;EACb,eAAA,EAAiB,eAAA;EACjB,cAAA,WAEI;EAAJ,IAAA;AAAA;;;AAY8B;AAoBhC;;;;AAAiD;AA4BjD;cAhDa,mBAAA;;;;;;;AAgDwD;;;;;;;;;;;;iBA5BrD,cAAA,CAAe,MAAkB,EAAV,UAAU;;;;;;;;;;iBA4BjC,YAAA,CAAa,OAAA,YAAmB,OAAA,IAAW,UAAU"}

package/esm/application/boot-signal.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/application/boot-signal.ts
+//#region core/src/application/boot-signal.ts
 /**
 * Schema version of {@link BootSignal}.
 *

package/esm/application/boot-signal.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"boot-signal.mjs","names":[],"sources":["../../../../../../../core/src/application/boot-signal.ts"],"sourcesContent":["import type { Environment, RuntimeStrategy } from \"../utils/environment\";\n\n/**\n * The only message type the boot channel carries today. Named rather than\n * inlined because both the sender (`sendBootSignal`) and the receiver\n * (`warlock start`) must agree on the exact literal.\n */\nexport type BootSignalType = \"warlock:ready\";\n\n/**\n * Schema version of {@link BootSignal}.\n *\n * Present from the first release on purpose: a version field cannot be added to\n * a shipped wire format without a flag day, and this one has to be able to\n * evolve while older CLIs are still supervising newer bundles.\n */\nexport const BOOT_SIGNAL_VERSION = 1;\n\n/**\n * What a booted child process tells its supervising parent over the IPC\n * channel `warlock start` opens for it.\n *\n * This is a wire contract, not an internal detail: `warlock start` prints its\n * success banner **only** when this arrives, so anything watching that banner\n * (a CI gate, a process supervisor) transitively depends on it.\n */\nexport type BootSignal = {\n  type: BootSignalType;\n  version: number;\n  /** The application process, so a supervisor can address it directly. */\n  pid: number;\n  /** When the boot completed, ISO-8601. */\n  at: string;\n  environment: Environment;\n  runtimeStrategy: RuntimeStrategy;\n  bootDurationMs?: number;\n  /** The bound http port, absent for an app with no http connector. */\n  port?: number;\n};\n\n/**\n * Environment flag `warlock start` sets on the process it supervises.\n *\n * An IPC channel alone is NOT proof that the parent speaks this protocol —\n * pm2, a vitest worker fork, and any custom supervisor all hand their child a\n * channel they use for their own messages. Writing to one of those, and then\n * closing it, corrupts someone else's protocol and can kill the process. The\n * flag is the handshake: only a parent that set it gets signalled.\n */\nexport const BOOT_SIGNAL_ENV_KEY = \"WARLOCK_BOOT_SIGNAL\";\n\n/**\n * Report a completed boot to the parent process, if one is supervising.\n *\n * Two conditions must both hold: the process was spawned with an `ipc` stdio\n * channel (`process.send` exists), and the parent identified itself with\n * {@link BOOT_SIGNAL_ENV_KEY}. A bundle run directly (`node app.mjs`, a Docker\n * `CMD`) or under a foreign supervisor is a no-op, so the signal never changes\n * how a standalone process behaves and never touches a channel we don't own.\n *\n * The channel is closed as soon as the message is flushed. An open IPC channel\n * holds a `ref` on the child's event loop, which would keep a finished or\n * wedged process alive and indistinguishable from a healthy server — the exact\n * confusion this signal exists to remove. One message, then disconnect.\n *\n * Failure to send is deliberately swallowed: the parent may have already\n * detached or died, and a supervisor going away must never take down a\n * healthy application.\n */\nexport function sendBootSignal(signal: BootSignal): void {\n  if (typeof process.send !== \"function\" || process.env[BOOT_SIGNAL_ENV_KEY] !== \"1\") {\n    return;\n  }\n\n  // Consumed here so it cannot be inherited by anything this app itself spawns\n  // and make a grandchild report readiness on a channel meant for someone else.\n  delete process.env[BOOT_SIGNAL_ENV_KEY];\n\n  try {\n    process.send(signal, undefined, undefined, () => {\n      process.disconnect?.();\n    });\n  } catch {\n    // The channel closed between the check and the write — the app is up\n    // regardless, and there is no longer anyone to tell.\n  }\n}\n\n/**\n * Narrow an arbitrary IPC payload to a {@link BootSignal}.\n *\n * The parent receives whatever the child chooses to send, so the message is\n * untrusted input and is validated before it is allowed to flip the parent's\n * \"the server is up\" state. A *newer* version than this CLI knows is still\n * accepted — readiness is readiness, and refusing it would make an old\n * supervisor report a healthy app as failed.\n */\nexport function isBootSignal(message: unknown): message is BootSignal {\n  if (typeof message !== \"object\" || message === null) {\n    return false;\n  }\n\n  const candidate = message as { type?: unknown; version?: unknown };\n\n  return candidate.type === \"warlock:ready\" && typeof candidate.version === \"number\";\n}\n"],"mappings":";;;;;;;;AAgBA,MAAa,sBAAsB;;;;;;;;;;AAiCnC,MAAa,sBAAsB;;;;;;;;;;;;;;;;;;;AAoBnC,SAAgB,eAAe,QAA0B;CACvD,IAAI,OAAO,QAAQ,SAAS,cAAc,QAAQ,+BAA6B,KAC7E;CAKF,OAAO,QAAQ,IAAI;CAEnB,IAAI;EACF,QAAQ,KAAK,QAAQ,QAAW,cAAiB;GAC/C,QAAQ,aAAa;EACvB,CAAC;CACH,QAAQ,CAGR;AACF;;;;;;;;;;AAWA,SAAgB,aAAa,SAAyC;CACpE,IAAI,OAAO,YAAY,YAAY,YAAY,MAC7C,OAAO;CAGT,MAAM,YAAY;CAElB,OAAO,UAAU,SAAS,mBAAmB,OAAO,UAAU,YAAY;AAC5E"}
+{"version":3,"file":"boot-signal.mjs","names":[],"sources":["C:/Work/Warlock.js/core/src/application/boot-signal.ts"],"sourcesContent":["import type { Environment, RuntimeStrategy } from \"../utils/environment\";\n\n/**\n * The only message type the boot channel carries today. Named rather than\n * inlined because both the sender (`sendBootSignal`) and the receiver\n * (`warlock start`) must agree on the exact literal.\n */\nexport type BootSignalType = \"warlock:ready\";\n\n/**\n * Schema version of {@link BootSignal}.\n *\n * Present from the first release on purpose: a version field cannot be added to\n * a shipped wire format without a flag day, and this one has to be able to\n * evolve while older CLIs are still supervising newer bundles.\n */\nexport const BOOT_SIGNAL_VERSION = 1;\n\n/**\n * What a booted child process tells its supervising parent over the IPC\n * channel `warlock start` opens for it.\n *\n * This is a wire contract, not an internal detail: `warlock start` prints its\n * success banner **only** when this arrives, so anything watching that banner\n * (a CI gate, a process supervisor) transitively depends on it.\n */\nexport type BootSignal = {\n  type: BootSignalType;\n  version: number;\n  /** The application process, so a supervisor can address it directly. */\n  pid: number;\n  /** When the boot completed, ISO-8601. */\n  at: string;\n  environment: Environment;\n  runtimeStrategy: RuntimeStrategy;\n  bootDurationMs?: number;\n  /** The bound http port, absent for an app with no http connector. */\n  port?: number;\n};\n\n/**\n * Environment flag `warlock start` sets on the process it supervises.\n *\n * An IPC channel alone is NOT proof that the parent speaks this protocol —\n * pm2, a vitest worker fork, and any custom supervisor all hand their child a\n * channel they use for their own messages. Writing to one of those, and then\n * closing it, corrupts someone else's protocol and can kill the process. The\n * flag is the handshake: only a parent that set it gets signalled.\n */\nexport const BOOT_SIGNAL_ENV_KEY = \"WARLOCK_BOOT_SIGNAL\";\n\n/**\n * Report a completed boot to the parent process, if one is supervising.\n *\n * Two conditions must both hold: the process was spawned with an `ipc` stdio\n * channel (`process.send` exists), and the parent identified itself with\n * {@link BOOT_SIGNAL_ENV_KEY}. A bundle run directly (`node app.mjs`, a Docker\n * `CMD`) or under a foreign supervisor is a no-op, so the signal never changes\n * how a standalone process behaves and never touches a channel we don't own.\n *\n * The channel is closed as soon as the message is flushed. An open IPC channel\n * holds a `ref` on the child's event loop, which would keep a finished or\n * wedged process alive and indistinguishable from a healthy server — the exact\n * confusion this signal exists to remove. One message, then disconnect.\n *\n * Failure to send is deliberately swallowed: the parent may have already\n * detached or died, and a supervisor going away must never take down a\n * healthy application.\n */\nexport function sendBootSignal(signal: BootSignal): void {\n  if (typeof process.send !== \"function\" || process.env[BOOT_SIGNAL_ENV_KEY] !== \"1\") {\n    return;\n  }\n\n  // Consumed here so it cannot be inherited by anything this app itself spawns\n  // and make a grandchild report readiness on a channel meant for someone else.\n  delete process.env[BOOT_SIGNAL_ENV_KEY];\n\n  try {\n    process.send(signal, undefined, undefined, () => {\n      process.disconnect?.();\n    });\n  } catch {\n    // The channel closed between the check and the write — the app is up\n    // regardless, and there is no longer anyone to tell.\n  }\n}\n\n/**\n * Narrow an arbitrary IPC payload to a {@link BootSignal}.\n *\n * The parent receives whatever the child chooses to send, so the message is\n * untrusted input and is validated before it is allowed to flip the parent's\n * \"the server is up\" state. A *newer* version than this CLI knows is still\n * accepted — readiness is readiness, and refusing it would make an old\n * supervisor report a healthy app as failed.\n */\nexport function isBootSignal(message: unknown): message is BootSignal {\n  if (typeof message !== \"object\" || message === null) {\n    return false;\n  }\n\n  const candidate = message as { type?: unknown; version?: unknown };\n\n  return candidate.type === \"warlock:ready\" && typeof candidate.version === \"number\";\n}\n"],"mappings":";;;;;;;;AAgBA,MAAa,sBAAsB;;;;;;;;;;AAiCnC,MAAa,sBAAsB;;;;;;;;;;;;;;;;;;;AAoBnC,SAAgB,eAAe,QAA0B;CACvD,IAAI,OAAO,QAAQ,SAAS,cAAc,QAAQ,+BAA6B,KAC7E;CAKF,OAAO,QAAQ,IAAI;CAEnB,IAAI;EACF,QAAQ,KAAK,QAAQ,QAAW,cAAiB;GAC/C,QAAQ,aAAa;EACvB,CAAC;CACH,QAAQ,CAGR;AACF;;;;;;;;;;AAWA,SAAgB,aAAa,SAAyC;CACpE,IAAI,OAAO,YAAY,YAAY,YAAY,MAC7C,OAAO;CAGT,MAAM,YAAY;CAElB,OAAO,UAAU,SAAS,mBAAmB,OAAO,UAAU,YAAY;AAC5E"}

package/esm/benchmark/benchmark-snapshots.d.mts

@@ -1,6 +1,6 @@
 import { BenchmarkErrorResult, BenchmarkSnapshotsOptions, BenchmarkSuccessResult } from "./types.mjs";
 
-//#region ../core/src/benchmark/benchmark-snapshots.d.ts
+//#region core/src/benchmark/benchmark-snapshots.d.ts
 declare class BenchmarkSnapshots {
   private readonly maxSnapshots;
   private readonly capture;

package/esm/benchmark/benchmark-snapshots.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"benchmark-snapshots.d.mts","names":[],"sources":["../../../../../../../core/src/benchmark/benchmark-snapshots.ts"],"mappings":";;;cAMa,kBAAA;EAAA,iBACM,YAAA;EAAA,iBACA,OAAA;EAAA,iBACA,SAAA;cAKE,OAAA,GAAU,yBAAA;EAAA;;;;;;;;;EActB,MAAA,CAAO,MAAA,EAAQ,sBAAA,YAAkC,oBAAA;EArBvC;;;;;;;;;EAgDV,YAAA,CAAa,IAAA,YAAgB,sBAAA,YAAkC,oBAAA;EAA/D;;;;;;;;EAYA,YAAA,IAAgB,MAAA,UAEpB,sBAAA,YAAkC,oBAAA;EAoBxB;;AAAa;;;;;;;EAAnB,KAAA,CAAM,IAAA;AAAA"}
+{"version":3,"file":"benchmark-snapshots.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/benchmark-snapshots.ts"],"mappings":";;;cAMa,kBAAA;EAAA,iBACM,YAAA;EAAA,iBACA,OAAA;EAAA,iBACA,SAAA;cAKE,OAAA,GAAU,yBAAA;EAAA;;;;;;;;;EActB,MAAA,CAAO,MAAA,EAAQ,sBAAA,YAAkC,oBAAA;EArBvC;;;;;;;;;EAgDV,YAAA,CAAa,IAAA,YAAgB,sBAAA,YAAkC,oBAAA;EAA/D;;;;;;;;EAYA,YAAA,CAAA,GAAgB,MAAA,UAEpB,sBAAA,YAAkC,oBAAA;EAoBxB;;AAAa;;;;;;;EAAnB,KAAA,CAAM,IAAA;AAAA"}

package/esm/benchmark/benchmark-snapshots.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/benchmark/benchmark-snapshots.ts
+//#region core/src/benchmark/benchmark-snapshots.ts
 var BenchmarkSnapshots = class {
 	constructor(options) {
 		this.snapshots = /* @__PURE__ */ new Map();

package/esm/benchmark/benchmark-snapshots.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"benchmark-snapshots.mjs","names":[],"sources":["../../../../../../../core/src/benchmark/benchmark-snapshots.ts"],"sourcesContent":["import type {\n  BenchmarkErrorResult,\n  BenchmarkSnapshotsOptions,\n  BenchmarkSuccessResult,\n} from \"./types\";\n\nexport class BenchmarkSnapshots {\n  private readonly maxSnapshots: number;\n  private readonly capture: \"error\" | \"value\" | \"all\";\n  private readonly snapshots = new Map<\n    string,\n    (BenchmarkSuccessResult<unknown> | BenchmarkErrorResult)[]\n  >();\n\n  public constructor(options?: BenchmarkSnapshotsOptions) {\n    this.maxSnapshots = options?.maxSnapshots ?? 100;\n    this.capture = options?.capture ?? \"error\";\n  }\n\n  /**\n   * Record a raw result. Called automatically by measure() when a snapshotContainer is set.\n   * Respects the `capture` setting — ignores results that don't match.\n   *\n   * @param result - The success or error result to record.\n   *\n   * @example\n   * snapshots.record(result);\n   */\n  public record(result: BenchmarkSuccessResult<unknown> | BenchmarkErrorResult): void {\n    if (this.capture === \"error\" && result.success) return;\n    if (this.capture === \"value\" && !result.success) return;\n\n    let list = this.snapshots.get(result.name);\n\n    if (!list) {\n      list = [];\n      this.snapshots.set(result.name, list);\n    }\n\n    if (list.length >= this.maxSnapshots && this.maxSnapshots > 0) {\n      list.shift(); // Evict oldest\n    }\n\n    list.push(result);\n  }\n\n  /**\n   * Get all snapshots for one operation name.\n   *\n   * @param name - The operation name.\n   * @returns Array of snapshots for the operation.\n   *\n   * @example\n   * snapshots.getSnapshots(\"db-query\");\n   */\n  public getSnapshots(name: string): (BenchmarkSuccessResult<unknown> | BenchmarkErrorResult)[] {\n    return this.snapshots.get(name) ?? [];\n  }\n\n  /**\n   * Get all snapshots for all tracked operations.\n   *\n   * @returns A mapping of operation names to their snapshots array.\n   *\n   * @example\n   * snapshots.allSnapshots();\n   */\n  public allSnapshots(): Record<\n    string,\n    (BenchmarkSuccessResult<unknown> | BenchmarkErrorResult)[]\n  > {\n    const all: Record<string, (BenchmarkSuccessResult<unknown> | BenchmarkErrorResult)[]> = {};\n\n    for (const [name, list] of this.snapshots.entries()) {\n      all[name] = [...list];\n    }\n\n    return all;\n  }\n\n  /**\n   * Clear snapshots for one or all operations.\n   *\n   * @param name - Optional operation name. If omitted, clears all snapshots.\n   *\n   * @example\n   * snapshots.reset(\"db-query\");\n   * snapshots.reset();\n   */\n  public reset(name?: string): void {\n    if (name) {\n      this.snapshots.delete(name);\n    } else {\n      this.snapshots.clear();\n    }\n  }\n}\n"],"mappings":";AAMA,IAAa,qBAAb,MAAgC;CAQ9B,AAAO,YAAY,SAAqC;mCAL3B,IAAI,IAG/B;EAGA,KAAK,eAAe,SAAS,gBAAgB;EAC7C,KAAK,UAAU,SAAS,WAAW;CACrC;;;;;;;;;;CAWA,AAAO,OAAO,QAAsE;EAClF,IAAI,KAAK,YAAY,WAAW,OAAO,SAAS;EAChD,IAAI,KAAK,YAAY,WAAW,CAAC,OAAO,SAAS;EAEjD,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,IAAI;EAEzC,IAAI,CAAC,MAAM;GACT,OAAO,CAAC;GACR,KAAK,UAAU,IAAI,OAAO,MAAM,IAAI;EACtC;EAEA,IAAI,KAAK,UAAU,KAAK,gBAAgB,KAAK,eAAe,GAC1D,KAAK,MAAM;EAGb,KAAK,KAAK,MAAM;CAClB;;;;;;;;;;CAWA,AAAO,aAAa,MAA0E;EAC5F,OAAO,KAAK,UAAU,IAAI,IAAI,KAAK,CAAC;CACtC;;;;;;;;;CAUA,AAAO,eAGL;EACA,MAAM,MAAkF,CAAC;EAEzF,KAAK,MAAM,CAAC,MAAM,SAAS,KAAK,UAAU,QAAQ,GAChD,IAAI,QAAQ,CAAC,GAAG,IAAI;EAGtB,OAAO;CACT;;;;;;;;;;CAWA,AAAO,MAAM,MAAqB;EAChC,IAAI,MACF,KAAK,UAAU,OAAO,IAAI;OAE1B,KAAK,UAAU,MAAM;CAEzB;AACF"}
+{"version":3,"file":"benchmark-snapshots.mjs","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/benchmark-snapshots.ts"],"sourcesContent":["import type {\n  BenchmarkErrorResult,\n  BenchmarkSnapshotsOptions,\n  BenchmarkSuccessResult,\n} from \"./types\";\n\nexport class BenchmarkSnapshots {\n  private readonly maxSnapshots: number;\n  private readonly capture: \"error\" | \"value\" | \"all\";\n  private readonly snapshots = new Map<\n    string,\n    (BenchmarkSuccessResult<unknown> | BenchmarkErrorResult)[]\n  >();\n\n  public constructor(options?: BenchmarkSnapshotsOptions) {\n    this.maxSnapshots = options?.maxSnapshots ?? 100;\n    this.capture = options?.capture ?? \"error\";\n  }\n\n  /**\n   * Record a raw result. Called automatically by measure() when a snapshotContainer is set.\n   * Respects the `capture` setting — ignores results that don't match.\n   *\n   * @param result - The success or error result to record.\n   *\n   * @example\n   * snapshots.record(result);\n   */\n  public record(result: BenchmarkSuccessResult<unknown> | BenchmarkErrorResult): void {\n    if (this.capture === \"error\" && result.success) return;\n    if (this.capture === \"value\" && !result.success) return;\n\n    let list = this.snapshots.get(result.name);\n\n    if (!list) {\n      list = [];\n      this.snapshots.set(result.name, list);\n    }\n\n    if (list.length >= this.maxSnapshots && this.maxSnapshots > 0) {\n      list.shift(); // Evict oldest\n    }\n\n    list.push(result);\n  }\n\n  /**\n   * Get all snapshots for one operation name.\n   *\n   * @param name - The operation name.\n   * @returns Array of snapshots for the operation.\n   *\n   * @example\n   * snapshots.getSnapshots(\"db-query\");\n   */\n  public getSnapshots(name: string): (BenchmarkSuccessResult<unknown> | BenchmarkErrorResult)[] {\n    return this.snapshots.get(name) ?? [];\n  }\n\n  /**\n   * Get all snapshots for all tracked operations.\n   *\n   * @returns A mapping of operation names to their snapshots array.\n   *\n   * @example\n   * snapshots.allSnapshots();\n   */\n  public allSnapshots(): Record<\n    string,\n    (BenchmarkSuccessResult<unknown> | BenchmarkErrorResult)[]\n  > {\n    const all: Record<string, (BenchmarkSuccessResult<unknown> | BenchmarkErrorResult)[]> = {};\n\n    for (const [name, list] of this.snapshots.entries()) {\n      all[name] = [...list];\n    }\n\n    return all;\n  }\n\n  /**\n   * Clear snapshots for one or all operations.\n   *\n   * @param name - Optional operation name. If omitted, clears all snapshots.\n   *\n   * @example\n   * snapshots.reset(\"db-query\");\n   * snapshots.reset();\n   */\n  public reset(name?: string): void {\n    if (name) {\n      this.snapshots.delete(name);\n    } else {\n      this.snapshots.clear();\n    }\n  }\n}\n"],"mappings":";AAMA,IAAa,qBAAb,MAAgC;CAQ9B,AAAO,YAAY,SAAqC;mCAL3B,IAAI,IAG/B;EAGA,KAAK,eAAe,SAAS,gBAAgB;EAC7C,KAAK,UAAU,SAAS,WAAW;CACrC;;;;;;;;;;CAWA,AAAO,OAAO,QAAsE;EAClF,IAAI,KAAK,YAAY,WAAW,OAAO,SAAS;EAChD,IAAI,KAAK,YAAY,WAAW,CAAC,OAAO,SAAS;EAEjD,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,IAAI;EAEzC,IAAI,CAAC,MAAM;GACT,OAAO,CAAC;GACR,KAAK,UAAU,IAAI,OAAO,MAAM,IAAI;EACtC;EAEA,IAAI,KAAK,UAAU,KAAK,gBAAgB,KAAK,eAAe,GAC1D,KAAK,MAAM;EAGb,KAAK,KAAK,MAAM;CAClB;;;;;;;;;;CAWA,AAAO,aAAa,MAA0E;EAC5F,OAAO,KAAK,UAAU,IAAI,IAAI,KAAK,CAAC;CACtC;;;;;;;;;CAUA,AAAO,eAGL;EACA,MAAM,MAAkF,CAAC;EAEzF,KAAK,MAAM,CAAC,MAAM,SAAS,KAAK,UAAU,QAAQ,GAChD,IAAI,QAAQ,CAAC,GAAG,IAAI;EAGtB,OAAO;CACT;;;;;;;;;;CAWA,AAAO,MAAM,MAAqB;EAChC,IAAI,MACF,KAAK,UAAU,OAAO,IAAI;OAE1B,KAAK,UAAU,MAAM;CAEzB;AACF"}

package/esm/benchmark/benchmark.d.mts

@@ -1,6 +1,6 @@
 import { BenchmarkErrorResult, BenchmarkOptions, BenchmarkSuccessResult } from "./types.mjs";
 
-//#region ../core/src/benchmark/benchmark.d.ts
+//#region core/src/benchmark/benchmark.d.ts
 /**
  * Measure the execution time of a function and classify its performance.
  *

package/esm/benchmark/benchmark.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"benchmark.d.mts","names":[],"sources":["../../../../../../../core/src/benchmark/benchmark.ts"],"mappings":";;;;;AA+CA;;;;;;;;;;;;;;;;;;;;iBAAsB,OAAA,IACpB,IAAA,UACA,EAAA,QAAU,CAAA,GAAI,OAAA,CAAQ,CAAA,GACtB,OAAA,GAAU,gBAAA,CAAiB,CAAA,IAC1B,OAAA,CAAQ,sBAAA,CAAuB,CAAA,IAAK,oBAAA"}
+{"version":3,"file":"benchmark.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/benchmark.ts"],"mappings":";;;;;AA+CA;;;;;;;;;;;;;;;;;;;;iBAAsB,OAAA,GAAA,CACpB,IAAA,UACA,EAAA,QAAU,CAAA,GAAI,OAAA,CAAQ,CAAA,GACtB,OAAA,GAAU,gBAAA,CAAiB,CAAA,IAC1B,OAAA,CAAQ,sBAAA,CAAuB,CAAA,IAAK,oBAAA"}

package/esm/benchmark/benchmark.mjs

@@ -1,7 +1,7 @@
 import { config } from "../config/config-getter.mjs";
 import "../config/index.mjs";
 
-//#region ../core/src/benchmark/benchmark.ts
+//#region core/src/benchmark/benchmark.ts
 /**
 * Classifies latency into "excellent", "good", or "poor" based on thresholds.
 *

package/esm/benchmark/benchmark.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"benchmark.mjs","names":[],"sources":["../../../../../../../core/src/benchmark/benchmark.ts"],"sourcesContent":["import { config } from \"../config\";\nimport type {\n  BenchmarkConfigurations,\n  BenchmarkErrorResult,\n  BenchmarkOptions,\n  BenchmarkSuccessResult,\n} from \"./types\";\n\n/**\n * Classifies latency into \"excellent\", \"good\", or \"poor\" based on thresholds.\n *\n * @example\n * latencyState(80, { excellent: 100, poor: 500 })  // \"excellent\"\n * latencyState(300, { excellent: 100, poor: 500 }) // \"good\"\n * latencyState(600, { excellent: 100, poor: 500 }) // \"poor\"\n */\nfunction latencyState(\n  latency: number,\n  range: { excellent: number; poor: number },\n): \"excellent\" | \"good\" | \"poor\" {\n  if (latency <= range.excellent) return \"excellent\";\n  if (latency >= range.poor) return \"poor\";\n  return \"good\";\n}\n\n/**\n * Measure the execution time of a function and classify its performance.\n *\n * When `enabled` is false, fn() is still called but no timing runs and no hooks fire.\n * A zeroed SuccessResult is returned to keep the return type stable for all callers.\n *\n * @example\n * ```ts\n * const result = await measure(\"db-query\", () => db.query(\"SELECT 1\"), {\n *   latencyRange: { excellent: 100, poor: 500 },\n *   onComplete: (r) => metrics.record(r.latency),\n *   onError:    (r) => logger.error(\"query failed\", r.error),\n *   onFinish:   (r) => logger.info(`${r.name} took ${r.latency}ms`),\n * });\n *\n * if (result.success) {\n *   console.log(result.value);\n * } else {\n *   console.error(result.error);\n * }\n * ```\n */\nexport async function measure<T>(\n  name: string,\n  fn: () => T | Promise<T>,\n  options?: BenchmarkOptions<T>,\n): Promise<BenchmarkSuccessResult<T> | BenchmarkErrorResult> {\n  // Fast path: disabled — call fn() and return a zeroed success wrapper.\n  // No timing, no hooks. Re-throws if fn() throws.\n  if (options?.enabled === false) {\n    const value = await fn();\n    return {\n      name,\n      success: true,\n      value,\n      latency: 0,\n      state: \"excellent\",\n      tags: options.tags,\n      startedAt: new Date(),\n      endedAt: new Date(),\n    };\n  }\n\n  // Resolve latency range from inline options or global config\n  const benchmarkConfig = config.get<BenchmarkConfigurations>(\"benchmark\");\n  const latencyRange = options?.latencyRange ?? benchmarkConfig?.latencyRange;\n\n  const startedAt = new Date();\n  const startTime = performance.now();\n  const profiler = options?.profiler ?? benchmarkConfig?.profiler;\n  const snapshotContainer = options?.snapshotContainer ?? benchmarkConfig?.snapshotContainer;\n\n  try {\n    const value = await fn();\n\n    const endTime = performance.now();\n    const latency = Math.round(endTime - startTime);\n    const state = latencyRange ? latencyState(latency, latencyRange) : \"good\";\n\n    const result: BenchmarkSuccessResult<T> = {\n      name,\n      success: true,\n      value,\n      latency,\n      state,\n      tags: options?.tags,\n      startedAt,\n      endedAt: new Date(),\n    };\n\n    if (profiler) {\n      profiler.record(result);\n    }\n\n    if (snapshotContainer) {\n      snapshotContainer.record(result);\n    }\n\n    options?.onComplete?.(result);\n    options?.onFinish?.(result);\n\n    return result;\n  } catch (thrown) {\n    // Decide whether to benchmark this error or just re-throw immediately\n    const shouldBenchmark = options?.shouldBenchmarkError\n      ? options.shouldBenchmarkError(thrown)\n      : true;\n\n    if (!shouldBenchmark) {\n      throw thrown;\n    }\n\n    // Capture timing even on failure — a 30s timeout is very different from a 2ms crash\n    const endTime = performance.now();\n    const latency = Math.round(endTime - startTime);\n    const state = latencyRange ? latencyState(latency, latencyRange) : \"poor\";\n\n    // Normalize thrown value to something consistent\n    const error = thrown instanceof Error ? thrown : new Error(String(thrown));\n\n    const result: BenchmarkErrorResult = {\n      name,\n      success: false,\n      error,\n      latency,\n      state,\n      tags: options?.tags,\n      startedAt,\n      endedAt: new Date(),\n    };\n\n    if (profiler) {\n      profiler.record(result);\n    }\n\n    if (snapshotContainer) {\n      snapshotContainer.record(result);\n    }\n\n    options?.onError?.(result);\n    options?.onFinish?.(result);\n\n    return result;\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAgBA,SAAS,aACP,SACA,OAC+B;CAC/B,IAAI,WAAW,MAAM,WAAW,OAAO;CACvC,IAAI,WAAW,MAAM,MAAM,OAAO;CAClC,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;AAwBA,eAAsB,QACpB,MACA,IACA,SAC2D;CAG3D,IAAI,SAAS,YAAY,OAEvB,OAAO;EACL;EACA,SAAS;EACT,aAJkB,GAAG;EAKrB,SAAS;EACT,OAAO;EACP,MAAM,QAAQ;EACd,2BAAW,IAAI,KAAK;EACpB,yBAAS,IAAI,KAAK;CACpB;CAIF,MAAM,kBAAkB,OAAO,IAA6B,WAAW;CACvE,MAAM,eAAe,SAAS,gBAAgB,iBAAiB;CAE/D,MAAM,4BAAY,IAAI,KAAK;CAC3B,MAAM,YAAY,YAAY,IAAI;CAClC,MAAM,WAAW,SAAS,YAAY,iBAAiB;CACvD,MAAM,oBAAoB,SAAS,qBAAqB,iBAAiB;CAEzE,IAAI;EACF,MAAM,QAAQ,MAAM,GAAG;EAEvB,MAAM,UAAU,YAAY,IAAI;EAChC,MAAM,UAAU,KAAK,MAAM,UAAU,SAAS;EAG9C,MAAM,SAAoC;GACxC;GACA,SAAS;GACT;GACA;GACA,OAPY,eAAe,aAAa,SAAS,YAAY,IAAI;GAQjE,MAAM,SAAS;GACf;GACA,yBAAS,IAAI,KAAK;EACpB;EAEA,IAAI,UACF,SAAS,OAAO,MAAM;EAGxB,IAAI,mBACF,kBAAkB,OAAO,MAAM;EAGjC,SAAS,aAAa,MAAM;EAC5B,SAAS,WAAW,MAAM;EAE1B,OAAO;CACT,SAAS,QAAQ;EAMf,IAAI,EAJoB,SAAS,uBAC7B,QAAQ,qBAAqB,MAAM,IACnC,OAGF,MAAM;EAIR,MAAM,UAAU,YAAY,IAAI;EAChC,MAAM,UAAU,KAAK,MAAM,UAAU,SAAS;EAC9C,MAAM,QAAQ,eAAe,aAAa,SAAS,YAAY,IAAI;EAKnE,MAAM,SAA+B;GACnC;GACA,SAAS;GACT,OALY,kBAAkB,QAAQ,SAAS,IAAI,MAAM,OAAO,MAAM,CAAC;GAMvE;GACA;GACA,MAAM,SAAS;GACf;GACA,yBAAS,IAAI,KAAK;EACpB;EAEA,IAAI,UACF,SAAS,OAAO,MAAM;EAGxB,IAAI,mBACF,kBAAkB,OAAO,MAAM;EAGjC,SAAS,UAAU,MAAM;EACzB,SAAS,WAAW,MAAM;EAE1B,OAAO;CACT;AACF"}
+{"version":3,"file":"benchmark.mjs","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/benchmark.ts"],"sourcesContent":["import { config } from \"../config\";\nimport type {\n  BenchmarkConfigurations,\n  BenchmarkErrorResult,\n  BenchmarkOptions,\n  BenchmarkSuccessResult,\n} from \"./types\";\n\n/**\n * Classifies latency into \"excellent\", \"good\", or \"poor\" based on thresholds.\n *\n * @example\n * latencyState(80, { excellent: 100, poor: 500 })  // \"excellent\"\n * latencyState(300, { excellent: 100, poor: 500 }) // \"good\"\n * latencyState(600, { excellent: 100, poor: 500 }) // \"poor\"\n */\nfunction latencyState(\n  latency: number,\n  range: { excellent: number; poor: number },\n): \"excellent\" | \"good\" | \"poor\" {\n  if (latency <= range.excellent) return \"excellent\";\n  if (latency >= range.poor) return \"poor\";\n  return \"good\";\n}\n\n/**\n * Measure the execution time of a function and classify its performance.\n *\n * When `enabled` is false, fn() is still called but no timing runs and no hooks fire.\n * A zeroed SuccessResult is returned to keep the return type stable for all callers.\n *\n * @example\n * ```ts\n * const result = await measure(\"db-query\", () => db.query(\"SELECT 1\"), {\n *   latencyRange: { excellent: 100, poor: 500 },\n *   onComplete: (r) => metrics.record(r.latency),\n *   onError:    (r) => logger.error(\"query failed\", r.error),\n *   onFinish:   (r) => logger.info(`${r.name} took ${r.latency}ms`),\n * });\n *\n * if (result.success) {\n *   console.log(result.value);\n * } else {\n *   console.error(result.error);\n * }\n * ```\n */\nexport async function measure<T>(\n  name: string,\n  fn: () => T | Promise<T>,\n  options?: BenchmarkOptions<T>,\n): Promise<BenchmarkSuccessResult<T> | BenchmarkErrorResult> {\n  // Fast path: disabled — call fn() and return a zeroed success wrapper.\n  // No timing, no hooks. Re-throws if fn() throws.\n  if (options?.enabled === false) {\n    const value = await fn();\n    return {\n      name,\n      success: true,\n      value,\n      latency: 0,\n      state: \"excellent\",\n      tags: options.tags,\n      startedAt: new Date(),\n      endedAt: new Date(),\n    };\n  }\n\n  // Resolve latency range from inline options or global config\n  const benchmarkConfig = config.get<BenchmarkConfigurations>(\"benchmark\");\n  const latencyRange = options?.latencyRange ?? benchmarkConfig?.latencyRange;\n\n  const startedAt = new Date();\n  const startTime = performance.now();\n  const profiler = options?.profiler ?? benchmarkConfig?.profiler;\n  const snapshotContainer = options?.snapshotContainer ?? benchmarkConfig?.snapshotContainer;\n\n  try {\n    const value = await fn();\n\n    const endTime = performance.now();\n    const latency = Math.round(endTime - startTime);\n    const state = latencyRange ? latencyState(latency, latencyRange) : \"good\";\n\n    const result: BenchmarkSuccessResult<T> = {\n      name,\n      success: true,\n      value,\n      latency,\n      state,\n      tags: options?.tags,\n      startedAt,\n      endedAt: new Date(),\n    };\n\n    if (profiler) {\n      profiler.record(result);\n    }\n\n    if (snapshotContainer) {\n      snapshotContainer.record(result);\n    }\n\n    options?.onComplete?.(result);\n    options?.onFinish?.(result);\n\n    return result;\n  } catch (thrown) {\n    // Decide whether to benchmark this error or just re-throw immediately\n    const shouldBenchmark = options?.shouldBenchmarkError\n      ? options.shouldBenchmarkError(thrown)\n      : true;\n\n    if (!shouldBenchmark) {\n      throw thrown;\n    }\n\n    // Capture timing even on failure — a 30s timeout is very different from a 2ms crash\n    const endTime = performance.now();\n    const latency = Math.round(endTime - startTime);\n    const state = latencyRange ? latencyState(latency, latencyRange) : \"poor\";\n\n    // Normalize thrown value to something consistent\n    const error = thrown instanceof Error ? thrown : new Error(String(thrown));\n\n    const result: BenchmarkErrorResult = {\n      name,\n      success: false,\n      error,\n      latency,\n      state,\n      tags: options?.tags,\n      startedAt,\n      endedAt: new Date(),\n    };\n\n    if (profiler) {\n      profiler.record(result);\n    }\n\n    if (snapshotContainer) {\n      snapshotContainer.record(result);\n    }\n\n    options?.onError?.(result);\n    options?.onFinish?.(result);\n\n    return result;\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAgBA,SAAS,aACP,SACA,OAC+B;CAC/B,IAAI,WAAW,MAAM,WAAW,OAAO;CACvC,IAAI,WAAW,MAAM,MAAM,OAAO;CAClC,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;AAwBA,eAAsB,QACpB,MACA,IACA,SAC2D;CAG3D,IAAI,SAAS,YAAY,OAEvB,OAAO;EACL;EACA,SAAS;EACT,aAJkB,GAAG;EAKrB,SAAS;EACT,OAAO;EACP,MAAM,QAAQ;EACd,2BAAW,IAAI,KAAK;EACpB,yBAAS,IAAI,KAAK;CACpB;CAIF,MAAM,kBAAkB,OAAO,IAA6B,WAAW;CACvE,MAAM,eAAe,SAAS,gBAAgB,iBAAiB;CAE/D,MAAM,4BAAY,IAAI,KAAK;CAC3B,MAAM,YAAY,YAAY,IAAI;CAClC,MAAM,WAAW,SAAS,YAAY,iBAAiB;CACvD,MAAM,oBAAoB,SAAS,qBAAqB,iBAAiB;CAEzE,IAAI;EACF,MAAM,QAAQ,MAAM,GAAG;EAEvB,MAAM,UAAU,YAAY,IAAI;EAChC,MAAM,UAAU,KAAK,MAAM,UAAU,SAAS;EAG9C,MAAM,SAAoC;GACxC;GACA,SAAS;GACT;GACA;GACA,OAPY,eAAe,aAAa,SAAS,YAAY,IAAI;GAQjE,MAAM,SAAS;GACf;GACA,yBAAS,IAAI,KAAK;EACpB;EAEA,IAAI,UACF,SAAS,OAAO,MAAM;EAGxB,IAAI,mBACF,kBAAkB,OAAO,MAAM;EAGjC,SAAS,aAAa,MAAM;EAC5B,SAAS,WAAW,MAAM;EAE1B,OAAO;CACT,SAAS,QAAQ;EAMf,IAAI,EAJoB,SAAS,uBAC7B,QAAQ,qBAAqB,MAAM,IACnC,OAGF,MAAM;EAIR,MAAM,UAAU,YAAY,IAAI;EAChC,MAAM,UAAU,KAAK,MAAM,UAAU,SAAS;EAC9C,MAAM,QAAQ,eAAe,aAAa,SAAS,YAAY,IAAI;EAKnE,MAAM,SAA+B;GACnC;GACA,SAAS;GACT,OALY,kBAAkB,QAAQ,SAAS,IAAI,MAAM,OAAO,MAAM,CAAC;GAMvE;GACA;GACA,MAAM,SAAS;GACf;GACA,yBAAS,IAAI,KAAK;EACpB;EAEA,IAAI,UACF,SAAS,OAAO,MAAM;EAGxB,IAAI,mBACF,kBAAkB,OAAO,MAAM;EAGjC,SAAS,UAAU,MAAM;EACzB,SAAS,WAAW,MAAM;EAE1B,OAAO;CACT;AACF"}

package/esm/benchmark/channels/console.channel.d.mts

@@ -1,6 +1,6 @@
 import { BenchmarkChannel, BenchmarkStats } from "../types.mjs";
 
-//#region ../core/src/benchmark/channels/console.channel.d.ts
+//#region core/src/benchmark/channels/console.channel.d.ts
 declare class ConsoleChannel implements BenchmarkChannel {
   /**
    * Pretty-prints a stats table per operation on onFlush().

package/esm/benchmark/channels/console.channel.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"console.channel.d.mts","names":[],"sources":["../../../../../../../../core/src/benchmark/channels/console.channel.ts"],"mappings":";;;cAEa,cAAA,YAA0B,gBAAA;;AAAvC;;;;;;;;EAUS,OAAA,CAAQ,KAAA,EAAO,MAAA,SAAe,cAAA;AAAA"}
+{"version":3,"file":"console.channel.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/channels/console.channel.ts"],"mappings":";;;cAEa,cAAA,YAA0B,gBAAA;;AAAvC;;;;;;;;EAUS,OAAA,CAAQ,KAAA,EAAO,MAAA,SAAe,cAAA;AAAA"}

package/esm/benchmark/channels/console.channel.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/benchmark/channels/console.channel.ts
+//#region core/src/benchmark/channels/console.channel.ts
 var ConsoleChannel = class {
 	/**
 	* Pretty-prints a stats table per operation on onFlush().

package/esm/benchmark/channels/console.channel.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"console.channel.mjs","names":[],"sources":["../../../../../../../../core/src/benchmark/channels/console.channel.ts"],"sourcesContent":["import type { BenchmarkChannel, BenchmarkStats } from \"../types\";\n\nexport class ConsoleChannel implements BenchmarkChannel {\n  /**\n   * Pretty-prints a stats table per operation on onFlush().\n   *\n   * @param stats - Aggregated stats for all tracked operations.\n   *\n   * @example\n   * const channel = new ConsoleChannel();\n   * channel.onFlush({ \"db-query\": { p50: 10, count: 100, ... } });\n   */\n  public onFlush(stats: Record<string, BenchmarkStats>): void {\n    const tableData: Record<string, any> = {};\n\n    for (const [name, operationStats] of Object.entries(stats)) {\n      tableData[name] = {\n        \"p50 (ms)\": operationStats.p50,\n        \"p90 (ms)\": operationStats.p90,\n        \"p95 (ms)\": operationStats.p95,\n        \"p99 (ms)\": operationStats.p99,\n        \"Avg (ms)\": operationStats.avg,\n        \"Min (ms)\": operationStats.min,\n        \"Max (ms)\": operationStats.max,\n        \"Error Rate\": `${(operationStats.errorRate * 100).toFixed(2)}%`,\n        Errors: operationStats.errors,\n        Count: operationStats.count,\n      };\n    }\n\n    console.table(tableData);\n  }\n}\n"],"mappings":";AAEA,IAAa,iBAAb,MAAwD;;;;;;;;;;CAUtD,AAAO,QAAQ,OAA6C;EAC1D,MAAM,YAAiC,CAAC;EAExC,KAAK,MAAM,CAAC,MAAM,mBAAmB,OAAO,QAAQ,KAAK,GACvD,UAAU,QAAQ;GAChB,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,cAAc,IAAI,eAAe,YAAY,IAAG,CAAE,QAAQ,CAAC,EAAE;GAC7D,QAAQ,eAAe;GACvB,OAAO,eAAe;EACxB;EAGF,QAAQ,MAAM,SAAS;CACzB;AACF"}
+{"version":3,"file":"console.channel.mjs","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/channels/console.channel.ts"],"sourcesContent":["import type { BenchmarkChannel, BenchmarkStats } from \"../types\";\n\nexport class ConsoleChannel implements BenchmarkChannel {\n  /**\n   * Pretty-prints a stats table per operation on onFlush().\n   *\n   * @param stats - Aggregated stats for all tracked operations.\n   *\n   * @example\n   * const channel = new ConsoleChannel();\n   * channel.onFlush({ \"db-query\": { p50: 10, count: 100, ... } });\n   */\n  public onFlush(stats: Record<string, BenchmarkStats>): void {\n    const tableData: Record<string, any> = {};\n\n    for (const [name, operationStats] of Object.entries(stats)) {\n      tableData[name] = {\n        \"p50 (ms)\": operationStats.p50,\n        \"p90 (ms)\": operationStats.p90,\n        \"p95 (ms)\": operationStats.p95,\n        \"p99 (ms)\": operationStats.p99,\n        \"Avg (ms)\": operationStats.avg,\n        \"Min (ms)\": operationStats.min,\n        \"Max (ms)\": operationStats.max,\n        \"Error Rate\": `${(operationStats.errorRate * 100).toFixed(2)}%`,\n        Errors: operationStats.errors,\n        Count: operationStats.count,\n      };\n    }\n\n    console.table(tableData);\n  }\n}\n"],"mappings":";AAEA,IAAa,iBAAb,MAAwD;;;;;;;;;;CAUtD,AAAO,QAAQ,OAA6C;EAC1D,MAAM,YAAiC,CAAC;EAExC,KAAK,MAAM,CAAC,MAAM,mBAAmB,OAAO,QAAQ,KAAK,GACvD,UAAU,QAAQ;GAChB,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,cAAc,IAAI,eAAe,YAAY,KAAK,QAAQ,CAAC,EAAE;GAC7D,QAAQ,eAAe;GACvB,OAAO,eAAe;EACxB;EAGF,QAAQ,MAAM,SAAS;CACzB;AACF"}

package/esm/benchmark/channels/noop.channel.d.mts

@@ -1,6 +1,6 @@
 import { BenchmarkChannel } from "../types.mjs";
 
-//#region ../core/src/benchmark/channels/noop.channel.d.ts
+//#region core/src/benchmark/channels/noop.channel.d.ts
 declare class NoopChannel implements BenchmarkChannel {
   onFlush(): void;
 }

package/esm/benchmark/channels/noop.channel.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"noop.channel.d.mts","names":[],"sources":["../../../../../../../../core/src/benchmark/channels/noop.channel.ts"],"mappings":";;;cAEa,WAAA,YAAuB,gBAAgB;EAC3C,OAAO;AAAA"}
+{"version":3,"file":"noop.channel.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/channels/noop.channel.ts"],"mappings":";;;cAEa,WAAA,YAAuB,gBAAgB;EAC3C,OAAO,CAAA;AAAA"}

package/esm/benchmark/channels/noop.channel.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/benchmark/channels/noop.channel.ts
+//#region core/src/benchmark/channels/noop.channel.ts
 var NoopChannel = class {
 	onFlush() {}
 };

package/esm/benchmark/channels/noop.channel.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"noop.channel.mjs","names":[],"sources":["../../../../../../../../core/src/benchmark/channels/noop.channel.ts"],"sourcesContent":["import type { BenchmarkChannel } from \"../types\";\n\nexport class NoopChannel implements BenchmarkChannel {\n  public onFlush(): void {}\n}\n"],"mappings":";AAEA,IAAa,cAAb,MAAqD;CACnD,AAAO,UAAgB,CAAC;AAC1B"}
+{"version":3,"file":"noop.channel.mjs","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/channels/noop.channel.ts"],"sourcesContent":["import type { BenchmarkChannel } from \"../types\";\n\nexport class NoopChannel implements BenchmarkChannel {\n  public onFlush(): void {}\n}\n"],"mappings":";AAEA,IAAa,cAAb,MAAqD;CACnD,AAAO,UAAgB,CAAC;AAC1B"}

package/esm/benchmark/profiler.d.mts

@@ -1,6 +1,6 @@
 import { BenchmarkErrorResult, BenchmarkProfilerOptions, BenchmarkStats, BenchmarkSuccessResult } from "./types.mjs";
 
-//#region ../core/src/benchmark/profiler.d.ts
+//#region core/src/benchmark/profiler.d.ts
 declare class BenchmarkProfiler {
   private readonly maxSamples;
   private readonly channels;

package/esm/benchmark/profiler.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"profiler.d.mts","names":[],"sources":["../../../../../../../core/src/benchmark/profiler.ts"],"mappings":";;;cAkBa,iBAAA;EAAA,iBACM,UAAA;EAAA,iBACA,QAAA;EAAA,iBACA,OAAA;EAAA,QACT,QAAA;cAEW,OAAA,GAAU,wBAAA;EAoBP;;;;;;;;EAAf,MAAA,CAAO,MAAA,EAAQ,sBAAA,YAAkC,oBAAA;EAxBvC;;;;;;;;;;EAqEV,KAAA,CAAM,IAAA,WAAe,cAAA;EAAf;;;;;;;;EAoCN,QAAA,IAAY,MAAA,SAAe,cAAA;EAyD3B;;AAAO;;;;EAxCD,KAAA,IAAS,OAAA;;;;;;;;;;;EAmBf,KAAA,CAAM,IAAA;;;;;;;EAqBN,OAAA;AAAA"}
+{"version":3,"file":"profiler.d.mts","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/profiler.ts"],"mappings":";;;cAkBa,iBAAA;EAAA,iBACM,UAAA;EAAA,iBACA,QAAA;EAAA,iBACA,OAAA;EAAA,QACT,QAAA;cAEW,OAAA,GAAU,wBAAA;EAoBP;;;;;;;;EAAf,MAAA,CAAO,MAAA,EAAQ,sBAAA,YAAkC,oBAAA;EAxBvC;;;;;;;;;;EAqEV,KAAA,CAAM,IAAA,WAAe,cAAA;EAAf;;;;;;;;EAoCN,QAAA,CAAA,GAAY,MAAA,SAAe,cAAA;EAyD3B;;AAAO;;;;EAxCD,KAAA,CAAA,GAAS,OAAA;;;;;;;;;;;EAmBf,KAAA,CAAM,IAAA;;;;;;;EAqBN,OAAA,CAAA;AAAA"}

package/esm/benchmark/profiler.mjs

@@ -1,6 +1,6 @@
 import { NoopChannel } from "./channels/noop.channel.mjs";
 
-//#region ../core/src/benchmark/profiler.ts
+//#region core/src/benchmark/profiler.ts
 var BenchmarkProfiler = class {
 	constructor(options) {
 		this.entries = /* @__PURE__ */ new Map();

package/esm/benchmark/profiler.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"profiler.mjs","names":[],"sources":["../../../../../../../core/src/benchmark/profiler.ts"],"sourcesContent":["import { NoopChannel } from \"./channels/noop.channel\";\nimport type {\n  BenchmarkChannel,\n  BenchmarkErrorResult,\n  BenchmarkProfilerOptions,\n  BenchmarkStats,\n  BenchmarkSuccessResult,\n} from \"./types\";\n\ntype BenchmarkEntry = {\n  latencies: number[];\n  sum: number;\n  total: number;\n  errors: number;\n  firstSeenAt: Date;\n  lastSeenAt: Date;\n};\n\nexport class BenchmarkProfiler {\n  private readonly maxSamples: number;\n  private readonly channels: BenchmarkChannel[];\n  private readonly entries = new Map<string, BenchmarkEntry>();\n  private interval?: ReturnType<typeof setInterval>;\n\n  public constructor(options?: BenchmarkProfilerOptions) {\n    this.maxSamples = options?.maxSamples ?? 1000;\n    this.channels = options?.channels ?? [new NoopChannel()];\n\n    if (options?.flushEvery) {\n      this.interval = setInterval(() => {\n        // We use void to explicitly ignore the promise, as this is a background interval\n        void this.flush();\n      }, options.flushEvery);\n    }\n  }\n\n  /**\n   * Record one measurement result. Called automatically by measure() when a profiler is set.\n   *\n   * @param result - The success or error result from measure()\n   *\n   * @example\n   * profiler.record(result);\n   */\n  public record(result: BenchmarkSuccessResult<unknown> | BenchmarkErrorResult): void {\n    let entry = this.entries.get(result.name);\n\n    if (!entry) {\n      entry = {\n        latencies: [],\n        sum: 0,\n        total: 0,\n        errors: 0,\n        firstSeenAt: result.startedAt,\n        lastSeenAt: result.endedAt,\n      };\n\n      this.entries.set(result.name, entry);\n    }\n\n    entry.latencies.push(result.latency);\n    entry.sum += result.latency;\n\n    if (entry.latencies.length > this.maxSamples) {\n      const removed = entry.latencies.shift();\n      if (removed !== undefined) {\n        entry.sum -= removed;\n      }\n    }\n\n    entry.total += 1;\n\n    if (!result.success) {\n      entry.errors += 1;\n    }\n\n    entry.lastSeenAt = result.endedAt;\n  }\n\n  /**\n   * Get aggregated stats for one operation name.\n   * Computes p50/p95/p99 by sorting the ring buffer on demand.\n   *\n   * @param name - The operation name to get stats for.\n   * @returns Stats object or undefined if no data yet.\n   *\n   * @example\n   * const stats = profiler.stats(\"db-query\");\n   */\n  public stats(name: string): BenchmarkStats | undefined {\n    const entry = this.entries.get(name);\n    if (!entry || entry.latencies.length === 0) return undefined;\n\n    const latencies = [...entry.latencies].sort((a, b) => a - b);\n    const count = latencies.length;\n\n    const getP = (percentile: number) => {\n      const index = Math.min(count - 1, Math.floor(count * percentile));\n      return latencies[index];\n    };\n\n    return {\n      p50: getP(0.5),\n      p90: getP(0.9),\n      p95: getP(0.95),\n      p99: getP(0.99),\n      avg: Math.round((entry.sum / count) * 100) / 100,\n      min: latencies[0],\n      max: latencies[count - 1],\n      count: entry.total,\n      errors: entry.errors,\n      errorRate: Math.round((entry.errors / entry.total) * 100) / 100,\n      firstSeenAt: entry.firstSeenAt,\n      lastSeenAt: entry.lastSeenAt,\n    };\n  }\n\n  /**\n   * Get stats for all tracked operations.\n   *\n   * @returns A record mapping operation names to their stats.\n   *\n   * @example\n   * const all = profiler.allStats();\n   */\n  public allStats(): Record<string, BenchmarkStats> {\n    const all: Record<string, BenchmarkStats> = {};\n    for (const name of this.entries.keys()) {\n      const operationStats = this.stats(name);\n      if (operationStats) {\n        all[name] = operationStats;\n      }\n    }\n    return all;\n  }\n\n  /**\n   * Send allStats() to all registered channels.\n   *\n   * @example\n   * await profiler.flush();\n   */\n  public async flush(): Promise<void> {\n    const stats = this.allStats();\n    if (Object.keys(stats).length === 0) return;\n\n    for (const channel of this.channels) {\n      await channel.onFlush(stats);\n    }\n  }\n\n  /**\n   * Clear ring buffer for one or all operations.\n   * Does NOT reset unbounded total/error counters.\n   *\n   * @param name - Optional operation name. If omitted, clears all ring buffers.\n   *\n   * @example\n   * profiler.reset(\"db-query\");\n   * profiler.reset();\n   */\n  public reset(name?: string): void {\n    if (name) {\n      const entry = this.entries.get(name);\n      if (entry) {\n        entry.latencies = [];\n        entry.sum = 0;\n      }\n    } else {\n      for (const entry of this.entries.values()) {\n        entry.latencies = [];\n        entry.sum = 0;\n      }\n    }\n  }\n\n  /**\n   * Dispose the profiler, clearing its auto-flush interval.\n   *\n   * @example\n   * profiler.dispose();\n   */\n  public dispose(): void {\n    if (this.interval) {\n      clearInterval(this.interval);\n      this.interval = undefined;\n    }\n  }\n}\n"],"mappings":";;;AAkBA,IAAa,oBAAb,MAA+B;CAM7B,AAAO,YAAY,SAAoC;iCAH5B,IAAI,IAA4B;EAIzD,KAAK,aAAa,SAAS,cAAc;EACzC,KAAK,WAAW,SAAS,YAAY,CAAC,IAAI,YAAY,CAAC;EAEvD,IAAI,SAAS,YACX,KAAK,WAAW,kBAAkB;GAEhC,AAAK,KAAK,MAAM;EAClB,GAAG,QAAQ,UAAU;CAEzB;;;;;;;;;CAUA,AAAO,OAAO,QAAsE;EAClF,IAAI,QAAQ,KAAK,QAAQ,IAAI,OAAO,IAAI;EAExC,IAAI,CAAC,OAAO;GACV,QAAQ;IACN,WAAW,CAAC;IACZ,KAAK;IACL,OAAO;IACP,QAAQ;IACR,aAAa,OAAO;IACpB,YAAY,OAAO;GACrB;GAEA,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK;EACrC;EAEA,MAAM,UAAU,KAAK,OAAO,OAAO;EACnC,MAAM,OAAO,OAAO;EAEpB,IAAI,MAAM,UAAU,SAAS,KAAK,YAAY;GAC5C,MAAM,UAAU,MAAM,UAAU,MAAM;GACtC,IAAI,YAAY,QACd,MAAM,OAAO;EAEjB;EAEA,MAAM,SAAS;EAEf,IAAI,CAAC,OAAO,SACV,MAAM,UAAU;EAGlB,MAAM,aAAa,OAAO;CAC5B;;;;;;;;;;;CAYA,AAAO,MAAM,MAA0C;EACrD,MAAM,QAAQ,KAAK,QAAQ,IAAI,IAAI;EACnC,IAAI,CAAC,SAAS,MAAM,UAAU,WAAW,GAAG,OAAO;EAEnD,MAAM,YAAY,CAAC,GAAG,MAAM,SAAS,CAAC,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC;EAC3D,MAAM,QAAQ,UAAU;EAExB,MAAM,QAAQ,eAAuB;GAEnC,OAAO,UADO,KAAK,IAAI,QAAQ,GAAG,KAAK,MAAM,QAAQ,UAAU,CAC1C;EACvB;EAEA,OAAO;GACL,KAAK,KAAK,EAAG;GACb,KAAK,KAAK,EAAG;GACb,KAAK,KAAK,GAAI;GACd,KAAK,KAAK,GAAI;GACd,KAAK,KAAK,MAAO,MAAM,MAAM,QAAS,GAAG,IAAI;GAC7C,KAAK,UAAU;GACf,KAAK,UAAU,QAAQ;GACvB,OAAO,MAAM;GACb,QAAQ,MAAM;GACd,WAAW,KAAK,MAAO,MAAM,SAAS,MAAM,QAAS,GAAG,IAAI;GAC5D,aAAa,MAAM;GACnB,YAAY,MAAM;EACpB;CACF;;;;;;;;;CAUA,AAAO,WAA2C;EAChD,MAAM,MAAsC,CAAC;EAC7C,KAAK,MAAM,QAAQ,KAAK,QAAQ,KAAK,GAAG;GACtC,MAAM,iBAAiB,KAAK,MAAM,IAAI;GACtC,IAAI,gBACF,IAAI,QAAQ;EAEhB;EACA,OAAO;CACT;;;;;;;CAQA,MAAa,QAAuB;EAClC,MAAM,QAAQ,KAAK,SAAS;EAC5B,IAAI,OAAO,KAAK,KAAK,CAAC,CAAC,WAAW,GAAG;EAErC,KAAK,MAAM,WAAW,KAAK,UACzB,MAAM,QAAQ,QAAQ,KAAK;CAE/B;;;;;;;;;;;CAYA,AAAO,MAAM,MAAqB;EAChC,IAAI,MAAM;GACR,MAAM,QAAQ,KAAK,QAAQ,IAAI,IAAI;GACnC,IAAI,OAAO;IACT,MAAM,YAAY,CAAC;IACnB,MAAM,MAAM;GACd;EACF,OACE,KAAK,MAAM,SAAS,KAAK,QAAQ,OAAO,GAAG;GACzC,MAAM,YAAY,CAAC;GACnB,MAAM,MAAM;EACd;CAEJ;;;;;;;CAQA,AAAO,UAAgB;EACrB,IAAI,KAAK,UAAU;GACjB,cAAc,KAAK,QAAQ;GAC3B,KAAK,WAAW;EAClB;CACF;AACF"}
+{"version":3,"file":"profiler.mjs","names":[],"sources":["C:/Work/Warlock.js/core/src/benchmark/profiler.ts"],"sourcesContent":["import { NoopChannel } from \"./channels/noop.channel\";\nimport type {\n  BenchmarkChannel,\n  BenchmarkErrorResult,\n  BenchmarkProfilerOptions,\n  BenchmarkStats,\n  BenchmarkSuccessResult,\n} from \"./types\";\n\ntype BenchmarkEntry = {\n  latencies: number[];\n  sum: number;\n  total: number;\n  errors: number;\n  firstSeenAt: Date;\n  lastSeenAt: Date;\n};\n\nexport class BenchmarkProfiler {\n  private readonly maxSamples: number;\n  private readonly channels: BenchmarkChannel[];\n  private readonly entries = new Map<string, BenchmarkEntry>();\n  private interval?: ReturnType<typeof setInterval>;\n\n  public constructor(options?: BenchmarkProfilerOptions) {\n    this.maxSamples = options?.maxSamples ?? 1000;\n    this.channels = options?.channels ?? [new NoopChannel()];\n\n    if (options?.flushEvery) {\n      this.interval = setInterval(() => {\n        // We use void to explicitly ignore the promise, as this is a background interval\n        void this.flush();\n      }, options.flushEvery);\n    }\n  }\n\n  /**\n   * Record one measurement result. Called automatically by measure() when a profiler is set.\n   *\n   * @param result - The success or error result from measure()\n   *\n   * @example\n   * profiler.record(result);\n   */\n  public record(result: BenchmarkSuccessResult<unknown> | BenchmarkErrorResult): void {\n    let entry = this.entries.get(result.name);\n\n    if (!entry) {\n      entry = {\n        latencies: [],\n        sum: 0,\n        total: 0,\n        errors: 0,\n        firstSeenAt: result.startedAt,\n        lastSeenAt: result.endedAt,\n      };\n\n      this.entries.set(result.name, entry);\n    }\n\n    entry.latencies.push(result.latency);\n    entry.sum += result.latency;\n\n    if (entry.latencies.length > this.maxSamples) {\n      const removed = entry.latencies.shift();\n      if (removed !== undefined) {\n        entry.sum -= removed;\n      }\n    }\n\n    entry.total += 1;\n\n    if (!result.success) {\n      entry.errors += 1;\n    }\n\n    entry.lastSeenAt = result.endedAt;\n  }\n\n  /**\n   * Get aggregated stats for one operation name.\n   * Computes p50/p95/p99 by sorting the ring buffer on demand.\n   *\n   * @param name - The operation name to get stats for.\n   * @returns Stats object or undefined if no data yet.\n   *\n   * @example\n   * const stats = profiler.stats(\"db-query\");\n   */\n  public stats(name: string): BenchmarkStats | undefined {\n    const entry = this.entries.get(name);\n    if (!entry || entry.latencies.length === 0) return undefined;\n\n    const latencies = [...entry.latencies].sort((a, b) => a - b);\n    const count = latencies.length;\n\n    const getP = (percentile: number) => {\n      const index = Math.min(count - 1, Math.floor(count * percentile));\n      return latencies[index];\n    };\n\n    return {\n      p50: getP(0.5),\n      p90: getP(0.9),\n      p95: getP(0.95),\n      p99: getP(0.99),\n      avg: Math.round((entry.sum / count) * 100) / 100,\n      min: latencies[0],\n      max: latencies[count - 1],\n      count: entry.total,\n      errors: entry.errors,\n      errorRate: Math.round((entry.errors / entry.total) * 100) / 100,\n      firstSeenAt: entry.firstSeenAt,\n      lastSeenAt: entry.lastSeenAt,\n    };\n  }\n\n  /**\n   * Get stats for all tracked operations.\n   *\n   * @returns A record mapping operation names to their stats.\n   *\n   * @example\n   * const all = profiler.allStats();\n   */\n  public allStats(): Record<string, BenchmarkStats> {\n    const all: Record<string, BenchmarkStats> = {};\n    for (const name of this.entries.keys()) {\n      const operationStats = this.stats(name);\n      if (operationStats) {\n        all[name] = operationStats;\n      }\n    }\n    return all;\n  }\n\n  /**\n   * Send allStats() to all registered channels.\n   *\n   * @example\n   * await profiler.flush();\n   */\n  public async flush(): Promise<void> {\n    const stats = this.allStats();\n    if (Object.keys(stats).length === 0) return;\n\n    for (const channel of this.channels) {\n      await channel.onFlush(stats);\n    }\n  }\n\n  /**\n   * Clear ring buffer for one or all operations.\n   * Does NOT reset unbounded total/error counters.\n   *\n   * @param name - Optional operation name. If omitted, clears all ring buffers.\n   *\n   * @example\n   * profiler.reset(\"db-query\");\n   * profiler.reset();\n   */\n  public reset(name?: string): void {\n    if (name) {\n      const entry = this.entries.get(name);\n      if (entry) {\n        entry.latencies = [];\n        entry.sum = 0;\n      }\n    } else {\n      for (const entry of this.entries.values()) {\n        entry.latencies = [];\n        entry.sum = 0;\n      }\n    }\n  }\n\n  /**\n   * Dispose the profiler, clearing its auto-flush interval.\n   *\n   * @example\n   * profiler.dispose();\n   */\n  public dispose(): void {\n    if (this.interval) {\n      clearInterval(this.interval);\n      this.interval = undefined;\n    }\n  }\n}\n"],"mappings":";;;AAkBA,IAAa,oBAAb,MAA+B;CAM7B,AAAO,YAAY,SAAoC;iCAH5B,IAAI,IAA4B;EAIzD,KAAK,aAAa,SAAS,cAAc;EACzC,KAAK,WAAW,SAAS,YAAY,CAAC,IAAI,YAAY,CAAC;EAEvD,IAAI,SAAS,YACX,KAAK,WAAW,kBAAkB;GAEhC,AAAK,KAAK,MAAM;EAClB,GAAG,QAAQ,UAAU;CAEzB;;;;;;;;;CAUA,AAAO,OAAO,QAAsE;EAClF,IAAI,QAAQ,KAAK,QAAQ,IAAI,OAAO,IAAI;EAExC,IAAI,CAAC,OAAO;GACV,QAAQ;IACN,WAAW,CAAC;IACZ,KAAK;IACL,OAAO;IACP,QAAQ;IACR,aAAa,OAAO;IACpB,YAAY,OAAO;GACrB;GAEA,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK;EACrC;EAEA,MAAM,UAAU,KAAK,OAAO,OAAO;EACnC,MAAM,OAAO,OAAO;EAEpB,IAAI,MAAM,UAAU,SAAS,KAAK,YAAY;GAC5C,MAAM,UAAU,MAAM,UAAU,MAAM;GACtC,IAAI,YAAY,QACd,MAAM,OAAO;EAEjB;EAEA,MAAM,SAAS;EAEf,IAAI,CAAC,OAAO,SACV,MAAM,UAAU;EAGlB,MAAM,aAAa,OAAO;CAC5B;;;;;;;;;;;CAYA,AAAO,MAAM,MAA0C;EACrD,MAAM,QAAQ,KAAK,QAAQ,IAAI,IAAI;EACnC,IAAI,CAAC,SAAS,MAAM,UAAU,WAAW,GAAG,OAAO;EAEnD,MAAM,YAAY,CAAC,GAAG,MAAM,SAAS,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;EAC3D,MAAM,QAAQ,UAAU;EAExB,MAAM,QAAQ,eAAuB;GAEnC,OAAO,UADO,KAAK,IAAI,QAAQ,GAAG,KAAK,MAAM,QAAQ,UAAU,CAC1C;EACvB;EAEA,OAAO;GACL,KAAK,KAAK,EAAG;GACb,KAAK,KAAK,EAAG;GACb,KAAK,KAAK,GAAI;GACd,KAAK,KAAK,GAAI;GACd,KAAK,KAAK,MAAO,MAAM,MAAM,QAAS,GAAG,IAAI;GAC7C,KAAK,UAAU;GACf,KAAK,UAAU,QAAQ;GACvB,OAAO,MAAM;GACb,QAAQ,MAAM;GACd,WAAW,KAAK,MAAO,MAAM,SAAS,MAAM,QAAS,GAAG,IAAI;GAC5D,aAAa,MAAM;GACnB,YAAY,MAAM;EACpB;CACF;;;;;;;;;CAUA,AAAO,WAA2C;EAChD,MAAM,MAAsC,CAAC;EAC7C,KAAK,MAAM,QAAQ,KAAK,QAAQ,KAAK,GAAG;GACtC,MAAM,iBAAiB,KAAK,MAAM,IAAI;GACtC,IAAI,gBACF,IAAI,QAAQ;EAEhB;EACA,OAAO;CACT;;;;;;;CAQA,MAAa,QAAuB;EAClC,MAAM,QAAQ,KAAK,SAAS;EAC5B,IAAI,OAAO,KAAK,KAAK,EAAE,WAAW,GAAG;EAErC,KAAK,MAAM,WAAW,KAAK,UACzB,MAAM,QAAQ,QAAQ,KAAK;CAE/B;;;;;;;;;;;CAYA,AAAO,MAAM,MAAqB;EAChC,IAAI,MAAM;GACR,MAAM,QAAQ,KAAK,QAAQ,IAAI,IAAI;GACnC,IAAI,OAAO;IACT,MAAM,YAAY,CAAC;IACnB,MAAM,MAAM;GACd;EACF,OACE,KAAK,MAAM,SAAS,KAAK,QAAQ,OAAO,GAAG;GACzC,MAAM,YAAY,CAAC;GACnB,MAAM,MAAM;EACd;CAEJ;;;;;;;CAQA,AAAO,UAAgB;EACrB,IAAI,KAAK,UAAU;GACjB,cAAc,KAAK,QAAQ;GAC3B,KAAK,WAAW;EAClB;CACF;AACF"}