Skip to content

fix(ingest): stop creating the Kùzu graph path as a directory - #540

Merged
chris-dare-dev merged 1 commit into
mainfrom
claude/kuzu-bootstrap-dir
Nov 15, 2026
Merged

chris-dare-dev merged 1 commit into
mainfrom
claude/kuzu-bootstrap-dir

Conversation

@chris-dare-dev

Copy link
Copy Markdown
Owner

What

Stops make bootstrap and ApplicationPaths.prepare() from creating var/arxmcp/index/kuzu as a directory. Kùzu 0.11.3 (pinned) stores a database as a single file and refuses a directory at its path (RuntimeError: Runtime exception: Database path cannot be a directory). On a freshly bootstrapped box, graph ingest therefore failed until someone deleted the directory, and a restic backup of that empty directory reached the restore drill as an unreadable graph.

There is no issue for this. It is the bootstrap follow-up named in #539.

  • Makefile bootstrap and ApplicationPaths.prepare() create only the parent index/.
  • apply_schema removes an empty directory found at the graph path, which is what older bootstraps left. Every graph writer (OpenAlex, INSPIRE and intra-paper ingest) calls it before opening the database, so existing boxes recover on their next ingest with no manual step. A non-empty directory is left alone and Kùzu still refuses it, so nothing with data in it is deleted.
  • The four --kuzudb help texts call the path a file instead of a directory that "matches Makefile bootstrap".
  • tests/test_backup_wrapper.py models the graph as the single file it is.

Verification

Run on Ubuntu at 00db2c2, on top of main at d9ddaa8.

  • Reproduced first on a fresh tmp tree: apply_schema on the bootstrapped directory raised the error above. With the directory gone, Kùzu wrote a single file at that path.
  • Three new tests fail on the unfixed code with that exact RuntimeError and pass with the fix:
    • running the real bootstrap target (PYTHON=true skips the install) and then opening the graph;
    • prepare() and then opening the graph;
    • apply_schema over an empty directory.
  • A fourth test checks that a non-empty directory is kept and Kùzu still refuses it.
  • ARXMCP_RUN_RESTIC_TESTS=1 pytest -m requires_restic tests/test_backup_wrapper.py passes with the graph as a file.
  • ruff check . is clean.
  • Full pytest with no ARXMCP_* variables set: 5557 passed, 144 skipped, 1 xfailed, exit 0.

Notes

  • Restore drill: ops/restore_drill_check.py is not touched here. fix: six more findings from the architecture review #539 already changes its locator to accept a single-file graph.
  • Now inaccurate, not changed here: docs/ops/backup-restore.md and gotcha 4 in CLAUDE.md write the path as index/kuzu/ with a trailing slash, which reads as a directory. Markdown edits are out of scope for a code change, so the wiki needs updating separately.
  • Docker: docker/Dockerfile.server never created the Kùzu path, so it needed no change.

🤖 Generated with Claude Code

Kùzu 0.11.3 stores a database as a single file and refuses a directory
at its path ("Database path cannot be a directory"). make bootstrap and
ApplicationPaths.prepare() both created var/arxmcp/index/kuzu as a
directory, so graph ingest failed on a freshly bootstrapped tree until
someone deleted it, and a restic backup of that empty directory reached
the restore drill as an unreadable graph.

Both now create only the parent. apply_schema, which every graph writer
calls before opening the database, removes an empty directory left by
an older bootstrap; a non-empty one is left alone for Kùzu to refuse.
The --kuzudb help text now calls the path a file.

The backup wrapper test now models the graph as the single file it is.
@chris-dare-dev
chris-dare-dev merged commit 9bea7d8 into main Nov 15, 2026
1 check passed
@chris-dare-dev
chris-dare-dev deleted the claude/kuzu-bootstrap-dir branch November 15, 2026 01:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant