Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
f509d28
feat: one copy table and gap matrix for accounts
neuromechanist Sep 6, 2026
2b58d09
feat: mark an auto-assigned username
neuromechanist Sep 6, 2026
d734a64
feat: serve profile gaps and name web accounts
neuromechanist Sep 6, 2026
69075df
feat: CLI prints what a profile is missing
neuromechanist Sep 6, 2026
c8e269b
docs: ADR 0045, parity by construction
neuromechanist Sep 6, 2026
94ba782
fix: never fail a sign-in over a username scan
neuromechanist Sep 6, 2026
eeb952e
fix: say what is unknown at upload preflight
neuromechanist Sep 6, 2026
49855ed
fix: report the username a race left behind
neuromechanist Sep 6, 2026
a59fd90
feat: case-insensitive username uniqueness
neuromechanist Sep 6, 2026
db42c7d
fix: tolerate a gap entry missing its keys
neuromechanist Sep 6, 2026
702a965
feat: report an exhausted username backfill
neuromechanist Sep 6, 2026
efc7c1a
refactor: one account status vocabulary
neuromechanist Sep 6, 2026
836d8e7
refactor: one loose profile gap wire type
neuromechanist Sep 6, 2026
1954cc5
refactor: the gap matrix owns its predicates
neuromechanist Sep 6, 2026
5d6bff4
refactor: one D1 integer flag helper
neuromechanist Sep 6, 2026
2ba58b8
docs: the 0042 sweep has not run yet
neuromechanist Sep 6, 2026
4ec534e
docs: the preflight is step 1c
neuromechanist Sep 6, 2026
14bcafe
ci: enforce the copy parity check
neuromechanist Sep 6, 2026
79d9075
test: username assignment edge cases
neuromechanist Sep 6, 2026
e869106
test: pin the backfill's per-row mark
neuromechanist Sep 6, 2026
c5dddae
test: restore NEMAR_CONFIG_DIR
neuromechanist Sep 6, 2026
566b179
copy: mirror the orcid_verified sentences
neuromechanist Sep 6, 2026
249cacf
test: sandbox gap sentence in the live tier
neuromechanist Sep 6, 2026
1505bee
test: fault-inject the lost-claim re-read
neuromechanist Sep 6, 2026
3fff09f
fix: json exit code before early return
neuromechanist Sep 6, 2026
77e63ab
fix: guard profile-gap wire fields for real
neuromechanist Sep 6, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
# ADR 0045: The CLI and the web say one thing about an account

**Status:** accepted
**Date:** 2026-09-05
**Owner:** Seyed Yahya Shirazi

> Numbering note: epic #1250 runs its phases in parallel worktrees off one epic
> branch, so the numbers were claimed out of order — phase 1 took 0040, phase 5
> took 0041, phase 3 took 0042, phase 4 took 0043 and phase 7 took 0044. This is
> phase 8, the last of them, and it is 0045. The index's gapless check goes green
> once the epic branch holds all six, which it does.

## Context

Epic #1250 rebuilt the account model across two surfaces at once. ADR 0040 fixed
the tiers, 0042 built the upload-access request, 0043 made an identity back one
account, 0044 brought identity self-service to the CLI, and
`nemarOrg/website#301`/`#310` built the browser half. By the end of phase 7 the
same account could be described three different ways in one afternoon:

- `POST /users/me/upload-access/request` refused with
`missing: ["github_username", "city"]`, assembled by six hand-written `blank()`
checks in `services/upload-access.ts`;
- `nemar auth status` said nothing about either field, and
`nemar auth request-upload-access` rendered them through `UPLOAD_ACCESS_FIX`,
a private table in `src/commands/auth.ts` that named commands with argument
placeholders (`nemar auth profile set-username <name>`);
- the dashboard derived its own list client-side, from the account fields
`/auth/me` happened to carry, and rendered it through the website's own
sentences.

Three implementations of one rule, in two repositories, none of which failed
when another changed. The concrete drift was already visible in the wording: the
website said "Set it in Settings or run `nemar auth profile set-github`" and the
CLI said "run 'nemar auth profile set-github <handle>'", for the same gap on the
same account.

