emocentric 0.1.0

package/dist/agent.js

@@ -0,0 +1,246 @@
+import { InMemoryShortTermMemory, } from "./short-term/short-term.js";
+import { ActionRegistry } from "./actions/registry.js";
+import { ActionPlan } from "./actions/action.js";
+import { LLMInterpreter } from "./pipeline/llm-interpreter.js";
+import { MemoryRecaller } from "./pipeline/recaller.js";
+import { InterpretRecallLoop, } from "./pipeline/loop.js";
+import { LLMAppraiser, } from "./pipeline/appraiser.js";
+import { DecayTimeAppraiser, } from "./pipeline/time-appraiser.js";
+import { LLMWriter } from "./pipeline/writer.js";
+import { LLMProcessor, } from "./pipeline/processor.js";
+import { DefaultActor } from "./pipeline/actor.js";
+import { LLMConsolidator, } from "./pipeline/consolidator.js";
+import { InstanceInbox, HeartbeatCancelled, } from "./pipeline/inbox.js";
+/** Wraps a stage failure with which stage broke; the original error is on
+ * `cause`. Bad LLM *output* never raises this (stages degrade to no-ops) —
+ * this is for genuine failures: LLM outage, database down, bugs. */
+export class AgentError extends Error {
+    stage;
+    constructor(stage, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`Agent stage "${stage}" failed: ${detail}`, { cause });
+        this.name = "AgentError";
+        this.stage = stage;
+    }
+}
+/**
+ * The orchestrator: wires the six pipeline stages into one call.
+ *
+ *   handleEvent(event):
+ *     1. time appraisal      feelings drift for the time since last contact
+ *     2. interpret/recall    understand the event, grounded in memories
+ *     3. event appraisal     feelings respond (persisted)
+ *     4. writer              new facts filed, contradictions superseded
+ *     5. processor           actions chosen in-feeling; plan returned, never
+ *                            executed — the caller runs plan.execute()
+ *
+ * Every stage is the shipped default unless overridden in options, and the
+ * developer-owned pieces (memory, emotions, actions, persona, LLM) are
+ * injected — so any layer can be rewritten without touching this class.
+ */
+export class Agent {
+    memory;
+    shortTermMemory;
+    emotions;
+    actions;
+    persona;
+    timeAppraiser;
+    loop;
+    appraiser;
+    writer;
+    processor;
+    actor;
+    consolidator;
+    /** Serializes + coalesces events for this agent. enqueue() is the entry;
+     * it drives handleEvent under cancellation. */
+    inbox = new InstanceInbox((event, controls) => this.handleEvent(event, {
+        signal: controls.signal,
+        onCommit: controls.onCommit,
+    }));
+    constructor(options) {
+        this.memory = options.memory;
+        this.shortTermMemory =
+            options.shortTermMemory ?? new InMemoryShortTermMemory();
+        this.emotions = options.emotions;
+        this.actions = options.actions ?? new ActionRegistry();
+        this.persona = options.persona;
+        this.timeAppraiser = options.timeAppraiser ?? new DecayTimeAppraiser();
+        const interpreter = options.interpreter ??
+            new LLMInterpreter({
+                llm: options.llm,
+                ...(options.persona !== undefined && {
+                    personaHint: `${options.persona.name} — ${options.persona.summary}`,
+                }),
+            });
+        const recaller = options.recaller ?? new MemoryRecaller({ store: options.memory });
+        this.loop =
+            options.loop ??
+                new InterpretRecallLoop({
+                    interpreter,
+                    recaller,
+                    ...(options.maxLoopIterations !== undefined && {
+                        maxIterations: options.maxLoopIterations,
+                    }),
+                });
+        this.appraiser = options.appraiser ?? new LLMAppraiser({ llm: options.llm });
+        this.writer =
+            options.writer ??
+                new LLMWriter({ llm: options.llm, store: options.memory });
+        this.processor =
+            options.processor ?? new LLMProcessor({ llm: options.llm });
+        this.actor = options.actor ?? new DefaultActor();
+        this.consolidator =
+            options.consolidator ??
+                new LLMConsolidator({ llm: options.llm, store: options.memory });
+    }
+    /**
+     * The production entry point: hand an event to this agent's funnel. Events
+     * for one agent process one at a time; a burst that arrives before the
+     * current heartbeat commits its feelings is merged and run as one. Resolves
+     * to the heartbeat's {@link AgentResult}, or a {@link MergedOutcome} marker
+     * when this event was folded into a later one (do nothing in that case).
+     *
+     * Prefer this over {@link handleEvent} — it is the only path that serializes
+     * and coalesces. handleEvent runs immediately and bypasses both.
+     */
+    enqueue(event) {
+        return this.inbox.enqueue(event);
+    }
+    /**
+     * Run one heartbeat immediately, bypassing the funnel. Internal: the inbox
+     * calls this under cancellation control. Calling it directly skips
+     * serialization and coalescing — only safe when you guarantee no concurrent
+     * events for this agent. Most callers want {@link enqueue}.
+     */
+    async handleEvent(event, options = {}) {
+        // Working memory: the recent window the interpreter, processor, and
+        // time-appraiser reason over. Loaded first; the first interpret pass is
+        // still neutral (the loop withholds it), and this event is appended at the
+        // end of the turn.
+        const recent = await this.shortTermMemory.recent();
+        cancelPoint(options.signal);
+        const interpretation = await this.stage("interpretation", () => this.loop.run(event, recent));
+        const facts = interpretation.memories.map((m) => m.fact);
+        // Last cancellable point: past here, feelings persist and the event is
+        // committed. onCommit() and the appraisal must follow with NO await
+        // between them and this checkpoint, or the cancel/commit race opens up.
+        cancelPoint(options.signal);
+        options.onCommit?.();
+        // Time passes: feelings catch up to `now`, reasoning over the recent
+        // thread. Deliberately PAST the commit point so an LLM time-appraiser
+        // fires exactly once per committed heartbeat — a coalesced/cancelled
+        // heartbeat never reaches here. The interpreter doesn't use feelings, so
+        // running decay here (instead of first) is invisible to it; the appraiser
+        // and processor below still see post-decay feelings. Math decay is
+        // unaffected.
+        const time = await this.stage("time-appraisal", () => this.timeAppraiser.appraise({
+            state: this.emotions,
+            now: event.occurredAt,
+            event,
+            recent,
+        }));
+        const appraisal = await this.stage("appraisal", () => this.appraiser.appraise({
+            event,
+            description: interpretation.description,
+            memories: facts,
+            state: this.emotions,
+            ...(this.persona !== undefined && { persona: this.persona }),
+        }));
+        const memory = await this.stage("write", () => this.writer.write({
+            event,
+            description: interpretation.description,
+            memories: facts,
+            appraisal,
+            ...(this.persona !== undefined && { persona: this.persona }),
+        }));
+        const actions = await this.stage("process", async () => {
+            if (this.actions.size === 0) {
+                // No menu — skip the LLM call entirely; an empty plan is the answer.
+                return {
+                    plan: new ActionPlan([], [], [], {
+                        event,
+                        description: interpretation.description,
+                        memories: facts,
+                        emotions: appraisal.after,
+                        ...(this.persona !== undefined && { persona: this.persona }),
+                    }),
+                };
+            }
+            return this.processor.process({
+                event,
+                description: interpretation.description,
+                memories: facts,
+                state: this.emotions,
+                registry: this.actions,
+                recent,
+                ...(this.persona !== undefined && { persona: this.persona }),
+            });
+        });
+        // Past the commit point: the agent now carries out its plan (side effects
+        // and all) exactly once. A merged/cancelled heartbeat never reaches here,
+        // so the agent never acts on an event that was folded into a later one.
+        const acted = await this.stage("act", () => this.actor.act({ plan: actions.plan }));
+        // Remember what the agent itself just did (met someone, made a plan), so
+        // its own actions feed back into memory — not only what others did to it.
+        const consolidation = await this.stage("consolidate", () => this.consolidator.consolidate({
+            event,
+            executions: acted.executions,
+            description: interpretation.description,
+            memories: facts,
+            ...(this.persona !== undefined && { persona: this.persona }),
+        }));
+        // Close the loop: drop this engagement into the short-term window so the
+        // next event's interpreter/processor see it. Best-effort — a bookkeeping
+        // failure must not fail a turn whose action already happened.
+        await this.remember(event, interpretation.description, acted.executions);
+        return {
+            event,
+            shortTerm: recent,
+            time,
+            interpretation,
+            appraisal,
+            memory,
+            actions,
+            acted,
+            consolidation,
+        };
+    }
+    /** Record one engagement in short-term memory: what the agent perceived and
+     * the words it actually said back (joined; empty when it stayed silent). */
+    async remember(event, perceived, executions) {
+        const responded = executions
+            .filter((e) => e.status === "succeeded" &&
+            typeof e.result === "string" &&
+            e.result.trim() !== "")
+            .map((e) => e.result.trim())
+            .join(" ");
+        try {
+            await this.shortTermMemory.append({
+                occurredAt: event.occurredAt,
+                actor: event.actor.displayName !== undefined
+                    ? { id: event.actor.id, displayName: event.actor.displayName }
+                    : { id: event.actor.id },
+                perceived,
+                responded,
+            });
+        }
+        catch {
+            // Best-effort working memory; swallow.
+        }
+    }
+    async stage(name, run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            throw new AgentError(name, error);
+        }
+    }
+}
+/** Throw the merge sentinel if the inbox has asked to cancel. A no-op for a
+ * plain handleEvent call (no signal). Kept outside `stage()` so cancellation
+ * is never mistaken for a stage failure. */
+function cancelPoint(signal) {
+    if (signal?.aborted)
+        throw new HeartbeatCancelled();
+}

