[srbaker]

Closes #184.

Promotes [Unreleased] to 1.10.0 and bumps the version. This ships #180: engine 4.0.0.a8 and the in-place a5 → a8 upgrade. It moves Grail on from #180's 29833cd to Grail main 06ccec5 (fa2c3f7).

Blocked: the brain-freeze upgrade gate fails on 06ccec5. Do not merge this as it stands. After the engine upgrade, redeployModules.gs runs out of temporary object memory on the brain-freeze database, so email.message.EmailMessage is never rebased and flask cannot import. 29833cd passes the same gate on the same machine today. Details are under Checks.

Stacked on #180. Merge this after #180, never before. Its base is feat/engine-upgrade-in-place. The repository has delete_branch_on_merge on, so when #180 merges GitHub deletes that branch and retargets this PR to main by itself. Check that the base reads main before merging. If it does not, retarget it by hand.

Why 1.10.0

A minor version, not 1.9.1 or 2.0.0:

• Not a patch. The engine changes, the Python runtime moves 201 Grail PRs, and the in-place upgrade is a new user-facing feature with a new prompt.
• Not a major. Nothing a 1.9.0 user has breaks or has to be redone. Their database is kept and upgraded after they confirm, with a backup. Settings, commands and the gemdb API are unchanged. Earlier releases bumped the minor version even when users had to delete their database (1.8.0's a4 → a5, 1.9.0's Rowan image), and this change is gentler than either.

What changes

• package.json / package-lock.json: npm version 1.10.0 --no-git-tag-version, as CONTRIBUTING.md says.
• CHANGELOG.md: a dated ## [1.10.0] - 2026-10-28 section, an empty [Unreleased], and the link definitions. The section opens with a preface that tells a 1.9.0 user not to delete ~/GemDB/db. The engine entry is now written for them: what triggers the prompt, what the upgrade does (stop, copy to db/data/extent0.dbf.pre-4.0.0.a5, upgrade, reinstall Python support and the MCP server), how long it takes, the disk space it needs (about the extent's size plus 1 GB), and what happens on a decline, a failure, an unconfirmed restore, and an auto-start or agent start. It also covers who still has to recreate their database. A new "A newer Python runtime" entry summarizes Grail c8cbc92 → 06ccec5 (255 commits, 201 PRs). Beyond 29833cd it covers Grail #1949 and #1957 (stored float/int subclass instances, mixin enum members and functional-API enums keep their class across a rebuild), #1934 and #1958 (assigned module attributes read back; sys.excepthook is honoured), #1962 and #1963 (an unchanged namespaced re-run writes nothing), and #1951/#1932 (PEP 263 source encodings).
• README.md: "GemDB Code updates and associated data" used to say you should not expect to keep access to your data after an update that changes the engine version. It now describes the in-place upgrade. The gemdb.engineVersion bullet is changed to match. These edits do not overlap README: split the notebook debugging bullets into a "Debug a notebook cell" section #175's README hunks on main.

npm run release:notes 1.10.0 renders the section.

The date: if this merges on a later day, change the heading's date to that day before merging.

Not given entries

These are on main since 1.9.0, but not on #180's branch:

• README: split the notebook debugging bullets into a "Debug a notebook cell" section #175: reorganizes the README's notebook-debugging bullets into their own section.
• Bump the dev-dependencies group with 4 updates #182 and Bump @eslint/js from 9.39.5 to 10.0.1 #156: dev-dependency bumps.

Checks

On fa2c3f7 (Grail 06ccec5, engine 4.0.0.a8), Darwin arm64:

