@adam0white/human-framework 2.13.0 → 2.14.1

package/dist/agenda/agenda.js

@@ -47,7 +47,7 @@
  */
 // The bundled catalog is only the default; a host with its own catalog passes it (`World.catalog`).
 import { DEFAULT_NORMS } from '../conscience/catalog.js';
-import { clamp01, dayOf, dpow, hasNumbers, isObj } from '../core/index.js';
+import { clamp01, dayOf, dpow, hasNumbers, isNum, isObj } from '../core/index.js';
 import { expectedEffect } from '../memory/index.js';
 import { MINUTES_PER_DAY } from '../types.js';
 export const AGENDA_DEFAULTS = {
@@ -144,6 +144,20 @@ 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 };
+            if (isNum(project.peak) && project.peak >= 0 && project.peak <= 1)
+                g.project.peak = project.peak;
+        }
+        else
+            delete g.project;
+    }
     const t = g.temporal;
     if (t !== undefined &&
         !(isObj(t) &&
@@ -479,11 +493,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)
@@ -671,9 +690,17 @@ 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;
+        // onFinished runs before the host shows the result: advanced counts a contribution made from
+        // at or above the high-water mark, not a confirmed new high. Only the next perception moves
+        // the progress clock, importance and pull; the composite does not consume advanced.
+        if (g.project?.perceivedProgress) {
+            if (g.project.peak === undefined || g.progress >= g.project.peak)
+                advanced.push(g);
+            continue;
+        }
         g.progress = clamp01(g.progress + amount);
         g.lastAdvancedAt = outcome.at;
         if (g.baseImportance !== undefined)
@@ -704,6 +731,25 @@ 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 (p.projects?.behaviour === 2 && g.project.peak === undefined)
+            g.project.peak = g.progress;
+        if (progress > (g.project.peak ?? g.progress)) {
+            if (g.project.peak !== undefined)
+                g.project.peak = clamp01(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/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.13.0";
+export declare const FRAMEWORK_VERSION = "2.14.1";
 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.13.0';
+export const FRAMEWORK_VERSION = '2.14.1';
 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,8 @@
  * 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.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
+ * the earliest-ending one. 2.14.0 to 2.14.1 only stamps the version: slices without behaviour markers
+ * retain 2.14.0 crediting and an undecaying pull until the host re-enables them. 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 +71,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.14.0': {
+        to: '2.14.1',
+        note: 'version stamp only; restored projects and persistence retain 2.14.0 behaviour until explicitly re-enabled',
+        apply: stamp,
+    },
+    '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',

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,19 @@
+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;
+    readonly stallHalfLifeMinutes: 30;
+};
+/** 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,209 @@
+/**
+ * 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 keeps one refractory entry, for the most recent release. With defaults
+ * (maxMinutes 240, restMinutes 20), two releases cannot fall within one interval; with a shorter
+ * maximum, a later release can replace an earlier unexpired interval.
+ * 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.
+ * Behaviour 2 halves both terms with time since the pursued goal last advanced (or adoption),
+ * including after release and re-formation. Absent behaviour retains the 2.14.0 undecaying pull.
+ * Without the slice, it adds no state or terms.
+ */
+import { emotionLevel } from '../affect/index.js';
+import { clamp01, cmpStr, dpow, 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,
+    stallHalfLifeMinutes: 30,
+};
+const KEYS = [
+    'continueScale',
+    'switchScale',
+    'cap',
+    'switchMargin',
+    'slackMinutes',
+    'maxMinutes',
+    'restMinutes',
+    'stallHalfLifeMinutes',
+];
+function cleanSpec(input) {
+    const out = {};
+    if (!isObj(input))
+        return out;
+    for (const key of KEYS) {
+        const x = input[key];
+        const duration = key === 'slackMinutes' ||
+            key === 'maxMinutes' ||
+            key === 'restMinutes' ||
+            key === 'stallHalfLifeMinutes';
+        const min = key === 'stallHalfLifeMinutes' ? 1 : 0;
+        if (isNum(x) && x >= min && x <= (duration ? 1440 : 1))
+            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 = { behaviour: 2 };
+    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)
+        return [];
+    const goal = active(p, c.goalId);
+    if (!goal)
+        return [];
+    const stall = Math.max(0, p.now - (goal.lastAdvancedAt ?? goal.adoptedAt));
+    const decay = s.behaviour === 2 ? dpow(0.5, stall / setting(s, 'stallHalfLifeMinutes')) : 1;
+    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) * decay),
+            },
+        ];
+    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) * decay),
+        },
+    ];
+}
+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;
+    if (input.behaviour !== undefined && input.behaviour !== 2)
+        return undefined;
+    const out = {};
+    if (input.behaviour === 2)
+        out.behaviour = 2;
+    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,6 +37,8 @@ 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';
@@ -162,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)
@@ -367,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;
@@ -386,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
@@ -454,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. */
@@ -546,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.
@@ -565,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;
@@ -1021,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 };
@@ -1295,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;
@@ -1409,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,325 @@
+/**
+ * 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.
+ * Behaviour 2 credits only new perceived highs; event-credited projects cannot observe reversals and stay unchanged.
+ * 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 (host 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: [] };
+    for (const g of p.agenda.goals)
+        if (g.status === 'active' && g.project?.perceivedProgress && g.project.peak === undefined)
+            g.project.peak = g.progress;
+    state.behaviour = 2;
+    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);
+    if (s.behaviour === 2 && g.project)
+        g.project.peak = g.progress;
+    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;
+    if (input.behaviour !== undefined && input.behaviour !== 2)
+        return undefined;
+    const out = { prospects: [], history: [] };
+    if (input.behaviour === 2)
+        out.behaviour = 2;
+    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

@@ -588,6 +588,13 @@ export interface Commitment {
     recurUntil?: Minute;
 }
 export interface Goal {
+    /** Prospect identity; perceived projects receive progress only through perception. */
+    project?: {
+        prospectId: string;
+        perceivedProgress: boolean;
+        /** Highest perceived progress since adoption; presence opts this goal into net credit. */
+        peak?: Unit;
+    };
     id: string;
     label: string;
     /** Which need/value the goal serves. */
@@ -889,7 +896,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.13.0";
+export declare const ENGINE_VERSION = "2.14.1";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1006,6 +1013,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. */
@@ -1071,6 +1080,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/`. */
@@ -1206,6 +1219,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
@@ -1529,6 +1544,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`). */
@@ -1957,3 +1976,78 @@ 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 {
+    /** Absent retains 2.14.0 credit. Re-enabling, including on every load, opts into net credit. */
+    behaviour?: 2;
+    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 {
+    /** Half-life without goal progress, in minutes (default 30; valid 1..1440). */
+    stallHalfLifeMinutes?: number;
+    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 {
+    /** Absent retains the 2.14.0 pull. Re-enabling, including on every load, opts into decay. */
+    behaviour?: 2;
+    spec?: PersistenceSpec;
+    current?: Pursuit;
+    /** Most recent maximum-duration release, withheld until this minute; agenda terms stay unchanged.
+     * Defaults (maxMinutes 240, restMinutes 20) prevent two releases within one interval.
+     * A shorter maximum can let a later release replace an earlier unexpired interval. */
+    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.13.0';
+export const ENGINE_VERSION = '2.14.1';

package/package.json

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