# Cursors Lego Architecture

> **Status:** commentable architecture. Some blocks exist experimentally; the full composition does not yet.

Cursors should feel like one machine assembled from replaceable, typed parts. It should not feel like SQLite, Lua, Datalog, Cap’n Web, WebRTC, torrents, WASM, and a cockpit were introduced at a conference reception and later discovered they shared a repository.

The integration rule is simple:

> **Share terms, horizons, receipts, and socket contracts. Do not collapse semantic responsibilities.**

## 1. Whole machine

```mermaid
flowchart TB
  CR[Canonical signed Cursors records] --> ADMIT[Verify + admit]
  ADMIT --> DB[(SQLite operational body)]

  DB --> LOGIC[Cursor Logic fixpoint]
  DB --> SCHED[Continuation scheduler]
  DB --> SPACE[Leased dataspace projections]
  DB --> PLAN[Cryptofabric plan store]
  DB --> OUTBOX[Transactional outbox]

  LOGIC --> PROV[Provenance + causal cone]
  LOGIC --> PROPOSE[Candidate facts / plans]
  PROPOSE --> GATE[Authority + semantic verifier]

  SCHED --> EXEC[Replaceable language body]
  EXEC --> DB

  PLAN --> FABRIC[Carrier / store / recovery machinery]
  OUTBOX --> FABRIC
  FABRIC --> EFFECT[External effect boundary]
  EFFECT --> RECEIPT[Observation + stable receipt]
  RECEIPT --> DB
  RECEIPT --> CR

  DB --> COCKPIT[Guide embeds + full cockpit]
  PROV --> COCKPIT
  FABRIC --> COCKPIT
```

The durable semantic loop is:

```text
verified input
  → SQLite transaction
  → leased bounded computation
  → explicit intents
  → SQLite commit
  → post-commit effect
  → receipt
  → successor cursor
```

## 2. SQLite owns coordination, not meaning

```mermaid
flowchart LR
  UI[Imba / JavaScript UI] -->|MessagePort batch| SQL[SQLite owner Worker]
  SQL --> FACTS[Fact + rule indexes]
  SQL --> CONT[Continuations + leases]
  SQL --> TUPLES[Assertions + interests]
  SQL --> PLAN[Fabric plans + costs]
  SQL --> FX[Outbox + receipts]

  SQL -->|immutable task packet| LANG[Language executor]
  LANG -->|bounded result deltas + intents| SQL

  SQL -->|semantic records only| REMOTE[Remote SQLite body / mailbox]
```

SQLite may:

- select and lease work;
- execute indexed joins;
- maintain incremental deltas;
- store explicit continuation state;
- enforce transactions and idempotency;
- project canonical records into queryable relations;
- rebuild indexes after cache loss.

SQLite does not become:

- the signature format;
- the identity root;
- a remote page-replication protocol;
- arbitrary authority for SQL callers;
- proof that an outbox row became a completed effect.

## 3. One term, several language views

```mermaid
flowchart TB
  TERM[Cursor Term v0]
  TERM --> CURSO[CURSO canonical bytes\nhash / signature identity]
  TERM --> SQL[SQLite rows + indexes\nqueries / deltas / provenance]
  TERM --> SEXP[Canonical S-expression\nrules / plans / fixtures]
  TERM --> LUA[Plain Lua tables\nrestricted programs / host API]
  TERM --> JS[JavaScript / later Imba\nreference evaluator / browser UI]
  TERM --> NELUA[Nelua → C → native/Wasm\nfirst accelerator]
  TERM --> SCHEME[Scheme profile\nmacros / reflection / relational layer]
  TERM --> RUST[Rust and later competitors\nindependent parity implementations]
```

Different renderings are not different object models. They must round-trip through one versioned term and rule/plan IR.

## 4. Evaluator ladder

```text
                 frozen conformance vectors
                            │
          ┌─────────────────┼──────────────────┐
          │                 │                  │
 JavaScript reference   Nelua/C/Wasm      later competitors
 complete fallback      first accelerator Rust / Zig / others
          │                 │                  │
          └─────────────────┼──────────────────┘
                            │ parity gate
                            ▼
                    admitted result deltas
                            │
                            ▼
                      SQLite transaction
```

The JavaScript implementation remains complete. It may later be rewritten or generated in optimized Imba without changing semantics.

Nelua is first because it naturally meets Lua, C, SQLite, native execution, and Emscripten. Rust arrives later as an independent competitor, not as a ceremonial coronation.

Scheme is different: it should eventually prove that Cursors can exist coherently at the language level. Its macros and S-expressions may describe terms, rules, continuations, and capability-scoped host calls while all durable facts still pass through SQLite and Cursors records.

## 5. Logic and effects remain separated

```mermaid
flowchart LR
  FACTS[Facts at horizon H] --> RULES[Bounded Datalog rules]
  RULES --> DERIVED[Derived candidate]
  DERIVED --> WHY[Provenance / why]
  DERIVED --> CHECK[Capability + policy check]
  CHECK -->|denied| DENIAL[Inspectable denial]
  CHECK -->|allowed| INTENT[Explicit effect intent]
  INTENT --> COMMIT[SQLite + outbox commit]
  COMMIT --> EXEC[Post-commit executor]
  EXEC --> RECEIPT[Stable receipt]
```

