@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/next/next.mjs

@@ -0,0 +1,371 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fallbackToolDirectory } from '../bridge/fallbackToolDirectory.mjs';
+import { hostToolDirectory } from '../bridge/hostToolDirectory.mjs';
+import { refreshProjectRecordFiles } from '../bridge/refreshProjectRecordFiles.mjs';
+import { TYPESCRIPT_TURBOPACK_RULE_GLOBS } from '../source/TYPESCRIPT_TURBOPACK_RULE_GLOBS.mjs';
+import { openTtscTransformSession } from '../transform/session/openTtscTransformSession.mjs';
+import { unplugin } from '../unplugin.mjs';
+import { TURBOPACK_PROJECT_WIDE_GLOB_COVERAGE } from './TURBOPACK_PROJECT_WIDE_GLOB_COVERAGE.mjs';
+
+/** The standalone loader entry Turbopack accepts through `turbopack.rules`. */
+const TURBOPACK_LOADER = "@ttsc/unplugin/turbopack";
+/**
+ * The globs the loader is wired for.
+ *
+ * The same exact set the manual wiring in the README uses. A wider glob would
+ * be harmless, since `isTransformTarget` declines everything else that reaches
+ * the loader, but it would also route files through a worker for nothing.
+ */
+const TURBOPACK_RULE_GLOBS = TYPESCRIPT_TURBOPACK_RULE_GLOBS;
+/**
+ * Wrap a Next.js config object so that ttsc runs under whichever bundler
+ * Next.js uses.
+ *
+ * The webpack plugin is injected through the `webpack` hook, and the Turbopack
+ * loader is wired through `turbopack.rules`, with the same options reaching
+ * both. Covering only webpack meant that a project on Turbopack, which is the
+ * default bundler in current Next majors, silently got no transform at all: the
+ * build succeeded and every plugin-driven construct in it, a typia
+ * `assert<T>()` above all, survived untransformed into a runtime failure
+ * (samchon/ttsc#1310).
+ *
+ * Both halves are additive. An existing `webpack` hook is preserved and called
+ * after the plugin is injected, with its returned object forwarded. Own
+ * enumerable Turbopack settings/rules are copied and nested caller values
+ * remain shared unless a source rule needs augmentation. Optional session
+ * storage lets workers adopt an equivalent proven publication; rejection or
+ * unavailable storage can require independent compilation.
+ *
+ * @param nextConfig - The caller's existing Next.js config (spread into the
+ *   returned object unchanged, except for `webpack` and `turbopack`).
+ * @param options - Ttsc plugin options forwarded to both bundlers.
+ * @evidence contracts/common.md#principled-implementation
+ *   The wrapper preserves caller settings and webpack-hook results while adding
+ *   both supported bundler integrations. Turbopack rule helpers preserve loader
+ *   ordering and conditions; only unconditional project-wide ownership suppresses
+ *   an additional ttsc rule, with resolved paths checked against package manifests.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The entry owns configuration/session orchestration; separate helpers own rule
+ *   shapes, coverage and loader identity instead of duplicating bundler policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Exact protocol glob/loader conventions implement host semantics. Resolved-loader
+ *   verification uses physical file ownership rather than basename guesses;
+ *   configuration hooks are preserved and no foreign runtime method is patched.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain additive integration and shared sessions. Helpers
+ *   document conditional rules, coverage limits and first-loader ordering, with
+ *   prose/tag separation following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Native joins, realpath and stat validate absolute loader ownership; file URLs
+ *   are decoded through Node's URL API. Host-local or accepted user fallback
+ *   directories carry records rather than a universal temporary-directory path.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Four exact source globs inspect R caller rules and their L loader entries;
+ *   project-wide coverage uses an indexed measured set. A per-invocation map
+ *   avoids repeated manifest/realpath checks of the same loader string.
+ *   Own setting/option keys and loader arrays are copied; cold ownership reads
+ *   retain path/manifest byte costs. Session setup includes native state/legacy
+ *   scans and reclamation; record refresh includes parsing/current proof/IO.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Loader ownership verdicts share one configuration snapshot and expire after
+ *   this call so later atomic installs or link retargets are observed. The process
+ *   session lets forked workers share generation identity with validation on adoption.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The ownership memo is call-local, but returned rule copies and webpack
+ *   closure/options live with the host config. The inherited store deliberately
+ *   persists across processes under its pruning owner; this wrapper adds no
+ *   count/byte bound or independent close. Plugin/cache owners acquire later
+ *   watchers/processes; no guaranteed complete storage reclamation is asserted.
+ */
+function next(nextConfig = {}, options) {
+    warnAboutSuppressedWebpackConfig(nextConfig);
+    // Turbopack forks its loader workers from this process after the config is
+    // read, so they inherit the session and compile each generation once
+    // between them (samchon/ttsc#1390).
+    openTtscTransformSession();
+    // Before either compiler validates a module against the cache below
+    // `.next`: a project whose state moved while nothing ran is heard through
+    // its record, which only a proof here can move.
+    refreshProjectRecordFiles(hostToolDirectory(process.cwd()));
+    // And where webpack's records live when that directory cannot be written
+    // (samchon/ttsc#1480); Turbopack's loader proves its own.
+    const fallback = fallbackToolDirectory(process.cwd());
+    if (fallback !== undefined)
+        refreshProjectRecordFiles(fallback);
+    return {
+        ...nextConfig,
+        turbopack: withTtscTurbopackRules(nextConfig.turbopack, options),
+        webpack(config, webpackOptions) {
+            config.plugins = Array.isArray(config.plugins) ? config.plugins : [];
+            // Prepend so ttsc runs before any user-added plugins.
+            config.plugins.unshift(unplugin.webpack(options));
+            if (typeof nextConfig.webpack === "function") {
+                return nextConfig.webpack(config, webpackOptions);
+            }
+            return config;
+        },
+    };
+}
+/**
+ * Say what Next.js can no longer say once this wrapper defines `turbopack`.
+ *
+ * Next stops the build when a config carries a `webpack` hook and no
+ * `turbopack` block, because the webpack hook is then silently ignored. Read
+ * from Next 16.3.2's own `dist/lib/turbopack-warning.js`, it is
+ * `log.error(...)` followed by `process.exit(1)` — a refusal, not a warning —
+ * and it is gated on `process.env.TURBOPACK === "auto"`, which
+ * `dist/lib/bundler.js` sets only when no bundler flag was passed. Next's
+ * comment there gives the reason: an explicit `--turbopack` means the user
+ * chose it and is assumed to have configured it. So the check fires on a plain
+ * `next build` or `next dev`, which is how Next 16 is normally run.
+ *
+ * `hasTurboConfig` is read from the raw exported config, which is this
+ * wrapper's return value, and this wrapper always defines `turbopack`. The
+ * check therefore can never fire again for anyone who uses `withTtsc`, and a
+ * caller's own webpack customisation would be dropped on a Turbopack build with
+ * nothing said. Wiring ttsc for Turbopack is worth exactly one line, not the
+ * loss of the refusal Next already gave.
+ *
+ * Verifying that gate is what this docstring exists for: measured with an
+ * explicit `--turbopack`, the check is silent, and a reading that stopped there
+ * would conclude Next says nothing and delete a true statement.
+ *
+ * Only for a caller who wrote a `webpack` hook and no `turbopack` block. A
+ * caller who configured Turbopack has already made that decision, and a caller
+ * with neither has no webpack-only configuration to lose.
+ */
+function warnAboutSuppressedWebpackConfig(nextConfig) {
+    if (typeof nextConfig.webpack !== "function" ||
+        nextConfig.turbopack !== undefined) {
+        return;
+    }
+    process.stderr.write("@ttsc/unplugin: withTtsc now configures Turbopack as well as webpack, so " +
+        "Next.js will no longer stop the build to tell you that your own " +
+        "`webpack` hook is ignored on a Turbopack build. Port it to `turbopack`, " +
+        "or run the bundler you configured with `next build --webpack` / " +
+        "`next dev --webpack`.\n");
+}
+/**
+ * Merge the ttsc loader rules into a caller's Turbopack configuration.
+ *
+ * Additive in every direction: unrelated Turbopack settings and unrelated rules
+ * are carried through untouched, and a glob the caller already configured keeps
+ * its own loaders with ttsc placed where the chain runs it first. A caller who
+ * already wired this loader by hand is left exactly as they are, so following
+ * the README's manual instructions and then adopting the wrapper cannot
+ * register it twice.
+ */
+function withTtscTurbopackRules(existing, options) {
+    const rules = { ...(existing?.rules ?? {}) };
+    // Package ownership is stable only for this configuration snapshot. A later
+    // call may observe an atomic install or a directory-link retarget at the same
+    // lexical loader path, so no verdict can escape this invocation.
+    const resolvedLoaderResults = new Map();
+    for (const glob of TURBOPACK_RULE_GLOBS) {
+        const rule = rules[glob];
+        if (hasUnconditionalTtscLoader(rule, resolvedLoaderResults)) {
+            continue;
+        }
+        // The caller may have written the same file set under a different glob.
+        // Adding ours beside theirs makes every matching module run the loader
+        // twice, and the second pass receives the first pass's output, so the
+        // guard has to cover the spellings a caller plausibly uses rather than
+        // only the four this wrapper writes (samchon/ttsc#1314).
+        if (coveredByAnotherRule(rules, glob, resolvedLoaderResults)) {
+            continue;
+        }
+        const entry = {
+            loader: TURBOPACK_LOADER,
+            options: { ...(options ?? {}) },
+        };
+        // Loader shorthand runs right to left, so ttsc is appended there to see
+        // the original source. Rule collections run matching items in order, so
+        // ttsc becomes an explicit first rule there for the same reason. That is
+        // the same position `enforce: "pre"` gives it on the webpack half.
+        //
+        // Measured rather than inferred from webpack's `loader-runner`: two
+        // loaders on one rule, each marking the source, came back marked in the
+        // order that only the last-runs-first chain produces (samchon/ttsc#1319).
+        rules[glob] = addUnconditionalTtscLoader(rule, entry);
+    }
+    return { ...(existing ?? {}), rules };
+}
+/**
+ * Whether some other rule already routes this glob's files through the loader.
+ *
+ * Deciding glob equivalence in general means implementing Turbopack's matcher,
+ * which is not worth it here. What is recognised instead is the spellings a
+ * caller plausibly writes for "every file with this extension", since only a
+ * glob that means every file can make the wrapper's own rules redundant. That
+ * is narrower than every glob with those semantics, and narrow on purpose:
+ * anything unrecognised is left alone and the wrapper still adds its rules,
+ * while skipping on a scoped glob would leave every module outside that scope
+ * untransformed, which is samchon/ttsc#1310 again and the quieter of the two
+ * failures. {@link matchesExtension} owns the rule and names what it declines.
+ */
+function coveredByAnotherRule(rules, glob, resolvedLoaderResults) {
+    const extension = glob.slice(glob.lastIndexOf(".") + 1);
+    return Object.entries(rules).some(([candidate, rule]) => {
+        if (candidate === glob) {
+            return false;
+        }
+        if (!hasUnconditionalTtscLoader(rule, resolvedLoaderResults)) {
+            return false;
+        }
+        return matchesExtension(candidate, extension);
+    });
+}
+/**
+ * Whether one glob names this extension across the whole project.
+ *
+ * Unscoped only. A rule carrying a path segment says nothing about the rest of
+ * the project, so treating it as covering everything would leave every module
+ * outside it with no ttsc rule at all. That is the silent failure
+ * samchon/ttsc#1310 is about, and it is strictly worse than the double
+ * registration this guard exists to prevent: a module no loader ever sees fails
+ * at runtime, while a module transformed twice costs time.
+ *
+ * How little a scoped rule covers is worth stating from measurement rather than
+ * from the obvious guess, because the guess is wrong. Against Next.js 16.3.2,
+ * `src/*.ts` and `src/**` + `/*.ts` match **nothing at all** — not even the
+ * `src/` subtree they name — while `./src/*.ts`, `**` + `/src/*.ts` and a bare
+ * `nested-probe.ts` all match a file at `src/`. Declining every one of them is
+ * therefore even safer than "it only covers its subtree" implies
+ * (samchon/ttsc#1319).
+ *
+ * The answer comes from {@link TURBOPACK_PROJECT_WIDE_GLOB_COVERAGE}, an exact
+ * set of measured spellings, and that document explains why it is a set rather
+ * than a rule.
+ */
+function matchesExtension(glob, extension) {
+    return PROJECT_WIDE_GLOBS.get(glob)?.includes(extension) === true;
+}
+/** {@link TURBOPACK_PROJECT_WIDE_GLOB_COVERAGE}, keyed by glob for lookup. */
+const PROJECT_WIDE_GLOBS = new Map(TURBOPACK_PROJECT_WIDE_GLOB_COVERAGE);
+/**
+ * Add one unconditional loader without flattening Next's rule collection.
+ *
+ * An array is either loader shorthand or a collection whose entries may be
+ * complete conditional rule objects, so it must remain an array. A collection
+ * executes every matching rule in order; its unconditional ttsc rule therefore
+ * comes first so it sees the original source before any caller rule. A
+ * conditioned object becomes that same two-item collection because putting ttsc
+ * inside the condition would leave the rest of the glob uncovered. An
+ * unconditioned object can keep its own shape while gaining the loader,
+ * including when it had no loaders.
+ */
+function addUnconditionalTtscLoader(rule, entry) {
+    if (Array.isArray(rule)) {
+        return rule.every(isTurbopackLoaderItem)
+            ? [...rule, entry]
+            : [{ loaders: [entry] }, ...rule];
+    }
+    if (typeof rule === "object" && rule !== null) {
+        if (rule.condition !== undefined) {
+            return [{ loaders: [entry] }, rule];
+        }
+        return {
+            ...rule,
+            loaders: [...selectTurbopackConfigLoaders(rule), entry],
+        };
+    }
+    return { loaders: [entry] };
+}
+/** Read the direct loader list from one Turbopack rule configuration item. */
+function selectTurbopackConfigLoaders(rule) {
+    if (typeof rule !== "object" || rule === null || Array.isArray(rule)) {
+        return [];
+    }
+    const loaders = rule.loaders;
+    return Array.isArray(loaders) ? loaders : [];
+}
+/** Whether a rule collection provides this loader without a condition. */
+function hasUnconditionalTtscLoader(rule, resolvedLoaderResults) {
+    if (Array.isArray(rule)) {
+        return rule.some((item) => {
+            if (isTurbopackLoaderItem(item)) {
+                return referencesTtscLoader(item, resolvedLoaderResults);
+            }
+            return (typeof item === "object" &&
+                item !== null &&
+                item.condition === undefined &&
+                selectTurbopackConfigLoaders(item).some((loader) => referencesTtscLoader(loader, resolvedLoaderResults)));
+        });
+    }
+    return (typeof rule === "object" &&
+        rule !== null &&
+        rule.condition === undefined &&
+        selectTurbopackConfigLoaders(rule).some((loader) => referencesTtscLoader(loader, resolvedLoaderResults)));
+}
+/** Whether one collection item is a direct Turbopack loader. */
+function isTurbopackLoaderItem(item) {
+    return (typeof item === "string" ||
+        (typeof item === "object" &&
+            item !== null &&
+            typeof item.loader === "string"));
+}
+/** Whether one Turbopack loader entry is already this package's loader. */
+function referencesTtscLoader(loader, resolvedLoaderResults) {
+    const identity = typeof loader === "string"
+        ? loader
+        : typeof loader === "object" && loader !== null
+            ? loader.loader
+            : undefined;
+    return (typeof identity === "string" &&
+        (identity === TURBOPACK_LOADER ||
+            isResolvedTtscLoader(identity, resolvedLoaderResults)));
+}
+/** Whether an absolute path is the Turbopack entry of an @ttsc/unplugin copy. */
+function isResolvedTtscLoader(identity, resolvedLoaderResults) {
+    const cached = resolvedLoaderResults.get(identity);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let file;
+    try {
+        file = /^file:/i.test(identity) ? fileURLToPath(identity) : identity;
+    }
+    catch {
+        resolvedLoaderResults.set(identity, false);
+        return false;
+    }
+    if (!path.isAbsolute(file)) {
+        resolvedLoaderResults.set(identity, false);
+        return false;
+    }
+    let resolvedFile;
+    try {
+        resolvedFile = fs.realpathSync.native(file);
+        if (!fs.statSync(resolvedFile).isFile()) {
+            resolvedLoaderResults.set(identity, false);
+            return false;
+        }
+    }
+    catch {
+        resolvedLoaderResults.set(identity, false);
+        return false;
+    }
+    const packageRoot = path.dirname(path.dirname(resolvedFile));
+    const relative = path
+        .relative(packageRoot, resolvedFile)
+        .replaceAll(path.sep, "/");
+    if (relative !== "lib/turbopack.js" && relative !== "lib/turbopack.mjs") {
+        resolvedLoaderResults.set(identity, false);
+        return false;
+    }
+    let matches = false;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        matches = manifest.name === "@ttsc/unplugin";
+    }
+    catch {
+        // An unreadable or malformed owner cannot prove this package's identity.
+    }
+    resolvedLoaderResults.set(identity, matches);
+    return matches;
+}
+
+export { next };
+//# sourceMappingURL=next.mjs.map

package/lib/core/next/next.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.mjs","sources":["../../../src/core/next/next.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

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

@@ -0,0 +1,41 @@
+import type { TtscWatchInputBaseline } from "../transform/watch/TtscWatchInputBaseline.cjs";
+import type { TtscWatchInputEvidence } from "../transform/watch/TtscWatchInputEvidence.cjs";
+/**
+ * One recorded state of a watched compiler input, shared by the owners that
+ * registered it.
+ *
+ * Either the generation's own evidence for the input, or a baseline this
+ * watcher attempted to capture itself. A failed baseline attempt stays
+ * undefined, and later comparison cannot certify it. The owners are told when
+ * the state no longer holds or cannot be proven. Conditions coexist when
+ * different generations recorded different states for it.
+ *
+ * @evidence contracts/common.md#principled-implementation Evidence or an observer baseline belongs to one condition, allowing different generations to share a path without overwriting each other's recorded state.
+ * @evidence contracts/common.md#clear-and-simple-design The condition combines one state representation and its owner set; path aliases and watch resources remain in the entry and scope.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing generation state attempts a current baseline; unavailable observation remains unproved rather than implying success or borrowing another owner's evidence.
+ * @evidence contracts/common.md#meaningful-documentation The native prose explains coexisting conditions, baseline fallback, and which owners hear a failed condition.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Evidence/baseline carry their owners' native identity, stat and realpath
+ *   observations, including unavailable states. Owner strings are the native
+ *   absolute registration spellings, not URLs or guessed physical aliases.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The carrier defines state/owner association; observer comparison owns
+ *   traversal, native observations and encoding costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The carrier defines no sharing coordinator; observer condition keys and
+ *   owner registration determine whether recorded states can be shared.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Observer entries own condition/owner retention and removal. This carrier
+ *   defines no independent acquisition, release or persistent state owner.
+ */
+export interface InputCondition {
+    /**
+     * State this watcher could capture when the evidence records none, even if
+     * evidence exists.
+     */
+    baseline?: TtscWatchInputBaseline;
+    /** The generation's recorded state for the input. */
+    evidence?: TtscWatchInputEvidence;
+    /** Native owner spellings notified when this state changes or is unproved. */
+    owners: Set<string>;
+}

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

