MRK-2.0: Machine-Ready Knowledge, maturity layer

Status Released 2026-10-19

Abstract

MRK-1.0 defines a machine-ready article: YAML front matter that validates against a JSON Schema, plus four editorial clauses. MRK-1.1 adds optional fields to that format. MRK-2.0 is a maturity layer over the 1.1 article format. It does not change the article format. It defines:

• five producer conformance classes (rungs L0 to L4) and how a tool assigns them;
• the graph projection of a corpus to RDF and the SHACL integrity gate over it;
• declared transclusion and the drift gate that keeps reused text honest;
• the consumer clause R (R1 to R7) and two consumer conformance classes, C1 and C2;
• a citation object, an evidence document, and the rules for claiming conformance;
• versioning and compatibility rules for the standard and the article format.

Every requirement has a stable identifier and is mapped to the check that tests it in Appendix C. Requirements that can only be attested say so and name the evidence.

Contents

1. Conventions and terminology
2. Scope and relationship to MRK-1.0 and MRK-1.1
3. Article format
4. Producer conformance classes (L0 to L4)
5. Namespace and identifiers
6. Graph projection
7. Integrity gate
8. Reuse: declared transclusion and drift
9. Clause R: retrieval conformance
10. Consumer conformance classes and the citation object
11. Conformance evidence
12. Corpus reporting and conformance claims
13. Versioning and compatibility
14. Security and privacy considerations
15. Changelog from MRK-1.1

• Appendix A: Normative artifacts
• Appendix B: Reference tools
• Appendix C: Conformance-test mapping
• Appendix D: Resolved inconsistencies
• Appendix E: Open issues

1. Conventions and terminology

1.1 Requirement language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

1.2 Requirement identifiers

Each requirement is a list item that begins with its identifier in bold, for example C-R5-1. Identifiers are stable. A later edition never reuses or renumbers an identifier; a withdrawn requirement keeps its identifier with the note "withdrawn". The prefixes are:

Text outside requirement items is informative unless it defines a term.

1.3 Terminology

• Article: one unit of knowledge, identified by id, with front matter and (for Markdown) a body.
• Front matter: the YAML mapping that describes an article. It is either a .yaml file or the --- fenced block at the start of a .md file.
• Section: an addressable part of an article, identified by article-id#slug.
• Corpus: the set of articles scored, projected or served together.
• Producer: whoever authors and publishes a corpus. Producer tool: software that validates, scores, lints or projects a corpus.
• Consumer: software that assembles answers from MRK articles (a retriever or answer assembler).
• Reader context: the facts about the person an answer is for (applicability dimensions, visibility scope, entitlements, locale, intent role), as given to a consumer.
• Rung: one of the producer classes L0 to L4.
• Gate: a mechanical check whose failure blocks a rung or a build.
• Attestation: a statement by a person or organisation that a property holds, which no tool checks. An attested requirement names the evidence that supports it.
• Evidence: a machine-readable record of a conformance run (§11).
• Projection: the transform from front matter to RDF defined in §6.
• Canonical JSON, article digest, suite digest: defined in §11.2.

2. Scope and relationship to MRK-1.0 and MRK-1.1

MRK-2.0 is a version of the standard, not of the article format. The article format of MRK-2.0 is MRK-1.1, which is a strict superset of MRK-1.0 for every instance that does not reuse a 1.1 field name with a non-conforming value (§13, Appendix D item 23).

MRK-2.0 has three conformance targets:

1. Articles and corpora (producer classes, §4), scored by a producer tool.
2. Consumers (consumer classes, §10), tested by the conformance suite.
3. Producer tools and validators, which must follow the processing rules in §3, §6 to §8, §11 and §13.

MRK-2.0 does not judge prose quality, coverage, or whether an answer is correct. Those remain human review.

3. Article format

The article format is defined by mrk-1.1.schema.json and, for instances that declare or default to format 1.0, mrk-1.0.schema.json (Appendix A). The four MRK-1.0 editorial clauses continue to hold.

• A-1 An article's front matter MUST validate against mrk-1.1.schema.json (JSON Schema 2020-12) to be scored above L0.
• A-2 Front matter MUST be either a .yaml file whose top-level value is a mapping, or a .md file that begins with a line ---, followed by a YAML mapping, followed by a line ---.
• A-3 (MRK-1.0 §1) A section marked self_contained: true MUST be safe to read in isolation: it MUST NOT depend on another section for its meaning ("as described above") and MUST state its prerequisites inside itself. This is attested. Evidence: the self_contained flag, set by a human at the curation gate. Tools check only the flag's value.
• A-4 (MRK-1.0 §2) Applicability MUST be stated as data in applies_to, with at least one dimension.
• A-5 (MRK-1.0 §3) An article id or section id MUST NOT change after it is assigned and MUST NOT be reused after retirement. This is attested. Evidence: the corpus's revision-control history. Tools check only the identifier format.
• A-6 The part of a section id before # MUST equal the id of the article that contains the section.
• A-7 (MRK-1.0 §4) owner, verified and lifecycle MUST be present. verified MUST be an RFC 3339 full-date (YYYY-MM-DD).
• A-8 A producer tool MUST convert a YAML date or timestamp value (for example an unquoted verified: 2026-07-30) to its ISO 8601 string before schema validation, and MUST validate format: "date" as an assertion, not only an annotation.
• A-9 A producer tool MUST parse YAML with a safe loader that constructs only plain mappings, sequences and scalars.

