SDK: a capsule repository in blocks, like ~/.m2/repository -- by hand now, from Nexus later #149

New Issue

2026-11-07T23:15:59Z

rajames commented

2026-11-07 23:15:59 +00:00

Ruled

Captain Bob, 2026-11-07: "Part of SDK will be to set aside a set of blocks that will act as a .m2/repository. ... for now we can populate it with capsules manually and eventually we'll connect it to this Nexus instance once we do networking, we'll pull capsules from Nexus as needed. Everything we pull in will have a repository TTL like the rest of the system almost by default."

The design (to rule where marked)

Where: on Artemis (the stick's persistent block store), a reserved block range of its own, written into experiments/bare_metal/README.md with the capsule ranges -- not blocks 0-2047 (the VM's fast RAM). Ruling: the range and its size.
Layout: an index -- per entry the coordinates (org.starship.capsules:<name>:<version>), the capsule's XXHash64 (already its ID), its signature, its block extent, when it came, its TTL, a pinned flag -- then content blocks. Content-addressed: identical capsules are stored once.
TTL by default, as acl_ttl is: a pulled capsule expires and is evicted, or re-fetched once there is networking. Ruling: the default TTL.
Pinning one-way, as ACL-PIN is: the system's own capsules never expire. Ruling: which are pinned.
Verified in and on use: the hash and the StarshipOS signature (FABRIC-3 XLVI); the CONTRIB tier already demands a good signature on real hardware (#139).
Releases immutable, snapshots expire -- Maven's distinction, which Nexus already enforces.
Composed in FORTH first: REPO-FIND, REPO-INSTALL, REPO-LIST, REPO-EVICT from the block words that exist; C only for raw block I/O or hashing.

Now and later

Now: populated by hand -- a host tool (mkcapsule or a sibling) writes signed entries into an Artemis image or onto the stick.
Later (networking): resolve locally, then from Nexus (starshipos-releases, a capsules group: the nightly's Maven deploy can already publish them), insert with a TTL, verify before use. Then the latency experiment (the next issue).

Done when

Ruled: the range, the size, the TTL, the pinned set
The repository words, and the host tool; a capsule installed by hand, found, used, expired and evicted -- on all three architectures

🤖 Filed with Claude Code

### Ruled Captain Bob, 2026-11-07: "Part of SDK will be to set aside a set of blocks that will act as a .m2/repository. ... for now we can populate it with capsules manually and eventually we'll connect it to this Nexus instance once we do networking, we'll pull capsules from Nexus as needed. Everything we pull in will have a repository TTL like the rest of the system almost by default." ### The design (to rule where marked) - **Where:** on **Artemis** (the stick's persistent block store), a reserved block range of its own, written into `experiments/bare_metal/README.md` with the capsule ranges -- not blocks 0-2047 (the VM's fast RAM). *Ruling: the range and its size.* - **Layout:** an index -- per entry the coordinates (`org.starship.capsules:<name>:<version>`), the capsule's XXHash64 (already its ID), its signature, its block extent, when it came, its TTL, a pinned flag -- then content blocks. Content-addressed: identical capsules are stored once. - **TTL by default**, as `acl_ttl` is: a pulled capsule expires and is evicted, or re-fetched once there is networking. *Ruling: the default TTL.* - **Pinning one-way**, as `ACL-PIN` is: the system's own capsules never expire. *Ruling: which are pinned.* - **Verified in and on use:** the hash and the StarshipOS signature (FABRIC-3 XLVI); the CONTRIB tier already demands a good signature on real hardware (#139). - **Releases immutable, snapshots expire** -- Maven's distinction, which Nexus already enforces. - **Composed in FORTH first:** `REPO-FIND`, `REPO-INSTALL`, `REPO-LIST`, `REPO-EVICT` from the block words that exist; C only for raw block I/O or hashing. ### Now and later - **Now:** populated by hand -- a host tool (`mkcapsule` or a sibling) writes signed entries into an Artemis image or onto the stick. - **Later (networking):** resolve locally, then from Nexus (`starshipos-releases`, a `capsules` group: the nightly's Maven deploy can already publish them), insert with a TTL, verify before use. Then the latency experiment (the next issue). ### Done when - [ ] Ruled: the range, the size, the TTL, the pinned set - [ ] The repository words, and the host tool; a capsule installed by hand, found, used, expired and evicted -- on all three architectures 🤖 Filed with [Claude Code](https://claude.com/claude-code)

rajames added this to the v4.0.0-alpha.5: SDK milestone 2026-11-07 23:15:59 +00:00

rajames added the

area/capsules labels 2026-11-07 23:16:00 +00:00

rajames referenced this issue

2026-11-07 23:16:17 +00:00

DoE: K under network latency -- the capsule repository pulling from Nexus, latency dialled in #150