@ultimat3/query 1.1.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,9 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "1.1.0",
-    "@ultimat3/core": "1.1.0",
-    "@ultimat3/policy": "1.1.0",
-    "@ultimat3/schema": "1.1.0"
+    "@ultimat3/cache": "2.0.0",
+    "@ultimat3/core": "2.0.0",
+    "@ultimat3/http": "2.0.0",
+    "@ultimat3/policy": "2.0.0",
+    "@ultimat3/schema": "2.0.0"
   }
 }

package/src/cache.ts

@@ -1,101 +1,210 @@
 /**
- * Read caching, two layers: a per-request memo (same query twice in one render
- * costs one round trip) and a tag-keyed tier behind the `ReadCache` interface.
- * Invalidation is never local — it goes through @ultimat3/cache so an action's
- * `invalidates` and a query's `tags` meet in one graph.
+ * The read path: a per-request memo (`readOnce` — same query twice in one render costs one
+ * execution, whether the second read follows the first or races it) and, for a query that
+ * declares `cache:`, the fill through `@ultimat3/cache`'s registered tiers (`readThrough`). Every
+ * read gets the memo; the ladder is the half a query opts into.
  */
 
-import type { CacheTag } from '@ultimat3/cache';
-import { invalidateTags } from '@ultimat3/cache';
-import type { Ctx } from '@ultimat3/core';
+import type { CacheStack, CacheTag, CacheTier } from '@ultimat3/cache';
+import { createCacheStack, registeredTiers, tagKeys } from '@ultimat3/cache';
+import type { Actor, Clock, Ctx } from '@ultimat3/core';
+import { assertNever } from '@ultimat3/core';
 import { fingerprint } from './stable';
-import { tagKeys } from './tags';
 
-export interface ReadCacheEntry {
-  readonly value: unknown;
-  readonly expiresAt: number | null;
-}
+/**
+ * A `cache:` block with no `ttlMs`. Tag invalidation is the primary eviction, so this is the
+ * backstop for the read whose tags never fire — one number, the same 60s `@ultimat3/cache`'s
+ * LRU tier defaults to.
+ */
+export const DEFAULT_READ_CACHE_TTL_MS = 60_000;
 
-export interface ReadCache {
-  get(key: string): Promise<ReadCacheEntry | undefined>;
-  set(key: string, entry: ReadCacheEntry): Promise<void>;
-  delete(key: string): Promise<void>;
-}
+/**
+ * Request-scoped memo. Keyed by ctx identity so it dies with the request.
+ *
+ * An entry is the read *in flight*, not its value: unsettled it is the answer a caller is
+ * already waiting for, settled it is the answer. That is what makes two concurrent identical
+ * reads one round trip — and it is why no sentinel is needed for a legitimately `undefined`
+ * value, which a value-keyed memo cannot tell apart from a miss. A promise is never `undefined`.
+ */
+const memos = new WeakMap<object, Map<string, Promise<unknown>>>();
 
-/** In-memory default. Production installs the tiered cache from @ultimat3/cache. */
-export class MemoryReadCache implements ReadCache {
-  readonly #entries = new Map<string, ReadCacheEntry>();
-
-  async get(key: string): Promise<ReadCacheEntry | undefined> {
-    const entry = this.#entries.get(key);
-    if (entry === undefined) return undefined;
-    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
-      this.#entries.delete(key);
-      return undefined;
-    }
-    return entry;
-  }
+export function requestMemo(ctx: Ctx): Map<string, Promise<unknown>> {
+  const key: object = ctx;
+  const existing = memos.get(key);
+  if (existing !== undefined) return existing;
+  const created = new Map<string, Promise<unknown>>();
+  memos.set(key, created);
+  return created;
+}
 
-  async set(key: string, entry: ReadCacheEntry): Promise<void> {
-    this.#entries.set(key, entry);
-  }
+/**
+ * Who a cached answer may be handed back to. Declared as `cache: { scope }`.
+ *
+ * `actor` is the default, and the default is the mechanism (axiom 3): a read that says nothing
+ * gets the NARROWEST key, which is always correct. Widening is a written statement about what the
+ * rows are — `tenant` says "every member of this org gets the same rows", `global` says "everyone
+ * does" — and a wrong one is visible in the declaration rather than in a support ticket.
+ */
+export type QueryCacheScope = 'actor' | 'tenant' | 'global';
 
