@lenso/cache 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# @lenso/cache
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed finite-TTL JSON caching. The ordinary service is independent of Lenso.
+`/memory`, `/redis` and `/plugin` are separate entries; the root entry imports
+neither Bun Redis nor Lenso, Auth, DB, Manage, Tasks, Log or OTel. Core is an
+optional peer used only by `/plugin`. No SQL migration is needed.
+
+## Ordinary service
+
+```ts
+import { createCache } from "@lenso/cache";
+import { createMemoryCacheAdapter } from "@lenso/cache/memory";
+
+const cache = createCache<string | null>({
+  namespace: "catalog:labels",
+  adapter: createMemoryCacheAdapter({ maxEntries: 1000 }),
+  validate: (value): value is string | null => value === null || typeof value === "string",
+});
+await cache.set("label:42", null, { ttlMs: 30_000 });
+const result = await cache.get("label:42");
+// { status: "hit", value: null }, not a miss
+const tenant = cache.scope("tenant:42");
+const value = await tenant.getOrSet("public-label", async (signal) => {
+  signal.throwIfAborted();
+  return "Local fixture";
+});
+await tenant.delete("public-label");
+await tenant.invalidate();
+cache.close();
+```
+
+`get`, `set`, `delete`, `getMany`, `scope`, `invalidate`, `getOrSet` are async
+business methods (except scope creation/close). `getMany` accepts at most 100
+keys, preserves order and duplicates, and returns a per-key hit, miss or error.
+It is not a transactional snapshot across adapters.
+
+## TTL, isolation and serialization
+
+- TTL units are **integer milliseconds**. Default: 60,000. All stored entries
+  have a positive finite TTL; default maximum: 86,400,000 (24 hours), which
+  applications may lower, not raise. Negative, fractional, non-finite and
+  above-maximum TTLs are rejected. No immortal-entry mode.
+- `set(..., {ttlMs: 0})` deletes the old entry and returns `skipped`, rather than
+  storing forever. A zero default applies this rule too. `getOrSet` with zero
+  ignores/removes an existing hit, loads fresh, and does not store its result.
+  `get` still reads entries created with an explicit positive TTL.
+- Expiry starts when the service serializes the entry before writing. Both
+  adapter expiry and the versioned JSON envelope's `expiresAt <= Date.now()`
+  reject expired reads. Redis physical expiry may be later because of transport
+  latency. Hosts must have synchronized clocks; clock jumps/skew can shorten or
+  extend effective lifetime. This is not a monotonic time guarantee.
+- Namespaces, scope segments and keys are nonempty well-formed Unicode,
+  <=256 UTF-8 bytes, without control characters. Paths are collision-safe and
+  limited to 16 segments including the root. Use application-controlled scopes,
+  not arbitrary request-driven namespace churn. `scope("a:b")` differs from
+  `scope("a").scope("b")`.
+- `invalidate()` affects **only the exact current scope**, not descendants,
+  parents, another plugin, or the whole backend. There is no flush-all, wildcard
+  invalidation or key listing. Plugins sharing an explicit namespace intentionally
+  share values; a namespace is isolation by convention, not authorization.
+- Values allow null, booleans, strings, finite numbers, dense ordinary arrays,
+  and plain/null-prototype objects containing those types. JSON normalizes `-0`
+  to `0`. Reject undefined (including object fields), BigInt, Date, Map/Set,
+  class instances, symbols, functions, accessors, custom array prototypes, sparse
+  arrays and cycles. Maximum nesting: 64. Values are copied by serialization.
+- Default maximum is 65,536 UTF-8 bytes **including the JSON envelope**, tunable
+  up to 1 MiB. Optional `validate` is a runtime type guard for writes and reads;
+  a TypeScript generic alone does not verify data from another writer. Different
+  scope types should provide their own guard and keys/schema versions.
+- Malformed JSON, unsupported envelope versions, oversized entries or failed
+  read guards become `{status:"miss", reason:"corrupt"}`. The entry is not
+  returned or eagerly deleted (a concurrent writer could have replaced it);
+  it expires normally or is replaced by a later load. Invalid writes throw a
+  sanitized `CacheError("serialization")` in both failure modes.
+
+## Adapters and actual guarantees
+
+| Adapter   | Visibility                                                          | Capacity / invalidation                                                                                                                                                                                                                                                                                                       |
+| --------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Memory    | Only users of the same adapter object in one process                | LRU, defaults 1000 entries, 8 MiB approximate serialized key/namespace/generation/value bytes, 128 namespace tokens. Expired reads remove entries. Namespace eviction removes its entries and uses a fresh token. Invalidation traverses at most the bounded entry map. No timers.                                            |
+| Bun Redis | Instances connected to the same standalone Redis primary and prefix | Parameterized Lua fences namespace generations; data keys include the generation. Invalidation changes one control key, no scanning. Old-generation entries expire within their finite TTL. Control keys persist: bound the number of provisioned scopes operationally. Redis memory/eviction policy belongs to its operator. |
+
+Memory byte accounting is not a JavaScript heap measurement. Names and entry
+counts also have limits. Oversized single entries can exceed the adapter byte
+budget independently of the service envelope limit and cause a write failure.
+Backend limits should be aligned with `maxValueBytes`.
+
+Redis uses Bun's built-in `RedisClient` and requires no third-party Redis
+dependency. Its documented target is Bun with Redis >=7.2. Local validation used
+Bun 1.4.2 / Redis 8.10.2, not every Redis version. No Redis Cluster, Sentinel,
+replica-read, failover durability, global ordering or exactly-once claim. Across
+instances, reads/writes fence completed namespace invalidation at the primary;
+operations already in flight can still return their earlier results. Deleted or
+evicted generation metadata is recreated with a new UUID, never a fallback
+generation that could resurrect old values.
+
+Individual getMany WRONGTYPE failures leave healthy keys intact. Whole-command
+or generation-read failure marks every affected item failed. No atomic bulk
+write API or automatic write retry is supplied; a lost connection may leave a
+write's outcome unknown. Concurrent writes to a key are ordinary last backend
+write wins. Cross-instance `delete` does not fence another instance's loader:
+use namespace invalidation when those loads must not repopulate a scope.
+
+## Failures, loading and lifetime
+
+`failureMode` defaults to `fail-closed`: single reads/writes/delete/invalidate
+throw sanitized `CacheError("backend")`; batches expose per-key errors.
+`fail-open` explicitly turns backend reads into misses with reason `backend`,
+and mutations into `bypassed`. `getOrSet` then loads from the authoritative
+source without substituting a local cache. Write results are `stored`,
+`skipped`, `superseded` (generation changed) or `bypassed`. Source loader errors
+are business errors, propagate unchanged, and are never cached or logged here.
+
+`getOrSet` merges loads by exact scope/key **within one service family**, not
+across independently created services, processes or Redis clients. First caller
+chooses loader/TTL; all other callers must use the same semantic loader. Each
+waiter receives an independent JSON copy. One waiter's cancellation only rejects
+that waiter. All cancelled waiters abort the shared loader signal, detach that
+load from new callers and prevent its result being written. Loader cancellation
+is cooperative: a loader ignoring the signal keeps consuming an in-flight slot
+until it settles. Default maximum: 128 active loads across scopes; overflow
+throws `busy`. Closing aborts loads and rejects subsequent operations across
+the service family, never closes the adapter. Cancelled waiter records are
+removed immediately; only one settlement subscription is retained per load.
+The host remains responsible for bounding concurrent live requests/waiters.
+
+Within the family, set/delete/exact invalidation detach and suppress earlier
+load writes. Namespace generation checks suppress late load writes across
+instances too. These are not distributed locks. An already dispatched backend
+command cannot be recalled by cancellation/close; writes that raced an operation
+may complete. A caller already loading may receive its earlier result after
+invalidation. Do not use this cache as a financial ledger, idempotency record,
+session store or permission source of truth.
+
+`onEvent` emits only operation and `backend`/`corrupt` reason. Observer errors
+do not alter results. No values, driver errors, credentials or keys are logged.
+The optional plugin sends these fields to Lenso's existing logger; application
+Log/OTel setup remains unchanged. Avoid sensitive span attributes in callers.
+
+## Optional plugin and owned Redis connection
+
+```ts
+import { RedisClient } from "bun";
+import { definePlugin, type Plugin } from "@lenso/core/plugin";
+import { createRedisCacheAdapter } from "@lenso/cache/redis";
+import { createCachePlugin } from "@lenso/cache/plugin";
+import type { CacheAdapter } from "@lenso/cache";
+
+const redisAdapter: Plugin<CacheAdapter> = definePlugin({
+  id: "catalog-redis",
+  async setup(context) {
+    // Supply CACHE_REDIS_URL through trusted configuration, not committed code.
+    const url = process.env.CACHE_REDIS_URL;
+    if (!url) throw new Error("CACHE_REDIS_URL is required");
+    const client = new RedisClient(url, {
+      connectionTimeout: 1000,
+      autoReconnect: false,
+      enableOfflineQueue: false,
+      maxRetries: 0,
+    });
+    context.onCleanup(() => client.close()); // register before connecting
+    await client.connect();
+    return createRedisCacheAdapter({ client, prefix: "catalog-cache" });
+  },
+});
+const cachePlugin = createCachePlugin({
+  id: "catalog-cache",
+  adapter: redisAdapter, // exact installed instance
+  config: { namespace: "catalog:public", failureMode: "fail-closed" },
+});
+// Install both instances. Consumers use requires: [cachePlugin] and context.get(cachePlugin).
+```
+
+The adapter borrows its client. If a DB/resource plugin owns a driver, keep
+cleanup with that plugin, not the cache. No resource acquisition at module
+top level. The cache plugin uses existing `definePluginConfig`/`bindConfig`;
+`config` also accepts ordered Config sources (`valuesSource`, explicit
+`envSource`, etc.) and resolves before any service setup. Exported `cacheConfig`
+provides a Standard Schema contract and explicit JSON Schema converter.
+Source failures are never made fail-open by cache policy.
+
+No Manage, HTTP, CLI, MCP or Auth operation is automatically exposed. Management
+is absent/disabled by default. If an application exposes delete/invalidate, it
+must choose an explicit operation allowlist, obtain a trusted identity at the
+entry, and authorize the exact scope in its ordinary service with existing Auth
+and Manage. Business JSON is not identity. Do not expose raw values or an
+arbitrary backend prefix/namespace selector to remote clients.
+
+Permission decisions are not cached by any integration here. Authenticate and
+authorize every request against existing Auth/fresh authority, even for cached
+business projections; a TTL cannot guarantee timely revocation. Drizzle remains
+the authoritative store; apply cache invalidation only after a successful DB
+change, using existing Tasks if retry/outbox delivery is needed. No implicit
+transaction coupling, task registration or exactly-once invalidation is added.
+
+## Existing application and checks
+
+`examples/greeting/src/cached.ts` is an opt-in assembly using a bounded memory
+adapter. It caches only the pure formatted text, not input validation or the
+per-call counter. Keys are SHA-256 digests of JSON-encoded names; names whose
+JSON representation exceeds 16 KiB bypass this projection cache to stay within
+its envelope budget. The default greeting
+config and CLI operation remain unchanged.
+
+```sh
+bun run --cwd packages/lenso build
+bun run --cwd packages/cache build
+bun run --cwd packages/cache typecheck
+bun run --cwd packages/cache test
+bun examples/greeting/src/cached.ts
+bun test examples/greeting/src/cached.test.ts
+```
+
+Redis tests launch only a disposable owned loopback server, persistence off,
+using the real Bun driver. They skip explicitly if `redis-server` is unavailable.
+Do not point tests at an existing/production Redis endpoint. Root/memory contain
+no native imports, but Workers deployment/runtime compatibility is unverified;
+Workers can select memory/custom adapters without installing or invoking Redis.
+No additional Workers backend or cache platform is introduced.
+
+The shared `bun.lock` includes this workspace and greeting dependency using the
+integration owner's supplied revision. Landing validates it with
+`bun install --frozen-lockfile`; no third-party dependency upgrade is required.
+
+### Local validation record
+
+- Bun 1.4.2, Redis 8.10.2. Cache build/typecheck passed; 40 cache tests passed,
+  including seven tests using the real Redis driver and an owned disposable
+  server. The cancellation retention fixture joins/cancels 20,000 callers while
+  keeping one loader pending.
+- Greeting build/typecheck passed; six existing/added application tests passed.
+  The opt-in cached assembly ran with counts 1 then 2. Default CLI inspect and
+  stdin call returned successful JSON.
+- Scoped oxlint, oxfmt checks and `git diff --check` passed. Initial development
+  used `--no-save` without changing the root lockfile; landing uses the supplied
+  matching lockfile and frozen installation. Builds use existing scripts.
+- Not run: full repository suite, release verification, deployed Workers,
+  Redis Cluster/Sentinel/failover or other Redis/server versions.

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import { type CacheConfig } from "./contracts";
+export declare const MAX_TTL_MS = 86400000;
+export declare function validateName(value: string): void;
+export declare function validateTtl(ttl: number, max: number): void;
+export declare function resolveCacheConfig(config: CacheConfig): Readonly<Required<CacheConfig>>;

package/dist/contracts.d.ts

@@ -0,0 +1,88 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type CacheErrorCode = "invalid-input" | "serialization" | "backend" | "aborted" | "busy" | "closed";
+/** Messages deliberately exclude driver errors, keys, values and credentials. */
+export declare class CacheError extends Error {
+    readonly code: CacheErrorCode;
+    constructor(code: CacheErrorCode);
+}
+export interface CacheCapabilities {
+    readonly provider: string;
+    readonly sharing: "process" | "shared";
+    readonly invalidation: "namespace-generation";
+    readonly batch: "per-key";
+}
+export type RawCacheRead = string | null | CacheError;
+/** Adapter methods receive opaque service-encoded namespaces and keys.
+ * Generation tokens must never be reused. Reads and writes fence old generations.
+ * Positive finite TTL is mandatory; implementations must not return expired data.
+ * Borrowed adapters/drivers are not closed by the service.
+ */
+export interface CacheAdapter {
+    readonly capabilities: CacheCapabilities;
+    generation(namespace: string): Promise<string>;
+    getMany(namespace: string, generation: string, keys: readonly string[]): Promise<RawCacheRead[]>;
+    set(namespace: string, generation: string, key: string, value: string, ttlMs: number): Promise<boolean>;
+    delete(namespace: string, generation: string, key: string): Promise<void>;
+    invalidate(namespace: string): Promise<void>;
+}
+export interface CacheConfig {
+    readonly namespace: string;
+    readonly defaultTtlMs?: number;
+    readonly maxTtlMs?: number;
+    readonly maxValueBytes?: number;
+    readonly maxInFlight?: number;
+    readonly failureMode?: "fail-open" | "fail-closed";
+}
+export interface CacheEvent {
+    readonly operation: "get" | "set" | "delete" | "invalidate";
+    readonly reason: "backend" | "corrupt";
+}
+export interface CacheOptions<T extends JsonValue> extends CacheConfig {
+    readonly adapter: CacheAdapter;
+    /** Optional runtime type guard. JSON constraints apply even without this guard. */
+    readonly validate?: (value: JsonValue) => value is T;
+    readonly onEvent?: (event: CacheEvent) => void;
+}
+export type CacheLookup<T> = {
+    readonly status: "hit";
+    readonly value: T;
+} | {
+    readonly status: "miss";
+    readonly reason: "absent" | "expired" | "corrupt" | "backend";
+};
+export type CacheBatchResult<T> = CacheLookup<T> | {
+    readonly status: "error";
+    readonly error: CacheError;
+};
+export type CacheWriteResult = {
+    readonly outcome: "stored" | "skipped" | "bypassed" | "superseded";
+};
+export interface Cache<T extends JsonValue = JsonValue> {
+    readonly capabilities: CacheCapabilities;
+    readonly config: Readonly<Required<CacheConfig>>;
+    get(key: string): Promise<CacheLookup<T>>;
+    /** Ordered, duplicates preserved, at most 100 keys. No transactional batch guarantee. */
+    getMany(keys: readonly string[]): Promise<CacheBatchResult<T>[]>;
+    set(key: string, value: T, options?: {
+        ttlMs?: number;
+    }): Promise<CacheWriteResult>;
+    delete(key: string): Promise<{
+        outcome: "deleted-or-absent" | "bypassed";
+    }>;
+    /** Invalidates only this exact scope, not parents, children or other plugins. */
+    invalidate(): Promise<{
+        outcome: "invalidated" | "bypassed";
+    }>;
+    scope(name: string): Cache<T>;
+    scope<U extends JsonValue>(name: string, options: {
+        validate: (value: JsonValue) => value is U;
+    }): Cache<U>;
+    getOrSet(key: string, loader: (signal: AbortSignal) => Promise<T>, options?: {
+        ttlMs?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    /** Closes the service family and aborts its loads, never the borrowed adapter. */
+    close(): void;
+}

package/dist/index-gp63f5x9.js

@@ -0,0 +1,57 @@
+// src/contracts.ts
+class CacheError2 extends Error {
+  code;
+  constructor(code) {
+    super(`Cache operation failed (${code})`);
+    this.code = code;
+    this.name = "CacheError";
+  }
+}
+
+// src/config.ts
+var MAX_TTL_MS = 86400000;
+function validateName(value) {
+  if (typeof value !== "string" || !value || new TextEncoder().encode(value).length > 256 || [...value].some((part) => {
+    const code = part.charCodeAt(0);
+    return code < 32 || code >= 127 && code <= 159 || part.length === 1 && code >= 55296 && code <= 57343;
+  })) {
+    throw new CacheError2("invalid-input");
+  }
+}
+function validateTtl(ttl, max) {
+  if (!Number.isSafeInteger(ttl) || ttl < 0 || ttl > max)
+    throw new CacheError2("invalid-input");
+}
+function resolveCacheConfig2(config) {
+  validateName(config.namespace);
+  for (const key of ["defaultTtlMs", "maxTtlMs", "maxValueBytes", "maxInFlight"]) {
+    if (config[key] !== undefined && typeof config[key] !== "number")
+      throw new CacheError2("invalid-input");
+  }
+  if (config.failureMode !== undefined && config.failureMode !== "fail-open" && config.failureMode !== "fail-closed")
+    throw new CacheError2("invalid-input");
+  const resolved = {
+    namespace: config.namespace,
+    defaultTtlMs: config.defaultTtlMs ?? 60000,
+    maxTtlMs: config.maxTtlMs ?? MAX_TTL_MS,
+    maxValueBytes: config.maxValueBytes ?? 65536,
+    maxInFlight: config.maxInFlight ?? 128,
+    failureMode: config.failureMode ?? "fail-closed"
+  };
+  validateTtl(resolved.maxTtlMs, MAX_TTL_MS);
+  if (resolved.maxTtlMs === 0)
+    throw new CacheError2("invalid-input");
+  validateTtl(resolved.defaultTtlMs, resolved.maxTtlMs);
+  for (const [value, max] of [
+    [resolved.maxValueBytes, 1048576],
+    [resolved.maxInFlight, 1e4]
+  ]) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > max)
+      throw new CacheError2("invalid-input");
+  }
+  if (resolved.failureMode !== "fail-open" && resolved.failureMode !== "fail-closed")
+    throw new CacheError2("invalid-input");
+  return Object.freeze(resolved);
+}
+
+export { CacheError2, MAX_TTL_MS, validateName, validateTtl, resolveCacheConfig2 };

