Skip to content

Phase 8: CLI and web parity for account tiers - #1270

Merged
neuromechanist merged 26 commits into
feature/issue-1250-epic-account-tiersfrom
feature/issue-1268-phase8-parity
Sep 6, 2026
Merged

neuromechanist merged 26 commits into
feature/issue-1250-epic-account-tiersfrom
feature/issue-1268-phase8-parity

Conversation

@neuromechanist

Copy link
Copy Markdown
Contributor

Closes #1268
Part of #1250

Before this epic reaches dev, the CLI and the web have to present one account model in one set of words. They did not: an upload-access request was refused by six hand-written blank() checks in services/upload-access.ts, nemar auth status said nothing about the fields it named, request-upload-access rendered them through a private UPLOAD_ACCESS_FIX table, and the dashboard derived a third list client-side. Three implementations of one rule, in two repositories, none of which failed when another changed — and the drift was already visible: the website said "Set it in Settings or run nemar auth profile set-github" where the CLI said "run 'nemar auth profile set-github '".

What landed

One matrix, one copy table, one gap function (ADR 0045).

  • shared/contract/account-copy.ts — the 81 keys the website shipped in Profile gaps: what each missing field blocks website#310, string for string, plus 12 cli.-prefixed keys the website has no surface for (sandbox, the terminal headings, the preflight). This contract is the source of truth; the website's src/lib/account-copy.ts is its transcription.
  • shared/contract/profile-gaps.ts — the matrix as data (blocks, where each field is set on each surface, whether it is derivable) plus the pure computeProfileGaps, and the rendering both surfaces print through.
  • The function is the only implementation. GET /users/me and GET /auth/me report its output as profile_gaps; checkUploadAccessRequest builds its missing array from it. They cannot disagree because there is one answer.

Username assignment at web sign-in. The ADR 0042 sweep closes the 19 accounts that exist and nothing after them. An account signing in with username IS NULL and a usable name now gets the same suggestion, collision-suffixed: inside the sign-in transaction at /auth/code/verify, and chained behind the ORCID name refresh on the callback and finalize paths, where the name only arrives after the response. No name leaves the column NULL and onboarding asks; nothing is invented from the email local part. Migration 0079 adds username_auto_assigned, written by both paths and cleared when the person changes the username.

The CLI says it out loud. A "Profile" block under nemar auth status and nemar auth profile; an upload-access preflight on nemar dataset upload that runs before validation and stops a run that cannot succeed; request-upload-access rendering missing through the same sentences. Sandbox training stays the CLI-only gate.

Two decisions taken from the website half and matched here: ORCID is not a gap (a CLI account cannot exist without one and a web account holds every tier without one — what an iD changes is where the NAME is set), and the email_verified gap blocks ["verified", "upload_access"] with a sentence that leads on activating the account.

Files

Contract shared/contract/{account-copy,profile-gaps,index,user}.ts
Backend services/{profile-gaps,username-assignment,upload-access,email-verification,web-session}.ts, routes/{users,auth-web,auth-orcid,admin/user-usernames}.ts, migration 0079
CLI lib/{account-gaps,config}.ts, lib/upload/preflight.ts, commands/{auth,dataset}.ts
Docs ADR 0045, the ADR index, AGENTS.md

How it was tested

Real tests only, no mocks. New: test/profile-gaps-matrix.test.ts (every field pinned against a fixture transcribed from the website's table, and all 2^7 combinations of the derivable fields, with blocks and set_on), test/account-copy-parity.test.ts (reads the website's copy module as text and fails on any shared key that drifted; skips with a note when no checkout sits beside this one), backend/test/profile-gaps-route.test.ts (asks /users/me, /auth/me and the refusal about one row and compares), backend/test/username-auto-assign-route.test.ts (all three sign-in paths through real routes: assigned, collision-suffixed, no name, a name that folds to nothing, the audit row, and the flag cleared on a real change but not on a re-save), test/auth-gaps-cli.test.ts (auth status, auth profile and the upload preflight through the real CLI against a local server, asserting the sentences verbatim).

Every new assertion was mutation-checked once — dropping the sandbox line, making the preflight never fail, printing a stale gap list after a failed refresh, narrowing a field's blocks, dropping profile_gaps from /users/me, dropping username_auto_assigned = 1 from the claim, dropping the flag clear from the PATCH, and cutting missing loose from the gap function each turn a test red.

bun run lint, bun run typecheck and bun run migrations:d1-check are clean. bun test: 5159 pass, 97 skip, 50 fail, and every failure is in a file this PR does not touch — the live-tier suites that need test/.env.test credentials this worktree has no copy of (test/api.test.ts 35, test/cli.test.ts 13, backend/test/publication-recorder.test.ts 3, plus one each in test/iam-removal.test.ts, test/email-preferences.test.ts, test/e2e-upload.test.ts, the last confirmed pre-existing by re-running it with the new preflight disabled).

