@adam0white/human-framework 2.2.1 → 2.4.0

package/README.md

@@ -123,6 +123,48 @@ The framework has no world of its own. The host supplies three things and receiv
 - **Decisions** (`DecisionRecord`) come back: the chosen offer, the top `considered` options with every
   utility term, the suggestion verdict(s), a private `intention`, and a `narration`.
 
+### Expected benefits and observed outcomes
+
+An offer describes expected effects. An outcome reports what happened. The host resolves space,
+contact, inventory and payment; HF uses the reported outcome to update the person. Do not copy
+`Affordance.advertises` into `Outcome.needs` as a general completion rule.
+
+| Host situation | Offer | Completion report |
+|---|---|---|
+| A person sleeps for part of the planned night. | Advertise typical sleep/rest benefits and set `mode: 'sleep'`. | Leave `sleep` and `rest` absent from `Outcome.needs`. `finish` advances the body to the actual end time and measures their change since the activity began. Explicit values replace that measurement; copying the advertisement can overstate the realized recovery reported to learning. |
+| A task promises four coins but actually pays two. | Set expected `Affordance.material` to four host units. | Update the host ledger by two and report `Outcome.material: 2`. A completed task does not imply the promised payment arrived. Report zero for no payment and a negative value for an actual cost. HF does not maintain the host's money ledger. |
+| A person can talk with someone who is present. | Tag the offer `social` when it really involves social contact; put participants in `with`. | Resolve actual participation. An empty room, a sleeping neighbour or someone who arrives after the conversation ends is not a completed encounter. Do not award contact or belonging merely because the activity uses a shared place. |
+
+For in-person activities, the host must establish co-presence and overlapping participation. HF has
+no map and does not discover companions. `with` names people taking part, not everyone assigned to a
+place. A `social` tag is also a claim about the offered activity, not a request to find someone. If
+contact becomes impossible, interrupt or replan the activity instead of completing the declared
+encounter. Report only the need effects that the actual interaction supports.
+
+The current behavior is defined in [`Affordance` and `Outcome`](src/types.ts) and
+[`finish`](src/person.ts). Existing controls cover [body advancement and waking after sleep](test/person.test.ts),
+[body recovery](test/body.test.ts), [material valuation under scarcity](test/cognition-scarcity.test.ts),
+[actual material in day records](test/chronicle.test.ts), and [relationship-aware social terms](test/social.test.ts).
+These boundaries require correct host reports; they do not imply a framework behavior change.
+
+### Scheduled activity reviews
+
+A custom host must process `activity.reviewAt`, including during sleep. `tick` advances the person;
+it does not dispatch a decision or automatically end the host's job. An `activity.interrupt` is also
+a request to review, not an instruction to cancel every activity.
+
+At a due review, call `decide` with physically feasible alternatives. It includes the current activity
+with its remaining duration. If that activity is chosen again, call `reviewed(p)` and keep its original
+job, arrival time and reservations. If another activity wins, reconcile the old physical job, call
+`finish` with an interrupted outcome, then `begin` the chosen activity with its decision record.
+Do not restart a continued activity or refund its resources. Hard capacity vetoes still apply.
+
+Sleep reviews can move earlier for ordinary pending appointments. The appointment's time pressure
+can permit waking; an obligatory norm is not required. A host that ignores the scheduled review can
+make someone miss an obligation HF was ready to reconsider. This does not imply advance planning
+for unavailable future actions. See [`reviewed` and the decision lifecycle](src/person.ts) and
+[`wakeReviewAt` and commitment-based waking](src/will/will.ts).
+
 You can drive a person by hand: `decide(p, offers, { suggestion })` → `begin(p, offer, record)` →
 `tick(p, now)` → `finish(p, outcome)`, with `perceive(p, percepts)` and `interrupt(p, now, reason)` between.
 Or implement `World` and let `stepCommunity` sequence everyone in deterministic (time, id) order:
