# 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.