@adam0white/human-framework 2.10.0 → 2.12.0

package/dist/cognition/cognition.js

@@ -40,6 +40,7 @@ import { agendaTermsWithGoalEstimates } from '../agenda/index.js';
 import { trustOf } from '../beliefs/index.js';
 import { normTerms } from '../conscience/index.js';
 import { clamp01, cmpStr, dexp, minuteOfDay, round } from '../core/index.js';
+import { curiosityTerms } from '../curiosity/index.js';
 import { habitEase, habitPull } from '../habits/index.js';
 import { expectedEffect } from '../memory/index.js';
 import { methodEvidence } from '../methods/index.js';
@@ -247,6 +248,12 @@ function materialValue(p, material, scarcity) {
     const sat = Math.sign(material) * (1 - dexp(-Math.abs(material) / scale));
     return K.materialWeight * sat * 2 * weight * (1 + K.scarcityMaterialGain * scarcity);
 }
+/** Shared whole-route valuation for scoring and the read-only plan readout. @internal */
+export function prospectiveRoute(p, aff, ctx) {
+    const scarcity = clamp01(Number.isFinite(ctx.scarcity) ? ctx.scarcity : 0);
+    return receivedGoalRoute(p, aff, ctx.now, 0.5 + 0.5 * clamp01(ctx.mods.maturity), (successor) => effortValue(p, successor, ctx) +
+        (successor.material ? materialValue(p, successor.material, scarcity) : 0));
+}
 /** Needs whose consumption can overfill (2.8.0 fullness): what `body.consume` feeds. */
 const FULL_NEEDS = ['food', 'water', 'relief'];
 /** Score one option. Pure apart from reads; terms are rounded for stable snapshots. */
@@ -327,12 +334,11 @@ export function consider(p, aff, ctx) {
     }
     const maturity = clamp01(ctx.mods.maturity);
     const maturityScale = 0.5 + 0.5 * maturity;
-    const received = receivedGoalRoute(p, aff, ctx.now, maturityScale, (successor) => effortValue(p, successor, ctx) +
-        (successor.material ? materialValue(p, successor.material, scarcity) : 0));
+    const received = prospectiveRoute(p, aff, ctx);
     for (const t of agendaTermsWithGoalEstimates(p, aff, ctx.now, received?.goals))
         push(t.source, t.value * maturityScale);
     if (received)
-        push(received.cost.source, received.cost.value);
+        push(received.cost.source, received.cost.value, received.cost.ref);
     // Habit: cue-matched automaticity (cued by the option's own place), stronger before planning matures.
     const habit = p.habits.length === 0
         ? 0
