@fundamental-engine/core 0.9.2 → 0.9.4

package/dist/{core → engine}/types.d.ts

@@ -84,6 +84,16 @@ export interface Particle {
      */
     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). */
@@ -136,12 +146,111 @@ export interface AtomPayload {
  * 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;
+}
+/** Who directed a focus deposit. Open union so multi-agent tags ride along (e.g. `'agent:planner'`). */
+export type FocusSource = 'operator' | 'agent' | 'system' | (string & {});
+/** One focus deposit's parameters. */
+export interface FocusInput {
+    /** the deposit's weight (default `1`). Accumulates decay-then-add onto the source's running mass. */
+    amount?: number;
+    /** who directed it (default `'system'` on the raw handle; the host stamps `'operator'` / `'agent'`). */
+    source?: FocusSource;
+    /** the deposit's half-life, in the field's simulation-clock unit (`env.t` SECONDS, matching
+     *  {@link FocusState}`.time`) — how fast this attention goes stale (default ~8). */
+    halfLife?: number;
+    /** the deposit's timestamp on the simulation clock (`env.t` seconds; default the field's current `env.t`);
+     *  backdates a stale focus. Same unit as {@link FocusState}`.time`. */
+    at?: number;
+}
+/** One source's decayed contribution to a body's salience — the provenance split (who is focused here). */
+export interface FocusSourceShare {
+    source: FocusSource;
+    /** the source's decayed weight at read time, clamped `0..1`. */
+    weight: number;
+    /** when this source last deposited (simulation clock). */
+    updatedAt: number;
+}
+/** A focused entity in a {@link FocusState} reading — who (sources), how hot (salience), where (identity). */
+export interface FocusEntry {
+    /** the entity's addressable id (the focus target; equals `identity.id`). */
+    target: string;
+    /** the entity's first-class identity (see {@link FieldBodyIdentity}) — the id for a write-back. */
+    identity: FieldBodyIdentity;
+    /** net decayed directed focus, clamped `0..1`. */
+    salience: number;
+    /** the per-source split (present in an agent view only with `read:focus`). */
+    sources: FocusSourceShare[];
+    /** the most recent deposit's timestamp (simulation clock). */
+    updatedAt: number;
+}
+/** Options for {@link FieldHandle.focusState} — bound the sharp-tip digest. All optional. */
+export interface FocusReadOptions {
+    /** max entries returned (default `8`). */
+    limit?: number;
+    /** drop entries below this salience (default `0.05`). */
+    threshold?: number;
+    /** rank + filter by ONE source's decayed weight instead of net salience. */
+    source?: FocusSource;
+}
+/** The current-focus digest — small, ranked, thresholded; cheap to push into an agent turn. */
+export interface FocusState {
+    frame: number;
+    /** the simulation clock at read time (matches {@link FieldQueryResult}`.time`). */
+    time: number;
+    /** entries ranked desc by salience (or by `opts.source` weight), thresholded, capped. */
+    entries: FocusEntry[];
+}
+/** The `focus` discrete event — the write-back channel AND an append-only, timestamped provenance receipt. */
+export interface FocusEvent {
+    /** the focused entity's addressable id. */
+    target: string;
+    identity: FieldBodyIdentity;
+    /** who directed this deposit. */
+    source: FocusSource;
+    /** this deposit's weight. */
+    amount: number;
+    /** the entity's net decayed salience after this deposit, clamped `0..1`. */
+    salience: number;
+    /** this source's decayed running mass after this deposit, clamped `0..1`. */
+    sourceSalience: number;
+    frame: number;
+    time: number;
+}
 /**
  * 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}. */