-  async delete(key: string): Promise<void> {
-    this.#entries.delete(key);
+/**
+ * The authority a read was answered under, as a key component.
+ *
+ * `sql(input, ctx)` is handed the context, and `@ultimat3/entity` derives every tenant predicate
+ * from `ctx.actor.orgId` rather than from the input — so the name, the input and the tags do not
+ * identify a read's answer, and a tier keyed on those three served one org's rows to the next org
+ * that asked. Folding the authority in is what `@ultimat3/entity`'s `scopeKey` does for a batched
+ * point read, for exactly this reason.
+ *
+ * JSON, never a joined string: an actor id is app data and may carry the separator, and a value
+ * that can spell a boundary can spell someone else's.
+ */
+export function readAuthority(actor: Actor, scope: QueryCacheScope): string {
+  switch (scope) {
+    case 'global':
+      return '*';
+    case 'tenant':
+      // An actor inside no org is not a shared tenant. Nothing here can prove two org-less callers
+      // see the same rows, so the key narrows to the actor rather than widening to everyone —
+      // declining instead of guessing, which is the only safe direction for a sharing key.
+      return actor.orgId === undefined || actor.orgId === ''
+        ? actorAuthority(actor)
+        : JSON.stringify(['org', actor.orgId]);
+    case 'actor':
+      return actorAuthority(actor);
+    default:
+      // A fourth scope is a compile error here, not a value that silently keys as `undefined`.
+      return assertNever(scope);
   }
 }
 
-let tier: ReadCache = new MemoryReadCache();
+const actorAuthority = (actor: Actor): string =>
+  JSON.stringify([actor.kind, actor.id, actor.orgId ?? null]);
 
-export function setReadCache(cache: ReadCache): void {
-  tier = cache;
+/**
+ * Deterministic: same query + same input + same tags + same authority => same key.
+ *
+ * `authority` is REQUIRED and positional rather than optional, because an optional one is one a
+ * call site can forget — and a forgotten one is the cross-tenant read this argument exists to
+ * make impossible. `readAuthority` is the only thing that produces it.
+ */
+export function cacheKeyFor(
+  name: string,
+  input: unknown,
+  tags: readonly CacheTag[],
+  authority: string,
+): string {
+  return `query:${name}:${authority}:${fingerprint(input)}:${tagKeys(tags).join(',')}`;
 }
 
-export function getReadCache(): ReadCache {
-  return tier;
+/**
+ * One execution per key per request: the first caller runs it, every caller after joins it.
+ *
+ * This is the layer a query gets whether or not it declares `cache:` — an uncached read asked
+ * once per row of a list is the N+1 the memo exists to collapse.
+ */
+export async function readOnce<T>(ctx: Ctx, key: string, run: () => Promise<T>): Promise<T> {
+  const memo = requestMemo(ctx);
+  const joined = memo.get(key);
+  // Already answered or already being answered: the second reader waits on the first read
+  // rather than starting a competing one. Awaiting a settled promise costs a microtask.
+  if (joined !== undefined) return (await joined) as T;
+  return publish(memo, key, run);
 }
 
-/** Request-scoped memo. Keyed by ctx identity so it dies with the request. */
-const memos = new WeakMap<object, Map<string, unknown>>();
+/**
+ * Runs no matter what the memo holds, and then *becomes* what it holds — what `fresh: true` asks
+ * for.
+ *
+ * Joining is the half `fresh` refuses; publishing is not. A fresh read that left the earlier entry
+ * in place would read past a write for its own caller and hand the next plain read of that key in
+ * the same request the answer this one just proved stale — so the guarantee would end at the one
+ * call that asked for it.
+ */
+export function readFresh<T>(ctx: Ctx, key: string, run: () => Promise<T>): Promise<T> {
+  return publish(requestMemo(ctx), key, run);
+}
 
-export function requestMemo(ctx: Ctx): Map<string, unknown> {
-  const key: object = ctx;
-  const existing = memos.get(key);
-  if (existing !== undefined) return existing;
-  const created = new Map<string, unknown>();
-  memos.set(key, created);
-  return created;
+/** The read in flight: published before its first await, evicted if it rejects. */
+async function publish<T>(
+  memo: Map<string, Promise<unknown>>,
+  key: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  // Published before the first await, so a reader arriving in the same tick finds this read.
+  const flight = run();
+  memo.set(key, flight);
+  try {
+    return await flight;
+  } catch (error) {
+    // A rejection is not an answer. Drop it so a later read in the same request retries
+    // instead of replaying one failure until the request ends. Only ours: a fresh read may have
+    // replaced this entry already, and evicting that one would discard a live answer.
+    if (memo.get(key) === flight) memo.delete(key);
+    throw error;
+  }
 }
 
-/** Deterministic: same query + same input + same tags => same key. */
-export function cacheKeyFor(name: string, input: unknown, tags: readonly CacheTag[]): string {
-  return `query:${name}:${fingerprint(input)}:${tagKeys(tags).join(',')}`;
+/**
+ * One stack per (registry, clock) — never one per read.
+ *
+ * `createCacheStack` owns a single-flight map, so a stack built per call joins nothing and the
+ * cross-request stampede guard would be a no-op. Keyed on the clock because the stack's expiry
+ * decision and the tiers' own have to agree: a tier registered with a frozen clock under a stack
+ * reading the wall clock calls every entry expired, which is the shape that made the old read
+ * tier undrivable by a test.
+ */
+const stacks = new WeakMap<Clock, { tiers: readonly CacheTier[]; stack: CacheStack }>();
+
+const sameTiers = (a: readonly CacheTier[], b: readonly CacheTier[]): boolean =>
+  a.length === b.length && a.every((tier, index) => tier === b[index]);
+
+function stackFor(clock: Clock): CacheStack {
+  const tiers = registeredTiers();
+  const held = stacks.get(clock);
+  // Rebuilt whenever the registry changes — a boot that registers the shared tier after the first
+  // read, and `resetTiers()` between suites. Compared element-wise by identity: a tier object is
+  // registered once and never mutated, so two equal lists are the same ladder.
+  if (held !== undefined && sameTiers(held.tiers, tiers)) return held.stack;
+  const stack = createCacheStack(tiers, { clock });
+  stacks.set(clock, { tiers, stack });
+  return stack;
 }
 
-/** Memo first, then the tier, then the source. */
-export async function readThrough<T>(
+/**
+ * Memo first, then the tier ladder, then the source — what a query with `cache:` reads through.
+ *
+ * `tags` is what the written entry is dropped by; an entry stored without them is reachable
+ * only by its key and can therefore only expire.
+ */
+export function readThrough<T>(
   ctx: Ctx,
   key: string,
   ttlMs: number | null,
   run: () => Promise<T>,
+  tags: readonly CacheTag[] = [],
 ): Promise<T> {
-  const memo = requestMemo(ctx);
-  const memoized = memo.get(key);
-  if (memoized !== undefined) return memoized as T;
-
-  const cached = await tier.get(key);
-  if (cached !== undefined) {
-    memo.set(key, cached.value);
-    return cached.value as T;
-  }
-
-  const value = await run();
-  memo.set(key, value);
-  await tier.set(key, { value, expiresAt: ttlMs === null ? null : Date.now() + ttlMs });
-  return value;
+  return readOnce(ctx, key, () => fill(ctx.clock, key, ttlMs, tags, run));
 }
 
-/** The one invalidation path. Actions call the same function via their `cache`. */
-export async function invalidateQueryTags(tags: readonly CacheTag[]): Promise<void> {
-  await invalidateTags(tags);
+/**
+ * The read itself, through the tiers `@ultimat3/cache` has registered and no store of this
+ * package's own. Runs once per key per request; the rest join it at the memo above.
+ *
+ * Everything this used to do by hand — the fence sampled before the load, `bestEffort` around
+ * every tier call, the expiry — is `createCacheStack`'s, which is the point: there was one read
+ * cache too many, and the one that lived here was in no registry, so `invalidateTags` could not
+ * reach it. A relative `ttlMs` and never an absolute expiry: the tier's own clock decides when
+ * the entry dies, so a tier registered with a frozen clock is drivable end to end.
+ */
+function fill<T>(
+  clock: Clock,
+  key: string,
+  ttlMs: number | null,
+  tags: readonly CacheTag[],
+  run: () => Promise<T>,
+): Promise<T> {
+  // `null` is "the caller named none", never "never": every tier refuses a non-positive `ttlMs`
+  // and none has an immortal entry to offer, so omitting it falls to the tier's own default.
+  return stackFor(clock).read(key, run, { ...(ttlMs === null ? {} : { ttlMs }), tags });
 }

package/src/client.ts

@@ -3,11 +3,18 @@
  * the same pure derivation the server uses, so a renamed query is a compile error
  * in a Solid component rather than a 404 at runtime. Browser-safe on purpose: no
  * server imports, nothing here touches a context, a policy or a database.
+ *
+ * Rows arrive as JSON and are handed back as parsed, exactly as `rpc` does: a query declares no
+ * output schema — row types come from the `SqlSource` its `sql:` returns — so there is nothing
+ * here to rehydrate a `Date` with, and an instant reaches a caller as the ISO string
+ * `JSON.stringify` wrote. A surface that formats one converts at its own edge.
  */
 
+import { currentSpanContext, traceparent } from '@ultimat3/core';
 import type { InferInput, StandardSchemaV1 } from '@ultimat3/schema';
 import { QueryRequestFailedError } from './errors';
 import { derivePath } from './naming';
+import type { Query } from './query';
 import { isJsonObject } from './stable';
 
 export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
@@ -28,7 +35,57 @@ export type QueryClientMethod<TInput extends StandardSchemaV1, TRow extends obje
   options?: QueryCallOptions,
 ) => Promise<readonly TRow[]>;
 
-/** One query's method — what `query.client()` returns. */
+/**
+ * Loose constraint on purpose: a map of concrete `Query<TInput, TRow>` values must be
+ * assignable to it, while `QueryClient<T>` still recovers each read's own input schema and
+ * row type. The mirror of `@ultimat3/action`'s `ActionLike`.
+ */
+export interface QueryLike {
+  readonly kind: 'query';
+  readonly name: string;
+}
+
+export type QueryMap = Record<string, QueryLike>;
+
+/** `queries.publicPost({ slug })`, with the input schema and the row type both inferred. */
+export type QueryClient<TQueries extends QueryMap> = {
+  readonly [K in keyof TQueries]: TQueries[K] extends Query<infer TInput, infer TRow>
+    ? QueryClientMethod<TInput, TRow>
+    : never;
+};
+
+/**
+ * The typed client for a whole query map: `queryClient<Api['queries']>({ baseUrl })`, the read
+ * half of `rpc<Api['actions']>`. A surface that must not import a feature — `site/`, whose one
+ * edge into `app/` would be a boundary violation — reaches every registered read through this
+ * and the `Api` TYPE, with no module-graph edge and no codegen step.
+ *
+ * One blessed name, and one implementation underneath it: every method is
+ * `queryClientMethodFor`, so the map-wide spelling and `read.client()` can never derive
+ * different URLs for the same read.
+ */
+export function queryClient<TQueries extends QueryMap>(
+  options: QueryClientOptions,
+): QueryClient<TQueries> {
+  const proxy = new Proxy(
+    {},
+    {
+      get(_target, property: string | symbol) {
+        // `then` is answered with `undefined` for the same reason a symbol is: `await client`,
+        // `Promise.resolve(client)` and returning the client from an async function all read it,
+        // and a method there makes the client a thenable that fetches a read named "then" and
+        // resolves the await to its rows. No query may be called `then` — it is the one name the
+        // language reserves at this seam.
+        if (typeof property !== 'string' || property === 'then') return undefined;
+        return queryClientMethodFor(property, options);
+      },
+    },
+  );
+  // The proxy realizes the mapped type structurally; TS cannot check a Proxy.
+  return proxy as QueryClient<TQueries>;
+}
+
+/** One query's method — what `query.client()` returns, and what `queryClient` proxies to. */
 export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow extends object>(
   name: string,
   options: QueryClientOptions,
@@ -52,7 +109,10 @@ async function read(
   const url = `${base}${derivePath(name)}${search === '' ? '' : `?${search}`}`;
   const init: RequestInit = {
     method: 'GET',
-    headers: { accept: 'application/json', ...options.headers },
+    // `traceHeaders()` before the caller's, so an explicit `traceparent` still wins. Without it a
+    // service-to-service read started a fresh root trace on the other side, and "which of my
+    // downstreams is slow" was unanswerable across every Ultimate-to-Ultimate hop.
+    headers: { accept: 'application/json', ...traceHeaders(), ...options.headers },
     ...(callOptions.signal === undefined ? {} : { signal: callOptions.signal }),
   };
 
@@ -63,6 +123,27 @@ async function read(
   return body;
 }
 
+/** A `traceparent` is `00-<32 hex>-<16 hex>-<2 hex>`, and nothing else may be sent as one. */
+const TRACE_ID = /^[0-9a-f]{32}$/;
+const SPAN_ID = /^[0-9a-f]{16}$/;
+
+/**
+ * The current trace, as the W3C header — or nothing at all. `currentSpanContext()` answers with
+ * an empty `spanId` when a request context exists but no span is active, and `00-<trace>--01` is
+ * a header every collector drops, so an incomplete context sends none. In a browser there is no
+ * ambient context and this is always empty, which is also what keeps a cross-origin read from
+ * acquiring a CORS preflight it did not have.
+ *
+ * `@ultimat3/action`'s client carries the twin of this function: both are tier 3, so neither may
+ * import the other — the same reason `naming.ts` is ported rather than shared.
+ */
+function traceHeaders(): Record<string, string> {
+  const context = currentSpanContext();
+  if (context === undefined) return {};
+  if (!TRACE_ID.test(context.traceId) || !SPAN_ID.test(context.spanId)) return {};
+  return { traceparent: traceparent(context) };
+}
+
 /**
  * Input as a query string. Keys are sorted so the same input always produces the
  * same URL — a GET is a cache key, and an unstable one caches nothing.

package/src/cursor-value.ts

@@ -0,0 +1,65 @@
+// Single responsibility: what a sort value becomes inside a cursor, and what it becomes again on
+// the way out. The codec is `@ultimat3/core`'s and it is JSON, so a `Date` went in and an ISO
+// STRING came back: `isAfterKey` then compared `"1769904000000"` against `"2026-02-01T…"` through
+// `compareValues`' string branch and page two came back empty. A `bigint` was worse — a bare
+// `TypeError` out of `JSON.stringify`, with no code and no fix.
+//
+// `@ultimat3/entity`'s `cursor.ts` solves the same problem by reading the column's declared kind.
+// A `query` has no column kinds — `QueryShape.orderBy` is a name and a direction — so the value
+// carries its own tag instead. Self-describing, which is also what makes the revive total: nothing
+// here has to know which read minted the cursor.
+
+import { CursorValueUnsupportedError } from './errors';
+
+/** The two tagged forms. `$x` is a key no column value can collide with: JSON has no bigints. */
+const DATE = 'date';
+const BIGINT = 'bigint';
+
+interface TaggedValue {
+  readonly $x: typeof DATE | typeof BIGINT;
+  readonly v: string;
+}
+
+function isTagged(value: unknown): value is TaggedValue {
+  if (typeof value !== 'object' || value === null) return false;
+  const tag = (value as Record<string, unknown>)['$x'];
+  return (
+    (tag === DATE || tag === BIGINT) && typeof (value as Record<string, unknown>)['v'] === 'string'
+  );
+}
+
+/**
+ * One sort value, in a form `JSON.stringify` carries losslessly.
+ *
+ * `undefined` becomes `null` because SQL has one absence and `isNull` reads both as it — a key
+ * that encoded `undefined` would be dropped by `JSON.stringify` and shift every later key one
+ * position left, which is a cursor that seeks by the wrong column.
+ *
+ * Everything JSON cannot carry AND this cannot tag is refused HERE, where the cursor is minted:
+ * the mistake is the read's `orderBy`, and reporting it on the next request would blame a client
+ * for a declaration it never saw.
+ */
+export function serializeSortValue(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) throw new CursorValueUnsupportedError('an Invalid Date');
+    return { $x: DATE, v: value.toISOString() } satisfies TaggedValue;
+  }
+  if (typeof value === 'bigint') return { $x: BIGINT, v: value.toString() } satisfies TaggedValue;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  // `NaN` and `±Infinity` are `null` in JSON, which is the largest value in this framework's sort
+  // order — so an unsortable number would decode as "past every row" and end the listing.
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return value;
+    throw new CursorValueUnsupportedError(`the number ${String(value)}`);
+  }
+  throw new CursorValueUnsupportedError(`a ${typeof value}`);
+}
+
+/** The inverse, over a whole decoded key. A value that is not one of ours is handed back as is. */
+export function reviveSortKey(key: readonly unknown[]): readonly unknown[] {
+  return key.map((value) => {
+    if (!isTagged(value)) return value;
+    return value.$x === DATE ? new Date(value.v) : BigInt(value.v);
+  });
+}

package/src/deprecation.ts

@@ -0,0 +1,81 @@
+/**
+ * A declared retirement, rendered as the two headers the standards already define — RFC 9745
+ * `Deprecation` and RFC 8594 `Sunset` — plus the successor link. Pure string and date maths, and
+ * deliberately throw-free: each package raises its own `X_*` for a date it cannot render.
+ *
+ * `@ultimat3/action` carries the twin of this file. Both are tier 3, so neither may import the
+ * other, and the shared home is `@ultimat3/http` (tier 2) once that package grows one — the same
+ * compromise `naming.ts` is ported under.
+ */
+import { counter } from '@ultimat3/core';
+
+export interface Deprecation {
+  /** When it was deprecated. ISO-8601, e.g. `'2026-08-01T00:00:00Z'`. */
+  readonly since: string;
+  /** When it stops answering. ISO-8601 — the date `Sunset` publishes and clients plan against. */
+  readonly sunset: string;
+  /** The export name of the replacement, projected to a `rel="successor-version"` link. */
+  readonly replacedBy?: string;
+}
+
+export type DeprecationField = 'since' | 'sunset';
+
+export type DeprecationRender =
+  | {
+      readonly ok: true;
+      readonly headers: Readonly<Record<string, string>>;
+      /** The same facts as data, for the descriptor and the manifest. */
+      readonly meta: Readonly<Record<string, string>>;
+    }
+  | { readonly ok: false; readonly field: DeprecationField; readonly value: string };
+
+/**
+ * How many calls a deprecated declaration is still taking — the number "can we remove it yet?"
+ * needs. Attributes are the primitive and the declared NAME, both bounded by the size of the
+ * codebase; a caller id here would be an unbounded series.
+ */
+const deprecatedCalls = counter('deprecated_calls_total', {
+  unit: '{call}',
+  description: 'Calls served by a declaration that has been deprecated, by primitive and name',
+});
+
+export function recordDeprecatedCall(primitive: 'action' | 'query', name: string): void {
+  deprecatedCalls.add(1, { primitive, name });
+}
+
+/**
+ * `Deprecation` is a structured-field Date (`@` + unix seconds, RFC 9745); `Sunset` is an
+ * HTTP-date (IMF-fixdate, RFC 8594). Two spellings of one instant because two RFCs chose
+ * differently — never render one in the other's format, and never emit `Invalid Date`.
+ */
+export function renderDeprecation(
+  deprecation: Deprecation,
+  successorPath: string | undefined,
+): DeprecationRender {
+  const since = Date.parse(deprecation.since);
+  if (Number.isNaN(since)) return { ok: false, field: 'since', value: deprecation.since };
+  const sunset = Date.parse(deprecation.sunset);
+  if (Number.isNaN(sunset)) return { ok: false, field: 'sunset', value: deprecation.sunset };
+
+  const headers: Record<string, string> = {
+    deprecation: `@${Math.floor(since / 1000)}`,
+    sunset: new Date(sunset).toUTCString(),
+  };
+  // The successor's URL, derived by the caller from the same `naming.ts` the client uses — a
+  // link this file built from the export name would be the second URL derivation in the package.
+  if (successorPath !== undefined) {
+    headers['link'] = `<${successorPath}>; rel="successor-version"`;
+  }
+
+  const meta: Record<string, string> = {
+    since: new Date(since).toISOString(),
+    sunset: new Date(sunset).toISOString(),
+    ...(deprecation.replacedBy === undefined ? {} : { replacedBy: deprecation.replacedBy }),
+  };
+  return { ok: true, headers, meta };
+}
+
+/** Set on a response that already exists, so a problem document carries them too. */
+export function applyHeaders(response: Response, headers: Readonly<Record<string, string>>): void {
+  for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
+}