cgalo5758
235ee3c438
CallbackHandler (gocognit 30) held the whole resolution of who a
verified sign-in is: the subject lookup, the first sign-in, and the
returning sign-in with its login stamp, person resync, and organization
and workspace binding. That code moves to internal/provisioning/signin.go
as ResolveSignIn, firstSignIn, returningSignIn, resyncPerson and
sessionWorkspace, and returns a SignedIn (user, person, organization
and workspace ids). The handler calls it once and answers a failure
with "Sign-in failed", 500. Measured scores (golangci-lint's gocognit):
CallbackHandler 11 (was 30), ResolveSignIn 1, firstSignIn 1,
returningSignIn 3, resyncPerson 4, sessionWorkspace 4.
The resolution's log lines move with it onto logging.FromContext(ctx),
the logger the handler used, with the same text, level, attributes and
order. A failure is logged where it happens and returns the unexported
sentinel errSignIn ("sign-in could not be resolved"), which no caller
prints: the handler renders the failure page. provisioning gains one
import, internal/logging.
The handler's second parse of the ID token for the nonce claim, its log
line ("could not parse the ID token's nonce claim") and the struct tag
json:"nonce" are deleted. The comparison reads idToken.Nonce, which
the verification has already read from the same verified payload as a
string; decoding that payload into a struct of one string field cannot
fail, so no input reached the removed failure branch.
The session-binding order (first organization, first workspace, each by
name) is unchanged and now sits in sessionWorkspace alone. The two READMEs
and the model document describe the resolution where it now lives.
TestReturningLoginWritesNoDesiredStateNotice calls ResolveSignIn with
changed claims in place of its copy of the callback's two writes. Its
assertion that a returning login writes no outbox notice for the person,
organization or pool is WIDER: the writes are now ResolveSignIn's own,
the same UpdateUserLogin and UpdatePerson plus its reads, instead of a
copy. Because ResolveSignIn only logs a failed stamp or resync, the test
reads back last_login_ip, display_name and primary_email, which keeps the
two checks that the old test made by failing on a write error (same).
How no output changed:
- go test over ./internal/auth ./internal/provisioning ./internal/server,
run at the parent and here after resetting the test databases, gives
1676 test and subtest names with identical results, none failing. The
sign-in callback goldens and exact log lists are unchanged.
- Literals of internal/auth/auth.go and internal/provisioning's
provisioning.go, workspace.go and (here) signin.go, summed per file:
the log message "could not parse the ID token's nonce claim" and the
tag `json:"nonce"` are gone, "sign-in could not be resolved" is added,
the other messages are present once each as before, and fmt.Errorf
formats are 21 at both. Repeat counts of "error", "email", "person_id",
"org_id" and import paths change where lines moved.
- 44 breaks (68 records, 48 of them one-side) are CAUGHT by the old tests
at the parent and by the same tests here.
- The operator walkthroughs (./test/e2e/operator-walkthroughs) run on the
demo state at the parent and here: the same names, results and skip
messages, 16 passing and 6 skipping.
Unprobed, with the reason:
- Deleting the handler's SetDeadline line is an equivalent edit: the
session manager's RenewToken, called just before it, sets the same
deadline, so no break can fail on it. The tests pin the full lifetime
itself.
- The error half of the organization and workspace guards (err != nil
beside the empty-list test): neither the generated queries nor the
test fakes return rows together with an error, so dropping it changes
no row.
- A first sign-in that succeeds is exercised only against the database.
- RenewToken failing in a real store: only the test wrapper makes it fail.
- A given_name or family_name of another JSON type, which also refuses
the sign-in: pinned for email_verified only.
- Two first sign-ins of one subject at once: no test runs two callbacks
concurrently.
- That a returning login writes no outbox row is not probed by a
one-line edit of signin.go, because the triggers that write those rows
watch other tables.
- Which attributes each log line carries, and the session's name and
username keys, beyond the ones the breaks probe: the golden holds
them all.
- The failure page's texts: the rows share two refusal values, whose
texts the existing failure-page tests pin.
title, audience, summary
| title | audience | summary | |
|---|---|---|---|
| Domain Model Cards |
|
One card per domain model: purpose, invariants, dimensions, drift traps, and open questions, each claim cited to the migration, file, or decision that enforces it. |
Domain Model Cards
Each card in this directory describes one domain model as it is actually built, so a maintainer can modify that model without re-deriving its rules from migrations, specs, and decision documents. The cards are the descriptive home for the as-built models; the normative record — the designed schema, the decision log, the numbered design documents, and the glossary — lives in the synced design/ directory (Decision 141, design/documents/doc-43-schema-topology-and-documentation-division.md). Migrations are the ground truth for as-built claims.
The catalog was motivated by a 2026-07 inventory of the console's domain models, which traced the majority of a 56-finding UX audit to model-attributable causes: rules that lived only in prose, invariants enforced nowhere, and dimensions that were easy to conflate because no single page named them side by side.
The cards
- Product / catalog — how capabilities are packaged, priced, and sold; the dissolved kind taxonomy and the shape views that replaced it.
- Payments and Billing — billing accounts, subscriptions, invoices and payments projected from Stripe, scheduled changes as intent, and the reconciler.
- Plan Ladders and Transitions — ranked tiers, who occupies which rung, the append-only audit, and the conferral functions as sole writers.
- Entitlements — resource keys, sets and rules, grants as decrees, provisions as delivery, and the materializer.
- Resource Pools — the per-organization container: workspace assignments, the two resolution directions, and pool-grain usage.
- Providers and Integrations — the registry and its connections, boot-time manifests, resource-key ownership, desired-state delivery, and the shared substrate.
- Domains Registry — claims as subtree ownership, placements as the only thing that serves, and the anti-abuse ledger.
- Identity, Organizations, and Workspaces — users vs persons, the containment ladder, org types as policy, and first-login provisioning.
A new domain model is not considered documented until its card exists and is listed here.
Card anatomy
Every card has four sections in this order:
- Purpose — what the model owns and why it exists, in plain present tense.
- Where this lives — a map of the model's pieces: each table, view, function, and code file, with one line saying what it is. Locations live here, not scattered through the body.
- Invariants — the rules the model guarantees, one per numbered entry so reviews can cite "invariant 3". Each entry carries an enforcement tag matching the actual mechanism: [db] means the database schema rejects violations outright; [db-code] means the database functions are written to uphold the rule, so reviews must protect it when they change; [app] means only application code upholds the rule, so new code paths must uphold it too.
- Dimensions — the orthogonal axes a maintainer must hold simultaneously, each defined where it is named.
Cards describe the model as it is today, for a reader who knows nothing yet. That means: no history, no decision numbers, no change narrative in the body — a card introduces every table, column, view, and concept before or where it first uses it. Drift between design and code, open questions, and other bookkeeping live on the forge tracker, not in the cards.
Style contract
Card prose follows these rules, and edits are reviewed against them:
- Write for someone with zero context: never assume the reader knows a term, a table, or an internal codename you haven't introduced.
- Name the agent: state what acted and what it acted on.
- Give each verb its own object; do not let one object serve two verbs.
- Connect clauses with explicit causal or temporal words (because, so, when, after) — never with a bare comma.
- Replace every metaphor or compressed phrase with the literal claim it stands for.
- Give every count or statistic its denominator.
A change that alters an invariant, dimension, or map entry recorded on a card must update that card in the same change (see openspec/specs/model-catalog/spec.md once this change archives).