@ultimat3/core 11.2.0 → 12.0.0

package/CLAUDE.md

@@ -121,6 +121,7 @@ shape against a locally declared sample interface for exactly that reason.
 | how many at once | `flight-gate.ts` | hand-over on release, refusal past `maxQueued`, injectable `overflow:` refusal |
 | whether an answer still applies | `generation-fence.ts` | `X_SUPERSEDED` / `isSuperseded`; nothing else in the tree had one |
 | which HTTP statuses are worth repeating | `retryable-status.ts` | `>= 500` plus 408, 409, 425, 429 — the two byte-identical copies' set |
+| how long this request has left | `request-budget.ts` (`Ctx.deadlineAt`, `REQUEST_TIMEOUT_HEADER`) | `@ultimat3/http`'s `startDeadline` is the one production writer of the instant; `traceHeaders()` is the one writer of the header. It lives here because the READER is tier 2 and the WRITER is a typed client in tier 0, and a second literal for the header name is a propagation that stops working the day either string is edited. A spent budget sends nothing rather than `0` — the far side ignores anything under 1ms and falls back to its own, which is the failure the header exists to prevent, one hop later |
 | the five above, composed into one typed-client call | `client-flight.ts` + `client-wire.ts` | `@ultimat3/action` and `@ultimat3/query` both project a typed client and are both tier 3, so neither could import the other: it shipped as a byte-identical 288-line + 85-line copy in each, policed by a `client-twin.test.ts` in both. Both packages re-export these names, so their public surface is unchanged. Declares NO code of its own — `X_SUPERSEDED`, `X_TIMEOUT` and `X_FLIGHT_GATE_OVERLOADED` are already here |
 | is this `unknown` a keyed record? | `json-object.ts` | `isJsonObject`, which was the same three terms in both those packages' `stable.ts`. A `Date` and a class instance PASS: it narrows a shape, it does not certify provenance |
 | a value that must not be printed | `secret.ts` | redacted by VALUE; `revealSecret()` is the one way out, on purpose greppable |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "11.2.0",
+  "version": "12.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/client-wire.ts

@@ -1,6 +1,7 @@
 /**
- * What a typed client puts on the wire and reads back off it: the W3C trace header, the
- * problem+json body, and the immutable answer one dispatch hands to every caller sharing it.
+ * What a typed client puts on the wire and reads back off it: the ambient call context as
+ * headers — the W3C trace and the remaining request budget — the problem+json body, and the
+ * immutable answer one dispatch hands to every caller sharing it.
  *
  * Tier 0 because `@ultimat3/action` and `@ultimat3/query` need this identical file and are both
  * tier 3, so neither may import the other — the shape `canonical-json.ts` is already here for.
@@ -11,6 +12,7 @@
 import type { ErrorRetry } from './error-retry';
 import { declaredErrorRetry } from './error-retry';
 import { isJsonObject } from './json-object';
+import { budgetHeaders } from './request-budget';
 import { isRetryableStatus } from './retryable-status';
 import { currentSpanContext, traceparent } from './telemetry';
 
@@ -30,17 +32,31 @@ 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 call from
- * acquiring a CORS preflight it did not have.
+ * Everything this process knows about the call in flight, as headers: the W3C trace, and how much
+ * of the request budget is left. Both callers (`@ultimat3/action`'s `postOnce` and
+ * `@ultimat3/query`'s reader) spread it BEFORE the caller's own headers, so an explicit value
+ * still wins.
+ *
+ * The trace half: `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 call from acquiring a CORS preflight it did not
+ * have.
+ *
+ * The budget half is independent of it, and that is deliberate: a deadline must propagate through
+ * a hop that is not being traced. `budgetHeaders()` answers `{}` outside a request and for a
+ * context with no deadline, so a browser and a job are unchanged — the header only appears where
+ * something really is waiting on a socket.
+ *
+ * The name is the trace half's alone for one reason: renaming it means editing
+ * `packages/{action,query}/src/client.ts`, and both spell it as a value import.
  */
 export function traceHeaders(): Record<string, string> {
+  const budget = budgetHeaders();
   const context = currentSpanContext();
-  if (context === undefined) return {};
-  if (!TRACE_ID.test(context.traceId) || !SPAN_ID.test(context.spanId)) return {};
-  return { traceparent: traceparent(context) };
+  if (context === undefined) return budget;
+  if (!TRACE_ID.test(context.traceId) || !SPAN_ID.test(context.spanId)) return budget;
+  return { ...budget, traceparent: traceparent(context) };
 }
 
 /**

package/src/context.ts

@@ -52,6 +52,16 @@ export interface Ctx extends CtxServices {
   now(): Date;
   readonly logger: Logger;
   readonly signal: AbortSignal;
+  /**
+   * Epoch milliseconds this request's budget runs out at, or `null` when nothing set one.
+   *
+   * The value BEHIND `signal`, published as a number because a signal can only say "already over"
+   * — and every outbound hop needs to say how much is LEFT. Without it a service called at t=29 of
+   * a 30s budget started a fresh 30s of its own: real work, holding a pool slot and a vendor
+   * connection, for half a minute after the caller's socket was answered `X_TIMEOUT`. `null` for a
+   * job, a task and a CLI command, none of which has a caller waiting on a socket.
+   */
+  readonly deadlineAt: number | null;
   /** Late-bound services, for anything not worth a type augmentation. */
   readonly services: ServiceBag;
 }
