galley-js-node 0.0.1

package/README.md

@@ -0,0 +1,7 @@
+# JavaScript Bindings for Node
+
+`galley-js-core` over koffi FFI and `bindings/c/galley.h`.
+
+See `docs/bindings_typescript.md` and `examples/js/node` for the consumer flow.
+
+One shared library embeds one parser; sessions are not thread-safe.

package/build.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Builds a Galley parser and its shared library for a JavaScript consumer
+ * on Node.
+ *
+ * Usage:
+ *   npx galley-js-node <language-dir>
+ *
+ * Thin wrapper over the shared gate (`galley-js-core/build/builder.mjs`),
+ * which documents the accepted grammar files and owns the build. For both
+ * legs at once, use the single entry instead: `galley build <language-dir>`
+ * from `@sanbus-org/galley`.
+ */
+
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildParserArtifact } from "galley-js-core/build/builder.mjs";
+
+const LIBRARY_NAME = "galley-js-node";
+
+function fatal(message) {
+  console.error(`galley-bindings: ${message}`);
+  process.exit(1);
+}
+
+async function main() {
+  if (process.argv.length !== 3) fatal("usage: npx galley-js-node <language-dir>");
+  await buildParserArtifact({
+    languageDirectory: process.argv[2],
+    libraryName: LIBRARY_NAME,
+    bindingsDirectory: path.dirname(fileURLToPath(import.meta.url)),
+    dependencyName: "koffi",
+  });
+}
+
+main().catch((error) => fatal(error?.message ?? String(error)));

package/dist/dispatch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Node procedure-dispatch installer.
+ *
+ * Owns the koffi callback that the shared JS shim
+ * (`galley_install_js_dispatch_id`, generated by `galley-js-core/build/shim.mjs`)
+ * forwards every parser hook through, plus the `require()`-based auto-scan
+ * of `procedures.*` in the language directory. The registry and the
+ * ID-to-name dispatcher live in the core; this module only bridges the
+ * native boundary. Libraries that predate integer hook IDs still export
+ * the name-carrying `galley_install_js_dispatch`, used as a fallback.
+ */
+import type { FfiPort } from "galley-js-core";
+import { type GalleyFFI } from "./ffi.ts";
+export declare function ensureDispatchFor(foreignInterface: GalleyFFI, port: FfiPort): void;

package/dist/dispatch.js

