[ac-pplx]

Mechanical move, no functional change. The sandboxes row writes listed below move into pplx-space-sandbox-store with their SQL byte-for-byte; callers keep their locks, transactions and error handling. Everything else is doc comments. Part of the wave-2 stack (5 of 10, on #1339); it lands with the stack.

Summary

The Direct substrate wrote the control-plane sandboxes row from inline SQL in crates/libs/api/src/controllers/substrate/direct.rs. Five of its six statements move into a new direct module of pplx-space-sandbox-store; the adoption update stays in the substrate (below). There is one function per transition, and each runs on the executor its caller passes:

• claim_direct_restore_lease → direct::claim_restore_lease (operation step)
• release_direct_restore_lease → direct::release_restore_lease (operation step)
• renew_direct_restore_lease → direct::renew_restore_lease (operation step)
• complete_direct_restore_lease → direct::complete_restore_lease (operation step)
• persist_owned_restore_route_identity_receipt (placement UPDATE) → direct::place_owned_restore_receipt (observed projection)

The SQL text is the same byte for byte (checked by extracting the literals from both files). The binds carry the same values; SandboxId and NodeId encode as the same UUIDs. These stay in the substrate: the restore-ownership SELECT ... FOR UPDATE, the route-identity writes, the owned-restore transaction and the lease durations. Each function returns whether its guarded write matched, and the substrate maps a miss to the same error as before.

The doc comments note the guards a reader might not expect:

• Renewal and completion check only the token. That is enough because the sandboxes_clear_restore_lease trigger clears the token whenever a row leaves restoring.
• Releasing a retry lease leaves the lease in place.
• The receipt placement has no lifecycle predicate. It relies on the caller's row lock.

sql! locators change: the moved statements now report pplx_space_sandbox_store::direct, which shows in pg_stat_activity and in query monitoring.

pattern_ratchet.sandbox_writes for substrate/direct.rs drops from 6 to 1. The one left is adopt_live_execution's update: its conditions join two Direct-only tables (sandbox_direct_route_identities, sandbox_direct_route_provenance), and moving it into the store would add an exception to the direct_tables rule. Exceptions there are not allowed to grow, so it stays in the substrate until those tables have an owning store. ARCHITECTURE.toml and substrate/AGENTS.md are unchanged.

Validation

• cargo nextest run -p pplx-space-sandbox-store -p pplx-space-api: 1583 of 1584 passed, Postgres-backed tests ran with no dependency skips. The one failure, routes::e2b::tests::detail_reports_authoritative_federated_ownership_not_metadata (a JSON key-order snapshot), fails the same way on unmodified origin/main.
• No test files changed.
• Mutation checks, reverted afterwards:
  • Widening the claim's lifecycle guard to include 'started' fails non_restore_lifecycle_without_a_lease_reports_conflict and restore_lease_claim_and_release_move_only_restore_lifecycles.
• cargo clippy --workspace --locked --all-targets --all-features -- -D warnings: clean. cargo fmt --check: clean.
• cargo arch: 0 required findings (110 advisory, also when run as CI does, against the merge base's architecture-baseline.toml, renames and ARCHITECTURE.toml). The direct_tables no_crossing finding on the store's direct.rs is gone: the same run with the old ARCHITECTURE.toml reports it, at 111 findings. In this PR's files the only finding left is the existing file_size.listed_no_growth on substrate/direct.rs (grew from 3907 to 4424 code lines; its cap was already below the file's size on main).
• Kind, Kubernetes lane (fresh cluster, up.sh 555 s, smoke-kind-typed.sh all 3159 s):
  • ECW pass: 82 passed, 1 failed, 5 inconclusive. Native pass: 35/35.
  • local.gentle_drain_leaves_sandbox_resident failed once and passed on rerun.
  • Two inconclusives were residue from a leftover sandbox and from that drain failure; both passed on rerun.
  • The other three inconclusives are bench conditions: no admin token file or receipt directory (2), and the Datadog telemetry mode (1).
• Kind, Direct lane (fresh cluster with SPACE_KIND_SUBSTRATE=direct, up.sh 122 s, all 1023 s):
  • ECW pass: 51/51, including pause/connect, the pause race, wake-from-idle-suspend and restore scenarios.
  • Native pass: 26 passed, 1 failed. native.stopped_restart_preserves_rootfs failed at its cleanup step, after both stop/start cycles passed. On this branch's base, the fixture's cleanup looked up the sandbox's execution pod, which Direct doesn't create; kind-ci: run the Direct substrate lane nightly and on Direct-path PRs (not required) #1225 on main makes it use the API's node placement on Direct. None of the moved statements is on that step. This PR's Kind Direct CI run, on the merge with main, passed the full typed suite on Direct (ECW 51/51, native 27/27), this scenario included.

Severity and risk

Severity: does not apply (pure move). Risk: the restore and adoption paths of the Direct substrate. Because the statements are unchanged, old and new pods issue the same SQL during a rollout. Rollback: revert the commit.

Open PRs that will need to rebase

• [space] fence every placement writer against the provider-terminate path #559 and [api] record the activating client from Direct's start, wake and restore receipts #1175 edit the body of DirectSubstrate::persist_owned_restore_route_identity_receipt. [space] fence every placement writer against the provider-terminate path #559 adds a fence before the FOR UPDATE; [api] record the activating client from Direct's start, wake and restore receipts #1175 adds record.write after the placement. Both additions stay at the call site, but the placement UPDATE they sit next to is now pplx_space_sandbox_store::direct::place_owned_restore_receipt.
• Enforce template lookup scope after compatible rollout #806 changes the sandbox_writes cap for substrate/direct.rs (5 → 7), and this PR removes that entry.

AI assistance: Claude Code (an AI agent) wrote the code change, ran the validation, and drafted this description.

After the wave-2 restack

This PR is one layer of a 10-PR stack, restacked onto main c5fdf0c7 (which includes #826) and then rebased mechanically onto 42a99002, which changed only baseline context lines, in order #1329 → #1336 → #1338 → #1339 → #1342 → #1347 → #1333 → #1335 → #1328 → #1332. The validation earlier in this description ran at pre-restack heads; this layer's head is 50153846.

• [cluster-controller] re-place an evacuated stopped sandbox as stopped on another node, materialized by the shim without a VM #826: Main's [cluster-controller] re-place an evacuated stopped sandbox as stopped on another node, materialized by the shim without a VM #826 and the commits since the previous restack touched nothing this layer moves, so the commit is unchanged apart from its new base (git range-diff shows =). For every file [cluster-controller] re-place an evacuated stopped sandbox as stopped on another node, materialized by the shim without a VM #826 and this stack share, each SQL line [cluster-controller] re-place an evacuated stopped sandbox as stopped on another node, materialized by the shim without a VM #826 added was checked to be present verbatim at the top head, in place or in the store module it moved to.
• At this head: cargo fmt --all -- --check, cargo check --workspace --all-targets --all-features and cargo arch (0 required findings, with main's layers and table-owner rules), and the ratchet and caps this layer changes are recounted exactly.
• At the top of the stack (e90aa284 before that rebase; nextest passed 4370 tests again at 77fbae1e): cargo clippy --workspace --locked --all-targets --all-features -- -D warnings is clean, and SPACE_CI_REQUIRE_TEST_DEPS=1 cargo nextest run --all-features passed 4355 tests across the store, api, internal-api server, cluster-controller server, metrics, db-test-fixtures, common-core, common-svc and portability crates, [cluster-controller] re-place an evacuated stopped sandbox as stopped on another node, materialized by the shim without a VM #826's suites included.
• Kind at the top of the stack, fresh clusters with the otel telemetry mode and CI's cold-receipt directory: scripts/tests/smoke-kind-typed.sh all gave ECW 91/91 and native 42/42, including [cluster-controller] re-place an evacuated stopped sandbox as stopped on another node, materialized by the shim without a VM #826's native.forced_drain_re_places_stopped_sandbox and its re-drain and restarted variants. The Direct substrate lane's all gave ECW 51/51 and native 27/27. No flakes and no reruns.
• Equivalence: apart from the [cluster-controller] re-place an evacuated stopped sandbox as stopped on another node, materialized by the shim without a VM #826 port named above, the PR's own +/- lines and its SQL string literals match its reviewed head (range-diff plus a literal multiset compare).

[github-actions]

Thanks for opening this pull request! A SPACE maintainer will take a look.

CONTRIBUTING.md explains how we review outside contributions.