@sanbus/galley-core 0.0.1

package/README.md

@@ -0,0 +1,15 @@
+# @sanbus/galley-core
+
+Runtime-neutral core for the Galley JavaScript bindings. Pure TypeScript:
+no `node:`, `bun:`, or `Deno` imports (enforced by `"types": []` in
+`tsconfig.json` — only `TextEncoder`/`TextDecoder`/`console` from standard
+lib). Each runtime ships a thin adapter package implementing `FfiPort`
+(`src/port.ts`) over the same `bindings/c/galley.h` shared library:
+
+- `bindings/js/node` — Node via koffi
+- `bindings/js/bun` — Bun via `bun:ffi`
+- `bindings/js/deno` — Deno via `Deno.dlopen`
+
+`Session`, `Node`, `Walker`, diagnostics, and the procedure registry live
+here exactly once. Adapters own library discovery, memory copying, native
+callback installation, and the public package surface.

package/build/builder.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * Shared parser-artifact builder for the Galley JavaScript bindings.
+ *
+ * Single gate behind every JavaScript build entry: `galley build` in the
+ * universal package, plus `@sanbus/galley-node`, `@sanbus/galley-bun`,
+ * `@sanbus/galley-wasm`, and the Deno `build.ts`. Callers pass targeting
+ * information (library name, wasm or native, platform, install layout);
+ * the gate owns everything else — checkout resolution, CLI bootstrap,
+ * parser generation, procedure-shim selection, and the consumer `zig
+ * build` invocation. No caller builds consumer arguments or picks shim
+ * emitters directly.
+ *
+ * The language directory must contain `ll.grm` and may contain
+ * `config.zig`, procedures, and `ll_error_messages.zig`, mirroring the
+ * other bindings:
+ *
+ * * `procedures.ts` / `procedures.js` — JavaScript hooks
+ *   (`export function reduction_<Variable>(args)` /
+ *   `export function hook_<name>(args)`), dispatched through a generated
+ *   shim shared by the Node, Bun, and Deno adapters (native emitter) or
+ *   through the wasm import (wasm emitter). This is the native-language
+ *   path mirroring Rust's `procedures.rs`.
+ * * `procedures.c` / `procedures.cpp` — legacy C/C++ hooks compiled into
+ *   the artifact, exactly like the C/C++ consumers.
+ * * `ll_error_messages.zig` / `lr_error_messages.zig` — custom syntax-error
+ *   message hooks.
+ *
+ * JavaScript procedures take precedence over C procedures. When neither
+ * exists, the gate still generates the shim as a no-op fallback so the
+ * artifact links (hooks stay no-ops until JavaScript registers them),
+ * mirroring the always-shim model of the other bindings.
+ *
+ * The tool generates the parser (`--emit-metadata`) and builds the artifact
+ * through the generic consumer build directly next to the grammar, so the
+ * adapters can name it through an explicit path or `GALLEY_LIBRARY_PATH`.
+ *
+ * Environment: `ZIG_EXECUTABLE` (default `zig`) and `GALLEY_CHECKOUT`
+ * (required): an existing Galley working tree holding `build.zig`. To
+ * fetch a checkout for convenience, use
+ * `examples/scripts/fetch-galley.sh` — that cache is an examples-only
+ * convenience, not part of the bindings.
+ */
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { emitJsProcedureShim, emitJsProcedureShimWasm } from "./shim.mjs";
+
+/**
+ * Canonical shared native build: one library serves the Node, Bun, and
+ * Deno adapters (the dispatch symbols are identical across them).
+ */
+export const NATIVE_LIBRARY_BASE = "@sanbus/galley-node";
+/** Canonical wasm build for the wasm adapter and the universal fallback leg. */
+export const WASM_LIBRARY_BASE = "@sanbus/galley-wasm";
+
+const WASM_TARGET = "wasm32-wasi";
+const NATIVE_SHIM_FILE = "procedures_js.zig";
+const WASM_SHIM_FILE = "procedures_wasm.zig";
+const CORE_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function fatal(message) {
+  console.error(`galley-bindings: ${message}`);
+  process.exit(1);
+}
+
+function run(command, argumentList, options = {}) {
+  console.log(`+ ${command} ${argumentList.map((argument) => JSON.stringify(argument)).join(" ")}`);
+  const result = spawnSync(command, argumentList, { stdio: "inherit", ...options });
+  if (result.error) fatal(`executable not found: ${command} (${result.error.message})`);
+  if (result.status !== 0) fatal(`command failed: ${command} ${argumentList.join(" ")} (exit ${result.status})`);
+}
+
+function capture(command, argumentList) {
+  const result = spawnSync(command, argumentList, { encoding: "utf-8" });
+  if (result.error) fatal(`failed to probe ${command}: ${result.error.message}`);
+  if (result.status !== 0) fatal(`command failed: ${command} ${argumentList.join(" ")}`);
+  return result.stdout ?? "";
+}
+
+function zigExecutable() {
+  return process.env.ZIG_EXECUTABLE ?? "zig";
+}
+
+/** The checkout `GALLEY_CHECKOUT` names, or a loud error. No guessing. */
+export function resolveGalleyCheckout() {
+  const checkout = process.env.GALLEY_CHECKOUT;
+  if (!checkout) {
+    fatal("GALLEY_CHECKOUT is not set; point it at a Galley checkout (examples/scripts/fetch-galley.sh can fetch one)");
+  }
+  if (!fs.existsSync(path.join(checkout, "build.zig"))) {
+    fatal(`GALLEY_CHECKOUT=${checkout} is not a Galley repository checkout (no build.zig)`);
+  }
+  return path.resolve(checkout);
+}
+
+/**
+ * Confirm the owning adapter is installed and built. Whatever the install
+ * layout (symlinked `file:` package or `--install-links` copy), the
+ * runtime dependency must resolve from the owning directory the same way
+ * the built output loads it. Say so loudly instead of running a package
+ * manager behind your back. Pass `bindingsDirectory: null` to skip (the
+ * Deno wrapper runs from source with no install step).
+ */
+export function ensureBindingsInstalled({ bindingsDirectory, dependencyName = null, installCommand = "npm install" }) {
+  const builtIndex = path.join(bindingsDirectory, "dist", "index.js");
+  if (!fs.existsSync(builtIndex)) {
+    fatal(`bindings not built: run npm run build in ${bindingsDirectory} first`);
+  }
+  if (dependencyName !== null) {
+    try {
+      createRequire(path.join(bindingsDirectory, "package.json")).resolve(dependencyName);
+    } catch {
+      fatal(`bindings not installed: run ${installCommand} in ${bindingsDirectory} first`);
+    }
+  }
+}
+
+let cachedArtifactNames = null;
+async function loadArtifactNames() {
+  if (cachedArtifactNames) return cachedArtifactNames;
+  try {
+    cachedArtifactNames = await import("../dist/artifact.js");
+    return cachedArtifactNames;
+  } catch (error) {
+    fatal(`cannot load @sanbus/galley-core dist (${error.message}); run npm run build in ${CORE_DIRECTORY} first`);
+  }
+}
+
+function findJsProceduresFile(languageDirectory) {
+  const candidates = [
+    path.join(languageDirectory, "procedures.ts"),
+    path.join(languageDirectory, "procedures.js"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Build one parser artifact next to the grammar. `wasm` selects the WASI
+ * reactor module (wasm shim, `-Dwasm` target); otherwise a native shared
+ * library (native shim). `platform` names the host for the native filename
+ * (`process.platform` under Node/Bun, `Deno.build.os` under Deno — both
+ * spellings map through the shared mapping). Returns the built path.
+ *
+ * `artifactFileName` / `wasmArtifactFileName` are the shared mapping from
+ * `@sanbus/galley-core`. Node-family wrappers omit them and the gate loads the
+ * built dist (their preflight guarantees it exists); the Deno wrapper
+ * passes them from core sources, which Deno consumes directly without
+ * ever building dist.
+ *
+ * @param {object} options
+ * @param {string} options.languageDirectory
+ * @param {string} options.libraryName
+ * @param {boolean} [options.wasm]
+ * @param {string} [options.platform]
+ * @param {string|null} [options.bindingsDirectory]
+ * @param {string|null} [options.dependencyName]
+ * @param {string} [options.installCommand]
+ * @param {boolean} [options.posixOnly]
+ * @param {Function|null} [options.artifactFileName]
+ * @param {Function|null} [options.wasmArtifactFileName]
+ * @returns {Promise<string>}
+ */
+export async function buildParserArtifact({
+  languageDirectory,
+  libraryName,
+  wasm = false,
+  platform = process.platform,
+  bindingsDirectory = null,
+  dependencyName = null,
+  installCommand = "npm install",
+  posixOnly = true,
+  artifactFileName = null,
+  wasmArtifactFileName = null,
+}) {
+  if (!languageDirectory) fatal("no language directory given");
+  if (!libraryName) fatal("no library name given");
+  if (posixOnly && (platform === "win32" || platform === "windows")) {
+    fatal("the JavaScript bindings target POSIX platforms");
+  }
+  if (bindingsDirectory !== null) {
+    ensureBindingsInstalled({ bindingsDirectory, dependencyName, installCommand });
+  }
+
+  const names =
+    artifactFileName && wasmArtifactFileName
+      ? { artifactFileName, wasmArtifactFileName }
+      : await loadArtifactNames();
+  const outputFileName = wasm ? names.wasmArtifactFileName(libraryName) : names.artifactFileName(libraryName, platform);
+
+  const languageDir = path.resolve(languageDirectory);
+  if (!fs.existsSync(path.join(languageDir, "ll.grm"))) fatal(`${languageDir} does not contain ll.grm`);
+
+  const galleySource = resolveGalleyCheckout();
+  const cli = path.join(galleySource, "zig-out", "bin", "galley");
+  if (!fs.existsSync(cli)) {
+    run(zigExecutable(), ["build", "-Doptimize=ReleaseFast", "install"], { cwd: galleySource });
+  }
+
+  const help = capture(cli, ["--help"]);
+  if (!help.includes("--emit-metadata")) {
+    fatal(
+      `the Galley at ${galleySource} is too old for the bindings workflow (no --emit-metadata support); update the checkout`,
+    );
+  }
+
+  run(cli, ["--emit-metadata", languageDir]);
+
+  // One library embeds one parser; the consumer build locates the file
+  // generation produced from `-Dlanguage-dir` and infers the family from
+  // the filename.
+  const jsProceduresFile = findJsProceduresFile(languageDir);
+  let proceduresZigSource = null;
+  let proceduresCSource = null;
+  const hasCProcedures =
+    fs.existsSync(path.join(languageDir, "procedures.c")) ||
+    fs.existsSync(path.join(languageDir, "procedures.cpp"));
+  // The wasm shim lives next to the native one under its own name so both
+  // builds can share one language directory.
+  const shimPath = path.join(languageDir, wasm ? WASM_SHIM_FILE : NATIVE_SHIM_FILE);
+  const emitShim = wasm ? emitJsProcedureShimWasm : emitJsProcedureShim;
+  if (jsProceduresFile !== null) {
+    if (hasCProcedures) {
+      console.error(`galley-bindings: both JS (${jsProceduresFile}) and C procedures found — using JS`);
+    }
+    console.error(`galley-bindings: using JS procedures from ${jsProceduresFile}`);
+    emitShim(path.join(languageDir, "metadata.json"), shimPath);
+    proceduresZigSource = shimPath;
+  } else if (hasCProcedures) {
+    if (fs.existsSync(path.join(languageDir, "procedures.zig"))) {
+      proceduresZigSource = path.join(languageDir, "procedures.zig");
+    }
+    if (fs.existsSync(path.join(languageDir, "procedures.c"))) {
+      proceduresCSource = path.join(languageDir, "procedures.c");
+    } else if (fs.existsSync(path.join(languageDir, "procedures.cpp"))) {
+      proceduresCSource = path.join(languageDir, "procedures.cpp");
+    }
+  } else if (fs.existsSync(path.join(languageDir, "procedures.zig"))) {
+    emitShim(path.join(languageDir, "metadata.json"), shimPath);
+    proceduresZigSource = shimPath;
+  }
+
+  const consumerArguments = [
+    "build",
+    "--build-file",
+    path.join(galleySource, "bindings/c/consumer/build.zig"),
+    `-Dlanguage-dir=${languageDir}`,
+    `-Dlib-name=${libraryName}`,
+    ...(wasm ? [`-Dtarget=${WASM_TARGET}`, "-Dwasm"] : []),
+    `-Doutput=${outputFileName}`,
+    "-Doptimize=ReleaseFast",
+    "--prefix",
+    languageDir,
+    "install",
+  ];
+  if (proceduresZigSource !== null) {
+    consumerArguments.splice(consumerArguments.length - 1, 0, `-Dprocedures-zig-source=${proceduresZigSource}`);
+  }
+  if (proceduresCSource !== null) {
+    consumerArguments.splice(consumerArguments.length - 1, 0, `-Dprocedures-c-source=${proceduresCSource}`);
+  }
+  // `config.zig` and `{ll,lr}_error_messages.zig` are inferred by the
+  // consumer build from the parser location.
+  run(zigExecutable(), consumerArguments, { cwd: galleySource });
+
+  const destination = path.join(languageDir, outputFileName);
+  if (!fs.existsSync(destination)) fatal(`expected library not found at ${destination}`);
+  console.log(`galley-bindings: built ${destination}; import from ${languageDir} (or set GALLEY_LIBRARY_PATH)`);
+  return destination;
+}

package/build/fixture.mjs

@@ -0,0 +1,85 @@
+/**
+ * Shared test-fixture builder for the Galley JavaScript bindings.
+ *
+ * One implementation behind every JS binding suite (node, bun, deno, wasm,
+ * universal): each test resolves its parser artifact through
+ * `ensureTestLibrary` instead of borrowing a user-facing example build.
+ * The fixture grammar (`bindings/js/test-fixture`, verbatim keyvalue
+ * sources) is copied to a stable per-scope workdir under the system temp
+ * directory and built there with the adapter's own builder, so test runs
+ * never read or write `examples/`.
+ *
+ * - `GALLEY_LIBRARY_PATH`, when set, wins outright (explicit user artifact,
+ *   no build). Otherwise the fixture is built and its path returned.
+ * - `GALLEY_CHECKOUT` must name the Galley checkout to build against
+ *   (CI sets it). Unset is a loud error, never a guess.
+ * - The workdir path is stable per `scope`, so the builders' content-hash
+ *   caches and zig's incremental cache stay warm across runs.
+ * - Builder output is captured and shown only on failure.
+ */
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.resolve(HERE, "..", "..", "test-fixture");
+const FIXTURE_FILES = ["ll.grm", "config.zig", "procedures.zig", "procedures.ts"];
+
+/** The checkout GALLEY_CHECKOUT names, or a loud error. No guessing. */
+function requireGalleyCheckout() {
+  const checkout = process.env.GALLEY_CHECKOUT;
+  if (!checkout) {
+    throw new Error(
+      "galley test fixture: set GALLEY_CHECKOUT to a Galley checkout (must contain build.zig)",
+    );
+  }
+  return checkout;
+}
+
+/**
+ * Return the parser artifact at `GALLEY_LIBRARY_PATH`, or build the shared
+ * fixture with `buildCommand` (argv prefix, workdir appended) and return
+ * `<workdir>/<libFileName>`. Throws loudly when the build fails.
+ */
+export function ensureTestLibrary({ buildCommand, libFileName, scope }) {
+  if (process.env.GALLEY_LIBRARY_PATH) return process.env.GALLEY_LIBRARY_PATH;
+  if (!Array.isArray(buildCommand) || buildCommand.length === 0) {
+    throw new Error("galley test fixture: buildCommand must be a non-empty argv array");
+  }
+  if (!libFileName || !scope) {
+    throw new Error("galley test fixture: libFileName and scope are required");
+  }
+  const workDir = path.join(os.tmpdir(), "galley-js-test", scope);
+  fs.mkdirSync(workDir, { recursive: true });
+  for (const file of FIXTURE_FILES) {
+    fs.copyFileSync(path.join(FIXTURE_DIR, file), path.join(workDir, file));
+  }
+  requireGalleyCheckout();
+  const [command, ...prefix] = buildCommand;
+  const built = spawnSync(command, [...prefix, workDir], { encoding: "utf-8" });
+  if (built.error) {
+    throw new Error(`galley test fixture: cannot run ${command}: ${built.error.message}`);
+  }
+  // Deno's node:child_process may return a degenerate result instead of
+  // throwing (e.g. spawning without --allow-run): fail loudly here rather
+  // than printing "exit undefined" below.
+  if (typeof built.status !== "number") {
+    throw new Error(
+      `galley test fixture: no exit status from ${command}; ` +
+        "under Deno the test command needs --allow-run",
+    );
+  }
+  if (built.status !== 0) {
+    throw new Error(
+      `galley test fixture: build failed for ${workDir} (exit ${built.status})\n${built.stdout ?? ""}${built.stderr ?? ""}`,
+    );
+  }
+  const libPath = path.join(workDir, libFileName);
+  if (!fs.existsSync(libPath)) {
+    throw new Error(`galley test fixture: expected library not found at ${libPath}`);
+  }
+  return libPath;
+}

package/build/shim.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * Shared procedure-shim generator for the Galley JavaScript bindings.
+ *
+ * Each adapter build script (`bindings/js/<runtime>/build.mjs`) imports
+ * `emitJsProcedureShim` to turn the generator's `procedures` hook list
+ * (metadata.json) into a dispatch shim: every hook forwards its integer ID
+ * (index into the hook list) through one JS callback installed via
+ * `galley_install_js_dispatch_id`. Only hooks the host enabled via
+ * `galley_js_procedure_enable` cross into the host; unenabled slots return
+ * after one boolean check (selective dispatch). The host resolves IDs to
+ * names once via `galley_js_procedure_count` /
+ * `galley_js_procedure_name_ptr` / `galley_js_procedure_name_len`, so the
+ * hot path copies and decodes no strings. The symbols are shared across
+ * the Node, Bun, and Deno adapters — one library build serves any of them.
+ * The generator owns the hook list; this module renders it.
+ */
+
+import * as fs from "node:fs";
+
+export const INSTALL_SYMBOL = "galley_install_js_dispatch_id";
+
+const PREAMBLE = [
+  "const std = @import(\"std\");",
+  'const root = @import("galley");',
+  "pub const Payload = struct {};",
+  "",
+];
+
+export function readProcedureHooks(metadataPath) {
+  let metadata;
+  try {
+    metadata = fs.readFileSync(metadataPath, "utf-8");
+  } catch (e) {
+    throw new Error(`failed to read ${metadataPath}: ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(metadata);
+  } catch (e) {
+    throw new Error(`failed to parse ${metadataPath}: ${e.message}`);
+  }
+  if (!parsed || !Array.isArray(parsed.procedures) || parsed.procedures.length === 0) {
+    throw new Error(`${metadataPath} has no procedure hook list; update the Galley checkout`);
+  }
+  return parsed.procedures;
+}
+
+export function emitJsProcedureShim(metadataPath, outputPath) {
+  const hooks = readProcedureHooks(metadataPath);
+
+  const builder = [];
+  builder.push("// Generated by galley-js bindings; DO NOT EDIT.");
+  builder.push("// Procedure hooks dispatch through a JS callback registered");
+  builder.push("// by the host runtime (Node, Bun, or Deno); only enabled hooks cross,");
+  builder.push("// each carrying its integer hook ID (no strings on the hot path).");
+  for (const line of PREAMBLE) builder.push(line);
+  builder.push(
+    "var js_dispatch_target: ?*const fn (u32, ?*anyopaque) callconv(.c) void = null;",
+  );
+  for (const name of hooks) {
+    builder.push(`var js_enabled_${name}: bool = false;`);
+  }
+  builder.push("");
+  builder.push("const procedure_names = [_][]const u8{");
+  for (const name of hooks) {
+    builder.push(`    "${name}",`);
+  }
+  builder.push("};");
+  builder.push("");
+  builder.push("fn dispatch(comptime id: u32, args: *root.data_structures.ProcedureArguments) void {");
+  builder.push("    if (js_dispatch_target) |target| {");
+  builder.push("        target(id, @ptrCast(args));");
+  builder.push("    }");
+  builder.push("}");
+  builder.push("");
+  hooks.forEach((name, id) => {
+    builder.push(`pub fn ${name}(args: *root.data_structures.ProcedureArguments) void {`);
+    builder.push(`    if (!js_enabled_${name}) return;`);
+    builder.push(`    dispatch(${id}, args);`);
+    builder.push("}");
+    builder.push("");
+  });
+  builder.push("const procedure_slots = [_]struct { name: []const u8, enabled: *bool }{");
+  for (const name of hooks) {
+    builder.push(`    .{ .name = "${name}", .enabled = &js_enabled_${name} },`);
+  }
+  builder.push("};");
+  builder.push("");
+  builder.push(
+    `export fn ${INSTALL_SYMBOL}(target: *const fn (u32, ?*anyopaque) callconv(.c) void) void {`,
+  );
+  builder.push("    js_dispatch_target = target;");
+  builder.push("}");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_count() u32 {");
+  builder.push("    return procedure_names.len;");
+  builder.push("}");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_name_ptr(index: u32) ?[*]const u8 {");
+  builder.push("    if (index >= procedure_names.len) return null;");
+  builder.push("    return procedure_names[index].ptr;");
+  builder.push("}");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_name_len(index: u32) usize {");
+  builder.push("    if (index >= procedure_names.len) return 0;");
+  builder.push("    return procedure_names[index].len;");
+  builder.push("}");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_enable(name_ptr: [*]const u8, name_len: usize) c_int {");
+  builder.push("    const name = name_ptr[0..name_len];");
+  builder.push("    inline for (&procedure_slots) |*slot| {");
+  builder.push("        if (std.mem.eql(u8, slot.name, name)) {");
+  builder.push("            slot.enabled.* = true;");
+  builder.push("            return 1;");
+  builder.push("        }");
+  builder.push("    }");
+  builder.push("    return 0;");
+  builder.push("}");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_clear() void {");
+  builder.push("    inline for (&procedure_slots) |*slot| {");
+  builder.push("        slot.enabled.* = false;");
+  builder.push("    }");
+  builder.push("}");
+  builder.push("");
+  fs.writeFileSync(outputPath, builder.join("\n"), "utf-8");
+}
+
+/**
+ * WebAssembly procedure-shim variant for `bindings/js/wasm`.
+ *
+ * Same hook set as {@link emitJsProcedureShim} (the generator's
+ * `procedures` list), but each hook forwards its integer ID through an
+ * imported host function instead of an installed function pointer: wasm
+ * modules cannot receive raw host addresses, so the adapter provides
+ * `galley_js_dispatch_id` in the `env` import object at instantiation. Only
+ * enabled hooks call the import (see `galley_js_procedure_enable`); the
+ * core registry stays the no-op backstop, matching native semantics.
+ */
+export const DISPATCH_IMPORT_MODULE = "env";
+export const DISPATCH_IMPORT_NAME = "galley_js_dispatch_id";
+
+export function emitJsProcedureShimWasm(metadataPath, outputPath) {
+  const hooks = readProcedureHooks(metadataPath);
+  const builder = [];
+  builder.push("// Generated by galley-js bindings; DO NOT EDIT.");
+  builder.push("// Procedure hooks dispatch through the host-provided");
+  builder.push("// galley_js_dispatch_id import (see bindings/js/wasm); only enabled hooks call it,");
+  builder.push("// each carrying its integer hook ID (no strings on the hot path).");
+  builder.push('const std = @import("std");');
+  for (const line of PREAMBLE.slice(1)) builder.push(line);
+  for (const name of hooks) {
+    builder.push(`var js_enabled_${name}: bool = false;`);
+  }
+  builder.push("");
+  builder.push("const procedure_names = [_][]const u8{");
+  for (const name of hooks) {
+    builder.push(`    "${name}",`);
+  }
+  builder.push("};");
+  builder.push("");
+  builder.push(
+    "extern fn galley_js_dispatch_id(hook_id: u32, args: ?*anyopaque) void;",
+  );
+  builder.push("");
+  builder.push("fn dispatch(comptime id: u32, args: *root.data_structures.ProcedureArguments) void {");
+  builder.push("    galley_js_dispatch_id(id, @ptrCast(args));");
+  builder.push("}");
+  builder.push("");
+  hooks.forEach((name, id) => {
+    builder.push(`pub fn ${name}(args: *root.data_structures.ProcedureArguments) void {`);
+    builder.push(`    if (!js_enabled_${name}) return;`);
+    builder.push(`    dispatch(${id}, args);`);
+    builder.push("}");
+    builder.push("");
+  });
+  builder.push("export fn galley_js_procedure_count() u32 {");
+  builder.push("    return procedure_names.len;");
+  builder.push("}");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_name_ptr(index: u32) ?[*]const u8 {");
+  builder.push("    if (index >= procedure_names.len) return null;");
+  builder.push("    return procedure_names[index].ptr;");
+  builder.push("}");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_name_len(index: u32) usize {");
+  builder.push("    if (index >= procedure_names.len) return 0;");
+  builder.push("    return procedure_names[index].len;");
+  builder.push("}");
+  builder.push("");
+  builder.push("const procedure_slots = [_]struct { name: []const u8, enabled: *bool }{");
+  for (const name of hooks) {
+    builder.push(`    .{ .name = "${name}", .enabled = &js_enabled_${name} },`);
+  }
+  builder.push("};");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_enable(name_ptr: [*]const u8, name_len: usize) c_int {");
+  builder.push("    const name = name_ptr[0..name_len];");
+  builder.push("    inline for (&procedure_slots) |*slot| {");
+  builder.push("        if (std.mem.eql(u8, slot.name, name)) {");
+  builder.push("            slot.enabled.* = true;");
+  builder.push("            return 1;");
+  builder.push("        }");
+  builder.push("    }");
+  builder.push("    return 0;");
+  builder.push("}");
+  builder.push("");
+  builder.push("export fn galley_js_procedure_clear() void {");
+  builder.push("    inline for (&procedure_slots) |*slot| {");
+  builder.push("        slot.enabled.* = false;");
+  builder.push("    }");
+  builder.push("}");
+  builder.push("");
+  fs.writeFileSync(outputPath, builder.join("\n"), "utf-8");
+}

package/dist/artifact.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare function artifactFileName(base: string, platform: string): string;
+/**
+ * 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 declare function wasmArtifactFileName(base: string): string;
+/**
+ * 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 declare function resolveArtifact(explicit: string | undefined, host: ArtifactHost): string;

package/dist/artifact.js

@@ -0,0 +1,45 @@
+import { MissingArtifactError } from "./errors.js";
+/**
+ * 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, platform) {
+    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) {
+    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, host) {
+    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;
+}
+//# sourceMappingURL=artifact.js.map

package/dist/artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../src/artifact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAgBnD;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAAgB;IAC7D,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,MAAM,IAAI,QAAQ,CAAC;IACrD,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,GAAG,IAAI,MAAM,CAAC;IACzE,OAAO,MAAM,IAAI,KAAK,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,MAAM,IAAI,OAAO,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,QAA4B,EAAE,IAAkB;IAC9E,MAAM,MAAM,GAAG,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAC9D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,oBAAoB,CAC5B,uEAAuE,EACvE,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,oBAAoB,CAAC,MAAM,QAAQ,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}