@adam0white/human-framework 2.19.0 → 2.20.0

package/README.md

@@ -529,3 +529,14 @@ wording, the generic fact sentence still includes that id so the claim is not hi
 Stock village outcomes, birth/marriage memories, routine fallbacks and generated
 community log details use the same per-person option. World-supplied outcome
 summaries and routine summaries remain exact.
+
+
+### Authored setup and explicit host effects
+
+Hosts may pass `habits: Habit[]` and `expectations: ActionExpectation[]` to `createPerson`. The framework copies records and their nested objects in order. Invalid or over-bound setup throws `RangeError`; omission preserves prior state. Duplicates remain authored records, with the existing matcher semantics.
+
+Use `gestureVoiceTrust(p, voiceId, amount, { reason, at?, action? })` for an explicit signed gesture toward an existing advising voice. It records the realized delta in bounded history and returns `undefined` for a missing voice. Reasons must be nonempty strings; optional action must be a string. Use `addTiredness(p, { sleepPressure?, exertion? })` for positive host-caused costs. Neither advances time or draws randomness. Host magnitudes are engineering premises.
+
+`confirmObservedReputation(p, prop, truth, now, table?)` replaces the manual `credence → confirm → applyReputationBelief` sequence. Supply only a fact the person could observe. It does not run attention or invent a moral judgement.
+
+`qalbReading(p)` is a read-only, sourced narration lens over existing records. Its detached categorical rows are this person's recorded understanding and evidence. They are never a spiritual health score, a ruling, a rank, or a decision input. Do not present mood, low social trust or missing memories as evidence of poor faith.

package/dist/body/body.d.ts

