@gajae-code/natives 0.10.1 → 0.11.0

package/native/index.d.ts

@@ -12,6 +12,7 @@ export declare class ComputerController {
   keypress(expectedEpoch: number | undefined | null, keys: Array<string>): void
   wait(expectedEpoch: number | undefined | null, ms: number): void
 }
+
 /**
  * Long-lived macOS appearance observer.
  *
@@ -117,6 +118,16 @@ export declare class NotificationServer {
    * config commands). Must be called before [`Self::start`].
    */
   onInbound(callback: (err: null | Error, msg: InboundEvent) => void): void
+  /**
+   * Register the raw v3 SDK frame callback. Must be called before
+   * [`Self::start`].
+   */
+  onSdkFrame(callback: (err: null | Error, frame: SdkFrameEvent) => void): void
+  /**
+   * Register the connection-close callback. Must be called before
+   * [`Self::start`].
+   */
+  onConnectionClose(callback: (err: null | Error, connectionId: string) => void): void
   /**
    * Bind the loopback endpoint and start serving. Resolves with the bound
    * endpoint info once the socket is bound.
@@ -128,12 +139,32 @@ export declare class NotificationServer {
   /**
    * Broadcast an `action_needed` ask. `needed_json` is a JSON `ActionNeeded`.
    *
-   * `repliable` should be `true` only in unattended/RPC mode.
+   * `repliable` should be `true` only when an SDK workflow-gate resolver is
+   * available.
    *
    * # Errors
    * Fails if not started or `needed_json` is invalid.
    */
   registerAsk(neededJson: string, repliable: boolean): void
+  /**
+   * Register a correlated workflow-gate ask. `workflow_json` must be an
+   * `action_needed` wire frame carrying a nonempty `workflowGateId`.
+   */
+  registerWorkflowGateAsk(workflowJson: string, repliable: boolean): void
+  /**
+   * Register an ask and return an opaque in-process capability. Pass it
+   * unchanged to [`Self::retire_if_unclaimed`]; do not construct, persist,
+   * inspect, or treat it as workflow-gate authority. A supplied
+   * `workflowGateId` is preserved.
+   */
+  registerArbitratedAsk(neededJson: string, repliable: boolean): PresentationLease
+  /**
+   * Atomically terminalize the exact presentation named by an opaque lease.
+   * The typed status proves whether it retired, was already terminal, was
+   * claimed, or became stale without exposing claims, receipts, registration
+   * state, or workflow-gate authority.
+   */
+  retireIfUnclaimed(lease: PresentationLease): RetireIfUnclaimedResult
   /**
    * Broadcast an ephemeral `action_needed` idle ping. `needed_json` is JSON
    * `ActionNeeded`.
@@ -152,6 +183,8 @@ export declare class NotificationServer {
    * Fails if not started or `frame_json` is not a valid `ServerMessage`.
    */
   pushFrame(frameJson: string): void
+  /** Send raw JSON to one connected v3 SDK client. */
+  sendTo(connectionId: string, json: string): void
   /**
    * Publish a replayable `session_ready` readiness signal. `ready_json` is a
    * JSON `SessionReady`. Unlike [`Self::push_frame`], this frame is buffered
@@ -164,11 +197,10 @@ export declare class NotificationServer {
    */
   pushSessionReady(readyJson: string): void
   /**
-   * Resolve an action locally (the CLI/TUI answered). `answer_json` is an
-   * optional JSON `ReplyAnswer`.
-   *
-   * # Errors
-   * Fails if not started or `answer_json` is invalid.
+   * Resolve a legacy/non-arbitrated action locally (the CLI/TUI answered).
+   * Arbitrated presentations require their opaque exact lease to be passed to
+   * [`Self::retire_if_unclaimed`], so an id-only local resolution fails
+   * closed.
    */
   resolveLocal(id: string, answerJson?: string | undefined | null): void
   /**
@@ -206,7 +238,7 @@ export declare class NotificationServer {
    */
   reject(id: string, reason?: string | undefined | null): void
   /**
-   * Update whether the unattended gate resolver is currently available.
+   * Update whether the SDK workflow-gate resolver is currently available.
    *
    * # Errors
    * Fails if not started.
@@ -226,6 +258,8 @@ export declare class Process {
   static fromPath(path: string): Array<Process>
   /** Operating-system process identifier for this process reference. */
   get pid(): number
+  /** Kernel-derived identity evidence for this exact process incarnation. */
+  get incarnation(): string
   /** Parent process id for this process, when available. */
   get ppid(): number | null
   /** Launch arguments for this process. */
