pi-supernova 0.5.0 → 0.7.0

package/README.md

@@ -12,6 +12,38 @@ Ordinary JavaScript control flow remains available; the guest command bindings
 are only `read`, `edit`, `write`, and `bash`. Supernova supplies retrieval,
 transactional file operations, batching, bounded results and the grouped nova UI.
 
+## Unreleased
+
+- **`parallel: true` on `programs`:** independent entries run at once (up to 8),
+  keep result order, and do not stop siblings on failure. Sequential is still
+  the default.
+- **JSON `.length`:** `read({path, json:".items.length"})` returns the array
+  length without dumping the array.
+- Prefer `edit` for a file you already read; `write` still replaces the file.
+
+## What is new in 0.7.0
+
+- **Faster batches:** guest workers pipeline their successor, so sequential
+  programs run about twice as fast with no token cost.
+- **Hardened guest:** `process.kill` is sealed out; patch hunks report
+  relocation and ambiguous hunks fail instead of misapplying.
+- **Leaner receipts:** multi-edit output caps at 32 matches with exact totals,
+  write receipts go workspace-relative, evidence/outline reads go compact.
+
+## What is new in 0.6.0
+
+- **Shared batch input:** supply top-level `data` once; each program gets an
+  independent copy unless it supplies its own replacement data.
+- **Conflict protection:** byte snapshots survive partial reads and body-cache
+  eviction; receipt generation cannot silently rebase a pending write.
+- **Read fidelity:** staged declarations remain discoverable in large/new files,
+  line windows preserve source endings, and `complete` always means the whole file.
+- **Explicit failures:** incompatible read modes, budget-limited matches, captured
+  overrides and conflicting new-file aliases no longer silently change outcomes.
+
+See the [changelog](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/CHANGELOG.md)
+and [token measurements](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/TOKEN_COSTS.md).
+
 ## Install and update
 
 Install the published package in your host:
@@ -29,9 +61,19 @@ pi install /path/to/pi-stack/packages/pi-supernova
 
 Git pushes do not update npm installations. Publish the new npm version first;
 then reinstall it in the host. Reinstall explicitly when an existing version
-range excludes the new minor version (for example, `^0.2.0` excludes `0.3.0`).
+range excludes the new minor version (`^0.6.0` excludes `0.7.0`). After 0.7.0 is
+published, pin that release with:
+
+```bash
+pi install npm:pi-supernova@0.7.0
+omp install npm:pi-supernova@0.7.0
+```
 
-Both package manifests use `index.js`. The old `src/bridge/pi-extension.ts` path
+In Pi, `pi list` shows the configured package sources. A local path uses that
+checkout directly; an npm source uses the installed npm copy. Do not assume that
+pushing a checkout or running `/reload` updates the copy executing in your host.
+
+Both host manifests use `index.js`. The old `src/bridge/pi-extension.ts` path
 remains a compatibility entrypoint but no longer imports Pi tool factories.
 After updating JavaScript sources, fully exit Pi and resume in a new process.
 Pi 0.85.1 can retain native ESM modules across `/reload`, even after its extension
@@ -54,7 +96,7 @@ settings. The runtime does not silently rewrite your tool policy.
 | `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 |
+| `read` | `read([path1,path2])`; up to 64 paths, ordered values; rejects if any path fails |
 | `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 |
@@ -75,7 +117,8 @@ 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.
+questions reuse lexical stemming. Source questions and focused `about` reads
+accept at most 16 keywords. Ripgrep must be available on 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:
@@ -90,7 +133,13 @@ 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}` to narrow the scope.
+Use `{path: directory, about: question}` to narrow the scope. Scoping a query
+does not relabel a selected span as a complete file. Newly staged files and large
+staged source participate in discovery before commit. Raw offset/limit windows
+preserve LF/CRLF endings and the final newline; focused views add line labels.
+A matching window too large for the output budget is reported as budget-limited,
+not as an absent match. Do not combine incompatible modes such as `outline:true`
+and `evidence:true`.
 
 Ordinary reads stay self-contained. Outlines and graph evidence remain explicit
 options, not mandatory stages of source resolution. Ordinary calls also get:
@@ -122,6 +171,14 @@ For intentionally writing literal marker documentation only, opt in with
 `write({path,content,allowReadArtifacts:true})`. This is a data-loss guard, not
 full dataflow tracking or a security sandbox.
 
+Read/modify/write conflict checks retain a signature of the actual disk bytes,
+including for partial and large-file reads. A fresh explicit text read refreshes
+that observation; internal receipt reads and body-cache eviction do not. Commits
+reject changed content and conflicting symlink aliases, including new file paths.
+These checks do not provide a cross-process lock or make shell/import mutations
+transactional. Extensionless filenames also support `complete:true`, for example
+`read({path:"LICENSE",complete:true})`.
+
 Explicit read arrays reject missing/failed paths. For typed partial outcomes use
 `Promise.allSettled(paths.map(path => read(path)))`. Successful arrays remain arrays.
 For literal file content or scripts, prefer the optional tool-level `data` parameter:
@@ -136,8 +193,9 @@ For literal file content or scripts, prefer the optional tool-level `data` param
 }
 ```
 
