The Atom Spec
Status: v1.0.0 — Constitutional design for the
*-atoms ecosystem.
The Spec defines what every atom and every catalog MUST be: universal identity, URL convention, signing, versioning, references, trust, and governance. Every catalog in the ecosystem conforms to it.
Canonical artifacts
| Form | Latest | Pinned |
|---|---|---|
| Markdown | /spec/atom-spec.md | /spec/atom-spec@1.0.0.md |
| Canonical TOML atom | /spec/atom-spec.toml | /spec/atom-spec@1.0.0.toml |
| Version index | /spec/index.toml | |
Trust
Per Part IX §40, Spec v1.0.0 is the bootstrap version — hand-authored
and signed by the atoms.convergent-systems.co root key. The
root key public material is at /keys/root.toml
and is listed in the umbrella's /keys.toml registry.
The signature over the canonical hash of the Spec body lives in the
[signatures] table of the canonical TOML.
Reading the Spec
The full Spec is the markdown above. For a quick mental model:
- Part I. An atom is a typed, signed, versioned, TOML artifact.
- Part II. A catalog groups atoms into classes under a canonical domain.
- Part III. References resolve via
<catalog-id>/<class>/<slug>@<version>. - Part IV. Every atom is Ed25519-signed; trust is configurable.
- Part V. SemVer for versions; immutable once published; deprecation windows for breaking changes.
- Part VI. Converters transform canonical TOML into consumer formats (W3C tokens, CSS, Tailwind, Rego, …).
- Part VII.
atoms.convergent-systems.co hosts the Spec, catalog registry, trust roots, and converter registry. - Part VIII. Builders validate, resolve, and sign atoms before publication.
- Part IX. Self-reference: the Spec is its own first instance.
- Part X. Spec evolves via a formal amendment process.
- Part XI. Open questions (localization, archival, federation, …).