lore-engine/docs/20-multi-setting-policy.md

20 — Multi-setting policy

Status: 📋 planned. Operationalizes the v1.2 Setting/Plane model from docs/17-planes.md.

Goal

A single Lore Engine instance can host multiple Settings (campaigns, worlds, parallel timelines). Queries can be scoped to a single setting, span multiple settings, or ask "how does setting A differ from setting B?" This doc pins down the operational contract.

The settings.yaml manifest

Every codex root has a settings.yaml:

default_setting: mardonari
settings:
  - id: mardonari
    name: Mardonari
    kind: multi-plane
    current_era: 3rd_age
    schema_version: 1.2
  - id: the_wild_dream
    name: The Wild Dream
    kind: single-plane
    current_era: dream_age
    schema_version: 1.2
    notes: "Mirror campaign; Aldric Raventhorne exists here too."

This file is read at ingest time. The default_setting is the implicit setting for any entity without an explicit setting_id in its frontmatter.

Cross-setting references

Two patterns:

1. The same entity in two settings. Aldric Raventhorne exists in both Mardonari and The Wild Dream. This is two distinct graph nodes with the same name, linked by an :ANALOG_OF edge. The LLM is told, on a query, which setting to scope to; if the user is ambiguous, the default_setting wins.

2. An entity in setting A references an entity in setting B. E.g., "the Mardonari chronicles mention a being from The Wild Dream." This is a :REFERENCES_SETTING edge from the Mardonari entity to the Setting node for The Wild Dream. Traversal is allowed; the LLM gets a flag saying "this answer crossed a setting boundary."

Tool behavior

• lookup(query, setting=None) — setting defaults to default_setting. Returns candidates from the scoped setting first, then other settings.
• was_true_at(...) — same scoping. Cross-setting time comparisons require an explicit setting_a= and setting_b=.
• state_at(...) — same.
• entities_present(at_time, setting=None) — scoped by default; cross-setting requires explicit opt-in.

What the LLM does on cross-setting queries

When a query spans settings (e.g., "compare Aldric's role in Mardonari vs. The Wild Dream"):

1. Run the query in each setting.
2. Surface both answers, clearly labeled.
3. If there's an :ANALOG_OF edge, note that the two are intentionally analogous.
4. If the user wanted one setting and the engine picked the other, the response includes "did you mean setting X?" with a setting: parameter for re-query.

Cross-setting consistency rules

Out of scope for v1. Per docs/plan/06-slice-planes.md#out-of-scope, cross-setting consistency is deferred. The v1 model is: within a setting, consistency rules apply; across settings, they don't.

Examples

• "Who is Aldric?" — defaults to Mardonari; if the user has The Wild Dream context, they pass setting=the_wild_dream.
• "List all events in Mardonari in the 3rd Age" — scoped, single-setting.
• "Is House Vyr in both Mardonari and The Wild Dream?" — cross-setting; LLM runs in both, returns both, flags the boundary.

Cross-references

• docs/17-planes.md — the plane model
• docs/adr/0004-region-vs-plane.md — Region vs Plane
• docs/plan/06-slice-planes.md — the migration slice