@rightkit/release 0.3.0 → 0.4.1

package/runtime-budget-crates.mjs

@@ -0,0 +1,14 @@
+// The continuous owners that must carry a runtime budget (docs/RUNTIME-BUDGETS.md). Kept free of
+// dependencies so the secretless publish plan job can check the runtime proof table against it.
+export const RUNTIME_BUDGET_CRATES = Object.freeze([
+  "rightkit-fsindex",
+  "rightkit-file-watch",
+  "rightkit-job-queue",
+  "rightkit-daemon",
+  "rightkit-cache",
+  "rightkit-sync",
+  "rightkit-logs",
+  "rightkit-tauri-shell",
+  "rightkit-qa",
+  "rightkit-send",
+]);

package/runtime-budgets.mjs

@@ -18,6 +18,8 @@
 //     "hostPolicyReason": "no Windows backend",
 //     "ceilings": { "residentMemoryBytes": N, "idleCpuPercent": N, "wakeupsPerSecond": N, "diskOpsPerSecond": N },  // null = undeclared, refused
 //     "ceilingSources": { "residentMemoryBytes": "path:line" },
+//     "ceilingBasis": { "wakeupsPerSecond": "delta-over-bare" },   // optional; see "Delta basis" below
+//     "deltaCeilings": { "wakeupsPerSecond": N },                  // required for, and only for, a figure with a delta basis
 //     "requiredScale": { "unit": "entries", "minCount": 1000000, "source": "path:line" },  // null = undeclared, refused
 //     "status": { "api": "Index::status()", "file": "src/index.rs", "exposes": ["residentMemoryBytes", ...] },
 //     "measurements": [ {
@@ -32,8 +34,20 @@
 // Measurements are written by `node runtime-budgets.mjs record`, never typed: the raw bench output is
 // stored under runtime-budget.evidence/, and the gate re-parses it and compares every value.
 //
+// Delta basis. A whole-process wake-up rate on a desktop host is dominated by host and window-server
+// activity the crate does not own. A crate may declare `ceilingBasis.wakeupsPerSecond = "delta-over-bare"`:
+// its synthetic bench then measures the crate's workload and a bare runtime loop back to back (separate
+// processes), and the gate compares (wake-ups - bare wake-ups), computed here from the two raw figures,
+// to `deltaCeilings.wakeupsPerSecond`. A synthetic measurement of that crate must carry `baseline` and
+// `delta` (`{ wakeupsPerSecond }`); one without a baseline is refused, and a reported delta that differs
+// from raw minus bare is refused (the gate never trusts it). `ceilings.wakeupsPerSecond` stays the
+// whole-process ceiling and keeps governing every other scope (real, installed) and app adoption, so an
+// installed app is never compared to a delta ceiling and nothing weakens for apps. Measurements of
+// other versions are history and are not re-gated, so they need no baseline.
+//
 // Bench output the `record` command accepts (exactly one such line in the file):
 //   RESULT budget crate=<name> version=<semver> resident_bytes=<int> idle_cpu_percent=<n> wakeups_per_s=<n> disk_ops_per_s=<n> scale_unit=<word> scale_count=<int>
+// optionally followed by `bare_wakeups_per_s=<n> wakeups_delta_per_s=<n>` (both or neither; delta may be negative).
 //
 // Check objects use the preflight shape ({ name, status, detail, fix }) so formatPreflight() in
 // preflight.mjs prints them as `[FAIL] runtime-budget: ...`.
@@ -45,7 +59,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { parse } from "smol-toml";
-import { isDarwinOnlyPolicy } from "./publication-gate.mjs";
+import { RUNTIME_BUDGET_CRATES } from "./runtime-budget-crates.mjs";
+import { singleHostOfPolicy } from "./publication-gate.mjs";
 import { findWorkspaceRoot, lockClosure, pathDependencyDirs, readCargoPackage } from "./crate-graph.mjs";
 
 export const RUNTIME_BUDGET_CHECK = "runtime-budget";
@@ -54,18 +69,7 @@ export const RUNTIME_BUDGET_FILE = "runtime-budget.json";
 export const RUNTIME_BUDGET_EVIDENCE_DIR = "runtime-budget.evidence";
 export const RUNTIME_BUDGET_SCHEMA = 1;
 
