@ttsc/unplugin 0.30.4 → 0.31.0

package/lib/core/transform/session/sharedCompileIdentity.d.cts

@@ -0,0 +1,42 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions.cjs";
+/**
+ * Hex digest of what a whole-project compile is, apart from the files it reads
+ * (samchon/ttsc#1390).
+ *
+ * The ordered JSON tuple groups sharing candidates by spelled config and source
+ * root, serialized compiler-option/alias/plugin payloads, reported versions and
+ * binary platform. Supported option values must preserve their meaning through
+ * JSON; omitted or unsupported JavaScript values are not independent key
+ * dimensions. This is a truncated digest, not a complete filesystem or output
+ * equivalence proof. Claim publication and adoption separately establish the
+ * recorded input/stability premises for a reused compile.
+ *
+ * A compile is kept beyond the process that published it, so a dev server
+ * started again adopts what the last one compiled (samchon/ttsc#1483). The
+ * compiler that ran is therefore part of the identity too: the ttsc and
+ * TypeScript-Go versions every plugin build is keyed on, by ttsc's own rule
+ * (`pluginBuildVersions` from `ttsc/plugin-source`), this adapter's version,
+ * whose code decides what an adopter proves, and the platform the binaries were
+ * built for. The plugins' own Go sources and the environment each builds in are
+ * not: each directory's state is proven when the envelope is adopted
+ * (`pluginSourceStateHolds`, samchon/ttsc#1487, samchon/ttsc#1493). Unknown
+ * metadata fallback values do not independently distinguish missing versions.
+ *
+ * @param props.projectRoot The project the compile runs for, which resolves its
+ *   TypeScript-Go.
+ * @evidence contracts/common.md#principled-implementation The ordered JSON tuple hashes spelled config and source root, serialized options/aliases/plugins, reported versions and binary platform into the claim's configuration key. JSON-compatible value semantics and separately validated recorded input state are premises; a key match alone is not a filesystem or output proof, and unknown version metadata remains a limitation.
+ * @evidence contracts/common.md#clear-and-simple-design One tuple hashes configuration and version identity; source-state proof remains separate rather than being duplicated in this key.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform identity legitimately separates compiled binaries; it is not a fixed platform assumption or an excuse to omit plugin-source validation on adoption.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains retained publications, version ownership, and why plugin-source state is proven elsewhere.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Tuple, encoded JSON and hash object are call-local; the returned digest transfers to the claim owner. Cached installation/version strings and module metadata belong to their reader owners, not an independent history or native handle acquired here.
+ * @evidence contracts/performance.md#efficient-algorithms JSON serialization and SHA-256 scan the full encoded tuple text, with temporary tuple/JSON storage proportional to its payload. pluginBuildVersions adds project package resolution, manifest read/parse and any cold host-version read; unpluginVersion adds its cold self-manifest resolution. Native path/ancestor/module-resolution and metadata byte populations remain costs beyond one logical helper call. Caller getters or toJSON methods can add work or throw during encoding. The output retains 32 hex characters of the digest.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation calculates a key and coordinates no completed publication or in-flight claim itself. Store claiming and capture adoption own sharing permission and proof; version helpers share only their own process-stable metadata, while this call observes the project-resolved version anew.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform/architecture distinguish binary targets, and the config spelling is serialized unchanged. Project and executing package versions come through Node native package resolution/readers; no OS-name case rule substitutes for that boundary. Reported metadata and a platform tuple still do not certify current native input identity or publication validity.
+ */
+export declare function sharedCompileIdentity(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    projectRoot: string;
+    tsconfig: string;
+}): string;

package/lib/core/transform/session/sharedCompileIdentity.d.mts

@@ -0,0 +1,42 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions.mjs";
+/**
+ * Hex digest of what a whole-project compile is, apart from the files it reads
+ * (samchon/ttsc#1390).
+ *
+ * The ordered JSON tuple groups sharing candidates by spelled config and source
+ * root, serialized compiler-option/alias/plugin payloads, reported versions and
+ * binary platform. Supported option values must preserve their meaning through
+ * JSON; omitted or unsupported JavaScript values are not independent key
+ * dimensions. This is a truncated digest, not a complete filesystem or output
+ * equivalence proof. Claim publication and adoption separately establish the
+ * recorded input/stability premises for a reused compile.
+ *
+ * A compile is kept beyond the process that published it, so a dev server
+ * started again adopts what the last one compiled (samchon/ttsc#1483). The
+ * compiler that ran is therefore part of the identity too: the ttsc and
+ * TypeScript-Go versions every plugin build is keyed on, by ttsc's own rule
+ * (`pluginBuildVersions` from `ttsc/plugin-source`), this adapter's version,
+ * whose code decides what an adopter proves, and the platform the binaries were
+ * built for. The plugins' own Go sources and the environment each builds in are
+ * not: each directory's state is proven when the envelope is adopted
+ * (`pluginSourceStateHolds`, samchon/ttsc#1487, samchon/ttsc#1493). Unknown
+ * metadata fallback values do not independently distinguish missing versions.
+ *
+ * @param props.projectRoot The project the compile runs for, which resolves its
+ *   TypeScript-Go.
+ * @evidence contracts/common.md#principled-implementation The ordered JSON tuple hashes spelled config and source root, serialized options/aliases/plugins, reported versions and binary platform into the claim's configuration key. JSON-compatible value semantics and separately validated recorded input state are premises; a key match alone is not a filesystem or output proof, and unknown version metadata remains a limitation.
+ * @evidence contracts/common.md#clear-and-simple-design One tuple hashes configuration and version identity; source-state proof remains separate rather than being duplicated in this key.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform identity legitimately separates compiled binaries; it is not a fixed platform assumption or an excuse to omit plugin-source validation on adoption.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains retained publications, version ownership, and why plugin-source state is proven elsewhere.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Tuple, encoded JSON and hash object are call-local; the returned digest transfers to the claim owner. Cached installation/version strings and module metadata belong to their reader owners, not an independent history or native handle acquired here.
+ * @evidence contracts/performance.md#efficient-algorithms JSON serialization and SHA-256 scan the full encoded tuple text, with temporary tuple/JSON storage proportional to its payload. pluginBuildVersions adds project package resolution, manifest read/parse and any cold host-version read; unpluginVersion adds its cold self-manifest resolution. Native path/ancestor/module-resolution and metadata byte populations remain costs beyond one logical helper call. Caller getters or toJSON methods can add work or throw during encoding. The output retains 32 hex characters of the digest.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation calculates a key and coordinates no completed publication or in-flight claim itself. Store claiming and capture adoption own sharing permission and proof; version helpers share only their own process-stable metadata, while this call observes the project-resolved version anew.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform/architecture distinguish binary targets, and the config spelling is serialized unchanged. Project and executing package versions come through Node native package resolution/readers; no OS-name case rule substitutes for that boundary. Reported metadata and a platform tuple still do not certify current native input identity or publication validity.
+ */
+export declare function sharedCompileIdentity(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    projectRoot: string;
+    tsconfig: string;
+}): string;

