> ## Documentation Index > Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt > Use this file to discover all available pages before exploring further. # Genesis Prover > Measure two database estates, compare them, and prove whether a delivered change meets its specification — with every difference either licensed by a rule a person ratified or left as an open finding a person decides. **Genesis Prover measures two database estates, compares them, and proves whether a delivered change meets its specification — with every difference either licensed by a rule a person ratified, licensed by a disclosed platform assumption, or left as an open finding a person decides.** Migrations, rebuilds and large refactors all end with the same question, and it is usually answered with a spreadsheet and a feeling: *did we actually deliver what we said we would, and is anything else different that nobody meant to change?* The Prover answers it as a measurement. It reads both databases first-hand, records what it found and how it was permitted to look, enumerates every difference between them, and then accounts for each one. A difference is accounted for by a rule a person ratified, a disclosed platform assumption, or a person deciding it. Nothing accounts for itself, and nothing is quietly dropped. The result is a signed verdict with its evidence attached — and it can be re-derived later, because every step records which build produced it, which rules it was judged under, and which database it actually read. Connection access and run provenance are separate; the [estate API reference](/docs/Genesis-API/API-Reference) defines how direct estate calls preserve agent transport and audit identity while opening saved connections as the authenticated human, including endpoint-specific reuse rules. Characterization resume state follows that same exact resolved transport identity. The opaque identity scope includes the bot and authenticated user pair, so an interrupted scan can resume only its own staged measurement progress; another identity never sees or consumes those rows. For Databricks sources, Prover scan reads use an internal 64 MB response ceiling and bound eligible degeneracy probes at the source; see [Databricks scan behavior](/docs/Integrations/Data%20Sources/Databricks/Databricks). **Who does what.** It is largely **agents** that run the Prover — registering estates, launching measurements, authoring specifications, proposing dispositions. It is **people** who look at the results and press the approve buttons. These pages are written for that person. Where you would reasonably wonder how something gets started, the answer is "an agent starts it"; the exact calls live in the agent-facing reference described at the end of this page. [How agents drive the Prover](/docs/Genesis-Prover/Agents-And-The-API) covers that division in full — what an agent starts, what you see once it has, and where the agent-facing reference lives. ## Readiness tells you what happened Before characterization, estate preflight reports access, ETL understanding, and clonability as separate readiness lights. A raw estate may be marked `source_only=true`: because no Genesis transform produces its data, it has no ETL light and can be ready without code assets. If the ETL agent turn reaches its configured wall-clock budget, the light reports a timeout and points to the budget setting rather than treating the partial reply as a format error. The API reference covers the response fields and the [Advanced Settings](/docs/Setup/Advanced-Settings) page lists the budget. Attaching code assets does not pin them: it records their locations until the agent calls `clone_code_assets`. When registration or an edit returns that verb in `next`, the agent must clone the git repositories or capture the Databricks revisions before characterization. For a SOURCE with no transform code, the response suggests declaring `source_only=true`; that declaration is explicit, not inferred from an empty asset list. See [estate registration and code assets](/docs/Genbot-Toolkit/Additional-Tool-Groups#estate-registration-and-code-assets) for the agent workflow and clone-fault recovery behavior. ## The data-work proving skill The optional `prove-data-work` skill is the end-to-end playbook for proving data built to a written definition: a migration, cutover, rebuild or replatform, a dbt build, a pipeline output, or a new gold, mart or reporting layer. It explains when to use the Prover instead of hand-written row counts, how to choose the cross-engine settings, and how to read a comparison into a punchlist without treating `indeterminate` or `errored` as a clean result. For a copy leg whose data already landed, register and characterize both whole estates before authoring one spec. Put each keep-but-don't-count table in `excluded_objects` on every estate that contains it. Give row identity only as `row_identity`; write renames into the spec and pass them to the proof as `schema_map`, `column_map`, and `object_map`. Other requirements become clarifications; ask all questions before commissioning at most one repair round. If an exclusion arrives after sealing, update the full `excluded_objects` list on each estate that holds the table, then characterize both estates again. A proof counts as proved only when the review page reads Verified: the person has accepted every remaining item with a reason, nothing is left open, and a partially specified spec has no open clauses. The skill gives the full order. In a Genesis thread, activate it with `manage_context(action='ADD_CONTEXT', active_skills='prove-data-work')`. An external MCP caller can read it through `genesis(action='read_skill', skill_name='prove-data-work', relative_path='SKILL.md')`. `SKILL.md` holds the core rules and identifies the supplementary files to read when needed: `the-path.md` for running a step, `reading-results.md` for comparisons, `grades.md` for grade reports, `approvals.md` for requests, `getting-the-verbs.md` for MCP or HTTP calls, and `relaying-to-people.md` before relaying an answer or asking a person. In a Genesis thread, read a listed file with `read_assigned_skill_file`; an external MCP caller uses `read_skill` with the file path as `relative_path`. See [Context Tools](/docs/Genbot-Toolkit/Context-Tools) for the assigned-skill reader details. The skill is optional: the `plan_estate_comparison` plan and the Prover's verbs work without it, and their responses identify the skill when it is useful. The two Prover skills were previously named `prove-a-migration` and `plan-a-migration`. Those names still load, as thin pointer skills that keep the migration trigger words and send the agent to `prove-data-work` and `plan-data-work`. The pointers carry none of the doctrine, so a thread or caller that uses an old name should load the new one. ## The data-work planning skill `prove-data-work` verifies one comparison. A migration or spec-driven build may need several comparisons in a required order, and the companion `plan-data-work` skill is the recipe book for working out which ones. It applies to migrations as well as builds such as a dbt model or reporting layer checked against a written definition. For layered work, it teaches the general source-layer, ETL and target-layer shape, the named shapes seen so far, and a method for deriving a recipe for a project that matches none of them. For each it gives the proof sequence, what must be declared before the first proof, and the rule that the deliverable is a durable pipeline on the target rather than hand-assembled copies. There is no separate planning agent: the same agent plans the sequence and then runs each proof through `prove-data-work`. The detailed recipes are written down once in the skill. Activate it the same way: `manage_context(action='ADD_CONTEXT', active_skills='plan-data-work')`, or `genesis(action='read_skill', skill_name='plan-data-work', relative_path='SKILL.md')` from outside. The data-work skills direct the agent to take its own next step in the same turn: repair its own spec defect and act on choices already covered by the sponsor's standing rule, including whether to open an adjudication. Required readiness items and sealed-spec ratification still wait for the person. For a review decision without a standing rule, the person must ask for it or include it in a goal, Blueprint, or mission; an agent records which basis it acted under. Readiness withholds another conversation's answers and documents by default; ask the person here, and set `include_other_conversations=true` only if they ask you to use that record. Confirm any answer from it before relying on or repeating it. See the [`readiness` tool reference](/docs/Genbot-Toolkit/Additional-Tool-Groups#readiness) for the response details and how the pair's latest proof can supply the migration shape when no sealed spec is named. ## Data-fidelity checks in the skills When planning or proving spec-driven data work, profile each source column for missing-value markers that its declared type does not reveal, such as `''`, `'-'`, `'N/A'`, `'-1'`, or text `'inf'`. Record each discovered marker and its required target representation in the mapping before it is ratified; an unreconciled count is not explained until the rows causing the difference are found. Choose conversions from the measured source values rather than the declared type, and verify every cast: a successful conversion can produce a misleading value such as `0.0` or `Infinity`. The mapping must state which values convert and where every other value lands. ## Fresh licensing evidence Questions about a comparison's licensing audit or audit trail, what licensed a difference, why the result should be trusted, or what a provenance label means must be answered from stored evidence, not earlier assistant prose. On every such turn, including repeats and follow-ups, activate `prove-data-work` with `manage_context(action='ADD_CONTEXT', active_skills='prove-data-work')`, then make a fresh `read_comparison(diff_hash=…, include=["license_audit"])` call before answering. Use each raw provenance label exactly as returned; do not translate it into a friendly name or infer a rule explanation from it. The [Prover toolkit reference](/docs/Genbot-Toolkit/Additional-Tool-Groups#read_comparison) covers the audit projection and its bounded evidence contract. When no Prover-page comparison context was supplied, the chat can use its own proof record only when the thread identifies exactly one distinct, successfully completed comparison. If there is no such comparison, more than one, or the record cannot be validated, the chat does not guess which audit to read. Supply valid Prover context from the relevant comparison to identify it explicitly. Anything labelled **Planned** on these pages is designed but not in the product today. Everything else describes Genesis as it currently ships. ## The flow ```mermaid theme={null} %%{init: {"flowchart":{"layout":"elk","htmlLabels":false,"nodeSpacing":70,"rankSpacing":80,"useMaxWidth":true},"themeVariables":{"fontSize":"18px"}} }%% flowchart TB SRC[(Source estate)] TGT[(Target estate)] subgraph MEASURE[" 1. Estates and characterization "] direction TB CS[Characterize source] CT[Characterize target] end subgraph PROVE[" 2 and 3. Prove "] direction TB CMP[Comparison: every difference, enumerated] SPEC[Sealed specification, authored from the ticket] GRADE[Grade: implemented / not / differently] end ADJ[4. Adjudicator settles findings against rules and rulings] CON[5. Consult rules on one named ambiguity] AGT([An estate-working agent]) REV[6. Human review: proposals, approvals, ratification] DEC{{The review decision — the one place a person signs}} SRC --> CS TGT --> CT CS --> CMP CT --> CMP SPEC --> GRADE CMP --> GRADE CMP --> ADJ GRADE --> ADJ ADJ --> REV CMP -.disputed finding.-> AGT AGT -.asks for a ruling.-> CON CON -.ruling.-> REV REV --> DEC classDef human fill:#ff9248,stroke:#c46a2c,color:#1a1a1a; class DEC,REV human; ``` Read it as one sentence: **measure both sides, compare them, grade the specification against that comparison, settle what can be settled mechanically, and put the remainder in front of a person.** ## One proof, with or without a specification A Prover proof is **one thing**, whether or not a specification is attached. The comparison always runs — the two estates are measured against each other and every difference is enumerated, specification or no specification. When a sealed specification is attached, the same proof also grades it. And whatever the specification did not explain **still goes to review**. That is the important guarantee. A specification narrows what a person has to decide by hand. It never shrinks what was measured, and it never closes a difference nobody licensed. For how the `prove` report handles a comparison that matched no objects before presenting the grade, see the [`prove` tool reference](/docs/Genbot-Toolkit/Additional-Tool-Groups#prove). The agent-facing `prove` operation now provides that one trigger: it takes both characterization snapshots and an optional sealed specification, returning one proof run that owns the comparison and, when attached, the grade. Grading remains separately repeatable for a repaired specification against an existing comparison; that path does not re-measure the databases. Before any comparison exists, an obligation-only grade is also possible with `tiers=["derivational"]`; see the [`grade` tool reference](/docs/Genbot-Toolkit/Additional-Tool-Groups#grade). Use `prove` when the first run should compare the estates and grade structural items as well. A succeeded, sealed `spec_conformance` grade can also be cited as server-checked project evidence through [`project_note`](/docs/Genbot-Toolkit/Project-Manager-Tools#project_note). For a sealed-connection refusal, follow the proposed retry described in the [`grade` tool reference](/docs/Genbot-Toolkit/Additional-Tool-Groups#grade). [Databricks characterization connections](/docs/Integrations/Data%20Sources/Databricks/Databricks#choose-an-authentication-mode) support Service Principal (OAuth M2M) credentials for headless Prover scans and validations; see [Databricks connection behavior](/docs/Integrations/Data%20Sources/Databricks/Databricks) for token refresh behavior during long-running validations. [How agents drive the Prover](/docs/Genesis-Prover/Agents-And-The-API#one-trigger-the-proof) ### When a grade names a comparison made without its spec A sealed specification that declares a `target_model` is graded over a comparison made under that model. This is the same comparison that `prove(spec_hash=...)` makes: the model licenses the declared target mappings and scope that the structural grade reads. If a caller uses `compare` and then calls `grade` with that comparison's `diff_hash`, Genesis compares the pair again under the sealed model and grades the replacement comparison. The grade provenance records `comparison_recomputed_under_spec`, including the replaced `diff_hash`, the `target_model_hash`, and the spec that declared it. If that recomputation creates a new comparison, its listing title comes first from the grade run's recorded title. Otherwise, it inherits the replaced comparison's title unless that title was explicitly recorded under a different kind. A title recorded without a spec is not carried onto a spec-measured comparison; a title minted before title kinds were recorded is carried forward, preserving the name shown for that older comparison. The new comparison records an inherited title under the graded spec, so later re-grades can match that kind. When no eligible title exists, the recomputation has no business title and the card keeps its technical label. Consent-triggered re-runs preserve the original comparison's title and its recorded spec kind. This keeps a title attached to the kind of comparison it names across re-grade and consent re-evaluation. The recomputation carries forward the original comparison's caller-declared `column_map`, so renamed columns remain paired instead of appearing as missing and surplus. It also carries the comparison's recorded `row_identity_declared` key and resolves it under the model as `prove(spec_hash=..., row_identity=...)` would. For a derived target, that means the key is resolved against the derived target's driving input. If the key no longer pairs rows one-to-one under the model — for example, its target column is unavailable or its values repeat — the recomputation withholds that pair as `indeterminate` rather than guessing or refusing the whole grade. If the original comparison never recorded target terms for a key that paired no rows, those terms are not invented; the pair is withheld. Mapping an input onto a model-declared `DERIVED` target is not treated as row correspondence: the model builds that target from its declared inputs. This keeps compare-then-grade aligned with `prove(spec_hash=...)` instead of presenting the input rows under the derived target's name. The grade reports the key and failure at `comparison_recomputed_under_spec.row_identity.