@nite-framework/nite-zk-profiler 0.2.1 → 0.2.3

package/README.md

@@ -45,7 +45,8 @@ $ nite-zk profile Sample.compact
   insert32    2299  13      8192  256x         ~2.6s
 
   4 circuits, toolchain 0.31.1, midnight-zkir 2.1.0, 0.9s
-  est. prove is modelled as 2^k on an uncalibrated default. Run `nite-zk calibrate` to anchor it.
+  est. prove models prover work as 2^k, on an uncalibrated default. Run `nite-zk calibrate` to anchor it to your prover.
+  It excludes network time, and assumes the proving key for that k is already on the prover.
 ```
 
 `k` is the number that matters. `cost` is `2^k` expressed relative to the cheapest circuit in the contract, so you can see at a glance which circuits dominate your proving budget.
@@ -385,6 +386,7 @@ nite-zk calibrate --observed <ms> --at-k <k>
   --out <dir>                 Compile into a specific directory
   --budget <file>             Use a different baseline path
   --strict                    check: fail on circuits missing from the budget
+  --replace                   save: overwrite the budget instead of merging
   --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
@@ -402,6 +404,23 @@ 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.
 
+Contracts can also be added one at a time. `save` merges into an existing
+budget rather than replacing it, and says what it did:
+
+```text
+$ nite-zk save packages/mint/src/mint.compact
+Wrote /repo/zk-budget.json
+  1 contract, 3 circuits
+  added:   packages/mint/src/mint.compact
+  kept:    packages/pool/src/lending.compact
+```
+
+`--replace` writes a fresh file when you do want the old entries gone.
+
+The budget is written relative to the working directory, and `save` prints the
+full path it wrote, so running it from the wrong directory is visible
+immediately rather than leaving a file somewhere unexpected.
+
 ### Comparing against a branch
 
 ```text
