pi-supernova 0.3.2 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-supernova
 
-**One nova / `supernova({code})` invocation. Four commands inside CodeMode.**
+**One `supernova` invocation. Inline code, a workspace program, or an explicit program batch. Four commands inside CodeMode.**
 
 ```javascript
 const source = await read("validateRefreshToken");
@@ -48,12 +48,15 @@ settings. The runtime does not silently rewrite your tool policy.
 | Function | Examples and behavior |
 | --- | --- |
 | `read` | `read(path, offset?, limit?)`, `read({path,offset,limit})`; one-based line windows |
-| `read` | `read(directory)`, `read("symbol or question")`, `read(path,{about:question})`; questions locate and open source directly |
-| `read` | `read({query,resolve:true})`; structured source and status for a resolve-to-edit handoff |
+| `read` | `return await read("plot.png")`; displays images directly, without a browser |
+| `read` | `read({path,json:".verdict"})`; parse full JSON before bounded field selection |
+| `read` | `read(directory)`, `read("symbol or question")`, `read(path,{about:question})`; a path is raw text, a symbol is a view |
+| `read` | `read({query,resolve:true})`; same view as `read("symbol")`: status, path, line, lines, text, complete |
 | `read` | `read({query,evidence:true})`; ranked evidence with provenance; optional `path` scopes discovery |
 | `read` | `read({path,outline:true})`; structural declarations |
 | `read` | `read([path1,path2])`; up to 64 paths, ordered values with labelled individual failures |
-| `edit` | `edit(path,oldText,newText)`, `edit({path,edits:[{oldText,newText}]})`; related edits validated against one original file |
+| `edit` | `edit(path,oldText,newText)`, `edit({path,edits:[{oldText,newText}]})`; unique in the file |
+| `edit` | `edit(view,text)` CAS-replaces that span; `edit(view,old,new)` is unique inside it |
 | `edit` | `edit({path,patch})`; unified patch application |
 | `edit` | `edit(async () => {...})`; filesystem-only checkpoint, described below |
 | `write` | `write(path,text)`, `write({path,content})`; atomic replacement |
@@ -68,27 +71,26 @@ payloads are not repeated in owned direct-execution errors;
 stdout/stderr, exit status and source context remain. Session environment variables are taken
 from the current execution context, not inherited from a different parent session.
 
-Source questions resolve and open the selected file in one command. An exact
+Source questions locate a declaration in one command. An exact
 declaration match uses one bounded direct ripgrep search, without a prerequisite
 file listing, persistent index, embeddings or summarization. A transient filename
 listing is a fallback for unmatched content or unresolved bare filenames. Natural-language
 questions reuse lexical stemming. Ripgrep must be available on PATH.
 
-Successful question reads return raw source with a path/range header, not the old
-JSON location preview. Use the structured form when code needs the path:
+`read(path)` stays raw text. `read("symbol")` is the same view as
+`read({query, resolve:true})` — not the file, not a path/range header:
 
 ```javascript
