terp-cap-sync 0.1.0__tar.gz

terp_cap_sync-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_sync-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: terp-cap-sync
+Version: 0.1.0
+Summary: Terp sync capability — reconcile a local entity against an external system on the jobs/scheduler seam.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-core==0.1.0

terp_cap_sync-0.1.0/escape-hatch-budget.json

@@ -0,0 +1,5 @@
+{
+  "arch-allow-mutations-emit-audit": 2,
+  "arch-allow-no-internal-imports": 1,
+  "arch-allow-table-models-use-base-table": 1
+}

terp_cap_sync-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-sync"
+version = "0.1.0"
+description = "Terp sync capability — reconcile a local entity against an external system on the jobs/scheduler seam."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+]
+
+# A LIBRARY capability (like terp-cap-identity): it owns tables + a mountable read router +
+# the reconcile engine, but declares NO `terp.capabilities` auto-discovery entry point. A
+# sync does nothing until an app registers a concrete SyncSource, so the app opts in
+# explicitly — it includes the exported `module` in its create_app(specs=[...]) and calls
+# register_sync_source(...). Auto-mounting it in an app with no SyncSource would only expose
+# hollow endpoints, so discovery is deliberately explicit.
+
+# Owns the `sync_mapping` / `sync_run` / append-only `sync_record_log` tables, so it ships an
+# independent, linear Alembic history (its own `alembic_version_sync` table). `terp migrate`
+# discovers this via the `terp.migrations` group (ADR 0027).
+[project.entry-points."terp.migrations"]
+sync = "terp.capabilities.sync"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.sync`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/sync"]

terp_cap_sync-0.1.0/src/terp/capabilities/sync/__init__.py

@@ -0,0 +1,109 @@
+"""terp.capabilities.sync — reconcile a local entity against an external system.
+
+The headline *consumer* capability of the async design (§14): a maintained, secure-by-default
+sync built **only** on the shipped ports — the jobs seam (:func:`terp.core.enqueue` + a typed
+:class:`~terp.core.JobDefinition`), the durable outbox (retry / dead-letter), and the scheduler
+seam (:class:`~terp.core.ScheduleDefinition`). It adds no engine and changes no ``terp.core``.
+
+* An app implements one :class:`SyncSource` per entity type (``pull`` reads System B; ``apply``
+  upserts the local row through an audited ``BaseService``) and registers it with
+  :func:`register_sync_source` at composition time.
+* It mounts the explicit :data:`module` (a *library* cap — no auto-discovery, since a sync does
+  nothing without a source) and declares a schedule via :func:`sync_pull_schedule`.
+* On each tick :data:`SYNC_PULL` runs in a worker: :class:`SyncService` opens a
+  :class:`SyncRun`, reconciles each remote record against the :class:`SyncMapping` ledger
+  (create / update / unchanged — **at-least-once + idempotent**), appends an immutable
+  :class:`SyncRecordLog` line per record, and closes the run with its counts + cursor. The
+  admin-only router exposes runs, logs, and mappings read-only.
+
+It depends only on ``terp-core`` — never a sibling capability or a broker engine; the app
+composes the durable ``OutboxJobQueue`` (and any broker/scheduler adapter) at ``create_app``.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.sync.jobs import SYNC_PULL, SYNC_PUSH, SyncJobPayload
+from terp.capabilities.sync.models import (
+    ACTION_CREATED,
+    ACTION_FAILED,
+    ACTION_UNCHANGED,
+    ACTION_UPDATED,
+    STATUS_FAILED,
+    STATUS_RUNNING,
+    STATUS_SUCCEEDED,
+    STATUS_SYNCED,
+    SyncMapping,
+    SyncRecordLog,
+    SyncRun,
+)
+from terp.capabilities.sync.remote import (
+    RemotePage,
+    RemoteRecord,
+    SyncError,
+    SyncSource,
+    register_sync_source,
+    registered_sync_sources,
+    reset_sync_sources,
+    resolve_sync_source,
+)
+from terp.capabilities.sync.router import module, router
+from terp.capabilities.sync.schedule import sync_pull_schedule, sync_push_schedule
+from terp.capabilities.sync.schemas import (
+  SyncMappingDraft,
+    SyncMappingRead,
+    SyncMappingUpdate,
+    SyncRecordLogRead,
+  SyncRunDraft,
+    SyncRunRead,
+    SyncRunUpdate,
+)
+from terp.capabilities.sync.service import (
+    SyncService,
+    get_run,
+    list_mappings,
+    list_record_logs,
+    list_runs,
+)
+from terp.capabilities.sync.store import record_sync_log
+
+__all__ = [
+    "ACTION_CREATED",
+    "ACTION_FAILED",
+    "ACTION_UNCHANGED",
+    "ACTION_UPDATED",
+    "STATUS_FAILED",
+    "STATUS_RUNNING",
+    "STATUS_SUCCEEDED",
+    "STATUS_SYNCED",
+    "SYNC_PULL",
+    "SYNC_PUSH",
+    "RemotePage",
+    "RemoteRecord",
+    "SyncError",
+    "SyncJobPayload",
+    "SyncMapping",
+    "SyncMappingDraft",
+    "SyncMappingRead",
+    "SyncMappingUpdate",
+    "SyncRecordLog",
+    "SyncRecordLogRead",
+    "SyncRun",
+    "SyncRunDraft",
+    "SyncRunRead",
+    "SyncRunUpdate",
+    "SyncService",
+    "SyncSource",
+    "get_run",
+    "list_mappings",
+    "list_record_logs",
+    "list_runs",
+    "module",
+    "record_sync_log",
+    "register_sync_source",
+    "registered_sync_sources",
+    "reset_sync_sources",
+    "resolve_sync_source",
+    "router",
+    "sync_pull_schedule",
+    "sync_push_schedule",
+]

terp_cap_sync-0.1.0/src/terp/capabilities/sync/jobs.py

@@ -0,0 +1,70 @@
+"""The sync jobs: ``SYNC_PULL`` (reconcile in ← System B) and ``SYNC_PUSH`` (push out → System B).
+
+Both are typed :class:`~terp.core.JobDefinition` catalog constants the ``sync`` module declares
+(``ModuleSpec.jobs``), so mounting the module registers them — an app then triggers them on the
+scheduler seam or by hand (``terp jobs run sync.pull ...``). The handler runs in a **worker,
+post-commit**: it resolves the registered :class:`~terp.capabilities.sync.remote.SyncSource` by
+``entity_type`` (a name crosses the wire, never a closure) and drives the audited reconcile. The
+external System-B read lives here in the handler — never in an ``_after_write`` hook (the
+dual-write hazard the design forbids).
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlmodel import Field
+
+from terp.core import BaseSchema, JobContext, JobDefinition
+
+from terp.capabilities.sync.remote import resolve_sync_source
+from terp.capabilities.sync.service import SyncService
+
+_TYPE_MAX = 128
+
+
+class SyncJobPayload(BaseSchema):
+    """Which entity type to reconcile — the registered source is resolved by this name."""
+
+    entity_type: str = Field(max_length=_TYPE_MAX)
+    tenant_id: uuid.UUID | None = None
+
+
+def _tenant_for_job(ctx: JobContext, payload: SyncJobPayload) -> uuid.UUID | None:
+    """Tenant metadata carried by the payload, falling back to the job envelope context."""
+    context_tenant = getattr(ctx, "tenant_id", None)
+    if context_tenant is not None:
+        return context_tenant
+    tenant = payload.model_dump().get("tenant_id")
+    if tenant is None:
+        return None
+    return tenant if isinstance(tenant, uuid.UUID) else uuid.UUID(str(tenant))
+
+
+def _run_pull(ctx: JobContext, payload: SyncJobPayload) -> None:
+    """Reconcile System B → local for the payload's entity type (the ``SYNC_PULL`` handler)."""
+    SyncService().pull(
+        ctx.session,
+        resolve_sync_source(payload.entity_type),
+        tenant_id=_tenant_for_job(ctx, payload),
+    )
+
+
+def _run_push(ctx: JobContext, payload: SyncJobPayload) -> None:
+    """Push local changes → System B for the payload's entity type (the ``SYNC_PUSH`` handler)."""
+    SyncService().push(
+        ctx.session,
+        resolve_sync_source(payload.entity_type),
+        tenant_id=_tenant_for_job(ctx, payload),
+    )
+
+
+SYNC_PULL = JobDefinition(
+    name="sync.pull", payload_schema=SyncJobPayload, handler=_run_pull
+)
+SYNC_PUSH = JobDefinition(
+    name="sync.push", payload_schema=SyncJobPayload, handler=_run_push
+)
+
+
+__all__ = ["SYNC_PULL", "SYNC_PUSH", "SyncJobPayload"]

terp_cap_sync-0.1.0/src/terp/capabilities/sync/migrations/versions/cb413566b235_create_sync_tables.py

@@ -0,0 +1,130 @@
+"""create sync tables
+
+Revision ID: cb413566b235
+Revises: 
+Create Date: 2026-07-01 22:55:48.247941
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'cb413566b235'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('sync_mapping',
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('version', sa.Integer(), nullable=False),
+    sa.Column('tenant_scope', sqlmodel.sql.sqltypes.AutoString(length=36), nullable=False),
+    sa.Column('tenant_id', sa.Uuid(), nullable=True),
+    sa.Column('entity_type', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.Column('local_id', sa.Uuid(), nullable=False),
+    sa.Column('remote_id', sqlmodel.sql.sqltypes.AutoString(length=200), nullable=False),
+    sa.Column('remote_checksum', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.Column('status', sqlmodel.sql.sqltypes.AutoString(length=16), nullable=False),
+    sa.Column('last_synced_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_sync_mapping')),
+    sa.UniqueConstraint('tenant_scope', 'entity_type', 'local_id', name='uq_sync_mapping_local'),
+    sa.UniqueConstraint('tenant_scope', 'entity_type', 'remote_id', name='uq_sync_mapping_remote')
+    )
+    with op.batch_alter_table('sync_mapping', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_sync_mapping_entity_type'), ['entity_type'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_mapping_local_id'), ['local_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_mapping_remote_id'), ['remote_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_mapping_status'), ['status'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_mapping_tenant_id'), ['tenant_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_mapping_tenant_scope'), ['tenant_scope'], unique=False)
+
+    op.create_table('sync_record_log',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('run_id', sa.Uuid(), nullable=False),
+    sa.Column('tenant_scope', sqlmodel.sql.sqltypes.AutoString(length=36), nullable=False),
+    sa.Column('tenant_id', sa.Uuid(), nullable=True),
+    sa.Column('entity_type', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.Column('remote_id', sqlmodel.sql.sqltypes.AutoString(length=200), nullable=False),
+    sa.Column('action', sqlmodel.sql.sqltypes.AutoString(length=16), nullable=False),
+    sa.Column('message', sqlmodel.sql.sqltypes.AutoString(length=2000), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_sync_record_log'))
+    )
+    with op.batch_alter_table('sync_record_log', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_sync_record_log_action'), ['action'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_record_log_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_record_log_entity_type'), ['entity_type'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_record_log_remote_id'), ['remote_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_record_log_run_id'), ['run_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_record_log_tenant_id'), ['tenant_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_record_log_tenant_scope'), ['tenant_scope'], unique=False)
+
+    op.create_table('sync_run',
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('version', sa.Integer(), nullable=False),
+    sa.Column('tenant_scope', sqlmodel.sql.sqltypes.AutoString(length=36), nullable=False),
+    sa.Column('tenant_id', sa.Uuid(), nullable=True),
+    sa.Column('source', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.Column('status', sqlmodel.sql.sqltypes.AutoString(length=16), nullable=False),
+    sa.Column('started_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('processed_count', sa.Integer(), nullable=False),
+    sa.Column('created_count', sa.Integer(), nullable=False),
+    sa.Column('updated_count', sa.Integer(), nullable=False),
+    sa.Column('failed_count', sa.Integer(), nullable=False),
+    sa.Column('cursor', sqlmodel.sql.sqltypes.AutoString(length=512), nullable=True),
+    sa.Column('error', sqlmodel.sql.sqltypes.AutoString(length=2000), nullable=True),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_sync_run'))
+    )
+    with op.batch_alter_table('sync_run', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_sync_run_source'), ['source'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_run_started_at'), ['started_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_run_status'), ['status'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_run_tenant_id'), ['tenant_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_sync_run_tenant_scope'), ['tenant_scope'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('sync_run', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_sync_run_tenant_scope'))
+        batch_op.drop_index(batch_op.f('ix_sync_run_tenant_id'))
+        batch_op.drop_index(batch_op.f('ix_sync_run_status'))
+        batch_op.drop_index(batch_op.f('ix_sync_run_started_at'))
+        batch_op.drop_index(batch_op.f('ix_sync_run_source'))
+
+    op.drop_table('sync_run')
+    with op.batch_alter_table('sync_record_log', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_sync_record_log_tenant_scope'))
+        batch_op.drop_index(batch_op.f('ix_sync_record_log_tenant_id'))
+        batch_op.drop_index(batch_op.f('ix_sync_record_log_run_id'))
+        batch_op.drop_index(batch_op.f('ix_sync_record_log_remote_id'))
+        batch_op.drop_index(batch_op.f('ix_sync_record_log_entity_type'))
+        batch_op.drop_index(batch_op.f('ix_sync_record_log_created_at'))
+        batch_op.drop_index(batch_op.f('ix_sync_record_log_action'))
+
+    op.drop_table('sync_record_log')
+    with op.batch_alter_table('sync_mapping', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_sync_mapping_tenant_scope'))
+        batch_op.drop_index(batch_op.f('ix_sync_mapping_tenant_id'))
+        batch_op.drop_index(batch_op.f('ix_sync_mapping_status'))
+        batch_op.drop_index(batch_op.f('ix_sync_mapping_remote_id'))
+        batch_op.drop_index(batch_op.f('ix_sync_mapping_local_id'))
+        batch_op.drop_index(batch_op.f('ix_sync_mapping_entity_type'))
+
+    op.drop_table('sync_mapping')
+    # ### end Alembic commands ###

terp_cap_sync-0.1.0/src/terp/capabilities/sync/models.py

@@ -0,0 +1,155 @@
+"""Sync tables: the identity ledger, per-run aggregates, and an append-only record log.
+
+A sync reconciles a local entity type against an external system. Three tables back it:
+
+* :class:`SyncMapping` (``BaseTable``) — the identity ledger tying a local row to its remote
+    counterpart. Unique on (``tenant_scope``, ``entity_type``, ``local_id``) **and**
+    (``tenant_scope``, ``entity_type``, ``remote_id``), so an upsert is idempotent from either
+    side without colliding across tenants — the natural at-least-once dedupe key the design (§6
+    rule 3) leans on.
+* :class:`SyncRun` (``BaseTable``) — one reconcile attempt's aggregates (counts + the
+  high-watermark ``cursor``), stored so a stats view never pays a per-row ``COUNT(*)``
+  (review M5).
+* :class:`SyncRecordLog` — one append-only line per record processed, immutable exactly like
+  :class:`~terp.capabilities.audit.AuditEvent` (``UUIDPrimaryKeyMixin``, no OCC ``version`` /
+  ``updated_at``); high-volume, so plan retention.
+
+Every caller-influenceable ``str`` column caps its length.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Final
+
+from sqlalchemy import DateTime, UniqueConstraint
+from sqlmodel import Field, SQLModel
+
+from terp.core import BaseTable, UUIDPrimaryKeyMixin
+
+# Mapping/run status + record-log actions (plain str columns, dependency-light leaves like
+# ``AuditEvent.action`` — never a higher-layer enum on the table).
+STATUS_SYNCED: Final[str] = "synced"
+STATUS_RUNNING: Final[str] = "running"
+STATUS_SUCCEEDED: Final[str] = "succeeded"
+STATUS_FAILED: Final[str] = "failed"
+
+ACTION_CREATED: Final[str] = "created"
+ACTION_UPDATED: Final[str] = "updated"
+ACTION_UNCHANGED: Final[str] = "unchanged"
+ACTION_FAILED: Final[str] = "failed"
+
+# Hard caps so a hostile / oversized value can never break the INSERT or the ledger.
+_TYPE_MAX: Final[int] = 128
+_REMOTE_ID_MAX: Final[int] = 200
+_CHECKSUM_MAX: Final[int] = 128
+_STATUS_MAX: Final[int] = 16
+_ACTION_MAX: Final[int] = 16
+_CURSOR_MAX: Final[int] = 512
+_MESSAGE_MAX: Final[int] = 2000
+_GLOBAL_TENANT_SCOPE: Final[str] = "global"
+
+
+def _utc_now() -> datetime:
+    """UTC ``now`` provider for the timestamp columns."""
+    return datetime.now(UTC)
+
+
+class SyncMapping(BaseTable, table=True):
+    """The identity ledger: one local row ↔ one remote row for an ``entity_type``.
+
+    ``id`` / ``created_at`` / ``updated_at`` / ``version`` are inherited from ``BaseTable``.
+    The two unique constraints make the mapping the idempotent upsert key from either side, so
+    an at-least-once redelivery of the same remote record never double-creates a local row.
+    ``remote_checksum`` lets the reconcile detect a change without deep-diffing the payload.
+    """
+
+    __tablename__ = "sync_mapping"
+    __table_args__ = (
+        UniqueConstraint(
+            "tenant_scope", "entity_type", "local_id", name="uq_sync_mapping_local"
+        ),
+        UniqueConstraint(
+            "tenant_scope", "entity_type", "remote_id", name="uq_sync_mapping_remote"
+        ),
+    )
+
+    tenant_scope: str = Field(default=_GLOBAL_TENANT_SCOPE, max_length=36, index=True)
+    tenant_id: uuid.UUID | None = Field(default=None, index=True)
+    entity_type: str = Field(max_length=_TYPE_MAX, index=True)
+    local_id: uuid.UUID = Field(index=True)
+    remote_id: str = Field(max_length=_REMOTE_ID_MAX, index=True)
+    remote_checksum: str = Field(max_length=_CHECKSUM_MAX)
+    status: str = Field(default=STATUS_SYNCED, max_length=_STATUS_MAX, index=True)
+    last_synced_at: datetime = Field(
+        default_factory=_utc_now,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=False,
+    )
+
+
+class SyncRun(BaseTable, table=True):
+    """One reconcile attempt for a ``source`` (entity type): status, counts, and cursor.
+
+    Aggregates are stored here (``processed_count`` / ``created_count`` / ``updated_count`` /
+    ``failed_count``) so a stats view reads a single row instead of counting the log; the
+    high-watermark ``cursor`` is where the next run resumes.
+    """
+
+    __tablename__ = "sync_run"
+
+    tenant_scope: str = Field(default=_GLOBAL_TENANT_SCOPE, max_length=36, index=True)
+    tenant_id: uuid.UUID | None = Field(default=None, index=True)
+    source: str = Field(max_length=_TYPE_MAX, index=True)
+    status: str = Field(default=STATUS_RUNNING, max_length=_STATUS_MAX, index=True)
+    started_at: datetime = Field(
+        default_factory=_utc_now,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=False,
+        index=True,
+    )
+    finished_at: datetime | None = Field(
+        default=None,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=True,
+    )
+    processed_count: int = Field(default=0)
+    created_count: int = Field(default=0)
+    updated_count: int = Field(default=0)
+    failed_count: int = Field(default=0)
+    cursor: str | None = Field(default=None, max_length=_CURSOR_MAX)
+    error: str | None = Field(default=None, max_length=_MESSAGE_MAX)
+
+
+class SyncRecordLog(UUIDPrimaryKeyMixin, SQLModel, table=True):  # arch-allow-table-models-use-base-table: append-only per-record log (like AuditEvent) — immutable, no version/updated_at by design (see module docstring)
+    __tablename__ = "sync_record_log"
+
+    run_id: uuid.UUID = Field(index=True)
+    tenant_scope: str = Field(default=_GLOBAL_TENANT_SCOPE, max_length=36, index=True)
+    tenant_id: uuid.UUID | None = Field(default=None, index=True)
+    entity_type: str = Field(max_length=_TYPE_MAX, index=True)
+    remote_id: str = Field(max_length=_REMOTE_ID_MAX, index=True)
+    action: str = Field(max_length=_ACTION_MAX, index=True)
+    message: str | None = Field(default=None, max_length=_MESSAGE_MAX)
+    created_at: datetime = Field(
+        default_factory=_utc_now,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=False,
+        index=True,
+    )
+
+
+__all__ = [
+    "ACTION_CREATED",
+    "ACTION_FAILED",
+    "ACTION_UNCHANGED",
+    "ACTION_UPDATED",
+    "STATUS_FAILED",
+    "STATUS_RUNNING",
+    "STATUS_SUCCEEDED",
+    "STATUS_SYNCED",
+    "SyncMapping",
+    "SyncRecordLog",
+    "SyncRun",
+]