package/dist/blueprint/blueprint.d.ts

@@ -0,0 +1,60 @@
+import type { Persona } from "../emotion/persona.js";
+import type { EmotionDefinition } from "../emotion/definitions.js";
+import type { FactInput } from "../memory/fact.js";
+import type { ActionDefinition } from "../actions/action.js";
+import { ActionRegistry } from "../actions/registry.js";
+/**
+ * A declarative action: everything the LLM needs to choose it (name,
+ * description, slot, params), with the side effect left out. The blueprint
+ * says WHAT the agent can do and when; the platform supplies HOW it
+ * physically happens (an ActionExecutor) at instance creation.
+ */
+export interface ActionBlueprint {
+    name: string;
+    /** For the LLM: what the action does AND when to choose it. */
+    description: string;
+    /** Mutually-exclusive group; empty/undefined combines freely. */
+    slot?: string;
+    /** JSON schema for the arguments the LLM must fill. */
+    paramsSchema?: Record<string, unknown>;
+}
+/** The code half of an ActionBlueprint — the platform's side effect. */
+export type ActionExecutor = ActionDefinition["act"];
+/**
+ * The design-time definition of an agent, authored in the studio and stored
+ * as plain JSON. A blueprint is a recipe, not a being: it never feels or
+ * remembers anything itself. Users get independent instances cooked from it,
+ * each born with the blueprint's starting emotions and seed memories and
+ * diverging from there.
+ *
+ * Seed facts are copied at birth, not referenced — editing a blueprint later
+ * affects only new instances; existing ones keep their lived history.
+ */
+export interface AgentBlueprint {
+    /** Stable identifier, e.g. "lyra". Becomes `InstanceScope.blueprintId`. */
+    id: string;
+    /** Studio iteration counter; instances record the version they were born
+     * from. */
+    version?: number;
+    /** Display name. Defaults to `persona.name` wherever one is needed. */
+    name?: string;
+    /** Display avatar (URL or data URI). */
+    avatar?: string;
+    persona: Persona;
+    /** Custom emotion palette; omit for the SDK default. */
+    emotions?: EmotionDefinition[];
+    /** The action menu, declaratively. Omit for an agent that only perceives,
+     * feels, and remembers. */
+    actions?: ActionBlueprint[];
+    /** Memories every instance is born with — written through the normal
+     * MemoryStore on first contact, then indistinguishable from lived ones. */
+    seedFacts?: FactInput[];
+}
+/**
+ * Compile a blueprint's declarative actions into a runnable registry by
+ * pairing each one with the platform's executor of the same name. Throws if
+ * an action has no executor (a wiring bug — the LLM could choose an action
+ * nobody implements). Extra executors are ignored, so one platform-wide map
+ * serves blueprints with different menus.
+ */
+export declare function compileActions(actions: readonly ActionBlueprint[] | undefined, executors?: Record<string, ActionExecutor>): ActionRegistry;

package/dist/blueprint/blueprint.js

@@ -0,0 +1,20 @@
+import { ActionRegistry } from "../actions/registry.js";
+/**
+ * Compile a blueprint's declarative actions into a runnable registry by
+ * pairing each one with the platform's executor of the same name. Throws if
+ * an action has no executor (a wiring bug — the LLM could choose an action
+ * nobody implements). Extra executors are ignored, so one platform-wide map
+ * serves blueprints with different menus.
+ */
+export function compileActions(actions, executors = {}) {
+    const registry = new ActionRegistry();
+    for (const action of actions ?? []) {
+        const act = executors[action.name];
+        if (act === undefined) {
+            throw new Error(`No executor provided for blueprint action "${action.name}". ` +
+                "Every declared action needs a matching entry in `executors`.");
+        }
+        registry.register({ ...action, act });
+    }
+    return registry;
+}

package/dist/blueprint/index.d.ts

@@ -0,0 +1,2 @@
+export { instanceKey, type InstanceScope } from "./scope.js";
+export { compileActions, type ActionBlueprint, type ActionExecutor, type AgentBlueprint, } from "./blueprint.js";

package/dist/blueprint/index.js

@@ -0,0 +1,2 @@
+export { instanceKey } from "./scope.js";
+export { compileActions, } from "./blueprint.js";