There is a second, smaller version of the same problem. ADR 0042 built an admin
sweep to give the username-less web/ORCID rows a handle. It has not been run:
production still holds 18 of them (the 19 that ADR counted, minus a duplicate
account deleted since), and the first run is scheduled for after this epic
deploys. Even once it has, the sweep closes the accounts that exist and nothing
after them — a web sign-up whose owner abandons onboarding lands straight back
in `username IS NULL` and stays there until an operator remembers to run it
again. It also never revisits: its candidate predicate is
`username IS NULL OR TRIM(username) = ''`, so a row it has named is a row it
cannot see.

## Decision

**One matrix, one copy table, one gap function — declared here, transcribed
there.**

1. `shared/contract/account-copy.ts` holds every user-facing sentence about
tiers, upload access and missing fields, as literal strings under dotted
keys. `nemarOrg/website/src/lib/account-copy.ts` is a transcription of it.
Each repo has a drift test that reads the other's file **as text** and fails
on any shared key whose string differs
(`test/account-copy-parity.test.ts` here, `test/account-copy-drift.test.ts`
there); both skip with a note when the other checkout is absent, because CI
clones one repo.
2. `shared/contract/profile-gaps.ts` holds the matrix as data — for each field,
what it blocks, where it is set on each surface, and whether it is derivable
from an account row — plus the pure `computeProfileGaps(account)`.
3. **That function is the only implementation.** `GET /users/me` and
`GET /auth/me` both report its output as `profile_gaps`, and
`checkUploadAccessRequest` builds its `missing` array from it. The three
answers cannot disagree because there is one answer;
`backend/test/profile-gaps-route.test.ts` asks all three about one row and
compares.
4. **A username is assigned lazily as well as in batches.** At a web sign-in
(`/auth/code/verify`, the ORCID callback sign-in, and `/auth/orcid/finalize`)
an account with `username IS NULL` and a usable name gets the ADR 0042
suggestion, collision-suffixed. Migration 0079 adds
`users.username_auto_assigned`, set by both paths and cleared when the person
changes the username.
5. **Sandbox training stays CLI-only** and is deliberately outside the shared
matrix.

## Consequences

**A sentence now changes in one place.** Editing copy means editing this
contract and transcribing it; the drift tests make forgetting the second half
loud on a maintainer's machine, and the mirroring is asymmetric on purpose —
`cli.`-prefixed keys are the CLI's own and the website reports them as a note.

**A rule now changes in one place too, and that is the sharper claim.** Adding
a precondition to the upload-access request means adding a row to
`PROFILE_GAP_MATRIX`, and every surface picks it up: the refusal, the CLI's
Profile block, the upload preflight, the dashboard nudge. Nothing has to be
remembered.

**The wire grew two fields and lost none.** `profile_gaps` is `.optional()` on
the CLI's `userSchema` (an older backend omits it, and absent must not read as
"nothing missing") and REQUIRED on `webUserSchema`, which only ever describes
what this backend sends.

**`set_on` on the wire names surfaces, not prose.** `["web", "cli"]`, or
`["web"]` for a name owned by a verified ORCID record. "Settings" is a website
noun and `nemar auth profile set-github` a CLI one; neither is something the
backend should spell for two clients that already know their own vocabulary and
read it out of the copy table.

