@adam0white/human-framework 2.17.0 → 2.19.0

package/README.md

@@ -476,3 +476,56 @@ Narration remains unchanged unless requested. Set `person.lexicon.variety`,
 `perceive` adds a third `{ reputationTraits }` argument. See the architecture's
 [narration and social host options](../../docs/framework.md#narration-and-social-host-options-opt-in)
 for cause-aware reviews and actor-addressed recall. These options change no default continuation.
+
+### Bounded chapter clock (2.18.0, opt-in)
+
+`createChapterClock(seed, nowMs)` and `advanceChapterClock(clock, nowMs)` are pure helpers for hosts that author coarse between-chapter life. They do not step a `Person`. The clock quantizes a supplied integer millisecond value into real-hour slots. A return processes at most the newest24 slots and reports the omitted count. Its watermark never moves backward. Repeating the same return produces no new slots. Each retained slot's draw depends only on its absolute slot and pinned seed.
+
+```ts
+const clock = createChapterClock(23, 0);
+const returnInput = advanceChapterClock(clock, 48 * 3_600_000);
+// returnInput.slots.length === 24; returnInput.skipped === 24
+// Pin clock, returned draws and the admitted initial host state in the replay.
+```
+
+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.

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/chapter-clock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Scope: pure, bounded host chapter scheduling from a supplied real-time clock. A slot is a coarse
+ * narrative opportunity, not a lived day. This helper touches no Person, resolves no obligations,
+ * and performs no body recovery. Hosts own fiction, persistence, admission and consent.
+ */
+export declare const CHAPTER_CLOCK: {
+    readonly version: 'hf-chapter-clock/1';
+    readonly quantumMs: 3600000;
+    readonly maxSlots: 24;
+};
+export interface ChapterClock {
+    version: 'hf-chapter-clock/1';
+    watermark: number;
+    seed: number;
+}
+export interface ChapterAdvance {
+    clock: ChapterClock;
+    slots: {
+        at: number;
+        draw: number;
+    }[];
+    skipped: number;
+}
+export declare function createChapterClock(seed: number, nowMs: number): ChapterClock;
+/** Stateless seeded draw per absolute slot: splitting returns does not alter a retained slot's result. */
+export declare function advanceChapterClock(clock: ChapterClock, nowMs: number): ChapterAdvance;

package/dist/chapter-clock.js

@@ -0,0 +1,36 @@
+/**
+ * Scope: pure, bounded host chapter scheduling from a supplied real-time clock. A slot is a coarse
+ * narrative opportunity, not a lived day. This helper touches no Person, resolves no obligations,
+ * and performs no body recovery. Hosts own fiction, persistence, admission and consent.
+ */
+export const CHAPTER_CLOCK = { version: 'hf-chapter-clock/1', quantumMs: 3_600_000, maxSlots: 24 };
+function slot(nowMs) {
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0)
+        throw new Error('Invalid chapter clock.');
+    return Math.floor(nowMs / CHAPTER_CLOCK.quantumMs);
+}
+export function createChapterClock(seed, nowMs) {
+    if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)
+        throw new Error('Invalid chapter seed.');
+    return { version: CHAPTER_CLOCK.version, watermark: slot(nowMs), seed };
+}
+/** Stateless seeded draw per absolute slot: splitting returns does not alter a retained slot's result. */
+export function advanceChapterClock(clock, nowMs) {
+    if (clock.version !== CHAPTER_CLOCK.version ||
+        !Number.isSafeInteger(clock.watermark) ||
+        clock.watermark < 0 ||
+        !Number.isInteger(clock.seed) ||
+        clock.seed < 0 ||
+        clock.seed > 0xffffffff)
+        throw new Error('Unsupported chapter clock.');
+    const end = Math.max(clock.watermark, slot(nowMs));
+    const count = Math.min(CHAPTER_CLOCK.maxSlots, end - clock.watermark);
+    const slots = Array.from({ length: count }, (_, i) => {
+        const at = end - count + i + 1;
+        let h = (clock.seed ^ (at >>> 0) ^ Math.floor(at / 0x100000000)) >>> 0;
+        h = Math.imul(h ^ (h >>> 16), 0x21f0aaad) >>> 0;
+        h = Math.imul(h ^ (h >>> 15), 0x735a2d97) >>> 0;
+        return { at, draw: ((h ^ (h >>> 15)) >>> 0) / 0x100000000 };
+    });
+    return { clock: { ...clock, watermark: end }, slots, skipped: end - clock.watermark - count };
+}

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

