core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs: audit semantic substrate affordances

Browse source
This commit is contained in:
Shay 2026-06-20 09:46:38 -07:00
parent 564e360eb1
commit e46c4dcbff
4 changed files with 1102 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

136
HANDOFF-gpt55-2026-06-20.md Normal file
View file

@ -0,0 +1,136 @@
# HANDOFF — GPT-5.5 — 2026-06-20
## Session objective
Produce the ADR-0223 semantic-substrate affordance audit without changing serving, derivation, benchmark, sealed, or runtime behavior.
## Baseline
- Repository: `/Users/kaizenpro/.codex/worktrees/1737/core`
- Git state at start: clean, detached HEAD
- Commit: `564e360e docs(adr): require semantic substrate affordance audit`
- Required bootstrap read: `GPT55.md`, `AGENTS.md`, `docs/runtime_contracts.md`, recent `HANDOFF-gpt55-2026-06-18.md`, ADR-0223 and governing ADRs, substrate briefs/audits, relevant source and tests.
## Map
Four directions were evaluated:
1. continue organ-local parsers — rejected as forward architecture;
2. universal parser/mega-IR — rejected because it collapses graph invariants;
3. pack-backed constructional affordances with exact proposal and deterministic proof — selected;
4. learned/stochastic parsing — deferred because it undermines replay and inspectability at the current stage.
The intrinsic space is a typed relational field over source spans, entities, quantities, events, target operators, hazards, and contract obligations. Semantic proximity can propose a construction but cannot prove it.
## Build
Documentation-only artifacts added:
- `docs/analysis/semantic-substrate-affordance-audit-2026-06-20.md`
- `docs/analysis/semantic-substrate-affordance-map-2026-06-20.md`
- `docs/analysis/problemframe-contract-gap-taxonomy-2026-06-20.md`
- this handoff
No Python, runtime, pack, benchmark, report, case, sealed artifact, manifest, or test file was changed.
## Principal findings
- CORE's geometric substrate is real in pack manifold compilation, exact CGA recall, vault recall, and versor propagation.
- The math `ProblemFrame` path does not consume that geometry. It uses hard-coded process triggers and local regex binding.
- `en_core_math_v1/frames.jsonl` is empty; its frame checksum is the SHA-256 of empty bytes. Process construction semantics live in `generate/process_frames.py`, separately from the pack lexicon.
- `ProblemFrame` is diagnostic only. Serving calls raw-text `resolve_promotable_*` organs through `parse_and_solve`.
- The no-new-legacy test contains parser expansion but does not retire the existing allowlist.
- Current percent-partition contract readiness is obligation-incomplete.
- Train case `0046` is the intended forward percent-partition slice.
- Holdout case `0393` is a false diagnostic runnable: a final remainder is selected as the whole and an inverse reconstruction is accepted by a forward contract.
- Train case `0005` has sufficient scalar/unit substrate to motivate proportional decrease, but no construction, state-transition relation, target direction, or contract.
- Graph boundaries are currently healthy: `ProblemFrame`, `EpistemicGraph`, `MathProblemGraph`, and `PropositionGraph` remain purpose-specific.
## Diagnostic evidence
Serving reports, run in memory without writes:
| Split | Correct | Refused | Wrong | Wrong IDs |
|---|---:|---:|---:|---|
| Train sample | 30 | 20 | 0 | `[]` |
| Holdout | 5 | 495 | 0 | `[]` |
ProblemFrame adequacy:
| Split | Contract candidates | Runnable |
|---|---:|---:|
| Train sample | 42 | 1 |
| Holdout | 423 | 1 (false runnable `0393`) |
## Validation
- `core test --suite smoke -q` — unavailable because `core` was not on `PATH`.
- Fallback: `uv run python -m core.cli test --suite smoke -q` — `108 passed in 136.89s`.
- Focused substrate/contract suite — `69 passed in 1.00s`:
- ProblemFrame builder and contracts
- adequacy and morphology labels
- no-new-legacy guard
- process frames
- scalar equivalence and unit dimensions
- ambiguity hazards
- epistemic carrier
No versor code or runtime field path changed, so the hard field invariant was not mechanically perturbed.
## Justification
The recommended architecture separates candidate resonance from constructive proof:
```text
exact semantic neighborhood
-> construction proposal
-> deterministic span/role binding
-> obligations and corrective hazards
-> ProblemFrame
-> organ-specific closed contract
```
This preserves duality: proposal is paired with correction, and positive evidence is paired with hazards/confusers. It also makes illegal readiness states structurally distinguishable: a candidate is not a binding, and a partial binding is not runnable.
## Recommended next PR
Branch: `codex/problemframe-proportional-change-closure`
Title: `feat(kernel): close proportional-decrease contracts and make readiness obligation-sound`
Scope:
- close proportional-decrease roles for train `0005` from existing substrate facts;
- represent base/final state, fractional scale, entity/unit continuity, and delta target with exact provenance;
- add an obligation-complete contract;
- tighten percent-partition readiness so holdout `0393` is not runnable;
- retain train `0046` with explicit topology and target obligations;
- add positive/confuser/determinism tests;
- do not change serving.
Expected diagnostic movement to verify:
- train runnable `1 -> 2` (`0005`, `0046`);
- holdout runnable `1 -> 0`;
- serving `wrong_ids == []` remains unchanged.
## Subsequent sequence
1. compile a reviewed, checksummed math construction catalog from pack data;
2. add exact CGA semantic-neighborhood proposal with evidence, never readiness authority;
3. bind acquisition/loss/transfer state changes constructionally;
4. close rate/comparison/container/partition topology;
5. migrate one organ to a typed closed contract and delete its local parser.
## Hard stops for the next session
- Do not turn CGA similarity into semantic assertion or organ selection.
- Do not add raw-text parsing to a new derivation organ.
- Do not promote `ProblemFrame` until false runnable `0393` is removed and obligations are explicit.
- Do not use `EpistemicGraph` or `PropositionGraph` as a mathematical mega-IR.
- Do not mutate packs without reviewed bytes, regenerated checksums, and replay evidence.
- Do not accept coverage growth if serving wrong IDs cease to be empty.
## Workspace note
At handoff creation, only the four documentation files listed above were intended changes. Recheck `git status`, `git diff --check`, and the final diff before committing.

305
docs/analysis/problemframe-contract-gap-taxonomy-2026-06-20.md Normal file
View file

