@adam0white/human-framework 2.19.0 → 2.21.0

package/dist/index.js

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export const FRAMEWORK_VERSION = '2.19.0';
+export const FRAMEWORK_VERSION = '2.21.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, isContinuingCommitment, isUnderWay, MAKRUH_DEFAULTS, makruhWindows, missedExcuse, onFinished, owedMakeUps, PRAYER_IMPORTANCE, PURPOSE_DEFAULTS, prayerWindows, pressureReachedAt, promise, proposeGoals, RAMADAN_DEFAULTS, ramadanFast, ramadanMeals, release as releaseCommitment, retimeCommitments, retirePaidMakeUps, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.js';
@@ -25,6 +25,7 @@ export { clearMethodContext, demonstrateMethod, METHOD_DEFAULTS, methodEvidence,
 export { MIGRATIONS, migratableVersions, migrate } from './migrate.js';
 export * from './narrate/index.js';
 export * from './needs/index.js';
+export { confirmObservedReputation } from './observed-reputation.js';
 export * from './partnering/index.js';
 export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistence/index.js';
 export * from './person.js';
@@ -34,6 +35,7 @@ export * from './presentation.js';
 export { adoptProjectTask, considerProjects, enableProjects, PROJECTS_DEFAULTS, projectAppeal, } from './projects/index.js';
 export * from './promptings/index.js';
 export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, enablePlanning, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, seedConsequences, } from './prospection/index.js';
+export { qalbReading } from './qalb.js';
 export { fingerprint, restore, snapshot } from './restore.js';
 export * from './review/index.js';
 export * from './scenarios/index.js';

package/dist/memory/memory.d.ts

@@ -1,3 +1,29 @@
+/**
+ * SCOPE: episodic memory and learned action expectations. Episodes carry a salience that decays
+ * exponentially (Ebbinghaus-style forgetting curve, modelled as a single exponential per episode) with a
+ * half-life that lengthens for emotionally strong episodes (emotional-enhancement of memory), and recall
+ * slightly raises the salience of what is retrieved (testing effect). Expectations are cached action
+ * values learned by a delta rule (prediction-error learning, Rescorla-Wagner shape) with a minimum
+ * learning rate and a clamped step, blended with the host's advertisement by sample-based confidence.
+ * It does NOT model reconsolidation, false memory, interference between similar episodes, sleep-dependent
+ * consolidation, semantic abstraction, or model-based planning; parameters are engineering defaults for
+ * game time scales, not calibrated estimates.
+ *
+ * SCOPE (lasting gists, 1.8.0, opt-in per person with `enableGists`): episodic detail does not last a life, but the
+ * gist of what mattered does. An episode that leaves the episode list (evicted beyond the bound, or older than
+ * `GIST_DEFAULTS.horizon` at a `foldGists` call, which the composite makes at each day's close) is folded into the
+ * gist with the same kind, action, people and place when it was emotional enough (|valence| ≥ `minValence`, or a
+ * loss); weaker ones are simply forgotten. A gist keeps the encoding-weighted mean valence, a count and the summary of
+ * its strongest episode, and fades with half-lives of years (`halfLifeNeutral`..`halfLifeEmotional` by |valence|).
+ * Gists answer `recall` and `recallByCue` like episodes (so a remembered fear or loss still comes back at its place,
+ * person or anniversary), and `expectedEffect` reports the gists about an option's action or place, which cognition
+ * weighs as a `memory` term that fades as fresh experience of the option accumulates. So a fear learned at 20 still
+ * shapes choices at 40 after its episodes are gone, and enough good later visits outweigh it. Named shapes: the
+ * fading of episodic detail while gist persists (fuzzy-trace theory, Brainerd & Reyna) and the long retention of
+ * emotional autobiographical memories; the horizon, thresholds, half-lives and the bound of 64 are engineering
+ * choices. It does not model reconstruction errors in gists, deliberate rehearsal beyond retelling (`recall`
+ * boosts), or semantic knowledge abstracted from gists.
+ */
 import type { Affordance, AppraisalEvent, EntityId, Episode, Gist, MemoryState, Minute, NeedId, Outcome, Person, Signed, Unit } from '../types.ts';
 export declare const MEMORY_DEFAULTS: {
     maxEpisodes: number;

package/dist/memory/memory.js

@@ -25,6 +25,7 @@
  * boosts), or semantic knowledge abstracted from gists.
  */
 import { clamp, clamp01, clampSigned, decay, hourOf, isNum, isObj, lerp, runningMean, } from '../core/index.js';
