Say what the client does when the data is wrong

[kumo-isaac]

An agent using the relational skill had no way to know what this client does when the tables have a problem in them. Some problems are refused, some are warned about and answered, and some are answered without a word. The last kind matters most, because nothing tells the caller.

What this adds

skills/relational/references/data-problems.md is a new standalone reference.

• One table, twenty problems found in real tables: a repeated key, a foreign key that matches nothing, integer or out-of-range dates, numbers stored as text, a list in a column, and so on. For each one it gives:
  • whether the client refuses, warns or says nothing
  • the words it uses (the error code and the quoted part of the message)
  • what to do about it
• Key, time and link inference, covering the one silent case: a key is only inferred from a column whose name ends in id/key. A surrogate customer_id beside the customer_code that other tables point at is taken as the key without a word, and a FOR EACH customers.customer_code query is then refused.

Links to the new page are added from skills/relational/SKILL.md ("Describing the data") and from the reference table in skills/README.md.

How it is held true

tests/test_skills.py covers every row:

• Each row is reproduced on the skill's own example frames with one thing wrong, then held to the stated verdict and the quoted words.
• A warning counts only if the clean frames don't also raise it.
• For a "says nothing" row, any new warning fails the test.
• The new table is listed in EVERY_TABLE as read, and the inference bullets have tests of their own.

Nothing here needs an endpoint. Everything happens in Schema.from_data and materialize().

The behaviours were first measured on 45 synthetic datasets, each with one problem injected, run through Schema.from_data → materialize() at 327fda0. The tests reproduce them here at small scale.

Checks

• pytest tests passes: 264 passed, 46 skipped (live_nim)
• pytest packages/structured-data-models-client/tests passes: 1790 passed
• ruff check . and ruff format --check pass
• scripts/check_repo_hygiene.py all passes
• -m live_nim: not run, no endpoint available. The new file has no examples, so no live test applies to it.

🤖 Generated with Claude Code