@@ -302,3 +344,60 @@ clearMethodContext(learner); // when leaving or switching the task
 ```
 
 Import these functions from the package. Rules/evidence live in optional `Person.methods` and survive snapshots. Current cues expire after 120 minutes. A stable demonstration id avoids counting the same example twice within the retained 256-example history, even after its rule or evidence is evicted. Once an id has left both that history and retained rule evidence, it can be admitted again. Missing observations cannot satisfy a condition. Failed demonstrations reduce support for that action. Successful alternatives retain their own support; ordinary cognition weighs the supported offers alongside other motives. A successful lecture does not certify reliable execution. [The routing control](examples/method-control.ts) demonstrates changed teaching, withheld teaching, a scalar-skill control and acquired-state ablation with two methods and an exception. [The alternatives control](examples/method-alternatives-control.ts) demonstrates two independently successful procedures under the same observations, failed practice, hunger and exact restore.
+
+
+## Receiving a possible future route
+
+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 {
+  type Affordance, type ReceivedConsequence,
+  consequenceEvidence, createPerson, decide, perceive,
+} from '@adam0white/human-framework';
+
+const person = createPerson({
+  id: 'courier', name: 'Courier', seed: 19, now: 600,
+  bornAt: -30 * 365 * 1440, sex: 'female',
+  goals: [{
+    id: 'delivery', label: 'Deliver the parcel', serves: ['achievement'],
+    advancedBy: [{ action: 'deliver', amount: 1 }], importance: 0.8,
+    temporal: { halfLifeMinutes: 30 },
+  }],
+});
+const route: ReceivedConsequence = {
+  id: 'access-window', revision: 0,
+  trigger: { action: 'ask-access', targetId: 'keeper' },
+  successor: { action: 'deliver', duration: 20, effort: 0.1 },
+  availableFrom: 620, availableUntil: 680, expiresAt: 800,
+  chance: 0.8, confidence: 0.9,
+};
+perceive(person, [{
+  at: 600, channel: 'told', kind: 'explanation', actorId: 'keeper',
+  targetId: person.id, salience: 1,
+  summary: 'If your request succeeds, this route may become available.',
+  consequences: [route],
+}]);
+const request: Affordance = {
+  id: 'ask', action: 'ask-access', label: 'Request access', targetId: 'keeper',
+  duration: 10, effort: 0.1, advertises: {},
+};
+const offers: Affordance[] = [request,
+  { id: 'direct', action: 'deliver', label: 'Deliver directly',
+    duration: 180, effort: 0.1, advertises: {} },
+];
+const decision = decide(person, offers);
+const evidence = consequenceEvidence(person, request); // pure; no RNG consumed
+```
+
+`consequences` and `withdrawConsequences: [{ id, revision }]` are accepted only on attended `told` percepts whose explicit `actorId` names someone else. `Percept.targetId` may identify this person or be omitted for a broadcast; testimony explicitly addressed to another recipient is rejected. A recipient-specific opportunity must be addressed to that recipient. Trigger action, target and place match exactly; an omitted target/place matches only an omitted value. `availableUntil` is the latest successor **completion**, inclusive. The whole successor must fit after the current action and `availableFrom`.
+
+`Goal.temporal.halfLifeMinutes` must be finite and positive. It enables expected completion valuation for direct actions **as well as** received successors: existing goal value × estimated action success × time discount. Existing `deadline` remains urgency, never a hard cutoff. Keep the same temporal goal in knowledge-intact, withheld and removed-knowledge controls; compare temporal-off separately. Legacy goals retain their prior formula. A received successor serves only goals listing its action in `Goal.advancedBy`; it does not inherit an `Affordance.advances` hint from a current offer.
+
+The received access estimate is current-action success × `chance` × `confidence` × current source trust. `chance` means access conditional on successful asking; it does not establish consent. One coherent route may contribute to goals. Expected successor effort and material costs use the same readers as direct actions, are charged once, and remain undiscounted and unscaled by maturity. A favorable explanation need not win against other motives.
+
+Only actual terminal outcomes advance terminal goals. Finishing one's own request consumes matching received opportunities even if a refusal has not been heard. It grants no access and executes no successor. The host still decides physical availability, reports the other person's actual response, and filters repeated or impossible requests. Do not mark asking as `advances` merely to make the route attractive.
+
+Knowledge lives in optional `Person.prospection` and survives snapshot/restore. A percept admits at most four additions/withdrawals combined, atomically. Invalid entries or duplicate source/id identities reject the entire batch. Equal/lower revisions do not reinforce or refresh; a higher revision replaces. There are at most 16 entries and 64 revision records. Consumed entries are evicted first, then the oldest remaining entries, while their revision records remain; a batch requiring more still-valid revision records is rejected. Entries and revision memory expire within seven days. Deduplication is bounded, not a durable audit. Capacity is shared across sources and admission does not allocate by trust. One prolific source can occupy the finite entry/revision capacity, causing other new ids to be rejected until revision space expires; this is bounded memory, not a source-fairness or trust firewall. Hosts must bound the premises they deliver. The pure query exposes retained entries, present feasibility and retained revisions.
+
+[The frozen control](examples/received-consequences.ts) publishes useful, late, costly, uncertain, withheld, removed-knowledge, removed-goal, temporal-off and refused arms in two renamed domains. This faculty does not search action graphs, predict future body state, price all waiting opportunities or guarantee consent or success. Its numerical bounds and control parameters are engineering assumptions.

