@adam0white/human-framework 2.12.0 → 2.14.0

package/dist/agenda/agenda.js

@@ -144,6 +144,17 @@ function copyArrays(c) {
  */
 /** Copy valid temporal settings and drop invalid ones at every agenda entry point. */
 function sanitizeGoalTemporal(g) {
+    const project = g.project;
+    if (project !== undefined) {
+        if (isObj(project) &&
+            typeof project.prospectId === 'string' &&
+            project.prospectId.length > 0 &&
+            project.prospectId.length <= 512 &&
+            typeof project.perceivedProgress === 'boolean')
+            g.project = { prospectId: project.prospectId, perceivedProgress: project.perceivedProgress };
+        else
+            delete g.project;
+    }
     const t = g.temporal;
     if (t !== undefined &&
         !(isObj(t) &&
@@ -154,8 +165,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);
@@ -476,11 +490,16 @@ function heldConviction(p, c) {
  * keeps by the same rule, so a pull never leads to an activity that cannot keep the commitment.
  */
 export const spanMeetsWindow = (c, start, end) => start <= c.until && end >= c.from;
+/** Explicit host progress can name either the adopted goal or its perceived prospect. */
+function namesGoal(g, advances) {
+    return ((advances?.includes(g.id) ?? false) ||
+        (g.project !== undefined && (advances?.includes(g.project.prospectId) ?? false)));
+}
 function goalAmount(g, aff) {
     const own = g.advancedBy.find((a) => a.action === aff.action);
     if (own)
         return own.amount;
-    return aff.advances?.includes(g.id) ? AGENDA_DEFAULTS.defaultAdvanceAmount : 0;
+    return namesGoal(g, aff.advances) ? AGENDA_DEFAULTS.defaultAdvanceAmount : 0;
 }
 function deadlinePressure(g, now) {
     if (g.deadline === undefined)
@@ -668,9 +687,14 @@ export function onFinished(p, outcome, startedAt = outcome.at, opts = {}) {
         if (g.status !== 'active')
             continue;
         const own = g.advancedBy.find((a) => a.action === outcome.action)?.amount ?? 0;
-        const amount = own > 0 ? own : outcome.advances?.includes(g.id) ? AGENDA_DEFAULTS.defaultAdvanceAmount : 0;
+        const amount = own > 0 ? own : namesGoal(g, outcome.advances) ? AGENDA_DEFAULTS.defaultAdvanceAmount : 0;
         if (amount <= 0)
             continue;
+        // Credit the contribution for narration/reward, but only perception sets this project's progress.
+        if (g.project?.perceivedProgress) {
+            advanced.push(g);
+            continue;
+        }
         g.progress = clamp01(g.progress + amount);
         g.lastAdvancedAt = outcome.at;
         if (g.baseImportance !== undefined)
@@ -701,6 +725,21 @@ export function adoptGoal(p, g, now) {
     p.agenda.goals.push(goal);
     return goal;
 }
+/** Attended host progress is authoritative for an active perceived-progress project. @internal */
+export function perceiveProjectProgress(p, prospectId, progress, now) {
+    for (const g of p.agenda.goals) {
+        if (g.status !== 'active' || !g.project?.perceivedProgress || g.project.prospectId !== prospectId)
+            continue;
+        if (progress > g.progress) {
+            g.lastAdvancedAt = now;
+            if (g.baseImportance !== undefined)
+                g.importance = g.baseImportance;
+        }
+        g.progress = clamp01(progress);
+        if (g.progress >= 1)
+            g.status = 'achieved';
+    }
+}
 export function abandonGoal(p, id) {
     const g = p.agenda.goals.find((x) => x.id === id);
     if (g?.status !== 'active')

package/dist/cognition/cognition.js

@@ -46,6 +46,7 @@ import { expectedEffect } from '../memory/index.js';
 import { methodEvidence } from '../methods/index.js';
 import { levelOf, needThreshold, urgencyOf } from '../needs/index.js';
 import { partneringTerms } from '../partnering/index.js';
+import { persistenceTerms } from '../persistence/index.js';
 import { promptIn, promptingTerms } from '../promptings/index.js';
 import { bodyForecastTerm, receivedGoalRoute } from '../prospection/index.js';
 import { reviewTerms } from '../review/index.js';
@@ -461,6 +462,9 @@ export function consider(p, aff, ctx) {
     if (p.curiosity)
         for (const t of curiosityTerms(p, aff, ctx))
             push(t.source, t.value);
+    if (p.pursuit)
+        for (const t of persistenceTerms(p, terms, ctx))
+            push(t.source, t.value);
     // Promptings (2.4.0, opt-in): a recurrence pull under `fault` and a practised turning-away from a noticed prompt.
     if (p.promptings)
         for (const t of promptingTerms(p, aff.action, terms, aff.tags, ctx.now, ctx.desperation))

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.14.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';
@@ -28,7 +28,9 @@ export { MIGRATIONS, migratableVersions, migrate } from './migrate.ts';
 export * from './narrate/index.ts';
 export * from './needs/index.ts';
 export * from './partnering/index.ts';
+export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistence/index.ts';
 export * from './person.ts';
+export { considerProjects, enableProjects, PROJECTS_DEFAULTS, projectAppeal } from './projects/index.ts';
 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';

package/dist/index.js

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export const FRAMEWORK_VERSION = '2.12.0';
+export const FRAMEWORK_VERSION = '2.14.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';
@@ -25,7 +25,9 @@ export { MIGRATIONS, migratableVersions, migrate } from './migrate.js';
 export * from './narrate/index.js';
 export * from './needs/index.js';
 export * from './partnering/index.js';
+export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistence/index.js';
 export * from './person.js';
+export { considerProjects, enableProjects, PROJECTS_DEFAULTS, projectAppeal } from './projects/index.js';
 export * from './promptings/index.js';
 export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, enablePlanning, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, seedConsequences, } from './prospection/index.js';
 export { fingerprint, restore, snapshot } from './restore.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.13.0 to 2.14.0 stamps the version (projects and persistence start absent; goals may carry `project`, received successors may carry `advances`). 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,16 @@ 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.13.0': {
+        to: '2.14.0',
+        note: 'projects (Person.projects) and persistence (Person.pursuit) are optional and start absent; Goal.project, Percept.prospect and received successor advances are optional; existing hosts retain exact behavior',
+        apply: stamp,
+    },
+    '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/persistence/index.d.ts

@@ -0,0 +1 @@
+export * from './persistence.ts';

package/dist/persistence/index.js

@@ -0,0 +1 @@
+export * from './persistence.js';

package/dist/persistence/persistence.d.ts

@@ -0,0 +1,18 @@
+import type { PersistenceSpec, Person, Pursuit, PursuitState } from '../types.ts';
+/** Engineering defaults, relative to cognition's need scale 4, pleasure .6 and curiosity .8/.15.
+ * Continuation and switching together outweigh mild relaxed distraction; urgency and fear gate both.
+ * A pressing commitment has its full agenda term and pays no switching cost.
+ */
+export declare const PERSISTENCE_DEFAULTS: {
+    readonly continueScale: 0.8;
+    readonly switchScale: 0.8;
+    readonly cap: 0.8;
+    readonly switchMargin: 0.15;
+    readonly slackMinutes: 20;
+    readonly maxMinutes: 240;
+    readonly restMinutes: 20;
+};
+/** Enable or reconfigure, retaining a current pursuit. Invalid overrides use defaults. */
+export declare function enablePersistence(p: Person, spec?: PersistenceSpec): PursuitState;
+/** A copy of the current pursuit, without pruning, mutation or RNG. */
+export declare function pursuitOf(p: Person): Pursuit | undefined;

package/dist/persistence/persistence.js

@@ -0,0 +1,190 @@
+/**
+ * SCOPE: opt-in persistence of a started goal, owned only in p.pursuit. Positive goal terms cue
+ * continued means (implementation intentions: Gollwitzer 1999; Gollwitzer & Sheeran 2006), while
+ * unrelated options pay a switching cost (goal shielding: Shah, Friedman & Kruglanski 2002;
+ * task switching: Monsell 2003). Unused activation expires (Altmann & Trafton 2002); short
+ * interruptions allow resumption (Ovsiankina 1928). See research/projects-and-persistence.md.
+ * Maximum-duration release rests that goal for one bounded interval before pursuit can form again.
+ * These are shapes, not fitted values; all coefficients and time bounds are engineering defaults.
+ * This is a bounded bias plus a switching cost, not a planner. It chooses no goals, executes no
+ * plans, reorders no steps and changes no agenda valuation. It imports no projects, uses no RNG,
+ * LLM or faith lens. Needs and fear gate both terms; commitment options never pay the switch cost.
+ * Without the slice, it adds no state or terms.
+ */
+import { emotionLevel } from '../affect/index.js';
+import { clamp01, cmpStr, isNum, isObj, round } from '../core/index.js';
+import { MAX_MINUTE, PHYSIOLOGICAL_NEEDS } from '../types.js';
+/** Engineering defaults, relative to cognition's need scale 4, pleasure .6 and curiosity .8/.15.
+ * Continuation and switching together outweigh mild relaxed distraction; urgency and fear gate both.
+ * A pressing commitment has its full agenda term and pays no switching cost.
+ */
+export const PERSISTENCE_DEFAULTS = {
+    continueScale: 0.8,
+    switchScale: 0.8,
+    cap: 0.8,
+    switchMargin: 0.15,
+    slackMinutes: 20,
+    maxMinutes: 240,
+    restMinutes: 20,
+};
+const KEYS = [
+    'continueScale',
+    'switchScale',
+    'cap',
+    'switchMargin',
+    'slackMinutes',
+    'maxMinutes',
+    'restMinutes',
+];
+function cleanSpec(input) {
+    const out = {};
+    if (!isObj(input))
+        return out;
+    for (const key of KEYS) {
+        const x = input[key];
+        const max = key === 'slackMinutes' || key === 'maxMinutes' || key === 'restMinutes' ? 1440 : 1;
+        if (isNum(x) && x >= 0 && x <= max)
+            out[key] = x;
+    }
+    return out;
+}
+const setting = (s, key) => s.spec?.[key] ?? PERSISTENCE_DEFAULTS[key];
+const identifier = (x) => typeof x === 'string' && x.length > 0 && x.length <= 512;
+const active = (p, id) => p.agenda.goals.find((g) => g.id === id && g.status === 'active');
+/** Enable or reconfigure, retaining a current pursuit. Invalid overrides use defaults. */
+export function enablePersistence(p, spec = {}) {
+    const out = {};
+    const clean = cleanSpec(spec);
+    if (Object.keys(clean).length)
+        out.spec = clean;
+    if (p.pursuit?.current)
+        out.current = { ...p.pursuit.current };
+    if (p.pursuit?.rested)
+        out.rested = { ...p.pursuit.rested };
+    p.pursuit = out;
+    return out;
+}
+/** A copy of the current pursuit, without pruning, mutation or RNG. */
+export function pursuitOf(p) {
+    return p.pursuit?.current ? { ...p.pursuit.current } : undefined;
+}
+/** Drop finished, absent, neglected or overlong pursuits. Interruptions alone do not release. @internal */
+export function releasePursuit(p) {
+    const s = p.pursuit;
+    if (!s)
+        return;
+    if (s.rested && p.now >= s.rested.until)
+        delete s.rested;
+    const c = s.current;
+    if (!c)
+        return;
+    if (!active(p, c.goalId) || p.now - c.lastServedAt >= setting(s, 'slackMinutes')) {
+        delete s.current;
+        return;
+    }
+    if (p.now - c.since >= setting(s, 'maxMinutes')) {
+        delete s.current;
+        s.rested = { goalId: c.goalId, until: Math.min(MAX_MINUTE, p.now + setting(s, 'restMinutes')) };
+    }
+}
+/** Form from the begun option's already-rounded goal terms, including route credit. @internal */
+export function beginPursuit(p, terms) {
+    const s = p.pursuit;
+    if (!s)
+        return;
+    releasePursuit(p);
+    const candidates = p.agenda.goals
+        .filter((g) => g.status === 'active' && identifier(g.id) && g.id !== s.rested?.goalId)
+        .map((goal) => ({
+        goal,
+        value: terms
+            .filter((t) => t.source === `goal:${goal.id}` && t.value > 0)
+            .reduce((v, t) => v + t.value, 0),
+    }))
+        .filter((x) => x.value > 0)
+        .sort((a, b) => b.value - a.value || cmpStr(a.goal.id, b.goal.id));
+    const best = candidates[0];
+    if (!best)
+        return;
+    const current = s.current;
+    const currentValue = candidates.find((x) => x.goal.id === current?.goalId)?.value ?? 0;
+    if (current &&
+        best.goal.id !== current.goalId &&
+        round(best.value - currentValue) <= setting(s, 'switchMargin')) {
+        if (currentValue > 0)
+            current.lastServedAt = p.now;
+        return;
+    }
+    s.current = {
+        goalId: best.goal.id,
+        since: current?.goalId === best.goal.id ? current.since : p.now,
+        lastServedAt: p.now,
+        strength: clamp01(best.goal.importance * (0.4 + 0.6 * p.traits.conscientiousness)),
+    };
+}
+/** Read already-pushed goal/commitment terms under the actual perceived needs. @internal */
+export function persistenceTerms(p, terms, ctx) {
+    const s = p.pursuit;
+    const c = s?.current;
+    if (!s || !c || !active(p, c.goalId))
+        return [];
+    let urgency = 0;
+    for (const n of ctx.needs)
+        if (n.id === 'safety' || PHYSIOLOGICAL_NEEDS.includes(n.id))
+            urgency = Math.max(urgency, n.urgency);
+    const gate = (1 - clamp01(urgency)) * (1 - emotionLevel(p, 'fear'));
+    if (terms.some((t) => t.source === `goal:${c.goalId}` && t.value > 0))
+        return [
+            {
+                source: `pursuit:${c.goalId}`,
+                value: round(Math.min(setting(s, 'cap'), setting(s, 'continueScale') * c.strength * gate)),
+            },
+        ];
+    if (terms.some((t) => t.source.startsWith('commitment:')))
+        return [];
+    return [
+        {
+            source: 'pursuit:switch',
+            value: -round(Math.min(setting(s, 'cap'), setting(s, 'switchScale') * c.strength * gate)),
+        },
+    ];
+}
+const minute = (x, now) => isNum(x) && Math.abs(x) <= MAX_MINUTE && x <= now;
+/** Conservative restore: malformed settings or pursuit drop the optional slice. @internal */
+export function sanitizePursuit(input, now) {
+    if (!isObj(input) || (input.spec !== undefined && !isObj(input.spec)))
+        return undefined;
+    const out = {};
+    if (input.spec !== undefined) {
+        const spec = cleanSpec(input.spec);
+        if (Object.keys(spec).length !== Object.keys(input.spec).length)
+            return undefined;
+        if (Object.keys(spec).length)
+            out.spec = spec;
+    }
+    const c = input.current;
+    if (c !== undefined) {
+        if (!isObj(c) ||
+            !identifier(c.goalId) ||
+            !minute(c.since, now) ||
+            !minute(c.lastServedAt, now) ||
+            c.lastServedAt < c.since ||
+            !isNum(c.strength) ||
+            c.strength < 0 ||
+            c.strength > 1)
+            return undefined;
+        out.current = { goalId: c.goalId, since: c.since, lastServedAt: c.lastServedAt, strength: c.strength };
+    }
+    const r = input.rested;
+    if (r !== undefined) {
+        if (!isObj(r) ||
+            !identifier(r.goalId) ||
+            !isNum(r.until) ||
+            Math.abs(r.until) > MAX_MINUTE ||
+            // A later reconfiguration may shorten restMinutes without shortening an existing interval.
+            r.until > now + 1440)
+            return undefined;
+        out.rested = { goalId: r.goalId, until: r.until };
+    }
+    return out;
+}

package/dist/person.js

@@ -20,14 +20,14 @@
  * long-horizon runs. Each hook calls the owning module; nothing here writes another module's slice.
  */
 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 { advanceAgenda, agendaTermsWithGoalEstimates, createAgenda, onFinished, promise, proposeGoals, revisePurposes, } from './agenda/index.js';
 import { advanceBeliefs, applyContradiction, attend, believe, confirm, credence, noteProvenance, trustOf, } from './beliefs/index.js';
 import { 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';
 import { decide as cognitionDecide, desperationOf, prospectiveRoute, scoreAll } from './cognition/index.js';
 import { createConscience, guiltLoad, heldNorms, normVeto, recordDeed, recordRepair, repent, } from './conscience/index.js';
-import { clamp01, clampSigned, createRng, dayOf, isObj, minuteOfDay } from './core/index.js';
+import { clamp01, clampSigned, createRng, dayOf, isObj, minuteOfDay, round } from './core/index.js';
 import { enableCuriosity, noteCuriosity } from './curiosity/index.js';
 import { ambientBodyParams, ambientModifiers, ambientMood, ambientNeeds } from './environment/index.js';
 import { aptitudeOf, createFamily, pregnancyModifiers } from './family/index.js';
@@ -37,13 +37,15 @@ import { advanceMemory, createMemory, enableGists, foldGists, learnOutcome, reca
 import { intentionFor, narrateDecision, voiceLine } from './narrate/index.js';
 import { advanceNeeds, createNeeds, levelOf, meanSatisfaction, readNeeds, satisfy, urgencyOf, } from './needs/index.js';
 import { widow } from './partnering/index.js';
+import { beginPursuit, enablePersistence, releasePursuit } from './persistence/index.js';
+import { considerProjects, enableProjects, noteProjectStatus, perceiveProspect } from './projects/index.js';
 import { enablePromptings, nafsPatterns, notePromptings } from './promptings/index.js';
 import { bodyForecastFor, consumeConsequences, enablePlanning, 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, 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 +150,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)
@@ -160,8 +164,12 @@ export function createPerson(spec) {
         enableFatigueStore(p);
     if (on?.fullness)
         enableFullness(p);
+    if (on?.projects)
+        enableProjects(p, on.projects === true ? {} : on.projects);
     if (on?.curiosity)
         enableCuriosity(p, on.curiosity === true ? {} : on.curiosity);
+    if (on?.persistence)
+        enablePersistence(p, on.persistence === true ? {} : on.persistence);
     if (on?.planning)
         enablePlanning(p, on.planning);
     if (on?.promptings)
@@ -365,11 +373,15 @@ function recordKeptAbstentions(p, kept, now) {
  * rounding (~1e-9) unless calls also fall on the grid, in which case replay is byte-identical.
  */
 export function tick(p, now) {
+    if (p.pursuit)
+        releasePursuit(p);
     if (now <= p.now)
         return;
     if (!p.body.alive) {
         p.now = now;
         pruneConsequences(p);
+        if (p.pursuit)
+            releasePursuit(p);
         return;
     }
     const seg = PERSON_DEFAULTS.maxSegment;
@@ -384,15 +396,21 @@ export function tick(p, now) {
         if (!(end > p.now)) {
             p.now = now;
             pruneConsequences(p);
+            if (p.pursuit)
+                releasePursuit(p);
             return;
         }
         advanceSegment(p, end - p.now, load, active && act ? act.affordance : undefined);
         p.now = end;
         pruneConsequences(p);
+        if (p.pursuit)
+            releasePursuit(p);
         if (!p.body.alive) {
             p.activity = null;
             p.now = now;
             pruneConsequences(p);
+            if (p.pursuit)
+                releasePursuit(p);
             return;
         }
         // Discrete bookkeeping runs only on grid boundaries, so it happens at the same minutes whatever the
@@ -452,6 +470,10 @@ export function tick(p, now) {
                 }
             }
         }
+        if (p.projects)
+            considerProjects(p, end);
+        if (p.pursuit)
+            releasePursuit(p);
     }
 }
 /** The composite's side of the hourly crisis check: interrupt and remember an onset, remember a recovery. */
@@ -544,6 +566,8 @@ export function skip(p, to) {
     skipBody(p, to);
     p.now = to;
     pruneConsequences(p);
+    if (p.pursuit)
+        releasePursuit(p);
     skipAffect(p, to);
     advanceAgenda(p, to);
     // Lasting gists (1.8.0, opt-in): episodes now past the horizon fold into gists.
@@ -563,6 +587,8 @@ function socialKindOf(kind) {
 }
 function perceiveOne(p, pc) {
     receiveConsequences(p, pc);
+    if (p.projects && pc.prospect)
+        perceiveProspect(p, pc.prospect, pc.at);
     const at = Math.min(Math.max(pc.at, p.affect.lastUpdated), p.now);
     const actor = pc.actorId;
     const target = pc.targetId;
@@ -1019,6 +1045,20 @@ export function begin(p, aff, record, opts = {}) {
     if (!p.body.alive)
         return null;
     const now = p.now;
+    if (p.pursuit) {
+        const considered = record.considered.find((c) => c.affordanceId === aff.id);
+        let terms = considered?.terms;
+        if (!terms) {
+            const { ctx } = decisionInputs(p, [aff], record.id, {});
+            const route = prospectiveRoute(p, aff, ctx);
+            const scale = 0.5 + 0.5 * clamp01(ctx.mods.maturity);
+            terms = agendaTermsWithGoalEstimates(p, aff, now, route?.goals).map((t) => ({
+                source: t.source,
+                value: round(t.value * scale),
+            }));
+        }
+        beginPursuit(p, terms);
+    }
     const duration = Number.isFinite(aff.duration) ? Math.max(1, Math.round(aff.duration)) : 1;
     const mode = aff.mode ?? 'awake';
     const load = { effort: clamp01(aff.effort), focus: clamp01(aff.focus ?? 0), mode };
@@ -1293,6 +1333,8 @@ function learnActivityVoices(p, act, after, now, felt, broken, breached) {
  * relationships, trust in the advising voice, injuries and illness. Clears the activity.
  */
 export function finish(p, outcome, opts = {}) {
+    if (p.pursuit)
+        releasePursuit(p);
     const act = p.activity;
     if (!act)
         return null;
@@ -1407,6 +1449,10 @@ export function finish(p, outcome, opts = {}) {
         ...(act.necessity ? { necessity: true } : {}),
         ...(opts.catalog ? { catalog: opts.catalog } : {}),
     });
+    if (p.projects)
+        noteProjectStatus(p, now);
+    if (p.pursuit)
+        releasePursuit(p);
     // A completed violating action inside an open abstention's window broke it (the fast, e.g. "no work after the evening prayer").
     if (broken.length > 0) {
         recordMissed(p, broken, now, outcome.action);

package/dist/projects/index.d.ts

@@ -0,0 +1 @@
+export * from './projects.ts';

package/dist/projects/index.js

@@ -0,0 +1 @@
+export * from './projects.js';

package/dist/projects/projects.d.ts

@@ -0,0 +1,23 @@
+import type { Minute, Person, ProjectsSpec, ProjectsState, Prospect } from '../types.ts';
+export declare const PROJECTS_DEFAULTS: {
+    readonly maxProspects: 8;
+    readonly maxHistory: 8;
+    readonly forgetMinutes: 1440;
+    readonly calmUrgency: 0.35;
+    readonly fearBelow: 0.35;
+    readonly adoptEveryMinutes: 30;
+    readonly cooldownMinutes: 60;
+    readonly adoptAppeal: 0.3;
+    readonly halfLifeMinutes: 120;
+    readonly staleMinutes: 180;
+};
+/** Enable or reconfigure without discarding retained prospects and history. */
+export declare function enableProjects(p: Person, spec?: ProjectsSpec): ProjectsState;
+/** Read-only, deterministic appeal. Thresholds close the relaxed gate before the bounded bonus. */
+export declare function projectAppeal(p: Person, prospect: Prospect, now?: Minute): number;
+/** Only the composite calls this, after attention. Newest event minute wins; equal-minute input order wins. */
+export declare function perceiveProspect(p: Person, input: Prospect, at: Minute): void;
+/** Called on each tick segment, including one-minute begin/tick/finish host loops. No RNG. */
+export declare function considerProjects(p: Person, now: Minute): void;
+/** Conservative restore: bounded fields, finite past timestamps, and no ambiguous duplicate ids. */
+export declare function sanitizeProjects(input: unknown, now: Minute): ProjectsState | undefined;

package/dist/projects/projects.js

@@ -0,0 +1,314 @@
+/**
+ * SCOPE: self-set, bounded pursuits from host-shown, attended prospects. Fit to temperament and
+ * relaxed needs chooses one project; perceived progress or completed acts advances it; neglect drops
+ * it. Shapes, not fitted values: Little's personal projects (1983), Locke & Latham's goal setting
+ * (2002), autonomy/competence in Deci & Ryan and Ryan & Deci (2000), constructive play (Smilansky
+ * 1968; Burghardt 2005), and interrupted-task resumption (Ovsiankina 1928). The resumption bonus
+ * models a pull to continue, not a Zeigarnik memory advantage. See research/projects-and-persistence.md.
+ * All thresholds and coefficients are engineering defaults. This owns only p.projects; agenda owns
+ * goals. All kinds serve competence and leisure: making is chosen as a free-time pursuit, not duty.
+ * Restore recovers one active project, keeping the newest (id breaks ties) and abandoning extras.
+ * No invented prospects, host task interpretation, world search, persistence, shielding, faith lens,
+ * LLM or RNG. Without the slice, perception and minute bookkeeping write nothing.
+ */
+import { emotionLevel } from '../affect/index.js';
+import { AGENDA_DEFAULTS, abandonGoal, adoptGoal, perceiveProjectProgress } from '../agenda/index.js';
+import { clamp01, cmpStr, isNum, isObj, round } from '../core/index.js';
+import { curiosityOf } from '../curiosity/index.js';
+import { readPerson } from '../person.js';
+import { MAX_MINUTE, PHYSIOLOGICAL_NEEDS } from '../types.js';
+export const PROJECTS_DEFAULTS = {
+    maxProspects: 8,
+    maxHistory: 8,
+    forgetMinutes: 1440,
+    calmUrgency: 0.35,
+    fearBelow: 0.35,
+    adoptEveryMinutes: 30,
+    cooldownMinutes: 60,
+    adoptAppeal: 0.3,
+    halfLifeMinutes: 120,
+    staleMinutes: 180,
+};
+const KEYS = [
+    'forgetMinutes',
+    'calmUrgency',
+    'fearBelow',
+    'adoptEveryMinutes',
+    'cooldownMinutes',
+    'adoptAppeal',
+    'halfLifeMinutes',
+    'staleMinutes',
+];
+function cleanSpec(input) {
+    const out = {};
+    if (!isObj(input))
+        return out;
+    for (const key of KEYS) {
+        const x = input[key];
+        const unit = key === 'calmUrgency' || key === 'fearBelow' || key === 'adoptAppeal';
+        if (isNum(x) && x >= (unit ? 0 : 1) && x <= (unit ? 1 : 525600))
+            out[key] = x;
+    }
+    return out;
+}
+const setting = (s, key) => s.spec?.[key] ?? PROJECTS_DEFAULTS[key];
+const str = (x) => typeof x === 'string' && x.length > 0 && x.length <= 512;
+const unit = (x) => isNum(x) && x >= 0 && x <= 1;
+const minute = (x, now) => isNum(x) && Math.abs(x) <= MAX_MINUTE && x <= now;
+function cleanProspect(x) {
+    if (!isObj(x) ||
+        !str(x.id) ||
+        !str(x.label) ||
+        !['make', 'arrange', 'gather', 'finish'].includes(x.kind) ||
+        (x.placeId !== undefined && !str(x.placeId)) ||
+        (x.progress !== undefined && !unit(x.progress)) ||
+        (x.materialIds !== undefined &&
+            (!Array.isArray(x.materialIds) || x.materialIds.length > 256 || !x.materialIds.every(str))))
+        return undefined;
+    const p = { id: x.id, label: x.label, kind: x.kind };
+    if (x.placeId !== undefined)
+        p.placeId = x.placeId;
+    if (x.progress !== undefined)
+        p.progress = x.progress;
+    // A long list is kept, not rejected: the first eight distinct ids in the host's order (island rerun, 2026-10-20).
+    if (x.materialIds !== undefined)
+        p.materialIds = [...new Set(x.materialIds)].slice(0, 8);
+    return p;
+}
+/** Enable or reconfigure without discarding retained prospects and history. */
+export function enableProjects(p, spec = {}) {
+    const state = p.projects ?? { prospects: [], history: [] };
+    const clean = cleanSpec(spec);
+    delete state.spec;
+    if (Object.keys(clean).length)
+        state.spec = clean;
+    p.projects = state;
+    return state;
+}
+function relaxed(p) {
+    const needs = readPerson(p).needs;
+    return {
+        urgency: Math.max(0, ...needs
+            .filter((n) => n.id === 'safety' || PHYSIOLOGICAL_NEEDS.includes(n.id))
+            .map((n) => n.urgency)),
+        fear: emotionLevel(p, 'fear'),
+        interest: Math.max(0, ...needs.filter((n) => ['leisure', 'competence', 'autonomy'].includes(n.id)).map((n) => n.urgency)),
+    };
+}
+/** Read-only, deterministic appeal. Thresholds close the relaxed gate before the bounded bonus. */
+export function projectAppeal(p, prospect, now = p.now) {
+    const s = p.projects;
+    if (!s ||
+        !cleanProspect(prospect) ||
+        prospect.progress === 1 ||
+        p.body.asleep ||
+        p.activity?.mode === 'sleep' ||
+        !p.body.alive)
+        return 0;
+    const { urgency, fear, interest } = relaxed(p);
+    if (urgency >= setting(s, 'calmUrgency') || fear >= setting(s, 'fearBelow'))
+        return 0;
+    const gate = (1 - urgency) * (1 - fear);
+    const fit = 0.25 + 0.75 * (prospect.kind === 'finish' ? p.traits.conscientiousness : p.traits.openness);
+    const resume = prospect.progress !== undefined && prospect.progress > 0 && prospect.progress < 1 ? 0.1 : 0;
+    const bonus = p.curiosity
+        ? 0.05 *
+            clamp01(curiosityOf(p, {
+                id: prospect.id,
+                action: prospect.kind,
+                label: prospect.label,
+                duration: 1,
+                effort: 0,
+                advertises: {},
+            }, now).drive)
+        : 0;
+    return round(clamp01(gate * (fit * (0.5 + 0.5 * interest) + resume + bonus)));
+}
+function recordProjectStatus(p, g, now) {
+    const s = p.projects;
+    if (!s || !g.project || g.status === 'active')
+        return;
+    if (!s.history.some((h) => h.goalId === g.id))
+        s.history.push({
+            prospectId: g.project.prospectId,
+            goalId: g.id,
+            adoptedAt: g.adoptedAt,
+            outcome: g.status,
+            at: now,
+        });
+    if (g.status === 'abandoned')
+        s.lastAbandonedAt = now;
+    else {
+        // Completed event-progress projects have no host progress reading: retain the known completion.
+        const prospect = s.prospects.find((x) => x.id === g.project?.prospectId);
+        if (prospect)
+            prospect.progress = 1;
+    }
+    if (s.history.length > PROJECTS_DEFAULTS.maxHistory)
+        s.history.shift();
+    if (s.currentGoalId === g.id)
+        delete s.currentGoalId;
+}
+/** Record the adopted project's terminal state once, even after history eviction. @internal */
+export function noteProjectStatus(p, now) {
+    const s = p.projects;
+    if (!s?.currentGoalId)
+        return;
+    const g = p.agenda.goals.find((g) => g.id === s.currentGoalId);
+    if (!g?.project)
+        delete s.currentGoalId;
+    else
+        recordProjectStatus(p, g, now);
+}
+/** Only the composite calls this, after attention. Newest event minute wins; equal-minute input order wins. */
+export function perceiveProspect(p, input, at) {
+    const s = p.projects;
+    if (!s || !minute(at, p.now))
+        return;
+    const prospect = cleanProspect(input);
+    if (!prospect)
+        return;
+    const old = s.prospects.find((x) => x.id === prospect.id);
+    if (old && old.lastSeenAt > at)
+        return;
+    if (p.now - at > setting(s, 'forgetMinutes'))
+        return;
+    const held = { ...prospect, lastSeenAt: at };
+    if (old)
+        s.prospects[s.prospects.indexOf(old)] = held;
+    else {
+        if (s.prospects.length >= PROJECTS_DEFAULTS.maxProspects) {
+            let oldest = 0;
+            for (const [i, entry] of s.prospects.entries())
+                if (entry.lastSeenAt < (s.prospects[oldest]?.lastSeenAt ?? Infinity))
+                    oldest = i;
+            s.prospects.splice(oldest, 1);
+        }
+        s.prospects.push(held);
+    }
+    if (prospect.progress !== undefined)
+        perceiveProjectProgress(p, prospect.id, prospect.progress, p.now);
+    noteProjectStatus(p, p.now);
+}
+/** Called on each tick segment, including one-minute begin/tick/finish host loops. No RNG. */
+export function considerProjects(p, now) {
+    const s = p.projects;
+    if (!s || !minute(now, p.now))
+        return;
+    s.prospects = s.prospects.filter((x) => now - x.lastSeenAt <= setting(s, 'forgetMinutes'));
+    for (const g of p.agenda.goals)
+        if (g.project &&
+            g.status === 'active' &&
+            now - (g.lastAdvancedAt ?? g.adoptedAt) >= setting(s, 'staleMinutes')) {
+            abandonGoal(p, g.id);
+            recordProjectStatus(p, g, now);
+        }
+    noteProjectStatus(p, now);
+    const active = p.agenda.goals.filter((g) => g.status === 'active');
+    if (active.some((g) => g.project) ||
+        active.length >= AGENDA_DEFAULTS.maxActiveGoals ||
+        p.agenda.commitments.some((c) => c.status === 'pending' && c.from <= now && c.until >= now) ||
+        (s.lastAdoptedAt !== undefined && now - s.lastAdoptedAt < setting(s, 'adoptEveryMinutes')) ||
+        (s.lastAbandonedAt !== undefined && now - s.lastAbandonedAt < setting(s, 'cooldownMinutes')))
+        return;
+    const best = s.prospects
+        .map((prospect) => ({ prospect, appeal: projectAppeal(p, prospect, now) }))
+        .filter((x) => x.appeal > setting(s, 'adoptAppeal'))
+        .sort((a, b) => b.appeal - a.appeal || cmpStr(a.prospect.id, b.prospect.id))[0];
+    if (!best)
+        return;
+    const { prospect, appeal } = best;
+    const g = adoptGoal(p, {
+        label: prospect.label,
+        serves: ['competence', 'leisure'],
+        advancedBy: [],
+        importance: Math.max(0.3, Math.min(0.7, appeal)),
+        temporal: { halfLifeMinutes: setting(s, 'halfLifeMinutes') },
+        project: { prospectId: prospect.id, perceivedProgress: prospect.progress !== undefined },
+    }, now);
+    if (prospect.progress !== undefined)
+        perceiveProjectProgress(p, prospect.id, prospect.progress, now);
+    s.lastAdoptedAt = now;
+    s.currentGoalId = g.id;
+}
+/** Conservative restore: bounded fields, finite past timestamps, and no ambiguous duplicate ids. */
+export function sanitizeProjects(input, now) {
+    if (!isObj(input) || !Array.isArray(input.prospects) || !Array.isArray(input.history))
+        return undefined;
+    const out = { prospects: [], history: [] };
+    if (input.spec !== undefined) {
+        if (!isObj(input.spec))
+            return undefined;
+        const spec = cleanSpec(input.spec);
+        if (Object.keys(spec).length !== Object.keys(input.spec).length)
+            return undefined;
+        if (Object.keys(spec).length)
+            out.spec = spec;
+    }
+    for (const key of ['lastAdoptedAt', 'lastAbandonedAt']) {
+        if (input[key] === undefined)
+            continue;
+        if (!minute(input[key], now))
+            return undefined;
+        out[key] = input[key];
+    }
+    if (input.currentGoalId !== undefined) {
+        if (!str(input.currentGoalId))
+            return undefined;
+        out.currentGoalId = input.currentGoalId;
+    }
+    const seen = new Set();
+    for (const entry of input.prospects.slice(0, PROJECTS_DEFAULTS.maxProspects)) {
+        const prospect = cleanProspect(entry);
+        if (!prospect || !isObj(entry) || !minute(entry.lastSeenAt, now))
+            continue;
+        if (seen.has(prospect.id))
+            return undefined;
+        seen.add(prospect.id);
+        if (now - entry.lastSeenAt <= setting(out, 'forgetMinutes'))
+            out.prospects.push({ ...prospect, lastSeenAt: entry.lastSeenAt });
+    }
+    seen.clear();
+    for (const h of input.history.slice(-PROJECTS_DEFAULTS.maxHistory)) {
+        if (!isObj(h) ||
+            !str(h.prospectId) ||
+            !str(h.goalId) ||
+            !minute(h.at, now) ||
+            !minute(h.adoptedAt, h.at) ||
+            (h.outcome !== 'achieved' && h.outcome !== 'abandoned'))
+            continue;
+        if (seen.has(h.goalId))
+            return undefined;
+        seen.add(h.goalId);
+        out.history.push({
+            prospectId: h.prospectId,
+            goalId: h.goalId,
+            adoptedAt: h.adoptedAt,
+            outcome: h.outcome,
+            at: h.at,
+        });
+    }
+    return out;
+}
+/** Sanitize and reconcile agenda ownership deterministically, without RNG. @internal */
+export function restoreProjects(p) {
+    const s = sanitizeProjects(p.projects, p.now);
+    if (!s) {
+        delete p.projects;
+        return;
+    }
+    p.projects = s;
+    noteProjectStatus(p, p.now);
+    const active = p.agenda.goals
+        .filter((g) => g.project && g.status === 'active')
+        .sort((a, b) => b.adoptedAt - a.adoptedAt || cmpStr(a.id, b.id));
+    for (const g of active.slice(1)) {
+        abandonGoal(p, g.id);
+        recordProjectStatus(p, g, p.now);
+    }
+    const kept = active[0];
+    if (kept)
+        s.currentGoalId = kept.id;
+    else
+        delete s.currentGoalId;
+}

package/dist/prospection/prospection.js

@@ -88,6 +88,10 @@ function consequence(x, receivedAt) {
         s.duration < 0 ||
         s.duration > PROSPECTION_DEFAULTS.horizon ||
         !unit(s.effort) ||
+        (s.advances !== undefined &&
+            (!Array.isArray(s.advances) ||
+                s.advances.length > 8 ||
+                !s.advances.every((x) => typeof x === 'string' && x.length > 0 && x.length <= 512))) ||
         (s.focus !== undefined && !unit(s.focus)) ||
         (s.materialCost !== undefined &&
             (!isNum(s.materialCost) || s.materialCost < 0 || s.materialCost > PROSPECTION_DEFAULTS.maxMaterialCost)))
@@ -110,6 +114,7 @@ function consequence(x, receivedAt) {
             ...successorAction,
             duration: s.duration,
             effort: s.effort,
+            ...(s.advances !== undefined ? { advances: [...s.advances] } : {}),
             ...(s.focus !== undefined ? { focus: s.focus } : {}),
             ...(s.materialCost !== undefined ? { materialCost: s.materialCost } : {}),
         },

package/dist/restore.js

@@ -21,7 +21,9 @@ import { GIST_DEFAULTS, MEMORY_DEFAULTS, sanitizeGists } from './memory/index.js
 import { sanitizeMethods } from './methods/index.js';
 import { migrate } from './migrate.js';
 import { sanitizeBonds } from './partnering/index.js';
+import { sanitizePursuit } from './persistence/index.js';
 import { cleanRetention, createPerson, traceLimit } from './person.js';
+import { restoreProjects } from './projects/index.js';
 import { sanitizePromptings } from './promptings/index.js';
 import { sanitizePlanning, sanitizeProspection } from './prospection/index.js';
 import { sanitizeReview } from './review/index.js';
@@ -88,6 +90,8 @@ const OPTIONAL_KEYS = new Set([
     'planning',
     'promptings',
     'curiosity',
+    'projects',
+    'pursuit',
     'review',
 ]);
 /** Kind of a JSON value for the per-field type check in `restore`. */
@@ -205,6 +209,8 @@ export function restore(input) {
     keepValid(out, 'planning', sanitizePlanning);
     keepValid(out, 'prospection', (x) => sanitizeProspection(x, out.now, out.id, out.planning !== undefined));
     keepValid(out, 'curiosity', (x) => sanitizeCuriosity(x, out.now));
+    restoreProjects(out);
+    keepValid(out, 'pursuit', (x) => sanitizePursuit(x, out.now));
     keepValid(out, 'promptings', (x) => sanitizePromptings(x, out.now));
     keepValid(out, 'review', (x) => sanitizeReview(x, out.now));
     boundLists(out);

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')[];
     /**
@@ -586,6 +588,11 @@ export interface Commitment {
     recurUntil?: Minute;
 }
 export interface Goal {
+    /** Prospect identity; perceived projects receive progress only through perception. */
+    project?: {
+        prospectId: string;
+        perceivedProgress: boolean;
+    };
     id: string;
     label: string;
     /** Which need/value the goal serves. */
@@ -700,6 +707,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 +894,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.14.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1002,6 +1011,8 @@ export interface ReceivedConsequence {
         effort: Unit;
         focus?: Unit;
         materialCost?: number;
+        /** Goal or prospect ids this successor contributes to (bounded to 8). */
+        advances?: string[];
     };
     availableFrom: Minute;
     /** Latest permitted successor completion, inclusive. */
@@ -1067,6 +1078,10 @@ export interface Person {
     promptings?: PromptingsState;
     /** Intrinsic exploration and varied repetition. Owned by `curiosity/`; absent unless enabled. */
     curiosity?: CuriosityState;
+    /** Self-set projects from attended prospects; owned by projects/. */
+    projects?: ProjectsState;
+    /** Keeping a started goal active. Owned by persistence/; absent unless enabled. */
+    pursuit?: PursuitState;
     /** Evening self-review and its resolves (2.7.0, opt-in via `enableReview`). Owned by `review/`. */
     review?: ReviewState;
     /** Practice consolidation (1.8.0, opt-in via `enableSkillRetention`). Owned by `skills/`. */
@@ -1202,6 +1217,8 @@ export interface Affordance {
 }
 /** Something a person perceives. Hosts emit percepts; attention decides which are encoded. */
 export interface Percept {
+    /** Host-shown opportunity, retained only with projects enabled and when attended. */
+    prospect?: Prospect;
     at: Minute;
     /**
      * How it reached the person: seen, heard, told (testimony), felt (bodily), the result of an action
@@ -1374,6 +1391,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 +1524,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;
@@ -1517,6 +1542,10 @@ export interface PersonSpec {
         planning?: PlanningSpec;
         /** Evening self-review (2.7.0): the same as `enableReview(p, spec)` after creation. */
         review?: ReviewSpec;
+        /** Self-set projects from what the person attends to. */
+        projects?: boolean | ProjectsSpec;
+        /** Keep started goal pursuits across decisions. */
+        persistence?: boolean | PersistenceSpec;
     };
 }
 /** A known span of exertion after an act (see `Affordance.followedBy`). */
@@ -1945,3 +1974,70 @@ export interface CuriosityReading {
     vary: Unit;
     drive: number;
 }
+/** A bounded pursuit opportunity explicitly shown by the host. */
+export interface Prospect {
+    id: string;
+    label: string;
+    kind: 'make' | 'arrange' | 'gather' | 'finish';
+    placeId?: EntityId;
+    /** Up to 256 accepted; the first eight distinct ids are retained. */
+    materialIds?: EntityId[];
+    progress?: Unit;
+}
+export interface ProjectsSpec {
+    forgetMinutes?: number;
+    calmUrgency?: Unit;
+    fearBelow?: Unit;
+    adoptEveryMinutes?: number;
+    cooldownMinutes?: number;
+    adoptAppeal?: Unit;
+    halfLifeMinutes?: number;
+    staleMinutes?: number;
+}
+export interface ProjectHistory {
+    prospectId: string;
+    goalId: string;
+    adoptedAt: Minute;
+    outcome: 'achieved' | 'abandoned';
+    at: Minute;
+}
+/** Optional bounded JSON state owned by projects/. */
+export interface ProjectsState {
+    spec?: ProjectsSpec;
+    prospects: (Prospect & {
+        lastSeenAt: Minute;
+    })[];
+    history: ProjectHistory[];
+    lastAdoptedAt?: Minute;
+    lastAbandonedAt?: Minute;
+    /** The adopted goal awaiting its one terminal history entry. */
+    currentGoalId?: string;
+}
+/** Bounded engineering overrides for persistence/. Invalid overrides use defaults. */
+export interface PersistenceSpec {
+    continueScale?: number;
+    switchScale?: number;
+    cap?: number;
+    switchMargin?: number;
+    slackMinutes?: number;
+    maxMinutes?: number;
+    /** Refractory interval for the same goal after maximum-duration release (default 20 minutes). */
+    restMinutes?: number;
+}
+/** A started goal retained across decisions. */
+export interface Pursuit {
+    goalId: string;
+    since: Minute;
+    lastServedAt: Minute;
+    strength: Unit;
+}
+/** Optional JSON state owned by persistence/: one current pursuit and one refractory goal. */
+export interface PursuitState {
+    spec?: PersistenceSpec;
+    current?: Pursuit;
+    /** One goal withheld from pursuit formation until this minute; agenda terms remain unchanged. */
+    rested?: {
+        goalId: string;
+        until: Minute;
+    };
+}

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.14.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.14.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",