@adam0white/human-framework 2.21.0 → 2.23.0

package/README.md

@@ -222,7 +222,7 @@ reference host: `createVillage`.
 
 There are two version numbers, and they move independently.
 
-- **The release version** is the package version (`package.json`, currently `2.21.0`) and `FRAMEWORK_VERSION`, the same
+- **The release version** is the package version (`package.json`, currently `2.23.0`) and `FRAMEWORK_VERSION`, the same
   string compiled into the build; a test keeps them equal. It versions the public API under
   [semver](https://semver.org/): a breaking change to an exported name or signature bumps the major, a new
   faculty or export the minor, a fix the patch. Each release is a tag `vX.Y.Z` and a GitHub release whose notes
@@ -236,15 +236,19 @@ There are two version numbers, and they move independently.
 The root `package.json` version is the site's version (stamped into the site's `release.json`) and is not part of
 this policy.
 
-## Optional felt body (2.21 source candidate)
+## Observation and inherited aptitude
 
-`PersonSpec.enable.doze` accepts `{ posture: 'upright' | 'seated' | 'reclined', stimulation: number }`; `enableDoze` and `setDozeContext` are the explicit host calls. Doze onset is checked at integer-minute boundaries while awake. `readDoze` reports the current hazard; `nextDozeCheck` tells a manual host when to tick next. The opt-in costs one check per elapsed minute, including when onset gates are closed. It changes integration granularity, so enabled runs require a new replay pin. A dozed activity records `dozedAt`; the host resolves interrupted work. Doze does not wake spontaneously. `perceive` wakes only for a percept delivered at `p.now`, with `salience >= 0.8`, a heard/felt/social channel, detectable proximity (`near !== false`) and either `targetId === p.id` or `near === true`. The host must supply those alarms. These hazard and salience values are engineering constants.
+`observeSkill(p, skill, minutes, modelLevel, domain, { inheritedAptitude: true })` applies the person's existing inherited skill factor to observation. An attended `Percept.demonstrates` can declare the same flag. Only literal `true` enables it. Without it, watching keeps its previous rate, including for people whose saved family already has aptitudes. This adds no Person state or RNG draw and does not change direct practice. Save the host's observation inputs and pin the package when opting in.
+
+## Optional felt body (2.21 release)
+
+`PersonSpec.enable.doze` accepts `{ posture: 'upright' | 'seated' | 'reclined', stimulation: number }`; `enableDoze` and `setDozeContext` are the explicit host calls. Doze onset is checked at integer-minute boundaries while awake. `readDoze` reports the current hazard; `nextDozeCheck` tells a manual host when to tick next. The opt-in costs one check per elapsed minute, including when onset gates are closed. It changes integration granularity, so enabled runs require a new replay pin. A dozed activity records `dozedAt`; the host resolves interrupted work with `finish`. Until that call, `begin` refuses every replacement, including voluntary sleep and work chosen after waking. Doze does not wake spontaneously. `perceive` wakes for a delivered percept stamped within the current doze span through `p.now`, including an alarm that occurred between community checkpoints, with `salience >= 0.8`, a heard/felt/social channel, detectable proximity (`near !== false`) and either `targetId === p.id` or `near === true`. The host must supply those alarms. Other delivered percepts pass through ordinary bounded attention, as during voluntary sleep. These hazard and salience values are engineering constants.
 
 `estimateQuantity(p, { truth, difficulty })` is an explicit observation, not a display reader. Finite nonnegative truth and difficulty in `[0,1]` are required. A nonzero request consumes one draw from the person's saved seeded RNG; zero truth or zero difficulty returns truth with confidence 1 and consumes none. The result does not store a belief. Objective sleepiness widens its uniform error; perceived sleepiness determines confidence. Coefficients are engineering choices, not calibrated uncertainty intervals.
 
 `PersonSpec.enable.bladder` or `enableBladder(p)` starts a normalized fill store. `readBladder` returns true and perceived urgency, equal in this first slice. Water intake adds delayed fill and a small base rate fills it over time. A host marks a toilet `Affordance` with `voidsBladder: true` to add urgency-based choice value. Actual successful urination is separate: a completed `Outcome` with `voidedBladder: true` empties it; `voidBladder(p)` is the direct host operation. An interrupted or failed outcome does not empty it. For an offer that declares voiding, expectation learning treats completion without actual voiding as failure of that purpose. Do not use `needs.relief` as a substitute: that field reduces pain. Filling rates, threshold and choice weight are engineering constants. The model has no continence, automatic toilet search or automatic waking.
 
