@adam0white/human-framework 2.9.0 → 2.10.0

package/dist/person.js

@@ -1,12 +1,12 @@
 /**
  * SCOPE: the composite. `createPerson` wires every faculty's constructor; `tick` advances all faculties in
  * closed form from `p.now` to a later minute under the current activity's body load (idle awake otherwise),
- * splitting at the activity's end; `perceive` runs attention, then beliefs, relationships, judgement of
- * others' acts, memory and appraisal; `decide` scores offers and resolves the will (`answerNow` answers a
- * suggestion immediately); `begin` and `finish` bracket an activity and route the outcome into body, needs,
- * skills, habits, memory, conscience, agenda, relationships and trust in advising voices. Direct control is
- * `command`, `releaseCommand` and `previewCommand`; `knockDown` and `standUp` move a person in and out of the
- * downed state; `observeSkill` is observational learning; `setRetention` sets the per-person retention
+ * splitting at the activity's end and the absolute hourly grid; `perceive` runs attention, then beliefs,
+ * relationships, judgement of others' acts, memory and appraisal; `decide` scores offers and resolves the
+ * will (`answerNow` answers a suggestion immediately); `begin` and `finish` bracket an activity and route the
+ * outcome into body, needs, skills, habits, memory, conscience, agenda, relationships and trust in advising
+ * voices. Direct control is `command`, `releaseCommand` and `previewCommand`; `knockDown` and `standUp`
+ * move a person in and out of the downed state; `observeSkill` is observational learning; `setRetention` sets the per-person retention
  * bounds; `readPerson` is the read-only summary. Snapshot and restore live in `restore.ts`. This file owns
  * `now`, `activity`, `trace`, `nextDecision` and `retention`; every other slice is written only through its
  * owning module. It sequences the modules and makes no behavioural claims of its own beyond the engineering
@@ -21,7 +21,7 @@
  */
 import { actionTendencies, advanceAffect, appraise, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, feel, readAffect, regulate, release, skipAffect, skipCrisis, strain, tendencyEmotions, } from './affect/index.js';
 import { advanceAgenda, createAgenda, onFinished, promise, proposeGoals, revisePurposes, } from './agenda/index.js';
-import { advanceBeliefs, attend, believe, confirm, credence } from './beliefs/index.js';
+import { advanceBeliefs, applyContradiction, attend, believe, confirm, credence, noteProvenance, trustOf, } from './beliefs/index.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';
@@ -40,7 +40,7 @@ import { enablePromptings, nafsPatterns, notePromptings } from './promptings/ind
 import { bodyForecastFor, consumeConsequences, forecastLine, forecastThresholds, pruneConsequences, receiveConsequences, } from './prospection/index.js';
 import { enableReview, reviewIfDue } from './review/index.js';
 import { enableSkillRetention, learnByWatching, practise, seedSkills, } from './skills/index.js';
