Skip to content

feat(profile): children per parent for every declared relationship - #1026

Merged
fas89 merged 1 commit into
mainfrom
claude/profile-children-per-parent
Nov 19, 2026
Merged

fas89 merged 1 commit into
mainfrom
claude/profile-children-per-parent

Conversation

@fas89

@fas89 fas89 commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

What this does

fluid profile counts children per parent for every semantics.relationships entry whose two exposes are profiled in one call, without --bundle. The document's existing top-level relationships[] (PROFILE-SPEC §5, format unchanged) carries a marginalHistogram/1 with the parent as unit, on the bins 0, 1, 2, 3-4, 5-9, 10-19 and 20 or more (the last bin ends at 2^53 - 1, so no count is cut to fit).

  • Keys are matched as the registry reads both columns; a null key matches none. Entries come in the contract's order, whatever order the call names the exposes in.
  • A relationship whose target is not profiled in the call, declares a validity window, has keys read in different domains, or whose fromColumns and toColumns are not two lists of one length is named in the summary and left out.
  • The child's foreign key withholds its distinctCount, sum, min, max and quantiles (D) and forms no mean/1. The key columns of a counted relationship take no default statistic of their own.

This was part of #1024 and moved to its own PR after the pre-merge re-check found a further disclosure channel. It sits on top of 0.36.0.

Disclosure

The output check sees the parents' cells and their total. A reader can know more. Other tables over the same parents (an enum column's level histogram, another relationship's cells) bound their number. The children's own counts bound what they hold, since each child row has at most one parent and each parent holds between its bin's edges.

So disclosure.pinned_children_cells audits every withheld cell against the strongest reader. That reader knows the exact number of parents, of children and of parents whose key is null, plus the published bands and the check's own rule (the withheld cells never total a small count). A withheld cell stands only where two tables that reader can hold true differ in it. The second table is found by moving one parent and, when the children's bounds break, as many more as repair them. The search errs toward withholding. runner._audited_children withholds the published cell of the highest edge until no cell is pinned, down to the whole histogram, which is where parents with few children often land.

universe, children unbounded, none an orphan worlds reader rules pins
a band of children split over a band of parents every way (in the suite) 875 and 4,700 the document ACRO 0 (14 without the audit)
the same, larger bands 16,480, 51,170 and 144,962 the document ACRO 0
up to 7 parents and 14 children (in the suite) 1,613 the document, the exact numbers of parents and children the 4 scaled rules, exact counts included 0
cells per bin over ranges, every children total 241,332 the document, and the exact numbers ACRO 0

The review found and closed four channels:

  • the children's counts beside a published cell of no child forced a high bin's zero;
  • other tables over the parents bound their number tighter than the row count;
  • an enum key's level histogram, or a number key's histogram or quantiles, counted each parent's children;
  • the foreign key's own sum, extremes and quantiles described each parent's children key by key.

Tests cover the re-check's worlds (503 parents, 23 parents, an enum over the parents beside the relationship, two relationships into one parent), enum and number keys, and the reader's two bounds, each with a test that fails when its clause is removed. With exact counts the children's total is exact too, and the case the earlier audit kept as an expected failure now passes.

Reviews

  • Security and disclosure review: BLOCK twice, once for enum keys and once for number keys. Both are fixed. It gave SHIP at the final commit, with its one LOW folded in.
  • Defect scan: one MEDIUM (two reader facts had no failing test), fixed. Its brute-force check of the reader model over 120 random tables found the search never missed a pin; it only withholds more than it must.

