Spec 0001 — Compiler kernel (`@effx/ir`, `@effx/compiler`)

Status: frozen 2026-10-03. Changes require editing this file explicitly. Source: docs/research/2026-10-02-deep-research-report.md §"Compiler and IR architecture", §"Research suite", §"Roadmap" (gate 1).

GoalCopy Anchor Link

One vertical proof that annotations become a Schema-defined IR, that the IR has stable laws (round trip, normalization, canonicalization, graph projection, determinism, syntax equivalence), and that extensions interpret annotations / analyse the graph / generate ordinary Effect without touching the core.

Non-goals (other slices): TypeScript frontend, runtime decorators, Cedar, persistence, CLI binary.

JourneyCopy Anchor Link

Collected (frontend-neutral declarations + annotations)
   │ interpret: every Extension.interpreters[annotation.name]
   ▼
Contribution* ──merge──▶ ApplicationIR ──normalize──▶ IR₀
                                                      │ toGraph
                                                      ▼
                           analyses(IR₀, GraphIndex) ──▶ Diagnostic[]   (errors block generation)
                                                      │
                           generators(IR₀, GraphIndex) ──▶ GeneratedFile[]

IR vocabulary (@effx/ir)Copy Anchor Link

StableIdCopy Anchor Link

Branded string, grammar (one regex, no spaces):

StableId   := kind ":" name
kind       := [a-z][a-z0-9-]*
name       := [A-Za-z0-9_$] [A-Za-z0-9_$./:-]*

Helpers: StableId.make(kind, name), kindOf, nameOf.

References (no source locations, no ts.*)Copy Anchor Link

Nodes (closed tagged union on _tag, plus one escape)Copy Anchor Link

Decision: core Exposure.transport is a closed union (http/rpc/cli) because core analyses (e.g. "Query exposed via non-GET") must pattern-match exhaustively. Third-party transports and any other new concept use Extension nodes (ext: ids) — they survive normalization, canonical JSON and graph projection without a core schema change. Promotion into the core union is a versioned IR migration.

EdgesCopy Anchor Link

{ kind, from: StableId, to: StableId, qualifier?: string } with kind ∈ { InputOf, SuccessOf, ErrorOf, Requires, AuthorizedBy, Focuses, ExposedAs, PersistsAs, ViewOf }.

Edges may point at absent nodes; that is data (missingTargets), not a decode failure.

EnvelopeCopy Anchor Link

ApplicationIR = { format: "effx-ir", version: 1, nodes: Node[], edges: Edge[] }, an Effect Schema. Codec, Arbitrary and type are derived from it.

Normalization (normalize)Copy Anchor Link

Duplicate ids with different content are preserved (reported by analysis EFFX1001).

Canonical JSON (canonical)Copy Anchor Link

RFC 8785 over encode(normalize(ir)): object keys sorted by UTF-16 code units, no whitespace, primitives via ES6 JSON.stringify semantics (strings, finite numbers, booleans, null). semanticHash(ir) = hex(sha256(utf8(canonical(ir)))) via the Effect Crypto service (provided by BunCrypto.layer at composition roots). encode/decode are Schema-derived (Schema.toCodecJson, Schema.fromJsonString).

Graph index (graph)Copy Anchor Link

toGraph(ir): GraphIndex { graph: Graph<Node, Edge>, byId: HashMap<StableId, Node>, ids: Trie<StableId>, dangling: Edge[], duplicates: StableId[] }. fromGraph(index): ApplicationIR (normalized). Helpers: outgoing(index, id, kind?), reachable(index, id), cycles(index), missingTargets(index), withPrefix(index, prefix).

Arbitrary adapter (arbitrary)Copy Anchor Link

arbitraryIR() wraps effect/Arbitrary (unstable) and is the only module importing it.

Compiler contract (@effx/compiler)Copy Anchor Link

DataCopy Anchor Link

Services and extensionsCopy Anchor Link

SourceFrontend.analyze(project: ProjectConfig) => Effect<Collected, CompilerFault>

Extension = { name, interpreters: Record<annotationName, Interpreter>, analyses: Analysis[], generators: Generator[] }
Interpreter(annotation, declaration, ctx) => Contribution { nodes, edges, diagnostics }
Analysis(ir, index) => Diagnostic[]
Generator(ir, index) => Effect<GeneratedFile[], CompilerFault>

Built-in extensions: core (Query, Command, Errors, Requirements, PersistentModel, Authorize), http (Http.Get/Post/Put/Patch/Delete), rpc (Rpc), cli (Cli), client (generator only). SchemaRef.module / SymbolRef.module are import specifiers the frontend guarantees resolvable from the generated directory; generators emit them verbatim.

Annotation argument shapes (what both decorators and builders lower to)Copy Anchor Link

Schema = { _tag: "Schema", ref: SchemaRef }, Symbol = { _tag: "Symbol", ref: SymbolRef }. The Query/Command interpreter owns the Operation node and its edges and reads sibling Errors/Requirements annotations for declared sets; the Errors/Requirements interpreters only compare declared vs inferred (they need handlerSignature, which is not in the IR), so EFFX22xx/23xx are produced during interpret, not analyze.

Diagnostic codesCopy Anchor Link

Pipeline stagesCopy Anchor Link

collect → interpret → merge → normalize → analyze → generate; every stage returns StageResult; diagnostics accumulate; any error severity → generate is skipped (value: none).

Laws (tests)Copy Anchor Link

Definition of doneCopy Anchor Link

• bun run typecheck, bun run lint, bun run fmt:check, bun --bun vitest run green.
• User slice fixture compiles to the expected IR and generates http.ts, rpc.ts, cli.ts, client.ts.
• All laws above are executable tests (property-based where Arbitrary derives).