@ttsc/unplugin 0.30.4 → 0.31.1

package/src/core/transform/tracker/linux/drainLinuxWatchHelper.ts

@@ -0,0 +1,34 @@
+import { LINUX_WATCH_HELPER } from "./LINUX_WATCH_HELPER";
+import { syncLinuxWatchHelper } from "./syncLinuxWatchHelper";
+
+/**
+ * The drain of a tracker whose watches live in the Linux watch helper: a sync
+ * round-trip, resolving whether it proved every earlier event arrived
+ * (samchon/ttsc#1426).
+ *
+ * With no helper running, the tracker's watches have ended with it, so there is
+ * nothing the drain could prove.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Only a current helper can acknowledge its ordered event queue; absence
+ *   resolves false because ended watches cannot certify a generation.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This adapter selects the current helper and delegates sync ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Missing native coverage is not replaced with a successful local-loop delay.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain sync authority and the absent-helper result,
+ *   following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral tracker drainage invokes the explicit helper boundary; it does
+ *   not assume another platform's event-loop barrier applies to inotify.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The sync owns and clears its own timer; this function keeps no state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One sync request.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A drain must prove every event queued before it, so each call sends its own sync.
+ */
+export function drainLinuxWatchHelper(): Promise<boolean> {
+  const helper = LINUX_WATCH_HELPER.current;
+  return helper === undefined
+    ? Promise.resolve(false)
+    : syncLinuxWatchHelper(helper);
+}

package/src/core/transform/tracker/linux/getLinuxWatchHelper.ts

@@ -0,0 +1,107 @@
+import readline from "node:readline";
+import { resolveBinary } from "ttsc/binary";
+
+import { traceProcessSpawn } from "../../../tracing/traceProcessSpawn";
+import { LINUX_WATCH_HELPER } from "./LINUX_WATCH_HELPER";
+import type { LinuxWatchHelper } from "./LinuxWatchHelper";
+import { routeLinuxWatchHelperLine } from "./routeLinuxWatchHelperLine";
+
+/**
+ * Return the process-wide Linux watch helper, starting it on first use, or
+ * `undefined` when there is none to start (samchon/ttsc#1426).
+ *
+ * The helper is the `__watch` command of ttsc's platform binary, found by
+ * ttsc's own rules (`ttsc/binary`), so it always comes from the binary ttsc
+ * itself uses. It owns one inotify instance and forwards the kernel's queue
+ * overflow notice, which libuv discards. Readiness and ordered sync qualify the
+ * native notification scope; helper construction alone proves no input. When
+ * the helper exits, every subscription ends and every sync is released
+ * unanswered, so each watch's observer stops vouching for anything; the next
+ * watch starts a new helper. A binary that exits before the decoder receives
+ * parsed object output is not tried again. Output receipt is separate from a
+ * successful subscription or sync acknowledgment.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The compiler-owned binary resolves the native protocol producer; exit
+ *   invalidates all subscriptions and unanswered syncs before a later helper starts.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One process-wide holder owns startup and failure routing, while subscription
+ *   opening and request reference accounting stay in their dedicated operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   A binary that never answers is refused instead of repeatedly restarting an
+ *   unsupported command or silently replacing loss-aware native notifications.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain protocol provenance, failure propagation and retry
+ *   conditions under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral startup uses ttsc/binary and argument-array spawn with windowsHide;
+ *   native availability is observed rather than inferred from filesystem naming.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Reusing the current helper is one holder lookup. Cold acquisition pays the
+ *   binary resolver's native/module lookup, path-key checks and process startup.
+ *   Failure snapshots live subscriptions and syncs once, O(S + D) references
+ *   plus their delegated callbacks. Decoding later stdout lines follows their
+ *   text and routed subscriber populations rather than project file count.
+ *   Enabled private tracing additionally serializes actual argv/lifecycle
+ *   observations and appends their bytes under its writer budget.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   All directory subscriptions share one live helper. Failure clears only that
+ *   instance; refused binary paths prevent repeating equivalent unsupported starts.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   One current child serves process-owned subscriptions and is unreferenced
+ *   between requests; exit clears live state. Refused binary strings persist
+ *   for process lifetime and grow with distinct rejected resolved binary paths.
+ *   Stdio and line assembly belong to that process lifetime; a partial output
+ *   line retains its received text until framing completes or the stream ends.
+ */
+export function getLinuxWatchHelper(): LinuxWatchHelper | undefined {
+  if (LINUX_WATCH_HELPER.current !== undefined) {
+    return LINUX_WATCH_HELPER.current;
+  }
+  const binary = resolveBinary();
+  if (binary === null || LINUX_WATCH_HELPER.refused.has(binary)) {
+    return undefined;
+  }
+  let child;
+  try {
+    child = traceProcessSpawn(binary, ["__watch"], {
+      stdio: ["pipe", "pipe", "ignore"],
+      windowsHide: true,
+    });
+  } catch {
+    LINUX_WATCH_HELPER.refused.add(binary);
+    return undefined;
+  }
+  const helper: LinuxWatchHelper = {
+    answered: false,
+    child,
+    nextId: 1,
+    pending: 0,
+    subscriptions: new Map(),
+    syncs: new Map(),
+  };
+  const fail = (): void => {
+    if (LINUX_WATCH_HELPER.current === helper) {
+      LINUX_WATCH_HELPER.current = undefined;
+    }
+    if (!helper.answered) LINUX_WATCH_HELPER.refused.add(binary);
+    const subscriptions = [...helper.subscriptions.values()];
+    helper.subscriptions.clear();
+    for (const release of [...helper.syncs.values()]) release(false);
+    for (const subscription of subscriptions) subscription.end();
+    helper.pending = 0;
+  };
+  child.on("error", fail);
+  child.on("exit", fail);
+  // Writing to a helper that already exited fails its pipe; the exit reports it.
+  child.stdin?.on("error", () => undefined);
+  if (child.stdout !== null) {
+    readline
+      .createInterface({ input: child.stdout, crlfDelay: Infinity })
+      .on("line", (line) => routeLinuxWatchHelperLine(helper, line));
+  }
+  child.unref();
+  (child.stdout as { unref?: () => void } | null)?.unref?.();
+  LINUX_WATCH_HELPER.current = helper;
+  return helper;
+}

