[Enrique Saurez (esaurez)]

Part of #847 (PR 1 of 2: template operations).

Stacked on #958.

Chain: #951 → #954 → #957 → #959 → #960 → #955 → #958 → this PR → #963, on dev; #879, #881, #885, #886, #877, #932, #884, #887, #933, #880, #936, #937, #939, #940, #941, #888, #949, and #950 have merged.

What and why

The runtime adapter's host program creates templates with create, but nothing refreshes, examines, or empties the template store that create fills. This PR adds refresh, list, inspect, and remove, as the operations table of #847 asks, through the public API of nvx::host::template alone.

• refresh captures a new generation of the class even when the store already serves one. As create does, it prints the key and the generation only once the store committed them, and no restore triggers either command.
• list and inspect report each generation from the store's index, its tombstones, and the records of its leases alone: its store generation, the identities of its compatibility key and of its capture class, its state, available or tombstoned, whether a clone may restore it at the host's time and why, and its leases. inspect adds each lease's sandbox and launch, and the metadata of the capture. They read no payload, neither the snapshot nor the key, whose decoding checks a digest, so they load no VM state and hash nothing.
• remove retires the generation that it names with NVX's Store::retire, which tombstones it first, so that no new lease takes it, and deletes it once no lease remains. While leases keep it, the command exits with status 7, busy, and lists them. It never moves or deletes a leased generation.

Where the store lives, and what it evicts

The store is the directory that each template command names, private to the current user and apart from every sandbox's store. create and refresh create it if needed, while list, inspect, and remove only open it.

Of each capture class, the adapter keeps the generation that it served last. Once create or refresh served a generation, generations::evict retires every other generation of the class that the store published before it, and any that a tombstone quarantines. A generation that leases keep stays tombstoned, with its payload, until a later retirement finds its leases gone. An eviction that fails only warns, since the store already committed what the command served, and the next create or refresh of the class retries it.

Tests

• template_operations, without a hypervisor: the command lines that the host program refuses, the operations on a directory that holds no template store, and a store without generations.
• vm_template, in VMs: a refresh that captures and retires the generations that it supersedes while a clone leases one of them, and a removal that reports busy while leases keep its generation, then deletes it once they end.

Not in this PR

• Starting and running clones of a template, and the stage's consolidated suite: PR 2.

Validation

At this PR's head 43879d7, the same commit as the earlier head 32942c3, restacked onto #958's head e19ceed: its tree, 6da8527f, is the merge of 32942c3 into dev at fbeb563, which holds #951, #954 and #957, plus #955's fix that treats a path whose links loop as a changed object. That merge, without the fix, passed the documentation gates of nvx-rs and of the test adapter, Clippy, validate-nvx on Linux and on Windows, and the Markdown link check; the fix has its own tests in #955. The rest of this section describes 32942c3, on #958's earlier head e9e7fc6.

Pending at 32942c3.

[Copilot]

🟡 Changes recommended

Retirement cleanup skips unindexed tombstones left by interrupted retirement, allowing them to persist indefinitely instead of being retried during later evictions.

1 open issue

• Retry cleanup for unindexed tombstones after interrupted retirement · New

What changed in this PR

Adds template-generation management to the runtime adapter through NVX’s public template-store API, implementing the template operations portion of #847.

Changes:

• Adds refresh, list, inspect, and lease-aware remove commands.
• Adds eviction of superseded generations and metadata-only listings without reading payloads or hashing.
• Documents the operations and adds command-line and VM-backed lifecycle tests.

File	Description
tests/​runtime-adapter/​tests/​vm_template.rs	Tests refresh, eviction, listings, and removal with retained leases.
tests/​runtime-adapter/​tests/​template_operations.rs	Tests argument validation, missing stores, and empty stores without a hypervisor.
tests/​runtime-adapter/​tests/​common/​mod.rs	Adds a shared refresh-command helper.
tests/​runtime-adapter/​src/​lib.rs	Exposes and documents the host-only generations module.
tests/​runtime-adapter/​src/​generations.rs	Implements generation descriptions and eviction policy.
tests/​runtime-adapter/​src/​bin/​runtime-adapter-host.rs	Adds command parsing, dispatch, output, and busy status handling.
tests/​runtime-adapter/​README.md	Documents store behavior, commands, output, and test scenarios.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are reported for the template-generation management changes.

No open issues 🎉

1 resolved since last review

• Retry cleanup for unindexed tombstones after interrupted retirement

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Listing generations repeatedly scans and reads all leases, causing G × L record reads instead of reading each lease once through a bulk API.

1 open issue

• Avoid repeated full lease scans when listing generations · New

_{Review effort: Balanced}