core/docs/sessions/quantity-entity-implementation-preflight-2026-06-20.md

PREFLIGHT: binding.quantity_entity Implementation Map

Agent: gpt55 Date: 2026-06-20 Target Branch: docs/kernel-quantity-entity-implementation-preflight Controlling Authorization: docs/sessions/quantity-entity-foundational-slice-authorization-2026-06-20.md

This document maps the exact implementation paths and boundaries for the upcoming binding.quantity_entity diagnostic proposal-first slice. It ensures the xHigh agent implements only the bounded surface authorized, preventing leakage into serving, broad parsing, or state-change semantics.

1. Current Seam Map

The proposal-first construction seam is established and strictly governed by PRs #841–#844.

• Construction Catalog (generate/construction_affordances.py): Defines immutable ConstructionFamily records, holding required roles, hazards, target semantics, and the diagnostic_only=True / serving_allowed=False gates.
• Proposal Factory (propose_construction): Creates a ConstructionProposal(status="proposed") from exact surface evidence before assessment.
• ProblemFrame Publication (generate/problem_frame_builder.py): The build_problem_frame() pipeline currently generates decrease_to_fraction and percent_partition proposals by scanning raw text, then adds them to the ProblemFrame alongside extracted facts, mentions, and bindings.
• Contract Dispatch (generate/problem_frame_contracts.py): assess_contracts() checks frame.proposals for specific family_ids and routes them to their corresponding assessment functions (e.g., assess_fraction_decrease).
• Assessment Authority: The individual ContractAssessment function is the sole authority for reporting runnable=True or runnable=False. The proposal remains a hypothesis.
• Legacy Fence: make_proposal() explicitly blocks migrated proposal-first families.

2. Quantity-Entity Target Map

To implement the authorized slice without broadening parsers, the following targeted additions are needed:

1. Foundational Registry (generate/foundational_families.py):
   • Flip implementation_authorized = True for _QUANTITY_ENTITY_BINDING only.
2. Construction Catalog (generate/construction_affordances.py):
   • Add _QUANTITY_ENTITY_FAMILY = ConstructionFamily(...) mirroring the foundational spec.
   • Register it in _CATALOG and _PROPOSAL_FIRST_FAMILIES.
3. Proposal Publication (generate/problem_frame_builder.py):
   • Extract proposals directly from the already existing MentionBinding(binding_type="quantity_entity") records built by _extract_bindings(). Do not add a new regex parser for nouns.
   • For each valid quantity-entity binding, call propose_construction("binding.quantity_entity", evidence_spans).
4. Contract Assessment (generate/problem_frame_contracts.py):
   • Add assess_quantity_entity(frame: ProblemFrame) -> ContractAssessment.
   • Update _CONTRACT_REGISTRY to map quantity_entity to this function.
   • In assess_contracts(), dispatch to assess_quantity_entity(frame) if the proposal exists.
5. Test Extensions:
   • Extend tests/test_construction_affordances.py and tests/test_construction_proposal_seam.py.
   • Create tests/test_quantity_entity_proposal.py for full boundary and confuser testing.

3. Existing Type Inventory

The implementation must exclusively use these existing structures:

• ProblemFrame: Exposes .quantities, .units, .mentions, .bindings, .hazards, and .proposals.
• GroundedScalar: Represents the numeric value (.value), exact .provenance, and .fact_id.
• GroundedMention: Represents the exact text matched (.surface), .span, .kind ("quantity", "object", "unit"), and the .fact_id it maps to.
• MentionBinding: Represents topological edges. .binding_type will be "quantity_entity" or "quantity_unit", connecting .source_mention_id to .target_mention_id.
• SourceSpan: Provides the exact textual provenance (.text, .start, .end).
• ConstructionProposal: Created via propose_construction(), carrying .role_obligations and initialized with .status="proposed".
• ContractAssessment: Yields .missing_bindings, .unresolved_hazards, and .runnable.

4. Implementation Hazards

The upcoming xHigh PR must actively avoid these known confusers:

• Broad noun parsing / generic extraction: Do not add NLP taggers or wide regexes to _extract_mentions. Rely entirely on the existing _ENTITY_AFTER_QUANTITY_RE, _FRACTION_ENTITY_RE, _COPULAR_PARTITION_RE, and _TRANSFER_RE behavior.
• Synthetic spans: Every evidence_spans element must perfectly slice the raw problem text. No string concatenation or synthetic gap-filling.
• Cross-sentence inference / Pronoun leakage: Do not attempt to resolve "it" or "them". If the exact local entity mention is not contiguous or clearly bound by existing heuristics, the contract must refuse.
• State-change leakage: A quantity/entity binding inside "He gained 5 pounds" is valid as grounding evidence, but it must not synthesize a state_change.transition proposal.
• Derivation / serving leakage: The assessment must remain diagnostic. Do not connect it to generate/math_candidate_graph.py or modify the canonical evaluation reports (train wrong_ids must remain []).
• Proposal mutation: Do not use make_proposal(). The proposal is a hypothesis and remains unmodified by the assessment.

