holonovel 2026.9.3 → 2026.9.4

package/dist/core/state.d.ts

@@ -53,6 +53,11 @@ export interface NpcState {
         dialogue: string;
         tag?: string;
     }[];
+    mind?: {
+        private_journal?: string[];
+        directive?: string;
+        auto_play?: boolean;
+    };
     conditions: string[];
     condition_rounds: Record<string, number>;
     memory?: {
@@ -259,6 +264,43 @@ export interface ConditionState {
     conditions: string[];
     condition_rounds: Record<string, number>;
 }
+export interface FateState {
+    aspects: Array<{
+        name: string;
+        target: string;
+    }>;
+    fate_points: Record<string, number>;
+    stress: Record<string, {
+        physical: number;
+        mental: number;
+        consequences: string[];
+    }>;
+}
+export declare const FATE_REFRESH = 3;
+export declare function normalizeFateState(raw: unknown): FateState;
+export interface IronswornProgressTrack {
+    name: string;
+    rank: "troublesome" | "dangerous" | "formidable" | "extreme" | "epic";
+    ticks: number;
+}
+export interface IronswornState {
+    momentum: Record<string, number>;
+    progress_tracks: IronswornProgressTrack[];
+}
+export declare const IRONSWORN_MOMENTUM_DEFAULT = 2;
+export declare const IRONSWORN_MOMENTUM_MIN = -6;
+export declare const IRONSWORN_MOMENTUM_MAX = 10;
+export declare const IRONSWORN_TRACK_BOXES = 10;
+export declare function normalizeIronswornState(raw: unknown): IronswornState;
+export interface ForgedCharacterState {
+    stress: number;
+    trauma: string[];
+}
+export interface ForgedState {
+    characters: Record<string, ForgedCharacterState>;
+}
+export declare const FORGED_STRESS_MAX = 8;
+export declare function normalizeForgedState(raw: unknown): ForgedState;
 export interface WorkflowSnapshot {
     timestamp: string;
     state: any;
@@ -397,6 +439,7 @@ export interface NovelState {
         audit_gap: number;
         timestamp_gap_ms: number;
         recorded_at: string;
+        backup_index?: number;
     } | null;
     last_mutation_at: string | null;
     mutation_counts_by_group: Record<string, number>;
@@ -434,6 +477,9 @@ export interface NovelState {
         imported_at: string;
         codex_modified_at: string;
     }>;
+    fate: FateState;
+    ironsworn: IronswornState;
+    forged: ForgedState;
 }
 export interface RosterEntity extends NovelEntity {
 }
@@ -459,9 +505,10 @@ export declare class StateManager {
         narrative_tag?: string;
     }>;
     codex: Map<string, CodexEntry>;
-    readonly dataFormat = "91fab184d376185c4a6cbfefd33c25242daf9e21f9837bcb0011657630a01980";
+    readonly dataFormat = "daff3d95da3bc1b51cf1b521a9d6a973aa95cccd3b6b7f777f54e11e95484161";
     staleData: Map<string, string>;
     corruptData: Map<string, string>;
+    private restoredThisSession;
     private npcCounter;
     private entityCounter;
     private stateDir;
@@ -477,7 +524,9 @@ export declare class StateManager {
     createNovel(name: string, ruleset?: string | null): NovelState;
     bindNovelRuleset(slug: string): NovelState;
     private computeStateRegression;
+    private hasValidChecksum;
     resumeNovel(slug: string): NovelState;
+    activateHydratedNovel(slug: string): NovelState;
     hydrateNovelsFromDisk(): void;
     private loadNovelFromData;
     switchNovel(slug: string): NovelState;
@@ -537,6 +586,10 @@ export declare class StateManager {
     };
     combatReport(novel: NovelState): string;
     worldHasRooms(novel: NovelState): boolean;
+    private backupCount;
+    private backupCandidates;
+    private restoreFromBackups;
+    private backupFilesOnDisk;
     saveNovel(novel: NovelState): void;
     saveRoster(): void;
     loadRoster(): void;

package/dist/core/state.js

@@ -62,6 +62,33 @@ export function migrateNovelData(data) {
     }
     return out;
 }
+export const FATE_REFRESH = 3;
+export function normalizeFateState(raw) {
+    const r = (raw ?? {});
+    return {
+        aspects: Array.isArray(r.aspects) ? r.aspects : [],
+        fate_points: (r.fate_points && typeof r.fate_points === "object") ? r.fate_points : {},
+        stress: (r.stress && typeof r.stress === "object") ? r.stress : {},
+    };
+}
+export const IRONSWORN_MOMENTUM_DEFAULT = 2;
+export const IRONSWORN_MOMENTUM_MIN = -6;
+export const IRONSWORN_MOMENTUM_MAX = 10;
+export const IRONSWORN_TRACK_BOXES = 10;
+export function normalizeIronswornState(raw) {
+    const r = (raw ?? {});
+    return {
+        momentum: (r.momentum && typeof r.momentum === "object") ? r.momentum : {},
+        progress_tracks: Array.isArray(r.progress_tracks) ? r.progress_tracks : [],
+    };
+}
+export const FORGED_STRESS_MAX = 8;
+export function normalizeForgedState(raw) {
+    const r = (raw ?? {});
+    return {
+        characters: (r.characters && typeof r.characters === "object") ? r.characters : {},
+    };
+}
 export const DEFAULT_AUTONOMY = {
     level: "mechanical_prompt",
     confirmation: "prompt",
@@ -186,6 +213,11 @@ export class StateManager {
     // resume (unparseable JSON, checksum mismatch, or data-migration failure),
     // surfaced as a [WARNING] in spec_health.data_health.corrupted.
     corruptData = new Map();
+    // REQ-238 — slugs loaded from a backup this session. The first save after a
+    // backup restore skips copying the (corrupt/stale) on-disk primary into
+    // `.bak.1`, so a good backup is never overwritten and corruption is never
+    // propagated into the rotated chain.
+    restoredThisSession = new Set();
     npcCounter = 0;
     entityCounter = 0;
     stateDir;
@@ -345,6 +377,9 @@ export class StateManager {
             active_session_id: null,
             pending_vow_countdown_suggestion: null,
             codex_sources: [],
+            fate: { aspects: [], fate_points: {}, stress: {} },
+            ironsworn: { momentum: {}, progress_tracks: [] },
+            forged: { characters: {} },
         };
         this.novels.set(slug, novel);
         this.activeNovelId = slug;
@@ -377,32 +412,49 @@ export class StateManager {
             - new Date(bakData.metadata?.modified ?? new Date()).getTime();
         return { audit_gap: Math.max(0, auditGap), timestamp_gap_ms: Math.max(0, tsGap) };
     }
+    // REQ-092 — a payload's checksum is valid when absent (legacy writes) or when
+    // it matches the recomputed hash of the payload excluding the checksum field.
+    hasValidChecksum(data) {
+        if (!data._checksum)
+            return true;
+        const payload = { ...data };
+        delete payload._checksum;
+        const computed = crypto.createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+        return computed === data._checksum;
+    }
     resumeNovel(slug) {
         const filePath = path.join(this.stateDir, "novels", `${slug}.json`);
         if (!fs.existsSync(filePath))
             throw new Error(`[STATE_CONFLICT] Novel '${slug}' does not exist on disk.`);
-        const raw = fs.readFileSync(filePath, "utf-8");
-        const data = JSON.parse(raw);
-        if (data._checksum) {
-            const payload = { ...data };
-            delete payload._checksum;
-            const computed = crypto.createHash("sha256").update(JSON.stringify(payload)).digest("hex");
-            if (computed !== data._checksum) {
-                const bakPath = filePath + ".bak";
-                if (fs.existsSync(bakPath)) {
-                    const bakRaw = fs.readFileSync(bakPath, "utf-8");
-                    const bakData = JSON.parse(bakRaw);
-                    const loaded = this.loadNovelFromData(bakData);
-                    // REQ-406 — surface the backup-restore content regression.
-                    loaded.state_regression = { ...this.computeStateRegression(data, bakData), recorded_at: new Date().toISOString() };
-                    this.novels.set(slug, loaded);
-                    this.activeNovelId = slug;
-                    this.audit(loaded, loaded.badge, "resume_novel", { slug, restored_from_backup: true });
-                    return loaded;
-                }
-                this.corruptData.set(slug, "checksum mismatch, no valid backup");
-                throw new Error(`[STATE_CONFLICT] Novel '${slug}' is corrupted (checksum mismatch).`);
+        let data;
+        let primaryData = null;
+        try {
+            data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+            primaryData = data;
+        }
+        catch {
+            data = null; // structurally corrupt primary — fall through to backup restore
+        }
+        // REQ-238a — restore triggers on a structural JSON error or a checksum
+        // mismatch (REQ-092); the first valid backup wins and its index is audited.
+        if (data === null || !this.hasValidChecksum(data)) {
+            const restored = this.restoreFromBackups(filePath);
+            if (restored) {
+                const loaded = this.loadNovelFromData(restored.data);
+                // REQ-406 — surface the backup-restore content regression.
+                loaded.state_regression = {
+                    ...this.computeStateRegression(primaryData ?? restored.data, restored.data),
+                    backup_index: restored.index,
+                    recorded_at: new Date().toISOString(),
+                };
+                this.novels.set(slug, loaded);
+                this.activeNovelId = slug;
+                this.restoredThisSession.add(slug);
+                this.audit(loaded, loaded.badge, "resume_novel", { slug, restored_from_backup: restored.index });
+                return loaded;
             }
+            this.corruptData.set(slug, "corrupt primary, no valid backup");
+            throw new Error(`[STATE_CONFLICT] Novel '${slug}' is corrupted.`);
         }
         const novel = this.loadNovelFromData(data);
         this.novels.set(slug, novel);
@@ -411,6 +463,23 @@ export class StateManager {
         this.checkWorkflowStaleness(novel);
         return novel;
     }
+    // REQ-088 — activate an already-hydrated Novel by its internal slug (registry
+    // key). Used by the TTRPG_NOVEL startup auto-load so a save file whose name
+    // diverges from its internal slug is activated without a second file read.
+    // Audits the resume and, when hydration restored from a backup, emits the
+    // `[restored-from-backup]` entry naming the backup index (REQ-238/T276).
+    activateHydratedNovel(slug) {
+        const novel = this.novels.get(slug);
+        if (!novel)
+            throw new Error(`[STATE_CONFLICT] Novel '${slug}' is not hydrated.`);
+        this.activeNovelId = slug;
+        const restoredIndex = novel.state_regression?.backup_index ?? null;
+        this.audit(novel, novel.badge, "resume_novel", restoredIndex !== null
+            ? { slug, restored_from_backup: restoredIndex }
+            : { slug });
+        this.checkWorkflowStaleness(novel);
+        return novel;
+    }
     // REQ-065 — hydrate the in-memory Novel registry from the on-disk novels/
     // directory at startup so list_novels reflects disk without an explicit
     // resume. Loads each save file (falling back to its .bak on a checksum
@@ -440,41 +509,27 @@ export class StateManager {
             const fileSlug = file.slice(0, -".json".length);
             const filePath = path.join(dir, file);
             let data;
+            let primaryData = null;
             try {
                 data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+                primaryData = data;
             }
             catch {
-                this.corruptData.set(fileSlug, "unparseable JSON");
-                process.stderr.write(`[holonovel] hydration: skipped unparseable novel file '${file}'.\n`);
-                continue;
+                data = null; // structurally corrupt primary — fall through to backup restore
             }
-            let restoredFromBackup = false;
-            let bakData = null;
-            const primaryData = data;
-            if (data._checksum) {
-                const payload = { ...data };
-                delete payload._checksum;
-                const computed = crypto.createHash("sha256").update(JSON.stringify(payload)).digest("hex");
-                if (computed !== data._checksum) {
-                    const bakPath = filePath + ".bak";
-                    if (fs.existsSync(bakPath)) {
-                        try {
-                            bakData = JSON.parse(fs.readFileSync(bakPath, "utf-8"));
-                            data = bakData;
-                            restoredFromBackup = true;
-                        }
-                        catch {
-                            this.corruptData.set(fileSlug, "checksum mismatch, unparseable backup");
-                            process.stderr.write(`[holonovel] hydration: skipped corrupt novel '${file}' (unreadable .bak).\n`);
-                            continue;
-                        }
-                    }
-                    else {
-                        this.corruptData.set(fileSlug, "checksum mismatch, no backup");
-                        process.stderr.write(`[holonovel] hydration: skipped corrupt novel '${file}' (no .bak).\n`);
-                        continue;
-                    }
+            let restoredIndex = null;
+            // REQ-238a — a structural JSON error or checksum mismatch triggers the
+            // rotated-backup restore chain; no valid backup → the corrupt-novel path.
+            if (data === null || !this.hasValidChecksum(data)) {
+                const restored = this.restoreFromBackups(filePath);
+                if (!restored) {
+                    const reason = data === null ? "unparseable JSON, no valid backup" : "checksum mismatch, no valid backup";
+                    this.corruptData.set(fileSlug, reason);
+                    process.stderr.write(`[holonovel] hydration: skipped corrupt novel '${file}' (${reason}).\n`);
+                    continue;
                 }
+                data = restored.data;
+                restoredIndex = restored.index;
             }
             let novel;
             try {
@@ -485,8 +540,13 @@ export class StateManager {
                 process.stderr.write(`[holonovel] hydration: skipped novel '${file}' (${e.message}).\n`);
                 continue;
             }
-            if (restoredFromBackup && bakData) {
-                novel.state_regression = { ...this.computeStateRegression(primaryData, bakData), recorded_at: new Date().toISOString() };
+            if (restoredIndex !== null) {
+                novel.state_regression = {
+                    ...this.computeStateRegression(primaryData ?? data, data),
+                    backup_index: restoredIndex,
+                    recorded_at: new Date().toISOString(),
+                };
+                this.restoredThisSession.add(novel.slug);
             }
             const key = novel.slug || fileSlug;
             if (this.novels.has(key)) {
@@ -596,6 +656,9 @@ export class StateManager {
             active_session_id: data.active_session_id ?? null,
             pending_vow_countdown_suggestion: data.pending_vow_countdown_suggestion ?? null,
             codex_sources: data.codex_sources ?? [],
+            fate: normalizeFateState(data.fate),
+            ironsworn: normalizeIronswornState(data.ironsworn),
+            forged: normalizeForgedState(data.forged),
         };
         return novel;
     }
@@ -635,12 +698,14 @@ export class StateManager {
         const trashDir = path.join(this.stateDir, ".trash");
         fs.mkdirSync(trashDir, { recursive: true });
         const novelFile = path.join(this.stateDir, "novels", `${novel.slug}.json`);
-        const bakFile = novelFile + ".bak";
         if (fs.existsSync(novelFile)) {
             fs.renameSync(novelFile, path.join(trashDir, `${novel.slug}-${Date.now()}.json`));
         }
-        if (fs.existsSync(bakFile)) {
-            fs.renameSync(bakFile, path.join(trashDir, `${novel.slug}-${Date.now()}.json.bak`));
+        // REQ-238b — move the whole backup chain (`.bak.N` + legacy `.bak`) to trash
+        // alongside the primary so no orphaned backups survive an ended Novel.
+        for (const bakPath of this.backupFilesOnDisk(novelFile)) {
+            const suffix = bakPath.slice(novelFile.length);
+            fs.renameSync(bakPath, path.join(trashDir, `${novel.slug}-${Date.now()}.json${suffix}`));
         }
         const archiveDir = path.join(this.stateDir, "archive");
         if (fs.existsSync(archiveDir)) {
@@ -669,9 +734,14 @@ export class StateManager {
         if (fs.existsSync(target))
             fs.unlinkSync(target);
         fs.renameSync(novelFile, target);
-        const bak = novelFile + ".bak";
-        if (fs.existsSync(bak))
-            fs.renameSync(bak, target + ".bak");
+        // REQ-334 — move the backup chain alongside the archived primary.
+        for (const bakPath of this.backupFilesOnDisk(novelFile)) {
+            const suffix = bakPath.slice(novelFile.length);
+            const dest = target + suffix;
+            if (fs.existsSync(dest))
+                fs.unlinkSync(dest);
+            fs.renameSync(bakPath, dest);
+        }
         this.novels.delete(slug);
         if (this.activeNovelId === slug)
             this.activeNovelId = null;
@@ -687,9 +757,14 @@ export class StateManager {
         if (fs.existsSync(target))
             throw new Error(`[STATE_CONFLICT] Novel '${slug}' already exists as active.`);
         fs.renameSync(archiveFile, target);
-        const bak = archiveFile + ".bak";
-        if (fs.existsSync(bak))
-            fs.renameSync(bak, target + ".bak");
+        // REQ-334 — restore the backup chain alongside the unarchived primary.
+        for (const bakPath of this.backupFilesOnDisk(archiveFile)) {
+            const suffix = bakPath.slice(archiveFile.length);
+            const dest = target + suffix;
+            if (fs.existsSync(dest))
+                fs.unlinkSync(dest);
+            fs.renameSync(bakPath, dest);
+        }
         return this.resumeNovel(slug);
     }
     archivedNovels() {
@@ -1151,12 +1226,68 @@ ${turnOrder}`;
         return novel.world.rooms.size > 0;
     }
     // ── Persistence ───────────────────────────────────────────────
+    // REQ-238 — the number of rotated backups retained per Novel, configured via
+    // TTRPG_NOVEL_BACKUP_COUNT (minimum 1; unset defaults to 1 = current behavior).
+    backupCount() {
+        const raw = parseInt(process.env.TTRPG_NOVEL_BACKUP_COUNT ?? "1", 10);
+        return Number.isFinite(raw) && raw >= 1 ? raw : 1;
+    }
+    // REQ-238 — ordered restore candidates: `.bak.1..N` (newest first), then a
+    // legacy singular `.bak` (pre-rotation saves) accepted as the index-1 candidate.
+    backupCandidates(filePath) {
+        const candidates = [];
+        for (let i = 1; i <= this.backupCount(); i++)
+            candidates.push({ path: `${filePath}.bak.${i}`, index: i });
+        candidates.push({ path: `${filePath}.bak`, index: 1 });
+        return candidates;
+    }
+    // REQ-238/REQ-092 — restore from the first parseable backup with a valid
+    // checksum. Returns the winning data plus its backup index, or null when no
+    // candidate is usable (REQ-238b hands off to the existing recovery path).
+    restoreFromBackups(filePath) {
+        for (const cand of this.backupCandidates(filePath)) {
+            if (!fs.existsSync(cand.path))
+                continue;
+            try {
+                const raw = fs.readFileSync(cand.path, "utf-8");
+                const data = JSON.parse(raw);
+                if (!this.hasValidChecksum(data))
+                    continue;
+                return { data, index: cand.index };
+            }
+            catch {
+                continue; // structurally corrupt or unreadable candidate — try the next
+            }
+        }
+        return null;
+    }
+    // REQ-238 — enumerate every backup file on disk for a primary file path: the
+    // rotated `<file>.bak.N` chain plus the legacy singular `<file>.bak`.
+    backupFilesOnDisk(filePath) {
+        const dir = path.dirname(filePath);
+        const base = path.basename(filePath);
+        const legacy = `${base}.bak`;
+        const prefix = `${base}.bak.`;
+        const found = [];
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            return found;
+        }
+        for (const e of entries) {
+            if (e === legacy || e.startsWith(prefix))
+                found.push(path.join(dir, e));
+        }
+        return found.sort();
+    }
     saveNovel(novel) {
         const dir = path.join(this.stateDir, "novels");
         fs.mkdirSync(dir, { recursive: true });
         const filePath = path.join(dir, `${novel.slug}.json`);
         const tmpPath = filePath + `.${process.pid}-${Date.now()}.tmp`;
-        const bakPath = filePath + ".bak";
+        const count = this.backupCount();
         novel.metadata.modified = new Date().toISOString();
         // Defensive guard: the undo/redo stacks are internal bookkeeping. If they
         // have grown pathologically (e.g. a snapshot regression embedded prior
@@ -1181,8 +1312,30 @@ ${turnOrder}`;
         payload.spec_version = SPEC_VERSION;
         payload._checksum = crypto.createHash("sha256").update(JSON.stringify(payload)).digest("hex");
         const out = JSON.stringify(payload, null, 2);
-        if (fs.existsSync(filePath)) {
-            fs.copyFileSync(filePath, bakPath);
+        // REQ-238 — rotate the backup chain before committing the new primary:
+        // `.bak.N-1` → `.bak.N`, … `.bak.1` → `.bak.2`, then the previous primary
+        // becomes `.bak.1`. count=1 writes only `.bak.1` (the previous primary).
+        if (count > 1) {
+            for (let i = count - 1; i >= 1; i--) {
+                const from = `${filePath}.bak.${i}`;
+                const to = `${filePath}.bak.${i + 1}`;
+                if (fs.existsSync(from)) {
+                    if (fs.existsSync(to))
+                        fs.unlinkSync(to);
+                    fs.renameSync(from, to);
+                }
+            }
+        }
+        if (fs.existsSync(filePath) && !this.restoredThisSession.delete(novel.slug)) {
+            fs.copyFileSync(filePath, `${filePath}.bak.1`);
+        }
+        // Prune backups beyond the configured chain (e.g. TTRPG_NOVEL_BACKUP_COUNT
+        // lowered between runs); breaks immediately when no stale index remains.
+        for (let i = count + 1;; i++) {
+            const stale = `${filePath}.bak.${i}`;
+            if (!fs.existsSync(stale))
+                break;
+            fs.unlinkSync(stale);
         }
         const fd = fs.openSync(tmpPath, "w");
         fs.writeFileSync(fd, out, "utf-8");
@@ -1399,6 +1552,9 @@ function novelToJSON(novel) {
         mutation_counts_by_group: novel.mutation_counts_by_group,
         uncommitted_rolls: novel.uncommitted_rolls,
         metadata: novel.metadata,
+        fate: novel.fate,
+        ironsworn: novel.ironsworn,
+        forged: novel.forged,
     };
 }
 // Snapshot-clone serialization: identical to novelToJSON but omits the
@@ -1505,6 +1661,9 @@ function novelFromJSON(data) {
         active_session_id: data.active_session_id ?? null,
         pending_vow_countdown_suggestion: data.pending_vow_countdown_suggestion ?? null,
         codex_sources: data.codex_sources ?? [],
+        fate: normalizeFateState(data.fate),
+        ironsworn: normalizeIronswornState(data.ironsworn),
+        forged: normalizeForgedState(data.forged),
     };
 }
 // Serialize a Novel to its full interchange form (REQ-096). Returns the flat
@@ -1587,5 +1746,8 @@ export function applyNovelState(target, source) {
     target.mutation_counts_by_group = source.mutation_counts_by_group;
     target.uncommitted_rolls = source.uncommitted_rolls;
     target.metadata = source.metadata;
+    target.fate = source.fate;
+    target.ironsworn = source.ironsworn;
+    target.forged = source.forged;
 }
 //# sourceMappingURL=state.js.map