open/llm-ingestion-okf
1
0
Fork 0
Code Issues Releases 1 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 catalog spec are resolved WITH the convention owner before the lift — the
library implements the agreed contract, not one repo's drift. library implements the agreed contract, not one repo's drift.
2. **Catalog stays convention owner.** The second-brain spec remains in the 2. **Catalog stays convention owner.** The second-brain spec remains in the
marketplace catalog; this repo implements it. After the lift, the catalog marketplace catalog; this repo implements it. Two premises here were wrong
re-pins its shared check gate to this repo's copy — acceptance is behavior and are corrected by the convention owner (2026-07-25):
parity on the shared fixture suite, and the re-pin follows the marketplace's - *There is no re-pin to make.* The catalog's version mechanism operates
release-tag pinning discipline. 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/` 3. **linkedin-studio stays plugin-local.** Its `ingest/published/`
provenance-record grammar has a different lifecycle by design and is NOT provenance-record grammar has a different lifecycle by design and is NOT
normalized into this library. Explicit non-goal, agreed up front. normalized into this library. Explicit non-goal, agreed up front.
@ -69,7 +84,7 @@ code.
| # | Assumption | Test | | # | 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 | | 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 | | 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 | | 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`; 2. Zero-dep proof: `package.json` has no `dependencies`/`optionalDependencies`;
grep for non-`node:` imports in core modules returns nothing (conversion grep for non-`node:` imports in core modules returns nothing (conversion
module exempted, lazy-load only). module exempted, lazy-load only).
3. Parity: this repo's check gate and the currently vendored reference copy 3. Parity: this repo's check gate is registered in the catalog's parity gate
produce identical verdicts on the full shared fixture suite (scripted and agrees with the other implementations over the spec §3 floor in default
comparison, part of CI until the catalog re-pins). 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 4. Cross-runtime agreement: Python (Phase 3 profile) and Node checkers give the
same accept/reject verdict per shared fixture (scripted matrix run). same accept/reject verdict per shared fixture (scripted matrix run).
5. CLI contract: each subcommand exercised via `node node/bin/okf.mjs …` in 5. CLI contract: each subcommand exercised via `node node/bin/okf.mjs …` in