A relation such as `candidate_resume(cursor, body)` is useful knowledge. It is not permission to resume.

## 6. Dedalus time and Cursors horizons

```mermaid
flowchart LR
  H0[Horizon H0\nheads A,B] -->|deductive rules| SAME[Derived facts at H0]
  H0 -->|inductive step / successor cursor| H1[Horizon H1\nheads C,B]
  H0 -->|asynchronous envelope| TRANSIT[Carrier / mailbox]
  TRANSIT -->|admitted receipt| HR[Receiver horizon HR]
```

Dedalus contributes three useful rule classes:

- **deductive:** reason within one logical instant;
- **inductive:** carry or derive state into the next logical instant;
- **asynchronous:** send to another location for delivery at a later logical time.

A Cursors causal horizon is not merely that time coordinate. It is the evidence-bearing cut from which a body reasons: cursor heads, curve, accepted roots, relation-completeness policies, leases, availability observations, and accepted receipts.

## 7. Cryptofabric plans are typed circuits

```mermaid
flowchart LR
  PTR[Pointer input] --> RES[Resolver]
  RES --> CHOOSE[Carrier planner]
  CHOOSE --> LOCAL[Local cache]
  CHOOSE --> RTC[WebRTC]
  CHOOSE --> HTTP[HTTP / webseed]
  CHOOSE --> MAIL[Mailbox]
  LOCAL --> HASH[Hash gate]
  RTC --> HASH
  HTTP --> HASH
  MAIL --> HASH
  HASH --> AUTH[Authority gate]
  AUTH --> TX[SQLite commit barrier]
  TX --> FX[Effect executor]
  FX --> RCPT[Receipt input]
```

Egglog may prove or discover equivalent local arrangements. It may not rewrite through the hash, authority, transaction, causal, curve, or receipt barriers.

## 8. Lego socket contract

Every component should publish this contract:

```text
component type
input term/profile
output term/profile
required capabilities
accepted causal-horizon shape
side-effect class
idempotency contract
receipt profile
failure states
barriers crossed
cost evidence
implementation body
```

Two components connect only when the sockets match. A generic arrow is not a contract, despite decades of diagramming software insisting otherwise.

## 9. Component families

| Family | Owns | Must not impersonate |
|---|---|---|
| Canonical records | portable signed facts | operational database |
| SQLite body | scheduling, projections, leases, commits | identity or protocol authority |
| Cursor Logic | bounded derivation and explanation | execution permission |
| Lua/Scheme source | human and language-level meaning | ambient host access |
| Nelua/Wasm | pure acceleration | semantic authority |
| Dataspace | current attributed coordination | durable causal history |
| Cryptofabric | movement, stores, recovery plans | identity or authorship |
| Capability plane | permission and attenuation | reachability |
| Effect adapter | bounded contact with the world | exactly-once mythology |
| Receipt plane | accepted evidence of effects | omniscient truth |
| Cockpit | inspectable projections | evidence invention |

## 10. What to merge, keep separate, or remove

### Integrate through Cursor Terms

- tuple values;
- rule ASTs;
- cryptofabric plan ASTs;
- continuation instructions;
- capability caveats;
- cockpit specimens;
- result and error values.

### Share SQLite machinery

- work leasing;
- fact and plan indexes;
- delta queues;
- provenance edges;
- horizons;
- transactional outbox;
- receipts;
- derived views.

### Keep semantically separate

- cursor ancestry and live dataspace state;
- reference and authority;
- delivery and execution;
- reconstruction and authenticity;
- current availability and durable identity;
- planned, simulated, configured, and observed state.

### Delete duplicate abstractions when proven redundant

- hand-written JS scans replaced by indexed SQL or compiled interests;
- separate ASTs that can use Cursor Terms;
- bespoke work queues already expressed by SQLite leases;
- transport-specific semantic records;
- UI-only graphs unrelated to actual machinery.

## 11. Comment points

These are the decisions most worth arguing about before freezing code:

1. Should Cursor Term v0 distinguish tuple, list, record, and constructor in canonical bytes, or encode some as profiles over one sequence type?
2. Should the first Datalog engine compile entirely to SQLite statements, or use SQLite only for indexes and a JS/Nelua fixpoint loop?
3. Which relations are safely `closed-at-horizon`, and who is authorized to declare that completeness?
4. Is the Lua DSL primary source, generated source, or merely one readable projection of canonical rule IR?
5. Should Scheme target the same restricted execution body as Lua, or remain a compiler/macro layer over Cursor Terms?
6. Which cryptofabric rewrites can be proven observationally equivalent with current receipts?
7. Which component costs belong in the signed plan, and which remain local measurements?
8. What is the smallest cockpit embed that counts as genuinely live without recursively loading the entire application?

## Related guides

- [Cursor Logic](cursor-logic.md)
- [Causal Horizons and Why-Not](causal-horizons-and-why-not.md)
- [Cryptofabric Plans and Egglog](cryptofabric-plans-and-egglog.md)
- [SQLite + Lua Cursor Machine](sqlite-lua-cursor-machine.md)
- [Architecture](architecture.md)