Skip to content

Phase E3: Job page #496

Closed
Closed

Description

@neuromechanist

Goal

After this phase each job has a page at /compute/jobs/<id> that shows its state as it changes, its resources and charge, its logs on request, its results with download links that can be renewed, and a cancel button for a live job.
It is the page the "results ready" email links to.

Routing

Scope

In: the job page, its client script, the state timeline, failure wording, log rendering, results and renew, cancel, polling; the proxy's one header addition; tests and fixtures.
Out: submitting jobs from the page; deleting results early; re-running a job; any change to the email (a mismatch of link form is filed as an issue against nemar-cli).

Design references

Design section 7: job states table, "Status updates" (a status read refreshes a job older than a minute), "Results" (verified, links valid 7 days and renewable, objects deleted after 30 days, the email links to the job page and never to a file), "Cancellation and revocation".
Website ADR 0029 (untrusted text rendered inert), src/components/ConfirmDialog.astro, src/pages/api/v1/[...path].ts (the proxy forwards only Content-Type and cookies from upstream), src/lib/compute-api.ts and src/lib/compute-badges.ts from #495.

Changes

  • src/pages/compute/jobs/[id].astro (app host, signed-in only): SSR reads the job; a job that is not the caller's answers 404 with a plain "Job not found" page and the 404 status (the backend answers the same for absent and foreign jobs; do not distinguish them). Sections: header (name, state badge, front door), a timeline of created, submitted, queued, running, archiving and the terminal state with the times the record carries, resources and charge, the failure sentence when there is a failure code, Logs, Results, and the actions row.
  • src/lib/compute-job-view.ts (pure, tested): the timeline stages for a state, isTerminal, canCancel, the results state (not_ready, available, expiring, expired), and the polling interval (10 seconds, doubling to 60 on errors, stopped on a terminal state, paused while the tab is hidden, one immediate refresh on becoming visible).
  • Client script: refresh the job through /api/v1/compute/me/jobs/<id>; update the badge and timeline in place and announce a change through an aria-live="polite" region; stop polling at a terminal state and then offer Results.
  • src/lib/compute-failure.ts: one plain sentence per failure code in the closed vocabulary (code_fetch_failed, dataset_fetch_failed, entry_not_found, runtime_error, out_of_memory, time_limit, result_verification_failed, upload_expired, and any the backend added); an unknown code prints the raw word; each sentence points at nemar compute logs <id> where logs help.
  • Logs: a "Show logs" button fetches /api/v1/compute/jobs/<id>/logs?tail=200 as text and renders it in a <pre> through textContent. src/lib/compute-logs.ts (pure, tested) strips control characters other than newline and tab, escape sequences, carriage-return overwrites, bidirectional overrides and zero-width characters, and caps line length. The backend marks a cut log with an X-Nemar-Truncated: true header, which the proxy currently drops: add that one header to the proxy's forwarded response headers with a test in the proxy's test file (a second reader of the header must not exist elsewhere), and show a "log truncated, use the CLI for the rest" note.
  • Results: a "Get download links" button (not at page load, so that viewing a job mints nothing) fetches the results list and renders path (text), size and a link per file with rel="noopener noreferrer", the expiry date, and a "Renew links" button that POSTs the renew route and re-renders. A 410 renders the "results were deleted after 30 days" copy; the record of what was submitted and the result manifest are kept and the page says so. Show at most the plan's row cap with the total count and the CLI command for the rest.
  • Cancel: shown only where canCancel; a ConfirmDialog, then POST /api/v1/compute/jobs/<id>/cancel; on success refresh in place; on a refusal show the backend's sentence as text.
  • Copy for the new sentences goes in the transcribed copy contract if the backend owns it, otherwise in a local compute-copy.ts marked website-owned; say which in the plan.
  • Verify the page responds with Cache-Control: private, no-store and is never served from the edge cache (src/lib/edge-cache.ts, src/middleware.ts); the page can carry signed links after the button, and an edge-cached copy would share a person's page.
  • Fixtures captured from the merged backend into test/fixtures/compute/: a job in each stage (submitted, queued, running, finished with results, failed with each failure code reachable in the stand-in, cancelled), a results body, an expired-results body.

Tests (write these first)

  1. compute-job-view.test.ts: timeline per state, canCancel per state, results states around the 7-day link and 30-day deletion boundaries, the polling schedule with an injected clock. Fails if a terminal state keeps polling.
  2. compute-logs.test.ts: ESC sequences, a bare carriage return, NUL, a right-to-left override, a 1 MiB single line, and an ordinary traceback that must survive unchanged. Fails if innerHTML-significant characters are altered or if control characters pass.
  3. compute-failure.test.ts: every known code has a sentence, an unknown code prints itself.
  4. compute-api.test.ts: the job, results and renew clients parse their fixtures; a 410 maps to the expired state; a 404 maps to not-found.
  5. The proxy test: X-Nemar-Truncated is forwarded and Set-Cookie handling is unchanged.
  6. Browser check against the local backend with the Tapis stand-in: watch a job go through queued, running and finished; show logs; get links, download one, renew; cancel a second live job; open another account's job id (404); light, dark and phone width; reduced motion; a hidden tab stops polling (check the network panel).

Acceptance criteria

  • No job text (name, log, file name) is ever inserted as HTML.
  • Viewing the page mints no result link; only the button does.
  • The page is not edge-cached and carries no link in server-rendered HTML.
  • The URL form matches the one in the "results ready" email, or an issue is filed and linked.

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 is inert text; a job's output is attacker-controlled.
  • Mail links to a page, never to a file or a result URL; so the page must be safe to open from a mail client.
  • Signed links belong to one person; never cache or log them (the proxy already sets no-store).
  • Do not distinguish a foreign job from an absent one.
  • Keep [hidden] rules as :not([hidden]) in scoped styles.

