terp-cap-sync 0.1.0__py3-none-any.whl

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/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/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/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",
+]

terp/capabilities/sync/remote.py

@@ -0,0 +1,127 @@
+"""The ``SyncSource`` seam: how a sync reads System B and applies records to the local target.
+
+An app implements one :class:`SyncSource` per entity type and registers it; the reconcile
+engine (:class:`~terp.capabilities.sync.SyncService`) owns everything else — the run
+bookkeeping, the mapping ledger, the record log. This is the seam that keeps the two
+design invariants (§14):
+
+* the **external read** of System B happens in :meth:`SyncSource.pull`, which the reconcile
+  calls **inside the job handler** (a worker, post-commit) — never in an ``_after_write`` hook
+  (the dual-write hazard the ADR-0040 review flagged); and
+* the **local write** happens in :meth:`SyncSource.apply`, which MUST go through an audited
+  ``BaseService`` so a synced row is actor / owner stamped and audited like any other write.
+
+The source is resolved by ``entity_type`` from a small registry (the job carries the entity
+type, not a closure — a remote worker resolves the source by name, like a job handler).
+"""
+
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlmodel import Session
+
+
+class SyncError(RuntimeError):
+    """Raised when a sync source is unregistered, or a direction it does not support is run."""
+
+
+@dataclass(frozen=True)
+class RemoteRecord:
+    """One record from System B: its remote id, a change-detecting checksum, and the payload.
+
+    ``payload`` is plain JSON scalars (ids, not entities) — it crosses the job boundary and is
+    handed to :meth:`SyncSource.apply` to upsert the local row. ``checksum`` lets the reconcile
+    skip an unchanged record without deep-diffing.
+    """
+
+    remote_id: str
+    checksum: str
+    payload: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RemotePage:
+    """One page of remote records plus the cursor to resume from (the high-watermark)."""
+
+    records: tuple[RemoteRecord, ...] = ()
+    next_cursor: str | None = None
+
+
+class SyncSource(ABC):
+    """A registered source/target pair for one ``entity_type`` — the app implements it.
+
+    Set ``entity_type`` on the subclass; implement :meth:`pull` (read System B) and
+    :meth:`apply` (upsert the local row via an audited ``BaseService``). Override :meth:`push`
+    only for a source that also pushes local changes outward (``SYNC_PUSH``); the default
+    fails closed.
+    """
+
+    entity_type: str
+
+    @abstractmethod
+    def pull(self, cursor: str | None) -> RemotePage:
+        """Read one page of remote records from *cursor* onward (the external System-B call)."""
+
+    @abstractmethod
+    def apply(
+        self, session: Session, record: RemoteRecord, local_id: uuid.UUID | None
+    ) -> uuid.UUID:
+        """Create (``local_id`` is ``None``) or update the local entity; return its id.
+
+        MUST persist through an audited ``BaseService`` so the synced row is stamped + audited.
+        """
+
+    def push(self, session: Session) -> int:  # noqa: ARG002 - default seam; overridden by push-capable sources
+        """Push local changes to System B (``SYNC_PUSH``); default: unsupported. Returns count."""
+        raise SyncError(f"sync source {self.entity_type!r} does not implement push")
+
+
+_sources: dict[str, SyncSource] = {}
+
+
+def register_sync_source(source: SyncSource) -> None:
+    """Register *source* for its ``entity_type`` (replacing any prior registration).
+
+    A capability registration (like a scope predicate): it persists across composed apps and is
+    cleared only by :func:`reset_sync_sources`. An app calls this at composition time for each
+    entity type it syncs.
+    """
+    _sources[source.entity_type] = source
+
+
+def resolve_sync_source(entity_type: str) -> SyncSource:
+    """Return the source registered for *entity_type*, or fail closed with :class:`SyncError`."""
+    try:
+        return _sources[entity_type]
+    except KeyError:
+        raise SyncError(
+            f"no sync source registered for entity type {entity_type!r}; "
+            "call register_sync_source(...) at composition time"
+        ) from None
+
+
+def registered_sync_sources() -> tuple[str, ...]:
+    """The entity types with a registered source, in registration order."""
+    return tuple(_sources)
+
+
+def reset_sync_sources() -> None:
+    """Clear the sync-source registry (a test seam; apps re-register at composition)."""
+    _sources.clear()
+
+
+__all__ = [
+    "RemotePage",
+    "RemoteRecord",
+    "SyncError",
+    "SyncSource",
+    "register_sync_source",
+    "registered_sync_sources",
+    "reset_sync_sources",
+    "resolve_sync_source",
+]