DEV Community: Rui Wang

The AI agent checked the table. Did every result describe the same state?

Rui Wang — Tue, 25 Aug 2026 07:29:28 +0000

Why agent data tools need exact table identity, bounded coverage, and honest incomplete results beyond a successful tool call.

An AI agent reports:

Table state: Delta version 1183
Schema check: Pass
Active files: 247 present
Release rule: Pass

The tool calls completed without an error. Can another agent rely on this result?

Suppose the table advanced from version 1182 to 1183 while the checks were running. The timeline call observed version 1183. The schema call used metadata cached from version 1182. The file check resolved the current table but did not return a version at all.

Every line may be accurate on its own. Together, they describe no real table state.

The values in this example are fictional. The failure shape is not. A mutable dataset can change between calls, retries, cache reads, and handoffs between agents. Once several valid observations are combined, the result can become a claim that none of the tools actually proved.

Transport is not evidence semantics

The July 2026 release of the Model Context Protocol
made its core stateless and each request self-describing. MCP gives clients and servers a common way to discover and call tools. The Agent2Agent protocol
defines communication between independent agent systems.

These protocols solve real connection problems. They do not define the domain meaning of every tool result.

An MCP tool can return a valid JSON object called schema_check. An A2A agent can send that object to another agent. Neither fact tells the receiver whether the schema and file checks observed the same table state, whether a read limit stopped the inspection, or whether an unsupported delete feature was ignored.

Protocol success answers, "Did the message arrive and satisfy the wire contract?" Data evidence answers, "What can this result prove?"

Data formats already give us stable states

The data layer has useful identities that an evidence contract can reuse.

The Delta Transaction Log Protocol defines a serial history of atomic table versions. A snapshot at a version contains the table metadata and the set of files that belong to that state.

The Apache Iceberg specification
defines snapshots, manifest lists, manifests, data files, and delete files. A snapshot identifies the table state used to plan a scan.

Those identities are stronger than latest, a wall-clock time, or an object storage prefix. They let an agent say which state it observed even after the table changes again.

Other data sources have equivalent anchors: an object version, a content digest, a database transaction identifier, or a catalog reference resolved to an immutable state. A useful agent contract should preserve the native identity instead of inventing a weaker one.

The surrounding standards cover different parts

OpenLineage models jobs, runs, and datasets. Its dataset facets can carry a dataset version, while its data quality assertions facet records test outcomes and optional expected and observed values.

W3C PROV provides a general model for entities, activities, agents, and derivations. It is a foundation for describing where an artifact came from and which activity produced it.

The OpenTelemetry semantic conventions for GenAI agents are developing shared names for agent invocations, plans, workflows, and tool execution spans. That work helps operators observe how an agent ran.

Newer proposals are also exploring cryptographically verifiable agent
evidence. For example,
Proof of Insight describes a content-addressed, signed graph for observation, deterministic computation, model reasoning, and attestation. Its current specification labels itself a working draft rather than a published standard.

These specifications overlap, but they do not require the same data-evidence boundary.

In the specifications above, I have not found a widely adopted profile that requires a data-check result to bind all of the following:

Part	Question it answers
Subject and state	Which exact dataset state was observed?
Question or rule	What was the check trying to establish?
Scope and coverage	Which metadata, files, partitions, samples, or rows were read?
Capability	Which table features and delete semantics did the reader understand?
Outcome	Did the rule pass, warn, fail, or remain incomplete?
Limitations and provenance	What stopped the check, and how can another system reproduce or challenge it?

OpenLineage can represent several of these facts. PROV can express their provenance. MCP or A2A can carry them. The missing piece is a small semantic profile that says which facts are required for an agent-facing data verification result and how they remain bound to one observation.

A profile is a better starting point than a new transport

Creating another RPC or messaging protocol would duplicate work. The same evidence should be able to travel through MCP, A2A, a command-line process, an event stream, or a saved file.

The standardizable part is the meaning of the result.

An illustrative envelope might express this shape:

subject:
  format: delta
  state: 1183
question: schema_compatibility
coverage:
  metadata: complete
  rows: not_read
outcome: incomplete
limitations:
  - active_file_check_observed_a_different_state

This is not a proposed wire schema. It only shows the separation between table identity, the question, observed coverage, outcome, and limitation.

A practical profile would need stronger rules:

