@ultimat3/core 24.0.0 → 25.0.0

package/src/context.ts

@@ -3,9 +3,9 @@
 // parameters — otherwise every signature in the framework grows a `ctx` argument twice.
 //
 // THERE IS EXACTLY ONE ASSERTION IN THIS FILE AND IT IS IRREDUCIBLE (`As of 2026-08-24`). It is
-// the `as Ctx` in `createContext`, and it is the LAST one: the second — over `preview` — is gone,
+// the `as Ctx` in `ctxOf`, and it is the LAST one: the second — over `preview` — is gone,
 // because `CtxFacts` gives that value an honest type, and `@ultimat3/http`'s
-// `createRequestContext` now composes this function instead of building a second context beside
+// `requestContext` now composes this function instead of building a second context beside
 // it, so that package has none at all.
 //
 // Why the last one cannot go. `Ctx extends CtxServices`, and `CtxServices` is the seam an app
@@ -20,9 +20,9 @@
 // Four alternatives were built and measured before this line was kept. Making the augmented half
 // `Partial<CtxServices>` removes the assertion and turns `ctx.posts` into `PostRepo | undefined`
 // for every app — true, and a breaking change to the documented seam. Requiring `CtxInit.services`
-// to be a `CtxServices` moves the proof to the caller and breaks every internal `createContext()`
+// to be a `CtxServices` moves the proof to the caller and breaks every internal `ctxOf()`
 // in an app's program, because an app typechecks the framework's sources through its project
-// references. A generic `createContext<S>` returns a context no framework caller can pass where a
+// references. A generic `ctxOf<S>` returns a context no framework caller can pass where a
 // `Ctx` is wanted. And an overload whose implementation signature returns the looser type compiles
 // only through TypeScript's documented bivariance hole — the same assertion, laundered.
 //
@@ -35,7 +35,7 @@ import { asyncContext } from './async-context';
 import { type Clock, systemClock } from './clock';
 import { UltimateError } from './errors';
 import { finiteOption } from './finite-option';
-import { traceId as newTraceId, uuid } from './ids';
+import { traceId as newTraceId, uuidV7 } from './ids';
 import { type Logger, logger as rootLogger, setLoggerContextFields } from './logger';
 import { installTraceHeaders } from './outbound-headers';
 import { type Role, resolveRole } from './roles';
