Canonical IR

The canonical semantic contract and abstract target for language.

Forma is written for people and agents. The Fact Store is built for durable semantic memory. The Runtime SDK is built for execution. Canonical IR is the contract between them: a precise, typed, serializable representation of operational semantics after source has been expanded, checked, and normalized.

Canonical IR is where Meta-Effects stops being prose and syntax and becomes a target-independent framework. Forma language packages elaborate into it. Alpha Ontology is the prebuilt operational ontology stack that emits it. The Fact Store persists assertions over time. Runtime SDKs specify how a given IR graph is interpreted, persisted, projected, simulated, or deployed.

Why Canonical IR Exists#

Source should be pleasant. Runtime semantics should be strict.

Those are different jobs.

text

Markdown + Forma  -> reader  -> macro expansion  -> prelude elaboration  -> type and effect checks  -> canonical IR  -> runtime targets

Canonical IR lets Forma evolve without forcing every runtime target to understand every surface form. It also lets multiple language packages, DSLs, and source languages produce the same kind of executable structure. A runtime should not care whether an entity came from markdown, a generated package, a visual editor, or a future language frontend if the resulting IR is canonical.

Abstract Target#

A useful Canonical IR is the abstract target for language. It should be:

explicit
typed
deterministic
serializable
diffable
inspectable
versioned
suitable for code generation
suitable for runtime execution
suitable for AI interpretation

It should not depend on a specific UI, database layout, cloud provider, or programming language runtime.

That makes IR a framework, not a dump format. It owns identity, provenance, type references, capability boundaries, and the normalized shape of definitions. Language layers elaborate into it; runtime layers attach execution meaning to it.

Module Shape#

The module is the compilation unit.

lisp

(ir/module  (:id company.hr.hiring)  (:version "0.1.0")  (:uses ontology.alpha actor.alpha)  (:imports    [(company.hr.people [Person Employee])     (company.hr.permissions :as perms)])  (:exports [Candidate CandidateActor SubmitFeedback CandidatePipeline])  (:definitions [...]))

A source file may be markdown. A package may contain many files. But after elaboration, the runtime sees modules with canonical identities, imports, exports, and definitions.

Canonical Identity#

Every definition receives a stable identity.

text

company.hr.hiring/Candidatecompany.hr.hiring/CandidateActorcompany.hr.hiring/SubmitFeedbackontology.alpha/Entityactor.alpha/Actor

Local names are aliases. Canonical names are references. That distinction matters for imports, refactors, generated APIs, persisted facts, documentation, and AI tool calls.

Definition Nodes#

The v0 IR framework should stay small. The likely primitive nodes are:

Type for value shapes.
Entity for semantic objects.
Fact for assertions.
Query for pure derivation.
Policy for authority.
Actor for jurisdiction and ordered mutation.
Command for writes.
Event for history.
Effect for controlled interaction with the world.
Projection for interfaces and derived surfaces.

Workflow, form, dashboard, task, violation, queue, timer, notification, and agent are usually elaborated patterns over those primitives. If a pattern becomes stable enough, Alpha Ontology can promote it into a named elaboration without forcing the IR to inherit product-specific surface syntax.

Canonical IR Framework Services#

Canonical IR should support the services every language frontend and runtime SDK needs:

declaration identity and import/export resolution
source-to-IR provenance for diagnostics and editor jumps
normalized type, effect, policy, and capability references
structural diffs for review, migration, and generated artifacts
conformance fixtures for runtimes that claim to execute the same IR
stable JSON snapshots for agents, test runners, and external tools

Those services are the reason the IR sits in the center. It is not just the output of the compiler. It is the abstract target that lets the rest of the stack remain interchangeable.

Example Entity#

lisp

(ir/entity  (:id company.hr.hiring/Candidate)  (:attributes    [(:name :candidate/name      :type string      :cardinality one      :required true)     (:name :candidate/status      :type company.hr.hiring/CandidateStatus      :cardinality one      :required true)     (:name :candidate/person      :type (ref company.hr.people/Person)      :cardinality zero-or-one)]))

This is not a SQL table definition. A runtime may project it into tables, facts, indexes, generated forms, validation, SDK types, or documentation. The IR preserves meaning; targets choose layout.

Example Actor#

lisp

(ir/actor  (:id company.hr.hiring/CandidateActor)  (:key-by [:candidate/id])  (:owns [company.hr.hiring/Candidate])  (:state    [(:name status :type company.hr.hiring/CandidateStatus)     (:name pending-feedback :type (list company.hr.hiring/FeedbackRequest))])  (:commands    [company.hr.hiring/SubmitFeedback     company.hr.hiring/AdvanceCandidate])  (:events    [company.hr.hiring/FeedbackSubmitted     company.hr.hiring/CandidateAdvanced])  (:effects [assert-fact emit-event send-notification schedule-command]))

The actor node tells the runtime where mutation is ordered, which facts are authoritative, which messages are accepted, and which effects are allowed.

Example Command#

lisp

(ir/command  (:id company.hr.hiring/SubmitFeedback)  (:target company.hr.hiring/CandidateActor)  (:input company.hr.hiring/SubmitFeedbackInput)  (:policy company.hr.hiring/CanSubmitFeedback)  (:preconditions [company.hr.hiring/CandidateIsInterviewing])  (:handler    (do      (assert! feedback :feedback/rating input.rating)      (emit! company.hr.hiring/FeedbackSubmitted        {:candidate input.candidate         :interviewer input.interviewer}))))

The important property is inspectability. Before execution, the runtime can know what is being requested, who may do it, which actor owns it, and which effects may occur.

Purity Boundary#

The IR makes purity explicit.

text

Query   -> pure readPolicy  -> pure decision over facts and contextCommand -> mutation boundaryEffect  -> declared capabilityActor   -> ordered owner of execution

This is what keeps replay, simulation, testing, audit, and agent safety possible. If a query can call HTTP or mutate state, the model collapses. If effects are declared and commands are bounded, the runtime can reason about the system.

Target Lowering#

The same IR can lower to multiple targets.

text

Canonical IR  -> Effect TS schemas and handlers  -> Rust fact/query/actor kernel  -> Cloudflare Durable Objects  -> Fact Store assertions  -> SQLite or Postgres storage  -> generated HTTP APIs  -> generated forms and dashboards  -> agent tool schemas

No target owns the semantics. The IR owns the semantics.

Why Agents Care#

AI agents struggle when structure is implicit. The IR gives them a map of operational reality:

what exists
what can be queried
what can be changed
who may change it
which effects are available
which actor owns execution
what history must be preserved

An agent working against IR is no longer guessing from screenshots and ad hoc API docs. It is acting inside explicit institutional semantics.

Summary#

The IR is the durable platform boundary.

Forma is the DSL-builder and runtime platform. Alpha Ontology is the prebuilt operational ontology stack. The Fact Store preserves durable assertions. Runtime SDK implementations define how the result executes. The IR is the normalized operational graph those layers agree on.

That is the center of Meta-Effects: readable source elaborated into executable institutional memory.