-`data` crosses the worker boundary as JSON, never as JavaScript source. Its
-JSON-encoded length is capped separately at `maxCodeChars`; split larger inputs.
+`data` crosses the worker boundary as JSON, never as JavaScript source. For a
+single program its JSON-encoded length is capped separately at `maxCodeChars`;
+batches use the combined admission budget described below. 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.
@@ -179,7 +237,7 @@ 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).
+for short one-off operations. See [token measurements](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/TOKEN_COSTS.md).
 
 ### Batch already-known continuations
 
@@ -194,12 +252,32 @@ for short one-off operations. See [token measurements](docs/TOKEN_COSTS.md).
 }
 ~~~
 
-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.
+Use programs instead of top-level code/file. Supply 1--32 entries, each with
+code OR file and optional data. Top-level data supplies an optional default for
+each entry; explicit entry data replaces it entirely, including null, false, 0
+and empty strings. Every guest receives its own copy, not a shared mutable heap.
+The JSON-encoded array (or `{programs,data}` when defaults are supplied) must fit
+maxCodeChars. Common input counts once; result representations and output limits are unchanged.
 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.
 
+For independent audits that use the same inputs, send them once:
+
+```json
+{
+  "data": {"paths": ["src/a.js", "src/b.js"]},
+  "programs": [
+    {"code": "return await read(data.paths);"},
+    {"code": "return await Promise.all(data.paths.map(path => read({path, outline:true})));"}
+  ]
+}
+```
+
+This avoids repeating literal arguments, without a compression codec or result elision.
+Mutating `data` in one guest cannot affect the next. An entry with `data:null`
+receives null, not the shared object; there is no implicit object merge.
+
 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.
@@ -208,6 +286,12 @@ results/images: isError and details.ok identify failure, details.programs contai
 every attempted result, and details.attempted/total identifies unstarted work.
 Single code/file invocations retain their existing throwing behavior.
 
+Set `parallel: true` with `programs` to run independent entries concurrently
+(up to 8 at once). Each still gets a fresh guest and its own commit; results stay
+in submission order. A failed entry does not stop siblings. Two entries writing
+the same file race: the losing commit reports a conflict. Sequential remains the
+default. `parallel` is invalid on a lone `code` or `file` call.
+
 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
@@ -266,6 +350,8 @@ 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.
+Other read options, even false-valued flags, do not bypass a captured external
+read executor; its policy, transforms and failures remain authoritative.
 
 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
@@ -424,7 +510,7 @@ not hard real-time guarantees.
 It excludes model latency, provider tokens and prewarm time; it is not a universal
 comparison against every CodeMode implementation.
 
-See [the changelog](docs/CHANGELOG.md) for changes and compatibility notes.
+See [the changelog](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/CHANGELOG.md) for changes and compatibility notes.
 
 ## Research and prior art
 

package/docs/CHANGELOG.md

@@ -1,5 +1,155 @@
 # Changelog
 