@@ -0,0 +1,146 @@
+/**
+ * Node procedure-dispatch installer.
+ *
+ * Owns the koffi callback that the shared JS shim
+ * (`galley_install_js_dispatch_id`, generated by `galley-js-core/build/shim.mjs`)
+ * forwards every parser hook through, plus the `require()`-based auto-scan
+ * of `procedures.*` in the language directory. The registry and the
+ * ID-to-name dispatcher live in the core; this module only bridges the
+ * native boundary. Libraries that predate integer hook IDs still export
+ * the name-carrying `galley_install_js_dispatch`, used as a fallback.
+ */
+import { createRequire } from "node:module";
+import * as path from "node:path";
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const koffi = require("koffi");
+import { dispatchProcedure, installProcedures, listProcedures } from "galley-js-core";
+import { copyStringBytes } from "./ffi.js";
+// Held to prevent GC of the koffi callbacks; installed per library path.
+// ID and name paths keep separate slots: their signatures differ.
+let dispatchIdCallback = null;
+let dispatchCallback = null;
+const installedFor = new Set();
+let autoAttempted = false;
+function isProcedureName(name) {
+    return name === "reduction" || name.startsWith("reduction_") || name.startsWith("hook_");
+}
+function tryAutoRegister(foreignInterface) {
+    if (listProcedures().length > 0 || autoAttempted)
+        return;
+    autoAttempted = true;
+    const tryLoadModule = (modulePath) => {
+        try {
+            const loadedModule = require(modulePath);
+            let hasHook = false;
+            for (const [name, value] of Object.entries(loadedModule)) {
+                if (typeof value !== "function" || !isProcedureName(name))
+                    continue;
+                hasHook = true;
+                break;
+            }
+            if (hasHook)
+                return installProcedures(loadedModule) > 0;
+            const defaultExport = loadedModule.default;
+            if (defaultExport && typeof defaultExport === "object") {
+                return installProcedures(defaultExport) > 0;
+            }
+        }
+        catch { }
+        return false;
+    };
+    // One place: the directory holding the loaded library. Anything found
+    // there belongs to this grammar; nothing else is even looked at.
+    const baseDirectory = path.dirname(foreignInterface.libPath);
+    const extensions = ["", ".js", ".ts"];
+    for (const extension of extensions) {
+        if (tryLoadModule(path.join(baseDirectory, `procedures${extension}`)))
+            return;
+    }
+}
+export function ensureDispatchFor(foreignInterface, port) {
+    // Option B: auto — if no explicit hooks yet, try to auto-discover procedures.* in language dir
+    tryAutoRegister(foreignInterface);
+    const useIds = foreignInterface.galley_install_js_dispatch_id !== null &&
+        typeof port.procedureNames === "function" &&
+        port.procedureNames().length > 0;
+    if (!useIds && foreignInterface.galley_install_js_dispatch === null) {
+        // Library was built for C procedures (no shim); installs will be no-ops.
+        return;
+    }
+    if (installedFor.has(foreignInterface.libPath))
+        return;
+    if (useIds) {
+        installIdDispatch(foreignInterface, port);
+    }
+    else {
+        installNameDispatch(foreignInterface, port);
+    }
+    installedFor.add(foreignInterface.libPath);
+}
+function installIdDispatch(foreignInterface, port) {
+    if (dispatchIdCallback === null) {
+        // Integer hook IDs: no string copy or decode on the hot path. The table
+        // is fixed per library build; unknown IDs are silent no-ops.
+        const table = port.procedureNames();
+        const proto = koffi.proto("void DispatchId(uint32_t id, void *args)");
+        const cb = koffi.register((id, argsPtr) => {
+            const name = table[typeof id === "bigint" ? Number(id) : id];
+            if (name === undefined)
+                return;
+            let argsAddr = 0n;
+            if (argsPtr !== null && argsPtr !== undefined) {
+                try {
+                    argsAddr = typeof argsPtr === "bigint" ? argsPtr : BigInt(argsPtr);
+                }
+                catch {
+                    argsAddr = 0n;
+                }
+            }
+            dispatchProcedure(name, argsAddr, port);
+        }, koffi.pointer(proto));
+        // Prevent GC — registered callbacks must stay reachable; koffi holds the
+        // trampoline, but we keep the address alive as well.
+        globalThis.__galley_js_dispatchIdCallback = cb;
+        dispatchIdCallback = cb;
+    }
+    foreignInterface.galley_install_js_dispatch_id(dispatchIdCallback);
+}
+function installNameDispatch(foreignInterface, port) {
+    if (dispatchCallback === null) {
+        // Create single global dispatcher. Uses registered callback (must persist
+        // beyond the installer call, unlike transient callbacks). Signature mirrors
+        // Zig: fn([*]const u8, usize, ?*anyopaque) callconv(.c) void — void* for
+        // the name pointer keeps it as a raw address with length.
+        const proto = koffi.proto("void Dispatch(void *name_ptr, size_t name_len, void *args)");
+        const cb = koffi.register((namePtr, nameLen, argsPtr) => {
+            let name;
+            try {
+                // Registered callbacks receive pointer values as BigInt (or null).
+                const ptrVal = typeof namePtr === "bigint" ? namePtr : BigInt(namePtr);
+                const lenVal = typeof nameLen === "bigint" ? nameLen : nameLen;
+                name = copyStringBytes(ptrVal, lenVal);
+            }
+            catch (e) {
+                console.error("galley procedure dispatch: failed to decode name", e);
+                return;
+            }
+            let argsAddr = 0n;
+            if (argsPtr !== null && argsPtr !== undefined) {
+                try {
+                    argsAddr = typeof argsPtr === "bigint" ? argsPtr : BigInt(argsPtr);
+                }
+                catch {
+                    argsAddr = 0n;
+                }
+            }
+            dispatchProcedure(name, argsAddr, port);
+        }, koffi.pointer(proto));
+        // Prevent GC — registered callbacks must stay reachable; koffi holds the
+        // trampoline, but we keep the address alive as well.
+        globalThis.__galley_js_dispatchCallback = cb;
+        dispatchCallback = cb;
+    }
+    foreignInterface.galley_install_js_dispatch(dispatchCallback);
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,iEAAiE;AACjE,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAA2B,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEtF,OAAO,EAAE,eAAe,EAAkB,MAAM,UAAU,CAAC;AAE3D,yEAAyE;AACzE,kEAAkE;AAClE,IAAI,kBAAkB,GAAY,IAAI,CAAC;AACvC,IAAI,gBAAgB,GAAY,IAAI,CAAC;AACrC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;AACvC,IAAI,aAAa,GAAG,KAAK,CAAC;AAE1B,SAAS,eAAe,CAAC,IAAY;IACnC,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,eAAe,CAAC,gBAA2B;IAClD,IAAI,cAAc,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa;QAAE,OAAO;IACzD,aAAa,GAAG,IAAI,CAAC;IACrB,MAAM,aAAa,GAAG,CAAC,UAAkB,EAAW,EAAE;QACpD,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,CAA4B,CAAC;YACpE,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;gBACzD,IAAI,OAAO,KAAK,KAAK,UAAU,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;oBAAE,SAAS;gBACpE,OAAO,GAAG,IAAI,CAAC;gBACf,MAAM;YACR,CAAC;YACD,IAAI,OAAO;gBAAE,OAAO,iBAAiB,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;YACxD,MAAM,aAAa,GAAI,YAAwC,CAAC,OAEnD,CAAC;YACd,IAAI,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;gBACvD,OAAO,iBAAiB,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;QACV,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,sEAAsE;IACtE,iEAAiE;IACjE,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACtC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,aAAa,SAAS,EAAE,CAAC,CAAC;YAAE,OAAO;IAChF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,gBAA2B,EAAE,IAAa;IAC1E,+FAA+F;IAC/F,eAAe,CAAC,gBAAgB,CAAC,CAAC;IAClC,MAAM,MAAM,GACV,gBAAgB,CAAC,6BAA6B,KAAK,IAAI;QACvD,OAAO,IAAI,CAAC,cAAc,KAAK,UAAU;QACzC,IAAI,CAAC,cAAc,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,IAAI,gBAAgB,CAAC,0BAA0B,KAAK,IAAI,EAAE,CAAC;QACpE,yEAAyE;QACzE,OAAO;IACT,CAAC;IACD,IAAI,YAAY,CAAC,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC;QAAE,OAAO;IACvD,IAAI,MAAM,EAAE,CAAC;QACX,iBAAiB,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,mBAAmB,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;IACD,YAAY,CAAC,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,iBAAiB,CAAC,gBAA2B,EAAE,IAAa;IACnE,IAAI,kBAAkB,KAAK,IAAI,EAAE,CAAC;QAChC,wEAAwE;QACxE,6DAA6D;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;QACtE,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAW,EAAE,OAAgB,EAAE,EAAE;YAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,EAAa,CAAC,CAAC;YACzE,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO;YAC/B,IAAI,QAAQ,GAAW,EAAE,CAAC;YAC1B,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC9C,IAAI,CAAC;oBACH,QAAQ,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAE,OAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAiB,CAAC,CAAC;gBAC3F,CAAC;gBAAC,MAAM,CAAC;oBACP,QAAQ,GAAG,EAAE,CAAC;gBAChB,CAAC;YACH,CAAC;YACD,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1C,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACzB,yEAAyE;QACzE,qDAAqD;QACpD,UAAiD,CAAC,8BAA8B,GAAG,EAAE,CAAC;QACvF,kBAAkB,GAAG,EAAE,CAAC;IAC1B,CAAC;IACD,gBAAgB,CAAC,6BAA8B,CAAC,kBAAkB,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,mBAAmB,CAAC,gBAA2B,EAAE,IAAa;IACrE,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC9B,0EAA0E;QAC1E,4EAA4E;QAC5E,yEAAyE;QACzE,0DAA0D;QAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,4DAA4D,CAAC,CAAC;QACxF,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,OAAgB,EAAE,OAAgB,EAAE,OAAgB,EAAE,EAAE;YACjF,IAAI,IAAY,CAAC;YACjB,IAAI,CAAC;gBACH,mEAAmE;gBACnE,MAAM,MAAM,GAAW,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAE,OAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAiB,CAAC,CAAC;gBACrG,MAAM,MAAM,GAAoB,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAE,OAAkB,CAAC,CAAC,CAAE,OAAkB,CAAC;gBACxG,IAAI,GAAG,eAAe,CAAC,MAAgB,EAAE,MAAyB,CAAC,CAAC;YACtE,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,CAAC,KAAK,CAAC,kDAAkD,EAAE,CAAC,CAAC,CAAC;gBACrE,OAAO;YACT,CAAC;YACD,IAAI,QAAQ,GAAW,EAAE,CAAC;YAC1B,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC9C,IAAI,CAAC;oBACH,QAAQ,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAE,OAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAiB,CAAC,CAAC;gBAC3F,CAAC;gBAAC,MAAM,CAAC;oBACP,QAAQ,GAAG,EAAE,CAAC;gBAChB,CAAC;YACH,CAAC;YACD,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1C,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACzB,yEAAyE;QACzE,qDAAqD;QACpD,UAAiD,CAAC,4BAA4B,GAAG,EAAE,CAAC;QACrF,gBAAgB,GAAG,EAAE,CAAC;IACxB,CAAC;IACD,gBAAgB,CAAC,0BAA2B,CAAC,gBAAgB,CAAC,CAAC;AACjE,CAAC"}

package/dist/ffi.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Node adapter for the Galley JavaScript bindings: low-level koffi bindings
+ * over `bindings/c/galley.h`, implementing the core `FfiPort`.
+ *
+ * This is the single FFI boundary for the Node runtime (mirroring
+ * `bindings/python/_galley.c` and `bindings/go/assets/wrapper.go.tmpl`).
+ * Library discovery, memory copying, and integer normalization live here;
+ * all session logic lives in `galley-js-core`. No caller touches koffi
+ * directly outside this module and `dispatch.ts`.
+ */
+import type { FfiPort, Handle, SessionCOptions, TreeSnapshot, WalkedStep } from "galley-js-core";
+declare const koffi: typeof import("koffi");
+export type LibraryHandle = ReturnType<typeof koffi.load>;
+export interface GalleyFFI {
+    libPath: string;
+    lib: LibraryHandle;
+    galley_version: () => string;
+    galley_parser_type: () => bigint | number;
+    galley_error_recovery_mode: () => bigint | number;
+    galley_has_ast: () => number;
+    galley_has_procedures: () => number;
+    galley_allows_no_ast_tree_procedures: () => number;
+    galley_source_retention_enabled: () => number;
+    galley_has_position_tracking: () => number;
+    galley_has_input_streaming: () => number;
+    galley_uses_verbatim: () => number;
+    galley_stack_overflow_recovery_available: () => number;
+    galley_symbol_count: () => bigint | number;
+    galley_variable_count: () => bigint | number;
+    galley_status_string: (status: bigint | number) => string | null;
+    galley_symbol_name: (session: bigint, index: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_symbol_is_terminal: (session: bigint, index: bigint | number) => number;
+    galley_variable_name: (session: bigint, index: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_session_create: () => bigint;
+    galley_session_create_ex: (options: unknown) => bigint;
+    galley_session_destroy: (session: bigint) => void;
+    galley_session_set_message_override: (session: bigint, name: string, nameLen: number | bigint, message: string, messageLen: number | bigint) => bigint | number;
+    galley_parse_sentinel: (session: bigint, input: string) => bigint | number;
+    galley_parse: (session: bigint, data: unknown, len: number | bigint) => bigint | number;
+    galley_parse_file: (session: bigint, p: string) => bigint | number;
+    galley_last_position: (session: bigint, outLine: unknown[], outCol: unknown[]) => bigint | number;
+    galley_node_count: (session: bigint) => bigint | number;
+    galley_reserve_nodes: (session: bigint, cap: bigint | number) => bigint | number;
+    galley_node_capacity: (session: bigint) => bigint | number;
+    galley_root_node: (session: bigint) => bigint | number;
+    galley_node_is_valid: (session: bigint, node: bigint | number) => number;
+    galley_node_child_count: (session: bigint, node: bigint | number) => number;
+    galley_node_first_child: (session: bigint, node: bigint | number) => bigint | number;
+    galley_node_last_child: (session: bigint, node: bigint | number) => bigint | number;
+    galley_node_next_sibling: (session: bigint, node: bigint | number) => bigint | number;
+    galley_node_prior_sibling: (session: bigint, node: bigint | number) => bigint | number;
+    galley_node_parent: (session: bigint, node: bigint | number) => bigint | number;
+    galley_walker_create: (session: bigint, node: bigint | number, skipSemanticErrors: number) => bigint;
+    galley_walker_next: (walker: bigint, outNode: unknown[], outDepth: unknown[], outIsSemanticError: unknown[]) => number;
+    galley_walker_skip_children: (walker: bigint) => void;
+    galley_walker_destroy: (walker: bigint) => void;
+    galley_node_symbol_name: (session: bigint, node: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_node_text: (session: bigint, node: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_node_span: (session: bigint, node: bigint | number, outStart: unknown[], outLen: unknown[]) => bigint | number;
+    galley_node_line_column: (session: bigint, node: bigint | number, outLine: unknown[], outCol: unknown[]) => bigint | number;
+    galley_node_variable_index: (session: bigint, node: bigint | number) => bigint | number;
+    galley_tree_snapshot: (session: bigint, outParent: BigUint64Array, outFirstChild: BigUint64Array, outNext: BigUint64Array, outChildCount: Uint32Array, outVariable: BigInt64Array, outSpanStart: BigUint64Array, outSpanLen: BigUint64Array, capacity: bigint | number) => bigint | number;
+    galley_has_diagnostic: (session: bigint) => number;
+    galley_diagnostic_kind: (session: bigint) => bigint | number;
+    galley_diagnostic_message: (session: bigint, out: unknown[]) => bigint | number;
+    galley_diagnostic_message_ansi: (session: bigint, out: unknown[]) => bigint | number;
+    galley_diagnostic_position: (session: bigint, outLine: unknown[], outCol: unknown[]) => bigint | number;
+    galley_diagnostic_unexpected_token: (session: bigint, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_diagnostic_expected_count: (session: bigint) => bigint | number;
+    galley_diagnostic_expected_at: (session: bigint, index: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_diagnostic_context_count: (session: bigint) => bigint | number;
+    galley_diagnostic_context_at: (session: bigint, index: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_diagnostic_indentation: (session: bigint, outSpaces: unknown[], outWidth: unknown[]) => bigint | number;
+    galley_syntax_error_count: (session: bigint) => bigint | number;
+    galley_semantic_error_count: (session: bigint) => bigint | number;
+    galley_diagnostic_semantic: (session: bigint, outVariable: unknown[], outVariableLen: unknown[], outMessage: unknown[], outMessageLen: unknown[]) => bigint | number;
+    galley_recorded_semantic: (session: bigint, diagIndex: bigint | number, outVariable: unknown[], outVariableLen: unknown[], outMessage: unknown[], outMessageLen: unknown[]) => bigint | number;
+    galley_diagnostic_recovery_kind: (session: bigint) => bigint | number;
+    galley_diagnostic_recovery_terminal: (session: bigint, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_diagnostic_recovery_resume: (session: bigint, out: unknown[]) => bigint | number;
+    galley_diagnostic_recovery_lhs_variable: (session: bigint, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_diagnostic_recovery_production: (session: bigint, outVar: unknown[], outLen: unknown[], outIndex: unknown[]) => bigint | number;
+    galley_diagnostic_recovery_occurrence: (session: bigint, outParent: unknown[], outParentLen: unknown[], outRhs: unknown[], outSym: unknown[], outVar: unknown[], outVarLen: unknown[]) => bigint | number;
+    galley_recorded_diagnostic_count: (session: bigint) => bigint | number;
+    galley_recorded_diagnostic_kind: (session: bigint, idx: bigint | number) => bigint | number;
+    galley_recorded_diagnostic_position: (session: bigint, idx: bigint | number, outLine: unknown[], outCol: unknown[]) => bigint | number;
+    galley_recorded_unexpected_token: (session: bigint, idx: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_recorded_diagnostic_message: (session: bigint, idx: bigint | number, out: unknown[]) => bigint | number;
+    galley_recorded_indentation: (session: bigint, idx: bigint | number, outSpaces: unknown[], outWidth: unknown[]) => bigint | number;
+    galley_recorded_expected_count: (session: bigint, idx: bigint | number) => bigint | number;
+    galley_recorded_expected_token: (session: bigint, idx: bigint | number, tokenIdx: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_recorded_context_count: (session: bigint, idx: bigint | number) => bigint | number;
+    galley_recorded_context_name: (session: bigint, idx: bigint | number, ctxIdx: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_recorded_recovery_kind: (session: bigint, idx: bigint | number) => bigint | number;
+    galley_recorded_recovery_terminal: (session: bigint, idx: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_recorded_recovery_resume: (session: bigint, idx: bigint | number, out: unknown[]) => bigint | number;
+    galley_recorded_recovery_lhs_variable: (session: bigint, idx: bigint | number, outData: unknown[], outLen: unknown[]) => bigint | number;
+    galley_recorded_recovery_production: (session: bigint, idx: bigint | number, outVar: unknown[], outLen: unknown[], outIdx: unknown[]) => bigint | number;
+    galley_recorded_recovery_occurrence: (session: bigint, idx: bigint | number, outParent: unknown[], outParentLen: unknown[], outRhs: unknown[], outSym: unknown[], outVar: unknown[], outVarLen: unknown[]) => bigint | number;
+    galley_tree_append_children: (session: bigint, parent: bigint | number, first: bigint | number) => bigint | number;
+    galley_tree_insert_before: (session: bigint, target: bigint | number, first: bigint | number) => bigint | number;
+    galley_tree_insert_after: (session: bigint, target: bigint | number, first: bigint | number) => bigint | number;
+    galley_tree_remove_siblings: (session: bigint, node: bigint | number, count: number | bigint, outHead: unknown[]) => bigint | number;
+    galley_tree_remove_self: (session: bigint, node: bigint | number, outHead: unknown[]) => bigint | number;
+    galley_tree_promote_children_over_wrapper: (session: bigint, wrapper: bigint | number, outHead: unknown[]) => bigint | number;
+    galley_tree_clean_children: (session: bigint, node: bigint | number, outHead: unknown[]) => bigint | number;
+    galley_tree_unlink_wrapper: (session: bigint, wrapper: bigint | number) => bigint | number;
+    galley_tree_insert_children_at: (session: bigint, parent: bigint | number, index: number | bigint, first: bigint | number) => bigint | number;
+    galley_tree_remove_children_at: (session: bigint, parent: bigint | number, index: number | bigint, count: number | bigint, outHead: unknown[]) => bigint | number;
+    galley_install_js_dispatch_id: ((target: unknown) => void) | null;
+    galley_install_js_dispatch: ((target: unknown) => void) | null;
+    galley_js_procedure_count: (() => number | bigint) | null;
+    galley_js_procedure_name_ptr: ((index: number) => bigint) | null;
+    galley_js_procedure_name_len: ((index: number) => number | bigint) | null;
+    galley_js_procedure_enable: ((name: string, nameLen: number | bigint) => number | bigint) | null;
+    galley_js_procedure_clear: (() => void) | null;
+    galley_procedure_session: (args: bigint) => bigint;
+    galley_procedure_current_node: (args: bigint) => bigint;
+    galley_procedure_set_current_node: (args: bigint, node: bigint | number) => void;
+    galley_procedure_drop_self: (args: bigint) => bigint | number;
+    galley_procedure_drop_children: (args: bigint) => bigint | number;
+    galley_procedure_drop_if_empty: (args: bigint) => bigint | number;
+    galley_procedure_replace_with_children: (args: bigint) => bigint | number;
+    galley_procedure_context_line: (args: bigint) => number;
+    galley_procedure_context_column: (args: bigint) => number;
+    galley_procedure_report_semantic_error: (args: bigint, message: string, messageLen: number | bigint) => bigint | number;
+    GalleyCOptions: ReturnType<typeof koffi.struct>;
+}
+export declare function libFileName(base?: string): string;
+export declare function findLibrary(explicit?: string): string;
+export declare function loadLibrary(explicitPath?: string): GalleyFFI;
+export declare function toBigInt(v: bigint | number): bigint;
+export declare function isOk(status: bigint | number): boolean;
+export declare function toNumber(v: bigint | number): number;
+/** Copy (ptr,len) into Uint8Array owning its bytes. */
+export declare function copyBytes(ptr: bigint, len: bigint | number): Uint8Array;
+export declare function copyStringBytes(ptr: bigint, len: bigint | number): string;
+/**
+ * Node's {@link FfiPort}: normalizes koffi's `bigint | number` unions and
+ * `_Out_` arrays into the structured values the core expects. All memory
+ * copying happens here; the core only sees owned bytes.
+ */
+export declare class NodePort implements FfiPort {
+    #private;
+    readonly ffi: GalleyFFI;
+    readonly libraryPath: string;
+    constructor(ffi: GalleyFFI);
+    version(): string;
+    parserType(): number;
+    errorRecoveryMode(): number;
+    hasAst(): boolean;
+    hasProcedures(): boolean;
+    allowsNoAstTreeProcedures(): boolean;
+    sourceRetentionEnabled(): boolean;
+    hasPositionTracking(): boolean;
+    hasInputStreaming(): boolean;
+    usesVerbatim(): boolean;
+    stackOverflowRecoveryAvailable(): boolean;
+    symbolCount(): number;
+    variableCount(): number;
+    statusString(status: number): string | null;
+    createSession(options: SessionCOptions | null): Handle;
+    destroySession(handle: Handle): void;
+    setMessageOverride(handle: Handle, name: Uint8Array, message: Uint8Array): number;
+    parse(handle: Handle, data: Uint8Array): number;
+    parseFile(handle: Handle, filePath: string): number;
+    lastPosition(handle: Handle): [number, number] | null;
+    nodeCount(handle: Handle): number;
+    reserveNodes(handle: Handle, capacity: bigint): number;
+    nodeCapacity(handle: Handle): number;
+    rootNode(handle: Handle): bigint;
+    nodeValid(handle: Handle, node: bigint): boolean;
+    childCount(handle: Handle, node: bigint): number;
+    firstChild(handle: Handle, node: bigint): bigint;
+    lastChild(handle: Handle, node: bigint): bigint;
+    nextSibling(handle: Handle, node: bigint): bigint;
+    priorSibling(handle: Handle, node: bigint): bigint;
+    parent(handle: Handle, node: bigint): bigint;
+    treeSnapshot(handle: Handle): TreeSnapshot;
+    walkerCreate(handle: Handle, node: bigint, skipSemanticErrors: boolean): Handle | null;
+    walkerNext(walker: Handle): WalkedStep | null;
+    walkerSkipChildren(walker: Handle): void;
+    walkerDestroy(walker: Handle): void;
+    nodeSymbolName(handle: Handle, node: bigint): Uint8Array | null;
+    nodeText(handle: Handle, node: bigint): Uint8Array | null;
+    nodeSpan(handle: Handle, node: bigint): [bigint, bigint] | null;
+    nodeLineColumn(handle: Handle, node: bigint): [number, number] | null;
+    nodeVariableIndex(handle: Handle, node: bigint): number;
+    symbolNameAt(handle: Handle, index: number): Uint8Array | null;
+    symbolIsTerminal(handle: Handle, index: number): boolean;
+    variableNameAt(handle: Handle, index: number): Uint8Array | null;
+    hasDiagnostic(handle: Handle): boolean;
+    diagnosticKind(handle: Handle): number;
+    diagnosticMessage(handle: Handle): string | null;
+    diagnosticMessageAnsi(handle: Handle): string | null;
+    diagnosticPosition(handle: Handle): [number, number] | null;
+    diagnosticUnexpectedToken(handle: Handle): Uint8Array | null;
+    diagnosticExpectedCount(handle: Handle): number;
+    diagnosticExpectedAt(handle: Handle, index: number): Uint8Array | null;
+    diagnosticContextCount(handle: Handle): number;
+    diagnosticContextAt(handle: Handle, index: number): Uint8Array | null;
+    syntaxErrorCount(handle: Handle): number;
+    semanticErrorCount(handle: Handle): number;
+    diagnosticSemantic(handle: Handle): [string, string] | null;
+    diagnosticIndentation(handle: Handle): [number, number] | null;
+    diagnosticRecoveryKind(handle: Handle): number;
+    diagnosticRecoveryTerminal(handle: Handle): Uint8Array | null;
+    diagnosticRecoveryResume(handle: Handle): number | null;
+    diagnosticRecoveryLhsVariable(handle: Handle): string | null;
+    diagnosticRecoveryProduction(handle: Handle): [string, number] | null;
+    diagnosticRecoveryOccurrence(handle: Handle): [string, number, number, string] | null;
+    recordedDiagnosticCount(handle: Handle): number;
+    recordedDiagnosticKind(handle: Handle, diagIndex: number): number;
+    recordedDiagnosticPosition(handle: Handle, diagIndex: number): [number, number] | null;
+    recordedUnexpectedToken(handle: Handle, diagIndex: number): Uint8Array | null;
+    recordedDiagnosticMessage(handle: Handle, diagIndex: number): string | null;
+    recordedIndentation(handle: Handle, diagIndex: number): [number, number] | null;
+    recordedSemantic(handle: Handle, diagIndex: number): [string, string] | null;
+    recordedExpectedCount(handle: Handle, diagIndex: number): number;
+    recordedExpectedToken(handle: Handle, diagIndex: number, tokenIndex: number): Uint8Array | null;
+    recordedContextCount(handle: Handle, diagIndex: number): number;
+    recordedContextName(handle: Handle, diagIndex: number, contextIndex: number): Uint8Array | null;
+    recordedRecoveryKind(handle: Handle, diagIndex: number): number;
+    recordedRecoveryTerminal(handle: Handle, diagIndex: number): Uint8Array | null;
+    recordedRecoveryResume(handle: Handle, diagIndex: number): number | null;
+    recordedRecoveryLhsVariable(handle: Handle, diagIndex: number): string | null;
+    recordedRecoveryProduction(handle: Handle, diagIndex: number): [string, number] | null;
+    recordedRecoveryOccurrence(handle: Handle, diagIndex: number): [string, number, number, string] | null;
+    treeAppendChildren(handle: Handle, parent: bigint, first: bigint): number;
+    treeInsertBefore(handle: Handle, target: bigint, first: bigint): number;
+    treeInsertAfter(handle: Handle, target: bigint, first: bigint): number;
+    treeRemoveSiblings(handle: Handle, node: bigint, count: number): {
+        status: number;
+        head: bigint;
+    };
+    treeRemoveSelf(handle: Handle, node: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treePromoteChildrenOverWrapper(handle: Handle, wrapper: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treeCleanChildren(handle: Handle, node: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treeUnlinkWrapper(handle: Handle, wrapper: bigint): number;
+    treeInsertChildrenAt(handle: Handle, parent: bigint, index: number, first: bigint): number;
+    treeRemoveChildrenAt(handle: Handle, parent: bigint, index: number, count: number): {
+        status: number;
+        head: bigint;
+    };
+    procCurrentNode(args: Handle): bigint;
+    procSetCurrentNode(args: Handle, node: bigint): void;
+    procDropSelf(args: Handle): number;
+    procDropChildren(args: Handle): number;
+    procDropIfEmpty(args: Handle): number;
+    procReplaceWithChildren(args: Handle): number;
+    procContextLine(args: Handle): number;
+    procContextColumn(args: Handle): number;
+    procReportSemanticError(args: Handle, message: Uint8Array): number;
+    syncProcedures(names: string[]): void;
+    procedureNames(): string[];
+}
+/** Port for the library at `explicitPath` (or default discovery), cached per path. */
+export declare function getNodePort(explicitPath?: string): NodePort;
+export {};