@jgengine/core 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -26,6 +26,37 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.30.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.30.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.27.0`; `@jgengine/github` is `0.17.0`.
+
+### Added
+
+- `ColorblindFrame` (`@jgengine/react/accessibility`) wraps the 3D canvas and applies the player's colour-vision mode to that box alone, so HUD, menu and caption text keep their own contrast. `colorblindFrameFilter` (`@jgengine/core/ui/accessibility`) resolves a mode to the CSS filter, and `useColorblindMode` reads the mode from the settings store the settings rows write; the 3D shell does both for the mounted game.
+- `SettingsSection` (`@jgengine/react/settingsBlocks`) is one `useMenuNav` menu: a d-pad or left stick moves between rows and left/right steps the focused value — slider by its step, toggle flipped, select to the next option, confirm arms a keybind — through the same `onAdjust` path the arrow keys use. `onAdjust` (`@jgengine/react/menuNav`) is the option that makes left/right adjust instead of move.
+- `createStanding` (`@jgengine/core/progression/standing`) holds per-faction or per-district standing over authored tracks and moves it from named outcomes, so an outcome that resolves to nothing throws at the call instead of silently moving nothing.
+- `createGateSet` (`@jgengine/core/progression/gates`) evaluates authored milestones against standing and money, and refuses to load when a gate's unlock id resolves to nothing.
+- `createCareerBank` (`@jgengine/core/progression/careerBank`) keeps persistent career money apart from a run's haul, so a failed run loses the haul and keeps the bank.
+- `createUpgradeTree` (`@jgengine/core/progression/upgrades`) prices each rank from the shared curve primitive and gates purchases on prerequisites and standing.
+
+### Changed
+
+- `AccessibilityProvider` (`@jgengine/react/accessibility`) sets its data attributes and text-scale var without filtering its own subtree. A colour matrix over the HUD and menu root recoloured the text the rest of the UI assumes, so wrap the game canvas in `ColorblindFrame` instead; a custom root can still offset it with its own `ColorblindFilters` and `filter: url(#jg-cb-<mode>)`.
+- World health bars and nameplates derive their range from the render camera and the target height when a game sets no `maxDistance`: an overhead camera reaches the units it looks down at, and a bar is kept while the target it annotates still covers 18 px, instead of hiding every target past a fixed 60 units.
+- A configured `worldHealthBars.maxDistance` or `nameplates.maxDistance` that hides every target in view now warns once with the nearest measured distance and the prop to raise, instead of rendering nothing.
+
+## 0.29.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.29.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.26.0`; `@jgengine/github` is `0.16.0`.
+
+### Fixed
+
+- `MissionView.remaining` (`@jgengine/core/gameplay`) now counts down from a `survive` objective's own `duration`, not only from a `timeout`. A defend or hold objective reports the seconds it still has to run, which is the one number its HUD needs; a completed run still reports null.
+
 ## 0.28.0
 
 ### Migrate

package/dist/agents/agent.d.ts

@@ -0,0 +1,134 @@
+import { type UtilityBrainSnapshot, type UtilityInterrupt, type UtilityOption, type UtilitySwitchReason } from "../ai/utilityBrain.js";
+import { type NeedDefinition, type NeedSet, type NeedSnapshot } from "../sim/needs.js";
+import { type Mood, type MoodReader, type MoodSnapshot, type MoodTier, type MoodWeight } from "./mood.js";
+import { type AgentSchedule, type AgentScheduleConfig, type AgentSchedulePhase } from "./schedule.js";
+/** Where an agent goes when the thing it wanted is gone: a named option and a named place. */
+export interface AgentFallback {
+    readonly option: string;
+    readonly target: string;
+}
+/** One reachable thing the agent could do this tick, as the game sees its own world. */
+export interface AgentTarget {
+    /** Option id declared in the agent's `options`; unknown ids are skipped. */
+    readonly option: string;
+    /** Opaque place or object id the option would be done at. */
+    readonly target: string;
+    /** Effort the caller wants priced in: travel, queue seconds, price. */
+    readonly cost?: number;
+    /** What to do when this target stops existing, instead of re-deciding from scratch. */
+    readonly fallback?: AgentFallback;
+}
+/** What the agent is doing. */
+export interface AgentAction {
+    readonly option: string | null;
+    readonly target: string | null;
+    readonly fallback: AgentFallback | null;
+    /** True while the action is the declared fallback rather than the agent's own pick. */
+    readonly usedFallback: boolean;
+    /** Game-second the action began. */
+    readonly since: number;
+    readonly score: number;
+}
+/** Why the action last changed. */
+export type AgentActionReason = UtilitySwitchReason | "fallback" | "schedule" | "cleared";
+/** One call per tick: the clock, and the targets the game's world currently offers. */
+export interface AgentUpdate {
+    readonly dt: number;
+    /** Absolute game-second from the world clock; the schedule reads it. */
+    readonly now?: number;
+    readonly targets?: readonly AgentTarget[];
+}
+/** What one update produced: the action, the feeling, and where the day plan puts the agent. */
+export interface AgentFrame {
+    readonly action: AgentAction;
+    readonly mood: Mood;
+    readonly phase: AgentSchedulePhase | null;
+    /** Place the work beat posts the agent to now; `null` with no schedule or while travelling. */
+    readonly post: string | null;
+    readonly changed: boolean;
+    readonly reason: AgentActionReason | null;
+}
+/** Everything an agent is made of. Policy is data; nothing about a game is compiled in. */
+export interface AgentConfig {
+    readonly id: string;
+    /** Decaying needs, in the survival meter shape (`sim/needs`). Order breaks ties. */
+    readonly needs: readonly NeedDefinition[];
+    /** Scored actions, in the utility option shape (`ai/utilityBrain`). */
+    readonly options: readonly UtilityOption[];
+    readonly interrupts?: readonly UtilityInterrupt[];
+    /** The authored day plan, or omitted for an agent with no schedule. */
+    readonly schedule?: AgentScheduleConfig;
+    readonly mood?: {
+        readonly weights?: readonly MoodWeight[];
+        readonly tiers?: readonly MoodTier[];
+    };
+    readonly switchMargin?: number;
+    readonly minHoldSeconds?: number;
+    readonly costWeight?: number;
+    readonly jitter?: number;
+    /** `[0,1)` source for `jitter`; pass `ctx.rng` so runs replay. */
+    readonly rng?: () => number;
+    readonly devtoolsName?: string;
+}
+/** Serializable whole agent: needs, feeling, held action, day-plan cursor and the far flag. */
+export interface AgentSnapshot {
+    needs: NeedSnapshot;
+    mood: MoodSnapshot;
+    brain: UtilityBrainSnapshot;
+    action: AgentAction;
+    /** True while the agent runs on its schedule alone, with no utility pass per tick. */
+    far: boolean;
+    /**
+     * Identity of the schedule stop the needs were last refilled at (`stop@arrival`). Saved so a
+     * loaded agent does not eat the same meal twice.
+     */
+    scheduleMark: string | null;
+}
+/**
+ * Needs, mood, schedule and a chosen action, in one object a game ticks.
+ *
+ * `update` is the loop: needs decay (`sim/needs`), the day plan says where the agent belongs
+ * (`sim/routine` through an agent schedule), the utility brain picks among the targets the game
+ * offers (`ai/utilityBrain`), and the mood reads how satisfied those needs are. A target that
+ * disappears falls back to the declared fallback rather than freezing the agent.
+ */
+export interface Agent {
+    readonly id: string;
+    /** The agent's own need set - the game refills it after a meal, a ride or a night's sleep. */
+    readonly needs: NeedSet;
+    /** Current mood: weighted need satisfaction plus any source the game raised. */
+    mood(): Mood;
+    /** The game-raised mood sources (a queue outside, litter underfoot). */
+    readonly moodSources: MoodReader;
+    /** The resigned day plan, or `null` for an agent that only reacts to targets. */
+    readonly schedule: AgentSchedule | null;
+    /** The held action. */
+    action(): AgentAction;
+    /** Where the schedule puts the agent now; `null` without a schedule. */
+    phaseAt(now: number): AgentSchedulePhase | null;
+    /** Run one tick: decay, day plan, decision. Returns the same frame object each call. */
+    update(next: AgentUpdate): AgentFrame;
+    /**
+     * Put the agent off camera: it keeps decaying and follows its schedule, but takes no utility
+     * pass - the cheap state a far body should be. A far agent with no schedule holds its action.
+     */
+    setFar(far: boolean): void;
+    isFar(): boolean;
+    retune(patch: {
+        readonly switchMargin?: number;
+        readonly minHoldSeconds?: number;
+        readonly costWeight?: number;
+        readonly jitter?: number;
+    }): void;
+    snapshot(): AgentSnapshot;
+    restore(next: AgentSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Create one agent. The same factory serves a park guest, a household being, a patrolling janitor
+ * and a soldier: `options` is what it can choose between, `schedule` is where its day puts it.
+ *
+ * @capability agents a needs, thought, action and mood loop an agent runs on the world clock
+ */
+export declare function createAgent(config: AgentConfig): Agent;

package/dist/agents/agent.js

@@ -0,0 +1,224 @@
+import { createUtilityBrain, } from "../ai/utilityBrain.js";
+import { createNeedSet } from "../sim/needs.js";
+import { createMoodReader, } from "./mood.js";
+import { createAgentSchedule } from "./schedule.js";
+const IDLE_ACTION = {
+    option: null,
+    target: null,
+    fallback: null,
+    usedFallback: false,
+    since: 0,
+    score: 0,
+};
+function findTarget(targets, option, target) {
+    for (const candidate of targets) {
+        if (candidate.option === option && candidate.target === target)
+            return candidate;
+    }
+    return null;
+}
+function firstOfOption(targets, option) {
+    if (option === null)
+        return null;
+    for (const candidate of targets)
+        if (candidate.option === option)
+            return candidate;
+    return null;
+}
+/**
+ * Create one agent. The same factory serves a park guest, a household being, a patrolling janitor
+ * and a soldier: `options` is what it can choose between, `schedule` is where its day puts it.
+ *
+ * @capability agents a needs, thought, action and mood loop an agent runs on the world clock
+ */
+export function createAgent(config) {
+    const needs = createNeedSet(config.needs);
+    const brain = createUtilityBrain({
+        needs,
+        options: config.options,
+        ...(config.interrupts === undefined ? {} : { interrupts: config.interrupts }),
+        ...(config.switchMargin === undefined ? {} : { switchMargin: config.switchMargin }),
+        ...(config.minHoldSeconds === undefined ? {} : { minHoldSeconds: config.minHoldSeconds }),
+        ...(config.costWeight === undefined ? {} : { costWeight: config.costWeight }),
+        ...(config.jitter === undefined ? {} : { jitter: config.jitter }),
+        ...(config.rng === undefined ? {} : { rng: config.rng }),
+        ...(config.devtoolsName === undefined ? {} : { devtoolsName: config.devtoolsName }),
+    });
+    const moodReader = createMoodReader({
+        needs,
+        ...(config.mood?.weights === undefined ? {} : { weights: config.mood.weights }),
+        ...(config.mood?.tiers === undefined ? {} : { tiers: config.mood.tiers }),
+    });
+    const schedule = config.schedule === undefined ? null : createAgentSchedule(config.schedule);
+    let action = { ...IDLE_ACTION };
+    let far = false;
+    let scheduleMark = null;
+    let reason = null;
+    let changed = false;
+    const candidates = [];
+    let frame = {
+        action,
+        mood: moodReader.read(),
+        phase: null,
+        post: null,
+        changed: false,
+        reason: null,
+    };
+    function applySchedule(now) {
+        if (schedule === null)
+            return null;
+        const phase = schedule.phaseAt(now);
+        const mark = `${phase.stop}@${phase.since}`;
+        if (mark !== scheduleMark) {
+            scheduleMark = mark;
+            if (phase.refill !== null && !phase.travelling) {
+                for (const [id, amount] of Object.entries(phase.refill))
+                    needs.refill(id, amount);
+            }
+        }
+        return phase;
+    }
+    function commit(option, target, score, since) {
+        if (option === null) {
+            action = { ...action, option: null, target: null, since };
+            return;
+        }
+        if (brain.chosen() !== option)
+            brain.decide([{ option, cost: 0 }]);
+        action = { ...action, option, target, since, score };
+    }
+    function think(targets, now) {
+        candidates.length = 0;
+        for (const target of targets) {
+            candidates.push(target.cost === undefined ? { option: target.option } : { option: target.option, cost: target.cost });
+        }
+        const decision = brain.decide(candidates);
+        const pickedOption = decision.option;
+        const pickedTarget = firstOfOption(targets, pickedOption);
+        const held = findTarget(targets, action.option, action.target);
+        const adopt = (target, nextReason, usedFallback) => {
+            const nextScore = brain.scoreOf(target.option);
+            const changedIdentity = target.option !== action.option || target.target !== action.target;
+            commit(target.option, target.target, nextScore, now);
+            action = {
+                ...action,
+                fallback: usedFallback ? null : target.fallback ?? null,
+                usedFallback,
+            };
+            changed = changedIdentity;
+            reason = changed ? nextReason : reason;
+        };
+        if (action.option !== null && held === null) {
+            const fallback = action.fallback;
+            const fallbackTarget = fallback === null ? null : findTarget(targets, fallback.option, fallback.target);
+            if (fallbackTarget !== null) {
+                adopt(fallbackTarget, "fallback", true);
+                return;
+            }
+            if (pickedTarget === null) {
+                action = { ...IDLE_ACTION, since: now };
+                changed = true;
+                reason = "cleared";
+                return;
+            }
+            adopt(pickedTarget, decision.reason ?? "unavailable", false);
+            return;
+        }
+        if (pickedTarget === null) {
+            if (action.option === null) {
+                changed = false;
+                reason = null;
+                return;
+            }
+            return;
+        }
+        if (decision.changed && pickedOption !== action.option) {
+            adopt(pickedTarget, decision.reason ?? "score", false);
+            return;
+        }
+        if (action.option === null) {
+            adopt(pickedTarget, decision.reason ?? "initial", false);
+            return;
+        }
+        changed = false;
+    }
+    return {
+        id: config.id,
+        needs,
+        mood: () => moodReader.read(),
+        moodSources: moodReader,
+        schedule,
+        action: () => action,
+        phaseAt: (now) => (schedule === null ? null : schedule.phaseAt(now)),
+        update(next) {
+            if (next.dt > 0)
+                brain.advance(next.dt);
+            const now = next.now ?? 0;
+            const phase = applySchedule(now);
+            changed = false;
+            reason = null;
+            if (far) {
+                if (phase !== null) {
+                    const option = phase.travelling ? "travel" : phase.activity;
+                    const target = phase.travelling ? phase.nextPlace : phase.post;
+                    if (option !== action.option || target !== action.target) {
+                        action = {
+                            option,
+                            target,
+                            fallback: null,
+                            usedFallback: false,
+                            since: now,
+                            score: 0,
+                        };
+                        changed = true;
+                        reason = "schedule";
+                    }
+                }
+            }
+            else {
+                think(next.targets ?? [], now);
+            }
+            frame = {
+                action,
+                mood: moodReader.read(),
+                phase,
+                post: phase?.post ?? null,
+                changed,
+                reason,
+            };
+            return frame;
+        },
+        setFar(next) {
+            if (far === next)
+                return;
+            far = next;
+            changed = true;
+            reason = "schedule";
+        },
+        isFar: () => far,
+        retune(patch) {
+            brain.retune(patch);
+        },
+        snapshot: () => ({
+            needs: needs.snapshot(),
+            mood: moodReader.snapshot(),
+            brain: brain.snapshot(),
+            action: { ...action },
+            far,
+            scheduleMark,
+        }),
+        restore(next) {
+            needs.restore(next.needs);
+            moodReader.restore(next.mood);
+            brain.restore(next.brain);
+            action = { ...next.action };
+            far = next.far;
+            scheduleMark = next.scheduleMark;
+            changed = false;
+            reason = null;
+        },
+        dispose() {
+            brain.dispose();
+        },
+    };
+}

package/dist/agents/mood.d.ts

@@ -0,0 +1,74 @@
+import type { NeedSet } from "../sim/needs.js";
+/** One need's say in the mood score; weights are relative, so they need no fixed total. */
+export interface MoodWeight {
+    /** Declared need id on the agent's need set; unknown ids are ignored. */
+    readonly need: string;
+    readonly weight: number;
+}
+/** One labelled band of the 0-100 mood score. */
+export interface MoodTier {
+    readonly id: string;
+    readonly label: string;
+    /** Lowest score that reads as this tier. */
+    readonly at: number;
+}
+/** What the agent feels right now, on the caller's own tier labels. */
+export interface Mood {
+    /** 0 (nothing satisfied) . 100 (everything satisfied), plus any live source. */
+    readonly score: number;
+    readonly tier: string;
+    readonly label: string;
+}
+/**
+ * Five bands a park guest, a household being or a soldier can share. A game overrides them when its
+ * own tone needs different words; the numeric bands are what HUD counters and tests read.
+ */
+export declare const DEFAULT_MOOD_TIERS: readonly MoodTier[];
+/** Serializable mood state: the game-raised biases that sit on top of need satisfaction. */
+export interface MoodSnapshot {
+    sources: Record<string, number>;
+}
+/**
+ * The band a score reads as, from tiers sorted by `at` descending. Unknown or unsorted tiers fall
+ * back to the lowest declared band rather than throwing, because a HUD reads this every frame.
+ *
+ * @capability mood a mood derived from how satisfied an agent's needs are
+ */
+export declare function moodTierOf(score: number, tiers?: readonly MoodTier[]): MoodTier;
+/**
+ * A mood read from a need set: each declared need contributes its `0..1` satisfaction times its
+ * weight, normalized by the total weight, so an agent with four needs and one with six read on the
+ * same 0-100 scale. Pure and allocation-light - the per-frame read a HUD and a thought bubble share.
+ *
+ * @capability mood a mood derived from how satisfied an agent's needs are
+ */
+export declare function readMood(needs: Pick<NeedSet, "ids" | "fraction">, weights: readonly MoodWeight[], tiers?: readonly MoodTier[], sources?: Readonly<Record<string, number>>): Mood;
+/** A mood reader that keeps the game-raised biases, so a queue or a litter patch moves mood too. */
+export interface MoodReader {
+    /** Current mood: need satisfaction plus every live source. */
+    read(): Mood;
+    /** Raise (or lower, with a negative) one named bias; calling again replaces that source. */
+    setSource(id: string, value: number): void;
+    /** Drop one bias - the queue emptied, the litter was cleaned. */
+    clearSource(id: string): void;
+    /** Every live bias, for a debug line or a panel. */
+    sources(): Readonly<Record<string, number>>;
+    /** Replace the weights and tiers in play, keeping the biases. */
+    retune(patch: {
+        readonly weights?: readonly MoodWeight[];
+        readonly tiers?: readonly MoodTier[];
+    }): void;
+    snapshot(): MoodSnapshot;
+    restore(next: MoodSnapshot): void;
+}
+/**
+ * Create the mood an agent carries. Needs are the agent's own (shared with its utility brain), and
+ * every bias is named data the game can remove again - there is no decaying hidden penalty.
+ *
+ * @capability mood a mood derived from how satisfied an agent's needs are
+ */
+export declare function createMoodReader(config: {
+    readonly needs: Pick<NeedSet, "ids" | "fraction">;
+    readonly weights?: readonly MoodWeight[];
+    readonly tiers?: readonly MoodTier[];
+}): MoodReader;

package/dist/agents/mood.js

@@ -0,0 +1,97 @@
+import { clamp } from "../math/scalar.js";
+/**
+ * Five bands a park guest, a household being or a soldier can share. A game overrides them when its
+ * own tone needs different words; the numeric bands are what HUD counters and tests read.
+ */
+export const DEFAULT_MOOD_TIERS = [
+    { at: 82, id: "radiant", label: "Radiant" },
+    { at: 64, id: "content", label: "Content" },
+    { at: 45, id: "fine", label: "Fine" },
+    { at: 26, id: "glum", label: "Glum" },
+    { at: 0, id: "low", label: "Low" },
+];
+/**
+ * The band a score reads as, from tiers sorted by `at` descending. Unknown or unsorted tiers fall
+ * back to the lowest declared band rather than throwing, because a HUD reads this every frame.
+ *
+ * @capability mood a mood derived from how satisfied an agent's needs are
+ */
+export function moodTierOf(score, tiers = DEFAULT_MOOD_TIERS) {
+    let best = null;
+    for (const tier of tiers)
+        if (score >= tier.at && (best === null || tier.at > best.at))
+            best = tier;
+    return best ?? tiers[tiers.length - 1] ?? { at: 0, id: "low", label: "Low" };
+}
+/**
+ * A mood read from a need set: each declared need contributes its `0..1` satisfaction times its
+ * weight, normalized by the total weight, so an agent with four needs and one with six read on the
+ * same 0-100 scale. Pure and allocation-light - the per-frame read a HUD and a thought bubble share.
+ *
+ * @capability mood a mood derived from how satisfied an agent's needs are
+ */
+export function readMood(needs, weights, tiers = DEFAULT_MOOD_TIERS, sources) {
+    let total = 0;
+    let weighted = 0;
+    const declared = needs.ids();
+    for (const entry of weights) {
+        if (!(entry.weight > 0) || declared.indexOf(entry.need) < 0)
+            continue;
+        const fraction = needs.fraction(entry.need);
+        weighted += fraction * entry.weight;
+        total += entry.weight;
+    }
+    const base = total > 0 ? weighted / total : 0;
+    let bias = 0;
+    if (sources !== undefined)
+        for (const value of Object.values(sources))
+            bias += value;
+    const score = clamp(base * 100 + bias, 0, 100);
+    const tier = moodTierOf(score, tiers);
+    return { score, tier: tier.id, label: tier.label };
+}
+/**
+ * Create the mood an agent carries. Needs are the agent's own (shared with its utility brain), and
+ * every bias is named data the game can remove again - there is no decaying hidden penalty.
+ *
+ * @capability mood a mood derived from how satisfied an agent's needs are
+ */
+export function createMoodReader(config) {
+    let weights = config.weights ??
+        config.needs.ids().map((need) => ({ need, weight: 1 }));
+    let tiers = config.tiers ?? DEFAULT_MOOD_TIERS;
+    let sources = {};
+    return {
+        read: () => readMood(config.needs, weights, tiers, sources),
+        setSource(id, value) {
+            if (!Number.isFinite(value) || value === 0) {
+                const { [id]: _dropped, ...rest } = sources;
+                sources = rest;
+                return;
+            }
+            sources = { ...sources, [id]: value };
+        },
+        clearSource(id) {
+            if (!(id in sources))
+                return;
+            const { [id]: _dropped, ...rest } = sources;
+            sources = rest;
+        },
+        sources: () => ({ ...sources }),
+        retune(patch) {
+            if (patch.weights !== undefined)
+                weights = patch.weights;
+            if (patch.tiers !== undefined)
+                tiers = patch.tiers;
+        },
+        snapshot: () => ({ sources: { ...sources } }),
+        restore(next) {
+            const restored = {};
+            for (const [id, value] of Object.entries(next.sources)) {
+                if (Number.isFinite(value) && value !== 0)
+                    restored[id] = value;
+            }
+            sources = restored;
+        },
+    };
+}

package/dist/agents/relationships.d.ts

@@ -0,0 +1,92 @@
+/** One labelled bond level on the opinion scale. */
+export interface RelationshipMilestone {
+    readonly id: string;
+    readonly label: string;
+    /** Opinion at which the pair reaches this level. */
+    readonly at: number;
+    /** Familiarity the pair also needs; a bond wants time shared, not one good afternoon. */
+    readonly requiresFamiliarity?: number;
+}
+/** The pair levels every game starts from; a game overrides the words and the cut points. */
+export declare const DEFAULT_RELATIONSHIP_MILESTONES: readonly RelationshipMilestone[];
+/** How one pair stands: how much time they have shared, and what they think of each other. */
+export interface Relationship {
+    /** 0 (strangers) . 1 (they know each other well). */
+    readonly familiarity: number;
+    /** The game's opinion scale, default -100 (rivals) . 100 (inseparable). */
+    readonly opinion: number;
+}
+/** Tunables a game owns, every one reachable through {@link RelationshipBook.retune}. */
+export interface RelationshipPolicy {
+    readonly opinionMin?: number;
+    readonly opinionMax?: number;
+    readonly familiarityMax?: number;
+    readonly milestones?: readonly RelationshipMilestone[];
+}
+/** Opinion and familiarity one interaction adds; a game passes its own for a hug, a row or a shift. */
+export interface SocialContact {
+    readonly familiarity?: number;
+    readonly opinion?: number;
+}
+/** What one social action did to a pair. */
+export interface SocialOutcome {
+    readonly a: string;
+    readonly b: string;
+    readonly before: Relationship;
+    readonly after: Relationship;
+    /** Milestones newly crossed upward, lowest first - what a notice feed or a journal line reads. */
+    readonly crossed: readonly RelationshipMilestone[];
+}
+/** Serializable relationship state: every known pair plus the dials in play. */
+export interface RelationshipBookSnapshot {
+    pairs: Record<string, Relationship>;
+    policy: RelationshipPolicy;
+}
+/** What a plain social action adds: a shared moment nudges both dials, never maxes either. */
+export declare const DEFAULT_SOCIAL_CONTACT: Required<SocialContact>;
+/**
+ * Everyone's view of everyone else: familiarity and opinion per pair, changed by social actions,
+ * with the pair levels that make a friendship a preference and a bond a refusal to split.
+ *
+ * One book serves a whole world (a park, a household, a squad). Pairs are undirected, so
+ * `opinion(a, b) === opinion(b, a)` and one interaction is enough for both sides.
+ */
+export interface RelationshipBook {
+    /** How a pair stands; strangers read as `familiarity 0, opinion 0`. */
+    get(a: string, b: string): Relationship;
+    familiarity(a: string, b: string): number;
+    opinion(a: string, b: string): number;
+    /**
+     * Record one interaction between two agents. Defaults add a small amount of familiarity and
+     * opinion; a game passes a larger or negative contact for a row or a rescue. An agent's own id is
+     * ignored, so a wide query that includes the actor cannot self-bond.
+     */
+    socialise(a: string, b: string, contact?: SocialContact): SocialOutcome;
+    /** The highest milestone a pair has reached, or `null` for strangers. */
+    milestone(a: string, b: string): RelationshipMilestone | null;
+    /** Id of the highest milestone reached, or `null`. */
+    label(a: string, b: string): string | null;
+    friends(a: string, b: string): boolean;
+    /** A bonded pair. */
+    bonded(a: string, b: string): boolean;
+    /** The strongest bonded partner of `a`, or `null`. A tie keeps the first pair recorded. */
+    bondedWith(a: string): string | null;
+    /** Friends or closer - the pair prefers each other's company when both are free. */
+    prefersCompanyOf(a: string, b: string): boolean;
+    /** WHY: the rule that keeps a couple from being posted to opposite shifts is an opinion threshold, not a flag. */
+    refusesToSplit(a: string, b: string): boolean;
+    /** Every agent this one has shared anything with, sorted by id. Allocates - UI and tests. */
+    partnersOf(a: string): readonly string[];
+    policy(): Required<RelationshipPolicy>;
+    retune(patch: RelationshipPolicy): void;
+    snapshot(): RelationshipBookSnapshot;
+    restore(next: RelationshipBookSnapshot): void;
+}
+/**
+ * Create the shared book of pair state. Keys are undirected and delimiter-safe through
+ * `createPairKeyCodec`, and milestone crossings come from `crossThresholds`, so a notice feed and a
+ * journal both read the same event.
+ *
+ * @capability relationships familiarity and opinion between agents, with a bond that changes behaviour
+ */
+export declare function createRelationshipBook(policy?: RelationshipPolicy): RelationshipBook;