4. Producer conformance classes (L0 to L4)

Each article sits on exactly one rung. Rungs measure machine-readiness depth. They are reached by adding front matter and running the gates, never by rewriting prose.

4.1 General rules

• P-G-1 A producer tool MUST assign each article exactly one rung: the highest rung whose criteria, and the criteria of every lower rung, all hold.
• P-G-2 A rung is all-or-nothing. An article that meets only some of a rung's criteria MUST be reported at the rung below.
• P-G-3 For each article below L4, a producer tool MUST report the first unmet criterion of the next rung, in the order the criteria are listed in §4.2 to §4.6.
• P-G-4 A rung MUST NOT depend on the age of verified or on the value of lifecycle. Freshness is a separate signal (consumers handle it under R2).

4.2 L0 Prose

• P-L0-1 An article whose front matter is missing, fails A-1, or fails any L1 criterion MUST be reported as L0.

4.3 L1 Contracted

• P-L1-1 The front matter validates against mrk-1.1.schema.json (A-1, after A-8 normalisation).
• P-L1-2 Every section has self_contained: true.
• P-L1-3 applies_to is present and has at least one dimension.
• P-L1-4 owner, verified and lifecycle are present.
• P-L1-5 Every section id satisfies A-6.

L1 is checked against the 1.1 schema, which does not require plan and region. L1 is therefore not the same as MRK-1.0 conformance (see K-7).

4.4 L2 Typed

• P-L2-1 Every section has a role.
• P-L2-2 If type is issue-resolution, the sections include the roles cause, resolution and verification. If type is task, the sections include the role procedure. This criterion applies whatever the mrk_version. Other type values, including concept and reference, impose no section shape in MRK-2.0.
• P-L2-3 visibility is present.

4.5 L3 Linked

• P-L3-1 The article has at least one edge: a non-empty relations list, or at least one section with a non-empty requires list.
• P-L3-2 concepts is non-empty on the article or on at least one section.
• P-L3-3 The article's front matter, normalised per §6, projects to RDF with the context without error.

4.6 L4 Reasoned

L4 has a mechanical half (P-L4-1, P-L4-2) and an operational half (P-L4-3), which is either measured by evidence or attested by the producer.

• P-L4-1 The article has no SHACL violation attributed to it (§7) when the whole corpus graph is validated against shapes.ttl.
• P-L4-2 If the article is a .md file, the drift gate (§8) reports no finding for any of its sections.
• P-L4-3 Graph-first retrieval of the article MUST be either measured or attested. It is measured when at least one evidence document supplied to the tool satisfies all of: it validates against mrk-evidence.schema.json; its self-hash verifies (E-5); its suite_sha256 equals the tool's suite digest (E-4); levels.C2 is "pass"; self_test is "rejected-broken-consumer"; corpus.articles[id] equals the article's current digest (E-3); for every article that is the target of an edge in one of the article's derived cases (E-6), corpus.articles records that target's digest and it equals the current digest of that article in the corpus being scored; at least one derived case of the article has a non-empty expect and ok: true; and no derived case of the article has ok: false. A derived case with an empty expect measures nothing: it never counts towards the "at least one". It is attested when no evidence measures it and the producer passes the attestation option (--graph-first). An attested L4 is an attestation. Evidence: the producer's own statement, recorded as l4_basis: "attested".
• P-L4-4 A producer tool MUST record the basis of every L4 result as measured or attested. When both apply, the basis MUST be measured.
• P-L4-5 A producer tool MUST NOT assign L4 without running the SHACL gate. If the SHACL engine is unavailable, the tool MUST fail rather than fall back.
• P-L4-6 When an L3 article is not promoted, a producer tool MUST report the most specific reason, checked in this order: SHACL violation; drift finding; evidence digest mismatch (the article is not covered, or its digest, or the digest of one of its edge targets, differs: "evidence predates this article"); evidence from a different suite; evidence without a C2 pass or whose self-test did not reject the broken consumer; no derived case that measures this article (E-6); a derived case of this article failed; neither measured nor attested. Evidence that does not validate or whose self-hash fails is reported before the evidence reasons (digest mismatch onward), but after a SHACL violation or drift finding, which are about the article itself.

The rule, as a producer tool applies it:

for each article a with rung(a) == 3:
  if a.id in shacl_failures:                 L3, "L4: SHACL - <message>"
  elif a is .md and drift(a) != []:          L3, "L4: drift - <finding>"
  elif some evidence e measures a (P-L4-3):  L4, basis = measured
  elif --graph-first:                        L4, basis = attested
  else:                                      L3, most specific reason (P-L4-6)

5. Namespace and identifiers

• N-1 The MRK vocabulary IRI is https://machinereadyknowledge.com/ns#. Every MRK class and property (for example mrk:Article, mrk:Section, mrk:sectionRole, mrk:requires) MUST be in this namespace, and the context's @vocab and mrk prefix and the mrk prefix in shapes.ttl MUST all equal it.
• N-2 The publisher of this standard MUST serve a human-readable description of the vocabulary at https://machinereadyknowledge.com/ns.
• N-3 Article and section IRIs are formed by resolving id against the context's @base (https://machinereadyknowledge.com/kb/); concept IRIs are formed against https://machinereadyknowledge.com/vocab/. These IRIs are identifiers only. They, and all /kb/ and /vocab/ IRIs shown in examples, are illustrative and not dereferenceable. Consumers and producer tools MUST NOT dereference them.

