@ttsc/unplugin 0.30.4 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/unplugin",
-  "version": "0.30.4",
+  "version": "0.31.0",
   "description": "Bundler adapters for ttsc plugins.",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
@@ -198,10 +198,14 @@
   "dependencies": {
     "unplugin": "^2.3.11"
   },
+  "optionalDependencies": {
+    "fsevents": "^2.3.3"
+  },
   "peerDependencies": {
-    "ttsc": "^0.30.4"
+    "ttsc": "^0.31.0"
   },
   "devDependencies": {
+    "@wrtnlabs/evidence": "^0.3.1",
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@types/node": "^25.3.0",
@@ -213,7 +217,7 @@
     "tslib": "^2.8.1",
     "typescript": "^7.0.2",
     "vite": "^7.3.5",
-    "ttsc": "0.30.4"
+    "ttsc": "0.31.0"
   },
   "repository": {
     "type": "git",
@@ -230,6 +234,7 @@
     "./lib/bun-register.mjs"
   ],
   "scripts": {
-    "build": "rimraf lib && tsc --emitDeclarationOnly && node scripts/emit-dual-declarations.mjs && rollup -c"
+    "build": "rimraf lib && tsc --emitDeclarationOnly && node scripts/emit-dual-declarations.mjs && rollup -c",
+    "evidence": "evidence"
   }
 }

package/src/bun-register.ts

@@ -1,173 +1,16 @@
-import { isDeepStrictEqual } from "node:util";
+import { bunRuntime } from "./core/bun/bunRuntime";
+import { ensureRegistered } from "./core/bun/ensureRegistered";
+import { registrationState } from "./core/bun/registrationState";
 
-import bun, { type BunLikePlugin } from "./bun";
-import type { TtscUnpluginOptions } from "./core/options";
-
-/**
- * Minimal shape of the Bun runtime global used to register a runtime plugin.
- *
- * Declared locally so the package needs no `bun-types` dependency; at runtime
- * Bun exposes `Bun.plugin`, which accepts the same object the bundler adapter
- * returns.
- */
-interface BunRuntimeGlobal {
-  plugin(plugin: BunLikePlugin): void;
-}
-
-interface BunRegistrationState {
-  activeOptions: TtscUnpluginOptions | undefined;
-  lockedOptions: TtscUnpluginOptions | undefined;
-  optionsLocked: boolean;
-  registered: boolean;
-}
-
-/**
- * Pending and locked options for the single runtime loader.
- *
- * Bun uses the first matching `onLoad` hook and does not fall through to a
- * later overlapping plugin (oven-sh/bun#20583). Registering twice — once
- * implicitly on import, once explicitly — would let the default loader shadow
- * the configured one. Instead exactly one Bun plugin is registered. Calls made
- * before its first load replace this detached snapshot; entering the first
- * transformable load locks that value synchronously for the process's immutable
- * module-loading session. State is keyed by the Bun runtime in a global weak
- * map so loading both emitted module conditions cannot install two overlapping
- * loaders.
- */
-const BUN_REGISTRATION_STATES = Symbol.for(
-  "@ttsc/unplugin/bun-register/states/v1",
-);
-
-/**
- * Register the ttsc transform as a Bun **runtime** plugin.
- *
- * The other `@ttsc/unplugin/*` adapters cover bundlers (`Bun.build`, Vite,
- * Webpack, …). This entry is the runtime counterpart: loading it registers the
- * same transform on Bun's module loader, so `bun run` / `bun test` apply ttsc
- * plugins (e.g. typia's `typia/lib/transform`) as files are imported, with no
- * bundling step. Wire it up once via a `bunfig.toml` preload entry — `preload =
- * ["@ttsc/unplugin/bun-register"]` — or imperatively with `import
- * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
- * `tsconfig.json`, identical to the bundler adapters.
- *
- * The first call registers one loader. Calls before its first transformable
- * TypeScript load use last-call-wins and capture options by value, so an
- * explicit call right after importing this module replaces the preload defaults
- * without installing a shadowing loader. Entering the first such load locks
- * that snapshot synchronously. Later calls with a structurally identical value
- * are idempotent; a different value throws rather than pretending a resolved
- * loader changed configuration.
- *
- * @throws When called explicitly off the Bun runtime, when options are not
- *   structured-cloneable, or when a different option value is supplied after
- *   the first load. The auto-registration below stays silent off Bun so the
- *   module is harmless to import from Node (tests, tooling).
- */
-export function register(options?: TtscUnpluginOptions): void {
-  const runtime = bunRuntime();
-  if (runtime === undefined) {
-    throw new Error(
-      "@ttsc/unplugin/bun-register must run under the Bun runtime " +
-        "(globalThis.Bun.plugin is unavailable). Use a bundler adapter such as " +
-        "@ttsc/unplugin/vite for non-Bun toolchains.",
-    );
-  }
-  const state = registrationState(runtime);
-  const snapshot = snapshotOptions(options);
-  if (state.optionsLocked) {
-    if (isDeepStrictEqual(snapshot, state.lockedOptions)) {
-      return;
-    }
-    throw new Error(
-      "@ttsc/unplugin/bun-register options are locked because the runtime " +
-        "loader has started handling a TypeScript module. Restart the Bun " +
-        "process to use different compiler or plugin options.",
-    );
-  }
-  state.activeOptions = snapshot;
-  ensureRegistered(runtime, state);
-}
-
-/** Install the runtime's one loader without changing its pending options. */
-function ensureRegistered(
-  runtime: BunRuntimeGlobal,
-  state: BunRegistrationState,
-): void {
-  if (state.registered) return;
-  state.registered = true;
-  try {
-    runtime.plugin(bun(() => lockOptions(state)));
-  } catch (error) {
-    state.registered = false;
-    throw error;
-  }
-}
-
-/** Lock and return the detached option snapshot at first load-handler entry. */
-function lockOptions(
-  state: BunRegistrationState,
-): TtscUnpluginOptions | undefined {
-  if (!state.optionsLocked) {
-    state.lockedOptions = state.activeOptions;
-    state.optionsLocked = true;
-  }
-  return state.lockedOptions;
-}
-
-/** Detach JSON-shaped options from mutations made after `register` returns. */
-function snapshotOptions(
-  options: TtscUnpluginOptions | undefined,
-): TtscUnpluginOptions | undefined {
-  if (options === undefined) return undefined;
-  try {
-    return structuredClone(options);
-  } catch (cause) {
-    throw new TypeError(
-      "@ttsc/unplugin/bun-register options must contain structured-cloneable values.",
-      { cause },
-    );
-  }
-}
-
-function bunRuntime(): BunRuntimeGlobal | undefined {
-  const runtime = (globalThis as { Bun?: BunRuntimeGlobal }).Bun;
-  return runtime !== undefined && typeof runtime.plugin === "function"
-    ? runtime
-    : undefined;
-}
-
-/** Resolve the shared state owned by one concrete Bun runtime object. */
-function registrationState(runtime: BunRuntimeGlobal): BunRegistrationState {
-  const holder = globalThis as unknown as Record<PropertyKey, unknown>;
-  let states = holder[BUN_REGISTRATION_STATES];
-  if (!(states instanceof WeakMap)) {
-    states = new WeakMap<object, BunRegistrationState>();
-    Object.defineProperty(holder, BUN_REGISTRATION_STATES, {
-      configurable: false,
-      enumerable: false,
-      value: states,
-      writable: false,
-    });
-  }
-  const registrations = states as WeakMap<object, BunRegistrationState>;
-  const existing = registrations.get(runtime);
-  if (existing !== undefined) return existing;
-  const created: BunRegistrationState = {
-    activeOptions: undefined,
-    lockedOptions: undefined,
-    optionsLocked: false,
-    registered: false,
-  };
-  registrations.set(runtime, created);
-  return created;
-}
+export { register, register as default } from "./core/bun/register";
 
 // Auto-register on import so a `bunfig.toml` `preload` entry — which only
-// imports the module — takes effect. Guarded so importing from Node (a stray
-// import, or a unit test) is a harmless no-op rather than a throw.
+// imports the module — takes effect. The side effect lives in this entry, not
+// in a core module it imports, so each evaluation of either built condition
+// registers exactly as a preload does, and `sideEffects` names only the entry.
+// Guarded so importing from Node (a stray import, or a unit test) is a
+// harmless no-op rather than a throw.
 const runtime = bunRuntime();
 if (runtime !== undefined) {
   ensureRegistered(runtime, registrationState(runtime));
 }
-
-export default register;

package/src/bun.ts

@@ -1,228 +1,5 @@
-import fs from "node:fs/promises";
-
-import {
-  beginTtscTransformBuild,
-  createTtscTransformCache,
-  isTransformTarget,
-  resetTtscTransformCache,
-  resolveOptions,
-  transformTtsc,
-} from "./core/index";
-import type { TtscUnpluginOptions } from "./core/options";
-import {
-  bunTypeScriptTransformSourcePattern,
-  typescriptTransformBunLoader,
-} from "./core/sourceExtensions";
-
-/**
- * Minimal subset of the Bun plugin API consumed by this adapter.
- *
- * Bun does not yet ship TypeScript types for its bundler plugin interface, so
- * we define the subset we need here. This keeps the adapter free of a Bun
- * runtime dependency while remaining type-safe.
- */
-export interface BunLikePlugin {
-  /** Plugin identifier shown in Bun bundler output. */
-  name: string;
-  /** Called by Bun when the plugin is registered. */
-  setup(build: BunLikeBuild): void | Promise<void>;
-}
-
-/** Bun loader identifiers this adapter can emit (only TypeScript is matched). */
-export type BunLoader = "ts" | "tsx";
-
-/**
- * Options accepted by {@link bun}, either resolved eagerly or supplied through a
- * provider evaluated lazily on the first `onLoad` call.
- *
- * The provider form exists for the runtime registration path (`bun-register`),
- * where a single Bun plugin is registered on import but its effective options
- * may be overridden by explicit `register(options)` calls made before the first
- * transformable TypeScript load. Resolving through the provider on that first
- * load, rather than at registration, lets the last pending call win without Bun
- * ever seeing a second shadowing loader.
- */
-export type TtscBunOptions =
-  | TtscUnpluginOptions
-  | (() => TtscUnpluginOptions | undefined);
-
-/** Resolve {@link TtscBunOptions} to a plain options object (or `undefined`). */
-function resolveBunOptions(
-  options?: TtscBunOptions,
-): TtscUnpluginOptions | undefined {
-  return typeof options === "function" ? options() : options;
-}
-
-/**
- * Minimal subset of the Bun `BuildConfig` plugin build object.
- *
- * `onLoad` drives the source transform. Bun's bundler also exposes `onStart`
- * and `onEnd`, which bracket the shared plugin's build lifecycle. The runtime
- * plugin API omits those hooks, so plugin setup itself starts its one
- * process-scoped module-loading session.
- */
-export interface BunLikeBuild {
-  /**
-   * Build configuration exposed unchanged by Bun's bundler plugin builder.
-   *
-   * Runtime plugin builders do not supply `files`. Bun's bundler accepts an
-   * in-memory file map whose values deliberately remain `unknown` here because
-   * this adapter only needs to preserve ownership, not consume their contents.
-   */
-  config?: {
-    files?: Readonly<Record<string, unknown>>;
-  };
-  /**
-   * Register a callback for the start of a bundler build.
-   *
-   * Optional because `Bun.plugin()` runtime builders do not expose this hook.
-   */
-  onStart?(callback: () => void | Promise<void>): void;
-  /** Register a callback for deterministic bundler-session teardown. */
-  onEnd?(callback: () => void | Promise<void>): void;
-  /**
-   * Register a loader callback for files matching `filter`.
-   *
-   * The callback receives the file path and must return the transformed file
-   * contents plus the `loader` Bun should apply next. Configured in-memory
-   * files retain relative key spellings; ordinary disk files are normally
-   * absolute. The `loader` matters most for the runtime path (`Bun.plugin`),
-   * where Bun must be told the returned contents are still TypeScript so it
-   * keeps transpiling them before execution.
-   */
-  onLoad(
-    options: { filter: RegExp },
-    loader: (args: {
-      path: string;
-    }) => Promise<{ contents: string; loader: BunLoader } | undefined>,
-  ): void;
-}
-
-/**
- * Create a ttsc plugin for Bun's bundler AND runtime.
- *
- * Bun does not implement the unplugin protocol, so this adapter wires the
- * shared ttsc transform core to Bun's `onLoad` hook directly. It reads each
- * included file from disk and forwards the content to the transform. Under
- * `Bun.build`, excluded files and no-op transforms return `undefined` so the
- * next loader retains ownership. Entries supplied through `BuildConfig.files`
- * also stay with Bun's in-memory loader: they are not filesystem project inputs
- * and reading the same path from disk would either fail or silently replace the
- * configured contents. The runtime `Bun.plugin()` API rejects an undefined
- * `onLoad` result, so that path explicitly returns the original source and
- * loader instead.
- *
- * The same object works for `Bun.build({ plugins: [ttsc()] })` (bundler) and
- * for `Bun.plugin(ttsc())` / a `bunfig.toml` preload (runtime) — see
- * `bun-register`. Every result carries an explicit `loader` so Bun keeps
- * transpiling the emitted TypeScript at runtime; `bunSourceFilePattern` only
- * matches TypeScript, so the loader is always `ts`/`tsx`. A runtime plugin
- * instance is one immutable load session, like Bun's own module cache; restart
- * the process after changing compiler inputs.
- */
-export default function bun(options?: TtscBunOptions): BunLikePlugin {
-  return {
-    name: "ttsc-unplugin",
-    setup(build) {
-      // Resolve options lazily on the first transformable TypeScript load.
-      // Runtime registration may replace its pending configuration at any time
-      // before then; the provider form must observe that last update without
-      // installing a second shadowing loader.
-      let resolved: ReturnType<typeof resolveOptions> | undefined;
-      const getOptions = () =>
-        (resolved ??= resolveOptions(resolveBunOptions(options)));
-      const cache = createTtscTransformCache();
-      const runtime = build.onStart === undefined;
-      const ownsInMemoryFile = createBunInMemoryFileMatcher(build);
-      // Bun.plugin() has no onStart callback, but one setup invocation belongs
-      // to exactly one runtime process and module-loading session. Mark that
-      // session up front so first delivery of every emitted project module is
-      // constant-time instead of re-reading the whole project. Bun.build()
-      // immediately starts the same initial scope again through onStart and
-      // repeats it for subsequent builds.
-      beginTtscTransformBuild(cache);
-      build.onStart?.(() => beginTtscTransformBuild(cache));
-      if (!runtime) {
-        build.onEnd?.(() => resetTtscTransformCache(cache));
-      }
-      build.onLoad(
-        { filter: bunTypeScriptTransformSourcePattern },
-        async (args) => {
-          if (!runtime && ownsInMemoryFile(args.path)) {
-            return undefined;
-          }
-          if (!isTransformTarget(args.path)) {
-            if (!runtime) return undefined;
-            return {
-              contents: await fs.readFile(args.path, "utf8"),
-              loader: bunLoaderFor(args.path),
-            };
-          }
-          const loader = bunLoaderFor(args.path);
-          const transformOptions = getOptions();
-          const source = await fs.readFile(args.path, "utf8");
-          // Bun has no dependency subscription API. Omitting watch hooks also
-          // avoids deriving a filesystem watch graph that this host cannot use.
-          const result = await transformTtsc(
-            args.path,
-            source,
-            transformOptions,
-            undefined,
-            cache,
-          );
-          if (result !== undefined) {
-            return { contents: result.code, loader };
-          }
-          return runtime ? { contents: source, loader } : undefined;
-        },
-      );
-    },
-  };
-}
-
-/**
- * Pick the Bun loader recorded beside the matched extension in the shared
- * source table. Reaching this function without a table entry would mean Bun
- * invoked a callback whose registration filter did not match.
- */
-function bunLoaderFor(filePath: string): BunLoader {
-  const loader = typescriptTransformBunLoader(filePath);
-  if (loader === undefined) {
-    throw new Error(`Bun delivered an unsupported source path: ${filePath}`);
-  }
-  return loader;
-}
-
-/**
- * Create a stable ownership matcher for Bun's `BuildConfig.files` map.
- *
- * Bun preserves relative `files` keys in the corresponding `onLoad` path.
- * Preserve relative versus absolute spelling and dot segments exactly. Windows
- * normalizes separators and drive-letter case, but not component case. No path
- * is resolved against cwd, so `process.chdir()` cannot change ownership.
- */
-function createBunInMemoryFileMatcher(
-  build: BunLikeBuild,
-): (file: string) => boolean {
-  const files = build.config?.files;
-  if (files === undefined) return () => false;
-  const identities = new Set(Object.keys(files).map(bunPathIdentityKey));
-  return (file) => identities.has(bunPathIdentityKey(file));
-}
-
-/**
- * Normalize the path forms Bun equates for its in-memory file map.
- *
- * Bun normalizes Windows separators and drive-letter case, but preserves path
- * component case, relative versus absolute spelling, and dot segments. A
- * filesystem identity key is broader and would suppress real disk transforms.
- */
-function bunPathIdentityKey(file: string): string {
-  if (process.platform !== "win32") return file;
-  return file
-    .replace(/\\/g, "/")
-    .replace(
-      /^([a-z]):/i,
-      (_match, drive: string) => `${drive.toLowerCase()}:`,
-    );
-}
+export { bun as default } from "./core/bun/bun";
+export type { BunLikeBuild } from "./core/bun/BunLikeBuild";
+export type { BunLikePlugin } from "./core/bun/BunLikePlugin";
+export type { BunLoader } from "./core/bun/BunLoader";
+export type { TtscBunOptions } from "./core/bun/TtscBunOptions";

package/src/core/bridge/HostWatchBridge.ts

@@ -0,0 +1,220 @@
+import type { TtscWatchInput } from "../transform/watch/TtscWatchInput";
+
+/**
+ * A watching build session's input-observation boundary, which requests host
+ * invalidation by moving the project's record (`openHostWatchBridge`). A move
+ * is not itself proof that the host observed or rebuilt that project.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Sequence capture, input registration and owed-state queries represent the
+ *   delivery/change race; compile dependency reports distinguish watched records.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One session boundary exposes record ownership without leaking watcher/timer maps.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The bridge signals through owned record files rather than modifying host watchers.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native member paragraphs explain capture timing, persistence and retry scope;
+ *   documented members and tags are separated per documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Record/input arguments and dependency callbacks carry absolute native
+ *   spellings handed to the host; sequence tokens and pass windows are separate
+ *   from native timestamps. The implementing observer owns actual case/path
+ *   capability and reproof; this boundary does not infer them from an OS name.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   This boundary organizes capture/query/registration/lifecycle operations.
+ *   Record scans, timer scheduling and input condition proofs are selected and
+ *   costed by openHostWatchBridge and its observer, not by this representation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Immutable delivery arrays/tokens permit the implementation's registration
+ *   reuse; this shape supplies no independent cache key or validity mechanism.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   openHostWatchBridge owns records, retry timers and its observer; the close
+ *   member specifies cleanup attempts and persisted-file behavior. This shape
+ *   does not independently acquire those resources or bound their populations.
+ */
+export interface HostWatchBridge {
+  /**
+   * The current change sequence, taken before a compile so registration can
+   * tell what changed during it.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   The observer sequence captured before delivery relates registered evidence
+   *   to changes during the pass instead of treating late delivery as current.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One scalar exposes the pass boundary without leaking event storage.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   A real change token replaces timing guesses about host watcher baselines.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   The method states capture timing and reason with native tag/member spacing
+   *   required by documentation guidance.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation
+   *   The returned number is a monotone change sequence, not a native timestamp,
+   *   path identity or filesystem capability.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   This scalar capture boundary selects no algorithm; openHostWatchBridge
+   *   owns pass advancement and the observer's sequence read.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Captures a pass token rather than sharing a computation across callers.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   The scalar result acquires no resource or retained population.
+   */
+  begin(): number;
+
+  /**
+   * Attempt observer cleanup and drop every owed signal. Backend close failures
+   * are suppressed by the observer and are not certified as released. The
+   * records stay: a host's persistent cache holds them as dependencies, and the
+   * next session proves them against the disk. A later delivery can register
+   * inputs again on the observer's retained root. Pass counters and the recent
+   * answering-pass window remain; completion does not promise owes() is false.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   Completion represents clearing bridge registrations/signals and attempting
+   *   observer disposal. Persistent record files remain for host cache dependencies;
+   *   completion does not certify a backend whose close threw.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One close boundary groups release rather than exposing each resource handle.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   Keeping records preserves actual persistent-cache dependencies, not abandoned
+   *   live watcher resources.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native prose distinguishes observer release from persisted files, separated
+   *   from tags and members per documentation guidance.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation
+   *   This closure boundary carries no native spelling or capability value;
+   *   observer disposal and record persistence are implemented by their owners.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   openHostWatchBridge owns clearing record/timer populations and delegating
+   *   observer disposal; this member declares their completion boundary.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Disposal is a lifecycle effect, not a reusable computed result.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   The bridge implementation owns timers and observer handles. This member
+   *   specifies when its cleanup attempt is complete, without owning the state.
+   */
+  close(): Promise<void>;
+
+  /**
+   * Report the records a compile of the host ended depending on, which the
+   * host's watcher observes until its next compile. The moves after a signal's
+   * first defend that watcher against a baseline taken after the move, so only
+   * a record the watcher observes is moved on the growing schedule; one it does
+   * not observe is still observed here and moved once per change, which a
+   * compile that later depends on it reads through its cache's snapshot. A host
+   * with several compilers opens one bridge per compiler, and each takes every
+   * record of the tool directory at its first pass: a compiler holding no
+   * module of a project never delivers the registration that ends the schedule,
+   * and would otherwise move the record for the rest of the session and run the
+   * compilers that do observe it each time. A record the watcher starts
+   * observing with a signal still owed is moved again at once, on the schedule,
+   * since the watcher took its baseline without that move.
+   *
+   * @param depends Whether the compile depends on a record, by its absolute
+   *   path, the one `projectRecordFile` spells and the host was handed.
+   * @evidence contracts/common.md#principled-implementation
+   *   The host predicate reports current record dependencies, so retries target
+   *   reported recipients. That report alone does not prove watcher health or
+   *   that a recipient will ever deliver a settling registration.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One predicate transfers dependency knowledge without a bundler-specific graph type.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   The predicate reports actual host dependencies rather than guessed compiler names.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native paragraphs explain unwatched records and resumed retries; parameter
+   *   and acknowledgment spacing follow documentation guidance.
+   * @evidence contracts/portability.md#os-neutral-implementation
+   *   The callback receives the absolute native record spelling delivered to
+   *   the host. It must report dependencies in that representation; this member
+   *   does not certify arbitrary alias equivalence or actual watcher health.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   The implementing bridge owns the registered-record scan and caller's
+   *   predicate cost; the signature selects no traversal strategy.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Reports one completed host pass's dependencies rather than caching a
+   *   result across later passes.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   The bridge owns retry timers and observed records; this callback contract
+   *   transfers dependency knowledge without acquiring or retaining a handle.
+   */
+  compiled(depends: (record: string) => boolean): void;
+
+  /**
+   * Whether the host has yet to run its modules against a change: a project was
+   * signalled since its record last registered, the one named or any the bridge
+   * observes, or a signal was answered in the current pass or the one before,
+   * whose other modules the host would still serve from the cache the signal
+   * was about. A host whose watcher applies the record's move to the build in
+   * progress, and then keeps that build's cache of the modules, loses the
+   * signal; Rollup does, measured on its watcher (samchon/ttsc#1460), and asks
+   * through `shouldTransformCachedModule` instead, before it serves a module
+   * from its cache, for any project since the module names none.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   Per-record or global queries include unsettled signals and the answering
+   *   pass window, preventing earlier stale modules from being reused immediately.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One query exposes pass invalidation without exposing signal collections.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   The extra pass follows a real host cache baseline race rather than forcing
+   *   all cached modules to transform unconditionally.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native prose explains the pass window and global query's purpose, with
+   *   separated paragraphs/tags per documentation guidance.
+   * @evidence contracts/portability.md#os-neutral-implementation
+   *   The optional record uses the absolute native delivered spelling; the
+   *   implementing bridge resolves it before Set lookup. The global pass-window
+   *   answer is separate from record spelling and certifies no native file state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   The implementation owns scalar/Set lookup and optional native resolution;
+   *   this member declares the query semantics rather than an algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Queries current owed/pass state; it does not coordinate reusable work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   The implementing bridge owns the owed Set and pass window, while this
+   *   boolean result acquires no handle or history.
+   */
+  owes(record?: string): boolean;
+
+  /**
+   * Replace the inputs observed for one project's record with a delivery's, as
+   * the Vite serve watcher does for an importer. The registration answers every
+   * signal still owed to the record, and signals again at once when the
+   * delivery read a state a change since `startedAt` has left
+   * (samchon/ttsc#1423). Without `startedAt`, every input is proven against the
+   * disk now, which is how a record handed over at a build start, read from the
+   * file rather than delivered, is taken (`refreshProjectRecordFiles`).
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   Inputs and optional capture sequence replace the record's evidence; without
+   *   a token the observer proves inputs now, while failed delivery retains recovery paths.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One replacement boundary keeps record identity and evidence together.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   Registration settles then rechecks races instead of declaring a host signal answered
+   *   solely because any module returned.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native paragraphs explain capture-token omission and immediate re-signaling,
+   *   with native tag/member spacing following documentation guidance.
+   * @evidence contracts/portability.md#os-neutral-implementation
+   *   Record and input paths carry the native spellings delivered to the host;
+   *   the implementing bridge resolves the record and delegates input identity
+   *   and native condition reproof to its observer. startedAt is a sequence,
+   *   not an OS timestamp or direct proof of unchanged input bytes.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   The implementing bridge and observer own registration/condition indexing
+   *   and proof costs; the member defines their input transfer boundary.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   The implementation may share a delivery only for the same immutable input
+   *   array and capture token when not failed; a changed population needs a new
+   *   array. This declaration owns no memo or independent validity mechanism.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   The bridge retains registration arrays and settles retry timers; its
+   *   observer owns transferred input conditions. This member acquires no handle.
+   */
+  register(
+    record: string,
+    inputs: readonly TtscWatchInput[],
+    failed?: boolean,
+    startedAt?: number,
+  ): void;
+}