timothy
f4987093f6
- define and validate the capability and resource-lock languages - provision workspace source repositories through Central Gitea - build package runtimes from pinned standalone sources - replace legacy schema compilation with workspace persistence plans - add stable optimistic registers and Automerge CRDT documents - modernize TypeScript/Nix package builds and runtime activation readiness
65 lines
2.2 KiB
Markdown
65 lines
2.2 KiB
Markdown
# Quixos protocol and capability compiler
|
|
|
|
This package owns the shared protobuf APIs for Camino, `quixos-orch`, package
|
|
runtimes, package descriptors, and generic runtime values. It also owns the v1
|
|
capability authoring language and semantic compiler.
|
|
|
|
## Capability language
|
|
|
|
The grammar is `grammar/QuixosCapability.g4`. The parser lowers source into the
|
|
parser-independent records in `src/capability-model`; validation then produces
|
|
an immutable checked workspace JSON document. Runtime semantics do not depend
|
|
on parse-tree shapes or declaration order.
|
|
|
|
```sh
|
|
nix develop
|
|
quixos-capability-compile ../quixos-instance/workspaces/todo.capabilities.qx
|
|
```
|
|
|
|
The compiler validates exact identities, interface operation coverage,
|
|
attachment ownership, native state/edge providers, package receiver and
|
|
dependency-port requirements, constructors, and the exact runtime closure.
|
|
Generics, interface composition, declarative forwarding, automatic
|
|
relationship materialization, and first-class bundles are intentionally absent
|
|
from v1.
|
|
|
|
## Repository locks
|
|
|
|
Every workspace, interface, and package repository carries a `quixos.lock`.
|
|
It pins the exact Quixos toolchain revision plus exact Git sources for imported
|
|
interfaces and packages. The v1 Git source is deliberately only a repository
|
|
URL and full commit ID; the publisher-owned reachability tag and Nix fetch
|
|
details are derived from those values.
|
|
|
|
```sh
|
|
quixos-lock-check quixos.lock
|
|
qx resource publish
|
|
```
|
|
|
|
The second command runs from a jj checkout. It validates the lock, snapshots
|
|
the current working-copy commit, and pushes the immutable tag
|
|
`refs/tags/quixos-reachability/<commit>` without advancing an authoring
|
|
bookmark.
|
|
|
|
## Package descriptors
|
|
|
|
Executable package metadata remains protobuf text format:
|
|
|
|
```sh
|
|
quixos-descriptor-check path/to/descriptor.quixos-package.txtpb
|
|
```
|
|
|
|
Descriptors identify exact package revisions and exported runtime symbols.
|
|
The checked workspace binds interface operations to those exports and supplies
|
|
their exact dependency ports.
|
|
|
|
## Tests
|
|
|
|
```sh
|
|
nix develop -c yarn test
|
|
```
|
|
|
|
The suite covers parsing/diagnostics, source-order independence, ordinary call
|
|
operations, semantic validation, exact closure/tree-shaking, private and shared
|
|
attachments, package port injection, and constructors.
|