6. Graph projection

The projection turns a corpus into one RDF graph. The context cannot express two transforms, so they are applied to each article's front matter first.

• G-1 The projection MUST use mrk-1.1.context.jsonld (JSON-LD 1.1) exactly as published (Appendix A).
• G-2 Before the context is applied, the article mapping MUST get "@type": "mrk:Article", and each item of sections MUST get "@type": "mrk:Section".
• G-3 Before the context is applied, relations MUST be removed and expanded. For each {rel, target}: if rel is one of depends_on, prerequisite_of, references, part_of, see_also, applies_with, append target to the list under the key named rel; if rel is supersedes, set supersedes to target only if supersedes is not already set. Other rel values are dropped.
• G-4 A corpus MUST be projected as a single JSON-LD document whose @graph lists every normalised article, so cross-article edges resolve within one graph.
• G-5 Dates MUST be serialised as ISO 8601 strings before projection, so that verified projects as an xsd:date literal.
• G-6 The projection MUST be deterministic: the same corpus MUST project to isomorphic graphs.

7. Integrity gate

shapes.ttl (Appendix A) is normative. JSON Schema checks one article; SHACL checks the corpus graph, where cross-article references can be resolved.

• I-1 The corpus graph MUST be validated against shapes.ttl as a whole (not per article) with a SHACL Core processor.
• I-2 Each mrk:Article MUST have exactly one dcterms:title, at least one mrk:verified of datatype xsd:date, a mrk:lifecycle in the 1.1 enumeration, an optional mrk:visibility in the 1.1 enumeration, and at least one mrk:hasSection of class mrk:Section (mrk:ArticleShape).
• I-3 Each mrk:Section MUST have exactly one mrk:sectionRole in the 1.1 role enumeration and an mrk:selfContained of datatype xsd:boolean (mrk:SectionShape).
• I-4 Every object of mrk:requires MUST be a mrk:Section in the corpus graph (mrk:RequiresIntegrityShape).
• I-5 Every object of mrk:dependsOn MUST be a mrk:Article in the corpus graph (mrk:DependsOnIntegrityShape). A depends_on relation therefore MUST target an article id, not a section id.
• I-6 Every object of dcterms:replaces (from supersedes) MUST be a mrk:Article in the corpus graph (mrk:SupersedesIntegrityShape).
• I-7 Targets of prerequisite_of, references, part_of, see_also and applies_with SHOULD resolve to a node in the corpus graph. The 2.0 shapes do not check these.
• I-8 A producer tool MUST attribute each SHACL violation to an article. If the focus node has an rdf:type in the graph, the violation belongs to the article of that node. Otherwise the focus node is a dangling target, and the violation belongs to every article whose node, or one of whose section nodes, is the subject of a triple with that target as object.

8. Reuse: declared transclusion and drift

MRK-1.0 §1 requires each section to restate its prerequisites. That creates copies. MRK-2.0 keeps the copy inline, declares where it came from, and gates drift between copy and source.

8.1 Grammar

