common_db.contracts.ops
ops.py — the operation vocabulary: what kinds of DB ops exist and the closed policy sets that parameterize them.
Classification primitives (fixed for an op’s life), never mechanics — the HOW lives in the client domain; these are the nouns every layer speaks.
Classes
CoercePolicy
Bases: StrEnum
The self-heal posture when incoming dtypes drift from the model.
Fields and properties declared here; inherited members belong to the bases above.
COERCE
COERCE = 'coerce'HEAL
HEAL = 'heal'STRICT
STRICT = 'strict'OpKind
Bases: StrEnum
The op axis — every verb the suite performs is one of these.
Fields and properties declared here; inherited members belong to the bases above.
APPEND
APPEND = 'append'ASSESS
ASSESS = 'assess'COMBINE
COMBINE = 'combine'EVOLVE
EVOLVE = 'evolve'KEY_UPGRADE
KEY_UPGRADE = 'key_upgrade'READ
READ = 'read'RECONCILE
RECONCILE = 'reconcile'REPLACE
REPLACE = 'replace'STASH
STASH = 'stash'UPSERT
UPSERT = 'upsert'UPSERT_APPEND
UPSERT_APPEND = 'upsert_append'OutputKind
Bases: StrEnum
Read-side output shape — total flexibility, one closed set.
Fields and properties declared here; inherited members belong to the bases above.
ARROW
ARROW = 'arrow'DICTS
DICTS = 'dicts'PANDAS
PANDAS = 'pandas'POLARS
POLARS = 'polars'ROWS
ROWS = 'rows'ReconcilePolicy
Bases: StrEnum
What happens to STALE rows (present in the target’s scope, absent from the new data). Sam’s ruling: never destructive by default.
(FLAG was removed 2026-08-16 — unearned: no op ever wrote a flag column, and vocabulary must be earned by a real mechanic.)
Fields and properties declared here; inherited members belong to the bases above.
ARCHIVE
ARCHIVE = 'archive'DELETE
DELETE = 'delete'REPORT
REPORT = 'report'StorageKind
Bases: StrEnum
The persistence axis a table policy targets.
PG is the keyed/reconciled census. PQ is the append-heavy parquet
dataset leg. TablePolicy accepts the historical "pg"/"pq"
spellings and normalizes them into this closed vocabulary at construction,
so a typo can never silently fall through to the Postgres branch.
Fields and properties declared here; inherited members belong to the bases above.
PG
PG = 'pg'PQ
PQ = 'pq'