package/src/core/transform/tracker/linux/openLinuxDirectoryObserver.ts

@@ -0,0 +1,318 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { pathIsWithin } from "../../filesystem/pathIsWithin";
+import { subscribeLinuxDirectoryWatch } from "./subscribeLinuxDirectoryWatch";
+
+/**
+ * Observe `root` recursively through Linux helper directory watches, applying
+ * caller admission before acquiring descendant coverage (samchon/ttsc#1389).
+ *
+ * This observer opens one non-recursive subscription per admitted directory,
+ * shared through the loaded helper directory registry, and never one per file.
+ * Root and paths forced by `track` can be watched despite admission. A
+ * directory created inside a watched one is watched as soon as its creation is
+ * reported, when `admit` accepts it, and every entry already inside it is
+ * reported as created, since it may have appeared before its watch opened. A
+ * directory confirmed absent releases its subtree watches; unavailable topology
+ * or enumeration instead withdraws coverage through `onError`.
+ *
+ * The watches live in the Linux watch helper (samchon/ttsc#1426), which answers
+ * each one asynchronously. A directory is read only once its watch is live, so
+ * the opening interval can be covered by enumeration or delivered events.
+ * Successful initial readiness requires admitted directories to be watched and
+ * enumerated. This is not an atomic tree snapshot; native loss still arrives as
+ * a conservative unnamed event. Failure resolves false, and later failure does
+ * not change an already resolved readiness Promise.
+ *
+ * Events reach `listener` as a recursive watch reports them: the event type and
+ * the changed path relative to `root`, or `null` when the backend could not
+ * name the entry, which may then be anything below the root. The helper reports
+ * dropped events that way to every watch at once, and the observer passes them
+ * on as one. A root that cannot be watched throws, exactly as `fs.watch` does,
+ * or resolves `ready` to `false`. Any other watch that cannot be opened or that
+ * fails while its directory still exists, the per-user limit among the causes,
+ * reaches `onError`, since the observer can no longer claim to cover what it
+ * was asked to.
+ *
+ * @returns The handle, with `track` to watch the directories leading to a path
+ *   registered after the observer opened, and the path itself while it is a
+ *   directory, whatever `admit` says of them. A directory it newly watches
+ *   follows `admit` below itself, as every watched directory does, but one
+ *   already watched is not read again. With `subtree`, `track` reads the
+ *   directories below that path again and watches every one `admit` now
+ *   accepts, for a registration that widened what `admit` accepts there
+ *   (samchon/ttsc#1419). Once every watch a `track` opened is live, the path is
+ *   reported changed when that pending batch completes, since it may have
+ *   changed before they were. A track with no pending opening emits no such
+ *   batch callback. `prune` releases non-root directories that current
+ *   admission no longer needs; call it after an atomic registration update,
+ *   once per observer.
+ * @evidence contracts/common.md#principled-implementation
+ *   Watches go live before enumeration; newly admitted directories announce
+ *   existing entries; failed enumeration or unknown topology withdraws coverage
+ *   instead of certifying an empty or deleted subtree.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One directory map owns recursive coverage; loaded-registry non-recursive
+ *   subscriptions own native handles and track batches own widened admission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Admission follows caller responsibility, not a hardcoded tree blacklist;
+ *   lost names remain a conservative root-wide event and watch failures withdraw coverage.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs and return comments distinguish initial coverage, dynamic
+ *   discovery, failure and widened track scope under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral recursive semantics use node:path and directory metadata; native
+ *   non-recursive helper watches avoid assuming every platform supports fs recursion.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Enumeration visits E entries across D admitted/forced directories and
+ *   delegates native watch/read/path work. Retirement copies/scans the D-watch
+ *   map and compares path text; prune scans D entries, while track examines
+ *   path-component prefixes and widening rescans selected directory listings.
+ *   Named events add native metadata and listener work. Unnamed bursts share
+ *   one notification until the queued microtask clears the coalescing flag.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The observer reuses live directory entries and joins opening readiness;
+ *   shared native subscriptions avoid reopening equivalent directory watches.
+ *   Explicit subtree widening revisits only existing coverage that may admit more.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The caller owns D directory subscriptions and outstanding readiness/batch
+ *   references; confirmed absence and prune retire entries, while failure keeps
+ *   remaining handles until close. Closure attempts each handle and prevents
+ *   later reads from adding coverage. No count/byte or initial-readiness deadline
+ *   is supplied. Listener/admission/error callbacks must return normally for
+ *   batch settlement and cleanup to finish; arbitrary callback exceptions are
+ *   not isolated, and local retirement is not certified native completion.
+ *   Track prefix stat failures can also propagate to the caller.
+ */
+export function openLinuxDirectoryObserver(
+  root: string,
+  admit: (directory: string) => boolean,
+  listener: (eventType: string, filename: string | null) => void,
+  onError: () => void,
+): {
+  close(): void;
+  ready: Promise<boolean>;
+  track(file: string, subtree?: boolean): void;
+  prune(): void;
+} {
+  const base = path.resolve(root);
+  const watched = new Map<
+    string,
+    { close(): void; live: boolean; ready: Promise<boolean> }
+  >();
+  let closed = false;
+  let failed = false;
+  let settle!: (live: boolean) => void;
+  const ready = new Promise<boolean>((resolve) => {
+    settle = resolve;
+  });
+  const fail = (): void => {
+    if (closed || failed) return;
+    failed = true;
+    settle(false);
+    onError();
+  };
+  const release = (directory: string): void => {
+    for (const [watchedDirectory, subscription] of [...watched]) {
+      if (
+        watchedDirectory === directory ||
+        watchedDirectory.startsWith(`${directory}${path.sep}`)
+      ) {
+        subscription.close();
+        watched.delete(watchedDirectory);
+      }
+    }
+  };
+  // A group of watches whose liveness one caller waits for: the initial tree,
+  // or the directories one `track` opened, with those their reads open below.
+  interface Batch {
+    pending: number;
+    settle(): void;
+  }
+  const join = (batch: Batch | undefined, live: Promise<unknown>): void => {
+    if (batch === undefined) return;
+    batch.pending += 1;
+    void live.then(() => {
+      batch.pending -= 1;
+      if (batch.pending === 0) batch.settle();
+    });
+  };
+  const watch = (
+    directory: string,
+    forced = false,
+    announce = false,
+    batch?: Batch,
+  ): void => {
+    if (closed || failed) return;
+    const existing = watched.get(directory);
+    if (existing !== undefined) {
+      // Still being opened for another caller: this one waits for it too.
+      if (!existing.live) join(batch, existing.ready);
+      return;
+    }
+    if (!forced && directory !== base && !admit(directory)) return;
+    let subscription: { close(): void; ready: Promise<boolean> };
+    try {
+      subscription = subscribeLinuxDirectoryWatch(
+        directory,
+        (eventType, filename) => deliver(directory, eventType, filename),
+        () => {
+          // Only confirmed absence retires descendant coverage. A failed
+          // presence observation does not prove that those directories vanished.
+          if (directory !== base) {
+            try {
+              fs.lstatSync(directory);
+            } catch (error) {
+              const code = (error as NodeJS.ErrnoException | undefined)?.code;
+              if (code === "ENOENT" || code === "ENOTDIR") {
+                release(directory);
+                return;
+              }
+            }
+          }
+          fail();
+        },
+      );
+    } catch (error) {
+      if (directory === base) throw error;
+      fail();
+      return;
+    }
+    const entry = {
+      close: subscription.close,
+      live: false,
+      ready: subscription.ready,
+    };
+    watched.set(directory, entry);
+    // Read the directory only once its watch is live, so an entry created in
+    // between is either read here or heard.
+    const read = subscription.ready.then((live) => {
+      entry.live = true;
+      if (!live || closed || failed || watched.get(directory) !== entry) {
+        return;
+      }
+      let entries: fs.Dirent[];
+      try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+      } catch {
+        fail();
+        return;
+      }
+      for (const child of entries) {
+        const childPath = path.join(directory, child.name);
+        if (announce && !closed) {
+          listener("rename", path.relative(base, childPath));
+        }
+        if (child.isDirectory()) watch(childPath, false, announce, batch);
+      }
+    });
+    join(batch, read);
+  };
+  // Watch the admitted directories below a watched one that the observer
+  // passed over when `admit` still declined them.
+  const scan = (directory: string, batch: Batch): void => {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      fail();
+      return;
+    }
+    for (const entry of entries) {
+      if (closed || failed) return;
+      if (!entry.isDirectory()) continue;
+      const child = path.join(directory, entry.name);
+      if (watched.has(child)) scan(child, batch);
+      else watch(child, false, false, batch);
+    }
+  };
+  // The helper reports dropped events to every watch at once; the observer
+  // passes the notice on once per burst.
+  let unattributed = false;
+  const deliver = (
+    directory: string,
+    eventType: string,
+    filename: string | null,
+  ): void => {
+    if (closed) return;
+    if (filename === null) {
+      if (unattributed) return;
+      unattributed = true;
+      queueMicrotask(() => {
+        unattributed = false;
+      });
+      listener(eventType, null);
+      return;
+    }
+    const changed = path.join(directory, filename);
+    // A recursive watch starts reporting inside a new directory at once; this
+    // one does from the moment the directory is admitted.
+    if (eventType === "rename") {
+      let directoryNow = false;
+      try {
+        const stats = fs.lstatSync(changed);
+        directoryNow = stats.isDirectory();
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException | undefined)?.code;
+        if (code === "ENOENT" || code === "ENOTDIR") release(changed);
+        else fail();
+      }
+      listener(eventType, path.relative(base, changed));
+      if (directoryNow) watch(changed, false, true);
+      return;
+    }
+    listener(eventType, path.relative(base, changed));
+  };
+  watch(base, false, false, {
+    pending: 0,
+    settle: () => {
+      if (!closed && !failed) settle(true);
+    },
+  });
+  return {
+    close: () => {
+      closed = true;
+      settle(false);
+      for (const subscription of watched.values()) subscription.close();
+      watched.clear();
+    },
+    ready,
+    prune: () => {
+      if (closed || failed) return;
+      for (const [directory, subscription] of watched) {
+        if (directory === base || admit(directory)) continue;
+        subscription.close();
+        watched.delete(directory);
+      }
+    },
+    track: (file, subtree = false) => {
+      const absolute = path.resolve(file);
+      if (!pathIsWithin(absolute, base)) return;
+      // Once every watch this call opened is live, the path may have changed
+      // before any of them could hear it.
+      const batch: Batch = {
+        pending: 0,
+        settle: () => {
+          if (!closed && !failed) {
+            listener("change", path.relative(base, absolute));
+          }
+        },
+      };
+      const relative = path.relative(base, absolute);
+      let directory = base;
+      for (const segment of relative === "" ? [] : relative.split(path.sep)) {
+        directory = path.join(directory, segment);
+        // Only a directory is ever watched, never a file on the way.
+        if (
+          fs.statSync(directory, { throwIfNoEntry: false })?.isDirectory() !==
+          true
+        )
+          break;
+        watch(directory, true, false, batch);
+        if (!watched.has(directory)) break;
+      }
+      if (subtree && watched.has(directory)) scan(directory, batch);
+    },
+  };
+}

