@adam0white/human-framework 2.14.1 → 2.15.0

package/README.md

@@ -1,13 +1,72 @@
 # @adam0white/human-framework
 
-Simulated people for games and headless simulations. A `Person` has a body, needs, emotions, memory,
-beliefs, skills, habits, relationships, values, an understanding of moral norms, and a will. The host
-world offers actions; the person chooses among them, and can refuse what an outside voice suggests. Every
-choice comes with the terms that produced it and a first-person line, so a refusal reads as a reason rather
-than a bug.
+HF is a TypeScript library for simulated people in games and headless simulations. Your world offers
+possible actions. Each person weighs needs, habits, duties, goals and suggestions, then chooses.
+A player can suggest an action; the person can defer or refuse it.
 
-The library is TypeScript and has no runtime dependencies. Its core loop is deterministic and does not use an LLM or touch the
-DOM. Person state is plain JSON.
+HF 2.14.1 uses utility scoring and seeded randomness, with no LLM in the actor loop and no runtime
+dependencies. Decision records expose scored terms and template narration. Person state is plain JSON.
+This is an authored simulation model, not a validated predictor of real people.
+
+## Try the games
+
+- [Twice at the Well](https://human.adamwhite.work/colony/): compare a colony without and with HF.
+- [The Day You Say Nothing](https://human.adamwhite.work/voice/): suggest actions to one man who can refuse.
+- [The Night Watch](https://human.adamwhite.work/watch/): guide a village watch across winters.
+- [All lab games](https://human.adamwhite.work/games/).
+
+## Quick start
+
+Use Node 24 or newer. In an empty directory, install the version this README describes:
+
+```sh
+npm install @adam0white/human-framework@2.14.1
+```
+
+Save these 20 lines as `quickstart.mjs`, then run `node quickstart.mjs`:
+
+```js
+import {
+  createCommunity, createPerson, createVillage,
+  predict, stepCommunity, villagerSpec,
+} from '@adam0white/human-framework';
+const start = 6 * 60; // simulation minutes
+const ids = ['ada', 'bora'];
+const people = ids.map((id, i) => createPerson(
+  villagerSpec(id, id, i + 1, { now: start, others: ids }),
+));
+const world = createVillage(people, { seed: 7 });
+const community = createCommunity(people);
+const ada = community.people[0];
+const ask = { voiceId: 'player', action: 'chat', strength: 0.6 };
+const hint = predict(ada, world.affordancesFor(ada), ask);
+console.log('Prediction:', hint.verdict, hint.reason);
+stepCommunity(community, world, start + 24 * 60, {
+  suggestions: { ada: ask },
+});
+console.log('Last decision:', ada.trace.at(-1)?.narration);
+console.log('JSON snapshot characters:', JSON.stringify(ada).length);
+```
+
+`predict` leaves the person and RNG unchanged. `stepCommunity` advances a bundled example village
+for one day; the suggestion stands at Ada's decisions. For your own game, replace that village
+with a `World` that supplies offers, percepts and actual outcomes (see [the host contract](#the-host-contract)).
+
+## What it models
+
+- Bodily and psychological needs, affect, attention, memory, beliefs, skills, habits and relationships.
+- Values, held moral norms, commitments, goals and trust in outside voices.
+- Optional faculties for long runs: aging, family, gists and character change.
+- Opt-in curiosity, bounded planning, self-set projects from host-shown prospects and pursuit persistence.
+
+The host supplies the available actions and their meaning. Projects and planning do not invent actions
+or solve arbitrary tasks. In the island control on 2.14.1, people made small free-time piles, but most
+placements replaced earlier work and the carry task did not improve. See the
+[experiment](https://github.com/adam0white/human-framework/blob/main/docs/lab/experiments/island-2026-10-20.md).
+
+HF does not provide a map, pathfinding, free-form language, a general planner or calibrated human
+behaviour. Its default norms are Islam-guided; it models a person's held understanding, never a ruling
+or divine acceptance. See [the boundaries](#what-it-does-not-model).
 
 ## The spine: Urge → Assent → Act
 
@@ -38,69 +97,13 @@ never overrides `cannot` or `willNot`.
 Every resolution also carries a machine-readable `reason` (`need:food`, `norm:theft`, `asleep`, `distrust`,
 ...) and a line in the person's voice (`says`).
 
-## Install
-
-The source is public on [GitHub](https://github.com/adam0white/human-framework) under the MIT license. Install
-it from npm (published from 2.1.3; later versions are built by the release workflow and carry an npm provenance
-attestation):
-
-```sh
-npm install @adam0white/human-framework
-```
-
-Each [GitHub release](https://github.com/adam0white/human-framework/releases) also has the tarball attached, which
-installs by URL:
-
-```sh
-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:
-
-```sh
-npm pack -w packages/human     # runs the build; writes adam0white-human-framework-<version>.tgz
-npm install /path/to/adam0white-human-framework-<version>.tgz
-```
-
-The v2.1.0 release tarball (`human-framework-2.1.0.tgz`) predates the rename and installs as
-`@human/framework`.
-
-It ships ES modules and `.d.ts` files (`exports["."]` with `types`). It requires Node ≥ 24 or a modern
-browser. The library needs `structuredClone` and nothing else from the host.
-
-## Quick start
-
-```ts
-import {
-  createCommunity, createPerson, createVillage, MINUTES_PER_DAY, predict, stepCommunity,
-  type Suggestion, villagerSpec,
-} from '@adam0white/human-framework';
-
-const ids = ['ada', 'bora'];
-const people = ids.map((id, i) => createPerson(villagerSpec(id, id, 1 + i, { now: 6 * 60, others: ids })));
-const world = createVillage(people, { seed: 7 });      // a bundled World: home, field, well, kitchen, mosque, forest
-const community = createCommunity(people);
-const ada = community.people[0]!;
-
-const ask: Suggestion = { voiceId: 'player', action: 'chat', strength: 0.6 };
-const hint = predict(ada, world.affordancesFor(ada), ask); // pure: no state change, no RNG
-console.log(hint.verdict, hint.reason, hint.says);
-
-// One day; the suggestion stands at each of Ada's decisions.
-const events = stepCommunity(community, world, 6 * 60 + MINUTES_PER_DAY, { suggestions: { ada: ask } });
-const last = ada.trace.at(-1)!;
-console.log(last.chosenAction, last.suggestion?.verdict, last.narration);
-```
-
-The runnable examples in [`examples/`](examples) go further. Run them all with
-`npm run examples -w packages/human`, or one at a time with `node examples/<name>.ts` after a build. A
-vitest (`test/examples.test.ts`) runs them, so they keep working as the code changes.
+## Package and source
 
-- [`minimal.ts`](examples/minimal.ts): a hand-written `World` (offers, percepts, outcomes) and one person's day.
-- [`suggestions.ts`](examples/suggestions.ts): one voice, five verdicts (assented, deferred, refused/willNot,
-  complied, refused/cannot), then one recorded decision and its utility terms.
-- [`community.ts`](examples/community.ts): three villagers, a standing nudge, then `runSilent` with that
-  voice muted and `diffChronicle` over the two periods.
+The package ships ES modules and TypeScript declarations. It requires Node ≥24 or a modern browser
+with `structuredClone`. Source, tests and runnable examples are on
+[GitHub](https://github.com/adam0white/human-framework/tree/main/packages/human).
+In a source checkout, `npm run examples -w packages/human` builds and runs `minimal.ts`,
+`suggestions.ts` and `community.ts`. The `examples/` and `test/` directories are not in the npm package.
 
 ## The host contract
 
@@ -141,10 +144,10 @@ place. A `social` tag is also a claim about the offered activity, not a request
 contact becomes impossible, interrupt or replan the activity instead of completing the declared
 encounter. Report only the need effects that the actual interaction supports.
 
-The current behavior is defined in [`Affordance` and `Outcome`](src/types.ts) and
-[`finish`](src/person.ts). Existing controls cover [body advancement and waking after sleep](test/person.test.ts),
-[body recovery](test/body.test.ts), [material valuation under scarcity](test/cognition-scarcity.test.ts),
-[actual material in day records](test/chronicle.test.ts), and [relationship-aware social terms](test/social.test.ts).
+The current behavior is defined in [`Affordance` and `Outcome`](https://github.com/adam0white/human-framework/blob/main/packages/human/src/types.ts) and
+[`finish`](https://github.com/adam0white/human-framework/blob/main/packages/human/src/person.ts). Existing controls cover [body advancement and waking after sleep](https://github.com/adam0white/human-framework/blob/main/packages/human/test/person.test.ts),
+[body recovery](https://github.com/adam0white/human-framework/blob/main/packages/human/test/body.test.ts), [material valuation under scarcity](https://github.com/adam0white/human-framework/blob/main/packages/human/test/cognition-scarcity.test.ts),
+[actual material in day records](https://github.com/adam0white/human-framework/blob/main/packages/human/test/chronicle.test.ts), and [relationship-aware social terms](https://github.com/adam0white/human-framework/blob/main/packages/human/test/social.test.ts).
 These boundaries require correct host reports; they do not imply a framework behavior change.
 
 ### Scheduled activity reviews
@@ -162,8 +165,8 @@ Do not restart a continued activity or refund its resources. Hard capacity vetoe
 Sleep reviews can move earlier for ordinary pending appointments. The appointment's time pressure
 can permit waking; an obligatory norm is not required. A host that ignores the scheduled review can
 make someone miss an obligation HF was ready to reconsider. This does not imply advance planning
-for unavailable future actions. See [`reviewed` and the decision lifecycle](src/person.ts) and
-[`wakeReviewAt` and commitment-based waking](src/will/will.ts).
+for unavailable future actions. See [`reviewed` and the decision lifecycle](https://github.com/adam0white/human-framework/blob/main/packages/human/src/person.ts) and
+[`wakeReviewAt` and commitment-based waking](https://github.com/adam0white/human-framework/blob/main/packages/human/src/will/will.ts).
 
 You can drive a person by hand: `decide(p, offers, { suggestion })` → `begin(p, offer, record)` →
 `tick(p, now)` → `finish(p, outcome)`, with `perceive(p, percepts)` and `interrupt(p, now, reason)` between.
@@ -212,20 +215,20 @@ reference host: `createVillage`.
 - Hosts that live people sparsely over decades can shrink what a save carries per person with
   `setRetention(p, { trace, chronicleDays })` (or `PersonSpec.retention`): fewer decision records, and day records
   bounded by age as well as count. No decision changes. `restore` also refuses a non-finite or out-of-range `now`
-  and holds every list to its live bound, so a crafted save cannot stall a host.
+  and bounds retained lists; hosts must still limit input size before parsing.
 - Version numbers are described under [Versions](#versions).
 
 ## Versions
 
 There are two version numbers, and they move independently.
 
-- **The release version** is the package version (`package.json`, now `2.2.1`) and `FRAMEWORK_VERSION`, the same
+- **The release version** is the package version (`package.json`, now `2.14.1`) 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.2.0` at release 2.2.1) versions simulation behaviour and the save format. It
+  are that version's section of the root [CHANGELOG.md](https://github.com/adam0white/human-framework/blob/main/CHANGELOG.md), with the package tarball attached
+  (`npm run release`, from a clean checkout of pushed `origin/main`).
+- **`ENGINE_VERSION`** (exported; `2.14.1` at release 2.14.1) 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.
@@ -295,22 +298,22 @@ that place lose appeal until the fear fades. Groups and factions themselves stay
   starts with a scope paragraph that also lists what that faculty leaves out.
 - **Rulings or divine judgment.** Norms come from a host catalog with provenance (`NormDefinition.sources`;
   the bundled `DEFAULT_NORMS` is Islam-guided; each reference's verification status is listed in
-  [research/norm-sources.md](../../research/norm-sources.md)). A host with its own catalog passes it as
+  [research/norm-sources.md](https://github.com/adam0white/human-framework/blob/main/research/norm-sources.md)). A host with its own catalog passes it as
   `World.catalog`, so necessity excuses and exemptions read that catalog; a norm not in it is not excused.
   A person holds an *understanding* of a norm, with a standing and a conviction. That understanding is
   not a ruling. The library never computes divine acceptance. Where schools of thought differ, the
   position the bundled catalog takes, and why, is recorded in
-  [research/decisions.md](../../research/decisions.md).
+  [research/decisions.md](https://github.com/adam0white/human-framework/blob/main/research/decisions.md).
 
 ## Further reading
 
-- [docs/framework.md](../../docs/framework.md): the architecture, which module owns which state slice, the
+- [docs/framework.md](https://github.com/adam0white/human-framework/blob/main/docs/framework.md): the architecture, which module owns which state slice, the
   utility terms, will rules, host protocols, and locked decisions.
-- [docs/api.md](../../docs/api.md): every export, grouped by module, generated from the built declarations.
+- [docs/api.md](https://github.com/adam0white/human-framework/blob/main/docs/api.md): every export, grouped by module, generated from the built declarations.
   Helpers tagged `@internal` are stripped from the shipped declarations and are not part of the API.
   The affect module's `release` is exported as `releaseEmotion`, the agenda's as `releaseCommitment`, and the
   will's scorer as `scoreAndResolve`.
-- [docs/findings.md](../../docs/findings.md): negative findings recorded during development.
+- [docs/findings.md](https://github.com/adam0white/human-framework/blob/main/docs/findings.md): negative findings recorded during development.
 
 ## License
 
@@ -343,7 +346,7 @@ const evidence = methodEvidence(learner, 'send-north', 'new-parcel');
 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. Failed demonstrations reduce support for that action. Successful alternatives retain their own support; ordinary cognition weighs the supported offers alongside other motives. A successful lecture does not certify reliable execution. [The routing control](examples/method-control.ts) demonstrates changed teaching, withheld teaching, a scalar-skill control and acquired-state ablation with two methods and an exception. [The alternatives control](examples/method-alternatives-control.ts) demonstrates two independently successful procedures under the same observations, failed practice, hunger and exact restore.
+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. Failed demonstrations reduce support for that action. Successful alternatives retain their own support; ordinary cognition weighs the supported offers alongside other motives. A successful lecture does not certify reliable execution. [The routing control](https://github.com/adam0white/human-framework/blob/main/packages/human/examples/method-control.ts) demonstrates changed teaching, withheld teaching, a scalar-skill control and acquired-state ablation with two methods and an exception. [The alternatives control](https://github.com/adam0white/human-framework/blob/main/packages/human/examples/method-alternatives-control.ts) demonstrates two independently successful procedures under the same observations, failed practice, hunger and exact restore.
 
 
 ## Receiving a possible future route
@@ -400,4 +403,40 @@ Only actual terminal outcomes advance terminal goals. Finishing one's own reques
 
 Knowledge lives in optional `Person.prospection` and survives snapshot/restore. A percept admits at most four additions/withdrawals combined, atomically. Invalid entries or duplicate source/id identities reject the entire batch. Equal/lower revisions do not reinforce or refresh; a higher revision replaces. There are at most 16 entries and 64 revision records. Consumed entries are evicted first, then the oldest remaining entries, while their revision records remain; a batch requiring more still-valid revision records is rejected. Entries and revision memory expire within seven days. Deduplication is bounded, not a durable audit. Capacity is shared across sources and admission does not allocate by trust. One prolific source can occupy the finite entry/revision capacity, causing other new ids to be rejected until revision space expires; this is bounded memory, not a source-fairness or trust firewall. Hosts must bound the premises they deliver. The pure query exposes retained entries, present feasibility and retained revisions.
 
-[The frozen control](examples/received-consequences.ts) publishes useful, late, costly, uncertain, withheld, removed-knowledge, removed-goal, temporal-off and refused arms in two renamed domains. This faculty does not search action graphs, predict future body state, price all waiting opportunities or guarantee consent or success. Its numerical bounds and control parameters are engineering assumptions.
+[The frozen control](https://github.com/adam0white/human-framework/blob/main/packages/human/examples/received-consequences.ts) publishes useful, late, costly, uncertain, withheld, removed-knowledge, removed-goal, temporal-off and refused arms in two renamed domains. This one-step faculty does not search action graphs, price all waiting opportunities or guarantee consent or success. Opt-in bounded planning (2.12.0) and bodily forecast (2.5.0) extend valuation separately. Its numerical bounds and control parameters are engineering assumptions.
+
+## Persona projection (opt-in)
+
+`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.
+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.
+Skills keep exact levels and practice evidence. Episode action/person/place/voice references need explicit
+bindings. Both evidence timestamps and birth minute shift by `targetOpening.now - source.now`; the Person
+RNG carries unchanged. Commitments have explicit target-calendar windows, identical duration, kind,
+importance and recurrence, and stay pending. This is a binding for a known calendar, not a calendar translator.
+
+Admission requires the declared identity binding, matching name, sex, age, healthy compatible body,
+and matching family/bond provenance. Version 1 rejects injuries, illness, downing and exposures. It also rejects pregnancy, courtships, marriages
+and mourning because their dates require a separate explicit clock mapping. It rejects
+running source activities, active goals/projects, owed duties and unmapped ongoing obligations, including
+completed occurrences of unreleased recurring chains. The host must release finished employment in its own
+replay. The host owns the cast registry, death history, branch authority, destination references and truth of
+selected facts. A hash is not authentication. An old projection cannot override a dead target Person.
+
+Target authors transient body state, needs, affect, social/conscience state and optional behaviour settings.
+Portable skills and selected episodes replace target priors in those stores. The report discloses exclusions;
+it does not claim that the complete source life continued. The original checkpoint belongs in the source save.
+Pin the admitted Person and mapping version in the target replay. The transport owns its cryptographic hash,
+branch metadata, consent and storage bounds. See `examples/persona-control.ts` for a deterministic two-host
+control with preserved evidence, source immutability and an unmapped-skill comparison.
+
+The agenda retains scheduled make-up records after the matching commitment is kept. Passport admission
+recognizes that positive kept record as completed history. Missing or pruned records do not establish completion.
+A host that needs durable completion evidence can explicitly call `retirePaidMakeUps(person)` before bounded
+commitment history prunes it. It removes only records matched to an existing, closed, kept make-up and returns
+recursively frozen, detached `MakeUpReceipt` objects. Persist those receipts in the source replay. Pending,
+broken, released, exempt and missing matches remain unresolved. The normal actor loop never calls retirement;
+existing games and saves keep their previous behavior until a host opts in.

package/dist/agenda/agenda.d.ts

@@ -182,6 +182,20 @@ export declare function applyExemptions(p: Person, now: Minute, ctx?: {
     exempted: Commitment[];
     owed: OwedMakeUp[];
 };
+export interface MakeUpReceipt {
+    readonly owed: Readonly<OwedMakeUp>;
+    readonly commitment: Readonly<Commitment>;
+    /** Source clock when the host explicitly retired the recorded debt. */
+    readonly recordedAt: Minute;
+}
+/**
+ * Opt-in host archive boundary. Remove only retained make-up records with a matching existing kept instance,
+ * returning detached, recursively frozen receipts for the host to persist in its replay. Keep commitments and
+ * every unpaid, pending, released, exempt or unproven record. Call before ordinary bounded history prunes the
+ * evidence. No actor-loop call is added; hosts that do not call this retain exact prior state and behavior.
+ * Records describe simulated completion, never divine acceptance or a waiver of an unfulfilled duty.
+ */
+export declare function retirePaidMakeUps(p: Person): readonly MakeUpReceipt[];
 /** Make-ups still owed and not yet scheduled. */
 export declare const owedMakeUps: (p: Person) => OwedMakeUp[];
 /**

package/dist/agenda/agenda.js

@@ -231,7 +231,8 @@ export function release(p, id) {
     c.status = 'released';
     return true;
 }
-const sameChain = (a, b) => a.chain !== undefined && b.chain !== undefined ? a.kind === b.kind && a.chain === b.chain : sameShape(a, b);
+/** Compare recurrence identity without changing agenda state. @internal */
+export const sameChain = (a, b) => a.chain !== undefined && b.chain !== undefined ? a.kind === b.kind && a.chain === b.chain : sameShape(a, b);
 const sameShape = (a, b) => a.kind === b.kind &&
     (a.violatedBy ?? []).join('|') === (b.violatedBy ?? []).join('|') &&
     a.normId === b.normId &&
@@ -888,6 +889,54 @@ function boundOwed(state) {
         owed.splice(i >= 0 ? i : 0, 1);
     }
 }
+/** A kept, closed instance is positive recorded evidence; scheduling or missing history is not. */
+function recordedKeptMakeUp(p, owed) {
+    return p.agenda.commitments.find((c) => owed.scheduledAs !== undefined &&
+        c.id === owed.scheduledAs &&
+        c.makeUpOf === owed.ofId &&
+        c.status === 'kept' &&
+        c.kind === owed.kind &&
+        c.normId === owed.normId &&
+        c.exempt === undefined &&
+        c.until <= p.now);
+}
+/**
+ * Whether any retained make-up record lacks a recorded kept matching instance. Scheduling alone is not
+ * fulfillment. Missing/pruned history remains unresolved to this reader; it does not infer payment from absence.
+ * Read-only; does not change the agenda's retained debt/history representation. @internal
+ */
+export function hasUnresolvedMakeUps(p) {
+    return (p.agenda.owed ?? []).some((owed) => recordedKeptMakeUp(p, owed) === undefined);
+}
+function freezeReceipt(value) {
+    if (value !== null && typeof value === 'object') {
+        for (const child of Object.values(value))
+            freezeReceipt(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * Opt-in host archive boundary. Remove only retained make-up records with a matching existing kept instance,
+ * returning detached, recursively frozen receipts for the host to persist in its replay. Keep commitments and
+ * every unpaid, pending, released, exempt or unproven record. Call before ordinary bounded history prunes the
+ * evidence. No actor-loop call is added; hosts that do not call this retain exact prior state and behavior.
+ * Records describe simulated completion, never divine acceptance or a waiver of an unfulfilled duty.
+ */
+export function retirePaidMakeUps(p) {
+    const receipts = [];
+    const unresolved = [];
+    for (const owed of p.agenda.owed ?? []) {
+        const commitment = recordedKeptMakeUp(p, owed);
+        if (commitment)
+            receipts.push(structuredClone({ owed, commitment, recordedAt: p.now }));
+        else
+            unresolved.push(owed);
+    }
+    if (receipts.length)
+        p.agenda.owed = unresolved;
+    return freezeReceipt(receipts);
+}
 /** Make-ups still owed and not yet scheduled. */
 export const owedMakeUps = (p) => (p.agenda.owed ?? []).filter((o) => o.scheduledAs === undefined);
 /**

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.14.1";
+export declare const FRAMEWORK_VERSION = "2.15.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';
-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.ts';
+export type { GoalTemplate, MakeUpReceipt, PrayerCalendar, PrayerSchedule, PrayerTimes, Retimer, } from './agenda/index.ts';
+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, retirePaidMakeUps, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.ts';
 export * from './beliefs/index.ts';
 export * from './body/index.ts';
 export * from './character/index.ts';
@@ -30,6 +30,7 @@ export * from './needs/index.ts';
 export * from './partnering/index.ts';
 export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistence/index.ts';
 export * from './person.ts';
+export * from './persona.ts';
 export { considerProjects, enableProjects, PROJECTS_DEFAULTS, projectAppeal } from './projects/index.ts';
 export * from './promptings/index.ts';
 export type { ConsequenceEvidence, PlanRoute, PlanStep } from './prospection/index.ts';

package/dist/index.js

@@ -1,8 +1,8 @@
 /** Human Framework public surface. */
-export const FRAMEWORK_VERSION = '2.14.1';
+export const FRAMEWORK_VERSION = '2.15.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';
+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, retirePaidMakeUps, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.js';
 export * from './beliefs/index.js';
 export * from './body/index.js';
 export * from './character/index.js';
@@ -27,6 +27,7 @@ export * from './needs/index.js';
 export * from './partnering/index.js';
 export { enablePersistence, PERSISTENCE_DEFAULTS, pursuitOf } from './persistence/index.js';
 export * from './person.js';
+export * from './persona.js';
 export { considerProjects, enableProjects, PROJECTS_DEFAULTS, projectAppeal } from './projects/index.js';
 export * from './promptings/index.js';
 export { bodyForecastFor, bodyForecastTerm, consequenceEvidence, enablePlanning, FORECAST_DEFAULTS, forecastLine, forecastThresholds, PROSPECTION_DEFAULTS, seedConsequences, } from './prospection/index.js';

package/dist/persona.d.ts

@@ -0,0 +1,76 @@
+import type { Commitment, Episode, Person, Skill } from './types.ts';
+export interface PersonaEpisodeMap {
+    id: string;
+    action?: string;
+    actorId?: string;
+    targetId?: string;
+    placeId?: string;
+    voiceId?: string;
+    /** Tags are semantic keys too; omitted means no portable tags. */
+    tags?: string[];
+}
+export interface PersonaCommitmentMap {
+    id: string;
+    actions: string[];
+    toId?: string;
+    targetId?: string;
+    normId?: string;
+    chain?: string;
+    /** Explicit target-calendar window. Duration and recurrence must remain identical. */
+    from: number;
+    until: number;
+}
+export interface PersonaProjection {
+    version: string;
+    skills: Record<string, string>;
+    episodes?: Record<string, PersonaEpisodeMap>;
+    /** Every pending or continuing recurring obligation requires a named binding. */
+    commitments?: Record<string, PersonaCommitmentMap>;
+}
+export interface PersonaProjectionSnapshot {
+    format: 'hf-persona-state/1';
+    mappingVersion: string;
+    source: {
+        schema: number;
+        engine: string;
+        id: string;
+        now: number;
+    };
+    name: string;
+    life: Person['life'];
+    rng: Person['rng'];
+    traits: Person['traits'];
+    values: Person['values'];
+    health: {
+        health: number;
+        fitness: number;
+        circadianPeak: number;
+    };
+    family: Person['family'] | null;
+    bonds: Person['bonds'] | null;
+    skills: Record<string, Skill>;
+    skillRetention: Person['skillRetention'] | null;
+    episodes: Episode[];
+    /** Already bound to the target calendar by the explicitly versioned host mapping. */
+    commitments: Commitment[];
+    limitations: string[];
+}
+export interface PersonaAdmission {
+    mappingVersion: string;
+    sourceId: string;
+    targetId: string;
+}
+export interface PersonaAdmissionResult {
+    person: Person;
+    report: {
+        mappingVersion: string;
+        offset: number;
+        limitations: string[];
+    };
+}
+/** Validates untrusted portable data without restoring defaults or accepting extra live fields. */
+export declare function validatePersonaProjection(input: unknown): PersonaProjectionSnapshot;
+/** Hosts must migrate supported old saves first. No random draws or mutation occur here. */
+export declare function projectPersona(source: Person, mapping: PersonaProjection): PersonaProjectionSnapshot;
+/** Return a detached target opening; a later shelf change cannot affect it. Host owns cast/branch/death authority. */
+export declare function admitPersona(input: unknown, target: Person, policy: PersonaAdmission): PersonaAdmissionResult;

package/dist/persona.js

@@ -0,0 +1,457 @@
+/**
+ * SCOPE: opt-in, deterministic projection between host-authored chapter openings. Copies exact temperament,
+ * values and RNG, explicitly mapped skills, episodes and commitments, with declared clock offsets. Checks
+ * 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.
+ */
+import { hasUnresolvedMakeUps, sameChain } from './agenda/agenda.js';
+import { createPerson } from './person.js';
+import { restore, snapshot } from './restore.js';
+import { ENGINE_VERSION, MAX_MINUTE, PERSON_SCHEMA } from './types.js';
+function fail(reason) {
+    throw new Error(`persona: ${reason}`);
+}
+function obj(x) {
+    if (!x || typeof x !== 'object' || Array.isArray(x))
+        fail('expected object');
+}
+function keys(x, allowed, required = allowed) {
+    obj(x);
+    if (Object.keys(x).some((k) => !allowed.includes(k)) || required.some((k) => !Object.hasOwn(x, k)))
+        fail('unsupported or missing field');
+}
+function text(x) {
+    if (typeof x !== 'string' ||
+        !x.length ||
+        x.length > 1024 ||
+        ['__proto__', 'constructor', 'prototype'].includes(x))
+        fail('invalid text/reference');
+}
+function num(x, min = -MAX_MINUTE, max = MAX_MINUTE) {
+    if (typeof x !== 'number' || !Number.isFinite(x) || x < min || x > max)
+        fail('invalid number/timestamp');
+}
+function texts(x, max = 128) {
+    if (!Array.isArray(x) || x.length > max)
+        fail('invalid list');
+    for (const value of x)
+        text(value);
+}
+function canonical(x) {
+    return JSON.stringify(x, (_key, value) => value && typeof value === 'object' && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : value);
+}
+function same(a, b) {
+    return canonical(a) === canonical(b);
+}
+function compatibleBody(p) {
+    if (!p.body.alive)
+        fail('dead person cannot travel or be revived');
+    if (p.body.health <= 0 ||
+        p.body.injuries.length ||
+        p.body.illnesses.length ||
+        p.body.downed ||
+        Object.keys(p.body.exposures ?? {}).length)
+        fail('unsupported health condition');
+}
+function boundRecord(x) {
+    obj(x);
+    if (Object.keys(x).length > 128)
+        fail('too many mappings');
+    for (const key of Object.keys(x))
+        text(key);
+}
+function episode(x) {
+    keys(x, [
+        'id',
+        'at',
+        'kind',
+        'action',
+        'actorId',
+        'targetId',
+        'placeId',
+        'valence',
+        'salience',
+        'summary',
+        'tags',
+        'voiceId',
+        'recalledAt',
+    ], ['id', 'at', 'kind', 'valence', 'salience', 'summary', 'tags']);
+    for (const key of ['id', 'kind', 'summary', 'action', 'actorId', 'targetId', 'placeId', 'voiceId'])
+        if (x[key] !== undefined)
+            text(x[key]);
+    num(x.at);
+    num(x.valence, -1, 1);
+    num(x.salience, 0, 1);
+    texts(x.tags);
+    if (x.recalledAt !== undefined)
+        num(x.recalledAt);
+}
+function commitment(x) {
+    keys(x, [
+        'id',
+        'kind',
+        'toId',
+        'actions',
+        'targetId',
+        'from',
+        'until',
+        'normId',
+        'importance',
+        'status',
+        'recurEvery',
+        'label',
+        'chain',
+    ], ['id', 'kind', 'actions', 'from', 'until', 'importance', 'status']);
+    for (const key of ['id', 'toId', 'targetId', 'normId', 'label', 'chain'])
+        if (x[key] !== undefined)
+            text(x[key]);
+    if (!['promise', 'duty', 'appointment', 'worship', 'job'].includes(String(x.kind)) ||
+        x.status !== 'pending')
+        fail('unsupported obligation');
+    texts(x.actions);
+    if (!x.actions.length)
+        fail('empty obligation actions');
+    num(x.from);
+    num(x.until);
+    if (x.until < x.from)
+        fail('invalid obligation window');
+    num(x.importance, 0, 1);
+    if (x.recurEvery !== undefined)
+        num(x.recurEvery, 1);
+}
+function boundedJson(input) {
+    const pending = [{ value: input, depth: 0 }];
+    const seen = new Set();
+    let nodes = 0;
+    while (pending.length) {
+        const item = pending.pop();
+        if (!item)
+            break;
+        if (++nodes > 8192 || item.depth > 16)
+            fail('JSON bounds exceeded');
+        const { value, depth } = item;
+        if (value === null || typeof value === 'boolean')
+            continue;
+        if (typeof value === 'string') {
+            if (value.length > 1024)
+                fail('text bounds exceeded');
+            continue;
+        }
+        if (typeof value === 'number') {
+            num(value);
+            continue;
+        }
+        if (typeof value !== 'object' || seen.has(value))
+            fail('non-JSON or cyclic input');
+        seen.add(value);
+        if (!Array.isArray(value) &&
+            Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null)
+            fail('non-JSON object');
+        for (const [key, child] of Object.entries(value)) {
+            if (['__proto__', 'prototype', 'constructor'].includes(key))
+                fail('unsafe reference');
+            pending.push({ value: child, depth: depth + 1 });
+        }
+    }
+}
+/** Validates untrusted portable data without restoring defaults or accepting extra live fields. */
+export function validatePersonaProjection(input) {
+    boundedJson(input);
+    keys(input, [
+        'format',
+        'mappingVersion',
+        'source',
+        'name',
+        'life',
+        'rng',
+        'traits',
+        'values',
+        'health',
+        'family',
+        'bonds',
+        'skills',
+        'skillRetention',
+        'episodes',
+        'commitments',
+        'limitations',
+    ]);
+    if (input.format !== 'hf-persona-state/1')
+        fail('unsupported format');
+    text(input.mappingVersion);
+    text(input.name);
+    keys(input.source, ['schema', 'engine', 'id', 'now']);
+    if (input.source.schema !== PERSON_SCHEMA || input.source.engine !== ENGINE_VERSION)
+        fail('unsupported source schema/engine; migrate the source before projection');
+    text(input.source.id);
+    num(input.source.now);
+    keys(input.life, ['bornAt', 'sex']);
+    num(input.life.bornAt);
+    if (!['female', 'male'].includes(String(input.life.sex)))
+        fail('invalid sex');
+    keys(input.rng, ['a', 'b', 'c', 'd']);
+    for (const [key, value] of Object.entries(input.rng)) {
+        num(value, key === 'a' ? -0x80000000 : 0, key === 'a' ? 0x7fffffff : 0xffffffff);
+        if (!Number.isInteger(value))
+            fail('invalid RNG');
+    }
+    const base = createPerson({ id: 'validation', name: 'validation', seed: 0, bornAt: 0, sex: 'female' });
+    for (const slice of ['traits', 'values']) {
+        keys(input[slice], Object.keys(base[slice]));
+        for (const value of Object.values(input[slice]))
+            num(value, 0, 1);
+    }
+    keys(input.health, ['health', 'fitness', 'circadianPeak']);
+    num(input.health.health, Number.MIN_VALUE, 1);
+    num(input.health.fitness, 0, 1);
+    num(input.health.circadianPeak, 0, 1440);
+    boundRecord(input.skills);
+    for (const value of Object.values(input.skills)) {
+        keys(value, ['level', 'practice', 'lastPracticed']);
+        num(value.level, 0, 1);
+        num(value.practice, 0);
+        num(value.lastPracticed);
+        if (value.lastPracticed > input.source.now)
+            fail('future skill evidence');
+    }
+    if (input.skillRetention !== null) {
+        keys(input.skillRetention, ['consolidationHours']);
+        num(input.skillRetention.consolidationHours, Number.MIN_VALUE);
+    }
+    if (input.family !== null) {
+        obj(input.family);
+        if (input.family.pregnancy !== undefined)
+            fail('unsupported temporal family state: pregnancy');
+    }
+    if (input.bonds !== null) {
+        obj(input.bonds);
+        if (input.bonds.mourning !== undefined ||
+            (Array.isArray(input.bonds.courtships) && input.bonds.courtships.length > 0) ||
+            (Array.isArray(input.bonds.marriages) && input.bonds.marriages.length > 0)) {
+            fail('unsupported temporal bonds state');
+        }
+    }
+    for (const field of ['family', 'bonds']) {
+        if (input[field] !== null) {
+            obj(input[field]);
+            const check = snapshot(base);
+            Object.assign(check, { [field]: input[field] });
+            if (!same(restore(check)[field], input[field]))
+                fail(`invalid ${field} provenance`);
+        }
+    }
+    if (!Array.isArray(input.episodes) ||
+        input.episodes.length > 128 ||
+        !Array.isArray(input.commitments) ||
+        input.commitments.length > 128)
+        fail('invalid portable lists');
+    for (const value of input.episodes) {
+        episode(value);
+        if (value.at > input.source.now ||
+            (value.recalledAt !== undefined && value.recalledAt > input.source.now))
+            fail('future episode evidence');
+    }
+    for (const value of input.commitments)
+        commitment(value);
+    for (const list of [input.episodes, input.commitments])
+        if (new Set(list.map((x) => x.id)).size !== list.length)
+            fail('duplicate portable id');
+    texts(input.limitations, 256);
+    return structuredClone(input);
+}
+/** Hosts must migrate supported old saves first. No random draws or mutation occur here. */
+export function projectPersona(source, mapping) {
+    const p = restore(snapshot(source));
+    compatibleBody(p);
+    if (p.activity)
+        fail('running activity');
+    if (p.agenda.goals.some((g) => g.status === 'active') || p.projects?.currentGoalId)
+        fail('active goal/project');
+    if (hasUnresolvedMakeUps(p) || p.agenda.lapse)
+        fail('unmapped owed obligation');
+    text(mapping.version);
+    boundRecord(mapping.skills);
+    const skills = Object.create(null);
+    for (const [from, to] of Object.entries(mapping.skills).sort()) {
+        text(to);
+        const skill = p.skills[from];
+        if (!Object.hasOwn(p.skills, from) || !skill || Object.hasOwn(skills, to))
+            fail('missing/duplicate skill mapping');
+        skills[to] = structuredClone(skill);
+    }
+    const episodes = [];
+    for (const [id, map] of Object.entries(mapping.episodes ?? {}).sort()) {
+        const old = p.memory.episodes.find((e) => e.id === id);
+        if (!old)
+            fail('missing approved episode');
+        keys(map, ['id', 'action', 'actorId', 'targetId', 'placeId', 'voiceId', 'tags'], ['id']);
+        // Every existing semantic reference needs a declared mapping; omission must never preserve host-local ids.
+        for (const ref of ['action', 'actorId', 'targetId', 'placeId', 'voiceId'])
+            if (old[ref] !== undefined && map[ref] === undefined)
+                fail(`unmapped episode ${ref}`);
+        const copy = {
+            id: map.id,
+            at: old.at,
+            kind: old.kind,
+            valence: old.valence,
+            salience: old.salience,
+            summary: old.summary,
+            tags: map.tags ?? [],
+        };
+        for (const ref of ['action', 'actorId', 'targetId', 'placeId', 'voiceId'])
+            if (map[ref] !== undefined)
+                copy[ref] = map[ref];
+        if (old.recalledAt !== undefined)
+            copy.recalledAt = old.recalledAt;
+        episodes.push(copy);
+    }
+    const commitments = [];
+    const bindings = mapping.commitments ?? {};
+    for (const old of p.agenda.commitments) {
+        // Closed history no longer owns the chain once an actual later instance exists, including a release.
+        if (old.status !== 'pending' &&
+            p.agenda.commitments.some((next) => next.from > old.from && sameChain(old, next)))
+            continue;
+        const ongoing = old.status === 'pending' ||
+            (old.recurEvery !== undefined &&
+                old.status !== 'released' &&
+                (old.recurUntil === undefined || old.recurUntil > p.now));
+        if (!ongoing)
+            continue;
+        const map = Object.hasOwn(bindings, old.id) ? bindings[old.id] : undefined;
+        if (!map || old.status !== 'pending')
+            fail(`unmapped obligation ${old.id}`);
+        keys(map, ['id', 'actions', 'toId', 'targetId', 'normId', 'chain', 'from', 'until'], ['id', 'actions', 'from', 'until']);
+        if (old.until - old.from !== map.until - map.from)
+            fail('obligation duration changed');
+        for (const ref of ['toId', 'targetId', 'normId', 'chain'])
+            if (old[ref] !== undefined && map[ref] === undefined)
+                fail(`unmapped obligation ${ref}`);
+        const copy = {
+            id: map.id,
+            kind: old.kind,
+            actions: [...map.actions],
+            from: map.from,
+            until: map.until,
+            importance: old.importance,
+            status: 'pending',
+        };
+        for (const ref of ['toId', 'targetId', 'normId', 'chain'])
+            if (map[ref] !== undefined)
+                copy[ref] = map[ref];
+        if (old.recurEvery !== undefined)
+            copy.recurEvery = old.recurEvery;
+        if (old.label !== undefined)
+            copy.label = old.label;
+        if (old.exempt ||
+            old.makeUpOf ||
+            old.recurUntil !== undefined ||
+            old.violatedBy ||
+            old.firm ||
+            old.exemptWhen)
+            fail('unsupported obligation semantics');
+        commitments.push(copy);
+    }
+    for (const id of Object.keys(bindings))
+        if (!p.agenda.commitments.some((c) => c.id === id && c.status === 'pending'))
+            fail('missing obligation binding');
+    const limitations = [
+        'source transient body/needs/affect/ambient omitted; target arrival policy',
+        'source habits/methods/beliefs/social/conscience omitted; target authored state',
+        'source optional behaviour stores and decision history omitted; target authored state',
+        'family/bonds provenance checked; target authored state',
+    ];
+    for (const key of Object.keys(p.skills).sort())
+        if (!Object.hasOwn(mapping.skills, key))
+            limitations.push(`skill:${key}`);
+    for (const e of p.memory.episodes)
+        if (!Object.hasOwn(mapping.episodes ?? {}, e.id))
+            limitations.push(`episode:${e.id}`);
+    return validatePersonaProjection({
+        format: 'hf-persona-state/1',
+        mappingVersion: mapping.version,
+        source: { schema: source.schema, engine: p.engine, id: p.id, now: p.now },
+        name: p.name,
+        life: p.life,
+        rng: p.rng,
+        traits: p.traits,
+        values: p.values,
+        health: { health: p.body.health, fitness: p.body.fitness, circadianPeak: p.body.circadianPeak },
+        family: p.family ?? null,
+        bonds: p.bonds ?? null,
+        skills,
+        skillRetention: p.skillRetention ?? null,
+        episodes,
+        commitments,
+        limitations,
+    });
+}
+/** Return a detached target opening; a later shelf change cannot affect it. Host owns cast/branch/death authority. */
+export function admitPersona(input, target, policy) {
+    const projection = validatePersonaProjection(input);
+    const p = restore(snapshot(target));
+    if (projection.mappingVersion !== policy.mappingVersion)
+        fail('unsupported mapping');
+    if (projection.source.id !== policy.sourceId || p.id !== policy.targetId)
+        fail('identity binding conflict');
+    compatibleBody(p);
+    const offset = p.now - projection.source.now;
+    const shift = (at) => {
+        const mapped = at + offset;
+        num(mapped);
+        return mapped;
+    };
+    if (p.life.sex !== projection.life.sex ||
+        p.life.bornAt !== shift(projection.life.bornAt) ||
+        p.name !== projection.name)
+        fail('identity/age conflict');
+    if (!same(p.family ?? null, projection.family) || !same(p.bonds ?? null, projection.bonds))
+        fail('family/bonds conflict');
+    if (!same({ health: p.body.health, fitness: p.body.fitness, circadianPeak: p.body.circadianPeak }, projection.health))
+        fail('health compatibility conflict');
+    if (p.activity)
+        fail('target already active');
+    p.traits = projection.traits;
+    p.values = projection.values;
+    p.rng = projection.rng;
+    // A sparse projection replaces target priors for portable skill/history stores, never blends evidence.
+    p.skills = projection.skills;
+    if (projection.skillRetention)
+        p.skillRetention = projection.skillRetention;
+    else
+        delete p.skillRetention;
+    for (const skill of Object.values(p.skills))
+        skill.lastPracticed = shift(skill.lastPracticed);
+    p.memory.episodes = projection.episodes;
+    for (const e of p.memory.episodes) {
+        e.at = shift(e.at);
+        if (e.recalledAt !== undefined)
+            e.recalledAt = shift(e.recalledAt);
+    }
+    p.memory.nextEpisode = Math.max(p.memory.nextEpisode, p.memory.episodes.length + 1);
+    for (const e of p.memory.episodes) {
+        if (/^e\d+$/.test(e.id)) {
+            const next = Number(e.id.slice(1)) + 1;
+            num(next, 0);
+            p.memory.nextEpisode = Math.max(p.memory.nextEpisode, next);
+        }
+    }
+    for (const c of projection.commitments) {
+        if (c.until < p.now ||
+            p.agenda.commitments.some((old) => old.id === c.id || (c.chain && old.chain === c.chain)))
+            fail('target obligation conflict');
+        p.agenda.commitments.push(c);
+    }
+    p.agenda.nextId = Math.max(p.agenda.nextId, p.agenda.commitments.length + 1);
+    const restored = restore(p);
+    if (!same(restored, p))
+        fail('admitted state exceeds supported bounds');
+    return {
+        person: restored,
+        report: { mappingVersion: policy.mappingVersion, offset, limitations: [...projection.limitations] },
+    };
+}

package/package.json

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