docs(runtime): P2 persistent-session-volume + VirtualFS seam detailing record (RIG-2395) - #873
Open
rigel-mintaka wants to merge 4 commits into
Open
docs(runtime): P2 persistent-session-volume + VirtualFS seam detailing record (RIG-2395)#873rigel-mintaka wants to merge 4 commits into
rigel-mintaka wants to merge 4 commits into
Conversation
…g record (RIG-2395) Detailing pass for task **P2** of the [compass-elastic-session-runtime](docs/designs/infra/runtime/compass-elastic-session-runtime/design.md) parent (RIG-1717, frozen PR #446), incorporating the [VirtualFS descope amendment](docs/designs/infra/runtime/compass-elastic-session-runtime/virtualfs-descope-amendment.md) (RIG-2395, PR #459) that moved the `VirtualFS` source-of-tree seam, the `WorkspaceSource` variant, and the provision-materialize wiring from S1 into P2 and deferred the clone-model / clone-credential-location decision to this record. ### What it designs - A **per-session persistent volume** (working tree + derived state — `target/`, `node_modules`, caches) that survives suspend/resume/eviction and mounts at a stable absolute in-container path on every launch. Local-directory subtree with session→box stickiness, box-loss-as-accepted-degradation, and a 14-day-after-close expiry reaper. - The **`VirtualFS` source-of-tree seam** (`go/internal/vfs`, created fresh — the S1 draft was closed by the descope), mirroring the shipped `go/internal/compute` layering: `Materialize`/`Release`, a `TreeSource` selecting checkout | sparse | snapshot | customer-mount, destination-as-binding-state, and reserved-not-implemented `Archive`/`Restore` on the sentinel discipline. - A **six-task plan** (W1–W6): volume lifecycle API + local-dir backend → snapshot backends (reflink + rsync) with a repo→snapshot index → the `VirtualFS` seam → the `WorkspaceSource` variant + mount doc-amendment → provision/teardown wiring → expiry reaper + the parent-mandated acceptance suite. ### The load-bearing decision (OQ-1) The one load-bearing open question — **who clones, and where the clone-read credential lives** — is presented for ratification as a single package: **1a** the clone posture (recommended **A**, keep the agent self-clone, zero new credential class; vs B host-side clone, vs C host-side mirror) and **1b** the snapshot-amortization provenance mechanism under A (recommended: snapshot only a provably-clean post-clone tree via a clone-complete signal, keyed in a repo→snapshot index). The record is drafted against A + provenance-(a); Matt ratifies the package. This draft was red-teamed by an adversarial design-critic pass before review (per `skill://design`): one genuine fork (the 1b provenance mechanism) folded into OQ-1's ruling package, four clear improvements folded into the record (Option C alternative, close-stamp race/crash/suspend hardening, seam post-condition + path-triple ownership, determinate W6 probes + snapshot-store retention). Spec-impact: none Ledger-impact: none Refs RIG-2395 Co-authored-by: Matt Wilkinson <matt@rigel.build>
|
🚫 This pull request was removed from the merge queue because it was canceled by Matt Wilkinson (a GitHub user). See more details here.
After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here |
|
Compass engineering docs preview: https://compass-runner-rig-2395-p2-p.compass-eng-docs.pages.dev Deployed from Changed pages: |
mattwilkinsonn
approved these changes
Sep 4, 2026
Round-1 review of the P2 persistent-session-volume record (2 high, 7 medium, 3 low; ~45 citations verified exact at main 17111cc). All 12 are clone-improvement folds — no new design fork; OQ-1 remains the only fork, with Matt. - HIGH: own the clone-complete signal (agent→Runner control message + Runner-side clean-tree verify + Snapshot call + index write) as an explicit W5 sub-unit, gated on OQ-1b — it was the only caller of the Snapshot verb and was unowned. - HIGH: scope the snapshot index to (AgentAccountID, repo), not repo alone, on a hosted multi-tenant platform (new P2-GC-f; agent.go:52-56 DL-167). - MED: gate W2's snapshot-store/index leg on OQ-1 and split out the ungated cloner volume-copy primitive; add W1 Lookup so resolve-or-create is expressible; name the Server session registry as the crash-reconciliation source (host.go:77 in-memory map is not authoritative); wire Release into W5 teardown + the parent's release round-trip; narrow P2-GC-b to the drafted-against posture; correct the suspend-intent citation to design.md:708-709 (Suspend), not :714-716 (Archive); state the keep-id uid ownership invariant for the volume root (podman.go:466-471, agent.go:356-357). - LOW: cite the rw agent-gateway-socket mount precedent (podman.go:100-103); add the OQ-N vs parent-OQ-N namespace note; name W5's own merge-time assertions. Refs RIG-2395 Co-authored-by: Matt Wilkinson <matt@rigel.build>
…s (RIG-2395) Round-2 review of the P2 persistent-session-volume record (2 high, 5 medium, 2 low). All 8 fold-added source citations verified line-exact at main 17111cc; 10 of 12 round-1 folds landed clean. The 9 findings are defects the round-1 fold itself introduced — no new design fork; OQ-1 remains the only fork, with Matt. - HIGH: restore the close-stamp invariant (c) a splice destroyed — all three W1 invariants (Attach-clears / per-volume-lock / close-vs-suspend intent) are labelled again. - HIGH: the clone-complete signal named `Control`, which is Runner→agent only (agent_gateway.proto:74-77). Re-spec it as a new agent→Runner unary RPC on the PostConversationFrame delivered-or-erred precedent (agent_gateway.proto: 68-73) — a dropped once-per-clone trigger must be an agent-retried error, not a silent warm-path loss on the loss-tolerable Publish spine; name the verify side (host-side git-status under the keep-id invariant). - MED: propagate the fold into the `## Tasks` checklist (add Lookup to W1; W5 deps W1,W2,W3,W4 + clone-complete sub-unit; account-scoped W2 index + its OQ-1 gate marker) — it still encoded the pre-fold API, DAG edge, and the un-account-scoped index HIGH-2 existed to fix. - MED: name the crash-reconciliation source concretely — hold unstamped volumes until the Server pushes the session set over the `Sessions` stream (runner.proto:61-70); RunnerService has no Runner→Server pull verb. - MED: reorder W5 teardown to container→release→stamp (the real reverse + W1's crash model), not release-while-mounted. - MED: make the descope-survivor list exhaustive over W1–W6 (add W3 minus its snapshot backend; state Snapshot joins Archive/Restore reserved-not- implemented when its sole caller drops). - LOW: route the Stickiness bullet through `Lookup` not `Attach`; two remaining repo→index namings → `(account, repo)`. Refs RIG-2395 Co-authored-by: Matt Wilkinson <matt@rigel.build>
…oncile (RIG-2395) Round-3 review (K=3, final) of the P2 persistent-session-volume record: 1 high, 1 medium, both verified at main 17111cc. Seven of the nine round-2 folds landed clean; two did not — both are round-2 fold-introduced defects, no new design fork (OQ-1 remains the only fork, with Matt). - HIGH: the round-2 crash-reconciliation re-spec was unbuildable. It waited for the Server to push a session SET over `Sessions`, but `SessionsResponse.command` is an exhaustive oneof with no session-set variant (runner.proto:233-284), and its premise ("Server's authoritative session set") inverts the real authority direction — the Runner is authoritative for live session truth (host.go:3-7, dispatch.go:10-11), and `Hub.enroll` clears the Server's bindings at every enroll (hub.go:933-935), so the map is empty exactly when a restart would read it. It failed OPEN: an unstamped orphan held forever = the unbounded leak the 14-day policy exists to bound. Re-spec Runner-local: stamp every unstamped volume closed AT DISCOVERY (deadline from discovery), invariant (a) clears it on a re-provisioning Attach. No Server query — fails safe, never open, never wrong. W1 test cycle retargeted (discovery-stamp + Attach-clears, no fake session set). - MED: W6's OQ-1 gate status contradicted itself across three sections — the round-2 fold's added sentence gated all of W6, but the Plan enumeration and the descope list gate only probe 3. Reconciled to gate W6's snapshot-materialized probe (probe 3) alone in all four places (Plan :395-400, W5 test :641, Tasks W6 line, consistent with descope :406). Review K=3 is exhausted; this fold is not itself review-verified. Surfaced to Matt on RIG-2395. Refs RIG-2395 Co-authored-by: Matt Wilkinson <matt@rigel.build>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Detailing pass for task P2 of the compass-elastic-session-runtime parent (RIG-1717, frozen PR #446), incorporating the VirtualFS descope amendment (RIG-2395, PR #459) that moved the
VirtualFSsource-of-tree seam, theWorkspaceSourcevariant, and the provision-materialize wiring from S1 into P2 and deferred the clone-model / clone-credential-location decision to this record.What it designs
target/,node_modules, caches) that survives suspend/resume/eviction and mounts at a stable absolute in-container path on every launch. Local-directory subtree with session→box stickiness, box-loss-as-accepted-degradation, and a 14-day-after-close expiry reaper.VirtualFSsource-of-tree seam (go/internal/vfs, created fresh — the S1 draft was closed by the descope), mirroring the shippedgo/internal/computelayering:Materialize/Release, aTreeSourceselecting checkout | sparse | snapshot | customer-mount, destination-as-binding-state, and reserved-not-implementedArchive/Restoreon the sentinel discipline.VirtualFSseam → theWorkspaceSourcevariant + mount doc-amendment → provision/teardown wiring → expiry reaper + the parent-mandated acceptance suite.The load-bearing decision (OQ-1)
The one load-bearing open question — who clones, and where the clone-read credential lives — is presented for ratification as a single package: 1a the clone posture (recommended A, keep the agent self-clone, zero new credential class; vs B host-side clone, vs C host-side mirror) and 1b the snapshot-amortization provenance mechanism under A (recommended: snapshot only a provably-clean post-clone tree via a clone-complete signal, keyed in a repo→snapshot index). The record is drafted against A + provenance-(a); Matt ratifies the package.
This draft was red-teamed by an adversarial design-critic pass before review (per
skill://design): one genuine fork (the 1b provenance mechanism) folded into OQ-1's ruling package, four clear improvements folded into the record (Option C alternative, close-stamp race/crash/suspend hardening, seam post-condition + path-triple ownership, determinate W6 probes + snapshot-store retention).Spec-impact: none
Ledger-impact: none
Refs RIG-2395
Co-authored-by: Matt Wilkinson matt@rigel.build