Validation

  • Gates on the commit: ruff, the dead-code gate, black 24.10.0, scripts/mypy_strict.py, import contracts, license headers, the product guardrail, and a secret scan of the touched files. All pass.
  • Tests (tests/profiler, tests/fluid_sql, the quality engine's column rules, the lazy command table, bootstrap): 2,616 passed, with only the three failures this shared environment has on main too.
  • The audit's cost: about 1 s for 100,000 parents with 300,000 children.

Follow-ups

  • A forge_docs page for children per parent.
  • The engine's fluxsim init does not read relationships[] yet, and must accept an entry whose only group is withheld.
  • The witness search is two moves deep, so it withholds more than an exact solver would.

When one call profiles both exposes of a semantics.relationships entry,
without --bundle, the profile's existing relationships[] (PROFILE-SPEC
section 5, format 1-0-0/1-1-0 unchanged) carries a marginalHistogram/1 with
the parent as the unit: each parent row counts once, by its number of child
rows, on the bins 0, 1, 2, 3-4, 5-9, 10-19 and 20 or more. The last bin ends
at 2^53 - 1, the largest count a profile holds, so a parent with many
children is counted where it belongs and no value is cut to fit.

- keys are matched as the registry reads both columns, so 7 and "007" agree
  where the type is a number; a null key, on either side, matches none;
- the histogram is formed by the registry's own definition
  (StatisticsBackend.count_histogram) and checked by check_edge_counts in a
  call of its own, as flux-stats 0.7.0 documents for a relationship's count
  of children, then spelled as a column's histogram is;
- the child's foreign-key columns withhold their distinctCount, sum, min,
  max and quantiles (D) and form no mean/1: the parents with a child, beside
  the parents' row count, give those with none, and the key's own values
  describe each parent's children key by key;
- a relationship whose target is not in the call, declares a validity window,
  or whose keys are read in different domains, or whose fromColumns and
  toColumns are not two lists of one length, is named and left out;
- the key columns of a counted relationship take no default statistic of
  their own: a key's level histogram, histogram or quantiles count each key's
  rows, and the child key's rows are each parent's children;
- relationships[] lists them in the contract's order, whatever order the call
  names the exposes in, so the document's bytes do not depend on it.

The output check sees the parents' cells and their total only. A reader can
know more: other tables over the same parents (an enum's level histogram,
another relationship's cells) bound their number, and the children's own
counts bound what they hold, each child row having at most one parent and each
parent between its bin's edges. disclosure.pinned_children_cells takes the
strongest reader, who knows the numbers of parents, of children and of
parents whose key is null exactly, besides the published bands and the
check's own rule (the withheld cells never total a small count). A withheld
cell stands only where two tables that reader can hold true differ in it,
found by moving one parent and, if the children's bounds break, as many more
as repair them; the search errs toward withholding. runner._audited_children
withholds the published cell of the highest edge until no cell is pinned,
down to the whole histogram.

The disclosure audit splits a band of children over a band of parents every
way, children unbounded and none an orphan, under ACRO's rule: 875 and 4,700
worlds in the suite and up to 144,962 beside it pin nothing, where the check
alone left 14 pins in the first. Keyed by the exact numbers of parents and
children, up to 7 parents and 14 children pin nothing under every scaled
rule, exact counts included, so the exact-count case is closed too. Tests
cover an enum over the parents beside the relationship, two relationships
into one parent, and enum and number keys.

ProfileResult is read through its tables (and relationships) only: the
one-table shortcuts kept beside them (plan, statistics, withheld_statistics,
partly_withheld_statistics, left_out) go, and the tests read tables[0].
@github-actions github-actions Bot added cli Changes to the CLI surface or implementation tests Test coverage or test infrastructure changes needs-docs Pull request needs a linked docs update or justification labels Nov 19, 2026
@github-actions

Copy link
Copy Markdown

📄 Documentation Reminder

This PR appears to be missing a documentation reference. Our docs live in a separate repo.

Please update the PR description with one of:

  • Link a docs PR — check the "Docs PR linked" box and paste the URL
  • Mark as no docs needed — check "No docs needed" with a justification
  • Acknowledge docs TODO — check "Docs TODO" and create the docs PR before merge

See the Contributing Guide for details.

@fas89
fas89 merged commit cfacd70 into main Nov 19, 2026
34 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cli Changes to the CLI surface or implementation needs-docs Pull request needs a linked docs update or justification tests Test coverage or test infrastructure changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant