Skip to content

fix(semantic): resolve Option.insights against findings as well as prior_insights (closes #70)#89

Open
ksd3 wants to merge 1 commit into
LightconeResearch:mainfrom
ksd3:fix/option-insights-resolve-findings
Open

fix(semantic): resolve Option.insights against findings as well as prior_insights (closes #70)#89
ksd3 wants to merge 1 commit into
LightconeResearch:mainfrom
ksd3:fix/option-insights-resolve-findings

Conversation

@ksd3
Copy link
Copy Markdown

@ksd3 ksd3 commented May 15, 2026

Summary

Closes #70. Option.insights now resolves against the union of prior_insights and findings at each scope, instead of only prior_insights. An option may cite either kind of Insight — external evidence motivating the choice (prior_insights) or a claim produced by this analysis that in turn justifies a downstream choice (findings).

This matches the semantics laid out by the @claude analysis on the issue thread: the constraint is inherently cross-collection, LinkML cannot express it, and the enforcement therefore lives in the semantic validator.

Change shape

_validate_option_insight_ref previously resolved bare ids against prior_insights only (and ../id-form refs against an ancestor's prior_insights only). Both lookups now union with the corresponding findings map:

  • Bare id → {**prior_insights, **findings} at the node-local scope
  • ../id, ../../id, ... → union of prior_insights ∪ findings at the resolved ancestor scope (via the existing _resolve_ancestor_scope walk)

findings is threaded through _validate_decisions from both call sites — root (validate_analysis) and sub-node (_validate_analysis_node). Scope-description strings in INVALID_INSIGHT_REF messages updated to say "prior_insights or findings" so author-facing errors stay accurate.

Companion PR

A small documentation / schema-description change lives in LightconeResearch/astra-spec#39 — clarifies Option.insights's expanded resolution in analysis.yaml and docs/specification.md. The two are independent (each merges cleanly on its own) but read better together.

Test plan

  • pytest tests/test_validation.py — 83 passed (82 existing + 1 new)
  • Full suite (minus the pre-existing test_init_generated_files_are_valid failure unrelated to this change, tracked separately): 213 passed, 21 skipped
  • ruff check / ruff format --check / mypy clean on changed files
  • New valid fixture tests/fixtures/valid/option_insights_reference_finding.yaml covers four cases: bare id → prior_insight, bare id → finding, ../id → ancestor prior_insight, ../id → ancestor finding
  • Existing test_insight_ref_bare_id_does_not_walk_ancestors and test_insight_ref_escapes_too_far still pass — the union widens which map within a scope but does not widen which scope, so the cross-scope-isolation behavior is preserved

…ightconeResearch#70)

Option.insights previously only resolved against a node's prior_insights
map (at bare-id scope, or via ../-form refs at an ancestor's scope).
Findings are also Insight entries — claims produced by an analysis are
valid evidence for a downstream option, alongside literature-backed
prior_insights — so the validator now resolves Option.insights against
the union of prior_insights and findings at each scope.

The constraint is semantic, not syntactic: LinkML cannot express
"this id must resolve in either of two keyed maps." The schema in
astra-spec carries a documentation update describing the broader intent.

- Thread findings through _validate_decisions and _validate_option_insight_ref
- Union prior_insights ∪ findings at both bare-id and ancestor lookups
- Update scope-description strings in error messages
- Add valid fixture + test covering bare-id and ../-form refs into findings
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow Option.insights to reference findings (not only prior_insights)

1 participant