theokit 0.71.0 → 0.72.0

package/dist/server/rate-limit/index.d.ts

@@ -1,8 +1,8 @@
 import { IncomingMessage } from 'node:http';
-import { R as RateLimitConfig, a as RateLimitResult } from '../../rate-limit-BdNDZ3vt.js';
-export { c as createRateLimiter, b as createRateLimiterWeb } from '../../rate-limit-BdNDZ3vt.js';
-import { R as RateLimitStore } from '../../rate-limit-store-BEJnhWdw.js';
-export { I as InMemoryStore, a as RateLimitState } from '../../rate-limit-store-BEJnhWdw.js';
+import { R as RateLimitConfig, a as RateLimitResult } from '../../rate-limit-fULgvzCz.js';
+export { c as createRateLimiter, b as createRateLimiterWeb } from '../../rate-limit-fULgvzCz.js';
+import { R as RateLimitStore, B as BakedStoreDeclaration } from '../../rate-limit-store-n1wD4Yk4.js';
+export { I as InMemoryStore, a as RateLimitState, s as slidingCount } from '../../rate-limit-store-n1wD4Yk4.js';
 import { CanActivate } from '@theokit/http';
 
 /**
@@ -73,8 +73,20 @@ interface RouteRateLimitConfig {
     keyBy?: KeyByMode;
     /** Cookie name used by keyBy='session'. Defaults to 'theo_session'. */
     cookieName?: string;
-    /** Optional shared store (for multi-route correlation). Default per-limiter InMemoryStore. */
-    store?: RateLimitStore;
+    /**
+     * Optional shared store (for multi-route correlation). Default per-limiter InMemoryStore.
+     *
+     * B-257 widened this to a union, and the second arm is not a store this runner uses. A deployed
+     * entry's BUILD-time declaration — `{ module, factory, options }` from
+     * `config/schemas/rate-limit.ts` — lands on the same key, because `theokit start` hands the
+     * parsed config straight to `createRouteRateLimiter`. `runtimeStore()` below discriminates on
+     * `incr` and drops the declaration.
+     *
+     * The union is declared rather than the parameter widened at the call site: a cast there would
+     * make the collision invisible to every other reader of this type, and the collision is the fact
+     * worth carrying.
+     */
+    store?: RateLimitStore | BakedStoreDeclaration;
     /**
      * How many reverse proxies sit in front of the app, for `keyBy: 'ip'`. Default `false` — trust
      * none and key on the socket address.
@@ -104,13 +116,6 @@ declare function matchRoutePattern(path: string, pattern: string | RegExp): bool
  * than sharing an empty bucket.
  */
 declare function deriveKey(req: IncomingMessage, keyBy: KeyByMode, cookieName: string, trustProxy?: TrustProxy): Promise<string>;
-/**
- * Per-route rate limiter factory. Returns a sync checker compatible with
- * the existing api-middleware shape.
- *
- * Backwards-compatibility (ADR D2): a flat `{ windowMs, max }` config is
- * accepted and treated as `default` (no per-route variants).
- */
 declare function createRouteRateLimiter(config: RouteRateLimitConfig | RateLimitConfig): (req: IncomingMessage) => Promise<RateLimitResult>;
 /**
  * T5a.2 Phase D slice 1/3 — Web-Standards rate-limiter inputs context.
@@ -290,4 +295,81 @@ interface RateLimitedOptions extends RateLimitConfig {
  */
 declare function RateLimited(options: RateLimitedOptions): new () => CanActivate;
 
