@adam0white/human-framework 2.1.4 → 2.2.0

package/README.md

@@ -52,7 +52,7 @@ Each [GitHub release](https://github.com/adam0white/human-framework/releases) al
 installs by URL:
 
 ```sh
-npm install https://github.com/adam0white/human-framework/releases/download/v2.1.4/adam0white-human-framework-2.1.4.tgz
+npm install https://github.com/adam0white/human-framework/releases/download/v2.2.0/adam0white-human-framework-2.2.0.tgz
 ```
 
 or build one from a checkout:
@@ -177,13 +177,13 @@ reference host: `createVillage`.
 
 There are two version numbers, and they move independently.
 
-- **The release version** is the package version (`package.json`, now `2.0.0`) and `FRAMEWORK_VERSION`, the same
+- **The release version** is the package version (`package.json`, now `2.2.0`) and `FRAMEWORK_VERSION`, the same
   string compiled into the build; a test keeps them equal. It versions the public API under
   [semver](https://semver.org/): a breaking change to an exported name or signature bumps the major, a new
   faculty or export the minor, a fix the patch. Each release is a tag `vX.Y.Z` and a GitHub release whose notes
   are that version's section of the root [CHANGELOG.md](../../CHANGELOG.md), with the package tarball attached
   (`npm run release`, run on a clean, pushed `main`).
-- **`ENGINE_VERSION`** (exported; `2.0.0` at release 2.0.0) versions simulation behaviour and the save format. It
+- **`ENGINE_VERSION`** (exported; `2.1.0` at release 2.2.0) versions simulation behaviour and the save format. It
   changes when the same seed and inputs would give different decisions, or when person state changes shape.
   `restore` upgrades saves from engine 1.4.0 and later through `migrate` and refuses older ones. Every release's notes name the
   `ENGINE_VERSION` it ships, so a host can tell whether its saves still restore.
@@ -274,3 +274,31 @@ that place lose appeal until the fear fades. Groups and factions themselves stay
 
 MIT; see [LICENSE](LICENSE). The repository's `docs/` and `research/`, which this README links to, are
 CC BY 4.0.
+
+## Learning a demonstrated conditional step
+
+Use observations the person actually received; the host owns what those observations mean. Matching is on categorical cue strings, not hidden world state or a per-object correct-action table.
+
+```ts
+receiveMethodCues(learner, {
+  contextId: 'observed-example',
+  cues: [{ cue: 'route', value: 'north' }, { cue: 'signal', value: 'clear' }],
+});
+demonstrateMethod(learner, {
+  id: 'routing-north', demonstrationId: 'example-1',
+  contextId: 'observed-example', sourceId: 'instructor',
+  conditions: [{ cue: 'route', value: 'north' }, { cue: 'signal', value: 'clear' }],
+  action: 'send-north', outcome: 'success',
+});
+// A new parcel can share the learned observation structure.
+receiveMethodCues(learner, {
+  contextId: 'new-parcel',
+  cues: [{ cue: 'route', value: 'north' }, { cue: 'signal', value: 'clear' }],
+});
+const evidence = methodEvidence(learner, 'send-north', 'new-parcel');
+// Offers for that parcel carry methodContext: 'new-parcel'.
+// Ordinary decide() includes the acquired method term alongside other motives.
+clearMethodContext(learner); // when leaving or switching the task
+```
+
+Import these functions from the package. Rules/evidence live in optional `Person.methods` and survive snapshots. Current cues expire after 120 minutes. A stable demonstration id avoids counting the same example twice within the retained 256-example history, even after its rule or evidence is evicted. Once an id has left both that history and retained rule evidence, it can be admitted again. Missing observations cannot satisfy a condition; conflicting examples reduce confidence. A successful lecture does not certify reliable execution. [The headless control](examples/method-control.ts) demonstrates changed teaching, withheld teaching, a scalar-skill control and acquired-state ablation with two methods and an exception.

package/dist/cognition/cognition.js

@@ -31,6 +31,7 @@ import { normTerms } from '../conscience/index.js';
 import { clamp01, cmpStr, dexp, minuteOfDay, round } from '../core/index.js';
 import { habitEase, habitPull } from '../habits/index.js';
 import { expectedEffect } from '../memory/index.js';
+import { methodEvidence } from '../methods/index.js';
 import { urgencyOf } from '../needs/index.js';
 import { partneringTerms } from '../partnering/index.js';
 import { companionSteadiness, socialTerms } from '../social/index.js';
@@ -238,6 +239,10 @@ export function consider(p, aff, ctx) {
     if (expected.gist) {
         push('memory', K.expectationScale * expected.gist.valence * expected.gist.weight * (1 - expected.confidence));
     }
+    // Acquired cue-conditioned methods remain one pull among ordinary motives.
+    if (aff.methodContext !== undefined)
+        for (const t of methodEvidence(p, aff.action, aff.methodContext).terms)
+            push(t.source, t.value);
     // Norms, commitments and goals. Planning terms scale with developmental maturity.
     let refractoryCache;
     const refractory = () => {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Human Framework v1 public surface. */
-export declare const FRAMEWORK_VERSION = "2.1.4";
+export declare const FRAMEWORK_VERSION = "2.2.0";
 export type { CrisisEvent, PracticeKind } from './affect/index.ts';
 export { AFFECT_DEFAULTS, actionTendencies, advanceAffect, appraise, breakAllows, breakBehaviour, breakHazard, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, enableBreaks, feel, inBreak, readAffect, regulate, release as releaseEmotion, skipCrisis, strain, tendencyEmotions, } from './affect/index.ts';
 export type { GoalTemplate, PrayerCalendar, PrayerSchedule, PrayerTimes, Retimer, } from './agenda/index.ts';
@@ -20,6 +20,8 @@ export * from './impression.ts';
 export * from './lifecourse/index.ts';
 export * from './longrun.ts';
 export * from './memory/index.ts';
+export type { MethodDemonstration, MethodEvidence } from './methods/index.ts';
+export { clearMethodContext, demonstrateMethod, METHOD_DEFAULTS, methodEvidence, receiveMethodCues, } from './methods/index.ts';
 export type { MigrationStep } from './migrate.ts';
 export { MIGRATIONS, migratableVersions, migrate } from './migrate.ts';
 export * from './narrate/index.ts';

package/dist/index.js

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

package/dist/methods/index.d.ts

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

package/dist/methods/index.js

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

package/dist/methods/methods.d.ts

@@ -0,0 +1,50 @@
+import type { MethodCue, Person, Term } from '../types.ts';
+export declare const METHOD_DEFAULTS: {
+    maxRules: number;
+    maxConditions: number;
+    maxCues: number;
+    maxEvidence: number;
+    maxRecentDemonstrations: number;
+    maxIdentifierLength: number;
+    maxValueLength: number;
+    contextMinutes: number;
+    evidenceHalfLife: number;
+    /** Two fully attended ordinary examples raise support to 0.5 before source trust. */
+    evidencePrior: number;
+    utilityScale: number;
+};
+export interface MethodDemonstration {
+    /** Name of the explained method; action/conditions distinguish its variants. */
+    id: string;
+    /** Stable event id: repeats within the retained 256-example horizon cannot strengthen it. */
+    demonstrationId: string;
+    contextId: string;
+    conditions: readonly MethodCue[];
+    action: string;
+    sourceId: string;
+    outcome: 'success' | 'failure';
+    /** Attended fraction of this example, 0..1; zero acquires nothing. */
+    attention?: number;
+}
+export interface MethodEvidence {
+    /** Net matching evidence for this action, -1..1; conflicts reduce it. */
+    support: number;
+    terms: Term[];
+    matched: {
+        id: string;
+        action: string;
+        sourceId: string;
+        support: number;
+    }[];
+}
+/** Replace current received observations. This is an explicit host reception event, not host truth. */
+export declare function receiveMethodCues(p: Person, received: {
+    contextId: string;
+    cues: readonly MethodCue[];
+}): boolean;
+/** Drop current observations while retaining learned methods. Call when leaving/switching a task. */
+export declare function clearMethodContext(p: Person): void;
+/** Acquire one explained step only when its learner actually received the matching observations. */
+export declare function demonstrateMethod(p: Person, example: MethodDemonstration): boolean;
+/** Read acquired evidence only. No draw, state mutation, hidden fault access or fixed action policy. */
+export declare function methodEvidence(p: Person, action: string, contextId: string): MethodEvidence;

package/dist/methods/methods.js

@@ -0,0 +1,235 @@
+/**
+ * SCOPE: bounded acquisition of conditional action methods from attended examples.
+ * A learner must have received every categorical cue in an explained conjunction.
+ * Successful and unsuccessful demonstrations become person-owned evidence; the
+ * same reader supplies host queries and ordinary cognition terms. Unknown cues
+ * do not mean false. Context identity prevents one task's observations being used
+ * for another task. Contradictory examples weaken support without choosing a
+ * privileged correct answer. Attention, source trust and recency grade evidence.
+ * These are explicit engineering choices, not fitted human learning parameters.
+ * This module does not infer cues, invent actions, plan sequences, certify skill,
+ * access host truth, compute religious worth, or guarantee that a person obeys.
+ */
+import { trustOf } from '../beliefs/index.js';
+import { clamp01, cmpStr, decay, isNum, isObj } from '../core/index.js';
+import { MAX_MINUTE, MINUTES_PER_DAY } from '../types.js';
+export const METHOD_DEFAULTS = {
+    maxRules: 24,
+    maxConditions: 8,
+    maxCues: 24,
+    maxEvidence: 16,
+    maxRecentDemonstrations: 256,
+    maxIdentifierLength: 96,
+    maxValueLength: 128,
+    contextMinutes: 120,
+    evidenceHalfLife: 180 * MINUTES_PER_DAY,
+    /** Two fully attended ordinary examples raise support to 0.5 before source trust. */
+    evidencePrior: 2,
+    utilityScale: 1.2,
+};
+const validId = (x) => typeof x === 'string' &&
+    x.length > 0 &&
+    x.length <= METHOD_DEFAULTS.maxIdentifierLength &&
+    x !== '__proto__' &&
+    x !== 'constructor' &&
+    x !== 'prototype';
+const validValue = (x) => typeof x === 'string' && x.length > 0 && x.length <= METHOD_DEFAULTS.maxValueLength;
+const validMinute = (x) => isNum(x) && Math.abs(x) <= MAX_MINUTE;
+function cleanCues(input, maximum) {
+    if (!Array.isArray(input) || input.length === 0 || input.length > maximum)
+        return undefined;
+    const out = [];
+    for (const c of input) {
+        if (!isObj(c) || !validId(c.cue) || !validValue(c.value))
+            return undefined;
+        // Ambiguous duplicate observations do not silently choose the last value.
+        if (out.some((v) => v.cue === c.cue))
+            return undefined;
+        out.push({ cue: c.cue, value: c.value });
+    }
+    return out.sort((a, b) => cmpStr(a.cue, b.cue));
+}
+function available(p) {
+    return p.body.alive && !p.body.asleep && !p.body.downed;
+}
+/** Replace current received observations. This is an explicit host reception event, not host truth. */
+export function receiveMethodCues(p, received) {
+    const cues = cleanCues(received.cues, METHOD_DEFAULTS.maxCues);
+    // Bad/new unreadable input must not leave stale cues available.
+    clearMethodContext(p);
+    if (!available(p) || !validId(received.contextId) || !cues)
+        return false;
+    p.methods ??= { rules: [], recentDemonstrations: [] };
+    p.methods.context = { id: received.contextId, at: p.now, cues };
+    return true;
+}
+/** Drop current observations while retaining learned methods. Call when leaving/switching a task. */
+export function clearMethodContext(p) {
+    if (p.methods)
+        delete p.methods.context;
+}
+function matches(conditions, cues) {
+    return conditions.every((c) => cues.some((v) => v.cue === c.cue && v.value === c.value));
+}
+function currentContext(p, id) {
+    const context = p.methods?.context;
+    if (!available(p) ||
+        !context ||
+        context.id !== id ||
+        p.now < context.at ||
+        p.now - context.at > METHOD_DEFAULTS.contextMinutes)
+        return undefined;
+    return context;
+}
+/** Acquire one explained step only when its learner actually received the matching observations. */
+export function demonstrateMethod(p, example) {
+    const conditions = cleanCues(example.conditions, METHOD_DEFAULTS.maxConditions);
+    const context = currentContext(p, example.contextId);
+    const attention = example.attention === undefined ? 1 : example.attention;
+    if (!context ||
+        !conditions ||
+        !validId(example.id) ||
+        !validId(example.action) ||
+        !validId(example.sourceId) ||
+        !validId(example.demonstrationId) ||
+        (example.outcome !== 'success' && example.outcome !== 'failure') ||
+        !isNum(attention) ||
+        attention <= 0 ||
+        attention > 1 ||
+        !matches(conditions, context.cues))
+        return false;
+    const state = p.methods;
+    if (!state)
+        return false;
+    if (state.recentDemonstrations.includes(example.demonstrationId) ||
+        state.rules.some((r) => r.evidence.some((e) => e.id === example.demonstrationId)))
+        return false;
+    state.recentDemonstrations.push(example.demonstrationId);
+    if (state.recentDemonstrations.length > METHOD_DEFAULTS.maxRecentDemonstrations)
+        state.recentDemonstrations.shift();
+    let rule = state.rules.find((r) => r.action === example.action && JSON.stringify(r.conditions) === JSON.stringify(conditions));
+    if (!rule) {
+        rule = { id: example.id, action: example.action, conditions, evidence: [] };
+        state.rules.push(rule);
+        if (state.rules.length > METHOD_DEFAULTS.maxRules)
+            state.rules.shift();
+    }
+    rule.evidence.push({
+        id: example.demonstrationId,
+        sourceId: example.sourceId,
+        at: p.now,
+        attention: clamp01(attention),
+        outcome: example.outcome,
+    });
+    if (rule.evidence.length > METHOD_DEFAULTS.maxEvidence)
+        rule.evidence.shift();
+    return true;
+}
+/** Read acquired evidence only. No draw, state mutation, hidden fault access or fixed action policy. */
+export function methodEvidence(p, action, contextId) {
+    const result = { support: 0, terms: [], matched: [] };
+    const context = currentContext(p, contextId);
+    if (!context)
+        return result;
+    const rules = p.methods?.rules ?? [];
+    for (const rule of rules) {
+        if (!matches(rule.conditions, context.cues))
+            continue;
+        const sources = [...new Set(rule.evidence.map((e) => e.sourceId))].sort(cmpStr);
+        for (const sourceId of sources) {
+            let positive = 0;
+            let negative = 0;
+            for (const e of rule.evidence) {
+                if (e.sourceId !== sourceId || e.at > p.now)
+                    continue;
+                const weight = decay(e.attention, p.now - e.at, METHOD_DEFAULTS.evidenceHalfLife);
+                if (e.outcome === 'success')
+                    positive += weight;
+                else
+                    negative += weight;
+            }
+            const voice = p.will.voices.find((v) => v.voiceId === sourceId);
+            const receivedTrust = voice?.trust ?? trustOf(p, sourceId);
+            const trust = isNum(receivedTrust) ? clamp01(receivedTrust) : 0.5;
+            const support = (trust * (positive - negative)) / (positive + negative + METHOD_DEFAULTS.evidencePrior);
+            result.matched.push({ id: rule.id, action: rule.action, sourceId, support });
+        }
+    }
+    // Comparable alternative actions reduce confidence; they never become a hidden answer override.
+    const strengths = new Map();
+    for (const match of result.matched)
+        strengths.set(match.action, (strengths.get(match.action) ?? 0) + match.support);
+    const own = strengths.get(action) ?? 0;
+    const rival = Math.max(0, ...[...strengths].filter(([a]) => a !== action).map(([, v]) => v));
+    const total = Math.max(1, ...[...strengths.values()].map((v) => Math.abs(v)));
+    const net = own > 0 ? Math.max(0, own - rival) : own;
+    result.support = Math.max(-1, Math.min(1, net / total));
+    const scale = own === 0 ? 0 : result.support / own;
+    for (const match of result.matched) {
+        if (match.action !== action || match.support === 0)
+            continue;
+        result.terms.push({
+            source: `method:${match.id}:${match.sourceId}`,
+            value: METHOD_DEFAULTS.utilityScale * match.support * scale,
+        });
+    }
+    return result;
+}
+/** @internal Strict bounded restore; no unrecognized fields survive. */
+export function sanitizeMethods(input) {
+    if (!isObj(input) || !Array.isArray(input.rules))
+        return undefined;
+    const rules = [];
+    const seen = new Set();
+    for (const row of input.rules.slice(-METHOD_DEFAULTS.maxRules)) {
+        if (!isObj(row) || !validId(row.id) || !validId(row.action) || !Array.isArray(row.evidence))
+            continue;
+        const conditions = cleanCues(row.conditions, METHOD_DEFAULTS.maxConditions);
+        if (!conditions)
+            continue;
+        const evidence = [];
+        for (const e of row.evidence.slice(-METHOD_DEFAULTS.maxEvidence)) {
+            if (!isObj(e) ||
+                !validId(e.id) ||
+                !validId(e.sourceId) ||
+                !validMinute(e.at) ||
+                !isNum(e.attention) ||
+                e.attention <= 0 ||
+                e.attention > 1 ||
+                (e.outcome !== 'success' && e.outcome !== 'failure') ||
+                seen.has(e.id))
+                continue;
+            seen.add(e.id);
+            evidence.push({ id: e.id, sourceId: e.sourceId, at: e.at, attention: e.attention, outcome: e.outcome });
+        }
+        if (evidence.length) {
+            const same = rules.find((r) => r.action === row.action && JSON.stringify(r.conditions) === JSON.stringify(conditions));
+            if (same)
+                same.evidence = [...same.evidence, ...evidence].slice(-METHOD_DEFAULTS.maxEvidence);
+            else
+                rules.push({ id: row.id, action: row.action, conditions, evidence });
+        }
+    }
+    const recentDemonstrations = [];
+    if (Array.isArray(input.recentDemonstrations))
+        for (const id of input.recentDemonstrations.slice(-METHOD_DEFAULTS.maxRecentDemonstrations))
+            if (validId(id) && !recentDemonstrations.includes(id))
+                recentDemonstrations.push(id);
+    // Only a missing history is reconstructed. Appending older evidence to a full
+    // valid horizon would evict genuinely newer event ids and alter a live save.
+    if (input.recentDemonstrations === undefined)
+        for (const rule of rules)
+            for (const e of rule.evidence)
+                if (!recentDemonstrations.includes(e.id))
+                    recentDemonstrations.push(e.id);
+    const out = {
+        rules,
+        recentDemonstrations: recentDemonstrations.slice(-METHOD_DEFAULTS.maxRecentDemonstrations),
+    };
+    if (isObj(input.context) && validId(input.context.id) && validMinute(input.context.at)) {
+        const cues = cleanCues(input.context.cues, METHOD_DEFAULTS.maxCues);
+        if (cues)
+            out.context = { id: input.context.id, at: input.context.at, cues };
+    }
+    return out;
+}

package/dist/migrate.js

@@ -7,7 +7,8 @@
  * optional fields that are absent by default), so those steps only stamp the version; 1.9.0 to 2.0.0 renames one
  * field of the optional surroundings slice (`ambient.now` → `ambient.percept`) and changes no behaviour (the optional `social.impressions` and `social.reserve`, like `retention`, are optional and start
  * absent in a migrated save); `restore` then fills and sanitizes
- * the slices as for any save. A migrated save continues under the current engine's rules: it restores and runs,
+ * the slices as for any save. 2.0.0 to 2.1.0 adds optional conditional method state, absent
+ * until explicitly used, so existing hosts retain their previous behavior; that step stamps the version. 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
  * changed how standing advice is heard; 1.8.0 to 1.9.0 changed the omission rule). Saves older than 1.4.0 and unknown versions are refused with an error.
  *
@@ -57,6 +58,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.0.0': {
+        to: '2.1.0',
+        note: 'conditional method state and received cues are optional and start absent; existing host decisions unchanged',
+        apply: stamp,
+    },
 };
 /** The step upgrading from `v`, looked up as an own property only (a version of "__proto__" matches nothing). */
 const stepFrom = (v) => Object.hasOwn(MIGRATIONS, v) ? MIGRATIONS[v] : undefined;