@@ -452,6 +458,9 @@ export function consider(p, aff, ctx) {
     if (!inBreak(p))
         for (const t of rememberedTerms(p, aff, ctx.now, voices))
             push(t.source, t.value);
+    if (p.curiosity)
+        for (const t of curiosityTerms(p, aff, ctx))
+            push(t.source, t.value);
     // Promptings (2.4.0, opt-in): a recurrence pull under `fault` and a practised turning-away from a noticed prompt.
     if (p.promptings)
         for (const t of promptingTerms(p, aff.action, terms, aff.tags, ctx.now, ctx.desperation))

package/dist/curiosity/curiosity.d.ts

@@ -0,0 +1,28 @@
+import type { ConsiderContext } from '../cognition/index.ts';
+import type { Affordance, CuriosityReading, CuriositySpec, CuriosityState, Minute, Outcome, Person, Term } from '../types.ts';
+/** Engineering defaults: unknown .8 exceeds mild effort (.1 base) and learned pleasure (.6 scale).
+ * Need relief uses cognition's scale 4; urgency and fear also suppress this entire drive.
+ */
+export declare const CURIOSITY_DEFAULTS: {
+    readonly unknownScale: 0.8;
+    readonly progressScale: 2;
+    readonly varyScale: 0.15;
+    readonly recentMinutes: 60;
+    readonly rewardMax: 0.03;
+    readonly fastAlpha: 0.5;
+    readonly slowAlpha: 0.15;
+    readonly maxKeys: 32;
+    readonly maxRecent: 8;
+};
+/** Enable or reconfigure; retain the bounded history. Invalid overrides use defaults. */
+export declare function enableCuriosity(p: Person, spec?: CuriositySpec): CuriosityState;
+type Context = Pick<ConsiderContext, 'needs' | 'mods' | 'now'>;
+/** Read raw signals and drive without mutation or RNG. `now` changes only the recent-act window. */
+export declare function curiosityOf(p: Person, aff: Affordance, now?: Minute): CuriosityReading;
+/** Cognition uses the actual decision context, including perceived needs. Fixed term order. */
+export declare function curiosityTerms(p: Person, aff: Affordance, ctx: Context): Term[];
+/** Called before memory learns this outcome. Needs owner applies the small, bounded reward. */
+export declare function noteCuriosity(p: Person, aff: Affordance, outcome: Outcome, felt: number): void;
+/** Conservative restore: drop malformed or ambiguous slices; skip malformed entries and bound lists. */
+export declare function sanitizeCuriosity(input: unknown, now: Minute): CuriosityState | undefined;
+export {};

package/dist/curiosity/curiosity.js

@@ -0,0 +1,190 @@
+/**
+ * SCOPE: opt-in intrinsic exploration and play. Uncertainty draws a relaxed person toward unfamiliar
+ * offers; falling prediction error (learning progress) pulls and rewards; recent action kinds invite variation in target or
+ * place. Shapes, not fitted values: learning progress (Oudeyer, Kaplan & Hafner 2007), information gaps
+ * (Loewenstein 1994; Kidd & Hayden 2015; Gottlieb et al. 2013), effectance and competence (White 1959;
+ * Deci & Ryan), relaxed repetition with variation (Burghardt 2005), openness (DeYoung), childhood
+ * exploration (Gopnik 2020). See research/curiosity-and-play.md. All coefficients are engineering defaults.
+ * This owns only p.curiosity. It neither adopts projects nor plans, reads no host novelty tags, and
+ * implements no faith lens, LLM or RNG. Without the slice it adds no state, terms or reward.
+ */
+import { emotionLevel } from '../affect/index.js';
+import { clamp01, isNum, isObj, round } from '../core/index.js';
+import { lifeModifiers } from '../lifecourse/index.js';
+import { expectationKey, expectedEffect } from '../memory/index.js';
+import { satisfy } from '../needs/index.js';
+import { readPerson } from '../person.js';
+import { MAX_MINUTE, PHYSIOLOGICAL_NEEDS } from '../types.js';
+/** Engineering defaults: unknown .8 exceeds mild effort (.1 base) and learned pleasure (.6 scale).
+ * Need relief uses cognition's scale 4; urgency and fear also suppress this entire drive.
+ */
+export const CURIOSITY_DEFAULTS = {
+    unknownScale: 0.8,
+    progressScale: 2,
+    varyScale: 0.15,
+    recentMinutes: 60,
+    rewardMax: 0.03,
+    fastAlpha: 0.5,
+    slowAlpha: 0.15,
+    maxKeys: 32,
+    maxRecent: 8,
+};
+const SPEC_KEYS = ['unknownScale', 'progressScale', 'varyScale', 'recentMinutes', 'rewardMax'];
+function cleanSpec(input) {
+    const out = {};
+    if (!isObj(input))
+        return out;
+    for (const key of SPEC_KEYS) {
+        const x = input[key];
+        const max = key === 'recentMinutes' ? 1440 : CURIOSITY_DEFAULTS[key];
+        if (isNum(x) && x >= 0 && x <= max)
+            out[key] = x;
+    }
+    return out;
+}
+const setting = (s, key) => s.spec?.[key] ?? CURIOSITY_DEFAULTS[key];
+/** Enable or reconfigure; retain the bounded history. Invalid overrides use defaults. */
+export function enableCuriosity(p, spec = {}) {
+    const out = { errors: p.curiosity?.errors ?? [], recent: p.curiosity?.recent ?? [] };
+    const clean = cleanSpec(spec);
+    if (Object.keys(clean).length)
+        out.spec = clean;
+    p.curiosity = out;
+    return out;
+}
+/** Identifiers the slice records and restores; longer ones are not tracked, so a save round-trips. */
+const str = (x) => typeof x === 'string' && x.length > 0 && x.length <= 512;
+function reading(p, aff, ctx) {
+    const s = p.curiosity;
+    if (!s)
+        return { unknown: 0, progress: 0, vary: 0, drive: 0 };
+    let urgency = 0;
+    for (const n of ctx.needs)
+        if (n.id === 'safety' || PHYSIOLOGICAL_NEEDS.includes(n.id))
+            urgency = Math.max(urgency, n.urgency);
+    const drive = (1 - clamp01(urgency)) *
+        (1 - emotionLevel(p, 'fear')) *
+        (0.25 + 0.75 * p.traits.openness) *
+        (1.25 - 0.5 * ctx.mods.maturity);
+    const error = s.errors.find((e) => e.key === expectationKey(aff));
+    const recent = s.recent.filter((r) => r.at <= ctx.now && ctx.now - r.at <= setting(s, 'recentMinutes') && r.action === aff.action);
+    const identical = recent.some((r) => r.targetId === aff.targetId && r.placeId === aff.placeId);
+    return {
+        unknown: clamp01(1 - expectedEffect(p, aff).confidence),
+        progress: error ? clamp01(error.slow - error.fast) : 0,
+        vary: !identical && recent.length > 0 ? 1 : 0,
+        drive,
+    };
+}
+/** Read raw signals and drive without mutation or RNG. `now` changes only the recent-act window. */
+export function curiosityOf(p, aff, now = p.now) {
+    if (!p.curiosity)
+        return { unknown: 0, progress: 0, vary: 0, drive: 0 };
+    return reading(p, aff, { now, needs: readPerson(p).needs, mods: lifeModifiers(p) });
+}
+/** Cognition uses the actual decision context, including perceived needs. Fixed term order. */
+export function curiosityTerms(p, aff, ctx) {
+    const s = p.curiosity;
+    if (!s)
+        return [];
+    const r = reading(p, aff, ctx);
+    return ['unknown', 'progress', 'vary'].map((key) => ({
+        source: `curiosity:${key}`,
+        value: round(Math.min(setting(s, `${key}Scale`), setting(s, `${key}Scale`) * r[key] * r.drive)),
+    }));
+}
+/** Called before memory learns this outcome. Needs owner applies the small, bounded reward. */
+export function noteCuriosity(p, aff, outcome, felt) {
+    const s = p.curiosity;
+    if (!s || outcome.status === 'interrupted')
+        return;
+    const before = curiosityOf(p, aff);
+    const expected = expectedEffect(p, aff);
+    const error = clamp01((Math.abs((outcome.status === 'completed' ? 1 : 0) - expected.successRate) +
+        Math.abs(felt - expected.valence) / 2) /
+        2);
+    const key = expectationKey(aff);
+    if (!str(key) ||
+        !str(aff.action) ||
+        (aff.targetId !== undefined && !str(aff.targetId)) ||
+        (aff.placeId !== undefined && !str(aff.placeId)))
+        return;
+    let entry = s.errors.find((e) => e.key === key);
+    if (!entry) {
+        if (s.errors.length >= CURIOSITY_DEFAULTS.maxKeys) {
+            let oldest = 0;
+            let oldestAt = s.errors[0]?.lastAt ?? p.now;
+            for (const [i, held] of s.errors.entries()) {
+                if (held.lastAt < oldestAt) {
+                    oldest = i;
+                    oldestAt = held.lastAt;
+                }
+            }
+            s.errors.splice(oldest, 1);
+        }
+        entry = { key, fast: error, slow: error, n: 1, lastAt: p.now };
+        s.errors.push(entry);
+    }
+    else {
+        entry.fast = clamp01(entry.fast + CURIOSITY_DEFAULTS.fastAlpha * (error - entry.fast));
+        entry.slow = clamp01(entry.slow + CURIOSITY_DEFAULTS.slowAlpha * (error - entry.slow));
+        entry.n = Math.min(Number.MAX_SAFE_INTEGER, entry.n + 1);
+        entry.lastAt = p.now;
+    }
+    const act = { action: aff.action, at: p.now };
+    if (aff.targetId !== undefined)
+        act.targetId = aff.targetId;
+    if (aff.placeId !== undefined)
+        act.placeId = aff.placeId;
+    s.recent.push(act);
+    if (s.recent.length > CURIOSITY_DEFAULTS.maxRecent)
+        s.recent.shift();
+    const progress = Math.max(0, entry.slow - entry.fast);
+    const reward = Math.min(setting(s, 'rewardMax'), setting(s, 'rewardMax') * progress * before.drive);
+    satisfy(p, { leisure: reward / 2, competence: reward / 2 });
+}
+const unit = (x) => isNum(x) && x >= 0 && x <= 1;
+const minute = (x, now) => isNum(x) && Math.abs(x) <= MAX_MINUTE && x <= now;
+/** Conservative restore: drop malformed or ambiguous slices; skip malformed entries and bound lists. */
+export function sanitizeCuriosity(input, now) {
+    if (!isObj(input) || !Array.isArray(input.errors) || !Array.isArray(input.recent))
+        return undefined;
+    if (input.spec !== undefined && !isObj(input.spec))
+        return undefined;
+    const out = { errors: [], recent: [] };
+    if (input.spec !== undefined) {
+        const spec = cleanSpec(input.spec);
+        if (Object.keys(spec).length !== Object.keys(input.spec).length)
+            return undefined;
+        if (Object.keys(spec).length)
+            out.spec = spec;
+    }
+    const seen = new Set();
+    for (const e of input.errors.slice(0, CURIOSITY_DEFAULTS.maxKeys)) {
+        if (!isObj(e) ||
+            !str(e.key) ||
+            !unit(e.fast) ||
+            !unit(e.slow) ||
+            !minute(e.lastAt, now) ||
+            !Number.isSafeInteger(e.n) ||
+            e.n < 1)
+            continue;
+        if (seen.has(e.key))
+            return undefined;
+        seen.add(e.key);
+        out.errors.push({ key: e.key, fast: e.fast, slow: e.slow, n: e.n, lastAt: e.lastAt });
+    }
+    for (const r of input.recent.slice(-CURIOSITY_DEFAULTS.maxRecent)) {
+        if (!isObj(r) || !str(r.action) || !minute(r.at, now))
+            continue;
+        if ((r.targetId !== undefined && !str(r.targetId)) || (r.placeId !== undefined && !str(r.placeId)))
+            continue;
+        const act = { action: r.action, at: r.at };
+        if (r.targetId !== undefined)
+            act.targetId = r.targetId;
+        if (r.placeId !== undefined)
+            act.placeId = r.placeId;
+        out.recent.push(act);
+    }
+    return out;
+}

package/dist/curiosity/index.d.ts

@@ -0,0 +1 @@
+export * from './curiosity.ts';

package/dist/curiosity/index.js

@@ -0,0 +1 @@
+export * from './curiosity.js';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.10.0";
+export declare const FRAMEWORK_VERSION = "2.12.0";
 export type { CrisisEvent, PracticeKind } from './affect/index.ts';
 export { AFFECT_DEFAULTS, actionTendencies, advanceAffect, appraise, breakAllows, breakBehaviour, breakHazard, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, enableBreaks, feel, inBreak, readAffect, regulate, release as releaseEmotion, skipCrisis, strain, tendencyEmotions, } from './affect/index.ts';
 export type { GoalTemplate, PrayerCalendar, PrayerSchedule, PrayerTimes, Retimer, } from './agenda/index.ts';
@@ -13,6 +13,7 @@ export { COGNITION_DEFAULTS, consider, decide as scoreAndResolve, desperationOf,
 export * from './conscience/index.ts';
 export * from './conversation/index.ts';
 export * from './core/index.ts';
+export { CURIOSITY_DEFAULTS, curiosityOf, enableCuriosity } from './curiosity/index.ts';
 export * from './environment/index.ts';
 export * from './family/index.ts';
 export * from './habits/index.ts';
@@ -29,8 +30,8 @@ export * from './needs/index.ts';
 export * from './partnering/index.ts';
 export * from './person.ts';
 export * from './promptings/index.ts';
-export type { ConsequenceEvidence } from './prospection/index.ts';
-export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, } from './prospection/index.ts';
+export type { ConsequenceEvidence, PlanRoute, PlanStep } from './prospection/index.ts';
+export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, enablePlanning, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, seedConsequences, } from './prospection/index.ts';
 export { fingerprint, restore, snapshot } from './restore.ts';
 export * from './review/index.ts';
 export * from './scenarios/index.ts';