@ -0,0 +1,305 @@
# ProblemFrame Contract Gap Taxonomy — 2026-06-20
Status: normative diagnostic taxonomy for ADR-0223
Applies to: `KernelFacts`, `ProblemFrame`, construction bindings, and `ContractAssessment`
## Purpose
Current adequacy reports count missing role names, but a missing role can arise from several fundamentally different failures: the source fact may be absent, the fact may exist but lack a binding, the wrong construction may have been proposed, or the contract may not express an obligation at all. Treating these as one “parser gap” encourages local regex patches.
This taxonomy makes each failure actionable while preserving the rule that unknown is not false.
## Gap record
Every reported gap should be representable by the following fields, whether or not a dedicated type is introduced immediately:
| Field | Meaning |
|---|---|
| `gap_code` | stable taxonomy code |
| `construction_id` | reviewed construction family, if any |
| `organ_id` | prospective contract consumer, if any |
| `role` | missing, conflicting, or weak role |
| `state` | proposed, partial, ambiguous, closed, runnable, refused |
| `evidence_spans` | exact spans that motivated the report |
| `provenance` | lexical, construction, reviewed reconstruction, or contract source |
| `blocking` | whether the gap prevents closure |
| `hazards` | applicable corrective conditions |
| `repair_layer` | pack, lexical fact extraction, construction binding, contract, adapter, or organ |
A gap without source evidence is still useful, but it must not fabricate an evidence span.
## Primary taxonomy
### PF-LX — lexical substrate gaps
The required surface meaning is lexical and should be resolved before construction matching.
| Code | Definition | Example | Correct repair | Forbidden repair |
|---|---|---|---|---|
| `PF-LX-001 scalar_unrecognized` | a scalar surface has no exact normalized value | unsupported mixed-number spelling | reviewed scalar-equivalence entry and tests | organ-local number regex |
| `PF-LX-002 unit_unrecognized` | a unit surface cannot map to a dimension/unit identity | plural or currency alias absent from pack | reviewed unit alias | local organ unit list |
| `PF-LX-003 lexical_ambiguity` | one surface has multiple admissible lexical meanings | “half” as noun vs modifier | preserve alternatives and hazard | first-match selection |
| `PF-LX-004 span_collision` | candidate lexical facts overlap incompatibly | “one half” recognized as two scalars | deterministic overlap policy with evidence | silent deletion |
| `PF-LX-005 semantic_anchor_absent` | a construction anchor is not represented in the mounted pack | reviewed acquisition synonym absent | pack addition and checksum | broad substring trigger |
### PF-EN — entity and reference gaps
The source contains relevant participants or quantities, but their identity or continuity is unresolved.
| Code | Definition | Example | Closure obligation |
|---|---|---|---|
| `PF-EN-001 entity_missing` | no entity candidate exists for a required role | quantity present without an object surface | bind or reconstruct only through reviewed construction evidence |
| `PF-EN-002 quantity_entity_unbound` | scalar exists but is not bound to a semantic entity | `3` incorrectly followed by “more” | exact entity binding with provenance |
| `PF-EN-003 referent_unresolved` | pronoun or ellipsis has multiple/no referents | “she gave him 3 more” | deterministic reference evidence or refusal |
| `PF-EN-004 continuity_unproven` | two mentions may or may not denote the same quantity-bearing kind | apples before/after acquisition | same-entity obligation |
| `PF-EN-005 role_alias_collision` | one surface is used for incompatible roles | “ones” as several subgroups | preserve competing bindings; block closure |
| `PF-EN-006 actor_patient_ambiguous` | event participants cannot be assigned safely | passive or reversed transfer | construction-specific voice/role proof |
### PF-CN — construction proposal gaps
The system has facts but cannot identify the relational construction that could organize them.
| Code | Definition | Example | Correct repair |
|---|---|---|---|
| `PF-CN-001 no_candidate` | no reviewed construction is proposed | proportional decrease case `0005` | construction catalog and exact candidate anchors |
| `PF-CN-002 overbroad_candidate` | surface trigger proposes a family lacking structural support | “left” creates percent-partition candidate | tighter declaration/proposal evidence; proposal remains non-runnable |
| `PF-CN-003 competing_candidates` | multiple constructions plausibly explain the same spans | consumption vs partition | retain candidates until obligations disambiguate |
| `PF-CN-004 construction_variant_missing` | family exists but a legitimate voice/order/topology variant is absent | transfer phrased passively | reviewed variant under same role contract |
| `PF-CN-005 negative_licensing_missing` | a construction lacks its disqualifying conditions | inverse question accepted as forward partition | add target/hazard obligations |
| `PF-CN-006 neighborhood_evidence_missing` | proposed family has no replayable retrieval evidence | hard-coded family activation | exact source/span/manifold evidence |
### PF-BD — role-binding gaps
A plausible construction exists, but required roles are not closed from facts.
| Code | Definition | Example | Closure obligation |
|---|---|---|---|
| `PF-BD-001 required_role_unbound` | declared role has no binding | labor `worker`, `rate`, or `duration` | exact role-to-fact binding |
| `PF-BD-002 relation_unanchored` | relation lacks an event/source anchor | percent linked to generic “ones” | event/entity anchored relation |
| `PF-BD-003 wrong_role_kind` | bound value has the wrong semantic type | object label used where numeric whole is required | typed role constraint |
| `PF-BD-004 positional_binding` | binding depends on first/nearest textual occurrence rather than structure | final 28 selected as original whole | construction topology proof |
| `PF-BD-005 cardinality_mismatch` | too few or too many role bindings exist | partition needs two distinct subgroups | role cardinality constraint |
| `PF-BD-006 incompatible_units` | quantities cannot participate dimensionally | hours treated as money | dimensional compatibility |
| `PF-BD-007 relation_direction_unknown` | operands exist but orientation is not proven | who has 3 more than whom | directional relation obligation |
| `PF-BD-008 event_order_unknown` | state transitions exist but temporal order is unresolved | acquisition then loss vs loss then acquisition | ordered event binding |
| `PF-BD-009 aggregate_membership_unknown` | members of a sum/partition are not proven co-members | percentages from unrelated groups | shared whole/topology obligation |
| `PF-BD-010 binding_conflict` | two closed-looking bindings assert incompatible roles | same scalar as initial and remaining value | ambiguous state; refuse |
### PF-TG — target gaps
The question target is a semantic operator over the frame, not merely a nearby noun.
| Code | Definition | Example | Closure obligation |
|---|---|---|---|
| `PF-TG-001 target_surface_missing` | no question/goal span is identified | declarative prompt or nonstandard question | explicit target evidence |
| `PF-TG-002 target_entity_unbound` | target operator is known but its entity is not | “How many are left?” | reference-resolved target entity |
| `PF-TG-003 target_operator_unknown` | count/difference/total/remaining/rate is unresolved | current generic `unknown` | typed target operator |
| `PF-TG-004 target_direction_unknown` | forward vs inverse or initial vs final state is unresolved | `0393` asks original from remainder | direction/state obligation |
| `PF-TG-005 target_scope_ambiguous` | target may apply to several subgroups/events | “How many did they have?” | exact scope binding |
| `PF-TG-006 target_unit_unproven` | expected answer dimension is not known | “How much money” classified as generic count | target dimension constraint |
| `PF-TG-007 target_incompatible_with_construction` | target is grounded but the candidate construction cannot produce it | remaining target for forward aggregate contract | block candidate contract |
### PF-TP — relational topology gaps
Individual bindings exist but do not prove the shape required by the construction.
| Code | Definition | Example | Closure obligation |
|---|---|---|---|
| `PF-TP-001 whole_missing` | no numeric base/whole is proven | percent without base quantity | numeric whole binding |
| `PF-TP-002 subgroup_missing` | a required subgroup lacks identity | percentage linked only to generic noun | subgroup entity binding |
| `PF-TP-003 subgroup_not_distinct` | multiple subgroup roles may denote the same group | repeated “ones” surfaces | distinctness proof |
| `PF-TP-004 partition_coverage_unknown` | subgroups are not proven to cover the whole | two mentioned groups may omit others | coverage obligation or explicit partial-partition construction |
| `PF-TP-005 scale_base_unlinked` | fraction/percent is not linked to the correct base | 80% attached to consumed group, not original whole | scoped base relation |
| `PF-TP-006 state_transition_open` | initial, changed, and final states do not form a closed transition | proportional decrease without final-state relation | state equation topology |
| `PF-TP-007 rate_axes_unbound` | rate numerator/denominator dimensions are not assigned | dollars per hour | dimensional axes and participant binding |
| `PF-TP-008 container_axes_unbound` | container/content/count-per roles are not connected | boxes with items each | container cardinality topology |
| `PF-TP-009 comparison_axis_unbound` | comparator/reference/difference are not connected | “3 more” | comparison topology |
| `PF-TP-010 inverse_topology_unlicensed` | facts support an inverse reconstruction not implemented by the candidate organ | `0393` original-from-remainder | refuse or route to a distinct reviewed contract |
### PF-HZ — hazard and correction gaps
Positive evidence exists, but the system lacks or ignores the conjugate corrective condition.
| Code | Definition | Example | Required behavior |
|---|---|---|---|
| `PF-HZ-001 hazard_unregistered` | known ambiguity has no centralized representation | overloaded comparative surface | add reviewed hazard |
| `PF-HZ-002 hazard_unattached` | hazard exists but is not linked to the relevant span/binding | percent-base ambiguity | attach with provenance |
| `PF-HZ-003 hazard_ignored_by_contract` | blocking hazard is visible but runnable remains true | unbound base tolerated | contract must block |
| `PF-HZ-004 confuser_missing` | positive test exists without a minimally different negative case | forward partition only | add adversarial pair |
| `PF-HZ-005 conflict_auto_resolved` | system silently picks one of competing interpretations | repeated entity aliases | preserve ambiguity/refuse |
| `PF-HZ-006 negation_scope_unknown` | negation may reverse or suppress an event/relation | “did not give” | scoped negation obligation |
### PF-CT — contract-definition gaps
The frame may contain adequate evidence, but the assessment does not express or enforce the organ's true preconditions.
| Code | Definition | Example | Correct repair |
|---|---|---|---|
| `PF-CT-001 contract_absent` | no assessment exists for a supported diagnostic family | proportional decrease | explicit contract over frame facts |
| `PF-CT-002 obligation_omitted` | assessment ignores a necessary precondition | percent contract omits numeric whole | add typed obligation |
| `PF-CT-003 obligation_too_weak` | surface equality substitutes for semantic proof | subgroup/percent both equal “ones” | topology-aware obligation |
| `PF-CT-004 candidate_gate_too_broad` | unrelated process candidate emits an organ assessment | consumption implies percent partition | construction-specific candidate gate |
| `PF-CT-005 runnable_false_positive` | assessment declares runnable but organ geometry is not closed | holdout `0393` | block and add regression |
| `PF-CT-006 runnable_false_negative` | all facts are present but assessment cannot recognize closure | future fully bound variant | strengthen contract without relaxing proof |
| `PF-CT-007 hazard_policy_incomplete` | assessment does not define blocking vs advisory hazards | ambiguity present but unused | explicit hazard disposition |
| `PF-CT-008 organ_capability_mismatch` | contract promises a target/topology the organ cannot execute | inverse target sent to forward organ | narrow contract or add distinct organ |
### PF-AD — adapter and graph-boundary gaps
The comprehension result is closed, but no safe projection exists or a projection crosses architectural boundaries.
| Code | Definition | Example | Correct repair |
|---|---|---|---|
| `PF-AD-001 organ_adapter_absent` | no typed adapter converts a closed contract to organ input | all current ProblemFrame diagnostics | narrow immutable adapter |
| `PF-AD-002 raw_text_reparse` | consumer ignores closed facts and reparses source | current derivation organs | consume typed projection and delete parser |
| `PF-AD-003 mega_ir_leak` | consumer-specific fields are added to a general graph | solver operands in `EpistemicGraph` | separate graph plus adapter |
| `PF-AD-004 provenance_dropped` | projected input loses source/reconstruction evidence | scalar passed without span/source | provenance-preserving projection |
| `PF-AD-005 target_semantics_dropped` | adapter passes quantities but not target operator/direction | forward/inverse confusion | include typed target contract |
| `PF-AD-006 fallback_divergence` | failed structured path silently falls back to a different parser | contract refusal followed by legacy solve | explicit lane policy; no hidden fallback |
### PF-EV — evidence and evaluation gaps
The feature cannot be judged safely because evidence is insufficient or non-replayable.
| Code | Definition | Example | Required evidence |
|---|---|---|---|
| `PF-EV-001 positive_case_missing` | no representative successful construction case | new family without fixture | exact expected frame/assessment |
| `PF-EV-002 confuser_case_missing` | no close negative case | no inverse variant | minimally different refusal fixture |
| `PF-EV-003 morphology_coverage_missing` | supported relation has no lexical/syntactic variation | fixed transfer sentence only | reviewed variants preserving geometry |
| `PF-EV-004 deterministic_replay_missing` | repeated extraction/assessment is not compared | unstable candidate order | identical serialized evidence/hash |
| `PF-EV-005 serving_safety_unmeasured` | diagnostic change lacks train/holdout serving comparison | new runnable cases only | correct/refused/wrong and wrong IDs |
| `PF-EV-006 false_runnable_unaudited` | runnable diagnostic cases are not manually/structurally audited | current holdout `0393` | per-case obligation proof |
| `PF-EV-007 parser_retirement_unmeasured` | substrate path added without demonstrating legacy deletion | duplicate paths remain | allowlist and call-site reduction |
### PF-TR — trust-boundary gaps
The proposed substrate change can execute, mutate, disclose, or ingest beyond its reviewed authority.
| Code | Definition | Example | Required control |
|---|---|---|---|
| `PF-TR-001 unreviewed_construction_mutation` | runtime/user correction changes construction catalog | learned trigger immediately active | reviewed proposal lifecycle |
| `PF-TR-002 unsafe_pack_path` | pack ID/path can escape approved roots | traversal in dynamic load | validation before access |
| `PF-TR-003 dynamic_execution` | construction data can execute arbitrary code | validator/import hook | explicit opt-in trust boundary |
| `PF-TR-004 sensitive_surface_leak` | reports log raw user tokens unnecessarily | full prompt in shared report | centralized safe display policy |
| `PF-TR-005 answer_evidence_contamination` | answers/labels enter recognition or construction retrieval | benchmark answer mining | source isolation and tests |
| `PF-TR-006 approximate_or_stochastic_retrieval` | proposal cannot replay exactly | ANN or randomized ranking | exact deterministic CGA scan |
## Severity and ownership
| Severity | Meaning | Examples | Merge policy |
|---|---|---|---|
| `S0 invariant` | can corrupt field, truth, replay, or trust boundary | approximate recall, hidden mutation, false answer | hard stop |
| `S1 readiness` | can declare an unclosed case runnable | `PF-CT-005`, ignored ambiguity | fix before any promotion |
| `S2 capability` | blocks a legitimate case safely | missing construction or binding | may merge as documented refusal; prioritize by roadmap |
| `S3 evidence` | weakens confidence or maintainability | missing morphology/confuser fixture | required before claiming capability |
Repair ownership follows the first layer able to resolve the gap without guessing:
```text
lexical fact -> construction proposal -> construction binding
-> contract -> adapter -> organ -> evaluation/trust boundary
```
Downstream layers must not compensate for an upstream gap by reparsing raw text.
## Applying the taxonomy to current evidence
### Train case `0005` — proportional decrease
Observed facts: exact `3/4`, `84`, a unit binding, but no process construction, no proportional relation, and an unresolved target.
Primary gaps:
- `PF-CN-001 no_candidate` — no proportional-decrease construction;
- `PF-TP-006 state_transition_open` — base/final/delta geometry is not formed;
- `PF-TG-003 target_operator_unknown` and `PF-TG-004 target_direction_unknown`;
- `PF-CT-001 contract_absent`;
- `PF-AD-001 organ_adapter_absent`.
It is not primarily `scalar_unrecognized`; adding another number regex would not close it.
### Train case `0046` — percent partition
Observed facts are adequate enough for the current forward aggregation, but proof is incomplete.
Residual gaps/risk:
- `PF-CT-002 obligation_omitted` — numeric whole and full topology are not explicitly required;
- `PF-TP-003 subgroup_not_distinct` / `PF-TP-004 partition_coverage_unknown` are not generally proven;
- `PF-EV-004 deterministic_replay_missing` if serialized assessment identity is not asserted across runs.
The case may remain runnable only after its positive obligations are made explicit.
### Holdout case `0393` — false runnable
Observed defects:
- `PF-BD-004 positional_binding` — final 28 is selected as original whole;
- `PF-BD-002 relation_unanchored` and `PF-EN-005 role_alias_collision` — “ones” links unrelated/local roles;
- `PF-TG-004 target_direction_unknown` or incorrectly tolerated;
- `PF-TP-010 inverse_topology_unlicensed`;
- `PF-CT-003 obligation_too_weak` and `PF-CT-005 runnable_false_positive`;
- `PF-EV-006 false_runnable_unaudited` before this audit.
Required disposition: not runnable for `percent_partition`. It may remain a proposal/partial frame until a distinct inverse-reconstruction construction is reviewed.
### Acquisition probe — “Lena has 5 apples. She buys 3 more apples.”
- `PF-EN-002 quantity_entity_unbound` because `3` can bind to “more”;
- `PF-CN-002 overbroad_candidate` for incidental comparison;
- `PF-TP-006 state_transition_open`;
- `PF-BD-008 event_order_unknown` if acquisition ordering is not bound;
- `PF-TG-004 target_direction_unknown` until final-state total is proven.
### Labor/rate probe
- `PF-BD-001 required_role_unbound` for worker/rate/duration;
- `PF-TP-007 rate_axes_unbound`;
- `PF-TG-006 target_unit_unproven` when money is classified as count;
- `PF-CT-008 organ_capability_mismatch` if a generic target is accepted.
## Report aggregation rules
Adequacy and morphology reports should aggregate without losing case-level evidence:
1. count each stable `gap_code` by split, construction, organ, and blocking status;
2. list every runnable case with its closed obligations and hazards;
3. list every false-runnable regression explicitly;
4. distinguish `no_candidate`, `candidate_partial`, `candidate_ambiguous`, and `contract_absent`;
5. never infer a missing relation from a missing answer;
6. keep answer labels out of construction extraction and gap classification;
7. preserve exact source spans when present, but do not require fabricated spans for absent roles;
8. produce deterministic sorted output.
Recommended headline metrics:
| Metric | Meaning |
|---|---|
| candidate precision | proposed cases that have at least one structurally supported role |
| binding closure rate | candidates whose required construction roles close |
| contract soundness | runnable cases whose organ preconditions are manually/test-proven |
| target soundness | runnable cases with explicit operator, scope, direction, and dimension |
| hazard effectiveness | blocking hazards that prevent a documented confuser |
| parser retirement | legacy parser/call-site/allowlist reduction after migration |
| serving safety | correct/refused/wrong with `wrong_ids` |
Coverage alone is not a success metric.
## Acceptance taxonomy for the immediate PR
The proportional-decrease/readiness PR is complete only if:
- `0005` eliminates `PF-CN-001`, `PF-TP-006`, `PF-TG-003/004`, and `PF-CT-001` through a closed diagnostic construction;
- `0393` eliminates `PF-CT-005` by becoming non-runnable for percent partition;
- `0046` remains runnable with explicit numeric-whole, topology, target, and hazard obligations;
- new confusers cover inverse target, remainder target, entity discontinuity, unit mismatch, and ambiguous base;
- no `PF-AD-002 raw_text_reparse` is added to a new layer;
- serving results retain `wrong_ids == []`;
- all new frame/assessment output is deterministic and provenance-bearing.
`PF-AD-001 organ_adapter_absent` is intentionally allowed to remain in that PR because serving migration is a later, separately reviewed step.
## Conclusion
The central distinction is between missing words, missing relations, and missing proof. CORE already recognizes many scalars and entities; most present gaps are constructional bindings, target semantics, topology, and contract obligations. This taxonomy directs repairs to those layers and blocks the default failure mode of compensating with another local prose parser.

