@ultimat3/core 20.2.1 → 22.0.0

package/src/record-envelope.ts

@@ -0,0 +1,98 @@
+/**
+ * The records envelope: an action's or a query's answer plus the entity rows it touched, so the
+ * page's one store adopts them on the way past. Used ONLY behind `RECORDS_HEADER`, which is what
+ * keeps an output with no entity rows byte-identical on the wire. Pure and schema-free — the rows
+ * are validated by whoever owns the sink, never here.
+ */
+
+import type { Row } from './conflict-policy';
+import { UltimateError } from './errors';
+import { isJsonObject } from './json-object';
+
+/** Set to `1` on a response whose body is a `RecordEnvelope` rather than the bare output. */
+export const RECORDS_HEADER = 'x-ultimate-records';
+
+/** One record type's rows, keyed by record key — the browser cannot derive a key without the entity. */
+export type RecordRows = Readonly<Record<string, Row>>;
+
+export interface RecordEnvelope<T = unknown> {
+  readonly data: T;
+  /** Rows to adopt: record type -> record key -> row. */
+  readonly records?: Readonly<Record<string, RecordRows>>;
+  /** Record keys to drop, keyed by the entity's record type. */
+  readonly removed?: Readonly<Record<string, readonly string[]>>;
+}
+
+/** The server half. An empty `removed` is omitted, so the envelope never claims a deletion. */
+export function encodeRecordEnvelope<T>(
+  data: T,
+  records: Readonly<Record<string, RecordRows>>,
+  removed?: Readonly<Record<string, readonly string[]>>,
+): RecordEnvelope<T> {
+  const hasRemoved = removed !== undefined && Object.keys(removed).length > 0;
+  return hasRemoved ? { data, records, removed } : { data, records };
+}
+
+/**
+ * The client half: a parsed body, checked for shape and copied onto null-prototype maps — a
+ * record type and a record key are server data, and `JSON.parse` mints `__proto__` as a real own
+ * key, which assigned onto a plain object would replace its prototype.
+ */
+export function decodeRecordEnvelope(body: unknown): RecordEnvelope {
+  if (!isJsonObject(body) || !Object.hasOwn(body, 'data')) {
+    throw envelopeInvalid('the body', 'is not an object with an own "data" member');
+  }
+  const records = byType(body['records'], 'records', (rows, at) => {
+    if (!isJsonObject(rows)) throw envelopeInvalid(at, 'is not an object of rows by key');
+    return nullProto(
+      Object.entries(rows).map(([key, row], index): [string, Row] => {
+        if (!isJsonObject(row)) throw envelopeInvalid(`${at} row #${index}`, 'is not an object');
+        return [key, row];
+      }),
+    );
+  });
+  const removed = byType(body['removed'], 'removed', (keys, at) => {
+    if (!Array.isArray(keys)) throw envelopeInvalid(at, 'is not an array');
+    const list: unknown[] = keys;
+    const bad = list.findIndex((key) => typeof key !== 'string');
+    if (bad !== -1) throw envelopeInvalid(`${at} key #${bad}`, 'is not a string');
+    return list as string[];
+  });
+  return {
+    data: body['data'],
+    ...(records === undefined ? {} : { records }),
+    ...(removed === undefined ? {} : { removed }),
+  };
+}
+
+function byType<T>(
+  value: unknown,
+  member: string,
+  read: (group: unknown, at: string) => T,
+): Readonly<Record<string, T>> | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) throw envelopeInvalid(`"${member}"`, 'is not an object');
+  return nullProto(
+    Object.entries(value).map(([type, group], index): [string, T] => [
+      type,
+      read(group, `"${member}" entry #${index}`),
+    ]),
+  );
+}
+
+function nullProto<T>(entries: readonly (readonly [string, T])[]): Record<string, T> {
+  const out = Object.create(null) as Record<string, T>;
+  for (const [key, value] of entries) {
+    Object.defineProperty(out, key, { value, enumerable: true });
+  }
+  return out;
+}
+
+/** Positions only, never the value: the body is whatever answered, and may carry anything. */
+function envelopeInvalid(where: string, what: string): UltimateError {
+  return new UltimateError({
+    code: 'X_CLIENT_RECORD_ENVELOPE_INVALID',
+    cause: `a response marked ${RECORDS_HEADER}: 1 carried a body where ${where} ${what}`,
+    fix: 'build the body with encodeRecordEnvelope() from @ultimat3/core in the handler that set the header, or stop setting the header',
+  });
+}

