This directory records significant, cross-cutting architectural decisions for the MetaObjects standard — the durable "why" that outlives any single feature spec.
| Doc type | Location | Scope |
|---|---|---|
| ADR | spec/decisions/ (here) |
Durable, cross-cutting, target-agnostic contracts that bind multiple language ports (e.g. how metadata→native types are bound; the conformance model; persistence-engine choice). |
| Feature design (FR spec) | docs/superpowers/specs/ |
A single feature's design, language- or area-scoped. |
| Implementation plan | docs/superpowers/plans/ |
Task-by-task execution of a feature. |
| Conventions / pointers | CLAUDE.md |
Lean, always-loaded context: durable one-liners + pointers here. |
Write one when a decision is cross-cutting (affects more than one language port or more than one feature) and durable (future work must respect it). Examples: a metamodel binding contract, the wire-format guarantee, "migrations decoupled from the runtime." Do not write ADRs for feature-level or easily-reversible choices — those live in the FR spec.
Michael Nygard's ADR format: Context → Decision → Consequences → Status, plus Alternatives considered and Realization status where useful. One decision per file. Status is Proposed | Accepted | Superseded by ADR-NNNN. Numbered sequentially; never renumber (supersede instead).
- ADR-0001 — Cross-language metadata→native-type binding — Accepted
- ADR-0002 — Open-Closed typed nodes (subtype behavior on the class) — Accepted
- ADR-0003 — Metamodel constants colocation — Accepted
- ADR-0004 — Provider-based type registration & composition — Accepted
- ADR-0005 — Object representation: entity/value semantics + binding-resolved representation (OO ports) — Accepted
- ADR-0006 — AI-first YAML authoring (sigil-free YAML; JSON stays canonical) — Proposed
- ADR-0007 — Source metatype v2: storage-paradigm subtypes, logical names, multi-source, per-subtype physical addresses — Proposed
- ADR-0008 — Parameter-passing for generated repo helpers — Accepted
- ADR-0009 — Loader error envelope + source-on-node — Accepted
- ADR-0010 — Per-port parser-on-receipt codegen for
template.output— Accepted - ADR-0011 —
template.toolcallas a core MO subtype — Accepted - ADR-0012 — Remove the OSGi runtime variant from the Java port — Accepted
- ADR-0013 — Logical field types vs. physical column-type attributes — Accepted
- ADR-0014 — Type-registry resolution is loader-scoped, not process-global — Accepted
- ADR-0017 — Cross-port runtime object model (ValueObject default + MetaObjectAware + self-registering ObjectClassRegistry + newInstance factory) — Accepted
- ADR-0018 — Per-kind physical-name attributes within source paradigms — Proposed
- ADR-0015 — One shared migration engine; codegen + loader stay per-port — Accepted
- ADR-0016 — Build the migration apply+tracking runner (TS-native, Postgres-first) — Accepted
- ADR-0019 — Runtime return-type contract: native in-process, canonicalize at the boundary — Accepted
- ADR-0020 — Codegen tiering — native-per-port vs neutral-shared — Superseded by ADR-0022
- ADR-0021 — Codegen surface coherence — one front door, stable-name registry, consistent verify — Superseded by ADR-0022
- ADR-0022 — Codegen & documentation surface architecture (consolidated) — Accepted
- ADR-0023 — Strict metadata provenance: no made-up attributes — Accepted
- ADR-0024 — AI-trace scope: the typed trace + recorder is the standard; the LLM caller is bring-your-own — Accepted
- ADR-0025 — Unified docs door — one command, two surfaces, one config — Accepted
- ADR-0026 — Shared & externally-provided named types (enums + value objects) — Accepted
- ADR-0027 — Polyglot docs composition — per-language api surfaces, model once — Accepted
- ADR-0028 — Object taxonomy:
object.projection, value purity, and the population doctrine — Accepted - ADR-0029 — Universal
Entity.childextends-resolution and theviainference contract — Accepted - ADR-0030 — The declared API surface lives in core; protocol lives in bindings; the organization tier stays out — Accepted
- ADR-0052 — A template's subtype axis is DIRECTION:
template.outputrenders outbound, a response is parsed inbound — Accepted - ADR-0053 — The reply's syntax is
@responseFormatontemplate.prompt— Accepted - ADR-0054 — A
<type>.basesubtype is a registry anchor, not an authorable node — Accepted - ADR-0055 — Overlay application is a deferred pass — plain declarations first, then overlays, each in source order — Accepted
- ADR-0056 — A value object's type is generated once — the template tier references it — Accepted (supersedes the payload-tier half of ADR-0044)
- ADR-0057 — Requirement checks and requirement tests run in every port — Accepted (reverses the "Checks — TypeScript only" split recorded in
docs/CONFORMANCE.md)
Index gap — ADR-0031 through ADR-0051 are on disk but not listed above. The index stopped being maintained after ADR-0030; the files are authoritative, this list is not. Read
ls spec/decisions/for the full set until the backfill lands. Recorded here rather than silently left, because an index that looks complete and is not is worse than one that says so.