@oh-my-pi/pi-natives 18.3.1 → 18.3.3

package/native/desktop-adapter.d.ts

@@ -2,7 +2,7 @@ interface AdaptedDesktopCapabilities {
 	readonly [key: string]: unknown;
 	readonly ax: boolean;
 	readonly backgroundWindowInput: boolean;
-	readonly deliveryModes: readonly string[];
+	readonly takeover: boolean;
 	readonly axPermission: string;
 }
 
@@ -14,10 +14,10 @@ interface AdaptedDesktopSession {
 		target: string,
 		x: number,
 		y: number,
-		options?: { button?: string; count?: number; modifiers?: string[]; deliveryMode?: string },
+		options?: { button?: string; count?: number; modifiers?: string[]; takeover?: boolean },
 	): Promise<void>;
-	typeText(target: string, text: string, options?: { deliveryMode?: string }): Promise<void>;
-	keyChord(target: string, keys: string[], options?: { deliveryMode?: string }): Promise<void>;
+	typeText(target: string, text: string, options?: { takeover?: boolean }): Promise<void>;
+	keyChord(target: string, keys: string[], options?: { takeover?: boolean }): Promise<void>;
 	close(): Promise<void>;
 }
 

package/native/desktop-adapter.js

@@ -33,7 +33,7 @@ function normalizeCapabilities(capabilities) {
 		...capabilities,
 		ax: false,
 		backgroundWindowInput: false,
-		deliveryModes: ["foreground"],
+		takeover: true,
 		axPermission: "unavailable",
 	};
 }
@@ -211,7 +211,7 @@ export function adaptDesktopSession(NativeDesktopSession) {
 		}
 
 		#ensureForeground(target, options) {
-			if (options?.deliveryMode !== "foreground" && (target !== "desktop" || options?.deliveryMode !== undefined)) {
+			if (target !== "desktop" && options?.takeover !== true) {
 				throw desktopError(
 					"BackgroundUnavailable",
 					"the installed native addon supports foreground input only",

package/native/index.d.ts

@@ -366,6 +366,53 @@ export declare class Shell {
   liveBackgroundJobCount(): Promise<number>
 }
 
+/** One word-completion engine running on its own thread. */
+export declare class TextPredictor {
+  /**
+   * Spawn the engine thread and start opening the engine; load errors
+   * surface from [`TextPredictor::ready`] and every later call.
+   *
+   * # Errors
+   * Returns an error when the engine thread cannot be spawned.
+   */
+  constructor(options: TextPredictorOptions)
+  /**
+   * Resolve once the engine has loaded.
+   *
+   * # Errors
+   * Rejects with the engine's load error (missing weights, corrupt state).
+   */
+  ready(): Promise<void>
+  /**
+   * Ghost text for `prefix` typed after `before`, or `null`.
+   *
+   * # Errors
+   * Rejects when the engine failed to load.
+   */
+  complete(before: string, prefix: string): Promise<PredictedWord | null>
+  /**
+   * Learn from submitted prompts, in submission order.
+   *
+   * # Errors
+   * Rejects when the engine failed to load.
+   */
+  observe(prompts: Array<string>): Promise<void>
+  /**
+   * Learn from a suggestion the user accepted (`true`) or typed past.
+   *
+   * # Errors
+   * Rejects when the engine failed to load.
+   */
+  feedback(before: string, prefix: string, suggestion: string, accepted: boolean): Promise<void>
+  /**
+   * Flush learned state to the state directory.
+   *
+   * # Errors
+   * Rejects when the engine failed to load or the state cannot be written.
+   */
+  persist(): Promise<void>
+}
+
 /**
  * Dedicated writer thread for one terminal fd.
  *
@@ -633,24 +680,13 @@ export declare class VcsRepo {
 export declare function __ompInstallTokioRuntime(): void
 
 /**
- * Version sentinel — exists solely so the JS loader can prove at load time
- * that the `.node` file on disk is from the same package release as the
- * `index.js` ESM wrapper invoking it.
- *
- * The `js_name` is bumped by `scripts/release.ts` to match the new
- * `Cargo.toml` / `package.json` version on every release. The JS loader
- * computes the expected name from `package.json#version` and refuses to use
- * a `.node` that doesn't expose it, turning the silent
- * `<sym> is not a function` crash from a locked-file update (the canonical
- * Windows `bun install -g` failure mode) into a clear load-time error.
+ * Release version stamped into this `.node` after linking.
  *
- * Bump policy: `__piNativesV{major}_{minor}_{patch}` — non-alphanumerics in
- * the version string are mapped to `_` to keep it a valid JS identifier.
- * MUST stay in sync with `VERSION_SENTINEL_EXPORT` in
- * `packages/natives/native/index.js` (which derives the name from
- * `package.json#version`).
+ * `None` for an unstamped build. The JS loader compares it against
+ * `package.json#version` so a `.node` from another release fails at load time
+ * with an actionable error instead of a later `<sym> is not a function` crash.
  */
-export declare function __piNativesV18_3_1(): void
+export declare function __piNativesBuildVersion(): string | null
 
 /**
  * Reports whether the on-device model can generate, as an `availability`
@@ -1066,7 +1102,11 @@ export interface DesktopCapabilities {
   input: boolean
   ax: boolean
   backgroundWindowInput: boolean
-  deliveryModes: Array<string>
+  /**
+   * Whether window input accepts `takeover: true` (briefly activate the
+   * target and post real input).
+   */
+  takeover: boolean
   capturePermission: string
   inputPermission: string
   axPermission: string
@@ -1726,6 +1766,11 @@ export interface GrepOptions {
   path: string
   /** Glob filter for filenames (e.g., "*.ts"). */
   glob?: string
+  /**
+   * Match simple glob patterns at any depth (default: true; `*.ts` ->
+   * `**\/*.ts`). Set false when `glob` is already relative to `path`.
+   */
+  recursive?: boolean
   /** Filter by file type (e.g., "js", "py", "rust"). */
   type?: string
   /** Case-insensitive search. */
@@ -2107,14 +2152,6 @@ export declare function macOSAutocorrectWord(text: string, start: number, length
  */
 export declare function macOSCheckSpelling(text: string): Promise<Array<SpellingRange>>
 
-/**
- * Return macOS dictionary completions for one partial-word range.
- *
- * Returns an empty list when Apple's spelling service is unavailable.
- * On macOS, the lookup runs on the dedicated spelling thread.
- */
-export declare function macOSCompleteWord(text: string, start: number, length: number): Promise<Array<string>>
-
 /** Whether the host can use Apple's native spelling service. */
 export declare function macOSSpellCheckerAvailable(): boolean
 
@@ -2388,7 +2425,11 @@ export interface PointerOptions {
   button?: string
   count?: number
   modifiers?: Array<string>
-  deliveryMode?: string
+  /**
+   * Briefly activate the target window and post real input instead of the
+   * default background delivery.
+   */
+  takeover?: boolean
 }
 
 /**
@@ -2415,6 +2456,14 @@ export interface PowerAssertionOptions {
   display?: boolean
 }
 
+/** Ghost text for the word being typed. */
+export interface PredictedWord {
+  /** Characters to paint after the typed prefix. */
+  suffix: string
+  /** Engine-calibrated probability that `suffix` is exactly right. */
+  confidence: number
+}
+
 /** Current state of a process reference. */
 export declare enum ProcessStatus {
   /** The referenced process is still running. */
@@ -3137,6 +3186,18 @@ export interface SummarySegment {
  */
 export declare function supportsLanguage(lang: string): boolean
 
+/** Options for [`TextPredictor::new`]. */
+export interface TextPredictorOptions {
+  /** Engine: `ngram`, `smollm`, or `apple`. */
+  method: string
+  /** Private directory for persisted learned state. */
+  stateDir: string
+  /** Directory holding downloaded model weights (`smollm` only). */
+  modelDir?: string
+  /** Show threshold override; omit for the engine's tuned default. */
+  showThreshold?: number
+}
+
 /**
  * Truncate text to a visible width, preserving ANSI codes.
  *

package/native/index.js

@@ -38,6 +38,7 @@ export const PowerAssertion = nativeBindings.PowerAssertion;
 export const Process = nativeBindings.Process;
 export const PtySession = nativeBindings.PtySession;
 export const Shell = nativeBindings.Shell;
+export const TextPredictor = nativeBindings.TextPredictor;
 export const TtyWriter = nativeBindings.TtyWriter;
 export const VcsGitRepo = nativeBindings.VcsGitRepo;
 export const VcsJjWorkspace = nativeBindings.VcsJjWorkspace;
@@ -45,7 +46,7 @@ export const VcsRepo = nativeBindings.VcsRepo;
 
 // functions
 export const __ompInstallTokioRuntime = nativeBindings.__ompInstallTokioRuntime ?? missingNativeExport("__ompInstallTokioRuntime");
-export const __piNativesV18_3_1 = nativeBindings.__piNativesV18_3_1;
+export const __piNativesBuildVersion = nativeBindings.__piNativesBuildVersion;
 export const appleFmAvailability = nativeBindings.appleFmAvailability ?? missingNativeExport("appleFmAvailability");
 export const appleFmCancel = nativeBindings.appleFmCancel ?? missingNativeExport("appleFmCancel");
 export const appleFmGenerate = nativeBindings.appleFmGenerate ?? missingNativeExport("appleFmGenerate");
@@ -98,7 +99,6 @@ export const isoStop = nativeBindings.isoStop ?? missingNativeExport("isoStop");
 export const listWorkspace = nativeBindings.listWorkspace ?? missingNativeExport("listWorkspace");
 export const macOSAutocorrectWord = nativeBindings.macOSAutocorrectWord ?? missingNativeExport("macOSAutocorrectWord");
 export const macOSCheckSpelling = nativeBindings.macOSCheckSpelling ?? missingNativeExport("macOSCheckSpelling");
-export const macOSCompleteWord = nativeBindings.macOSCompleteWord ?? missingNativeExport("macOSCompleteWord");
 export const macOSSpellCheckerAvailable = nativeBindings.macOSSpellCheckerAvailable ?? missingNativeExport("macOSSpellCheckerAvailable");
 export const macOSSpellingGuesses = nativeBindings.macOSSpellingGuesses ?? missingNativeExport("macOSSpellingGuesses");
 export const matchesKey = nativeBindings.matchesKey ?? missingNativeExport("matchesKey");

package/native/loader-state.d.ts

@@ -75,7 +75,6 @@ export interface NativeLoaderContext {
 	addonFilenames: string[];
 	addonLabel: string;
 	candidates: string[];
-	versionSentinelExport: string;
 	isWorkspaceLoad: boolean;
 	nativesDir: string;
 }
@@ -118,7 +117,6 @@ export function selectCpuVariant(input: SelectCpuVariantInput): SelectCpuVariant
 export interface ValidateLoadedBindingsContext {
 	isWorkspaceLoad: boolean;
 	packageVersion: string;
-	versionSentinelExport: string;
 }
 
 export function validateLoadedBindings(
@@ -131,10 +129,8 @@ export function validateLoadedBindings(
 export interface NativeAddonStatus {
 	/** Absolute path of the loaded `.node`. */
 	path: string;
-	/** Sentinel the loaded addon carries, or `null` before sentinels existed. */
-	sentinel: string | null;
-	/** Sentinel this loader's package version expects. */
-	expectedSentinel: string;
+	/** Release the loaded addon reports (post-link stamp or legacy sentinel), or `null` when unidentified. */
+	version: string | null;
 	/** `package.json#version` of the loader that loaded it. */
 	packageVersion: string;
 	/** True when the addon carries a different release than this package. */

package/native/loader-state.js

@@ -6,7 +6,7 @@ import * as path from "node:path";
 import * as zlib from "node:zlib";
 import packageJson from "../package.json" with { type: "json" };
 import { embeddedAddon } from "./embedded-addon.js";
-import { containsVersionSentinel, versionSentinelFor } from "./version-sentinel.js";
+import { bindingsHaveReleaseIdentity, bindingsReleaseVersion, containsVersionStamp } from "./version-sentinel.js";
 
 /**
  * Native addon loader for `@oh-my-pi/pi-natives`.
@@ -15,7 +15,7 @@ import { containsVersionSentinel, versionSentinelFor } from "./version-sentinel.
  * `pi_natives.<platform>-<arch>*.node` is required, validated, and returned":
  * platform/variant detection, candidate-path resolution, on-disk staging from
  * `node_modules` (Windows update safety), embedded-addon extraction (Bun
- * standalone binaries), version-sentinel validation, and the aggregated error
+ * standalone binaries), release-stamp validation, and the aggregated error
  * surface for diagnostic-friendly failures.
  *
  * `native/index.js` is reduced to one `loadNative()` call plus the generated
@@ -656,28 +656,15 @@ function maybeStageNodeModulesAddon(ctx, errors) {
 	return stagedPath;
 }
 
-
-/** Any release sentinel a `.node` may carry (`__piNativesV{major}_{minor}_{patch}`). */
-const VERSION_SENTINEL_ANY_RE = /^__piNativesV[A-Za-z0-9_]+$/;
-
-/**
- * Release version encoded in a sentinel export name.
- * @param {string} sentinel
- * @returns {string}
- */
-function sentinelVersion(sentinel) {
-	return sentinel.slice("__piNativesV".length).replace(/_/g, ".");
-}
-
 /**
- * Before version sentinels were exported, published native addons still shared
+ * Before release identities existed, published native addons still shared
  * this stable core ABI. Let those on-disk addons bridge a package-version bump
- * when they expose the signature; keep every versioned addon and a current
+ * when they expose the signature; keep every identified addon and a current
  * on-disk file paired with resident old exports on the strict path below.
  */
-function isCompatiblePreSentinelNativeAddon(bindings, diskHasExpectedSentinel) {
-	if (diskHasExpectedSentinel) return false;
-	if (Object.keys(bindings).some(key => /^__piNativesV[A-Za-z0-9_]+$/.test(key))) return false;
+function isCompatiblePreSentinelNativeAddon(bindings, diskHasExpectedStamp) {
+	if (diskHasExpectedStamp) return false;
+	if (bindingsHaveReleaseIdentity(bindings)) return false;
 	return (
 		typeof bindings.countTokens === "function" &&
 		typeof bindings.executeShell === "function" &&
@@ -692,53 +679,48 @@ function isCompatiblePreSentinelNativeAddon(bindings, diskHasExpectedSentinel) {
 export function validateLoadedBindings(ctx, bindings, candidate) {
 	// In workspace dev (running out of `packages/natives/native/` rather than a
 	// `node_modules` install or a compiled bundle) the local `.node` only gains
-	// the renamed sentinel after `bun --cwd=packages/natives run build`. Skip
+	// the new release stamp after `bun --cwd=packages/natives run build`. Skip
 	// validation there so a stale post-pull dev tree boots while the rebuild
 	// completes; install and compiled-binary paths still validate. The mismatch
 	// is not swallowed silently: `native/index.js` exports `missingNativeExport`
 	// for every symbol the stale addon predates, so the first call through one
 	// reports the addon, both releases, and the rebuild command.
 	if (ctx.isWorkspaceLoad) return;
-	if (typeof bindings[ctx.versionSentinelExport] === "function") return;
+	const residentVersion = bindingsReleaseVersion(bindings);
+	if (residentVersion === ctx.packageVersion) return;
 
-	// The expected sentinel is missing. Distinguish two failure modes by the
-	// sentinel the bindings DO carry:
+	// The bindings report another release (or none). Distinguish two failure
+	// modes by what the file on disk carries:
 	//   - disk stale: the `.node` on disk predates this loader (its own build);
 	//     reinstalling re-syncs the file.
 	//   - process stale: an in-place upgrade landed a new release on disk while
 	//     this process still holds the previous addon generation resident in the
 	//     dynamic-loader's native-module cache. `require` returns those old
-	//     exports, which carry the PRIOR sentinel — disk is already consistent,
+	//     exports, which report the PRIOR release — disk is already consistent,
 	//     so reinstall is a no-op and only restarting the process re-syncs.
-	const residentSentinel = Object.keys(bindings).find(
-		key => key !== ctx.versionSentinelExport && VERSION_SENTINEL_ANY_RE.test(key),
-	);
-	// A prior sentinel alone cannot distinguish a resident old module from an
-	// actually stale file: `require` returns the same exports in both cases.
-	// The restart diagnosis is valid only when the selected file itself carries
-	// the current sentinel; otherwise a restart would simply reload stale disk.
-	let diskHasExpectedSentinel = false;
+	// Resident exports alone cannot tell these apart: `require` returns the
+	// same exports in both cases. The restart diagnosis is valid only when the
+	// selected file itself carries the current stamp; otherwise a restart would
+	// simply reload stale disk.
+	let diskHasExpectedStamp = false;
 	try {
-		diskHasExpectedSentinel = containsVersionSentinel(fs.readFileSync(candidate), ctx.versionSentinelExport);
+		diskHasExpectedStamp = containsVersionStamp(fs.readFileSync(candidate), ctx.packageVersion);
 	} catch {
 		// The successful require above normally guarantees readability. If the
 		// file disappears concurrently, retain the safe reinstall diagnosis.
 	}
-	if (isCompatiblePreSentinelNativeAddon(bindings, diskHasExpectedSentinel)) return;
-	if (residentSentinel && diskHasExpectedSentinel) {
-		const residentVersion = sentinelVersion(residentSentinel);
+	if (isCompatiblePreSentinelNativeAddon(bindings, diskHasExpectedStamp)) return;
+	if (residentVersion && diskHasExpectedStamp) {
 		throw new Error(
-			`Loaded ${candidate}, which exposes the @oh-my-pi/pi-natives@${residentVersion} version ` +
-				`sentinel \`${residentSentinel}\` but not the @${ctx.packageVersion} sentinel ` +
-				`\`${ctx.versionSentinelExport}\` this loader expects. omp was upgraded to ` +
-				`${ctx.packageVersion} while this session was running; the ${residentVersion} addon is ` +
-				"still resident in this process. Disk is already consistent — restart omp to pick up " +
-				`${ctx.packageVersion} (reinstalling changes nothing).`,
+			`Loaded ${candidate}, which reports @oh-my-pi/pi-natives@${residentVersion}, but this loader is ` +
+				`@${ctx.packageVersion}. omp was upgraded to ${ctx.packageVersion} while this session was running; ` +
+				`the ${residentVersion} addon is still resident in this process. Disk is already consistent — ` +
+				`restart omp to pick up ${ctx.packageVersion} (reinstalling changes nothing).`,
 		);
 	}
 	throw new Error(
-		`Loaded ${candidate} but it does not expose the @oh-my-pi/pi-natives@${ctx.packageVersion} ` +
-			`version sentinel \`${ctx.versionSentinelExport}\`. The .node file on disk is from a different ` +
+		`Loaded ${candidate} but it reports ${residentVersion ? `@oh-my-pi/pi-natives@${residentVersion}` : "no release version"}, ` +
+			`not the @${ctx.packageVersion} this loader expects. The .node file on disk is from a different ` +
 			"release than this loader — reinstall to re-sync.",
 	);
 }
@@ -746,7 +728,7 @@ export function validateLoadedBindings(ctx, bindings, candidate) {
 /**
  * Identity of the addon `loadNative()` returned, in the shape the
  * missing-export diagnostic reports. Null until a load succeeds.
- * @type {{ path: string; sentinel: string | null; expectedSentinel: string; packageVersion: string; stale: boolean } | null}
+ * @type {{ path: string; version: string | null; packageVersion: string; stale: boolean } | null}
  */
 let loadedAddon = null;
 
@@ -755,22 +737,21 @@ let loadedAddon = null;
  * release the file came from, and the release this tree expects.
  * @param {Record<string, unknown>} bindings
  * @param {string} candidate
- * @param {{ packageVersion: string; versionSentinelExport: string }} ctx
+ * @param {{ packageVersion: string }} ctx
  */
 function describeLoadedAddon(bindings, candidate, ctx) {
-	const sentinel = Object.keys(bindings).find(key => VERSION_SENTINEL_ANY_RE.test(key)) ?? null;
+	const version = bindingsReleaseVersion(bindings);
 	return {
 		path: candidate,
-		sentinel,
-		expectedSentinel: ctx.versionSentinelExport,
+		version,
 		packageVersion: ctx.packageVersion,
-		stale: sentinel !== ctx.versionSentinelExport,
+		stale: version !== ctx.packageVersion,
 	};
 }
 
 /**
  * The addon behind this process's `@oh-my-pi/pi-natives` exports.
- * @returns {{ path: string; sentinel: string | null; expectedSentinel: string; packageVersion: string; stale: boolean } | null}
+ * @returns {{ path: string; version: string | null; packageVersion: string; stale: boolean } | null}
  */
 export function nativeAddonStatus() {
 	return loadedAddon;
@@ -779,7 +760,7 @@ export function nativeAddonStatus() {
 /**
  * Stand-in for an export the loaded addon does not provide.
  *
- * A workspace tree tolerates a sentinel mismatch on purpose: a checkout that
+ * A workspace tree tolerates a release mismatch on purpose: a checkout that
  * pulled a new release keeps running until `bun run build:native` finishes
  * (see `validateLoadedBindings`), and PR CI loads release addons under a newer
  * checkout the same way. Such an addon has no value for any symbol added after
@@ -815,12 +796,12 @@ export function missingNativeExportMessage(symbolName, addon = loadedAddon) {
 	if (!addon.stale) {
 		return `@oh-my-pi/pi-natives export \`${symbolName}\` is missing from ${addon.path}; ${rebuild}.`;
 	}
-	const loaded = addon.sentinel
-		? `the @oh-my-pi/pi-natives@${sentinelVersion(addon.sentinel)} addon`
-		: "an addon built before version sentinels existed";
+	const loaded = addon.version
+		? `the @oh-my-pi/pi-natives@${addon.version} addon`
+		: "an addon without a release stamp";
 	return (
 		`@oh-my-pi/pi-natives export \`${symbolName}\` is missing: ${addon.path} is ${loaded}, not ` +
-		`@${addon.packageVersion} (\`${addon.expectedSentinel}\`) — ${rebuild}.`
+		`@${addon.packageVersion} — ${rebuild}.`
 	);
 }
 
@@ -927,14 +908,12 @@ export function initLoaderContext(overrides = {}) {
 		userDataDir,
 	});
 
-	// Version sentinel emitted by the Rust addon under a `js_name` that encodes
-	// the package version (`__piNativesV{major}_{minor}_{patch}`).
-	// `scripts/release.ts` bumps the name in `crates/pi-natives/src/lib.rs` in
-	// lock-step with the version, so a `.node` from a different release
-	// physically cannot expose the symbol this loader is looking for. That
-	// turns the silent `<sym> is not a function` crash from a Windows
-	// locked-file update into an actionable load-time error.
-	const versionSentinelExport = versionSentinelFor(packageVersion);
+	// Release validation compares `__piNativesBuildVersion()` — the version the
+	// build pipeline stamps into the addon after linking
+	// (`scripts/stamp-native-version.ts`) — with `package.json#version`, so a
+	// `.node` from a different release is rejected at load time instead of
+	// surfacing later as a silent `<sym> is not a function` crash from a
+	// Windows locked-file update.
 
 	return {
 		platformTag,
@@ -948,7 +927,6 @@ export function initLoaderContext(overrides = {}) {
 		addonFilenames,
 		addonLabel,
 		candidates,
-		versionSentinelExport,
 		isWorkspaceLoad,
 		nativesDir,
 	};

package/native/version-sentinel.d.ts

@@ -1,5 +1,17 @@
-/** Return the native-addon export expected for a package version. */
-export function versionSentinelFor(packageVersion: string): string;
+/** Prefix of the post-link stamp slot linked into every addon. */
+export const VERSION_STAMP_MAGIC: string;
 
-/** Check whether addon bytes contain the exact expected version sentinel. */
-export function containsVersionSentinel(bytes: Buffer, expected: string): boolean;
+/** Total stamp slot size in bytes: magic, version, NUL padding. */
+export const VERSION_STAMP_SIZE: number;
+
+/** Check whether addon bytes carry the stamp for exactly `version`. */
+export function containsVersionStamp(bytes: Uint8Array, version: string): boolean;
+
+/** Check whether pre-stamp addon bytes export the legacy `__piNativesV*` sentinel for exactly `version`. */
+export function containsLegacyVersionSentinel(bytes: Uint8Array, version: string): boolean;
+
+/** Release a loaded addon reports (stamp, or legacy `__piNativesV*` export), or `null`. */
+export function bindingsReleaseVersion(bindings: Record<string, unknown>): string | null;
+
+/** True when the bindings identify their release at all (stamp reader or legacy sentinel). */
+export function bindingsHaveReleaseIdentity(bindings: Record<string, unknown>): boolean;

package/native/version-sentinel.js

@@ -1,42 +1,100 @@
 /**
- * Version-sentinel helpers shared by the native loader and the embed pipeline.
+ * Addon release-identity helpers shared by the native loader, the embed
+ * pipeline, and the post-link stamp tool (`scripts/stamp-native-version.ts`).
  *
- * Kept in its own module so `scripts/embed-native.ts` can reuse the exact-match
- * logic without importing `loader-state.js` — which pulls in the generated
+ * Kept in its own module so `scripts/embed-native.ts` can reuse them without
+ * importing `loader-state.js` — which pulls in the generated
  * `embedded-addon.js` and its `with { type: "file" }` archive import. That
  * chain fails to resolve when the archive is missing, which would break
  * `gen:native:reset` on an inconsistent tree (populated manifest, deleted
  * archive) before it can restore the checked-in null stub.
+ *
+ * Current addons carry a fixed-size stamp slot (`VERSION_STAMP_MAGIC` + the
+ * release version + NUL padding) written after linking and reported by
+ * `__piNativesBuildVersion()`. Addons published before that exported a
+ * per-release `__piNativesV{major}_{minor}_{patch}` function instead; those
+ * are still recognized so an old module resident across an in-place upgrade
+ * is diagnosed correctly.
  */
 
+/** Prefix of the stamp slot linked into every addon (`crates/pi-natives/src/lib.rs`). */
+export const VERSION_STAMP_MAGIC = "PI_NATIVES_VERSION_STAMP:";
+
+/** Total stamp slot size in bytes: magic, version, NUL padding. */
+export const VERSION_STAMP_SIZE = 64;
+
+/** Export names of pre-stamp releases (`__piNativesV18_3_2`). */
+const LEGACY_SENTINEL_RE = /^__piNativesV([A-Za-z0-9_]+)$/;
+
 /**
- * Return the version sentinel exported by an addon built for `packageVersion`.
- * @param {string} packageVersion
- * @returns {string}
+ * Check whether addon bytes carry the stamp for exactly `version` (a stamp for
+ * `18.1.10` must not satisfy a lookup for `18.1.1`, so the version must be
+ * followed by the slot's NUL padding).
+ * @param {Uint8Array} bytes
+ * @param {string} version
+ * @returns {boolean}
  */
-export function versionSentinelFor(packageVersion) {
-	return `__piNativesV${packageVersion.replace(/[^A-Za-z0-9]/g, "_")}`;
+export function containsVersionStamp(bytes, version) {
+	if (version.length === 0) return false;
+	const needle = Buffer.from(`${VERSION_STAMP_MAGIC}${version}\0`, "utf8");
+	return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).indexOf(needle) !== -1;
 }
 
 /**
- * Check for an exact version sentinel rather than a longer sentinel with the
- * expected value as its prefix (e.g. `__piNativesV18_1_10` must not satisfy a
- * lookup for `__piNativesV18_1_1`).
- * @param {Buffer} bytes
- * @param {string} expected
+ * Check whether pre-stamp addon bytes export the legacy sentinel for exactly
+ * `version` (`__piNativesV18_3_2`, not a longer `__piNativesV18_3_20`). The
+ * loader accepts such an addon for that release, so embedding may too.
+ * @param {Uint8Array} bytes
+ * @param {string} version
  * @returns {boolean}
  */
-export function containsVersionSentinel(bytes, expected) {
-	if (expected.length === 0) return false;
-	let offset = 0;
-	while (offset < bytes.length) {
-		const index = bytes.indexOf(expected, offset);
-		if (index === -1) return false;
-		const next = bytes[index + expected.length];
-		const isIdentifierByte =
-			next === 95 || (next >= 48 && next <= 57) || (next >= 65 && next <= 90) || (next >= 97 && next <= 122);
-		if (!isIdentifierByte) return true;
-		offset = index + expected.length;
+export function containsLegacyVersionSentinel(bytes, version) {
+	if (version.length === 0) return false;
+	const haystack = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const needle = Buffer.from(`__piNativesV${version.replace(/[^A-Za-z0-9]/g, "_")}`, "utf8");
+	for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + 1)) {
+		const next = haystack[at + needle.length];
+		const continues =
+			next !== undefined &&
+			((next >= 0x30 && next <= 0x39) || (next >= 0x41 && next <= 0x5a) || (next >= 0x61 && next <= 0x7a) || next === 0x5f);
+		if (!continues) return true;
 	}
 	return false;
 }
+
+/**
+ * Release version a loaded addon reports: the post-link stamp for current
+ * addons, the legacy sentinel export name for pre-stamp releases, `null` for
+ * unstamped builds and addons that predate both.
+ * @param {Record<string, unknown>} bindings
+ * @returns {string | null}
+ */
+export function bindingsReleaseVersion(bindings) {
+	const report = bindings.__piNativesBuildVersion;
+	if (typeof report === "function") {
+		try {
+			const version = report();
+			return typeof version === "string" && version.length > 0 ? version : null;
+		} catch {
+			return null;
+		}
+	}
+	for (const key of Object.keys(bindings)) {
+		const match = LEGACY_SENTINEL_RE.exec(key);
+		if (match) return match[1].replace(/_/g, ".");
+	}
+	return null;
+}
+
+/**
+ * True when the bindings identify their release at all (stamp reader or
+ * legacy sentinel), i.e. they are not a pre-sentinel addon.
+ * @param {Record<string, unknown>} bindings
+ * @returns {boolean}
+ */
+export function bindingsHaveReleaseIdentity(bindings) {
+	return (
+		typeof bindings.__piNativesBuildVersion === "function" ||
+		Object.keys(bindings).some(key => LEGACY_SENTINEL_RE.test(key))
+	);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-natives",
-	"version": "18.3.1",
+	"version": "18.3.3",
 	"description": "Native Rust bindings for PDF conversion, audio, WebRTC, grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://omp.sh",
@@ -107,11 +107,11 @@
 		}
 	},
 	"optionalDependencies": {
-		"@oh-my-pi/pi-natives-linux-x64": "18.3.1",
-		"@oh-my-pi/pi-natives-linux-arm64": "18.3.1",
-		"@oh-my-pi/pi-natives-darwin-x64": "18.3.1",
-		"@oh-my-pi/pi-natives-darwin-arm64": "18.3.1",
-		"@oh-my-pi/pi-natives-win32-x64": "18.3.1",
-		"@oh-my-pi/pi-natives-win32-arm64": "18.3.1"
+		"@oh-my-pi/pi-natives-linux-x64": "18.3.3",
+		"@oh-my-pi/pi-natives-linux-arm64": "18.3.3",
+		"@oh-my-pi/pi-natives-darwin-x64": "18.3.3",
+		"@oh-my-pi/pi-natives-darwin-arm64": "18.3.3",
+		"@oh-my-pi/pi-natives-win32-x64": "18.3.3",
+		"@oh-my-pi/pi-natives-win32-arm64": "18.3.3"
 	}
 }