package/lib/core/transform/session/sharedCompileIdentity.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedTtscUnpluginOptions } from "../../options/ResolvedTtscUnpluginOptions";
+/**
+ * Hex digest of what a whole-project compile is, apart from the files it reads
+ * (samchon/ttsc#1390).
+ *
+ * The ordered JSON tuple groups sharing candidates by spelled config and source
+ * root, serialized compiler-option/alias/plugin payloads, reported versions and
+ * binary platform. Supported option values must preserve their meaning through
+ * JSON; omitted or unsupported JavaScript values are not independent key
+ * dimensions. This is a truncated digest, not a complete filesystem or output
+ * equivalence proof. Claim publication and adoption separately establish the
+ * recorded input/stability premises for a reused compile.
+ *
+ * A compile is kept beyond the process that published it, so a dev server
+ * started again adopts what the last one compiled (samchon/ttsc#1483). The
+ * compiler that ran is therefore part of the identity too: the ttsc and
+ * TypeScript-Go versions every plugin build is keyed on, by ttsc's own rule
+ * (`pluginBuildVersions` from `ttsc/plugin-source`), this adapter's version,
+ * whose code decides what an adopter proves, and the platform the binaries were
+ * built for. The plugins' own Go sources and the environment each builds in are
+ * not: each directory's state is proven when the envelope is adopted
+ * (`pluginSourceStateHolds`, samchon/ttsc#1487, samchon/ttsc#1493). Unknown
+ * metadata fallback values do not independently distinguish missing versions.
+ *
+ * @param props.projectRoot The project the compile runs for, which resolves its
+ *   TypeScript-Go.
+ * @evidence contracts/common.md#principled-implementation The ordered JSON tuple hashes spelled config and source root, serialized options/aliases/plugins, reported versions and binary platform into the claim's configuration key. JSON-compatible value semantics and separately validated recorded input state are premises; a key match alone is not a filesystem or output proof, and unknown version metadata remains a limitation.
+ * @evidence contracts/common.md#clear-and-simple-design One tuple hashes configuration and version identity; source-state proof remains separate rather than being duplicated in this key.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform identity legitimately separates compiled binaries; it is not a fixed platform assumption or an excuse to omit plugin-source validation on adoption.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains retained publications, version ownership, and why plugin-source state is proven elsewhere.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Tuple, encoded JSON and hash object are call-local; the returned digest transfers to the claim owner. Cached installation/version strings and module metadata belong to their reader owners, not an independent history or native handle acquired here.
+ * @evidence contracts/performance.md#efficient-algorithms JSON serialization and SHA-256 scan the full encoded tuple text, with temporary tuple/JSON storage proportional to its payload. pluginBuildVersions adds project package resolution, manifest read/parse and any cold host-version read; unpluginVersion adds its cold self-manifest resolution. Native path/ancestor/module-resolution and metadata byte populations remain costs beyond one logical helper call. Caller getters or toJSON methods can add work or throw during encoding. The output retains 32 hex characters of the digest.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation calculates a key and coordinates no completed publication or in-flight claim itself. Store claiming and capture adoption own sharing permission and proof; version helpers share only their own process-stable metadata, while this call observes the project-resolved version anew.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform/architecture distinguish binary targets, and the config spelling is serialized unchanged. Project and executing package versions come through Node native package resolution/readers; no OS-name case rule substitutes for that boundary. Reported metadata and a platform tuple still do not certify current native input identity or publication validity.
+ */
+export declare function sharedCompileIdentity(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    plugins?: ResolvedTtscUnpluginOptions["plugins"];
+    projectRoot: string;
+    tsconfig: string;
+}): string;

package/lib/core/transform/session/sharedCompileIdentity.js