One pre-existing fixture needed a fix: backend/test/identity-conflict-still-usable.test.ts replayed only the migrations up to 0077, so /users/me 500'd the moment it selected a column a later migration adds. It now replays the ones after 0077 too, keeping the seed-then-flag split that is the point of the file.

Every user-facing sentence about tiers, upload access and missing profile
fields moves into shared/contract/account-copy.ts, and the matrix behind
them into shared/contract/profile-gaps.ts with the pure computeProfileGaps
the backend will compute profile_gaps from.

The website (nemarOrg/website#310) transcribes both files; the parity test
reads its copy module as text and fails on any shared key that drifted,
skipping with a note when no website checkout sits beside this one. The
matrix test pins every field against a fixture copied from the website's
table and walks all 2^7 combinations of the derivable fields.

Sandbox training is deliberately outside the shared matrix: it exists in
the terminal and nowhere else, so a mirrored row would be a claim about
both surfaces that is false on one.
users.username_auto_assigned records that a handle was derived from the
name rather than chosen, by the ADR 0042 backfill sweep or at a web
sign-in. Onboarding and Settings offer to change it once, an offer that
would be nonsense to someone who typed their own at CLI signup and that
the users table had no other way to tell apart.

Cleared, not sticky: PATCH /auth/profile sets it back to 0 on a real
username change. DEFAULT 0 is honest for the back catalogue -- every
existing row either typed its username or still holds NULL.
GET /users/me and GET /auth/me now carry profile_gaps and
username_auto_assigned, and checkUploadAccessRequest builds its `missing`
array from the same computeProfileGaps -- so a refusal, a status command
and a dashboard nudge cannot name three different sets of fields. The
route test asks all three about one row and compares.

A web account that signs in with username NULL and a usable name is given
the ADR 0042 suggestion, collision-suffixed: inside the sign-in
transaction at /auth/code/verify, and chained behind the ORCID name
refresh on the callback and finalize paths, where the name itself only
arrives after the response. No name leaves the column NULL; nothing is
invented from the email local part. The sweep stays the batch path and
shares the claim statement, so both mark what they did.

identity-conflict-still-usable replays the migrations after 0077 as well
as before it: it stopped at 0077, so /users/me 500'd the moment it
selected a column a later migration adds.
`nemar auth status` and `nemar auth profile` print a Profile block: one
sentence per gap, from the shared copy table, with the exact command that
fixes each. status reads the backend's list from the config cache so it
still works offline, with the same three-state honesty the upload-access
line has -- a refresh that was asked for and failed reports not-checked
rather than presenting yesterday's list as today's.

`nemar dataset upload` gains an upload-access preflight before anything
expensive runs. A missing grant ends the run; --dry-run continues, since
it uploads nothing; a grant that cannot be READ warns and continues,
because the server enforces the gate regardless. Sandbox training stays
the CLI-only gate, now stated in the same sentence shape.

request-upload-access renders `missing` through those sentences too, so
the refusal and the nudge read alike. The ad hoc UPLOAD_ACCESS_FIX table
and the support-page hint are gone.
One matrix, one copy table, one gap function shared by /users/me,
/auth/me and the upload-access preconditions; the website transcribes the
copy module and derives identically. Records the sweep-versus-sign-in
split for usernames, the one-time change the mark buys, and what stays
CLI-only.

AGENTS.md points at the two contract files as the parity source.
@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown

📦 Package Preview

Your package is ready to test!

bun install -g nemar-cli@PR1270

Version: 0.9.16-PR1270.77e63ab
Commit: 77e63ab


🤖 Updated on each push.

@neuromechanist

Copy link
Copy Markdown
Contributor Author

Review findings addressed, one commit per numbered item. All 16 are fixed; none was a false positive.

  1. CRITICAL, pickUsernameForName burning a correctly-typed code: 94ba782. The scan now runs inside its own try/catch in /auth/code/verify, so a transient D1 failure logs with the account id and the sign-in completes with no assignment instead of reaching the outer catch and returning a 500 that never restores the code. An exhausted pick also gets the same console.warn the two ORCID doors already log. TAKEN_SQL is exported so the test can point that one statement at SQL SQLite refuses (the read-side sibling of blockUserWrites()), and the new test asserts 200, a real session row and cookie, the promotion, a NULL username, no audit row, and the log line.

  2. profile_gaps ?? [] reading absent as empty at upload preflight: eeb952e. The step now branches on user.profile_gaps === undefined and prints the new cli.upload.preflight.gaps_unknown copy key, matching the three-state honesty service_access already has. Covered in test/auth-gaps-cli.test.ts by a real subprocess run against a local server that omits the field.

  3. Stale userRow.username on the lost-claim branch: 49855ed. When a claim was planned but did not land, the row is re-read (guarded, non-fatal, because the sign-in has already committed) before the response is built, and the comment now distinguishes the two branches. The test stages the race deterministically with a SQLite trigger on the session INSERT, which is the statement immediately before the claim in the same batch.

  4. The case-insensitive username index ADR 0042 promised: a59fd90. Migration 0080_username_case_insensitive_unique.sql adds a partial unique index on users(username COLLATE NOCASE) with 0077's predicate clause for clause (NULL/blank excluded, deleted_at IS NULL, identity_conflict = 0), no pattern of any kind, and bun run migrations:d1-check replays all 82 migrations through real D1 clean. PATCH /auth/profile already mapped the violation to a typed username_taken through isUsernameUniqueViolation, and SQLite reports the new index's failure as UNIQUE constraint failed: users.username (the column), so that path is unchanged; the CLI set-username goes through the same route. A new route test provokes the case-variant violation with a trigger that plants ada between the pre-check and the write, and fails without the migration. ADR 0045's Consequences note the closed gap.

  5. profileGapSchema stricter than both renderers: db42c7d. blocks and set_on are now .optional(), with parse tests for an entry carrying only field and for one carrying no field at all.

  6. exhausted collapsed into conflict: 702a965. Added to backfillUsernameOutcomeSchema with a doc line, reported from the route (the claim race at the write keeps conflict), counted in the response and in BackfillUsernamesResponse, and rendered by the CLI with its own branch and summary counter. It also stays in the non-zero exit condition, because it used to be a conflict and splitting it must not turn a run that finished nothing into a clean exit. The pre-existing route test that asserted conflict for a saturated base is now the exhausted test, and reads the suffix limit from the newly exported USERNAME_SUFFIX_LIMIT instead of a hardcoded 50.

  7. Account status compared as bare strings: efc7c1a. accountStatusSchema (pending/verified/approved/revoked, the set migration 0001's CHECK constraint closes) is declared once and used by userSchema.status and ProfileGapAccount.status. webUserSchema.status gets a SECOND enum, webAccountStatusSchema (active/pending/revoked): /auth/me does not report the column, it reports userStatusForDashboard's collapse of it, so one enum would have conflated two vocabularies. The row types that feed computeProfileGaps were narrowed to AccountStatus in auth-web.ts, users.ts and web-session.ts.

  8. The loose { field, blocks, set_on } shape declared four times: 836d8e7. ProfileGapWireEntry is exported from profile-gaps.ts and used by resolveWireProfileGaps and ProfileGapView.gaps; both zod schemas stay schemas, and each is pinned to it by an AssignableTo alias that resolves to never if it tightens.

  9. computeProfileGaps exhaustive by construction: 1954cc5. derivable: boolean is replaced by isMissing: ((account) => boolean) | null on ProfileGapDefinition, so the Record<GapField, ...> constraint forces every row to say when it is missing; DERIVABLE_GAP_FIELDS is derived from it and the if-chain is gone. The 128-combination oracle passes unchanged and goes red when a single predicate is neutered.

  10. username_auto_assigned converted four ways: 5d6bff4. flag() moved to backend/src/db/flag.ts (accepting null/undefined so flag(row?.col) works), reused at all four sites, and services/profile-gaps.ts imports it rather than keeping a private copy.

  11. Migration 0079's header and ADR 0045's Context claiming the sweep has run: 2ba58b8. Both reworded: 18 nameless rows as of 2026-09-06, zero sweep runs, the first production run after 0079 is what marks them, and the candidate predicate can never revisit a row that already has a username, so "re-run the sweep" is not a repair. The same claim in username-assignment.ts's module docstring is corrected too.

  12. Step 1d in the preflight JSDoc: 4ec534e. It is 1c; 1d is the required-tools step.

  13. Parity enforced only on developer machines: 14bcafe. unit-pure now sparse-checks out nemarOrg/website's src/lib/account-copy.ts (public, no token, non-cone, one file) into website-copy/, with ref pairing website staging to nemar-cli dev/feature branches and website main to main, and passes it as NEMAR_WEBSITE_ACCOUNT_COPY. The test treats that variable as the contract: a path that is not there FAILS naming the path and the variable, while an unset variable with no sibling checkout is a visible describe.skipIf skip rather than an early return. website-copy/ is gitignored, and the job's file glob (test/*.test.ts backend/test/*.test.ts) cannot reach it. Proved in all three modes: declared-and-missing fails, declared-and-present passes, unset-with-bogus-candidates reports 3 skip.

  14. Sign-in coverage gaps: 79d9075. Added the saturated-base case at /auth/code/verify (NULL username, flag 0, no audit row, the warn log naming the base), the lost-claim case staged deterministically through the route with a trigger that has a different account take the handle mid-batch, a direct assertion that usernameClaimStatement reports changes === 0 rather than raising (the property that makes it safe to batch inside a sign-in transaction), a literal double sign-in asserting one audit row and an unchanged username, and two more ORCID-callback cases: a suffix collision, and a public-record name with no ASCII to fold to.

  15. The backfill's per-row mark unasserted: e869106. The assigns-and-audits test now checks username_auto_assigned = 1 on the row and the per-row username_auto_assigned audit entry with details.source === "admin_backfill"; both go red when the corresponding write is removed.

  16. NEMAR_CONFIG_DIR = undefined leaking the string across the shared test process: c5dddae. The previous value is captured in beforeAll and restored in afterAll, deleting the key when it was unset. No undefined/ directory exists after a full run.

Verification from the worktree: bun run lint clean, bun run typecheck clean, bun run migrations:d1-check replays 82 migrations through real D1 and the catalogue matches bun:sqlite (87 objects, 23 tables). Full bun test: 5173 pass, 97 skip, 50 fail across 351 files. 49 of the failures are the live-tier files that need test/.env.test credentials (api.test.ts 34, cli.test.ts 13, iam-removal.test.ts 1, e2e-upload.test.ts 1).

The 50th is real, and it is not from these commits. account-copy-parity > nothing the website carries is missing here fails because nemarOrg/website merged #312 to staging today ("Unverified ORCID blocks the upload access request"), which added three copy keys this contract does not have:

gap.field.orcid_verified.label
gap.field.orcid_verified.set_on.web
gap.field.orcid_verified.set_on.cli

The same test fails identically on the parent commit, so item 13 did not cause it; it is the first thing the newly-enforced check found. Landing the contract half here is a feature, not a review fix: it needs a new orcid_verified row in PROFILE_GAP_MATRIX, a backend precondition in services/upload-access.ts (which has none today) with the admin/owner exemption #312 describes, a 2^8 oracle, and an amendment to ADR 0045's "ORCID is not a gap" paragraph. It should be its own issue. Until it lands, the unit-pure job on this PR will be red on that one assertion.

@neuromechanist

Copy link
Copy Markdown
Contributor Author

Closed the three residual review findings from this thread.

  1. Lost-claim re-read (POST /auth/code/verify): exported REREAD_USERNAME_SQL from backend/src/services/username-assignment.ts next to TAKEN_SQL, switched the call site in backend/src/routes/auth-web.ts to use it, made the fallback trade-off explicit in the comment (the next GET /auth/me reads the row fresh, so a stale value here costs at most one round trip), and added a fault-injection test in backend/test/username-auto-assign-route.test.ts that stages the mid-sign-in race and diverts the re-read statement. Mutation-checked by removing the try/catch fallback: the new test failed (500 instead of 200) as expected, then the fallback was restored. Commit 1505bee. 20/20 tests pass in that file.

  2. --json exit-code ordering in src/commands/admin.ts: moved the exit-code computation above the --json early return in both backfill-usernames and backfill-names (same shape, same bug) so a scripted caller sees the same verdict in either output mode. Added a test in test/admin-backfill-usernames-cli.test.ts asserting --json exits 1 when the response carries exhausted > 0 (the existing "prints the raw response" test already covers the exit-0 clean case). Mutation-checked by reverting the ordering: the new test failed (exit 0 instead of 1) as expected, then the fix was restored. Commit 3fff09f. 13/13 tests pass in that file.

  3. AssignableTo<B, A extends B> in shared/contract/profile-gaps.ts never guarded anything, because every field on ProfileGapWireEntry is typed unknown and any shape is assignable to unknown (verified against tsc 5.9.3 strict). Replaced it with GapFieldsStayOptional<T>, a conditional type that resolves to never unless undefined extends T["blocks"] and undefined extends T["set_on"], used at both declaration sites (shared/contract/user.ts's _profileGapWireIsRenderable, src/lib/config.ts's _cachedProfileGapIsRenderable). Proved it catches a tightening: temporarily made blocks required on profileGapSchema, bun run typecheck failed with Type 'true' is not assignable to type 'never' at the user.ts declaration site, then reverted. Removed AssignableTo entirely (no other use sites) and rewrote both docstrings to point at test/contract-schemas.test.ts "a profile_gaps entry may carry only its field name" as the runtime half of the guarantee. Commit 77e63ab.

Verification: bun run lint, bun run typecheck, and bun run migrations:d1-check all clean. bun test on every touched file plus the three required suites: 121/121 pass (username-auto-assign-route 20, admin-backfill-usernames-cli 13, profile-gaps-matrix 36, contract-schemas 43, account-copy-parity 9). No deviations from the brief. Pushed to feature/issue-1268-phase8-parity; not merged.

This branch was previously deployed

1 inactive deployment
npm — 77e63ab0 Deployed Sep 6, 2026 by neuromechanist via publish #2330
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant