@adam0white/human-framework 2.18.0 → 2.20.0

package/README.md

@@ -489,3 +489,54 @@ const returnInput = advanceChapterClock(clock, 48 * 3_600_000);
 ```
 
 The host owns elapsed-time pacing, narrative interpretation, storage, consent and persona admission. A slot is an opportunity for coarse fiction. It is not proof of a lived day, settled duty, completed project or recovered body. Existing actor state and engine2.17.0 continuation remain unchanged unless the host explicitly uses the helper.
+
+
+## Plain English (2.19.0)
+
+Set `lexicon: { plainEnglish: true }` in `PersonSpec` for new people. Change an
+existing person's choice only through an explicit recorded host action. Do not
+overwrite a loaded run's saved choice. Built-in decision narration,
+spoken replies, intentions and person summaries then use complete, literal English.
+Keep this choice in the saved person and replay setup. It changes recorded prose.
+Without the option, legacy wording and continuation stay exact. Engine2.17.0 remains
+unchanged: this option changes presentation, not decisions or save structure.
+
+Host `lines`, `extend`, names and action forms still apply. A host phrase pack owns
+its own grammar. HF does not translate arbitrary host labels or memory summaries.
+Short words used inside templates remain phrases, so they compose grammatically.
+Pass the same lexicon to renderers without a Person, including chronicle renderers
+and label/reason readers.
+Use authored `actions` forms for domain actions that English cannot inflect from an id.
+
+Run `node packages/human/examples/plain-narration-control.ts` to compare legacy and
+plain replies without advancing the person's state or RNG.
+
+`labelLine(label, lexicon)` and `commitmentLabel(commitment, lexicon)` explain built-in
+prayer and purpose labels without changing stored identity keys. `normLabel(norm, lexicon)`
+explains selected built-in norm labels. `reasonLine(code, lexicon)` gives a sentence
+for a known reason; an unknown plain reason returns an empty string so a host can
+supply its own explanation. Without the option, each reader returns the legacy text.
+
+`promptingLine(..., { plainEnglish: true })` supports direct calls.
+`promptingsReading`, `reviewLine` and `bodyForecast` read the saved person's choice.
+A person’s held interpretation of a thought stays distinct from an observed response.
+Neither wording nor a missed-duty explanation changes obligations or excuses.
+
+For domain-specific conversation facts, supply `converse`'s `phrase` callback.
+HF cannot infer the English meaning of an opaque proposition id. Without authored
+wording, the generic fact sentence still includes that id so the claim is not hidden.
+
+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/agenda/agenda.d.ts

@@ -1,3 +1,50 @@
+/**
+ * SCOPE: The agenda holds a person's commitments (promises, duties, appointments, worship windows, jobs)
+ * and goals, turns them into utility terms, closes them when kept or broken, recurs periodic ones, and
+ * proposes spontaneous purposes when a psychological need goes unserved. Shapes borrowed: deadline
+ * pressure rising toward the end of a window (temporal-motivation style, monotone and saturating, not
+ * hyperbolic-discounting fitted values), SDT-style needs (belonging, competence, meaning) as the sources
+ * of spontaneous goals. Breaking a commitment is reported to the composite, which routes any linked norm
+ * through conscience; the agenda itself does not judge. It does not plan multi-step routes, model
+ * implementation intentions, or claim calibrated procrastination curves.
+ *
+ * SCOPE (abstention, lane agenda+conscience): an `abstain` commitment (a fast, e.g. "no work after the evening prayer") is kept by
+ * not completing any `violatedBy` action whose span overlaps the window, and broken by the first one that does.
+ * While open it pushes against violating options with a constant negative term (importance x held conviction);
+ * it does not rise with deadline pressure, because the cost of breaking does not grow toward the end. Shape:
+ * self-imposed restraint as a standing cost on the tempting option (precommitment, cf. Ariely & Wertenbroch 2002
+ * for the qualitative effect only; no fitted values). Interrupted outcomes do not break it (hosts report a
+ * partial meal as completed if it should). Exemptions (illness, travel) come from the norm catalog's
+ * `exemptions` with their provenance, release that day's instance and record an owed make-up; they are not the
+ * necessity exception of Qur'an 2:173. The illness threshold is an engineering stand-in for the person's own
+ * judgment that they are ill; the fidya provision of 2:184 and any expiation (kaffara) for deliberate breaking are
+ * not modelled (kaffara is disputed: research/fasting-sources.md §1). A deliberately broken obligatory fast is a
+ * breach and also leaves a make-up owed (1.7.0; research/decisions.md, fasting-sources.md §1: the day is made up).
+ * A break under necessity is excused with a make-up owed (see the necessity-break SCOPE below).
+ *
+ * SCOPE (missed duties and make-up debt, engine 1.7.0; research/decisions.md, research/capacity-and-excuse-sources.md):
+ * the sources keep blame (a breach) apart from debt (qada) (capacity-and-excuse-sources.md §0). When a `worship`
+ * window linked to a norm the person holds as obligatory closes unkept, or an obligatory `abstain` is broken, an
+ * `OwedMakeUp` is recorded in `agenda.owed` whatever the cause; what the cause decides is the blame:
+ * - Asleep throughout (§4: sleep lifts blame, not the debt): the window opened while the person was already
+ *   asleep and they woke no earlier than `wakeGrace` minutes before it closed (read from `body.since` and
+ *   `body.lastSleep`). Sleep begun inside the open window is not excused: whether the sleeper expected to wake is
+ *   not represented, so the framework takes the stricter reading.
+ * - Downed when it closed (§2, unconsciousness; `body.downed`, `body.lastDowned`): blame lifted, debt owed, but
+ *   once more than `lapseWaiver` (5) windows have closed within one downing, that stretch's debt drops and no more
+ *   is added (the Hanafi count by prayer times, kept as the default by decisions.md; Maliki and Shafi'i drop it
+ *   sooner, Hanbali never). Downing is involuntary, so going down after the window opened still excuses it.
+ * - Excused instances close `released` with `exempt.reason` 'sleep' or 'unconscious', so the composite books no
+ *   breach, distress or esteem cost; the chain recurs as for any exemption.
+ * - A mental break (`affect/crisis.ts`, reason intact) is not an excuse (§6: the test is retained capacity, and
+ *   motivation is irrelevant): the window closes broken, with its breach, and the debt is owed (reason 'missed').
+ * - Forgetting lifts blame in the sources (§4) but the framework has no state for having forgotten a duty, and no
+ *   state for loss of reason (junun, §1) or intoxication (§3); none of them is detected. Coercion and commands are
+ *   not excuses here (§7).
+ * A make-up commitment (`makeUpOf`, see `scheduleMakeUp`) that closes unkept, or is broken, carries no blame: qada
+ * has no fixed time in the sources, so it closes `released` and its debt is open again for the host to reschedule.
+ * The framework never computes whether a prayer or a make-up is accepted.
+ */
 import type { Affordance, AgendaState, Commitment, Episode, Goal, Minute, MissedExcuse, NeedId, NeedReading, NormDefinition, Outcome, OwedMakeUp, Person, PersonId, PsychologicalNeed, Term } from '../types.ts';
 export interface GoalTemplate {
     label: string;

package/dist/agenda/agenda.js

@@ -49,6 +49,7 @@
 import { DEFAULT_NORMS } from '../conscience/catalog.js';
 import { clamp01, dayOf, dpow, hasNumbers, isNum, isObj } from '../core/index.js';
 import { expectedEffect } from '../memory/index.js';
+import { labelLine } from '../presentation.js';
 import { diminishesProject } from '../projects/index.js';
 import { MINUTES_PER_DAY } from '../types.js';
 export const AGENDA_DEFAULTS = {
@@ -1015,7 +1016,9 @@ export function revisePurposes(p, now) {
             kind: 'abandoned',
             actorId: p.id,
             valence: -0.3 * g.baseImportance,
-            summary: `gave up on ${g.label}`,
+            summary: p.lexicon?.plainEnglish
+                ? `I stopped trying to reach this goal: ${labelLine(g.label, p.lexicon)}.`
+                : `gave up on ${g.label}`,
             tags: ['abandoned', 'goal', g.label, ...g.serves],
         });
     }

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/chronicle/story.js

@@ -8,6 +8,7 @@
  * activity. Lines report behaviour and stated relationships; they never grade devotion, worth or acceptance.
  */
 import { actionForms, capitalize, displayName, nameOf, phraseLine } from '../narrate/lexicon.js';
+import { labelLine } from '../presentation.js';
 /** Thresholds for `diffChronicle` (share of days). */
 export const STORY_DEFAULTS = {
     /** An item done unprompted on at least this share of days counts as done "without being told". */
@@ -97,7 +98,7 @@ function worshipActions(records) {
 }
 function formsOf(item, lex) {
     if (item.startsWith('prayer:')) {
-        const label = item.slice('prayer:'.length);
+        const label = labelLine(item.slice('prayer:'.length), lex);
         return {
             base: phraseLine('prayer.base', { label }, lex),
             past: phraseLine('prayer.past', { label }, lex),
@@ -138,7 +139,7 @@ export function narrateChronicle(chronicle, opts = {}) {
                     ? 'chronicle.prayer.one'
                     : 'chronicle.prayer.all'
                 : 'chronicle.prayer';
-        raw.push({ key, vars: { label, n, days } });
+        raw.push({ key, vars: { label: labelLine(label, lex), n, days } });
     }
     // Commitments kept by kind (worship is covered above).
     const kept = {};

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/conversation/conversation.js

@@ -244,9 +244,13 @@ export function converse(speaker, listener, ctx) {
             actorId: speaker.id,
             salience: round(0.3 + 0.4 * c.confidence),
             claims: [{ prop: c.prop, value: c.value, confidence: c.confidence }],
-            summary: c.about !== undefined
-                ? `${nameOf(speaker)} says ${c.about} is ${c.value ? '' : 'not '}${c.prop.split(':')[1] ?? ''}`
-                : `${nameOf(speaker)} says ${c.prop} is ${c.value ? 'so' : 'not so'}`,
+            summary: speaker.lexicon?.plainEnglish
+                ? c.about !== undefined
+                    ? `${nameOf(speaker)} says ${speaker.lexicon.names?.[c.about] ?? c.about} ${c.prop.split(':')[1] === 'owes' ? `${c.value ? 'owes' : 'does not owe'} money to ${speaker.lexicon.names?.[c.prop.split(':').slice(2).join(':')] ?? c.prop.split(':').slice(2).join(':')}` : `is ${c.value ? '' : 'not '}${c.prop.split(':')[1] ?? ''}`}.`
+                    : `${nameOf(speaker)} says this is ${c.value ? 'true' : 'false'}: ${c.prop}.`
+                : c.about !== undefined
+                    ? `${nameOf(speaker)} says ${c.about} is ${c.value ? '' : 'not '}${c.prop.split(':')[1] ?? ''}`
+                    : `${nameOf(speaker)} says ${c.prop} is ${c.value ? 'so' : 'not so'}`,
         };
         if (ctx.phrase)
             pc.summary = ctx.phrase(Object.freeze(structuredClone(c)), pc.summary ?? '');
@@ -293,7 +297,9 @@ export function converse(speaker, listener, ctx) {
             valence: 0.1,
             salience: round(0.4 + 0.3 * a.strength),
             claims: [{ prop: `advice:${a.action}`, value: true, confidence: round(a.cred) }],
-            summary: `${nameOf(speaker)} says I should ${a.action}`,
+            summary: speaker.lexicon?.plainEnglish
+                ? `${nameOf(speaker)} suggests this action: ${a.action.replace(/[-_]/g, ' ')}.`
+                : `${nameOf(speaker)} says I should ${a.action}`,
         };
         if (ctx.provenance) {
             const meta = beliefs.find((b) => b.prop === `${prefix}${a.action}`)?.provenance;

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);
@@ -215,7 +215,7 @@ export function deliver(mother, child, at = mother.now) {
         targetId: child.id,
         valence: 0.9,
         salience: 0.95,
-        summary: 'gave birth',
+        summary: mother.lexicon?.plainEnglish ? 'I gave birth.' : 'gave birth',
         tags: ['birth', 'family'],
     });
     return { id: child.id, name: child.name ?? child.id, seed: pg.seed, bornAt: at, fatherId: pg.fatherId };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.18.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,15 +28,18 @@ 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';
 export * from './persona.ts';
 export * from './persona-calendar.ts';
+export * from './presentation.ts';
 export { adoptProjectTask, considerProjects, enableProjects, PROJECTS_DEFAULTS, projectAppeal, } from './projects/index.ts';
 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.18.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,14 +25,17 @@ 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';
 export * from './persona.js';
 export * from './persona-calendar.js';
+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/longrun.js

@@ -108,7 +108,7 @@ export function routineDay(p, routine, opts = {}) {
                 action: a.action,
                 actorId: p.id,
                 valence: clampSigned(a.valence ?? 0),
-                summary: a.summary ?? a.action,
+                summary: a.summary ?? (p.lexicon?.plainEnglish ? `I completed the activity “${a.action}”.` : a.action),
                 tags: [...(a.tags ?? []), 'routine'],
             };
             if (companions[0] !== undefined)

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/narrate/lexicon.d.ts

@@ -1,6 +1,7 @@
 /**
  * SCOPE: keyed narration templates, host phrase packs and name/role lookup (N6). Every English sentence the
- * framework narrates lives in `EN_LINES` under a stable key; a host `Lexicon` replaces (`lines`) or extends
+ * framework narrates lives in `EN_LINES` under a stable key; `Lexicon.plainEnglish` selects the matching
+ * literal English pack while preserving default templates and host overrides. A host `Lexicon` replaces (`lines`) or extends
  * (`extend`) any key, names entities ("Ada") and maps relationship roles to nouns ("daughter") so narration
  * can say "my daughter" or "his daughter". Selection stays deterministic: a template is picked by an FNV hash of
  * a caller key (a decision id, a day index), never by the person's RNG. This is presentation only. It is

package/dist/narrate/lexicon.js

@@ -1,3 +1,4 @@
+import { PLAIN_EN_LINES } from './plain.js';
 /** FNV-1a 32-bit hash for deterministic template selection. */
 export function hashString(s) {
     let h = 0x811c9dc5;
@@ -264,7 +265,7 @@ export const EN_LINES = {
 };
 /** Templates for a key after the lexicon's replacements and extensions; empty when unknown. */
 export function linesFor(key, lex) {
-    const base = lex?.lines?.[key] ?? EN_LINES[key] ?? [];
+    const base = lex?.lines?.[key] ?? (lex?.plainEnglish ? PLAIN_EN_LINES[key] : undefined) ?? EN_LINES[key] ?? [];
     const more = lex?.extend?.[key];
     return more && more.length > 0 ? [...base, ...more] : base;
 }

package/dist/narrate/narrate.d.ts

@@ -1,5 +1,18 @@
+/**
+ * SCOPE: templated first-person language for decisions and suggestion verdicts, plus a short summary of a
+ * person for UI. Sentences are selected from keyed template sets (`EN_LINES`, overridable per key by a host
+ * `Lexicon`, N6) by a hash of the decision id, so the same record always narrates the same way without
+ * consuming the person's RNG. When memory shaped an option (the record's `recalled` episodes), the narration
+ * cites the episode summary. People are named through `nameOf` (lexicon name, role phrase, or id). This is
+ * presentation only: nothing here reads back into the simulation, and no claim is made that the templates
+ * reflect how people actually explain themselves. `Lexicon.plainEnglish` opts into sentence intentions
+ * and summaries; arbitrary host prose is not translated or grammatically inferred.
+ */
 import type { DecisionRecord, Episode, Lexicon, Person, SuggestionResolution } from '../types.ts';
-/** Intention string for a decision: 'for Allah', 'to feed myself', 'to keep my promise to X', ... */
+/**
+ * A plain intention is a sentence; legacy intentions remain phrases for existing hosts.
+ * Host-authored sentences pass through. This renderer never changes the record or RNG.
+ */
 export declare function intentionFor(p: Person, record: DecisionRecord, lexicon?: Lexicon): string;
 /** First-person narration of a decision record. Deterministic by the decision id. */
 export declare function narrateDecision(p: Person, record: DecisionRecord, lexicon?: Lexicon): string;