package/src/record-sink.ts

@@ -0,0 +1,129 @@
+/**
+ * The ONE per-tab client handle, and the seam records flow through into it. Every island bundle
+ * carries its own copy of `@ultimat3/core`, so a module-scope singleton here would be one store
+ * PER ISLAND; the handle lives on `globalThis` under one `Symbol.for` key instead — the pattern
+ * `ultimate.error` already uses — and every copy resolves the same object.
+ */
+
+import type { ClientScope } from './client-scope';
+import { CLIENT_SCOPE_META } from './page-meta';
+import type { PendingRecords } from './pending-records';
+import { pendingRecords } from './pending-records';
+import type { RecordRows } from './record-envelope';
+
+/**
+ * Where decoded records land. `@ultimat3/realtime` installs the store. `adopt` MUST be idempotent
+ * per `recordType + key`: a deduped read hands one answer to several callers and each adopts it.
+ */
+export interface RecordSink {
+  /** `rows` is record key -> row: the key is the server's, the browser cannot derive it. */
+  adopt(recordType: string, rows: RecordRows): void;
+  remove(recordType: string, keys: readonly string[]): void;
+}
+
+export interface PageClient {
+  /**
+   * The record store — `undefined` until realtime installs one. ASSIGNING it is the one install
+   * path: records answered before then are held (browser pages only) and adopted into the new
+   * store once, on assignment. With no `document` (SSR, a test, a server) they are dropped.
+   */
+  store: RecordSink | undefined;
+  /** The page's one socket — typed by `@ultimat3/realtime`, which fills it. */
+  socket: unknown;
+  /** Who the page is acting for right now. Read-only here: `rescope()` is the one writer. */
+  readonly scope: ClientScope;
+}
+
+/** The mutable half `client-scope.ts` owns. On the handle, so every module copy shares it. */
+export interface ScopeCell {
+  current: ClientScope;
+  readonly listeners: Set<(next: ClientScope, prev: ClientScope) => void>;
+}
+
+/** Headers every outbound request carries, or nothing. See `outbound-headers.ts`. */
+export type OutboundHeaders = () => Readonly<Record<string, string>>;
+
+interface PageClientHandle extends PageClient {
+  readonly scopeCell: ScopeCell;
+  /** The early-records buffer, or `undefined` where there is no page to install a store on. */
+  readonly pending: PendingRecords | undefined;
+  outboundHeaders: OutboundHeaders | undefined;
+}
+
+const HANDLE_KEY: unique symbol = Symbol.for('ultimate.client');
+
+type HandleHost = { [HANDLE_KEY]?: PageClientHandle };
+
+/** Get-or-create. The only `globalThis` write in the client seam, and it happens on first call. */
+export function pageClient(): PageClient {
+  return handle();
+}
+
+/** The scope cell behind `pageClient().scope`. Internal: `client-scope.ts` is its one caller. */
+export function scopeCell(): ScopeCell {
+  return handle().scopeCell;
+}
+
+/**
+ * Where decoded records go RIGHT NOW: the installed store, else the browser's pending buffer, else
+ * nowhere. Internal: `client-transport.ts` is its one caller.
+ */
+export function recordSink(): RecordSink | undefined {
+  const client = handle();
+  return client.store ?? client.pending;
+}
+
+/** The early-records buffer, for `rescope()` to clear. Internal. */
+export function heldRecords(): PendingRecords | undefined {
+  return handle().pending;
+}
+
+/** The outbound-header slot. Internal: `outbound-headers.ts` writes it, the dispatch reads it. */
+export function outboundSlot(): { outboundHeaders: OutboundHeaders | undefined } {
+  return handle();
+}
+
+/**
+ * The principal the server rendered into the page, read ONCE, when the handle is created. Three
+ * answers: the tag's content, `null` for an empty tag (anonymous), `undefined` for no tag or no
+ * `document` at all (unscoped — nobody's page). A later change is `rescope()`'s, never a re-read.
+ */
+function renderedPrincipal(): string | null | undefined {
+  const doc: { querySelector?: (selector: string) => { content?: unknown } | null } | undefined =
+    Reflect.get(globalThis, 'document');
+  const tag = doc?.querySelector?.(`meta[name="${CLIENT_SCOPE_META}"]`);
+  if (tag === undefined || tag === null) return undefined;
+  return typeof tag.content === 'string' && tag.content !== '' ? tag.content : null;
+}
+
+function handle(): PageClientHandle {
+  const host = globalThis as HandleHost;
+  const existing = host[HANDLE_KEY];
+  if (existing !== undefined) return existing;
+  const cell: ScopeCell = {
+    current: { principal: renderedPrincipal(), epoch: 0 },
+    listeners: new Set(),
+  };
+  const pending = Reflect.has(globalThis, 'document') ? pendingRecords() : undefined;
+  let store: RecordSink | undefined;
+  const created: PageClientHandle = {
+    socket: undefined,
+    scopeCell: cell,
+    pending,
+    outboundHeaders: undefined,
+    get store(): RecordSink | undefined {
+      return store;
+    },
+    set store(next: RecordSink | undefined) {
+      store = next;
+      if (next !== undefined) pending?.drainInto(next);
+    },
+    get scope(): ClientScope {
+      return cell.current;
+    },
+  };
+  // Non-enumerable, so a test harness or a devtools dump walking `globalThis` never serialises
+  // the store through it.
+  Object.defineProperty(host, HANDLE_KEY, { value: created, configurable: true });
+  return created;
+}

package/src/schema-error-codes.ts

@@ -23,7 +23,7 @@ export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object
   ),
 );
 
-// Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because core does not own
+// Registered here rather than in `core-error-codes.ts`'s `CORE_CODE_TITLES` because core does not own
 // these codes — `@ultimat3/schema` does — and `registerErrorCodes` is the one mechanism that
 // raises `X_ERROR_CODE_DUPLICATE` if a package that DOES own one of them ever tries to register it
 // too, which pins ownership even though the registration happens here.

package/src/secrets-errors.ts

@@ -30,7 +30,7 @@ const SECRETS_ERROR_TITLES: Readonly<Record<SecretsErrorCode, string>> = {
   X_SECRETS_PLAINTEXT_INVALID: 'the decrypted secrets are not a flat map of env values',
 };
 
-// Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because these codes and the
+// Registered here rather than in `core-error-codes.ts`'s `CORE_CODE_TITLES` because these codes and the
 // module that throws them ship together: `registerErrorCodes` is the documented way a set of codes
 // joins the registry, and it raises `X_ERROR_CODE_DUPLICATE` if anything else ever claims one.
 registerErrorCodes(

package/src/secrets-store.ts

@@ -6,9 +6,11 @@
 // `node:fs` sync, by necessity twice over: Bun.write takes no mode, and a world-readable master key
 // is the whole failure this file exists to prevent — and `installSecrets()` runs once, at boot,
 // before the process is serving anything, so there is nothing for an async read to overlap with.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+// `renameSync` because Bun has no atomic-replace primitive, and `rmSync` to clear the temp file.
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 // Bun exposes no path-join primitive.
 import { join } from 'node:path';
+import { isUltimateError } from './errors';
 import type { SecretValues } from './secrets';
 import { masterKeyId, openSecrets, parseMasterKey, sealSecrets } from './secrets';
 import { SecretsFileMissingError, SecretsKeyMissingError } from './secrets-errors';
@@ -36,6 +38,38 @@ type EnvRecord = Record<string, string | undefined>;
 export const secretsPath = (root: string): string => join(root, SECRETS_FILE);
 export const masterKeyPath = (root: string): string => join(root, SECRETS_KEY_FILE);
 export const secretsFileExists = (root: string): boolean => existsSync(secretsPath(root));
+/**
+ * Where `x secrets rotate` STAGES a new key before sealing the committed file with it; the rename
+ * that makes it live comes last. One spelling, here, for the CLI and the runtime alike.
+ */
+export const stagedMasterKeyPath = (root: string): string => `${masterKeyPath(root)}.next`;
+
+/**
+ * The committed file, opened with `key` — or, when that key no longer opens it and a rotation left
+ * a staged key, with the staged one. A crash between the seal and the rename leaves exactly that
+ * state, and a process booting then could not read its own secrets. READ-ONLY: finishing the
+ * rotation (the rename) is `x secrets`'s recovery, never a booting process's — two replicas racing
+ * a rename is how a key gets lost. An env key is never second-guessed: the platform owns it.
+ */
+async function openWithStaged(
+  root: string,
+  key: MasterKeyRef,
+): Promise<{ readonly values: SecretValues; readonly key: MasterKeyRef }> {
+  try {
+    return { values: await readSecretsFile(root, key), key };
+  } catch (error) {
+    const staged = stagedMasterKeyPath(root);
+    const mismatch = isUltimateError(error) && error.code === 'X_SECRETS_KEY_MISMATCH';
+    if (!mismatch || key.source !== 'file' || !existsSync(staged)) throw error;
+    const candidate: MasterKeyRef = {
+      hex: readFileSync(staged, 'utf-8').trim(),
+      source: 'file',
+      at: staged,
+    };
+    // The staged key's own mismatch when neither opens it — the file's problem, not the key's.
+    return { values: await readSecretsFile(root, candidate), key: candidate };
+  }
+}
 
 /**
  * Env var first, key file second. That order is what makes one image run everywhere: a container
@@ -83,10 +117,23 @@ export async function writeSecretsFile(
   return path;
 }
 
-/** Write the master key at 0600. Callers must have made the ignore rule true first. */
+/**
+ * Write the master key at 0600. Callers must have made the ignore rule true first.
+ *
+ * Through a fresh temp file renamed over the target, never a write in place: `mode` applies only
+ * when a write CREATES the file, so rotating over a key that was 0644 left the new key 0644. The
+ * rename is also atomic — a reader sees the old key or the new one, never half of either.
+ */
 export function writeMasterKeyFile(root: string, keyHex: string): string {
   const path = masterKeyPath(root);
-  writeFileSync(path, `${keyHex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE });
+  const temp = `${path}.${crypto.randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${keyHex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE, flag: 'wx' });
+    renameSync(temp, path);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
   return path;
 }
 
@@ -149,8 +196,7 @@ export async function installSecrets(
       skipped: [],
     };
   }
-  const key = requireMasterKey(root, env);
-  const values = await readSecretsFile(root, key);
+  const { values, key } = await openWithStaged(root, requireMasterKey(root, env));
   const installed: string[] = [];
   const skipped: string[] = [];
   for (const [name, value] of Object.entries(values)) {

package/src/service.ts

@@ -64,3 +64,12 @@ export function installedServices(ctx: CtxFacts): ServiceBag {
 export function resetServices(): void {
   factories.clear();
 }
+
+/**
+ * The names `installedServices` would build, without building them. `@ultimat3/http` binds each as
+ * a lazy member of a request context, because the actor a request's services must close over is
+ * only known once its `auth` stage has run — after the context exists.
+ */
+export function registeredServiceNames(): readonly string[] {
+  return [...factories.keys()];
+}

package/src/source-mask.ts

@@ -27,11 +27,41 @@ export function endOfLiteral(text: string, from: number): number {
   for (let i = from + 1; i < text.length; i += 1) {
     if (text[i] === '\\') i += 1;
     else if (text[i] === quote) return i + 1;
+    else if (spansLines && text[i] === '$' && text[i + 1] === '{')
+      i = endOfInterpolation(text, i + 2) - 1;
     else if (!spansLines && text[i] === '\n') return from + 1;
   }
   return spansLines ? text.length : from + 1;
 }
 
+/**
+ * Index just past the `}` closing a template's `${` whose body starts at `from`. The body is CODE:
+ * braces nest, and a string or a template inside it is skipped whole — a nested template's backtick
+ * read as the outer one's close desynced every literal after it, and `scripts/guards-doc.ts` lost
+ * every `code:` below the nesting to the gate. Comments in the body are skipped the same way.
+ */
+function endOfInterpolation(text: string, from: number): number {
+  let depth = 1;
+  let i = from;
+  while (i < text.length) {
+    const ch = text[i] as string;
+    if (ch === '/' && (text[i + 1] === '/' || text[i + 1] === '*')) {
+      const line = text[i + 1] === '/';
+      const end = line ? text.indexOf('\n', i) : text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : line ? end : end + 2;
+    } else if (QUOTES.has(ch)) i = endOfLiteral(text, i);
+    else if (ch === '{') {
+      depth += 1;
+      i += 1;
+    } else if (ch === '}') {
+      depth -= 1;
+      i += 1;
+      if (depth === 0) return i;
+    } else i += 1;
+  }
+  return text.length;
+}
+
 /**
  * Whether the `/` at `at` opens a regex rather than divides — the call no scanner without a parser
  * avoids. A regex cannot follow what ends an expression: an identifier that is not one of the words

package/src/telemetry.ts

@@ -8,6 +8,7 @@ import { tryUseContext } from './context';
 import { renderThrowable } from './error-render';
 import { isUltimateError } from './errors';
 import { isSpanId, isTraceId, spanId as newSpanId, traceId as newTraceId } from './ids';
+import { installTraceHeaders } from './outbound-headers';
 import { defaultSampler, resetDefaultSampler, type Sampler } from './sampler';
 
 export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
@@ -194,6 +195,8 @@ function inboundParent(parent: SpanContext | undefined): SpanContext | undefined
 }
 
 export function startSpan(name: string, options?: StartSpanOptions): Span {
+  // A live span is what gives an outbound typed call a trace to continue; see the module.
+  installTraceHeaders();
   const parent = options?.parent ?? currentSpanContext();
   const inbound = inboundParent(parent);
   const attributes: Record<string, AttributeValue> = { ...(options?.attributes ?? {}) };

package/src/type-pins.ts

@@ -132,6 +132,15 @@ type _RealtimeConfigCarriesNoDeadField = Assert<
   Extract<keyof RealtimeConfig, DeadRealtimeField> extends never ? true : false
 >;
 
+/**
+ * `'redis'` accepted, built by nothing, and booted whichever bus `NATS_URL` chose — removed in
+ * 22.0.0 when `selectTransport` began building what `transport` says. Re-adding it to the union is
+ * a type that promises a bus the framework does not have.
+ */
+type _RealtimeTransportHasNoRedis = Assert<
+  'redis' extends RealtimeConfig['transport'] ? false : true
+>;
+
 /** And the input side with it — `Input<RealtimeConfig>` is what an `app.config.ts` writes. */
 type _RealtimeInputCarriesNoDeadField = Assert<
   Extract<keyof NonNullable<AppConfigInput['realtime']>, DeadRealtimeField> extends never

package/src/write-digest.ts

@@ -0,0 +1,29 @@
+// A write's public name: the digest of the idempotency key the page sent it under. The server
+// stamps it on every `records` frame the write produced; the page computes the same digest from
+// its own key, so it can tell its own echo from somebody else's change. A digest, never the key:
+// a frame fans out to every member of the channel, and the key is only the writer's to show.
+
+/** Hex characters kept from the SHA-256: 128 bits, no collision between two writes in flight. */
+export const WRITE_DIGEST_LENGTH = 32;
+
+const WRITE_DIGEST_SHAPE = /^[0-9a-f]{32}$/;
+
+/** Whether `value` is a write digest as this module mints one — what a decoder admits. */
+export function isWriteDigest(value: unknown): value is string {
+  return typeof value === 'string' && WRITE_DIGEST_SHAPE.test(value);
+}
+
+/**
+ * SHA-256 of the key, hex, first `WRITE_DIGEST_LENGTH` characters. `undefined` where the runtime
+ * has no `crypto.subtle` — a browser page served over plain HTTP from a host that is not
+ * `localhost`. The page then names none of its writes and every frame is a plain merge, which is
+ * the behaviour before frames named their write: a flicker at worst, never a wrong row.
+ */
+export async function writeDigest(key: string): Promise<string | undefined> {
+  const subtle: SubtleCrypto | undefined = globalThis.crypto?.subtle;
+  if (subtle === undefined) return undefined;
+  const bytes = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(key)));
+  let hex = '';
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, '0');
+  return hex.slice(0, WRITE_DIGEST_LENGTH);
+}

