@ontrails/core 1.0.0-beta.32 → 1.0.0-beta.39

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @ontrails/core
 
+## 1.0.0-beta.39
+
+### Patch Changes
+
+- [`f42ca6e`](https://github.com/outfitter-dev/trails/commit/f42ca6e40b29155acec446e5bf44e52e014466bd): Hard cutover: the CLI consumes `cli` bindings from the app-authored surfaces overlay. Scalar bindings behave identically to the removed cliAliases (parity-tested) — the binding name splits on `.` into a transparent synonym command path for exactly one trail. List bindings arrive as command groups: each expanded member trail gets a group-prefixed route that dispatches the member trail with its identity preserved, and a singleton list stays a group. Expansion is fail-fast boundary validation: a scalar binding resolving to zero or multiple trails, or a group with an empty member union, is a `ValidationError` naming the binding. `DeriveTopoGraphOptions.cliAliases`, the `cliAliases`/`trailsCliAliases` app-module export convention, and the per-kind compile lift are deleted; `deriveCliCommands`/`createProgram` take `overlays` instead of `aliases`, and both topo-graph derivation pipelines expand the same bindings through one shared helper so runtime CLI routes and lock routes come from one semantic. A leftover legacy export is now a Warden error (`no-legacy-cli-alias-export`) naming the `surfaceOverlay({ cli: { ... } })` rewrite.
+
+  This is a breaking API removal shipped under the lockstep beta patch convention (pre-1.0 hard-cutover posture, zero external adoption); the removed options have no deprecation window by design.
+
+- [`6b75a46`](https://github.com/outfitter-dev/trails/commit/6b75a46ab6210237d306cceade833bf9ce6e7431): The core barrel is now execution-portable: no eager `bun:`/`node:` builtin imports remain on its module graph (TRL-1198). `trails-db`, workspace discovery, and path security load `bun:sqlite`, `node:fs`, `node:os`, and `node:path` lazily through `process.getBuiltinModule` at first use, and signal payload summaries plus per-project store keys use a pure SHA-256 (output-identical to `node:crypto`). A Worker bundle no longer needs a `bun:sqlite` stub plugin or the `nodejs_compat` flag to serve trails; the Cloudflare adapter's miniflare lane now bundles without externals and boots workerd without `nodejs_compat` as the structural regression gate, and its README stub instructions are replaced with the portable posture. Tooling helpers throw a clear `InternalError` naming the missing builtin when called on runtimes without it.
+- [`81373bc`](https://github.com/outfitter-dev/trails/commit/81373bc5e980bb06d56fb06af4f0986f72e318c7): Wave-2 MCP cutover to the app-authored `surfaces` overlay. The overlay's `mcp` bindings are now the authored, lockable default for the MCP surface: a list binding derives one grouped trailhead tool (member selection in `{ trail, input }`, member identity preserved in `{ trail, output }`, deterministic derived description), and a scalar binding derives an additional tool synonym whose MCP-safe name is published verbatim and must expand to exactly one trail. `deriveMcpTools`/`createServer` accept the new `overlays` option; `@ontrails/core` gains `expandMcpSurfaceBindings` and `deriveMcpTrailheadDescription`.
+
+  The call-site `CreateServerOptions.trailheads` map survives as permanent override-in-context design, not a compatibility bridge: when both channels are present, the call-site map wins at runtime. Warden's new `trailhead-override-divergence` rule (warn) names both sides when a call-site map's binding names or member selectors diverge from the authored overlay default.
+
+  Topographer now derives `graph.trailheads` from the overlay's `mcp` list bindings in both `deriveTopoGraph` and the store-side graph build, so trailhead facts flow from compiled locks into Wayfinder reads for the first time. The never-wired `DeriveTopoGraphOptions.trailheads` option and the `TopoGraphTrailheadDeclaration`/`TopoGraphTrailheadTrailSelector` types are removed — a beta-window hard cutover of an option no caller could reach; author the equivalent `mcp` list binding in `surfaceOverlay({ mcp })` instead.
+
+- [`820b4ad`](https://github.com/outfitter-dev/trails/commit/820b4ad9c40ea383b3c489a05fe7e4b2328e324f): Add `surfaceOverlay` — the shared surface-naming schema (scalar binding = synonym, list binding = grouped entry, singleton list stays a group) with app-authored/adapter-derived overlay provenance enforced at collection and consumption, and the `surface-overlay-coherence` Warden rule. MCP tool-name derivation moves to `@ontrails/core` (`deriveMcpToolName`) so the surface and governance read one projection; `@ontrails/mcp`'s `deriveToolName` now delegates to it. The coherence rule activates on standard warden runs once fresh derivations collect app-module overlays through the shared compile channel (TRL-1209, next in this stack).
+- [`28d75fb`](https://github.com/outfitter-dev/trails/commit/28d75fbadecc62794f43957bc3aca11a4cf39c51): Add `forkVersion()` so fork version entries get typed blazes (TRL-1180). `TrailVersions` fixes every entry's generics to `unknown`, which left fork blazes with `unknown` input and forced authors to re-parse the already-validated value just to narrow it. `forkVersion({ input, output, blaze, ... })` threads the entry's own schemas into the blaze signature (including merged `composeInput` fields) and enforces the entry's output shape at compile time; the erasure back to `TrailVersionEntry` is sound because the fork pipeline validates raw input against the entry's own schema before dispatch. `TrailVersionForkSpec` is exported alongside it.
+- [`b9e82a3`](https://github.com/outfitter-dev/trails/commit/b9e82a33546356c93fbc302fb934a83f19f1c2c5): Webhook ingress v2 (TRL-1194, absorbing TRL-1174 and TRL-1175): store-verified, per-endpoint webhook ingress becomes framework-expressible. `webhook()` accepts dynamic path segments (`path: '/hooks/:endpoint'`) whose values are delivered as envelope fields, opt-in `rawBody: true` delivery (a non-JSON body is no longer a surface-level failure — the trail owns payload interpretation), an allowlisted `headers` list delivered lowercased, and `resources` that make `verify` resource-capable: the HTTP surface resolves the declared resources into a context for the verifier and releases them afterwards, so signature checks can reach stores holding per-endpoint secrets. Envelope-mode ingress responds 202 Accepted; classic static webhooks keep their exact-match, JSON-gated, 200 behavior. Core exports `parseWebhookPathParams`, `matchWebhookPath`, `webhookPathPatternsOverlap`, and `createResources`. The `webhook-route-collision` Warden rule now also flags dynamic patterns that overlap other webhook or derived routes, not just exact method/path duplicates.
+
+## 1.0.0-beta.38
+
+### Patch Changes
+
+- [`a105127`](https://github.com/outfitter-dev/trails/commit/a105127e5662ed9a6c245125f791fb0182da3f5e): Add the `@ontrails/cloudflare` adapter collection with its first two service subpaths. `@ontrails/cloudflare/workers` exports `createWorkersHandler`, a materializer producing the `{ fetch(request, env, ctx) }` Worker export on the shared HTTP fetch kernel, with an env bridge that re-resolves env-bound resources whenever a new Worker `env` arrives so no resource instance serves a request with a stale env. `@ontrails/cloudflare/kv` exports `cloudflareKv`, a resource definition wrapping a KV namespace binding (`get`/`put`/`delete`/`list` with TTL options) plus an in-memory `createMemoryKv` mock so `testAll` runs configuration-free.
+
+  `@ontrails/core` now guards the default trail context fields: `requestId` falls back to `crypto.randomUUID()` when the `Bun` global is absent, and `cwd`/`env` fall back to `'/'`/`{}` when `process` is absent, so trail execution works on runtimes like Cloudflare Workers.
+
+  `@ontrails/warden` registers the `@ontrails/cloudflare` public barrel in the repo-local `public-export-example-coverage` policy, requiring `@example` TSDoc coverage on `createWorkersHandler` and `cloudflareKv`.
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+### Patch Changes
+
+- [`417bd84`](https://github.com/outfitter-dev/trails/commit/417bd8471d0f0f47ad5f33cd2ac1c606eccd72f8): Promote signal trace helpers from tracing compatibility code to core exports, and make tracing's memory sink wrapper use the observe-owned implementation.
+- [`a88114b`](https://github.com/outfitter-dev/trails/commit/a88114b4dd0772db6b58ecdb7671e4169e6bdca5): Expose stable typed topo diagnostics for missing references so downstream
+  migration tooling can consume validation results without parsing human messages.
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
 ## 1.0.0-beta.32
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.32",
+  "version": "1.0.0-beta.39",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",

package/src/context.ts

@@ -21,11 +21,25 @@ export const passthroughTrace: TraceFn = async <T>(
   fn: () => T | Promise<T>
 ): Promise<T> => await fn();
 
+const defaultCwd = (): string =>
+  typeof process === 'undefined' ? '/' : process.cwd();
+
+const defaultEnv = (): Record<string, string | undefined> =>
+  typeof process === 'undefined'
+    ? {}
+    : (process.env as Record<string, string | undefined>);
+
+const defaultRequestId = (): string =>
+  typeof Bun === 'undefined' ? crypto.randomUUID() : Bun.randomUUIDv7();
+
 /**
  * Create a TrailContext with sensible defaults.
  *
- * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID)
+ * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID), falling
+ *   back to `crypto.randomUUID()` on runtimes without the `Bun` global
  * - `abortSignal` defaults to a fresh, non-aborted `AbortSignal`
+ * - `cwd`/`env` default to the `process` globals when available, and to
+ *   `'/'`/`{}` on runtimes without `process` (for example Cloudflare Workers)
  * - All other fields come from `overrides`
  */
 export const createTrailContext = (
@@ -33,10 +47,10 @@ export const createTrailContext = (
 ): TrailContext => {
   const ctx = {
     abortSignal: new AbortController().signal,
-    cwd: process.cwd(),
+    cwd: defaultCwd(),
     dryRun: false,
-    env: process.env as Record<string, string | undefined>,
-    requestId: Bun.randomUUIDv7(),
+    env: defaultEnv(),
+    requestId: defaultRequestId(),
     trace: passthroughTrace,
     ...overrides,
   } as MutableTrailContext;

package/src/derive.ts

@@ -382,6 +382,27 @@ const normalizeCliAlias = ({
   };
 };
 
+/**
+ * Convert app name + trail ID to an MCP-safe tool name.
+ *
+ * MCP tool names must be `[a-z0-9_]+`: the app name prefixes the trail id,
+ * dots and hyphens collapse to underscores, and everything lowercases. This
+ * is the one owner for the projection — the MCP surface renders tools with
+ * it and Warden checks binding-name collisions against it, so the two
+ * readers cannot drift.
+ *
+ * @example
+ * ```ts
+ * deriveMcpToolName('myapp', 'entity.show'); // "myapp_entity_show"
+ * deriveMcpToolName('dispatch', 'patch.search'); // "dispatch_patch_search"
+ * ```
+ */
+export const deriveMcpToolName = (appName: string, trailId: string): string => {
+  const prefix = appName.toLowerCase().replaceAll(/[.-]/g, '_');
+  const suffix = trailId.toLowerCase().replaceAll(/[.-]/g, '_');
+  return `${prefix}_${suffix}`;
+};
+
 /** Derive resolved CLI command routes for one trail. */
 export const deriveTrailCliCommandProjection = (
   trail: TrailCliProjectionInput,

package/src/index.ts

@@ -143,8 +143,13 @@ export {
   isResource,
   resource,
 } from './resource.js';
-export { drainResources, resolveResourceConfig } from './resource-config.js';
+export {
+  createResources,
+  drainResources,
+  resolveResourceConfig,
+} from './resource-config.js';
 export type {
+  ResolvedResourceScope,
   ResourceConfigValues,
   ResourceDrainReport,
 } from './resource-config.js';
@@ -186,6 +191,7 @@ export {
 export type { ActivationSourceProjection } from './activation-source-projection.js';
 export {
   deriveSupportedTrailVersions,
+  forkVersion,
   getTrailVersionEntryKind,
   hasDeprecatedTrailVersionGuidance,
   intentValues,
@@ -224,6 +230,7 @@ export type {
   TrailVersionArchivedStatus,
   TrailVersionDeprecatedStatus,
   TrailVersionForkEntry,
+  TrailVersionForkSpec,
   TrailVersionRevisionEntry,
   TrailVersions,
   TrailVersionStatus,
@@ -302,10 +309,13 @@ export type {
 export {
   getWebhookHeader,
   getWebhookHeaders,
+  matchWebhookPath,
+  parseWebhookPathParams,
   validateWebhookSource,
   verifyWebhookRequest,
   webhook,
   webhookMethods,
+  webhookPathPatternsOverlap,
 } from './webhook.js';
 export type {
   WebhookMethod,
@@ -410,6 +420,31 @@ export type {
 export { topo } from './topo.js';
 export type { Topo, TopoIdentity } from './topo.js';
 
+// Surface overlay
+export {
+  SURFACES_OVERLAY_NAMESPACE,
+  classifySurfaceBinding,
+  deriveMcpTrailheadDescription,
+  expandCliSurfaceBindings,
+  expandMcpSurfaceBindings,
+  resolveSurfaceOverlayBindings,
+  surfaceBindingsFromLockOverlays,
+  surfaceOverlay,
+  surfaceOverlayBindingsSchema,
+} from './surface-overlay.js';
+export type {
+  CliSurfaceBindingAliases,
+  McpSurfaceBindingExpansion,
+  OverlayEnvelopeLike,
+  OverlayProvenance,
+  SurfaceBindingRef,
+  SurfaceBindingShape,
+  SurfaceBindingValue,
+  SurfaceBindings,
+  SurfaceOverlay,
+  SurfaceOverlayBindings,
+} from './surface-overlay.js';
+
 // Generic trails-db helpers (shared framework infrastructure per ADR-0014).
 // The topo-store public API that previously lived here moved to
 // `@ontrails/topographer` per ADR-0042.
@@ -447,8 +482,15 @@ export type {
 } from './draft.js';
 
 // Topo validation
-export { validateTopo } from './validate-topo.js';
-export type { TopoDiagnostic, TopoIssue } from './validate-topo.js';
+export { getTopoDiagnostics, validateTopo } from './validate-topo.js';
+export type {
+  TopoDiagnostic,
+  TopoDiagnosticCode,
+  TopoIssue,
+  TopoMissingReference,
+  TopoReferenceKind,
+  TopoReferenceOwnerKind,
+} from './validate-topo.js';
 export { validateEstablishedTopo } from './validate-established-topo.js';
 
 // Layer
@@ -473,6 +515,7 @@ export type {
 export {
   deriveCliPath,
   deriveFields,
+  deriveMcpToolName,
   deriveTrailCliCommandProjection,
   normalizeCliCommandPath,
 } from './derive.js';
@@ -506,6 +549,7 @@ export type { ExecuteTrailOptions } from './execute.js';
 export {
   clearTraceSink,
   createActivationTraceRecord,
+  createSignalTraceRecord,
   createTraceRecord,
   getTraceContext,
   getTraceSink,
@@ -514,6 +558,7 @@ export {
   TRACE_CONTEXT_KEY,
   traceContextFromRecord,
   writeActivationTraceRecord,
+  writeSignalTraceRecord,
 } from './tracing.js';
 export type {
   ActivationTraceRecordName,

package/src/path-security.ts

@@ -4,10 +4,14 @@
  * All functions are runtime-agnostic (Node / Bun compatible).
  */
 
-import { resolve, relative, normalize, isAbsolute } from 'node:path';
-
 import { PermissionError } from './errors.js';
 import { Result } from './result.js';
+// Path security guards filesystem access on tooling paths: node:path
+// loads lazily at first use so the core barrel's module graph stays
+// execution-portable on runtimes without node: builtins (TRL-1198).
+import { loadRuntimeBuiltin } from './runtime-builtins.js';
+
+const nodePath = () => loadRuntimeBuiltin('node:path');
 
 // ---------------------------------------------------------------------------
 // Internal
@@ -15,6 +19,7 @@ import { Result } from './result.js';
 
 /** Returns true when `target` is equal to or a descendant of `base`. */
 const isWithin = (base: string, target: string): boolean => {
+  const { isAbsolute, relative } = nodePath();
   const rel = relative(base, target);
   // Empty string means they are the same directory.
   // A relative path starting with ".." means it escapes.
@@ -39,6 +44,7 @@ export const securePath = (
   basePath: string,
   userPath: string
 ): Result<string, PermissionError> => {
+  const { resolve } = nodePath();
   const base = resolve(basePath);
   const resolved = resolve(base, userPath);
 
@@ -61,6 +67,7 @@ export const securePath = (
  * `basePath`.
  */
 export const isPathSafe = (basePath: string, userPath: string): boolean => {
+  const { resolve } = nodePath();
   const base = resolve(basePath);
   const resolved = resolve(base, userPath);
   return isWithin(base, resolved);
@@ -74,6 +81,7 @@ export const deriveSafePath = (
   basePath: string,
   ...segments: string[]
 ): Result<string, PermissionError> => {
+  const { normalize, resolve } = nodePath();
   const base = resolve(basePath);
   const joined = resolve(base, ...segments.map((s) => normalize(s)));
 

package/src/resource-config.ts

@@ -585,7 +585,7 @@ const withResolvedResources = (
 /**
  * Resolved trail context plus lease release for resources used by the run.
  */
-interface ResolvedResourceScope {
+export interface ResolvedResourceScope {
   readonly ctx: TrailContext;
   release(): void;
 }
@@ -593,14 +593,26 @@ interface ResolvedResourceScope {
 const releaseNoResources = (): undefined => undefined;
 
 /**
- * Resolve all declared resources for a trail.
+ * Resolve all declared resources for a resource-bearing declaration.
  *
  * Validates per-resource config, checks overrides and caches, and creates
  * new instances as needed. Returns an enriched context with all resource
- * instances injected into extensions.
+ * instances injected into extensions. Callers own the returned `release`.
+ *
+ * @example
+ * ```ts
+ * const scope = await createResources(
+ *   { resources: [secretsStore] },
+ *   createTrailContext()
+ * );
+ * if (scope.isOk()) {
+ *   const secrets = secretsStore.from(scope.value.ctx);
+ *   scope.value.release();
+ * }
+ * ```
  */
 export const createResources = async (
-  trail: AnyTrail,
+  trail: Pick<AnyTrail, 'resources'>,
   ctx: TrailContext,
   overrides?: ResourceOverrideMap,
   configValues?: ConfigValues

package/src/runtime-builtins.ts

@@ -0,0 +1,69 @@
+/**
+ * Lazy runtime-builtin loading for the execution-portable core barrel.
+ *
+ * Core tooling modules that need Bun or Node capabilities (`bun:sqlite`,
+ * `node:fs`, `node:os`, `node:path`) must not import them eagerly: the
+ * core barrel sits on the execution path of every surface, and edge
+ * runtimes such as workerd refuse module graphs that import `bun:`
+ * builtins and gate `node:` builtins behind compatibility flags
+ * (TRL-1198). Loading through `process.getBuiltinModule` keeps the
+ * specifier out of bundler module graphs entirely and defers the
+ * capability requirement to first use, so runtimes that never call a
+ * tooling helper never pay for it.
+ */
+
+import type * as BunSqlite from 'bun:sqlite';
+import type * as NodeFs from 'node:fs';
+import type * as NodeOs from 'node:os';
+import type * as NodePath from 'node:path';
+
+import { InternalError } from './errors.js';
+
+interface BuiltinModules {
+  readonly 'bun:sqlite': typeof BunSqlite;
+  readonly 'node:fs': typeof NodeFs;
+  readonly 'node:os': typeof NodeOs;
+  readonly 'node:path': typeof NodePath;
+}
+
+const loadedBuiltins = new Map<keyof BuiltinModules, unknown>();
+
+/**
+ * Load a Bun/Node builtin module at first use.
+ *
+ * @throws {InternalError} When the runtime does not expose the builtin
+ * (for example workerd without `nodejs_compat`). Trail execution never
+ * reaches this loader; only tooling helpers (trails-db, workspace
+ * discovery) do.
+ */
+export const loadRuntimeBuiltin = <TName extends keyof BuiltinModules>(
+  name: TName
+): BuiltinModules[TName] => {
+  const cached = loadedBuiltins.get(name);
+  if (cached !== undefined) {
+    return cached as BuiltinModules[TName];
+  }
+
+  const proc = (
+    globalThis as {
+      readonly process?: {
+        readonly getBuiltinModule?: (id: string) => unknown;
+      };
+    }
+  ).process;
+  if (typeof proc?.getBuiltinModule !== 'function') {
+    throw new InternalError(
+      `Runtime builtin "${name}" is unavailable: this runtime does not expose process.getBuiltinModule. Trails tooling helpers need a Bun or Node runtime; the trail execution path never loads them.`
+    );
+  }
+
+  const loaded = proc.getBuiltinModule(name);
+  if (loaded === undefined || loaded === null) {
+    throw new InternalError(
+      `Runtime builtin "${name}" is unavailable on this runtime.`
+    );
+  }
+
+  loadedBuiltins.set(name, loaded);
+  return loaded as BuiltinModules[TName];
+};

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)));

package/src/signal-diagnostics.ts

@@ -5,11 +5,10 @@
  * observable without changing the best-effort producer API.
  */
 
-import { createHash } from 'node:crypto';
-
 import type { z } from 'zod';
 
 import type { ActivationProvenance } from './activation-provenance.js';
+import { sha256Hex } from './sha256.js';
 import type { Logger } from './types.js';
 
 export const SIGNAL_DIAGNOSTICS_SINK_KEY =
@@ -349,8 +348,9 @@ const stableJson = (value: unknown): string => {
   }
 };
 
-const hashText = (text: string): string =>
-  createHash('sha256').update(text).digest('hex');
+// Pure sha256 keeps payload summarization on the execution path portable:
+// node:crypto is unavailable on edge runtimes without compat flags.
+const hashText = (text: string): string => sha256Hex(text);
 
 export const summarizeSignalPayload = (
   payload: unknown