Learned a lot; vibe coding ain't easy.
The valley of despair is real.
Anyway, created a new Constitution. The United States of Agents' Constitution is alive now. This way I can control my AI babies and their future generations as a benevolent dictator.
Background: the project at one point changed its language law six times in five days. That is unacceptable; The Constitution exists to stop that. It states what must always be true, and which gate proves it. It does not explain, persuade, or record history; reasoning lives in the interview records.
Three standing rules about the Constitution:
- No rule without a gate. A rule that cannot be mechanically checked is a suggestion, and suggestions decay. Every rule below names its gate. Where the gate does not exist yet, that is stated plainly rather than implied.
- A rule appears exactly once. If it is here, no other document restates it. Other documents point at it.
- The law is frozen. The language roster in §1 does not change until the constitution is signed off and at least one capability has shipped end to end.
The language law
1.1 First-party languages - the roster is FINAL!
| Language | Owns | Decides |
|---|
| Rust | Platform, control plane, product domain, security, authentication, authorisation, tenancy, configuration, APIs (REST/GraphQL/SSE), PostgreSQL ownership, Kafka and event processing, search orchestration, AutoIssues, console, observability, deployment, model registry and activation | "Should this happen?" |
| C++17 | The entire AI lifecycle: data loading, feature engineering, training, evaluation, hyperparameter optimisation, inference, embeddings, ranking execution, model conversion, quantisation, GPU/CUDA acceleration, SIMD kernels, all hot paths | "How do we calculate this efficiently?" |
| TypeScript | The browser: React, Studio, DDK, visual builders, dashboards, developer cockpit, typed API clients | "How should humans interact with the system?" |
| C | The ABI bridge only - contracts/abi/signal_abi.h and its versioning. Never business logic | Nothing. It is a connector. |
Rust is the brain. C++ is the muscle. C is the nervous-system connector. TypeScript is the face. PHP may be added to the Constitution, and the SDK and DDK.
The DDK is a design development kit that's meant for agencies who may want to tweak how the app looks down to every detail; this way, people will stop complaining about the GUI being ugly. And for noobs like me, there is something like a page builder; you just point and click, drag the layout, whatever mess or beauty you want to bring to life.
The SDK is still something for consideration; ideally, it would be great for open source stuff, but some companies have a habit of taking open source projects and putting them behind their SaaS walled gardens. Will talk about that later.
1.2 Banned first-party languages
Java and Python are banned as first-party source, shipped runtime, and build-required tooling. So are Go, C#, Haskell, Lua, Fortran, and .ps1/.psw/.cmd/.bat/.vbs automation. C23 does not return; C's role is §1.1's ABI bridge and nothing more.
Python's ban includes model training; C++ owns the whole AI lifecycle (§1.1). The product does not become a research framework: C++ trains the product's own models (ranking, quality scoring, anomaly detection, embeddings, classification). Foundation models are never trained here; they are imported as controlled artifacts.
Note: Spring Boot, Gradle, and the Java ecosystem were tried for curiosity's sake (it's interesting at the speed you can swap and try different things with Docker containers, though; very useful).
Problem: Java isn't a horrible language, just too heavy; the target is getting things to run on systems with 16 GB of RAM and a minimum of 20 cores. Also, Python was banned for being too slow; actually, Python has some best-in-class ML/AI libraries. However, benchmarks showed that Rust or C++ can be optimized to run 20x faster than Python for scoring/crawling. For instance, the project has a scoring/computing stage, where imported XenForo threads/replies/resources/articles, or WordPress, etc, are embedded, but the math stuff with Python is a SLOW process; C++ is fast, like really fast. Below is the stuff that C++ will have to crunch, but although it says 14 signals, actually, some are hidden; the project will ship with over 500+ weights, and meta algorithms (i.e., not meta as in Facebook, lmao, but meta meaning algorithms that fine-tune base algorithms; the vision is making the system sentient).
Documentation is
colocated (Google g3doc convention): every module carries its own g3doc/ directory and a README.md landing page. The top-level docs/ holds only what spans modules.
4. Rust module structure
One crate per bounded context:
kernel · identity · tenancy · agencies · projects · configuration · studio · workflows · policies · search · ranking · quality · analytics · autoissue · ai-orchestration · console · audit · operations · telemetry · api-rest · api-graphql · api-sse
Boundary rules:
- Each crate declares its permitted dependencies explicitly. Anything not declared is forbidden.
- No cycles.
- Domain crates never depend on infrastructure - not axum, sqlx, rdkafka or any adapter.
- Modules never call each other over HTTP inside the process. Direct typed interfaces only.
- One module never reads or writes another module's tables.
- No common, shared, utilities, helpers, or misc crate. Shared code is named after and owned by the capability it implements.
- No global mutable service locator. Dependencies are supplied at the composition root.
- Cross-module reactions use explicit typed events.
4.1
Renamed from admission and radically narrowed, 2026-08-03. console is a runtime layer sitting above Docker. It is designed to be extensible for later features, but its scope today is:
- Queue heavy work with limits
- Split divisible work across machines
- A plugin registry with manifests and versions
- Error logs
- Permission enforcement — untrusted code runs in a throwaway container with no network and no credentials
- Per-module resource budgets
- Self-measurement
What console explicitly does NOT do:
- It never places containers. Docker does that.
- No consensus. No leader election. No quorum. No stateful failover controllers.
- PostgreSQL row locks are the coordinator.
"Admission" survives only as the name of one decision console makes when work arrives.
This supersedes the Google Borg-compatible scheduler design in docs. The eight-step placement algorithm, Borgmaster/placement-engine/agent split, replicated log, leader election, quorum survivability, and per-engine stateful failover controllers are all withdrawn. Part 2's execution-driver model, native installer and durable-settings design survive, minus the scheduling machinery. Multi-machine growth uses Docker Swarm mode, not a first-party scheduler.
Recorded plainly because it is the single largest scope reduction in this Constitution: it removes a distributed-consensus system that two machines never needed, and with it the deterministic fault-injection burden the 100% Law would have imposed on that consensus code.
5. Governed novelty - Rule 56
Novel capabilities are welcome, valuable extensions are encouraged, proven wheels are reused, and duplicate meanings are rejected.
This applies to new capabilities, features, modules, libraries, algorithms, services, components, workflow nodes and architectural abstractions. It does not apply to security fixes, defect corrections, compatibility work, maintenance, migrations, documentation, test strengthening, dependency updates, deletion or consolidation - those are valuable without being novel.
7. The 100% Law
Every ratio at exactly 1.0000. Every defect count at 0. Whole repository. Every commit. No ratchets, no changed-file boundary, no exceptions, and --no-verify is never used.
| Gauge | Tool | Target |
|---|
| rust.coverage.line / .branch | cargo-llvm-cov | 1.0000 |
| rust.mcdc | first-party engine (§5.3) — Rust stays on stable | 1.0000 |
| rust.mutation.kill | first-party engine (§5.3) | 1.0000 |
| rust.unsafe.count | cargo-geiger | 0 |
| cpp.coverage.line / .branch | llvm-cov | 1.0000 |
| cpp.mcdc | llvm-cov -fcoverage-mcdc | 1.0000 |
| cpp.mutation.kill | Mull | 1.0000 |
| cpp.misra.violations | clang-tidy, MISRA C++:2023 profile | 0 |
| ts.coverage.line / .branch | Vitest | 1.0000 |
| ts.mcdc | first-party engine (§5.3) | 1.0000 |
| ts.mutation.kill | Stryker | 1.0000 |
| sanitizers.failures | ASan · UBSan · TSan | 0 |
| code.duplication.blocks | ELCV semantic dedup | 0 |
Rust stays on the stable toolchain. Rather than pin nightly for -fcoverage-mcdc under a Law with no bypass — where an upstream regression would block every commit with no exception mechanism — the Rust MC/DC engine is built first-party (§5.3). rust.mutation.kill at 1.0000 remains unproven at this scale and is verified on Dell before product code is written (§13.1).
One conditional, to be settled by the toolchain verification (§13.1): if stable Rust turns out to support llvm-cov -fcoverage-mcdc, the first-party Rust MC/DC engine in §5.3 becomes unnecessary and is withdrawn — adopting the existing tool instead, per Rule 56 §5.2. The first-party engine is justified
only by the absence of a stable-toolchain option. Do not build it before that question is answered.
Two targets may be physically unreachable, and the verification is designed to find out (§13.1):
- mutation.kill = 1.0000 - a mutant is equivalent when the mutation behaves identically for every reachable input. Equivalent mutants cannot be killed by any test, and identifying them is undecidable in general. If real equivalents exist in this codebase, the target is not merely hard; it is impossible as stated.
- mcdc = 1.0000 - defensive branches, unreachable!() arms and error paths that cannot be triggered without breaking an invariant are uncoverable by construction.
If either proves unreachable, it is reported as unreachable and brought to the owner - it is not quietly relaxed, and no exclusion mechanism is used to manufacture the number. Doing so would be the exact gaming the anti-gaming controls exist to catch.
8. Language standards
8.1 Rust — full strict mode
#![forbid(unsafe_code)] · #![deny(warnings)] · clippy pedantic and nursery denied · no unwrap, expect, panic!, todo! or unimplemented! outside tests · no as casts (checked conversions only) · every public item documented.
Errors: thiserror in libraries, anyhow at executable boundaries. Failures propagate as Result and surface loudly at the boundary — consistent with §6.
Stack: tokio · axum · tower/tower-http · async-graphql · sqlx · rdkafka · tonic/prost · serde · tracing + OpenTelemetry · argon2/jsonwebtoken/rustls · secrecy/zeroize · uuid/ulid/time · wasmtime (sandboxed advanced mods only). Testing: cargo-nextest (execution) · proptest (property-based) · cargo-fuzz (fuzzing) · insta (snapshot/regression) · loom (concurrency interleavings) · criterion (benchmark) · testcontainers-rs (integration against real PostgreSQL/OpenSearch/Kafka) · mockall (mocking — used only where a trait cannot simply be implemented for test; prefer a real test implementation). Coverage and safety: cargo-llvm-cov (coverage) · cargo-geiger (unsafe count) · Miri (undefined-behaviour detection). Supply chain: cargo-deny · cargo-audit · cargo-vet · cargo-semver-checks. Dioxus is rejected — it would duplicate the TypeScript frontend.
Validation: garde. Chosen over validator because it supports context-aware validation — passing tenant, project and configuration state into a validator — which this product needs everywhere given §2.2's tenancy rules, and which validator handles awkwardly. Its structured error type also maps cleanly onto the RFC 9457 problem responses the REST surface returns. Exactly one validation library; running both is the anti-pattern.
8.2 C++ / C++17 under a written MISRA profile
C++17 specifically, so that MISRA C++:2023 applies cleanly. This is deliberate: the project previously claimed MISRA C:2025 compliance for C23, which MISRA does not cover. That mistake is not repeated.
RAII everywhere · no raw ownership · no manual memory management unless justified · no exceptions across ABI boundaries · no undefined behaviour · no global mutable state · Google C++ Style Guide · Abseil (absl::Status, absl::StatusOr, flat_hash_map, Span).
MISRA applicability matrix, approved and prohibited C++17 features, compiler-behaviour register, deviation records, UB register, tool-coverage matrix. The profile exists; C++ admission remains blocked until its licensed per-guideline register and qualified analyser are present.
Stack: Abseil (absl::Status, absl::StatusOr, flat_hash_map, Span) · LibTorch · Eigen · LightGBM/XGBoost C++ · FAISS · SentencePiece · ICU · oneTBB · OpenBLAS/oneMKL · Arrow/Parquet C++ · CUDA/TensorRT. Build: CMake + Ninja + vcpkg/Conan + Clang. Testing: GoogleTest (unit) · GoogleMock (mocking) · FuzzTest (property-based + fuzzing, over libFuzzer) · ApprovalTests.Cpp (snapshot/regression) · Google Benchmark · Mull (mutation) · ASan/UBSan/TSan (sanitizers, and the only concurrency check on this side - there is no C++ equivalent of Rust's loom) · llvm-cov (coverage and MC/DC). Static analysis: clang-tidy - carrying the MISRA profile, the bugprone-* checks, and the clang-analyzer-* interprocedural path-sensitive checks · clang-format · cppcheck · include-what-you-use (include hygiene).
Module boundaries. C++17 has no module system and no ArchUnit equivalent. Boundaries are declared as CMake target-level dependencies and enforced by a first-party include-graph gate - the same shape as SC-ARCH-001 on the Rust side, over #include edges instead of crate edges. Gate SC-CPP-002 - include-graph check.
Does not exist.
Property-based testing: Google FuzzTest. It provides property-based testing
and coverage-guided fuzzing behind one FUZZ_TEST API, integrates natively with GoogleTest, and drives libFuzzer as its engine - so it is a better front end to a tool already chosen, not a second runtime. It is built for exactly this stack: GoogleTest, Abseil, Clang, Linux. Collapsing two tools into one satisfies Rule 56's smallest-maintainable-implementation preference.
Fallback if FuzzTest's build integration proves unworkable under vcpkg/Conan: RapidCheck, the conventional QuickCheck port for C++, with libFuzzer retained separately for fuzzing.
Snapshot/regression testing: ApprovalTests.Cpp. The C++ golden-master library, header-only, with GoogleTest integration - the direct analogue of Rust's insta.
8.3 TypeScript
Strict mode, tsc --noEmit. No any. No business logic in JSX. No compute the backend owns. Downward-only imports: ui → shared → features → app/routes. No cross-feature imports.
Stack: React · Vite · TanStack Router/Query · Zod · React Hook Form · @xyflow/react · Monaco · dnd-kit · Storybook. Testing: Vitest (unit + coverage) · Testing Library (component) · fast-check (property-based) · Stryker (mutation) · Playwright (E2E, the canonical interface proof) · MSW (API mocking) · axe-core (accessibility) · Vitest bench (microbenchmark - the JMH equivalent on this side). Static analysis and boundaries: tsc --noEmit strict · Biome (lint and format) · dependency-cruiser (import boundaries).
No TypeScript fuzzer, deliberately. fast-check is sufficient and nothing more is adopted. The untrusted-input parsing that would justify a fuzzer does not live here: .scp packages, imported bundles, workflow graphs and crawled content are all parsed by Rust (covered by cargo-fuzz) or C++ (covered by FuzzTest), because §2.1 forbids TypeScript from computing anything the backend owns. TypeScript parses API responses from its own trusted backend and form input validated by Zod. Adding a JS fuzzer would be tooling for a surface that does not exist; a Rule 56 REJECT.
Studio is a mode inside the single application, not a separate app: one design system, one auth session, one navigation, one permission surface.
8.4 C - the ABI bridge
C is not a production language (§1.1). It exists as contracts/abi/signal_abi.h plus versioning, and its only job is to be a stable binary contract between Rust and C++, both of which have unstable ABIs of their own.
The rule it must never break: the ABI is permanent. A change that alters struct layout, function signatures, symbol names, or calling convention is a breaking change even when it compiles.
Tooling: clang-format (formatting) · clang-tidy + cppcheck (static analysis) · a C compiler check proving the headers compile cleanly as C, not merely as C++ · abidiff (libabigail) for binary-compatibility verification against the previously released ABI · symbol versioning · a frozen header corpus kept as the comparison baseline.
abidiff is the C-side equivalent of cargo-semver-checks on the Rust side. Without it, "the ABI is stable" is an assertion rather than a checked fact.
Gate SC-ABI-001 - headers compile as C; abidiff reports no breaking change against the frozen corpus; symbol versions are intact. Armed from the first C commit, not before - an ABI gate with no ABI to check is vacuous.