-export { type DeriveKeyRequestContext, type KeyByMode, RateLimitConfig, RateLimitResult, RateLimitStore, RateLimited, type RateLimitedKeyBy, type RateLimitedOptions, type RouteRateLimitConfig, type TrustProxy, createRouteRateLimiter, createRouteRateLimiterWeb, deriveKey, deriveKeyFromRequest, matchRoutePattern, resolveClientIp, resolveClientIpFromRequest };
+/**
+ * A rate limiter that AWAITS the store it was given — B-257, decided by
+ * [ADR 0018](../../../../../docs/adr/0018-a-durable-rate-limit-gets-its-own-path-beside-the-sync-facade.md).
+ *
+ * ## Why this is new surface rather than a reshaped `createRateLimiterWeb`
+ *
+ * That facade declares `opts.store` and then refuses anything that is not an `InMemoryStore`
+ * (`rate-limit.ts:110`, throwing at `:118-121`), because its closure returns `RateLimitResult`
+ * synchronously and cannot await. Every durable store is network-backed and therefore async, so the
+ * declared seam rejects exactly the class of store the problem requires.
+ *
+ * Changing that signature would spend a breaking change on a **promise owed** — the symbol is
+ * recorded as one in `docs/api/rate-limit-subpath-surface.md:25` — reached through `theokit/server`,
+ * an umbrella the same row records as **DEPRECATED, removal at `0.x+2`**. A break on a path that
+ * disappears two minors later costs a break's full price for two minors of use. The path beside it
+ * costs two code paths for one concept, which is bounded and reversible: when the umbrella goes, the
+ * facade can follow.
+ *
+ * So the facade keeps its signature, its guard and its throw. Its error message stays accurate.
+ *
+ * ## What this does NOT do
+ *
+ * It ships no store. `rate-limit-store.ts:5-7` names Redis and Cloudflare KV as what a deployment
+ * OPTS INTO, and `docs/adr/0017:32-34` states the principle: *"a framework that shipped one would be
+ * choosing everybody's datastore."* This is the path by which an application reaches a store it
+ * brought.
+ *
+ * `unstorage` is not a shortcut: its declared surface (`server/storage/use-unstorage.ts:32-40`) has
+ * no atomic increment, so a read-then-write over it is the race `rate-limit-store.ts:10-12` exists
+ * to prevent.
+ */
+declare function createDurableRateLimiterWeb(config: RateLimitConfig, opts: {
+    store: RateLimitStore;
+}): (clientIp: string) => Promise<RateLimitResult>;
+
+/**
+ * The limiter's wiring, as a REAL file the compiler reads.
+ *
+ * ## Why it lives in `server/` and not beside the adapter that emits its call
+ *
+ * It was written under `adapters/entries/` first, and `/code-quality` refused it: the declared rule
+ * `adapters-may-only-depend-on-core-router-services` lets `adapters/` reach `core/`, `router/`,
+ * `services/` and `config/`, and nothing else. The plan had asserted "architecture boundary crossed:
+ * none" without checking that rule, and the gate was right — this file is RUNTIME wiring. It builds
+ * the limiter a request is answered by; it does not participate in the build. `server/` is where the
+ * thing it wires already lives.
+ *
+ * B-262 — this file exists because of a measurement taken while implementing the task that preceded
+ * it. The first design moved the limiter's import inside the emitted string, from
+ * `theokit/server/rate-limit` to a bundler virtual id, and claimed that gave `tsc` sight of the
+ * symbol. It does not: `renderCloudflareWorkerEntry` RETURNS a 215-line string, and
+ * `tsconfig.json` includes the package-source include pattern — source, never build output. **No string is
+ * type-checked, whatever its import says.**
+ *
+ * B-257 paid the bill for that invisibility: `createDurableRateLimiterWeb` was used at module scope
+ * in an emitted entry and never imported, the entry threw when it LOADED, and the compiler reported
+ * nothing. The only instrument that caught it was a test that loads and drives the generated entry.
+ *
+ * Deleting either import below fails `npx tsc --noEmit`, naming the symbol, before any test runs.
+ * That is the whole reason this is a file rather than a fragment.
+ *
+ * ## What stays emitted, and why it must
+ *
+ * The VALUES — the window, the max, the store the app named — exist only at build time, so they
+ * cannot live here. They arrive as arguments. The adapter emits the call; this file holds the
+ * decision the call is made of.
+ */
+
+/**
+ * The limiter a deployed entry should use, given what the app declared.
+ *
+ * Always async, whichever branch runs. The sync facade returns a value and the durable one returns a
+ * Promise, and an entry that had to know which it got would be an entry whose call site changes with
+ * the config — the shape that produced B-257's `await` defect. One signature removes the question.
+ */
+declare function buildRateLimiter(config: RateLimitConfig, store: RateLimitStore | undefined): (clientIp: string) => Promise<RateLimitResult>;
+
+export { BakedStoreDeclaration, type DeriveKeyRequestContext, type KeyByMode, RateLimitConfig, RateLimitResult, RateLimitStore, RateLimited, type RateLimitedKeyBy, type RateLimitedOptions, type RouteRateLimitConfig, type TrustProxy, buildRateLimiter, createDurableRateLimiterWeb, createRouteRateLimiter, createRouteRateLimiterWeb, deriveKey, deriveKeyFromRequest, matchRoutePattern, resolveClientIp, resolveClientIpFromRequest };

