quixos-protocol/README.md

# Quixos protocol and capability compiler

Shared protobuf APIs for Camino, orch, package runtimes/descriptors and values,
plus the capability language/compiler. Commands below are for backend development;
workspace authors use `qx-workspace check` for all verification.

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

Local workspace fragments, source-editing APIs, and generated package contracts
are documented in [QX bindings and tooling](../docs/QX_BINDINGS_AND_TOOLING.md).
`quixos-resource-compile --schema-out` exports the portable generator input;
`quixos-codegen-ts` is the first backend. `quixos-qx` provides parse, lint,
format, and nominal-atom scaffold commands.

## Repository locks

Every workspace, interface, and package repository carries a `quixos.lock`.
A resource lock is not a miniature workspace: it contains only the exact
Quixos commit that resource was authored against plus its dependency list.
It also pins exact Git sources for interfaces and packages named by that
resource's own manifest. Resource Git sources are deliberately only a
repository URL and full commit ID; the publisher-owned reachability tag and
Nix fetch details are derived from those values.

A workspace root additionally records its Quixos selection policy and ref.
Its `commit` is the exact compatibility baseline shared by the resource graph,
not necessarily the runtime candidate. `pinned` requires the ref, baseline,
and candidate to be one commit. `track-development` lets Central resolve the
named development ref to a newer candidate while preserving the authored
baseline. `track-release` is reserved for compatibility-filtered release-line
advancement and is not implemented yet.

```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-workspace 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";
    policy track-development;
    ref "dev/alice/main";
    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.