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.

Local workspace fragments, source-editing APIs, and generated package contracts are documented in QX bindings and tooling. 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.

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:

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";
}

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.