open/llm-ingestion-okf
1
0
Fork 0
Code Issues Pull requests Releases Activity

docs(plan): correct the Phase 4 parity oracle and the catalog re-pin premise

Browse source 
Both were wrong, and the convention owner corrected them: this library is not
a marketplace plugin, so there is no catalog ref to re-pin -- the integration
is a registry entry in the catalog's parity gate. And the catalog's vendored
okf-check.mjs is not byte-identical to okr's (~141 differing lines of code, an
intentional layer-1 floor), so it cannot serve as a conformance oracle. Parity
is behavioural over the spec section 3 floor in default read-mode, per file,
measured by that gate over an adversarial corpus.
This commit is contained in:
Kjell Tore Guttormsen 2026-07-25 07:35:54 +02:00
commit 0b77c58a1c
1 changed files with 24 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/plan/phase-4-node-half.md
View file

@ -25,10 +25,25 @@ code.
catalog spec are resolved WITH the convention owner before the lift — the
library implements the agreed contract, not one repo's drift.
2. **Catalog stays convention owner.** The second-brain spec remains in the
marketplace catalog; this repo implements it. After the lift, the catalog
re-pins its shared check gate to this repo's copy — acceptance is behavior
parity on the shared fixture suite, and the re-pin follows the marketplace's
release-tag pinning discipline.
marketplace catalog; this repo implements it. Two premises here were wrong
and are corrected by the convention owner (2026-07-25):
- *There is no re-pin to make.* The catalog's version mechanism operates
only over entries in its marketplace manifest, and this library is not a
plugin. Adding an entry to make the mechanism fit would misrepresent a
library as an installable plugin. The integration is instead a registry
entry in the catalog's parity gate (`check-okf-parity.mjs`), whose
implementation registry is already n-way and names this repo's future
checker explicitly. We register when an implementation legitimately
exists — never a placeholder.
- *Parity is not byte identity, and the vendored copy is not an oracle.*
The catalog's vendored `okf-check.mjs` diverges from okr's by ~141 lines
of CODE (strictIngest mode, file scoping, walk filtering, shared-lib
dependencies, BOM/CRLF handling) — an intentional decision to keep
layer 1 at the bare spec §3 floor, not drift to be repaired. Parity is
BEHAVIOURAL over that floor in default read-mode, at per-file
granularity, measured by the catalog's parity gate over an adversarial
corpus that carries a proof it can go red. No artifact self-certifies
parity.
3. **linkedin-studio stays plugin-local.** Its `ingest/published/`
provenance-record grammar has a different lifecycle by design and is NOT
normalized into this library. Explicit non-goal, agreed up front.
@ -69,7 +84,7 @@ code.
| # | Assumption | Test |
|---|---|---|
| D1 | okr's reference code + tests transfer cleanly to this repo's layout | Ported suite green before any behavior change; parity run against okr's copy on the shared fixtures |
| D1 | okr's reference code + tests transfer cleanly to this repo's layout | Ported suite green before any behavior change; behavioural parity over the spec §3 floor via the catalog's parity gate, not a byte comparison |
| D2 | The catalog spec is the single contract both halves implement | Phase 3 profile expresses it; cross-runtime fixture suite passes in both runtimes |
| D3 | Zero-dep core is compatible with doc conversion | Lazy-load pattern proven by a test run WITHOUT optional parsers installed: core commands work, `convert` fails fast with a clear message |
| D4 | Vendoring workflow works for consumers | Dry-run: copy `node/` into a scratch plugin layout, run the CLI from there, exit codes intact |
@ -88,9 +103,10 @@ code.
2. Zero-dep proof: `package.json` has no `dependencies`/`optionalDependencies`;
grep for non-`node:` imports in core modules returns nothing (conversion
module exempted, lazy-load only).
3. Parity: this repo's check gate and the currently vendored reference copy
produce identical verdicts on the full shared fixture suite (scripted
comparison, part of CI until the catalog re-pins).
3. Parity: this repo's check gate is registered in the catalog's parity gate
and agrees with the other implementations over the spec §3 floor in default
read-mode, per file, on the adversarial corpus that gate owns. Behavioural
agreement, never byte comparison against a vendored copy.
4. Cross-runtime agreement: Python (Phase 3 profile) and Node checkers give the
same accept/reject verdict per shared fixture (scripted matrix run).
5. CLI contract: each subcommand exercised via `node node/bin/okf.mjs …` in