@ttsc/unplugin 0.30.4 → 0.31.1

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

@@ -0,0 +1,64 @@
+import type { InputCondition } from "./InputCondition";
+import type { WatchScope } from "./WatchScope";
+/**
+ * One compiler-input path an input observer (`createInputObserver`) is
+ * responsible for.
+ *
+ * Holds observed spelling keys (`aliases`), the ancestors whose rename can move
+ * it (`renameAliases`), the scopes and links observing it, and the recorded
+ * conditions that decide whether an event really changed it. `fallback` marks
+ * an entry the bounded poll checks instead of a native scope. These indexes do
+ * not enumerate every native event alias; a reporting scope rechecks its
+ * covered entries against their recorded conditions.
+ *
+ * @evidence contracts/common.md#principled-implementation A watched spelling keeps its recorded conditions separate from event aliases, link topology, and scope coverage, so notifications can select an entry before checking what its compile observed.
+ * @evidence contracts/common.md#clear-and-simple-design One entry holds shared path observation state while conditions own per-generation evidence and owners; native handles remain with scopes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An event or fallback flag is not itself a successful input proof; conditions must still be checked before notifying owners.
+ * @evidence contracts/common.md#meaningful-documentation Member comments distinguish lexical spelling, physical roots, event keys, and fallback reasons with their implementation consequences.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Lexical spelling, observed physical target, link topology and scope coverage
+ *   are distinct native boundary data. Alias keys cannot prove every possible
+ *   native notification spelling has been enumerated.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   InputEntry only declares a shape; it has no computation at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   InputEntry only declares a shape; it has no work to reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   InputEntry only declares a shape; it has no handle or retained state at
+ *   runtime.
+ */
+export interface InputEntry {
+    /**
+     * Observed event keys: its own spelling, its physical target, and linked
+     * components.
+     */
+    aliases: Set<string>;
+    /** Latest native event or new shared-scope admission for this spelling. */
+    changedAt: number;
+    /** Recorded states by serialized evidence, each with its owners. */
+    conditions: Map<string, InputCondition>;
+    /**
+     * Whether the bounded poll checks this entry: no native scope covers it, the
+     * owner declared polling, its directory's case policy could not be measured,
+     * it has more than one hard link, a linked component cannot be resolved, or
+     * its native watcher failed.
+     */
+    fallback: boolean;
+    /** Absolute spelling registered by the transform. */
+    file: string;
+    /**
+     * The physical spelling of a project root registered for its membership, when
+     * the root is named through a link: a backend that reports the physical path
+     * of what changed can name the root this way, and the event is placed under
+     * the root's own name before its policy is asked (samchon/ttsc#1461).
+     */
+    physical?: string;
+    /** Linked spellings whose retarget can move this entry without an event on it. */
+    links: Set<string>;
+    /** Ancestor keys whose rename can move this entry. */
+    renameAliases: Set<string>;
+    /** Native observers covering the entry. */
+    scopes: Set<WatchScope>;
+    /** Directory-admission keys contributed by this entry to each native scope. */
+    scopeDirectories: Map<WatchScope, Set<string>>;
+}

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

