@ultimat3/cache 1.0.0

package/src/purge-fastly.ts

@@ -0,0 +1,119 @@
+// Single responsibility: Fastly's surrogate-key purge. One `POST /service/<id>/purge` per batch
+// of keys, one `POST /service/<id>/purge_all` for the whole service — no SDK, `fetch` is the whole
+// client. The keys are Ultimate's wire tags unchanged (`post`, `post:1`), which is the property
+// that keeps an edge purge and an app-level invalidation from ever meaning different things.
+
+import type { PurgeDriver } from './cdn';
+import { CachePurgeFailedError } from './errors';
+import type { PurgeFetch } from './purge-http';
+import {
+  assertPurgeableKeys,
+  chunked,
+  DEFAULT_PURGE_TIMEOUT_MS,
+  defaultPurgeFetch,
+  detailFrom,
+  isRecord,
+  isRetryableStatus,
+  type PurgeBody,
+  purgeBody,
+  purgePost,
+  requireCredential,
+} from './purge-http';
+
+export const FASTLY_API_URL = 'https://api.fastly.com';
+
+/** Fastly accepts 256 surrogate keys in one batch purge; more is a second request, not a refusal. */
+export const FASTLY_MAX_KEYS_PER_REQUEST = 256;
+
+export interface FastlyPurgeOptions {
+  /** Read from `FASTLY_API_TOKEN`. A literal token in app.config.ts is a token in git. */
+  readonly apiToken: string;
+  /** Read from `FASTLY_SERVICE_ID` — which service this deployment fronts. */
+  readonly serviceId: string;
+  /** Override for a proxy or a test double. Defaults to `FASTLY_API_URL`. */
+  readonly baseUrl?: string | undefined;
+  readonly timeoutMs?: number | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: PurgeFetch | undefined;
+}
+
+// Every branch names the env key to edit or a command to run. "raise the rate limit, or bust fewer
+// tags" was the one that named neither: Fastly answers every API call with `Fastly-RateLimit-*`,
+// so the remaining budget and its reset are readable — which is the half an agent can act on.
+const fixFor = (status: number): string => {
+  if (status === 401 || status === 403) {
+    return 'set FASTLY_API_TOKEN in .env.production to a token with the purge scope from https://manage.fastly.com/account/personal/tokens';
+  }
+  if (status === 404) {
+    return 'set FASTLY_SERVICE_ID in .env.production to the id at https://manage.fastly.com/configure/services';
+  }
+  if (status === 429) {
+    return 'curl -sS -D - -o /dev/null -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID | grep -i fastly-ratelimit';
+  }
+  return 'curl -sS -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID';
+};
+
+/**
+ * Fastly answers a batch purge with `{ "<key>": "<purge id>" }`, and a single-key purge with
+ * `{ "status": "ok", "id": … }`. Only the first shape names keys, so anything else is read as
+ * "the whole batch was accepted" — which a 2xx already means.
+ */
+function acceptedFrom(body: PurgeBody, batch: readonly string[]): string[] {
+  const payload = body.json;
+  if (!isRecord(payload)) return [...batch];
+  const named = batch.filter((key) => key in payload);
+  return named.length > 0 ? named : [...batch];
+}
+
+export function fastlyPurgeDriver(options: FastlyPurgeOptions): PurgeDriver {
+  const apiToken = requireCredential(options.apiToken, 'FASTLY_API_TOKEN', 'fastly');
+  const serviceId = requireCredential(options.serviceId, 'FASTLY_SERVICE_ID', 'fastly');
+  const baseUrl = options.baseUrl ?? FASTLY_API_URL;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_PURGE_TIMEOUT_MS;
+  const doFetch = options.fetch ?? defaultPurgeFetch;
+  const headers = { 'Fastly-Key': apiToken };
+
+  const post = (path: string, body: unknown): Promise<Response> =>
+    purgePost({
+      driver: 'fastly',
+      url: `${baseUrl}/service/${serviceId}${path}`,
+      headers,
+      body,
+      fetch: doFetch,
+      timeoutMs,
+    });
+
+  /** The body is read here whether or not the call failed, because a `Response` gives it up once. */
+  const settle = async (response: Response): Promise<PurgeBody> => {
+    const body = await purgeBody(response);
+    if (response.ok) return body;
+    throw new CachePurgeFailedError({
+      driver: 'fastly',
+      detail: detailFrom(body),
+      status: response.status,
+      retryable: isRetryableStatus(response.status),
+      fix: fixFor(response.status),
+    });
+  };
+
+  return {
+    name: 'fastly',
+
+    async purge(keys: readonly string[]): Promise<readonly string[]> {
+      if (keys.length === 0) return [];
+      assertPurgeableKeys('fastly', keys);
+      const accepted: string[] = [];
+      // Sequential on purpose: a bust of thousands of keys must not open thousands of sockets
+      // against an API that rate-limits, and nothing downstream reads a purge before it lands.
+      for (const batch of chunked('fastly', keys, FASTLY_MAX_KEYS_PER_REQUEST)) {
+        const body = await settle(await post('/purge', { surrogate_keys: batch }));
+        accepted.push(...acceptedFrom(body, batch));
+      }
+      return accepted;
+    },
+
+    async purgeAll(): Promise<void> {
+      await settle(await post('/purge_all', {}));
+    },
+  };
+}