@@ -0,0 +1,59 @@
+'use strict';
+
+var crypto = require('node:crypto');
+var pluginSource = require('ttsc/plugin-source');
+var unpluginVersion = require('./unpluginVersion.js');
+
+/**
+ * Hex digest of what a whole-project compile is, apart from the files it reads
+ * (samchon/ttsc#1390).
+ *
+ * The ordered JSON tuple groups sharing candidates by spelled config and source
+ * root, serialized compiler-option/alias/plugin payloads, reported versions and
+ * binary platform. Supported option values must preserve their meaning through
+ * JSON; omitted or unsupported JavaScript values are not independent key
+ * dimensions. This is a truncated digest, not a complete filesystem or output
+ * equivalence proof. Claim publication and adoption separately establish the
+ * recorded input/stability premises for a reused compile.
+ *
+ * A compile is kept beyond the process that published it, so a dev server
+ * started again adopts what the last one compiled (samchon/ttsc#1483). The
+ * compiler that ran is therefore part of the identity too: the ttsc and
+ * TypeScript-Go versions every plugin build is keyed on, by ttsc's own rule
+ * (`pluginBuildVersions` from `ttsc/plugin-source`), this adapter's version,
+ * whose code decides what an adopter proves, and the platform the binaries were
+ * built for. The plugins' own Go sources and the environment each builds in are
+ * not: each directory's state is proven when the envelope is adopted
+ * (`pluginSourceStateHolds`, samchon/ttsc#1487, samchon/ttsc#1493). Unknown
+ * metadata fallback values do not independently distinguish missing versions.
+ *
+ * @param props.projectRoot The project the compile runs for, which resolves its
+ *   TypeScript-Go.
+ * @evidence contracts/common.md#principled-implementation The ordered JSON tuple hashes spelled config and source root, serialized options/aliases/plugins, reported versions and binary platform into the claim's configuration key. JSON-compatible value semantics and separately validated recorded input state are premises; a key match alone is not a filesystem or output proof, and unknown version metadata remains a limitation.
+ * @evidence contracts/common.md#clear-and-simple-design One tuple hashes configuration and version identity; source-state proof remains separate rather than being duplicated in this key.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform identity legitimately separates compiled binaries; it is not a fixed platform assumption or an excuse to omit plugin-source validation on adoption.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains retained publications, version ownership, and why plugin-source state is proven elsewhere.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Tuple, encoded JSON and hash object are call-local; the returned digest transfers to the claim owner. Cached installation/version strings and module metadata belong to their reader owners, not an independent history or native handle acquired here.
+ * @evidence contracts/performance.md#efficient-algorithms JSON serialization and SHA-256 scan the full encoded tuple text, with temporary tuple/JSON storage proportional to its payload. pluginBuildVersions adds project package resolution, manifest read/parse and any cold host-version read; unpluginVersion adds its cold self-manifest resolution. Native path/ancestor/module-resolution and metadata byte populations remain costs beyond one logical helper call. Caller getters or toJSON methods can add work or throw during encoding. The output retains 32 hex characters of the digest.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation calculates a key and coordinates no completed publication or in-flight claim itself. Store claiming and capture adoption own sharing permission and proof; version helpers share only their own process-stable metadata, while this call observes the project-resolved version anew.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform/architecture distinguish binary targets, and the config spelling is serialized unchanged. Project and executing package versions come through Node native package resolution/readers; no OS-name case rule substitutes for that boundary. Reported metadata and a platform tuple still do not certify current native input identity or publication validity.
+ */
+function sharedCompileIdentity(props) {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify([
+        props.tsconfig,
+        props.projectRoot,
+        props.compilerOptions,
+        props.aliasPaths,
+        props.plugins ?? null,
+        pluginSource.pluginBuildVersions(props.projectRoot),
+        unpluginVersion.unpluginVersion(),
+        `${process.platform}-${process.arch}`,
+    ]))
+        .digest("hex")
+        .slice(0, 32);
+}
+
+exports.sharedCompileIdentity = sharedCompileIdentity;
+//# sourceMappingURL=sharedCompileIdentity.js.map

package/lib/core/transform/session/sharedCompileIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedCompileIdentity.js","sources":["../../../../src/core/transform/session/sharedCompileIdentity.ts"],"sourcesContent":[null],"names":["pluginBuildVersions","unpluginVersion"],"mappings":";;;;;;AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCG;AACG,SAAU,qBAAqB,CAAC,KAMrC,EAAA;AACC,IAAA,OAAO;SACJ,UAAU,CAAC,QAAQ;AACnB,SAAA,MAAM,CACL,IAAI,CAAC,SAAS,CAAC;AACb,QAAA,KAAK,CAAC,QAAQ;AACd,QAAA,KAAK,CAAC,WAAW;AACjB,QAAA,KAAK,CAAC,eAAe;AACrB,QAAA,KAAK,CAAC,UAAU;QAChB,KAAK,CAAC,OAAO,IAAI,IAAI;AACrB,QAAAA,gCAAmB,CAAC,KAAK,CAAC,WAAW,CAAC;AACtC,QAAAC,+BAAe,EAAE;AACjB,QAAA,CAAA,EAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAA,CAAE;AACtC,KAAA,CAAC;SAEH,MAAM,CAAC,KAAK;AACZ,SAAA,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;AACjB;;;;"}

package/lib/core/transform/session/sharedCompileIdentity.mjs

