lorebase-store 0.2.3__py3-none-any.whl

lorebase_store/models/materialized.py

@@ -0,0 +1,277 @@
+"""Materialized heads (design 7.2): compiled schema, Records, Links, history, embeddings.
+
+Per-Attribute expression indexes on `mat_records` and per-dimension HNSW indexes on
+`embeddings` depend on configuration and schema; they are created outside this metadata.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pgvector.sqlalchemy import VECTOR
+from sqlalchemy import BigInteger, CheckConstraint, ForeignKeyConstraint, Index, Integer, text
+from sqlalchemy.dialects.postgresql import TSVECTOR
+from sqlalchemy.orm import Mapped, mapped_column
+
+from lorebase_store.models.base import H32, HASH_PARTITIONED, Base, DomainKey, domain_fk
+
+
+def _branch_fk() -> ForeignKeyConstraint:
+    """Materialized rows belong to a ref and go when the branch is deleted."""
+    return ForeignKeyConstraint(
+        ["domain_id", "branch"], ["refs.domain_id", "refs.name"], ondelete="CASCADE"
+    )
+
+
+class MatSchema(Base):
+    """Compiled schema at a branch head.
+
+    `path_fanout` is the `store.traverse.path_fanout` the branch's materialized path
+    Derivations were computed with (`None` before any was): a different setting rewrites
+    them (`lorebase_store.materialize.paths`).
+    """
+
+    __tablename__ = "mat_schema"
+    __table_args__ = (_branch_fk(),)
+
+    domain_id: Mapped[DomainKey]
+    branch: Mapped[str] = mapped_column(primary_key=True)
+    schema_hash: Mapped[H32]
+    compiled: Mapped[dict[str, Any]]
+    path_fanout: Mapped[int | None] = mapped_column(Integer)
+
+
+class MatRecord(Base):
+    """One Record at a branch head; `values` is keyed by Attribute id.
+
+    `revision_generation` is the generation of the Revision that last wrote the row and
+    `deleted` marks a tombstone, which only overlay branches hold (store schema notes).
+    `lineage_revisions` maps each Attribute of `lineage` to the Revision (hex) of that change,
+    and `$created` to the Revision that last created the Record (revision 0032); it is null
+    on rows written before that revision, whose readers fall back to the branch history.
+    """
+
+    __tablename__ = "mat_records"
+    __table_args__ = (
+        _branch_fk(),
+        # btree_gin (revision 0011): a search's Domain and branch are index conditions of the
+        # search vector index.
+        Index(
+            "ix_mat_records_branch_search",
+            "domain_id",
+            "branch",
+            "search",
+            postgresql_using="gin",
+        ),
+        Index(
+            "ix_mat_records_values",
+            "values",
+            postgresql_using="gin",
+            postgresql_ops={"values": "jsonb_path_ops"},
+        ),
+        HASH_PARTITIONED,
+    )
+
+    domain_id: Mapped[DomainKey]
+    branch: Mapped[str] = mapped_column(primary_key=True)
+    kind_id: Mapped[str] = mapped_column(primary_key=True)
+    key: Mapped[str] = mapped_column(primary_key=True)
+    values: Mapped[dict[str, Any]]
+    derived: Mapped[dict[str, Any]] = mapped_column(server_default=text("'{}'::jsonb"))
+    title: Mapped[str | None]
+    search: Mapped[str | None] = mapped_column(TSVECTOR)
+    object_hash: Mapped[H32]
+    lineage: Mapped[dict[str, Any]]
+    updated_revision: Mapped[H32]
+    updated_at: Mapped[datetime]
+    revision_generation: Mapped[int] = mapped_column(BigInteger, server_default=text("0"))
+    deleted: Mapped[bool] = mapped_column(server_default=text("false"))
+    lineage_revisions: Mapped[dict[str, Any] | None]
+
+
+class MatLink(Base):
+    """One Link at a branch head, indexed in both directions."""
+
+    __tablename__ = "mat_links"
+    __table_args__ = (
+        _branch_fk(),
+        Index("ix_mat_links_reverse", "domain_id", "branch", "relation_id", "to_key"),
+        HASH_PARTITIONED,
+    )
+
+    domain_id: Mapped[DomainKey]
+    branch: Mapped[str] = mapped_column(primary_key=True)
+    relation_id: Mapped[str] = mapped_column(primary_key=True)
+    from_key: Mapped[str] = mapped_column(primary_key=True)
+    to_key: Mapped[str] = mapped_column(primary_key=True)
+    values: Mapped[dict[str, Any]] = mapped_column(server_default=text("'{}'::jsonb"))
+    object_hash: Mapped[H32]
+    lineage: Mapped[dict[str, Any]]
+    revision_generation: Mapped[int] = mapped_column(BigInteger, server_default=text("0"))
+    deleted: Mapped[bool] = mapped_column(server_default=text("false"))
+
+
+class MatLineageMap(Base):
+    """A lineage map shared by the rows that name it (revision 0036).
+
+    With shared lineage maps (`store.storage.lineage_maps`), the map columns of `mat_records`
+    (`lineage`, `lineage_revisions`) and `mat_links` (`lineage`) hold `{"$map": "<hex id>"}`
+    and the map is stored here once per Domain; `id` is the first 16 bytes of the SHA-256 of
+    its canonical text. Readers resolve the columns with `lb_lineage(domain_id, column)`.
+    """
+
+    __tablename__ = "mat_lineage_maps"
+    __table_args__ = (
+        CheckConstraint("octet_length(id) = 16", name="id_h16"),
+        domain_fk(),
+    )
+
+    domain_id: Mapped[DomainKey]
+    id: Mapped[bytes] = mapped_column(primary_key=True)
+    map: Mapped[dict[str, Any]]
+
+
+class StorageTask(Base):
+    """Progress of a resumable step of `storage apply` (`lorebase_store.storage`, 0036)."""
+
+    __tablename__ = "storage_tasks"
+
+    name: Mapped[str] = mapped_column(primary_key=True)
+    state: Mapped[dict[str, Any]] = mapped_column(server_default=text("'{}'::jsonb"))
+    updated_at: Mapped[datetime] = mapped_column(server_default=text("now()"))
+
+
+class MatLexicon(Base):
+    """Per Kind, the words of a branch's own search vectors and how many of its rows hold
+    each (revision 0018): typo-tolerant search matches query words against them by trigrams.
+
+    Kept by triggers on `mat_records`; words with a digit or longer than 64 characters are
+    left out. An overlay holds the words of its own rows, and its readers add its base's.
+    """
+
+    __tablename__ = "mat_lexicon"
+    __table_args__ = (
+        _branch_fk(),
+        Index(
+            "ix_mat_lexicon_branch_word",
+            "domain_id",
+            "branch",
+            "word",
+            postgresql_using="gin",
+            postgresql_ops={"word": "gin_trgm_ops"},
+        ),
+        Index("ix_mat_lexicon_spent", "domain_id", "branch", postgresql_where=text("records <= 0")),
+    )
+
+    domain_id: Mapped[DomainKey]
+    branch: Mapped[str] = mapped_column(primary_key=True)
+    kind_id: Mapped[str] = mapped_column(primary_key=True)
+    word: Mapped[str] = mapped_column(primary_key=True)
+    records: Mapped[int] = mapped_column(BigInteger)
+
+
+class MatHistory(Base):
+    """Per branch, per element change log along the first-parent chain."""
+
+    __tablename__ = "mat_history"
+    __table_args__ = (_branch_fk(),)
+
+    domain_id: Mapped[DomainKey]
+    branch: Mapped[str] = mapped_column(primary_key=True)
+    partition: Mapped[str] = mapped_column(primary_key=True)
+    element_key: Mapped[str] = mapped_column(primary_key=True)
+    revision_id: Mapped[H32] = mapped_column(primary_key=True)
+    at: Mapped[datetime]
+    old_hash: Mapped[H32 | None]
+    new_hash: Mapped[H32 | None]
+    provenance: Mapped[dict[str, Any] | None]
+
+
+class Embedding(Base):
+    """Vector of an object for one model and embedding template; shared by all branches whose
+    template of the object's Kind has that fingerprint.
+
+    The column is dimensionless so models of different sizes coexist; `dims` must match the
+    vector and selects the per-dimension HNSW index. `text_hash` is the SHA-256 of the text
+    that was embedded (revision 0014): an object whose text did not change keeps its vector,
+    and a new object with the text of another reuses that one's vector. `fingerprint` is the
+    template fingerprint the text was rendered with (revision 0024); empty for a vector whose
+    template could not be told when the column was added.
+    """
+
+    __tablename__ = "embeddings"
+    __table_args__ = (
+        CheckConstraint("vector_dims(embedding) = dims", name="dims_match"),
+        domain_fk(),
+        Index("ix_embeddings_domain_id_model_text_hash", "domain_id", "model", "text_hash"),
+    )
+
+    domain_id: Mapped[DomainKey]
+    object_hash: Mapped[H32] = mapped_column(primary_key=True)
+    model: Mapped[str] = mapped_column(primary_key=True)
+    fingerprint: Mapped[str] = mapped_column(primary_key=True)
+    dims: Mapped[int] = mapped_column(Integer)
+    embedding: Mapped[list[float]] = mapped_column(VECTOR())
+    text_hash: Mapped[H32 | None]
+
+
+class EmbeddingCursor(Base):
+    """How far the embedding job got on a branch for one model (revision 0014).
+
+    `head` is the branch head the last complete pass read and `fingerprints` the embedding
+    template fingerprint of each embedded Kind at that head; a pass is skipped while both are
+    unchanged, and Kinds whose fingerprint changed have every text rendered again.
+    """
+
+    __tablename__ = "embedding_cursors"
+    __table_args__ = (_branch_fk(),)
+
+    domain_id: Mapped[DomainKey]
+    branch: Mapped[str] = mapped_column(primary_key=True)
+    model: Mapped[str] = mapped_column(primary_key=True)
+    head: Mapped[H32]
+    fingerprints: Mapped[dict[str, Any]]
+    updated_at: Mapped[datetime]
+
+
+class BranchMaterialization(Base):
+    """Progress of turning a branch into a full copy in batches (revisions 0017, 0031).
+
+    One row per branch whose rows a `store.materialize` job writes: a copy branch created
+    as an overlay, an overlay promoted in the background (`strategy` `base`: copies the base
+    rows), or a branch built from the tree of its head (`tree`). `phase` and `cursor` say
+    where the next batch starts; `base_branch` and `base_generation` are the fork point a
+    `base` copy reads (for `tree`, the source and the head's generation). `failures` counts
+    failed jobs; `reconcile` holds schema changes made during the copy. Rows go with their
+    branch.
+    """
+
+    __tablename__ = "branch_materializations"
+    __table_args__ = (
+        _branch_fk(),
+        CheckConstraint("status IN ('pending', 'running', 'done', 'failed')", name="status"),
+        CheckConstraint("strategy IN ('base', 'tree')", name="strategy"),
+        CheckConstraint(
+            "phase IN ('records', 'links', 'history', 'clear', 'tree_history', 'tree_rows', "
+            "'switch', 'prune', 'derived', 'paths', 'search', 'done')",
+            name="phase",
+        ),
+    )
+
+    domain_id: Mapped[DomainKey]
+    branch: Mapped[str] = mapped_column(primary_key=True)
+    status: Mapped[str]
+    phase: Mapped[str]
+    base_branch: Mapped[str]
+    base_generation: Mapped[int] = mapped_column(BigInteger)
+    cursor: Mapped[dict[str, Any] | None]
+    rows_done: Mapped[int] = mapped_column(BigInteger, server_default=text("0"))
+    rows_total: Mapped[int | None] = mapped_column(BigInteger)
+    error: Mapped[str | None]
+    strategy: Mapped[str] = mapped_column(server_default=text("'base'"))
+    failures: Mapped[int] = mapped_column(server_default=text("0"))
+    reconcile: Mapped[dict[str, Any] | None]
+    created_at: Mapped[datetime]
+    updated_at: Mapped[datetime]
+    finished_at: Mapped[datetime | None]

lorebase_store/models/proposals.py

@@ -0,0 +1,195 @@
+"""Proposals and merges (design 7.3)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import (
+    REAL,
+    CheckConstraint,
+    ForeignKeyConstraint,
+    Index,
+    Integer,
+    SmallInteger,
+    UniqueConstraint,
+    text,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from lorebase_store.models.base import H32, Base, DomainKey, domain_fk
+from lorebase_store.models.enums import (
+    ITEM_DECISION,
+    MERGE_ATTEMPT_STATUS,
+    PROPOSAL_ORIGIN,
+    PROPOSAL_STATUS,
+    REVIEW_VERDICT,
+    ItemDecision,
+    MergeAttemptStatus,
+    ProposalOrigin,
+    ProposalStatus,
+    ReviewVerdict,
+)
+
+
+def _proposal_fk() -> ForeignKeyConstraint:
+    return ForeignKeyConstraint(
+        ["domain_id", "proposal_id"],
+        ["proposals.domain_id", "proposals.id"],
+        ondelete="CASCADE",
+    )
+
+
+class Proposal(Base):
+    """Request to merge a source ref into a target ref."""
+
+    __tablename__ = "proposals"
+    __table_args__ = (
+        domain_fk(),
+        Index(None, "domain_id", "target_ref", "status"),
+        Index(
+            "uq_proposals_idempotency",
+            "domain_id",
+            "author",
+            "idempotency_key",
+            unique=True,
+            postgresql_where=text("idempotency_key IS NOT NULL"),
+        ),
+    )
+
+    domain_id: Mapped[DomainKey]
+    id: Mapped[str] = mapped_column(primary_key=True)
+    title: Mapped[str]
+    description: Mapped[str | None]
+    source_ref: Mapped[str]
+    target_ref: Mapped[str]
+    origin: Mapped[ProposalOrigin] = mapped_column(PROPOSAL_ORIGIN)
+    status: Mapped[ProposalStatus] = mapped_column(PROPOSAL_STATUS)
+    author: Mapped[str]
+    created_at: Mapped[datetime]
+    merged_revision: Mapped[H32 | None]
+    checks: Mapped[dict[str, Any] | None]
+    policies: Mapped[dict[str, Any] | None]
+    idempotency_key: Mapped[str | None]
+    updated_at: Mapped[datetime | None]
+
+
+class ProposalReview(Base):
+    """One review of a Proposal; a reviewer may review several times."""
+
+    __tablename__ = "proposal_reviews"
+    __table_args__ = (_proposal_fk(), Index(None, "domain_id", "proposal_id"))
+
+    domain_id: Mapped[DomainKey]
+    id: Mapped[str] = mapped_column(primary_key=True)
+    proposal_id: Mapped[str]
+    reviewer: Mapped[str]
+    verdict: Mapped[ReviewVerdict] = mapped_column(REVIEW_VERDICT)
+    comment: Mapped[str | None]
+    at: Mapped[datetime]
+
+
+class ProposalItem(Base):
+    """One extraction Proposal item: a proposed Record, Attribute value or Link with its
+    evidence, confidence and decision."""
+
+    __tablename__ = "proposal_items"
+    __table_args__ = (
+        _proposal_fk(),
+        CheckConstraint("item_type IN ('record', 'value', 'link')", name="item_type"),
+        Index(None, "domain_id", "proposal_id", "seq"),
+    )
+
+    domain_id: Mapped[DomainKey]
+    proposal_id: Mapped[str] = mapped_column(primary_key=True)
+    item_id: Mapped[str] = mapped_column(primary_key=True)
+    partition: Mapped[str]
+    element_key: Mapped[str]
+    attribute_id: Mapped[str | None]
+    evidence: Mapped[dict[str, Any] | None]
+    confidence: Mapped[float | None] = mapped_column(REAL)
+    decision: Mapped[ItemDecision] = mapped_column(ITEM_DECISION)
+    decided_by: Mapped[str | None]
+    decided_at: Mapped[datetime | None]
+    #: `record` (new Record), `value` (Attribute value of an existing Record) or `link`.
+    item_type: Mapped[str] = mapped_column(server_default=text("'record'"))
+    seq: Mapped[int] = mapped_column(Integer, server_default=text("0"))
+    job_id: Mapped[str | None]
+    #: What the item proposes: Kind and key with values, or Relation and endpoints.
+    subject: Mapped[dict[str, Any]] = mapped_column(server_default=text("'{}'::jsonb"))
+    #: Entity resolution outcome: status, method, candidates.
+    match: Mapped[dict[str, Any] | None]
+    tier: Mapped[int | None] = mapped_column(SmallInteger)
+    model: Mapped[str | None]
+    #: Reviewer edits applied over `subject` values when the item is accepted.
+    edits: Mapped[dict[str, Any] | None]
+    created_at: Mapped[datetime] = mapped_column(server_default=text("now()"))
+
+
+class MergeAttempt(Base):
+    """Stored three-way merge with Conflicts, attached to a Proposal."""
+
+    __tablename__ = "merge_attempts"
+    __table_args__ = (_proposal_fk(), Index(None, "domain_id", "proposal_id"))
+
+    domain_id: Mapped[DomainKey]
+    id: Mapped[str] = mapped_column(primary_key=True)
+    proposal_id: Mapped[str]
+    #: Merge base; null when the heads share no ancestor or the base is virtual (AC-13).
+    base: Mapped[H32 | None]
+    ours: Mapped[H32]
+    theirs: Mapped[H32]
+    status: Mapped[MergeAttemptStatus] = mapped_column(MERGE_ATTEMPT_STATUS)
+    created_at: Mapped[datetime]
+    virtual_base: Mapped[bool] = mapped_column(server_default=text("false"))
+    #: `conflicts`, `merged`, `fast_forward` or `up_to_date`.
+    result: Mapped[str | None]
+    policy: Mapped[dict[str, Any] | None]
+    created_by: Mapped[str | None]
+    #: Automatic resolutions, resolutions that matched no Conflict, Conflict counts.
+    outcome: Mapped[dict[str, Any] | None]
+    #: The Revision the target moved to when the attempt was committed.
+    revision: Mapped[H32 | None]
+    idempotency_key: Mapped[str | None]
+
+
+class Conflict(Base):
+    """One Conflict of a merge attempt, identified by its fingerprint (design 6.10)."""
+
+    __tablename__ = "conflicts"
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["domain_id", "attempt_id"],
+            ["merge_attempts.domain_id", "merge_attempts.id"],
+            ondelete="CASCADE",
+        ),
+        UniqueConstraint("domain_id", "attempt_id", "fingerprint"),
+    )
+
+    domain_id: Mapped[DomainKey]
+    attempt_id: Mapped[str] = mapped_column(primary_key=True)
+    id: Mapped[str] = mapped_column(primary_key=True)
+    code: Mapped[str]
+    fingerprint: Mapped[H32]
+    partition: Mapped[str]
+    element_key: Mapped[str | None]
+    attribute_id: Mapped[str | None]
+    payload: Mapped[dict[str, Any]]
+    member_count: Mapped[int] = mapped_column(Integer)
+    resolution: Mapped[dict[str, Any] | None]
+    resolved_by: Mapped[str | None]
+    resolved_at: Mapped[datetime | None]
+
+
+class ConflictResolution(Base):
+    """Resolution stored by fingerprint so it survives merge attempt recomputation."""
+
+    __tablename__ = "conflict_resolutions"
+    __table_args__ = (_proposal_fk(),)
+
+    domain_id: Mapped[DomainKey]
+    proposal_id: Mapped[str] = mapped_column(primary_key=True)
+    fingerprint: Mapped[H32] = mapped_column(primary_key=True)
+    resolution: Mapped[dict[str, Any]]
+    resolved_by: Mapped[str]
+    at: Mapped[datetime]