package/dist/restore.js

@@ -16,6 +16,7 @@ import { sanitizeAmbient } from './environment/index.js';
 import { sanitizeFamily } from './family/index.js';
 import { HABIT_DEFAULTS } from './habits/index.js';
 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 { cleanRetention, createPerson, traceLimit } from './person.js';
@@ -57,6 +58,7 @@ const OPTIONAL_KEYS = new Set([
     'bonds',
     'ambient',
     'retention',
+    'methods',
 ]);
 /** 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);
@@ -168,6 +170,7 @@ export function restore(input) {
     keepValid(out, 'bonds', sanitizeBonds);
     keepValid(out, 'ambient', sanitizeAmbient);
     keepValid(out, 'retention', cleanRetention);
+    keepValid(out, 'methods', sanitizeMethods);
     boundLists(out);
     return out;
 }

package/dist/types.d.ts

@@ -787,9 +787,9 @@ export interface Activity {
 }
 export declare const PERSON_SCHEMA = "human/person@1";
 /**
- * Current: 2.0.0 (2026-10-04): `AmbientState.now` renamed `percept` (migrated); per-person `retention` (optional,
- * absent until set); `restore` validates every slice by range and bound and refuses minutes it cannot step. No valid
- * run changes. The current version comes first, then earlier engines oldest first; the API doc shows this first line.
+ * Current: 2.1.0 (2026-10-10): optional acquired conditional methods and explicit received cue contexts.
+ * Normal cognition reads learned method evidence only on offers carrying the matching context.
+ * Existing hosts with no method state keep their previous decisions; 2.0.0 saves migrate by stamping the version.
  *
  * Earlier engines (oldest first):
  * 1.1.0 (2026-10-03): joint activities, omission/distrust rules, reactance, voice history.
@@ -818,7 +818,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.0.0";
+export declare const ENGINE_VERSION = "2.1.0";
 /** A pregnancy carried by this person (host-driven; see `family/`). */
 export interface Pregnancy {
     fatherId: PersonId;
@@ -891,6 +891,34 @@ export interface AmbientState {
     /** Minute these surroundings began. */
     since: Minute;
 }
+/** A received categorical observation; missing values never stand for a negative observation. */
+export interface MethodCue {
+    cue: string;
+    value: string;
+}
+export interface MethodRule {
+    id: string;
+    action: string;
+    conditions: MethodCue[];
+    evidence: {
+        id: string;
+        sourceId: string;
+        at: Minute;
+        attention: Unit;
+        outcome: 'success' | 'failure';
+    }[];
+}
+/** Optional conditional action learning. Owned by methods/, not a host answer table. */
+export interface MethodsState {
+    rules: MethodRule[];
+    /** Last 256 acquired example ids, independent of rule/evidence eviction. */
+    recentDemonstrations: string[];
+    context?: {
+        id: string;
+        at: Minute;
+        cues: MethodCue[];
+    };
+}
 export interface Person {
     schema: typeof PERSON_SCHEMA;
     /** Engine version that last wrote this state. */
@@ -908,6 +936,8 @@ export interface Person {
     conscience: ConscienceState;
     affect: AffectState;
     skills: Record<string, Skill>;
+    /** Acquired conditional method evidence and current received cues; absent until used. */
+    methods?: MethodsState;
     /** Practice consolidation (1.8.0, opt-in via `enableSkillRetention`). Owned by `skills/`. */
     skillRetention?: {
         consolidationHours: number;
@@ -968,6 +998,8 @@ export interface Affordance {
     /** Verb/action class shared across offers: 'eat', 'sleep', 'farm', 'talk', 'pray', 'steal', ... */
     action: string;
     label: string;
+    /** Received method context this offer belongs to; absent = no method term. */
+    methodContext?: string;
     targetId?: EntityId;
     placeId?: EntityId;
     /** Other people taking part. */

package/dist/types.js

@@ -84,9 +84,9 @@ export const EMOTIONS = [
 // ---------------------------------------------------------------------------------------------
 export const PERSON_SCHEMA = 'human/person@1';
 /**
- * Current: 2.0.0 (2026-10-04): `AmbientState.now` renamed `percept` (migrated); per-person `retention` (optional,
- * absent until set); `restore` validates every slice by range and bound and refuses minutes it cannot step. No valid
- * run changes. The current version comes first, then earlier engines oldest first; the API doc shows this first line.
+ * Current: 2.1.0 (2026-10-10): optional acquired conditional methods and explicit received cue contexts.
+ * Normal cognition reads learned method evidence only on offers carrying the matching context.
+ * Existing hosts with no method state keep their previous decisions; 2.0.0 saves migrate by stamping the version.
  *
  * Earlier engines (oldest first):
  * 1.1.0 (2026-10-03): joint activities, omission/distrust rules, reactance, voice history.
@@ -115,4 +115,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.0.0';
+export const ENGINE_VERSION = '2.1.0';

package/package.json

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