@@ -183,6 +292,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;
@@ -221,6 +334,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;
@@ -236,6 +353,12 @@ export interface Body {
     d: number;
     /** conserved-attention effective-strength multiplier (§2.4); 1 = neutral. */
     attn?: number;
+    /** EXPERIMENTAL (focus substrate): this body's net decayed directed focus ∈ [0,1], joined from the
+     *  focus ledger each frame; `undefined` when unfocused (the fast path). Surfaces as `metrics.salience`. */
+    salience?: number;
+    /** EXPERIMENTAL (focus substrate): the focus-well strength multiplier derived from `salience` (≥1,
+     *  clamped), applied at the integrator; `undefined` = neutral (preserves the `mul === 1` fast path). */
+    focusMul?: number;
     /** fractional-emission accumulator for a budgeted [S] source (`spawn`) — carries the
      *  sub-1/frame remainder when the rate is clamped to `cap / life`. Runtime state. */
     emitAcc?: number;
@@ -373,11 +496,22 @@ export interface Env {
      * 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. */
+     * 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';
+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:
@@ -526,6 +660,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;
@@ -540,11 +721,14 @@ export interface FieldOptions {
      */
     depth?: number;
     /** 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 — see {@link Env.integrator}. */
+     *  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 true. Set false for the bare
-     *  free-particle field with no carrier waves. */
+    /** 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';
@@ -571,13 +755,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[];
@@ -613,6 +871,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;
     /**
@@ -658,6 +927,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 {
@@ -665,7 +949,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;
@@ -708,6 +992,11 @@ 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). */
@@ -814,8 +1103,12 @@ export interface FieldQuery {
 }
 /** 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`). */
+    /** 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). */
@@ -881,6 +1174,19 @@ export interface FieldQueryResult {
     /** 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). */
@@ -892,10 +1198,65 @@ export interface FieldSnapshotOptions {
     /** 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'
+/** EXPERIMENTAL: gates the {@link AgentFieldView.focusState} digest + the per-source provenance split.
+ *  The aggregate per-body `salience` still rides `query()`/`snapshot()` under the base grant. */
+ | 'read:focus';
+/** 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;
+    /** the current-focus digest — present ONLY when `read:focus` is granted (otherwise `undefined`, so the
+     *  facade's shape reflects the grant). Read-only, like the rest of the view. The aggregate per-body
+     *  `salience` still rides `query()`/`snapshot()` metrics; this adds the ranked tip with the per-source
+     *  provenance split (who is focused where). */
+    focusState?(opts?: FocusReadOptions): FocusState;
 }
 /** 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). */
@@ -1154,6 +1515,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
@@ -1161,7 +1539,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
@@ -1342,13 +1720,32 @@ export interface FieldHandle {
      * name (e.g. `'scent'`) to keep an authored field independent. Read-write, lives in field px.
      */
     grid(name: string): ScalarGrid;
+    /**
+     * EXPERIMENTAL — deposit source-tagged, decaying **focus** onto a body by identity: the write side of
+     * the shared attention channel. `focus('file:src/auth.ts', { source: 'operator' })`. Operator/host
+     * attention is an input; an agent's is an output — the host relays `field.focus(id, { source: 'agent' })`
+     * so the read-only agent view can never write. Deposits accumulate decay-then-add per source (decay is
+     * `temporal.freshness`, the `env.t` clock — no `Date.now`); each fires the `focus` event and surfaces as
+     * `metrics.salience` + in {@link focusState}. A string target ALWAYS records (retained until a body with
+     * that id appears, then it binds). The only no-op is the absent-field case (e.g. a detached `<field-root>`).
+     */
+    focus(target: string | FieldBodyIdentity, input?: FocusInput): void;
+    /**
+     * EXPERIMENTAL — read the current-focus digest: the ranked, thresholded, capped "sharp tip" (a few
+     * hundred bytes), small enough to push into an agent turn each turn. Net breadth — any body's focus
+     * magnitude — rides `query()`/`snapshot()` via `metrics.salience`; this is the tip, with the per-source
+     * provenance split (who is focused where).
+     */
+    focusState(opts?: FocusReadOptions): FocusState;
     /**
      * Subscribe to a discrete **field event** — the engine's host-agnostic push bus, for reacting to
      * *occurrences* instead of polling the continuous feedback channels each frame. Returns an
      * unsubscribe function. Plain data, no DOM (distinct from the `data-on` CustomEvent bindings a DOM
-     * host uses). Events: `absorb` / `release` — a `sink` body captured / let go of matter (the rising
-     * / falling edge of accretion), `{ body, count }`. Detection is lazy: a type with no listener costs
-     * nothing. (`contact`, `settle`, and per-particle `enter`·`exit` are the next slice — see #441.)
+     * host uses). Events: `captured` / `released` — a `sink` body captured / let go of matter (the rising
+     * / falling edge of accretion), `{ body, count }`; `enter` / `exit` — another body crossed INTO / OUT
+     * of a body's `range`, `{ body, other }`; `met` — two bodies' boxes touched, `{ a, b }`; `focus` — a
+     * `focus()` deposit landed (the write-back channel + provenance receipt), a flat {@link FocusEvent}.
+     * Detection is lazy: a type with no listener costs nothing.
      */
     on<K extends FieldEventType>(type: K, cb: (e: FieldEventMap[K]) => void): () => void;
     /**