@gajae-code/natives 0.11.7 → 0.11.9

package/native/index.d.ts

@@ -201,6 +201,11 @@ export declare class NotificationServer {
    * Fails if not started or `frame_json` is not a valid `ServerMessage`.
    */
   pushFrame(frameJson: string): void
+  /**
+   * Deliver a frame through every authenticated connection and wait for each
+   * socket writer to settle within `timeout_ms`.
+   */
+  pushFrameAndWait(frameJson: string, timeoutMs: number): Promise<boolean>
   /**
    * Broadcast a TypeScript-constructed turn frame without re-parsing JSON.
    * External frames must continue through [`Self::push_frame`] for serde
@@ -386,7 +391,7 @@ export declare class RecoveryFsRoot {
    */
   appendManaged(relativePath: string, data: Uint8Array, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
   /** Remove one exact managed regular file through retained authority. */
-  removeManaged(relativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
+  removeManaged(relativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsRetainedCleanupResult
   /**
    * Create each absent directory component beneath the retained root with
    * owner-only security. Existing components are re-opened no-follow.
@@ -397,22 +402,22 @@ export declare class RecoveryFsRoot {
    * retained root. The source identity is rechecked after the no-replace
    * rename, and the move is rolled back on a mismatch.
    */
-  renameManagedFileNoReplace(sourceRelativePath: string, destinationRelativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
+  renameManagedFileNoReplace(sourceRelativePath: string, destinationRelativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsPublishResult
   /** Snapshot a managed directory tree entirely through the retained root. */
   snapshotManagedTree(relativePath: string): NativeDirectoryTreeResult
   /**
    * Move an exact managed directory tree to an absent name through retained
    * authority.
    */
-  renameManagedTreeNoReplace(sourceRelativePath: string, destinationRelativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsResult
+  renameManagedTreeNoReplace(sourceRelativePath: string, destinationRelativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsPublishResult
   /** Remove an exact managed directory tree through retained authority. */
-  removeManagedTree(relativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsResult
+  removeManagedTree(relativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsRetainedCleanupResult
   /**
    * Atomically install an already-created regular file at an absent name.
    * Both names remain relative to this retained root and are never resolved
    * through a pathname after their parent descriptors are acquired.
    */
-  install(sourceRelativePath: string, destinationRelativePath: string): RecoveryFsResult
+  install(sourceRelativePath: string, destinationRelativePath: string): RecoveryFsPublishResult
   /**
    * Synchronize the retained root directory, making a preceding create or
    * install durable when the filesystem supports directory fsync.
@@ -452,6 +457,15 @@ export declare class Shell {
   abort(): Promise<void>
 }
 
+/**
+ * Publish-result wire-contract sentinel.
+ *
+ * The loader requires this in addition to the release sentinel, so a
+ * same-version modern artifact built before the retained-publish contract
+ * cannot be selected over a compatible baseline.
+ */
+export declare function __piNativesPublishOutcomeV1(): 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
@@ -470,7 +484,7 @@ export declare class Shell {
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV0_11_7(): void
+export declare function __piNativesV0_11_9(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
@@ -1720,6 +1734,18 @@ export interface NativeExactUnlinkResult {
   retainedUnknownPath?: string
 }
 
+/** Dedicated result for an atomic no-replace namespace publication. */
+export interface NativeNoReplaceResult {
+  ok: boolean
+  code?: string
+  mutationState: string
+  durabilityState: string
+  reason: string
+  primitive: string
+  phase: string
+  diagnostic: NativePublishDiagnostic
+}
+
 /** Result of applying or checking owner-only path security. */
 export type NativeOwnerOnlySecurityResult =
 	| {
@@ -1950,6 +1976,38 @@ export interface RecoveryFsIdentity {
   sha256?: string
 }
 
+/** Bounded, path-free diagnostic evidence for one retained publication. */
+export interface RecoveryFsPublishDiagnostic {
+  schemaVersion: number
+  collectionState: string
+  osCode?: number
+  syncFailures?: Array<RecoveryFsPublishSyncFailure>
+}
+
+/**
+ * Explicit mutation and durability outcome for retained no-replace
+ * publication.
+ */
+export interface RecoveryFsPublishResult {
+  ok: boolean
+  code?: string
+  identity?: RecoveryFsIdentity
+  mutationState: string
+  durabilityState: string
+  reason: string
+  primitive: string
+  phase: string
+  diagnostic: RecoveryFsPublishDiagnostic
+}
+
+/** Bounded, path-free diagnostic evidence for one retained publication. */
+export interface RecoveryFsPublishSyncFailure {
+  phase: string
+  parentRole: string
+  osCode?: number
+  kind: string
+}
+
 export interface RecoveryFsResult {
   ok: boolean
   code?: string
@@ -1957,7 +2015,20 @@ export interface RecoveryFsResult {
   data?: Uint8Array
 }
 
-export declare function renameNoReplacePath(sourcePath: string, destinationPath: string): NativeExactUnlinkResult
+/**
+ * Fail-closed outcome for a removal whose detached object remains retained.
+ * `recovery_path` identifies evidence only; it grants no authority to replay
+ * or delete the retained object.
+ */
+export interface RecoveryFsRetainedCleanupResult {
+  ok: boolean
+  code?: string
+  recoveryPath?: string
+  identity?: RecoveryFsIdentity
+  treeSnapshot?: NativeDirectoryTreeSnapshot
+}
+
+export declare function renameNoReplacePath(sourcePath: string, destinationPath: string): NativeNoReplaceResult
 
 /**
  * Repair an owner-only ACL on a retained expected path.
@@ -2232,3 +2303,19 @@ export interface WorkProfile {
  * Returns UTF-16 lines with active SGR codes carried across line boundaries.
  */
 export declare function wrapTextWithAnsi(text: string, width: number, tabWidth: number): Array<string>
+
+/** Bounded, path-free evidence for a parent-directory durability failure. */
+export interface NativePublishSyncFailure {
+  phase: string
+  parentRole: string
+  osCode: number
+  kind: string
+}
+
+/** Bounded, path-free evidence for one atomic publication. */
+export interface NativePublishDiagnostic {
+  schemaVersion: number
+  collectionState: string
+  osCode?: number
+  syncFailures?: Array<NativePublishSyncFailure>
+}

package/native/index.js

@@ -29,7 +29,8 @@ export const RecoveryFsRoot = nativeBindings.RecoveryFsRoot;
 export const Shell = nativeBindings.Shell;
 
 // functions
-export const __piNativesV0_11_7 = nativeBindings.__piNativesV0_11_7;
+export const __piNativesPublishOutcomeV1 = nativeBindings.__piNativesPublishOutcomeV1;
+export const __piNativesV0_11_9 = nativeBindings.__piNativesV0_11_9;
 export const applyBashFixups = nativeBindings.applyBashFixups;
 export const applyOwnerOnlyFdSecurity = nativeBindings.applyOwnerOnlyFdSecurity;
 export const applyOwnerOnlyPathSecurity = nativeBindings.applyOwnerOnlyPathSecurity;

package/native/loader-state.d.ts

@@ -79,4 +79,28 @@ export interface CachedEmbeddedExtractionIsFreshInput {
 
 export function cachedEmbeddedExtractionIsFresh(input: CachedEmbeddedExtractionIsFreshInput): boolean;
 
-export function loadNative(): Record<string, unknown>;
+export interface LoaderContext {
+	isCompiledBinary: boolean;
+	platformTag: string;
+	packageVersion?: string;
+	addonLabel?: string;
+	addonFilenames?: string[];
+	versionedDir?: string;
+	candidates?: string[];
+	selectedVariant?: "modern" | "baseline" | null;
+}
+
+export function embeddedAddonIsAuthoritative(
+	ctx: LoaderContext,
+	addon?: EmbeddedAddon | null,
+): boolean;
+
+export interface LoadNativeOptions {
+	context?: LoaderContext;
+	extractEmbeddedAddons?: (ctx: LoaderContext) => string[];
+	stageNodeModulesAddon?: () => string | null;
+	requireCandidate?: (candidate: string) => Record<string, unknown>;
+	validateCandidate?: (bindings: Record<string, unknown>) => void;
+}
+
+export function loadNative(options?: LoadNativeOptions): Record<string, unknown>;

package/native/loader-state.js

@@ -306,64 +306,56 @@ function resolveCpuVariant(override) {
 	return detectAvx2Support() ? "modern" : "baseline";
 }
 
-function selectEmbeddedAddonFile(selectedVariant) {
-	if (!embeddedAddon) return null;
-	const defaultFile = embeddedAddon.files.find(file => file.variant === "default") || null;
-	if (process.arch !== "x64") return defaultFile || embeddedAddon.files[0] || null;
-	if (selectedVariant === "modern") {
-		return (
-			embeddedAddon.files.find(file => file.variant === "modern") ||
-			embeddedAddon.files.find(file => file.variant === "baseline") ||
-			null
-		);
-	}
-	return embeddedAddon.files.find(file => file.variant === "baseline") || null;
+function embeddedAddonCandidates(selectedVariant) {
+	if (!embeddedAddon) return [];
+	const files = embeddedAddon.files;
+	const candidates = process.arch !== "x64"
+		? [files.find(file => file.variant === "default"), ...files]
+		: selectedVariant === "modern"
+			? [files.find(file => file.variant === "modern"), files.find(file => file.variant === "baseline")]
+			: [files.find(file => file.variant === "baseline")];
+	return [...new Set(candidates.filter(Boolean))];
 }
 
-function maybeExtractEmbeddedAddon(ctx, errors) {
-	if (!ctx.isCompiledBinary || !embeddedAddon) return null;
-	if (embeddedAddon.platformTag !== ctx.platformTag || embeddedAddon.version !== ctx.packageVersion) return null;
-
-	const selectedEmbeddedFile = selectEmbeddedAddonFile(ctx.selectedVariant);
-	if (!selectedEmbeddedFile) return null;
-	const targetPath = path.join(ctx.versionedDir, selectedEmbeddedFile.filename);
-	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.
-		const sizeOf = candidate => {
-			try {
-				return fs.statSync(candidate).size;
-			} catch {
-				return null;
+function maybeExtractEmbeddedAddons(ctx, errors) {
+	if (!ctx.isCompiledBinary || !embeddedAddon) return [];
+	if (embeddedAddon.platformTag !== ctx.platformTag || embeddedAddon.version !== ctx.packageVersion) return [];
+
+	const extracted = [];
+	for (const embeddedFile of embeddedAddonCandidates(ctx.selectedVariant)) {
+		const targetPath = path.join(ctx.versionedDir, embeddedFile.filename);
+		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.
+			const sizeOf = candidate => {
+				try {
+					return fs.statSync(candidate).size;
+				} catch {
+					return null;
+				}
+			};
+			if (cachedEmbeddedExtractionIsFresh({ targetPath, embeddedPath: embeddedFile.filePath, sizeOf })) {
+				extracted.push(targetPath);
+				continue;
 			}
-		};
-		if (cachedEmbeddedExtractionIsFresh({ targetPath, embeddedPath: selectedEmbeddedFile.filePath, sizeOf })) {
-			return targetPath;
 		}
-	}
-
-	try {
-		fs.mkdirSync(ctx.versionedDir, { recursive: true });
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		errors.push(`embedded addon dir: ${message}`);
-		return null;
-	}
 
-	try {
-		const buffer = fs.readFileSync(selectedEmbeddedFile.filePath);
-		const tempPath = `${targetPath}.tmp.${process.pid}`;
-		fs.writeFileSync(tempPath, buffer);
-		fs.renameSync(tempPath, targetPath);
-		return targetPath;
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		errors.push(`embedded addon write (${selectedEmbeddedFile.filename}): ${message}`);
-		return null;
+		try {
+			fs.mkdirSync(ctx.versionedDir, { recursive: true });
+			const buffer = fs.readFileSync(embeddedFile.filePath);
+			const tempPath = `${targetPath}.tmp.${process.pid}`;
+			fs.writeFileSync(tempPath, buffer);
+			fs.renameSync(tempPath, targetPath);
+			extracted.push(targetPath);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			errors.push(`embedded addon write (${embeddedFile.filename}): ${message}`);
+		}
 	}
+	return extracted;
 }
 
 /**
@@ -410,12 +402,22 @@ function maybeStageNodeModulesAddon(ctx, errors) {
 }
 
 function validateLoadedBindings(ctx, bindings, candidate) {
-	if (typeof bindings[ctx.versionSentinelExport] === "function") return;
-	throw new Error(
-		`Loaded ${candidate} but it does not expose the @gajae-code/natives@${ctx.packageVersion} ` +
-			`version sentinel \`${ctx.versionSentinelExport}\`. The .node file on disk is from a different ` +
-			"release than this loader — reinstall to re-sync.",
-	);
+	if (typeof bindings[ctx.versionSentinelExport] !== "function") {
+		throw new Error(
+			`Loaded ${candidate} but it does not expose the @gajae-code/natives@${ctx.packageVersion} ` +
+				`version sentinel \`${ctx.versionSentinelExport}\`. The .node file on disk is from a different ` +
+				"release than this loader — reinstall to re-sync.",
+		);
+	}
+	if (typeof bindings.__piNativesPublishOutcomeV1 !== "function") {
+		throw new Error(
+			`Loaded ${candidate} but it lacks retained-publish capability sentinel ` +
+			"`__piNativesPublishOutcomeV1`; trying the next compatible artifact.",
+		);
+	}
+	if (typeof bindings.renameNoReplacePath !== "function") {
+		throw new Error(`Loaded ${candidate} but it lacks required atomic publish capability \`renameNoReplacePath\`.`);
+	}
 }
 
 function buildHelpMessage(ctx) {
@@ -516,20 +518,30 @@ function initLoaderContext(require_) {
 	};
 }
 
-export function loadNative() {
-	const require_ = createRequire(import.meta.url);
-	const ctx = initLoaderContext(require_);
+/** Embedded standalone payloads are the complete trust boundary for their matching build. */
+export function embeddedAddonIsAuthoritative(ctx, addon = embeddedAddon) {
+	return (
+		ctx.isCompiledBinary && addon?.platformTag === ctx.platformTag && addon.version === ctx.packageVersion
+	);
+}
 
-	const errors = [];
-	const embeddedCandidate = maybeExtractEmbeddedAddon(ctx, errors);
-	const stagedCandidate = embeddedCandidate ? null : maybeStageNodeModulesAddon(ctx, errors);
-	const prepended = [embeddedCandidate, stagedCandidate].filter(c => typeof c === "string");
-	const runtimeCandidates = prepended.length > 0 ? [...prepended, ...ctx.candidates] : ctx.candidates;
+export function loadNative(options = {}) {
+	const require_ = options.requireCandidate ? null : createRequire(import.meta.url);
+	const ctx = options.context ?? initLoaderContext(require_);
 
+	const errors = [];
+	const embeddedCandidates = (options.extractEmbeddedAddons ?? maybeExtractEmbeddedAddons)(ctx, errors);
+	const embeddedIsAuthoritative = embeddedAddonIsAuthoritative(ctx);
+	const stagedCandidate =
+		embeddedCandidates.length > 0 || embeddedIsAuthoritative
+			? null
+			: (options.stageNodeModulesAddon ?? maybeStageNodeModulesAddon)(ctx, errors);
+	const prepended = [...embeddedCandidates, stagedCandidate].filter(c => typeof c === "string");
+	const runtimeCandidates = embeddedIsAuthoritative ? prepended : prepended.length > 0 ? [...prepended, ...ctx.candidates] : ctx.candidates;
 	const loaded = loadFromCandidates({
 		candidates: runtimeCandidates,
-		requireCandidate: candidate => require_(candidate),
-		validateCandidate: (bindings, candidate) => validateLoadedBindings(ctx, bindings, candidate),
+		requireCandidate: options.requireCandidate ?? (candidate => require_(candidate)),
+		validateCandidate: options.validateCandidate ?? ((bindings, candidate) => validateLoadedBindings(ctx, bindings, candidate)),
 		describeCandidate: candidate => candidate,
 	});
 	if (loaded.bindings) return loaded.bindings;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gajae-code/natives",
-	"version": "0.11.7",
+	"version": "0.11.9",
 	"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",
@@ -61,11 +61,11 @@
 		"README.md"
 	],
 	"optionalDependencies": {
-		"@gajae-code/natives-darwin-arm64": "0.11.7",
-		"@gajae-code/natives-darwin-x64": "0.11.7",
-		"@gajae-code/natives-linux-arm64": "0.11.7",
-		"@gajae-code/natives-linux-x64": "0.11.7",
-		"@gajae-code/natives-win32-x64": "0.11.7"
+		"@gajae-code/natives-darwin-arm64": "0.11.9",
+		"@gajae-code/natives-darwin-x64": "0.11.9",
+		"@gajae-code/natives-linux-arm64": "0.11.9",
+		"@gajae-code/natives-linux-x64": "0.11.9",
+		"@gajae-code/natives-win32-x64": "0.11.9"
 	},
 	"exports": {
 		".": {