@cat-factory/caching 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @cat-factory/caching
+
+The app-level caching seam (see `docs/initiatives/caching-layer.md` in the repo).
+`createAppCaches(options)` builds the named, typed read-through caches the services
+consume through the kernel `AppCaches` port, implemented on
+[`layered-loader`](https://github.com/kibertoad/layered-loader).
+
+## Design rules
+
+- **In-memory only.** Each cache is a per-replica LRU (`layered-loader` `GroupLoader`
+  over its in-memory tier). A replica always repopulates from its own data source on a
+  miss. There is deliberately **no Redis (or any async) data tier**.
+- **Redis is an invalidation bus, never a data tier.** In a multi-node Node deployment
+  the facade injects a `notificationPairFactory` (built from layered-loader's
+  `createGroupNotificationPair` over dedicated ioredis clients, gated on `REDIS_URL`);
+  a write on one node then broadcasts the invalidated key/group so every peer drops its
+  in-memory entry. Only keys/groups travel on the wire — never values. Absent the
+  factory (single replica, local mode, tests) the loaders are bare in-memory with zero
+  extra dependency.
+- **Invalidate after commit, at every write site.** The consuming service calls
+  `invalidate`/`invalidateGroup` (or the coarse `invalidateAll` for rare wide-blast
+  writes) after the DB write commits; layered-loader publishes to peers automatically.
+- **Staleness probes for git-backed caches.** A profile with `ttlLeftBeforeRefreshInMsecs`
+  turns on preemptive in-memory refresh (layered-loader ≥ 14.5.3): an entry hit inside the
+  window runs the caller's per-read `isStillCurrent` probe (a sha/hash compare, strictly
+  cheaper than the load) in the background — TTL bump when the source hasn't moved, full
+  background reload otherwise. DB-backed invalidation-driven caches leave the window unset:
+  a DB read as a probe saves nothing over the DB read as the load.
+- **Deep imports keep ioredis out of every runtime but Node.** layered-loader's root
+  index eagerly loads its Redis modules (and `ioredis`), so this package deep-imports
+  only the in-memory machinery. The Redis notification classes are loaded dynamically
+  by the Node facade alone, behind `REDIS_URL`.
+
+## The Cloudflare Worker profile (`ISOLATE_SAFE_APP_CACHES_PROFILE`)
+
+A Worker isolate has no cross-isolate invalidation bus and no Redis, so a TTL'd
+in-isolate cache over **mutable cross-instance state** would serve stale data after a
+write processed by another isolate — a correctness bug, not an optimization. The
+Worker therefore wires the isolate-safe profile: caches of mutable state are
+configured **pass-through** (`enabled: false` — every read runs its load), and only
+caches of immutable or self-verifying entries (sha-pinned repo reads, static
+catalogs) get real TTLs. Distributed invalidation is a
+genuine Node-only concern, not a facade-parity gap: the Worker's cross-instance state
+already lives in globally-addressed Durable Objects / D1. Revisit only if a
+per-isolate staleness bug actually surfaces.
+
+`fragmentDocumentBody` is the first self-verifying cache that stays **enabled** on the
+Worker: its entries are external Confluence/Notion/GitHub/… page content re-validated
+by the source's cheap version probe (`ttlLeftBeforeRefreshInMsecs` + `isStillCurrent`),
+so a peer isolate's cached body self-heals within the refresh window without an
+invalidation bus — its staleness is bounded by the probe, exactly like a sha-pinned
+read. Only `fragmentCatalog`, which mirrors our own mutable D1 rows, passes through.
+
+## Named caches
+
+| Cache                  | Value                                           | Group / key                                | Profile                                      |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------ | -------------------------------------------- |
+| `fragmentCatalog`      | merged per-workspace catalog                    | `workspaceId` / `workspaceId`              | TTL + invalidation; pass-through on Worker   |
+| `fragmentDocumentBody` | a document-backed fragment's live external body | `viaWorkspaceId` / `<source>:<externalId>` | TTL + version probe; enabled on both facades |
+
+## Usage
+
+```ts
+import { createAppCaches } from '@cat-factory/caching'
+
+// Node facade (multi-node): inject the Redis-backed notification pair factory.
+const caches = createAppCaches({ notificationPairFactory, logger })
+
+// Cloudflare Worker: the isolate-safe profile.
+const caches = createAppCaches({ profile: ISOLATE_SAFE_APP_CACHES_PROFILE })
+
+// A consuming service reads through its named handle…
+const catalog = await caches.fragmentCatalog.get(key, workspaceId, () => loadCatalog())
+// …and every write path invalidates after commit.
+await caches.fragmentCatalog.invalidateGroup(workspaceId)
+```

package/dist/appCaches.d.ts

@@ -0,0 +1,85 @@
+import type { AppCaches } from '@cat-factory/kernel';
+import type { AbstractNotificationConsumer } from 'layered-loader/dist/lib/notifications/AbstractNotificationConsumer.js';
+import type { GroupNotificationPublisher } from 'layered-loader/dist/lib/notifications/GroupNotificationPublisher.js';
+import type { InMemoryGroupCache } from 'layered-loader/dist/lib/memory/InMemoryGroupCache.js';
+import type { Logger } from 'layered-loader/dist/lib/util/Logger.js';
+/** Per-cache tuning knobs; a facade passes a profile so TTLs can differ per runtime. */
+export interface GroupCacheProfile {
+    /**
+     * `false` ⇒ pass-through: no in-memory tier is built and every read runs its
+     * load. The Worker's isolate-safe stance for caches of MUTABLE cross-instance
+     * state — an isolate has no cross-isolate invalidation bus, so a TTL'd cache
+     * there would serve stale data after a write on another isolate.
+     */
+    enabled: boolean;
+    /** Entry freshness backstop; invalidation, not the TTL, is the coherence story. */
+    ttlInMsecs: number;
+    /** LRU bound on distinct groups (workspaces, typically). */
+    maxGroups: number;
+    /** LRU bound on entries within one group. */
+    maxItemsPerGroup: number;
+    /**
+     * Preemptive-refresh window for git-backed caches (layered-loader ≥ 14.5.3
+     * supports it in-memory-only): an entry hit with less than this much TTL left
+     * refreshes in the background — via the caller's cheap `isStillCurrent` probe
+     * (TTL bump when the source hasn't moved) when one is passed to `get`, else a
+     * full background reload. Unset ⇒ entries simply expire at `ttlInMsecs`
+     * (correct for the invalidation-driven DB-backed caches, where a probe would
+     * cost as much as the load).
+     */
+    ttlLeftBeforeRefreshInMsecs?: number;
+}
+/** One profile entry per named cache in the kernel {@link AppCaches} bag. */
+export interface AppCachesProfile {
+    fragmentCatalog: GroupCacheProfile;
+    fragmentDocumentBody: GroupCacheProfile;
+    repoProjection: GroupCacheProfile;
+}
+/** The default (Node/local/test) profile: caching on, modest bounds. */
+export declare const DEFAULT_APP_CACHES_PROFILE: AppCachesProfile;
+/**
+ * The Cloudflare Worker profile: every cache of mutable cross-instance state is
+ * pass-through, because a Worker isolate has no cross-isolate invalidation bus
+ * (and no Redis) — see the package README. Caches of immutable or self-verifying
+ * entries (sha-pinned reads, static catalogs) may enable real TTLs here.
+ *
+ * `fragmentDocumentBody` stays ENABLED here: its entries are external page content
+ * re-validated by a cheap version probe, so a peer isolate's cached body self-heals
+ * within the refresh window without an invalidation bus (the same reasoning that
+ * lets sha-pinned reads keep a TTL on the Worker) — its staleness is bounded by the
+ * probe, not indefinite. Only `fragmentCatalog`, which mirrors our own mutable D1
+ * state, must pass through.
+ */
+export declare const ISOLATE_SAFE_APP_CACHES_PROFILE: AppCachesProfile;
+/**
+ * A per-cache invalidation-notification pair (layered-loader's group publisher +
+ * consumer). Produced by the facade's factory — Redis-backed in a multi-node Node
+ * deployment, a fake sharing an in-memory bus in tests.
+ */
+export interface GroupCacheNotifications<T> {
+    publisher: GroupNotificationPublisher<T>;
+    consumer: AbstractNotificationConsumer<T, InMemoryGroupCache<T>>;
+}
+/**
+ * Builds the notification pair for one named cache (each cache gets its own
+ * channel, `<prefix>:<cacheName>`). Returning `undefined` leaves that cache bare
+ * in-memory. The factory is per-CACHE so a facade can wire dedicated clients per
+ * channel — layered-loader closes a pair's clients with its loader.
+ */
+export type GroupNotificationPairFactory = <T>(cacheName: string) => GroupCacheNotifications<T> | undefined;
+export interface CreateAppCachesOptions {
+    /** Per-cache overrides merged over {@link DEFAULT_APP_CACHES_PROFILE}. */
+    profile?: Partial<AppCachesProfile>;
+    /** Absent ⇒ bare in-memory loaders (single replica, local mode, tests). */
+    notificationPairFactory?: GroupNotificationPairFactory;
+    /** Error sink for background cache/notification failures (a pino logger fits). */
+    logger?: Logger;
+}
+/**
+ * Build the app-owned cache bag. Called once per process by a facade's
+ * composition root and threaded through the dependency bag as the kernel
+ * {@link AppCaches} port; `createCore` builds a bare default when a harness
+ * passes none.
+ */
+export declare function createAppCaches(options?: CreateAppCachesOptions): AppCaches;
+//# sourceMappingURL=appCaches.d.ts.map

