Skip to content

Phase E4: Admin compute tab #497

Closed
Closed

Description

@neuromechanist

Goal

After this phase an admin has a Compute tab in the admin portal where they review and decide compute access requests, and can see the platform's pools and usage, the jobs the backend flagged (mismatch, unreserved, unattributed), and the drift between NEMAR's ledger and the supercomputer's own accounting, as far as the backend serves each.

Routing

Scope

In: the compute entry in ADMIN_TABS, src/pages/admin/compute.astro, the access-request review with decisions, read-only sections for pools, usage, flagged jobs and drift, a tab badge for open requests.
Out: changing owner policy (that is nemar admin compute policy set, owner-only, in the CLI), legal holds and record reads (owner-only, CLI), moving a charge (CLI), anything that reads identities from the records bucket.

Design references

Design section 4 (approval is a person's decision and includes export-control screening against the stated country), section 5 (pools, owner policy), section 6 ("Jobs that skipped the reservation": unreserved and unattributed flags), section 9 ("Admins see usage and job state, not identities or code").
Closest code: src/lib/admin-tabs.ts (AdminTab, ADMIN_TABS, adminMetricHref), src/pages/admin/users.astro and src/lib/users-admin-api.ts (chips, list, approve and revoke by id, fetchAwaitingApprovalCount), src/components/admin/UserAdminRow.astro, src/layouts/AdminLayout.astro (BADGE_WORDS), src/lib/admin-guard.ts, src/pages/admin/mail.astro (inert text rule, ADR 0029), src/lib/admin-badges.ts.

Changes

  • src/lib/admin-tabs.ts: add "compute" to AdminTab and { id: "compute", label: "Compute", href: "/admin/compute", enabled: true } to ADMIN_TABS; update admin-tabs.test.ts. Add a metric-family mapping only if the observability metrics expose a compute. family; otherwise none.
  • src/lib/compute-admin-api.ts: listComputeAccess({ state, limit, after }), decideComputeAccess(id, action, reason?), and one reader per section the plan found a route for; SSR with cookieHeader, browser through /api/v1, deadlines as in admin-api.ts; a body the guard rejects is an error, never an empty section. fetchComputeRequestsCount is fail-soft like the other badge counts and is added to AdminLayout.astro's Promise.all and BADGE_WORDS ("awaiting decision").
  • src/pages/admin/compute.astro: adminGate like the other admin pages, 404 for a non-admin; views by ?view= (requests default, pools, usage, flagged, drift), each section independent so one failed read degrades one section (SectionErrorNotice). Requests: a row per request with username or id, name, country, affiliation, ORCID iD (as the admin users tab shows it), requested date, the terms version accepted, and the stated purpose, all as inert text; buttons Grant, Deny (with an optional reason of at most 500 characters), and for a granted row Suspend and Revoke; each decision goes through a ConfirmDialog, posts to the by-id route through /api/v1, and re-renders the row from the response. The success and refusal sentences are the backend's, printed as text. Pools: platform budget and what has been granted, held and charged per pool, from the merged read route. Usage: SU by day, partition and source for the platform, as a table (and a hand-rolled SVG chart only if Phase E2: Compute dashboard #495's chart component fits without change). Flagged jobs: the flag word, the job id, the person's account id (no identity beyond what the admin users tab already shows), the front door, the charge and when; link to the user in the Users tab. Drift: the ledger-versus-supercomputer difference per job or day as Phase A7: Tenant reconcile, observer and reporting nemar-cli#2012 reports it, with the tolerance the backend states; a larger-than-tolerance row is visibly marked.
  • Where a section has no backend route yet, render a "not available yet" note naming the missing route, file the nemar-cli issue, and link it in the PR and the epic issue. Do not derive the numbers from other routes.
  • Owner-only affordances read session.user.backend_role === "owner" as users.astro does; suspension and revocation are admin actions in the backend, so do not hide them from admins.
  • Fixtures captured from the merged backend into test/fixtures/compute/: access rows in every state, a decision response and each refusal (not_requested, already_active), a flagged-jobs body, a drift body.

Tests (write these first)

  1. admin-tabs.test.ts: the new tab is present, enabled and linked; adminMetricHref still returns nothing for unknown families.
  2. compute-admin-api.test.ts: each reader parses its captured fixture; a malformed body raises; decideComputeAccess sends the right path and body per action and surfaces the backend's refusal sentence.
  3. A view-model test (pure) for the requests row: purpose and names as text, an overlong purpose truncated with the full text reachable, a missing affiliation reads "not set", the allowed buttons per state (grant for requested, suspended, denied and revoked; suspend and revoke for active).
  4. Badge-count test: fetchComputeRequestsCount returns no badge on a failed read and never throws.
  5. A guard test: a non-admin session gets /404 and an anonymous one the login redirect (the shared adminGate, asserted for this path).
  6. Browser check against the local backend as the seeded test admin: a person's request appears with the badge; grant it and see the row change and the person's Settings card and /compute page change; deny another with a reason; suspend and see the person's /compute explain; the sections without a route show their note; light, dark, phone width; keyboard-operable dialogs.

Acceptance criteria

  • An admin can grant, deny, suspend and revoke from the tab, and the backend's answer is what the page shows.
  • No section shows a number the page computed itself.
  • All user-controlled text is inert; no identity beyond what the Users tab shows.
  • A section with no route says so and has a filed issue.

Gates

bun run typecheck && bun run lint && bun run test && bun run build; then the browser check.

Rules that bite here

  • ADR 0029: untrusted text renders inert; a purpose is typed by a stranger.
  • Approval is a person's decision (nemar-cli ADR 0042): no bulk approve, no auto-approve, no default-focused Grant button in a confirm dialog.
  • adminGate is a role check that answers 404 to a signed-in non-admin; do not weaken it.
  • Admin portal pages share one layout whose badge reads must stay fail-soft.
  • Do not read identity from anywhere the design reserves for the owner.

