Sovaign is built on the premise that these risks are not abstract — they are engineering problems with engineering solutions. This post walks through Sovaign's back-end tools, processes, and front-end implementation feature by feature, naming the quality, AI, and IT performance risks each one is designed to address.
Security risks and their measures for treatment are not discussed here for obvious reasons.
SATO: autonomous task orchestration and distributed locking
SATO (Sovaign Autonomous Task Orchestrator) coordinates a pool of AI agents — an Opus 4.6 coordinator directing Sonnet 4.5 workers — that can execute compliance engineering tasks against a shared codebase and Neo4j graph. Tasks are queued, assigned, and tracked through a lifecycle: pending → assigned → running → completed. Dependencies between tasks are declared and enforced. Priority levels P1 through P4 determine scheduling order.
Each agent that claims a task acquires a Redis-backed distributed lock before touching any file. The lock carries a thirty-minute TTL. The pessimistic approach — lock first, work second — is deliberate.
Agent collision is the first risk this eliminates. Without coordination, two agents working on overlapping files produce interleaved writes, corrupted state, and results that are impossible to diagnose after the fact. The distributed lock ensures only one agent holds a given resource at a time.
The second risk is unconstrained autonomous execution. Agents that run without declared dependencies can execute steps before their prerequisites are complete, producing nonsensical or destructive outcomes. SATO's dependency graph prevents this: a task blocked by an incomplete predecessor does not run. The error recovery service detects tasks that stall and returns them to the queue rather than letting them hold resources indefinitely.
Git: checkpointing, memory, and rollback
Before any SATO agent begins a task, the Git checkpointer records the current state of the codebase. On success, changes are committed with attribution — the agent ID and task reference are embedded in every commit message. On failure, the codebase can be restored to the pre-task checkpoint without manual reconstruction.
The repository architecture is dual-track: SATO commits to a working feature branch; clean curated snapshots are pushed to a separate export repository. Priority-1 completions trigger an immediate push; every five completed tasks trigger a batch push. Both behaviours are configurable in the coordinator environment.
AI-introduced code regression without recoverability is the first risk addressed. AI agents make changes at a pace that exceeds human review cadence. Git checkpointing means every autonomous change is reversible to a known-good state.
The second is accountability loss in machine-authored change. In a system where multiple autonomous agents modify shared code, establishing who changed what and why is a compliance requirement in itself. Attributable, task-linked commits provide a full audit trail — a requirement that becomes load-bearing when the system manages compliance evidence for external organisations.
DTAP environment separation: VM for development and testing, VPS for acceptance
Self-explanatory, really. Dev and test cannot kill acceptance or production.
Context compaction prevention: agent memory across sessions
Claude Code, like all large language models, operates within a finite context window (getting larger though). When sessions grow long or are interrupted, accumulated reasoning, decisions, and intermediate state can be lost. Sovaign treats this as an engineering problem rather than an inherent limitation.
The system maintains a persistent Neo4j memory layer across five node types:
sov__AgentSession for session context, sov__AgentLesson for
lessons that survive resets, sov__AgentDecision for design decisions with
supersession tracking, sov__AgentMistake for root-cause-analysed mistakes
with recurrence detection, and sov__AgentEvent for file-level development
events. Session start and end scripts initialise and close sessions with a unique ID, write
summaries on completion, and surface high-severity lessons at the top of every new session.
A separate file, CURRENT_TASK.md, is synced from Neo4j every ten seconds and
survives any context reset as a plain-text record of what is in progress.
Reasoning quality degradation from context loss is the first risk managed. An agent that cannot recall a decision made three sessions ago is likely to contradict it — producing inconsistent compliance outputs or undoing completed work. Persistent memory prevents this regression.
The second is invisible recurrence of the same mistakes. Without a mistake
registry, the same failure mode can occur in session 14 that occurred in session 3, with no
signal that it is a pattern. The sov__AgentMistake node tracks root cause
analysis and links related mistakes explicitly, enabling structural fixes rather than
repeated patches.
Blast radius containment: resource limits and service isolation
Every container in Sovaign runs with explicit CPU and memory limits defined in the Docker Compose configuration. The Graph API, AI gateway, Graphiti service — all capped. These are enforced by Docker as hard limits.
Resource exhaustion cascading across services is the first risk this addresses. A memory leak in one service, or a spike in AI gateway traffic, cannot consume the host's full capacity and starve other services. Each service operates within a defined envelope; a failure inside that envelope is contained there.
The second is unpredictable performance degradation with no visible cause. Without resource limits, a spike in one service appears as mysterious slowness everywhere else. With limits, the boundary makes cause and effect visible: if a service hits its cap, the impact is localised and diagnosable rather than diffuse.
Network separation: localhost binding and the APOC allowlist
Every container port in Sovaign is bound exclusively to internal interfaces. No container is directly reachable from the public network. External traffic enters only through nginx, which terminates TLS and proxies selectively.
Inside Neo4j, the APOC procedure allowlist restricts which operations can execute.
Procedures capable of making outbound HTTP or database connections —
apoc.load.json, apoc.load.html, JDBC connectors — are explicitly
excluded. Only graph-internal operations are permitted.
Unintended service exposure from a configuration error is the first risk managed. A misconfigured Docker Compose update cannot accidentally expose the Neo4j Bolt interface to the public network if the port binding enforces localhost structurally. Localhost binding is a constraint, not a discipline that can be forgotten.
The second is server-side request forgery via graph operations. Without the APOC allowlist, a crafted Cypher query could instruct Neo4j to make outbound HTTP requests to internal infrastructure or external endpoints. The allowlist prevents the database from becoming an unwitting SSRF relay.
RBAC: functional role differentiation across eleven access levels
Sovaign defines eleven functional roles that map to real positions in a compliance
programme: compliance_architect, evidence_manager,
lifecycle_coordinator, discovery_strategist,
bridge_operator, knowledge_steward,
external_auditor, executive_officer,
ai_cost_operator, external_project_member, and
system_administrator. Each role determines which screens are visible and
which actions are available.
The external_auditor role has read-only access to the control catalogue,
evidence library, and audit trail — nothing more. The ai_cost_operator role
sees AI usage costs and budget monitoring only. The executive_officer role
sees readiness scores and SLA dashboards without access to underlying control configuration.
Incorrect evidence submission by users without appropriate authority is the first risk this controls. A read-only auditor cannot submit, modify, or link evidence. An external project member cannot alter framework configuration. The functional role boundary enforces the organisational responsibility model inside the tool.
The second is framework configuration changes corrupting the compliance model.
Obligation chains, hub definitions, and control lifecycles are central to the platform's
reasoning. Restricting write access to compliance_architect and
system_administrator prevents well-intentioned but uninformed modifications
from destabilising the graph state that all compliance scoring depends on.
Hub-and-spoke compliance architecture
Sovaign's compliance data model centres on the scomp__ObligationChain node —
referred to as a hub. Each hub represents a single obligation from a regulatory framework
and contains the reasoning chain that connects that obligation to evidence.
Hubs carry a coverage status — fully_evidenced,
substantially_evidenced, partially_evidenced,
chain_incomplete, or no_evidence — and a lifecycle status from
draft through to deprecated. Other nodes provide verifiable, step-by-step justification for
each coverage conclusion, referencing the specific controls, documents, and relationships
that led to it. There is much more to say about our unique architecture, but we're keeping
that to ourselves — again, for logical reasons.
Evidence without traceability to an obligation is the first risk this model eliminates. In a flat document store, an organisation can accumulate thousands of evidence artefacts with no clear mapping to what they prove. The hub model requires that every piece of evidence attach to a specific obligation via a specific hub. Evidence with no hub attachment does not contribute to coverage scores.
The second is compliance reasoning that cannot survive scrutiny. A coverage conclusion backed only by a percentage score is difficult to defend in an audit. The reasoning step structure ensures every coverage conclusion has an inspectable justification that can be presented as a chain of evidence.
AI gateway: model routing, redaction, and cost controls
Every LLM call passes through the AI gateway before reaching an external provider. The gateway supports OpenAI, Anthropic, Google, local Ollama or anything else you want to hook up. It exposes a unified completion and embeddings interface regardless of the provider selected underneath. Before any message leaves Sovaign's infrastructure, the redaction layer scans for passwords, API keys, and Bearer token patterns. A model allowlist restricts which models can be selected. Per-model token usage and cost are tracked continuously and exposed via Prometheus metrics.
Sensitive compliance data reaching external AI providers is the first risk this controls. Compliance workflows handle obligation text, evidence content, and control descriptions. The redaction layer removes credential patterns before dispatch; the allowlist prevents use of unapproved models that may have different data handling terms.
The second is cost overrun from unconstrained model selection. Without a gateway, an agent could select a frontier model for a task a local Ollama model would handle adequately — repeatedly, at scale. The cost tracking and model allowlist make every AI expenditure visible and bounded.
Node-RED ingestion pipeline: deduplication and sequential processing
Files submitted for ingestion are placed in a staging directory, moved atomically to the
inbox, and processed by a Node-RED flow polling every five seconds. Each file triggers a
two-phase Python script: first, all chunks are embedded using
mxbai-embed-large; second, entities are extracted sequentially using
mistral-nemo:12b (for example, for a typical local setup).
Every inbound file is SHA-256 hashed. A file whose hash matches an existing document is
quarantined as a duplicate. A file matching an existing title with a different hash creates
a SUPERSEDED_BY relationship, preserving version history while making the
newer version authoritative. A global file lock — acquired via flock — ensures
only one ingestion job runs at a time.
Knowledge graph corruption from duplicate ingestion is the first risk eliminated. Without deduplication, re-uploading an amended framework produces redundant entity nodes, inflated coverage scores, and contradictory obligation chains — silently. The hash check catches this at the boundary.
The second is concurrent processing conflicts on a resource-constrained host. Two ingestion jobs running simultaneously on a two-CPU VPS compete for the same Ollama process and write to overlapping graph regions. The global lock enforces sequential execution regardless of how many files arrive simultaneously.
Chunk quality filtering
After a document is split into chunks for embedding, not all chunks contain meaningful compliance content. Page numbers, table of contents entries, horizontal rules, continuation markers, and standalone headers produce embeddings that are semantically noise. The chunk quality router applies fourteen regex filter patterns against every chunk before embedding. Chunks below fifty characters of substantive content after cleanup are discarded. A retroactive cleanup endpoint allows existing low-quality chunks to be removed without re-ingesting the source document.
Semantic pollution in the knowledge graph is the first risk this addresses. A low-quality embedding for a page number or a divider line can surface as a false positive in similarity searches, causing an obligation to appear evidenced by a chunk that contains no relevant content.
The second is wasted compute on meaningless embeddings. Embedding is the most resource-intensive phase of ingestion on the VPS. Filtering noise chunks before this phase reduces ingestion time for long documents without affecting the quality of the output graph.
Document versioning and supersession
When a document already active in the graph is re-submitted, Sovaign does not overwrite
the existing record. If the document is in active status, a new
sc__Document node is created and linked to its predecessor via a
SUPERSEDED_BY relationship with a major version increment. If the document is
in validated or approved status, an in-place minor version update
is applied. Chunk-to-version mappings are preserved through the
CHUNK_OF_VERSION relationship.
Outdated document versions remaining authoritative is the first risk this addresses. Without versioning, replacing a document means either overwriting the original — destroying history — or accumulating multiple copies with no way to determine which is current.
The second is evidence traceability breaking across a document update. When an obligation chain references a specific evidence chunk and that chunk's source document is revised, the chunk-to-version relationship ensures the reference remains valid and the lineage is preserved.
Slack and webhook notifications: sanitisation and rate limiting
Sovaign sends outbound notifications to Slack (and if configured, Teams, Discord, and Outlook) via webhook. Before any message is dispatched, the notification router passes content through a sanitisation layer that redacts credential patterns. Webhook URLs are validated against a provider allowlist; HTTP endpoints are rejected. Rate limiting is enforced at one hundred messages per hour per channel — a hard limit in code at this time, not a configurable guideline.
Compliance and operational data leaking through outbound notifications is the first risk managed. Agent actions and audit events may reference content that contains sensitive identifiers. The redaction layer removes these before dispatch regardless of what triggered the notification.
The second is notification loops creating signal noise or system instability. A misconfigured alert that fires on every graph write would flood a Slack channel with hundreds of messages per hour. The rate limit caps this at one hundred per channel, making runaway notification loops recoverable rather than catastrophic.
Error recovery: deadlock detection and orphan resolution
The error recovery service monitors the task queue continuously. It detects agents that have claimed a task but have not reported progress within a threshold window. Claimed tasks are returned to the pending queue. Redis locks whose TTL has expired are released. The orphan recovery service runs on a five-minute cycle with a two-hour task timeout — reflecting the realistic duration of complex AI tasks on a resource-constrained host — and recovers tasks that have lost their assigned agent without manual intervention.
Permanent queue blockage from agent deadlock is the first risk addressed. A single failing agent that holds a lock indefinitely would stall all dependent tasks. The thirty-minute Redis TTL and automatic orphan recovery prevent this from requiring manual intervention.
The second is silent failure accumulation. Without active monitoring, recurring task failures become visible only through degraded compliance output — not through a system signal. The error recovery service tracks failure counts and escalates recurring patterns rather than silently retrying.
Action Center: human-in-the-loop escalation for 24/7 agent operation
SATO agents run continuously — including overnight and across weekends. Autonomous operation at that scale means no human is watching the majority of agent decisions as they happen.
The back-end includes a structured agent help request API with four priority levels (low, medium, high, critical), six categories (clarification, approval, blocked, error, decision, other), and a full lifecycle from pending through to resolved, cancelled, or expired. The infrastructure exists for an agent to signal that it needs human input before proceeding, and for a human to respond with direction that the agent can act on.
Whether agents actively invoke this in practice, and how their state changes in response to a pending help request, depends on how individual SATO tasks are authored — it is not enforced automatically by the orchestrator. The mechanism is available; its use is a function of task design.
Separately, the session memory system tracks agent mistakes with root cause analysis and recurring pattern detection. A mistake that occurs in session 3 and again in session 11 is not treated as two isolated incidents — it is flagged as a pattern, surfaced in the next session start summary, and treated as a structural problem requiring a fix.
Compounding errors from unreviewed autonomous decisions is the first risk this infrastructure addresses. An agent that proceeds through genuine ambiguity rather than signalling it does not produce one wrong result — it produces a cascade of downstream conclusions built on a wrong foundation. The help request mechanism exists to stop that cascade at the point of uncertainty.
The second risk is quality drift invisible to the team until it is audited. The mistake registry and recurring pattern detection create an active quality signal — not just an absence of alerts — so that systematic reasoning problems surface during development rather than during an external compliance review. In case of a total mess-up: we have Git.
Compliance snapshots and drift alerting
Sovaign captures point-in-time snapshots of compliance posture — active controls, evidence mappings, freshness scores, and gap status — at configurable intervals. Drift alerting compares current state against a baseline and surfaces controls that have changed without a corresponding evidence update.
Inability to reconstruct compliance posture at an audit date is the first risk managed. Auditors routinely ask what the compliance state was at a specific date — not today, but six months ago. Without snapshots, the answer requires manual reconstruction from change logs. With snapshots, it is a query.
The second is control drift going undetected between review cycles. A control that was evidenced in January may be invalidated by an infrastructure change in February without triggering a review. Drift alerting surfaces this before the next formal audit rather than during it.
Audit readiness score and stale controls
The audit readiness score is a 0–100 composite across four components, each with a defined weight: evidence coverage forty percent, evidence freshness twenty percent, gap score twenty percent, and SLA compliance twenty percent. No single dimension can mask a failure in the others.
Stale controls are detected on two separate thresholds. Controls not reviewed within ninety days are flagged for review staleness. Controls with no evidence update within one hundred and eighty days are flagged for evidence staleness. These are separate alert types, not a single escalating threshold.
False confidence in compliance posture is the risk the composite score addresses. A single-dimension score can be satisfied with expired or low-relevance documents. The multi-dimensional composite prevents any single metric from conveying safety that the overall posture does not support.
The second is evidence decay between audit cycles. Evidence valid at the time of ingestion does not remain valid indefinitely. Without active freshness monitoring, a compliance graph accumulates a growing gap between what it reports as evidenced and what would survive scrutiny.
AI criticality calibration: confidence thresholds and recommendation depth
Sovaign's AI behaviour is calibrated through a criticality level setting — conservative, moderate, or aggressive — that governs how the system applies AI-generated content. Conservative mode applies a high confidence threshold before accepting AI-generated statements or recommendations; aggressive mode lowers that threshold and increases recommendation depth and verbosity. The setting affects risk scoring weights, statement extraction confidence requirements, and whether AI-generated content requires human review before being committed to the graph.
AI-generated compliance content accepted without sufficient confidence is the first risk this controls. Without a confidence threshold, a low-certainty entity extraction or obligation mapping can be written directly into the compliance graph, propagating uncertainty as if it were fact. The calibration layer makes that threshold explicit and adjustable.
The second is AI recommendation depth mismatched to operational capacity. An organisation in an aggressive calibration mode receives more recommendations, more verbosely, with lower confidence filtering. If that organisation lacks the capacity to review what is surfaced, the volume becomes noise rather than signal. The three-level calibration allows the AI's output to be matched to what the team can actually act on.
These are not theoretical mitigations. Each one exists in the codebase because we encountered the risk it prevents — either in a live incident, a near-miss during development, or a failure mode we recognised before it occurred. The list will grow as the system does.