cc-transcript 10.6.0__tar.gz → 10.7.0__tar.gz

{cc_transcript-10.6.0 → cc_transcript-10.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-transcript
-Version: 10.6.0
+Version: 10.7.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers

{cc_transcript-10.6.0 → cc_transcript-10.7.0}/cc_transcript/__init__.py

@@ -83,6 +83,7 @@ EXPORTS: dict[str, str] = {
             "Plugin",
             "PrintMessage",
             "PrintResult",
+            "Question",
             "ServerToolUse",
             "SystemEvent",
             "TextBlock",
@@ -522,6 +523,9 @@ if TYPE_CHECKING:
     from cc_transcript.models import (
         PrintResult as PrintResult,
     )
+    from cc_transcript.models import (
+        Question as Question,
+    )
     from cc_transcript.models import (
         ServerToolUse as ServerToolUse,
     )

{cc_transcript-10.6.0 → cc_transcript-10.7.0}/cc_transcript/_parser_rs.pyi

@@ -35,6 +35,9 @@ def lexicon_has_hit(text: str, floor: int, want_negative: bool, /) -> bool:
 def lexicon_overrides() -> list[tuple[str, int]]:
     """The embedded domain-override entries (for the single-source drift guard)."""
 
+def embedded_literals() -> dict[str, str | float | list[str]]:
+    """The generated protocol, mining, and command literals keyed ``module.NAME`` (for the single-source drift guard)."""
+
 def score_short_circuit(spec_json: str, buckets: list[list[str]], /) -> list[int | None]:
     """Per bucket, the first short-circuit stage's score over its user texts, else None."""
 

{cc_transcript-10.6.0 → cc_transcript-10.7.0}/cc_transcript/corrections.py

@@ -19,8 +19,9 @@ from __future__ import annotations
 import json
 import sqlite3
 from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING, Literal, Self
+from typing import TYPE_CHECKING, Literal
+
+from cc_transcript.ledger import SyncLedger
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -57,12 +58,6 @@ CREATE INDEX IF NOT EXISTS idx_corrections_incorrect_digest ON corrections (inco
 
 Origin = Literal["session", "git", "review"]
 
-CORRECTION_COLUMNS = (
-    "ts_ms, session_id, source, anchor_uuid, incorrect_digest, incorrect_file, incorrect_old, "
-    "incorrect_new, correction_origin, correction_file, correction_old, correction_new, "
-    "correction_commit, correction_text, overlap, detail_json"
-)
-
 
 @dataclass(frozen=True, slots=True)
 class Correction:
@@ -111,7 +106,7 @@ class Correction:
     detail: Mapping[str, Any] = field(default_factory=dict)
 
 
-class CorrectionLog:
+class CorrectionLog(SyncLedger[Correction]):
     """The ``corrections`` ledger at ``~/.cc-transcript/corrections.db``.
 
     Opened in WAL mode with a busy timeout because writers across the family
@@ -124,66 +119,46 @@ class CorrectionLog:
         >>> log.by_digest(session_id, incorrect_digest=digest)
     """
 
-    def __init__(self, conn: sqlite3.Connection) -> None:
-        self.conn = conn
-
-    @classmethod
-    def open(cls, path: Path | None = None) -> Self:
-        """Opens (creating if needed) the ledger at ``path``.
-
-        Args:
-            path: The database file path; its parents are created if absent.
-                Defaults to ``~/.cc-transcript/corrections.db``.
-
-        Returns:
-            The opened log.
-        """
-        path = path or Path.home() / ".cc-transcript" / "corrections.db"
-        path.parent.mkdir(parents=True, exist_ok=True)
-        conn = sqlite3.connect(path, autocommit=True)
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA journal_mode = WAL")
-        conn.execute("PRAGMA busy_timeout = 2000")
-        conn.executescript(CORRECTIONS_DDL)
-        return cls(conn)
-
-    def append(self, correction: Correction) -> None:
-        """Appends ``correction`` as a single ``INSERT OR IGNORE``.
-
-        Idempotent on the UNIQUE key ``(session_id, anchor_uuid,
-        incorrect_digest)`` — re-harvesting the same edit, across reruns or
-        across the pairs of one event, writes one row.
-        """
-        self.conn.execute(
-            f"INSERT OR IGNORE INTO corrections ({CORRECTION_COLUMNS}) "
-            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-            (
-                correction.ts_ms,
-                correction.session_id,
-                correction.source,
-                correction.anchor_uuid,
-                correction.incorrect_digest,
-                correction.incorrect_file,
-                correction.incorrect_old,
-                correction.incorrect_new,
-                correction.correction_origin,
-                correction.correction_file,
-                correction.correction_old,
-                correction.correction_new,
-                correction.correction_commit,
-                correction.correction_text,
-                correction.overlap,
-                json.dumps(dict(correction.detail)),
-            ),
-        )
+    DDL = CORRECTIONS_DDL
+    FILENAME = "corrections.db"
+    TABLE = "corrections"
+    COLUMNS = (
+        "ts_ms",
+        "session_id",
+        "source",
+        "anchor_uuid",
+        "incorrect_digest",
+        "incorrect_file",
+        "incorrect_old",
+        "incorrect_new",
+        "correction_origin",
+        "correction_file",
+        "correction_old",
+        "correction_new",
+        "correction_commit",
+        "correction_text",
+        "overlap",
+        "detail_json",
+    )
 
-    def for_session(self, session_id: SessionId) -> tuple[Correction, ...]:
-        """All corrections for ``session_id``, ordered by timestamp."""
-        return tuple(
-            correction_of(row)
-            for row in self.conn.execute(
-                "SELECT * FROM corrections WHERE session_id = ? ORDER BY ts_ms, id", (session_id,)
-            )
+    def row_to_record(self, row: sqlite3.Row) -> Correction:
+        return Correction(
+            ts_ms=row["ts_ms"],
+            session_id=row["session_id"],
+            source=row["source"],
+            anchor_uuid=row["anchor_uuid"],
+            incorrect_digest=row["incorrect_digest"],
+            incorrect_file=row["incorrect_file"],
+            incorrect_old=row["incorrect_old"],
+            incorrect_new=row["incorrect_new"],
+            correction_origin=row["correction_origin"],
+            correction_file=row["correction_file"],
+            correction_old=row["correction_old"],
+            correction_new=row["correction_new"],
+            correction_commit=row["correction_commit"],
+            correction_text=row["correction_text"],
+            overlap=row["overlap"],
+            detail=json.loads(row["detail_json"]),
         )
 
     def for_repo(self, repo: str) -> tuple[Correction, ...]:
@@ -193,7 +168,7 @@ class CorrectionLog:
         captain-hook reviewer) can pull every correction for its repo at once.
         """
         return tuple(
-            correction_of(row)
+            self.row_to_record(row)
             for row in self.conn.execute(
                 "SELECT * FROM corrections WHERE json_extract(detail_json, '$.repo') = ? ORDER BY ts_ms, id",
                 (repo,),
@@ -212,12 +187,12 @@ class CorrectionLog:
             rows = self.conn.execute(
                 "SELECT * FROM corrections WHERE ts_ms > ? AND source = ? ORDER BY ts_ms, id", (ts_ms, source)
             )
-        return tuple(correction_of(row) for row in rows)
+        return tuple(self.row_to_record(row) for row in rows)
 
     def for_anchor(self, session_id: SessionId, anchor_uuid: EventUuid) -> tuple[Correction, ...]:
         """The corrections harvested around one feedback ``anchor_uuid``."""
         return tuple(
-            correction_of(row)
+            self.row_to_record(row)
             for row in self.conn.execute(
                 "SELECT * FROM corrections WHERE session_id = ? AND anchor_uuid = ? ORDER BY ts_ms, id",
                 (session_id, anchor_uuid),
@@ -232,30 +207,9 @@ class CorrectionLog:
         corrected.
         """
         return tuple(
-            correction_of(row)
+            self.row_to_record(row)
             for row in self.conn.execute(
                 "SELECT * FROM corrections WHERE session_id = ? AND incorrect_digest = ? ORDER BY ts_ms, id",
                 (session_id, incorrect_digest),
             )
         )
-
-
-def correction_of(row: sqlite3.Row) -> Correction:
-    return Correction(
-        ts_ms=row["ts_ms"],
-        session_id=row["session_id"],
-        source=row["source"],
-        anchor_uuid=row["anchor_uuid"],
-        incorrect_digest=row["incorrect_digest"],
-        incorrect_file=row["incorrect_file"],
-        incorrect_old=row["incorrect_old"],
-        incorrect_new=row["incorrect_new"],
-        correction_origin=row["correction_origin"],
-        correction_file=row["correction_file"],
-        correction_old=row["correction_old"],
-        correction_new=row["correction_new"],
-        correction_commit=row["correction_commit"],
-        correction_text=row["correction_text"],
-        overlap=row["overlap"],
-        detail=json.loads(row["detail_json"]),
-    )

{cc_transcript-10.6.0 → cc_transcript-10.7.0}/cc_transcript/decisions.py

@@ -12,8 +12,9 @@ from __future__ import annotations
 import json
 import sqlite3
 from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING, Literal, Self
+from typing import TYPE_CHECKING, Literal
+
+from cc_transcript.ledger import SyncLedger
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -48,11 +49,6 @@ CREATE INDEX IF NOT EXISTS idx_decisions_source_file ON decisions (source_file);
 
 Action = Literal["allow", "block", "warn", "nudge", "note"]
 
-DECISION_COLUMNS = (
-    "ts_ms, session_id, source, kind, source_file, event, action, "
-    "tool_name, tool_digest, event_uuid, message, detail_json"
-)
-
 
 @dataclass(frozen=True, slots=True)
 class Decision:
@@ -91,7 +87,7 @@ class Decision:
     detail: Mapping[str, Any] = field(default_factory=dict)
 
 
-class DecisionLog:
+class DecisionLog(SyncLedger[Decision]):
     """The ``decisions`` ledger at ``~/.cc-transcript/decisions.db``.
 
     Opened in WAL mode with a busy timeout because cc-review's Go daemon
@@ -104,62 +100,38 @@ class DecisionLog:
         >>> log.attribute_tool(session_id, tool_digest=digest, near_ts_ms=ts)
     """
 
-    def __init__(self, conn: sqlite3.Connection) -> None:
-        self.conn = conn
-
-    @classmethod
-    def open(cls, path: Path | None = None) -> Self:
-        """Opens (creating if needed) the ledger at ``path``.
-
-        Args:
-            path: The database file path; its parents are created if absent.
-                Defaults to ``~/.cc-transcript/decisions.db``.
-
-        Returns:
-            The opened log.
-        """
-        path = path or Path.home() / ".cc-transcript" / "decisions.db"
-        path.parent.mkdir(parents=True, exist_ok=True)
-        conn = sqlite3.connect(path, autocommit=True)
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA journal_mode = WAL")
-        conn.execute("PRAGMA busy_timeout = 2000")
-        conn.executescript(DECISIONS_DDL)
-        return cls(conn)
-
-    def append(self, decision: Decision) -> None:
-        """Appends ``decision`` as a single ``INSERT OR IGNORE``.
-
-        Idempotent on the UNIQUE key ``(session_id, ts_ms, source, kind,
-        tool_digest)`` when ``tool_digest`` is present; SQLite treats NULL
-        digests as distinct, so digestless rows rely on the writer not
-        re-running the same integer-ms timestamp.
-        """
-        self.conn.execute(
-            f"INSERT OR IGNORE INTO decisions ({DECISION_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-            (
-                decision.ts_ms,
-                decision.session_id,
-                decision.source,
-                decision.kind,
-                decision.source_file,
-                decision.event,
-                decision.action,
-                decision.tool_name,
-                decision.tool_digest,
-                decision.event_uuid,
-                decision.message,
-                json.dumps(dict(decision.detail)),
-            ),
-        )
+    DDL = DECISIONS_DDL
+    FILENAME = "decisions.db"
+    TABLE = "decisions"
+    COLUMNS = (
+        "ts_ms",
+        "session_id",
+        "source",
+        "kind",
+        "source_file",
+        "event",
+        "action",
+        "tool_name",
+        "tool_digest",
+        "event_uuid",
+        "message",
+        "detail_json",
+    )
 
-    def for_session(self, session_id: SessionId) -> tuple[Decision, ...]:
-        """All decisions for ``session_id``, ordered by timestamp."""
-        return tuple(
-            decision_of(row)
-            for row in self.conn.execute(
-                "SELECT * FROM decisions WHERE session_id = ? ORDER BY ts_ms, id", (session_id,)
-            )
+    def row_to_record(self, row: sqlite3.Row) -> Decision:
+        return Decision(
+            ts_ms=row["ts_ms"],
+            session_id=row["session_id"],
+            source=row["source"],
+            kind=row["kind"],
+            source_file=row["source_file"],
+            event=row["event"],
+            action=row["action"],
+            tool_name=row["tool_name"],
+            tool_digest=row["tool_digest"],
+            event_uuid=row["event_uuid"],
+            message=row["message"],
+            detail=json.loads(row["detail_json"]),
         )
 
     def attribute_tool(
@@ -181,7 +153,7 @@ class DecisionLog:
             " ORDER BY ts_ms DESC, id DESC LIMIT 1",
             (session_id, tool_digest, near_ts_ms - window_ms, near_ts_ms),
         ).fetchone()
-        return decision_of(row) if row else None
+        return self.row_to_record(row) if row else None
 
     def attribute_nearest(
         self,
@@ -209,21 +181,4 @@ class DecisionLog:
             " ORDER BY ABS(ts_ms - ?), id DESC LIMIT 1",
             (session_id, event, *kind_params, near_ts_ms - window_ms, near_ts_ms + window_ms, near_ts_ms),
         ).fetchone()
-        return decision_of(row) if row else None
-
-
-def decision_of(row: sqlite3.Row) -> Decision:
-    return Decision(
-        ts_ms=row["ts_ms"],
-        session_id=row["session_id"],
-        source=row["source"],
-        kind=row["kind"],
-        source_file=row["source_file"],
-        event=row["event"],
-        action=row["action"],
-        tool_name=row["tool_name"],
-        tool_digest=row["tool_digest"],
-        event_uuid=row["event_uuid"],
-        message=row["message"],
-        detail=json.loads(row["detail_json"]),
-    )
+        return self.row_to_record(row) if row else None

{cc_transcript-10.6.0 → cc_transcript-10.7.0}/cc_transcript/filterspec.py

@@ -43,7 +43,7 @@ TRAILING_PUNCT = ".!?…,;:"
 STRUCTURAL_TAG_GROUP: tuple[str, str] = (
     "xml_tags",
     r"<(?:system[_-](?:instruction|reminder)"
-    r"|local-command-(?:stdout|caveat)"
+    r"|local-command-(?:stdout|stderr|caveat)"
     r"|command-(?:name|message|args)"
     r"|task-notification"
     r"|persisted-output"
@@ -59,33 +59,31 @@ STRUCTURAL_GROUPS: tuple[tuple[str, str], ...] = (
     ("hash_banner", r"(?:###\s+[\w][\w \-]{0,30}\s+){3,}###"),
 )
 
-# Agent-injected banners (teammate messages, scheduled tasks, foreign agents). Start-anchored
-# so a mid-text mention is not a banner; the follower class replaces \b and Reminder's "i" is
-# ASCII-pinned via (?-i:[Ii]) so Rust regex and Python re stay in parity across combining marks
-# and dotted/dotless-I folding. Mirror any change in rust/src/protocol.rs AGENT_INJECTION_PATTERN.
+# Start-anchored so a mid-text mention is not a banner.
+# Dialect-hardened for Rust-regex parity — see cc-notes doc "rust-regex-dialect-parity".
 AGENT_INJECTION_GROUPS: tuple[tuple[str, str], ...] = (
     ("xml_tags_extra", r"\A\s*<(?:teammate-message|scheduled-task)(?:[\s/>]|$)"),
     ("augment_agent", r"\A\s*# Augment Agent(?:\s|$)"),
     ("role_reminder", r"\A\s*\[Role Rem(?-i:[Ii])nder(?:[\s:\]]|$)"),
 )
 
-INTERRUPT_MARKER_GROUPS: tuple[tuple[str, str], ...] = (("interrupt", r"^\s*\[Request interrupted by user"),)
+# The leading "i" of "interrupted" is ASCII-pinned (?-i:[Ii]) so Python re.IGNORECASE
+# doesn't fold the dotted/dotless-I forms (U+0130/U+0131) that Rust regex never matches.
+# Dialect-hardened for Rust-regex parity — see cc-notes doc "rust-regex-dialect-parity".
+INTERRUPT_MARKER_GROUPS: tuple[tuple[str, str], ...] = (
+    ("interrupt", r"^\s*\[Request (?-i:[Ii])nterrupted by user"),
+)
 STOP_HOOK_GROUPS: tuple[tuple[str, str], ...] = (("stop_hook", r"Stop hook feedback:"),)
 
-# Raw CC-injected protocol strings carried in tool-result content: the denial banner
-# and the markers that wrap the user's verbatim instruction in a rejected tool use,
-# and the banner pair that wraps an answered AskUserQuestion round.
+# Raw CC-injected protocol strings carried in tool-result content, not user-authored text.
 DENIAL_PREFIX = "The user doesn't want to proceed with this tool use. The tool use was rejected"
 USER_SAID_MARKER = "To tell you how to proceed, the user said:\n"
 USER_SAID_TRAILER = "Note: The user's next message"
 ANSWERED_PREFIX = "Your questions have been answered: "
 ANSWERED_TRAILER = ". You can now continue with these answers in mind."
 
-# Approve-and-advance directives: a user telling the agent to proceed/commit/push or
-# to resume killed work. They follow an assistant turn but advance it rather than
-# correcting it — the opposite of pushback — so a pushback consumer drops them. The
-# approve-and-advance arm is start-anchored so a mid-sentence "commit"/"push" inside
-# a real correction never matches; only the resume arm searches anywhere.
+# Approve-and-advance directives advance the prior assistant turn rather than correct it — the opposite of
+# pushback — so pushback consumers drop them; start-anchoring keeps a mid-correction "commit"/"push" from matching.
 CONTINUATION_GROUPS: tuple[tuple[str, str], ...] = (
     (
         "continuation",
@@ -98,12 +96,12 @@ CONTINUATION_GROUPS: tuple[tuple[str, str], ...] = (
 )
 
 # Bash-mode (`!`) command echoes recorded as user turns — the command line and its
-# captured stdout/stderr, not authored feedback.
-COMMAND_ECHO_GROUPS: tuple[tuple[str, str], ...] = (("command_echo", r"<bash-(?:input|stdout|stderr)\b"),)
+# captured stdout/stderr, not authored feedback. Start-anchored (\A\s*) so a mid-text
+# mention of a bash tag is authored prose, not an echo — a real echo begins with the tag.
+# Dialect-hardened for Rust-regex parity — see cc-notes doc "rust-regex-dialect-parity".
+COMMAND_ECHO_GROUPS: tuple[tuple[str, str], ...] = (("command_echo", r"\A\s*<bash-(?:input|stdout|stderr)\b"),)
 
-# Named junk categories a consumer composes via ``drop_junk(...)``. Interrupt and
-# stop-hook are kept separate because they carry pushback and must never be folded
-# into the structural-noise default.
+# Interrupt and stop-hook stay separate categories: they carry pushback and must never fold into structural noise.
 JUNK_CATEGORIES: dict[str, tuple[tuple[str, str], ...]] = {
     "structural": STRUCTURAL_GROUPS,
     "agent_injection": AGENT_INJECTION_GROUPS,
@@ -113,13 +111,13 @@ JUNK_CATEGORIES: dict[str, tuple[tuple[str, str], ...]] = {
     "command_echo": COMMAND_ECHO_GROUPS,
 }
 
-# The superset of structural noise (structural ∪ agent-injection), WITHOUT
-# interrupt/stop-hook — those carry pushback and must never live here.
+# Structural ∪ agent-injection, WITHOUT interrupt/stop-hook — those carry pushback and must never live here.
 STRUCTURAL_NOISE_GROUPS: tuple[tuple[str, str], ...] = STRUCTURAL_GROUPS + AGENT_INJECTION_GROUPS
 
-# The sentiment junk set: structural (narrow) + interrupt + stop-hook. This
-# reproduces the historical monolithic JUNK_USER_MESSAGE_RE behavior.
-SENTIMENT_JUNK_GROUPS: tuple[tuple[str, str], ...] = STRUCTURAL_GROUPS + INTERRUPT_MARKER_GROUPS + STOP_HOOK_GROUPS
+# The historical monolithic JUNK_USER_MESSAGE_RE plus bash-mode command echoes.
+SENTIMENT_JUNK_GROUPS: tuple[tuple[str, str], ...] = (
+    STRUCTURAL_GROUPS + INTERRUPT_MARKER_GROUPS + STOP_HOOK_GROUPS + COMMAND_ECHO_GROUPS
+)
 
 FRUSTRATION_GROUPS: tuple[tuple[str, str], ...] = (
     (
@@ -351,9 +349,14 @@ class FilterSpec:
     clauses: tuple[Clause, ...]
 
 
+def group_pattern(groups: tuple[tuple[str, str], ...]) -> str:
+    """Composes named regex groups into one non-capturing alternation."""
+    return "|".join(f"(?:{pattern})" for _, pattern in groups)
+
+
 @cache
-def compile_groups(groups: tuple[tuple[str, str], ...], ignore_case: bool) -> re.Pattern[str]:
-    return re.compile("|".join(f"(?:{pattern})" for _, pattern in groups), re.IGNORECASE if ignore_case else 0)
+def compile_groups(groups: tuple[tuple[str, str], ...], ignore_case: bool, *, multiline: bool = False) -> re.Pattern[str]:
+    return re.compile(group_pattern(groups), (re.IGNORECASE if ignore_case else 0) | (re.MULTILINE if multiline else 0))
 
 
 def event_kind(event: TranscriptEvent) -> EventKind:

cc_transcript-10.7.0/cc_transcript/ledger.py

@@ -0,0 +1,87 @@
+"""The append-only SQLite base shared by the correction and decision ledgers.
+
+Both family ledgers are one durable, WAL-mode, ``INSERT OR IGNORE`` table behind
+a fixed schema, so :class:`SyncLedger` owns the connection, the ``open`` plumbing,
+and the schema-driven append and read — each ledger supplies only its DDL,
+filename, table, columns, and row mapper.
+
+Import-light by contract, like :mod:`cc_transcript.ids`: the standard library
+plus identity primitives only, so a hook reading a ledger pays nothing for the
+parser.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar, Protocol, Self
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from typing import Any
+
+    from cc_transcript.ids import SessionId
+
+
+class LedgerRecord(Protocol):
+    detail: Mapping[str, Any]
+
+
+class SyncLedger[R: LedgerRecord](ABC):
+    DDL: ClassVar[str]
+    FILENAME: ClassVar[str]
+    TABLE: ClassVar[str]
+    COLUMNS: ClassVar[tuple[str, ...]]
+
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self.conn = conn
+
+    @abstractmethod
+    def row_to_record(self, row: sqlite3.Row) -> R: ...
+
+    @classmethod
+    def open(cls, path: Path | None = None) -> Self:
+        """Opens (creating if needed) the ledger at ``path``.
+
+        Args:
+            path: The database file path; its parents are created if absent.
+                Defaults to the ledger's file under ``~/.cc-transcript``.
+
+        Returns:
+            The opened log.
+        """
+        path = path or Path.home() / ".cc-transcript" / cls.FILENAME
+        path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(path, autocommit=True)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode = WAL")
+        conn.execute("PRAGMA busy_timeout = 2000")
+        conn.executescript(cls.DDL)
+        return cls(conn)
+
+    def append(self, record: R) -> None:
+        """Appends ``record`` as a single ``INSERT OR IGNORE``.
+
+        Idempotent on the table's UNIQUE key, so re-running a writer writes one
+        row; SQLite treats NULL key columns as distinct, so rows whose key
+        carries a NULL rely on the writer not repeating the same values.
+        """
+        self.conn.execute(
+            f"INSERT OR IGNORE INTO {self.TABLE} ({', '.join(self.COLUMNS)}) "
+            f"VALUES ({', '.join(['?'] * len(self.COLUMNS))})",
+            tuple(
+                json.dumps(dict(record.detail)) if column == "detail_json" else getattr(record, column)
+                for column in self.COLUMNS
+            ),
+        )
+
+    def for_session(self, session_id: SessionId) -> tuple[R, ...]:
+        """All records for ``session_id``, ordered by timestamp."""
+        return tuple(
+            self.row_to_record(row)
+            for row in self.conn.execute(
+                f"SELECT * FROM {self.TABLE} WHERE session_id = ? ORDER BY ts_ms, id", (session_id,)
+            )
+        )