pi-fovea 0.29.2 → 0.31.0

package/LAWS.bend

@@ -0,0 +1,110 @@
+import Base
+import ./proofs/disclosure.bend as D
+import ./proofs/heat.bend as H
+import ./proofs/kernel.bend as K
+import ./proofs/basis.bend as B
+
+# Proposed specifications extracted from render.ts and heat.ts. Review these independently
+# of PROOF.bend; do not weaken a law to make an implementation pass.
+
+# Disclosure: these six laws cover the entire five-Boolean input domain.
+law scope_wins:
+  for excluded: Bool
+  for seen: Bool
+  for repeat: Bool
+  for nucleus: Bool
+  {K.disclosure(False{}, excluded, seen, repeat, nucleus) == D.Drop{} : D.Decision}
+
+law exclusion_wins:
+  for scope: Bool
+  for seen: Bool
+  for repeat: Bool
+  for nucleus: Bool
+  {K.disclosure(scope, True{}, seen, repeat, nucleus) == D.Drop{} : D.Decision}
+
+law fresh_revealed:
+  for repeat: Bool
+  for nucleus: Bool
+  {K.disclosure(True{}, False{}, False{}, repeat, nucleus) == D.Reveal{} : D.Decision}
+
+law seen_suppressed:
+  for nucleus: Bool
+  {K.disclosure(True{}, False{}, True{}, False{}, nucleus) == D.Suppress{} : D.Decision}
+
+law periphery_suppressed:
+  for repeat: Bool
+  {K.disclosure(True{}, False{}, True{}, repeat, False{}) == D.Suppress{} : D.Decision}
+
+law nucleus_repeated:
+  for seen: Bool
+  {K.disclosure(True{}, False{}, seen, True{}, True{}) == D.Reveal{} : D.Decision}
+
+# Executed natural-number accounting. This does NOT prove token estimation,
+# renderer formatting, or binary-search monotonicity. Keep boundary tests.
+law shown_bounded_by_total:
+  for +total: Nat
+  for requested: Nat
+  {Nat.is_le(K.shownCount(total, requested), total) == True{} : Bool}
+
+law shown_bounded_by_request:
+  for total: Nat
+  for +requested: Nat
+  {Nat.is_le(K.shownCount(total, requested), requested) == True{} : Bool}
+
+law counts_conserved:
+  for +total: Nat
+  for +requested: Nat
+  {Nat.add(K.shownCount(total, requested), K.remainingCount(total, requested)) == total : Nat}
+
+law full_prefix_omits_nothing:
+  for +total: Nat
+  {K.remainingCount(total, total) == 0n : Nat}
+
+law cap_idempotent:
+  for +total: Nat
+  for +cap: Nat
+  {K.shownCount(K.shownCount(total, cap), cap) == K.shownCount(total, cap) : Nat}
+
+# Exact nonnegative rational transport model, not IEEE-754 or the exponential.
+law heat_vector_add_mass:
+  for +xs: +List<Nat>
+  for +ys: +List<Nat>
+  {H.sum(H.add(xs, ys)) == Nat.add(H.sum(xs), H.sum(ys)) : Nat}
+
+law heat_scale_mass:
+  for +mass: Nat
+  for +weights: +List<Nat>
+  {H.sum(H.scale(mass, weights)) == Nat.mul(mass, H.sum(weights)) : Nat}
+
+# D = 1 + denominator is strictly positive. For source numerators a over Q,
+# transport returns numerators over D*Q; this equality conserves rational mass.
+law heat_transport_mass:
+  for +columns: +List<H.Column>
+  for +denominator: Nat
+  for normalized: H.Normalized(columns, 1n+denominator)
+  {H.sum(H.transport(columns)) == Nat.mul(H.input_mass(columns), 1n+denominator) : Nat}
+
+law heat_singleton_mass:
+  for +mass: Nat
+  {H.sum(H.transport([H.Source{mass, [1n]}])) == mass : Nat}
+
+# Executed basis-extension commands. Float64 evaluation remains host code.
+law basis_empty_refused:
+  for order: Nat
+  {K.basisStep(0n, order) == B.Empty{} : B.Step}
+
+law basis_complete_retained:
+  for +have: Nat
+  for +order: Nat
+  for complete: {Nat.is_le(1n+have, order) == False{} : Bool}
+  {K.basisStep(1n+have, order) == B.Done{} : B.Step}
+
+law basis_first_order:
+  for order: Nat
+  {K.basisStep(1n, 1n+order) == B.First{} : B.Step}
+
+law basis_next_exact:
+  for +have: Nat
+  for +order: Nat
+  for missing: {Nat.is_le(2n+have, order) == True{} : Bool}
+  {K.basisStep(2n+have, order) == B.Next{2n+have, 1n+have, have} : B.Step}

