@adam0white/human-framework 2.20.0 → 2.21.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`, now `2.14.1`) and `FRAMEWORK_VERSION`, the same
+- **The release version** is the package version (`package.json`, currently `2.21.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,6 +236,16 @@ 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)
+
+`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.
+
+`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.
+
 ## Long runs (2.0)
 
 HF 2.0 adds what a life over decades needs. Each faculty is opt-in or absent until used, so a host that uses none

package/dist/body/bladder.d.ts

@@ -0,0 +1,21 @@
+import type { Affordance, Person } from '../types.ts';
+export declare const BLADDER_DEFAULTS: Readonly<{
+    intakeScale: 0.5;
+    maxPending: 4;
+    halfLife: 45;
+    basePerMinute: 0.001;
+    /** Frozen engineering default, not a clinical threshold or fitted choice result. */
+    choiceThreshold: 0.35;
+    /** Frozen engineering weight on perceived urgency above the threshold. */
+    choiceScale: 4;
+}>;
+export declare function enableBladder(p: Person): void;
+/** Pure host readout; equal perceived urgency is a first-slice assumption. */
+export declare function readBladder(p: Person): {
+    urgency: number;
+    perceived: number;
+} | undefined;
+/** Pure opt-in choice contribution; a declared offer says nothing about actual success. */
+export declare function bladderMotivation(p: Person, offer: Affordance, believedSuccess: number): number;
+/** Host calls only after successful urination. Pending intake remains. */
+export declare function voidBladder(p: Person): boolean;

package/dist/body/bladder.js

@@ -0,0 +1,64 @@
+/**
+ * SCOPE: opt-in normalized storage and delayed water intake; hosts resolve actual voiding.
+ * NIDDK, The Urinary Tract & How It Works supports production/storage/urination, not these
+ * engineering rates. Base filling is independent of hydration, including dehydration.
+ * Urgency and perceived urgency are equal in this slice; hosts supply toilet choices. It models no renal calibration, continence, injury, search for a toilet or automatic waking.
+ */
+import { clamp01, dexp, isNum, isObj } from '../core/index.js';
+export const BLADDER_DEFAULTS = Object.freeze({
+    intakeScale: 0.5,
+    maxPending: 4,
+    halfLife: 45,
+    basePerMinute: 0.001,
+    /** Frozen engineering default, not a clinical threshold or fitted choice result. */
+    choiceThreshold: 0.35,
+    /** Frozen engineering weight on perceived urgency above the threshold. */
+    choiceScale: 4,
+});
+export function enableBladder(p) {
+    p.body.bladder ??= { fill: 0, pending: 0 };
+}
+/** Pure host readout; equal perceived urgency is a first-slice assumption. */
+export function readBladder(p) {
+    const b = p.body.bladder;
+    return b ? { urgency: b.fill, perceived: b.fill } : undefined;
+}
+/** Pure opt-in choice contribution; a declared offer says nothing about actual success. */
+export function bladderMotivation(p, offer, believedSuccess) {
+    if (offer.voidsBladder !== true)
+        return 0;
+    const perceived = readBladder(p)?.perceived;
+    if (perceived === undefined)
+        return 0;
+    return (BLADDER_DEFAULTS.choiceScale *
+        clamp01((perceived - BLADDER_DEFAULTS.choiceThreshold) / (1 - BLADDER_DEFAULTS.choiceThreshold)) *
+        clamp01(believedSuccess));
+}
+/** Host calls only after successful urination. Pending intake remains. */
+export function voidBladder(p) {
+    if (!p.body.bladder || !p.body.alive || p.body.asleep)
+        return false;
+    p.body.bladder.fill = 0;
+    return true;
+}
+/** @internal */
+export function intakeBladder(p, water) {
+    const b = p.body.bladder;
+    if (b && isNum(water) && water > 0)
+        b.pending = Math.min(BLADDER_DEFAULTS.maxPending, b.pending + BLADDER_DEFAULTS.intakeScale * clamp01(water));
+}
+/** @internal */
+export function advanceBladder(b, dt) {
+    const remaining = b.pending * dexp((-Math.LN2 * dt) / BLADDER_DEFAULTS.halfLife);
+    b.fill = clamp01(b.fill + BLADDER_DEFAULTS.basePerMinute * dt + b.pending - remaining);
+    b.pending = remaining;
+}
+/** @internal */
+export function sanitizeBladder(raw) {
+    if (!isObj(raw) || !isNum(raw.fill) || !isNum(raw.pending))
+        return undefined;
+    return {
+        fill: clamp01(raw.fill),
+        pending: Math.min(BLADDER_DEFAULTS.maxPending, Math.max(0, raw.pending)),
+    };
+}

package/dist/body/body.js

@@ -8,7 +8,7 @@
  * and is under-perceived (cumulative-cost-of-wakefulness pattern, Van Dongen et al. 2003). Satiety and
  * hydration fall linearly with metabolic rate and effort. Fitness relaxes exponentially toward a training
  * target or a detraining floor. All rates are engineering defaults; none is a calibrated physiological