-export const RUNTIME_BUDGET_CRATES = Object.freeze([
-  "rightkit-fsindex",
-  "rightkit-file-watch",
-  "rightkit-job-queue",
-  "rightkit-daemon",
-  "rightkit-cache",
-  "rightkit-sync",
-  "rightkit-logs",
-  "rightkit-tauri-shell",
-  "rightkit-qa",
-  "rightkit-send",
-]);
+export { RUNTIME_BUDGET_CRATES };
 
 export const BUDGET_FIGURES = Object.freeze(["residentMemoryBytes", "idleCpuPercent", "wakeupsPerSecond", "diskOpsPerSecond"]);
 const FIGURE_LABEL = Object.freeze({
@@ -83,6 +87,14 @@ const HOSTS = Object.freeze({ darwin: "macOS", win32: "Windows" });
 const SHA = /^[0-9a-f]{40}$/;
 const SHA256 = /^[0-9a-f]{64}$/;
 const SCOPES = Object.freeze(["synthetic", "real", "installed"]);
+// Figures that may be gated as a delta over a bare-runtime baseline, and the only scope that carries one.
+export const CEILING_BASIS_DELTA = "delta-over-bare";
+export const DELTA_FIGURES = Object.freeze(["wakeupsPerSecond"]);
+const DELTA_SCOPE = "synthetic";
+// Each rate is printed to 3 decimals, so raw - bare and the printed delta may differ by rounding only.
+const DELTA_TOLERANCE = 0.002;
+// A baseline more than this far above its own watchdog run is a mismatched or corrupt pair, not a quiet crate.
+const DELTA_FLOOR = -2;
 
 // Long-lived work a crate must declare. Each id must be named in `continuous_reason` for a `continuous = false`
 // crate; for a held-resource crate every file that matches must be listed in `resources`.
@@ -132,7 +144,8 @@ export function isRuntimeBudgetCrate(crate, manifestText) {
 
 /** Hosts the budget must be measured on. `evidence` (release evidence) is the policy authority when given. */
 export function requiredBudgetHosts(budget, evidence) {
-  return isDarwinOnlyPolicy(evidence ?? budget) ? ["darwin"] : ["darwin", "win32"];
+  const single = singleHostOfPolicy(evidence ?? budget);
+  return single ? [single] : ["darwin", "win32"];
 }
 
 // ---------------------------------------------------------------- README view (generated from the JSON)
@@ -183,7 +196,10 @@ export function renderRuntimeBudgetBody(budget) {
   out.push("");
   out.push(`- Resident memory ceiling: ${figure("residentMemoryBytes", budget.ceilings?.residentMemoryBytes)}.`);
   out.push(`- CPU ceiling (idle, steady state): ${figure("idleCpuPercent", budget.ceilings?.idleCpuPercent)}.`);
-  out.push(`- Wake-ups ceiling: ${figure("wakeupsPerSecond", budget.ceilings?.wakeupsPerSecond)}.`);
+  if (budget.ceilingBasis?.wakeupsPerSecond === CEILING_BASIS_DELTA) {
+    out.push(`- Wake-ups ceiling (whole process; installed and real measurements): ${figure("wakeupsPerSecond", budget.ceilings?.wakeupsPerSecond)}.`);
+    out.push(`- Wake-ups gate (synthetic bench): at most ${figure("wakeupsPerSecond", budget.deltaCeilings?.wakeupsPerSecond)} over a bare runtime loop measured in the same bench run.`);
+  } else out.push(`- Wake-ups ceiling: ${figure("wakeupsPerSecond", budget.ceilings?.wakeupsPerSecond)}.`);
   out.push(`- Disk operations ceiling: ${figure("diskOpsPerSecond", budget.ceilings?.diskOpsPerSecond)}.`);
   const rs = budget.requiredScale;
   out.push(rs && rs.unit && Number.isFinite(rs.minCount) ? `- Required scale: ${count(rs.minCount)} ${rs.unit} or more.` : "- Required scale: undeclared.");
@@ -200,7 +216,9 @@ export function renderRuntimeBudgetBody(budget) {
     const scale = `${count(m.dataScale?.count)} ${m.dataScale?.unit} (${m.dataScale?.description})`;
     const app = m.scope === "installed" && m.app ? `, app ${m.app.name} ${m.app.version}` : "";
     const observed = BUDGET_FIGURES.map((k) => `${FIGURE_LABEL[k]} ${m.observed?.[k] === undefined || m.observed?.[k] === null ? "n/a (not measurable on this host)" : FORMAT[k](m.observed[k])}`).join(", ");
-    out.push(`- Measured: ${host}, ${budget.crate} ${m.crateVersion} at ${String(m.commit).slice(0, 12)}, ${scale}, ${m.scope}${app}, \`${m.command}\`, ${m.date}, evidence ${String(m.evidence?.sha256 ?? "none").slice(0, 12)}: ${observed}.`);
+    const bare = isNumber(m.baseline?.wakeupsPerSecond) && isNumber(m.delta?.wakeupsPerSecond)
+      ? `; bare baseline wake-ups ${FORMAT.wakeupsPerSecond(m.baseline.wakeupsPerSecond)}, delta ${FORMAT.wakeupsPerSecond(m.delta.wakeupsPerSecond)}` : "";
+    out.push(`- Measured: ${host}, ${budget.crate} ${m.crateVersion} at ${String(m.commit).slice(0, 12)}, ${scale}, ${m.scope}${app}, \`${m.command}\`, ${m.date}, evidence ${String(m.evidence?.sha256 ?? "none").slice(0, 12)}: ${observed}${bare}.`);
   }
   return out;
 }
@@ -232,17 +250,86 @@ const posix = (p) => p.split(path.sep).join("/");
 /**
  * The git pathspecs (relative to the workspace root) whose change makes a measurement stale: the
  * crate's src, benches, Cargo.toml (features) and build.rs, plus src, Cargo.toml and build.rs of every
- * workspace crate it reaches through `path` dependencies (transitively). Returns { root, specs }.
+ * workspace crate it reaches through `path` dependencies (transitively). Returns { root, specs, problems }.
+ * Callers must refuse incomplete metadata rather than using a partial dependency scope.
  */
 export function measuredPathspecs(crateDir, deps = {}) {
-  const root = findWorkspaceRoot(crateDir, deps) ?? path.resolve(crateDir);
+  const { exists = existsSync, readFile = readFileSync } = deps;
+  const problems = [];
+  // Workspace discovery deliberately tolerates bad ancestor manifests elsewhere. Freshness cannot:
+  // a swallowed read/parse failure could hide inherited dependencies and shrink the measured graph.
+  const checkedRead = (file, encoding) => {
+    try {
+      const contents = readFile(file, encoding);
+      if (path.basename(file) === "Cargo.toml") parse(contents);
+      return contents;
+    } catch (error) {
+      problems.push(`cannot read dependency metadata ${file}: ${error.message}`);
+      throw error;
+    }
+  };
+  const checked = { exists, readFile: checkedRead };
+  let root = path.resolve(crateDir);
   const specs = [];
   const add = (dir, names) => { for (const name of names) specs.push(posix(path.relative(root, path.join(dir, name)))); };
-  add(path.resolve(crateDir), CRATE_PATHS);
-  let dependencies = [];
-  try { dependencies = pathDependencyDirs(crateDir, deps); } catch { /* unreadable manifest: the crate paths alone */ }
-  for (const dir of dependencies) add(dir, DEPENDENCY_PATHS);
-  return { root, specs: [...new Set(specs)] };
+  try {
+    root = findWorkspaceRoot(crateDir, checked) ?? root;
+    add(path.resolve(crateDir), CRATE_PATHS);
+    const dependencies = pathDependencyDirs(crateDir, checked);
+    const workspace = exists(path.join(root, "Cargo.toml")) ? parse(checkedRead(path.join(root, "Cargo.toml"), "utf8")).workspace : undefined;
+    for (const dir of [path.resolve(crateDir), ...dependencies]) {
+      const manifestPath = path.join(dir, "Cargo.toml");
+      if (!exists(manifestPath)) {
+        // A manifest-free standalone path has no Cargo graph. A declared path dependency must exist.
+        if (dir !== path.resolve(crateDir)) problems.push(`dependency manifest is missing: ${manifestPath}`);
+        continue;
+      }
+      const manifest = parse(checkedRead(manifestPath, "utf8"));
+      if (!nonEmpty(manifest.package?.name)) problems.push(`dependency manifest has no package.name: ${manifestPath}`);
+      const holders = [manifest, ...Object.values(manifest.target ?? {})];
+      for (const holder of holders) {
+        for (const key of ["dependencies", "build-dependencies", ...(dir === path.resolve(crateDir) ? ["dev-dependencies"] : [])]) {
+          for (const [name, spec] of Object.entries(holder?.[key] ?? {})) {
+            if (spec && typeof spec === "object" && spec.workspace === true && workspace?.dependencies?.[name] === undefined) {
+              problems.push(`workspace dependency ${name} cannot be resolved for ${manifestPath}`);
+            }
+          }
+        }
+      }
+    }
+    for (const dir of dependencies) add(dir, DEPENDENCY_PATHS);
+  } catch (error) {
+    if (!problems.length) problems.push(`cannot resolve measured dependency paths for ${crateDir}: ${error.message}`);
+  }
+  return { root, specs: [...new Set(specs)], problems: [...new Set(problems)] };
+}
+
+// lockClosure compares reachable entries, but its permissive parser can return an empty/partial graph.
+// Require the root and every reachable edge before allowing equality to establish freshness.
+function completeLockClosure(contents, name) {
+  const packages = parse(contents).package;
+  if (!Array.isArray(packages)) throw new Error("missing [[package]] entries");
+  const roots = packages.filter((entry) => entry.name === name);
+  if (!roots.length) throw new Error(`missing package ${name}`);
+  const seen = new Set();
+  const pending = [...roots];
+  while (pending.length) {
+    const entry = pending.pop();
+    if (seen.has(entry)) continue;
+    seen.add(entry);
+    if (!nonEmpty(entry.name) || !nonEmpty(entry.version)) throw new Error(`incomplete package identity for ${entry.name ?? name}`);
+    if (entry.dependencies !== undefined && !Array.isArray(entry.dependencies)) throw new Error(`invalid dependencies for ${entry.name}`);
+    for (const edge of entry.dependencies ?? []) {
+      if (!nonEmpty(edge)) throw new Error(`invalid dependency edge for ${entry.name}`);
+      const match = /^(\S+)(?: (\S+))?(?: \(([^)]+)\))?$/.exec(edge);
+      if (!match) throw new Error(`invalid dependency ${edge} of ${entry.name}`);
+      const candidates = packages.filter((candidate) => candidate.name === match[1]
+        && (!match[2] || candidate.version === match[2]) && (!match[3] || candidate.source === match[3]));
+      if (!candidates.length) throw new Error(`unresolved dependency ${edge} of ${entry.name}`);
+      pending.push(...candidates);
+    }
+  }
+  return lockClosure(contents, name);
 }
 
 /**
@@ -261,7 +348,8 @@ export function measurementStaleness(commit, crateDir, git = defaultGit, deps =
   const known = git(["cat-file", "-t", commit], crateDir);
   if (known.status !== 0 || known.stdout !== "commit") return `commit ${commit.slice(0, 12)} is not a commit in this repository (shallow clone?)`;
   if (git(["merge-base", "--is-ancestor", commit, "HEAD"], crateDir).status !== 0) return `commit ${commit.slice(0, 12)} is not an ancestor of HEAD`;
-  const { root, specs } = measuredPathspecs(crateDir, { exists, readFile });
+  const { root, specs, problems } = measuredPathspecs(crateDir, { exists, readFile });
+  if (problems.length) return `cannot resolve measured dependency graph: ${problems.join("; ")}`;
   // `git diff <commit>` (no second revision) compares the working tree to the commit.
   const changed = git(["diff", "--name-only", commit, "--", ...specs], root);
   if (changed.status !== 0) return "cannot diff the crate against the measured commit";
@@ -270,17 +358,29 @@ export function measurementStaleness(commit, crateDir, git = defaultGit, deps =
   if (untracked.status !== 0) return "cannot list untracked crate files";
   if (untracked.stdout !== "") return `untracked files since the measurement: ${untracked.stdout.split("\n").slice(0, 5).join(", ")}`;
   let name = null;
-  try { name = readCargoPackage(crateDir, { exists, readFile }).name; } catch { /* no manifest: nothing to resolve in the lock */ }
+  try {
+    if (exists(path.join(crateDir, "Cargo.toml"))) {
+      name = readCargoPackage(crateDir, { exists, readFile }).name;
+      if (!nonEmpty(name)) return `cannot resolve Cargo.lock: ${path.join(crateDir, "Cargo.toml")} has no package.name`;
+    }
+  } catch (error) { return `cannot resolve Cargo.lock package identity: ${error.message}`; }
   if (name) {
     const lockPath = path.join(root, "Cargo.lock");
-    const now = exists(lockPath) ? readFile(lockPath, "utf8") : null;
+    let now;
+    try { now = exists(lockPath) ? readFile(lockPath, "utf8") : null; }
+    catch (error) { return `cannot read Cargo.lock ${lockPath}: ${error.message}`; }
     const then = git(["show", `${commit}:./Cargo.lock`], root);
     const had = then.status === 0;
     if (now === null && had) return "Cargo.lock was removed since the measurement";
     if (now !== null && !had) return "Cargo.lock did not exist at the measured commit";
+    if (now === null && !had) {
+      // A failed show alone cannot distinguish an absent lock from an unreadable Git object.
+      const listed = git(["ls-tree", commit, "--", "Cargo.lock"], root);
+      if (listed.status !== 0 || listed.stdout !== "") return "cannot establish that Cargo.lock was absent at the measured commit";
+    }
     if (now !== null) {
       try {
-        if (JSON.stringify(lockClosure(now, name)) !== JSON.stringify(lockClosure(then.stdout, name))) {
+        if (JSON.stringify(completeLockClosure(now, name)) !== JSON.stringify(completeLockClosure(then.stdout, name))) {
           return `Cargo.lock changed in the dependency graph of ${name} since commit ${commit.slice(0, 12)}`;
         }
       } catch (error) { return `cannot compare Cargo.lock: ${error.message}`; }
@@ -297,6 +397,8 @@ export const HOST_UNAVAILABLE_FIGURES = Object.freeze({ darwin: Object.freeze(["
 export const figureUnavailableOn = (os, key) => (HOST_UNAVAILABLE_FIGURES[os] ?? []).includes(key);
 const RESULT_NUMBERS = Object.freeze({ resident_bytes: "residentMemoryBytes", idle_cpu_percent: "idleCpuPercent", wakeups_per_s: "wakeupsPerSecond", disk_ops_per_s: "diskOpsPerSecond", scale_count: "scaleCount" });
 const RESULT_WORDS = Object.freeze(["crate", "version", "scale_unit"]);
+// Optional pair emitted by a delta-basis bench: the bare-runtime wake-up rate and the bench's own reported delta.
+const RESULT_DELTA = Object.freeze({ bare_wakeups_per_s: "bareWakeupsPerSecond", wakeups_delta_per_s: "wakeupsDeltaPerSecond" });
 
 /** Parses the one `RESULT budget ...` line of a bench's raw output. */
 export function parseBudgetResult(text) {
@@ -308,7 +410,7 @@ export function parseBudgetResult(text) {
     const eq = token.indexOf("=");
     const key = eq > 0 ? token.slice(0, eq) : token;
     const value = eq > 0 ? token.slice(eq + 1) : "";
-    if (!(key in RESULT_NUMBERS) && !RESULT_WORDS.includes(key)) problems.push(`unknown field ${key}`);
+    if (!(key in RESULT_NUMBERS) && !(key in RESULT_DELTA) && !RESULT_WORDS.includes(key)) problems.push(`unknown field ${key}`);
     else if (key in fields) problems.push(`duplicate field ${key}`);
     else fields[key] = value;
   }
@@ -320,6 +422,14 @@ export function parseBudgetResult(text) {
     else if (fields[key] === undefined || fields[key] === "" || !Number.isFinite(n) || n < 0) problems.push(`field ${key} must be a non-negative number`);
     else value[name] = n;
   }
+  const present = Object.keys(RESULT_DELTA).filter((key) => key in fields);
+  if (present.length === 1) problems.push(`fields ${Object.keys(RESULT_DELTA).join(" and ")} must appear together`);
+  for (const key of present) {
+    const n = Number(fields[key]);
+    // The delta is a difference and may be negative; the bare rate is a rate and may not.
+    if (fields[key] === "" || !Number.isFinite(n) || (key === "bare_wakeups_per_s" && n < 0)) problems.push(`field ${key} must be a ${key === "bare_wakeups_per_s" ? "non-negative " : ""}number`);
+    else value[RESULT_DELTA[key]] = n;
+  }
   return problems.length ? { ok: false, problems } : { ok: true, problems: [], value };
 }
 
@@ -343,6 +453,14 @@ function checkEvidence(m, index, budget, crateDir, { exists, readFile }) {
   if (v.version !== m.crateVersion) problems.push(`evidence version ${v.version} != recorded ${m.crateVersion}`);
   for (const key of BUDGET_FIGURES) if (v[key] !== m.observed[key]) problems.push(`evidence ${key} ${v[key]} != recorded ${m.observed[key]}`);
   if (v.scale_unit !== m.dataScale.unit || v.scaleCount !== m.dataScale.count) problems.push("evidence data scale differs from the record");
+  // The baseline and delta belong to the record exactly when the raw output carries them.
+  const recordedBare = m.baseline?.wakeupsPerSecond;
+  const recordedDelta = m.delta?.wakeupsPerSecond;
+  if (v.bareWakeupsPerSecond !== recordedBare) problems.push(`evidence bare_wakeups_per_s ${v.bareWakeupsPerSecond} != recorded baseline ${recordedBare}`);
+  if (v.wakeupsDeltaPerSecond !== recordedDelta) problems.push(`evidence wakeups_delta_per_s ${v.wakeupsDeltaPerSecond} != recorded delta ${recordedDelta}`);
+  if (v.bareWakeupsPerSecond !== undefined && !(isNumber(v.wakeupsPerSecond) && Math.abs(v.wakeupsPerSecond - v.bareWakeupsPerSecond - v.wakeupsDeltaPerSecond) <= DELTA_TOLERANCE)) {
+    problems.push(`evidence wakeups_delta_per_s ${v.wakeupsDeltaPerSecond} disagrees with wakeups_per_s ${v.wakeupsPerSecond} minus bare_wakeups_per_s ${v.bareWakeupsPerSecond}`);
+  }
   return problems.map((p) => `${at} ${p}`);
 }
 
@@ -423,9 +541,19 @@ function validateMeasurement(m, index) {
   if (isNumber(m.observed?.residentMemoryBytes) && m.observed.residentMemoryBytes === 0) {
     problems.push(`${at} observed.residentMemoryBytes of 0 is implausible for a running process`);
   }
+  // Optional bare-runtime baseline and reported delta: shape only here; the gate recomputes the delta.
+  for (const [field, signed] of [["baseline", false], ["delta", true]]) {
+    if (m[field] === undefined) continue;
+    const ok = m[field] && typeof m[field] === "object" && Object.keys(m[field]).every((key) => DELTA_FIGURES.includes(key) && isNumber(m[field][key]) && (signed || m[field][key] >= 0));
+    if (!ok) problems.push(`${at} ${field} must map ${DELTA_FIGURES.join(", ")} to ${signed ? "numbers" : "non-negative numbers"}`);
+  }
+  if ((m.baseline === undefined) !== (m.delta === undefined)) problems.push(`${at} baseline and delta must be recorded together`);
   return problems;
 }
 
+/** Figures of `budget` gated as a delta over the bare baseline (validated separately; unknown bases never match). */
+const deltaFiguresOf = (budget) => DELTA_FIGURES.filter((key) => budget.ceilingBasis?.[key] === CEILING_BASIS_DELTA);
+
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 /** True when `api` (`Type::method()` or a bare type) is a `pub fn` / `pub struct|enum|trait` item in `source`, not in a comment. */
@@ -444,7 +572,14 @@ export function statusApiDeclared(api, source) {
  * `evidence` is the release gate evidence for it (the host-policy authority). `requireInstalled`
  * (adoption) additionally needs a fresh in-ceiling installed-app measurement, optionally for `app`.
  */
-export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requireInstalled = false, app, heldResource = false }, { readFile = readFileSync, exists = existsSync, git = defaultGit } = {}) {
+export function evaluateRuntimeBudget(options, deps = {}) {
+  return evaluateRuntimeBudgetOwned(options, deps);
+}
+
+// Private owner mode: no caller-supplied boolean can weaken publication or adoption.
+const STRUCTURE_ONLY = Symbol("runtime-budget-structure-only");
+function evaluateRuntimeBudgetOwned({ crate, crateDir, version, evidence, requireInstalled = false, app, heldResource = false }, { readFile = readFileSync, exists = existsSync, git = defaultGit } = {}, mode) {
+  const structural = mode === STRUCTURE_ONLY;
   const file = path.join(crateDir, RUNTIME_BUDGET_FILE);
   if (!exists(file)) return { ok: false, problems: [`${RUNTIME_BUDGET_FILE} is missing (docs/RUNTIME-BUDGETS.md)`] };
   let budget;
@@ -456,14 +591,15 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
   if (budget.schema !== RUNTIME_BUDGET_SCHEMA) problems.push(`${RUNTIME_BUDGET_FILE} schema must be ${RUNTIME_BUDGET_SCHEMA}`);
   if (budget.crate !== crate) problems.push(`${RUNTIME_BUDGET_FILE} is for ${budget.crate}, expected ${crate}`);
   if (!nonEmpty(version)) problems.push("publishing version is unknown, cannot bind the measurements to it");
-  if (budget.hostPolicy !== undefined && budget.hostPolicy !== "darwin-only") problems.push('hostPolicy must be "darwin-only" when present');
-  if (budget.hostPolicy === "darwin-only" && !nonEmpty(budget.hostPolicyReason)) problems.push("hostPolicy darwin-only needs a hostPolicyReason");
+  if (budget.hostPolicy !== undefined && budget.hostPolicy !== "darwin-only" && budget.hostPolicy !== "win32-only") problems.push('hostPolicy must be "darwin-only" or "win32-only" when present');
+  if ((budget.hostPolicy === "darwin-only" || budget.hostPolicy === "win32-only") && !nonEmpty(budget.hostPolicyReason)) problems.push(`hostPolicy ${budget.hostPolicy} needs a hostPolicyReason`);
   // One source of truth for the host policy: the release evidence. The budget file may repeat it, never differ.
   if (evidence) {
-    const evidenceDarwinOnly = requiredBudgetHosts(null, evidence).length === 1;
-    const budgetDarwinOnly = requiredBudgetHosts(budget).length === 1;
-    if (evidenceDarwinOnly !== budgetDarwinOnly) {
-      problems.push(`hostPolicy disagrees with the release evidence (evidence: ${evidenceDarwinOnly ? "darwin-only" : "macOS and Windows"}; ${RUNTIME_BUDGET_FILE}: ${budgetDarwinOnly ? "darwin-only" : "macOS and Windows"})`);
+    const policyLabel = (hosts) => (hosts.length === 1 ? `${hosts[0]}-only` : "macOS and Windows");
+    const evidenceHosts = requiredBudgetHosts(null, evidence);
+    const budgetHosts = requiredBudgetHosts(budget);
+    if (evidenceHosts.join() !== budgetHosts.join()) {
+      problems.push(`hostPolicy disagrees with the release evidence (evidence: ${policyLabel(evidenceHosts)}; ${RUNTIME_BUDGET_FILE}: ${policyLabel(budgetHosts)})`);
     }
   }
 
@@ -476,6 +612,24 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
     else ceilings[key] = value;
   }
 
+  // Ceiling basis: an explicit, closed declaration. A delta figure needs its own positive delta ceiling,
+  // and a delta ceiling without the basis would be dead text, so both directions are refused.
+  const basis = budget.ceilingBasis;
+  if (basis !== undefined && (!basis || typeof basis !== "object" || Array.isArray(basis))) problems.push("ceilingBasis must be an object");
+  else for (const [key, value] of Object.entries(basis ?? {})) {
+    if (!DELTA_FIGURES.includes(key)) problems.push(`ceilingBasis.${key} is not a figure that can use a delta basis (${DELTA_FIGURES.join(", ")})`);
+    else if (value !== CEILING_BASIS_DELTA) problems.push(`ceilingBasis.${key} must be "${CEILING_BASIS_DELTA}"`);
+  }
+  const deltaFigures = deltaFiguresOf(budget);
+  const deltaCeilings = {};
+  for (const key of DELTA_FIGURES) {
+    const value = budget.deltaCeilings?.[key];
+    if (deltaFigures.includes(key)) {
+      if (!isNumber(value) || value <= 0) problems.push(`deltaCeilings.${key} must be a positive number (ceilingBasis.${key} is ${CEILING_BASIS_DELTA})`);
+      else deltaCeilings[key] = value;
+    } else if (value !== undefined) problems.push(`deltaCeilings.${key} is declared but ceilingBasis.${key} is not ${CEILING_BASIS_DELTA}`);
+  }
+
   // Required scale: the unit and minimum the crate's measurement must reach.
   const scale = budget.requiredScale;
   let requiredScale = null;
@@ -499,7 +653,7 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
 
   // Measurements.
   const records = Array.isArray(budget.measurements) ? budget.measurements : [];
-  if (records.length === 0) problems.push("no measurements recorded (a declared ceiling is not evidence)");
+  if (!structural && records.length === 0) problems.push("no measurements recorded (a declared ceiling is not evidence)");
   const valid = [];
   records.forEach((m, index) => {
     const bad = validateMeasurement(m, index);
@@ -508,18 +662,47 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
     if (evidenceProblems.length) problems.push(...evidenceProblems); else valid.push({ m, index });
   });
   const counted = valid.filter(({ m }) => m.crateVersion === version);
-  if (valid.length && nonEmpty(version) && counted.length === 0) {
+  if (!structural && valid.length && nonEmpty(version) && counted.length === 0) {
     problems.push(`no measurement for version ${version} (recorded: ${[...new Set(valid.map(({ m }) => m.crateVersion))].join(", ")})`);
   }
-  for (const { m, index } of counted) {
+  // Why a measurement fails one figure, or null. A delta-basis figure of a synthetic measurement is gated on
+  // observed - baseline, recomputed here; the reported delta must agree and the baseline must exist. Every
+  // other scope (real, installed) keeps the whole-process ceiling, so an app is never held to a delta.
+  const usesDelta = (m, key) => deltaFigures.includes(key) && m.scope === DELTA_SCOPE;
+  const figureFailure = (m, key) => {
+    if (usesDelta(m, key)) {
+      const raw = m.observed[key];
+      const bare = m.baseline?.[key];
+      const reported = m.delta?.[key];
+      if (deltaCeilings[key] === undefined) return null; // the declaration problem is already reported
+      if (!isNumber(raw)) return `${FIGURE_LABEL[key]} is not measurable here but the ${FIGURE_LABEL[key]} ceiling is a delta over a bare baseline`;
+      if (!isNumber(bare) || !isNumber(reported)) return `has no bare baseline for ${FIGURE_LABEL[key]} (ceilingBasis.${key} is ${CEILING_BASIS_DELTA}; re-run the bench and record it again)`;
+      const delta = Number((raw - bare).toFixed(3)); // the bench prints 3 decimals; compare at that precision
+      if (Math.abs(delta - reported) > DELTA_TOLERANCE) return `reported ${FIGURE_LABEL[key]} delta ${reported} disagrees with observed ${raw} minus baseline ${bare}`;
+      if (delta < DELTA_FLOOR) return `bare baseline ${bare} is more than ${-DELTA_FLOOR} ${FIGURE_LABEL[key]}/s above observed ${raw}: a mismatched pair; re-run the bench`;
+      return delta > deltaCeilings[key] ? `exceeds the ${FIGURE_LABEL[key]} delta ceiling over the bare baseline: ${raw} - ${bare} = ${delta} > ${deltaCeilings[key]}` : null;
+    }
+    if (ceilings[key] !== undefined && m.observed[key] !== null && m.observed[key] > ceilings[key]) {
+      return `exceeds the ${FIGURE_LABEL[key]} ceiling: observed ${m.observed[key]} > ${ceilings[key]}`;
+    }
+    return null;
+  };
+  for (const { m, index } of (structural ? valid : counted)) {
     for (const key of BUDGET_FIGURES) {
-      if (ceilings[key] !== undefined && m.observed[key] !== null && m.observed[key] > ceilings[key]) {
-        problems.push(`measurement[${index}] on ${m.host.os}/${m.host.arch} exceeds the ${FIGURE_LABEL[key]} ceiling: observed ${m.observed[key]} > ${ceilings[key]}`);
-      }
+      const failure = figureFailure(m, key);
+      if (failure) problems.push(`measurement[${index}] on ${m.host.os}/${m.host.arch} ${failure}`);
     }
   }
-  const withinCeilings = (m) => BUDGET_FIGURES.every((key) => ceilings[key] !== undefined && (m.observed[key] === null ? figureUnavailableOn(m.host?.os, key) : m.observed[key] <= ceilings[key]));
+  const withinCeilings = (m) => BUDGET_FIGURES.every((key) => ceilings[key] !== undefined && (usesDelta(m, key) ? deltaCeilings[key] !== undefined && figureFailure(m, key) === null : m.observed[key] === null ? figureUnavailableOn(m.host?.os, key) : m.observed[key] <= ceilings[key]));
   const atScale = (m) => requiredScale !== null && m.dataScale.unit === requiredScale.unit && m.dataScale.count >= requiredScale.minCount;
+  if (structural) {
+    if (!Array.isArray(budget.measurements)) problems.push("measurements must be an array");
+    const scope = measuredPathspecs(crateDir, { exists, readFile });
+    problems.push(...scope.problems);
+    for (const key of deltaFigures) if (!nonEmpty(budget.deltaSources?.[key])) problems.push(`deltaSources.${key} must name its ceiling source`);
+    if (budget.deltaSources !== undefined && (!budget.deltaSources || typeof budget.deltaSources !== "object" || Array.isArray(budget.deltaSources) || Object.keys(budget.deltaSources).some((key) => !deltaFigures.includes(key)))) problems.push("deltaSources must name only declared delta figures");
+    for (const { m, index } of valid) if (!atScale(m)) problems.push(`measurement[${index}] is below required scale`);
+  }
   const staleness = new Map();
   const stale = (m) => {
     if (!staleness.has(m.commit)) staleness.set(m.commit, measurementStaleness(m.commit, crateDir, git, { exists, readFile }));
@@ -528,10 +711,10 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
 
   // Required hosts: one fresh, in-ceiling, at-scale measurement of this version on each.
   // A held-resource crate defers measurement to adoption: no per-host publish measurement is required.
-  const required = heldResource ? [] : requiredBudgetHosts(budget, evidence);
+  const required = heldResource || structural ? [] : requiredBudgetHosts(budget, evidence);
   for (const host of required) {
     const onHost = counted.filter(({ m }) => m.host.os === host);
-    if (onHost.length === 0) { problems.push(`no ${HOSTS[host]} measurement for version ${version} (required hosts: ${required.map((h) => HOSTS[h]).join(" and ")}${required.length > 1 ? "; apps ship on both and the release gate requires both unless a darwin-only policy with a reason is recorded" : `; darwin-only policy: ${String((evidence ?? budget).hostPolicyReason).trim()}`})`); continue; }
+    if (onHost.length === 0) { problems.push(`no ${HOSTS[host]} measurement for version ${version} (required hosts: ${required.map((h) => HOSTS[h]).join(" and ")}${required.length > 1 ? "; apps ship on both and the release gate requires both unless a darwin-only policy with a reason is recorded" : `; ${required[0]}-only policy: ${String((evidence ?? budget).hostPolicyReason).trim()}`})`); continue; }
     const fresh = onHost.filter(({ m }) => stale(m) === null);
     if (fresh.length === 0) { problems.push(`${HOSTS[host]} measurement is stale: ${onHost.map(({ m }) => stale(m)).join("; ")}`); continue; }
     const within = fresh.filter(({ m }) => withinCeilings(m));
@@ -632,7 +815,17 @@ export function heldResourceProblems({ crate, crateDir, meta }, { readFile = rea
  * naming every matched pattern), "held-resource" (resources table, adoption-time proof) or always-on
  * (runtime-budget.json, fully checked). `readFile`, `exists` and `git` are injectable.
  */
-export function runtimeBudgetCheck({ crate, crateDir, version, evidence, requireInstalled = false, app }, deps = {}) {
+export function runtimeBudgetCheck(options, deps = {}) {
+  return runtimeBudgetCheckOwned(options, deps);
+}
+
+/** Source structure only; grants no runtime qualification or semantic admission. */
+export function runtimeBudgetStructureCheck(options, deps = {}) {
+  const result = runtimeBudgetCheckOwned({ ...options, requireInstalled: false }, deps, STRUCTURE_ONLY);
+  return { ...result, name: "runtime-budget-structure" };
+}
+
+function runtimeBudgetCheckOwned({ crate, crateDir, version, evidence, requireInstalled = false, app }, deps = {}, mode) {
   const { readFile = readFileSync, exists = existsSync } = deps;
   let pkg;
   try { pkg = readCargoPackage(crateDir, { exists, readFile }); } catch (error) {
@@ -679,9 +872,9 @@ export function runtimeBudgetCheck({ crate, crateDir, version, evidence, require
     return fail(crate, crateDir, [`undeclared: none of ${RUNTIME_BUDGET_FILE}, continuous = false with a continuous_reason, or continuous = "held-resource" with resources`],
       `declare the crate (docs/RUNTIME-BUDGETS.md)`);
   }
-  const result = evaluateRuntimeBudget({ crate, crateDir, version: version ?? pkg.version, evidence, requireInstalled, app }, deps);
+  const result = evaluateRuntimeBudgetOwned({ crate, crateDir, version: version ?? pkg.version, evidence, requireInstalled, app }, deps, mode);
   if (result.ok) {
-    return { name: RUNTIME_BUDGET_CHECK, status: "ok", detail: `${crate} ${version ?? pkg.version} has measured runtime budgets on every required host` };
+    return { name: RUNTIME_BUDGET_CHECK, status: "ok", detail: mode === STRUCTURE_ONLY ? `${crate} ${version ?? pkg.version} runtime budget structure is valid; qualification is separate` : `${crate} ${version ?? pkg.version} has measured runtime budgets on every required host` };
   }
   return fail(crate, crateDir, result.problems);
 }
@@ -839,6 +1032,13 @@ export function recordMeasurement({ crateDir, resultFile, scope, command, descri
   if (stale) throw new Error(`refusing to record: ${stale} (commit the code under test, then re-run the bench)`);
   const file = path.join(crateDir, RUNTIME_BUDGET_FILE);
   const budget = JSON.parse(fs.readFileSync(file, "utf8"));
+  const hasBaseline = v.bareWakeupsPerSecond !== undefined;
+  if (scope === DELTA_SCOPE && !hasBaseline && deltaFiguresOf(budget).length) {
+    throw new Error(`bench output rejected: ${RUNTIME_BUDGET_FILE} gates ${deltaFiguresOf(budget).join(", ")} as ${CEILING_BASIS_DELTA}, so the RESULT line needs bare_wakeups_per_s and wakeups_delta_per_s`);
+  }
+  if (hasBaseline && !(isNumber(v.wakeupsPerSecond) && Math.abs(v.wakeupsPerSecond - v.bareWakeupsPerSecond - v.wakeupsDeltaPerSecond) <= DELTA_TOLERANCE)) {
+    throw new Error("bench output rejected: wakeups_delta_per_s disagrees with wakeups_per_s minus bare_wakeups_per_s");
+  }
   const evidenceName = `${host.os}-${host.arch}-${pkg.version}-${scope}${scope === "installed" ? `-${app.name}` : ""}.txt`.replace(/[^\w.-]/g, "_");
   const evidenceRel = `${RUNTIME_BUDGET_EVIDENCE_DIR}/${evidenceName}`;
   fs.mkdirSync(path.join(crateDir, RUNTIME_BUDGET_EVIDENCE_DIR), { recursive: true });
@@ -849,6 +1049,7 @@ export function recordMeasurement({ crateDir, resultFile, scope, command, descri
     dataScale: { description, unit: v.scale_unit, count: v.scaleCount },
     command,
     observed: Object.fromEntries(BUDGET_FIGURES.map((key) => [key, v[key]])),
+    ...(hasBaseline ? { baseline: { wakeupsPerSecond: v.bareWakeupsPerSecond }, delta: { wakeupsPerSecond: v.wakeupsDeltaPerSecond } } : {}),
     evidence: { file: evidenceRel, sha256: sha256Of(raw) },
   };
   const same = (m) => m.host?.os === host.os && m.host?.arch === host.arch && m.crateVersion === pkg.version && m.scope === scope && (m.app?.name ?? null) === (app?.name ?? null);