@scriptc/compiler 0.0.34 → 0.0.35

package/dist/backend/cc.d.ts

@@ -4,6 +4,11 @@ export interface ToolchainEnvironmentCachePolicy {
 }
 export declare function toolchainEnvironmentCachePolicy(env?: NodeJS.ProcessEnv): ToolchainEnvironmentCachePolicy;
 export declare function toolchainEnvironmentFingerprint(env?: NodeJS.ProcessEnv): string;
+/** Inputs that can change which native tool/runtime implementation an
+ * executable build selects before compileC has a chance to rediscover it.
+ * The early whole-program cache keys this exact posture before restoring a
+ * final binary; compileC retains its deeper inode/content validation. */
+export declare function executableNativeEnvironmentFingerprint(env?: NodeJS.ProcessEnv): Promise<string>;
 export interface CcOptions {
     /** Path of the generated (or hand-written) program TU: a .c file, or the
      * LLVM backend's .ll — clang compiles IR text natively on the same
@@ -18,6 +23,19 @@ export interface CcOptions {
      * top-level bytes alone can safely represent. scriptc's frontend supplies
      * this for its generated C/LLVM IR; `--from-c` deliberately does not. */
     cacheIdentity?: string;
+    /** Native optimization posture. Release preserves the historical -O2
+     * executable lane; dev selects -O0 and may compile a caller-provided LLVM
+     * shard set into independently cached objects before the final link. */
+    optimization?: "release" | "dev";
+    /** Optional equivalent LLVM modules for dev compilation. Unsupported
+     * targets or merge failures fall back to the canonical cPath TU. */
+    programShards?: readonly {
+        name: string;
+        source: string;
+    }[];
+    /** Canonical externally visible definitions retained while shard merging
+     * demotes generated cross-shard linkage back to local symbols. */
+    programPublicSymbols?: readonly string[];
     /** Build with ASan + the runtime RC audit (test/debug lane). */
     sanitize?: boolean;
     /** Additional native archives/objects, appended after the generated
@@ -196,6 +214,17 @@ export interface CcOptions {
      * The unit also compiles whenever `tls` does — scr_tls.c consults its
      * default-set override and shared Windows-certificate enumerator. */
     tlsCa?: boolean;
+    /** Internal compiler hook: called only after a strict native artifact hit
+     * or a successful stable build has installed `outPath`. The executable
+     * frontend cache uses it to publish its stamp after native dependencies
+     * have validated; arbitrary compileC callers leave it unset. */
+    onArtifactReady?: (artifact: ValidatedNativeArtifact) => Promise<void>;
+}
+/** Native dependency proof attached to an executable frontend-cache entry.
+ * compileC produces this only after its strict local/CAS validation succeeds;
+ * the early reader replays it before restoring the final executable. */
+export interface ValidatedNativeArtifact {
+    dependencies: NativeArtifactDependency[];
 }
 /** Structured compiler-driver failure. Most callers still let this surface
  * as an internal build error; the TypeScript compiler pipeline recognizes it
@@ -264,10 +293,11 @@ export declare function cacheTargetIdentity(driver: Pick<CcDriver, "target">, ho
  * be used by both arm64 Node and Rosetta/x64 Node on macOS. */
 export declare function vendorCacheTargetFlavor(driver: Pick<CcDriver, "target">, hostPlatform?: NodeJS.Platform, hostArch?: string): string;
 /** Vendor prerequisites live outside the content-addressed build root, so
- * their directory name must carry the same environment and resolved compiler
- * identity as the artifacts that consume them. The short digest keeps the
- * package-local path readable while preventing build-order contamination. */
-export declare function vendorCacheBuildIdentity(environmentFingerprint: string, compilerIdentity: string): string;
+ * their directory name must carry the environment, resolved compiler, owned
+ * source bytes, and build-recipe identity of the artifacts that consume them.
+ * The short digest keeps the cache path readable while preventing build-order
+ * and cross-installation contamination. */
+export declare function vendorCacheBuildIdentity(environmentFingerprint: string, compilerIdentity: string, nativeSourceIdentity: string): string;
 export interface LibArchiveOptions {
     /** The program TU (.c or .ll — clang compiles either with -c). */
     cPath: string;
@@ -275,6 +305,17 @@ export interface LibArchiveOptions {
      * spelling. Library assembly uses this for the identity-free projection of
      * a complete caller-visible TU; its bytes drive every native cache key. */
     programSource?: string;
+    /** Optional equivalent LLVM modules for native compilation. The public
+     * `programSource` remains the canonical TU/cache identity; these stable
+     * shards compile independently and are relocatably merged into one program
+     * object before archive assembly. */
+    programShards?: readonly {
+        name: string;
+        source: string;
+    }[];
+    /** Canonical externally visible definitions retained while the shard merge
+     * demotes generated cross-shard linkage back to local symbols. */
+    programPublicSymbols?: readonly string[];
     /** Tiny generated C source carrying volatile library identity getters.
      * Its bytes join the complete archive key, but the source itself exists
      * only in the invocation-private build directory and the large program-
@@ -347,24 +388,55 @@ export declare function ccVersionOnce(argv: string[], environmentFingerprint?: s
 export declare function implicitDependencyProbeIncludes(rtDir: string): Promise<string[]>;
 export declare function parseLinkTraceFiles(output: string, cwd: string, excludedRoot: string, driverDryRun?: boolean): Promise<string[]>;
 export declare function runtimeFingerprint(rtDir: string): Promise<string>;
+export interface NativeArtifactDependency {
+    path: string;
+    kind: "file" | "directory" | "symlink";
+    dev: number;
+    ino: number;
+    size: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    /** Symlinks are identity-bearing paths whose target bytes also matter. */
+    targetPath?: string;
+    targetKind?: "file" | "directory";
+    targetDev?: number;
+    targetIno?: number;
+    targetSize?: number;
+    targetMtimeMs?: number;
+    targetCtimeMs?: number;
+    /** A directory's recursive namespace. This detects a new nested candidate
+     * that can begin shadowing an existing system/header dependency. */
+    treeDigest?: string;
+    treeExclusions?: string[];
+}
+export declare function nativeArtifactDependenciesStillMatch(dependencies: readonly NativeArtifactDependency[]): Promise<boolean>;
 /** Give one active link/archive operation private names for its cached
  * runtime objects. A hard link keeps the inode alive if another process's LRU
  * sweep unlinks the cache entry; filesystems that cannot hard-link across the
  * cache/tmp boundary fall back to a copy. If eviction wins before staging,
  * the caller catches the read failure and performs a fully fresh compile. */
 export declare function stageRuntimeObjects(objects: ReadonlyMap<string, string>, stageDir: string): Promise<Map<string, string>>;
-/** Compiles one C program together with the runtime sources.
- * With caching disabled, the runtime (a dozen small files) is recompiled on
- * every build in one historical clang invocation — no cached-archive
- * staleness bugs. --dynamic additionally compiles
- * scr_island.c under SCR_DYNAMIC and links the cached engine archive (built
- * lazily, see above); regex-using programs additionally compile scr_regex.c
- * and link libregexp (the cached objects, or the archive's own copy under
- * --dynamic). Without either, the command line is exactly the historical
- * one — regex-free static builds must stay byte-identical.
- *
- * With a caller-supplied dependency identity and an enabled cache root,
- * unchanged programs skip payload code generation/linking via the binary
- * cache after lightweight metadata probes, and misses link the program's own
- * TU against cached per-flavor runtime objects. */
 export declare function compileC(opts: CcOptions): Promise<void>;
+export type NativeCacheWarmProfile = "runtime" | "tls" | "dynamic";
+export interface WarmNativeCachesOptions {
+    /** Native object posture to seed. Defaults to the shipped release/-O2 lane. */
+    optimization?: "release" | "dev";
+    /** Seed ASan + RC-audit objects instead of the ordinary lane. */
+    sanitize?: boolean;
+    /** Feature families to seed. Defaults to every expensive native family. */
+    profiles?: readonly NativeCacheWarmProfile[];
+}
+export interface WarmNativeCachesResult {
+    cacheRoot: string;
+    profiles: {
+        profile: NativeCacheWarmProfile;
+        elapsedMs: number;
+    }[];
+}
+export declare function supportedNativeCacheWarmProfiles(driver: CcDriver): readonly NativeCacheWarmProfile[];
+/** Populate expensive native prerequisites against the current compiler,
+ * target, SDK, and environment. The resulting entries use the exact same
+ * identities and validators as ordinary builds; this merely pays their cost
+ * before a developer's first program asks for them. Synthetic link products
+ * are discarded and never enter the complete-executable cache. */
+export declare function warmNativeCaches(options?: WarmNativeCachesOptions): Promise<WarmNativeCachesResult>;