@adam0white/human-framework 2.4.0 → 2.6.0

package/dist/body/body.d.ts

@@ -30,6 +30,15 @@ export declare const BODY_DEFAULTS: {
     exertionRiseHalfLife: number;
     exertionRecoverHalfLife: number;
     exertionRecoverHalfLifeAsleep: number;
+    /** Fatigue store (2.6.0, opt-in): depletion per hour at full effort (× (1 - 0.5 fitness) × (1 - depletion)). */
+    depletionPerHour: number;
+    /** Effort below which the store does not fill and recovers while awake. */
+    depletionFloor: number;
+    /** Half-life of depletion at rest awake and asleep (minutes, divided by the life-course recovery factor). */
+    depletionRestHalfLife: number;
+    depletionSleepHalfLife: number;
+    /** How much a full store adds to felt fatigue: fatigue = 1 - (1 - exertion)(1 - 0.5 s)(1 - weight × depletion). */
+    depletionFatigueWeight: number;
     /** Effort above which fitness trains. */
     trainingEffort: number;
     /** Detraining half-life (min) toward fitnessFloor. */
@@ -116,6 +125,8 @@ export interface BodyPerceptionContext {
     fastingDays: number;
 }
 export type BodyParams = typeof BODY_DEFAULTS;
+/** Turn on the fatigue store (2.6.0): accumulated exertion that recovers with rest and sleep. Idempotent. */
+export declare function enableFatigueStore(p: Person): void;
 export declare function createBody(init: PersonSpec['body'] | undefined, now: Minute): BodyState;
 /**
  * Advance `p.body` over `dt` minutes under `load`. Call with `p.now` at the start of the interval: a mode
@@ -189,3 +200,20 @@ export interface BodyThresholds {
  * then refines minute by minute inside the crossing step. Does not mutate `p`.
  */
 export declare function nextBodyThreshold(p: Person, load: BodyLoad, mods: LifeModifiers, thresholds?: BodyThresholds, horizon?: number, params?: BodyParams, perception?: BodyPerceptionContext): number;
+/** One forecast span: where it ends and the worst perceived readout during it. */
+export interface BodyForecastSpan {
+    label: string;
+    endsAt: Minute;
+    /** Worst perceived fatigue, sleepiness, hunger or thirst during the span (0..1), and which. */
+    worst: Unit;
+    worstOf: 'fatigue' | 'sleepiness' | 'hunger' | 'thirst';
+}
+/**
+ * The person's own forecast of their body through consecutive spans of known exertion, read as they perceive it
+ * (2.5.0). Simulates a cloned body in steps of at most `step` minutes; pure (does not mutate `p`).
+ */
+export declare function forecastBody(p: Person, spans: readonly {
+    label: string;
+    duration: number;
+    load: BodyLoad;
+}[], mods: LifeModifiers, params?: BodyParams, step?: number, perception?: BodyPerceptionContext): BodyForecastSpan[];

package/dist/body/body.js

@@ -76,6 +76,15 @@ export const BODY_DEFAULTS = {
     exertionRiseHalfLife: 40,
     exertionRecoverHalfLife: 45,
     exertionRecoverHalfLifeAsleep: 25,
+    /** Fatigue store (2.6.0, opt-in): depletion per hour at full effort (× (1 - 0.5 fitness) × (1 - depletion)). */
+    depletionPerHour: 0.3,
+    /** Effort below which the store does not fill and recovers while awake. */
+    depletionFloor: 0.3,
+    /** Half-life of depletion at rest awake and asleep (minutes, divided by the life-course recovery factor). */
+    depletionRestHalfLife: 8 * 60,
+    depletionSleepHalfLife: 3 * 60,
+    /** How much a full store adds to felt fatigue: fatigue = 1 - (1 - exertion)(1 - 0.5 s)(1 - weight × depletion). */
+    depletionFatigueWeight: 1,
     /** Effort above which fitness trains. */
     trainingEffort: 0.4,
     /** Detraining half-life (min) toward fitnessFloor. */
@@ -229,6 +238,13 @@ export function sanitizeBody(b, now) {
         delete b.lastSleep;
     if (b.lastDowned !== undefined && !span(b.lastDowned))
         delete b.lastDowned;
+    if (b.depletion !== undefined)
+        b.depletion = typeof b.depletion === 'number' && Number.isFinite(b.depletion) ? clamp01(b.depletion) : 0;
+}
+/** Turn on the fatigue store (2.6.0): accumulated exertion that recovers with rest and sleep. Idempotent. */
+export function enableFatigueStore(p) {
+    if (p.body.depletion === undefined)
+        p.body.depletion = 0;
 }
 /**
  * Repair the optional chronic fields of saved illnesses in place: a non-finite or out-of-range `baseline` is
@@ -367,6 +383,18 @@ function subStep(b, h, load, mods, P) {
         ? P.exertionRiseHalfLife
         : (asleep ? P.exertionRecoverHalfLifeAsleep : P.exertionRecoverHalfLife) / recovery;
     b.exertion = clamp01(decay(b.exertion, h, hl, target));
+    // Fatigue store (2.6.0, opt-in): fills with sustained effort above the floor, empties with rest and sleep.
+    if (b.depletion !== undefined) {
+        const d = clamp01(Number.isFinite(b.depletion) ? b.depletion : 0);
+        if (effortUsed > P.depletionFloor) {
+            const rate = (P.depletionPerHour * (effortUsed - P.depletionFloor)) / (1 - P.depletionFloor);
+            b.depletion = clamp01(d + (rate * (1 - 0.5 * b.fitness) * (1 - d) * h) / 60);
+        }
+        else {
+            const half = (asleep ? P.depletionSleepHalfLife : P.depletionRestHalfLife) / recovery;
+            b.depletion = clamp01(decay(d, h, half, 0));
+        }
+    }
     // Fitness: dF/dt = -kd (F - floor) + kt (max - F), exact for constant load.
     const maxFit = clamp01(mods.maxFitness);
     const kd = LN2 / P.detrainHalfLife;
@@ -501,7 +529,8 @@ export function readBody(p, params = BODY_DEFAULTS, ctx) {
     const sleepiness = clamp01(params.sleepinessPressureWeight * b.sleepPressure +
         params.sleepinessCircadianWeight * (1 - alertness) +
         debtTerm);
-    const fatigueOf = (s) => clamp01(1 - (1 - b.exertion) * (1 - 0.5 * s));
+    const store = b.depletion === undefined ? 1 : 1 - params.depletionFatigueWeight * clamp01(b.depletion);
+    const fatigueOf = (s) => clamp01(1 - (1 - b.exertion) * (1 - 0.5 * s) * store);
     const fatigue = fatigueOf(sleepiness);
     const hunger = clamp01(1 - b.satiety);
     const thirst = clamp01(1 - b.hydration);
@@ -763,3 +792,40 @@ export function nextBodyThreshold(p, load, mods, thresholds = { hunger: 0.7, thi
     }
     return Number.POSITIVE_INFINITY;
 }
+/**
+ * The person's own forecast of their body through consecutive spans of known exertion, read as they perceive it
+ * (2.5.0). Simulates a cloned body in steps of at most `step` minutes; pure (does not mutate `p`).
+ */
+export function forecastBody(p, spans, mods, params = BODY_DEFAULTS, step = 30, perception) {
+    const out = [];
+    const sim = { ...p, body: cloneBody(p.body) };
+    for (const s of spans) {
+        const span = { label: s.label, endsAt: sim.now, worst: 0, worstOf: 'fatigue' };
+        // Hard internal cap (a week) so a hostile span cannot stall a decision.
+        let left = Math.min(7 * MINUTES_PER_DAY, Math.max(0, Number.isFinite(s.duration) ? s.duration : 0));
+        advanceBody(sim, 0, s.load, mods, params);
+        const r0 = readBody(sim, params, perception).perceived;
+        for (const k of ['fatigue', 'sleepiness', 'hunger', 'thirst'])
+            if (r0[k] > span.worst) {
+                span.worst = r0[k];
+                span.worstOf = k;
+            }
+        while (left > 0 && sim.body.alive) {
+            const dt = Math.min(step, left);
+            advanceBody(sim, dt, s.load, mods, params);
+            sim.now += dt;
+            left -= dt;
+            const r = readBody(sim, params, perception).perceived;
+            for (const k of ['fatigue', 'sleepiness', 'hunger', 'thirst'])
+                if (r[k] > span.worst) {
+                    span.worst = r[k];
+                    span.worstOf = k;
+                }
+        }
+        if (!sim.body.alive)
+            span.worst = 1;
+        span.endsAt = sim.now;
+        out.push(span);
+    }
+    return out;
+}

package/dist/cognition/cognition.d.ts

@@ -1,3 +1,4 @@
+import type { BodyPerceptionContext } from '../body/index.ts';
 import { type HabitContext } from '../habits/index.ts';
 import { type PromptingSeen } from '../promptings/index.ts';
 import type { Affordance, BodyReadout, Command, Considered, DecisionRecord, LifeModifiers, Minute, NeedReading, Person, Suggestion, Term, Unit } from '../types.ts';
@@ -100,6 +101,8 @@ export interface ConsiderContext {
      * leaves the material and safety terms exactly as without it.
      */
     scarcity?: Unit;
+    /** The body's perception context now (an open fast), for the bodily forecast (2.6.0). */
+    perception?: BodyPerceptionContext;
 }
 /**
  * Standing advice terms for one option: per source, the strongest matching entry's weight × trust in the source

package/dist/cognition/cognition.js

@@ -35,7 +35,7 @@ import { methodEvidence } from '../methods/index.js';
 import { urgencyOf } from '../needs/index.js';
 import { partneringTerms } from '../partnering/index.js';
 import { promptIn, promptingTerms } from '../promptings/index.js';
-import { receivedGoalRoute } from '../prospection/index.js';
+import { bodyForecastTerm, receivedGoalRoute } from '../prospection/index.js';
 import { companionSteadiness, socialTerms } from '../social/index.js';
 import { PHYSIOLOGICAL_NEEDS, VALUE_KEYS } from '../types.js';
 import { adviceWeight, resolveChoice, safeUtility, standingAdvice, suggestionTargets, voicesIn, } from '../will/index.js';
@@ -349,6 +349,12 @@ export function consider(p, aff, ctx) {
     const effort = effortValue(p, aff, ctx);
     if (effort < 0)
         push('effort', effort);
+    // Bodily forecast (2.5.0): only offers that declare known follow-on exertion.
+    if (aff.followedBy?.length) {
+        const t = bodyForecastTerm(p, aff, ctx.mods, ctx.perception);
+        if (t)
+            push(t.source, t.value);
+    }
     // Risk: chance × severity × (fear + emotionality).
     if (aff.risk && aff.risk.chance > 0 && aff.risk.severity > 0) {
         const fear = emotionLevel(p, 'fear');

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework v1 public surface. */
-export declare const FRAMEWORK_VERSION = "2.4.0";
+export declare const FRAMEWORK_VERSION = "2.6.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,7 +30,7 @@ export * from './partnering/index.ts';
 export * from './person.ts';
 export * from './promptings/index.ts';
 export type { ConsequenceEvidence } from './prospection/index.ts';
-export { consequenceEvidence, PROSPECTION_DEFAULTS } from './prospection/index.ts';
+export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, FORECAST_DEFAULTS, forecastLine, PROSPECTION_DEFAULTS, } from './prospection/index.ts';
 export * from './restore.ts';
 export * from './scenarios/index.ts';
 export * from './sim/index.ts';

package/dist/index.js

@@ -1,5 +1,5 @@
 /** Human Framework v1 public surface. */
-export const FRAMEWORK_VERSION = '2.4.0';
+export const FRAMEWORK_VERSION = '2.6.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';
@@ -26,7 +26,7 @@ export * from './needs/index.js';
 export * from './partnering/index.js';
 export * from './person.js';
 export * from './promptings/index.js';
-export { consequenceEvidence, PROSPECTION_DEFAULTS } from './prospection/index.js';
+export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, FORECAST_DEFAULTS, forecastLine, PROSPECTION_DEFAULTS, } from './prospection/index.js';
 export * from './restore.js';
 export * from './scenarios/index.js';
 export * from './sim/index.js';