@@ -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,11 +1,12 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.17.0";
+export declare const FRAMEWORK_VERSION = "2.19.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';
 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.ts';
 export * from './beliefs/index.ts';
 export * from './body/index.ts';
+export * from './chapter-clock.ts';
 export * from './character/index.ts';
 export * from './chronicle/index.ts';
 export type { ConsiderContext, DecideContext, Decision, SocialContext } from './cognition/index.ts';
@@ -32,6 +33,7 @@ export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistenc
 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';

package/dist/index.js

@@ -1,10 +1,11 @@
 /** Human Framework public surface. */
-export const FRAMEWORK_VERSION = '2.17.0';
+export const FRAMEWORK_VERSION = '2.19.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';
 export * from './beliefs/index.js';
 export * from './body/index.js';
+export * from './chapter-clock.js';
 export * from './character/index.js';
 export * from './chronicle/index.js';
 // `cognition.decide` is the raw scorer; the composite's `decide` (person.ts) is the one hosts call.
@@ -29,6 +30,7 @@ export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistenc
 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';

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/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;

package/dist/narrate/narrate.js

@@ -5,23 +5,23 @@
  * 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.
+ * reflect how people actually explain themselves. `Lexicon.plainEnglish` opts into sentence intentions
+ * and summaries; arbitrary host prose is not translated or grammatically inferred.
  */
 import { NORM_SCOPE } from '../conscience/index.js';
+import { labelLine } from '../presentation.js';
 import { capitalize, linesFor, lowerFirst, nameOf, phraseLine, pickLine } from './lexicon.js';
 /**
  * Devotional intention: 'for Allah' for norms the built-in catalog scopes as religious, else 'for God'. The phrase
  * follows the norm, not the person (review 2026-10-03): a host whose people differ in faith overrides
  * `devotion.allah` / `devotion.god` per person through `Person.lexicon` (from `PersonSpec.lexicon`).
  */
