@adam0white/human-framework 2.17.0 → 2.18.0

package/README.md

@@ -476,3 +476,16 @@ Narration remains unchanged unless requested. Set `person.lexicon.variety`,
 `perceive` adds a third `{ reputationTraits }` argument. See the architecture's
 [narration and social host options](../../docs/framework.md#narration-and-social-host-options-opt-in)
 for cause-aware reviews and actor-addressed recall. These options change no default continuation.
+
+### Bounded chapter clock (2.18.0, opt-in)
+
+`createChapterClock(seed, nowMs)` and `advanceChapterClock(clock, nowMs)` are pure helpers for hosts that author coarse between-chapter life. They do not step a `Person`. The clock quantizes a supplied integer millisecond value into real-hour slots. A return processes at most the newest24 slots and reports the omitted count. Its watermark never moves backward. Repeating the same return produces no new slots. Each retained slot's draw depends only on its absolute slot and pinned seed.
+
+```ts
+const clock = createChapterClock(23, 0);
+const returnInput = advanceChapterClock(clock, 48 * 3_600_000);
+// returnInput.slots.length === 24; returnInput.skipped === 24
+// Pin clock, returned draws and the admitted initial host state in the replay.
+```
+
+The host owns elapsed-time pacing, narrative interpretation, storage, consent and persona admission. A slot is an opportunity for coarse fiction. It is not proof of a lived day, settled duty, completed project or recovered body. Existing actor state and engine2.17.0 continuation remain unchanged unless the host explicitly uses the helper.

package/dist/chapter-clock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Scope: pure, bounded host chapter scheduling from a supplied real-time clock. A slot is a coarse
+ * narrative opportunity, not a lived day. This helper touches no Person, resolves no obligations,
+ * and performs no body recovery. Hosts own fiction, persistence, admission and consent.
+ */
+export declare const CHAPTER_CLOCK: {
+    readonly version: 'hf-chapter-clock/1';
+    readonly quantumMs: 3600000;
+    readonly maxSlots: 24;
+};
+export interface ChapterClock {
+    version: 'hf-chapter-clock/1';
+    watermark: number;
+    seed: number;
+}
+export interface ChapterAdvance {
+    clock: ChapterClock;
+    slots: {
+        at: number;
+        draw: number;
+    }[];
+    skipped: number;
+}
+export declare function createChapterClock(seed: number, nowMs: number): ChapterClock;
+/** Stateless seeded draw per absolute slot: splitting returns does not alter a retained slot's result. */
+export declare function advanceChapterClock(clock: ChapterClock, nowMs: number): ChapterAdvance;

package/dist/chapter-clock.js

@@ -0,0 +1,36 @@
+/**
+ * Scope: pure, bounded host chapter scheduling from a supplied real-time clock. A slot is a coarse
+ * narrative opportunity, not a lived day. This helper touches no Person, resolves no obligations,
+ * and performs no body recovery. Hosts own fiction, persistence, admission and consent.
+ */
+export const CHAPTER_CLOCK = { version: 'hf-chapter-clock/1', quantumMs: 3_600_000, maxSlots: 24 };
+function slot(nowMs) {
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0)
+        throw new Error('Invalid chapter clock.');
+    return Math.floor(nowMs / CHAPTER_CLOCK.quantumMs);
+}
+export function createChapterClock(seed, nowMs) {
+    if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)
+        throw new Error('Invalid chapter seed.');
+    return { version: CHAPTER_CLOCK.version, watermark: slot(nowMs), seed };
+}
+/** Stateless seeded draw per absolute slot: splitting returns does not alter a retained slot's result. */
+export function advanceChapterClock(clock, nowMs) {
+    if (clock.version !== CHAPTER_CLOCK.version ||
+        !Number.isSafeInteger(clock.watermark) ||
+        clock.watermark < 0 ||
+        !Number.isInteger(clock.seed) ||
+        clock.seed < 0 ||
+        clock.seed > 0xffffffff)
+        throw new Error('Unsupported chapter clock.');
+    const end = Math.max(clock.watermark, slot(nowMs));
+    const count = Math.min(CHAPTER_CLOCK.maxSlots, end - clock.watermark);
+    const slots = Array.from({ length: count }, (_, i) => {
+        const at = end - count + i + 1;
+        let h = (clock.seed ^ (at >>> 0) ^ Math.floor(at / 0x100000000)) >>> 0;
+        h = Math.imul(h ^ (h >>> 16), 0x21f0aaad) >>> 0;
+        h = Math.imul(h ^ (h >>> 15), 0x735a2d97) >>> 0;
+        return { at, draw: ((h ^ (h >>> 15)) >>> 0) / 0x100000000 };
+    });
+    return { clock: { ...clock, watermark: end }, slots, skipped: end - clock.watermark - count };
+}

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 /** Human Framework public surface. */
-export declare const FRAMEWORK_VERSION = "2.17.0";
+export declare const FRAMEWORK_VERSION = "2.18.0";
 export type { CrisisEvent, PracticeKind } from './affect/index.ts';
 export { AFFECT_DEFAULTS, actionTendencies, advanceAffect, appraise, breakAllows, breakBehaviour, breakHazard, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, enableBreaks, feel, inBreak, readAffect, regulate, release as releaseEmotion, skipCrisis, strain, tendencyEmotions, } from './affect/index.ts';
 export type { GoalTemplate, MakeUpReceipt, PrayerCalendar, PrayerSchedule, PrayerTimes, Retimer, } from './agenda/index.ts';
 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 './chapter-clock.ts';
 export * from './character/index.ts';
 export * from './chronicle/index.ts';
 export type { ConsiderContext, DecideContext, Decision, SocialContext } from './cognition/index.ts';

