Skip to main content

# Framework Implementation Guide

Technical documentation for integrating the 6 Tractatus governance services into your AI systems. Production-tested architecture and real code examples.

## Framework Architecture

### Service Interaction Flow

Download SVG

### Service Trigger Conditions

Download SVG

## Core Services

### BoundaryEnforcer

Implements Tractatus 12.1-12.7: AI cannot make values decisions without human approval.

Boundaries:

- 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).

Classification:

- 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.

Validation:

- 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.

Pressure Levels:

- 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.

Verification:

- 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.

Features:

- 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"
      ]
    }

Keywords detected: value, principle, ethic, moral, should, ought, right, wrong, privacy, policy, trade-off, etc.

### 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"
      }
    }

Quadrants: STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STORAGE
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/

## Resources

### Documentation

- → GitHub Repository
- → Full Documentation
- → Live Demos

### Source Code

- → /src/services/ 11 services
- → /src/models/ 10 MongoDB models
- → /tests/ 17 test files

### Support

Questions about implementation or integration?

- • GitHub Issues
- • GitHub Discussions
- • research@agenticgovernance.digital