Architecture Decision Records

Purpose: Document significant architectural decisions Audience: Contributors, maintainers, architects Status: Historical decision index

---

What are ADRs?

ADR stands for Architecture Decision Record — documents that capture important architectural decisions along with their context and consequences.

ADRs are:

• Immutable records of decisions made at a point in time
• Context-rich explanations of why decisions were made
• Historical artifacts showing evolution of the architecture

ADRs are NOT:

• Specifications (see Specifications)
• Design rationale (see FDR)
• Current architecture description (see Architecture)

Use ADRs to understand why the architecture changed. Use package READMEs, API docs, and current specs to understand how the current system works.

---

Global ADRs

These ADRs affect multiple packages across the monorepo:

ID	Title	Status	Date	Affected Packages
ADR-001	Layer Separation after Host v2.0.1	Accepted	2025-01-17	Core, Host, World
ADR-002	DX improvement — auto $mel namespace injection + onceIntent syntax	Implemented	2026-01-27	App, Compiler, World, Core, Host
ADR-003	Historical persistence draft	Superseded	2026-02-03	App, World (retired)
ADR-004	App Package Internal Decomposition	Proposed	2026-02-07	App
ADR-005	DX improvement — Snapshot Path DSL (${...}) introduction	Withdrawn	2026-02-10	Core, Host, World, App, Compiler
ADR-006	Publish Boundary, Canonicalization, and Channel Separation Rules	Proposed	2026-02-10	Core, Host, World, App
ADR-007	SDK/Runtime Split Kickoff Gate and Staged Locking	Superseded	2026-02-14	App, Runtime, SDK, World
ADR-008	SDK-First Public Entry and App Package Retirement	Deprecated	2026-02-17	SDK, Runtime, Docs, Release, CI
ADR-009	Structured PatchPath (Segments)	Implemented	2026-02-25	Core, Compiler, Host, Runtime, World
ADR-010	Protocol-First SDK Reconstruction	Implemented	2026-02-27	Core, Runtime, Host, World, SDK
ADR-011	Host Boundary Reset Completeness Policy	Implemented	2026-02-25	Host, Runtime, World, SDK
ADR-012	Remove computed. Prefix from Computed Snapshot Keys	Implemented	2026-03-05	Core, Compiler, Host, SDK, Docs
ADR-013a	MEL Statement Composition — flow and include	Implemented	2026-03-24	Compiler
ADR-013b	Entity Collection Primitives — findById, existsById, updateById, removeById	Implemented	2026-03-24	Compiler
ADR-014	Split World Protocol into Governance and Lineage Packages	Implemented	2026-03-28	World, Governance, Lineage, SDK, Docs
ADR-015	Snapshot Ontological Purification — Remove Accumulated History from Point-in-Time State	Implemented	2026-03-29	Core, Lineage, Host, World, SDK
ADR-016	Merkle Tree Lineage — Positional World Identity via Parent-Linked Hashing	Implemented	2026-03-29	Lineage, Governance, World
ADR-017	Capability Decorator Pattern — Semantic Transformation of SDK Surface	Implemented	2026-04-01	SDK, Lineage, Governance
ADR-018	Public Snapshot Boundary — User-Facing Snapshot Projection and CanonicalSnapshot Separation	Implemented	2026-04-03	SDK, Core (docs), Docs, Lineage, Governance
ADR-019	Post-Activation Extension Kernel — Safe Public Seam for Arbitrary-Snapshot Operations	Implemented	2026-04-07	SDK
ADR-020	Intent-Level Dispatchability — dispatchable when Clause	Implemented	2026-04-07	Compiler, Core, SDK, Studio/Introspection, Docs
ADR-021	MEL Structural Annotation System — @meta Sidecar	Accepted	2026-04-15	Compiler, Tooling, Docs
ADR-022	Compiler-Owned Source Location Sidecar (SourceMapIndex)	Accepted	2026-04-16	Compiler, Tooling, Docs
ADR-023	Object Spread Sugar in MEL	Accepted	2026-04-23	Compiler, Docs
ADR-024	Compiler-Owned MEL Source Fragment Editing Primitive	Accepted	2026-04-25	Compiler, Studio/authoring tools
ADR-025	Snapshot Ontology Hard Cut — data Retirement and Namespace Separation	Implemented	2026-04-29	Core, Host, SDK, Compiler, Lineage, Governance, Studio, Agent tooling, Constitution, Docs
ADR-026	SDK v5 Action Candidate Surface and Law-Aware submit() Ingress	Implemented	2026-04-29	SDK, Lineage, Governance, Studio, Agent tooling, Codegen, Docs
ADR-027	Context and Runtime Namespace Semantics	Implemented	2026-05-03	Core, Compiler, Host, SDK, Lineage, Governance, Constitution, Docs
ADR-028	Core-Owned Dynamic Patch Target Semantics	Implemented	2026-05-07	Core, Compiler, Host, Docs, CTS