package/dist/index-pmwehpb3.js

@@ -0,0 +1,326 @@
+import {
+  CacheError2,
+  validateName,
+  validateTtl,
+  resolveCacheConfig2
+} from "./index-gp63f5x9.js";
+
+// src/json.ts
+var encoder = new TextEncoder;
+function check(value, ancestors = new Set, depth = 0) {
+  if (value === null || typeof value === "boolean" || typeof value === "string")
+    return;
+  if (typeof value === "number" && Number.isFinite(value))
+    return;
+  if (typeof value !== "object" || value === null || depth >= 64 || ancestors.has(value))
+    throw new CacheError2("serialization");
+  const array = Array.isArray(value);
+  if (array && Object.getPrototypeOf(value) !== Array.prototype)
+    throw new CacheError2("serialization");
+  if (!array && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+    throw new CacheError2("serialization");
+  ancestors.add(value);
+  try {
+    let count = 0;
+    for (const key of Reflect.ownKeys(value)) {
+      if (array && key === "length")
+        continue;
+      if (typeof key !== "string")
+        throw new CacheError2("serialization");
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor.enumerable || !("value" in descriptor))
+        throw new CacheError2("serialization");
+      if (array && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length))
+        throw new CacheError2("serialization");
+      check(descriptor.value, ancestors, depth + 1);
+      count++;
+    }
+    if (array && count !== value.length)
+      throw new CacheError2("serialization");
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function encode(value, expiresAt, maxBytes, validate) {
+  try {
+    check(value);
+    if (validate && !validate(value))
+      throw new CacheError2("serialization");
+    const text = JSON.stringify({ v: 1, expiresAt, value });
+    if (encoder.encode(text).length > maxBytes)
+      throw new CacheError2("serialization");
+    return text;
+  } catch {
+    throw new CacheError2("serialization");
+  }
+}
+function decode(text, maxBytes, validate) {
+  if (encoder.encode(text).length > maxBytes)
+    throw new CacheError2("serialization");
+  const envelope = JSON.parse(text);
+  if (envelope === null || typeof envelope !== "object" || envelope.v !== 1 || !Number.isSafeInteger(envelope.expiresAt) || envelope.expiresAt < 0 || !Object.hasOwn(envelope, "value") || Object.keys(envelope).length !== 3)
+    throw new CacheError2("serialization");
+  check(envelope.value);
+  if (validate && !validate(envelope.value))
+    throw new CacheError2("serialization");
+  return { expiresAt: envelope.expiresAt, value: envelope.value };
+}
+
+// src/index.ts
+function createCache2(options) {
+  const config = resolveCacheConfig2(options);
+  const flights = new Map;
+  const active = new Set;
+  let closed = false;
+  const adapter = options.adapter;
+  function ready() {
+    if (closed)
+      throw new CacheError2("closed");
+  }
+  function event(operation, reason) {
+    try {
+      options.onEvent?.({ operation, reason });
+    } catch {}
+  }
+  function backend(operation) {
+    event(operation, "backend");
+    if (config.failureMode === "fail-closed")
+      throw new CacheError2("backend");
+  }
+  function fence(namespace, key) {
+    const prefix = `${namespace}
+`;
+    for (const [id, flight] of flights) {
+      if (key === undefined ? id.startsWith(prefix) : id === `${prefix}${key}`) {
+        flight.writable = false;
+        flights.delete(id);
+      }
+    }
+  }
+  function scoped(path, validate) {
+    const namespace = JSON.stringify(path);
+    async function read(keys) {
+      let generation;
+      let raw;
+      try {
+        generation = await adapter.generation(namespace);
+        raw = await adapter.getMany(namespace, generation, keys);
+        if (raw.length !== keys.length)
+          throw new CacheError2("backend");
+      } catch {
+        event("get", "backend");
+        return {
+          results: keys.map(() => config.failureMode === "fail-open" ? { status: "miss", reason: "backend" } : { status: "error", error: new CacheError2("backend") })
+        };
+      }
+      return {
+        generation,
+        results: raw.map((item) => {
+          if (item instanceof CacheError2) {
+            event("get", "backend");
+            return config.failureMode === "fail-open" ? { status: "miss", reason: "backend" } : { status: "error", error: new CacheError2("backend") };
+          }
+          if (item === null)
+            return { status: "miss", reason: "absent" };
+          try {
+            const entry = decode(item, config.maxValueBytes, validate);
+            if (entry.expiresAt <= Date.now())
+              return { status: "miss", reason: "expired" };
+            return { status: "hit", value: entry.value };
+          } catch {
+            event("get", "corrupt");
+            return { status: "miss", reason: "corrupt" };
+          }
+        })
+      };
+    }
+    function unwrap(result) {
+      if (result.status === "error")
+        throw result.error;
+      return result;
+    }
+    function ttl(value) {
+      const result = value === undefined ? config.defaultTtlMs : value;
+      validateTtl(result, config.maxTtlMs);
+      return result;
+    }
+    async function write(key, text, duration, generation) {
+      if (generation === undefined)
+        return { outcome: "bypassed" };
+      try {
+        const stored = await adapter.set(namespace, generation, key, text, duration);
+        return { outcome: stored ? "stored" : "superseded" };
+      } catch {
+        backend("set");
+        return { outcome: "bypassed" };
+      }
+    }
+    const service = {
+      capabilities: adapter.capabilities,
+      config,
+      async get(key) {
+        ready();
+        validateName(key);
+        return unwrap((await read([key])).results[0]);
+      },
+      async getMany(keys) {
+        ready();
+        if (!Array.isArray(keys) || keys.length > 100)
+          throw new CacheError2("invalid-input");
+        const copied = [...keys];
+        copied.forEach(validateName);
+        if (!copied.length)
+          return [];
+        return (await read(copied)).results;
+      },
+      async set(key, value, input = {}) {
+        ready();
+        validateName(key);
+        const duration = ttl(input.ttlMs);
+        const text = encode(value, Date.now() + duration, config.maxValueBytes, validate);
+        fence(namespace, key);
+        if (duration === 0) {
+          const result = await service.delete(key);
+          return { outcome: result.outcome === "bypassed" ? "bypassed" : "skipped" };
+        }
+        let generation;
+        try {
+          generation = await adapter.generation(namespace);
+        } catch {
+          backend("set");
+          return { outcome: "bypassed" };
+        }
+        return write(key, text, duration, generation);
+      },
+      async delete(key) {
+        ready();
+        validateName(key);
+        fence(namespace, key);
+        try {
+          const generation = await adapter.generation(namespace);
+          await adapter.delete(namespace, generation, key);
+          return { outcome: "deleted-or-absent" };
+        } catch {
+          backend("delete");
+          return { outcome: "bypassed" };
+        }
+      },
+      async invalidate() {
+        ready();
+        fence(namespace);
+        try {
+          await adapter.invalidate(namespace);
+          return { outcome: "invalidated" };
+        } catch {
+          backend("invalidate");
+          return { outcome: "bypassed" };
+        }
+      },
+      scope(name, input) {
+        ready();
+        validateName(name);
+        if (path.length >= 16)
+          throw new CacheError2("invalid-input");
+        return scoped([...path, name], input?.validate ?? validate);
+      },
+      async getOrSet(key, loader, input = {}) {
+        ready();
+        validateName(key);
+        const duration = ttl(input.ttlMs);
+        if (input.signal?.aborted)
+          throw new CacheError2("aborted");
+        const id = `${namespace}
+${key}`;
+        let flight = flights.get(id);
+        if (!flight) {
+          if (active.size >= config.maxInFlight)
+            throw new CacheError2("busy");
+          flight = {
+            controller: new AbortController,
+            waiters: new Set,
+            writable: true
+          };
+          const current = flight;
+          active.add(current);
+          flights.set(id, current);
+          const work = (async () => {
+            const snapshot = await read([key]);
+            const lookup = unwrap(snapshot.results[0]);
+            if (duration > 0 && lookup.status === "hit")
+              return encode(lookup.value, Date.now() + duration, config.maxValueBytes, validate);
+            if (duration === 0 && snapshot.generation !== undefined && current.writable && !closed && !current.controller.signal.aborted) {
+              try {
+                await adapter.delete(namespace, snapshot.generation, key);
+              } catch {
+                backend("delete");
+              }
+            }
+            if (current.controller.signal.aborted)
+              throw new CacheError2("aborted");
+            const value = await loader(current.controller.signal);
+            if (current.controller.signal.aborted)
+              throw new CacheError2("aborted");
+            const text = encode(value, Date.now() + duration, config.maxValueBytes, validate);
+            if (duration > 0 && current.writable && !closed)
+              await write(key, text, duration, snapshot.generation);
+            return text;
+          })();
+          const settle = (failed, value) => {
+            active.delete(current);
+            if (flights.get(id) === current)
+              flights.delete(id);
+            for (const waiter of current.waiters)
+              waiter.finish(failed, value);
+          };
+          work.then((value) => settle(false, value), (error) => settle(true, error));
+        }
+        const current = flight;
+        const text = await new Promise((resolve, reject) => {
+          let settled = false;
+          const finish = (failed, value) => {
+            if (settled)
+              return;
+            settled = true;
+            input.signal?.removeEventListener("abort", abort);
+            current.controller.signal.removeEventListener("abort", abort);
+            current.waiters.delete(waiter);
+            if (failed)
+              reject(value);
+            else
+              resolve(value);
+          };
+          const waiter = { finish };
+          const abort = () => {
+            finish(true, new CacheError2("aborted"));
+            if (current.waiters.size === 0) {
+              current.writable = false;
+              if (flights.get(id) === current)
+                flights.delete(id);
+              current.controller.abort();
+            }
+          };
+          current.waiters.add(waiter);
+          input.signal?.addEventListener("abort", abort, { once: true });
+          current.controller.signal.addEventListener("abort", abort, { once: true });
+          if (input.signal?.aborted || current.controller.signal.aborted)
+            abort();
+        });
+        return decode(text, config.maxValueBytes, validate).value;
+      },
+      close() {
+        if (closed)
+          return;
+        closed = true;
+        flights.clear();
+        for (const flight of active) {
+          flight.writable = false;
+          flight.controller.abort();
+        }
+      }
+    };
+    return service;
+  }
+  return scoped([config.namespace], options.validate);
+}
+
+export { createCache2 };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { type Cache, type CacheOptions, type JsonValue } from "./contracts";
+export * from "./contracts";
+export { resolveCacheConfig } from "./config";
+export declare function createCache<T extends JsonValue = JsonValue>(options: CacheOptions<T>): Cache<T>;

package/dist/index.js

@@ -0,0 +1,12 @@
+import {
+  createCache2
+} from "./index-pmwehpb3.js";
+import {
+  CacheError2,
+  resolveCacheConfig2
+} from "./index-gp63f5x9.js";
+export {
+  CacheError2 as CacheError,
+  createCache2 as createCache,
+  resolveCacheConfig2 as resolveCacheConfig
+};

package/dist/json.d.ts

@@ -0,0 +1,6 @@
+import { type JsonValue } from "./contracts";
+export declare function encode(value: JsonValue, expiresAt: number, maxBytes: number, validate?: (value: JsonValue) => boolean): string;
+export declare function decode<T extends JsonValue>(text: string, maxBytes: number, validate?: (value: JsonValue) => value is T): {
+    expiresAt: number;
+    value: T;
+};

package/dist/memory.d.ts

@@ -0,0 +1,8 @@
+import { type CacheAdapter } from "./contracts";
+export interface MemoryCacheAdapterOptions {
+    maxEntries?: number;
+    maxBytes?: number;
+    maxNamespaces?: number;
+    now?: () => number;
+}
+export declare function createMemoryCacheAdapter(options?: MemoryCacheAdapterOptions): CacheAdapter;

package/dist/memory.js

@@ -0,0 +1,133 @@
+import {
+  CacheError2,
+  MAX_TTL_MS,
+  validateTtl
+} from "./index-gp63f5x9.js";
+
+// src/memory.ts
+var DEFAULT_MAX_ENTRIES = 1000;
+var DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+var DEFAULT_MAX_NAMESPACES = 128;
+var MAX_BATCH_SIZE = 100;
+var encoder = new TextEncoder;
+function validateLimit(value, fallback) {
+  const limit = value ?? fallback;
+  if (!Number.isSafeInteger(limit) || limit <= 0)
+    throw new CacheError2("invalid-input");
+  return limit;
+}
+function freshGeneration() {
+  return crypto.randomUUID();
+}
+function createMemoryCacheAdapter(options = {}) {
+  const maxEntries = validateLimit(options.maxEntries, DEFAULT_MAX_ENTRIES);
+  const maxBytes = validateLimit(options.maxBytes, DEFAULT_MAX_BYTES);
+  const maxNamespaces = validateLimit(options.maxNamespaces, DEFAULT_MAX_NAMESPACES);
+  const now = options.now ?? Date.now;
+  const namespaces = new Map;
+  const entries = new Map;
+  let bytes = 0;
+  const capabilities = Object.freeze({
+    provider: "memory",
+    sharing: "process",
+    invalidation: "namespace-generation",
+    batch: "per-key"
+  });
+  function composite(namespace, key) {
+    return JSON.stringify([namespace, key]);
+  }
+  function removeEntry(id) {
+    const entry = entries.get(id);
+    if (!entry)
+      return;
+    entries.delete(id);
+    bytes -= entry.bytes;
+  }
+  function evictNamespace(namespace) {
+    const prefix = `[${JSON.stringify(namespace)},`;
+    for (const [id] of entries) {
+      if (id.startsWith(prefix))
+        removeEntry(id);
+    }
+  }
+  function touchNamespace(namespace) {
+    let generation = namespaces.get(namespace);
+    if (generation !== undefined) {
+      namespaces.delete(namespace);
+      namespaces.set(namespace, generation);
+      return generation;
+    }
+    if (namespaces.size >= maxNamespaces) {
+      const oldest = namespaces.keys().next().value;
+      namespaces.delete(oldest);
+      evictNamespace(oldest);
+    }
+    generation = freshGeneration();
+    namespaces.set(namespace, generation);
+    return generation;
+  }
+  return {
+    capabilities,
+    async generation(namespace) {
+      return touchNamespace(namespace);
+    },
+    async getMany(namespace, generation, keys) {
+      if (keys.length > MAX_BATCH_SIZE)
+        throw new CacheError2("invalid-input");
+      const current = namespaces.get(namespace);
+      if (current !== generation)
+        return keys.map(() => null);
+      touchNamespace(namespace);
+      return keys.map((key) => {
+        const id = composite(namespace, key);
+        const entry = entries.get(id);
+        if (!entry || entry.generation !== generation)
+          return null;
+        if (entry.expiresAt <= now()) {
+          removeEntry(id);
+          return null;
+        }
+        entries.delete(id);
+        entries.set(id, entry);
+        return entry.value;
+      });
+    },
+    async set(namespace, generation, key, value, ttlMs) {
+      validateTtl(ttlMs, MAX_TTL_MS);
+      if (ttlMs === 0)
+        throw new CacheError2("invalid-input");
+      if (namespaces.get(namespace) !== generation)
+        return false;
+      touchNamespace(namespace);
+      const id = composite(namespace, key);
+      const size = encoder.encode(namespace).byteLength + encoder.encode(generation).byteLength + encoder.encode(key).byteLength + encoder.encode(value).byteLength;
+      if (size > maxBytes)
+        throw new CacheError2("serialization");
+      removeEntry(id);
+      while (entries.size >= maxEntries || bytes + size > maxBytes) {
+        const oldest = entries.keys().next().value;
+        if (oldest === undefined)
+          break;
+        removeEntry(oldest);
+      }
+      entries.set(id, { generation, value, expiresAt: now() + ttlMs, bytes: size });
+      bytes += size;
+      return true;
+    },
+    async delete(namespace, generation, key) {
+      if (namespaces.get(namespace) !== generation)
+        return;
+      touchNamespace(namespace);
+      removeEntry(composite(namespace, key));
+    },
+    async invalidate(namespace) {
+      if (namespaces.has(namespace))
+        evictNamespace(namespace);
+      namespaces.delete(namespace);
+      touchNamespace(namespace);
+    }
+  };
+}
+export {
+  createMemoryCacheAdapter
+};

package/dist/plugin.d.ts

@@ -0,0 +1,28 @@
+import type { Plugin } from "@lenso/core/plugin";
+import { type ConfigSource } from "@lenso/core/config";
+import { type Cache, type CacheAdapter, type CacheConfig, type JsonValue } from "./index";
+export declare const cacheConfig: import("@lenso/core/config").ConfigContract<{
+    "~standard": {
+        version: 1;
+        vendor: string;
+        types: {
+            input: CacheConfig;
+            output: Readonly<Required<CacheConfig>>;
+        } | undefined;
+        validate(input: unknown): {
+            issues: {
+                message: string;
+            }[];
+            value?: undefined;
+        } | {
+            issues?: undefined;
+            value: Readonly<Required<CacheConfig>>;
+        };
+    };
+}>;
+export declare function createCachePlugin<T extends JsonValue = JsonValue>(options: {
+    id: string;
+    adapter: Plugin<CacheAdapter>;
+    config: CacheConfig | readonly ConfigSource[];
+    validate?: (value: JsonValue) => value is T;
+}): Plugin<Cache<T>>;

package/dist/plugin.js

@@ -0,0 +1,82 @@
+import {
+  createCache2
+} from "./index-pmwehpb3.js";
+import {
+  resolveCacheConfig2
+} from "./index-gp63f5x9.js";
+
+// src/plugin.ts
+import { bindConfig, definePluginConfig } from "@lenso/core/config";
+var schema = {
+  "~standard": {
+    version: 1,
+    vendor: "lenso-cache",
+    types: undefined,
+    validate(input) {
+      try {
+        if (!input || typeof input !== "object" || Array.isArray(input))
+          return { issues: [{ message: "Invalid cache configuration" }] };
+        const allowed = new Set([
+          "namespace",
+          "defaultTtlMs",
+          "maxTtlMs",
+          "maxValueBytes",
+          "maxInFlight",
+          "failureMode"
+        ]);
+        if (Object.keys(input).some((key) => !allowed.has(key)))
+          return { issues: [{ message: "Unknown cache configuration field" }] };
+        return { value: resolveCacheConfig2(input) };
+      } catch {
+        return { issues: [{ message: "Invalid cache configuration" }] };
+      }
+    }
+  }
+};
+var cacheConfig = definePluginConfig({
+  schema,
+  description: "Finite-TTL JSON cache. No authorization decision caching or management exposure.",
+  fields: [
+    { path: ["namespace"], description: "Plugin-owned namespace, not an authorization boundary." },
+    { path: ["defaultTtlMs"], description: "Default TTL in milliseconds. Zero disables storage." },
+    {
+      path: ["failureMode"],
+      description: "Fail closed by default; fail open explicitly bypasses the backend."
+    }
+  ],
+  jsonSchema: () => ({
+    type: "object",
+    additionalProperties: false,
+    required: ["namespace"],
+    properties: {
+      namespace: { type: "string", minLength: 1, maxLength: 256 },
+      defaultTtlMs: { type: "integer", minimum: 0, maximum: 86400000 },
+      maxTtlMs: { type: "integer", minimum: 1, maximum: 86400000 },
+      maxValueBytes: { type: "integer", minimum: 1, maximum: 1048576 },
+      maxInFlight: { type: "integer", minimum: 1, maximum: 1e4 },
+      failureMode: { enum: ["fail-open", "fail-closed"] }
+    }
+  })
+});
+function createCachePlugin(options) {
+  return bindConfig(cacheConfig, options.config, {
+    id: options.id,
+    requires: [options.adapter],
+    setup(context, config) {
+      const cache = createCache2({
+        ...config,
+        adapter: context.get(options.adapter),
+        validate: options.validate,
+        onEvent(event) {
+          context.logger?.warn({ operation: event.operation, reason: event.reason }, "Cache backend bypass or corrupt entry");
+        }
+      });
+      context.onCleanup(() => cache.close());
+      return cache;
+    }
+  });
+}
+export {
+  cacheConfig,
+  createCachePlugin
+};

package/dist/redis.d.ts

@@ -0,0 +1,7 @@
+import type { RedisClient } from "bun";
+import { type CacheAdapter } from "./contracts";
+export interface RedisCacheAdapterOptions {
+    readonly client: RedisClient;
+    readonly prefix?: string;
+}
+export declare function createRedisCacheAdapter({ client, prefix, }: RedisCacheAdapterOptions): CacheAdapter;

package/dist/redis.js

@@ -0,0 +1,152 @@
+import {
+  CacheError2,
+  MAX_TTL_MS,
+  validateTtl
+} from "./index-gp63f5x9.js";
+
+// src/redis.ts
+var DEFAULT_PREFIX = "lenso-cache";
+var MAX_BATCH_SIZE = 100;
+var MAX_PREFIX_LENGTH = 256;
+var SAFE_PREFIX = /^[A-Za-z0-9:_-]+$/;
+var GENERATION_SCRIPT = `
+local generation = redis.call("GET", KEYS[1])
+if not generation then
+  redis.call("SET", KEYS[1], ARGV[1], "NX")
+  generation = redis.call("GET", KEYS[1])
+end
+return generation
+`;
+var READ_SCRIPT = `
+local generation = redis.call("GET", KEYS[1])
+if generation ~= ARGV[1] then
+  return cjson.encode({false})
+end
+local result = {true}
+for i = 2, #KEYS do
+  local value = redis.pcall("GET", KEYS[i])
+  if type(value) == "table" and value.err then
+    result[#result + 1] = {error = true}
+  else
+    result[#result + 1] = value or cjson.null
+  end
+end
+return cjson.encode(result)
+`;
+var SET_SCRIPT = `
+if redis.call("GET", KEYS[1]) ~= ARGV[1] then return 0 end
+redis.call("SET", KEYS[2], ARGV[2], "PX", ARGV[3])
+return 1
+`;
+var DELETE_SCRIPT = `
+if redis.call("GET", KEYS[1]) ~= ARGV[1] then return 0 end
+redis.call("DEL", KEYS[2])
+return 1
+`;
+var INVALIDATE_SCRIPT = `
+redis.call("SET", KEYS[1], ARGV[1])
+return 1
+`;
+function encode(part) {
+  return Buffer.from(part, "utf8").toString("hex");
+}
+function scopeKey(prefix, namespace) {
+  const encoded = encode(namespace);
+  return `${prefix}:scope:${encoded.length}:${encoded}`;
+}
+function dataKey(prefix, namespace, generation, key) {
+  const scope = encode(namespace);
+  const epoch = encode(generation);
+  const item = encode(key);
+  return `${prefix}:data:${scope.length}:${scope}:${epoch.length}:${epoch}:${item.length}:${item}`;
+}
+function uuid() {
+  return crypto.randomUUID();
+}
+function backendError() {
+  return new CacheError2("backend");
+}
+function createRedisCacheAdapter({
+  client,
+  prefix = DEFAULT_PREFIX
+}) {
+  if (typeof prefix !== "string" || prefix.length === 0 || prefix.length > MAX_PREFIX_LENGTH || !SAFE_PREFIX.test(prefix)) {
+    throw new CacheError2("invalid-input");
+  }
+  async function evalScript(script, keys, args) {
+    try {
+      return await client.send("EVAL", [script, String(keys.length), ...keys, ...args]);
+    } catch {
+      throw backendError();
+    }
+  }
+  return {
+    capabilities: {
+      provider: "redis",
+      sharing: "shared",
+      invalidation: "namespace-generation",
+      batch: "per-key"
+    },
+    async generation(namespace) {
+      const value = await evalScript(GENERATION_SCRIPT, [scopeKey(prefix, namespace)], [uuid()]);
+      if (typeof value !== "string")
+        throw backendError();
+      return value;
+    },
+    async getMany(namespace, generation, keys) {
+      if (keys.length > MAX_BATCH_SIZE)
+        throw new CacheError2("invalid-input");
+      if (keys.length === 0)
+        return [];
+      const result = await evalScript(READ_SCRIPT, [
+        scopeKey(prefix, namespace),
+        ...keys.map((key) => dataKey(prefix, namespace, generation, key))
+      ], [generation]);
+      if (typeof result !== "string")
+        throw backendError();
+      let values;
+      try {
+        values = JSON.parse(result);
+      } catch {
+        throw backendError();
+      }
+      if (!Array.isArray(values))
+        throw backendError();
+      if (values[0] !== true) {
+        return keys.map(() => null);
+      }
+      if (values.length !== keys.length + 1)
+        throw backendError();
+      return values.slice(1).map((value) => {
+        if (value === null)
+          return null;
+        if (typeof value === "object" && value !== null && "error" in value && value.error === true) {
+          return backendError();
+        }
+        if (typeof value === "string")
+          return value;
+        throw backendError();
+      });
+    },
+    async set(namespace, generation, key, value, ttlMs) {
+      validateTtl(ttlMs, MAX_TTL_MS);
+      if (ttlMs === 0)
+        throw new CacheError2("invalid-input");
+      const result = await evalScript(SET_SCRIPT, [scopeKey(prefix, namespace), dataKey(prefix, namespace, generation, key)], [generation, value, String(ttlMs)]);
+      if (result === 1 || result === "1")
+        return true;
+      if (result === 0 || result === "0")
+        return false;
+      throw backendError();
+    },
+    async delete(namespace, generation, key) {
+      await evalScript(DELETE_SCRIPT, [scopeKey(prefix, namespace), dataKey(prefix, namespace, generation, key)], [generation]);
+    },
+    async invalidate(namespace) {
+      await evalScript(INVALIDATE_SCRIPT, [scopeKey(prefix, namespace)], [uuid()]);
+    }
+  };
+}
+export {
+  createRedisCacheAdapter
+};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@lenso/cache",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LioRael/lenso.git",
+    "directory": "packages/cache"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./memory": {
+      "types": "./dist/memory.d.ts",
+      "default": "./dist/memory.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "default": "./dist/redis.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts src/memory.ts src/redis.ts src/plugin.ts --outdir dist --target browser --packages external --splitting && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test test"
+  },
+  "devDependencies": {
+    "@lenso/core": "^0.2.1"
+  },
+  "peerDependencies": {
+    "@lenso/core": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@lenso/core": {
+      "optional": true
+    }
+  }
+}