**The CLI still caches.** `nemar auth status` prints the gaps from the config
cache so it works offline, with the same three-state honesty the upload-access
line already has: cached, "not checked" when nobody has refreshed, and "not
checked" again when a refresh was asked for and failed. Only `nemar auth
profile` and the upload preflight always fetch.

**The upload preflight is a hard stop with one deliberate exception.** A missing
grant ends the run before validation, because the run cannot succeed; `--dry-run`
continues, because it uploads nothing and the plan is what was asked for. A
preflight that cannot READ the grant — offline, a 5xx, an older backend — warns
and continues, because the server enforces the gate regardless and refusing an
upload over a briefly unavailable status endpoint invents a refusal nobody made.

**The username finally gets the index ADR 0042 promised it.** That ADR's
Consequences say a case-variant race "can still land two usernames one shift key
apart" and that "phase 4's case-insensitive unique index closes it"; phase 4
(migration 0077) built that index for `orcid` and `email` and not for
`username`, so the sentence has been describing a file that did not exist.
Migration 0080 is it — the same partial predicate as 0077's two, and clean to
create because the username catalogue holds no case-variant duplicates.

**Two write paths now name accounts, and both mark what they did.** The sweep is
the batch path and sign-in is the lazy path; between them an account cannot keep
browsing NEMAR without a handle. The mark is a column and not just an audit row
because the copy that offers "we chose this from your name, change it if you
like" renders on every page load and cannot scan an audit log.

**The lazy assignment is a nudge, not a guarantee.** No name, a name that folds
to nothing in ASCII, or a saturated base leaves the column NULL and onboarding
asks — nothing is ever invented from the email local part (ADR 0042). At
`/auth/code/verify` the claim rides inside the sign-in's own transaction; on the
two ORCID paths it is chained behind the public-record name refresh, which
already runs after the response, so it lands a moment later.

**What is NOT shared, and should not become shared.** Sandbox training (no web
surface); anchors and hrefs (website routing); the refusal `message` strings,
which the backend builds and both clients prefer verbatim when present. Adding a
sandbox row to the shared matrix would make the table a claim about both
surfaces that is false on one of them.

## Alternatives considered

- **Publish `@nemar/contract` to npm and have the website import it.** The
correct end state, and out of scope for a phase that had to ship alongside a
website release. The contract directory is already written to lift verbatim
(zero deps beyond zod); the drift tests are the interim, and they cost a
transcription rather than a release cycle.
- **Let each surface derive its own gaps from the account fields.** What the
website did while waiting for this, and what the CLI would have had to do.
Two derivations that agree today and are not tested against each other are one
bug fix away from disagreeing, and the disagreement is invisible from either
side.
- **Have the backend send rendered sentences.** It would guarantee identical
wording and destroy everything else: a terminal wants a backtick-quoted
command, a browser wants an anchor to `/settings#profile-city`, and the
backend would be spelling both. Sending `field` plus `blocks` and rendering
locally keeps the rule central and the presentation where it belongs.
- **Assign usernames only in the sweep (ADR 0042 as shipped).** It converges on
the rows that exist and diverges on the ones arriving. The sweep stays; it is
now the batch half of a pair.
- **Assign at sign-up rather than at sign-in.** ORCID sign-up has no name yet:
`POST /auth/orcid/finalize` inserts the row and the given/family names arrive
afterwards from the public record. Assigning at the INSERT would skip exactly
the accounts this exists for, which is why the assignment is chained behind
the name refresh on both ORCID paths.
- **Make the upload preflight a warning only.** Kinder in the moment and wrong:
the upload will 403 at the server, after validation and after a repository has
been asked for. The one case where warning is right is the one where we do not
know the answer, and that is the case that warns.

## Receipts