package/src/core/transform/tracker/linux/referenceLinuxWatchHelper.ts

@@ -0,0 +1,54 @@
+import type { Socket } from "node:net";
+
+import type { LinuxWatchHelper } from "./LinuxWatchHelper";
+
+/**
+ * Count one reply the Linux watch helper owes, or one it paid, and keep its
+ * output referenced exactly while any is owed (samchon/ttsc#1426).
+ *
+ * The helper is unreferenced between requests so it never keeps a host alive. A
+ * pending registration or drain is released by a reply, failed submission,
+ * retirement or timeout. While a request remains outstanding, the helper keeps
+ * the loop from emptying.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Outstanding reply counts determine loop ownership, not the number of quiet
+ *   directory subscriptions; zero-to-nonzero transitions reference both channels.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One counter transition owns child and output references so request owners
+ *   cannot apply inconsistent liveness policies independently.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Referencing follows actual outstanding requests rather than a guessed delay
+ *   or permanent keepalive that hides missing completion.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain the reply-count authority and exit-liveness reason
+ *   under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral request ownership uses supported child and stream ref operations;
+ *   optional methods accommodate transport implementations without patching them.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One arithmetic update and boundary checks use constant work per transition.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   All subscription and sync owners share one helper counter; non-boundary
+ *   transitions avoid repeating ref or unref effects on the same channel.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Outstanding replies keep the process and output referenced; the final
+ *   release unrefs them. Request owners must balance additions and removals.
+ *   The zero clamp prevents a negative counter; it does not prove balanced
+ *   ownership or repair an extra release by a caller.
+ */
+export function referenceLinuxWatchHelper(
+  helper: LinuxWatchHelper,
+  delta: 1 | -1,
+): void {
+  const before = helper.pending;
+  helper.pending = Math.max(0, before + delta);
+  const output = helper.child.stdout as Socket | null;
+  if (before === 0 && helper.pending !== 0) {
+    helper.child.ref();
+    output?.ref?.();
+  } else if (before !== 0 && helper.pending === 0) {
+    helper.child.unref();
+    output?.unref?.();
+  }
+}

package/src/core/transform/tracker/linux/routeLinuxWatchHelperLine.ts

@@ -0,0 +1,96 @@
+import type { LinuxWatchHelper } from "./LinuxWatchHelper";
+import { referenceLinuxWatchHelper } from "./referenceLinuxWatchHelper";
+
+/**
+ * Apply one line of the Linux watch helper's output to the subscription or sync
+ * it names (samchon/ttsc#1426).
+ *
+ * The helper writes events and replies in the order it produced them, so a
+ * sync's answer arrives after every event read before it. The decision is a
+ * table over what the line carries:
+ *
+ * - Invalid JSON or a non-object value is ignored. Parsed objects mark output
+ *   receipt for startup policy; an unknown id invokes no owner callback.
+ * - `overflow` means the kernel dropped events, so every subscription hears an
+ *   unattributed event, which may concern anything it covers.
+ * - `synced` releases the sync waiting on that id.
+ * - `ready` makes a subscription live, and `error` refuses it.
+ * - `gone` ends a subscription whose directory went away.
+ * - Another line with a live subscription id and string name is one named event.
+ *   Only an explicit `change` type is content; other types are `rename`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Parsed protocol discriminants route live ids; overflow retains unknown
+ *   attribution and sync callbacks run before later lines from the same chunk.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One transport decoder selects lifecycle or event callbacks; subscription
+ *   owners interpret scope without learning the JSON record representation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Malformed and retired ids cannot revive watchers; overflow is delivered
+ *   conservatively rather than suppressed to preserve cache hits.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs and protocol list explain ordering and message precedence,
+ *   following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral owners receive callback semantics while Linux-specific JSON
+ *   framing and overflow translation remain in this native transport boundary.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources It ends a subscription the helper reports gone or refused, and keeps no state of its own.
+ * @evidence contracts/performance.md#efficient-algorithms Parsing and temporary decoded fields follow line text length. Ordinary routing uses expected-constant id-map lookup; overflow snapshots S live subscriptions and invokes each once, using O(S) temporary references. Owner callbacks retain their own classification/lifecycle cost. Without overflow, retired or malformed ids do not trigger a population scan.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A line is an event delivered once; there is no computation to share.
+ */
+export function routeLinuxWatchHelperLine(
+  helper: LinuxWatchHelper,
+  line: string,
+): void {
+  let record: {
+    error?: unknown;
+    gone?: unknown;
+    id?: unknown;
+    name?: unknown;
+    overflow?: unknown;
+    ready?: unknown;
+    synced?: unknown;
+    type?: unknown;
+  };
+  try {
+    record = JSON.parse(line) as typeof record;
+  } catch {
+    return;
+  }
+  if (record === null || typeof record !== "object") return;
+  helper.answered = true;
+  if (record.overflow === true) {
+    for (const subscription of [...helper.subscriptions.values()]) {
+      subscription.event("rename", null);
+    }
+    return;
+  }
+  if (typeof record.id !== "number") return;
+  if (record.synced === true) {
+    helper.syncs.get(record.id)?.(true);
+    return;
+  }
+  const subscription = helper.subscriptions.get(record.id);
+  if (subscription === undefined) return;
+  if (record.ready === true || typeof record.error === "string") {
+    referenceLinuxWatchHelper(helper, -1);
+    if (record.ready === true) {
+      subscription.ready(true);
+      return;
+    }
+    helper.subscriptions.delete(record.id);
+    subscription.ready(false);
+    return;
+  }
+  if (record.gone === true) {
+    helper.subscriptions.delete(record.id);
+    subscription.end();
+    return;
+  }
+  if (typeof record.name === "string") {
+    subscription.event(
+      record.type === "change" ? "change" : "rename",
+      record.name,
+    );
+  }
+}

