@nite-framework/nite-zk-profiler 0.1.3 → 0.2.0

package/README.md

@@ -370,15 +370,113 @@ Anything outside this range is rejected with a clear error naming the version fo
 ## Command line surface
 
 ```text
-nite-zk profile <source>     Report rows, k and relative cost per circuit
-nite-zk save <source>        Write zk-budget.json from current measurements
-nite-zk check [<source>]     Measure and compare against zk-budget.json
+nite-zk profile <source...>   Report rows, k and relative cost per circuit
+nite-zk save <source...>      Write zk-budget.json from current measurements
+nite-zk check [<source...>]   Compare against zk-budget.json
+nite-zk diff <ref> [<source>] Compare a contract against a git ref
+nite-zk calibrate --observed <ms> --at-k <k>
+                              Anchor proving estimates to a real proof
+
+  --estimate                  Show modelled proving time per circuit
+  --deep                      Also generate real proving keys, and report
+                              measured setup time and prover key size
+  --json                      Machine readable output
+  --out <dir>                 Compile into a specific directory
+  --budget <file>             Use a different baseline path
+  --strict                    check: fail on circuits missing from the budget
+  --no-color                  Plain output (NO_COLOR is honoured too)
+  --no-cache                  Ignore cached measurements for this run
+  +VERSION                    Pin the Compact toolchain, e.g. +0.31.1
+```
+
+### Several contracts at once
+
+Pass more than one entry point, and one budget file covers them all:
+
+```text
+$ nite-zk save packages/pool/src/lending.compact packages/mint/src/mint.compact
+Wrote zk-budget.json: 2 contracts, 16 circuits
+```
+
+`check` then reads every contract back out of the budget, so CI stays one step
+whether the repository holds one contract or ten.
+
+### Comparing against a branch
+
+```text
+$ nite-zk diff main
+
+  transferFunds  k  15 ->  16   +1, about 2x more expensive
+  proveMembership k 16 ->  16   unchanged
+  newHelper      k   - ->   9   new circuit
+
+  1 circuit more expensive than main
+```
 
-  --json                     Machine readable output
-  --out <dir>                Compile into a specific directory
-  --budget <file>            Use a different baseline path
+The ref is exported with `git archive` into a temporary directory, so the
+working tree and the index are never touched. Exits nonzero when a circuit that
+already existed got more expensive, which makes it usable as a pull request
+check without committing a budget file first.
+
+### Estimated proving time
+
+`--estimate` models proving time as `time = rate * 2^k`, since a Halo2 proof is
+dominated by work over the full `2^k` domain.
+
+The rate is machine specific, so the shipped default is only an order of
+magnitude. Time one real proof and record it, and every estimate becomes
+anchored to your own prover:
+
+```text
+$ nite-zk calibrate --observed 9000 --at-k 16
+Calibrated: 0.1373 ms per domain row, from 9000ms at k=16.
 ```
 
+Two limits worth stating plainly. Proving delegated to a remote proof server is
+often dominated by network round trip and server load rather than by circuit
+size, and no model of `k` can see that. And the same gate degree effect that
+makes key size unpredictable, described below, puts a factor of about two around
+any figure derived from `k` alone. Treat it as a ratio you can reason with, not
+a stopwatch.
+
+`save` records which contracts the budget describes, so `check` needs no
+arguments afterwards. That is what makes it a one line CI step. It also records
+rows, capacity and relative cost per circuit, so a reviewer reading the diff can
+see what changed without running anything. Only `maxK` is enforced.
+
+### Measuring the real thing
+
+`--deep` stops mocking and generates actual proving keys. It answers two
+questions the fast path cannot, and both are measured rather than modelled:
+
+```text
+  circuit   rows   k  capacity   cost  setup  prover key
+  k05         24   5        32     1x  156ms       14 KB
+  k13       4189  13      8192   256x   2.3s      2.7 MB
+  k14      11965  14     16384   512x   4.6s      5.0 MB
+  k15      19657  15     32768  1024x   9.6s      9.5 MB
+```
+
+Setup time and prover key size both roughly double per step in `k`, which is
+the same 2^k curve proving time follows. The prover key size is worth attention
+on its own: it is what users download and hold in memory, and a k=15 circuit
+carries a 9.5 MB key against 14 KB at k=5.
+
+This mode is slow by design, since it does the work `--skip-zk` exists to avoid.
+Use it when choosing between designs, not in an edit loop.
+
+**Why key size is measured rather than predicted.** It looks predictable from
+`k`: three structurally unrelated circuits at k=13 agreed within 0.11%, and a
+synthetic k=15 circuit matched a production one to 0.08%. It does not hold. At
+k=16 a production circuit produced 19,524,757 bytes while a synthetic one
+produced 38,513,181, a factor of two apart, with identical verifier key sizes.
+
+The likely cause is the extended evaluation domain, which Halo2 sizes by maximum
+gate degree, and which `mock-compile` does not report. From `k` alone there is
+no way to tell which case a circuit is in, and a figure that is exact at one `k`
+and twice wrong at the next is worse than no figure. So key size comes only from
+`--deep`, where it is measured.
+
 Designed to work as a single CI step:
 
 ```yaml

package/dist/budget.d.ts

@@ -1,14 +1,33 @@
 import type { CircuitCost } from "./analyze.ts";
 export declare const DEFAULT_BUDGET_PATH = "zk-budget.json";
+/**
+ * Per circuit entry.
+ *
+ * `maxK` is the only enforced field. The rest is a snapshot recorded at save
+ * time so a reviewer reading the diff can see what changed and by how much,
+ * without running the tool. Snapshot drift never fails a check.
+ */
+export interface CircuitBudget {
+    maxK: number;
+    rows?: number;
+    capacity?: number;
+    relativeCost?: number;
+}
+export interface ContractBudget {
+    circuits: Record<string, CircuitBudget>;
+}
 export interface Budget {
+    /** Which release wrote this, so an old file can be recognised. */
+    tool?: string;
     /** Toolchain line the ceilings were established against. */
     toolchain: string;
-    circuits: Record<string, {
-        maxK: number;
-    }>;
+    generated?: string;
+    /** Keyed by source path, relative to the budget file. */
+    contracts: Record<string, ContractBudget>;
 }
 export type Status = "under" | "at" | "over" | "undeclared" | "stale";
 export interface CheckRow {
+    contract: string;
     circuit: string;
     status: Status;
     k?: number;
@@ -18,16 +37,23 @@ export interface CheckResult {
     rows: CheckRow[];
     failed: boolean;
 }
-/** Build a budget that grants every circuit exactly what it currently costs. */
-export declare function budgetFrom(costs: CircuitCost[], toolchainLine: string): Budget;
+/** Measurements for one contract, as the CLI collects them. */
+export interface ContractCosts {
+    source: string;
+    costs: CircuitCost[];
+}
+/** Build a budget granting every circuit exactly what it currently costs. */
+export declare function budgetFrom(contracts: ContractCosts[], toolchainLine: string): Budget;
 export declare function writeBudget(path: string, budget: Budget): void;
 export declare function readBudget(path: string): Budget;
+/** Every contract the budget describes. */
+export declare function budgetSources(budget: Budget): string[];
 /**
  * Compare measurements against declared ceilings.
  *
- * The gate is a ceiling, not a diff against the last run. A circuit's `k` rising
- * is often intentional, so only exceeding a ceiling the project has committed to
- * is a failure. Raising a ceiling deliberately is a one line change a reviewer
- * sees, which is the point.
+ * The gate is a ceiling, not a diff against the last run. A circuit's `k`
+ * rising is often intentional, so only exceeding a ceiling the project has
+ * committed to is a failure. Raising a ceiling deliberately is a one line
+ * change a reviewer sees, which is the point.
  */
-export declare function check(costs: CircuitCost[], budget: Budget, strict: boolean): CheckResult;
+export declare function check(measured: ContractCosts[], budget: Budget, strict: boolean): CheckResult;

package/dist/budget.js

@@ -1,17 +1,49 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { ProfilerError } from "./errors.js";
+import { toolVersion } from "./version.js";
 export const DEFAULT_BUDGET_PATH = "zk-budget.json";
-/** Build a budget that grants every circuit exactly what it currently costs. */
-export function budgetFrom(costs, toolchainLine) {
-    const circuits = {};
-    for (const c of [...costs].sort((a, b) => a.circuit.localeCompare(b.circuit))) {
-        circuits[c.circuit] = { maxK: c.k };
+/** Build a budget granting every circuit exactly what it currently costs. */
+export function budgetFrom(contracts, toolchainLine) {
+    const out = {};
+    for (const { source, costs } of [...contracts].sort((a, b) => a.source.localeCompare(b.source))) {
+        const circuits = {};
+        for (const c of [...costs].sort((a, b) => a.circuit.localeCompare(b.circuit))) {
+            circuits[c.circuit] = {
+                maxK: c.k,
+                rows: c.rows,
+                capacity: c.capacity,
+                relativeCost: c.relativeCost,
+            };
+        }
+        out[source] = { circuits };
     }
-    return { toolchain: toolchainLine, circuits };
+    return {
+        tool: `nite-zk-profiler ${toolVersion()}`,
+        toolchain: toolchainLine,
+        generated: new Date().toISOString(),
+        contracts: out,
+    };
 }
 export function writeBudget(path, budget) {
     writeFileSync(path, `${JSON.stringify(budget, null, 2)}\n`, "utf8");
 }
+/** Bring the pre multi contract shape forward, so old files keep working. */
+function normalise(parsed, path) {
+    if ("contracts" in parsed && parsed.contracts)
+        return parsed;
+    const legacy = parsed;
+    if (!legacy.circuits) {
+        throw new ProfilerError(`Malformed budget file: ${path}`, 'Expected a "contracts" map. Rewrite it with `nite-zk save <source>`.');
+    }
+    return {
+        toolchain: legacy.toolchain,
+        contracts: {
+            [legacy.source ?? ""]: {
+                circuits: Object.fromEntries(Object.entries(legacy.circuits).map(([n, e]) => [n, { maxK: e.maxK }])),
+            },
+        },
+    };
+}
 export function readBudget(path) {
     let raw;
     try {
@@ -27,50 +59,75 @@ export function readBudget(path) {
     catch (e) {
         throw new ProfilerError(`Could not parse ${path}`, String(e));
     }
-    const budget = parsed;
-    if (!budget || typeof budget !== "object" || typeof budget.circuits !== "object") {
-        throw new ProfilerError(`Malformed budget file: ${path}`, 'Expected {"toolchain": "...", "circuits": {"name": {"maxK": N}}}.');
+    if (!parsed || typeof parsed !== "object") {
+        throw new ProfilerError(`Malformed budget file: ${path}`, "Expected a JSON object.");
     }
-    for (const [name, entry] of Object.entries(budget.circuits)) {
-        if (!entry || typeof entry.maxK !== "number" || !Number.isInteger(entry.maxK)) {
-            throw new ProfilerError(`Malformed budget entry for "${name}" in ${path}`, 'Each circuit needs an integer "maxK".');
+    const budget = normalise(parsed, path);
+    for (const [source, contract] of Object.entries(budget.contracts)) {
+        for (const [name, entry] of Object.entries(contract.circuits ?? {})) {
+            if (!entry || typeof entry.maxK !== "number" || !Number.isInteger(entry.maxK)) {
+                throw new ProfilerError(`Malformed budget entry for "${name}" in ${source || path}`, 'Each circuit needs an integer "maxK".');
+            }
         }
     }
     return budget;
 }
+/** Every contract the budget describes. */
+export function budgetSources(budget) {
+    return Object.keys(budget.contracts).filter((s) => s.length > 0);
+}
 /**
  * Compare measurements against declared ceilings.
  *
- * The gate is a ceiling, not a diff against the last run. A circuit's `k` rising
- * is often intentional, so only exceeding a ceiling the project has committed to
- * is a failure. Raising a ceiling deliberately is a one line change a reviewer
- * sees, which is the point.
+ * The gate is a ceiling, not a diff against the last run. A circuit's `k`
+ * rising is often intentional, so only exceeding a ceiling the project has
+ * committed to is a failure. Raising a ceiling deliberately is a one line
+ * change a reviewer sees, which is the point.
  */
-export function check(costs, budget, strict) {
+export function check(measured, budget, strict) {
     const rows = [];
     let failed = false;
-    for (const cost of costs) {
-        const declared = budget.circuits[cost.circuit];
-        if (!declared) {
-            rows.push({ circuit: cost.circuit, status: "undeclared", k: cost.k });
-            if (strict)
+    for (const { source, costs } of measured) {
+        const declared = budget.contracts[source]?.circuits ??
+            // A legacy budget stores its single contract under "", so fall back to it
+            // when only one contract is declared and the path does not match.
+            (Object.keys(budget.contracts).length === 1
+                ? Object.values(budget.contracts)[0].circuits
+                : {});
+        for (const cost of costs) {
+            const entry = declared[cost.circuit];
+            if (!entry) {
+                rows.push({
+                    contract: source,
+                    circuit: cost.circuit,
+                    status: "undeclared",
+                    k: cost.k,
+                });
+                if (strict)
+                    failed = true;
+                continue;
+            }
+            let status = "under";
+            if (cost.k > entry.maxK) {
+                status = "over";
                 failed = true;
-            continue;
+            }
+            else if (cost.k === entry.maxK) {
+                status = "at";
+            }
+            rows.push({
+                contract: source,
+                circuit: cost.circuit,
+                status,
+                k: cost.k,
+                maxK: entry.maxK,
+            });
         }
-        let status = "under";
-        if (cost.k > declared.maxK) {
-            status = "over";
-            failed = true;
-        }
-        else if (cost.k === declared.maxK) {
-            status = "at";
-        }
-        rows.push({ circuit: cost.circuit, status, k: cost.k, maxK: declared.maxK });
-    }
-    const measured = new Set(costs.map((c) => c.circuit));
-    for (const name of Object.keys(budget.circuits)) {
-        if (!measured.has(name)) {
-            rows.push({ circuit: name, status: "stale", maxK: budget.circuits[name].maxK });
+        const seen = new Set(costs.map((c) => c.circuit));
+        for (const [name, entry] of Object.entries(declared)) {
+            if (!seen.has(name)) {
+                rows.push({ contract: source, circuit: name, status: "stale", maxK: entry.maxK });
+            }
         }
     }
     return { rows, failed };

package/dist/cache.d.ts

@@ -0,0 +1,16 @@
+import type { Measurement } from "./measure.ts";
+import type { Toolchain } from "./toolchain.ts";
+/**
+ * Measurement cache, keyed on the emitted IR rather than on the source.
+ *
+ * Compilation is the cheap half: on a nine circuit contract it took 1.1s
+ * against 17s to measure. So the compile always runs, and its output is used as
+ * the cache key. Identical IR provably yields identical constraint counts, so
+ * this cannot go stale in a way that produces a wrong answer, which a source
+ * timestamp or a partial import scan could.
+ */
+export declare function cacheDir(): string;
+/** Hash every emitted IR file, plus the toolchain that produced and reads it. */
+export declare function cacheKey(zkirDir: string, toolchain: Toolchain): string;
+export declare function readCache(key: string): Measurement[] | undefined;
+export declare function writeCache(key: string, measurements: Measurement[]): void;

package/dist/cache.js

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { toolVersion } from "./version.js";
+/**
+ * Measurement cache, keyed on the emitted IR rather than on the source.
+ *
+ * Compilation is the cheap half: on a nine circuit contract it took 1.1s
+ * against 17s to measure. So the compile always runs, and its output is used as
+ * the cache key. Identical IR provably yields identical constraint counts, so
+ * this cannot go stale in a way that produces a wrong answer, which a source
+ * timestamp or a partial import scan could.
+ */
+export function cacheDir() {
+    return process.env.NITE_ZK_CACHE || join(tmpdir(), "nite-zk-profiler-cache");
+}
+/** Hash every emitted IR file, plus the toolchain that produced and reads it. */
+export function cacheKey(zkirDir, toolchain) {
+    const hash = createHash("sha256");
+    // The profiler's own version is part of the key. Without it, upgrading the
+    // tool would keep serving results produced by the previous measurement code,
+    // which looks exactly like the upgrade having no effect.
+    hash.update(toolVersion());
+    hash.update(toolchain.version);
+    hash.update(toolchain.zkirVersion);
+    for (const file of readdirSync(zkirDir).filter((f) => f.endsWith(".zkir")).sort()) {
+        hash.update(file);
+        hash.update(readFileSync(join(zkirDir, file)));
+    }
+    return hash.digest("hex").slice(0, 32);
+}
+export function readCache(key) {
+    const file = join(cacheDir(), `${key}.json`);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        // A corrupt entry is not worth failing over; measure again instead.
+        return undefined;
+    }
+}
+export function writeCache(key, measurements) {
+    try {
+        mkdirSync(cacheDir(), { recursive: true });
+        writeFileSync(join(cacheDir(), `${key}.json`), JSON.stringify(measurements), "utf8");
+    }
+    catch {
+        // Caching is an optimisation. Failing to write one must never fail a run.
+    }
+}

package/dist/cli.d.ts

@@ -1,16 +1,23 @@
 #!/usr/bin/env node
 interface Options {
     command?: string;
-    source?: string;
+    sources: string[];
+    ref?: string;
     json: boolean;
     strict: boolean;
+    deep: boolean;
+    estimate: boolean;
+    noColor: boolean;
+    noCache: boolean;
     out?: string;
     budget: string;
     versionArg?: string;
+    observedMs?: number;
+    atK?: number;
     help: boolean;
     version: boolean;
 }
 export declare function parseArgs(argv: string[]): Options;
-export declare function run(argv: string[]): number;
-export declare function main(argv: string[]): number;
+export declare function run(argv: string[]): Promise<number>;
+export declare function main(argv: string[]): Promise<number>;
 export {};