superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/storage/correction_cases.py

@@ -1,670 +0,0 @@
-"""Review-gated correction-case ledger and atomic temporal lifecycle seam.
-
-The ledger stores identifiers and temporal snapshots only, never raw fact
-text.  A trusted reviewer may apply or roll back a case inside the same SQLite
-transaction that changes the predecessor's temporal lifecycle.
-"""
-
-from __future__ import annotations
-
-import sqlite3
-from dataclasses import dataclass, replace
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Callable, Literal, Mapping
-from uuid import uuid4
-
-from superlocalmemory.storage.write_lock import get_write_lock
-
-_SCOPES = frozenset({"personal", "project", "shared", "global"})
-_STATUSES = frozenset({"proposed", "applied", "rejected", "rolled_back"})
-_EVENTS = frozenset({"proposed", "applied", "rejected", "rolled_back"})
-_MAX_FIELD_LENGTH = 128
-
-
-class CorrectionCaseError(RuntimeError):
-    """Base exception for correction-case lifecycle failures."""
-
-
-class CorrectionAuthorizationError(CorrectionCaseError):
-    """The host/server did not attest the acting identity as trusted."""
-
-
-class CorrectionCompareAndSetError(CorrectionCaseError):
-    """The caller attempted a state transition against a stale case version."""
-
-
-class CorrectionIdempotencyError(CorrectionCaseError):
-    """A replay key names a different correction proposal."""
-
-
-class CorrectionNotFoundError(CorrectionCaseError):
-    """No correction case exists for the requested identifier."""
-
-
-@dataclass(frozen=True, slots=True)
-class CorrectionActor:
-    """Actor provenance supplied by a host-authenticated integration seam."""
-
-    actor_id: str
-    actor_kind: str
-    trust_tier: str
-
-
-@dataclass(frozen=True, slots=True)
-class CorrectionCase:
-    """A fact-identifier-only correction decision and its lifecycle state."""
-
-    case_id: str
-    profile_id: str
-    scope: str
-    predecessor_fact_id: str
-    successor_fact_id: str
-    reason_code: str
-    status: str
-    version: int
-    idempotency_key: str
-    created_at: str
-    updated_at: str
-    reviewed_by_actor_id: str | None
-    reviewed_at: str | None
-    applied_at: str | None
-    system_effective_at: str | None
-    event_valid_from: str | None
-    event_valid_until: str | None
-    predecessor_temporal_existed: bool | None
-    predecessor_valid_from: str | None
-    predecessor_valid_until: str | None
-    predecessor_system_created_at: str | None
-    predecessor_system_expired_at: str | None
-    predecessor_invalidated_by: str | None
-    predecessor_invalidation_reason: str | None
-
-
-class CorrectionCaseStore:
-    """Own correction lifecycle metadata with explicit profile/trust seams.
-
-    ``is_actor_trusted`` must be implemented by the server/host integration.
-    This storage module never invents identity or authorization from an actor
-    string, which keeps unverified clients from self-approving corrections.
-    """
-
-    def __init__(
-        self,
-        path: str | Path,
-        *,
-        is_profile_active: Callable[[str], bool],
-        is_actor_trusted: Callable[[CorrectionActor], bool],
-    ) -> None:
-        self._path = Path(path)
-        self._is_profile_active = is_profile_active
-        self._is_actor_trusted = is_actor_trusted
-
-    @property
-    def path(self) -> str:
-        return str(self._path)
-
-    def propose(
-        self,
-        *,
-        case_id: str,
-        profile_id: str,
-        scope: str,
-        predecessor_fact_id: str,
-        successor_fact_id: str,
-        reason_code: str,
-        actor: CorrectionActor,
-        idempotency_key: str,
-        event_valid_from: str | None = None,
-        event_valid_until: str | None = None,
-    ) -> CorrectionCase:
-        """Record a candidate without changing facts or retrieval behaviour."""
-        with self._transaction() as conn:
-            return propose_on_connection(
-                conn,
-                case_id=case_id,
-                profile_id=profile_id,
-                scope=scope,
-                predecessor_fact_id=predecessor_fact_id,
-                successor_fact_id=successor_fact_id,
-                reason_code=reason_code,
-                actor=actor,
-                idempotency_key=idempotency_key,
-                event_valid_from=event_valid_from,
-                event_valid_until=event_valid_until,
-                is_profile_active=self._is_profile_active,
-                is_actor_trusted=self._is_actor_trusted,
-            )
-
-    def apply(
-        self,
-        case_id: str,
-        *,
-        expected_version: int,
-        actor: CorrectionActor,
-        operation_id: str,
-        event_valid_until: str | None = None,
-    ) -> CorrectionCase:
-        """Atomically approve a case and supersede its scoped predecessor."""
-        return self._transition(
-            case_id, expected_version=expected_version, actor=actor,
-            operation_id=operation_id, from_status="proposed", to_status="applied",
-            mutate_temporal=True,
-            event_valid_until=event_valid_until,
-        )
-
-    def reject(
-        self, case_id: str, *, expected_version: int, actor: CorrectionActor, operation_id: str
-    ) -> CorrectionCase:
-        """Record a reviewed rejection atomically, preserving all history."""
-        return self._transition(
-            case_id, expected_version=expected_version, actor=actor,
-            operation_id=operation_id, from_status="proposed", to_status="rejected",
-        )
-
-    def rollback(
-        self, case_id: str, *, expected_version: int, actor: CorrectionActor, operation_id: str
-    ) -> CorrectionCase:
-        """Atomically restore the predecessor tuple and append a rollback event."""
-        return self._transition(
-            case_id, expected_version=expected_version, actor=actor,
-            operation_id=operation_id, from_status="applied", to_status="rolled_back",
-            mutate_temporal=True,
-        )
-
-    def get_case(self, case_id: str) -> CorrectionCase:
-        """Read one active-profile case without exposing fact text."""
-        _validate_field("case_id", case_id)
-        with self._read_connection() as conn:
-            case = _get_case(conn, case_id)
-        if not self._is_profile_active(case.profile_id):
-            raise CorrectionAuthorizationError("profile is inactive or closing")
-        return case
-
-    def list_cases(self, profile_id: str, *, limit: int = 100) -> list[CorrectionCase]:
-        """List bounded active-profile cases, newest first, identifiers only."""
-        _validate_field("profile_id", profile_id)
-        if not self._is_profile_active(profile_id):
-            raise CorrectionAuthorizationError("profile is inactive or closing")
-        if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 500:
-            raise ValueError("limit must be an integer from 1 to 500")
-        with self._read_connection() as conn:
-            rows = conn.execute(
-                "SELECT * FROM correction_cases WHERE profile_id=? "
-                "ORDER BY updated_at DESC, case_id DESC LIMIT ?",
-                (profile_id, limit),
-            ).fetchall()
-        return [_case_from_row(row) for row in rows]
-
-    def _transition(
-        self,
-        case_id: str,
-        *,
-        expected_version: int,
-        actor: CorrectionActor,
-        operation_id: str,
-        from_status: Literal["proposed", "applied"],
-        to_status: Literal["applied", "rejected", "rolled_back"],
-        mutate_temporal: bool = False,
-        event_valid_until: str | None = None,
-    ) -> CorrectionCase:
-        with self._transaction() as conn:
-            return transition_on_connection(
-                conn,
-                case_id=case_id,
-                expected_version=expected_version,
-                actor=actor,
-                operation_id=operation_id,
-                from_status=from_status,
-                to_status=to_status,
-                mutate_temporal=mutate_temporal,
-                event_valid_until=event_valid_until,
-                is_profile_active=self._is_profile_active,
-                is_actor_trusted=self._is_actor_trusted,
-            )
-
-    def _assert_admitted(self, profile_id: str, actor: CorrectionActor) -> None:
-        if not self._is_profile_active(profile_id):
-            raise CorrectionAuthorizationError("profile is inactive or closing")
-        if not self._is_actor_trusted(actor):
-            raise CorrectionAuthorizationError("actor is not trusted by the host/server")
-
-    def _transaction(self):
-        return _CorrectionTransaction(self._path)
-
-    def _read_connection(self):
-        return _CorrectionReadConnection(self._path)
-
-
-def propose_on_connection(
-    conn: sqlite3.Connection,
-    *,
-    case_id: str,
-    profile_id: str,
-    scope: str,
-    predecessor_fact_id: str,
-    successor_fact_id: str,
-    reason_code: str,
-    actor: CorrectionActor,
-    idempotency_key: str,
-    event_valid_from: str | None = None,
-    event_valid_until: str | None = None,
-    is_profile_active: Callable[[str], bool],
-    is_actor_trusted: Callable[[CorrectionActor], bool],
-) -> CorrectionCase:
-    """Write one candidate through the caller-owned SQLite transaction.
-
-    This function never starts, commits, rolls back, or closes ``conn``. It is
-    the only storage entry point suitable for a canonical writer command or a
-    bound ``DatabaseManager.raw_connection()`` scope.
-    """
-    if not isinstance(conn, sqlite3.Connection):
-        raise TypeError("correction proposal requires a sqlite3 connection")
-    _validate_case_input(
-        case_id, profile_id, scope, predecessor_fact_id, successor_fact_id,
-        reason_code, actor, idempotency_key, event_valid_from, event_valid_until,
-    )
-    if not is_profile_active(profile_id):
-        raise CorrectionAuthorizationError("profile is inactive or closing")
-    if not is_actor_trusted(actor):
-        raise CorrectionAuthorizationError("actor is not trusted by the host/server")
-
-    existing = conn.execute(
-        "SELECT * FROM correction_cases WHERE profile_id=? AND idempotency_key=?",
-        (profile_id, idempotency_key),
-    ).fetchone()
-    if existing is not None:
-        case = _case_from_row(existing)
-        if (
-            case.case_id != case_id
-            or case.scope != scope
-            or case.predecessor_fact_id != predecessor_fact_id
-            or case.successor_fact_id != successor_fact_id
-            or case.reason_code != reason_code
-        ):
-            raise CorrectionIdempotencyError("proposal replay key names different data")
-        return case
-
-    now = _now()
-    conn.execute(
-        "INSERT INTO correction_cases (case_id, profile_id, scope, predecessor_fact_id, "
-        "successor_fact_id, reason_code, status, version, idempotency_key, "
-        "proposed_by_actor_id, proposed_by_actor_kind, proposed_by_trust_tier, created_at, "
-        "updated_at, event_valid_from, event_valid_until) "
-        "VALUES (?, ?, ?, ?, ?, ?, 'proposed', 0, ?, ?, ?, ?, ?, ?, ?, ?)",
-        (
-            case_id, profile_id, scope, predecessor_fact_id, successor_fact_id,
-            reason_code, idempotency_key, actor.actor_id, actor.actor_kind,
-            actor.trust_tier, now, now, event_valid_from, event_valid_until,
-        ),
-    )
-    _append_event(
-        conn, case_id=case_id, profile_id=profile_id, scope=scope,
-        event_type="proposed", operation_id=idempotency_key, actor=actor,
-        expected_version=None, resulting_version=0, occurred_at=now,
-        event_valid_from=event_valid_from, event_valid_until=event_valid_until,
-    )
-    return _get_case(conn, case_id)
-
-
-def transition_on_connection(
-    conn: sqlite3.Connection,
-    *,
-    case_id: str,
-    expected_version: int,
-    actor: CorrectionActor,
-    operation_id: str,
-    from_status: Literal["proposed", "applied"],
-    to_status: Literal["applied", "rejected", "rolled_back"],
-    mutate_temporal: bool,
-    event_valid_until: str | None = None,
-    is_profile_active: Callable[[str], bool],
-    is_actor_trusted: Callable[[CorrectionActor], bool],
-) -> CorrectionCase:
-    """Transition one case in a caller-owned transaction, never nesting it."""
-    _validate_field("case_id", case_id)
-    _validate_field("operation_id", operation_id)
-    if expected_version < 0:
-        raise ValueError("expected_version must be non-negative")
-    _validate_actor(actor)
-    if not is_actor_trusted(actor):
-        raise CorrectionAuthorizationError("actor is not trusted by the host/server")
-    replay = conn.execute(
-        "SELECT event_type FROM correction_events WHERE case_id=? AND operation_id=?",
-        (case_id, operation_id),
-    ).fetchone()
-    if replay is not None:
-        if replay[0] != to_status:
-            raise CorrectionIdempotencyError("operation replay key has another transition")
-        return _get_case(conn, case_id)
-    case = _get_case(conn, case_id)
-    if not is_profile_active(case.profile_id):
-        raise CorrectionAuthorizationError("profile is inactive or closing")
-    if case.status != from_status or case.version != expected_version:
-        raise CorrectionCompareAndSetError("case state changed; reload before review action")
-    if to_status == "rolled_back":
-        dependent = conn.execute(
-            "SELECT 1 FROM correction_cases WHERE profile_id=? "
-            "AND predecessor_fact_id=? AND status IN ('proposed', 'applied') LIMIT 1",
-            (case.profile_id, case.successor_fact_id),
-        ).fetchone()
-        if dependent is not None:
-            raise CorrectionCompareAndSetError(
-                "dependent correction is active; resolve it before rollback"
-            )
-    now = _now()
-    if event_valid_until is not None:
-        if to_status != "applied":
-            raise ValueError("event-valid boundary is permitted only when applying a correction")
-        _validate_timestamp("event_valid_until", event_valid_until)
-        case = replace(case, event_valid_until=event_valid_until)
-    if mutate_temporal:
-        if to_status == "applied":
-            _apply_predecessor_temporal(conn, case, occurred_at=now)
-        else:
-            _restore_predecessor_temporal(conn, case)
-    next_version = case.version + 1
-    cursor = conn.execute(
-        "UPDATE correction_cases SET status=?, version=?, updated_at=?, event_valid_until=?, "
-        "reviewed_by_actor_id=?, reviewed_at=?, applied_at=?, system_effective_at=? "
-        "WHERE case_id=? AND status=? AND version=?",
-        (
-            to_status,
-            next_version,
-            now,
-            case.event_valid_until,
-            actor.actor_id,
-            now,
-            now if to_status == "applied" else case.applied_at,
-            now if to_status == "applied" else case.system_effective_at,
-            case_id,
-            from_status,
-            expected_version,
-        ),
-    )
-    if cursor.rowcount != 1:
-        raise CorrectionCompareAndSetError("case state changed; reload before review action")
-    _append_event(
-        conn,
-        case_id=case.case_id,
-        profile_id=case.profile_id,
-        scope=case.scope,
-        event_type=to_status,
-        operation_id=operation_id,
-        actor=actor,
-        expected_version=expected_version,
-        resulting_version=next_version,
-        occurred_at=now,
-        event_valid_from=case.event_valid_from,
-        event_valid_until=case.event_valid_until,
-    )
-    return _get_case(conn, case_id)
-
-
-def _append_event(
-    conn: sqlite3.Connection,
-    *,
-    case_id: str,
-    profile_id: str,
-    scope: str,
-    event_type: str,
-    operation_id: str,
-    actor: CorrectionActor,
-    expected_version: int | None,
-    resulting_version: int,
-    occurred_at: str,
-    event_valid_from: str | None,
-    event_valid_until: str | None,
-) -> None:
-    conn.execute(
-        "INSERT INTO correction_events (event_id, case_id, profile_id, scope, event_type, "
-        "operation_id, actor_id, actor_kind, actor_trust_tier, expected_version, "
-        "resulting_version, system_occurred_at, event_valid_from, event_valid_until) "
-        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-        (
-            uuid4().hex, case_id, profile_id, scope, event_type, operation_id,
-            actor.actor_id, actor.actor_kind, actor.trust_tier, expected_version,
-            resulting_version, occurred_at, event_valid_from, event_valid_until,
-        ),
-    )
-
-
-def _get_case(conn: sqlite3.Connection, case_id: str) -> CorrectionCase:
-    row = conn.execute("SELECT * FROM correction_cases WHERE case_id=?", (case_id,)).fetchone()
-    if row is None:
-        raise CorrectionNotFoundError("correction case does not exist")
-    return _case_from_row(row)
-
-
-def _apply_predecessor_temporal(
-    conn: sqlite3.Connection, case: CorrectionCase, *, occurred_at: str
-) -> None:
-    """Snapshot and supersede exactly one profile-and-scope-owned predecessor."""
-    rows = conn.execute(
-        "SELECT fact_id, profile_id, scope FROM atomic_facts "
-        "WHERE fact_id IN (?, ?)",
-        (case.predecessor_fact_id, case.successor_fact_id),
-    ).fetchall()
-    facts = {str(row["fact_id"]): row for row in rows}
-    if set(facts) != {case.predecessor_fact_id, case.successor_fact_id}:
-        raise CorrectionNotFoundError("correction facts are no longer available")
-    for row in facts.values():
-        if row["profile_id"] != case.profile_id or row["scope"] != case.scope:
-            raise CorrectionAuthorizationError("correction facts are outside the approved scope")
-
-    prior = conn.execute(
-        "SELECT valid_from, valid_until, system_created_at, system_expired_at, "
-        "invalidated_by, invalidation_reason FROM fact_temporal_validity "
-        "WHERE fact_id=? AND profile_id=?",
-        (case.predecessor_fact_id, case.profile_id),
-    ).fetchone()
-    if prior is None:
-        conn.execute(
-            "UPDATE correction_cases SET predecessor_temporal_existed=0, "
-            "predecessor_valid_from=NULL, predecessor_valid_until=NULL, "
-            "predecessor_system_created_at=NULL, predecessor_system_expired_at=NULL, "
-            "predecessor_invalidated_by=NULL, predecessor_invalidation_reason=NULL "
-            "WHERE case_id=?",
-            (case.case_id,),
-        )
-        conn.execute(
-            "INSERT INTO fact_temporal_validity "
-            "(fact_id, profile_id, system_created_at) VALUES (?, ?, ?)",
-            (case.predecessor_fact_id, case.profile_id, occurred_at),
-        )
-    else:
-        conn.execute(
-            "UPDATE correction_cases SET predecessor_temporal_existed=1, "
-            "predecessor_valid_from=?, predecessor_valid_until=?, "
-            "predecessor_system_created_at=?, predecessor_system_expired_at=?, "
-            "predecessor_invalidated_by=?, predecessor_invalidation_reason=? "
-            "WHERE case_id=?",
-            (*tuple(prior), case.case_id),
-        )
-    conn.execute(
-        "UPDATE fact_temporal_validity SET "
-        "valid_until=COALESCE(?, valid_until), system_expired_at=?, "
-        "invalidated_by=?, invalidation_reason=? WHERE fact_id=? AND profile_id=?",
-        (
-            case.event_valid_until,
-            occurred_at,
-            case.successor_fact_id,
-            case.reason_code,
-            case.predecessor_fact_id,
-            case.profile_id,
-        ),
-    )
-
-
-def _restore_predecessor_temporal(conn: sqlite3.Connection, case: CorrectionCase) -> None:
-    """Restore the snapshot captured at apply; history rows themselves remain."""
-    if case.predecessor_temporal_existed is None:
-        raise CorrectionCaseError("approved case has no predecessor temporal snapshot")
-    if not case.predecessor_temporal_existed:
-        conn.execute(
-            "DELETE FROM fact_temporal_validity WHERE fact_id=? AND profile_id=?",
-            (case.predecessor_fact_id, case.profile_id),
-        )
-        return
-    cursor = conn.execute(
-        "UPDATE fact_temporal_validity SET valid_from=?, valid_until=?, system_created_at=?, "
-        "system_expired_at=?, invalidated_by=?, invalidation_reason=? "
-        "WHERE fact_id=? AND profile_id=?",
-        (
-            case.predecessor_valid_from,
-            case.predecessor_valid_until,
-            case.predecessor_system_created_at,
-            case.predecessor_system_expired_at,
-            case.predecessor_invalidated_by,
-            case.predecessor_invalidation_reason,
-            case.predecessor_fact_id,
-            case.profile_id,
-        ),
-    )
-    if cursor.rowcount != 1:
-        raise CorrectionNotFoundError("predecessor temporal record is no longer available")
-
-
-class _CorrectionTransaction:
-    """Small transaction guard: all case/event writes commit or roll back together."""
-
-    def __init__(self, path: Path) -> None:
-        self._path = path
-        self._conn: sqlite3.Connection | None = None
-        # Standalone lifecycle operations are rare, but must serialize with
-        # DatabaseManager writes just like coordinator-owned operations do.
-        self._lock = get_write_lock(path)
-
-    def __enter__(self) -> sqlite3.Connection:
-        self._lock.acquire()
-        try:
-            conn = sqlite3.connect(str(self._path), timeout=5, isolation_level=None)
-            conn.row_factory = sqlite3.Row
-            conn.execute("PRAGMA journal_mode=WAL")
-            conn.execute("PRAGMA busy_timeout=5000")
-            conn.execute("BEGIN IMMEDIATE")
-            self._conn = conn
-            return conn
-        except Exception:
-            self._lock.release()
-            raise
-
-    def __exit__(self, exc_type, exc, _traceback) -> None:
-        assert self._conn is not None
-        try:
-            self._conn.execute("ROLLBACK" if exc_type is not None else "COMMIT")
-        finally:
-            try:
-                self._conn.close()
-            finally:
-                self._lock.release()
-
-
-class _CorrectionReadConnection:
-    """Small read-only guard kept out of the canonical writer domain."""
-
-    def __init__(self, path: Path) -> None:
-        self._path = path
-        self._conn: sqlite3.Connection | None = None
-
-    def __enter__(self) -> sqlite3.Connection:
-        conn = sqlite3.connect(f"file:{self._path}?mode=ro", uri=True, timeout=0.25)
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA query_only=ON")
-        self._conn = conn
-        return conn
-
-    def __exit__(self, _exc_type, _exc, _traceback) -> None:
-        assert self._conn is not None
-        self._conn.close()
-
-
-def _case_from_row(
-    row: sqlite3.Row | tuple[object, ...] | Mapping[str, object],
-) -> CorrectionCase:
-    if not isinstance(row, sqlite3.Row):
-        columns = (
-            "case_id", "profile_id", "scope", "predecessor_fact_id", "successor_fact_id",
-            "reason_code", "status", "version", "idempotency_key", "proposed_by_actor_id",
-            "proposed_by_actor_kind", "proposed_by_trust_tier", "created_at", "updated_at",
-            "reviewed_by_actor_id", "reviewed_at", "applied_at", "system_effective_at",
-            "event_valid_from", "event_valid_until", "predecessor_temporal_existed",
-            "predecessor_valid_from", "predecessor_valid_until", "predecessor_system_created_at",
-            "predecessor_system_expired_at", "predecessor_invalidated_by",
-            "predecessor_invalidation_reason",
-        )
-        row = dict(zip(columns, row, strict=True))
-    return CorrectionCase(
-        case_id=row["case_id"], profile_id=row["profile_id"], scope=row["scope"],
-        predecessor_fact_id=row["predecessor_fact_id"], successor_fact_id=row["successor_fact_id"],
-        reason_code=row["reason_code"], status=row["status"], version=int(row["version"]),
-        idempotency_key=row["idempotency_key"], created_at=row["created_at"],
-        updated_at=row["updated_at"], reviewed_by_actor_id=row["reviewed_by_actor_id"],
-        reviewed_at=row["reviewed_at"], applied_at=row["applied_at"],
-        system_effective_at=row["system_effective_at"], event_valid_from=row["event_valid_from"],
-        event_valid_until=row["event_valid_until"],
-        predecessor_temporal_existed=(
-            None if row["predecessor_temporal_existed"] is None
-            else bool(row["predecessor_temporal_existed"])
-        ),
-        predecessor_valid_from=row["predecessor_valid_from"],
-        predecessor_valid_until=row["predecessor_valid_until"],
-        predecessor_system_created_at=row["predecessor_system_created_at"],
-        predecessor_system_expired_at=row["predecessor_system_expired_at"],
-        predecessor_invalidated_by=row["predecessor_invalidated_by"],
-        predecessor_invalidation_reason=row["predecessor_invalidation_reason"],
-    )
-
-
-def _validate_case_input(
-    case_id: str, profile_id: str, scope: str, predecessor_fact_id: str, successor_fact_id: str,
-    reason_code: str, actor: CorrectionActor, idempotency_key: str,
-    event_valid_from: str | None, event_valid_until: str | None,
-) -> None:
-    for name, value in (
-        ("case_id", case_id),
-        ("profile_id", profile_id),
-        ("predecessor_fact_id", predecessor_fact_id),
-        ("successor_fact_id", successor_fact_id), ("reason_code", reason_code),
-        ("idempotency_key", idempotency_key),
-    ):
-        _validate_field(name, value)
-    if predecessor_fact_id == successor_fact_id:
-        raise ValueError("predecessor and successor facts must differ")
-    if scope not in _SCOPES:
-        raise ValueError("scope is unsupported")
-    _validate_actor(actor)
-    _validate_timestamp("event_valid_from", event_valid_from)
-    _validate_timestamp("event_valid_until", event_valid_until)
-    if event_valid_from and event_valid_until and event_valid_from >= event_valid_until:
-        raise ValueError("event-valid interval must be ordered")
-
-
-def _validate_actor(actor: CorrectionActor) -> None:
-    for name, value in (
-        ("actor_id", actor.actor_id), ("actor_kind", actor.actor_kind),
-        ("trust_tier", actor.trust_tier),
-    ):
-        _validate_field(name, value)
-
-
-def _validate_field(name: str, value: str) -> None:
-    if not isinstance(value, str) or not value or len(value.encode("utf-8")) > _MAX_FIELD_LENGTH:
-        raise ValueError(f"{name} must be a non-empty bounded identifier")
-    if any(ch.isspace() for ch in value) or "\x00" in value:
-        raise ValueError(f"{name} must be a safe identifier")
-
-
-def _validate_timestamp(name: str, value: str | None) -> None:
-    if value is None:
-        return
-    if not isinstance(value, str):
-        raise ValueError(f"{name} must be an RFC3339 timestamp")
-    try:
-        datetime.fromisoformat(value.replace("Z", "+00:00"))
-    except ValueError as exc:
-        raise ValueError(f"{name} must be an RFC3339 timestamp") from exc
-
-
-def _now() -> str:
-    return datetime.now(timezone.utc).isoformat()