docs(compass): design comms file sharing (RIG-2669)

[rigel-mintaka]

Moved

• Moved from docs(agent): design comms file sharing (RIG-2669) compass#2153: design records now live in this repo, under docs/designs/compass/.
• Links to compass records that have not moved point at compass main blob URLs.

Summary

Design record for RIG-2669: file sharing on the comms surface. Agents and the operator can attach a file to a channel, topic or DM message, and anyone who can read that message can read the file. Agents get attach and read tools; the operator downloads from the UI and the CLI.

Record: docs/designs/agent/compass-comms-file-sharing/design.md. Ledger rows: DL-480 to DL-485, all Active (proposed, pending Matt, 2026-10-11).

Decisions (proposed)

	Decision
D1 storage	Bytes go through the existing Server ObjectStore under blobs/<sha256>, as session blobs do (DL-426). A new tenant-RLS comms_attachments table indexes them.
D2 wire	UploadAttachment / GetAttachment RPCs on CommsService; new MessageBlock arm 4. Upload first, then a post binds the attachment to one message. Agent call arms 16 and 17.
D3 read access	A file is readable exactly where its message block was delivered: IsTopicChannelMember, the probe that already gates MessagePosted. The uploader can also read it until it is posted. Every refusal is NotFound.
D4 cap and retention	15 MiB per file (the 16 MiB message limit less 1 MiB). At most 8 unposted uploads per uploader in 24 h. An attachment lives as long as its message; GC is deferred.
D5 agent tools	comms_attach_file and comms_read_file.
D6 operator	UI attachment chip with download (always application/octet-stream); compass message attach / get.
T0	Directory-backed ObjectStore (--object-dir, default <StateDir>/objects) so local stacks have storage (OQ-1).

Open questions for Matt

OQ-1 (load-bearing: a directory-backed object store for local stacks, recommended) is with Matt in RIG-5148. OQ-2 to OQ-4 are deferrals: retention and GC as one follow-up, no UI upload, no files over 15 MiB. The Plan builds each recommendation and lists the delta for the other options.

Review

An adversarial design critic and three review-correctness rounds; every finding is folded in. Review at head 4a65014d: 0 high, 0 medium, 0 low, 0 nit (see the PR comment).

Spec-impact: none
Ledger-impact: DL-480..485 added (proposed)

Refs RIG-2669

Co-authored-by: Matt Wilkinson matt@rigel.build

[linear-code]

RIG-2669

[github-actions]

Rigel public design docs preview: https://compass-comms-rig-2669-file.docs-2ui.pages.dev

Deployed from compass-comms/rig-2669-file-sharing-design at 72437df.

[rigel-mintaka]

Head note at 72437dfd3d1e894e25f51e4f5207597f4463cbe5 (base main b752ded3).

• Rebased onto main with no conflicts. The record is byte-identical to the one reviewed at compass#2153 4a65014d: 0 high, 0 medium, 0 low.
• Local: rumdl, biome, the design-ledger gate and ref-gate are clean. CI check is green.
• OQ-1 (storage on local stacks) is still open for Matt in RIG-5148.