diff --git a/00-overview/postgres-migration-roadmap.md b/00-overview/postgres-migration-roadmap.md index be3e24f..9d8484e 100644 --- a/00-overview/postgres-migration-roadmap.md +++ b/00-overview/postgres-migration-roadmap.md @@ -472,14 +472,20 @@ | 2026-11-19 | Phase 2: history, diff, restore | API and MCP expose `document_history`, `document_version`, `document_diff`, and `restore_document_version`; restore creates a new version | | 2026-11-19 | Phase 2: validation | `GET /validate` and the MCP validation tool validate the database in `db` mode | | 2026-11-19 | Phase 2: tests | Full suite: 56 passed, 1 known stale-freshness failure | +| 2026-11-19 | Phase 3: inventory and relationships | Database read/write for inventory, schema validation from stored schemas, unique live item IDs, relationship graph over database records | +| 2026-11-19 | Phase 3: freshness | Database freshness report matches the file backend issue-for-issue | +| 2026-11-19 | Phase 3: search | Substring/line-match path at parity; PostgreSQL FTS index deferred to a performance phase | +| 2026-11-19 | Phase 3: tests | Full suite: 57 passed, 1 known stale-freshness failure | Notes: - The default backend remains `file`. Set `GNEXUS_BOOK_STORAGE_BACKEND=db` to use PostgreSQL for reads and writes. - In database mode, applying a changeset publishes it; `commit_changes` is a no-op and - `POST /commit` is blocked. Freshness still reads files until Phase 3. + `POST /commit` is blocked. +- Search keeps the current substring semantics for exact response parity. A full-text + index is a later optimization, not a correctness requirement. - The date-dependent freshness test still fails because 25 documents are past their review interval. This is the recorded baseline, not a regression. -- The next phase is Phase 3: inventory, relationships, search, and freshness at - database parity. +- The next phase is Phase 4: gnexus-auth SSO, users, roles, actor attribution, and + audit enforcement. diff --git a/CLAUDE.md b/CLAUDE.md index 97c4c63..9349498 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -95,7 +95,7 @@ - **`validation.py`** — the full-repo gate used before apply/commit: schemas parse as Draft 2020-12, every inventory file validates against its schema (`SCHEMA_BY_INVENTORY`), Markdown has required frontmatter, ids are unique per inventory file, and a regex scan detects raw secret assignments/private-key blocks. The separate inventory `docs`-link validator (`_validate_inventory_doc_links`) is intentionally disabled; freshness still reports those missing targets. - **`pending_changes.py`** — the write path. A proposal is a JSON file in `90-maintenance/pending-changes/`; `apply()` writes a Markdown doc or patches/creates an inventory item, runs whole-repo validation, and restores the previous file content if validation fails. Only `doc` and `inventory-item` kinds can be applied; full-file inventory replacement is not implemented. - **`git_adapter.py`** — status/diff/commit. Commit requires an explicit file list, rejects absolute/traversal/denied paths, runs validation first, stages only the named files, and creates a local commit only (never pushes). -- **`storage/`** — the PostgreSQL layer introduced for the migration. `models.py` defines the schema (documents/versions/blobs, inventory items/versions, changesets, users, audit), `db_repositories.py` implements the read interfaces, `pending_changes_db.py` implements draft/apply changesets transactionally, `documents.py` provides history/version/diff/restore, `validation.py` validates the database, `importer.py` copies the repository into PostgreSQL, `parity.py` compares both backends, and `cli.py` exposes `import`, `parity`, and `counts`. `factory.py` selects docs/inventory/pending repositories from `GNEXUS_BOOK_STORAGE_BACKEND`. Alembic lives in `server/alembic/`. In `db` mode all knowledge writes go through changesets; `commit_changes` is a no-op. Freshness still reads files until Phase 3. +- **`storage/`** — the PostgreSQL layer introduced for the migration. `models.py` defines the schema (documents/versions/blobs, inventory items/versions, changesets, users, audit), `db_repositories.py` implements the read interfaces, `pending_changes_db.py` implements draft/apply changesets transactionally, `documents.py` provides history/version/diff/restore, `validation.py` validates the database, `importer.py` copies the repository into PostgreSQL, `parity.py` compares both backends, and `cli.py` exposes `import`, `parity`, and `counts`. `factory.py` selects docs/inventory/pending repositories from `GNEXUS_BOOK_STORAGE_BACKEND`. Alembic lives in `server/alembic/`. In `db` mode all knowledge writes go through changesets; `commit_changes` is a no-op. Validation, freshness, and relationships use the selected backend. ### MCP server diff --git a/server/README.md b/server/README.md index 45de8a2..493155b 100644 --- a/server/README.md +++ b/server/README.md @@ -39,8 +39,7 @@ - Documents and inventory are read and written through PostgreSQL. Every write creates immutable versions grouped into a changeset; applying a changeset publishes it. History, version reads, diff, and restore are available in database mode. -- Validation uses the database when the backend is `db`. Freshness still reads files - until Phase 3. +- Validation and freshness use the database when the backend is `db`. - In database mode `POST /commit` is blocked: applying a changeset is the publish step. `commit_changes` in MCP is a documented no-op. - Database tests use `GNEXUS_BOOK_TEST_DATABASE_URL` (default @@ -146,7 +145,8 @@ - File-backend `POST /commit` creates a local Git commit only. It does not push. - Commit requests must provide an explicit file list. - Validation uses JSON Schema 2020-12 for inventory records in both backends. -- Freshness reports still read the file backend until Phase 3. +- Search keeps a substring/line-match path for exact response parity; a PostgreSQL + full-text index is deferred to a performance phase. ## Validation