@adam0white/human-framework 2.16.0 → 2.17.0

package/README.md

@@ -410,6 +410,7 @@ Knowledge lives in optional `Person.prospection` and survives snapshot/restore.
 `projectPersona(source, mapping)` produces `PersonaProjectionSnapshot` (`hf-persona-state/1`).
 `admitPersona(projection, targetOpening, { mappingVersion, sourceId, targetId })` returns a detached
 `{ person, report }`. `validatePersonaProjection(unknown)` validates portable data without filling defaults.
+Portable v1 accepts the published 2.14.1 source-engine stamp and the current engine; it preserves that source provenance. Unknown source engines remain rejected.
 These functions never enter the actor loop and never mutate the source or the host opening.
 
 The host supplies a versioned map of skill ids, selected episode ids and every continuing obligation.
@@ -459,3 +460,19 @@ returning a detached Person. The receiving calendar must be empty; authored role
 admission, the host uses ordinary agenda APIs and its declared calendar. No duty is waived, no new ruling
 is invented, and no obligation is converted to a score. Activities, projects and incompatible identity or
 health remain unsupported. The original passport format and no-call continuation remain unchanged.
+
+### Project protection and narration options
+
+Projects can opt into undo protection with `enableProjects(person, { protectProgress: true })`.
+Declare `diminishes: [prospectId]` on an offer or its described successor, or let the person
+learn the exact action context from a perceived drop after its own completed act.
+`adoptProjectTask(person, prospectId, task)` reuses an active project and its net credit
+for a host task; an absent match returns `undefined`.
+
+Narration remains unchanged unless requested. Set `person.lexicon.variety`,
+`nounActions` or `materialMeaning` for the corresponding host wording. Use
+`promptingLine(reading, outcome, kind, { voice: 'third' })` for plain third-person lines.
+`converse` adds per-call `loyalWarning`, `confidentMin` and `phrase` options;
+`perceive` adds a third `{ reputationTraits }` argument. See the architecture's
+[narration and social host options](../../docs/framework.md#narration-and-social-host-options-opt-in)
+for cause-aware reviews and actor-addressed recall. These options change no default continuation.

package/dist/agenda/agenda.js

@@ -49,6 +49,7 @@
 import { DEFAULT_NORMS } from '../conscience/catalog.js';
 import { clamp01, dayOf, dpow, hasNumbers, isNum, isObj } from '../core/index.js';
 import { expectedEffect } from '../memory/index.js';
+import { diminishesProject } from '../projects/index.js';
 import { MINUTES_PER_DAY } from '../types.js';
 export const AGENDA_DEFAULTS = {
     /** Minutes before a window opens during which a commitment already pulls (to get there). */
@@ -527,6 +528,8 @@ function goalValue(g, aff, now) {
 }
 /** Opt-in completion-time and success estimate, shared by direct and received routes. @internal */
 export function temporalGoalValue(p, g, aff, now, completion) {
+    if (g.project && diminishesProject(p, aff, g.project.prospectId))
+        return 0;
     const base = goalValue(g, aff, now);
     return g.temporal
         ? base *
@@ -578,7 +581,7 @@ export function agendaTermsWithGoalEstimates(p, aff, now, goalOverrides) {
         terms.push({ source: `commitment:${c.id}`, value: d.commitmentScale * c.importance * pressure });
     }
     for (const g of p.agenda.goals) {
-        if (g.status !== 'active')
+        if (g.status !== 'active' || (g.project && diminishesProject(p, aff, g.project.prospectId)))
             continue;
         const override = goalOverrides?.get(g.id);
         if (override !== undefined || g.temporal) {

package/dist/conversation/conversation.d.ts

@@ -55,6 +55,12 @@ export interface ConverseContext {
     traits?: Record<string, TraitEffect>;
     /** Carry belief origin and opaque lineage into told claims (off by default). */
     provenance?: boolean;
+    /** Relay beliefs this far from 0.5 (0..0.5); default 0.2. Invalid values use the default. */
+    confidentMin?: number;
+    /** Let a fond speaker warn the listener of an unfavourable character claim about them. */
+    loyalWarning?: boolean;
+    /** Presentation only. Receives a told claim or a withheld reason and its default summary; never changes selection. */
+    phrase?: (claim: Readonly<ToldClaim | WithheldClaim>, summary: string) => string;
 }
 /** Host-visible record of one claim. */
 export interface ToldClaim {
@@ -80,6 +86,12 @@ export interface AdviceGiven {
     /** For the listener's next decision; the voice is the speaker. */
     suggestion: Suggestion;
 }
+export interface WithheldClaim {
+    prop: string;
+    reason: string;
+    /** Present only when a host phrasing callback rendered this reason. */
+    summary?: string;
+}
 export interface ConversationResult {
     /** Testimony percepts for `perceive(listener, told)`. */
     told: Percept[];
@@ -87,10 +99,7 @@ export interface ConversationResult {
     advice: AdviceGiven[];
     claims: ToldClaim[];
     /** Candidate claims the speaker held back, and why (e.g. 'norm:backbiting', 'norm:lying'). */
-    withheld: {
-        prop: string;
-        reason: string;
-    }[];
+    withheld: WithheldClaim[];
     /** True when any told claim was a lie. */
     deceit: boolean;
     /** The speaker's own deed tags for conscience (e.g. backbiting/lying violated), deduplicated, sorted. */

package/dist/conversation/conversation.js

@@ -21,6 +21,10 @@
  * share of conversation about absent third parties that spreads reputational information (Dunbar 2004), and
  * extraversion as talkativeness (how many claims are offered).
  *
+ * SCOPE (host options): `loyalWarning` admits only unfavourable listener claims when affection is at least
+ * 0.5 (an engineering threshold). `confidentMin` sets a per-call relay threshold. `phrase` renders selected
+ * testimony only; the host owns authored facts, delivery and subsequent disclosure. No hidden relay occurs.
+ *
  * It does NOT generate language, model turn-taking, persuasion beyond source trust, what the speaker believes
  * the listener already knows, lies of omission, white lies told to spare feelings, or the speaker's fear of
  * being found out. Coefficients are engineering defaults, not calibrated estimates. Nothing here judges the
@@ -150,12 +154,25 @@ export function converse(speaker, listener, ctx) {
         if (b.prop.startsWith('advice:') || b.prop.includes(':should:'))
             continue;
         const subject = b.prop.split(':')[0];
-        if (subject === listener.id || subject === speaker.id)
+        if (subject === speaker.id)
             continue;
         const cred = expit(b.logOdds);
-        if (Math.abs(cred - 0.5) < C.confidentMin)
+        const threshold = Number.isFinite(ctx.confidentMin) &&
+            ctx.confidentMin >= 0 &&
+            ctx.confidentMin <= 0.5
+            ? ctx.confidentMin
+            : C.confidentMin;
+        if (Math.abs(cred - 0.5) < threshold)
             continue;
         const value = cred > 0.5;
+        if (subject === listener.id) {
+            const trait = parseTraitProp(b.prop, table)?.trait;
+            if (!ctx.loyalWarning ||
+                relationshipWith(speaker, listener.id).affection < 0.5 ||
+                trait === undefined ||
+                !isUnfavourableTrait(trait, value, table))
+                continue;
+        }
         const confidence = value ? cred : 1 - cred;
         const recency = 1 / (1 + Math.max(0, ctx.at - b.updatedAt) / C.recencyScale);
         consider(b.prop, value, confidence, cred, false, R.confidence * (confidence - 0.5) * 2 + R.recency * recency);
@@ -231,6 +248,8 @@ export function converse(speaker, listener, ctx) {
                 ? `${nameOf(speaker)} says ${c.about} is ${c.value ? '' : 'not '}${c.prop.split(':')[1] ?? ''}`
                 : `${nameOf(speaker)} says ${c.prop} is ${c.value ? 'so' : 'not so'}`,
         };
+        if (ctx.phrase)
+            pc.summary = ctx.phrase(Object.freeze(structuredClone(c)), pc.summary ?? '');
         const claim = pc.claims?.[0];
         if (claim && c.origin !== undefined)
             claim.origin = c.origin;
@@ -292,6 +311,9 @@ export function converse(speaker, listener, ctx) {
             suggestion.appeal = 'benevolence';
         out.advice.push({ action: a.action, percept, suggestion });
     }
+    if (ctx.phrase)
+        for (const withheld of out.withheld)
+            withheld.summary = ctx.phrase(Object.freeze(structuredClone(withheld)), withheld.reason);
     const magnitude = clamp01((ctx.magnitude ?? C.chatMagnitude) + C.chatPerClaim * out.told.length);
     out.socialEvents.speaker.push({ at: ctx.at, kind: 'chat', otherId: listener.id, byMe: true, magnitude });
     out.socialEvents.listener.push({ at: ctx.at, kind: 'chat', otherId: speaker.id, byMe: false, magnitude });

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.16.0";
+export declare const FRAMEWORK_VERSION = "2.17.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, MakeUpReceipt, PrayerCalendar, PrayerSchedule, PrayerTimes, Retimer, } from './agenda/index.ts';
@@ -32,7 +32,7 @@ export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistenc
 export * from './person.ts';
 export * from './persona.ts';
 export * from './persona-calendar.ts';
-export { considerProjects, enableProjects, PROJECTS_DEFAULTS, projectAppeal } from './projects/index.ts';
+export { adoptProjectTask, 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.16.0';
+export const FRAMEWORK_VERSION = '2.17.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, isContinuingCommitment, isUnderWay, MAKRUH_DEFAULTS, makruhWindows, missedExcuse, onFinished, owedMakeUps, PRAYER_IMPORTANCE, PURPOSE_DEFAULTS, prayerWindows, pressureReachedAt, promise, proposeGoals, RAMADAN_DEFAULTS, ramadanFast, ramadanMeals, release as releaseCommitment, retimeCommitments, retirePaidMakeUps, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.js';
@@ -29,7 +29,7 @@ export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistenc
 export * from './person.js';
 export * from './persona.js';
 export * from './persona-calendar.js';
-export { considerProjects, enableProjects, PROJECTS_DEFAULTS, projectAppeal } from './projects/index.js';
+export { adoptProjectTask, 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

@@ -71,6 +71,11 @@ export const MIGRATIONS = {
         note: 'the surroundings field `ambient.now` is renamed `ambient.percept`; per-person retention is optional and starts absent; behaviour unchanged',
         apply: renameAmbient,
     },
+    '2.14.1': {
+        to: '2.17.0',
+        note: 'version stamp only; project protection and narration/social options require explicit opt-in, and existing enabled faculties retain exact behavior',
+        apply: stamp,
+    },
     '2.14.0': {
         to: '2.14.1',
         note: 'version stamp only; restored projects and persistence retain 2.14.0 behaviour until explicitly re-enabled',

package/dist/narrate/lexicon.js

@@ -34,6 +34,23 @@ export const EN_LINES = {
     // Decision lines by other dominant sources.
     'source:habit': ['Same as always.', 'Out of habit, really.', "It's what I do at this hour."],
     'source:effort': ['The easy thing, for now.', 'Nothing strenuous.'],
+    'review.cause': [
+        'After {cause}, {missed} remained undone. {next}',
+        'I left {missed} unfinished after {cause}. {next}',
+        'I was {cause}; {missed} went unfinished. {next}',
+    ],
+    'review.accounting': [
+        "I didn't keep {missed}. Next time I'll be ready when it comes.",
+        'I left {missed} undone. I will prepare for the next occasion.',
+        'Today {missed} went unfinished. Next time I will make room for it.',
+    ],
+    'review.ruminating': [
+        'I keep going back over {missed}.',
+        'My thoughts keep returning to {missed}.',
+        'I cannot stop turning {missed} over in my mind.',
+    ],
+    'source:material.named': ['It brings {material}.', 'We can use the {material}.'],
+    'intention.material.named': ['for {material}'],
     'source:material': ['There is money in it.', 'It pays.'],
     'source:expectation': ['It went well last time.', 'I know how this goes.'],
     'source:conscience:repair': ['I owe them that much.', 'I have to make this right.'],
@@ -363,6 +380,12 @@ function regularGerund(verb) {
 export function actionForms(action, lexicon) {
     const given = lexicon?.actions?.[action];
     const base = given?.base ?? action.replace(/[-_]/g, ' ');
+    if (lexicon?.nounActions)
+        return {
+            base: given?.base ?? `do ${base}`,
+            past: given?.past ?? `did ${base}`,
+            gerund: given?.gerund ?? `doing ${base}`,
+        };
     const [verb = base, ...rest] = base.split(' ');
     const tail = rest.length > 0 ? ` ${rest.join(' ')}` : '';
     return {

package/dist/narrate/narrate.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionRecord, Lexicon, Person, SuggestionResolution } from '../types.ts';
+import type { DecisionRecord, Episode, Lexicon, Person, SuggestionResolution } from '../types.ts';
 /** Intention string for a decision: 'for Allah', 'to feed myself', 'to keep my promise to X', ... */
 export declare function intentionFor(p: Person, record: DecisionRecord, lexicon?: Lexicon): string;
 /** First-person narration of a decision record. Deterministic by the decision id. */
@@ -7,3 +7,9 @@ export declare function narrateDecision(p: Person, record: DecisionRecord, lexic
 export declare function voiceLine(p: Person, res: SuggestionResolution, key?: string, lexicon?: Lexicon): string;
 /** Short UI summary of a person's state. */
 export declare function describePerson(p: Person, lexicon?: Lexicon): string;
+/**
+ * SCOPE: a host-authored addressee form of an episode, selected only for its named actor.
+ * Free text cannot safely be inflected. With no authored form, return the original summary.
+ * This read-only helper neither recalls an episode nor changes its salience or RNG.
+ */
+export declare function recallLine(episode: Episode, toActor: string): string;

package/dist/narrate/narrate.js

@@ -93,7 +93,9 @@ export function intentionFor(p, record, lexicon) {
         case 'emotion':
             return phraseLine('intention.emotion', {}, lex);
         case 'material':
-            return phraseLine('intention.material', {}, lex);
+            return lex?.materialMeaning !== undefined
+                ? phraseLine('intention.material.named', { material: lex.materialMeaning }, lex)
+                : phraseLine('intention.material', {}, lex);
         case 'precommit':
             return phraseLine('intention.precommit', {}, lex);
         case 'expectation':
@@ -157,6 +159,8 @@ export function narrateDecision(p, record, lexicon) {
             ? pickLine(`emotion:${tag}`, id, {}, lex)
             : pickLine('emotion:default', id, {}, lex));
     }
+    else if (kind === 'material' && lex?.materialMeaning !== undefined)
+        parts.push(pickLine('source:material.named', id, { material: lex.materialMeaning }, lex));
     else
         parts.push(linesFor(`source:${source}`, lex).length > 0
             ? pickLine(`source:${source}`, id, {}, lex)
@@ -192,6 +196,8 @@ export function narrateDecision(p, record, lexicon) {
 /** The person's spoken reply to a suggestion. */
 export function voiceLine(p, res, key = res.reason, lexicon) {
     const lex = lexicon ?? p.lexicon;
+    if (lex?.variety && (res.verdict === 'assented' || res.verdict === 'deferred'))
+        key = `${p.id}:${p.now}:${p.traits.extraversion}:${p.traits.honesty}:${key}`;
     const trust = p.will.voices.find((v) => v.voiceId === res.voiceId)?.trust ?? 0.5;
     switch (res.verdict) {
         case 'assented':
@@ -293,3 +299,13 @@ export function describePerson(p, lexicon) {
     const state = bits.length > 0 ? bits.join(', ') : phraseLine('describe.well', {}, lex);
     return phraseLine('describe.line', { name: p.name, act, state }, lex);
 }
+/**
+ * SCOPE: a host-authored addressee form of an episode, selected only for its named actor.
+ * Free text cannot safely be inflected. With no authored form, return the original summary.
+ * This read-only helper neither recalls an episode nor changes its salience or RNG.
+ */
+export function recallLine(episode, toActor) {
+    return episode.actorId === toActor && episode.addressedSummary !== undefined
+        ? episode.addressedSummary
+        : episode.summary;
+}

package/dist/person.d.ts

@@ -1,6 +1,7 @@
 import { type BodyForecastSpan } from './body/index.ts';
 import { type NafsPattern } from './promptings/index.ts';
 import { type SkillTransfer } from './skills/index.ts';
+import { applyReputationBelief } from './social/index.ts';
 import type { Activity, Affordance, BodyLoad, BodyReadout, Command, Commitment, DecisionRecord, LearningDomain, Minute, NeedId, NeedReading, NormDefinition, Outcome, Percept, Person, PersonSpec, Retention, Suggestion, SuggestionResolution, Unit } from './types.ts';
 import { type CommandOutcome } from './will/index.ts';
 export declare const PERSON_DEFAULTS: {
@@ -85,12 +86,16 @@ export declare function standUp(p: Person): boolean;
  * only age (from `life.bornAt`) changes. Hosts that want the interval lived call `tick`.
  */
 export declare function skip(p: Person, to: Minute): void;
+export interface PerceiveOptions {
+    /** Complete host character-trait vocabulary; absent uses HF's default table. */
+    reputationTraits?: Parameters<typeof applyReputationBelief>[5];
+}
 /**
  * Attend to percepts (limited capacity), then encode what got through: claims into beliefs, interactions
  * into relationships, others' acts judged by my norms, appraisal into emotions, and an episode each.
  * Returns the percepts that were attended to.
  */
-export declare function perceive(p: Person, percepts: readonly Percept[]): Percept[];
+export declare function perceive(p: Person, percepts: readonly Percept[], options?: PerceiveOptions): Percept[];
 export interface DecideOptions {
     suggestion?: Suggestion;
     /** Several voices in one decision (N1); merged with `suggestion`, one per voice id. */

package/dist/person.js

@@ -38,7 +38,7 @@ 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 { considerProjects, enableProjects, noteProjectAct, 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';
@@ -585,10 +585,10 @@ function socialKindOf(kind) {
         return kind;
     return SOCIAL_ALIASES[kind];
 }
-function perceiveOne(p, pc) {
+function perceiveOne(p, pc, options) {
     receiveConsequences(p, pc);
     if (p.projects && pc.prospect)
-        perceiveProspect(p, pc.prospect, pc.at);
+        perceiveProspect(p, pc.prospect, pc.at, (pc.channel === 'saw' || pc.channel === 'outcome') && (pc.actorId === undefined || pc.actorId === p.id));
     const at = Math.min(Math.max(pc.at, p.affect.lastUpdated), p.now);
     const actor = pc.actorId;
     const target = pc.targetId;
@@ -606,7 +606,7 @@ function perceiveOne(p, pc) {
         if (claim.origin !== undefined || claim.lineage !== undefined)
             noteProvenance(p, claim, direct ? p.id : (actor ?? 'rumour'), at);
         // Hearsay about someone's character moves my relationship with them (reputation).
-        applyReputationBelief(p, claim.prop, before, credence(p, claim.prop), at);
+        applyReputationBelief(p, claim.prop, before, credence(p, claim.prop), at, options.reputationTraits);
     }
     // Another source's account, reported by the teller (2.10.0): one source telling two people opposite things.
     if (pc.channel === 'told' && actor !== undefined && Array.isArray(pc.reports)) {
@@ -724,8 +724,11 @@ function perceiveOne(p, pc) {
         summary: pc.summary,
         tags: [pc.kind, pc.channel, ...(isNight(at) ? ['night'] : []), ...(threat ? ['threat'] : [])],
     };
-    if (actor !== undefined)
+    if (actor !== undefined) {
         episode.actorId = actor;
+        if (pc.addressedSummary !== undefined)
+            episode.addressedSummary = pc.addressedSummary;
+    }
     if (target !== undefined)
         episode.targetId = target;
     if (pc.placeId !== undefined)
@@ -748,7 +751,7 @@ function judgeDeed(p, actor, pc, at) {
  * into relationships, others' acts judged by my norms, appraisal into emotions, and an episode each.
  * Returns the percepts that were attended to.
  */
-export function perceive(p, percepts) {
+export function perceive(p, percepts, options = {}) {
     if (percepts.length === 0 || !p.body.alive)
         return [];
     const body = readBodyOf(p);
@@ -758,7 +761,7 @@ export function perceive(p, percepts) {
         fear: emotionLevel(p, 'fear'),
     });
     for (const pc of attended) {
-        perceiveOne(p, pc);
+        perceiveOne(p, pc, options);
         // What I just noticed may bring a memory back (the cemetery road, her name on the phone).
         const at = Math.min(Math.max(pc.at, p.affect.lastUpdated), p.now);
         const cue = { at, action: pc.kind, tags: [pc.kind] };
@@ -1449,8 +1452,10 @@ export function finish(p, outcome, opts = {}) {
         ...(act.necessity ? { necessity: true } : {}),
         ...(opts.catalog ? { catalog: opts.catalog } : {}),
     });
-    if (p.projects)
+    if (p.projects) {
+        noteProjectAct(p, aff, completed, now);
         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").

package/dist/persona.js

@@ -4,7 +4,8 @@
  * identity, age, family and health compatibility before returning a new Person. Neither input is mutated.
  * This is not a world migration, identity registry, transport, hash, authentication or general calendar mapper.
  * v1 admits zero-duration travel and healthy compatible bodies only; family/bonds remain host-authored and must
- * match source provenance. Pregnancy and nonempty temporal bonds are unsupported in v1. All other world-dependent stores stay with the source and are disclosed as omitted.
+ * match source provenance. Portable v1 accepts its published 2.14.1 stamp and the current engine;
+ * the 2.14.1 to 2.17.0 migration changes no portable field semantics. Pregnancy and nonempty temporal bonds are unsupported in v1. All other world-dependent stores stay with the source and are disclosed as omitted.
  */
 import { hasUnresolvedMakeUps, sameChain } from './agenda/agenda.js';
 import { createPerson } from './person.js';
@@ -185,7 +186,9 @@ export function validatePersonaProjection(input) {
     text(input.mappingVersion);
     text(input.name);
     keys(input.source, ['schema', 'engine', 'id', 'now']);
-    if (input.source.schema !== PERSON_SCHEMA || input.source.engine !== ENGINE_VERSION)
+    // Both published passport releases used 2.14.1; the next engine upgrade is stamp-only here.
+    const compatibleEngine = input.source.engine === ENGINE_VERSION || input.source.engine === '2.14.1';
+    if (input.source.schema !== PERSON_SCHEMA || !compatibleEngine)
         fail('unsupported source schema/engine; migrate the source before projection');
     text(input.source.id);
     num(input.source.now);

package/dist/projects/projects.d.ts

@@ -1,4 +1,4 @@
-import type { Minute, Person, ProjectsSpec, ProjectsState, Prospect } from '../types.ts';
+import type { Goal, Minute, Person, ProjectsSpec, ProjectsState, Prospect } from '../types.ts';
 export declare const PROJECTS_DEFAULTS: {
     readonly maxProspects: 8;
     readonly maxHistory: 8;
@@ -13,10 +13,16 @@ export declare const PROJECTS_DEFAULTS: {
 };
 /** Enable or reconfigure without discarding retained prospects and history. */
 export declare function enableProjects(p: Person, spec?: ProjectsSpec): ProjectsState;
+/** Turn an active held project into a host task. Undefined means there is no active held project.
+ * Reuses identity, adoption time, progress, peak and progress clock; never revives an abandoned project.
+ * Retains its temporal horizon unless the task supplies a valid replacement.
+ * The caller supplies task meaning and deadlines. No second goal or fresh progress is created.
+ */
+export declare function adoptProjectTask(p: Person, prospectId: string, task: Omit<Goal, 'id' | 'status' | 'progress' | 'adoptedAt' | 'project' | 'lastAdvancedAt'>, now?: Minute): Goal | undefined;
 /** 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;
+export declare function perceiveProspect(p: Person, input: Prospect, at: Minute, attributeOwnAct?: boolean): 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. */

package/dist/projects/projects.js

@@ -9,7 +9,12 @@
  * 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,
+ * Explicit protectProgress blocks goal credit for host-declared reductions and exact contextual acts
+ * followed within five minutes by an attended drop after one's own completion. This is a bounded
+ * causal assumption, not proof of causation. Only direct saw/outcome readings without another actor
+ * can teach that link. It learns no effects from unattended world state or testimony.
+ * adoptProjectTask reuses an active project goal, preserving net credit and pursuit identity.
+ * No invented prospects, implicit 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';
@@ -44,6 +49,8 @@ function cleanSpec(input) {
     const out = {};
     if (!isObj(input))
         return out;
+    if (typeof input.protectProgress === 'boolean')
+        out.protectProgress = input.protectProgress;
     for (const key of KEYS) {
         const x = input[key];
         const unit = key === 'calmUrgency' || key === 'fearBelow' || key === 'adoptAppeal';
@@ -90,6 +97,70 @@ export function enableProjects(p, spec = {}) {
     p.projects = state;
     return state;
 }
+/** Whether this offer is understood to undo this prospect. Read-only; exact context, no action-only generalisation. @internal */
+export function diminishesProject(p, aff, prospectId) {
+    const s = p.projects;
+    return (s?.spec?.protectProgress === true &&
+        ((aff.diminishes?.includes(prospectId) ?? false) ||
+            (s.setbacks?.some((x) => x.prospectId === prospectId &&
+                x.action === aff.action &&
+                x.targetId === aff.targetId &&
+                x.placeId === aff.placeId) ??
+                false)));
+}
+/** Own completed acts alone can explain the next attended drop. Failed/interrupted acts clear attribution. @internal */
+export function noteProjectAct(p, aff, completed, at) {
+    const s = p.projects;
+    if (!s?.spec?.protectProgress)
+        return;
+    delete s.pendingAct;
+    if (!completed ||
+        !str(aff.action) ||
+        (aff.targetId !== undefined && !str(aff.targetId)) ||
+        (aff.placeId !== undefined && !str(aff.placeId)))
+        return;
+    const readings = s.prospects
+        .filter((x) => x.progress !== undefined &&
+        p.agenda.goals.some((g) => g.status === 'active' && g.project?.prospectId === x.id))
+        .map((x) => ({ prospectId: x.id, progress: x.progress }));
+    if (!readings.length)
+        return;
+    s.pendingAct = {
+        action: aff.action,
+        at,
+        readings,
+        ...(aff.targetId !== undefined ? { targetId: aff.targetId } : {}),
+        ...(aff.placeId !== undefined ? { placeId: aff.placeId } : {}),
+    };
+}
+/** Turn an active held project into a host task. Undefined means there is no active held project.
+ * Reuses identity, adoption time, progress, peak and progress clock; never revives an abandoned project.
+ * Retains its temporal horizon unless the task supplies a valid replacement.
+ * The caller supplies task meaning and deadlines. No second goal or fresh progress is created.
+ */
+export function adoptProjectTask(p, prospectId, task, now = p.now) {
+    if (!p.projects || !minute(now, p.now))
+        return undefined;
+    const held = p.agenda.goals.find((g) => g.status === 'active' && g.project?.prospectId === prospectId);
+    if (!held)
+        return undefined;
+    // Use agenda's copying and sanitization, then retain the existing goal rather than allocating a new id.
+    const nextId = p.agenda.nextId;
+    const staged = adoptGoal(p, task, now);
+    p.agenda.goals.pop();
+    p.agenda.nextId = nextId;
+    held.label = staged.label;
+    held.serves = staged.serves;
+    held.advancedBy = staged.advancedBy;
+    held.importance = staged.importance;
+    held.baseImportance = staged.baseImportance;
+    delete held.deadline;
+    if (staged.deadline !== undefined)
+        held.deadline = staged.deadline;
+    if (staged.temporal !== undefined)
+        held.temporal = staged.temporal;
+    return held;
+}
 function relaxed(p) {
     const needs = readPerson(p).needs;
     return {
@@ -166,7 +237,7 @@ export function noteProjectStatus(p, now) {
         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) {
+export function perceiveProspect(p, input, at, attributeOwnAct = false) {
     const s = p.projects;
     if (!s || !minute(at, p.now))
         return;
@@ -178,6 +249,32 @@ export function perceiveProspect(p, input, at) {
         return;
     if (p.now - at > setting(s, 'forgetMinutes'))
         return;
+    const act = s.pendingAct;
+    if (s.spec?.protectProgress && act && at >= act.at) {
+        const before = act.readings.find((x) => x.prospectId === prospect.id);
+        if (before && prospect.progress !== undefined) {
+            if (attributeOwnAct && at - act.at <= 5 && prospect.progress < before.progress) {
+                const learned = {
+                    prospectId: prospect.id,
+                    action: act.action,
+                    ...(act.targetId !== undefined ? { targetId: act.targetId } : {}),
+                    ...(act.placeId !== undefined ? { placeId: act.placeId } : {}),
+                };
+                const list = s.setbacks ?? [];
+                if (!list.some((x) => x.prospectId === learned.prospectId &&
+                    x.action === learned.action &&
+                    x.targetId === learned.targetId &&
+                    x.placeId === learned.placeId))
+                    list.push(learned);
+                s.setbacks = list.slice(-16);
+            }
+            act.readings = act.readings.filter((x) => x.prospectId !== prospect.id);
+            if (!act.readings.length)
+                delete s.pendingAct;
+        }
+        if (at - act.at > 5)
+            delete s.pendingAct;
+    }
     const held = { ...prospect, lastSeenAt: at };
     if (old)
         s.prospects[s.prospects.indexOf(old)] = held;
@@ -268,6 +365,49 @@ export function sanitizeProjects(input, now) {
             return undefined;
         out.currentGoalId = input.currentGoalId;
     }
+    if (input.setbacks !== undefined) {
+        if (!Array.isArray(input.setbacks) || input.setbacks.length > 16)
+            return undefined;
+        out.setbacks = [];
+        for (const x of input.setbacks) {
+            if (!isObj(x) ||
+                !str(x.prospectId) ||
+                !str(x.action) ||
+                (x.targetId !== undefined && !str(x.targetId)) ||
+                (x.placeId !== undefined && !str(x.placeId)))
+                return undefined;
+            out.setbacks.push({
+                prospectId: x.prospectId,
+                action: x.action,
+                ...(x.targetId !== undefined ? { targetId: x.targetId } : {}),
+                ...(x.placeId !== undefined ? { placeId: x.placeId } : {}),
+            });
+        }
+    }
+    const act = input.pendingAct;
+    if (act !== undefined) {
+        if (!isObj(act) ||
+            !str(act.action) ||
+            !minute(act.at, now) ||
+            (act.targetId !== undefined && !str(act.targetId)) ||
+            (act.placeId !== undefined && !str(act.placeId)) ||
+            !Array.isArray(act.readings) ||
+            act.readings.length > PROJECTS_DEFAULTS.maxProspects)
+            return undefined;
+        const readings = [];
+        for (const x of act.readings) {
+            if (!isObj(x) || !str(x.prospectId) || !unit(x.progress))
+                return undefined;
+            readings.push({ prospectId: x.prospectId, progress: x.progress });
+        }
+        out.pendingAct = {
+            action: act.action,
+            at: act.at,
+            readings,
+            ...(act.targetId !== undefined ? { targetId: act.targetId } : {}),
+            ...(act.placeId !== undefined ? { placeId: act.placeId } : {}),
+        };
+    }
     const seen = new Set();
     for (const entry of input.prospects.slice(0, PROJECTS_DEFAULTS.maxProspects)) {
         const prospect = cleanProspect(entry);

package/dist/promptings/promptings.d.ts

@@ -70,7 +70,9 @@ export interface PromptingsNoted {
  */
 export declare function notePromptings(p: Person, seen: readonly PromptingSeen[], chosenId: string | null, now: Minute): PromptingsNoted;
 /** Vocabulary for one prompt under a held reading (narration only; it changes nothing). */
-export declare function promptingLine(reading: PromptingReading, outcome: PromptingRecord['outcome'], kind?: PromptingResponseKind): string;
+export declare function promptingLine(reading: PromptingReading, outcome: PromptingRecord['outcome'], kind?: PromptingResponseKind, options?: {
+    voice?: 'first' | 'third';
+}): string;
 /** Read-only summary of recent prompts (a lens; computes nothing new about the person). */
 export interface PromptingsReadingView {
     reading: PromptingReading;

package/dist/promptings/promptings.js

@@ -256,7 +256,19 @@ export function notePromptings(p, seen, chosenId, now) {
     return noted;
 }
 /** Vocabulary for one prompt under a held reading (narration only; it changes nothing). */
-export function promptingLine(reading, outcome, kind) {
+export function promptingLine(reading, outcome, kind, options = {}) {
+    // Plain third-person observations describe the response, without inferring the prompt's origin.
+    if (options.voice === 'third') {
+        if (outcome === 'assented')
+            return 'an urge came and was acted on';
+        if (outcome === 'turned')
+            return kind === 'refuge'
+                ? 'an urge came; the person sought refuge and let it pass'
+                : kind === 'redirect'
+                    ? 'an urge came; the person turned to something else'
+                    : 'an urge came; the person held back';
+        return 'an urge came and passed';
+    }
     if (outcome === 'assented')
         return reading === 'whisper'
             ? 'a whisper came and was followed'

package/dist/prospection/prospection.js

@@ -17,6 +17,7 @@ import { temporalGoalValue } from '../agenda/agenda.js';
 import { trustOf } from '../beliefs/index.js';
 import { cmpStr, isNum, isObj, round } from '../core/index.js';
 import { expectedEffect } from '../memory/index.js';
+import { diminishesProject } from '../projects/index.js';
 import { MAX_MINUTE, MINUTES_PER_DAY } from '../types.js';
 export const PROSPECTION_DEFAULTS = {
     maxEntries: 16,
@@ -92,6 +93,10 @@ function consequence(x, receivedAt) {
             (!Array.isArray(s.advances) ||
                 s.advances.length > 8 ||
                 !s.advances.every((x) => typeof x === 'string' && x.length > 0 && x.length <= 512))) ||
+        (s.diminishes !== undefined &&
+            (!Array.isArray(s.diminishes) ||
+                s.diminishes.length > 8 ||
+                !s.diminishes.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)))
@@ -115,6 +120,7 @@ function consequence(x, receivedAt) {
             duration: s.duration,
             effort: s.effort,
             ...(s.advances !== undefined ? { advances: [...s.advances] } : {}),
+            ...(s.diminishes !== undefined ? { diminishes: [...s.diminishes] } : {}),
             ...(s.focus !== undefined ? { focus: s.focus } : {}),
             ...(s.materialCost !== undefined ? { materialCost: s.materialCost } : {}),
         },
@@ -262,7 +268,9 @@ function successorOffer(e) {
 }
 /** Select a whole route in the exact rounded units cognition emits. @internal */
 export function receivedGoalRoute(p, aff, now, maturityScale, costs) {
-    const goals = p.agenda.goals.filter((g) => g.status === 'active' && g.temporal !== undefined);
+    const goals = p.agenda.goals.filter((g) => g.status === 'active' &&
+        g.temporal !== undefined &&
+        !(g.project && diminishesProject(p, aff, g.project.prospectId)));
     if (!goals.length || !p.prospection?.entries.length)
         return undefined;
     const direct = goals.map((g) => temporalGoalValue(p, g, aff, now, now + Math.max(0, aff.duration)));
@@ -297,7 +305,12 @@ export function receivedGoalRoute(p, aff, now, maturityScale, costs) {
                 entry.confidence *
                 reliability(p, entry);
             const successor = successorOffer(entry);
-            const nextValues = goals.map((g, i) => Math.max(values[i] ?? 0, nextAccess * beta * temporalGoalValue(p, g, successor, now, end)));
+            const nextValues = goals.map((g, i) => {
+                const prospectId = g.project?.prospectId;
+                return prospectId && [...done, previous, successor].some((a) => diminishesProject(p, a, prospectId))
+                    ? 0
+                    : Math.max(values[i] ?? 0, nextAccess * beta * temporalGoalValue(p, g, successor, now, end));
+            });
             const nextCost = accumulatedCost + beta * nextAccess * Math.min(0, costs(successor));
             const cost = round(nextCost);
             const total = nextValues.reduce((sum, value) => sum + round(value * maturityScale), 0) + cost;

package/dist/review/review.d.ts

@@ -42,6 +42,9 @@ export declare function reviewIfDue(p: Person, now: Minute, recent: readonly Day
     distress: number;
 } | undefined;
 /** The person's own words for their latest review, or undefined when they hold no review. */
-export declare function reviewLine(p: Person): string | undefined;
+export declare function reviewLine(p: Person, options?: {
+    variety?: boolean;
+    cause?: 'ordered' | 'interrupted';
+}): string | undefined;
 /** Restore guard: drop malformed fields, keep valid resolves. */
 export declare function sanitizeReview(x: unknown, now?: Minute): ReviewState | undefined;

package/dist/review/review.js

@@ -31,6 +31,7 @@
  * fast-forward) should still live, or release, that day's occasions, or the review counts each one as missed.
  */
 import { clamp01, dexp, isObj, minuteOfDay, round } from '../core/index.js';
+import { pickLine } from '../narrate/lexicon.js';
 export const REVIEW_DEFAULTS = {
     /** Default evening review time, minute of day. */
     at: 21 * 60,
@@ -192,7 +193,7 @@ export function reviewIfDue(p, now, recent, closed) {
     return { record, distress };
 }
 /** The person's own words for their latest review, or undefined when they hold no review. */
-export function reviewLine(p) {
+export function reviewLine(p, options = {}) {
     const st = p.review;
     const r = st?.last;
     if (!st || st.style === 'none' || !r)
@@ -200,6 +201,16 @@ export function reviewLine(p) {
     const list = (xs) => xs.length <= 1 ? (xs[0] ?? '') : `${xs.slice(0, -1).join(', ')} and ${xs.at(-1)}`;
     if (r.missed.length === 0)
         return r.kept.length > 0 ? `Today I kept ${list(r.kept)}.` : undefined;
+    if (options.cause) {
+        const cause = options.cause === 'ordered' ? 'following an order' : 'being interrupted';
+        const next = options.cause === 'ordered'
+            ? 'Next time I will say what the order would put aside.'
+            : 'Next time I will make room to return to it.';
+        return pickLine('review.cause', `${p.id}:${r.day}`, { cause, missed: list(r.missed), next }, p.lexicon);
+    }
+    if (options.variety ?? p.lexicon?.variety) {
+        return pickLine(`review.${st.style}`, `${p.id}:${r.day}`, { missed: list(r.missed) }, p.lexicon);
+    }
     if (st.style === 'ruminating')
         return `I keep going back over ${list(r.missed)}.`;
     return `I didn't keep ${list(r.missed)}. Next time I'll be ready when it comes.`;

package/dist/types.d.ts

@@ -373,6 +373,8 @@ export interface Episode {
     /** 0..1 how memorable; decays and is boosted by recall. */
     salience: Unit;
     summary: string;
+    /** Host-authored summary spoken back to actorId (second person); never inferred from free text. */
+    addressedSummary?: string;
     tags: string[];
     /**
      * The outside voice whose suggestion led to this episode (set on outcomes of assented/complied activities and
@@ -896,7 +898,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.14.1";
+export declare const ENGINE_VERSION = "2.17.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -1013,6 +1015,8 @@ export interface ReceivedConsequence {
         effort: Unit;
         focus?: Unit;
         materialCost?: number;
+        /** Prospect ids this successor reduces; read only with projects protectProgress. */
+        diminishes?: string[];
         /** Goal or prospect ids this successor contributes to (bounded to 8). */
         advances?: string[];
     };
@@ -1186,6 +1190,8 @@ export interface Affordance {
      * earliest-ending match, explicit or by action, as before.
      */
     fulfills?: string[];
+    /** Prospect ids this offer reduces; read only with projects protectProgress. */
+    diminishes?: string[];
     /** Goal ids this advances. */
     advances?: string[];
     /** Probability of harm and its severity, as advertised. */
@@ -1251,6 +1257,8 @@ export interface Percept {
         aboutId?: PersonId;
     };
     summary: string;
+    /** Host-authored summary spoken back to actorId (second person); never inferred from free text. */
+    addressedSummary?: string;
     /**
      * Host flag for `sim/` interrupts. true: this percept is near the person (the framework has no spatial model),
      * so a salient one forces re-decision even if it does not target them. false: never interrupts.
@@ -1759,6 +1767,12 @@ export interface VoiceConflict {
  * slots documented next to each key.
  */
 export interface Lexicon {
+    /** Include person identity and stable temperament in assent/deferral selection (no RNG draws). */
+    variety?: boolean;
+    /** What material gains mean here, e.g. 'food', 'household keep' or 'resources'; absent keeps legacy money lines. */
+    materialMeaning?: string;
+    /** Treat action labels as noun phrases unless explicit verb forms are supplied. */
+    nounActions?: boolean;
     /** Informational locale tag, e.g. 'en', 'tr'. */
     locale?: string;
     /** Display names by entity id: { ana: 'Ana', ben: 'Ben' }. */
@@ -1987,6 +2001,8 @@ export interface Prospect {
     progress?: Unit;
 }
 export interface ProjectsSpec {
+    /** Learn and respect declared reductions of a held project. Absent preserves existing choice. */
+    protectProgress?: boolean;
     forgetMinutes?: number;
     calmUrgency?: Unit;
     fearBelow?: Unit;
@@ -2008,6 +2024,24 @@ export interface ProjectsState {
     /** Absent retains 2.14.0 credit. Re-enabling, including on every load, opts into net credit. */
     behaviour?: 2;
     spec?: ProjectsSpec;
+    /** Exact contextual acts learned to reduce a prospect; oldest entries are evicted. */
+    setbacks?: {
+        prospectId: string;
+        action: string;
+        targetId?: EntityId;
+        placeId?: EntityId;
+    }[];
+    /** Last completed act and attended progress before it; consumed by the next matching perception. */
+    pendingAct?: {
+        action: string;
+        targetId?: EntityId;
+        placeId?: EntityId;
+        at: Minute;
+        readings: {
+            prospectId: string;
+            progress: Unit;
+        }[];
+    };
     prospects: (Prospect & {
         lastSeenAt: 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.14.1';
+export const ENGINE_VERSION = '2.17.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adam0white/human-framework",
-  "version": "2.16.0",
+  "version": "2.17.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",