@adam0white/human-framework 2.2.1 → 2.4.0

package/dist/promptings/promptings.js

@@ -0,0 +1,348 @@
+/**
+ * SCOPE (promptings and turning away, 2.4.0): a *prompt* is a pull toward an option that the person's own held
+ * norms or goals oppose, strong enough to be noticed. This module records prompts, lets the person turn from them
+ * by a practised response, and keeps a prompt apart from assent: only an assented act reaches `conscience/
+ * recordDeed`, so a prompt is never a breach (Bukhari 5269, research/reconciliation.md §3). It is opt-in
+ * (`enablePromptings`, or `PersonSpec.enable.promptings`); without it nothing here runs and existing runs replay
+ * byte for byte. It draws no randomness.
+ *
+ * Detection reads an option's traced terms and changes none of them: the pull is the sum of positive `habit`,
+ * `emotion:*`, `need:*` and `promptings:echo` terms (every positive term on an offer tagged `temptation`); it is a
+ * prompt when the pull reaches `noticeAt` while a `norm:*` or `goal:*` term on the same option is negative.
+ * Abstention windows are not detected (they veto, and carry no term). A person with a response gets one extra
+ * term, `promptings:turn` = -turnMax × practice, on that option; it is bounded and absent at survival desperation,
+ * so a desperate bodily need still wins (2:286). Each prompt is recorded once per decision point (a review that
+ * keeps the running activity records nothing) as `assented` (chosen), `turned` (not chosen, a response practised)
+ * or `passed` (not chosen, no response). Practice grows with diminishing gains once per decision point where the
+ * response was used (more when it held; a vetoed option earns none, since the will blocked it), and halves over `practiceHalfLifeDays` of disuse.
+ *
+ * Held readings (reconciliation.md §5): `whisper`, `inclination`, `intrusion` and `none` give identical decisions
+ * and differ only in the vocabulary of `promptingLine`. `fault` (the scrupulous reading, which both the tradition
+ * and clinicians reject) adds a small guilt emotion at the prompt itself, from the person's own understanding;
+ * that guilt is an emotion, never a breach, so it changes decisions only where an offer acts through guilt's
+ * tendencies. With a host-set `echoRate` > 0, `fault` also gains a recurrence pull on that action
+ * (`promptings:echo`), decaying over days: a labelled assumption from contested suppression-rebound evidence
+ * (P3), off by default. No reading earns a hidden bonus.
+ *
+ * Borrowed shapes: everyday desire, conflict and resistance (P1, P2); suppression rebound and redirection (P3,
+ * P13); practised if–then responses (P5). Every number is an engineering default, not fitted. Does not claim: the
+ * source of any thought, a measure of faith, spiritual rank, reward for resisting (H4 is acknowledged as a held
+ * belief and never computed), clinical OCD, or a cessation rate. The lenses (`promptingsReading`, `nafsReading`)
+ * only describe existing state; they store and compute nothing new about the person.
+ */
+import { clamp01, dexp, isObj, round } from '../core/index.js';
+import { MINUTES_PER_DAY } from '../types.js';
+export const PROMPTINGS_DEFAULTS = {
+    /** Pull (utility units) from which a pull against a held norm or goal is noticed. */
+    noticeAt: 0.15,
+    /** Largest turning-away term at full practice (utility units). */
+    turnMax: 0.8,
+    /** No turning-away term at or above this desperation (same scale as will's survival desperation). */
+    survivalDesperation: 0.75,
+    /** Practice gained at a prompt where the response held (× (1 - practice)). */
+    gainTurned: 0.12,
+    /** Practice gained at a prompt where the response was tried but the person assented. */
+    gainAttempt: 0.04,
+    /** Practice halves over this many days without use. */
+    practiceHalfLifeDays: 60,
+    /** Guilt intensity at a prompt under the `fault` reading. */
+    faultGuilt: 0.15,
+    /** Recurrence pull at echo level 1 (utility units); only reached when a host sets `echoRate` > 0. */
+    echoScale: 0.5,
+    echoHalfLifeDays: 3,
+    maxRecent: 64,
+    maxResponses: 8,
+    maxEcho: 32,
+};
+const READINGS = ['whisper', 'inclination', 'intrusion', 'fault', 'none'];
+const KINDS = ['refuge', 'redirect', 'leave'];
+const halve = (value, minutes, halfLifeDays) => minutes <= 0 ? value : value * dexp((-Math.LN2 * minutes) / (halfLifeDays * MINUTES_PER_DAY));
+/**
+ * Turn the slice on, or reconfigure it: recent records and echo are kept, and a response whose id is already held
+ * keeps its practice and last use (the spec's `practice` only seeds new responses). Returns the state.
+ */
+export function enablePromptings(p, spec = {}) {
+    const prev = p.promptings;
+    const responses = [];
+    for (const r of spec.responses ?? []) {
+        if (!isObj(r) || typeof r.id !== 'string' || r.id === '' || !KINDS.includes(r.kind))
+            continue;
+        if (responses.some((x) => x.id === r.id) || responses.length >= PROMPTINGS_DEFAULTS.maxResponses)
+            continue;
+        const held = prev?.responses.find((x) => x.id === r.id);
+        const seed = Number.isFinite(r.practice) ? clamp01(r.practice) : 0.1;
+        responses.push(held ? { ...held, kind: r.kind } : { id: r.id, kind: r.kind, practice: seed, lastUsedAt: p.now });
+    }
+    const state = {
+        reading: spec.reading && READINGS.includes(spec.reading) ? spec.reading : 'none',
+        responses,
+        recent: prev?.recent ?? [],
+        echo: prev?.echo ?? {},
+        echoRate: Number.isFinite(spec.echoRate) ? clamp01(spec.echoRate) : 0,
+    };
+    if (spec.readingSource !== undefined)
+        state.readingSource = spec.readingSource;
+    p.promptings = state;
+    return state;
+}
+/** Practice of a response at `now`, after disuse decay. Pure. */
+export function practiceAt(r, now) {
+    return clamp01(halve(r.practice, now - r.lastUsedAt, PROMPTINGS_DEFAULTS.practiceHalfLifeDays));
+}
+/** The response a person would use now: highest practice, ties by id. */
+function bestResponse(s, now) {
+    let best;
+    for (const r of s.responses) {
+        const practice = practiceAt(r, now);
+        if (!best || practice > best.practice || (practice === best.practice && r.id < best.r.id))
+            best = { r, practice };
+    }
+    return best;
+}
+const isPull = (source, tagged) => tagged ||
+    source === 'habit' ||
+    source === 'promptings:echo' ||
+    source.startsWith('emotion:') ||
+    source.startsWith('need:');
+/** Whether an option's terms carry a noticed prompt: its strongest pull and the opposing term. Pure. */
+export function promptIn(terms, tags) {
+    const tagged = tags?.includes('temptation') ?? false;
+    let pull = 0;
+    let top;
+    let opposed;
+    for (const t of terms) {
+        if (t.source === 'promptings:turn')
+            continue;
+        if (t.value > 0 && isPull(t.source, tagged)) {
+            pull += t.value;
+            if (!top || t.value > top.value)
+                top = t;
+        }
+        else if (t.value < 0 &&
+            (t.source.startsWith('norm:') || t.source.startsWith('goal:')) &&
+            (!opposed || t.value < opposed.value))
+            opposed = t;
+    }
+    if (!top || !opposed || pull < PROMPTINGS_DEFAULTS.noticeAt)
+        return undefined;
+    return { source: tagged && !isPull(top.source, false) ? 'host' : top.source, opposedBy: opposed.source };
+}
+/**
+ * Extra terms for one option (cognition calls this before summing): the echo pull under `fault`, then the
+ * turning-away term when the option carries a prompt. Pure apart from reads; empty without the slice.
+ */
+export function promptingTerms(p, action, terms, tags, now, desperation) {
+    const s = p.promptings;
+    if (!s)
+        return [];
+    const out = [];
+    const e = Object.hasOwn(s.echo, action) ? s.echo[action] : undefined;
+    if (e && s.reading === 'fault') {
+        const level = halve(e.level, now - e.at, PROMPTINGS_DEFAULTS.echoHalfLifeDays);
+        const v = round(PROMPTINGS_DEFAULTS.echoScale * level);
+        if (v > 0)
+            out.push({ source: 'promptings:echo', value: v });
+    }
+    if (desperation >= PROMPTINGS_DEFAULTS.survivalDesperation)
+        return out;
+    const best = bestResponse(s, now);
+    if (!best || best.practice <= 0)
+        return out;
+    if (!promptIn([...terms, ...out], tags))
+        return out;
+    const v = round(-PROMPTINGS_DEFAULTS.turnMax * best.practice);
+    if (v < 0)
+        out.push({ source: 'promptings:turn', value: v });
+    return out;
+}
+/**
+ * Record the prompts of one decision point and learn from them. `chosenId` is the chosen affordance (null when
+ * nothing was chosen). The only writer of `p.promptings` after `enablePromptings`.
+ */
+export function notePromptings(p, seen, chosenId, now) {
+    const s = p.promptings;
+    const noted = { records: [], guilt: 0 };
+    if (!s || seen.length === 0)
+        return noted;
+    const D = PROMPTINGS_DEFAULTS;
+    const best = bestResponse(s, now);
+    // One practice gain per decision point, however many options carried a prompt: the larger one if any held.
+    let gain = 0;
+    for (const x of seen) {
+        const assented = x.affordanceId === chosenId;
+        const used = x.turnApplied && best !== undefined;
+        const rec = {
+            at: now,
+            action: x.action,
+            affordanceId: x.affordanceId,
+            source: x.source,
+            opposedBy: x.opposedBy,
+            outcome: assented ? 'assented' : used ? 'turned' : 'passed',
+        };
+        if (used && best) {
+            rec.responseId = best.r.id;
+            gain = Math.max(gain, assented ? D.gainAttempt : D.gainTurned);
+        }
+        s.recent.push(rec);
+        noted.records.push(rec);
+        if (s.reading === 'fault') {
+            noted.guilt = Math.max(noted.guilt, D.faultGuilt);
+            if (s.echoRate > 0) {
+                const prev = Object.hasOwn(s.echo, x.action) ? s.echo[x.action] : undefined;
+                const level = prev ? halve(prev.level, now - prev.at, D.echoHalfLifeDays) : 0;
+                s.echo[x.action] = { level: round(clamp01(level + s.echoRate * (1 - level))), at: now };
+            }
+        }
+    }
+    if (best && gain > 0) {
+        const practice = practiceAt(best.r, now);
+        best.r.practice = round(clamp01(practice + gain * (1 - practice)));
+        best.r.lastUsedAt = now;
+    }
+    if (s.recent.length > D.maxRecent)
+        s.recent.splice(0, s.recent.length - D.maxRecent);
+    const keys = Object.keys(s.echo);
+    if (keys.length > D.maxEcho) {
+        keys.sort((a, b) => (s.echo[a]?.at ?? 0) - (s.echo[b]?.at ?? 0) || (a < b ? -1 : 1));
+        for (const k of keys.slice(0, keys.length - D.maxEcho))
+            delete s.echo[k];
+    }
+    return noted;
+}
+/** Vocabulary for one prompt under a held reading (narration only; it changes nothing). */
+export function promptingLine(reading, outcome, kind) {
+    if (outcome === 'assented')
+        return reading === 'whisper'
+            ? 'a whisper came and was followed'
+            : reading === 'inclination'
+                ? 'the pull of the self won'
+                : 'an urge came and was acted on';
+    const how = outcome === 'turned'
+        ? kind === 'refuge'
+            ? 'sought refuge and '
+            : kind === 'redirect'
+                ? 'turned to something else and '
+                : ''
+        : '';
+    switch (reading) {
+        case 'whisper':
+            return `a whisper came; ${how}let it pass`;
+        case 'inclination':
+            return `the self pulled; ${how}held back`;
+        case 'intrusion':
+            return `a thought came, not who I am; ${how}let it go`;
+        case 'fault':
+            return `a thought came and felt like wrongdoing; ${how}let it pass`;
+        default:
+            return `an urge came; ${how}it passed`;
+    }
+}
+export function promptingsReading(p, now = p.now) {
+    const s = p.promptings;
+    if (!s)
+        return undefined;
+    const count = (o) => s.recent.filter((r) => r.outcome === o).length;
+    const kindOf = (id) => s.responses.find((r) => r.id === id)?.kind;
+    const view = {
+        reading: s.reading,
+        prompts: s.recent.length,
+        turned: count('turned'),
+        passed: count('passed'),
+        assented: count('assented'),
+        responses: s.responses.map((r) => ({ id: r.id, kind: r.kind, practice: round(practiceAt(r, now)) })),
+        lines: s.recent.slice(-5).map((r) => promptingLine(s.reading, r.outcome, kindOf(r.responseId))),
+    };
+    if (s.readingSource !== undefined)
+        view.readingSource = s.readingSource;
+    return view;
+}
+export function nafsPatterns(p, inputs) {
+    const recent = p.promptings?.recent ?? [];
+    const assentedAgainstNorm = recent.filter((r) => r.outcome === 'assented' && r.opposedBy.startsWith('norm:'));
+    const letPass = recent.filter((r) => r.outcome !== 'assented').length;
+    const reproach = inputs.guiltLoad > 0 || inputs.guilt > 0.05;
+    return [
+        {
+            name: 'urging',
+            ref: 'Qur’an 12:53',
+            evident: assentedAgainstNorm.length > 0,
+            evidence: `${assentedAgainstNorm.length} recent prompts followed against a held norm`,
+        },
+        {
+            name: 'reproaching',
+            ref: 'Qur’an 75:2',
+            evident: reproach,
+            evidence: `open-breach weight ${round(inputs.guiltLoad, 2)}, felt guilt ${round(inputs.guilt, 2)}`,
+        },
+        {
+            name: 'at rest',
+            ref: 'Qur’an 89:27',
+            evident: letPass > 0 && assentedAgainstNorm.length === 0 && !reproach,
+            evidence: `${letPass} recent prompts let pass, none followed against a norm, no felt reproach`,
+        },
+    ];
+}
+const unit = (x) => typeof x === 'number' && Number.isFinite(x) && x >= 0 && x <= 1;
+const minute = (x) => typeof x === 'number' && Number.isFinite(x);
+const str = (x) => typeof x === 'string' && x !== '' && x.length <= 200;
+/** Validate a saved slice; a malformed slice is dropped (undefined), malformed entries are skipped. */
+export function sanitizePromptings(input, now) {
+    if (!isObj(input) || !Array.isArray(input.responses) || !Array.isArray(input.recent) || !isObj(input.echo))
+        return undefined;
+    if (typeof input.reading !== 'string' || !READINGS.includes(input.reading))
+        return undefined;
+    const D = PROMPTINGS_DEFAULTS;
+    const responses = [];
+    for (const r of input.responses.slice(0, D.maxResponses)) {
+        if (!isObj(r) || !str(r.id) || !KINDS.includes(r.kind) || !unit(r.practice))
+            continue;
+        if (!minute(r.lastUsedAt) || r.lastUsedAt > now || responses.some((x) => x.id === r.id))
+            continue;
+        responses.push({
+            id: r.id,
+            kind: r.kind,
+            practice: r.practice,
+            lastUsedAt: r.lastUsedAt,
+        });
+    }
+    const recent = [];
+    for (const r of input.recent.slice(-D.maxRecent)) {
+        if (!isObj(r) || !minute(r.at) || r.at > now || !str(r.action) || !str(r.affordanceId))
+            continue;
+        if (!str(r.source) || !str(r.opposedBy))
+            continue;
+        if (r.outcome !== 'passed' && r.outcome !== 'turned' && r.outcome !== 'assented')
+            continue;
+        const rec = {
+            at: r.at,
+            action: r.action,
+            affordanceId: r.affordanceId,
+            source: r.source,
+            opposedBy: r.opposedBy,
+            outcome: r.outcome,
+        };
+        if (str(r.responseId))
+            rec.responseId = r.responseId;
+        recent.push(rec);
+    }
+    const echo = {};
+    for (const k of Object.keys(input.echo).slice(0, D.maxEcho)) {
+        if (k === '__proto__' || !str(k))
+            continue;
+        const e = input.echo[k];
+        if (!isObj(e) || !unit(e.level) || !minute(e.at) || e.at > now)
+            continue;
+        echo[k] = { level: e.level, at: e.at };
+    }
+    const rate = input.echoRate;
+    const out = {
+        reading: input.reading,
+        responses,
+        recent,
+        echo,
+        echoRate: typeof rate === 'number' && Number.isFinite(rate) && rate >= 0 ? Math.min(1, rate) : 0,
+    };
+    if (str(input.readingSource))
+        out.readingSource = input.readingSource;
+    return out;
+}

