@rexezuge/runtime 0.0.0-stage → 1.0.0

package/dist/di/Container.js

@@ -0,0 +1,48 @@
+/**
+ * The dependency-injection container.
+ *
+ * Converged verbatim from `backend-runtime/src/di/Container.ts` — the file is
+ * byte-identical (modulo scope) across all nine full-framework consumer repos,
+ * because the last divergence in it was fixed in all of them at once.
+ *
+ * Minimal by design: factory + singleton scopes, branded tokens for inference,
+ * nothing else. A DI container that grows features grows coupling with it.
+ */
+/**
+ * Composition roots (a request scope, a cron entrypoint, tests) wire concrete
+ * implementations once; handlers resolve via `scope.get(Tokens.X)`. Prefer
+ * constructor injection of ports at registration time over inline
+ * `scope.get()` in business logic.
+ */
+class Container {
+    factories = new Map();
+    singletons = new Map();
+    bind(token, factory) {
+        this.factories.set(token, factory);
+        return this;
+    }
+    bindValue(token, value) {
+        this.singletons.set(token, value);
+        return this;
+    }
+    /**
+     * Is a token bound (as a value or a factory)? Used to assert wiring.
+     */
+    has(token) {
+        return this.singletons.has(token) || this.factories.has(token);
+    }
+    get(token) {
+        if (this.singletons.has(token)) {
+            return this.singletons.get(token);
+        }
+        const factory = this.factories.get(token);
+        if (!factory) {
+            throw new Error(`DI container has no binding for token: ${String(token)}`);
+        }
+        const instance = factory(this);
+        this.singletons.set(token, instance);
+        return instance;
+    }
+}
+export { Container };
+//# sourceMappingURL=Container.js.map

package/dist/di/Container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Container.js","sourceRoot":"","sources":["../../src/di/Container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH;;;;;GAKG;AACH,MAAM,SAAS;IACI,SAAS,GAAG,IAAI,GAAG,EAAoC,CAAC;IAExD,UAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE1D,IAAI,CAAI,KAAe,EAAE,OAAmB;QACjD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAEM,SAAS,CAAI,KAAe,EAAE,KAAQ;QAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,GAAG,CAAI,KAAe;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjE,CAAC;IAEM,GAAG,CAAI,KAAe;QAC3B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAM,CAAC;QACzC,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,0CAA0C,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,MAAM,QAAQ,GAAI,OAAsB,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACrC,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/di/RequestScope.d.ts

@@ -0,0 +1,32 @@
+import type { Container } from './Container';
+/**
+ * Single-scope-per-request helper.
+ *
+ * Converged verbatim from `backend-runtime/src/di/RequestScope.ts` (identical in
+ * all nine repos). Middleware creates one `Container` per request and stores it
+ * on the request context; handlers resolve via `getRequestScope(c)` instead of
+ * building a scope per handler — which minted N scopes per request and broke
+ * singleton memoization.
+ */
+interface ScopedContext {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    readonly env: unknown;
+}
+declare function setRequestScope(c: ScopedContext, scope: Container): void;
+/**
+ * Structural adapter for framework contexts.
+ *
+ * Hono's `Context.get` overloads are not assignable to `ScopedContext['get']`,
+ * so call sites used `c as never`. Centralize that single unsafe cast here —
+ * one audited location instead of many scattered ones.
+ */
+declare function asScopedContext(c: {
+    get(key: string): unknown;
+    set?(key: string, value: unknown): void;
+    readonly env: unknown;
+}): ScopedContext;
+declare function getRequestScope(c: ScopedContext): Container;
+export { setRequestScope, getRequestScope, asScopedContext };
+export type { ScopedContext };
+//# sourceMappingURL=RequestScope.d.ts.map

package/dist/di/RequestScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestScope.d.ts","sourceRoot":"","sources":["../../src/di/RequestScope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;GAQG;AACH,UAAU,aAAa;IACrB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAID,iBAAS,eAAe,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAEjE;AAED;;;;;;GAMG;AACH,iBAAS,eAAe,CAAC,CAAC,EAAE;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB,GAAG,aAAa,CAEhB;AAED,iBAAS,eAAe,CAAC,CAAC,EAAE,aAAa,GAAG,SAAS,CAIpD;AAED,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/dist/di/RequestScope.js

@@ -0,0 +1,22 @@
+const SCOPE_KEY = '__kitScope';
+function setRequestScope(c, scope) {
+    c.set(SCOPE_KEY, scope);
+}
+/**
+ * Structural adapter for framework contexts.
+ *
+ * Hono's `Context.get` overloads are not assignable to `ScopedContext['get']`,
+ * so call sites used `c as never`. Centralize that single unsafe cast here —
+ * one audited location instead of many scattered ones.
+ */
+function asScopedContext(c) {
+    return c;
+}
+function getRequestScope(c) {
+    const scope = c.get(SCOPE_KEY);
+    if (!scope)
+        throw new Error('Request scope is not set. Register the scope middleware before routes.');
+    return scope;
+}
+export { setRequestScope, getRequestScope, asScopedContext };
+//# sourceMappingURL=RequestScope.js.map

package/dist/di/RequestScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestScope.js","sourceRoot":"","sources":["../../src/di/RequestScope.ts"],"names":[],"mappings":"AAiBA,MAAM,SAAS,GAAG,YAAY,CAAC;AAE/B,SAAS,eAAe,CAAC,CAAgB,EAAE,KAAgB;IACzD,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,CAIxB;IACC,OAAO,CAA6B,CAAC;AACvC,CAAC;AAED,SAAS,eAAe,CAAC,CAAgB;IACvC,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,SAAS,CAA0B,CAAC;IACxD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IACtG,OAAO,KAAK,CAAC;AACf,CAAC;AAED,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,CAAC"}

package/dist/di/index.d.ts

@@ -0,0 +1,5 @@
+export { Container } from './Container';
+export type { Factory, Token } from './Container';
+export { asScopedContext, getRequestScope, setRequestScope } from './RequestScope';
+export type { ScopedContext } from './RequestScope';
+//# sourceMappingURL=index.d.ts.map

package/dist/di/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/di/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACnF,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/di/index.js

@@ -0,0 +1,3 @@
+export { Container } from './Container';
+export { asScopedContext, getRequestScope, setRequestScope } from './RequestScope';
+//# sourceMappingURL=index.js.map