@@ -0,0 +1,57 @@
+import crypto from 'node:crypto';
+import { pluginBuildVersions } from 'ttsc/plugin-source';
+import { unpluginVersion } from './unpluginVersion.mjs';
+
+/**
+ * Hex digest of what a whole-project compile is, apart from the files it reads
+ * (samchon/ttsc#1390).
+ *
+ * The ordered JSON tuple groups sharing candidates by spelled config and source
+ * root, serialized compiler-option/alias/plugin payloads, reported versions and
+ * binary platform. Supported option values must preserve their meaning through
+ * JSON; omitted or unsupported JavaScript values are not independent key
+ * dimensions. This is a truncated digest, not a complete filesystem or output
+ * equivalence proof. Claim publication and adoption separately establish the
+ * recorded input/stability premises for a reused compile.
+ *
+ * A compile is kept beyond the process that published it, so a dev server
+ * started again adopts what the last one compiled (samchon/ttsc#1483). The
+ * compiler that ran is therefore part of the identity too: the ttsc and
+ * TypeScript-Go versions every plugin build is keyed on, by ttsc's own rule
+ * (`pluginBuildVersions` from `ttsc/plugin-source`), this adapter's version,
+ * whose code decides what an adopter proves, and the platform the binaries were
+ * built for. The plugins' own Go sources and the environment each builds in are
+ * not: each directory's state is proven when the envelope is adopted
+ * (`pluginSourceStateHolds`, samchon/ttsc#1487, samchon/ttsc#1493). Unknown
+ * metadata fallback values do not independently distinguish missing versions.
+ *
+ * @param props.projectRoot The project the compile runs for, which resolves its
+ *   TypeScript-Go.
+ * @evidence contracts/common.md#principled-implementation The ordered JSON tuple hashes spelled config and source root, serialized options/aliases/plugins, reported versions and binary platform into the claim's configuration key. JSON-compatible value semantics and separately validated recorded input state are premises; a key match alone is not a filesystem or output proof, and unknown version metadata remains a limitation.
+ * @evidence contracts/common.md#clear-and-simple-design One tuple hashes configuration and version identity; source-state proof remains separate rather than being duplicated in this key.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform identity legitimately separates compiled binaries; it is not a fixed platform assumption or an excuse to omit plugin-source validation on adoption.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains retained publications, version ownership, and why plugin-source state is proven elsewhere.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Tuple, encoded JSON and hash object are call-local; the returned digest transfers to the claim owner. Cached installation/version strings and module metadata belong to their reader owners, not an independent history or native handle acquired here.
+ * @evidence contracts/performance.md#efficient-algorithms JSON serialization and SHA-256 scan the full encoded tuple text, with temporary tuple/JSON storage proportional to its payload. pluginBuildVersions adds project package resolution, manifest read/parse and any cold host-version read; unpluginVersion adds its cold self-manifest resolution. Native path/ancestor/module-resolution and metadata byte populations remain costs beyond one logical helper call. Caller getters or toJSON methods can add work or throw during encoding. The output retains 32 hex characters of the digest.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation calculates a key and coordinates no completed publication or in-flight claim itself. Store claiming and capture adoption own sharing permission and proof; version helpers share only their own process-stable metadata, while this call observes the project-resolved version anew.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform/architecture distinguish binary targets, and the config spelling is serialized unchanged. Project and executing package versions come through Node native package resolution/readers; no OS-name case rule substitutes for that boundary. Reported metadata and a platform tuple still do not certify current native input identity or publication validity.
+ */
+function sharedCompileIdentity(props) {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify([
+        props.tsconfig,
+        props.projectRoot,
+        props.compilerOptions,
+        props.aliasPaths,
+        props.plugins ?? null,
+        pluginBuildVersions(props.projectRoot),
+        unpluginVersion(),
+        `${process.platform}-${process.arch}`,
+    ]))
+        .digest("hex")
+        .slice(0, 32);
+}
+
+export { sharedCompileIdentity };
+//# sourceMappingURL=sharedCompileIdentity.mjs.map

package/lib/core/transform/session/sharedCompileIdentity.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedCompileIdentity.mjs","sources":["../../../../src/core/transform/session/sharedCompileIdentity.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCG;AACG,SAAU,qBAAqB,CAAC,KAMrC,EAAA;AACC,IAAA,OAAO;SACJ,UAAU,CAAC,QAAQ;AACnB,SAAA,MAAM,CACL,IAAI,CAAC,SAAS,CAAC;AACb,QAAA,KAAK,CAAC,QAAQ;AACd,QAAA,KAAK,CAAC,WAAW;AACjB,QAAA,KAAK,CAAC,eAAe;AACrB,QAAA,KAAK,CAAC,UAAU;QAChB,KAAK,CAAC,OAAO,IAAI,IAAI;AACrB,QAAA,mBAAmB,CAAC,KAAK,CAAC,WAAW,CAAC;AACtC,QAAA,eAAe,EAAE;AACjB,QAAA,CAAA,EAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAA,CAAE;AACtC,KAAA,CAAC;SAEH,MAAM,CAAC,KAAK;AACZ,SAAA,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;AACjB;;;;"}

package/lib/core/transform/session/sharedCompileState.d.cts

@@ -0,0 +1,30 @@
+import type { TtscProjectDirectorySnapshot } from "../project/TtscProjectDirectorySnapshot.cjs";
+/**
+ * Hex digest of the project state a compile reads, from the snapshot a worker
+ * takes before compiling (samchon/ttsc#1390).
+ *
+ * It encodes supplied file hash entries, relevant directory path/signature
+ * records and the caller's tsconfig-state signature. Capture supplies a
+ * complete before-walk snapshot before making a shared claim. Irrelevant
+ * directory records are omitted by their recorded relevance flag, not by an
+ * output name. This truncated key does not establish snapshot completeness or
+ * stability itself: publication and adoption retain those proof
+ * responsibilities. Inputs outside the walk, such as the reference graph's and
+ * the plugins' own inputs, are not in the digest: the envelope records their
+ * compile-time state, and the adopter proves it against the filesystem as it
+ * would its own compile's.
+ *
+ * @evidence contracts/common.md#principled-implementation Sorted file keys and relevant directory addresses stream distinct file/directory records with their recorded hash/signature values after the config signature. The actual producer supplies native names without NUL and scalar hashes/signatures; this is a projection key, not standalone completeness or current-state proof. External inputs retain separate adoption validation.
+ * @evidence contracts/common.md#clear-and-simple-design The digest streams the three existing snapshot components and filters only directories the membership policy already classified as irrelevant.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No output-directory name is guessed here and a matching digest does not replace the publisher's stability or adopter's external-input proof.
+ * @evidence contracts/common.md#meaningful-documentation The comment defines the digest's included and excluded inputs and why both publication and adoption still require proof.
+ * @evidence contracts/performance.md#efficient-algorithms Object.keys materializes and sorts F file keys; filtering scans all D directory records before sorting R relevant paths. Key/path comparisons and each streamed config/key/hash/signature frame pay text/UTF-8 encoding and hash work. Temporary key/filter arrays follow F and R, and each update constructs a frame string; no source byte contents or full serialized snapshot is copied. The returned key retains 32 hex characters.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure snapshot digest coordinates no cache or in-flight computation; producer and adopter owners decide when matching state permits sharing a compile.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Ordering arrays and the hash object remain local; the digest transfers to the caller and no historical snapshot, handle or task is retained.
+ * @evidence contracts/portability.md#os-neutral-implementation File keys and directory addresses remain exactly as the native snapshot producer recorded them; sorting and framing add no case folding, separator conversion or physical alias equality. Sharing requires comparable captured address domains from the caller, and this encoding performs no new native identity observation or filesystem read.
+ */
+export declare function sharedCompileState(props: {
+    directories: readonly TtscProjectDirectorySnapshot[];
+    hashes: Readonly<Record<string, string>>;
+    tsconfigSignature: string;
+}): string;

package/lib/core/transform/session/sharedCompileState.d.mts

