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:
- Zero
node:*Imports: Nonode:fs,node:path,node:crypto, ornode:child_processimports anywhere in core. - Zero Unguarded Node Globals: Never touches bare
Bufferorprocesswithout safeglobalThischecks. - Zero External npm Dependencies: No supply-chain risk and no bundler step needed.
- 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. - Fast Rule Engine:
evaluatePreToolUseandcomputeBreakEvenrun in about0.2ms p95inside 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:
- ANSI & Spinner Cleanup: Strips color codes and folds
\rspinner lines before checking the4,096-char size limit. - Smart Noise Filters: Trims boilerplate from
cargo test,npm install, and test suites while keeping every failed assert, stack trace, and compiler error. - SQLite FTS5 & Polyfill Archive: Saves the full raw log to
.ctxtop/cache/artifacts/ah_<sha256>.txtand indexes every line in.ctxtop/cache/artifacts_fts5.db. If a Node 22 build lacksSQLITE_ENABLE_FTS5(orCTXTOP_FORCE_FTS5_POLYFILL=1is set),src/engine-node/db/probe.mjswrapsDatabaseSyncwithcreateFts5PolyfillClass(). That provides drop-inUSING fts5(...)tables,MATCH,bm25(), and centeredsnippet()windows (evaluateFtsSnippet). - 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:
5. USTF v1 & 3-Way SHA-256 Mirror Parity
- USTF v1 (
src/core-isomorphic/ustf/): Maps Antigravity SQLite/JSONL steps and Claude Code events into one shared log format (version: "1.0.0",sessionId,harness,modelId,usage: { uncached, cacheWrite5m, cacheWrite1h, cacheRead, output, thinking, costUSD },events,spans). - Release & Mirror Sync: When core or WebView files change, run
node scripts/sync_mirrors.mjsfirst. Then runnode scripts/generate_checksums.mjsandnode bin/ctxtop.mjs verify --jsonso root files and plugin copies stay byte-for-byte identical.