package/dist/migrate.js

@@ -8,7 +8,7 @@
  * field of the optional surroundings slice (`ambient.now` → `ambient.percept`) and changes no behaviour (the optional `social.impressions` and `social.reserve`, like `retention`, are optional and start
  * absent in a migrated save); `restore` then fills and sanitizes
  * the slices as for any save. 2.0.0 to 2.1.0 adds optional conditional method state, absent
- * until explicitly used, so existing hosts retain their previous behavior; that step stamps the version. 2.1.0 to 2.2.0 preserves optional method records and stamps the version; successful alternatives now retain independent support. 2.2.0 to 2.3.0 stamps the version; received consequences and temporal goals remain absent unless explicitly supplied. 2.3.0 to 2.4.0 stamps the version; promptings remain absent unless enabled. A migrated save continues under the current engine's rules: it restores and runs,
+ * until explicitly used, so existing hosts retain their previous behavior; that step stamps the version. 2.1.0 to 2.2.0 preserves optional method records and stamps the version; successful alternatives now retain independent support. 2.2.0 to 2.3.0 stamps the version; received consequences and temporal goals remain absent unless explicitly supplied. 2.3.0 to 2.4.0 stamps the version; promptings remain absent unless enabled. 2.4.0 to 2.5.0 stamps the version; the bodily forecast reads only offers that declare `followedBy`. 2.5.0 to 2.6.0 stamps the version; the fatigue store stays absent unless enabled. 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
  * changed how standing advice is heard; 1.8.0 to 1.9.0 changed the omission rule). Saves older than 1.4.0 and unknown versions are refused with an error.
  *