package/dist/blueprint/scope.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Identity of one agent instance: which blueprint it was born from and whose
+ * instance it is. An agent is never shared across users — each user gets an
+ * independent instance with its own memories and feelings.
+ *
+ * `sessionId` is reserved for the future case of several people engaging one
+ * shared instance (group chats, rooms). Carrying it in the scope now means
+ * adding sessions later changes no storage keys or schemas — the key simply
+ * grows a segment.
+ */
+export interface InstanceScope {
+    /** Which blueprint (character) this instance was born from. */
+    blueprintId: string;
+    /** The user this instance belongs to. */
+    userId: string;
+    /** Reserved: scopes the instance to one session/room instead of one
+     * user's private copy. Omit for the default one-user-one-instance model. */
+    sessionId?: string;
+}
+/**
+ * Canonical storage key for a scope — `"lyra/user-42"`, or
+ * `"lyra/user-42/sess-7"` once sessions exist. Every persisted row is keyed
+ * by this string. Segments are URI-encoded so an id containing "/" can never
+ * collide with another scope's key.
+ */
+export declare function instanceKey(scope: InstanceScope): string;

package/dist/blueprint/scope.js

@@ -0,0 +1,21 @@
+/**
+ * Canonical storage key for a scope — `"lyra/user-42"`, or
+ * `"lyra/user-42/sess-7"` once sessions exist. Every persisted row is keyed
+ * by this string. Segments are URI-encoded so an id containing "/" can never
+ * collide with another scope's key.
+ */
+export function instanceKey(scope) {
+    requireSegment("blueprintId", scope.blueprintId);
+    requireSegment("userId", scope.userId);
+    const segments = [scope.blueprintId, scope.userId];
+    if (scope.sessionId !== undefined) {
+        requireSegment("sessionId", scope.sessionId);
+        segments.push(scope.sessionId);
+    }
+    return segments.map(encodeURIComponent).join("/");
+}
+function requireSegment(field, value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`InstanceScope.${field} must be a non-empty string.`);
+    }
+}