@@ -67,6 +77,8 @@ export interface CtxInit {
   readonly clock?: Clock | undefined;
   readonly logger?: Logger | undefined;
   readonly signal?: AbortSignal | undefined;
+  /** Epoch ms. `@ultimat3/http`'s `startDeadline` is the one production writer. */
+  readonly deadlineAt?: number | undefined;
   readonly services?: ServiceBag | undefined;
 }
 
@@ -112,6 +124,7 @@ export function createContext(init: CtxInit = {}): Ctx {
     now: () => clock.now(),
     logger: base.child({ requestId, traceId: trace }),
     signal: init.signal ?? neverAborted,
+    deadlineAt: init.deadlineAt ?? null,
   };
   // A registered service (`defineService`) closes over the ctx it is built for — actor, clock,
   // tz — so it has to run HERE, against this exact call's fields, rather than once at boot and
@@ -191,6 +204,10 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
     role: patch.role ?? parent.role,
     clock: patch.clock ?? parent.clock,
     logger: patch.logger ?? parent.logger,
+    // One request, one budget: a child scope inherits the deadline for the same reason it
+    // inherits `requestId`. A patch may SHORTEN it (a step with its own budget); nothing here
+    // lengthens it, because the socket the parent is answering does not move.
+    deadlineAt: patch.deadlineAt ?? parent.deadlineAt ?? undefined,
     signal: patch.signal ?? parent.signal,
     services: { ...carried, ...(patch.services ?? {}) },
   });

package/src/env-example.ts

@@ -18,7 +18,7 @@ const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 export const ENV_EXAMPLE_PATH = '.env.example';
 
 /**
- * What Bun loads by itself, lowest precedence first — measured against Bun 1.3, not assumed.
+ * What Bun loads by itself, lowest precedence first — measured against Bun 1.4, not assumed.
  *
  * The mode is NOT `ULTIMATE_ENV` and not even `NODE_ENV` verbatim: Bun reads `.env.production`
  * for `NODE_ENV=production`, `.env.test` for `test`, and `.env.development` for **everything

package/src/index.ts

@@ -509,6 +509,11 @@ export {
   registerPrimitiveRegistrar,
   resetPrimitiveRegistrars,
 } from './registrar';
+export {
+  budgetHeaders,
+  REQUEST_TIMEOUT_HEADER,
+  remainingBudgetMs,
+} from './request-budget';
 export type { Err, Ok, Result } from './result';
 export { err, isErr, isOk, map, mapErr, ok, tryCatch, unwrap, unwrapOr } from './result';
 export type { RetryDecision, RetryDeps, RetryPolicy, RetryStopReason } from './retry';

package/src/request-budget.ts

@@ -0,0 +1,44 @@
+// How much of THIS request's budget is left, and the one header that carries it to the next hop.
+// The header name lives here rather than in `@ultimat3/http` because both ends need it and only
+// one of them is tier 2: the reader is http's `resolveTimeoutMs`, the writer is a typed client in
+// tier 0, and a second literal in the writer is a propagation that silently stops working the day
+// either string is edited.
+
+import type { Ctx } from './context';
+import { tryUseContext } from './context';
+
+/**
+ * A caller may SHORTEN the hop it is calling, never lengthen it — `@ultimat3/http`'s
+ * `resolveTimeoutMs` takes the minimum of its own configured budget and this. It had ONE reader
+ * and zero writers anywhere in the tree, so a 30s gateway budget that had already been spent to
+ * t=29 handed the next service a fresh 30s: work still running, still holding a pool slot and a
+ * vendor connection, 30 seconds after the caller's socket was answered `X_TIMEOUT`.
+ */
+export const REQUEST_TIMEOUT_HEADER = 'x-request-timeout-ms';
+
+/**
+ * Milliseconds left before this context's deadline, or `undefined` when there is no deadline or
+ * it has already passed.
+ *
+ * `undefined` for a spent budget rather than `0`, and that is not a nicety: the far side ignores
+ * anything under 1ms and falls back to its OWN configured budget, so a `0` on the wire reads as
+ * "the caller asked for nothing" — the exact failure this header exists to prevent, one hop later.
+ * Whether to make a call whose budget is gone is the caller's decision (`throwIfAborted`), not
+ * this function's.
+ */
+export const remainingBudgetMs = (ctx: Ctx): number | undefined => {
+  if (ctx.deadlineAt === null) return undefined;
+  const left = Math.floor(ctx.deadlineAt - ctx.now().getTime());
+  return left >= 1 ? left : undefined;
+};
+
+/**
+ * The budget header for the ambient request, or nothing. Rounded DOWN by `remainingBudgetMs`:
+ * a hop must never be told it has more time than the caller will wait.
+ */
+export const budgetHeaders = (): Record<string, string> => {
+  const ctx = tryUseContext();
+  if (ctx === undefined) return {};
+  const left = remainingBudgetMs(ctx);
+  return left === undefined ? {} : { [REQUEST_TIMEOUT_HEADER]: String(left) };
+};