@ttsc/unplugin 0.30.4 → 0.31.1

package/lib/core/observer/openIsolatedRecursiveWatch.d.mts

@@ -0,0 +1,42 @@
+/**
+ * Open one recursive observer inside the transform core's isolated watch broker
+ * instead of the host process.
+ *
+ * On Windows, ttsc's direct native helper excludes access-only notifications
+ * and reports actual mutation, loss and failure through the same broker sink.
+ * On macOS, libuv serves every directory watch of a loop through one
+ * FSEventStream and re-creates it whenever any watch opens or closes, losing
+ * the events in between (samchon/ttsc#1418), where the broker opens one stream
+ * per watch. The observer's scopes get the isolation the transform core's
+ * trackers have, through the same registration (`openBrokeredWatch`) with a
+ * sink of their own that forwards events (samchon/ttsc#1485). Attributed events
+ * reach `listener` with a joined caller-directory path; unattributed events use
+ * null. A failed registration reaches `onError`, which hands the scope's
+ * entries to the bounded poll.
+ *
+ * Registration completes asynchronously, and FSEvents can later drop events
+ * (samchon/ttsc#1425). Until the broker confirms the watch, and whenever it
+ * reports such a gap or an event it could not place, an event can have gone
+ * unheard, so each is delivered as one unattributed event, which makes the
+ * observer re-check every entry the scope covers against its recorded state. On
+ * macOS a probe-capable project stream's child withholds ordinary callbacks
+ * until its opening probe returns (samchon/ttsc#1454). Ready promise completion
+ * only ends a wait; this wrapper rechecks unless closed or already failed,
+ * rather than certifying every earlier native mutation was observed.
+ *
+ * @param probeRoot The project root, when the scope is the project's: the
+ *   broker may then prove the scope's stream delivered, through a probe below
+ *   the project's tool cache (samchon/ttsc#1453). An external scope names
+ *   none.
+ * @evidence contracts/common.md#principled-implementation Broker isolation contains native watcher failures; opening confirmation and gaps trigger rechecks rather than authorizing unchanged inputs silently.
+ * @evidence contracts/common.md#clear-and-simple-design One registration forwards events and failures while the input observer owns conditions, polling, and consumer actions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The owned broker protocol does not patch native methods, and dropped events cannot become freshness proof.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains isolation, asynchronous readiness, gaps, and project-only probe ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral observation routes Windows and macOS native capability differences through the shared broker; native path joining reconstructs event paths, while failure and gaps require rechecks.
+ * @evidence contracts/performance.md#efficient-algorithms One location still delegates native normalization, optional probe namespace lookup/sweep, IPC encoding and cold child/backend setup. Each named callback joins path text and invokes the listener; condition batching and native/content revalidation cost remain with the observer, not bounded by one transport event.
+ * @evidence contracts/performance.md#reuse-equivalent-work Existing broker infrastructure is shared across scopes, while this registration retains its own event sink and observation authority.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One registration retains listener/error closures and a ready reaction. Close marks the wrapper inactive before attempting delegated cleanup, which can throw without proving child exit. Failure calls onError once but does not itself close; the owner must retire it. Late ready cannot reactivate closed/failed rechecks. Setup exceptions can occur before a handle is returned; rollback/deadline ownership remains with the broker operation.
+ */
+export declare function openIsolatedRecursiveWatch(root: string, listener: (eventType: string, file: string | null) => void, onError: () => void, _admit?: (directory: string) => boolean, probeRoot?: string): {
+    close(): void;
+};

