Foundational Design Rationale (FDR)

This page serves as a hub linking to the authoritative FDR documents maintained in each package's docs/ directory.

Status: Historical and rationale index

What is FDR?

FDR documents explain why design decisions were made. They complement SPECs (which define what) by providing rationale, alternatives considered, and consequences.

Package FDRs

Core Packages

Package	Latest FDR	Scope	Package Docs
@manifesto-ai/core	v2.0.0 (historical)	Compute equation, purity, patches	archive/FDR-v2.0.0.md
@manifesto-ai/host	v2.0.2 (inlined in host-SPEC)	Event-loop, snapshot ownership	host-FDR-v2.0.2.md

Application Layer

Package	Latest FDR	Scope	Package Docs
App facade (retired)	Removed (R2)	Legacy compatibility rationale	Retired Page
@manifesto-ai/compiler	v0.5.0	MEL syntax, IR design	FDR-v0.5.0.md
@manifesto-ai/sdk	v3.1.0 (accepted companion)	Projected schema graph, full-transition dry-run simulation, and introspection rationale staged into the living SDK spec	FDR-v3.1.0.md

Core/Host rationale is primarily available in each package SPEC Rationale block. SDK currently has an accepted rationale companion for projected introspection APIs; its normative contract appears in the living SDK spec.

---

App Transition Note

The former app compatibility facade has been removed in R2. App-era rationale remains part of project history and ADR context (see ADR-007, ADR-008).

---

Quick Links to Key FDRs

Core FDR Highlights

Core v2.0.0 - Foundational compute model

• FDR-C001: Pure compute equation
• FDR-C002: Snapshot immutability
• FDR-C003: Patch-only mutation

Host v2.0.2 - Execution model

• FDR-H001~H022: Event-loop, concurrency
• FDR-H023: Context determinism
• FDR-H024~H027: Snapshot type alignment

SDK v3.1.0 (accepted companion) - Introspection expansion

• FDR-SDK-001: Projected SchemaGraph influence graph
• FDR-SDK-002: Full-transition simulate() dry-run

Retired Package Rationale

The former @manifesto-ai/world rationale is retained only as historical split context. It is not a package FDR and is not a current package authority.

• Retirement record: @manifesto-ai/world
• Replacement authorities: Lineage SPEC and Governance API

---

FDR Document Structure

Each FDR typically contains:

## FDR-XXX: Decision Title

### Decision
What was decided.

### Context
Why the decision was needed.

### Rationale
Why this option was chosen.

### Alternatives Rejected
What other options were considered.

### Consequences
What follows from this decision.

---

Reading Guide

1. Start with SPEC - Understand what the system does
2. Read FDR for "why" - Understand design rationale
3. Check ADRs - For cross-cutting architectural decisions

Active product and package onboarding should start with maintained docs, not with the FDR hub.

FDR versions typically align with SPEC versions. Prefer reading the SPEC first, then the relevant FDR rationale when needed.