@ultimat3/core 27.10.1 → 27.10.2

package/CLAUDE.md

@@ -6,14 +6,14 @@ change to every package.
 
 | Rule | |
 |---|---|
-| Deps | `@ultimat3/schema` only (`bun-types` for types) |
+| Deps | `@ultimat3/schema` only (`bun-types`: types) |
 | Errors | subclass `UltimateError`; never `throw new Error` |
 | Values in a message | `renderCauseValue()` / `renderFixLiteral()`; never raw `JSON.stringify`, `String()` or `${…}` on an `unknown` |
 | A value in a `fix:` a shell READS | `renderFixShellArg(value, placeholder)` — `renderFixLiteral`'s double quotes leave `$(…)`, `` ` `` and `${…}` live. An ordinary path or URL passes through; anything a shell would read becomes the placeholder |
 | Whether that value TRAVELS | `isFixShellSafe(value)`, the predicate `renderFixShellArg` is built on. A placeholder is not a runnable command, so a `fix:` whose value sits mid-command asks this first and emits PROSE when the answer is no (`@ultimat3/auth`'s `jwks.ts`, `@ultimat3/scraping`'s `profileLocked`) |
 | Rendering the 3-line format | nothing to remember — `UltimateError`'s CONSTRUCTOR escapes `code`, `title`, `cause`, `fix` and `docs` with `singleLine()`. Call it yourself only for a shape this class never built (a `Finding`) |
 | A value a CALLER supplied | `describeValue()` — shape, never content. `renderCauseValue` is safe against throwing, not against leaking |
-| Reading a caught value | `renderThrowable()` / `isThrownError()` / `stringField()`; never `error.message`, `instanceof Error` or `typeof error.code === 'string'` |
+| Reading a caught value | `renderThrowable()` / `isThrownError()` / `stringField()` / `failureStack()`; never `error.message`, `instanceof Error` or `typeof error.code === 'string'` |
 | New code | add to `CORE_CODE_TITLES` in `core-error-codes.ts` — a side-effect anchor the barrel bare-imports, so `UltimateError` alone never carries the table |
 | Where an error points | `ERROR_DOCS_URL` — one constant, never a per-code URL. `docs:` is omitted at construction and resolved from the registry |
 | Time | take a `Clock`; `Date.now()` / `new Date()` only inside `clock.ts` |

package/README.md

@@ -7,6 +7,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 |---|---|
 | `UltimateError`, the 3-line rendering, `--json` shape | `errors.ts` |
 | rendering an app's value into a `cause` / `fix` without throwing | `error-render.ts` |
