Skip to content

feat(relay): atomically consume sandbox attachment approvals - #169

Draft
tee8z wants to merge 3 commits into
tee8z/sandbox-snapshot-archivefrom
tee8z/sandbox-attach-claims
Draft

tee8z wants to merge 3 commits into
tee8z/sandbox-snapshot-archivefrom
tee8z/sandbox-attach-claims

Conversation

@tee8z

@tee8z tee8z commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator

Two overlapping harnesses must never open work from the same owner approval. This layer atomically consumes terminal and snapshot acceptance coordinates under the existing addressable-event lock and retains a watermark in the same transaction. No schema migration is required.

The relay verifies canonical, unambiguous coordinates; the typed owner-signed approval; immutable channel/thread/agent/requester; recorded agent ownership; a unique signed claim nonce; zero initial byte counters; and absence of expiration. Terminal audit builders now generate a distinct nonce per attempt, matching the snapshot builder. Consumers retain the exact signed event for retries.

Receipt Meaning
Accepted, matching event ID, sandbox-attach: first-claim-v1 This transaction inserted the first claim.
Duplicate, generic success, mismatch, rejection, or timeout Refuse to start; obtain a new owner approval.

The server consumer must require the first-claim receipt. This prevents an older relay's ordinary replacement success from silently authorizing work. Exact-ID retries never receive that receipt, including a lost-ack retry.

NIP-09 event/address deletion and NIP-29 deletion preserve acceptance records. Ordinary pending requests and owner approvals remain revocable. Removing an audit body through trusted retention leaves its replay watermark; normal community deletion still purges the existing tenant-scoped table. The retention contract describes the trusted operator boundary. Stored records contain approval metadata and counters only.

Validation:

  • Full unit suites: core 290, SDK 358, DB 192 passed (674 infrastructure cases ignored), relay 1,673 passed (625 infrastructure cases ignored).
  • Two actual-ingest PostgreSQL tests pass for both terminal and snapshot modes: concurrent writers, exact replay, NIP-09/NIP-29 deletion, audit-body purge, ordinary revocation, and malformed/unowned signers.
  • Four production guard mutations fail the intended assertions: no-head transaction guard, retained watermark, no-expiration requirement, and recorded agent ownership. Restored PostgreSQL regressions pass again.
  • All-target core/SDK/DB/relay Clippy with warnings denied, repository formatting, PostgreSQL discovery convention, differential file-size checks, and diff checks pass.

The production-ingest command and expected result are in the linked retention document. Full repository CI remains outside this focused local result; the parent task's broad local gate is blocked by missing native Tauri GLib libraries. This PR remains a draft pending independent review, combined runtime evidence, and explicit human testing. No deployment is included.

Stack: gateway #154 → terminal SDK #159 → CLI #163 → worker #166 → snapshot wire #167 → snapshot producer #168 → this atomic claim layer → ACP terminal server. The terminal server follows separately. Two tiny, signed owning-layer fixes are carried additively because the published intermediate bases are preserved: the CLI Unix-only clock import and the relay unit fixture's cached gateway denial. This layer adds 707 changed lines; those carried fixes add 15.

The Rust claim diff is byte-identical after the signed rebase onto published producer #168 at 6504ed331. That producer has a separately tracked draft resource-accounting blocker; terminal claims do not invoke its archive helper. Its additive fix must be carried into the unpublished server before publication.

Signed-off-by: Tee8z <tee8z@protonmail.com>
(cherry picked from commit 3b9756a)
Signed-off-by: Tee8z <tee8z@protonmail.com>
Signed-off-by: Tee8z <tee8z@protonmail.com>
(cherry picked from commit 2af27c5)
Signed-off-by: Tee8z <tee8z@protonmail.com>
Signed-off-by: Tee8z <tee8z@protonmail.com>
@tee8z tee8z self-assigned this Nov 10, 2026
@coderabbitai

coderabbitai Bot commented Nov 10, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@tee8z
tee8z added this pull request to stack #160 November 10, 2026 21:33
@tee8z

tee8z commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator Author

Independent agent review of 1c6ee69d8: no concrete blockers found. Minimalism 9/10, elegance 9/10, correctness 9/10. I verified that the reviewed Rust files are byte-identical to 07cb1e385 after the stack-base change.

The database takes the existing community/kind/author/coordinate lock before reading either the live head or retained watermark. A first acceptance and its watermark commit together; later attempts and exact retries cannot receive the first-claim marker. The marker is assigned only after an actual insert, so an older relay's generic success is insufficient for the upcoming consumer to start work.

I traced canonical coordinate and tag validation, typed terminal/snapshot owner approvals, immutable scope and requester, current recorded agent ownership, zero initial counters, nonce bounds, and the no-expiration rule. Acceptance protection is limited to per-event NIP-09/NIP-29 deletion paths; requests and approvals remain revocable, and whole-entity erasure paths are not given a new exception. Removing an accepted event body leaves the separate replay watermark. End records retain their existing semantics, including publication after grant expiry.

The two PostgreSQL journeys bind production ingest and cover concurrent writers, duplicate receipts, narrow deletion protection, ordinary revocation, metadata-body removal, and invalid/unowned claims. I inspected the restored two-test pass log and all four guard-mutation failures; each fails the intended assertion. The compiled test artifact was removed during disk recovery, so I did not independently rerun those tests or rebuild solely to replace that artifact.

The combined real-relay consumer journey and explicit human testing remain pending. This comment is review evidence; the PR remains draft.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant