@aethervtt/shard-core 0.1.0 → 0.2.1

package/dist/scheduler/profiler.js

@@ -1,22 +1,281 @@
+import { ShardError } from "../error.js";
 import { defineResource } from "../schema/resource.js";
+function defineSpan(name) {
+  return { name, id: -1 };
+}
+const TRACK = { main: 0, gpu: 1, async: 2, gc: 3, worker: 4 };
+function trackName(track) {
+  if (track === TRACK.main) return "main";
+  if (track === TRACK.gpu) return "gpu";
+  if (track === TRACK.async) return "async";
+  if (track === TRACK.gc) return "gc";
+  return "worker";
+}
+function spanCovers(key, name) {
+  if (name === key) return true;
+  const n = key.length;
+  if (n === 0 || name.length <= n || !name.startsWith(key)) return false;
+  return key.charCodeAt(n - 1) === SLASH || name.charCodeAt(n) === SLASH;
+}
+const SLASH = 47;
+const MAX_SPANS = 65536;
+const MAX_DEPTH = 64;
+const ASYNC_SLOTS = 256;
+const spanNames = [];
+const spanTracks = [];
+const spanIds = /* @__PURE__ */ new Map();
+function internSpan(name, track = defaultTrack(name)) {
+  const known = spanIds.get(name);
+  if (known !== void 0) return known;
+  const id = spanNames.length;
+  if (id >= MAX_SPANS) {
+    throw new ShardError("perf/too-many-spans", `More than ${MAX_SPANS} span names`, {
+      hint: 'Span names are fixed strings (e.g. "terrain/encode"), not per-entity or per-frame text.'
+    });
+  }
+  spanNames.push(name);
+  spanTracks.push(track);
+  spanIds.set(name, id);
+  return id;
+}
+function spanCount() {
+  return spanNames.length;
+}
+function spanId(name) {
+  return spanIds.get(name) ?? -1;
+}
+function spanName(id) {
+  return spanNames[id] ?? `span#${id}`;
+}
+function spanTrack(id) {
+  return spanTracks[id] ?? TRACK.main;
+}
+function defaultTrack(name) {
+  if (name.startsWith("gpu:")) return TRACK.gpu;
+  if (name.startsWith("worker/")) return TRACK.worker;
+  if (name === "gc" || name.startsWith("gc/")) return TRACK.gc;
+  return TRACK.main;
+}
+function idOf(span, track) {
+  if (typeof span === "string") return spanIds.get(span) ?? internSpan(span, track);
+  let id = span.id;
+  if (id < 0) {
+    id = internSpan(span.name, track);
+    span.id = id;
+  }
+  return id;
+}
+const ProfilerSettings = defineResource("core/ProfilerSettings", {
+  description: "Turns the profiler (0074) on or off, and how many runs its aggregates cover. Off, spans cost a branch.",
+  hostWritable: true,
+  init: () => ({ enabled: true, window: 120 })
+});
+const host = globalThis;
+function defaultNow() {
+  return host.performance ? host.performance.now() : Date.now();
+}
+let measuredClock;
+function clockInfo() {
+  if (measuredClock) return measuredClock;
+  let resolution = Number.POSITIVE_INFINITY;
+  let prev = defaultNow();
+  let steps = 0;
+  for (let i = 0; i < 2e6 && steps < 20; i++) {
+    const t = defaultNow();
+    if (t !== prev) {
+      if (t - prev < resolution) resolution = t - prev;
+      prev = t;
+      steps++;
+    }
+  }
+  const isolated = host.document === void 0 ? true : host.crossOriginIsolated === true;
+  measuredClock = {
+    resolutionMs: Number.isFinite(resolution) ? Math.round(resolution * 1e6) / 1e6 : 0,
+    isolated
+  };
+  return measuredClock;
+}
 class Profiler {
-  window;
-  series = /* @__PURE__ */ new Map();
-  constructor(window = 120) {
-    this.window = window;
+  settings;
+  /** The clock, in ms. */
+  now;
+  /** Receives every span while a capture runs. */
+  sink;
+  /** Gets `perf/span-mismatch` and similar warnings; the app logs them. */
+  onWarning;
+  /** `Time.frame` of the frame running now (or that ran last). */
+  frame = 0;
+  /** The last span `end` measured, in ms. */
+  lastMs = 0;
+  /** What the renderer said about GPU timing: `unavailable` without timestamp queries. */
+  gpu = {
+    status: "unknown",
+    quantized: false
+  };
+  windowSize;
+  series = [];
+  stackIds = new Int32Array(MAX_DEPTH);
+  stackStarts = new Float64Array(MAX_DEPTH);
+  depth = 0;
+  frameStartAt = 0;
+  warned = new Uint8Array(256);
+  asyncIds = new Int32Array(ASYNC_SLOTS).fill(-1);
+  asyncKeys = new Array(ASYNC_SLOTS);
+  asyncStarts = new Float64Array(ASYNC_SLOTS);
+  asyncCount = 0;
+  frameSpan = defineSpan("frame");
+  constructor(options = {}) {
+    const o = typeof options === "number" ? { settings: { enabled: true, window: options } } : options;
+    this.settings = o.settings ?? { enabled: true, window: 120 };
+    this.now = o.now ?? defaultNow;
+    this.windowSize = Math.max(1, this.settings.window | 0);
+  }
+  get window() {
+    return this.windowSize;
+  }
+  get enabled() {
+    return this.settings.enabled;
   }
-  record(name, ms) {
-    let series = this.series.get(name);
-    if (!series) {
-      series = { samples: new Float64Array(this.window), cursor: 0, count: 0 };
-      this.series.set(name, series);
+  // --- spans -------------------------------------------------------------------
+  /** Starts a span on the main track. Returns a token for `end`; -1 when the profiler is off. */
+  begin(span) {
+    if (!this.settings.enabled) return -1;
+    const id = span.id >= 0 ? span.id : idOf(span, TRACK.main);
+    const d = this.depth;
+    if (d >= MAX_DEPTH) {
+      this.warn(id, WARN_DEPTH);
+      return -1;
     }
-    series.samples[series.cursor] = ms;
-    series.cursor = (series.cursor + 1) % this.window;
-    if (series.count < this.window) series.count++;
+    this.stackIds[d] = id;
+    this.depth = d + 1;
+    this.stackStarts[d] = this.now();
+    return d * MAX_SPANS + id;
+  }
+  /** Ends the span `begin` returned `token` for, recording it. */
+  end(token) {
+    if (token < 0) return;
+    const at = this.now();
+    const d = token / MAX_SPANS | 0;
+    const id = token - d * MAX_SPANS;
+    if (d !== this.depth - 1 || this.stackIds[d] !== id) {
+      this.warn(id, WARN_ORDER);
+      if (d >= this.depth || this.stackIds[d] !== id) return;
+    }
+    this.depth = d;
+    const start = this.stackStarts[d];
+    const ms = at - start;
+    this.lastMs = ms;
+    this.push(id, ms);
+    const sink = this.sink;
+    if (sink !== void 0) sink.event(id, TRACK.main, d, start, ms, -1);
   }
+  /** Drops the span `token` and everything begun inside it, recording nothing (an exception unwound it). */
+  cancel(token) {
+    if (token < 0) return;
+    const d = token / MAX_SPANS | 0;
+    if (d < this.depth) this.depth = d;
+  }
+  /**
+   * Time measured elsewhere (a GPU pass, a worker job): its aggregate, and a timeline event on
+   * `track` that ended now, or started at `start`. `frame`: the frame it belongs to, when it lands
+   * later (GPU timings).
+   */
+  record(span, ms, track, start, frame = -1) {
+    if (!this.settings.enabled) return;
+    const id = idOf(span, track);
+    this.push(id, ms);
+    const sink = this.sink;
+    if (sink !== void 0) {
+      const t = track ?? spanTracks[id];
+      sink.event(id, t, t === TRACK.main ? this.depth : 0, start ?? this.now() - ms, ms, frame);
+    }
+  }
+  /** Only the aggregate (`render/<node>` sums its views into one sample a frame). */
+  sample(span, ms) {
+    if (!this.settings.enabled) return;
+    this.push(idOf(span), ms);
+  }
+  /** Only the timeline event, when a capture runs. */
+  event(span, track, start, ms, frame = -1) {
+    const sink = this.sink;
+    if (sink === void 0 || !this.settings.enabled) return;
+    sink.event(idOf(span, track), track, track === TRACK.main ? this.depth : 0, start, ms, frame);
+  }
+  /** Whether a capture is listening (callers skip work that only feeds the timeline). */
+  get capturing() {
+    return this.sink !== void 0;
+  }
+  /**
+   * Work that starts in one frame and ends in another (an asset load, a page fetch): an async span,
+   * matched to its `endAsync` by span and key.
+   */
+  beginAsync(span, key) {
+    if (!this.settings.enabled) return;
+    const id = span.id >= 0 ? span.id : idOf(span, TRACK.async);
+    if (this.asyncCount >= ASYNC_SLOTS) {
+      this.warn(id, WARN_ASYNC);
+      return;
+    }
+    for (let i = 0; i < ASYNC_SLOTS; i++) {
+      if (this.asyncIds[i] !== -1) continue;
+      this.asyncIds[i] = id;
+      this.asyncKeys[i] = key;
+      this.asyncStarts[i] = this.now();
+      this.asyncCount++;
+      return;
+    }
+  }
+  endAsync(span, key) {
+    if (!this.settings.enabled || span.id < 0 || this.asyncCount === 0) return;
+    const id = span.id;
+    for (let i = 0; i < ASYNC_SLOTS; i++) {
+      if (this.asyncIds[i] !== id || this.asyncKeys[i] !== key) continue;
+      const start = this.asyncStarts[i];
+      const ms = this.now() - start;
+      this.asyncIds[i] = -1;
+      this.asyncKeys[i] = void 0;
+      this.asyncCount--;
+      this.push(id, ms);
+      const sink = this.sink;
+      if (sink !== void 0) sink.event(id, TRACK.async, 0, start, ms, -1);
+      return;
+    }
+  }
+  // --- frames ------------------------------------------------------------------
+  /**
+   * A frame starts: spans left open from before are dropped (and reported once), and the `frame`
+   * span begins. Returns its token for `endFrame`.
+   */
+  beginFrame(frame) {
+    if (!this.settings.enabled) return -1;
+    if (this.depth > 0) {
+      const id = this.stackIds[this.depth - 1];
+      this.warn(id, WARN_OPEN_AT_START);
+      this.depth = 0;
+    }
+    if (this.settings.window !== this.windowSize) this.resize();
+    this.frame = frame;
+    const token = this.begin(this.frameSpan);
+    this.frameStartAt = this.stackStarts[0];
+    const sink = this.sink;
+    if (sink !== void 0) sink.frameStart(frame, this.frameStartAt);
+    return token;
+  }
+  endFrame(token) {
+    if (token < 0) return;
+    if (this.depth > 1) {
+      const id = this.stackIds[this.depth - 1];
+      this.warn(id, WARN_OPEN_AT_END);
+      this.depth = 1;
+    }
+    this.end(token);
+    const sink = this.sink;
+    if (sink !== void 0) sink.frameEnd(this.frame, this.lastMs);
+  }
+  // --- reading -----------------------------------------------------------------
   timing(name) {
-    const series = this.series.get(name);
+    const id = spanIds.get(name);
+    const series = id === void 0 ? void 0 : this.series[id];
     if (!series || series.count === 0) return void 0;
     let sum = 0;
     let max = 0;
@@ -25,20 +284,174 @@ class Profiler {
       sum += v;
       if (v > max) max = v;
     }
-    const last = series.samples[(series.cursor - 1 + this.window) % this.window];
+    const last = series.samples[(series.cursor - 1 + this.windowSize) % this.windowSize];
     return { last, avg: sum / series.count, max, samples: series.count };
   }
+  /** A span's samples over the window, in ring order (not by age); undefined if it never ran. */
+  samples(name) {
+    const id = spanIds.get(name);
+    const series = id === void 0 ? void 0 : this.series[id];
+    return series?.count ? series.samples.subarray(0, series.count) : void 0;
+  }
+  /** Every span that ran, by name. */
   all() {
     const out = {};
-    for (const name of this.series.keys()) out[name] = this.timing(name);
+    for (let id = 0; id < this.series.length; id++) {
+      if (!this.series[id]?.count) continue;
+      const name = spanNames[id];
+      out[name] = this.timing(name);
+    }
+    return out;
+  }
+  /**
+   * How many samples a span has had since the profiler started (or its aggregates were reset), by
+   * id: 0 if none. Allocates nothing, for per-frame readers such as feature budgets (0075).
+   */
+  runsOf(id) {
+    return this.series[id]?.total ?? 0;
+  }
+  /**
+   * The span that was open around a span's latest sample (its parent on the main track), by id, or
+   * -1: what lets aggregates count time two covering keys share once (0075's slices).
+   */
+  parentOf(id) {
+    return this.series[id]?.parent ?? -1;
+  }
+  /** A span's latest sample in ms, by id, or 0 if it has none. Allocates nothing. */
+  lastOf(id) {
+    const series = this.series[id];
+    if (series === void 0 || series.count === 0) return 0;
+    return series.samples[(series.cursor - 1 + this.windowSize) % this.windowSize];
+  }
+  /** Names of every span with samples. */
+  names() {
+    const out = [];
+    for (let id = 0; id < this.series.length; id++)
+      if (this.series[id]?.count) out.push(spanNames[id]);
     return out;
   }
+  /** Forgets every aggregate (`perf.reset`). */
+  reset() {
+    for (const series of this.series) {
+      if (!series) continue;
+      series.count = 0;
+      series.cursor = 0;
+      series.total = 0;
+    }
+  }
+  // --- internals ---------------------------------------------------------------
+  push(id, ms) {
+    let series = this.series[id];
+    if (series === void 0) series = this.createSeries(id);
+    series.samples[series.cursor] = ms;
+    series.cursor = series.cursor + 1 === this.windowSize ? 0 : series.cursor + 1;
+    if (series.count < this.windowSize) series.count++;
+    series.total++;
+    series.parent = this.depth > 0 ? this.stackIds[this.depth - 1] : -1;
+  }
+  createSeries(id) {
+    while (this.series.length <= id) this.series.push(void 0);
+    const series = {
+      samples: new Float64Array(this.windowSize),
+      cursor: 0,
+      count: 0,
+      total: 0,
+      parent: -1
+    };
+    this.series[id] = series;
+    return series;
+  }
+  resize() {
+    this.windowSize = Math.max(1, this.settings.window | 0);
+    for (let id = 0; id < this.series.length; id++) {
+      if (this.series[id])
+        this.series[id] = {
+          samples: new Float64Array(this.windowSize),
+          cursor: 0,
+          count: 0,
+          total: this.series[id].total,
+          parent: this.series[id].parent
+        };
+    }
+  }
+  /** Reports a problem once per span name. */
+  warn(id, kind) {
+    if (id >= this.warned.length) {
+      const grown = new Uint8Array(Math.max(id + 1, this.warned.length * 2));
+      grown.set(this.warned);
+      this.warned = grown;
+    }
+    if (this.warned[id]) return;
+    this.warned[id] = 1;
+    this.onWarning?.(warningOf(kind, spanName(id)));
+  }
+}
+const WARN_ORDER = 0;
+const WARN_OPEN_AT_START = 1;
+const WARN_OPEN_AT_END = 2;
+const WARN_DEPTH = 3;
+const WARN_ASYNC = 4;
+const MISMATCH = [
+  "ended out of order: spans end in the reverse order they began",
+  "was still open when a frame began",
+  "was still open when its frame ended"
+];
+function warningOf(kind, name) {
+  if (kind === WARN_DEPTH) {
+    return new ShardError(
+      "perf/span-overflow",
+      `Spans nest deeper than ${MAX_DEPTH} at "${name}"`,
+      {
+        hint: "A span that begins in a loop needs its end inside the loop too.",
+        path: name
+      }
+    );
+  }
+  if (kind === WARN_ASYNC) {
+    return new ShardError("perf/async-overflow", `More than ${ASYNC_SLOTS} async spans are open`, {
+      hint: "Every beginAsync(span, key) needs an endAsync(span, key), even when the work fails.",
+      path: name
+    });
+  }
+  return new ShardError("perf/span-mismatch", `Span "${name}" ${MISMATCH[kind]}`, {
+    hint: "Every profiler.begin(span) needs one profiler.end(token), in the same frame.",
+    path: name
+  });
+}
+function spanStats(profiler, name) {
+  const timing = profiler.timing(name);
+  const samples = profiler.samples(name);
+  if (!timing || !samples) return void 0;
+  const sorted = Float64Array.from(samples).sort();
+  const at = (p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+  const out = {
+    span: name,
+    track: trackName(spanTrack(spanIds.get(name))),
+    ...timing,
+    p50: at(0.5),
+    p95: at(0.95)
+  };
+  const resolution = clockInfo().resolutionMs;
+  if (out.track !== "gpu" && resolution > 0 && timing.avg < 4 * resolution) out.coarse = true;
+  return out;
 }
 const ProfilerResource = defineResource("core/Profiler", {
-  description: "Per-system CPU timings over recent frames.",
+  description: "Span timings (0074): systems, schedules, frames, render passes, GPU and workers.",
   init: () => new Profiler()
 });
 export {
   Profiler,
-  ProfilerResource
+  ProfilerResource,
+  ProfilerSettings,
+  TRACK,
+  clockInfo,
+  defineSpan,
+  internSpan,
+  spanCount,
+  spanCovers,
+  spanId,
+  spanName,
+  spanStats,
+  spanTrack,
+  trackName
 };

package/dist/scheduler/schedule.d.ts

@@ -1,5 +1,5 @@
 import type { World } from '../ecs/world.js';
-import type { Profiler } from './profiler.js';
+import { type Profiler } from './profiler.js';
 import { SystemConfig, type SystemDef, type SystemSetConfig } from './system.js';
 export interface ScheduleLabel {
     readonly kind: 'schedule';
@@ -33,6 +33,10 @@ export interface SystemDescription {
  */
 export declare class Schedule {
     readonly label: ScheduleLabel;
+    /** `schedule/<Label>`: one run of the schedule (0074). */
+    private readonly span;
+    /** `commands/<Label>`: command application over one run. */
+    private readonly commandsSpan;
     private readonly entries;
     private readonly setConfigs;
     private order;

package/dist/scheduler/schedule.js

@@ -1,5 +1,6 @@
 import { Commands } from "../ecs/commands.js";
 import { ShardError } from "../error.js";
+import { defineSpan, TRACK } from "./profiler.js";
 import {
   conditionLabel,
   SystemConfig
@@ -35,16 +36,23 @@ class Context {
 }
 class Schedule {
   label;
+  /** `schedule/<Label>`: one run of the schedule (0074). */
+  span;
+  /** `commands/<Label>`: command application over one run. */
+  commandsSpan;
   entries = [];
   setConfigs = [];
   order;
   constructor(label) {
     this.label = label;
+    this.span = defineSpan(`schedule/${label.name}`);
+    this.commandsSpan = defineSpan(`commands/${label.name}`);
   }
   add(system) {
     const config = system instanceof SystemConfig ? system : new SystemConfig(system);
     this.entries.push({
       config,
+      span: defineSpan(config.system.name),
       index: this.entries.length,
       state: void 0,
       ctx: void 0,
@@ -77,6 +85,9 @@ class Schedule {
   }
   run(world, options) {
     const order = this.resolve();
+    const profiler = options.profiler;
+    const scheduleToken = profiler !== void 0 ? profiler.begin(this.span) : -1;
+    let commandsMs = 0;
     for (let i = 0; i < order.length; i++) {
       const entry = order[i];
       const conditions = entry.conditions;
@@ -95,10 +106,11 @@ class Schedule {
       }
       const ctx = entry.ctx;
       ctx.thisRunTick = world.incrementTick();
-      const start = options.now();
+      const token = profiler !== void 0 ? profiler.begin(entry.span) : -1;
       try {
         system.run(entry.state, world, ctx);
       } catch (err) {
+        profiler?.cancel(scheduleToken);
         const message = err instanceof Error ? err.message : String(err);
         const code = err instanceof ShardError ? ` [${err.code}]` : "";
         throw new ShardError(
@@ -110,10 +122,28 @@ class Schedule {
           }
         );
       }
-      options.profiler?.record(system.name, options.now() - start);
+      if (profiler !== void 0) profiler.end(token);
       ctx.lastRunTick = ctx.thisRunTick;
       world.incrementTick();
-      if (ctx.commands.length > 0) ctx.commands.apply();
+      if (ctx.commands.length > 0) {
+        if (profiler === void 0) ctx.commands.apply();
+        else {
+          const start = profiler.now();
+          try {
+            ctx.commands.apply();
+          } catch (err) {
+            profiler.cancel(scheduleToken);
+            throw err;
+          }
+          const ms = profiler.now() - start;
+          commandsMs += ms;
+          profiler.event(this.commandsSpan, TRACK.main, start, ms);
+        }
+      }
+    }
+    if (profiler !== void 0) {
+      profiler.sample(this.commandsSpan, commandsMs);
+      profiler.end(scheduleToken);
     }
   }
   describe() {

package/dist/test-env.d.ts

@@ -9,12 +9,106 @@
  *
  * Write every timing assertion through `budget()`, `slack` or `allocationChecks`, and it lands in
  * the right tier.
+ *
+ * Budgets are data (spec 0075): `bench/perf/budgets.json` holds a number per key and named machine
+ * (`bench/perf/machines.json`), and `budget(key)` reads it. Core can't read files, so the numbers
+ * arrive resolved, as JSON in the `SHARD_BUDGETS` environment variable:
+ *
+ * - `pnpm bench` (`scripts/bench.mjs`) detects the machine, resolves every key for it, and passes
+ *   the result (`ResolvedBudgets`) to the test processes. On an unknown machine it passes the
+ *   closest machine's numbers with `enforce: false`: budgets stay unlimited, and the report
+ *   (`bench/perf/report.json`) compares against them.
+ * - `pnpm test` gets the keys with no machine from `testFiles()` (`scripts/test-shard.mjs`), so an
+ *   unknown key fails there too (`perf/unknown-budget`) while every budget is unlimited.
+ *
+ * Under `pnpm bench`, `SHARD_PERF_REPORT` names a folder: each `budget(key)` call is noted on
+ * `globalThis.__shardBudget`, and `scripts/perf-report.setup.mjs` records the value the next
+ * comparison matcher (`toBeLessThan` and the like) checks against it.
  */
 export type TimingMode = 'bench' | 'test' | 'ci';
 export declare const timingMode: TimingMode;
 /** The factor budgets are multiplied by (and rate floors divided by): 1 under `pnpm bench`, else ∞. */
 export declare const slack: number;
-/** A time budget in ms: exact under `pnpm bench`, unlimited in `pnpm test` and CI. */
+/** One key of `budgets.json`, resolved for a machine. `value` is null without one. */
+export interface ResolvedSpan {
+    kind: 'target' | 'unit' | 'rate' | 'guard';
+    value: number | null;
+    /** Guards: the limit is `value × (1 + margin)`. */
+    margin?: number;
+    /** Units and rates: what one item is ("prop", "point"). */
+    per?: string;
+    /** What the number measures when it isn't ms: 'frames', 'ratio'. */
+    in?: string;
+}
+export type Track = 'gpu' | 'cpu';
+export interface ResolvedScenario {
+    /** The frame budget per track, in ms. */
+    frame: Record<Track, number | null>;
+    /** Each slice in ms (its share of the frame, or the machine's override). */
+    slices: Record<Track, Record<string, number | null>>;
+}
+/** What `SHARD_BUDGETS` carries. */
+export interface ResolvedBudgets {
+    /** The machine the numbers are for; null outside `pnpm bench`. */
+    machine: string | null;
+    /** False on an unknown machine and outside `pnpm bench`: every budget is unlimited. */
+    enforce: boolean;
+    spans: Record<string, ResolvedSpan>;
+    scenarios: Record<string, ResolvedScenario>;
+    /**
+     * How the machine checks GPU slices (machines.json): per-pass timestamps, or ablation where
+     * passes overlap (tile-based GPUs). Absent outside `pnpm bench`.
+     */
+    passTiming?: 'ablation' | 'timestamps' | null;
+}
+export interface BudgetOptions {
+    /** Unit costs: how many items the measurement covered (the budget is the unit cost × this). */
+    count?: number;
+    /** Scenarios: a slice's budget instead of the whole frame's. */
+    slice?: string;
+    /** Scenarios: 'gpu' or 'cpu'. Default: 'gpu' for a `gpu:` slice, else 'cpu'. */
+    track?: Track;
+}
+/** A key's number on the resolved machine, and the limit a test checks: ∞ (0 for rates) when off. */
+export interface ResolvedLimit {
+    /** What the test compares against. */
+    limit: number;
+    /** The machine's number for the comparison (null without one), enforced or not. */
+    reference: number | null;
+    kind: ResolvedSpan['kind'] | 'slice';
+}
+/**
+ * The limit for `key` from resolved budgets: a span's number (a unit's times `count`, a guard's
+ * plus its margin), or a scenario's frame or slice in ms. Unlimited unless `enforce`: ∞, or 0 for a
+ * rate (a floor). Throws `perf/unknown-budget` for a key, scenario or slice budgets.json lacks.
+ */
+export declare function resolveLimit(budgets: ResolvedBudgets | undefined, key: string, opts?: BudgetOptions, enforce?: boolean): ResolvedLimit;
+/** The last `budget(key)` call, for `scripts/perf-report.setup.mjs` (under `pnpm bench` only). */
+export interface BudgetCall extends ResolvedLimit {
+    key: string;
+    opts: BudgetOptions;
+    used: boolean;
+}
+/**
+ * A scenario's slice keys per track, `headroom` aside (0075): what a scenario test measures. Throws
+ * `perf/unknown-budget` for a scenario budgets.json lacks, in `pnpm test` too.
+ */
+export declare function scenarioSlices(name: string): Record<Track, string[]>;
+/**
+ * How GPU slices are measured on this machine (0075): `'ablation'` under `pnpm bench` on a machine
+ * whose passes overlap (machines.json's `passTiming`), else `'timestamps'`.
+ */
+export declare function passTiming(): 'ablation' | 'timestamps';
+/**
+ * A time budget from `bench/perf/budgets.json`: the detected machine's number under `pnpm bench`,
+ * unlimited in `pnpm test`, CI, and on an unknown machine (∞; 0 for a rate, which is a floor).
+ * `{ count }` scales a unit cost; `{ slice, track }` reads a scenario's slice. An unknown key throws
+ * `perf/unknown-budget`.
+ *
+ * `budget(ms)`, a literal, still works (exact under `pnpm bench`): `scripts/budget-literals.mjs`
+ * lists those calls, and the goal is none.
+ */
+export declare function budget(key: string, opts?: BudgetOptions): number;
 export declare function budget(ms: number): number;
 /** A test or hook timeout in ms: 5× in CI, unchanged everywhere else. */
 export declare function timeout(ms: number): number;