package/src/purge-http.ts

@@ -0,0 +1,163 @@
+// Single responsibility: the HTTP half both remote purge drivers share — one POST with a
+// deadline, the status → retryable table, and the batching a provider's per-request key cap
+// forces. Kept apart from the drivers because "which failure can succeed unchanged" is one
+// judgement, and two copies of it would drift into two answers for the same 429.
+
+import { CacheDriverUnavailableError, CachePurgeFailedError } from './errors';
+
+/** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
+export type PurgeFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+/** A purge is behind the write, not in front of it: a slow CDN must not hold the fan-out open. */
+export const DEFAULT_PURGE_TIMEOUT_MS = 10_000;
+
+const MAX_DETAIL_LENGTH = 200;
+
+// A 4xx here means the same request, unchanged, might land: a throttle or a momentary conflict.
+// Every other 4xx is a credential or a plan, which no retry fixes.
+const RETRYABLE_STATUSES = new Set([408, 409, 425, 429]);
+
+export const isRetryableStatus = (status: number): boolean =>
+  status >= 500 || RETRYABLE_STATUSES.has(status);
+
+/**
+ * A bare reference to `globalThis.fetch` risks "Illegal invocation" on some hosts; closing over
+ * the call keeps it detached from any receiver, in production and in tests alike.
+ */
+export const defaultPurgeFetch: PurgeFetch = (input, init) => globalThis.fetch(input, init);
+
+/**
+ * Providers cap keys per request. A bust of 300 tags is still one purge — several requests.
+ *
+ * The size is refused before the loop, not trusted: a `0` or a negative never advances `index`, so
+ * the fan-out hangs holding the write's invalidation open, and a `NaN` ends the loop after one pass
+ * that slices to nothing — an empty key list posted to a CDN that answers 200 and clears nothing.
+ * `X_CACHE_DRIVER_UNAVAILABLE` rather than `X_CACHE_PURGE_FAILED`: the only sizes this ever sees
+ * are the drivers' own caps, so a bad one is this package miswired, and no CDN refused anything.
+ */
+export function chunked<T>(
+  driver: string,
+  values: readonly T[],
+  size: number,
+): readonly (readonly T[])[] {
+  if (!Number.isSafeInteger(size) || size < 1) {
+    throw new CacheDriverUnavailableError({
+      driver,
+      cause: `batch size ${String(size)} is not a positive integer, so ${values.length} keys cannot be split into requests`,
+      fix: 'pass a positive integer batch size to chunked(), as FASTLY_MAX_KEYS_PER_REQUEST does',
+    });
+  }
+  const batches: T[][] = [];
+  for (let index = 0; index < values.length; index += size) {
+    batches.push(values.slice(index, index + size));
+  }
+  return batches;
+}
+
+/**
+ * A credential the driver cannot run without, refused at construction — where the env key is
+ * still nameable — rather than on the first purge nobody watches. "no CDN token" is what
+ * `X_CACHE_DRIVER_UNAVAILABLE` already means, so this is that code and not a second one.
+ */
+export function requireCredential(value: string, envKey: string, driver: string): string {
+  if (value.trim() !== '') return value.trim();
+  throw new CacheDriverUnavailableError({
+    driver,
+    cause: `${envKey} is unset, so the ${driver} purge driver has no credential`,
+    fix: `set ${envKey} in .env.production, or use noopPurgeDriver() to purge nothing`,
+  });
+}
+
+// Every CDN splits a key list on whitespace or a comma, so a key carrying either purges two
+// things that do not exist instead of the one that does — silently, since the request succeeds.
+const UNSAFE_KEY = /[\s,]/;
+const MAX_KEY_LENGTH = 1024;
+
+const keyProblem = (key: string): string | undefined => {
+  if (key === '') return 'is empty';
+  if (UNSAFE_KEY.test(key))
+    return 'contains whitespace or a comma, which a CDN reads as a separator';
+  if (key.length > MAX_KEY_LENGTH)
+    return `is ${key.length} characters, over the 1024-byte key limit`;
+  return undefined;
+};
+
+/**
+ * Refused before the request, not after: a malformed key comes back as an accepted purge that
+ * cleared nothing, which is the one CDN failure no later read can catch.
+ */
+export function assertPurgeableKeys(driver: string, keys: readonly string[]): void {
+  for (const key of keys) {
+    const problem = keyProblem(key);
+    if (problem === undefined) continue;
+    throw new CachePurgeFailedError({
+      driver,
+      detail: `surrogate key ${JSON.stringify(key)} ${problem}`,
+      retryable: false,
+      fix: 'rename the tag in its declareTags(...) call so the key carries no space or comma',
+    });
+  }
+}
+
+export interface PurgeBody {
+  readonly text: string;
+  /** `undefined` when the provider sent something that is not JSON — an html error page, or nothing. */
+  readonly json: unknown;
+}
+
+/**
+ * The body, read exactly once. A `Response` streams: `json()` followed by `text()` throws "Body
+ * already used", so the failure path would lose the very message it exists to report.
+ */
+export async function purgeBody(response: Response): Promise<PurgeBody> {
+  const text = await response.text().catch(() => '');
+  try {
+    return { text, json: JSON.parse(text) as unknown };
+  } catch {
+    return { text, json: undefined };
+  }
+}
+
+/** Raw text, capped so a provider's error page cannot flood a log line. */
+export function detailFrom(body: PurgeBody): string {
+  if (body.text === '') return 'the response body was empty';
+  return body.text.length > MAX_DETAIL_LENGTH
+    ? `${body.text.slice(0, MAX_DETAIL_LENGTH)}…`
+    : body.text;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export interface PurgePostInput {
+  readonly driver: string;
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: unknown;
+  readonly fetch: PurgeFetch;
+  readonly timeoutMs: number;
+}
+
+/**
+ * One POST, with the transport failure already translated. A request that never got a status —
+ * DNS, TLS, a reset, the deadline — is retryable by definition: nothing at the edge has seen it.
+ */
+export async function purgePost(input: PurgePostInput): Promise<Response> {
+  try {
+    return await input.fetch(input.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', ...input.headers },
+      body: JSON.stringify(input.body),
+      signal: AbortSignal.timeout(input.timeoutMs),
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : 'the request failed before a response';
+    throw new CachePurgeFailedError({
+      driver: input.driver,
+      detail: `${reason} — nothing left this host for ${input.url} (egress, DNS or TLS)`,
+      retryable: true,
+      fix: `curl -sS -m 5 -o /dev/null ${input.url}`,
+    });
+  }
+}

package/src/redis.ts

@@ -0,0 +1,131 @@
+// Tier 2: shared cache over `Bun.redis` (no client dependency — the runtime ships one).
+// A tag -> keys SET is maintained alongside every write so `invalidateTags` is ONE round
+// trip via a server-side script, not a KEYS scan. KEYS is O(n) and blocks the server; a
+// framework that ships it as the invalidation path is shipping an outage.
+
+import { logger } from '@ultimat3/core';
+import { CacheDriverUnavailableError } from './errors';
+import type { CacheTag } from './tags';
+import { parseTag, serializeTag } from './tags';
+import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
+
+/** The slice of Bun's Redis client this tier uses. Narrow on purpose: easy to fake in tests. */
+export interface RedisLike {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<unknown>;
+  send(command: string, args: string[]): Promise<unknown>;
+}
+
+export interface RedisTierOptions {
+  /** Key namespace, so two apps can share one Redis without colliding. Default `x`. */
+  readonly prefix?: string;
+  readonly defaultTtlMs?: number;
+  /** Injected in tests; production reads `Bun.redis`. */
+  readonly client?: RedisLike;
+}
+
+interface StoredEntry {
+  readonly v: unknown;
+  readonly t: readonly string[];
+}
+
+/**
+ * Drop the value keys, then drop the tag sets themselves. `SMEMBERS` + `DEL` in one EVAL is
+ * atomic and single-trip; doing it client-side would race a concurrent write.
+ */
+const INVALIDATE_SCRIPT = `
+local removed = {}
+for i, tagKey in ipairs(KEYS) do
+  local members = redis.call('SMEMBERS', tagKey)
+  for _, key in ipairs(members) do
+    redis.call('DEL', key)
+    table.insert(removed, key)
+  end
+  redis.call('DEL', tagKey)
+end
+return removed
+`.trim();
+
+function resolveClient(injected: RedisLike | undefined): RedisLike {
+  if (injected !== undefined) return injected;
+  const candidate = (Bun as unknown as { redis?: RedisLike }).redis;
+  if (candidate === undefined || typeof candidate.send !== 'function') {
+    throw new CacheDriverUnavailableError({
+      driver: 'redis',
+      cause: 'Bun.redis is not available (needs bun >= 1.3 and REDIS_URL)',
+      fix: 'set REDIS_URL in .env, or drop the redis tier from cache.tiers in app.config.ts',
+    });
+  }
+  return candidate;
+}
+
+const toStrings = (value: unknown): string[] =>
+  Array.isArray(value) ? value.map((item) => String(item)) : [];
+
+export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
+  const prefix = options.prefix ?? 'x';
+  const defaultTtlMs = options.defaultTtlMs ?? 300_000;
+  let client: RedisLike | undefined;
+
+  const conn = (): RedisLike => {
+    client ??= resolveClient(options.client);
+    return client;
+  };
+
+  const valueKey = (key: string): string => `${prefix}:c:${key}`;
+  const tagKey = (wire: string): string => `${prefix}:t:${wire}`;
+  // A row write must also appear in the collection's tag set, or list caches survive it.
+  const tagKeysFor = (owned: CacheTag): string[] =>
+    owned.id === undefined
+      ? [tagKey(owned.entity)]
+      : [tagKey(serializeTag(owned)), tagKey(owned.entity)];
+
+  return {
+    name: 'redis',
+
+    async get<T>(key: string): Promise<CacheEntry<T> | undefined> {
+      const raw = await conn().get(valueKey(key));
+      if (raw === null) return undefined;
+      try {
+        const parsed = JSON.parse(raw) as StoredEntry;
+        return { value: parsed.v as T, tags: parsed.t.map(parseTag) };
+      } catch {
+        // A poisoned value is a miss, never a 500. Redis TTL will reap it.
+        logger.warn('cache.redis.corrupt-entry', { key });
+        return undefined;
+      }
+    },
+
+    async set<T>(key: string, value: T, setOptions?: CacheSetOptions): Promise<void> {
+      const tags = setOptions?.tags ?? [];
+      const ttlMs = setOptions?.ttlMs ?? defaultTtlMs;
+      const payload: StoredEntry = { v: value, t: tags.map(serializeTag) };
+      const stored = valueKey(key);
+      const ttlSeconds = Math.max(1, Math.ceil(ttlMs / 1000));
+      await conn().send('SET', [stored, JSON.stringify(payload), 'EX', String(ttlSeconds)]);
+      for (const owned of tags) {
+        for (const bucket of tagKeysFor(owned)) {
+          await conn().send('SADD', [bucket, stored]);
+        }
+      }
+    },
+
+    async del(key: string): Promise<void> {
+      await conn().send('DEL', [valueKey(key)]);
+    },
+
+    async invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
+      const buckets = [...new Set(tags.flatMap(tagKeysFor))];
+      if (buckets.length === 0) return { tier: 'redis', keys: [] };
+      const result = await conn().send('EVAL', [
+        INVALIDATE_SCRIPT,
+        String(buckets.length),
+        ...buckets,
+      ]);
+      const stripped = toStrings(result).map((key) => key.slice(`${prefix}:c:`.length));
+      return { tier: 'redis', keys: stripped };
+    },
+  };
+}
+
+export const REDIS_INVALIDATE_SCRIPT = INVALIDATE_SCRIPT;

package/src/semantic.ts

@@ -0,0 +1,146 @@
+// The semantic cache for LLM calls: a near-duplicate prompt should not pay for a second
+// completion. Keyed by embedding, matched by cosine similarity above a threshold — exact
+// string keys miss on "list my orders" vs "show me my orders", which is most of the traffic.
+// The in-memory default is correct but O(n); pgvector is the production backing (an ivfflat
+// index over `x_semantic_cache.embedding`), which is why the interface is a driver.
+
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import type { CacheTag } from './tags';
+import { tagsIntersect } from './tags';
+import { nowMs } from './tiers';
+
+export type Embedding = readonly number[];
+
+export interface SemanticHit<T> {
+  readonly value: T;
+  readonly similarity: number;
+  readonly key: string;
+}
+
+export interface SemanticRememberOptions {
+  readonly ttlMs?: number;
+  readonly tags?: readonly CacheTag[];
+}
+
+export interface SemanticCache {
+  readonly name: string;
+  /** Nearest neighbour above `threshold`, or `undefined`. */
+  lookup<T>(embedding: Embedding, threshold?: number): Promise<SemanticHit<T> | undefined>;
+  remember<T>(
+    key: string,
+    embedding: Embedding,
+    value: T,
+    options?: SemanticRememberOptions,
+  ): Promise<void>;
+  invalidateTags(tags: readonly CacheTag[]): Promise<readonly string[]>;
+  size(): Promise<number>;
+}
+
+export interface SemanticCacheOptions {
+  /**
+   * Default 0.92. Below ~0.9 unrelated prompts start colliding and the cache answers the
+   * wrong question — a worse failure than a cache miss, so the default is deliberately tight.
+   */
+  readonly threshold?: number;
+  readonly maxEntries?: number;
+  readonly defaultTtlMs?: number;
+  readonly clock?: Clock;
+}
+
+export function cosineSimilarity(a: Embedding, b: Embedding): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    dot += x * y;
+    normA += x * x;
+    normB += y * y;
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+interface SemanticRecord {
+  readonly key: string;
+  readonly embedding: Embedding;
+  readonly value: unknown;
+  readonly expiresAt: number;
+  readonly tags: readonly CacheTag[];
+}
+
+export function createMemorySemanticCache(options: SemanticCacheOptions = {}): SemanticCache {
+  const threshold = options.threshold ?? 0.92;
+  const maxEntries = options.maxEntries ?? 1000;
+  const defaultTtlMs = options.defaultTtlMs ?? 3_600_000;
+  const clock = options.clock ?? systemClock;
+  const records = new Map<string, SemanticRecord>();
+
+  const live = (): SemanticRecord[] => {
+    const at = nowMs(clock);
+    const out: SemanticRecord[] = [];
+    for (const [key, record] of records) {
+      if (record.expiresAt <= at) records.delete(key);
+      else out.push(record);
+    }
+    return out;
+  };
+
+  return {
+    name: 'memory',
+
+    lookup<T>(embedding: Embedding, override?: number): Promise<SemanticHit<T> | undefined> {
+      const floor = override ?? threshold;
+      let best: SemanticHit<T> | undefined;
+      for (const record of live()) {
+        const similarity = cosineSimilarity(embedding, record.embedding);
+        if (similarity < floor) continue;
+        if (best === undefined || similarity > best.similarity) {
+          best = { value: record.value as T, similarity, key: record.key };
+        }
+      }
+      return Promise.resolve(best);
+    },
+
+    remember<T>(
+      key: string,
+      embedding: Embedding,
+      value: T,
+      rememberOptions?: SemanticRememberOptions,
+    ): Promise<void> {
+      records.delete(key);
+      records.set(key, {
+        key,
+        embedding,
+        value,
+        expiresAt: nowMs(clock) + (rememberOptions?.ttlMs ?? defaultTtlMs),
+        tags: rememberOptions?.tags ?? [],
+      });
+      // Insertion-ordered Map: the oldest key is the first one.
+      while (records.size > maxEntries) {
+        const oldest = records.keys().next();
+        if (oldest.done === true) break;
+        records.delete(oldest.value);
+      }
+      return Promise.resolve();
+    },
+
+    invalidateTags(tags: readonly CacheTag[]): Promise<readonly string[]> {
+      const removed: string[] = [];
+      for (const [key, record] of records) {
+        if (tagsIntersect(tags, record.tags)) {
+          records.delete(key);
+          removed.push(key);
+        }
+      }
+      return Promise.resolve(removed);
+    },
+
+    size(): Promise<number> {
+      return Promise.resolve(live().length);
+    },
+  };
+}

package/src/tags.ts

@@ -0,0 +1,110 @@
+// Tags are the ONLY invalidation currency in Ultimate: actions declare `invalidates`,
+// routes declare `revalidate.tags`, and every tier speaks the same strings. No tier ever
+// invents its own key convention, so there is nothing for an agent to keep in sync.
+
+import { CacheTagUnknownError } from './errors';
+
+/** An entity-scoped tag. `{ entity: 'post' }` covers the collection, `+ id` a single row. */
+export interface CacheTag<E extends string = string> {
+  readonly entity: E;
+  readonly id?: string;
+}
+
+/**
+ * Apps augment this interface (generated by `x manifest` from their entities) to get
+ * `tag.post` typed and `tag.pots` as a build error:
+ *
+ * declare module '@ultimat3/cache' {
+ *   interface CacheTagRegistry { post: true; feed: true }
+ * }
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmentation target, filled by generated code
+export interface CacheTagRegistry {}
+
+type TagAccessors = { readonly [K in keyof CacheTagRegistry & string]: CacheTag<K> };
+
+export type TagFactory = TagAccessors & (<E extends string>(entity: E, id?: string) => CacheTag<E>);
+
+const makeTag = <E extends string>(entity: E, id?: string): CacheTag<E> =>
+  id === undefined ? { entity } : { entity, id };
+
+/**
+ * `tag('post', id)` for a row, `tag.post` for the collection. The property form is a Proxy
+ * so generated registry augmentations need no runtime codegen.
+ */
+export const tag: TagFactory = new Proxy(makeTag, {
+  get(target, prop, receiver): unknown {
+    if (typeof prop === 'string') return makeTag(prop);
+    return Reflect.get(target, prop, receiver);
+  },
+}) as unknown as TagFactory;
+
+/** Wire form: `post` for a collection, `post:<id>` for a row. Stable across tiers. */
+export function serializeTag(value: CacheTag): string {
+  return value.id === undefined ? value.entity : `${value.entity}:${value.id}`;
+}
+
+export function parseTag(wire: string): CacheTag {
+  const split = wire.indexOf(':');
+  if (split === -1) return { entity: wire };
+  return { entity: wire.slice(0, split), id: wire.slice(split + 1) };
+}
+
+export function serializeTags(tags: readonly CacheTag[]): string[] {
+  return tags.map(serializeTag);
+}
+
+/**
+ * Every tag a row participates in: its collection and its own identity. A row write
+ * therefore busts list caches and detail caches with one call.
+ */
+export function tagsFor(
+  entity: { readonly name: string },
+  row: { readonly id: string },
+): readonly CacheTag[] {
+  return [makeTag(entity.name), makeTag(entity.name, row.id)];
+}
+
+/**
+ * Invalidation is deliberately asymmetric-tolerant: busting a collection (`post`) must kill
+ * cached rows, and busting a row (`post:1`) must kill the lists that contained it. Anything
+ * narrower leaves an agent hunting a stale list it never thought to tag.
+ */
+export function tagMatches(requested: CacheTag, owned: CacheTag): boolean {
+  if (requested.entity !== owned.entity) return false;
+  if (requested.id === undefined || owned.id === undefined) return true;
+  return requested.id === owned.id;
+}
+
+export function tagsIntersect(requested: readonly CacheTag[], owned: readonly CacheTag[]): boolean {
+  return requested.some((r) => owned.some((o) => tagMatches(r, o)));
+}
+
+const declared = new Set<string>();
+
+/** Called once at boot with the entity names from `x.manifest.json`. */
+export function declareTags(entities: readonly string[]): void {
+  for (const name of entities) declared.add(name);
+}
+
+export function knownTags(): readonly string[] {
+  return [...declared].sort();
+}
+
+export function resetDeclaredTags(): void {
+  declared.clear();
+}
+
+/**
+ * Validation is skipped while nothing is declared — `x dev` boots before the manifest
+ * exists, and a hard failure there would be worse than a late one. Once any entity has
+ * declared itself, an undeclared tag is a typo and fails loudly.
+ */
+export function assertKnownTags(tags: readonly CacheTag[]): void {
+  if (declared.size === 0) return;
+  for (const value of tags) {
+    if (!declared.has(value.entity)) {
+      throw new CacheTagUnknownError({ tag: serializeTag(value), known: knownTags() });
+    }
+  }
+}