@fundamental-engine/core 0.4.0

package/dist/core/shadow.js

@@ -0,0 +1,84 @@
+/** The registration event names. `composed: true` lets them cross the shadow boundary. */
+export const REGISTER_BODY = 'field:register-body';
+export const UNREGISTER_BODY = 'field:unregister-body';
+export const UPDATE_BODY = 'field:update-body';
+/**
+ * Component-side helper (shadow-dom.md §31.1) so a custom element joins the field without
+ * repeating event boilerplate. Construct with the host (and optional extra detail), then
+ * call `connect()` / `disconnect()` / `update()` from the element's lifecycle callbacks.
+ */
+export class FieldController {
+    host;
+    detail;
+    constructor(host, detail = {}) {
+        this.host = host;
+        this.detail = detail;
+    }
+    /** register the host as a body — call from `connectedCallback`. */
+    connect() {
+        this.emit(REGISTER_BODY);
+    }
+    /** remove the body — call from `disconnectedCallback`. */
+    disconnect() {
+        this.emit(UNREGISTER_BODY);
+    }
+    /** refresh attrs/geometry — call from `attributeChangedCallback`. */
+    update() {
+        this.emit(UPDATE_BODY);
+    }
+    emit(type) {
+        const detail = { element: this.host, ...this.detail };
+        this.host.dispatchEvent(new CustomEvent(type, { bubbles: true, composed: true, detail }));
+    }
+}
+/**
+ * Engine-side registry of event-registered hosts. Pure of the DOM event system: the field
+ * feeds it details and asks for bodies each scan. It prunes hosts that have left the document
+ * (do not rely on `disconnectedCallback` alone, §15) and never touches a shadow root.
+ */
+export class ShadowRegistry {
+    hosts = new Map();
+    /** Register (or, idempotently, refresh) a host. */
+    register(detail) {
+        this.hosts.set(detail.element, detail);
+    }
+    /** Drop a host. */
+    unregister(element) {
+        this.hosts.delete(element);
+    }
+    /** how many hosts are currently registered (post-prune count is via `bodies`). */
+    get size() {
+        return this.hosts.size;
+    }
+    /**
+     * Build a `Body` per live registered host, pruning any that have disconnected. `build` is
+     * the scanner's `bodyFromElement`; `attrs` (if supplied at registration) override the
+     * host's own `data-*`, else the host is read directly. A custom `getRect` and `writeTarget`
+     * are attached to the resulting body.
+     */
+    bodies(build) {
+        const out = [];
+        for (const [el, detail] of this.hosts) {
+            if (!el.isConnected) {
+                this.hosts.delete(el);
+                continue;
+            }
+            const attrs = detail.attrs ? attrsView(detail.attrs, el) : undefined;
+            const body = build(el, attrs);
+            if (detail.getRect)
+                body.rect = detail.getRect;
+            if (detail.writeTarget)
+                body.writeTarget = detail.writeTarget;
+            out.push(body);
+        }
+        return out;
+    }
+}
+/** A `BodyAttrs` view that prefers the explicit `attrs` record, falling back to the host. */
+function attrsView(attrs, el) {
+    return {
+        get: (name) => attrs[name] ?? el.getAttribute('data-' + name),
+        has: (name) => name in attrs || el.hasAttribute('data-' + name),
+    };
+}
+//# sourceMappingURL=shadow.js.map

package/dist/core/shadow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow.js","sourceRoot":"","sources":["../../src/core/shadow.ts"],"names":[],"mappings":"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"}

package/dist/core/spatial-hash.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A uniform-grid spatial hash for neighbour queries — the index that makes
+ * particle↔particle forces (§20.1 class [B]) O(n·k) instead of O(n²).
+ *
+ * Rebuilt each frame from the live particle pool; query with `near(x, y, r)`.
+ * Dependency-free.
+ */
+export interface Point {
+    x: number;
+    y: number;
+    /** optional z lane (z-axis.md) — undefined reads as 0 (the flat plane). */
+    z?: number;
+}
+export declare class SpatialHash<T extends Point> {
+    private readonly cell;
+    private readonly bins;
+    constructor(cellSize?: number);
+    private key;
+    clear(): void;
+    insert(item: T): void;
+    rebuild(items: readonly T[]): void;
+    /**
+     * Items within radius `r` of (x, y, z), filtered by TRUE (3D) distance. Bins stay
+     * planar — items at any z share their (x, y) cell — which over-collects candidates
+     * in a deep volume but never returns a wrong result; the z² term below is the
+     * contract. `z` defaults to 0, so flat-field callers are byte-identical.
+     */
+    near(x: number, y: number, r: number, z?: number): T[];
+}
+//# sourceMappingURL=spatial-hash.d.ts.map

package/dist/core/spatial-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-hash.d.ts","sourceRoot":"","sources":["../../src/core/spatial-hash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,2EAA2E;IAC3E,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,qBAAa,WAAW,CAAC,CAAC,SAAS,KAAK;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;gBAEnC,QAAQ,SAAK;IAIzB,OAAO,CAAC,GAAG;IAKX,KAAK,IAAI,IAAI;IAIb,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAUrB,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,IAAI;IAKlC;;;;;OAKG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,CAAC,EAAE;CAqBlD"}

package/dist/core/spatial-hash.js

