{
"id": "20260924054348-7f5637f4",
"kind": "doc",
"target": "10-systems/applications/gnexus-book.md",
"summary": "Document poisoned-pending protection: validate-before-write, full rollback on failed apply, delete_pending_change tool, corrupt-JSON tolerance",
"reason": "Задача gntodo #3: задокументирована новая защита от отравленных pending-changes (validate-before-write, полный rollback, delete_pending_change, устойчивость к corrupt JSON). Коммит c77bcb1 на gnbook.",
"payload": {
"content": "---\nowner: gmikcon\nstatus: active\nlast_reviewed: 2026-09-24\nreview_interval: 30d\nconfidence: high\nsource_of_truth: ssh-host-verified\n---\n\n# Gnexus Book\n\nGnexus Book is the canonical infrastructure knowledge base and maintenance API for the personal digital and server infrastructure.\n\n## Deployment\n\n- Runs as KVM VM `gnbook` (192.168.1.170) on hypervisor `hp-proliant-dl380-g6` (192.168.1.130).\n- SSH: `ubuntu` on 192.168.1.170 (credentials in gnexus-creds, secret `gnauth-gnbook-ssh`).\n- Repository path: `/home/ubuntu/gnexus-book` (branch `master`).\n- Source of truth: Markdown, YAML inventory, JSON Schema, and Git history.\n\n## Runtime Components\n\n- Backend: FastAPI under `server/`.\n- Agent interface: MCP server under `server/app/mcp_server.py`.\n- UI: Vue/Vite under `ui/`.\n- UI dependency: `gnexus-ui-kit`.\n\n## Endpoints\n\n- REST API: `http://192.168.1.170:8000/` (uvicorn, openapi at `/openapi.json`).\n- MCP (SSE): `http://192.168.1.170:8001/sse`.\n- UI (LAN): `http://192.168.1.170:80/` (nginx serves the built SPA).\n- Services run as user-level systemd units under `user@1000.service`: `gnexus-book-backend.service` (uvicorn :8000) and `gnexus-book-mcp.service` (MCP server).\n\n## Maintenance Model\n\nAgents should prefer structured inventory changes, validation, pending changes, and local commits through the maintenance API.\n\nPending-change queue lives in `90-maintenance/pending-changes/` (untracked JSON files; 11 older ones are git-tracked). Repository-wide validation scans every pending JSON, so a single invalid pending file blocks all applies and commits.\n\nPoisoned-pending protection (since 2026-09-24, commit c77bcb1):\n\n- Create (`propose_doc_change`, `propose_inventory_item_change`, `update_doc`): payloads with secret patterns or unsafe doc targets (outside repo root) are rejected BEFORE any file is written — a rejected request leaves no pending file behind.\n- Apply: on validation failure the target file is rolled back AND the change's own pending JSON is removed (full rollback, both doc and inventory-item paths).\n- `delete_pending_change` (MCP) / `DELETE /changes/{id}` (REST): deletes pending or corrupt records; applied records are refused (409).\n- `list_pending_changes` tolerates corrupt JSON files and reports them with status `corrupt`; corrupt records can be deleted but not applied.\n- `update_doc` cleans up its own pending JSON automatically if apply or commit fails.\n\nFor agent-facing MCP usage rules, see [../../90-maintenance/agent-mcp-usage.md](../../90-maintenance/agent-mcp-usage.md).\n\nNo raw credentials are documented here."
},
"status": "applied",
"created_at": "2026-09-24T05:43:48Z",
"updated_at": "2026-09-24T05:43:49Z",
"applied_at": "2026-09-24T05:43:49Z",
"validation": {
"status": "ok",
"issue_count": 0,
"issues": []
}
}