Skip to content

fix: release, CI, dashboard and docs fixes for 0.3.0 (#120–#132) - #153

Merged
vyncint merged 14 commits into
mainfrom
pr/030-ux
Nov 18, 2026
Merged

vyncint merged 14 commits into
mainfrom
pr/030-ux

Conversation

@vyncint

@vyncint vyncint commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Release, CI, dashboard and docs fixes from the 0.3.0 review, one commit each, with the before/after evidence in each commit body.

Release and CI

Dashboard and TUI

Docs

Two commits come from rebasing onto main. One makes the README's new SECURITY.md link absolute, which the new gate caught. The other pins gpu.yml's checkout comment to v7.0.1, as #138 did for every other workflow.

Locally on this branch: fmt, the TUI suites, the operator-stats test, the runtime library tests, metrics clippy, workspace clippy, crate-metadata, release-scripts, ci-scripts (47 tests) and zizmor all pass.

Closes #130
Closes #131
Closes #127
Closes #128
Closes #120
Closes #121
Closes #123
Closes #126
Closes #122
Closes #129
Closes #132

…eline

release.yml looked oxidelake-core up on crates.io and set found=true only
for HTTP 200; any other answer took the "Skip (first release, no
baseline)" branch and the cargo-semver-checks action did not run. Every
crate has been published since 0.1.0, so a 429 or a 503 switched the
gate off before `cargo publish`, with a green job.

Before: the step verbatim against a local stand-in for crates.io
  200 -> found=true   404/429/503 -> found=false, exit 0 (check skipped)

The lookup is now .github/scripts/crates-io-baseline.sh, run as an
unconditional step, and the semver action has no `if:` left:
  200            pass
  404            fail at once (a wrong name or a crates.io fault; there is
                 no first release left to skip for)
  429, 5xx, 000  retried (4 attempts, 20 s apart), then fail
  anything else  fail
It is a script rather than an inline step so ci-scripts can run it;
release.yml already runs extract-changelog.sh from the tag's tree the
same way, so a re-run at a tag finds the script that tag shipped.

Tests (make ci-scripts, SemverBaselineTests): a ThreadingHTTPServer on
127.0.0.1 port 0 answers scripted statuses. 200 passes after one request;
503, 429 and 500 fail after 3 requests; 503,429,200 passes after 3; 404,
301 and 403 fail after one; a closed port fails with HTTP 000; and the
semver job in release.yml calls the script and has no `if:`.
Broken once each: the base commit's release.yml fails the workflow test;
a script that accepts 429/5xx/000 fails five tests. Both restored, green.

docs/RELEASING.md step 3 said the check is "skipped on the first
release"; it now says it is never skipped and what a failure means.
docs/verification.md lists the new ci-scripts coverage.

Closes #130

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
binaries.yml's re-run guard looked for a target's versioned archive
only. A run that uploaded the archive and then failed (four sequential
`gh release upload`s) left the .sha256 and the unversioned alias missing,
every re-run said "already attached — nothing to build", and the formula
job then failed on the missing checksum for good. Its own guard for that
case never printed: under `set -euo pipefail` the 404 ended the step
before `::error::no checksum for <target>` ran.

Before (BinariesRepairTests on the base workflow, steps run verbatim
against a fake `gh` whose release is a directory): 9 failures; the
partial case printed "oxidelake-0.3.0-x86_64-unknown-linux-musl.tar.gz
is already attached to v0.3.0 — nothing to build".

Now "Already on the release?" checks all four files and sets
state=complete|repair|build:
- complete: nothing runs.
- repair (archive or alias attached, something missing): the new
  "Recover the missing files from the attached archive" step downloads
  whichever copy is attached and recomputes the rest from those bytes.
  It never rebuilds: a rebuild does not reproduce the published archive,
  so its checksum would describe a file nobody can download.
- build: as before.
- a checksum attached with no archive at all fails with the command to
  delete it, since no rebuild could match it.
Attach derives the names itself (the GITHUB_ENV hand-off from Package
is gone) and runs whenever the state is not complete. The formula's
`sum=$(curl … | awk …)` gets `|| sum=""` so its error names the target:
against a local 404 it used to exit 22 silently, now it prints
"::error::no checksum for x86_64-unknown-linux-musl" and exits 1.

The steps stay inline: the job checks out the tag, and a re-run
dispatched from main against an older tag would not find a script that
tag predates. test_ci.py extracts them from the workflow text.