package/dist/agenda/agenda.js

@@ -48,6 +48,7 @@
 // The bundled catalog is only the default; a host with its own catalog passes it (`World.catalog`).
 import { DEFAULT_NORMS } from '../conscience/catalog.js';
 import { clamp01, dayOf, dpow, hasNumbers, isObj } from '../core/index.js';
+import { expectedEffect } from '../memory/index.js';
 import { MINUTES_PER_DAY } from '../types.js';
 export const AGENDA_DEFAULTS = {
     /** Minutes before a window opens during which a commitment already pulls (to get there). */
@@ -141,8 +142,23 @@ function copyArrays(c) {
  * Spec commitments keep a given id; entries without one get a free `c<n>` id after all given ids are placed, so
  * `prayerWindows()` output can be passed straight into `PersonSpec.commitments`.
  */
+/** Copy valid temporal settings and drop invalid ones at every agenda entry point. */
+function sanitizeGoalTemporal(g) {
+    const t = g.temporal;
+    if (t !== undefined &&
+        !(isObj(t) &&
+            typeof t.halfLifeMinutes === 'number' &&
+            Number.isFinite(t.halfLifeMinutes) &&
+            t.halfLifeMinutes > 0))
+        delete g.temporal;
+    else if (g.temporal)
+        g.temporal = { halfLifeMinutes: g.temporal.halfLifeMinutes };
+}
 /** Restore-time check of `agenda.lapse` (1.7.0), in place: a malformed one is dropped (absent means none). @internal */
 export function sanitizeAgenda(a) {
+    for (const g of a.goals)
+        if (isObj(g))
+            sanitizeGoalTemporal(g);
     const lapse = a.lapse;
     if (lapse !== undefined && !(isObj(lapse) && hasNumbers(lapse, 'since', 'missed')))
         delete a.lapse;
@@ -177,6 +193,7 @@ export function createAgenda(spec, now) {
             lastAdvancedAt: now,
         });
     }
+    sanitizeAgenda(state);
     return state;
 }
 export function promise(p, c) {
@@ -471,7 +488,27 @@ function deadlinePressure(g, now) {
     const span = Math.max(1, g.deadline - g.adoptedAt);
     return 1 + AGENDA_DEFAULTS.goalDeadlineBoost * clamp01((now - g.adoptedAt) / span);
 }
+/** Shared existing amount and urgency reader; no future knowledge is consulted here. @internal */
+export function goalValue(g, aff, now) {
+    const amount = goalAmount(g, aff);
+    return amount > 0
+        ? g.importance * clamp01(amount * AGENDA_DEFAULTS.goalAmountGain) * deadlinePressure(g, now)
+        : 0;
+}
+/** Opt-in completion-time and success estimate, shared by direct and received routes. @internal */
+export function temporalGoalValue(p, g, aff, now, completion) {
+    const base = goalValue(g, aff, now);
+    return g.temporal
+        ? base *
+            expectedEffect(p, aff).successRate *
+            dpow(0.5, Math.max(0, completion - now) / g.temporal.halfLifeMinutes)
+        : base;
+}
 export function agendaTerms(p, aff, now) {
+    return agendaTermsWithGoalEstimates(p, aff, now);
+}
+/** Internal route integration; hosts cannot provide goal overrides through the public API. @internal */
+export function agendaTermsWithGoalEstimates(p, aff, now, goalOverrides) {
     const d = AGENDA_DEFAULTS;
     const terms = [];
     for (const c of p.agenda.commitments) {
@@ -506,6 +543,13 @@ export function agendaTerms(p, aff, now) {
     for (const g of p.agenda.goals) {
         if (g.status !== 'active')
             continue;
+        const override = goalOverrides?.get(g.id);
+        if (override !== undefined || g.temporal) {
+            const value = override ?? temporalGoalValue(p, g, aff, now, now + Math.max(0, aff.duration));
+            if (value > 0)
+                terms.push({ source: `goal:${g.id}`, value });
+            continue;
+        }
         const amount = goalAmount(g, aff);
         if (amount <= 0)
             continue;
@@ -632,6 +676,7 @@ export function adoptGoal(p, g, now) {
         adoptedAt: now,
         lastAdvancedAt: now,
     };
+    sanitizeGoalTemporal(goal);
     p.agenda.goals.push(goal);
     return goal;
 }

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

@@ -25,7 +25,7 @@
  * `safety` need: `security` is a value, not a need, and no need is added.
  */
 import { emotionLevel, inBreak } from '../affect/index.js';
-import { agendaTerms } from '../agenda/index.js';
+import { agendaTermsWithGoalEstimates } from '../agenda/index.js';
 import { trustOf } from '../beliefs/index.js';
 import { normTerms } from '../conscience/index.js';
 import { clamp01, cmpStr, dexp, minuteOfDay, round } from '../core/index.js';
@@ -34,6 +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 { promptIn, promptingTerms } from '../promptings/index.js';
+import { 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';
@@ -200,6 +202,29 @@ export function socialContext(ctx) {
         satiation: K.socialSatiationFloor + (1 - K.socialSatiationFloor) * (1 - clamp01(belongingLevel)),
     };
 }
+/** Same perceived-body effort estimate for actual offers and received successors. @internal */
+export function effortValue(p, aff, ctx) {
+    const K = COGNITION_DEFAULTS;
+    const per = ctx.body.perceived;
+    const effort = clamp01(aff.effort);
+    const focus = clamp01(aff.focus ?? 0);
+    // A cued habit eases initiation and attention (N4: the depleted fall back on habits), not physical exertion.
+    const ease = p.habits.length === 0
+        ? 1
+        : habitEase(p, aff, { ...ctx.habit, placeId: aff.placeId ?? ctx.habit.placeId });
+    const effortCost = (effort * K.effortBase + focus * per.sleepiness) * ease +
+        effort * per.fatigue * (1 - clamp01(p.body.fitness));
+    return -K.effortScale * effortCost;
+}
+/** Same material valuation for actual offers and received successor costs. @internal */
+export function materialValue(p, material, scarcity) {
+    const K = COGNITION_DEFAULTS;
+    const v = p.values;
+    const weight = (v.security + v.achievement + v.power) / 3;
+    const scale = K.materialScale * (1 - K.scarcityScaleShrink * scarcity);
+    const sat = Math.sign(material) * (1 - dexp(-Math.abs(material) / scale));
+    return K.materialWeight * sat * 2 * weight * (1 + K.scarcityMaterialGain * scarcity);
+}
 /** Score one option. Pure apart from reads; terms are rounded for stable snapshots. */
 export function consider(p, aff, ctx) {
     const K = COGNITION_DEFAULTS;
@@ -264,8 +289,13 @@ export function consider(p, aff, ctx) {
         }
     }
     const maturity = clamp01(ctx.mods.maturity);
-    for (const t of agendaTerms(p, aff, ctx.now))
-        push(t.source, t.value * (0.5 + 0.5 * maturity));
+    const maturityScale = 0.5 + 0.5 * maturity;
+    const received = receivedGoalRoute(p, aff, ctx.now, maturityScale, (successor) => effortValue(p, successor, ctx) +
+        (successor.material ? materialValue(p, successor.material, scarcity) : 0));
+    for (const t of agendaTermsWithGoalEstimates(p, aff, ctx.now, received?.goals))
+        push(t.source, t.value * maturityScale);
+    if (received)
+        push(received.cost.source, received.cost.value);
     // Habit: cue-matched automaticity (cued by the option's own place), stronger before planning matures.
     const habit = p.habits.length === 0
         ? 0
@@ -316,17 +346,9 @@ export function consider(p, aff, ctx) {
         }
     }
     // Effort and mental load, read from the perceived body.
-    const per = ctx.body.perceived;
-    const effort = clamp01(aff.effort);
-    const focus = clamp01(aff.focus ?? 0);
-    // A cued habit eases initiation and attention (N4: the depleted fall back on habits), not physical exertion.
-    const ease = p.habits.length === 0
-        ? 1
-        : habitEase(p, aff, { ...ctx.habit, placeId: aff.placeId ?? ctx.habit.placeId });
-    const effortCost = (effort * K.effortBase + focus * per.sleepiness) * ease +
-        effort * per.fatigue * (1 - clamp01(p.body.fitness));
-    if (effortCost > 0)
-        push('effort', -K.effortScale * effortCost);
+    const effort = effortValue(p, aff, ctx);
+    if (effort < 0)
+        push('effort', effort);
     // Risk: chance × severity × (fear + emotionality).
     if (aff.risk && aff.risk.chance > 0 && aff.risk.severity > 0) {
         const fear = emotionLevel(p, 'fear');
@@ -340,13 +362,8 @@ export function consider(p, aff, ctx) {
         }
     }
     // Material: saturating value of host units, scaled by security/achievement/power.
-    if (aff.material) {
-        const v = p.values;
-        const weight = (v.security + v.achievement + v.power) / 3;
-        const scale = K.materialScale * (1 - K.scarcityScaleShrink * scarcity);
-        const sat = Math.sign(aff.material) * (1 - dexp(-Math.abs(aff.material) / scale));
-        push('material', K.materialWeight * sat * 2 * weight * (1 + K.scarcityMaterialGain * scarcity));
-    }
+    if (aff.material)
+        push('material', materialValue(p, aff.material, scarcity));
     // Precommitments inside their daily window.
     const mod = minuteOfDay(ctx.now);
     for (const pc of p.will.precommitments) {
@@ -382,6 +399,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;
@@ -455,5 +476,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.2.1";
+export declare const FRAMEWORK_VERSION = "2.4.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,6 +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 * 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.2.1';
+export const FRAMEWORK_VERSION = '2.4.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,6 +25,8 @@ export * from './narrate/index.js';
 export * from './needs/index.js';
 export * from './partnering/index.js';
 export * from './person.js';
+export * from './promptings/index.js';
+export { consequenceEvidence, PROSPECTION_DEFAULTS } from './prospection/index.js';
 export * 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. 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. 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.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',
+        apply: stamp,
+    },
     '2.1.0': {
         to: '2.2.0',
         note: 'person shape unchanged; method evidence now grades each action independently, preserving successful alternatives',

package/dist/person.d.ts

@@ -1,3 +1,4 @@
+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 +231,8 @@ 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[];

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,6 +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 { enablePromptings, nafsPatterns, notePromptings } from './promptings/index.js';
+import { consumeConsequences, 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';
@@ -152,6 +154,8 @@ export function createPerson(spec) {
         enableCharacterChange(p);
     if (on?.skillRetention)
         enableSkillRetention(p);
+    if (on?.promptings)
+        enablePromptings(p, on.promptings);
     return p;
 }
 /**
@@ -353,6 +357,7 @@ export function tick(p, now) {
         return;
     if (!p.body.alive) {
         p.now = now;
+        pruneConsequences(p);
         return;
     }
     const seg = PERSON_DEFAULTS.maxSegment;
@@ -366,13 +371,16 @@ export function tick(p, now) {
         // A minute so large that the grid step rounds away cannot advance (security review H2): stop, never spin.
         if (!(end > p.now)) {
             p.now = now;
+            pruneConsequences(p);
             return;
         }
         advanceSegment(p, end - p.now, load, active && act ? act.affordance : undefined);
         p.now = end;
+        pruneConsequences(p);
         if (!p.body.alive) {
             p.activity = null;
             p.now = now;
+            pruneConsequences(p);
             return;
         }
         // Discrete bookkeeping runs only on grid boundaries, so it happens at the same minutes whatever the
@@ -517,6 +525,7 @@ export function skip(p, to) {
     p.activity = null;
     skipBody(p, to);
     p.now = to;
+    pruneConsequences(p);
     skipAffect(p, to);
     advanceAgenda(p, to);
     // Lasting gists (1.8.0, opt-in): episodes now past the horizon fold into gists.
@@ -535,6 +544,7 @@ function socialKindOf(kind) {
     return SOCIAL_ALIASES[kind];
 }
 function perceiveOne(p, pc) {
+    receiveConsequences(p, pc);
     const at = Math.min(Math.max(pc.at, p.affect.lastUpdated), p.now);
     const actor = pc.actorId;
     const target = pc.targetId;
@@ -810,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;
@@ -824,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) {
@@ -1191,6 +1207,7 @@ export function finish(p, outcome, opts = {}) {
     }
     const prev = lastAction(p);
     if (completed) {
+        consumeConsequences(p, aff);
         const hctx = { now };
         if (aff.placeId !== undefined)
             hctx.placeId = aff.placeId;
@@ -1382,3 +1399,14 @@ 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 });
+}

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;