Skip to content

refactor(okf): typed FrontmatterError, yaml kept behind okf.py, enable ruff BLE - #1163

Merged
jasonssdev merged 13 commits into
mainfrom
refactor/frontmatter-typed-error
Sep 30, 2026
Merged

jasonssdev merged 13 commits into
mainfrom
refactor/frontmatter-typed-error

Conversation

@jasonssdev

Copy link
Copy Markdown
Owner

Summary

model/okf.py is now the only module that knows what a frontmatter parse failure looks like.

  • okf.load_frontmatter raises a typed okf.FrontmatterError (a ValueError subclass, so existing except ValueError sites keep working) for every parser failure: yaml.YAMLError, the library's own ValueError on impossible dates, and the other errors the YAML stack can raise. The parser error is chained as __cause__. Adds try_load_frontmatter, parse_frontmatter_fragment, okf_version_is_current and rewrite_okf_version.
  • Every except Exception that only guarded a frontmatter parse now catches okf.FrontmatterError (or ValueError where the same try also calls decode_relations, or (OSError, ValueError) where it also reads the file). Each site keeps its skip / fail-closed / preserve / raise behaviour.
  • bundle/source_titles.py, bundle/ledger.py and application/doctor.py no longer import yaml. The okf_version regex rewrite moved into okf.rewrite_okf_version; cli/main.py and application/repair.py use okf.okf_version_is_current.
  • Ruff BLE is enabled. The remaining broad catches (advisory caches, LLM and backend calls, probes, worker-thread forwarding) carry # noqa: BLE001 -- <reason>. evals/** has a per-file ignore for probe harnesses.

Related issue

Closes #1144

Type of change

  • refactor — no behavior change
  • chore / ci — tooling, build, or CI

How was this tested?

  • RED first: tests/unit/model/test_okf_frontmatter_error.py failed with 13 failures (AttributeError: module 'openkos.model.okf' has no attribute 'FrontmatterError' and the new helpers) before the implementation.
  • tests/unit/test_frontmatter_catch_narrowing.py: one site per class (skip: scan_source_titles; preserve: parse_provenance_entry; fail closed: _reread_sensitivity_blocked) proves a malformed file still degrades the same way and that an unrelated RuntimeError now propagates. Mutating scan_source_titles back to except Exception fails the propagation test.
  • Four existing tests simulated a parse failure with a generic RuntimeError / ValueError; they now raise okf.FrontmatterError, which is what a parse failure is.
  • uv run ruff check ., uv run ruff format --check ., uv run mypy . clean; full suite uv run pytest -q -p no:cacheprovider: 7833 passed, 2 skipped, after merging origin/main.

Checklist

  • My commits follow Conventional Commits.
  • I added or updated tests for the change.
  • I updated docs where behavior, interfaces, or the knowledge model changed (one line in AGENTS.md).
  • Lint, format, type check, and tests pass locally.
  • Output remains OKF-conformant and derived stores stay reconstructible.
  • The change is consistent with the project's guiding principles.

Notes for reviewers

  • Unchanged on purpose: an unterminated --- block, and frontmatter that is a list or scalar, still yield empty metadata from the library rather than an error (no spec asks otherwise). Only a block that is present and unparseable raises.
  • config.py still imports yaml: it parses openkos.yaml, not OKF frontmatter, so it is outside this seam.
  • Behavioural narrowing: where a site used to swallow any exception from the parse call, an unrelated programming error now surfaces. For the privacy fail-closed sites (query, retrieval/answer, volatility_typing, edge_typing, revisions, contradiction) a crash is still closed, but it is a crash rather than a silent confidential/empty result.
  • bundle/references.py and bundle/relations.py catch ValueError (covers FrontmatterError and decode_relations's shape error).
  • No CHANGELOG entry: no user-visible change.

@jasonssdev
jasonssdev merged commit a9c21df into main Sep 30, 2026
9 checks passed
@jasonssdev
jasonssdev deleted the refactor/frontmatter-typed-error branch September 30, 2026 19:30
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.

bug: okf.load_frontmatter lets yaml.YAMLError escape, so ~35 call sites each hand-roll a broad except and format knowledge leaks out of model/okf.py

1 participant