inillucent 0.1.4 → 0.1.5

package/README.md

@@ -1,102 +1,102 @@
-# inillucent
-
-An embedded SQL database that speaks SQLite's dialect on its own storage, with
-full-text and vector search built in — the job of PostgreSQL + pgvector + an
-embedding server, in one process and one file.
-
-```sh
-npm install -g inillucent
-# or, without installing anything permanently:
-npx inillucent help
-```
-
-No native build step and no postinstall download: the binaries ship as
-per-platform packages that npm installs only where they run, so `npm ci` works
-offline and behind a proxy.
-
-## Four programs
-
-| | |
-|---|---|
-| `inillucent` | the command line: `query`, `exec`, `describe`, `import`, `export`, `search`, and twenty more |
-| `inillucent-shell` | an interactive shell shaped like `sqlite3`, with all 63 of its dot commands |
-| `inillucent-mcp` | the same commands served to an AI agent over MCP |
-| `inillucent-migrate` | builds an inillucent database from a SQLite file |
-
-## From a shell
-
-```sh
-inillucent create app.rdb
-inillucent --db app.rdb exec "CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)"
-inillucent --db app.rdb exec "INSERT INTO notes (body) VALUES (?1)" --params '["hello"]'
-inillucent --db app.rdb query "SELECT * FROM notes"
-inillucent --db app.rdb describe notes
-inillucent help
-```
-
-Exit codes carry meaning: `0` success, `1` failed, `2` a command line nobody
-could act on, and **`3` a construct the engine has not built yet** — so a script
-can branch on "not yet" without matching on a message.
-
-## From Node
-
-```js
-import { query, inillucent } from 'inillucent';
-
-const rows = await query('SELECT id, body FROM notes WHERE id > ?1', {
-  db: 'app.rdb',
-  params: [3],
-});
-// [{ id: 4, body: 'hello' }]
-
-const described = await inillucent('describe', { db: 'app.rdb', table: 'notes' });
-console.log(described.ddl, described.indexes, described.row_count_in_table);
-```
-
-Each call is a process, so this is the right tool for the dozen calls a build
-script or a tool wrapper makes and the wrong one for a loop over a million rows.
-For that, write a binding over the C ABI — the header ships in this package's
-platform dependency under `include/`, and
-[`drivers/README.md`](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/drivers/README.md)
-is written to be followed.
-
-## For an agent
-
-```json
-{
-  "mcpServers": {
-    "inillucent": {
-      "command": "npx",
-      "args": ["-y", "inillucent-mcp", "--db", "app.rdb"]
-    }
-  }
-}
-```
-
-27 tools, generated from the same command table the CLI reads, so the two can
-never drift. `--readonly` refuses every statement that changes something, and
-`--root DIR` refuses every path outside a directory.
-
-## Licence
-
-MIT. Source: <https://github.com/Black-Rainbow-Labs/Inillucent>
-
-## The API
-
-Every method this binding has. The worked example each one appears in is the link; nothing here is
-a summary of a method that does not exist, because
-`cargo test -p inillucent-compat --test documentation` reads this table and fails on a name the
-binding source does not declare.
-
-| what | one line |
-|---|---|
-| `inillucent(command, options)` | run one command of the command line and return its parsed JSON. `options.db` names the file, `options.args` the rest. |
-| `query(sql, options)` | run one `SELECT` and return its rows. `options.params` binds `?1`, `?2`; `options.limit` caps the rows kept. |
-| `resolveBinary(program)` | the path to one of the four programs on this platform, from the platform package npm installed. |
-| `platformPackage()` | the name of the platform package this machine needs, which is what an install failure should name. |
-| `PROGRAMS` | the four programs and what each is for, as an object. |
-
-Every call goes through the command line rather than through the C ABI: the four programs are what
-the platform package ships, and `--output json` is the same object every other binding sees. That
-is why there is no `Connection` here and no transaction - a command is one process, and a
-transaction that spanned two of them would be a transaction nothing held open.
+# inillucent
+
+An embedded SQL database that speaks SQLite's dialect on its own storage, with
+full-text and vector search built in — the job of PostgreSQL + pgvector + an
+embedding server, in one process and one file.
+
+```sh
+npm install -g inillucent
+# or, without installing anything permanently:
+npx inillucent help
+```
+
+No native build step and no postinstall download: the binaries ship as
+per-platform packages that npm installs only where they run, so `npm ci` works
+offline and behind a proxy.
+
+## Four programs
+
+| | |
+|---|---|
+| `inillucent` | the command line: `query`, `exec`, `describe`, `import`, `export`, `search`, and twenty more |
+| `inillucent-shell` | an interactive shell shaped like `sqlite3`, with all 63 of its dot commands |
+| `inillucent-mcp` | the same commands served to an AI agent over MCP |
+| `inillucent-migrate` | builds an inillucent database from a SQLite file |
+
+## From a shell
+
+```sh
+inillucent create app.rdb
+inillucent --db app.rdb exec "CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)"
+inillucent --db app.rdb exec "INSERT INTO notes (body) VALUES (?1)" --params '["hello"]'
+inillucent --db app.rdb query "SELECT * FROM notes"
+inillucent --db app.rdb describe notes
+inillucent help
+```
+
+Exit codes carry meaning: `0` success, `1` failed, `2` a command line nobody
+could act on, and **`3` a construct the engine has not built yet** — so a script
+can branch on "not yet" without matching on a message.
+
+## From Node
+
+```js
+import { query, inillucent } from 'inillucent';
+
+const rows = await query('SELECT id, body FROM notes WHERE id > ?1', {
+  db: 'app.rdb',
+  params: [3],
+});
+// [{ id: 4, body: 'hello' }]
+
+const described = await inillucent('describe', { db: 'app.rdb', table: 'notes' });
+console.log(described.ddl, described.indexes, described.row_count_in_table);
+```
+
+Each call is a process, so this is the right tool for the dozen calls a build
+script or a tool wrapper makes and the wrong one for a loop over a million rows.
+For that, write a binding over the C ABI — the header ships in this package's
+platform dependency under `include/`, and
+[`drivers/README.md`](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/drivers/README.md)
+is written to be followed.
+
+## For an agent
+
+```json
+{
+  "mcpServers": {
+    "inillucent": {
+      "command": "npx",
+      "args": ["-y", "inillucent-mcp", "--db", "app.rdb"]
+    }
+  }
+}
+```
+
+27 tools, generated from the same command table the CLI reads, so the two can
+never drift. `--readonly` refuses every statement that changes something, and
+`--root DIR` refuses every path outside a directory.
+
+## Licence
+
+MIT. Source: <https://github.com/Black-Rainbow-Labs/Inillucent>
+
+## The API
+
+Every method this binding has. The worked example each one appears in is the link; nothing here is
+a summary of a method that does not exist, because
+`cargo test -p inillucent-compat --test documentation` reads this table and fails on a name the
+binding source does not declare.
+
+| what | one line |
+|---|---|
+| `inillucent(command, options)` | run one command of the command line and return its parsed JSON. `options.db` names the file, `options.args` the rest. |
+| `query(sql, options)` | run one `SELECT` and return its rows. `options.params` binds `?1`, `?2`; `options.limit` caps the rows kept. |
+| `resolveBinary(program)` | the path to one of the four programs on this platform, from the platform package npm installed. |
+| `platformPackage()` | the name of the platform package this machine needs, which is what an install failure should name. |
+| `PROGRAMS` | the four programs and what each is for, as an object. |
+
+Every call goes through the command line rather than through the C ABI: the four programs are what
+the platform package ships, and `--output json` is the same object every other binding sees. That
+is why there is no `Connection` here and no transaction - a command is one process, and a
+transaction that spanned two of them would be a transaction nothing held open.