@@ -58,6 +58,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.5.0': {
+        to: '2.6.0',
+        note: "the fatigue store (body.depletion) is optional and starts absent; the bodily forecast now applies an open fast's hunger damping, which changes only offers that declare followedBy",
+        apply: stamp,
+    },
+    '2.4.0': {
+        to: '2.5.0',
+        note: 'person shape unchanged; offers may declare followedBy spans for a bodily forecast; offers without it are unchanged',
+        apply: stamp,
+    },
     '2.3.0': {
         to: '2.4.0',
         note: 'promptings are optional and start absent; existing hosts retain exact behavior',

package/dist/person.d.ts

@@ -1,3 +1,4 @@
+import { type BodyForecastSpan } from './body/index.ts';
 import { type NafsPattern } from './promptings/index.ts';
 import { type SkillTransfer } from './skills/index.ts';
 import type { Activity, Affordance, BodyLoad, BodyReadout, Command, Commitment, DecisionRecord, LearningDomain, Minute, NeedId, NeedReading, NormDefinition, Outcome, Percept, Person, PersonSpec, Retention, Suggestion, SuggestionResolution, Unit } from './types.ts';
@@ -236,3 +237,11 @@ export declare function setRetention(p: Person, retention: Retention): void;
  * 75:2, 89:27), each with the matching evidence in existing state. Descriptions, never a level or a rank.
  */
 export declare function nafsReading(p: Person): NafsPattern[];