package/dist/appCaches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appCaches.d.ts","sourceRoot":"","sources":["../src/appCaches.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAKV,MAAM,qBAAqB,CAAA;AAM5B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uEAAuE,CAAA;AACzH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qEAAqE,CAAA;AACrH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sDAAsD,CAAA;AAC9F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wCAAwC,CAAA;AAUpE,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;;;OAQG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAA;CACrC;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,iBAAiB,CAAA;IAClC,oBAAoB,EAAE,iBAAiB,CAAA;IACvC,cAAc,EAAE,iBAAiB,CAAA;CAClC;AAED,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,EAAE,gBAmBxC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,+BAA+B,EAAE,gBAQ7C,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,SAAS,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAA;IACxC,QAAQ,EAAE,4BAA4B,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAA;CACjE;AAED;;;;;GAKG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,EAC3C,SAAS,EAAE,MAAM,KACd,uBAAuB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAE3C,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACnC,2EAA2E;IAC3E,uBAAuB,CAAC,EAAE,4BAA4B,CAAA;IACtD,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAqGD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CA6B/E"}

package/dist/appCaches.js

@@ -0,0 +1,147 @@
+// Deep imports on purpose: layered-loader's root index eagerly requires its Redis
+// modules (and thereby `ioredis`), which must never load outside the Node facade's
+// REDIS_URL-gated notification wiring — the Worker imports this package too. The
+// non-Redis modules below pull in only in-memory machinery.
+import { GroupLoader } from 'layered-loader/dist/lib/GroupLoader.js';
+/** The default (Node/local/test) profile: caching on, modest bounds. */
+export const DEFAULT_APP_CACHES_PROFILE = {
+    // One merged catalog per workspace; the key varies only when the workspace's
+    // account changes, so a small per-group bound is plenty.
+    fragmentCatalog: { enabled: true, ttlInMsecs: 5 * 60_000, maxGroups: 500, maxItemsPerGroup: 4 },
+    // The live external body of a document-backed fragment, grouped by workspace and
+    // keyed per document. Self-verifying: an entry entering the last minute of its TTL
+    // runs the source's cheap version probe (bump on unchanged, background reload on
+    // change) so a run never blocks on a live page fetch.
+    fragmentDocumentBody: {
+        enabled: true,
+        ttlInMsecs: 5 * 60_000,
+        maxGroups: 500,
+        maxItemsPerGroup: 64,
+        ttlLeftBeforeRefreshInMsecs: 60_000,
+    },
+    // One repo-projection list per workspace, keyed by workspace id (so exactly one
+    // entry per group). Invalidation-driven — no version probe (a DB read as the probe
+    // would cost as much as the DB read as the load).
+    repoProjection: { enabled: true, ttlInMsecs: 5 * 60_000, maxGroups: 1000, maxItemsPerGroup: 1 },
+};
+/**
+ * The Cloudflare Worker profile: every cache of mutable cross-instance state is
+ * pass-through, because a Worker isolate has no cross-isolate invalidation bus
+ * (and no Redis) — see the package README. Caches of immutable or self-verifying
+ * entries (sha-pinned reads, static catalogs) may enable real TTLs here.
+ *
+ * `fragmentDocumentBody` stays ENABLED here: its entries are external page content
+ * re-validated by a cheap version probe, so a peer isolate's cached body self-heals
+ * within the refresh window without an invalidation bus (the same reasoning that
+ * lets sha-pinned reads keep a TTL on the Worker) — its staleness is bounded by the
+ * probe, not indefinite. Only `fragmentCatalog`, which mirrors our own mutable D1
+ * state, must pass through.
+ */
+export const ISOLATE_SAFE_APP_CACHES_PROFILE = {
+    fragmentCatalog: { ...DEFAULT_APP_CACHES_PROFILE.fragmentCatalog, enabled: false },
+    fragmentDocumentBody: { ...DEFAULT_APP_CACHES_PROFILE.fragmentDocumentBody },
+    // Pass-through: the repo projection is our own mutable D1 state, and a Worker
+    // isolate has no cross-isolate invalidation bus (unlike `fragmentDocumentBody`,
+    // whose external entries self-verify via a version probe). So the Worker reads it
+    // live every time, exactly like `fragmentCatalog`.
+    repoProjection: { ...DEFAULT_APP_CACHES_PROFILE.repoProjection, enabled: false },
+};
+class LayeredGroupCacheHandle {
+    loader;
+    constructor(name, profile, notifications, logger) {
+        this.loader = new GroupLoader({
+            inMemoryCache: profile.enabled
+                ? {
+                    cacheId: name,
+                    cacheType: 'lru-object',
+                    groupCacheType: 'lru-object',
+                    ttlInMsecs: profile.ttlInMsecs,
+                    maxGroups: profile.maxGroups,
+                    maxItemsPerGroup: profile.maxItemsPerGroup,
+                    ...(profile.ttlLeftBeforeRefreshInMsecs
+                        ? { ttlLeftBeforeRefreshInMsecs: profile.ttlLeftBeforeRefreshInMsecs }
+                        : {}),
+                }
+                : false,
+            // The read-through source: each `get` carries its own load closure, so the
+            // owning service keeps its load logic and the loader keeps in-flight dedup.
+            dataSources: [
+                {
+                    name: `${name}-load`,
+                    getFromGroup: (params) => params.load(),
+                    getManyFromGroup: () => Promise.reject(new Error(`cache '${name}' does not support getMany`)),
+                },
+            ],
+            cacheKeyFromLoadParamsResolver: (params) => params.key,
+            // The staleness probe rides the per-read load params, like the load itself.
+            // Wired only when the profile configures a refresh window (layered-loader
+            // rejects a probe with no window to fire in); a read that passed no probe
+            // reports stale, degrading to the default full background reload. A null
+            // cached value (resolved-but-empty) is re-loaded rather than probed.
+            ...(profile.enabled && profile.ttlLeftBeforeRefreshInMsecs
+                ? {
+                    isEntryStillCurrentFn: (cached, params) => cached !== null && params.isStillCurrent
+                        ? params.isStillCurrent(cached)
+                        : Promise.resolve(false),
+                }
+                : {}),
+            // A notification pair only makes sense with an in-memory tier to invalidate
+            // (layered-loader rejects the combination outright).
+            ...(profile.enabled && notifications
+                ? {
+                    notificationConsumer: notifications.consumer,
+                    notificationPublisher: notifications.publisher,
+                }
+                : {}),
+            ...(logger ? { logger } : {}),
+        });
+    }
+    async get(key, group, load, isStillCurrent) {
+        // The data source always resolves to the load's result, and load errors
+        // propagate (throwIfLoadError defaults on) — so a non-value here is impossible
+        // unless T itself includes null.
+        return (await this.loader.get({ key, load, isStillCurrent }, group));
+    }
+    invalidate(key, group) {
+        return this.loader.invalidateCacheFor(key, group);
+    }
+    invalidateGroup(group) {
+        return this.loader.invalidateCacheForGroup(group);
+    }
+    invalidateAll() {
+        return this.loader.invalidateCache();
+    }
+    /** Releases the notification pair's resources along with the loader. */
+    close() {
+        return this.loader.close();
+    }
+}
+/**
+ * Build the app-owned cache bag. Called once per process by a facade's
+ * composition root and threaded through the dependency bag as the kernel
+ * {@link AppCaches} port; `createCore` builds a bare default when a harness
+ * passes none.
+ */
+export function createAppCaches(options = {}) {
+    const profile = { ...DEFAULT_APP_CACHES_PROFILE, ...options.profile };
+    const fragmentCatalog = buildGroupCache('fragment-catalog', profile.fragmentCatalog, options);
+    const fragmentDocumentBody = buildGroupCache('fragment-document-body', profile.fragmentDocumentBody, options);
+    const repoProjection = buildGroupCache('repo-projection', profile.repoProjection, options);
+    return {
+        fragmentCatalog,
+        fragmentDocumentBody,
+        repoProjection,
+        close: async () => {
+            await Promise.all([
+                fragmentCatalog.close(),
+                fragmentDocumentBody.close(),
+                repoProjection.close(),
+            ]);
+        },
+    };
+}
+function buildGroupCache(name, profile, options) {
+    const notifications = profile.enabled ? options.notificationPairFactory?.(name) : undefined;
+    return new LayeredGroupCacheHandle(name, profile, notifications, options.logger);
+}
+//# sourceMappingURL=appCaches.js.map

