graphdl-orm

An implementation of the AREST whitepaper — Compiling Facts into Applications.

Domain knowledge expressed as FORML 2 readings compiles into executable applications via Backus's FFP representation function. The system is a tuple (O, ρ, D, P, sub) where readings are FFP objects, ρ maps them to executables, state D is a sequence of cells, population P is Codd's named set, and sub dispatches inputs to state transitions producing REST representations with HATEOAS links.

Based on the work of John Backus (FFP/AST, 1978), E.F. Codd (relational model, 1970), Terry Halpin (ORM 2, 2008), and Roy Fielding (REST, 2000).

Architecture

readings (FORML 2)
    │
    ├─► parse_readings_wasm (Rust/WASM)  ──► entities (cells in D)
    │
    ├─► compile_domain (handle-based, from DEFS cell)
    │
    ├─► apply_command (create = emit ∘ validate ∘ derive ∘ resolve)
    │
    └─► representation (entity data + HATEOAS links + _view metadata)

Two Durable Objects, matching the paper exactly:

Component	Paper	Implementation
D (state)	Sequence of cells ⟨CELL, n, c⟩	EntityDB — one DO per entity. ↑n = get(), ↓n = put().
P (population)	↑FILE:D — named set of relations	RegistryDB — population index. Maps (type, id) to cells.
ρ (representation function)	Maps FFP objects to executables	Rust/WASM engine (arest). Compiles readings, evaluates constraints, forward-chains derivations.
sub (subsystem dispatch)	Routes inputs to state transitions	itty-router. Dispatches create/update/query/transition/load commands.

The complexity lives in ρ (WASM), not in the host.

Domains and Apps

Domains are NORMA tabs, not partitions. A domain organizes discourse — which readings are visible in a tab. Fact types are idempotent: "Customer has Name" declared in both "sales" and "support" is the SAME fact type. All domains compile to a single Universe of Discourse.

Apps lasso domains into databases. An App determines which domains are navigable and which users can access them. The Support Tickets app navigates the "support" domain. The admin view shows all domains.

App "Support Tickets"
  └── navigable domains: ["support"]
       └── entity types: Support Request, Support Response, Message, ...

App "Admin" (all domains)
  └── navigable domains: ["core", "state", "support", "stripe", ...]
       └── entity types: Noun, Reading, Constraint, Graph Schema, ...

Access control is expressed as readings in organizations.md:

User accesses Domain iff User has Org Role in Organization
  and Domain belongs to that Organization.
User accesses Domain if Domain has Access 'public'.

The engine evaluates these derivation rules — no procedural access control code.

Writing Readings

Readings are FORML 2 sentences — natural language with unambiguous grammar (Theorem 1).

# Support

## Entity Types

Support Request(.Request Id) is an entity type.
Category is a value type.
  The possible values of Category are 'question', 'feature-request', 'incident'.

## Fact Types

Support Request has Subject.
  Each Support Request has exactly one Subject.
Support Request has Category.
  Each Support Request has at most one Category.

## Constraints

It is obligatory that each Support Response is professional.

## State Machine

State Machine Definition 'Support Request' is for Noun 'Support Request'.
Status 'Received' is initial in State Machine Definition 'Support Request'.
Transition 'categorize' is from Status 'Received'.
  Transition 'categorize' is to Status 'Categorized'.

Abstract nouns prevent direct instantiation:

Request is abstract.

Or via totality: Each Request is a Support Request or a Feature Request.

Order and indentation do not matter. Each sentence has exactly one parse.

API

AREST routes (HATEOAS, constraint-derived navigation):

GET    /arest/:domain                       — domain root with navigable nouns
GET    /arest/:domain/:noun                 — list entities (cells in D)
GET    /arest/:domain/:noun/:id             — entity detail with HATEOAS links
POST   /arest/:domain/:noun                 — create (emit ∘ validate ∘ derive ∘ resolve)
POST   /arest/:domain/:noun/:id/transition  — fire state machine transition

Seed and evaluation:

POST   /seed                                — parse FORML 2 markdown via WASM
GET    /seed                                — population stats
POST   /arest/:domain/evaluate              — constraint evaluation

Self-describing representations include _view (view metadata derived from readings) and _nav (navigation context from access derivation rules):

{
  "docs": [...],
  "_view": { "type": "ListView", "title": "Support Request", "fields": [...], "constraints": [...] },
  "_nav": { "domains": [...], "apps": [...], "breadcrumb": ["support", "Support Request"] },
  "_links": { "self": "...", "collection": "...", "create": "..." }
}

Development

npm install
npm run dev          # wrangler dev
npm test             # vitest (161 tests)
npx tsc --noEmit     # type check

# Rust/WASM engine
cd crates/arest
cargo test           # 242 tests
wasm-pack build --target web --out-dir pkg

# Deploy
npx wrangler deploy

# Seed
curl -X POST https://api.auto.dev/api/seed -F "core=@readings/core.md" -F "support=@readings/support.md"

Theorems

The whitepaper proves six properties:

1. Grammar Unambiguity — each FORML 2 sentence has exactly one parse
2. Specification Equivalence — parse⁻¹ ∘ compile⁻¹ ∘ compile ∘ parse = id
3. Completeness of State Transfer — create reaches the least fixed point with all derived facts and violations
4. HATEOAS as Projection — transition links and entity hierarchy are θ₁ projections of P
5. Derivability — every value in the representation is (ρf):P for some f ∈ O

License

MIT