Memory
# DocuClear Compliance Engine — Graph Versioning Design ## Core Rule A GraphVersion is a named, immutable snapshot of a complete node+edge bundle. AssessmentRuns always bind to a specific graph_version_id — never against 'current' or 'latest'. ## Three Graph Environments | Environment | Purpose | Assessments allowed? | Promoted by | |---|---|---|---| | dev | Active construction — Kreuzberg/Crawlberg ingestion, rule authoring, editing | No (mutable) | Flow ingestion pipeline | | test | Frozen candidate — regression QA, law-firm scenario validation | Yes (flagged as test) | Manual promotion from dev | | production | Live canonical graph — immutable once active | Yes (canonical) | Manual promotion from test with human sign-off | ## GraphVersion Entity (SurrealDB) - graph_version_id — e.g. semantic "v1.4.2" - label — human name, e.g. "EU AI Act initial + UK GDPR baseline" - environment — "dev" | "test" | "production" - status — "building" | "candidate" | "active" | "retired" - source_refs[] — Kreuzberg/Crawlberg document IDs that fed this version - created_at, promoted_at, promoted_by - retired_at, retired_by - predecessor_version_id — chain for audit trail - integrity_hash — hash of all nodes+edges in this bundle - change_summary — human-readable diff description - regime_coverage[] — e.g. ["EU-AI-ACT", "UK-GDPR", "DUAA"] ## Node-Level Versioning All normative nodes (DecisionRule, Obligation, etc.) carry: - graph_version_id — which version they belong to - source_ref — Kreuzberg document + extraction ID - ingested_at, ingested_by — e.g. "kreuzberg-flow-v2" Nodes in production are NEVER updated in place. Changes require new dev ingestion → new GraphVersion. ## Lifecycle State Machine Kreuzberg/Crawlberg ingest → dev (mutable/building) → [Flow: promote to test action] → test (frozen candidate) → [regression tests pass + human sign-off] → production/active → [new version promoted] → retired (immutable, addressable for replay) ## Kreuzberg + Crawlberg Ingestion Pipeline 1. Crawlberg fetches/crawls source regulatory documents (legislation, ICO guidance, etc.) 2. Kreuzberg applies document intelligence — extracts provisions, obligations, conditions — emits structured objects 3. Flow ingestion stage receives Kreuzberg output, upserts nodes/edges into dev graph, tags each with source_ref (Kreuzberg document ID) 4. "Promote to test" Flow action snapshots dev — freezes node/edge set as named GraphVersion (environment: test) 5. After QA, "promote to production" activates it and retires previous production version ## Regression Test Gate (test → production) Before promotion, Flow automatically runs the law-firm-with-AI-product stress test scenario against the candidate version and compares against known-good baseline. If traversal output changes unexpectedly, promotion blocks and flags for review. This is the automated correctness gate. ## Open Decisions (not yet resolved — July 2026) 1. **Promotion trigger mechanism** — manual button in Flow admin UI vs. role/token-gated API call. Production promotion must require explicit human action + OpenLogger audit entry. 2. **Versioning scheme** — semantic (v1.4.2) vs. date-stamped (2026-07-02-r1) vs. UUID. Semantic preferred for change communication. 3. **Partial regime updates** — full new GraphVersion for all regimes on any change (simpler, safer for auditability) vs. per-regime versioning (granular but adds traversal resolution complexity). Full versioning is the safer default. ## Integration with Assessment Lifecycle Stage 2 of the 7-stage assessment lifecycle: "Resolve graph" — Flow selects the active production GraphVersion and binds it to the AssessmentRun via graph_version_id. This version_id is then immutably stored in the decision trace envelope in OpenLogger.
Tags: docuclear, graph-versioning, kreuzberg, crawlberg, compliance-engine, surrealdb, design, kind:semantic, status:canonical, project:docucleargraph — Source: claude — 2026-07-02 16:32:09 UTC