+import { keysOf } from '../core/keys.js';
 import { DAYS_PER_YEAR, MINUTES_PER_DAY, MINUTES_PER_YEAR } from '../types.js';
 export const MEMORY_DEFAULTS = {
     maxEpisodes: 200,
@@ -511,10 +512,7 @@ export function expectedEffect(p, aff) {
     const samples = learned?.samples ?? 0;
     const confidence = samples / (samples + MEMORY_DEFAULTS.confidenceK);
     const needs = {};
-    const keys = new Set([
-        ...Object.keys(aff.advertises),
-        ...(learned ? Object.keys(learned.needs) : []),
-    ]);
+    const keys = new Set([...keysOf(aff.advertises), ...(learned ? keysOf(learned.needs) : [])]);
     for (const k of [...keys].sort()) {
         const adv = aff.advertises[k] ?? 0;
         const lv = learned?.needs[k];
@@ -563,11 +561,7 @@ function updateExpectation(p, key, aff, success, realized, felt) {
     }
     x.samples += 1;
     const n = x.samples;
-    const keys = new Set([
-        ...Object.keys(x.needs),
-        ...Object.keys(aff.advertises),
-        ...Object.keys(realized),
-    ]);
+    const keys = new Set([...keysOf(x.needs), ...keysOf(aff.advertises), ...keysOf(realized)]);
     for (const k of keys) {
         const prior = x.needs[k] ?? aff.advertises[k] ?? 0;
         x.needs[k] = step(prior, realized[k] ?? 0, n);
@@ -582,7 +576,8 @@ function updateExpectation(p, key, aff, success, realized, felt) {
 export function learnOutcome(p, aff, outcome, realized, felt) {
     if (outcome.status === 'interrupted')
         return;
-    const success = outcome.status === 'completed';
+    // A declared voiding purpose succeeds only when the actual outcome confirms it.
+    const success = outcome.status === 'completed' && (aff.voidsBladder !== true || outcome.voidedBladder === true);
     const touched = new Set([expectationKey({ action: aff.action })]);
     if (aff.targetId !== undefined)
         touched.add(expectationKey(aff));

package/dist/migrate.js

@@ -41,6 +41,11 @@ function renameAmbient(json) {
 }
 /** The chain, keyed by the version each step upgrades from. */
 export const MIGRATIONS = {
+    '2.17.0': {
+        to: '2.21.0',
+        note: 'doze and bladder state start absent; old callers retain their continuation',
+        apply: stamp,
+    },
     '1.4.0': {
         to: '1.5.0',
         note: 'person shape unchanged; standing advice is heard for the running activity from now on',

package/dist/narrate/lexicon.js

@@ -23,6 +23,7 @@ export const EN_LINES = {
     ],
     'need:rest': ['I need to sit down for a while.', 'A rest first, then the rest.'],
     'need:relief': ['This pain needs seeing to.', "I can't think past the pain."],
+    'need:bladder': ['I need to use the toilet.'],
     'need:belonging': ["I've been alone too long. I want company.", 'Let me find someone to talk to.'],
     'need:leisure': ['I need a break from all this.', 'Time for something easier.'],
     'need:meaning': ['I want to do something that matters.', 'Something worthwhile, for once.'],
@@ -102,6 +103,7 @@ export const EN_LINES = {
     'intention:sleep': ['to sleep'],
     'intention:rest': ['to rest'],
     'intention:relief': ['to ease the pain'],
+    'intention:bladder': ['to use the toilet'],
     'intention:belonging': ['to be with people'],
     'intention:leisure': ['to enjoy myself'],
     'intention:meaning': ['to do something that matters'],

package/dist/narrate/plain.js

@@ -22,6 +22,7 @@ export const PLAIN_EN_LINES = {
         'I need to sleep before I do anything else.',
     ],
     'need:rest': ['I need to sit down for a while.', 'I will rest before I do anything else.'],
+    'need:bladder': ['I need to use the toilet.'],
     'need:relief': [
         'I need to do something about this pain.',
         'The pain makes it hard to think about anything else.',
@@ -116,6 +117,7 @@ export const PLAIN_EN_LINES = {
     'intention:water': ['to drink'],
     'intention:sleep': ['to sleep'],
     'intention:rest': ['to rest'],
+    'intention:bladder': ['to use the toilet'],
     'intention:relief': ['to ease the pain'],
     'intention:belonging': ['to be with people'],
     'intention:leisure': ['to enjoy myself'],

package/dist/observed-reputation.d.ts

@@ -0,0 +1,4 @@
+import { type TraitEffect } from './social/social.ts';
+import type { EntityId, Minute, Person } from './types.ts';
+/** Returns the same detached, sorted misled-source ids as confirm; no relationship alias escapes. */
+export declare function confirmObservedReputation(p: Person, prop: string, truth: boolean, now: Minute, table?: Record<string, TraitEffect>): EntityId[];

package/dist/observed-reputation.js

@@ -0,0 +1,16 @@
+/**
+ * SCOPE: opt-in composition of beliefs.confirm and social.applyReputationBelief, in that order.
+ * Owns no state or formula. This is the Hearsay 2 wrapper: direct observation corrects the belief,
+ * recalibrates its sources and applies the credence change to the subject's relationship. It does
+ * not infer opposite traits, accuse a source of lying, run attention or record a percept. Hosts
+ * supply only observations their person has access to. Existing callers remain unchanged.
+ */
+import { confirm, credence } from './beliefs/beliefs.js';
+import { applyReputationBelief } from './social/social.js';
+/** Returns the same detached, sorted misled-source ids as confirm; no relationship alias escapes. */
+export function confirmObservedReputation(p, prop, truth, now, table) {
+    const before = credence(p, prop);
+    const misled = confirm(p, prop, truth, now);
+    applyReputationBelief(p, prop, before, credence(p, prop), now, table);
+    return misled;
+}

package/dist/person.d.ts

@@ -50,6 +50,11 @@ export declare const PERSON_DEFAULTS: {
     nightFrom: number;
     nightTo: number;
 };
+/**
+ * SCOPE (host setup): optional habits and expectations copy authored records, including nested cues and
+ * need deltas, in source order. Invalid numbers, domains or collection bounds reject with RangeError;
+ * setup never clamps, evicts, learns, advances time or consumes RNG. Omitted options keep legacy state.
+ */
 export declare function createPerson(spec: PersonSpec): Person;
 export interface PersonReadout {
     body: BodyReadout;

package/dist/person.js

@@ -22,18 +22,20 @@
 import { actionTendencies, advanceAffect, appraise, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, feel, readAffect, regulate, release, skipAffect, skipCrisis, strain, tendencyEmotions, } from './affect/index.js';
 import { advanceAgenda, agendaTermsWithGoalEstimates, createAgenda, onFinished, promise, proposeGoals, revisePurposes, } from './agenda/index.js';
 import { advanceBeliefs, applyContradiction, attend, believe, confirm, credence, noteProvenance, trustOf, } from './beliefs/index.js';
+import { enableBladder, voidBladder } from './body/bladder.js';
+import { checkDoze, DOZE_DEFAULTS, enableDoze, enterVoluntarySleep, wakeDoze } from './body/doze.js';
 import { advanceBody, BODY_DEFAULTS, checkDowned, clearDowned, consume, createBody, downedAllows, enableFatigueStore, enableFullness, expose, injure, nextBodyThreshold, readBody, setDowned, sicken, skipBody, } from './body/index.js';
 import { ageCharacter, enableCharacterChange, noteCharacterDay, noteCharacterSocial, } from './character/index.js';
 import { closeDay, enableYearbook, endDay, noteAnswer, noteCommitments, noteDecision, noteMood, noteOutcome, trimChronicle, } from './chronicle/index.js';
 import { decide as cognitionDecide, desperationOf, prospectiveRoute, scoreAll } from './cognition/index.js';
 import { createConscience, guiltLoad, heldNorms, normVeto, recordDeed, recordRepair, repent, } from './conscience/index.js';
-import { clamp01, clampSigned, createRng, dayOf, isObj, minuteOfDay, round } from './core/index.js';
+import { clamp01, clampSigned, createRng, dayOf, isObj, keysOf, minuteOfDay, round } from './core/index.js';
 import { enableCuriosity, noteCuriosity } from './curiosity/index.js';
 import { ambientBodyParams, ambientModifiers, ambientMood, ambientNeeds } from './environment/index.js';
 import { aptitudeOf, createFamily, pregnancyModifiers } from './family/index.js';
-import { advanceHabits, reinforce, withholdCued } from './habits/index.js';
+import { advanceHabits, HABIT_DEFAULTS, reinforce, withholdCued } from './habits/index.js';
 import { ageYears, learningMultiplier, lifeModifiers } from './lifecourse/index.js';
-import { advanceMemory, createMemory, enableGists, foldGists, learnOutcome, recallByCue, remember, } from './memory/index.js';
+import { advanceMemory, createMemory, enableGists, foldGists, learnOutcome, MEMORY_DEFAULTS, recallByCue, remember, } from './memory/index.js';
 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';
@@ -114,7 +116,56 @@ function fill(keys, given, def) {
     }
     return out;
 }
+function validateHostSetup(spec) {
+    const finite = (n) => Number.isFinite(n);
+    const unit = (n) => finite(n) && n >= 0 && n <= 1;
+    const count = (n) => Number.isSafeInteger(n) && n >= 0;
+    const optional = (n, valid) => n === undefined || valid(n);
+    if (spec.habits !== undefined) {
+        if (!Array.isArray(spec.habits) || spec.habits.length > HABIT_DEFAULTS.maxHabits)
+            throw new RangeError('Invalid habits setup bound');
+        for (const h of spec.habits) {
+            if (!h ||
+                !isObj(h.cue) ||
+                typeof h.action !== 'string' ||
+                h.action.length === 0 ||
+                !unit(h.strength) ||
+                !count(h.repetitions) ||
+                !finite(h.lastAt) ||
+                !optional(h.withheld, count) ||
+                !optional(h.lastWithheldAt, finite) ||
+                !optional(h.craving, unit) ||
+                !optional(h.cue.hour, (n) => finite(n) && n >= 0 && n < 24) ||
+                (h.cue.placeId !== undefined && typeof h.cue.placeId !== 'string') ||
+                (h.cue.after !== undefined && typeof h.cue.after !== 'string'))
+                throw new RangeError('Invalid habit setup record');
+        }
+    }
+    if (spec.expectations !== undefined) {
+        if (!Array.isArray(spec.expectations) || spec.expectations.length > MEMORY_DEFAULTS.maxExpectations)
+            throw new RangeError('Invalid expectations setup bound');
+        for (const e of spec.expectations) {
+            if (!e ||
+                typeof e.key !== 'string' ||
+                e.key.length === 0 ||
+                !isObj(e.needs) ||
+                !unit(e.successRate) ||
+                !count(e.samples) ||
+                !finite(e.valence) ||
+                Math.abs(e.valence) > 1 ||
+                Object.entries(e.needs).some(([key, n]) => ![...PHYSIOLOGICAL_NEEDS, ...PSYCHOLOGICAL_NEEDS].some((need) => need === key) ||
+                    (n !== undefined && !finite(n))))
+                throw new RangeError('Invalid expectation setup record');
+        }
+    }
+}
+/**
+ * SCOPE (host setup): optional habits and expectations copy authored records, including nested cues and
+ * need deltas, in source order. Invalid numbers, domains or collection bounds reject with RangeError;
+ * setup never clamps, evicts, learns, advances time or consumes RNG. Omitted options keep legacy state.
+ */
 export function createPerson(spec) {
+    validateHostSetup(spec);
     const now = spec.now ?? 0;
     const traits = fill(TRAIT_KEYS, spec.traits, 0.5);
     const values = fill(VALUE_KEYS, spec.values, 0.5);
@@ -143,6 +194,38 @@ export function createPerson(spec) {
         trace: [],
         nextDecision: 0,
     };
+    if (spec.habits)
+        p.habits = spec.habits.map((h) => {
+            const cue = {};
+            if (h.cue.hour !== undefined)
+                cue.hour = h.cue.hour;
+            if (h.cue.placeId !== undefined)
+                cue.placeId = h.cue.placeId;
+            if (h.cue.after !== undefined)
+                cue.after = h.cue.after;
+            const out = {
+                cue,
+                action: h.action,
+                strength: h.strength,
+                repetitions: h.repetitions,
+                lastAt: h.lastAt,
+            };
+            if (h.craving !== undefined)
+                out.craving = h.craving;
+            if (h.withheld !== undefined)
+                out.withheld = h.withheld;
+            if (h.lastWithheldAt !== undefined)
+                out.lastWithheldAt = h.lastWithheldAt;
+            return out;
+        });
+    if (spec.expectations)
+        p.memory.expectations = spec.expectations.map((e) => ({
+            key: e.key,
+            needs: Object.fromEntries(Object.entries(e.needs)),
+            successRate: e.successRate,
+            samples: e.samples,
+            valence: e.valence,
+        }));
     if (spec.lexicon)
         p.lexicon = structuredClone(spec.lexicon);
     if (spec.retention)
@@ -177,6 +260,10 @@ export function createPerson(spec) {
         enablePromptings(p, on.promptings);
     if (on?.review)
         enableReview(p, on.review);
+    if (on?.doze)
+        enableDoze(p, on.doze);
+    if (on?.bladder)
+        enableBladder(p);
     return p;
 }
 /**
@@ -392,10 +479,10 @@ export function tick(p, now) {
     const seg = PERSON_DEFAULTS.maxSegment;
     while (p.now < now) {
         const act = p.activity;
-        const active = act !== null && p.now < act.endsAt;
+        const active = act !== null && act.dozedAt === undefined && p.body.doze?.since === undefined && p.now < act.endsAt;
         // Segment boundaries sit on an absolute grid, so how a host chunks its calls does not change the result.
         const grid = (Math.floor(p.now / seg) + 1) * seg;
-        const end = Math.min(active ? Math.min(now, act.endsAt) : now, grid);
+        const end = Math.min(active ? Math.min(now, act.endsAt) : now, grid, p.body.doze ? Math.floor(p.now) + 1 : Number.POSITIVE_INFINITY);
         const load = active && act ? { effort: act.effort, focus: act.focus, mode: act.mode } : PERSON_DEFAULTS.idleLoad;
         // A minute so large that the grid step rounds away cannot advance (security review H2): stop, never spin.
         if (!(end > p.now)) {
@@ -407,6 +494,12 @@ export function tick(p, now) {
         }
         advanceSegment(p, end - p.now, load, active && act ? act.affordance : undefined);
         p.now = end;
+        if (Number.isInteger(end) && p.body.doze && !(act && act.endsAt === end) && checkDoze(p, end)) {
+            if (act)
+                act.dozedAt ??= end;
+            // Physical onset must not erase a host/percept reason awaiting resolution.
+            interrupt(p, end, act?.interrupt?.reason ?? 'doze');
+        }
         pruneConsequences(p);
         if (p.pursuit)
             releasePursuit(p);
@@ -771,6 +864,18 @@ function judgeDeed(p, actor, pc, at) {
 export function perceive(p, percepts, options = {}) {
     if (percepts.length === 0 || !p.body.alive)
         return [];
+    if (p.body.doze?.since !== undefined) {
+        const wakes = percepts.some((pc) => Number.isFinite(pc.at) &&
+            pc.at === p.now &&
+            Number.isFinite(pc.salience) &&
+            pc.salience >= DOZE_DEFAULTS.wakeSalience &&
+            pc.near !== false &&
+            (pc.targetId === p.id || pc.near === true) &&
+            (pc.channel === 'heard' || pc.channel === 'felt' || pc.channel === 'social'));
+        if (!wakes)
+            return [];
+        wakeDoze(p, p.now);
+    }
     const body = readBodyOf(p);
     const attended = attend(p, [...percepts], {
         focus: p.activity?.focus ?? 0,
@@ -1068,6 +1173,8 @@ function thresholdFor(p, load, review) {
 export function begin(p, aff, record, opts = {}) {
     if (!p.body.alive)
         return null;
+    if (p.body.doze?.since !== undefined && aff.mode !== 'sleep')
+        return null;
     const now = p.now;
     if (p.pursuit) {
         const considered = record.considered.find((c) => c.affordanceId === aff.id);
@@ -1143,6 +1250,8 @@ export function begin(p, aff, record, opts = {}) {
         activity.commitmentId = c.id;
     }
     p.activity = activity;
+    if (load.mode === 'sleep')
+        enterVoluntarySleep(p);
     advanceBody(p, 0, load, mods); // apply the sleep/wake switch now
     const review = load.mode === 'sleep' ? PERSON_DEFAULTS.sleepReviewInterval : PERSON_DEFAULTS.reviewInterval;
     const thresholdAt = thresholdFor(p, load, review);
@@ -1367,7 +1476,7 @@ export function finish(p, outcome, opts = {}) {
     const now = p.now;
     const aff = act.affordance;
     const completed = outcome.status === 'completed';
-    const minutes = Math.max(0, now - act.startedAt);
+    const minutes = Math.max(0, Math.min(now, act.dozedAt ?? now) - act.startedAt);
     const mods = lifeModifiers(p);
     const D = PERSON_DEFAULTS;
     const before = readNeeds(p, readBodyOf(p));
@@ -1380,6 +1489,8 @@ export function finish(p, outcome, opts = {}) {
     if (given.relief)
         bodyDeltas.relief = given.relief;
     consume(p, bodyDeltas);
+    if (completed && outcome.voidedBladder === true)
+        voidBladder(p);
     const psych = {};
     for (const id of PSYCHOLOGICAL_NEEDS)
         if (given[id] !== undefined)
@@ -1399,7 +1510,7 @@ export function finish(p, outcome, opts = {}) {
     const realized = realizedNeedDeltas(act, given, before, after);
     // Felt valence.
     let felt = 0;
-    for (const id of Object.keys(realized)) {
+    for (const id of keysOf(realized)) {
         felt += D.feltGain * (D.feltBase + urgencyOf(before, id)) * (realized[id] ?? 0);
     }
     if (outcome.status === 'failed')

package/dist/persona.js

@@ -4,8 +4,8 @@
  * identity, age, family and health compatibility before returning a new Person. Neither input is mutated.
  * This is not a world migration, identity registry, transport, hash, authentication or general calendar mapper.
  * v1 admits zero-duration travel and healthy compatible bodies only; family/bonds remain host-authored and must
- * match source provenance. Portable v1 accepts its published 2.14.1 stamp and the current engine;
- * the 2.14.1 to 2.17.0 migration changes no portable field semantics. Pregnancy and nonempty temporal bonds are unsupported in v1. All other world-dependent stores stay with the source and are disclosed as omitted.
+ * match source provenance. Portable v1 accepts its published 2.14.1 and 2.17.0 stamps and the current engine;
+ * the bodily opt-ins change no portable field semantics. Pregnancy and nonempty temporal bonds are unsupported in v1. All other world-dependent stores stay with the source and are disclosed as omitted.
  */
 import { hasUnresolvedMakeUps, sameChain } from './agenda/agenda.js';
 import { createPerson } from './person.js';
@@ -186,8 +186,10 @@ export function validatePersonaProjection(input) {
     text(input.mappingVersion);
     text(input.name);
     keys(input.source, ['schema', 'engine', 'id', 'now']);
-    // Both published passport releases used 2.14.1; the next engine upgrade is stamp-only here.
-    const compatibleEngine = input.source.engine === ENGINE_VERSION || input.source.engine === '2.14.1';
+    // The 2.14.1 and 2.17.0 portable fields retain their semantics across the bodily opt-ins.
+    const compatibleEngine = input.source.engine === ENGINE_VERSION ||
+        input.source.engine === '2.17.0' ||
+        input.source.engine === '2.14.1';
     if (input.source.schema !== PERSON_SCHEMA || !compatibleEngine)
         fail('unsupported source schema/engine; migrate the source before projection');
     text(input.source.id);

package/dist/qalb.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SCOPE: a read-only narration lens over retained attention evidence, held norms and conviction,
+ * mood and the three distinct trust stores. Owns no state and supplies no decision input. It does
+ * not infer spiritual health, rank people, judge norms, measure the ruh or compute divine acceptance.
+ * Retained memories are evidence available for narration, not a complete attention history.
+ *
+ * Provenance: research/reconciliation.md §2–4, §7 (Q7: Qur'an 22:46; H9: Bukhari 52 /
+ * Muslim 1599a); research/islamic-foundations.md §2 (qalb as an overlapping interpretive view);
+ * research/decisions.md, “Qalb, nafs, fitra, ʿaql as state”. These support the lens, not a
+ * diagnostic mapping. Sign/zero categories below are engineering descriptions of stored values,
+ * not religious categories. Mood and interpersonal trust imply nothing about faith.
+ */
+import type { Person } from './types.ts';
+export interface QalbDescription {
+    facet: 'attention' | 'held-norm' | 'mood' | 'trust';
+    category: string;
+    /** Every description is attributed to this simulated person's records. */
+    personId: string;
+    text: string;
+    /** Detached identifiers and state paths, never mutable state objects or spiritual scores. */
+    evidence: string[];
+    sources: string[];
+}
+/**
+ * Plain English descriptions; no scalar summary, comparison or hidden update.
+ * Hosts must not present these records as spiritual health or a religious assessment.
+ */
+export declare function qalbReading(p: Person): QalbDescription[];

package/dist/qalb.js

@@ -0,0 +1,67 @@
+/**
+ * Plain English descriptions; no scalar summary, comparison or hidden update.
+ * Hosts must not present these records as spiritual health or a religious assessment.
+ */
+export function qalbReading(p) {
+    const sources = [
+        'research/reconciliation.md §2–4, §7; Q7 (22:46); H9 (Bukhari 52; Muslim 1599a)',
+        'research/islamic-foundations.md §2: Qalb',
+        'research/decisions.md: Qalb, nafs, fitra, ʿaql as state (2026-10-18)',
+    ];
+    const rows = [];
+    const add = (facet, category, text, evidence) => {
+        rows.push({ facet, category, personId: p.id, text, evidence, sources: [...sources] });
+    };
+    const memories = [...p.memory.episodes, ...(p.memory.gists ?? [])];
+    add('attention', memories.length ? 'retained-evidence' : 'no-retained-evidence', memories.length
+        ? 'Their memories retain some experiences. These do not show everything they noticed.'
+        : 'Their records contain no retained experiences. This does not show what they noticed.', memories.map((e) => `memory:${e.id}:${e.kind}`));
+    if (!p.conscience.norms.length)
+        add('held-norm', 'unrecorded', 'Their records contain no held rules.', ['conscience.norms']);
+    for (const n of p.conscience.norms) {
+        add('held-norm', n.conviction === 0 ? 'no-conviction' : 'held-understanding', n.conviction === 0
+            ? 'They have a recorded rule with no stated conviction.'
+            : 'They hold an understanding of this rule. This is their view.', [`norm:${n.normId}`, `standing:${n.standing}`, 'conscience.norms.conviction']);
+    }
+    add('mood', p.affect.mood.valence < 0 ? 'unpleasant' : p.affect.mood.valence > 0 ? 'pleasant' : 'neutral', p.affect.mood.valence < 0
+        ? 'Their recorded mood feels unpleasant.'
+        : p.affect.mood.valence > 0
+            ? 'Their recorded mood feels pleasant.'
+            : 'Their recorded mood feels neutral.', ['affect.mood.valence']);
+    add('mood', p.affect.mood.arousal === 0 ? 'no-arousal' : 'some-arousal', p.affect.mood.arousal === 0
+        ? 'Their recorded mood has no arousal.'
+        : 'Their recorded mood has some arousal.', ['affect.mood.arousal']);
+    // Keep stores distinct. Do not substitute relationship trust for source or advising-voice trust.
+    const ties = p.social.relationships.map((r) => ({
+        store: 'social.relationships',
+        id: r.otherId,
+        trust: r.trust,
+    }));
+    const voices = p.will.voices.map((v) => ({ store: 'will.voices', id: v.voiceId, trust: v.trust }));
+    const sourcesTrust = Object.entries(p.memory.sourceTrust).map(([id, trust]) => ({
+        store: 'memory.sourceTrust',
+        id,
+        trust,
+    }));
+    const trusts = [...ties, ...voices, ...sourcesTrust];
+    if (!trusts.length)
+        add('trust', 'unrecorded', 'Their records contain no learned trust.', [
+            'social.relationships',
+            'will.voices',
+            'memory.sourceTrust',
+        ]);
+    for (const t of trusts) {
+        // 0.5 is the numeric range midpoint, not a faith threshold or personal baseline.
+        const subject = t.store === 'social.relationships'
+            ? 'this person'
+            : t.store === 'will.voices'
+                ? 'this advising voice'
+                : 'this information source';
+        add('trust', t.trust < 0.5 ? 'below-midpoint' : t.trust > 0.5 ? 'above-midpoint' : 'at-midpoint', t.trust < 0.5
+            ? `Their trust in ${subject} is below the middle of its range.`
+            : t.trust > 0.5
+                ? `Their trust in ${subject} is above the middle of its range.`
+                : `Their trust in ${subject} is at the middle of its range.`, [`${t.store}:${t.id}`]);
+    }
+    return rows;
+}

package/dist/sim/sim.d.ts

@@ -245,7 +245,7 @@ export declare function birth(c: Community, a: Person, b: Person, spec: ChildSpe
 export declare function tellDeath(c: Community, dead: Person, at: Minute, opts?: {
     late?: 'throw' | 'now';
 }): void;
-/** Next minute at which this person needs attention. */
+/** Pure scheduling query, including passive bodily checkpoints during joint waiting. */
 export declare function nextEventAt(c: Community, p: Person): Minute;
 /**
  * How this person would answer `suggestion` now, without changing state (UI telegraph; wraps `predict`). Pass the