Escalate to the owner if

  • Epic A exposes no read route for pools, flagged jobs or drift and the owner wants the tab to ship without them (record the decision).
  • A decision route's semantics differ from the design (for example suspend that does not freeze).

When merged

Update the architecture map in AGENTS.md; list in the epic issue which sections were served and which wait on a nemar-cli issue, with their numbers.

Activity

  1. neuromechanist commented on Nov 4, 2026

    @neuromechanist
    ContributorAuthor

    Driver amendment, 2026-11-04, from the nemar-cli phase A1 review. The owner policy reader on the website is lenient: it ignores keys it does not know, and it never reuses the strict policy schema of nemar-cli's shared/contract/compute.ts to parse an API response.

  2. neuromechanist commented on Nov 7, 2026

    @neuromechanist
    ContributorAuthor

    Plan for Phase E4: Admin Compute tab

    Planner output for the Sonnet implementer.
    Read against: website feature/issue-#493-epic-compute-web (E1 / #502 merged, ADR 0030) and nemar-cli feature/issue-2021-epic-compute-users at e0685a25 (Epic D through D4, which contains Epic A's admin routes).
    Epic A's own PR (nemar-cli#2063) is still open into dev, so every route below exists only on that branch today; the epic's existing rule (do not merge to staging before the compute epic is on nemar-cli dev) applies to this phase too.
    Where the issue text and the code differ, the code wins and this plan says so (section 2).

    0. Verdict in one table

    Section Backend route today Ships as
    Access requests (list, grant, deny, suspend, revoke) yes, admin full, with decisions
    Pools and budgets yes, admin (GET /admin/compute/pools) read-only table
    Usage partial: a quarterly report only (counts, not SU); no platform usage by day, partition and source quarter table + "not available yet" note + nemar-cli issue
    Flagged jobs yes, admin (GET /admin/compute/jobs?flag=); four flags not three; one flag per call read-only, one chip per flag
    Drift (ledger vs the supercomputer's accounting) no route. Served instead: unmatched accounting rows, mismatch-flagged jobs, and status counts "Reconciliation" view from those three + "not available yet" note for the per-job difference and the tolerance + nemar-cli issue

    No partner policy editing, no move-charge, no pool grants or adjustments, no job cancel or advance in this phase (section 5).

    1. The backend contract as merged

    All routes are on the admin router: authentication, then adminMiddleware (role admin or owner, else 403 { error: "Admin access required" } with no code), then cookieOriginGuard (a write made with a session cookie must come from a NEMAR page; the /api/v1 proxy forwards Origin).
    Browser calls are /api/v1/admin/compute/...; SSR calls use dashboardApiBase(cookieHeader).
    Money is integer milli-SU everywhere (*_milli).

    1.1 Access (backend/src/routes/admin/compute-access.ts, shared/contract/compute-access.ts, shared/compute-access-state.ts)

    Route Who Notes
    GET /admin/compute/access?state=&after=&limit= admin, owner query is .strict() (an unknown key is 400 invalid_query); state is one of requested active suspended denied revoked (not none); limit 1 to 200, default 50 (COMPUTE_ACCESS_PAGE_MAX); after is an account id and rows have id > after; answers { accounts: [...], next_after: number or null }
    POST /admin/compute/access/{grant,deny,suspend,revoke}/by-id/:id admin, owner body { reason?: string }, .strict(), at most 500 characters (COMPUTE_ACCESS_REASON_MAX_CHARS, a UTF-16 length), trimmed, empty becomes null; :id must match /^[1-9][0-9]{0,14}$/ or the answer is 400 invalid_query
    the same four, /:username twins admin, owner not used: a web account has username = NULL, which is why the by-id twins exist. Use by-id for everyone, as approveUserById does

    Row (accounts[], and account in a decision answer): id, username|null, email, given_name, family_name, affiliation, city, country, orcid, account_kind, compute_access, compute_access_requested_at, compute_access_notified_at, compute_access_granted_at, compute_access_granted_by (an account id), compute_purpose, compute_terms_version, compute_terms_accepted_at.
    The row carries no status, email_verified or orcid_verified.

    Decision answer (200): { decision, from, to, account, allocation?, email_sent }.
    allocation (grant only) is { granted: boolean, cpu_milli, gpu_milli, reason: null | "policy_default_zero" | "already_granted", policy_version: number|null }.
    There is no sentence in a success body.

    Decision matrix (the state machine, enforced in the flip's WHERE clause):

    Decision From To
    grant requested, suspended, denied, revoked active
    deny requested denied
    suspend active suspended
    revoke active, suspended revoked

    Side effects the confirm copy must state: a grant opens the owner's default allocation once per account (a re-grant adds nothing) and unfreezes the account's pools; a suspend and a revoke freeze the account's pools, cancel live jobs (the Tapis cancels follow from the retried sweep) and end the person's compute sign-ins.
    The person is mailed after the commit; the reason is NOT in the mail and no route reads it back (it lands in the audit row only).

    Refusals are { error: <sentence>, code: <word> }, the reverse of the Users routes, so readError() in api-base.ts is wrong here (it reads error as the code); use a reader like readMailError in mail-admin-api.ts:

    code HTTP meaning
    invalid_body, invalid_query 400 names the fields, never the values
    account_not_found 404
    not_requested 409 a grant (from none) or a deny from a state that is not requested
    already_active 409 a grant of an active account
    not_active 409 a suspend or revoke of an account that does not hold access
    self_decision 409 an admin granting their OWN access (an owner may; deny, suspend and revoke of oneself are allowed)
    account_not_in_good_standing 409 a grant to an account that is deleted, revoked or not verified
    stale_state 409 the state changed between the read and the write
    policy_unreadable 503 a grant fails closed, nothing written
    internal 500 the route re-reads the account AFTER its batch inside the same try, so a 500 can follow a committed decision

    Decisions read no compute switch and never touch service_access.

    1.2 Pools, status, policy (routes/admin/compute.ts, shared/contract/compute-admin.ts)

    Route Who Used in E4
    GET /admin/compute/pools?holder_kind=&after=&limit= (holder_kind is account, platform or partner, one per call) admin yes. { pools: [{ id, holder_kind, holder_ref, pool: "cpu" or "gpu", granted_milli, held_milli, charged_milli, available_milli (may be negative), frozen, created_at, updated_at }], next_after }, ordered by pool id, limit 1 to 200 (default 50). Platform pools are holder_ref people and pipelines, each for cpu and gpu
    GET /admin/compute/pools/by-id/:accountId admin no
    POST /admin/compute/pools/by-id/:accountId/grant and /adjust admin (needs an Idempotency-Key header); an adjustment of the CHARGE is owner-only (403 owner_only) no (section 5)
    POST /admin/compute/pools/platform/:key/grant and /adjust owner no
    GET /admin/compute/policy, PUT /admin/compute/policy owner (an admin gets 403 owner_only) no. An admin cannot even read the policy, so no policy value (default grant, settle tolerance, partner block) can be shown to an admin
    GET /admin/compute/status admin yes, on the Reconciliation view only. Booleans, counts and fixed words; it makes one Tapis token mint and one health call, so it is NOT called on every tab load. Fields used: switches.compute_enabled, reconciliation.paused, attention (an open record of counts by word, today access_reports_failed, cancel_pending_failed, copy_abandoned; values are not narrowed), tapis.token and tapis.health words

    1.3 Jobs and reporting (routes/admin/compute-reporting.ts, compute-jobs.ts)

    Route Who Used in E4
    GET /admin/compute/jobs?flag=&state=&account=&limit=&after= admin yes. flag is ONE of unreserved unattributed mismatch overrun (COMPUTE_JOB_FLAGS); state is one of the ten job states; limit 1 to 200 (default 50); after is the previous page's next_after (a row sequence, not a job id); newest first; answers { jobs: [jobView], next_after }
    GET /admin/compute/jobs?unmatched=1&limit= admin yes. { rows: [{ slurm_job_id, partition, state, elapsed_seconds, alloc_nodes, alloc_cpus, alloc_gpus, charged_milli or null, ingested_at }], total }: the supercomputer's accounting rows that no NEMAR job claims. Newest first, limit only (no cursor)
    GET /admin/compute/access-report?quarter=yyyyQn admin yes. { quarter, rows: [{ partition, source, distinct_users, jobs }], totals: { distinct_users, jobs } }: counts of people and jobs, no SU
    GET /admin/compute/report?account=&from=&to= admin no (one account, up to 5000 open-shape job objects)
    GET /admin/compute/records/:ref admin no (CLI)
    POST /admin/compute/records/:ref/read owner no
    GET /admin/compute/holds; POST /holds, DELETE /holds/:id read: admin; write: owner no
    GET /admin/compute/access-reports; POST .../requeue read: admin; requeue: owner no
    POST /admin/compute/jobs/:id/cancel, /advance admin no (section 5)
    POST /admin/compute/jobs/:id/move-charge owner no (section 5)
    POST /admin/compute/observer-runs, POST /pipeline/run, GET /pipeline/status admin no

    jobView (no identity, no spec, no log, no token): id, account_id|null, source (cli|web|partner|pipeline), kind, state, tapis_status, failure_code, failure_detail, platform_failure, cancel_requested, cancel_reason, partition, pool, held_milli, charged_milli, settled, flags[], created_at, submitted_at, started_at, ended_at, tapis_synced_at, outputs_completed, results_verified, results_bytes, records_copied, partner_state?, partner_flag?.
    Error words for these routes are COMPUTE_ADMIN_ERROR_CODES (invalid_query, job_not_found, owner_only, ...), in the same { error, code } envelope.

    2. Where the issue text and the code differ

    1. Success sentences are not the backend's. A decision success is structured fields only (decision, from, to, account, allocation, email_sent). Refusals do carry error (a sentence) and code. The page prints refusal sentences from error; success wording comes from the copy keys (section 7), composed from the served fields.
    2. The refusal envelope is { error: sentence, code: word }, so readError() must not be used. Same trap as the Mail routes; mirror readMailError.
    3. Four flags, not three. The issue names mismatch, unreserved, unattributed; the code also has overrun (a job that used more than its hold, recorded as a ledger overrun entry). And the API takes ONE flag per call: there is no "all flagged" query and no counts.
    4. Suspended rows have two actions: Grant (lifts the suspension) and Revoke. The issue says "for a granted row Suspend and Revoke"; the matrix above is the truth. denied and revoked rows offer Grant only.
    5. A self-grant by a non-owner admin is refused (self_decision); the issue does not mention it.
    6. The list is ordered by account id ascending, not by request time. The route's own comment says so; the contract header comment ("oldest request first") is wrong. The page must not re-sort across pages.
    7. There is no drift route. Epic A's reporting phase (#2012) shipped the unmatched-rows listing, the status route and the mismatch flag; nothing returns a ledger-versus-accounting difference per job or day, and the tolerance (policy settle.toleranceMilli and tolerancePercent) is only readable through the owner-only policy route.
    8. There is no platform usage by day, partition and source. The nearest admin read is the quarterly report (distinct users and jobs by partition and source, counts not SU) and per-pool totals.
    9. No count route. The badge needs a count; the only source is the list itself.
    10. No status, email_verified or orcid_verified on a request row. The page cannot warn "this account is no longer in good standing" before a grant; it learns it from the refusal.
    11. No single-account read. After an ambiguous outcome the page re-reads one account with GET /admin/compute/access?after=<id-1>&limit=1 (keyset is id > after, and with no state filter it lists every non-none state). This leans on the documented keyset behavior, not a dedicated route (nemar-cli issue F).
    12. Jobs and pools identify an account by id only, and the Users page is keyed by username, so "link to the user in the Users tab" works for request rows (they carry username) and not for job or pool rows (open question 8).
    13. The issue's amendment (website#497 comment: the owner policy reader is lenient and never reuses the strict nemar-cli schema) is satisfied vacuously: an admin cannot read the policy, so this phase has no policy reader. If an owner-only read-only policy panel is ever added, it must use a hand-written lenient guard.

    3. Where it lives, how it is gated

    • src/lib/admin-tabs.ts: add "compute" to AdminTab and { id: "compute", label: "Compute", href: "/admin/compute", enabled: true } at the end of ADMIN_TABS (after Mail). No TAB_FOR_METRIC_FAMILY entry (no compute. observability family is known), and adminMetricHref must keep returning undefined for unknown families. Update admin-tabs.test.ts.
    • src/pages/admin/compute.astro calls adminGate(session, Astro.url.pathname) first, exactly like users.astro (anonymous gets the login redirect, a signed-in non-admin gets /404). /admin is already an app-host prefix in host.ts; no change there.
    • Roles. adminGate collapses owner and admin to admin; the backend is the authority. The page reads session.user.backend_role for ONE thing in this phase: disabling the Grant button on the signed-in person's own row when they are not an owner, and saying why. Nothing owner-only is offered anywhere on this tab, so there is no owner-only control to hide; instead the lede states, from copy, that policy, legal holds, record reads and moving a charge are owner-only and done with nemar admin compute in the CLI.
    • Views by ?view=requests|pools|usage|flagged|drift; unknown or missing is requests. Other query parameters are validated and an invalid one is ignored: state (requests; one of the five or all; default requested), after (positive integer), holder_kind (pools), flag (flagged; default unreserved), quarter (usage; /^\d{4}Q[1-4]$/, default the current quarter from a tested pure helper). Chips use the admin-filters family from users.astro (anchors with aria-current).
    • Independence: within a view, every read is its own Promise.allSettled entry and a failed read renders a section notice naming what failed with the backend's sentence (error) or the transport word; it never renders an empty table. SectionErrorNotice.astro is typed to observability's MetricSectionError, so add a small ComputeSectionError.astro in the same visual family rather than bending that one.
    • Badge: fetchComputeRequestsCount in compute-admin-api.ts calls GET /admin/compute/access?state=requested&limit=200 with the 2 s badge deadline and returns { count, capped } or null; it never throws and logs a warning on degrade (like fetchAwaitingApprovalCount). count is the length of the served list; capped is next_after !== null. AdminLayout.astro: add it to the Promise.all, set BADGE_WORDS.compute = "awaiting decision", and make the badge text a string so a capped count renders 200+. This is the one number the page derives, and it is the row count of a served list rather than a computed quantity; nemar-cli issue C asks for a real count.

    4. Sections

    Every value is a text node; free-text fields go through displaySafeLine (one line) or displaySafeBody (purpose) from mail-display.ts, imported as is (ADR 0029). A source-level test scans the new files for set:html, innerHTML, insertAdjacentHTML, outerHTML, and links or images in free-text blocks.

    4.1 Requests (default)

    Chips: Requested (default), Active, Suspended, Denied, Revoked, All.
    Keyset pager: limit=25; "Next" only when next_after !== null; "First page" when after is present; no total and no "page N of M" because the API serves none (so AdminPagination.astro, which needs totals, is not reused). The page says, from copy, that the order is account creation order.

    Row (ComputeRequestRow.astro, one <article> per account, data-account-id):

    • heading: name (or the email when there is no name), @username or "no username" plus #id; a state pill (label, tone, icon from a lookup with a neutral raw-text fallback for an unknown word, like admin-badges.ts); a chip when account_kind is not person.
    • a labeled field "Stated country", prominent, with city, plus affiliation. This is the export-control screen. The backend serves no country list and no verdict, so the page does not rule on it; it puts the stated country next to the Grant button and the Grant dialog restates it. The country is free text the person typed, so it renders like any untrusted line.
    • email (as the Users review card shows it), ORCID iD (a link to https://orcid.org/<id> only when isValidOrcid, else text), requested date (absolute and relative via format.ts), terms version accepted and when, and the purpose (full text in a dir="auto" white-space: pre-wrap block; when longer than 280 characters, the first 280 and a <details> "Show full purpose" holding the whole text, so the full text is always reachable with no JS).
    • compute_access_notified_at null on a requested row prints the served fact "No administrator has been emailed about this request yet".
    • for active and suspended: "Granted by account #N" from compute_access_granted_at and _by.
    • a missing affiliation, city or name reads "not set" (a view-model rule, tested).
    • "Open in Users" to /admin/users/<username> only when username is non-null.
    • buttons per state (the pure allowedDecisions(state) mirrors the matrix; the backend still decides): requested: Grant, Deny; active: Suspend, Revoke; suspended: "Lift suspension" (a grant) and Revoke; denied and revoked: "Grant again". No bulk selection anywhere.

    4.1.1 ComputeDecisionDialog.astro (new; do not extend ConfirmDialog, which has a static body and no reason field and is used by other pages). One <dialog> filled per open with text nodes:

    • title per decision; a subject block (name, #id, stated country, affiliation); the consequences list for that decision from copy;
    • an optional reason <textarea maxlength="500"> with a live "N of 500" counter counting .length (the server's UTF-16 limit) and the line "Recorded in the audit log. The person is not sent it.";
    • for Grant only, an unticked checkbox "I reviewed this person's name, affiliation and stated country against the export-control rules" that keeps the confirm button disabled until ticked (open question 1);
    • for Revoke only, a typed word REVOKE (the Users tab pattern);
    • initial focus is Cancel, never the confirm button; Escape and Cancel close with no request; focus returns to the row's trigger button; events follow ConfirmDialog's custom-event style with a detail of { id, decision, reason }.

    4.1.2 Decide flow (src/lib/compute-decide-flow.ts, a pure state machine with a thin DOM shell in the page, like mail-reply-flow.ts): one decision in flight page-wide; on confirm the dialog closes, every button of that row is disabled and the row shows "Working" in a role="status" region; on 200 the row is re-rendered from the response account using the same view-model, plus a result note (4.1.3) that stays until the next load. A decided row is not removed from a filtered view, so the admin sees what happened.

    4.1.3 Result and error notes (text from copy keys, composed from served fields by pure describeDecision(result) and describeFailure(err), both unit tested):

    • grant with allocation.granted true: opened X CPU SU and Y GPU SU (from cpu_milli, gpu_milli via formatSu); reason: "policy_default_zero": the owner's default allocation is zero, nothing was opened; reason: "already_granted": an earlier grant already opened it; any other word prints the word.
    • email_sent: false: "The decision stands but the person could not be emailed; tell them." Not retried from the page.
    • 409 not_requested, already_active, not_active, stale_state: print the backend error, then re-read the account and re-render the row from truth, with the line "Someone else may have decided this first".
    • 409 self_decision, account_not_in_good_standing and 503 policy_unreadable: print error; the row is unchanged and its buttons come back.
    • 404 account_not_found: print error; mark the row stale.
    • 400: print error (field names); a bug if it happens, also console.error.
    • 401 and the plain 403 (no code): "Sign in again" or the sentence.
    • the proxy's upstream_unreachable or upstream_redirect, a timeout, a network error, a non-JSON gateway body and any 5xx: the outcome is UNKNOWN (a 500 can follow a committed batch), so say "The result is not confirmed", re-read the account and show the truth. Never auto-retry a POST.
    • Double submit: the in-flight lock plus the disabled row make a second click impossible in one tab; two tabs or two admins deciding the same account get the 409 path above. These routes take no Idempotency-Key and need none: the state flip is guarded by the from-state, so a repeat changes nothing.

    4.2 Pools

    Three independent reads: platform (holder_kind=platform), partner (holder_kind=partner) and accounts (holder_kind=account, limit=50, keyset on next_after, which is a pool id).
    Columns: holder (platform key or partner ref as text; account #N), pool word, granted, held, charged, available (a negative prints as negative), frozen (a word and icon, not colour alone), updated.
    SU strings come only from formatSu(milli) (integer thousandths in, string out; never a float sum). The page shows served numbers and nothing derived.
    No chart: no time dimension is served, and the issue allows one only if #495's component fits unchanged.
    An empty platform read says "No platform budgets are recorded", not zero.

    4.3 Usage

    Served: the quarterly report (quarter selector, default the current quarter): partition, source, distinct users, jobs, and the served totals row (the page never sums rows itself). The column heads say these are counts of people and jobs.
    Plus the "not available yet" note for SU charged by day, partition and source across the platform, naming the missing read and linking nemar-cli issue A. Pool charged totals live on the Pools view and are not copied here.

    4.4 Flagged jobs

    Chips: Unreserved (default), Unattributed, Mismatch, Overrun (?flag=). One GET /admin/compute/jobs?flag=<flag>&limit=50&after= per view, keyset pager as above.
    Columns: job id (text; no link, there is no admin job page and /compute/jobs/<id> is the person's page), the row's flags[] words, account #N or "no account" for null, front door (source), partition, pool, state pill (the shared compute-badges.ts from #495 when present, else the same rule), charged and held via formatSu, platform_failure as a labeled "NEMAR's fault" marker (an information flag; nothing is refunded automatically), failure_code and failure_detail as inert lines, partner_state and partner_flag words when present, created and ended times.
    A one-line meaning of each flag comes from copy (open question 6). The follow-up for an unreserved charge is the owner's move-charge, stated as CLI text, not a button.
    An empty list says "No jobs carry this flag", which is a fact about this read only.

    4.5 Reconciliation (?view=drift)

    Three independent reads, status first so it can qualify the others:

    • GET /admin/compute/status: show reconciliation.paused (when true, a banner: "Reconciliation is paused while compute is off. An empty list below does not mean nothing is unmatched.", because silence is evidence only when there was work to do), switches.compute_enabled, every key of attention whose value is a positive number as word: count with the word as served, and the Tapis token and health words as served. An unknown shape in attention renders as text, never as zero.
    • GET /admin/compute/jobs?unmatched=1&limit=100: accounting rows no job claims (Slurm id as text, partition, state, elapsed seconds, nodes, cpus, gpus, charged_milli or "not priced", ingested), with "Showing the newest N of total".
    • GET /admin/compute/jobs?flag=mismatch&limit=25: the mismatch-flagged jobs, linking to the Flagged view for the rest.
    • "Not available yet" notes for the per-job or per-day ledger-versus-accounting difference and the tolerance it is measured against (nemar-cli issue B). No row is marked "over tolerance": the page has no tolerance to apply and must not invent one.

    5. What the website offers

    • Offered: Grant, Deny, Suspend, Revoke (and "Lift suspension" and "Grant again", which are grants), each through the dialog, each by id, each with an optional reason.
    • Never offered on this tab: anything owner-only.
    • Reasons are write-only: no route returns a stored reason, so the page cannot show one after the fact. It does not echo the typed reason back either, which avoids a surface for untrusted text. The limitation is stated in the dialog and in nemar-cli issue D.
    • Recommendation on the cost-bearing and owner actions:
      • Partner policy editing: no. GET and PUT /admin/compute/policy are owner-only, and the partner reservation switches (partner_reservations_open, force_partner_off) are what the owner changes deliberately from the CLI.
      • Move-charge: no. Owner-only, raises a person's charge, needs the confirm_unproven_owner judgment, and the job list does not serve the attributed account the route compares against (attributed_account_id appears only in the move's own answer).
      • Pool grants and adjustments: no. The grant route is admin-allowed but needs an Idempotency-Key, moves real allocation, and the issue scopes pools as read-only; a later phase can add it with the Mail tab's key-per-draft pattern.
      • Job cancel and advance: no. Admin-allowed but out of scope, and a cancel is irreversible.

    6. Files and atomic commits

    Prerequisite in nemar-cli (a separate PR, before the copy keys can be transcribed): add the compute_admin.* keys to shared/contract/account-copy.ts, and file the issues in section 10.

    Website, one commit each, tests first within each:

    1. src/lib/compute-admin-contract.ts (transcribed closed lists: states, decisions and the from-states table, error codes, job states, flags, sources, pool words, holder kinds, platform keys, page maxima, reason max) and test/compute-admin-contract-drift.test.ts, strict in CI via NEMAR_CLI_COMPUTE_ADMIN_CONTRACT like the Mail drift test; add the paths (shared/contract/compute-access.ts, shared/contract/compute-admin.ts, shared/compute-state.ts, shared/compute-access-state.ts) to the existing sparse checkout in .github/workflows/ci.yml.
    2. scripts/capture-compute-admin-fixtures.mjs and test/fixtures/compute/admin-*.json (section 8).
    3. src/lib/compute-admin-api.ts and its test: listComputeAccess({ state, limit, after }), decideComputeAccess(id, decision, reason?), getComputeAccount(id) (the after=id-1&limit=1 re-read), listComputePools, listComputeJobs, listUnmatchedAccounting, getComputeAccessReport, getComputeStatus, fetchComputeRequestsCount. Plain fetch (never api-fetch.ts; the client-bundle guard forbids it), resolveSignal deadlines (5 s default, 2 s for the badge), hand-written guards (no zod in this repo; a body a guard rejects raises a typed error, never an empty list), readComputeAdminError for { error, code }, and classifyDecisionFailure returning refused | state_changed | unknown_outcome | signed_out.
    4. src/lib/compute-admin-view.ts and its test (pure): requestRowModel, allowedDecisions, describeDecision, describeFailure, flag and state label and tone lookups, the current-quarter helper, pool and job row models.
    5. Copy: transcribe the new compute_admin.* keys into src/lib/account-copy.ts (test/account-copy-drift.test.ts then pins them). No sentence is typed in a page or component; test/compute-admin-ui.test.ts enforces it.
    6. admin-tabs.ts and its test, the AdminLayout.astro badge, the badge test.
    7. ComputeDecisionDialog.astro, ComputeRequestRow.astro, ComputeSectionError.astro, compute-decide-flow.ts and its test, and src/pages/admin/compute.astro with the Requests view.
    8. The Pools, Usage, Flagged and Reconciliation views.
    9. The scripts/local-backend.mjs extension (section 9), .context/local-backend.md, the AGENTS.md architecture map and .context/handoff.md.

    If #495 has not merged when this starts, E4 creates src/lib/compute-format.ts with formatSu(milli: number): string exactly as #495's spec names it, and the same for compute-badges.ts; #495 rebases onto it. Whoever lands first owns the file, the other imports. compute-admin-api.ts is a separate file from #495's compute-api.ts, so there is no overlap there.

    7. Account-copy keys (both sides, parity)

    New keys, prefix compute_admin. (not cli., so the website transcribes them and the drift test compares both directions; plain string literals per ADR 0015, with the existing {placeholder} convention through fillCopy):

    • page: page.title, page.lede, page.owner_only_note, order_note (the list is in account-creation order)
    • views: view.requests, view.pools, view.usage, view.flagged, view.drift
    • state chips and labels: state.requested, state.active, state.suspended, state.denied, state.revoked, state.all (exact words for admins; the person-facing compute_access.state.* keys soften denied and revoked and are not reused)
    • row labels: row.stated_country, row.stated_country_hint, row.affiliation, row.purpose, row.show_full_purpose, row.terms, row.requested, row.granted_by, row.not_set, row.no_username, row.open_in_users, row.not_notified
    • actions: action.grant, action.grant_again, action.lift_suspension, action.deny, action.suspend, action.revoke
    • dialog: dialog.title.<decision> and dialog.consequence.<decision> for the four decisions, dialog.reason_label, dialog.reason_hint, dialog.ack_export_review, dialog.cancel; the typed word REVOKE stays a constant beside the keys, as in users.astro
    • self-grant: self_grant.disabled
    • results: result.granted_opened, result.granted_zero_default, result.granted_already, result.denied, result.suspended, result.revoked, result.email_not_sent, result.state_changed, result.unconfirmed, result.working
    • sections: section.failed, section.empty, the pool column heads, usage.counts_note, the four flag labels and one-line meanings, flagged.none, drift.paused, drift.empty_not_zero, unavailable.usage_by_day, unavailable.drift_difference, unavailable.link_label
    • badge: badge.awaiting_decision

    Refusal sentences are NOT keys: they come from the response error.

    8. Fixtures and the capture command

    scripts/capture-compute-admin-fixtures.mjs, run as
    NEMAR_CLI_DIR=<checkout of nemar-cli's Epic D branch> bun scripts/capture-compute-admin-fixtures.mjs
    (the command is named in every test file that reads a fixture and recorded in each fixture's _provenance with the nemar-cli commit, as E1's capture-compute-fixtures.mjs does).
    It imports the backend's own makeComputeApp, seedComputeUsers, COMPUTE_KEYS, freshDb and realD1 (the real admin router with its real middleware over a real migrated database and hashed API keys), and for job rows startLifecycleFixture, makeJob and endedJob (the Tapis stand-in; no tenant). Flag columns are set by the same UPDATE compute_jobs SET flag_... = 1 that the backend's own compute-reporting-routes.test.ts uses on rows the real services made. Emails are @example.org; wall-clock values are pinned as in E1.
    Fixtures under test/fixtures/compute/:

    • admin-access-list.json: a page with accounts in each of the five listed states (including a null username, a missing affiliation, a hostile purpose with markup and bidirectional characters, a 1000-character purpose, a service account), a next_after case (limit=2), the empty page, an invalid-query refusal.
    • admin-access-decisions.json: one real body per outcome: grant with allocation.granted: true; grant with policy_default_zero; a second grant with already_granted; deny; suspend; revoke; lift suspension; and the refusals not_requested, already_active, not_active, account_not_found, self_decision (an admin key on the admin's own account), account_not_in_good_standing, policy_unreadable (503), invalid_body (reason over 500), plus the middleware's own 401 and 403 (no key, a member key) and the owner-only 403 on GET /admin/compute/policy with an admin key. stale_state is captured only if the backend's test seam can force it on the real route (its decision test imports decisionFlipStatement to do so); if it cannot, the fixture is omitted, the file says why, and the test covers that 409 through the other 409 bodies. Nothing is hand-written.
    • admin-pools.json (platform, partner and account pages, a frozen pool, a negative available_milli), admin-jobs-flagged.json (one page per flag, a next_after page, a partner job with partner_flag), admin-jobs-unmatched.json, admin-access-report.json, admin-status.json (compute off, reconciliation paused, Tapis words unconfigured, an attention map with a positive count).

    9. Tests

    Vitest only, no mocks, no jsdom harness (this repo reads .astro source through ?raw).

    1. admin-tabs.test.ts: the tab is present, enabled and linked to /admin/compute; the id lists include it; adminMetricHref still returns undefined for unknown families and for compute.*.
    2. compute-admin-api.test.ts: every reader parses its fixture; a body missing a required field raises; an unknown extra key is tolerated; decideComputeAccess sends POST /api/v1/admin/compute/access/<decision>/by-id/<id> with body {} or { "reason": "..." } (trimmed, omitted when empty, the 500-length boundary) and the right headers; each captured refusal surfaces its error sentence and code; a non-JSON gateway body, upstream_unreachable, a timeout (an aborted signal) and a 500 classify as unknown_outcome; the plain 403 Admin access required (no code) classifies as signed out or forbidden.
    3. View model (pure): purpose and names as text; the 1000-character purpose is truncated at 280 with the full text reachable; a missing affiliation, city or name reads "not set"; a null username reads "no username" and offers no Users link; buttons per state exactly as the matrix (requested: grant, deny; active: suspend, revoke; suspended: lift, revoke; denied and revoked: grant again; an unknown state offers none); the own-row rule (a non-owner's own row has Grant disabled with the explanation, an owner's does not, and deny, suspend and revoke are unaffected); describeDecision for each captured success, both allocation.reason words and an unknown word; describeFailure for each code.
    4. Badge: fetchComputeRequestsCount returns null on a failed read, an aborted read and a malformed body, and never throws; it returns capped: true when next_after is non-null.
    5. Guard: adminGate asserted for /admin/compute (anonymous gets /login?next=%2Fadmin%2Fcompute, a member gets /404, an admin gets null), and a source-level check that the page calls adminGate before any fetch.
    6. test/compute-admin-ui.test.ts (source scan): no set:html, innerHTML, insertAdjacentHTML or outerHTML in any new file; no <a> or <img> inside the free-text blocks; free-text fields pass through displaySafeLine or displaySafeBody; no sentence-length string literal in a new page or component outside ACCOUNT_COPY; the dialog's confirm button is never the focus target; nothing posts more than one id per action (no select-all); ConfirmDialog.astro is unmodified.
    7. Decide-flow state machine: one in flight; a second confirm while in flight is ignored; each failure class returns to the right state; an unknown outcome causes exactly one re-read and zero repeated POSTs.
    8. Pagination helpers: after parsing (rejects 0, negative, non-numeric, huge); next and first links keep the other parameters.
    9. Pool and job row models: a negative available_milli prints negative; frozen has a word; a null account_id reads "no account"; formatSu only ever receives integers.
    10. Contract drift (commit 1), strict in CI.

    Browser check, against the local backend. Extend scripts/local-backend.mjs first: it currently seeds one owner with an API key and no cookie, and nine members. Add a signed-in localowner and a signed-in non-owner localadmin whose own compute request is requested; several requested people with varied countries and one hostile purpose; one owner PUT /admin/compute/policy with a nonzero default grant so a grant opens something; and flagged and unmatched rows made through the same real services as the capture script (where no real path yet produces a flag, say so in the PR instead of writing rows by hand).

    • as the non-owner admin: the tab and badge appear; own Grant is disabled with the explanation; granting another request needs the unticked acknowledgement, Cancel is focused first, Escape does nothing; grant it and watch the row change, the allocation note, and then Settings for that person (the E1 card) change; deny another with a reason and confirm the audit row has it (GET /admin/audit); suspend an active one and see the person's Settings card explain; revoke needs REVOKE; lift a suspension.
    • as the owner: own Grant works; nothing owner-only appears.
    • a member session gets the 404; anonymous gets the login redirect.
    • double-click Grant (one request leaves); two tabs deciding the same account (the second shows the 409 sentence and the re-read state); stop the backend mid-decision (outcome unconfirmed, then re-read after restart).
    • the hostile purpose renders as visible text with escapes, no markup, no link.
    • Pools show the new allocation; each Flagged chip shows its rows; Reconciliation shows paused or not paused and the unavailable notes; Usage shows the quarter table and the unavailable note; stop the backend and each section degrades alone.
    • light, dark, and phone width 375 px with no horizontal scroll and a 16 px gutter; keyboard only through a full grant; focus returns to the trigger.

    Gates: bun run typecheck && bun run lint && bun run test && bun run build, then the browser check.

    10. What the backend does not serve (file in nemar-cli, do not synthesize)

    File these before or with the PR and link them from the "not available yet" notes (all public-safe):

    • A: platform usage over time: SU charged by day, partition and source over a date range (the Usage table and chart).
    • B: the ledger-versus-accounting difference per job or day, with the tolerance in force, readable by an admin (the Drift section). Today the tolerance is only in the owner-only policy.
    • C: a count on GET /admin/compute/access for a state (the badge), an optional order, and a fix of the contract header comment that says "oldest request first".
    • D: on access rows, the last decision (decision, at, by, reason) so a reason can be read back, and status, email_verified and orcid_verified so the page can say before a grant that an account is not in good standing.
    • E: the compute_admin.* copy keys (prerequisite for commit 5).
    • F (optional): a single-account read, GET /admin/compute/access/by-id/:id, so the re-read after an ambiguous outcome is not the after=id-1 idiom.

    11. What waits on the missing Tapis tenant

    Nothing in Requests or Pools. Decisions are bookkeeping and read no switch, so grant, deny, suspend and revoke, the pool rows a grant opens, and the badge all work today against the local backend with no Tapis. The Tapis stand-in from Epic A (backend/test/helpers/tapis-standin.ts) is only needed to make real job rows locally; the captured and browser-checked flagged rows come from the backend's own lifecycle fixture on that stand-in.
    Blocked or empty until a real tenant exists: real unreserved, unattributed, mismatch and overrun rows from live scheduler data; real unmatched accounting rows (the observer ingests them from the supercomputer's accounting); the tapis.token and tapis.health words reading ok; reconciliation not being paused. In production before then the Flagged and Reconciliation views will correctly be empty or paused, and the page must say paused, not "none".

    12. Risks

    • A UI that grants a cost-bearing capability: a grant opens an allocation and lets the person spend. Mitigations: a dialog with the stated country and the consequences, no focused confirm, an acknowledgement for Grant, a typed word for Revoke, one decision in flight, no bulk anything, no auto-approve, and every result printed from what the backend returned.
    • Double submit and stale state: the in-flight lock, the backend's from-state guard (a repeat is a 409), and re-read-on-doubt; never an automatic POST retry. Residual: two admins deciding at once; the loser sees a 409 and the truth.
    • A 500 after a committed batch (1.1): the page must not say "failed"; it says unconfirmed and re-reads.
    • Stale lists: nothing auto-refreshes; a decided row stays in its new state until reload.
    • Hostile text: purpose, names, affiliation, country, ORCID string, username, email and failure_detail are all attacker-influenced; text nodes, displaySafe* and the source scan cover them.
    • Identity minimization: the Requests view shows what the Users review card shows (name, email, ORCID, affiliation, city, country); job, pool, usage and reconciliation views show only account numbers and fixed words.
    • Gate drift: 404 for a member and a login redirect for anonymous, asserted by test; the backend is the authority, so a loosened page gate would still be refused by the API.
    • Copy drift: new keys must exist in nemar-cli before the website transcribes them; the drift test turns red on a mismatch in either direction.
    • Epic ordering: nothing here may reach staging before the compute epic is on nemar-cli dev (the admin routes and the compute_admin.* keys are not there yet).
    • A partial Reconciliation view could be read as "the platform is reconciled": the paused banner, the "not available yet" notes and a plain-language header guard against it.

    13. Open questions for the owner

    1. Should Grant require the "I reviewed the stated country" acknowledgement (recommended), or only the confirm dialog?
    2. Do you want any of the cost-bearing admin actions in the UI this phase (account pool grants, job cancel), or CLI-only as recommended?
    3. Show the person's email on the request row, as the Users review card does (recommended), or leave it off?
    4. Ship the Reconciliation view as scoped (partial, with the unavailable notes), or hold the Drift section until nemar-cli issue B is built?
    5. May the implementer add the compute_admin.* keys to nemar-cli's account-copy.ts (a small nemar-cli PR), or should page chrome (column heads, view labels) stay as page labels with only the access-state and decision wording in the shared copy?
    6. Please confirm the one-line meanings of the four flags (unreserved: skipped the reservation; unattributed: no account could be attributed; mismatch: NEMAR's record and the scheduler's disagree; overrun: used more than its hold) before they become copy.
    7. Tab placement (after Mail) and the label "Reconciliation" for the ?view=drift view are my choices; say if you want "Drift".
    8. Job and pool rows identify accounts by number only; is plain "account #N" acceptable, or do you want an id-to-user link (which needs either a Users page that accepts an id or one extra lookup per distinct account)?
    9. Is a non-owner admin allowed to grant at all? The code allows it (except to themselves) and the issue says not to hide it from admins, so the plan keeps it.
  3. neuromechanist commented on Nov 7, 2026

    @neuromechanist
    ContributorAuthor

    Merged in #504 (46ac1d5) with copy keys in nemarOrg/nemar-cli#2089 (27eecff9).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions