docs: describe toolchains as a typed bin/src/license document
commit
ef411fddocs: describe toolchains as a typed bin/src/license document
Updates storage.adoc’s collection-shape note, cli.adoc’s toolchain command list, and checks.adoc’s sandbox description to match the typed Toolchain document: bin/src as raw-passthrough trees plus a required license, and PATH activation reading Toolchain::bin explicitly rather than assuming a bin/ layout inside a bare imported tree.
Assisted-by: Claude:claude-sonnet-5
Reviews
No reviews of this commit yet — record a verdict below.
Start a review
docs/spec/checks.adoc
@@ -78,13 +78,15 @@
run via `sprite auth setup`, so the credential stays current without restart.
Before running a check that names a toolchain, the worker MUST resolve each
-distinct toolchain named across the job's checks (<<checks.toolchains>>) and
-extract it into the Sprite at a hash-keyed directory, skipping the extraction
-when that directory already exists — the Sprite's persistent filesystem is
-the cache, so the same toolchain is never re-extracted across pushes. A
-check's command MUST then run with each of its named toolchains' `bin`
-directory prefixed onto `PATH`, in the order they are declared, so an earlier
-toolchain takes precedence over a later one on a name collision.
+distinct toolchain named across the job's checks (<<checks.toolchains>>) to
+its typed `bin` tree (`git-toolchain`'s `Toolchain::bin`, not the whole
+document) and extract that tree into the Sprite at a hash-keyed directory,
+skipping the extraction when that directory already exists — the Sprite's
+persistent filesystem is the cache, so the same toolchain is never
+re-extracted across pushes. A check's command MUST then run with each of its
+named toolchains' extracted `bin` directory prefixed onto `PATH`, in the
+order they are declared, so an earlier toolchain takes precedence over a
+later one on a name collision.
--
[role="requirement", id="checks.outcomes"]
docs/spec/cli.adoc
@@ -68,12 +68,15 @@
--
The CLI MUST provide, under `git ents toolchain`:
-* `import` — write a local directory's contents to `refs/meta/toolchains/<name>`
- on a remote and push it, creating the ref when absent.
-* `list` — render every toolchain configured on a remote with its root tree id.
-* `export` — recreate a remote's named toolchain under a local destination
- directory, restoring the executable bit and symlinks; read-only, per
- <<cli.remote-admin>>.
+* `import` — write a local `bin` directory (and, optionally, a `src`
+ directory) plus a license to `refs/meta/toolchains/<name>` on a remote and
+ push it, creating the ref when absent. `bin` MUST be non-empty and
+ `license` MUST be non-empty.
+* `list` — render every toolchain configured on a remote with its `bin`
+ tree id and license.
+* `export` — recreate a remote's named toolchain's `bin` (and `src`, if
+ present) under a local destination directory, restoring the executable bit
+ and symlinks, and print the license; read-only, per <<cli.remote-admin>>.
* `remove` — delete the toolchain's ref on a remote.
--
docs/spec/storage.adoc
@@ -64,10 +64,15 @@
`comments/<genesis-hash>`) via the shared `git_store::new_id`
(origin-or-content-hash), so filing an item never contends a counter and
the identity rule cannot drift between collections. `toolchains/<name>`
- (`git-toolchain`) is a named collection like `member/<username>`, but its
- item is a directory tree imported wholesale rather than a `Facet` document
- — the one collection whose identity is its own root tree hash
- (`Store::store_tree`/`ref_tree`) instead of a deserialized value.
+ (`git-toolchain`) is a named collection like `member/<username>`, and its
+ item is a `Facet` document like any other — a `bin` directory tree, an
+ optional `src` directory tree, and a license — but `bin` and `src` are each
+ captured whole as a `facet_git_tree::RawTree`, a raw-passthrough field
+ wrapping an already-written tree's object id rather than a directory
+ layout `Facet` could model field-by-field. `Store::store_tree`/`ref_tree`
+ write and read the document's root tree directly, since the two
+ directories underneath must be written into the object database before the
+ document that references them can be assembled.
Authored collections::
A collection whose documents treat the commit as the record