holonovel 2026.9.10 → 2026.9.27

package/README.md

@@ -0,0 +1,95 @@
+# holonovel
+
+**The Holodeck for your rulebooks — rules enforced, worlds remembered.**
+
+A world-model MCP server for tabletop RPG play: rooms, things, exits, a
+parser command layer, and narrative tools, with out-of-the-box mechanics from
+Fate, Ironsworn, and Blades in the Dark (Fudge dice, momentum, and stress
+tracks — no ruleset required). Install it, then drop in any number of ruleset
+packages; each loads alongside the base and never modifies it.
+
+## Requirements
+
+- Node.js 20+
+
+## Install
+
+```sh
+npm install
+npm run start
+```
+
+Or run the published package:
+
+```sh
+npx -y holonovel
+```
+
+## MCP client configuration
+
+```json
+"holonovel": {
+  "type": "local",
+  "command": ["npx", "tsx", "src/index.ts"],
+  "cwd": "<path>/holonovel",
+  "environment": {
+    "TTRPG_NOVEL": "default"
+  },
+  "enabled": true
+}
+```
+
+## Tool surface
+
+The host exposes 34 action-discriminator tools — one per persisted entity
+type — plus a parser command tool and three base-mechanics resolvers. Every
+tool carries all four MCP mutation-class hints and a three-clause description
+(see `AGENTS.md` for the full surface and the tool-definition authoring
+standard).
+
+Categories:
+
+- **Badges & Workflow** — badge switching, workflow response, undo/redo
+- **Characters & Cast** — player characters, NPCs, identity, beliefs
+- **World & Scene** — world model, scene framing, perception, causal state
+- **Narrative** — story journal, lore, notes, vows, factions, countdowns
+- **Session** — recap, health, discovery, event log, audit
+- **Mechanics** — Fate, Ironsworn, and Forged in the Dark resolvers
+- **Content** — adventures, codex, ruleset packages, synthesis
+
+## Configuration
+
+Behavioral switches read from the environment; every switch is inert by
+default. Common values:
+
+| Variable | Purpose |
+|---|---|
+| `TTRPG_DATA_DIR` | State directory (default: `.holonovel-state`) |
+| `TTRPG_NOVEL` | Novel to activate at startup |
+| `TTRPG_SEED` | Deterministic PRNG seed |
+| `TTRPG_RULESETS` | Ruleset slugs to load eagerly |
+| `TTRPG_RULESET_DIRS` | Ruleset install directories |
+| `TTRPG_NPC_AUTONOMY`, `TTRPG_NPC_MIND` | NPC autonomy behaviors |
+| `TTRPG_WORLD_REACTIVITY` | World-in-Motion reactivity (default on) |
+| `TTRPG_NARRATION_VALIDATION` | Narration grounding validation |
+| `TTRPG_GUIDANCE_PROFILE` | `full` or `lean` guidance |
+
+## State
+
+A Novel is a structured save file under `.holonovel-state/novels/<slug>.json`
+with atomic saves, per-badge undo/redo snapshots, and an append-only audit
+log. Campaign data and installed packages live under `.holonovel-state/`,
+outside the server tree, so updating holonovel never touches them.
+
+## Development
+
+```sh
+npm run typecheck          # TypeScript type checking
+npm run test:all           # verification harnesses
+```
+
+Tests are `tsx` harnesses under `scripts/` (there is no `test/` directory).
+
+## License
+
+MIT. See `LICENSE.md`.

package/dist/core/agent.d.ts

@@ -0,0 +1,25 @@
+export type AgentTaskStatus = "queued" | "active" | "done" | "failed" | "cancelled";
+export type AgentAutonomy = "advisory" | "prompt" | "auto";
+export interface AgentAction {
+    seq: number;
+    description: string;
+    at: string;
+}
+export interface AgentTask {
+    id: string;
+    subject: string;
+    goal: string;
+    status: AgentTaskStatus;
+    autonomy: AgentAutonomy;
+    actions: AgentAction[];
+    source_goal?: string;
+    created_at: string;
+    updated_at: string;
+}
+export declare const AUTONOMY_LEVELS: AgentAutonomy[];
+export declare function isTerminal(status: AgentTaskStatus): boolean;
+export declare function canTransition(from: AgentTaskStatus, to: AgentTaskStatus): boolean;
+export declare function transition(task: AgentTask, to: AgentTaskStatus, at: string): boolean;
+export declare function recordAction(task: AgentTask, description: string, at: string): AgentAction;
+export declare function nextTaskId(tasks: AgentTask[]): string;
+export declare function isMutable(task: AgentTask): boolean;

