@adam0white/human-framework 2.11.0 → 2.12.0

package/dist/cognition/cognition.js

@@ -248,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. */
@@ -328,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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.11.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';
@@ -30,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.11.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';
@@ -27,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.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
+ * 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,11 @@ 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',

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,7 +25,7 @@ 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';
@@ -38,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';
@@ -162,6 +162,8 @@ export function createPerson(spec) {
         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)
@@ -852,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] : []);
 /**

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.js

@@ -23,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';
@@ -85,6 +85,7 @@ const OPTIONAL_KEYS = new Set([
     'retention',
     'methods',
     'prospection',
+    'planning',
     'promptings',
     'curiosity',
     'review',
@@ -201,7 +202,8 @@ 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));

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.11.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,8 +1059,10 @@ 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. */
@@ -1500,6 +1513,8 @@ export interface PersonSpec {
         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;
     };

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.11.0';
+export const ENGINE_VERSION = '2.12.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adam0white/human-framework",
-  "version": "2.11.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",