Skip to content

fix: never ship a source field as an OKF key kbforge does not emit - #56

Merged
flyersworder merged 1 commit into
mainfrom
fix/reserve-unemitted-okf-keys
Oct 29, 2026
Merged

flyersworder merged 1 commit into
mainfrom
fix/reserve-unemitted-okf-keys

Conversation

@flyersworder

Copy link
Copy Markdown
Owner

OKF v0.2 defines verified, stale_after and usage_window, and kbforge emits none of them (see docs/design/2026-08-08-okf-02-deferred-decisions.md). _facets only dropped OKF_OWNED, so a source field with one of those names was written straight into the frontmatter:

  • A SQL date column named stale_after shipped stale_after: '2026-09-23'. Since the 2026-08-21 tightening of v0.2 §5, every OKF timestamp needs an explicit UTC offset, so that value is non-conformant.
  • A verified column would set a consumer's §5.3 trust tier with nothing behind it.

Change

  • synthesize.OKF_RESERVED lists the three keys. _facets drops them the same way it drops the owned keys.
  • A new okf-strict check rejects a rendered concept that carries any of them. That also catches a regressed _facets or a synthesizer that writes its own frontmatter.
  • kbforge-sql now rejects facets: [stale_after] (and the other two) at config time, as it already does for the owned keys, so the column can't silently disappear.
  • status is left alone on purpose. It's a common source column (kbforge-sql's own example uses status: active), and §5.4 gives an unknown value nothing to act on.

Verification

  • The offline suite passes (986 passed, 15 skipped), and ruff and ty pass.
  • I mutated each piece in place and restored it with git checkout --. Disabling the emitter drop fails the synthesize tests. Disabling the gate fails the strict tests, which assert on the failure message. Reverting the sql check fails its config test. With only the emitter broken, the gate still rejects the output (rendered concept carries 'stale_after' …).

Release note: kbforge_sql.config now imports OKF_RESERVED. When this ships, kbforge-sql's kbforge>=0.8.0 floor must move up to the kbforge release that carries it, and the two need separate tags. CHANGELOG has entries for both under Unreleased.

🤖 Generated with Claude Code

OKF v0.2 defines `verified`, `stale_after` and `usage_window`, and kbforge
emits none of them (docs/design/2026-08-08-okf-02-deferred-decisions.md).
`_facets` dropped only OKF_OWNED, so a source field with one of these
names became the only writer: a SQL `date` column named `stale_after`
shipped `stale_after: '2026-09-23'`, a date-only value v0.2 §5 now rules
out, and a `verified` column would set the §5.3 trust tier.

OKF_RESERVED names the three. The emitter drops them like owned keys,
and the strict validator rejects a rendered concept that carries one,
so a regressed `_facets` or a synthesizer writing its own frontmatter
is caught too. kbforge-sql rejects them in `facets` at config time, as
it does the owned keys. `status` stays a facet: it is a common source
column, and §5.4 gives an unknown value nothing to act on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@flyersworder
flyersworder merged commit b75eb98 into main Oct 29, 2026
6 checks passed
@flyersworder
flyersworder deleted the fix/reserve-unemitted-okf-keys branch October 29, 2026 11:20
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.

1 participant