@ultimat3/core 23.0.0 → 25.0.0

package/src/cookie.ts

@@ -0,0 +1,299 @@
+// 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
+ * `URIError` — which escapes every coded path that reads through here: an OAuth callback would
+ * answer 500 instead of `X_OAUTH_STATE_INVALID`, and `curl -H 'Cookie: x-locale=%'` paged the
+ * on-call from the `locale` stage. The raw value is returned instead, so the caller's own
+ * rejection stays the readable failure; a raw value is still checked against a signature, a stored
+ * hash or a `supported` list, and none of them match a mangled one.
+ */
+const decodeCookieValue = (raw: string): string => {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+};
+
+/**
+ * The value of cookie `name` in a `Cookie:` header, or `null` when the header or the cookie is
+ * absent. Never throws: the header is client-authored, so an unreadable value is the raw value and
+ * a header that is not a string at all is no cookie.
+ */
+export function readCookie(header: string | null | undefined, name: string): string | null {
+  if (typeof header !== 'string') return null;
+  for (const part of header.split(';')) {
+    const equals = part.indexOf('=');
+    if (equals === -1) continue;
+    if (part.slice(0, equals).trim() !== name) continue;
+    return decodeCookieValue(part.slice(equals + 1).trim());
+  }
+  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;
@@ -49,7 +59,10 @@ let configured: string | undefined;
  * warned and nothing failed.
  */
 function currentSecret(): string {
-  return configured ?? Bun.env['ULTIMATE_CURSOR_SECRET'] ?? DEV_SECRET;
+  // `||`, 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[CURSOR_SECRET_KEY] || DEV_CURSOR_SECRET;
 }
 
 /**
@@ -74,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/decimal-order.ts

@@ -10,10 +10,11 @@
  * and a keyset page boundary was cut where the database never cuts one.
  *
  * It answers `undefined` rather than guessing, and that is the whole of its contract: a caller
- * that knows the column's declared kind (`@ultimat3/entity`'s `compareByKind`) asks; a caller that
- * does NOT know it — `@ultimat3/query`, whose `OrderKey` is a name and a direction — must not,
- * because Postgres orders a `text` column holding `"10"` and `"9"` lexically and a comparator
- * guessing "both sides look like decimals" would disagree with the SQL it printed.
+ * that knows the column's declared kind asks — `@ultimat3/entity`'s `numericOrder`, behind
+ * `compareByKind`, which `@ultimat3/query` calls with the kind it resolves from the entity — and a
+ * caller with NO kind in hand must not, because Postgres orders a `text` column holding `"10"` and
+ * `"9"` lexically and a comparator guessing "both sides look like decimals" would disagree with
+ * the SQL it printed.
  */
 
 /** A decimal, split so two of them can be compared exactly however long the digits run. */

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, 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)];
+}

package/src/env-example.ts

@@ -2,16 +2,12 @@
 // second hand-maintained list. Render it from the declarations, and report drift when the file on
 // disk has fallen behind. Loading `.env` itself is Bun's job — see `envFileCandidates()`.
 
-import type { EnvSchema, EnvVarDecl } from './env';
-import { type CodedErrorInit, UltimateError } from './errors';
+//
+// It REPORTS and never throws. `assertEnvExample` and its `EnvExampleDriftError` were deleted in
+// 25.0.0: a second, weaker gate nothing called. `X_ENV_EXAMPLE_DRIFT` is `x verify`'s `manifest`
+// step's finding (`@ultimat3/cli`'s `app-env.ts`), byte-for-byte against `renderEnvExample`.
 
-export class EnvExampleDriftError extends UltimateError {
-  static readonly code = 'X_ENV_EXAMPLE_DRIFT';
-  override readonly name = 'EnvExampleDriftError';
-  constructor(init: CodedErrorInit) {
-    super({ ...init, code: EnvExampleDriftError.code });
-  }
-}
+import type { EnvSchema, EnvVarDecl } from './env';
 
 const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -99,11 +95,10 @@ export interface EnvExampleReport {
   /**
    * In the file, not in the schema — never fatal, because apps set keys nothing declares.
    *
-   * NOT reported on its own, and the comment here said it was. `ok` is `missing.length === 0`, so
-   * an example carrying only extra keys returns `ok: true` and `assertEnvExample` never builds an
-   * error: the list reaches a surface only as `meta` on a drift some MISSING key already raised.
-   * A caller that wants it reads `checkEnvExample(...).extra` itself, which is why this stays
-   * public. `env-example.test.ts` pins both halves.
+   * NOT reported on its own. `ok` is `missing.length === 0`, so an example carrying only extra
+   * keys returns `ok: true`; the framework's reporter (`@ultimat3/cli`'s `app-env.ts`) builds its
+   * finding from `missing` only. A caller that wants it reads `checkEnvExample(...).extra` itself,
+   * which is why this stays public. `env-example.test.ts` pins it.
    */
   readonly extra: readonly string[];
 }
@@ -115,18 +110,3 @@ export function checkEnvExample(schema: EnvSchema, text: string): EnvExampleRepo
   const extra = [...present].filter((key) => !declared.includes(key));
   return { ok: missing.length === 0, missing, extra };
 }
-
-/**
- * Throws `X_ENV_EXAMPLE_DRIFT` when the committed example has fallen behind the schema — the
- * failure an agent hits *before* a teammate hits `X_ENV_MISSING` on a variable nobody told them
- * about.
- */
-export function assertEnvExample(schema: EnvSchema, text: string, path = ENV_EXAMPLE_PATH): void {
-  const report = checkEnvExample(schema, text);
-  if (report.ok) return;
-  throw new EnvExampleDriftError({
-    cause: `${path} does not declare ${report.missing.join(', ')}, declared by defineEnv()`,
-    fix: `Bun.write('${path}', renderEnvExample(schema)) — regenerate it from the declarations`,
-    meta: { path, missing: report.missing, extra: report.extra },
-  });
-}