package/PROOF.bend

@@ -0,0 +1,118 @@
+import Base
+import ./LAWS.bend as Laws
+import ./proofs/disclosure.bend as D
+import ./proofs/counts.bend as C
+import ./proofs/counts-proof.bend as CP
+import ./proofs/heat.bend as H
+import ./proofs/nat-proof.bend as N
+import ./proofs/kernel.bend as K
+import ./proofs/basis.bend as B
+
+def Laws.scope_wins(excluded, seen, repeat, nucleus):
+  {==}
+
+def Laws.exclusion_wins(scope, seen, repeat, nucleus):
+  match scope:
+    case False{}:
+      {==}
+    case True{}:
+      {==}
+
+def Laws.fresh_revealed(repeat, nucleus):
+  {==}
+
+def Laws.seen_suppressed(nucleus):
+  {==}
+
+def Laws.periphery_suppressed(repeat):
+  match repeat:
+    case False{}:
+      {==}
+    case True{}:
+      {==}
+
+def Laws.nucleus_repeated(seen):
+  match seen:
+    case False{}:
+      {==}
+    case True{}:
+      {==}
+
+def Laws.shown_bounded_by_total(total, requested):
+  +requested = requested
+  %Equal.sym(Nat, C.fastShown(total, requested), C.shown(total, requested), CP.shown_equiv(total, requested)) : {Nat.is_le(_, total) == True{} : Bool}
+  CP.bounded_total(total, requested)
+
+def Laws.shown_bounded_by_request(total, requested):
+  +total = total
+  %Equal.sym(Nat, C.fastShown(total, requested), C.shown(total, requested), CP.shown_equiv(total, requested)) : {Nat.is_le(_, requested) == True{} : Bool}
+  CP.bounded_request(total, requested)
+
+def Laws.counts_conserved(total, requested):
+  %Equal.sym(Nat, C.fastShown(total, requested), C.shown(total, requested), CP.shown_equiv(total, requested)) : {Nat.add(_, C.fastRemaining(total, requested)) == total : Nat}
+  %Equal.sym(Nat, C.fastRemaining(total, requested), C.remaining(total, requested), CP.remaining_equiv(total, requested)) : {Nat.add(C.shown(total, requested), _) == total : Nat}
+  CP.conserved(total, requested)
+
+def Laws.full_prefix_omits_nothing(total):
+  %Equal.sym(Nat, C.fastRemaining(total, total), C.remaining(total, total), CP.remaining_equiv(total, total)) : {_ == 0n : Nat}
+  CP.full(total)
+
+def Laws.cap_idempotent(total, cap):
+  %Equal.sym(Nat, C.fastShown(C.fastShown(total, cap), cap), C.shown(C.fastShown(total, cap), cap), CP.shown_equiv(C.fastShown(total, cap), cap)) : {_ == C.fastShown(total, cap) : Nat}
+  %Equal.sym(Nat, C.fastShown(total, cap), C.shown(total, cap), CP.shown_equiv(total, cap)) : {C.shown(_, cap) == C.fastShown(total, cap) : Nat}
+  %Equal.sym(Nat, C.fastShown(total, cap), C.shown(total, cap), CP.shown_equiv(total, cap)) : {C.shown(C.shown(total, cap), cap) == _ : Nat}
+  CP.idempotent(total, cap)
+
+def Laws.heat_vector_add_mass(xs, ys):
+  match xs ys:
+    case Nil{} _:
+      {==}
+    case x <> tail Nil{}:
+      Equal.sym(Nat, Nat.add(H.sum(x <> tail), 0n), H.sum(x <> tail), N.add_zero(H.sum(x <> tail)))
+    case x <> xt y <> yt:
+      %N.add_shuffle(x, y, H.sum(xt), H.sum(yt)) : {Nat.add(Nat.add(x, y), H.sum(H.add(xt, yt))) == _ : Nat}
+      %Laws.heat_vector_add_mass(xt, yt) : {Nat.add(Nat.add(x, y), H.sum(H.add(xt, yt))) == Nat.add(Nat.add(x, y), _) : Nat}
+      {==}
+
+def Laws.heat_scale_mass(mass, weights):
+  match mass:
+    case 0n:
+      {==}
+    case 1n+p:
+      %Laws.heat_scale_mass(p, weights) : {H.sum(H.add(weights, H.scale(p, weights))) == Nat.add(H.sum(weights), _) : Nat}
+      Laws.heat_vector_add_mass(weights, H.scale(p, weights))
+
+def Laws.heat_transport_mass(columns, denominator, normalized):
+  match columns:
+    case Nil{}:
+      {==}
+    case H.Source{mass, weights} <> tail:
+      (column_norm, tail_norm) = normalized
+      %N.mul_add(mass, H.input_mass(tail), 1n+denominator) : {H.sum(H.add(H.scale(mass, weights), H.transport(tail))) == _ : Nat}
+      %Equal.cong(Nat, Nat, x => Nat.mul(mass, x), H.sum(weights), 1n+denominator, column_norm) : {H.sum(H.add(H.scale(mass, weights), H.transport(tail))) == Nat.add(_, Nat.mul(H.input_mass(tail), 1n+denominator)) : Nat}
+      %Laws.heat_scale_mass(mass, weights) : {H.sum(H.add(H.scale(mass, weights), H.transport(tail))) == Nat.add(_, Nat.mul(H.input_mass(tail), 1n+denominator)) : Nat}
+      %Laws.heat_transport_mass(tail, denominator, tail_norm) : {H.sum(H.add(H.scale(mass, weights), H.transport(tail))) == Nat.add(H.sum(H.scale(mass, weights)), _) : Nat}
+      Laws.heat_vector_add_mass(H.scale(mass, weights), H.transport(tail))
+
+def Laws.heat_singleton_mass(mass):
+  %N.mul_one(mass) : {H.sum(H.transport([H.Source{mass, [1n]}])) == _ : Nat}
+  %N.add_zero(mass) : {H.sum(H.transport([H.Source{mass, [1n]}])) == Nat.mul(_, 1n) : Nat}
+  Laws.heat_transport_mass([H.Source{mass, [1n]}], 0n, ({==}, Unit{}))
+
+def Laws.basis_empty_refused(order):
+  {==}
+
+def Laws.basis_complete_retained(have, order, complete):
+  %Equal.sym(Bool, Nat.is_le(1n+have, order), False{}, complete) : {B.choose(_, 1n+have) == B.Done{} : B.Step}
+  {==}
+
+def Laws.basis_first_order(order):
+  match order:
+    case 0n:
+      {==}
+    case 1n+p:
+      {==}
+
+def Laws.basis_next_exact(have, order, missing):
+  %Equal.sym(Bool, Nat.is_le(2n+have, order), True{}, missing) : {B.choose(_, 2n+have) == B.Next{2n+have, 1n+have, have} : B.Step}
+  {==}

