@adam0white/human-framework 2.14.1 → 2.16.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,59 @@ 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.
+
+
+### Calendar passports (2.16.0, opt-in)
+
+Use `projectCalendarPersona(source, { version, skills, episodes, calendar })` when declared obligations must
+travel. `calendar` has version `hf-persona-calendar-map/1`, one exact clock offset, explicit injective maps
+for commitment, chain, action, entity and norm references, and the source-backed norm catalog.
+The result is `hf-persona-calendar/1`, wrapping the original approved Person projection and a separate
+calendar. It preserves continuing commitments, every owed record, actual retained receipts, held norm
+understandings and lapse state. A missing scheduled receipt remains unresolved and is disclosed; it never
+becomes a paid duty. `isContinuingCommitment(agenda, commitment)` lets a host construct the required maps
+using the owning agenda's existing recurrence semantics.
+
+`validateCalendarPersona` strictly validates portable data. `admitCalendarPersona(payload, opening,
+{ mappingVersion, sourceId, targetId, targetNorms })` checks the offset and exact catalog semantics before
+returning a detached Person. The receiving calendar must be empty; authored role goals may remain. After
+admission, the host uses ordinary agenda APIs and its declared calendar. No duty is waived, no new ruling
+is invented, and no obligation is converted to a score. Activities, projects and incompatible identity or
+health remain unsupported. The original passport format and no-call continuation remain unchanged.

package/dist/agenda/agenda.d.ts

@@ -56,6 +56,8 @@ export declare function createAgenda(spec: {
 export declare function promise(p: Person, c: Omit<Commitment, 'id' | 'status'>): Commitment;
 /** Release a pending commitment (the other party let it go). Released commitments do not recur. */
 export declare function release(p: Person, id: string): boolean;
+/** Whether an instance still owns a pending duty or a recurrence that can produce its next window. Read-only. */
+export declare const isContinuingCommitment: (state: AgendaState, c: Commitment) => boolean;
 /**
  * Whether an activity that would keep `c` is under way at `now`: begun no later than the window's end
  * (`spanMeetsWindow`), not yet ended, not sleep, and serving `c` (listed in `fulfills` or matching its action and
@@ -182,6 +184,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 &&
@@ -245,6 +246,13 @@ const sameShape = (a, b) => a.kind === b.kind &&
 const hasSuccessor = (state, c) => state.commitments.some((x) => x !== c && x.from > c.from && sameChain(x, c));
 /** Closed instances that carry their chain on: kept, broken, or released by an exemption (not by the other party). */
 const chainLink = (c) => c.status === 'kept' || c.status === 'broken' || (c.status === 'released' && c.exempt !== undefined);
+/** Whether an instance still owns a pending duty or a recurrence that can produce its next window. Read-only. */
+export const isContinuingCommitment = (state, c) => c.status === 'pending' ||
+    (c.recurEvery !== undefined &&
+        c.recurEvery > 0 &&
+        chainLink(c) &&
+        (c.recurUntil === undefined || c.from + c.recurEvery <= c.recurUntil) &&
+        !hasSuccessor(state, c));
 const needsSpawn = (state, c, now) => c.recurEvery !== undefined &&
     c.recurEvery > 0 &&
     chainLink(c) &&
@@ -888,6 +896,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.16.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, isContinuingCommitment, isUnderWay, MAKRUH_DEFAULTS, makruhWindows, missedExcuse, onFinished, owedMakeUps, PRAYER_IMPORTANCE, PURPOSE_DEFAULTS, prayerWindows, pressureReachedAt, promise, proposeGoals, RAMADAN_DEFAULTS, ramadanFast, ramadanMeals, release as releaseCommitment, retimeCommitments, retirePaidMakeUps, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.ts';
 export * from './beliefs/index.ts';
 export * from './body/index.ts';
 export * from './character/index.ts';
@@ -30,6 +30,8 @@ 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 * from './persona-calendar.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.16.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, isContinuingCommitment, isUnderWay, MAKRUH_DEFAULTS, makruhWindows, missedExcuse, onFinished, owedMakeUps, PRAYER_IMPORTANCE, PURPOSE_DEFAULTS, prayerWindows, pressureReachedAt, promise, proposeGoals, RAMADAN_DEFAULTS, ramadanFast, ramadanMeals, release as releaseCommitment, retimeCommitments, retirePaidMakeUps, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.js';
 export * from './beliefs/index.js';
 export * from './body/index.js';
 export * from './character/index.js';
@@ -27,6 +27,8 @@ 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 * from './persona-calendar.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-calendar.d.ts

@@ -0,0 +1,39 @@
+import { type PersonaAdmission, type PersonaAdmissionResult, type PersonaProjection, type PersonaProjectionSnapshot } from './persona.ts';
+import { type Commitment, type HeldNorm, type NormDefinition, type OwedMakeUp, type Person } from './types.ts';
+export interface PersonaCalendarMap {
+    version: 'hf-persona-calendar-map/1';
+    /** Exactly target opening minus source departure. All retained calendar timestamps use this offset. */
+    offset: number;
+    references: {
+        commitments: Record<string, string>;
+        chains: Record<string, string>;
+        actions: Record<string, string>;
+        entities: Record<string, string>;
+        norms: Record<string, string>;
+    };
+    sourceNorms: NormDefinition[];
+}
+export interface CalendarPersonaProjection extends Omit<PersonaProjection, 'commitments'> {
+    calendar: PersonaCalendarMap;
+}
+export interface CalendarPersonaSnapshot {
+    format: 'hf-persona-calendar/1';
+    person: PersonaProjectionSnapshot;
+    calendar: {
+        offset: number;
+        commitments: Commitment[];
+        owed: OwedMakeUp[];
+        lapse: Person['agenda']['lapse'] | null;
+        heldNorms: HeldNorm[];
+        norms: NormDefinition[];
+    };
+}
+export interface CalendarPersonaAdmission extends PersonaAdmission {
+    targetNorms: NormDefinition[];
+}
+/** Validate portable calendar data strictly; no restore defaults or debt settlement. */
+export declare function validateCalendarPersona(input: unknown): CalendarPersonaSnapshot;
+/** Source declares a complete semantic ID map, a clock offset and source-backed norm catalog. */
+export declare function projectCalendarPersona(source: Person, mapping: CalendarPersonaProjection): CalendarPersonaSnapshot;
+/** Receiver declares identical norm meanings and a clean calendar at the exact declared opening clock. */
+export declare function admitCalendarPersona(input: unknown, target: Person, policy: CalendarPersonaAdmission): PersonaAdmissionResult;