+## Unreleased
+
+## [0.7.0] - 2026-09-17
+
+### Internals
+
+- Shared `src/contract/` for read/edit/bash shapes. Guest and host classify once;
+  guest no longer reimplements exclusive-mode routing before RPC.
+- Read dispatch is `classifyRead` → kind table. Disk vs staged `about` focus share
+  one `focusAbout` helper.
+- Invoke permission/target resolution lives in `bridge/invoke.js`.
+- Native adapters live in `src/adapters/{read,write,edit,bash,list}.js`;
+  `createNativeAdapters` is a 30-line assembler. The host kernel stays in
+  `host-bridge.js`.
+- Line/edit helpers in `fs/text-ops.js`. Unused catalog search/describe APIs and
+  the unused native-tool registrar are gone.
+- Per-function cyclomatic complexity is under 10: guest lifecycle is `GuestRun`,
+  program batches are `ProgramBatch`, snap ranking/read/edit/bash/VFS/evidence/
+  output/UI are extracted helpers and classify tables. Same public behavior;
+  BIND DAG unchanged.
+- Guest isolate: no `fs` / `child_process` / `import` / `require`. After `read()`
+  of a path, `write()` of that path throws (use `edit`, or `replace:true`).
+  Raw reads of large source require `about` / offset or `complete:true`;
+  large JSON returns a shape routing value (top-level keys, or length for
+  arrays) instead of throwing.
+- Standing reference stays one nova invocation: prefer `edit` after `read`,
+  `json`/about/`complete:true` for large files, no guest `fs`, and
+  `programs`/`parallel:true` for independent work *inside* one call. Overlapping
+  sibling `supernova` calls still hint that independent work belongs in one
+  program.
+
+### Added
+
+- `parallel: true` on `programs`: independent entries run concurrently (up to 8
+  lanes) in fresh guests, results keep submission order, and a failed entry does
+  not stop siblings. Two entries writing the same file race; the losing commit
+  reports a conflict. Sequential batches still stop on the first failure.
+  `parallel` is rejected on a lone `code` or `file` call.
+- JSON selectors accept array `.length` (for example `.items.length`) so a
+  catalog count does not require dumping the array. String `.length` is still
+  rejected; this is not jq.
+- Raw reads of JSON above the bound return a shape routing value instead of
+  throwing: `{status:"too_large", path, chars, keys}` for objects (`length`
+  for top-level arrays), so the same program can project with `json:".field"`
+  and array reads survive one oversize member. Malformed JSON still throws;
+  non-JSON text still returns verbatim.
+
+### Changed
+
+- Prefer `edit` for a file already read; `write` remains replace-the-file.
+- Overlapping sibling `supernova` calls hint to batch independent work as
+  `programs` with `parallel:true`.
+- Empty programs (no adapter calls) still draw a nova card with a result preview
+  instead of a one-line `complete` status.
+- Shorter standing tool reference: 68 fewer tokens per request with the same
+  commands and surface needles. Wording compression plus dropped peripheral
+  clauses; the JSON/about signatures, prefer-edit rule, and batching nudge
+  stay. Ablation family verified live over 12 green gpt-6-astra runs.
+- Standing tool reference trimmed by 120 more tokens per request (o200k_base),
+  below the previous release baseline: limits and failure patterns already
+  taught by engine errors are no longer repeated proactively, and the batching
+  nudge, guest-confinement rule, and checkpoint clause are compressed. All
+  surface needles, the prefer-edit rule, and the oversize-JSON routing line
+  stay. Live-verified over 2 green gpt-6-astra runs against 2 task-matched
+  controls with no strategy change.
+- An acquired guest worker pipelines its successor while the run executes, so
+  back-to-back programs share construction cost: sequential batches run ~2x
+  faster (22.4ms to 10.5ms per realistic program). Isolated cold starts are
+  unchanged apart from the deferred successor spawn.
+- Multi-edit receipts render the first 32 matches with exact totals and an
+  `…N more matches` note instead of unbounded lines.
+- Write receipts report workspace-relative paths, matching `edited <rel>`.
+- Evidence and outline reads return compact JSON instead of pretty-printed.
+- Refused bridge calls (unknown or excluded tools) no longer consume the host
+  call budget; routing validation runs before charging.
+- The VFS body cache is gone: every read hits disk or its overlay, and CAS
+  baselines are the only retained per-file state.
+
+### Fixed
+
+- `bash({command, args}, opts)` no longer drops the second options argument:
+  `cwd` (and `timeoutMs`) merge in, with the params object's own keys winning
+  on conflict. Covered by argv-form tests.
+- Over-budget JSON selections return an in-band routing value
+  (`{status:"too_large", path, selector, chars}` with `keys` or `length`)
+  instead of throwing, so one oversize field no longer kills the read and
+  small sibling selections flow through. The standing reference line covers
+  raw and selection routing at the same token cost; live-verified over 3
+  green runs (top-level keys now answer in 1 call instead of 2).
+- Memory-limit failures now report the RSS growth, the in-flight operation,
+  host-call count, and tracked host bytes (index entries, overlays),
+  splitting tracked from untracked growth so host-side pressure
+  is distinguishable from tool-side growth.
+- `process.kill` is sealed out of the guest realm: signals are process-wide
+  and could terminate the host. Stop processes with `bash`.
+- Patch hunks that drift report their relocation per hunk, and a hunk whose
+  context matches more than one location fails with a disambiguation error
+  instead of applying at the first candidate.
+- A failed commit keeps CAS baselines for files it never touched, so a later
+  write to a diverged path fails loudly instead of re-capturing unknown
+  bytes as the new truth.
+- The workspace index reuses one scratch read buffer instead of allocating
+  512 KiB per file, bounding transient RSS on large-tree scans.
+
+## [0.6.0] - 2026-09-15
+
+### Added
+
+- Shared literal input for `programs`: top-level `data` defaults each entry, while
+  explicit entry data replaces it entirely, including falsy values. Every fresh
+  guest receives its own copy. The combined JSON admission budget counts common
+  input once; deadlines, host-call limits, separate commits and stop reports stay
+  unchanged. No implicit object merge, shared heap or inferred plan is introduced.
+
+### Hardened execution and reads
+
+- Keep byte-accurate conflict snapshots independent of receipt/body caches.
+  Explicit rereads refresh observations; internal diff reads and cache eviction do
+  not rebase pending writes. Partial and focused reads retain full-file signatures,
+  including above 16 MiB, and invalid UTF-8 no longer causes a false conflict.
+- Canonicalize new-file destinations before checking conflicting symlink aliases,
+  while preserving the existing logical paths in workspace-change notifications.
+- Preserve read/mutation/checkpoint ordering across coalesced read waves. Tighten
+  input validation, cancellation handling and bounded output without reusing an
+  executed worker or reducing individual independent-read budgets.
+- Keep captured read overrides authoritative when options are supplied. Align
+  native/guest evidence results and path-array aliases; reject incompatible modes
+  and enforce the same focused-query keyword cap for disk and staged content.
+- Discover newly staged declarations in file-scoped queries and large overlays.
+  Preserve line endings, EOF characters and post-edit line coordinates. Distinguish
+  absent matches from matches that exceed the view budget. `complete` consistently
+  means the whole file; extensionless paths support `complete:true`.
+
+### Documentation and verification
+
+- Document shared-input examples, commit/rollback and override boundaries, and the
+  need for a full host restart after JavaScript updates. `/reload` can retain old
+  native ESM modules; pushing GitHub does not update an npm installation.
+- Restore the historical token fixture and hash-lock it. Version the single
+  terminating-newline expectation separately, without changing historical traffic,
+  programs, decision boundaries or acceptance thresholds.
+- Add failure-first regressions for reviewed and newly found defects. Correct
+  oversized fixtures, non-finite timeout inputs and misleading test descriptions.
+- Measure shared-input audits with identical complete outputs: 16,309 to 5,499
+  tokens (o200k_base) and 14,649 to 5,197 (cl100k_base), including replay, result
+  framing and added standing guidance. These are workload-specific non-compressive
+  savings, not provider-billing or live-model quality claims. See
+  [token measurements](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/TOKEN_COSTS.md)
+  for the unchanged historical gates, accounting and reproduction commands.
+
 ## [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.

