uro-core 0.2.0__py3-none-any.whl

uro_core/__init__.py

@@ -0,0 +1,8 @@
+"""Uro Engine core library. Architecture: docs/01-architecture.md."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("uro-core")
+except PackageNotFoundError:  # pragma: no cover - source checkout without an install
+    __version__ = "0.0.0+unknown"

uro_core/_distill_core.py

@@ -0,0 +1,256 @@
+"""Outcome distillation core (D-25/D-32/D-41) — the parameterized engine behind Chronicler mode.
+
+INTERNAL (underscore module): the outcome-bundle models + the single `_distill` body, parameterized
+by a `protect` predicate that decides which actors are shielded from a bundle's canon-minting. Two
+callers inject it:
+
+- `uro_core.chronicler.distill_outcome*` → `protect=_is_protected` — the UNTRUSTED path (an external
+  game reporting over the network). The full D-32 ceiling holds: a protected actor can't be killed,
+  looted, or conscripted as a witness by a bundle.
+- `uro_core.authored.distill_authored_outcome` → `protect=_never_protected` — the TRUSTED,
+  in-process
+  path (a Posture-A embedder that already holds root via `store.append_beat`). It reuses the
+  distillation services (witness-rumor cascade, casualty→death, loot) with NO ceiling.
+
+**Trust is which MODULE a caller imports, never a flag on the wire (D-41, the outcome twin of D-37's
+`plan=`).** `uro_server` is import-linter-forbidden from importing this module / `uro_core.authored`
+directly, so the wire layer cannot even NAME the lethal path — the untrusted endpoint only ever
+reaches `chronicler` (ceiling on). The guarantee against the wire is structural + CI-enforced; the
+residual (a deliberate in-core edit importing `_distill` with a false predicate) is not
+language-preventable and is backstopped by a behavioral server test + review (same posture as D-37).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from uro_core.domain.events import (
+    DomainEvent,
+    actor_died,
+    claim_recorded,
+    external_cause,
+    item_transferred,
+)
+from uro_core.engines.actor import propagate_belief
+from uro_core.ports.projections import ProjectionQueries
+
+_MAX_LIST = 64  # cap on feats / casualties / loot per bundle (anti-abuse; docs/13, OQ-12)
+_MAX_WITNESSES = 256
+_SUPPORTED_BUNDLE_VERSIONS = frozenset({1})  # schema-v1 pin (D-41); a v2 bundle is rejected LOUDLY
+
+
+class Feat(BaseModel):
+    model_config = ConfigDict(extra="forbid")  # D-41: an unknown field (e.g. a forged trust)→400
+    actor: str  # the actor who performed the deed
+    description: str  # "a lone wizard split the warband's champion in two"
+
+
+class LootTransfer(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    item_id: str
+    from_ref: str = ""
+    to_ref: str = ""
+
+
+class OutcomeBundle(BaseModel):
+    """Outcome bundle v1 (docs/05, D-25) — what a game reports after resolving an encounter in its
+    own domain. List sizes are capped (D-32 anti-abuse) and `extra='forbid'` + a version pin (D-41)
+    make a forged `{trust:...}` field or an unknown v a loud 400, not a silently-dropped extra."""
+
+    model_config = ConfigDict(extra="forbid")
+    v: int = 1
+    encounter_id: str
+    participants: list[str] = Field(default_factory=list, max_length=_MAX_WITNESSES)
+    witnesses: list[str] = Field(
+        default_factory=list, max_length=_MAX_WITNESSES
+    )  # SURVIVORS who saw it
+    casualties: list[str] = Field(default_factory=list, max_length=_MAX_LIST)
+    feats: list[Feat] = Field(default_factory=list, max_length=_MAX_LIST)
+    loot: list[LootTransfer] = Field(default_factory=list, max_length=_MAX_LIST)
+    duration_rounds: int = 0
+
+    @field_validator("v")
+    @classmethod
+    def _pin_version(cls, v: int) -> int:
+        if v not in _SUPPORTED_BUNDLE_VERSIONS:
+            raise ValueError(
+                f"OutcomeBundle v={v} unsupported; this engine supports "
+                f"{sorted(_SUPPORTED_BUNDLE_VERSIONS)}"
+            )
+        return v
+
+
+# A protection predicate: (store, branch_id, ref) → is this actor shielded from bundle canon?
+Protect = Callable[[ProjectionQueries, str, str], Awaitable[bool]]
+
+
+async def _is_protected(store: ProjectionQueries, branch_id: str, ref: str) -> bool:
+    """A PC or a T2+ named actor is protected canon — an UNTRUSTED bundle may not kill/loot/
+    first-hand-witness it (D-32). The predicate the network path injects."""
+    if await store.is_pc(branch_id, ref):
+        return True
+    actor = await store.get_actor(branch_id, ref)
+    return actor is not None and actor.tier >= 2
+
+
+async def _never_protected(store: ProjectionQueries, branch_id: str, ref: str) -> bool:
+    """No actor is shielded — the TRUSTED, in-process path (D-41). A Posture-A embedder holds root
+    via `append_beat` anyway, so `authored.py` reuses distillation with the ceiling off."""
+    return False
+
+
+class ReceiptEntry(BaseModel):
+    """One line of an ingestion receipt (docs/18 B6): what distillation did with a bundle ref, so a
+    consumer learns whether its report was applied, downgraded to a rumor, or dropped — and why
+    (Ironwake rows 1-2, Seventh G-22). Purely informational; it commits nothing."""
+
+    kind: str  # feat | witness | casualty | loot
+    ref: str  # the actor / item ref the entry is about
+    disposition: str  # applied | downgraded | dropped
+    reason: str = ""
+
+
+@dataclass
+class DistillResult:
+    """The events to commit + the per-ref ingestion receipt (docs/18 B6)."""
+
+    events: list[DomainEvent] = field(default_factory=list)
+    receipt: list[ReceiptEntry] = field(default_factory=list)
+
+
+async def _distill(
+    store: ProjectionQueries, branch_id: str, bundle: OutcomeBundle, *, protect: Protect
+) -> DistillResult:
+    """Distill an outcome bundle into committable events (emitter E) + the witness rumor cascade +
+    a per-ref receipt. `protect` decides which actors are shielded from canon: `_is_protected` (the
+    untrusted D-32 ceiling) or `_never_protected` (a trusted embedder). Every protection site —
+    casualty-death, witness-conscript, loot from_ref, loot to_ref — routes through it, so the two
+    tiers differ ONLY in that predicate. Out-of-scope / nonexistent effects are dropped regardless
+    of tier (scope + existence are not trust-relaxable — a bundle still only touches its declared
+    cast). Deterministic ids (encounter_id, index) → idempotent replay."""
+    cause = external_cause(bundle.encounter_id)
+    participants = set(bundle.participants)
+    events: list[DomainEvent] = []
+    receipt: list[ReceiptEntry] = []
+
+    def note(kind: str, ref: str, disposition: str, reason: str = "") -> None:
+        receipt.append(ReceiptEntry(kind=kind, ref=ref, disposition=disposition, reason=reason))
+
+    async def resolve(ref: str) -> str | None:
+        """Entity-resolve a bundle ref to a KNOWN actor id (never mint one — a bundle cannot create
+        actors), or None. Pass the RAW name to find_actor_by_name (it canonicalizes internally):
+        passing a pre-canonicalized value would defeat its exact-name tiebreak and could attribute a
+        feat to a different duplicate than the extractor resolves to (P8-P1)."""
+        if not ref:
+            return None
+        if await store.get_actor(branch_id, ref) is not None:
+            return ref
+        match = await store.find_actor_by_name(branch_id, ref)
+        return match.actor_id if match is not None else None
+
+    # --- feats → testimony + a witness rumor cascade (deterministic ids → idempotent replay) ---
+    for i, feat in enumerate(bundle.feats):
+        actor = await resolve(feat.actor)
+        if actor is None or actor not in participants:
+            note("feat", feat.actor, "dropped", "actor unknown or not a declared participant")
+            continue  # a feat is about a DECLARED combatant; skip out-of-cast / unknown attribution
+        note("feat", actor, "applied", "recorded as truth=unknown testimony")
+        claim_id = f"c:{bundle.encounter_id}:feat:{i}"
+        events.append(
+            claim_recorded(
+                claim_id=claim_id,
+                statement=feat.description,
+                subject_refs=[actor],
+                truth="unknown",  # testimony, not canon — witnesses believe it, the world doesn't
+                origin="external",
+                caused_by=cause,
+            )
+        )
+        # Witnesses must be real, in the declared cast, alive (not a casualty), and (untrusted) not
+        # protected — an external game can't conscript a PC / named canon figure as its eyewitness.
+        witnesses: list[str] = []
+        for w in bundle.witnesses:
+            if w not in participants:
+                note("witness", w, "dropped", "not a declared participant")
+            elif w in bundle.casualties:
+                note("witness", w, "dropped", "reported as a casualty")
+            elif await store.get_actor(branch_id, w) is None:
+                note("witness", w, "dropped", "unknown actor")
+            elif await protect(store, branch_id, w):
+                note("witness", w, "dropped", "protected (PC or T2+) — can't be conscripted")
+            else:
+                witnesses.append(w)
+                note("witness", w, "applied", "carries the rumor")
+        events.extend(
+            await propagate_belief(store, branch_id, claim_id=claim_id, witnesses=witnesses)
+        )
+
+    # --- casualties: an in-cast, unprotected combatant dies; an out-of-cast one DROPS (scope, like
+    # feats/loot — D-41, Ironwake row-7); an in-cast PROTECTED one downgrades to testimony ---
+    for casualty in bundle.casualties:
+        victim = await store.get_actor(branch_id, casualty)
+        if victim is None or victim.status == "dead":
+            note("casualty", casualty, "dropped", "unknown actor or already dead")
+            continue
+        if casualty not in participants:
+            note("casualty", casualty, "dropped", "not a declared participant")
+            continue  # out-of-cast: dropped, not rumored (was a public rumor leak on the wire)
+        if not await protect(store, branch_id, casualty):
+            note("casualty", casualty, "applied", "committed as a death")
+            events.append(
+                actor_died(actor_id=casualty, cause="fell in the battle", caused_by=cause)
+            )
+        else:
+            note(
+                "casualty",
+                casualty,
+                "downgraded",
+                "protected canon — a rumored fall, not a committed death (untrusted path)",
+            )
+            # protected canon on the UNTRUSTED path — the world hears a rumor of the fall, it does
+            # not become a committed death (a protected death needs Uro's own mechanics, or the
+            # trusted authored path). On the trusted path `protect` is false, so this is dead.
+            events.append(
+                claim_recorded(
+                    claim_id=f"c:{bundle.encounter_id}:fell:{casualty}",
+                    statement=f"{victim.name} is said to have fallen at {bundle.encounter_id}.",
+                    subject_refs=[casualty],
+                    truth="unknown",
+                    origin="external",
+                    caused_by=cause,
+                )
+            )
+
+    # --- loot: only a real item, actually held by an in-cast, unprotected loser, moves to an
+    # in-cast, unprotected recipient (D-41: both ends route through `protect`) ---
+    for loot in bundle.loot:
+        item = await store.get_item(branch_id, loot.item_id)
+        if item is None or item.get("owner_ref") != loot.from_ref:
+            note("loot", loot.item_id, "dropped", "nonexistent item or from_ref is not the owner")
+            continue  # nonexistent item, or from_ref is not the current owner (forged transfer)
+        if loot.from_ref not in participants or loot.to_ref not in participants:
+            note("loot", loot.item_id, "dropped", "from_ref or to_ref not a declared participant")
+            continue  # both sides must be declared combatants (scope)
+        if loot.to_ref in bundle.casualties:
+            note("loot", loot.item_id, "dropped", "recipient reported as fallen")
+            continue  # a recipient reported as fallen can't carry loot off the field
+        if await protect(store, branch_id, loot.from_ref):
+            note("loot", loot.item_id, "dropped", "owner is protected (PC or T2+)")
+            continue  # a PC's / named actor's gear is not looted out-of-band by an external game
+        if await protect(store, branch_id, loot.to_ref):
+            note("loot", loot.item_id, "dropped", "recipient is protected (PC or T2+)")
+            continue  # nor can a bundle mint canon making a PC/named actor the RECIPIENT (D-41)
+        note("loot", loot.item_id, "applied", f"transferred {loot.from_ref} → {loot.to_ref}")
+        events.append(
+            item_transferred(
+                item_id=loot.item_id,
+                from_ref=loot.from_ref,
+                to_ref=loot.to_ref,
+                caused_by=cause,
+            )
+        )
+
+    return DistillResult(events=events, receipt=receipt)

uro_core/adapters/__init__.py

@@ -0,0 +1 @@
+"""Port implementations: Postgres, pgvector, in-proc bus. Governing doc: 07."""

uro_core/adapters/postgres/__init__.py

@@ -0,0 +1 @@
+"""Postgres adapter: event store, projections, SQL migrations (docs/14)."""

uro_core/adapters/postgres/migrations/001_init.sql

@@ -0,0 +1,46 @@
+-- Phase 0 timeline core (docs/03, 07). Append-only events + hash-chained commits.
+-- Projections, snapshots, edges, pgvector, and the full event catalog arrive later.
+
+CREATE TABLE worlds (
+    world_id   TEXT PRIMARY KEY,
+    name       TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE commits (
+    commit_id   TEXT PRIMARY KEY,
+    world_id    TEXT NOT NULL REFERENCES worlds(world_id),
+    parent_id   TEXT REFERENCES commits(commit_id),   -- NULL = world genesis
+    commit_hash TEXT NOT NULL,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX commits_parent_idx ON commits(parent_id);
+
+CREATE TABLE branches (
+    branch_id   TEXT PRIMARY KEY,
+    world_id    TEXT NOT NULL REFERENCES worlds(world_id),
+    name        TEXT NOT NULL,
+    head_commit TEXT REFERENCES commits(commit_id),
+    forked_from TEXT REFERENCES commits(commit_id)
+);
+
+-- append-only; NEVER updated or deleted. Canonical event types: docs/12.
+CREATE TABLE events (
+    event_id    TEXT PRIMARY KEY,
+    commit_id   TEXT NOT NULL REFERENCES commits(commit_id),
+    seq         INT  NOT NULL,
+    event_type  TEXT NOT NULL,
+    entity_refs TEXT[] NOT NULL DEFAULT '{}',
+    world_time  JSONB NOT NULL,
+    caused_by   JSONB NOT NULL,
+    payload     JSONB NOT NULL
+);
+CREATE INDEX events_commit_idx ON events(commit_id);
+CREATE INDEX events_type_idx ON events(event_type);
+
+CREATE TABLE campaigns (
+    campaign_id TEXT PRIMARY KEY,
+    world_id    TEXT NOT NULL REFERENCES worlds(world_id),
+    branch_id   TEXT NOT NULL REFERENCES branches(branch_id),
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);

uro_core/adapters/postgres/migrations/002_llm_calls.sql

@@ -0,0 +1,16 @@
+-- Usage metering (docs/07, D-14, docs/01 rule 5). Stage-tagged LLM calls.
+-- Operational and PRUNABLE — never world truth, never on the timeline.
+-- Added as a forward-only migration (docs/14): 001 is already applied, so metering
+-- arrives in its own file rather than editing the released migration.
+
+CREATE TABLE llm_calls (
+    call_id     TEXT PRIMARY KEY,
+    stage_tag   TEXT NOT NULL,
+    model       TEXT,
+    prompt_hash TEXT NOT NULL,
+    tokens_in   INT,
+    tokens_out  INT,
+    latency_ms  INT NOT NULL,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX llm_calls_stage_idx ON llm_calls(stage_tag);

uro_core/adapters/postgres/migrations/003_projections.sql

@@ -0,0 +1,35 @@
+-- Phase 1 projections (docs/02, 03, 07). Rebuildable read-models DERIVED from the
+-- event log — never written directly, only by the projector, in the same transaction
+-- as the commit that produced the events. Keyed by (branch_id, entity_id).
+-- Phase 1 has a single branch (main); copy-on-fork arrives in Phase 2.
+
+CREATE TABLE proj_actors (
+    branch_id TEXT NOT NULL,
+    actor_id  TEXT NOT NULL,
+    name      TEXT NOT NULL,
+    tier      INT  NOT NULL,
+    role      TEXT NOT NULL DEFAULT '',
+    aliases   TEXT[] NOT NULL DEFAULT '{}',
+    PRIMARY KEY (branch_id, actor_id)
+);
+
+CREATE TABLE proj_claims (
+    branch_id    TEXT NOT NULL,
+    claim_id     TEXT NOT NULL,
+    statement    TEXT NOT NULL,
+    subject_refs TEXT[] NOT NULL DEFAULT '{}',
+    truth        TEXT NOT NULL,          -- true | false | unknown (engine ground truth)
+    origin       TEXT NOT NULL DEFAULT '',
+    PRIMARY KEY (branch_id, claim_id)
+);
+CREATE INDEX proj_claims_subject_idx ON proj_claims USING GIN (subject_refs);
+
+CREATE TABLE proj_beliefs (
+    branch_id    TEXT NOT NULL,
+    actor_id     TEXT NOT NULL,
+    claim_id     TEXT NOT NULL,
+    confidence   DOUBLE PRECISION NOT NULL,   -- how strongly the actor holds the claim
+    learned_from TEXT,
+    PRIMARY KEY (branch_id, actor_id, claim_id)
+);
+CREATE INDEX proj_beliefs_actor_idx ON proj_beliefs (branch_id, actor_id);

uro_core/adapters/postgres/migrations/004_embeddings.sql

@@ -0,0 +1,23 @@
+-- Phase 1 semantic memory (docs/04, 07). pgvector-backed.
+-- Vectors live once, keyed by content hash (dedup); per-branch membership rows point
+-- at them and carry the recallable text. Copy-on-fork of memberships is a later increment.
+-- Unbounded `vector` (dimension set by the deployment's embedder) + exact search for now;
+-- an HNSW index with a pinned dimension arrives when scale demands it.
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE embeddings (
+    content_hash TEXT PRIMARY KEY,
+    vector       vector NOT NULL
+);
+
+CREATE TABLE memory_index (
+    memory_id    TEXT PRIMARY KEY,
+    branch_id    TEXT NOT NULL,
+    content_hash TEXT NOT NULL REFERENCES embeddings(content_hash),
+    kind         TEXT NOT NULL,              -- 'beat' | 'synopsis' | 'journal' | …
+    text         TEXT NOT NULL,              -- the recallable snippet
+    entity_refs  TEXT[] NOT NULL DEFAULT '{}',
+    commit_id    TEXT NOT NULL
+);
+CREATE INDEX memory_index_branch_idx ON memory_index(branch_id);

uro_core/adapters/postgres/migrations/005_timeline_branching.sql

@@ -0,0 +1,56 @@
+-- Phase 2 timeline substrate (docs/03, 07). Markers, snapshots, and the places
+-- projection — the machinery for branch-from-any-commit and materialization.
+--
+-- `depth` = generation from genesis (genesis = 0, each child = parent + 1). Commits
+-- form a tree (one parent each; branches share prefixes), so depth is well-defined.
+-- It gives cheap "snapshot every N commits", ordered replay, and git-log numbering
+-- without walking ancestry per beat. Backfilled here for any pre-Phase-2 commits.
+
+ALTER TABLE commits ADD COLUMN depth INT NOT NULL DEFAULT 0;
+
+WITH RECURSIVE gen AS (
+    SELECT commit_id, 0 AS depth FROM commits WHERE parent_id IS NULL
+    UNION ALL
+    SELECT c.commit_id, gen.depth + 1
+    FROM commits c JOIN gen ON c.parent_id = gen.commit_id
+)
+UPDATE commits SET depth = gen.depth FROM gen WHERE commits.commit_id = gen.commit_id;
+
+CREATE INDEX commits_depth_idx ON commits(depth);
+
+-- Markers: named, immutable refs to a commit (campaign-a-end, "the meteor falls").
+-- Refs, not events (docs/12 rule 2) — creating one never touches the log.
+CREATE TABLE markers (
+    marker_id  TEXT PRIMARY KEY,
+    world_id   TEXT NOT NULL REFERENCES worlds(world_id),
+    name       TEXT NOT NULL,
+    commit_id  TEXT NOT NULL REFERENCES commits(commit_id),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE (world_id, name)
+);
+
+-- Snapshots: full materialized projection state at a commit, serialized every N
+-- commits and at markers. Keyed by commit_id — state-at-a-commit is branch-independent
+-- (a commit's ancestry is immutable), so a snapshot serves any branch that passes
+-- through it. Materializing commit X = nearest ancestor snapshot ≤ X + replay forward;
+-- branching is therefore O(replay window), not O(history). state_hash makes each blob
+-- tamper-evident on its own (docs/07, the export-pack trust anchor).
+CREATE TABLE snapshots (
+    commit_id  TEXT PRIMARY KEY REFERENCES commits(commit_id),
+    state_hash TEXT NOT NULL,
+    state      JSONB NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Places projection (docs/02). Deferred in Phase 1 ("places/edges when needed");
+-- the meteor test needs it — PlaceDestroyed(Vel) is simply true on the aftermath
+-- branch and false on a what-if forked before the strike.
+CREATE TABLE proj_places (
+    branch_id   TEXT NOT NULL,
+    place_id    TEXT NOT NULL,
+    name        TEXT NOT NULL,
+    kind        TEXT NOT NULL DEFAULT 'site',    -- region | settlement | site (docs/02)
+    status      TEXT NOT NULL DEFAULT 'active',  -- active | destroyed
+    description TEXT NOT NULL DEFAULT '',
+    PRIMARY KEY (branch_id, place_id)
+);

uro_core/adapters/postgres/migrations/006_branch_name_unique.sql

@@ -0,0 +1,9 @@
+-- Phase 2 review fix (inc 2.1): branch names are unique per world.
+--
+-- Markers got UNIQUE(world_id, name) in 005; branches were left unguarded, so
+-- `uro branch fork --name main` could mint a SECOND branch named 'main' — and the
+-- world-main lookups (get_world / get_world_by_name) resolve via an unordered
+-- `JOIN branches ... AND b.name='main'`, which then returns an arbitrary one and
+-- silently targets the wrong timeline. Git's branch namespace is unique per repo;
+-- Uro's is unique per world. Structural guarantee, not policy (the repo norm).
+ALTER TABLE branches ADD CONSTRAINT branches_world_name_uniq UNIQUE (world_id, name);

uro_core/adapters/postgres/migrations/007_pc_binding.sql

@@ -0,0 +1,14 @@
+-- Phase 2 inc 2.2: PC-binding projection (docs/02, 12). "Is this actor a PC?" is
+-- answered per-branch by the campaign's PCBound/PCReleased history — NOT a global flag,
+-- because the same actor_id is a PC on the fork where the player continues and an
+-- ordinary NPC on a sibling fork (the meteor test's retired wizard). `active` flips to
+-- false on PCReleased (campaign end); the row stays as history ("was a PC in campaign A").
+CREATE TABLE proj_pcs (
+    branch_id      TEXT NOT NULL,
+    campaign_id    TEXT NOT NULL,
+    actor_id       TEXT NOT NULL,
+    participant_id TEXT NOT NULL,
+    active         BOOLEAN NOT NULL DEFAULT true,
+    PRIMARY KEY (branch_id, campaign_id, actor_id)
+);
+CREATE INDEX proj_pcs_active_idx ON proj_pcs (branch_id, actor_id) WHERE active;

uro_core/adapters/postgres/migrations/008_sheets.sql

@@ -0,0 +1,13 @@
+-- Phase 3 inc 3.2: character-sheet projection (docs/06, 12). The store keeps the sheet
+-- opaquely as JSONB; the pipeline reads it via the shared port Sheet (a d20-shaped contract
+-- for now, OQ-13) and the ruleset owns its semantics. Written by the projector on
+-- SheetUpdated (emitter R S),
+-- carried per-branch and rebuilt on replay like every other projection. The mechanics gate
+-- reads a PC/NPC sheet here to build a CheckRequest.
+CREATE TABLE proj_sheets (
+    branch_id  TEXT NOT NULL,
+    actor_id   TEXT NOT NULL,
+    ruleset_id TEXT NOT NULL DEFAULT '',
+    sheet      JSONB NOT NULL,
+    PRIMARY KEY (branch_id, actor_id)
+);

uro_core/adapters/postgres/migrations/009_items.sql

@@ -0,0 +1,13 @@
+-- Phase 3 inc 3.3: items projection (docs/02, 12). Minimal ownership tracking so a lost
+-- fight's loot (ItemTransferred) and a starting weapon (ItemCreated) persist into later
+-- free-roam. Written by the projector on ItemCreated/ItemTransferred; HP damage lives in
+-- proj_sheets (ActorDamaged mutates the sheet's hp), so no separate condition table yet.
+CREATE TABLE proj_items (
+    branch_id TEXT NOT NULL,
+    item_id   TEXT NOT NULL,
+    name      TEXT NOT NULL DEFAULT '',
+    kind      TEXT NOT NULL DEFAULT '',
+    owner_ref TEXT NOT NULL DEFAULT '',
+    PRIMARY KEY (branch_id, item_id)
+);
+CREATE INDEX proj_items_owner_idx ON proj_items (branch_id, owner_ref);

uro_core/adapters/postgres/migrations/010_factions_edges.sql

@@ -0,0 +1,27 @@
+-- Phase 4 inc 4.2: factions + the graph edge table (docs/02, 07). Deferred since Phase 1
+-- ("places/edges when needed") — World seeding needs them: dynasties are factions and wars
+-- are `at_war_with` edges, so seed 42 vs 43 differ here on identical geography.
+--
+-- Edges are the whole graph story for MVP. The PoC keeps CURRENT-STATE edges keyed by
+-- (src, rel_type, dst); the per-commit temporal validity (valid_from/valid_to for point-in-time
+-- reads, docs/07) is deferred — copy-on-fork already materializes current state per branch.
+CREATE TABLE proj_factions (
+    branch_id   TEXT NOT NULL,
+    faction_id  TEXT NOT NULL,
+    name        TEXT NOT NULL,
+    kind        TEXT NOT NULL DEFAULT 'faction',   -- faction | religion (docs/02)
+    description TEXT NOT NULL DEFAULT '',
+    PRIMARY KEY (branch_id, faction_id)
+);
+
+CREATE TABLE proj_edges (
+    branch_id TEXT NOT NULL,
+    src       TEXT NOT NULL,
+    rel_type  TEXT NOT NULL,   -- member_of | located_in | at_war_with | rules | owns | knows | …
+    dst       TEXT NOT NULL,
+    weight    DOUBLE PRECISION NOT NULL DEFAULT 1.0,
+    attrs     JSONB NOT NULL DEFAULT '{}',
+    PRIMARY KEY (branch_id, src, rel_type, dst)
+);
+CREATE INDEX proj_edges_src_idx ON proj_edges (branch_id, src);
+CREATE INDEX proj_edges_dst_idx ON proj_edges (branch_id, dst);

uro_core/adapters/postgres/migrations/011_threads.sql

@@ -0,0 +1,11 @@
+-- Phase 4 review fix: threads become real state. World-pack conflict seeds (authored) and AI
+-- backfill (provenance=ai_backfill) now commit as ThreadCreated events at import (emitter S),
+-- so the machine's inventions are reviewable committed state — not a discarded in-memory model.
+CREATE TABLE proj_threads (
+    branch_id   TEXT NOT NULL,
+    thread_id   TEXT NOT NULL,
+    stakes      TEXT NOT NULL,
+    state       TEXT NOT NULL DEFAULT 'dormant',
+    provenance  TEXT NOT NULL DEFAULT 'author',   -- author | ai_backfill (docs/09)
+    PRIMARY KEY (branch_id, thread_id)
+);

uro_core/adapters/postgres/migrations/012_actor_status.sql

@@ -0,0 +1,5 @@
+-- Cross-phase review fix (P1+P3+P5): ActorDied previously only zeroed a character sheet's hp, so
+-- a sheet-less casualty (a History-seeded NPC, or a Chronicler-reported death) left NO queryable
+-- death trace — recall still surfaced it as alive/present. A lifecycle column on proj_actors gives
+-- death a projection trace independent of the ruleset sheet.
+ALTER TABLE proj_actors ADD COLUMN status TEXT NOT NULL DEFAULT 'alive';  -- alive | dead

uro_core/adapters/postgres/migrations/013_campaign_ruleset.sql

@@ -0,0 +1,6 @@
+-- Phase 6 inc 6.3 (D-30): pin the bound ruleset on the campaign, so a later `play`/fork rebinds
+-- the SAME ruleset (a d20 campaign resolves uro_basic; a PbtA campaign resolves uro_pbta). Before
+-- this, only the CampaignStarted EVENT carried ruleset_id (and no version) — the play path ignored
+-- it and hard-bound uro_basic. These columns make the binding queryable at get_campaign time.
+ALTER TABLE campaigns ADD COLUMN ruleset_id TEXT NOT NULL DEFAULT '';
+ALTER TABLE campaigns ADD COLUMN ruleset_version TEXT NOT NULL DEFAULT '';

uro_core/adapters/postgres/migrations/014_memory_index_commit_idx.sql

@@ -0,0 +1,7 @@
+-- Gap-report fix (Hollowloop G-10, found by a fork-per-loop game at 500 forks): the fork hot path
+-- `_copy_memory` filters `memory_index WHERE commit_id = ANY(...)`, but the only index on the table
+-- was on `branch_id` (migration 004) — so every fork did a Seq Scan over ALL of memory_index, which
+-- holds one row per beat of EVERY world in the database. EXPLAIN ANALYZE showed ~17k rows discarded
+-- per fork (30-60% of fork time), and the cost grows with total beats ever played, not with the
+-- world being forked. One index removes the scan.
+CREATE INDEX IF NOT EXISTS memory_index_commit_idx ON memory_index(commit_id);

uro_core/adapters/postgres/migrations/015_counters.sql

@@ -0,0 +1,16 @@
+-- Computation Layer INC-C1 (docs/19, D-34): pack-authored numeric state as engine-owned, event-
+-- sourced integer counters. A CounterChanged event UPSERTs a row here; the projector is the sole
+-- writer, and because proj_counters joins projector._HANDLERS + _SNAPSHOT_TABLES it forks/replays/
+-- snapshots/exports by construction (the fix for shadow-state that did not ride fork_branch —
+-- Sable G-1/G-10). value is BIGINT (integer only — no float, for cross-platform arithmetic
+-- determinism). created_day is preserved on UPSERT (updated_day moves) so claim/counter age math
+-- works. Branch-scoped like every projection → per-branch isolation + copy-on-fork inherited.
+CREATE TABLE proj_counters (
+    branch_id    TEXT   NOT NULL,
+    scope_ref    TEXT   NOT NULL,   -- the entity the counter hangs on (a faction/thread/place id)
+    key          TEXT   NOT NULL,   -- the counter name (e.g. "tension", "heat", "influence")
+    value        BIGINT NOT NULL DEFAULT 0,
+    created_day  INT    NOT NULL DEFAULT 0,
+    updated_day  INT    NOT NULL DEFAULT 0,
+    PRIMARY KEY (branch_id, scope_ref, key)
+);

uro_core/adapters/postgres/migrations/016_campaign_seed.sql

@@ -0,0 +1,12 @@
+-- G-3 (docs/18): make a played-through campaign's mechanics REPRODUCIBLE run-to-run. Before this,
+-- Engine._beat_rng hashed (campaign_id : head_commit) — BOTH freshly random per run (new_id()) — so
+-- the same intents produced different d20/2d6 rolls every run (even on a REPLAY of the same log), and
+-- a "guaranteed-loss" fight would occasionally flip (a flaky gate, Seventh Vault G-3). The fix reseeds
+-- _beat_rng from the campaign's persisted seed + the commit DEPTH (a deterministic generation count),
+-- so the RNG STREAM is a pure function of (seed, depth) — a fight then replays identically given an
+-- identical event log up to it (which is what makes the deterministic-provider CI gate reproducible;
+-- live-LLM runs can still vary the log). The seed lives on CampaignStarted (payload) already;
+-- denormalize it here (like ruleset_id) so get_campaign can load it without replaying the event.
+-- BIGINT: the seed is a 48-bit-ish integer; DEFAULT 0 keeps every pre-existing campaign valid
+-- (seed 0 is a fine, fully-deterministic default — tests pin it, `uro campaign new --seed` sets it).
+ALTER TABLE campaigns ADD COLUMN seed BIGINT NOT NULL DEFAULT 0;

uro_core/adapters/postgres/migrations/017_participant_notes.sql

@@ -0,0 +1,21 @@
+-- B8 (docs/18, D-36): participant-scoped memory — a player's out-of-world meta-knowledge that
+-- SURVIVES A FORK (time-loop / roguelike / NG+). Keyed on (participant_id, world_ref) — NOT
+-- branch_id — so it is deliberately OUTSIDE the branch axis: it is NOT a proj_* projection, is NOT
+-- in the projector's _HANDLERS/_SNAPSHOT_TABLES, and is never touched by fork_branch's copy step, so
+-- a fork neither copies nor resets it (fork-immunity is structural). It is also NOT an event and has
+-- no DIRECT path into proj_claims/proj_beliefs — nothing wires it into the extractor, planner, or
+-- belief-propagation, so it cannot DIRECTLY become canon or an NPC belief (structural for direct
+-- wiring). It surfaces only in the narrator prompt (labelled "the world does NOT know this"); a note
+-- the narrator ECHOES into prose could then be re-extracted like any narrator output — that residual
+-- is fenced by narrator-tier trust (by-policy), the same fence every narrator input already has (13).
+-- world_ref is the SCOPE knob: the world_id gives per-(world x participant) scope (the default; a
+-- within-world fork keeps the same world_id, so it survives); a sentinel could later give global.
+CREATE TABLE participant_notes (
+    participant_id TEXT   NOT NULL,
+    world_ref      TEXT   NOT NULL,   -- the world_id (scope); a fork stays in-world so notes persist
+    key            TEXT   NOT NULL,   -- caller-supplied or sha256(text): the dedup key across loops
+    text           TEXT   NOT NULL,
+    pinned         BOOLEAN NOT NULL DEFAULT FALSE,   -- always-surface vs entity-triggered
+    entity_refs    TEXT[]  NOT NULL DEFAULT '{}',    -- e.g. {name:vault} — surfaces when mentioned
+    PRIMARY KEY (participant_id, world_ref, key)
+);

uro_core/adapters/postgres/migrations/018_session_tokens.sql

@@ -0,0 +1,19 @@
+-- B10 (docs/18, D-39): runtime session-token management. A durable, hashed, revocable token
+-- registry so a player added to a RUNNING server (bind_pc / uro campaign join) can AUTHENTICATE
+-- without a server restart (the --token argv map is frozen at launch). Like participant_notes
+-- (017), this is deliberately OFF THE BRANCH AXIS: it is NOT a proj_* projection, is NOT in the
+-- projector's _HANDLERS/_SNAPSHOT_TABLES, and is never touched by fork_branch / import_world — a
+-- token authenticates a HUMAN to the server, independent of which what-if branch they explore, so a
+-- fork must neither copy nor reset it (structural, mirrored by a fork-exclusion test). It is also
+-- NOT event-sourced (D-31/D-39 kept: no session/turn/token state enters the log — nothing new
+-- rides fork_branch). Only sha256(token) is stored; the plaintext is returned once at mint and
+-- never at rest. Durability is REQUIRED: an in-process-only registry would lose runtime-minted
+-- tokens on restart while proj_pcs survives, permanently locking out every runtime-added player.
+CREATE TABLE session_tokens (
+    token_hash     TEXT        NOT NULL PRIMARY KEY,  -- sha256(token); plaintext never stored
+    participant_id TEXT        NOT NULL,
+    campaign_id    TEXT        NOT NULL,
+    revoked        BOOLEAN     NOT NULL DEFAULT FALSE,
+    created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX session_tokens_participant_idx ON session_tokens (participant_id, campaign_id);