After: 6 tests green — archive-only is completed (alias bytes equal the
archive, both .sha256 lines match their bytes) and a second run says
complete; each single missing file is restored without changing the
three attached ones; a complete target uploads nothing; an empty release
builds; a checksum-only release fails; the build steps are gated on
state == 'build', recover on 'repair', attach on != 'complete'.
actionlint and zizmor --persona=pedantic (online): no findings.

docs/RELEASING.md now says what a re-run does per state;
docs/verification.md lists the coverage.

Closes #131

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
`oxide tui --table Trips=PATH` registers the table through DataFusion's
`TableReference::from(&str)`, which parses the name as a SQL identifier
and folds it to `trips`. profile_table then quoted the name as typed,
`"Trips"`, which is case-sensitive, and query_dashboard propagated the
planning error, so the dashboard died after the user's query had run.
The quoting came from the 2026-09-02 audit's S6 fix, which did not match
the registration's normalisation.

Before (new test a_table_named_in_upper_case_is_profiled, Parquet demo
table registered with session.register_parquet as the CLI does):
  Plan("table 'datafusion.public.Trips' not found")

Fix: quote the reference as registration resolved it,
`TableReference::from(table).to_quoted_string()`: the same parse, then
each part quoted where it needs it with `"` doubled. A name that does
not parse as an identifier falls back to the raw string on both sides,
so the two still agree.

The test also covers the two names S6 is about: `trip data` (no
identifier at all) and `a"b` (a quote that would end a naively quoted
name). All three profile five columns with id max 299. Broken once by
interpolating the name unquoted: `--table trip data` fails with "table
'datafusion.public.trip' not found" (parsed as table `trip` alias
`data`). Restored, green; cargo clippy -p oxidelake-runtime
--all-targets -D warnings clean.