-import { advanceSocial, applyReputationBelief, careFor, closeness, judge, markDeceased, relationshipWith, seedRelationships, socialEvent, threatAppraisal, } from './social/index.js';
+import { advanceSocial, applyReputationBelief, careFor, closeness, judge, markDeceased, noteKnownBy, relationshipWith, seedRelationships, socialEvent, threatAppraisal, } from './social/index.js';
 import { ENGINE_VERSION, MAX_MINUTE, PERSON_SCHEMA, PHYSIOLOGICAL_NEEDS, PSYCHOLOGICAL_NEEDS, TRAIT_KEYS, VALUE_KEYS, } from './types.js';
 import { advanceWill, answerSuggestion, chargeCommand, commandTargets, createWill, creditedVoices, dischargeAdvice, dutyReviewAt, endCommand, learnFromVoice, noteCommandOutcome, predictResponse, rememberAdvice, resolveCommand, takeCommand, voicesIn, WILL_DEFAULTS, wakeReviewAt, } from './will/index.js';
 export const PERSON_DEFAULTS = {
@@ -571,9 +571,36 @@ function perceiveOne(p, pc) {
             confirm(p, claim.prop, claim.value, at);
         else
             believe(p, claim.prop, claim.value, claim.confidence, direct ? p.id : (actor ?? 'rumour'), at);
+        // Provenance (2.10.0): recorded only when the claim carries it; first acquisition wins.
+        if (claim.origin !== undefined || claim.lineage !== undefined)
+            noteProvenance(p, claim, direct ? p.id : (actor ?? 'rumour'), at);
         // Hearsay about someone's character moves my relationship with them (reputation).
         applyReputationBelief(p, claim.prop, before, credence(p, claim.prop), at);
     }
+    // Another source's account, reported by the teller (2.10.0): one source telling two people opposite things.
+    if (pc.channel === 'told' && actor !== undefined && Array.isArray(pc.reports)) {
+        // One trust basis for the whole percept: a report that lowers the reporter's own trust must not reweigh the rest.
+        const reporterTrust = trustOf(p, actor);
+        for (const r of pc.reports.slice(0, 4))
+            applyContradiction(p, { ...r, reporterId: actor, at }, reporterTrust);
+    }
+    // My own act, seen by others (2.10.0): what I believe they now think of me.
+    if (byMe && Array.isArray(pc.witnesses)) {
+        for (const w of pc.witnesses.slice(0, 8)) {
+            if (typeof w !== 'string')
+                continue;
+            if (w === p.id)
+                continue;
+            const act = { kind: pc.kind };
+            if (target !== undefined)
+                act.targetId = target;
+            if (pc.valence !== undefined)
+                act.valence = pc.valence;
+            if (pc.norms)
+                act.norms = pc.norms;
+            noteKnownBy(p, { otherId: w, act, at, via: 'seen' });
+        }
+    }
     // Advice carried by testimony keeps pulling after the speaker falls silent (standing advice, N9).
     if (pc.channel === 'told')
         rememberAdvice(p, pc);
@@ -1136,6 +1163,115 @@ export function learningFor(p, domain) {
 export function observeSkill(p, skill, minutes, modelLevel, domain) {
     return learnByWatching(p, skill, minutes, modelLevel, learningFor(p, domain), p.now);
 }
+/** Realized need changes, using readings captured before and after the outcome's deltas. */
+function realizedNeedDeltas(act, given, before, after) {
+    const aff = act.affordance;
+    const realized = {};
+    for (const id of [...PHYSIOLOGICAL_NEEDS, ...PSYCHOLOGICAL_NEEDS]) {
+        if (given[id] === undefined)
+            continue;
+        realized[id] =
+            id === 'food' || id === 'water' || id === 'relief'
+                ? levelOf(after, id) - levelOf(before, id)
+                : given[id];
+    }
+    for (const id of ['sleep', 'rest']) {
+        if (aff.advertises[id] !== undefined && given[id] === undefined) {
+            realized[id] = levelOf(after, id) - (act.needsAtStart[id] ?? levelOf(before, id));
+        }
+    }
+    return realized;
+}
+/** Record the deed and apply its appraisal, repentance, repair and regulation. */
+function respondToConscience(p, act, now, completed, minutes) {
+    const aff = act.affordance;
+    const deed = recordDeed(p, aff, act.intention, now, completed, act.necessity ? { necessity: true } : {});
+    for (const ev of deed.appraisal)
+        appraise(p, ev);
+    const tags = aff.tags ?? [];
+    if (completed && (tags.includes('worship') || tags.includes('repent'))) {
+        // Worship closes breaches against God alone; guilt toward a wronged person waits for repair.
+        const repented = new Set();
+        for (const b of p.conscience.breaches) {
+            if (!b.repaired && b.victimId === undefined && repent(p, b.id, now))
+                repented.add(b.normId);
+        }
+        for (const b of p.conscience.breaches)
+            if (!b.repaired && b.victimId !== undefined)
+                repented.delete(b.normId);
+        for (const normId of [...repented].sort())
+            release(p, { id: 'guilt', causePrefix: `breach:${normId}` }, 0.6);
+        regulate(p, minutes, 'worship');
+    }
+    if (completed && (tags.includes('repair') || tags.includes('apologize')) && aff.targetId !== undefined) {
+        recordRepair(p, aff.targetId, now);
+        release(p, { id: 'guilt', targetId: aff.targetId });
+        socialEvent(p, { at: now, kind: 'apology', otherId: aff.targetId, byMe: true, magnitude: 0.7 });
+    }
+    if (act.mode === 'sleep' || tags.includes('rest') || tags.includes('reflection')) {
+        regulate(p, minutes, tags.includes('reflection') ? 'reflection' : 'rest');
+    }
+    return { deed, tags };
+}
+/** Record relationships and character experience from a completed activity. */
+function recordParticipation(p, aff, tags, now, minutes) {
+    const D = PERSON_DEFAULTS;
+    if (p.character && (aff.with ?? []).some((o) => o !== p.id))
+        noteCharacterSocial(p, minutes);
+    const kind = tags.includes('work') ? 'shared-work' : 'chat';
+    for (const other of aff.with ?? []) {
+        if (other === p.id)
+            continue;
+        socialEvent(p, { at: now, kind, otherId: other, byMe: true, magnitude: D.participationMagnitude });
+    }
+    if (aff.targetId !== undefined && aff.targetId !== p.id) {
+        const care = tags.includes('help') ? 'help' : tags.includes('gift') ? 'gift' : undefined;
+        if (care)
+            socialEvent(p, { at: now, kind: care, otherId: aff.targetId, byMe: true, magnitude: 0.7 });
+    }
+}
+/** Learn from each advising voice after the activity's conscience and agenda results are known. */
+function learnActivityVoices(p, act, after, now, felt, broken, breached) {
+    const aff = act.affordance;
+    const D = PERSON_DEFAULTS;
+    // Trust in every voice that pushed this activity: how it felt, minus bodily harm the host's deltas do not
+    // show (needs that fell during the activity and are now urgent).
+    const voices = act.suggestions ?? (act.suggestion ? [act.suggestion] : []);
+    if (voices.length > 0) {
+        let harm = 0;
+        for (const id of ['food', 'water', 'sleep', 'rest']) {
+            if (urgencyOf(after, id) < D.voiceHarmUrgency)
+                continue;
+            harm += Math.max(0, (act.needsAtStart[id] ?? levelOf(after, id)) - levelOf(after, id));
+        }
+        // Doing what a voice pushed broke a commitment or the person's own standards: that costs the voice as harm
+        // does (review 2026-10-03: thirty broken fasts under insistence had moved trust only 0.50 -> 0.41). Omissions
+        // the push caused later (a missed prayer during a pushed activity) are not attributed here.
+        let breach = 0;
+        for (const c of broken)
+            breach += D.missedDistress * c.importance;
+        breach += D.missedDistress * 0.5 * breached;
+        for (const res of voices) {
+            const protest = res.verdict === 'complied' || res.verdict === 'commanded';
+            const reason = breach > 0
+                ? protest
+                    ? 'breach-under-protest'
+                    : 'breach'
+                : harm > 0
+                    ? protest
+                        ? 'harm-under-protest'
+                        : 'harm'
+                    : felt >= 0
+                        ? 'went-well'
+                        : 'went-badly';
+            learnFromVoice(p, res, clampSigned(felt - D.voiceHarmGain * harm - breach), {
+                at: now,
+                action: aff.action,
+                reason,
+            });
+        }
+    }
+}
 /**
  * Apply what happened. Physiological deltas go to the body, psychological ones to the needs, then skills,
  * habits, memory (expectation learning and an episode), conscience (deed, breaches, repair), agenda,
@@ -1179,20 +1315,7 @@ export function finish(p, outcome, opts = {}) {
     // Realized deltas: what the body actually took in for food/water/relief (a drink at full hydration
     // realizes nothing), host values for psychological needs, and measured since the start for sleep/rest.
     const after = readNeeds(p, readBodyOf(p));
-    const realized = {};
-    for (const id of [...PHYSIOLOGICAL_NEEDS, ...PSYCHOLOGICAL_NEEDS]) {
-        if (given[id] === undefined)
-            continue;
-        realized[id] =
-            id === 'food' || id === 'water' || id === 'relief'
-                ? levelOf(after, id) - levelOf(before, id)
-                : given[id];
-    }
-    for (const id of ['sleep', 'rest']) {
-        if (aff.advertises[id] !== undefined && given[id] === undefined) {
-            realized[id] = levelOf(after, id) - (act.needsAtStart[id] ?? levelOf(before, id));
-        }
-    }
+    const realized = realizedNeedDeltas(act, given, before, after);
     // Felt valence.
     let felt = 0;
     for (const id of Object.keys(realized)) {
@@ -1255,32 +1378,7 @@ export function finish(p, outcome, opts = {}) {
         episode.voiceId = act.suggestion.voiceId;
     remember(p, episode);
     // Conscience.
-    const deed = recordDeed(p, aff, act.intention, now, completed, act.necessity ? { necessity: true } : {});
-    for (const ev of deed.appraisal)
-        appraise(p, ev);
-    const tags = aff.tags ?? [];
-    if (completed && (tags.includes('worship') || tags.includes('repent'))) {
-        // Worship closes breaches against God alone; guilt toward a wronged person waits for repair.
-        const repented = new Set();
-        for (const b of p.conscience.breaches) {
-            if (!b.repaired && b.victimId === undefined && repent(p, b.id, now))
-                repented.add(b.normId);
-        }
-        for (const b of p.conscience.breaches)
-            if (!b.repaired && b.victimId !== undefined)
-                repented.delete(b.normId);
-        for (const normId of [...repented].sort())
-            release(p, { id: 'guilt', causePrefix: `breach:${normId}` }, 0.6);
-        regulate(p, minutes, 'worship');
-    }
-    if (completed && (tags.includes('repair') || tags.includes('apologize')) && aff.targetId !== undefined) {
-        recordRepair(p, aff.targetId, now);
-        release(p, { id: 'guilt', targetId: aff.targetId });
-        socialEvent(p, { at: now, kind: 'apology', otherId: aff.targetId, byMe: true, magnitude: 0.7 });
-    }
-    if (act.mode === 'sleep' || tags.includes('rest') || tags.includes('reflection')) {
-        regulate(p, minutes, tags.includes('reflection') ? 'reflection' : 'rest');
-    }
+    const { deed, tags } = respondToConscience(p, act, now, completed, minutes);
     // Agenda.
     const routed = { ...outcome };
     if (routed.fulfills === undefined && aff.fulfills !== undefined)
@@ -1303,58 +1401,10 @@ export function finish(p, outcome, opts = {}) {
         }
     }
     // Relationships from taking part together.
-    if (completed) {
-        if (p.character && (aff.with ?? []).some((o) => o !== p.id))
-            noteCharacterSocial(p, minutes);
-        const kind = tags.includes('work') ? 'shared-work' : 'chat';
-        for (const other of aff.with ?? []) {
-            if (other === p.id)
-                continue;
-            socialEvent(p, { at: now, kind, otherId: other, byMe: true, magnitude: D.participationMagnitude });
-        }
-        if (aff.targetId !== undefined && aff.targetId !== p.id) {
-            const care = tags.includes('help') ? 'help' : tags.includes('gift') ? 'gift' : undefined;
-            if (care)
-                socialEvent(p, { at: now, kind: care, otherId: aff.targetId, byMe: true, magnitude: 0.7 });
-        }
-    }
-    // Trust in every voice that pushed this activity: how it felt, minus bodily harm the host's deltas do not
-    // show (needs that fell during the activity and are now urgent).
-    const voices = act.suggestions ?? (act.suggestion ? [act.suggestion] : []);
-    if (voices.length > 0) {
-        let harm = 0;
-        for (const id of ['food', 'water', 'sleep', 'rest']) {
-            if (urgencyOf(after, id) < D.voiceHarmUrgency)
-                continue;
-            harm += Math.max(0, (act.needsAtStart[id] ?? levelOf(after, id)) - levelOf(after, id));
-        }
-        // Doing what a voice pushed broke a commitment or the person's own standards: that costs the voice as harm
-        // does (review 2026-10-03: thirty broken fasts under insistence had moved trust only 0.50 -> 0.41). Omissions
-        // the push caused later (a missed prayer during a pushed activity) are not attributed here.
-        let breach = 0;
-        for (const c of broken)
-            breach += D.missedDistress * c.importance;
-        breach += D.missedDistress * 0.5 * deed.breached.length;
-        for (const res of voices) {
-            const protest = res.verdict === 'complied' || res.verdict === 'commanded';
-            const reason = breach > 0
-                ? protest
-                    ? 'breach-under-protest'
-                    : 'breach'
-                : harm > 0
-                    ? protest
-                        ? 'harm-under-protest'
-                        : 'harm'
-                    : felt >= 0
-                        ? 'went-well'
-                        : 'went-badly';
-            learnFromVoice(p, res, clampSigned(felt - D.voiceHarmGain * harm - breach), {
-                at: now,
-                action: aff.action,
-                reason,
-            });
-        }
-    }
+    if (completed)
+        recordParticipation(p, aff, tags, now, minutes);
+    // Voice learning follows both conscience and agenda, so it includes their breaches.
+    learnActivityVoices(p, act, after, now, felt, broken, deed.breached.length);
     // Chronicle, while the activity is still current.
     const noted = { kept: kept.map((c) => c.id) };
     if (act.suggestion)

package/dist/prospection/prospection.js

@@ -260,9 +260,15 @@ export function sanitizeProspection(input, now, personId) {
             !minute(r.receivedAt) ||
             r.receivedAt > now)
             continue;
-        if (revisions.some((old) => identity(old, r)))
+        const validated = {
+            sourceId: r.sourceId,
+            id: r.id,
+            revision: r.revision,
+            receivedAt: r.receivedAt,
+        };
+        if (revisions.some((old) => identity(old, validated)))
             return undefined;
-        revisions.push({ sourceId: r.sourceId, id: r.id, revision: r.revision, receivedAt: r.receivedAt });
+        revisions.push(validated);
     }
     const valid = [];
     for (const e of entries) {

package/dist/restore.d.ts

@@ -1,6 +1,15 @@
 import type { Person } from './types.ts';
 /** A deep copy of the person as plain JSON (what a host saves). */
 export declare function snapshot(p: Person): Person;
+/**
+ * A deterministic 16-hex-digit digest of the canonical saved person. Canonicalization runs the saved form
+ * through `restore` (including migrations, defaults, bounds and optional-slice sanitizers), then sorts every
+ * object's keys recursively; array order stays significant. Thus key insertion order and empty optional slices
+ * that `restore` drops do not change the digest. Includes the engine stamp. Reads only; never mutates `p`.
+ * Uses 64-bit FNV-1a over JSON's UTF-16 code units, with no platform or crypto dependency. This is a change
+ * detector, not a cryptographic integrity check; collisions are possible. Invalid saves throw as in `restore`.
+ */
+export declare function fingerprint(p: Person): string;
 /**
  * Validate a saved person and fill defaults for missing or mistyped fields, slice by slice and field by
  * field. A save from an earlier supported engine is upgraded by `migrate` first. Throws on a wrong schema, a

package/dist/restore.js

@@ -8,6 +8,7 @@
  */
 import { sanitizeCrisis } from './affect/index.js';
 import { sanitizeAgenda } from './agenda/index.js';
+import { sanitizeBeliefMeta } from './beliefs/index.js';
 import { sanitizeBody, sanitizeInjuries } from './body/index.js';
 import { sanitizeCharacter } from './character/index.js';
 import { CHRONICLE_DEFAULTS, sanitizeYears } from './chronicle/index.js';
@@ -31,6 +32,26 @@ import { sanitizeWill } from './will/index.js';
 export function snapshot(p) {
     return structuredClone(p);
 }
+/**
+ * A deterministic 16-hex-digit digest of the canonical saved person. Canonicalization runs the saved form
+ * through `restore` (including migrations, defaults, bounds and optional-slice sanitizers), then sorts every
+ * object's keys recursively; array order stays significant. Thus key insertion order and empty optional slices
+ * that `restore` drops do not change the digest. Includes the engine stamp. Reads only; never mutates `p`.
+ * Uses 64-bit FNV-1a over JSON's UTF-16 code units, with no platform or crypto dependency. This is a change
+ * detector, not a cryptographic integrity check; collisions are possible. Invalid saves throw as in `restore`.
+ */
+export function fingerprint(p) {
+    const json = JSON.stringify(restore(snapshot(p)), (_key, value) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return value;
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    });
+    let hash = 0xcbf29ce484222325n;
+    for (let i = 0; i < json.length; i++) {
+        hash = BigInt.asUintN(64, (hash ^ BigInt(json.charCodeAt(i))) * 0x100000001b3n);
+    }
+    return hash.toString(16).padStart(16, '0');
+}
 // Unlike core `isObj`, arrays pass: a required slice saved as an array is filled from defaults, not refused.
 const isObject = (x) => typeof x === 'object' && x !== null;
 const isMinute = (x) => isNum(x) && Math.abs(x) <= MAX_MINUTE;
@@ -168,6 +189,7 @@ export function restore(input) {
     sanitizeCrisis(out.affect);
     sanitizeAgenda(out.agenda);
     sanitizeGists(out.memory);
+    sanitizeBeliefMeta(out.memory);
     // Optional top-level slices (1.8.0 onward), each checked by its owner.
     keepValid(out, 'chronicleYears', sanitizeYears);
     keepValid(out, 'character', sanitizeCharacter);

package/dist/sim/sim.d.ts

@@ -225,6 +225,7 @@ export declare function communityState(c: Community): CommunityState;
 /**
  * A community over `people`. With `prior` (from `communityState`, possibly through JSON), the host-side state is
  * resumed from it, so a run restored from people + community + world state continues exactly as it would have.
+ * `prior` is copied: after stepping, write back `communityState(c)`; the old `prior` stays stale.
  */
 export declare function createCommunity(people: Person[], prior?: CommunityState): Community;
 /** Add a person to a community (a newborn, an arrival); keeps the id order the driver relies on. */
@@ -237,9 +238,13 @@ export declare function birth(c: Community, a: Person, b: Person, spec: ChildSpe
 /**
  * Tell `dead`'s death at `at` to everyone alive in the community who has a tie to them (1.8.0): a told `death`
  * percept through `perceive`, so they grieve, the tie is kept and marked, and a spouse is widowed. Each listener's
- * clock must be at or before `at`; the drivers call it when they notice the death.
+ * receipt time is at least their own `now`. `late: 'now'` explicitly permits listeners past `at`, as does the
+ * existing default. `late: 'throw'` requires all eligible listeners to be at or before `at` and throws before
+ * delivering any news if one is ahead. This changes no listener's clock.
  */
-export declare function tellDeath(c: Community, dead: Person, at: Minute): void;
+export declare function tellDeath(c: Community, dead: Person, at: Minute, opts?: {
+    late?: 'throw' | 'now';
+}): void;
 /** Next minute at which this person needs attention. */
 export declare function nextEventAt(c: Community, p: Person): Minute;
 /**