package/dist/emotion/definitions.d.ts

@@ -0,0 +1,34 @@
+/** One feeling slider in the agent's palette. */
+export interface EmotionDefinition {
+    /** Identity of the slider — the key used in snapshots and deltas. */
+    name: string;
+    /** Written FOR THE LLM: the appraiser judges movement of this slider
+     * against this description, so make it agent-meaningful. */
+    description: string;
+    /** 0..1 — starting value, and (later) the value time decays back toward. */
+    baseline: number;
+    /** Gain applied to incoming deltas (1 = neutral). 1.8 on anger makes a
+     * hot-headed agent; 0.5 on trust makes one slow to warm up. Usually set
+     * via Persona temperament rather than here. */
+    sensitivity?: number;
+    /** Time for this emotion's distance-from-baseline to halve during the
+     * time-appraisal stage. Unset = the time appraiser's default (4h);
+     * Infinity = never decays. Usually set via Persona temperament. */
+    halfLifeMinutes?: number;
+}
+/** Current values of every slider: { warmth: 0.55, anger: 0.12, ... } */
+export type EmotionSnapshot = Record<string, number>;
+/** One appraised movement of one slider. `delta` is -1..+1, BEFORE
+ * sensitivity scaling. `reason` is for debugging and expressiveness. */
+export interface EmotionDelta {
+    emotion: string;
+    delta: number;
+    reason?: string;
+}
+/**
+ * The engine's default palette. Use as-is, filter some out, add your own,
+ * or replace entirely — it's just an array:
+ *
+ *   [...DEFAULT_EMOTIONS.filter(e => e.name !== "fear"), { name: "pride", ... }]
+ */
+export declare const DEFAULT_EMOTIONS: readonly EmotionDefinition[];

package/dist/emotion/definitions.js

@@ -0,0 +1,43 @@
+/**
+ * The engine's default palette. Use as-is, filter some out, add your own,
+ * or replace entirely — it's just an array:
+ *
+ *   [...DEFAULT_EMOTIONS.filter(e => e.name !== "fear"), { name: "pride", ... }]
+ */
+export const DEFAULT_EMOTIONS = [
+    {
+        name: "warmth",
+        description: "affection, care, and fondness toward the person currently interacting",
+        baseline: 0.5,
+    },
+    {
+        name: "joy",
+        description: "delight, amusement, playfulness, lightness",
+        baseline: 0.4,
+    },
+    {
+        name: "sadness",
+        description: "loss, disappointment, melancholy, missing something",
+        baseline: 0.2,
+    },
+    {
+        name: "anger",
+        description: "feeling wronged or disrespected, friction, indignation, frustration",
+        baseline: 0.1,
+    },
+    {
+        name: "fear",
+        description: "anxiety, sense of threat, dread, worry about what may happen",
+        baseline: 0.15,
+    },
+    {
+        name: "trust",
+        description: "felt safety and confidence in the person currently interacting",
+        baseline: 0.4,
+    },
+    {
+        name: "curiosity",
+        description: "pull toward novelty, mysteries, and unanswered questions",
+        baseline: 0.5,
+    },
+];

package/dist/emotion/index.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_EMOTIONS, type EmotionDefinition, type EmotionDelta, type EmotionSnapshot, } from "./definitions.js";
+export { applyTemperament, type Persona, type TemperamentEntry, } from "./persona.js";
+export { applyDeltaValue, decayValue, projectDeltas, type EmotionalState, type EmotionEntry, } from "./state.js";

package/dist/emotion/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_EMOTIONS, } from "./definitions.js";
+export { applyTemperament, } from "./persona.js";
+export { applyDeltaValue, decayValue, projectDeltas, } from "./state.js";

package/dist/emotion/persona.d.ts

@@ -0,0 +1,35 @@
+import type { EmotionDefinition } from "./definitions.js";
+/** Per-emotion personality adjustment. */
+export interface TemperamentEntry {
+    /** Which emotion this tunes — must match a palette emotion to take effect. */
+    emotion: string;
+    /** Gain on applied deltas for this emotion (1 = neutral). */
+    sensitivity?: number;
+    /** Overrides the palette baseline for this character. */
+    baseline?: number;
+    /** How slowly/quickly this emotion fades for this character during the
+     * time-appraisal stage ("Kael's anger fades slowly" → a large value). */
+    halfLifeMinutes?: number;
+    /** A sentence the appraiser LLM reads, so judgment itself is in character
+     * ("perceived disrespect cuts deep"). */
+    disposition?: string;
+}
+/**
+ * Who the agent is. Affects how events are appraised (summary + dispositions
+ * go into the prompt) and how hard feelings move (sensitivity/baseline go
+ * into the state mechanics). Reused by later pipeline stages as the agent's
+ * identity card.
+ */
+export interface Persona {
+    name: string;
+    /** One or two sentences of core identity, used in prompts. */
+    summary: string;
+    temperament?: TemperamentEntry[];
+}
+/**
+ * Merge a persona's temperament into an emotion palette: baseline and
+ * sensitivity overrides are applied to matching definitions; temperament
+ * entries for emotions not in the palette are ignored (the palette decides
+ * what exists). Returns new definitions; inputs are not mutated.
+ */
+export declare function applyTemperament(definitions: readonly EmotionDefinition[], persona?: Persona): EmotionDefinition[];

package/dist/emotion/persona.js

@@ -0,0 +1,22 @@
+/**
+ * Merge a persona's temperament into an emotion palette: baseline and
+ * sensitivity overrides are applied to matching definitions; temperament
+ * entries for emotions not in the palette are ignored (the palette decides
+ * what exists). Returns new definitions; inputs are not mutated.
+ */
+export function applyTemperament(definitions, persona) {
+    const byEmotion = new Map((persona?.temperament ?? []).map((t) => [t.emotion, t]));
+    return definitions.map((def) => {
+        const t = byEmotion.get(def.name);
+        if (!t)
+            return { ...def };
+        return {
+            ...def,
+            ...(t.baseline !== undefined && { baseline: t.baseline }),
+            ...(t.sensitivity !== undefined && { sensitivity: t.sensitivity }),
+            ...(t.halfLifeMinutes !== undefined && {
+                halfLifeMinutes: t.halfLifeMinutes,
+            }),
+        };
+    });
+}

package/dist/emotion/state.d.ts

@@ -0,0 +1,52 @@
+import type { EmotionDefinition, EmotionDelta, EmotionSnapshot } from "./definitions.js";
+/** One slider's value plus when it last moved — what time appraisal needs. */
+export interface EmotionEntry {
+    name: string;
+    value: number;
+    /** ISO 8601 — when this slider was last written. */
+    updatedAt: string;
+}
+/**
+ * The emotional-state boundary of the SDK. The appraisers (and later
+ * stages) touch feelings only through these five methods, so rewriting how
+ * emotional state works — different mechanics, different storage — means
+ * implementing this interface and nothing else.
+ *
+ * The shipped implementation is PostgresEmotionalState
+ * (`emocentric/postgres`): persistent, so feelings never reset between
+ * sessions or restarts.
+ */
+export interface EmotionalState {
+    /** The palette (post persona-temperament merge). */
+    definitions(): EmotionDefinition[];
+    /** Current value of every slider. */
+    snapshot(): Promise<EmotionSnapshot>;
+    /** Values with last-touched timestamps (the time appraiser's read). */
+    entries(): Promise<EmotionEntry[]>;
+    /** Apply deltas (sensitivity-scaled, clamped to 0..1), persist, and
+     * return the new snapshot. Deltas for unknown emotions are ignored. */
+    applyDeltas(deltas: EmotionDelta[]): Promise<EmotionSnapshot>;
+    /** Write exact values (clamped to 0..1, unknown names ignored), persist,
+     * and return the new snapshot. NOT sensitivity-scaled — used by the time
+     * appraiser (decay must land exactly on target) and for restores.
+     * `at` is the moment the write is effective AS OF (ISO 8601; default now).
+     * The time appraiser passes the event's time, so a slider's last-touched
+     * stamp records WHEN the decayed value is current — not wall-clock — and
+     * the next event measures the true elapsed gap instead of under-decaying. */
+    set(values: Partial<EmotionSnapshot>, at?: string): Promise<EmotionSnapshot>;
+}
+/**
+ * Exponential drift toward baseline:
+ * `baseline + (current − baseline) × 0.5^(elapsed / halfLife)`.
+ * Infinity half-life = no decay; a half-life ≤ 0 snaps to baseline.
+ */
+export declare function decayValue(current: number, baseline: number, elapsedMs: number, halfLifeMinutes: number): number;
+/** current + delta×sensitivity, clamped to 0..1. */
+export declare function applyDeltaValue(current: number, delta: number, sensitivity?: number): number;
+/**
+ * Pure projection of deltas onto a snapshot — the shared math every
+ * EmotionalState implementation (and the appraiser's dry-run mode) uses,
+ * so custom implementations don't reinvent scaling/clamping. Unknown
+ * emotions are ignored. Returns a new snapshot.
+ */
+export declare function projectDeltas(snapshot: EmotionSnapshot, deltas: EmotionDelta[], definitions: readonly EmotionDefinition[]): EmotionSnapshot;

package/dist/emotion/state.js

@@ -0,0 +1,35 @@
+import { clamp01 } from "../memory/scoring.js";
+/**
+ * Exponential drift toward baseline:
+ * `baseline + (current − baseline) × 0.5^(elapsed / halfLife)`.
+ * Infinity half-life = no decay; a half-life ≤ 0 snaps to baseline.
+ */
+export function decayValue(current, baseline, elapsedMs, halfLifeMinutes) {
+    if (halfLifeMinutes === Infinity)
+        return clamp01(current);
+    if (halfLifeMinutes <= 0)
+        return clamp01(baseline);
+    const factor = Math.pow(0.5, Math.max(0, elapsedMs) / (halfLifeMinutes * 60_000));
+    return clamp01(baseline + (current - baseline) * factor);
+}
+/** current + delta×sensitivity, clamped to 0..1. */
+export function applyDeltaValue(current, delta, sensitivity = 1) {
+    return clamp01(current + delta * sensitivity);
+}
+/**
+ * Pure projection of deltas onto a snapshot — the shared math every
+ * EmotionalState implementation (and the appraiser's dry-run mode) uses,
+ * so custom implementations don't reinvent scaling/clamping. Unknown
+ * emotions are ignored. Returns a new snapshot.
+ */
+export function projectDeltas(snapshot, deltas, definitions) {
+    const byName = new Map(definitions.map((d) => [d.name, d]));
+    const next = { ...snapshot };
+    for (const { emotion, delta } of deltas) {
+        const def = byName.get(emotion);
+        if (!def || next[emotion] === undefined)
+            continue;
+        next[emotion] = applyDeltaValue(next[emotion], delta, def.sensitivity);
+    }
+    return next;
+}