A mutable source must resolve to an exact state, or the result remains incomplete.
Observations from incompatible states cannot be merged under one verdict.
Transport completion and evidence outcome use separate status fields.
Successful sections remain available when another section is incomplete.
Unsupported table features and exhausted read limits appear in the result.
The shareable form excludes credentials, signed URLs, private locations, raw rows, and hidden model reasoning.
A policy decision remains separate from the observations it evaluates.

The seventh rule matters when an agent participates in a release workflow. A schema comparison can prove that one field changed. It cannot decide whether the change is allowed until it receives an explicit compatibility or release rule.

Bounded reads need an honest result

Agents make repeated work cheap to request. They do not make remote metadata, object listings, or full scans free.

A data tool needs budgets for time, bytes, objects, metadata entries, rows, and retries. When a budget ends the operation, the result should preserve what was observed and mark the unsupported conclusion as Incomplete.

Retrying silently can make the evidence worse. The next request may observe a new table state and fill the missing section with facts from a different snapshot. A clean-looking report then hides the boundary that mattered most.

An incomplete result can still be useful:

State identity: Verified at Iceberg snapshot 711
Schema check: Pass over snapshot metadata
Delete check: Incomplete after the manifest-read limit
Row impact: Not checked

Another agent can reuse the state and schema evidence, request a larger delete budget with approval, or send the result to a person. It does not need to discard the whole operation or pretend the missing premise passed.

A standard should earn its name

Publishing a JSON Schema is easy. Establishing a useful standard requires independent use.

A credible path would start with one narrow profile for read-only observations of versioned analytical data. It would include mappings to MCP tool results, A2A artifacts, OpenLineage facets, and PROV records. A public conformance set would cover state changes during inspection, unsupported delete semantics, bounded reads, redaction, and incompatible evidence binding.

The profile would become more convincing when two unrelated implementations can exchange the same result and reject the same invalid combinations. Open governance, versioning rules, and a compatibility policy should follow before anyone calls it an industry standard.

That suggests a modest first step: publish a data-evidence profile draft, its mappings, and failure cases. Ask data tool builders, lineage projects, and agent framework authors where it conflicts with their existing models. Change the draft before giving it a brand.

A BigdataSight development note

In our post-1.0 research, we are exploring how local agents can request bounded, read-only checks of Delta and Iceberg tables and receive compact evidence without source locations, credentials, schema bodies, or row values.

The recurring constraint is that observations must stay attached to the state that produced them. Speed matters only when the observations describe the same state. Interoperability matters only when the next agent can see their coverage and limitations.

We are treating MCP and other transports as adapters around stable data semantics. Product truth stays in the data contract. The broader idea of an open data-evidence profile is research. It is not a shipping BigdataSight 1.0 capability, a published specification, or a delivery commitment.

One question for data and agent engineers

If an AI agent returns a data verification result, which missing fact makes the result hardest to trust?

The exact table version, snapshot, or object identity
The metadata, files, partitions, samples, or rows it covered
Unsupported features or delete semantics
The expectation or release rule used for the verdict
A reproducible provenance or evidence reference
Something else

A one-number comment is enough, and important to us.😊

Disclosure: We build BigdataSight, a native Mac data workstation. This article describes a post-1.0 research direction, not a shipping 1.0 capability, public protocol, or release commitment.

AI-assistance disclosure: I used an AI coding assistant to help research and edit this article. I reviewed the final argument and the linked specifications before publishing.

The report says verified. Is the change safe to release?

Rui Wang — Wed, 12 Aug 2026 11:30:26 +0000

How to keep table identity, evidence coverage, and release intent separate in a data investigation report.

A schema-change report contains four lines:

Previous state: Delta version 41
Current state: Delta version 42
Schema changes: Verified
Fields added: 1

The feature request expected one new nullable double field named score.
Can version 42 go to production?

Not from those four lines.

The report established an observed change between two table states. It did not
establish that the added field is score, that its type is double, or that
the change matches the feature request. Verified describes the evidence
check. It is not a synonym for safe to release.

The numbers in this article are fictional, but this gap is common whenever a
data report mixes observation and approval.

Two questions, two different answers

A data investigation usually starts with a factual question:

What changed between the two states?

A release review asks a second question:

Did the observed change match what we intended and what consumers allow?

The first answer comes from evidence. The second also needs an expectation or
rule.

Suppose a metadata comparison confirms that version 42 contains one more field
than version 41. That is useful. It narrows the investigation. It still cannot
approve the release because several different changes produce the same count:

score was added as nullable double;
score was added as nullable string;
an unrelated field was added;
score was added, but an existing field also changed type.