package/dist/core/agent.js

@@ -0,0 +1,48 @@
+// Durable Agent Tasks — a persistent task and action lifecycle for NPCs and
+// entities, with an autonomy policy. Tasks are durable Novel state; only
+// admitted lifecycle transitions are permitted.
+// REQ-522, REQ-523, REQ-524, REQ-525, REQ-526, REQ-527, REQ-528, REQ-529, REQ-530
+export const AUTONOMY_LEVELS = ["advisory", "prompt", "auto"];
+// REQ-524 — only these lifecycle transitions are permitted.
+const TRANSITIONS = {
+    queued: ["active", "cancelled"],
+    active: ["done", "failed", "cancelled"],
+    done: [],
+    failed: [],
+    cancelled: [],
+};
+export function isTerminal(status) {
+    return TRANSITIONS[status].length === 0;
+}
+export function canTransition(from, to) {
+    return TRANSITIONS[from].includes(to);
+}
+// REQ-522/REQ-523/REQ-524 — apply a lifecycle transition; returns false if illegal.
+export function transition(task, to, at) {
+    if (!canTransition(task.status, to))
+        return false;
+    task.status = to;
+    task.updated_at = at;
+    return true;
+}
+// REQ-525 — append an action to the task's log.
+export function recordAction(task, description, at) {
+    const action = { seq: task.actions.length + 1, description, at };
+    task.actions.push(action);
+    task.updated_at = at;
+    return action;
+}
+export function nextTaskId(tasks) {
+    let max = 0;
+    for (const t of tasks) {
+        const m = t.id.match(/^task-(\d+)$/);
+        if (m)
+            max = Math.max(max, parseInt(m[1], 10));
+    }
+    return `task-${max + 1}`;
+}
+// REQ-528 — a terminal task is immutable; only actions may still be appended.
+export function isMutable(task) {
+    return !isTerminal(task.status);
+}
+//# sourceMappingURL=agent.js.map

package/dist/core/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yEAAyE;AACzE,gDAAgD;AAChD,kFAAkF;AAuBlF,MAAM,CAAC,MAAM,eAAe,GAAoB,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAE/E,4DAA4D;AAC5D,MAAM,WAAW,GAA+C;IAC9D,MAAM,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC;IACvC,IAAI,EAAE,EAAE;IACR,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE;CACd,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,MAAuB;IAChD,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAqB,EAAE,EAAmB;IACtE,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,UAAU,CAAC,IAAe,EAAE,EAAmB,EAAE,EAAU;IACzE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IACjB,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;IACrB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,YAAY,CAAC,IAAe,EAAE,WAAmB,EAAE,EAAU;IAC3E,MAAM,MAAM,GAAgB,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC9E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;IACrB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAkB;IAC3C,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACrC,IAAI,CAAC;YAAE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,QAAQ,GAAG,GAAG,CAAC,EAAE,CAAC;AAC3B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,SAAS,CAAC,IAAe;IACvC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC"}

package/dist/core/belief.d.ts

