Repository navigation
refactor(scripts): one usage-text printer shared by premerge-check and prebuilt-bin (LABS-1366) - #173
Conversation
|
Rust review: no rust-relevant changes (no Rust files modified). ✅ |
|
Security review (security-review skill) Reviewed the shared usage-printer extraction in No issues found. Security review: ✅ no issues found |
| # [ -f "$usage_lib" ] && [ -r "$usage_lib" ] || { | ||
| # echo "cannot load $usage_lib" >&2; exit 2; | ||
| # } | ||
| # source "$usage_lib" |
There was a problem hiding this comment.
[Medium] branching (std-0): The loading contract rests on a false premise: bash's source returns non-zero for a missing file, and a source ... || { ... } guard does run — it only aborts the shell when left unguarded under `s
Suggested fix: Drop the template and guard the source itself — source "$usage_lib" 2>/dev/null || { echo ...; exit 2; } in prebuilt-bin.sh, source "$usage_lib" 2>/dev/null || fail "..." in premerge-check.sh — and reduce the header's contract to that one line. Each caller loses a branch, and the paste-in block
finding F-1-1
| [ -f "$usage_lib" ] && [ -r "$usage_lib" ] || { | ||
| echo "prebuilt-bin: cannot load scripts/lib/usage.sh (incomplete checkout?)" >&2 | ||
| exit 2 | ||
| } |
There was a problem hiding this comment.
[Medium] boundaries (std-6): The new 'loading contract' makes every caller hand-expand the same test-and-message block (premerge-check lines 79-81 carries the second copy), and the stated reason — 'bash aborts the script outright
Suggested fix: Load it as one line: source "$REPO/scripts/lib/usage.sh" || { echo "prebuilt-bin: cannot load scripts/lib/usage.sh (incomplete checkout?)" >&2; exit 2; } (premerge: || fail "…"), drop the usage_lib variable, and make that the template in usage.sh's header so callers stop expanding a block.
finding F-1-4
|
Stellar review (stellar-review skill) Round 4 · head Still open from earlier rounds
Stellar review: |
cada170 to
9944f69
Compare
|
Round-1 F-1-1 / F-1-4 (the loading contract) — evidence, and what changed F-1-1 says the header's premise is false: "bash's Both are right on bash 5, and wrong on bash 3.2. Measured,
Without Both scripts set Changed in
Verified on both: Deferred (context units — outside this diff, filed as a review-tasks ticket): F-1-2 (git invocations not anchored to |
| # leading comment block is its usage prose, so --help and usage errors print | ||
| # it by content — skip the shebang, stop at the first non-comment line, strip | ||
| # one `# ` — and a line-numbered slice cannot drift when the header grows or | ||
| # shrinks. Source this file from a script that has resolved the repo root. |
There was a problem hiding this comment.
[Medium] boundaries (std-4): The printer offers one handle — 'everything from line 2 to the first non-comment line' — and asserts that block is the usage prose, but both callers' headers mix implementation notes with the usage se
Suggested fix: Make the usage region explicit — delimit it with start/end marker comments, or have usage_text take the section name — so design notes and help output stop sharing one artifact.
finding F-2-1
…d prebuilt-bin (LABS-1366) The awk usage-printer (skip the shebang, stop at the first non-comment line, strip one '# ') existed as a verbatim second copy in prebuilt-bin.sh's --help and premerge-check.sh's usage error path — the same policy in the same words, PR #162 stellar round-2 F-2-3. scripts/lib/usage.sh now owns the one printer (usage_text <script-path>), beside the repo's other sourced helpers; both scripts source it and keep their own exit contract (0 for --help, 2 for usage errors). The argument is explicit and both call sites pass the identical "${BASH_SOURCE[0]}", so neither a caller-identity parameter nor a call-stack frame can make two sites drift. The loading contract is stated once in usage.sh's header, as an existence and readability pre-check rather than an `||` guard on the `source`: on bash 3.2 (macOS) a `source` of a missing file under `set -e` aborts the script before any `||` guard can run, while bash 5 runs it. Measured on both (bash 3.2.57 and bash 5.2.21); the pre-check behaves the same on either, so a helper-less checkout is reported through premerge-check's environment status (2) — never 1, which that gate reserves for "do not merge". Output is byte-identical to before on both paths, verified against captured pre-change output; exit codes verified on bash 3.2 and bash 5: 0 / 2 / 2, and 2 for a missing or unreadable helper. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Code <noreply@anthropic.com>
9944f69 to
951288d
Compare
|
Round 2 — F-2-1 fixed; the loop is bounded here F-2-1 (medium) — fixed in The behavioural half of F-2-1 — that F-1-1 / F-1-4 — the re-report predates the answer. This round's ledger is head F-1-2, F-1-3, F-1-5, F-1-6, F-1-7, F-1-8 — deferred, ticketed. All are context units outside this diff's changed hunks (git invocations not anchored to Per the merge bar's loop bound: this round re-reported the answered F-1-1/F-1-4 and the already-ticketed context-unit class, and its one new finding is fixed. The PR is at the merge bar from my side; the ready flip is yours. |
Oplane Security ReviewOplane identified security requirements relevant to this PR and checked the implementation against them. All requirements are satisfied. Review the generated threat model.
Change comment settings · Set up Oplane in your agent · Workflow guidance |
Spec-harness coverage — 🟡
Rerun |
|
Memory shape
Memory shapeStatus: ok All memory shapes held. 🟢 baseGiven: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling. When: the base shape is loaded to 0 nodes and 0 relationships, then checkpointed. The child RSS is sampled. Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries. Baseline: logical 0.00 MB – 0.00 MB, disk 0.00 MB – 0.00 MB, attributed RSS 0.00 MB – 0.00 MB, ratio 0.000x–0.000x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes. Validated: logical 0.00 MB, disk 0.00 MB, attributed RSS 0.00 MB, ratio 0.000x. Report: logical, disk, attributed RSS, and the ratio held. flatGiven: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling. When: the flat shape is loaded to 120000 nodes and 0 relationships, then checkpointed. The child RSS is sampled. Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries. Baseline: logical 26.02 MB – 26.02 MB, disk 1.95 MB – 1.95 MB, attributed RSS 36.49 MB – 36.93 MB, ratio 1.402x–1.419x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes. Validated: logical 26.02 MB, disk 1.26 MB, attributed RSS 37.47 MB, ratio 1.440x. Report: logical, disk, attributed RSS, and the ratio held. fanoutGiven: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling. When: the fanout shape is loaded to 52016 nodes and 52000 relationships, then checkpointed. The child RSS is sampled. Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries. Baseline: logical 28.62 MB – 28.62 MB, disk 1.75 MB – 1.75 MB, attributed RSS 34.93 MB – 36.61 MB, ratio 1.220x–1.279x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes. Validated: logical 27.43 MB, disk 1.10 MB, attributed RSS 35.84 MB, ratio 1.306x. Report: logical, disk, attributed RSS, and the ratio held. ringGiven: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling. When: the ring shape is loaded to 46000 nodes and 46000 relationships, then checkpointed. The child RSS is sampled. Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries. Baseline: logical 29.99 MB – 29.99 MB, disk 1.77 MB – 1.77 MB, attributed RSS 35.30 MB – 35.89 MB, ratio 1.177x–1.197x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes. Validated: logical 29.99 MB, disk 1.20 MB, attributed RSS 36.30 MB, ratio 1.211x. Report: logical, disk, attributed RSS, and the ratio held. dense ringGiven: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling. When: the dense ring shape is loaded to 5000 nodes and 100000 relationships, then checkpointed. The child RSS is sampled. Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries. Baseline: logical 31.41 MB – 31.41 MB, disk 1.62 MB – 1.62 MB, attributed RSS 31.27 MB – 32.46 MB, ratio 0.996x–1.034x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes. Validated: logical 31.11 MB, disk 0.73 MB, attributed RSS 31.83 MB, ratio 1.023x. Report: logical, disk, attributed RSS, and the ratio held. |
|
Loadtest baselines comparison
Loadtest baseline comparisonFrozen baselines vs current reports; bands match the Status: ok Pairs: fraud-loadtest: compared · identity-loadtest: compared fraud-loadtest
Per-use-case p99 latency
identity-loadtest
Per-use-case p99 latency
|
|
Memory controls and workspace memory calibration
Memory controls and workspace memory calibrationStatus: improvement sort — max_cgroup_to_logical_ratioVerdict: improvement Given: a fresh server per observation, admission on, a hold of 2500 ms, and 1 repeats. Families: sort, expand, aggregation, distinct, and create. When: each observation parks its sessions on RETURN 1, then holds one workspace family at the target reservation. The shapes are one holder at 1.00 MB, 4.00 MB, and 16.00 MB, then the same 16.00 MB across two and four holders. Then: each observation records VmRSS and cgroup deltas against the live held logical bytes. The child stays alive. Outcome: Expected cgroup ratio 0.999x–1.082x. A reading may sit 5% outside that range. Measured 19.23 MB, ratio 0.873x. Investigate whether this improvement is a false positive. When it is real, re-freeze the envelope with the create-loadtest-baselines workflow. expand — max_rss_to_logical_ratioVerdict: improvement Given: a fresh server per observation, admission on, a hold of 2500 ms, and 1 repeats. Families: sort, expand, aggregation, distinct, and create. When: each observation parks its sessions on RETURN 1, then holds one workspace family at the target reservation. The shapes are one holder at 1.00 MB, 4.00 MB, and 16.00 MB, then the same 16.00 MB across two and four holders. Then: each observation records VmRSS and cgroup deltas against the live held logical bytes. The child stays alive. Outcome: Expected RSS ratio 2.099x–2.147x. A reading may sit 5% outside that range. Measured 34.14 MB, ratio 1.004x. Investigate whether this improvement is a false positive. When it is real, re-freeze the envelope with the create-loadtest-baselines workflow. expand — max_cgroup_to_logical_ratioVerdict: improvement Given: a fresh server per observation, admission on, a hold of 2500 ms, and 1 repeats. Families: sort, expand, aggregation, distinct, and create. When: each observation parks its sessions on RETURN 1, then holds one workspace family at the target reservation. The shapes are one holder at 1.00 MB, 4.00 MB, and 16.00 MB, then the same 16.00 MB across two and four holders. Then: each observation records VmRSS and cgroup deltas against the live held logical bytes. The child stays alive. Outcome: Expected cgroup ratio 2.072x–2.215x. A reading may sit 5% outside that range. Measured 8.75 MB, ratio 1.028x. Investigate whether this improvement is a false positive. When it is real, re-freeze the envelope with the create-loadtest-baselines workflow. |
…lt stage publishes by rename (LABS-1387) The six context-unit findings PR #173 deferred, plus what the local stellar round found in the fixing. premerge-check.sh: - One repo anchor for every git call AND the `gh` lookup (`git -C "$REPO"`, `cd "$REPO" && gh ...`), never the caller's cwd: the script worked only from inside a work tree, and an unanchored `gh pr view` read whichever clone the cwd walked up to while every git call ran against this one. The repo check comes first, so "not a git repository" is the message that surfaces rather than a downstream "is not a commit". - `resolve_base` calls `fail` instead of re-spelling its contract, and assigns `base_ref` rather than printing it: the call site cannot be a command substitution, because `fail` inside `$(...)` exits only the subshell and would leave the base empty. A post-condition check states the invariant instead of pre-seeding it. - `gh`'s two fields come back one per line and are read with `read -r`, then required non-empty: a short response is an environment error (2), never the exit-1 "do not merge" verdict a bare failing `read` gave, and an empty base line no longer silently merges against `main`. - One `is_commit` predicate replaces four hand-spelled `rev-parse --verify --quiet …^{commit}` sites. - `log_head` folded into `fail`, its one caller; the conflict report is documented as merge-tree's own output, sliced where it is printed. - The scratch dir is guarded like every other environment fault, so a failure there is exit 2, not the exit-1 verdict. prebuilt-bin.sh: - Published by rename (sibling temp, chmod, `mv` over) instead of an in-place overwrite followed by chmod: a lane exec'ing the staged path meanwhile hit ETXTBSY or read a truncated binary. The publish also fires when the staged file is not executable — `cp` does not preserve mtime, so a stale non-executable stage would otherwise stay newer than the source and never be republished. - The build output is read from `${CARGO_TARGET_DIR:-$REPO/target}`, the override the ramdisk and shared-cache lanes set, resolved once beside the staging dir; a build that produces no binary fails loud. Verified: `bash -n` clean on both; six exit-2 paths exercised (usage, unreadable PR, bad rev, unfetchable base, unwritable TMPDIR, foreign cwd) with the producer log still surfacing through `fail`; the two-line parse against a real PR; `prebuilt-bin.sh --help` exit 0. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Code <noreply@anthropic.com>
…lt stage publishes by rename (LABS-1387) The six context-unit findings PR #173 deferred, plus what two local stellar rounds found in the fixing. premerge-check.sh: - One repo anchor for every git call AND the `gh` lookup (`git -C "$REPO"`, `cd "$REPO" && gh ...`), never the caller's cwd: the script worked only from inside a work tree, and an unanchored `gh pr view` read whichever clone the cwd walked up to while every git call ran against this one. The repo check comes first, so "not a git repository" is the message that surfaces rather than a downstream "is not a commit". - `resolve_base` calls `fail` instead of re-spelling its contract (prefix, log tail, status), keeping its stdout-is-the-ref shape: `fail` runs in the substitution's subshell, and the call site's `|| exit 2` is what carries its status into this shell. - `gh`'s two fields come back one per line and are read with `read -r`, then required non-empty: a short response is an environment error (2), never the exit-1 "do not merge" verdict a bare failing `read` gave, and an empty base line no longer silently merges against `main`. - One `is_commit` predicate replaces four hand-spelled `rev-parse --verify --quiet …^{commit}` sites. - `log_head` folded into `fail`, its one caller; the conflict report is documented as merge-tree's own output, sliced where it is printed. - The scratch dir is guarded like every other environment fault, so a failure there is exit 2, not the exit-1 verdict. prebuilt-bin.sh: - Published by rename (temp beside the target, chmod, `mv` over) instead of an in-place overwrite followed by chmod: a lane exec'ing the staged path meanwhile hit ETXTBSY or read a truncated binary. The temp follows the repo's writer contract (scripts/lib/toml.sh): `mktemp` beside the target, removed when the publish does not complete. - The build decision is recorded once and the publish gate reads it, rather than re-spelling the build's two-clause test with one clause appended. - The build output is read from `${CARGO_TARGET_DIR:-$REPO/target}`, the override the ramdisk and shared-cache lanes set, resolved once beside the staging dir; a build that produces no binary fails loud. Verified: `bash -n` clean on both; six exit-2 paths exercised (usage, unreadable PR, bad rev, unfetchable base, unwritable TMPDIR, foreign cwd) with the producer log still surfacing through `fail`; the two-line parse against a real PR; the publish and its failure branch exercised in isolation (executable result, matching bytes, no leftover temp either way); `prebuilt-bin.sh --help` exit 0. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Code <noreply@anthropic.com>
Summary
Refactor (code-health, LABS-1366): the awk usage-printer — skip the shebang, stop at the first non-comment line, strip one
#— existed as a verbatim second copy inprebuilt-bin.sh's--helpandpremerge-check.sh's usage error path. PR #162's stellar round-2 F-2-3 deferred it because the remedy is a cross-file extraction, sliced here on its own.Changes
scripts/lib/usage.sh(new) owns the one printer,usage_text <script-path>, beside the repo's other sourced helpers (common.sh,toml.sh), following their shebang + "Source this file…" shape. The loading contract is stated once in its header.premerge-check.shandprebuilt-bin.shsource it and keep their own exit contract (0 for--help, 2 for usage errors). Both call sites pass the identical"${BASH_SOURCE[0]}"— no caller-identity parameter to drift on.source, because bash aborts the script outright on a missing or unreadable source target — an|| failguard would never run (verified empirically). A helper-less checkout exits through premerge-check's environment status (2), never 1, which that gate reserves for "do not merge".Verification
--help→ 0, usage error → 2, unknown flag → 2, missing helper → 2, unreadable helper → 2.bash -nclean on all three files; set-equality on the file list (exactly the three intended files).sed/headuses are log/manifest slices, not header printers).🤖 Generated with Claude Code