ADR-006 Companion Evidence (Non-Normative)

• ADR-006 Evidence Matrix - Rule-to-implementation and test traceability while ADR-006 remains Proposed.
• ADR-006 Split Readiness Pack - Fixed baseline, current readiness verdict, and owner decision cards for package split planning.

Supersede Notes

• ADR-007 partially supersedes ADR-004 §7.4 and ADR-006 §5 for split kickoff timing and gating policy.
• ADR-008 supersedes ADR-007 Phase 1 entrypoint guardrails by promoting SDK as canonical public entry and retiring App.
• ADR-007 does not supersede ADR-001 layer separation principles (package split is not a new layer).
• ADR-010 supersedes ADR-008. ADR-008 is deprecated as historical transition record; ADR-010 is the active boundary.
• ADR-010 accepts ADR-008 outcomes and converts App-retirement policy from migration guidance into canonical hard-cut.
• ADR-010 is the active boundary for submit/dispatch API simplification; public createApp surface is removed in v1+ implementation.
• ADR-010 supersedes SDK-SPEC v0.1.0/v0.2.0 via SDK-SPEC v1.0.0. Runtime-SPEC v0.1.0/v0.2.0 are retired (no successor).

ADR-009 Companion Notes

• ADR-009 is an implemented cross-cutting decision that completed the path-representation rewrite for patching across Core/Compiler/Host/Runtime/World.
• The rule set is now reflected in Core/Compiler/Host/World normative docs and runtime/store code paths.
• ADR-009 Week 1 Convergence Pack - Frozen gap matrix, decision-complete ticket set, and Week 2 PR wave plan.

ADR-010 Companion Notes

• ADR-010 defines the protocol-first reconstruction of the SDK as a thin composition layer with createManifesto() as its sole owned concept.
• This ADR explicitly removes App-layer semantic coupling in product-facing APIs. ActionHandle, Session, Hook, Plugin, and 20+ binding-layer concepts are retired.
• ADR-010 lifts the old SDK SPEC v0.1.0 kickoff lock for submitProposal, createApp, and legacy App aliases.
• The original hard-cut migration contract was createManifesto() returning a runtime directly with dispatch() as the single action entrypoint.
• The current SDK contract is the activation-first createManifesto() -> activate() model documented in sdk-SPEC.md.
• ADR-010 supersedes SDK SPEC v0.1.0 and v0.2.0 via SDK SPEC v1.0.0.
• ADR-010 retires Runtime SPEC v0.1.0 and v0.2.0 (no successor — responsibilities absorbed into createManifesto).
• ADR-010 is now implemented in the current SDK/package layout; the remaining split-related work belongs to ADR-014 rather than this hard-cut.

ADR-011 Companion Notes

• ADR-011 defines Host boundary baseline-completeness policy for reset/Bootstrap entry.
• It is the host-runtime contract companion to #198, scoped to full-canonical snapshot continuity at boundary entry.
• executionKey serialization and timeout-slot release remain Host SPEC v2.0.3 enforcement work, not architecture decisions in this ADR.
• ADR-011 is implemented via the current Host contract and boundary-entry hardening; §2.2/§2.3 remains enforced as Host SPEC behavior, not extra ADR text.

ADR-013 Split Notes

• There is no standalone ADR-013 file in the repository.
• The original mixed ADR-013 draft was withdrawn and split into ADR-013a (flow/include) and ADR-013b (entity collection primitives).
• Both split tracks are now implemented in the compiler current contract, reflected in SPEC-v1.2.0, and covered by the compiler compliance suites.

ADR-014 Companion Notes

• ADR-014 is the implemented protocol split of @manifesto-ai/world into @manifesto-ai/governance and @manifesto-ai/lineage.
• The current continuity contract now lives in lineage-SPEC.md.
• The current legitimacy contract now lives in governance-SPEC.md.
• Historical split-era landing docs remain available in lineage-SPEC-2.0.0v.md, governance-SPEC-2.0.0v.md, and world-facade-spec-v2.0.0.md.
• There is no separate current @manifesto-ai/world package surface; world-facade materials are historical split context only.

ADR-015 Companion Notes

• ADR-015 is implemented and lands in the current Core contract: accumulated system.errors history and appendErrors are removed while lastError remains the sole current error surface.
• ADR-015 originally landed alongside Core v4.0.0, Host v4.0.0, Lineage v2.0.0, Governance v2.0.0, and World facade v2.0.0. The current decorator supersession is tracked separately by ADR-017 and the v3.0.0 package version indexes.
• core-SPEC-v4.0.0-draft.md is now historical draft context only; the current normative Core contract is core-SPEC.md.
• The wider SDK/decorator rewrite is now current in sdk-SPEC.md, but the Snapshot-shape portion of ADR-015 remains its independent current contribution.
• ADR-015 now pairs with ADR-016, the implemented lineage-side companion for the same co-deployed epoch boundary.

ADR-016 Companion Notes

• ADR-016 is implemented as the lineage identity rewrite companion to ADR-015: WorldId becomes parent-linked positional identity instead of content-only identity.
• The landed contract introduces tip / headAdvancedAt, idempotent reuse for same-parent same-snapshot seals, and SealAttempt as the per-attempt chronology substrate.
• The original service-first landing is preserved in lineage-SPEC-2.0.0v.md and governance-SPEC-2.0.0v.md.
• The current continuity and legitimacy contracts now live in lineage-SPEC.md and governance-SPEC.md.
• The historical pre-landing Host execution-side draft remains available in host-SPEC-v4.0.0-draft.md, while the current Host contract lives in host-SPEC.md.
• The historical world-facade contract remains available in world-facade-spec-v2.0.0.md, but it is no longer a current package authority.
• The current decorator-era routing is tracked by ADR-017, the current package specs, and the current version indexes.

ADR-020 Companion Notes

• ADR-020 is implemented in the current compiler, core, and SDK contracts.
• The current behavior now lives in SPEC-v1.2.0, core-SPEC.md, sdk-SPEC.md, and the maintained MEL docs.
• This ADR remains the architectural rationale for dispatchable when; the owning package specs define the current runtime and compiler behavior.

ADR-021 Companion Notes

• ADR-021 is accepted and reflected in the current compiler contract and maintained MEL docs for the current v1 surface.
• The current landed/documented subset excludes action_param; that grammar decision remains deferred.
• Core, Host, and SDK runtime entrypoints remain annotation-blind.

ADR-022 Companion Notes

• ADR-022 is accepted as the compiler-owned source-location sidecar decision for declaration-level MEL provenance.
• The canonical accepted record is ADR-022 v11; earlier review iterations are preserved in the inline revision history rather than separate archived ADR files.
• SourceMapIndex is additive tooling-only output and does not change DomainSchema.hash, SchemaGraph, or runtime entrypoints.