• D-1 A transcluded block MUST open with <!-- mrk:transclude TARGET --> and close with <!-- /mrk:transclude -->, where whitespace inside the comment delimiters is free and TARGET is a section id matching ^[a-z][a-z0-9-]*-[0-9]+#[a-z][a-z0-9-]*$. Blocks MUST NOT nest.
• D-2 In a .md body, each section MUST begin with a level-2 heading ending in {#slug}. The section body is the text from that heading to the next such heading or the end of the file, and corresponds to the front-matter section article-id#slug.

8.2 Rules

• D-3 TARGET MUST resolve to a section present in the linted corpus.
• D-4 TARGET MUST be listed in the requires of the front-matter section that encloses the block.
• D-5 A block MUST NOT name its own enclosing section as TARGET. The target is the canonical source; edits are made there and copies are updated to match.
• D-6 The block MUST be grounded in its source: the grounding score MUST be at least 0.5. The score is |W(block) ∩ W(canonical)| / |W(block)|, where W(text) is the set of lower-cased tokens matching [a-zA-Z0-9_]+ that are longer than two characters and not in the stop list below, and canonical is the target section's body with every transcluded block removed. A block with an empty W passes.
• D-7 A drift linter MUST exit with a non-zero status when any of D-3 to D-6 fails, and MUST name the section, the target and the failed rule.

Stop list (normative for D-6): a an the of to in on and or is are was were be been for with that this it its as at by from into if then so no not up out you your they them their.

9. Clause R: retrieval conformance

MRK-1.0 specifies the article. Clause R specifies the consumer that turns articles into an answer. R1 to R7 are the rule groups; the numbered items are the requirements.

R1 Applicability

• C-R1-1 A consumer MUST evaluate each candidate's applies_to against the reader context and MUST NOT quote a section whose applicability excludes the reader.
• C-R1-2 For plan, region, product, component, audience, role and jurisdiction: a dimension constrained by the article and not supplied by the reader context MUST NOT match. Only the explicit value "all" matches every reader.
• C-R1-3 For version, version_min, version_max, version_exact and each dimensions entry: a consumer that does not evaluate the dimension MUST treat the article as not matching, unless the value is "all".

R2 Freshness and lifecycle

• C-R2-1 A consumer MUST read verified and lifecycle, and MUST NOT serve a section from an article whose lifecycle is retired or expired.
• C-R2-2 A consumer SHOULD downweight an article whose verified date is older than its freshness window (365 days unless the consumer declares another), and SHOULD mark its citations stale: true.
• C-R2-3 A consumer SHOULD prefer a current source over a superseded one for the same claim, and SHOULD mark citations from a superseded article superseded: true. Superseded articles are downweighted, not refused.
• C-R2-4 A consumer MUST take the reference date for freshness as an input, so that a conformance run can fix it.

R3 Safety

• C-R3-1 A consumer MUST NOT surface an article whose visibility ranks above the reader's scope (order: public < internal < confidential). An absent visibility means public.
• C-R3-2 A consumer MUST NOT surface an article with a non-empty entitlement unless the reader holds every listed key.
• C-R3-3 A consumer MUST NOT surface an article whose locale primary language subtag differs from the reader's, unless the reader context explicitly accepts that locale as a fallback.
• C-R3-4 A consumer MUST declare a default locale and MUST apply it to articles with no locale.

R4 Sections, not pages

• C-R4-1 A consumer MUST retrieve and quote addressable sections and cite them as article-id#slug, not whole pages or arbitrary character windows.
• C-R4-2 A consumer MUST quote only sections with self_contained: true.

R5 Graph before similarity

• C-R5-1 When articles carry relations or requires and a projected graph is available, a consumer SHOULD resolve retrieval by graph traversal and use vector similarity only to interpret the query or shortlist candidates. At C2 this is a MUST, tested by C-R5-2 to C-R5-5.
• C-R5-2 At C2, for a reader context whose matching articles have no edges, the graph path MUST return the same set of section ids as the flat path.
• C-R5-3 At C2, when a matched article depends_on another, the graph path MUST add the target article's self_contained: true sections.
• C-R5-4 At C2, when a matched section requires another section, the graph path MUST add the required section.
• C-R5-5 At C2, every section the graph path adds MUST pass the R1 to R4 gates for the same reader context.

R6 Citation

• C-R6-1 Every claim in an assembled answer MUST carry a citation object that validates against answer-object.schema.json, with section, article and verified.
• C-R6-2 A citation's article MUST equal the part of its section before #, and its verified MUST equal that article's verified.
• C-R6-3 A citation's version, when present and not null, MUST be the article digest (§11.2) in the form sha256:<64 hex>. It MUST NOT carry the mrk_version value.
• C-R6-4 Citations from the graph path SHOULD carry stale and superseded on the same terms as the flat path.

R7 Role-aware assembly

• C-R7-1 When sections carry role and the reader context gives an intent role, a consumer SHOULD assemble from sections of that role (for example a fix from resolution or procedure, an explanation from cause or concept), not by position or similarity alone. At C2 this is a MUST.

10. Consumer conformance classes and the citation object

• C-L-1 A consumer conforms to C1 when it satisfies every MUST in R1, R2, R3, R4 and R6, and passes every suite case graded on its flat path (answer) alone. A C1 claim MUST NOT require a graph path.
• C-L-2 A consumer conforms to C2 when it conforms to C1, satisfies C-R5-1 to C-R5-5 and C-R7-1 as MUST, passes every parity and r5_contract suite case, and, when a corpus is given, passes every derived case for that corpus (§11.3).
• C-L-3 A consumer under test MUST expose this interface: it is constructed as Class(article_paths); answer(ctx) returns a list of citations, or a pair (citations, notes); for C2, answer_graph(ctx) returns a list of citations. ctx is a mapping that MAY contain the applicability dimensions, reader_scope, reader_entitlements, locale, accept_locales, intent_role and today.
• C-L-4 The conformance harness MUST reject the reference broken consumer (one that ignores R3) in its self-test. A run whose self-test does not reject it MUST NOT be recorded as passing.

The citation object is defined by answer-object.schema.json (Appendix A): required section, article, verified; optional version, stale, superseded; further properties allowed.

11. Conformance evidence

Evidence binds a consumer's conformance run to a specific suite and a specific corpus, so that L4's operational half and C1/C2 claims can be measured rather than only attested.

11.1 The evidence document

• E-1 An evidence document MUST be a JSON object that validates against mrk-evidence.schema.json and has these members: mrk_evidence ("1"), kind ("retrieval-conformance"), spec ("MRK-2.0"), tool (name, version), suite_sha256, consumer (entry, name, version), run_at (RFC 3339 date-time, UTC; required), today (full-date), levels (C1, "pass" or "fail"; C2, "pass", "fail" or "not-claimed", the last for a consumer that implements C1 only; L4 measured requires "pass"), suite_results (one entry per suite case with name, mode, rules, ok), self_test ("rejected-broken-consumer" or "accepted-broken-consumer"), corpus (required; articles: map from article id to article digest, empty when no corpus was given; derived_cases: list of article, edge, section, target, ctx, expect, ok, and, when present, missing and error), and sha256.

Example (values shortened):

{
  "mrk_evidence": "1",
  "kind": "retrieval-conformance",
  "spec": "MRK-2.0",
  "tool": { "name": "mrk-tools", "version": "2.0.0" },
  "suite_sha256": "4f1c…",
  "consumer": { "entry": "acme_rag.mrk:Consumer", "name": "acme-rag", "version": "4.2.1" },
  "run_at": "2026-10-19T14:03:00Z",
  "today": "2026-10-19",
  "levels": { "C1": "pass", "C2": "pass" },
  "suite_results": [ { "name": "public-starter", "mode": "parity", "rules": "R1 R2 R3 R4 R6 R7", "ok": true } ],
  "self_test": "rejected-broken-consumer",
  "corpus": {
    "articles": { "ck-ops-1": "sha256:9a0e…", "ck-ops-2": "sha256:77b2…" },
    "derived_cases": [
      { "article": "ck-ops-2", "edge": "depends_on", "target": "ck-ops-1",
        "section": "ck-ops-2#steps", "ctx": { "reader_scope": "public", "locale": "en", "intent_role": "procedure" },
        "expect": ["ck-ops-2#steps", "ck-ops-1#resolution"], "ok": true }
    ]
  },
  "sha256": "c03d…"
}

11.2 Digests

• E-2 Canonical JSON of a value MUST be the UTF-8 encoding of json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str) as produced by Python 3; date and datetime values are rendered as their ISO 8601 strings. Other implementations MUST produce identical bytes.
• E-3 The article digest MUST be "sha256:" followed by the lower-case hex SHA-256 of the canonical JSON of the article's front matter mapping. It covers front matter only; body changes are the drift gate's concern.
• E-4 The suite digest MUST be the lower-case hex SHA-256 over, for each file under the suite's fixtures/ directory in ascending order of its POSIX path relative to the suite root, the bytes of that path, one zero byte, the file bytes and one zero byte; followed by the canonical JSON (E-2) of the suite's case list (the cases array of cases.json), with every set rendered as a sorted array. Nothing else under the suite root is hashed and no byte is normalised (no newline or Unicode conversion), so a checkout MUST keep the suite files byte-for-byte; a repository SHOULD mark them as binary (-text in .gitattributes).
• E-5 The sha256 member MUST be the lower-case hex SHA-256 of the canonical JSON of the evidence object with the sha256 member removed.