package/lib/core/observer/openIsolatedRecursiveWatch.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Open one recursive observer inside the transform core's isolated watch broker
+ * instead of the host process.
+ *
+ * On Windows, ttsc's direct native helper excludes access-only notifications
+ * and reports actual mutation, loss and failure through the same broker sink.
+ * On macOS, libuv serves every directory watch of a loop through one
+ * FSEventStream and re-creates it whenever any watch opens or closes, losing
+ * the events in between (samchon/ttsc#1418), where the broker opens one stream
+ * per watch. The observer's scopes get the isolation the transform core's
+ * trackers have, through the same registration (`openBrokeredWatch`) with a
+ * sink of their own that forwards events (samchon/ttsc#1485). Attributed events
+ * reach `listener` with a joined caller-directory path; unattributed events use
+ * null. A failed registration reaches `onError`, which hands the scope's
+ * entries to the bounded poll.
+ *
+ * Registration completes asynchronously, and FSEvents can later drop events
+ * (samchon/ttsc#1425). Until the broker confirms the watch, and whenever it
+ * reports such a gap or an event it could not place, an event can have gone
+ * unheard, so each is delivered as one unattributed event, which makes the
+ * observer re-check every entry the scope covers against its recorded state. On
+ * macOS a probe-capable project stream's child withholds ordinary callbacks
+ * until its opening probe returns (samchon/ttsc#1454). Ready promise completion
+ * only ends a wait; this wrapper rechecks unless closed or already failed,
+ * rather than certifying every earlier native mutation was observed.
+ *
+ * @param probeRoot The project root, when the scope is the project's: the
+ *   broker may then prove the scope's stream delivered, through a probe below
+ *   the project's tool cache (samchon/ttsc#1453). An external scope names
+ *   none.
+ * @evidence contracts/common.md#principled-implementation Broker isolation contains native watcher failures; opening confirmation and gaps trigger rechecks rather than authorizing unchanged inputs silently.
+ * @evidence contracts/common.md#clear-and-simple-design One registration forwards events and failures while the input observer owns conditions, polling, and consumer actions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The owned broker protocol does not patch native methods, and dropped events cannot become freshness proof.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains isolation, asynchronous readiness, gaps, and project-only probe ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral observation routes Windows and macOS native capability differences through the shared broker; native path joining reconstructs event paths, while failure and gaps require rechecks.
+ * @evidence contracts/performance.md#efficient-algorithms One location still delegates native normalization, optional probe namespace lookup/sweep, IPC encoding and cold child/backend setup. Each named callback joins path text and invokes the listener; condition batching and native/content revalidation cost remain with the observer, not bounded by one transport event.
+ * @evidence contracts/performance.md#reuse-equivalent-work Existing broker infrastructure is shared across scopes, while this registration retains its own event sink and observation authority.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One registration retains listener/error closures and a ready reaction. Close marks the wrapper inactive before attempting delegated cleanup, which can throw without proving child exit. Failure calls onError once but does not itself close; the owner must retire it. Late ready cannot reactivate closed/failed rechecks. Setup exceptions can occur before a handle is returned; rollback/deadline ownership remains with the broker operation.
+ */
+export declare function openIsolatedRecursiveWatch(root: string, listener: (eventType: string, file: string | null) => void, onError: () => void, _admit?: (directory: string) => boolean, probeRoot?: string): {
+    close(): void;
+};

package/lib/core/observer/openIsolatedRecursiveWatch.js

@@ -0,0 +1,87 @@
+'use strict';
+
+var path = require('node:path');
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../transform/filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+var openBrokeredWatch = require('../transform/tracker/broker/openBrokeredWatch.js');
+
+/**
+ * Open one recursive observer inside the transform core's isolated watch broker
+ * instead of the host process.
+ *
+ * On Windows, ttsc's direct native helper excludes access-only notifications
+ * and reports actual mutation, loss and failure through the same broker sink.
+ * On macOS, libuv serves every directory watch of a loop through one
+ * FSEventStream and re-creates it whenever any watch opens or closes, losing
+ * the events in between (samchon/ttsc#1418), where the broker opens one stream
+ * per watch. The observer's scopes get the isolation the transform core's
+ * trackers have, through the same registration (`openBrokeredWatch`) with a
+ * sink of their own that forwards events (samchon/ttsc#1485). Attributed events
+ * reach `listener` with a joined caller-directory path; unattributed events use
+ * null. A failed registration reaches `onError`, which hands the scope's
+ * entries to the bounded poll.
+ *
+ * Registration completes asynchronously, and FSEvents can later drop events
+ * (samchon/ttsc#1425). Until the broker confirms the watch, and whenever it
+ * reports such a gap or an event it could not place, an event can have gone
+ * unheard, so each is delivered as one unattributed event, which makes the
+ * observer re-check every entry the scope covers against its recorded state. On
+ * macOS a probe-capable project stream's child withholds ordinary callbacks
+ * until its opening probe returns (samchon/ttsc#1454). Ready promise completion
+ * only ends a wait; this wrapper rechecks unless closed or already failed,
+ * rather than certifying every earlier native mutation was observed.
+ *
+ * @param probeRoot The project root, when the scope is the project's: the
+ *   broker may then prove the scope's stream delivered, through a probe below
+ *   the project's tool cache (samchon/ttsc#1453). An external scope names
+ *   none.
+ * @evidence contracts/common.md#principled-implementation Broker isolation contains native watcher failures; opening confirmation and gaps trigger rechecks rather than authorizing unchanged inputs silently.
+ * @evidence contracts/common.md#clear-and-simple-design One registration forwards events and failures while the input observer owns conditions, polling, and consumer actions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The owned broker protocol does not patch native methods, and dropped events cannot become freshness proof.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains isolation, asynchronous readiness, gaps, and project-only probe ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral observation routes Windows and macOS native capability differences through the shared broker; native path joining reconstructs event paths, while failure and gaps require rechecks.
+ * @evidence contracts/performance.md#efficient-algorithms One location still delegates native normalization, optional probe namespace lookup/sweep, IPC encoding and cold child/backend setup. Each named callback joins path text and invokes the listener; condition batching and native/content revalidation cost remain with the observer, not bounded by one transport event.
+ * @evidence contracts/performance.md#reuse-equivalent-work Existing broker infrastructure is shared across scopes, while this registration retains its own event sink and observation authority.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One registration retains listener/error closures and a ready reaction. Close marks the wrapper inactive before attempting delegated cleanup, which can throw without proving child exit. Failure calls onError once but does not itself close; the owner must retire it. Late ready cannot reactivate closed/failed rechecks. Setup exceptions can occur before a handle is returned; rollback/deadline ownership remains with the broker operation.
+ */
+function openIsolatedRecursiveWatch(root, listener, onError, _admit, probeRoot) {
+    let closed = false;
+    let failed = false;
+    const recheck = () => {
+        if (!closed && !failed)
+            listener("rename", null);
+    };
+    const watch = openBrokeredWatch.openBrokeredWatch([{ directory: root, recursive: true }], {
+        allEvents: true,
+        // The scope never drains: its events are forwarded as they come, and a
+        // drain's verdict on other registrations' proofs is not its business.
+        drains: false,
+        filesystem: DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS,
+        ...(probeRoot === undefined ? {} : { probeRoot }),
+        sink: {
+            event: (directory, filename, eventType) => {
+                if (!closed) {
+                    listener(eventType, filename === null ? null : path.join(directory, filename));
+                }
+            },
+            failed: () => {
+                if (failed || closed)
+                    return;
+                failed = true;
+                onError();
+            },
+            gap: recheck,
+            unattributed: recheck,
+            unproven: () => undefined,
+        },
+    });
+    void watch.ready.then(recheck);
+    return {
+        close: () => {
+            closed = true;
+            watch.close();
+        },
+    };
+}
+
+exports.openIsolatedRecursiveWatch = openIsolatedRecursiveWatch;
+//# sourceMappingURL=openIsolatedRecursiveWatch.js.map

package/lib/core/observer/openIsolatedRecursiveWatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openIsolatedRecursiveWatch.js","sources":["../../../src/core/observer/openIsolatedRecursiveWatch.ts"],"sourcesContent":[null],"names":["openBrokeredWatch","DEFAULT_FILESYSTEM_OPERATIONS"],"mappings":";;;;;;AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCG;AACG,SAAU,0BAA0B,CACxC,IAAY,EACZ,QAA0D,EAC1D,OAAmB,EACnB,MAAuC,EACvC,SAAkB,EAAA;IAElB,IAAI,MAAM,GAAG,KAAK;IAClB,IAAI,MAAM,GAAG,KAAK;IAClB,MAAM,OAAO,GAAG,MAAW;AACzB,QAAA,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM;AAAE,YAAA,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;AAClD,IAAA,CAAC;AACD,IAAA,MAAM,KAAK,GAAGA,mCAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE;AACtE,QAAA,SAAS,EAAE,IAAI;;;AAGf,QAAA,MAAM,EAAE,KAAK;AACb,QAAA,UAAU,EAAEC,2DAA6B;AACzC,QAAA,IAAI,SAAS,KAAK,SAAS,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;AACjD,QAAA,IAAI,EAAE;YACJ,KAAK,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,KAAI;gBACxC,IAAI,CAAC,MAAM,EAAE;oBACX,QAAQ,CACN,SAAS,EACT,QAAQ,KAAK,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAC1D;gBACH;YACF,CAAC;YACD,MAAM,EAAE,MAAK;gBACX,IAAI,MAAM,IAAI,MAAM;oBAAE;gBACtB,MAAM,GAAG,IAAI;AACb,gBAAA,OAAO,EAAE;YACX,CAAC;AACD,YAAA,GAAG,EAAE,OAAO;AACZ,YAAA,YAAY,EAAE,OAAO;AACrB,YAAA,QAAQ,EAAE,MAAM,SAAS;AAC1B,SAAA;AACF,KAAA,CAAC;IACF,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;IAC9B,OAAO;QACL,KAAK,EAAE,MAAK;YACV,MAAM,GAAG,IAAI;YACb,KAAK,CAAC,KAAK,EAAE;QACf,CAAC;KACF;AACH;;;;"}

package/lib/core/observer/openIsolatedRecursiveWatch.mjs

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../transform/filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+import { openBrokeredWatch } from '../transform/tracker/broker/openBrokeredWatch.mjs';
+
+/**
+ * Open one recursive observer inside the transform core's isolated watch broker
+ * instead of the host process.
+ *
+ * On Windows, ttsc's direct native helper excludes access-only notifications
+ * and reports actual mutation, loss and failure through the same broker sink.
+ * On macOS, libuv serves every directory watch of a loop through one
+ * FSEventStream and re-creates it whenever any watch opens or closes, losing
+ * the events in between (samchon/ttsc#1418), where the broker opens one stream
+ * per watch. The observer's scopes get the isolation the transform core's
+ * trackers have, through the same registration (`openBrokeredWatch`) with a
+ * sink of their own that forwards events (samchon/ttsc#1485). Attributed events
+ * reach `listener` with a joined caller-directory path; unattributed events use
+ * null. A failed registration reaches `onError`, which hands the scope's
+ * entries to the bounded poll.
+ *
+ * Registration completes asynchronously, and FSEvents can later drop events
+ * (samchon/ttsc#1425). Until the broker confirms the watch, and whenever it
+ * reports such a gap or an event it could not place, an event can have gone
+ * unheard, so each is delivered as one unattributed event, which makes the
+ * observer re-check every entry the scope covers against its recorded state. On
+ * macOS a probe-capable project stream's child withholds ordinary callbacks
+ * until its opening probe returns (samchon/ttsc#1454). Ready promise completion
+ * only ends a wait; this wrapper rechecks unless closed or already failed,
+ * rather than certifying every earlier native mutation was observed.
+ *
+ * @param probeRoot The project root, when the scope is the project's: the
+ *   broker may then prove the scope's stream delivered, through a probe below
+ *   the project's tool cache (samchon/ttsc#1453). An external scope names
+ *   none.
+ * @evidence contracts/common.md#principled-implementation Broker isolation contains native watcher failures; opening confirmation and gaps trigger rechecks rather than authorizing unchanged inputs silently.
+ * @evidence contracts/common.md#clear-and-simple-design One registration forwards events and failures while the input observer owns conditions, polling, and consumer actions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The owned broker protocol does not patch native methods, and dropped events cannot become freshness proof.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains isolation, asynchronous readiness, gaps, and project-only probe ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral observation routes Windows and macOS native capability differences through the shared broker; native path joining reconstructs event paths, while failure and gaps require rechecks.
+ * @evidence contracts/performance.md#efficient-algorithms One location still delegates native normalization, optional probe namespace lookup/sweep, IPC encoding and cold child/backend setup. Each named callback joins path text and invokes the listener; condition batching and native/content revalidation cost remain with the observer, not bounded by one transport event.
+ * @evidence contracts/performance.md#reuse-equivalent-work Existing broker infrastructure is shared across scopes, while this registration retains its own event sink and observation authority.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One registration retains listener/error closures and a ready reaction. Close marks the wrapper inactive before attempting delegated cleanup, which can throw without proving child exit. Failure calls onError once but does not itself close; the owner must retire it. Late ready cannot reactivate closed/failed rechecks. Setup exceptions can occur before a handle is returned; rollback/deadline ownership remains with the broker operation.
+ */
+function openIsolatedRecursiveWatch(root, listener, onError, _admit, probeRoot) {
+    let closed = false;
+    let failed = false;
+    const recheck = () => {
+        if (!closed && !failed)
+            listener("rename", null);
+    };
+    const watch = openBrokeredWatch([{ directory: root, recursive: true }], {
+        allEvents: true,
+        // The scope never drains: its events are forwarded as they come, and a
+        // drain's verdict on other registrations' proofs is not its business.
+        drains: false,
+        filesystem: DEFAULT_FILESYSTEM_OPERATIONS,
+        ...(probeRoot === undefined ? {} : { probeRoot }),
+        sink: {
+            event: (directory, filename, eventType) => {
+                if (!closed) {
+                    listener(eventType, filename === null ? null : path.join(directory, filename));
+                }
+            },
+            failed: () => {
+                if (failed || closed)
+                    return;
+                failed = true;
+                onError();
+            },
+            gap: recheck,
+            unattributed: recheck,
+            unproven: () => undefined,
+        },
+    });
+    void watch.ready.then(recheck);
+    return {
+        close: () => {
+            closed = true;
+            watch.close();
+        },
+    };
+}
+
+export { openIsolatedRecursiveWatch };
+//# sourceMappingURL=openIsolatedRecursiveWatch.mjs.map

package/lib/core/observer/openIsolatedRecursiveWatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openIsolatedRecursiveWatch.mjs","sources":["../../../src/core/observer/openIsolatedRecursiveWatch.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCG;AACG,SAAU,0BAA0B,CACxC,IAAY,EACZ,QAA0D,EAC1D,OAAmB,EACnB,MAAuC,EACvC,SAAkB,EAAA;IAElB,IAAI,MAAM,GAAG,KAAK;IAClB,IAAI,MAAM,GAAG,KAAK;IAClB,MAAM,OAAO,GAAG,MAAW;AACzB,QAAA,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM;AAAE,YAAA,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;AAClD,IAAA,CAAC;AACD,IAAA,MAAM,KAAK,GAAG,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE;AACtE,QAAA,SAAS,EAAE,IAAI;;;AAGf,QAAA,MAAM,EAAE,KAAK;AACb,QAAA,UAAU,EAAE,6BAA6B;AACzC,QAAA,IAAI,SAAS,KAAK,SAAS,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;AACjD,QAAA,IAAI,EAAE;YACJ,KAAK,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,KAAI;gBACxC,IAAI,CAAC,MAAM,EAAE;oBACX,QAAQ,CACN,SAAS,EACT,QAAQ,KAAK,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAC1D;gBACH;YACF,CAAC;YACD,MAAM,EAAE,MAAK;gBACX,IAAI,MAAM,IAAI,MAAM;oBAAE;gBACtB,MAAM,GAAG,IAAI;AACb,gBAAA,OAAO,EAAE;YACX,CAAC;AACD,YAAA,GAAG,EAAE,OAAO;AACZ,YAAA,YAAY,EAAE,OAAO;AACrB,YAAA,QAAQ,EAAE,MAAM,SAAS;AAC1B,SAAA;AACF,KAAA,CAAC;IACF,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;IAC9B,OAAO;QACL,KAAK,EAAE,MAAK;YACV,MAAM,GAAG,IAAI;YACb,KAAK,CAAC,KAAK,EAAE;QACf,CAAC;KACF;AACH;;;;"}

package/lib/core/observer/openRecursiveWatch.d.cts

@@ -0,0 +1,33 @@
+/**
+ * Open the in-process recursive observer for one input observer scope, on a
+ * platform whose scopes are not brokered: Windows and macOS open theirs in the
+ * isolated watch broker instead (`openIsolatedRecursiveWatch`).
+ *
+ * Non-persistent, so it never keeps a host process alive by itself. Errors are
+ * reported to `onError`, which moves the scope's entries to the bounded
+ * fallback poll instead of losing them.
+ *
+ * The non-Windows/non-macOS branch selects the Linux directory observer instead
+ * of Node recursive traversal. It watches admitted directories and those its
+ * handle's `track` names (samchon/ttsc#1389); enumeration still sees entries it
+ * does not admit. Its watches live in the Linux helper and go live
+ * asynchronously (samchon/ttsc#1426), so once they are, the scope re-checks
+ * entries through one unattributed callback: an entry could have changed before
+ * any watch heard it. That callback requests a recheck, not proof of a complete
+ * event history. Unsupported helper platforms or acquisition errors must fall
+ * back through the owning observer's failure handling.
+ *
+ * @evidence contracts/common.md#principled-implementation Linux directory-level observation watches admitted paths and triggers readiness rechecks; native recursive failures enter the same conservative fallback boundary.
+ * @evidence contracts/common.md#clear-and-simple-design An explicit platform branch selects the Linux helper or Node backend, returning closure and optional directory tracking; actual readiness/failure stays with the selected backend.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Readiness triggers actual recorded-state checks, without assuming handle construction proves earlier unchanged inputs.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains recursive emulation cost and why asynchronous startup requires an unattributed event.
+ * @evidence contracts/portability.md#os-neutral-implementation The non-Windows/non-macOS branch delegates to the Linux helper, whose availability must actually hold; the other branch passes native root/recursive/nonpersistent options to Node. Platform selection alone proves no case policy, watcher coverage or success. Errors withdraw authority through the owner rather than pretending unsupported helper platforms work.
+ * @evidence contracts/performance.md#efficient-algorithms The helper enumerates admitted directory topology: D directory acquisitions still inspect E listed entries/native metadata and admission callbacks. The Node branch delegates recursive acquisition/notification work to its backend; neither one wrapper call nor directory-only handles bound listing bytes or callback revalidation cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work The shared Linux watch helper owns backend subscriptions, while scope callbacks keep their own coverage and proof conditions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned native/helper handle owns a scope until close; nonpersistence does not itself release it. Helper directory count follows admitted/explicitly tracked topology. The observer closes failed, unused external and disposed scopes; setup/cleanup can throw, and this wrapper adds no rollback, timeout or listener-effect cancellation beyond its backend.
+ */
+export declare function openRecursiveWatch(root: string, listener: (eventType: string, file: string | null) => void, onError: () => void, admit?: (directory: string) => boolean): {
+    close(): void;
+    track?(file: string, subtree?: boolean): void;
+    prune?(): void;
+};

package/lib/core/observer/openRecursiveWatch.d.mts

@@ -0,0 +1,33 @@
+/**
+ * Open the in-process recursive observer for one input observer scope, on a
+ * platform whose scopes are not brokered: Windows and macOS open theirs in the
+ * isolated watch broker instead (`openIsolatedRecursiveWatch`).
+ *
+ * Non-persistent, so it never keeps a host process alive by itself. Errors are
+ * reported to `onError`, which moves the scope's entries to the bounded
+ * fallback poll instead of losing them.
+ *
+ * The non-Windows/non-macOS branch selects the Linux directory observer instead
+ * of Node recursive traversal. It watches admitted directories and those its
+ * handle's `track` names (samchon/ttsc#1389); enumeration still sees entries it
+ * does not admit. Its watches live in the Linux helper and go live
+ * asynchronously (samchon/ttsc#1426), so once they are, the scope re-checks
+ * entries through one unattributed callback: an entry could have changed before
+ * any watch heard it. That callback requests a recheck, not proof of a complete
+ * event history. Unsupported helper platforms or acquisition errors must fall
+ * back through the owning observer's failure handling.
+ *
+ * @evidence contracts/common.md#principled-implementation Linux directory-level observation watches admitted paths and triggers readiness rechecks; native recursive failures enter the same conservative fallback boundary.
+ * @evidence contracts/common.md#clear-and-simple-design An explicit platform branch selects the Linux helper or Node backend, returning closure and optional directory tracking; actual readiness/failure stays with the selected backend.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Readiness triggers actual recorded-state checks, without assuming handle construction proves earlier unchanged inputs.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains recursive emulation cost and why asynchronous startup requires an unattributed event.
+ * @evidence contracts/portability.md#os-neutral-implementation The non-Windows/non-macOS branch delegates to the Linux helper, whose availability must actually hold; the other branch passes native root/recursive/nonpersistent options to Node. Platform selection alone proves no case policy, watcher coverage or success. Errors withdraw authority through the owner rather than pretending unsupported helper platforms work.
+ * @evidence contracts/performance.md#efficient-algorithms The helper enumerates admitted directory topology: D directory acquisitions still inspect E listed entries/native metadata and admission callbacks. The Node branch delegates recursive acquisition/notification work to its backend; neither one wrapper call nor directory-only handles bound listing bytes or callback revalidation cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work The shared Linux watch helper owns backend subscriptions, while scope callbacks keep their own coverage and proof conditions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned native/helper handle owns a scope until close; nonpersistence does not itself release it. Helper directory count follows admitted/explicitly tracked topology. The observer closes failed, unused external and disposed scopes; setup/cleanup can throw, and this wrapper adds no rollback, timeout or listener-effect cancellation beyond its backend.
+ */
+export declare function openRecursiveWatch(root: string, listener: (eventType: string, file: string | null) => void, onError: () => void, admit?: (directory: string) => boolean): {
+    close(): void;
+    track?(file: string, subtree?: boolean): void;
+    prune?(): void;
+};

package/lib/core/observer/openRecursiveWatch.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Open the in-process recursive observer for one input observer scope, on a
+ * platform whose scopes are not brokered: Windows and macOS open theirs in the
+ * isolated watch broker instead (`openIsolatedRecursiveWatch`).
+ *
+ * Non-persistent, so it never keeps a host process alive by itself. Errors are
+ * reported to `onError`, which moves the scope's entries to the bounded
+ * fallback poll instead of losing them.
+ *
+ * The non-Windows/non-macOS branch selects the Linux directory observer instead
+ * of Node recursive traversal. It watches admitted directories and those its
+ * handle's `track` names (samchon/ttsc#1389); enumeration still sees entries it
+ * does not admit. Its watches live in the Linux helper and go live
+ * asynchronously (samchon/ttsc#1426), so once they are, the scope re-checks
+ * entries through one unattributed callback: an entry could have changed before
+ * any watch heard it. That callback requests a recheck, not proof of a complete
+ * event history. Unsupported helper platforms or acquisition errors must fall
+ * back through the owning observer's failure handling.
+ *
+ * @evidence contracts/common.md#principled-implementation Linux directory-level observation watches admitted paths and triggers readiness rechecks; native recursive failures enter the same conservative fallback boundary.
+ * @evidence contracts/common.md#clear-and-simple-design An explicit platform branch selects the Linux helper or Node backend, returning closure and optional directory tracking; actual readiness/failure stays with the selected backend.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Readiness triggers actual recorded-state checks, without assuming handle construction proves earlier unchanged inputs.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains recursive emulation cost and why asynchronous startup requires an unattributed event.
+ * @evidence contracts/portability.md#os-neutral-implementation The non-Windows/non-macOS branch delegates to the Linux helper, whose availability must actually hold; the other branch passes native root/recursive/nonpersistent options to Node. Platform selection alone proves no case policy, watcher coverage or success. Errors withdraw authority through the owner rather than pretending unsupported helper platforms work.
+ * @evidence contracts/performance.md#efficient-algorithms The helper enumerates admitted directory topology: D directory acquisitions still inspect E listed entries/native metadata and admission callbacks. The Node branch delegates recursive acquisition/notification work to its backend; neither one wrapper call nor directory-only handles bound listing bytes or callback revalidation cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work The shared Linux watch helper owns backend subscriptions, while scope callbacks keep their own coverage and proof conditions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned native/helper handle owns a scope until close; nonpersistence does not itself release it. Helper directory count follows admitted/explicitly tracked topology. The observer closes failed, unused external and disposed scopes; setup/cleanup can throw, and this wrapper adds no rollback, timeout or listener-effect cancellation beyond its backend.
+ */
+export declare function openRecursiveWatch(root: string, listener: (eventType: string, file: string | null) => void, onError: () => void, admit?: (directory: string) => boolean): {
+    close(): void;
+    track?(file: string, subtree?: boolean): void;
+    prune?(): void;
+};

package/lib/core/observer/openRecursiveWatch.js

@@ -0,0 +1,49 @@
+'use strict';
+
+var fs = require('node:fs');
+var openLinuxDirectoryObserver = require('../transform/tracker/linux/openLinuxDirectoryObserver.js');
+
+/**
+ * Open the in-process recursive observer for one input observer scope, on a
+ * platform whose scopes are not brokered: Windows and macOS open theirs in the
+ * isolated watch broker instead (`openIsolatedRecursiveWatch`).
+ *
+ * Non-persistent, so it never keeps a host process alive by itself. Errors are
+ * reported to `onError`, which moves the scope's entries to the bounded
+ * fallback poll instead of losing them.
+ *
+ * The non-Windows/non-macOS branch selects the Linux directory observer instead
+ * of Node recursive traversal. It watches admitted directories and those its
+ * handle's `track` names (samchon/ttsc#1389); enumeration still sees entries it
+ * does not admit. Its watches live in the Linux helper and go live
+ * asynchronously (samchon/ttsc#1426), so once they are, the scope re-checks
+ * entries through one unattributed callback: an entry could have changed before
+ * any watch heard it. That callback requests a recheck, not proof of a complete
+ * event history. Unsupported helper platforms or acquisition errors must fall
+ * back through the owning observer's failure handling.
+ *
+ * @evidence contracts/common.md#principled-implementation Linux directory-level observation watches admitted paths and triggers readiness rechecks; native recursive failures enter the same conservative fallback boundary.
+ * @evidence contracts/common.md#clear-and-simple-design An explicit platform branch selects the Linux helper or Node backend, returning closure and optional directory tracking; actual readiness/failure stays with the selected backend.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Readiness triggers actual recorded-state checks, without assuming handle construction proves earlier unchanged inputs.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains recursive emulation cost and why asynchronous startup requires an unattributed event.
+ * @evidence contracts/portability.md#os-neutral-implementation The non-Windows/non-macOS branch delegates to the Linux helper, whose availability must actually hold; the other branch passes native root/recursive/nonpersistent options to Node. Platform selection alone proves no case policy, watcher coverage or success. Errors withdraw authority through the owner rather than pretending unsupported helper platforms work.
+ * @evidence contracts/performance.md#efficient-algorithms The helper enumerates admitted directory topology: D directory acquisitions still inspect E listed entries/native metadata and admission callbacks. The Node branch delegates recursive acquisition/notification work to its backend; neither one wrapper call nor directory-only handles bound listing bytes or callback revalidation cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work The shared Linux watch helper owns backend subscriptions, while scope callbacks keep their own coverage and proof conditions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned native/helper handle owns a scope until close; nonpersistence does not itself release it. Helper directory count follows admitted/explicitly tracked topology. The observer closes failed, unused external and disposed scopes; setup/cleanup can throw, and this wrapper adds no rollback, timeout or listener-effect cancellation beyond its backend.
+ */
+function openRecursiveWatch(root, listener, onError, admit = () => true) {
+    if (process.platform !== "darwin" && process.platform !== "win32") {
+        const observer = openLinuxDirectoryObserver.openLinuxDirectoryObserver(root, admit, listener, onError);
+        void observer.ready.then((live) => {
+            if (live)
+                listener("rename", null);
+        });
+        return observer;
+    }
+    const watcher = fs.watch(root, { persistent: false, recursive: true }, (eventType, file) => listener(eventType, file === null ? null : String(file)));
+    watcher.on("error", onError);
+    return { close: () => watcher.close() };
+}
+
+exports.openRecursiveWatch = openRecursiveWatch;
+//# sourceMappingURL=openRecursiveWatch.js.map

package/lib/core/observer/openRecursiveWatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openRecursiveWatch.js","sources":["../../../src/core/observer/openRecursiveWatch.ts"],"sourcesContent":[null],"names":["openLinuxDirectoryObserver"],"mappings":";;;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACG,SAAU,kBAAkB,CAChC,IAAY,EACZ,QAA0D,EAC1D,OAAmB,EACnB,KAAA,GAAwC,MAAM,IAAI,EAAA;AAMlD,IAAA,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE;AACjE,QAAA,MAAM,QAAQ,GAAGA,qDAA0B,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC;QAC3E,KAAK,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,KAAI;AAChC,YAAA,IAAI,IAAI;AAAE,gBAAA,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;AACpC,QAAA,CAAC,CAAC;AACF,QAAA,OAAO,QAAQ;IACjB;IACA,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CACtB,IAAI,EACJ,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,EACtC,CAAC,SAAS,EAAE,IAAI,KACd,QAAQ,CAAC,SAAS,EAAE,IAAI,KAAK,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAC3D;AACD,IAAA,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC;IAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,KAAK,EAAE,EAAE;AACzC;;;;"}

package/lib/core/observer/openRecursiveWatch.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import { openLinuxDirectoryObserver } from '../transform/tracker/linux/openLinuxDirectoryObserver.mjs';
+
+/**
+ * Open the in-process recursive observer for one input observer scope, on a
+ * platform whose scopes are not brokered: Windows and macOS open theirs in the
+ * isolated watch broker instead (`openIsolatedRecursiveWatch`).
+ *
+ * Non-persistent, so it never keeps a host process alive by itself. Errors are
+ * reported to `onError`, which moves the scope's entries to the bounded
+ * fallback poll instead of losing them.
+ *
+ * The non-Windows/non-macOS branch selects the Linux directory observer instead
+ * of Node recursive traversal. It watches admitted directories and those its
+ * handle's `track` names (samchon/ttsc#1389); enumeration still sees entries it
+ * does not admit. Its watches live in the Linux helper and go live
+ * asynchronously (samchon/ttsc#1426), so once they are, the scope re-checks
+ * entries through one unattributed callback: an entry could have changed before
+ * any watch heard it. That callback requests a recheck, not proof of a complete
+ * event history. Unsupported helper platforms or acquisition errors must fall
+ * back through the owning observer's failure handling.
+ *
+ * @evidence contracts/common.md#principled-implementation Linux directory-level observation watches admitted paths and triggers readiness rechecks; native recursive failures enter the same conservative fallback boundary.
+ * @evidence contracts/common.md#clear-and-simple-design An explicit platform branch selects the Linux helper or Node backend, returning closure and optional directory tracking; actual readiness/failure stays with the selected backend.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Readiness triggers actual recorded-state checks, without assuming handle construction proves earlier unchanged inputs.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains recursive emulation cost and why asynchronous startup requires an unattributed event.
+ * @evidence contracts/portability.md#os-neutral-implementation The non-Windows/non-macOS branch delegates to the Linux helper, whose availability must actually hold; the other branch passes native root/recursive/nonpersistent options to Node. Platform selection alone proves no case policy, watcher coverage or success. Errors withdraw authority through the owner rather than pretending unsupported helper platforms work.
+ * @evidence contracts/performance.md#efficient-algorithms The helper enumerates admitted directory topology: D directory acquisitions still inspect E listed entries/native metadata and admission callbacks. The Node branch delegates recursive acquisition/notification work to its backend; neither one wrapper call nor directory-only handles bound listing bytes or callback revalidation cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work The shared Linux watch helper owns backend subscriptions, while scope callbacks keep their own coverage and proof conditions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned native/helper handle owns a scope until close; nonpersistence does not itself release it. Helper directory count follows admitted/explicitly tracked topology. The observer closes failed, unused external and disposed scopes; setup/cleanup can throw, and this wrapper adds no rollback, timeout or listener-effect cancellation beyond its backend.
+ */
+function openRecursiveWatch(root, listener, onError, admit = () => true) {
+    if (process.platform !== "darwin" && process.platform !== "win32") {
+        const observer = openLinuxDirectoryObserver(root, admit, listener, onError);
+        void observer.ready.then((live) => {
+            if (live)
+                listener("rename", null);
+        });
+        return observer;
+    }
+    const watcher = fs.watch(root, { persistent: false, recursive: true }, (eventType, file) => listener(eventType, file === null ? null : String(file)));
+    watcher.on("error", onError);
+    return { close: () => watcher.close() };
+}
+
+export { openRecursiveWatch };
+//# sourceMappingURL=openRecursiveWatch.mjs.map

package/lib/core/observer/openRecursiveWatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openRecursiveWatch.mjs","sources":["../../../src/core/observer/openRecursiveWatch.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACG,SAAU,kBAAkB,CAChC,IAAY,EACZ,QAA0D,EAC1D,OAAmB,EACnB,KAAA,GAAwC,MAAM,IAAI,EAAA;AAMlD,IAAA,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE;AACjE,QAAA,MAAM,QAAQ,GAAG,0BAA0B,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC;QAC3E,KAAK,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,KAAI;AAChC,YAAA,IAAI,IAAI;AAAE,gBAAA,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;AACpC,QAAA,CAAC,CAAC;AACF,QAAA,OAAO,QAAQ;IACjB;IACA,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CACtB,IAAI,EACJ,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,EACtC,CAAC,SAAS,EAAE,IAAI,KACd,QAAQ,CAAC,SAAS,EAAE,IAAI,KAAK,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAC3D;AACD,IAAA,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC;IAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,KAAK,EAAE,EAAE;AACzC;;;;"}

package/lib/core/observer/openWatchPoller.d.cts

@@ -0,0 +1,19 @@
+/**
+ * Open the shared fallback poll that checks inputs no native scope can cover.
+ *
+ * One unreferenced interval serves an observer's fallback inputs. Its listener
+ * chooses per-tick probe slices; bounded probe counts do not bound native
+ * query, content-byte or affected-owner work per tick.
+ *
+ * @evidence contracts/common.md#principled-implementation One interval invokes fallback checks for inputs lacking native coverage, with an explicit returned close handle.
+ * @evidence contracts/common.md#clear-and-simple-design The provider owns timing only; bounded sampling and changed-condition decisions remain in its listener.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The unreferenced interval invokes real checks without replacing global timers or manufacturing events.
+ * @evidence contracts/common.md#meaningful-documentation The comment distinguishes shared scheduling from the bounded per-tick work owned by the observer.
+ * @evidence contracts/performance.md#efficient-algorithms One 500ms interval invokes one listener per tick; observer sampling/metadata/content/topology and affected-entry work remains delegated, without a listener CPU or byte bound here.
+ * @evidence contracts/performance.md#reuse-equivalent-work One observer-owned interval serves all uncovered inputs, avoiding one polling timer per path or consumer.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns one interval and its retained listener until close or process exit. Unref permits process exit but does not release the timer; close clears future ticks, without cancelling listener effects already performed or hiding listener exceptions.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Starts a timer and returns its closer; it reads no filesystem and parses no path.
+ */
+export declare function openWatchPoller(listener: () => void): {
+    close(): void;
+};

package/lib/core/observer/openWatchPoller.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Open the shared fallback poll that checks inputs no native scope can cover.
+ *
+ * One unreferenced interval serves an observer's fallback inputs. Its listener
+ * chooses per-tick probe slices; bounded probe counts do not bound native
+ * query, content-byte or affected-owner work per tick.
+ *
+ * @evidence contracts/common.md#principled-implementation One interval invokes fallback checks for inputs lacking native coverage, with an explicit returned close handle.
+ * @evidence contracts/common.md#clear-and-simple-design The provider owns timing only; bounded sampling and changed-condition decisions remain in its listener.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The unreferenced interval invokes real checks without replacing global timers or manufacturing events.
+ * @evidence contracts/common.md#meaningful-documentation The comment distinguishes shared scheduling from the bounded per-tick work owned by the observer.
+ * @evidence contracts/performance.md#efficient-algorithms One 500ms interval invokes one listener per tick; observer sampling/metadata/content/topology and affected-entry work remains delegated, without a listener CPU or byte bound here.
+ * @evidence contracts/performance.md#reuse-equivalent-work One observer-owned interval serves all uncovered inputs, avoiding one polling timer per path or consumer.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns one interval and its retained listener until close or process exit. Unref permits process exit but does not release the timer; close clears future ticks, without cancelling listener effects already performed or hiding listener exceptions.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Starts a timer and returns its closer; it reads no filesystem and parses no path.
+ */
+export declare function openWatchPoller(listener: () => void): {
+    close(): void;
+};

package/lib/core/observer/openWatchPoller.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Open the shared fallback poll that checks inputs no native scope can cover.
+ *
+ * One unreferenced interval serves an observer's fallback inputs. Its listener
+ * chooses per-tick probe slices; bounded probe counts do not bound native
+ * query, content-byte or affected-owner work per tick.
+ *
+ * @evidence contracts/common.md#principled-implementation One interval invokes fallback checks for inputs lacking native coverage, with an explicit returned close handle.
+ * @evidence contracts/common.md#clear-and-simple-design The provider owns timing only; bounded sampling and changed-condition decisions remain in its listener.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The unreferenced interval invokes real checks without replacing global timers or manufacturing events.
+ * @evidence contracts/common.md#meaningful-documentation The comment distinguishes shared scheduling from the bounded per-tick work owned by the observer.
+ * @evidence contracts/performance.md#efficient-algorithms One 500ms interval invokes one listener per tick; observer sampling/metadata/content/topology and affected-entry work remains delegated, without a listener CPU or byte bound here.
+ * @evidence contracts/performance.md#reuse-equivalent-work One observer-owned interval serves all uncovered inputs, avoiding one polling timer per path or consumer.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns one interval and its retained listener until close or process exit. Unref permits process exit but does not release the timer; close clears future ticks, without cancelling listener effects already performed or hiding listener exceptions.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Starts a timer and returns its closer; it reads no filesystem and parses no path.
+ */
+export declare function openWatchPoller(listener: () => void): {
+    close(): void;
+};

package/lib/core/observer/openWatchPoller.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * Open the shared fallback poll that checks inputs no native scope can cover.
+ *
+ * One unreferenced interval serves an observer's fallback inputs. Its listener
+ * chooses per-tick probe slices; bounded probe counts do not bound native
+ * query, content-byte or affected-owner work per tick.
+ *
+ * @evidence contracts/common.md#principled-implementation One interval invokes fallback checks for inputs lacking native coverage, with an explicit returned close handle.
+ * @evidence contracts/common.md#clear-and-simple-design The provider owns timing only; bounded sampling and changed-condition decisions remain in its listener.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The unreferenced interval invokes real checks without replacing global timers or manufacturing events.
+ * @evidence contracts/common.md#meaningful-documentation The comment distinguishes shared scheduling from the bounded per-tick work owned by the observer.
+ * @evidence contracts/performance.md#efficient-algorithms One 500ms interval invokes one listener per tick; observer sampling/metadata/content/topology and affected-entry work remains delegated, without a listener CPU or byte bound here.
+ * @evidence contracts/performance.md#reuse-equivalent-work One observer-owned interval serves all uncovered inputs, avoiding one polling timer per path or consumer.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns one interval and its retained listener until close or process exit. Unref permits process exit but does not release the timer; close clears future ticks, without cancelling listener effects already performed or hiding listener exceptions.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Starts a timer and returns its closer; it reads no filesystem and parses no path.
+ */
+function openWatchPoller(listener) {
+    const timer = setInterval(listener, 500);
+    timer.unref();
+    return { close: () => clearInterval(timer) };
+}
+
+exports.openWatchPoller = openWatchPoller;
+//# sourceMappingURL=openWatchPoller.js.map

package/lib/core/observer/openWatchPoller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openWatchPoller.js","sources":["../../../src/core/observer/openWatchPoller.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;AAeG;AACG,SAAU,eAAe,CAAC,QAAoB,EAAA;IAClD,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,EAAE,GAAG,CAAC;IACxC,KAAK,CAAC,KAAK,EAAE;IACb,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC,KAAK,CAAC,EAAE;AAC9C;;;;"}