Build workspace agent, capability graph, and versioned cutovers

README.md

@@ -13,10 +13,29 @@ on parse-tree shapes or declaration order.
 
 ```sh
 nix develop
-quixos-capability-compile ../quixos-instance/workspaces/todo.capabilities.qx
+quixos-workspace-compile \
+  --root ../quixos-instance/workspaces/todo \
+  --checkout-root /tmp/quixos-resolved-resources
 ```
 
-The compiler validates exact identities, interface operation coverage,
+`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
@@ -26,21 +45,69 @@ from v1.
 ## Repository locks
 
 Every workspace, interface, and package repository carries a `quixos.lock`.
-It pins the exact Quixos toolchain revision plus exact Git sources for imported
-interfaces and packages. 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.
+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
-qx resource publish
+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 second command runs from a jj checkout. It validates the lock, snapshots
-the current working-copy commit, and pushes the immutable tag
+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:
@@ -59,6 +126,7 @@ their exact dependency ports.
 nix develop -c yarn test
 ```
 
-The suite covers parsing/diagnostics, source-order independence, ordinary call
-operations, semantic validation, exact closure/tree-shaking, private and shared
-attachments, package port injection, and constructors.
+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.