Skip to content

D8 arms: the text cut without word-bound claims, and an attribution instruction (#316, under #305) - #317

Merged
holden merged 2 commits into
mainfrom
claude/d8-lexeme-claims-attrib
Nov 6, 2026
Merged

holden merged 2 commits into
mainfrom
claude/d8-lexeme-claims-attrib

Conversation

@holden

@holden holden commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

D8 under #305 (#316): the two changes to D7's nudge arm, each on its own seam, so the batch can measure them apart as a 2 × 2. Comparison-only. Nothing here touches the live cut, the publishing path, a configuration, mix.lock or a migration, so it deploys by fast-forward with no restart.

What changes

1. The cut whole-entry-text-cut-v2 (Packet, text2 in Compare)

  • It is the text cut, plus one rule: a claim whose bound meaning is a word (m*) is not offered. These are the lexeme_entity_candidate path of LinkedClaims.for_scope/2, where the claim's subject is the lexeme. Sense-bound refers_to claims are offered as before.
  • Each omitted claim is recorded as lexeme_claim_excluded, beside text_cut_excluded in cut/4, before the quotas. The claim kind's unused room flows down, and the freed slot is refilled exactly as the text cut refills.
  • whole_entry_cuts/0 and omission_reasons/0 list the new cut and reason, and Coverage's omission list names the reason so the comparison report counts it rather than calling it unknown. Compare's cut table gains "text2" => "whole-entry-text-cut-v2", and dd.runtime's usage line names it.
  • Unchanged: text_bearing?/1, the quotas, whole-entry-cut-v1, the evidence fingerprint and the publishing path.
  • No packet-version change. freeze/2 accepts the new packets because their omitted reason is listed. verify/1 never reads the cut's name.
  • The prompt never carries the cut's name. On a page with no word-bound claim, text2's candidates, fingerprint and prompt equal text's; only the packet hash differs, through policy.cut.

2. The instruction voltaire-whole-entry-v7-fixed-lead-cap200-nudge-attrib-v1 (sha256 6938459b2118d8b9670ffa9ede62e4da8e776f408623f280bd89b28408344e1e)

  • It is nudge-v1's text with one paragraph, #305 D8: the nudge arm without lexeme-bound claim records, and with an attribution rule, measured apart (2 × 2), batch d8-<date> (under #305) #316 §3b's ATTRIBUTION IN REASONS (Packet.attribution_section/0, sha256 5dd2e125…), inserted after the AFTER THE LEAD section and before OUTPUT AND SAFETY. It is built with the same string-replace pattern as the nudge.
  • It is pinned in Packet, and named in WholeEntry's comparison, fixed-lead and cap tables (200). That gives it selection-output-v5 by Contract's existing raised-cap rule.
  • The compile-time guard still holds: only a comparison instruction may raise its cap, and only to 200.
  • Every existing pinned sha is unchanged; nudge-v1 is still ac08a3d8….

Tests

comparison_instructions_test.exs:

compare_test.exs, on the love fixture with a title-match claim added:

  • v2 omits the word-bound claim as lexeme_claim_excluded and keeps the sense-bound ones; v1 and the live cut keep both.
  • With the 24-candidate cap binding, the one candidate v2 drops is that claim, and the one it adds is a text-bearing candidate that v1 omitted as over quota. Every offered candidate is accounted for exactly once, and the count equals counts.offered.
  • Arms sharing a cut share a fingerprint.
  • A v2 packet freezes and verifies under runtime-packet-v4.
  • With no word-bound claim, v2's fingerprint and prompt equal v1's.
  • The comparison report counts the new reason by name.
  • parse_arms/1 accepts :text2.

packet_test.exs:

  • The pinned-instruction list.
  • The cut list and omission reasons.
  • A text cut still needs a whole-entry instruction, and an unknown cut is refused.

Checks at head 59733e9:

  • mix precommit in a private partition (MIX_TEST_PARTITION=_d8a, MIX_ENV=test DD_NO_OBAN=1): 19 doctests, 3,416 tests, 0 failures. The only warnings are the test build's migration-module redefinitions, which predate this PR.
  • Two independent exact-head reviews by fresh subagents found nothing REQUIRED. The first, at 427060c, made six RECOMMENDED points; 59733e9 applies five of them. The sixth, the dry run's per-page list of excluded claims, is met by the run folder's read-only expiry.exs. The second review, at 59733e9, is posted below.
  • CodeRabbit did not run. The CLI is signed in, but its GitHub access needs re-authorising.

Not in this PR

  • The run folder, run/d8-<date>/, which is outside the repository.
  • The new model config, registered at the run on the owner's yes.
  • The batch itself.

The live cut may one day retire word-bound claims too. That is a publishing-path change, and it waits for a qualifying arm (#316 §10).

Refs #316, #305.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Added a comparison option that excludes word-bound claims while retaining sense-bound claims and refilling available candidate slots.
    • Added an attribution option that limits named people, works, sources, and dates to details provided in the candidate information.
  • Documentation
    • Updated comparison guidance with the new options, setup and dry-run commands, and examples of supported arm pairs.

holden and others added 2 commits November 5, 2026 07:16
…ction (#316)

Two comparison-only seams for #305's D8, measured apart as a 2 x 2:

- whole-entry-text-cut-v2 (`text2`): the text cut that also omits every
  claim bound to a word meaning (m*, the lexeme_entity_candidate path) as
  lexeme_claim_excluded, before the quotas, so the freed slot flows down
  and is refilled as the text cut refills. Coverage names the reason.
- voltaire-whole-entry-v7-fixed-lead-cap200-nudge-attrib-v1: nudge-v1's
  text with one ATTRIBUTION IN REASONS paragraph after the after-lead
  section, at cap 200 under selection-output-v5.

The live cut, the publishing path, configuration and migrations are
unchanged; every existing pinned sha holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The independent review of 427060c found nothing required. Its
recommendations, applied:

- The refill test counts every offered key once (sorted lists, no
  duplicates, equal to counts.offered) instead of comparing sets.
- The first D8 test adds a live-cut arm, which still offers the
  word-bound claim and never omits it as lexeme_claim_excluded.
- Coverage reads its omission reasons from Packet.omission_reasons/0.
- Docs: text2 sends what text sends only where the page's pool offers no
  word-bound claim (meaning places are ranked by citations); the cut list
  names text2; the fingerprint rule names D8's arms; the packet moduledoc
  lists every omission reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Explain Change →

Caution

Review failed

The pull request is closed.

Walkthrough

The whole-entry comparison flow adds a text2 cut that excludes word-bound claims and refills available slots. It also adds a cap-200 nudge instruction variant with attribution constraints. Tests and runtime documentation cover both additions.

Changes: D8 comparison variants

Layer / File(s) Summary
text2 cut and comparison flow
lib/devils_dictionary/curation/runtime/packet.ex, lib/devils_dictionary/curation/runtime/compare.ex, lib/devils_dictionary/curation/coverage.ex, lib/mix/tasks/dd.runtime.ex, test/devils_dictionary/curation/runtime/compare_test.exs, test/devils_dictionary/curation/runtime/packet_test.exs, docs/curation/runtime-operations.md
The text2 cut excludes word-bound claims with lexeme_claim_excluded before quota selection, then refills available slots. Arm parsing and omission reporting support the cut. Tests cover exclusions, refills, fingerprints, and packet verification.
Attribution instruction arm
lib/devils_dictionary/curation/runtime/packet.ex, lib/devils_dictionary/curation/whole_entry.ex, test/devils_dictionary/curation/runtime/comparison_instructions_test.exs, test/devils_dictionary/curation/runtime/packet_test.exs, docs/curation/runtime-operations.md
A new instruction variant adds a paragraph that restricts named people, works, sources, and dates to information in candidate fields. The variant uses the 200-character reason cap and is included in comparison configuration. Tests check the instruction text, digest, schemas, and reason validation.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

  • razrfly/dictionary#316: This issue specifies the text2 cut and attribution instruction added by this change.
  • razrfly/dictionary#305: This change adds D8 comparison variants for the tracked offline policy experiments.
  • razrfly/dictionary#311: This change extends the D7 nudge and cap work with an attribution instruction and a word-bound-claim cut.
  • razrfly/dictionary#193: This change continues the offline packet-policy experiments described in the delivery tracker.

Possibly related PRs

  • razrfly/dictionary#312: This PR extends the cap-200 nudge instruction introduced there with an attribution paragraph.
  • razrfly/dictionary#303: This PR extends the text cut and comparison flow with word-bound-claim exclusions and a new omission reason.
  • razrfly/dictionary#279: This PR adds a comparison cut to the whole-entry selection flow and refills candidates within its existing bound.
Merge Risk: Minimal · up to 59733

No concrete issue requiring a change before merge was established; proceed with normal checks.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@holden

holden commented Nov 6, 2026

Copy link
Copy Markdown
Member Author

Independent exact-head review of 59733e9

Branch claude/d8-lexeme-claims-attrib, worktree .claude/worktrees/d8-claims-attrib, git rev-parse HEAD = 59733e97aad520d418becc8232cbb17efd501418 (checked before and after the review). Range reviewed: git diff decb956 59733e9, two commits (427060c, 59733e9), 9 files. Design: private/issues/2026-11-05-305-d8.md (#316), §2–§3b, §5 R1, §10.

Read-only: git and file reads only. No mix, no tests, no database, no server. I did not run the suite, so the new sha pin (6938459b…) and the green state are the test run's to confirm. My check of the instruction text is structural (below).

Verdict: nothing REQUIRED. Both changes do what §3a and §3b ask. The live cut, the publishing path, every existing pinned text and sha, config, mix.lock and migrations are unchanged. Safe for a no-restart fast-forward.

REQUIRED

None.

RECOMMENDED

R1. The compare dry run cannot show what §5 R1 expects to read from it

§5 R1 expects the dry run to show "lexeme_claim_excluded omissions on exactly the pages where a lexeme-bound claim is offered … and the per-page list recorded", plus "the earliest expiry per case". compare_lines/1 (lib/mix/tasks/dd.runtime.ex:563–610) prints only these things per arm: fingerprint, packet hash, candidate count, priority and fixed lead. It prints no omissions by reason and no expiry. --dry-run writes no record (dd.runtime.ex:321–323). Both values do exist: Compare.prepared_record/1 holds them as omitted_by_reason and earliest_expiry (compare.ex:514–533), and so does snapshot["earliest_expiry"]. But they reach a file only in the batch record a real run writes.

The earliest-expiry gap predates this PR. Stage 1's R1 asked for the same two observables. The lexeme_claim_excluded list, though, is new to D8 and is the main pre-call check of the new cut. As things stand, R1 cannot be ticked from the command it names.

Either:

  • print omitted_by_reason on each arm's dry-run line and the snapshot's earliest_expiry on the case line. This only changes what is printed, never a packet or a prompt; or
  • amend R1 so the per-page list is taken from the batch record (cases[].prepared[].omitted_by_reason) after the run.

Tell the executor one more thing either way. The cut omits every word-bound claim in the page's pool, not only those text would have sent. A page can therefore show lexeme_claim_excluded while N and NX have equal fingerprints, and a page can show more than one. On a new snapshot, "love, hope, bestiality, one each" is a lower bound, not the expected list.

R2. The docs name one route by which text2 can differ from text; there is a second

docs/curation/runtime-operations.md (D8 paragraph) says that where the pool offers a word-bound claim that text leaves out, text2 "may still differ through the meaning places". That is correct: bound_meanings/4 counts citations over offerable (packet.ex:678, 850), and offerable no longer holds the claim.

There is a second, rarer route through refill/2 (packet.ex:797–830):

  1. Under text, the word claim lands in acc.over (over quota).
  2. During the refill it is skipped for the meaning bound: its m* is not kept and 12 meanings are already kept.
  3. Under text2 the claim is absent, so every later claim in the claim row moves up one index in the round-robin turns.
  4. When the 24-candidate cap binds in between, the chosen set or its order (and so the c* ids) can change.

The closing advice, that the dry run's fingerprints say which pages differ, still covers both routes. Suggested wording: "may still differ (meaning places, refill order)". This also qualifies §3a's "What this bounds" sentence ("On a page where no lexeme-bound claim is offered, text2 keeps text's candidate set"). That sentence is exact only when "offered" means offered in the pool. The code applies the rule exactly as §3a defines it (omitted before the quotas, beside text_cut_excluded), so this is a prediction to correct, not a defect.

R3. No test pins the pool-level behaviour the docs describe

The D8 tests cover:

  • a word claim that text sends (tests 1, 2 and 4);
  • a page with no word claim in the packet (test 3).

None covers a word-bound claim that is in the pool but that text leaves out (for example, ranked below two sense-bound claims by basis["rank"]). That case would show that lexeme_claim_excluded is still recorded, that the candidate set is unchanged on a small page, and that the accounting stays one entry per offered key.

None covers a word-bound claim on a second word's meaning (m1) of a page with two words. The code handles both, since words is built from every {:lexeme, _} target in the universe (packet.ex:643), but no test pins either.

R4. Coverage now depends on Packet at compile time

coverage.ex:24 @omissions Packet.omission_reasons() calls a function in the module body, which makes it a compile-time dependency. It is correct and it fixes a real gap: before this change, the hard-coded list would have reported lexeme_claim_excluded as "unknown", and test 4 proves that no longer happens.

The cost: Coverage now recompiles whenever Packet does, and, because the dependency is compile-connected, whenever any of Packet's many runtime dependencies change. It is harmless for a hot reload. Coverage is a leaf (nothing depends on it at compile time), there is no cycle, and the parallel compiler orders it after Packet. The codebase already follows this pattern (Contract, SectionOutput and EvidenceGuidance read WholeEntry at compile time).

If the wider recompile surface matters, defp omissions, do: Packet.omission_reasons() keeps it a runtime dependency. Optional.

R5. Wording nits

  • packet.ex:38–39 (moduledoc): "the text cuts' text_cut_excluded and lexeme_claim_excluded" reads as though both text cuts emit both reasons. Only v2 emits lexeme_claim_excluded.
  • packet.ex:792 ("The text-focused cut's refill") and text_bearing?/1's doc ("the text-focused cut") now apply to both text cuts.
  • compare.ex:10–14: the reflow leaves a ragged line ("D8). Arms that differ in instruction").

What I checked and found sound

1. The new cut (packet.ex cut/4, by_quota/3, refill/2, bound_meanings/4, usable/3)

  • What gets omitted. words is the set of universe meaning ids whose target is {:lexeme, _}, exactly the m* ids that meanings/2 assigns. usable/3 gives each candidate its universe meaning id. So kind == "claim" and meaning in words is exactly "a claim bound to a word meaning".
  • Equivalence with the design. In LinkedClaims.for_scope/2 (linked_claims.ex:73–86), {:lexeme, _} arises only on the direct path for lexeme_entity_candidate. A refers_to subject is always among senses, so it always gets {:sense_revision, _}. The rule therefore equals "the lexeme_entity_candidate path", as the docs say.
  • Scope of the rule. It runs only when policy.cut == "whole-entry-text-cut-v2". Sense-bound claims, exemplars, content bound to m0, and every other kind pass through. Priority candidates (content only) are split off first, and claims are text-bearing, so the two exclusions never overlap.
  • Placement. It runs before by_quota/3, beside the text_cut_excluded split, as §3a asks. The claim kind's unused room carries to shelf (@kinds order). refill/2 runs for both text cuts (policy.cut in @text_cuts, packet.ex:780), and word claims never enter acc.over, so the refill cannot bring one back.
  • Accounting. Every offered candidate ends up in exactly one place: unusable, text_cut_excluded, lexeme_claim_excluded, or by_quota (chosen, over_quota, or meaning_out_of_bound, with refill removing the omission of anything it picks). Each omission has exactly key, kind, object_id and reason, sorted by key with the text-cut exclusions.
  • v1 and live cuts unchanged. For whole-entry-text-cut-v1, word_claims == [], and the new excluded expression equals the old one (same input order, stable sort_by), so v1 packets are byte-identical. For the live cut both lists are empty. for_page/2 sets a cut only when the caller passes :cut; no live or publishing caller does. whole_entry_cuts/0, the :unsupported_cut check and :cut_needs_whole_entry_instruction all cover v2. fingerprint_version/1, the refresh path and Endpoint are untouched.

2. Freeze, verify and other callers

  • Freeze and verify. freeze/2 → shape/2 → omission?/1 accepts the new reason through @omission_reasons. The packet stays runtime-packet-v4. verify/1 re-derives sent candidates only and never reads omitted. evidence_fingerprint/1 excludes policy and omitted. messages/1 sends no policy, so the prompt does not carry the cut name. summary/1 keeps omitted and policy.
  • Every caller in lib/:
    • Compare: @cuts gains text2 correctly. arm_record records the cut_version; matched? groups by arm cut label; the expiry check uses the shared snapshot.
    • Coverage: groups by policy.cut and now names the reason.
    • dd.runtime: help text updated; arms parse through Compare.parse_arms/1.
    • curation_live/attempt.ex, Rehearsal, Proposals: render or count reasons generically.
    • No other code hard-codes a cut name, an omission reason or a comparison instruction name; I searched lib/ and priv/repo/.

3. The instruction voltaire-whole-entry-v7-fixed-lead-cap200-nudge-attrib-v1

  • Text equals nudge-v1 plus one paragraph. Both texts are built from @whole_grounded_fixed_lead. The cap sentence becomes "…under 200 characters." in both, since reason_cap is 200 for each. @output_header is replaced by @after_lead <> @attribution <> @output_header instead of @after_lead <> @output_header. The guard at packet.ex:402–404 proves @output_header occurs exactly once. So the text is nudge-v1's with only the paragraph inserted, after AFTER THE LEAD and before OUTPUT AND SAFETY.
  • Paragraph matches the issue byte for byte. I compared the heredoc lines against the issue's §3b quote with a script: identical, ASCII apostrophe, no trailing spaces. It is followed by one blank line, as @after_lead is.
  • Listed where §3b says. It is in @instructions, WholeEntry.@comparison, @fixed_lead and @reason_caps (200). The compile-time guard at whole_entry.ex:63–65 is intact and satisfied. Contract.version/1 derives selection-output-v5 from @raised_cap. SectionOutput and EvidenceGuidance admit it through comparison_instructions/0. The publishing list, the configuration CHECK and the author guard are unchanged.
  • Nothing pinned changed. No existing instruction attribute or pinned sha was edited (the test diff only adds the @attrib pin, 6938459b…). N and NA therefore differ only in the system text: same user packet, same evidence guidance, same schema at cap 200.

4. Tests

  • The attribution test is strong. It asserts String.replace(attrib, paragraph, "") == nudge, the paragraph's position, a line diff with no deletions, the paragraph literal, the single occurrence and the sha.
  • The D8 cut tests would fail with the feature broken.
    • Test 1 fails if v2 drops sense-bound claims, if v1 or the live cut drop the word claim, or if the omission is not recorded.
    • Test 2 fails if anything else is dropped, if the freed slot is not refilled under the 24 cap, or if accounting duplicates or loses a key.
    • Test 3 fails if v2 changes a page with no word claim (that page has sense-bound claims, so dropping all claims would change the fingerprint).
    • Test 4 fails without the Coverage change ("unknown").
  • The packet_test additions cover the cut list, the reasons, :cut_needs_whole_entry_instruction and :unsupported_cut for both text cuts.

5. No-restart deploy

  • No hard-to-reload files. No config/*.exs, mix.lock, migration or supervised-process change.
  • Recompiled set. WholeEntry changed, so its compile-time dependants recompile: Packet (reason_cap/1 in attributes), Contract, SectionOutput, EvidenceGuidance, and now Coverage (on Packet). All are tracked dependencies and none is cyclic. The new WholeEntry guard holds, so compiling raises nothing.
  • Running code. The changed modules are stateless function modules, so an in-flight call is unaffected by the reload.
  • Formatting. The longest new code line is 98 characters (packet.ex:647), within the formatter's limit.

6. Docs

runtime-operations.md is accurate about:

  • the cut list;
  • the D8 arms and setup commands (switches the runbook test parses);
  • "N = NA, NX = NXA";
  • the fact that the prompt does not carry the cut name;
  • what the dry run prints.

The moduledocs (Packet, Compare, WholeEntry comments) are accurate apart from the nits in R5. §10 scope is respected: no live-packet change, no persona, Stage 3 or #309 file in the range.

Round history (added by the executor)

  • Round 1, at 427060c: a fresh subagent, read-only, found nothing REQUIRED and made six RECOMMENDED points. 59733e9 applies points 2–6:
    • the refill test now counts every offered key once (sorted lists, no duplicates, equal to counts.offered);
    • a live-cut arm shows the live cut still offers the word-bound claim;
    • Coverage reads its omission reasons from Packet;
    • three docs fixes.
      Point 1, the dry run's per-page list of excluded claims, is met outside the repository by the run folder's read-only expiry.exs, from the same freeze as compare --dry-run.
  • Round 2, at 59733e9: this review. Its RECOMMENDED points stay open as notes. None changes a packet, a prompt or a test outcome, and the run folder takes R1 and R2 into account (pool-level exclusions are a lower bound; the dry-run fingerprints are the authority).
  • Precommit at 59733e9: 19 doctests, 3,416 tests, 0 failures, in a private partition.
  • CodeRabbit: not run. The CLI's GitHub access needs re-authorising.

@holden
holden merged commit ed22b60 into main Nov 6, 2026
1 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant