@sanbus/galley-core 0.0.1

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@sanbus/galley-core",
+  "version": "0.0.1",
+  "description": "Runtime-neutral core for the Galley JavaScript bindings (Node, Bun, Deno). Pure TypeScript: no node:, bun:, or Deno imports. Each runtime ships a thin adapter implementing FfiPort.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./build/shim.mjs": "./build/shim.mjs",
+    "./build/builder.mjs": "./build/builder.mjs",
+    "./build/fixture.mjs": "./build/fixture.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "build",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}

package/src/artifact.ts

@@ -0,0 +1,62 @@
+import { MissingArtifactError } from "./errors.ts";
+
+/**
+ * Host capabilities artifact resolution needs from each adapter.
+ * Node, Bun, and wasm pass `process.env`, `path.resolve`, and an
+ * `fs.accessSync` probe; Deno passes `Deno.env.get`, the identity
+ * resolver (Deno reports the path it was given), and a `Deno.statSync`
+ * probe. Core stays runtime-neutral: no `node:`, `bun:`, or Deno imports.
+ */
+export interface ArtifactHost {
+  getEnv(name: string): string | undefined;
+  resolvePath(candidate: string): string;
+  existsSync(candidate: string): boolean;
+  buildHint: string;
+}
+
+/**
+ * Shared library filename mapping for every JavaScript adapter.
+ * One library name per platform: `lib<base>.dylib` on macOS, `<base>.dll`
+ * on Windows (no `lib` prefix), `lib<base>.so` elsewhere. The platform
+ * string comes from the host (`process.platform` under Node/Bun, where
+ * Windows reports `win32`; `Deno.build.os`, where it reports `windows`);
+ * both spellings map to the Windows name here so the adapters cannot
+ * diverge. Each adapter keeps a thin `libFileName` wrapper passing its
+ * own base name; the mapping lives here.
+ */
+export function artifactFileName(base: string, platform: string): string {
+  if (platform === "darwin") return `lib${base}.dylib`;
+  if (platform === "win32" || platform === "windows") return `${base}.dll`;
+  return `lib${base}.so`;
+}
+
+/**
+ * Shared wasm artifact filename. WebAssembly modules are platform-neutral:
+ * always `lib<base>.wasm`. The wasm adapter keeps a thin `wasmFileName`
+ * wrapper passing its base name.
+ */
+export function wasmArtifactFileName(base: string): string {
+  return `lib${base}.wasm`;
+}
+
+/**
+ * Shared parser-artifact resolution for every JavaScript adapter.
+ * One place is named up front — an explicit path or GALLEY_LIBRARY_PATH.
+ * Anything else is a loud error, never a search. Each adapter keeps a
+ * thin `findLibrary` wrapper passing its host capabilities and its own
+ * build hint; the decision lives here.
+ */
+export function resolveArtifact(explicit: string | undefined, host: ArtifactHost): string {
+  const chosen = explicit || host.getEnv("GALLEY_LIBRARY_PATH");
+  if (!chosen) {
+    throw new MissingArtifactError(
+      "no parser artifact given; pass libraryPath or set GALLEY_LIBRARY_PATH",
+      host.buildHint,
+    );
+  }
+  const resolved = host.resolvePath(chosen);
+  if (!host.existsSync(resolved)) {
+    throw new MissingArtifactError(`at ${resolved}`, host.buildHint);
+  }
+  return resolved;
+}

package/src/constants.ts

@@ -0,0 +1,47 @@
+/**
+ * Constants mirroring `bindings/c/galley.h` status and kind enumerations.
+ * These are the single source for JavaScript consumers; they must stay
+ * in sync with the C header.
+ */
+
+export const INVALID_NODE = 0xffffffffffffffffn; // 2^64-1
+
+// Status codes (negative = failure)
+export const STATUS_OK = 0;
+export const STATUS_ERROR_NULL_ARGUMENT = -1;
+export const STATUS_ERROR_SYNTAX = -2;
+export const STATUS_ERROR_INDENTATION = -3;
+export const STATUS_ERROR_STACK_OVERFLOW = -4;
+export const STATUS_ERROR_AST_CAPACITY_EXCEEDED = -5;
+export const STATUS_ERROR_UNTERMINATED_RAW_STRING = -6;
+export const STATUS_ERROR_OUT_OF_MEMORY = -7;
+export const STATUS_ERROR_INTERNAL = -8;
+export const STATUS_ERROR_NO_DIAGNOSTIC = -9;
+export const STATUS_ERROR_INVALID_NODE = -10;
+export const STATUS_ERROR_IO = -11;
+export const STATUS_ERROR_SEMANTIC = -12;
+
+// Parser families
+export const PARSER_TYPE_LL = 0;
+export const PARSER_TYPE_LR = 1;
+
+// Recovery modes
+export const RECOVERY_MODE_DISABLED = 0;
+export const RECOVERY_MODE_AUTOMATIC = 1;
+export const RECOVERY_MODE_EXPLICIT = 2;
+
+// Diagnostic kinds
+export const KIND_NONE = 0;
+export const KIND_SYNTAX = 1;
+export const KIND_INDENTATION = 2;
+export const KIND_SEMANTIC = 3;
+
+// Recovery targets
+export const RECOVERY_TARGET_NONE = 0;
+export const RECOVERY_TARGET_LHS_VARIABLE = 1;
+export const RECOVERY_TARGET_PRODUCTION = 2;
+export const RECOVERY_TARGET_OCCURRENCE = 3;
+
+// Resume sides
+export const RESUME_BEFORE = 0;
+export const RESUME_AFTER = 1;

package/src/diagnostic.ts

@@ -0,0 +1,48 @@
+/**
+ * Read-only snapshot of a parse diagnostic.
+ * All `Uint8Array` fields are copies that remain valid after the next parse.
+ */
+
+/**
+ * Display name for the synthetic control-byte terminals (end of input and
+ * the indentation pair), which never occur as user-typable input. Exact
+ * full-token match only; anything else returns null and the caller keeps
+ * its existing rendering.
+ *
+ * Mirrors `tokenDisplayName` in `src/runtime/string.zig` until the general
+ * per-grammar mechanism arrives; keep the two tables in sync.
+ */
+export function displayTokenName(token: Uint8Array): string | null {
+  if (token.length !== 1) return null;
+  switch (token[0]) {
+    case 0x00:
+      return "End of input";
+    case 0x01:
+      return "Indent";
+    case 0x02:
+      return "Dedent";
+    default:
+      return null;
+  }
+}
+
+export interface Diagnostic {
+  kind: number; // KIND_*
+  line: number; // 1-based
+  column: number;
+  message: string; // plain text
+  messageAnsi: string; // with ANSI
+  unexpectedToken: Uint8Array | null; // syntax only
+  expectedTokens: Uint8Array[]; // syntax only
+  context: string[]; // innermost-first variable names, syntax only
+  syntaxErrorCount: number;
+  semanticErrorCount: number;
+  semantic: [string, string] | null; // (variable, message) for semantic errors
+  indentation: [number, number] | null; // (spaces, width) for indentation errors
+  recoveryKind: number | null; // RECOVERY_TARGET_*
+  recoveryTerminal: Uint8Array | null;
+  recoveryResume: number | null; // RESUME_*
+  recoveryLhsVariable: string | null;
+  recoveryProduction: [string, number] | null; // (variable, rhs_index)
+  recoveryOccurrence: [string, number, number, string] | null; // (parent, rhs, symbol, variable)
+}

package/src/errors.ts