+/**
+ * The person's own forecast of their body through an offer and its `followedBy` spans (2.5.0, read-only), with a
+ * first-person line ("I can do it, but I'll be spent for the descent."). Empty spans without `followedBy`.
+ */
+export declare function bodyForecast(p: Person, aff: Affordance): {
+    spans: BodyForecastSpan[];
+    line: string;
+};

package/dist/person.js

@@ -22,7 +22,7 @@
 import { actionTendencies, advanceAffect, appraise, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, feel, readAffect, regulate, release, skipAffect, skipCrisis, strain, tendencyEmotions, } from './affect/index.js';
 import { advanceAgenda, createAgenda, onFinished, promise, proposeGoals, revisePurposes, } from './agenda/index.js';
 import { advanceBeliefs, attend, believe, confirm, credence } from './beliefs/index.js';
-import { advanceBody, BODY_DEFAULTS, checkDowned, clearDowned, consume, createBody, downedAllows, expose, injure, nextBodyThreshold, readBody, setDowned, sicken, skipBody, } from './body/index.js';
+import { advanceBody, BODY_DEFAULTS, checkDowned, clearDowned, consume, createBody, downedAllows, enableFatigueStore, 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';
@@ -37,7 +37,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 { consumeConsequences, pruneConsequences, receiveConsequences } from './prospection/index.js';
+import { bodyForecastFor, consumeConsequences, forecastLine, pruneConsequences, receiveConsequences, } from './prospection/index.js';
 import { enableSkillRetention, learnByWatching, practise, seedSkills, } from './skills/index.js';
 import { advanceSocial, applyReputationBelief, careFor, closeness, judge, markDeceased, 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';
@@ -154,6 +154,8 @@ export function createPerson(spec) {
         enableCharacterChange(p);
     if (on?.skillRetention)
         enableSkillRetention(p);
+    if (on?.fatigueStore)
+        enableFatigueStore(p);
     if (on?.promptings)
         enablePromptings(p, on.promptings);
     return p;
@@ -732,6 +734,9 @@ function decisionInputs(p, affordances, id, opts) {
         necessity: opts.necessity ?? true,
         tendencyEmotions: tendencyEmotions(p),
     };
+    const perception = fastingCtx(p);
+    if (perception)
+        ctx.perception = perception;
     if (opts.suggestion)
         ctx.suggestion = opts.suggestion;
     // Only set when voices were given this way, so single-voice records keep their shape.
@@ -1410,3 +1415,11 @@ export function nafsReading(p) {
             guilt = Math.max(guilt, e.intensity);
     return nafsPatterns(p, { guiltLoad: guiltLoad(p), guilt });
 }
+/**
+ * The person's own forecast of their body through an offer and its `followedBy` spans (2.5.0, read-only), with a
+ * first-person line ("I can do it, but I'll be spent for the descent."). Empty spans without `followedBy`.
+ */
+export function bodyForecast(p, aff) {
+    const spans = bodyForecastFor(p, aff, lifeModifiers(p), fastingCtx(p));
+    return { spans, line: forecastLine(spans) };
+}

package/dist/prospection/forecast.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SCOPE (bodily forecast, 2.5.0): a person anticipates their own body during exertion they know must follow an
+ * act ("I can reach the top, but I'll be spent for the descent"). The host declares the follow-on spans on the
+ * offer (`Affordance.followedBy`); the person simulates a copy of their body through the act and those spans with
+ * the ordinary body model, reads it as they perceive it, and weighs the worst perceived fatigue, sleepiness,
+ * hunger or thirst during the follow-on spans. One term, `forecast:body` = -forecastScale × smoothstep(comfortAt,
+ * spentAt, worst), joins the offer's utility; it is pure and draws no randomness. Offers without `followedBy`
+ * get no forecast, so existing hosts continue exactly.
+ *
+ * The forecast inherits the body model's limits and the person's misperceptions. Exertion relaxes toward the
+ * current effort; only a person with the opt-in fatigue store (2.6.0, `enableFatigueStore`) carries accumulated
+ * exertion, so only then does a long climb by itself leave them more spent for the descent; unfelt
+ * sleep debt stays unfelt in the forecast; an open fast's damping of hunger and thirst applies (2.6.0) as it is
+ * now, held for the whole forecast even if the fast would end during it; host surroundings are not applied (the person's own body rates and life
+ * modifiers are, but not `ambient` parameters). Existing bleeding, illness and healing run in the copy, so an
+ * open wound can read as being spent, and death in the forecast reads as fully spent. The term is absolute
+ * (see `bodyForecastTerm`). It does not plan, search routes, schedule rests on the way or
+ * predict injuries, and it is not a calibrated estimate of human anticipation. Every number is an engineering
+ * default.
+ */
+import { type BodyForecastSpan, type BodyPerceptionContext } from '../body/index.ts';
+import type { Affordance, LifeModifiers, Person, Term } from '../types.ts';
+export declare const FORECAST_DEFAULTS: {
+    /** Worst perceived readout during a follow-on from which the forecast starts to weigh. */
+    readonly comfortAt: 0.8;
+    /** Worst perceived readout at which the person expects to be spent (full weight). */
+    readonly spentAt: 0.97;
+    /** Weight at full expected spending (utility units; the effort term is on the order of 0.1–1). */
+    readonly forecastScale: 1.2;
+    /** At most this many follow-on spans are read, and at most this many minutes in total. */
+    readonly maxSpans: 4;
+    readonly maxMinutes: number;
+};
+/** The person's forecast for an offer: the act, then its follow-on spans. Empty without `followedBy`. Pure. */
+export declare function bodyForecastFor(p: Person, aff: Affordance, mods: LifeModifiers, perception?: BodyPerceptionContext): BodyForecastSpan[];
+/**
+ * The `forecast:body` term for an offer, or undefined (no follow-on, or not expected to weigh). Absolute by
+ * design: it weighs being in that state *while doing* the follow-on, so a person already sleepy or thirsty is
+ * charged for exerting so, while an offer with no declared follow-on is not (a night hike with a declared descent
+ * costs more than staying home). A resting baseline was tried and rejected: thirst and sleepiness rise at rest
+ * too, which cancelled the very case the forecast exists for. Pure.
+ */
+export declare function bodyForecastTerm(p: Person, aff: Affordance, mods: LifeModifiers, perception?: BodyPerceptionContext): Term | undefined;
+/** A first-person line for the forecast (narration only). */
+export declare function forecastLine(spans: readonly BodyForecastSpan[]): string;

package/dist/prospection/forecast.js

@@ -0,0 +1,103 @@
+/**
+ * SCOPE (bodily forecast, 2.5.0): a person anticipates their own body during exertion they know must follow an
+ * act ("I can reach the top, but I'll be spent for the descent"). The host declares the follow-on spans on the
+ * offer (`Affordance.followedBy`); the person simulates a copy of their body through the act and those spans with
+ * the ordinary body model, reads it as they perceive it, and weighs the worst perceived fatigue, sleepiness,
+ * hunger or thirst during the follow-on spans. One term, `forecast:body` = -forecastScale × smoothstep(comfortAt,
+ * spentAt, worst), joins the offer's utility; it is pure and draws no randomness. Offers without `followedBy`
+ * get no forecast, so existing hosts continue exactly.
+ *
+ * The forecast inherits the body model's limits and the person's misperceptions. Exertion relaxes toward the
+ * current effort; only a person with the opt-in fatigue store (2.6.0, `enableFatigueStore`) carries accumulated
+ * exertion, so only then does a long climb by itself leave them more spent for the descent; unfelt
+ * sleep debt stays unfelt in the forecast; an open fast's damping of hunger and thirst applies (2.6.0) as it is
+ * now, held for the whole forecast even if the fast would end during it; host surroundings are not applied (the person's own body rates and life
+ * modifiers are, but not `ambient` parameters). Existing bleeding, illness and healing run in the copy, so an
+ * open wound can read as being spent, and death in the forecast reads as fully spent. The term is absolute
+ * (see `bodyForecastTerm`). It does not plan, search routes, schedule rests on the way or
+ * predict injuries, and it is not a calibrated estimate of human anticipation. Every number is an engineering
+ * default.
+ */
+import { BODY_DEFAULTS, forecastBody, } from '../body/index.js';
+import { clamp01, round } from '../core/index.js';
+export const FORECAST_DEFAULTS = {
+    /** Worst perceived readout during a follow-on from which the forecast starts to weigh. */
+    comfortAt: 0.8,
+    /** Worst perceived readout at which the person expects to be spent (full weight). */
+    spentAt: 0.97,
+    /** Weight at full expected spending (utility units; the effort term is on the order of 0.1–1). */
+    forecastScale: 1.2,
+    /** At most this many follow-on spans are read, and at most this many minutes in total. */
+    maxSpans: 4,
+    maxMinutes: 24 * 60,
+};
+const smooth = (a, b, x) => {
+    const t = clamp01((x - a) / (b - a));
+    return t * t * (3 - 2 * t);
+};
+/** The person's forecast for an offer: the act, then its follow-on spans. Empty without `followedBy`. Pure. */
+export function bodyForecastFor(p, aff, mods, perception) {
+    const follow = aff.followedBy;
+    if (!Array.isArray(follow) || follow.length === 0 || !p.body.alive)
+        return [];
+    const D = FORECAST_DEFAULTS;
+    const d0 = Number.isFinite(aff.duration) ? Math.min(D.maxMinutes, Math.max(0, aff.duration)) : 0;
+    const spans = [
+        {
+            label: aff.label,
+            duration: d0,
+            load: {
+                effort: clamp01(aff.effort),
+                focus: clamp01(aff.focus ?? 0),
+                mode: aff.mode ?? 'awake',
+            },
+        },
+    ];
+    let total = spans[0]?.duration ?? 0;
+    for (const f of follow.slice(0, D.maxSpans)) {
+        if (!f || typeof f !== 'object')
+            continue;
+        const d = Number.isFinite(f.duration) ? Math.max(0, f.duration) : 0;
+        if (total + d > D.maxMinutes)
+            break;
+        total += d;
+        spans.push({
+            label: f.label ?? 'after',
+            duration: d,
+            load: { effort: clamp01(f.effort), focus: clamp01(f.focus ?? 0), mode: 'awake' },
+        });
+    }
+    return forecastBody(p, spans, mods, BODY_DEFAULTS, 30, perception);
+}
+/**
+ * The `forecast:body` term for an offer, or undefined (no follow-on, or not expected to weigh). Absolute by
+ * design: it weighs being in that state *while doing* the follow-on, so a person already sleepy or thirsty is
+ * charged for exerting so, while an offer with no declared follow-on is not (a night hike with a declared descent
+ * costs more than staying home). A resting baseline was tried and rejected: thirst and sleepiness rise at rest
+ * too, which cancelled the very case the forecast exists for. Pure.
+ */
+export function bodyForecastTerm(p, aff, mods, perception) {
+    const spans = bodyForecastFor(p, aff, mods, perception).slice(1);
+    if (spans.length === 0)
+        return undefined;
+    const D = FORECAST_DEFAULTS;
+    const worst = Math.max(...spans.map((s) => s.worst));
+    const v = round(-D.forecastScale * smooth(D.comfortAt, D.spentAt, worst));
+    return v < 0 ? { source: 'forecast:body', value: v } : undefined;
+}
+/** A first-person line for the forecast (narration only). */
+export function forecastLine(spans) {
+    const after = spans.slice(1);
+    if (after.length === 0)
+        return '';
+    let w = after[0];
+    for (const s of after)
+        if (s.worst > w.worst)
+            w = s;
+    const what = { fatigue: 'spent', sleepiness: 'too sleepy', hunger: 'too hungry', thirst: 'too thirsty' }[w.worstOf];
+    if (w.worst >= FORECAST_DEFAULTS.spentAt)
+        return `I can do it, but I'll be ${what} for ${w.label}.`;
+    if (w.worst >= FORECAST_DEFAULTS.comfortAt)
+        return `I can do it, though ${w.label} will be hard.`;
+    return `I'll still have enough for ${w.label}.`;
+}

package/dist/prospection/index.d.ts

@@ -1 +1,2 @@
+export * from './forecast.ts';
 export * from './prospection.ts';

package/dist/prospection/index.js

@@ -1 +1,2 @@
+export * from './forecast.js';
 export * from './prospection.js';

package/dist/types.d.ts

@@ -86,6 +86,11 @@ export interface BodyState {
     illnesses: Illness[];
     /** Accumulated sleep debt in hours (chronic restriction); under-perceived by the person. */
     sleepDebt: number;
+    /**
+     * Accumulated exertion (2.6.0, opt-in via `enableFatigueStore`): 0..1, rising slowly with sustained effort and
+     * recovering with rest and faster with sleep. Raises felt fatigue and lowers capacity. Absent = no store.
+     */
+    depletion?: Unit;
     asleep: boolean;
     /** Minute the current sleep or wake period began. */
     since: Minute;
@@ -827,7 +832,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.4.0";
+export declare const ENGINE_VERSION = "2.6.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1092,6 +1097,12 @@ export interface Affordance {
         severity: Unit;
         kind: string;
     };
+    /**
+     * Exertion the person knows must follow this act (2.5.0): the way back down, carrying the load home. The
+     * person forecasts their own body through the act and these spans (`prospection/` forecast) and weighs being
+     * spent during them. Absent = no forecast, exactly as before.
+     */
+    followedBy?: FollowOn[];
     /** Set on a partner's mirror offer by the joint protocol in `sim/` (the proposal id). */
     jointId?: string;
     /** Material gain/cost in host units (e.g. coins). Valued via security/achievement/power values. */
@@ -1298,7 +1309,8 @@ export interface Term {
     /** 'need:food', 'norm:salah', 'commitment:c3', 'commitment' (promise inertia of the running activity),
      *  'goal:g1', 'habit', 'emotion:fear:risky' (emotion id, then the tag it acts through), 'effort', 'risk',
      *  'suggestion:player', 'social:p2', 'expectation', 'autonomy' (reactance to a pushing voice),
-     *  'promptings:turn' (a practised turning-away), 'promptings:echo' (recurrence under the `fault` reading) */
+     *  'promptings:turn' (a practised turning-away), 'forecast:body' (expected
+     *  bodily state during `followedBy` spans), 'promptings:echo' (recurrence under the `fault` reading) */
     source: string;
     value: number;
 }
@@ -1386,10 +1398,20 @@ export interface PersonSpec {
         yearbook?: boolean;
         character?: boolean;
         skillRetention?: boolean;
+        /** Accumulated exertion (2.6.0): the same as `enableFatigueStore(p)` after creation. */
+        fatigueStore?: boolean;
         /** Promptings and turning away (2.4.0): the same as `enablePromptings(p, spec)` after creation. */
         promptings?: PromptingsSpec;
     };
 }
+/** A known span of exertion after an act (see `Affordance.followedBy`). */
+export interface FollowOn {
+    label?: string;
+    /** Minutes. */
+    duration: number;
+    effort: Unit;
+    focus?: Unit;
+}
 /**
  * How a person understands their own unwanted inner pulls (a held reading, set by the host, with provenance).
  * `whisper`, `inclination` and `intrusion` share mechanics and differ only in vocabulary; `fault` (the scrupulous

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

package/package.json

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