443
docs/analysis/semantic-substrate-affordance-audit-2026-06-20.md Normal file
View file

@ -0,0 +1,443 @@
# Semantic Substrate Affordance Audit — 2026-06-20
Status: decision audit; no serving-path change
Governing decision: ADR-0223
Evidence baseline: detached `564e360e` (`docs(adr): require semantic substrate affordance audit`)
## Executive decision
CORE has a real geometric substrate, but mathematical problem comprehension does not yet use it. Exact CGA neighborhood operations, deterministic field propagation, pack compilation, provenance-carrying facts, and separated graph roles all exist. The diagnostic `ProblemFrame` path instead discovers process families from hard-coded surface triggers and binds its few relations with local regular expressions. The serving path bypasses `ProblemFrame` entirely and invokes a sequence of raw-text derivation organs.
The immediate decision is therefore not to add another parser or to promote diagnostics into serving. The next load-bearing change should close the proportional-decrease affordance in `ProblemFrame` as an obligation-sound construction, while strengthening percent-partition readiness so that inverse/remainder cases cannot be declared runnable. That slice should establish the shape of the eventual construction system: pack-backed construction declarations, exact semantic-neighborhood proposal, deterministic span binding, explicit obligations and hazards, and typed projection into `ProblemFrame`.
The masterstroke is separation of **proposal** from **proof**:
```text
exact semantic neighborhood
-> candidate construction family (proposal only)
-> deterministic construction binding with exact spans
-> obligation and hazard assessment
-> ProblemFrame facts and relations
-> organ readiness
```
CGA retrieval may suggest which construction deserves inspection. It must never, by similarity alone, license a relation, an answer, or a serving organ.
## Scope and non-negotiable invariants
This audit inspected architecture and diagnostics only. It does not change serving behavior, migrate a derivation organ, mutate benchmark cases or sealed artifacts, mine answers, introduce raw-text fallback, add broad parsing, weaken exact recall, normalize a hot path, or create unreviewed learning.
The preserved safety conditions are:
- `versor_condition(F) < 1e-6` remains the field invariant.
- exact CGA recall remains exact; no ANN, cosine, HNSW, or stochastic retrieval is proposed.
- `surface`, `walk_surface`, and `articulation_surface` remain distinct.
- `ProblemFrame`, `EpistemicGraph`, `PropositionGraph`, and `MathProblemGraph` retain separate responsibilities.
- diagnostic coverage may increase only with `wrong_ids == []`.
- unknown remains unknown; absence of a relation is not evidence that it is false.
- reviewed teaching and pack mutation remain proposal/review controlled.
## Map: four architectural directions
### Direction A — Continue local organ parsers
Each new mathematical family gets another `resolve_promotable_*` function with local regexes, phrase checks, and extraction logic.
This is locally cheap and can preserve benchmark precision, but it duplicates recognition, binding, hazards, and provenance in every organ. It makes semantic equivalence a maintenance problem and leaves the geometric substrate irrelevant to comprehension. The no-new-legacy guard limits the number of new regex-bearing files but does not retire the existing allowlist or prevent phrase-based local grammars.
Decision: reject as the forward architecture. Existing organs remain bounded debt until a contract-backed replacement is proven.
### Direction B — Build a universal parser or universal graph
A broad parser would turn prose into one maximal intermediate representation and feed recognition, reasoning, articulation, and solving from it.
This appears to consolidate work but violates the repository's graph-boundary discipline. Recognition evidence, mathematical solver structure, and articulation plans have different invariants and lifetimes. A universal graph would accumulate optional fields, erase epistemic distinctions, and make illegal cross-layer states representable.
Decision: reject. Use typed adapters between purpose-specific structures.
### Direction C — Constructional affordances over the semantic substrate
Reviewed construction declarations define candidate families, required roles, admissible lexical neighborhoods, exact binding rules, hazards, and contract obligations. Exact CGA retrieval proposes candidates; deterministic construction code proves bindings and emits `KernelFacts`/`ProblemFrame` relations with spans and provenance. Contracts decide readiness.
This direction fits the intrinsic space: a word problem is not a bag of numbers or a flat parse. It is a partially observed relational field in which several constructions may resonate, but only constructions whose role obligations close may act.
Decision: select. Implement incrementally, beginning with proportional decrease and false-readiness correction.
### Direction D — Learned or stochastic semantic parsing
A model could infer latent structures or select organs probabilistically.
That would make current gaps harder to inspect, undermine replay, and conflate candidate confidence with semantic proof. It may be reconsidered only after deterministic construction contracts provide a gold interface and replayable evidence.
Decision: defer; not licensed by the current architecture.
## What the substrate actually affords today
### Real and operational affordances
1. **Geometric vocabulary state.** Language-pack compilation builds vocab manifolds and resonance structures. `VocabManifold.nearest` and vault recall use exact `cga_inner` scans. Field transitions use `versor_apply` and preserve the hard versor invariant.
2. **Exact lexical normalization.** Pack-backed scalar equivalence maps number surfaces to exact `Fraction` values with source spans. Unit dimensions provide deterministic exact lookup. These are lexical affordances, not grammar parsers.
3. **Provenance-bearing diagnostic facts.** `KernelFacts` and `ProblemFrame` preserve source spans, normalized values, bindings, candidate relations, targets, and hazards with deterministic ordering.
4. **Separated graph meanings.** `EpistemicGraph` carries recognition evidence, `PropositionGraph` plans articulation, and `MathProblemGraph` is a solver graph. Their current separation is architecturally correct.
5. **A narrow construction precedent.** The recognition anti-unifier produces typed slots and spans from taught examples. It demonstrates deterministic constructional recognition, though it is currently narrow and disconnected from math comprehension.
6. **Deterministic evaluation.** Serving reports, adequacy reports, morphology reports, trace hashes, and CLI lanes allow a proposal to be measured without silently changing behavior.
### Prepared but unused affordances
The `en_core_math_v1` pack contains 57,106 bytes of lexical material and compiled semantic domains, but `frames.jsonl` is empty and its manifest carries the SHA-256 of empty bytes. Mathematical process-frame declarations instead live in `generate/process_frames.py`. The pack therefore prepares vocabulary neighborhoods but does not provide a reviewed construction layer.
`ProblemFrame` does not load a pack manifold, call `cga_inner`, or query exact vault recall. Its process-family detection scans `ProcessFrame.trigger_surfaces` using boundary text matching. In this path, “semantic neighborhood” is an architectural intention, not an implemented recognition mechanism.
### Merely named affordances
- Semantic similarity does not currently retrieve mathematical constructions.
- Process frames declare roles but do not bind them.
- Contract candidates do not consistently prove the facts their organs require.
- Hazards are attached, but most do not participate in readiness decisions.
- A `ProblemFrame` does not currently serve as the input to any promoted derivation organ.
## Concrete path audit
### Real current pipeline after #831
Confirmed from repository call sites:
```text
diagnostic path
raw text
-> scalar/unit/entity/hazard extraction
-> hard-coded ProcessFrame trigger scan
-> local-regex mentions and narrow bound relations
-> ProblemFrame
-> assess_contracts
-> adequacy/morphology report
serving path
raw text
-> generate.math_candidate_graph.parse_and_solve
-> ordered raw-text resolve_promotable_* organs
-> MathProblemGraph/candidate result
-> serving result or refusal
```
There is no serving edge from `ProblemFrame` or `ContractAssessment` to a derivation organ. There is also no math-comprehension edge from a mounted manifold or exact CGA recall operation into `build_problem_frame`. The intended constructional loop is therefore a proposed architecture, not current behavior.
### `ProblemFrame` extraction and binding
`generate/problem_frame_builder.py` has a useful deterministic shell and exact provenance, but its semantic core is narrow:
- `_extract_process_frame_candidates` (line 179) matches every hard-coded trigger surface.
- `_extract_candidate_relations` (line 201) creates unbound declarations rather than evidence-backed roles.
- `_ENTITY_AFTER_QUANTITY_RE`, `_FRACTION_ENTITY_RE`, `_QUESTION_ENTITY_RE`, `_ACTOR_VERB_RE`, and `_TRANSFER_RE` (lines 280–298) form a local grammar.
- `_bound_relations` (line 397) binds generic fraction/percent relations and one exact transfer shape.
- the “whole” is selected positionally as the first non-percent/non-fraction quantity binding, which can select a final remainder as the original whole.
- target grounding handles narrow “how many/how much” objects; other question forms remain unresolved.
The builder is acceptable as a diagnostic scaffold, but ADR-0207 does not license its grammar regexes as the basis of positive capability. New affordances should consume substrate facts and reviewed constructions, not enlarge this local grammar.
### Contract assessment
`generate/problem_frame_contracts.py` implements one material assessment: `percent_partition`. `nested_fraction_remainder_total` and `temporal_tariff` assessments are skeletons over relation types the builder never emits.
The percent assessment currently treats partition or consumption process-frame presence as enough to emit a candidate. Runnable status checks a subgroup/whole link, a percent/subgroup surface match, target grounding, and limited hazards. It does not prove:
- a numeric whole quantity rather than an object label;
- the expected partition topology;
- coverage and distinctness of subgroup roles;
- target operator and direction;
- forward aggregation rather than inverse reconstruction or remaining-state recovery;
- relation anchoring to the relevant events;
- that all percentages belong to the same partition.
This is a readiness-soundness defect, not merely a coverage gap.
### Serving path
`generate/math_candidate_graph.py::parse_and_solve` (line 589) invokes a sequence of raw-text `resolve_promotable_*` organs. Repository search found `build_problem_frame` only in diagnostics and tests. The existing `fraction_decrease` and `percent_partition` organs each perform their own raw-text recognition and extraction.
The no-new-legacy guard currently allowlists 31 derivation files. Representative regex counts include 47 in `math_candidate_parser`, 18 in `r1_reconstruction`, and 13 in `temporal_tariff`. The guard is valuable containment, but containment is not migration.
### Local recognizer inventory
| File/function | Recognizes | Classification | Evidence | Recommendation |
|---|---|---|---|---|
| `language_packs/scalar_equivalence.py` and numerics loader | exact numeric surfaces and values | allowed lexical normalization | pack-backed entries, exact `Fraction`, spans | retain; extend only through reviewed lexical data |
| `language_packs/unit_dimensions.py` | exact unit aliases/dimensions | allowed lexical normalization | pack lookup with deterministic result | retain; improve lexical coverage without sentence grammar |
| `language_packs/ambiguity_hazards.py` | known ambiguous surfaces | allowed corrective scaffold | centralized deterministic registry | retain and connect hazards to construction/contract blocking |
| `generate/problem_frame_builder.py::_extract_process_frame_candidates` | process families from trigger surfaces | diagnostic scaffold; duplicate semantic source | scans Python `ProcessFrame.trigger_surfaces`; no pack/CGA lookup | replace incrementally with pack-backed construction proposals |
| builder entity/question/actor regexes | local mentions, bindings, question object | diagnostic scaffold / foundation risk | grammar-bearing regexes at lines 280–298 | freeze; replace family-by-family through construction binding |
| builder `_TRANSFER_RE` / `_bound_relations` | one transfer form and generic fraction/percent links | diagnostic scaffold / legacy parser risk | fixed clause shape and positional whole selection | use only as migration evidence; do not broaden |
| `generate/process_frames.py` declarations | process surfaces, roles, hazards | duplicate semantic source | Python taxonomy while math pack `frames.jsonl` is empty | consolidate into reviewed checksummed construction data |
| `generate/problem_frame_contracts.py` | percent readiness and skeletal missing-role reports | substrate-backed readiness gate, incomplete | consumes structured frame rather than raw prose | preserve boundary; strengthen obligations and add family contracts |
| `scripts/gsm8k_substrate_morphology.py` | gap labels and migration recommendations | contract-first diagnostic with loose-trigger fallback | assessments are preferred; raw substring/regex fallbacks remain | report contract gap codes; label fallback recommendations as heuristic |
| `generate/derivation/fraction_decrease.py` | decrease-to-fraction word problems | legacy parser risk | local regex/quantity/question extraction from raw text | migrate only after a closed frame contract exists, then delete parser |
| `generate/derivation/percent_partition.py` | equal partition plus percentages | legacy parser risk | local percent regex and phrase scan | keep serving unchanged until contract soundness and parity are proven |
| other `generate/derivation/*` resolvers | organ-specific prose shapes | legacy parser risk | repeated raw-text recognizers in serving chain | retire one-for-one; do not create a generic replacement parser |
| `recognition/anti_unifier.py` | taught token-shape constructions with typed slots | substrate-aligned binder precedent | deterministic slot/span construction | reuse its proof discipline, not its graph type, for math |
The scalar/unit recognizers are acceptable because they map lexical forms to exact typed facts without asserting sentence relations. Grammar-bearing recognizers become foundation risks when they directly license process roles, target direction, or organ readiness.
### Morphology recommendation audit
The morphology script is strongest when it derives recommendations from `ContractAssessment.missing_obligations`. Its raw surface fallbacks are diagnostically convenient but can repeat the same overbroad-trigger problem as process-frame discovery. A future report should distinguish `contract_gap` from `surface_heuristic` provenance and should never count the latter as readiness evidence.
### Graph boundaries
- `ProblemFrame`: diagnostic mathematical facts, bindings, process candidates, targets, hazards, and readiness inputs.
- `EpistemicGraph`: recognition assertions and provenance for a cognitive turn.
- `MathProblemGraph`: solver-specific candidate graph used by the serving math lane.
- `PropositionGraph`: articulation planning, not comprehension or solving.
No current mega-IR drift was found. The risk is prospective: using `PropositionGraph` as a math representation or expanding `EpistemicGraph` into a solver graph would collapse distinct invariants. The selected design instead projects a closed construction binding into each consumer through a narrow typed adapter.
## Diagnostic evidence
### Serving baseline
| Split | Correct | Refused | Wrong | Wrong IDs |
|---|---:|---:|---:|---|
| Train sample | 30 | 20 | 0 | `[]` |
| Holdout | 5 | 495 | 0 | `[]` |
This is the governing safety posture: extremely sparse coverage with no known wrong answers.
### `ProblemFrame` adequacy
| Split | Frames | Scalars | Units | Entity bindings | Quantity bindings | Process relations | Bound targets | Contract candidates | Runnable |
|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
| Train sample (50) | 50 | 47 | 21 | 50 | 46 | 16 | 42 | 42 | 1 |
| Holdout (500) | 500 | 470 | 202 | 494 | 452 | 124 | 402 | 423 | 1 |
High scalar/entity/target presence is not contract readiness. The large candidate-to-runnable collapse is appropriate when obligations are missing, but candidate emission is also too broad.
Top observed missing obligations/hazards:
| Gap | Train sample | Holdout |
|---|---:|---:|
| percent link | 24 | 240 |
| whole | 15 | 180 |
| partition subgroup | 14 | 167 |
| worker / rate / duration (each) | 10 | 128 |
| container / content / count-per (each) | 7 | 54 |
| target | 6 | 34 |
| unbound-base hazard | 15 | 180 |
| percent-ambiguity hazard | 2 | 19 |
These counts are diagnostic occurrences, not independent cases or projected serving gains.
Contract candidate counts:
| Split | Percent partition | Temporal tariff | Nested fraction | Runnable |
|---|---:|---:|---:|---:|
| Train sample | 25 | 10 | 7 | 1 |
| Holdout | 241 | 128 | 54 | 1 |
The dominant missing roles are percent-link/whole/subgroup, worker-rate-duration, and container-content-count-per bindings. These are construction-binding gaps, not missing arithmetic operators.
### Runnable truth audit
Train case `0046` is the intended percent-partition slice: 100 students, two halves, percentages within subgroups, aggregate target. The current frame is sufficient to solve it, though its contract proof is weaker than the example itself.
Holdout case `0393` is a false runnable. It describes chocolates, two halves, consumption percentages, a final remainder of 28, and asks for the original count. The builder:
- selects the final `28 chocolates` binding as the “whole”;
- binds fraction entities to local verbs such as “have” and “do”;
- links percent and subgroup surfaces through the generic word “ones”;
- grounds the target as `remaining`;
- declares a forward percent-partition contract runnable even though the problem requires inverse reconstruction.
The serving system correctly refuses this case. Contract readiness must be tightened before any diagnostic promotion.
### Representative affordance probes
| Family | Current diagnostic behavior | Structural gap |
|---|---|---|
| Acquisition | Detects transaction/comparison; may bind `3` to “more”; no process relation | event roles, same-entity continuity, additive direction |
| Loss/remainder | “left” can trigger consumption/partition and a false percent candidate | event state transition, remainder target direction |
| Transfer | One fixed regex binds agent, patient, quantity, object | construction generality, pronouns, tense/voice variants |
| Proportional decrease | Scalars and unit may be present; no process relation or grounded delta target | base/final state, scale, delta target construction |
| Rate/labor | Labor candidate only; worker/rate/duration remain unbound | dimensional rate construction and monetary target |
| Comparison | Comparison candidate only; `3 more` may bind as an entity | comparator, difference, direction, referent continuity |
| Container | Container candidate only | container/content/count-per/cardinality roles |
| Partition | Percent/fraction links are surface-local and topology-poor | whole/subgroup topology, coverage, aggregation target |
## Hidden geometry and intrinsic representation
The intrinsic space is a typed relational field over source spans, semantic entities, quantities, events, and question operators. Its invariants are:
1. every asserted role has source or reviewed-reconstruction provenance;
2. semantic-neighborhood retrieval can propose but cannot assert;
3. each construction has a dual: positive obligations and corrective hazards/confusers;
4. target direction is part of the construction, not punctuation trivia;
5. numerical execution occurs only after role closure;
6. graph projections preserve their consumer-specific invariants;
7. refusal is the correct reconstruction when closure is absent.
The distortion in the current system comes from projecting this relational field too early into flat text patterns. The correction is not a larger regex. It is an explicit construction-binding boundary.
## Foundation risk register
| Severity label | Evidence | Consequence | Recommendation | PR needed? |
|---|---|---|---|---|
| `FOUNDATION_BLOCKER` | no math construction catalog; no neighborhood-to-construction path; no typed organ adapter | substrate cannot become the source of problem-solving behavior | establish reviewed construction declarations and proposal/proof boundary | yes, PRs 2–3 and first migration |
| `READINESS_FALSE_POSITIVE` | holdout `0393` is declared runnable by a forward percent contract | future promotion could admit an unsupported answer | strengthen target/topology/whole obligations before promotion | yes, immediate PR |
| `LEGACY_BYPASS_RISK` | serving reparses raw text in each `resolve_promotable_*` organ | semantic fixes duplicate and can disagree by organ | migrate one closed contract at a time and delete the parser | yes, staged |
| `DUPLICATE_SEMANTICS` | pack lexicon, Python process frames, builder triggers, morphology triggers, and organ patterns encode overlapping meaning | aliases, roles, and hazards drift | make reviewed pack construction bytes authoritative | yes, PR 2 |
| `MISSING_AFFORDANCE` | acquisition, loss, comparison, rate, container, and proportional roles remain unbound | many cases have facts but no closed relational topology | add bounded construction families in priority order | yes, PRs 1, 4, 5 |
| `DOC_GOVERNANCE_DRIFT` | ADR-0207 forbids grammar regex as positive capability while current diagnostics can be described as substrate-backed | implementation status can be overstated and legacy patterns copied | label local grammar as diagnostic scaffold and require parser retirement evidence | docs now; tests later |
| `DEFERRED_RESEARCH` | exact CGA proposal thresholds/precision for construction families are unmeasured | premature retrieval could create noisy candidates or hot-path cost | prototype only after catalog; measure confusers and deterministic cost | later research PR |
Confirmed facts in this register come from repository code, manifests, diagnostics, and tests. The proposed construction type names, exact catalog schema, and likely performance characteristics are architectural hypotheses that require implementation evidence; they are not claimed as existing behavior.
## Build decision: construction proposal and proof
The selected architecture should use three narrowly scoped types or equivalent structural contracts; names are illustrative, not an implementation mandate:
1. **Construction declaration** — reviewed, pack-backed family identity; admissible lexical/domain anchors; required and optional roles; target operators; hazards; and declared projections.
2. **Construction candidate** — candidate family, exact retrieval evidence, source spans, and provenance. It is epistemically `possible`, never runnable.
3. **Construction binding** — exact role-to-fact bindings, unresolved obligations, triggered hazards, and a deterministic proof record. Only a closed binding projects bound relations into `ProblemFrame`.
This makes illegal states unrepresentable: a candidate cannot masquerade as a binding, and a binding with missing obligations cannot masquerade as a runnable contract.
The exact semantic-neighborhood layer should remain bounded:
- query only reviewed, mounted pack state;
- use exact CGA scans and deterministic ordering;
- return family proposals, not inferred facts;
- preserve matched lexical evidence and spans;
- require a deterministic construction matcher to close roles;
- reject ambiguous or conflicting bindings through explicit hazards;
- never retrieve answers, benchmark labels, or executable organ names from unreviewed text.
## Recommended implementation sequence
### PR 1 — proportional closure and readiness soundness
Proposed branch: `codex/problemframe-proportional-change-closure`
Proposed title: `feat(kernel): close proportional-decrease contracts and make readiness obligation-sound`
Scope:
- represent a `decrease_to_fraction` construction over existing `KernelFacts`/`ProblemFrame` concepts;
- bind base state, final fractional state, unit/entity continuity, scale, and requested delta with exact spans;
- add a contract assessment whose runnable state proves those obligations;
- strengthen `percent_partition` assessment so inverse/remainder target `0393` is not runnable;
- add positive, confuser, target-direction, ambiguity, and deterministic-order tests;
- keep serving behavior unchanged.
Expected diagnostic movement, to be verified rather than hard-coded:
- train runnable: `1 -> 2` (`0005`, `0046`);
- holdout runnable: `1 -> 0` by removing false runnable `0393`;
- serving wrong IDs remain `[]`.
Non-goals: organ migration, answer production, new serving dispatch, broad grammar, benchmark mutation, and CGA construction retrieval.
Decision: **yes, this remains the immediate engineering PR**. It is the smallest slice that both adds a missing substrate relation and removes a false readiness state. The acceptance criteria are the expected case movements above, explicit positive/corrective obligations, exact spans/provenance, deterministic output, focused tests, smoke, and unchanged serving `wrong_ids == []`.
### PR 2 — pack-backed construction catalog
Proposed branch: `codex/math-construction-catalog`
Proposed title: `refactor(kernel): compile reviewed math constructions from language packs`
Move process-family declarations, role obligations, hazards, and stable aliases into a checksummed reviewed pack artifact. Compile them into typed immutable runtime declarations. Keep a compatibility adapter to `ProcessFrame`; do not add a universal graph.
Non-goals: serving use, fuzzy role binding, and automatic pack mutation.
### PR 3 — exact semantic-neighborhood proposal seam
Proposed branch: `codex/math-construction-neighborhoods`
Proposed title: `feat(kernel): propose math constructions from exact semantic neighborhoods`
Use mounted pack manifolds and exact CGA scans to propose construction families with evidence. Measure precision on curated confusers. Candidate proposals must not affect readiness until deterministic role binding closes.
Non-goals: approximate retrieval, learned thresholds, organ selection, or answer retrieval.
### PR 4 — constructional transaction and state-change bindings
Proposed branch: `codex/problemframe-state-change-constructions`
Proposed title: `feat(kernel): bind acquisition, loss, and transfer state changes`
Replace the fixed transfer shape and loose transaction triggers with catalog-backed constructions for acquisition, loss, and transfer, including entity continuity and target direction. Emit only bound `ProblemFrame` relations.
Non-goals: serving migration and unconstrained coreference.
### PR 5 — rate, comparison, container, and partition topology
Proposed branch: `codex/problemframe-relational-constructions`
Proposed title: `feat(kernel): close relational word-problem construction families`
Add typed bindings and obligation-complete assessments for labor/rate, comparison, container/count-per, and partition topology. Each family requires positive and adversarial morphology evidence.
### PR 6 — first contract-backed organ migration
Proposed branch: `codex/contract-backed-fraction-decrease`
Proposed title: `refactor(math): serve fraction decrease from closed ProblemFrame contracts`
Only after diagnostics demonstrate precision should one organ accept a typed closed contract instead of raw text. Compare serving reports and remove the corresponding legacy parser in the same PR.
Non-goals: multi-organ migration, fallback to the legacy parser after a failed contract, or changes to sealed evidence.
## Work allocation
Top-tier architectural work:
- construction type and proof-state design;
- obligation semantics and target-direction modeling;
- exact CGA proposal boundary and calibration policy;
- graph adapter boundaries;
- first serving migration and deletion of legacy parsing.
Lower-cost, mechanically checkable work suitable for narrower agents after the design is fixed:
- moving reviewed declarations to a pack and regenerating byte-derived checksums;
- adding table-driven positive/confuser fixtures;
- producing adequacy/morphology report diffs;
- adding deterministic ordering and serialization tests;
- shrinking the no-new-legacy allowlist when a parser is removed;
- documentation and audit-map updates.
## Safety gates for every PR
1. smallest relevant targeted tests pass;
2. smoke and cognition lanes remain green;
3. train and holdout serving reports retain `wrong_ids == []`;
4. adequacy report lists every newly runnable case and every removed false runnable;
5. deterministic reruns produce identical frames, assessments, and trace hashes;
6. construction candidates cannot become runnable without closed obligations;
7. exact spans and provenance exist for every bound role;
8. ambiguity hazards have adversarial tests and block readiness where relevant;
9. no normalization appears outside an allowed construction/algebra boundary;
10. no approximate retrieval, stochastic fallback, hidden answer path, or unreviewed mutation is introduced;
11. graph-boundary tests prevent `PropositionGraph` or `EpistemicGraph` from becoming solver IRs;
12. any serving migration deletes or deprecates the corresponding local parser and updates the legacy audit.
## Bounded handoff prompts
### Prompt for the next top-tier engineering agent
> Implement `feat(kernel): close proportional-decrease contracts and make readiness obligation-sound` on branch `codex/problemframe-proportional-change-closure`. Read `AGENTS.md`, your agent supplement, `docs/runtime_contracts.md`, ADR-0207/0218/0222/0223, and the three 2026-06-20 audit artifacts before editing. Map existing scalar, entity, unit, target, relation, and contract call sites first. Add a diagnostic-only proportional-decrease construction for train case `0005` using `KernelFacts`/`ProblemFrame` facts with exact spans and provenance. Its contract must prove base state, final fractional scale, entity/unit continuity, and delta target direction. Strengthen percent-partition obligations so train `0046` remains runnable and holdout `0393` becomes non-runnable. Do not change serving, derivation organs, benchmark/report/sealed files, or add raw-text fallback/generic parsing. Add positive, inverse, remainder, ambiguity, entity-mismatch, unit-mismatch, and deterministic-order tests. Run focused ProblemFrame/contract tests, adequacy on both splits, serving reports with `wrong_ids == []`, no-new-legacy, and smoke. Report exact runnable case changes; treat false-runnable removal as success.
### Prompt for a lower-cost mechanical agent after PR 1 design is fixed
> Add table-driven diagnostic fixtures and report assertions for the approved proportional-decrease and strengthened percent-partition contracts. Work only from the contract obligations specified in the parent design; do not invent surfaces, roles, parsing, or readiness policy. Cover deterministic ordering, exact spans/provenance, inverse/remainder refusal, entity and unit mismatch, and the expected `0005`/`0046`/`0393` classifications. Do not touch serving, derivation organs, pack data, benchmark cases, reports, or sealed artifacts. Run the focused test list and return the exact commands/results.
## Justification
The selected design follows the substrate's actual geometry. Semantic neighborhoods provide resonance; construction matching supplies the conjugate correction; contract obligations establish closure. Candidate retrieval and corrective proof are dual operations. Refusal is not a missing feature but the stable state reached when the field cannot close without inventing facts.
This is also mechanically sympathetic. Exact neighborhood scans operate over compact reviewed packs, immutable construction declarations can be compiled once, and deterministic role binding avoids repeatedly rebuilding ad hoc parser state in every organ. Typed projections keep each graph small and purpose-specific.
Most importantly, the design makes the desired direction measurable. CORE stops accumulating parsers when a newly supported family first appears as a closed substrate construction, then feeds a derivation organ through a typed contract, and finally permits deletion of the local raw-text parser. Coverage without parser retirement is not architectural progress.
## Answer to the governing question
The next most important thing CORE should do is implement the proportional-decrease slice as the first obligation-sound substrate construction—while removing the false percent-partition readiness of holdout `0393`—and use that slice to establish the reviewed construction-binding interface. Do not add another raw-text solver. The decisive milestone is a derivation organ receiving a closed, provenance-bearing `ProblemFrame` contract and deleting its local parser.

