@adam0white/human-framework 2.21.0 → 2.22.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.22.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,7 +236,11 @@ 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
+
+`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. 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.
 
@@ -244,7 +248,7 @@ this policy.
 
 `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/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.22.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.22.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/person.d.ts

@@ -229,9 +229,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);
@@ -1346,10 +1347,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/types.d.ts

@@ -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/package.json

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