- Issue #1268 (this phase), epic #1250, and the website's companion
`nemarOrg/website#309` / `#310`.
- ADR 0040 (tiers, and `service_access` as the single grant), ADR 0041 (the name
a DOI cites), ADR 0042 (the request, the username default, the sweep),
ADR 0043 (one person, one account), ADR 0044 (identity self-service on the
CLI).
- `shared/contract/account-copy.ts`, `shared/contract/profile-gaps.ts`,
`backend/src/services/profile-gaps.ts`,
`backend/src/services/username-assignment.ts`, migrations
`0079_username_auto_assigned.sql` and
`0080_username_case_insensitive_unique.sql`.
- `test/profile-gaps-matrix.test.ts` (the matrix against a fixture copied from
the website's table, and all 2^7 field combinations),
`test/account-copy-parity.test.ts`, `backend/test/profile-gaps-route.test.ts`,
`backend/test/username-auto-assign-route.test.ts`,
`test/auth-gaps-cli.test.ts`.
1 change: 1 addition & 0 deletions .context/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ invisible one — which is why it is checked rather than trusted.
- [ADR 0042](0042-upload-access-is-requested-once-by-the-person-who-wants-it.md) - Upload access is requested once, by the person who wants it
- [ADR 0043](0043-one-person-one-account.md) - One person, one account: ORCID, email and GitHub each back at most one live account
- [ADR 0044](0044-identity-self-service-reaches-the-cli.md) - Identity self-service reaches the CLI, and ORCID does it through the browser
- [ADR 0045](0045-the-cli-and-the-web-say-one-thing-about-an-account.md) - The CLI and the web say one thing about an account: one matrix, one copy table, one gap function

## Backfill note (2026-07-31)

Expand Down
31 changes: 31 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -317,7 +317,38 @@ jobs:
- name: Install backend dependencies
run: cd backend && bun install

# The website's transcription of shared/contract/account-copy.ts, so
# test/account-copy-parity.test.ts can actually compare the two here
# (#1268, ADR 0045). Without it that test found no checkout and returned
# early: the parity claim was enforced on developer machines and nowhere
# else, while reporting green as a required check.
#
# nemarOrg/website is PUBLIC, so no token is needed. Sparse, non-cone, one
# file: a table of string constants, not that repo's module graph. It
# lands in website-copy/ at the repo root, which the unit-pure file glob
# below cannot reach (it lists test/*.test.ts and backend/test/*.test.ts
# only) and .gitignore covers.
#
# REF PAIRING: website `staging` is the counterpart of nemar-cli `dev` and
# of every feature branch off it; website `main` pairs with nemar-cli
# `main`. Comparing a dev-side contract against the website's released
# copy would fail every PR that lands a copy change ahead of the website
# release, which is the normal order.
- name: Check out the website's copy table
uses: actions/checkout@v4
with:
repository: nemarOrg/website
path: website-copy
sparse-checkout: src/lib/account-copy.ts
sparse-checkout-cone-mode: false
ref: ${{ (github.base_ref == 'main' || github.ref_name == 'main') && 'main' || 'staging' }}

- name: Run pure unit tests (no live backend)
env:
# Names the checkout above. The parity test treats this as the
# contract: a path that is not there FAILS rather than skipping, so a
# broken checkout step cannot silently disable the check.
NEMAR_WEBSITE_ACCOUNT_COPY: website-copy/src/lib/account-copy.ts
run: |
# Deliberately no TEST_API_URL / secrets: these tests don't touch the
# backend, so a misclassified file fails loudly here instead of
Expand Down
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,11 @@ __pycache__/
# inside the working tree since the driver moved into this repo (#1109).
.zarr-secrets.env

# The unit-pure CI job sparse-checks out nemarOrg/website's account-copy.ts
# here so test/account-copy-parity.test.ts can compare the two (#1268). Ignored
# so a developer who reproduces that checkout locally cannot commit it.
website-copy/

# Regenerated by the deno-based BIDS validator tooling on local test runs.
# Untracked on dev and unrelated to any change here; it has been committed by
# accident twice now (dropped once in 745059e), so ignore it rather than rely
Expand Down
14 changes: 13 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,19 @@ Load-bearing ones to know before touching the relevant area:
0042 (upload access is requested once, by the person who wants it),
0043 (one person, one account: an ORCID iD, an email or a GitHub handle backs at most one live account),
0044 (identity self-service reaches the CLI; ORCID links through a browser handoff whose
signed state names the account).
signed state names the account),
0045 (the CLI and the web say one thing about an account).

**Account copy and the profile-gap matrix are declared once, in
[`shared/contract/account-copy.ts`](shared/contract/account-copy.ts) and
[`shared/contract/profile-gaps.ts`](shared/contract/profile-gaps.ts)** (ADR 0045).
Every sentence about tiers, upload access or a missing field comes from the first;
`computeProfileGaps` in the second is the ONE rule behind `profile_gaps` on
`GET /users/me`, `profile_gaps` on `GET /auth/me`, and the `missing` array a refused
upload-access request carries. `nemarOrg/website` transcribes both files and a drift
test on each side compares them when both checkouts are present. Change a sentence or a
rule there, never at a call site; `cli.`-prefixed keys are the CLI's own and the website
ignores them.

---