package/dist/prospection/index.d.ts

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

package/dist/prospection/index.js

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

package/dist/prospection/prospection.d.ts

@@ -0,0 +1,23 @@
+import type { Affordance, ConsequenceRevision, Minute, Person, RetainedConsequence } from '../types.ts';
+export declare const PROSPECTION_DEFAULTS: {
+    maxEntries: number;
+    maxRevisions: number;
+    maxBatch: number;
+    maxIdentifierLength: number;
+    horizon: number;
+    maxMaterialCost: number;
+};
+export interface ConsequenceEvidence {
+    entry: RetainedConsequence;
+    matches: boolean;
+    feasible: boolean;
+    successorStartsAt: Minute;
+    successorEndsAt: Minute;
+    accessProbability: number;
+    terminalProbability: number;
+}
+/** Read current retained knowledge and feasibility. Does not mutate, prune or consume RNG. */
+export declare function consequenceEvidence(p: Person, aff: Affordance, now?: Minute): {
+    entries: ConsequenceEvidence[];
+    revisions: ConsequenceRevision[];
+};

package/dist/prospection/prospection.js

@@ -0,0 +1,278 @@
+/**
+ * SCOPE: one received current-action → successor consequence, acquired only through
+ * attended external testimony for this person or an untargeted broadcast. Knowledge is person-owned, source-labelled, bounded and saved.
+ * Temporal goals value expected completion using time, success and source reliability.
+ * One coherent route may contribute; it never executes actions, grants consent or
+ * advances a goal. Own completed triggers consume their received opportunity.
+ * This is not graph search, inferred procedure learning or a model of future bodies,
+ * waiting opportunity cost or another person's agency. Parameters are engineering
+ * bounds, not fitted psychological estimates. Revision memory is bounded, not an audit.
+ */
+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 { MAX_MINUTE, MINUTES_PER_DAY } from '../types.js';
+export const PROSPECTION_DEFAULTS = {
+    maxEntries: 16,
+    maxRevisions: 64,
+    maxBatch: 4,
+    maxIdentifierLength: 96,
+    horizon: 7 * MINUTES_PER_DAY,
+    maxMaterialCost: 1_000_000,
+};
+const id = (x) => typeof x === 'string' &&
+    x.length > 0 &&
+    x.length <= PROSPECTION_DEFAULTS.maxIdentifierLength &&
+    x !== '__proto__' &&
+    x !== 'constructor' &&
+    x !== 'prototype';
+const minute = (x) => isNum(x) && Math.abs(x) <= MAX_MINUTE;
+const unit = (x) => isNum(x) && x >= 0 && x <= 1;
+const revision = (x) => typeof x === 'number' && Number.isSafeInteger(x) && x >= 0;
+const identity = (a, b) => a.sourceId === b.sourceId && a.id === b.id;
+const order = (a, b) => a.receivedAt - b.receivedAt || cmpStr(a.sourceId, b.sourceId) || cmpStr(a.id, b.id);
+function action(x) {
+    if (!isObj(x) ||
+        !id(x.action) ||
+        (x.targetId !== undefined && !id(x.targetId)) ||
+        (x.placeId !== undefined && !id(x.placeId)))
+        return undefined;
+    return {
+        action: x.action,
+        ...(x.targetId !== undefined ? { targetId: x.targetId } : {}),
+        ...(x.placeId !== undefined ? { placeId: x.placeId } : {}),
+    };
+}
+function consequence(x, receivedAt) {
+    if (!isObj(x) || !id(x.id) || !revision(x.revision))
+        return undefined;
+    const trigger = action(x.trigger);
+    const successorAction = action(x.successor);
+    const s = x.successor;
+    if (!trigger ||
+        !successorAction ||
+        !isObj(s) ||
+        !isNum(s.duration) ||
+        s.duration < 0 ||
+        s.duration > PROSPECTION_DEFAULTS.horizon ||
+        !unit(s.effort) ||
+        (s.focus !== undefined && !unit(s.focus)) ||
+        (s.materialCost !== undefined &&
+            (!isNum(s.materialCost) || s.materialCost < 0 || s.materialCost > PROSPECTION_DEFAULTS.maxMaterialCost)))
+        return undefined;
+    if (!minute(x.availableFrom) ||
+        !minute(x.availableUntil) ||
+        !minute(x.expiresAt) ||
+        x.availableFrom > x.availableUntil ||
+        x.availableUntil > x.expiresAt ||
+        x.expiresAt < receivedAt ||
+        x.expiresAt > receivedAt + PROSPECTION_DEFAULTS.horizon ||
+        !unit(x.chance) ||
+        !unit(x.confidence))
+        return undefined;
+    return {
+        id: x.id,
+        revision: x.revision,
+        trigger,
+        successor: {
+            ...successorAction,
+            duration: s.duration,
+            effort: s.effort,
+            ...(s.focus !== undefined ? { focus: s.focus } : {}),
+            ...(s.materialCost !== undefined ? { materialCost: s.materialCost } : {}),
+        },
+        availableFrom: x.availableFrom,
+        availableUntil: x.availableUntil,
+        expiresAt: x.expiresAt,
+        chance: x.chance,
+        confidence: x.confidence,
+    };
+}
+function retained(x, now) {
+    if (!isObj(x) || !id(x.sourceId) || x.channel !== 'told' || !minute(x.receivedAt) || x.receivedAt > now)
+        return undefined;
+    const c = consequence(x, x.receivedAt);
+    if (!c ||
+        (x.triggeredAt !== undefined &&
+            (!minute(x.triggeredAt) || x.triggeredAt < x.receivedAt || x.triggeredAt > now)))
+        return undefined;
+    return {
+        ...c,
+        sourceId: x.sourceId,
+        channel: 'told',
+        receivedAt: x.receivedAt,
+        ...(x.triggeredAt !== undefined ? { triggeredAt: x.triggeredAt } : {}),
+    };
+}
+function cleaned(state, now) {
+    const revisions = state.revisions.filter((r) => now - r.receivedAt <= PROSPECTION_DEFAULTS.horizon);
+    return {
+        entries: state.entries.filter((e) => e.expiresAt >= now && revisions.some((r) => identity(r, e) && r.revision === e.revision)),
+        revisions,
+    };
+}
+function store(p, s) {
+    if (s.entries.length || s.revisions.length)
+        p.prospection = s;
+    else
+        delete p.prospection;
+}
+/** Expiry changes only existing optional state. @internal */
+export function pruneConsequences(p, now = p.now) {
+    if (p.prospection)
+        store(p, cleaned(p.prospection, now));
+}
+/** Called only for an attended percept. Invalid combined batches mutate no prospection state. @internal */
+export function receiveConsequences(p, pc) {
+    if (pc.consequences === undefined && pc.withdrawConsequences === undefined)
+        return false;
+    if (pc.channel !== 'told' ||
+        !id(pc.actorId) ||
+        pc.actorId === p.id ||
+        (pc.targetId !== undefined && pc.targetId !== p.id))
+        return false;
+    const adds = pc.consequences ?? [];
+    const removes = pc.withdrawConsequences ?? [];
+    if (!Array.isArray(adds) ||
+        !Array.isArray(removes) ||
+        adds.length + removes.length > PROSPECTION_DEFAULTS.maxBatch ||
+        adds.length + removes.length === 0)
+        return false;
+    const additions = adds.map((x) => consequence(x, p.now));
+    if (additions.some((x) => x === undefined) ||
+        removes.some((x) => !isObj(x) || !id(x.id) || !revision(x.revision)))
+        return false;
+    const withdrawals = removes;
+    const batch = [...additions.map((x) => ({ id: x?.id, revision: x?.revision })), ...withdrawals];
+    if (new Set(batch.map((x) => x.id)).size !== batch.length)
+        return false;
+    const state = cleaned(structuredClone(p.prospection ?? { entries: [], revisions: [] }), p.now);
+    const sourceId = pc.actorId;
+    const updates = batch.filter((b) => !state.revisions.some((r) => r.sourceId === sourceId && r.id === b.id && r.revision >= (b.revision ?? 0)));
+    const newIds = updates.filter((b) => !state.revisions.some((r) => r.sourceId === sourceId && r.id === b.id));
+    // Never evict a still-valid tombstone to admit a batch; dedup holds within the stated horizon.
+    if (state.revisions.length + newIds.length > PROSPECTION_DEFAULTS.maxRevisions)
+        return false;
+    for (const b of updates) {
+        state.entries = state.entries.filter((e) => !(e.sourceId === sourceId && e.id === b.id));
+        state.revisions = state.revisions.filter((r) => !(r.sourceId === sourceId && r.id === b.id));
+        const addition = additions.find((a) => a?.id === b.id);
+        if (addition)
+            state.entries.push({ ...addition, sourceId, channel: 'told', receivedAt: p.now });
+        state.revisions.push({ sourceId, id: b.id, revision: b.revision, receivedAt: p.now });
+    }
+    if (state.entries.length > PROSPECTION_DEFAULTS.maxEntries) {
+        const oldest = [...state.entries]
+            .sort((a, b) => Number(b.triggeredAt !== undefined) - Number(a.triggeredAt !== undefined) || order(a, b))
+            .slice(0, state.entries.length - PROSPECTION_DEFAULTS.maxEntries);
+        state.entries = state.entries.filter((e) => !oldest.includes(e));
+    }
+    store(p, state);
+    return true;
+}
+const matches = (a, b) => a.action === b.action && a.targetId === b.targetId && a.placeId === b.placeId;
+/** Own actual completed trigger consumes an opportunity, without predicting consent. @internal */
+export function consumeConsequences(p, completed) {
+    for (const e of p.prospection?.entries ?? [])
+        if (e.triggeredAt === undefined && matches(e.trigger, completed))
+            e.triggeredAt = p.now;
+}
+/** Read current retained knowledge and feasibility. Does not mutate, prune or consume RNG. */
+export function consequenceEvidence(p, aff, now = p.now) {
+    return {
+        entries: (p.prospection?.entries ?? []).map((entry) => {
+            const start = Math.max(now + Math.max(0, aff.duration), entry.availableFrom);
+            const end = start + entry.successor.duration;
+            const match = matches(entry.trigger, aff);
+            const feasible = match &&
+                entry.triggeredAt === undefined &&
+                now <= entry.expiresAt &&
+                end <= entry.availableUntil &&
+                Number.isFinite(end);
+            const accessProbability = expectedEffect(p, aff).successRate * entry.chance * entry.confidence * trustOf(p, entry.sourceId);
+            return {
+                entry: structuredClone(entry),
+                matches: match,
+                feasible,
+                successorStartsAt: start,
+                successorEndsAt: end,
+                accessProbability,
+                terminalProbability: accessProbability * expectedEffect(p, successorOffer(entry)).successRate,
+            };
+        }),
+        revisions: structuredClone((p.prospection?.revisions ?? []).filter((r) => now - r.receivedAt <= PROSPECTION_DEFAULTS.horizon)),
+    };
+}
+function successorOffer(e) {
+    const { materialCost, ...rest } = e.successor;
+    return {
+        ...rest,
+        id: 'prospective-successor',
+        label: 'Received successor',
+        advertises: {},
+        ...(materialCost !== undefined ? { material: -materialCost } : {}),
+    };
+}
+/** 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);
+    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)));
+    const baseline = direct.reduce((sum, value) => sum + round(value * maturityScale), 0);
+    let bestScore = baseline;
+    let best;
+    const entries = consequenceEvidence(p, aff, now).entries.sort((a, b) => cmpStr(a.entry.sourceId, b.entry.sourceId) || cmpStr(a.entry.id, b.entry.id));
+    for (const e of entries) {
+        if (!e.feasible)
+            continue;
+        const successor = successorOffer(e.entry);
+        const values = goals.map((g, i) => Math.max(direct[i] ?? 0, e.accessProbability * temporalGoalValue(p, g, successor, now, e.successorEndsAt)));
+        const cost = round(e.accessProbability * Math.min(0, costs(successor)));
+        const total = values.reduce((sum, value) => sum + round(value * maturityScale), 0) + cost;
+        if (!(round(total - bestScore) > 0))
+            continue;
+        bestScore = total;
+        best = {
+            goals: new Map(goals.map((g, i) => [g.id, values[i] ?? 0])),
+            cost: { source: `prospection:cost:${e.entry.sourceId}:${e.entry.id}`, value: cost },
+        };
+    }
+    return best;
+}
+/** Conservative optional-slice restore; ambiguous identities drop the slice. @internal */
+export function sanitizeProspection(input, now, personId) {
+    if (!isObj(input) ||
+        !Array.isArray(input.entries) ||
+        !Array.isArray(input.revisions) ||
+        input.entries.length > PROSPECTION_DEFAULTS.maxEntries ||
+        input.revisions.length > PROSPECTION_DEFAULTS.maxRevisions)
+        return undefined;
+    const entries = input.entries.map((x) => retained(x, now)).filter((e) => e?.sourceId !== personId);
+    const revisions = [];
+    for (const r of input.revisions) {
+        if (!isObj(r) ||
+            !id(r.sourceId) ||
+            r.sourceId === personId ||
+            !id(r.id) ||
+            !revision(r.revision) ||
+            !minute(r.receivedAt) ||
+            r.receivedAt > now)
+            continue;
+        if (revisions.some((old) => identity(old, r)))
+            return undefined;
+        revisions.push({ sourceId: r.sourceId, id: r.id, revision: r.revision, receivedAt: r.receivedAt });
+    }
+    const valid = [];
+    for (const e of entries) {
+        if (!e)
+            continue;
+        if (valid.some((old) => identity(old, e)))
+            return undefined;
+        if (revisions.some((r) => identity(r, e) && r.revision === e.revision && r.receivedAt === e.receivedAt))
+            valid.push(e);
+    }
+    const state = cleaned({ entries: valid, revisions }, now);
+    return state.entries.length || state.revisions.length ? state : undefined;
+}

package/dist/restore.js

@@ -20,6 +20,8 @@ import { sanitizeMethods } from './methods/index.js';
 import { migrate } from './migrate.js';
 import { sanitizeBonds } from './partnering/index.js';
 import { cleanRetention, createPerson, traceLimit } from './person.js';
+import { sanitizePromptings } from './promptings/index.js';
+import { sanitizeProspection } from './prospection/index.js';
 import { sanitizeSkillRetention } from './skills/index.js';
 import { sanitizeGroups, sanitizeImpressions } from './social/index.js';
 import { ENGINE_VERSION, MAX_MINUTE, PERSON_SCHEMA } from './types.js';
@@ -59,6 +61,8 @@ const OPTIONAL_KEYS = new Set([
     'ambient',
     'retention',
     'methods',
+    'prospection',
+    'promptings',
 ]);
 /** Kind of a JSON value for the per-field type check in `restore`. */
 const kindOf = (x) => (Array.isArray(x) ? 'array' : x === null ? 'null' : typeof x);
@@ -171,6 +175,8 @@ export function restore(input) {
     keepValid(out, 'ambient', sanitizeAmbient);
     keepValid(out, 'retention', cleanRetention);
     keepValid(out, 'methods', sanitizeMethods);
+    keepValid(out, 'prospection', (x) => sanitizeProspection(x, out.now, out.id));
+    keepValid(out, 'promptings', (x) => sanitizePromptings(x, out.now));
     boundLists(out);
     return out;
 }