@@ -0,0 +1,64 @@
+/**
+ * A uniform-grid spatial hash for neighbour queries — the index that makes
+ * particle↔particle forces (§20.1 class [B]) O(n·k) instead of O(n²).
+ *
+ * Rebuilt each frame from the live particle pool; query with `near(x, y, r)`.
+ * Dependency-free.
+ */
+export class SpatialHash {
+    cell;
+    bins = new Map();
+    constructor(cellSize = 64) {
+        this.cell = cellSize > 0 ? cellSize : 64;
+    }
+    key(cx, cy) {
+        // pack two signed cell coords into one number (offset to keep non-negative).
+        return (cx + 0x8000) * 0x10000 + (cy + 0x8000);
+    }
+    clear() {
+        this.bins.clear();
+    }
+    insert(item) {
+        const k = this.key(Math.floor(item.x / this.cell), Math.floor(item.y / this.cell));
+        const bin = this.bins.get(k);
+        if (bin)
+            bin.push(item);
+        else
+            this.bins.set(k, [item]);
+    }
+    rebuild(items) {
+        this.clear();
+        for (const it of items)
+            this.insert(it);
+    }
+    /**
+     * Items within radius `r` of (x, y, z), filtered by TRUE (3D) distance. Bins stay
+     * planar — items at any z share their (x, y) cell — which over-collects candidates
+     * in a deep volume but never returns a wrong result; the z² term below is the
+     * contract. `z` defaults to 0, so flat-field callers are byte-identical.
+     */
+    near(x, y, r, z = 0) {
+        const out = [];
+        const r2 = r * r;
+        const minCx = Math.floor((x - r) / this.cell);
+        const maxCx = Math.floor((x + r) / this.cell);
+        const minCy = Math.floor((y - r) / this.cell);
+        const maxCy = Math.floor((y + r) / this.cell);
+        for (let cx = minCx; cx <= maxCx; cx++) {
+            for (let cy = minCy; cy <= maxCy; cy++) {
+                const bin = this.bins.get(this.key(cx, cy));
+                if (!bin)
+                    continue;
+                for (const it of bin) {
+                    const dx = it.x - x;
+                    const dy = it.y - y;
+                    const dz = (it.z ?? 0) - z;
+                    if (dx * dx + dy * dy + dz * dz <= r2)
+                        out.push(it);
+                }
+            }
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=spatial-hash.js.map

package/dist/core/spatial-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-hash.js","sourceRoot":"","sources":["../../src/core/spatial-hash.ts"],"names":[],"mappings":"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"}

package/dist/core/streamlines.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Streamlines / vector-field render (§20.6, diagnostic) — instead of the matter, draw
+ * the *forces themselves*. At a grid of probe points we measure the net push a
+ * still test particle would feel and draw a short arrow along it, so the invisible
+ * field a layout creates becomes visible. Invaluable in the Lab: place forces, then
+ * see the field they make.
+ *
+ * `forceAt` is pure and mirrors the integrator's body-force loop (same range cull),
+ * minus the per-particle modifier pass — a faithful-enough probe for a diagnostic.
+ */
+import type { Body, Env, ForceRegistry } from './types.ts';
+/** Net force a zero-velocity test particle would feel at (x, y) — the field vector.
+ *  A force that defines a `field()` (its visual/structure field) contributes that instead
+ *  of its `apply`, so velocity- and charge-dependent forces (magnetism, charge) appear here
+ *  even though they no-op on a still, neutral probe. */
+export declare function forceAt(bodies: readonly Body[], forces: ForceRegistry, env: Env, x: number, y: number): {
+    fx: number;
+    fy: number;
+};
+/** The net *structure* field at (x, y): the superposition of every visible body's `field()`
+ *  contribution (the dipoles and monopoles only — no apply-probe), with the same range cull
+ *  as the integrator. This is the field the streamlines view draws and the vector matter
+ *  follows under `fieldflow`. Pure: same inputs, same output, no `env` mutation (the `field()`
+ *  hooks read only `b` and the point, so it is safe to call mid-integration). */
+export declare function netField(bodies: readonly Body[], forces: ForceRegistry, x: number, y: number): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=streamlines.d.ts.map

package/dist/core/streamlines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamlines.d.ts","sourceRoot":"","sources":["../../src/core/streamlines.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,aAAa,EAAY,MAAM,YAAY,CAAC;AAIrE;;;wDAGwD;AACxD,wBAAgB,OAAO,CACrB,MAAM,EAAE,SAAS,IAAI,EAAE,EACvB,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,GAAG,EACR,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CA+B5B;AAED;;;;iFAIiF;AACjF,wBAAgB,QAAQ,CACtB,MAAM,EAAE,SAAS,IAAI,EAAE,EACvB,MAAM,EAAE,aAAa,EACrB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAoB1B"}

package/dist/core/streamlines.js

@@ -0,0 +1,70 @@
+const probe = { x: 0, y: 0, vx: 0, vy: 0, m: 1, heat: 0, size: 1, cap: null };
+/** Net force a zero-velocity test particle would feel at (x, y) — the field vector.
+ *  A force that defines a `field()` (its visual/structure field) contributes that instead
+ *  of its `apply`, so velocity- and charge-dependent forces (magnetism, charge) appear here
+ *  even though they no-op on a still, neutral probe. */
+export function forceAt(bodies, forces, env, x, y) {
+    probe.x = x;
+    probe.y = y;
+    probe.vx = 0;
+    probe.vy = 0;
+    probe.heat = 0;
+    let fxField = 0; // field() contributions, accumulated apart from the apply probe
+    let fyField = 0;
+    for (const b of bodies) {
+        if (!b.vis || b.tokens.length === 0)
+            continue;
+        const dx = b.cx - x;
+        const dy = b.cy - y;
+        const d2 = dx * dx + dy * dy;
+        if (b.range > 0 && d2 >= b.range * b.range * 2.56)
+            continue; // same cull as the integrator
+        const d = Math.sqrt(d2);
+        env.dx = dx;
+        env.dy = dy;
+        env.dist = d < 1 ? 1 : d;
+        for (const tok of b.tokens) {
+            const f = forces[tok];
+            if (!f || f.modify)
+                continue;
+            if (f.field) {
+                const v = f.field(b, x, y);
+                fxField += v.x;
+                fyField += v.y;
+            }
+            else {
+                f.apply(b, probe, env);
+            }
+        }
+    }
+    return { fx: probe.vx + fxField, fy: probe.vy + fyField };
+}
+/** The net *structure* field at (x, y): the superposition of every visible body's `field()`
+ *  contribution (the dipoles and monopoles only — no apply-probe), with the same range cull
+ *  as the integrator. This is the field the streamlines view draws and the vector matter
+ *  follows under `fieldflow`. Pure: same inputs, same output, no `env` mutation (the `field()`
+ *  hooks read only `b` and the point, so it is safe to call mid-integration). */
+export function netField(bodies, forces, x, y) {
+    let fx = 0;
+    let fy = 0;
+    for (const b of bodies) {
+        if (!b.vis || b.tokens.length === 0)
+            continue;
+        if (b.range > 0) {
+            const dx = b.cx - x;
+            const dy = b.cy - y;
+            if (dx * dx + dy * dy >= b.range * b.range * 2.56)
+                continue; // same cull as the integrator
+        }
+        for (const tok of b.tokens) {
+            const f = forces[tok];
+            if (f?.field) {
+                const v = f.field(b, x, y);
+                fx += v.x;
+                fy += v.y;
+            }
+        }
+    }
+    return { x: fx, y: fy };
+}
+//# sourceMappingURL=streamlines.js.map

package/dist/core/streamlines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamlines.js","sourceRoot":"","sources":["../../src/core/streamlines.ts"],"names":[],"mappings":"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"}

package/dist/core/surface.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The decorative full-viewport canvas surface (§13, §18) — one source of truth for the
+ * fixed, click-through, behind-everything styling every managed mount uses. The vanilla
+ * `mountField` / `FieldField` and the React `<FieldField>` render this exact surface; the
+ * web component styles its shadow host to match.
+ */
+/** The surface as a style object (React `CSSProperties`-compatible). */
+export declare const FIELD_CANVAS_STYLE: {
+    readonly position: "fixed";
+    readonly inset: "0";
+    readonly width: "100%";
+    readonly height: "100%";
+    readonly zIndex: "0";
+    readonly pointerEvents: "none";
+    readonly display: "block";
+};
+/** The same surface as a `cssText` string (camelCase keys → kebab-case), for `style.cssText`. */
+export declare const FIELD_CANVAS_CSS: string;
+//# sourceMappingURL=surface.d.ts.map

package/dist/core/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/core/surface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wEAAwE;AACxE,eAAO,MAAM,kBAAkB;;;;;;;;CAQrB,CAAC;AAEX,iGAAiG;AACjG,eAAO,MAAM,gBAAgB,QAEjB,CAAC"}

package/dist/core/surface.js

@@ -0,0 +1,21 @@
+/**
+ * The decorative full-viewport canvas surface (§13, §18) — one source of truth for the
+ * fixed, click-through, behind-everything styling every managed mount uses. The vanilla
+ * `mountField` / `FieldField` and the React `<FieldField>` render this exact surface; the
+ * web component styles its shadow host to match.
+ */
+/** The surface as a style object (React `CSSProperties`-compatible). */
+export const FIELD_CANVAS_STYLE = {
+    position: 'fixed',
+    inset: '0',
+    width: '100%',
+    height: '100%',
+    zIndex: '0',
+    pointerEvents: 'none',
+    display: 'block',
+};
+/** The same surface as a `cssText` string (camelCase keys → kebab-case), for `style.cssText`. */
+export const FIELD_CANVAS_CSS = Object.entries(FIELD_CANVAS_STYLE)
+    .map(([k, v]) => `${k.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase())}:${v}`)
+    .join(';');
+//# sourceMappingURL=surface.js.map

package/dist/core/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../../src/core/surface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,QAAQ,EAAE,OAAO;IACjB,KAAK,EAAE,GAAG;IACV,KAAK,EAAE,MAAM;IACb,MAAM,EAAE,MAAM;IACd,MAAM,EAAE,GAAG;IACX,aAAa,EAAE,MAAM;IACrB,OAAO,EAAE,OAAO;CACR,CAAC;AAEX,iGAAiG;AACjG,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC;KAC/D,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;KAC5E,IAAI,CAAC,GAAG,CAAC,CAAC"}

package/dist/core/temporal.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Temporal kernels — WORLD TIME made computable.
+ *
+ * field-ui keeps three clocks:
+ *
+ *   1. **Simulation time** — `env.t` / `dt`, particle age: the integrator's clock.
+ *   2. **Experiential time** — the platform metric pipeline's attention / memory / recency:
+ *      eased integrals of interaction (`@fundamental-engine/platform` `metrics.ts`).
+ *   3. **World time** — timestamps carried by the data itself: a launch's T−0, an issue's
+ *      `updatedAt`, a question's `askedAt`, a fact's last review.
+ *
+ * These kernels are clock 3. Each is a pure, deterministic map from world timestamps to a
+ * `0..1` weight — zero DOM, zero state, and **no `Date.now()`**: the caller supplies `nowMs`
+ * (the platform samples it once per frame; pages sample it once per tick). All arguments are
+ * epoch/duration **milliseconds**; the day and hour constants the shapes were calibrated in
+ * are exported explicitly. Degenerate inputs (NaN, ±Infinity, non-positive timescales) never
+ * produce NaN — each kernel documents its safe value.
+ *
+ * The shapes are lifted, exactly, from the shipped example family (the extraction ratchet:
+ * four hand-rolls → one primitive): `imminence` from the calendar page's 1 Hz clock,
+ * `retention` from the memory page's forgetting curve, `freshness` as the canonical form of
+ * the backlog/inbox recency lanes. `data-field-at` (see `@fundamental-engine/platform`) feeds
+ * `freshness` to ground the metric pipeline's recency lane in declared world time.
+ */
+/** One hour in milliseconds — `imminence`'s log-softening unit (the calendar shape is hour-calibrated). */
+export declare const HOUR_MS = 3600000;
+/** One day in milliseconds — `retention`'s τ defaults are day-calibrated (4 + a·56 days). */
+export declare const DAY_MS = 86400000;
+/**
+ * How imminent a moment feels: `1` at (or past) the moment, log-ramping down to `0` at the
+ * far edge of the horizon.
+ *
+ * The exact form, with `until = atMs − nowMs`:
+ *
+ *     imminence = clamp01( 1 − ln(until/HOUR_MS + 1) / ln(horizonMs/HOUR_MS + 1) )
+ *
+ * i.e. the calendar example's weight, `1 − ln(hoursUntil + 1) / ln(horizonHours + 1)`, with
+ * hours generalized to milliseconds. The one-hour softening unit (`+1` in hour units) is part
+ * of the shape: it keeps the ramp finite at `until = 0` and makes the last hours before the
+ * moment the steepest part of the curve. Returns `1` for any `until ≤ 0` (the moment has
+ * arrived — what a page does with a *passed* moment, e.g. the calendar's `0.08` floor for
+ * passed/TBD launches, is page semantics layered on top). Monotonically non-increasing in
+ * `until`; `0` at and beyond the horizon.
+ *
+ * Degenerate inputs: a non-finite `atMs`/`nowMs` returns `0`; a non-positive or non-finite
+ * `horizonMs` returns `1` at/past the moment and `0` otherwise (no horizon, no ramp).
+ */
+export declare function imminence(atMs: number, nowMs: number, horizonMs: number): number;
+/**
+ * Exponential newness decay — the backlog/inbox recency shape in its canonical form:
+ *
+ *     freshness = 2^(−since / halfLifeMs)    with since = nowMs − atMs
+ *
+ * `1` at the moment itself, **exactly `0.5` one half-life later**, `0.25` after two, → `0`
+ * asymptotically. Future timestamps (`since < 0`) clamp to `1` — nothing is fresher than now.
+ * Monotonically non-increasing in `since`.
+ *
+ * Naming: this lane reads positively — the complement is *staleness*, and it is deliberately
+ * not exported: `staleness = 1 − freshness`. One word per lane.
+ *
+ * Degenerate inputs: a non-finite `atMs`/`nowMs` returns `0`; a non-positive or non-finite
+ * `halfLifeMs` returns `1` at/before the moment and `0` after it (instant decay).
+ */
+export declare function freshness(atMs: number, nowMs: number, halfLifeMs: number): number;
+/** Options for {@link retention} — the τ calibration, in milliseconds. */
+export interface RetentionOptions {
+    /** τ's base — the decay timescale of a zero-strength anchor. Default `4 * DAY_MS`. */
+    tauBaseMs?: number;
+    /** τ's growth with anchor strength — `τ(a) = tauBaseMs + a · tauGrowthMs`. Default `56 * DAY_MS`. */
+    tauGrowthMs?: number;
+}
+/**
+ * Ebbinghaus-shaped retention: how much of an anchored fact is still held after `sinceMs`.
+ *
+ * The exact form, lifted from the memory example's forgetting curve:
+ *
+ *     retention = a · e^(−since / τ(a))    with τ(a) = tauBaseMs + a · tauGrowthMs
+ *
+ * which is the memory page's `w = a · exp(−days / τ)` with `τ = 4 + a·56` **in day units**,
+ * generalized to milliseconds with the day constant explicit (defaults `4 * DAY_MS` and
+ * `56 * DAY_MS`). The stability term is the point: τ *grows* with anchor strength, so deeply
+ * anchored facts decay slower — exponential decay alone forgets everything at one rate.
+ * `anchor` is clamped to `0..1`; `retention(a, 0)` is exactly `a`; monotonically
+ * non-increasing in `sinceMs` (negative `sinceMs` clamps to `0` — a future review holds full
+ * strength, it doesn't overshoot).
+ *
+ * The shape is Ebbinghaus's; the default constants are the memory page's, tuned for
+ * legibility, not fitted to recall data. Degenerate inputs: non-finite `anchor` reads as `0`;
+ * non-finite `sinceMs` or a non-positive τ returns `0` (nothing held).
+ */
+export declare function retention(anchor: number, sinceMs: number, opts?: RetentionOptions): number;
+/**
+ * Cyclical phase: where `nowMs` sits inside a repeating period, as `0..1` (the result is in
+ * `[0, 1)` — the wrap point reads as `0`, never `1`).
+ *
+ *     phase = ((nowMs − offsetMs) mod periodMs) / periodMs
+ *
+ * with a true (sign-safe) modulo, so times before the offset wrap correctly. `offsetMs`
+ * anchors the cycle's zero — e.g. a local midnight for a day rhythm, a Monday 00:00 for a
+ * week rhythm.
+ *
+ * Honesty note: this kernel ships for completeness of the world-time family (day/week
+ * rhythms are the obvious fourth shape next to imminence, freshness, and retention), but
+ * **no shipped page or pipeline consumes it yet** — it has no worked example.
+ *
+ * Degenerate inputs: a non-finite `nowMs`/`offsetMs` or a non-positive/non-finite `periodMs`
+ * returns `0`.
+ */
+export declare function phase(nowMs: number, periodMs: number, offsetMs?: number): number;
+//# sourceMappingURL=temporal.d.ts.map

package/dist/core/temporal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../../src/core/temporal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,OAAO,UAAY,CAAC;AAEjC,6FAA6F;AAC7F,eAAO,MAAM,MAAM,WAAa,CAAC;AAIjC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAMhF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAMjF;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAO9F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAM3E"}

package/dist/core/temporal.js

@@ -0,0 +1,139 @@
+/**
+ * Temporal kernels — WORLD TIME made computable.
+ *
+ * field-ui keeps three clocks:
+ *
+ *   1. **Simulation time** — `env.t` / `dt`, particle age: the integrator's clock.
+ *   2. **Experiential time** — the platform metric pipeline's attention / memory / recency:
+ *      eased integrals of interaction (`@fundamental-engine/platform` `metrics.ts`).
+ *   3. **World time** — timestamps carried by the data itself: a launch's T−0, an issue's
+ *      `updatedAt`, a question's `askedAt`, a fact's last review.
+ *
+ * These kernels are clock 3. Each is a pure, deterministic map from world timestamps to a
+ * `0..1` weight — zero DOM, zero state, and **no `Date.now()`**: the caller supplies `nowMs`
+ * (the platform samples it once per frame; pages sample it once per tick). All arguments are
+ * epoch/duration **milliseconds**; the day and hour constants the shapes were calibrated in
+ * are exported explicitly. Degenerate inputs (NaN, ±Infinity, non-positive timescales) never
+ * produce NaN — each kernel documents its safe value.
+ *
+ * The shapes are lifted, exactly, from the shipped example family (the extraction ratchet:
+ * four hand-rolls → one primitive): `imminence` from the calendar page's 1 Hz clock,
+ * `retention` from the memory page's forgetting curve, `freshness` as the canonical form of
+ * the backlog/inbox recency lanes. `data-field-at` (see `@fundamental-engine/platform`) feeds
+ * `freshness` to ground the metric pipeline's recency lane in declared world time.
+ */
+/** One hour in milliseconds — `imminence`'s log-softening unit (the calendar shape is hour-calibrated). */
+export const HOUR_MS = 3_600_000;
+/** One day in milliseconds — `retention`'s τ defaults are day-calibrated (4 + a·56 days). */
+export const DAY_MS = 86_400_000;
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+/**
+ * How imminent a moment feels: `1` at (or past) the moment, log-ramping down to `0` at the
+ * far edge of the horizon.
+ *
+ * The exact form, with `until = atMs − nowMs`:
+ *
+ *     imminence = clamp01( 1 − ln(until/HOUR_MS + 1) / ln(horizonMs/HOUR_MS + 1) )
+ *
+ * i.e. the calendar example's weight, `1 − ln(hoursUntil + 1) / ln(horizonHours + 1)`, with
+ * hours generalized to milliseconds. The one-hour softening unit (`+1` in hour units) is part
+ * of the shape: it keeps the ramp finite at `until = 0` and makes the last hours before the
+ * moment the steepest part of the curve. Returns `1` for any `until ≤ 0` (the moment has
+ * arrived — what a page does with a *passed* moment, e.g. the calendar's `0.08` floor for
+ * passed/TBD launches, is page semantics layered on top). Monotonically non-increasing in
+ * `until`; `0` at and beyond the horizon.
+ *
+ * Degenerate inputs: a non-finite `atMs`/`nowMs` returns `0`; a non-positive or non-finite
+ * `horizonMs` returns `1` at/past the moment and `0` otherwise (no horizon, no ramp).
+ */
+export function imminence(atMs, nowMs, horizonMs) {
+    if (!Number.isFinite(atMs) || !Number.isFinite(nowMs))
+        return 0;
+    const until = atMs - nowMs;
+    if (until <= 0)
+        return 1;
+    if (!Number.isFinite(horizonMs) || horizonMs <= 0)
+        return 0;
+    return clamp01(1 - Math.log(until / HOUR_MS + 1) / Math.log(horizonMs / HOUR_MS + 1));
+}
+/**
+ * Exponential newness decay — the backlog/inbox recency shape in its canonical form:
+ *
+ *     freshness = 2^(−since / halfLifeMs)    with since = nowMs − atMs
+ *
+ * `1` at the moment itself, **exactly `0.5` one half-life later**, `0.25` after two, → `0`
+ * asymptotically. Future timestamps (`since < 0`) clamp to `1` — nothing is fresher than now.
+ * Monotonically non-increasing in `since`.
+ *
+ * Naming: this lane reads positively — the complement is *staleness*, and it is deliberately
+ * not exported: `staleness = 1 − freshness`. One word per lane.
+ *
+ * Degenerate inputs: a non-finite `atMs`/`nowMs` returns `0`; a non-positive or non-finite
+ * `halfLifeMs` returns `1` at/before the moment and `0` after it (instant decay).
+ */
+export function freshness(atMs, nowMs, halfLifeMs) {
+    if (!Number.isFinite(atMs) || !Number.isFinite(nowMs))
+        return 0;
+    const since = nowMs - atMs;
+    if (since <= 0)
+        return 1;
+    if (!Number.isFinite(halfLifeMs) || halfLifeMs <= 0)
+        return 0;
+    return Math.pow(2, -since / halfLifeMs);
+}
+/**
+ * Ebbinghaus-shaped retention: how much of an anchored fact is still held after `sinceMs`.
+ *
+ * The exact form, lifted from the memory example's forgetting curve:
+ *
+ *     retention = a · e^(−since / τ(a))    with τ(a) = tauBaseMs + a · tauGrowthMs
+ *
+ * which is the memory page's `w = a · exp(−days / τ)` with `τ = 4 + a·56` **in day units**,
+ * generalized to milliseconds with the day constant explicit (defaults `4 * DAY_MS` and
+ * `56 * DAY_MS`). The stability term is the point: τ *grows* with anchor strength, so deeply
+ * anchored facts decay slower — exponential decay alone forgets everything at one rate.
+ * `anchor` is clamped to `0..1`; `retention(a, 0)` is exactly `a`; monotonically
+ * non-increasing in `sinceMs` (negative `sinceMs` clamps to `0` — a future review holds full
+ * strength, it doesn't overshoot).
+ *
+ * The shape is Ebbinghaus's; the default constants are the memory page's, tuned for
+ * legibility, not fitted to recall data. Degenerate inputs: non-finite `anchor` reads as `0`;
+ * non-finite `sinceMs` or a non-positive τ returns `0` (nothing held).
+ */
+export function retention(anchor, sinceMs, opts = {}) {
+    const a = clamp01(Number.isFinite(anchor) ? anchor : 0);
+    if (!Number.isFinite(sinceMs))
+        return 0;
+    const since = sinceMs < 0 ? 0 : sinceMs;
+    const tau = (opts.tauBaseMs ?? 4 * DAY_MS) + a * (opts.tauGrowthMs ?? 56 * DAY_MS);
+    if (!Number.isFinite(tau) || tau <= 0)
+        return 0;
+    return a * Math.exp(-since / tau);
+}
+/**
+ * Cyclical phase: where `nowMs` sits inside a repeating period, as `0..1` (the result is in
+ * `[0, 1)` — the wrap point reads as `0`, never `1`).
+ *
+ *     phase = ((nowMs − offsetMs) mod periodMs) / periodMs
+ *
+ * with a true (sign-safe) modulo, so times before the offset wrap correctly. `offsetMs`
+ * anchors the cycle's zero — e.g. a local midnight for a day rhythm, a Monday 00:00 for a
+ * week rhythm.
+ *
+ * Honesty note: this kernel ships for completeness of the world-time family (day/week
+ * rhythms are the obvious fourth shape next to imminence, freshness, and retention), but
+ * **no shipped page or pipeline consumes it yet** — it has no worked example.
+ *
+ * Degenerate inputs: a non-finite `nowMs`/`offsetMs` or a non-positive/non-finite `periodMs`
+ * returns `0`.
+ */
+export function phase(nowMs, periodMs, offsetMs = 0) {
+    if (!Number.isFinite(nowMs) || !Number.isFinite(offsetMs))
+        return 0;
+    if (!Number.isFinite(periodMs) || periodMs <= 0)
+        return 0;
+    const m = (nowMs - offsetMs) % periodMs;
+    const f = (m < 0 ? m + periodMs : m) / periodMs;
+    return f >= 1 ? 0 : f; // float wrap guard: x + period can round to period
+}
+//# sourceMappingURL=temporal.js.map

package/dist/core/temporal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.js","sourceRoot":"","sources":["../../src/core/temporal.ts"],"names":[],"mappings":"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"}