11.3 Derived cases

• E-6 For a corpus run, the harness MUST generate exactly one derived case for each edge A to T, where an edge is either a depends_on relation of article A to article T, or a section s of A that requires section T. For a requires edge the case's section is s. For a depends_on edge it is A's first section that has a role and self_contained: true (an article with none yields no case for that edge). The reader context MUST be built from A: for each R1 dimension in A's applies_to, the first listed value (a scalar value is used as is); reader_scope from A's visibility (default public); reader_entitlements from A's entitlement; locale from A's locale if present; version from A's version_exact, else version, else version_min, else version_max (the first listed value that is not "all"); dimensions with the first listed value of each entry that is not "all"; intent_role from the case's section role. expect MUST be the servable sections the edge must surface: the case's section if it is self_contained: true and servable under that context, plus the target sections that are self_contained: true and servable under that context (for a requires edge, section T; for a depends_on edge, every section of article T). Sections that are not servable are not expected. A case MUST be recorded ok: true only if expect is a subset of the section ids returned by answer_graph(ctx) and the call raised no error. A case with an empty expect is vacuous: it is recorded, but it never measures anything (P-L4-3). The evidence MUST record, in corpus.articles, the digest of A and of every article T that is the target of an edge of A that is present in the corpus; a target absent from the run is simply not recorded, and an article with an edge to it is not measured (P-L4-3, P-L4-6).
• E-7 The harness MUST record in today the reference date it passed to the consumer (C-R2-4). The standard suite fixes its own date (today in cases.json); corpus runs use the run date. today is the date of the derived cases (the suite date when there is no corpus), and each derived case records the date it used as ctx.today, so the evidence shows what every derived case ran with. The suite cases' fixed date is not recorded per case.

11.4 Verification

