Skip to content

refactor(scripts): one usage-text printer shared by premerge-check and prebuilt-bin (LABS-1366) - #173

Merged
jexp merged 1 commit into
mainfrom
fix/usage-text-lib
Nov 11, 2026
Merged

jexp merged 1 commit into
mainfrom
fix/usage-text-lib

Conversation

@jexp

@jexp jexp commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

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 in prebuilt-bin.sh's --help and premerge-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.sh and prebuilt-bin.sh source 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.
  • Load guard: existence and readability are checked before the source, because bash aborts the script outright on a missing or unreadable source target — an || fail guard 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

  • Usage output byte-identical to pre-change on both paths, diffed against captured pre-change output (the awk rule order and the shebang rule both changed, so this check is load-bearing).
  • Exit codes: --help → 0, usage error → 2, unknown flag → 2, missing helper → 2, unreadable helper → 2.
  • bash -n clean on all three files; set-equality on the file list (exactly the three intended files).
  • Local stellar round 1 + round 2 (four passes each) — all findings fixed in-commit; round-2 branching pass returned no findings. No third copy of the printer exists (grep-verified: sed/head uses are log/manifest slices, not header printers).

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Rust review: no rust-relevant changes (no Rust files modified). ✅

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Security review (security-review skill)

Reviewed the shared usage-printer extraction in scripts/lib/usage.sh, scripts/premerge-check.sh, and scripts/prebuilt-bin.sh against the skill checklist (trust boundaries, input validation, secrets, dependency and CI-execution risk). The change is a pure refactor: the new helper prints a script's leading comment block via a quoted awk invocation, both call sites pass their own ${BASH_SOURCE[0]}, and the helper is loaded from a repo-root-relative path behind an existence/readability pre-check. No new input, network, auth, secret, or dependency surface is introduced; the only CI caller (merge-compiles, pull_request event) already executes PR-owned shell and exposes no secrets. No issues found.

No issues found.

Security review: ✅ no issues found

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stellar review round 1: 2 inline finding(s); see summary comment.

Comment thread scripts/lib/usage.sh
# [ -f "$usage_lib" ] && [ -r "$usage_lib" ] || {
# echo "cannot load $usage_lib" >&2; exit 2;
# }
# source "$usage_lib"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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