-const source = await read({query: "validateRefreshToken", resolve: true});
-if (source.status !== "found") return source;
-return await edit(source.path, "token.length > 3", "token.length > 5");
+const v = await read("validateRefreshToken");
+if (v.status !== "found") return v;
+await edit(v, v.text.replace("token.length > 3", "token.length > 5"));
 ```
 
-The structured result contains `status`, `path`, the matching `line`, delivered
-`lines`, unchanged `text`, `complete`, and `nextOffset` when more source follows.
-Files that fit the output budget are returned in full. Oversized files open near
-the matching line and give a continuation; they are not summarized. Uncertain
+The view contains `status`, `path`, the matching `line`, span `lines`, unchanged
+`text`, `complete`, and `nextOffset` when a budget clip continues. A declaration
+snap is that span (`complete` is false unless the span is the whole file). Uncertain
 results report `ambiguous`, `not_found` or `incomplete` with no selected path.
-Use `{path: directory, about: question, resolve: true}` to narrow the scope.
+Use `{path: directory, about: question}` to narrow the scope.
 
 Ordinary reads stay self-contained. Outlines and graph evidence remain explicit
 options, not mandatory stages of source resolution. Ordinary calls also get:
@@ -122,16 +124,33 @@ full dataflow tracking or a security sandbox.
 
 Explicit read arrays reject missing/failed paths. For typed partial outcomes use
 `Promise.allSettled(paths.map(path => read(path)))`. Successful arrays remain arrays.
-For embedded source with backslash escapes, use `String.raw` template literals
-(and escape delimiter backticks), or JSON-quoted strings. Validate generated code.
+For literal file content or scripts, prefer the optional tool-level `data` parameter:
+
+```json
+{
+  "code": "await write(data.path,data.content); return await bash({command:\"python3\",args:[data.path]});",
+  "data": {
+    "path": "probe.py",
+    "content": "print(\"literal `backticks` and ${braces}\")\n"
+  }
+}
+```
+
+`data` crosses the worker boundary as JSON, never as JavaScript source. Its
+JSON-encoded length is capped separately at `maxCodeChars`; split larger inputs.
+The binding exists only when supplied, so older programs declaring their own `data`
+remain valid. Syntax errors run no commands and give quoting guidance. For inline
+source, use `String.raw` (escaping backtick delimiters) or JSON-quoted strings.
 
 On hosts exposing `sessionManager.getArtifactsDir()`, bare `agent://<id>` and
 `artifact://<number>` read files from the calling session's artifact directory.
 They preserve ID casing and support offset/limit and structured continuation.
 These resources are read-only; ambiguous artifact IDs and escaping symlinks fail.
-This is not the full OMP URI language: cross-session search, nested path/query
-selectors and other schemes are not implemented. Hosts without an artifact
-directory report that limitation rather than treating the URI as a local path.
+A single `?q=.answer` (URL-encoded when needed) selects JSON from either resource
+using the same bounded projection as `read({path,json})`. The resource must contain
+valid JSON; ordinary Markdown is not parsed heuristically. This is not the full
+OMP URI language: full jq, cross-session search and other schemes are not implemented.
+Hosts without an artifact directory report that limitation rather than treating the URI as a local path.
 
 For unstructured logs/text, `read(path,{about:"STT database"})` returns bounded,
 line-numbered matching windows, or explicitly reports no matching text. It is not
@@ -139,6 +158,67 @@ a complete-file read. Write temporary investigation files under the workspace
 (e.g. `.work/probe.py`): ordinary `write`/`edit` paths cannot escape it, including
 absolute `/tmp` paths. Shell execution is a separate trusted boundary, not a sandbox.
 