@@ -0,0 +1,41 @@
+import type { TtscWatchInputBaseline } from "../transform/watch/TtscWatchInputBaseline.mjs";
+import type { TtscWatchInputEvidence } from "../transform/watch/TtscWatchInputEvidence.mjs";
+/**
+ * One recorded state of a watched compiler input, shared by the owners that
+ * registered it.
+ *
+ * Either the generation's own evidence for the input, or a baseline this
+ * watcher attempted to capture itself. A failed baseline attempt stays
+ * undefined, and later comparison cannot certify it. The owners are told when
+ * the state no longer holds or cannot be proven. Conditions coexist when
+ * different generations recorded different states for it.
+ *
+ * @evidence contracts/common.md#principled-implementation Evidence or an observer baseline belongs to one condition, allowing different generations to share a path without overwriting each other's recorded state.
+ * @evidence contracts/common.md#clear-and-simple-design The condition combines one state representation and its owner set; path aliases and watch resources remain in the entry and scope.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing generation state attempts a current baseline; unavailable observation remains unproved rather than implying success or borrowing another owner's evidence.
+ * @evidence contracts/common.md#meaningful-documentation The native prose explains coexisting conditions, baseline fallback, and which owners hear a failed condition.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Evidence/baseline carry their owners' native identity, stat and realpath
+ *   observations, including unavailable states. Owner strings are the native
+ *   absolute registration spellings, not URLs or guessed physical aliases.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The carrier defines state/owner association; observer comparison owns
+ *   traversal, native observations and encoding costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The carrier defines no sharing coordinator; observer condition keys and
+ *   owner registration determine whether recorded states can be shared.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Observer entries own condition/owner retention and removal. This carrier
+ *   defines no independent acquisition, release or persistent state owner.
+ */
+export interface InputCondition {
+    /**
+     * State this watcher could capture when the evidence records none, even if
+     * evidence exists.
+     */
+    baseline?: TtscWatchInputBaseline;
+    /** The generation's recorded state for the input. */
+    evidence?: TtscWatchInputEvidence;
+    /** Native owner spellings notified when this state changes or is unproved. */
+    owners: Set<string>;
+}

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