package/docs/TOKEN_COSTS.md

@@ -1,11 +1,12 @@
 # Token usage and benchmarks
 
-Supernova reduces repeated tool traffic through explicit program reuse and batching.
+Supernova reduces repeated tool traffic through explicit program reuse, batching
+and shared batch input defaults.
 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.
+See the [API guide](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/README.md) for program-file and batch usage.
 
 ## Reproduce
 
@@ -69,12 +70,12 @@ text contributes to totals through later history, not as a second charge.
 
 ## Measured results
 
-Observed on macOS with Node v26.7.0.
+Observed for 0.6.0 on 2026-09-15, on an Apple M5 Max running macOS and 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%** |
+| o200k_base | 28,130 | 18,535 | 9,843 | **46.90%** | **65.01%** |
+| cl100k_base | 27,841 | 18,310 | 9,726 | **46.88%** | **65.07%** |
 
 The gate requires at least 40% reduction on **each tokenizer for the complete
 workload**, not for every scenario individually. Token counts and reductions are
@@ -83,15 +84,12 @@ 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
+### Definition and result accounting
 
-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.
+The current serialized definition is 602 tokens with o200k_base and 595 with
+cl100k_base, versus 908 and 901 in the frozen non-batched baseline. It retains
+command signatures, complete-read and JSON limits, array-read failure rules,
+transaction boundaries, batch defaults and edit/view guidance on every request.
 
 For the fixed six-call schedule, the accounting can also be written as:
 