• Grail 06ccec5's CI: the merge-queue CI run on exactly that commit passed (GemTalk/Grail run 41095217594). Grail main has no push-triggered CI. The Grail upgrade workflow has not run on 06ccec5: its nightly last ran on 93d0c30, and #1949 and #1957 passed it on their PR branches.
• npm test: 71 files, 1318 tests passed. lint, lint:toolchain, format:check, typecheck, typecheck:strict and npm run bundle are clean.
• scripts/bundle-grail.sh, bundle:mcp, bundle:stats, test:extent, then npm run test:integration with GEMDB_TEST_ENGINE set to an a8 product outside ~/GemDB: 13 files passed, 1 skipped. Tests: 181 passed, 2 expected fail, 4 skipped, 1 todo. scripts/package.sh darwin-arm64 packages and checks the .vsix.
• src/__integration__/engineUpgrade.test.ts with GEMDB_TEST_UPGRADE_EXTENT (an a5 GemDB test extent carrying Grail c8cbc92), GEMDB_TEST_UPGRADE_ENGINE (a5) and GEMDB_TEST_ENGINE (a8): 4 of 4 passed (119s).
• By hand, with a separate global dir and stone names: an a5 stone ran on a copy of that extent and was stopped. The bundled upgrade_engine.sh --in-place upgraded the copy in 43s, and copydbf -i reads 4.0.0.a8. An a8 stone started without -N. resources/install-grail.sh exited 0 in 15s ("Recompiling 1528 Grail methods an engine upgrade removed", redeployModules: 0 rebuilt, 0 skipped, 0 failed). Python then ran a class, sum, a dict holding a tuple, None and enum keys, an int-mixin enum, a functional enum, and Unicode upper().
• CI on fa2c3f7: green (run 41098533220). All three integration legs and the checks passed on the first attempt. ci-complete was cancelled at its 1-minute limit while the GitHub API was returning 504s, and passed when re-run.
• brain-freeze upgrade gate (ci/upgrade.sh at brain-freeze b7767fd, gemdb-darwin-arm64-1.9.0.vsix → this run's vsix-darwin-arm64): FAIL, reproduced from a fresh HOME.
  • The engine upgrade, the counts and the record all pass: policies=901 events=4995 claims=2174 quotes=1 flavoured=1, sha256 4e013440…e2c0ba both before and after.
  • The web app exits before it serves:

    ImportError: class email.message.EmailMessage changed its bases (Message -> MIMEPart), and its instances are stored against the old class: run gemdb.schema.rebase('email.message.EmailMessage') under a clean transaction, or restore the base
    

  • Cause: install-grail.sh's last step, redeployModules.gs, runs at GEM_TEMPOBJ_CACHE_SIZE=900000 (Grail's own install.sh uses the same figure). It dies with vmGc OOM … 674943/674944Kold and then error 4035 (lost connection), so it prints no summary and commits nothing. install-grail.sh reports only its generic WARNING.
  • Same machine, same day, same gate, with Upgrade an a5 database to a8 in place instead of asking to delete it #180's 29833cd build (CI run 40618737420) as NEW: PASS. redeployModules: 296 rebuilt, 0 skipped, 0 failed, in 403836 ms, unit suite 343 OK (83 skipped), acceptance 12 features / 16 scenarios passed.
  • Re-running redeployModules.gs by hand on the failed database at 2000000 KB finishes (190s) but reports 0 rebuilt, 0 skipped, 57 failed. 56 of the 57 are the EmailMessage refusal; the other is routes: No module named 'conflicts'. The "nothing is stored against email.message.EmailMessage, so it is rebuilt on its new bases" repair that 29833cd makes never fires. This was measured after two failed runs on that database, so it is a lead, not a clean measurement: the larger cache may only move the failure.
  • So the regression is in Grail 29833cd..06ccec5, not in this branch. It needs a Grail fix and a re-pin before 1.10.0 ships.

Follow-ups this PR does not make

• The Python-update warning looks stale. confirmGrailInstall in src/lifecycle.ts, and README's "How setup runs" paragraph, still say that installing newer Python support makes committed dates, decimals, tuples and instances stop working. Grail #1791 (in this pin range) rebuilds deployed modules in place to keep them working. Grail #1867 measured the release=c8cbc92 upgrade case at 243/0. So the warning now contradicts the upgrade path, which reinstalls Python support without asking. Changing that is a code change, so it belongs in its own PR.
• Download sizes. platform.ts's download and disk figures (170 MB / 470 MB) are still a5 measurements.
• The gitleaks scan of the .vsix (Upgrade an a5 database to a8 in place instead of asking to delete it #180's open item) runs in the Release workflow's scan job.

To release, after both PRs merge

1. Merge Upgrade an a5 database to a8 in place instead of asking to delete it #180. Confirm this PR retargeted to main, fix the date if needed, and merge it.
2. Wait for the main push CI run on the merge commit to go green. It uploads vsix-darwin-arm64, vsix-linux-x64 and vsix-linux-arm64.
3. Optionally, npm run release:fetch on that commit, then install dist/gemdb-darwin-arm64-1.10.0.vsix over a 1.9.0 setup and run the upgrade once.
4. Go to Actions → Release → Run workflow on main with 1.10.0, ticking dry-run first (validate → collect → scan).
5. Run it again without dry-run and approve at the release-approval gate. It tags v1.10.0, creates the GitHub Release, publishes to the Marketplace and Open VSX, then runs verify.

🤖 Generated with Claude Code