Framework Architecture
System Architecture
High-level overview showing how the 6 governance services integrate with your application and data layer.
Request Flow Sequence
Typical AI decision flow with governance enforcement: from user request through boundary checking to human approval.
Deployment Architecture
Production deployment reference showing Node.js application, MongoDB, and monitoring stack configuration.
Core Services
BoundaryEnforcer
Implements Tractatus 12.1-12.7: AI cannot make values decisions without human approval.
- VALUES (12.1) - Ethics, privacy, principles
- INNOVATION (12.2) - Architectural decisions
- WISDOM (12.3) - Strategic judgment
- PURPOSE (12.4) - Goal definition
const { checkBoundary } = require('./services/BoundaryEnforcer')
const result = await checkBoundary(decision)
// Returns: { allowed: false, requires_human: true }
InstructionPersistenceClassifier
Classifies instructions by quadrant (STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM) and persistence level (HIGH/MEDIUM/LOW).
- Quadrant (STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM)
- Persistence (HIGH/MEDIUM/LOW)
- Temporal scope (PROJECT/SESSION/TASK)
- Explicitness score (0.0-1.0)
const { classify } = require('./services/InstructionPersistenceClassifier')
const result = await classify(instruction)
// Returns: { quadrant, persistence, temporal_scope, explicitness }
CrossReferenceValidator
Validates AI actions against stored instructions to prevent pattern recognition overrides.
- Checks action against HIGH persistence instructions
- Detects conflicts (pattern vs explicit instruction)
- Provides correct parameters when rejected
const { validate } = require('./services/CrossReferenceValidator')
const result = await validate(action, instructions)
// Returns: { status: 'REJECTED', conflicts, correct_parameters }
ContextPressureMonitor
Monitors token usage and context pressure, triggering safety protocols at thresholds.
- NORMAL (0-50%) - Full operation
- ELEVATED (50-75%) - Increase verification
- HIGH (75-90%) - Reduce complexity
- CRITICAL (90%+) - Suggest handoff
const { analyzePressure } = require('./services/ContextPressureMonitor')
const result = await analyzePressure(tokens, messages)
// Returns: { level: 'HIGH', score: 82, shouldReduce: true }
MetacognitiveVerifier
Verifies action reasoning and confidence, requiring confirmation for low-confidence actions.
- Confidence scoring (0.0-1.0)
- Selective mode (HIGH persistence only)
- Requires confirmation if confidence < 0.7
const { verify } = require('./services/MetacognitiveVerifier')
const result = await verify(action, reasoning)
// Returns: { confidence: 0.65, requires_confirmation: true }
PluralisticDeliberationOrchestrator
Manages multi-stakeholder deliberation ensuring value pluralism in decisions.
- Stakeholder perspective tracking
- Value conflict detection
- Deliberation session management
- Precedent storage
const { orchestrate } = require('./services/PluralisticDeliberationOrchestrator')
const result = await orchestrate(decision, stakeholders)
// Returns: { decision, perspectives, conflicts_identified }
π Source Code
All services are available in the GitHub repository: /src/services/
API Reference
BoundaryEnforcer.checkBoundary()
const { checkBoundary } = require('./src/services/BoundaryEnforcer.service')
// Check if decision crosses Tractatus boundary
const decision = {
domain: 'values',
description: 'Change privacy policy to enable analytics',
context: { /* ... */ }
}
const result = await checkBoundary(decision)
// Returns:
{
allowed: false, // AI cannot proceed
requires_human: true, // Human decision required
boundary: "12.1", // Tractatus boundary violated
principle: "Values cannot be automated, only verified",
reason: "Decision involves values domain",
ai_can_provide: [ // What AI CAN do
"Analyze privacy implications",
"List alternative approaches",
"Document tradeoffs"
]
}
InstructionPersistenceClassifier.classify()
const { classify } = require('./src/services/InstructionPersistenceClassifier.service')
const instruction = "Always use MongoDB on port 27017"
const result = await classify(instruction, context)
// Returns:
{
quadrant: 'SYSTEM', // Decision domain
persistence: 'HIGH', // How long to remember
temporal_scope: 'PROJECT', // Scope of applicability
verification_required: 'MANDATORY', // Verification level
explicitness: 0.85, // Confidence score
parameters: {
port: "27017",
database: "mongodb",
service: "mongodb"
}
}
Persistence: HIGH (override all), MEDIUM (session-scoped), LOW (can be superseded)
CrossReferenceValidator.validate()
const { validate } = require('./src/services/CrossReferenceValidator.service')
// User instructed: "Use port 27027"
// AI attempting: port 27017 (pattern recognition)
const action = {
type: 'db_config',
parameters: { port: 27017 }
}
const instructions = await getStoredInstructions() // From MongoDB
const result = await validate(action, instructions)
// Returns (CONFLICT):
{
status: 'REJECTED',
conflicts: [
{
instruction_id: 'inst_042',
instruction: 'Use MongoDB port 27027',
persistence: 'HIGH',
conflict: 'Proposed port 27017 conflicts with instruction port 27027'
}
],
correct_parameters: {
port: 27027 // Use this instead
}
}
ContextPressureMonitor.analyzePressure()
const { analyzePressure } = require('./src/services/ContextPressureMonitor.service')
const pressure = await analyzePressure({
currentTokens: 150000,
maxTokens: 200000,
messageCount: 45,
errorCount: 2
})
// Returns:
{
level: 'HIGH', // NORMAL|ELEVATED|HIGH|CRITICAL
score: 75, // 0-100 percentage
shouldReduce: true, // Reduce complexity
recommendations: [
'Consider handoff to new session',
'Reduce verbose explanations',
'Increase verification for remaining actions'
],
thresholds: {
tokens: 75, // 75% of max
messages: 64, // 45/70 messages
errors: 40 // 2 errors
}
}
Integration Examples
Express Middleware Integration
const express = require('express')
const { BoundaryEnforcer } = require('./services')
const app = express()
// Add boundary checking middleware
app.use(async (req, res, next) => {
if (req.body.decision) {
const check = await BoundaryEnforcer.checkBoundary(
req.body.decision
)
if (!check.allowed) {
return res.status(403).json({
error: 'Boundary violation',
reason: check.reason,
alternatives: check.ai_can_provide
})
}
}
next()
})
Instruction Validation
const {
InstructionPersistenceClassifier,
CrossReferenceValidator
} = require('./services')
// Classify and store user instruction
const classification = await
InstructionPersistenceClassifier.classify(
userInstruction
)
if (classification.explicitness >= 0.6) {
await storeInstruction(classification)
}
// Validate AI action before execution
const validation = await
CrossReferenceValidator.validate(
proposedAction,
await getStoredInstructions()
)
if (validation.status === 'REJECTED') {
console.error(validation.conflicts)
useCorrectParameters(
validation.correct_parameters
)
}
MongoDB Data Models
GovernanceRule
{
id: "inst_001",
text: "Use MongoDB port 27017",
quadrant: "SYSTEM",
persistence: "HIGH",
temporal_scope: "PROJECT",
explicitness: 0.85,
parameters: { port: "27017" },
active: true,
timestamp: "2025-10-21T10:00:00Z"
}
AuditLog
{
action: "boundary_check",
result: "REJECTED",
boundary: "12.1",
decision: { /* ... */ },
timestamp: "2025-10-21T11:30:00Z",
session_id: "2025-10-21-001"
}
Deployment
Requirements
-
β’
Node.js: v18.0.0+ (v20+ recommended)
-
β’
MongoDB: v7.0+ (for instruction persistence)
-
β’
Memory: 2GB+ recommended
Installation
# Clone the framework repository
git clone https://github.com/AgenticGovernance/tractatus-framework.git
cd tractatus-framework
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env with your MongoDB URI
# Initialize MongoDB indexes
node scripts/init-db.js
# Start the server
npm start
π Full Documentation
Complete deployment guide available at: /deployment-quickstart/
Integration Patterns
Common architectural patterns for integrating Tractatus into existing systems.
Middleware Integration
Insert governance checks as middleware in your request pipeline. Suitable for API-based AI systems.
Use Case: REST APIs, Express.js applications
app.use(governanceMiddleware({
services: ['BoundaryEnforcer', 'CrossReferenceValidator'],
mode: 'strict',
auditAll: true
}))
Event-Driven Governance
Trigger governance checks via events. Suitable for async workflows and microservices.
Use Case: Message queues, event buses, async processing
eventBus.on('ai:decision', async (event) => {
const result = await checkBoundary(event.decision)
if (!result.allowed) {
await requestHumanApproval(event, result)
}
})
Pre/Post-Action Hooks
Validate actions before and after execution. Current production pattern for Claude Code.
Use Case: LLM tool use, autonomous agents
hooks: {
PreToolUse: governanceCheck,
PostToolUse: auditLog,
SessionStart: loadInstructions,
SessionEnd: cleanup
}
Sidecar Governance Service
Deploy governance as a separate service. Suitable for multi-LLM or polyglot environments.
Use Case: Kubernetes, containerized deployments
// AI Service makes HTTP call
const govResponse = await fetch(
'http://governance-sidecar:8080/check',
{ method: 'POST', body: JSON.stringify(decision) }
)
Development Roadmap & Collaboration
Tractatus is an active research framework. We welcome collaboration on priority development areas.
π Priority Areas for Development
These initiatives represent high-impact opportunities for framework enhancement. Technical contributors, researchers, and organizations are encouraged to engage.
Multi-LLM Support
Status: Research Phase
Extend governance to GPT-4, Gemini, Llama, and local models. Requires adapting hook architecture to different LLM interfaces.
Language Bindings
Status: Community Interest
Python, Go, and Rust implementations to serve broader developer communities. Core logic is portable; MongoDB integration is universal.
Cloud-Native Deployment
Status: Reference Architectures Needed
Terraform/Helm charts for AWS, Azure, GCP. Include managed MongoDB (Atlas), auto-scaling, and monitoring integration.
AI Framework Integration
Status: Conceptual
Adapters for LangChain, Semantic Kernel, AutoGPT, and CrewAI. Enable governance for existing agent frameworks.
Enterprise-Scale Performance
Status: Validation Needed
Optimize for 1000+ concurrent AI agents. Requires caching strategies, rule compilation, and distributed audit logging.
Extended Governance Services
Status: Research
Cost monitoring, rate limiting, PII detection, adversarial prompt defense. Domain-specific services for regulated industries.
Get Involved
Tractatus is Apache 2.0 licensed research. We welcome contributions, pilot implementations, and collaborative research partnerships.
π¨βπ» Technical Contributors
Implement features, fix bugs, improve documentation
β Contributing Guideπ¬ Research Partners
Validation studies, academic collaboration, case studies
β research@agenticgovernance.digitalπ’ Organization Pilots
Production deployments, enterprise requirements, feedback loops
β Submit Case StudyWhy Collaborate? Tractatus addresses real gaps in AI safety. Early adopters shape the framework's evolution and gain expertise in structural AI governanceβa differentiating capability as regulatory requirements mature.
Resources
Documentation
Reference Implementation
This website (agenticgovernance.digital) runs on Tractatus governance.
- Services: 22 governance components
- Data Models: 29 MongoDB schemas
- Test Coverage: 35 test suites
- β Collaboration Repository
Support
Questions about implementation or integration?
- β’ GitHub Issues
- β’ GitHub Discussions
- β’ research@agenticgovernance.digital