Move circle definitions into the Circle table

[toddmitchell]

Groundwork for Cat 3 (the enrollment model). Stacked on review-stamp-cat1 (#1649) — retarget to main once that lands. Independent of Cat 2 (#1655).

Why this has to happen first

Circle.AppId, GrantOn, Designation and Emoji shipped dormant with the drive-addressing schema work. Nothing was ever wired to them — in fact grep for TableCircle across src/services and src/apps returns nothing. The table has no callers at all.

Circle definitions actually live in CircleDefinitionService's ThreeKeyValueStorage blob, which is exactly what part 1 warned about:

Bury AppId in that blob and: delete app ⇒ delete its circles becomes load-all-deserialize-filter-delete… and no constraint or FK can ever reference it.

The enrollment pipeline is specified as a table query (part 2, L188-194):

The server queries the Circle table — WHERE GrantOn = Connect (this query is why GrantOn is an indexed column)… The stored registration JSON is not read here; rows are the truth.

You can't run that against a blob store. So the definitions have to move before any of Cat 3 can be built.

What changed

CircleDefinition gains AppId, GrantOn, Designation, Emoji. They're columns, and a second copy inside the row's data blob would let a query on the column disagree with the hydrated object — the same promote-don't-duplicate rule Cat 1 applied to ReviewedAt.

They are not [JsonIgnore], and the second commit explains why: this same type is the wire shape. CircleDefinitionControllerBase serves it directly and takes one as an update body, so hiding the fields from JSON would starve clients and make every client-side circle update arrive with GrantOn defaulted — silently resetting it. Data loss on an ordinary edit.

One attribute can't make one type be both the wire shape and the stored shape, so the blob copy is cleared inside ToRecord instead, the same trick ToConnectionsRecord uses for the grant collections. AppId is also no longer taken from an update request: ownership is set at creation and must not be reassignable by anyone who can PUT a definition.

Equality and GetHashCode account for all four, because EnsureSystemCirclesExistAsync reconciles definitions by comparing them — miss that and system circles silently stop reconciling.

RedactedCircleDefinition exposes the same four. Part 4 renders circles by designation and emoji.

New enums CircleGrantOn (None | Connect | OwnFlowConnect | Review) and CircleDesignation (Personal | Audience | Vendor), matching the column values.

Table layer — TableCircle grows UpsertAsync and GetAllAsync; TableCircleCached wraps both and invalidates the new all-key alongside the per-circle key.

CircleDefinitionService moves off ThreeKeyValueStorage onto db.CircleCached, with ToRecord/FromRecord doing the column-vs-blob split.

v13 → v14 copies existing definitions across. Idempotent and additive — a definition already in the table is skipped rather than overwritten, so a partial run repeats safely. The blob rows are deliberately left in place: if this goes wrong the source data is still sitting there. Cleaning them up is a separate job.

Behaviour

None. All four fields take their defaults for every existing circle (AppId null, GrantOn None, Designation Personal, Emoji null), which is what they already were.

What's not here

The other part-1 leftover: AppRegistrations exists as a table but AppRegistrationService still writes to the KeyThreeValue blob. Nothing in the circle work needs it until DefaultCircles lands in the next PR, so it's cleaner as its own change than bulking this one out.

Testing

Full solution suite green: 2,524 passed, 0 failed (68 skipped, all pre-existing [Explicit]).

Not verified: the v13→v14 migration has not been run against a live PostgreSQL or SQLite tenant holding real blob-stored definitions. Given this moves where every circle definition lives, that's the check I'd want before it leaves draft.

🤖 Generated with Claude Code

[toddmitchell]

Superseded by #1688, which replays this onto main (migration renumbered to v12->v13, folded together with the app-registrations move). Branch deleted; every commit on it is reachable from integration-connection-defaults.