Host-object replay scenarios for the existing grounding contract¶

• Date: 2026-11-06
• Status: Research draft, documentation only. Outcomes confirmed by a run on 2026-11-06 (see "Confirming run"). No code changed, no fixture committed, no schema added, nothing accepted.
• Baseline: main at 8a72bbc6 (every file:line below refers to that commit)
• Decision record under study: ADR-025, status Proposed (2026-09-23). This note does not change that status.
• Builds on: Kernel contract fit/gap memo (its gap numbers 1-8 are used below as [GAP n])
• Issue context: #700 (HCI-HF-007, pure replay evaluation, open on 2026-11-06, scoped to examples/hci-hf-lab/eval)
• Governing direction: ADR-030 section 3 (breadth freeze)

Labels that apply to every scenario¶

• Synthetic. Every value is invented: a toy "scene" host with one shape, obj-17, in an invented coordinate space host-canvas. No real application, user, recording or person.
• Linux-only reading, no hardware. The outcomes come from reading pure Python modules that do not touch the platform. No camera, gaze tracker, headset, host application or device was used.
• Derived by reading, then confirmed by a run. The outcomes below were first derived by reading the code. A review run on 2026-11-06 replayed the appendix trace through the real resolver and ran decide; every resolver and decide outcome matched (see "Confirming run"). The hci-lab column remains a mapping, not a run: nothing in examples/hci-hf-lab was executed.

Question¶

The fit/gap memo found that the grounding contract already handles time freshness, layout invalidation and target ambiguity. It also found that a host-owned object lacks a state revision, an authority object, an inverse record and a postcondition check. This note asks a narrower, replayable question:

For at most six synthetic host-object situations, what does the existing contract return today, and where does that answer differ from what a host-object kernel would need?

The note expresses each situation in the existing grounding trace format (TRACE_SCHEMA_VERSION = "1.0", src/yazses/grounding/trace.py:72). The real TargetResolver can replay that format through scripts/replay_grounding_trace.py --trace without any new code. The note adds no fields to that format or to examples/hci-hf-lab/fixtures.schema.json.

Shared setup¶

Policy: the ResolutionPolicy defaults (src/yazses/grounding/resolver.py:187). These defaults are not measured, as the module's own docstring says. The relevant values are max_target_age_s = 0.5 (:207), max_candidate_skew_s = 0.5 (:211), min_target_confidence = 0.5 (:203) and tie_distance_px = 4.0 (:228).

Every scenario has the same target: a gaze TargetSnapshot at timestamp_s = 100.0, confidence = 0.8, space = host-canvas v3, point = (120, 80). Resolution happens at now_s = 100.1, so the target is 0.1 s old and passes _target_failure (resolver.py:504).

Unless a scenario says otherwise, obj-17 is an APPLICATION candidate with role shape, bounds = (100, 60, 40, 40) in host-canvas v3, confidence = 0.9, label Cube and actions ["set_colour"]. The point (120, 80) lies inside those bounds.

How the outcome vocabularies line up¶

Three vocabularies appear below. This table maps them and invents no new one.

The hci-lab stop decision (emergency stop) has no counterpart in either Python module. None of the scenarios uses it.

The resolver and decide are not wired together anywhere in src/yazses today. Scenarios 5 and 6 show their composition as a thought experiment: each function was run separately, and the arrow between them is hypothetical.

The six scenarios¶

The expected_entity_id column holds the ground truth written into the appendix trace. It records what a host-object kernel should do, so null means abstaining is correct. A replay therefore scores any scenario where the existing contract grounds but should not as grounded_wrong, which makes the gap visible as a number.

What the six scenarios establish, and what they do not¶

• S1 and S2 restate, in replayable form, two rows the memo already produced by running a scratch script. They are included so that one trace covers both the cases the contract already handles and the cases it cannot handle.
• S3 is the clearest case: the existing contract grounds confidently in a situation where a host-object kernel would need to re-validate. It does not mislead the user today, because nothing in src/yazses acts on a host object. It is a gap only for a future that ADR-025 proposes and ADR-030 freezes.
• S5 and S6 show that the existing consequence policy errs toward confirming. Nothing here argues for loosening it.
• The scenarios say nothing about any real application, any real accessibility tree, any user, or any threshold value. The policy defaults are unmeasured, and a synthetic trace cannot license them.

What this note deliberately does not do¶