@@ -434,12 +453,15 @@ $ 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.
+The figure models **prover work only**. It excludes network round trip and
+server queueing, and it assumes the proving key for that `k` is already on the
+prover rather than being fetched. Wall clock time against a remote proof server
+is frequently dominated by exactly those two things, which no model of `k` can
+see. 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.
+
+So it answers "how much work is this circuit" rather than "how long will my user
+wait". The first is what you control while writing Compact.
 
 `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

package/dist/budget.d.ts

@@ -44,6 +44,22 @@ export interface ContractCosts {
 }
 /** Build a budget granting every circuit exactly what it currently costs. */
 export declare function budgetFrom(contracts: ContractCosts[], toolchainLine: string): Budget;
+export interface MergeSummary {
+    added: string[];
+    updated: string[];
+    kept: string[];
+}
+/**
+ * Fold a new save into an existing budget.
+ *
+ * Saving one contract must not silently discard the others. A monorepo is
+ * saved a contract at a time, and without merging each save wipes the previous
+ * one, which looks like it worked and quietly loses the ceilings you committed.
+ */
+export declare function mergeBudgets(existing: Budget, incoming: Budget): {
+    budget: Budget;
+    summary: MergeSummary;
+};
 export declare function writeBudget(path: string, budget: Budget): void;
 export declare function readBudget(path: string): Budget;
 /** Every contract the budget describes. */

package/dist/budget.js

@@ -24,6 +24,33 @@ export function budgetFrom(contracts, toolchainLine) {
         contracts: out,
     };
 }
+/**
+ * Fold a new save into an existing budget.
+ *
+ * Saving one contract must not silently discard the others. A monorepo is
+ * saved a contract at a time, and without merging each save wipes the previous
+ * one, which looks like it worked and quietly loses the ceilings you committed.
+ */
+export function mergeBudgets(existing, incoming) {
+    const contracts = { ...existing.contracts };
+    const summary = { added: [], updated: [], kept: [] };
+    for (const [source, contract] of Object.entries(incoming.contracts)) {
+        (source in contracts ? summary.updated : summary.added).push(source);
+        contracts[source] = contract;
+    }
+    for (const source of Object.keys(existing.contracts)) {
+        if (!(source in incoming.contracts) && source.length > 0)
+            summary.kept.push(source);
+    }
+    return {
+        budget: { ...incoming, contracts },
+        summary: {
+            added: summary.added.sort(),
+            updated: summary.updated.sort(),
+            kept: summary.kept.sort(),
+        },
+    };
+}
 export function writeBudget(path, budget) {
     writeFileSync(path, `${JSON.stringify(budget, null, 2)}\n`, "utf8");
 }

package/dist/cli.d.ts

@@ -5,6 +5,7 @@ interface Options {
     ref?: string;
     json: boolean;
     strict: boolean;
+    replace: boolean;
     deep: boolean;
     estimate: boolean;
     noColor: boolean;

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { analyze } from "./analyze.js";
-import { DEFAULT_BUDGET_PATH, budgetFrom, budgetSources, check, readBudget, writeBudget, } from "./budget.js";
+import { DEFAULT_BUDGET_PATH, budgetFrom, budgetSources, check, mergeBudgets, readBudget, writeBudget, } from "./budget.js";
 import { cacheKey, readCache, writeCache } from "./cache.js";
 import { setColorEnabled } from "./colors.js";
 import { compileSkipZk } from "./compile.js";
@@ -34,6 +34,7 @@ Options:
   --out <dir>                   Compile into a specific directory (kept)
   --budget <file>               Budget path (default: ${DEFAULT_BUDGET_PATH})
   --strict                      check: fail on circuits missing from the budget
+  --replace                     save: overwrite the budget instead of merging
   --no-color                    Plain output (also honours NO_COLOR)
   --no-cache                    Ignore cached measurements for this run
   +VERSION                      Pin the Compact toolchain, e.g. +0.31.1
@@ -47,6 +48,7 @@ export function parseArgs(argv) {
         sources: [],
         json: false,
         strict: false,
+        replace: false,
         deep: false,
         estimate: true,
         noColor: false,
@@ -61,6 +63,8 @@ export function parseArgs(argv) {
             opts.json = true;
         else if (arg === "--strict")
             opts.strict = true;
+        else if (arg === "--replace")
+            opts.replace = true;
         else if (arg === "--deep")
             opts.deep = true;
         else if (arg === "--estimate")
@@ -262,12 +266,36 @@ export async function run(argv) {
     // stored relative to the budget file so the pair stays portable.
     const base = dirname(resolve(opts.budget));
     const line = `${run_.toolchain.version.split(".").slice(0, 2).join(".")}.x`;
-    const budget = budgetFrom(run_.contracts.map((c) => ({ source: relative(base, resolve(c.source)), costs: c.costs })), line);
-    writeBudget(opts.budget, budget);
+    const fresh = budgetFrom(run_.contracts.map((c) => ({ source: relative(base, resolve(c.source)), costs: c.costs })), line);
+    // Merge rather than overwrite. Saving one contract at a time is the normal
+    // way to set up a monorepo, and replacing the file each time would discard
+    // ceilings that are already committed, silently and while reporting success.
+    let existing;
+    if (!opts.replace) {
+        try {
+            existing = readBudget(opts.budget);
+        }
+        catch {
+            existing = undefined;
+        }
+    }
+    const merged = existing ? mergeBudgets(existing, fresh) : { budget: fresh, summary: undefined };
+    writeBudget(opts.budget, merged.budget);
     const circuits = run_.contracts.reduce((n, c) => n + c.costs.length, 0);
-    process.stdout.write(`Wrote ${opts.budget}: ${run_.contracts.length} contract${run_.contracts.length === 1 ? "" : "s"}, ` +
-        `${circuits} circuit${circuits === 1 ? "" : "s"}\n` +
-        "Check it in, then run `nite-zk check` in CI.\n");
+    const written = resolve(opts.budget);
+    process.stdout.write(`Wrote ${written}\n` +
+        `  ${run_.contracts.length} contract${run_.contracts.length === 1 ? "" : "s"}, ` +
+        `${circuits} circuit${circuits === 1 ? "" : "s"}\n`);
+    const s_ = merged.summary;
+    if (s_) {
+        if (s_.added.length)
+            process.stdout.write(`  added:   ${s_.added.join(", ")}\n`);
+        if (s_.updated.length)
+            process.stdout.write(`  updated: ${s_.updated.join(", ")}\n`);
+        if (s_.kept.length)
+            process.stdout.write(`  kept:    ${s_.kept.join(", ")}\n`);
+    }
+    process.stdout.write("Check it in, then run `nite-zk check` in CI.\n");
     return 0;
 }
 export async function main(argv) {

package/dist/report.js

@@ -88,8 +88,11 @@ export function formatProfile(contracts, opts) {
     }
     if (opts.showEstimate) {
         lines.push(gray(opts.calibration
-            ? `  est. prove is modelled as 2^k, calibrated from an observed ${formatDuration(opts.calibration.observedMs)} proof at k=${opts.calibration.observedK}.`
-            : "  est. prove is modelled as 2^k on an uncalibrated default. Run `nite-zk calibrate` to anchor it."));
+            ? `  est. prove models prover work as 2^k, calibrated from an observed ` +
+                `${formatDuration(opts.calibration.observedMs)} proof at k=${opts.calibration.observedK}.`
+            : "  est. prove models prover work as 2^k, on an uncalibrated default. " +
+                "Run `nite-zk calibrate` to anchor it to your prover."));
+        lines.push(gray("  It excludes network time, and assumes the proving key for that k is already on the prover."));
     }
     lines.push("");
     return lines.join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nite-framework/nite-zk-profiler",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "See what a Compact circuit costs to prove, without generating proving keys",
   "type": "module",
   "bin": {
@@ -23,7 +23,8 @@
     "zero-knowledge",
     "profiler",
     "proving-cost",
-    "nite-zk-profiler"
+    "nite-zk-profiler",
+    "@nite-framework/nite-zk-profiler"
   ],
   "license": "MIT",
   "repository": {