@adam0white/human-framework 2.5.0 → 2.7.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
@@ -205,4 +216,4 @@ export declare function forecastBody(p: Person, spans: readonly {
     label: string;
     duration: number;
     load: BodyLoad;
-}[], mods: LifeModifiers, params?: BodyParams, step?: number): BodyForecastSpan[];
+}[], 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);
@@ -767,7 +796,7 @@ export function nextBodyThreshold(p, load, mods, thresholds = { hunger: 0.7, thi
  * 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) {
+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) {
@@ -775,7 +804,7 @@ export function forecastBody(p, spans, mods, params = BODY_DEFAULTS, step = 30)
         // 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).perceived;
+        const r0 = readBody(sim, params, perception).perceived;
         for (const k of ['fatigue', 'sleepiness', 'hunger', 'thirst'])
             if (r0[k] > span.worst) {
                 span.worst = r0[k];
@@ -786,7 +815,7 @@ export function forecastBody(p, spans, mods, params = BODY_DEFAULTS, step = 30)
             advanceBody(sim, dt, s.load, mods, params);
             sim.now += dt;
             left -= dt;
-            const r = readBody(sim, params).perceived;
+            const r = readBody(sim, params, perception).perceived;
             for (const k of ['fatigue', 'sleepiness', 'hunger', 'thirst'])
                 if (r[k] > span.worst) {
                     span.worst = r[k];

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

@@ -36,6 +36,7 @@ import { urgencyOf } from '../needs/index.js';
 import { partneringTerms } from '../partnering/index.js';
 import { promptIn, promptingTerms } from '../promptings/index.js';
 import { bodyForecastTerm, receivedGoalRoute } from '../prospection/index.js';
+import { reviewTerms } from '../review/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';
@@ -351,7 +352,7 @@ export function consider(p, aff, ctx) {
         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);
+        const t = bodyForecastTerm(p, aff, ctx.mods, ctx.perception);
         if (t)
             push(t.source, t.value);
     }
@@ -409,6 +410,10 @@ export function consider(p, aff, ctx) {
     if (p.promptings)
         for (const t of promptingTerms(p, aff.action, terms, aff.tags, ctx.now, ctx.desperation))
             push(t.source, t.value);
+    // Evening review (2.7.0, opt-in): a resolve formed after a lapse leans on that commitment's own term.
+    if (p.review)
+        for (const t of reviewTerms(p, terms))
+            push(t.source, t.value);
     let utility = 0;
     for (const t of terms)
         utility += t.value;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,5 +1,5 @@
 /** Human Framework v1 public surface. */
-export const FRAMEWORK_VERSION = '2.5.0';
+export const FRAMEWORK_VERSION = '2.7.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';
@@ -28,6 +28,7 @@ export * from './person.js';
 export * from './promptings/index.js';
 export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, FORECAST_DEFAULTS, forecastLine, PROSPECTION_DEFAULTS, } from './prospection/index.js';
 export * from './restore.js';
+export * from './review/index.js';
 export * from './scenarios/index.js';
 export * from './sim/index.js';
 export * from './skills/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. 2.4.0 to 2.5.0 stamps the version; the bodily forecast reads only offers that declare `followedBy`. 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. 2.6.0 to 2.7.0 stamps the version; the evening review 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.6.0': {
+        to: '2.7.0',
+        note: 'the evening review (review) is optional and starts absent; existing hosts retain exact behavior',
+        apply: stamp,
+    },
+    '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',

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';
@@ -38,6 +38,7 @@ import { advanceNeeds, createNeeds, levelOf, meanSatisfaction, readNeeds, satisf
 import { widow } from './partnering/index.js';
 import { enablePromptings, nafsPatterns, notePromptings } from './promptings/index.js';
 import { bodyForecastFor, consumeConsequences, forecastLine, 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, 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,8 +155,12 @@ export function createPerson(spec) {
         enableCharacterChange(p);
     if (on?.skillRetention)
         enableSkillRetention(p);
+    if (on?.fatigueStore)
+        enableFatigueStore(p);
     if (on?.promptings)
         enablePromptings(p, on.promptings);
+    if (on?.review)
+        enableReview(p, on.review);
     return p;
 }
 /**
@@ -416,6 +421,12 @@ export function tick(p, now) {
                 closed = closeDay(p);
                 applyRecall(p, recallByCue(p, { at: end }));
             }
+            // Evening review (2.7.0, opt-in): from its hour, or at the close of a day that passed without one.
+            if (p.review) {
+                const done = reviewIfDue(p, end, (p.chronicle ?? []).slice(-2), closed);
+                if (done && done.distress > 0)
+                    feel(p, 'distress', done.distress, 'review', end);
+            }
             if (minuteOfDay(end) === 0) {
                 // Lasting gists (1.8.0, opt-in): at midnight, episodes past the horizon fold into gists.
                 if (p.memory.gists)
@@ -732,6 +743,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.
@@ -1415,6 +1429,6 @@ export function nafsReading(p) {
  * 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));
+    const spans = bodyForecastFor(p, aff, lifeModifiers(p), fastingCtx(p));
     return { spans, line: forecastLine(spans) };
 }

package/dist/prospection/forecast.d.ts

@@ -7,18 +7,18 @@
  * 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: HF exertion relaxes toward the
- * current effort (no cumulative glycogen or muscle-damage store), so a long climb does not by itself leave a
- * person more spent for the descent unless sleepiness, hunger, thirst or the descent's own effort do; unfelt
- * sleep debt stays unfelt in the forecast; a fast's damped hunger and thirst are not applied (so a fasting
- * person forecasts them undamped); host surroundings are not applied (the person's own body rates and life
+ * 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 } from '../body/index.ts';
+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. */
@@ -32,7 +32,7 @@ export declare const FORECAST_DEFAULTS: {
     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): BodyForecastSpan[];
+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
@@ -40,6 +40,6 @@ export declare function bodyForecastFor(p: Person, aff: Affordance, mods: LifeMo
  * 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): Term | undefined;
+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

@@ -7,18 +7,18 @@
  * 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: HF exertion relaxes toward the
- * current effort (no cumulative glycogen or muscle-damage store), so a long climb does not by itself leave a
- * person more spent for the descent unless sleepiness, hunger, thirst or the descent's own effort do; unfelt
- * sleep debt stays unfelt in the forecast; a fast's damped hunger and thirst are not applied (so a fasting
- * person forecasts them undamped); host surroundings are not applied (the person's own body rates and life
+ * 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 { forecastBody } from '../body/index.js';
+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. */
@@ -36,7 +36,7 @@ const smooth = (a, b, x) => {
     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) {
+export function bodyForecastFor(p, aff, mods, perception) {
     const follow = aff.followedBy;
     if (!Array.isArray(follow) || follow.length === 0 || !p.body.alive)
         return [];
@@ -67,7 +67,7 @@ export function bodyForecastFor(p, aff, mods) {
             load: { effort: clamp01(f.effort), focus: clamp01(f.focus ?? 0), mode: 'awake' },
         });
     }
-    return forecastBody(p, spans, mods);
+    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
@@ -76,8 +76,8 @@ export function bodyForecastFor(p, aff, mods) {
  * 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) {
-    const spans = bodyForecastFor(p, aff, mods).slice(1);
+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;

package/dist/restore.js

@@ -22,6 +22,7 @@ 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 { sanitizeReview } from './review/index.js';
 import { sanitizeSkillRetention } from './skills/index.js';
 import { sanitizeGroups, sanitizeImpressions } from './social/index.js';
 import { ENGINE_VERSION, MAX_MINUTE, PERSON_SCHEMA } from './types.js';
@@ -63,6 +64,7 @@ const OPTIONAL_KEYS = new Set([
     'methods',
     'prospection',
     'promptings',
+    'review',
 ]);
 /** Kind of a JSON value for the per-field type check in `restore`. */
 const kindOf = (x) => (Array.isArray(x) ? 'array' : x === null ? 'null' : typeof x);
@@ -177,6 +179,7 @@ export function restore(input) {
     keepValid(out, 'methods', sanitizeMethods);
     keepValid(out, 'prospection', (x) => sanitizeProspection(x, out.now, out.id));
     keepValid(out, 'promptings', (x) => sanitizePromptings(x, out.now));
+    keepValid(out, 'review', (x) => sanitizeReview(x, out.now));
     boundLists(out);
     return out;
 }

package/dist/review/index.d.ts

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

package/dist/review/index.js

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

package/dist/review/review.d.ts

@@ -0,0 +1,47 @@
+import type { DayRecord, Minute, Person, ReviewRecord, ReviewSpec, ReviewState, ReviewStyle, Term } from '../types.ts';
+export declare const REVIEW_DEFAULTS: {
+    /** Default evening review time, minute of day. */
+    at: number;
+    /** Largest `review:resolve` term at full strength. */
+    resolveScale: number;
+    /** Share of the remaining headroom a lapse adds, by style. */
+    gain: Record<ReviewStyle, number>;
+    /** Strength kept after the commitment is kept. */
+    keptKeep: number;
+    halfLifeDays: number;
+    /** Resolves weaker than this are dropped. */
+    dropBelow: number;
+    maxResolves: number;
+    maxSeen: number;
+    /** Distress felt per lapse by a ruminating reviewer, capped at `ruminateMax`. */
+    ruminatePer: number;
+    ruminateMax: number;
+};
+/** Turn on the evening review. Idempotent; a second call updates style, source and time but keeps resolves. */
+export declare function enableReview(p: Person, spec?: ReviewSpec): ReviewState;
+/** The key a commitment and its chronicle note share: kind, owed-to, and label (else first action). */
+export declare const resolveKey: (c: {
+    label?: string | undefined;
+    kind: string;
+    action?: string | undefined;
+    actions?: readonly string[];
+    toId?: string | undefined;
+}) => string;
+/**
+ * The `review:resolve` terms for an option, read from its already-traced `commitment:*` and `abstain:*` terms.
+ * Pure; empty when review is off or no resolve matches.
+ */
+export declare function reviewTerms(p: Person, terms: readonly Term[]): Term[];
+/**
+ * Review now if it is due: at or after `at` on a day not yet reviewed, or when `closed` (the day just closed)
+ * was never reviewed. Reads the notes of `recent` (the latest closed day records) and the open day. Returns the
+ * record, or undefined when nothing ran. Distress for a ruminating reviewer is returned for the composite to feel.
+ */
+export declare function reviewIfDue(p: Person, now: Minute, recent: readonly DayRecord[], closed?: DayRecord): {
+    record: ReviewRecord;
+    distress: number;
+} | undefined;
+/** The person's own words for their latest review, or undefined when they hold no review. */
+export declare function reviewLine(p: Person): string | undefined;
+/** Restore guard: drop malformed fields, keep valid resolves. */
+export declare function sanitizeReview(x: unknown, now?: Minute): ReviewState | undefined;

package/dist/review/review.js

@@ -0,0 +1,239 @@
+/**
+ * SCOPE (evening self-review, muhasaba, 2.7.0): once a day, from `at` (default 21:00), a person looks back over
+ * the commitments the chronicle recorded as kept or broken since their last review, and for each one they broke
+ * forms or renews a *resolve*: an if–then intention for that commitment's next occasion (Gollwitzer & Sheeran
+ * 2006, research/reconciliation.md E1). While a matching commitment is pending, the resolve adds one bounded term,
+ * `review:resolve` (each resolve counted once per option, the sum clamped to ±`resolveScale`), with the sign of the commitment's own term (toward a duty, away from an abstention's breaking
+ * act), scaled by its strength. Strength grows with diminishing gains at each further lapse, relaxes once the
+ * commitment is kept, and fades over `halfLifeDays` of disuse. Released and excused commitments (exemptions,
+ * sleep, necessity) form no resolve: what was beyond capacity is not held against the person (2:286). The review
+ * also runs when the day closes, if the evening passed without it or a lapse came after it.
+ *
+ * Held readings (`ReviewStyle`): `accounting` is self-accounting as the tradition describes it, naming the lapse
+ * with a view to tomorrow (Q 59:18, whose "tomorrow" most exegetes read as the hereafter, so a daily review is an
+ * inference; ʿUmar's saying reported by Tirmidhi after 2459, an athar, not a prophetic
+ * hadith) and turning back without despair (3:135, 39:53); it forms full resolves and adds no emotion. Reading accounting as
+ * non-punishing, like self-compassion after failure raising the motivation to repair (Breines & Chen 2012, E3),
+ * is an engineering mapping, not a finding about muhasaba. `ruminating` goes over
+ * the lapse abstractly: weaker resolves and a small distress emotion (Watkins 2008, E4: abstract, unconstructive
+ * repetitive thought). `none` never reviews. The review reads only chronicle notes and changes no other module's
+ * state except that one emotion.
+ *
+ * Every number is an engineering default, not fitted. Does not claim: divine reckoning or acceptance, a measure of
+ * piety, repentance as a ruling (tawba conditions are not modelled), effects on sleep onset (Harvey's model, E6, is
+ * not evidence enough), or that review improves outcomes beyond the borrowed if–then shape. It draws no randomness;
+ * without `enableReview` nothing here runs and existing runs replay byte for byte.
+ */
+import { clamp01, dexp, isObj, minuteOfDay, round } from '../core/index.js';
+export const REVIEW_DEFAULTS = {
+    /** Default evening review time, minute of day. */
+    at: 21 * 60,
+    /** Largest `review:resolve` term at full strength. */
+    resolveScale: 0.3,
+    /** Share of the remaining headroom a lapse adds, by style. */
+    gain: { accounting: 0.5, ruminating: 0.15, none: 0 },
+    /** Strength kept after the commitment is kept. */
+    keptKeep: 0.6,
+    halfLifeDays: 7,
+    /** Resolves weaker than this are dropped. */
+    dropBelow: 0.05,
+    maxResolves: 8,
+    maxSeen: 64,
+    /** Distress felt per lapse by a ruminating reviewer, capped at `ruminateMax`. */
+    ruminatePer: 0.15,
+    ruminateMax: 0.45,
+};
+const STYLES = ['accounting', 'ruminating', 'none'];
+/** Turn on the evening review. Idempotent; a second call updates style, source and time but keeps resolves. */
+export function enableReview(p, spec = {}) {
+    const at = spec.at !== undefined && Number.isInteger(spec.at) && spec.at >= 0 && spec.at < 1440
+        ? spec.at
+        : undefined;
+    const cur = p.review;
+    const st = cur ?? { style: 'accounting', at: REVIEW_DEFAULTS.at, resolves: [] };
+    if (spec.style && STYLES.includes(spec.style))
+        st.style = spec.style;
+    if (spec.styleSource !== undefined)
+        st.styleSource = spec.styleSource.slice(0, 96);
+    if (at !== undefined)
+        st.at = at;
+    p.review = st;
+    return st;
+}
+/** The key a commitment and its chronicle note share: kind, owed-to, and label (else first action). */
+export const resolveKey = (c) => `${c.kind}:${c.toId ?? ''}:${c.label ?? c.action ?? c.actions?.[0] ?? ''}`;
+/**
+ * The `review:resolve` terms for an option, read from its already-traced `commitment:*` and `abstain:*` terms.
+ * Pure; empty when review is off or no resolve matches.
+ */
+export function reviewTerms(p, terms) {
+    const st = p.review;
+    if (!st || st.resolves.length === 0)
+        return [];
+    let value = 0;
+    const used = new Set();
+    for (const t of terms) {
+        const m = /^(commitment|abstain):(.+)$/.exec(t.source);
+        if (!m || t.value === 0)
+            continue;
+        const c = p.agenda.commitments.find((x) => x.id === m[2]);
+        if (!c)
+            continue;
+        const r = st.resolves.find((x) => x.key === resolveKey(c));
+        if (!r || used.has(r.key))
+            continue;
+        used.add(r.key);
+        value += Math.sign(t.value) * REVIEW_DEFAULTS.resolveScale * r.strength;
+    }
+    const max = REVIEW_DEFAULTS.resolveScale;
+    value = Math.max(-max, Math.min(max, value));
+    return value === 0 ? [] : [{ source: 'review:resolve', value: round(value) }];
+}
+const fade = (s, days) => days <= 0 ? s : s * dexp((-Math.LN2 * days) / REVIEW_DEFAULTS.halfLifeDays);
+/**
+ * Review now if it is due: at or after `at` on a day not yet reviewed, or when `closed` (the day just closed)
+ * was never reviewed. Reads the notes of `recent` (the latest closed day records) and the open day. Returns the
+ * record, or undefined when nothing ran. Distress for a ruminating reviewer is returned for the composite to feel.
+ */
+export function reviewIfDue(p, now, recent, closed) {
+    const st = p.review;
+    if (!st || st.style === 'none')
+        return undefined;
+    const today = Math.floor(now / 1440);
+    const seenNow = new Set(st.seen ?? []);
+    const lateLapse = closed?.broken.some((n) => !seenNow.has(n.id)) ?? false;
+    let day;
+    if (closed && (st.lastDay === undefined || st.lastDay < closed.day || lateLapse))
+        day = Math.max(closed.day, st.lastDay ?? closed.day);
+    else if (minuteOfDay(now) >= st.at && (st.lastDay === undefined || st.lastDay < today))
+        day = today;
+    else
+        return undefined;
+    const seen = new Set(st.seen ?? []);
+    const notes = (kind) => {
+        const out = [];
+        for (const r of closed && !recent.includes(closed) ? [...recent, closed] : recent)
+            for (const n of r[kind])
+                if (!seen.has(n.id))
+                    out.push(n);
+        const open = p.chronicleDay;
+        if (open && open.day <= day)
+            for (const n of open[kind])
+                if (!seen.has(n.id))
+                    out.push(n);
+        return out;
+    };
+    const broken = notes('broken');
+    const kept = notes('kept');
+    const elapsed = st.lastDay === undefined ? 0 : day - st.lastDay;
+    for (const r of st.resolves)
+        r.strength = round(fade(r.strength, elapsed));
+    const gain = REVIEW_DEFAULTS.gain[st.style];
+    const missed = [];
+    const resolved = [];
+    for (const n of broken) {
+        const key = resolveKey(n);
+        const name = n.label ?? n.action ?? n.kind;
+        if (!missed.includes(name))
+            missed.push(name);
+        let r = st.resolves.find((x) => x.key === key);
+        if (!r) {
+            r = { key, kind: n.kind, strength: 0, day };
+            if (n.label !== undefined)
+                r.label = n.label;
+            st.resolves.push(r);
+        }
+        r.strength = round(clamp01(r.strength + gain * (1 - r.strength)));
+        r.day = day;
+        if (!resolved.includes(name))
+            resolved.push(name);
+    }
+    const keptNames = [];
+    for (const n of kept) {
+        const key = resolveKey(n);
+        const name = n.label ?? n.action ?? n.kind;
+        if (!keptNames.includes(name))
+            keptNames.push(name);
+        const r = st.resolves.find((x) => x.key === key);
+        if (r && !broken.some((b) => resolveKey(b) === key))
+            r.strength = round(r.strength * REVIEW_DEFAULTS.keptKeep);
+    }
+    st.resolves = st.resolves
+        .filter((r) => r.strength >= REVIEW_DEFAULTS.dropBelow)
+        .sort((a, b) => b.strength - a.strength || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+        .slice(0, REVIEW_DEFAULTS.maxResolves);
+    const ids = [...(st.seen ?? []), ...broken.map((n) => n.id), ...kept.map((n) => n.id)];
+    st.seen = ids.slice(-REVIEW_DEFAULTS.maxSeen);
+    st.lastDay = day;
+    const record = {
+        day,
+        missed,
+        kept: keptNames,
+        resolved: st.style === 'accounting' ? resolved : [],
+    };
+    st.last = record;
+    const distress = st.style === 'ruminating'
+        ? Math.min(REVIEW_DEFAULTS.ruminateMax, REVIEW_DEFAULTS.ruminatePer * missed.length)
+        : 0;
+    return { record, distress };
+}
+/** The person's own words for their latest review, or undefined when they hold no review. */
+export function reviewLine(p) {
+    const st = p.review;
+    const r = st?.last;
+    if (!st || st.style === 'none' || !r)
+        return undefined;
+    const list = (xs) => xs.length <= 1 ? (xs[0] ?? '') : `${xs.slice(0, -1).join(', ')} and ${xs.at(-1)}`;
+    if (r.missed.length === 0)
+        return r.kept.length > 0 ? `Today I kept ${list(r.kept)}.` : undefined;
+    if (st.style === 'ruminating')
+        return `I keep going back over ${list(r.missed)}.`;
+    return `I didn't keep ${list(r.missed)}. Next time I'll be ready when it comes.`;
+}
+/** Restore guard: drop malformed fields, keep valid resolves. */
+export function sanitizeReview(x, now) {
+    if (!isObj(x))
+        return undefined;
+    const style = STYLES.includes(x.style) ? x.style : 'accounting';
+    const at = Number.isInteger(x.at) && x.at >= 0 && x.at < 1440
+        ? x.at
+        : REVIEW_DEFAULTS.at;
+    const resolves = [];
+    if (Array.isArray(x.resolves))
+        for (const r of x.resolves) {
+            if (!isObj(r) || typeof r.key !== 'string' || typeof r.kind !== 'string')
+                continue;
+            if (typeof r.strength !== 'number' || !Number.isFinite(r.strength) || !Number.isInteger(r.day))
+                continue;
+            const out = {
+                key: r.key.slice(0, 96),
+                kind: r.kind.slice(0, 32),
+                strength: clamp01(r.strength),
+                day: r.day,
+            };
+            if (typeof r.label === 'string')
+                out.label = r.label.slice(0, 96);
+            if (!resolves.some((y) => y.key === out.key))
+                resolves.push(out);
+            if (resolves.length >= REVIEW_DEFAULTS.maxResolves)
+                break;
+        }
+    const st = { style, at, resolves };
+    if (typeof x.styleSource === 'string')
+        st.styleSource = x.styleSource.slice(0, 96);
+    if (Number.isInteger(x.lastDay) && (now === undefined || x.lastDay <= Math.floor(now / 1440)))
+        st.lastDay = x.lastDay;
+    if (Array.isArray(x.seen))
+        st.seen = x.seen.filter((s) => typeof s === 'string').slice(-REVIEW_DEFAULTS.maxSeen);
+    const l = x.last;
+    if (isObj(l) && Number.isInteger(l.day)) {
+        const strs = (v) => Array.isArray(v) ? v.filter((s) => typeof s === 'string').slice(0, 24) : [];
+        st.last = {
+            day: l.day,
+            missed: strs(l.missed),
+            kept: strs(l.kept),
+            resolved: strs(l.resolved),
+        };
+    }
+    return st;
+}

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.5.0";
+export declare const ENGINE_VERSION = "2.7.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -994,6 +999,8 @@ export interface Person {
     prospection?: ProspectionState;
     /** Noticed promptings and practised turnings-away (2.4.0, opt-in via `enablePromptings`). Owned by `promptings/`. */
     promptings?: PromptingsState;
+    /** Evening self-review and its resolves (2.7.0, opt-in via `enableReview`). Owned by `review/`. */
+    review?: ReviewState;
     /** Practice consolidation (1.8.0, opt-in via `enableSkillRetention`). Owned by `skills/`. */
     skillRetention?: {
         consolidationHours: number;
@@ -1393,8 +1400,12 @@ 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;
+        /** Evening self-review (2.7.0): the same as `enableReview(p, spec)` after creation. */
+        review?: ReviewSpec;
     };
 }
 /** A known span of exertion after an act (see `Affordance.followedBy`). */
@@ -1447,6 +1458,47 @@ export interface PromptingsState {
     /** Echo gained per prompt under `fault`. Default 0: the recurrence term is a host-set assumption (P3 contested). */
     echoRate: number;
 }
+/**
+ * How a person reviews a day (2.7.0, a held reading): `accounting` (muhasaba: name the lapse and resolve for its
+ * next occasion), `ruminating` (go over it abstractly: weaker resolve, some distress) or `none` (no review).
+ */
+export type ReviewStyle = 'accounting' | 'ruminating' | 'none';
+/** A resolve formed in review: an if-then intention for the next occasion of a missed commitment. */
+export interface Resolve {
+    /** The commitment's label, else its first action, else its kind. */
+    key: string;
+    label?: string;
+    kind: string;
+    strength: Unit;
+    /** Day the resolve was formed or last renewed. */
+    day: number;
+}
+/** What the person concluded in their latest review. */
+export interface ReviewRecord {
+    day: number;
+    missed: string[];
+    kept: string[];
+    resolved: string[];
+}
+/** Owned by `review/`. */
+export interface ReviewState {
+    style: ReviewStyle;
+    styleSource?: string;
+    /** Minute of the day from which the evening review can run (default 21:00). */
+    at: number;
+    /** Last day reviewed. */
+    lastDay?: number;
+    resolves: Resolve[];
+    last?: ReviewRecord;
+    /** Commitment ids already reviewed (bounded). */
+    seen?: string[];
+}
+/** What a host hands `enableReview`. */
+export interface ReviewSpec {
+    style?: ReviewStyle;
+    styleSource?: string;
+    at?: number;
+}
 /** What a host hands `enablePromptings`. */
 export interface PromptingsSpec {
     reading?: PromptingReading;

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

package/package.json

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