ci: Node 22/24 test workflow; better-sqlite3 13 to stop the Node 24.19 ObjectWrap abort

.github/workflows/test.yml

@@ -0,0 +1,36 @@
+# Runs the whole suite (vitest contract + integration, node:test security) on
+# every pull request and every push to main. The external MSP integration suite
+# skips here because MSP_REPO_ROOT is not set; no secrets are used.
+name: test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: npm test (Node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [22, 24]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: node --version && npm --version
+      - run: npm ci
+      - run: npm test

README.md

@@ -1,7 +1,7 @@
 ---
-version: "0.2.2b"
+version: "0.2.4b"
 created_at: "2026-08-12T10:29:29+07:00,ATHER,working-tree"
-last_update: "2026-09-08T20:00:00+07:00,RWANG"
+last_update: "2026-09-11T12:30:00+07:00,Claude Opus 5"
 status: "beta"
 superseded_by: null
 attributes:
@@ -53,6 +53,15 @@ npm run pack:client
 The external MSP tests skip when `MSP_REPO_ROOT` is absent. They run against
 the actual MSP provider and MSP service when the variable is present.
 
+Toolchain: Node `>=22` (the floor of `better-sqlite3` 13, which runs on N-API
+and ships its prebuilt binaries, so nothing is rebuilt against local Node
+headers). `.github/workflows/test.yml` runs `npm ci` and `npm test` on Node 22
+and 24 for every pull request and push to `main`, without `MSP_REPO_ROOT` and
+without secrets. Do not pin `better-sqlite3` back to 11.x/12.x: a copy compiled
+against Node 24.19+ headers aborts on garbage collection
+([nodejs/node#65446](https://github.com/nodejs/node/issues/65446)); see
+[`docs/RUNBOOK-GKS-LOCAL.md`](docs/RUNBOOK-GKS-LOCAL.md#preflight).
+
 ## Start
 
 GKS never chooses an implicit canonical database path. Use the same explicit
@@ -131,6 +140,7 @@ verification, not production deployment or Zuri cutover evidence.
 
 | Version | Date | Status | Summary | Commit Hash | Agent |
 |---|---|---|---|---|---|
+| 0.2.4b | 2026-09-11 | beta | Toolchain note: Node `>=22` for `better-sqlite3` 13 (N-API), the CI workflow, and why 11.x/12.x must not return on Node 24.19+ (nodejs/node#65446). Numbered 0.2.4b because open PR #7 takes 0.2.3b. | working-tree | Claude Opus 5 |
 | 0.2.1b | 2026-09-08 | beta | Aligned the local verification/start examples with the Node 24.18.x acceptance profile, explicit parameterized roots, and MSP-injected relay credential setup. | 9279cfe | RWANG |
 | 0.2.0b | 2026-09-08 | beta | Documented the authenticated GenesisRAG17 stage 9–14/17 surface, nine related tool contracts, immutable receipt order, and extension boundary. | 9279cfe | RWANG |
 | 0.1.1b | 2026-09-07 | beta | `gks_stage_evidence_export` (port version 3, migration 0005): Stage 9 evidence rows on every promotion and human decision, backfilled for every earlier execution, exported by cursor for zuri-ai's pull through MSP. | working-tree | Claude Fable 5.1 |

docs/RUNBOOK-GKS-LOCAL.md

@@ -1,7 +1,7 @@
 ---
-version: "0.2.1b"
+version: "0.2.2b"
 created_at: "2026-08-12T10:29:29+07:00,ATHER,working-tree"
-last_update: "2026-09-08T00:30:00+07:00,RWANG"
+last_update: "2026-09-11T12:30:00+07:00,Claude Opus 5"
 status: "beta"
 superseded_by: null
 attributes:
@@ -20,16 +20,27 @@ npm ci
 npm test
 ```
 
-The package declares Node `>=20`, but the verified GenesisRAG17 acceptance
-profile uses Node 24.18.x. Rebuild `better-sqlite3` against the same 24.18.x
-headers before running that profile; a Node 20 run is not equivalent evidence.
-`npm ci` must report no unresolved security advisories before release
-consideration.
-
-The current GenesisRAG17 acceptance profile uses the isolated Node 24.18 runtime
-when native SQLite dependencies are rebuilt. Record the runtime and the checked
-out commit with every compatibility result; do not treat a different local Node
-patch level as equivalent evidence.
+The package declares Node `>=22`, the floor of `better-sqlite3` 13.
+`.github/workflows/test.yml` runs `npm ci` and `npm test` on Node 22 and 24
+(ubuntu-latest) for every pull request and push to `main`; the external MSP
+suite skips there because `MSP_REPO_ROOT` is unset. `npm ci` must report no
+unresolved security advisories before release consideration.
+
+`better-sqlite3` 13 runs on N-API and ships its prebuilt binaries inside the
+package, so it no longer has to be rebuilt against the headers of the running
+Node. Do not move it back to 11.x or 12.x: those are `node::ObjectWrap` addons,
+and a copy compiled against Node 24.19.0 or later 24.x headers (every source
+build on those runtimes, including 11.10.0, which has no Node 24 prebuild)
+aborts the process when the garbage collector frees a prepared statement:
+`node::RemoveEnvironmentCleanupHook ... Assertion failed: (env) != nullptr`.
+Node 24.19.0 backported the `ObjectWrap` cleanup hooks without the global hook
+registry that makes removal safe without a live `Environment`
+([nodejs/node#65446](https://github.com/nodejs/node/issues/65446); backport of
+the registry pending in [nodejs/node#65943](https://github.com/nodejs/node/pull/65943)).
+
+The GenesisRAG17 acceptance profile was verified on Node 24.18.x. Record the
+runtime and the checked-out commit with every compatibility result; do not treat
+a different local Node patch level as equivalent evidence.
 
 ## Clone, paths, and grants
 
@@ -139,6 +150,7 @@ call it recovered canonical state.
 
 | Version | Date | Status | Summary | Commit Hash | Agent |
 |---|---|---|---|---|---|
+| 0.2.2b | 2026-09-11 | beta | Node floor raised to `>=22` for `better-sqlite3` 13 (N-API); replaced the "rebuild against 24.18.x headers" step with the Node 24.19+ `ObjectWrap` abort it now avoids (nodejs/node#65446); named the CI workflow. | working-tree | Claude Opus 5 |
 | 0.2.1b | 2026-09-08 | beta | Corrected graph receipt ownership and materialized replay semantics, added MSP-injected relay credential validation, and required `allowPublication: true` with the actual pointer/snapshot switch before publication. | 9279cfe | RWANG |
 | 0.2.0b | 2026-09-08 | beta | Documented explicit clone/runtime/path grants, the nine GenesisRAG17-related tool contracts, physical Stage 13 to Stage 14 ordering, and retry/stop recovery rules. | 9279cfe | RWANG |
 | 0.1.0b | 2026-08-12 | beta | Initial local start, health, evidence, failure, and recovery procedure. | working-tree | ATHER |