• It adds no fixture schema and no field to the grounding trace or the hci-lab schema. If #700 wants host-object cases in its harness, the decision belongs in that issue's examples/hci-hf-lab/fixtures.schema.json lineage, as the memo already says.
• It commits no fixture file. The appendix trace lives only in this note so that it cannot enter tests/fixtures/grounding_replay_report.json or the CI drift gate by accident.
• It changes no src/ code, adds no field to SemanticCandidate, and adds no member to UnresolvedReason or Consequence. The ADR-030 freeze table in the memo still applies.
• It does not move ADR-025 from Proposed, and it does not recommend Accept, Amend or Defer. That remains the owner's choice, using the memo's options table.
• It proposes no ThinkGear, EEG, XR or digital-twin runtime.

How to confirm (re-run)¶

Save the appendix JSON to a scratch path outside the repository, for example $TMPDIR/kernel-replay-scenarios.json. Then run these commands from the repository root:

uv run python scripts/replay_grounding_trace.py --trace "$TMPDIR/kernel-replay-scenarios.json"
uv run python -m pytest tests/test_adr_index_is_current.py -q

Expected from the first command, per case under semantic_grounding: S1 unresolved/semantic_all_stale, S2 unresolved/semantic_space_mismatch, S3 grounded_wrong (ground truth null, resolver grounded obj-17), S4 ambiguous, S5 and S6 grounded_correct. Under window_only, every case is expected to be unresolved with semantic_no_candidates, because no candidate has source window (src/yazses/grounding/replay.py:184).

For the decide half of S5 and S6, a one-line check:

uv run python -c "from yazses.activation.confirm import classify_consequence as c, decide as d; print(d(0.8, c('set_colour')), d(0.8, c('undo')))"

Expected output: Decision.CONFIRM Decision.CONFIRM.

If any observed outcome differs from a prediction, replace the cell with the observed value and record the run's commit. Do not adjust the trace to match the prediction.

Confirming run (2026-11-06)¶

Run on 2026-11-06 at branch commit 0f40e53c (whose src/ is identical to 8a72bbc6), Linux, CPython 3.14, with the appendix extracted to a scratch file outside the repository.

• scripts/replay_grounding_trace.py --trace exited 0; the trace validator accepted the appendix, including targets with no window_id. semantic_grounding: S1 unresolved/ semantic_all_stale, S2 unresolved/semantic_space_mismatch, S3 grounded obj-17 classified grounded_wrong, S4 ambiguous (2 alternatives, evidence inside_target_region), S5 and S6 grounded obj-17 classified grounded_correct. Totals: 2 correct, 1 wrong, 1 ambiguous, 2 unresolved of 6. window_only: 6 of 6 unresolved/semantic_no_candidates. Every case matched its prediction.
• The decide one-liner printed Decision.CONFIRM Decision.CONFIRM, as predicted.
• tests/test_adr_index_is_current.py, tests/test_citation_hygiene.py and tests/test_private_tiers_stay_private.py: 21 passed. pytest -k 'link or hygiene or research': 5144 passed, 24 skipped.

These numbers describe six invented cases. They license no threshold and say nothing about real hosts or users.

Appendix: the synthetic trace (grounding trace schema 1.0, existing format)¶