@@ -0,0 +1,30 @@
+import type { TtscProjectDirectorySnapshot } from "../project/TtscProjectDirectorySnapshot.mjs";
+/**
+ * Hex digest of the project state a compile reads, from the snapshot a worker
+ * takes before compiling (samchon/ttsc#1390).
+ *
+ * It encodes supplied file hash entries, relevant directory path/signature
+ * records and the caller's tsconfig-state signature. Capture supplies a
+ * complete before-walk snapshot before making a shared claim. Irrelevant
+ * directory records are omitted by their recorded relevance flag, not by an
+ * output name. This truncated key does not establish snapshot completeness or
+ * stability itself: publication and adoption retain those proof
+ * responsibilities. Inputs outside the walk, such as the reference graph's and
+ * the plugins' own inputs, are not in the digest: the envelope records their
+ * compile-time state, and the adopter proves it against the filesystem as it
+ * would its own compile's.
+ *
+ * @evidence contracts/common.md#principled-implementation Sorted file keys and relevant directory addresses stream distinct file/directory records with their recorded hash/signature values after the config signature. The actual producer supplies native names without NUL and scalar hashes/signatures; this is a projection key, not standalone completeness or current-state proof. External inputs retain separate adoption validation.
+ * @evidence contracts/common.md#clear-and-simple-design The digest streams the three existing snapshot components and filters only directories the membership policy already classified as irrelevant.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No output-directory name is guessed here and a matching digest does not replace the publisher's stability or adopter's external-input proof.
+ * @evidence contracts/common.md#meaningful-documentation The comment defines the digest's included and excluded inputs and why both publication and adoption still require proof.
+ * @evidence contracts/performance.md#efficient-algorithms Object.keys materializes and sorts F file keys; filtering scans all D directory records before sorting R relevant paths. Key/path comparisons and each streamed config/key/hash/signature frame pay text/UTF-8 encoding and hash work. Temporary key/filter arrays follow F and R, and each update constructs a frame string; no source byte contents or full serialized snapshot is copied. The returned key retains 32 hex characters.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure snapshot digest coordinates no cache or in-flight computation; producer and adopter owners decide when matching state permits sharing a compile.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Ordering arrays and the hash object remain local; the digest transfers to the caller and no historical snapshot, handle or task is retained.
+ * @evidence contracts/portability.md#os-neutral-implementation File keys and directory addresses remain exactly as the native snapshot producer recorded them; sorting and framing add no case folding, separator conversion or physical alias equality. Sharing requires comparable captured address domains from the caller, and this encoding performs no new native identity observation or filesystem read.
+ */
+export declare function sharedCompileState(props: {
+    directories: readonly TtscProjectDirectorySnapshot[];
+    hashes: Readonly<Record<string, string>>;
+    tsconfigSignature: string;
+}): string;

package/lib/core/transform/session/sharedCompileState.d.ts

@@ -0,0 +1,30 @@
+import type { TtscProjectDirectorySnapshot } from "../project/TtscProjectDirectorySnapshot";
+/**
+ * Hex digest of the project state a compile reads, from the snapshot a worker
+ * takes before compiling (samchon/ttsc#1390).
+ *
+ * It encodes supplied file hash entries, relevant directory path/signature
+ * records and the caller's tsconfig-state signature. Capture supplies a
+ * complete before-walk snapshot before making a shared claim. Irrelevant
+ * directory records are omitted by their recorded relevance flag, not by an
+ * output name. This truncated key does not establish snapshot completeness or
+ * stability itself: publication and adoption retain those proof
+ * responsibilities. Inputs outside the walk, such as the reference graph's and
+ * the plugins' own inputs, are not in the digest: the envelope records their
+ * compile-time state, and the adopter proves it against the filesystem as it
+ * would its own compile's.
+ *
+ * @evidence contracts/common.md#principled-implementation Sorted file keys and relevant directory addresses stream distinct file/directory records with their recorded hash/signature values after the config signature. The actual producer supplies native names without NUL and scalar hashes/signatures; this is a projection key, not standalone completeness or current-state proof. External inputs retain separate adoption validation.
+ * @evidence contracts/common.md#clear-and-simple-design The digest streams the three existing snapshot components and filters only directories the membership policy already classified as irrelevant.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No output-directory name is guessed here and a matching digest does not replace the publisher's stability or adopter's external-input proof.
+ * @evidence contracts/common.md#meaningful-documentation The comment defines the digest's included and excluded inputs and why both publication and adoption still require proof.
+ * @evidence contracts/performance.md#efficient-algorithms Object.keys materializes and sorts F file keys; filtering scans all D directory records before sorting R relevant paths. Key/path comparisons and each streamed config/key/hash/signature frame pay text/UTF-8 encoding and hash work. Temporary key/filter arrays follow F and R, and each update constructs a frame string; no source byte contents or full serialized snapshot is copied. The returned key retains 32 hex characters.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure snapshot digest coordinates no cache or in-flight computation; producer and adopter owners decide when matching state permits sharing a compile.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Ordering arrays and the hash object remain local; the digest transfers to the caller and no historical snapshot, handle or task is retained.
+ * @evidence contracts/portability.md#os-neutral-implementation File keys and directory addresses remain exactly as the native snapshot producer recorded them; sorting and framing add no case folding, separator conversion or physical alias equality. Sharing requires comparable captured address domains from the caller, and this encoding performs no new native identity observation or filesystem read.
+ */
+export declare function sharedCompileState(props: {
+    directories: readonly TtscProjectDirectorySnapshot[];
+    hashes: Readonly<Record<string, string>>;
+    tsconfigSignature: string;
+}): string;

package/lib/core/transform/session/sharedCompileState.js

