feat(sys): astrid:sys@1.1.0 superset adding capsule-set-epoch#18
feat(sys): astrid:sys@1.1.0 superset adding capsule-set-epoch#18joshuajbouw wants to merge 2 commits into
Conversation
…pection Additive companion to sys@1.0.0 (not a superset; it mutates no existing shape). Exposes a single read-only introspection call returning a stable hash of the sorted (capsule-id, package-version) set — moving on install / removal / version-bump, restart-stable, infallible (0 when the registry is momentarily unavailable). Lets a consumer keyed on the loaded set (e.g. a per-principal tool-schema cache) self-heal on its own next turn instead of relying on a kernel-side per-principal invalidation fan-out.
Carry every @1.0.0 type and function into @1.1.0 verbatim (alongside the new capsule-set-epoch), so a guest can bind only the latest version and still reach the whole system surface — the http@1.1.0 pattern. The host backs both from one impl; the @1.1.0 carry-overs delegate to the @1.0.0 path.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new WIT interface file host/sys@1.1.0.wit defining system-level runtime functions, which is an additive successor to version 1.0.0. It adds a new capsule-set-epoch function to return a stable hash of the currently-loaded capsule set. The reviewer suggests changing the return type of capsule-set-epoch from u64 to option<u64> to avoid using a magic value of 0 when the registry is temporarily unavailable, which could otherwise lead to false cache matches.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| /// Return a stable hash of the currently-loaded capsule set — the sorted | ||
| /// (capsule-id, package-version) pairs across every registered capsule. The | ||
| /// value MOVES on install / removal / version-bump, is load-order | ||
| /// independent, and is restart-stable (no process state), so a consumer | ||
| /// keyed on the loaded set (e.g. a per-principal tool-schema cache) can | ||
| /// re-validate cheaply on its own next turn. Ungated, read-only | ||
| /// introspection like enumerate-capabilities. Infallible — returns 0 if the | ||
| /// registry is momentarily unavailable (a value that won't match a | ||
| /// populated cache's stored epoch, biasing toward a safe refresh). | ||
| capsule-set-epoch: func() -> u64; |
There was a problem hiding this comment.
Returning a magic value of 0 when the registry is momentarily unavailable can lead to correctness issues. If a client starts up with an uninitialized or empty cache (which often defaults to 0 or is represented as 0), and the registry is temporarily unavailable, the host will return 0. The client will compare the returned 0 with its cached 0, assume they match, and skip the initial cache population, leading to a silent failure.\n\nUsing option<u64> instead of a magic 0 allows the client to explicitly handle the unavailable state (e.g., by retrying or keeping the existing cache) without risking a false match with an uninitialized state.
/// Return a stable hash of the currently-loaded capsule set — the sorted\n /// (capsule-id, package-version) pairs across every registered capsule. The\n /// value MOVES on install / removal / version-bump, is load-order\n /// independent, and is restart-stable (no process state), so a consumer\n /// keyed on the loaded set (e.g. a per-principal tool-schema cache) can\n /// re-validate cheaply on its own next turn. Ungated, read-only\n /// introspection like enumerate-capabilities. Returns none if the\n /// registry is momentarily unavailable.\n capsule-set-epoch: func() -> option<u64>;
There was a problem hiding this comment.
Pull request overview
Adds a new astrid:sys@1.1.0 WIT interface as an additive superset of astrid:sys@1.0.0, introducing a single new read-only introspection call (capsule-set-epoch) while keeping the existing surface intact so guests can bind only the latest sys version.
Changes:
- Introduces
host/sys@1.1.0.witas a superset ofhost/sys@1.0.0.wit. - Adds
capsule-set-epoch: func() -> u64for detecting loaded-capsule-set changes.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /// introspection like enumerate-capabilities. Infallible — returns 0 if the | ||
| /// registry is momentarily unavailable (a value that won't match a | ||
| /// populated cache's stored epoch, biasing toward a safe refresh). |
|
Closing in favour of #1069 (per-principal capsule loading). The capsule-set-epoch primitive assumed a single global loaded capsule set; but principals are on per-principal distributions and versions (loaded per-principal off their own meta.json by content hash). With per-principal loaded sets the tool surface is per-principal by construction — no global epoch, no cross-principal cache — so this primitive is the wrong layer. Superseded; tracked under #1069. |
Adds
astrid:sys@1.1.0as a full additive superset of the frozen@1.0.0— every existing type and function carried verbatim — plus one new read-only introspection call:This lets a capsule detect that the loaded set changed and self-heal a load-derived cache (e.g. a describe-fan-out tool list) on its own next turn, instead of relying on the principal-less
astrid.v1.capsules_loadedbroadcast that only ever reaches the default principal.Superset (not a slim companion) so the host serves both versions while the SDK binds only the latest and still reaches the whole
syssurface — theastrid:http@1.1.0pattern.Consumed by
unicity-astrid/astrid(host impl, issue #1063) andunicity-astrid/sdk-rust(runtime::capsule_set_epoch), in service of theunicity-astrid/astrid#982fix. Merge first; the core and sdk submodule pins point at this branch and re-pin to the merge commit.