@adam0white/human-framework 2.12.0 → 2.13.0

package/dist/agenda/agenda.js

@@ -154,8 +154,11 @@ function sanitizeGoalTemporal(g) {
     else if (g.temporal)
         g.temporal = { halfLifeMinutes: g.temporal.halfLifeMinutes };
 }
-/** Restore-time check of `agenda.lapse` (1.7.0), in place: a malformed one is dropped (absent means none). @internal */
+/** Restore-time check of optional lapse and firm flags; malformed values are dropped. @internal */
 export function sanitizeAgenda(a) {
+    for (const c of a.commitments)
+        if (isObj(c) && (c.firm !== true || c.kind !== 'abstain'))
+            delete c.firm;
     for (const g of a.goals)
         if (isObj(g))
             sanitizeGoalTemporal(g);

package/dist/conscience/conscience.js

@@ -22,7 +22,10 @@
  * desperation threshold, and only for acts meeting a bodily need; this is not the fast's own exemption for
  * illness and travel (2:184-185, applied in the agenda) and not the 2:173 necessity exception for forbidden
  * food. Below the threshold the abstention acts only as a negative term (agenda), so a weakly convinced person
- * can be tempted. It does not model the person's later judgment of a broken fast beyond the recorded breach.
+ * can be tempted. An opt-in `firm: true` self abstention without a linked obligatory norm instead vetoes
+ * as `rule:<label>` (id fallback). It uses the same open-window, exemption and bodily survival checks,
+ * including for self choice and insistence. It models a held rule, not a new religious ruling.
+ * It does not model the person's later judgment of a broken fast beyond the recorded breach.
  */
 import { clamp01 } from '../core/index.js';
 import { DEFAULT_NORMS, NORM_SCOPE } from './catalog.js';
@@ -251,11 +254,15 @@ export function abstentionVeto(p, aff, now, capacityLifted = false) {
         return undefined;
     const end = now + Math.max(0, aff.duration);
     for (const c of p.agenda?.commitments ?? []) {
-        if (c.kind !== 'abstain' || c.status !== 'pending' || c.exempt !== undefined || c.normId === undefined)
+        if (c.kind !== 'abstain' || c.status !== 'pending' || c.exempt !== undefined)
             continue;
         if (!(c.violatedBy?.includes(aff.action) ?? false) || now >= c.until || end <= c.from)
             continue;
-        const held = heldNorm(p, c.normId);
+        const held = c.normId === undefined ? undefined : heldNorm(p, c.normId);
+        if (c.firm === true &&
+            (c.toId === undefined || c.toId === 'self' || c.toId === p.id) &&
+            held?.standing !== 'obligatory')
+            return { kind: 'willNot', reason: `rule:${c.label ?? c.id}` };
         if (held?.standing !== 'obligatory' || held.conviction < CONSCIENCE_DEFAULTS.abstainVetoConviction)
             continue;
         return { kind: 'willNot', reason: `duty:${c.normId}` };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.12.0";
+export declare const FRAMEWORK_VERSION = "2.13.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, PrayerCalendar, PrayerSchedule, PrayerTimes, Retimer, } from './agenda/index.ts';

package/dist/index.js

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export const FRAMEWORK_VERSION = '2.12.0';
+export const FRAMEWORK_VERSION = '2.13.0';
 export { AFFECT_DEFAULTS, actionTendencies, advanceAffect, appraise, breakAllows, breakBehaviour, breakHazard, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, enableBreaks, feel, inBreak, readAffect, regulate, release as releaseEmotion, skipCrisis, strain, tendencyEmotions, } from './affect/index.js';
 // `agenda.release` collides with `affect.release`; the agenda one is re-exported under a clearer name.
 export { AGENDA_DEFAULTS, abandonGoal, adoptGoal, advanceAgenda, agendaTerms, applyExemptions, CARE_DEFAULTS, calendarRetimer, careDuty, commitmentPressure, createAgenda, DEFAULT_PRAYER_TIMES, EID_PRAYER_IMPORTANCE, EXEMPTION_DEFAULTS, eidPrayer, eidWindow, fastWindow, iftarWindow, inMakruhTime, isUnderWay, MAKRUH_DEFAULTS, makruhWindows, missedExcuse, onFinished, owedMakeUps, PRAYER_IMPORTANCE, PURPOSE_DEFAULTS, prayerWindows, pressureReachedAt, promise, proposeGoals, RAMADAN_DEFAULTS, ramadanFast, ramadanMeals, release as releaseCommitment, retimeCommitments, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.js';

package/dist/migrate.js

@@ -18,7 +18,7 @@
  * version; fullness stays absent unless enabled, and alongside partners and reconsideration are opt-in.
  * 2.8.0 to 2.9.0 stamps the version; prompting cues and practice half-lives stay absent unless supplied,
  * review terms may carry refs, and an outcome naming several commitments now keeps each rather than only
- * the earliest-ending one. 2.11.0 to 2.12.0 stamps the version (planning starts absent). 2.10.0 to 2.11.0 stamps the version (curiosity starts absent). 2.9.0 to 2.10.0 stamps the version; belief provenance, noted contradictions and
+ * the earliest-ending one. 2.12.0 to 2.13.0 stamps the version (suggestion reasons and firm rules start absent). 2.11.0 to 2.12.0 stamps the version (planning starts absent). 2.10.0 to 2.11.0 stamps the version (curiosity starts absent). 2.9.0 to 2.10.0 stamps the version; belief provenance, noted contradictions and
  * believed regard stay absent unless a host supplies them;
  * `regard` becomes a reserved impression cue key. A migrated save continues under the current engine's rules: it restores and runs,
  * but it does not reproduce what the old engine would have done next where the rules changed (1.4.0 to 1.5.0
@@ -70,6 +70,11 @@ export const MIGRATIONS = {
         note: 'the surroundings field `ambient.now` is renamed `ambient.percept`; per-person retention is optional and starts absent; behaviour unchanged',
         apply: renameAmbient,
     },
+    '2.12.0': {
+        to: '2.13.0',
+        note: 'suggestion reasons (Person.will.suggestionReasons) and firm self-rules (Commitment.firm) are optional and start absent; existing hosts retain exact behavior',
+        apply: stamp,
+    },
     '2.11.0': {
         to: '2.12.0',
         note: 'the planning slice (Person.planning) is optional and starts absent; retained consequences may carry channel known only when seeded; existing hosts retain exact behavior',

package/dist/person.js

@@ -43,7 +43,7 @@ import { enableReview, reviewIfDue } from './review/index.js';
 import { enableSkillRetention, learnByWatching, practise, seedSkills, } from './skills/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';
+import { advanceWill, answerSuggestion, chargeCommand, commandTargets, createWill, creditedVoices, dischargeAdvice, dutyReviewAt, enableSuggestionReasons, endCommand, learnFromVoice, noteCommandOutcome, predictResponse, rememberAdvice, resolveCommand, takeCommand, voicesIn, WILL_DEFAULTS, wakeReviewAt, } from './will/index.js';
 export const PERSON_DEFAULTS = {
     /** Body load while idle and awake. */
     idleLoad: { effort: 0.05, focus: 0.05, mode: 'awake' },
@@ -148,6 +148,8 @@ export function createPerson(spec) {
     if (family)
         p.family = family;
     const on = spec.enable;
+    if (on?.suggestionReasons)
+        enableSuggestionReasons(p);
     if (on?.gists)
         enableGists(p);
     if (on?.yearbook)

package/dist/types.d.ts

@@ -563,6 +563,8 @@ export interface Commitment {
     label?: string;
     /** For kind 'abstain': action ids whose completion inside the window breaks it. */
     violatedBy?: string[];
+    /** Firm self abstention: a will-not, lifted for bodily survival like a norm abstention. */
+    firm?: true;
     /** For kind 'abstain': catalogued conditions under which the person may not hold it that day. */
     exemptWhen?: ('illness' | 'travel')[];
     /**
@@ -700,6 +702,8 @@ export interface VoiceTrustEvent {
  * impulse emerges from competing terms, real fatigue costs, habits and precommitments.
  */
 export interface WillState {
+    /** Opt-in score explanations on suggestion resolutions; absent preserves legacy JSON. */
+    suggestionReasons?: true;
     voices: VoiceRelation[];
     /**
      * Precommitments the person made for themselves (e.g. "no work after Isha", "walk instead of eat when bored"):
@@ -885,7 +889,7 @@ export declare const PERSON_SCHEMA = "human/person@1";
  * and an activity that would cover a closing stretch is reviewed when the stretch begins (`isUnderWay`,
  * `dutyReviewAt`). Person shape unchanged.
  */
-export declare const ENGINE_VERSION = "2.12.0";
+export declare const ENGINE_VERSION = "2.13.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1374,6 +1378,12 @@ export type SuggestionVerdict = 'assented' | 'complied' | 'deferred' | 'modified
 /** Refusal class for UI: grey = cannot, amber = notNow, red = willNot. */
 export type RefusalKind = 'cannot' | 'notNow' | 'willNot';
 export interface SuggestionResolution {
+    /** Read-only score explanation, only with `enableSuggestionReasons`; margin includes activity inertia. */
+    decidedBy?: {
+        kind: 'inertia' | 'term';
+        source?: string;
+        margin: number;
+    };
     voiceId: EntityId;
     verdict: SuggestionVerdict;
     kind?: RefusalKind;
@@ -1501,6 +1511,8 @@ export interface PersonSpec {
      * `enableCharacterChange` and `enableSkillRetention` right after `createPerson`. Each is off when absent.
      */
     enable?: {
+        /** Read-only suggestion score explanations, as with `enableSuggestionReasons(p)`. */
+        suggestionReasons?: boolean;
         gists?: boolean;
         yearbook?: boolean;
         character?: boolean;

package/dist/types.js

@@ -120,4 +120,4 @@ export const PERSON_SCHEMA = 'human/person@1';
  * and an activity that would cover a closing stretch is reviewed when the stretch begins (`isUnderWay`,
  * `dutyReviewAt`). Person shape unchanged.
  */
-export const ENGINE_VERSION = '2.12.0';
+export const ENGINE_VERSION = '2.13.0';

package/dist/will/will.d.ts

@@ -266,6 +266,13 @@ export declare function dominantTerm(c: Considered | undefined): string;
  * sorted by voice id and bounded by `maxVoices`, so the outcome never depends on the host's argument order.
  */
 export declare function voicesIn(single: Suggestion | undefined, list: readonly Suggestion[] | undefined): Suggestion[];
+/**
+ * SCOPE (suggestion reasons): opt-in read-only explanations of score-based deferrals and modifications.
+ * The gap includes running-activity inertia; source differences aggregate like-labelled terms and tie by
+ * source string. This does not change selection, voice wording, counters or RNG, explain vetoes, or claim
+ * a score caused a lower-scoring stochastic choice. Legacy resolutions have no additional keys.
+ */
+export declare function enableSuggestionReasons(p: Person): void;
 /** Whether a command names offer `aff` (by affordance id, or by action class when it names no affordance). */
 export declare const commandTargets: (cmd: Command, aff: Affordance) => boolean;
 /**

package/dist/will/will.js

@@ -36,7 +36,7 @@ import { breakAllows, inBreak } from '../affect/index.js';
 import { commitmentPressure, isUnderWay, pressureReachedAt } from '../agenda/index.js';
 import { downedAllows, readCapacities } from '../body/index.js';
 import { CONSCIENCE_DEFAULTS, normVeto } from '../conscience/index.js';
-import { clamp01, cmpStr, decay, dexp, dpow, hasNumbers, isObj, random } from '../core/index.js';
+import { clamp01, cmpStr, decay, dexp, dpow, hasNumbers, isObj, random, round } from '../core/index.js';
 import { skillLevel } from '../skills/index.js';
 import { MINUTES_PER_DAY, MINUTES_PER_HOUR } from '../types.js';
 export const WILL_DEFAULTS = {
@@ -160,6 +160,8 @@ export const WILL_DEFAULTS = {
  * or `lastCommand` (1.6.0, 1.7.0) are dropped (absent means none). A save the engine wrote is unchanged. @internal
  */
 export function sanitizeWill(w) {
+    if (w.suggestionReasons !== true)
+        delete w.suggestionReasons;
     if (w.advice !== undefined && !Array.isArray(w.advice))
         delete w.advice;
     const cmd = w.command;
@@ -721,6 +723,43 @@ function arbitrateCommand(p, ctx, cmd, suggestions, prepared, selection, ev) {
     }
     return false;
 }
+/**
+ * SCOPE (suggestion reasons): opt-in read-only explanations of score-based deferrals and modifications.
+ * The gap includes running-activity inertia; source differences aggregate like-labelled terms and tie by
+ * source string. This does not change selection, voice wording, counters or RNG, explain vetoes, or claim
+ * a score caused a lower-scoring stochastic choice. Legacy resolutions have no additional keys.
+ */
+export function enableSuggestionReasons(p) {
+    p.will.suggestionReasons = true;
+}
+function scoreReason(selection, live, targetIds) {
+    const { winner, ranked, score } = selection;
+    if (!winner)
+        return undefined;
+    // A stochastic draw below the best live score was not decided by the scores.
+    if (ranked.some((c) => !c.vetoed && score(c) > score(winner)))
+        return undefined;
+    // Compare against the closest suggested option by the same adjusted score the winner was chosen on.
+    const suggested = [...live].sort((a, b) => score(b) - score(a) || cmpStr(a.affordanceId, b.affordanceId))[0];
+    if (!suggested)
+        return undefined;
+    const gap = score(winner) - score(suggested);
+    if (!Number.isFinite(gap) || gap < 0)
+        return undefined;
+    const margin = round(gap);
+    const withoutInertia = [...ranked].sort(byUtilityThenId)[0];
+    if (score(winner) > winner.utility && withoutInertia && targetIds.has(withoutInertia.affordanceId))
+        return { kind: 'inertia', margin };
+    const differences = new Map();
+    for (const t of winner.terms)
+        differences.set(t.source, (differences.get(t.source) ?? 0) + t.value);
+    for (const t of suggested.terms)
+        differences.set(t.source, (differences.get(t.source) ?? 0) - t.value);
+    const term = [...differences]
+        .filter(([, value]) => value > 0)
+        .sort((a, b) => b[1] - a[1] || cmpStr(a[0], b[0]))[0];
+    return { kind: 'term', ...(term ? { source: term[0] } : {}), margin };
+}
 /** Judge each voice against the same selected option before resolving competing insistence. */
 function judgeVoices(p, ctx, suggestions, prepared, selection) {
     const W = WILL_DEFAULTS;
@@ -829,17 +868,21 @@ function judgeVoices(p, ctx, suggestions, prepared, selection) {
         }
         side.pressure = W.pressurePush * clamp01(s.strength);
         side.refused = 1;
+        const decidedBy = p.will.suggestionReasons ? scoreReason(selection, liveSuggested, targetIds) : undefined;
+        const explanation = decidedBy ? { decidedBy } : {};
         const near = winnerAff !== undefined &&
             suggestedAff !== undefined &&
             (winnerAff.action === suggestedAff.action ||
                 (mainAim(suggestedAff) !== undefined && mainAim(suggestedAff) === mainAim(winnerAff)));
         if (near && winnerAff)
             return out(resolution('modified', reason, {
+                ...explanation,
                 kind: 'notNow',
                 insteadAffordanceId: winnerAff.id,
                 counterOffer: { affordanceId: winnerAff.id, label: winnerAff.label },
             }));
         return out(resolution('deferred', reason, {
+            ...explanation,
             kind: 'notNow',
             insteadAffordanceId: winnerAff?.id,
             counterOffer: winnerAff
@@ -865,6 +908,9 @@ function arbitrateInsistence(p, judged, considered, affById, ev) {
             forcer = j;
     }
     if (forcer?.comply) {
+        // The final option is imposed by insistence, not selected by scores.
+        for (const j of judged)
+            delete j.res.decidedBy;
         const forced = forcer.comply.target.affordanceId;
         const forcedAff = affById.get(forced);
         ev.chosenId = forced;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adam0white/human-framework",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Deterministic, explainable simulated people: body, needs, affect, memory, beliefs, skills, habits, relationships, values and a will that can refuse a suggestion",
   "keywords": [
     "simulation",