@adam0white/human-framework 2.22.0 → 3.0.0

package/README.md

@@ -4,10 +4,50 @@ HF is a TypeScript library for simulated people in games and headless simulation
 possible actions. Each person weighs needs, habits, duties, goals and suggestions, then chooses.
 A player can suggest an action; the person can defer or refuse it.
 
-HF 2.14.1 uses utility scoring and seeded randomness, with no LLM in the actor loop and no runtime
+HF 3.0.0 uses utility scoring and seeded randomness, with no LLM in the actor loop and no runtime
 dependencies. Decision records expose scored terms and template narration. Person state is plain JSON.
 This is an authored simulation model, not a validated predictor of real people.
 
+## Migrating to v3
+
+The API migration keeps engine `2.23.0`. Relative to HF 2.23.0, it does not change seeded draws, numeric rules or saved Person state. The package version is `3.0.0`; publication is recorded separately in the release history.
+
+| Before                                                                         | v3                                                                                                |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `glimpse(p, id, signs, { at, clarity })`                                       | `glimpse(p, id, signs, at, clarity)`                                                              |
+| `glimpseOf(p, target, at, clarity)` or `glimpseOf(p, target, { at, clarity })` | `glimpsePerson(p, target, at, clarity)`                                                           |
+| `acquaintWith(p, target, familiarity, at)`                                     | `acquaintPerson(p, target, familiarity, at)`                                                      |
+| `hear(p, id, key, value, { at, weight })`                                      | `hear(p, id, key, value, at, weight)`                                                             |
+| `conceive(mother, father, { seed, at })`                                       | `conceive(mother, father, seed, at)`                                                              |
+| `retell(teller, listener, { at, trust, limit, placeIds })`                     | `retell(teller, listener, at, { trust, limit, placeIds })`                                        |
+| `TRAIT_NAMES`                                                                  | `TRAIT_KEYS` (same order)                                                                         |
+| `expit(x)`                                                                     | `sigmoid(x)` (same function body)                                                                 |
+| `keysOf(record)`                                                               | `Object.keys(record)` (same enumeration order; narrow host key types explicitly when needed)      |
+| `repent(p, breachId, unusedTime)`                                              | `repent(p, breachId)`                                                                             |
+| `recordRepair(p, victimId, unusedTime)`                                        | `recordRepair(p, victimId)`                                                                       |
+| `liveRoutine(p, to, fixedRoutine)`                                             | `liveRoutine(p, to, () => fixedRoutine)`                                                          |
+| `routineFor: (p, day, community) => choose(p, day, community)`                 | `routineFor: (p, day) => choose(p, day, community)` with `community` captured from the host scope |
+
+Removed options-object calls from untyped JavaScript throw `TypeError` before changing Person state. Their time argument must be a finite number in the positional slot.
+
+Both routine drivers use `RoutineSource = (p: Person, day: number) => Routine`. `day` is the absolute day being started. Existing two-argument sources continue unchanged. A community source closes over the community for that run; bind a new closure after restoring a different community. Sources still run immediately before each person's routine day. Community dawn hooks still run first, and earlier people's days are already applied when later sources read community state. Do not precompute all routines at dawn if that would change those reads.
+
+The primitive names `glimpse` and `acquaint` stay. Their Person composites use the explicit `Person` suffix. The proposed `skip` → `skipTo` rename is dropped (Q15): it provides no player value and `skip` is clear in context.
+
+### Tuning defaults (Q5)
+
+Assignment to existing mutable defaults remains the tuning API in v3. These settings apply to every run in the same module instance. Set them before creating or restoring a run, then keep them fixed while it runs. Already-frozen defaults remain frozen.
+
+Deterministic replay requires the same engine version, effective tuning values, initial state, seeded streams, inputs and call order. Person snapshots do not store these global settings. A host that tunes must store its complete effective configuration or its overrides relative to a known pristine baseline in its save or replay envelope. Before restoring or continuing, restore that baseline first, then apply the saved overrides. A fresh module instance is another way to start from the baseline. Applying overrides over a previous run's settings can leak tuning between runs.
+
+Two worlds with different settings cannot safely share one module instance. Tests that tune must restore values in a `finally` block and must not mutate them concurrently. This decision preserves existing hosts and seeded behavior. It adds no global configuration function or per-person settings. A future isolated settings API must first demonstrate exact snapshot, restore and continuation under overrides.
+
+## Ordering inputs for one logical tick (opt-in)
+
+`canonicalTickInputs(tick, inputs, expected)` waits for the complete declared sender/sequence set and returns a new envelope array sorted by sender, then sequence. It returns `undefined` while an input is missing and throws for duplicate, unexpected or wrong-tick inputs. Payloads remain host-owned. Use the returned array only after the barrier completes; save pending input with host state.
+
+This is a bounded host convention, not transport, consensus or fairness. It reads no Person or RNG. Existing actor calls never use it implicitly. The H3 controls compare reordered deliveries, withheld input, restore and a behaviorally different unsorted control. The copyable two-person starter in `examples/h3-starter` owns its own clock and replay envelope; it is not a complete game engine or part of the npm artifact.
+
 ## Try the games
 
 - [Twice at the Well](https://human.adamwhite.work/colony/): compare a colony without and with HF.
@@ -20,21 +60,23 @@ This is an authored simulation model, not a validated predictor of real people.
 Use Node 24 or newer. In an empty directory, install the version this README describes:
 
 ```sh
-npm install @adam0white/human-framework@2.14.1
+npm install @adam0white/human-framework@3.0.0
 ```
 
 Save these 20 lines as `quickstart.mjs`, then run `node quickstart.mjs`:
 
 ```js
 import {
-  createCommunity, createPerson, createVillage,
-  predict, stepCommunity, villagerSpec,
+  createCommunity,
+  createPerson,
+  createVillage,
+  predict,
+  stepCommunity,
+  villagerSpec,
 } from '@adam0white/human-framework';
 const start = 6 * 60; // simulation minutes
 const ids = ['ada', 'bora'];
-const people = ids.map((id, i) => createPerson(
-  villagerSpec(id, id, i + 1, { now: start, others: ids }),
-));
+const people = ids.map((id, i) => createPerson(villagerSpec(id, id, i + 1, { now: start, others: ids })));
 const world = createVillage(people, { seed: 7 });
 const community = createCommunity(people);
 const ada = community.people[0];
@@ -83,14 +125,14 @@ A suggestion is one urge among many. Its weight is strength × trust in the voic
 fits the person's motives, and a suggestion alone never overrides a veto. Each one resolves to a typed
 verdict (`SuggestionResolution`):
 
-| verdict | meaning | `kind` |
-|---|---|---|
-| `assented` | the suggested option won | none |
-| `deferred` | the person's own preference won; carries a `counterOffer` ("after I eat lunch") | `notNow` |
-| `modified` | a near alternative with the same action or aim won; the `counterOffer` names it | `notNow` |
-| `refused` | cannot (asleep, exhausted, skill far too low, a pressing bodily need) or will not (a firmly held norm, broken trust) | `cannot` / `willNot` |
-| `complied` | the voice insisted on a "not now"; done under protest (`activity.protest`), at a cost to autonomy and trust | `notNow` |
-| `commanded` | the host took direct control (see [Direct control](#direct-control)); the person does the order whatever they would have chosen | none |
+| verdict     | meaning                                                                                                                         | `kind`               |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `assented`  | the suggested option won                                                                                                        | none                 |
+| `deferred`  | the person's own preference won; carries a `counterOffer` ("after I eat lunch")                                                 | `notNow`             |
+| `modified`  | a near alternative with the same action or aim won; the `counterOffer` names it                                                 | `notNow`             |
+| `refused`   | cannot (asleep, exhausted, skill far too low, a pressing bodily need) or will not (a firmly held norm, broken trust)            | `cannot` / `willNot` |
+| `complied`  | the voice insisted on a "not now"; done under protest (`activity.protest`), at a cost to autonomy and trust                     | `notNow`             |
+| `commanded` | the host took direct control (see [Direct control](#direct-control)); the person does the order whatever they would have chosen | none                 |
 
 Insisting (`insist: true`) turns only a `notNow` into compliance, and not when a bodily need is pressing. It
 never overrides `cannot` or `willNot`.
@@ -132,11 +174,12 @@ An offer describes expected effects. An outcome reports what happened. The host
 contact, inventory and payment; HF uses the reported outcome to update the person. Do not copy
 `Affordance.advertises` into `Outcome.needs` as a general completion rule.
 
-| Host situation | Offer | Completion report |
-|---|---|---|
-| A person sleeps for part of the planned night. | Advertise typical sleep/rest benefits and set `mode: 'sleep'`. | Leave `sleep` and `rest` absent from `Outcome.needs`. `finish` advances the body to the actual end time and measures their change since the activity began. Explicit values replace that measurement; copying the advertisement can overstate the realized recovery reported to learning. |
-| A task promises four coins but actually pays two. | Set expected `Affordance.material` to four host units. | Update the host ledger by two and report `Outcome.material: 2`. A completed task does not imply the promised payment arrived. Report zero for no payment and a negative value for an actual cost. HF does not maintain the host's money ledger. |
-| A person can talk with someone who is present. | Tag the offer `social` when it really involves social contact; put participants in `with`. | Resolve actual participation. An empty room, a sleeping neighbour or someone who arrives after the conversation ends is not a completed encounter. Do not award contact or belonging merely because the activity uses a shared place. |
+<!-- biome-ignore format: Biome 2.6.3 adds column padding on each pass for this inline-code table; preserve stable source. -->
+| Host situation                                    | Offer                                                                                      | Completion report                                                                                                                                                                                                                                                                        |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A person sleeps for part of the planned night.    | Advertise typical sleep/rest benefits and set `mode: 'sleep'`.                             | Leave `sleep` and `rest` absent from `Outcome.needs`.`finish` advances the body to the actual end time and measures their change since the activity began. Explicit values replace that measurement; copying the advertisement can overstate the realized recovery reported to learning. |
+| A task promises four coins but actually pays two. | Set expected `Affordance.material` to four host units.                                     | Update the host ledger by two and report `Outcome.material: 2`. A completed task does not imply the promised payment arrived. Report zero for no payment and a negative value for an actual cost. HF does not maintain the host's money ledger.                                          |
+| A person can talk with someone who is present.    | Tag the offer `social` when it really involves social contact; put participants in `with`. | Resolve actual participation. An empty room, a sleeping neighbour or someone who arrives after the conversation ends is not a completed encounter. Do not award contact or belonging merely because the activity uses a shared place.                                                    |
 
 For in-person activities, the host must establish co-presence and overlapping participation. HF has
 no map and does not discover companions. `with` names people taking part, not everyone assigned to a
@@ -211,7 +254,7 @@ reference host: `createVillage`.
   const village2 = createVillage(people, { seed: 0, state: s.world });
   const c2 = createCommunity(people, s.community); // continues exactly as the unsaved run would
   ```
-- **Time arguments.** A host event takes `at` as its last required argument, with optional knobs after it (`glimpseOf(observer, target, at, clarity?)`, `retell(teller, listener, at, opts?)`); a query evaluated at a time takes `now`. The 2.0 options-object forms still work and are deprecated until 3.0. See docs/framework.md, "Argument order".
+- **Time arguments.** A host event takes `at` as its last required argument, with optional knobs after it (`glimpsePerson(observer, target, at, clarity?)`, `retell(teller, listener, at, opts?)`); a query evaluated at a time takes `now`. The former 2.0 options-object forms are removed in v3. See docs/framework.md, "Argument order".
 - Hosts that live people sparsely over decades can shrink what a save carries per person with
   `setRetention(p, { trace, chronicleDays })` (or `PersonSpec.retention`): fewer decision records, and day records
   bounded by age as well as count. No decision changes. `restore` also refuses a non-finite or out-of-range `now`
@@ -222,7 +265,7 @@ reference host: `createVillage`.
 
 There are two version numbers, and they move independently.
 
-- **The release version** is the package version (`package.json`, currently `2.22.0`) and `FRAMEWORK_VERSION`, the same
+- **The release version** is the package version (`package.json`, currently `3.0.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
@@ -242,7 +285,7 @@ this policy.
 
 ## 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.
+`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.
 
@@ -269,8 +312,8 @@ of it runs as before.
 - **Surroundings.** `setAmbient` (cold, dark, crowding, beauty, weather, day length) shifts mood, body and needs.
 - **Multi-year stepping.** `liveRoutine` and `liveCommunity` live people by routine a coarse day at a time, with
   natural death, chronic onsets, deaths told and minors raised.
-- **Impressions of others.** What one person believes about another (`glimpseOf(observer, target, at, clarity?)`, `observeAct`, `hear(observer, targetId, key, value, at, weight?)`,
-  `acquaintWith`), with confidence; `predictAs` runs a prediction on the person as the observer pictures them.
+- **Impressions of others.** What one person believes about another (`glimpsePerson(observer, target, at, clarity?)`, `observeAct`, `hear(observer, targetId, key, value, at, weight?)`,
+  `acquaintPerson`), with confidence; `predictAs` runs a prediction on the person as the observer pictures them.
 - **Switching on at creation.** `PersonSpec.enable: { gists, yearbook, character, skillRetention }` turns the long-run faculties above on when the person is created.
 - **Answering between decisions.** `answerNow` books a refusal at once without touching the running activity.
 
@@ -314,7 +357,7 @@ that place lose appeal until the fear fades. Groups and factions themselves stay
   the bundled `DEFAULT_NORMS` is Islam-guided; each reference's verification status is listed in
   [research/norm-sources.md](https://github.com/adam0white/human-framework/blob/main/research/norm-sources.md)). A host with its own catalog passes it as
   `World.catalog`, so necessity excuses and exemptions read that catalog; a norm not in it is not excused.
-  A person holds an *understanding* of a norm, with a standing and a conviction. That understanding is
+  A person holds an _understanding_ of a norm, with a standing and a conviction. That understanding is
   not a ruling. The library never computes divine acceptance. Where schools of thought differ, the
   position the bundled catalog takes, and why, is recorded in
   [research/decisions.md](https://github.com/adam0white/human-framework/blob/main/research/decisions.md).
@@ -341,18 +384,30 @@ Use observations the person actually received; the host owns what those observat
 ```ts
 receiveMethodCues(learner, {
   contextId: 'observed-example',
-  cues: [{ cue: 'route', value: 'north' }, { cue: 'signal', value: 'clear' }],
+  cues: [
+    { cue: 'route', value: 'north' },
+    { cue: 'signal', value: 'clear' },
+  ],
 });
 demonstrateMethod(learner, {
-  id: 'routing-north', demonstrationId: 'example-1',
-  contextId: 'observed-example', sourceId: 'instructor',
-  conditions: [{ cue: 'route', value: 'north' }, { cue: 'signal', value: 'clear' }],
-  action: 'send-north', outcome: 'success',
+  id: 'routing-north',
+  demonstrationId: 'example-1',
+  contextId: 'observed-example',
+  sourceId: 'instructor',
+  conditions: [
+    { cue: 'route', value: 'north' },
+    { cue: 'signal', value: 'clear' },
+  ],
+  action: 'send-north',
+  outcome: 'success',
 });
 // A new parcel can share the learned observation structure.
 receiveMethodCues(learner, {
   contextId: 'new-parcel',
-  cues: [{ cue: 'route', value: 'north' }, { cue: 'signal', value: 'clear' }],
+  cues: [
+    { cue: 'route', value: 'north' },
+    { cue: 'signal', value: 'clear' },
+  ],
 });
 const evidence = methodEvidence(learner, 'send-north', 'new-parcel');
 // Offers for that parcel carry methodContext: 'new-parcel'.
@@ -369,39 +424,67 @@ HF 2.3.0 lets an attended explanation connect one current action to one possible
 
 ```ts
 import {
-  type Affordance, type ReceivedConsequence,
-  consequenceEvidence, createPerson, decide, perceive,
+  type Affordance,
+  type ReceivedConsequence,
+  consequenceEvidence,
+  createPerson,
+  decide,
+  perceive,
 } from '@adam0white/human-framework';
 
 const person = createPerson({
-  id: 'courier', name: 'Courier', seed: 19, now: 600,
-  bornAt: -30 * 365 * 1440, sex: 'female',
-  goals: [{
-    id: 'delivery', label: 'Deliver the parcel', serves: ['achievement'],
-    advancedBy: [{ action: 'deliver', amount: 1 }], importance: 0.8,
-    temporal: { halfLifeMinutes: 30 },
-  }],
+  id: 'courier',
+  name: 'Courier',
+  seed: 19,
+  now: 600,
+  bornAt: -30 * 365 * 1440,
+  sex: 'female',
+  goals: [
+    {
+      id: 'delivery',
+      label: 'Deliver the parcel',
+      serves: ['achievement'],
+      advancedBy: [{ action: 'deliver', amount: 1 }],
+      importance: 0.8,
+      temporal: { halfLifeMinutes: 30 },
+    },
+  ],
 });
 const route: ReceivedConsequence = {
-  id: 'access-window', revision: 0,
+  id: 'access-window',
+  revision: 0,
   trigger: { action: 'ask-access', targetId: 'keeper' },
   successor: { action: 'deliver', duration: 20, effort: 0.1 },
-  availableFrom: 620, availableUntil: 680, expiresAt: 800,
-  chance: 0.8, confidence: 0.9,
+  availableFrom: 620,
+  availableUntil: 680,
+  expiresAt: 800,
+  chance: 0.8,
+  confidence: 0.9,
 };
-perceive(person, [{
-  at: 600, channel: 'told', kind: 'explanation', actorId: 'keeper',
-  targetId: person.id, salience: 1,
-  summary: 'If your request succeeds, this route may become available.',
-  consequences: [route],
-}]);
+perceive(person, [
+  {
+    at: 600,
+    channel: 'told',
+    kind: 'explanation',
+    actorId: 'keeper',
+    targetId: person.id,
+    salience: 1,
+    summary: 'If your request succeeds, this route may become available.',
+    consequences: [route],
+  },
+]);
 const request: Affordance = {
-  id: 'ask', action: 'ask-access', label: 'Request access', targetId: 'keeper',
-  duration: 10, effort: 0.1, advertises: {},
+  id: 'ask',
+  action: 'ask-access',
+  label: 'Request access',
+  targetId: 'keeper',
+  duration: 10,
+  effort: 0.1,
+  advertises: {},
 };
-const offers: Affordance[] = [request,
-  { id: 'direct', action: 'deliver', label: 'Deliver directly',
-    duration: 180, effort: 0.1, advertises: {} },
+const offers: Affordance[] = [
+  request,
+  { id: 'direct', action: 'deliver', label: 'Deliver directly', duration: 180, effort: 0.1, advertises: {} },
 ];
 const decision = decide(person, offers);
 const evidence = consequenceEvidence(person, request); // pure; no RNG consumed

package/dist/agenda/agenda.js

@@ -897,7 +897,7 @@ function boundOwed(state) {
         return;
     while (owed.length > AGENDA_DEFAULTS.maxOwed) {
         const i = owed.findIndex((o) => o.scheduledAs !== undefined);
-        owed.splice(i >= 0 ? i : 0, 1);
+        owed.splice(Math.max(i, 0), 1);
     }
 }
 /** A kept, closed instance is positive recorded evidence; scheduling or missing history is not. */

package/dist/beliefs/beliefs.js

@@ -24,7 +24,7 @@
  * not prove deceit, change the belief, or change relationship or voice trust. Loss and retention limits are
  * engineering defaults, not calibrated effect sizes. Deduplication lasts only while its bounded record stays.
  */
-import { clamp, clamp01, decay, dpow, expit, isNum, isObj, logit } from '../core/index.js';
+import { clamp, clamp01, decay, dpow, isNum, isObj, logit, sigmoid } from '../core/index.js';
 import { MAX_MINUTE, MINUTES_PER_DAY } from '../types.js';
 export const BELIEF_DEFAULTS = {
     maxBeliefs: 300,
@@ -229,7 +229,7 @@ export function believe(p, prop, value, confidence, sourceId, now) {
 }
 export function credence(p, prop) {
     const b = findBelief(p, prop);
-    return b ? expit(b.logOdds) : 0.5;
+    return b ? sigmoid(b.logOdds) : 0.5;
 }
 /**
  * Direct observation of the truth: set the belief firmly and recalibrate the sources that spoke on it.

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

@@ -100,13 +100,11 @@ export declare function recordDeed(p: Person, aff: Affordance, intention: string
  * The person repents a breach: regret, stopping and resolve. When another person was wronged,
  * restitution is also required, so the breach closes only after `recordRepair` for that victim.
  * Returns whether the breach is now closed. This records the person's acts, not acceptance.
- * The unused `_now` parameter is optional since 2.9.1 and is removed in 3.0.
  */
-export declare function repent(p: Person, id: string, _now?: Minute): boolean;
+export declare function repent(p: Person, id: string): boolean;
 /**
  * Restitution/apology delivered to a wronged person (host-attested): closes their open breaches.
- * The unused `_now` parameter is optional since 2.9.1 and is removed in 3.0.
  */
-export declare function recordRepair(p: Person, victimId: string, _now?: Minute): number;
+export declare function recordRepair(p: Person, victimId: string): number;
 /** Felt weight of open breaches, saturating: 1 - Π(1 - weight). Input for guilt in affect. */
 export declare function guiltLoad(p: Person): Unit;

package/dist/conscience/conscience.js

@@ -278,7 +278,7 @@ function breachId(p, at, normId) {
 function boundBreaches(c) {
     while (c.breaches.length > CONSCIENCE_DEFAULTS.maxBreaches) {
         const i = c.breaches.findIndex((b) => b.repaired);
-        c.breaches.splice(i >= 0 ? i : 0, 1);
+        c.breaches.splice(Math.max(i, 0), 1);
     }
 }
 /**
@@ -358,9 +358,8 @@ export function recordDeed(p, aff, intention, now, completed, opts = {}) {
  * The person repents a breach: regret, stopping and resolve. When another person was wronged,
  * restitution is also required, so the breach closes only after `recordRepair` for that victim.
  * Returns whether the breach is now closed. This records the person's acts, not acceptance.
- * The unused `_now` parameter is optional since 2.9.1 and is removed in 3.0.
  */
-export function repent(p, id, _now) {
+export function repent(p, id) {
     const breach = p.conscience.breaches.find((b) => b.id === id);
     if (!breach)
         return false;
@@ -371,9 +370,8 @@ export function repent(p, id, _now) {
 }
 /**
  * Restitution/apology delivered to a wronged person (host-attested): closes their open breaches.
- * The unused `_now` parameter is optional since 2.9.1 and is removed in 3.0.
  */
-export function recordRepair(p, victimId, _now) {
+export function recordRepair(p, victimId) {
     let count = 0;
     for (const b of p.conscience.breaches) {
         if (!b.repaired && b.victimId === victimId) {

package/dist/conversation/conversation.js

@@ -39,7 +39,8 @@
  * 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 { clamp01, expit, round } from '../core/index.js';
+import { clamp01, round, sigmoid } 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 = {
@@ -156,7 +157,7 @@ export function converse(speaker, listener, ctx) {
         const subject = b.prop.split(':')[0];
         if (subject === speaker.id)
             continue;
-        const cred = expit(b.logOdds);
+        const cred = sigmoid(b.logOdds);
         const threshold = Number.isFinite(ctx.confidentMin) &&
             ctx.confidentMin >= 0 &&
             ctx.confidentMin <= 0.5
@@ -180,7 +181,7 @@ export function converse(speaker, listener, ctx) {
     // Temptations: claims the speaker would gain from the listener believing.
     for (const t of [...(ctx.temptations ?? [])].sort((a, b) => (a.prop < b.prop ? -1 : 1))) {
         const b = speaker.memory.beliefs.find((x) => x.prop === t.prop);
-        const cred = b ? expit(b.logOdds) : 0.5;
+        const cred = b ? sigmoid(b.logOdds) : 0.5;
         const forValue = t.value ? cred : 1 - cred;
         const gain = clamp01(t.gain);
         if (forValue >= 0.5) {
@@ -233,7 +234,7 @@ export function converse(speaker, listener, ctx) {
         // deed (counted above) but yields no percept, so the same gossip retold at every tea is not judged afresh.
         const heard = listener.memory.beliefs.find((x) => x.prop === c.prop);
         if (heard) {
-            const cred = expit(heard.logOdds);
+            const cred = sigmoid(heard.logOdds);
             if ((c.value ? cred : 1 - cred) >= c.confidence)
                 continue;
         }
@@ -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'}`,
@@ -280,7 +281,7 @@ export function converse(speaker, listener, ctx) {
     for (const b of beliefs) {
         if (!b.prop.startsWith(prefix))
             continue;
-        const cred = expit(b.logOdds);
+        const cred = sigmoid(b.logOdds);
         if (cred < C.adviceMin)
             continue;
         const strength = clamp01((cred - 0.5) * 2 * (0.3 + 0.7 * care) * (0.5 + benevolence));
@@ -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/core/index.d.ts

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

package/dist/core/index.js

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

package/dist/core/math.d.ts

@@ -5,8 +5,6 @@ export declare const clampSigned: (value: number) => number;
 export declare const lerp: (a: number, b: number, t: number) => number;
 export declare const sigmoid: (x: number) => number;
 export declare const logit: (p: number) => number;
-/** @deprecated since 2.9.1, removed in 3.0; use sigmoid */
-export declare const expit: typeof sigmoid;
 /** Exponential decay of `value` toward `target` over `dt` minutes with the given half-life. */
 export declare function decay(value: number, dt: number, halfLife: number, target?: number): number;
 export declare const minuteOfDay: (now: number) => number;

package/dist/core/math.js

@@ -1,7 +1,9 @@
 import { MINUTES_PER_DAY } from '../types.js';
 import { dexp, dlog, dpow } from './libm.js';
 /** Clamp into [min, max]. NaN maps to `min`, so one bad host number cannot propagate through state. */
-export const clamp = (value, min, max) => Number.isNaN(value) ? min : value < min ? min : value > max ? max : value;
+export const clamp = (value, min, max) => 
+// biome-ignore lint/complexity/useMathMinMax: Comparisons preserve signed zero and NaN bounds; Math.min/max change them.
+Number.isNaN(value) ? min : value < min ? min : value > max ? max : value;
 export const clamp01 = (value) => clamp(value, 0, 1);
 export const clampSigned = (value) => clamp(value, -1, 1);
 /** A finite number. Restore sanitizers use it. @internal */
@@ -36,8 +38,6 @@ export const logit = (p) => {
     const q = clamp(p, 1e-6, 1 - 1e-6);
     return dlog(q / (1 - q));
 };
-/** @deprecated since 2.9.1, removed in 3.0; use sigmoid */
-export const expit = sigmoid;
 /** Exponential decay of `value` toward `target` over `dt` minutes with the given half-life. */
 export function decay(value, dt, halfLife, target = 0) {
     if (halfLife <= 0)

package/dist/family/family.d.ts

@@ -40,11 +40,6 @@ export declare function conceptionChance(mother: Person, father: Person, days: n
  * median (an engineering bound against extreme draws). Returns the pregnancy, or undefined if one is already open.
  */
 export declare function conceive(mother: Person, father: Person | PersonId, seed: number, at: Minute): Pregnancy | undefined;
-/** @deprecated since 2.1: pass `at` (and the optional knobs) positionally. Removed in 3.0. */
-export declare function conceive(mother: Person, father: Person | PersonId, opts: {
-    at: Minute;
-    seed: number;
-}): Pregnancy | undefined;
 /**
  * Weeks since conception (0 when not pregnant). Counted from conception, not from the last menstrual period, which
  * is where obstetric weeks and trimesters are conventionally counted from (about two weeks earlier). The second

package/dist/family/family.js

@@ -161,19 +161,25 @@ export function conceptionChance(mother, father, days) {
         return 0;
     return clamp01(1 - dpow(1 - c, days / FAMILY_DEFAULTS.cycleDays));
 }
-export function conceive(mother, father, seedOrOpts, when) {
-    const opts = typeof seedOrOpts === 'number' ? { seed: seedOrOpts, at: when } : seedOrOpts;
+/**
+ * Record that `mother` has conceived by `father` at `at`. The due date is drawn from a stream derived from `seed`;
+ * `seed` also becomes the child's seed at delivery. The drawn length is clamped to 4 sd below and 3 sd above the
+ * median (an engineering bound against extreme draws). Returns the pregnancy, or undefined if one is already open.
+ */
+export function conceive(mother, father, seed, at) {
+    if (!Number.isFinite(at))
+        throw new TypeError('conceive requires a finite positional time');
     const fam = familyOf(mother);
     if (fam.pregnancy)
         return undefined;
-    const rng = createRng((opts.seed ^ 0x9e3779b9) >>> 0);
+    const rng = createRng((seed ^ 0x9e3779b9) >>> 0);
     const F = FAMILY_DEFAULTS;
     const days = clamp(normal(rng, F.gestationDays, F.gestationSdDays), F.gestationDays - 4 * F.gestationSdDays, F.gestationDays + 3 * F.gestationSdDays);
     const pregnancy = {
         fatherId: typeof father === 'string' ? father : father.id,
-        conceivedAt: opts.at,
-        dueAt: opts.at + Math.round(days * MINUTES_PER_DAY),
-        seed: opts.seed,
+        conceivedAt: at,
+        dueAt: at + Math.round(days * MINUTES_PER_DAY),
+        seed,
     };
     fam.pregnancy = pregnancy;
     return { ...pregnancy };

package/dist/impression.d.ts

@@ -6,14 +6,9 @@ export declare function outwardSigns(target: Person): OutwardSigns;
 /** What `target` says of themself: words hide more than faces (`wordsReserve`), and a limp is not mentioned. */
 export declare function selfReport(target: Person): OutwardSigns;
 /** `observer` looks at `target` at `at` (clarity 0..1: a clear look near by, or a distant figure; default 1). */
-export declare function glimpseOf(observer: Person, target: Person, at: Minute, clarity?: Unit): void;
-/** @deprecated since 2.1: pass `at` (and the optional knobs) positionally. Removed in 3.0. */
-export declare function glimpseOf(observer: Person, target: Person, opts: {
-    at: Minute;
-    clarity?: Unit;
-}): void;
+export declare function glimpsePerson(observer: Person, target: Person, at: Minute, clarity?: Unit): void;
 /** `observer` has known `target` for a long time (familiarity 0..1): traits and family ties, condensed. */
-export declare function acquaintWith(observer: Person, target: Person, familiarity: Unit, at: Minute): void;
+export declare function acquaintPerson(observer: Person, target: Person, familiarity: Unit, at: Minute): void;
 /** How sure the observer is of the things that drive an answer: traits and the state cues, 0..1. */
 export declare function impressionConfidence(observer: Person, targetId: PersonId, now: Minute): Unit;
 /**