@@ -315,7 +349,7 @@ export declare class Shell {
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV0_10_1(): void
+export declare function __piNativesV0_11_0(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
@@ -1419,6 +1453,18 @@ export declare function parseKey(data: string, kittyProtocolActive: boolean): st
  */
 export declare function parseKittySequence(data: string): ParsedKittyResult | null
 
+/**
+ * Opaque in-process presentation capability.
+ *
+ * Returned by [`NotificationServer::register_arbitrated_ask`]. Pass it
+ * unchanged to [`NotificationServer::retire_if_unclaimed`]; do not construct,
+ * persist, inspect, or treat it as workflow-gate authority.
+ */
+export interface PresentationLease {
+  actionId: string
+  registrationEpoch: number
+}
+
 /** Current state of a process reference. */
 export declare enum ProcessStatus {
   /** The referenced process is still running. */
@@ -1497,7 +1543,10 @@ export declare function readImageFromClipboard(): Promise<ClipboardImage | undef
 
 /** A client reply forwarded to the TypeScript host for gate resolution. */
 export interface ReplyEvent {
-  /** The action id being answered (the real broker `gate_id` for asks). */
+  /**
+   * The transient action/presentation id being answered. This is not the
+   * durable workflow gate id.
+   */
   id: string
   /** JSON-encoded `ReplyAnswer` (number, string, or `{selected,custom}`). */
   answerJson: string
@@ -1507,6 +1556,17 @@ export interface ReplyEvent {
   replyReceiptId: string
 }
 
+/** Public status of exact direct retirement. Claims and receipts remain native. */
+export interface RetireIfUnclaimedResult {
+  status: 'retired' | 'already_terminal' | 'claimed' | 'stale'
+}
+
+/** A raw v3 SDK frame paired with its actual WebSocket connection id. */
+export interface SdkFrameEvent {
+  connectionId: string
+  json: string
+}
+
 /**
  * Search content for a pattern (one-shot, compiles pattern each time).
  * For repeated searches with the same pattern, use [`grep`] with file filters.

package/native/index.js

@@ -27,7 +27,7 @@ export const PtySession = nativeBindings.PtySession;
 export const Shell = nativeBindings.Shell;
 
 // functions
-export const __piNativesV0_10_1 = nativeBindings.__piNativesV0_10_1;
+export const __piNativesV0_11_0 = nativeBindings.__piNativesV0_11_0;
 export const applyBashFixups = nativeBindings.applyBashFixups;
 export const astEdit = nativeBindings.astEdit;
 export const astGrep = nativeBindings.astGrep;

package/native/loader-state.d.ts

@@ -47,6 +47,7 @@ export interface ResolveLoaderCandidatesInput {
 	addonFilenames: string[];
 	isCompiledBinary: boolean;
 	stageFromNodeModules?: boolean;
+	isWorkspaceLoad?: boolean;
 	optionalPackageNativeDirs?: string[];
 	nativeDir: string;
 	execDir: string;
@@ -56,4 +57,18 @@ export interface ResolveLoaderCandidatesInput {
 
 export function resolveLoaderCandidates(input: ResolveLoaderCandidatesInput): string[];
 
+export interface LoadFromCandidatesInput<T> {
+	candidates: string[];
+	requireCandidate: (candidate: string) => T;
+	validateCandidate: (bindings: T, candidate: string) => void;
+	describeCandidate: (candidate: string) => string;
+}
+
+export interface LoadFromCandidatesResult<T> {
+	bindings: T | null;
+	errors: string[];
+}
+
+export function loadFromCandidates<T>(input: LoadFromCandidatesInput<T>): LoadFromCandidatesResult<T>;
+
 export function loadNative(): Record<string, unknown>;

package/native/loader-state.js

@@ -146,6 +146,7 @@ export function shouldStageNodeModulesAddon({ platform, isCompiledBinary, native
  *   addonFilenames: string[];
  *   isCompiledBinary: boolean;
  *   stageFromNodeModules?: boolean;
+ *   isWorkspaceLoad?: boolean;
  *   optionalPackageNativeDirs?: string[];
  *   nativeDir: string;
  *   execDir: string;
@@ -158,12 +159,14 @@ export function resolveLoaderCandidates({
 	addonFilenames,
 	isCompiledBinary,
 	stageFromNodeModules = false,
+	isWorkspaceLoad = false,
 	optionalPackageNativeDirs = [],
 	nativeDir,
 	execDir,
 	versionedDir,
 	userDataDir,
 }) {
+	const workspaceCandidates = addonFilenames.map(filename => path.join(nativeDir, filename));
 	const optionalPackageCandidates = optionalPackageNativeDirs.flatMap(optionalNativeDir =>
 		addonFilenames.map(filename => path.join(optionalNativeDir, filename)),
 	);
@@ -171,7 +174,10 @@ export function resolveLoaderCandidates({
 		path.join(nativeDir, filename),
 		path.join(execDir, filename),
 	]);
-	const baseReleaseCandidates = [...optionalPackageCandidates, ...legacyReleaseCandidates];
+	const legacyExecCandidates = addonFilenames.map(filename => path.join(execDir, filename));
+	const baseReleaseCandidates = isWorkspaceLoad
+		? [...workspaceCandidates, ...optionalPackageCandidates, ...legacyExecCandidates]
+		: [...optionalPackageCandidates, ...legacyReleaseCandidates];
 	const compiledCandidates = addonFilenames.flatMap(filename => [
 		path.join(versionedDir, filename),
 		path.join(userDataDir, filename),
@@ -188,6 +194,35 @@ export function resolveLoaderCandidates({
 	return [...new Set(releaseCandidates)];
 }
 
+/**
+ * Deterministically try candidate paths in order using injected operations.
+ * This leaves file loading and compatibility policy at the call site while
+ * making fallback behavior testable without a native addon on disk.
+ *
+ * @template T
+ * @param {{
+ *   candidates: string[];
+ *   requireCandidate: (candidate: string) => T;
+ *   validateCandidate: (bindings: T, candidate: string) => void;
+ *   describeCandidate: (candidate: string) => string;
+ * }} input
+ * @returns {{ bindings: T | null; errors: string[] }}
+ */
+export function loadFromCandidates({ candidates, requireCandidate, validateCandidate, describeCandidate }) {
+	const errors = [];
+	for (const candidate of candidates) {
+		try {
+			const bindings = requireCandidate(candidate);
+			validateCandidate(bindings, candidate);
+			return { bindings, errors };
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			errors.push(`${describeCandidate(candidate)}: ${message}`);
+		}
+	}
+	return { bindings: null, errors };
+}
+
 // =========================================================================
 // Side-effectful loader. Everything below runs only when `loadNative()` is
 // called from `native/index.js` — tests that only import the pure helpers
@@ -342,12 +377,6 @@ function maybeStageNodeModulesAddon(ctx, errors) {
 }
 
 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
-	// validation there so a stale post-pull dev tree boots while the rebuild
-	// completes; install and compiled-binary paths still validate.
-	if (ctx.isWorkspaceLoad) return;
 	if (typeof bindings[ctx.versionSentinelExport] === "function") return;
 	throw new Error(
 		`Loaded ${candidate} but it does not expose the @gajae-code/natives@${ctx.packageVersion} ` +
@@ -405,6 +434,8 @@ function initLoaderContext(require_) {
 		isCompiledBinary,
 		nativeDir,
 	});
+	const isWorkspaceLoad =
+		!isCompiledBinary && !nativeDir.includes("\\node_modules\\") && !nativeDir.includes("/node_modules/");
 
 	const selectedVariant = resolveCpuVariant(getVariantOverride());
 	const addonFilenames = getAddonFilenames({ tag: platformTag, arch: process.arch, variant: selectedVariant });
@@ -419,6 +450,7 @@ function initLoaderContext(require_) {
 		addonFilenames,
 		isCompiledBinary,
 		stageFromNodeModules,
+		isWorkspaceLoad,
 		optionalPackageNativeDirs,
 		nativeDir,
 		execDir,
@@ -434,8 +466,6 @@ function initLoaderContext(require_) {
 	// turns the silent `<sym> is not a function` crash from a Windows
 	// locked-file update into an actionable load-time error.
 	const versionSentinelExport = `__piNativesV${packageVersion.replace(/[^A-Za-z0-9]/g, "_")}`;
-	const isWorkspaceLoad =
-		!isCompiledBinary && !nativeDir.includes("\\node_modules\\") && !nativeDir.includes("/node_modules/");
 
 	return {
 		platformTag,
@@ -450,7 +480,6 @@ function initLoaderContext(require_) {
 		addonLabel,
 		candidates,
 		versionSentinelExport,
-		isWorkspaceLoad,
 	};
 }
 
@@ -464,16 +493,14 @@ export function loadNative() {
 	const prepended = [embeddedCandidate, stagedCandidate].filter(c => typeof c === "string");
 	const runtimeCandidates = prepended.length > 0 ? [...prepended, ...ctx.candidates] : ctx.candidates;
 
-	for (const candidate of runtimeCandidates) {
-		try {
-			const bindings = require_(candidate);
-			validateLoadedBindings(ctx, bindings, candidate);
-			return bindings;
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			errors.push(`${candidate}: ${message}`);
-		}
-	}
+	const loaded = loadFromCandidates({
+		candidates: runtimeCandidates,
+		requireCandidate: candidate => require_(candidate),
+		validateCandidate: (bindings, candidate) => validateLoadedBindings(ctx, bindings, candidate),
+		describeCandidate: candidate => candidate,
+	});
+	if (loaded.bindings) return loaded.bindings;
+	errors.push(...loaded.errors);
 
 	if (!SUPPORTED_PLATFORMS.includes(ctx.platformTag)) {
 		throw new Error(

package/package.json

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