pi-fovea 0.25.0 → 0.26.0

package/README.md

@@ -520,6 +520,12 @@ special case of this field. [docs/heat-diffusion.md](docs/heat-diffusion.md)
 walks through conductance tiers, specificity bridges, hub gravity, and inferred
 regions.
 
+## Snapshot substrate API
+
+`pi-fovea/substrate` exposes a versioned, session-free graph and heat interface for
+consumers such as pi-contour. It assembles caller-supplied immutable facts without
+discovering files or reading a live worktree. See [docs/substrate.md](docs/substrate.md).
+
 ## Languages
 
 Full symbol and call extraction: **TypeScript, TSX, JavaScript, Python, Go, and Rust**.

package/docs/substrate.md

@@ -0,0 +1,23 @@
+# Snapshot substrate v1
+
+`pi-fovea/substrate` is a small, session-free entrypoint for graph consumers. It does not enroll roots, discover files, read project rules, perform extraction, or inspect the current working tree.
+
+```ts
+import { SUBSTRATE_VERSION, assembleFactGraph, diffuseMass, type SnapshotFacts } from "pi-fovea/substrate";
+
+if (SUBSTRATE_VERSION !== 1) throw new Error("Unsupported substrate version");
+const facts = new Map<string, SnapshotFacts>();
+// Populate immutable per-file symbol/import/call/literal/anchor facts.
+const graph = await assembleFactGraph(facts);
+const source = new Float64Array(graph.nodes.length);
+// Assign nonnegative source mass to graph node indices.
+const fields = diffuseMass(graph, source, [0.5, 2, 8]);
+```
+
+`SnapshotFacts` is the explicit projection of Fovea's extraction-fact shape. Its legacy `sha1` field is caller-owned content identity; graph assembly does not interpret that digest. Every site must name its owning repository-relative file. Unsafe paths and cross-file witnesses are rejected. Callers own source coverage and must keep supplied facts immutable during assembly.
+
+The resulting `Graph` retains nodes, typed relationship evidence, file/name indexes, and import coverage. Callers can select or reweight relationships without introducing a second graph resolver. Navigation conductances are not calibrated defect probabilities.
+
+`diffuseMass` accepts a graph, a finite nonnegative source vector matching the node count, and finite times in [0,64]. Results are `{ time, mass: Float64Array }` in requested order. It shares Chebyshev recurrence vectors across times and applies the forward random-walk conjugation of the symmetric heat kernel. Isolates retain their original mass. Floating-point conservation is approximate; tests cover it against existing solver paths, whose independent reference tests remain in the core suite.
+
+No session, disclosure, snapshot cache, or quality policy is implied by this API. Consumers such as pi-contour supply immutable Git/index snapshots, analysis-specific projections, source evidence, and their own bounded caches.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",
@@ -34,10 +34,12 @@
     "image": "https://raw.githubusercontent.com/monotykamary/pi-fovea/main/media/cover.svg"
   },
   "exports": {
-    "./ops": "./src/core/ops.ts"
+    "./ops": "./src/core/ops.ts",
+    "./substrate": "./src/substrate.ts"
   },
   "files": [
     "src",
+    "docs/substrate.md",
     "cli.ts",
     "dist",
     "skills",

package/src/substrate.ts

@@ -0,0 +1,46 @@
+// Versioned, session-free substrate for consumers of immutable extraction facts.
+// This module never discovers files, reads project configuration, or loads a session.
+import { assembleGraphWithIndex } from "./core/graph.js";
+import { buildCsr, chebyshevVectors, chooseOrder, heatField } from "./core/heat.js";
+import type { FileFacts } from "./core/build.js";
+import type { Graph } from "./core/types.js";
+
+export const SUBSTRATE_VERSION = 1 as const;
+export type SnapshotFacts = Pick<FileFacts, "sha1" | "symbols" | "imports" | "calls" | "literals" | "anchors">;
+export type { Graph, Edge, NodeRec, EdgeEvidence } from "./core/types.js";
+
+/** Assemble only the supplied files. Paths and witnesses must belong to this snapshot. */
+export async function assembleFactGraph(facts: ReadonlyMap<string, SnapshotFacts>): Promise<Graph> {
+  const files = [...facts.keys()].sort();
+  for (const file of files) {
+    if (!file || file.startsWith("/") || file.includes("\\") || file.split("/").some(p => p === ".." || p === "." || !p)) {
+      throw new Error(`Invalid snapshot path: ${file}`);
+    }
+    const fact = facts.get(file)!;
+    for (const site of [...fact.symbols, ...fact.imports, ...fact.calls, ...fact.literals, ...fact.anchors]) {
+      if (site.file !== file) throw new Error(`Witness outside its snapshot file: ${site.file}`);
+    }
+  }
+  return (await assembleGraphWithIndex("", files, new Map(facts))).graph;
+}
+
+/** Column-mass heat D^(1/2) exp(-t Lsym) D^(-1/2) q, sharing one Chebyshev basis.
+ * Times are analysis scales, not wall-clock ages. Isolates retain their source mass.
+ * Results are exposure, not calibrated risk. Callers may project/reweight the graph.
+ */
+export function diffuseMass(graph: Graph, source: Float64Array, times: readonly number[]): Array<{ time: number; mass: Float64Array }> {
+  if (source.length !== graph.nodes.length || source.some(v => !Number.isFinite(v) || v < 0)) {
+    throw new Error("Mass must be finite, nonnegative, and match the graph");
+  }
+  if (times.some(t => !Number.isFinite(t) || t < 0 || t > 64)) throw new Error("Diffusion scales must lie in [0, 64]");
+  if (graph.edges.some(e => !Number.isFinite(e.w) || e.w < 0 || !Number.isInteger(e.a) || !Number.isInteger(e.b)
+    || e.a < 0 || e.b < 0 || e.a >= source.length || e.b >= source.length)) throw new Error("Invalid conductance edge");
+  if (!times.length) return [];
+  const csr = buildCsr(graph);
+  const seed = Float64Array.from(source, (mass, i) => csr.deg[i]! > 0 ? mass / Math.sqrt(csr.deg[i]!) : 0);
+  const vectors = chebyshevVectors(csr, seed, chooseOrder(Math.max(...times)));
+  return times.map(time => {
+    const field = heatField(vectors, time, csr.n);
+    return { time, mass: Float64Array.from(source, (mass, i) => csr.deg[i]! > 0 ? Math.sqrt(csr.deg[i]!) * field[i]! : mass) };
+  });
+}