@nite-framework/nite-zk-profiler 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codeBigInt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,433 @@
+# nite-zk-profiler
+
+See what a Compact circuit costs to prove, while you are still writing it.
+
+No proving keys. No real proof. A small contract reports in under a second, and a thirteen circuit production contract in about thirty, nearly all of which is the Compact compiler itself. Measuring the same contract by generating proving keys takes far longer.
+
+> Every number and command output in this document was captured from a real toolchain run on Compact 0.31.1, not invented. See [Verified mechanism](#verified-mechanism) for the raw evidence.
+
+## The problem
+
+Proving cost does not rise smoothly with circuit size. It rises in steps.
+
+Every circuit is assigned a `k`. The prover works over `2^k` rows, and everything you pay for, proving time and peak memory, is set by `k`. Each step up in `k` roughly doubles the bill.
+
+The trap is that **`k` is not a function of how much code you wrote.** It is set by which ledger operations and witness calls your circuit performs, and by the shape of the data they touch. Measured on real circuits:
+
+| circuit | what it does | rows | k | relative cost |
+| --- | --- | --- | --- | --- |
+| `bump` | one Counter increment | 24 | 5 | 1x |
+| `manyIncrements` | twelve Counter increments | 24 | 7 | 4x |
+| `justAdd` | Counter increment with a cast | 191 | 8 | 8x |
+| `justCompare` | one Boolean write from one comparison | 119 | 9 | 16x |
+| `balanceOf` | one Map lookup | 305 | 9 | 16x |
+| `register` | Map insert plus Counter increment | 368 | 9 | 16x |
+| `insert32` | one MerkleTree insert | 2299 | 13 | 256x |
+| `prove32` | one MerkleTree path check, depth 32 | 3551 | 13 | 256x |
+
+Read that table twice. `manyIncrements` does twelve times the work of `bump` in exactly the same 24 rows, and still costs four times as much to prove. `justCompare` writes a single boolean and costs sixteen times `bump`. `justAdd` uses more rows than `justCompare` and costs half as much. Touching a MerkleTree at all costs 256 times a counter increment.
+
+None of this is visible in the source. None of it is proportional to lines of code. And today the only way to find out is to generate proving keys and time a real proof, which is far too slow to sit in an edit loop. So the expensive choice gets made early, silently, and shows up much later as a user facing performance problem.
+
+This tool makes `k` visible while you are still choosing your data model.
+
+## What the tool does
+
+It reports the cost class of every circuit in your contract.
+
+```text
+$ nite-zk profile Sample.compact
+
+  circuit        rows      k   capacity   cost
+  bump             24      5         32     1x
+  balanceOf       305      9        512    16x
+  register        368      9        512    16x
+  insert32       2299     13       8192   256x
+
+  4 circuits, toolchain 0.31.1, zkir 2.1.0, 0.4s
+```
+
+`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.
+
+It also supports a committed cost budget, so an unintended increase fails CI instead of shipping:
+
+```text
+$ nite-zk check
+
+  transferFunds     k 16   budget 15   over by 1, about 2x
+  proveMembership   k 16   budget 16   at budget
+  setConfig         k  9   budget  9   at budget
+
+  FAIL: 1 circuit over budget
+```
+
+The budget is a ceiling you declare, not a snapshot of the last run. Raising `k` on purpose means raising the ceiling in the same commit, where a reviewer sees it.
+
+## Scope
+
+In scope for this release:
+
+- Per circuit `rows`, `k`, capacity, and relative cost
+- `zk-budget.json` declared cost ceilings: write them, and check against them
+- Nonzero exit when a circuit exceeds its declared `maxK`, so it drops into CI as one step
+- Multi file contracts
+- A measured cost reference for Compact constructs, so a developer reading a high `k` knows what to do about it
+
+Explicitly out of scope:
+
+- Per line attribution by ablation. Proposed and deliberately cut. It may be proposed separately later.
+- The VS Code extension. The tool is built so an extension could consume its JSON output later, but that is not part of this work.
+
+## Architecture
+
+The tool is a thin, honest wrapper around two programs that already ship with the Compact toolchain. It does not model proving cost itself, it does not reimplement any part of the compiler, and it does not guess. It runs the shipped tools and reads what they report.
+
+### Pipeline
+
+```mermaid
+flowchart TD
+    A["Compact source file"] --> B["1. Resolve toolchain"]
+    B --> C["2. compact compile --skip-zk"]
+    C --> D["out/zkir/*.zkir<br/>one file per exported circuit"]
+    D --> E["3. zkir mock-compile-many"]
+    E --> F["4. Parse rows and k per circuit"]
+    F --> G{"Mode"}
+    G -->|"profile"| H["Print table, or JSON"]
+    G -->|"save"| I["Write zk-budget.json"]
+    G -->|"check"| J["Compare against baseline"]
+    J --> K{"Any circuit at a higher k?"}
+    K -->|"no"| L["exit 0"]
+    K -->|"yes"| M["Print diff, exit 1"]
+```
+
+Each stage is described below.
+
+### Stage 1: resolve the toolchain
+
+This is the most important stage in the tool, and the condition that is easiest to get wrong.
+
+`zkir` is not on your `PATH`. It ships inside each installed toolchain version:
+
+```text
+~/.compact/versions/0.31.1/x86_64-unknown-linux-musl/
+    zkir        (midnight-zkir 2.1.0,     reads IR version 2.0)
+    zkir-v3     (midnight-zkir-v3 3.0.0,  reads IR version 3.0)
+```
+
+Two binaries, identical command line interfaces, incompatible IR formats. If the profiler ever picks a `zkir` from a different toolchain than the compiler that produced the IR, the results are meaningless or the run breaks outright.
+
+So the binary is always resolved from the version directory of the compiler that actually ran:
+
+```mermaid
+flowchart TD
+    A["Start"] --> B["Determine compiler version<br/>(+VERSION arg, or the configured default)"]
+    B --> C["Resolve artifact root<br/>COMPACT_DIRECTORY, else ~/.compact"]
+    C --> D["versions/VERSION/TARGET/"]
+    D --> E{"Version supported?"}
+    E -->|"no"| F["Error: unsupported toolchain,<br/>name the version and what is supported"]
+    E -->|"yes"| G["Select the zkir in that same directory"]
+    G --> H["Confirm with zkir --version"]
+    H --> I["Use it for every mock-compile in this run"]
+```
+
+Three rules follow, and they are load bearing:
+
+1. **Never resolve `zkir` from `PATH`.** Only from the version directory.
+2. **Never fall back to another version.** If the paired binary is missing, that is an error, not a reason to reach for a neighbour.
+3. **Refuse unknown versions up front,** naming the version found and the versions supported, rather than producing a number that looks plausible and is wrong.
+
+The failure this prevents is real and it is quiet. Running the v3 binary against v2 IR does not fail cleanly at the start:
+
+```text
+$ zkir-v3 mock-compile-many out/zkir
+Mock compiling 2 circuits:
+  circuit "balanceOf"Error: Unhandled version: 2.0
+```
+
+It prints the beginning of a normal, successful looking report, then dies partway through the first circuit. A parser that reads line by line without checking the exit code would report a partial result as a complete one. The tool checks the exit code on every invocation and treats a truncated report as a hard failure.
+
+### Stage 2: compile without proving keys
+
+```text
+compact compile --skip-zk <source> <outdir>
+```
+
+`--skip-zk` is what makes this fast enough to sit in an edit loop. It produces the intermediate representation and skips proving key generation entirely, which is the slow part.
+
+The output directory looks like this:
+
+```text
+out/
+    zkir/
+        balanceOf.zkir        <- one file per exported circuit
+        register.zkir
+    compiler/
+        contract-info.json
+    contract/
+        index.js, index.d.ts, index.js.map
+```
+
+Only `out/zkir/` matters here. The tool compiles into a temporary directory by default so it never disturbs your project's own build output.
+
+Two failure modes get explicit handling:
+
+- **A contract with no provable circuits emits no `out/zkir/` directory at all.** Circuits that touch neither the ledger nor a witness compile to nothing and need no proof. Running `zkir` at that point produces a bare `Error: No such file or directory`, which explains nothing. The tool detects the empty case first and reports that the contract has no provable circuits.
+- **A compile error exits 255** through the launcher, with diagnostics on stdout. Those are surfaced as is rather than being reworded, since the compiler's own messages are better than anything the tool would invent.
+
+### Stage 3: measure
+
+```text
+zkir mock-compile-many out/zkir
+```
+
+One invocation covers every circuit, and it reports circuit names directly:
+
+```text
+Mock compiling 2 circuits:
+  circuit "balanceOf" (k=9, rows=305)
+  circuit "register" (k=9, rows=368)
+```
+
+Two details drive the implementation:
+
+- **This is written to stderr, not stdout.** Reading stdout gives you an empty string and a report with zero circuits. That is a silent wrong answer rather than a crash, so it is worth stating plainly.
+- **`mock-compile-many` is preferred over per file `mock-compile`.** The single file form reports the full file path instead of the circuit name, which would leave the tool recovering names from filenames. The batch form gives clean names and costs one process instead of one per circuit.
+
+### Stage 4: analyse
+
+`rows` and `k` are both read from the `zkir` output. **`k` is never computed locally, because it cannot be.**
+
+This is the central design constraint of the tool, and it is worth being precise about. It would be natural to assume `k = ceil(log2(rows))` and derive everything from a row count. The measurements say otherwise:
+
+- `bump` and `manyIncrements` both use **24 rows**, and report **k=5** and **k=7**.
+- `justCompare` uses **119 rows** at **k=9**, while `justAdd` uses **191 rows** at **k=8**. More rows, lower `k`.
+
+So any formula mapping rows to `k` is wrong, and a tool built on one would report confident, incorrect costs. `k` comes from `zkir` or it does not come at all.
+
+The same evidence rules out a headroom metric. There is no honest way to say "this circuit has N rows left before its cost doubles," because rows are not what pushes a circuit to the next `k`. Reporting one would be inventing a number.
+
+The only derived value is capacity:
+
+```text
+capacity     = 2^k
+relative cost = 2^(k - lowest k in this contract)
+```
+
+`k` is stable and deterministic per circuit. The same circuit reports the same `k` across reruns, and is unaffected by which other circuits share the contract, which is what makes it sound to use as a committed budget.
+
+### Stage 5: report or gate
+
+Three modes over the same measurement.
+
+```mermaid
+flowchart LR
+    A["Measurements"] --> B["profile"]
+    A --> C["save"]
+    A --> D["check"]
+    B --> E["Human table, or --json<br/>exit 0"]
+    C --> F["zk-budget.json<br/>committed to the repo"]
+    D --> G["Compare to declared budget"]
+    F -.->|"read back"| G
+    G --> H["exit 0 or exit 1"]
+```
+
+**The gate compares against a declared budget, not against the last run.** This distinction is the whole design.
+
+A circuit's `k` going up is not automatically a bug. Adding a MerkleTree for stronger privacy, or an extra commitment for replay protection, raises `k` and is supposed to. A tool that fails the build every time cost rises for a good reason gets switched off within a week, and then it protects nothing.
+
+So `zk-budget.json` records the cost you have consciously accepted:
+
+```json
+{
+  "toolchain": "0.31.x",
+  "circuits": {
+    "proveMembership":  { "maxK": 16 },
+    "transferFunds": { "maxK": 15 },
+    "setConfig": { "maxK": 9 }
+  }
+}
+```
+
+`check` fails only when a circuit exceeds its declared `maxK`. Raising a ceiling on purpose is a one line edit committed alongside the change that caused it:
+
+```diff
+-    "transferFunds": { "maxK": 15 }
++    "transferFunds": { "maxK": 16 }
+```
+
+That line is the point. It turns a silent 2x proving cost increase into something a reviewer sees and approves, without ever blocking a deliberate design decision. The gate is an acknowledgement mechanism, not a prohibition.
+
+Behavior in the remaining cases:
+
+- **Circuit under budget:** pass, and report the slack so an over generous ceiling is visible.
+- **New circuit not in the budget:** pass with a warning by default, fail under `--strict` so mature projects can require every circuit to be declared.
+- **Circuit removed from the contract:** pass, with a note that the budget entry is stale.
+- **Row growth within the same `k`:** reported, never fails. Rows do not predict `k`, so a row threshold would fire on changes that cost nothing and stay silent on changes that cost sixteen times more.
+
+## Cost model
+
+Every construct below was measured by compiling one factor at a time into an otherwise fixed contract and reading the row delta. Marginal cost per occurrence, on Compact 0.31.1:
+
+| construct | rows each |
+| --- | --- |
+| `persistentHash<Vector<n, _>>` | `1956 + 1930 * ceil(n/2)`, plus 33 when `n` is odd |
+| `persistentCommit<S>` where `S` has `f` fields | same as `persistentHash` of width `f + 1` |
+| `MerkleTree.insert` | 1996 |
+| `witness` call | 258 |
+| `transientHash<Vector<n, _>>` | 22 per element |
+| `if / else` block | 31 |
+| `if` block | 19 |
+| `assert` on a ledger value | 13 |
+| ledger read, `Bytes<32>` | 12 |
+| `assert` on a public value | 11 |
+| ternary | 10 |
+| `Map.member`, `Set.member` | 1 |
+| `Map.insert`, `Set.insert`, ledger write | 0 |
+
+The spread is four orders of magnitude. One `persistentHash` of four inputs costs more than five hundred asserts.
+
+Validated outside the synthetic probes: removing a single `persistentHash<Vector<4, Bytes<32>>>` from a 26687 row circuit dropped it to 20862, a delta of 5825 rows. The table predicts 5817. That is 0.14% error.
+
+### Choosing between alternatives
+
+The cheap option is often the wrong option. Each lever below is stated with the constraint first, because every one of them has a case where taking it is a correctness or upgrade safety bug rather than a saving.
+
+#### Transient versus persistent hashing
+
+This is the largest cost difference in Compact, and the most dangerous to apply blindly.
+
+| primitive | rows, 2 inputs | returns | guarantee |
+| --- | --- | --- | --- |
+| `persistentHash` | 3886 | `Bytes<32>` | stable across upgrades, except on devnet |
+| `transientHash` | 44 | `Field` | **not** guaranteed stable across upgrades |
+
+The runtime documentation is explicit about which to use, and it is a semantic rule, not a performance one:
+
+- `persistentHash` and `persistentCommit` "should be used to derive state data, and not for consistency checks where avoidable."
+- `transientHash` and `transientCommit` "should not be used to derive state data, but can be used for consistency checks."
+
+**The pitfall.** Anything written into ledger state, or compared against a value that outlives the transaction, is state data and must use the persistent form. A replay protection key inserted into a `Set<Bytes<32>>` and checked on a later transaction is state data. Swapping it to `transientHash` makes the contract cheaper and breaks it on the next toolchain upgrade, silently, with no compile error and no failing test until the upgrade lands.
+
+**The trap that looks like a workaround.** `upgradeFromTransient` converts a `Field` back to `Bytes<32>` for 361 rows, so `transientHash` plus `upgradeFromTransient` costs 405 rows against `persistentHash`'s 3886, a tempting 9.6x. Do not read this as a cheap persistent hash. The function upgrades the *representation*, not the *stability guarantee*, and the value is still derived from a hash the documentation says may change between upgrades. The type system will not stop you. Treat this pattern as unsafe for state data unless Midnight documents otherwise.
+
+**A lever that may be safe, not yet demonstrated end to end.** `degradeToTransient` measured at **zero rows** in isolation, and `transientHash` at 44 rows against `persistentHash`'s 3886. That suggests the documented split is also the cheap one: derive state with `persistentHash` once, then degrade for free and run in circuit consistency checks transiently.
+
+Stated precisely, because the distinction matters: what is measured is the cost of each primitive on its own. What is **not** measured is a real circuit rewritten this way and confirmed to produce equivalent results for fewer rows. Treat the pattern as a hypothesis with good supporting numbers, and measure your own circuit before and after rather than trusting the arithmetic.
+
+Two further constraints on the persistent forms: they throw at runtime on data containing `Opaque` types, and `persistentCommit` requires an opening of exactly 32 bytes.
+
+#### Hash arity
+
+Cost steps every two inputs, so widening an even width hash by one is nearly free (33 rows) while widening an odd one is not (1897 rows).
+
+**The pitfall.** Arity is not a free tuning knob. The number and order of inputs define what the hash commits to, so changing arity changes every value it derives. If those values are in ledger state, that is a breaking state migration, not an optimization. And dropping an input to land on a cheaper parity can destroy domain separation and open a collision between two things that were previously distinct. Only spend this when you are adding a genuinely useful binding and the current width happens to be even.
+
+#### Combining hashes
+
+Four `persistentHash<Vector<2>>` calls cost 15544 rows. One `persistentHash<Vector<8>>` over the same eight values costs 9676, a 38% saving.
+
+**The pitfall.** This only applies when the intermediate hashes are not individually needed. If each narrow hash is separately stored, separately compared, or separately disclosed, merging them changes the contract's semantics. Merging is safe with respect to collisions here only because `Vector<n, Bytes<32>>` is fixed width and positional, so there is no concatenation ambiguity. Do not generalise the trick to variable length or attacker influenced inputs.
+
+#### Ledger reads and writes
+
+Writes, `Map.insert` and `Set.insert` all measured at **zero** marginal rows, because they are recorded as public ledger operations rather than proven in circuit. Reads cost 12 rows each, and reading the same field twice pays twice.
+
+**The pitfall, and it is a big one.** Zero *proving* rows does not mean free. This tool measures one cost dimension. Ledger writes still consume on chain state, transaction size, and fees, and a developer who reads "writes are free" here and starts writing liberally to state will pay for it somewhere this tool does not look. The measurement is narrow and true; the conclusion "so write more" does not follow.
+
+Hoisting a repeated read into a local is a real saving, but confirm it is a safe rewrite in your circuit before applying it, since caching a value changes behavior if anything between the two reads could alter what the second one would have seen.
+
+#### Control flow
+
+A ternary costs 10 rows and an `if / else` costs 31. Ternary is genuinely three times cheaper, and both are noise next to a single hash call. Restructuring branches while a `persistentHash` sits in the same circuit is optimising the wrong thing by a factor of roughly four hundred.
+
+> These figures describe Compact 0.31.1 and will move with the toolchain. They are measured, reproducible documentation, not something the tool computes at runtime. Automated attribution of cost back to source constructs is the ablation feature that was cut from this release.
+
+### Multi file contracts
+
+Supported, and requiring no extra configuration. Relative imports resolve against the importing file's directory, so the compiler walks the import graph itself from a single entry point:
+
+```text
+src/
+    Main.compact          <- entry point, the file you profile
+    lib/
+        Math.compact      <- import "./lib/Math";
+```
+
+Two things follow from how the compiler handles this:
+
+- **An imported file must contain a single `module` definition and nothing else.** A `pragma` or top level `import` in a module file fails with `does not contain a (single) module defintion`.
+- **Only the entry contract's exported circuits produce ZKIR.** An imported helper is inlined into whichever circuit calls it, so its cost is attributed to the circuit that actually pays for it. That is the correct behavior for a profiler: you see the true cost of each entry point, helpers included.
+
+## Supported toolchain versions
+
+| Compact toolchain | zkir | Status |
+| --- | --- | --- |
+| 0.31.x | 2.1.0 (IR 2.0) | Supported, verified on 0.31.1 |
+| 0.33.x | not yet released | Committed to support when it lands |
+
+Anything outside this range is rejected with a clear error naming the version found. The tool will not produce a number it cannot stand behind.
+
+## 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
+
+  --json                     Machine readable output
+  --out <dir>                Compile into a specific directory
+  --budget <file>            Use a different baseline path
+```
+
+Designed to work as a single CI step:
+
+```yaml
+- run: npx @nite-framework/nite-zk-profiler check src/Main.compact
+```
+
+`profile` and `check` exit 0 on success and 1 on failure, so no wrapper script is needed. `check` fails only when a circuit exceeds its declared `maxK`, or, under `--strict`, when a circuit is missing from the budget entirely.
+
+## Installing
+
+```text
+npm install --save-dev @nite-framework/nite-zk-profiler
+```
+
+The published command is `nite-zk` regardless of the package name. The package ships as ES modules and runs on Node 20 or newer, and on Bun. It expects a supported Compact toolchain already installed, since it drives `compact` and the `zkir` that ships beside it rather than bundling either.
+
+## Development
+
+```text
+npm install
+npm test          # unit tests, plus integration tests against the real toolchain
+npm run typecheck
+npm run build
+```
+
+Tests are TypeScript and run directly through Node's native type stripping, so development needs Node 22.18 or newer. The published package is plain JavaScript and runs on Node 20.
+
+The integration tests skip themselves when no supported compiler is present, so the suite still runs on a machine without one.
+
+## Verified mechanism
+
+Captured on Compact toolchain 0.31.1, language version 0.23.0, before any code was written.
+
+Toolchain behavior:
+
+- `compact compile --skip-zk` emits `out/zkir/<circuit>.zkir`, one file per exported circuit.
+- `zkir mock-compile-many <dir>` reports `(k=N, rows=N)` per named circuit, **on stderr**.
+- `zkir` reports `midnight-zkir 2.1.0`; `zkir-v3` reports `midnight-zkir-v3 3.0.0-rc.1`.
+- v3 against v2 IR fails with `Error: Unhandled version: 2.0`, exit 1, after emitting partial output.
+- A contract with no ledger or witness usage emits no `out/zkir/` directory at all.
+- Compile errors exit 255 through the launcher.
+- `mock-compile-many` over two circuits completes in roughly 50ms.
+
+Cost model:
+
+- `k` is not derivable from `rows`. Equal row counts produce different `k`; higher row counts produce lower `k`.
+- `k` is deterministic per circuit, and unaffected by the other circuits in the same contract.
+- `rows` sets a floor on `k` but does not determine it. `k` is at least `ceil(log2(rows))` across every circuit measured, and sometimes higher, so rows are the lever you pull while `k` is the price you pay.
+- MerkleTree depth changes `rows` by roughly 31 per level (2807, 3055, 3551 rows at depths 8, 16, 32) without changing `k` across that range. The `k` class was already set by the tree operation itself.
+- Every figure in the cost model table was produced by one factor at a time ablation against a fixed contract, at occurrence counts of 1, 2 and 4, and was linear in all cases.
+
+Across the contracts used to develop this tool, circuits ranged from k=9 to k=17, a 256x spread in proving cost, and in every case the expensive circuits were expensive because of hashing rather than size.

package/dist/analyze.d.ts

@@ -0,0 +1,16 @@
+import type { Measurement } from "./measure.ts";
+export interface CircuitCost extends Measurement {
+    /** Rows the prover works over: 2^k. */
+    capacity: number;
+    /** Cost relative to the cheapest circuit in this contract. */
+    relativeCost: number;
+}
+/**
+ * Derive the reportable numbers.
+ *
+ * `k` is read from zkir and never recomputed. It is not a function of `rows`:
+ * equal row counts have been observed at different `k`, and higher row counts
+ * at lower `k`. Any local formula would be confidently wrong, so the only
+ * derived values here are the ones that follow from `k` itself.
+ */
+export declare function analyze(measurements: Measurement[]): CircuitCost[];

package/dist/analyze.js

@@ -0,0 +1,18 @@
+/**
+ * Derive the reportable numbers.
+ *
+ * `k` is read from zkir and never recomputed. It is not a function of `rows`:
+ * equal row counts have been observed at different `k`, and higher row counts
+ * at lower `k`. Any local formula would be confidently wrong, so the only
+ * derived values here are the ones that follow from `k` itself.
+ */
+export function analyze(measurements) {
+    if (measurements.length === 0)
+        return [];
+    const lowestK = Math.min(...measurements.map((m) => m.k));
+    return measurements.map((m) => ({
+        ...m,
+        capacity: 2 ** m.k,
+        relativeCost: 2 ** (m.k - lowestK),
+    }));
+}

package/dist/budget.d.ts

@@ -0,0 +1,33 @@
+import type { CircuitCost } from "./analyze.ts";
+export declare const DEFAULT_BUDGET_PATH = "zk-budget.json";
+export interface Budget {
+    /** Toolchain line the ceilings were established against. */
+    toolchain: string;
+    circuits: Record<string, {
+        maxK: number;
+    }>;
+}
+export type Status = "under" | "at" | "over" | "undeclared" | "stale";
+export interface CheckRow {
+    circuit: string;
+    status: Status;
+    k?: number;
+    maxK?: number;
+}
+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;
+export declare function writeBudget(path: string, budget: Budget): void;
+export declare function readBudget(path: string): Budget;
+/**
+ * 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.
+ */
+export declare function check(costs: CircuitCost[], budget: Budget, strict: boolean): CheckResult;

package/dist/budget.js

@@ -0,0 +1,77 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { ProfilerError } from "./errors.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 };
+    }
+    return { toolchain: toolchainLine, circuits };
+}
+export function writeBudget(path, budget) {
+    writeFileSync(path, `${JSON.stringify(budget, null, 2)}\n`, "utf8");
+}
+export function readBudget(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new ProfilerError(`No budget file at ${path}`, "Create one from the current measurements with `nite-zk save <source>`.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    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}}}.');
+    }
+    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".');
+        }
+    }
+    return budget;
+}
+/**
+ * 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.
+ */
+export function check(costs, 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)
+                failed = true;
+            continue;
+        }
+        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 });
+        }
+    }
+    return { rows, failed };
+}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+interface Options {
+    command?: string;
+    source?: string;
+    json: boolean;
+    strict: boolean;
+    out?: string;
+    budget: string;
+    versionArg?: string;
+    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 {};

package/dist/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { analyze } from "./analyze.js";
+import { DEFAULT_BUDGET_PATH, budgetFrom, check, readBudget, writeBudget, } from "./budget.js";
+import { compileSkipZk } from "./compile.js";
+import { ProfilerError } from "./errors.js";
+import { measure } from "./measure.js";
+import { checkJson, formatCheck, formatProfile, profileJson } from "./report.js";
+import { SUPPORTED_RANGES, resolveToolchain } from "./toolchain.js";
+const USAGE = `nite-zk - see what a Compact circuit costs to prove
+
+Usage:
+  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
+
+Options:
+  --json                       Machine readable output
+  --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
+  +VERSION                     Pin the Compact toolchain, e.g. +0.31.1
+  -h, --help                   Show this message
+  -v, --version                Show the tool version
+
+Supported Compact toolchains: ${SUPPORTED_RANGES.join(", ")}
+`;
+export function parseArgs(argv) {
+    const opts = {
+        json: false,
+        strict: false,
+        budget: DEFAULT_BUDGET_PATH,
+        help: false,
+        version: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--json")
+            opts.json = true;
+        else if (arg === "--strict")
+            opts.strict = true;
+        else if (arg === "-h" || arg === "--help")
+            opts.help = true;
+        else if (arg === "-v" || arg === "--version")
+            opts.version = true;
+        else if (arg === "--out")
+            opts.out = argv[++i];
+        else if (arg === "--budget")
+            opts.budget = argv[++i] ?? DEFAULT_BUDGET_PATH;
+        else if (arg.startsWith("+"))
+            opts.versionArg = arg;
+        else if (!opts.command)
+            opts.command = arg;
+        else if (!opts.source)
+            opts.source = arg;
+    }
+    return opts;
+}
+/** Compile and measure. Shared by all three commands. */
+function profileSource(source, opts) {
+    // Monotonic, so a wall clock adjustment mid run cannot produce a negative
+    // or wildly wrong duration.
+    const started = performance.now();
+    const toolchain = resolveToolchain(opts.versionArg);
+    const compiled = compileSkipZk(source, toolchain, opts.out);
+    try {
+        const costs = analyze(measure(compiled.zkirDir, toolchain, source));
+        return { costs, toolchain, elapsedMs: performance.now() - started };
+    }
+    finally {
+        compiled.cleanup();
+    }
+}
+export function run(argv) {
+    const opts = parseArgs(argv);
+    if (opts.help || !opts.command) {
+        process.stdout.write(USAGE);
+        return opts.command ? 0 : 1;
+    }
+    if (opts.version) {
+        process.stdout.write("nite-zk-profiler 0.1.0\n");
+        return 0;
+    }
+    if (!["profile", "save", "check"].includes(opts.command)) {
+        process.stderr.write(`Unknown command: ${opts.command}\n\n${USAGE}`);
+        return 1;
+    }
+    if (!opts.source) {
+        process.stderr.write(`${opts.command} needs a source file\n\n${USAGE}`);
+        return 1;
+    }
+    const { costs, toolchain, elapsedMs } = profileSource(opts.source, opts);
+    if (opts.command === "profile") {
+        process.stdout.write(opts.json
+            ? `${profileJson(costs, toolchain)}\n`
+            : formatProfile(costs, toolchain, elapsedMs));
+        return 0;
+    }
+    if (opts.command === "save") {
+        // Record the supported line rather than the exact patch version, so a
+        // routine toolchain bump inside 0.31.x does not invalidate the budget.
+        const budget = budgetFrom(costs, `${toolchain.version.split(".").slice(0, 2).join(".")}.x`);
+        writeBudget(opts.budget, budget);
+        process.stdout.write(`Wrote ${opts.budget} with ${costs.length} circuit${costs.length === 1 ? "" : "s"}\n`);
+        return 0;
+    }
+    const result = check(costs, readBudget(opts.budget), opts.strict);
+    process.stdout.write(opts.json ? `${checkJson(result)}\n` : formatCheck(result));
+    return result.failed ? 1 : 0;
+}
+export function main(argv) {
+    try {
+        return run(argv);
+    }
+    catch (e) {
+        if (e instanceof ProfilerError) {
+            process.stderr.write(`\nerror: ${e.message}\n`);
+            if (e.details)
+                process.stderr.write(`\n${e.details}\n`);
+            process.stderr.write("\n");
+            return 1;
+        }
+        throw e;
+    }
+}
+// Only self-execute as a CLI, so the module stays importable from tests.
+const invokedDirectly = process.argv[1] !== undefined &&
+    /(?:^|[\\/])(?:cli\.(?:ts|js)|nite-zk)$/.test(process.argv[1]);
+if (invokedDirectly) {
+    process.exit(main(process.argv.slice(2)));
+}

package/dist/compile.d.ts

@@ -0,0 +1,16 @@
+import type { Toolchain } from "./toolchain.ts";
+export interface CompileResult {
+    /** Directory the compiler wrote into. */
+    outDir: string;
+    /** Directory holding `<circuit>.zkir`, whether or not it exists. */
+    zkirDir: string;
+    /** Remove the output directory, when this tool created a temporary one. */
+    cleanup: () => void;
+}
+/**
+ * Compile without proving keys.
+ *
+ * `--skip-zk` is what makes profiling fast enough to sit in an edit loop: it
+ * emits the IR and skips key generation, which is the slow part.
+ */
+export declare function compileSkipZk(source: string, toolchain: Toolchain, outDir?: string): CompileResult;

package/dist/compile.js

@@ -0,0 +1,38 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { ProfilerError } from "./errors.js";
+/**
+ * Compile without proving keys.
+ *
+ * `--skip-zk` is what makes profiling fast enough to sit in an edit loop: it
+ * emits the IR and skips key generation, which is the slow part.
+ */
+export function compileSkipZk(source, toolchain, outDir) {
+    const temporary = outDir === undefined;
+    const target = temporary
+        ? mkdtempSync(join(tmpdir(), "nite-zk-"))
+        : resolve(outDir);
+    const args = ["compile"];
+    if (toolchain.versionArg)
+        args.push(toolchain.versionArg);
+    args.push("--skip-zk", resolve(source), target);
+    const res = spawnSync("compact", args, { encoding: "utf8" });
+    const cleanup = () => {
+        if (temporary)
+            rmSync(target, { recursive: true, force: true });
+    };
+    if (res.error) {
+        cleanup();
+        throw new ProfilerError("Could not run `compact compile`", String(res.error));
+    }
+    if (res.status !== 0) {
+        // The compiler's own diagnostics are better than anything worth inventing
+        // here, so they are passed through unchanged.
+        const diagnostics = `${res.stdout ?? ""}${res.stderr ?? ""}`.trim();
+        cleanup();
+        throw new ProfilerError(`Compilation failed for ${source}`, diagnostics || `compact exited with status ${res.status}`);
+    }
+    return { outDir: target, zkirDir: join(target, "zkir"), cleanup };
+}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Errors that represent a clear, actionable problem for the user.
+ * The CLI prints these without a stack trace; anything else is a real crash.
+ */
+export declare class ProfilerError extends Error {
+    readonly details?: string;
+    constructor(message: string, details?: string);
+}
+/** The contract compiled fine but contains nothing that needs a proof. */
+export declare class NoProvableCircuitsError extends ProfilerError {
+    constructor(source: string);
+}

package/dist/errors.js

@@ -0,0 +1,20 @@
+/**
+ * Errors that represent a clear, actionable problem for the user.
+ * The CLI prints these without a stack trace; anything else is a real crash.
+ */
+export class ProfilerError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = "ProfilerError";
+        this.details = details;
+    }
+}
+/** The contract compiled fine but contains nothing that needs a proof. */
+export class NoProvableCircuitsError extends ProfilerError {
+    constructor(source) {
+        super(`No provable circuits in ${source}`, "The contract compiled, but emitted no ZKIR. Circuits that touch neither\n" +
+            "ledger state nor a witness need no proof, so there is nothing to measure.");
+        this.name = "NoProvableCircuitsError";
+    }
+}

package/dist/measure.d.ts

@@ -0,0 +1,23 @@
+import type { Toolchain } from "./toolchain.ts";
+export interface Measurement {
+    circuit: string;
+    /** Constraint rows, as reported by zkir. */
+    rows: number;
+    /** Proving domain exponent, as reported by zkir. Never computed here. */
+    k: number;
+}
+/**
+ * Parse a `zkir mock-compile-many` report.
+ *
+ * Exported for testing, because the failure this guards against is a partial
+ * report that reads as a successful one.
+ */
+export declare function parseReport(text: string): Measurement[];
+/**
+ * Measure every circuit in one `zkir` invocation.
+ *
+ * `mock-compile-many` is used rather than per file `mock-compile` because the
+ * single file form reports the file path instead of the circuit name, which
+ * would leave circuit names to be recovered from filenames.
+ */
+export declare function measure(zkirDir: string, toolchain: Toolchain, source: string): Measurement[];

package/dist/measure.js

@@ -0,0 +1,67 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { NoProvableCircuitsError, ProfilerError } from "./errors.js";
+/** `  circuit "name" (k=9, rows=305)` */
+const CIRCUIT_LINE = /^\s*circuit\s+"([^"]+)"\s+\(k=(\d+),\s*rows=(\d+)\)\s*$/;
+/** `Mock compiling 2 circuits:` */
+const HEADER_LINE = /^Mock compiling (\d+) circuits?:/m;
+/**
+ * Parse a `zkir mock-compile-many` report.
+ *
+ * Exported for testing, because the failure this guards against is a partial
+ * report that reads as a successful one.
+ */
+export function parseReport(text) {
+    const measurements = [];
+    for (const line of text.split("\n")) {
+        const match = line.match(CIRCUIT_LINE);
+        if (match) {
+            measurements.push({
+                circuit: match[1],
+                k: Number(match[2]),
+                rows: Number(match[3]),
+            });
+        }
+    }
+    const header = text.match(HEADER_LINE);
+    if (!header) {
+        throw new ProfilerError("Could not parse the zkir report", `Expected a "Mock compiling N circuits:" header. Got:\n${text.trim() || "(no output)"}`);
+    }
+    // A truncated run prints the header and some circuits before dying, so the
+    // declared count is checked against what was actually parsed.
+    const declared = Number(header[1]);
+    if (declared !== measurements.length) {
+        throw new ProfilerError("Truncated zkir report", `zkir said it was compiling ${declared} circuits but only ${measurements.length} were reported.\n` +
+            "This usually means the run failed partway through. Refusing to report partial results.");
+    }
+    return measurements;
+}
+/**
+ * Measure every circuit in one `zkir` invocation.
+ *
+ * `mock-compile-many` is used rather than per file `mock-compile` because the
+ * single file form reports the file path instead of the circuit name, which
+ * would leave circuit names to be recovered from filenames.
+ */
+export function measure(zkirDir, toolchain, source) {
+    if (!existsSync(zkirDir)) {
+        throw new NoProvableCircuitsError(source);
+    }
+    const res = spawnSync(toolchain.zkirPath, ["mock-compile-many", zkirDir], {
+        encoding: "utf8",
+    });
+    if (res.error) {
+        throw new ProfilerError(`Could not run ${toolchain.zkirPath}`, String(res.error));
+    }
+    // zkir writes its report to stderr. Reading stdout yields an empty string and
+    // a report of zero circuits, which is a silent wrong answer rather than a crash.
+    const output = `${res.stderr ?? ""}${res.stdout ?? ""}`;
+    if (res.status !== 0) {
+        throw new ProfilerError("zkir mock-compile-many failed", output.trim() || `zkir exited with status ${res.status}`);
+    }
+    const measurements = parseReport(output);
+    if (measurements.length === 0) {
+        throw new NoProvableCircuitsError(source);
+    }
+    return measurements.sort((a, b) => a.circuit.localeCompare(b.circuit));
+}

package/dist/report.d.ts

@@ -0,0 +1,9 @@
+import type { CircuitCost } from "./analyze.ts";
+import type { CheckResult } from "./budget.ts";
+import type { Toolchain } from "./toolchain.ts";
+/** Human readable per circuit cost table. */
+export declare function formatProfile(costs: CircuitCost[], toolchain: Toolchain, elapsedMs: number): string;
+/** Human readable budget comparison. */
+export declare function formatCheck(result: CheckResult): string;
+export declare function profileJson(costs: CircuitCost[], toolchain: Toolchain): string;
+export declare function checkJson(result: CheckResult): string;

package/dist/report.js

@@ -0,0 +1,74 @@
+function pad(text, width) {
+    return text.padEnd(width);
+}
+function padLeft(text, width) {
+    return text.padStart(width);
+}
+function costLabel(relative) {
+    return `${relative}x`;
+}
+/** Human readable per circuit cost table. */
+export function formatProfile(costs, toolchain, elapsedMs) {
+    const nameWidth = Math.max(7, ...costs.map((c) => c.circuit.length));
+    const rowsWidth = Math.max(4, ...costs.map((c) => String(c.rows).length));
+    const capWidth = Math.max(8, ...costs.map((c) => String(c.capacity).length));
+    const costWidth = Math.max(4, ...costs.map((c) => costLabel(c.relativeCost).length));
+    const lines = [""];
+    lines.push(`  ${pad("circuit", nameWidth)}  ${padLeft("rows", rowsWidth)}  ${padLeft("k", 3)}  ` +
+        `${padLeft("capacity", capWidth)}  ${padLeft("cost", costWidth)}`);
+    for (const c of costs) {
+        lines.push(`  ${pad(c.circuit, nameWidth)}  ${padLeft(String(c.rows), rowsWidth)}  ` +
+            `${padLeft(String(c.k), 3)}  ${padLeft(String(c.capacity), capWidth)}  ` +
+            `${padLeft(costLabel(c.relativeCost), costWidth)}`);
+    }
+    const plural = costs.length === 1 ? "circuit" : "circuits";
+    lines.push("");
+    lines.push(`  ${costs.length} ${plural}, toolchain ${toolchain.version}, ` +
+        `${toolchain.zkirVersion}, ${(elapsedMs / 1000).toFixed(1)}s`);
+    lines.push("");
+    return lines.join("\n");
+}
+const STATUS_NOTE = {
+    under: (r) => `under by ${(r.maxK ?? 0) - (r.k ?? 0)}`,
+    at: () => "at budget",
+    over: (r) => {
+        const by = (r.k ?? 0) - (r.maxK ?? 0);
+        return `over by ${by}, about ${2 ** by}x`;
+    },
+    undeclared: () => "not in budget",
+    stale: () => "no longer in contract",
+};
+/** Human readable budget comparison. */
+export function formatCheck(result) {
+    const nameWidth = Math.max(7, ...result.rows.map((r) => r.circuit.length));
+    const lines = [""];
+    for (const row of result.rows) {
+        const k = row.k === undefined ? "  -" : padLeft(String(row.k), 3);
+        const maxK = row.maxK === undefined ? "  -" : padLeft(String(row.maxK), 3);
+        lines.push(`  ${pad(row.circuit, nameWidth)}  k ${k}   budget ${maxK}   ${STATUS_NOTE[row.status](row)}`);
+    }
+    const over = result.rows.filter((r) => r.status === "over").length;
+    const undeclared = result.rows.filter((r) => r.status === "undeclared").length;
+    lines.push("");
+    if (over > 0) {
+        lines.push(`  FAIL: ${over} circuit${over === 1 ? "" : "s"} over budget`);
+    }
+    else if (result.failed) {
+        lines.push(`  FAIL: ${undeclared} circuit${undeclared === 1 ? "" : "s"} not declared in the budget (--strict)`);
+    }
+    else {
+        lines.push("  OK: every circuit within budget");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function profileJson(costs, toolchain) {
+    return JSON.stringify({
+        toolchain: toolchain.version,
+        zkir: toolchain.zkirVersion,
+        circuits: costs,
+    }, null, 2);
+}
+export function checkJson(result) {
+    return JSON.stringify(result, null, 2);
+}

package/dist/toolchain.d.ts

@@ -0,0 +1,24 @@
+/** Toolchain lines this tool has been verified against. */
+export declare const SUPPORTED_RANGES: string[];
+export interface Toolchain {
+    /** Compiler version, as reported by the compiler itself. */
+    version: string;
+    /** Absolute path to the `zkir` paired with that compiler. */
+    zkirPath: string;
+    /** Version string reported by that `zkir` binary. */
+    zkirVersion: string;
+    /** `+VERSION` selector to pass through to `compact`, when one was requested. */
+    versionArg?: string;
+}
+/** Whether a compiler version is one this tool has been verified against. */
+export declare function isSupported(version: string): boolean;
+/** Root holding `versions/`, overridable exactly as the `compact` CLI does. */
+export declare function artifactRoot(): string;
+/**
+ * Resolve the compiler and the `zkir` that ships beside it.
+ *
+ * `zkir` is never taken from PATH and never borrowed from a neighbouring
+ * version. If the paired binary is missing that is an error, because a report
+ * built from a mismatched IR reader is wrong rather than merely incomplete.
+ */
+export declare function resolveToolchain(versionArg?: string): Toolchain;

package/dist/toolchain.js

@@ -0,0 +1,101 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ProfilerError } from "./errors.js";
+/** Toolchain lines this tool has been verified against. */
+export const SUPPORTED_RANGES = ["0.31.x"];
+/**
+ * The IR major version emitted by supported compilers. The toolchain ships a
+ * `zkir` (IR 2.0) and a `zkir-v3` (IR 3.0) side by side with identical CLIs and
+ * incompatible formats, so the major version is checked rather than assumed.
+ */
+const EXPECTED_ZKIR_MAJOR = 2;
+/** Whether a compiler version is one this tool has been verified against. */
+export function isSupported(version) {
+    return /^0\.31\./.test(version);
+}
+/** Root holding `versions/`, overridable exactly as the `compact` CLI does. */
+export function artifactRoot() {
+    return process.env.COMPACT_DIRECTORY || join(homedir(), ".compact");
+}
+/**
+ * Ask the compiler which version it is. This honours `+VERSION` and any
+ * configured default, so the answer describes the compiler that will actually
+ * run rather than whatever happens to be installed.
+ */
+function detectCompilerVersion(versionArg) {
+    const args = ["compile"];
+    if (versionArg)
+        args.push(versionArg);
+    args.push("--version");
+    const res = spawnSync("compact", args, { encoding: "utf8" });
+    if (res.error) {
+        throw new ProfilerError("Could not run `compact`", "The Compact CLI was not found on your PATH.\n" +
+            "Install it, or see https://docs.midnight.network for setup.");
+    }
+    const out = `${res.stdout ?? ""}${res.stderr ?? ""}`.trim();
+    const match = out.match(/^\s*(\d+\.\d+\.\d+)\s*$/m);
+    if (!match) {
+        const hint = versionArg
+            ? `Is ${versionArg.slice(1)} installed? Check with \`compact list\`, ` +
+                `and install it with \`compact update ${versionArg.slice(1)}\`.`
+            : "No default compiler appears to be set. Set one with `compact update`.";
+        throw new ProfilerError("Could not determine the Compact compiler version", `${hint}\n\n\`compact compile ${versionArg ?? ""} --version\` returned:\n${out || "(no output)"}`);
+    }
+    return match[1];
+}
+/** Find the per-target directory inside a version that actually holds `zkir`. */
+function findTargetDir(versionDir) {
+    let entries;
+    try {
+        entries = readdirSync(versionDir);
+    }
+    catch {
+        throw new ProfilerError(`Toolchain directory not found: ${versionDir}`, "The compiler reported a version with no matching install directory.");
+    }
+    const hit = entries.find((e) => existsSync(join(versionDir, e, "zkir")));
+    if (!hit) {
+        throw new ProfilerError(`No \`zkir\` binary found under ${versionDir}`, "This toolchain version is installed but incomplete. Reinstall it with\n" +
+            "`compact update`, and note that a separately installed zkir is never used.");
+    }
+    return join(versionDir, hit);
+}
+/** Confirm the binary is the one we think it is, and that it reads IR 2.0. */
+function checkZkir(zkirPath) {
+    const res = spawnSync(zkirPath, ["--version"], { encoding: "utf8" });
+    if (res.status !== 0) {
+        throw new ProfilerError(`Could not run ${zkirPath}`, (res.stderr ?? "").trim() || "The binary exists but did not execute.");
+    }
+    const reported = `${res.stdout ?? ""}${res.stderr ?? ""}`.trim();
+    const match = reported.match(/midnight-zkir\s+(\d+)\.(\d+)\.\S+/);
+    if (!match) {
+        throw new ProfilerError(`Unrecognised zkir version string: ${reported}`, "Expected something like `midnight-zkir 2.1.0`.");
+    }
+    const major = Number(match[1]);
+    if (major !== EXPECTED_ZKIR_MAJOR) {
+        throw new ProfilerError(`Wrong zkir IR version: found ${reported}`, `Supported compilers emit IR ${EXPECTED_ZKIR_MAJOR}.0, but this binary reads IR ${major}.0.\n` +
+            "Mixing them produces a partial report that looks successful. Refusing to continue.");
+    }
+    return reported;
+}
+/**
+ * Resolve the compiler and the `zkir` that ships beside it.
+ *
+ * `zkir` is never taken from PATH and never borrowed from a neighbouring
+ * version. If the paired binary is missing that is an error, because a report
+ * built from a mismatched IR reader is wrong rather than merely incomplete.
+ */
+export function resolveToolchain(versionArg) {
+    const version = detectCompilerVersion(versionArg);
+    if (!isSupported(version)) {
+        throw new ProfilerError(`Unsupported Compact toolchain: ${version}`, `This tool supports ${SUPPORTED_RANGES.join(", ")}.\n` +
+            "Toolchain lines change zkir internals, so rather than report a number it\n" +
+            "cannot stand behind, it stops here.\n" +
+            `Pin a supported compiler with: nite-zk profile +0.31.1 <source>`);
+    }
+    const versionDir = join(artifactRoot(), "versions", version);
+    const zkirPath = join(findTargetDir(versionDir), "zkir");
+    const zkirVersion = checkZkir(zkirPath);
+    return { version, zkirPath, zkirVersion, versionArg };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nite-framework/nite-zk-profiler",
+  "version": "0.1.3",
+  "description": "See what a Compact circuit costs to prove, without generating proving keys",
+  "type": "module",
+  "bin": {
+    "nite-zk": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "npm@11.10.1",
+  "keywords": [
+    "midnight",
+    "compact",
+    "zk",
+    "zero-knowledge",
+    "profiler",
+    "proving-cost",
+    "nite-zk-profiler"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nite-framework/nite-zk-profiler.git"
+  },
+  "homepage": "https://github.com/nite-framework/nite-zk-profiler#readme",
+  "bugs": {
+    "url": "https://github.com/nite-framework/nite-zk-profiler/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "postbuild": "node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^5.9.3"
+  }
+}