Lab L5 — Role Capability Matrix & Tool Scoping Engine

Phase 3 · ROLES — Lab L5
Status: Authored & Empirically Verified.
Student Lab Package: Authenticated Direct Download from VTAlgo Platform
Branches: main (starter template) · solution (reference architecture).
Video Master: 05:21 min @ 1080p FHD 60fps NVENC · Audio Elmer Oficial (-16 LUFS, Zero BGM) · Curated Synchronized Subtitles (ASS).
Canonical Path: Student repo only — not E:\bridle, not the Kratos live product.

1. Laboratory Objective

Construct from scratch in pure Go an industrial Role Capability Matrix & Dynamic Tool Scoping Engine, proving empirically that agent safety and authority boundaries cannot be entrusted to natural language prompts.

The student implements:

• Constant-time $O(1)$ capability authorization via register-level bitmasks.
• Ephemeral, HMAC-SHA256-signed capability tokens with step quotas and directory sandboxing.
• An in-flight tool interceptor backed by Go compiler static AST oracles.
• An ephemeral subagent recycler that deterministically eliminates persona drift.

2. The Five Cardinal Subsystems

┌──────────────────────────────────────────────────────────────────────────┐
│             ROLE CAPABILITY MATRIX & SCOPING ENGINE (PURE GO)            │
│                                                                          │
│  ┌─────────────────────────┐           ┌──────────────────────────────┐  │
│  │  1. Bitmask Capability  │           │  2. Dynamic Tool Scoping     │  │
│  │     Matrix [uint64]     ├──────────►│     Engine (HMAC-SHA256)     │  │
│  │  (O(1) Nanosecond Gate) │           │  (Step Quotas / Sandbox)     │  │
│  └─────────────────────────┘           └──────────────┬───────────────┘  │
│                                                       │                  │
│                                                       ▼                  │
│  ┌─────────────────────────┐           ┌──────────────────────────────┐  │
│  │  4. Ephemeral Subagent  │           │  3. In-Flight Tool           │  │
│  │     Recycler (Anti-Drift)│◄──────────┤     Interceptor (AST Oracle) │  │
│  │  (State Checkpointing)  │           │  (go/parser Static Audit)    │  │
│  └───────────┬─────────────┘           └──────────────────────────────┘  │
│              │                                                           │
│              ▼                                                           │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  5. Deterministic In-Memory Test Suite (10/10 in <50ms)            │  │
│  └────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘

1. Bitmask Capability Matrix (pkg/matrix)

• Represents atomic capabilities as typed uint64 bitflags: CapReadFiles, CapWriteCode, CapRunTests, CapGitCommit, CapDeploy.
• Evaluates role authorization via CPU register-level bitwise AND (roleMask & toolMask == toolMask).
• Zero reflection, zero dynamic string lookups, nanosecond-scale constant-time verification.

2. Dynamic Tool Scoping Engine (pkg/scoping)

• Monotonically attenuates capabilities based on active FSM state.
• Issues ephemeral CapabilityToken structs cryptographically signed with HMAC-SHA256.
• Enforces strict execution step quotas ($TTL$) and absolute directory path sandboxes.
• Forbids token replay and detects signature forgery instantly.

3. In-Flight Tool Interceptor (pkg/interceptor)

• Kernel-level pre-dispatch hook intercepting all code writes prior to disk persistence.
• Uses Go's native go/parser and go/ast packages to parse source AST in memory.
• Enforces negative invariants: blocks forbidden package imports (os/exec, net/http, syscall) and directory traversal.
• Issues typed rejection verdicts with zero reliance on model self-policing.

4. Ephemeral Subagent Recycler (pkg/recycler)

• Eliminates persona drift and constraint decay across extended multi-turn runs.
• Monitors execution step counters and consecutive contract breaches.
• On breach threshold: checkpoints verified state, terminates the compromised worker goroutine, and spawns a pristine instance with clean context and re-anchored contracts.

5. Deterministic Test Suite (tests/matrix_test.go)

• 10/10 deterministic tests pass in under 50 milliseconds with zero flakiness.
• Validates bitmask operations, token forgery rejection, AST import containment, sandbox isolation, and clean worker recycling.

3. Hands-On Verification Protocol

To run the complete test suite locally:

cd hefesto-lab5-role-matrix
go test -v -race ./...

All 10 deterministic tests must pass with zero data races.