package/dist/server/rate-limit/index.js

@@ -1,5 +1,7 @@
 import {
   RateLimited,
+  buildRateLimiter,
+  createDurableRateLimiterWeb,
   createRouteRateLimiter,
   createRouteRateLimiterWeb,
   deriveKey,
@@ -7,17 +9,20 @@ import {
   matchRoutePattern,
   resolveClientIp,
   resolveClientIpFromRequest
-} from "../../chunk-Q4NSUGMS.js";
+} from "../../chunk-JJXBRY2U.js";
 import {
   InMemoryStore,
   createRateLimiter,
-  createRateLimiterWeb
-} from "../../chunk-TNI4MARH.js";
+  createRateLimiterWeb,
+  slidingCount
+} from "../../chunk-SFGGRC35.js";
 import "../../chunk-4FWBKX6G.js";
 import "../../chunk-XTHN6JBX.js";
 export {
   InMemoryStore,
   RateLimited,
+  buildRateLimiter,
+  createDurableRateLimiterWeb,
   createRateLimiter,
   createRateLimiterWeb,
   createRouteRateLimiter,
@@ -26,6 +31,7 @@ export {
   deriveKeyFromRequest,
   matchRoutePattern,
   resolveClientIp,
-  resolveClientIpFromRequest
+  resolveClientIpFromRequest,
+  slidingCount
 };
 //# sourceMappingURL=index.js.map

package/dist/server/storage/index.js

@@ -3,7 +3,7 @@ import {
   getStorageManager,
   useDatabase,
   useUnstorage
-} from "../../chunk-3DGIANAN.js";
+} from "../../chunk-FJEKQ4FT.js";
 import "../../chunk-XTHN6JBX.js";
 export {
   StorageManager,

package/dist/{server-boundary-RX2AFU5U.js → server-boundary-P52I6YMH.js}

@@ -3,11 +3,11 @@ import "tsx/esm";
 import {
   resolveTheoRootDir
 } from "./chunk-FDOOBTXJ.js";
-import "./chunk-5XXXJ6DT.js";
+import "./chunk-EZHDAVAF.js";
 import "./chunk-BINRCILF.js";
 import "./chunk-QD5X56I3.js";
 import "./chunk-WSMLSIS5.js";
-import "./chunk-MS4A7N77.js";
+import "./chunk-PEL3MJLM.js";
 import "./chunk-C27VRUVN.js";
 import "./chunk-7UZZHCRN.js";
 import "./chunk-RCFD5W5V.js";
@@ -17,7 +17,7 @@ import {
 } from "./chunk-NO6HA4FG.js";
 import "./chunk-Z7CJHDLS.js";
 import "./chunk-U5PWXS3J.js";
-import "./chunk-OSBGZYXZ.js";
+import "./chunk-D2R5SJEL.js";
 import "./chunk-VQIUTCK2.js";
 
 // src/vite-plugin/server-boundary.ts
@@ -131,4 +131,4 @@ export {
   ServerOnlyImportError,
   serverOnlyImportBoundary
 };
-//# sourceMappingURL=server-boundary-RX2AFU5U.js.map
+//# sourceMappingURL=server-boundary-P52I6YMH.js.map

package/dist/{server-boundary-NZPP33G6.js → server-boundary-WUKORSW2.js}

@@ -2,7 +2,7 @@ import {
   resolveTheoRootDir
 } from "./chunk-7NRFZBAL.js";
 import "./chunk-JMN4COMK.js";
-import "./chunk-SX7ZAHNE.js";
+import "./chunk-WBB3MEEN.js";
 import "./chunk-WSOAN4KN.js";
 import "./chunk-ENSFCKP6.js";
 import "./chunk-KOG5K26V.js";
@@ -17,7 +17,7 @@ import "./chunk-ZDCCILMP.js";
 import "./chunk-CHTAWXC2.js";
 import "./chunk-AVQU5CQF.js";
 import "./chunk-VSLTKX5L.js";
-import "./chunk-TNI4MARH.js";
+import "./chunk-SFGGRC35.js";
 import "./chunk-4ERYQBL6.js";
 import {
   ACTION_SCHEMAS_DIR
@@ -147,4 +147,4 @@ export {
   ServerOnlyImportError,
   serverOnlyImportBoundary
 };
-//# sourceMappingURL=server-boundary-NZPP33G6.js.map
+//# sourceMappingURL=server-boundary-WUKORSW2.js.map

package/dist/{start-TYXS5I4M.js → start-LCA67RES.js}

@@ -12,7 +12,7 @@ import {
 } from "./chunk-46FM5AFZ.js";
 import {
   initCacheEngineFromConfig
-} from "./chunk-NZDGV4YJ.js";
+} from "./chunk-YCF3N4JS.js";
 import {
   preflightNodeAndBindings
 } from "./chunk-KTMQUYED.js";
@@ -29,7 +29,7 @@ import {
   resolveTransformer,
   serveMatchedAuxRoute,
   serveThroughPluginLifecycle
-} from "./chunk-PGDBSK2L.js";
+} from "./chunk-7CHPOMP5.js";
 import "./chunk-BDH5GKFZ.js";
 import {
   findRootDiv
@@ -45,7 +45,7 @@ import {
   mountAgent,
   readAgentPolicy,
   writeWebResponseToServerResponse
-} from "./chunk-5XXXJ6DT.js";
+} from "./chunk-EZHDAVAF.js";
 import {
   getApprovalRegistry,
   resolveProvider
@@ -64,7 +64,7 @@ import {
   createObservabilityPluginFromConfig,
   extractTraceId,
   generateNewTraceContext
-} from "./chunk-MS4A7N77.js";
+} from "./chunk-PEL3MJLM.js";
 import {
   logRequest,
   warnOnce
@@ -85,14 +85,14 @@ import {
 import "./chunk-Z7CJHDLS.js";
 import {
   loadConfig
-} from "./chunk-FFS7IRZF.js";
+} from "./chunk-SZWGXHY3.js";
 import {
   loadEnv
 } from "./chunk-3QPVEJ7D.js";
 import "./chunk-U5PWXS3J.js";
-import "./chunk-TMQ52AZR.js";
+import "./chunk-X2LFNDJQ.js";
 import "./chunk-ZNZISJDZ.js";
-import "./chunk-OSBGZYXZ.js";
+import "./chunk-D2R5SJEL.js";
 import "./chunk-VQIUTCK2.js";
 
 // src/cli/commands/start/index.ts
@@ -271,10 +271,13 @@ async function deriveKey(req, keyBy, cookieName, trustProxy = false) {
       return `ip:${ip}`;
   }
 }
+function runtimeStore(store) {
+  return typeof store?.incr === "function" ? store : void 0;
+}
 function createRouteRateLimiter(config) {
   const isFlat = "windowMs" in config && "max" in config && !("default" in config) && !("routes" in config);
   const cfg = isFlat ? { default: config } : config;
-  const store = cfg.store ?? new InMemoryStore();
+  const store = runtimeStore(cfg.store) ?? new InMemoryStore();
   if (!(store instanceof InMemoryStore)) {
     throw new Error(
       "createRouteRateLimiter: async RateLimitStore implementations require a dedicated async middleware path. Use the InMemoryStore default for the sync facade."
@@ -433,7 +436,7 @@ async function configureStorageManagerFromConfig(storageConfig) {
   if (storageConfig === void 0 || storageConfig === null) return;
   try {
     const { getStorageManager } = await import("./storage-manager-3O5PDO6O.js");
-    const { storageSchema } = await import("./schema-ND7GHPQK.js");
+    const { storageSchema } = await import("./schema-LHNWUR4V.js");
     const parsed = storageSchema.parse(storageConfig);
     getStorageManager().configure(parsed);
   } catch (err) {
@@ -512,7 +515,7 @@ function installGracefulShutdown(server) {
         });
       }
       try {
-        const { getObservabilityAdapter } = await import("./observability-bootstrap-YQKMEYW7.js");
+        const { getObservabilityAdapter } = await import("./observability-bootstrap-FP6LMMJE.js");
         await getObservabilityAdapter()?.shutdown();
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -1428,4 +1431,4 @@ export {
   resolveSsrEntry,
   startCommand
 };
-//# sourceMappingURL=start-TYXS5I4M.js.map
+//# sourceMappingURL=start-LCA67RES.js.map