@@ -0,0 +1,39 @@
+export type EvidenceStatus = "active" | "unresolved" | "suppressed";
+export type Polarity = "positive" | "negative";
+export type BeliefStance = "positive" | "negative" | "unresolved";
+export interface EvidenceRecord {
+    id: string;
+    entity_id: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    polarity: Polarity;
+    status: EvidenceStatus;
+    weight: number;
+    source: string;
+    source_ordinals: number[];
+    at: string;
+}
+export interface BeliefRecord {
+    entity_id: string;
+    question: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    stance: BeliefStance;
+    support: number;
+    opposition: number;
+    accepted: boolean;
+    family: "durable" | "volatile" | "single_value";
+    current: boolean;
+    evidence_ids: string[];
+    at: string;
+}
+export declare function normalizeToken(value: string): string;
+export declare function questionKey(subject: string, predicate: string, object: string): string;
+export declare function beliefFamily(predicate: string): BeliefRecord["family"];
+export interface ReconcileOptions {
+    acceptThreshold: number;
+    decisionMargin: number;
+}
+export declare function reconcileEntity(entityId: string, evidence: EvidenceRecord[], opts: ReconcileOptions, at: string): BeliefRecord[];

package/dist/core/belief.js

@@ -0,0 +1,113 @@
+// Belief & Evidence — deterministic per-entity reconciliation of admitted
+// evidence into belief stances, preserving all evidence and disagreement.
+// REQ-461, REQ-462, REQ-463, REQ-464, REQ-465, REQ-466, REQ-467, REQ-468,
+// REQ-469, REQ-470, REQ-471, REQ-472
+// REQ-469 — predicate family policy. Deterministic default mapping; a ruleset
+// or builder may extend it, but the mapping used is always reported.
+const VOLATILE_PREDICATES = new Set(["status", "mood", "location", "condition", "activity"]);
+const SINGLE_VALUE_PREDICATES = new Set(["location", "wearing", "holding", "carrying"]);
+export function normalizeToken(value) {
+    return value.trim().toLowerCase();
+}
+// REQ-463 — polarity-independent question identity.
+export function questionKey(subject, predicate, object) {
+    return `${normalizeToken(subject)}|${normalizeToken(predicate)}|${normalizeToken(object)}`;
+}
+export function beliefFamily(predicate) {
+    const p = normalizeToken(predicate);
+    if (SINGLE_VALUE_PREDICATES.has(p))
+        return "single_value";
+    if (VOLATILE_PREDICATES.has(p))
+        return "volatile";
+    return "durable";
+}
+// REQ-466 — noisy-OR over independent sources; evidence sharing a source key is
+// correlated and does not compound.
+function sideSupport(records) {
+    const bySource = new Map();
+    for (const r of records) {
+        const key = r.source || "unknown";
+        bySource.set(key, Math.max(bySource.get(key) ?? 0, r.weight));
+    }
+    let product = 1;
+    for (const w of bySource.values())
+        product *= 1 - w;
+    return 1 - product;
+}
+function activeFor(records) {
+    return records.filter((r) => r.status === "active");
+}
+// REQ-468/REQ-465/REQ-469/REQ-470 — recompute every question for one entity.
+export function reconcileEntity(entityId, evidence, opts, at) {
+    const mine = activeFor(evidence).filter((e) => e.entity_id === entityId);
+    const questions = new Map();
+    for (const e of mine) {
+        const key = questionKey(e.subject, e.predicate, e.object);
+        const list = questions.get(key) ?? [];
+        list.push(e);
+        questions.set(key, list);
+    }
+    const records = [];
+    for (const [key, list] of questions) {
+        const first = list[0];
+        const family = beliefFamily(first.predicate);
+        const positive = list.filter((e) => e.polarity === "positive");
+        const negative = list.filter((e) => e.polarity === "negative");
+        let support;
+        let opposition;
+        let stance;
+        if (family === "volatile") {
+            // REQ-469 — most recent acquisition wins; ties go to the later id.
+            const latest = [...list].sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : a.id.localeCompare(b.id))).pop();
+            support = latest.polarity === "positive" ? latest.weight : 0;
+            opposition = latest.polarity === "negative" ? latest.weight : 0;
+            stance = latest.weight >= opts.acceptThreshold ? latest.polarity : "unresolved";
+        }
+        else {
+            support = sideSupport(positive);
+            opposition = sideSupport(negative);
+            if (support >= opts.acceptThreshold && support - opposition >= opts.decisionMargin)
+                stance = "positive";
+            else if (opposition >= opts.acceptThreshold && opposition - support >= opts.decisionMargin)
+                stance = "negative";
+            else
+                stance = "unresolved";
+        }
+        records.push({
+            entity_id: entityId,
+            question: key,
+            subject: first.subject,
+            predicate: first.predicate,
+            object: first.object,
+            stance,
+            support: Number(support.toFixed(4)),
+            opposition: Number(opposition.toFixed(4)),
+            accepted: stance !== "unresolved",
+            family,
+            current: family !== "single_value",
+            evidence_ids: list.map((e) => e.id),
+            at,
+        });
+    }
+    // REQ-470 — single-value predicates: only the highest-support object for a
+    // subject+predicate is current; a tie-contested slot yields no current value.
+    const slots = new Map();
+    for (const r of records) {
+        if (r.family !== "single_value")
+            continue;
+        const slot = `${normalizeToken(r.subject)}|${normalizeToken(r.predicate)}`;
+        const group = slots.get(slot) ?? [];
+        group.push(r);
+        slots.set(slot, group);
+    }
+    for (const group of slots.values()) {
+        const accepted = group.filter((r) => r.accepted);
+        const ranked = [...accepted].sort((a, b) => b.support - a.support);
+        const top = ranked[0];
+        const tie = top && ranked.filter((r) => Math.abs(r.support - top.support) < opts.decisionMargin).length > 1;
+        for (const r of group)
+            r.current = !!top && !tie && r === top;
+    }
+    return records.sort((a, b) => a.question.localeCompare(b.question));
+}
+//# sourceMappingURL=belief.js.map

package/dist/core/belief.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"belief.js","sourceRoot":"","sources":["../../src/core/belief.ts"],"names":[],"mappings":"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"}

package/dist/core/causal.d.ts

@@ -0,0 +1,49 @@
+export type AdmissionDecision = "admitted" | "admitted_with_latent_transition" | "rejected_impossible" | "conflict" | "underdetermined" | "fork_required" | "epistemic_only";
+export type CausalDomain = "location" | "scalar";
+export type OriginSource = "narrative" | "machine" | "ruleset";
+export type CausalValue = string | number | boolean | null;
+export interface TransitionProposal {
+    id: string;
+    scope: string;
+    domain: CausalDomain;
+    entity: string;
+    key: string;
+    value: CausalValue;
+    from?: CausalValue;
+    expected_version?: number;
+    origin_source: OriginSource;
+    source_ordinal: number | null;
+    at: string;
+}
+export interface TransitionRecord extends TransitionProposal {
+    decision: AdmissionDecision;
+    reason: string;
+}
+export interface CausalSlot {
+    scope: string;
+    domain: CausalDomain;
+    entity: string;
+    key: string;
+    value: CausalValue;
+    version: number;
+    at: string;
+}
+export interface CausalOptions {
+    scope: string;
+    latentTransitions: boolean;
+}
+export declare function slotKey(s: {
+    scope: string;
+    domain: CausalDomain;
+    entity: string;
+    key: string;
+}): string;
+export declare function findSlot(slots: CausalSlot[], p: TransitionProposal): CausalSlot | undefined;
+export declare function evaluate(p: TransitionProposal, slots: CausalSlot[], opts: CausalOptions): {
+    decision: AdmissionDecision;
+    reason: string;
+};
+export declare function applySlot(slots: CausalSlot[], p: TransitionProposal, at: string): boolean;
+export declare function nextProposalId(ledger: TransitionRecord[]): string;
+export declare function isProvisional(decision: AdmissionDecision): boolean;
+export declare const CAUSAL_DOMAINS: CausalDomain[];

package/dist/core/causal.js