package/README.md

@@ -132,7 +132,7 @@ pi install /absolute/path/to/pi-fovea
 
 </details>
 
-There is also a package for any agent shell or CI:
+The standalone **`@monotykamary/fovea`** package provides the same engine for any agent shell or CI, without installing Pi:
 
 ```sh
 fovea sketch /path/to/repo 900
@@ -142,13 +142,19 @@ fovea rules /path/to/repo
 fovea status /path/to/repo
 ```
 
-Install the CLI globally — the published bin is a single self-contained bundle, so it runs on plain Node.js (no tsx, no node_modules):
+Install the CLI globally — its bundled JavaScript runs on plain Node.js (no Pi or tsx required):
 
 ```sh
-npm i -g pi-fovea      # or: bun add -g pi-fovea, bun add -g pi-fovea
+npm i -g @monotykamary/fovea      # or: bun add -g @monotykamary/fovea
 ```
 
+The executable is still `fovea`. The legacy `npm i -g pi-fovea` remains supported;
+choose one global package because both provide that executable. Installing the
+Pi extension through `pi install npm:pi-fovea` can coexist with the standalone CLI.
+
 From a checkout, `bun run fovea` runs the live source via `tsx`, and `bun run build:cli` rebuilds `dist/cli.mjs` (the `prepack` hook keeps the published bundle in sync).
