docs(product): design record — @compass system-sender + root-supervisor first turn (SEA-1820 case-1) - #297
Open
seal-agent wants to merge 1 commit into
Open
Conversation
…or first turn (SEA-1820 case-1)
## What
Design record for **SEA-1820 case-1**: the `@compass` system-sender representation and the root-supervisor first-turn Setup-thread flow. The merged first-turn-delivery record froze the *mechanism* (`@compass` = the system-sender alias) and scoped these two things out to this follow-up; this record decides exactly them.
Pure design — no code. `docs/designs/product/compass-system-sender-first-turn/design.md`.
## Decisions
- **(A) `@compass` representation** — a real reserved `accounts` row (handle `compass`, display `Compass`) with a `user_accounts` subtype, seeded at startup via an idempotent `EnsureSystemAccount` beside `BootstrapAdmin`. The sentinel-author option is foreclosed at the schema (`messages.author_account_id NOT NULL REFERENCES accounts(id)`). Never-a-deliver-recipient is **structural**: no `agent_accounts` row ⇒ absent from the agent-only delivery JOIN; pinned by guard tests. Reserved-handle guard (positive grammar + the server's reserved-mention names) + an `IssueToken` refusal make it un-registrable and un-authenticatable.
- **(B) Setup-thread flow** — `postSetupThread` fired from `seedRootSupervisor` on both up-arms, idempotent via a supervisor-scoped `client_request_id`, posted as `@compass` into the supervisor's home channel from a `go:embed`'d `setup_thread.md`, riding the built deliver lane.
Plan is T1–T6 (T1–T4 server lane, T5 compass-ui, T6 driver ledger).
## Review posture
This draft has already survived one adversarial red-team pass (a `design-critic` pass per `skill://design`); its findings are folded — the highlight is **Global Constraint 7 / OQ-6**: the Setup delivery is gated on the parent record's fresh-start barrier-lift (parent task T-R3), which is unbuilt on main (no production sender of `AgentControl{replay_complete}`; agent barrier defaults closed). Captured as a load-bearing sequencing Open Question for the freeze gate.
**Open Questions carried to the freeze gate** (batched to Matt separately): OQ-1 (ledger reconciliation — the parent record's four first-turn DL rows never landed; renumber+map, don't edit frozen prose), OQ-2 (reserved-row subtype), OQ-6 (T-R3 land-order fork). OQ-3 folded into T1; OQ-4/OQ-5/OQ-7 are explicit non-load-bearing deferrals.
## CI note
Base is `main@origin` which currently carries a **pre-existing shared markdownlint red** — 17 MD010 hard-tab errors in `docs/designs/platform/compass-runner-gateway-error-sentinels/design.md`, **not this PR's file** (this record lints clean). That red is fixed by #289 and lifts for every compass PR when #289 merges. It is not a failure of this diff.
Spec-impact: none (product design record; no proto/spec surface changed).
Ledger-impact: none in this PR — the ledger rows (T6) are gated on OQ-1's reconciliation and land in a follow-up per the record; this PR adds a design record only and declares no `DECISIONS.md` delta yet.
Refs SEA-1820.
Co-authored-by: Matt Wilkinson <matt@sealedsecurity.com>
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
1 participant
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.
What
Design record for SEA-1820 case-1: the
@compasssystem-sender representation and the root-supervisor first-turn Setup-thread flow. The merged first-turn-delivery record froze the mechanism (@compass= the system-sender alias) and scoped these two things out to this follow-up; this record decides exactly them.Pure design — no code.
docs/designs/product/compass-system-sender-first-turn/design.md.Decisions
@compassrepresentation — a real reservedaccountsrow (handlecompass, displayCompass) with auser_accountssubtype, seeded at startup via an idempotentEnsureSystemAccountbesideBootstrapAdmin. The sentinel-author option is foreclosed at the schema (messages.author_account_id NOT NULL REFERENCES accounts(id)). Never-a-deliver-recipient is structural: noagent_accountsrow ⇒ absent from the agent-only delivery JOIN; pinned by guard tests. Reserved-handle guard (positive grammar + the server's reserved-mention names) + anIssueTokenrefusal make it un-registrable and un-authenticatable.postSetupThreadfired fromseedRootSupervisoron both up-arms, idempotent via a supervisor-scopedclient_request_id, posted as@compassinto the supervisor's home channel from ago:embed'dsetup_thread.md, riding the built deliver lane.Plan is T1–T6 (T1–T4 server lane, T5 compass-ui, T6 driver ledger).
Review posture
This draft has already survived one adversarial red-team pass (a
design-criticpass perskill://design); its findings are folded — the highlight is Global Constraint 7 / OQ-6: the Setup delivery is gated on the parent record's fresh-start barrier-lift (parent task T-R3), which is unbuilt on main (no production sender ofAgentControl{replay_complete}; agent barrier defaults closed). Captured as a load-bearing sequencing Open Question for the freeze gate.Open Questions carried to the freeze gate (batched to Matt separately): OQ-1 (ledger reconciliation — the parent record's four first-turn DL rows never landed; renumber+map, don't edit frozen prose), OQ-2 (reserved-row subtype), OQ-6 (T-R3 land-order fork). OQ-3 folded into T1; OQ-4/OQ-5/OQ-7 are explicit non-load-bearing deferrals.
CI note
Base is
main@originwhich currently carries a pre-existing shared markdownlint red — 17 MD010 hard-tab errors indocs/designs/platform/compass-runner-gateway-error-sentinels/design.md, not this PR's file (this record lints clean). That red is fixed by #289 and lifts for every compass PR when #289 merges. It is not a failure of this diff.Spec-impact: none (product design record; no proto/spec surface changed).
Ledger-impact: none in this PR — the ledger rows (T6) are gated on OQ-1's reconciliation and land in a follow-up per the record; this PR adds a design record only and declares no
DECISIONS.mddelta yet.Refs SEA-1820.
Co-authored-by: Matt Wilkinson matt@sealedsecurity.com