ADR-024 Companion Notes

• ADR-024 is accepted as the compiler-owned source-fragment editing primitive decision for Studio and external Author layer integrations.
• The accepted boundary is narrow: compiler validates and materializes exactly one source edit; the Author layer owns request interpretation, sequencing, retries, acceptance policy, and edit-attempt lineage.
• ADR-024 is reflected in the current Compiler SPEC v1.2.0 contract at packages/compiler/docs/SPEC-v1.2.0.md.

ADR-025 Companion Notes

• ADR-025 is implemented as the v5 Snapshot ontology hard-cut decision: domain state moves from Snapshot.data to Snapshot.state, and platform/runtime/tooling namespaces move under Snapshot.namespaces.
• ADR-025 retracts the prior Snapshot.data normative commitments in SPEC §13.3, the Constitution/CLAUDE.md canonical Snapshot block, and ADR-009 §2.8.
• Current package SPECs, docs gates, and public API inventory now treat ADR-025 as landed v5 surface.

ADR-026 Companion Notes

• ADR-026 is implemented as the v5 SDK surface hard-cut decision: the public runtime moves from the v3 intent/dispatch/simulate ladder to action-candidate handles with info(), available(), check(), preview(), submit(), and bind().
• ADR-026 supersedes createIntent() + dispatchAsync() as the primary app-facing path, public simulate() / simulateIntent() naming, and the public write-verb fork between dispatchAsync, commitAsync, and proposeAsync.
• ADR-026 revision 8 adds projected read handles under app.state.* and app.computed.*; these are typed read-only aliases over snapshot() / observe.state(), not mutation or canonical-substrate surfaces.
• ADR-026 revision 9 replaces the split plural action namespace and callable semantic action entrypoint with a single static app.action.* namespace; dynamic collision-safe semantic action access is removed and reserved public action names fail fast.
• ADR-026 is the SDK surface layer of the same v5 release train as ADR-025's Snapshot substrate hard cut.
• ADR-026 is reflected in SDK, Lineage, Governance, Codegen, and maintained docs as the current action-candidate ingress.

ADR-027 Companion Notes

• ADR-027 is implemented as the v5 compute-input hard-cut decision: canonical Core compute is compute(schema, snapshot, intent, context).
• ADR-027 defines snapshot as schema-driven existence information and context as captured external environment; determinism is over the full four-input tuple.
• ADR-027 keeps context owner-neutral. It supersedes HostContext and rejects the interim CoreIntent.frame plan as the canonical API.
• ADR-027 limits user-defined context to schema-declared direct-injected JSON data under context.external; user-defined context generators/resolvers/providers remain out of scope.
• ADR-027 keeps runtime view selection separate from action triggering. SDK context/report/diagnostics flow through with(view) or root context APIs before action selection, not through preview() or submit() option bags.
• ADR-027 introduces $runtime.* as the single built-in Manifesto runtime expression contract over intent/context facts, retiring $meta.*, $system.*, and $mel.sys runtime-value lowering.
• ADR-027 requires Lineage replay records to include the intent and exact context value used for the transition.
• ADR-027 preserves snapshot.namespaces as owner bookkeeping only; Core MUST NOT know Host/MEL namespace shapes or use owner namespaces as semantic expression inputs.
• ADR-027 is the compute-input layer of the same v5 release train as ADR-025's Snapshot substrate and ADR-026's SDK surface hard cuts.

ADR-028 Companion Notes

• ADR-028 is implemented as the v5 semantic-boundary hard-cut decision for dynamic patch targets.
• ADR-028 preserves ADR-009's structured concrete PatchPath, but supersedes ADR-009's Compiler/runtime evaluateConditionalPatchOps() contract and skip + warning invalid dynamic target policy.
• Core owns dynamic Flow patch target resolution during compute(); emitted patches and core.apply() remain concrete-only.
• Compiler lowers and preserves dynamic target expressions but does not evaluate them, allocate runtime values, or produce runtime patches from runtime data.
• Host never resolves dynamic patch targets; it applies Core-emitted concrete domain patches, namespace deltas, and system deltas.

ADR-017 Version Notes

• The canonical implemented record is ADR-017 v3.1, which lands the activation boundary, one-shot activate(), and Governance/Lineage config precedence rules.
• The earlier ADR-017 v2 archived draft is retained for traceability. It preserves the cross-model review consensus phase before the activation-boundary rewrite. ADR-026 later supersedes root verb-chain wording with the v5 action.<name>.check/preview/submit surface.

---

Package-Specific ADRs

Translator ADRs

The translator package maintains its own ADRs for translation-specific decisions:

ID	Title	Version	Status
ADR-001	Clean Architecture	v1.0.8	Accepted
ADR-002	Decompose Layer Design	v0.1.1	Accepted
ADR-003	Decompose Layer Compliance	v0.1.1	Accepted

Translator ADR Versions

Translator ADRs are versioned with SPEC versions. ADR-001 has two versions:

• v0.1.1: Initial Clean Architecture proposal
• v1.0.8: Updated after SPEC v1.0.3 implementation

Codegen ADRs

The codegen package maintains its own ADRs for code generation decisions:

ID	Title	Version	Status
ADR-CODEGEN-001	Plugin-Based Codegen Targets for Manifesto Domains	v0.3.1	Accepted

---

ADR Status Definitions

Status	Meaning
Proposed	Under discussion, not yet implemented
Accepted	Approved, implementation started or pending
Implemented	Approved and fully reflected in SPEC/Changelog
Withdrawn	Reviewed and explicitly retracted with documented rationale
Deprecated	No longer recommended but may still be in use
Superseded	Replaced by a newer ADR

---

SPEC Changes from ADRs

ADRs often result in SPEC changes. Here's the traceability:

ADR-001: Layer Separation

Package	SPEC Version	Changes
World	v2.0.1	Event ownership, boundary definition
Host	v2.0.2	Snapshot type alignment

ADR-002: DX Improvements

Package	SPEC Version	Changes
Compiler	v0.5.0	$mel namespace, onceIntent syntax
App	v2.1.0	Platform namespace injection
World	v2.0.3	$mel namespace hash exclusion
Core	v2.0.1	Namespace alignment
Host	v2.0.2	$host namespace

ADR-003: World Owns Persistence (+ Issue #109)

Package	SPEC Version	Changes
World	v2.0.5	Head Query API, resume contract, branch state persistence
App	v2.3.1	Head Query delegation (getHeads(), getLatestHead())

ADR-010: Protocol-First SDK Reconstruction

Package	SPEC Version	Changes
SDK	v1.0.0	Complete reconstruction: createManifesto(), ManifestoInstance (5 methods), Runtime absorbed
Runtime	(retired)	Superseded — no successor SPEC. Responsibilities absorbed into createManifesto()

---

ADR Process

When to Write an ADR

Write an ADR when:

• Making a significant architectural change
• Resolving ambiguity in layer boundaries
• Introducing new patterns or conventions
• Making decisions that affect multiple packages

ADR Template

# ADR-XXX: [Title]

> **Status:** Proposed | Accepted | Implemented | Deprecated | Superseded
> **Date:** YYYY-MM-DD
> **Deciders:** [List of decision makers]
> **Scope:** [Affected packages/layers]

## Context
[What is the issue that we're seeing that is motivating this decision?]

## Decision
[What is the change that we're proposing and/or doing?]

## Consequences
[What becomes easier or more difficult as a result of this change?]

---

Related Documents

• Architecture - Current architecture overview
• Specifications - Normative contracts
• Design Rationale - Why decisions were made