diff --git a/Makefile b/Makefile index 14f0330..dee6a9c 100644 --- a/Makefile +++ b/Makefile @@ -122,7 +122,9 @@ bootstrap: fi $(PYTHON) -m pip install --require-virtualenv -e ".[dev]" mkdir -p var/arxmcp/corpus/raw var/arxmcp/corpus/parsed var/arxmcp/corpus/chunks - mkdir -p var/arxmcp/index/lancedb var/arxmcp/index/kuzu + # Kùzu stores the citation graph as a single file at index/kuzu and + # refuses a directory there, so only its parent index/ is created. + mkdir -p var/arxmcp/index/lancedb mkdir -p var/arxmcp/cache/ar5iv mkdir -p var/arxmcp/ops/parser-failures # E14_S03: Phoenix's SQLite trace store under PHOENIX_WORKING_DIR. diff --git a/ingest/graph_ingest.py b/ingest/graph_ingest.py index eee8ebc..301fc7c 100644 --- a/ingest/graph_ingest.py +++ b/ingest/graph_ingest.py @@ -748,10 +748,7 @@ def main(argv: list[str] | None = None) -> int: "--kuzudb", type=Path, default=Path("var/arxmcp/index/kuzu"), - help=( - "Kùzu DB directory (default: var/arxmcp/index/kuzu — matches " - "Makefile bootstrap and 05-storage-and-indexing.md)" - ), + help="Kùzu database file (default: var/arxmcp/index/kuzu)", ) parser.add_argument( "--category", diff --git a/ingest/inspire_ingest.py b/ingest/inspire_ingest.py index d97f779..ef79ce6 100644 --- a/ingest/inspire_ingest.py +++ b/ingest/inspire_ingest.py @@ -760,10 +760,7 @@ def main(argv: list[str] | None = None) -> int: "--kuzudb", type=Path, default=Path("var/arxmcp/index/kuzu"), - help=( - "Kùzu DB directory (default: var/arxmcp/index/kuzu — " - "matches Makefile bootstrap and 05-storage-and-indexing.md)" - ), + help="Kùzu database file (default: var/arxmcp/index/kuzu)", ) parser.add_argument( "--include-back-refs", diff --git a/ingest/intra_paper_refs.py b/ingest/intra_paper_refs.py index f4cb84f..5638a4d 100644 --- a/ingest/intra_paper_refs.py +++ b/ingest/intra_paper_refs.py @@ -459,7 +459,7 @@ def main(argv: list[str] | None = None) -> int: "--kuzudb", type=Path, default=DEFAULT_KUZUDB_PATH, - help=f"Kùzu DB directory (default: {DEFAULT_KUZUDB_PATH})", + help=f"Kùzu database file (default: {DEFAULT_KUZUDB_PATH})", ) parser.add_argument( "--lancedb", diff --git a/ingest/kuzudb_schema.py b/ingest/kuzudb_schema.py index 23c212b..e16d382 100644 --- a/ingest/kuzudb_schema.py +++ b/ingest/kuzudb_schema.py @@ -99,19 +99,23 @@ def apply_schema(db_path: Path) -> None: - """Apply the citation-graph schema to a Kùzu database directory. + """Apply the citation-graph schema to a Kùzu database file. - Creates the parent directory if missing (the Kùzu DB itself is a - directory, not a single file). Runs every statement in - ``SCHEMA_STATEMENTS`` in order; each uses ``IF NOT EXISTS`` so the - function is idempotent (AC#2). + Creates the parent directory if missing. Kùzu stores the database as + a single file and refuses a directory at ``db_path``; an empty + directory there (what older bootstraps created) is removed first, + while a non-empty one is left for Kùzu to reject. Runs every + statement in ``SCHEMA_STATEMENTS`` in order; each uses + ``IF NOT EXISTS`` so the function is idempotent (AC#2). Args: - db_path: directory the Kùzu ``Database`` will own. The - production default is ``var/arxmcp/index/kuzu/``; tests - pass ``tmp_path`` per the conftest discipline. + db_path: file the Kùzu ``Database`` will own. The production + default is ``var/arxmcp/index/kuzu``; tests pass + ``tmp_path`` per the conftest discipline. """ db_path.parent.mkdir(parents=True, exist_ok=True) + if db_path.is_dir() and not any(db_path.iterdir()): + db_path.rmdir() db = kuzu.Database(str(db_path)) conn = None try: @@ -205,10 +209,7 @@ def main() -> int: "--kuzudb", type=Path, default=Path("var/arxmcp/index/kuzu"), - help=( - "directory the Kùzu database will own " - "(default: var/arxmcp/index/kuzu — matches Makefile bootstrap)" - ), + help="file the Kùzu database will own (default: var/arxmcp/index/kuzu)", ) args = parser.parse_args() apply_schema(args.kuzudb) diff --git a/server/application_paths.py b/server/application_paths.py index 1320457..50c44f8 100644 --- a/server/application_paths.py +++ b/server/application_paths.py @@ -183,9 +183,13 @@ def resolve( ) def prepare(self) -> None: - """Create the tree and prove temporary state is writable using EAFP.""" + """Create the tree and prove temporary state is writable using EAFP. + + The Kùzu graph is a single file that Kùzu refuses to open as a + directory, so only its parent is created. + """ directories = (self.root, self.corpus, self.index, self.lancedb, - self.kuzu, self.bm25, self.sqlite, self.notebooks, + self.kuzu.parent, self.bm25, self.sqlite, self.notebooks, self.cache, self.ops, self.logs, self.backups, self.tmp) for path in directories: path.mkdir(parents=True, exist_ok=True) diff --git a/tests/test_application_paths.py b/tests/test_application_paths.py index 515e0b3..9ed9b67 100644 --- a/tests/test_application_paths.py +++ b/tests/test_application_paths.py @@ -1,5 +1,6 @@ from pathlib import Path +import kuzu import pytest import server.application_paths as paths_module @@ -185,3 +186,12 @@ def denied(**_kwargs): monkeypatch.setattr(paths_module.tempfile, "mkstemp", denied) with pytest.raises(PermissionError, match="read-only"): paths.prepare() + + +def test_prepared_tree_opens_the_citation_graph(tmp_path: Path) -> None: + paths = ApplicationPaths.resolve( + environ={}, mode="installed", root=tmp_path / "data" + ) + paths.prepare() + db = kuzu.Database(str(paths.kuzu)) + db.close() diff --git a/tests/test_backup_wrapper.py b/tests/test_backup_wrapper.py index 7232ff4..70b7f99 100644 --- a/tests/test_backup_wrapper.py +++ b/tests/test_backup_wrapper.py @@ -277,9 +277,11 @@ def _root(self, tmp_path: Path) -> Path: encoding="utf-8", ) var = root / "var" / "arxmcp" - for rel in ("index/lancedb", "index/kuzu", "corpus/chunks", "notebooks/demo"): + for rel in ("index/lancedb", "corpus/chunks", "notebooks/demo"): (var / rel).mkdir(parents=True) (var / rel / "data.bin").write_bytes(os.urandom(64)) + # Kùzu stores the citation graph as a single file. + (var / "index" / "kuzu").write_bytes(os.urandom(64)) (var / "cache").mkdir() sqlite3.connect(str(var / "cache" / "notebooks.db")).close() return root diff --git a/tests/test_graph_ingest.py b/tests/test_graph_ingest.py index b6ef298..8e0b158 100644 --- a/tests/test_graph_ingest.py +++ b/tests/test_graph_ingest.py @@ -10,6 +10,9 @@ from __future__ import annotations import json +import os +import shutil +import subprocess from pathlib import Path from typing import Any @@ -18,6 +21,8 @@ from ingest import graph_ingest, kuzudb_schema +REPO_ROOT = Path(__file__).resolve().parent.parent + # --------------------------------------------------------------------------- # Fixtures: 5-paper corpus per the brief deliverable list # --------------------------------------------------------------------------- @@ -222,6 +227,42 @@ def test_stamps_schema_version(self, db_path: Path): def test_read_schema_version_none_when_db_absent(self, tmp_path: Path): assert kuzudb_schema.read_schema_version(tmp_path / "missing") is None + def test_replaces_empty_directory_at_db_path(self, db_path: Path): + """Older bootstraps left an empty directory at the graph path, + which Kùzu refuses to open; the first schema run still succeeds.""" + db_path.mkdir() + kuzudb_schema.apply_schema(db_path) + assert ( + kuzudb_schema.read_schema_version(db_path) + == kuzudb_schema.KUZU_SCHEMA_VERSION + ) + + def test_leaves_non_empty_directory_for_kuzu_to_refuse(self, db_path: Path): + db_path.mkdir() + kept = db_path / "operator-file" + kept.write_text("keep", encoding="utf-8") + with pytest.raises(RuntimeError, match="directory"): + kuzudb_schema.apply_schema(db_path) + assert kept.read_text(encoding="utf-8") == "keep" + + +@pytest.mark.skipif(shutil.which("make") is None, reason="make is not installed") +def test_bootstrapped_tree_opens_the_citation_graph(tmp_path: Path): + """``make bootstrap`` leaves the graph path free for Kùzu to create. + + ``PYTHON=true`` skips the interpreter check and the editable install, + so only the tree-creating steps run, inside ``tmp_path``. + """ + subprocess.run( + ["make", "-s", "-f", str(REPO_ROOT / "Makefile"), "bootstrap", "PYTHON=true"], + cwd=tmp_path, + env={**os.environ, "VIRTUAL_ENV": str(tmp_path)}, + check=True, + capture_output=True, + ) + db = kuzu.Database(str(tmp_path / "var" / "arxmcp" / "index" / "kuzu")) + db.close() + # --------------------------------------------------------------------------- # Ingest — happy path