# Cursors context kernel
> **Purpose:** this is the one small document an agent should read before working on Cursors. Do **not** preload the README, book, all guides, all issues, and every research branch. Read this, then use `npm run context -- "the task or concept"` to retrieve a bounded task-specific context pack with provenance.
>
> This file is an index and semantic spine, not a substitute for reading exact source/tests when changing them. It exists because making every agent rediscover several years of research by burning a novel's worth of tokens is not a systems architecture.
## 0. Name and scope
**Cursors** is the product and research system. **`curso.rs`** is its public home and repository name. **CURSO/0** is the legacy/current v0 canonical record profile, not the product name.
Cursors explores computation whose durable identity is not a process, host, socket, database connection, provider, or cloud deployment. The durable center is the **cryptocursor**: an immutable, signed, causal continuation that can pause, advance, split, join, delegate/attenuate authority, migrate between execution bodies, name immutable state and outputs, and carry evidence about effects.
The system is browser-first but deliberately host-, language-, transport-, and provider-independent. SQLite is the preferred boring local machine. Metasocketry is the companion virtual socket/topology substrate. Cursors also studies curved dataspaces, Datalog/Prolog-style explanation, cryptofabric planning, content-addressed recovery, mobile/offline execution, and a live evidence-oriented cockpit.
## 1. The correction agents must not regress
### A cryptocursor carries authority. There is no separate top-level capability plane.
Older source, docs, issues, and book drafts sometimes describe a five-plane system with a distinct **capability graph** beside the cryptocursor DAG. That model is superseded for architectural reasoning.
Authority is part of the cryptocursor's durable causal continuation. A cursor's authority lineage can be attenuated, delegated, partitioned at a split, joined under explicit rules, presented for an effect, and cited by later evidence. **CURSO/0 currently materializes parts of that authority lineage through `grants[]` and separate grant/split records. Keep those byte-level compatibility structures until a reviewed profile transition changes them, but do not reify them into an independent semantic universe.**
Useful vocabulary such as *grant*, *capability*, *attenuation*, *presentation*, *redemption*, and *authority proof* remains valid. The mistake is treating capability state as a separately living graph that can drift away from the cursor whose continuation it authorizes.
A concise model is:
```text
cryptocursor
= causal continuation
+ immutable state/input/output references
+ authority lineage / attenuation / delegation
+ effect intent and receipt references
+ continuation/body requirements
+ signed ancestry
```
Authority evidence can be stored in independently addressed records, just as state and receipts can. Addressability does not make it a separate top-level semantic plane.
## 2. The whole machine
Think in **responsibilities**, not a stack of fashionable libraries.
```text
World / Self / curve-relative view
|
v
Cryptocursor DAG
history + continuation + authority + receipts
|
+-------------------------+
| |
v v
Curved dataspace Cursor Logic / Cryptolog
assertions/interests why / why-not / planning facts
leases/facets Datalog core, Prolog/Trealla surface
| |
+------------+------------+
v
SQLite body
transactions / leases / indexes / horizons
outbox / mailbox / projections / scheduling
|
verified intent/plan
v
cryptofabric planner
content/recovery/effect movement under hard invariants
|
+----------+-----------+
| |
v v
Metasocketry content providers
typed virtual handles HTTP/webseed/torrent/cache/
live topology/sessions checkpoint/fountain/F3/etc.
|
MessagePort / WS / iroh / libp2p / WebRTC / TCP / radio / ...
|
receipts
|
+-------> SQLite / successor cryptocursor
```
### Object/content plane
Immutable objects, program artifacts, checkpoints, chunks, manifests, and state roots are content-addressed material. **Content identity is not availability, authority, transport identity, or attestation identity.** Different carriers may provide the same canonical object.
### Cryptocursor plane
The cryptocursor is the durable causal execution point and authority-bearing continuation. Parents define causal ancestry; continuation + state say how work may resume; authority is carried/attenuated with that continuation; outputs must already be stable references before a cursor claims them; receipts preserve evidence around external effects.
A cursor is not a process snapshot, bearer secret, packet, actor PID, RPC stub, SQL row, or transport connection.
### Curved dataspace
Linda/Syndicate-inspired assertions, interests, facets, leases, and attributed tuples express **current coordination**, not immutable history. A curve is an observer-/relationship-/authority-relative projection of a world. There is no assumption of one globally consistent tuple space or global `now`.
### SQLite body
SQLite owns body-local operational truth: scheduling, transactions, leases, queues, indexes, projections, outbox state, mailbox state, logic facts/horizons/provenance, and rebuildable views. SQLite is not the wire format or identity root.
Preferred rule: **sync semantic rows/objects, never pretend remote SQLite pages/WAL are one distributed database.** Browser bodies use the official SQLite Wasm Worker/VFS work; native bodies use ordinary SQLite. `ATTACH` is useful for local composition and staged immutable checkpoints.
### Cursor Logic / Cryptolog
The safe center is bounded Datalog-style relational evaluation, with Prolog/Trealla-like human query and explanation surfaces. Logic may derive, explain, compare, and propose. It may not silently create authority, execute an effect, declare missing open-world evidence false, or trust its own proof.
Important states include `supported`, `blocked/refuted under explicit closure`, `unknown`, and `conflicted`. Every negative conclusion needs a named completeness/closure basis. Dedalus/CALM ideas matter for distinguishing same-horizon deduction, successor state, and asynchronous delivery.
### Cryptofabric
A cryptofabric is the semantic movement/recovery plan around Cursors material. It chooses among stores, carriers, mailboxes, reconciliation, reconstruction, and effect paths while preserving cursor/object/effect identity and authority semantics. Planner/optimizer output is untrusted until independently verified.
### Metasocketry
`Spaceghost/metasocketry` is a companion substrate, not a competing Cursors semantics layer. Its direction is a **virtual BSD/Plan-9-like typed handle system**: a logical communication/resource handle may survive carrier changes and can expose only operations the realization actually supports (`send/recv`, `read/write`, `listen/accept`, `poll`, etc.). Do not force everything to cosplay as a byte-stream file.
A high-level `open()` may resolve a semantic target to a typed `MetaHandle`; compatibility veneers may look like `socket()`, `fopen()`, `connect()`, `listen()`, `send()`, and `recv()`. The handle is local/ephemeral; cursor identity and authority are durable Cursors semantics. Endpoint IDs, routes, sockets, and carriers are never identity or authority.
Metasocketry owns live byte movement/topology/session machinery. Cursors owns causal meaning, authority, effect identity, acceptance, and receipts. Generic Caravan routing/relay/store behavior should migrate toward Metasocketry; signed Cursors-specific discovery/recovery semantics remain in Cursors.
## 3. The durable loop
The normal successful path is deliberately boring:
```text
admit canonical evidence
-> SQLite transaction / local horizon
-> derive or select bounded work
-> verify cursor authority and hard constraints
-> lease execution / build effect intent
-> commit state + transactional outbox
-> post-commit movement or external effect
-> observe acceptance/completion/uncertainty
-> admit a receipt/evidence record
-> seal successor cryptocursor
```
Never collapse these facts:
```text
parsed != authenticated != locally accepted
accepted != authorized
reference != authority
reachable != authorized
transport arrival != authorship
outbox intent != submission
submission != remote acceptance
remote acceptance != application execution
decryption != authorization
receipt != omniscient truth
carrier availability != content identity
body != Self
process != cursor
current dataspace != durable history
modeled/planned != observed
```
## 4. Persistence classes
Cursors repeatedly uses three classes:
**Portable/canonical truth:** canonical objects, cryptocursors, authority lineage evidence, signed receipts, immutable checkpoints/manifests. Independently verifiable.
**Operational truth:** SQLite queues, leases, local policy, mailbox state, transport dedupe, Metasocketry spool/session observations, quota and retry state. Must be transactionally sane but may be body-local.
**Derived/rebuildable:** indexes, search/vector projections, cockpit caches, analytics, route estimates, materialized explanations. Losing them must not rewrite history.
Secrets/private keys are local protected state and are never smuggled into durable public cursor bytes merely to make recovery convenient.
## 5. Context and knowledge architecture
The project itself needs to dogfood its reasoning model for agents.
Issue #94 defines the intended semantic knowledge index: canonical concept/claim/source/status records, relational edges such as `implements`, `requires`, `forbids`, `supersedes`, `contradicts`, `use_when`, and `evidence_for`, optional vector hints for fuzzy recall, and provenance on every extracted fact. **Embeddings propose candidates; they never establish truth or freshness.**
This repository now starts smaller and useful:
```sh
npm run context -- "metasocketry open listen sqlite"
npm run context -- "cryptocursor authority attenuation split"
npm run context -- "trealla causal horizons why not"
npm run context -- --catalog
```
The context packer searches tracked source/docs/tests, Git research refs when requested/available, and the GitHub issue corpus when `gh` is authenticated. It has a hard output budget and reports source provenance. Agents should retrieve more only when the current task needs it.
**Do not solve context by concatenating the book.** The book is valuable, but some chapters deliberately preserve research history and can lag current decisions.
## 6. Source precedence and staleness
When sources conflict, use this order unless the user explicitly overrides it:
1. **Direct current user decision.** The user is the architecture authority for an unresolved design decision.
2. **This context kernel for current conceptual vocabulary and explicit supersessions.** Keep it small and update it when a major decision changes.
3. **Approved/active design/spec ledger for the workstream being changed**, including exact branch/SHA when an issue records one.
4. **Executable code, protocol vectors, tests, and current schemas** for claims about what actually exists.
5. **Current `main` architecture/security docs and runbooks.**
6. **Current issues/PRs** for roadmap, open decisions, audits, and work that intentionally has not landed.
7. **Book chapters, enjoyer guides, research branches, historical proposals, and old issues.** These are essential research evidence but may contain superseded architecture.
Never silently erase old research. Mark it **superseded**, **historical**, or **research-only** and preserve why it was interesting.
A current code structure can also be legacy compatibility rather than preferred architecture. Example: CURSO/0 has separately sealed capability grant/split records and cursor `grants[]`; that is a current byte/API reality, while the current conceptual model treats authority as part of the cryptocursor continuation rather than a separate top-level plane.
## 7. Current implementation baseline
At `main` around the context-kernel introduction, the repository contains real executable slices including:
- CURSO/0 canonical values and signed cursor/capability/mailbox records;
- cursor fan-out/fan-in and pause/migrate/resume examples;
- SQLite Wasm body/Worker machinery, strict schemas, authorizer boundaries, transactional outbox and receipts;
- restricted Lua program/cursor-machine work and JS/Nelua/Wasm parity experiments;
- Cursor Cells experiments;
- Open MCT operations/cockpit surfaces;
- WebTorrent/WebRTC and native bridge observation paths;
- Cap'n Web experiments;
- signed swarm/bootstrap/recovery experiments;
- a substantial book/guide/research corpus.
Do not inflate those slices into claims of production-grade distributed execution, exactly-once effects, global consensus, perfect durability, universal WebRTC, or completed hostile-peer security. The project's audits are intentionally severe about this.
## 8. Research program and obscure lineages
The following are not decorative citations. They are part of the project's mechanism vocabulary and should be discoverable through context packs.
### Distributed OS / naming / mobility
Sprite, Plan 9, Inferno/Styx/9P, Amoeba, LOCUS, Emerald, Obliq, Orleans, KeyKOS, EROS, CapROS, Coyotos, Ken/MaceKen, BEAM/OTP, Smalltalk/Squeak/Self, process migration, processor pools, orthogonal persistence, mobile objects/continuations, capability-secure namespaces.
**Current synthesis:** Sprite-like single-computer experience without pretending failure/authority are global; Plan-9-like openable namespaces but typed handles rather than universal fake files; Amoeba/E/seL4 lessons for explicit authority; migration as cursor continuation re-placement rather than moving a hidden process heap.
### Coordination / logic / explanation
Linda, LIME, Syndicate, Datalog, Prolog, Trealla, Dedalus, Bloom/CALM, provenance semirings, Whyline, Causeway, Oddity, ShiViz, Pivot Tracing, miniKanren, Scheme, egglog/e-graphs, differential dataflow, DBSP, Soufflé, Flix/Formulog/DDlog, Petri nets, Kahn/dataflow networks, Ptolemy/LabVIEW-like executable graphs.
**Current synthesis:** bounded facts over explicit horizons, open-world honesty, explainable why/why-not, independent verification, and logic as candidate/explanation machinery rather than authority.
### Replication / P2P / recovery
Caravan, BitTorrent/WebTorrent, SSB, Cable/Cabal, Hypercore/Autobase, Willow, Freenet, GNUnet, Tahoe-LAFS, IPFS/IPNS, NDN/CCN, DTN Bundle Protocol, minisketch, range/Merkle reconciliation, rateless IBLT, LT/Raptor/RaptorQ, network coding, fountain recovery, sparse replication, query-shaped sync, removable media/sneakernet, F3 causal-segment research.
**Current synthesis:** reconcile identities/sets separately from reconstructing bytes; verify content independent of source; optimize time-to-first-useful causal future rather than full synchronization.
### Authority / live RPC / privacy
Macaroons, Biscuit, object capabilities, E/Waterken/OCapN, Cap'n Proto/Cap'n Web, seL4/Amoeba capability lessons, Signal/MLS and metadata-private messaging research, scoped redemption/settlement.
**Current synthesis:** authority belongs to the cryptocursor's causal continuation; live RPC stubs/sockets are ephemeral realizations; external effects require explicit evidence/receipt semantics; privacy mechanisms never manufacture authority.
### Storage / local-first / evidence
SQLite application-file/Fossil patterns, OPFS VFS, DuckDB/Parquet where analytical projections help, content-addressed object DAGs, storage/custody proofs, twining/cooperative persistence, checkpoints/resurrection capsules, formal/model-checker traces, deterministic simulation and lineage-driven fault injection.
## 9. Important work indexes
Use the context packer to fetch these rather than reading all of them by default.
- **#8**: canonical product context and Caravan absorption. Important but contains older separate-capability-plane wording.
- **#94**: semantic knowledge index and bounded agent context packs.
- **#97**: adversarial evaluation for search/context machinery.
- **#151**: serialized Advanced Research Program ledger and current research gates.
- **#137**: S0 core-integrity/profile-transition work (issue number may have older book history elsewhere; use title/current body, not number folklore).
- **#102 / #103**: cryptocursor and cryptofabric mini-book/research review queues.
- **#110 / #133**: bodies, continuation placement, scheduling/resource-aware execution.
- **#146**: causal fast boot, causal cones, Trealla, SQLite capsules, progressive execution.
- **#150**: F3 causal segment provider research.
- **#74 / #122**: Cryptolog and proof-preserving cryptofabric planning.
- **#100**: large mini-book/research queue. This is a map, not automatic endorsement.
- **Metasocketry repository**: socket-shaped adapters, routed Fabric/PeerSocket, relay/store, and the emerging typed virtual-handle/open model.
Issue numbers are navigation hints. Titles, current body, exact branches/SHAs, code, and tests are stronger evidence than an old reference to a number whose scope evolved.
## 10. Development rules that save future archaeology
- Freeze semantic invariants and vectors before coronating an implementation language.
- Keep JavaScript/browser fallbacks where the architecture promises them; accelerators must earn parity.
- Keep SQLite boring and local; do not turn it into a magical distributed pager.
- No durable protocol record contains POSIX paths, file descriptors, browser objects, JS callbacks, raw socket handles, private keys, bearer secrets, or ambient authority.
- Failure, replay, duplication, expiry, partition, stale state, mutation, and resource exhaustion need executable tests.
- Every UI status names its evidence class: observed, verified, derived, configured, planned, simulated, unavailable, stale, conflicted, or unknown.
- A carrier/provider/optimizer may be replaced without changing canonical meaning.
- If a research mechanism becomes unnecessary, preserve the research note and delete the duplicate runtime abstraction.
- Metasocketry and Cursors should share narrow typed contracts, not duplicate routing stacks.
- Agents should update this file when they intentionally supersede a project-wide concept. Otherwise the next model will faithfully excavate the wrong civilization.
## 11. Agent startup: spend tokens only when needed
1. Read `AGENTS.md` for workflow constraints.
2. Read **this file**. Stop preloading project prose.
3. Run a bounded retrieval for the actual task:
```sh
npm run context -- "<task in plain language>"
```
4. Read exact implementation/tests returned by the pack before editing those paths.
5. If the task concerns a historical design, use `--all-refs`; if it concerns roadmap/research, ensure `gh` is authenticated so issue bodies are searchable.
6. Before asserting that something is shipped/current, prefer executable source/tests/current issue ledger over prose volume.
For a broad architecture task, a good seed query is:
```sh
npm run context -- "cryptocursor authority sqlite metasocketry cryptofabric logic current architecture"
```
For everything discoverable without dumping it into the prompt:
```sh
npm run context -- --catalog
```
The desired agent experience is: **one small context kernel, one task query, then exact sources.**