-function devotion(p, normId, lex) {
+function devotion(p, normId, lex, say = phraseLine) {
     if (p.values.tradition < 0.6)
-        return normId === undefined
-            ? phraseLine('devotion.keep', {}, lex)
-            : phraseLine('intention.right', {}, lex);
+        return normId === undefined ? say('devotion.keep', {}, lex) : say('intention.right', {}, lex);
     if (normId !== undefined && NORM_SCOPE[normId] === 'religious')
-        return phraseLine('devotion.allah', {}, lex);
-    return phraseLine('devotion.god', {}, lex);
+        return say('devotion.allah', {}, lex);
+    return say('devotion.god', {}, lex);
 }
 const topTerm = (c) => {
     let best;
@@ -33,77 +33,108 @@ const topTerm = (c) => {
 /** Voices the narration addresses as "you" (the host's own voice); other voices are named when a lexicon names them. */
 const PLAYER_VOICES = new Set(['player', 'you']);
 /** Intention string for a decision: 'for Allah', 'to feed myself', 'to keep my promise to X', ... */
-export function intentionFor(p, record, lexicon) {
+function intentionPhrase(p, record, lexicon, selected) {
     const lex = lexicon ?? p.lexicon;
+    const say = (key, vars = {}, lex) => {
+        if (selected)
+            selected.key = key;
+        return phraseLine(key, vars, lex);
+    };
     const chosen = record.considered.find((c) => c.affordanceId === record.chosenAffordanceId);
     if (!chosen)
-        return phraseLine('intention.none', {}, lex);
+        return say('intention.none', {}, lex);
     if (record.suggestion?.verdict === 'complied')
-        return phraseLine('intention.complied', {}, lex);
+        return say('intention.complied', {}, lex);
     if (record.suggestion?.verdict === 'commanded')
-        return phraseLine('intention.commanded', {}, lex);
+        return say('intention.commanded', {}, lex);
     const top = topTerm(chosen);
     if (!top)
-        return phraseLine('intention.default', {}, lex);
+        return say('intention.default', {}, lex);
     const [kind, rest] = [top.source.split(':')[0] ?? '', top.source.slice(top.source.indexOf(':') + 1)];
     switch (kind) {
         case 'need':
             return linesFor(`intention:${rest}`, lex).length > 0
-                ? phraseLine(`intention:${rest}`, {}, lex)
-                : phraseLine('intention.need', { need: rest }, lex);
+                ? say(`intention:${rest}`, {}, lex)
+                : say('intention.need', { need: rest }, lex);
         case 'norm': {
             const tracked = p.agenda.commitments.some((c) => c.normId === rest && c.kind === 'worship');
             if (NORM_SCOPE[rest] === 'religious' || tracked)
-                return devotion(p, rest, lex);
-            return phraseLine('intention.right', {}, lex);
+                return devotion(p, rest, lex, say);
+            return say('intention.right', {}, lex);
         }
         case 'conscience':
-            return phraseLine(rest === 'repair' ? 'intention.repair' : 'intention.repent', {}, lex);
+            return say(rest === 'repair' ? 'intention.repair' : 'intention.repent', {}, lex);
         case 'commitment': {
             const c = p.agenda.commitments.find((x) => x.id === rest);
             if (c?.kind === 'worship')
                 return c.normId === undefined || p.values.tradition < 0.6
-                    ? devotion(p, undefined, lex)
-                    : devotion(p, c.normId, lex);
+                    ? devotion(p, undefined, lex, say)
+                    : devotion(p, c.normId, lex, say);
             if (c?.toId && c.toId !== 'self')
-                return phraseLine('intention.promiseTo', { who: nameOf(p, c.toId, lex) }, lex);
+                return say('intention.promiseTo', { who: nameOf(p, c.toId, lex) }, lex);
             // A host may phrase a labelled commitment its own way ('intention.label:suhoor' → "for suhoor").
             if (c?.label !== undefined && linesFor(`intention.label:${c.label}`, lex).length > 0)
-                return phraseLine(`intention.label:${c.label}`, {}, lex);
-            return phraseLine('intention.word', {}, lex);
+                return say(`intention.label:${c.label}`, {}, lex);
+            return say('intention.word', {}, lex);
         }
         case 'goal': {
             const g = p.agenda.goals.find((x) => x.id === rest);
             return g
-                ? phraseLine('intention.goal', { goal: g.label.replace(/-/g, ' ') }, lex)
-                : phraseLine('intention.goalFallback', {}, lex);
+                ? say('intention.goal', { goal: lex?.plainEnglish ? labelLine(g.label, lex) : g.label.replace(/-/g, ' ') }, lex)
+                : say('intention.goalFallback', {}, lex);
         }
         case 'social':
             return rest === 'group'
-                ? phraseLine('intention.group', {}, lex)
-                : phraseLine('intention.for', { who: nameOf(p, rest, lex) }, lex);
+                ? say('intention.group', {}, lex)
+                : say('intention.for', { who: nameOf(p, rest, lex) }, lex);
         case 'suggestion': {
             const voice = rest.startsWith('remembered:') ? rest.slice('remembered:'.length) : rest;
             if (lex?.names?.[voice] !== undefined && !PLAYER_VOICES.has(voice))
-                return phraseLine('intention.suggestionBy', { who: nameOf(p, voice, lex) }, lex);
-            return phraseLine('intention.suggestion', {}, lex);
+                return say('intention.suggestionBy', { who: nameOf(p, voice, lex) }, lex);
+            return say('intention.suggestion', {}, lex);
         }
         case 'habit':
-            return phraseLine('intention.habit', {}, lex);
+            return say('intention.habit', {}, lex);
         case 'emotion':
-            return phraseLine('intention.emotion', {}, lex);
+            return say('intention.emotion', {}, lex);
         case 'material':
             return lex?.materialMeaning !== undefined
-                ? phraseLine('intention.material.named', { material: lex.materialMeaning }, lex)
-                : phraseLine('intention.material', {}, lex);
+                ? say('intention.material.named', { material: lex.materialMeaning }, lex)
+                : say('intention.material', {}, lex);
         case 'precommit':
-            return phraseLine('intention.precommit', {}, lex);
+            return say('intention.precommit', {}, lex);
         case 'expectation':
-            return phraseLine('intention.expectation', {}, lex);
+            return say('intention.expectation', {}, lex);
         default:
-            return phraseLine('intention.default', {}, lex);
+            return say('intention.default', {}, lex);
     }
 }
+/**
+ * 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 function intentionFor(p, record, lexicon) {
+    const lex = lexicon ?? p.lexicon;
+    const selected = {};
+    const phrase = intentionPhrase(p, record, lex, selected);
+    if (selected.key !== undefined && lex?.lines?.[selected.key] !== undefined)
+        return phrase;
+    if (!lex?.plainEnglish || /[.!?]$/.test(phrase))
+        return phrase;
+    if (phrase === 'nothing to do')
+        return 'There is nothing for me to do.';
+    if (phrase === 'to earn')
+        return 'I want to earn money.';
+    if (phrase.startsWith('to '))
+        return `I want ${phrase}.`;
+    if (phrase.startsWith('because '))
+        return `I am doing this ${phrase}.`;
+    if (phrase.startsWith('for '))
+        return `I am doing this ${phrase}.`;
+    if (phrase === 'out of habit')
+        return 'I am doing this out of habit.';
+    return `My reason is ${phrase}.`;
+}
 function citeEpisode(p, ids, key, lex) {
     if (!ids || ids.length === 0)
         return undefined;
@@ -111,7 +142,7 @@ function citeEpisode(p, ids, key, lex) {
     if (!ep)
         return undefined;
     const summary = ep.summary.endsWith('.') ? ep.summary : `${ep.summary}.`;
-    return pickLine(ep.valence < 0 ? 'cite.bad' : 'cite.good', key, { summary: lowerFirst(summary) }, lex);
+    return pickLine(ep.valence < 0 ? 'cite.bad' : 'cite.good', key, { summary: lex?.plainEnglish ? summary : lowerFirst(summary) }, lex);
 }
 /** A rival within this fraction of the chosen utility makes the choice "a close call". */
 const CLOSE_CALL_FRACTION = 0.2;
@@ -212,13 +243,17 @@ export function voiceLine(p, res, key = res.reason, lexicon) {
         }
         case 'modified': {
             const alt = res.counterOffer?.label ?? phraseLine('voice.modified.default', {}, lex);
-            return pickLine('voice.modified', key, { alt: lowerFirst(alt) }, lex);
+            return pickLine('voice.modified', key, { alt: lex?.plainEnglish ? alt : lowerFirst(alt) }, lex);
         }
         case 'refused': {
             if (res.reason === 'distrust') {
                 const ep = res.episodeId ? p.memory.episodes.find((e) => e.id === res.episodeId) : undefined;
                 if (ep)
-                    return pickLine('voice.distrust.episode', key, { what: lowerFirst(ep.summary.replace(/\.$/, '')) }, lex);
+                    return pickLine('voice.distrust.episode', key, {
+                        what: lex?.plainEnglish
+                            ? ep.summary.replace(/[.!?]$/, '')
+                            : lowerFirst(ep.summary.replace(/\.$/, '')),
+                    }, lex);
                 return pickLine('voice.distrust', key, {}, lex);
             }
             if (res.kind === 'willNot' && res.commitmentId !== undefined) {
@@ -228,7 +263,7 @@ export function voiceLine(p, res, key = res.reason, lexicon) {
                     : duty?.label
                         ? duty.label
                         : phraseLine('voice.omission.default', {}, lex);
-                return pickLine('voice.omission', key, { what }, lex);
+                return pickLine('voice.omission', key, { what: labelLine(what, lex) }, lex);
             }
             if (res.kind === 'willNot' && res.reason.startsWith('duty:')) {
                 // An abstention held as a duty (the fast): the veto names what is being kept, not a forbidden act.
@@ -296,6 +331,13 @@ export function describePerson(p, lexicon) {
     const act = p.activity
         ? `${p.activity.action}${p.activity.targetId ? ` (${p.activity.targetId})` : ''}`
         : phraseLine('describe.idle', {}, lex);
+    if (lex?.plainEnglish) {
+        const state = bits.length > 0 ? bits.join(', ') : phraseLine('describe.well', {}, lex);
+        const activity = p.activity
+            ? `${p.name} is doing this: ${p.activity.affordance.label}${p.activity.targetId ? ` (${nameOf(p, p.activity.targetId, lex)})` : ''}.`
+            : `${p.name} is ${phraseLine('describe.idle', {}, lex)}.`;
+        return phraseLine('describe.line', { name: p.name, act: lex.lines?.['describe.line'] ? act : activity, state }, lex);
+    }
     const state = bits.length > 0 ? bits.join(', ') : phraseLine('describe.well', {}, lex);
     return phraseLine('describe.line', { name: p.name, act, state }, lex);
 }

package/dist/narrate/plain.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SCOPE: literal English narration for hosts that opt in to plain English. Keys, slot names,
+ * template counts and ordering match the legacy English pack, preserving deterministic selection.
+ * Internal word and intention slots remain phrases for composition. This pack changes presentation
+ * only; it does not change simulation state, choose templates, or rewrite host-authored text.
+ */
+export declare const PLAIN_EN_LINES: Readonly<Record<string, readonly string[]>>;