@@ -0,0 +1,44 @@
+'use strict';
+
+var crypto = require('node:crypto');
+
+/**
+ * Hex digest of the project state a compile reads, from the snapshot a worker
+ * takes before compiling (samchon/ttsc#1390).
+ *
+ * It encodes supplied file hash entries, relevant directory path/signature
+ * records and the caller's tsconfig-state signature. Capture supplies a
+ * complete before-walk snapshot before making a shared claim. Irrelevant
+ * directory records are omitted by their recorded relevance flag, not by an
+ * output name. This truncated key does not establish snapshot completeness or
+ * stability itself: publication and adoption retain those proof
+ * responsibilities. Inputs outside the walk, such as the reference graph's and
+ * the plugins' own inputs, are not in the digest: the envelope records their
+ * compile-time state, and the adopter proves it against the filesystem as it
+ * would its own compile's.
+ *
+ * @evidence contracts/common.md#principled-implementation Sorted file keys and relevant directory addresses stream distinct file/directory records with their recorded hash/signature values after the config signature. The actual producer supplies native names without NUL and scalar hashes/signatures; this is a projection key, not standalone completeness or current-state proof. External inputs retain separate adoption validation.
+ * @evidence contracts/common.md#clear-and-simple-design The digest streams the three existing snapshot components and filters only directories the membership policy already classified as irrelevant.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No output-directory name is guessed here and a matching digest does not replace the publisher's stability or adopter's external-input proof.
+ * @evidence contracts/common.md#meaningful-documentation The comment defines the digest's included and excluded inputs and why both publication and adoption still require proof.
+ * @evidence contracts/performance.md#efficient-algorithms Object.keys materializes and sorts F file keys; filtering scans all D directory records before sorting R relevant paths. Key/path comparisons and each streamed config/key/hash/signature frame pay text/UTF-8 encoding and hash work. Temporary key/filter arrays follow F and R, and each update constructs a frame string; no source byte contents or full serialized snapshot is copied. The returned key retains 32 hex characters.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure snapshot digest coordinates no cache or in-flight computation; producer and adopter owners decide when matching state permits sharing a compile.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Ordering arrays and the hash object remain local; the digest transfers to the caller and no historical snapshot, handle or task is retained.
+ * @evidence contracts/portability.md#os-neutral-implementation File keys and directory addresses remain exactly as the native snapshot producer recorded them; sorting and framing add no case folding, separator conversion or physical alias equality. Sharing requires comparable captured address domains from the caller, and this encoding performs no new native identity observation or filesystem read.
+ */
+function sharedCompileState(props) {
+    const hash = crypto.createHash("sha256");
+    hash.update(`${props.tsconfigSignature}\n`);
+    for (const key of Object.keys(props.hashes).sort()) {
+        hash.update(`f\0${key}\0${props.hashes[key]}\n`);
+    }
+    for (const directory of props.directories
+        .filter((directory) => directory.relevant)
+        .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)) {
+        hash.update(`d\0${directory.path}\0${directory.signature}\n`);
+    }
+    return hash.digest("hex").slice(0, 32);
+}
+
+exports.sharedCompileState = sharedCompileState;
+//# sourceMappingURL=sharedCompileState.js.map

package/lib/core/transform/session/sharedCompileState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedCompileState.js","sources":["../../../../src/core/transform/session/sharedCompileState.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACG,SAAU,kBAAkB,CAAC,KAIlC,EAAA;IACC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,CAAA,EAAG,KAAK,CAAC,iBAAiB,CAAA,EAAA,CAAI,CAAC;AAC3C,IAAA,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;AAClD,QAAA,IAAI,CAAC,MAAM,CAAC,CAAA,GAAA,EAAM,GAAG,CAAA,EAAA,EAAK,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA,EAAA,CAAI,CAAC;IAClD;AACA,IAAA,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC;SAC3B,MAAM,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,QAAQ;AACxC,SAAA,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,KAChB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAC7D,EAAE;AACH,QAAA,IAAI,CAAC,MAAM,CAAC,CAAA,GAAA,EAAM,SAAS,CAAC,IAAI,CAAA,EAAA,EAAK,SAAS,CAAC,SAAS,CAAA,EAAA,CAAI,CAAC;IAC/D;AACA,IAAA,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;AACxC;;;;"}

package/lib/core/transform/session/sharedCompileState.mjs

@@ -0,0 +1,42 @@
+import crypto from 'node:crypto';
+
+/**
+ * Hex digest of the project state a compile reads, from the snapshot a worker
+ * takes before compiling (samchon/ttsc#1390).
+ *
+ * It encodes supplied file hash entries, relevant directory path/signature
+ * records and the caller's tsconfig-state signature. Capture supplies a
+ * complete before-walk snapshot before making a shared claim. Irrelevant
+ * directory records are omitted by their recorded relevance flag, not by an
+ * output name. This truncated key does not establish snapshot completeness or
+ * stability itself: publication and adoption retain those proof
+ * responsibilities. Inputs outside the walk, such as the reference graph's and
+ * the plugins' own inputs, are not in the digest: the envelope records their
+ * compile-time state, and the adopter proves it against the filesystem as it
+ * would its own compile's.
+ *
+ * @evidence contracts/common.md#principled-implementation Sorted file keys and relevant directory addresses stream distinct file/directory records with their recorded hash/signature values after the config signature. The actual producer supplies native names without NUL and scalar hashes/signatures; this is a projection key, not standalone completeness or current-state proof. External inputs retain separate adoption validation.
+ * @evidence contracts/common.md#clear-and-simple-design The digest streams the three existing snapshot components and filters only directories the membership policy already classified as irrelevant.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No output-directory name is guessed here and a matching digest does not replace the publisher's stability or adopter's external-input proof.
+ * @evidence contracts/common.md#meaningful-documentation The comment defines the digest's included and excluded inputs and why both publication and adoption still require proof.
+ * @evidence contracts/performance.md#efficient-algorithms Object.keys materializes and sorts F file keys; filtering scans all D directory records before sorting R relevant paths. Key/path comparisons and each streamed config/key/hash/signature frame pay text/UTF-8 encoding and hash work. Temporary key/filter arrays follow F and R, and each update constructs a frame string; no source byte contents or full serialized snapshot is copied. The returned key retains 32 hex characters.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure snapshot digest coordinates no cache or in-flight computation; producer and adopter owners decide when matching state permits sharing a compile.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Ordering arrays and the hash object remain local; the digest transfers to the caller and no historical snapshot, handle or task is retained.
+ * @evidence contracts/portability.md#os-neutral-implementation File keys and directory addresses remain exactly as the native snapshot producer recorded them; sorting and framing add no case folding, separator conversion or physical alias equality. Sharing requires comparable captured address domains from the caller, and this encoding performs no new native identity observation or filesystem read.
+ */
+function sharedCompileState(props) {
+    const hash = crypto.createHash("sha256");
+    hash.update(`${props.tsconfigSignature}\n`);
+    for (const key of Object.keys(props.hashes).sort()) {
+        hash.update(`f\0${key}\0${props.hashes[key]}\n`);
+    }
+    for (const directory of props.directories
+        .filter((directory) => directory.relevant)
+        .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)) {
+        hash.update(`d\0${directory.path}\0${directory.signature}\n`);
+    }
+    return hash.digest("hex").slice(0, 32);
+}
+
+export { sharedCompileState };
+//# sourceMappingURL=sharedCompileState.mjs.map