@@ -73,7 +73,7 @@ export interface ServiceBag {
  * against a type carrying members only the app's boot knows about: `Ctx extends CtxServices`, an
  * app augments `CtxServices` with `declare module`, and every service it declares then became a
  * REQUIRED member of every context literal in the framework. `@ultimat3/http`'s
- * `createRequestContext` stopped compiling inside `examples/dummy` for exactly that reason
+ * `requestContext` stopped compiling inside `examples/dummy` for exactly that reason
  * (`TS2739: missing posts, orgs`), while the framework's own gate — which augments nothing —
  * stayed green.
  *
@@ -157,6 +157,10 @@ const requestContext = asyncContext<Ctx>('the request context');
 
 const neverAborted = new AbortController().signal;
 
+/**
+ * The framework's default locale — the ONE declaration: `@ultimat3/i18n` imports it rather than
+ * restating it (a second `'en'` there could drift from the context's own default).
+ */
 export const DEFAULT_LOCALE = 'en';
 export const DEFAULT_TIME_ZONE = 'UTC';
 
@@ -164,9 +168,9 @@ function buildId(): string {
   return process.env['BUILD_ID'] ?? 'dev';
 }
 
-export function createContext(init: CtxInit = {}): Ctx {
+export function ctxOf(init: CtxInit = {}): Ctx {
   const clock = init.clock ?? systemClock;
-  const requestId = init.requestId ?? uuid(clock);
+  const requestId = init.requestId ?? uuidV7(clock);
   const trace = init.traceId ?? newTraceId();
   const base = init.logger ?? rootLogger;
   const explicit: ServiceBag = Object.freeze({ ...(init.services ?? {}) });
@@ -233,7 +237,7 @@ export function useContext(): Ctx {
     throw new UltimateError({
       code: 'X_NO_CONTEXT',
       cause: 'useContext() was called outside of runWithContext()',
-      fix: 'wrap the entry point in runWithContext(createContext({ ... }), fn)',
+      fix: 'wrap the entry point in runWithContext(ctxOf({ ... }), fn)',
     });
   }
   return ctx;
@@ -291,13 +295,13 @@ function composeSignal(parent: AbortSignal, patch: AbortSignal | undefined): Abo
 export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
   const parent = useContext();
   // A factory-managed service was built for the PARENT's actor; forwarding it verbatim into an
-  // impersonated child would answer every call with the parent's tenant. `createContext` below
+  // impersonated child would answer every call with the parent's tenant. `ctxOf` below
   // rebuilds every registered factory fresh against the child's own actor, so only services no
   // factory owns — a hand-built mock nothing registered — carry forward unrebuilt.
   const carried = Object.fromEntries(
     Object.entries(parent.services).filter(([name]) => !isManagedService(name)),
   );
-  const child = createContext({
+  const child = ctxOf({
     requestId: parent.requestId,
     traceId: patch.traceId ?? parent.traceId,
     actor: patch.actor ?? parent.actor,
@@ -330,7 +334,7 @@ export function useService<T>(name: string): T {
     throw new UltimateError({
       code: 'X_SERVICE_MISSING',
       cause: `"${name}" is not on ctx.services (have: ${Object.keys(ctx.services).join(', ')})`,
-      fix: `pass it in createContext({ services: { ${name} } })`,
+      fix: `pass it in ctxOf({ services: { ${name} } })`,
       meta: { name },
     });
   }

package/src/cookie.ts

@@ -1,6 +1,10 @@
-// The one `Cookie:` request-header reader. At tier 0 because three packages need it — auth and http
-// at tier 2 cannot import each other, i18n sits below both — and each copy had to rediscover the
-// same thrown `URIError` on its own (`bun run flight-copies` refuses a fourth).
+// The one cookie header codec: `readCookie` reads a `Cookie:` request header, `serializeSetCookie`
+// builds a `Set-Cookie` value. At tier 0 because three packages need it — auth and http at tier 2
+// cannot import each other, i18n sits below both — and each copy had to rediscover the same thrown
+// `URIError` on its own (`bun run flight-copies` refuses a fourth).
+
+import { renderCauseValue } from './error-render';
+import { UltimateError } from './errors';
 
 /**
  * A `Cookie:` header is attacker-controlled, and `decodeURIComponent('%')` throws a bare
@@ -33,3 +37,263 @@ export function readCookie(header: string | null | undefined, name: string): str
   }
   return null;
 }
+
+/** `SameSite`: `None` sends the cookie cross-site, so it is only accepted beside `Secure`. */
+export type CookieSameSite = 'Strict' | 'Lax' | 'None';
+/** Chromium's `Priority`, the order cookies are evicted in when a domain is over its quota. */
+export type CookiePriority = 'Low' | 'Medium' | 'High';
+
+export interface SetCookieOptions {
+  /** Seconds until expiry; `0` clears the cookie. A non-negative integer. */
+  readonly maxAge?: number;
+  /** Absolute expiry, written as an IMF-fixdate in UTC. Beside `maxAge`, `maxAge` wins in a browser. */
+  readonly expires?: Date;
+  /** Defaults to `/`. Must start with `/`: a browser silently replaces any other with its own. */
+  readonly path?: string;
+  /** Omitted by default, which scopes the cookie to the exact host that set it. */
+  readonly domain?: string;
+  /** Defaults to `true`. */
+  readonly secure?: boolean;
+  /** Defaults to `true`. */
+  readonly httpOnly?: boolean;
+  /** Defaults to `'Lax'`. */
+  readonly sameSite?: CookieSameSite;
+  /** CHIPS: keyed to the top-level site. Requires `secure`. */
+  readonly partitioned?: boolean;
+  readonly priority?: CookiePriority;
+}
+
+/** RFC 6265 §4.1.1 `token`: any CHAR except CTLs and the separators `()<>@,;:\"/[]?={}`, SP, HT. */
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** Every UTF-16 unit outside RFC 6265 `cookie-octet` — plus `%`, which readCookie decodes. */
+const NOT_COOKIE_OCTET = /[^\x21\x23\x24\x26-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]+/g;
+/**
+ * A lone UTF-16 surrogate: it has no UTF-8 form, so `encodeURIComponent` would throw a bare
+ * `URIError`. Spelled out because `String#isWellFormed` is ES2024 and the lib is ES2023.
+ */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** A path a browser keeps verbatim: absolute, printable ASCII, no `;` to end the attribute early. */
+const COOKIE_PATH = /^\/[\x21-\x3A\x3C-\x7E]*$/;
+const DOMAIN_LABEL = '[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?';
+const COOKIE_DOMAIN = new RegExp(`^\\.?${DOMAIN_LABEL}(?:\\.${DOMAIN_LABEL})*$`);
+/** RFC 6265bis §5.6/§5.7: a browser ignores a pair over 4096 octets and an attribute over 1024. */
+const MAX_PAIR_OCTETS = 4096;
+const MAX_ATTRIBUTE_OCTETS = 1024;
+const SAME_SITE: readonly string[] = ['Strict', 'Lax', 'None'];
+const PRIORITY: readonly string[] = ['Low', 'Medium', 'High'];
+const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const;
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+const PARTITIONED_FIX =
+  'serializeSetCookie(name, value, { partitioned: true, secure: true })   # Partitioned requires Secure';
+
+type CookieField = keyof SetCookieOptions | 'name' | 'value';
+
+/** A `Set-Cookie` the caller asked for that a browser would drop, misread or let be injected into. */
+export class CookieInvalidError extends UltimateError {
+  override readonly name = 'CookieInvalidError';
+
+  constructor(field: CookieField, cookie: string, reason: string, fix: string) {
+    super({
+      code: 'X_COOKIE_INVALID',
+      cause: `Set-Cookie ${renderCauseValue(cookie)}: ${field} ${reason}`,
+      fix,
+      meta: { field },
+    });
+  }
+}
+
+/**
+ * Percent-encodes exactly what `cookie-octet` excludes, and `%`. Minimal rather than
+ * `encodeURIComponent`, so a base64url token or a sealed value is written byte-identical — moving
+ * an existing cookie onto this does not change what a non-Ultimate reader sees — while
+ * `decodeURIComponent` in `readCookie` still inverts it exactly: what was passed is what is read.
+ */
+const encodeCookieValue = (value: string): string =>
+  value.replace(NOT_COOKIE_OCTET, (run) => encodeURIComponent(run));
+
+const pad = (n: number): string => String(n).padStart(2, '0');
+
+/**
+ * RFC 9110 §5.6.7 IMF-fixdate, read from the `getUTC*` fields: the zone is UTC by construction,
+ * never the process's, and no locale table can rename a weekday.
+ */
+function imfFixdate(at: Date): string {
+  const day = WEEKDAYS[at.getUTCDay()];
+  const month = MONTHS[at.getUTCMonth()];
+  const year = String(at.getUTCFullYear()).padStart(4, '0');
+  const time = `${pad(at.getUTCHours())}:${pad(at.getUTCMinutes())}:${pad(at.getUTCSeconds())}`;
+  return `${day}, ${pad(at.getUTCDate())} ${month} ${year} ${time} GMT`;
+}
+
+/**
+ * RFC 6265bis §4.1.3: a browser drops a prefixed cookie that breaks its prefix's rule, silently,
+ * and matches the prefix case-insensitively — so the refusal does too.
+ */
+function checkPrefix(name: string, secure: boolean, path: string, domain: string | undefined) {
+  const lower = name.toLowerCase();
+  if (lower.startsWith('__secure-') && !secure) {
+    throw new CookieInvalidError(
+      'name',
+      name,
+      'has the __Secure- prefix without Secure',
+      'serializeSetCookie(name, value, { secure: true })   # __Secure- requires Secure',
+    );
+  }
+  if (!lower.startsWith('__host-')) return;
+  if (!secure || domain !== undefined || path !== '/') {
+    throw new CookieInvalidError(
+      'name',
+      name,
+      'has the __Host- prefix, which requires Secure, no Domain and Path=/',
+      "serializeSetCookie(name, value, { secure: true, path: '/' })   # __Host- also forbids domain",
+    );
+  }
+}
+
+function checkAttribute(
+  field: 'path' | 'domain',
+  name: string,
+  value: string,
+  shape: RegExp,
+  fix: string,
+) {
+  // The shape admits ASCII only, so once it matches `.length` is the octet count.
+  if (value.length <= MAX_ATTRIBUTE_OCTETS && shape.test(value)) return;
+  throw new CookieInvalidError(
+    field,
+    name,
+    `${renderCauseValue(value)} is not a valid ${field}`,
+    fix,
+  );
+}
+
+function checkEnum(
+  field: 'sameSite' | 'priority',
+  name: string,
+  value: string,
+  allowed: readonly string[],
+) {
+  if (allowed.includes(value)) return;
+  const reason = `${renderCauseValue(value)} is not one of ${allowed.join(', ')}`;
+  throw new CookieInvalidError(
+    field,
+    name,
+    reason,
+    `serializeSetCookie(name, value, { ${field}: '${allowed[1]}' })   # one of ${allowed.join(', ')}`,
+  );
+}
+
+function expiresAttribute(name: string, expires: Date): string {
+  const year = expires instanceof Date ? expires.getUTCFullYear() : Number.NaN;
+  // Below 1601 a cookie parser rejects the date (RFC 6265 §5.1.1); above 9999 it is not 4 digits.
+  if (!(year >= 1601 && year <= 9999)) {
+    throw new CookieInvalidError(
+      'expires',
+      name,
+      `${renderCauseValue(expires)} is not a Date between the years 1601 and 9999`,
+      'serializeSetCookie(name, value, { expires: new Date(Date.now() + ms) })   # or maxAge in seconds',
+    );
+  }
+  return `; Expires=${imfFixdate(expires)}`;
+}
+
+/**
+ * One `Set-Cookie` header value — the only place the framework spells one. Defaults are the ones
+ * `@ultimat3/auth`'s session and OAuth cookies already ship: `Path=/; HttpOnly; Secure;
+ * SameSite=Lax`. The value is encoded so `readCookie` returns it exactly; anything a browser would
+ * silently drop, or that could end the header early, is an `X_COOKIE_INVALID` instead.
+ */
+export function serializeSetCookie(
+  name: string,
+  value: string,
+  options: SetCookieOptions = {},
+): string {
+  if (!COOKIE_NAME.test(name)) {
+    const reason = "is not an RFC 6265 token (letters, digits and !#$%&'*+-.^_`|~ only)";
+    throw new CookieInvalidError(
+      'name',
+      name,
+      reason,
+      "serializeSetCookie('session_id', value)   # letters, digits, - and _ only",
+    );
+  }
+  if (LONE_SURROGATE.test(value)) {
+    const fix =
+      'serializeSetCookie(name, value.toWellFormed())   # or base64url-encode binary data';
+    throw new CookieInvalidError('value', name, 'has a lone UTF-16 surrogate', fix);
+  }
+  const encoded = encodeCookieValue(value);
+  // `.length` IS the octet count: a token name and a percent-encoded value are ASCII only.
+  const pairOctets = name.length + encoded.length;
+  if (pairOctets > MAX_PAIR_OCTETS) {
+    const reason = `is ${pairOctets} octets as name=value encoded; a browser drops one over ${MAX_PAIR_OCTETS}`;
+    throw new CookieInvalidError(
+      'value',
+      name,
+      reason,
+      'serializeSetCookie(name, sessionId)   # keep the data server-side, an id in the cookie',
+    );
+  }
+  const { maxAge, expires, domain, partitioned, priority } = options;
+  const path = options.path ?? '/';
+  const secure = options.secure ?? true;
+  const httpOnly = options.httpOnly ?? true;
+  const sameSite = options.sameSite ?? 'Lax';
+  checkPrefix(name, secure, path, domain);
+  checkEnum('sameSite', name, sameSite, SAME_SITE);
+  if (sameSite === 'None' && !secure) {
+    const reason = 'is None without Secure, which every current browser rejects';
+    throw new CookieInvalidError(
+      'sameSite',
+      name,
+      reason,
+      "serializeSetCookie(name, value, { sameSite: 'None', secure: true })   # None requires Secure",
+    );
+  }
+  if (partitioned === true && !secure) {
+    const reason = 'is set without Secure, which a browser rejects';
+    throw new CookieInvalidError('partitioned', name, reason, PARTITIONED_FIX);
+  }
+  let header = `${name}=${encoded}`;
+  if (maxAge !== undefined) {
+    if (!Number.isSafeInteger(maxAge) || maxAge < 0) {
+      const reason = `${renderCauseValue(maxAge)} is not a whole number of seconds >= 0`;
+      throw new CookieInvalidError(
+        'maxAge',
+        name,
+        reason,
+        'serializeSetCookie(name, value, { maxAge: Math.floor(ms / 1000) })   # 0 clears the cookie',
+      );
+    }
+    header += `; Max-Age=${maxAge}`;
+  }
+  if (expires !== undefined) header += expiresAttribute(name, expires);
+  if (domain !== undefined) {
+    checkAttribute(
+      'domain',
+      name,
+      domain,
+      COOKIE_DOMAIN,
+      "serializeSetCookie(name, value, { domain: 'example.com' })   # a bare host, or omit domain",
+    );
+    header += `; Domain=${domain}`;
+  }
+  checkAttribute(
+    'path',
+    name,
+    path,
+    COOKIE_PATH,
+    "serializeSetCookie(name, value, { path: '/app' })   # absolute, percent-encoded",
+  );
+  header += `; Path=${path}`;
+  if (httpOnly) header += '; HttpOnly';
+  if (secure) header += '; Secure';
+  header += `; SameSite=${sameSite}`;
+  if (partitioned === true) header += '; Partitioned';
+  if (priority !== undefined) {
+    checkEnum('priority', name, priority, PRIORITY);
+    header += `; Priority=${priority}`;
+  }
+  return header;
+}

package/src/core-error-codes.ts

@@ -70,6 +70,8 @@ const CORE_CODE_TITLES = {
   // place rather than by whichever package happened to raise one first.
   X_TIMEOUT: 'operation exceeded its deadline',
   X_UNREACHABLE: 'unreachable branch was reached',
+  X_SECRETS_KEY_ACL_FAILED: 'key file ACL not owner-only',
+  X_COOKIE_INVALID: 'a Set-Cookie value would be dropped, misread or injectable',
 } as const;
 
 export type CoreErrorCode = keyof typeof CORE_CODE_TITLES;

package/src/cursor-page.ts

@@ -0,0 +1,41 @@
+// The framework's ONE page shape — an entity `findMany`, a query `.page()`, the `?_first` HTTP
+// envelope and the typed client all answer it. Tier 0 so the repo (tier 2) and the read (tier 3)
+// share it rather than each declaring a page whose `nextCursor` meant something different.
+
+/**
+ * One page of a cursor-paginated listing, with ONE meaning: `nextCursor` is the cursor for the
+ * next page, and `null` exactly when `hasMore` is false.
+ *
+ * A union and not an interface, so the two facts cannot disagree in any value that typechecks:
+ * `{ nextCursor: null, hasMore: true }` is a build error, and `if (page.hasMore)` narrows
+ * `nextCursor` to `string`. `while (page.hasMore)` and `while (page.nextCursor !== null)` are the
+ * same loop and both stop on the last page, with no extra round trip to learn it was the last.
+ *
+ * Before 25.0.0 there were two pages: entity's own `Page` (null = last page, no `hasMore`) and query's
+ * `Page` (null only on an EMPTY page, `hasMore` carried "last") — so a `while (page.nextCursor)`
+ * loop was right on one and fetched an empty page past the end of the other.
+ */
+export type Page<Row> =
+  | {
+      readonly rows: readonly Row[];
+      /** Pass back as `cursor` (a repo) or `after` (a read) — `_after` on the wire. */
+      readonly nextCursor: string;
+      readonly hasMore: true;
+    }
+  | {
+      readonly rows: readonly Row[];
+      readonly nextCursor: null;
+      readonly hasMore: false;
+    };
+
+/**
+ * The only constructor: `hasMore` is DERIVED from the cursor, never passed beside it, so a
+ * producer cannot answer "more" without saying where. A producer that learned "no more" passes
+ * `null` — the cursor it could have minted for its last row is not a next page. An empty string is
+ * no cursor (a falsy cursor would end a `while (page.nextCursor)` loop that `hasMore` continues).
+ */
+export function pageOf<Row>(rows: readonly Row[], nextCursor: string | null): Page<Row> {
+  return nextCursor === null || nextCursor === ''
+    ? { rows, nextCursor: null, hasMore: false }
+    : { rows, nextCursor, hasMore: true };
+}

package/src/cursor.ts

@@ -36,7 +36,17 @@ export class CursorInvalidError extends UltimateError {
  * — a fixed literal rather than a per-process random one on purpose: a random secret would make
  * a cursor issued by one instance fail on the next, and that failure only shows up under scale.
  */
-const DEV_SECRET = 'ultimate-dev-cursor-secret';
+export const DEV_CURSOR_SECRET = 'ultimate-dev-cursor-secret';
+
+/**
+ * The env key a deployed process signs cursors with. Named once: signing below, the boot refusal
+ * (`dev-secrets.ts`'s `CursorSecretDevError`) and `@ultimat3/cli`'s deploy contract
+ * (`.env.example`, `x env check`, `x doctor`) all read this constant.
+ */
+export const CURSOR_SECRET_KEY = 'ULTIMATE_CURSOR_SECRET';
+
+/** The one fix for `X_CURSOR_SECRET_DEV`, wherever it is reported — the boot and the CLI. */
+export const CURSOR_SECRET_FIX = `export ${CURSOR_SECRET_KEY}="$(openssl rand -hex 32)"`;
 
 /** `configureCursorSigning`'s value, when an app has called it. `undefined` means "read the env". */
 let configured: string | undefined;
@@ -52,7 +62,7 @@ function currentSecret(): string {
   // `||`, never `??`: `ULTIMATE_CURSOR_SECRET=` (a blank compose or chart value) is the EMPTY
   // string, which `??` keeps — an HMAC keyed by '' that anyone can forge, while
   // `usesDevCursorSecret()` answered `false` and the boot check passed. Empty is unset.
-  return configured || Bun.env['ULTIMATE_CURSOR_SECRET'] || DEV_SECRET;
+  return configured || Bun.env[CURSOR_SECRET_KEY] || DEV_CURSOR_SECRET;
 }
 
 /**
@@ -77,9 +87,17 @@ export function resetCursorSigning(): void {
   configured = undefined;
 }
 
-/** True while cursors are signed with the shipped dev key — `x doctor` reports it. */
-export function usesDevCursorSecret(): boolean {
-  return currentSecret() === DEV_SECRET;
+/**
+ * True while cursors are signed with the shipped dev key. Bare, it asks THIS process — exactly what
+ * signing reads. With `env`, it asks that table the way signing would read it (`configured` first,
+ * then the key, empty counting as unset) — `@ultimat3/storage`'s `usesDevStorageSecret({ env })`
+ * twin, which `x env check` asks of a deploy's environment rather than of the CLI's own.
+ */
+export function usesDevCursorSecret(options?: {
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}): boolean {
+  if (options?.env === undefined) return currentSecret() === DEV_CURSOR_SECRET;
+  return (configured || options.env[CURSOR_SECRET_KEY] || DEV_CURSOR_SECRET) === DEV_CURSOR_SECRET;
 }
 
 /** `base64url(payload).signature`. Opaque by contract: callers must never parse it. */

package/src/deprecation.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 caller raises its own `X_*` for a date it cannot render.
+ *
+ * One home for `@ultimat3/action` and `@ultimat3/query`, which are both tier 3 and so cannot share
+ * a module sideways; their twins had already drifted in prose. `HELPER_HOMES` refuses a third.
+ */
+import { counter } from './metrics';
+
+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: OpenAPI `x-ultimate`, 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 and the one nothing in the framework could answer. 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, which is the cardinality mistake core's own overflow bucket exists to catch. Declared
+ * once, here: two declaring modules were two owners of one 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 its own route naming — the one the typed
+  // client uses. A link built here from the export name would be a second URL derivation.
+  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 };
+}

package/src/dev-secrets.ts

@@ -2,7 +2,7 @@
 // environment. `x doctor` reported it; nothing failed — so a production pod that forgot
 // ULTIMATE_CURSOR_SECRET signed every cursor with a key published in this package.
 
-import { usesDevCursorSecret } from './cursor';
+import { CURSOR_SECRET_FIX, CURSOR_SECRET_KEY, usesDevCursorSecret } from './cursor';
 import { isLocal } from './environment';
 import { UltimateError } from './errors';
 
@@ -14,14 +14,14 @@ export class CursorSecretDevError extends UltimateError {
   static readonly code = 'X_CURSOR_SECRET_DEV';
   override readonly name = 'CursorSecretDevError';
 
-  // One secret today, so the fix is a literal: a spliced name would be a value in a pasted command.
+  // The key and the fix are `cursor.ts`'s constants, never spelled here: `x doctor` and
+  // `x env check` report this code with `CURSOR_SECRET_FIX` too, and one code has one fix.
   constructor() {
     super({
       code: CursorSecretDevError.code,
-      cause:
-        'ULTIMATE_CURSOR_SECRET is unset or empty, so this process signs cursors with the development key the framework ships — anyone can forge a page position',
-      fix: "x secrets set ULTIMATE_CURSOR_SECRET — or export ULTIMATE_CURSOR_SECRET from the platform's secret store",
-      meta: { variable: 'ULTIMATE_CURSOR_SECRET' },
+      cause: `${CURSOR_SECRET_KEY} is unset or empty, so this process signs cursors with the development key the framework ships — anyone can forge a page position`,
+      fix: CURSOR_SECRET_FIX,
+      meta: { variable: CURSOR_SECRET_KEY },
     });
   }
 }
@@ -40,6 +40,17 @@ export interface DevSecretsOptions {
  * signing reads it, so this refuses what the process WILL sign with, not what `env` claims.
  */
 export function assertNoDevSecretsOutsideLocal(options: DevSecretsOptions = {}): void {
-  if (isLocal({ env: options.env, fallback: 'production' })) return;
+  if (!devSecretsRefused(options)) return;
   if (usesDevCursorSecret()) throw new CursorSecretDevError();
 }
+
+/**
+ * THE rule for whether an environment refuses a shipped development secret: anything but
+ * `development`/`test`, and a table naming no environment counts as production (fails closed).
+ * The boot asks it above; `@ultimat3/cli` asks it of a deploy's table (`x env check`, `x doctor`),
+ * so a diagnostic cannot call green an environment the boot refuses. Throws
+ * `X_ENVIRONMENT_INVALID` on an unknown `ULTIMATE_ENV`, as the boot does.
+ */
+export function devSecretsRefused(options: DevSecretsOptions = {}): boolean {
+  return !isLocal({ env: options.env, fallback: 'production' });
+}

package/src/drain-deadline.ts

@@ -0,0 +1,43 @@
+// Single responsibility: the drain budget's default and its domain — `drain.deadlineMs` in
+// `app.config.ts`. One module because the config validator, the lifecycle's own default and the
+// chart's grace period must all mean the same number.
+
+import { countIssue } from './config-count';
+import { readinessGraceIssue } from './lifecycle-grace';
+
+/**
+ * How long a SIGTERM'd process has to finish what it holds — in-flight requests, a running job's
+ * step — before the lifecycle abandons the rest. 25 s sits inside a 30 s kubelet grace with the
+ * teardown margin beside it; an app whose jobs run longer raises it, and the chart's
+ * `terminationGracePeriodSeconds` is derived from the raised number.
+ */
+export const DRAIN_DEADLINE_DEFAULT_MS = 25_000;
+
+/**
+ * An hour. Past it a deploy is not draining, it is waiting on work that should checkpoint: a step
+ * is the replay unit, so a job longer than this belongs in more steps, not a longer drain.
+ */
+export const DRAIN_DEADLINE_MAX_MS = 3_600_000;
+
+const DEADLINE_KEY = 'drain.deadlineMs';
+
+/**
+ * Why a value is not a drain budget, or `undefined` when it is one. A whole number of milliseconds
+ * in `1 ≤ v ≤ 3600000`. Zero is refused here although `configureLifecycle` accepts it: "drain now"
+ * is a test's or a tool's decision, never one a deployed app makes by typing it into its config.
+ */
+export function drainDeadlineIssue(value: unknown): string | undefined {
+  const count = countIssue(DEADLINE_KEY, value, 1);
+  if (count !== undefined) return count;
+  return (value as number) > DRAIN_DEADLINE_MAX_MS
+    ? `${DEADLINE_KEY} must be at most ${DRAIN_DEADLINE_MAX_MS} milliseconds — a longer drain is work that should checkpoint in steps, not a deploy waiting on it`
+    : undefined;
+}
+
+/** The `drain` section's issues, one per key, for `defineConfig`'s validator. */
+export function drainIssues(drain: {
+  readonly readinessGraceMs: unknown;
+  readonly deadlineMs: unknown;
+}): readonly (string | undefined)[] {
+  return [readinessGraceIssue(drain.readinessGraceMs), drainDeadlineIssue(drain.deadlineMs)];
+}