Bristlecone-Logic/bristlecone-logic

**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).
| Dendro Tier | Operational Role | Execution Authority | Side-Effect Constraints |
| :---- | :---- | :---- | :---- |
| **Seedling** | Intake & Parsing | Read-only input sanitization and schema parsing | Zero write privileges |