@@ -0,0 +1,79 @@
+// Causal Transition Validation — decides whether a proposed objective-state
+// transition can coexist with the committed history of one scope, preserving
+// every proposal (admitted or not) as auditable evidence.
+// REQ-484, REQ-485, REQ-486, REQ-487, REQ-488, REQ-489, REQ-490, REQ-491,
+// REQ-492, REQ-493, REQ-494, REQ-495
+export function slotKey(s) {
+    return `${s.scope}|${s.domain}|${s.entity}|${s.key}`;
+}
+export function findSlot(slots, p) {
+    const k = slotKey(p);
+    return slots.find((s) => slotKey(s) === k);
+}
+// REQ-485 — the admission decision; REQ-486–REQ-490 set the outcome.
+export function evaluate(p, slots, opts) {
+    // REQ-488 — a proposal must co-reside on the active scope coordinate.
+    if (!p.scope)
+        return { decision: "rejected_impossible", reason: "missing scope coordinate" };
+    if (p.scope !== opts.scope) {
+        return { decision: "rejected_impossible", reason: `scope coordinate mismatch: '${p.scope}' is not the active scope '${opts.scope}'` };
+    }
+    const slot = findSlot(slots, p);
+    if (!slot)
+        return { decision: "admitted", reason: "first write at this coordinate" };
+    // REQ-489 — optimistic version guard.
+    if (p.expected_version !== undefined && p.expected_version !== slot.version) {
+        return { decision: "conflict", reason: `stale expected version ${p.expected_version} (current ${slot.version})` };
+    }
+    // REQ-489 — idempotent when the value is unchanged.
+    if (slot.value === p.value)
+        return { decision: "admitted", reason: "idempotent — value unchanged" };
+    // REQ-486 — an incompatible prior value is a conflict unless a latent transition is allowed.
+    if (p.from !== undefined && p.from !== slot.value) {
+        return opts.latentTransitions
+            ? { decision: "admitted_with_latent_transition", reason: "incompatible prior value; latent transition admitted" }
+            : { decision: "conflict", reason: "incompatible prior value" };
+    }
+    // REQ-487 — ordered scalar state admits a later value, refuses an incompatible one.
+    if (p.domain === "scalar" && typeof slot.value === "number" && typeof p.value === "number") {
+        return p.value >= slot.value
+            ? { decision: "admitted", reason: "ordered scalar advance" }
+            : { decision: "conflict", reason: "concurrent incompatible scalar value" };
+    }
+    // A continuous transition (from matches) is admitted; an unconstrained write is not.
+    if (p.from !== undefined && p.from === slot.value) {
+        return { decision: "admitted", reason: "continuous transition from prior value" };
+    }
+    return opts.latentTransitions
+        ? { decision: "admitted_with_latent_transition", reason: "unconstrained incompatible write; latent transition admitted" }
+        : { decision: "conflict", reason: "unconstrained incompatible write" };
+}
+// REQ-489 — apply an admitted value; returns false (no version bump) when idempotent.
+export function applySlot(slots, p, at) {
+    const idx = slots.findIndex((s) => slotKey(s) === slotKey(p));
+    if (idx === -1) {
+        slots.push({ scope: p.scope, domain: p.domain, entity: p.entity, key: p.key, value: p.value, version: 1, at });
+        return true;
+    }
+    if (slots[idx].value === p.value)
+        return false;
+    slots[idx] = { ...slots[idx], value: p.value, version: slots[idx].version + 1, at };
+    return true;
+}
+export function nextProposalId(ledger) {
+    let max = 0;
+    for (const r of ledger) {
+        const m = r.id.match(/^tp-(\d+)$/);
+        if (m)
+            max = Math.max(max, parseInt(m[1], 10));
+    }
+    return `tp-${max + 1}`;
+}
+// REQ-490 — a latent transition is provisional: it is applied but flagged.
+export function isProvisional(decision) {
+    return decision === "admitted_with_latent_transition";
+}
+// REQ-492 — the causal layer never writes epistemic or identity state. This
+// module has no access to those stores; the firewall is structural.
+export const CAUSAL_DOMAINS = ["location", "scalar"];
+//# sourceMappingURL=causal.js.map

package/dist/core/causal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"causal.js","sourceRoot":"","sources":["../../src/core/causal.ts"],"names":[],"mappings":"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"}

package/dist/core/corpus.d.ts