All four cases can display Fields added: 1. Only the first matches the stated
request.

What a useful report must preserve

The report needs enough context to stop a reader from silently strengthening
its conclusion.

The exact before and after

“Previous” and “current” are unstable labels. Record Delta versions, Iceberg
snapshot IDs, object versions, or another durable identity.

If the table advances to version 43 five minutes later, another engineer should
still be able to inspect the 41-to-42 edge. Otherwise, the rerun answers a new
question while looking like a reproduction of the old one.

What was actually read

Metadata can support schema, snapshot, manifest, and recorded file-count
claims. It cannot prove a claim about every row.

A bounded sample can reveal a suspicious pattern. It cannot prove that the
pattern is absent outside the sample. A full scan supports stronger row-level
claims only when it covered every relevant partition and applied the table's
delete semantics.

Write the coverage beside the result. Do not hide it in a log or tooltip.

Independent results

One missing check should not erase evidence that was successfully collected.
It should also not disappear behind one green report status.

For example:

Check	Result	Meaning
State identity	Verified	Versions 41 and 42 were resolved.
Schema summary	Verified	One field was added.
Field detail	Incomplete	The shareable report does not include the field path or type.
Row impact	Not checked	No table rows were read.

This report is more useful than either “passed” or “failed.” It tells the next
reviewer what can be reused and what still needs work.

The limitation and the next check

Incomplete is not an error message. It is a result with a missing premise.

In this example, the next check is small: compare the added field's path, type,
and nullability with the feature request. If a local detailed review observes
score as nullable string, the release rule fails. If the detail is not
available, the decision remains incomplete. Neither case should become a pass.

Why this matters to automation

A person may notice that Verified and Fields added: 1 do not answer the
release question. An automated step can make a stronger assumption because the
word looks conclusive.

Giving the same report to an AI agent does not repair missing evidence. The
machine-readable version must preserve the same state identities, coverage,
independent results, and limitations that a person sees. It should not turn an
absent field-level check into approval.

This does not require a giant document. It requires stable meaning. A compact
structured report can say:

which two states were compared;
which observations completed;
what each observation covered;
what remains incomplete;
which rule, if any, produced a decision.

The agent can then combine the report with project context it already has. If
the report contains evidence but no release rule, the agent should describe
the evidence and leave the release decision open.

Five questions before trusting a report

Before accepting a green status, ask:

Which exact before-and-after states were compared?
What metadata, files, samples, or rows were actually read?
Does Verified describe an observation or a decision against an explicit rule?
What missing evidence would make the result incomplete?
Can another person repeat the same check after the table changes again?

If the report cannot answer one of them, narrow the claim. “One field was added
between versions 41 and 42” may be fully supported. “Version 42 is safe to
release” is a different claim.

A BigdataSight development note

In a post-1.0 development build, BigdataSight can generate a read-only
Investigation Report for an opened remote Delta or Iceberg table. The report
brings current-to-previous state checks into one view, keeps section results
independent, and can copy a bounded report without source locations,
credentials, schema bodies, or row values.

The user starts the report explicitly. A completed report does not certify that
the table is correct, compatible, or safe to release. When a bounded check
cannot establish a result, the section remains Incomplete.

This work has passed automated and hands-on development acceptance. It is not
part of the current App Store 1.0 release, and this note does not promise a
release date.

Our broader direction is evidence-backed, local-first data investigation and
reproducible verification, read-only by default. The useful outcome is not a
larger green badge. It is a report whose conclusion cannot outrun its evidence.

One question for data engineers

When you review a data change, which detail is most often missing from the
report?

The exact before-and-after states
What data or metadata was checked
The expected change or release rule
The reason a result is incomplete
Reproduction steps
Something else

A one-number comment is enough. Please do not post confidential data, file
paths, SQL, schemas, credentials, customer information, or screenshots.

If you prefer email, use the one-question prompt on the
BigdataSight research page.

Disclosure: We build BigdataSight, a native Mac data workstation. This article describes a post-1.0 development artifact and its design boundary, not a shipping 1.0 capability or delivery commitment.

Writing note: I developed and verified the technical argument in this article. AI tools assisted with English drafting and editing.

The query succeeded. Which table state did it read?

Rui Wang — Thu, 30 Jul 2026 02:31:28 +0000

Why two successful queries can count different rows when they resolve different Delta or Iceberg table states.

Two queries return different counts for the same Iceberg table:

