@fundamental-engine/core 0.9.1 → 0.9.3

package/dist/core/types.d.ts

@@ -27,6 +27,21 @@ export interface Vec2 {
     x: number;
     y: number;
 }
+/** A 3D vector — the optional z lane (a `depth > 0` field) and the accumulator's linear channel. */
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** An axis-aligned rectangle in field coordinates, `DOMRect`-shaped (x/y/width/height) so a caller
+ *  can pass `el.getBoundingClientRect()` straight into a {@link FieldQuery}'s `at`. (Distinct from the
+ *  engine-internal {@link Rect} in geometry, which is centre + half-extents.) */
+export interface FieldRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 /** A force id. Open string so the registry can be extended (§20), but the
  *  canonical set is enumerated in `config/forces.config.ts`. */
 export type Token = string;
@@ -60,6 +75,25 @@ export interface Particle {
      */
     z?: number;
     vz?: number;
+    /**
+     * OPTIONAL ORIENTATION LANE (substrate doc 04 §Step 6): `orient` is the particle's angle (radians,
+     * about the z axis) and `spin` its angular velocity. Undefined ⇒ no orientation ⇒ byte-identical to
+     * the spin-less engine — exactly the z-lane discipline. Only a `torque`-style force ever writes
+     * `spin`; the integrator advances `orient += spin · dt` (and damps) only when `spin` is defined.
+     * Renderers may ignore it; nothing in the base field depends on a particle facing a direction.
+     */
+    orient?: number;
+    spin?: number;
+    /**
+     * OPTIONAL ACCELERATION LANE (velocity-Verlet, #659): the previous step's acceleration
+     * a(t) = Δv/dt, stored so the next position full-step can take `x += v·dt + ½·a·dt²` and the
+     * velocity half-step can average `½·(a + a′)·dt`. Only the `'velocity-verlet'` integrator ever
+     * writes these; undefined ⇒ 0 ⇒ the default engine never materializes them (the z-lane
+     * discipline — byte-identical when unused).
+     */
+    ax?: number;
+    ay?: number;
+    az?: number;
     /** inertial mass — 1 = nominal (§21). */
     m: number;
     /** ∈ [0,1]; drives color (toward accent), size, and glow (§2.2). */
@@ -102,14 +136,64 @@ export interface AtomPayload {
     readonly weight?: number;
     readonly [key: string]: unknown;
 }
+/**
+ * Who owns a body's position (substrate doc 04 §body-authority). `anchored` (default) — the DOM/host
+ * rect is authoritative, re-measured each frame (today's behavior for all bodies). `kinematic` — the
+ * engine writes the body's visual transform while the DOM stays the rendered object (the shipped
+ * `data-move` / transform pattern). `dynamic` — the engine owns position/velocity: the body integrates
+ * under the net field each frame and moves (recoil / field-to-body coupling, doc 04 §Step 5). Anchored
+ * and kinematic behave exactly as before. (Literal momentum-recoil from the body's own emission, torque,
+ * and conservation are later refinements.)
+ */
+export type BodyAuthority = 'anchored' | 'kinematic' | 'dynamic';
+/**
+ * A body's FIRST-CLASS IDENTITY (substrate critical path). A stable, structured handle for referring to
+ * a body across frames, snapshots, diffs, and relationships — decoupled from object reference and from
+ * display text. `id` is the stable primary key: it MUST be unique within a field and MUST NOT change for
+ * the life of the body. The rest is optional metadata that lets a consumer group / route bodies (e.g. a
+ * bridge keying host meshes off `host`, or an agent filtering by `kind`).
+ *
+ * DOCTRINE — identity is NOT:
+ *   · display text (a heading's words are not its identity — they can change while identity holds);
+ *   · necessarily a DOM `id` (a DOM id is one *source* of a stable id, not the concept);
+ *   · an object reference (references don't survive a rescan or a serialize/replay round-trip).
+ * Snapshots, diffs, and relationships key on `identity.id`. When a body carries no supplied identity, the
+ * engine DERIVES a stable one deterministically (the element's DOM id, else a monotonic `body-N` counter —
+ * never `Math.random`, which is banned on the reproducible paths) so identity is always present and stable.
+ */
+export interface FieldBodyIdentity {
+    /** the stable primary key — unique within the field, constant for the body's life. Equals the reading's
+     *  top-level `id` (back-compat). Snapshot/diff/replay/relationships key on this. */
+    id: string;
+    /** optional grouping namespace (e.g. an app/module the body belongs to). Free-form; opaque to the engine. */
+    namespace?: string;
+    /** optional kind/type tag (e.g. `'card'`, `'heading'`, `'agent'`). Free-form; opaque to the engine. */
+    kind?: string;
+    /** optional host/owner tag (e.g. a renderer or view that owns the body's rendered object). Free-form. */
+    host?: string;
+}
 /**
  * A registered DOM element acting as a force source (§3.1). Parsed from
  * `data-*` attributes; the runtime fields are refreshed each scan/frame.
  */
 export interface Body {
     el: HTMLElement;
+    /** FIRST-CLASS IDENTITY (see {@link FieldBodyIdentity}). Supplied via `addBody({ identity })` or the
+     *  `identify` field option, else lazily DERIVED and cached the first time the body is keyed. Once
+     *  resolved it is stable for the body's life; snapshots/diff/replay/relationships key on `identity.id`. */
+    identity?: FieldBodyIdentity;
     /** space-joined force ids from `data-body` (they compose, §4). */
     tokens: Token[];
+    /** who owns this body's position (`data-authority`); default `'anchored'`. See {@link BodyAuthority}. */
+    authority?: BodyAuthority;
+    /** engine-owned position + velocity for a `dynamic` body (substrate doc 04 §Step 5 — recoil). Lazily
+     *  initialized from the body's first measured centre, then integrated under the net field each frame
+     *  and written back to `cx`/`cy` (so `measureBodies`' per-frame rect overwrite doesn't reset it).
+     *  Untouched for anchored/kinematic bodies. */
+    bx?: number;
+    by?: number;
+    bvx?: number;
+    bvy?: number;
     /** `tokens` split into `{ modifiers, forces, sources }` per the modifier contract
      *  (workover v0.3). The scanner fills it at parse time; the integrator memoizes it
      *  lazily for bodies built elsewhere (conformance, tests). Modifiers carry the
@@ -139,6 +223,10 @@ export interface Body {
      *  box, not its centre, so matter gathers in a shell around the shape (field-systems
      *  Stage C). Undefined ⇒ point source (the default). */
     shaped?: boolean;
+    /** `data-charge-gated` (opt-in, #711) — restrict `fieldflow` to *charged* matter (`charge ≠ 0`),
+     *  modelling magnetized plasma tied to the field line. Undefined/false ⇒ the default neutral-medium
+     *  advection (fieldflow transports ALL matter). Only read by the `fieldflow` force. */
+    chargeGated?: boolean;
     /** `data-species` — the species tag this body stamps on matter it *emits* (a `spawn` source),
      *  so multiple ecologies (pollen vs seeds vs spores) can share one field. Undefined ⇒ 0. */
     species?: number;
@@ -177,6 +265,10 @@ export interface Body {
     warpHas?: boolean;
     /** source mass M for `gravity`/`charge` (§20.10/§21). */
     M: number;
+    /** INERTIAL mass (substrate momentum, #872) — how hard the body is to *move*, distinct from `M` (how
+     *  strongly it *emits*). Undefined ⇒ nominal 1 ⇒ byte-identical. Populated (∝ rendered area, clamped)
+     *  only under `mass: 'area'`; the dynamic-body recoil integrator divides by `inertia ?? M`. */
+    inertia?: number;
     cx: number;
     cy: number;
     hw: number;
@@ -315,6 +407,89 @@ export interface Env {
      *  follows under `fieldflow`. Set by the integrator each step from the live bodies; absent
      *  in bare/probe envs, where a field-following force simply no-ops. */
     fieldAt?(x: number, y: number): Vec2;
+    /**
+     * OPT-IN impulse accumulator (substrate critical path, doc 04). When present, the
+     * integrator's central `applyForce` records each force's per-particle contribution here
+     * (net + per-force attribution) WITHOUT changing the integration math — the force still
+     * updates velocity as before. Absent on the default hot path (zero overhead, byte-identical
+     * behavior); a diagnostic / Field-Query probe sets it to read structured attribution. The
+     * shape is dimension-aware from day one so orientation/time/semantic channels are not painted
+     * into a corner, even though only `linear` is populated today. Read-only contract: setting
+     * `accum` never alters how matter moves. */
+    accum?: FieldImpulseAccumulator;
+    /** The integration scheme (substrate doc 04 §Step 3). `undefined`/`'legacy'` is the shipped
+     * semi-implicit Euler with per-frame decay (the default — unchanged). `'fixed'` is the opt-in
+     * fixed-timestep integrator: additive force impulses and the `FRICTION`/`HEAT_DECAY` decays scale
+     * with `dt`, so motion is frame-rate independent. At `dt === 1` (the reference rate, and every
+     * golden/conformance run) the two are byte-identical, so opting in never moves the golden.
+     * `'velocity-verlet'` (#659) is the opt-in second-order scheme: the position full-step uses the
+     * previous step's stored acceleration, the force pass evaluates a′ at the updated position, and
+     * the velocity takes the half-step average — see the integrator for the exact math and the
+     * velocity-dependence / kinematic-force approximations. It changes trajectories BY DESIGN once
+     * opted into; the default path never engages it. */
+    integrator?: IntegratorMode;
+    /** INTERNAL (velocity-Verlet only): set by the central `applyForce` when a *kinematic*
+     * (velocity-REPLACING) force actually changed the current particle's velocity, and reset by the
+     * integrator at the top of each particle's force pass. A reflection / relaunch / teleport is a
+     * discontinuity, not an acceleration — the Verlet half-step average is skipped for that particle
+     * that step. Never touched on the `'legacy'`/`'fixed'` paths. */
+    kinTouch?: boolean;
+}
+/** The integration scheme for the field (see {@link Env.integrator}). */
+export type IntegratorMode = 'legacy' | 'fixed' | 'velocity-verlet';
+/**
+ * A single force's contribution to one agent in one step, in one channel (substrate doc 04).
+ * The unit the diagnostics (`causality`/`prediction`), Field Query, and Causal Replay consume:
+ * "this matter moved 0.42 in linear x because of `attract`."
+ */
+export interface ForceAttribution {
+    /** the contributing force token (`Force.token`). */
+    force: Token;
+    /** which channel the contribution lands in. Only `linear` is populated today. */
+    channel: 'linear' | 'angular' | 'thermal' | 'temporal' | 'semantic' | 'constraint';
+    /** the contribution value — a `{x,y,z}` Δv for `linear`; a scalar for `thermal`. */
+    contribution: {
+        x: number;
+        y: number;
+        z: number;
+    } | number;
+    /** dimensions this force couples, if any (the coupling passport, doc 04 / dimensional-coupling). */
+    couplesDimensions?: string[];
+}
+/**
+ * A dimension-aware impulse accumulator (substrate doc 04). Collects per-force contributions for
+ * one agent so cause can be attributed before/independent of integration. `linear` is the running
+ * net Δv; `attribution` is the per-force breakdown. The optional channels (`angular`/`thermal`/
+ * `temporal`/`semantic`) are declared now so the contract does not assume all force is `vx/vy` —
+ * they are not populated until those dimensions are restored.
+ */
+export interface FieldImpulseAccumulator {
+    /** running net linear Δv (x/y, plus z when the lane is engaged). */
+    linear: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** angular Δω contribution (θx/θy/θz) — populated when a force writes `Particle.spin` (doc 04 §Step 6). */
+    angular?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** thermal (heat) contribution — populated when a force changes `Particle.heat` (doc 04 §Step 6). */
+    thermal?: number;
+    /** temporal contribution (delay/decay/phase) — `decay` populated when a force changes mortal matter's
+     *  `Particle.age` (frames-to-live); delay/phase reserved (doc 04 §Step 6). */
+    temporal?: {
+        delay?: number;
+        decay?: number;
+        phase?: number;
+    };
+    /** semantic-channel contributions (attention/confidence/memory) — `attention` populated with the body's
+     *  conserved-attention multiplier (`Body.attn`) when active; confidence/memory reserved (doc 04 §Step 6). */
+    semantic?: Record<string, number>;
+    /** per-force breakdown — preserves explainability (Paper 31 §6). */
+    attribution: ForceAttribution[];
 }
 /**
  * A force module (§4). The engine owns the loop and everything conserved; a
@@ -410,6 +585,53 @@ export type ConditionRegistry = Record<string, Condition>;
 export type OverlayMode = 'off' | 'streamlines' | 'force-vectors' | 'field-lines' | 'grid' | 'temperature' | 'energy' | 'path' | 'data';
 /** One reading, or an additive stack of readings, for `setOverlay` / `FieldOptions.overlay`. */
 export type OverlayInput = OverlayMode | readonly OverlayMode[];
+/**
+ * Consumable field-resource budgets — upper bounds a host/session/user/app sets on what the field is
+ * PERMITTED to spend, distinct from what doctrine *allows* (that is governance — static lint). Each is
+ * optional; an unset budget means "unbounded / engine default". Values are normalized `0..1` unless the
+ * one-line note says otherwise. Carried on {@link FieldPolicy.budgets}.
+ *
+ * WIRED today: `motion` (folds into the effective motion allowance alongside reduced-motion + perf
+ * pressure) and `privacy` (gates body `data` in snapshots). The rest are DECLARED-not-yet-enforced —
+ * accepted and carried on the policy for host/tooling introspection, wired as their consumers land.
+ */
+export interface FieldBudgets {
+    /** WIRED. `0..1` cap on how much motion the field may express; `0` behaves as reduced-motion (frozen). */
+    motion?: number;
+    /** DECLARED. `0..1` cap on applied force magnitude — the share of the impulse budget matter may absorb. */
+    force?: number;
+    /** DECLARED. `0..1` cap on conserved-attention spend (§2.4) — the finite focus budget. */
+    attention?: number;
+    /** DECLARED. `0..1` cap on thermal/heat accumulation the field may carry. */
+    thermal?: number;
+    /** DECLARED. `0..1` cap on render cost the field may spend (draw layers / fill). */
+    render?: number;
+    /** WIRED. `0..1` privacy budget; below the `PRIVACY_DATA_THRESHOLD` (0.5) snapshots withhold body `data`. */
+    privacy?: number;
+    /** DECLARED. `0..1` accessibility floor — the minimum non-motion legibility the field must preserve. */
+    accessibility?: number;
+    /** DECLARED. `0..1` cap on how much field state agent readers (query/snapshot/agent-json) may consume. */
+    agentRead?: number;
+}
+/**
+ * Runtime FIELD POLICY — what THIS host / session / user / app PERMITS, evaluated live. Distinct lane
+ * from GOVERNANCE (what doctrine allows — static lint): policy can only tighten, never loosen, the
+ * accessibility floor (reduced-motion always wins; a policy can lower motion but never raise it above
+ * what the host/user reduced-motion state allows). Set at creation via {@link FieldOptions.policy} and
+ * live via {@link FieldHandle.setPolicy}; read via {@link FieldHandle.policy}. Purely additive — a field
+ * with no policy behaves exactly as before.
+ */
+export interface FieldPolicy {
+    /** permit body `data` to appear in snapshots (default: fall through to `FieldSnapshotOptions.includeData`). */
+    allowBodyDataInSnapshots?: boolean;
+    /** permit motion-expressing projections/animation at all; `false` pins the effective motion budget to 0. */
+    allowMotionProjection?: boolean;
+    /** `0..1` host/session cap on motion; folded (via `min`) with reduced-motion + perf pressure into the
+     *  effective motion allowance the integrator/easing path reads. Reduced-motion can only lower it. */
+    maxMotionBudget?: number;
+    /** consumable-resource budgets (see {@link FieldBudgets}). */
+    budgets?: Partial<FieldBudgets>;
+}
 export interface FieldOptions {
     /** travelling accent color (§9). */
     accent?: string;
@@ -423,8 +645,15 @@ export interface FieldOptions {
      * render projects z as a size/alpha recession. Purely additive: no API requires z.
      */
     depth?: number;
-    /** draw the background Currents (§24); default true. Set false for the bare
-     *  free-particle field with no carrier waves. */
+    /** the integration scheme (substrate doc 04 §Step 3); default `'legacy'`. `'fixed'` opts into the
+     *  frame-rate-independent fixed-timestep integrator (additive impulses and decay scale with `dt`);
+     *  identical to legacy at the reference frame rate. `'velocity-verlet'` (#659) opts into the
+     *  second-order velocity-Verlet scheme (higher positional accuracy; trajectories differ by
+     *  design). See {@link Env.integrator}. */
+    integrator?: IntegratorMode;
+    /** draw the background Currents (§24); default **false** (opt-in, #979 — the signals-first
+     *  companion to `render: 'none'`). A bare field has no carrier waves; set true for the ambient
+     *  resting structure + the bound shimmer reservoir. */
     waves?: boolean;
     /** wave layout style: `'linear'` (default horizontal lines) or `'circular'` (concentric orbits around a center). */
     waveStyle?: 'linear' | 'circular';
@@ -451,13 +680,87 @@ export interface FieldOptions {
      *  dots), 'streamlines' (draw the force field itself — diagnostic, REPLACES the dots),
      *  'flow' (the dots AND the streamlines drawn together in the one underlay canvas —
      *  particles drifting along the visible flow, with no separate front surface and no
-     *  `mix-blend`, so it stays a single cheap layer). */
-    render?: 'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none';
-    /** first-class mass (§21.3): when true, particle mass ∝ size and body forces
-     *  accelerate by `a = F/m` (heavier matter moves less). Default false (unit mass). */
+     *  `mix-blend`, so it stays a single cheap layer), 'knockout' (figure-ground inversion:
+     *  an accent field wash with matter punched out as negative space — clip the canvas to
+     *  type with a host CSS mask for the field-inside-letters treatment, #667), 'redshift'
+     *  (dots tinted by spectral shift — Doppler from radial velocity + gravitational red
+     *  near body wells, #668), 'blackbody' (dots tinted by energy on a thermal ramp, ember
+     *  → white → blue-white, #669), 'depth' (the z lane made visible: far-to-near painter's
+     *  sorting, perspective parallax, defocus with distance — pairs with `depth > 0`, #670). */
+    render?: 'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'knockout' | 'redshift' | 'blackbody' | 'depth' | 'none';
+    /**
+     * DECLARED render reference point (Wallpaper Rule, #975): the center of the cool→warm heat
+     * vignette the `dots`/`depth` swarm is tinted against — a body far from this point reads warm,
+     * a body near it reads cool. Given as viewport FRACTIONS `{ x, y }` ∈ [0,1] (resolved to pixels
+     * against the live canvas each frame, so it tracks resize). Formerly a hardcoded `(W/2, H·0.4)`
+     * painted into the draw path (a content-independent "gray debt"): the default `{ x: 0.5, y: 0.4 }`
+     * reproduces it exactly, so the default render is byte-identical. Only affects the `dots`/`depth`
+     * render modes. **Experimental.** */
+    heatCenter?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * DECLARED render reference point (Wallpaper Rule, #975): the OBSERVER the `redshift` mode
+     * measures each particle's radial velocity against — receding matter reddens, approaching matter
+     * blues, at-rest at the observer. Given as viewport FRACTIONS `{ x, y }` ∈ [0,1] (resolved to
+     * pixels against the live canvas each frame). Formerly a hardcoded `(W/2, H/2)` (a "gray debt"):
+     * the default `{ x: 0.5, y: 0.5 }` reproduces it exactly, so the `redshift` render is byte-identical.
+     * Only affects the `redshift` render mode. **Experimental.** */
+    redshiftObserver?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * DECLARED render reference point (Wallpaper Rule, #975): the perspective focal length (in CSS px)
+     * of the `depth` mode's camera — the size/parallax recession the z lane is projected through. A
+     * larger focal flattens the perspective (a longer lens); a smaller one exaggerates it. Formerly a
+     * hardcoded `FOCAL = 480` (a "gray debt"): the default `480` reproduces it exactly, so the `depth`
+     * render is byte-identical. Only affects the `depth` render mode (pairs with `depth > 0`).
+     * **Experimental.** */
+    depthFocal?: number;
+    /**
+     * DECLARED page-layout reference (Wallpaper Rule, #975): how the density `heatmap` glow fades out
+     * as the page scrolls past the hero. `start` is the scroll position (in VIEWPORTS, `scrollY / H`)
+     * at which the fade begins, `span` is how many viewports it takes to reach fully transparent — the
+     * layer is full above `start·H` and gone by `(start + span)·H`. Formerly a hardcoded
+     * `(1.15 - scrollY/H)/0.85` baked into a core draw path — a "content = first viewport" assumption
+     * (a "gray debt"): the default `{ start: 0.3, span: 0.85 }` reproduces it exactly (the historical
+     * curve is full through `1.15 - 0.85 = 0.3` viewports and gone by `1.15`), so the heatmap glow is
+     * byte-identical. Set a large `span` to disable the scroll fade. Only affects the density `heatmap`
+     * layer. **Experimental.** */
+    heatmapFade?: {
+        start: number;
+        span: number;
+    };
+    /** first-class mass (§21.3): when true, particle mass ∝ size and body forces accelerate by `a = F/m`
+     *  (heavier matter moves less). Also gives DYNAMIC bodies inertial mass ∝ rendered area (#872), so a
+     *  big heading recoils slowly and a small tag snaps. Default false (unit mass, byte-identical). */
     mass?: boolean;
+    /** Newtonian own-emission reaction (substrate momentum, #873): when true, a DYNAMIC body feels the
+     *  equal-and-opposite of the net impulse it imparts to nearby matter (a directional emitter recoils
+     *  like a rocket; reciprocity closes through *motion*, not just feedback). Best paired with `mass`
+     *  (recoil ÷ inertial mass). Default false ⇒ byte-identical. **Experimental.** */
+    reaction?: boolean;
     /** strength of particle-to-particle separation/repulsion force (0 to 1, default 0). */
     separation?: number;
+    /**
+     * DECLARED ambient bias (Wallpaper Rule, #978): the resting `ambient` formation's tangential
+     * swirl injected into `attract` bodies (`Formation.orbit`) — the gentle spiral free matter
+     * traces around a well at rest. Formerly a hardcoded `0.1` painted into the default formation
+     * preset (a "gray debt": a content-independent constant inside an honest feature). Now a
+     * documented, opt-in dial with the historical value as its default, so behavior is unchanged;
+     * set `0` for a purely radial resting attract (no spiral), or raise it for a stronger orbit.
+     * Applies to the `ambient` formation only (the section formations keep their authored presets);
+     * `<field-root ambient-orbit>`. Default `0.1`. */
+    ambientOrbit?: number;
+    /**
+     * DECLARED ambient bias (Wallpaper Rule, #978): the resting `ambient` formation's `wander`
+     * term — the per-particle drift that keeps resting matter alive rather than frozen. Formerly a
+     * hardcoded `1.0` in the default formation preset. Now a documented, opt-in dial defaulting to
+     * the historical value (behavior unchanged); lower it for a calmer rest, `0` to still the drift.
+     * Applies to the `ambient` formation only; `<field-root ambient-wander>`. Default `1.0`. */
+    ambientWander?: number;
     /** color template for the travelling accent (§9): a built-in name
      *  (`'ours'` · `'heatmap'` · `'infrared'` · `'spectrum'`) or custom hex stops. */
     palette?: string | readonly string[];
@@ -493,6 +796,17 @@ export interface FieldOptions {
      * provides the canvas, core only draws. Default unset → no overlay surface.
      */
     overlayCanvas?: HTMLCanvasElement;
+    /**
+     * Field Surfaces (overlay placement, #676): a lazy alternative to `overlayCanvas`. When no
+     * `overlayCanvas` is bound, core calls this provider ONCE — the first time an overlay reading actually
+     * becomes active (a non-`off` `setOverlay`, or `setRender` leaving `'none'` with a reading already
+     * set) — to obtain the surface. This lets a host (e.g. `<field-root>`) defer creating its
+     * full-viewport, mix-blend light-DOM canvas until an overlay is switched on, so the common
+     * `overlay: off` path never puts a canvas into the compositing tree at boot. Return `null` to decline
+     * (stays surface-less). Ignored when `overlayCanvas` is set. Keeps core DOM-free — the host still owns
+     * the element and its CSS placement.
+     */
+    overlayCanvasProvider?: () => HTMLCanvasElement | null;
     /** initial overlay visualization mode (Field Surfaces); default `'off'`. */
     overlay?: OverlayInput;
     /**
@@ -538,6 +852,21 @@ export interface FieldOptions {
      * you; inject a custom host for a headless renderer / different document / tests.
      */
     host?: FieldHost;
+    /**
+     * Initial runtime {@link FieldPolicy} — what this host/session/user/app PERMITS (runtime rules),
+     * distinct from governance (what doctrine allows). Change it live with {@link FieldHandle.setPolicy}.
+     * Purely additive — omit for the unbounded default. */
+    policy?: FieldPolicy;
+    /**
+     * FIRST-CLASS IDENTITY resolver (substrate critical path): derive a {@link FieldBodyIdentity} for a
+     * DOM-scanned body from its element. Called once per body, the first time the body is keyed; the
+     * returned identity is cached and used for query/snapshot/diff/replay/relationship keying. Return
+     * `undefined` (or omit the option) to fall back to the default derivation (the element's DOM `id`,
+     * else a monotonic `body-N`). The `id` a resolver returns MUST be unique within the field and stable
+     * for the body's life. Programmatic `addBody({ identity })` overrides this. Purely additive — a field
+     * with no `identify` behaves exactly as before.
+     */
+    identify?: (el: HTMLElement) => FieldBodyIdentity | undefined;
 }
 /** Per-element feedback values the engine produces each frame (Phase D3 seam). */
 export interface FeedbackChannels {
@@ -545,7 +874,7 @@ export interface FeedbackChannels {
     density?: number;
     /** the ambient heatmap density at the body → `--field-heatmap-density`. */
     heatmapDensity?: number;
-    /** sink accretion fill ∈ [0,1] → `--load` / `--mass`. */
+    /** sink accretion fill ∈ [0,1] → `--load`. */
     load?: number;
     /** cross-boundary lit signal ∈ [0,1] → `--lit` + thresholded `field:lit` / `field:dim`. */
     lit?: number;
@@ -588,6 +917,13 @@ export interface AgentHandle {
 export interface BodySpec {
     /** the force ids this body emits (space-joined string or array), e.g. `'attract swirl'`. */
     tokens: string | readonly string[];
+    /** FIRST-CLASS IDENTITY for this programmatic body (see {@link FieldBodyIdentity}). Supply a stable
+     *  `id` (unique in the field) plus optional `namespace`/`kind`/`host`, so snapshots/diff/replay and a
+     *  bridge can reference this body by identity rather than the returned handle. A bare string is shorthand
+     *  for `{ id }`. Omitted ⇒ the engine derives a stable synthetic `body-N`. */
+    identity?: FieldBodyIdentity | string;
+    /** who owns this body's position; default `'anchored'`. See {@link BodyAuthority}. */
+    authority?: BodyAuthority;
     /** overall force magnitude (scales every token). */
     strength?: number;
     /** radius of influence, in field px. */
@@ -659,6 +995,387 @@ export interface EdgeView {
     /** whether the relationship was exercised this tick (its source body was salient). */
     active: boolean;
 }
+/** What a {@link FieldQuery} should return. Omitted ⇒ a sensible default (`bodies`, `metrics`,
+ *  `relationships`, plus `influences` when the query targets a point/region). */
+export type FieldQueryInclude = 'bodies' | 'metrics' | 'relationships' | 'influences';
+/** A user-defined interpretation lens over a query/snapshot reading (substrate query phase 2) — a
+ *  declarative scope, NOT an opinionated preset catalog: the caller supplies the lens, the field/`applyLens`
+ *  filters by it. Each clause is an allow-list; omitting a clause keeps everything in that dimension.
+ *  Pure metadata — a lens never changes field state. **EXPERIMENTAL.** */
+export interface FieldLens {
+    /** lens id, echoed onto the result as `FieldQueryResult.lens`. */
+    id: string;
+    label?: string;
+    /** keep only these metric keys (applied to global metrics + each body's metrics/dimensions). */
+    metrics?: readonly string[];
+    /** keep only influences in these accumulator channels (a missing `channel` counts as `'linear'`). */
+    channels?: readonly ForceAttribution['channel'][];
+    /** keep only bodies carrying at least one of these tokens. */
+    tokens?: readonly Token[];
+}
+/** A structured question put to the live field (read-only; never mutates state). */
+export interface FieldQuery {
+    /** where to look: a point (`{x, y}`) or a rectangle (`{x, y, width, height}` — `DOMRect`-shaped).
+     *  Omitted ⇒ a global query over the whole field. */
+    at?: Vec2 | FieldRect;
+    /** for a point `at`, the query radius in field px (default 240). Ignored for a rect or global query. */
+    radius?: number;
+    /** which sections to include; omitted ⇒ the default set (see {@link FieldQueryInclude}). */
+    include?: readonly FieldQueryInclude[];
+    /** interpret the result through a lens (substrate query phase 2) — scopes metrics/influences/bodies.
+     *  Equivalent to calling `applyLens(result, lens)` on the answer. **EXPERIMENTAL.** */
+    lens?: FieldLens;
+}
+/** A body as seen by a query — identity, box, active tokens, and its measured metrics/dimensions. */
+export interface FieldBodyReading {
+    /** stable id: the element's `id` when present, else a per-field synthetic (`body-N`). Equals
+     *  `identity.id`. Kept as the top-level field for back-compat; new consumers may read `identity`. */
+    id: string;
+    /** the body's resolved FIRST-CLASS IDENTITY (see {@link FieldBodyIdentity}). `identity.id === id`;
+     *  `namespace`/`kind`/`host` carry any supplied structured metadata. Always present. */
+    identity: FieldBodyIdentity;
+    /** the body's box in field coordinates, when measured. */
+    rect?: FieldRect;
+    /** the composed force ids (the `data-body` tokens). */
+    tokens: Token[];
+    /** scalar readings (lane: metric) — e.g. `density`, `load`, `attention`, `engaged`. */
+    metrics: Record<string, number>;
+    /** measured field dimensions (lane: metric) — e.g. `entropy`, `coherence`, `temperature`. */
+    dimensions: Record<string, number>;
+    /** the Field Formation(s) biasing this body right now (the field's active formation). */
+    activeFormations?: string[];
+    /** who owns this body's position (see {@link BodyAuthority}); `'anchored'` by default. */
+    authority?: BodyAuthority;
+}
+/** A relationship (edge) as seen by a query. */
+export interface FieldRelationshipReading {
+    /** source / target body ids (see {@link FieldBodyReading.id}). */
+    from: string;
+    to: string;
+    /** the relationship kind (`'related'` by default). */
+    type: string;
+    /** active coupling ∈ [0,1]. */
+    strength: number;
+    /** slow accumulated familiarity ∈ [0,1]. */
+    memory?: number;
+    /** exercised this tick. */
+    active: boolean;
+    /** whether the edge carried causal influence this frame (today: equal to `active`). */
+    causal: boolean;
+}
+/** A single force's influence at the query point/region — which body's which force contributed how
+ *  much (from the impulse accumulator; lane: force). */
+export interface FieldInfluenceReading {
+    /** the body whose force exerted the influence. */
+    source: string;
+    /** the influenced target, when the query has one (the query point/region). */
+    target?: string;
+    /** the contributing force token. */
+    force: Token;
+    /** which accumulator channel this contribution is in (`'linear'` Δv, `'thermal'` heat, …). Default
+     *  `'linear'` for back-compat with readers written before the thermal channel (doc 04 §Step 6). */
+    channel?: ForceAttribution['channel'];
+    /** the contribution — a Δv vector for `'linear'`, a scalar heat delta for `'thermal'`. */
+    contribution: number | Vec2 | Vec3;
+    /** optional human-readable note (lane: diagnostic). */
+    reason?: string;
+}
+/** The structured answer to a {@link FieldQuery}. Plain data; safe to serialize. */
+export interface FieldQueryResult {
+    /** the query that produced this reading (echoed back). */
+    query: FieldQuery;
+    /** the frame this reading was taken on. */
+    frame: number;
+    /** the field clock at read time. */
+    time: number;
+    /** the resolved region (for a point/rect query). */
+    region?: FieldRect;
+    bodies: FieldBodyReading[];
+    metrics: Record<string, number>;
+    relationships: FieldRelationshipReading[];
+    influences: FieldInfluenceReading[];
+    /** the projections registered on the field (substrate 05) — metadata only; read-only. */
+    projections: FieldProjectionInfo[];
+    /** the lens id this reading was scoped through, when a `lens` was supplied (substrate query phase 2). */
+    lens?: string;
+}
+/**
+ * A named **snapshot profile** — a concrete inclusion preset for {@link FieldHandle.snapshot}, resolved
+ * to the TIGHTEST (most private) combination of its base inclusions, any explicit `include*` flags, and
+ * the runtime {@link FieldPolicy} privacy budget. A profile can only tighten a call; it never widens past
+ * what policy allows.
+ *
+ * - `'debug'` — everything: particles, relationships, influences, and body `data` (still gated by policy).
+ * - `'agent'` — the Software-Agent read: stable ids + metrics + relationships + influence attribution +
+ *   projections, but NO opaque body `data` (raw/user-identifying payloads withheld regardless of `includeData`).
+ * - `'bug-report'` — structural + versions (relationships + influences), no user data.
+ * - `'public'` — minimal: ids + shape (bodies/metrics/projections), no relationships, influences, or data.
+ */
+export type SnapshotProfile = 'debug' | 'agent' | 'bug-report' | 'public';
+/** Options for {@link FieldHandle.snapshot}. */
+export interface FieldSnapshotOptions {
+    /** include the raw particle pool (heavier; off by default for lightweight exports). */
+    includeParticles?: boolean;
+    /** include the relationship (edge) graph (default true). */
+    includeRelationships?: boolean;
+    /** include each body's opaque `data` record (default false — privacy-preserving). */
+    includeData?: boolean;
+    /** include per-body force attribution (each body's own forces at its centre, via the impulse
+     *  accumulator) so a later `replay()` can derive `cause: 'force'` steps. Off by default. */
+    includeInfluences?: boolean;
+    /** apply a named {@link SnapshotProfile} preset. Composes with the explicit `include*` flags and the
+     *  {@link FieldPolicy} privacy budget, always resolving to the TIGHTEST (most private) result — a
+     *  profile can never widen past what policy or an explicit deny allows. */
+    profile?: SnapshotProfile;
+}
+/**
+ * A scoped read CAPABILITY an {@link AgentFieldView} grants. Each names one dimension of the field's
+ * read surface; a capability set is an allow-list — a dimension the caps don't include is stripped from
+ * every reading (it tightens, never widens). Read-only throughout — there is no write capability, because
+ * *agent-readable is not agent-writable* (see `docs/canonical/agent-consumption-model.md`).
+ */
+export type AgentCapability = 'read:metrics' | 'read:relationships' | 'read:influences' | 'read:snapshots' | 'read:body-data' | 'read:projections' | 'read:diagnostics' | 'read:replay';
+/** Options for {@link FieldHandle.forAgent} — the capability grant + optional redaction list. */
+export interface AgentViewOptions {
+    /** the capabilities this agent view grants. An allow-list: any dimension not listed is stripped from
+     *  every reading. An empty set yields the most-restricted view (ids + shape only). */
+    capabilities: AgentCapability[];
+    /** dotted paths stripped from every reading AFTER capability scoping (e.g. `'body.data'`, `'host.user'`,
+     *  `'metrics.temperature'`). `body.*` / `relationship.*` / `influence.*` / `projection.*` prefixes address
+     *  the per-entry shape of each list; a bare top-level key addresses the result/snapshot itself. */
+    redactions?: string[];
+}
+/**
+ * A READ-ONLY facade over a field, scoped to a set of {@link AgentCapability}s — the surface a Software
+ * Agent uses to read the field safely. It exposes ONLY scoped `query()` / `snapshot()` (and `replay()`
+ * when `read:replay` is granted). It has NO mutation methods — no `applyForce`, no `addBody`, no
+ * `setPolicy` — enforced by the facade's very shape: *agent-readable is not agent-writable*. Every
+ * reading is tightened to the granted capabilities, then any `redactions` paths are stripped, and the
+ * result can never widen past what the field's {@link FieldPolicy} already permits.
+ */
+export interface AgentFieldView {
+    /** the granted capabilities (a frozen copy). */
+    readonly capabilities: readonly AgentCapability[];
+    /** the redaction paths (a frozen copy). */
+    readonly redactions: readonly string[];
+    /** a capability-scoped, redacted {@link FieldQueryResult}. Dimensions the caps don't grant are absent
+     *  (no `read:influences` → no influences; no `read:relationships` → no relationships; etc.). */
+    query(q?: FieldQuery): FieldQueryResult;
+    /** a capability-scoped, redacted {@link FieldSnapshot}. Body `data` is withheld unless `read:body-data`
+     *  is granted (and policy permits it); a `profile`/`include*` request can only tighten from here. */
+    snapshot(opts?: FieldSnapshotOptions): FieldSnapshot;
+    /** narrate how the field changed between two snapshots — present ONLY when `read:replay` is granted
+     *  (otherwise `undefined`, so the facade's shape reflects the grant). */
+    replay?(a: FieldSnapshot, b: FieldSnapshot, opts?: ReplayOptions): CausalReplay;
+}
+/** A body captured in a {@link FieldSnapshot}. */
+export interface FieldBodySnapshot {
+    /** stable id — equals `identity.id`; snapshot/diff/replay key on it. */
+    id: string;
+    /** the body's resolved FIRST-CLASS IDENTITY (see {@link FieldBodyIdentity}). Always present. */
+    identity: FieldBodyIdentity;
+    /** who owns this body's position (see {@link BodyAuthority}); `'anchored'` by default. */
+    authority?: BodyAuthority;
+    /** the body's box in field coordinates (anchored bodies). */
+    rect?: FieldRect;
+    /** the body's centre in field coordinates (z = 0 for an anchored body). */
+    position?: Vec3;
+    tokens: Token[];
+    metrics: Record<string, number>;
+    dimensions: Record<string, number>;
+    /** the body's opaque record, only when `includeData` was set. */
+    data?: unknown;
+}
+/** One particle captured in a {@link FieldSnapshot} (only when `includeParticles`). */
+export interface FieldParticleSnapshot {
+    x: number;
+    y: number;
+    z: number;
+    heat: number;
+    size: number;
+}
+/** A portable capture of field state at a moment in time — inspect, compare, test, export, or hand to
+ *  an agent. Plain data; safe to serialize. Format is versioned via {@link FieldSnapshot.version}. */
+export interface FieldSnapshot {
+    /** a per-field unique id (`snap-<frame>-<n>`). */
+    id: string;
+    /** the field clock at capture (`env.t`). */
+    createdAt: number;
+    /** the frame captured. */
+    frame: number;
+    /** the engine build (`FIELD_VERSION`) — the snapshot-format version. */
+    version: string;
+    /** the active Field Formation id(s) at capture. */
+    formations: string[];
+    bodies: FieldBodySnapshot[];
+    relationships: FieldRelationshipReading[];
+    metrics: Record<string, number>;
+    /** per-body force attribution at capture (only when `includeInfluences`) — each body's own forces at
+     *  its centre, by channel; lets `replay()` derive `cause: 'force'` steps. */
+    influences?: FieldInfluenceReading[];
+    /** the projections registered on the field at capture (substrate 05) — metadata only. */
+    projections: FieldProjectionInfo[];
+    particles?: FieldParticleSnapshot[];
+}
+/** A change to one body between two snapshots. */
+export interface BodyChange {
+    id: string;
+    kind: 'added' | 'removed' | 'changed';
+    /** per-metric `{ from, to }` for the metrics that changed (kind `'changed'`). */
+    metrics?: Record<string, {
+        from: number;
+        to: number;
+    }>;
+}
+/** A change to one relationship between two snapshots. */
+export interface RelationshipChange {
+    from: string;
+    to: string;
+    type: string;
+    kind: 'added' | 'removed' | 'changed';
+    strength?: {
+        from: number;
+        to: number;
+    };
+    active?: {
+        from: boolean;
+        to: boolean;
+    };
+}
+/** A change to one field-level metric between two snapshots. */
+export interface MetricChange {
+    key: string;
+    from: number;
+    to: number;
+}
+/** A Field Formation that activated or deactivated between two snapshots. */
+export interface FormationChange {
+    id: string;
+    kind: 'activated' | 'deactivated';
+}
+/** The structured comparison of two {@link FieldSnapshot}s — what changed in the field, by lane. */
+export interface FieldDiff {
+    /** the `id`s of the two snapshots compared. */
+    from: string;
+    to: string;
+    bodyChanges: BodyChange[];
+    relationshipChanges: RelationshipChange[];
+    metricChanges: MetricChange[];
+    formationChanges: FormationChange[];
+}
+/** The kinds of output surface a {@link FieldProjection} can target. */
+export type FieldProjectionSurface = 'css' | 'dom-attribute' | 'svg' | 'canvas' | 'typography' | 'annotation' | 'sound' | 'haptic' | 'native' | 'spatial' | 'agent-json';
+/** Where a projection writes — a minimal, DOM-shaped sink (an element's style / attributes), but open
+ *  so non-DOM surfaces (native, agent-json) can pass their own target. */
+export interface FieldProjectionTarget {
+    style?: {
+        setProperty(key: string, value: string): void;
+    };
+    setAttribute?(key: string, value: string): void;
+    [key: string]: unknown;
+}
+/** A named mapping from field state to an output surface. `apply` is the (optional) writer; the rest is
+ *  declarative metadata governance + tooling read. A projection must NOT change field state. */
+export interface FieldProjection {
+    id: string;
+    label: string;
+    /** the field channels this projection reads (e.g. `['density','confidence']`). */
+    channels: string[];
+    /** the surface(s) it writes to. */
+    surfaces: FieldProjectionSurface[];
+    /** the non-motion equivalent, for `prefers-reduced-motion` (governance: motion must translate). */
+    reducedMotionEquivalent?: string;
+    /** the accessibility equivalent — an alternate projection of the same state, not a fallback. */
+    accessibilityEquivalent?: string;
+    /** write the reading onto the target (read-only w.r.t. the field). */
+    apply?(reading: Record<string, number>, target: FieldProjectionTarget): void;
+}
+/** A live reading source for an auto-applied projection — called once per write phase to produce the
+ *  reading handed to the projection's `apply`. The field never reads it for simulation. */
+export type ProjectionSource = () => Record<string, number>;
+/** A {@link FieldProjectionTarget} for the `agent-json` surface: it captures the last reading written to
+ *  it as a plain object, serializable for agent / tooling consumption. Build one with `agentJsonTarget()`
+ *  and pair it with `agentJsonProjection()`. **EXPERIMENTAL.** */
+export interface AgentJsonTarget extends FieldProjectionTarget {
+    /** receive a reading (called by the projection's `apply`). */
+    receive(reading: Record<string, number>): void;
+    /** the last received reading, or null before the first write. */
+    value(): Record<string, number> | null;
+    /** the last received reading serialized as JSON (`"null"` before the first write). */
+    json(): string;
+}
+/** Serializable metadata about a registered projection (no `apply`) — what `query()`/`snapshot()` and
+ *  governance tooling read. */
+export interface FieldProjectionInfo {
+    id: string;
+    label: string;
+    channels: string[];
+    surfaces: FieldProjectionSurface[];
+    reducedMotionEquivalent?: string;
+    accessibilityEquivalent?: string;
+}
+/** The field's projection registry ({@link FieldHandle.projections}) — register named projections and
+ *  apply them. Read/output only; registering a projection never changes how matter moves. */
+export interface ProjectionRegistry {
+    /** register a projection (replacing any with the same id); returns an unregister fn. */
+    register(projection: FieldProjection): () => void;
+    /** remove a registered projection by id. */
+    unregister(id: string): void;
+    /** the full projection (incl. `apply`) for an id, or undefined. */
+    get(id: string): FieldProjection | undefined;
+    /** serializable metadata for every registered projection. */
+    list(): FieldProjectionInfo[];
+    /** apply a registered projection's writer to a target (no-op if the id/`apply` is absent). */
+    apply(id: string, reading: Record<string, number>, target: FieldProjectionTarget): void;
+    /** bind a registered projection to a target + a live reading source — the field auto-applies it once
+     *  per write phase (after feedback), read-only w.r.t. the field. Returns an unbind fn. Multiple
+     *  bindings (even of the same id) coexist; binding an unknown/`apply`-less id is inert. **EXPERIMENTAL.** */
+    bind(id: string, target: FieldProjectionTarget, source: ProjectionSource): () => void;
+    /** governance lint over the registered projections (substrate 05 §governance) — flags accessibility
+     *  gaps (a motion-capable projection with no reduced-motion equivalent; any projection with no
+     *  accessibility equivalent). Pure; the standalone `lintProjections` is also exported. */
+    lint(): GovernanceWarning[];
+}
+/** A governance lint finding. `rule` is a stable `field/...` id (see doc 05 §field-lint-rules). The
+ *  severity scale matches the visual `LintSeverity` (info / warning / error / fatal). */
+export interface GovernanceWarning {
+    rule: string;
+    severity: 'info' | 'warning' | 'error' | 'fatal';
+    /** the offending subject — e.g. a projection id. */
+    subject: string;
+    message: string;
+}
+/** The lane a {@link CausalReplayStep} belongs to. */
+export type CausalCause = 'force' | 'relationship' | 'metric' | 'formation' | 'measurement';
+/** Options for {@link FieldHandle.replay}. */
+export interface ReplayOptions {
+    /** restrict the replay to steps touching this body id (its metrics, or a relationship endpoint). */
+    focus?: string;
+}
+/** One narrated cause in a {@link CausalReplay}. */
+export interface CausalReplayStep {
+    frame: number;
+    time: number;
+    cause: CausalCause;
+    /** the body/edge the cause originates from (a body id, or a relationship's `from`). */
+    source?: string;
+    /** the affected target, when the cause is a relationship. */
+    target?: string;
+    /** a human-readable account of the change (lane: diagnostic). */
+    description: string;
+    /** the structured before/after behind the description (e.g. `{ from, to }`). */
+    contribution?: unknown;
+}
+/** An explanation of how the field changed between two snapshots — the ordered causal steps. Pure
+ *  (derived from the two snapshots); plain data, safe to serialize. */
+export interface CausalReplay {
+    /** the `id`s of the two snapshots replayed. */
+    from: string;
+    to: string;
+    /** the focus body id, if the replay was scoped to one. */
+    focus?: string;
+    steps: CausalReplayStep[];
+}
 /** A registered **field channel** (`FieldHandle.addField`) — an external scalar field sampled on the
  *  engine's read path. The open *input* analog of the render surfaces. */
 export interface FieldChannelHandle {
@@ -673,6 +1390,10 @@ export interface FieldChannelHandle {
 export interface FieldHandle {
     /** the running engine version (`FIELD_VERSION`) — which build this field is on. */
     readonly version: string;
+    /** the field's projection registry (substrate 05) — register named projections that reveal field
+     *  state on an output surface (CSS / annotation / agent-json / reduced-motion …). Read/output only:
+     *  a projection never changes how matter moves. See {@link ProjectionRegistry}. **EXPERIMENTAL.** */
+    readonly projections: ProjectionRegistry;
     /** (re)scan the document for `[data-body]` bodies after a layout change. */
     scan(): void;
     /** alias of `scan`. */
@@ -711,6 +1432,23 @@ export interface FieldHandle {
      *  quality. The platform runtime forwards the governor's tier automatically; call it directly for a
      *  custom quality policy. */
     setQualityTier(tier: number): void;
+    /** the field's current runtime {@link FieldPolicy} (a frozen copy). `{}` when none was set. */
+    readonly policy: FieldPolicy;
+    /** Replace the runtime {@link FieldPolicy} live — what this host/session/user/app PERMITS. This is a
+     *  REPLACE (not a merge): pass the full policy you want in effect (`{}` clears to the unbounded
+     *  default). Takes effect from the next frame. The motion budget it carries folds (via `min`) with
+     *  reduced-motion + perf pressure — reduced-motion always wins, so a policy can lower motion but never
+     *  raise it. The privacy budget gates body `data` in `snapshot()`. */
+    setPolicy(policy: FieldPolicy): void;
+    /**
+     * Derive a READ-ONLY {@link AgentFieldView} scoped to a set of {@link AgentCapability}s — the safe
+     * surface a Software Agent uses to read the field. The returned facade exposes ONLY scoped
+     * `query()` / `snapshot()` (and `replay()` when `read:replay` is granted); it has NO mutation methods.
+     * Readings are tightened to the granted capabilities, then any `redactions` paths are stripped, and the
+     * result can never widen past what the field's {@link FieldPolicy} already permits. Purely additive —
+     * `forAgent` reads the same live field; it does not fork or copy it.
+     */
+    forAgent(opts: AgentViewOptions): AgentFieldView;
     /**
      * Switch the underlay render mode (§20.6) live — the surface behind content. `'none'` is the
      * signals-only mode (§13.7 / #297): drawing stops from the next frame while the simulation and
@@ -718,7 +1456,7 @@ export interface FieldHandle {
      * backing store (the no-allocation guarantee belongs to fields CREATED with `render: 'none'`);
      * switching FROM `'none'` acquires the context lazily and sizes the backing store at that moment.
      */
-    setRender(mode: 'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'): void;
+    setRender(mode: 'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'knockout' | 'redshift' | 'blackbody' | 'depth' | 'none'): void;
     /**
      * Render field READINGS on the OVERLAY surface — in front of page content (Field Surfaces). Pairs
      * with `setRender` (the underlay); set both for an immersive look. No-op unless the field was created
@@ -786,6 +1524,22 @@ export interface FieldHandle {
      *  consumer: each edge's endpoint `data`, type, live `strength`/`memory`, and whether it's active this
      *  tick. Pure, read-only. Shipped-but-unfrozen. */
     readEdges(): ReadonlyArray<EdgeView>;
+    /** Ask the live field a structured question and get back plain, serializable data — bodies,
+     *  metrics, relationships, and per-force influence — for a point, a rect, or the whole field.
+     *  Read-only and render-agnostic (works headless). The substrate's agent-/tool-readable surface;
+     *  see {@link FieldQuery}. **EXPERIMENTAL** — not yet in the frozen API set. */
+    query(q?: FieldQuery): FieldQueryResult;
+    /** Capture *what the field is doing* right now — a portable, serializable {@link FieldSnapshot}
+     *  (bodies, metrics, relationships, active formations; optionally particles). Read-only; works
+     *  headless. Pair with {@link FieldHandle.diff} to compare two snapshots. **EXPERIMENTAL.** */
+    snapshot(opts?: FieldSnapshotOptions): FieldSnapshot;
+    /** Compare two snapshots and report what changed in the field — body, relationship, metric, and
+     *  formation changes. Pure (takes two snapshots; ignores live state). **EXPERIMENTAL.** */
+    diff(a: FieldSnapshot, b: FieldSnapshot): FieldDiff;
+    /** Explain how the field changed between two snapshots — an ordered, narrated sequence of causes
+     *  (formation activations, relationship shifts, body measurements/metrics). Pure (derived from the
+     *  two snapshots). Pass `{ focus }` to scope it to one body. **EXPERIMENTAL.** */
+    replay(a: FieldSnapshot, b: FieldSnapshot, opts?: ReplayOptions): CausalReplay;
     /**
      * Register a named **field channel** — a read-back substrate the host samples via `sampleField`; the
      * engine does not (yet) couple it into forces. The open *input* analog of the render surfaces