Closes #120

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
profile_table decided which columns get min/max with
`matches!(Int64 | Float64 | Utf8)`. DataFusion 55 reads Parquet strings
as Utf8View, so the demo table's own `s`, read the way `oxide tui
--table` reads it, showed `min="" max=""`, as did every other integer
width, float32, decimal, date, timestamp, boolean, LargeUtf8 and list.

Before (new tests, run on the unchanged function):
- every_column_min_and_max_can_order_gets_them: `s` (Utf8View, from
  Parquet) has empty min/max.
- the_other_type_families_are_profiled_and_a_map_is_left_out: i32, u32,
  f32, decimal(10,2), date32, timestamp(ms), boolean, LargeUtf8 all
  `("", "")`.

Fix: min_max_applies() asks DataFusion's own MinAccumulator and
MaxAccumulator to take an empty array of the type. The signatures
cannot answer it (both functions' coerce_types accept any type) and a
list kept here drifted once already. A type they cannot order must be
left out rather than tried: broken once by returning true for every
type, the test fails with DataFusion's
  Internal("Min/Max accumulator not implemented for type Map(...)")
and the whole profile is lost. Restored, green.

Quantiles now apply to every `DataType::is_numeric()` type (integers,
floats, decimals), which approx_percentile_cont coerces to Float64; the
test asserts quantiles exist exactly for the four numeric columns. The
positional layout became named slots, so a column with quantiles but no
min/max could not read the wrong cells.

After: s shows its smallest and largest string, emb (FixedSizeList(8 x
Float32)) a lexicographic min/max vector, i32 -3/7 with 1 null,
decimal -3.00/12.50, date32 2019-04-14/2023-05-23 (checked against
Python's date arithmetic), the Map column no min/max and its 1 null.

Cost: emb's min/max uses DataFusion's generic per-row path. On a
1M-row demo table in a debug build, `SELECT min(emb), max(emb)` took
310-370 ms against 80 ms for the rest of the profile; release is
several times faster, and it runs once per dashboard.

Closes #121

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
query_dashboard merged the hub's operator entries by name and gave
every plan row of that name the merged snapshot. The hub registers one
entry per exec instance, so any plan with two operators of one name (a
self-join's two filters, a union's two aggregates) showed each the sum
of both.

Before (new test two_operators_with_one_name_keep_their_own_counters:
the reviewer's query on a 3000-row Parquet demo table, CUDA placement,
truth from a CPU session's own counts):
  k < 4: OperatorSnapshot { rows_in: 6000, rows_out: 1580, .. }
  expected (3000, 129); the k >= 50 filter likewise, expected 1451.

A hub entry carries id, name and backend only, and registration order
is execution order (partitions spawn), so no reading of the hub alone
can pair entries with plan rows. The pairing has to come from the node:
the four Gpu*Exec types gain `pub fn operator_stats(&self) ->
Option<OperatorSnapshot>` (each at the end of its inherent impl, with a
fully qualified return type so no `use` line moves; agreed with the
lead and fx-compute), backed by `ExecConfig::operator_stats`, which
snapshots the instance's own OnceLock'd hub entry. dashboard.rs now
reads each node's counters in the same pre-order walk that builds the
plan rows (plan_rows; plan_summary keeps its signature), so the two can
never misalign; the HashMap merge is gone.

After: k < 4 reads (3000, 129) and k >= 50 (3000, 1451); the join's
rows_out equals a CPU count of the join; a second query's
GpuVectorDistanceExec reads (3000, 3000). The vector query keeps `emb`
in its projection: only that shape lowers, by design (placement.rs
336-375); `SELECT id, l2_distance(...)` stays a ProjectionExec on the
published 0.2.0 binary as on this branch.

crates/oxidelake-compute/tests/operator_stats.rs (new file): two filters
on one hub each read their own rows (100 in, 4 / 50 out) and ids; None
before execution and without a hub. Broken once by making
ExecConfig::operator_stats return None: the test fails at the unwrap.
Restored, green. clippy -p oxidelake-compute -p oxidelake-runtime
--all-targets -D warnings clean.

STATUS's decision note said counters are "aggregated per operator name
across partitions"; it now says what is read and why. CHANGELOG: the
four methods under Added, the fix under Fixed.

Closes #123

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
run_terminal created AppState::new(model.plan().len()) once, before the
loop's first refresh, and never told it again. Its rustdoc invites a
refresh that pulls live telemetry; one that supplies the plan or grows
it left the selection bounded by the old length, so Down could not reach
the new operators (with an empty start, could not move at all), and a
plan that shrank left the selection on a row that no longer existed.

The loop moved into a private event_loop(model, refresh, draw,
next_event) so a test can drive it without a terminal; run_terminal
passes draw_frame and next_event(tick), which polls for `tick` and reads
as before (the refactor came from the previous WIP draft). After every
refresh the loop now calls the new AppState::set_node_count, which takes
the count and moves the selection to the last row left when its row is
gone; the focused panel is kept. It is public (additive) because AppState
and render are public too, and a caller with a loop of its own had no
way to tell the state the plan changed short of a new AppState, which
loses the selection and the focus.

Before (new tests in app.rs, run on the extracted but unfixed loop):
  a_plan_the_refresh_brings_can_be_walked_to_its_last_operator:
    selections drawn [0, 0, 0, 0], want [0, 1, 2, 2]
  a_plan_that_shrinks_keeps_the_selection_on_it:
    "drew a selection outside the plan: 2 of 1"
and in a real PTY (termlens, 120x40, a probe running run_terminal with a
50 ms tick and a refresh that installs demo_model() into an empty model,
then Down twice): the Inspector still read `rows in 812400`
(GpuAggregateExec); the selection did not move.

After: both tests and the new state test
a_new_node_count_moves_the_bound_and_keeps_the_panel pass; the same PTY
probe reaches DataSourceExec (`8.0 MiB`). The probe was investigation
only and is not committed.

Broken once each: without the clamp in set_node_count, the shrink test
and the state test fail ("2 of 1"; left 2, right 1); with a loop that
ignores q, the test helper fails with "the loop did not quit on q"
instead of spinning (the draft's helper answered q forever past the end
of its inputs, which would have hung). Restored, green.

`oxide tui` passes no refresh and was not affected. cargo test -p
oxidelake-tui (all 31) and clippy -p oxidelake-tui --all-targets
-D warnings clean.

Closes #126

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
The Describe table asked for 62 cells (fixed widths 8,8,7,7,7,6,6,6 and
seven gaps) whatever it held. Inside its border the panel is 38 cells at
80x24 and 58 at 120x40, so ratatui squeezed every column below the width
its cells had been fitted to and cut them with no mark. The Inspector and
Telemetry were 45% of the body, which cut their last lines below 28 and
26 rows.

Before (the new tests, run on the base render.rs):
- at_80x24_the_numbers_are_exact_and_no_line_is_lost: v's row read
  ("colu","v") ("type","Floa") ("nul","769") ("p99","23.7"); 76923 nulls
  drawn as 769.
- describe_never_draws_a_number_it_cut: "demo at 80x24: a header was cut,
  renamed or reordered".
- a_small_value_is_never_rounded_to_zero: fit_number("-0.000012345678",
  7) returned "-0".

Now:
- Each column is as wide as its header or its widest cell (cells are
  still fitted to the old caps first, so a number is rounded, never cut).
  Columns are kept in priority order (nulls, min, max, p50, type, p99,
  p25; the name always) while they fit, and the title names the rest:
  "Describe (hidden: p99)" for the demo at 80x24. The draft this started
  from instead dropped the least important column until the rest fit,
  which hid p25 at 80x24 although it fits once p99 is gone (38 of 38
  cells); describe_keeps_columns_by_priority_and_always_the_name pins it.
- fit_number takes, of the fixed and exponent forms that fit, the one
  closest to the value, and never one 100% off it (zero; or 0.001 for
  0.0005). With no room for any other form the cut is marked with "…".
- The Inspector gets Min(12) rows (its ten lines and border), Telemetry
  Min(11) (three two-row gauges, three lines, border). From 40 rows up
  the 45% already gave both that much, so 120x40 keeps its layout.

End to end: the README's `oxide tui -q "SELECT k, SUM(v) FROM t WHERE k
>= 2 GROUP BY k" --table t=data/ --target cuda` over the seed-42 1M-row
table, driven at 80x24 by `termlens inspect` on this build, shows id max
999999, k nulls 19880, v nulls 24830, "Describe (hidden: type p25 p99)"
and "cpu fallback 1 / 1" (the issue measured 9999 and 198 on 0.2.0).