package/src/core/transform/tracker/linux/sendLinuxWatchHelper.ts

@@ -0,0 +1,50 @@
+import type { LinuxWatchHelper } from "./LinuxWatchHelper";
+
+/**
+ * Write one request line to the Linux watch helper, and report whether it could
+ * be written (samchon/ttsc#1426).
+ *
+ * A false stream-write return denotes backpressure after queuing, not failed
+ * submission. Only an unavailable stream or thrown write withdraws submission.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Newline-delimited JSON carries the helper protocol. Stream availability
+ *   and exceptions determine submission, preserving Node's backpressure meaning.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One serialization boundary handles add, remove and sync uniformly;
+ *   acknowledgment and request lifetime remain with callers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The function does not invent an acknowledgment from write success or
+ *   conflate a queued request with a helper-confirmed observation.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs distinguish submission from backpressure and later
+ *   acknowledgment, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral protocol transport uses child stdin and JSON framing rather
+ *   than shell syntax, native separators or filesystem case assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Serialization is call-local; submitted bytes transfer to the helper stdin queue, whose lifetime belongs to the process/stream owner. Request acknowledgment and cancellation belong to the caller, and this adapter retains no descriptor or history.
+ * @evidence contracts/performance.md#efficient-algorithms One JSON serialization and newline framing process the request's supplied path text and escaped output; stream encoding and submission follow serialized byte length. Temporary storage follows serialized/framed text. A queued backpressured write is not retried or reserialized here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each write is a distinct protocol effect. Opening and sync owners await their replies; removal has no acknowledgment. No returned computation is cached or shared here.
+ */
+export function sendLinuxWatchHelper(
+  helper: LinuxWatchHelper,
+  request: {
+    /** Subscription or ordered-sync identifier owned by the caller. */
+    id: number;
+
+    /** Native opening, removal or ordered queue barrier. */
+    op: "add" | "remove" | "sync";
+
+    /** Native directory spelling for add; absent for remove and sync. */
+    path?: string;
+  },
+): boolean {
+  const input = helper.child.stdin;
+  if (input === null || input.destroyed || !input.writable) return false;
+  try {
+    input.write(`${JSON.stringify(request)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}