The Commons Format

A format for shipping verifiable intent. Commons Format modules distribute prose and eval suites; consumers generate divergent implementations against the same contract. Each consumer's running code is unique to their machine, their generator, and their seed.

Why this exists

Frontier AI models can find software exploits autonomously. When an attacker can spend a few thousand dollars to find a CVE in a popular library, every consumer of that library is exposed by the same shared code. Defense becomes a token-spending contest where the side spending more on hardening wins — but only if defenders aren't all running the same code as each other.

Commons Format's bet: shared code is the vulnerability. Distributing intent and evals rather than compiled artifacts, and letting each consumer generate divergent implementations against the same contract, fragments the application-code attack surface. A single exploit no longer hits everyone. Attackers must spend tokens against each consumer's unique implementation rather than amortizing one discovery across thousands of targets.

The format does not solve runtime, OS, or hardware-layer vulnerabilities. It addresses application code, which is where most current attacks live.

What a module looks like

A module is a directory:

my-module/
├── commonsformat.toml      # metadata + dependencies
├── commonsformat.md        # canonical prose with tagged sections
├── evals.toml              # the conformance contract
├── LICENSE
└── README.md               # optional, for repo browsers

The prose describes intent, constraints, anti-patterns, interface, and threat model in human-readable Markdown with extractable tagged sections:

<intent>
A token-bucket rate limiter that isolates limits per key,
adds jitter to prevent thundering herd, and degrades
gracefully under load.
</intent>

<constraints>
- no-fixed-window: must not use fixed-window counters
- no-global-locks: must not use global locking
</constraints>

The eval suite is machine-readable test cases organized by category — functional, adversarial, generator-adversary — each with input, expected behavior, and (optionally) a verifies list naming which constraints it tests:

[[adversarial]]
name = "thundering-herd-at-boundary"
category = "timing"
input = { limit = 100, clients = 1000, synchronized_at_ms = 1000 }
expect = { max_concurrent_at_reset_lt = 200 }
verifies = ["no-fixed-window"]

How consumers use it

1. Resolve — the module's depends_on declarations are followed to produce a merged virtual spec covering the module and its transitive dependencies.
2. Generate — the merged spec is fed to a code generator that produces source code in the consumer's target language.
3. Verify — the eval runner executes the merged eval suite against the generated code. Iteration continues until conformance.
4. Lock — a lockfile records which spec commits and which generators produced the verified implementation.

The consumer never installs anyone else's compiled code. Their running implementation is unique to their machine, their generator choice, and their generation seed.

Deployment tiers

Verification rigor matches deployment context. Consumers declare the tier appropriate to their use:

Composition

Modules merge at the spec layer, not the implementation layer. When module A declares depends_on module B, the resolver merges B's spec content into A's, producing a single merged virtual spec. The consumer generates one implementation against the merged contract. There is no runtime linking and no version-skew between linked libraries; the merge happens before generation.

Identity and distribution

Modules are identified by their Git-rooted URL — for example, github.com/jane/specs/rate-limiting@v1.2.0. The repository URL is the module's identity. There is no central registry. Forking is the natural disagreement mechanism: a fork at a different URL is a different module. Lockfiles pin commit SHAs for reproducibility and tamper detection.

Where to start

• The format specification is the canonical normative document.
• commonsformat-parser is a worked example of a tooling module — small enough to read end-to-end.
• The field reference lists every defined TOML key, tagged section, and eval category.

Status

Format version 0.2, draft. Canonical release 0.2. Breaking changes expected before 1.0. The format is intentionally minimal at this stage; extension happens through real use revealing what the format needs to address.

describes commons format 0.2 · generated from release 0.2 · 2026-05-28