Broken once each, all red, restored green: the Inspector back at 45%
("`H2D / D2H` is not on screen at 80x24"); Telemetry back at 45% ("`spill
on the query path` is not on screen"); no column hidden (cells squeezed:
the integration and unit tests fail); a title without the hidden list
("a column left out must be named"); no 100% filter (width 4 gave "-0");
the first form that fits instead of the closest ("0.001" for
0.0005000000001); the drop-until-it-fits loop (p25 hidden at 38).

tui_pty_test::moving_the_selection_leaves_the_right_half_alone wrote the
Inspector body down as rows 14..=21. The Inspector now starts two rows
higher, so the test reads its rows off the screen instead (from under its
title to above its bottom border).

Snapshots, edited by hand; rows are 0-based screen rows.

80x24, five files: tui_render_test initial_frame_80x24 and
selection_moves_and_panels_cycle, tui_pty_test
demo_renders_navigates_resizes_and_quits (and -2), and
the_first_frame_carries_its_colours_too. Rows 0-9, 22 and 23 are
unchanged; rows 10-21 change:
- Left half: the Plan DAG ends at row 10 (was 12) to give the Inspector
  its 12 rows, so the Inspector's border is row 11 (was 13) and the same
  eight lines follow two rows higher (operator, detail, blank, rows in,
  rows out, batches, latency/batch, memory: rows 12-19, were 14-21).
  Rows 20-21 are new on screen: "H2D / D2H" and "cpu fallback", which
  the old eight-line body cut (selected operator's values: 12.4 MiB /
  512 B and 0 / 100; GpuFilterExec in -2: 22.9 MiB / 18.6 MiB and
  7 / 100; DataSourceExec in selection_moves: 0 B / 0 B and 0 / 100).
- Right half: Telemetry gains its last line at row 10, "spill on the
  query path" (the demo sets the flag), and its border moves from 10 to
  11. Describe moves down one row: border row 12, now titled "Describe
  (hidden: p99)"; header row 13 "column type min max nulls p25 p50" (was
  "colu type min max nul p25 p50 p99"); row 14 k with "Int64" (was
  "Int6"); row 15 v with "Float64 0.0 24.0 76923 6.0 12.0" (was "Floa
  0.0 24.0 769 6.0 12.0 23.7"); row 16 s, "Utf8 s0 s6 0" as before; rows
  17-21 blank.
- The styled snapshot's styles block follows the same moves: row 10 is
  the plan's bottom border (yellow, focused) plus "on the query path" in
  green (cols 47-63); the old row 10-11 side-border entries go because
  the plan ends at 10; row 12 the operator name bold and [CUDA] green
  (was row 14); row 13 the Describe header bold (was row 12); row 21 the
  fallback count, green for 0 of 100 (cols 14-27, new on screen).

120x40, two files: initial_frame_120x40 and
demo_renders_navigates_resizes_and_quits-3. Only rows 19-22 of the right
half change, the Describe header and its k, v, s rows: columns at their
data's width (6,7,3,4,5,3,4,5) instead of the fixed widths squeezed into
58 cells, so v's type reads "Float64" (was "Float6"); every value is the
same and nothing is hidden. The rest of both screens is unchanged.

`oxide_tui_pty.rs` (the shipped `oxide tui` against the styled snapshot)
passes, as do cargo test -p oxidelake-tui, clippy -p oxidelake-tui
--all-targets -D warnings and the termlens-cli suite over the edited
screens. docs/architecture.md says what Describe does when it cannot fit
a column.

Not fixed, reported instead: at 80 columns Telemetry's text lines are
still clipped mid-word, so a live session's "NVMe spilled 0 B (0
demotions)  reloa" loses the reloaded/promotions figures.

Closes #122

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
ci.yml's msrv job installed the declared version (1.94.1) with
dtolnay/rust-toolchain and then ran a plain `cargo check`. rustup prefers
rust-toolchain.toml (1.98.0) to the default the action sets, so the job
compiled with 1.98.0 and could not fail on an MSRV break; only a local
`make msrv`, which uses `rustup run`, ever checked the claim.

Proof on real toolchains, in a scratch crate shaped like this workspace
(rust-toolchain.toml 1.98.0, rust-version 1.94.1) whose one function calls
core::hint::cold_path, stable from 1.95.0 (E0658 on 1.94.1, clean on
1.95.0), each step run as ci.yml has it:
- the old step, `cargo check --workspace --all-targets --locked`: exit 0;
- the new assertion step with RUSTUP_TOOLCHAIN: "release: 1.94.1", exit 0;
  without it: "release: 1.98.0" and "::error::the msrv job is not running
  rustc 1.94.1", exit 1;
- the new check step, `make msrv`: "rustc 1.94.1 ..." then
  "error[E0658]: use of unstable library feature `cold_path`", exit 2.
The scratch crate is not committed.

The job now sets RUSTUP_TOOLCHAIN on every step that compiles, asserts
`rustc -vV` reports the declared release first (the fix and assertion
termlens#213 made), and runs `make msrv` itself, so CI and the local
target are one command. `make msrv` keeps `rustup run`, which also holds
past a cargo on PATH that is not rustup's proxy (the existing
ToolchainTests case), and now prints `rustup run $(MSRV) rustc --version`
so the log names the compiler that checked.

Tests (make ci-scripts):
- MsrvJobTests.test_every_step_that_compiles_names_the_declared_toolchain:
  each msrv step whose run mentions cargo, make or rustc carries
  `RUSTUP_TOOLCHAIN: ${{ steps.msrv.outputs.msrv }}`, and one runs `make
  msrv`. On the base ci.yml: "RUSTUP_TOOLCHAIN ... not found in ['- run:
  cargo check --workspace --all-targets --locked']".
- MsrvJobTests.test_the_assertion_fails_when_rust_toolchain_toml_wins:
  the assertion step's script, run as a Linux runner runs it, against a
  rustc answering with rustup's precedence: passes with the pin, fails
  with the ::error:: line without it. Errors on the base (no such step).
- ToolchainTests now also checks that `make msrv` names the toolchain
  Cargo.toml declares, for both the version line and the check.
Broken once each, all red: the pin removed from the check step, or from
the assertion step (the first test); the grep loosened to any release
(the second); `make msrv` with a plain $(CARGO) (ToolchainTests).
Restored, green; make ci-scripts 35 tests OK. make zizmor (offline,
pedantic) and actionlint: no findings.

`make msrv` itself is run once at the end of this branch, per the gate.
docs/verification.md lists the new coverage; STATUS.md's "CI now checks
it" says what the job did through 0.2.0.

Closes #127

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
oxidelake-runtime's `metrics` feature (the 0.2.0 Prometheus endpoint,
`make deny` turned it on, through --all-features.

Verified on this branch: a type error in the metrics-gated
`serve_metrics` of src/bin/oxide_worker.rs (`let broken: u32 = "not a
number";`) passes `RUSTDOCFLAGS="-D warnings" cargo doc -p
oxidelake-runtime --no-deps --features metrics` (exit 0: rustdoc does not
type-check a binary's function bodies) and `make lint` (the code is not
compiled without the feature). The same error in the library's
src/metrics.rs is caught by `cargo doc` after all, because documenting
the binaries type-checks the library they depend on; the binaries' gated
code is what nothing compiled.

Now:
- `make lint-metrics`: clippy -p oxidelake-runtime --all-targets
  --features metrics -D warnings.
- `make test-metrics`: cargo test -p oxidelake-runtime --features metrics
  --lib --bins. --lib runs the endpoint's two tests (metrics::tests, with
  the library's other 17 under the feature); --bins builds oxide-worker
  and oxide-scheduler, whose --metrics-port is the feature's whole
  surface. Without --bins this target would not have caught the error
  above.
- Both are in `make gate`, and in ci.yml as `clippy (metrics)` and `test
  (linux, metrics)` matrix entries, like predict's. Neither changes the
  dependency graph's features (tokio's net and io-util are already on),
  so locally each ran in seconds over the default build's artifacts.
With the broken body both new targets fail with E0308 at
oxide_worker.rs:88; restored, both pass (19 lib tests, 3 bins).

Test (make ci-scripts), FeatureCoverageTests: every feature in
oxidelake-runtime's [features] is compiled by a cargo clippy, test,
check or build that `make -n <target>` expands to, for a target ci.yml
runs (--all-features in doc and deny does not count); `metrics` is both
linted and tested; and each target ci.yml runs for it is in `make gate`.
On the base: "no CI job compiles oxidelake-runtime's `metrics` feature".
Broken once each: lint-metrics out of `gate` ("ci.yml runs `make
lint-metrics` and `make gate` does not"); the test lane removed
("`metrics` is linted and its tests run, not merely compiled").
Restored, green: 37 tests OK. make zizmor (offline, pedantic) and
actionlint: no findings.

The same map shows `io-uring` tested but never linted (no clippy target
enables it); reported, not changed here.

AGENTS.md and CONTRIBUTING.md list `metrics` with the other optional
features and lanes; docs/verification.md lists the new lanes, the gate
commands and the coverage test.

Closes #128

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
Each of the nine crates sets `readme.workspace = true`, so its crates.io
page renders the workspace README.md, and crates.io resolves a relative
link against the crate's own directory: `docs/SPEC.md` on the
oxidelake-api page is .../crates/oxidelake-api/docs/SPEC.md, a 404.
GitHub renders the same file from the root, where every link works, so
nothing in the repository showed it.

Before: the new check on the base README.md fails on all 28 distinct
relative targets (33 links): CHANGELOG.md, CONTRIBUTING.md, LICENSE,
Makefile, SECURITY.md, STATUS.md, deny.toml, .github/workflows/ci.yml,
docs, nine docs/ targets (architecture.md twice, once with
crates/oxidelake-device/kernels. The issue counted 27; the 28th is that
anchored architecture.md link.

Now every one is https://github.com/vyncint/oxidelake/blob/main/<file>,
or tree/main/<dir> for the crate, kernels and docs directories, chosen by
what the path is in the checkout; nothing else in README.md changed but
the rewrap of one paragraph the longer links pushed past the margin.
Checked online once: all 37 distinct URLs in the README return 200
(crates.io's crate page once the request asks for text/html, as a
browser does), and the one anchor matches architecture.md's "## Memory
model and spill tiers".

.github/scripts/check-readme-links.sh, run from
check-crate-metadata.sh (so `make crate-metadata` and CI's
release-scripts job), reads every target a renderer follows: inline
`](...)`, reference definitions and HTML src/href. Anything relative
fails and names the absolute URL to write; a link into this repository's
main branch must name a path in the checkout. It never asks the network,
which is slow, flaky and can answer 200 for the wrong reason, and a
README in which it finds no link at all is a failure, so a broken
extraction cannot pass as a clean README. Bash 3.2 constructs only (the
metadata gate also runs on macOS), as in check-crate-metadata.sh. The
termlens checker (termlens#369, #384, #657) is where the rules come from.

Tests (make ci-scripts): ReadmeLinkTests - the committed README passes;
absolute links into the repo, other absolute links, anchors, mailto and
a reference definition pass; each relative form fails naming its link
(inline, inline with angle brackets and a title, reference definition,
img src, a href, ./LICENSE); a repo link to a missing path fails; a
README with no link fails. MetadataTests - the metadata gate fails on a
relative README link (red before check-crate-metadata.sh called the new
script). Broken once each, all red: a relative LICENSE link put back in
README.md fails `make crate-metadata` and the committed-README test;
without the reference-definition extraction, "[s]: docs/SPEC.md" passes
and its case fails; without the existence check the missing-path case
fails. Restored, green: make crate-metadata, make ci-scripts (all OK),
make zizmor offline pedantic and actionlint clean.

Closes #129

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
Each claim below was checked against the code on this branch; each
sentence now says what the code does.

1. Spill manager (docs/SPEC.md 2.1, docs/architecture.md, docs/roadmap.md
   Phase 2). They said it demotes cold batches asynchronously at a
   high-watermark (LRU/clock) and exports a spill throughput metric.
   crates/oxidelake-memory/src/spill.rs: SpillBudget bounds device and
   host only (disk unbounded); insert_host, insert_device and get call
   enforce_device/enforce_host, which loop `while used > budget` demoting
   State::coldest (min last_touch on an AtomicU64 tick) one tier down,
   under the state lock, before the call returns. There is no watermark,
   no background task, and no CLOCK algorithm. get promotes a disk batch
   to host and returns a host copy of a device batch without moving it.
   SpillSnapshot has demotions, promotions, spilled_bytes and
   reloaded_bytes: totals, no rate. SPEC also says, in 0.x terms like its
   other bullets, that no operator registers a batch (#25).
   The same rate claim was in two more SPEC sentences, fixed with it:
   TelemetryHub's "transfer and spill rates" (telemetry.rs keeps byte and
   count totals and per-operator elapsed time; nothing divides by time),
   and the Telemetry panel's "PCIe/NVMe transfer rates" (render.rs prints
   `PCIe  H2D <total>  D2H <total>` and spilled/reloaded totals). That
   sentence's "pinned RAM" gauge is labelled and measured as host RAM.
2. crates/oxidelake-storage/src/uring.rs said the EINTR path is driven by
   `tests/uring_signals.rs`, which never existed (tests/ holds
   object_store_conformance.rs and pruning.rs). The test that drives it is
   the unit test uring::tests::a_signal_during_the_wait_does_not_abandon_
   the_completion in the same file; the comment names it. Run here:
   `cargo test -p oxidelake-storage --features io-uring --lib --
   uring::tests::a_signal_during_the_wait_does_not_abandon_the_completion
   --exact` passes (1 test). Comment only; no code changed.
3. docs/verification.md said "Two dev boxes so far", CUDA execution
   "never claim", and "no such box has run this yet", while STATUS.md's
   matrix records the 2026-09-06 g4dn.xlarge T4 session (driver 595.71,
   CUDA 13.2) that ran the device tests, the conformance suite with the
   transfer-counter witness and embedded.rs on the cuda target. The page
   now records that session, that it was manual and nothing has executed
   CUDA since (#38), splits execution (done once, on a CUDA machine
   only) from performance (no timing on record), and lists the two
   commands the session ran. STATUS.md's deferred list said "CUDA
   execution verification" was deferred; it now says what is: re-running
   it for every release.
4. oxidelake-api's description (shown on crates.io) said "(PyO3 bindings
   optional)". No crate has a `python` feature (STATUS.md: deferred).
   The same claim was in docs/architecture.md's crate graph ("optional
   PyO3"), docs/dependencies.md ("`ffi` only under
   `oxidelake-api/python`"; `cargo tree --workspace --all-features -e
   features -i arrow` enables no `ffi`), and SPEC's layout comment and
   feature-wiring line, which now say it was deferred.

No test: these are prose and a comment. The one mechanical class here, a
comment citing a test file that does not exist, has a single other
instance in crates/ (it resolves), so a guard for it was not added.
make crate-metadata, make skill-version (reads SPEC.md and
dependencies.md) and make ci-scripts pass; cargo fmt --check is clean.

Closes #132

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
No CI job executes CUDA code: ci.yml's runners have no GPU, so the cuda
feature is only compiled and linted (make check-cuda, make lint-cuda)
and every device test is #[ignore]d. The only CUDA execution on record
is the manual T4 session of 2026-09-06, which found the aggregation
kernel bug that CPU conformance had passed (STATUS.md).

This workflow has NOT run. It needs a self-hosted runner labelled `gpu`
and none is registered, so a dispatch would wait in the queue until
GitHub cancels it. It is committed so the release checklist can name it
and a runner can be added without another change; #38 is not done until
it has run green on a CUDA machine for a main SHA, and release.yml does
not gate on it (see below).

- `make test-cuda-device` (not in `make gate`): fails at once, before
  building anything, unless `nvidia-smi -L` lists a GPU (unlike
  test-metal-device, which skips: a skip here would be a green run that
  executed nothing); then the three suites the T4 session ran, from
  STATUS.md's matrix: `cargo test -p oxidelake-device --features cuda --
  --include-ignored` (transfers, pinned round trip, NVRTC compile and
  launch, the aggregation regression); `OXIDE_BACKEND=cuda cargo test -p
  oxidelake-compute --features cuda -- --ignored` (conformance, with the
  transfer-counter witness against a silent CPU fallback); and
  `OXIDE_BACKEND=cuda cargo test -p oxidelake-runtime --features cuda
  --test embedded` (the multi-partition net that caught the bug).
- .github/workflows/gpu.yml: workflow_dispatch only, on [self-hosted,
  linux, gpu], `permissions: {}` with contents: read for the job,
  checkout without persisted credentials. It records the GPU, driver and
  commit, runs the target under `set -euo pipefail` with its output teed
  to a log (without pipefail tee's success would hide a failure), and
  uploads the log. Dispatch-only matters: this repository is public, and
  a self-hosted runner that ran pull_request jobs would run a stranger's
  code on the GPU box. Pins are the SHAs ci.yml already uses.
- docs/RELEASING.md: the `gpu` runner is a prerequisite (none yet), and
  step 0 requires a green gpu.yml run on the release candidate with its
  GPU, driver and commit added to STATUS.md's matrix in the release PR.
  release.yml does not check it; with no runner, the release PR and notes
  must say the release's CUDA paths are compiled-only (ADR-0012). The
  issue also asks for `make test-termlens-cli` in step 0; release.yml's
  call into ci.yml already runs it in the default Linux lane, so it is
  not repeated.
- .github/zizmor.yml accepts dtolnay/rust-toolchain in gpu.yml like the
  other workflows (pedantic superfluous-actions): on a bare self-hosted
  runner it installs rustup when it is missing, which the pinned
  action.yml (683b588) does in "Install rustup if needed".
  .github/actionlint.yaml declares the `gpu` label, which actionlint
  otherwise reports as unknown.

Tests (make ci-scripts, CudaDeviceTests), with a fake nvidia-smi and a
cargo that records its calls: no GPU (nvidia-smi exits 9) -> make fails
naming the reason and cargo is never called; a T4 listed -> exactly the
three commands above, OXIDE_BACKEND as shown. The workflow's only
trigger is workflow_dispatch and it runs on the gpu label. Its step
script, run as a runner runs it against a `make` that fails, fails and
still writes the log. Broken once each, all red: the probe removed
(cargo is called with no GPU), pipefail removed (the step passes), a
pull_request trigger added. Restored, green: 47 tests OK. On this
GPU-less box the real `make test-cuda-device` stops at the probe, exit 2.
make zizmor (offline, pedantic) and actionlint (all workflows) clean.

docs/verification.md and STATUS.md's deferred list say gpu.yml exists
and has never run; CHANGELOG lists it under Added.

Not done here, from the issue: running it (no runner); a workflow_call
from release.yml that refuses to publish without a green gpu run for the
tagged SHA (it would block every release until a runner exists); a run
appending its STATUS.md row by PR (step 0 makes that a manual step).

Refs #38

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
The worker-build paragraph (#92) arrived with a relative link, which
crates.io resolves against each crate's directory, where it is a 404;
the crate-metadata gate this branch adds refuses it.

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
Every other workflow names v7.0.1 for this SHA since #138; a bare `# v7`
is the moving major that zizmor flags once upstream releases.

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
@vyncint vyncint added this to the v0.3.0 milestone Nov 18, 2026
@vyncint
vyncint merged commit da6b766 into main Nov 18, 2026
19 checks passed
@vyncint
vyncint deleted the pr/030-ux branch November 18, 2026 09:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment