Reference

Every TOML key, tagged section, eval category, and deployment tier defined by the format. Each entry links to the section of the specification that defines it.

Module metadata · `commonsformat.toml`

field	description	defined
commonsformat	Format version this module targets, as a string (e.g., `"0.2"`). Required.	§6
name	Module name. Lower-case ASCII letters, digits, and hyphens; must not begin or end with a hyphen. Required.	§6
version	SemVer-shaped `MAJOR.MINOR.PATCH` string with no pre-release or build suffix. Required.	§6
description	One-to-three sentence summary, plain text. Required.	§6
license	SPDX license identifier (e.g., `MPL-2.0`). Required.	§6
authors	Array of inline tables with `name` (required) and optional `email`, `url`. At least one author required.	§6
verifies	Relative path to the eval suite, typically `"./evals.toml"`. Required for D1 or higher.	§6
homepage	URL of a project homepage. Optional.	§6
repository	URL of the module's source repository. Optional.	§6
keywords	Array of strings for indexing. Optional.	§6
depends_on	Array of dependency declarations. See §11. Optional.	§11.2
extends	Single-parent extension declaration; inherits the parent's evals and takes precedence on conflicts. Optional.	§11.6
contributes_only	Array restricting an eval pack to specified categories (`adversarial`, `generator_adversary`). Optional.	§11.7

Dependency declaration fields

field	description	defined
spec	Git-rooted path of the form `host/owner/repo/path`. Required.	§11.2
version	Constraint matching a Git tag in the dependency repository. One of `version` / `ref` / `commit` required.	§11.3
ref	Git ref name (branch, tag, or commit reference).	§11.2
commit	Exact Git commit SHA.	§11.2
overrides	Subtable resolving merge conflicts for this dependency. Values may be literals or `"ignore"`.	§11.5

Tagged sections · `commonsformat.md`

tag	description	defined
<intent>	What the generated code should do. At most one per module.	§5.3.2
<constraints>	Hard requirements the implementation must satisfy. Each line `name: description`. At most one per module.	§5.3.2 / §9.7
<avoid>	Anti-patterns that disqualify an implementation. At most one per module.	§5.3.2
<interface>	Declared shape of the public API. At most one per module. Only the root module's interface is exposed in a merged spec.	§5.3.2
<threat-model>	Adversarial assumptions and attacker capabilities. At most one per module.	§5.3.2
<example name="...">	Illustrative input/output pair. May appear multiple times with distinct `name` attribute values.	§5.3.4

Data shape · `schema.sql`

construct	description	defined
schema.sql	Optional file declaring data shape in a pinned SQLite-subset DDL. A shape commitment, not a storage commitment — runtime representation is the generator's choice. Omitted when a module has no shaped data.	§8
header comment	Required leading comment stating the file is shape, not storage; must precede any DDL.	§8.2
CREATE TABLE / CREATE INDEX	The only permitted statements. No views, triggers, procedural SQL, `INSERT`, or `IF NOT EXISTS`.	§8.1
types	`INTEGER`, `REAL`, `TEXT`, `BLOB`, `TIMESTAMP`, `BOOLEAN`. No vendor extensions or affinity sugar.	§8.1
constraints	`PRIMARY KEY`, `FOREIGN KEY` (same-file target only), `NOT NULL`, `UNIQUE`, `CHECK`, and literal column defaults.	§8.1
composition	Schemas do not merge across modules; each module owns its tables. Cross-module foreign keys are rejected.	§8.3

Eval suite · `evals.toml`

field	description	defined
commonsformat_evals	Eval format version. Required.	§9.1
target	Name of the module these evals verify. Must match the module's `name`.	§9.1
target_version	Version range these evals are valid for, in the §11.3 constraint syntax.	§9.1
[[cases]]	Array of functional verification cases.	§9.4
[[adversarial]]	Array of cases probing known attack patterns. Required for D1+.	§9.5
[[generator_adversary]]	Array of cases probing generator-introduced flaws. Required for D2+.	§9.6
[adversarial_coverage]	Declares which attack categories the eval suite covers.	§9.5
[properties]	Invariants not easily expressed as input/output cases (advisory unless tooling verifies).	§9.8

Eval case fields

field	description	defined
name	Kebab-case identifier, unique within the eval file.	§9.2
description	One-sentence human-readable description.	§9.2
category	One of: `functional`, `input-validation`, `timing`, `concurrency`, `resource`, `failure-mode`, `crypto`, `interface`.	§9.3
input	Inline table of inputs to the implementation under test.	§9.2
expect	Inline table of expectations on the implementation's behavior.	§9.2
tags	Optional array of strings for filtering.	§9.2
severity	Optional, one of `info`, `warn`, `error`, `critical`. Default `error`.	§9.2
verifies	Optional array of constraint names from the prose (see §9.7).	§9.7
fixture://...	String reference to a file or directory under `fixtures/`, used in `input` values.	§9.2.1

Eval categories

category	execution model	defined
functional	Invokes implementation with `input`; checks structural-equality match of `expect` fields against output.	§9.3
input-validation	Expects implementation to reject `input`; checks `rejects = true` and optional `error_includes`.	§9.3
interface	Examines structural properties of the result (`has_fields`, `has_field`) — verifies shape, not content.	§9.3
timing	Sets up a timed scenario; comparison operators in `expect` express bounds (e.g., `max_x_lt = 200`).	§9.3
concurrency	Executes multiple operations genuinely concurrently and verifies properties of the combined result.	§9.3
resource	Monitors memory, CPU, file handles, etc.; verifies bounds in `expect`.	§9.3
failure-mode	Arranges a degraded condition (network down, disk full, dependency timeout) and verifies behavior.	§9.3
crypto	Uses `input` as a test vector; compares output to `expect` byte-for-byte, constant-time when possible.	§9.3

Deployment tiers

tier	requirement	defined
D0	Personal / experimental. Functional eval cases pass.	§12
D1	Internal production. D0 plus adversarial cases pass; every declared constraint verified by at least one case.	§12
D2	Network-exposed production. D1 plus generator-adversary cases, two independent generator records, and recorded prose review.	§12
D3	Critical infrastructure. D2 plus two distinct runtime records and any declared `formal_artifact_path` referenced from the lockfile.	§12

Verification axes

axis	levels	defined
eval depth	functional · adversarial · generator-adversary · formal	§13.1
generator diversity	single · same-family · independent-family · independent-provider	§13.2
runtime diversity	single · multi-runtime same family · multi-runtime independent family	§13.3

Lockfile · `commonsformat.lock`

field	description	defined
commonsformat_lock	Lockfile format version.	§14
generated_at	ISO 8601 timestamp of lockfile generation.	§14
generator_tool	Identifier of the tool that produced the lockfile.	§14
[root]	Root module identification, including `spec_hash`.	§14
[[modules]]	Per-dependency record: `spec`, `version`, `commit`, `checksum`, `fetched_at`.	§14
[modules.verification]	Per-dependency verification state: `deployment_tier`, `results` by generator, `applied_packs`.	§14
[modules.verification.prose_review]	D2+ attestation: `reviewed`, `reviewed_at`, `reviewer`, `prose_hash`.	§14.1

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