package/dist/appCaches.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createAppCaches, DEFAULT_APP_CACHES_PROFILE, ISOLATE_SAFE_APP_CACHES_PROFILE, } from './appCaches.js';
+export type { AppCachesProfile, CreateAppCachesOptions, GroupCacheNotifications, GroupCacheProfile, GroupNotificationPairFactory, } from './appCaches.js';
+//# 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,OAAO,EACL,eAAe,EACf,0BAA0B,EAC1B,+BAA+B,GAChC,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createAppCaches, DEFAULT_APP_CACHES_PROFILE, ISOLATE_SAFE_APP_CACHES_PROFILE, } from './appCaches.js';
+//# 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,OAAO,EACL,eAAe,EACf,0BAA0B,EAC1B,+BAA+B,GAChC,MAAM,gBAAgB,CAAA"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cat-factory/caching",
+  "version": "0.4.0",
+  "description": "The app-level caching seam for the Agent Architecture Board (docs/initiatives/caching-layer.md): createAppCaches builds the named, typed in-memory read-through caches (layered-loader) the services consume via the kernel AppCaches port, with optional distributed invalidation over an injected Redis notification pair. Redis is only ever an invalidation bus, never a data tier.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kibertoad/cat-factory.git",
+    "directory": "backend/packages/caching"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "layered-loader": "^14.5.3",
+    "@cat-factory/kernel": "0.85.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "7.0.1-rc",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}