the catalog query returns 12,480,032 rows;
a direct scan of the storage folder returns 12,691,404 rows.

Neither query fails. The difference is 211,372 rows. The numbers are
fictional, but the investigation problem is real.

Before comparing SQL engines, compare the inputs. The catalog query and the
folder scan may not have read the same logical table.

A lakehouse table is a selection of files

A Delta or Iceberg table may store its rows in Parquet files, but the directory
is not the table definition.

For Delta, a table version is reconstructed from its transaction log. The log
records which logical files were added or removed. A logical file can also
carry a deletion vector that marks rows as no longer present. A file removed
from the current version may remain in storage until a later cleanup.

For Iceberg, a catalog or table reference points to table metadata. That
metadata identifies a snapshot. The snapshot points to a manifest list, and
the manifests identify the data files and delete files used for the scan.

This distinction explains why listing every Parquet object can produce a
plausible but incorrect result. The folder may contain:

files used by the selected table state;
files retained for an older state;
files left by a failed or abandoned write;
data whose rows are changed by separate delete metadata.

The object listing answers, "What exists at this location?" The table metadata
answers, "What belongs to this version or snapshot?" An investigation often
needs both answers.

Work from the selected state outward

Suppose an Iceberg snapshot references 118 data files and 2 delete files. The
storage prefix contains 126 Parquet objects.

Scanning all 126 objects does not prove that the snapshot is wrong. Some
objects may belong to an older snapshot or to no committed snapshot. Ignoring
the 2 delete files can also count rows that the table considers deleted.

Start with the reference the user selected:

Record the catalog, branch, tag, version, timestamp, or other table reference used by the query.
Resolve it to an exact Delta version or Iceberg snapshot ID.
Follow the metadata chain and construct the active data-file and delete-file sets.
Check whether each referenced object is accessible. If the metadata records a length or another identity that can be checked safely, compare that too.
Apply the format's delete semantics before comparing row counts.

Do not begin with the newest-looking metadata filename. In Iceberg, the catalog
or table reference chooses the current metadata. In Delta, the selected log
version and its preceding state determine the snapshot.

Missing and extra files mean different things

A referenced file that the reader cannot access makes the check incomplete.
That observation alone does not distinguish a missing object from a temporary
service or authorization failure.

In Apache Iceberg issue 4168, a user reported a data-file upload failure
followed by a manifest that still referenced the object. A later query failed
when it needed that file. This is an example of the failure shape, not proof
that every inaccessible reference has the same cause.

The safe result is incomplete. Treating an unreadable reference as zero rows
would turn missing evidence into a clean-looking count.

An unreferenced object needs a different interpretation. It might be retained
for an older snapshot, left by an unsuccessful write, or waiting for approved
maintenance. Its presence alone does not prove corruption, and deleting it
during an investigation could damage a state that another reader still needs.

Keep the first check read-only. Determine whether any committed state still
references the object before considering cleanup.

A successful query is one piece of evidence

A successful query tells you that an engine returned rows. Record the exact
table state separately before deciding what the result proves. The result does
not, by itself, establish that:

the query selected the state the user intended;
every metadata reference and object was present;
the reader understood every required table feature and delete type;
another engine resolved the same catalog reference and cached metadata.

When two results disagree, save the selected version or snapshot, active-file
counts, delete-file counts, and unsupported features before rerunning either
query. A rerun against a newer state can erase the comparison you needed.

A small evidence record

The record does not need every metadata field. It needs enough information for
another engineer to repeat the decision.

Field	Example
Question	Why do the catalog query and folder scan differ by 211,372 rows?
Selected state	Iceberg snapshot 711.
Metadata check	Snapshot and manifest chain resolved.
File check	118 referenced data files present; 8 additional objects not attributed.
Delete check	2 delete files apply to the selected snapshot.
Result	Incomplete until the folder scan applies the same active-file and delete rules.

Do not include credentials, signed URLs, private paths, SQL, schemas, customer
information, or raw provider errors in the record.

The two inputs are now specific: snapshot 711, interpreted through its data and
delete manifests, and a scan of 126 physical objects. Make the folder scan use
the same active-file and delete rules, then recount. That check can explain the
211,372-row difference instead of running two vague queries again.

References

One question for Delta and Iceberg users

When a table's state looks wrong, which step usually costs you the most time?

Identifying the exact version or snapshot
Following the metadata chain
Matching referenced files to object storage
Understanding delete files or deletion vectors
Reproducing the same result in another tool
Something else

