timothy
0c46850973
- run a singleton Codex App Server adapter in each dev workspace - gate Web Studio with a reloadable fragment-token to HttpOnly-session exchange - add ChatGPT device login and streamed chat to Web Studio - isolate authoring access in a declarative NixOS service account - split Web Studio canvas, object, panel, and model concerns - check generated Quixos protocol clients for drift - resolve same-repository quixos.lock fragments deterministically - preserve the collaborative canvas gesture fixes
122 lines
4.9 KiB
Markdown
122 lines
4.9 KiB
Markdown
# 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.
|