Escalate to the owner if

  • The email's link form differs from the route and the fix belongs in the backend.
  • Results can be several thousand files and the planned cap loses what a person needs.

When merged

Update the architecture map in AGENTS.md; record in the epic issue the job states and failure codes the page words, so the backend's vocabulary and the page cannot drift silently.

Activity

  1. neuromechanist commented on Nov 7, 2026

    @neuromechanist
    ContributorAuthor

    Plan for Phase E3: the job page (website#496)

    Readiness was "expand", so this plan quotes the merged backend and says where it differs from the issue text; where they differ, the code wins.
    Read: Epic D branch feature/issue-2021-epic-compute-users at caf3a77a (routes backend/src/routes/compute/{index,jobs,read,shared,auth}.ts, services compute-logs.ts, compute-results.ts, compute-user-reads.ts, compute-lifecycle.ts, contracts shared/contract/{compute-user,compute-submit,compute-responses}.ts, shared/compute-state.ts, CLI src/commands/{compute-jobs,compute-read}.ts) and the merged E1 and E2 work on feature/issue-493-epic-compute-web (442be8b).
    Implementer: Sonnet.
    Nothing in this phase needs a nemar-cli change to merge; four optional nemar-cli issues are listed in section 15 and are filed first, so the page can link them.

    1. What the backend serves, quoted

    All paths are under the API; the browser reaches them through the same-origin proxy as /api/v1/compute/....
    The credential on every one of these is the session cookie (or a CLI key); a write made with a cookie also passes cookieOriginGuard, which the proxy already satisfies because it forwards origin.

    Need Route Answer
    Job GET /compute/me/jobs/:id { "job": { id, kind, source, state, app_id, app_version, partition, pool, resources: { nodes, cores_per_node, memory_mb (nullable), gpus, minutes }, created_at, started_at, ended_at, charged_milli, failure_code, cancel_requested }, "stale"?: boolean }. Times are YYYY-MM-DD HH:MM:SS UTC. private, no-store. A live job older than 60 s is read back from the cluster first (debounced per job, so polling faster than a minute adds no freshness); stale: true means that read failed and the stored record is shown.
    Log GET /compute/jobs/:id/logs text/plain; charset=utf-8, nosniff, no-store; the FIRST 1 MiB (COMPUTE_LOG_MAX_BYTES), with X-Nemar-Truncated: true when cut (COMPUTE_TRUNCATED_HEADER).
    Links GET /compute/jobs/:id/results[?after=<path>] and POST /compute/jobs/:id/results/renew[?after=<path>] One handler, identical answers: { expires_at (ISO), files: [{ path, size, sha256, url }], total, truncated, next_after, bearer_links: true, notice }, up to COMPUTE_RESULTS_PAGE_MAX (1000) files in path order, no-store. Both MINT new 7-day links; the only difference is that the POST also passes the origin guard.
    Cancel POST /compute/jobs/:id/cancel 200 { ok: true, state, outcome, cancelled }, outcome one of cancel_requested, already_cancelled, already_ended. No body, no key.

    Refusals are { "error": "<sentence>", "code": "<word>" } (plus field for invalid_spec), with the sentences and statuses of COMPUTE_ROUTE_SENTENCES, COMPUTE_SUBMIT_SENTENCES and COMPUTE_REFUSAL_STATUS:

    • job_not_found 404 "No such job." (absent, foreign, malformed id, an unreserved swept job, and an administrator who is not the owner all answer this; no route is an oracle).
    • logs_not_available 404 "The job has no log yet."; storage_unavailable 503 "Compute storage could not be reached just now; ask again shortly."
    • bad_state 409 "The job is not in a state that accepts this." (links for a job that is not finished and verified); results_expired 410 "The results of this job have expired."; compute_disabled 503 "Compute storage is not configured."; invalid_spec 400 for a malformed after.
    • 401 and 403 are authMiddleware's (readComputeError already reads both shapes).

    Failure codes a job may carry (COMPUTE_FAILURE_CODES, 17, not the 8 the issue lists): the launcher's code_fetch_failed, dataset_fetch_failed, entry_not_found, runtime_error, out_of_memory, time_limit, result_upload_failed; the rest of the platform's tapis_submit_failed, submit_timeout, staging_failed, launch_failed, archive_failed, tapis_error, result_verification_failed, records_unavailable, tapis_record_lost; and the submitter's upload_expired.
    The user view deliberately carries no fault attribution (failure_detail and platform_failure are not served), so no sentence may say whose fault a failure was.

    The "results ready" mail links to <APP_BASE_URL>/compute/jobs/<job id> (computeJobPageUrl in compute-results.ts), which is exactly this page's route on the app host, so the fourth acceptance criterion holds; a test pins the path shape (section 13).

    2. Where the issue text and the code differ

    1. The job read is GET /compute/me/jobs/:id and answers { job, stale }, not a bare job.
    2. There is no ?tail= on the log route (an unknown query is ignored). The route always returns the BEGINNING, at most 1 MiB, and X-Nemar-Truncated means "there is more AFTER this". The CLI's --tail <n> is client side over that same prefix. So the page fetches without a query, keeps the last 200 lines for display, and a log over 1 MiB shows its start, not its end. Issue (a) in section 15 asks for a server tail.
    3. The job view has no name. The header is "Job <id>" with the app and the front door (sourceLabel). nemar-cli#2079 ("carry the job name") is open; the guard reads an optional string name if it ever appears, shows it through displaySafeLine, and needs no later website change.
    4. The record carries three times only: created_at, started_at, ended_at. There are no submitted, queued or archiving times, so the timeline shows no time for them (nothing is synthesized).
    5. The issue's "which states offer cancel (from the merged refusals)": the route refuses nothing by state. bad_state is not a cancel refusal; an ended job answers 200 already_ended, cancelled: false. The only cancel refusals are job_not_found and the credential ones. The page's canCancel is therefore the page's own choice (section 8).
    6. The issue says the results list and renew return a list "of links"; the field is files (the older POST /compute/jobs/:id/links answers links and is NOT used here).
    7. The issue says "the record of what was submitted and the result manifest are kept and the page says so". No route lets a person read either, so the page says only what it can show itself: the job's record on this page (state, resources, charge) stays, and the log stays readable after the results expire (it is served from the records copy).

    3. Route, page and files

    src/pages/compute/jobs/[id].astro, app host, signed-in only, export const prerender = false as the siblings do.
    Frontmatter order: (1) session, else Astro.redirect("/login?next=" + encodeURIComponent("/compute/jobs/<id>")) (safeRedirectPath already accepts the path; add one assertion to its test); (2) set Cache-Control: private, no-store and Referrer-Policy: no-referrer (ADR 0021 keeps a page-set no-referrer) BEFORE any return, so the 404 carries them too; (3) an id that does not match COMPUTE_JOB_ID_RE is the same 404 as an unknown one, without calling the API; (4) read the job through getComputeJob(id, { cookieHeader, fetch: apiFetch }); (5) only when the job is finished, read getComputeMe for limits.results_days (its own try/catch; failure degrades the retention line to "Results are kept for a limited time", never blocks the page).

    Statuses:

    • job_not_found (by the code, not by the 404 alone): Astro.response.status = 404, plain "Job not found" with a link back to /compute; one page for absent and foreign.
    • Any other 404 (an API without the compute routes, the release gate) reuses E2's "Compute is not available on this server yet" notice.
    • 401 redirects to sign-in; 403 shows E2's "This account cannot use compute yet."; 5xx, timeout, network and shape render one notice with a "Try again" link and the page's own status stays 200 (E2's pattern).

    New and changed files:

    • src/pages/compute/jobs/[id].astro (frontmatter above, sections Header, Timeline, Resources and charge, Failure, Logs, Results, Actions, one <script>).
    • src/components/ComputeJobTimeline.astro, ComputeJobLogs.astro, ComputeJobResults.astro, ComputeJobActions.astro (contains ConfirmDialog). Each is a thin renderer over a view model; client-built nodes come from src/lib/compute-job-dom.ts (createElement and textContent only, like compute-jobs-dom.ts), with global .compute-job* styles because Astro scoped styles do not reach script-built nodes.
    • src/lib/compute-job-view.ts (pure, tested): timeline, isTerminal, canCancel, resultsWindow, cancelOutcome, resultsOutcome, nextPoll, jobDetailView.
    • src/lib/compute-job-live.ts (browser only): the poller, the one module allowed to read a clock or set a timer. E2's source scan forbids Date.now() and new Date() in every compute-*.ts; the scan gets one named exception for this file, stated in the test.
    • src/lib/compute-failure.ts, src/lib/compute-logs.ts (pure, tested), src/lib/compute-copy.ts (website-owned sentences, section 11).
    • src/lib/compute-api.ts: getComputeJob, getComputeLogs, getComputeResults, renewComputeResults, cancelComputeJob, with parseComputeJob (the E2 job() guard plus resources, plus optional name), parseComputeResults, parseComputeCancel; same copy-out-only-the-keys-read rule and shape errors, a text transport for the log that returns { text, truncated }, and a send transport for POST. The log call uses a longer timeout (30 s; the backend may read the cluster for up to about 8 s).
    • src/lib/compute-contract.ts: add COMPUTE_FAILURE_CODES, COMPUTE_CANCEL_OUTCOMES, COMPUTE_TRUNCATED_HEADER, COMPUTE_LOG_MAX_BYTES, COMPUTE_RESULTS_PAGE_MAX, and the result refusal words with their statuses.
    • src/lib/compute-view.ts: extract the charge rule inside jobRowView into one exported chargeText(job) that both the table and the detail use, so the two cannot disagree (E2's tests cover it).
    • src/pages/api/v1/[...path].ts, src/middleware.ts, the tests, fixtures and scripts of sections 12 to 14.

    4. State presentation

    Header: the job id as text, app and version, front door, the state badge (jobBadge), and "Cancel requested" when cancel_requested on a live job (same words as the table).
    The badge is the only thing that changes color; each state also has its words and icon (E2 rule).

    Timeline (an ordered list, aria-current="step" on the current one): Created, Submitted, Queued, Running, Archiving, then the terminal node (Finished, Failed or Canceled).
    uploading is shown on the Created step as the current label "Uploading" (it precedes Submitted and exists only for jobs with a code bundle).
    Because the record has three times and Tapis may skip states (the backend's forward-only table allows skipping), the timeline claims only what is known:

    • Created shows created_at; Running shows started_at as "Started"; the terminal node shows ended_at; every other step shows no time.
    • A live known state marks the steps before it as passed and itself as current. unreported is a side state with no place on the line: steps are passed through Running only if started_at is set, else only Created, and the existing compute_page.unreported_note copy is shown (reuse ACCOUNT_COPY).
    • finished: all steps passed. failed and cancelled: Created passed; Submitted to Running passed only if started_at is set; Archiving is shown with a neutral dash ("not known"), never as passed; the terminal node carries the outcome.
    • A state outside the closed ten shows the escaped raw word as the badge and a single "State: " line, no timeline.

    Resources and charge, in this order: partition and pool (CPU/GPU labels from E2), nodes, cores per node, GPUs when above zero, memory when not null (MB), "up to" the maximum run time (formatDuration(minutes * 60)), then Created, Started and Ended as formatUtcMinute in <time datetime title>, and "Charged".
    Charge: suFixed with the unit "SU" (units note from ACCOUNT_COPY["compute_page.units_note"]), so the digits match nemar compute status; a finished, failed or canceled job prints a true 0.000; a live job prints "Not charged yet" until the backend reports an amount (the CLI prints -); a state this build does not know prints its amount or "Not known". formatSu is not used on this page (it is for chart ticks).

    The failure sentence (when failure_code is set) comes from compute-failure.ts: one plain sentence per code of COMPUTE_FAILURE_CODES, an unknown code prints the raw word through displaySafeLine, and the codes where a log helps (code_fetch_failed, dataset_fetch_failed, entry_not_found, runtime_error, out_of_memory, time_limit, result_upload_failed) end with "Read the log below, or run nemar compute logs <id>." Draft sentences, neutral, no blame:
    code_fetch_failed "The job could not fetch its code."; dataset_fetch_failed "The job could not read a dataset it asked for."; entry_not_found "The job's entry file was not found in its code."; runtime_error "The job's program stopped with an error."; out_of_memory "The job ran out of memory."; time_limit "The job reached its time limit and was stopped."; result_upload_failed "The job ran, but NEMAR could not accept its result files."; tapis_submit_failed "NEMAR could not hand the job to the cluster."; submit_timeout "The cluster did not accept the job in time."; staging_failed "The cluster could not prepare the job's files."; launch_failed "The cluster could not start the job."; archive_failed "The cluster could not save the job's output."; tapis_error "The cluster reported an error for this job."; result_verification_failed "The job finished, but NEMAR could not verify its results, so they are not offered."; records_unavailable "The job finished, but NEMAR could not read the files it needs to check the results."; tapis_record_lost "NEMAR lost track of this job on the cluster and ended it."; upload_expired the backend's own sentence, "The upload window closed and the job was ended; submit it again." (transcribed from COMPUTE_SUBMIT_SENTENCES, drift-tested).

    NEVER shown, enforced by copy-out guards and a test over a response that carries extra keys: any key the guard does not name (the contract is open and may grow), the tenant or platform pool, any hold figure (the user view has none and the page must not infer one from the pool balance), Tapis or scheduler identifiers, flags, platform_failure, failure_detail, and anything about who caused a failure.

    5. Live refresh

    Only for a known, non-terminal state (isTerminal false). A terminal state, an unknown state or a dead page never starts the poller.
    Reads GET /api/v1/compute/me/jobs/<id>; in place it updates the badge, timeline, charge, failure sentence and results panel, and announces a change in a visually-hidden aria-live="polite" region ("Job is now Running."), never on an unchanged poll.

    Schedule (nextPoll(prev, outcome) is pure; compute-job-live.ts only holds the setTimeout and the AbortController):

    • First poll 10 s after load (the issue's number). Unchanged answer (same state, same cancel_requested, same charged_milli, or stale: true): double up to 60 s. A changed answer resets to 10 s. This matters because the backend refreshes a live job from the cluster at most once a minute per job, so asking every 10 s for long adds Worker and database load and no freshness.
    • Error (network, timeout, 5xx, shape): double up to 60 s as well; five consecutive errors stop the poller and show "Updates paused." with a Refresh button. A 401 stops it and shows the sign-in link; a job_not_found stops it and shows the not-found text.
    • ±15% jitter on every delay so tabs opened from one email do not align. setTimeout chains, never setInterval; one request in flight at most.
    • visibilitychange: hidden clears the timer and aborts the in-flight request; visible does one immediate refresh (if the last read is older than 5 s) and restarts at 10 s. pagehide aborts.
    • Hard stop two hours after load with "Updates paused." and a Resume button, so a forgotten foreground tab does not poll for a day.
    • On the transition to finished the client reads GET /api/v1/compute/me once for limits.results_days (same degrade rule as SSR) and offers Results.
      Tabs do not coordinate; two tabs poll independently, which the schedule makes cheap.

    Test (injected clock, no timers): a terminal state returns "stop" whatever the previous schedule; hidden returns "pause"; the doubling sequence 10, 20, 40, 60, 60; a change resets; the fifth error stops; the two-hour stop at exactly the boundary. A mutation that lets a terminal state continue must fail a test.

    6. Logs

    "Show logs" (not loaded at page load; a log read can be a cluster read). One fetch of /api/v1/compute/jobs/<id>/logs with no query, response read as text (res.text() replaces invalid UTF-8 with U+FFFD, and a cut multi-byte tail does the same, which is fine).
    States, each with its own words and role="status": loading; "No log yet" for 404 logs_not_available (for source: "partner" add that a partner job's log appears once NEMAR has checked it, which is the backend rule in readJobLog); "The log could not be read just now. Try again." for 503 storage_unavailable; the generic notices for 401, 403, timeout and network; an empty body is "The job wrote no output." (not an error).
    No automatic log refresh. A "Refresh log" button replaces the content, is disabled while a request is in flight and for 10 s after, aborts a previous request, and for a live job is the only way the log updates (each press may be a cluster read of up to 1 MiB). When the poller sees the job end while a log is shown, a note says "The job ended. Refresh the log for the final output."

    compute-logs.ts (pure): prepareLog(text):

    1. Strip complete ANSI escape sequences (CSI ESC [ ... final, OSC ESC ] ... BEL|ESC \, two-character ESC x, and the C1 CSI U+009B), as formatting, not as text; an unterminated sequence at the end is dropped.
    2. Hand the rest to the existing displaySafeBody (ADR 0029, same escape set as the CLI and the Mail tab): \r\n and bare \r become newlines (so a carriage-return overwrite can never hide text; a progress bar becomes many lines, which the tail window absorbs), newline and tab stay, every other control, bidirectional override or isolate, zero-width and invisible character is written out as a visible \x1b/‮-style escape. This differs from the issue's "strips ... bidirectional overrides and zero-width characters": the ADR's rule is to show that something hostile was there rather than silently cleaning it, and the CLI's plainLog also drops them silently. If the owner prefers silent stripping, flip it in one place (open question 2).
    3. Split into lines and cap each at 2,000 characters; a longer line is cut with a visible "[line cut: N more characters]" suffix. A 1 MiB single line is therefore one capped line.
      <, >, &, quotes and backslashes are never altered (the log is shown with textContent); a normal traceback must survive byte for byte.

    Display: a <pre> in a focusable scroll region (tabindex="0" role="region" aria-label="Job log"), white-space: pre-wrap; overflow-wrap: anywhere, monospace token, both themes. Default is the LAST 200 lines of what was returned, with "Show earlier lines" adding 1,000 at a time (set textContent of the one <pre> from a slice; no per-line nodes). A visible count "Showing the last 200 of 5,431 lines".
    Truncation: when X-Nemar-Truncated: true, a note under the log: "The log was cut at 1 MiB: this is its beginning. Use nemar compute logs <id> for the same part with --tail; the end of a longer log cannot be read yet." and the page does NOT claim "last 200 lines" is the end of the job; the count line says "of the first 1 MiB".
    Never logged: no console.* of log text or sizes; the proxy and the backend already do not log it.

    7. Results

    Section visible for every known state, with the right words:

    • Not finished (any live state): "Results appear here when the job finishes." No button.
    • failed and cancelled: "This job has no results to download." No button (the backend would answer bad_state; not worth a request).
    • finished: the retention line and a "Get download links" button. Viewing the page, the poller, and the SSR never call the results routes (a source scan fails the build if [id].astro imports getComputeResults or renewComputeResults, or if the poller does).

    Retention line (resultsWindow(ended_at, results_days, nowMs), pure): states not_ready (not finished), available, expiring (3 days or fewer left; RESULTS_EXPIRING_DAYS = 3, website-owned), expired (strictly after ended_at + results_days, the backend's own rule in resultsRetentionPassed: it uses now > ended + days, so equality is still available). With the number from limits.results_days: "Results are kept for 30 days after the job ends, until 2026-12-07 14:05 UTC." and the browser adds the local time ("your time: ..."). This derived date is the one place the page computes a backend rule; the 410 stays authoritative, and the button remains until the backend says 410. If results_days could not be read, the line is "Results are kept for a limited time." Issue (c) in section 15 asks for the server to state the date so the derivation can be deleted.

    Button flow: GET /api/v1/compute/jobs/<id>/results. On 200 render, for the first 100 files, a row each: the path as text, formatBytes(size), sha256 (first 12 characters in <code>, whole value in title), and an <a> with rel="noopener noreferrer", referrerpolicy="no-referrer", target="_blank", text "Download". href is set through one function safeResultHref(url) that accepts https: URLs and, for the local browser check only, http: on loopback hosts, and otherwise renders no link ("link unavailable"); javascript: and data: cannot get through. Header lines: "N files, total size", "Links expire (your time )", and the response's own notice text as a text node (the backend's "Anyone who holds a link can download that file until the link expires; keep them private."; not retyped on the site, so it cannot drift). There is no "copy link" control and no "copy all"; the page never writes a link to storage, the URL, the title, an attribute other than href, a log, or the clipboard.
    More than 100 rows: "Show 100 more" (client side, from the page already held). When the held page (up to 1,000 files) is used up and next_after is non-null: "N more files. Get the next links", which GETs ?after=<next_after> (the cursor is opaque; passed back through URLSearchParams). Always show "To download everything, run nemar compute results <id> --download <dir>": it pages, verifies sizes and checksums, and sends no NEMAR credential to the store. This answers the issue's row cap and its escalation: nothing is lost because every file is reachable by cursor, and the contract allows up to 100,000 outputs, so the CLI is the recommendation for large sets (note in open question 7).
    Renew: "Renew links" POSTs /api/v1/compute/jobs/<id>/results/renew (and ?after= to renew the page being shown) and replaces the rows; double-click safe (button disabled while in flight; the call is idempotent, each answer is a fresh set). After expires_at passes (checked on visibilitychange and on click), rows are replaced by "These links have expired. Renew them." (no stale links stay in the DOM).
    Errors: 410 results_expired shows "The results of this job were deleted after N days. This page keeps the job's record (state, resources and charge) and its log." (N from results_days or omitted), removes the button and sets the expired state; 409 bad_state shows "NEMAR has no result files for this job."; 404 job_not_found switches to the not-found text and stops the poller; 503 shows the backend sentence; timeout and network say it could not be reached and keep the button.
    Leaving: pageshow with persisted clears the list back to "not fetched" (bfcache must not restore live links; the document is no-store, which already blocks bfcache in Chromium, but a test of the handler is cheap). Links die with the page: the list lives only in memory.
    Link life versus retention: a link minted late can outlive the files (7 days of link life against the retention date). When expires_at is later than the retention date, add "The files may be deleted before these links expire."

    8. Cancel

    canCancel(job): true only for a known non-terminal state (created, uploading, submitted, queued, running, archiving, unreported) and cancel_requested === false. Never for a terminal state, an unknown state, or when a cancel is already recorded (the page then shows "Cancel requested").
    All sources are offered the button, partner included: the backend records the intent for a partner reservation and resolves it itself.
    Flow: button opens ConfirmDialog (dialogId="compute-cancel", danger tone, via the existing nemar:open-confirm-dialog and nemar:confirm-dialog-confirm events) with the words "This stops the job. A job that has not started costs nothing. A job that is running is charged for the time it used. This cannot be undone." (the CLI's own statement of the charge rule; no refund is promised anywhere, matching the owner's decision that nothing is refunded automatically). Then one POST /api/v1/compute/jobs/<id>/cancel with no body.
    Double submit: a module-level busy flag plus disabled and aria-busy on the button, the dialog closes on confirm, and the backend is idempotent in effect (a repeat answers already_cancelled or cancel_requested again). Focus returns to the status region, because the button is removed after a successful cancel.
    Outcome words (pure cancelOutcome(response); the website words them, the codes are the backend's):

    • cancel_requested, state still live: "Cancel recorded. NEMAR stops the job shortly, and this page updates." Poll again at 10 s.
    • cancel_requested or already_cancelled with state: "cancelled": "The job was canceled." and the refreshed charge is shown ("Charged 0.000 SU" or the amount).
    • already_cancelled while a cancel is recorded: "A cancel was already recorded for this job."
    • already_ended, cancelled: false: "The job had already ended (); nothing was canceled." and the page refreshes the job (it may have just finished, so Results appear).
    • cancelled absent (an older Worker) is read from outcome.
    • Network or 5xx: "Could not tell whether the cancel went through. Checking the job." and one immediate re-read, because cancel_requested in the job view tells the truth; if it is true, show the recorded outcome, else offer the button again. 404 switches to not-found; 401 to the sign-in link; 403 shows the backend sentence.
      What the person is told about charges is exactly the dialog sentence plus the real charged_milli after the refresh; the page never computes or promises an amount.

    9. Honest states

    • unreported: badge plus the shared compute_page.unreported_note; cancel offered; the poller continues (it may resume).
    • source: "partner": shown as "Partner site" (E2). Logs say the log is available once NEMAR has checked the job; results say the same when the backend answers bad_state. The page cannot see the backend's partner_state, so it never says "unverified" or "verified".
    • stale: true: "This may be out of date: the cluster could not be asked just now." (the CLI's meaning, website-owned wording); cleared on the next fresh read.
    • Compute switched off or the person suspended: the job routes work for the owner in every access state, so the page does too; no access-state gating beyond sign-in.
    • A job the backend lists in the table but answers 404 on (an unreserved swept job is hidden from both) cannot occur; if it does, it is the one not-found page.

    10. Layout, keyboard, motion, themes

    Single column inside compute-shell (max 64 rem, 16 px gutter); the timeline is a horizontal row from 720 px up and a vertical list below; summary rows are a definition list that stacks below 640 px; result rows stack path over size/checksum over the Download link below 640 px; the log and the results list are focusable scroll regions, never a horizontal page scroll.
    Every control is a real <button> or <a> with a 44 px minimum target; Show logs, Get links, Renew, Cancel and the dialog are keyboard operable; the dialog is the native <dialog> (focus trap, Escape cancels); live regions: one polite region for state changes, one role="status" per section, role="alert" only for errors.
    Tokens only (--admin-* tones through .compute-badge, --color-*, --space-*), light and dark equal; the current timeline step has a shape and the word, not color alone; forced-colors keeps a border. Under prefers-reduced-motion: reduce there is no pulse or spinner animation (a static "Loading" word). Scoped styles that touch [hidden] use :not([hidden]) for the display rule.

    11. Copy ownership

    Backend-owned and shown as served: every refusal sentence (error), the results notice, the unreported note (ACCOUNT_COPY["compute_page.unreported_note"]) and the units note (compute_page.units_note). upload_expired's sentence is transcribed from the backend contract and drift-tested.
    Website-owned, in compute-copy.ts (a header comment says so) and compute-failure.ts: the failure sentences, the state descriptions on the timeline, the log and results notes, the cancel dialog and outcome sentences, "Updates paused.", the stale note. The CLI says the same things for cancel, logs and results in its own strings today (src/commands/compute-jobs.ts), and its status command prints the raw failure code; no sentence of this page exists in nemar-cli's account-copy.ts, so there is no key parity to maintain in this phase, and no cli. key is needed.
    If the owner wants the cancel and log sentences shared with the CLI (ADR 0045's "one thing"), the cheap path is a copy-only nemar-cli PR like #2082 followed by a transcription here; I recommend deferring it (open question 3). E2's scan test (sentences only in compute-labels.ts or ACCOUNT_COPY) is extended to allow compute-copy.ts and compute-failure.ts, and still forbids a long sentence in a page or component.

    12. Contract transcription and drift

    Add to compute-contract.ts (leaf, imports nothing): the 17 failure codes (split launcher, platform, submitter as the source does, so a code that moves category still passes), COMPUTE_CANCEL_OUTCOMES, COMPUTE_TRUNCATED_HEADER, COMPUTE_LOG_MAX_BYTES, COMPUTE_RESULTS_PAGE_MAX, and the result refusals (results_expired 410, bad_state 409, logs_not_available 404, storage_unavailable 503, compute_disabled 503, invalid_spec 400).
    Extend test/compute-user-contract-drift.test.ts and test/compute-contract-drift.ts (text extractors over nemar-cli shared/compute-state.ts, shared/contract/compute-submit.ts and compute-responses.ts) so a moved word fails CI instead of rendering as an unknown pill.

    13. Proxy, caching and the mail link

    src/pages/api/v1/[...path].ts: forward ONE more response header, the value of COMPUTE_TRUNCATED_HEADER (import the constant; the literal x-nemar-truncated appears nowhere else, which a source scan asserts, so "a second reader" cannot exist). Cache-Control stays hard-coded no-store and Set-Cookie handling is unchanged. Tests next to test/api-proxy-error-body.test.ts: the header is forwarded when present and absent when the upstream has none; an upstream Cache-Control: public still answers no-store; Set-Cookie copy is unchanged; the log body is not altered.
    Edge cache: the middleware already skips the cache when a session cookie is present and wraps public HTML as private, and the page sets private, no-store. As belt and braces, add /compute to routeBypassesEdgeCache (today only /oauth), so even an anonymous login redirect or a mistaken header can never enter the shared cache; a middleware.test.ts case covers /compute and /compute/jobs/job_<24 hex>, with and without a cookie.
    Mail link: the only entry from mail is a GET of the page, which for a signed-out reader (or a link scanner) is a login redirect with no job data; nothing in the HTML names a result. A test asserts the route shape /compute/jobs/<COMPUTE_JOB_ID_RE> and that signed-out requests get the next= redirect.
    The server-rendered HTML carries no link or url: the SSR frontmatter never imports the results or log client, and a source scan enforces it.

    14. Fixtures and capture

    New scripts/capture-compute-job-fixtures.mjs, same pattern and provenance blocks as capture-compute-read-fixtures.mjs; commit and command named in the test header. All bodies come from the REAL router: job rows through readApp(...).call('/me/jobs/<id>') over insertJob rows (one per state, 17 failed rows one per failure code, a cancel-requested live job, a stale job if reachable); log, results, renew and cancel through the lifecycle fixture (startLifecycleFixture, the Tapis stand-in and the object-store stand-in) and makeRoutesApp(), as backend/test/compute-results-routes.test.ts and compute-jobs-person-routes.test.ts do.
    Files under test/fixtures/compute/: job-<state>.json (ten) or one jobs-detail-all-states.json, job-failure-codes.json, job-cancel-requested.json, job-stale.json, logs-live.json and logs-ended.json (status, headers, text), logs-hostile.json (the hostile bytes are written to the log object store by the script, then read back through the real log route), logs-truncated.json (headers and byte length only; the test builds the 1 MiB body), results-page.json, results-renewed.json, results-expired.json (the real 410), results-bad-state.json, cancel-requested.json, cancel-already-cancelled.json, cancel-already-ended.json, errors-job.json (404, 401, 403).
    Step 0 is a one-hour spike: confirm the capture script can import the lifecycle fixture outside bun test (it needs only a type import from bun:sqlite). If it cannot, run the same capture inside a throwaway test file in a nemar-cli worktree that writes the bodies, and say so in the PR; do NOT hand-write fixtures or mock a route. Captured presigned URLs point at the local object-store stand-in and expire; they contain test signatures only, and a test asserts no fixture contains a production host.

    15. What the backend does not serve (file in nemar-cli first, link from the code comments; do not synthesize)

    (a) Logs: a tail (last N lines or bytes) on GET /compute/jobs/:id/logs; today a log over 1 MiB shows only its beginning, which is the wrong end for a failure, and the CLI has the same limit. The issue text assumed ?tail=200.
    (b) Results links: presign with response-content-disposition=attachment, so a text or JSON result downloads instead of rendering in the browser (a cross-origin download attribute is ignored, and an HTML result would run in the store's origin).
    (c) Job view: results_expires_at (or results_kept_until), so the page need not derive the date from ended_at and the policy's results_days. Optional and low priority.
    (d) Job view: per-stage times (submitted_at, queued_at, archiving_at) if the owner wants a complete timeline; today only three times exist. Optional.
    Existing: nemar-cli#2079 (job name), #2078 and #2080 (E2's).

    16. Tests (write first)

    Vitest only, real-shaped inputs from the fixtures, no mocks; helpers are pure.

    1. compute-job-view.test.ts: timeline for each of the ten states, an unknown state, unreported with and without started_at, failed and cancelled with and without started_at; canCancel for all ten states, an unknown state, and cancel_requested; resultsWindow at ended+days minus 1 ms, exactly ended+days (still available, the backend's strict >), plus 1 ms (expired), the 3-day expiring edge, a null ended_at, and a policy value that is missing; cancelOutcome for every (outcome, state, cancelled) row of section 8; nextPoll as in section 5, with an injected clock; chargeText for terminal, live and unknown states.
    2. compute-logs.test.ts: ESC colors and cursor moves and an OSC hyperlink removed and the visible text kept; an unterminated ESC at the end; a bare CR (becomes a line break, nothing hidden); CRLF; NUL, U+0007 and U+0085 written out; U+202E and U+2066 written out; zero-width space written out; a 1 MiB single line capped at 2,000 characters with the marker; a line of exactly 2,000 untouched and 2,001 cut; <script>, &amp;, quotes and backslashes unchanged; an ordinary multi-line traceback identical after the pass; the tail window of 200 and the earlier-lines step; invalid UTF-8 handled.
    3. compute-failure.test.ts: every one of the 17 codes has a sentence (the list comes from compute-contract.ts), the seven log codes mention the log, the other ten do not claim a cause, an unknown code prints itself escaped, an empty string and a hostile code (control and bidi characters) print escaped.
    4. compute-api.test.ts: getComputeJob parses every state fixture and the failure-code fixture; an extra key is not copied out; a missing key or wrong type is a shape error, never zeros; stale; the log client returns { text, truncated } from the header and a missing header is false; results, renew and cancel parse their fixtures; 410 maps to the expired outcome, 409 to not-ready, 404 with code job_not_found to not-found and a 404 without it to unavailable (the release gate), 401 to session; after is URL-encoded; the POST sends no body and no key.
    5. api-proxy tests (section 13).
    6. test/compute-job-ui.test.ts (source scan in the style of compute-dashboard-ui.test.ts): no innerHTML, outerHTML, insertAdjacentHTML, document.write, DOMParser, createContextualFragment, set:html in any job file; no localStorage, sessionStorage, console. with log or link variables, location.hash, history. or clipboard in the results and log code; the page sets private, no-store and Referrer-Policy: no-referrer before the first return; the page does not import the log or results clients; rel="noopener noreferrer" on result anchors; safeResultHref is the only place .href is assigned; no job-page file reads a clock except compute-job-live.ts; ConfirmDialog is used for cancel.
    7. Middleware cases (section 13) and an auth.ts case for safeRedirectPath("/compute/jobs/job_...").
    8. Mutation-worthy rules, each with a test that fails if the rule is deleted: terminal stops polling; hidden pauses; the strict > retention boundary; canCancel false for terminal and for cancel_requested; ANSI stripped but following text kept; the link scheme guard; the header forwarded exactly once; no extra key copied.
      Gates: bun run typecheck && bun run lint && bun run test && bun run build.

    17. Local browser check (desktop and phone width, light and dark, reduced motion)

    Needs a local backend that has the object stores and the Tapis stand-in. scripts/local-backend.mjs today seeds a SQLite database only, so extend it (flag --seed-compute-jobs, no stand-ins of routes: the backend's own lifecycle fixture supplies the Tapis stand-in and object stores) in step 0 and document it in .context/local-backend.md. If that spike fails, stop and escalate; do not substitute a mock backend.
    Checklist, recorded in the PR: (1) open a seeded job in each state; (2) watch a job go queued, running, finished with the badge, timeline and aria-live announcement updating in place; (3) Network panel: polling stops at the terminal state, stops when the tab is hidden, resumes with one immediate request, and backs off from 10 s to 60 s when nothing changes; (4) Show logs for a live and an ended job, the hostile log (escapes visible, nothing executes), the "No log yet" state, Refresh log, the truncated note (a seeded log over 1 MiB); (5) Get download links, check the list, download one file, Renew, wait for or fake-advance expiry only through a seeded short window, confirm no link appears in the page source, the URL, history, storage or the console; (6) a second live job: cancel from the dialog, double-click the confirm button (one request), the three outcome sentences (cancel a job twice; cancel an already ended job from a stale tab); (7) another account's job id and a malformed id: the same plain 404; (8) a signed-out request to the job URL goes to login with next; (9) a stale job shows the stale note; (10) keyboard-only run through every control and the dialog, focus after cancel; (11) 360 px wide: no horizontal page scroll, targets 44 px; (12) both themes and prefers-reduced-motion; (13) the response headers of the page: Cache-Control: private, no-store, Referrer-Policy: no-referrer, no x-nemar-cache: HIT.

    18. Risks

    • Bearer links in the DOM: the only exposure is the open page and browser extensions; mitigations are the click-only mint, no storage or clipboard, no-store document, pageshow clearing, the expiry replacement, and a source scan. A link in a URL, the page URL itself, or any log would be a defect; the page URL carries only the job id.
    • Caching: the proxy hardcodes no-store; the page is private; /compute bypasses the edge cache; the backend sends no-store on logs and results itself.
    • Leakage across accounts: every read is the visitor's cookie to the owner-only routes; the page keeps no module-level cache of jobs or links (the poller and results state are per page instance); the 404 is one page for absent and foreign.
    • Polling cost: one cheap read per 10 to 60 s per foreground tab, a backend that debounces cluster reads to once a minute, jitter, hidden-tab pause, error cap and a two-hour stop. The GET can itself finish a job (the backend refreshes on read), so the page may be the first to see finished.
    • Log size and hostile text: bounded at 1 MiB by the backend, line cap and windowed display here, textContent only, visible escapes.
    • Presigned links open inline for some content types until issue (b) lands; they open in a new tab so the page is not lost.
    • The derived retention date could disagree with the object store's own deletion by a day or so; the line states the backend's rule and the 410 settles any disagreement.

    19. Tapis dependency

    The page reads only the nemar-cli routes above, so it needs no Tapis of its own. A live job's GET /me/jobs/:id refresh needs the Epic A client; with no Tapis configured the refresh fails and the answer is stale: true, which the page shows honestly. The browser check uses the Epic A Tapis stand-in through the lifecycle fixture (section 17), so a job can be driven through submitted, queued, running, archiving and finished; the failure codes other than the launcher's are exercised by captured rows. Phase E3 can merge into the epic branch before the real tenant is wired.

    20. When merged

    Update the architecture map in AGENTS.md (new page, components, the five lib modules, the proxy header); add an "E3" addendum to ADR 0030 (bearer links are minted only by a click and never stored or logged, the log is inert text with visible escapes, the polling schedule and why it backs off, the derived retention date and where it is settled by the 410); record in the epic issue the ten job states, the 17 failure codes and the three cancel outcomes the page words (so a backend change shows up as a drift-test failure and a checklist item), and close #496 by hand with the merge commit (closing keywords do nothing on a non-default branch).

    21. Order of work

    1. Spikes: lifecycle fixture outside bun test; local backend with stand-ins (sections 14 and 17). File the four nemar-cli issues.
    2. Contract additions and drift extractors; fixtures captured; commit.
    3. Pure modules with their tests first (compute-job-view, compute-logs, compute-failure), then compute-api clients and tests; commit each.
    4. Proxy header and middleware bypass with tests.
    5. Page, components, DOM builders, poller; source-scan test; local browser check; fix.
    6. AGENTS.md, ADR addendum, PR with the check list; one review round.
      Atomic commits under 50 characters, no emojis, no co-author lines; never edit the version.

    22. Open questions for the owner

    1. Polling: the issue's 10 s start is kept, but it backs off to 60 s while nothing changes because the backend refreshes a job at most once a minute. Is a 60 s ceiling and a two-hour stop acceptable?
    2. Hostile characters in logs: show them as visible escapes (ADR 0029 and the Mail tab) or strip them silently (the issue and the CLI)? The plan chose visible escapes and strips only ANSI formatting.
    3. Cancel and log sentences: keep them website-owned now, or add copy-only keys to nemar-cli (like #2082) so the CLI and the page say one thing? The plan keeps them website-owned.
    4. Cancel for a partner-source job is offered like any other; the backend records the intent and resolves it. Should the page hide it for partner jobs instead?
    5. The retention date is derived from ended_at and limits.results_days until nemar-cli serves it (issue c). Acceptable, or wait for (c)?
    6. A log over 1 MiB shows its start only until (a) lands; is that acceptable for the first release, or should E3 wait for a tail?
    7. A job can have up to 100,000 outputs. The page pages by cursor (1,000 at a time, 100 rows shown) and points to nemar compute results --download; is that enough for the web, or should the web offer a bulk path?
    8. Add /compute to routeBypassesEdgeCache (one line, section 13)? It is not required by the issue.
  2. neuromechanist commented on Nov 7, 2026

    @neuromechanist
    ContributorAuthor

    Merged in #507 (41299d4). Gap issues: nemar-cli#2094 to #2097.

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