+### Reuse a program without resending its source
+
+Save a trusted JavaScript async body or arrow in the workspace, then invoke it:
+
+```json
+{"file":".work/audit.js","data":{"paths":["src/a.js","src/b.js"],"term":"TODO"}}
+```
+
+Supply exactly one of `code` or `file`. File programs get the same four commands,
+optional `data`, limits, deadlines and transaction semantics. Each invocation
+rereads the file and starts a fresh guest; there is no implicit last-program
+state, auto-replay, or retained heap. Paths inside the program still resolve from
+the calling workspace, not the script directory. This runs a Nova program, not
+an arbitrary JavaScript module or a Python/shell script.
+
+Program files must be regular UTF-8 files inside the workspace, including symlink
+targets. Invalid encoding, oversized input and syntax errors fail before commands;
+no truncated prefix is executed. Review untrusted source before running it.
+Use ordinary `edit` to revise saved programs. This is explicit source reuse, not
+conversation compression: prior calls and read results remain intact. Creation
+costs an additional call unless combined with other work, so prefer inline code
+for short one-off operations. See [token measurements](docs/TOKEN_COSTS.md).
+
+### Batch already-known continuations
+
+~~~json
+{
+  "programs": [
+    {"code": "return await edit(data.path,data.oldText,data.newText);", "data": {"path":"src/config.js","oldText":"limit = 8","newText":"limit = 16"}},
+    {"code": "return await bash(\"npm test\");"},
+    {"file": ".work/audit.js", "data": {"paths":["src/config.js"],"term":"limit"}}
+  ],
+  "timeoutMs": 60000
+}
+~~~
+
+Use programs instead of top-level code/file/data. Supply 1--32 entries, each with
+code OR file and optional data; the JSON-encoded array must fit maxCodeChars.
+Entries run sequentially in fresh guests and commit separately. A successful
+entry can create the file executed by a later entry. No implicit retries,
+reordering, shared heap or nested batches are introduced.
+
+The batch stops on the first failed entry, cancellation/deadline, or exhausted
+output/log/image budget. Earlier successful commits remain; only the active
+program's uncommitted writes roll back. Admission errors throw before any program.
+Execution failures return a **typed stop report**, rather than throwing away prior
+results/images: isError and details.ok identify failure, details.programs contains
+every attempted result, and details.attempted/total identifies unstarted work.
+Single code/file invocations retain their existing throwing behavior.
+
+The outer deadline, host-call budget, log allowance, text budget and image limits
+are shared across the batch. Individual read budgets are not reduced. Every
+attempted program's original text is returned in length-delimited blocks; ordinary
+limits still disclose clipping. Images retain program/image labels. Split a plan
+that would exceed the aggregate output budget.
+
+Batch only continuations already chosen by the agent, such as edit then known
+verification, or create then run known audits. Keep a separate call whenever new
+source/results are needed to decide the next action. This does not lower reasoning
+settings, hide observations, or infer a plan on the agent's behalf.
+
 ### Large inputs and report outputs
 
 The default program limit is 48,000 UTF-16 code units (configurable via
@@ -159,17 +239,38 @@ output delivery; progress files survive shell execution but staged VFS writes ma
 roll back.
 
 Large returned objects are bounded previews, not retained artifacts. Select fields
-and array windows before returning, rather than parsing a truncated preview:
+and array windows before returning, rather than parsing a truncated preview.
+
+## JSON reports and targeted text audits
+
+For JSON, select fields inside the read adapter, **before** output budgeting:
 
 ```js
-const report = JSON.parse(await read({path:"report.json",complete:true}));
-return {verdict:report.verdict, values:report.values.slice(5000,5003)};
+const [verdict, values] = await read({path:"report.json",json:[".verdict",".values[5000:5003]"]});
+return {verdict, values};
 ```
 
-If the raw JSON exceeds the read budget, reconstruct exact source windows or run
-a bounded parser through `bash`. There is no implicit continuation handle for
-arbitrary guest objects. For embedded code, JSON-encode the source string once;
-do not nest shell, JavaScript, and Python quoting unless it is necessary.
+Selectors support "." (root), .field, .nested[0], .items[0:10], and .["quoted.key"].
+Use json:true for the complete parsed value. Selectors are not full jq: pipes,
+filters, wildcards and negative indices fail explicitly. Missing keys and indices
+fail; false, zero and null remain values. Slices use an exclusive end and clamp to
+array length. Only own JSON properties are traversed; nothing is evaluated.
+
+Inputs are capped at 16 MiB, including staged files. JSON reads require regular
+files and reject named pipes without waiting for a writer. The entire input must
+be valid JSON before any selection. Each selector is budgeted before allocating
+the next slice; sparse selector/path/edit arrays are rejected. Selected JSON must
+fit the ordinary read budget or the
+read throws; it is never returned as malformed/truncated JSON. Oversized unwindowed
+plain .json reads also fail with a projection hint. Explicit offset/limit or
+resolve:true still allow raw inspection, but line windows are not JSON documents.
+Do not combine json with complete, line windows, or source views. External read
+overrides reject JSON projection rather than silently ignoring the option.
+
+For large Markdown/log path audits, use read(path,{about:"document path"}) or
+explicit offset/limit, not complete:true. Larger JSON needs a streaming parser via
+bash. Arbitrary returned objects still have bounded previews, not implicit
+continuation handles.
 
 ## Execution and automatic batching
 
@@ -191,7 +292,12 @@ File changes are staged until program success. A throw before an external-mutati
 barrier rolls them back. Shell execution flushes preceding changes; external shell
 side effects cannot be rolled back. Stale commits fail explicitly rather than
 silently overwriting successful concurrent changes. This is not a cross-process
-filesystem lock.
+filesystem lock. Outcomes explicitly report committed/rolledBack **file versions**
+(counted per flush/checkpoint, not unique paths) and external-call attempts. A
+successful inner checkpoint merges into the program, not necessarily onto disk.
+Pending commits or failed recovery are reported as uncertain: inspect disk and
+recovery backups before retrying. Import-based mutations and shell side effects
+are outside the VFS counters; this is not a filesystem audit.
 
 `edit(async () => {...})` creates a nested filesystem checkpoint. It returns
 `{ok:true,committed:true,value}` on success or `{ok:false,committed:false,error}` on
@@ -212,6 +318,10 @@ outside the active callback are rejected. Await the checkpoint before proceeding
   strings and result types are unchanged. This is output framing, not source
   compression. It is chosen only when shorter in characters than escaped output;
   it does not guarantee lower billed tokens for every tokenizer or input.
+  Nested multiline strings use the same approach: the complete value structure
+  references `raw[n]`, followed by length-delimited verbatim string blocks. Literal
+  `"raw[0]"` values stay quoted; duplicate source is never deduplicated. Small values
+  keep their existing format. Machine-facing result values are unchanged.
 - Intermediate values stay inside CodeMode unless returned or logged. Final text,
   errors and logs are bounded with explicit truncation. Details support rendering;
   they are not a second model-facing transcript.
@@ -220,6 +330,12 @@ outside the active callback are rejected. Await the checkpoint before proceeding
 
 Default limits are in `src/config/config.default.json`. Configuration loads from
 `~/.pi/agent/supernova.json`, the configured host directory, or `PI_SUPERNOVA_CONFIG`.
+
+Citation elision is **disabled by default** (`seenWindow: 0`): each result remains
+self-contained within the normal output budgets. A positive `seenWindow` explicitly
+opts into an experimental ledger with known retention gaps: hidden message details,
+later context transforms and missing citation targets can invalidate its assumptions.
+It is not a proven lossless optimization and is not recommended for production.
 Text limits are character budgets, not tokenizer counts. `/supernova` reports
 programs and output characters without labelling characters as tokens.
 
@@ -259,7 +375,9 @@ privileges. Do not run untrusted programs as though these adapters isolate them.
 Pi preflights the outer `supernova` call. Internal primitives do not emit ordinary
 native `tool_call` events, so third-party guards that only recognize top-level
 `edit` or `bash` need CodeMode-aware handling. Configured exclusions and supported
-host-session execution safeguards remain enforced. Actual-host smoke checks are
+host-session execution safeguards remain enforced. Guards inspecting code/file
+inputs must also understand the programs array; its entries do not emit separate
+top-level tool_call events. Actual-host smoke checks are
 not a claim that every third-party permission extension has been validated.
 
 ## Development and evidence
@@ -284,6 +402,7 @@ arbitrary wall-clock assertions.
 npm test --prefix packages/pi-supernova
 npm run lint:supernova
 npm run measure --prefix packages/pi-supernova
+npm run test:tokens --prefix packages/pi-supernova
 
 PI_SUPERNOVA_PI_ROOT=/path/to/pi-coding-agent \
 PI_SUPERNOVA_OMP=/path/to/omp \

package/docs/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.5.0] - 2026-09-12
+
+- Report overlapping `supernova` calls from every participant in the wave, including the first-started call that finishes last. Start-order or finish-order counters missed that side; a peak concurrent count resets when the wave drains. Sequential calls, `programs` batches, and failed programs still do not leak a split hint. The regression forces the slower first program so the last-finisher case cannot flake under load.
+
+- Shrink the standing tool definition without compressing source or results. Duplicate object-form restatements, schema prose already covered by the command list, and discoverable operational asides are gone; signatures and safety rules stay in the always-sent reference. Frozen six-call traffic is 14,970 / 14,787 tokens (o200k / cl100k): 19.23% / 19.24% below d444eb7. The current-pass gate now requires 19% vs d444eb7.
+
+- An unmatched or non-unique edit keeps the file and returns a numbered window of the actual source (16-line cap, same coordinates as a successful edit) so the next program can copy oldText without a blind re-read. Successful read/write/edit results are unchanged.
+
+- A program that writes or edits and returns nothing still delivers those mutation receipts (numbered post-edit lines, `wrote` paths). Reads without a return stay a no-return hint and do not dump file contents. Explicit `return await edit(...)` is not duplicated.
+
+- `edit(view, text)` replaces a `resolve:true` window by line span with CAS against the viewed bytes. Duplicate substrings no longer block a ranged edit; a stale view fails and rolls back. The silent receipt names that span (`edited path:2-2`), not a ±2 context window.
+
+- A `resolve:true` snap of a declaration is that declaration's span, not the whole file just because the file fits the read budget. `edit(view, text)` then replaces the function, not the file. `edit(view, old, new)` is unique inside that span. A budget-clipped view (`nextOffset`) is not editable.
+
+- Gravity: `read("symbol")` is the same view as `read({query, resolve:true})`. `read(path)` stays raw text. `looksLikePath` lives in `shared/decode.js` so guest and host share the identifier-vs-path rule.
+
+- Nested declaration spans: a parent still includes its body (brace-matched from the opening line), one-line class methods resolve, and two exact same-name declarations in one file are ambiguous instead of snapping the first. Ambiguous candidates (same-file or cross-file) are that hit's span (signature, lines, text, context), not a clone of the first match's window. Span pick/slice live in `src/context/spans.js` for locate + host resolve.
+
+- Do not subscribe a `context` observer when `seenWindow` is 0. A no-op listener still ran on every provider context event; opt-in retention windows still register.
+
+- Encode the module BIND spine as a regression: acyclic imports, no upward edges, context and runtime stay siblings. host-bridge remains the fused INVOKE kernel.
+
+- Drop guest/host RPC for `search` and `describe`, and stop returning unused `exec`/`patch`/`nova` bindings from the worker API. The guest still injects only read, write, edit, bash.
+
+## [0.4.0] - 2026-09-10
+
+- Disable citation elision by default (`seenWindow: 0`), including direct bridge/ledger defaults. A failure-first integration regression preserves complete results across hidden, reordered and removed context. Positive windows remain an explicit research opt-in, not a validated retention guarantee. The historical ledger measurements below describe that experimental mode only.
+
+- Make the traffic gate able to see the retention ledger, and prove it can. The gate previously ran only a host that emits no lifecycle events, so it measured the conservative floor and could not observe the largest token lever in the package. It now also runs the frozen schedule against a production-shaped host that fires `context` before each request, comparing like for like against the unbatched baseline, and gates three things: an unobserved ceiling recorded after this pass, a floor requiring the observing host to beat the same schedule, and an anti-vacuity check requiring the fidelity assertion to have had a subject. Fidelity in that arm is asserted as elision-only rather than byte-equality: every surviving line must match in order and every citation must cover a run of exactly the lines it replaced.
+- Add self-tests for the elision checker itself. A checker that cannot reject anything makes every gate that relies on it vacuous; seven failure-first cases (a vanished line, an overstated or understated citation, a sub-run citation, an invented line, a reordered elision) fail if the checker is weakened or reports that it saw nothing.
+- Fix an information-loss bug the retention proof exposes: a program inside a `programs` batch could cite a peer in the same batch, whose result the model had not received yet. Nothing in a batch is collapsible against its own batch, and a regression now holds that line. The pre-existing frozen output assertion already caught this; it now has a named test.
+- Record the observed-arm ceiling in `token-baseline.json` with provenance. The frozen workload is effectively read-once, so the ledger's saving on it is 0.77%/0.85%; repeat-heavy sessions measure 43.6% and are guarded by `tests/fidelity/ledger-retention.test.mjs`.
+- Experimental only: retain the seen-ledger observation mechanism for research. Its earlier "retention proof" claim was invalid: metadata is not necessarily model-visible, context handlers can transform later, and a missing citation target is not rehydrated. The extension now subscribes to Pi's `context` hook and collapses a run only when those exact lines were observed in the messages about to be sent. The blanket `seenWindow: 0` existed because local cache residency cannot establish model-context residency; the pre-conversion host observation does not establish final-payload residency. Future collapse stops when lines disappear from the observation, but existing citations can still be dangling; a citation is never evidence of its own contents, and citations never nest. Observation costs ~1.7 ms per request on a 0.87 MB payload. On a 12-call repeated-read session: 42.8% fewer published result characters and 31.0% less cumulative replay. Changed lines are still never collapsed, explicit offset/limit reads stay pinned, and a host that never fires `context` publishes byte-identical results, so the frozen `events` and the batched arm of the gate are untouched; only a new observed-arm ceiling was added to the baseline.
+- Consolidate overlapping tests into multi-operation failure-and-repair contracts covering JSON, saved programs, checkpoints, literal argv, images and concurrent workspaces. Retain distinct admission, isolation and resource-limit regressions.
+- Fix truncation reporting for complete tool responses, including logs and wrapper metadata; make log-limit omissions visible in model-facing output.
+- Remove duplicate startup guidance and batch wrapper metadata while retaining every original per-program result. The unchanged six-call benchmark uses another 5.15%/5.17% fewer tokens than d444eb7; add a request-hash guard against moving model decision boundaries.
+
+- Add explicit sequential `programs` batches with fresh guests and separate commits. Preserve complete per-program text and earlier images in typed stop reports; share deadlines, host calls, logs and outer output/image limits. Reject malformed/nested/oversized plans before execution.
+- Make the additional 40% token gate part of `npm test`, with a frozen post-previous-pass baseline, exact logical-result checks, both tokenizers, full tool-history replay and the final answer handoff. Measured 56.19%/56.26% fewer modeled tool tokens for the fixed workload; retain the full startup reference. No provider billing or model-quality claim.
+
+- Add explicit workspace program-file input as an alternative to inline code, with fresh loading/guests, strict bounded UTF-8 admission and unchanged deadlines/transactions. No implicit replay or persistent heap.
+- Extend verbatim string framing to nested source results, preserving all fields, types, duplicate strings and lengths; retain compact scalar output. Remove redundant guidance already present in parameter/command descriptions.
+- Add reproducible two-tokenizer measurements and package comparisons in `TOKEN_COSTS.md`, including creation/definition overhead and explicit no-claim boundaries for billing and end-to-end quality.
+
+- Stress follow-up: budget each JSON selector before allocating the next slice, reject non-regular JSON inputs without blocking on FIFO open, and reject sparse selector/path/edit arrays. Add a heap-limited host-survival regression, exact input boundaries, concurrent queried-resource isolation, and failed-recovery backup verification. The mixed stress lane now exercises literal input data and JSON projection.
+
+- Add literal tool-level `data` input for Markdown/scripts/argv without nested JavaScript quoting; parse failures explicitly state no commands ran.
+- Parse full JSON before bounded field/index/slice projection with `read({path,json})`, including session `?q=.answer` resources. Reject invalid selectors, missing fields, oversized inputs/selections and incompatible read options. Oversized unwindowed plain JSON reads fail with actionable guidance.
+- Validate edit overloads before dispatch and show supported signatures, without touching a file on invalid input.
+- Report committed/rolledBack file versions and external-call attempts on failure, and distinguish uncertain commit recovery from complete rollback.
+- Advertise direct image viewing and targeted large-text reads in model-facing guidance. Add Spark papercut regressions through the registered tool and real worker.
+
 ## [0.3.2] - 2026-09-07
 
 - Focus `read(path,{about})` on matching line windows in unstructured logs/text instead of returning a truncated unrelated prefix; report no matches explicitly.