• E-8 An evidence verifier MUST check, in order: schema validity (E-1); the self-hash (E-5); that suite_sha256 equals its own suite digest (E-4); and, when given the corpus, that each listed article digest matches the current front matter (E-3). The verifier MUST also report a failed case: it MUST NOT pass evidence that contains a suite or derived case with ok: false. The verifier re-runs the derived cases and compares expect and ok only when it is explicitly given a consumer and a corpus (the kit's --consumer with --corpus); it MUST NOT import the consumer that consumer.entry names on the evidence's own say-so, because that would execute code chosen by the evidence file. Giving a consumer without a corpus is a usage error.

Evidence proves integrity and freshness of a run, not who ran it (§14).

12. Corpus reporting and conformance claims

• K-1 A producer tool's corpus report MUST include the count of articles at each rung L0 to L4, the contract rate (share at L1 or above) and the graph-ready rate (share at L3 or above).
• K-2 Whenever any article reaches L4, the report MUST include one line giving the L4 basis counts: L4 basis: N measured, M attested, however L4 was reached (evidence, attestation, or both). Measured and attested L4 both count as L4 in the distribution.
• K-3 When asked for machine-readable output, a producer tool MUST emit, per article, its id, rung, next-rung reason (if any) and, for L4, l4_basis.
• K-4 A published producer claim MUST name the standard version (MRK-2.0), the corpus size, the contract and graph-ready rates, and for any L4 figure its basis split. Example: "MRK-2.0 producer; corpus kb/ (412 articles): contract 88%, graph-ready 64%, L4 12% (measured 12%, attested 0%)". This is attested by the publisher. Evidence: the retained producer-tool report (K-1 to K-3) the claim quotes.
• K-5 A producer SHOULD base L4 claims on measured evidence rather than attestation.
• K-6 A published consumer claim MUST name the class and cite the evidence digest. Example: "MRK-2.0 C2 consumer (acme-rag 4.2.1), evidence sha256:c03d…". This is attested by the publisher. Evidence: the evidence document whose sha256 is cited, which anyone can check with E-8.
• K-7 A corpus MUST NOT be described as MRK-1.0 conformant on the strength of L1 alone. MRK-1.0 conformance requires validation against mrk-1.0.schema.json. A producer tool MUST NOT label L1 as "MRK-1.0".

13. Versioning and compatibility

MRK has two version axes. The standard version (MRK-1.0, MRK-2.0) names this document and its conformance classes. The article-format version is the mrk_version value in front matter.

• V-1-1 (V1) MRK-2.0 defines no new mrk_version value. Its format versions are "1.0" (or absent) and "1.1".
• V-2-1 (V2) A 2.0 producer tool or consumer MUST accept every instance that is valid under the schema of its format version (mrk-1.0.schema.json for absent or "1.0", mrk-1.1.schema.json for "1.1"): it MUST process it without error, and a validator MUST report it valid. Scoring is separate: a rung is still decided by A-1.
• V-2-2 (V2) An absent mrk_version MUST be treated as "1.0".
• V-3-1 (V3) A consumer MUST NOT reject an article because it has properties the consumer does not recognise. It MAY ignore them.
• V-4-1 (V4) A minor format version (1.x) MUST be strictly additive: every instance valid under the previous minor version that does not use a newly added property name MUST remain valid.
• V-4-2 (V4) Every new constraint in a minor format version MUST apply only to instances that opt in by declaring that mrk_version (or by using a property introduced in that version, such as profile).
• V-4-3 (V4) mrk_version values "2" and higher are reserved for a future breaking format change. MRK-2.0 instances MUST NOT use them.
• V-5-1 (V5) A validator that meets an mrk_version it does not know MUST report it as unknown and MUST NOT validate the instance against an older schema in its place.
• V-6-1 (V6) The validation keywords of a published schema $id MUST NOT change. Its title, description and $comment text MAY be corrected. The validation fingerprint (Appendix A) is the test.
• V-6-2 (V6) mrk-1.0.schema.json is frozen: its bytes MUST NOT change.
• V-6-3 (V6) At the release of MRK-2.0, mrk-1.1.schema.json is frozen in its validation keywords (V-6-1).

14. Security and privacy considerations

• R3 (C-R3-1 to C-R3-4) is the safety gate. C-R5-5 applies it to every section the graph path adds, so dependency traversal cannot leak internal content into a public answer.
• Evidence is self-produced and unsigned. Its hashes show that a run is intact and matches the current corpus; they do not show who ran it. A verifier that needs more assurance re-runs the derived cases (E-8).
• --consumer loads and runs third-party code with the caller's privileges.

• S-1 Producer tools, the conformance harness and the evidence verifier MUST NOT access the network at run time. Spec files are bundled with the tools or given with --spec DIR.

15. Changelog from MRK-1.1

• Released 2026-10-19 as the first release of MRK-2.0. MRK-1.0 and MRK-1.1 are frozen formats; this release adds no format.
• No article-format change. No new mrk_version. The 1.1 schema is frozen in its validation keywords as of this release (V-6-3). Its title and description were corrected editorially: the DRAFT label is dropped and the description points to /mrk-2.0.
• New: producer classes L0 to L4 (§4), with measured or attested L4.
• New: namespace and identifier rules (§5).
• New: projection normalisation made normative (§6).
• New: SHACL integrity gate, with per-article attribution (§7).
• New: declared transclusion grammar and the drift gate, which joins L4 (§8).
• New: consumer clause R with classes C1 and C2 (§9, §10), and the citation object.
• New: evidence document, digests, corpus-derived cases and verification (§11).
• New: reporting and claim rules (§12).
• Clarified: section ids must belong to their article (A-6); YAML dates are normalised and format: date is asserted (A-8); a citation version is the article digest, not mrk_version (C-R6-3); applicability dimensions a consumer cannot evaluate fail closed (C-R1-3); absent locale uses the consumer's declared default (C-R3-4).
• Changed: validators must reject an unknown mrk_version instead of falling back (V-5-1).
• Reserved: mrk_version values "2" and higher (V-4-3).
• Compatibility note (non-normative): an instance whose verified is not an ISO date (for example 2026-7-3, 20260730, or a timestamp such as 2026-07-30T10:00:00Z) or whose section id does not start with its article's id now scores L0, where the MRK-1.1-era scorer gave L1 (A-6, A-7, A-8). The 1.1 schema is unchanged; these checks are the scorer's, so an external 1.0 or 1.1 corpus can drop a rung until those fields are corrected.

Appendix A: Normative artifacts

SHA-256 values are of the files as released.

Validation fingerprint. The SHA-256 of the canonical JSON (E-2) of a schema after removing every title, description and $comment member that is in schema position. Members of properties, $defs, patternProperties and dependentSchemas are names, not keywords, and are kept (so the 1.0 and 1.1 property named title stays in the fingerprint).

Appendix B: Reference tools

The reference tools ship as one kit, mrk-tools.zip, served at /downloads/mrk-tools.zip. The old URL /downloads/mrk-ladder-scorer.zip redirects to it. Commands, run from the unzipped directory:

python -m mrk ladder   [--graph-first] [--evidence FILE ...] [--spec DIR] [--json] PATHS...
python -m mrk conform  [--consumer MODULE:CLASS] [--corpus PATHS...] [--self-test] [--evidence-out FILE]
python -m mrk drift    PATHS.md...
python -m mrk project  build|demo PATHS...
python -m mrk verify-evidence FILE [--corpus PATHS...]
python ladder.py ...   # same as: python -m mrk ladder ...

The kit is a reference implementation. Conformance is defined by this document, not by the kit.

• T-1 The kit MUST bundle mrk-1.0.schema.json, mrk-1.1.schema.json, mrk-1.1.context.jsonld, shapes.ttl, answer-object.schema.json and mrk-evidence.schema.json, each byte-identical to its served copy.
• T-2 Every served copy of a normative artifact MUST be byte-identical to its authority in Appendix A.
• T-3 The kit's requirements.txt MUST pin the full transitive dependency set with hashes, so that pip install --require-hashes -r requirements.txt succeeds.
• T-4 python ladder.py ARGS MUST behave identically to python -m mrk ladder ARGS.

Appendix C: Conformance-test mapping

One row per requirement. Check names the test: a schema keyword (schema:), a SHACL shape (shacl:), a conformance-suite case (suite:), a drift-lint rule (drift:), a scorer rule (ladder:), an evidence-verifier step (verify:), a pre-upload gate check (gate:), or a repository test written for the requirement (test:). Where is the current implementation and the tests that exercise it; a test is named file::function, and the tests written for this appendix are in tests/test_appendix_c.py, named after the requirement they check (test_A_6_...). Status: exists (the check is in code and tests this requirement), partial (in code but incomplete, as noted and explained in Appendix E), missing (to be built), attested (cannot be machine-checked; the evidence is named in the requirement).

Current files: scorer = tools/mrk-tools/mrk/ladder.py; drift = tools/mrk-tools/mrk/drift.py; harness = tools/mrk-tools/mrk/conform.py; consumer = tools/mrk-tools/mrk/consumer.py; gate = tools/validate-machine-blocks.py. Suite case ids map to the current harness case names: public-starter (Starter / public / en), enterprise, internal, locale-de, r5-depends (graph completes the answer), self-test.

Appendix D: Resolved inconsistencies

Where the design documents disagreed with each other or with the code, this specification follows the Gate B decisions (B1 maturity layer, B2 one kit, B3 corpus-bound evidence).

1. Instance version "2.0". Pages describe "MRK-2.0 at L4"; the 1.1 schema's mrk_version enum is ["1.0", "1.1"], so a "2.0" instance would score L0 in the shipped scorer. Resolved: MRK-2.0 is a standard version only; no new mrk_version (V-1-1); values "2" and up reserved (V-4-3).
2. Online scorer vs offline tools. The packaged scorer fetches spec files from the site by default. Resolved: no network at run time (S-1); files bundled or --spec (T-1).
3. Two ladder implementations. The prototype mrk-2.0/ladder.py holds the whole corpus at L3 on any SHACL failure and treats pyshacl as optional; the packaged scorer attributes violations per article and requires pyshacl. Resolved: the packaged behaviour is normative (I-8, P-L4-5).
4. Drift and L4. reuse-transclusion.md puts drift-lint in the L4 gate; neither scorer runs it. Resolved: drift is part of L4's mechanical half for .md articles (P-L4-2).
5. L4 operational half. It was a bare flag. Resolved: measured by corpus-bound evidence or attested by flag, with the basis always reported (P-L4-3, P-L4-4, K-2).
6. Per-corpus or per-article L4 evidence (ladder open question 3). Resolved: one run per corpus; acceptance per article by digest membership (P-L4-3, E-3).
7. "No dangling relTarget". The ladder text says SHACL rejects dangling relTarget; the projection expands relations so relTarget never appears, and the shapes check only requires, dependsOn and replaces. Resolved: those three are mandatory (I-4 to I-6); other relation types are expected to resolve, with shapes to be added (I-7).
8. Stable ids as an L1 criterion. The ladder table lists stable ids as part of L1, but no single snapshot can show stability. Resolved: attested from revision history (A-5); not a scored criterion.
9. L1 labelled "MRK-1.0 bar". L1 is checked against the 1.1 schema, which drops plan/region. Resolved: L1 is not MRK-1.0 conformance (K-7); the label changes. The reference tool labels L1 "contracted".
10. Recognised types. The 1.1 schema description says concept and reference gain section-shape rules; the schema has rules only for issue-resolution and task. Resolved: only those two have shapes (P-L2-2); the description is corrected editorially at release (V-6-1).
11. Type shapes vs mrk_version. The schema enforces type shapes only under mrk_version: "1.1"; the scorer applies them always. Resolved: both stand. Schema validity is gated by version (V-4-2); the L2 criterion is not (P-L2-2).
12. C1 scope. The harness prints "C1 (R1-R4, R6, R7)"; retrieval-conformance.md defines C1 as R1-R4 and R6. Resolved: R7 belongs to C2 (§10).
13. C1-only consumers. Parity cases call answer_graph unconditionally, so a consumer without a graph path crashes. Resolved: C1 is graded on answer() alone (C-L-1).
14. R6 "article version". No article version field exists; the reference consumer cites mrk_version. Resolved without a new field: version is the article digest or null, never mrk_version (C-R6-3).
15. Graph-path citation flags. answer_graph omits stale/superseded. Resolved: C-R6-4.
16. Hard-coded date. The reference consumer fixes TODAY = 2026-09-18. Resolved: the reference date is an input (C-R2-4) and recorded in evidence (E-7).
17. Absent locale. The reference consumer silently treats an absent locale as en. Resolved: the consumer declares its default (C-R3-4).
18. Unevaluated dimensions. The reference consumer ignores version* and dimensions, so such articles match every reader. Resolved: the reference consumer compares version* (dotted numeric segments; anything else by exact string) and dimensions (per key) with the reader context, and fails closed (C-R1-3) where the context does not answer or the values cannot be compared.
19. Retired articles. MRK-1.0 §4 says consumers "may" refuse retired articles; R2 says they must not serve them. Resolved: R2 governs consumers claiming C1 or C2 (C-R2-1); MRK-1.0 had no consumer conformance.
20. Superseded articles (§R open question 3). Resolved: refuse retired and expired; downweight and flag superseded (C-R2-1, C-R2-3).
21. Freshness in the ladder (ladder open question 1). Resolved: separate from rung (P-G-4).
22. Partial L2 (ladder open question 2). Resolved: all-or-nothing, with the next-rung gap reported (P-G-2, P-G-3).
23. Scope of the 1.0 → 1.1 theorem. Both schemas are open, so a valid 1.0 instance can carry a property that 1.1 later defined (for example profile: custom) and fail 1.1. Resolved: tools accept instances under their own format version's schema (V-2-1); such an article scores L0 with the schema message as its gap; V-4-1 states additivity for instances that do not use new names.
24. Unknown mrk_version routing. validate-machine-blocks.py validates any non-"1.1" value against 1.0. Resolved: unknown values fail (V-5-1).
25. Fingerprint definition. The Gate B memo strips every title/description/$comment recursively, which would also delete the schema of the article property named title. Resolved: annotation keywords are stripped only in schema position (Appendix A).
26. YAML dates. The scorer validates raw yaml.safe_load output, so an unquoted verified: 2026-07-30, as shown on the MRK-1.0 page, loads as a date and fails type: string; the scorer also does not assert format: date. The repository's own samples quote dates to avoid this. Resolved: A-8.
27. Section id ownership. Nothing checks that a section id's prefix is its article's id, though citations and the projection depend on it. Resolved: A-6 and P-L1-5.
28. requires in graph retrieval. requires counts as an L3 edge, but the reference consumer follows only depends_on. Resolved: C2 follows both (C-R5-4); derived cases cover both (E-6).
29. Transclusion direction (reuse open question 3). Resolved: the marker's target is canonical; self-targets are forbidden (D-5). Cycles stay open (Appendix E).
30. Marker syntax and metric (reuse open questions 1 and 2). Resolved: HTML comment markers (D-1) and the lexical grounding score at 0.5 (D-6); no embedding model.
31. Namespace and /kb/ IRIs. The context's @base gives every adopter's articles IRIs under machinereadyknowledge.com/kb/, and /ns is not served today. Resolved: IRIs are identifiers only and not dereferenced (N-3); /ns must be served (N-2).
32. Stale status lines. graduation-ladder.md, retrieval-conformance.md, reuse-transclusion.md, conformance/README.md and mrk-1.1/CHANGES.md say "DRAFT" or "Nothing here is served" for content that #60 serves. Resolved: this document is the authority; those files carry a "rationale, superseded by SPEC.md" status line (changed at release).

Appendix E: Open issues

1. Transclusion cycles (A copies from B, B copies from A). The drift gate tolerates them because canonical text excludes transcluded blocks; whether to forbid them is open.
2. Evidence is unsigned. A signing scheme would need key distribution, which conflicts with offline use.
3. An answer-envelope schema (the whole answer, not each citation).
4. Further r5_contract shapes: supersedes pruning and trust-tiered selection.
5. MRK-2.1 may require a measured L4 basis. MRK-2.0 keeps attestation so that existing results do not change.
6. The recognised type set (howto, faq, policy) and provenance.confidence as an enum or a number, carried over from MRK-1.1.
7. Known limitation: the reference tool's CI runs on macOS arm64 with Python 3.12 and 3.14 only. The pytest job installs the hash-locked tests/requirements.txt (--require-hashes) and the unzip-and-install step installs the kit's lock the same way. Linux, Windows and Python 3.13 are not run in CI. What is checked for them is the dependency locks: tests/test_locks.py evaluates the metadata of every locked package for Windows, Linux and macOS under Python 3.12 and 3.14 and fails if a dependency active there is not locked. That check found one gap, now closed: pytest needs colorama on Windows only, so pip-compile run on macOS leaves it out; it is pinned by hand, with a sys_platform == "win32" marker and its hashes, in tests/requirements.txt. This shows the locks are complete, not that the tool runs on those platforms.
8. Known limitation (N-2): the live route https://machinereadyknowledge.com/ns cannot be tested from the repository. The test reads the .htaccess negotiation rules and checks that the files they name are served byte-identical to docs/; after an upload, request /ns with each Accept header to confirm the route (DEPLOY.md describes the rules).
9. I-7 is a SHOULD and the 2.0 shapes do not check the targets of prerequisite_of, references, part_of, see_also and applies_with; a dangling one does not block L4. Whether a later edition should add shapes, which would make a dangling optional edge an L4 blocker, is open.