package/dist/index.js

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export const FRAMEWORK_VERSION = '2.10.0';
+export const FRAMEWORK_VERSION = '2.12.0';
 export { AFFECT_DEFAULTS, actionTendencies, advanceAffect, appraise, breakAllows, breakBehaviour, breakHazard, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, enableBreaks, feel, inBreak, readAffect, regulate, release as releaseEmotion, skipCrisis, strain, tendencyEmotions, } from './affect/index.js';
 // `agenda.release` collides with `affect.release`; the agenda one is re-exported under a clearer name.
 export { AGENDA_DEFAULTS, abandonGoal, adoptGoal, advanceAgenda, agendaTerms, applyExemptions, CARE_DEFAULTS, calendarRetimer, careDuty, commitmentPressure, createAgenda, DEFAULT_PRAYER_TIMES, EID_PRAYER_IMPORTANCE, EXEMPTION_DEFAULTS, eidPrayer, eidWindow, fastWindow, iftarWindow, inMakruhTime, isUnderWay, MAKRUH_DEFAULTS, makruhWindows, missedExcuse, onFinished, owedMakeUps, PRAYER_IMPORTANCE, PURPOSE_DEFAULTS, prayerWindows, pressureReachedAt, promise, proposeGoals, RAMADAN_DEFAULTS, ramadanFast, ramadanMeals, release as releaseCommitment, retimeCommitments, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.js';
@@ -12,6 +12,7 @@ export { COGNITION_DEFAULTS, consider, decide as scoreAndResolve, desperationOf,
 export * from './conscience/index.js';
 export * from './conversation/index.js';
 export * from './core/index.js';
+export { CURIOSITY_DEFAULTS, curiosityOf, enableCuriosity } from './curiosity/index.js';
 export * from './environment/index.js';
 export * from './family/index.js';
 export * from './habits/index.js';
@@ -26,7 +27,7 @@ export * from './needs/index.js';
 export * from './partnering/index.js';
 export * from './person.js';
 export * from './promptings/index.js';
-export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, } from './prospection/index.js';
+export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, enablePlanning, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, seedConsequences, } from './prospection/index.js';
 export { fingerprint, restore, snapshot } from './restore.js';
 export * from './review/index.js';
 export * from './scenarios/index.js';

package/dist/migrate.js

@@ -18,7 +18,7 @@
  * version; fullness stays absent unless enabled, and alongside partners and reconsideration are opt-in.
  * 2.8.0 to 2.9.0 stamps the version; prompting cues and practice half-lives stay absent unless supplied,
  * review terms may carry refs, and an outcome naming several commitments now keeps each rather than only
- * the earliest-ending one. 2.9.0 to 2.10.0 stamps the version; belief provenance, noted contradictions and
+ * the earliest-ending one. 2.11.0 to 2.12.0 stamps the version (planning starts absent). 2.10.0 to 2.11.0 stamps the version (curiosity starts absent). 2.9.0 to 2.10.0 stamps the version; belief provenance, noted contradictions and
  * believed regard stay absent unless a host supplies them;
  * `regard` becomes a reserved impression cue key. A migrated save continues under the current engine's rules: it restores and runs,
  * but it does not reproduce what the old engine would have done next where the rules changed (1.4.0 to 1.5.0
@@ -70,6 +70,16 @@ export const MIGRATIONS = {
         note: 'the surroundings field `ambient.now` is renamed `ambient.percept`; per-person retention is optional and starts absent; behaviour unchanged',
         apply: renameAmbient,
     },
+    '2.11.0': {
+        to: '2.12.0',
+        note: 'the planning slice (Person.planning) is optional and starts absent; retained consequences may carry channel known only when seeded; existing hosts retain exact behavior',
+        apply: stamp,
+    },
+    '2.10.0': {
+        to: '2.11.0',
+        note: 'the curiosity slice (Person.curiosity) is optional and starts absent; existing hosts retain exact behavior',
+        apply: stamp,
+    },
     '2.9.0': {
         to: '2.10.0',
         note: 'belief provenance (Belief.provenance), noted contradictions (memory.contradictions) and the believed-regard impression cue are optional and start absent; existing hosts retain exact behavior',

package/dist/person.d.ts

@@ -136,6 +136,12 @@ export declare function answerNow(p: Person, affordances: readonly Affordance[],
     resolution: SuggestionResolution;
     booked: boolean;
 };
+/**
+ * Read the best retained-claim route using ordinary scoring costs (scarcity absent).
+ * Does not mutate, advance time or consume RNG. `now` values timing against the held state.
+ * Returns undefined when no route improves on direct goal value.
+ */
+export declare function planRoute(p: Person, aff: Affordance, now?: Minute): import("./index.ts").PlanRoute | undefined;
 /** Every resolution of a decision record (all voices), oldest API first. */
 export declare const resolutionsOf: (r: {
     suggestion?: SuggestionResolution;

package/dist/person.js

@@ -25,9 +25,10 @@ import { advanceBeliefs, applyContradiction, attend, believe, confirm, credence,
 import { advanceBody, BODY_DEFAULTS, checkDowned, clearDowned, consume, createBody, downedAllows, enableFatigueStore, enableFullness, expose, injure, nextBodyThreshold, readBody, setDowned, sicken, skipBody, } from './body/index.js';
 import { ageCharacter, enableCharacterChange, noteCharacterDay, noteCharacterSocial, } from './character/index.js';
 import { closeDay, enableYearbook, endDay, noteAnswer, noteCommitments, noteDecision, noteMood, noteOutcome, trimChronicle, } from './chronicle/index.js';
-import { decide as cognitionDecide, desperationOf, scoreAll } from './cognition/index.js';
+import { decide as cognitionDecide, desperationOf, prospectiveRoute, scoreAll } from './cognition/index.js';
 import { createConscience, guiltLoad, heldNorms, normVeto, recordDeed, recordRepair, repent, } from './conscience/index.js';
 import { clamp01, clampSigned, createRng, dayOf, isObj, minuteOfDay } from './core/index.js';
+import { enableCuriosity, noteCuriosity } from './curiosity/index.js';
 import { ambientBodyParams, ambientModifiers, ambientMood, ambientNeeds } from './environment/index.js';
 import { aptitudeOf, createFamily, pregnancyModifiers } from './family/index.js';
 import { advanceHabits, reinforce, withholdCued } from './habits/index.js';
@@ -37,7 +38,7 @@ import { intentionFor, narrateDecision, voiceLine } from './narrate/index.js';
 import { advanceNeeds, createNeeds, levelOf, meanSatisfaction, readNeeds, satisfy, urgencyOf, } from './needs/index.js';
 import { widow } from './partnering/index.js';
 import { enablePromptings, nafsPatterns, notePromptings } from './promptings/index.js';
-import { bodyForecastFor, consumeConsequences, forecastLine, forecastThresholds, pruneConsequences, receiveConsequences, } from './prospection/index.js';
+import { bodyForecastFor, consumeConsequences, enablePlanning, forecastLine, forecastThresholds, pruneConsequences, receiveConsequences, } from './prospection/index.js';
 import { enableReview, reviewIfDue } from './review/index.js';
 import { enableSkillRetention, learnByWatching, practise, seedSkills, } from './skills/index.js';
 import { advanceSocial, applyReputationBelief, careFor, closeness, judge, markDeceased, noteKnownBy, relationshipWith, seedRelationships, socialEvent, threatAppraisal, } from './social/index.js';
@@ -159,6 +160,10 @@ export function createPerson(spec) {
         enableFatigueStore(p);
     if (on?.fullness)
         enableFullness(p);
+    if (on?.curiosity)
+        enableCuriosity(p, on.curiosity === true ? {} : on.curiosity);
+    if (on?.planning)
+        enablePlanning(p, on.planning);
     if (on?.promptings)
         enablePromptings(p, on.promptings);
     if (on?.review)
@@ -849,6 +854,16 @@ export function answerNow(p, affordances, suggestion, opts = {}) {
     }
     return out;
 }
+/**
+ * Read the best retained-claim route using ordinary scoring costs (scarcity absent).
+ * Does not mutate, advance time or consume RNG. `now` values timing against the held state.
+ * Returns undefined when no route improves on direct goal value.
+ */
+export function planRoute(p, aff, now = p.now) {
+    const held = now === p.now ? p : { ...p, now };
+    const { ctx } = decisionInputs(held, [aff], 'plan-readout', {});
+    return prospectiveRoute(held, aff, ctx)?.route;
+}
 /** Every resolution of a decision record (all voices), oldest API first. */
 export const resolutionsOf = (r) => r.suggestions ?? (r.suggestion ? [r.suggestion] : []);
 /**
@@ -1360,6 +1375,8 @@ export function finish(p, outcome, opts = {}) {
         dischargeAdvice(p, aff.action);
     }
     // Memory.
+    if (p.curiosity)
+        noteCuriosity(p, aff, outcome, felt);
     learnOutcome(p, aff, outcome, realized, felt);
     const episode = {
         at: now,

package/dist/prospection/prospection.d.ts

@@ -1,4 +1,4 @@
-import type { Affordance, ConsequenceRevision, Minute, Person, RetainedConsequence } from '../types.ts';
+import type { Affordance, ConsequenceRevision, Minute, Person, PlanningSpec, ReceivedConsequence, RetainedConsequence } from '../types.ts';
 export declare const PROSPECTION_DEFAULTS: {
     maxEntries: number;
     maxRevisions: number;
@@ -7,6 +7,10 @@ export declare const PROSPECTION_DEFAULTS: {
     horizon: number;
     maxMaterialCost: number;
 };
+/** Enable bounded planning. Invalid configuration throws without changing the person. */
+export declare function enablePlanning(p: Person, spec?: PlanningSpec): void;
+/** Seed what the person already knows. Uses claim confidence/chance, without source trust or attention. */
+export declare function seedConsequences(p: Person, sourceId: string, claims: readonly ReceivedConsequence[]): boolean;
 export interface ConsequenceEvidence {
     entry: RetainedConsequence;
     matches: boolean;
@@ -21,3 +25,15 @@ export declare function consequenceEvidence(p: Person, aff: Affordance, now?: Mi
     entries: ConsequenceEvidence[];
     revisions: ConsequenceRevision[];
 };
+/** One successor in a selected route. Times and access are unrounded estimates. */
+export interface PlanStep {
+    successor: ReceivedConsequence['successor'];
+    start: Minute;
+    end: Minute;
+    access: number;
+}
+/** Plain JSON readout of the best whole route; goals are unscaled per-goal values. */
+export interface PlanRoute {
+    steps: PlanStep[];
+    goals: Record<string, number>;
+}

package/dist/prospection/prospection.js

@@ -1,12 +1,17 @@
 /**
- * SCOPE: one received current-action → successor consequence, acquired only through
- * attended external testimony for this person or an untargeted broadcast. Knowledge is person-owned, source-labelled, bounded and saved.
- * Temporal goals value expected completion using time, success and source reliability.
- * One coherent route may contribute; it never executes actions, grants consent or
- * advances a goal. Own completed triggers consume their received opportunity.
- * This is not graph search, inferred procedure learning or a model of future bodies,
- * waiting opportunity cost or another person's agency. Parameters are engineering
- * bounds, not fitted psychological estimates. Revision memory is bounded, not an audit.
+ * SCOPE: retained current-action → successor claims, acquired through attended external
+ * testimony or host-seeded prior knowledge. Knowledge is person-owned, source-labelled,
+ * bounded and saved. Opt-in planning searches chains of retained claims, depth first in
+ * stable source/id order, with total depth 2..5 and 64 feasible node expansions.
+ * Shapes: depth limits and pruning (Huys et al. 2012; Keramati et al. 2016), resource-rational
+ * planning (Callaway et al. 2022), quasi-hyperbolic present bias (Laibson 1997;
+ * O'Donoghue and Rabin 1999); see research/curiosity-and-play.md §Planning.
+ * Parameters are engineering bounds, not fitted psychological estimates.
+ * Without planning, only one successor is considered. One coherent route contributes;
+ * it never executes actions, grants consent or advances goals. Actual completed triggers
+ * consume opportunities. This is not a general planner: it does not search the host's
+ * world, infer procedures, execute plans or model another person's agency, future bodies
+ * or waiting opportunity cost. Revision memory is bounded, not an audit.
  */
 import { temporalGoalValue } from '../agenda/agenda.js';
 import { trustOf } from '../beliefs/index.js';
@@ -21,6 +26,32 @@ export const PROSPECTION_DEFAULTS = {
     horizon: 7 * MINUTES_PER_DAY,
     maxMaterialCost: 1_000_000,
 };
+/** Validate the optional planning configuration. Malformed saved state is dropped. @internal */
+export function sanitizePlanning(input) {
+    if (!isObj(input) ||
+        !Number.isInteger(input.depth) ||
+        !isNum(input.depth) ||
+        input.depth < 2 ||
+        input.depth > 5)
+        return undefined;
+    if (input.presentBias !== undefined &&
+        (!isNum(input.presentBias) || input.presentBias <= 0 || input.presentBias > 1))
+        return undefined;
+    return {
+        depth: input.depth,
+        ...(input.presentBias !== undefined ? { presentBias: input.presentBias } : {}),
+    };
+}
+/** Enable bounded planning. Invalid configuration throws without changing the person. */
+export function enablePlanning(p, spec = {}) {
+    const state = sanitizePlanning({ ...spec, depth: spec.depth ?? 4 });
+    if (!state)
+        throw new RangeError('Planning requires depth 2..5 and presentBias in (0, 1]');
+    p.planning = state;
+}
+const maxEntries = (planning) => (planning ? 64 : PROSPECTION_DEFAULTS.maxEntries);
+const maxBatch = (p) => (p.planning ? 16 : PROSPECTION_DEFAULTS.maxBatch);
+const reliability = (p, e) => e.channel === 'known' ? 1 : trustOf(p, e.sourceId);
 const id = (x) => typeof x === 'string' &&
     x.length > 0 &&
     x.length <= PROSPECTION_DEFAULTS.maxIdentifierLength &&
@@ -90,7 +121,11 @@ function consequence(x, receivedAt) {
     };
 }
 function retained(x, now) {
-    if (!isObj(x) || !id(x.sourceId) || x.channel !== 'told' || !minute(x.receivedAt) || x.receivedAt > now)
+    if (!isObj(x) ||
+        !id(x.sourceId) ||
+        (x.channel !== 'told' && x.channel !== 'known') ||
+        !minute(x.receivedAt) ||
+        x.receivedAt > now)
         return undefined;
     const c = consequence(x, x.receivedAt);
     if (!c ||
@@ -100,7 +135,7 @@ function retained(x, now) {
     return {
         ...c,
         sourceId: x.sourceId,
-        channel: 'told',
+        channel: x.channel,
         receivedAt: x.receivedAt,
         ...(x.triggeredAt !== undefined ? { triggeredAt: x.triggeredAt } : {}),
     };
@@ -132,11 +167,18 @@ export function receiveConsequences(p, pc) {
         pc.actorId === p.id ||
         (pc.targetId !== undefined && pc.targetId !== p.id))
         return false;
-    const adds = pc.consequences ?? [];
-    const removes = pc.withdrawConsequences ?? [];
+    return acceptConsequences(p, pc.actorId, pc.consequences ?? [], pc.withdrawConsequences ?? [], 'told');
+}
+/** Seed what the person already knows. Uses claim confidence/chance, without source trust or attention. */
+export function seedConsequences(p, sourceId, claims) {
+    if (!id(sourceId) || sourceId === p.id)
+        return false;
+    return acceptConsequences(p, sourceId, claims, [], 'known');
+}
+function acceptConsequences(p, sourceId, adds, removes, channel) {
     if (!Array.isArray(adds) ||
         !Array.isArray(removes) ||
-        adds.length + removes.length > PROSPECTION_DEFAULTS.maxBatch ||
+        adds.length + removes.length > maxBatch(p) ||
         adds.length + removes.length === 0)
         return false;
     const additions = adds.map((x) => consequence(x, p.now));
@@ -148,7 +190,6 @@ export function receiveConsequences(p, pc) {
     if (new Set(batch.map((x) => x.id)).size !== batch.length)
         return false;
     const state = cleaned(structuredClone(p.prospection ?? { entries: [], revisions: [] }), p.now);
-    const sourceId = pc.actorId;
     const updates = batch.filter((b) => !state.revisions.some((r) => r.sourceId === sourceId && r.id === b.id && r.revision >= (b.revision ?? 0)));
     const newIds = updates.filter((b) => !state.revisions.some((r) => r.sourceId === sourceId && r.id === b.id));
     // Never evict a still-valid tombstone to admit a batch; dedup holds within the stated horizon.
@@ -159,13 +200,13 @@ export function receiveConsequences(p, pc) {
         state.revisions = state.revisions.filter((r) => !(r.sourceId === sourceId && r.id === b.id));
         const addition = additions.find((a) => a?.id === b.id);
         if (addition)
-            state.entries.push({ ...addition, sourceId, channel: 'told', receivedAt: p.now });
+            state.entries.push({ ...addition, sourceId, channel, receivedAt: p.now });
         state.revisions.push({ sourceId, id: b.id, revision: b.revision, receivedAt: p.now });
     }
-    if (state.entries.length > PROSPECTION_DEFAULTS.maxEntries) {
+    if (state.entries.length > maxEntries(p.planning !== undefined)) {
         const oldest = [...state.entries]
             .sort((a, b) => Number(b.triggeredAt !== undefined) - Number(a.triggeredAt !== undefined) || order(a, b))
-            .slice(0, state.entries.length - PROSPECTION_DEFAULTS.maxEntries);
+            .slice(0, state.entries.length - maxEntries(p.planning !== undefined));
         state.entries = state.entries.filter((e) => !oldest.includes(e));
     }
     store(p, state);
@@ -190,7 +231,7 @@ export function consequenceEvidence(p, aff, now = p.now) {
                 now <= entry.expiresAt &&
                 end <= entry.availableUntil &&
                 Number.isFinite(end);
-            const accessProbability = expectedEffect(p, aff).successRate * entry.chance * entry.confidence * trustOf(p, entry.sourceId);
+            const accessProbability = expectedEffect(p, aff).successRate * entry.chance * entry.confidence * reliability(p, entry);
             return {
                 entry: structuredClone(entry),
                 matches: match,
@@ -223,30 +264,72 @@ export function receivedGoalRoute(p, aff, now, maturityScale, costs) {
     const baseline = direct.reduce((sum, value) => sum + round(value * maturityScale), 0);
     let bestScore = baseline;
     let best;
-    const entries = consequenceEvidence(p, aff, now).entries.sort((a, b) => cmpStr(a.entry.sourceId, b.entry.sourceId) || cmpStr(a.entry.id, b.entry.id));
-    for (const e of entries) {
-        if (!e.feasible)
-            continue;
-        const successor = successorOffer(e.entry);
-        const values = goals.map((g, i) => Math.max(direct[i] ?? 0, e.accessProbability * temporalGoalValue(p, g, successor, now, e.successorEndsAt)));
-        const cost = round(e.accessProbability * Math.min(0, costs(successor)));
-        const total = values.reduce((sum, value) => sum + round(value * maturityScale), 0) + cost;
-        if (!(round(total - bestScore) > 0))
-            continue;
-        bestScore = total;
-        best = {
-            goals: new Map(goals.map((g, i) => [g.id, values[i] ?? 0])),
-            cost: { source: `prospection:cost:${e.entry.sourceId}:${e.entry.id}`, value: cost },
-        };
+    const entries = [...p.prospection.entries].sort((a, b) => cmpStr(a.sourceId, b.sourceId) || cmpStr(a.id, b.id));
+    const beta = p.planning?.presentBias ?? 1;
+    let remaining = p.planning ? 64 : Infinity;
+    function visit(previous, previousEnd, access, path, steps, values, accumulatedCost, done) {
+        if (path.length >= (p.planning?.depth ?? 2) - 1 || remaining <= 0)
+            return;
+        for (const entry of entries) {
+            if (remaining <= 0)
+                return;
+            // Completing an action consumes every open opportunity it triggers, so a
+            // link whose trigger an earlier simulated step already performed is gone.
+            if (path.includes(entry) ||
+                !matches(entry.trigger, previous) ||
+                done.some((a) => matches(entry.trigger, a)) ||
+                entry.triggeredAt !== undefined ||
+                now > entry.expiresAt)
+                continue;
+            const start = Math.max(previousEnd, entry.availableFrom);
+            const end = start + entry.successor.duration;
+            if (!Number.isFinite(end) || end > entry.availableUntil)
+                continue;
+            remaining -= 1;
+            const nextAccess = access *
+                expectedEffect(p, previous).successRate *
+                entry.chance *
+                entry.confidence *
+                reliability(p, entry);
+            const successor = successorOffer(entry);
+            const nextValues = goals.map((g, i) => Math.max(values[i] ?? 0, nextAccess * beta * temporalGoalValue(p, g, successor, now, end)));
+            const nextCost = accumulatedCost + beta * nextAccess * Math.min(0, costs(successor));
+            const cost = round(nextCost);
+            const total = nextValues.reduce((sum, value) => sum + round(value * maturityScale), 0) + cost;
+            const nextPath = [...path, entry];
+            const nextSteps = [
+                ...steps,
+                { successor: structuredClone(entry.successor), start, end, access: nextAccess },
+            ];
+            if (round(total - bestScore) > 0) {
+                bestScore = total;
+                // Keep the original root's source string; the ref explains longer routes.
+                const root = nextPath[0];
+                best = {
+                    goals: new Map(goals.map((g, i) => [g.id, nextValues[i] ?? 0])),
+                    cost: {
+                        source: `prospection:cost:${root.sourceId}:${root.id}`,
+                        value: cost,
+                        ...(nextPath.length > 1 ? { ref: nextPath.map((e) => e.id).join('>') } : {}),
+                    },
+                    route: {
+                        steps: nextSteps,
+                        goals: Object.fromEntries(goals.map((g, i) => [g.id, nextValues[i] ?? 0])),
+                    },
+                };
+            }
+            visit(successor, end, nextAccess, nextPath, nextSteps, nextValues, nextCost, [...done, previous]);
+        }
     }
+    visit(aff, now + Math.max(0, aff.duration), 1, [], [], direct, 0, []);
     return best;
 }
 /** Conservative optional-slice restore; ambiguous identities drop the slice. @internal */
-export function sanitizeProspection(input, now, personId) {
+export function sanitizeProspection(input, now, personId, planning = false) {
     if (!isObj(input) ||
         !Array.isArray(input.entries) ||
         !Array.isArray(input.revisions) ||
-        input.entries.length > PROSPECTION_DEFAULTS.maxEntries ||
+        input.entries.length > maxEntries(planning) ||
         input.revisions.length > PROSPECTION_DEFAULTS.maxRevisions)
         return undefined;
     const entries = input.entries.map((x) => retained(x, now)).filter((e) => e?.sourceId !== personId);

package/dist/restore.d.ts

@@ -1,3 +1,11 @@
+/**
+ * SCOPE: saving and loading a person. `snapshot` copies a person as plain JSON; `restore` validates a saved person,
+ * upgrades a save from an earlier supported engine (`migrate`), fills defaults for missing or mistyped core fields,
+ * hands every optional slice to its owning module's sanitizer (the chronicle, its day accumulator and the lexicon
+ * need only a type check, done here), and holds every list to the bound the live code keeps.
+ * A save the engine wrote restores to exactly what was saved. It does not repair a save's meaning (a plausible but
+ * wrong value stays), merge two saves, or read any format but the person JSON.
+ */
 import type { Person } from './types.ts';
 /** A deep copy of the person as plain JSON (what a host saves). */
 export declare function snapshot(p: Person): Person;

package/dist/restore.js

@@ -13,6 +13,7 @@ import { sanitizeBody, sanitizeInjuries } from './body/index.js';
 import { sanitizeCharacter } from './character/index.js';
 import { CHRONICLE_DEFAULTS, sanitizeYears } from './chronicle/index.js';
 import { isNum } from './core/index.js';
+import { sanitizeCuriosity } from './curiosity/index.js';
 import { sanitizeAmbient } from './environment/index.js';
 import { sanitizeFamily } from './family/index.js';
 import { HABIT_DEFAULTS } from './habits/index.js';
@@ -22,7 +23,7 @@ import { migrate } from './migrate.js';
 import { sanitizeBonds } from './partnering/index.js';
 import { cleanRetention, createPerson, traceLimit } from './person.js';
 import { sanitizePromptings } from './promptings/index.js';
-import { sanitizeProspection } from './prospection/index.js';
+import { sanitizePlanning, sanitizeProspection } from './prospection/index.js';
 import { sanitizeReview } from './review/index.js';
 import { sanitizeSkillRetention } from './skills/index.js';
 import { sanitizeGroups, sanitizeImpressions } from './social/index.js';
@@ -84,7 +85,9 @@ const OPTIONAL_KEYS = new Set([
     'retention',
     'methods',
     'prospection',
+    'planning',
     'promptings',
+    'curiosity',
     'review',
 ]);
 /** Kind of a JSON value for the per-field type check in `restore`. */
@@ -199,7 +202,9 @@ export function restore(input) {
     keepValid(out, 'ambient', sanitizeAmbient);
     keepValid(out, 'retention', cleanRetention);
     keepValid(out, 'methods', sanitizeMethods);
-    keepValid(out, 'prospection', (x) => sanitizeProspection(x, out.now, out.id));
+    keepValid(out, 'planning', sanitizePlanning);
+    keepValid(out, 'prospection', (x) => sanitizeProspection(x, out.now, out.id, out.planning !== undefined));
+    keepValid(out, 'curiosity', (x) => sanitizeCuriosity(x, out.now));
     keepValid(out, 'promptings', (x) => sanitizePromptings(x, out.now));
     keepValid(out, 'review', (x) => sanitizeReview(x, out.now));
     boundLists(out);

package/dist/types.d.ts

@@ -885,7 +885,7 @@ export declare const PERSON_SCHEMA = "human/person@1";
  * and an activity that would cover a closing stretch is reviewed when the stretch begins (`isUnderWay`,
  * `dutyReviewAt`). Person shape unchanged.
  */
-export declare const ENGINE_VERSION = "2.10.0";
+export declare const ENGINE_VERSION = "2.12.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1019,7 +1019,7 @@ export interface ConsequenceRevision {
 }
 export interface RetainedConsequence extends ReceivedConsequence {
     sourceId: EntityId;
-    channel: 'told';
+    channel: 'told' | 'known';
     receivedAt: Minute;
     /** Own completed trigger; does not establish access or goal progress. */
     triggeredAt?: Minute;
@@ -1029,6 +1029,17 @@ export interface ProspectionState {
     entries: RetainedConsequence[];
     revisions: ConsequenceRevision[];
 }
+/** Bounded retained-claim search, owned by `prospection/`. */
+export interface PlanningSpec {
+    /** Total steps including the current offer: integer 2..5, default 4. */
+    depth?: number;
+    /** Quasi-hyperbolic beta in (0, 1]; absent means no present bias. */
+    presentBias?: Unit;
+}
+export interface PlanningState {
+    depth: number;
+    presentBias?: Unit;
+}
 export interface Person {
     schema: typeof PERSON_SCHEMA;
     /** Engine version that last wrote this state. */
@@ -1048,10 +1059,14 @@ export interface Person {
     skills: Record<string, Skill>;
     /** Acquired conditional method evidence and current received cues; absent until used. */
     methods?: MethodsState;
-    /** Received future consequences, absent until attended testimony supplies them. */
+    /** Received future consequences, absent until attended testimony or `seedConsequences` supplies them. */
     prospection?: ProspectionState;
+    /** Opt-in bounded planning over retained consequences. Owned by `prospection/`. */
+    planning?: PlanningState;
     /** Noticed promptings and practised turnings-away (2.4.0, opt-in via `enablePromptings`). Owned by `promptings/`. */
     promptings?: PromptingsState;
+    /** Intrinsic exploration and varied repetition. Owned by `curiosity/`; absent unless enabled. */
+    curiosity?: CuriosityState;
     /** Evening self-review and its resolves (2.7.0, opt-in via `enableReview`). Owned by `review/`. */
     review?: ReviewState;
     /** Practice consolidation (1.8.0, opt-in via `enableSkillRetention`). Owned by `skills/`. */
@@ -1496,6 +1511,10 @@ export interface PersonSpec {
         fullness?: boolean;
         /** Promptings and turning away (2.4.0): the same as `enablePromptings(p, spec)` after creation. */
         promptings?: PromptingsSpec;
+        /** Enable intrinsic exploration and play, using engineering defaults or bounded overrides. */
+        curiosity?: boolean | CuriositySpec;
+        /** Bounded planning: the same as `enablePlanning(p, spec)` after creation. */
+        planning?: PlanningSpec;
         /** Evening self-review (2.7.0): the same as `enableReview(p, spec)` after creation. */
         review?: ReviewSpec;
     };
@@ -1890,3 +1909,39 @@ export interface DayRecord {
      */
     state?: ChronicleState;
 }
+/** Engineering overrides for intrinsic motivation; scales are capped at their defaults. */
+export interface CuriositySpec {
+    unknownScale?: number;
+    progressScale?: number;
+    varyScale?: number;
+    recentMinutes?: number;
+    rewardMax?: number;
+}
+/** Prediction-error history for the same key used by memory expectations. */
+export interface CuriosityError {
+    key: string;
+    fast: Unit;
+    slow: Unit;
+    n: number;
+    lastAt: Minute;
+}
+/** A completed or failed act, retained only for bounded repetition with variation. */
+export interface CuriosityAct {
+    action: string;
+    targetId?: EntityId;
+    placeId?: EntityId;
+    at: Minute;
+}
+/** Optional JSON state owned by curiosity/. */
+export interface CuriosityState {
+    spec?: CuriositySpec;
+    errors: CuriosityError[];
+    recent: CuriosityAct[];
+}
+/** Raw bounded signals and their common drive; no RNG or mutation. */
+export interface CuriosityReading {
+    unknown: Unit;
+    progress: Unit;
+    vary: Unit;
+    drive: number;
+}

package/dist/types.js

@@ -120,4 +120,4 @@ export const PERSON_SCHEMA = 'human/person@1';
  * and an activity that would cover a closing stretch is reviewed when the stretch begins (`isUnderWay`,
  * `dutyReviewAt`). Person shape unchanged.
  */
-export const ENGINE_VERSION = '2.10.0';
+export const ENGINE_VERSION = '2.12.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adam0white/human-framework",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Deterministic, explainable simulated people: body, needs, affect, memory, beliefs, skills, habits, relationships, values and a will that can refuse a suggestion",
   "keywords": [
     "simulation",