@@ -0,0 +1,33 @@
+export type ConsumptionMode = "read" | "research" | "taught" | "import";
+export interface CorpusDocument {
+    id: string;
+    title: string;
+    domain: string;
+    body: string;
+    source_profile: string;
+    access_public: boolean;
+    access_domains: string[];
+    access_grants: string[];
+    access_denies: string[];
+    registered_at: string;
+}
+export interface CorpusAccess {
+    entity_id: string;
+    domains: string[];
+}
+export interface CorpusConsumption {
+    id: string;
+    entity_id: string;
+    document_id: string;
+    domain: string;
+    mode: ConsumptionMode;
+    deixis: "unresolved" | "resolved";
+    excerpt: string;
+    at: string;
+}
+export declare const CONSUMPTION_MODES: ConsumptionMode[];
+export declare function deixisOf(body: string): "unresolved" | "resolved";
+export declare function canAccess(doc: CorpusDocument, entityId: string, access: CorpusAccess[]): boolean;
+export declare function nextDocumentId(docs: CorpusDocument[]): string;
+export declare function nextConsumptionId(records: CorpusConsumption[]): string;
+export declare function excerptOf(body: string, limit?: number): string;

package/dist/core/corpus.js

@@ -0,0 +1,43 @@
+// Knowledge Corpus — cold reference material that stays quarantined until an
+// entity explicitly consumes it, then records exactly what was acquired.
+// REQ-496, REQ-497, REQ-498, REQ-499, REQ-500, REQ-501, REQ-502, REQ-503
+export const CONSUMPTION_MODES = ["read", "research", "taught", "import"];
+const DEIXIS_RE = /\b(i|you|my|your|me|we|our)\b/i;
+// REQ-502 — first/second-person reference material cannot silently become
+// self-knowledge: consumption records the deixis as unresolved.
+export function deixisOf(body) {
+    return DEIXIS_RE.test(body) ? "unresolved" : "resolved";
+}
+// REQ-498 — public, OR domain match, OR explicit grant, minus explicit deny.
+export function canAccess(doc, entityId, access) {
+    if (doc.access_denies.includes(entityId))
+        return false;
+    if (doc.access_public)
+        return true;
+    if (doc.access_grants.includes(entityId))
+        return true;
+    const profile = access.find((a) => a.entity_id === entityId);
+    return !!profile && profile.domains.includes(doc.domain);
+}
+export function nextDocumentId(docs) {
+    let max = 0;
+    for (const d of docs) {
+        const m = d.id.match(/^doc-(\d+)$/);
+        if (m)
+            max = Math.max(max, parseInt(m[1], 10));
+    }
+    return `doc-${max + 1}`;
+}
+export function nextConsumptionId(records) {
+    let max = 0;
+    for (const r of records) {
+        const m = r.id.match(/^cc-(\d+)$/);
+        if (m)
+            max = Math.max(max, parseInt(m[1], 10));
+    }
+    return `cc-${max + 1}`;
+}
+export function excerptOf(body, limit = 200) {
+    return body.length > limit ? body.slice(0, limit) : body;
+}
+//# sourceMappingURL=corpus.js.map

package/dist/core/corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.js","sourceRoot":"","sources":["../../src/core/corpus.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,yEAAyE;AACzE,yEAAyE;AAuCzE,MAAM,CAAC,MAAM,iBAAiB,GAAsB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAE7F,MAAM,SAAS,GAAG,gCAAgC,CAAC;AAEnD,0EAA0E;AAC1E,gEAAgE;AAChE,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC;AAC1D,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,SAAS,CAAC,GAAmB,EAAE,QAAgB,EAAE,MAAsB;IACrF,IAAI,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACvD,IAAI,GAAG,CAAC,aAAa;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC;IAC7D,OAAO,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAsB;IACnD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QACpC,IAAI,CAAC;YAAE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,OAAO,GAAG,GAAG,CAAC,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAA4B;IAC5D,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACnC,IAAI,CAAC;YAAE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAK,GAAG,GAAG;IACjD,OAAO,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3D,CAAC"}

package/dist/core/event-log.d.ts

@@ -0,0 +1,23 @@
+export type EventSource = "player" | "game_master" | "system" | "machine";
+export interface EventLogEntry {
+    ordinal: number;
+    source: EventSource;
+    kind: string;
+    text: string;
+    at: string;
+    superseded?: boolean;
+    superseded_by?: number;
+    alternatives?: number[];
+}
+export interface BranchLineage {
+    parent_slug: string | null;
+    branch_point: number | null;
+}
+export declare function emptyBranchLineage(): BranchLineage;
+export declare function nextOrdinal(log: EventLogEntry[]): number;
+export declare function appendEvent(log: EventLogEntry[], source: EventSource, kind: string, text: string, at: string): EventLogEntry;
+export declare function supersedeEvent(log: EventLogEntry[], ordinal: number, source: EventSource, kind: string, text: string, at: string): EventLogEntry | null;
+export declare function sliceThrough(log: EventLogEntry[], ordinal: number | null): EventLogEntry[];
+export declare function describeEntry(e: EventLogEntry): string;
+export declare function entriesByOrdinals(log: EventLogEntry[], ordinals: number[]): EventLogEntry[];
+export declare function evictToCap(log: EventLogEntry[], cap: number): EventLogEntry[];

package/dist/core/event-log.js

@@ -0,0 +1,58 @@
+// Event Log — Novel-scoped append-only observational record with deterministic
+// ordering, provenance, supersession, and branch slicing.
+// REQ-455, REQ-456, REQ-457, REQ-458, REQ-459, REQ-460
+export function emptyBranchLineage() {
+    return { parent_slug: null, branch_point: null };
+}
+// REQ-455 — deterministic ordinal: monotonic within a Novel, independent of
+// wall-clock time, so replaying the same inputs reproduces the same ordinals.
+export function nextOrdinal(log) {
+    if (log.length === 0)
+        return 1;
+    return log[log.length - 1].ordinal + 1;
+}
+// REQ-455 — append. Returns the new entry. Callers persist the Novel after.
+export function appendEvent(log, source, kind, text, at) {
+    const entry = { ordinal: nextOrdinal(log), source, kind, text, at };
+    log.push(entry);
+    return entry;
+}
+// REQ-457 — append a replacement and mark the prior entry superseded. The prior
+// entry remains readable; the replacement is linked as an alternative.
+export function supersedeEvent(log, ordinal, source, kind, text, at) {
+    const prior = log.find((e) => e.ordinal === ordinal);
+    if (!prior)
+        return null;
+    const replacement = appendEvent(log, source, kind, text, at);
+    prior.superseded = true;
+    prior.superseded_by = replacement.ordinal;
+    if (!prior.alternatives)
+        prior.alternatives = [];
+    prior.alternatives.push(replacement.ordinal);
+    return replacement;
+}
+// REQ-458 — branch slice: entries up to and including the branch point.
+export function sliceThrough(log, ordinal) {
+    if (ordinal === null)
+        return log.map((e) => ({ ...e }));
+    return log.filter((e) => e.ordinal <= ordinal).map((e) => ({ ...e }));
+}
+// REQ-456 — non-semantic view: ordering, provenance, and supersession only.
+export function describeEntry(e) {
+    const tag = e.superseded ? " [superseded]" : "";
+    return `#${e.ordinal} (${e.source}/${e.kind})${tag} ${e.text}`;
+}
+// REQ-460 — contributing entries for a derived record, by ordinal.
+export function entriesByOrdinals(log, ordinals) {
+    const set = new Set(ordinals);
+    return log.filter((e) => set.has(e.ordinal));
+}
+// REQ-455 — configured cap: evict oldest entries when the cap is exceeded,
+// preserving the append-only contract for entries still retained.
+export function evictToCap(log, cap) {
+    if (cap > 0 && log.length > cap) {
+        return log.slice(log.length - cap);
+    }
+    return log;
+}
+//# sourceMappingURL=event-log.js.map

package/dist/core/event-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.js","sourceRoot":"","sources":["../../src/core/event-log.ts"],"names":[],"mappings":"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"}