open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Releases Activity

fix(okf-check): recommended last-change field follows the bundle's okf_version

Browse source 
The gate carried a flat RECOMMENDED list ending in `timestamp`. Upstream retired
that field in v0.2: "`timestamp` is superseded by `generated.at`" (okf/SPEC.md
§13.1:802-803, read at frozen 3fcbb9f), one of the version's two breaking
changes — while :804 still lets a consumer "fall back to a legacy `timestamp`
when `generated` is absent".

A version-unconditional list cannot serve both readings. It either nags a
correct v0.2 bundle about a retired field, or goes silent about a field v0.1
still wants. So the list is now chosen by the bundle root's own okf_version:
< 0.2 (or absent/unshaped) keeps `timestamp`, >= 0.2 asks for `generated`.
Absence gets the legacy floor deliberately — §3 echoes a missing marker rather
than failing it, so it still needs a defined list.

Measured, not assumed:
- Every fixture in both corpora and both live emitters (okr, linkedin-studio)
  still write `okf_version: 0.1`, so this changes NO verdict today. It is
  written now because the upstream reading is fresh and pinned to a commit.
- The parity signature is conceptCount|untyped|okfVersion|okfVersionAccepted
  (check-okf-parity.mjs:73-76) — warnings are not in it, so diverging from
  okr's list here cannot red the parity gate. Confirmed: 9/9 fixtures pass.
- The compare is component-wise, NOT parseFloat: okf_version is version-SHAPED,
  and parseFloat('0.10') is 0.1, which would sort 0.10 before 0.2 and hand a
  newer bundle the retired field. Guarded by its own test.

spec §4 is updated in the same commit — a gate and the convention it enforces
must not disagree about which field they want.

Tests 98 -> 103 (okf-check 17 -> 22). All six suites green; check-versions
11 OK / 0 WARN / 0 ERROR.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0135YZBcCDvH3BgG5yEtuHCA
This commit is contained in:
Kjell Tore Guttormsen 2026-07-31 21:27:31 +02:00
commit fa3c5d8482
3 changed files with 136 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/okf-second-brain/spec.md
View file

@ -83,8 +83,17 @@ catalog exercising that, and a reader must not take it as upstream's requirement
## 4. Recommended fields (warnings, not errors)
`title`, `description`, `resource` (canonical source URI), `tags`, `timestamp`. Supply where cheap.
`title`, `description`, `resource` (canonical source URI), `tags`, and a last-content-change
marker whose name depends on the bundle's `okf_version` (below). Supply where cheap.
- **The last-change marker is version-dependent.** A bundle declaring `okf_version` **< 0.2**
(or none at all) uses **`timestamp`**; **>= 0.2** uses **`generated`**. Upstream retired the
first in favour of `generated: { by, at }` — "`timestamp` is superseded by `generated.at`",
one of v0.2's two breaking changes (`okf/SPEC.md` §13.1:802-803, read at `3fcbb9f`) — while
still permitting a consumer to "fall back to a legacy `timestamp` when `generated` is absent"
(`:804`). The gate therefore asks each bundle for the marker its own version names, and never
nags a correct bundle of either version. An absent or non-version-shaped `okf_version` gets
the legacy floor: absence is echoed, not failed (§3), so it still needs a defined list.
- **Canonical name is `resource`** (the OKF spec's name) — **not** `source`.
- A field that would break a plugin's invariant may be omitted. Example: linkedin-studio omits
`timestamp` (its serializer is pure/deterministic — a timestamp would break round-trip) and