Expand Down
33 changes: 33 additions & 0 deletions backend/src/db/flag.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
/**
* One place that turns a D1 boolean column into a JavaScript boolean.
*
* SQLite has no boolean type, so every flag on `users` is an INTEGER with a
* `NOT NULL DEFAULT 0` — `email_verified` (0001), `orcid_verified` (0050),
* `service_access` (0062), `identity_conflict` (0077),
* `username_auto_assigned` (0079). Each one is read by several SELECTs and
* converted at each of them, and the conversions were drifting into three
* spellings for one question: `x === 1`, `!!x`, and `x === true || x === 1` for
* a value that might already have been normalised upstream.
*
* They are not equivalent. `!!x` says true for any non-zero integer AND for a
* non-empty string, so a column that ever held something unexpected reads as
* set; `x === 1` says false for a `true` that a caller had already converted.
* This is the third spelling, which is the correct one for both directions, and
* it lives here so a new flag column has somewhere obvious to be read from
* rather than a fourth spelling to invent.
*
* Lifted out of services/profile-gaps.ts (#1268 review), where it was a private
* helper doing exactly this for the three flags the gap matrix reads.
*/

/**
* True for the SQLite integer 1 and for a boolean `true`; false for everything
* else, INCLUDING null and undefined.
*
* `null | undefined` is accepted rather than pushed onto callers because the
* common shape is `flag(row?.some_column)` on a row that may not have been
* found — and an absent row's flag is not set, which is the same answer as 0.
*/
export function flag(value: number | boolean | null | undefined): boolean {
return value === true || value === 1;
}
47 changes: 47 additions & 0 deletions backend/src/db/migrations/0079_username_auto_assigned.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
-- Mark a username the account did not choose (epic #1250 phase #1268, ADR 0045).
--
-- WHAT THIS IS FOR. ADR 0042 gave the username-less web/ORCID rows a handle
-- through the admin backfill sweep, and phase 8 adds the lazy half: an account
-- that signs in with `username IS NULL` and a usable name gets the same
-- suggestion assigned server-side, in the same transaction as the sign-in, so
-- that abandoning onboarding no longer leaves the column NULL forever. Both
-- paths write a handle nobody typed.
--
-- That fact has to survive the write, because it changes what the product may
-- say next. Onboarding and Settings offer "we chose this from your name, change
-- it if you like" (`onboarding.username.auto_assigned.*` in
-- shared/contract/account-copy.ts) — an offer that would be nonsense to someone
-- who typed their handle at CLI signup, and the users table has no other way to
-- tell the two apart afterwards. The audit row records the EVENT; this column is
-- the STATE, and only the state can be read cheaply on every page load.
--
-- CLEARED, NOT STICKY. `PATCH /auth/profile` sets it back to 0 whenever the
-- username actually changes: once the person has picked one, the offer is spent
-- and repeating it would invite them to change a handle they just chose.
--
-- DEFAULT 0 IS THE HONEST DEFAULT for the back catalogue. Every existing row is
-- one of: a CLI signup that typed its username, or a web row that is still NULL
-- (and so has nothing to have been auto-assigned). Neither is an
-- auto-assignment, and no data migration guesses at history here.
--
-- The nameless rows are still nameless. ADR 0042 built the sweep; as of
-- 2026-09-06 production holds 18 of them (the 19 that ADR describes, minus a
-- duplicate account since deleted) and the sweep has been run ZERO times — it
-- is scheduled for after this epic deploys. So the FIRST production run of
-- `POST /admin/users/backfill-usernames` after this column exists is what marks
-- those rows; there is nothing here for it to re-mark.
--
-- And "re-run the sweep" is not a repair for a row it has already named,
-- anywhere: its candidate predicate is `username IS NULL OR TRIM(username) = ''`
-- (REMAINING_SQL, routes/admin/user-usernames.ts), so a row that HAS a username
-- is no longer a candidate and no future run will ever look at it again. The
-- only rows that can be left holding 0 after being auto-named are ones named by
-- a sweep that ran before this migration — dev D1 only, since production has
-- run none — and fixing those would be a one-off UPDATE against a list of ids,
-- not a sweep.
--
-- One statement, one column, NOT NULL with a default, so it is a rewrite-free
-- ALTER on SQLite and re-running the file is the only thing that fails (which is
-- what d1_migrations already prevents).

ALTER TABLE users ADD COLUMN username_auto_assigned INTEGER NOT NULL DEFAULT 0;
Loading
Loading