Bristlecone Logic

BRISTLECONE LOGIC, LLC — SYSTEM ARCHITECTURE & DEVELOPMENT MASTER LOG

Document Status: Production Baseline Approved Date Range: July 20, 2026 – August 1, 2026 Core Toolchain: Linux, uv (Astral), Python 3.12+, FastAPI, Pydantic v2, PostgreSQL 16, Redis, Nginx, Docker, Streamlit, Web3.py, AWS KMS (secp256k1) Engineering Philosophy: First-Principles, Spec-Driven Zero-Trust Architecture governed by schema-validated contracts, deterministic state machines, and cryptographically signed execution boundaries.

1\. Executive Summary & Core Objective

The primary objective of Bristlecone Logic, LLC is to design, construct, and deploy a high-performance, deterministic Machine-to-Machine (M2M) microservice engine. The core platform is engineered to support autonomous AI agent swarms, sub-cent metering, automated balance/rate management, hardware-isolated L2 treasury sweeping, and real-time auditability. ┌────────────────────────────────────────────────────────┐ │ Layer 5: Diagnostics & Observability │ │ (OpenTelemetry / Trace Management / Audit) │ ├────────────────────────────────────────────────────────┤ │ Layer 4: Transaction & Asset Isolation │ │ (HMAC Payload Signing / x402 Treasury Gate) │ ├────────────────────────────────────────────────────────┤ │ Layer 3: Orchestration & State Machine │ │ (Commit DAG / Invigilator / BYOK / Metering) │ ├────────────────────────────────────────────────────────┤ │ Layer 2: Core Business & API Logic │ │ (FastAPI Microservices / Pydantic Schemas) │ ├────────────────────────────────────────────────────────┤ │ Layer 1: Deterministic Runtime Sandbox │ │ (Astral 'uv' Engine / Schema Validation) │ ├────────────────────────────────────────────────────────┤ │ Layer 0: Hardware-Isolated Settlement │ │ (AWS KMS HSM / Base L2 / Coinbase Vault Sweep) │ └────────────────────────────────────────────────────────┘

2\. System Architecture (The 6-Layer Zero-Trust Engine)

Layer 0: Hardware-Isolated On-Chain Settlement

• Engine: AWS KMS HSM (us-west-2, ECC\_SECG\_P256K1), Base L2 (Chain ID 8453), Web3 Engine.
• Responsibility: Manages off-server private key security; executes raw ASN.1 DER signature parsing, EIP-2 low-S canonicalization, and EIP-1559 offline raw transaction signing for automated USDC revenue sweeping.

Layer 1: Deterministic Runtime Sandbox & Schema Base

• Engine: uv by Astral (bypassing pip/pyenv) managing pinned Python 3.12+ virtual environments (.venv).
• Responsibility: Implements strict data contracts and Pydantic schemas (app/layer1\_schemas/base.py). Rejects unapproved payloads or non-compliant agent names prior to network routing.

Layer 2: Core Microservice Routing & Execution Engine

• Engine: FastAPI / Uvicorn running an Application Factory pattern (create\_app()).
• Responsibility: Handles high-concurrency API request routing, security middleware execution, input sanitization, and structured payload processing.

Layer 3: Orchestration, Commit DAG & Metered Gateway

• Engine: SQLite/PostgreSQL State Stores, Native GeminiWorker integration, Model Context Protocol (MCP) tool registries, and Redis hot-path metering.
• Responsibility: Governs agent decision loops, enforces the Commit DAG (Directed Acyclic Graph) for execution lineage, manages BYOK (Bring Your Own Key) routing, and handles real-time token/usd metering.

Layer 4: Cryptographic Integrity & Treasury Isolation

• Engine: HMAC-SHA256 Signer (app/layer4\_crypto/signer.py) and Treasury Gates (app/layer4\_ledgers/treasury.py).
• Responsibility: Signs and verifies all request envelopes; enforces hard spending ceilings ($50.00 single-transaction limit) to prevent runaway autonomous agent costs.

Layer 5: Observability, Audit Persistence & Telemetry

• Engine: OpenTelemetry standards, immutable JSON-Lines (audit\_log.jsonl), and PostgreSQL audit logs.
• Responsibility: Captures UTC timestamped trace events, execution latencies, and output quality checks across all system transitions.

3\. Dendro Taxonomy Enforcement Matrix

Agent identity across all system layers is strictly validated at Layer 1 using soft prefix matching (@field\_validator("agent\_name")). Agent names must begin with an approved prefix followed by a hyphen or underscore (e.g., sapling\_01, resin-gate).

4\. Subsystem Specifications

A. The Commit DAG Engine (Task Lineage)

• Commit Nodes (commit\_nodes): Every sub-task execution generates an immutable commit record holding parent commit pointers (parent\_ids), deterministic SHA-256 state hashes, agent roles, and input/output payloads.
• Commit Edges (commit\_edges): Links parent execution nodes to child nodes.
• State Rollback: If a downstream worker fails, the system rewinds state to the last valid parent commit hash without corrupting database integrity.

B. Metered Gateway & BYOK Architecture

• API Key Security: Machine-to-machine tokens (bcl\_...) are authenticated via SHA-256 hashes (key\_hash). Plaintext keys are never stored.
• Metering Engine: Redis Lua scripts (METER\_LUA) atomically track rate limits (Requests Per Minute) and execute micro-cent balance deductions (INCRBYFLOAT with negative cost deltas) in under 1ms.
• BYOK Support: Tenants can supply custom LLM keys (custom\_llm\_key), bypassing Master Gateway charges while maintaining telemetry logging.
• Automated Low-Balance Sweep: A 15-minute background cron task evaluates tenant credit balances. Accounts falling below $5.00 USD trigger asynchronous HTTP webhooks (tenant.low\_balance\_warning) and emit Prometheus telemetry metrics (bristlecone\_low\_balance\_alerts\_total).

C. Hardware-Isolated Automated USDC Sweeper Daemon

• AWS KMS Signing Engine (kms\_signer.py): Uses an AWS KMS HSM key (us-west-2, bristlecone-sweeper-bot) to sign Base L2 transactions without ever exposing private keys on disk or in memory. Converts ASN.1 DER signatures to EIP-2 canonical format with $v$ recovery value calculation.
• Sweeper Daemon (sweeper\_daemon.py): Polls Base L2 RPC nodes every 10 seconds, checks hot-wallet USDC balance (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), verifies native ETH gas reserves, constructs raw ERC-20 transfer payloads (0xa9059cbb), and routes sweeps directly to corporate custody.
• System Daemon (bristlecone-sweeper.service): Runs asynchronously under systemd with auto-restart and journalctl logging. Operated in DRY\_RUN\_MODE \= True during pre-deployment verification.

5\. Engineering Ledger & Timeline (July 20 – August 1, 2026\)

July 20, 2026: Blueprinting & Core 5-Layer Baseline

• Baseline Setup: Initialized the isolated environment using uv, established pyproject.toml, locked core dependencies, and configured AGENTS.md.
• Layer 1 Taxonomy Locking: Built prefix validation rules rejecting rogue agent names (422 Unprocessable Entity) while permitting valid Dendro prefixes.
• Treasury Gate Test: Verified pre-execution rejection of a simulated $150.00 transaction due to breaching the $50.00 single-transaction hard limit.

July 21, 2026: Zero-Trust Defense & Cryptographic Payload Signing

• HMAC-SHA256 Engine: Implemented PayloadSigner in app/layer4\_crypto/signer.py using canonical JSON serialization (sort\_keys=True) and hmac.compare\_digest for constant-time validation.
• Tamper Probe: Intercepted valid payloads, modified body attributes, and verified immediate 403 Forbidden rejections at Layer 2\.
• Durable Telemetry: Implemented append-only JSONL logging (audit\_log.jsonl) across all state graph transitions.

July 22, 2026: Externalized Secrets, Tool Gating & Streamlit UI

• Secrets Hardening: Refactored runtime environment parsing using python-dotenv, removing hardcoded secret fallbacks.
• Tool Execution Gating: Deployed tool\_gater.py enforcing dual-gate checks (explicit tool whitelist \+ HMAC signature) before executing function calls.
• Control Panel & Daemon: Created Streamlit frontend (dashboard.py) connected to FastAPI; mounted bristlecone-logic.service background daemon under systemd.

July 23, 2026: SQLite Persistence & Native Gemini Worker Integration

• SQLite State Engine: Built SQLiteStateStore (state\_store.py) to manage local task execution state and audit logging offline.
• Native Gemini Worker: Encapsulated GeminiWorker (gemini-flash-latest) inside Layer3Orchestrator, translating natural language intent directly into structured, schema-compliant tool parameters.

July 24, 2026: Containerization & Zero-Trust Pipeline Verification

• Multi-Stage Dockerfile: Packaged the core microservice engine into isolated Docker containers (bristlecone\_m2m\_engine).
• Security & Middleware Hardening: Integrated payload size limits (1MB cap), API key verification dependencies, and CORS/TrustedHost middleware.

July 26, 2026: VPS Deployment & PostgreSQL Schema Baseline

• Cloud Infrastructure: Deployed production container stack to Vultr VPS (bristlecone-prod-1, IP: 45.76.245.124) using Docker Compose behind an Nginx reverse proxy.
• Database Relational Setup: Initialized PostgreSQL 16 database (bristlecone\_db) using SQLAlchemy 2.0 and Alembic migrations.

July 27, 2026: Multi-Tenant Context & JWT Refactoring

• JWT Claims Integration: Updated authentication handlers to encode organization\_id directly as org\_id inside JWT tokens.
• Tenant Isolation: Enforced tenant-scoped query filters across /users, /projects, and /organizations endpoints.

July 28, 2026: Commit DAG Engine & Admin API Stack

• Blueprint v2.0 Addendum: Provisioned Alembic migration 60962c26fe50 adding commit\_nodes, commit\_edges, and invigilator\_logs tables.
• DAG Services & API: Deployed /api/v1/dag endpoints for creating commit nodes, linking parent dependencies, and retrieving graph lineages.

July 30, 2026: Metered Gateway, BYOK Schema & Automated Sweeps

• Metering Schema: Provisioned tenants, api\_keys, and llm\_usage\_ledger tables with NUMERIC(12, 6\) precision.
• Background Sweeper: Configured system cron (/etc/cron.d/bristlecone-sweep) executing automated low-balance checks every 15 minutes.

July 31, 2026: Concurrency Optimization & System Benchmarking

• Swarm Benchmark: Executed 150-request load test (50 concurrent workers) achieving a 100% processing success rate (136 metered HTTP 200s, 14 rate-limited HTTP 429s, 0 connection drops) and exact balance reconciliation.

August 1, 2026: AWS KMS HSM Signer, Base L2 USDC Sweeper & KYB Submission

• **AWS K