{
  "schema_version": "1.0",
  "trace_id": "kernel-replay-scenarios",
  "study_mode": "synthetic",
  "description": "Synthetic host-object scenarios S1-S6 from design/research/kernel-replay-scenarios.md. Invented toy scene; no real application or user.",
  "space": {"name": "host-canvas", "version": 3},
  "cases": [
    {
      "case_id": "s1-stale-host-snapshot",
      "description": "Host snapshot captured 2.0 s before the gaze target.",
      "now_s": 100.1,
      "target": {"source": "gaze", "timestamp_s": 100.0, "confidence": 0.8, "point": {"x": 120.0, "y": 80.0}},
      "candidates": [
        {"source": "application", "entity_id": "obj-17", "role": "shape", "captured_at_s": 98.0, "confidence": 0.9,
         "bounds": {"x": 100.0, "y": 60.0, "width": 40.0, "height": 40.0}, "label": "Cube", "actions": ["set_colour"]}
      ],
      "hint": null,
      "expected_entity_id": null
    },
    {
      "case_id": "s2-layout-revision-mismatch",
      "description": "Host re-laid out the canvas: candidate in host-canvas v4, target in v3.",
      "now_s": 100.1,
      "target": {"source": "gaze", "timestamp_s": 100.0, "confidence": 0.8, "point": {"x": 120.0, "y": 80.0}},
      "candidates": [
        {"source": "application", "entity_id": "obj-17", "role": "shape", "captured_at_s": 100.0, "confidence": 0.9,
         "space": {"name": "host-canvas", "version": 4},
         "bounds": {"x": 100.0, "y": 60.0, "width": 40.0, "height": 40.0}, "label": "Cube", "actions": ["set_colour"]}
      ],
      "hint": null,
      "expected_entity_id": null
    },
    {
      "case_id": "s3-state-revision-invisible",
      "description": "Two reports of obj-17; the fill changed between them but no carried field differs except captured_at_s.",
      "now_s": 100.1,
      "target": {"source": "gaze", "timestamp_s": 100.0, "confidence": 0.8, "point": {"x": 120.0, "y": 80.0}},
      "candidates": [
        {"source": "application", "entity_id": "obj-17", "role": "shape", "captured_at_s": 100.0, "confidence": 0.9,
         "bounds": {"x": 100.0, "y": 60.0, "width": 40.0, "height": 40.0}, "label": "Cube", "actions": ["set_colour"]},
        {"source": "application", "entity_id": "obj-17", "role": "shape", "captured_at_s": 100.2, "confidence": 0.9,
         "bounds": {"x": 100.0, "y": 60.0, "width": 40.0, "height": 40.0}, "label": "Cube", "actions": ["set_colour"]}
      ],
      "hint": null,
      "expected_entity_id": null
    },
    {
      "case_id": "s4-same-id-moved",
      "description": "Host moved obj-17 by 4 px between reports; both readings contain the point.",
      "now_s": 100.1,
      "target": {"source": "gaze", "timestamp_s": 100.0, "confidence": 0.8, "point": {"x": 120.0, "y": 80.0}},
      "candidates": [
        {"source": "application", "entity_id": "obj-17", "role": "shape", "captured_at_s": 100.0, "confidence": 0.9,
         "bounds": {"x": 100.0, "y": 60.0, "width": 40.0, "height": 40.0}, "label": "Cube", "actions": ["set_colour"]},
        {"source": "application", "entity_id": "obj-17", "role": "shape", "captured_at_s": 100.2, "confidence": 0.9,
         "bounds": {"x": 104.0, "y": 60.0, "width": 40.0, "height": 40.0}, "label": "Cube", "actions": ["set_colour"]}
      ],
      "hint": null,
      "expected_entity_id": null
    },
    {
      "case_id": "s5-authority-colour-this",
      "description": "'Colour this blue' on a single fresh candidate; the verb is carried but not used by the resolver.",
      "now_s": 100.1,
      "target": {"source": "gaze", "timestamp_s": 100.0, "confidence": 0.8, "point": {"x": 120.0, "y": 80.0}},
      "candidates": [
        {"source": "application", "entity_id": "obj-17", "role": "shape", "captured_at_s": 100.0, "confidence": 0.9,
         "bounds": {"x": 100.0, "y": 60.0, "width": 40.0, "height": 40.0}, "label": "Cube", "actions": ["set_colour"]}
      ],
      "hint": {"verb": "colour", "role": null, "label_tokens": []},
      "expected_entity_id": "obj-17"
    },
    {
      "case_id": "s6-outcome-check-after-change",
      "description": "Re-observation after the (hypothetical) colour change; indistinguishable from the pre-change observation.",
      "now_s": 100.1,
      "target": {"source": "gaze", "timestamp_s": 100.0, "confidence": 0.8, "point": {"x": 120.0, "y": 80.0}},
      "candidates": [
        {"source": "application", "entity_id": "obj-17", "role": "shape", "captured_at_s": 100.05, "confidence": 0.9,
         "bounds": {"x": 100.0, "y": 60.0, "width": 40.0, "height": 40.0}, "label": "Cube", "actions": ["set_colour"]}
      ],
      "hint": null,
      "expected_entity_id": "obj-17"
    }
  ]
}

What was and was not checked¶

• Read at 8a72bbc6: src/yazses/grounding/contracts.py, resolver.py and the case format in trace.py; src/yazses/activation/confirm.py:53-143; the $defs.decision and scenario shape of examples/hci-hf-lab/fixtures.schema.json; the memo kernel-contract-fit.md.
• Checked on 2026-11-06 with gh issue view 700 (read-only): #700 is OPEN.
• Run on 2026-11-06: the replay script on the appendix trace (validator included), the decide one-liner and the tests listed under "Confirming run". All outcomes matched.
• Not run: anything in examples/hci-hf-lab; the hci-lab column is a vocabulary mapping.