package/bin/inillucent-mcp.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-// The `inillucent-mcp` shim: resolve the platform binary and become it.
-//
-// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
-// execve and this has to work on Windows. The child's exit code and its signal
-// are both passed back up: a wrapper that always exited 0 would break every
-// script that branches on the exit code, and inillucent's exit codes carry
-// meaning - 3 is "the engine has not built that".
-import { spawn } from 'node:child_process';
-import { resolveBinary } from '../resolve.mjs';
-
-let binary;
-try {
-  binary = resolveBinary('inillucent-mcp');
-} catch (why) {
-  process.stderr.write(String(why.message ?? why) + '\n');
-  process.exit(1);
-}
-
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
-child.on('error', (why) => {
-  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
-  process.exit(1);
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    // Re-raise it on ourselves so a shell sees the same thing it would have
-    // seen from the real program, rather than a plain exit.
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// The `inillucent-mcp` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-mcp');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent-migrate.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-// The `inillucent-migrate` shim: resolve the platform binary and become it.
-//
-// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
-// execve and this has to work on Windows. The child's exit code and its signal
-// are both passed back up: a wrapper that always exited 0 would break every
-// script that branches on the exit code, and inillucent's exit codes carry
-// meaning - 3 is "the engine has not built that".
-import { spawn } from 'node:child_process';
-import { resolveBinary } from '../resolve.mjs';
-
-let binary;
-try {
-  binary = resolveBinary('inillucent-migrate');
-} catch (why) {
-  process.stderr.write(String(why.message ?? why) + '\n');
-  process.exit(1);
-}
-
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
-child.on('error', (why) => {
-  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
-  process.exit(1);
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    // Re-raise it on ourselves so a shell sees the same thing it would have
-    // seen from the real program, rather than a plain exit.
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// The `inillucent-migrate` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-migrate');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent-shell.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-// The `inillucent-shell` shim: resolve the platform binary and become it.
-//
-// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
-// execve and this has to work on Windows. The child's exit code and its signal
-// are both passed back up: a wrapper that always exited 0 would break every
-// script that branches on the exit code, and inillucent's exit codes carry
-// meaning - 3 is "the engine has not built that".
-import { spawn } from 'node:child_process';
-import { resolveBinary } from '../resolve.mjs';
-
-let binary;
-try {
-  binary = resolveBinary('inillucent-shell');
-} catch (why) {
-  process.stderr.write(String(why.message ?? why) + '\n');
-  process.exit(1);
-}
-
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
-child.on('error', (why) => {
-  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
-  process.exit(1);
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    // Re-raise it on ourselves so a shell sees the same thing it would have
-    // seen from the real program, rather than a plain exit.
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// The `inillucent-shell` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-shell');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-// The `inillucent` shim: resolve the platform binary and become it.
-//
-// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
-// execve and this has to work on Windows. The child's exit code and its signal
-// are both passed back up: a wrapper that always exited 0 would break every
-// script that branches on the exit code, and inillucent's exit codes carry
-// meaning - 3 is "the engine has not built that".
-import { spawn } from 'node:child_process';
-import { resolveBinary } from '../resolve.mjs';
-
-let binary;
-try {
-  binary = resolveBinary('inillucent');
-} catch (why) {
-  process.stderr.write(String(why.message ?? why) + '\n');
-  process.exit(1);
-}
-
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
-child.on('error', (why) => {
-  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
-  process.exit(1);
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    // Re-raise it on ourselves so a shell sees the same thing it would have
-    // seen from the real program, rather than a plain exit.
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// The `inillucent` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/package.json

@@ -1,52 +1,52 @@
-{
-  "name": "inillucent",
-  "version": "0.1.4",
-  "description": "Embedded SQL database with full-text and vector search, an MCP server, and a sqlite3-shaped shell. No native build step: the binaries ship as platform packages.",
-  "keywords": [
-    "database",
-    "sql",
-    "sqlite",
-    "vector",
-    "embedding",
-    "search",
-    "mcp",
-    "cli",
-    "rag"
-  ],
-  "homepage": "https://github.com/Black-Rainbow-Labs/Inillucent#readme",
-  "bugs": "https://github.com/Black-Rainbow-Labs/Inillucent/issues",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Black-Rainbow-Labs/Inillucent.git",
-    "directory": "packages/npm/inillucent"
-  },
-  "license": "MIT",
-  "author": "Black Rainbow Labs",
-  "type": "module",
-  "engines": {
-    "node": ">=18"
-  },
-  "bin": {
-    "inillucent": "bin/inillucent.mjs",
-    "inillucent-shell": "bin/inillucent-shell.mjs",
-    "inillucent-mcp": "bin/inillucent-mcp.mjs",
-    "inillucent-migrate": "bin/inillucent-migrate.mjs"
-  },
-  "main": "index.mjs",
-  "exports": {
-    ".": "./index.mjs"
-  },
-  "files": [
-    "bin",
-    "index.mjs",
-    "resolve.mjs",
-    "README.md"
-  ],
-  "optionalDependencies": {
-    "@blackrainbowlabs/cli-win32-x64": "0.1.4",
-    "@blackrainbowlabs/cli-darwin-arm64": "0.1.4",
-    "@blackrainbowlabs/cli-darwin-x64": "0.1.4",
-    "@blackrainbowlabs/cli-linux-x64": "0.1.4",
-    "@blackrainbowlabs/cli-linux-arm64": "0.1.4"
-  }
-}
+{
+  "name": "inillucent",
+  "version": "0.1.5",
+  "description": "Embedded SQL database with full-text and vector search, an MCP server, and a sqlite3-shaped shell. No native build step: the binaries ship as platform packages.",
+  "keywords": [
+    "database",
+    "sql",
+    "sqlite",
+    "vector",
+    "embedding",
+    "search",
+    "mcp",
+    "cli",
+    "rag"
+  ],
+  "homepage": "https://github.com/Black-Rainbow-Labs/Inillucent#readme",
+  "bugs": "https://github.com/Black-Rainbow-Labs/Inillucent/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Black-Rainbow-Labs/Inillucent.git",
+    "directory": "packages/npm/inillucent"
+  },
+  "license": "MIT",
+  "author": "Black Rainbow Labs",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "inillucent": "bin/inillucent.mjs",
+    "inillucent-shell": "bin/inillucent-shell.mjs",
+    "inillucent-mcp": "bin/inillucent-mcp.mjs",
+    "inillucent-migrate": "bin/inillucent-migrate.mjs"
+  },
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "bin",
+    "index.mjs",
+    "resolve.mjs",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "@blackrainbowlabs/cli-win32-x64": "0.1.5",
+    "@blackrainbowlabs/cli-darwin-arm64": "0.1.5",
+    "@blackrainbowlabs/cli-darwin-x64": "0.1.5",
+    "@blackrainbowlabs/cli-linux-x64": "0.1.5",
+    "@blackrainbowlabs/cli-linux-arm64": "0.1.5"
+  }
+}

package/resolve.mjs

@@ -1,114 +1,122 @@
-// Finds the binary for the machine this is running on.
-//
-// The arrangement is esbuild's, and it is the right one: the binaries live in
-// per-platform packages listed as `optionalDependencies`, npm installs only the
-// one that matches, and this package's `bin` entries are tiny shims that
-// resolve it and hand over. There is no postinstall script and nothing is
-// downloaded at install time, which means `npm ci` works offline, in a locked
-// CI, and behind a registry proxy - none of which is true of a package that
-// fetches a binary from GitHub when it is installed.
-//
-// The cost is that a platform without a published package cannot install, and
-// the failure has to say so in a sentence somebody can act on rather than as an
-// unresolved import. That is what `resolveBinary` is for.
-
-import { createRequire } from 'node:module';
-import { accessSync, constants, existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-
-const require = createRequire(import.meta.url);
-
-/** The platform packages, by the `process.platform`-`process.arch` pair each serves. */
-const PACKAGES = {
-  'win32-x64': '@inillucent/cli-win32-x64',
-  'darwin-arm64': '@inillucent/cli-darwin-arm64',
-  'darwin-x64': '@inillucent/cli-darwin-x64',
-  'linux-x64': '@inillucent/cli-linux-x64',
-  'linux-arm64': '@inillucent/cli-linux-arm64',
-};
-
-/** The four programs the release ships, and what each one is for. */
-export const PROGRAMS = {
-  inillucent: 'the command line: query, exec, describe, import, export, search',
-  'inillucent-shell': 'the interactive sqlite3-shaped shell',
-  'inillucent-mcp': 'the MCP server, for an agent',
-  'inillucent-migrate': 'builds an inillucent database from a SQLite file',
-};
-
-/**
- * Returns the platform package name for this machine, or null if there is none.
- */
-export function platformPackage() {
-  return PACKAGES[`${process.platform}-${process.arch}`] ?? null;
-}
-
-/**
- * Returns the absolute path of one of the four programs on this machine.
- *
- * @param program - which program, as it is named in PROGRAMS
- */
-export function resolveBinary(program) {
-  if (!(program in PROGRAMS)) {
-    throw new Error(`inillucent has no program called ${program}`);
-  }
-  // **`INILLUCENT_BIN` wins, the way it already does for the Go and PHP
-  // wrappers (task-1969, 4.5).** It names the `inillucent` binary; the others
-  // are looked for beside it, which is where a build and an install both put
-  // them. Without this the wrappers stage of `tools/validate` could point the
-  // other two languages at a freshly built binary and had no way to point this
-  // one, so the only npm test that could run was the one that reads the
-  // platform table as text.
-  //
-  // It throws rather than falling through when the named binary is not there:
-  // a caller who says where the binary is and is wrong wants to know, not to
-  // have the resolver quietly go looking somewhere else.
-  const named = process.env.INILLUCENT_BIN;
-  if (named) {
-    const suffix = process.platform === 'win32' ? '.exe' : '';
-    const beside = program === 'inillucent'
-      ? named
-      : join(dirname(named), `${program}${suffix}`);
-    if (!existsSync(beside)) {
-      throw new Error(
-        `INILLUCENT_BIN is set and ${beside} is not there.
-` +
-          `  Unset INILLUCENT_BIN to look for an installed copy instead.`,
-      );
-    }
-    return beside;
-  }
-  const name = platformPackage();
-  if (!name) {
-    throw new Error(
-      `inillucent has no prebuilt binary for ${process.platform}-${process.arch}.\n` +
-        `  Build it from source instead:  cargo install inillucent-cli\n` +
-        `  Or open an issue: https://github.com/Black-Rainbow-Labs/Inillucent/issues`,
-    );
-  }
-  const suffix = process.platform === 'win32' ? '.exe' : '';
-  let path;
-  try {
-    // The platform package's own entry point tells us where its bin directory
-    // is, rather than this package guessing at a node_modules layout - which
-    // pnpm, yarn's pnp and a hoisted npm tree all arrange differently.
-    path = require.resolve(`${name}/bin/${program}${suffix}`);
-  } catch {
-    throw new Error(
-      `inillucent's binary for ${process.platform}-${process.arch} is not installed.\n` +
-        `  The package ${name} should have been installed as an optional dependency.\n` +
-        `  If your installer was run with --no-optional, install it directly:\n` +
-        `    npm install ${name}\n`,
-    );
-  }
-  try {
-    accessSync(path, constants.X_OK);
-  } catch {
-    // An npm tarball does not always preserve the executable bit, and the
-    // failure it produces otherwise is EACCES from execve with no explanation.
-    throw new Error(
-      `${path} is not executable.\n  Fix it with:  chmod +x ${path}\n` +
-        `  Then please report it: https://github.com/Black-Rainbow-Labs/Inillucent/issues`,
-    );
-  }
-  return path;
-}
+// Finds the binary for the machine this is running on.
+//
+// The arrangement is esbuild's, and it is the right one: the binaries live in
+// per-platform packages listed as `optionalDependencies`, npm installs only the
+// one that matches, and this package's `bin` entries are tiny shims that
+// resolve it and hand over. There is no postinstall script and nothing is
+// downloaded at install time, which means `npm ci` works offline, in a locked
+// CI, and behind a registry proxy - none of which is true of a package that
+// fetches a binary from GitHub when it is installed.
+//
+// The cost is that a platform without a published package cannot install, and
+// the failure has to say so in a sentence somebody can act on rather than as an
+// unresolved import. That is what `resolveBinary` is for.
+
+import { createRequire } from 'node:module';
+import { accessSync, constants, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+// **The scope here is the scope they are published under, and the two came apart (task-1995).**
+// The packages were renamed from `@inillucent/*` to `@blackrainbowlabs/*` in build.mjs and in this
+// package's optionalDependencies, and this table was missed. npm then installed
+// `@blackrainbowlabs/cli-win32-x64` correctly and the shim looked for `@inillucent/cli-win32-x64`,
+// so every install on every platform ended at "inillucent's binary for win32-x64 is not installed"
+// - naming a package that does not exist. It reached the registry, where a version cannot be
+// replaced. resolve.test.mjs compares this table against package.json and against build.mjs, and it
+// no longer hard-codes a scope, so a rename that touches one of the three fails here instead.
+/** The platform packages, by the `process.platform`-`process.arch` pair each serves. */
+const PACKAGES = {
+  'win32-x64': '@blackrainbowlabs/cli-win32-x64',
+  'darwin-arm64': '@blackrainbowlabs/cli-darwin-arm64',
+  'darwin-x64': '@blackrainbowlabs/cli-darwin-x64',
+  'linux-x64': '@blackrainbowlabs/cli-linux-x64',
+  'linux-arm64': '@blackrainbowlabs/cli-linux-arm64',
+};
+
+/** The four programs the release ships, and what each one is for. */
+export const PROGRAMS = {
+  inillucent: 'the command line: query, exec, describe, import, export, search',
+  'inillucent-shell': 'the interactive sqlite3-shaped shell',
+  'inillucent-mcp': 'the MCP server, for an agent',
+  'inillucent-migrate': 'builds an inillucent database from a SQLite file',
+};
+
+/**
+ * Returns the platform package name for this machine, or null if there is none.
+ */
+export function platformPackage() {
+  return PACKAGES[`${process.platform}-${process.arch}`] ?? null;
+}
+
+/**
+ * Returns the absolute path of one of the four programs on this machine.
+ *
+ * @param program - which program, as it is named in PROGRAMS
+ */
+export function resolveBinary(program) {
+  if (!(program in PROGRAMS)) {
+    throw new Error(`inillucent has no program called ${program}`);
+  }
+  // **`INILLUCENT_BIN` wins, the way it already does for the Go and PHP
+  // wrappers (task-1969, 4.5).** It names the `inillucent` binary; the others
+  // are looked for beside it, which is where a build and an install both put
+  // them. Without this the wrappers stage of `tools/validate` could point the
+  // other two languages at a freshly built binary and had no way to point this
+  // one, so the only npm test that could run was the one that reads the
+  // platform table as text.
+  //
+  // It throws rather than falling through when the named binary is not there:
+  // a caller who says where the binary is and is wrong wants to know, not to
+  // have the resolver quietly go looking somewhere else.
+  const named = process.env.INILLUCENT_BIN;
+  if (named) {
+    const suffix = process.platform === 'win32' ? '.exe' : '';
+    const beside = program === 'inillucent'
+      ? named
+      : join(dirname(named), `${program}${suffix}`);
+    if (!existsSync(beside)) {
+      throw new Error(
+        `INILLUCENT_BIN is set and ${beside} is not there.
+` +
+          `  Unset INILLUCENT_BIN to look for an installed copy instead.`,
+      );
+    }
+    return beside;
+  }
+  const name = platformPackage();
+  if (!name) {
+    throw new Error(
+      `inillucent has no prebuilt binary for ${process.platform}-${process.arch}.\n` +
+        `  Build it from source instead:  cargo install inillucent-cli\n` +
+        `  Or open an issue: https://github.com/Black-Rainbow-Labs/Inillucent/issues`,
+    );
+  }
+  const suffix = process.platform === 'win32' ? '.exe' : '';
+  let path;
+  try {
+    // The platform package's own entry point tells us where its bin directory
+    // is, rather than this package guessing at a node_modules layout - which
+    // pnpm, yarn's pnp and a hoisted npm tree all arrange differently.
+    path = require.resolve(`${name}/bin/${program}${suffix}`);
+  } catch {
+    throw new Error(
+      `inillucent's binary for ${process.platform}-${process.arch} is not installed.\n` +
+        `  The package ${name} should have been installed as an optional dependency.\n` +
+        `  If your installer was run with --no-optional, install it directly:\n` +
+        `    npm install ${name}\n`,
+    );
+  }
+  try {
+    accessSync(path, constants.X_OK);
+  } catch {
+    // An npm tarball does not always preserve the executable bit, and the
+    // failure it produces otherwise is EACCES from execve with no explanation.
+    throw new Error(
+      `${path} is not executable.\n  Fix it with:  chmod +x ${path}\n` +
+        `  Then please report it: https://github.com/Black-Rainbow-Labs/Inillucent/issues`,
+    );
+  }
+  return path;
+}