package/dist/index.js

@@ -1,10 +1,11 @@
 /** Human Framework public surface. */
-export const FRAMEWORK_VERSION = '2.17.0';
+export const FRAMEWORK_VERSION = '2.18.0';
 export { AFFECT_DEFAULTS, actionTendencies, advanceAffect, appraise, breakAllows, breakBehaviour, breakHazard, CRISIS_DEFAULTS, checkCrisis, createAffect, easeBreak, emotionLevel, enableBreaks, feel, inBreak, readAffect, regulate, release as releaseEmotion, skipCrisis, strain, tendencyEmotions, } from './affect/index.js';
 // `agenda.release` collides with `affect.release`; the agenda one is re-exported under a clearer name.
 export { AGENDA_DEFAULTS, abandonGoal, adoptGoal, advanceAgenda, agendaTerms, applyExemptions, CARE_DEFAULTS, calendarRetimer, careDuty, commitmentPressure, createAgenda, DEFAULT_PRAYER_TIMES, EID_PRAYER_IMPORTANCE, EXEMPTION_DEFAULTS, eidPrayer, eidWindow, fastWindow, iftarWindow, inMakruhTime, isContinuingCommitment, isUnderWay, MAKRUH_DEFAULTS, makruhWindows, missedExcuse, onFinished, owedMakeUps, PRAYER_IMPORTANCE, PURPOSE_DEFAULTS, prayerWindows, pressureReachedAt, promise, proposeGoals, RAMADAN_DEFAULTS, ramadanFast, ramadanMeals, release as releaseCommitment, retimeCommitments, retirePaidMakeUps, revisePurposes, scheduleMakeUp, spanMeetsWindow, suhoorWindow, timesFor, violatesAbstention, } from './agenda/index.js';
 export * from './beliefs/index.js';
 export * from './body/index.js';
+export * from './chapter-clock.js';
 export * from './character/index.js';
 export * from './chronicle/index.js';
 // `cognition.decide` is the raw scorer; the composite's `decide` (person.ts) is the one hosts call.

package/package.json

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