@@ -99,17 +97,9 @@ For the fixed six-call schedule, the accounting can also be written as:
 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 definition is counted seven times, including the final handoff. Batch result
+framing and every attempted program's text are counted too. One-off calls should
+not be assumed to benefit from batching.
 
 The report also includes separate source-framing and argument-reuse comparisons.
 Those component measurements are not total-session savings, and the reported
@@ -117,28 +107,78 @@ 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.
 
+## Shared batch input: a separate 0.6.0 measurement
+
+Eight independent audit programs use the same list of 48 source paths. The before
+arm repeats the literal `data` in every entry; the after arm supplies it once at
+the top level. Both execute the same programs and return the same complete source
+strings and typed results. The before request fits the existing admission cap;
+this is not a comparison against a hypothetical request that could never run.
+
+| Tokenizer | Repeated-input traffic | Shared-input traffic | Reduction | Arguments before / after | Unchanged result tokens |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| o200k_base | 16,309 | 5,441 | **66.64%** | 6,461 / 1,043 | 2,151 |
+| cl100k_base | 14,649 | 5,135 | **64.95%** | 5,684 / 945 | 2,055 |
+
+Each arm has one tool invocation followed by the final answer request:
+
+~~~text
+Total = 2*D + 2*A + R
+~~~
+
+Arguments are charged when generated and when replayed; the complete result is
+charged on handoff. The standing guidance measures 602 definition tokens per
+request with o200k_base (595 with cl100k_base), and that cost is included in
+the after totals.
+There is no source compression, result elision, hidden output or lost decision
+boundary. Programs receive fresh data copies, not a shared mutable heap.
+
+The gate requires at least 70% less argument traffic and 60% less replay-inclusive
+traffic in each encoding, plus equality of the complete normalized output. This
+workload deliberately exercises repeated input; it is not an average task-cost
+estimate. The original 13-program/six-call benchmark remains separate and intact.
+
 ## Benchmark integrity
 
-The [baseline fixture](../tests/efficiency/token-baseline.json) contains the source
+The [baseline fixture](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/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
+[runner](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/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.
+- Every original argument and expected failure matches; complete logical results
+  match the explicit current newline contract described below.
 - 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.
+are fixed test inputs, not production execution rules. The baseline is not regenerated
+by the benchmark and is checked against its SHA-256 before execution.
+
+Contract v2 preserves the terminating newline of one selected source line. The
+runner derives that single expected-output correction from the frozen input, not
+from candidate output. The historical fixture and its traffic counts stay
+untouched; programs, arguments, failures and decision boundaries are unchanged.
+The shared-input comparison separately requires equal complete result text in
+both arms, after only run-metadata normalization.
+
+Contract v3 reports write receipts relative to the workspace (`wrote rel/path`,
+matching the long-standing `edited <rel>` form) instead of absolute paths. The
+runner strips the frozen `/workspace/` prefix from baseline outputs; the
+historical fixture and its traffic counts stay untouched. Temporary workspace
+prefixes no longer appear in live receipts, so that normalization only applies
+to the frozen baseline side.
+
+The README and these docs ship in the npm tarball. Benchmarks and test fixtures
+remain in the GitHub checkout, so their links above use GitHub URLs.
 
 Recorded baseline SHA-256:
 
 ~~~text
-79a819eca82c8a5ff381e96b7669d8a5bf04fabbc8c10cf02f3a7c8817171b62
+96964f990f481ac05afaefdd02001bd15f61835a8381349a61e38c06209d7508
 ~~~
 
 ## Limitations
@@ -150,6 +190,8 @@ Recorded baseline SHA-256:
   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.
+- The report also has an experimental citation-elision arm. It is disabled by
+  default and is not the source of the non-compressive savings reported here.
 - Existing read, output, log, image and execution limits still apply. The
   benchmark does not obtain savings by lowering them or hiding truncation.