Comment thread scripts/prebuilt-bin.sh Outdated
[ -f "$usage_lib" ] && [ -r "$usage_lib" ] || {
echo "prebuilt-bin: cannot load scripts/lib/usage.sh (incomplete checkout?)" >&2
exit 2
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Stellar review (stellar-review skill)

Round 4 · head 951288df · scope: 0/3 units (3 sealed from earlier rounds).

Still open from earlier rounds

  • [Medium] branching (std-0) F-1-1: scripts/lib/usage.sh:9-14 — 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
  • [Medium] boundaries (std-5) F-1-2: scripts/premerge-check.sh:164-164 — The script derives REPO from BASH_SOURCE (line 46) yet every git command — this probe, the head/base rev-parse, and resolve_base's fetch — runs against the caller's cwd; only the usage-lib pat
  • [Medium] boundaries (std-6) F-1-3: scripts/premerge-check.sh:149-152 — resolve_base re-spells fail's contract twice (prefix, log tail, status) because it returns a status instead of exiting; but its only caller (line 162, || exit 2) turns any non-zero into the same
  • [Medium] boundaries (std-6) F-1-4: scripts/prebuilt-bin.sh:38-42 — 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
  • [Medium] boundaries (std-5) F-1-5: scripts/premerge-check.sh:110-112 — gh's two fields are packed into one space-joined string and re-split with %% */#* , so the head/base boundary exists only as an unwritten no-whitespace assumption and the base is recovered by su
  • [Medium] boundaries (std-7) F-1-6: scripts/prebuilt-bin.sh:85-88 — stage publishes by overwriting the live $DEST/$1 in place and then chmods it: a lane that execs the path while another stages hits a write-open file (ETXTBSY) or a truncated binary, and a failed c
  • [Medium] boundaries (std-5) F-1-7: scripts/prebuilt-bin.sh:80-83 — The artifact is read back from $REPO/target/<profile>/ although cargo build honours CARGO_TARGET_DIR (this repo's ramdisk and shared-cache lanes set it); with the variable set the copy either di
  • [Low] boundaries (std-6) F-1-8: scripts/premerge-check.sh:59-64 — The comment claims one truncation spelling, but the conflict report at line 196 has its own sed -n '2,40p', and log_head's ${2:-10} length parameter has no caller — one policy, two implementatio
  • [Medium] boundaries (std-4) F-2-1: scripts/lib/usage.sh:2-6 — 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
  • [Low] structure (q-harder-to-scan) F-2-2: scripts/premerge-check.sh:50-53 — The branch replaced this function's inline awk with a usage_text call, but the library that defines it is sourced 30 lines further down (line 82), because the load block has to sit after fail (69-
  • [Low] boundaries (std-5) F-2-3: scripts/lib/usage.sh:20-22 — The contract is 'prints that script's block', but a header whose first non-comment line comes early (a bare blank separator line, or no comment block at all) makes awk exit 0 having printed nothing: p

Stellar review: ⚠️ 5 issue(s) open (0 + 0 anchored new (fail/low) + 5 carried)

@jexp
jexp force-pushed the fix/usage-text-lib branch from cada170 to 9944f69 Compare November 11, 2026 09:18
@jexp

jexp commented Nov 11, 2026

Copy link
Copy Markdown
Contributor Author

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 source returns non-zero for a missing file, and a source ... || { ... } guard does run". F-1-4 says every caller should collapse to that one-line guard.

Both are right on bash 5, and wrong on bash 3.2. Measured, source /tmp/missing.sh 2>/dev/null || <guard> under set -euo pipefail:

shell guard
bash 5.2.21 (ubuntu 24.04 — CI) runs → exit 2
bash 3.2.57 (macOS /bin/bash) never runs → exit 1, guard untouched

Without set -e, both versions run the guard — so the abort is errexit interacting with a failed source, and bash 3.2 and bash 5 disagree about it.

Both scripts set -euo pipefail, and both run on macOS (agents invoke premerge-check.sh locally; the whole reason the gate exists is a local pre-merge check). So the || one-liner would leave premerge-check exiting 1 on macOS — the status its header reserves for "do not merge" — which is the exact defect F-1-1's round-1 sibling asked to close.

Changed in 9944f69:

  • The header now states the version-scoped fact instead of the absolute claim, with both shells named.
  • prebuilt-bin.sh's guard is one line, matching premerge-check.sh's shape (F-1-4's "every caller hand-expands a block").
  • The pre-check stays. It is the only form that reports the environment fault as status 2 on both shells; a sourced file cannot guard its own absence, so the check itself is irreducible — only its wording is shared, and that now lives in the lib's header.

Verified on both: --help → 0, usage error → 2, unknown flag → 2, missing helper → 2, unreadable helper → 2; usage output byte-identical to pre-change on both paths.

Deferred (context units — outside this diff, filed as a review-tasks ticket): F-1-2 (git invocations not anchored to $REPO), F-1-3 (resolve_base re-spelling fail), F-1-5 (gh field round-trip through a space-joined string), F-1-6 (stage overwriting the live binary → ETXTBSY), F-1-7 (CARGO_TARGET_DIR ignored), F-1-8 (log_head's never-passed $2).

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stellar review round 2: 1 inline finding(s); see summary comment.

Comment thread scripts/lib/usage.sh Outdated
# 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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>
@jexp
jexp force-pushed the fix/usage-text-lib branch from 9944f69 to 951288d Compare November 11, 2026 09:30
@jexp

jexp commented Nov 11, 2026

Copy link
Copy Markdown
Contributor Author

Round 2 — F-2-1 fixed; the loop is bounded here

F-2-1 (medium) — fixed in 951288d. The lib's doc claimed the leading comment block is the usage prose; both consumers' headers also carry implementation notes, so the claim was false. Reworded to say what the printer actually does: it prints the whole header block, and a caller that wants --help to show prose alone keeps its notes outside the block. No behaviour change — output stays byte-identical to pre-change on both paths (re-verified).

The behavioural half of F-2-1 — that prebuilt-bin.sh --help prints its consumer notes and build-cache pointers — is pre-existing, unchanged by this PR, and a user-facing change to an unrelated shipped script's help text. It belongs in its own slice, not a dedup PR; I've left it out.

F-1-1 / F-1-4 — the re-report predates the answer. This round's ledger is head 9944f698, posted 09:13:27; the evidence comment answering both (the bash 3.2 vs bash 5.2 measurement table, and why the pre-check stays) landed at 09:18:34. The round could not have read it. The finding as stated — "the guard does run" — is correct on bash 5 and false on bash 3.2, which is exactly what the comment documents; the header now states the version-scoped fact rather than the absolute. F-1-4's remedy (source … || …) would leave premerge-check exiting 1 on macOS, the status its header reserves for "do not merge".

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 $REPO, resolve_base re-spelling fail, the gh field round-trip, stage's in-place overwrite, CARGO_TARGET_DIR ignored, log_head's unused $2). Filed as LABS-1387 (Agent Backlog, infra + code-health, with a Files: section).

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.

@jexp
jexp marked this pull request as ready for review November 11, 2026 10:09
@oplane-bot

oplane-bot Bot commented Nov 11, 2026

Copy link
Copy Markdown

Oplane Security Review

Oplane identified security requirements relevant to this PR and checked the implementation against them. All requirements are satisfied. Review the generated threat model.

StatusRequirementSeverityAction
🟢 ImplementedHelper Script Sourcing Path Restriction for usage.sh
OPLANE_REQ-00355635
Critical

Change comment settings · Set up Oplane in your agent · Workflow guidance

@github-actions

Copy link
Copy Markdown

Spec-harness coverage — 🟡

  • 🟡 spec coverage 98.98% — 343 genuine failures (1.02% of the executed scenarios)
  • scenarios run: 33646 (passed 33303, failed 343)
  • bands: 🟢 zero failures · 🟡 failure share ≤ 10% · 🔴 beyond (ADR-0482 §4 — the light never fails the build)
  • suite runtime: 1m 20s
  • neo4j_expected_fail (not counted): 406
  • nondeterministic (not counted): 4
  • skipped (not counted): 2323
  • harness ref: 0f43b85cf8b015a6542ceaf44c384213ca3ac225
failure category count
missing-validation 105
side-effects 51
error-class-mismatch 44
result-mismatch 33
syntax-error 31
result-temporal-fidelity 29
notification-missing 19
semantic-error 10
type-error 10
other 8
setup-failed-syntax 3

Rerun spec-harness to refresh. Coverage below 100% never fails the build (ADR-0482 §4).

@github-actions

Copy link
Copy Markdown

Memory shape

Note: loadtest comparison completed with no failing rows.


Memory shape

Status: ok

All memory shapes held. 🟢

base

Given: 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.

flat

Given: 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.

fanout

Given: 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.

ring

Given: 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 ring

Given: 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.

@github-actions

Copy link
Copy Markdown

Loadtest baselines comparison

Note: loadtest comparison completed with no failing rows.


Loadtest baseline comparison

Frozen baselines vs current reports; bands match the compare-loadtests gate.

Status: ok

Pairs: fraud-loadtest: compared · identity-loadtest: compared

fraud-loadtest

baselines/fraud-loadtest.json → target/fraud-loadtest.json

Metric Baseline PR Δ Status
environment relate-loadtest-baseline/v1 relate-loadtest-baseline/v1 — match
errors 0 0 +0 ok
ops/s 3938.56 3731.34 -207.22 (-5.3%) ok
p99 (worst: counterparties) 7.45 ms 7.47 ms +0.02 ms (+0.2%) ok
logical bytes 17,344,481 16,379,227 -965,254 (-5.6%) ok
Per-use-case p99 latency
Use case ops Baseline p99 PR p99 Δ Status
p2p_transfer 3,806 8.04 ms 8.05 ms +0.01 ms (+0.1%) ok
payroll_scatter 1,106 17.85 ms 16.56 ms -1.29 ms (-7.2%) ok
onboard_customer 842 8.53 ms 7.59 ms -0.95 ms (-11.1%) ok
mule_scatter 828 14.80 ms 12.41 ms -2.39 ms (-16.1%) ok
layering_cycle 813 15.10 ms 11.96 ms -3.13 ms (-20.8%) ok
recent_transfers 2,233 7.65 ms 7.13 ms -0.52 ms (-6.9%) ok
customer_portfolio 1,384 7.37 ms 6.87 ms -0.50 ms (-6.8%) ok
outgoing_volume 1,145 7.48 ms 6.75 ms -0.73 ms (-9.7%) ok
detect_fanout 811 25.78 ms 16.22 ms -9.55 ms (-37.1%) ok
detect_cycle 864 7.55 ms 6.79 ms -0.76 ms (-10.1%) ok
activity_page 1,164 7.48 ms 7.06 ms -0.42 ms (-5.6%) ok
search_customer 845 7.84 ms 7.50 ms -0.35 ms (-4.4%) ok
counterparties 1,125 7.45 ms 7.47 ms +0.02 ms (+0.2%) ok
payment_path 840 7.47 ms 6.76 ms -0.71 ms (-9.5%) ok
amount_band 862 7.30 ms 6.75 ms -0.55 ms (-7.5%) ok
flag_account 637 8.21 ms 7.59 ms -0.61 ms (-7.5%) ok
reverse_last_out 695 8.04 ms 7.67 ms -0.37 ms (-4.6%) ok

identity-loadtest

baselines/identity-loadtest.json → target/identity-loadtest.json

Metric Baseline PR Δ Status
environment relate-loadtest-baseline/v1 relate-loadtest-baseline/v1 — match
errors 0 0 +0 ok
ops/s 573.51 655.82 +82.31 (+14.4%) ok
p99 (worst: stale_grants) 15.06 ms 15.70 ms +0.64 ms (+4.2%) ok
logical bytes 7,167,614 7,393,082 +225,468 (+3.1%) ok
Per-use-case p99 latency
Use case ops Baseline p99 PR p99 Δ Status
provision_user 1,373 11.00 ms 9.98 ms -1.02 ms (-9.3%) ok
add_to_group 1,775 18.57 ms 17.52 ms -1.05 ms (-5.7%) ok
grant_role 1,079 18.52 ms 17.10 ms -1.41 ms (-7.6%) ok
attach_device 907 18.88 ms 17.54 ms -1.33 ms (-7.1%) ok
nested_grant 736 19.41 ms 16.93 ms -2.48 ms (-12.8%) ok
effective_access 2,173 25.25 ms 20.13 ms -5.12 ms (-20.3%) ok
org_walk 1,387 19.94 ms 18.03 ms -1.91 ms (-9.6%) ok
optional_manager 1,312 20.00 ms 17.30 ms -2.70 ms (-13.5%) ok
detect_nested_admin 810 19.97 ms 16.98 ms -3.00 ms (-15.0%) ok
detect_sod 817 19.60 ms 17.17 ms -2.43 ms (-12.4%) ok
stale_grants 827 15.06 ms 15.70 ms +0.64 ms (+4.2%) ok
search_directory 1,147 10.91 ms 10.82 ms -0.08 ms (-0.8%) ok
group_roster 1,047 7.72 ms 7.44 ms -0.28 ms (-3.6%) ok
access_review 801 20.02 ms 17.62 ms -2.40 ms (-12.0%) ok
reporting_path 794 30.98 ms 25.90 ms -5.08 ms (-16.4%) ok
disable_user 644 19.50 ms 17.60 ms -1.90 ms (-9.7%) ok
add_alias 710 19.99 ms 16.32 ms -3.67 ms (-18.4%) ok
revoke_membership 674 8.10 ms 7.43 ms -0.67 ms (-8.3%) ok
detach_device 538 14.79 ms 14.25 ms -0.54 ms (-3.7%) ok
clear_expiry 449 17.39 ms 15.18 ms -2.21 ms (-12.7%) ok

@github-actions

Copy link
Copy Markdown

Memory controls and workspace memory calibration

Warning: memory controls reported improvement.


Memory controls and workspace memory calibration

Status: improvement

sort — max_cgroup_to_logical_ratio

Verdict: 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_ratio

Verdict: 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_ratio

Verdict: 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.

@jexp
jexp merged commit 05e6ea0 into main Nov 11, 2026
82 of 84 checks passed
@jexp
jexp deleted the fix/usage-text-lib branch November 11, 2026 11:03
jexp added a commit that referenced this pull request Nov 11, 2026
…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>
jexp added a commit that referenced this pull request Nov 11, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant