Architecture & Ops

System Architecture & Internals

Highbeam uses a six-package monorepo with zero npm dependencies. It keeps pure ESM context math cleanly separated from Node.js storage code and host plugins.

1. Six-Package Workspace Topology

Root package.json defines six packages under packages/* backed by shared code in src/core-isomorphic/, src/engine-node/, and src/core/:

Workspace Package Runtime Constraint Core Modules
@ctxtop/core Pure ESM, zero node:* imports DET-01..DET-32 rules, CircuitBreakerEngine, cacheGravity, dualTtl, cliffBreaker, horizonGrid, costRadarSvg, modViews, USTF v1 parser.
@ctxtop/engine-node Node.js >= 22.13.0 stdlib only node:sqlite read-only reader + JSONL offset fallback, Micro-IPC server/client, FTS5 log archiver, git merge-tree conflict check.
@ctxtop/antigravity Node.js >= 22.13.0 PreInvocation 8-state router, 6 Blind-Spot Sensors, local HTTP/SSE sidecar server, Simple & Advanced WebView (horizon_panel.html).
@ctxtop/claude-code Node command hooks + CLI Command hooks (hooks/handlers/*.mjs), an in-process module (hooks/register.js, not loaded by current Claude Code), width-aware ah-statusline bar.
@ctxtop/mcp Node.js stdio JSON-RPC 2.0 Stdio MCP server providing 7 tools: horizon_status, cache_gravity_check, scope_lock_claim, export_receipt_pdf, horizon_compress_cli, horizon_search_logs, and horizon_audit_sessions.
@ctxtop/pro Offline Ed25519 + Polar worker Offline Ed25519 license check, PDF 1.4 receipt writer, team_finops_pack.mjs (Grafana/Datadog), and webhook signer.

2. Claude Mod Laws 1-5 & Pure-JS Cryptography

Claude Code's in-process module (not loaded by current versions) would run inside a sandboxed V8 isolate without Node.js built-ins, so every file in src/core-isomorphic/ follows five strict rules checked by test/mod_static_compliance.test.mjs:

  1. Zero node:* Imports: No node:fs, node:path, node:crypto, or node:child_process imports anywhere in core.
  2. Zero Unguarded Node Globals: Never touches bare Buffer or process without safe globalThis checks.
  3. Zero External npm Dependencies: No supply-chain risk and no bundler step needed.
  4. Pure JS Hashing: Uses pure-JS 64-bit FNV-1a (fnv1a64.mjs) for fast fingerprints and pure-JS SHA-256 (sha256HexPure) for checksums and receipts.
  5. Fast Rule Engine: evaluatePreToolUse and computeBreakEven run in about 0.2ms p95 inside the process. Each hook call also pays Node startup, so end-to-end it is ~60-80ms on Linux and ~200-275ms on Windows.

3. Lossless FTS5 CLI Output Compressor

Test runs and package installs often dump 50,000+ chars of progress bars and passing test lines. Built into src/core/fts5_output_compressor.mjs and src/shims/agy_cli_compressor.mjs (DET-07), the compressor cleans shell output in four steps:

  1. ANSI & Spinner Cleanup: Strips color codes and folds \r spinner lines before checking the 4,096-char size limit.
  2. Smart Noise Filters: Trims boilerplate from cargo test, npm install, and test suites while keeping every failed assert, stack trace, and compiler error.
  3. SQLite FTS5 & Polyfill Archive: Saves the full raw log to .ctxtop/cache/artifacts/ah_<sha256>.txt and indexes every line in .ctxtop/cache/artifacts_fts5.db. If a Node 22 build lacks SQLITE_ENABLE_FTS5 (or CTXTOP_FORCE_FTS5_POLYFILL=1 is set), src/engine-node/db/probe.mjs wraps DatabaseSync with createFts5PolyfillClass(). That provides drop-in USING fts5(...) tables, MATCH, bm25(), and centered snippet() windows (evaluateFtsSnippet).
  4. Searchable Summary: Sends the model a short head/tail + error summary plus an exact agy-horizon log-search "<query>" command so no debug detail is ever lost.

4. PrefixCacheShield & TurnZeroGate Fencing

Editing AGENTS.md, CLAUDE.md, or .agents/rules/*.md mid-chat changes Cell 1 at the top of your prompt. That resets every warm cached token below it. PrefixCacheShield and TurnZeroGate stop mid-chat cache resets by holding rule edits until the cache cools naturally:

TurnZeroGate Deferred Rule Promotion Sequence 1. Warm Cache Active (TTL 03:40) /evolve or rule promotion DET-09 fences direct write; delta staged in queue 0 cached tokens invalidated 2. Cold Boundary Reached 5m TTL == 00:00 OR PostCompact / SessionStart TurnZeroGate unlocks fence 3. Atomic Primacy Flush AGENTS.md / CLAUDE.md written via PID temp rename; U-curve Primacy order kept

5. USTF v1 & 3-Way SHA-256 Mirror Parity