+`bun run pack:cli` produces the scoped CLI tarball at `dist/fovea-cli.tgz` using the
+root package version. See [CLI usage](docs/cli.md) and [release checks and publishing](docs/releasing.md).
 
 ## Many projects, one conversation
 
@@ -544,12 +550,22 @@ calls and proof checking are not modeled; Bend 1/HVM syntax is not supported.
 
 ```sh
 bun install
-bun run check:fast   # typecheck + tests your working tree affects
+bun run check:fast   # Bend laws + artifact parity + typecheck + affected tests
 bun run test:smoke   # curated scan-to-render floor, seconds
 bun run bench        # rate–distortion and refresh bench against ../pi-fabric
 bun run bench tests/fixtures/mini  # self-contained smoke run
 ```
 
+Development checks require **Bend 2.0.26** (`bend guide`). See [laws, proofs, and
+which tests they can replace](docs/proofs.md). Bend is development-only; the
+extension and published CLI need no Bend installation or generation step.
+Production executes the committed Bend-compiled disclosure, prefix-accounting,
+and heat-basis command kernels. After changing their sources or adapters, run
+`bun run proofs:generate`; `bun run proofs:artifact` checks the receipt without
+Bend. CLI builds check that receipt; publishing also proves and reproduces the
+artifact. The Float64 heat solver still relies on numerical tests, not a proof
+of its approximation or rounding errors.
+
 The [warm-path performance report](docs/performance.md) compares the coverage-complete implementation with the optimized version. `bun run corpus:performance <coverage-work> <before-source> <after-source> [rounds]` runs alternating, isolated comparisons with a shared extraction snapshot, independent Git indexes, and exact graph, focus/dwell/sketch, and overflow-content checks. It does not trade fewer candidates or weaker freshness checks for speed. For Node, run `NODE_OPTIONS='--import tsx' node scripts/performance-corpus.mjs ...`; development dependencies are required.
 
 Warm matching derives query terms once and caches normalized symbol names by weak node identity, checking renames before reuse. Focus builds only the heat orders currently needed; dwell appends missing orders without replacing its existing basis. No new kernel or review state is introduced. Independent cold extraction can select different literal-join locations when capture order varies, so this paired benchmark deliberately makes no cold-extraction speedup claim.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,12 @@
+# Third-party notices
+
+## Bend 2.0.26
+
+The generated policy kernel contains Bend's emitted JavaScript trampoline and
+compiled Base primitives from [Bend 2.0.26](https://github.com/bendlang/bend/tree/v2.0.26),
+Copyright 2026 HigherOrderCO, licensed under Apache-2.0. Pi Fovea removes the
+CLI invocations, adds library exports, and tree-shakes/minifies unused runtime
+code using the bridge pattern developed in Pi Fabric.
+
+The complete license is distributed at
+[docs/licenses/bend-apache-2.0.txt](docs/licenses/bend-apache-2.0.txt).