Opt-in LawSet consolidation¶
LawSet.consolidate(candidate, buffer, exclude=None, commit=True) addresses a
patchwork of at least two strictly narrower laws with the same action and effect.
It returns the replacement law, or None. Ordinary test() still requires
positive net error reduction against the original active book.
For example, a book containing leap & on -> yes and leap & off -> yes
already answers correctly on 60 held-out leap rows. leap -> yes has original
net zero, so test() refuses it. Explicit consolidation may replace the two
laws after testing the general candidate on all 60 matched rows. It then also
answers yes for leap & mid, which the old book did not cover.
This is empirical compaction, not additional evidence of prediction improvement
and not a guarantee for unseen inputs. The caller opts into extending the answer
to the candidate's declared condition. If that extension requires a domain
guarantee, the caller must establish it separately; confirm(candidate) can
enforce an application validator. Observed matching counterexamples are included
even if an existing exception would hide them under support_on="applied".
In particular, a candidate with condition () must pass on every held-out row of
its action. No claim is made about historical multi-seed quality results.
The condition is canonicalized by Grammar.check before selecting subsumed laws
or spending candidate budget: duplicate atoms collapse, invalid atoms, feature
combinations and condition lengths raise ValueError.
The transaction uses a private trial book with the proposed subsumed laws removed.
It forces matched support for this candidate and uses ordinary test() gates:
grammar, readmission, cap, positive counterfactual net, minimum support,
precision, sized binomial bound/null, rivals, confirmation and the post-admission
check. Existing leftover-probe falsification is also enforced. Buffer candidate
accounting retains the same candidate identity and multiplicity budget; a
committed attempted test spends its candidate in Buffer.tested even if refused.
A full book can compact when removal makes room; the resulting book obeys cap.
Before committing, every previously correct allowed held-out row must remain
correct, the replacement must remain active, and every other active law must
survive. This prevents an overlapping contrary rule from silently making the
replacement lose correct predictions when priorities change. Rejection or a
confirmation exception changes no active or retired laws. Confirmation is a
read-only predicate: writes to this owning set's book containers, counters and
existing Law fields are rolled back on False, exception and True. Nested
consolidate calls from confirmation are refused. External callback effects,
grammar/buffer mutations and writes inside shared action/effect/group payload
objects cannot be sandboxed and are outside this rollback scope. Callbacks must
not mutate those objects. Failed committed attempts, including callback exceptions,
still update candidate and test-cost accounting as ordinary attempted admission does.
On success the same original Law objects become retired with reason
subsumed by <replacement-id>. The replacement's admitted is
"consolidation"; its consolidation dictionary records the replaced IDs,
held-out source IDs, original net, counterfactual net, old/new correct counts,
excluded group and domain_guarantee=False. Its ordinary net field is the
counterfactual net from the trial book, not error reduction against the original
book. Original source IDs are not recycled as new independent evidence. Normal
independent observation, checking, suspension/retirement and pickle persistence
continue to apply to the replacement.
commit=False performs the same evidence checks on a private buffer, returns a
status="proposed" law, skips the external confirmation callback, and changes
neither the original book nor its candidate budget. It can be replayed to inspect
the proof before committing. A proposed law is conditional on later confirmation.
The initial API intentionally refuses compaction when the candidate has no
positive net even against the book with the subsumed laws removed (for example,
an already-correct base). It does not implement arbitrary semantic implication,
effect equivalence, automatic consolidation during step(), or a statistical
comparison proving that a broader rule is better than its patchwork.
Deterministic regression coverage is in tests/test_laws_consolidation.py:
the original leap/on/off witness under both support modes, unseen mid behavior,
contrary matched rows and defaults, retained overlaps, sized/support/net gates,
readmit/falsification and exclusion, cap, confirmation rejection/exception,
read-only replay, pickle and independent falsifying observations.