@@ -0,0 +1,41 @@
+import type { TtscWatchInputBaseline } from "../transform/watch/TtscWatchInputBaseline";
+import type { TtscWatchInputEvidence } from "../transform/watch/TtscWatchInputEvidence";
+/**
+ * One recorded state of a watched compiler input, shared by the owners that
+ * registered it.
+ *
+ * Either the generation's own evidence for the input, or a baseline this
+ * watcher attempted to capture itself. A failed baseline attempt stays
+ * undefined, and later comparison cannot certify it. The owners are told when
+ * the state no longer holds or cannot be proven. Conditions coexist when
+ * different generations recorded different states for it.
+ *
+ * @evidence contracts/common.md#principled-implementation Evidence or an observer baseline belongs to one condition, allowing different generations to share a path without overwriting each other's recorded state.
+ * @evidence contracts/common.md#clear-and-simple-design The condition combines one state representation and its owner set; path aliases and watch resources remain in the entry and scope.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing generation state attempts a current baseline; unavailable observation remains unproved rather than implying success or borrowing another owner's evidence.
+ * @evidence contracts/common.md#meaningful-documentation The native prose explains coexisting conditions, baseline fallback, and which owners hear a failed condition.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Evidence/baseline carry their owners' native identity, stat and realpath
+ *   observations, including unavailable states. Owner strings are the native
+ *   absolute registration spellings, not URLs or guessed physical aliases.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The carrier defines state/owner association; observer comparison owns
+ *   traversal, native observations and encoding costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The carrier defines no sharing coordinator; observer condition keys and
+ *   owner registration determine whether recorded states can be shared.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Observer entries own condition/owner retention and removal. This carrier
+ *   defines no independent acquisition, release or persistent state owner.
+ */
+export interface InputCondition {
+    /**
+     * State this watcher could capture when the evidence records none, even if
+     * evidence exists.
+     */
+    baseline?: TtscWatchInputBaseline;
+    /** The generation's recorded state for the input. */
+    evidence?: TtscWatchInputEvidence;
+    /** Native owner spellings notified when this state changes or is unproved. */
+    owners: Set<string>;
+}

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

@@ -0,0 +1,64 @@
+import type { InputCondition } from "./InputCondition.cjs";
+import type { WatchScope } from "./WatchScope.cjs";
+/**
+ * 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/InputEntry.d.mts

@@ -0,0 +1,64 @@
+import type { InputCondition } from "./InputCondition.mjs";
+import type { WatchScope } from "./WatchScope.mjs";
+/**
+ * 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>>;
+}