5. Fixture Inventory

Existing test phrases in core that provide safe local binding vs. mandatory refusal:

Existing Phrase / Fixture	Expected Disposition	Reason
"Tom gave Ana 3 marbles."	Runnable	Quantity "3" bound to entity "marbles".
"There are 4 full boxes and 3 loose crayons."	Runnable	Multiple valid bindings: "4" → "boxes", "3" → "crayons".
"A block of iron has a mass of 12 grams."	Runnable	Quantity "12", unit "grams", bound properly.
"Mia spent 50% of her money."	Refusal	"50%" triggers percent/partition; missing direct quantity/entity count.
"A quarter of the class left."	Refusal / Ambiguous	"quarter" is a scalar but acts as a percent/partition.
"Marion has 1/4 more than what Yun currently has..."	Refusal	Comparison operator ("more than"); "1/4" does not bind to a direct entity.

6. Test Plan

The xHigh implementation must provide tests/test_quantity_entity_proposal.py mirroring the rigour of test_percent_partition_proposal.py:

1. Catalog & Posture Check: test_supported_case_has_diagnostic_catalog_proposal verifies status="proposed", diagnostic_only=True, and serving_allowed=False.
2. Execution Ordering: test_proposal_precedes_role_binding_and_contract_assessment using monkeypatch to prove proposal happens before ContractAssessment.
3. Legacy Fence: test_migrated_family_does_not_use_legacy_assessment_adapter ensures make_proposal is not called.
4. Authority: test_contract_assessment_remains_runnable_authority ensures the proposal does not declare itself runnable.
5. Exact Spans: Verify evidence_spans exactly match original raw text slices.
6. Confuser Rejection:
   • Test a phrase with a quantity but no entity (e.g., "The answer is 5.").
   • Test a phrase with two numbers and one entity (e.g., "The 2 boys have 3 dogs.").
   • Test a percent/rate confuser (e.g., "Increased by 20%").
   • Test unit/kind conflict (if practically verifiable with current types).
7. Independence: Run test_percent_partition_proposal.py and test_proportional_decrease_proposal.py to prove no regression in existing seam behavior.

7. Stop Conditions for Implementation

The xHigh agent must STOP and refuse to write code if any of the following occur:

• No Local Evidence: If the existing _extract_bindings logic cannot expose the needed entity without adding a broad noun regex, stop. Do not expand the parser.
• Ambiguity Cannot Be Represented: If quantity_kind (count vs. measurement) cannot be safely defaulted or extracted from existing ProblemFrame types without introducing a massive ontology, stop.
• State/Pronoun Creep: If binding a fixture requires pronoun resolution ("he", "they") or cross-sentence tracking, stop. The family requires exact local spans.
• Serving Path Touch: If forced to touch any serving API, candidate_graph, or eval artifact to make tests pass, stop immediately.

8. Copy-paste Next Implementation Brief Refinement

PR title: feat(kernel): introduce diagnostic quantity-entity proposal seam

Dependency: Start only after both docs/sessions/quantity-entity-foundational-slice-authorization-2026-06-20.md and docs/sessions/quantity-entity-implementation-preflight-2026-06-20.md have merged. Create a fresh worktree from origin/main and verify both commits are in the base.

Task: Implement the bounded diagnostic proposal-first slice for binding.quantity_entity.

• Registry: Flip implementation_authorized = True for this family in generate/foundational_families.py.
• Catalog: Add _QUANTITY_ENTITY_FAMILY to generate/construction_affordances.py, enforcing diagnostic_only=True and serving_allowed=False.
• Proposals: In generate/problem_frame_builder.py, iterate over existing MentionBinding(binding_type="quantity_entity") records to propose the construction using propose_construction(). Do not add new regex parsers for entities.
• Contracts: Create assess_quantity_entity(frame) in generate/problem_frame_contracts.py. Enforce the exact closure obligations from the authorization doc (provenance spans, grounded scalar, local binding relation).
• Tests: Create tests/test_quantity_entity_proposal.py to prove ordering, legacy adapter bypass, exact span slicing, diagnostic posture, and mandatory confuser refusal (quantity without entity, percent/comparison confusion).

Constraints: Do not implement state_change.transition. Do not add broad noun parsing or pronoun resolution. Do not alter serving or derivation organs. Train and holdout wrong_ids must remain []. If the exact local evidence is insufficient, the assessment must refuse; do not synthesize spans or bypass the preflight stop conditions.