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.

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.

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:

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

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:

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

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.