@@ -0,0 +1,142 @@
+import type { TtscWatchInput } from "../transform/watch/TtscWatchInput.cjs";
+/**
+ * The adapter's own observer of compiler inputs, keyed by owner
+ * (`createInputObserver`).
+ *
+ * @evidence contracts/common.md#principled-implementation Owner registrations and pre-compile sequence tokens preserve which recorded conditions authorize each consumer's delivery.
+ * @evidence contracts/common.md#clear-and-simple-design Root, registration, and lifetime boundaries stay independent of consumer-specific reload and record-signaling APIs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Owners register actual delivery dependencies; observation cannot manufacture compiler proof or host success.
+ * @evidence contracts/common.md#meaningful-documentation Method comments distinguish sequence capture, failed-delivery retention, and reusable lifetime after disposal.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Root and owner/input spellings form a native observation boundary. Native
+ *   sampling, alias/case authority and watch admission belong to the supplied
+ *   observer implementation; sequence tokens alone certify no native freshness.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   createInputObserver owns registration maps, condition proof and scope/poller
+ *   populations; this interface specifies their entry points, not algorithms.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The implementation owns qualified shared scopes and condition registrations;
+ *   method signatures alone grant no immutable or cached proof authority.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned observer implementation owns current scopes/timers/conditions;
+ *   this carrier specifies open/replacement/forget/disposal ownership operations.
+ */
+export interface InputObserver {
+    /**
+     * The current change sequence, taken before a compile so a registration can
+     * tell what changed during it.
+     *
+     * @evidence contracts/common.md#principled-implementation The token orders a compile against events and newly established scopes, letting replacement identify its observation window.
+     * @evidence contracts/common.md#clear-and-simple-design One number communicates ordering without copying observer history to every consumer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Capturing a token does not certify unchanged inputs; replacement still checks actual history.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains pre-compile capture and its later registration purpose.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of begin is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     */
+    begin(): number;
+    /**
+     * Forget every owner and attempt closure of current scopes, poller and timer.
+     * Native or supplied close refusal need not mean a handle actually closed.
+     * The observer stays open on its root, and observes owners again as they
+     * register.
+     *
+     * @evidence contracts/common.md#principled-implementation Disposal clears current registration authority and attempts independent cleanup while allowing later deliveries to register again on the root; successful native release is not guaranteed.
+     * @evidence contracts/common.md#clear-and-simple-design One lifecycle boundary releases observer-owned state rather than exposing every native watch to consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposal removes observation authority instead of transferring stale proof to new registrations.
+     * @evidence contracts/common.md#meaningful-documentation The prose distinguishes releasing current owners from permanently closing the observer.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of dispose is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Release every input one owner registered.
+     *
+     * @evidence contracts/common.md#principled-implementation Removing one owner preserves conditions still owned by others and releases inputs whose final registration leaves.
+     * @evidence contracts/common.md#clear-and-simple-design Owner identity selects the existing registration set without exposing shared-entry reference counts.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Owner removal cannot clear another owner's valid registration or alter its host methods.
+     * @evidence contracts/common.md#meaningful-documentation The comment identifies the owner as the unit of removal rather than a file or the whole observer.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   The owner is a native path spelling resolved by the observer, rather than
+     *   a URL or arbitrary numeric token; last-owner watch cleanup remains delegated.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     */
+    forget(owner: string): void;
+    /**
+     * Anchor the observer at a root, which a pinned scope then observes, unless
+     * the host declared polling, which sends every input to the bounded poll
+     * instead (samchon/ttsc#1395). Called again, it re-anchors. Nothing is
+     * observed before the first call.
+     *
+     * @evidence contracts/common.md#principled-implementation Opening establishes the project-root boundary and declares whether native notifications or polling can observe subsequent registrations.
+     * @evidence contracts/common.md#clear-and-simple-design Root anchoring and watch policy share one operation before registration begins.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A polling declaration prevents native silence from being treated as freshness authority.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains root anchoring, polling, and the unobserved state before first open.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   The root anchors native observation grammar and backend admission; polling
+     *   is an explicit host declaration, not an OS-name or case-policy inference.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     */
+    open(root: string, polling: boolean): void;
+    /**
+     * Replace one owner's inputs with a delivery's, keeping a failed delivery's
+     * previous spellings for recovery. Current proof can use the `startedAt`
+     * observation window when history and scope authority permit; fallback, newly
+     * recorded conditions or unavailable history still require disk replay
+     * (samchon/ttsc#1423).
+     *
+     * @evidence contracts/common.md#principled-implementation Replacement registers recorded conditions and checks the compile-to-subscribe window; failed delivery retains previous spellings that its exception may omit.
+     * @evidence contracts/common.md#clear-and-simple-design One operation updates the owner's conditions instead of exposing separate add/remove steps that could lose shared ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A token narrows proof only through actual history, and failure cannot erase prior recovery dependencies.
+     * @evidence contracts/common.md#meaningful-documentation The prose explains failed-delivery retention and why an optional pre-compile token affects validation.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   Owner and input files are native spellings paired with recorded identity
+     *   and codecs. The observer qualifies actual alias/case/watch authority;
+     *   optional sequence ordering supplies no new physical-identity assumption.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     */
+    replace(owner: string, inputs: readonly TtscWatchInput[], failed?: boolean, startedAt?: number): void;
+}

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