package/src/write-origin.ts

@@ -0,0 +1,31 @@
+// The write in flight on the server: the digest of the idempotency key the request that is
+// running arrived with. `@ultimat3/action`'s HTTP projection opens the scope; the layers that turn
+// a committed row into a `records` frame read it — entity's row observer in-process, and the
+// Postgres driver, which writes it into the WAL for the replicator to find. Server-only: it rides
+// core's one `AsyncLocalStorage` seam, which a browser bundle does not have.
+
+import { asyncContext } from './async-context';
+import { isWriteDigest } from './write-digest';
+
+const origin = asyncContext<string>('the write origin');
+
+/**
+ * The `pg_logical_emit_message` prefix a keyed write's transaction opens with, its content the
+ * digest. `@ultimat3/entity`'s Postgres driver writes it; `@ultimat3/realtime`'s replication stream
+ * reads it and names every change of that transaction. One constant, so the two cannot drift.
+ */
+export const WRITE_ORIGIN_WAL_PREFIX = 'ultimate.write';
+
+/**
+ * Run `fn` as the write named `digest` (`writeDigest(key)`). Anything but a digest runs `fn`
+ * unnamed — the scope is a label on frames, never a gate, so a malformed one costs the page its
+ * echo match and nothing else.
+ */
+export function withWriteOrigin<T>(digest: string | undefined, fn: () => T): T {
+  return isWriteDigest(digest) ? origin.run(digest, fn) : fn();
+}
+
+/** The digest of the write this code runs inside, or `undefined` outside every keyed write. */
+export function currentWriteOrigin(): string | undefined {
+  return origin.get();
+}

package/src/result.ts

@@ -1,78 +0,0 @@
-// Single responsibility: `Result<T, E>` for boundaries where throwing is wrong —
-// validation seams, driver probes, CLI commands that must render `--json` either way.
-
-import { toUltimateError, type UltimateError } from './errors';
-
-export interface Ok<T> {
-  readonly ok: true;
-  readonly value: T;
-}
-
-export interface Err<E> {
-  readonly ok: false;
-  readonly error: E;
-}
-
-export type Result<T, E = UltimateError> = Ok<T> | Err<E>;
-
-export function ok<T>(value: T): Ok<T> {
-  return { ok: true, value };
-}
-
-export function err<E>(error: E): Err<E> {
-  return { ok: false, error };
-}
-
-export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
-  return result.ok;
-}
-
-export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
-  return !result.ok;
-}
-
-export function map<T, E, U>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> {
-  return result.ok ? ok(fn(result.value)) : result;
-}
-
-export function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> {
-  return result.ok ? result : err(fn(result.error));
-}
-
-export function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T {
-  return result.ok ? result.value : fallback;
-}
-
-/** Throws the contained error — use only where a throw is genuinely correct. */
-export function unwrap<T, E>(result: Result<T, E>): T {
-  if (result.ok) return result.value;
-  throw toUltimateError(result.error);
-}
-
-export function tryCatch<T>(fn: () => Promise<T>): Promise<Result<T, UltimateError>>;
-export function tryCatch<T>(fn: () => T): Result<T, UltimateError>;
-export function tryCatch<T>(
-  fn: () => T | Promise<T>,
-): Result<T, UltimateError> | Promise<Result<T, UltimateError>> {
-  try {
-    const value = fn();
-    if (isPromiseLike(value)) {
-      return value.then(
-        (resolved) => ok(resolved),
-        (reason: unknown) => err(toUltimateError(reason)),
-      );
-    }
-    return ok(value);
-  } catch (thrown) {
-    return err(toUltimateError(thrown));
-  }
-}
-
-function isPromiseLike<T>(value: T | Promise<T>): value is Promise<T> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'then' in value &&
-    typeof (value as { then: unknown }).then === 'function'
-  );
-}