package/docs/TOKEN_COSTS.md

@@ -0,0 +1,173 @@
+# Token usage and benchmarks
+
+Supernova reduces repeated tool traffic through explicit program reuse and batching.
+It can also reduce escaping in nested multiline results with lossless text framing.
+These mechanisms do not summarize results, rewrite conversation history, or change
+reasoning settings. Savings depend on the workload.
+
+See the [API guide](../README.md) for program-file and batch usage.
+
+## Reproduce
+
+From a repository checkout with development dependencies installed:
+
+~~~sh
+npm run test:tokens --prefix packages/pi-supernova
+npm test --prefix packages/pi-supernova
+~~~
+
+The benchmark uses js-tiktoken 1.0.21, pinned as a development dependency. It runs
+real Supernova programs in temporary workspaces without provider calls or downloads.
+The token regression gate also runs in the normal test suite.
+
+## Workload
+
+The baseline is a frozen, non-batched implementation snapshot with program-file
+reuse and nested source framing already enabled. It is not a comparison against
+a separately published release.
+
+| Scenario | Baseline calls | Batched calls |
+| --- | ---: | ---: |
+| Inspect source, reproduce a failure, repair and verify | 4 | 3 |
+| Inspect, update and verify a JSON report | 3 | 2 |
+| Create an audit program and run it for five search terms | 6 | 1 |
+| **Total** | **13** | **6** |
+
+Both executions perform the same 13 logical programs. The batch schedule is
+hand-authored: it groups known edit-then-verify and create-then-audit continuations,
+while keeping decision points after inspection and the failing check separate.
+No model chooses the schedule during this test. The runtime does not infer plans
+or contain benchmark-specific paths, search terms, or expected results.
+
+This workload deliberately includes repeated audits that benefit from batching.
+It is a reproducible regression fixture, not a representative sample of all agent
+tasks or a guarantee of savings when a model decides how to use the tool.
+
+## Accounting
+
+For each model request, the benchmark counts:
+
+- The serialized Supernova definition: description, parameters and prompt guidance.
+- All preceding tool arguments and complete result text in the request history.
+- Newly generated tool arguments, serialized as JSON.
+
+It also counts the definition and full tool history sent for the final answer
+request. A newly produced tool result is counted when the next model request
+consumes it, not twice. Program creation is included. The complete startup
+reference is retained, so this workload needs no separate discovery call.
+
+Formally, with definition cost D, generated argument cost A_i, result cost R_i,
+and prior tool-history cost H_i = sum(A_j + R_j) for j < i:
+
+~~~text
+Total = sum(D + A_i + H_i, i = 1..N) + D + H_(N+1)
+~~~
+
+This assumes full tool-history replay. The JSON report includes per-scenario
+breakdowns. Its results field records newly produced text for inspection; that
+text contributes to totals through later history, not as a second charge.
+
+## Measured results
+
+Observed on macOS with Node v26.7.0.
+
+| Tokenizer | Non-batched baseline | Batched baseline (d444eb7) | Current | Further reduction | Total reduction |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| o200k_base | 28,130 | 18,535 | 9,537 | **48.55%** | **66.10%** |
+| cl100k_base | 27,841 | 18,310 | 9,420 | **48.55%** | **66.17%** |
+
+The gate requires at least 40% reduction on **each tokenizer for the complete
+workload**, not for every scenario individually. Token counts and reductions are
+computed from the recorded baseline and fresh execution results, not constants
+returned by the runtime. A second gate requires another 19% against the measured
+batched baseline from commit d444eb7. Its six-call argument hash is pinned as well
+as the original workload: removing a decision boundary cannot satisfy this gate.
+
+### What changed after the batched baseline
+
+The serialized definition falls from 1,068 to 577 tokens with o200k_base and from
+1,057 to 572 with cl100k_base. Duplicate object-form restatements, parameter
+prose already covered by the command list, and discoverable operational asides
+were removed; command signatures and safety rules (`complete:true`, JSON 16 MiB /
+no jq, array-read rejection, transactions, `programs` batch, edit oldText as an
+exact substring, `edit(view,text)`) remain in the standing reference. No source
+text or independent result is removed or compressed.
+
+For the fixed six-call schedule, the accounting can also be written as:
+
+~~~text
+Total = (N+1)*D + sum((N-i+2)*A_i + (N-i+1)*R_i, i = 1..N)
+~~~
+
+Seven definition appearances still save 7*491 = 3,437 tokens with o200k_base versus
+d444eb7's 1,068-token definition. Snap-to-span then changed the first repair
+observation from a whole-file view to the `MAX_JSON_BYTES` declaration
+(`lines:[3,3]`, `complete:false`). That smaller result is replayed through later
+requests; no source or independent result is compressed or dropped. Frozen
+programs, arguments and decision boundaries are unchanged. Combined with
+batching, current o200k traffic is 9,558 vs d444eb7's 18,535 (48.43%).
+
+The current definition is now *below* the non-batched baseline (577 vs 908
+o200k_base). Batching still adds result framing. One-off calls should not be
+assumed to benefit from the batch API.
+
+The report also includes separate source-framing and argument-reuse comparisons.
+Those component measurements are not total-session savings, and the reported
+argument-only break-even excludes other request costs. Text framing is selected
+by character length, not a runtime tokenizer; it need not reduce tokens for every
+input or encoding.
+
+## Benchmark integrity
+
+The [baseline fixture](../tests/efficiency/token-baseline.json) contains the source
+inputs, definition, workload hash, arguments and complete outputs. The
+[runner](../tests/efficiency/workflow.mjs) executes the registered tool with real
+workers and filesystem operations. It checks that:
+
+- The workload hash matches the frozen baseline, and the six-call argument hash
+  matches the prior batched execution.
+- Every original argument, complete logical result and expected failure matches.
+- Batched output contains every original result, with no unaccounted outer text.
+- No result is truncated, and final repaired source and JSON contents match.
+
+Only run IDs, elapsed times and temporary workspace prefixes in write receipts
+are normalized. Batch framing lengths are adjusted to match that normalized text.
+The workload, batch schedule, recorded comparison totals and acceptance thresholds
+are fixed test inputs, not production execution rules. The baseline is not regenerated by the benchmark.
+
+Recorded baseline SHA-256:
+
+~~~text
+79a819eca82c8a5ff381e96b7669d8a5bf04fabbc8c10cf02f3a7c8817171b62
+~~~
+
+## Limitations
+
+- These are local estimates of model tool-token traffic, not provider billing.
+  Provider-specific envelopes, unrelated user/system messages, reasoning tokens,
+  image token costs and cache discounts are excluded.
+- There is no live-model A/B quality evaluation. Preserving observations and
+  reasoning settings does not establish unchanged end-to-end task quality.
+- Batching is appropriate only for already-chosen continuations. Actions requiring
+  a new model decision must remain separate calls.
+- Existing read, output, log, image and execution limits still apply. The
+  benchmark does not obtain savings by lowering them or hiding truncation.
+
+## Design references
+
+These sources informed the implementation choices; the measurements above compare
+Supernova implementations only, not the performance of these packages.
+
+| Reference | Mechanisms studied |
+| --- | --- |
+| [pi-codex-conversion 3.0.31](https://github.com/IgorWarzocha/howaboua-pi-stuff/tree/94eb6c0745e2f516bf19603f912f7b6478b43355) | Code transport, concise signatures and deferred discovery |
+| [pi-codemcp](https://github.com/yolonir/pi-codemcp) | Saved call chains and intermediate results |
+| [Ian Pascoe's pi-codemode](https://github.com/ian-pascoe/pi-extensions/tree/main/packages/pi-codemode) | Notebook state and tool declarations |
+| [Nick Nisi's codemode](https://github.com/nicknisi/pi-extensions/tree/main/packages/codemode) | Named snippets and explicit composition |
+| [Boozedog's pi-codemode 0.3.0](https://github.com/boozedog/pi-codemode/tree/1390c938ef4f23a0d50b814e7e3a14c03a08d39d) | Literal inputs and typed CLI capabilities |
+| [pi-cache-optimizer 2.8.2](https://github.com/jiangge/pi-cache-optimizer) | Cache-prefix and prompt handling |
+
+Unpinned repository links refer to inspected source, not independently verified
+package versions. Supernova retains fresh guests, explicit transaction boundaries
+and its general command surface rather than adopting persistent notebook state,
+restricted CLI catalogs or provider/history rewriting.