+| a thrown value's stack, its `name: message` line restored when Bun dropped it — `failureStack` | `error-stack.ts` |
 | code → `{ title, docs }` registry, `registerErrorCodes()` | `error-codes.ts` |
 | the one lazy `AsyncLocalStorage`, every ambient scope in the framework | `async-context.ts` |
 | request context on that seam | `context.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "27.10.1",
+  "version": "27.10.2",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "27.10.1"
+    "@ultimat3/schema": "27.10.2"
   }
 }

package/src/client-dispatch.ts

@@ -50,11 +50,18 @@ export interface TransportRequest {
   /** This call's retry override, handed to the `flight`. */
   readonly retry?: ClientRetry | undefined;
   /**
-   * The decoded records envelope, after its records were adopted — only when the answer carried
+   * The decoded records envelope, after its records were adopted (with `adopt: false`, they are
+   * not; the caller adopts them) — only when the answer carried
    * `x-ultimate-records: 1` and belongs to the current principal. What a caller reads to know the
    * ORDER of `records[type]`, which the store (keyed, unordered) cannot give it back.
    */
   readonly onEnvelope?: ((envelope: RecordEnvelope) => void) | undefined;
+  /**
+   * `false`: the records are NOT adopted here — the caller adopts them from `onEnvelope`, inside a
+   * notification of its own. For a read whose rows must land together with something only the
+   * caller holds: a channel's catch-up and the frames held behind it (`@ultimat3/realtime`).
+   */
+  readonly adopt?: boolean | undefined;
   /**
    * How a 2xx body is read. `'json'` (the default) decodes it and adopts a records envelope;
    * `'text'` answers the body as a string, untouched — an HTML fragment, a CSV — sends

package/src/client-transport.ts

@@ -76,7 +76,7 @@ export async function clientTransport<T = unknown>(req: TransportRequest): Promi
   // A write that crossed a rescope HAS landed, so its caller is told — but its rows are the
   // previous principal's, and the new scope's store never sees them.
   if (current === issued) {
-    adopt(envelope);
+    if (req.adopt !== false) adopt(envelope);
     if (answer.enveloped) req.onEnvelope?.(envelope);
   }
   return envelope.data as T;

package/src/error-reporter.ts

@@ -6,7 +6,8 @@
 import { type Clock, systemClock } from './clock';
 import { tryUseContext } from './context';
 import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from './environment';
-import { renderThrowable, stringField } from './error-render';
+import { renderThrowable } from './error-render';
+import { failureStack } from './error-stack';
 import { toUltimateError } from './errors';
 import { logger } from './logger';
 import type { Role } from './roles';
@@ -181,9 +182,9 @@ export function errorReport(error: unknown, options: ReportErrorOptions): ErrorR
     meta: normalized.meta,
     // The thrown value's own stack, not the wrapper's: `toUltimateError` builds its `InternalError`
     // at this line, so the wrapper's stack points here rather than at the throw. Read through
-    // `stringField`, because `error instanceof Error` and `.stack` are both property operations
-    // on a caught value — and this function's own contract is that reporting never throws.
-    stack: stringField(error, 'stack') ?? normalized.stack,
+    // `failureStack` (total, and its header restored when Bun dropped it), because `.stack` is a
+    // property operation on a caught value — and reporting never throws.
+    stack: failureStack(error) ?? normalized.stack,
     resource: serviceResource(),
     environment: environmentNow(),
     release: release ?? ctx?.buildId ?? null,

package/src/error-stack.ts

@@ -0,0 +1,28 @@
+// The ONE reader of a thrown value's stack: `.stack`, opening with its own `name: message` line.
+// Bun 1.4 renders `.stack` lazily, and a full collection between the throw crossing an `await`
+// and the first read leaves it opening with a bare `Error` (#773) — the frames survive, the
+// header does not. The header is recomposed from the fields that did survive. Total: never throws.
+
+import { stringField } from './error-render';
+
+/** A stack's first line when it is a frame and not a header (`    at f (file:1:2)`). */
+const FRAME_LINE = /^\s+at\s/;
+
+/**
+ * `value.stack`, with the header restored when the runtime dropped it. A stack that already opens
+ * with the header — or that its author shaped some other way — is returned untouched.
+ */
+export function failureStack(value: unknown): string | undefined {
+  const stack = stringField(value, 'stack');
+  if (stack === undefined) return undefined;
+  const name = stringField(value, 'name') ?? 'Error';
+  const message = stringField(value, 'message') ?? '';
+  const header = message === '' ? name : `${name}: ${message}`;
+  if (stack.startsWith(header)) return stack;
+  const newline = stack.indexOf('\n');
+  const first = newline === -1 ? stack : stack.slice(0, newline);
+  // The lost header is exactly the base constructor's name with no message after it.
+  if (first === 'Error') return `${header}${newline === -1 ? '' : stack.slice(newline)}`;
+  if (FRAME_LINE.test(first)) return `${header}\n${stack}`;
+  return stack;
+}

package/src/exports/error-contract.ts

@@ -44,6 +44,7 @@ export {
   retryFor,
   statedDelayMs,
 } from '../error-retry';
+export { failureStack } from '../error-stack';
 export type {
   CodedErrorInit,
   ErrorAudience,

package/src/index.ts

@@ -309,6 +309,7 @@ export {
   ERROR_RETRY_KINDS,
   errorCodeSnapshot,
   errorRetry,
+  failureStack,
   fixFor,
   formatError,
   hasErrorCode,