218
docs/analysis/semantic-substrate-affordance-map-2026-06-20.md Normal file
View file

@ -0,0 +1,218 @@
# Semantic Substrate Affordance Map — 2026-06-20
Status: architecture map supporting ADR-0223
Companion audit: `docs/analysis/semantic-substrate-affordance-audit-2026-06-20.md`
## Purpose
This map distinguishes capabilities that are operational, prepared but disconnected, diagnostic-only, inherited debt, or absent. It also fixes the intended boundary between semantic recognition, mathematical comprehension, solving, and articulation.
## End-to-end map
```text
reviewed language packs
|-- lexicon / scalar equivalence / units / semantic domains
|-- [missing] reviewed mathematical construction catalog
v
compiled immutable pack state
|-- VocabManifold + exact CGA neighborhood
|-- deterministic lexical normalization
v
candidate construction proposals EpistemicGraph
| [missing for math] recognition evidence only
v
deterministic role binding + hazards
| [narrow/local-regex scaffold today]
v
KernelFacts -> ProblemFrame -> ContractAssessment
| diagnostic only today
v
typed closed organ input
| [missing]
v
MathProblemGraph / derivation -> articulation target -> PropositionGraph
solver-specific articulation-specific
```
## Capability-state legend
- **Operational** — executes in the live or diagnostic repository path with tested semantics.
- **Prepared** — underlying substrate exists but the relevant path does not consume it.
- **Diagnostic** — produces evidence but cannot change serving behavior.
- **Debt** — inherited mechanism retained for current precision, not a forward pattern.
- **Absent** — no repository mechanism currently provides the claimed capability.
## Affordance inventory
| Affordance | State | Evidence | Architectural reading | Required correction |
|---|---|---|---|---|
| Versor field transition | Operational | `algebra/versor.py`, `field/propagate.py` | Actual geometric state transition | Preserve; do not insert hot-path repair |
| Exact CGA recall | Operational | `algebra/cga.py`, `vault/store.py`, vocab manifold lookup | Exact deterministic neighborhood/recall exists | Keep exact and bounded |
| Language-pack manifold compilation | Operational | pack compiler and semantic-domain data | Reviewed lexical state can become geometric state | Reuse for construction proposal |
| Scalar equivalence | Operational | pack-backed numerics, exact `Fraction`, spans | Correct lexical normalization boundary | Extend formats only with lexical tests |
| Unit dimensions | Operational but narrow | pack-backed lookup; digit-plus-token discovery | Useful typed lexical fact | Improve token discovery without grammar creep |
| Ambiguity hazards | Operational diagnostically | centralized hazard registry and frame annotations | Corrective vocabulary exists | Make hazards participate in binding/readiness |
| `KernelFacts` | Operational diagnostically | scalars, units, entities, hazards, candidates | Stable substrate fact carrier | Preserve exact provenance and deterministic order |
| `ProblemFrame` | Operational diagnostically | builder, adequacy script, tests | Correct location for math comprehension facts | Replace local grammar with constructions incrementally |
| Process-family discovery | Diagnostic debt | hard-coded `trigger_surfaces` scan | Surface resonance is being simulated by string matching | Move reviewed declarations to pack; add exact proposal seam |
| Process role declaration | Diagnostic | candidate relations with unbound roles | Taxonomy exists, comprehension does not | Add deterministic role-binding constructions |
| Transfer role binding | Diagnostic debt | one fixed transfer regex | Demonstrates desired output shape, not general mechanism | Re-express as reviewed construction |
| Fraction/percent binding | Diagnostic debt | local quantity/entity regexes and positional whole selection | Produces some useful facts but weak topology | Close roles through explicit construction obligations |
| Target grounding | Diagnostic and narrow | “how many/how much” question object | Target is recognized as a role but direction is under-modeled | Represent target operator, state, and direction explicitly |
| Contract assessment | Diagnostic and incomplete | one material percent assessment; two skeletons | Right gate, insufficient proof | Define obligation-complete readiness |
| Construction catalog | Absent | math `frames.jsonl` is empty | No reviewed home for math constructions | Compile checksummed declarations from pack data |
| Semantic-neighborhood construction retrieval | Absent | no CGA/manifold call from builder/contracts | Geometric substrate bypassed in math comprehension | Add exact proposal-only retrieval |
| Construction proof record | Absent | candidate and binding are not strongly separated | Candidate presence can overstate readiness | Make candidate/binding/closed assessment distinct states |
| ProblemFrame-fed derivation | Absent | builder imported by scripts/tests, not organs | Diagnostics cannot retire parsers | Migrate one organ after precision proof |
| Raw-text derivation organs | Operational debt | `parse_and_solve` chain of `resolve_promotable_*` | Current serving precision comes from local parsers | Retire one-for-one after contract migration |
| No-new-legacy guard | Operational containment | allowlist-based test | Stops some expansion | Require allowlist shrink on migration |
| Recognition anti-unifier | Operational but narrow | typed slots/spans from taught patterns | A constructional precedent | Reuse principles, not its graph as math IR |
| `EpistemicGraph` | Operational in recognition | per-turn assertions/provenance | Correct recognition evidence boundary | Do not add solver state |
| `MathProblemGraph` | Operational in serving | candidate graph and derivations | Correct solver-specific structure | Accept typed closed contract through adapter |
| `PropositionGraph` | Operational in articulation | planner/target/realizer path | Correct articulation structure | Never use as comprehension mega-IR |
| Deterministic reports | Operational | serving, adequacy, morphology scripts | Enables non-serving architecture work | Add construction precision/confuser views |
| Reviewed mutation | Operational elsewhere | teaching/proposal lifecycle | Correct trust boundary | Apply to construction catalog changes |
## Source-of-truth map
### Current duplication
| Meaning | Current source | Duplicate or shadow source | Consequence |
|---|---|---|---|
| Math lexical surfaces | `en_core_math_v1/lexicon.jsonl` | organ-local phrase/regex inventories | semantic aliases drift by organ |
| Process families | `generate/process_frames.py` | derivation organ trigger logic | pack cannot review or checksum construction semantics |
| Roles | `ProcessFrame.required_roles` | local organ extraction assumptions | declared roles do not match proven inputs |
| Hazards | ambiguity registry / process frame fields | local negative checks | readiness corrections are inconsistent |
| Target meaning | `ProblemFrame` target binding | each organ's question parsing | target direction is repeatedly reinterpreted |
| Arithmetic readiness | `ContractAssessment` | organ-local promotability | diagnostic “runnable” can disagree with actual solving |
### Intended source hierarchy
```text
reviewed pack bytes
-> compiled lexical/manifold state
-> compiled construction declarations
-> exact candidate evidence
-> deterministic construction bindings
-> ProblemFrame relations and target
-> obligation-complete ContractAssessment
-> typed organ adapter
```
Manifest checksums must continue to be computed from bytes written to disk. Python declarations may be generated adapters or compatibility views, but must not remain an independent semantic source of truth.
## Boundary matrix
| Structure | Owns | Must not own | Lifetime | Projection rule |
|---|---|---|---|---|
| `KernelFacts` | lexical facts, spans, normalized exact values, hazards | inferred solution or articulation | one problem parse | source facts only |
| `ProblemFrame` | entities, bindings, process candidates, bound relations, target, contract inputs | answer, token walk, prose realization | one problem comprehension | only exact/provenanced construction output |
| `ContractAssessment` | candidate organ, obligations, hazards, runnable proof state | parsing or arithmetic result | one frame assessment | runnable iff all positive and corrective obligations close |
| `EpistemicGraph` | recognition assertions and provenance | mathematical solver operations | one cognitive turn | optional typed evidence adapter only |
| `MathProblemGraph` | solver operands, operations, candidate derivations | general recognition or articulation policy | one math solve | consume closed math contract, not raw recognition graph |
| `PropositionGraph` | claims and relations needed for articulation | math comprehension and arithmetic execution | one articulation plan | receive derived claims through adapter |
This separation is the anti-mega-IR rule. Shared facts should be projected, not shared through a growing universal object.
## Construction family coverage map
### Required affordance families
| Family | Representative surfaces | Construction/chunk | Intended semantic neighborhood | Role obligations | Current support | Missing pieces and principal risk |
|---|---|---|---|---|---|---|
| Acquisition / transaction | buy, bought, purchase, acquire, get, gain, receive | actor acquires quantity of same entity; optional counterparty/cost | possession change, positive object delta, transaction | buyer, acquired entity/quantity, prior state, same-entity continuation; optional seller/price/money delta; target direction | transaction/comparison trigger candidates only | no event binding; `3` may bind to “more”; comparison or money target can be confused with acquisition |
| Loss / consumption | spend, use, eat, lose, give away, remove | owner loses/consumes quantity from prior state | possession change, negative object delta, consumption | owner, entity, lost quantity, prior/final state, ordered event, target direction | consumption/partition candidates only | no state transition; “left” can over-trigger partition; spending money vs consuming objects needs dimensions |
| Transfer | give, send, receive, sell, trade | source transfers quantity/entity to target | possession transfer, dual source/target deltas | source actor, target actor, entity, quantity; optional price/value; voice and direction | one fixed transfer regex can bind core roles | variants, pronouns, passive voice, selling/value topology; fixed regex is not a reviewed construction |
| Proportional change | decrease to, reduced to, increase to, fraction of | state becomes scale times base; question may request final or delta | scaling, state transition, part/base relation | base quantity/entity/unit, target scale, prior/final state, requested final/delta direction | scalar/unit facts may exist; no construction or contract | immediate gap for `0005`; risk of confusing “decrease by” with “decrease to” |
| Rate / frequency | per, each, every, daily, hourly, every other | numerator quantity per denominator interval/entity | dimensional rate, repeated propagation | numerator unit, denominator unit, interval/count, participant/event, target dimension | labor frame candidate; temporal contract skeleton | worker/rate/duration unbound; “every other” and monetary targets require distinct topology |
| Comparison | more than, fewer than, difference, how many more | left entity stands in directed delta/ratio relation to right | comparative ordering, directed difference, relative scale | left/right entities, comparator, amount/ratio, reference direction, delta target | comparison trigger only | “more” mistaken for entity; direction and target scope absent |
| Remainder / final state | left, remain, after, still has | ordered deltas reconstruct final or initial state | state transition, residual, inverse reconstruction | initial state, ordered deltas, final state, entity continuity, target state/direction | loose consumption/partition triggers; local serving organs | current false runnable `0393`; “left” is polysemous and cannot license a forward partition |
| Container / part-whole | box, bag, pan, group, half of, percent of | containers hold count-per contents; parts/subgroups relate to whole | containment, cardinality product, partition topology | container, content, count per, container count; or whole, part/subgroups, scale, coverage, aggregate target | container/partition candidates; weak generic percent/fraction bindings; skeletal contract | roles/topology mostly unbound; surface-local subgroup links can create false closure |
Semantic neighborhoods in this table are proposal domains, not synonym lists that automatically select operators. Each construction still requires exact binding and corrective hazards for negation, incompatible entities/units, target mismatch, and competing interpretations.
### Current closure status
| Family | Candidate detection | Bound roles today | Contract today | Serving today | Next structural obligation |
|---|---|---|---|---|---|
| Proportional decrease | None or incidental | scalar/unit only | None | local `fraction_decrease` parser | base state, final scale, entity continuity, delta target |
| Percent partition | Loose partition/consumption triggers | weak whole/subgroup/percent links | Material but unsound | local parser | topology, numeric whole, target aggregation/direction |
| Nested fraction remainder | Container trigger | none | missing-role skeleton | local parser | container, content, count-per, remainder/total direction |
| Temporal tariff/labor | Labor trigger | none | missing-role skeleton | local parser | worker, rate, duration, unit dimensions, earnings target |
| Transfer | transfer trigger and fixed regex | agent, patient, quantity, object in one shape | None | several local organs | construction variants and state transition |
| Acquisition | transaction/comparison triggers | none | None | local organs/candidate parser | actor, acquired amount, entity continuity, additive target |
| Loss/remainder | consumption/partition triggers | none | may create false percent candidate | local organs | initial state, loss event, remaining state, target direction |
| Comparison | comparison trigger | none | None | local organs | subject/reference, difference/ratio, comparison direction |
| Container/count-per | container trigger | none | missing-role skeleton | local organs | container, content, count-per, container count, requested total |
## Candidate-to-proof state machine
```text
UNSEEN
-> PROPOSED exact neighborhood or exact construction anchor found
-> PARTIAL at least one role bound with provenance
-> AMBIGUOUS conflicting bindings or blocking hazard
-> CLOSED every required role and corrective obligation proven
-> RUNNABLE a contract-backed organ accepts the closed projection
PROPOSED/PARTIAL/AMBIGUOUS -> REFUSED
```
Required invariants:
- `PROPOSED` cannot expose an organ input.
- `PARTIAL` cannot be serialized as runnable.
- `AMBIGUOUS` records competing bindings; it must not select one silently.
- `CLOSED` is construction closure, not an answer.
- `RUNNABLE` is specific to an organ contract; a closed construction may still have no capable organ.
- every transition is deterministic and replayable.
## Duality map: forward affordance and correction
| Forward operation | Required conjugate/correction |
|---|---|
| Semantic-neighborhood proposal | exact construction obligations and confusers |
| Scalar normalization | ambiguity and span-overlap hazards |
| Entity continuity | pronoun/reference ambiguity evidence |
| Process-family activation | negative licensing and incompatible target checks |
| Quantity binding | unit/dimension and role compatibility |
| Partition binding | topology, subgroup distinctness, and coverage |
| Target grounding | target operator, state, and direction |
| Runnable assessment | explicit missing obligations and blocking hazards |
| Serving promotion | report comparison and legacy-parser deletion |
| Reviewed pack change | checksum, deterministic compilation, and replay evidence |
## Tests that prove substrate use rather than parser growth
### Construction invariance tests
For a supported construction, vary lexical surfaces within reviewed neighborhoods while preserving role geometry. The resulting bound relation topology and normalized quantities must remain identical, modulo source spans.
### Confuser tests
Hold surface vocabulary roughly constant while changing target direction, event roles, negation, temporal order, inverse/forward form, or entity continuity. The incorrect construction must remain partial, ambiguous, or refused.
### Proposal/proof separation tests
A close semantic-neighborhood match with missing roles must produce a candidate but never a runnable assessment. This is the direct test that CGA is proposing rather than deciding.
### Projection tests
A closed construction projects only consumer-required fields into `ProblemFrame`, `MathProblemGraph`, or recognition evidence. No graph acquires fields owned by another layer.
### Retirement tests
When an organ migrates, remove its legacy parser from the no-new-legacy allowlist and prove equivalent or stricter serving behavior. A new substrate path without deletion is incomplete migration.
## Decision checkpoints
1. **After proportional closure:** train `0005` is runnable, train `0046` remains runnable, holdout `0393` is not runnable, and serving wrong IDs remain empty.
2. **After construction catalog:** no independent Python trigger taxonomy remains authoritative; pack bytes and checksums are the source.
3. **After neighborhood proposal:** confuser precision proves semantic proximity alone cannot grant closure.
4. **After first organ migration:** the organ consumes a typed closed contract and its local raw-text parser is removed.
5. **Before broader rollout:** exact CGA cost and deterministic construction matching meet hot-path performance requirements without caching mutable state.
## Architectural conclusion
CORE already has the lower substrate and the upper cognitive pipeline. The missing middle is a reviewed construction layer that turns semantic resonance into proven relational affordances. The correct bridge is not a universal parse tree and not another derivation regex. It is a deterministic candidate-and-correction boundary whose closed output can be projected into the existing purpose-specific graphs.