package/lib/core/transform/session/sharedCompileState.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedCompileState.mjs","sources":["../../../../src/core/transform/session/sharedCompileState.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACG,SAAU,kBAAkB,CAAC,KAIlC,EAAA;IACC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,CAAA,EAAG,KAAK,CAAC,iBAAiB,CAAA,EAAA,CAAI,CAAC;AAC3C,IAAA,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;AAClD,QAAA,IAAI,CAAC,MAAM,CAAC,CAAA,GAAA,EAAM,GAAG,CAAA,EAAA,EAAK,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA,EAAA,CAAI,CAAC;IAClD;AACA,IAAA,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC;SAC3B,MAAM,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,QAAQ;AACxC,SAAA,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,KAChB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAC7D,EAAE;AACH,QAAA,IAAI,CAAC,MAAM,CAAC,CAAA,GAAA,EAAM,SAAS,CAAC,IAAI,CAAA,EAAA,EAAK,SAAS,CAAC,SAAS,CAAA,EAAA,CAAI,CAAC;IAC/D;AACA,IAAA,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;AACxC;;;;"}

package/lib/core/transform/session/unpluginVersion.d.cts

@@ -0,0 +1,25 @@
+/**
+ * The version of this `@ttsc/unplugin`, read once from its own manifest, or
+ * `"unknown"` when the manifest cannot be read.
+ *
+ * A shared compile outlives its publishing process (samchon/ttsc#1483), and
+ * this adapter's code decides adoption proof. Its reported package version
+ * therefore contributes to sharedCompileIdentity. A distinct string changes
+ * that tuple; unknown fallback does not certify identical adapter code. The
+ * configured CommonJS/ES module outputs supply the executing module context,
+ * and the package resolves its manifest by name through its exports.
+ *
+ * The first accepted string or unknown fallback is retained for the process. An
+ * installation changed after that read is not revalidated here; sharing assumes
+ * the executing package and its metadata remain stable for that process.
+ *
+ * @evidence contracts/common.md#principled-implementation The self-resolved package's reported version string enters retained-publication identity; missing/nonstring metadata is explicitly unknown. This is package metadata, not an independent code fingerprint, so stable executing installation and separate adoption proof remain premises.
+ * @evidence contracts/common.md#clear-and-simple-design A single cached manifest lookup provides the version; compiler-version ownership remains in pluginBuildVersions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Package self-resolution uses the installed export contract rather than a guessed checkout path; an unavailable manifest is explicitly represented as unknown.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains retained-publication identity and self-resolution under both emitted module formats.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One accepted version string or fallback is retained until process exit with no string-byte cap or invalidation API. Native/module metadata caches belong to Node's loader; this helper owns no file descriptor or historical version list.
+ * @evidence contracts/performance.md#efficient-algorithms A completed value needs fixed field access. Cold self-resolution/require can process native paths, package export metadata and manifest bytes before one version-field check; module lookup/read/parse cost is not constant merely because one require expression appears.
+ * @evidence contracts/performance.md#reuse-equivalent-work First string or unknown fallback is memoized for every later identity call. This saves repeated lookup under a process-stable executing installation; even a failed first lookup is not retried, and the memo supplies no current package-change detection.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire uses the executing module address and declared package self-export to locate metadata rather than a fixed checkout or separator pattern. The configured CJS/ESM outputs preserve that module context; any unavailable self-resolution yields the documented unknown value, not an invented native package address.
+ */
+export declare function unpluginVersion(): string;

package/lib/core/transform/session/unpluginVersion.d.mts

@@ -0,0 +1,25 @@
+/**
+ * The version of this `@ttsc/unplugin`, read once from its own manifest, or
+ * `"unknown"` when the manifest cannot be read.
+ *
+ * A shared compile outlives its publishing process (samchon/ttsc#1483), and
+ * this adapter's code decides adoption proof. Its reported package version
+ * therefore contributes to sharedCompileIdentity. A distinct string changes
+ * that tuple; unknown fallback does not certify identical adapter code. The
+ * configured CommonJS/ES module outputs supply the executing module context,
+ * and the package resolves its manifest by name through its exports.
+ *
+ * The first accepted string or unknown fallback is retained for the process. An
+ * installation changed after that read is not revalidated here; sharing assumes
+ * the executing package and its metadata remain stable for that process.
+ *
+ * @evidence contracts/common.md#principled-implementation The self-resolved package's reported version string enters retained-publication identity; missing/nonstring metadata is explicitly unknown. This is package metadata, not an independent code fingerprint, so stable executing installation and separate adoption proof remain premises.
+ * @evidence contracts/common.md#clear-and-simple-design A single cached manifest lookup provides the version; compiler-version ownership remains in pluginBuildVersions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Package self-resolution uses the installed export contract rather than a guessed checkout path; an unavailable manifest is explicitly represented as unknown.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains retained-publication identity and self-resolution under both emitted module formats.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One accepted version string or fallback is retained until process exit with no string-byte cap or invalidation API. Native/module metadata caches belong to Node's loader; this helper owns no file descriptor or historical version list.
+ * @evidence contracts/performance.md#efficient-algorithms A completed value needs fixed field access. Cold self-resolution/require can process native paths, package export metadata and manifest bytes before one version-field check; module lookup/read/parse cost is not constant merely because one require expression appears.
+ * @evidence contracts/performance.md#reuse-equivalent-work First string or unknown fallback is memoized for every later identity call. This saves repeated lookup under a process-stable executing installation; even a failed first lookup is not retried, and the memo supplies no current package-change detection.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire uses the executing module address and declared package self-export to locate metadata rather than a fixed checkout or separator pattern. The configured CJS/ESM outputs preserve that module context; any unavailable self-resolution yields the documented unknown value, not an invented native package address.
+ */
+export declare function unpluginVersion(): string;

