@preventive/triage 1.0.0-alpha.1 → 1.0.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT",
   "author": {
@@ -28,12 +28,18 @@
     "#client/sync.js": "./client/sync.js",
     "#client/sync-host.js": "./client/sync-host.js"
   },
+  "exports": {
+    "./server": "./server/index.ts",
+    "./strip-types-loader": "./strip-types-loader.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
-    "triage-server": "server/index.ts"
+    "triage-server": "server/cli.js"
   },
   "files": [
     "server/auth.ts",
     "server/bus-receiver.ts",
+    "server/cli.js",
     "server/config.ts",
     "server/db-neon.ts",
     "server/db-revision-sql.ts",
@@ -83,7 +89,8 @@
     "out/terminal.js",
     "out/view.css",
     "out/view.html",
-    "out/view.js"
+    "out/view.js",
+    "strip-types-loader.js"
   ],
   "scripts": {
     "lint": "node --run lint:js && node --run lint:css && node --run lint:ts",

package/server/cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Executable entry for the `triage-server` bin.
+//
+// Node refuses to strip TypeScript types from files under node_modules
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so once this package is
+// installed as a dependency, server/index.ts can't be executed directly.
+// This launcher registers the built-in-type-stripping hook FIRST
+// (synchronous, in-thread — see ../strip-types-loader.js), then loads the
+// server with the hook active and starts it.
+//
+// The `await import()` is load-bearing: a static `import './index.ts'`
+// would be fetched during this module's instantiation — before the body
+// runs and before the hook is registered — and would hit the node_modules
+// strip error. Deferring to a dynamic import runs it only after the static
+// `../strip-types-loader.js` import has evaluated and registered the hook.
+//
+// Because the server is imported here (not the process entry), its
+// `import.meta.main` auto-start gate stays off, so we call the exported
+// `start()` ourselves.
+import '../strip-types-loader.js'
+const { start } = await import('./index.ts')
+start()

package/server/db-neon.ts

@@ -10,9 +10,14 @@
 // (`autoInstallPeers: false` in `pnpm-workspace.yaml`) and never
 // reaches the import.
 //
-// API shape: `neon(connectionString)` returns a tagged-template +
-// callable function. We use the function-call form
-// `sql(text, params)`. `tryCommitNeon` (below) folds the dup-check
+// API shape: `neon(connectionString)` returns a tagged-template
+// callable with a `.query(text, params)` value-placeholder method.
+// We use the `sql.query(text, params)` form everywhere — our queries
+// are dynamically composed strings + parameter arrays from
+// `./db-revision-sql.ts`, so the tagged-template form doesn't fit.
+// The function-call form (`sql(text, params)`) that the 0.x driver
+// accepted was removed in `@neondatabase/serverless@1.0.0`; the peer
+// dep declares `^1.0.2`. `tryCommitNeon` (below) folds the dup-check
 // + head-check + gated INSERT into a single pipelined
 // `sql.transaction([...])` — NO commit-time advisory lock. The gated
 // INSERT's head-check and `MAX(seq)` run inside one Postgres
@@ -71,15 +76,16 @@ export { num, numOrNull }
 // side. Used by the DDL bootstrap below to prevent partial schema
 // creation on a transient mid-batch network failure.
 //
-// `transaction` is typed against the query promise the call form
+// `transaction` is typed against the query promise `sql.query`
 // returns (NOT plain `Promise<unknown>`) so a misuse like
 // `sql.transaction([Promise.resolve(123)])` fails at compile time
 // rather than failing opaquely inside the driver. The driver itself
 // inspects each promise's internal shape and rejects non-query
 // promises at runtime; the type narrows that to a static error.
-type NeonQueryPromise = ReturnType<NeonSqlCall>
-type NeonSqlCall = (queryText: string, params?: readonly unknown[]) => Promise<unknown[]>
-export type NeonSql = NeonSqlCall & {
+type NeonQueryPromise = ReturnType<NeonQueryCall>
+type NeonQueryCall = (queryText: string, params?: readonly unknown[]) => Promise<unknown[]>
+export type NeonSql = {
+  query: NeonQueryCall
   transaction: (queries: NeonQueryPromise[]) => Promise<unknown[][]>
 }
 
@@ -104,7 +110,7 @@ const DDL_LOCK_KEY_REVISION_SUB = 0x7273_6e72 // 'rsnr'
 const DURABLE_SYNC_COMMIT_LEVELS = new Set(['local', 'on', 'remote_write', 'remote_apply'])
 
 export async function assertDurableSyncCommit(sql: NeonSql): Promise<void> {
-  const rows = await sql(`SHOW synchronous_commit`, []) as Array<{ synchronous_commit?: unknown }>
+  const rows = await sql.query(`SHOW synchronous_commit`, []) as Array<{ synchronous_commit?: unknown }>
   const level = String(rows[0]?.synchronous_commit ?? '').trim().toLowerCase()
   if (!DURABLE_SYNC_COMMIT_LEVELS.has(level)) {
     throw new Error(
@@ -157,7 +163,7 @@ const SCHEMA_PG = [
 
 // Generic statement-builder helpers shared by both Neon planes
 // (workspace_revision here + the objstore tables in store-neon.ts).
-// They remove the repeated `{ run/get: async (...args) => sql(...) }`
+// They remove the repeated `{ run/get: async (...args) => sql.query(...) }`
 // wrapper for the statements whose positional args map straight to
 // the query's `$1..$N` placeholders and whose rows need no coercion.
 // Statements that coerce BIGINT (via `num`) or map snake_case rows
@@ -166,14 +172,14 @@ const SCHEMA_PG = [
 
 // Trivial passthrough write: args → $1..$N in order, no result shape.
 export function runStmt<P extends unknown[]>(sql: NeonSql, query: string): RunStmt<P> {
-  return { run: async (...args: P) => { await sql(query, args as readonly unknown[]) } }
+  return { run: async (...args: P) => { await sql.query(query, args as readonly unknown[]) } }
 }
 
 // First-row read with no coercion (callers needing BIGINT→number or
 // snake_case mapping build their own). Returns `undefined` on the
 // empty result set, matching the SQLite `wrapGet` contract.
 export function getRowStmt<P extends unknown[], T>(sql: NeonSql, query: string): GetStmt<P, T> {
-  return { get: async (...args: P) => (await sql(query, args as readonly unknown[]) as T[])[0] }
+  return { get: async (...args: P) => (await sql.query(query, args as readonly unknown[]) as T[])[0] }
 }
 
 // Per-statement builders — extracted so `openNeonDb` stays small
@@ -185,7 +191,7 @@ function buildHeadFor(sql: NeonSql): GetStmt<[string], { id: string }> {
 
 function buildSeqOfId(sql: NeonSql): GetStmt<[string, string], { seq: number }> {
   return { get: async (tag, id) => {
-    const rows = await sql(SEQ_OF_ID_SQL, [tag, id]) as Array<{ seq: number | string }>
+    const rows = await sql.query(SEQ_OF_ID_SQL, [tag, id]) as Array<{ seq: number | string }>
     const r = rows[0]
     if (!r) return undefined
     const n = numOrNull(r.seq)
@@ -195,7 +201,7 @@ function buildSeqOfId(sql: NeonSql): GetStmt<[string, string], { seq: number }>
 
 function buildLastKeyframeSeq(sql: NeonSql): GetStmt<[string], { s: number | null }> {
   return { get: async (tag) => {
-    const rows = await sql(LAST_KEYFRAME_SEQ_SQL, [tag]) as Array<{ s: number | string | null }>
+    const rows = await sql.query(LAST_KEYFRAME_SEQ_SQL, [tag]) as Array<{ s: number | string | null }>
     const r = rows[0]
     return r ? { s: numOrNull(r.s) } : undefined
   } }
@@ -203,14 +209,14 @@ function buildLastKeyframeSeq(sql: NeonSql): GetStmt<[string], { s: number | nul
 
 function buildChain(sql: NeonSql, query: string): AllStmt<[string], RevisionRow> {
   return { all: async (tag) => {
-    const rows = await sql(query, [tag]) as Array<Record<string, unknown>>
+    const rows = await sql.query(query, [tag]) as Array<Record<string, unknown>>
     return rows.map(mapRevisionRow)
   } }
 }
 
 function buildChainSeq(sql: NeonSql, query: string): AllStmt<[string, number], RevisionRow> {
   return { all: async (tag, seq) => {
-    const rows = await sql(query, [tag, seq]) as Array<Record<string, unknown>>
+    const rows = await sql.query(query, [tag, seq]) as Array<Record<string, unknown>>
     return rows.map(mapRevisionRow)
   } }
 }
@@ -221,7 +227,7 @@ function buildRevisionExists(sql: NeonSql): GetStmt<[string, string], unknown> {
 
 function buildRevisionById(sql: NeonSql): GetStmt<[string, string], RevisionRow> {
   return { get: async (tag, id) => {
-    const rows = await sql(REVISION_BY_ID_SQL, [tag, id]) as Array<Record<string, unknown>>
+    const rows = await sql.query(REVISION_BY_ID_SQL, [tag, id]) as Array<Record<string, unknown>>
     const r = rows[0]
     return r ? mapRevisionRow(r) : undefined
   } }
@@ -283,7 +289,7 @@ function tryCommitNeon(sql: NeonSql): (input: RevisionInsert) => Promise<CommitR
         // matches `base = NULL` on the first revision against the
         // empty-chain head (also NULL); plain `=` would be NULL → false
         // and the first revision would never insert.
-        sql(
+        sql.query(
           GATED_INSERT_SQL_PG,
           [tag, id, baseNorm, keyframeCol, nonce, ciphertext, signature, createdAt],
         ),
@@ -297,8 +303,8 @@ function tryCommitNeon(sql: NeonSql): (input: RevisionInsert) => Promise<CommitR
         // stable: our id present ⇒ duplicate, else the head moved ⇒
         // stale-base. (The INSERT itself is still authoritative — its own
         // single-statement snapshot is what prevents a chain fork.)
-        sql(REVISION_EXISTS_SQL, [tag, id]),
-        sql(HEAD_FOR_SQL, [tag]),
+        sql.query(REVISION_EXISTS_SQL, [tag, id]),
+        sql.query(HEAD_FOR_SQL, [tag]),
       ])
     } catch (err) {
       // A unique-violation reaches here when a cross-replica racer (or
@@ -312,9 +318,9 @@ function tryCommitNeon(sql: NeonSql): (input: RevisionInsert) => Promise<CommitR
       // escaping to `handleSave`'s IIFE. Other errors (network, syntax,
       // type mismatch) rethrow.
       if (!isUniqueViolation(err)) throw err
-      const dupRows = await sql(REVISION_EXISTS_SQL, [tag, id]) as Array<unknown>
+      const dupRows = await sql.query(REVISION_EXISTS_SQL, [tag, id]) as Array<unknown>
       if (dupRows.length > 0) return { kind: 'inserted' }
-      const headRows = await sql(HEAD_FOR_SQL, [tag]) as Array<{ id: string }>
+      const headRows = await sql.query(HEAD_FOR_SQL, [tag]) as Array<{ id: string }>
       return { kind: 'stale-base', head: headRows[0]?.id ?? null }
     }
     const insertRows = results[0] as Array<unknown>
@@ -352,8 +358,8 @@ export async function openNeonDb(connectionString: string): Promise<Handle> {
   // their DDL (the advisory lock releases at COMMIT; the
   // `IF NOT EXISTS` clauses then make the second runner a no-op).
   await sql.transaction([
-    sql(`SELECT pg_advisory_xact_lock($1, $2)`, [DDL_LOCK_KEY_REVISION, DDL_LOCK_KEY_REVISION_SUB]),
-    ...SCHEMA_PG.map((stmt) => sql(stmt, [])),
+    sql.query(`SELECT pg_advisory_xact_lock($1, $2)`, [DDL_LOCK_KEY_REVISION, DDL_LOCK_KEY_REVISION_SUB]),
+    ...SCHEMA_PG.map((stmt) => sql.query(stmt, [])),
   ])
 
   const handle: Handle = {

package/server/index.ts

@@ -452,11 +452,30 @@ installLifecycle({
 
 // Bind only after the startup orphan sweep finishes — otherwise a
 // fresh boot could serve traffic against tags whose on-disk state
-// still has residue from a prior crash. Top-level await is fine
-// for an entry-point ESM module (no other module imports this for
-// its exports — the side effect IS the program). `startupReap`
-// already resolves on any error (the reaper's own catch logs the
-// failure unconditionally and returns void), so no outer `.catch`
-// is needed here.
+// still has residue from a prior crash. `startupReap` already
+// resolves on any error (the reaper's own catch logs the failure
+// unconditionally and returns void), so no outer `.catch` is
+// needed here.
 await startupReap
-httpServer.listen(PORT, HOST)
+
+// Start serving: bind the HTTP/WS plane on the configured PORT/HOST.
+// Exported as `start()` so a launcher (server/cli.js — the triage-server
+// bin) or any consumer that `import`ed this module can begin serving once
+// the top-level `await startupReap` above has settled (the server is fully
+// ready — DB open, DDL bootstrapped, objstore reaper swept — by the time
+// the import resolves).
+export function start(): void {
+  httpServer.listen(PORT, HOST)
+}
+
+export { httpServer, wss }
+
+// Library mode: when this module is `import`ed (rather than run as the
+// entry script) skip the auto-start so consumers can own the bind — e.g.
+// wrap CF Access / framework-preset shims around the assembled
+// `httpServer`, or just call `start()` when ready. Direct invocation via
+// `node server/index.ts` (or the `triage-server` bin) still listens.
+if (import.meta.main) {
+  start()
+}
+

package/server/lifecycle.ts

@@ -46,7 +46,12 @@ export function createLifecycle(): Lifecycle {
   const inFlight = new Set<Promise<unknown>>()
   function track(promise: Promise<unknown>): void {
     inFlight.add(promise)
-    promise.finally(() => inFlight.delete(promise))
+    // Trailing `.catch(() => {})` swallows the rejection that `.finally`
+    // propagates through its returned promise — without it, a tracked
+    // handler that rejects (or whose caller's catch handler itself
+    // throws) trips the `unhandledRejection` catchall below and crashes
+    // the process via `fireShutdown(1)`.
+    promise.finally(() => inFlight.delete(promise)).catch(() => {})
   }
   let shuttingDown = false
   // Live exit code the in-progress shutdown will pass to `process.exit`.

package/server/objstore/blob-vercel.ts

@@ -364,9 +364,30 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
     // GET layer doesn't pass If-None-Match — but a future call
     // site could. Treat as unavailable rather than streaming a
     // null body.
-    if (res.statusCode !== 200 || res.stream == null || res.blob.size == null) {
+    if (res.statusCode !== 200 || res.stream == null) {
       return { ok: false, reason: 'unavailable' }
     }
+    // `@vercel/blob@2.x`'s streaming `get()` for private blobs
+    // returns the body but does NOT populate `blob.size` and does
+    // NOT pass a `content-length` header through (verified
+    // empirically: get.size=0, content-length-hdr=null while
+    // head.size reports the true byte count). The REST layer
+    // depends on a size to set `content-length` on its response
+    // and for the integrity check against the DB row, so when
+    // get() leaves it 0/null we fall back to a head() lookup.
+    // Two round-trips per private read on Vercel until the SDK is
+    // fixed — small price vs. the alternative of 503ing every read.
+    let size: number | null | undefined = res.blob?.size
+    if (size == null || size === 0) {
+      try {
+        const h = await sdk.head(path, { token })
+        size = (h as { size?: number })?.size
+      } catch (headErr) {
+        if (isNotFound(headErr)) return { ok: false, reason: 'not-found' }
+        throw headErr
+      }
+    }
+    if (size == null) return { ok: false, reason: 'unavailable' }
     // SDK returns a web ReadableStream<Uint8Array>; the REST layer
     // expects a Node Readable for pipeline(). Convert via
     // Readable.fromWeb — built-in and zero-copy where possible.
@@ -376,7 +397,7 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
       ok: true,
       reader: {
         stream: nodeStream,
-        size: res.blob.size,
+        size,
         // eslint-disable-next-line require-await
         close: async () => {
           // Destroying the Node wrapper also cancels the underlying

package/server/objstore/store-neon.ts

@@ -121,7 +121,7 @@ type StagingRow = {
 
 function buildSelectStaging(sql: NeonSql): GetStmt<[string, string, string], StagingRow> {
   return { get: async (tag, resourceTag, stagingId) => {
-    const rows = await sql(
+    const rows = await sql.query(
       `SELECT prev_version, prev_incarnation, expected_length, content_hash, signature, begun_at
        FROM workspace_object_staging
        WHERE workspace_tag = $1 AND resource_tag = $2 AND staging_id = $3`,
@@ -162,7 +162,7 @@ function buildDeleteStaging(sql: NeonSql): RunStmt<[string, string, string]> {
 // Bind order: (tag, res, sid, staleBefore).
 function buildDeleteStagingIfStale(sql: NeonSql): GetStmt<[string, string, string, number], { ok: number }> {
   return { get: async (tag, resourceTag, stagingId, staleBefore) => {
-    const rows = await sql(
+    const rows = await sql.query(
       `DELETE FROM workspace_object_staging
        WHERE workspace_tag = $1 AND resource_tag = $2 AND staging_id = $3 AND begun_at < $4
        RETURNING 1 AS ok`,
@@ -175,7 +175,7 @@ function buildDeleteStagingIfStale(sql: NeonSql): GetStmt<[string, string, strin
 
 function buildSelectLive(sql: NeonSql): AllStmt<[string], LiveDbRow> {
   return { all: async (tag) => {
-    const rows = await sql(
+    const rows = await sql.query(
       `SELECT resource_tag, version, incarnation, content_hash, content_length,
               signature, put_at
        FROM workspace_object
@@ -189,7 +189,7 @@ function buildSelectLive(sql: NeonSql): AllStmt<[string], LiveDbRow> {
 
 function buildSelectLiveOne(sql: NeonSql): GetStmt<[string, string], LiveDbRow> {
   return { get: async (tag, resourceTag) => {
-    const rows = await sql(
+    const rows = await sql.query(
       `SELECT resource_tag, version, incarnation, content_hash, content_length,
               signature, put_at
        FROM workspace_object
@@ -208,7 +208,7 @@ function buildSelectLiveOne(sql: NeonSql): GetStmt<[string, string], LiveDbRow>
 // (tag, res, hash, len, sig, put_at); version is the literal 1.
 function buildInsertLiveIfAbsent(sql: NeonSql): GetStmt<[string, string, string, string, number, string, number], { ok: number }> {
   return { get: async (tag, resourceTag, incarnation, contentHash, contentLength, signature, putAt) => {
-    const rows = await sql(
+    const rows = await sql.query(
       `INSERT INTO workspace_object
          (workspace_tag, resource_tag, version, incarnation, content_hash, content_length,
           signature, put_at)
@@ -230,7 +230,7 @@ function buildInsertLiveIfAbsent(sql: NeonSql): GetStmt<[string, string, string,
 // (tag, res, nextVersion, hash, len, sig, put_at, expectedVersion).
 function buildUpdateLiveCAS(sql: NeonSql): GetStmt<[string, string, number, string, number, string, number, number, string], { ok: number }> {
   return { get: async (tag, resourceTag, nextVersion, contentHash, contentLength, signature, putAt, expectedVersion, expectedIncarnation) => {
-    const rows = await sql(
+    const rows = await sql.query(
       `UPDATE workspace_object
        SET version        = $3,
            content_hash   = $4,
@@ -252,7 +252,7 @@ function buildUpdateLiveCAS(sql: NeonSql): GetStmt<[string, string, number, stri
 // not-found, never a lost update.
 function buildDeleteLiveCAS(sql: NeonSql): GetStmt<[string, string, number, string], { ok: number }> {
   return { get: async (tag, resourceTag, expectedVersion, expectedIncarnation) => {
-    const rows = await sql(
+    const rows = await sql.query(
       `DELETE FROM workspace_object
        WHERE workspace_tag = $1 AND resource_tag = $2 AND version = $3 AND incarnation = $4
        RETURNING 1 AS ok`,
@@ -268,7 +268,7 @@ function buildListAllStaging(sql: NeonSql): AllStmt<[number], { workspace_tag: s
     // `WHERE begun_at < $1` uses workspace_object_staging_begun_at_idx
     // so the reaper sweep is O(stale-rows) cluster-wide. DB-layout
     // audit follow-up.
-    const rows = await sql(
+    const rows = await sql.query(
       `SELECT workspace_tag, resource_tag, staging_id, begun_at
        FROM workspace_object_staging
        WHERE begun_at < $1`,
@@ -285,7 +285,7 @@ function buildListAllStaging(sql: NeonSql): AllStmt<[number], { workspace_tag: s
 
 function buildListLiveTags(sql: NeonSql): AllStmt<[], { workspace_tag: string }> {
   return { all: async () => {
-    const rows = await sql(
+    const rows = await sql.query(
       `SELECT DISTINCT workspace_tag FROM workspace_object`,
       [],
     ) as Array<Record<string, unknown>>
@@ -295,7 +295,7 @@ function buildListLiveTags(sql: NeonSql): AllStmt<[], { workspace_tag: string }>
 
 function buildCountLive(sql: NeonSql): GetStmt<[string], { c: number }> {
   return { get: async (tag) => {
-    const rows = await sql(
+    const rows = await sql.query(
       `SELECT COUNT(*) AS c FROM workspace_object WHERE workspace_tag = $1`,
       [tag],
     ) as Array<{ c: number | string | bigint }>
@@ -324,8 +324,8 @@ export async function openNeonObjstore(connectionString: string, blob: BlobBacke
   // advisory lock so two replicas booting concurrently serialize
   // their DDL (the advisory lock releases at COMMIT).
   await sql.transaction([
-    sql(`SELECT pg_advisory_xact_lock($1, $2)`, [DDL_LOCK_KEY_OBJSTORE, DDL_LOCK_KEY_OBJSTORE_SUB]),
-    ...SCHEMA_PG.map((stmt) => sql(stmt, [])),
+    sql.query(`SELECT pg_advisory_xact_lock($1, $2)`, [DDL_LOCK_KEY_OBJSTORE, DDL_LOCK_KEY_OBJSTORE_SUB]),
+    ...SCHEMA_PG.map((stmt) => sql.query(stmt, [])),
   ])
 
   return {

package/strip-types-loader.js

@@ -0,0 +1,94 @@
+// Module customization hook that erases TypeScript types using Node's
+// built-in `module.stripTypeScriptTypes()` — the same eraser that powers
+// Node's unflagged `.ts` execution, exposed here as an explicit loader so
+// this package can run its own `.ts` source after it's installed as a
+// dependency. Built on Node's bundled eraser, it needs no third-party dep
+// (cf. `amaro`, which is just the library Node already bundles for this).
+//
+// Why this is needed at all — Node DISABLES built-in `.ts` stripping for
+// any file under `node_modules` (it throws ERR_UNSUPPORTED_NODE_MODULES_
+// TYPE_STRIPPING), which is exactly where this package's `.ts` files live
+// once it's a dependency. A registered `load` hook is not bound by that
+// rule, so it restores `.ts` execution from inside `node_modules`.
+//
+// Registered as an entry point — `@preventive/triage/strip-types-loader` —
+// so consumers can run the server (or import `@preventive/triage/server`)
+// with the hook active:
+//   node --import @preventive/triage/strip-types-loader <entry>
+//
+// `registerHooks` (synchronous, in-thread) is used over the async,
+// worker-thread `module.register`: stripping is a pure synchronous string
+// transform, so there's no reason to round-trip every load through a
+// worker — and the read below is synchronous too.
+//
+// We must read + strip the source OURSELVES rather than delegate to
+// `nextLoad`: under `node_modules`, `nextLoad`'s default format detection
+// is what throws ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING, before our
+// hook ever sees the source. Reading the bytes and short-circuiting with
+// an explicit format sidesteps that gate.
+//
+// `mode: 'strip'` (types elided, no enum/namespace transform) suffices —
+// the repo is `erasableSyntaxOnly` (tsconfig.json). Strip mode replaces
+// each elided type with equal-width whitespace, so line AND column
+// positions survive 1:1 and stack traces stay exact without a source map.
+
+import { isUtf8 } from 'node:buffer'
+import { readFileSync } from 'node:fs'
+import { registerHooks, stripTypeScriptTypes } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+// `.ts` / `.mts` -> ESM, `.cts` -> CommonJS. The `kind` group is the
+// optional `m`/`c` infix; absent (plain `.ts`) defaults to ESM, which is
+// correct for this `"type": "module"` package.
+const TS_RE = /\.(?<kind>[cm])?ts$/u
+
+// Defence-in-depth: assert strip mode only ERASED — every output character
+// is either unchanged, replaced by whitespace, or replaced by a semicolon
+// (swc's ASI guard — swc-project/swc#9331). This enforces at runtime what
+// tsconfig's `erasableSyntaxOnly` asserts at type-check time: nothing but
+// type syntax was removed, so the bytes Node runs can't silently diverge
+// from the bytes we wrote.
+//
+// The comparison is per-CODE-POINT, not per-byte. swc preserves byte
+// offsets by swapping each elided multi-byte character for a *same-width*
+// Unicode whitespace char — e.g. an em-dash (U+2014) in a type-level
+// comment becomes U+2002 EN SPACE, not ASCII 0x20 — so a raw-byte check
+// would false-positive on the many such comments in this codebase. `\s`
+// matches those Unicode spaces, and strip preserves code-unit length too,
+// so string indices stay aligned.
+const WHITESPACE = /\s/u
+
+function assertOnlyErased(url, source, stripped) {
+  if (source.length !== stripped.length) {
+    throw new Error(`strip-types-loader: ${url} changed length ${source.length} -> ${stripped.length}; not a pure type erasure`)
+  }
+  for (let i = 0; i < stripped.length; i++) {
+    const ch = stripped[i]
+    if (ch === source[i] || ch === ';' || WHITESPACE.test(ch)) continue
+    throw new Error(`strip-types-loader: ${url} char ${i} changed ${JSON.stringify(source[i])} -> ${JSON.stringify(ch)}; not a pure type erasure`)
+  }
+}
+
+registerHooks({
+  load(url, context, nextLoad) {
+    const match = TS_RE.exec(new URL(url).pathname)
+    if (match) {
+      const bytes = readFileSync(fileURLToPath(url))
+      // Assert the source is valid UTF-8 before decoding: a mis-encoded
+      // file (latin-1, UTF-16, a stray binary) would otherwise decode with
+      // U+FFFD replacement chars and we'd strip / execute silent garbage.
+      if (!isUtf8(bytes)) {
+        throw new Error(`strip-types-loader: ${url} is not valid UTF-8`)
+      }
+      const raw = bytes.toString('utf8')
+      const stripped = stripTypeScriptTypes(raw, { mode: 'strip' })
+      assertOnlyErased(url, raw, stripped)
+      return {
+        format: match.groups.kind === 'c' ? 'commonjs' : 'module',
+        source: stripped,
+        shortCircuit: true,
+      }
+    }
+    return nextLoad(url, context)
+  },
+})