lorebase_store/models/queues.py

@@ -0,0 +1,87 @@
+"""Outbox events, their consumers and the job queue (design 7.4, 10.5).
+
+Neither events nor jobs reference `domains`: events and jobs about a Domain outlive its
+deletion.
+
+Each consumer of the outbox keeps its own delivery state: a trigger on `outbox` (revision 0020)
+adds one `outbox_pending` row per registered consumer in the transaction that writes the event,
+and the consumer deletes its row once the event is handed off. An event is pruned only when no
+consumer still has it pending (or when it is older than `store.outbox.max_age_s`).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import BigInteger, ForeignKeyConstraint, Identity, Index, Integer, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from lorebase_store.models.base import Base
+from lorebase_store.models.enums import JOB_STATUS, JobStatus
+
+
+class OutboxEvent(Base):
+    """Event written in the commit transaction and delivered later by Scribe."""
+
+    __tablename__ = "outbox"
+    __table_args__ = (Index(None, "created_at"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, Identity(always=True), primary_key=True)
+    domain_id: Mapped[str]
+    event_type: Mapped[str]
+    payload: Mapped[dict[str, Any]]
+    created_at: Mapped[datetime] = mapped_column(server_default=text("now()"))
+
+
+class OutboxConsumer(Base):
+    """A consumer of the outbox (the webhook worker is `webhooks`); events written after it
+    is registered are pending for it until it hands them off."""
+
+    __tablename__ = "outbox_consumers"
+
+    name: Mapped[str] = mapped_column(primary_key=True)
+    created_at: Mapped[datetime] = mapped_column(server_default=text("now()"))
+
+
+class OutboxPending(Base):
+    """An event one consumer has not handed off yet (its delivery state)."""
+
+    __tablename__ = "outbox_pending"
+    __table_args__ = (
+        ForeignKeyConstraint(["consumer"], ["outbox_consumers.name"], ondelete="CASCADE"),
+        ForeignKeyConstraint(["event_id"], ["outbox.id"], ondelete="CASCADE"),
+        Index(None, "event_id"),
+    )
+
+    consumer: Mapped[str] = mapped_column(primary_key=True)
+    event_id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    domain_id: Mapped[str]
+
+
+class Job(Base):
+    """Background job; workers claim `queued` rows with `FOR UPDATE SKIP LOCKED`."""
+
+    __tablename__ = "jobs"
+    __table_args__ = (
+        Index(
+            "ix_jobs_claimable",
+            text("priority DESC"),
+            "run_after",
+            postgresql_where=text("status = 'queued'"),
+        ),
+        Index(None, "domain_id", "type"),
+    )
+
+    id: Mapped[int] = mapped_column(BigInteger, Identity(always=True), primary_key=True)
+    type: Mapped[str]
+    domain_id: Mapped[str | None]
+    payload: Mapped[dict[str, Any]] = mapped_column(server_default=text("'{}'::jsonb"))
+    status: Mapped[JobStatus] = mapped_column(JOB_STATUS, server_default=text("'queued'"))
+    priority: Mapped[int] = mapped_column(Integer, server_default=text("0"))
+    run_after: Mapped[datetime] = mapped_column(server_default=text("now()"))
+    attempts: Mapped[int] = mapped_column(Integer, server_default=text("0"))
+    locked_by: Mapped[str | None]
+    locked_at: Mapped[datetime | None]
+    result: Mapped[dict[str, Any] | None]
+    created_at: Mapped[datetime] = mapped_column(server_default=text("now()"))

lorebase_store/models/tracing.py

@@ -0,0 +1,116 @@
+"""Agent trace steps (`keeper.trace`): how an agent session navigated the graph.
+
+Debugging data, not compliance: rows are written best effort and pruned after the retention
+period. Never values of Records: the query as the caller sent it (filter literals redacted
+unless configured otherwise), result counts and the refs (Kind and key) a response touched.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import (
+    BigInteger,
+    CheckConstraint,
+    Double,
+    Identity,
+    Index,
+    Integer,
+    Text,
+    UniqueConstraint,
+    text,
+)
+from sqlalchemy.dialects.postgresql import ARRAY
+from sqlalchemy.orm import Mapped, mapped_column
+
+from lorebase_store.models.base import Base
+
+STEP_TYPES = ("call", "note")
+
+
+class AgentTraceStep(Base):
+    """One traced request (`call`) or one note an agent attached to its session (`note`).
+
+    `domain_id` is null for notes and for calls outside a Domain; it has no foreign key, so
+    steps outlive a deleted Domain until the retention period ends.
+    """
+
+    __tablename__ = "agent_trace_steps"
+    __table_args__ = (
+        CheckConstraint("type IN ('call', 'note')", name="type"),
+        Index(None, "actor", "session_id", "seq"),
+        Index(None, "session_id", "seq"),
+        Index(None, "domain_id", "at"),
+        Index(None, "at"),
+        Index(None, "actor", "fingerprint", "at", postgresql_where=text("inferred")),
+    )
+
+    seq: Mapped[int] = mapped_column(BigInteger, Identity(always=True), primary_key=True)
+    session_id: Mapped[str]
+    actor: Mapped[str]
+    principal_type: Mapped[str | None]
+    domain_id: Mapped[str | None]
+    at: Mapped[datetime] = mapped_column(server_default=text("now()"))
+    type: Mapped[str]
+    tool: Mapped[str | None]
+    method: Mapped[str | None]
+    route: Mapped[str | None]
+    status: Mapped[int | None] = mapped_column(Integer)
+    latency_ms: Mapped[float | None] = mapped_column(Double)
+    cache: Mapped[str | None]
+    branch: Mapped[str | None]
+    query: Mapped[dict[str, Any] | None]
+    result: Mapped[dict[str, Any] | None]
+    refs: Mapped[dict[str, Any] | None]
+    explain: Mapped[dict[str, Any] | None]
+    note: Mapped[str | None]
+    proposal_id: Mapped[str | None]
+    request_id: Mapped[str | None]
+    trace_id: Mapped[str | None]
+    inferred: Mapped[bool] = mapped_column(server_default=text("false"))
+    """The session was inferred (no session header): grouped by principal and client
+    fingerprint while requests keep coming within `keeper.trace.inferred_session_idle_s`."""
+    fingerprint: Mapped[str | None]
+    """Digest of the principal, its credential and user agent; set on inferred steps."""
+
+
+class AgentTraceSession(Base):
+    """One session of one actor: the number of steps it holds, which caps it.
+
+    The trace writer raises `steps` in the transaction that writes the steps, under the row
+    lock, and skips the steps past `keeper.trace.max_steps_per_session`; pruning lowers it by
+    the steps it deletes and removes the row once none is left.
+    """
+
+    __tablename__ = "agent_trace_sessions"
+
+    actor: Mapped[str] = mapped_column(primary_key=True)
+    session_id: Mapped[str] = mapped_column(primary_key=True)
+    steps: Mapped[int] = mapped_column(Integer)
+    last_at: Mapped[datetime]
+
+
+class AgentTraceSessionDomain(Base):
+    """Summary of the steps of one session of one actor in one Domain (`domain_id` null: steps
+    outside any Domain), kept by the trace writer and pruning. Sessions are listed from these
+    rows, which visibility filters like steps (by actor and Domain)."""
+
+    __tablename__ = "agent_trace_session_domains"
+    __table_args__ = (
+        UniqueConstraint("actor", "session_id", "domain_id", postgresql_nulls_not_distinct=True),
+        Index(None, "actor", "last_at"),
+        Index(None, "domain_id", "last_at"),
+    )
+
+    id: Mapped[int] = mapped_column(BigInteger, Identity(always=True), primary_key=True)
+    actor: Mapped[str]
+    session_id: Mapped[str]
+    domain_id: Mapped[str | None]
+    started_at: Mapped[datetime]
+    last_at: Mapped[datetime]
+    calls: Mapped[int] = mapped_column(Integer)
+    notes: Mapped[int] = mapped_column(Integer)
+    inferred: Mapped[bool]
+    tools: Mapped[list[str]] = mapped_column(ARRAY(Text))
+    proposals: Mapped[list[str]] = mapped_column(ARRAY(Text))