package/lib/core/transform/session/unpluginVersion.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The version of this `@ttsc/unplugin`, read once from its own manifest, or
+ * `"unknown"` when the manifest cannot be read.
+ *
+ * A shared compile outlives its publishing process (samchon/ttsc#1483), and
+ * this adapter's code decides adoption proof. Its reported package version
+ * therefore contributes to sharedCompileIdentity. A distinct string changes
+ * that tuple; unknown fallback does not certify identical adapter code. The
+ * configured CommonJS/ES module outputs supply the executing module context,
+ * and the package resolves its manifest by name through its exports.
+ *
+ * The first accepted string or unknown fallback is retained for the process. An
+ * installation changed after that read is not revalidated here; sharing assumes
+ * the executing package and its metadata remain stable for that process.
+ *
+ * @evidence contracts/common.md#principled-implementation The self-resolved package's reported version string enters retained-publication identity; missing/nonstring metadata is explicitly unknown. This is package metadata, not an independent code fingerprint, so stable executing installation and separate adoption proof remain premises.
+ * @evidence contracts/common.md#clear-and-simple-design A single cached manifest lookup provides the version; compiler-version ownership remains in pluginBuildVersions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Package self-resolution uses the installed export contract rather than a guessed checkout path; an unavailable manifest is explicitly represented as unknown.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains retained-publication identity and self-resolution under both emitted module formats.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One accepted version string or fallback is retained until process exit with no string-byte cap or invalidation API. Native/module metadata caches belong to Node's loader; this helper owns no file descriptor or historical version list.
+ * @evidence contracts/performance.md#efficient-algorithms A completed value needs fixed field access. Cold self-resolution/require can process native paths, package export metadata and manifest bytes before one version-field check; module lookup/read/parse cost is not constant merely because one require expression appears.
+ * @evidence contracts/performance.md#reuse-equivalent-work First string or unknown fallback is memoized for every later identity call. This saves repeated lookup under a process-stable executing installation; even a failed first lookup is not retried, and the memo supplies no current package-change detection.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire uses the executing module address and declared package self-export to locate metadata rather than a fixed checkout or separator pattern. The configured CJS/ESM outputs preserve that module context; any unavailable self-resolution yields the documented unknown value, not an invented native package address.
+ */
+export declare function unpluginVersion(): string;

package/lib/core/transform/session/unpluginVersion.js

@@ -0,0 +1,47 @@
+'use strict';
+
+var node_module = require('node:module');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+/**
+ * The version of this `@ttsc/unplugin`, read once from its own manifest, or
+ * `"unknown"` when the manifest cannot be read.
+ *
+ * A shared compile outlives its publishing process (samchon/ttsc#1483), and
+ * this adapter's code decides adoption proof. Its reported package version
+ * therefore contributes to sharedCompileIdentity. A distinct string changes
+ * that tuple; unknown fallback does not certify identical adapter code. The
+ * configured CommonJS/ES module outputs supply the executing module context,
+ * and the package resolves its manifest by name through its exports.
+ *
+ * The first accepted string or unknown fallback is retained for the process. An
+ * installation changed after that read is not revalidated here; sharing assumes
+ * the executing package and its metadata remain stable for that process.
+ *
+ * @evidence contracts/common.md#principled-implementation The self-resolved package's reported version string enters retained-publication identity; missing/nonstring metadata is explicitly unknown. This is package metadata, not an independent code fingerprint, so stable executing installation and separate adoption proof remain premises.
+ * @evidence contracts/common.md#clear-and-simple-design A single cached manifest lookup provides the version; compiler-version ownership remains in pluginBuildVersions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Package self-resolution uses the installed export contract rather than a guessed checkout path; an unavailable manifest is explicitly represented as unknown.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains retained-publication identity and self-resolution under both emitted module formats.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One accepted version string or fallback is retained until process exit with no string-byte cap or invalidation API. Native/module metadata caches belong to Node's loader; this helper owns no file descriptor or historical version list.
+ * @evidence contracts/performance.md#efficient-algorithms A completed value needs fixed field access. Cold self-resolution/require can process native paths, package export metadata and manifest bytes before one version-field check; module lookup/read/parse cost is not constant merely because one require expression appears.
+ * @evidence contracts/performance.md#reuse-equivalent-work First string or unknown fallback is memoized for every later identity call. This saves repeated lookup under a process-stable executing installation; even a failed first lookup is not retried, and the memo supplies no current package-change detection.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire uses the executing module address and declared package self-export to locate metadata rather than a fixed checkout or separator pattern. The configured CJS/ESM outputs preserve that module context; any unavailable self-resolution yields the documented unknown value, not an invented native package address.
+ */
+function unpluginVersion() {
+    if (VERSION.value === undefined) {
+        try {
+            const manifest = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('core/transform/session/unpluginVersion.js', document.baseURI).href)))("@ttsc/unplugin/package.json");
+            VERSION.value =
+                typeof manifest.version === "string" ? manifest.version : "unknown";
+        }
+        catch {
+            VERSION.value = "unknown";
+        }
+    }
+    return VERSION.value;
+}
+/** The version, once read. */
+const VERSION = {};
+
+exports.unpluginVersion = unpluginVersion;
+//# sourceMappingURL=unpluginVersion.js.map