@adam0white/human-framework 2.3.0 → 2.5.0

package/README.md

@@ -348,7 +348,7 @@ Import these functions from the package. Rules/evidence live in optional `Person
 
 ## Receiving a possible future route
 
-The pending 2.3.0 increment lets an attended explanation connect one current action to one possible successor. The host supplies the explanation the person received, not a private success bonus.
+HF 2.3.0 lets an attended explanation connect one current action to one possible successor. The host supplies the explanation the person received, not a private success bonus.
 
 ```ts
 import {

package/dist/body/body.d.ts

@@ -189,3 +189,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): BodyForecastSpan[];

package/dist/body/body.js

@@ -763,3 +763,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) {
+    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).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).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,4 +1,5 @@
 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';
 import { type CommandOutcome, type WillContext } from '../will/index.ts';
 export declare const COGNITION_DEFAULTS: {
@@ -132,6 +133,8 @@ export interface Decision {
     needDeltas: Partial<Record<'autonomy', number>>;
     /** How a command in force fared (absent when none). */
     command?: CommandOutcome;
+    /** Prompts noticed at this decision point (only with `p.promptings`); the composite records them. */
+    prompts?: PromptingSeen[];
 }
 /** Highest physiological urgency: the input to the necessity exception. */
 export declare function desperationOf(needs: NeedReading[]): number;

package/dist/cognition/cognition.js

@@ -34,7 +34,8 @@ import { expectedEffect } from '../memory/index.js';
 import { methodEvidence } from '../methods/index.js';
 import { urgencyOf } from '../needs/index.js';
 import { partneringTerms } from '../partnering/index.js';
-import { receivedGoalRoute } from '../prospection/index.js';
+import { promptIn, promptingTerms } from '../promptings/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';
@@ -348,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);
+        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');
@@ -398,6 +405,10 @@ export function consider(p, aff, ctx) {
     if (!inBreak(p))
         for (const t of rememberedTerms(p, aff, ctx.now, voices))
             push(t.source, t.value);
+    // Promptings (2.4.0, opt-in): a recurrence pull under `fault` and a practised turning-away from a noticed prompt.
+    if (p.promptings)
+        for (const t of promptingTerms(p, aff.action, terms, aff.tags, ctx.now, ctx.desperation))
+            push(t.source, t.value);
     let utility = 0;
     for (const t of terms)
         utility += t.value;
@@ -471,5 +482,22 @@ export function decide(p, affordances, ctx) {
     const out = { record, needDeltas };
     if (res.command)
         out.command = res.command;
+    if (p.promptings) {
+        const prompts = [];
+        const tagsOf = new Map(sorted.map((a) => [a.id, a.tags]));
+        for (const c of res.considered) {
+            const seen = promptIn(c.terms, tagsOf.get(c.affordanceId));
+            if (seen)
+                prompts.push({
+                    affordanceId: c.affordanceId,
+                    action: c.action,
+                    ...seen,
+                    // A vetoed option was not turned from: the will blocked it, so the response earns no practice.
+                    turnApplied: c.vetoed === undefined && c.terms.some((t) => t.source === 'promptings:turn'),
+                });
+        }
+        if (prompts.length > 0)
+            out.prompts = prompts;
+    }
     return out;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework v1 public surface. */
-export declare const FRAMEWORK_VERSION = "2.3.0";
+export declare const FRAMEWORK_VERSION = "2.5.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';
@@ -28,8 +28,9 @@ export * from './narrate/index.ts';
 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 { 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.3.0';
+export const FRAMEWORK_VERSION = '2.5.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';
@@ -25,7 +25,8 @@ export * from './narrate/index.js';
 export * from './needs/index.js';
 export * from './partnering/index.js';
 export * from './person.js';
-export { consequenceEvidence, PROSPECTION_DEFAULTS } from './prospection/index.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 './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. 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`. 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.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',
+        apply: stamp,
+    },
     '2.2.0': {
         to: '2.3.0',
         note: 'received consequences and temporal goals are optional; existing hosts retain exact behavior',

package/dist/person.d.ts

@@ -1,3 +1,5 @@
+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';
 import { type CommandOutcome } from './will/index.ts';
@@ -230,3 +232,16 @@ export declare function finish(p: Person, outcome: Outcome, opts?: FinishOptions
  * entries are ignored; an empty or wholly invalid retention restores the defaults. Changes no decision.
  */
 export declare function setRetention(p: Person, retention: Retention): void;
+/**
+ * The nafs lens (2.4.0, read-only; see `promptings/` SCOPE): the three Qur'anic descriptions of one self (12:53,
+ * 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

@@ -26,7 +26,7 @@ import { advanceBody, BODY_DEFAULTS, checkDowned, clearDowned, consume, createBo
 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 { createConscience, heldNorms, normVeto, recordDeed, recordRepair, repent, } from './conscience/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 { ambientBodyParams, ambientModifiers, ambientMood, ambientNeeds } from './environment/index.js';
 import { aptitudeOf, createFamily, pregnancyModifiers } from './family/index.js';
@@ -36,7 +36,8 @@ import { advanceMemory, createMemory, enableGists, foldGists, learnOutcome, reca
 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 { consumeConsequences, pruneConsequences, receiveConsequences } from './prospection/index.js';
+import { enablePromptings, nafsPatterns, notePromptings } from './promptings/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';
@@ -153,6 +154,8 @@ export function createPerson(spec) {
         enableCharacterChange(p);
     if (on?.skillRetention)
         enableSkillRetention(p);
+    if (on?.promptings)
+        enablePromptings(p, on.promptings);
     return p;
 }
 /**
@@ -817,7 +820,7 @@ export function decide(p, affordances, opts = {}) {
     const review = p.activity !== null;
     if (review)
         ctx.quiet = true;
-    const { record, needDeltas, command: co } = cognitionDecide(p, list, ctx);
+    const { record, needDeltas, command: co, prompts } = cognitionDecide(p, list, ctx);
     if (review)
         record.review = true;
     const interruptReason = opts.interrupt ?? p.activity?.interrupt?.reason;
@@ -831,6 +834,12 @@ export function decide(p, affordances, opts = {}) {
     record.narration = narrateDecision(p, record);
     const resolutions = resolutionsOf(record);
     const continuing = review && (record.chosenAffordanceId === null || record.chosenAffordanceId === p.activity?.affordanceId);
+    // Promptings (opt-in): a review that keeps the running activity is not a new decision point for a prompt.
+    if (prompts && !continuing) {
+        const noted = notePromptings(p, prompts, record.chosenAffordanceId, p.now);
+        if (noted.guilt > 0)
+            feel(p, 'guilt', noted.guilt, 'prompting', p.now);
+    }
     for (const res of resolutions) {
         res.says = voiceLine(p, res, record.id);
         if (res.verdict === 'complied' && !continuing) {
@@ -1390,3 +1399,22 @@ export function setRetention(p, retention) {
         p.trace.splice(0, p.trace.length - keep);
     trimChronicle(p);
 }
+/**
+ * The nafs lens (2.4.0, read-only; see `promptings/` SCOPE): the three Qur'anic descriptions of one self (12:53,
+ * 75:2, 89:27), each with the matching evidence in existing state. Descriptions, never a level or a rank.
+ */
+export function nafsReading(p) {
+    let guilt = 0;
+    for (const e of p.affect.emotions)
+        if (e.id === 'guilt' && e.cause !== 'prompting')
+            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));
+    return { spans, line: forecastLine(spans) };
+}

package/dist/promptings/index.d.ts

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

package/dist/promptings/index.js

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

package/dist/promptings/promptings.d.ts

@@ -0,0 +1,100 @@
+import type { Minute, Person, PromptingReading, PromptingRecord, PromptingResponse, PromptingResponseKind, PromptingsSpec, PromptingsState, Term, Unit } from '../types.ts';
+export declare const PROMPTINGS_DEFAULTS: {
+    /** Pull (utility units) from which a pull against a held norm or goal is noticed. */
+    readonly noticeAt: 0.15;
+    /** Largest turning-away term at full practice (utility units). */
+    readonly turnMax: 0.8;
+    /** No turning-away term at or above this desperation (same scale as will's survival desperation). */
+    readonly survivalDesperation: 0.75;
+    /** Practice gained at a prompt where the response held (× (1 - practice)). */
+    readonly gainTurned: 0.12;
+    /** Practice gained at a prompt where the response was tried but the person assented. */
+    readonly gainAttempt: 0.04;
+    /** Practice halves over this many days without use. */
+    readonly practiceHalfLifeDays: 60;
+    /** Guilt intensity at a prompt under the `fault` reading. */
+    readonly faultGuilt: 0.15;
+    /** Recurrence pull at echo level 1 (utility units); only reached when a host sets `echoRate` > 0. */
+    readonly echoScale: 0.5;
+    readonly echoHalfLifeDays: 3;
+    readonly maxRecent: 64;
+    readonly maxResponses: 8;
+    readonly maxEcho: 32;
+};
+/**
+ * Turn the slice on, or reconfigure it: recent records and echo are kept, and a response whose id is already held
+ * keeps its practice and last use (the spec's `practice` only seeds new responses). Returns the state.
+ */
+export declare function enablePromptings(p: Person, spec?: PromptingsSpec): PromptingsState;
+/** Practice of a response at `now`, after disuse decay. Pure. */
+export declare function practiceAt(r: PromptingResponse, now: Minute): Unit;
+/** Whether an option's terms carry a noticed prompt: its strongest pull and the opposing term. Pure. */
+export declare function promptIn(terms: readonly Term[], tags: readonly string[] | undefined): {
+    source: string;
+    opposedBy: string;
+} | undefined;
+/**
+ * Extra terms for one option (cognition calls this before summing): the echo pull under `fault`, then the
+ * turning-away term when the option carries a prompt. Pure apart from reads; empty without the slice.
+ */
+export declare function promptingTerms(p: Person, action: string, terms: readonly Term[], tags: readonly string[] | undefined, now: Minute, desperation: number): Term[];
+/** A prompt found at a decision point, handed from cognition to the composite. */
+export interface PromptingSeen {
+    affordanceId: string;
+    action: string;
+    source: string;
+    opposedBy: string;
+    /** Whether a turning-away term was applied. */
+    turnApplied: boolean;
+}
+/** What `notePromptings` did, for the composite (the `fault` guilt goes through affect). */
+export interface PromptingsNoted {
+    records: PromptingRecord[];
+    /** Guilt intensity to feel at the prompt (only under `fault`); 0 otherwise. */
+    guilt: Unit;
+}
+/**
+ * Record the prompts of one decision point and learn from them. `chosenId` is the chosen affordance (null when
+ * nothing was chosen). The only writer of `p.promptings` after `enablePromptings`.
+ */
+export declare function notePromptings(p: Person, seen: readonly PromptingSeen[], chosenId: string | null, now: Minute): PromptingsNoted;
+/** Vocabulary for one prompt under a held reading (narration only; it changes nothing). */
+export declare function promptingLine(reading: PromptingReading, outcome: PromptingRecord['outcome'], kind?: PromptingResponseKind): string;
+/** Read-only summary of recent prompts (a lens; computes nothing new about the person). */
+export interface PromptingsReadingView {
+    reading: PromptingReading;
+    readingSource?: string;
+    prompts: number;
+    turned: number;
+    passed: number;
+    assented: number;
+    responses: {
+        id: string;
+        kind: PromptingResponseKind;
+        practice: Unit;
+    }[];
+    /** Vocabulary for the last few prompts, newest last. */
+    lines: string[];
+}
+export declare function promptingsReading(p: Person, now?: Minute): PromptingsReadingView | undefined;
+/**
+ * The nafs lens (reconciliation.md §3): the three Qur'anic descriptions of one self, each with the evidence in
+ * existing state that matches it. Descriptions, not a level, a ladder or three agents; several can hold at once,
+ * and none says anything about rank before God. Inputs are passed in by the composite (open-breach weight and
+ * felt guilt from conscience and affect), so this module reads nothing it does not own. Guilt that the `fault` reading
+ * feels at a prompt is excluded, so the scrupulous reading is not mapped onto self-reproach (75:2). These mappings
+ * from state to description are engineering conventions (C), not interpretations of the verses.
+ */
+export interface NafsPattern {
+    name: 'urging' | 'reproaching' | 'at rest';
+    /** Qur'anic description it borrows (12:53 ammara, 75:2 lawwama, 89:27 mutmaʾinna). */
+    ref: string;
+    evident: boolean;
+    evidence: string;
+}
+export declare function nafsPatterns(p: Person, inputs: {
+    guiltLoad: Unit;
+    guilt: Unit;
+}): NafsPattern[];
+/** Validate a saved slice; a malformed slice is dropped (undefined), malformed entries are skipped. */
+export declare function sanitizePromptings(input: unknown, now: Minute): PromptingsState | undefined;

package/dist/promptings/promptings.js

@@ -0,0 +1,348 @@
+/**
+ * SCOPE (promptings and turning away, 2.4.0): a *prompt* is a pull toward an option that the person's own held
+ * norms or goals oppose, strong enough to be noticed. This module records prompts, lets the person turn from them
+ * by a practised response, and keeps a prompt apart from assent: only an assented act reaches `conscience/
+ * recordDeed`, so a prompt is never a breach (Bukhari 5269, research/reconciliation.md §3). It is opt-in
+ * (`enablePromptings`, or `PersonSpec.enable.promptings`); without it nothing here runs and existing runs replay
+ * byte for byte. It draws no randomness.
+ *
+ * Detection reads an option's traced terms and changes none of them: the pull is the sum of positive `habit`,
+ * `emotion:*`, `need:*` and `promptings:echo` terms (every positive term on an offer tagged `temptation`); it is a
+ * prompt when the pull reaches `noticeAt` while a `norm:*` or `goal:*` term on the same option is negative.
+ * Abstention windows are not detected (they veto, and carry no term). A person with a response gets one extra
+ * term, `promptings:turn` = -turnMax × practice, on that option; it is bounded and absent at survival desperation,
+ * so a desperate bodily need still wins (2:286). Each prompt is recorded once per decision point (a review that
+ * keeps the running activity records nothing) as `assented` (chosen), `turned` (not chosen, a response practised)
+ * or `passed` (not chosen, no response). Practice grows with diminishing gains once per decision point where the
+ * response was used (more when it held; a vetoed option earns none, since the will blocked it), and halves over `practiceHalfLifeDays` of disuse.
+ *
+ * Held readings (reconciliation.md §5): `whisper`, `inclination`, `intrusion` and `none` give identical decisions
+ * and differ only in the vocabulary of `promptingLine`. `fault` (the scrupulous reading, which both the tradition
+ * and clinicians reject) adds a small guilt emotion at the prompt itself, from the person's own understanding;
+ * that guilt is an emotion, never a breach, so it changes decisions only where an offer acts through guilt's
+ * tendencies. With a host-set `echoRate` > 0, `fault` also gains a recurrence pull on that action
+ * (`promptings:echo`), decaying over days: a labelled assumption from contested suppression-rebound evidence
+ * (P3), off by default. No reading earns a hidden bonus.
+ *
+ * Borrowed shapes: everyday desire, conflict and resistance (P1, P2); suppression rebound and redirection (P3,
+ * P13); practised if–then responses (P5). Every number is an engineering default, not fitted. Does not claim: the
+ * source of any thought, a measure of faith, spiritual rank, reward for resisting (H4 is acknowledged as a held
+ * belief and never computed), clinical OCD, or a cessation rate. The lenses (`promptingsReading`, `nafsReading`)
+ * only describe existing state; they store and compute nothing new about the person.
+ */
+import { clamp01, dexp, isObj, round } from '../core/index.js';
+import { MINUTES_PER_DAY } from '../types.js';
+export const PROMPTINGS_DEFAULTS = {
+    /** Pull (utility units) from which a pull against a held norm or goal is noticed. */
+    noticeAt: 0.15,
+    /** Largest turning-away term at full practice (utility units). */
+    turnMax: 0.8,
+    /** No turning-away term at or above this desperation (same scale as will's survival desperation). */
+    survivalDesperation: 0.75,
+    /** Practice gained at a prompt where the response held (× (1 - practice)). */
+    gainTurned: 0.12,
+    /** Practice gained at a prompt where the response was tried but the person assented. */
+    gainAttempt: 0.04,
+    /** Practice halves over this many days without use. */
+    practiceHalfLifeDays: 60,
+    /** Guilt intensity at a prompt under the `fault` reading. */
+    faultGuilt: 0.15,
+    /** Recurrence pull at echo level 1 (utility units); only reached when a host sets `echoRate` > 0. */
+    echoScale: 0.5,
+    echoHalfLifeDays: 3,
+    maxRecent: 64,
+    maxResponses: 8,
+    maxEcho: 32,
+};
+const READINGS = ['whisper', 'inclination', 'intrusion', 'fault', 'none'];
+const KINDS = ['refuge', 'redirect', 'leave'];
+const halve = (value, minutes, halfLifeDays) => minutes <= 0 ? value : value * dexp((-Math.LN2 * minutes) / (halfLifeDays * MINUTES_PER_DAY));
+/**
+ * Turn the slice on, or reconfigure it: recent records and echo are kept, and a response whose id is already held
+ * keeps its practice and last use (the spec's `practice` only seeds new responses). Returns the state.
+ */
+export function enablePromptings(p, spec = {}) {
+    const prev = p.promptings;
+    const responses = [];
+    for (const r of spec.responses ?? []) {
+        if (!isObj(r) || typeof r.id !== 'string' || r.id === '' || !KINDS.includes(r.kind))
+            continue;
+        if (responses.some((x) => x.id === r.id) || responses.length >= PROMPTINGS_DEFAULTS.maxResponses)
+            continue;
+        const held = prev?.responses.find((x) => x.id === r.id);
+        const seed = Number.isFinite(r.practice) ? clamp01(r.practice) : 0.1;
+        responses.push(held ? { ...held, kind: r.kind } : { id: r.id, kind: r.kind, practice: seed, lastUsedAt: p.now });
+    }
+    const state = {
+        reading: spec.reading && READINGS.includes(spec.reading) ? spec.reading : 'none',
+        responses,
+        recent: prev?.recent ?? [],
+        echo: prev?.echo ?? {},
+        echoRate: Number.isFinite(spec.echoRate) ? clamp01(spec.echoRate) : 0,
+    };
+    if (spec.readingSource !== undefined)
+        state.readingSource = spec.readingSource;
+    p.promptings = state;
+    return state;
+}
+/** Practice of a response at `now`, after disuse decay. Pure. */
+export function practiceAt(r, now) {
+    return clamp01(halve(r.practice, now - r.lastUsedAt, PROMPTINGS_DEFAULTS.practiceHalfLifeDays));
+}
+/** The response a person would use now: highest practice, ties by id. */
+function bestResponse(s, now) {
+    let best;
+    for (const r of s.responses) {
+        const practice = practiceAt(r, now);
+        if (!best || practice > best.practice || (practice === best.practice && r.id < best.r.id))
+            best = { r, practice };
+    }
+    return best;
+}
+const isPull = (source, tagged) => tagged ||
+    source === 'habit' ||
+    source === 'promptings:echo' ||
+    source.startsWith('emotion:') ||
+    source.startsWith('need:');
+/** Whether an option's terms carry a noticed prompt: its strongest pull and the opposing term. Pure. */
+export function promptIn(terms, tags) {
+    const tagged = tags?.includes('temptation') ?? false;
+    let pull = 0;
+    let top;
+    let opposed;
+    for (const t of terms) {
+        if (t.source === 'promptings:turn')
+            continue;
+        if (t.value > 0 && isPull(t.source, tagged)) {
+            pull += t.value;
+            if (!top || t.value > top.value)
+                top = t;
+        }
+        else if (t.value < 0 &&
+            (t.source.startsWith('norm:') || t.source.startsWith('goal:')) &&
+            (!opposed || t.value < opposed.value))
+            opposed = t;
+    }
+    if (!top || !opposed || pull < PROMPTINGS_DEFAULTS.noticeAt)
+        return undefined;
+    return { source: tagged && !isPull(top.source, false) ? 'host' : top.source, opposedBy: opposed.source };
+}
+/**
+ * Extra terms for one option (cognition calls this before summing): the echo pull under `fault`, then the
+ * turning-away term when the option carries a prompt. Pure apart from reads; empty without the slice.
+ */
+export function promptingTerms(p, action, terms, tags, now, desperation) {
+    const s = p.promptings;
+    if (!s)
+        return [];
+    const out = [];
+    const e = Object.hasOwn(s.echo, action) ? s.echo[action] : undefined;
+    if (e && s.reading === 'fault') {
+        const level = halve(e.level, now - e.at, PROMPTINGS_DEFAULTS.echoHalfLifeDays);
+        const v = round(PROMPTINGS_DEFAULTS.echoScale * level);
+        if (v > 0)
+            out.push({ source: 'promptings:echo', value: v });
+    }
+    if (desperation >= PROMPTINGS_DEFAULTS.survivalDesperation)
+        return out;
+    const best = bestResponse(s, now);
+    if (!best || best.practice <= 0)
+        return out;
+    if (!promptIn([...terms, ...out], tags))
+        return out;
+    const v = round(-PROMPTINGS_DEFAULTS.turnMax * best.practice);
+    if (v < 0)
+        out.push({ source: 'promptings:turn', value: v });
+    return out;
+}
+/**
+ * Record the prompts of one decision point and learn from them. `chosenId` is the chosen affordance (null when
+ * nothing was chosen). The only writer of `p.promptings` after `enablePromptings`.
+ */
+export function notePromptings(p, seen, chosenId, now) {
+    const s = p.promptings;
+    const noted = { records: [], guilt: 0 };
+    if (!s || seen.length === 0)
+        return noted;
+    const D = PROMPTINGS_DEFAULTS;
+    const best = bestResponse(s, now);
+    // One practice gain per decision point, however many options carried a prompt: the larger one if any held.
+    let gain = 0;
+    for (const x of seen) {
+        const assented = x.affordanceId === chosenId;
+        const used = x.turnApplied && best !== undefined;
+        const rec = {
+            at: now,
+            action: x.action,
+            affordanceId: x.affordanceId,
+            source: x.source,
+            opposedBy: x.opposedBy,
+            outcome: assented ? 'assented' : used ? 'turned' : 'passed',
+        };
+        if (used && best) {
+            rec.responseId = best.r.id;
+            gain = Math.max(gain, assented ? D.gainAttempt : D.gainTurned);
+        }
+        s.recent.push(rec);
+        noted.records.push(rec);
+        if (s.reading === 'fault') {
+            noted.guilt = Math.max(noted.guilt, D.faultGuilt);
+            if (s.echoRate > 0) {
+                const prev = Object.hasOwn(s.echo, x.action) ? s.echo[x.action] : undefined;
+                const level = prev ? halve(prev.level, now - prev.at, D.echoHalfLifeDays) : 0;
+                s.echo[x.action] = { level: round(clamp01(level + s.echoRate * (1 - level))), at: now };
+            }
+        }
+    }
+    if (best && gain > 0) {
+        const practice = practiceAt(best.r, now);
+        best.r.practice = round(clamp01(practice + gain * (1 - practice)));
+        best.r.lastUsedAt = now;
+    }
+    if (s.recent.length > D.maxRecent)
+        s.recent.splice(0, s.recent.length - D.maxRecent);
+    const keys = Object.keys(s.echo);
+    if (keys.length > D.maxEcho) {
+        keys.sort((a, b) => (s.echo[a]?.at ?? 0) - (s.echo[b]?.at ?? 0) || (a < b ? -1 : 1));
+        for (const k of keys.slice(0, keys.length - D.maxEcho))
+            delete s.echo[k];
+    }
+    return noted;
+}
+/** Vocabulary for one prompt under a held reading (narration only; it changes nothing). */
+export function promptingLine(reading, outcome, kind) {
+    if (outcome === 'assented')
+        return reading === 'whisper'
+            ? 'a whisper came and was followed'
+            : reading === 'inclination'
+                ? 'the pull of the self won'
+                : 'an urge came and was acted on';
+    const how = outcome === 'turned'
+        ? kind === 'refuge'
+            ? 'sought refuge and '
+            : kind === 'redirect'
+                ? 'turned to something else and '
+                : ''
+        : '';
+    switch (reading) {
+        case 'whisper':
+            return `a whisper came; ${how}let it pass`;
+        case 'inclination':
+            return `the self pulled; ${how}held back`;
+        case 'intrusion':
+            return `a thought came, not who I am; ${how}let it go`;
+        case 'fault':
+            return `a thought came and felt like wrongdoing; ${how}let it pass`;
+        default:
+            return `an urge came; ${how}it passed`;
+    }
+}
+export function promptingsReading(p, now = p.now) {
+    const s = p.promptings;
+    if (!s)
+        return undefined;
+    const count = (o) => s.recent.filter((r) => r.outcome === o).length;
+    const kindOf = (id) => s.responses.find((r) => r.id === id)?.kind;
+    const view = {
+        reading: s.reading,
+        prompts: s.recent.length,
+        turned: count('turned'),
+        passed: count('passed'),
+        assented: count('assented'),
+        responses: s.responses.map((r) => ({ id: r.id, kind: r.kind, practice: round(practiceAt(r, now)) })),
+        lines: s.recent.slice(-5).map((r) => promptingLine(s.reading, r.outcome, kindOf(r.responseId))),
+    };
+    if (s.readingSource !== undefined)
+        view.readingSource = s.readingSource;
+    return view;
+}
+export function nafsPatterns(p, inputs) {
+    const recent = p.promptings?.recent ?? [];
+    const assentedAgainstNorm = recent.filter((r) => r.outcome === 'assented' && r.opposedBy.startsWith('norm:'));
+    const letPass = recent.filter((r) => r.outcome !== 'assented').length;
+    const reproach = inputs.guiltLoad > 0 || inputs.guilt > 0.05;
+    return [
+        {
+            name: 'urging',
+            ref: 'Qur’an 12:53',
+            evident: assentedAgainstNorm.length > 0,
+            evidence: `${assentedAgainstNorm.length} recent prompts followed against a held norm`,
+        },
+        {
+            name: 'reproaching',
+            ref: 'Qur’an 75:2',
+            evident: reproach,
+            evidence: `open-breach weight ${round(inputs.guiltLoad, 2)}, felt guilt ${round(inputs.guilt, 2)}`,
+        },
+        {
+            name: 'at rest',
+            ref: 'Qur’an 89:27',
+            evident: letPass > 0 && assentedAgainstNorm.length === 0 && !reproach,
+            evidence: `${letPass} recent prompts let pass, none followed against a norm, no felt reproach`,
+        },
+    ];
+}
+const unit = (x) => typeof x === 'number' && Number.isFinite(x) && x >= 0 && x <= 1;
+const minute = (x) => typeof x === 'number' && Number.isFinite(x);
+const str = (x) => typeof x === 'string' && x !== '' && x.length <= 200;
+/** Validate a saved slice; a malformed slice is dropped (undefined), malformed entries are skipped. */
+export function sanitizePromptings(input, now) {
+    if (!isObj(input) || !Array.isArray(input.responses) || !Array.isArray(input.recent) || !isObj(input.echo))
+        return undefined;
+    if (typeof input.reading !== 'string' || !READINGS.includes(input.reading))
+        return undefined;
+    const D = PROMPTINGS_DEFAULTS;
+    const responses = [];
+    for (const r of input.responses.slice(0, D.maxResponses)) {
+        if (!isObj(r) || !str(r.id) || !KINDS.includes(r.kind) || !unit(r.practice))
+            continue;
+        if (!minute(r.lastUsedAt) || r.lastUsedAt > now || responses.some((x) => x.id === r.id))
+            continue;
+        responses.push({
+            id: r.id,
+            kind: r.kind,
+            practice: r.practice,
+            lastUsedAt: r.lastUsedAt,
+        });
+    }
+    const recent = [];
+    for (const r of input.recent.slice(-D.maxRecent)) {
+        if (!isObj(r) || !minute(r.at) || r.at > now || !str(r.action) || !str(r.affordanceId))
+            continue;
+        if (!str(r.source) || !str(r.opposedBy))
+            continue;
+        if (r.outcome !== 'passed' && r.outcome !== 'turned' && r.outcome !== 'assented')
+            continue;
+        const rec = {
+            at: r.at,
+            action: r.action,
+            affordanceId: r.affordanceId,
+            source: r.source,
+            opposedBy: r.opposedBy,
+            outcome: r.outcome,
+        };
+        if (str(r.responseId))
+            rec.responseId = r.responseId;
+        recent.push(rec);
+    }
+    const echo = {};
+    for (const k of Object.keys(input.echo).slice(0, D.maxEcho)) {
+        if (k === '__proto__' || !str(k))
+            continue;
+        const e = input.echo[k];
+        if (!isObj(e) || !unit(e.level) || !minute(e.at) || e.at > now)
+            continue;
+        echo[k] = { level: e.level, at: e.at };
+    }
+    const rate = input.echoRate;
+    const out = {
+        reading: input.reading,
+        responses,
+        recent,
+        echo,
+        echoRate: typeof rate === 'number' && Number.isFinite(rate) && rate >= 0 ? Math.min(1, rate) : 0,
+    };
+    if (str(input.readingSource))
+        out.readingSource = input.readingSource;
+    return out;
+}

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: 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
+ * 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 { 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): 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): 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: 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
+ * 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 { 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) {
+    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);
+}
+/**
+ * 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) {
+    const spans = bodyForecastFor(p, aff, mods).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/restore.js

@@ -20,6 +20,7 @@ import { sanitizeMethods } from './methods/index.js';
 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 { sanitizeSkillRetention } from './skills/index.js';
 import { sanitizeGroups, sanitizeImpressions } from './social/index.js';
@@ -61,6 +62,7 @@ const OPTIONAL_KEYS = new Set([
     'retention',
     'methods',
     'prospection',
+    'promptings',
 ]);
 /** 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);
@@ -174,6 +176,7 @@ export function restore(input) {
     keepValid(out, 'retention', cleanRetention);
     keepValid(out, 'methods', sanitizeMethods);
     keepValid(out, 'prospection', (x) => sanitizeProspection(x, out.now, out.id));
+    keepValid(out, 'promptings', (x) => sanitizePromptings(x, out.now));
     boundLists(out);
     return out;
 }

package/dist/types.d.ts

@@ -827,7 +827,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.3.0";
+export declare const ENGINE_VERSION = "2.5.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -992,6 +992,8 @@ export interface Person {
     methods?: MethodsState;
     /** Received future consequences, absent until attended testimony supplies them. */
     prospection?: ProspectionState;
+    /** Noticed promptings and practised turnings-away (2.4.0, opt-in via `enablePromptings`). Owned by `promptings/`. */
+    promptings?: PromptingsState;
     /** Practice consolidation (1.8.0, opt-in via `enableSkillRetention`). Owned by `skills/`. */
     skillRetention?: {
         consolidationHours: number;
@@ -1090,6 +1092,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. */
@@ -1295,7 +1303,9 @@ export interface SuggestionResolution {
 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) */
+     *  'suggestion:player', 'social:p2', 'expectation', 'autonomy' (reactance to a pushing voice),
+     *  '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;
 }
@@ -1383,8 +1393,71 @@ export interface PersonSpec {
         yearbook?: boolean;
         character?: boolean;
         skillRetention?: 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
+ * reading) adds guilt at the prompt itself; `none` is neutral vocabulary. See research/reconciliation.md §5.
+ */
+export type PromptingReading = 'whisper' | 'inclination' | 'intrusion' | 'fault' | 'none';
+/** A practised turning-away: seeking refuge, redirecting attention, or simply leaving the thought. */
+export type PromptingResponseKind = 'refuge' | 'redirect' | 'leave';
+export interface PromptingResponse {
+    id: string;
+    kind: PromptingResponseKind;
+    /** Skill-like practice 0..1 as of `lastUsedAt`; it decays slowly with disuse. */
+    practice: Unit;
+    lastUsedAt: Minute;
+}
+export interface PromptingRecord {
+    at: Minute;
+    action: string;
+    affordanceId: string;
+    /** The strongest pull: 'habit', 'emotion:*', 'need:*', 'promptings:echo' or 'host' (a `temptation` tag). */
+    source: string;
+    /** The opposing term: 'norm:x' or 'goal:g'. */
+    opposedBy: string;
+    outcome: 'passed' | 'turned' | 'assented';
+    /** The response that was practised at this prompt, if any. */
+    responseId?: string;
+}
+export interface PromptingsState {
+    reading: PromptingReading;
+    /** Provenance of the reading (upbringing, a teacher, a book id), as for held norms. */
+    readingSource?: string;
+    responses: PromptingResponse[];
+    /** Recent prompts, oldest first, bounded (`PROMPTINGS_DEFAULTS.maxRecent`). */
+    recent: PromptingRecord[];
+    /** Recurrence per action under the `fault` reading (an off-by-default assumption; see `echoRate`). */
+    echo: Record<string, {
+        level: Unit;
+        at: Minute;
+    }>;
+    /** Echo gained per prompt under `fault`. Default 0: the recurrence term is a host-set assumption (P3 contested). */
+    echoRate: number;
+}
+/** What a host hands `enablePromptings`. */
+export interface PromptingsSpec {
+    reading?: PromptingReading;
+    readingSource?: string;
+    responses?: {
+        id: string;
+        kind: PromptingResponseKind;
+        practice?: Unit;
+    }[];
+    echoRate?: number;
+}
 /** What the body is doing over an interval. */
 export interface BodyLoad {
     effort: Unit;

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

package/package.json

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