@@ -154,6 +154,16 @@ export declare function fastingDamping(b: Pick<BodyState, 'satiety' | 'hydration
  * fast: perceived hunger is damped (see SCOPE, N2b); true values, capacity and health are unchanged.
  */
 export declare function readBody(p: Person, params?: BodyParams, ctx?: BodyPerceptionContext): BodyReadout;
+/**
+ * SCOPE (host-caused tiredness): add nonnegative sleep-pressure and exertion costs, clamped to 0..1.
+ * The host supplies magnitudes; these are not calibrated claims. Absent, negative and non-finite costs
+ * do nothing. A dead body is unchanged, as with consume. Writes only these two body fields: no ticking,
+ * sleep transition, depletion, memory, RNG or other effects. Recovery remains with the existing body APIs.
+ */
+export declare function addTiredness(p: Person, costs: {
+    sleepPressure?: number;
+    exertion?: number;
+}): void;
 /** Eat, drink or take pain relief. `relief` lowers current pain; it then relaxes back toward its sources. */
 export declare function consume(p: Person, deltas: {
     food?: number;

package/dist/body/body.js

@@ -578,6 +578,21 @@ export function readBody(p, params = BODY_DEFAULTS, ctx) {
         },
     };
 }
+/**
+ * SCOPE (host-caused tiredness): add nonnegative sleep-pressure and exertion costs, clamped to 0..1.
+ * The host supplies magnitudes; these are not calibrated claims. Absent, negative and non-finite costs
+ * do nothing. A dead body is unchanged, as with consume. Writes only these two body fields: no ticking,
+ * sleep transition, depletion, memory, RNG or other effects. Recovery remains with the existing body APIs.
+ */
+export function addTiredness(p, costs) {
+    if (!p.body.alive)
+        return;
+    for (const key of ['sleepPressure', 'exertion']) {
+        const amount = costs[key];
+        if (amount !== undefined && Number.isFinite(amount) && amount > 0)
+            p.body[key] = clamp01(p.body[key] + amount);
+    }
+}
 /** Eat, drink or take pain relief. `relief` lowers current pain; it then relaxes back toward its sources. */
 export function consume(p, deltas) {
     const b = p.body;

package/dist/cognition/cognition.d.ts

@@ -1,3 +1,40 @@
+/**
+ * SCOPE: scoring of offered options. `consider` sums the utility terms listed in docs/framework.md
+ * ("Utility of an option"): need terms use the person's need urgencies times the gain they *believe* an
+ * option gives (the advertisement blended with learned expectation, times believed success); norm,
+ * commitment/goal, habit, emotion-tendency, social, effort, risk, material, precommitment and suggestion
+ * terms come from the owning faculties or from simple coefficient forms. Traits and values only scale
+ * terms. `decide` processes affordances in stable id order, scores them all and hands the list to `will`
+ * for vetoes and selection. Borrowed shapes: additive multi-attribute utility with a saturating money
+ * term (diminishing marginal value of material gain), prediction-error-adjusted action values
+ * (model-free cached values alongside the host's model-based advertisement). It does NOT claim calibrated
+ * weights, rational-choice optimality, or that a weighted sum exhausts human deliberation; every term is
+ * kept in the trace so the UI can show why.
+ *
+ * SCOPE (lane will+cognition, 2026-10-03): several voices add one `suggestion:<voiceId>` term each, with
+ * reactance summed into one `autonomy` term; remembered advice adds `suggestion:remembered:<source>` terms
+ * (see `rememberedTerms` and `will.rememberAdvice`). Scarcity (N13): a host-supplied 0..1 shortfall raises the
+ * weight of the material term, shrinks its saturation scale so small sums still count, and raises the
+ * `need:safety` term. Borrowed shapes: diminishing marginal utility of wealth (the same sum weighs more to
+ * someone who has less) and the scarcity account of Mullainathan & Shafir, where a shortfall captures
+ * attention and raises the felt value of the scarce resource. Neither source is catalogued in
+ * research/empirical-models.md yet; the coefficients are engineering defaults. It does not model the claimed
+ * cognitive cost of scarcity ("bandwidth tax"), debt itself (a host ledger plus commitments), or present
+ * bias; and because losses are amplified too, a host must carry the benefit of paying a debt (a commitment,
+ * an advertised `safety` gain) or paying looks only like a loss. The spec's "security need" is read as the
+ * `safety` need: `security` is a value, not a need, and no need is added.
+ *
+ * SCOPE (2.8.0, both additive): an offer naming `alongside` partners (people already taking that course) gets one
+ * `together:<id>` term per known, living partner, `togetherScale` × closeness, without belonging satiation: the
+ * pull is not to be left behind, which stays when the pair is together and belonging is full (The Rope's resting
+ * partner, 2026-10-18 reproduction: belonging terms near 0.01 against inertia of 0.07-0.15). Shape only, after
+ * joint commitment and the sense of commitment in joint action (Gilbert 1990; Michael and Pacherie 2015; cited unaudited, research/empirical-models.md §6b); it does
+ * not model who leads, negotiation, or obligations between the partners. With opt-in `body.fullness`, an offer
+ * that advertises food, water or relief while that need is past its comfort threshold gets `full:<need>` =
+ * -fullnessScale × gain × over²: eating or drinking when full is mildly unpleasant (negative alliesthesia, unaudited citation, Cabanac
+ * 1971), so idle choice stops cycling short consumption at full hydration (The Rope, owner Kestrel export
+ * 2026-10-19). It models no bladder, sensory-specific satiety by food, or overeating for comfort.
+ */
 import type { BodyPerceptionContext } from '../body/index.ts';
 import { type HabitContext } from '../habits/index.ts';
 import { type PromptingSeen } from '../promptings/index.ts';

package/dist/cognition/cognition.js

@@ -40,6 +40,7 @@ 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';
+import { keysOf } from '../core/keys.js';
 import { curiosityTerms } from '../curiosity/index.js';
 import { habitEase, habitPull } from '../habits/index.js';
 import { expectedEffect } from '../memory/index.js';
@@ -270,7 +271,7 @@ export function consider(p, aff, ctx) {
     };
     // Needs: urgency × believed gain × believed success.
     const expected = expectedEffect(p, aff);
-    for (const id of Object.keys(expected.needs)) {
+    for (const id of keysOf(expected.needs)) {
         const gain = expected.needs[id] ?? 0;
         if (gain === 0)
             continue;
@@ -296,7 +297,7 @@ export function consider(p, aff, ctx) {
         let relevance = 1;
         if (expected.valence > 0) {
             let served = -1;
-            for (const id of Object.keys(expected.needs))
+            for (const id of keysOf(expected.needs))
                 if ((expected.needs[id] ?? 0) > 0)
                     served = Math.max(served, urgencyOf(ctx.needs, id));
             if (served >= 0)

package/dist/core/index.d.ts

@@ -1,3 +1,4 @@
+export * from './keys.ts';
 export * from './libm.ts';
 export * from './math.ts';
 export * from './random.ts';

package/dist/core/index.js

@@ -1,3 +1,4 @@
+export * from './keys.js';
 export * from './libm.js';
 export * from './math.js';
 export * from './random.js';

package/dist/core/keys.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Own enumerable string keys of a typed record, in Object.keys order.
+ * Callers must supply records whose runtime keys match their declared key type.
+ * This only types enumeration; it does not sort, validate keys or change state.
+ */
+export declare function keysOf<K extends string>(record: Partial<Record<K, unknown>>): K[];

package/dist/core/keys.js

@@ -0,0 +1,8 @@
+/**
+ * Own enumerable string keys of a typed record, in Object.keys order.
+ * Callers must supply records whose runtime keys match their declared key type.
+ * This only types enumeration; it does not sort, validate keys or change state.
+ */
+export function keysOf(record) {
+    return Object.keys(record);
+}

package/dist/family/family.js

@@ -88,7 +88,7 @@ function sanitizeAptitudes(x) {
             out[k] = clamp(v, 0.25, 4);
     return Object.keys(out).length > 0 ? out : undefined;
 }
-/** Validate a saved family slice; undefined when nothing usable remains (used by `restore`). @internal */
+/** Validate a saved family slice; drop malformed pregnancies, keep usable fields. Undefined when none remain. @internal */
 export function sanitizeFamily(x) {
     if (!isObj(x))
         return undefined;
@@ -101,9 +101,9 @@ export function sanitizeFamily(x) {
     if (pg &&
         typeof pg === 'object' &&
         typeof pg.fatherId === 'string' &&
-        typeof pg.conceivedAt === 'number' &&
-        typeof pg.dueAt === 'number' &&
-        typeof pg.seed === 'number')
+        isNum(pg.conceivedAt) &&
+        isNum(pg.dueAt) &&
+        isNum(pg.seed))
         out.pregnancy = { fatherId: pg.fatherId, conceivedAt: pg.conceivedAt, dueAt: pg.dueAt, seed: pg.seed };
     if (isNum(f.attachment))
         out.attachment = clamp01(f.attachment);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.19.0";
+export declare const FRAMEWORK_VERSION = "2.20.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, MakeUpReceipt, PrayerCalendar, PrayerSchedule, PrayerTimes, Retimer, } from './agenda/index.ts';
@@ -28,6 +28,7 @@ export type { MigrationStep } from './migrate.ts';
 export { MIGRATIONS, migratableVersions, migrate } from './migrate.ts';
 export * from './narrate/index.ts';
 export * from './needs/index.ts';
+export { confirmObservedReputation } from './observed-reputation.ts';
 export * from './partnering/index.ts';
 export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistence/index.ts';
 export * from './person.ts';
@@ -38,6 +39,7 @@ export { adoptProjectTask, considerProjects, enableProjects, PROJECTS_DEFAULTS,
 export * from './promptings/index.ts';
 export type { ConsequenceEvidence, PlanRoute, PlanStep } from './prospection/index.ts';
 export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, enablePlanning, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, seedConsequences, } from './prospection/index.ts';
+export { type QalbDescription, qalbReading } from './qalb.ts';
 export { fingerprint, restore, snapshot } from './restore.ts';
 export * from './review/index.ts';
 export * from './scenarios/index.ts';

package/dist/index.js

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export const FRAMEWORK_VERSION = '2.19.0';
+export const FRAMEWORK_VERSION = '2.20.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);

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

@@ -27,13 +27,13 @@ import { ageCharacter, enableCharacterChange, noteCharacterDay, noteCharacterSoc
 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 +114,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 +192,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)
@@ -1399,7 +1480,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/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/social/social.js

@@ -471,6 +471,16 @@ export const REPUTATION_DEFAULTS = {
     /** First-hand familiarity damps hearsay: scale = 1 - familiarityDamping × familiarity. */
     familiarityDamping: 0.5,
 };
+/** Only authored, finite effects count; prototype properties are not character traits. */
+function reputationEffect(trait, table) {
+    const effect = Object.hasOwn(table, trait) ? table[trait] : undefined;
+    return effect &&
+        Number.isFinite(effect.affection) &&
+        Number.isFinite(effect.trust) &&
+        Number.isFinite(effect.respect)
+        ? effect
+        : undefined;
+}
 /** Splits a character proposition '<personId>:<trait>[:...]' into its subject and trait, if it is one. */
 export function parseTraitProp(prop, table = REPUTATION_TRAITS) {
     const parts = prop.split(':');
@@ -478,7 +488,7 @@ export function parseTraitProp(prop, table = REPUTATION_TRAITS) {
         return undefined;
     const personId = parts[0];
     const trait = parts[1];
-    if (personId === '' || table[trait] === undefined)
+    if (personId === '' || reputationEffect(trait, table) === undefined)
         return undefined;
     return { personId, trait };
 }
@@ -509,7 +519,7 @@ export function applyReputationBelief(p, prop, before, after, now, table = REPUT
 }
 /** Whether a character claim about a person is unfavourable to them (for backbiting tags). */
 export function isUnfavourableTrait(trait, value, table = REPUTATION_TRAITS) {
-    const e = table[trait];
+    const e = reputationEffect(trait, table);
     if (!e)
         return false;
     const sum = e.affection + e.trust + e.respect;

package/dist/types.d.ts

@@ -1509,6 +1509,10 @@ export interface PersonSpec {
     values?: Partial<Values>;
     norms?: HeldNorm[];
     skills?: Record<string, Unit>;
+    /** Authored habits, copied in order. Invalid or over-bound setup throws RangeError. */
+    habits?: Habit[];
+    /** Authored expectations, copied in order. Invalid or over-bound setup throws RangeError. */
+    expectations?: ActionExpectation[];
     body?: Partial<Omit<BodyState, 'injuries' | 'illnesses' | 'nextId'>>;
     needs?: Partial<NeedReservoirs>;
     relationships?: (Partial<Relationship> & {

package/dist/will/will.d.ts

@@ -233,6 +233,18 @@ export declare function noteVoicePromise(p: Person, voiceId: EntityId, event: {
     at?: Minute;
     action?: string;
 }): VoiceRelation;
+/**
+ * SCOPE (host trust gesture): add a host-supplied signed amount to an existing advising voice's trust,
+ * clamped to 0..1, and record the realized change in the usual bounded history. Magnitudes and reason
+ * are host premises, not calibrated claims. Missing voices return undefined without creating a voice.
+ * Non-finite amounts are ignored. No pressure, credit, counters, memory, time or RNG changes occur.
+ * Empty/non-string reasons and non-string actions reject before mutation with RangeError.
+ */
+export declare function gestureVoiceTrust(p: Person, voiceId: EntityId, amount: number, event: {
+    reason: string;
+    at?: Minute;
+    action?: string;
+}): VoiceRelation | undefined;
 /**
  * The next minute after `now` at which a pending commitment reaches `wakeCommitmentPressure`, the level at which a
  * sleeper may wake to serve it (the asleep veto lifts). The composite caps a sleeper's review there so a duty whose

package/dist/will/will.js

@@ -293,6 +293,27 @@ export function noteVoicePromise(p, voiceId, event) {
     noteTrust(v, v.trust - before, event.kept ? 'promise-kept' : 'promise-broken', at, event.action);
     return v;
 }
+/**
+ * SCOPE (host trust gesture): add a host-supplied signed amount to an existing advising voice's trust,
+ * clamped to 0..1, and record the realized change in the usual bounded history. Magnitudes and reason
+ * are host premises, not calibrated claims. Missing voices return undefined without creating a voice.
+ * Non-finite amounts are ignored. No pressure, credit, counters, memory, time or RNG changes occur.
+ * Empty/non-string reasons and non-string actions reject before mutation with RangeError.
+ */
+export function gestureVoiceTrust(p, voiceId, amount, event) {
+    if (!event || typeof event.reason !== 'string' || event.reason.length === 0)
+        throw new RangeError('A trust gesture needs a reason');
+    if (event.action !== undefined && typeof event.action !== 'string')
+        throw new RangeError('Invalid trust gesture action');
+    const v = voiceOf(p, voiceId);
+    if (!v || !Number.isFinite(amount))
+        return v;
+    const before = v.trust;
+    v.trust = clamp01(before + amount);
+    const at = event.at !== undefined && Number.isFinite(event.at) ? event.at : p.now;
+    noteTrust(v, v.trust - before, event.reason, at, event.action);
+    return v;
+}
 const finite = (x) => x === undefined || Number.isFinite(x);
 /** Host numbers the framework computes with must be finite; a NaN offer is vetoed, never chosen. */
 function wellFormed(aff) {

package/package.json

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