- * prediction. Not modelled: bladder, temperature, specific nutrients, endocrine and immune detail,
+ * prediction. Not modelled: temperature, specific nutrients, endocrine and immune detail,
  * stress physiology, and masking of hunger or pain by emotion or focus (that belongs to other faculties).
  * `advanceBody` integrates in deterministic sub-steps of at most 15 minutes, using the exact solution
  * within each sub-step where the dynamics are linear, so one long step matches many short ones closely.
@@ -44,6 +44,8 @@
  */
 import { chance, clamp, clamp01, dcos, decay, dexp, dlog, hasNumbers, isNum, isObj, minuteOfDay, smoothstep, } from '../core/index.js';
 import { MINUTES_PER_DAY, MINUTES_PER_YEAR } from '../types.js';
+import { advanceBladder, intakeBladder, sanitizeBladder } from './bladder.js';
+import { sanitizeDoze } from './doze.js';
 import { bleedStep, INJURY_DEFAULTS } from './injury.js';
 export const BODY_DEFAULTS = {
     maxSubStep: 15,
@@ -218,6 +220,20 @@ export function sanitizeExposures(input, now) {
  * downing are checked by `sanitizeInjuries`. A save the engine wrote is unchanged. @internal
  */
 export function sanitizeBody(b, now) {
+    if (b.doze !== undefined) {
+        const d = sanitizeDoze(b.doze, b, now);
+        if (d)
+            b.doze = d;
+        else
+            delete b.doze;
+    }
+    if (b.bladder !== undefined) {
+        const bladder = sanitizeBladder(b.bladder);
+        if (bladder)
+            b.bladder = bladder;
+        else
+            delete b.bladder;
+    }
     if (b.rates !== undefined) {
         const rates = sanitizeRates(b.rates);
         if (rates)
@@ -304,6 +320,8 @@ export function createBody(init, now) {
         illnesses: [],
         nextId: 0,
     };
+    delete b.doze;
+    delete b.bladder;
     b.satiety = clamp01(b.satiety);
     b.hydration = clamp01(b.hydration);
     b.sleepPressure = clamp01(b.sleepPressure);
@@ -486,7 +504,7 @@ export function advanceBody(p, dt, load, mods, params = BODY_DEFAULTS) {
     const b = p.body;
     if (!b.alive)
         return;
-    const wantAsleep = load.mode === 'sleep';
+    const wantAsleep = load.mode === 'sleep' || b.doze?.since !== undefined;
     if (wantAsleep !== b.asleep) {
         if (b.asleep)
             b.lastSleep = { from: b.since, to: p.now };
@@ -497,8 +515,15 @@ export function advanceBody(p, dt, load, mods, params = BODY_DEFAULTS) {
         return;
     const n = Math.ceil(dt / params.maxSubStep);
     const h = dt / n;
-    for (let i = 0; i < n && b.alive; i++)
+    for (let i = 0; i < n && b.alive; i++) {
+        if (b.bladder)
+            advanceBladder(b.bladder, h);
         subStep(b, h, load, mods, params);
+    }
+    if (!b.alive && b.doze?.since !== undefined) {
+        delete b.doze.since;
+        b.asleep = false;
+    }
 }
 /** Circadian alertness 0..1 (Process C): cosine peaking at `circadianPeak`, trough 12 h earlier, post-lunch dip. */
 export function circadianAlertness(now, circadianPeak) {
@@ -598,6 +623,7 @@ export function consume(p, deltas) {
     const b = p.body;
     if (!b.alive)
         return;
+    intakeBladder(p, deltas.water);
     if (deltas.food)
         b.satiety = clamp01(b.satiety + deltas.food);
     if (deltas.water)
@@ -617,6 +643,8 @@ function freshId(b, prefix, now) {
  */
 export function skipBody(p, to) {
     p.body.since = to;
+    if (p.body.doze?.since !== undefined)
+        p.body.doze.since = to;
 }
 /**
  * The body-owned death setter for host-rolled deaths (`lifecourse.mortalityEvent`): health 0, not alive, awake.
@@ -629,6 +657,8 @@ export function die(p) {
     b.alive = false;
     b.health = 0;
     b.asleep = false;
+    if (b.doze)
+        delete b.doze.since;
     b.since = p.now;
 }
 export function injure(p, injury) {
@@ -761,6 +791,10 @@ const cloneBody = (b) => {
             ex[k] = { ...e };
         out.exposures = ex;
     }
+    if (b.doze)
+        out.doze = { ...b.doze, context: { ...b.doze.context } };
+    if (b.bladder)
+        out.bladder = { ...b.bladder };
     if (b.rates)
         out.rates = { ...b.rates };
     if (b.downed)
@@ -793,6 +827,8 @@ export function nextBodyThreshold(p, load, mods, thresholds = { hunger: 0.7, thi
         return watch.some((k) => r[k] >= thresholds[k]);
     };
     const sim = { ...p, body: cloneBody(p.body) };
+    if (sim.body.doze)
+        delete sim.body.doze.since;
     advanceBody(sim, 0, load, mods, params); // apply mode change
     const coarse = 30;
     let t = 0;
@@ -823,6 +859,8 @@ export function nextBodyThreshold(p, load, mods, thresholds = { hunger: 0.7, thi
 export function forecastBody(p, spans, mods, params = BODY_DEFAULTS, step = 30, perception) {
     const out = [];
     const sim = { ...p, body: cloneBody(p.body) };
+    if (sim.body.doze)
+        delete sim.body.doze.since;
     for (const s of spans) {
         const span = { label: s.label, endsAt: sim.now, worst: 0, worstOf: 'fatigue' };
         // Hard internal cap (a week) so a hostile span cannot stall a decision.

package/dist/body/doze.d.ts

@@ -0,0 +1,28 @@
+import type { DozeContext, Person } from '../types.ts';
+export declare const DOZE_DEFAULTS: Readonly<{
+    sleepiness: 0.75;
+    stimulation: 0.5;
+    hazard: 0.08;
+    seatedWeight: 0.5;
+    wakeSalience: 0.8;
+}>;
+/**
+ * Enable involuntary doze without drawing RNG. Idempotent; off when absent.
+ * Hosts must deliver current, 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.
+ * 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;
+ * the pending interrupt reason may retain an earlier host/percept cause.
+ */
+export declare function enableDoze(p: Person, input: DozeContext): void;
+export declare function setDozeContext(p: Person, input: DozeContext): void;
+/** Pure; closed onset gates still require the next checkpoint. */
+export declare function nextDozeCheck(p: Person): number;
+/** Pure truth/debug reader, not a first-person lens. */
+export declare function readDoze(p: Person): {
+    asleep: boolean;
+    hazardPerMinute: number;
+} | undefined;

package/dist/body/doze.js

@@ -0,0 +1,114 @@
+/**
+ * SCOPE: opt-in minute-grid involuntary onset and current 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.
+ * Manual hosts schedule nextDozeCheck and resolve activities stopped at Activity.dozedAt.
+ * A prior pending interrupt reason is retained; physical doze still stops work.
+ */
+import { clamp01, dexp, isNum, isObj, random, smoothstep } from '../core/index.js';
+import { readBody } from './body.js';
+export const DOZE_DEFAULTS = Object.freeze({
+    sleepiness: 0.75,
+    stimulation: 0.5,
+    hazard: 0.08,
+    seatedWeight: 0.5,
+    wakeSalience: 0.8,
+});
+function context(raw) {
+    if (!isObj(raw) ||
+        (raw.posture !== 'upright' && raw.posture !== 'seated' && raw.posture !== 'reclined') ||
+        !isNum(raw.stimulation))
+        return undefined;
+    return { posture: raw.posture, stimulation: clamp01(raw.stimulation) };
+}
+/**
+ * Enable involuntary doze without drawing RNG. Idempotent; off when absent.
+ * Hosts must deliver current, 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.
+ * 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;
+ * the pending interrupt reason may retain an earlier host/percept cause.
+ */
+export function enableDoze(p, input) {
+    if (p.body.doze)
+        return;
+    const ctx = context(input);
+    if (!ctx)
+        throw new RangeError('Invalid doze context');
+    p.body.doze = { context: ctx };
+}
+export function setDozeContext(p, input) {
+    if (!p.body.doze)
+        return;
+    const ctx = context(input);
+    if (!ctx)
+        throw new RangeError('Invalid doze context');
+    p.body.doze.context = ctx;
+}
+/** Pure; closed onset gates still require the next checkpoint. */
+export function nextDozeCheck(p) {
+    return p.body.doze && p.body.alive && !p.body.asleep ? Math.floor(p.now) + 1 : Number.POSITIVE_INFINITY;
+}
+/** Pure truth/debug reader, not a first-person lens. */
+export function readDoze(p) {
+    const d = p.body.doze;
+    if (!d)
+        return undefined;
+    const s = readBody(p).sleepiness;
+    const D = DOZE_DEFAULTS;
+    const eligible = p.body.alive &&
+        !p.body.downed &&
+        !p.body.asleep &&
+        s > D.sleepiness &&
+        d.context.posture !== 'upright' &&
+        d.context.stimulation < D.stimulation;
+    const lambda = eligible
+        ? D.hazard *
+            smoothstep(D.sleepiness, 1, s) *
+            (d.context.posture === 'seated' ? D.seatedWeight : 1) *
+            (1 - d.context.stimulation / D.stimulation)
+        : 0;
+    return { asleep: d.since !== undefined, hazardPerMinute: 1 - dexp(-lambda) };
+}
+/** @internal Composite dispatch only, once per crossed integer minute. */
+export function checkDoze(p, at) {
+    const d = p.body.doze;
+    const hazard = readDoze(p)?.hazardPerMinute ?? 0;
+    if (!d || hazard <= 0 || random(p.rng) >= hazard)
+        return false;
+    d.since = at;
+    p.body.asleep = true;
+    p.body.since = at;
+    return true;
+}
+/** @internal */
+export function wakeDoze(p, at) {
+    if (p.body.doze?.since === undefined)
+        return false;
+    delete p.body.doze.since;
+    p.body.lastSleep = { from: p.body.since, to: at };
+    p.body.asleep = false;
+    p.body.since = at;
+    return true;
+}
+/** @internal Transfer without resetting the continuous sleep span. */
+export function enterVoluntarySleep(p) {
+    if (p.body.doze)
+        delete p.body.doze.since;
+}
+/** @internal */
+export function sanitizeDoze(raw, b, now) {
+    if (!isObj(raw))
+        return undefined;
+    const ctx = context(raw.context);
+    if (!ctx)
+        return undefined;
+    const out = { context: ctx };
+    if (isNum(raw.since) && raw.since <= now && raw.since === b.since && b.alive && b.asleep)
+        out.since = raw.since;
+    return out;
+}

package/dist/body/index.d.ts

@@ -1,2 +1,5 @@
+export { BLADDER_DEFAULTS, enableBladder, readBladder, voidBladder } from './bladder.ts';
 export * from './body.ts';
+export { DOZE_DEFAULTS, enableDoze, nextDozeCheck, readDoze, setDozeContext } from './doze.ts';
 export * from './injury.ts';
+export { estimateQuantity } from './quantity.ts';

package/dist/body/index.js

@@ -1,2 +1,5 @@
+export { BLADDER_DEFAULTS, enableBladder, readBladder, voidBladder } from './bladder.js';
 export * from './body.js';
+export { DOZE_DEFAULTS, enableDoze, nextDozeCheck, readDoze, setDozeContext } from './doze.js';
 export * from './injury.js';
+export { estimateQuantity } from './quantity.js';

package/dist/body/quantity.d.ts

@@ -0,0 +1,8 @@
+import type { Person } from '../types.ts';
+export declare function estimateQuantity(p: Person, input: {
+    truth: number;
+    difficulty: number;
+}): {
+    value: number;
+    confidence: number;
+};

package/dist/body/quantity.js

@@ -0,0 +1,27 @@
+/**
+ * SCOPE: explicit scalar observation, never a render-time reader. Valid nonzero truth and
+ * difficulty consume one seeded draw. Zero truth or zero difficulty return exact truth without
+ * drawing; invalid/overflowing requests reject before drawing.
+ * Van Dongen et al. 2003 (PMID 12683469) supports separating objective impairment from
+ * subjective awareness, not quantity-task coefficients. Uniform errors and certainty are
+ * engineering defaults, not calibrated error intervals. No history or belief mutation.
+ */
+import { clamp01, random } from '../core/index.js';
+import { readBody } from './body.js';
+export function estimateQuantity(p, input) {
+    const { truth, difficulty } = input;
+    if (!Number.isFinite(truth) ||
+        truth < 0 ||
+        !Number.isFinite(difficulty) ||
+        difficulty < 0 ||
+        difficulty > 1)
+        throw new RangeError('Quantity requires finite non-negative truth and difficulty in [0,1]');
+    if (truth === 0 || difficulty === 0)
+        return { value: truth, confidence: 1 };
+    const body = readBody(p);
+    const error = difficulty * (0.05 + 0.45 * body.sleepiness);
+    if (!Number.isFinite(truth * (1 + error)))
+        throw new RangeError('Quantity estimate would overflow');
+    const value = truth * (1 + (2 * random(p.rng) - 1) * error);
+    return { value, confidence: clamp01(1 - difficulty * (0.05 + 0.45 * body.perceived.sleepiness)) };
+}

package/dist/cognition/cognition.js

@@ -38,6 +38,7 @@
 import { emotionLevel, inBreak } from '../affect/index.js';
 import { agendaTermsWithGoalEstimates } from '../agenda/index.js';
 import { trustOf } from '../beliefs/index.js';
+import { bladderMotivation } from '../body/bladder.js';
 import { normTerms } from '../conscience/index.js';
 import { clamp01, cmpStr, dexp, minuteOfDay, round } from '../core/index.js';
 import { keysOf } from '../core/keys.js';
@@ -271,6 +272,8 @@ export function consider(p, aff, ctx) {
     };
     // Needs: urgency × believed gain × believed success.
     const expected = expectedEffect(p, aff);
+    if (p.body.bladder)
+        push('need:bladder', bladderMotivation(p, aff, expected.successRate));
     for (const id of keysOf(expected.needs)) {
         const gain = expected.needs[id] ?? 0;
         if (gain === 0)

package/dist/index.d.ts

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

@@ -576,7 +576,8 @@ function updateExpectation(p, key, aff, success, realized, felt) {
 export function learnOutcome(p, aff, outcome, realized, felt) {
     if (outcome.status === 'interrupted')
         return;
-    const success = outcome.status === 'completed';
+    // A declared voiding purpose succeeds only when the actual outcome confirms it.
+    const success = outcome.status === 'completed' && (aff.voidsBladder !== true || outcome.voidedBladder === true);
     const touched = new Set([expectationKey({ action: aff.action })]);
     if (aff.targetId !== undefined)
         touched.add(expectationKey(aff));

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.17.0': {
+        to: '2.21.0',
+        note: 'doze and bladder state start absent; old callers retain their continuation',
+        apply: stamp,
+    },
     '1.4.0': {
         to: '1.5.0',
         note: 'person shape unchanged; standing advice is heard for the running activity from now on',

package/dist/narrate/lexicon.js

@@ -23,6 +23,7 @@ export const EN_LINES = {
     ],
     'need:rest': ['I need to sit down for a while.', 'A rest first, then the rest.'],
     'need:relief': ['This pain needs seeing to.', "I can't think past the pain."],
+    'need:bladder': ['I need to use the toilet.'],
     'need:belonging': ["I've been alone too long. I want company.", 'Let me find someone to talk to.'],
     'need:leisure': ['I need a break from all this.', 'Time for something easier.'],
     'need:meaning': ['I want to do something that matters.', 'Something worthwhile, for once.'],
@@ -102,6 +103,7 @@ export const EN_LINES = {
     'intention:sleep': ['to sleep'],
     'intention:rest': ['to rest'],
     'intention:relief': ['to ease the pain'],
+    'intention:bladder': ['to use the toilet'],
     'intention:belonging': ['to be with people'],
     'intention:leisure': ['to enjoy myself'],
     'intention:meaning': ['to do something that matters'],

package/dist/narrate/plain.js

@@ -22,6 +22,7 @@ export const PLAIN_EN_LINES = {
         'I need to sleep before I do anything else.',
     ],
     'need:rest': ['I need to sit down for a while.', 'I will rest before I do anything else.'],
+    'need:bladder': ['I need to use the toilet.'],
     'need:relief': [
         'I need to do something about this pain.',
         'The pain makes it hard to think about anything else.',
@@ -116,6 +117,7 @@ export const PLAIN_EN_LINES = {
     'intention:water': ['to drink'],
     'intention:sleep': ['to sleep'],
     'intention:rest': ['to rest'],
+    'intention:bladder': ['to use the toilet'],
     'intention:relief': ['to ease the pain'],
     'intention:belonging': ['to be with people'],
     'intention:leisure': ['to enjoy myself'],

package/dist/person.js

@@ -22,6 +22,8 @@
 import { actionTendencies, advanceAffect, appraise, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, feel, readAffect, regulate, release, skipAffect, skipCrisis, strain, tendencyEmotions, } from './affect/index.js';
 import { advanceAgenda, agendaTermsWithGoalEstimates, createAgenda, onFinished, promise, proposeGoals, revisePurposes, } from './agenda/index.js';
 import { advanceBeliefs, applyContradiction, attend, believe, confirm, credence, noteProvenance, trustOf, } from './beliefs/index.js';
+import { enableBladder, voidBladder } from './body/bladder.js';
+import { checkDoze, DOZE_DEFAULTS, enableDoze, enterVoluntarySleep, wakeDoze } from './body/doze.js';
 import { advanceBody, BODY_DEFAULTS, checkDowned, clearDowned, consume, createBody, downedAllows, enableFatigueStore, enableFullness, expose, injure, nextBodyThreshold, readBody, setDowned, sicken, skipBody, } from './body/index.js';
 import { ageCharacter, enableCharacterChange, noteCharacterDay, noteCharacterSocial, } from './character/index.js';
 import { closeDay, enableYearbook, endDay, noteAnswer, noteCommitments, noteDecision, noteMood, noteOutcome, trimChronicle, } from './chronicle/index.js';
@@ -258,6 +260,10 @@ export function createPerson(spec) {
         enablePromptings(p, on.promptings);
     if (on?.review)
         enableReview(p, on.review);
+    if (on?.doze)
+        enableDoze(p, on.doze);
+    if (on?.bladder)
+        enableBladder(p);
     return p;
 }
 /**
@@ -473,10 +479,10 @@ export function tick(p, now) {
     const seg = PERSON_DEFAULTS.maxSegment;
     while (p.now < now) {
         const act = p.activity;
-        const active = act !== null && p.now < act.endsAt;
+        const active = act !== null && act.dozedAt === undefined && p.body.doze?.since === undefined && p.now < act.endsAt;
         // Segment boundaries sit on an absolute grid, so how a host chunks its calls does not change the result.
         const grid = (Math.floor(p.now / seg) + 1) * seg;
-        const end = Math.min(active ? Math.min(now, act.endsAt) : now, grid);
+        const end = Math.min(active ? Math.min(now, act.endsAt) : now, grid, p.body.doze ? Math.floor(p.now) + 1 : Number.POSITIVE_INFINITY);
         const load = active && act ? { effort: act.effort, focus: act.focus, mode: act.mode } : PERSON_DEFAULTS.idleLoad;
         // A minute so large that the grid step rounds away cannot advance (security review H2): stop, never spin.
         if (!(end > p.now)) {
@@ -488,6 +494,12 @@ export function tick(p, now) {
         }
         advanceSegment(p, end - p.now, load, active && act ? act.affordance : undefined);
         p.now = end;
+        if (Number.isInteger(end) && p.body.doze && !(act && act.endsAt === end) && checkDoze(p, end)) {
+            if (act)
+                act.dozedAt ??= end;
+            // Physical onset must not erase a host/percept reason awaiting resolution.
+            interrupt(p, end, act?.interrupt?.reason ?? 'doze');
+        }
         pruneConsequences(p);
         if (p.pursuit)
             releasePursuit(p);
@@ -852,6 +864,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 wakes = percepts.some((pc) => Number.isFinite(pc.at) &&
+            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);
+    }
     const body = readBodyOf(p);
     const attended = attend(p, [...percepts], {
         focus: p.activity?.focus ?? 0,
@@ -1149,6 +1173,8 @@ function thresholdFor(p, load, review) {
 export function begin(p, aff, record, opts = {}) {
     if (!p.body.alive)
         return null;
+    if (p.body.doze?.since !== undefined && aff.mode !== 'sleep')
+        return null;
     const now = p.now;
     if (p.pursuit) {
         const considered = record.considered.find((c) => c.affordanceId === aff.id);
@@ -1224,6 +1250,8 @@ export function begin(p, aff, record, opts = {}) {
         activity.commitmentId = c.id;
     }
     p.activity = activity;
+    if (load.mode === 'sleep')
+        enterVoluntarySleep(p);
     advanceBody(p, 0, load, mods); // apply the sleep/wake switch now
     const review = load.mode === 'sleep' ? PERSON_DEFAULTS.sleepReviewInterval : PERSON_DEFAULTS.reviewInterval;
     const thresholdAt = thresholdFor(p, load, review);
@@ -1448,7 +1476,7 @@ export function finish(p, outcome, opts = {}) {
     const now = p.now;
     const aff = act.affordance;
     const completed = outcome.status === 'completed';
-    const minutes = Math.max(0, now - act.startedAt);
+    const minutes = Math.max(0, Math.min(now, act.dozedAt ?? now) - act.startedAt);
     const mods = lifeModifiers(p);
     const D = PERSON_DEFAULTS;
     const before = readNeeds(p, readBodyOf(p));
@@ -1461,6 +1489,8 @@ export function finish(p, outcome, opts = {}) {
     if (given.relief)
         bodyDeltas.relief = given.relief;
     consume(p, bodyDeltas);
+    if (completed && outcome.voidedBladder === true)
+        voidBladder(p);
     const psych = {};
     for (const id of PSYCHOLOGICAL_NEEDS)
         if (given[id] !== undefined)

package/dist/persona.js

@@ -4,8 +4,8 @@
  * identity, age, family and health compatibility before returning a new Person. Neither input is mutated.
  * This is not a world migration, identity registry, transport, hash, authentication or general calendar mapper.
  * v1 admits zero-duration travel and healthy compatible bodies only; family/bonds remain host-authored and must
- * match source provenance. Portable v1 accepts its published 2.14.1 stamp and the current engine;
- * the 2.14.1 to 2.17.0 migration changes no portable field semantics. Pregnancy and nonempty temporal bonds are unsupported in v1. All other world-dependent stores stay with the source and are disclosed as omitted.
+ * match source provenance. Portable v1 accepts its published 2.14.1 and 2.17.0 stamps and the current engine;
+ * the bodily opt-ins change no portable field semantics. Pregnancy and nonempty temporal bonds are unsupported in v1. All other world-dependent stores stay with the source and are disclosed as omitted.
  */
 import { hasUnresolvedMakeUps, sameChain } from './agenda/agenda.js';
 import { createPerson } from './person.js';
@@ -186,8 +186,10 @@ export function validatePersonaProjection(input) {
     text(input.mappingVersion);
     text(input.name);
     keys(input.source, ['schema', 'engine', 'id', 'now']);
-    // Both published passport releases used 2.14.1; the next engine upgrade is stamp-only here.
-    const compatibleEngine = input.source.engine === ENGINE_VERSION || input.source.engine === '2.14.1';
+    // 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.17.0' ||
+        input.source.engine === '2.14.1';
     if (input.source.schema !== PERSON_SCHEMA || !compatibleEngine)
         fail('unsupported source schema/engine; migrate the source before projection');
     text(input.source.id);

package/dist/sim/sim.d.ts

@@ -245,7 +245,7 @@ export declare function birth(c: Community, a: Person, b: Person, spec: ChildSpe
 export declare function tellDeath(c: Community, dead: Person, at: Minute, opts?: {
     late?: 'throw' | 'now';
 }): void;
-/** Next minute at which this person needs attention. */
+/** Pure scheduling query, including passive bodily checkpoints during joint waiting. */
 export declare function nextEventAt(c: Community, p: Person): Minute;
 /**
  * How this person would answer `suggestion` now, without changing state (UI telegraph; wraps `predict`). Pass the

package/dist/sim/sim.js

@@ -50,7 +50,7 @@
  */
 import { appraise } from '../affect/index.js';
 import { matchesCommitment, spanMeetsWindow } from '../agenda/index.js';
-import { BODY_DEFAULTS, contagionRoll, die, readBody, sicken } from '../body/index.js';
+import { BODY_DEFAULTS, contagionRoll, die, nextDozeCheck, readBody, sicken } from '../body/index.js';
 import { chronicleBetween } from '../chronicle/index.js';
 import { recordDeed } from '../conscience/index.js';
 import { converse } from '../conversation/index.js';
@@ -274,7 +274,7 @@ function awaitingJoint(c, id) {
     return pendingProposals(c).some((x) => x.proposerId === id || x.accepted.includes(id));
 }
 /** Next minute at which this person needs attention. */
-export function nextEventAt(c, p) {
+function ordinaryEventAt(c, p) {
     if (!p.body.alive)
         return Number.POSITIVE_INFINITY;
     if (awaitingJoint(c, p.id))
@@ -284,6 +284,12 @@ export function nextEventAt(c, p) {
         return Math.max(p.now, Math.min(act.endsAt, act.reviewAt));
     return Math.max(p.now, c.idleUntil[p.id] ?? p.now);
 }
+/** Pure scheduling query, including passive bodily checkpoints during joint waiting. */
+export function nextEventAt(c, p) {
+    if (p.body.doze?.since !== undefined && awaitingJoint(c, p.id))
+        return p.now;
+    return Math.min(ordinaryEventAt(c, p), nextDozeCheck(p));
+}
 /**
  * How this person would answer `suggestion` now, without changing state (UI telegraph; wraps `predict`). Pass the
  * world's `scarcityFor(p)` as `scarcity`, as the step does, or the telegraph can promise what the step refuses.
@@ -415,7 +421,6 @@ export function acceptJoint(c, world, proposal, partner, partnerRecord, writeLog
     proposal.partnerRecords[partner.id] = partnerRecord;
     if (proposal.accepted.length < proposal.partnerIds.length)
         return [];
-    settle(c, proposal, 'accepted');
     const proposer = personById(c, proposal.proposerId);
     const participants = [];
     if (proposer)
@@ -427,6 +432,19 @@ export function acceptJoint(c, world, proposal, partner, partnerRecord, writeLog
             participants.push({ person: q, offer: mirrorFor(world, q, proposal), record: rec });
     }
     const at = Math.max(...participants.map((x) => x.person.now));
+    // Opted-in catch-up can physically stop a participant. Validate everyone before any begin.
+    if (participants.some(({ person }) => person.body.doze !== undefined)) {
+        for (const { person } of participants)
+            if (person.now < at)
+                tick(person, at);
+        if (participants.some(({ person }) => person.body.doze?.since !== undefined)) {
+            declineJoint(c, proposal);
+            for (const { person } of participants)
+                interruptPerson(c, person, at, person.activity?.interrupt?.reason ?? `declined:${proposal.id}`);
+            return [];
+        }
+    }
+    settle(c, proposal, 'accepted');
     const begun = [];
     for (const { person, offer, record } of participants) {
         if (person.now < at)
@@ -770,6 +788,26 @@ export function stepCommunity(c, world, until, opts = {}) {
     c.queued ??= {};
     c.dayDone ??= {};
     synchronizeCommands(c, opts, log);
+    // Cancellation releases clocks AND review deadlines. Keep pending causes, including simultaneous doze.
+    const cancelDozeWaiting = (p, t) => {
+        for (const x of pendingProposals(c)) {
+            if (x.proposerId !== p.id && !x.partnerIds.includes(p.id))
+                continue;
+            const waiters = [x.proposerId, ...x.accepted]
+                .map((id) => personById(c, id))
+                .filter((q) => q !== undefined);
+            for (const q of waiters)
+                if (q.now < t)
+                    tick(q, t);
+            const reasons = new Map(waiters.map((q) => [q.id, q.activity?.interrupt?.reason ?? c.interrupts[q.id]?.reason]));
+            if (x.proposerId === p.id)
+                settle(c, x, 'declined');
+            else
+                declineJoint(c, x);
+            for (const q of waiters)
+                interruptPerson(c, q, t, reasons.get(q.id) ?? `declined:${x.id}`);
+        }
+    };
     // Pairs whose shared activity already ran its conversation and contagion at `pairMinute` (both partners
     // finishing the same joint activity at the same minute would otherwise run them twice).
     let pairMinute = Number.NEGATIVE_INFINITY;
@@ -787,7 +825,32 @@ export function stepCommunity(c, world, until, opts = {}) {
         if (!next || t > until)
             break;
         const p = next;
+        const ordinaryDue = ordinaryEventAt(c, p) <= t;
         tick(p, t);
+        const dozed = p.activity?.dozedAt !== undefined || p.body.doze?.since !== undefined;
+        if (dozed) {
+            cancelDozeWaiting(p, t);
+            const act = p.activity;
+            if (act?.dozedAt !== undefined) {
+                if (act.interrupt)
+                    c.interrupts[p.id] ??= { ...act.interrupt };
+                const outcome = world.resolve(p, act, 'interrupted');
+                finish(p, outcome, finishOpts(world));
+                log({
+                    at: t,
+                    personId: p.id,
+                    kind: 'finish',
+                    detail: `${act.action} interrupted by doze`,
+                    action: act.action,
+                    status: outcome.status,
+                });
+            }
+            c.idleUntil[p.id] = t + quantum;
+            if (!ordinaryDue)
+                continue;
+        }
+        if (!ordinaryDue && p.body.alive)
+            continue;
         bookkeepDay(p, world, t, c.dayDone, opts);
         if (!p.body.alive) {
             log({ at: t, personId: p.id, kind: 'died', detail: `${p.name} died` });
@@ -821,6 +884,11 @@ export function stepCommunity(c, world, until, opts = {}) {
                 }
             }
         }
+        if (p.body.doze?.since !== undefined) {
+            cancelDozeWaiting(p, t);
+            c.idleUntil[p.id] = t + quantum;
+            continue;
+        }
         let act = p.activity;
         // An interrupt on an activity that ends at this event still reaches the next decision.
         perceptReason ??= act?.interrupt?.reason;

package/dist/types.d.ts

@@ -65,7 +65,22 @@ export interface Illness {
     /** Exposure kinds (keys of `BodyState.exposures`) whose recent load raises this chronic condition. */
     aggravatedBy?: string[];
 }
+export interface DozeContext {
+    posture: 'upright' | 'seated' | 'reclined';
+    /** Host-declared alerting demand, not volume. */
+    stimulation: Unit;
+}
+export interface DozeState {
+    context: DozeContext;
+    since?: Minute;
+}
+export interface BladderState {
+    fill: Unit;
+    pending: number;
+}
 export interface BodyState {
+    doze?: DozeState;
+    bladder?: BladderState;
     /** 1 = fully fed, 0 = starving. */
     satiety: Unit;
     /** 1 = fully hydrated. */
@@ -848,6 +863,8 @@ export interface Activity {
         at: Minute;
         reason: string;
     };
+    /** Involuntary doze stopped this activity here. Work and practice stay stopped until host resolution. */
+    dozedAt?: Minute;
     /**
      * Set by `begin` when the chosen act was possible only because necessity / the capacity bound lifted a
      * conscience veto (eating forbidden food, or drinking during the fast, in extremity). `finish` then records no
@@ -898,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.17.0";
+export declare const ENGINE_VERSION = "2.21.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1181,6 +1198,8 @@ export interface Affordance {
     };
     /** Advertised need deltas over the whole activity (positive = satisfies). */
     advertises: Partial<Record<NeedId, number>>;
+    /** Intended urination: actual voiding, not completion alone, defines expectation success. */
+    voidsBladder?: boolean;
     /** Free tags: 'work', 'leisure', 'social', 'worship', 'risky', 'outdoors', ... */
     tags?: string[];
     norms?: NormTag[];
@@ -1335,6 +1354,8 @@ export interface Outcome {
     at: Minute;
     /** Realized need deltas from world effects (e.g. food eaten). Body exertion is computed by the framework. */
     needs?: Partial<Record<NeedId, number>>;
+    /** Host-confirmed urination; only a completed activity clears stored bladder fill. */
+    voidedBladder?: boolean;
     material?: number;
     /** Harm suffered. */
     injury?: Omit<Injury, 'id' | 'since'>;
@@ -1538,6 +1559,8 @@ export interface PersonSpec {
      * `enableCharacterChange` and `enableSkillRetention` right after `createPerson`. Each is off when absent.
      */
     enable?: {
+        doze?: DozeContext;
+        bladder?: boolean;
         /** Read-only suggestion score explanations, as with `enableSuggestionReasons(p)`. */
         suggestionReasons?: boolean;
         gists?: boolean;

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.17.0';
+export const ENGINE_VERSION = '2.21.0';

package/package.json

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