@fundamental-engine/core 0.10.1 → 0.10.2

package/dist/engine/field.js

@@ -49,6 +49,7 @@ import { forceAt, netField } from "./streamlines.js";
 import { traceFieldLines } from "./fieldlines.js";
 import { fieldLineSeeds } from "./fieldline-seeds.js";
 import { flowBiasInto, makeFlowFocus } from "./flow.js";
+import { admits as admitsShare } from "./agent-read-share.js";
 import { devWarnNoOp } from "../contracts/guards.js";
 import { FIELD_VERSION } from "../version.js";
 import { energyReport } from "../diagnostics/energy.js";
@@ -56,100 +57,13 @@ import { accumulateAt } from "../diagnostics/probes.js";
 import { diffFieldSnapshots, replayFieldSnapshots } from "./field-snapshot.js";
 import { lintProjections } from "./governance.js";
 import { applyLens } from "./query-lens.js";
+import { clonePolicy, applyRedactions, resolveSnapshotInclusion } from "./snapshot-policy.js";
 // Shared draw/integrate scratch — reused across the per-particle and per-cell hot loops so an
 // active flow focus and the particle draw don't allocate a `{x,y}` / `[r,g,b]` each iteration.
 // Safe to share module-wide: each field's frame runs synchronously, and every read consumes the
 // scratch before the next write (no overlapping lifetimes, no cross-instance interleaving).
 const _flowB = { x: 0, y: 0 };
 const _rgb = [0, 0, 0];
-/** Deep-copy a {@link FieldPolicy} (shallow is unsafe — `budgets` is nested). `undefined` → `{}` (the
- *  unbounded default). Used on set + read so callers can neither mutate the field's live policy nor
- *  observe later mutations of the object they passed in. */
-function clonePolicy(p) {
-    if (!p)
-        return {};
-    const out = {};
-    if (p.allowBodyDataInSnapshots != null)
-        out.allowBodyDataInSnapshots = p.allowBodyDataInSnapshots;
-    if (p.allowMotionProjection != null)
-        out.allowMotionProjection = p.allowMotionProjection;
-    if (p.maxMotionBudget != null)
-        out.maxMotionBudget = p.maxMotionBudget;
-    if (p.budgets)
-        out.budgets = { ...p.budgets };
-    return out;
-}
-/**
- * Resolve {@link FieldSnapshotOptions} — an optional {@link SnapshotProfile} composed with the explicit
- * `include*` flags — to concrete inclusion, TIGHTEST-wins. A profile establishes a baseline; an explicit
- * flag may tighten it further but never widen it (an explicit `true` cannot re-enable what the profile
- * turned off). `includeData` additionally passes through the policy gate at the call site (this only
- * governs whether the CALLER asked for it). Relationships default true when nothing narrows them.
- */
-function resolveSnapshotInclusion(opts) {
-    // Per-profile baselines. `debug` = everything; `agent` = structure + attribution, no opaque data;
-    // `bug-report` = structural + versions, no data; `public` = ids + shape only.
-    const base = {
-        debug: { includeParticles: true, includeRelationships: true, includeData: true, includeInfluences: true },
-        agent: { includeParticles: false, includeRelationships: true, includeData: false, includeInfluences: true },
-        'bug-report': { includeParticles: false, includeRelationships: true, includeData: false, includeInfluences: true },
-        public: { includeParticles: false, includeRelationships: false, includeData: false, includeInfluences: false },
-    };
-    const p = opts.profile;
-    if (!p) {
-        // No profile: today's defaults — relationships default true, the rest default false.
-        return {
-            includeParticles: opts.includeParticles === true,
-            includeRelationships: opts.includeRelationships !== false,
-            includeData: opts.includeData === true,
-            includeInfluences: opts.includeInfluences === true,
-        };
-    }
-    const b = base[p];
-    // TIGHTEST wins: a flag is on only if the profile allows it AND the caller didn't explicitly turn it
-    // off. An explicit `true` can never widen past the profile's baseline.
-    return {
-        includeParticles: b.includeParticles && opts.includeParticles !== false,
-        includeRelationships: b.includeRelationships && opts.includeRelationships !== false,
-        includeData: b.includeData && opts.includeData !== false,
-        includeInfluences: b.includeInfluences && opts.includeInfluences !== false,
-    };
-}
-/**
- * Strip a set of dotted `redactions` paths from a plain reading (query result or snapshot). A top-level
- * key (`'metrics'`, `'relationships'`) deletes that key from the object. A `<prefix>.<key>` path where
- * prefix ∈ {body, relationship, influence, projection} strips `<key>` from each entry of the matching
- * list; `body.data` strips per-body `data`. Mutates the passed object (it's always a fresh result/copy).
- */
-function applyRedactions(reading, redactions) {
-    const listKeyFor = { body: 'bodies', relationship: 'relationships', influence: 'influences', projection: 'projections' };
-    for (const path of redactions) {
-        const dot = path.indexOf('.');
-        if (dot < 0) {
-            delete reading[path];
-            continue;
-        }
-        const prefix = path.slice(0, dot);
-        const key = path.slice(dot + 1);
-        const listKey = listKeyFor[prefix];
-        if (listKey && Array.isArray(reading[listKey])) {
-            for (const entry of reading[listKey]) {
-                if (entry && typeof entry === 'object')
-                    delete entry[key];
-            }
-        }
-        else if (prefix === 'metrics' && reading['metrics'] && typeof reading['metrics'] === 'object') {
-            delete reading['metrics'][key];
-        }
-        else {
-            // an unrecognized prefix addresses a nested top-level object key.
-            const target = reading[prefix];
-            if (target && typeof target === 'object')
-                delete target[key];
-        }
-    }
-    return reading;
-}
 // ── Focus / attention substrate (experimental) constants ────────────────────────────────────────
 /** default half-life of a focus deposit, in the field's simulation-clock unit (env.t SECONDS) — attention
  *  halves in ~8s. freshness() is unit-agnostic, so at/now/halfLife share env.t's unit (seconds). */
@@ -219,6 +133,45 @@ export function createField(canvas, opts = {}) {
     const store = new FieldStore();
     let nextParticleId = 1; // monotonic stable particle identity (readParticleIds); never reused
     const grids = new Map(); // §20.1 class [C] field buffers, lazy
+    // ── declared potentials (#443) ──────────────────────────────────────────────────────────────
+    // A host channel (`addField`) admitted as a scalar potential Φ and rasterised into a HELD grid the
+    // `relief` force reads as −∇Φ. This raster is the ONE place the engine caches a channel sampler
+    // (the amended `addField` contract), so its invalidation set is the entire correctness story:
+    //
+    //   addField(name, …)   a channel appeared          ─┐
+    //   handle.set(next)    the sampler was swapped      │  bump the epoch ⇒ the next read re-rasters
+    //   handle.remove()     the channel is gone          │  (remove ALSO drops the grid, so a removed
+    //   resize()            the buffers were rebuilt    ─┘   channel can never be read stale)
+    //
+    // There is deliberately NO schedule. Nothing re-rasters on a frame cadence, so held state cannot be
+    // frame-phase dependent — registering a channel on frame 3 gives the same trajectory as on frame 0 —
+    // and it cannot outlive its channel. `potentialAt` is pulled BY the force during the force pass and
+    // re-rasters exactly when the epoch it last saw has moved. Under reduced motion the integrator
+    // returns before the force pass (`dt === 0`), so nothing is sampled at all: the raster freezes with
+    // the motion, with no dt special-case here.
+    let channelEpoch = 0;
+    const potentialStamp = new Map(); // grid key → the epoch its cells were filled at
+    const potentialKey = (name) => `potential:${name}`;
+    function invalidatePotentials() {
+        channelEpoch++;
+    }
+    function potentialAt(name) {
+        const sampler = fieldChannels.get(name);
+        if (!sampler)
+            return undefined; // never registered, or removed — the force no-ops (never stale)
+        const key = potentialKey(name);
+        let g = grids.get(key);
+        if (!g) {
+            g = new ScalarGridImpl(W, H, 'held');
+            grids.set(key, g);
+            potentialStamp.set(key, -1);
+        }
+        if (potentialStamp.get(key) !== channelEpoch) {
+            g.fillFrom(sampler); // non-finite samples are clamped to 0 inside fillFrom, at the boundary
+            potentialStamp.set(key, channelEpoch);
+        }
+        return g;
+    }
     const reg = createRegistry();
     // host-agnostic discrete event bus (the read side): plain-data push for occurrences a non-DOM
     // host reacts to (a sink caught/released matter, the swarm settled) — no DOM, no polling. Cheap
@@ -328,7 +281,7 @@ export function createField(canvas, opts = {}) {
     // through its `data-body` token (e.g. `data-body="lens crystallize"`); an unused force costs nothing.
     registerCoreForces(reg); // the canonical nine (§6)
     registerNaturalForces(reg); // 8 natural primitives: gravity, charge, magnetism, thermal, … (§20.10)
-    registerExtendedForces(reg); // 19 designed extended forces: lens, crystallize, link, morph, … (§20.3)
+    registerExtendedForces(reg); // 20 designed extended forces: lens, crystallize, link, morph, relief, … (§20.3)
     // the environment seam: all DOM access goes through this injected host — core imports zero DOM.
     // In the browser, pass `browserHost()` from @fundamental-engine/dom (or use createBrowserField); the
     // @fundamental-engine/{elements,react,vanilla} entry points wire it for you.
@@ -427,6 +380,13 @@ export function createField(canvas, opts = {}) {
         // full above start·H, gone by (start+span)·H. Defaults reproduce start=0.3, span=0.85.
         heatmapFadeStart: opts.heatmapFade && Number.isFinite(opts.heatmapFade.start) ? opts.heatmapFade.start : 0.3,
         heatmapFadeSpan: opts.heatmapFade && Number.isFinite(opts.heatmapFade.span) && opts.heatmapFade.span > 0 ? opts.heatmapFade.span : 0.85,
+        // the resting-motion floor (declared, default OFF): validated to the two modes; strength ≥ 0 (default 1).
+        restingMotion: opts.restingMotion && (opts.restingMotion.mode === 'thermal' || opts.restingMotion.mode === 'flow')
+            ? {
+                mode: opts.restingMotion.mode,
+                strength: opts.restingMotion.strength != null && opts.restingMotion.strength >= 0 ? opts.restingMotion.strength : 1,
+            }
+            : undefined,
         // the integration scheme (substrate doc 04 §Step 3, #659); 'legacy' (default) is the shipped engine.
         integrator: (opts.integrator === 'fixed' || opts.integrator === 'velocity-verlet'
             ? opts.integrator
@@ -926,11 +886,23 @@ export function createField(canvas, opts = {}) {
         neighbors: (p, r) => store.neighbors(p, r),
         // scalar field-buffer service (§20.1 class [C]): created on demand, so a page
         // with no diffuse/propagate body allocates nothing. Grids named "wave…" use the
-        // wave scheme; everything else diffuses.
+        // wave scheme, "memory…" the slow-decay scheme, "potential:…" the HELD raster of a
+        // declared potential (#443 — it never steps); everything else diffuses.
+        //
+        // THE ONE NON-BYTE-IDENTICAL CHANGE in #443, stated rather than buried: a host that was
+        // already calling `grid('potential:…')` got a DIFFUSING grid before this change and gets a
+        // held one after. No shipped code, recipe or doc opens such a name; it is called out here and
+        // in the CHANGELOG because it is the only way any existing field could move.
         grid: (name) => {
             let g = grids.get(name);
             if (!g) {
-                const mode = name.startsWith('wave') ? 'wave' : name.startsWith('memory') ? 'memory' : 'diffuse';
+                const mode = name.startsWith('wave')
+                    ? 'wave'
+                    : name.startsWith('memory')
+                        ? 'memory'
+                        : name.startsWith('potential:')
+                            ? 'held'
+                            : 'diffuse';
                 g = new ScalarGridImpl(W, H, mode);
                 grids.set(name, g);
             }
@@ -1005,10 +977,12 @@ export function createField(canvas, opts = {}) {
         const scanned = scanBodies(host.root);
         // merge event-registered shadow-DOM hosts (deduped — a light-DOM host that also fires
         // a registration event is counted once). Registration is the canonical discovery path;
-        // light-DOM scanning is the compatibility fallback (shadow-dom.md §16).
+        // light-DOM scanning is the compatibility fallback (shadow-dom.md §16). The scan root is
+        // passed so a host registered with `scope: 'nearest'` / a `field` target (§17–§19) is built
+        // only by the field that owns it; a detail without those keys is built as before.
         if (shadow.size > 0) {
             const seen = new Set(scanned.map((b) => b.el));
-            bodies = scanned.concat(shadow.bodies(bodyFromElement).filter((b) => !seen.has(b.el)));
+            bodies = scanned.concat(shadow.bodies(bodyFromElement, host.root).filter((b) => !seen.has(b.el)));
         }
         else {
             bodies = scanned;
@@ -1653,6 +1627,11 @@ export function createField(canvas, opts = {}) {
         maxScroll = (host.scrollHeight?.() ?? H) - H || 1;
         for (const g of grids.values())
             g.resize(W, H); // keep field buffers viewport-sized
+        // resize() rebuilds the buffers and preserves NOTHING — every held raster is now all zeros, i.e.
+        // a flat potential. Invalidate so the next force pass refills it; `relief` would otherwise read a
+        // zero gradient (no transport at all) rather than stale data. The refill happens on the next PULL,
+        // which is necessarily after the scan() below has re-detected the bodies.
+        invalidatePotentials();
         if (cfg.heatmap) {
             if (!heatmap)
                 heatmap = new Heatmap(W, H);
@@ -3023,7 +3002,18 @@ export function createField(canvas, opts = {}) {
             resolvedWaveCenter = null;
         }
         updateWarpTargets(); // refresh warp relocate targets from paired bodies (§22.3) before the step
-        step({ store, bodies, env, forces: reg.forces, conditions: reg.conditions, waves, waveStyle: cfg.waveStyle, waveCenter: resolvedWaveCenter, separation: cfg.separation });
+        // `Env.potential` follows the `fieldAt?` / `accum?` precedent: an opt-in service, present only
+        // while some body actually declares `relief`. A field that never declares one — INCLUDING every
+        // field whose host called `addField` — carries no such property, so `applyForce` never sees it and
+        // the default hot path is byte-identical. This is the "registration does not couple" guarantee the
+        // shipped docs make, enforced structurally rather than by a flag. Decided from the live body list
+        // each frame rather than at scan time, because `addBody` appends a programmatic body without a
+        // rescan — deciding in `scan()` would leave a programmatic `relief` body permanently uncoupled.
+        if (bodies.some((b) => b.tokens.includes('relief')))
+            env.potential = potentialAt;
+        else if (env.potential)
+            delete env.potential;
+        step({ store, bodies, env, forces: reg.forces, conditions: reg.conditions, waves, waveStyle: cfg.waveStyle, waveCenter: resolvedWaveCenter, separation: cfg.separation, restingMotion: cfg.restingMotion });
         // hover-focus (field.focusAt): hold the focused particle still and light it up — the dwell
         // affordance ("it stops and does something") before a click opens its record.
         if (focusP) {
@@ -3266,13 +3256,50 @@ export function createField(canvas, opts = {}) {
             const caps = new Set(viewOpts.capabilities ?? []);
             const redactions = (viewOpts.redactions ?? []).slice();
             const has = (c) => caps.has(c);
-            // If a future `budgets.agentRead` budget is 0, the agent surface is closed entirely: the most
-            // restricted view (empty caps → ids + shape only). SEAM: only the 0 boundary is wired today; the
-            // fractional 0<b<1 gradient (partial agent read) is DECLARED-not-yet-enforced (see FieldBudgets).
+            // `budgets.agentRead` is a CONSERVATION LAW on the agent surface (#915): `b` is the SHARE of the
+            // field's readable body population this view may consume. `b == null` or `b >= 1` is the whole
+            // field; `b <= 0` closes the surface entirely (ids + shape only); `0 < b < 1` grants a partial read.
             const agentReadOpen = () => {
                 const b = policy.budgets?.agentRead;
                 return b == null || b > 0;
             };
+            const agentReadShare = () => {
+                const b = policy.budgets?.agentRead;
+                return b == null ? 1 : b;
+            };
+            // Which bodies a partial read admits. The selection is DETERMINISTIC, STABLE PER BODY ID, and
+            // NOT POSITIONAL — each property is load-bearing, and the obvious implementations fail one:
+            //   · deterministic, because a random draw makes an agent read unreplayable, and record/replay
+            //     is a contract this engine keeps everywhere else (it threads a seeded `rng` for exactly this);
+            //   · stable, because a subset RESAMPLED each frame leaks the whole field to a patient reader —
+            //     the union of enough independent 10% samples is 100%. A budget that can be defeated by
+            //     calling `query()` in a loop is not a budget. This is the security core of the gate;
+            //   · not positional, because `take the first ceil(n·b)` leaks scan order, hands every agent the
+            //     same prefix, and makes the withheld tail identical for everyone.
+            // FNV-1a over the body id gives a fixed [0,1) coordinate per body; admit those under the share.
+            // The expected admitted count is n·b, not exactly n·b — that is inherent to a per-body stable
+            // rule, and the alternative (an exact count) is necessarily positional or unstable.
+            /**
+             * Narrow a reading to the admitted share. Edges are filtered to SURVIVING ENDPOINTS: a
+             * relationship or influence naming a withheld body is itself a disclosure of that body's id and
+             * existence, so an edge survives only when every body it names does. Field-wide `metrics` are
+             * aggregates over the whole field, not per-body readings, and are left to `read:metrics`.
+             */
+            const sampleBodies = (res, share) => {
+                if (!(share < 1))
+                    return res;
+                const kept = new Set();
+                for (const b of res.bodies)
+                    if (admitsShare(b.id, share))
+                        kept.add(b.id);
+                res.bodies = res.bodies.filter((b) => kept.has(b.id));
+                if (res.relationships)
+                    res.relationships = res.relationships.filter((r) => kept.has(r.from) && kept.has(r.to));
+                if (res.influences) {
+                    res.influences = res.influences.filter((i) => kept.has(i.source) && (i.target == null || kept.has(i.target)));
+                }
+                return res;
+            };
             const scopeQuery = (q = {}) => {
                 if (!agentReadOpen()) {
                     // closed budget → most-restricted reading: shape only, no metrics/relationships/influences.
@@ -3305,6 +3332,9 @@ export function createField(canvas, opts = {}) {
                     res.influences = [];
                 if (!has('read:projections'))
                     res.projections = [];
+                // #915: the fractional budget narrows the population AFTER capability scoping — tighten-only,
+                // and it composes with the caps rather than replacing them.
+                sampleBodies(res, agentReadShare());
                 return applyRedactions(res, redactions);
             };
             const scopeSnapshot = (snapOpts = {}) => {
@@ -3313,8 +3343,11 @@ export function createField(canvas, opts = {}) {
                     return applyRedactions(snap, redactions);
                 }
                 // read:body-data is the gate for opaque `data`: without it, force `includeData` off (tightens,
-                // never widens — even if a profile or explicit flag asked for it). Everything else composes with
-                // resolveSnapshotInclusion's TIGHTEST-wins rule + the field's own privacy policy downstream.
+                // never widens — even if a profile or explicit flag asked for it). read:diagnostics is the gate
+                // for the RAW PARTICLE POOL — the engine's own internal state, not a modelled reading of bodies /
+                // relationships / metrics — so without it `includeParticles` is forced off even under `profile:
+                // 'debug'`. Everything else composes with resolveSnapshotInclusion's TIGHTEST-wins rule + the
+                // field's own privacy policy downstream.
                 const scoped = { ...snapOpts };
                 if (!has('read:body-data'))
                     scoped.includeData = false;
@@ -3322,17 +3355,33 @@ export function createField(canvas, opts = {}) {
                     scoped.includeRelationships = false;
                 if (!has('read:influences'))
                     scoped.includeInfluences = false;
+                if (!has('read:diagnostics'))
+                    scoped.includeParticles = false;
                 const snap = handle.snapshot(scoped);
                 if (!has('read:projections'))
                     snap.projections = [];
+                // #915: the same share applies to a capture, or `snapshot()` would hand back the whole field
+                // that `query()` just withheld. The raw particle pool carries no body identity, so it has no
+                // stable key to sample by; it stays gated by `read:diagnostics` alone (documented boundary).
+                sampleBodies(snap, agentReadShare());
                 return applyRedactions(snap, redactions);
             };
             const view = {
                 get capabilities() { return Object.freeze([...caps]); },
                 get redactions() { return Object.freeze([...redactions]); },
                 query: scopeQuery,
-                snapshot: scopeSnapshot,
             };
+            // `snapshot` is present ONLY when granted — the facade's shape reflects the grant, exactly as
+            // `replay`/`focusState` do. read:snapshots gates the CAPTURE SURFACE, not a lane within a reading:
+            // the per-lane caps (body-data / relationships / influences / projections / diagnostics) narrow what
+            // a capture contains, this one decides whether a capture may be taken at all. Withholding it closes
+            // the call rather than returning an empty shell — an empty capture is indistinguishable from an
+            // empty field, and a silent-but-permissive-looking reading is the failure this gate exists to stop.
+            // `query()` stays available under the base grant, so a denied agent is never blinded, only barred
+            // from the portable, serializable, replayable artifact.
+            if (has('read:snapshots')) {
+                view.snapshot = scopeSnapshot;
+            }
             // `replay` is present ONLY when granted — the facade's shape reflects the capability.
             if (has('read:replay')) {
                 view.replay = (a, b, replayOpts) => handle.replay(a, b, replayOpts);
@@ -3512,6 +3561,14 @@ export function createField(canvas, opts = {}) {
                 attrs['data-angle'] = String(spec.angle);
             if (spec.color != null)
                 attrs['data-color'] = spec.color;
+            // the declared-potential channel (#443) — the programmatic mirror of data-potential, so a
+            // non-DOM host (a game, an agent runtime) can declare terrain-coupled matter through addBody.
+            if (spec.potential != null)
+                attrs['data-potential'] = spec.potential;
+            // the capture horizon (#1177) — the programmatic mirror of data-absorb, so a non-DOM host can
+            // size a sink's or a warp throat's radius without reaching past the public API.
+            if (spec.absorbR != null)
+                attrs['data-absorb'] = String(spec.absorbR);
             const toRect = () => {
                 const r = spec.rect();
                 return {
@@ -3810,10 +3867,21 @@ export function createField(canvas, opts = {}) {
         replay: (a, b, opts) => replayFieldSnapshots(a, b, opts),
         addField: (name, sampler) => {
             fieldChannels.set(name, sampler);
+            invalidatePotentials(); // a channel registered AFTER a `relief` body was declared must couple
             return {
                 name,
-                set: (next) => { fieldChannels.set(name, next); },
-                remove: () => { fieldChannels.delete(name); },
+                set: (next) => {
+                    fieldChannels.set(name, next);
+                    invalidatePotentials(); // the swap is live: the next force pass reads the NEW surface
+                },
+                remove: () => {
+                    fieldChannels.delete(name);
+                    // Drop the raster with the channel. Without this the held cells would outlive the channel
+                    // and `relief` would keep transporting matter down a terrain the host has withdrawn.
+                    grids.delete(potentialKey(name));
+                    potentialStamp.delete(potentialKey(name));
+                    invalidatePotentials();
+                },
             };
         },
         sampleField: (name, x, y) => {