# 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-workspace-compile \
  --root ../quixos-instance/workspaces/todo \
  --checkout-root /tmp/quixos-resolved-resources
```

`workspace.qx` contains workspace-local atoms, attachments, conformances, and
constructor bindings. Each imported interface has an `interface.qx` in its own
repository; each imported package similarly has a `package.qx`. Source
locations never appear in those declarations. `quixos.lock` supplies their
exact Git repositories and commits, and the workspace compiler resolves that
dependency graph recursively.

Inside an interface or package manifest, `import interface Named;` is a true
source dependency: the repository lock must pin it, and tooling may use the
full contract for generated types. `external atom` and `external interface`
declare nominal identities which the final importing workspace must provide.
The latter is appropriate for relationship targets and other opaque
references; it deliberately does not grant the contract needed for an
interface invocation port. This distinction permits mutually referential
interface identities without creating a cycle in the Git Merkle graph.

The compiler validates exact identities, recursive lock/source agreement,
external requirement satisfaction, 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`.
This is not a miniature workspace: a resource lock is only a Quixos toolchain
pin plus a dependency list. It pins exact Git sources for the interfaces and
packages named by that resource's own manifest. 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
quixos-resource-compile \
  --root . --kind package \
  --repository https://repos.quixos.org/example/package-example.git \
  --commit 1111111111111111111111111111111111111111 \
  --checkout-root /tmp/quixos-resource-dependencies
qx resource publish
```

The resource compiler validates the local manifest against the recursively
resolved locks without turning the resource into a workspace. The final
command runs from a jj checkout. It performs that same recursive compilation,
snapshots the current working-copy commit, and pushes the immutable tag
`refs/tags/quixos-reachability/<commit>` without advancing an authoring
bookmark.

A workspace root may split its resource pins into same-repository fragments:

```text
quixos-lock version 1 {
  quixos source {
    repository "https://repos.quixos.org/quixos/quixos.git";
    commit "1111111111111111111111111111111111111111";
  }
  import "locks/web-studio.lock";
}
```

```text
quixos-lock fragment version 1 {
  package CanvasRuntime source {
    repository "https://repos.quixos.org/org-quixos-web-studio/package-canvas-runtime.git";
    commit "2222222222222222222222222222222222222222";
  }
}
```

Import paths are normalized, repository-root-relative paths. Absolute paths,
URLs, traversal, empty segments, directories, and symbolic links are rejected.
Fragments may import other fragments; cycles fail, shared fragments are loaded
once, and duplicate resource bindings fail across the flattened closure.
`quixos-lock-check` resolves the complete closure and reports its `sourceFiles`
alongside the flattened resources. The root Git commit content-addresses every
fragment, so fragments do not become independent repositories or identities.

## 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, recursive repository assembly, external
requirement validation, source-order independence, ordinary call operations,
semantic validation, exact closure/tree-shaking, private and shared
attachments, related-object interface-port injection, and constructors.