-With none of these options enabled or calls made, person state and seeded RNG continuation match HF 2.20.0 after normalizing the engine stamp only. HF 2.21.0 is library source here; the three site games still declare HF 2.20.0. Watch's adoption of `gestureVoiceTrust` and `addTiredness` uses the 2.20.0 helpers.
+With none of these options enabled or calls made, person state and seeded RNG continuation match HF 2.20.0 after normalizing the engine stamp only. The bodily options were introduced in HF 2.21.0. Site games pin their adopted package separately from the current library; upgrading the library does not enable these faculties or silently change game runtime.
 
 ## Long runs (2.0)
 

package/dist/body/doze.d.ts

@@ -8,13 +8,16 @@ export declare const DOZE_DEFAULTS: Readonly<{
 }>;
 /**
  * Enable involuntary doze without drawing RNG. Idempotent; off when absent.
- * Hosts must deliver current, detectable heard/felt/social alarms with salience >= 0.8
+ * Hosts must deliver detectable heard/felt/social alarms with salience >= 0.8
  * to this person (targetId, or near: true). There is no spontaneous wake: without such
- * percepts sleep continues. The community driver checks percepts on its ordinary idle cadence.
+ * percepts sleep continues. Alarm timestamps must be within the current doze span
+ * through p.now; delayed interval delivery can wake. Other delivered percepts still
+ * pass through ordinary bounded attention, as during voluntary sleep. The community driver checks percepts on its ordinary idle cadence.
  * Enabled tick integration uses one-minute boundaries even with closed gates or during sleep;
  * cost is O(elapsed minutes) and continuous state can differ from the absent opt-in arm.
  * Closed gates draw no onset RNG; passive community checkpoints do not call choice.
- * Activity.dozedAt pins stopped work until the host resolves it, even after an alarm;
+ * Activity.dozedAt pins stopped work until the host resolves it with finish, even after an alarm;
+ * begin refuses all replacements while that pin remains;
  * the pending interrupt reason may retain an earlier host/percept cause.
  */
 export declare function enableDoze(p: Person, input: DozeContext): void;

package/dist/body/doze.js

@@ -1,5 +1,5 @@
 /**
- * SCOPE: opt-in minute-grid involuntary onset and current urgent-percept waking. Cole 1989
+ * SCOPE: opt-in minute-grid involuntary onset and interval-delivered urgent-percept waking. Cole 1989
  * (PMID 2606843) supports posture context; auditory arousal studies (PMIDs 8776786,
  * 8153254) distinguish arousal from attention. None calibrates these engineering gates,
  * hazard weights or salience. No stages, inertia, spontaneous wake or clinical prediction.
@@ -24,13 +24,16 @@ function context(raw) {
 }
 /**
  * Enable involuntary doze without drawing RNG. Idempotent; off when absent.
- * Hosts must deliver current, detectable heard/felt/social alarms with salience >= 0.8
+ * Hosts must deliver detectable heard/felt/social alarms with salience >= 0.8
  * to this person (targetId, or near: true). There is no spontaneous wake: without such
- * percepts sleep continues. The community driver checks percepts on its ordinary idle cadence.
+ * percepts sleep continues. Alarm timestamps must be within the current doze span
+ * through p.now; delayed interval delivery can wake. Other delivered percepts still
+ * pass through ordinary bounded attention, as during voluntary sleep. The community driver checks percepts on its ordinary idle cadence.
  * Enabled tick integration uses one-minute boundaries even with closed gates or during sleep;
  * cost is O(elapsed minutes) and continuous state can differ from the absent opt-in arm.
  * Closed gates draw no onset RNG; passive community checkpoints do not call choice.
- * Activity.dozedAt pins stopped work until the host resolves it, even after an alarm;
+ * Activity.dozedAt pins stopped work until the host resolves it with finish, even after an alarm;
+ * begin refuses all replacements while that pin remains;
  * the pending interrupt reason may retain an earlier host/percept cause.
  */
 export function enableDoze(p, input) {

package/dist/conversation/conversation.d.ts

@@ -1,3 +1,44 @@
+/**
+ * SCOPE: one conversation turn between two people: what the speaker tells the listener, drawn from the
+ * speaker's own confident beliefs, and what advice they give, drawn from the speaker's beliefs about what the
+ * listener should do. Output is plain data: `told` percepts (testimony with claims at the speaker's credence)
+ * and advice percepts that the host delivers through the listener's `perceive`, a `Suggestion` per piece of
+ * advice for the listener's next decision, and social events for both sides. Reputation is nothing more than
+ * these claims spreading belief by belief (`social.applyReputationBelief` turns a changed character belief
+ * into a changed relationship).
+ *
+ * Choice of what to say is deterministic and explainable: each candidate claim gets a relevance score
+ * (confidence, recency, host topics, the speaker's feeling about its subject); an unfavourable claim about an
+ * absent third party is tagged with the catalog norm 'backbiting' (Qur'an 49:12, as catalogued in
+ * `conscience/catalog.ts`) and costs the speaker in proportion to their OWN held understanding of that norm and
+ * their honesty-humility, so a speaker who holds it firmly withholds it and one who does not tells it. The
+ * definition used here (an unfavourable character claim about someone not present) is an engineering
+ * assumption for the tag, not a ruling on what counts as backbiting. Deceit happens only when the host offers a
+ * temptation (the speaker gains if the listener believes something the speaker does not): temptation scales
+ * with (1 − honesty-humility) and is opposed by the speaker's held 'lying' norm. The lie is a host-visible flag
+ * (`ToldClaim.deceit`); the listener cannot see it. Named shapes: honesty-humility as the HEXACO factor most
+ * predictive of lower dishonesty (Hilbig & Zettler 2009; Heck et al. 2018 meta-analysis), gossip as a large
+ * share of conversation about absent third parties that spreads reputational information (Dunbar 2004), and
+ * extraversion as talkativeness (how many claims are offered).
+ *
+ * SCOPE (host options): `loyalWarning` admits only unfavourable listener claims when affection is at least
+ * 0.5 (an engineering threshold). `confidentMin` sets a per-call relay threshold. `phrase` renders selected
+ * testimony only; the host owns authored facts, delivery and subsequent disclosure. No hidden relay occurs.
+ *
+ * It does NOT generate language, model turn-taking, persuasion beyond source trust, what the speaker believes
+ * the listener already knows, lies of omission, white lies told to spare feelings, or the speaker's fear of
+ * being found out. Coefficients are engineering defaults, not calibrated estimates. Nothing here judges the
+ * worth of either person; norms are the people's own understandings with catalog provenance.
+ * Repetition (integration, 2026-10-03): a claim the listener already holds at the told confidence produces no
+ * percept (it is in `claims`, not `told`). A claim this listener already heard from this speaker, in the same
+ * direction, is dropped before the speaker chooses, so it is not even a deed. The speaker keeps no memory of what was said to whom; the listener's
+ * belief stands in for it.
+ *
+ * SCOPE (Word and witness, 2.10.0): `provenance: true` carries each claim's first known origin and opaque
+ * lineage into testimony. Missing provenance names the speaker as origin. Metadata changes neither claim
+ * selection nor repetition rules; the host still owns the relay graph and disclosure. It does not establish
+ * that an origin is truthful, expose deceit to the listener, or infer who else heard a claim.
+ */
 import { type TraitEffect } from '../social/index.ts';
 import type { EntityId, Minute, NormTag, Percept, Person, PersonId, SocialEvent, Suggestion, Unit } from '../types.ts';
 export declare const CONVERSATION_DEFAULTS: {

package/dist/conversation/conversation.js

@@ -40,6 +40,7 @@
  * that an origin is truthful, expose deceit to the listener, or infer who else heard a claim.
  */
 import { clamp01, expit, round } from '../core/index.js';
+import { nameOf as listenerNameOf } from '../narrate/lexicon.js';
 import { isDeceased, isUnfavourableTrait, parseTraitProp, REPUTATION_TRAITS, relationshipWith, } from '../social/index.js';
 import { MINUTES_PER_DAY } from '../types.js';
 export const CONVERSATION_DEFAULTS = {
@@ -244,10 +245,10 @@ 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: speaker.lexicon?.plainEnglish
+            summary: listener.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}.`
+                    ? `${listener.lexicon.names?.[speaker.id] ?? nameOf(speaker)} says ${listenerNameOf(listener, c.about)} ${c.prop.split(':')[1] === 'owes' ? `${c.value ? 'owes' : 'does not owe'} money to ${listenerNameOf(listener, c.prop.split(':').slice(2).join(':'))}` : `is ${c.value ? '' : 'not '}${c.prop.split(':')[1] ?? ''}`}.`
+                    : `${listener.lexicon.names?.[speaker.id] ?? 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'}`,
@@ -297,8 +298,8 @@ 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: speaker.lexicon?.plainEnglish
-                ? `${nameOf(speaker)} suggests this action: ${a.action.replace(/[-_]/g, ' ')}.`
+            summary: listener.lexicon?.plainEnglish
+                ? `${listener.lexicon.names?.[speaker.id] ?? nameOf(speaker)} suggests this action: ${a.action.replace(/[-_]/g, ' ')}.`
                 : `${nameOf(speaker)} says I should ${a.action}`,
         };
         if (ctx.provenance) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.21.0";
+export declare const FRAMEWORK_VERSION = "2.23.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';

package/dist/index.js

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

package/dist/migrate.js

@@ -41,6 +41,11 @@ function renameAmbient(json) {
 }
 /** The chain, keyed by the version each step upgrades from. */
 export const MIGRATIONS = {
+    '2.21.0': {
+        to: '2.23.0',
+        note: 'shape unchanged; doze delivery and plain narration fixes apply to opted-in runs',
+        apply: stamp,
+    },
     '2.17.0': {
         to: '2.21.0',
         note: 'doze and bladder state start absent; old callers retain their continuation',

package/dist/narrate/narrate.js

@@ -332,7 +332,9 @@ export function describePerson(p, lexicon) {
         ? `${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 state = bits.length > 1
+            ? `${bits.slice(0, -1).join(', ')} and ${bits.at(-1)}`
+            : (bits[0] ?? 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)}.`;

package/dist/observed-reputation.js

@@ -1,6 +1,6 @@
 /**
  * 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,
+ * Owns no state or formula. This host composition handles observed-trait correction: 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.

package/dist/person.d.ts

@@ -196,7 +196,11 @@ export interface BeginOptions {
     /** Joint-activity proposal id (set by `sim/` when both partners begin together). */
     jointId?: string;
 }
-/** Start an activity chosen by `record`. Returns null when the person is dead. */
+/**
+ * Start an activity chosen by `record`. Returns null when dead, or when dozed work
+ * is unresolved. Call `finish` for the stopped activity before starting any replacement,
+ * including voluntary sleep or an activity chosen after a waking percept.
+ */
 export declare function begin(p: Person, aff: Affordance, record: DecisionRecord, opts?: BeginOptions): Activity | null;
 /**
  * Push the review time forward after a decision to continue the current activity, refresh the cached
@@ -229,9 +233,13 @@ export declare function learningFor(p: Person, domain?: LearningDomain): number;
 /**
  * Watch someone practise skill `skill` at `modelLevel` for `minutes` (observational learning, 1.8.0): the
  * composite's side of `skills.learnByWatching` at the person's age-and-domain learning rate. A `Percept.demonstrates` on an
- * attended percept does the same. Returns the level before and after.
+ * attended percept does the same. `inheritedAptitude: true` applies the family's existing aptitude factor to
+ * watching. Absent or false keeps earlier observation learning, including for a person with an authored family.
+ * This changes no practice rule, draws no RNG, and stores no new state. Returns the level before and after.
  */
-export declare function observeSkill(p: Person, skill: string, minutes: number, modelLevel: Unit, domain?: LearningDomain): {
+export declare function observeSkill(p: Person, skill: string, minutes: number, modelLevel: Unit, domain?: LearningDomain, options?: {
+    inheritedAptitude?: boolean;
+}): {
     before: Unit;
     after: Unit;
 };

package/dist/person.js

@@ -748,7 +748,8 @@ function perceiveOne(p, pc, options) {
     // Watching someone skilled at work teaches a little (1.8.0, observational learning).
     const demo = pc.demonstrates;
     if (demo && !byMe && demo.minutes > 0) {
-        learnByWatching(p, demo.skill, demo.minutes, demo.level, learningFor(p, demo.domain), p.now);
+        const learning = learningFor(p, demo.domain);
+        learnByWatching(p, demo.skill, demo.minutes, demo.level, demo.inheritedAptitude === true ? learning * aptitudeOf(p, demo.skill) : learning, p.now);
     }
     // Relationships: interactions I took part in.
     const social = socialKindOf(pc.kind);
@@ -864,17 +865,18 @@ function judgeDeed(p, actor, pc, at) {
 export function perceive(p, percepts, options = {}) {
     if (percepts.length === 0 || !p.body.alive)
         return [];
-    if (p.body.doze?.since !== undefined) {
+    const dozeSince = p.body.doze?.since;
+    if (dozeSince !== undefined) {
         const wakes = percepts.some((pc) => Number.isFinite(pc.at) &&
-            pc.at === p.now &&
+            pc.at >= dozeSince &&
+            pc.at <= p.now &&
             Number.isFinite(pc.salience) &&
             pc.salience >= DOZE_DEFAULTS.wakeSalience &&
             pc.near !== false &&
             (pc.targetId === p.id || pc.near === true) &&
             (pc.channel === 'heard' || pc.channel === 'felt' || pc.channel === 'social'));
-        if (!wakes)
-            return [];
-        wakeDoze(p, p.now);
+        if (wakes)
+            wakeDoze(p, p.now);
     }
     const body = readBodyOf(p);
     const attended = attend(p, [...percepts], {
@@ -1169,9 +1171,13 @@ function thresholdFor(p, load, review) {
     const t = nextBodyThreshold(p, load, segmentModifiers(p), PERSON_DEFAULTS.interruptThresholds, review, p.ambient ? ambientBodyParams(p, BODY_DEFAULTS) : BODY_DEFAULTS, fastingCtx(p));
     return Number.isFinite(t) ? p.now + t : undefined;
 }
-/** Start an activity chosen by `record`. Returns null when the person is dead. */
+/**
+ * Start an activity chosen by `record`. Returns null when dead, or when dozed work
+ * is unresolved. Call `finish` for the stopped activity before starting any replacement,
+ * including voluntary sleep or an activity chosen after a waking percept.
+ */
 export function begin(p, aff, record, opts = {}) {
-    if (!p.body.alive)
+    if (!p.body.alive || p.activity?.dozedAt !== undefined)
         return null;
     if (p.body.doze?.since !== undefined && aff.mode !== 'sleep')
         return null;
@@ -1346,10 +1352,13 @@ export function learningFor(p, domain) {
 /**
  * Watch someone practise skill `skill` at `modelLevel` for `minutes` (observational learning, 1.8.0): the
  * composite's side of `skills.learnByWatching` at the person's age-and-domain learning rate. A `Percept.demonstrates` on an
- * attended percept does the same. Returns the level before and after.
+ * attended percept does the same. `inheritedAptitude: true` applies the family's existing aptitude factor to
+ * watching. Absent or false keeps earlier observation learning, including for a person with an authored family.
+ * This changes no practice rule, draws no RNG, and stores no new state. Returns the level before and after.
  */
-export function observeSkill(p, skill, minutes, modelLevel, domain) {
-    return learnByWatching(p, skill, minutes, modelLevel, learningFor(p, domain), p.now);
+export function observeSkill(p, skill, minutes, modelLevel, domain, options) {
+    const learning = learningFor(p, domain);
+    return learnByWatching(p, skill, minutes, modelLevel, options?.inheritedAptitude === true ? learning * aptitudeOf(p, skill) : learning, p.now);
 }
 /** Realized need changes, using readings captured before and after the outcome's deltas. */
 function realizedNeedDeltas(act, given, before, after) {

package/dist/persona.js

@@ -188,6 +188,7 @@ export function validatePersonaProjection(input) {
     keys(input.source, ['schema', 'engine', 'id', 'now']);
     // The 2.14.1 and 2.17.0 portable fields retain their semantics across the bodily opt-ins.
     const compatibleEngine = input.source.engine === ENGINE_VERSION ||
+        input.source.engine === '2.21.0' ||
         input.source.engine === '2.17.0' ||
         input.source.engine === '2.14.1';
     if (input.source.schema !== PERSON_SCHEMA || !compatibleEngine)

package/dist/presentation.js

@@ -68,6 +68,7 @@ export function reasonLine(reason, lexicon) {
         'need:water': 'I need to drink first.',
         'need:sleep': 'I need to sleep first.',
         'need:rest': 'I need to rest first.',
+        'need:bladder': 'I need to use the toilet first.',
         'need:survival': 'I need to meet an urgent bodily need first.',
     };
     if (Object.hasOwn(lines, reason))

package/dist/promptings/promptings.js

@@ -360,7 +360,7 @@ export function nafsPatterns(p, inputs) {
             ref: 'Qur’an 12:53',
             evident: assentedAgainstNorm.length > 0,
             evidence: p.lexicon?.plainEnglish
-                ? `The person acted on ${assentedAgainstNorm.length} recent urges despite a rule they hold.`
+                ? `The person acted on ${assentedAgainstNorm.length} recent ${assentedAgainstNorm.length === 1 ? 'urge' : 'urges'} despite a rule they hold.`
                 : `${assentedAgainstNorm.length} recent prompts followed against a held norm`,
         },
         {
@@ -376,7 +376,7 @@ export function nafsPatterns(p, inputs) {
             ref: 'Qur’an 89:27',
             evident: letPass > 0 && assentedAgainstNorm.length === 0 && !reproach,
             evidence: p.lexicon?.plainEnglish
-                ? `${letPass} recent urges passed without action. ${assentedAgainstNorm.length} were acted on against a held rule. Current guilt or unresolved breach: ${reproach ? 'yes' : 'no'}.`
+                ? `${letPass} recent ${letPass === 1 ? 'urge' : 'urges'} passed without action. ${assentedAgainstNorm.length} ${assentedAgainstNorm.length === 1 ? 'was' : 'were'} acted on against a held rule. Current guilt or unresolved breach: ${reproach ? 'yes' : 'no'}.`
                 : `${letPass} recent prompts let pass, none followed against a norm, no felt reproach`,
         },
     ];

package/dist/qalb.d.ts

@@ -1,15 +1,3 @@
-/**
- * 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';

package/dist/qalb.js

@@ -1,3 +1,18 @@
+/**
+ * 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 { DEFAULT_NORMS } from './conscience/catalog.js';
+import { nameOf } from './narrate/lexicon.js';
+import { normLabel } from './presentation.js';
 /**
  * Plain English descriptions; no scalar summary, comparison or hidden update.
  * Hosts must not present these records as spiritual health or a religious assessment.
@@ -19,18 +34,17 @@ export function qalbReading(p) {
     if (!p.conscience.norms.length)
         add('held-norm', 'unrecorded', 'Their records contain no held rules.', ['conscience.norms']);
     for (const n of p.conscience.norms) {
+        const rule = normLabel(DEFAULT_NORMS.find((rule) => rule.id === n.normId) ?? { id: n.normId, label: n.normId }, { ...p.lexicon, plainEnglish: true });
         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']);
+            ? `They have a recorded rule, “${rule}”, with no stated conviction.`
+            : `They hold an understanding of the rule “${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']);
+    add('mood', p.affect.mood.arousal === 0 ? 'no-arousal' : 'some-arousal', p.affect.mood.arousal === 0 ? 'Their recorded mood is calm.' : 'Their recorded mood is stirred.', ['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',
@@ -53,10 +67,10 @@ export function qalbReading(p) {
     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'
+            ? `the person ${nameOf(p, t.id)}`
             : t.store === 'will.voices'
-                ? 'this advising voice'
-                : 'this information source';
+                ? `the advising voice ${nameOf(p, t.id)}`
+                : `the information source ${nameOf(p, t.id)}`;
         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

package/dist/sim/sim.js

@@ -840,10 +840,15 @@ export function stepCommunity(c, world, until, opts = {}) {
                     at: t,
                     personId: p.id,
                     kind: 'finish',
-                    detail: `${act.action} interrupted by doze`,
+                    detail: outcome.summary ??
+                        (p.lexicon?.plainEnglish
+                            ? `${p.name} stopped the task “${act.affordance.label}” because they dozed off.`
+                            : `${act.action} interrupted by doze`),
+                    decisionId: act.decisionId,
+                    affordanceId: act.affordanceId,
                     action: act.action,
                     status: outcome.status,
-                });
+                }, outcome.summary !== undefined);
             }
             c.idleUntil[p.id] = t + quantum;
             if (!ordinaryDue)
@@ -995,12 +1000,12 @@ export function stepCommunity(c, world, until, opts = {}) {
                 detail: p.lexicon?.plainEnglish
                     ? proposal.status === 'declined'
                         ? `The shared task “${chosen.label}” could not start because a partner was unavailable.`
-                        : `${chosen.label} with ${proposal.partnerIds.map((id) => personById(c, id)?.name ?? id).join(', ')}`
+                        : `${p.name} proposed the shared task “${chosen.label}” with ${proposal.partnerIds.map((id) => personById(c, id)?.name ?? id).join(', ')}.`
                     : `${chosen.label} with ${proposal.partnerIds.join(', ')}`,
                 affordanceId: chosen.id,
                 action: chosen.action,
                 jointId: proposal.id,
-            }, Boolean(p.lexicon?.plainEnglish && proposal.status === 'declined'));
+            }, Boolean(p.lexicon?.plainEnglish));
             continue;
         }
         if (act) {

package/dist/tick-input.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SCOPE: opt-in host input ordering for one declared logical tick. Waits for the
+ * caller's complete expected identity set, then sorts by sender and sequence.
+ * Lexical sender priority is deterministic host policy, not fairness or
+ * consensus. For conflicting same-voice requests, earlier senders take priority.
+ * Owns no Person, clock, queue or RNG state. Does not supply transport, consensus,
+ * payload validation, retries or snapshot storage. Payloads remain caller-owned;
+ * hosts must agree on their meaning and save pending input alongside host state.
+ */
+export interface TickInputKey {
+    sender: string;
+    sequence: number;
+}
+export interface TickInput<T> extends TickInputKey {
+    tick: number;
+    payload: T;
+}
+/**
+ * Returns undefined while a declared input is missing. Unexpected, duplicate or
+ * wrong-tick inputs throw. An empty expected set is a complete barrier. This
+ * reader never mutates input arrays or envelopes and never reads payload fields.
+ * Call only when explicitly opting into this host scheduling convention.
+ */
+export declare function canonicalTickInputs<T>(tick: number, inputs: readonly TickInput<T>[], expected: readonly TickInputKey[]): TickInput<T>[] | undefined;

package/dist/tick-input.js

@@ -0,0 +1,56 @@
+const MAX_INPUTS = 256;
+function identity(key) {
+    if (typeof key.sender !== 'string' ||
+        key.sender.length === 0 ||
+        key.sender.length > 128 ||
+        !Number.isSafeInteger(key.sequence) ||
+        key.sequence < 0) {
+        throw new Error('Invalid tick input identity');
+    }
+    return JSON.stringify([key.sender, key.sequence]);
+}
+/**
+ * Returns undefined while a declared input is missing. Unexpected, duplicate or
+ * wrong-tick inputs throw. An empty expected set is a complete barrier. This
+ * reader never mutates input arrays or envelopes and never reads payload fields.
+ * Call only when explicitly opting into this host scheduling convention.
+ */
+export function canonicalTickInputs(tick, inputs, expected) {
+    if (!Number.isSafeInteger(tick) || tick < 0)
+        throw new Error('Invalid logical tick');
+    if (inputs.length > MAX_INPUTS || expected.length > MAX_INPUTS) {
+        throw new Error('Tick input limit exceeded');
+    }
+    const wanted = new Set();
+    for (const key of expected) {
+        const id = identity(key);
+        if (wanted.has(id))
+            throw new Error('Duplicate expected tick input');
+        wanted.add(id);
+    }
+    const received = new Set();
+    for (const input of inputs) {
+        const id = identity(input);
+        if (input.tick !== tick)
+            throw new Error('Input belongs to another tick');
+        if (!wanted.has(id))
+            throw new Error('Unexpected tick input');
+        if (received.has(id))
+            throw new Error('Duplicate tick input');
+        received.add(id);
+    }
+    if (received.size !== wanted.size)
+        return undefined;
+    return inputs
+        .map((input) => ({
+        tick: input.tick,
+        sender: input.sender,
+        sequence: input.sequence,
+        payload: input.payload,
+    }))
+        .sort((a, b) => {
+        if (a.sender !== b.sender)
+            return a.sender < b.sender ? -1 : 1;
+        return a.sequence - b.sequence;
+    });
+}

package/dist/types.d.ts

@@ -915,7 +915,7 @@ export declare const PERSON_SCHEMA = "human/person@1";
  * and an activity that would cover a closing stretch is reviewed when the stretch begins (`isUnderWay`,
  * `dutyReviewAt`). Person shape unchanged.
  */
-export declare const ENGINE_VERSION = "2.21.0";
+export declare const ENGINE_VERSION = "2.23.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1301,6 +1301,8 @@ export interface Percept {
         level: Unit;
         minutes: number;
         domain?: LearningDomain;
+        /** Apply the watcher's inherited skill aptitude. Absent keeps earlier observation learning exactly. */
+        inheritedAptitude?: boolean;
     };
     /** At most four additions/withdrawals combined; attended external testimony to this person or a broadcast. */
     consequences?: readonly ReceivedConsequence[];

package/dist/types.js

@@ -120,4 +120,4 @@ export const PERSON_SCHEMA = 'human/person@1';
  * and an activity that would cover a closing stretch is reviewed when the stretch begins (`isUnderWay`,
  * `dutyReviewAt`). Person shape unchanged.
  */
-export const ENGINE_VERSION = '2.21.0';
+export const ENGINE_VERSION = '2.23.0';

package/package.json

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