Substrate thesis requires a single source of truth before parallel work
streams (UI/Atoms/Graph/Runtime) can proceed independently without drift.
This document is that SSoT.
Key decisions baked in (open to revision before lock):
- Atom = one verb on a primitive, not one crate. Target ~150 atoms
across current 25 crates. Crate = physical container, atom = unit of
composition.
- File layout: src/atoms/<verb>.rs (code) + atoms/<verb>.md (docs with
machine-parseable YAML frontmatter) + atoms/schemas/*.json (JSON
Schema draft-07 for input/output) + capabilities.toml (auto-generated
aggregator, committed to repo).
- Atom kinds: command / query / stream / transform. Combined with
side_effects[] and idempotent flag, runtime decides retry safety,
parallelism, caching.
- Naming: <crate>::<verb> globally unique. Rust :: separator keeps it
native-feeling.
- Versioning: atoms inherit crate SemVer. Breaking change to an atom =
new atom (create-v2), old marked deprecated.
- Runtime contract: `kei-runtime invoke <atom-id> --input <json>` with
schema validation at entry + exit, ledger row per invocation.
- Graph contract: kei-sage auto-walks atoms/*.md, resolves [[atom-id]]
wikilinks, exposes rank / related / search / graph over atom corpus.
- UI contract: kei-forge web wizard generates .md + .json + .rs + test
from form input; postcondition cargo check + kei-schema-lint pass.
Document declares 4 stream interfaces explicitly — each stream knows
what it reads from this schema, what it writes, what it does NOT depend
on from other streams. Enables true parallel work.
6 open questions flagged for user review at bottom:
1) JSON Schema draft-07 vs 2020-12
2) Atom ID separator :: vs /
3) side_effects strings vs structured
4) capabilities.toml committed vs gitignored
5) kei-atom-template in this PR or defer to Stream A
6) Error model per-atom vs shared registry
STATUS: DRAFT — awaits user approval + SCHEMA-LOCKED.md marker before
parallel streams start. Once locked, breaking changes require explicit
revocation + all-streams sync.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
58944e15bd