@ontrails/core 1.0.0-beta.4 → 1.0.0-beta.41

package/src/schedule.ts

@@ -0,0 +1,326 @@
+import { ValidationError } from './errors.js';
+import type {
+  ActivationSource,
+  ActivationSourceMeta,
+} from './activation-source.js';
+
+type ScheduleInputDefault = Record<string, never>;
+
+export interface ScheduleSpec<TInput = unknown> {
+  readonly cron: string;
+  readonly input?: TInput | undefined;
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly timezone?: string | undefined;
+  /** Reserved for future schedule-specific design; trail versioning is trail-only. */
+  readonly version?: never;
+}
+
+export interface ScheduleSource<TInput = unknown> extends ActivationSource {
+  readonly cron: string;
+  readonly input: TInput;
+  readonly kind: 'schedule';
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly timezone?: string | undefined;
+}
+
+export interface ScheduleValidationIssue {
+  readonly field: 'cron' | 'input' | 'timezone';
+  readonly message: string;
+}
+
+const CRON_FIELD_BOUNDS = Object.freeze([
+  { max: 59, min: 0, name: 'minute' },
+  { max: 23, min: 0, name: 'hour' },
+  { max: 31, min: 1, name: 'day of month' },
+  { max: 12, min: 1, name: 'month' },
+  { max: 7, min: 0, name: 'day of week' },
+] as const);
+
+const EMPTY_INPUT = Object.freeze({}) as ScheduleInputDefault;
+
+const normalizeCron = (cron: string): string =>
+  cron.trim().replaceAll(/\s+/g, ' ');
+
+const isIntegerToken = (value: string): boolean => /^\d+$/.test(value);
+
+const parseIntegerToken = (value: string): number | undefined =>
+  isIntegerToken(value) ? Number.parseInt(value, 10) : undefined;
+
+const isNumberInRange = (
+  value: string,
+  bounds: (typeof CRON_FIELD_BOUNDS)[number]
+): boolean => {
+  const parsed = parseIntegerToken(value);
+  return parsed !== undefined && parsed >= bounds.min && parsed <= bounds.max;
+};
+
+const isCronAtomValid = (
+  atom: string,
+  bounds: (typeof CRON_FIELD_BOUNDS)[number]
+): boolean => {
+  if (atom === '*') {
+    return true;
+  }
+  if (isNumberInRange(atom, bounds)) {
+    return true;
+  }
+
+  const range = atom.split('-');
+  if (range.length !== 2) {
+    return false;
+  }
+  const [rangeStart, rangeEnd] = range;
+  if (rangeStart === undefined || rangeEnd === undefined) {
+    return false;
+  }
+  if (
+    !isNumberInRange(rangeStart, bounds) ||
+    !isNumberInRange(rangeEnd, bounds)
+  ) {
+    return false;
+  }
+  const start = Number.parseInt(rangeStart, 10);
+  const end = Number.parseInt(rangeEnd, 10);
+  return start <= end;
+};
+
+const isCronPartValid = (
+  part: string,
+  bounds: (typeof CRON_FIELD_BOUNDS)[number]
+): boolean => {
+  const stepped = part.split('/');
+  if (stepped.length > 2) {
+    return false;
+  }
+  const [atom, step] = stepped;
+  if (!atom || !isCronAtomValid(atom, bounds)) {
+    return false;
+  }
+  if (step === undefined) {
+    return true;
+  }
+  const parsedStep = parseIntegerToken(step);
+  return parsedStep !== undefined && parsedStep > 0;
+};
+
+const validateCronField = (
+  field: string,
+  bounds: (typeof CRON_FIELD_BOUNDS)[number]
+): string | undefined => {
+  if (field.length === 0) {
+    return `${bounds.name} field is empty`;
+  }
+  const parts = field.split(',');
+  return parts.every((part) => isCronPartValid(part, bounds))
+    ? undefined
+    : `${bounds.name} field is not a supported cron expression`;
+};
+
+const validateCron = (cron: unknown): ScheduleValidationIssue[] => {
+  if (typeof cron !== 'string' || cron.trim().length === 0) {
+    return [
+      { field: 'cron', message: 'Cron expression must be a non-empty string' },
+    ];
+  }
+
+  const normalized = normalizeCron(cron);
+  const fields = normalized.split(' ');
+  if (fields.length !== CRON_FIELD_BOUNDS.length) {
+    return [
+      {
+        field: 'cron',
+        message: 'Cron expression must contain exactly five fields',
+      },
+    ];
+  }
+
+  return fields.flatMap((field, index) => {
+    const bounds = CRON_FIELD_BOUNDS[index];
+    if (!bounds) {
+      return [];
+    }
+    const issue = validateCronField(field, bounds);
+    return issue === undefined
+      ? []
+      : [{ field: 'cron' as const, message: issue }];
+  });
+};
+
+const isTimezoneValid = (timezone: string): boolean => {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: timezone }).format();
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const validateTimezone = (
+  timezone: unknown
+): readonly ScheduleValidationIssue[] => {
+  if (timezone === undefined) {
+    return [];
+  }
+  if (typeof timezone !== 'string' || timezone.trim().length === 0) {
+    return [
+      {
+        field: 'timezone',
+        message: 'Timezone must be a non-empty IANA timezone string',
+      },
+    ];
+  }
+  return isTimezoneValid(timezone.trim())
+    ? []
+    : [
+        {
+          field: 'timezone',
+          message: `Timezone "${timezone}" is not supported by Intl.DateTimeFormat`,
+        },
+      ];
+};
+
+const isNonJsonLeaf = (value: unknown): boolean => {
+  if (value === undefined) {
+    return true;
+  }
+  const kind = typeof value;
+  if (kind === 'function' || kind === 'symbol' || kind === 'bigint') {
+    return true;
+  }
+  return (
+    value instanceof Date ||
+    value instanceof RegExp ||
+    value instanceof Map ||
+    value instanceof Set
+  );
+};
+
+const containsNonSerializableLeaf = (
+  value: unknown,
+  seen: WeakSet<object>
+): boolean => {
+  if (isNonJsonLeaf(value)) {
+    return true;
+  }
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  if (seen.has(value)) {
+    return true;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.some((entry) => containsNonSerializableLeaf(entry, seen));
+  }
+  return Object.values(value).some((entry) =>
+    containsNonSerializableLeaf(entry, seen)
+  );
+};
+
+const validateInput = (input: unknown): readonly ScheduleValidationIssue[] => {
+  if (containsNonSerializableLeaf(input, new WeakSet<object>())) {
+    return [
+      {
+        field: 'input',
+        message: 'Schedule input must be JSON-serializable data',
+      },
+    ];
+  }
+  try {
+    JSON.stringify(input);
+    return [];
+  } catch {
+    return [
+      {
+        field: 'input',
+        message: 'Schedule input must be JSON-serializable data',
+      },
+    ];
+  }
+};
+
+const scheduleIssuesMessage = (
+  id: string,
+  issues: readonly ScheduleValidationIssue[]
+): string =>
+  `schedule("${id}") is invalid: ${issues.map((issue) => `${issue.field}: ${issue.message}`).join('; ')}`;
+
+const assertScheduleSpec = (
+  id: string,
+  spec: ScheduleSpec
+): {
+  readonly cron: string;
+  readonly input: unknown;
+  readonly timezone?: string | undefined;
+} => {
+  const input = spec.input === undefined ? EMPTY_INPUT : spec.input;
+  const timezone = spec.timezone?.trim();
+  const issues = [
+    ...validateCron(spec.cron),
+    ...validateTimezone(timezone),
+    ...validateInput(input),
+  ];
+
+  if (issues.length > 0) {
+    throw new ValidationError(scheduleIssuesMessage(id, issues), {
+      context: { issues },
+    });
+  }
+
+  return {
+    cron: normalizeCron(spec.cron),
+    input,
+    ...(timezone === undefined ? {} : { timezone }),
+  };
+};
+
+export const validateScheduleSource = (
+  source: ActivationSource
+): readonly ScheduleValidationIssue[] => {
+  if (source.kind !== 'schedule') {
+    return [];
+  }
+  const input = Object.hasOwn(source, 'input') ? source.input : EMPTY_INPUT;
+  return [
+    ...validateCron(source.cron),
+    ...validateTimezone(source.timezone),
+    ...validateInput(input),
+  ];
+};
+
+export function schedule<TInput>(
+  id: string,
+  spec: ScheduleSpec<TInput> & { readonly input: TInput }
+): ScheduleSource<TInput>;
+export function schedule(
+  id: string,
+  spec: ScheduleSpec
+): ScheduleSource<ScheduleInputDefault>;
+export function schedule<TInput>(
+  spec: ScheduleSpec<TInput> & { readonly id: string; readonly input: TInput }
+): ScheduleSource<TInput>;
+export function schedule(
+  spec: ScheduleSpec & { readonly id: string }
+): ScheduleSource<ScheduleInputDefault>;
+export function schedule<TInput>(
+  idOrSpec: string | (ScheduleSpec<TInput> & { readonly id: string }),
+  maybeSpec?: ScheduleSpec<TInput>
+): ScheduleSource<TInput | ScheduleInputDefault> {
+  const id = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
+  // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
+  const spec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
+  const normalized = assertScheduleSpec(id, spec);
+
+  return Object.freeze({
+    cron: normalized.cron,
+    id,
+    input: normalized.input as TInput | ScheduleInputDefault,
+    kind: 'schedule' as const,
+    ...(spec.meta === undefined
+      ? {}
+      : { meta: Object.freeze({ ...spec.meta }) }),
+    ...(normalized.timezone === undefined
+      ? {}
+      : { timezone: normalized.timezone }),
+  });
+}

