@adam0white/human-framework 2.19.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
@@ -529,3 +539,14 @@ wording, the generic fact sentence still includes that id so the claim is not hi
 Stock village outcomes, birth/marriage memories, routine fallbacks and generated
 community log details use the same per-person option. World-supplied outcome
 summaries and routine summaries remain exact.
+
+
+### Authored setup and explicit host effects
+
+Hosts may pass `habits: Habit[]` and `expectations: ActionExpectation[]` to `createPerson`. The framework copies records and their nested objects in order. Invalid or over-bound setup throws `RangeError`; omission preserves prior state. Duplicates remain authored records, with the existing matcher semantics.
+
+Use `gestureVoiceTrust(p, voiceId, amount, { reason, at?, action? })` for an explicit signed gesture toward an existing advising voice. It records the realized delta in bounded history and returns `undefined` for a missing voice. Reasons must be nonempty strings; optional action must be a string. Use `addTiredness(p, { sleepPressure?, exertion? })` for positive host-caused costs. Neither advances time or draws randomness. Host magnitudes are engineering premises.
+
+`confirmObservedReputation(p, prop, truth, now, table?)` replaces the manual `credence → confirm → applyReputationBelief` sequence. Supply only a fact the person could observe. It does not run attention or invent a moral judgement.
+
+`qalbReading(p)` is a read-only, sourced narration lens over existing records. Its detached categorical rows are this person's recorded understanding and evidence. They are never a spiritual health score, a ruling, a rank, or a decision input. Do not present mood, low social trust or missing memories as evidence of poor faith.

package/dist/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.d.ts

@@ -154,6 +154,16 @@ export declare function fastingDamping(b: Pick<BodyState, 'satiety' | 'hydration
  * fast: perceived hunger is damped (see SCOPE, N2b); true values, capacity and health are unchanged.
  */
 export declare function readBody(p: Person, params?: BodyParams, ctx?: BodyPerceptionContext): BodyReadout;
+/**
+ * SCOPE (host-caused tiredness): add nonnegative sleep-pressure and exertion costs, clamped to 0..1.
+ * The host supplies magnitudes; these are not calibrated claims. Absent, negative and non-finite costs
+ * do nothing. A dead body is unchanged, as with consume. Writes only these two body fields: no ticking,
+ * sleep transition, depletion, memory, RNG or other effects. Recovery remains with the existing body APIs.
+ */
+export declare function addTiredness(p: Person, costs: {
+    sleepPressure?: number;
+    exertion?: number;
+}): void;
 /** Eat, drink or take pain relief. `relief` lowers current pain; it then relaxes back toward its sources. */
 export declare function consume(p: Person, deltas: {
     food?: number;

package/dist/body/body.js

@@ -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) {
@@ -578,11 +603,27 @@ export function readBody(p, params = BODY_DEFAULTS, ctx) {
         },
     };
 }
+/**
+ * SCOPE (host-caused tiredness): add nonnegative sleep-pressure and exertion costs, clamped to 0..1.
+ * The host supplies magnitudes; these are not calibrated claims. Absent, negative and non-finite costs
+ * do nothing. A dead body is unchanged, as with consume. Writes only these two body fields: no ticking,
+ * sleep transition, depletion, memory, RNG or other effects. Recovery remains with the existing body APIs.
+ */
+export function addTiredness(p, costs) {
+    if (!p.body.alive)
+        return;
+    for (const key of ['sleepPressure', 'exertion']) {
+        const amount = costs[key];
+        if (amount !== undefined && Number.isFinite(amount) && amount > 0)
+            p.body[key] = clamp01(p.body[key] + amount);
+    }
+}
 /** Eat, drink or take pain relief. `relief` lowers current pain; it then relaxes back toward its sources. */
 export function consume(p, deltas) {
     const b = p.body;
     if (!b.alive)
         return;
+    intakeBladder(p, deltas.water);
     if (deltas.food)
         b.satiety = clamp01(b.satiety + deltas.food);
     if (deltas.water)
@@ -602,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.
@@ -614,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) {
@@ -746,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)
@@ -778,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;
@@ -808,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.d.ts

@@ -1,3 +1,40 @@
+/**
+ * SCOPE: scoring of offered options. `consider` sums the utility terms listed in docs/framework.md
+ * ("Utility of an option"): need terms use the person's need urgencies times the gain they *believe* an
+ * option gives (the advertisement blended with learned expectation, times believed success); norm,
+ * commitment/goal, habit, emotion-tendency, social, effort, risk, material, precommitment and suggestion
+ * terms come from the owning faculties or from simple coefficient forms. Traits and values only scale
+ * terms. `decide` processes affordances in stable id order, scores them all and hands the list to `will`
+ * for vetoes and selection. Borrowed shapes: additive multi-attribute utility with a saturating money
+ * term (diminishing marginal value of material gain), prediction-error-adjusted action values
+ * (model-free cached values alongside the host's model-based advertisement). It does NOT claim calibrated
+ * weights, rational-choice optimality, or that a weighted sum exhausts human deliberation; every term is
+ * kept in the trace so the UI can show why.
+ *
+ * SCOPE (lane will+cognition, 2026-10-03): several voices add one `suggestion:<voiceId>` term each, with
+ * reactance summed into one `autonomy` term; remembered advice adds `suggestion:remembered:<source>` terms
+ * (see `rememberedTerms` and `will.rememberAdvice`). Scarcity (N13): a host-supplied 0..1 shortfall raises the
+ * weight of the material term, shrinks its saturation scale so small sums still count, and raises the
+ * `need:safety` term. Borrowed shapes: diminishing marginal utility of wealth (the same sum weighs more to
+ * someone who has less) and the scarcity account of Mullainathan & Shafir, where a shortfall captures
+ * attention and raises the felt value of the scarce resource. Neither source is catalogued in
+ * research/empirical-models.md yet; the coefficients are engineering defaults. It does not model the claimed
+ * cognitive cost of scarcity ("bandwidth tax"), debt itself (a host ledger plus commitments), or present
+ * bias; and because losses are amplified too, a host must carry the benefit of paying a debt (a commitment,
+ * an advertised `safety` gain) or paying looks only like a loss. The spec's "security need" is read as the
+ * `safety` need: `security` is a value, not a need, and no need is added.
+ *
+ * SCOPE (2.8.0, both additive): an offer naming `alongside` partners (people already taking that course) gets one
+ * `together:<id>` term per known, living partner, `togetherScale` × closeness, without belonging satiation: the
+ * pull is not to be left behind, which stays when the pair is together and belonging is full (The Rope's resting
+ * partner, 2026-10-18 reproduction: belonging terms near 0.01 against inertia of 0.07-0.15). Shape only, after
+ * joint commitment and the sense of commitment in joint action (Gilbert 1990; Michael and Pacherie 2015; cited unaudited, research/empirical-models.md §6b); it does
+ * not model who leads, negotiation, or obligations between the partners. With opt-in `body.fullness`, an offer
+ * that advertises food, water or relief while that need is past its comfort threshold gets `full:<need>` =
+ * -fullnessScale × gain × over²: eating or drinking when full is mildly unpleasant (negative alliesthesia, unaudited citation, Cabanac
+ * 1971), so idle choice stops cycling short consumption at full hydration (The Rope, owner Kestrel export
+ * 2026-10-19). It models no bladder, sensory-specific satiety by food, or overeating for comfort.
+ */
 import type { BodyPerceptionContext } from '../body/index.ts';
 import { type HabitContext } from '../habits/index.ts';
 import { type PromptingSeen } from '../promptings/index.ts';

package/dist/cognition/cognition.js

@@ -38,8 +38,10 @@
 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';
 import { curiosityTerms } from '../curiosity/index.js';
 import { habitEase, habitPull } from '../habits/index.js';
 import { expectedEffect } from '../memory/index.js';
@@ -270,7 +272,9 @@ export function consider(p, aff, ctx) {
     };
     // Needs: urgency × believed gain × believed success.
     const expected = expectedEffect(p, aff);
-    for (const id of Object.keys(expected.needs)) {
+    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)
             continue;
@@ -296,7 +300,7 @@ export function consider(p, aff, ctx) {
         let relevance = 1;
         if (expected.valence > 0) {
             let served = -1;
-            for (const id of Object.keys(expected.needs))
+            for (const id of keysOf(expected.needs))
                 if ((expected.needs[id] ?? 0) > 0)
                     served = Math.max(served, urgencyOf(ctx.needs, id));
             if (served >= 0)

package/dist/core/index.d.ts

@@ -1,3 +1,4 @@
+export * from './keys.ts';
 export * from './libm.ts';
 export * from './math.ts';
 export * from './random.ts';

package/dist/core/index.js

@@ -1,3 +1,4 @@
+export * from './keys.js';
 export * from './libm.js';
 export * from './math.js';
 export * from './random.js';

package/dist/core/keys.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Own enumerable string keys of a typed record, in Object.keys order.
+ * Callers must supply records whose runtime keys match their declared key type.
+ * This only types enumeration; it does not sort, validate keys or change state.
+ */
+export declare function keysOf<K extends string>(record: Partial<Record<K, unknown>>): K[];

package/dist/core/keys.js

@@ -0,0 +1,8 @@
+/**
+ * Own enumerable string keys of a typed record, in Object.keys order.
+ * Callers must supply records whose runtime keys match their declared key type.
+ * This only types enumeration; it does not sort, validate keys or change state.
+ */
+export function keysOf(record) {
+    return Object.keys(record);
+}

package/dist/family/family.js

@@ -88,7 +88,7 @@ function sanitizeAptitudes(x) {
             out[k] = clamp(v, 0.25, 4);
     return Object.keys(out).length > 0 ? out : undefined;
 }
-/** Validate a saved family slice; undefined when nothing usable remains (used by `restore`). @internal */
+/** Validate a saved family slice; drop malformed pregnancies, keep usable fields. Undefined when none remain. @internal */
 export function sanitizeFamily(x) {
     if (!isObj(x))
         return undefined;
@@ -101,9 +101,9 @@ export function sanitizeFamily(x) {
     if (pg &&
         typeof pg === 'object' &&
         typeof pg.fatherId === 'string' &&
-        typeof pg.conceivedAt === 'number' &&
-        typeof pg.dueAt === 'number' &&
-        typeof pg.seed === 'number')
+        isNum(pg.conceivedAt) &&
+        isNum(pg.dueAt) &&
+        isNum(pg.seed))
         out.pregnancy = { fatherId: pg.fatherId, conceivedAt: pg.conceivedAt, dueAt: pg.dueAt, seed: pg.seed };
     if (isNum(f.attachment))
         out.attachment = clamp01(f.attachment);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.19.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';
@@ -28,6 +28,7 @@ export type { MigrationStep } from './migrate.ts';
 export { MIGRATIONS, migratableVersions, migrate } from './migrate.ts';
 export * from './narrate/index.ts';
 export * from './needs/index.ts';
+export { confirmObservedReputation } from './observed-reputation.ts';
 export * from './partnering/index.ts';
 export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistence/index.ts';
 export * from './person.ts';
@@ -38,6 +39,7 @@ export { adoptProjectTask, considerProjects, enableProjects, PROJECTS_DEFAULTS,
 export * from './promptings/index.ts';
 export type { ConsequenceEvidence, PlanRoute, PlanStep } from './prospection/index.ts';
 export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, enablePlanning, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, seedConsequences, } from './prospection/index.ts';
+export { type QalbDescription, qalbReading } from './qalb.ts';
 export { fingerprint, restore, snapshot } from './restore.ts';
 export * from './review/index.ts';
 export * from './scenarios/index.ts';