@gajae-code/natives 0.18.11 → 0.19.0

package/native/diagnostic-artifact-embedded.json

@@ -0,0 +1,5 @@
+{
+  "schema": "gjc.diagnostic-artifact",
+  "version": "",
+  "artifacts": {}
+}

package/native/diagnostic-artifact.json

@@ -1,12 +1,12 @@
 {
   "schema": "gjc.diagnostic-artifact",
-  "version": "0.18.11",
+  "version": "0.19.0",
   "artifacts": {
-    "pi_natives.darwin-arm64.node": "d9cada560d9cfc412caeb1b880ffe535b35de975f4399524b4ddabcc28f0038a",
-    "pi_natives.darwin-x64-baseline.node": "517f6d12e892f3e98cf8d59715584cf5246047c5355f4533a9be0b3e259e030c",
-    "pi_natives.linux-arm64.node": "aa60a3e8f99c2e2e0c5345cefbf0dfbd3e0cb2bb7e54c7714b69bc8d2602934c",
-    "pi_natives.linux-x64-baseline.node": "701d94a804760eb23c7f0f9c7965aa308885e0794a973e8b9bce187fafd2d4db",
-    "pi_natives.linux-x64-modern.node": "bb4bb9fc065c960f37e32c046b719f78d6b4bd5614e091d1ebc791e8d53a89a8",
-    "pi_natives.win32-x64-baseline.node": "a2275bdb5de62da0fcd31713e49ef70ae6bfe8ee9bf678ea8308867b5c0216c4"
+    "pi_natives.darwin-arm64.node": "bcb20db50a480de66eed5448d63d530ce708ab84d77ab1cb1620132772690af5",
+    "pi_natives.darwin-x64-baseline.node": "3de5a046531495e0a0afdff4d6f0bcd4c8639fcd30fd6cff8ea9ec2efd43b63f",
+    "pi_natives.linux-arm64.node": "3eb72a1956e59f3134d45690c61c79a24e0eddcb9627b238deb32540ec0433ce",
+    "pi_natives.linux-x64-baseline.node": "d6282ea56f7c47bf659fbb1aef7f8df3fb798c9b828abc5dc3b6cf4334f3c651",
+    "pi_natives.linux-x64-modern.node": "8d1fd3d3bc98cc479c75cea158b6059dbed4dbd7a614a6a8c9ad60a12b7a4dae",
+    "pi_natives.win32-x64-baseline.node": "7d9ed748b9b6eb6e14a2c87afccbe1590498512f2830fb1e813aa3529b715bb2"
   }
 }

package/native/diagnostic-loader.js

@@ -19,10 +19,12 @@
  *   - proves the trusted namespace before reading: every component is owned by the
  *     current user or by root, is not a symlink, and grants no group/other write,
  *     so an account that owns none of the path cannot swap the artifact out;
- *   - proves the bytes on a retained descriptor: SHA-256 equal to the digest this
- *     package records in `diagnostic-artifact.json`, which is part of the module
- *     graph so a compiled binary carries it too. An addon's own
- *     `nativeBuildInfo()` is self-reported by code that has already executed, so
+ *   - proves the bytes on a retained descriptor: SHA-256 equal to the shipped
+ *     `diagnostic-artifact.json` digest, a compiled-binary digest captured from the
+ *     verified embed input, or (in a source checkout only) the gitignored local
+ *     manifest when adjacent build metadata explicitly identifies a local build.
+ *     Each manifest belongs to the package and is checked before use. An addon's own
+ *     `nativeBuildInfo()` is self-reported by code that has already been executed, so
  *     it is only a consistency check afterwards, never the trust anchor;
  *   - activates the verified bytes through that same retained descriptor
  *     (`process.dlopen` on `/dev/fd/<fd>`), so a pathname replaced between
@@ -75,6 +77,8 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as nodePath from "node:path";
+import { fileURLToPath } from "node:url";
+import compiledArtifacts from "./diagnostic-artifact-embedded.json" with { type: "json" };
 import trustedArtifacts from "./diagnostic-artifact.json" with { type: "json" };
 import packageManifest from "../package.json" with { type: "json" };
 
@@ -127,17 +131,126 @@ function cachedArtifactPath() {
 }
 
 /**
- * The package-owned expected digest for this artifact, or null when this package
- * ships no trusted record for it.
+ * The package-owned expected digest, or null when this package has no trusted
+ * record. Compiled binaries prefer the digest recorded at their embed boundary;
+ * source checkouts may use the gitignored local manifest for an explicitly local
+ * build. Installed packages use the shipped record.
  *
+ * @param {string} file
  * @returns {string | null}
  */
-function trustedDigest() {
+function trustedDigest(file) {
+	const compiledDigest = compiledArtifactDigest(file);
+	if (compiledDigest !== undefined) return compiledDigest;
+	const localDigest = sourceLocalBuildDigest(file);
+	if (localDigest !== undefined) return localDigest;
 	if (trustedArtifacts?.version !== packageManifest.version) return null;
 	const digest = trustedArtifacts?.artifacts?.[ARTIFACT_BASENAME];
 	return typeof digest === "string" && /^[0-9a-f]{64}$/.test(digest) ? digest : null;
 }
 
+/**
+ * A compiled binary carries the digest of the exact addon verified before embedding.
+ * An empty stub falls back to the shipped record; a populated but stale or malformed
+ * compiled record fails closed.
+ *
+ * @param {string} file
+ * @returns {string | null | undefined} Undefined means no compiled digest is present.
+ */
+function compiledArtifactDigest(file) {
+	if (!runningFromCompiledBinary() || compiledArtifacts?.version === "") return undefined;
+	if (compiledArtifacts?.schema !== "gjc.diagnostic-artifact" || compiledArtifacts?.version !== packageManifest.version) {
+		return null;
+	}
+	const digest = compiledArtifacts?.artifacts?.[nodePath.basename(file)];
+	if (digest === undefined) return undefined;
+	return typeof digest === "string" && /^[0-9a-f]{64}$/.test(digest) ? digest : null;
+}
+
+/**
+ * Read one bounded JSON file only after proving its path and retained descriptor are
+ * in the same trusted namespace used for the native artifact.
+ *
+ * @param {string} file
+ * @returns {Record<string, unknown> | null}
+ */
+function readTrustedLocalJson(file) {
+	let fd = -1;
+	try {
+		if (!trustedNamespace(file)) return null;
+		fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+		const stat = fs.fstatSync(fd);
+		if (!stat.isFile() || stat.size === 0 || stat.size > 1 << 20) return null;
+		if ((stat.mode & 0o022) !== 0) return null;
+		if (stat.uid !== process.geteuid?.() && stat.uid !== 0) return null;
+		if (inspectAclOnDescriptor(fd) !== "absent") return null;
+		const bytes = Buffer.allocUnsafe(stat.size);
+		let offset = 0;
+		while (offset < bytes.length) {
+			const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+			if (read === 0) return null;
+			offset += read;
+		}
+		if (fs.fstatSync(fd).size !== stat.size) return null;
+		const value = JSON.parse(bytes.toString("utf8"));
+		return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+	} catch {
+		return null;
+	} finally {
+		if (fd >= 0) closeDescriptor(fd);
+	}
+}
+
+/**
+ * An unversioned local build is accepted only when the package-owned record proves
+ * these exact bytes for the current package version. This is the migration path for
+ * builds produced before local sidecars carried their version.
+ *
+ * @param {unknown} record
+ * @param {string} version
+ * @param {string} artifact
+ * @param {string} digest
+ * @returns {boolean}
+ */
+function trustedRecordHasDigest(record, version, artifact, digest) {
+	if (typeof record !== "object" || record === null || Array.isArray(record)) return false;
+	const candidate = /** @type {Record<string, unknown>} */ (record);
+	if (candidate.schema !== "gjc.diagnostic-artifact" || candidate.version !== version) return false;
+	const artifacts = candidate.artifacts;
+	if (typeof artifacts !== "object" || artifacts === null || Array.isArray(artifacts)) return false;
+	return /** @type {Record<string, unknown>} */ (artifacts)[artifact] === digest;
+}
+
+/**
+ * A source-mode local build has an explicit profile marker and a gitignored digest
+ * record. Never consult these files for a compiled binary, an installed platform
+ * package, or a release/CI addon.
+ *
+ * @param {string} file
+ * @returns {string | null | undefined} Undefined means this is not a local source build.
+ */
+function sourceLocalBuildDigest(file) {
+	if (runningFromCompiledBinary()) return undefined;
+	const sourceAddon = nodePath.join(nodePath.dirname(fileURLToPath(import.meta.url)), ARTIFACT_BASENAME);
+	if (nodePath.resolve(file) !== sourceAddon) return undefined;
+	const buildMetadata = readTrustedLocalJson(`${sourceAddon}.build.json`);
+	if (buildMetadata?.profile !== "local") return undefined;
+
+	const localManifest = readTrustedLocalJson(
+		nodePath.join(nodePath.dirname(sourceAddon), "diagnostic-artifact.local.json"),
+	);
+	if (localManifest?.schema !== "gjc.diagnostic-artifact") return null;
+	if (localManifest.version !== packageManifest.version) return null;
+	const artifacts = localManifest.artifacts;
+	if (typeof artifacts !== "object" || artifacts === null || Array.isArray(artifacts)) return null;
+	const digest = /** @type {Record<string, unknown>} */ (artifacts)[ARTIFACT_BASENAME];
+	if (typeof digest !== "string" || !/^[0-9a-f]{64}$/.test(digest)) return null;
+	if (buildMetadata.version !== undefined) {
+		return buildMetadata.version === packageManifest.version ? digest : null;
+	}
+	return trustedRecordHasDigest(trustedArtifacts, packageManifest.version, ARTIFACT_BASENAME, digest) ? digest : null;
+}
+
 /**
  * Select the single applicable layout. Exactly one distribution shape applies per
  * install, and a failure of the selected layout is never a reason to try another.
@@ -674,7 +787,7 @@ function consumeHandle(handle) {
  * @returns {{ ok: true, token: string } | { ok: false, reason: "unsupported" }}
  */
 export function verifyDiagnosticArtifact(file) {
-	const expectedDigest = trustedDigest();
+	const expectedDigest = trustedDigest(file);
 	if (expectedDigest === null) return unsupported;
 	let fd = -1;
 	try {

package/native/index.d.ts

@@ -687,7 +687,7 @@ export declare function __piNativesPublishOutcomeV1(): void
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV0_18_11(): void
+export declare function __piNativesV0_19_0(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
@@ -795,6 +795,59 @@ export interface AstFindResult {
  */
 export declare function astGrep(options: AstFindOptions): Promise<AstFindResult>
 
+/**
+ * Match ast-grep patterns against an in-memory source string; returns a
+ * promise resolved on a worker thread.
+ *
+ * This is the file-free counterpart to [`ast_grep`]: callers that already hold
+ * the source (streaming buffers, generated code, editor contents) avoid a
+ * temp-file round trip. `lang` is required since there is no path to infer it
+ * from.
+ */
+export declare function astMatch(options: AstMatchOptions): Promise<AstMatchResult>
+
+/**
+ * Options for `astMatch`: run ast-grep patterns against an in-memory source
+ * string instead of files on disk.
+ */
+export interface AstMatchOptions {
+  /** Source code to match against (parsed in memory, never read from disk). */
+  source: string
+  /**
+   * Language of `source` (required): an alias ("ts", "rust", "python") or a
+   * file extension ("scss"), resolved like a path's extension.
+   */
+  lang: string
+  /** ast-grep patterns to search for (OR across patterns). */
+  patterns: Array<string>
+  /** Rule selector for multi-rule ast-grep configurations. */
+  selector?: string
+  /** Pattern strictness; defaults to smart matching when omitted. */
+  strictness?: AstMatchStrictness
+  /** Maximum matches to return after `offset` (default applies when omitted). */
+  limit?: number
+  /** Number of leading matches to skip before applying `limit`. */
+  offset?: number
+  /** When true, include meta-variable bindings per match. */
+  includeMeta?: boolean
+  /** Optional cancellation handle (library-specific). */
+  signal?: unknown
+  /** Wall-clock timeout for the worker task in milliseconds. */
+  timeoutMs?: number
+}
+
+/** Result of an in-memory `astMatch` run. */
+export interface AstMatchResult {
+  /** Page of matches after sort, offset, and limit. */
+  matches: Array<AstFindMatch>
+  /** Total matches found before paging (can exceed `matches.length`). */
+  totalMatches: number
+  /** True when results were truncated by `limit`. */
+  limitReached: boolean
+  /** Non-fatal parse or pattern-compile errors collected during the run. */
+  parseErrors?: Array<string>
+}
+
 /** ast-grep pattern strictness (controls how patterns match syntax). */
 export declare enum AstMatchStrictness {
   /** Match at the concrete syntax tree level. */
@@ -1189,10 +1242,11 @@ export declare function encodeSixel(bytes: Uint8Array, targetWidthPx: number, ta
 
 /**
  * Remove a directory tree only when a fresh descriptor-relative snapshot
- * exactly equals the persisted snapshot. POSIX first no-replace detaches the
- * verified root to its deterministic `.removing` sibling; the reopened
- * detached descriptor remains authoritative throughout payload scrubbing and
- * replay.
+ * exactly equals the persisted snapshot. POSIX removal no-replace detaches the
+ * verified root to its deterministic `.removing` sibling before scrubbing. On
+ * Windows, callers that need retirement semantics must request a detach-only
+ * pass, then replay exact removal at the returned sibling; ordinary Windows
+ * removal never vacates the caller's path before scrubbing completes.
  */
 export declare function exactRemoveDirectoryTree(path: string, snapshot: NativeDirectoryTreeSnapshot, parentIdentity?: NativeDirectoryParentIdentity | undefined | null, detachOnly?: boolean | undefined | null): NativeExactUnlinkResult
 
@@ -1239,9 +1293,10 @@ export declare function exactReplacePath(sourcePath: string, destinationPath: st
  * single-link ownership; hard-linked or symlinked source/destination are
  * rejected) before anything is mutated. On Windows a pre-mutation
  * `STATUS_SHARING_VIOLATION` on the destination open is reported as a
- * distinct `sharing_violation` code with `windows_error_code` set -- exactly
- * as [`exact_replace_path`] already reports it -- and is always surfaced
- * before any rename, so it is never mistaken for a post-effect failure.
+ * distinct `sharing_violation` code, while `STATUS_ACCESS_DENIED` on a
+ * retained open or rename is reported as `access_denied`. Pre-mutation
+ * failures include the original `windows_error_code`; only known-safe rename
+ * operations retry transient access-denied or sharing-violation statuses.
  */
 export declare function exactReplaceRetained(sourcePath: string, destinationPath: string, backupName: string, expectedSource: NativeExactFileIdentity, expectedDestination: NativeExactFileIdentity): NativeExactUnlinkResult
 
@@ -1294,6 +1349,17 @@ export declare function exactUnlinkDirect(path: string, identity: NativeExactFil
  */
 export declare function exactUnlinkDirectDetached(path: string, identity: NativeExactFileIdentity): boolean
 
+/**
+ * Delete only the empty regular file opened by the caller's retained
+ * descriptor.
+ *
+ * This is used when a newly created staging file cannot be statted through the
+ * host API. Native code derives identity from the open descriptor and verifies
+ * the public entry still names that object before using the platform's exact
+ * unlink protocol.
+ */
+export declare function exactUnlinkOpenFile(path: string, callerFd: number, quarantineName: string): NativeExactUnlinkResult
+
 /**
  * Execute a brush shell command.
  *
@@ -2105,7 +2171,7 @@ export type NativeCanonicalDirectoryIdentity =
 			ok: false;
 			platform?: never;
 			canonicalPath?: never;
-			code: "not_found" | "not_directory" | "not_utf8" | "network_unsupported" | "identity_unavailable" | "io_error";
+			code: "access_denied" | "not_found" | "not_directory" | "not_utf8" | "network_unsupported" | "identity_unavailable" | "io_error";
 	  }
 
 /** Bytes copied out of one read-only broker publication observation. */
@@ -2321,6 +2387,7 @@ export type NativeOwnerOnlySecurityResult =
 	| {
 			ok: false;
 			code:
+				| "access_denied"
 				| "not_found"
 				| "not_directory"
 				| "network_unsupported"
@@ -2578,16 +2645,22 @@ export interface PtyStartOptions {
 export declare function ptyTimeoutCount(): bigint
 
 /**
- * Rasterize SVG/SVGZ bytes into a bounded PNG without resolving local files.
+ * Rasterize bounded SVG/SVGZ bytes into a PNG without resolving local files.
+ *
+ * DTD/entity declarations and SVG image elements are rejected rather than
+ * allowing unbounded expansion or silently returning an incomplete preview.
  *
  * Conversion runs on the native blocking pool so parsing and rendering do not
  * stall the JavaScript event loop.
  *
+ * When both cell dimensions are provided, the PNG is padded on a transparent
+ * canvas to whole terminal cells without embedding or decoding another image.
+ *
  * # Errors
- * Returns an error for invalid SVG data, zero/oversized limits, allocation
- * failure, or PNG encoding failure.
+ * Returns an error for invalid SVG data, mismatched/zero cell dimensions,
+ * zero/oversized limits, allocation failure, or PNG encoding failure.
  */
-export declare function rasterizeSvg(input: Uint8Array, maxWidthPx: number, maxHeightPx: number): Promise<Uint8Array>
+export declare function rasterizeSvg(input: Uint8Array, maxWidthPx: number, maxHeightPx: number, cellWidthPx?: number | undefined | null, cellHeightPx?: number | undefined | null): Promise<Uint8Array>
 
 /**
  * Read an image from the system clipboard.

package/native/index.js

@@ -35,12 +35,13 @@ export const TtyWriter = nativeBindings.TtyWriter;
 // functions
 export const __gjcInstallTokioRuntime = nativeBindings.__gjcInstallTokioRuntime;
 export const __piNativesPublishOutcomeV1 = nativeBindings.__piNativesPublishOutcomeV1;
-export const __piNativesV0_18_11 = nativeBindings.__piNativesV0_18_11;
+export const __piNativesV0_19_0 = nativeBindings.__piNativesV0_19_0;
 export const applyBashFixups = nativeBindings.applyBashFixups;
 export const applyOwnerOnlyFdSecurity = nativeBindings.applyOwnerOnlyFdSecurity;
 export const applyOwnerOnlyPathSecurity = nativeBindings.applyOwnerOnlyPathSecurity;
 export const astEdit = nativeBindings.astEdit;
 export const astGrep = nativeBindings.astGrep;
+export const astMatch = nativeBindings.astMatch;
 export const canonicalExistingDirectoryIdentity = nativeBindings.canonicalExistingDirectoryIdentity;
 export const computerScreenshot = nativeBindings.computerScreenshot;
 export const copyToClipboard = nativeBindings.copyToClipboard;
@@ -64,6 +65,7 @@ export const exactSwapManagedLink = nativeBindings.exactSwapManagedLink;
 export const exactUnlink = nativeBindings.exactUnlink;
 export const exactUnlinkDirect = nativeBindings.exactUnlinkDirect;
 export const exactUnlinkDirectDetached = nativeBindings.exactUnlinkDirectDetached;
+export const exactUnlinkOpenFile = nativeBindings.exactUnlinkOpenFile;
 export const executeShell = nativeBindings.executeShell;
 export const extractSegments = nativeBindings.extractSegments;
 export const fuzzyFind = nativeBindings.fuzzyFind;

package/native/loader-state.d.ts

@@ -88,7 +88,9 @@ export function loadFromCandidates<T>(input: LoadFromCandidatesInput<T>): LoadFr
 export interface CachedEmbeddedExtractionIsFreshInput {
 	targetPath: string;
 	embeddedPath: string;
+	expectedDigest: string | null | undefined;
 	sizeOf: (path: string) => number | null;
+	digestOf: (path: string) => string | null;
 }
 
 export function cachedEmbeddedExtractionIsFresh(input: CachedEmbeddedExtractionIsFreshInput): boolean;
@@ -136,6 +138,7 @@ export interface LoadNativeOptions {
 	acquireStagedCandidateLease?: (candidate: string) => () => void;
 	requireCandidate?: (candidate: string) => Record<string, unknown>;
 	validateCandidate?: (bindings: Record<string, unknown>, candidate: string) => void;
+	loadNativeLibrary?: (runtime: string) => bigint | number | null;
 }
 
 export function loadNative(options?: LoadNativeOptions): Record<string, unknown>;

package/native/loader-state.js

@@ -5,6 +5,7 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as path from "node:path";
+import embeddedDiagnosticArtifacts from "./diagnostic-artifact-embedded.json" with { type: "json" };
 import packageJson from "../package.json" with { type: "json" };
 import { embeddedAddon } from "./embedded-addon.js";
 
@@ -32,13 +33,14 @@ import { embeddedAddon } from "./embedded-addon.js";
  * post-build `--reset` stub) is the authoritative compiled-mode signal.
  */
 
-const SUPPORTED_PLATFORMS = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64"];
+const SUPPORTED_PLATFORMS = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64", "win32-arm64"];
 const OPTIONAL_PACKAGE_BY_PLATFORM_TAG = {
 	"darwin-arm64": "@gajae-code/natives-darwin-arm64",
 	"darwin-x64": "@gajae-code/natives-darwin-x64",
 	"linux-arm64": "@gajae-code/natives-linux-arm64",
 	"linux-x64": "@gajae-code/natives-linux-x64",
 	"win32-x64": "@gajae-code/natives-win32-x64",
+	"win32-arm64": "@gajae-code/natives-win32-arm64",
 };
 const WINDOWS_GENERIC_READ = 0x80000000;
 const WINDOWS_FILE_SHARE_READ = 0x00000001;
@@ -138,6 +140,32 @@ function validateStagedCandidate(ctx, candidate) {
 	}
 }
 
+function preloadSiblingNativeRuntime(ctx, candidate, loadLibrary) {
+	if (process.platform !== "win32") return;
+	// Staging copies only the .node into the versioned cache and drops the
+	// package directory from the candidate list. The DLL stays beside the
+	// recorded source addon, not beside that cache copy or bun.exe.
+	const sourcePath = ctx.stagedSourceSnapshots?.get(candidate)?.sourcePath;
+	const runtimes = [
+		typeof sourcePath === "string" ? path.join(path.dirname(sourcePath), "libunwind.dll") : null,
+		path.join(path.dirname(candidate), "libunwind.dll"),
+		path.join(path.dirname(process.execPath), "libunwind.dll"),
+	];
+	const seen = new Set();
+	for (const runtime of runtimes) {
+		if (!runtime || seen.has(runtime) || !fs.existsSync(runtime)) continue;
+		seen.add(runtime);
+		const handle = loadLibrary(runtime);
+		if (handle !== 0 && handle !== 0n && handle != null) return;
+	}
+}
+
+function loadSiblingNativeLibrary(runtime) {
+	const widePath = new Uint16Array(runtime.length + 1);
+	for (let index = 0; index < runtime.length; index++) widePath[index] = runtime.charCodeAt(index);
+	return windowsKernel32Bindings().symbols.LoadLibraryW(ptr(widePath));
+}
+
 function windowsKernel32Bindings() {
 	if (windowsKernel32) return windowsKernel32;
 	windowsKernel32 = dlopen("kernel32.dll", {
@@ -147,6 +175,7 @@ function windowsKernel32Bindings() {
 		},
 		CloseHandle: { args: ["i64"], returns: "u32" },
 		GetLastError: { args: [], returns: "u32" },
+		LoadLibraryW: { args: ["ptr"], returns: "ptr" },
 	});
 	return windowsKernel32;
 }
@@ -368,18 +397,60 @@ export function loadFromCandidates({ candidates, requireCandidate, validateCandi
 /**
  * Decide whether a previously extracted embedded addon may be reused. A cached
  * extraction from an earlier build of the same version carries the same version
- * sentinel yet can expose a different native surface, so it is fresh only when
- * its byte size matches the embedded payload. `sizeOf` returns the byte size of
- * a path, or `null` when it cannot be inspected.
- * @param {{ targetPath: string; embeddedPath: string; sizeOf: (path: string) => number | null }} input
+ * sentinel and may have the same byte size, so freshness also requires its digest
+ * to match the package-owned embedded build record. `sizeOf` returns a path's
+ * byte size; `digestOf` returns a SHA-256 hex digest. Both return `null` when the
+ * path cannot be inspected.
+ * @param {{ targetPath: string; embeddedPath: string; expectedDigest: string | null | undefined; sizeOf: (path: string) => number | null; digestOf: (path: string) => string | null }} input
  * @returns {boolean}
  */
-export function cachedEmbeddedExtractionIsFresh({ targetPath, embeddedPath, sizeOf }) {
+export function cachedEmbeddedExtractionIsFresh({ targetPath, embeddedPath, expectedDigest, sizeOf, digestOf }) {
+	if (typeof expectedDigest !== "string" || !/^[0-9a-f]{64}$/.test(expectedDigest)) return false;
 	const cachedSize = sizeOf(targetPath);
 	if (cachedSize === null) return false;
 	const embeddedSize = sizeOf(embeddedPath);
 	if (embeddedSize === null) return false;
-	return cachedSize === embeddedSize;
+	if (cachedSize !== embeddedSize) return false;
+	return digestOf(targetPath) === expectedDigest;
+}
+
+function sha256File(file) {
+	let fd = -1;
+	try {
+		const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+		fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+		const before = fs.fstatSync(fd);
+		if (!before.isFile()) return null;
+		const hash = createHash("sha256");
+		const buffer = Buffer.allocUnsafe(1 << 20);
+		let offset = 0;
+		while (offset < before.size) {
+			const read = fs.readSync(fd, buffer, 0, Math.min(buffer.length, before.size - offset), offset);
+			if (read === 0) return null;
+			hash.update(buffer.subarray(0, read));
+			offset += read;
+		}
+		const after = fs.fstatSync(fd);
+		if (
+			after.dev !== before.dev ||
+			after.ino !== before.ino ||
+			after.size !== before.size ||
+			after.mtimeMs !== before.mtimeMs
+		) {
+			return null;
+		}
+		return hash.digest("hex");
+	} catch {
+		return null;
+	} finally {
+		if (fd >= 0) {
+			try {
+				fs.closeSync(fd);
+			} catch {
+				// A failed close cannot make an unverified digest admissible.
+			}
+		}
+	}
 }
 
 // =========================================================================
@@ -549,12 +620,16 @@ function maybeExtractEmbeddedAddons(ctx, errors) {
 	const extracted = [];
 	for (const embeddedFile of embeddedAddonCandidates(ctx.selectedVariant)) {
 		const targetPath = path.join(ctx.versionedDir, embeddedFile.filename);
+		const expectedDigest =
+			embeddedDiagnosticArtifacts?.schema === "gjc.diagnostic-artifact" &&
+			embeddedDiagnosticArtifacts?.version === embeddedAddon.version
+				? embeddedDiagnosticArtifacts?.artifacts?.[embeddedFile.filename]
+				: undefined;
 		if (fs.existsSync(targetPath)) {
 			// Guard against intra-version drift: a cached extraction written by an earlier
-			// build of the same version carries the same version sentinel but can expose a
-			// different native surface (e.g. a symbol added mid-cycle). The embedded addon
-			// is the source of truth, so reuse the cached file only when it matches the
-			// embedded payload size and re-extract otherwise.
+			// build of the same version carries the same version sentinel and may even have
+			// the same byte size. The embedded digest is the source of truth, so reuse the
+			// cached file only when its bytes match that exact build.
 			const sizeOf = candidate => {
 				try {
 					return fs.statSync(candidate).size;
@@ -562,7 +637,15 @@ function maybeExtractEmbeddedAddons(ctx, errors) {
 					return null;
 				}
 			};
-			if (cachedEmbeddedExtractionIsFresh({ targetPath, embeddedPath: embeddedFile.filePath, sizeOf })) {
+			if (
+				cachedEmbeddedExtractionIsFresh({
+					targetPath,
+					embeddedPath: embeddedFile.filePath,
+					expectedDigest,
+					sizeOf,
+					digestOf: sha256File,
+				})
+			) {
 				extracted.push(targetPath);
 				continue;
 			}
@@ -910,6 +993,7 @@ export function loadNative(options = {}) {
 			}
 			try {
 				validateStagedCandidate(ctx, candidate);
+				preloadSiblingNativeRuntime(ctx, candidate, options.loadNativeLibrary ?? loadSiblingNativeLibrary);
 				const bindings = options.requireCandidate ? options.requireCandidate(candidate) : require_(candidate);
 				if (typeof bindings.__gjcInstallTokioRuntime === "function") {
 					bindings.__gjcInstallTokioRuntime();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gajae-code/natives",
-	"version": "0.18.11",
+	"version": "0.19.0",
 	"description": "Native Rust bindings for grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://gajae-code.com",
@@ -31,7 +31,7 @@
 	"scripts": {
 		"build": "bun scripts/build-native.ts",
 		"check": "biome check . && bun run check:types",
-		"check:types": "tsc -p tsconfig.json --noEmit",
+		"check:types": "bun ../coding-agent/scripts/generate-docs-index.ts && tsc -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"test": "bun test",
 		"fix": "biome check --write --unsafe .",
@@ -61,15 +61,16 @@
 		"native/diagnostic-loader.d.ts",
 		"native/diagnostic-loader.js",
 		"native/diagnostic-artifact.json",
+		"native/diagnostic-artifact-embedded.json",
 		"native/embedded-addon.js",
 		"README.md"
 	],
 	"optionalDependencies": {
-		"@gajae-code/natives-darwin-arm64": "0.18.11",
-		"@gajae-code/natives-darwin-x64": "0.18.11",
-		"@gajae-code/natives-linux-arm64": "0.18.11",
-		"@gajae-code/natives-linux-x64": "0.18.11",
-		"@gajae-code/natives-win32-x64": "0.18.11"
+		"@gajae-code/natives-darwin-arm64": "0.19.0",
+		"@gajae-code/natives-darwin-x64": "0.19.0",
+		"@gajae-code/natives-linux-arm64": "0.19.0",
+		"@gajae-code/natives-linux-x64": "0.19.0",
+		"@gajae-code/natives-win32-x64": "0.19.0"
 	},
 	"exports": {
 		".": {