package/src/serialization.ts

@@ -7,21 +7,26 @@
 
 import type { ErrorCategory, TrailsError } from './errors.js';
 import {
+  AuthError,
+  CancelledError,
+  ConflictError,
   ValidationError,
-  AmbiguousError,
-  AssertionError,
+  InternalError,
+  NetworkError,
   NotFoundError,
-  AlreadyExistsError,
-  ConflictError,
   PermissionError,
-  TimeoutError,
   RateLimitError,
-  NetworkError,
-  InternalError,
-  AuthError,
-  CancelledError,
+  RetryExhaustedError,
+  TimeoutError,
+  WorkspaceShiftError,
+  errorClasses,
   isTrailsError,
 } from './errors.js';
+import {
+  redactErrorContext,
+  redactErrorStack,
+  redactErrorString,
+} from './error-projection.js';
 import { Result } from './result.js';
 
 // ---------------------------------------------------------------------------
@@ -31,7 +36,10 @@ import { Result } from './result.js';
 export interface SerializedError {
   readonly name: string;
   readonly message: string;
+  readonly attempts?: number | undefined;
   readonly category?: ErrorCategory | undefined;
+  readonly cause?: SerializedError | undefined;
+  readonly detour?: string | undefined;
   readonly retryable?: boolean | undefined;
   readonly retryAfter?: number | undefined;
   readonly context?: Record<string, unknown> | undefined;
@@ -56,10 +64,15 @@ const buildOpts = (
 
 type ErrorFactory = (
   message: string,
-  opts: { context?: Record<string, unknown> },
+  opts: { cause?: Error; context?: Record<string, unknown> },
   retryAfter: number | undefined
 ) => TrailsError;
 
+type FixedErrorConstructor = new (
+  message: string,
+  options?: { cause?: Error; context?: Record<string, unknown> }
+) => TrailsError;
+
 const errorFactories: Record<ErrorCategory, ErrorFactory> = {
   auth: (msg, opts) => new AuthError(msg, opts),
   cancelled: (msg, opts) => new CancelledError(msg, opts),
@@ -77,6 +90,7 @@ const errorFactories: Record<ErrorCategory, ErrorFactory> = {
     }
     return new RateLimitError(msg, rlOpts);
   },
+  shift: (msg, opts) => new WorkspaceShiftError(msg, opts),
   timeout: (msg, opts) => new TimeoutError(msg, opts),
   validation: (msg, opts) => new ValidationError(msg, opts),
 };
@@ -92,30 +106,42 @@ const createErrorByCategory = (
   return factory(message, opts, retryAfter);
 };
 
-/** Map error class names to their constructors for precise round-tripping. */
-const errorConstructorsByName: Record<string, ErrorFactory> = {
-  AlreadyExistsError: (msg, opts) => new AlreadyExistsError(msg, opts),
-  AmbiguousError: (msg, opts) => new AmbiguousError(msg, opts),
-  AssertionError: (msg, opts) => new AssertionError(msg, opts),
-  AuthError: (msg, opts) => new AuthError(msg, opts),
-  CancelledError: (msg, opts) => new CancelledError(msg, opts),
-  ConflictError: (msg, opts) => new ConflictError(msg, opts),
-  InternalError: (msg, opts) => new InternalError(msg, opts),
-  NetworkError: (msg, opts) => new NetworkError(msg, opts),
-  NotFoundError: (msg, opts) => new NotFoundError(msg, opts),
-  PermissionError: (msg, opts) => new PermissionError(msg, opts),
-  RateLimitError: (msg, opts, retryAfter) => {
-    const rlOpts: { context?: Record<string, unknown>; retryAfter?: number } = {
-      ...opts,
-    };
-    if (retryAfter !== undefined) {
-      rlOpts.retryAfter = retryAfter;
-    }
-    return new RateLimitError(msg, rlOpts);
-  },
-  TimeoutError: (msg, opts) => new TimeoutError(msg, opts),
-  ValidationError: (msg, opts) => new ValidationError(msg, opts),
-};
+/** Map fixed error class names to constructors for precise round-tripping. */
+const errorConstructorsByName: Readonly<Record<string, ErrorFactory>> =
+  Object.fromEntries(
+    errorClasses.flatMap((entry): [string, ErrorFactory][] => {
+      if (entry.category === 'dynamic') {
+        return [];
+      }
+      const ctor = entry.ctor as FixedErrorConstructor;
+      return [
+        [
+          entry.name,
+          (message, opts, retryAfter) => {
+            if (ctor === RateLimitError) {
+              const rateLimitOptions:
+                | {
+                    cause?: Error;
+                    context?: Record<string, unknown>;
+                    retryAfter?: number;
+                  }
+                | undefined =
+                opts.context === undefined &&
+                opts.cause === undefined &&
+                retryAfter === undefined
+                  ? undefined
+                  : {
+                      ...opts,
+                      ...(retryAfter === undefined ? {} : { retryAfter }),
+                    };
+              return new RateLimitError(message, rateLimitOptions);
+            }
+            return new ctor(message, opts);
+          },
+        ],
+      ];
+    })
+  );
 
 // ---------------------------------------------------------------------------
 // Error serialization
@@ -124,16 +150,23 @@ const errorConstructorsByName: Record<string, ErrorFactory> = {
 /** Extract structured data from an Error for transport. */
 export const serializeError = (error: Error): SerializedError => {
   const result: SerializedError = {
-    message: error.message,
+    message: redactErrorString(error.message),
     name: error.name,
-    stack: error.stack,
+    stack: redactErrorStack(error.stack),
   };
 
   if (isTrailsError(error)) {
     return {
       ...result,
       category: error.category,
-      context: error.context,
+      context: redactErrorContext(error.context),
+      ...(error instanceof RetryExhaustedError
+        ? {
+            attempts: error.attempts,
+            cause: serializeError(error.cause),
+            detour: error.detour,
+          }
+        : {}),
       retryAfter:
         error instanceof RateLimitError ? error.retryAfter : undefined,
       retryable: error.retryable,
@@ -146,6 +179,28 @@ export const serializeError = (error: Error): SerializedError => {
 /** Reconstruct a TrailsError from serialized data. */
 export const deserializeError = (data: SerializedError): TrailsError => {
   const opts = buildOpts(data.context);
+  if (data.name === 'RetryExhaustedError') {
+    const wrapped =
+      data.cause === undefined
+        ? createErrorByCategory(
+            data.category ?? 'internal',
+            data.message,
+            data.context,
+            data.retryAfter
+          )
+        : deserializeError(data.cause);
+    const error = new RetryExhaustedError(wrapped, {
+      attempts: data.attempts ?? 0,
+      detour: data.detour ?? 'unknown',
+    });
+    if (data.message !== error.message) {
+      error.message = data.message;
+    }
+    if (data.stack) {
+      error.stack = data.stack;
+    }
+    return error;
+  }
   const nameFactory = errorConstructorsByName[data.name];
 
   const error = nameFactory
@@ -164,24 +219,6 @@ export const deserializeError = (data: SerializedError): TrailsError => {
   return error;
 };
 
-// ---------------------------------------------------------------------------
-// Safe JSON
-// ---------------------------------------------------------------------------
-
-/** Parse a JSON string, returning a Result instead of throwing. */
-export const safeParse = (json: string): Result<unknown, ValidationError> => {
-  try {
-    return Result.ok(JSON.parse(json) as unknown);
-  } catch (error) {
-    return Result.err(
-      new ValidationError('Invalid JSON', {
-        cause: error instanceof Error ? error : new Error(String(error)),
-        context: { input: json.slice(0, 200) },
-      })
-    );
-  }
-};
-
 /** Stringify a value, returning a Result. Handles circular references. */
 export const safeStringify = (
   value: unknown

package/src/sha256.ts

@@ -0,0 +1,136 @@
+/**
+ * Pure synchronous SHA-256 for runtime-portable fingerprints.
+ *
+ * `node:crypto`'s `createHash` is unavailable on edge runtimes without
+ * compatibility flags, and Web Crypto's `subtle.digest` is asynchronous,
+ * which does not fit the synchronous summary paths that need a digest
+ * (signal payload summaries, per-project store keys). This implementation
+ * follows FIPS 180-4 and produces output identical to
+ * `createHash('sha256').update(text).digest('hex')`.
+ */
+
+/* oxlint-disable no-bitwise, unicorn/prefer-math-trunc, unicorn/number-literal-case -- SHA-256 is defined over 32-bit words: rotations, xor, and `>>> 0` unsigned wrapping are the specified operations, and `Math.trunc()` is not equivalent to `>>> 0` (it neither wraps to 32 bits nor coerces to unsigned). number-literal-case is disabled because oxfmt normalizes hex digits to lowercase, which the rule rejects — the formatter wins. */
+
+// FIPS 180-4 §4.2.2: first 32 bits of the fractional parts of the cube
+// roots of the first 64 primes.
+const K = Uint32Array.from([
+  0x42_8a_2f_98, 0x71_37_44_91, 0xb5_c0_fb_cf, 0xe9_b5_db_a5, 0x39_56_c2_5b,
+  0x59_f1_11_f1, 0x92_3f_82_a4, 0xab_1c_5e_d5, 0xd8_07_aa_98, 0x12_83_5b_01,
+  0x24_31_85_be, 0x55_0c_7d_c3, 0x72_be_5d_74, 0x80_de_b1_fe, 0x9b_dc_06_a7,
+  0xc1_9b_f1_74, 0xe4_9b_69_c1, 0xef_be_47_86, 0x0f_c1_9d_c6, 0x24_0c_a1_cc,
+  0x2d_e9_2c_6f, 0x4a_74_84_aa, 0x5c_b0_a9_dc, 0x76_f9_88_da, 0x98_3e_51_52,
+  0xa8_31_c6_6d, 0xb0_03_27_c8, 0xbf_59_7f_c7, 0xc6_e0_0b_f3, 0xd5_a7_91_47,
+  0x06_ca_63_51, 0x14_29_29_67, 0x27_b7_0a_85, 0x2e_1b_21_38, 0x4d_2c_6d_fc,
+  0x53_38_0d_13, 0x65_0a_73_54, 0x76_6a_0a_bb, 0x81_c2_c9_2e, 0x92_72_2c_85,
+  0xa2_bf_e8_a1, 0xa8_1a_66_4b, 0xc2_4b_8b_70, 0xc7_6c_51_a3, 0xd1_92_e8_19,
+  0xd6_99_06_24, 0xf4_0e_35_85, 0x10_6a_a0_70, 0x19_a4_c1_16, 0x1e_37_6c_08,
+  0x27_48_77_4c, 0x34_b0_bc_b5, 0x39_1c_0c_b3, 0x4e_d8_aa_4a, 0x5b_9c_ca_4f,
+  0x68_2e_6f_f3, 0x74_8f_82_ee, 0x78_a5_63_6f, 0x84_c8_78_14, 0x8c_c7_02_08,
+  0x90_be_ff_fa, 0xa4_50_6c_eb, 0xbe_f9_a3_f7, 0xc6_71_78_f2,
+]);
+
+const rotr = (value: number, bits: number): number =>
+  (value >>> bits) | (value << (32 - bits));
+
+/**
+ * Total array accessor: every read in the compression loop is provably in
+ * range, so the fallback never fires — it only satisfies
+ * `noUncheckedIndexedAccess` without an assertion.
+ */
+const wordAt = (words: Uint32Array, index: number): number => words[index] ?? 0;
+
+const padMessage = (bytes: Uint8Array): Uint8Array => {
+  const bitLength = bytes.length * 8;
+  // Message + 0x80 marker, padded to 56 mod 64, then a 64-bit big-endian
+  // bit length. Message sizes here are far below 2^32 bits, so the high
+  // word of the length is derived from the float division.
+  const paddedLength = (Math.floor((bytes.length + 8) / 64) + 1) * 64;
+  const padded = new Uint8Array(paddedLength);
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x1_00_00_00_00));
+  view.setUint32(paddedLength - 4, bitLength >>> 0);
+  return padded;
+};
+
+const fillSchedule = (w: Uint32Array, view: DataView, offset: number): void => {
+  for (let i = 0; i < 16; i += 1) {
+    w[i] = view.getUint32(offset + i * 4);
+  }
+  for (let i = 16; i < 64; i += 1) {
+    const w15 = wordAt(w, i - 15);
+    const w2 = wordAt(w, i - 2);
+    const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+    const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+    w[i] = (wordAt(w, i - 16) + s0 + wordAt(w, i - 7) + s1) >>> 0;
+  }
+};
+
+// oxlint-disable-next-line max-statements -- the FIPS 180-4 compression loop reads more clearly as one block than split across helpers
+const digestHex = (padded: Uint8Array): string => {
+  // FIPS 180-4 §5.3.3 initial hash value.
+  let h0 = 0x6a_09_e6_67;
+  let h1 = 0xbb_67_ae_85;
+  let h2 = 0x3c_6e_f3_72;
+  let h3 = 0xa5_4f_f5_3a;
+  let h4 = 0x51_0e_52_7f;
+  let h5 = 0x9b_05_68_8c;
+  let h6 = 0x1f_83_d9_ab;
+  let h7 = 0x5b_e0_cd_19;
+
+  const view = new DataView(padded.buffer);
+  const w = new Uint32Array(64);
+
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    fillSchedule(w, view, offset);
+
+    let a = h0;
+    let b = h1;
+    let c = h2;
+    let d = h3;
+    let e = h4;
+    let f = h5;
+    let g = h6;
+    let h = h7;
+
+    for (let i = 0; i < 64; i += 1) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const temp1 = (h + s1 + ch + wordAt(K, i) + wordAt(w, i)) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (s0 + maj) >>> 0;
+
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temp1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) >>> 0;
+    }
+
+    h0 = (h0 + a) >>> 0;
+    h1 = (h1 + b) >>> 0;
+    h2 = (h2 + c) >>> 0;
+    h3 = (h3 + d) >>> 0;
+    h4 = (h4 + e) >>> 0;
+    h5 = (h5 + f) >>> 0;
+    h6 = (h6 + g) >>> 0;
+    h7 = (h7 + h) >>> 0;
+  }
+
+  return [h0, h1, h2, h3, h4, h5, h6, h7]
+    .map((word) => word.toString(16).padStart(8, '0'))
+    .join('');
+};
+
+/**
+ * SHA-256 of the UTF-8 encoding of `text`, as lowercase hex.
+ *
+ * Output-identical to `createHash('sha256').update(text).digest('hex')`.
+ */
+export const sha256Hex = (text: string): string =>
+  digestHex(padMessage(new TextEncoder().encode(text)));