package/dist/di/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/di/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@rexezuge/runtime` — the platform foundation layer: DI, configuration,
+ * worker bases, logger, KV cache. Zero dependencies (the one platform import
+ * is type-only, resolved through each consumer's generated wrangler types).
+ */
+export { Container } from './di/Container';
+export type { Factory, Token } from './di/Container';
+export { asScopedContext, getRequestScope, setRequestScope } from './di/RequestScope';
+export type { ScopedContext } from './di/RequestScope';
+export { AppConfiguration } from './config/AppConfiguration';
+export { EnvParser } from './config/EnvParser';
+export { DEFAULT_SITE_URL } from './config/ConfigurationDefaults';
+export { AbstractEntrypointWorker } from './base/AbstractEntrypointWorker';
+export type { WorkerExecutionContext, WorkerScheduledController } from './base/AbstractEntrypointWorker';
+export { AbstractDurableObjectWorker } from './base/AbstractDurableObjectWorker';
+export { AbstractQueueWorker } from './base/AbstractQueueWorker';
+export type { WorkerMessageBatch } from './base/AbstractQueueWorker';
+export { AbstractWorkflowWorker } from './base/AbstractWorkflowWorker';
+export type { WorkflowEventLike, WorkflowStepLike } from './base/AbstractWorkflowWorker';
+export { createLogger, isLogLevel, resolveLogLevel } from './logger';
+export type { LogLevel, Logger } from './logger';
+export { KvCache, KV_DOMAINS, buildKvKey, clampTtl, digest128 } from './kv';
+export type { KvDomainDef, KvDomainName, KvNamespaceLike } from './kv';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtF,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AACzG,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAC5E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@rexezuge/runtime` — the platform foundation layer: DI, configuration,
+ * worker bases, logger, KV cache. Zero dependencies (the one platform import
+ * is type-only, resolved through each consumer's generated wrangler types).
+ */
+export { Container } from './di/Container';
+export { asScopedContext, getRequestScope, setRequestScope } from './di/RequestScope';
+export { AppConfiguration } from './config/AppConfiguration';
+export { EnvParser } from './config/EnvParser';
+export { DEFAULT_SITE_URL } from './config/ConfigurationDefaults';
+export { AbstractEntrypointWorker } from './base/AbstractEntrypointWorker';
+export { AbstractDurableObjectWorker } from './base/AbstractDurableObjectWorker';
+export { AbstractQueueWorker } from './base/AbstractQueueWorker';
+export { AbstractWorkflowWorker } from './base/AbstractWorkflowWorker';
+export { createLogger, isLogLevel, resolveLogLevel } from './logger';
+export { KvCache, KV_DOMAINS, buildKvKey, clampTtl, digest128 } from './kv';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAErE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC"}

package/dist/kv/KvCache.d.ts

@@ -0,0 +1,74 @@
+import type { KvDomainName } from './KvDomains';
+interface KvListPage {
+    keys: Array<{
+        name: string;
+    }>;
+    list_complete: boolean;
+    cursor?: string;
+}
+interface KvGetWithMetadataResult {
+    value: string | ArrayBuffer | null;
+    metadata: unknown;
+}
+interface KvNamespaceLike {
+    get(key: string): Promise<string | null>;
+    get(key: string, type: 'text'): Promise<string | null>;
+    get(key: string, type: 'arrayBuffer'): Promise<ArrayBuffer | null>;
+    getWithMetadata?(key: string, type: 'arrayBuffer'): Promise<KvGetWithMetadataResult>;
+    put(key: string, value: string | ArrayBuffer, options?: {
+        expirationTtl?: number;
+        metadata?: unknown;
+    }): Promise<void>;
+    delete(key: string): Promise<unknown>;
+    list(options: {
+        prefix: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<KvListPage>;
+}
+interface KvPutOptions {
+    ttlSeconds?: number;
+}
+interface KvFileMetadata {
+    etag: string;
+    contentType: string | null;
+}
+interface KvBinaryEntry {
+    bytes: Uint8Array;
+    metadata: KvFileMetadata;
+}
+declare const PURGE_LIST_LIMIT = 1000;
+declare const PURGE_MAX_PAGES = 10;
+declare class KvCache {
+    private readonly namespace?;
+    constructor(namespace?: (KvNamespaceLike | null) | undefined);
+    get available(): boolean;
+    getText(domain: KvDomainName, parts: readonly string[]): Promise<string | null>;
+    putText(domain: KvDomainName, parts: readonly string[], value: string, options?: KvPutOptions): Promise<boolean>;
+    getJson<T>(domain: KvDomainName, parts: readonly string[]): Promise<T | null>;
+    putJson(domain: KvDomainName, parts: readonly string[], value: unknown, options?: KvPutOptions): Promise<boolean>;
+    /**
+     * Binary read for the `asset` domain: value bytes plus `{etag, contentType}`
+     * KV metadata in a single entry. Legacy base64-JSON entries carry no metadata
+     * and read as a miss here — the caller falls back to `getJson` for one TTL
+     * window rather than this layer knowing the legacy shape.
+     */
+    getBinary(domain: KvDomainName, parts: readonly string[]): Promise<KvBinaryEntry | null>;
+    /**
+     * Binary write for the `asset` domain. Size is enforced on raw bytes (no
+     * base64 inflation) and failures stay fail-soft like `putText`.
+     */
+    putBinary(domain: KvDomainName, parts: readonly string[], bytes: Uint8Array, metadata: {
+        etag: string;
+        contentType: string | null;
+    }, options?: KvPutOptions): Promise<boolean>;
+    del(domain: KvDomainName, parts: readonly string[]): Promise<void>;
+    /**
+     * Delete every key under a prefix, page-capped. Restarts from the start after
+     * each page: deleting while a positional cursor advances would skip keys.
+     */
+    purgePrefix(domain: KvDomainName, parts?: readonly string[]): Promise<number>;
+}
+export { KvCache, PURGE_LIST_LIMIT, PURGE_MAX_PAGES };
+export type { KvBinaryEntry, KvFileMetadata, KvNamespaceLike, KvPutOptions };
+//# sourceMappingURL=KvCache.d.ts.map

package/dist/kv/KvCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KvCache.d.ts","sourceRoot":"","sources":["../../src/kv/KvCache.ts"],"names":[],"mappings":"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"}

package/dist/kv/KvCache.js

@@ -0,0 +1,198 @@
+import { createLogger } from '../logger';
+import { KV_DOMAINS, buildKvKey, clampTtl, utf8ByteLength } from './KvDomains';
+/**
+ * `KvCache` — typed facade over the single `CACHE` KV binding.
+ *
+ * Converged from `backend-runtime/src/kv/KvCache.ts`, identical in the four
+ * repos that cache through KV. Semantics are fail-soft by design: reads return
+ * `null` on miss, missing binding, or backend error; writes return `false`
+ * when skipped (no binding, oversize value, backend error) and `true` when
+ * stored. Callers treat KV as a pure optimization — D1/DO stay authoritative.
+ */
+const logger = createLogger('KvCache');
+const PURGE_LIST_LIMIT = 1000;
+const PURGE_MAX_PAGES = 10;
+class KvCache {
+    namespace;
+    constructor(namespace) {
+        this.namespace = namespace;
+    }
+    get available() {
+        return !!this.namespace;
+    }
+    async getText(domain, parts) {
+        const ns = this.namespace;
+        if (!ns)
+            return null;
+        try {
+            return await ns.get(buildKvKey(domain, parts));
+        }
+        catch (error) {
+            logger.debug(`KV get failed for ${domain}: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    async putText(domain, parts, value, options) {
+        const ns = this.namespace;
+        if (!ns)
+            return false;
+        // No unknown-domain check: `buildKvKey` below throws for one, and the
+        // return type has never been able to express that. A silent `false` here
+        // would have made an unknown domain look like a namespace miss.
+        const def = KV_DOMAINS[domain];
+        if (utf8ByteLength(value) > def.maxValueBytes) {
+            logger.debug(`KV put skipped for ${domain}: value exceeds ${def.maxValueBytes} bytes.`);
+            return false;
+        }
+        try {
+            const ttl = clampTtl(options?.ttlSeconds, domain);
+            await ns.put(buildKvKey(domain, parts), value, { expirationTtl: ttl });
+            return true;
+        }
+        catch (error) {
+            logger.debug(`KV put failed for ${domain}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    async getJson(domain, parts) {
+        const raw = await this.getText(domain, parts);
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async putJson(domain, parts, value, options) {
+        let raw;
+        try {
+            raw = JSON.stringify(value);
+        }
+        catch {
+            return false;
+        }
+        return typeof raw === 'string' && this.putText(domain, parts, raw, options);
+    }
+    /**
+     * Binary read for the `asset` domain: value bytes plus `{etag, contentType}`
+     * KV metadata in a single entry. Legacy base64-JSON entries carry no metadata
+     * and read as a miss here — the caller falls back to `getJson` for one TTL
+     * window rather than this layer knowing the legacy shape.
+     */
+    async getBinary(domain, parts) {
+        const ns = this.namespace;
+        if (!ns || typeof ns.getWithMetadata !== 'function')
+            return null;
+        try {
+            const res = await ns.getWithMetadata(buildKvKey(domain, parts), 'arrayBuffer');
+            if (!res || res.value == null)
+                return null;
+            const value = res.value;
+            let bytes = null;
+            if (value instanceof ArrayBuffer) {
+                bytes = new Uint8Array(value.slice(0));
+            }
+            else if (value instanceof Uint8Array) {
+                bytes = value.slice();
+            }
+            else if (typeof value === 'string') {
+                bytes = new TextEncoder().encode(value);
+            }
+            if (!bytes)
+                return null;
+            const meta = res.metadata;
+            if (typeof meta !== 'object' || meta === null || typeof meta.etag !== 'string' || meta.etag === '')
+                return null;
+            return { bytes, metadata: { etag: meta.etag, contentType: typeof meta.contentType === 'string' ? meta.contentType : null } };
+        }
+        catch (error) {
+            logger.debug(`KV getBinary failed for ${domain}: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Binary write for the `asset` domain. Size is enforced on raw bytes (no
+     * base64 inflation) and failures stay fail-soft like `putText`.
+     */
+    async putBinary(domain, parts, bytes, metadata, options) {
+        const ns = this.namespace;
+        if (!ns)
+            return false;
+        if (!(bytes instanceof Uint8Array)) {
+            logger.debug(`KV putBinary skipped for ${domain}: value is not bytes.`);
+            return false;
+        }
+        const def = KV_DOMAINS[domain];
+        if (bytes.byteLength > def.maxValueBytes) {
+            logger.debug(`KV putBinary skipped for ${domain}: value exceeds ${def.maxValueBytes} bytes.`);
+            return false;
+        }
+        if (typeof metadata?.etag !== 'string' || metadata.etag === '') {
+            logger.debug(`KV putBinary skipped for ${domain}: missing etag metadata.`);
+            return false;
+        }
+        try {
+            const ttl = clampTtl(options?.ttlSeconds, domain);
+            const contentType = typeof metadata.contentType === 'string' ? metadata.contentType : null;
+            await ns.put(buildKvKey(domain, parts), bytes.slice().buffer, {
+                expirationTtl: ttl,
+                metadata: { etag: metadata.etag, contentType },
+            });
+            return true;
+        }
+        catch (error) {
+            logger.debug(`KV putBinary failed for ${domain}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    async del(domain, parts) {
+        const ns = this.namespace;
+        if (!ns)
+            return;
+        try {
+            await ns.delete(buildKvKey(domain, parts));
+        }
+        catch (error) {
+            logger.debug(`KV delete failed for ${domain}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Delete every key under a prefix, page-capped. Restarts from the start after
+     * each page: deleting while a positional cursor advances would skip keys.
+     */
+    async purgePrefix(domain, parts = []) {
+        const ns = this.namespace;
+        if (!ns)
+            return 0;
+        const prefix = parts.length === 0 ? `${domain}:` : buildKvKey(domain, parts);
+        let deleted = 0;
+        try {
+            for (let page = 0; page < PURGE_MAX_PAGES; page += 1) {
+                const result = await ns.list({ prefix, limit: PURGE_LIST_LIMIT });
+                if (result.keys.length === 0)
+                    return deleted;
+                for (const key of result.keys) {
+                    await ns.delete(key.name);
+                    deleted += 1;
+                }
+                if (result.keys.length < PURGE_LIST_LIMIT)
+                    return deleted;
+            }
+            // The cap was hit with a full page still coming back, so keys remain and
+            // the caller sees a count indistinguishable from a complete purge. A
+            // write-invalidation that silently under-purges serves pre-write bytes
+            // for a whole TTL while reporting success, so this is never silent.
+            logger.warn(`KV purge for ${domain} hit the ${PURGE_MAX_PAGES * PURGE_LIST_LIMIT}-key page cap; ` +
+                `at least one key may survive invalidation`);
+            return deleted;
+        }
+        catch (error) {
+            logger.warn(`KV purge for ${domain} failed: ${error instanceof Error ? error.message : String(error)}`);
+            return deleted;
+        }
+    }
+}
+export { KvCache, PURGE_LIST_LIMIT, PURGE_MAX_PAGES };
+//# sourceMappingURL=KvCache.js.map

package/dist/kv/KvCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KvCache.js","sourceRoot":"","sources":["../../src/kv/KvCache.ts"],"names":[],"mappings":"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"}

package/dist/kv/KvDomains.d.ts

@@ -0,0 +1,34 @@
+declare const KV_MAX_KEY_LENGTH = 512;
+declare const KV_MIN_TTL_SECONDS = 60;
+type KvDomainName = 'session' | 'asset' | 'metadata';
+interface KvDomainDef {
+    ttlSeconds: number;
+    maxValueBytes: number;
+    description: string;
+}
+declare const KV_DOMAINS: Record<KvDomainName, KvDomainDef>;
+/**
+ * 128-bit digest built from four independent FNV-1a lanes.
+ *
+ * Why not a single 32-bit FNV: `buildKvKey` falls back to a digest when a key
+ * exceeds the platform's 512-character limit, and the longest keys embed a
+ * user-controlled path or name. A 32-bit digest over a shared keyspace is
+ * collision-searchable — someone who controls names in their own scope could
+ * grind a colliding key and read another tenant's cached bytes. Four lanes over
+ * the same bytes with different offsets/primes cost one extra pass and take a
+ * birthday collision to ~2^64 work, which is not worth attacking.
+ *
+ * Synchronous on purpose: `buildKvKey` is called from sync cache-key builders.
+ */
+declare function digest128(input: string): string;
+declare function sanitizeSegment(segment: string): string;
+declare function buildKvKey(domain: KvDomainName, parts: readonly string[]): string;
+declare function utf8ByteLength(value: string): number;
+/**
+ * Resolve a TTL, defaulting to the domain's own. Every domain declares a
+ * required `ttlSeconds`, so there is no "no TTL" case to represent.
+ */
+declare function clampTtl(ttlSeconds: number | undefined, domain: KvDomainName): number;
+export { KV_DOMAINS, KV_MAX_KEY_LENGTH, KV_MIN_TTL_SECONDS, buildKvKey, clampTtl, digest128, sanitizeSegment, utf8ByteLength };
+export type { KvDomainDef, KvDomainName };
+//# sourceMappingURL=KvDomains.d.ts.map

package/dist/kv/KvDomains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KvDomains.d.ts","sourceRoot":"","sources":["../../src/kv/KvDomains.ts"],"names":[],"mappings":"AAiBA,QAAA,MAAM,iBAAiB,MAAM,CAAC;AAC9B,QAAA,MAAM,kBAAkB,KAAK,CAAC;AAE9B,KAAK,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAErD,UAAU,WAAW;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,QAAA,MAAM,UAAU,EAAE,MAAM,CAAC,YAAY,EAAE,WAAW,CAgBjD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,iBAAS,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAcxC;AAED,iBAAS,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,iBAAS,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAc1E;AAED,iBAAS,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;GAGG;AACH,iBAAS,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAG9E;AAED,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC;AAC/H,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC"}

package/dist/kv/KvDomains.js

@@ -0,0 +1,101 @@
+/**
+ * Single-KV keyspace: one `CACHE` binding, domains separated by key prefix.
+ *
+ * Converged from `backend-runtime/src/kv/KvDomains.ts` (Durable-DAV,
+ * Durable-DAV-Router, Edge-Sonic, Mail-Otter — the same table under four sets
+ * of names). The domains are generalized to the three the whole family shares;
+ * a consumer with a different cache vocabulary renames its call sites (clients
+ * adapt) rather than extending the registry, because an open registry is how
+ * prefix collisions start.
+ *
+ * Rationale: D1 and the Durable Object stay the source of truth. KV is a
+ * loss-tolerant, read-heavy cache only — a miss or eviction must always be
+ * recoverable by recompute. Call sites never touch `env.CACHE` directly; they
+ * go through `KvCache` with a closed `KvDomainName` registry so prefixes cannot
+ * collide and TTL/size policy lives in one table.
+ */
+const KV_KEY_VERSION = 'v1';
+const KV_MAX_KEY_LENGTH = 512;
+const KV_MIN_TTL_SECONDS = 60;
+const KV_DOMAINS = {
+    session: {
+        ttlSeconds: 300,
+        maxValueBytes: 65_536,
+        description: 'Per-user session/profile snapshots; invalidated on any credential change.',
+    },
+    asset: {
+        ttlSeconds: 300,
+        maxValueBytes: 10_485_760,
+        description: 'Binary payloads (file bodies, sealed secrets) with etag/contentType metadata; invalidated on write.',
+    },
+    metadata: {
+        ttlSeconds: 120,
+        maxValueBytes: 1_048_576,
+        description: 'Listing/derived snapshots keyed by owner or collection; invalidated on mutation.',
+    },
+};
+/**
+ * 128-bit digest built from four independent FNV-1a lanes.
+ *
+ * Why not a single 32-bit FNV: `buildKvKey` falls back to a digest when a key
+ * exceeds the platform's 512-character limit, and the longest keys embed a
+ * user-controlled path or name. A 32-bit digest over a shared keyspace is
+ * collision-searchable — someone who controls names in their own scope could
+ * grind a colliding key and read another tenant's cached bytes. Four lanes over
+ * the same bytes with different offsets/primes cost one extra pass and take a
+ * birthday collision to ~2^64 work, which is not worth attacking.
+ *
+ * Synchronous on purpose: `buildKvKey` is called from sync cache-key builders.
+ */
+function digest128(input) {
+    const LANES = 4;
+    const offsets = [0x81_1c_9d_c5, 0xc2_b2_ae_35, 0x27_d4_eb_2f, 0x16_56_67_b1];
+    let out = '';
+    for (let lane = 0; lane < LANES; lane += 1) {
+        let hash = offsets[lane];
+        const prime = 0x01_00_01_93 + lane * 0x9e_37_79_b9;
+        for (let i = 0; i < input.length; i += 1) {
+            hash ^= input.codePointAt(i) ?? 0;
+            hash = Math.imul(hash, prime);
+        }
+        out += (hash >>> 0).toString(16).padStart(8, '0');
+    }
+    return out;
+}
+function sanitizeSegment(segment) {
+    const trimmed = segment.trim();
+    if (!trimmed)
+        throw new Error('KV key segment must not be empty.');
+    return encodeURIComponent(trimmed);
+}
+function buildKvKey(domain, parts) {
+    const def = KV_DOMAINS[domain];
+    if (!def)
+        throw new Error(`Unknown KV domain: ${domain}.`);
+    if (parts.length === 0)
+        throw new Error(`KV domain ${domain} requires at least one key part.`);
+    const prefix = `${domain}:${KV_KEY_VERSION}:`;
+    const joined = parts.map((part) => sanitizeSegment(part)).join(':');
+    const full = prefix + joined;
+    if (full.length <= KV_MAX_KEY_LENGTH)
+        return full;
+    // Deterministic overflow form. Note the consequence for invalidation: an
+    // overflowing key does not start with the plain prefix, so `purgePrefix` on
+    // the parts will not match it. Callers must therefore bound the key material
+    // they cache (path length, identifier length) — the digest is a crash guard,
+    // not a caching strategy.
+    return `${prefix}h:${digest128(joined)}`;
+}
+function utf8ByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}
+/**
+ * Resolve a TTL, defaulting to the domain's own. Every domain declares a
+ * required `ttlSeconds`, so there is no "no TTL" case to represent.
+ */
+function clampTtl(ttlSeconds, domain) {
+    const effective = ttlSeconds ?? KV_DOMAINS[domain].ttlSeconds;
+    return Number.isFinite(effective) ? Math.max(KV_MIN_TTL_SECONDS, Math.floor(effective)) : KV_DOMAINS[domain].ttlSeconds;
+}
+export { KV_DOMAINS, KV_MAX_KEY_LENGTH, KV_MIN_TTL_SECONDS, buildKvKey, clampTtl, digest128, sanitizeSegment, utf8ByteLength };
+//# sourceMappingURL=KvDomains.js.map

package/dist/kv/KvDomains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KvDomains.js","sourceRoot":"","sources":["../../src/kv/KvDomains.ts"],"names":[],"mappings":"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"}

package/dist/kv/index.d.ts

@@ -0,0 +1,5 @@
+export { KvCache, PURGE_LIST_LIMIT, PURGE_MAX_PAGES } from './KvCache';
+export type { KvBinaryEntry, KvFileMetadata, KvNamespaceLike, KvPutOptions } from './KvCache';
+export { KV_DOMAINS, KV_MAX_KEY_LENGTH, KV_MIN_TTL_SECONDS, buildKvKey, clampTtl, digest128, sanitizeSegment, utf8ByteLength, } from './KvDomains';
+export type { KvDomainDef, KvDomainName } from './KvDomains';
+//# sourceMappingURL=index.d.ts.map

package/dist/kv/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/kv/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACvE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9F,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,SAAS,EACT,eAAe,EACf,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}