docs(invites): correct stale last_seen_at NULL claim

The provisioning docstring claimed the invitee row gets
`last_seen_at = NULL` as the "not yet arrived" discriminator. It does
not: the column is NOT NULL and the INSERT omits it, so it defaults to
datetime('now') — the longer note below already explained this, but the
bullet contradicted it. Rewrite the bullet to state the real behavior
(both timestamps default to now; the pending-invite state lives in the
unclaimed user_invite_tokens row) and note that consumers must treat a
pending-invite row as never-seen. Comment-only; no runtime change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Ben Stull
2026-05-30 04:04:11 -07:00
parent 7e595b6e5e
commit e8e555d8a4
+10 -4
View File
@@ -144,10 +144,16 @@ def create_invite(
The invitee `users` row is provisioned with: The invitee `users` row is provisioned with:
* `permission_state='granted'` — the admin's hand is the grant; * `permission_state='granted'` — the admin's hand is the grant;
the v0.8.0 self-serve `pending` queue is for the other path. the v0.8.0 self-serve `pending` queue is for the other path.
* `last_seen_at = NULL` — the discriminator for "invited but * `created_at` / `last_seen_at` — NOT set here, so both fall
not yet arrived" per the §16 / roadmap design. Every sign-in through to the column default `datetime('now')` (the column is
path stamps `last_seen_at` to now, so a NULL value means the `NOT NULL`; see `migrations/001_users_and_audit.sql` and the
invited user has not clicked through yet. longer note below). The "invited but not yet arrived" state is
therefore NOT carried on the user row — it is the existence of
an unclaimed `user_invite_tokens` row, surfaced as the listing's
`pending_invite` field. Consumers that want a truthful
last-seen MUST treat a pending-invite row as never-seen rather
than trusting `last_seen_at` (every real sign-in path stamps it
to now, but an unclaimed invite has never hit one).
* `gitea_id = NULL`, `gitea_login = NULL` — same as a v0.7.0 * `gitea_id = NULL`, `gitea_login = NULL` — same as a v0.7.0
OTC-provisioned user; the OAuth identity is grandfathered if OTC-provisioned user; the OAuth identity is grandfathered if
the user ever lands through that path. the user ever lands through that path.