Paridity glossary & canonical terminology¶

The single source of truth for Paridity terminology. Every doc, tooltip, and screen uses these terms exactly. When a doc introduces one of these terms, it links here. The Paridity style guide (§3, internal: docs/governance/style_guide.md) enforces conformance. Getting metering terms wrong is a correctness defect, not a style choice — it misprices the product (#644).

Canonical commercial units (use these exactly)¶

These three are the highest-stakes terms in the product. The retired terms below were ambiguous and caused a mispricing defect.

Canonical term	Definition	Source of truth	Never write
Mapping	The configured source→target reconciliation unit: one source dataset compared to one target dataset under a resolved config. The fundamental object operators create, schedule, and run.	`cfg.mappings`	~~Validation Pair~~, ~~recon pair~~, ~~table pair~~
Mappings Run per Month	The headline usage meter: distinct Mappings run within a UTC calendar month. Drives the commercial tier. Meter-never-block — exceeding it never blocks a run; it meters for expansion.	`db/seeds/subscription_tiers.sql` `base_mappings_run_per_month`	~~Validation Execution~~, ~~validation run~~ (as a meter)
Active Mapping Cap	The entitlement limit: how many Mappings may be concurrently active (configured/enabled) on a tier. Hard on every tier that carries one — Trial, Team, Department, Division and Enterprise all enforce it identically; only Global Enterprise is uncapped. Enforced as published; once a tier's single growth addon is active the cap becomes the greater of the published cap and 1.5 × the effective run allowance, rounded up (the published cap is itself 1.5 × the base allowance; #3421). Blocks Mapping creation (HTTP 402 `MAPPING_LIMIT_REACHED`), never a run.	`db/seeds/subscription_tiers.sql` `max_active_mappings` + `entitlement_service.get_entitlements`	~~pair limit~~, ~~mapping limit~~, ~~seat cap~~

Important — "Mappings Run per Month" is a meter (measures usage, never blocks). "Active Mapping Cap" is a limit (bounds concurrent configuration). They are different dimensions; conflating or swapping them misprices a deal.

Retired terms — do not use anywhere: Validation Pair, Validation Execution, validation run (as a metered noun). Replace on sight with the canonical unit above.

Core reconciliation concepts¶

Term	Definition
Reconciliation	Proving a target dataset is complete and correct versus its source, within a deterministically aligned time window. Paridity is a replication correctness assurance platform, not a data-quality or observability tool.
Source	The system of record the data is copied from (e.g. SAP ECC on Oracle/DB2).
Target	The analytical/downstream system the data is copied to (e.g. Snowflake, Databricks, ADLS via Trino).
Proof phase	The fast O(1) pass/fail gate: compares aggregate dataset fingerprints (`hash_total`) plus row counts. Proves an entire dataset identical without pulling rows.
Diff phase	The detailed evidence phase that runs only when proof fails: identifies which rows differ (`row_hash`), then compares them column-by-column (`field_diff`).
Proof-only mode	Per-mapping/schedule mode that stops after the proof phase regardless of outcome — for cost/egress-sensitive high-frequency checks.
CDC-aware	Paridity aligns source and target to the same point in time using CDC tool state before comparing, avoiding false positives from in-flight replication. The category descriptor is CDC-Aware Reconciliation Platform (locked phrase).
Key identity (exact-v1)	The rule for when a source row and a target row are the same entity: their key values, as each database returns them, are identical. No case folding, accent folding, Unicode normalisation or trimming is applied to keys. `SMITH` and `smith` are two keys (one missing, one extra), not a match with a field difference. See the key identity contract.
Declared SCD scope	An operator-declared, versioned scope limiting the comparison to the current rows of an SCD2/bitemporal side. Never inferred; stored in the checksummed config snapshot; supported only where scope rendering is live-verified (PostgreSQL and Snowflake today). Watermark queries are never scoped by it.
SCD invariant	A per-run assertion that a declared scope's own premise holds on the scoped side: exactly one current row per business key (always checked) and, opt-in, no overlapping validity intervals. A violation is a qualification, never a new terminal status: the run keeps its data verdict, is reclassified SCD Invariant Violated, and is excluded from pass counts.

Fingerprints & hashing (never confuse these)¶

Term	Definition
`hash_total`	Aggregate dataset fingerprint (proof phase). Proves an entire dataset identical. A fast pass/fail signal — not a checksum.
`row_hash`	Per-row SHA-256 fingerprint (key-extraction phase). Identifies which specific rows differ.
`field_diff`	Column-by-column comparison output (diff phase). The actual reconciliation deliverable.
`config_checksum`	SHA-256 of the resolved config JSON. Detects policy changes between runs. Concerns config, not data.
`hash_method`	The named hashing algorithm used on a side (e.g. `xor_sum_sha256`). Source and target must match; if they differ, both fall back to the DuckDB reference implementation.
Canonicalization	Normalizing every column value to a fixed string form (NULL token, fixed-point numerics, UTC ISO timestamps, etc.) before hashing, so identical data hashes identically across engines.
Reference engine (DuckDB)	The ground-truth hash implementation. When engines can't match `hash_method`, comparison falls back to DuckDB.

Configuration & policy¶

Term	Definition
Config resolution (7 layers)	Config is resolved at run time from L1 platform defaults → L7 run overrides, via the `ConfigResolver`. Most settings: lower layer wins; special rules for `max_concurrency` (MIN), `store_raw_diff_values` (AND), `priority` (MAX), and `mask_in_ui` (field level only — there is no tenant-wide mask).
Resolved config snapshot	The frozen config a run uses, stored in `cfg.config_versions`. A run always uses the snapshot active when it started.
`store_raw_diff_values`	AND-chain across tenant (L2), mapping (L4), field (L5). Any `FALSE` suppresses raw diff storage and sets `values_masked`.
`mask_in_ui`	Field-level (L5) only. `TRUE` masks the field in the UI; a tenant-wide mask policy is not implemented.
Field Config	Per-field settings on a Mapping (`cfg.mapping_fields`): hash column order, numeric scale, timestamp precision, blob compare mode, decrypt expression, masking.
Replication Profile	First-class `cfg` entity capturing how data flows source→target via a specific replication tool. Sits between Systems and Mappings; provides default watermark templates and known-replicated-table lists. One per source+target+tool.
Replication tool	The CDC/replication technology (Debezium, Airbyte, SLT, GoldenGate, …). User-declared — the platform does not auto-detect it.

Windows, watermarks & readiness¶

Term	Definition
Watermark	The signal used to align source and target to the same point in time. Strategies in preference order: `control_marker` → `delta_version`/CDC offset → `ingest_ts` → `partition_max` → `timestamp` → `custom_sql` → `snapshot`.
`watermark_domain`	The comparability space of a watermark: `time_utc` (e.g. SCN, ingest_ts) or `sequence` (LSN, delta_version). Never mix domains within a Mapping.
Readiness	The pre-proof evaluation: CDC probe → watermark fetch → latency evaluation → stability → advancement. Determines whether a window is safe to compare.
In-flight recheck	In-workflow re-check loop for rows that differed only because replication was still in flight when they were compared (`lag_retry_pending` internally). Does not create a new run; `compare_started_at` never changes across rechecks.
`compare_started_at`	The immutable SOX/ICFR audit timestamp, set once when a run starts. Never updated - not on in-flight rechecks, not on reruns.
Window mode	`auto` (incremental window, default) or `full` (full-table comparison, e.g. quarter-end audits).

Evidence, audit & schema¶

Term	Definition
Evidence	Append-only records in the `ev` schema: `hash_total`, `row_hash`, `field_diff`, metrics, in-flight rechecks, anomalies, signed bundles. Immutable except retention purge and defined lifecycle exceptions.
Evidence bundle	A signed, content-hash-chained package of a run's evidence, verifiable by an external auditor.
Period bundle	A signed container over the individually signed per-run evidence bundles for one mapping across a date range. Persisted and downloadable through the product; optionally stored in the customer's own object store.
Write-once anchor	The attestation that a period bundle's container sits in a store that itself refuses deletion (S3 Object Lock, Azure Blob immutability, GCS retention lock). Written only when the store confirms protection, and verified by reading the object back in full.
Legal hold	A scoped freeze — tenant, mapping or single bundle — that makes the retention purge skip the held evidence. Approval-gated (`evidence.legal_hold`) and audited on placement, release, and every skip.
Schema drift	A change in either side's columns/types versus the config snapshot's `known_column_set`, detected at the start of each proof phase. Added columns are advisory and never halt. A lost or breaking-changed reconciled column follows `schema_drift_policy` (`halt` or `continue_excluding`; default `continue_excluding`) — a `continue_excluding` run records reduced coverage and can never display or count as a clean pass. Losing a key column, or a column a declared SCD scope depends on, always halts to `schema_drift_error` regardless of policy.
Config audit	The `ev.ev_config_audit` record (with `config_checksum`) written before proof begins, proving the config was stable during the run.
Audit log	`cfg.audit_log` — terminal status transitions, admin actions, and lifecycle events with actor, entity, action, IP, timestamp.

Access & tenancy¶

Term	Definition
RBAC roles	`platform_admin`, `tenant_admin`, `operator`, `dba`, `steward`, `analyst`, `auditor`, `viewer` — eight roles. `platform_admin`, `tenant_admin`, `operator` and `auditor` share a common read set (mappings, systems, runs, masked evidence, metrics, the audit log); `dba`, `steward`, `analyst` and `viewer` carry only their own narrower permission sets. Enforced in the API layer only.
Grant / scope	A scoped permission binding a principal to a set of resources (e.g. a business domain).
Tenant	An isolated customer boundary; row-level security (RLS) is live as defense-in-depth.
SSO / SCIM	Single sign-on and SCIM user/group provisioning. The interactive browser login is SAML (Okta and Microsoft Entra ID, both live-verified); OIDC is bearer-token validation against a registered per-tenant issuer — for API and service-account access, not a sign-in redirect.
Trust Center	The curated bundle of security, architecture, and compliance docs a customer's vendor-risk team consumes in one place.

Capability status vocabulary¶

Used in every capability/coverage table (style guide §5). Do not invent synonyms.

Status	Meaning
Verified	Implemented and validated end-to-end (live integration + byte-identity proof vs the reference engine).
Supported	Implemented and operational; broader live verification still expanding.
Roadmap	Planned; adapter/contract defined, not yet production-validated.
Evaluating	Candidate under consideration; no committed implementation.

Locked brand phrases (verbatim)¶

Verified data. Trusted outcomes. (tagline)
CDC-Aware Reconciliation Platform (category descriptor)
Evil Genius MindWorks LLC (legal entity — text only, where legally required)

See the Paridity brand kit and style guide (internal: docs/governance/brand/brand_kit.md, docs/governance/style_guide.md).