@@ -0,0 +1,142 @@
+import type { TtscWatchInput } from "../transform/watch/TtscWatchInput.mjs";
+/**
+ * The adapter's own observer of compiler inputs, keyed by owner
+ * (`createInputObserver`).
+ *
+ * @evidence contracts/common.md#principled-implementation Owner registrations and pre-compile sequence tokens preserve which recorded conditions authorize each consumer's delivery.
+ * @evidence contracts/common.md#clear-and-simple-design Root, registration, and lifetime boundaries stay independent of consumer-specific reload and record-signaling APIs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Owners register actual delivery dependencies; observation cannot manufacture compiler proof or host success.
+ * @evidence contracts/common.md#meaningful-documentation Method comments distinguish sequence capture, failed-delivery retention, and reusable lifetime after disposal.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Root and owner/input spellings form a native observation boundary. Native
+ *   sampling, alias/case authority and watch admission belong to the supplied
+ *   observer implementation; sequence tokens alone certify no native freshness.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   createInputObserver owns registration maps, condition proof and scope/poller
+ *   populations; this interface specifies their entry points, not algorithms.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The implementation owns qualified shared scopes and condition registrations;
+ *   method signatures alone grant no immutable or cached proof authority.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned observer implementation owns current scopes/timers/conditions;
+ *   this carrier specifies open/replacement/forget/disposal ownership operations.
+ */
+export interface InputObserver {
+    /**
+     * The current change sequence, taken before a compile so a registration can
+     * tell what changed during it.
+     *
+     * @evidence contracts/common.md#principled-implementation The token orders a compile against events and newly established scopes, letting replacement identify its observation window.
+     * @evidence contracts/common.md#clear-and-simple-design One number communicates ordering without copying observer history to every consumer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Capturing a token does not certify unchanged inputs; replacement still checks actual history.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains pre-compile capture and its later registration purpose.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of begin is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     */
+    begin(): number;
+    /**
+     * Forget every owner and attempt closure of current scopes, poller and timer.
+     * Native or supplied close refusal need not mean a handle actually closed.
+     * The observer stays open on its root, and observes owners again as they
+     * register.
+     *
+     * @evidence contracts/common.md#principled-implementation Disposal clears current registration authority and attempts independent cleanup while allowing later deliveries to register again on the root; successful native release is not guaranteed.
+     * @evidence contracts/common.md#clear-and-simple-design One lifecycle boundary releases observer-owned state rather than exposing every native watch to consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposal removes observation authority instead of transferring stale proof to new registrations.
+     * @evidence contracts/common.md#meaningful-documentation The prose distinguishes releasing current owners from permanently closing the observer.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of dispose is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Release every input one owner registered.
+     *
+     * @evidence contracts/common.md#principled-implementation Removing one owner preserves conditions still owned by others and releases inputs whose final registration leaves.
+     * @evidence contracts/common.md#clear-and-simple-design Owner identity selects the existing registration set without exposing shared-entry reference counts.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Owner removal cannot clear another owner's valid registration or alter its host methods.
+     * @evidence contracts/common.md#meaningful-documentation The comment identifies the owner as the unit of removal rather than a file or the whole observer.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   The owner is a native path spelling resolved by the observer, rather than
+     *   a URL or arbitrary numeric token; last-owner watch cleanup remains delegated.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     */
+    forget(owner: string): void;
+    /**
+     * Anchor the observer at a root, which a pinned scope then observes, unless
+     * the host declared polling, which sends every input to the bounded poll
+     * instead (samchon/ttsc#1395). Called again, it re-anchors. Nothing is
+     * observed before the first call.
+     *
+     * @evidence contracts/common.md#principled-implementation Opening establishes the project-root boundary and declares whether native notifications or polling can observe subsequent registrations.
+     * @evidence contracts/common.md#clear-and-simple-design Root anchoring and watch policy share one operation before registration begins.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A polling declaration prevents native silence from being treated as freshness authority.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains root anchoring, polling, and the unobserved state before first open.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   The root anchors native observation grammar and backend admission; polling
+     *   is an explicit host declaration, not an OS-name or case-policy inference.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     */
+    open(root: string, polling: boolean): void;
+    /**
+     * Replace one owner's inputs with a delivery's, keeping a failed delivery's
+     * previous spellings for recovery. Current proof can use the `startedAt`
+     * observation window when history and scope authority permit; fallback, newly
+     * recorded conditions or unavailable history still require disk replay
+     * (samchon/ttsc#1423).
+     *
+     * @evidence contracts/common.md#principled-implementation Replacement registers recorded conditions and checks the compile-to-subscribe window; failed delivery retains previous spellings that its exception may omit.
+     * @evidence contracts/common.md#clear-and-simple-design One operation updates the owner's conditions instead of exposing separate add/remove steps that could lose shared ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A token narrows proof only through actual history, and failure cannot erase prior recovery dependencies.
+     * @evidence contracts/common.md#meaningful-documentation The prose explains failed-delivery retention and why an optional pre-compile token affects validation.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   Owner and input files are native spellings paired with recorded identity
+     *   and codecs. The observer qualifies actual alias/case/watch authority;
+     *   optional sequence ordering supplies no new physical-identity assumption.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     */
+    replace(owner: string, inputs: readonly TtscWatchInput[], failed?: boolean, startedAt?: number): void;
+}

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

@@ -0,0 +1,142 @@
+import type { TtscWatchInput } from "../transform/watch/TtscWatchInput";
+/**
+ * The adapter's own observer of compiler inputs, keyed by owner
+ * (`createInputObserver`).
+ *
+ * @evidence contracts/common.md#principled-implementation Owner registrations and pre-compile sequence tokens preserve which recorded conditions authorize each consumer's delivery.
+ * @evidence contracts/common.md#clear-and-simple-design Root, registration, and lifetime boundaries stay independent of consumer-specific reload and record-signaling APIs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Owners register actual delivery dependencies; observation cannot manufacture compiler proof or host success.
+ * @evidence contracts/common.md#meaningful-documentation Method comments distinguish sequence capture, failed-delivery retention, and reusable lifetime after disposal.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Root and owner/input spellings form a native observation boundary. Native
+ *   sampling, alias/case authority and watch admission belong to the supplied
+ *   observer implementation; sequence tokens alone certify no native freshness.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   createInputObserver owns registration maps, condition proof and scope/poller
+ *   populations; this interface specifies their entry points, not algorithms.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The implementation owns qualified shared scopes and condition registrations;
+ *   method signatures alone grant no immutable or cached proof authority.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned observer implementation owns current scopes/timers/conditions;
+ *   this carrier specifies open/replacement/forget/disposal ownership operations.
+ */
+export interface InputObserver {
+    /**
+     * The current change sequence, taken before a compile so a registration can
+     * tell what changed during it.
+     *
+     * @evidence contracts/common.md#principled-implementation The token orders a compile against events and newly established scopes, letting replacement identify its observation window.
+     * @evidence contracts/common.md#clear-and-simple-design One number communicates ordering without copying observer history to every consumer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Capturing a token does not certify unchanged inputs; replacement still checks actual history.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains pre-compile capture and its later registration purpose.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of begin is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     */
+    begin(): number;
+    /**
+     * Forget every owner and attempt closure of current scopes, poller and timer.
+     * Native or supplied close refusal need not mean a handle actually closed.
+     * The observer stays open on its root, and observes owners again as they
+     * register.
+     *
+     * @evidence contracts/common.md#principled-implementation Disposal clears current registration authority and attempts independent cleanup while allowing later deliveries to register again on the root; successful native release is not guaranteed.
+     * @evidence contracts/common.md#clear-and-simple-design One lifecycle boundary releases observer-owned state rather than exposing every native watch to consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposal removes observation authority instead of transferring stale proof to new registrations.
+     * @evidence contracts/common.md#meaningful-documentation The prose distinguishes releasing current owners from permanently closing the observer.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of dispose is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of dispose is declared here; the cost belongs to its
+     *   implementation.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Release every input one owner registered.
+     *
+     * @evidence contracts/common.md#principled-implementation Removing one owner preserves conditions still owned by others and releases inputs whose final registration leaves.
+     * @evidence contracts/common.md#clear-and-simple-design Owner identity selects the existing registration set without exposing shared-entry reference counts.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Owner removal cannot clear another owner's valid registration or alter its host methods.
+     * @evidence contracts/common.md#meaningful-documentation The comment identifies the owner as the unit of removal rather than a file or the whole observer.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   The owner is a native path spelling resolved by the observer, rather than
+     *   a URL or arbitrary numeric token; last-owner watch cleanup remains delegated.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of forget is declared here; the cost belongs to its
+     *   implementation.
+     */
+    forget(owner: string): void;
+    /**
+     * Anchor the observer at a root, which a pinned scope then observes, unless
+     * the host declared polling, which sends every input to the bounded poll
+     * instead (samchon/ttsc#1395). Called again, it re-anchors. Nothing is
+     * observed before the first call.
+     *
+     * @evidence contracts/common.md#principled-implementation Opening establishes the project-root boundary and declares whether native notifications or polling can observe subsequent registrations.
+     * @evidence contracts/common.md#clear-and-simple-design Root anchoring and watch policy share one operation before registration begins.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A polling declaration prevents native silence from being treated as freshness authority.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains root anchoring, polling, and the unobserved state before first open.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   The root anchors native observation grammar and backend admission; polling
+     *   is an explicit host declaration, not an OS-name or case-policy inference.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of open is declared here; the cost belongs to its
+     *   implementation.
+     */
+    open(root: string, polling: boolean): void;
+    /**
+     * Replace one owner's inputs with a delivery's, keeping a failed delivery's
+     * previous spellings for recovery. Current proof can use the `startedAt`
+     * observation window when history and scope authority permit; fallback, newly
+     * recorded conditions or unavailable history still require disk replay
+     * (samchon/ttsc#1423).
+     *
+     * @evidence contracts/common.md#principled-implementation Replacement registers recorded conditions and checks the compile-to-subscribe window; failed delivery retains previous spellings that its exception may omit.
+     * @evidence contracts/common.md#clear-and-simple-design One operation updates the owner's conditions instead of exposing separate add/remove steps that could lose shared ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A token narrows proof only through actual history, and failure cannot erase prior recovery dependencies.
+     * @evidence contracts/common.md#meaningful-documentation The prose explains failed-delivery retention and why an optional pre-compile token affects validation.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   Owner and input files are native spellings paired with recorded identity
+     *   and codecs. The observer qualifies actual alias/case/watch authority;
+     *   optional sequence ordering supplies no new physical-identity assumption.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of replace is declared here; the cost belongs to its
+     *   implementation.
+     */
+    replace(owner: string, inputs: readonly TtscWatchInput[], failed?: boolean, startedAt?: number): void;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Which owners an input observer (`createInputObserver`) found to have changed
+ * or unproved recorded input states in one settled batch.
+ *
+ * The two sets are disjoint: an owner that has both a changed input and a
+ * membership change is in `reload` alone.
+ *
+ * @evidence contracts/common.md#principled-implementation Disjoint reload and invalidate sets distinguish failed non-membership state checks from membership-only failures; reload takes precedence when both occur.
+ * @evidence contracts/common.md#clear-and-simple-design The observer reports owner identities and change category, leaving host-specific actions to the callback consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The result reports failed state comparisons, including unavailable proof, rather than fabricating a host reload or equating every event with changed compiler output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states set disjointness and explains why membership-only changes deserve a separate action.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Both sets carry native absolute owner registration spellings unchanged.
+ *   Native registration resolves them; this result does not convert them to
+ *   browser identifiers, fold case or certify physical alias equivalence.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   This result specifies categories and disjointness; observer checks and
+ *   host callbacks own their processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This result defines no completed/in-flight computation coordinator;
+ *   condition validation and host action sharing belong to their owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The observer creates these sets and hands them to its callback. This
+ *   carrier defines no independent handle/task or retention policy.
+ */
+export interface InputObserverChange {
+    /**
+     * Owners whose only failed comparison concerns root-file membership,
+     * including changed or unavailable membership proof, with no failed content
+     * state, so a host that can tell the two apart re-runs them without an update
+     * of their own (samchon/ttsc#1419).
+     */
+    invalidate: ReadonlySet<string>;
+    /** Native owners with a changed or unproved non-membership input state. */
+    reload: ReadonlySet<string>;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Which owners an input observer (`createInputObserver`) found to have changed
+ * or unproved recorded input states in one settled batch.
+ *
+ * The two sets are disjoint: an owner that has both a changed input and a
+ * membership change is in `reload` alone.
+ *
+ * @evidence contracts/common.md#principled-implementation Disjoint reload and invalidate sets distinguish failed non-membership state checks from membership-only failures; reload takes precedence when both occur.
+ * @evidence contracts/common.md#clear-and-simple-design The observer reports owner identities and change category, leaving host-specific actions to the callback consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The result reports failed state comparisons, including unavailable proof, rather than fabricating a host reload or equating every event with changed compiler output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states set disjointness and explains why membership-only changes deserve a separate action.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Both sets carry native absolute owner registration spellings unchanged.
+ *   Native registration resolves them; this result does not convert them to
+ *   browser identifiers, fold case or certify physical alias equivalence.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   This result specifies categories and disjointness; observer checks and
+ *   host callbacks own their processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This result defines no completed/in-flight computation coordinator;
+ *   condition validation and host action sharing belong to their owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The observer creates these sets and hands them to its callback. This
+ *   carrier defines no independent handle/task or retention policy.
+ */
+export interface InputObserverChange {
+    /**
+     * Owners whose only failed comparison concerns root-file membership,
+     * including changed or unavailable membership proof, with no failed content
+     * state, so a host that can tell the two apart re-runs them without an update
+     * of their own (samchon/ttsc#1419).
+     */
+    invalidate: ReadonlySet<string>;
+    /** Native owners with a changed or unproved non-membership input state. */
+    reload: ReadonlySet<string>;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Which owners an input observer (`createInputObserver`) found to have changed
+ * or unproved recorded input states in one settled batch.
+ *
+ * The two sets are disjoint: an owner that has both a changed input and a
+ * membership change is in `reload` alone.
+ *
+ * @evidence contracts/common.md#principled-implementation Disjoint reload and invalidate sets distinguish failed non-membership state checks from membership-only failures; reload takes precedence when both occur.
+ * @evidence contracts/common.md#clear-and-simple-design The observer reports owner identities and change category, leaving host-specific actions to the callback consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The result reports failed state comparisons, including unavailable proof, rather than fabricating a host reload or equating every event with changed compiler output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states set disjointness and explains why membership-only changes deserve a separate action.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Both sets carry native absolute owner registration spellings unchanged.
+ *   Native registration resolves them; this result does not convert them to
+ *   browser identifiers, fold case or certify physical alias equivalence.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   This result specifies categories and disjointness; observer checks and
+ *   host callbacks own their processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This result defines no completed/in-flight computation coordinator;
+ *   condition validation and host action sharing belong to their owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The observer creates these sets and hands them to its callback. This
+ *   carrier defines no independent handle/task or retention policy.
+ */
+export interface InputObserverChange {
+    /**
+     * Owners whose only failed comparison concerns root-file membership,
+     * including changed or unavailable membership proof, with no failed content
+     * state, so a host that can tell the two apart re-runs them without an update
+     * of their own (samchon/ttsc#1419).
+     */
+    invalidate: ReadonlySet<string>;
+    /** Native owners with a changed or unproved non-membership input state. */
+    reload: ReadonlySet<string>;
+}