@aethervtt/shard-core 0.0.1 → 0.2.0

package/dist/test-env.d.ts

@@ -1,16 +1,114 @@
 /**
- * How strict tests are about time, in one place.
+ * How strict tests are about time, in one place. Two tiers:
  *
- * - `pnpm bench` (`SHARD_BENCH`) holds the exact budgets from the specs, one file at a time.
- * - `pnpm test` allows 3×, for a machine busy running test files in parallel.
- * - CI (`SHARD_CI`) checks correctness only. Shared runners render with a software GPU, so their
- *   timings say nothing about the engine; budgets are unlimited there and timeouts are 5× longer.
+ * - `pnpm bench` (`SHARD_BENCH`) checks performance: the exact budgets from the specs and
+ *   "allocates nothing", one file at a time on a machine doing nothing else.
+ * - `pnpm test`, locally and in CI (`SHARD_CI`), checks correctness only. Parallel files share the
+ *   CPU and GPU, and CI renders on a software GPU, so wall-clock timings there say nothing about the
+ *   engine: budgets are unlimited and allocation checks are off. Timeouts are 5× longer in CI.
+ *
+ * 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) in this mode. */
+/** 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`, 3× in `pnpm test`, unlimited in 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;
@@ -24,8 +122,7 @@ export declare function gcWindow(): {
     end(): Promise<number>;
 };
 /**
- * Whether "allocates nothing" checks run. They hold under `pnpm bench` and `pnpm test`; CI turns them
- * off with the time budgets, since when V8 optimizes (and so whether a call boxes its result) depends
- * on the runner's CPU and timing.
+ * Whether "allocates nothing" checks run: under `pnpm bench` only. When V8 optimizes (and so whether
+ * a call boxes its result) depends on the CPU and on what else is running.
  */
 export declare const allocationChecks: boolean;

package/dist/test-env.js

@@ -1,8 +1,73 @@
+import { ShardError } from "./error.js";
 const env = globalThis.process?.env ?? {};
 const timingMode = env.SHARD_BENCH ? "bench" : env.SHARD_CI ? "ci" : "test";
-const slack = timingMode === "bench" ? 1 : timingMode === "test" ? 3 : Number.POSITIVE_INFINITY;
-function budget(ms) {
-  return ms * slack;
+const slack = timingMode === "bench" ? 1 : Number.POSITIVE_INFINITY;
+function unknownBudget(key, detail = "") {
+  return new ShardError("perf/unknown-budget", `No budget "${key}"${detail} in budgets.json`, {
+    path: key,
+    hint: "Add it to bench/perf/budgets.json with a number for every machine and a note."
+  });
+}
+function resolveLimit(budgets2, key, opts = {}, enforce = true) {
+  if (!budgets2) {
+    if (enforce) {
+      throw new ShardError("perf/no-budgets", `No budgets to resolve "${key}" against`, {
+        hint: "pnpm bench passes them in SHARD_BUDGETS; run tests through it or through testFiles()."
+      });
+    }
+    return { limit: Number.POSITIVE_INFINITY, reference: null, kind: "target" };
+  }
+  const on = enforce && budgets2.enforce;
+  const span = budgets2.spans[key];
+  if (span) {
+    let reference2 = span.value;
+    if (reference2 !== null && span.kind === "unit") reference2 *= opts.count ?? 1;
+    if (reference2 !== null && span.kind === "guard") reference2 *= 1 + (span.margin ?? 0);
+    const off = span.kind === "rate" ? 0 : Number.POSITIVE_INFINITY;
+    return { limit: on && reference2 !== null ? reference2 : off, reference: reference2, kind: span.kind };
+  }
+  const scenario = budgets2.scenarios[key];
+  if (!scenario) throw unknownBudget(key);
+  const track = opts.track ?? (opts.slice?.startsWith("gpu:") ? "gpu" : "cpu");
+  const slices = scenario.slices[track];
+  if (opts.slice !== void 0 && !(opts.slice in slices)) {
+    throw unknownBudget(key, ` slice "${opts.slice}" (${track})`);
+  }
+  const reference = opts.slice !== void 0 ? slices[opts.slice] : scenario.frame[track];
+  return {
+    limit: on && reference !== null ? reference : Number.POSITIVE_INFINITY,
+    reference,
+    kind: "slice"
+  };
+}
+let resolved;
+let parsed = false;
+function budgets() {
+  if (!parsed) {
+    parsed = true;
+    if (env.SHARD_BUDGETS) resolved = JSON.parse(env.SHARD_BUDGETS);
+  }
+  return resolved;
+}
+function scenarioSlices(name) {
+  const scenario = budgets()?.scenarios[name];
+  if (!scenario) throw unknownBudget(name);
+  const keys = (track) => Object.keys(scenario.slices[track]).filter((k) => k !== "headroom");
+  return { gpu: keys("gpu"), cpu: keys("cpu") };
+}
+function passTiming() {
+  return timingMode === "bench" && budgets()?.passTiming === "ablation" ? "ablation" : "timestamps";
+}
+function budget(key, opts = {}) {
+  if (typeof key === "number") return key * slack;
+  const bench = timingMode === "bench";
+  const data = budgets();
+  const result = resolveLimit(data, key, opts, bench);
+  if (bench && env.SHARD_PERF_REPORT) {
+    const call = { key, opts, used: false, ...result };
+    globalThis.__shardBudget = call;
+  }
+  return result.limit;
 }
 function timeout(ms) {
   return timingMode === "ci" ? ms * 5 : ms;
@@ -26,11 +91,14 @@ function gcWindow() {
     }
   };
 }
-const allocationChecks = timingMode !== "ci";
+const allocationChecks = timingMode === "bench";
 export {
   allocationChecks,
   budget,
   gcWindow,
+  passTiming,
+  resolveLimit,
+  scenarioSlices,
   slack,
   timeout,
   timingMode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-core",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -9,6 +9,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./capture": {
+      "types": "./dist/scheduler/capture/index.d.ts",
+      "default": "./dist/scheduler/capture/index.js"
+    },
     "./math": {
       "types": "./dist/math/index.d.ts",
       "default": "./dist/math/index.js"
@@ -33,6 +37,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
   }
 }