Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

ci(hub): make the §12.4 whole-hub gate green, correct, and runnable (follow-up to #1725) (#1858)

xerj-org4d7e27f4493b
diff --git a/engine/crates/xerj-hub/src/ask.rs b/engine/crates/xerj-hub/src/ask.rs
index b3d5fdb98..2fdae1100 100644
--- a/engine/crates/xerj-hub/src/ask.rs
+++ b/engine/crates/xerj-hub/src/ask.rs
@@ -606,12 +606,13 @@ pub fn ask(args: &AskArgs, deps: &AskDeps<'_>) -> AskOutcome {
};
// The pull policy is decided FIRST, before anything about how this run was asked
// to behave. Whether a pack may be pulled at all does not depend on `--offline`
- // or `--no-fetch`; and what is printed below must never be a command that
- // `xerj hub pull` refuses — or, for an excluded licence class, a way round
- // "never pulled". (The offline branch used to run before the policy and print
- // `run: xerj hub pull <slug>` for an excluded corpus; `hub pull` itself had no
- // licence check, so an agent that followed the hint pulled it.) An excluded
- // corpus and an oversize pack get a plain no.
+ // or `--no-fetch`. An EXCLUDED corpus is never pulled, so no command is printed
+ // for it — a `run: xerj hub pull <slug>` would be a way round "never pulled"
+ // (the offline branch used to run before the policy and print exactly that; the
+ // pull had no licence check, so an agent that followed the hint pulled it). An
+ // OVERSIZE pack is different: a question does not drag it down automatically,
+ // but `xerj hub pull <slug>` fetches it explicitly, so its message names that
+ // command — the same hint an allowed pack gets.
match pull_policy(entry) {
PullPolicy::Excluded => {
out.stderr.push(format!(
@@ -624,8 +625,9 @@ pub fn ask(args: &AskArgs, deps: &AskDeps<'_>) -> AskOutcome {
}
PullPolicy::TooLarge => {
out.stderr.push(format!(
- "'{shown}' is {} MB, over the {} MB limit for pulling a pack, so it is not \
- downloaded; no hosted answer is available",
+ "'{shown}' is {} MB, over the {} MB auto-pull cap, so a question does not \
+ download it automatically and no hosted answer is available; run \
+ `xerj hub pull {shown}` to fetch it once, then ask again",
megabytes(entry.pack_bytes),
megabytes(AUTO_PULL_MAX_BYTES)
));
@@ -914,12 +916,14 @@ fn finish_hosted(
}
}
}
- // No command to run for these: `xerj hub pull` refuses both.
+ // An oversize pack is not auto-pulled, but `xerj hub pull` fetches it
+ // explicitly, so the note names that command; an excluded one it refuses.
PullPolicy::TooLarge => notes.push(format!(
- "the pack is {} MB, over the {} MB limit for pulling a pack: this answer is \
- from the hosted hub only",
+ "the pack is {} MB, over the {} MB auto-pull cap, so this answer is from the \
+ hosted hub; run `xerj hub pull {}` to fetch it for local answers",
megabytes(e.pack_bytes),
- megabytes(AUTO_PULL_MAX_BYTES)
+ megabytes(AUTO_PULL_MAX_BYTES),
+ printable(&e.slug)
)),
PullPolicy::Excluded => notes.push(format!(
"excluded licence ({}): this corpus is never pulled",
@@ -1502,8 +1506,11 @@ impl Backend for RealBackend {
// Everything that can refuse this pull — the licence policy, the size cap, a
// malformed slug or pin, no key to verify with — is decided BEFORE a node is
// started for it. A pull that is going to be refused must not first boot a
- // whole node.
- let plan = cli::plan_pull_entry(entry).map_err(|e| PullFailure {
+ // whole node. This is the AUTOMATIC path (a question triggered it), so the
+ // ceiling is the 50 MiB auto-pull cap, not the disk budget an explicit
+ // `xerj hub pull` uses: `pull_policy` already kept a larger pack off this
+ // path, and the cap here is the backstop that keeps it off.
+ let plan = cli::plan_pull_entry(entry, AUTO_PULL_MAX_BYTES).map_err(|e| PullFailure {
code: e.code,
message: format!("pull of '{}' failed: {}", printable(&entry.slug), e.message),
})?;
@@ -2320,7 +2327,7 @@ mod tests {
}
#[test]
- fn a_pack_over_the_limit_is_not_pulled_and_the_message_names_its_size() {
+ fn a_pack_over_the_limit_is_not_auto_pulled_but_the_note_names_the_explicit_pull() {
let rig = Rig::new();
let sixty_mib = 60 * 1024 * 1024;
let cat = catalogue(vec![lz4(sixty_mib, LicenceClass::AdaptWithAttribution)]);
@@ -2332,21 +2339,21 @@ mod tests {
&backend,
);
assert_eq!(out.exit, EXIT_OK);
+ // A question still does not AUTO-pull an oversize pack ...
assert!(!backend.called("pull_"), "{:?}", backend.calls());
- // The note names the size, and is in the structured answer too ...
+ // ... the note names the size and says the answer is from the hosted hub ...
assert!(out.stdout.contains("60.0 MB"), "{}", out.stdout);
let ans = out.answer.unwrap();
assert!(
ans.warnings
.iter()
- .any(|w| w.contains("60.0 MB") && w.contains("hosted hub only")),
+ .any(|w| w.contains("60.0 MB") && w.contains("hosted hub")),
"{:?}",
ans.warnings
);
- // ... but it is not a command: `xerj hub pull` refuses an oversize pack, so
- // a `run:` line would send the reader to a command that fails.
- assert!(!out.stdout.contains("xerj hub pull"), "{}", out.stdout);
- assert!(!out.stdout.contains("run:"), "{}", out.stdout);
+ // ... and, now that an explicit pull fetches an oversize pack, it names
+ // `xerj hub pull` so the reader can get local answers.
+ assert!(out.stdout.contains("xerj hub pull lz4"), "{}", out.stdout);
}
#[test]
@@ -2502,7 +2509,8 @@ mod tests {
#[test]
fn the_policy_also_binds_the_synchronous_pull() {
let rig = Rig::new();
- // Over the limit: no pull, the message names the size and the command.
+ // Over the cap: no AUTOMATIC pull, but the message names the size and the
+ // explicit command that does fetch it.
let cat = catalogue(vec![lz4(
80 * 1024 * 1024,
LicenceClass::AdaptWithAttribution,
@@ -2513,8 +2521,8 @@ mod tests {
assert!(!backend.called("pull_now"), "{:?}", backend.calls());
assert!(out.stderr[0].contains("80.0 MB"), "{:?}", out.stderr);
assert!(
- !out.stderr[0].contains("xerj hub pull") && !out.stderr[0].contains("run:"),
- "no command for a pack `hub pull` refuses: {:?}",
+ out.stderr[0].contains("xerj hub pull lz4"),
+ "names the explicit pull for an over-cap pack: {:?}",
out.stderr
);
@@ -2584,7 +2592,10 @@ mod tests {
}
#[test]
- fn offline_never_hints_a_pull_for_a_pack_over_the_limit() {
+ fn offline_names_the_explicit_pull_for_a_pack_over_the_cap() {
+ // An oversize pack is not auto-pulled, but `xerj hub pull` fetches it
+ // explicitly — so, like any pullable pack, the offline/no-fetch message
+ // names that command (it is the thing to run once back online).
let rig = Rig::new();
let cat = catalogue(vec![lz4(
80 * 1024 * 1024,
@@ -2601,8 +2612,16 @@ mod tests {
let out = rig.run(&a, &cat, None, &backend);
assert_eq!(out.exit, EXIT_NO_ANSWER);
assert!(out.stderr[0].contains("80.0 MB"), "{:?}", out.stderr);
- no_pull_command(&out);
- assert_eq!(backend.calls(), ["ready:lz4"]);
+ assert!(
+ out.stderr[0].contains("xerj hub pull lz4"),
+ "names the explicit pull: {:?}",
+ out.stderr
+ );
+ assert!(
+ !backend.called("pull_"),
+ "not auto-pulled: {:?}",
+ backend.calls()
+ );
}
}
diff --git a/engine/crates/xerj-hub/src/cli.rs b/engine/crates/xerj-hub/src/cli.rs
index c257fd474..470f6e6fa 100644
--- a/engine/crates/xerj-hub/src/cli.rs
+++ b/engine/crates/xerj-hub/src/cli.rs
@@ -645,10 +645,12 @@ fn run_pull(args: &[String]) -> i32 {
return 2;
};
// Everything that can refuse this pull — a malformed or unknown slug, an
- // excluded licence, a pack over the size cap, no key to verify it with — is
- // decided BEFORE a node is looked for or started. A doomed pull used to boot a
- // whole node first, and only then say "no".
- let plan = match plan_pull(&slug) {
+ // excluded licence, a pack larger than the whole disk budget, no key to verify
+ // it with — is decided BEFORE a node is looked for or started. A doomed pull
+ // used to boot a whole node first, and only then say "no". This is the explicit
+ // command, so the ceiling is the disk budget, not the 50 MiB auto-pull cap: the
+ // person typing it has named exactly this pack.
+ let plan = match plan_pull(&slug, DISK_BUDGET_BYTES) {
Ok(p) => p,
Err(PullError { code, message }) => {
eprintln!("xerj hub pull: {message}");
@@ -736,9 +738,10 @@ const E_NOKEY: i32 = ask::EXIT_NO_KEY;
/// so this caps a hostile hub's "signature" far below the pack cap.
const SIG_MAX_BYTES: u64 = 4096;
/// How long a pull waits for another pull of the same pin to finish before it
-/// gives up. A pull is a download of at most [`AUTO_PULL_MAX_BYTES`] plus a
-/// restore, so this is generous; it exists so a wedged holder cannot hang a
-/// caller (an agent's tool call) for ever.
+/// gives up. A pull is a download of at most the planned ceiling
+/// ([`AUTO_PULL_MAX_BYTES`] for an automatic pull, [`DISK_BUDGET_BYTES`] for an
+/// explicit one) plus a restore, so this is generous; it exists so a wedged holder
+/// cannot hang a caller (an agent's tool call) for ever.
const PULL_LOCK_WAIT: Duration = Duration::from_secs(60);
/// Cross-process exclusion for one `(slug, pin)`: an OS lock on `<pin8>.lock`
@@ -808,16 +811,25 @@ impl PullLock {
}
/// What a pull has decided before it touches a node or the disk: the catalogue
-/// entry, the pin its files are named by, and the key it will verify with.
+/// entry, the pin its files are named by, the key it will verify with, and the
+/// byte ceiling this pull may download under (see [`plan_pull_entry`]).
pub(crate) struct PullPlan {
entry: CatalogueEntry,
pin8: String,
pubkey: String,
+ /// The largest pack this pull will accept and download. An *explicit*
+ /// `xerj hub pull <slug>` passes [`DISK_BUDGET_BYTES`]; an *automatic* pull
+ /// (the `ask` flow) passes [`AUTO_PULL_MAX_BYTES`]. The transfer in
+ /// [`pull_with`] is bounded again by this value, so a hub that lies in
+ /// `pack_bytes` still cannot write more than the ceiling the caller chose.
+ max_bytes: u64,
}
/// Look `slug` up in the catalogue and decide whether it may be pulled at all
-/// ([`plan_pull_entry`]).
-pub(crate) fn plan_pull(slug: &str) -> Result<PullPlan, PullError> {
+/// ([`plan_pull_entry`]). `max_bytes` is the largest pack this caller accepts —
+/// [`DISK_BUDGET_BYTES`] for an explicit pull, [`AUTO_PULL_MAX_BYTES`] for an
+/// automatic one.
+pub(crate) fn plan_pull(slug: &str, max_bytes: u64) -> Result<PullPlan, PullError> {
// 0. Validate the slug BEFORE it is ever joined into a filesystem path. The
// catalogue is accepted UNVERIFIED when no hub pubkey is configured, so a
// hostile `slug` ("../../etc") must be rejected here, ahead of every fs op.
@@ -857,7 +869,7 @@ pub(crate) fn plan_pull(slug: &str) -> Result<PullPlan, PullError> {
),
)
})?;
- plan_pull_entry(entry)
+ plan_pull_entry(entry, max_bytes)
}
/// Everything that can refuse to pull `entry`, checked in the order that costs
@@ -875,12 +887,22 @@ pub(crate) fn plan_pull(slug: &str) -> Result<PullPlan, PullError> {
/// a licence class, and a flag an agent can read in `--help` is not a human
/// decision. If an override is ever wanted it needs its own decision and its own
/// confirmation, not a switch here;
-/// 4. its advertised size is within [`AUTO_PULL_MAX_BYTES`] — a malicious hub must
-/// not OOM the client by advertising a huge pack (decision 2). The transfer is
-/// bounded again in [`fetch_to`] in case the field lies;
+/// 4. its advertised size is within `max_bytes` — a malicious hub must not OOM the
+/// client by advertising a huge pack (decision 2). The ceiling depends on who is
+/// pulling: an *automatic* pull (the `ask` flow) passes [`AUTO_PULL_MAX_BYTES`],
+/// so a question never silently drags down a large pack; an *explicit*
+/// `xerj hub pull <slug>` passes the larger [`DISK_BUDGET_BYTES`], because the
+/// person (or agent) naming the slug has asked for exactly this pack and the hub
+/// cannot keep a pack bigger than the whole cache anyway. The 50 MiB cap is on
+/// the implicit case, not on the command — the notice a build prints over the
+/// cap ("run `xerj hub pull <slug>`") now resolves to a command that works. The
+/// transfer is bounded again in [`fetch_to`] in case the field lies;
/// 5. there is a key to verify it with (exit [`E_NOKEY`]). Resolved before any temp
/// dir exists, so a pull with no key leaves nothing to re-fetch.
-pub(crate) fn plan_pull_entry(entry: &CatalogueEntry) -> Result<PullPlan, PullError> {
+pub(crate) fn plan_pull_entry(
+ entry: &CatalogueEntry,
+ max_bytes: u64,
+) -> Result<PullPlan, PullError> {
let slug = entry.slug.as_str();
if !valid_slug(slug) {
return Err(PullError::new(
@@ -903,12 +925,18 @@ pub(crate) fn plan_pull_entry(entry: &CatalogueEntry) -> Result<PullPlan, PullEr
),
));
}
- if entry.pack_bytes > AUTO_PULL_MAX_BYTES {
+ if entry.pack_bytes > max_bytes {
+ let hint = if max_bytes <= AUTO_PULL_MAX_BYTES {
+ "over the auto-pull cap; run `xerj hub pull` to fetch it explicitly"
+ } else {
+ "larger than the disk budget"
+ };
return Err(PullError::new(
E_INFRA,
format!(
- "pack '{slug}' is {} bytes, over the {}-byte auto-pull cap; not downloaded",
- entry.pack_bytes, AUTO_PULL_MAX_BYTES
+ "pack '{slug}' is {} bytes, over the {max_bytes}-byte limit for this pull \
+ ({hint}); not downloaded",
+ entry.pack_bytes
),
));
}
@@ -917,6 +945,7 @@ pub(crate) fn plan_pull_entry(entry: &CatalogueEntry) -> Result<PullPlan, PullEr
entry: entry.clone(),
pin8,
pubkey,
+ max_bytes,
})
}
@@ -965,7 +994,8 @@ pub(crate) fn pull_with(
let pack_dir = hub_home.join("packs").join(slug);
let _lock = PullLock::acquire(&pack_dir, slug, pin8, PULL_LOCK_WAIT, quiet)?;
- // Download pack + sig into a temp dir (size-capped). NOTHING is extracted.
+ // Download pack + sig into a temp dir (size-capped at the ceiling this pull was
+ // planned under — see `PullPlan::max_bytes`). NOTHING is extracted.
let tmp = pack_dir.join(format!("{pin8}.tmp"));
let extract = pack_dir.join(pin8);
let _ = fs::remove_dir_all(&tmp); // a stale temp from a crash must not poison this
@@ -974,7 +1004,7 @@ pub(crate) fn pull_with(
let archive = tmp.join(format!("{slug}-{pin8}.hubpack.tar.zst"));
let sig = tmp.join(format!("{slug}-{pin8}.hubpack.tar.zst.sig"));
let dl = (|| -> Result<u64> {
- let n = fetch_to(&entry.pack_url, &archive, AUTO_PULL_MAX_BYTES)
+ let n = fetch_to(&entry.pack_url, &archive, plan.max_bytes)
.with_context(|| format!("download pack {}", entry.pack_url))?;
fetch_to(&entry.sig_url, &sig, SIG_MAX_BYTES)
.with_context(|| format!("download sig {}", entry.sig_url))?;
@@ -2202,9 +2232,12 @@ mod tests {
// `xerj hub pull <slug>` is a command anyone can type — including from a
// hint an earlier run printed. Plan §11: an excluded licence class is never
// pulled. The refusal is the pull's, before any node, download or temp dir.
- let err = plan_pull_entry(&entry("gpl-thing", LicenceClass::Excluded, 1024))
- .err()
- .expect("refused");
+ let err = plan_pull_entry(
+ &entry("gpl-thing", LicenceClass::Excluded, 1024),
+ DISK_BUDGET_BYTES,
+ )
+ .err()
+ .expect("refused");
assert_eq!(err.code, 1, "a policy refusal, exit 1");
assert!(
err.message.contains("excluded licence class"),
@@ -2217,10 +2250,14 @@ mod tests {
"names the licence: {}",
err.message
);
- // Excluded wins over the size cap: the licence is the first thing said.
- let err = plan_pull_entry(&entry("gpl-thing", LicenceClass::Excluded, u64::MAX / 2))
- .err()
- .expect("refused");
+ // Excluded wins over the size cap: the licence is the first thing said,
+ // even for a pack far over any ceiling.
+ let err = plan_pull_entry(
+ &entry("gpl-thing", LicenceClass::Excluded, u64::MAX / 2),
+ DISK_BUDGET_BYTES,
+ )
+ .err()
+ .expect("refused");
assert!(
err.message.contains("excluded licence class"),
"{}",
@@ -2229,25 +2266,77 @@ mod tests {
}
#[test]
- fn pull_refuses_a_pack_over_the_cap_and_a_bad_slug_before_anything_else() {
- let err = plan_pull_entry(&entry(
+ fn the_size_ceiling_is_the_callers_not_a_fixed_cap() {
+ // A pack just over the 50 MiB auto-pull cap. Under the AUTOMATIC ceiling it
+ // is refused — a question must never silently drag it down — and the refusal
+ // points at the command that CAN fetch it.
+ let big = entry(
"big",
LicenceClass::AdaptWithAttribution,
AUTO_PULL_MAX_BYTES + 1,
- ))
- .err()
- .expect("refused");
+ );
+ let err = plan_pull_entry(&big, AUTO_PULL_MAX_BYTES)
+ .err()
+ .expect("auto-pull refuses an over-cap pack");
assert_eq!(err.code, 1);
assert!(err.message.contains("over the"), "{}", err.message);
+ assert!(
+ err.message.contains("xerj hub pull"),
+ "the refusal names the explicit escape hatch: {}",
+ err.message
+ );
- let err = plan_pull_entry(&entry("../../etc", LicenceClass::AdaptWithAttribution, 1))
+ // The SAME pack under the EXPLICIT ceiling (the disk budget) is NOT refused
+ // for its size: the person typing `xerj hub pull big` asked for exactly it.
+ // The only thing that may still stop it here is the key lookup (no hub key
+ // in a unit test) — never a size refusal. This is the fix: over-50-MiB
+ // corpora were previously unpullable by any route.
+ match plan_pull_entry(&big, DISK_BUDGET_BYTES) {
+ Ok(plan) => assert_eq!(plan.max_bytes, DISK_BUDGET_BYTES),
+ Err(e) => {
+ assert_eq!(
+ e.code, E_NOKEY,
+ "only a missing key may stop it: {}",
+ e.message
+ );
+ assert!(
+ !e.message.contains("not downloaded"),
+ "an explicit pull must not refuse on size: {}",
+ e.message
+ );
+ }
+ }
+
+ // A pack larger than the whole disk budget is refused even explicitly —
+ // it could not be stored — and says so.
+ let huge = entry(
+ "huge",
+ LicenceClass::AdaptWithAttribution,
+ DISK_BUDGET_BYTES + 1,
+ );
+ let err = plan_pull_entry(&huge, DISK_BUDGET_BYTES)
.err()
- .expect("refused");
+ .expect("over the disk budget is refused");
+ assert_eq!(err.code, 1);
+ assert!(err.message.contains("disk budget"), "{}", err.message);
+
+ let err = plan_pull_entry(
+ &entry("../../etc", LicenceClass::AdaptWithAttribution, 1),
+ DISK_BUDGET_BYTES,
+ )
+ .err()
+ .expect("refused");
assert_eq!(err.code, 2, "a malformed slug is exit 2");
let mut bad_pin = entry("ok", LicenceClass::AdaptWithAttribution, 1);
bad_pin.pin_sha = "not-a-commit".to_string();
- assert_eq!(plan_pull_entry(&bad_pin).err().expect("refused").code, 1);
+ assert_eq!(
+ plan_pull_entry(&bad_pin, DISK_BUDGET_BYTES)
+ .err()
+ .expect("refused")
+ .code,
+ 1
+ );
}
#[test]
@@ -2258,7 +2347,7 @@ mod tests {
LicenceClass::AdaptWithAttribution,
LicenceClass::ApproachOnly,
] {
- match plan_pull_entry(&entry("fine", class, 1024)) {
+ match plan_pull_entry(&entry("fine", class, 1024), DISK_BUDGET_BYTES) {
Ok(plan) => assert_eq!(plan.pin8, "0774d055"),
Err(e) => assert_eq!(
e.code, E_NOKEY,
diff --git a/engine/crates/xerj-hub/tests/pack_roundtrip.rs b/engine/crates/xerj-hub/tests/pack_roundtrip.rs
index 98631d5b9..23972d706 100644
--- a/engine/crates/xerj-hub/tests/pack_roundtrip.rs
+++ b/engine/crates/xerj-hub/tests/pack_roundtrip.rs
@@ -32,7 +32,7 @@ use xerj_hub::node::HubNode;
use xerj_hub::pack::{self, PackFileEntry};
use xerj_hub::{
Catalogue, CatalogueEntry, DefRecord, LicenceClass, PackIndex, PackManifest, PackSource,
- Sketch, AUTO_PULL_MAX_BYTES, CATALOGUE_FORMAT_VERSION, PACK_FORMAT_VERSION,
+ Sketch, AUTO_PULL_MAX_BYTES, CATALOGUE_FORMAT_VERSION, DISK_BUDGET_BYTES, PACK_FORMAT_VERSION,
};
const PIN_SHA: &str = "0774d05537f9762f838f7ab541b7765f1a729cb5";
@@ -587,19 +587,40 @@ async fn pack_build_pull_def_roundtrip() {
assert_eq!(after.hits[0].value.as_deref(), Some("128"));
}
- // ── A too-large advertised pack is refused BEFORE any download (DoS cap) ──
+ // ── Advertised over the AUTO-pull cap but under the disk budget: the EXPLICIT
+ // `xerj hub pull` fetches it. The 50 MiB cap is on the implicit auto-pull a
+ // question would trigger, not on the command a person (or an agent that was
+ // handed the hint) types — otherwise a corpus whose pack is over the cap
+ // would be unreachable by any route (hosted search is plan step 6/7). ──
{
- let hh = work.join("hub-cap");
+ let hh = work.join("hub-overcap");
write_catalogue_bytes(&hh, &archive, &good_sha, AUTO_PULL_MAX_BYTES + 1);
+ let rc = run_pull(&work.join("code-overcap"), &hh, Some(&public), &url_b).await;
+ assert_eq!(
+ rc, 0,
+ "an explicit pull fetches a pack over the auto-pull cap"
+ );
+ assert!(
+ hh.join("packs/mini-c").join(PIN8).exists(),
+ "the over-cap pack was extracted by the explicit pull"
+ );
+ }
+
+ // ── Advertised larger than the whole disk budget: refused BEFORE any download,
+ // even on an explicit pull (the DoS cap — a malicious hub must not OOM the
+ // client; the transfer is bounded again by `fetch_to` if the field lies). ──
+ {
+ let hh = work.join("hub-cap");
+ write_catalogue_bytes(&hh, &archive, &good_sha, DISK_BUDGET_BYTES + 1);
let rc = run_pull(&work.join("code-cap"), &hh, Some(&public), &url_b).await;
- assert_eq!(rc, 1, "over-cap pack → policy/infra exit 1");
+ assert_eq!(rc, 1, "over-budget pack → policy/infra exit 1");
assert!(
!hh.join("packs/mini-c").join(format!("{PIN8}.tmp")).exists(),
- "nothing downloaded over the cap"
+ "nothing downloaded over the budget"
);
assert!(
!hh.join("packs/mini-c").join(PIN8).exists(),
- "nothing extracted over the cap"
+ "nothing extracted over the budget"
);
}
diff --git a/tools/hub-packs/whole_hub_e2e.sh b/tools/hub-packs/whole_hub_e2e.sh
index 26346f7ad..7ff869542 100644
--- a/tools/hub-packs/whole_hub_e2e.sh
+++ b/tools/hub-packs/whole_hub_e2e.sh
@@ -30,6 +30,10 @@
# engine/crates/xerj-common/src/hub.rs in this checkout).
# --questions <file> the lz4 benchmark questions (default: e2e/lz4-questions.json).
# --only <slugs> restrict the per-corpus checks (a partial run never passes).
+# --strict the final gate: a catalogued corpus with no published pack
+# is a FAIL, not pending, and the catalogue count must equal
+# the published-pack count. Default (backfill climbing): a
+# not-yet-published corpus is pending, not a fail.
# --batch <n> corpora per fresh HOME + node (default 20).
# --no-sandbox run without bubblewrap (still an empty HOME and a cleared
# environment per phase). Default: every client phase runs in
@@ -46,12 +50,32 @@
# against). The tampered-CATALOGUE check uses the hub's own catalogue and
# signature, so in production mode it is a real-key check.
#
+# GREEN CRITERIA (what has to hold for exit 0 — the release gate)
+# The gate is GREEN when ALL of these hold:
+# 1. the catalogue loads, verifies against the client's embedded key, and
+# verifies independently with openssl;
+# 2. every corpus with a PUBLISHED pack is in the catalogue (a published pack
+# that is not catalogued is a hard fail — users could not discover it);
+# 3. every catalogued corpus that HAS a published pack passes pull + one --def
+# + one question (§12.3). A catalogued corpus whose pack is NOT published
+# yet is PENDING (skipped, reported, never a fail) — the backfill is still
+# climbing to 100% coverage; `--strict` turns pending into a fail;
+# 4. the lz4 benchmark questions route and answer with no corpus named;
+# 5. every documented failure path (hosted off/unreachable, offline,
+# over-the-auto-pull-cap, over-the-disk-budget) and both tamper checks give
+# their exact message and leave nothing extracted.
+# --strict additionally requires: 0 pending corpora, and the catalogue count to
+# equal the published-pack count (the spec §12.4 gate once the backfill is done).
+#
# OUTPUT (in --out)
# checks.jsonl one {check, result, signatures, detail} line per gate check
# rows/*.json one backfill-report row per catalogued corpus (hub_packs.py
-# `report --rows-dir` folds them into benchmarks/hub-backfill/)
-# GATE.md the human summary; homes/<phase>/ every phase's HOME and logs
-# Exit 0 only when every check passed and every catalogued corpus passed.
+# `report --rows-dir` folds them into benchmarks/hub-backfill/).
+# result is "e2e passed", "pending" (no published pack yet), or
+# "failed" (a published corpus that did not answer).
+# GATE.md the human summary (with the GREEN/RED verdict and these
+# criteria); homes/<phase>/ every phase's HOME and logs
+# Exit 0 only when the gate is GREEN by the criteria above.
#
# Never point --hub, XERJ_URL or anything else here at a node you care about: each
# client phase starts its own node (the automatic node, port >= 9300) in its own
@@ -70,12 +94,13 @@ MSG_KEEP_CACHE="keeping the cached copy"
MSG_HTML="not a signed catalogue; no catalogue is served at this address" # catalogue.rs fetch_and_store
MSG_OFFLINE_NOCAT="offline and no usable cached catalogue" # catalogue.rs load_catalogue
MSG_OFFLINE_NOPACK="--offline forbids downloading it" # ask.rs ask() step 5
-MSG_OVERCAP_ASK="MB limit for pulling a pack, so it is not downloaded" # ask.rs ask() pull policy
-MSG_OVERCAP_PULL="over the 52428800-byte auto-pull cap; not downloaded" # cli.rs plan_pull_entry
+MSG_OVERCAP_ASK="auto-pull cap, so a question does not download it automatically" # ask.rs ask() pull policy (#1784)
+MSG_OVERBUDGET_PULL="larger than the disk budget); not downloaded" # cli.rs plan_pull_entry (#1784)
MSG_TAMPER_SHA="pack sha256 mismatch" # pack.rs read_and_verify_pack
MSG_TAMPER_SIG="pack signature" # pack.rs read_and_verify_pack
MSG_TAMPER_CAT="catalogue signature did not verify" # catalogue.rs fetch_and_store
AUTO_PULL_MAX_BYTES=52428800 # xerj-common hub.rs
+DISK_BUDGET_BYTES=4294967296 # xerj-common hub.rs (explicit-pull ceiling, #1784)
# ═════════════════════════════════════════════════════════════════════════════
# INNER: one client phase, run inside the sandbox with a fresh HOME. Everything it
@@ -115,7 +140,38 @@ if [ "${1:-}" = "--inner" ]; then
-o -name '*.tmp' -o -name snapshot \) 2>/dev/null | head -n 3 || true)
[ -z "$found" ] && [ ! -e "$HOME/.xerj-code/state/$slug.json" ]
}
+ # <slug>'s pack WAS extracted (an explicit `hub pull` over the auto-pull cap now
+ # fetches it, #1784): the restored pack files are present under its packs dir.
+ extracted() {
+ local slug=$1
+ find "$HOME/.xerj/hub/packs/$slug" \( -name pack.json -o -name defs.jsonl \) 2>/dev/null | grep -q .
+ }
+ # Is <slug> one of the published packs this run was told about? When
+ # E2E_PUBLISHED is empty every catalogued corpus is treated as published
+ # (rehearsal builds its catalogue from exactly the packs it was given).
+ is_published() {
+ [ -z "${E2E_PUBLISHED:-}" ] && return 0
+ local s; for s in $E2E_PUBLISHED; do [ "$s" = "$1" ] && return 0; done; return 1
+ }
last_err() { tr '\n' ' ' < "$ERRF" | tr -s ' ' | cut -c1-200; }
+ # The automatic node's FIRST cold boot creates its console/system indices one by
+ # one; on a loaded machine that can exceed the client's hard-wired 60s boot wait
+ # (xerj-hub node.rs NODE_BOOT_TIMEOUT, not env-configurable), so the first
+ # node-starting command times out. The indices persist on disk, so the next boot
+ # just opens them and is fast. Retry a command that failed ONLY because the node
+ # was not healthy yet — never a verification, licence or match failure.
+ run_boot_retry() { # label cmd...
+ local label=$1; shift
+ local tries=${E2E_BOOT_TRIES:-5} n
+ for ((n = 1; n <= tries; n++)); do
+ run "$label" "$@"
+ [ "$RC" = 0 ] && return 0
+ grep -qE 'did not report a healthy cluster|has not answered on port|not answering on port' "$ERRF" 2>/dev/null || return "$RC"
+ echo " ($label: node still cold-booting, attempt $n/$tries)" >&2
+ sleep 3
+ done
+ return "$RC"
+ }
case "$PHASE" in
sync)
@@ -144,7 +200,14 @@ if [ "${1:-}" = "--inner" ]; then
"$cat" > "$R/rows/$slug.json" 2>/dev/null || echo "$base" > "$R/rows/$slug.json"
echo " $slug: $1${2:+ at $2}${3:+ ($3)}${4:+ $4}"
}
- run "pull-$slug" "$BIN" hub pull "$slug"
+ # A catalogued corpus whose pack is not published yet is PENDING, not a
+ # fail: skip it (no pull), record it, move on. The gate is 100% of the
+ # PUBLISHED corpora; full coverage follows the backfill (--strict fails it).
+ if ! is_published "$slug"; then
+ row pending "" "" "no published pack yet (backfill in progress); skipped"
+ continue
+ fi
+ run_boot_retry "pull-$slug" "$BIN" hub pull "$slug"
if [ "$RC" != 0 ]; then row failed pull "exit $RC: $(last_err)"; continue; fi
pin8=$(jq -r --arg s "$slug" '.corpora[] | select(.slug == $s) | .pin_sha[0:8]' "$HOME/.xerj/hub/catalogue.json")
defs="$HOME/.xerj/hub/packs/$slug/$pin8/defs.jsonl"
@@ -153,17 +216,17 @@ if [ "${1:-}" = "--inner" ]; then
SYM=$(jq -r .symbol <<<"$DEF")
def_ok() { [ "$RC" = 0 ] && jq -e --argjson d "$DEF" '.answered_from == "local_pack"
and ([.hits[]? | select(.file == $d.file and .line == $d.line)] | length) > 0' "$OUTF" >/dev/null 2>&1; }
- run "def-$slug" "$BIN" code "$slug" --def "$SYM" --json
+ # `xerj code <slug>` with no XERJ_URL finds the node `hub pull` restored
+ # into, through the hub ledger (#1729: node::resolve_pulled_node, never
+ # localhost:9200 for a pulled pack). The outer base env points XERJ_URL at a
+ # dead port so `hub pull` cannot restore into a node on :9200 — but that
+ # same var makes `code` skip the ledger and query the dead port, so it is
+ # cleared HERE with `env -u`, which is exactly a clean machine's state.
+ run "def-$slug" env -u XERJ_URL "$BIN" code "$slug" --def "$SYM" --json
if ! def_ok; then
why="--def $SYM did not return $(jq -r '"\(.file):\(.line)"' <<<"$DEF") from the local pack (exit $RC: $(last_err))"
- # Tell a broken pack from a client that cannot find the node the pull started
- # (`xerj code` resolves --url / XERJ_URL / localhost:9200 only): ask the
- # automatic node directly. The row still fails: a clean machine has no XERJ_URL.
port=$(cat "$HOME/.xerj/hub/node.port" 2>/dev/null || true)
- if [ -n "$port" ]; then
- run "def-$slug-autonode" env XERJ_URL="http://127.0.0.1:$port" "$BIN" code "$slug" --def "$SYM" --json
- def_ok && why="$why; the same call answers with XERJ_URL=<the automatic node, port $port>: xerj code does not find the node xerj hub pull started"
- fi
+ [ -n "$port" ] && why="$why; the automatic node the pull started is on port $port"
row failed def "$why"; continue
fi
ASK=$(jq -r --arg s "$slug" '.corpora[] | select(.slug == $s) | .ask_for' "$HOME/.xerj/hub/catalogue.json")
@@ -173,7 +236,7 @@ if [ "${1:-}" = "--inner" ]; then
[ -n "$WORDS" ] || WORDS=$slug
hit=""
for w in $WORDS; do
- run "q-$slug" "$BIN" code "$slug" "$w" --json
+ run "q-$slug" env -u XERJ_URL "$BIN" code "$slug" "$w" --json
if [ "$RC" = 0 ] && jq -e '[.. | objects | select((.file? // .path? // "") != "" and (.line? // .start_line? // null) != null)] | length > 0' "$OUTF" >/dev/null 2>&1; then
hit=$w; break
fi
@@ -187,6 +250,9 @@ if [ "${1:-}" = "--inner" ]; then
questions)
# Spec step 2 "done when", asked the step-5 way: `xerj "<question>"`, no corpus
# named, on a machine with no pack yet (the first question pulls it).
+ # Warm the node first so a slow cold boot does not fail the FIRST question
+ # (the counted questions then reuse the ready node, as a real session would).
+ run_boot_retry warmup "$BIN" hub pull "$E2E_QCORPUS" || true
total=$(jq '.tasks | length' "$E2E_QFILE"); ok=0; bad=""
for i in $(seq 0 $((total - 1))); do
q=$(jq -r ".tasks[$i].q" "$E2E_QFILE"); id=$(jq -r ".tasks[$i].id" "$E2E_QFILE")
@@ -298,14 +364,31 @@ if [ "${1:-}" = "--inner" ]; then
;;
overcap)
+ # #1784: a question does NOT auto-pull an over-cap pack — it refuses with the
+ # auto-pull-cap message and now NAMES `xerj hub pull` — but an explicit
+ # `xerj hub pull` DOES fetch it (its ceiling is the 4 GiB disk budget, not the
+ # 50 MiB auto-pull cap), so the pack is downloaded and extracted.
run sync "$BIN" hub sync
run ask "$BIN" ask --corpus "$E2E_TARGET" "$E2E_TARGET"; a=$RC; ae=$ERRF
+ run_boot_retry pull "$BIN" hub pull "$E2E_TARGET"
+ if [ "$a" = 1 ] && has "$MSG_OVERCAP_ASK" "$ae" && has "xerj hub pull" "$ae" \
+ && [ "$RC" = 0 ] && extracted "$E2E_TARGET"; then
+ check over-the-cap 0 "pack_bytes $((AUTO_PULL_MAX_BYTES + 1)): ask exit 1 '…$MSG_OVERCAP_ASK…' and names the explicit pull; hub pull exit 0 and the pack is extracted (#1784)"
+ else
+ check over-the-cap 1 "ask exit $a (cap msg: $(has "$MSG_OVERCAP_ASK" "$ae" && echo yes || echo no)), pull exit $RC: $(last_err)"
+ fi
+ ;;
+
+ overbudget)
+ # #1784: even an explicit `xerj hub pull` refuses a pack advertised LARGER
+ # than the whole disk budget (4 GiB) — and refuses before any node is started
+ # or any byte is downloaded (the check is on the advertised pack_bytes).
+ run sync "$BIN" hub sync
run pull "$BIN" hub pull "$E2E_TARGET"
- if [ "$a" = 1 ] && has "$MSG_OVERCAP_ASK" "$ae" && [ "$RC" != 0 ] && has "$MSG_OVERCAP_PULL" "$ERRF" \
- && nothing_extracted "$E2E_TARGET"; then
- check over-the-cap 0 "pack_bytes $((AUTO_PULL_MAX_BYTES + 1)): ask exit 1 '$(head -c 160 "$ae")', pull exit $RC '…$MSG_OVERCAP_PULL'; nothing downloaded"
+ if [ "$RC" != 0 ] && has "$MSG_OVERBUDGET_PULL" "$ERRF" && nothing_extracted "$E2E_TARGET"; then
+ check over-the-budget 0 "pack_bytes $((DISK_BUDGET_BYTES + 1)): hub pull exit $RC '…$MSG_OVERBUDGET_PULL'; nothing downloaded or extracted"
else
- check over-the-cap 1 "sync/ask/pull: ask exit $a, pull exit $RC: $(last_err)"
+ check over-the-budget 1 "pull exit $RC: $(last_err)"
fi
;;
@@ -342,7 +425,7 @@ fi
# ═════════════════════════════════════════════════════════════════════════════
usage() { sed -n '2,60p' "$SELF" >&2; exit 2; }
BIN="" OUT="" HUB="https://hub.xerj.org" REPO="xerj-org/xerj" EXPECT="" REHEARSE="" REGISTRY="" BACKLOG=""
-ASSETS="" PUBKEY="" QFILE="$HERE/e2e/lz4-questions.json" ONLY="" BATCH=20 SANDBOX=1 RUN_ID="" PORT=19530
+ASSETS="" PUBKEY="" QFILE="$HERE/e2e/lz4-questions.json" ONLY="" BATCH=20 SANDBOX=1 RUN_ID="" PORT=19530 STRICT=0
while [ $# -gt 0 ]; do
case "$1" in
--bin) BIN=$2; shift 2 ;;
@@ -357,6 +440,7 @@ while [ $# -gt 0 ]; do
--pubkey) PUBKEY=$2; shift 2 ;;
--questions) QFILE=$2; shift 2 ;;
--only) ONLY=$2; shift 2 ;;
+ --strict) STRICT=1; shift ;;
--batch) BATCH=$2; shift 2 ;;
--no-sandbox) SANDBOX=0; shift ;;
--run-id) RUN_ID=$2; shift 2 ;;
@@ -493,8 +577,9 @@ phase() { # phase-name home-name [env...] -- [args...]
MSG_HOSTED_OFF="$MSG_HOSTED_OFF" MSG_NO_HOSTED_CLIENT="$MSG_NO_HOSTED_CLIENT" MSG_NO_CACHE="$MSG_NO_CACHE"
MSG_KEEP_CACHE="$MSG_KEEP_CACHE" MSG_HTML="$MSG_HTML" MSG_OFFLINE_NOCAT="$MSG_OFFLINE_NOCAT"
MSG_OFFLINE_NOPACK="$MSG_OFFLINE_NOPACK" MSG_OVERCAP_ASK="$MSG_OVERCAP_ASK"
- MSG_OVERCAP_PULL="$MSG_OVERCAP_PULL" MSG_TAMPER_SHA="$MSG_TAMPER_SHA" MSG_TAMPER_SIG="$MSG_TAMPER_SIG"
- MSG_TAMPER_CAT="$MSG_TAMPER_CAT" AUTO_PULL_MAX_BYTES="$AUTO_PULL_MAX_BYTES")
+ MSG_OVERBUDGET_PULL="$MSG_OVERBUDGET_PULL" MSG_TAMPER_SHA="$MSG_TAMPER_SHA" MSG_TAMPER_SIG="$MSG_TAMPER_SIG"
+ MSG_TAMPER_CAT="$MSG_TAMPER_CAT" AUTO_PULL_MAX_BYTES="$AUTO_PULL_MAX_BYTES" DISK_BUDGET_BYTES="$DISK_BUDGET_BYTES"
+ E2E_PUBLISHED="${PUBLISHED:-}")
[ -n "$CLIENT_KEY" ] && base+=(XERJ_HUB_PUBKEY="$CLIENT_KEY")
base+=("${envs[@]}")
echo "-- phase $name (HOME $home)"
@@ -531,16 +616,29 @@ else
fi
got=$(jq '.corpora | length' "$OUT/catalogue.json")
CAT_SLUGS=$(jq -r '.corpora[].slug' "$OUT/catalogue.json" | sort -u)
- detail="catalogue lists $got corpora; $EXPECT corpora have a published pack"
+ # A PUBLISHED pack that is not catalogued is always a hard fail (users could not
+ # discover it). A CATALOGUED corpus with no published pack yet is PENDING: fine
+ # by default (the backfill is still climbing to full coverage), a fail only under
+ # --strict, which is the spec §12.4 gate for the final, fully-backfilled release.
+ miss=""; extra=""; n_pending=0
if [ -n "${EXPECT_SLUGS:-}" ]; then
miss=$(comm -13 <(echo "$CAT_SLUGS") <(tr ' ' '\n' <<<"$EXPECT_SLUGS" | grep . | sort -u) | tr '\n' ' ')
extra=$(comm -23 <(echo "$CAT_SLUGS") <(tr ' ' '\n' <<<"$EXPECT_SLUGS" | grep . | sort -u) | tr '\n' ' ')
- [ -n "$miss" ] && detail="$detail; published but not catalogued: $miss"
- [ -n "$extra" ] && detail="$detail; catalogued without a published pack: $extra"
+ n_pending=$(echo $extra | wc -w)
+ fi
+ detail="catalogue lists $got corpora; $EXPECT have a published pack; $n_pending catalogued without a published pack yet (pending)"
+ [ -n "$miss" ] && detail="$detail; PUBLISHED BUT NOT CATALOGUED: $miss"
+ if [ "$STRICT" = 1 ]; then
+ detail="$detail [--strict: count must equal published, 0 pending]"
+ ccok=$([ -z "$miss" ] && [ -z "$extra" ] && [ "$got" = "$EXPECT" ] && echo 0 || echo 1)
+ else
+ ccok=$([ -z "$miss" ] && echo 0 || echo 1)
fi
- check catalogue-count-equals-published "$([ "$got" = "$EXPECT" ] && [ -z "${miss:-}${extra:-}" ] && echo 0 || echo 1)" "$detail"
+ check catalogue-count-equals-published "$ccok" "$detail"
- # 2. Every catalogued corpus: pull + one --def + one question (§12.3 again).
+ # 2. Every catalogued corpus: pull + one --def + one question (§12.3 again). The
+ # PUBLISHED set is passed to the phase so a not-yet-published corpus is pending.
+ PUBLISHED="${EXPECT_SLUGS:-}"
SLUGS=$CAT_SLUGS
if [ -n "$ONLY" ]; then SLUGS=$(tr ',' '\n' <<<"$ONLY" | grep -xF -f <(echo "$CAT_SLUGS") || true); fi
mapfile -t ALL <<<"$SLUGS"
@@ -559,9 +657,19 @@ else
done
n_rows=$(ls "$OUT/rows" | wc -l)
n_pass=$(cat "$OUT/rows/"*.json 2>/dev/null | jq -s '[.[] | select(.result == "e2e passed")] | length')
- partial=""; [ -n "$ONLY" ] && partial=" (PARTIAL: --only $ONLY; the gate is every catalogued corpus)"
- check every-corpus-pull-def-question "$([ "$n_pass" = "$got" ] && [ -z "$ONLY" ] && echo 0 || echo 1)" \
- "$n_pass of $got catalogued corpora passed pull + --def + one question$partial"
+ n_pend=$(cat "$OUT/rows/"*.json 2>/dev/null | jq -s '[.[] | select(.result == "pending")] | length')
+ n_cfail=$(cat "$OUT/rows/"*.json 2>/dev/null | jq -s '[.[] | select(.result != "e2e passed" and .result != "pending")] | length')
+ partial=""; [ -n "$ONLY" ] && partial=" (PARTIAL: --only $ONLY; the gate is every PUBLISHED corpus)"
+ # GREEN when no PUBLISHED corpus failed. Pending (not-yet-published) is allowed
+ # by default; --strict requires 0 pending too (every catalogued corpus passed).
+ if [ "$STRICT" = 1 ]; then
+ ecok=$([ "$n_cfail" = 0 ] && [ "$n_pend" = 0 ] && [ -z "$ONLY" ] && echo 0 || echo 1)
+ partial="$partial [--strict: pending is a fail]"
+ else
+ ecok=$([ "$n_cfail" = 0 ] && [ -z "$ONLY" ] && echo 0 || echo 1)
+ fi
+ check every-corpus-pull-def-question "$ecok" \
+ "$n_pass passed, $n_pend pending (no published pack yet), $n_cfail failed of $got catalogued corpora$partial"
# 3. `xerj "<question>"`, no corpus named: the lz4 benchmark questions.
QCORPUS=$(jq -r .corpus "$QFILE")
@@ -590,6 +698,7 @@ else
}
T="file://$OUT/lab/target"
lab_catalogue overcap "(.corpora[] | select(.slug == \$s) | .pack_bytes) = $((AUTO_PULL_MAX_BYTES + 1))"
+ lab_catalogue overbudget "(.corpora[] | select(.slug == \$s) | .pack_bytes) = $((DISK_BUDGET_BYTES + 1))"
lab_catalogue tamper-sha "(.corpora[] | select(.slug == \$s)) |= (.pack_url = \"$T/tampered-$file\" | .sig_url = \"$T/$file.sig\")"
lab_catalogue tamper-sig "(.corpora[] | select(.slug == \$s)) |= (.pack_url = \"$T/tampered-$file\" | .sig_url = \"$T/$file.sig\" | .pack_sha256 = \"$bad_sha\")"
mkdir -p "$OUT/site/tampered/api/v1"
@@ -600,6 +709,7 @@ else
phase html html
phase offline offline
SIG=lab phase overcap overcap XERJ_HUB_URL="$LOCAL/overcap" XERJ_HUB_PUBKEY="$LAB_PUB"
+ SIG=lab phase overbudget overbudget XERJ_HUB_URL="$LOCAL/overbudget" XERJ_HUB_PUBKEY="$LAB_PUB"
SIG=lab phase tamper-sha tamper-sha XERJ_HUB_URL="$LOCAL/tamper-sha" XERJ_HUB_PUBKEY="$LAB_PUB"
SIG=lab phase tamper-sig tamper-sig XERJ_HUB_URL="$LOCAL/tamper-sig" XERJ_HUB_PUBKEY="$LAB_PUB"
phase tamper-catalogue tamper-catalogue XERJ_HUB_URL="$LOCAL/tampered"
@@ -608,21 +718,31 @@ fi
# ── fold ────────────────────────────────────────────────────────────────────
n_fail=$(jq -s '[.[] | select(.result != "pass")] | length' "$CHECKS")
n_all=$(jq -s length "$CHECKS")
+rp_pass=$(cat "$OUT/rows/"*.json 2>/dev/null | jq -s '[.[] | select(.result == "e2e passed")] | length' 2>/dev/null || echo 0)
+rp_pend=$(cat "$OUT/rows/"*.json 2>/dev/null | jq -s '[.[] | select(.result == "pending")] | length' 2>/dev/null || echo 0)
+rp_fail=$(cat "$OUT/rows/"*.json 2>/dev/null | jq -s '[.[] | select(.result != "e2e passed" and .result != "pending")] | length' 2>/dev/null || echo 0)
+verdict=$([ "$n_fail" = 0 ] && echo "GREEN" || echo "RED")
{
echo "# Hub v2 whole-hub end-to-end (spec §12.4)"
echo
- echo "- run: \`$RUN_ID\` ($DATE), mode: **$MODE**, hub: \`$HUB_UNDER_TEST\`"
+ echo "## GATE: $verdict"
+ echo
+ echo "- run: \`$RUN_ID\` ($DATE), mode: **$MODE**, hub: \`$HUB_UNDER_TEST\`$([ "$STRICT" = 1 ] && echo ', **--strict**')"
echo "- binary: \`$("$BIN" --version 2>/dev/null | head -n 1 || echo "$BIN")\`, embedded key \`$PUBKEY\`"
[ "$MODE" = rehearsal ] && echo "- rehearsal: the client verified a throwaway key \`$LAB_PUB\` (packs re-signed); \`signatures: real\` rows used the real key"
echo "- sandbox: $([ "$SANDBOX" = 1 ] && echo "benchmarks/hub-pov/sandbox.sh, a fresh HOME per phase" || echo "none (--no-sandbox); a fresh HOME and cleared env per phase")"
echo
- echo "**$((n_all - n_fail)) of $n_all checks passed.**"
+ echo "**$((n_all - n_fail)) of $n_all gate checks passed.** Per corpus: **$rp_pass passed, $rp_pend pending, $rp_fail failed.**"
+ echo
+ echo "Green criteria (exit 0): every gate check below passes. A corpus with a"
+ echo "published pack must pass pull + \`--def\` + one question; a catalogued corpus"
+ echo "with no published pack yet is *pending*, not a fail$([ "$STRICT" = 1 ] && echo ", EXCEPT under --strict (pending is a fail and the catalogue count must equal the published-pack count)" || echo " (the backfill is still climbing to 100% coverage; --strict is the final gate)")."
echo
echo "| check | result | signatures | detail |"
echo "|---|---|---|---|"
jq -r '"| `\(.check)` | \(.result) | \(.signatures) | \(.detail | gsub("\\|"; "\\\\|")) |"' "$CHECKS"
echo
- echo "## Per corpus"
+ echo "## Per corpus (result: \`e2e passed\` / \`pending\` = no published pack yet / \`failed\`)"
echo
echo "| slug | pin8 | bytes | result | detail |"
echo "|---|---|---:|---|---|"