@@ -0,0 +1,49 @@
+import type { Diagnostic } from "./diagnostic.ts";
+
+/**
+ * Failure reported by a Galley operation.
+ * Mirrors Python's `galley.Error` (code + diagnostic snapshot).
+ */
+export class GalleyError extends Error {
+  readonly code: number;
+  readonly diagnostic: Diagnostic | null;
+
+  constructor(
+    message: string,
+    code: number,
+    diagnostic: Diagnostic | null = null,
+  ) {
+    super(message);
+    this.name = "GalleyError";
+    this.code = code;
+    this.diagnostic = diagnostic;
+  }
+}
+
+const MISSING_ARTIFACT_CODE = "galley:missing-artifact";
+
+/**
+ * The parser artifact a binding was told to load is not where it was told.
+ * Thrown by every adapter's artifact resolution instead of searching
+ * elsewhere. The universal loader catches exactly this class to try the
+ * next engine; anything else propagates loudly.
+ */
+export class MissingArtifactError extends Error {
+  readonly code = MISSING_ARTIFACT_CODE;
+
+  constructor(detail: string, buildHint: string) {
+    super(`galley: parser artifact not found: ${detail}.\n${buildHint}`);
+    this.name = "MissingArtifactError";
+  }
+
+  /** True for missing-artifact failures even across duplicated installs. */
+  static is(error: unknown): error is MissingArtifactError {
+    if (error instanceof MissingArtifactError) return true;
+    return (
+      typeof error === "object" &&
+      error !== null &&
+      (error as { name?: unknown }).name === "MissingArtifactError" &&
+      (error as { code?: unknown }).code === MISSING_ARTIFACT_CODE
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Galley JavaScript core — runtime-neutral public surface.
+ *
+ * Each adapter package (`@sanbus/galley-node`, `@sanbus/galley-bun`, `@sanbus/galley-deno`)
+ * binds these classes to its {@link FfiPort} and re-exports them.
+ */
+
+import { Session, Walker } from "./session.ts";
+import type { SessionOptions, WalkStep } from "./session.ts";
+import { Node } from "./node.ts";
+import { GalleyError, MissingArtifactError } from "./errors.ts";
+import { resolveArtifact, artifactFileName, wasmArtifactFileName } from "./artifact.ts";
+import type { ArtifactHost } from "./artifact.ts";
+import type { Diagnostic } from "./diagnostic.ts";
+import { displayTokenName } from "./diagnostic.ts";
+import type { FfiPort, Handle, SessionCOptions, TreeSnapshot, WalkedStep, DispatchHandler } from "./port.ts";
+import {
+  installProcedure,
+  installProcedures,
+  clearProcedures,
+  listProcedures,
+  ProcedureArguments,
+  dispatchProcedure,
+  setParsingSession,
+  getParsingSession,
+} from "./procedures.ts";
+import type { HookFn } from "./procedures.ts";
+import { encodeUtf8, decodeUtf8, byteLengthUtf8 } from "./text.ts";
+
+export {
+  Session,
+  Walker,
+  Node,
+  GalleyError,
+  MissingArtifactError,
+  resolveArtifact,
+  artifactFileName,
+  wasmArtifactFileName,
+  displayTokenName,
+  ProcedureArguments,
+  installProcedure,
+  installProcedures,
+  clearProcedures,
+  listProcedures,
+  dispatchProcedure,
+  setParsingSession,
+  getParsingSession,
+  encodeUtf8,
+  decodeUtf8,
+  byteLengthUtf8,
+};
+export type { Diagnostic, WalkStep, SessionOptions, FfiPort, Handle, SessionCOptions, TreeSnapshot, WalkedStep, DispatchHandler, HookFn, ArtifactHost };
+export * from "./constants.ts";

package/src/node.ts

@@ -0,0 +1,154 @@
+import type { Session } from "./session.ts";
+import { decodeUtf8 } from "./text.ts";
+
+/**
+ * Session-bound handle for a node in the non-relocating AST storage.
+ * Mirrors Python's `galley.Node`: keeps a strong reference to its Session
+ * and raises after the session is closed.
+ */
+export class Node {
+  readonly #session: Session;
+  readonly #address: bigint;
+
+  constructor(session: Session, address: bigint | number) {
+    this.#session = session;
+    this.#address = typeof address === "bigint" ? address : BigInt(address);
+  }
+
+  /** Raw address (stable index in the session's node storage). */
+  get address(): bigint {
+    return this.#address;
+  }
+
+  /** Owning session. */
+  get session(): Session {
+    return this.#session;
+  }
+
+  private ensureAlive(): void {
+    if (this.#session.isClosed) {
+      throw new Error("node's session is closed");
+    }
+  }
+
+  /** Tuple of direct children, from first to last (empty when leaf). */
+  children(): Node[] {
+    this.ensureAlive();
+    return this.#session.children(this);
+  }
+
+  /** Text bytes of this node, or null for invalid node. */
+  text(): Uint8Array | null {
+    this.ensureAlive();
+    return this.#session.text(this);
+  }
+
+  /** Symbol name bytes as string, or null for invalid node. Terminal-only nodes → "". */
+  symbolName(): string | null {
+    this.ensureAlive();
+    const bytes = this.#session.symbolNameBytes(this);
+    if (bytes === null) return null;
+    return decodeUtf8(bytes);
+  }
+
+  /** Raw symbol name bytes (Uint8Array) or null. */
+  symbolNameBytes(): Uint8Array | null {
+    this.ensureAlive();
+    return this.#session.symbolNameBytes(this);
+  }
+
+  /** (start, length) byte span, or null. */
+  span(): [bigint, bigint] | null {
+    this.ensureAlive();
+    return this.#session.span(this);
+  }
+
+  /** 1-based (line, column) of first byte, or null. */
+  lineColumn(): [number, number] | null {
+    this.ensureAlive();
+    return this.#session.lineColumn(this);
+  }
+
+  /** Parent node, or null for root. */
+  parent(): Node | null {
+    this.ensureAlive();
+    return this.#session.parent(this);
+  }
+
+  nextSibling(): Node | null {
+    this.ensureAlive();
+    return this.#session.nextSibling(this);
+  }
+
+  priorSibling(): Node | null {
+    this.ensureAlive();
+    return this.#session.priorSibling(this);
+  }
+
+  firstChild(): Node | null {
+    this.ensureAlive();
+    return this.#session.firstChild(this);
+  }
+
+  lastChild(): Node | null {
+    this.ensureAlive();
+    return this.#session.lastChild(this);
+  }
+
+  cleanChildren(): Node | null {
+    this.ensureAlive();
+    return this.#session.cleanChildren(this);
+  }
+
+  appendChildren(chain: Node | bigint): void {
+    this.ensureAlive();
+    this.#session.appendChildren(this, chain);
+  }
+
+  /** Number of direct children. */
+  get length(): number {
+    this.ensureAlive();
+    return this.#session.childCount(this);
+  }
+
+  /** Child at index (negative indices supported). */
+  at(index: number): Node {
+    this.ensureAlive();
+    const count = this.length;
+    let i = index;
+    if (i < 0) i += count;
+    if (i < 0 || i >= count) throw new RangeError(`node index ${index} out of range (0..${count - 1})`);
+    const arr = this.children();
+    return arr[i];
+  }
+
+  *[Symbol.iterator](): Iterator<Node> {
+    this.ensureAlive();
+    for (const child of this.children()) yield child;
+  }
+
+  /** Raw address for `Number(node)` / `BigInt(node)`. */
+  valueOf(): bigint {
+    return this.#address;
+  }
+
+  toString(): string {
+    return `Node(${this.#address.toString()})`;
+  }
+
+  equals(other: unknown): boolean {
+    if (other instanceof Node) {
+      return this.#address === other.#address && this.#session === other.#session;
+    }
+    if (typeof other === "bigint") return this.#address === other;
+    if (typeof other === "number") return this.#address === BigInt(other);
+    return false;
+  }
+
+  // allow `Number(node)` and `+node`
+  [Symbol.toPrimitive](hint: string): bigint | string | number {
+    if (hint === "number") return Number(this.#address);
+    if (hint === "string") return this.toString();
+    return this.#address;
+  }
+}

package/src/port.ts

@@ -0,0 +1,213 @@
+/**
+ * Neutral FFI port: the single seam between the runtime-neutral core
+ * (`session.ts`, `node.ts`, `procedures.ts`) and each runtime adapter
+ * (Node/koffi, Bun/`bun:ffi`, Deno/`Deno.dlopen`).
+ *
+ * The port mirrors `bindings/c/galley.h`, but with structured returns
+ * instead of C out-parameters: adapters own all memory copying (bytes are
+ * already-copied `Uint8Array`s here, valid after the next parse) and all
+ * integer normalization (addresses are `bigint`, counts and statuses are
+ * `number`). Opaque native pointers (sessions, walkers, procedure args)
+ * cross the seam as `Handle` and are never inspected by the core.
+ */
+
+export type Handle = unknown;
+
+/** `GalleyCOptions` fields as plain data; null selects library defaults. */
+export interface SessionCOptions {
+  maxErrors: number;
+  recoveryWindow: number;
+  stackOverflowRecovery: number;
+  syntaxErrorStackDepth: number;
+  verbosity: number;
+  astPreallocationRatio: number;
+  astPreallocationCap: bigint;
+}
+
+/** One pre-order walker step. */
+export interface WalkedStep {
+  node: bigint;
+  depth: number;
+  isSemanticError: boolean;
+}
+
+/**
+ * Flat bulk read of the most recent successful parse, one slot per node
+ * address. `parent` holds `INVALID_NODE` for the root, `firstChild`/`next`
+ * hold `INVALID_NODE` where the link does not exist, `variable` holds -1
+ * for nodes without a variable, and `spanStart`/`spanLen` are byte
+ * offsets into the parsed input. Parent, firstChild, and next alone
+ * describe the whole tree with no further calls.
+ */
+export interface TreeSnapshot {
+  count: number;
+  parent: BigUint64Array;
+  firstChild: BigUint64Array;
+  next: BigUint64Array;
+  childCount: Uint32Array;
+  variable: BigInt64Array;
+  spanStart: BigUint64Array;
+  spanLen: BigUint64Array;
+}
+
+/** Native dispatch callback installed by the adapter; receives a decoded hook name. */
+export type DispatchHandler = (name: string, args: Handle) => void;
+
+export interface FfiPort {
+  // -- module-level queries (mirror galley.h) --------------------------
+  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;
+
+  // -- sessions ---------------------------------------------------------
+  /** Null handle on initialization failure (most commonly allocation failure). */
+  createSession(options: SessionCOptions | null): Handle;
+  destroySession(handle: Handle): void;
+  /** Negative status on failure. */
+  setMessageOverride(handle: Handle, name: Uint8Array, message: Uint8Array): number;
+
+  // -- parsing ----------------------------------------------------------
+  /** Bytes parsed, or a negative status code. */
+  parse(handle: Handle, data: Uint8Array): number;
+  /** Bytes parsed, or a negative status code. */
+  parseFile(handle: Handle, path: string): number;
+  /** End position of the most recent successful parse; null on failure. */
+  lastPosition(handle: Handle): [number, number] | null;
+
+  // -- arena and navigation ----------------------------------------------
+  nodeCount(handle: Handle): number;
+  /** Negative status on failure (e.g. capacity exceeded). */
+  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;
+  /** Flat bulk read of the most recent successful parse (see `TreeSnapshot`). */
+  treeSnapshot(handle: Handle): TreeSnapshot;
+
+  // -- walker ------------------------------------------------------------
+  /** Null without AST construction or on invalid arguments. */
+  walkerCreate(handle: Handle, node: bigint, skipSemanticErrors: boolean): Handle | null;
+  /** Null when the walk is done. */
+  walkerNext(walker: Handle): WalkedStep | null;
+  walkerSkipChildren(walker: Handle): void;
+  walkerDestroy(walker: Handle): void;
+
+  // -- node accessors (null on invalid node) ------------------------------
+  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;
+  /** Raw variable index; -1 when the node has no variable. */
+  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;
+
+  // -- diagnostics ---------------------------------------------------------
+  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;
+  /** (variable, message); null when there is no semantic diagnostic. */
+  diagnosticSemantic(handle: Handle): [string, string] | null;
+  /** (spaces, width); null when not an indentation diagnostic. */
+  diagnosticIndentation(handle: Handle): [number, number] | null;
+
+  // -- recovery, current diagnostic ------------------------------------------
+  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;
+
+  // -- recovery, recorded diagnostics ------------------------------------------
+  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;
+
+  // -- tree editing ----------------------------------------------------------
+  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 };
+
+  // -- procedure hooks (parse-time state) ---------------------------------------
+  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;
+  /** Running semantic-error total, or a negative status code. */
+  procReportSemanticError(args: Handle, message: Uint8Array): number;
+  /**
+   * Enables exactly `names` in the native procedure gates before a parse
+   * (selective dispatch): the adapter clears all gates, then enables each
+   * name. Missing symbols (C-procedure or stale libraries) are no-ops.
+   */
+  syncProcedures(names: string[]): void;
+  /**
+   * Hook names in integer-ID order for the ID dispatch path. Queried once
+   * from the library (`galley_js_procedure_count` /
+   * `galley_js_procedure_name_ptr` / `galley_js_procedure_name_len`) and
+   * cached; empty when the library predates the query exports (C-procedure
+   * or stale libraries use the name-carrying dispatch instead).
+   */
+  procedureNames(): string[];
+}