owner: gmikcon status: draft last_reviewed: 2026-11-19 review_interval: 30d confidence: medium
Draft, proposed on 2026-11-19. Not implemented and not accepted.
Gnexus Book currently keeps its knowledge base as Markdown and YAML inside a Git checkout. The FastAPI server reads those files, applies proposed changes, validates the whole repository, and creates local Git commits. The UI and MCP server are thin layers over the same file-backed repositories.
Current characteristics:
90-maintenance/pending-changes/;Owner direction (2026-11-19):
Platform-wide rules in gnexus-handbook also apply. They are not repeated here; the relevant sections are linked below.
PostgreSQL becomes the system of record for documents, inventory, versions, users, changesets, and audit data. Git stops being the write path.
Reasons: multi-user concurrency and transactions, relational integrity, full-text search, JSONB for the flexible inventory records, mature backup/restore tooling.
The service stores immutable document and inventory versions grouped into changesets. It does not implement branches, merges, packfiles, remotes, or a general-purpose distributed VCS. The current functionality does not require them.
Required semantics:
sub principal and profile.10-platform/auth.md.user.*, global_logout, session.revoked, and role/permission webhooks are required, with HMAC verification./mcp-protocol/ (trailing slash significant). SSE is a legacy fallback only; stdio is not the production transport.mcp_* keys, not gnexus-auth access tokens.user_id, consumer); revocation is revoked_at, never deletion./internal/keys provisioning endpoints are required (not published through nginx, service-to-service secret + allowlist).401, and updates last_used_at.is_user; REST accepts X-Actor: user; audit records actor_kind, actor_name, and via.The database is dumped on a schedule to a separate host, with a documented restore procedure and periodic restore drills. A dump that has never been restored does not count as a backup. This follows 20-deployment/backups.md.
There is no Markdown/JSONL export from the database in the first version (owner decision). The dumps are the only safety net, so retention, off-host storage, and restore verification are mandatory.
The current repository stays the canonical source until the new backend passes its tests and a migration has been verified. The importer is a later task and must be repeatable.
users -- mirror of gnexus-auth principals id, sub (unique), email, display_name, profile jsonb, locale, created_at, updated_at, blocked_at user_sessions -- cookie-session pattern, if used id, user_id, created_at, expires_at oauth_states -- PKCE state documents id, slug (unique), title, created_at, deleted_at doc_versions id, document_id, version_no, parent_version_id, content_hash, raw text, body text, frontmatter jsonb, author_user_id, actor_kind, actor_name, via, changeset_id, created_at unique (document_id, version_no) blobs hash pk, content text -- content-addressed deduplication inventory_types name pk, schema_id schemas id, name, version, body jsonb, created_at inventory_items id, type, item_id, data jsonb, current_version_id, deleted_at unique (type, item_id) among live rows inventory_item_versions id, inventory_item_id, version_no, data jsonb, author_user_id, changeset_id, created_at changesets id, author_user_id, summary, reason, status (draft | applied | rejected), created_at, applied_at, validation jsonb change_items id, changeset_id, kind (doc | inventory-item), target, payload jsonb, status validation_runs id, changeset_id, status, issues jsonb, created_at mcp_tokens id, user_id, consumer, name, role, scopes jsonb, token_hash (unique), token_hint, created_at, last_used_at, revoked_at partial unique (user_id, consumer) where revoked_at is null user_prefs user_id, locale audit_log id, actor_user_id, actor_kind, actor_name, via, action, entity_type, entity_id, before jsonb, after jsonb, created_at
Search is a tsvector index on document versions plus a trigram/substring path to preserve the current "find a line containing the query" behavior. Relationships are computed from inventory_items.data as they are today; materialized edges are an optimization, not a v1 requirement.
The new system must close the current functionality before the migration. This table is the acceptance checklist.
| Capability | Current implementation | New implementation |
|---|---|---|
| List documents | Recursive *.md scan, title from first H1 or file stem, frontmatter dict |
Query current document versions |
| Read document | path → {path, frontmatter, body, raw} |
Lookup by slug/id; same response shape |
| Search | Case-insensitive substring, up to 5 matching lines per document | FTS plus substring/line-match path; keep response shape |
| Create/update document | Pending change → write file → validate → rollback on failure | Draft changeset → apply transaction → validate |
| Path safety | Reject escapes, non-.md, denied directories |
Slug/route validation; no filesystem paths |
| Inventory types | *.yml files |
inventory_types rows |
| Inventory read | raw YAML, parsed list, item by id |
JSONB records; raw view is a defined serialization |
| Inventory create/update | patch merge or create append, immutable id |
Change item applied in a transaction |
| JSON Schema validation | Draft 2020-12, per-type mapping | Same schemas stored in schemas |
| Unique inventory IDs | Per-file scan | Unique constraint per type among live items |
| Secret scanning | Regex over Markdown/YAML/JSON/dotenv | Same scan on every candidate version |
| Freshness | Frontmatter presence, stale by interval, missing docs targets |
SQL queries over versions and inventory |
| Relationship graph | Nodes <type>/<id>, edges from known fields, unresolved refs |
Same computation over inventory data; optional materialized edges |
| Pending changes | JSON files, pending/applied/rejected, apply + rollback |
changesets + change_items, transactional apply |
| Git status/diff/commit | Working tree, explicit file list, local commit | Draft changesets, version diff, publish/apply changeset |
| MCP | 17 tools, 9 resources, stdio/SSE, static environment | Same domain tools over HTTP with per-user keys |
| UI | Four tabs, metrics, apply/commit forms | Same views plus history/diff, auth gate, MCP keys, i18n |
| Health | {"status": "ok", "repo_root": ...} |
Handbook contract: no auth, cheap, status plus optional checks.db |
| Deployment | systemd user units, nginx, scripts | Postgres service, migrations, systemd, nginx |
| Tests | 38 tests, real-repo fixtures | Parameterized against DB fixtures; keep behavior contracts |
Deliberately absent today and still absent unless separately requested: document delete/rename, full-file inventory replacement, reject/approval workflow, generated inventory index, visual topology, embedding search.
| Area | Handbook requirement | Current state | Action |
|---|---|---|---|
| Auth | gnexus-auth SSO, mirrored sub |
None | Add PKCE client, session, webhooks |
| MCP transport | Streamable HTTP /mcp-protocol/ |
stdio/SSE | Add HTTP endpoint; keep stdio for dev/tests only |
| MCP keys | Per-user mcp_*, hash + hint, revoke |
None | Add mcp_tokens, guard, UI page |
| Key provisioning | /internal/keys, service secret, allowlist |
None | Add later, before external consumers |
| Actor | is_user / X-Actor, audit fields |
None | Add to write paths and audit |
| UI | Kit, auth gate, drawer nav, GnPageHeader |
Kit only | Add gate, nav, history views |
| i18n | en/uk/ru, account locale | English only | Add i18n module and dictionaries |
| Health | No auth, cheap, status contract | Exposes repo path | Remove topology, add DB check |
| Backups | Separate host, verified restore | Same disk, verified once | Add cron dump, off-host copy, restore drill |
| Secrets | gnexus-creds, .env, references only |
Scanner in validation | Keep scanner; align docs |
| Monitoring | hard-panel + Synapse alerts | None | Add when deployed |
| Notifications | Synapse envelopes | None | Add only if the service emits alerts |
| Docs | Service page in gnexus-book | Page exists | Keep current |
| Git commits | No co-authorship lines | No agent commits yet | Follow 10-platform/git.md |
Read contracts can be kept almost unchanged. Write contracts need an explicit decision because the working-tree model disappears:
propose_* → create a draft changeset/change item;apply_pending_change → apply the changeset transactionally;git_status → list draft changesets and pending items;git_diff → diff a draft against the current version;commit_changes → publish/apply a changeset (or become a deprecated alias).The recommendation is to introduce the new names and keep the old tools as aliases for one transition period, so existing agents do not break. The alternative is a clean rename with updated MCP instructions and tests.
Phases, acceptance criteria, dependencies, and decision gates are in ../00-overview/postgres-migration-roadmap.md.
path as the public key, or switch to UUID + slug with redirects?*.gnexus.space subdomain and public MCP endpoint?server/app/main.py, server/app/mcp_server.py, server/app/pending_changes.py, server/app/validation.py, server/app/freshness.py, server/app/relationships.py, ui/src/main.js