This matrix maps the pinned specification to implementation surfaces,
diagnostic policy and canonical evidence. It intentionally distinguishes
upstream requirements from skosovsky/okf strict policy.
| Clause | Executable contract | Implementation surface | Stable diagnostics / policy | Canonical evidence |
|---|---|---|---|---|
| §1 | OKF describes portable files; this toolkit never executes computations, executors or attesters | read-only bundle, validator, graph APIs |
no execution ABI or runtime verdict is inferred | positive/appendix-a, positive/durability; deferred-ABI contract |
| §2 | a bundle remains plain human-readable files; optional families are independently consumable | lossless frontmatter/body reads and BYOT decode/encode | no diagnostic for omission of an optional family | positive/minimal; lossless round-trip tests |
| §3 | revision-visible regular files form a bundle; reserved names are special | bundle.Source, bundle.Load, deterministic concept IDs |
I/O failure aborts; per-concept parse failures are collected | positive/appendix-a, positive/canonical, positive/durability |
| §3.1 | reserved filenames are not ordinary concepts | scanner and reserved-document validators | malformed present index.md/log.md is base ERROR |
legacy negative corpus and strict reserved-file goldens |
| §4.1, §11.1–11.2 | concept frontmatter is parseable; type is a non-empty YAML string |
bundle.Document, typed/raw frontmatter, validator base profile |
frontmatter_* or type_* base ERROR with exact field path |
positive/minimal, strict/adversarial corpus |
| §4.1 | unknown keys, unknown non-empty string types and unrelated duplicate producer keys are preserved and consumable; duplicate standard keys remain present but typed-unresolved | raw YAML node API, semantic value state plus BYOT decode/encode | no diagnostic solely for unknown data; typed reads never choose one duplicate value | positive/minimal, adversarial corpus, shared duplicate-key tests |
| §§4.2–4.4 | Markdown body and optional resource binding remain byte-readable | Document.Body, field-aware path observation |
missing resource target is not base non-conformance | canonical resource/path cases |
| toolkit parser boundary | parser-backed Markdown ownership accepts at most 16 MiB per complete document or separated body | bundle.MaxMarkdownDocumentBytes, bundle.MaxMarkdownBodyBytes, Context ownership accessors |
cancellation precedes invalid UTF-8, which precedes typed ErrMarkdownResourceLimit; rejected Context calls publish no partial result |
bundle/markdown_limit_contract_test.go, internal/markdownowner/markdown_limit_contract_test.go, and validator/markdown_limit_validation_test.go |
| §5.1 | sources and credibility signals are readable only from correctly tagged scalar shapes | typed source observations plus raw YAML access | malformed present shapes and duplicate attribution IDs are strict WARNING |
positive/appendix-a, strict/adversarial corpus |
| §5.1 | claim attribution joins prose-owned footnote labels to source IDs | parser-backed Document.Attributions |
orphan/duplicate joins are strict WARNING; inline and multiline code markers are ignored; exact shortcut [^label] references remain owned |
Appendix A, Markdown ownership tests and interoperability corpus |
| §5.2 | a valid bare verified mapping equals a one-item sequence |
typed verification observations | malformed actor/date/event is strict WARNING and cannot raise trust |
positive/canonical/verified-{bare,list}.md, strict corpus |
| §5.3 | trust tier is derived from valid verification events and is never stored | bundle trust helper; toolkit graph projection | absence of verification is accepted | canonical trust matrix |
| §§5.4–5.5, both pinned 0.2 revisions | only absent status defaults to stable; date-3fcbb9f compares calendar dates and instant-0b87c52 compares exact offset-bearing instants; omission of reference leaves staleness unevaluated |
explicit temporal profile, profile-aware lifecycle observation and injected-reference validator; CLI/MCP never default to wall clock | malformed present lifecycle is unresolved plus strict WARNING; reached boundary is policy warning only with explicit --as-of/as_of; old dates are not inferred instants |
both spec locks, instant boundary and legacy regression tests |
| §6.1 | concept links are Markdown-owned and bundle-relative; validation uses only the captured bundle snapshot, so ignored symlinks and later live-filesystem changes cannot satisfy targets | parser-backed link extraction and semantic index | broken links are not base errors; optional relation policy is separate | canonical links, ignored-symlink fixture, snapshot mutation and code-ownership tests |
| §6.2 | URL, root-relative and concept-relative path values are preserved; source scope ambiguity is explicit | field-aware path observation API | no network/existence conformance requirement; ambiguous source descriptors are not rewritten | canonical file-backed and scope/path adversarial cases |
| §6.3 | references/ is a convention, not a reserved namespace |
ordinary bundle asset capture | no special conformance diagnostic | Appendix A references tree |
| §7 | actor strings are classified only when valid; unknown producer namespaces remain open | typed provenance/verification actor helpers | malformed actor shape is strict WARNING; no registry enforcement |
canonical human/process/agent matrix |
| §8, §11.3 | present index.md groups linked entries under headings; an initial H1 title and introduction may precede populated groups |
reserved index parser and validator | empty grouping sections, malformed linked lists and empty listings remain base ERROR at body |
reserved-file tests and frozen interoperability corpus |
| §8, §11 | root index.md may declare okf_version; unknown adjacent keys are preserved under the consumer unknown-key prohibition in §11, even though §8 describes only the standard producer field |
reserved index declaration state and raw YAML | duplicate/malformed/missing declaration in a present root frontmatter block is a base ERROR; unknown adjacent keys alone are not |
root extension and declaration tests; frozen interoperability corpus |
| §9, §11.3 | present log.md follows flat, newest-first date groups; physical wrapped lines belonging to one list item are valid |
shared Markdown owner, typed log parser and validator | separate paragraphs and nested lists remain base ERROR at body; wrapped lines produce no diagnostic |
reserved-file tests and frozen interoperability corpus |
| §§10.1–10.2 | only exact type: Attested Computation exposes the typed contract |
typed computation accessor | malformed present fields are strict WARNING, never base ERROR |
Appendix A, canonical inline/file cases |
| §10.3 | exactly one top-level H1 section owns one closed direct-child fenced block, or a file path, as the computation; prose siblings are allowed, nested list/blockquote fences are conflicting example content | parser-backed typed computation inspection | missing/malformed/ambiguous modes are strict WARNING; code-owned headings do not count; nested candidates never degrade to absence |
TestAttestedComputationStateIsExactTypeAndPayloadOwned, TestComputationSectionsRetainUnclosedAndMultipleFenceSpans, strict Markdown adversarial cases |
| §§10.4–10.6 | concepts link to computations; the toolkit records definitions, not execution or attestation verdicts | semantic links and graph observations | no receipt execution or verdict inference | Appendix A and durability fixture |
| §11 | base conformance is exhaustive: only frontmatter/type/reserved structure produce errors; duplicate concept type is present but unresolved and remains a base error |
validator severity boundary and semantic duplicate state | semantic relation checks and explicit selector assertions are separate policy/API outcomes; other duplicate standard families are strict warnings | strict diagnostic golden sets and TestDuplicateTypeAndReservedVersionRemainBaseDiagnostics |
| §12 | root declaration is optional; every canonical unsupported declaration uses best-effort v0.2 and the frozen public source label future-best-effort; explicit selectors assert; duplicate root okf_version is present but unresolved |
shared version grammar/state and resolution | malformed or duplicate declaration is a reserved-root ERROR; conflict is an API error; valid unsupported raw value remains visible |
TestVersionResolutionUnsupportedCanonicalMatrix, TestDuplicateTypeAndReservedVersionRemainBaseDiagnostics, TestV02CompatibilityCorpusPreservesFallbackPrecedenceAndBytes |
| §13.1 | timestamp and # Citations are used only when replacements are completely absent |
effective provenance/time reads and marked legacy graph observations | malformed present replacement suppresses fallback; legacy representation alone is accepted | declared/undeclared v0.1 and mixed-provenance fixtures |
| §13.2 | additive unknown fields remain round-trippable | raw YAML/BYOT access | no rejection for future additive keys | future-version and adversarial fixtures |
| Appendix A | derived files stay traceable to the pinned example and declared transforms | derivation.json plus digest drift test |
fixture changes require explicit transform reason and new hashes | positive/appendix-a |
| toolkit extension | YAML relations is outside upstream v0.2 |
relation observations; opt-in graph extension policy | diagnostics never change upstream conformance | existing relation fixtures/tests |
| toolkit mutation policy | mutation preserves unrelated duplicate YAML keys and rejects only a duplicate path or selector touched by the requested operation | lossless presentation engine and semantic v0.2 operations | duplicate_touched_key/selector ambiguity is an operation error, never a whole-document read error |
shared mutation duplicate-key tests |
| toolkit graph profile | v0.2 JSON-LD/RDF vocabulary is toolkit-owned and versioned | explicit projection profile and graph contract | no invented predicates for unknown YAML | Appendix A plus graph contract/goldens |
Diagnostic codes and field paths are stable API. New family diagnostics use
paths such as sources[2].resource; callers must not parse human messages.