A one-number comment is enough. Please do not post confidential data, file
paths, SQL, schemas, credentials, customer information, or screenshots.

If you prefer email, use the same one-question prompt on the
BigdataSight research page.

Disclosure: We build BigdataSight, a native Mac data workstation. We are
researching evidence-backed, local-first tools for data investigation,
reproducible verification, and workflows that are read-only by default. The
workflow described here is research, not a shipping capability or delivery
commitment.

Writing note: I developed and verified the technical argument in this article. AI tools assisted with English drafting and editing.

The pipeline passed. The data still needs proof.

Rui Wang — Wed, 29 Jul 2026 13:22:55 +0000

A pipeline job finishes without an error. The new table has 18% fewer rows.
Should you rerun the pipeline, stop the release, or trust the new output?

Before rerunning the job, preserve the two states you need to compare. A rerun
can create another state and make the original change harder to explain. The
first useful question is: which two states are we actually comparing?

Pin down the before and after

"Yesterday" and "latest" sound precise until a file is replaced or a table
advances to another snapshot.

Give both states durable identities. That might mean a file checksum, an object
version, a Delta table version, an Iceberg snapshot, a catalog reference, or a
pipeline run ID. Record the local time and timezone too. They help when logs and
object histories use different clocks.

Suppose a Delta table's row-count drop occurred between versions 842 and 849.
Those two numbers turn a vague report into a reproducible question. Without
them, another engineer may inspect version 850 and reach a different conclusion.

Test the smallest useful explanation

An unexpected nullable column and a lower row count point to different first
checks.

If a column became nullable, compare the two schemas before scanning rows.
Check whether the field changed type, moved inside a nested structure, or was
renamed. A CSV inference change and a Parquet schema change may look similar in
a grid, but they are different events.

If the row count changed, group counts by the partition or date most likely to
explain it. A full profile of every column may cost more than the original query
while hiding the useful difference.

Delta and Iceberg add another question: which logical table state did the
reader resolve? The newest objects in storage do not necessarily belong to the
selected state. Check the version or snapshot, the metadata chain, and the data
or delete files involved before blaming an individual file.

The aim is a smaller search area. A larger report can wait until the evidence
calls for one.

State what the check can prove

The same finding means something different when it comes from metadata, a
sample, or every relevant row.

Metadata can establish recorded schema, partition information, and available
statistics. It cannot prove a claim about every row. A sample helps discover a
pattern, but a missing value in the sample does not prove that the value is
absent. A full scan supports stronger row-level claims, provided it covered
every relevant partition and delete.

Record truncation, skipped objects, unsupported semantics, cancellation, and
fallback behavior. If one of them prevents a conclusion, call the result
incomplete. That is more useful than a clean-looking result with a hidden gap.

Leave evidence another engineer can challenge

A short record is enough when another engineer can understand the decision and
repeat the check.

A fictional record might look like this:

Field	Recorded value
Question	Why did the table lose 18% of its rows?
Inputs	Delta table versions 842 and 849.
Checks	Schema comparison and row counts grouped by day.
Scope	Metadata plus a full scan of the affected partition.
Outcome	Warning. The drop is isolated to July 25, 2026.
Limit	Delete semantics were not checked, so the cause remains unproven.

Keep credentials, signed URLs, private paths, secret-bearing SQL, customer data,
and private screenshots out of the record.

Before running the checks, define the finish line:

Pass means the stated rule held over the recorded scope.
Warning means the result needs review.
Failure means the evidence disproved the rule.
Incomplete means the available evidence cannot support a conclusion.

Leave enough evidence for another engineer to reproduce the result, disagree
with it, and run the investigation again.

One question for data engineers

Which part of this work usually costs you the most time?

Understanding an unexpected schema change
Finding why row counts or profiles changed
Understanding the real state of a Delta or Iceberg table
Comparing pipeline output before and after a change
Proving that a delivery or release is safe
Something else

A one-number comment is enough. Please do not post confidential data, file
paths, SQL, schemas, credentials, customer information, or screenshots.

If you prefer email, the same one-question prompt is available on the
BigdataSight research page.

Disclosure: I build BigdataSight, a native Mac data workstation. We are
researching evidence-backed tools for investigating changes in files and
lakehouse tables. The product direction described here remains research and is
not a shipping capability.

Writing note: I developed and verified the technical argument in this article. AI tools assisted with English drafting and editing.