@adam0white/human-framework 2.11.0 → 2.13.0

package/dist/agenda/agenda.js

@@ -154,8 +154,11 @@ function sanitizeGoalTemporal(g) {
     else if (g.temporal)
         g.temporal = { halfLifeMinutes: g.temporal.halfLifeMinutes };
 }
-/** Restore-time check of `agenda.lapse` (1.7.0), in place: a malformed one is dropped (absent means none). @internal */
+/** Restore-time check of optional lapse and firm flags; malformed values are dropped. @internal */
 export function sanitizeAgenda(a) {
+    for (const c of a.commitments)
+        if (isObj(c) && (c.firm !== true || c.kind !== 'abstain'))
+            delete c.firm;
     for (const g of a.goals)
         if (isObj(g))
             sanitizeGoalTemporal(g);

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

@@ -22,7 +22,10 @@
  * desperation threshold, and only for acts meeting a bodily need; this is not the fast's own exemption for
  * illness and travel (2:184-185, applied in the agenda) and not the 2:173 necessity exception for forbidden
  * food. Below the threshold the abstention acts only as a negative term (agenda), so a weakly convinced person
- * can be tempted. It does not model the person's later judgment of a broken fast beyond the recorded breach.
+ * can be tempted. An opt-in `firm: true` self abstention without a linked obligatory norm instead vetoes
+ * as `rule:<label>` (id fallback). It uses the same open-window, exemption and bodily survival checks,
+ * including for self choice and insistence. It models a held rule, not a new religious ruling.
+ * It does not model the person's later judgment of a broken fast beyond the recorded breach.
  */
 import { clamp01 } from '../core/index.js';
 import { DEFAULT_NORMS, NORM_SCOPE } from './catalog.js';
@@ -251,11 +254,15 @@ export function abstentionVeto(p, aff, now, capacityLifted = false) {
         return undefined;
     const end = now + Math.max(0, aff.duration);
     for (const c of p.agenda?.commitments ?? []) {
-        if (c.kind !== 'abstain' || c.status !== 'pending' || c.exempt !== undefined || c.normId === undefined)
+        if (c.kind !== 'abstain' || c.status !== 'pending' || c.exempt !== undefined)
             continue;
         if (!(c.violatedBy?.includes(aff.action) ?? false) || now >= c.until || end <= c.from)
             continue;
-        const held = heldNorm(p, c.normId);
+        const held = c.normId === undefined ? undefined : heldNorm(p, c.normId);
+        if (c.firm === true &&
+            (c.toId === undefined || c.toId === 'self' || c.toId === p.id) &&
+            held?.standing !== 'obligatory')
+            return { kind: 'willNot', reason: `rule:${c.label ?? c.id}` };
         if (held?.standing !== 'obligatory' || held.conviction < CONSCIENCE_DEFAULTS.abstainVetoConviction)
             continue;
         return { kind: 'willNot', reason: `duty:${c.normId}` };

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.13.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.13.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.12.0 to 2.13.0 stamps the version (suggestion reasons and firm rules start absent). 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.12.0': {
+        to: '2.13.0',
+        note: 'suggestion reasons (Person.will.suggestionReasons) and firm self-rules (Commitment.firm) are optional and start absent; existing hosts retain exact behavior',
+        apply: stamp,
+    },
+    '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,12 +38,12 @@ 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';
 import { ENGINE_VERSION, MAX_MINUTE, PERSON_SCHEMA, PHYSIOLOGICAL_NEEDS, PSYCHOLOGICAL_NEEDS, TRAIT_KEYS, VALUE_KEYS, } from './types.js';
-import { advanceWill, answerSuggestion, chargeCommand, commandTargets, createWill, creditedVoices, dischargeAdvice, dutyReviewAt, endCommand, learnFromVoice, noteCommandOutcome, predictResponse, rememberAdvice, resolveCommand, takeCommand, voicesIn, WILL_DEFAULTS, wakeReviewAt, } from './will/index.js';
+import { advanceWill, answerSuggestion, chargeCommand, commandTargets, createWill, creditedVoices, dischargeAdvice, dutyReviewAt, enableSuggestionReasons, endCommand, learnFromVoice, noteCommandOutcome, predictResponse, rememberAdvice, resolveCommand, takeCommand, voicesIn, WILL_DEFAULTS, wakeReviewAt, } from './will/index.js';
 export const PERSON_DEFAULTS = {
     /** Body load while idle and awake. */
     idleLoad: { effort: 0.05, focus: 0.05, mode: 'awake' },
@@ -148,6 +148,8 @@ export function createPerson(spec) {
     if (family)
         p.family = family;
     const on = spec.enable;
+    if (on?.suggestionReasons)
+        enableSuggestionReasons(p);
     if (on?.gists)
         enableGists(p);
     if (on?.yearbook)
@@ -162,6 +164,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 +856,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

@@ -563,6 +563,8 @@ export interface Commitment {
     label?: string;
     /** For kind 'abstain': action ids whose completion inside the window breaks it. */
     violatedBy?: string[];
+    /** Firm self abstention: a will-not, lifted for bodily survival like a norm abstention. */
+    firm?: true;
     /** For kind 'abstain': catalogued conditions under which the person may not hold it that day. */
     exemptWhen?: ('illness' | 'travel')[];
     /**
@@ -700,6 +702,8 @@ export interface VoiceTrustEvent {
  * impulse emerges from competing terms, real fatigue costs, habits and precommitments.
  */
 export interface WillState {
+    /** Opt-in score explanations on suggestion resolutions; absent preserves legacy JSON. */
+    suggestionReasons?: true;
     voices: VoiceRelation[];
     /**
      * Precommitments the person made for themselves (e.g. "no work after Isha", "walk instead of eat when bored"):
@@ -885,7 +889,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.13.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1019,7 +1023,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 +1033,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 +1063,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. */
@@ -1361,6 +1378,12 @@ export type SuggestionVerdict = 'assented' | 'complied' | 'deferred' | 'modified
 /** Refusal class for UI: grey = cannot, amber = notNow, red = willNot. */
 export type RefusalKind = 'cannot' | 'notNow' | 'willNot';
 export interface SuggestionResolution {
+    /** Read-only score explanation, only with `enableSuggestionReasons`; margin includes activity inertia. */
+    decidedBy?: {
+        kind: 'inertia' | 'term';
+        source?: string;
+        margin: number;
+    };
     voiceId: EntityId;
     verdict: SuggestionVerdict;
     kind?: RefusalKind;
@@ -1488,6 +1511,8 @@ export interface PersonSpec {
      * `enableCharacterChange` and `enableSkillRetention` right after `createPerson`. Each is off when absent.
      */
     enable?: {
+        /** Read-only suggestion score explanations, as with `enableSuggestionReasons(p)`. */
+        suggestionReasons?: boolean;
         gists?: boolean;
         yearbook?: boolean;
         character?: boolean;
@@ -1500,6 +1525,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.13.0';

package/dist/will/will.d.ts

@@ -266,6 +266,13 @@ export declare function dominantTerm(c: Considered | undefined): string;
  * sorted by voice id and bounded by `maxVoices`, so the outcome never depends on the host's argument order.
  */
 export declare function voicesIn(single: Suggestion | undefined, list: readonly Suggestion[] | undefined): Suggestion[];
+/**
+ * SCOPE (suggestion reasons): opt-in read-only explanations of score-based deferrals and modifications.
+ * The gap includes running-activity inertia; source differences aggregate like-labelled terms and tie by
+ * source string. This does not change selection, voice wording, counters or RNG, explain vetoes, or claim
+ * a score caused a lower-scoring stochastic choice. Legacy resolutions have no additional keys.
+ */
+export declare function enableSuggestionReasons(p: Person): void;
 /** Whether a command names offer `aff` (by affordance id, or by action class when it names no affordance). */
 export declare const commandTargets: (cmd: Command, aff: Affordance) => boolean;
 /**

package/dist/will/will.js

@@ -36,7 +36,7 @@ import { breakAllows, inBreak } from '../affect/index.js';
 import { commitmentPressure, isUnderWay, pressureReachedAt } from '../agenda/index.js';
 import { downedAllows, readCapacities } from '../body/index.js';
 import { CONSCIENCE_DEFAULTS, normVeto } from '../conscience/index.js';
-import { clamp01, cmpStr, decay, dexp, dpow, hasNumbers, isObj, random } from '../core/index.js';
+import { clamp01, cmpStr, decay, dexp, dpow, hasNumbers, isObj, random, round } from '../core/index.js';
 import { skillLevel } from '../skills/index.js';
 import { MINUTES_PER_DAY, MINUTES_PER_HOUR } from '../types.js';
 export const WILL_DEFAULTS = {
@@ -160,6 +160,8 @@ export const WILL_DEFAULTS = {
  * or `lastCommand` (1.6.0, 1.7.0) are dropped (absent means none). A save the engine wrote is unchanged. @internal
  */
 export function sanitizeWill(w) {
+    if (w.suggestionReasons !== true)
+        delete w.suggestionReasons;
     if (w.advice !== undefined && !Array.isArray(w.advice))
         delete w.advice;
     const cmd = w.command;
@@ -721,6 +723,43 @@ function arbitrateCommand(p, ctx, cmd, suggestions, prepared, selection, ev) {
     }
     return false;
 }
+/**
+ * SCOPE (suggestion reasons): opt-in read-only explanations of score-based deferrals and modifications.
+ * The gap includes running-activity inertia; source differences aggregate like-labelled terms and tie by
+ * source string. This does not change selection, voice wording, counters or RNG, explain vetoes, or claim
+ * a score caused a lower-scoring stochastic choice. Legacy resolutions have no additional keys.
+ */
+export function enableSuggestionReasons(p) {
+    p.will.suggestionReasons = true;
+}
+function scoreReason(selection, live, targetIds) {
+    const { winner, ranked, score } = selection;
+    if (!winner)
+        return undefined;
+    // A stochastic draw below the best live score was not decided by the scores.
+    if (ranked.some((c) => !c.vetoed && score(c) > score(winner)))
+        return undefined;
+    // Compare against the closest suggested option by the same adjusted score the winner was chosen on.
+    const suggested = [...live].sort((a, b) => score(b) - score(a) || cmpStr(a.affordanceId, b.affordanceId))[0];
+    if (!suggested)
+        return undefined;
+    const gap = score(winner) - score(suggested);
+    if (!Number.isFinite(gap) || gap < 0)
+        return undefined;
+    const margin = round(gap);
+    const withoutInertia = [...ranked].sort(byUtilityThenId)[0];
+    if (score(winner) > winner.utility && withoutInertia && targetIds.has(withoutInertia.affordanceId))
+        return { kind: 'inertia', margin };
+    const differences = new Map();
+    for (const t of winner.terms)
+        differences.set(t.source, (differences.get(t.source) ?? 0) + t.value);
+    for (const t of suggested.terms)
+        differences.set(t.source, (differences.get(t.source) ?? 0) - t.value);
+    const term = [...differences]
+        .filter(([, value]) => value > 0)
+        .sort((a, b) => b[1] - a[1] || cmpStr(a[0], b[0]))[0];
+    return { kind: 'term', ...(term ? { source: term[0] } : {}), margin };
+}
 /** Judge each voice against the same selected option before resolving competing insistence. */
 function judgeVoices(p, ctx, suggestions, prepared, selection) {
     const W = WILL_DEFAULTS;
@@ -829,17 +868,21 @@ function judgeVoices(p, ctx, suggestions, prepared, selection) {
         }
         side.pressure = W.pressurePush * clamp01(s.strength);
         side.refused = 1;
+        const decidedBy = p.will.suggestionReasons ? scoreReason(selection, liveSuggested, targetIds) : undefined;
+        const explanation = decidedBy ? { decidedBy } : {};
         const near = winnerAff !== undefined &&
             suggestedAff !== undefined &&
             (winnerAff.action === suggestedAff.action ||
                 (mainAim(suggestedAff) !== undefined && mainAim(suggestedAff) === mainAim(winnerAff)));
         if (near && winnerAff)
             return out(resolution('modified', reason, {
+                ...explanation,
                 kind: 'notNow',
                 insteadAffordanceId: winnerAff.id,
                 counterOffer: { affordanceId: winnerAff.id, label: winnerAff.label },
             }));
         return out(resolution('deferred', reason, {
+            ...explanation,
             kind: 'notNow',
             insteadAffordanceId: winnerAff?.id,
             counterOffer: winnerAff
@@ -865,6 +908,9 @@ function arbitrateInsistence(p, judged, considered, affById, ev) {
             forcer = j;
     }
     if (forcer?.comply) {
+        // The final option is imposed by insistence, not selected by scores.
+        for (const j of judged)
+            delete j.res.decidedBy;
         const forced = forcer.comply.target.affordanceId;
         const forcedAff = affById.get(forced);
         ev.chosenId = forced;

package/package.json

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