@adam0white/human-framework 2.2.1 → 2.3.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
+
+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.
+
+```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.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,7 @@ 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 { 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 +201,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 +288,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 +345,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 +361,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) {

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.3.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,8 @@ export * from './narrate/index.ts';
 export * from './needs/index.ts';
 export * from './partnering/index.ts';
 export * from './person.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.3.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,7 @@ 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 './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. 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,11 @@ 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.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.js

@@ -36,6 +36,7 @@ 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 { 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';
@@ -353,6 +354,7 @@ export function tick(p, now) {
         return;
     if (!p.body.alive) {
         p.now = now;
+        pruneConsequences(p);
         return;
     }
     const seg = PERSON_DEFAULTS.maxSegment;
@@ -366,13 +368,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 +522,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 +541,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;
@@ -1191,6 +1198,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;

package/dist/prospection/index.d.ts

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

package/dist/prospection/index.js

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

package/dist/prospection/prospection.d.ts

@@ -0,0 +1,23 @@
+import type { Affordance, ConsequenceRevision, Minute, Person, RetainedConsequence } from '../types.ts';
+export declare const PROSPECTION_DEFAULTS: {
+    maxEntries: number;
+    maxRevisions: number;
+    maxBatch: number;
+    maxIdentifierLength: number;
+    horizon: number;
+    maxMaterialCost: number;
+};
+export interface ConsequenceEvidence {
+    entry: RetainedConsequence;
+    matches: boolean;
+    feasible: boolean;
+    successorStartsAt: Minute;
+    successorEndsAt: Minute;
+    accessProbability: number;
+    terminalProbability: number;
+}
+/** Read current retained knowledge and feasibility. Does not mutate, prune or consume RNG. */
+export declare function consequenceEvidence(p: Person, aff: Affordance, now?: Minute): {
+    entries: ConsequenceEvidence[];
+    revisions: ConsequenceRevision[];
+};

package/dist/prospection/prospection.js

@@ -0,0 +1,278 @@
+/**
+ * SCOPE: one received current-action → successor consequence, acquired only through
+ * attended external testimony for this person or an untargeted broadcast. Knowledge is person-owned, source-labelled, bounded and saved.
+ * Temporal goals value expected completion using time, success and source reliability.
+ * One coherent route may contribute; it never executes actions, grants consent or
+ * advances a goal. Own completed triggers consume their received opportunity.
+ * This is not graph search, inferred procedure learning or a model of future bodies,
+ * waiting opportunity cost or another person's agency. Parameters are engineering
+ * bounds, not fitted psychological estimates. Revision memory is bounded, not an audit.
+ */
+import { temporalGoalValue } from '../agenda/agenda.js';
+import { trustOf } from '../beliefs/index.js';
+import { cmpStr, isNum, isObj, round } from '../core/index.js';
+import { expectedEffect } from '../memory/index.js';
+import { MAX_MINUTE, MINUTES_PER_DAY } from '../types.js';
+export const PROSPECTION_DEFAULTS = {
+    maxEntries: 16,
+    maxRevisions: 64,
+    maxBatch: 4,
+    maxIdentifierLength: 96,
+    horizon: 7 * MINUTES_PER_DAY,
+    maxMaterialCost: 1_000_000,
+};
+const id = (x) => typeof x === 'string' &&
+    x.length > 0 &&
+    x.length <= PROSPECTION_DEFAULTS.maxIdentifierLength &&
+    x !== '__proto__' &&
+    x !== 'constructor' &&
+    x !== 'prototype';
+const minute = (x) => isNum(x) && Math.abs(x) <= MAX_MINUTE;
+const unit = (x) => isNum(x) && x >= 0 && x <= 1;
+const revision = (x) => typeof x === 'number' && Number.isSafeInteger(x) && x >= 0;
+const identity = (a, b) => a.sourceId === b.sourceId && a.id === b.id;
+const order = (a, b) => a.receivedAt - b.receivedAt || cmpStr(a.sourceId, b.sourceId) || cmpStr(a.id, b.id);
+function action(x) {
+    if (!isObj(x) ||
+        !id(x.action) ||
+        (x.targetId !== undefined && !id(x.targetId)) ||
+        (x.placeId !== undefined && !id(x.placeId)))
+        return undefined;
+    return {
+        action: x.action,
+        ...(x.targetId !== undefined ? { targetId: x.targetId } : {}),
+        ...(x.placeId !== undefined ? { placeId: x.placeId } : {}),
+    };
+}
+function consequence(x, receivedAt) {
+    if (!isObj(x) || !id(x.id) || !revision(x.revision))
+        return undefined;
+    const trigger = action(x.trigger);
+    const successorAction = action(x.successor);
+    const s = x.successor;
+    if (!trigger ||
+        !successorAction ||
+        !isObj(s) ||
+        !isNum(s.duration) ||
+        s.duration < 0 ||
+        s.duration > PROSPECTION_DEFAULTS.horizon ||
+        !unit(s.effort) ||
+        (s.focus !== undefined && !unit(s.focus)) ||
+        (s.materialCost !== undefined &&
+            (!isNum(s.materialCost) || s.materialCost < 0 || s.materialCost > PROSPECTION_DEFAULTS.maxMaterialCost)))
+        return undefined;
+    if (!minute(x.availableFrom) ||
+        !minute(x.availableUntil) ||
+        !minute(x.expiresAt) ||
+        x.availableFrom > x.availableUntil ||
+        x.availableUntil > x.expiresAt ||
+        x.expiresAt < receivedAt ||
+        x.expiresAt > receivedAt + PROSPECTION_DEFAULTS.horizon ||
+        !unit(x.chance) ||
+        !unit(x.confidence))
+        return undefined;
+    return {
+        id: x.id,
+        revision: x.revision,
+        trigger,
+        successor: {
+            ...successorAction,
+            duration: s.duration,
+            effort: s.effort,
+            ...(s.focus !== undefined ? { focus: s.focus } : {}),
+            ...(s.materialCost !== undefined ? { materialCost: s.materialCost } : {}),
+        },
+        availableFrom: x.availableFrom,
+        availableUntil: x.availableUntil,
+        expiresAt: x.expiresAt,
+        chance: x.chance,
+        confidence: x.confidence,
+    };
+}
+function retained(x, now) {
+    if (!isObj(x) || !id(x.sourceId) || x.channel !== 'told' || !minute(x.receivedAt) || x.receivedAt > now)
+        return undefined;
+    const c = consequence(x, x.receivedAt);
+    if (!c ||
+        (x.triggeredAt !== undefined &&
+            (!minute(x.triggeredAt) || x.triggeredAt < x.receivedAt || x.triggeredAt > now)))
+        return undefined;
+    return {
+        ...c,
+        sourceId: x.sourceId,
+        channel: 'told',
+        receivedAt: x.receivedAt,
+        ...(x.triggeredAt !== undefined ? { triggeredAt: x.triggeredAt } : {}),
+    };
+}
+function cleaned(state, now) {
+    const revisions = state.revisions.filter((r) => now - r.receivedAt <= PROSPECTION_DEFAULTS.horizon);
+    return {
+        entries: state.entries.filter((e) => e.expiresAt >= now && revisions.some((r) => identity(r, e) && r.revision === e.revision)),
+        revisions,
+    };
+}
+function store(p, s) {
+    if (s.entries.length || s.revisions.length)
+        p.prospection = s;
+    else
+        delete p.prospection;
+}
+/** Expiry changes only existing optional state. @internal */
+export function pruneConsequences(p, now = p.now) {
+    if (p.prospection)
+        store(p, cleaned(p.prospection, now));
+}
+/** Called only for an attended percept. Invalid combined batches mutate no prospection state. @internal */
+export function receiveConsequences(p, pc) {
+    if (pc.consequences === undefined && pc.withdrawConsequences === undefined)
+        return false;
+    if (pc.channel !== 'told' ||
+        !id(pc.actorId) ||
+        pc.actorId === p.id ||
+        (pc.targetId !== undefined && pc.targetId !== p.id))
+        return false;
+    const adds = pc.consequences ?? [];
+    const removes = pc.withdrawConsequences ?? [];
+    if (!Array.isArray(adds) ||
+        !Array.isArray(removes) ||
+        adds.length + removes.length > PROSPECTION_DEFAULTS.maxBatch ||
+        adds.length + removes.length === 0)
+        return false;
+    const additions = adds.map((x) => consequence(x, p.now));
+    if (additions.some((x) => x === undefined) ||
+        removes.some((x) => !isObj(x) || !id(x.id) || !revision(x.revision)))
+        return false;
+    const withdrawals = removes;
+    const batch = [...additions.map((x) => ({ id: x?.id, revision: x?.revision })), ...withdrawals];
+    if (new Set(batch.map((x) => x.id)).size !== batch.length)
+        return false;
+    const state = cleaned(structuredClone(p.prospection ?? { entries: [], revisions: [] }), p.now);
+    const sourceId = pc.actorId;
+    const updates = batch.filter((b) => !state.revisions.some((r) => r.sourceId === sourceId && r.id === b.id && r.revision >= (b.revision ?? 0)));
+    const newIds = updates.filter((b) => !state.revisions.some((r) => r.sourceId === sourceId && r.id === b.id));
+    // Never evict a still-valid tombstone to admit a batch; dedup holds within the stated horizon.
+    if (state.revisions.length + newIds.length > PROSPECTION_DEFAULTS.maxRevisions)
+        return false;
+    for (const b of updates) {
+        state.entries = state.entries.filter((e) => !(e.sourceId === sourceId && e.id === b.id));
+        state.revisions = state.revisions.filter((r) => !(r.sourceId === sourceId && r.id === b.id));
+        const addition = additions.find((a) => a?.id === b.id);
+        if (addition)
+            state.entries.push({ ...addition, sourceId, channel: 'told', receivedAt: p.now });
+        state.revisions.push({ sourceId, id: b.id, revision: b.revision, receivedAt: p.now });
+    }
+    if (state.entries.length > PROSPECTION_DEFAULTS.maxEntries) {
+        const oldest = [...state.entries]
+            .sort((a, b) => Number(b.triggeredAt !== undefined) - Number(a.triggeredAt !== undefined) || order(a, b))
+            .slice(0, state.entries.length - PROSPECTION_DEFAULTS.maxEntries);
+        state.entries = state.entries.filter((e) => !oldest.includes(e));
+    }
+    store(p, state);
+    return true;
+}
+const matches = (a, b) => a.action === b.action && a.targetId === b.targetId && a.placeId === b.placeId;
+/** Own actual completed trigger consumes an opportunity, without predicting consent. @internal */
+export function consumeConsequences(p, completed) {
+    for (const e of p.prospection?.entries ?? [])
+        if (e.triggeredAt === undefined && matches(e.trigger, completed))
+            e.triggeredAt = p.now;
+}
+/** Read current retained knowledge and feasibility. Does not mutate, prune or consume RNG. */
+export function consequenceEvidence(p, aff, now = p.now) {
+    return {
+        entries: (p.prospection?.entries ?? []).map((entry) => {
+            const start = Math.max(now + Math.max(0, aff.duration), entry.availableFrom);
+            const end = start + entry.successor.duration;
+            const match = matches(entry.trigger, aff);
+            const feasible = match &&
+                entry.triggeredAt === undefined &&
+                now <= entry.expiresAt &&
+                end <= entry.availableUntil &&
+                Number.isFinite(end);
+            const accessProbability = expectedEffect(p, aff).successRate * entry.chance * entry.confidence * trustOf(p, entry.sourceId);
+            return {
+                entry: structuredClone(entry),
+                matches: match,
+                feasible,
+                successorStartsAt: start,
+                successorEndsAt: end,
+                accessProbability,
+                terminalProbability: accessProbability * expectedEffect(p, successorOffer(entry)).successRate,
+            };
+        }),
+        revisions: structuredClone((p.prospection?.revisions ?? []).filter((r) => now - r.receivedAt <= PROSPECTION_DEFAULTS.horizon)),
+    };
+}
+function successorOffer(e) {
+    const { materialCost, ...rest } = e.successor;
+    return {
+        ...rest,
+        id: 'prospective-successor',
+        label: 'Received successor',
+        advertises: {},
+        ...(materialCost !== undefined ? { material: -materialCost } : {}),
+    };
+}
+/** Select a whole route in the exact rounded units cognition emits. @internal */
+export function receivedGoalRoute(p, aff, now, maturityScale, costs) {
+    const goals = p.agenda.goals.filter((g) => g.status === 'active' && g.temporal !== undefined);
+    if (!goals.length || !p.prospection?.entries.length)
+        return undefined;
+    const direct = goals.map((g) => temporalGoalValue(p, g, aff, now, now + Math.max(0, aff.duration)));
+    const baseline = direct.reduce((sum, value) => sum + round(value * maturityScale), 0);
+    let bestScore = baseline;
+    let best;
+    const entries = consequenceEvidence(p, aff, now).entries.sort((a, b) => cmpStr(a.entry.sourceId, b.entry.sourceId) || cmpStr(a.entry.id, b.entry.id));
+    for (const e of entries) {
+        if (!e.feasible)
+            continue;
+        const successor = successorOffer(e.entry);
+        const values = goals.map((g, i) => Math.max(direct[i] ?? 0, e.accessProbability * temporalGoalValue(p, g, successor, now, e.successorEndsAt)));
+        const cost = round(e.accessProbability * Math.min(0, costs(successor)));
+        const total = values.reduce((sum, value) => sum + round(value * maturityScale), 0) + cost;
+        if (!(round(total - bestScore) > 0))
+            continue;
+        bestScore = total;
+        best = {
+            goals: new Map(goals.map((g, i) => [g.id, values[i] ?? 0])),
+            cost: { source: `prospection:cost:${e.entry.sourceId}:${e.entry.id}`, value: cost },
+        };
+    }
+    return best;
+}
+/** Conservative optional-slice restore; ambiguous identities drop the slice. @internal */
+export function sanitizeProspection(input, now, personId) {
+    if (!isObj(input) ||
+        !Array.isArray(input.entries) ||
+        !Array.isArray(input.revisions) ||
+        input.entries.length > PROSPECTION_DEFAULTS.maxEntries ||
+        input.revisions.length > PROSPECTION_DEFAULTS.maxRevisions)
+        return undefined;
+    const entries = input.entries.map((x) => retained(x, now)).filter((e) => e?.sourceId !== personId);
+    const revisions = [];
+    for (const r of input.revisions) {
+        if (!isObj(r) ||
+            !id(r.sourceId) ||
+            r.sourceId === personId ||
+            !id(r.id) ||
+            !revision(r.revision) ||
+            !minute(r.receivedAt) ||
+            r.receivedAt > now)
+            continue;
+        if (revisions.some((old) => identity(old, r)))
+            return undefined;
+        revisions.push({ sourceId: r.sourceId, id: r.id, revision: r.revision, receivedAt: r.receivedAt });
+    }
+    const valid = [];
+    for (const e of entries) {
+        if (!e)
+            continue;
+        if (valid.some((old) => identity(old, e)))
+            return undefined;
+        if (revisions.some((r) => identity(r, e) && r.revision === e.revision && r.receivedAt === e.receivedAt))
+            valid.push(e);
+    }
+    const state = cleaned({ entries: valid, revisions }, now);
+    return state.entries.length || state.revisions.length ? state : undefined;
+}

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 { sanitizeProspection } from './prospection/index.js';
 import { sanitizeSkillRetention } from './skills/index.js';
 import { sanitizeGroups, sanitizeImpressions } from './social/index.js';
 import { ENGINE_VERSION, MAX_MINUTE, PERSON_SCHEMA } from './types.js';
@@ -59,6 +60,7 @@ const OPTIONAL_KEYS = new Set([
     'ambient',
     'retention',
     'methods',
+    'prospection',
 ]);
 /** 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);
@@ -171,6 +173,7 @@ export function restore(input) {
     keepValid(out, 'ambient', sanitizeAmbient);
     keepValid(out, 'retention', cleanRetention);
     keepValid(out, 'methods', sanitizeMethods);
+    keepValid(out, 'prospection', (x) => sanitizeProspection(x, out.now, out.id));
     boundLists(out);
     return out;
 }

package/dist/types.d.ts

@@ -543,6 +543,10 @@ export interface Goal {
     status: 'active' | 'achieved' | 'abandoned';
     adoptedAt: Minute;
     deadline?: Minute;
+    /** Opt-in expected completion valuation; deadline remains urgency, never a cutoff. */
+    temporal?: {
+        halfLifeMinutes: number;
+    };
     /** Last minute the goal was advanced (or adopted); neglect is counted from here. */
     lastAdvancedAt?: Minute;
     /** Importance before neglect decay; `revisePurposes` recomputes `importance` from it. */
@@ -787,7 +791,8 @@ export interface Activity {
 }
 export declare const PERSON_SCHEMA = "human/person@1";
 /**
- * Current: 2.2.0 (2026-10-14): method evidence grades each action independently.
+ * Current: 2.3.0 (2026-10-17): optional temporal goals and received consequences.
+ * 2.2.0 (2026-10-14): method evidence grades each action independently.
  * Successful alternatives no longer count as failures of another action. Person state shape is unchanged.
  * 2.1.0 saves migrate by stamping the version.
  *
@@ -822,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.2.0";
+export declare const ENGINE_VERSION = "2.3.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -923,6 +928,49 @@ export interface MethodsState {
         cues: MethodCue[];
     };
 }
+/** Exact current-action identity; omitted target/place match only omitted values. */
+export interface ConsequenceAction {
+    action: string;
+    targetId?: EntityId;
+    placeId?: EntityId;
+}
+/** A received conditional opportunity, never another person's consent or an actual outcome. */
+export interface ReceivedConsequence {
+    id: string;
+    revision: number;
+    trigger: ConsequenceAction;
+    successor: ConsequenceAction & {
+        duration: number;
+        effort: Unit;
+        focus?: Unit;
+        materialCost?: number;
+    };
+    availableFrom: Minute;
+    /** Latest permitted successor completion, inclusive. */
+    availableUntil: Minute;
+    expiresAt: Minute;
+    /** P(access | trigger completes successfully), not consent. */
+    chance: Unit;
+    confidence: Unit;
+}
+export interface ConsequenceRevision {
+    sourceId: EntityId;
+    id: string;
+    revision: number;
+    receivedAt: Minute;
+}
+export interface RetainedConsequence extends ReceivedConsequence {
+    sourceId: EntityId;
+    channel: 'told';
+    receivedAt: Minute;
+    /** Own completed trigger; does not establish access or goal progress. */
+    triggeredAt?: Minute;
+}
+/** Optional person-owned received knowledge. Deduplication lasts only within bounded revision memory. */
+export interface ProspectionState {
+    entries: RetainedConsequence[];
+    revisions: ConsequenceRevision[];
+}
 export interface Person {
     schema: typeof PERSON_SCHEMA;
     /** Engine version that last wrote this state. */
@@ -942,6 +990,8 @@ export interface Person {
     skills: Record<string, Skill>;
     /** Acquired conditional method evidence and current received cues; absent until used. */
     methods?: MethodsState;
+    /** Received future consequences, absent until attended testimony supplies them. */
+    prospection?: ProspectionState;
     /** Practice consolidation (1.8.0, opt-in via `enableSkillRetention`). Owned by `skills/`. */
     skillRetention?: {
         consolidationHours: number;
@@ -1107,6 +1157,12 @@ export interface Percept {
         minutes: number;
         domain?: LearningDomain;
     };
+    /** At most four additions/withdrawals combined; attended external testimony to this person or a broadcast. */
+    consequences?: readonly ReceivedConsequence[];
+    withdrawConsequences?: readonly {
+        id: string;
+        revision: number;
+    }[];
 }
 /**
  * Domains with distinct age curves for learning rate (`lifecourse.learningMultiplier`). 'general' is

package/dist/types.js

@@ -84,7 +84,8 @@ export const EMOTIONS = [
 // ---------------------------------------------------------------------------------------------
 export const PERSON_SCHEMA = 'human/person@1';
 /**
- * Current: 2.2.0 (2026-10-14): method evidence grades each action independently.
+ * Current: 2.3.0 (2026-10-17): optional temporal goals and received consequences.
+ * 2.2.0 (2026-10-14): method evidence grades each action independently.
  * Successful alternatives no longer count as failures of another action. Person state shape is unchanged.
  * 2.1.0 saves migrate by stamping the version.
  *
@@ -119,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.2.0';
+export const ENGINE_VERSION = '2.3.0';

package/package.json

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