# llms-understanding.txt — MX as proposed for ratification

> **What MX is for.** Make anything you publish — a video, a podcast, a PDF, an image, a web page — readable by machines. The drafts in this bundle are the open-standard specifications that define how.
>
> **What kind of layer MX is.** MX is the DNA a file carries when it leaves any pool. A memory-pool architecture (an LLM-wiki, a vector store, a knowledge base, a CMS, a training corpus) organises knowledge inside one system; MX governs what survives extraction, so the next reader can interpret the file without inference. The two boundary notes at the end of this bundle (`MX is not GEO` and `MX is not a memory-pool architecture`) draw the boundary explicitly.

> A single-file, plain-markdown corpus of every public MX draft note offered to The Gathering for community review. Read this file end-to-end to acquire a complete working understanding of the Machine Experience vocabulary, its conformance levels, the carrier formats it travels in, the optional cogs/signing layers, the temporal-stance vocabulary for documents anchored to dated events, and the discoverability and accessibility standards it inherits from existing W3C, ISO, and IETF specifications.

## What this file is

`llms-understanding.txt` is a knowledge bundle for AI agents, search engines, and human reviewers who want the entire MX proposal in one place without crawling page-by-page. It contains every draft note from the public mx-shared-gathering repository (https://github.com/ddttom/mx-shared-gathering), in the recommended reading order, with each draft prefixed by its canonical URL.

The drafts are **not ratified standards**. They are proposals authored by Tom Cranstoun and offered to The Gathering (https://tg.community) community for review via Stream (https://stream.tg.community). Each draft is standalone and refers only to existing published external standards (RFC, ISO, W3C, NIST, Schema.org, Dublin Core, SPDX) for normative content. Where one draft excludes a topic owned by a sister draft, it names the sister draft for orientation; no draft depends on another for normative material — except that every sister note adheres to the field-definition discipline laid down in the primary `MX Field Definition Pattern note`.

## How to read this file

The recommended order is the order of sections below.

1. **MX Field Definition Pattern note** — the primary note. Defines the authoring discipline every sister note follows when specifying a frontmatter field. Read it first.
2. **MX Core Metadata note** — Zone 1 / Zone 2 document metadata and externally-aligned fields. The vocabulary floor that any text-bearing artefact can adopt. Reading this together with MX Provenance gives an author the full Level-2 floor.
3. **MX Cogs note** — the optional `.cog.md` file format as a layer on top of MX, for documents that need to be navigable, composable, and runnable by agents. Most MX-aware documents will not be cogs. Cogs are graded on a Tier A / B / C ladder distinct from the MX Core Level 1/2/3 ladder; a cog is graded by both at once.
4. **MX Extensions note** — namespace policy (standard / vendor-public / vendor-private prefixes) so vendors can extend MX without polluting the core vocabulary. The public extension namespace is operated by CogNovaMX during the seed phase; vendor sub-namespaces of the form `x-mx-{vendor}-*` are reserved for individual vendors.
5. **MX Provenance note** — attribution, trust, maintenance, and decision-record references. The metadata that makes a document's origin and stewardship verifiable. Part of the Level-2 floor for documents that need verifiable origin.
6. **MX Temporal Stance note** — temporal vocabulary for documents whose prose depends on dated anchors. Regulatory analyses, contracts, SLAs, compliance reports, pricing pages — anything that has to read correctly today and again later when the anchors move. Time-neutral documents can skip this note.
7. **MX Carrier Formats note** — how MX metadata is carried in each supported file format (markdown, HTML, JSDoc, CSS, shell, XMP, sidecar, SQL), plus a small code-specific provenance vocabulary. Behaviour-level code metadata defers to JSDoc, docstrings, OpenAPI. Carries the binding HTML mapping for the four MUST-at-Level-2 web fields.
8. **MX Workflow Contracts note** — optional top-level fields for cogs that declare an executable approval, review, or procedural workflow.
9. **MX Agent Directory Discovery note** — three-layer discoverability standard for `llms.txt` and any agent-directory file: HTML transport, sitemap inclusion, in-page `<link>`.
10. **MX Document Accessibility note** — three-layer accessibility standard for non-HTML document carriers: tagged structure, declared conformance, independent verification. PDF normative; DOCX and EPUB informative. Defers to ISO 14289 PDF/UA, ISO 32000, WCAG 2.1, BCP 47, Schema.org accessibility properties, Directive (EU) 2019/882 (EAA).
11. **MX Contract Fingerprinting and Signing note** — the contract a cog satisfies *when it elects to be signed*. Signing is optional. The fingerprint format is open. The contract surface is derivable from a `schema:` annotation; the explicit `contractFields` array is the override.
12. **MX scope note: machine-readable documents beyond web optimisation** *(boundary note)* — the boundary between MX governance and Generative Engine Optimisation (GEO/AEO). MX builds coverage across an unknowable landscape of machines and formats; GEO targets one pathway and accepts failure on the others. Read when you need to explain what MX is *not* doing in a GEO conversation.
13. **MX scope note: file-borne provenance beyond memory-pool architectures** *(boundary note)* — the boundary between MX governance and memory-pool architectures (LLM-wikis, Karpathy-style compiled knowledge bases, Obsidian vaults, vector stores). A memory pool governs how knowledge is organised inside one system; MX governs the DNA a file carries when it leaves any system. The two are complementary, not competitors. Read when MX is being conflated with an in-system retrieval design.

## Provenance of this bundle

**Generated:** 2026-07-03
**Source repository:** https://github.com/ddttom/mx-shared-gathering
**Canonical home for each draft:** https://github.com/ddttom/mx-shared-gathering/blob/main/<filename>
**Licence:** MIT. The MX vocabulary is free, open, and vendor-neutral.
**Format convention:** llms-full.txt — popularised by Fern and Mintlify; compatible with the llms-ctx-full.txt pattern at llmstxt.org.

---

## MX Field Definition Pattern note (primary)

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-field-pattern.md
**File:** `draft-field-pattern.md`

# MX Field Definition Pattern note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review — **primary note of the MX draft set**
**Date:** 27 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This is the **primary note** of the MX draft set. Every other note in the set defines one or more frontmatter fields, and every one of those fields is described under the pattern this note specifies. Readers new to the suite should read this note first; sister notes assume its rules and do not restate them.

Without a shared pattern, each note would express the same structural choices in slightly different prose: a heading, a property table, a definition, an example, and (sometimes) extra rules. Even minor variations make automated extraction harder than it needs to be, and they make a reviewer ask "is this field defined the same way as the last one?" every time.

This note specifies a single, vetted **pattern** for defining a frontmatter field inside any MX draft. Drafts add new fields by following the template — author once, machine-read everywhere.

**Why field discipline matters.** Machine consumers — agents, validators, registries, signers, graph builders — cannot infer intent from prose. They need fields that are explicit, tightly typed, and constrained to a small set of legal values. The MX vocabulary is therefore expected to **grow, not shrink**: new fields are how machines come to understand what a document means. Field growth without authoring discipline produces drift, and drift compounds: every loose definition multiplies the work of every downstream consumer that has to reconcile it. The pattern in this note exists to absorb growth without producing drift, and to keep every new field tightly constrained from the moment it is defined.

This note specifies the pattern itself. **No new frontmatter fields are introduced in this note.** It governs *how* a field is defined; *which* fields exist is the work of the sister notes that define them.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

This note's pattern is **normative for the entire MX draft set**. Every MX note that defines one or more frontmatter fields MUST define each field using the structure in §4, the property-table rows in §5 (for standard fields), or the inventory-table form in §4.4 (for pass-through fields). Sister notes MUST NOT introduce alternative shapes, additional property-table rows, or supplementary section types beyond those defined here.

A note that defines no fields makes no claim against this pattern and is unaffected by it.

### 2.1 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the structural rules below are working drafts — stable enough to author against, expected to evolve through review.

---

## 3. Scope

### 3.1 In scope

- The structural template for a **standard field** definition inside an MX draft.
- The structural template for **pass-through fields** — fields whose value semantics are owned by an external vocabulary (Dublin Core, Schema.org, BCP 47, SPDX, FOAF, ...).
- The required and optional rows of the property table.
- Naming and ordering conventions for field-definition headings and sub-sections.
- One worked example showing the pattern applied.

### 3.2 Out of scope

- **Specific field semantics.** What `title`, `provenanceAuthor`, `x-mx-thresholds`, or any other field *means* belongs in the relevant note. This note does not define any field.
- **Profile catalogues.** Which fields apply to which document type (`core`, `cog`, `report`, ...) is governed by the notes that own those profiles.
- **Schema languages.** JSON Schema, YAML schema, Schema.org, and similar machine-readable shape languages are unrelated; this note specifies authored-prose shape only.
- **Carrier-format mappings.** How a field is expressed in HTML, JSDoc, CSS, etc. is governed by the MX Carrier Formats note.
- **Conformance-level definitions.** What "Level 1 / 2 / 3" mean within a particular note is the host note's choice; this pattern only requires that one of those levels be cited.

### 3.3 Relationship to existing standards

This note follows the [IETF RFC format](https://www.rfc-editor.org/rfc/rfc7322) for standards-document authoring and uses the [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) keyword vocabulary. The pattern itself is a stylistic convention layered on top of those, not a redefinition of either.

### 3.4 Recommended reading order across the draft set

Each sister note is self-contained and may be read in any order. For a newcomer to the draft set, the following sequence orients the vocabulary from the floor upwards before reaching the optional layers:

1. **MX Field Definition Pattern note** *(this note)* — the authoring pattern every other note follows when defining a frontmatter field. Read first.
2. **MX Core Metadata note** — the floor. Document-identity and operational fields every MX-aware artefact declares (`title`, `author`, `created`, `description`, `status`, `contentType`, ...) plus the pass-through inventory.
3. **MX Provenance note** — extends the floor with attribution, trust, maintenance, and decision-record references — the metadata that makes a document's origin and stewardship verifiable.
4. **MX Extensions note** — namespace policy: how vendors extend the vocabulary (`x-mx-`, `x-mx-p-`) without polluting the core, plus context-specific naming across syntactic carriers.
5. **MX Carrier Formats note** — how MX metadata is carried across markdown, HTML, JSDoc, CSS, shell, EXIF/XMP, sidecar, and SQL carriers, plus a small code-specific provenance vocabulary.
6. **MX Cogs note** — the optional `.cog.md` layer for documents that want to be navigable, composable, and runnable by agents.
7. **MX Workflow Contracts note** — top-level fields for cogs that declare an executable approval, review, or procedural workflow.
8. **MX Contract Fingerprinting and Signing note** — the signing format a cog uses *when it elects to be signed*. Signing is optional.

The order moves from authoring discipline (this note) to the universal floor, then enriches the floor (provenance, extensions), maps it onto carriers (carrier formats), and finally reaches the optional cog layer and its three specialisations. A reader interested only in a specific topic — say, signing a contract cog — can jump directly to the relevant note; the listed prerequisites are recommendations, not normative dependencies.

---

## 4. The field-definition pattern

A field definition is a contiguous unit inside a host note. It has four required pieces, in order, plus optional supplementary material.

### 4.1 Required pieces

1. **Heading.** A section heading at the level appropriate to the host note's structure (typically `### N.M`), with the field name in backticks. Example: `### 5.3` `` `author` ``. Headings MUST contain only the bare field name; no prose, no qualifiers, no parenthetical types.
2. **Property table.** A two-column markdown table with the rows specified in §5, in the order given.
3. **Definition prose.** One or more paragraphs of plain prose that name what the field is, what it carries, and any constraint not expressible in the property table. Definition prose MUST come immediately after the property table. Definition prose MUST NOT restate values already given in the table.
4. **Example.** A fenced YAML code block showing the field in use, in the carrier the host note targets (typically `mx:` block or top-level frontmatter). Examples MUST be syntactically valid YAML and MUST illustrate the field's actual shape. A definition with multiple legal shapes (e.g. `string-or-object`) MAY include multiple example blocks.

### 4.2 Optional supplementary material

After the required pieces, a definition MAY include any of:

- **Bulleted constraints** — additional rules expressible as short bullets (e.g. "the value MUST be quoted in YAML to prevent numeric coercion").
- **Cross-reference** — a one-line pointer to a related field elsewhere in the same note (e.g. "Distinct from `maintainer` (§6.6)"). Cross-references to *other notes* MUST be by note name only, never by file path or URL, per the standalone-ness rule of the draft set.
- **Sub-table** — a further markdown table when the field's value is an object with named sub-keys (e.g. `cogHeader` with `version`, `spec`, `runtime`, `runtimeDoc`).

A definition MUST NOT include a "Normative notes" preamble whose body merely paraphrases the property table or the definition prose. If a putative note adds no new constraint, it is removed.

### 4.3 Group rules

When two or more fields share the same shape and conformance, a note MAY collapse them into a single section that lists the fields together, presents one shared property table, and explains the differences in a small differentiation table. The host note SHOULD use this form whenever the result is shorter than separate sections without loss of normative content.

A group section follows the same Required-pieces order as a single field, with the heading naming the group (e.g. "Decision record references: `adr`, `ndr`, `bdr`") instead of a single field.

### 4.4 Pass-through field pattern

A **pass-through field** is a YAML key whose value semantics belong to an established external vocabulary (Dublin Core, Schema.org, BCP 47, SPDX, FOAF, and similar). MX names the key so that authors do not have to switch syntax mid-frontmatter; the external standard owns the meaning.

Pass-through fields use a different shape from §4.1, because the host note is not the owner of the value. Instead of one full section per field, a host note groups pass-through fields into a single **inventory table** with these columns, in this order:

| Column | Required | Value |
|--------|:--------:|-------|
| **Field** | yes | The YAML key MX provides, in backticks. |
| **Aligns with** | yes | The external standard's canonical name plus the specific term, e.g. `Dublin Core dc:date, Schema.org Date`. The standard MUST be cited precisely (URL plus the specific field/property name) at least once in the note. |
| **Value** | yes | One sentence summarising what the value carries. |
| **Conformance** | yes | Always `MAY` for pass-through fields — they are optional surface for an external vocabulary. |

A pass-through inventory table appears in a dedicated pass-through section of the host note. The section MUST also state, in prose:

- That the listed fields are pass-through (definition above).
- That MX does not redefine or contradict the cited external standard.
- The rule for adding a new pass-through field: an established external vocabulary cleanly covers the value, the alignment is declared via canon's `alignsWith:`, and MX names the YAML key without governing its semantics. If the external standard does not cleanly cover the value, the field is **not** a pass-through and MUST be defined under the standard pattern in §4.1.

Pass-through fields MUST NOT use the property table in §5; the inventory table replaces it. A field definition that mixes the two forms is a conformance failure.

The MX Core Metadata note's pass-through inventory is the reference precedent. Sister notes that introduce additional pass-through fields (e.g. linguistic, rights, dataset metadata) MUST follow this same inventory-table form.

---

## 5. The property table

The property table is the standard-field shape. It immediately follows the heading and uses two columns — `Property` and `Value` — containing the rows below in this exact order. Rows that do not apply MUST be omitted entirely; rows that do apply MUST appear in the order given. Pass-through fields use the inventory-table form in §4.4 and do not use this property table.

| Row | When | Value |
|-----|------|-------|
| **Type** | always | One of: `string`, `boolean`, `number`, `array`, `object`, `array of <type>`, `string-or-object`, `string-or-array`, `string-or-boolean`. New compound types MUST be hyphenated and in lowercase. |
| **Zone** | always for fields that live in YAML frontmatter | `1 (top-level)` or `2 (mx:)`. Fields that have no zone (e.g. parameters of a sub-key) omit this row. |
| **Profile** | when the field is profile-restricted | A comma-separated list of profile names (`core`, `cog`, `report`, `migration`, `x-mx-public`, ...). Omitted when the field is universal. |
| **Conformance** | always | An [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) keyword (`MUST`, `SHOULD`, `MAY`) plus the host note's level in parentheses. Example: `MUST (Level 1)`. Multiple conformance entries MAY appear when the level depends on context, separated by semicolons. |
| **Valid values** | when the value is enumerated | A comma-separated list of permitted values, in lowercase, exactly as they appear in YAML. |
| **Default** | when omitting the field has a defined behaviour | The default value, or `*(none)*` when there is no default. Use `*(none — explicit declaration required)*` for MUST-level fields. |

The table MUST NOT contain rows beyond these. New rows MAY be proposed only by amending this note, not by individual field definitions.

---

## 6. Worked example

The following is a complete, conforming definition of a hypothetical field `riskLevel`. It is not a real field; it exists only to illustrate the pattern.

> ### 7.4 `riskLevel`
>
> | Property | Value |
> |----------|-------|
> | **Type** | string |
> | **Zone** | 2 (mx:) |
> | **Conformance** | MAY (Level 3) |
> | **Valid values** | low, medium, high, critical |
> | **Default** | *(none)* |
>
> Self-declared risk classification of the document's subject matter. Helps agents and maintainers prioritise review attention when a queue is large.
>
> ```yaml
> mx:
>   riskLevel: medium
> ```
>
> - `critical` SHOULD be reserved for content whose factual error could cause material harm; lighter classifications cover everyday content.
> - Distinct from `confidential`, which controls publication, not review urgency.

The example shows: a heading containing only the bare field name; the four required property rows in order; the two optional rows (`Valid values`, `Default`) where they apply; one paragraph of definition prose that does not restate the table; one YAML example block; and two bulleted constraints — one introducing a new rule, one cross-referencing a sibling field. No "Normative notes" preamble is used.

---

## 7. Authoring rules

These rules are normative for any field defined under this pattern.

### 7.1 Naming

Field names use camelCase in YAML contexts (matching the [Schema.org Style Guide](https://schema.org/docs/styleguide.html)). Vendor-extension fields use kebab-case after their prefix (`x-mx-deploy-target`, not `x-mx-deployTarget`). Field names MUST NOT use snake_case or PascalCase in YAML contexts.

### 7.2 Conformance keywords

Each definition cites exactly one of `MUST`, `SHOULD`, or `MAY` as its primary conformance keyword. When the level is conditional ("MUST when X applies, MAY otherwise"), the conditions MUST be explicit in the Conformance row, semicolon-separated.

### 7.3 Length

A typical single-field definition is 8–25 lines. Definitions that exceed roughly 40 lines SHOULD be reviewed for unnecessary prose, restated rules, or material that belongs in a sibling note.

### 7.4 What not to include

A field definition MUST NOT contain:

- Marketing language or assertions of importance ("this critical field", "the most useful").
- Implementation detail (which library reads it, which database column it maps to).
- Forward-looking statements ("we plan to extend this to ...").
- Examples that duplicate a previous example without adding new shape.
- Cross-references to draft files by path or URL.

### 7.5 Worked-example status

The example in §6 is illustrative, not normative. Implementations MUST NOT treat `riskLevel` as a registered field on the basis of this note alone.

---

## 8. Security and privacy considerations

This note specifies authoring style only and introduces no new fields, no carriers, and no signing surface. It carries no direct security or privacy implications.

A second-order consideration: a uniform field-definition pattern makes automated extraction tractable, which means tooling can mechanically enumerate every field a draft defines. Authors SHOULD assume that anything written inside a property table or YAML example will be parsed by tools that treat the draft as canonical, and SHOULD NOT include sensitive sample values in examples.

---

## 9. References

### 9.1 Normative references

- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) — Key words for use in RFCs to indicate requirement levels

### 9.2 Informative references

- [RFC 7322](https://www.rfc-editor.org/rfc/rfc7322) — RFC Style Guide (style precedent for standards-document authoring)
- [Schema.org Style Guide](https://schema.org/docs/styleguide.html) — Vocabulary naming conventions

---

*End of MX Field Definition Pattern note draft.*

---

## MX Core Metadata note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-core-metadata.md
**File:** `draft-core-metadata.md`

# MX Core Metadata note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 27 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note defines the core machine-readable document-metadata vocabulary for the Machine Experience (MX) framework. It specifies the foundational fields that every MX-aware document — whether a markdown file, an HTML page, a YAML sidecar, or any other text-bearing artefact — must, should, or may declare.

The core vocabulary is organised into three zones and one supplementary group. **Zone 1a identity fields** (top-level document identity: title, description, author, dates, version) are required on every MX document. **Zone 1b OKF-reserved surface fields** (top-level: type, tags, and resource when applicable) are required on every MX document. MX is an OKF implementation; Zone 1b fields are present unconditionally so that any OKF-compliant tool reads an MX document without adaptation. **Zone 2 operational fields** (governance, classification, and distribution metadata under the `mx:` namespace) carry everything OKF does not define; an OKF consumer preserves the entire `mx:` block as one unknown key. **Externally-aligned fields** are YAML keys whose semantics are owned by, or modelled after, established external vocabularies — Dublin Core, Schema.org, BCP 47, SPDX, RFC 3986. The relationship between MX and each external standard is recorded explicitly per field; see §7.

The cog file format is **not** described here. Cogs are an optional layer on top of MX, covered by the MX Cogs note in the same draft set. A document can carry MX metadata without ever being a cog.

**Accessibility (Normative).** An MX-compliant document MUST itself be accessible. For HTML, EPUB, and other web-style carriers, the artefact MUST conform to [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level AA. For PDF, the artefact MUST be tagged for accessibility with at least the conformance level cited in the MX Document Accessibility note. For markdown and other plain-text carriers, the structural conventions covered by the MX Document Accessibility note (heading hierarchy, alt text on images, descriptive link text, plain-language summaries) apply. MX adds machine-readable governance on top of standards-conformant content; it does not replace or relax the underlying accessibility requirement.

**Provenance.** Authorship, stewardship, derivation, and review history are governed by the **MX Provenance note**. That note extends this floor with the attribution and trust fields that make a document's origin verifiable. It is part of the recommended reading order for any author writing for an MX-aware audience.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of this draft set). That pattern governs the structural template for every field — heading, property table, definition prose, example — and the inventory-table form used for the externally-aligned fields in §7. This note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

| Level | Name | Requirement | Description |
|-------|------|-------------|-------------|
| Level 1 | **MX Core** | All MUST fields present and valid | Minimum viable MX metadata. A document at Level 1 is machine-identifiable and attributable. |
| Level 2 | **MX Standard** | All MUST and SHOULD fields present | Recommended for production use. A document at Level 2 is fully classified and lifecycle-managed. |
| Level 3 | **MX Complete** | All MUST, SHOULD, and applicable MAY fields present | Full metadata coverage. |

A document claiming conformance at a given level MUST satisfy all requirements at that level and all lower levels.

### 2.2 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the field definitions, conformance requirements, and normative rules in this note are working drafts — stable enough to build against, expected to evolve through review.

---

## 3. Scope

### 3.1 In scope

- **Zone 1a identity fields** — top-level document identity (title, description, author, dates, version)
- **Zone 1b OKF-reserved surface fields** — top-level fields present on every MX document. MX is an OKF implementation; these fields are required unconditionally so any OKF-compliant tool reads MX files without adaptation: `type` (MUST, carries MX content-type vocabulary), `tags` (MUST, for discovery), `resource` (MUST when the document describes a specific external asset; absent for abstract concepts)
- **Zone 2 core operational fields** — classification, governance, and distribution metadata
- **Externally-aligned fields** — fields where MX provides a YAML key whose value semantics are owned by, or modelled after, an established external vocabulary (§7)
- **The conformance level framework** — Level 1/2/3 definitions

### 3.2 Out of scope

- The cog file format (an optional layer over MX). A separate note covers cogs.
- Any signing or fingerprint contract a document might choose to carry.
- Carrier-format mappings (how the same field is expressed in HTML meta tags, JSDoc, CSS comments, etc.).

### 3.3 Relationship to existing standards

All field names in this note use camelCase, follow spelling-neutral forms (e.g. `license`, not `licence`, when an SPDX-aligned identifier is required), and use ISO 8601 date format (YYYY-MM-DD) for all date fields:

- **ISO 8601** — date and time format
- **SPDX License List** — licence identifiers follow the SPDX standard
- **Schema.org Style Guide** — vocabulary naming conventions (camelCase, lowercase first character)
- **Dublin Core DCMI Namespace** — namespace governance model

---

## 4. The three-zone frontmatter model

MX metadata in YAML frontmatter is organised into three zones.

**Zone 1a** (top-level) carries document identity fields: `title`, `description`, `author`, `created`, `modified`, `version`. These are required on every MX document.

**Zone 1b** (top-level) carries the OKF-reserved surface: `type` (required), `tags` (required), and `resource` (required when the document describes a specific external asset; absent for abstract concepts). MX is an OKF implementation. These fields are present unconditionally so that any external tooling built to read OKF files reads an MX document without adaptation. `type` carries the content-type vocabulary. `tags` carries discovery keywords. `resource` carries the singular URI of the external asset the document describes — distinct from `mx.refersToExternal` (plural citations). An OKF consumer reading an MX file treats the entire `mx:` block as one unknown preserved key, which is OKF-conformant. One field, one zone, no duplicate. The OKF `timestamp` field is satisfied by `modified` and derived at export time; it is never stored in source frontmatter.

**Zone 2** (under the `mx:` object) carries everything OKF does not define: lifecycle fields (`status`, `stability`), governance fields (`canonicalUri`, `license`, `audience`), the typed relation graph (`buildsOn`, `refersTo`, `relatedTo`, `refersToExternal`), and all MX extensions. An OKF consumer preserves the entire `mx:` object as one unknown key; it neither reads nor rejects it.

**Externally-aligned fields** are YAML keys whose value semantics are owned by, or modelled after, an established external vocabulary; the inventory and the alignment relationships are in §7, and the fields otherwise behave as Zone 1a, Zone 1b, or Zone 2 depending on which zone the field declaration places them in.

**Three-zone example:**

```yaml
---
# Zone 1a — identity
title: "Document Title"
description: "Brief summary for search engines and machines"
author: "Author Name"
created: 2026-04-02
modified: 2026-04-16
version: "1.0"

# Zone 1b — OKF reserved surface
type: guide
tags: [metadata, example]

# Zone 2 — MX operational
mx:
  status: active
  audience: [humans]
  canonicalUri: https://example.com/docs/title
---
```

**Dual-conformance:** the same frontmatter block is simultaneously valid OKF (because `type`, `title`, `description`, `tags` are at the top level where OKF looks for them) and full MX (because the `mx:` block carries everything OKF does not define, and OKF preserves it as one unknown key).

Implementations MUST NOT place Zone 1a or Zone 1b fields inside the `mx:` object. Implementations MUST NOT place Zone 2 fields at the top level. No fact may be carried under two field names.

**OKF field alignment reference:** Open Knowledge Format v0.1, [GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md). The load-bearing rule: `Producers MAY include any additional keys. Consumers SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject documents with unrecognized fields.`

---

## 5. Zone 1a identity fields

### 5.1 `title`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1 (top-level) |
| **Conformance** | MUST (Level 1) |

Human-readable document title. The canonical identity field for all documents.

```yaml
title: "MX Core Metadata note"
```

If both `title` in frontmatter and an H1 heading exist in the document body, authors SHOULD avoid duplication by omitting `title` from frontmatter and relying on the H1 heading, or vice versa.

---

### 5.2 `description`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1 (top-level) |
| **Conformance** | MUST (Level 1) |

One-line summary. Used by search engines, machines of every class, and registry listings. The value SHOULD NOT exceed 160 characters and MUST be a single sentence or phrase summarising the document's purpose.

```yaml
description: "Single source of truth for every YAML frontmatter field."
```

---

### 5.3 `originator`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1 (top-level) |
| **Conformance** | MUST (Level 1) |

Creator of the document. Person name or collaborative attribution. Identity, not stewardship — names who first wrote the document, not who currently looks after it.

```yaml
originator: "Tom Cranstoun"
```

- The `originator` field is immutable after creation. Implementations MUST NOT change this value after the document is first committed.
- For collaborative work, all contributors SHOULD be listed.
- `originator` is distinct from the `stewardship` object (§6.6). The originator is the original creator (immutable, Zone 1); stewardship covers ongoing maintenance, contact, and ownership (mutable, Zone 2).

**Alias.** Documents written before this rename used the field name `author`. Implementations MUST treat a top-level `author` field as an alias of `originator` and SHOULD copy the value across when migrating. The `author` alias is supported for one major version after this note ratifies, then retires per the field-deprecation lifecycle in the MX Extensions note §10.4.

---

### 5.4 `created`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1 (top-level) |
| **Conformance** | MUST (Level 1) |

Creation date in ISO 8601 format (YYYY-MM-DD). This field is immutable — once set, it MUST NOT be changed.

```yaml
created: 2026-04-02
```

---

### 5.5 `modified`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1 (top-level) |
| **Conformance** | MUST (Level 1) |

Last modification date in ISO 8601 format (YYYY-MM-DD). Implementations MUST update this field every time the document's content changes.

```yaml
modified: 2026-04-16
```

---

### 5.6 `version`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1 (top-level) |
| **Conformance** | SHOULD (Level 2) |

Semantic version string. The value MUST be quoted in YAML to prevent numeric coercion (e.g., `"1.0"` not `1.0`). Version numbers live in frontmatter, never in filenames.

```yaml
version: "2.0"
```

---

### 5.7 `schema`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1 (top-level) |
| **Conformance** | MAY (Level 3) |

Schema reference identifier — pointer to the schema document that defines and validates this document's contract. May be a Schema.org type URL, a JSON Schema `$id`, a relative path to a YAML/JSON schema file, or a database schema name.

```yaml
schema: ./schemas/invoice-approval.v1.yaml
```

- When present, validators SHOULD attempt to resolve the reference and apply the referenced schema before checking field-level conformance.
- The reference MAY be a relative path, an absolute path, a URL, or a registry-resolvable name.
- Implementations SHOULD treat unresolved references as a warning, not a failure, since the schema may live in an external system.

---

### 5.8 `validatesAgainst`

| Property | Value |
|----------|-------|
| **Type** | array of string |
| **Zone** | 1 (top-level) |
| **Conformance** | MAY (Level 3) |

Named validators (dotted notation) this document claims conformance to. A document MAY declare conformance to multiple validators (typically one meta-validator plus one or more domain validators).

```yaml
validatesAgainst:
  - cog.meta.v1
  - invoice-approval.v1
```

- Each entry SHOULD be a dotted name resolvable via the cog registry or via a `schema` pointer.
- Validators MUST treat the array as additive — a document conforming to `cog.meta.v1` AND `invoice-approval.v1` must satisfy both.
- Implementations SHOULD warn when a referenced validator name cannot be resolved; they MUST NOT silently skip validation.

---

## 5b. Zone 1b OKF-reserved surface fields

The three fields in this section sit at the top level of the YAML frontmatter block (Zone 1b). They are defined by the Open Knowledge Format (OKF) as the six reserved fields OKF consumers read first. MX adopts five of them directly and satisfies the sixth (`timestamp`) by derivation from `modified` at export time. The adopt-don't-reinvent rule applies: these are OKF fields MX carries, not MX synonyms. No equivalent field exists under the `mx:` namespace; placing them there is a conformance failure.

### 5b.1 `type`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1b (top-level, OKF-reserved) |
| **Conformance** | MUST (Level 1) |
| **OKF field** | `type` (required in OKF) |
| **Replaces** | `mx.contentType` (retiring synonym; see note) |

The kind of concept this document represents. Carries the MX content-type vocabulary at the top level so OKF consumers can route, filter, and present the document without reading the `mx:` block. Common values: `info-doc`, `action-doc`, `blog-post`, `specification`, `guide`, `report`, `field-dictionary`, `contact`, `direct-message`, `folder-metadata`.

```yaml
type: info-doc
```

**Retiring synonym:** `mx.contentType` is the pre-OKF location for this field. It is accepted during a migration window but MUST be promoted to top-level `type` for OKF conformance. After migration, `mx.contentType` is absent from conformant documents.

---

### 5b.2 `tags`

| Property | Value |
|----------|-------|
| **Type** | array of strings |
| **Zone** | 1b (top-level, OKF-reserved) |
| **Conformance** | MUST (Level 1) |
| **OKF field** | `tags` (optional in OKF) |
| **Replaces** | `mx.tags` (retiring synonym) |

Discovery keywords. Array of lowercase strings for search, filtering, and agent matching. Aligns with Schema.org `keywords`.

```yaml
tags: [metadata, yaml, frontmatter]
```

**Retiring synonym:** `mx.tags` is the pre-OKF location. Promote to top-level `tags` for conformance.

---

### 5b.3 `resource`

| Property | Value |
|----------|-------|
| **Type** | string (URI) |
| **Zone** | 1b (top-level, OKF-reserved) |
| **Conformance** | MUST when the document describes a specific external asset; absent for abstract concepts |
| **OKF field** | `resource` (optional in OKF) |

A URI that uniquely identifies the underlying external asset this document describes. Present only when the document describes a specific external object (a table, a dataset, an API endpoint). Absent for abstract concepts (playbooks, runbooks, policies). **Semantically distinct from `mx.refersToExternal`**: `resource` names the one thing this document is *about*; `refersToExternal` is the set of external sources the document *cites*.

```yaml
resource: https://bigquery.googleapis.com/v2/projects/bigquery-public-data/datasets/ga4_obfuscated
```

---

### 5b.4 `timestamp` (derived on export; not stored in source)

| Property | Value |
|----------|-------|
| **OKF field** | `timestamp` (optional in OKF) |
| **MX equivalent** | `modified` (Zone 1a) |
| **Storage rule** | MUST NOT be stored in source frontmatter |

OKF's optional `timestamp` field (ISO 8601 datetime of last meaningful change) is satisfied by `modified`. MX keeps the two-date model (`created` + `modified`) which is richer; `timestamp` is derived from `modified` at the export boundary when a pure-OKF view is needed. Storing both `modified` and a `timestamp` with the same value in source frontmatter violates the no-duplicates rule.

---

## 6. Zone 2 core operational fields

### 6.1 `status`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 2) |
| **Valid values** | draft, active, published, deprecated, archived, unknown, proposed, accepted, rejected, superseded, pending, review, approved, planning, open, closed, sent, canonical |

Lifecycle state. The valid values span three lifecycles — document, decision-record, and workflow — and the value's meaning depends on the document's `type` (Zone 1b, §5b.1) or, during the migration window, `mx.contentType` (§6.8 retiring synonym). The matrix in §6.1.1 governs which values are valid for which content types; an out-of-matrix value is a conformance failure.

```yaml
mx:
  status: active
```

#### 6.1.1 Valid `status` by `type` (Normative)

A document MUST declare a `status` value drawn from the row matching its `type` (or `mx.contentType` during the migration window). The matrix below is normative; a `status` value that does not appear in the row for the document's declared type is a conformance failure.

| `type`            | Valid `status` values                                                |
|--------------------------|----------------------------------------------------------------------|
| `info-doc`, `manuscript`, `guide`, `reference`, `report`, `field-dictionary`, `standards-alignment` | draft, active, published, archived, canonical, unknown |
| `specification`, `cog`, `cogs`              | draft, active, canonical, deprecated, archived, unknown              |
| `decision-record`, `adr`                    | proposed, accepted, rejected, superseded                             |
| `workflow`, `task`, `ticket`                | pending, review, approved, planning, open, closed, sent              |
| `identity`                                  | active, archived, unknown                                            |

Notes on the matrix:

- A document whose `type` does not appear in the matrix MAY use any value in the document lifecycle row (`draft`, `active`, `published`, `archived`, `canonical`, `unknown`) as a default; sister notes adding new content types SHOULD extend the matrix in lockstep.
- `unknown` is a conformance-safe placeholder for documents whose lifecycle is genuinely undetermined; tools SHOULD warn when it persists past initial authorship.
- `canonical` denotes an authoritative reference document — the present-tense source of truth for its subject. Distinct from `published` (a release point) and `active` (currently maintained).
- A document that legitimately spans lifecycles (rare — for example, a decision-record blog post) MUST pick a single `type` value and draw its `status` from that lifecycle's row.

---

### 6.2 `tags`

| Property | Value |
|----------|-------|
| **Type** | array |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Discovery keywords. Array of strings for search, filtering, and agent matching. Values SHOULD be lowercase strings.

```yaml
mx:
  tags: [metadata, yaml, frontmatter, reference]
```

---

### 6.3 `audience`

| Property | Value |
|----------|-------|
| **Type** | string-or-array |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |
| **Valid values** | tech, business, humans, machines, agents, both |

Intended readership.

```yaml
mx:
  audience: [humans, machines]
```

---

### 6.4 `purpose`

| Property | Value |
|----------|-------|
| **Type** | string-or-object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Why this document exists. Distinct from `type` (§5b.1), which classifies what a document is, not why it exists. The field accepts two shapes:

- **String form** — a single value drawn from the controlled high-level vocabulary below. Sufficient for most documents.
- **Object form** — `{ kind: <controlled value>, subPurpose: "<free-form>" }` — for documents whose purpose has a recognisable major axis but a specific genre that the controlled vocabulary does not name (a position paper, a press release, a regulatory filing, a contract, a case study).

The controlled high-level vocabulary (used as the bare string value or as the `kind` sub-key in the object form):

| Value | Definition |
|-------|-----------|
| `specification` | Defines a contract, schema, or normative rule that other artefacts implement. |
| `reference` | A lookup resource: catalogue, dictionary, registry, atlas. Read by index, not cover-to-cover. |
| `guide` | Walks a reader through an unfamiliar process or domain. Pedagogical. |
| `operational` | Operational instructions for an actor (human or machine) to execute. Includes runbooks, SOPs, manuals. |
| `narrative` | Argument-bearing prose. Includes position papers, blog posts, essays, manifestos, press releases, opinion pieces. |
| `record` | Captures a state, event, or decision for the historical record. Includes minutes, decision records, audit logs, reports. |

A document declaring `purpose` SHOULD pick the value whose definition fits best; when the genre is recognisable but specific, the object form names it via `subPurpose`.

**Examples:**

```yaml
# String form — most documents
mx:
  purpose: reference
```

```yaml
# Object form — narrative, named genre
mx:
  purpose:
    kind: narrative
    subPurpose: "position paper"
```

```yaml
# Object form — record, named genre
mx:
  purpose:
    kind: record
    subPurpose: "regulatory filing"
```

- The legacy values `operational manual`, `dispatcher`, and `configuration` (from earlier drafts of this note) are no longer in the controlled vocabulary. Implementations MUST treat `operational manual` as an alias of `operational`; `dispatcher` and `configuration` SHOULD be migrated to the closest fit (typically `operational` with a `subPurpose`) and the alias supported for one major version.
- `subPurpose` is free-form and lower-case-with-spaces. Tools SHOULD index `subPurpose` values for discoverability but MUST NOT treat them as a controlled vocabulary.

---

### 6.5 `license`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

SPDX licence identifier. Values MUST use SPDX licence identifiers as defined in the [SPDX Licence List](https://spdx.org/licenses/). Common values: `proprietary`, `MIT`, `Apache-2.0`, `CC-BY-4.0`. The field name uses the spelling-neutral form `license` (SPDX standard spelling) so that the YAML key matches the SPDX identifier exactly across regional spellings.

```yaml
mx:
  license: MIT
```

---

### 6.6 `stewardship`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Mutable stewardship details. A single object that captures ongoing responsibility for the document — who maintains it, who answers questions about it, which legal entity owns it, what brand it is published under. Distinct from `originator` (§5.3), which is the immutable original creator and lives at the top level.

**Sub-keys** (all optional; declare the ones the document needs):

| Sub-key | Type | Definition |
|---------|------|-----------|
| `steward` | string | Person or team currently responsible for ongoing updates and corrections. May change as stewardship transfers. |
| `accountableContact` | string | Mailto, URL, or organisation reference that an outside reader uses when something is wrong with the document. The single point of contact for follow-up. |
| `legalEntity` | string | The legal owner of the document and its underlying rights. Typically a registered company or trading entity. |
| `brand` | string | Public-facing trading name or imprint under which the document is published. May differ from `legalEntity`. |

```yaml
mx:
  stewardship:
    steward: "Maxine + Tom"
    accountableContact: "info@cognovamx.com"
    legalEntity: "Digital Domain Technologies Ltd"
    brand: "CogNovaMX"
```

- A document SHOULD declare at least one sub-key when `stewardship` is present; an empty object is permitted but unusual.
- When `steward` is omitted, the `originator` is assumed to also be the steward.
- Implementations that publish metadata publicly SHOULD consider whether `accountableContact` values are appropriate for public exposure.

**Aliases.** Documents written before this consolidation used `maintainer` (string) and `ownership` (string-or-object). Implementations MUST treat them as aliases:

| Legacy field | Maps to |
|--------------|---------|
| `mx.maintainer: "<name>"` | `mx.stewardship.steward: "<name>"` |
| `mx.ownership: "<name>"` (string form) | `mx.stewardship.legalEntity: "<name>"` |
| `mx.ownership.owner` | `mx.stewardship.legalEntity` |
| `mx.ownership.delegate` | `mx.stewardship.steward` |
| `mx.ownership.contact` | `mx.stewardship.accountableContact` |

The legacy fields are supported for one major version after this note ratifies, then retire per the field-deprecation lifecycle in the MX Extensions note §10.4. The polymorphic string-or-object shape of `ownership` is retired entirely; the explicit object on `stewardship` replaces it.

---

### 6.7 `domain`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Business domain or subject area. Values are context-specific and not constrained to an enumeration. In folder metadata, `domain` is an identity field and MUST NOT be inherited by child folders.

```yaml
mx:
  domain: "machine-experience"
```

---

### 6.8 `contentType` *(retiring synonym — use top-level `type`)*

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) — retiring; canonical home is Zone 1b top-level `type` |
| **Conformance** | Accepted during migration window; promote to `type` for OKF conformance |

Machine-readable content type classification. This field is the pre-OKF location for content-type information. **New documents SHOULD declare `type:` at the top level (Zone 1b, §5b.1) instead.** The vocabulary and valid values are the same.

```yaml
# Pre-OKF (retiring synonym — still accepted during migration window):
mx:
  contentType: field-dictionary

# OKF-conformant (canonical):
type: field-dictionary
```

During the adoption window, implementations SHOULD accept `mx.contentType` and report it as a retiring synonym. After migration, `mx.contentType` is absent from conformant documents and the conformance gate rejects it.

---

### 6.9 `segment`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |
| **Valid values** | developer, author, agent, business, morning, afternoon, evening |

Segment classifier. Used in two contexts: audience segment (developer, author, agent, business) and time segment for session reports (morning, afternoon, evening).

```yaml
mx:
  segment: developer
```

---

### 6.10 `cacheability`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |
| **Valid values** | ephemeral, short-lived, medium, long-lived, permanent |
| **Default** | medium |

How long an agent or resolver may cache this document's content before re-fetching.

- `ephemeral` — MUST NOT be cached; content changes on every request.
- `short-lived` — cache for up to 1 hour.
- `medium` — cache for up to 1 day.
- `long-lived` — cache for up to 1 week.
- `permanent` — cache indefinitely until the document changes.

A custom duration string (e.g., `4h`, `30d`) is also accepted. Format: number + unit (`s`, `m`, `h`, `d`, `w`). Distinct from `stability` (content reliability) and `lifecycle` (development phase).

```yaml
mx:
  cacheability: long-lived
```

---

### 6.11 `readingLevel`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |
| **Valid values** | beginner, intermediate, advanced, expert |

Content reading level. Helps agents recommend content based on user expertise.

```yaml
mx:
  readingLevel: intermediate
```

---

### 6.12 `runbook`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 2) |

Operational instructions for agents. Describes how to interpret and act on this document. The runbook SHOULD be written in imperative voice and SHOULD be specific enough that an agent can act on it without reading the full document body. Particularly valuable for machine-facing documents where the document structure is not self-evident.

```yaml
mx:
  runbook: "Parse the fields array. Each entry has name, type, definition, status, and profile."
```

---

### 6.13 `confidential`

| Property | Value |
|----------|-------|
| **Type** | boolean |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |
| **Default** | false |

Whether this record must be excluded from public outputs. Authors SHOULD only declare this field when marking content as confidential.

```yaml
mx:
  confidential: true
```

---

### 6.14 `inherits`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Path to the file this document extends. The inheriting file adds MX metadata on top of the target's content. The target can be any file type (`.md`, `.html`, `.json`, `.yaml`, etc.). The inheriting file extends the target; it does not replace it. The path MAY be relative or absolute. For folder-level field inheritance, an `inheritable` field on the parent folder's metadata (out of scope for this note) is the preferred mechanism.

```yaml
mx:
  inherits: "README.md"
```

---

### 6.15 `ld`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Inline JSON-LD (Schema.org) expressed in YAML frontmatter. Enables structured data without a separate `<script>` block. Implementations rendering HTML from this metadata SHOULD convert the `ld` object to a `<script type="application/ld+json">` block.

```yaml
mx:
  ld:
    "@context": "https://schema.org"
    "@type": "TechArticle"
    name: "MX Core Metadata note"
```

---

### 6.16 `hold`

| Property | Value |
|----------|-------|
| **Type** | boolean |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |
| **Default** | false |

Publication-block flag. When `true`, the document is otherwise ready but is being held back from release, send, or merge pending an external decision. Distinct from `status: draft`, which means "still in progress"; `hold: true` says "complete or near-complete, but blocked from going out".

The flag is for human-readable workflow signalling. Implementations MAY use it to suppress publication, send, or notification automations; consumers SHOULD treat the absence of `hold` (and `hold: false`) as "not held". When `hold` is `true`, `holdReason` SHOULD be provided.

```yaml
mx:
  hold: true
```

---

### 6.17 `holdReason`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Free-text companion to `hold`. Records why the document is being held back and, where possible, the condition that will release it. Single sentence in present tense.

`holdReason` is meaningful only when `hold: true`. Setting `holdReason` without `hold` is permitted but SHOULD be treated by implementations as a hold not yet activated.

```yaml
mx:
  hold: true
  holdReason: "Tom holding the draft set overnight; release decision 1 May."
```

---

## 7. External alignments

Some MX fields carry values whose semantics are owned, in whole or in part, by an external standard. The `Owns semantics` column in the inventory below records the relationship:

- **`external`** — the external vocabulary fully owns the value's meaning. MX provides the YAML key as a convenience so authors don't have to switch syntax mid-frontmatter; tooling treats the field as the aligned external field. (Older drafts called this "pass-through".)
- **`mx`** — MX names both the field and the value semantics, but models them after a recognised external standard so existing tools can interoperate. The field name is MX's; the alignment is informational.
- **`aligned`** — MX names the field and its abstract semantics, with a normative requirement that the value be expressible in the cited external vocabulary. The field is MX's; the value's structure must agree with the standard.

### 7.1 Inventory

| Field | Aligns with | Owns semantics | Definition | Conformance |
|-------|-------------|:--------------:|-----------|:-----------:|
| `date` | Dublin Core `dc:date`, Schema.org `Date` | external | ISO 8601 date for a generic reference event distinct from `created` / `modified`. | MAY |
| `duration` | Schema.org `duration` | external | ISO 8601 duration (e.g. `PT1H30M`). For time-based content. | MAY |
| `format` | Dublin Core `dc:format`, Schema.org `encodingFormat` | external | Media type or file format string. | MAY |
| `rights` | Dublin Core `dc:rights`, Schema.org `license` | external | Free-form rights statement when an SPDX identifier does not fit. | MAY |
| `displayName` | FOAF `displayName`, Schema.org `alternateName` | external | Citation form when it differs from `title`. | MAY |
| `usage` | Schema.org `usageInfo` | external | Guidance on how the document is meant to be consumed. | MAY |
| `proofOfAuthorship` | W3C Verifiable Credentials, Signed Exchanges | mx | Cryptographic claim that the named author wrote this. | MAY |
| `integritySignature` | RFC 9421 HTTP Message Signatures, Subresource Integrity | mx | Hash or signature over the artefact's content. | MAY |
| `provenancePedigree` | W3C PROV-O, C2PA Content Credentials | mx | Derivation chain back to the source. | MAY |
| `canonicalUri` | RFC 3986, Schema.org `mainEntityOfPage`, Dublin Core `identifier` | aligned | Canonical location of this document, expressed as a URI (see §7a.1). | MUST (Level 2) |
| `conformsTo` | Dublin Core `conformsTo` | aligned | Standards this document declares conformance to (see §7a.4). | MUST (Level 2) |

### 7.2 Adding a new externally-aligned field

A new field in this inventory SHOULD be proposed only when there is value in surfacing the key in MX frontmatter and the alignment relationship is clear. The proposal MUST:

- Cite the external standard precisely (URL plus the specific field/property name).
- Declare which `Owns semantics` value applies (`external`, `mx`, or `aligned`).
- Declare the alignment in canon via `alignsWith:` so converters and validators can route the value to the external standard's schema.
- For `external` semantics: NOT redefine the value's meaning. MX's role is to carry the key.
- For `mx` and `aligned` semantics: name the alignment explicitly so a future deviation is documented at the proposal stage rather than discovered at integration.

### 7.3 Tiebreaker — when external semantics almost fit (Normative)

A recurring authoring question: an external standard's field nearly captures the value MX needs, but not exactly. The rule:

- **Exact fit** — declare the field with `Owns semantics: external` and defer entirely. MX MUST NOT redefine the value's meaning.
- **Close fit, no deviation needed** — declare the field with `Owns semantics: aligned`. MX names the abstract semantics; values must be expressible in the external vocabulary. No re-interpretation.
- **Close fit, deviation needed** — declare the field with `Owns semantics: mx` and document the deviation in the field's definition. The proposal MUST name the specific point at which MX departs from the external standard, the reason for the deviation, and the migration path if the external standard later closes the gap.
- **No fit** — the field is not externally aligned. Define it in §5 (Zone 1) or §6 (Zone 2) with full MX semantics; do not list it in this inventory.

MX MUST NOT silently override an external standard's semantics. A deviation is documented at the proposal stage or it is not a deviation — it is a bug.

---

## 7a. Document discovery and lifecycle

This section covers document discovery, version chains, lifecycle dates, machine-readable affordances, semantic identifiers, and consumption policy. Each field has a direct analogue in Dublin Core or Schema.org and applies to any MX-governed document regardless of vendor. The fields are written into the YAML frontmatter under Zone 2 (the `mx:` object) and, where the carrier supports XMP metadata (e.g. tagged PDFs under ISO 14289-1), should be propagated into the carrier's metadata packet so they survive copying and reformatting.

### 7a.1 Identity and provenance

| Field | Zone | Type | Definition | Analogue |
|-------|:-:|------|-----------|----------|
| `canonicalUri` | 2 | URI (RFC 3986) | Canonical location of this document, expressed as a URI. The scheme tells the receiver what kind of location it is: `file://` for a carrier that lives on disk, `smb://` / `nfs://` / internal `https://` for a carrier reachable inside a network, a publicly resolvable `https://` for a carrier on the public internet. | Schema.org `mainEntityOfPage`, Dublin Core `identifier` |
| `supersedes` | 2 | string-or-array | URL or identifier of an earlier document this one replaces. | Dublin Core `replaces` |
| `supersededBy` | 2 | string | URL of the later document that replaces this one. The inverse of `supersedes`. | Dublin Core `isReplacedBy` |

`canonicalUri` carries the carrier's authoritative location at every tier; the URI scheme tells the receiver how to interpret it. A cog that lives only on disk SHOULD use a `file://` URI naming the carrier. A cog served from a network volume or internal corporate application SHOULD use the URI reachable inside the relevant network (`smb://`, `nfs://`, or an internal `https://`). When a cog is hosted in a publicly reachable source repository or website, the value MUST be that public URI: without it, an agent holding a copy cannot find the authoritative version.

**Agreement with HTML's `<link rel="canonical">` (Normative).** For HTML carriers, the URL declared by the page's `<link rel="canonical">` element and the value of the `mx:canonical-uri` `<meta>` tag (the kebab-case HTML rendering of `mx.canonicalUri` per the MX Carrier Formats note) MUST agree. Verifiers MAY treat either form as authoritative. A page that declares both with disagreeing URLs is a conformance failure: tools cannot reconcile two contradictory canonical claims and SHOULD flag the page as ambiguous rather than guess. When only one form is present, that form is authoritative.

### 7a.2 Lifecycle dates

| Field | Zone | Type | Definition | Analogue |
|-------|:-:|------|-----------|----------|
| `expires` | 2 | string | ISO-8601 date after which the document's content is no longer authoritative. Pricing PDFs, SLAs, compliance reports benefit from explicit expiry. | Dublin Core `valid` (end date) |
| `reviewBy` | 2 | string | ISO-8601 date by which the document is scheduled for the next editorial review. Distinct from `expires`; review may confirm continued validity. | (none direct) |

### 7a.3 Action affordances

| Field | Zone | Type | Definition | Analogue |
|-------|:-:|------|-----------|----------|
| `relatedDocs` | 2 | array | List of URLs an agent should consider fetching for full context on this document. | Dublin Core `relation` |
| `supportContact` | 2 | string | Contact address (mailto, URL, or organisation reference) for follow-up questions. | Schema.org `contactPoint` |

### 7a.4 Semantics and structure

| Field | Zone | Type | Definition | Analogue |
|-------|:-:|------|-----------|----------|
| `summary` | 2 | string | One-to-two-sentence machine-summary of the document. Targets agents that need to decide whether the artefact is relevant before reading the body. | Schema.org `abstract` |
| `topic` | 2 | array | Controlled-vocabulary identifiers for the topics the document covers (Wikidata QIDs, Schema.org Concept URLs). | Schema.org `about`, Dublin Core `subject` |
| `entities` | 2 | array | Named entities (people, organisations, products) the document is about, given as stable identifiers (Wikidata QIDs, ORCID IDs, organisation domain names). | Schema.org `mentions` |
| `speakable` | 2 | string | Optional inline summary suitable for a voice agent to read aloud. | Schema.org SpeakableSpecification |
| `conformsTo` | 2 | array | Standards this document declares conformance to, as URIs or stable identifiers. Centralises what would otherwise be spread across many separate fields. | Dublin Core `conformsTo` |

### 7a.5 Consumption policy (negative space)

| Field | Zone | Type | Definition |
|-------|:-:|------|-----------|
| `trainingDataPolicy` | 2 | string | Whether this artefact may be included in AI training corpora. The flip side of robots.txt, embedded so it survives copying and syndication. |
| `doNotIndex` | 2 | boolean | When `true`, the document should not be added to public indices (search, llms.txt, sitemap) even where it is technically reachable. Embedded equivalent of robots.txt `noindex`. |

### 7a.6 Conformance levels

Four of the fourteen fields are MUST at Level 2 of the MX Core profile: `canonicalUri`, `summary`, `conformsTo`, `trainingDataPolicy`. The reasoning, in each case:

- `canonicalUri` — without it, agents holding a copy of the artefact cannot find the current authoritative version. The URI scheme also tells the receiver what kind of location it is: `file://` for on-disk, an internal scheme for network-reachable, a publicly resolvable `https://` for public. The single highest-value field of the standard.
- `summary` — without it, agents read the whole document to decide if it is relevant. The energy and inference saving is direct.
- `conformsTo` — without it, conformance claims are scattered across many implicit fields. Centralising them lets an agent read one field and know which contracts the document claims.
- `trainingDataPolicy` — AI training corpora routinely ingest public documents. An explicit policy is the only way for a publisher to express a position the consumer can act on.

The remaining ten fields are SHOULD at Level 2 and MAY at Level 1.

### 7a.7 XMP rendering

For carriers that support XMP metadata (PDFs, audio, video), the same fields should be written into the XMP packet using a registered namespace. The reference implementation in CogNovaMX uses `https://schemas.cognovamx.com/mx/1.0/` with the prefix `mx`, so a tagged PDF carries XMP properties such as `mx:CanonicalUri`, `mx:Summary`, `mx:ConformsTo`. The Gathering may wish to propose a vendor-neutral namespace once the field set is ratified.

---

## 8. Conformance summary

| Field | Zone | Level 1 (MUST) | Level 2 (SHOULD) | Level 3 (MAY) |
|-------|:-:|:-:|:-:|:-:|
| `title` | 1 | MUST | — | — |
| `description` | 1 | MUST | — | — |
| `originator` | 1 | MUST | — | — |
| `created` | 1 | MUST | — | — |
| `modified` | 1 | MUST | — | — |
| `version` | 1 | — | SHOULD | — |
| `schema` | 1 | — | — | MAY |
| `validatesAgainst` | 1 | — | — | MAY |
| `type` | 1b | — | SHOULD | — |
| `tags` | 1b | — | SHOULD | — |
| `resource` | 1b | — | — | MAY |
| `status` | 2 | — | SHOULD | — |
| `contentType` | 2 (retiring) | — | — | — |
| `runbook` | 2 | — | SHOULD | — |
| `audience` | 2 | — | — | MAY |
| `purpose` | 2 | — | — | MAY |
| `license` | 2 | — | — | MAY |
| `stewardship` | 2 | — | — | MAY |
| `domain` | 2 | — | — | MAY |
| `segment` | 2 | — | — | MAY |
| `cacheability` | 2 | — | — | MAY |
| `readingLevel` | 2 | — | — | MAY |
| `confidential` | 2 | — | — | MAY |
| `inherits` | 2 | — | — | MAY |
| `ld` | 2 | — | — | MAY |
| External alignments (§7) | varies | — | — | MAY |
| `canonicalUri` | 2 | — | MUST | — |
| `summary` | 2 | — | MUST | — |
| `conformsTo` | 2 | — | MUST | — |
| `trainingDataPolicy` | 2 | — | MUST | — |
| Legacy aliases: `author` → `originator`; `maintainer` → `stewardship.steward`; `ownership` → `stewardship.legalEntity` (and sub-keys per §6.6). Supported for one major version after this note ratifies. | | | | |

---

## 9. Security and privacy considerations

- The `confidential` field controls whether a document is excluded from public outputs. Implementations that generate public artefacts MUST respect this field.
- The `originator` field is immutable and establishes provenance. Implementations MUST NOT allow modification of this field after initial creation. The legacy `author` alias inherits the same immutability.
- The `stewardship.accountableContact` sub-key (§6.6) is typically a public contact address. Implementations that publish metadata publicly SHOULD verify the value is appropriate for public exposure (an organisational mailbox or generic role address rather than a personal one) before rendering it.

---

## 10. References

### 10.1 Normative references

- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) — Key words for use in RFCs to indicate requirement levels
- [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) — Date and time format
- [SPDX Licence List](https://spdx.org/licenses/) — Software Package Data Exchange licence identifiers

### 10.2 Informative references

- [Schema.org Style Guide](https://schema.org/docs/styleguide.html) — Vocabulary naming conventions
- [Dublin Core DCMI Namespace](https://www.dublincore.org/specifications/dublin-core/dcmi-namespace/) — Namespace governance model
- [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — Web Content Accessibility Guidelines (conformance level model)

---

## 11. Author quickstart (Informative)

Three minimum-viable frontmatter blocks an author can copy and adapt.

### 11.1 Minimum-viable Level 1 — a blog post

The smallest valid Level 1 frontmatter. Identifies and attributes; does not classify lifecycle.

```yaml
---
title: "How we hit Level 2 in a fortnight"
description: "What it took to retrofit MX core metadata onto an existing site."
originator: "Tom Cranstoun"
created: 2026-04-15
modified: 2026-05-07
---
```

### 11.2 Minimum-viable Level 2 — a production document

Level 2 adds lifecycle, classification, the four MUST-at-Level-2 web fields, and stewardship.

```yaml
---
title: "How we hit Level 2 in a fortnight"
description: "What it took to retrofit MX core metadata onto an existing site."
originator: "Tom Cranstoun"
created: 2026-04-15
modified: 2026-05-07
version: "1.0"
type: info-doc
mx:
  status: published
  runbook: "Read top to bottom; the table in section 3 carries the punch list."
  canonicalUri: https://mx.allabout.network/blog/level-2-in-a-fortnight
  summary: "A retrofit playbook from a real adoption: which fields landed first, which failed, and why."
  conformsTo: [https://mx.allabout.network/cog.html]
  trainingDataPolicy: "Permitted with attribution."
  stewardship:
    steward: "Tom Cranstoun"
    accountableContact: "info@cognovamx.com"
---
```

### 11.3 Minimum-viable Level 3 — a fully-described reference

Level 3 adds the discretionary classification fields. The example is a field-dictionary entry in a registry.

```yaml
---
title: "MX Core field — originator"
description: "Specification entry for the originator field in MX Core."
originator: "Tom Cranstoun"
created: 2026-05-07
modified: 2026-05-07
version: "1.0"
schema: ./schemas/mx-field-entry.v1.yaml
type: field-dictionary
tags: [mx-core, field, identity]
mx:
  status: canonical
  runbook: "The field-dictionary entry for originator. See §5.3 of the MX Core Metadata note for the full definition."
  canonicalUri: https://mx.allabout.network/fields/originator
  summary: "Immutable Zone 1 field naming the document's original creator."
  conformsTo: [https://mx.allabout.network/cog.html]
  trainingDataPolicy: "Permitted with attribution."
  audience: [humans, machines]
  purpose:
    kind: reference
    subPurpose: "field dictionary entry"
  license: MIT
  domain: "machine-experience"
  cacheability: long-lived
  readingLevel: intermediate
  stewardship:
    steward: "Tom Cranstoun"
    accountableContact: "info@cognovamx.com"
    legalEntity: "Digital Domain Technologies Ltd"
    brand: "CogNovaMX"
---
```

---

## 12. Common authoring mistakes (Informative)

Five shapes a fresh author often produces, each with the fix.

**Mistake 1: keeping `author` after rename.**

```yaml
# WRONG — author is a deprecated alias
author: "Tom Cranstoun"
```

The canonical Zone 1 identity field is `originator` (§5.3). `author` remains as a one-major-version alias, but new documents SHOULD declare `originator` directly.

**Mistake 2: using `ownership` as a string.**

```yaml
# WRONG — string-or-object polymorph is retired
mx:
  ownership: "Tom Cranstoun"
```

The polymorphic shape is gone. Use the `stewardship` object with explicit sub-keys (§6.6):

```yaml
# RIGHT
mx:
  stewardship:
    legalEntity: "Tom Cranstoun"
```

**Mistake 3: out-of-matrix `status`.**

```yaml
# WRONG — `closed` is not a valid status for a blog post
type: info-doc
mx:
  status: closed
```

`closed` is workflow lifecycle (§6.1.1). For an info-doc, draw from the document lifecycle row: `draft`, `active`, `published`, `archived`, `canonical`, `unknown`.

**Mistake 4: silent override of an external standard.**

```yaml
# WRONG — `format` is externally-aligned (Owns semantics: external); MX does not redefine its values
mx:
  format: "long-form"   # Not a valid Schema.org / Dublin Core format value
```

Externally-aligned fields with `Owns semantics: external` (§7.1) defer entirely to the external vocabulary. `format` expects a media type or recognised file format identifier. If a value the external standard does not accept is genuinely needed, the field is the wrong field — see §7.3 (Tiebreaker).

**Mistake 5: claiming Level 2 without the four MUST web fields.**

```yaml
# WRONG — Level 2 requires canonicalUri, summary, conformsTo, trainingDataPolicy
type: info-doc
mx:
  status: published
  runbook: "..."
```

A document at Level 2 MUST declare `canonicalUri`, `summary`, `conformsTo`, and `trainingDataPolicy` (§7a.6). Without them, the document is at Level 1, not Level 2 — declaring `status: published` is not the conformance signal.

---

*End of MX Core Metadata note draft.*

---

## MX Cogs note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-cogs.md
**File:** `draft-cogs.md`

# MX Cogs note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 27 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

MX Core defines machine-readable document metadata. **Cogs (Community Owned Governance Standards) are an optional layer on top of MX.** A cog is a `.cog.md` file: a markdown document with structured YAML frontmatter that, in addition to the MX core fields it carries, declares additional fields describing its place in a registry, its dependencies, the typed content blocks in its body, an optional execution contract, and how it identifies itself to unfamiliar consumers.

A document does not need to be a cog to carry MX metadata. A blog post, a sidecar YAML, or an HTML page can declare title, author, dates, audience, license without ever being a cog. Cogs are the vocabulary you reach for when you want a document to be **navigable**, **composable**, and **runnable** by agents and runtimes — not the floor for being MX-aware.

This note specifies:

- The cog file format (`.cog.md`).
- The magic-header YAML comment line carried inside the frontmatter for raw-text self-identification.
- The HTML carrier form of the magic-header: an `mx:cog` `<meta>` tag in the document's `<head>` (§4.1).
- The `cogHeader` frontmatter field that mirrors the magic-header comment for consumers that work on parsed data structures rather than raw text.
- The cog structural fields (`partOf`, `buildsOn`, `dependencies`, `refersTo`, plus the cog-specific extensions for blocks, execute contracts, includes, deliverables, classification, and identifiers — some of which are carried in vendor-extension space and may be promoted into the standard tier by The Gathering).

**Out of scope:**

- **Signing.** A cog can be signed but does not have to be; signing is governed by the MX Contract Fingerprinting and Signing draft note.
- **Non-YAML carriers.** This note specifies the `.cog.md` markdown form only. How an MX-aware HTML page, JavaScript file, CSS file, or sidecar carries identity and operational metadata is governed by the MX Carrier Formats note.
- **Document identity field semantics.** What `title`, `description`, `author`, `created`, `modified`, and `version` mean is governed by the MX Core Metadata note. Cogs inherit these definitions; this note does not redefine them.
- **Namespace policy.** The `x-mx-` and `x-mx-p-` prefix conventions used by some cog fields are governed by the MX Extensions note.

The three-zone YAML frontmatter model is carried over from MX Core: Zone 1a (top-level) holds document identity fields; Zone 1b (top-level) holds OKF-reserved surface fields (`type`, `tags`, `resource`); Zone 2 (under the `mx:` object) holds MX-operational fields. Cog structural fields live in Zone 2 unless explicitly noted as top-level (`cogHeader`, `contractFields`, `metadataFields`). An OKF consumer reading a cog file treats the entire `mx:` block as one unknown preserved key — this is the dual-conformance property that makes a cog simultaneously valid OKF and full MX.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) when, and only when, they appear in all capitals.

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of this draft set). That pattern governs the structural template for every field — heading, property table, definition prose, example — and is binding on this note. This note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance tiers

This note defines three conformance tiers for cog documents (modelled on the [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level A/AA/AAA pattern). The tiers are deliberately labelled **A / B / C** rather than Level 1/2/3 to avoid collision with the MX Core ladder defined in the MX Core Metadata note §2.1, which also uses Level 1/2/3 to grade the document-identity floor. Each cog tier assumes the document already satisfies the matching MX Core level for document identity; the two ladders apply simultaneously.

| Tier | Cog requirement |
|------|-----------------|
| **Tier A** | The document is a `.cog.md` file. `partOf` declared. |
| **Tier B** | Adds `buildsOn` (or an empty array) and either a magic-header comment or a `cogHeader` field. |
| **Tier C** | Adds explicit `dependencies`, `refersTo`, plus the relevant extensions (block declarations, execute contract, deliverables, identifiers) for the cog's role. |

A cog claiming conformance at a given tier MUST satisfy all requirements at that tier and all lower tiers.

#### 2.1.1 Reconciliation with the MX Core ladder

A cog is graded by **two** ladders at once: the MX Core Metadata note's Level 1/2/3 ladder (the document-identity floor that applies to every MX document) and this note's Tier A/B/C ladder (the cog-layer fields). A complete claim names both — for example, *"this cog is MX Core Level 3 + Cog Tier C"*. The combinations have the following meanings:

| MX Core | Cog Tier | What this cog is |
|---------|----------|------------------|
| Level 1 | Tier A | Minimal cog: identifies as `.cog.md` and carries the MUST identity fields. |
| Level 2 | Tier B | Discoverable: the magic-header / `cogHeader` lets unfamiliar consumers self-orient, and the SHOULD identity fields are present. |
| Level 3 | Tier C | Fully wired: dependencies, refers-to, classification, and all applicable identity fields are declared. |

Lower-numbered MX Core levels can pair with higher cog tiers, and vice versa, but a Tier C cog at MX Core Level 1 is unusual — most fully-wired cogs also carry the Level 2 or Level 3 identity floor.

### 2.2 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the field definitions and conformance rules are working drafts — stable enough to build against, expected to evolve through review.

---

## 3. Terminology

- **Cog** — A `.cog.md` file. The atomic unit of the cog layer: a markdown document with YAML frontmatter and optionally typed content blocks (prose, action, definition, code, html, sop, etc.) within the body.
- **Optional layer** — A capability some MX-aware documents adopt and others do not. A document that does not adopt the cog layer is still a valid MX document.
- **Magic-header comment** — A specially formatted YAML comment line placed inside a cog file's YAML frontmatter (RECOMMENDED: the line immediately after the opening `---`), used for unambiguous file-level recognition by consumers scanning the frontmatter. In HTML carriers, the same identification is carried by an `mx:cog` `<meta>` tag in the document's `<head>` (§4.1).
- **Profile** — A named set of fields applicable to a specific document type. The cog layer defines the `cog` profile.

---

## 4. The magic-header comment

A cog file SHOULD identify itself as a cog by carrying a magic-header comment inside its YAML frontmatter, written as a YAML line comment:

```yaml
---
# cog v1 spec=https://example.org/cog-spec.v1.md runtime=https://example.org/cog-runtime.md
title: "..."
```

A YAML comment inside the frontmatter is visible to any agent reading the raw text and is preserved by YAML parsers as a token, so consumers that scan raw bytes and consumers that tokenise frontmatter both see the same identification line. Every YAML frontmatter parser (pandoc, gray-matter, kramdown-rfc) requires the opening `---` to be the first content in the file; the magic-header line placed immediately after that delimiter keeps the parser happy and the marker visible at the top of the file.

The line is a single YAML comment. Tokens in order, after the leading `#`:

1. The literal `cog`.
2. A version token of the form `v\d+(\.\d+)*` (`v1`, `v1.2`, `v2`, ...) — the cog spec version the document claims.
3. Zero or more `key=value` pairs separated by spaces. Conventional keys: `spec` (URL where the spec is published), `runtime` (URL where a runtime implementation lives), `runtime-doc` (URL pointing to runtime documentation).

The line MAY appear at any position within the frontmatter; placement on the line immediately after the opening `---` is RECOMMENDED so the identification is the first content a reader sees.

### 4.1 HTML carrier form

In HTML carriers, the same identification is carried by a single `mx:cog` meta tag in the document's `<head>`:

```html
<meta name="mx:cog" content="v1 spec=https://example.org/cog-spec.v1.md runtime=https://example.org/cog-runtime.md">
```

The `name` attribute is the fixed string `mx:cog` (the `mx:` prefix is the MX namespace per the **MX Extensions note**; `cog` is the marker). The `content` attribute follows the same token grammar as the YAML comment after the leading `# cog` token: a version token (`v\d+(\.\d+)*`) followed by zero or more space-separated `key=value` pairs. The HTML meta tag MAY appear anywhere inside `<head>`; placement near the top of `<head>` is RECOMMENDED so the identification is the first content a reader sees.

The YAML comment form, the HTML meta-tag form, and the `cogHeader` frontmatter field (§5) carry identical information; each is the canonical form for its carrier. A document with multiple carriers (an HTML page generated from a Markdown source, a PDF with XMP metadata mirroring its source) SHOULD carry the appropriate form in every carrier where the content circulates.

### 4.2 Preserving the source YAML frontmatter in HTML

An HTML carrier MAY include the source markdown's YAML frontmatter verbatim as an HTML comment, typically placed inside `<head>` immediately after the `mx:cog` meta tag (§4.1). This preserves the full structured metadata for consumers that prefer to parse the original YAML rather than reconstruct it from individual `<meta>` tags:

```html
<head>
  <meta name="mx:cog" content="v1 spec=https://example.org/cog-spec.v1.md runtime=https://example.org/cog-runtime.md">
  <!--
  ---
  # cog v1 spec=https://example.org/cog-spec.v1.md runtime=https://example.org/cog-runtime.md
  title: "Example document"
  description: "..."
  author: "..."
  created: 2026-01-01
  modified: 2026-01-01
  type: info-doc
  mx:
    cogUrn: cog:web:example.com:01JC8X7K2N4P5Q6R7S8T9V0W1Y
    partOf: example-collection
  ---
  -->
  ...
</head>
```

The convention is useful when the HTML is generated from a markdown source and downstream tools (registries, validators, search indexers) prefer to consume the original YAML rather than reconstruct it field-by-field from `<meta>` tags. The HTML comment MUST contain the verbatim source frontmatter including the surrounding `---` delimiters; consumers parsing it use the same YAML grammar as for the source markdown file.

This carrier form is permissive (MAY), not required. The `mx:cog` meta tag (§4.1) is the canonical cog identification for HTML carriers; this convention is an additional metadata-preservation aid for implementations that generate HTML from a markdown source.

### 4.3 Consumers that operate on parsed YAML

For consumers that operate purely on parsed YAML data (registries, validators, graph builders that discard comments during parsing), the same information is also available through the `cogHeader` frontmatter field (§5).

### 4.4 Design rationale

Each carrier form earns its place from a specific reader's vantage point. The full reasoning behind the choice is informative, not normative; this sub-section records it so future implementers do not have to re-derive it.

**Why the YAML comment lives inside the frontmatter.** Pandoc, gray-matter, and kramdown-rfc all require the opening `---` of the YAML frontmatter to be the first thing in the file. Placing the magic-header as a YAML comment line inside the frontmatter preserves every parser the ecosystem depends on while still giving raw-byte scanners a marker in the first few hundred bytes of the file. The YAML lexer treats the comment as a token, so consumers that tokenise the frontmatter still see the line; consumers that scan raw bytes see it inline at the top of the file. One form serves both readerships without forcing either to compromise.

**Why the HTML form is an `mx:cog` `<meta>` tag.** HTML has a native metadata mechanism (`<meta>` in `<head>`) that every HTML consumer already understands. Cog identification in HTML therefore reuses the convention rather than inventing a new container: `<meta name="mx:cog" content="...">` mirrors the existing `<meta name="mx:fieldName" content="value">` pattern that every MX-aware HTML page uses for its other operational metadata. The `mx:` prefix carries the namespace and lets a consumer filter MX metadata from non-MX metadata in a single regex. The `content` value follows the same token grammar as the YAML comment (a version token, then `key=value` pairs) so an implementation that parses one form parses both with the same lexer.

**Why the preserved-YAML HTML comment is permissive and complementary.** HTML's `<meta>` tags are flat key-value pairs and do not represent nested YAML structures cleanly. A `mx:` block with sub-objects (`policyRef`, `model`, `humanInLoop`, `clauses`) requires either a flattened per-field naming convention (verbose, error-prone) or a structured value encoded into the `content` attribute (parsing burden on every consumer). For HTML generated from a Markdown source, the simpler answer is to keep the original YAML available verbatim in an HTML comment alongside the per-field `<meta>` tags. Tools that prefer the structured source read the comment; tools that need only specific fields read the meta tags; the two views are consistent because both are derived from the same source. The convention is MAY rather than MUST because not every HTML carrier has a Markdown source to preserve.

---

## 5. `cogHeader` — the frontmatter equivalent

A cog MAY declare `cogHeader` instead of, or in addition to, the magic-header comment. Both forms carry the same information; either suffices for cog identification. Implementations SHOULD prefer `cogHeader` for programmatic consumption (registries, validators) and the magic-header comment for raw-text file recognition by agents that have not yet parsed YAML.

### 5.1 `cogHeader`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 1 (top-level) |
| **Conformance** | MAY (Tier C); MUST be present if neither this field nor a magic-header comment is declared on a cog circulating outside a closed system (Tier B SHOULD-or-magic-header rule). |
| **Default** | *(none)* |

**Definition:** Object carrying the same information as the cog magic-header comment. Sub-keys:

| Sub-key | Type | Required when present | Definition |
|---------|------|-----------------------|-----------|
| `version` | string | yes | Cog spec version the document claims. Format: `v` followed by an integer or a dotted version string (`v1`, `v1.1`, `v2`). Same token as the magic header's version slot. |
| `spec` | string (URL) | yes | URL where the cog specification is published. SHOULD be HTTPS. |
| `runtime` | string (URL) | optional | URL where a runtime implementation can be found, downloaded, or invoked. |
| `runtimeDoc` | string (URL) | optional | URL pointing to runtime documentation explaining how to consume cogs. |

**Example:**

```yaml
cogHeader:
  version: v1
  spec: https://example.org/cog-spec.v1.md
  runtime: https://example.org/cog-runtime.md
  runtimeDoc: https://example.org/cog-runtime.md
```

- A cog declaring `cogHeader` MUST populate `version` and `spec`.
- `runtime` and `runtimeDoc` are optional; consumers MUST NOT treat their absence as a conformance failure.
- All URL-typed sub-keys SHOULD be HTTPS.
- Implementations SHOULD treat `cogHeader` values as informational metadata (excluded from any contract fingerprint applied to the cog) — these values describe identity, not contract.

### 5.2 The equivalence rule

When a cog includes both a magic-header comment AND a `cogHeader` field, the two forms MUST agree on every key they both declare:

- The magic header's version token MUST equal `cogHeader.version`.
- The magic header's `spec=` value MUST equal `cogHeader.spec`.
- The magic header's `runtime=` value MUST equal `cogHeader.runtime` when both are present.
- The magic header's `runtime-doc=` value MUST equal `cogHeader.runtimeDoc` when both are present.

A key present in only one form is permitted; a key present in both with mismatched values is a conformance failure.

### 5.3 Implementer guidance

Implementations SHOULD:

- Prefer `cogHeader` for programmatic consumption — it is queryable, robust to comment-stripping parsers, and addressable by registry tooling.
- Prefer the magic-header comment for raw-text self-identification — it sits at the top of the frontmatter and is visible to agents that scan bytes before parsing YAML structurally.
- Emit both forms when generating cogs intended for circulation, so consumers of either kind can recognise the file without round-trip parsing.

---

## 6. Cog structural fields

The following fields define a cog's place in a registry, its dependencies, and its operational contract. All cog structural fields reside in Zone 2 (the `mx:` object) unless explicitly noted as top-level.

### Declaring dependencies — explicit when applicable, standalone otherwise

A cog that stands on another cog — by being part of it, building on it, requiring it, inheriting from it, including it, or referring to it — MUST declare the relationship in the frontmatter using the appropriate relationship field (`partOf`, `buildsOn`, `dependencies`, `refersTo`, `inherits`, plus any include-style field a profile declares). Inheritance and inclusion count as dependencies for this purpose: any field that names another cog the current cog stands on carries the rule.

A **standalone cog** is one that names no other cog. It declares `dependencies: []` to make the absence explicit (the visible standalone marker) and carries no other relationship fields. The standalone case is the explicit converse of the MUST rule, not a separate category: every cog either lists what it depends on, or declares that it depends on nothing.

The rule applies to dependencies the cog itself relies on. Cogs the current cog publishes about, comments on, or supersedes are not dependencies and belong in their own fields (`supersedes`, `replaces`, vendor-namespaced extensions). The relationship fields named above are the canonical declarations a runtime, a registry, or a reader reads to know what context the cog needs to make sense.

### 6.1 `partOf`

| Property | Value |
|----------|-------|
| **Type** | array of strings (a bare string is accepted as a single-element array) |
| **Zone** | 2 (mx:) |
| **Conformance** | MUST (Tier A) for cogs |

**Definition:** Parent collection(s), suite(s), or initiative(s) the cog belongs to. Each value names a registry namespace, a series, or a parent artefact. Because it is an array, a cog can belong to more than one set at once - so a query for the members of any one set returns every cog that declares it, even when the cog also belongs to others.

**Example:**

```yaml
mx:
  partOf: [mx-the-gathering, mx-audit]
```

A single membership may be written as a bare string (`partOf: mx-the-gathering`); a conforming reader treats it as a one-element array.

### 6.2 `buildsOn`

| Property | Value |
|----------|-------|
| **Type** | array |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Tier B) for cogs |

**Definition:** Context graph. Array of cog names this document builds upon. Soft dependency — provides context, not a hard requirement.

**Example:**

```yaml
mx:
  buildsOn: [what-is-a-cog, cog-unified-spec]
```

- `buildsOn` forms the cog knowledge graph. The referenced cogs provide context but are not required for this cog to function.
- Distinct from `dependencies` (hard dependency) and `refersTo` (informational link).

### 6.3 `dependencies`

| Property | Value |
|----------|-------|
| **Type** | array of objects |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Tier C) |

**Definition:** Hard dependencies. An array of objects, each describing one thing this cog depends upon. Each entry has at minimum a `name` sub-key; optional sub-keys are `version` (a version constraint such as a SemVer range), `reason` (a one-sentence explanation of why the dependency is needed), and `kind` (one of `cog` | `runtime` | `package` | `external`; defaults to `cog`).

**Example:**

```yaml
mx:
  dependencies:
    - name: schema
      kind: cog
      reason: Validator depends on the schema cog's contract.
    - name: node
      kind: runtime
      version: '>=18'
    - name: markdownlint-cli2
      kind: package
```

- A cog MUST NOT be considered functional if any of its `dependencies` entries are missing or unresolvable for their declared `kind`.
- The recommended `kind` is `cog`. Runtime, package, and external deps SHOULD usually live in their proper carrier (`package.json`, the cog's runbook, an external manifest); the non-cog kinds in this field are escape hatches for cases where inline declaration is genuinely the right home.
- A cog with no dependencies MUST declare `dependencies: []` to make the standalone state visible — see the *Declaring dependencies* rule at the head of §6. Omitting the field is the older form and is being retired.
- Distinct from `buildsOn` (soft context) and `refersTo` (informational link).

### 6.4 `refersTo`

| Property | Value |
|----------|-------|
| **Type** | array |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Tier C) |

**Definition:** Related cogs or external resources. Informational links, not dependencies.

**Example:**

```yaml
mx:
  refersTo: [field-dictionary, cog-unified-spec]
```

### 6.5 Identifier and classification fields

The following fields classify a cog within its registry. They live in vendor-extension space (`x-mx-*`); the field names without prefix are reserved here and SHOULD be implemented under the `x-<vendor>-` convention. The Gathering may promote any of them into the standard cog tier.

| Field | Type | Zone | Purpose |
|-------|------|:----:|---------|
| `cogId` | string | 2 | Unique cog identifier within the registry. Typically derived from the filename without `.cog.md`. MUST be unique within its `partOf` namespace. |
| `cogType` | string | 2 | Cog classification. Common values: `info` (reference / documentation), `action.scripted` / `action.sop` / `action.hybrid` (carries an execute contract; the discriminator after the dot names the cognitive class — see §6.5.2; `action` paired with a separate `actionType` field is an equivalent alias), `routing` (agent navigation), `certificate-of-genuineness` (publisher-provenanced credential), `cogs` (community-owned governance standard; see §6.5.1). |
| `category` | string | 2 | Registry grouping (e.g. `mx-core`, `mx-tool`, `mx-content`). Coarser than `cogType`. |

#### 6.5.1 The `cogs` classification (community-owned governance standard)

A `cogs` cog (initialism: Community Owned Governance Standard) is a cog whose definition is owned and stewarded by an open community rather than a single vendor or author. The classification denotes the governance model, not the file format — every `cogs` cog is still a normal `.cog.md` file with the same frontmatter shape as any other cog. What differs is who can change the cog's definition and through what process.

A cog declaring `cogType: cogs` MUST also identify the community that governs its definition. The MX community uses <https://tg.community> as the convening venue for The Gathering's cog stewardship. Other communities MAY use this classification for their own governance arrangements, identifying the governing body in the cog's `partOf`, `publisher`, or `provenanceOrigin` field as appropriate.

The `cogs` classification is intended for cogs that act as community-ratified reference definitions — field dictionaries, terminology registers, governance policies, conformance rubrics — where vendor capture would defeat the purpose. A `cogs` cog has no implied license; the cog's own `license` field still applies.

#### 6.5.2 Action cog discriminator (`cogType: action.<kind>` and `actionType`)

The cog specification draws a sharp axis through every action cog: it MAY be **deterministic**, **inference-driven**, or **both**. The discriminator named in this subsection is how the cog declares which. A deterministic cog carries fixed instructions a runtime executes the same way every time; an inference-driven cog carries instructions a language-model runtime reads and performs using its own reasoning; a both-form cog carries each in the role each is fit for. A consumer that knows this axis up front can choose to accept, reject, or sandbox the cog without inspecting the body. A consumer that does not know it has no way to tell whether the cog will run a shell command or invite a language model to act on its behalf — two operationally very different requests.

An action cog MUST declare its cognitive class so a consumer (human or agent) knows what kind of execution is involved without inspecting the body. Two forms are permitted, both expressing the same meaning:

- **Dotted form (canonical):** `cogType: action.scripted`, `cogType: action.sop`, or `cogType: action.hybrid`. The discriminator lives entirely in the `cogType` value. A consumer parses one field.
- **Deconstructed form (alias):** `cogType: action` with a separate `actionType: scripted | sop | hybrid` field. Equivalent semantically; permitted for tools or vendors that prefer the parallel-field shape.

A cog MUST NOT declare both forms with disagreeing values. When both are present they MUST agree (e.g. `cogType: action.scripted` with `actionType: scripted` is valid; `cogType: action.scripted` with `actionType: sop` is a conformance failure).

The three discriminator values:

- **`scripted`** — the cog body carries an embedded executable artefact (a fenced code block annotated `@embedded:<id>` per the cog specification). A runtime extracts the artefact by id and runs it directly. Deterministic; the same inputs produce the same outputs.
- **`sop`** — the cog body carries no embedded executable artefact. The `execute.actions[].usage` value is descriptive prose intended for a language-model runtime to read and perform the steps. The runtime is the language model itself.
- **`hybrid`** — the cog carries both an embedded executable artefact AND descriptive `usage` prose. The script handles the deterministic portion; the prose carries the judgement-dependent portion a language model performs.

| Field | Type | Zone | Profile | Conformance |
|-------|------|:----:|---------|-------------|
| `cogType` | string | 2 | cog (action) | MUST be of the form `action.<kind>` for action cogs (or `action` when paired with `actionType`) |
| `actionType` | string | 2 | cog (action) | OPTIONAL alias of the dotted form; SHOULD NOT appear when the dotted form is used; MUST NOT appear on cogs without `execute` |

A cog declaring `execute` MUST declare the discriminator (in either form) so consumers can resolve the runtime requirement (interpreter, language model, or both) before extracting any artefact. A cog without `execute` MUST NOT declare the discriminator in either form.

**Example (dotted form, canonical):**

```yaml
mx:
  cogType: action.scripted
  execute:
    actions:
      - name: run
        description: Execute the embedded script
```

**Example (deconstructed form, alias):**

```yaml
mx:
  cogType: action
  actionType: scripted
  execute:
    actions:
      - name: run
        description: Execute the embedded script
```

#### 6.5.3 `cogUrn` — universal identifier

A cog SHOULD declare a `cogUrn` field carrying its universal identifier as a URN-shaped string of the form `cog:<publisher-namespace>:<local-id>`. Unlike `cogId` (§6.5), which is reserved in vendor-extension space for a registry-local short identifier, `cogUrn` is a standard-tier field intended for use by every party outside the publisher's own systems: registries, clients, verifiers, and downstream agents.

The `<publisher-namespace>` is a stable namespace the publisher controls, typically derived from the publisher's DID (for example `web:example.com` for `did:web:example.com`). The `<local-id>` is a publisher-chosen identifier unique within that namespace; [ULID](https://github.com/ulid/spec) values are RECOMMENDED for `<local-id>` because they are time-sortable and collision-resistant without coordination.

| Field | Type | Zone | Profile | Conformance |
|-------|------|:----:|---------|-------------|
| `cogUrn` | string | 2 | cog (any) | SHOULD; URN-shaped `cog:<publisher-namespace>:<local-id>`; permanent across versions of the same logical record |

The `cogUrn` is set when the cog is created. It is permanent: a cog never changes its `cogUrn`. New versions of the same logical record (a corrected record, an amended clause) share the `cogUrn` and differ in `schemaVersion` (§6.5.4). The namespace prefix ensures global uniqueness without a central authority; two publishers controlling distinct domains cannot collide.

A publisher that loses control of its namespace is a recoverable situation as long as the original DID document remains resolvable; permanent loss is a worst-case that the trust layer handles per the MX Attestation Records and Verification note, with liability resting on the publisher.

**Example:**

```yaml
mx:
  cogUrn: cog:web:example.com:01JC8X7K2N4P5Q6R7S8T9V0W1Y
```

`cogUrn` and `cogId` (§6.5) are independent identifiers and MAY both be present on the same cog. `cogUrn` is the universal long-form identifier; `cogId` is a vendor-extension short-form identifier scoped to a registry's namespace.

#### 6.5.4 `schemaVersion` — cog-schema version

A cog SHOULD declare a `schemaVersion` field carrying the semver of the cog schema this record conforms to. `schemaVersion` is a standard-tier field, distinct from `cogHeader.version` (§5.1) which declares the cog-spec version a file conforms to.

| Field | Type | Zone | Profile | Conformance |
|-------|------|:----:|---------|-------------|
| `schemaVersion` | string | 2 | cog (any) | SHOULD; semver (`MAJOR.MINOR.PATCH` or `MAJOR.MINOR`) |

The Gathering versions cog schemas using semver:

- **Patch** (1.0.0 → 1.0.1): editorial corrections to the schema, no field changes. Existing cogs remain valid.
- **Minor** (1.0.0 → 1.1.0): new optional fields added. Existing cogs remain valid. Clients that understand the previous minor version parse the newer cogs and ignore the unfamiliar fields.
- **Major** (1.0.0 → 2.0.0): breaking changes, including field removals, semantics changes, or required-field additions. Existing cogs remain readable but require version-aware clients.

Registries MUST serve cogs at whatever `schemaVersion` they were published under. A v1.0 cog is served as v1.0 indefinitely. Registries MUST NOT migrate cogs to newer schema versions; the publisher MAY publish a new version of the same `cogUrn` under a newer `schemaVersion` if they choose, but the old version remains queryable.

Clients SHOULD accept any minor version within the major version they support. Clients encountering a major version they do not support SHOULD report this to the caller rather than attempt partial parsing.

**Example:**

```yaml
mx:
  schemaVersion: 1.0
```

The Gathering publishes a schema-evolution policy as part of the cog-schema documentation. The policy commits to: no breaking changes within a major version; a minimum window between major versions so the ecosystem can adapt; both the current and previous major versions remaining supported for a published transition period.

### 6.6 Composition and content-shape fields

The following fields describe the cog's body content and how it composes with other cogs. They likewise live in vendor-extension space.

| Field | Type | Zone | Purpose |
|-------|------|:----:|---------|
| `blocks` | array | 2 | Names the typed content blocks present in the document body (e.g. `prose`, `action`, `definition`, `essence`, `provenance`, `version`, `code`, `html`, `sop`, `security`). The `prose` block is implicit and need not be declared. |
| `includes` | array | 2 | Cog composition declarations. Each entry names a source cog, an optional block filter, and a resolution mode (`build` resolves at build time and inlines content; `runtime` resolves on each request). |
| `execute` | object | 2 | Action-doc execution contract. Carries `runtime`, `command`, optional `actions[]`, optional `policy`. The presence of an `execute` field distinguishes action cogs from info cogs. |
| `policy` | string-or-object | 2 | Content-handling rules for agents. Inheritable from a parent uber-doc. |
| `deliverable` | string-or-array | 2 | What this cog produces or delivers — a report, a validated artefact, a published page. For action cogs, describes what running the actions yields; for info cogs, describes the knowledge or artefact the cog represents. |

#### 6.6.1 Named sub-sections within the prose block

A single prose block MAY carry more than one named zone. A **sub-section** is a contiguous span of prose inside the document body enclosed by two HTML comments of the form `<!-- begin: <id> -->` and `<!-- end: <id> -->`. The `<id>` is a stable, kebab-case identifier. The markers are HTML comments so they survive markdown round-trips and render invisibly in any HTML view of the document.

The prose block remains the single implicit block of the cog. Sub-sections are an addressing convention within that block, not separate blocks; the `blocks` array does not list them.

Sub-sections are addressable by id. Readers and renderers MAY include, exclude, or extract a named sub-section. The canonical motivating case is a renderer that produces two derived artefacts from one source — for example, a covering letter plus a formal briefing in one markdown file, where one derived artefact strips the covering-letter sub-section and the other keeps it. Prose outside any marker pair is the default zone and is always included.

Conformance requirements:

- Sub-sections MUST NOT nest. A marker pair MUST close before the next pair opens. Nested ids constitute a malformed document.
- Each `<id>` MUST appear in at most one marker pair per document. Repeated ids constitute a malformed document.
- A reader that does not implement sub-section addressing MUST treat the markers as ordinary HTML comments and render the contained prose as part of the body.

### 6.7 Action contract fields

The following fields apply to cogs that declare an `execute` block or a procedure-declaring field. They make two questions a consumer always asks of an action cog answerable from frontmatter alone: *what shape does a successful output take* (`produces`), and *what should the runtime do when a failure arises that I have not catalogued* (`defaultRemedy` paired with `troubleshooting`). Both fields reside in Zone 2 (the `mx:` object).

#### 6.7.1 `produces`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 2 (mx:) |
| **Profile** | cog |
| **Conformance** | SHOULD (Tier C) for cogs that emit a structured output; MAY otherwise |

**Definition:** Output contract. Declares the typed shape a successful execution of this cog produces, so consumers can reason about (and validate) the output without first running the cog. Distinct from `deliverable` (§6.6), which names what the cog yields in human terms; `produces` declares a machine-checkable shape.

**Sub-keys:**

| Sub-key | Type | Required when present | Definition |
|---------|------|-----------------------|-----------|
| `shape` | string | yes | Pointer to a JSON Schema, YAML schema, or named profile describing the output. Resolved using the same rules the host runtime applies to a cog's input `schema` field. |
| `format` | string | optional | MIME type or named format identifier (`application/json`, `text/markdown`, `application/pdf`). |
| `example` | any | optional | An illustrative output value matching `shape`. |

**Example:**

```yaml
mx:
  produces:
    shape: ./schemas/audit-report.v1.yaml
    format: application/json
    example:
      summary: "12 issues, 3 critical"
      issues: []
```

- A cog with no `execute` block and no procedure-declaring field SHOULD NOT declare `produces`.
- Distinct from the document-level `schema` field (input contract for the document itself) and from `deliverable` (semantic description, not typed shape).
- Runtimes MAY validate the produced output against `produces.shape` after execution; runtimes that do so MUST report a shape mismatch as an unmodelled failure (see `defaultRemedy`).

#### 6.7.2 `defaultRemedy`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Profile** | cog |
| **Conformance** | SHOULD (Tier C) when `troubleshooting` is declared; MAY otherwise |

**Definition:** Catch-all remedy. Names the runtime-resolvable remedy a runtime SHOULD invoke when a failure arises that does not match any entry in `troubleshooting`. Resolves through the same registry used for `troubleshooting[].remedy` and obeys the same dotted-name syntax (lowercase, two or more dot-separated segments).

**Example:**

```yaml
mx:
  defaultRemedy: cogs.remedies.halt-and-escalate
  troubleshooting:
    - condition: required-field-missing
      remedy: cogs.remedies.request-supplier-resubmit
    - condition: validator-timeout
      remedy: cogs.remedies.retry-with-backoff
```

- The value MUST match the validator name regex (`^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$`).
- A cog declaring `defaultRemedy` without `troubleshooting` is valid but unusual; it asserts a single fallback for every failure mode.
- Distinct from a per-condition `troubleshooting` entry: `defaultRemedy` catches unmodelled conditions, not named ones, and removes the runtime's need to guess a safe behaviour.
- Combines naturally with `produces`: if a runtime cannot produce an output matching `produces.shape`, the situation is an unmodelled failure and `defaultRemedy` applies.

---

## 7. Conformance summary

| Field | Tier A (MUST) | Tier B (SHOULD) | Tier C (MAY) |
|-------|:-:|:-:|:-:|
| `partOf` | MUST | — | — |
| `buildsOn` | — | SHOULD | — |
| `cogHeader` *or* magic-header comment | — | SHOULD (when circulating) | — |
| `cogUrn` | — | SHOULD | — |
| `schemaVersion` | — | SHOULD | — |
| `dependencies` | — | — | MAY |
| `refersTo` | — | — | MAY |
| `cogId`, `cogType`, `category` | — | — | MAY |
| `blocks`, `includes`, `execute`, `policy`, `deliverable` | — | — | MAY |
| `produces`, `defaultRemedy` | — | — | MAY (SHOULD when the cog declares an `execute` block or a procedure-declaring field) |

A cog at Tier A is registry-locatable. At Tier B it is identifiable to unfamiliar consumers and provides its context graph. At Tier C it is fully described — dependencies, classifications, body content shape, and any execution contract.

---

## 8. Security and privacy considerations

- URLs declared in `cogHeader.runtime` may leak deployment topology. A cog declaring an internal runtime URL is exposing that URL to any reader of the cog. Operators concerned with topology privacy SHOULD either publish a public runtime URL or omit the field.
- A `cogHeader.spec` or `cogHeader.runtime` URL pointing at an attacker-controlled host is a phishing vector for runtimes that auto-fetch from those URLs. The protections are normative:
  - Runtimes **MUST** validate the `cogHeader.spec` and `cogHeader.runtime` URLs against an operator-controlled allowlist or a trusted registry before any fetch.
  - Runtimes **SHOULD NOT** auto-fetch unknown spec or runtime URLs. A first sight of an unrecognised URL warrants operator confirmation, not automatic resolution.
  - Runtimes **MAY** refuse to process cogs whose declared spec URL is unrecognised or unreachable, returning an explicit identification failure rather than guessing a fallback.
- The magic-header comment and `cogHeader` field are NOT authenticated — anyone who can write the cog can lie about which spec it claims to follow. Authentication, if required, is the responsibility of an external signing or witness mechanism, not this note.
- Cogs declaring `execute` contracts give agents a runnable surface. Operators MUST treat `execute.command` and `execute.actions[]` values as untrusted input and apply the same sandboxing, allowlisting, and audit measures they apply to any user-supplied command.
- A signed cog only attests provenance and integrity, never the truth of the content. Even when a cog's signature verifies cleanly, downstream consumers MUST NOT treat the values as factually correct — the signature confirms only that the cog genuinely came from the named signer and has not been altered. Editorial truth-curation is a different problem and out of scope for the cog format. User-facing language SHOULD say *attested*, not *verified*, to avoid implying a truth claim no signer makes.

---

## 9. References

### 9.1 Normative references

- [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) — keywords for use in RFCs to indicate requirement levels

### 9.2 Informative references

- [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — conformance level model that inspired the Tier A/B/C framework in §2.1

---

## 10. Author quickstart (Informative)

Two minimum-viable cogs an author can copy and adapt — one of each type.

### 10.1 Minimum-viable info-cog (Tier A)

The smallest valid info-cog. Identity floor is MX Core Level 1; cog layer is Tier A. Saved as `auth-design-notes.cog.md`:

```markdown
---
# cog v1 spec=https://example.org/cog-spec.v1.md runtime=https://example.org/cog-runtime.md
title: "Auth design notes"
description: "Working notes on the authentication redesign."
created: 2026-05-01
modified: 2026-05-07
author: "Tom Cranstoun"
mx:
  partOf: mx-internal
  cogType: info
---

# Auth design notes

(Body content goes here.)
```

This cog declares the four MUST-at-Level-1 identity fields (`title`, `created`, `modified`, `author`), the one MUST-at-Tier-A cog field (`partOf`), and an info-cog `cogType`. The magic-header YAML comment on the line immediately after the opening `---` identifies the document as a cog to any reader that scans the frontmatter.

### 10.2 Minimum-viable action-cog (Tier C)

The smallest valid scripted action-cog. Identity floor is MX Core Level 2; cog layer is Tier C. Saved as `run-audit.cog.md`:

````markdown
---
# cog v1 spec=https://example.org/cog-spec.v1.md runtime=https://example.org/cog-runtime.md
title: "Run audit"
description: "Run the audit pipeline against a target site."
created: 2026-05-01
modified: 2026-05-07
author: "Tom Cranstoun"
cogHeader:
  version: v1
  spec: https://example.org/cog-spec.v1.md
  runtime: https://example.org/cog-runtime.md
mx:
  partOf: mx-tools
  buildsOn: [audit-runtime]
  dependencies:
    - name: audit-runtime
      kind: cog
  cogType: action.scripted
  execute:
    runtime: bash
    actions:
      - name: run
        description: Run the audit pipeline
---

# Run audit

```bash
@embedded:run
echo "running audit"
```
````

This cog satisfies Tier C: `partOf`, `buildsOn`, a `cogHeader` block (and a magic-header comment line on the first line of the frontmatter), `dependencies` declared, the canonical dotted `cogType`, and an `execute` contract with a named action whose embedded artefact is identifiable to a runtime.

---

## 11. Consumer checklist (Informative)

The order a consuming tool SHOULD process a cog file:

1. **Scan the frontmatter for the magic-header line.** Inside the YAML frontmatter (the block between the opening `---` and the closing `---`), look for a YAML comment line of the form `# cog <version> <key=value> ...`. Parse the version token and any `spec=`, `runtime=`, `runtime-doc=` tokens.
2. **Parse YAML frontmatter.** Read identity (Zone 1) and operational (`mx:`) fields. If a `cogHeader` field is present, verify it agrees with the magic-header per §5.2.
3. **Validate the spec URL.** If `cogHeader.spec` is not on the operator's allowlist or trusted registry, refuse to process the cog or escalate to operator confirmation (§8).
4. **Resolve `partOf`.** Locate the cog within its parent registry. A cog whose `partOf` cannot be resolved is identifiable but not navigable.
5. **Walk `buildsOn`.** Load the named context cogs into the graph. Missing `buildsOn` entries are warnings, not failures.
6. **Walk `dependencies`.** Hard-resolve each entry per its declared `kind`. A missing `dependencies` entry is a hard failure (§6.3).
7. **Branch on `cogType`.**
    - `info` / `routing` / `cogs` / `certificate-of-genuineness` — process as a documentation or governance artefact; do not look for `execute`.
    - `action.<kind>` (or `action` with a separate `actionType`) — process as an executable cog; resolve the runtime requirement before extracting any artefact.
8. **For action cogs, validate `execute`.** Confirm the runtime is permitted in the consumer's environment. For `scripted` and `hybrid` cogs, locate the `@embedded:<id>` artefact named in `execute.actions[].name`.
9. **For action cogs that declare `produces`,** prepare to validate the output against the declared shape after execution. A shape mismatch is an unmodelled failure and triggers `defaultRemedy` (§6.7.2).

---

## 12. Common authoring mistakes (Informative)

Three shapes a fresh author often produces, each with the fix.

**Mistake 1: discriminator forms disagree.**

```yaml
# WRONG — dotted form and deconstructed alias contradict each other
mx:
  cogType: action.scripted
  actionType: sop
```

The two forms MUST agree (§6.5.2). Pick one form; if both are present, set `actionType` to the suffix of `cogType` or remove it entirely. The dotted form alone is sufficient.

**Mistake 2: `actionType` on an info-cog.**

```yaml
# WRONG — actionType MUST NOT appear without an execute block
mx:
  cogType: info
  actionType: sop
```

`actionType` is the discriminator for action cogs only (§6.5.2). On a cog without `execute`, remove the field.

**Mistake 3: claiming Tier B without an identifier.**

```yaml
# WRONG — Tier B requires either a cogHeader OR a magic-header
mx:
  partOf: mx-tools
  buildsOn: [other-cog]
```

The Tier B SHOULD-or-magic-header rule (§2.1, §5.1) requires at least one of: a magic-header YAML comment line inside the frontmatter, or a `cogHeader` field in the frontmatter. A cog circulating outside a closed system MUST carry one.

**Mistake 4: cog structural fields at the top level.**

```yaml
# WRONG — partOf and dependencies belong under mx:, not at the top level
title: "Run audit"
partOf: mx-tools
dependencies: [...]
```

All cog structural fields live in Zone 2 (§6) unless explicitly noted as top-level (`cogHeader`, `contractFields`, `metadataFields`). Move the misplaced fields under the `mx:` object.

---

*End of MX Cogs note draft.*

<!-- cog-spec-sync: 2026-07-01-a -->

---

## MX Extensions note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-extensions.md
**File:** `draft-extensions.md`

# MX Extensions note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 27 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note defines the namespace policy for the Machine Experience (MX) framework. It specifies how vendors extend the MX vocabulary without polluting the standard namespace, how field names adapt across syntactic contexts, and how new extension fields are registered.

The namespace policy establishes three levels: standard fields (no prefix, owned by The Gathering), public extensions (`x-mx-`, the public extension namespace operated by CogNovaMX during the seed phase; vendor sub-namespaces of the form `x-mx-{vendor}-*` are reserved for individual vendors), and private extensions (`x-mx-p-`, opaque-value extensions). The prefix itself is the policy: an implementation can determine governance from the field name alone, without external lookup.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of this draft set). That pattern governs the structural template for every field — heading, property table, definition prose, example — and is binding on this note. This note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

This note defines two conformance levels (modelled on the [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level A/AA pattern):

| Level | Name | Requirement |
|-------|------|-------------|
| Level 1 | **MX Core** | Valid namespace usage — standard fields have no prefix, extensions use `x-mx-` or `x-mx-p-`. No prefix pollution. |
| Level 2 | **MX Standard** | Adds Level 1 plus correct context-specific naming when fields appear outside YAML (HTML, JSDoc, CSS, XMP, shell, sidecar, SQL). |

A document claiming conformance at a given level MUST satisfy all requirements at that level and all lower levels.

### 2.2 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the field definitions, conformance requirements, and normative rules in this note are working drafts — stable enough to build against, expected to evolve through review.

---

## 3. Scope

### 3.1 In scope

This note specifies:

- **Namespace policy** — the three-level prefix hierarchy and governance rules
- **Context-specific naming** — how the same field appears in YAML, HTML, JSDoc, CSS, shell, XMP, sidecar, and SQL contexts
- **Public extension fields** — the `x-mx-` vendor extension vocabulary
- **Private extension mechanism** — the `x-mx-p-` obfuscated extension system
- **Extension registration process** — how to add new extension fields

### 3.2 Out of scope

- **Carrier format mechanics** — how each file format (HTML meta tags, JSDoc, CSS comments, EXIF/XMP, shell, sidecar, SQL) carries MX metadata is governed by a separate carrier-formats note.
- **Non-YAML identity fields** — the `mx:*` field vocabulary used by HTML, JavaScript, and CSS carriers (`mx:name`, `mx:version`, `mx:type`, etc.) is governed by the carrier-formats note.
- **Domain-specific extension fields** — fields belonging to a particular application domain (workflow contracts, content audits, observability) belong in their own notes, not this one.
- **Standard field definitions** — the meaning, type, and validation of standard MX fields (`title`, `author`, `created`, `description`, `status`, `contentType`) is governed by the MX Core Metadata note.

### 3.3 Relationship to existing standards

This note draws on the following published standards:

- **HTTP "X-" extension header convention** ([RFC 6648](https://www.rfc-editor.org/rfc/rfc6648) provides historical context) — the `x-` prefix convention for non-standard headers, adapted for metadata namespaces as `x-mx-`
- **Schema.org Style Guide** — vocabulary naming conventions; fields in YAML use camelCase per the Schema.org pattern
- **Dublin Core DCMI Namespace** — namespace governance model

---

## 4. Terminology

- **Namespace** — A prefix that identifies the owner and governance policy of a metadata field.
- **Standard field** — A field with no prefix, owned by The Gathering, universal across all MX implementations.
- **Extension field** — A field with an `x-mx-` or `x-mx-p-` prefix, owned by a vendor (currently CogNovaMX).
- **$MX_HOME** — The local MX OS registry directory. Contains decode tables for private extension values.

---

## 5. Design principles

The namespace system follows these principles:

1. **The prefix IS the policy.** No documentation lookup is needed to determine governance — `x-` means extension, `mx-` means CogNovaMX, `p-` means private.
2. **Standard fields are universal.** Every MX implementation uses the same core vocabulary with no prefix.
3. **Extensions are opt-in.** No implementation is required to support `x-mx-` or `x-mx-p-` fields.
4. **Context determines syntax, not semantics.** A field means the same thing regardless of whether it appears in YAML, HTML, or JSDoc.

---

## 6. Namespace policy

### 6.1 The three-level namespace

MX metadata fields are organised into three namespace levels. Each level has a distinct prefix, owner, and governance policy.

| Level | Prefix | Owner | Governance | Visibility |
|-------|--------|-------|------------|------------|
| Standard | *(none)* | The Gathering | Community-governed. Changes require Gathering approval. | Universal — all implementations use these fields. |
| Public extension | `x-mx-` | Public namespace, operated by CogNovaMX during the seed phase. Vendor sub-namespaces `x-mx-{vendor}-*` are reserved for individual vendors and allocated on request. | Vendor-governed within each sub-namespace. | Visible in published cogs. Implementation extension, not the open standard. |
| Private extension | `x-mx-p-` | Vendor-internal namespace. CogNovaMX during the seed phase; vendor sub-namespaces `x-mx-p-{vendor}-*` allocated as the public namespace is. | Vendor-governed. | Obfuscated. Only registry holders can decode values. |

### 6.2 Standard fields (no prefix)

Standard fields are the core MX vocabulary owned by The Gathering. They have no prefix.

Implementations MUST NOT add a prefix to standard fields. A field that is part of the core MX vocabulary MUST always appear without a prefix in all contexts.

**Example (correct):**

```yaml
type: guide
mx:
  status: active
```

**Example (incorrect — prefix pollution):**

```yaml
mx:
  x-mx-status: active     # WRONG — status is a standard field
  mx-type: guide           # WRONG — type is a Zone 1b field; no prefix, no mx: block
```

### 6.3 Public extension fields (`x-mx-`)

Public extension fields use the `x-mx-` prefix. The namespace is the public extension space for the MX vocabulary; CogNovaMX operates it during the seed phase. Vendor sub-namespaces of the form `x-mx-{vendor}-*` are reserved for individual vendors and allocated on request — for example, a vendor named "Acme" would publish fields as `x-mx-acme-deploy-target`. Within a vendor sub-namespace the vendor governs the field set.

Public extension fields MUST use the `x-mx-` prefix. They MUST use kebab-case for the field name portion (unlike standard fields which use camelCase in YAML). They are visible in published cogs and public outputs; they are implementation-specific features, not part of the open standard.

**Example (CogNovaMX, the seed-phase operator):**

```yaml
mx:
  x-mx-mount-type: personal
  x-mx-mount-swappable: true
```

**Example (vendor sub-namespace):**

```yaml
mx:
  x-mx-acme-deploy-target: production
  x-mx-acme-cluster-id: cluster-east-1
```

### 6.4 Private extension fields (`x-mx-p-`)

Private extension fields use the `x-mx-p-` prefix. They are owned by CogNovaMX and their values are hashed, encoded, or tokenised.

- Private extension field values MUST be opaque to any system that does not hold the decode registry at `$MX_HOME`.
- Implementations MUST NOT attempt to interpret `x-mx-p-` field values without access to the decode registry. Unknown values MUST be passed through unchanged.

**Example:**

```yaml
mx:
  x-mx-p-client-tier: "a3f2c8"
```

### 6.5 Prefix parsing rule

Implementations MUST parse field prefixes using the following precedence:

1. If the field name starts with `x-mx-p-`, it is a **private extension**.
2. If the field name starts with `x-mx-`, it is a **public extension**.
3. Otherwise, it is a **standard field**.

This ordering ensures that `x-mx-p-` is not misidentified as `x-mx-` followed by `p-`.

---

## 7. Context-specific naming

The same MX field appears in syntactically different contexts — YAML frontmatter, HTML meta tags, JavaScript documentation comments, CSS comments, shell scripts, XMP metadata, sidecar files, and SQL comments. Each context has its own naming convention. Implementations MUST apply the conversion consistently so that a field's identity is preserved across carriers.

### 7.1 Naming and conversion rules (Informative summary)

The table below summarises the per-carrier conventions. The **normative form** of each conversion — the binding rule a verifier checks — lives in the **MX Carrier Formats note**, which is the single source of truth for carrier-specific syntax. This summary is informative; if a row here disagrees with the carrier-formats note, the carrier-formats note wins.

| Context | Convention | Conversion from YAML camelCase | Example field | Example syntax |
|---------|-----------|--------------------------------|---------------|----------------|
| YAML | camelCase | *(canonical)* | `buildsOn` | `buildsOn: [cog-unified-spec]` |
| YAML (Zone 1b) | camelCase, top-level, no prefix | OKF-reserved field at top level | `type` | `type: guide` |
| HTML | Zone 1b: bare kebab-case; Zone 2: kebab-case with `mx:` prefix | OKF fields: no prefix; operational: prepend `mx:` | `type` / `mx:status` | `<meta name="type" content="guide">` / `<meta name="mx:status" content="active">` |
| JSDoc | kebab-case with `@mx:` tag | camelCase → kebab-case, prepend `@mx:` | `@mx:runtime` | `@mx:runtime node` |
| CSS | kebab-case with `@mx:` comment | camelCase → kebab-case, prepend `@mx:` | `@mx:type` | `/* @mx:type utility */` |
| Shell | camelCase in `# key: value` | none — preserve camelCase | `type` | `# type: guide` |
| XMP | `mx:` namespace prefix, case preserved | prepend `mx:` | `mx:type` | `<mx:type>guide</mx:type>` |
| Sidecar | camelCase in YAML (three-zone) | Zone 1b fields at top level | `type` | `type: guide` |
| SQL | camelCase in `-- @mx` block | none — preserve camelCase | `type` | `-- @mx type: guide` |

For HTML in particular: the four MUST-at-Level-2 fields from MX Core Metadata §7a (`canonicalUri`, `summary`, `conformsTo`, `trainingDataPolicy`) MUST be present in HTML carriers as the kebab-case `mx:` `<meta>` tags `mx:canonical-uri`, `mx:summary`, `mx:conforms-to`, `mx:training-data-policy`. The carrier-formats note defines the binding form and worked examples.

### 7.2 Extension field naming in non-YAML contexts

Extension fields (`x-mx-` and `x-mx-p-`) already use kebab-case. In non-YAML contexts, the prefix is preserved as-is:

| Context | Standard field example | Extension field example |
|---------|----------------------|------------------------|
| YAML | `type: guide` (Zone 1b) | `x-mx-mount-type: personal` |
| HTML | `<meta name="type" content="guide">` | `<meta name="mx:x-mx-mount-type">` |
| JSDoc | `@okf-type guide` | `@mx:x-mx-mount-type personal` |

---

## 8. Public extension fields (`x-mx-`)

The following fields use the `x-mx-` prefix and are owned by CogNovaMX. They are visible in published cogs and provide implementation-specific features that are not part of the open standard.

### 8.1 `x-mx-mount-type`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Profile** | x-mx-public |
| **Conformance** | MUST (Level 1) for x-mx-public profile |
| **Valid values** | personal, team, product, standard |

Categorises submodules in the hub mount table. Determines the governance and swapability characteristics of a mounted repository.

- `personal` — owned by an individual.
- `team` — shared across a team.
- `product` — a product component.
- `standard` — a forkable standard.

This field is REQUIRED for all `.mx.yaml.md` folder metadata files that describe mount points.

```yaml
mx:
  x-mx-mount-type: personal
```

### 8.2 `x-mx-mount-swappable`

| Property | Value |
|----------|-------|
| **Type** | string-or-boolean |
| **Zone** | 2 (mx:) |
| **Profile** | x-mx-public |
| **Conformance** | MUST (Level 1) for x-mx-public profile |
| **Valid values** | true, false, fork |

Whether this mount can be swapped for a different implementation.

- `true` — the mount can be replaced with any compatible alternative.
- `false` — the mount is integral and MUST NOT be replaced.
- `fork` — the mount can be replaced only by forking and customising.

```yaml
mx:
  x-mx-mount-swappable: true
```

### 8.3 `x-mx-mount-upstream`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Profile** | x-mx-public |
| **Conformance** | MAY (Level 2) |

Upstream source for standard-type mounts. Identifies the canonical source repository for a forked or derived mount. Only meaningful when `x-mx-mount-type` is `standard`. The value SHOULD be a URL pointing to the upstream repository.

```yaml
mx:
  x-mx-mount-upstream: "https://github.com/example/upstream-repo"
```

---

## 9. Private extension mechanism (`x-mx-p-`)

### 9.1 Overview

The `x-mx-p-` prefix designates private extension fields. Unlike standard fields and `x-mx-` public extensions, private extension values are opaque — they are hashed, encoded, or tokenised so that only holders of the decode registry can interpret them.

### 9.2 Value encoding

Private extension values MUST be encoded before storage. The encoding method is at the vendor's discretion. Common approaches include:

- **Hash-based** — a one-way hash that maps to a lookup table in `$MX_HOME`
- **Token-based** — a short token (e.g., `a3f2c8`) that resolves to a full value via the registry
- **Encrypted** — symmetric or asymmetric encryption with keys stored in `$MX_HOME`

### 9.3 Decode registry

The decode registry lives in `$MX_HOME`. Implementations that encounter `x-mx-p-` fields without access to the decode registry MUST:

1. Preserve the field and its opaque value unchanged.
2. Not attempt to decode, interpret, or validate the value.
3. Pass the field through to any output format without modification.

### 9.4 Field listing

This note does not list individual `x-mx-p-` fields. By definition, private extension fields are internal to CogNovaMX's implementation. Their names and semantics are documented in the `$MX_HOME` registry, not in public standards.

---

## 10. Extension registration process

### 10.1 How to add new extension fields

New extension fields are registered by CogNovaMX. The Gathering does not govern extension fields — vendor extensions are the vendor's call.

### 10.2 Registration steps

1. **Choose the prefix.** Use `x-mx-` for public extensions, `x-mx-p-` for private extensions.
2. **Use kebab-case.** Extension field names MUST use kebab-case (unlike standard fields which use camelCase in YAML). Example: `x-mx-deploy-target`, not `x-mx-deployTarget`.
3. **Document the context.** Describe the field's purpose, type, valid values, and which carrier formats it applies to.
4. **No Gathering approval needed.** Extension fields follow vendor governance, not community governance.

### 10.3 Promotion to the core vocabulary

An extension field MAY be promoted into the core MX vocabulary through the following process:

1. The vendor proposes promotion to The Gathering.
2. The Gathering reviews the field's adoption, utility, and universality.
3. If accepted, the field's prefix is removed, and it becomes a core field with camelCase naming.
4. The old `x-mx-` prefixed version SHOULD be maintained as an alias for one major version cycle.

### 10.4 Field deprecation and retirement (Normative)

A field — standard or extension — that turns out to be a bad idea, that fails to find adoption, or that is replaced by a better-named or better-shaped equivalent follows the announce → deprecate → retire lifecycle. The lifecycle is normative for fields owned by The Gathering; vendor sub-namespaces SHOULD adopt it but MAY follow their own retirement policy provided the policy is documented and the same one-major-version alias guarantee is offered.

**Stage 1 — Announce.** The owner publishes notice that the field will be deprecated. The notice MUST name:

- The field being deprecated.
- The replacement field, if any (or the rationale for retirement without replacement).
- The major version at which the field will be marked deprecated.
- The major version at which the field will be retired (typically one major version after deprecation).

The notice is a draft note, an entry in the field dictionary's deprecation log, or both. From the announcement onwards the canonical documentation for the field MUST link to the announcement.

**Stage 2 — Deprecate.** At the announced major version, the field is marked deprecated:

- The field's canonical documentation gains a `Deprecated:` banner naming the replacement.
- New documents SHOULD declare the replacement field; existing documents continue to validate.
- Tools SHOULD emit a one-line warning when they encounter the deprecated field, naming the replacement.
- The replacement field MUST treat the deprecated field as an alias and copy the value across when migrating documents.

A field MUST remain in the deprecated state for at least one major version cycle. This window is the migration runway: tooling, registries, downstream consumers, and authored documents have time to switch.

**Stage 3 — Retire.** At the announced retirement version, the field is removed:

- The field is removed from the canonical field dictionary and from the conformance summary tables.
- Validators MAY treat the retired field as a conformance failure (warning at minimum, error at the validator's discretion).
- The deprecation log keeps the field's entry permanently as historical record, with the retirement version annotated.

**Reverse of promotion.** A field that was promoted from extension space into the core vocabulary (§10.3) follows the same announce → deprecate → retire path if it is later retired. The `x-mx-`-prefixed alias maintained during promotion is itself retired in the same lifecycle event.

**Aliases as a migration tool.** When a field is renamed (the active case throughout the MX 1.0 ratification cycle — `author` → `originator`, `maintainer` / `ownership` → `stewardship`), the old name is treated as a deprecated alias of the new name from the deprecation announcement onward. The one-major-version alias guarantee gives every author and tool a mechanical migration path: update the field name at any point in the migration window, and validators on either side of the change will accept the document.

---

## 11. Conformance summary

| Requirement | Level 1 (MUST) | Level 2 (SHOULD/MAY) |
|-------------|:-:|:-:|
| Standard fields have no prefix | MUST | — |
| Extension fields use `x-mx-` or `x-mx-p-` | MUST | — |
| No prefix pollution | MUST | — |
| Correct context-specific naming for non-YAML carriers | — | SHOULD |
| `x-mx-mount-type` (when x-mx-public profile applies) | MUST | — |
| `x-mx-mount-swappable` (when x-mx-public profile applies) | MUST | — |
| `x-mx-mount-upstream` | — | MAY |

---

## 12. Security and privacy considerations

- The `x-mx-p-` private extension mechanism is designed to protect sensitive metadata values. Implementations MUST NOT attempt to decode private values without the `$MX_HOME` registry.
- Extension fields MAY carry information about infrastructure, deployment targets, or organisational structure. Authors SHOULD consider whether public extension values expose sensitive operational details.
- The decode registry at `$MX_HOME` contains sensitive lookup tables. Access to `$MX_HOME` SHOULD be restricted to authorised users and agents.

---

## 13. References

### 13.1 Normative references

- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) — Key words for use in RFCs to indicate requirement levels

### 13.2 Informative references

- [RFC 6648](https://www.rfc-editor.org/rfc/rfc6648) — Deprecating the "X-" prefix (historical context for the `x-mx-` convention)
- [HTTP Extension Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) — the `X-` prefix convention for non-standard headers
- [Schema.org Style Guide](https://schema.org/docs/styleguide.html) — Vocabulary naming conventions
- [Dublin Core DCMI Namespace](https://www.dublincore.org/specifications/dublin-core/dcmi-namespace/) — namespace governance model
- [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — Web Content Accessibility Guidelines (conformance level model)

---

## 14. Common authoring mistakes (Informative)

Five shapes a fresh author often produces, each with the fix.

**Mistake 1: prefixing a standard field.**

```yaml
# WRONG — status is a standard field; no prefix
mx:
  x-mx-status: active
```

Standard fields (§6.2) MUST never carry the `x-mx-` prefix. Drop the prefix:

```yaml
# RIGHT
mx:
  status: active
```

**Mistake 2: camelCase on an extension field.**

```yaml
# WRONG — extension fields use kebab-case in YAML, not camelCase
mx:
  x-mx-deployTarget: production
```

Extension fields (§6.3, §10.2) use kebab-case for the suffix:

```yaml
# RIGHT
mx:
  x-mx-deploy-target: production
```

**Mistake 3: claiming a vendor sub-namespace without permission.**

```yaml
# WRONG — `acme` sub-namespace not allocated to this author
mx:
  x-mx-acme-cluster-id: "prod-1"
```

The vendor sub-namespace pattern `x-mx-{vendor}-*` (§6.3) is reserved. Only use a vendor's sub-namespace if the namespace has been allocated to that vendor. For one-off fields outside an allocated sub-namespace, the seed-phase `x-mx-` namespace operated by CogNovaMX is the default until a sub-namespace is allocated.

**Mistake 4: trying to decode an `x-mx-p-` value.**

```yaml
# WRONG — implementations without the registry MUST NOT attempt to interpret
mx:
  x-mx-p-client-tier: "a3f2c8"
  # ... and downstream code does:
  # if (clientTier === "a3f2c8") { ... }
```

Private extension values (§9) are opaque. Implementations without access to the decode registry MUST pass the value through unchanged and MUST NOT branch on its content. The opaque token is meaningful only to a registry-equipped consumer.

**Mistake 5: introducing `x-mx-` for something the standard already covers.**

```yaml
# WRONG — modified is already a standard field
mx:
  x-mx-last-changed: 2026-05-07
```

Before declaring an `x-mx-` extension, check the standard vocabulary in MX Core Metadata §5–6. The intent here is captured by `modified` (Zone 1, §5.5). Use the standard field; the extension namespace is for genuinely new vocabulary, not synonyms of existing fields.

---

*End of MX Extensions note draft.*

---

## MX Provenance note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-provenance.md
**File:** `draft-provenance.md`

# MX Provenance note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 27 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note defines the provenance, trust, and verification metadata vocabulary for the Machine Experience (MX) framework. It specifies the fields that establish who created content, how it was created, how trustworthy it is, who maintains it, and what governance decisions shaped it.

The provenance vocabulary is organised into five groups: **attribution fields** (authorship and origin), **quality and trust fields** (reliability commitments), **maintenance fields** (ongoing stewardship), **decision record references** (governance links), and **migration fields** (content relocation tracking).

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of this draft set). That pattern governs the structural template for every field — heading, property table, definition prose, example — and is binding on this note. This note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

This note defines three conformance levels for provenance metadata. References to a top-level `author` field describe a string identifying the document's creator, located in the YAML frontmatter outside the `mx:` object — a near-universal convention in markdown-based authoring systems.

| Level | Name | Provenance requirement |
|-------|------|------------------------|
| Level 1 | **MX Core** | Author attribution present (`provenanceAuthor`, or a top-level `author` field) |
| Level 2 | **MX Standard** | Adds `provenanceOrigin`, `maintainedDate`, and `reviewCycle` declared |
| Level 3 | **MX Complete** | Full trust chain including `publisher`, `accuracyCommitment`, `correctionSla`, decision records, and quality triad |

A document claiming conformance at a given level MUST satisfy all requirements at that level and all lower levels.

### 2.2 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the field definitions, conformance requirements, and normative rules in this note are working drafts — stable enough to build against, expected to evolve through review.

---

## 3. Scope

### 3.1 In scope

- **Attribution fields** — authorship, publishing entity, content origin, source material, and generation instructions
- **Quality and trust fields** — accuracy commitments, review cycles, compliance levels, and the quality triad
- **Maintenance fields** — freshness tracking, maintainer identity, expiry, and update triggers
- **Decision record references** — links to architecture, naming, and business decision records
- **Migration fields** — content relocation tracking

### 3.2 Out of scope

- **Document identity fields** — `title`, `description`, `author`, `created`, `modified`, `version` are governed by the MX Core Metadata note. This note refers to the top-level `author` but does not redefine it.
- **AI/agent governance** — how agents may interact with content (read, edit, regenerate, attribute) is a separate concern; this note declares only how content was created (`provenanceOrigin`).
- **Cryptographic verification** — fingerprinting, signing, and signature verification are governed by a separate note. The `provenancePedigree`, `proofOfAuthorship`, and `integritySignature` fields are named in core metadata; their cryptographic mechanics are out of scope here.
- **Carrier-format mappings** — how these fields are expressed in HTML, JSDoc, CSS, etc. is governed by the MX Carrier Formats note.

### 3.3 Relationship to existing standards

All field names in this note use camelCase (matching the [Schema.org Style Guide](https://schema.org/docs/styleguide.html)) and avoid regional spelling variants where an established identifier system supplies a canonical spelling. All date fields use [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (YYYY-MM-DD). The quality triad references [WCAG 2.1](https://www.w3.org/TR/WCAG21/) for accessibility and [Schema.org](https://schema.org/) JSON-LD for semantic structure.

---

## 4. Provenance in the two-zone model

Provenance fields reside in Zone 2 (the `mx:` object), complementing the top-level `author` field that markdown-based authoring conventionally places in Zone 1.

The Zone 1 `author` field identifies the document creator. The Zone 2 provenance fields extend this with richer attribution: how the content was created (`provenanceOrigin`), who published it (`provenancePublisher`), and the original author if distinct from the Zone 1 `author` (`provenanceAuthor`).

```yaml
---
title: "Example Document"
author: "Tom Cranstoun"
created: 2026-04-02
modified: 2026-04-16

mx:
  provenanceAuthor: "Tom Cranstoun"
  provenancePublisher: "CogNovaMX Ltd"
  provenanceOrigin: human-directed
  maintainedDate: 2026-04-02
  maintainedBy: "Tom Cranstoun"
  reviewCycle: quarterly
  accuracyCommitment: "All factual claims verified against source documentation"
---
```

---

## 5. Attribution fields

### 5.0 Identity-field boundaries

Six fields touch document identity, each marking a distinct role in the document lifecycle. Treat them as different concepts and do not conflate them:

| Field | Role | Defined in |
|-------|------|-----------|
| `author` | Immutable creator of the document. The person or entity who first wrote it. Set once at creation and never changed. | **MX Core Metadata note** (Zone 1, top-level) |
| `provenanceAuthor` | Originator of the document's content, recorded in Zone 2 attribution metadata. May differ from `author` when content was contributed by another party. | This note (§5.1) |
| `maintainer` | Person or team responsible for ongoing maintenance of the document. The accountable steward, not necessarily the original creator. | **MX Core Metadata note** (Zone 2) |
| `maintainedBy` | Person or team who performed the most recent accuracy confirmation. May differ from `maintainer` (`maintainer` is the accountable role; `maintainedBy` records who actually did the last review). | This note (§7.2) |
| `publisher` | Entity that publishes the document and stands behind its claims. Rich struct with name, url, and contact sub-keys. | This note (§5.5) |
| `provenancePublisher` | Flat entity-name string declaring who published. The simpler form for cogs that do not need the rich `publisher` struct. | This note (§5.2) |

When a document declares more than one of these, each carries its own role and the others are not redundant. Validators MUST NOT collapse them. Authors of the canonical reading-order documentation SHOULD describe the role each field plays rather than treating them as interchangeable synonyms.

---

### 5.1 `provenanceAuthor`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MUST (Level 1) |

Person or entity who originally authored the document content.

```yaml
mx:
  provenanceAuthor: "Tom Cranstoun"
```

- At Level 1, a document MUST declare either `provenanceAuthor` or a top-level `author` field. Both MAY be present.
- When both are present, `provenanceAuthor` identifies the original content author, while `author` identifies the document creator. These are often the same person.

---

### 5.2 `provenancePublisher`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 2) |

Entity that published the document. Distinct from `publisher` (§5.5), which is a richer object used in trust-declaration cogs.

```yaml
mx:
  provenancePublisher: "CogNovaMX Ltd"
```

---

### 5.3 `provenanceOrigin`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 2) |
| **Valid values** | human-directed, ai-assisted, automated-fact-check |

How the content was created. Declares the human-machine authorship balance.

- `human-directed` — content authored by a human, possibly with AI tooling assistance.
- `ai-assisted` — content substantially generated by AI, with human review and direction.
- `automated-fact-check` — content generated and verified by automated processes.

```yaml
mx:
  provenanceOrigin: human-directed
```

---

### 5.4 `source`

| Property | Value |
|----------|-------|
| **Type** | string-or-array |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Origin source material or input files. Declares the content provenance chain — what materials were used to create this document. Paths MAY be relative or absolute.

```yaml
mx:
  source: "brainstorm.md"
```

```yaml
mx:
  source:
    - "quarterly-report.csv"
    - "customer-feedback.md"
```

---

### 5.5 `publisher`

| Property | Value |
|----------|-------|
| **Type** | string-or-object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Entity that publishes and stands behind this document. Can be a string (name) or an object with `name`, `url`, and `contact` sub-fields. Distinct from `provenancePublisher` (§5.2), which is a flat provenance field. The `publisher` field supports richer structured data and is used alongside `accuracyCommitment`, `reviewCycle`, and `mxCompliance` to form a complete trust declaration.

```yaml
mx:
  publisher: "CogNovaMX Ltd"
```

```yaml
mx:
  publisher:
    name: "CogNovaMX Ltd"
    url: "https://allabout.network"
    contact: "info@cognovamx.com"
```

---

### 5.6 `generate`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Generation instructions. Describes how to regenerate this content if lost or outdated. If a document is lost, an agent with access to the `generate` instructions and source material can recreate it.

```yaml
mx:
  generate:
    prompt: "Regenerate from source data"
    source: "quarterly-report.csv"
```

- The `prompt` sub-field SHOULD contain instructions specific enough to produce a faithful reconstruction.
- The `source` sub-field identifies the input data required for regeneration.

---

### 5.7 `provenanceUri`

| Property | Value |
|----------|-------|
| **Type** | string (URL) |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Canonical URL of the document's AI-governance provenance record: the hosted account of the parties, the regulatory frameworks the record cites, and every recorded action in the chain. A consumer reads `provenanceUri`, fetches the named record, and walks the evidence without the chain embedded in the document itself.

```yaml
mx:
  provenanceOrigin: ai-assisted
  provenanceUri: "https://example.org/reports/q3.mxprov.json"
```

`provenanceUri` complements an embedded chain rather than replacing it. A carrier that can embed its provenance (a PDF XMP packet, a raster or SVG metadata block, an HTML script block) MAY carry a snapshot so the chain travels offline, AND declare `provenanceUri` so a consumer can reach the current, canonical record. When both are present, the embedded copy is authoritative offline and the URL names the version to check against. This mirrors `canonicalUri`: the file carries what it can and names where the canonical form lives.

---

### 5.8 The hosted provenance record (`.mxprov.json`)

An implementation MAY publish a document's provenance chain as a standalone record served beside the document and addressed by `provenanceUri`. This note RECOMMENDS the file-name suffix `.mxprov.json` for such a record, so a consumer can recognise it by extension and a server can assign it a stable content type.

The record is JSON. Its body is the provenance chain: a `schemaVersion`, the accountable `parties`, the `frameworks` the record attests to, a `responsiblePerson`, and an ordered list of `steps`, each recording one action (agent, outcome, inputs). The shape is the same one an embedded chain carries; the `.mxprov.json` record is that chain lifted out of the file and hosted on its own.

```
example.org/reports/q3.html          the document
example.org/reports/q3.mxprov.json   its provenance record, named by q3.html's provenanceUri
```

A consumer that trusts the origin MAY fetch the `.mxprov.json` record named by `provenanceUri` to obtain the current chain. Fetching the record is a read of a public URL the document itself names; it discloses nothing about the consumer's copy of the document.

---

## 6. Quality and trust fields

### 6.1 `accuracyCommitment`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Publisher's commitment to content accuracy. A human-readable statement of the accuracy standard the publisher holds themselves to. The value SHOULD be a clear, actionable statement that a reader can use to assess the publisher's reliability. Used alongside `publisher`, `reviewCycle`, and `correctionSla` to form a complete trust declaration.

```yaml
mx:
  accuracyCommitment: "All factual claims verified against source documentation"
```

---

### 6.2 `reviewCycle`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 2) |

How often content is reviewed for accuracy. Common values: `weekly`, `monthly`, `quarterly`, `annually`, `on-change`.

```yaml
mx:
  reviewCycle: quarterly
```

---

### 6.3 `correctionSla`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Service-level agreement for correcting errors. The value SHOULD be a human-readable duration string. Communicates the publisher's responsiveness to reported errors.

```yaml
mx:
  correctionSla: "24 hours"
```

---

### 6.4 `mxCompliance`

| Property | Value |
|----------|-------|
| **Type** | string-or-object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

MX compliance level or detailed compliance metadata. When expressed as a string, the value corresponds to the conformance levels in §2.1 (`level-1`, `level-2`, `level-3`). Used alongside `publisher`, `accuracyCommitment`, and `reviewCycle` to form a complete trust declaration.

```yaml
mx:
  mxCompliance: "level-3"
```

```yaml
mx:
  mxCompliance:
    level: "level-3"
    lastAudit: 2026-04-01
    auditor: "Maxine"
```

---

### 6.5 `quality`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

The `quality` object groups three sub-keys that together describe document quality across complementary dimensions. Each sub-key MAY be a string (compliance level or summary) or an object with structured assessment data.

| Sub-key | Dimension | Aligns with |
|---------|-----------|-------------|
| `quality.accessibility` | How well content serves users with disabilities | [WCAG 2.1](https://www.w3.org/TR/WCAG21/), Pa11y |
| `quality.semantic` | How well content uses semantic HTML and structured data | [Schema.org](https://schema.org/) JSON-LD, microdata |
| `quality.convergence` | How well content aligns human and machine experiences | MX dual-experience principle |

```yaml
mx:
  quality:
    accessibility: "WCAG 2.1 AA"
    semantic: "Schema.org JSON-LD"
    convergence: high
```

Common values for `quality.convergence` when expressed as a string: `low`, `medium`, `high`.

The grouping into one parent object reflects that the three dimensions are complementary facets of a shared quality theme; readers and validators can probe `quality` once and iterate the sub-keys rather than checking three top-level fields. The detailed accessibility-conformance vocabulary (`accessibilityConformance`, `accessibilityFeature`, `accessibilityHazard`, `accessibilitySummary`) defined in the **MX Document Accessibility note** lives in a separate disclosure layer; `quality.accessibility` is the high-level signal, the document-accessibility fields are the detailed conformance claim.

---

## 7. Maintenance fields

### 7.1 `maintainedDate`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 2) |

Date the content was last confirmed accurate by its maintainer. Distinct from a top-level `modified` field. `modified` tracks when the document was last changed; `maintainedDate` tracks when it was last confirmed to still be accurate — even if no changes were needed. Agents SHOULD treat documents with a `maintainedDate` older than the `reviewCycle` as potentially stale.

```yaml
mx:
  maintainedDate: 2026-04-02
```

---

### 7.2 `maintainedBy`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Person or team who last confirmed accuracy. Distinct from a `maintainer` field (the person responsible for ongoing maintenance). `maintainedBy` records who performed the last accuracy confirmation — these may differ.

```yaml
mx:
  maintainedBy: "Tom Cranstoun"
```

---

### 7.3 `expires`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY |

`expires` is defined in the **MX Core Metadata note** as the ISO-8601 date after which the document's content is no longer expected to be authoritative. It is a foundation-layer field; this provenance note refers to it but does not redefine it. Time-sensitive content (pricing PDFs, service-level agreements, compliance reports, regulatory text) MAY declare `expires` alongside the maintenance fields here so a single review window covers both maintenance and validity.

```yaml
mx:
  expires: 2027-12-31
```

---

### 7.4 `updateTriggers`

| Property | Value |
|----------|-------|
| **Type** | array |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Conditions that trigger a content update. Events that should prompt a content review or revision. Values are context-specific strings describing trigger conditions. Tooling MAY use these values to automate review notifications when trigger conditions are detected.

```yaml
mx:
  updateTriggers:
    - specification-change
    - new-field-added
```

---

## 8. Decision record references

The fields `adr`, `ndr`, and `bdr` link a document to the formal decision record that governs an aspect of its content. Decision records provide governance traceability — they explain why certain choices were made.

All three fields share the same shape: a string path to the decision record, or an object with `path`, `date`, and `status` sub-fields.

| Field | Decision type | Typical content |
|-------|---------------|-----------------|
| `adr` | Architecture Decision Record | Architectural choices: storage strategy, transport protocol, deployment topology |
| `ndr` | Naming Decision Record | Naming conventions: identifier style, file naming, vocabulary policy |
| `bdr` | Business Decision Record | Business decisions: pricing, market positioning, partnership terms |

| Property | Value |
|----------|-------|
| **Type** | string-or-object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

```yaml
mx:
  adr: "decisions/adr-007-storage-strategy.md"
  ndr: "decisions/ndr-002-camelcase-naming.md"
  bdr: "decisions/bdr-012-launch-pricing.md"
```

```yaml
mx:
  adr:
    path: "decisions/adr-007-storage-strategy.md"
    date: 2026-03-15
    status: accepted
```

---

## 9. Migration fields

### 9.1 `movedFrom`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Previous file path before content was relocated. Used for redirect generation and link maintenance. The value SHOULD be the full relative path from the repository root. Tooling MAY use this field to generate redirects or update internal links automatically. SHOULD be paired with `movedDate`.

```yaml
mx:
  movedFrom: "datalake/knowledge/reference/field-definitions.md"
```

---

### 9.2 `movedDate`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

Date content was relocated. SHOULD be paired with `movedFrom` to provide a complete migration record.

```yaml
mx:
  movedDate: 2026-03-15
```

---

## 10. Conformance summary

| Field | Group | Level 1 (MUST) | Level 2 (SHOULD) | Level 3 (MAY) |
|-------|-------|:-:|:-:|:-:|
| `provenanceAuthor` | attribution | MUST | — | — |
| `provenancePublisher` | attribution | — | SHOULD | — |
| `provenanceOrigin` | attribution | — | SHOULD | — |
| `source` | attribution | — | — | MAY |
| `publisher` | attribution | — | — | MAY |
| `generate` | attribution | — | — | MAY |
| `reviewCycle` | quality | — | SHOULD | — |
| `accuracyCommitment` | quality | — | — | MAY |
| `correctionSla` | quality | — | — | MAY |
| `mxCompliance` | quality | — | — | MAY |
| `quality` | quality | — | — | MAY |
| `maintainedDate` | maintenance | — | SHOULD | — |
| `maintainedBy` | maintenance | — | — | MAY |
| `expires` | maintenance | — | — | MAY |
| `updateTriggers` | maintenance | — | — | MAY |
| `adr` | decisions | — | — | MAY |
| `ndr` | decisions | — | — | MAY |
| `bdr` | decisions | — | — | MAY |
| `movedFrom` | migration | — | — | MAY |
| `movedDate` | migration | — | — | MAY |

---

## 11. Security and privacy considerations

- The `provenanceAuthor` and `provenancePublisher` fields contain personally identifiable information. Implementations that publish metadata publicly SHOULD consider whether these values are appropriate for public exposure.
- The `publisher.contact` sub-field MAY contain email addresses or other contact information. Implementations SHOULD consider whether such values are appropriate for public exposure before publishing this metadata externally.
- The `provenanceOrigin` field declares the human-machine authorship balance. Publishers SHOULD declare this field honestly to maintain trust with consumers and agents.
- Decision record references (`adr`, `ndr`, `bdr`) MAY link to internal governance documents. Implementations SHOULD verify that referenced documents are accessible to the intended audience before publishing these links externally.
- The `generate` field contains instructions for content regeneration. Implementations SHOULD ensure that generation prompts do not expose sensitive business logic or proprietary processes in publicly accessible metadata.

---

## 12. References

### 12.1 Normative references

- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) — Key words for use in RFCs to indicate requirement levels
- [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) — Date and time format

### 12.2 Informative references

- [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — Web Content Accessibility Guidelines (referenced in quality triad and the conformance level model)
- [Schema.org](https://schema.org/) — Structured data vocabulary (referenced in semantic quality)
- [Schema.org Style Guide](https://schema.org/docs/styleguide.html) — Vocabulary naming conventions
- [Dublin Core DCMI Namespace](https://www.dublincore.org/specifications/dublin-core/dcmi-namespace/) — Provenance and stewardship metadata model

---

## 13. Minimum-viable provenance block (Informative)

A worked example an author can copy and adapt. The block sits in Zone 2 (the `mx:` object) of any document's frontmatter and extends the MX Core Metadata floor (governed by the **MX Core Metadata note**).

```yaml
mx:
  provenanceAuthor: "Tom Cranstoun"
  provenancePublisher:
    name: "Digital Domain Technologies Ltd"
    brand: "CogNovaMX"
    contact: "info@cognovamx.com"
  provenanceOrigin: "human-led, AI-assisted"
  reviewCycle: "quarterly"
  maintainedDate: 2026-05-07
```

This block declares: who wrote the original (`provenanceAuthor`), who publishes it under what brand (`provenancePublisher`), the human-machine balance of its authorship (`provenanceOrigin`), the review cadence (`reviewCycle`), and when it was last maintained (`maintainedDate`). Five fields, complete enough to verify provenance for most documents.

For higher trust requirements add `accuracyCommitment` and `correctionSla` from §6 (the quality triad); for full traceability add the decision-record references (`adr`, `ndr`, `bdr`) from §8; for migrated documents add `movedFrom` and `movedDate` from §9.

---

## 14. Common authoring mistakes (Informative)

Three shapes a fresh author often produces, each with the fix.

**Mistake 1: confusing identity with stewardship.**

```yaml
# WRONG — provenanceAuthor names the original creator, not the current maintainer
mx:
  provenanceAuthor: "Maxine"   # Maxine is the current maintainer, not the originator
```

`provenanceAuthor` is immutable identity, closely related to the `originator` field in MX Core Metadata §5.3. For ongoing maintenance, use `maintainedBy` (§7) or the `stewardship.steward` sub-key from MX Core Metadata §6.6.

**Mistake 2: claiming `provenanceOrigin: human-only` after AI-assisted authorship.**

```yaml
# WRONG — the document was edited with AI assistance
mx:
  provenanceOrigin: "human-only"
```

Declaring the human-machine balance honestly is part of what makes provenance verifiable. If an AI tool contributed to drafting, editing, summarising, or fact-checking the document, the value is not `human-only`. Use `human-led, AI-assisted` (or one of the other values defined in §5).

**Mistake 3: declaring `expires` without a review plan.**

```yaml
# WRONG — expires says "this document goes stale on a date" but reviewCycle is missing
mx:
  expires: 2026-12-31
```

`expires` (§7) marks an authoritative-content cutoff. A document that declares `expires` SHOULD also declare `reviewCycle` so that an author or steward knows when to re-validate the content before the cutoff. Otherwise the expiry date is arbitrary.

---

*End of MX Provenance note draft.*

---

## MX Temporal Stance note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-temporal-stance.md
**File:** `draft-temporal-stance.md`

# MX Temporal Stance note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 7 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

Many MX-aware documents have a **temporal stance**: a relationship between the prose they carry and the dates they describe. A regulatory analysis published before a law's application date reads correctly today and reads stale eighteen months later. A pricing document declares a price that holds until a specific date. An SLA quotes uptime targets relative to a contract anchor. A blog post marking the EU AI Act's application date is anchored to a date the legislator could shift.

Without a shared vocabulary for declaring temporal stance, every author solves the problem differently — some bake dates into prose, some compute "days until X" from JavaScript at render time, some rely on the reader to know which dates are real and which are anchors. The result is documents that drift silently from their intended truth-relative-to-time as the dates they describe move.

This note defines four fields — `temporalStance`, `temporalAnchors`, `temporalComputedFields`, `temporalProseGuidance` — that let a document declare its relationship to time machine-readably. A consumer (a render-time agent, a static-site builder, a verifier, a downstream summariser) can then compute date-derived values from anchors at fetch time, surface stale prose to the steward when an anchor moves, and explain the document's temporal contract without parsing the prose.

The fields live in Zone 2 (the `mx:` object) of any MX-aware document's frontmatter and apply equally to regulatory analyses, contracts, SLAs, compliance reports, pricing pages, and tech-trend pieces.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here.

### 2.1 Conformance levels

A document declaring a temporal stance SHALL satisfy:

- **Level 1 (Stance declared):** The document declares `temporalStance` with a value drawn from the controlled vocabulary in §4.1.
- **Level 2 (Anchored):** Level 1 plus, when `temporalStance: anchored`, every anchor referenced in the prose is declared in `temporalAnchors`.
- **Level 3 (Verifiable):** Level 2 plus `temporalComputedFields` declares every value in the prose computed from an anchor at render time, and `temporalProseGuidance` describes what a steward should change in the prose if any anchor moves.

A document not concerned with time MAY omit all four fields. A document declaring `temporalStance` other than `frozen` SHOULD declare at least Level 2.

### 2.2 Draft status

This is a draft note. Conformance levels and field semantics MAY change in response to community review. Implementations of this draft SHOULD note the draft version number they implemented against.

---

## 3. Scope

### 3.1 In scope

- The four temporal-stance fields and their semantics.
- The render-time and fetch-time obligations on consumers that resolve anchors.
- The prose-guidance fields stewards use to keep documents honest as anchors move.

### 3.2 Out of scope

- **Calendar systems and timezones.** Anchors are ISO 8601 dates ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)); time-of-day, timezone, and non-Gregorian calendars are beyond this note.
- **Versioning.** When an anchor moves materially, the document SHOULD be re-versioned per the MX Core Metadata note's `version` field; that note governs the lifecycle.
- **Display formatting.** How a render-time agent presents a computed value (e.g. "in 87 days" vs. "on 2 August 2026") is a presentation concern, not specified here.

### 3.3 Relationship to existing standards

This note relies on:

- [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) for date format.
- [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) for URI form when anchors reference external sources.

It builds on:

- The **MX Core Metadata note** for the Zone 2 (`mx:` object) frontmatter model and the `created` / `modified` / `version` lifecycle fields.
- The **MX Provenance note** for `expires` and `reviewCycle`, which declare lifecycle endpoints distinct from temporal stance.

This note adds vocabulary; it does not duplicate or override either dependency.

---

## 4. Field definitions

### 4.1 `temporalStance`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 1) for any document referring to dated events; MAY otherwise |
| **Valid values** | frozen, living, anchored |

**Definition:** Declares the document's relationship between its prose and the dates the prose describes. Three values:

- **`frozen`** — the prose reflects state at publication. Dates in the prose are historical record; they do not move when the underlying world moves. A retrospective, a historical study, a release-notes archive.
- **`living`** — the prose reflects state at fetch time. Dates and date-derived values are recomputed against the consumer's clock when the document is read. A status page, a "current state" report, a now-page.
- **`anchored`** — the prose contains values computed from declared anchors. When an anchor moves, the document's intended meaning moves with it; stewards re-render or re-author per `temporalProseGuidance`. Regulatory analyses, contract terms, SLAs, compliance reports.

```yaml
mx:
  temporalStance: anchored
```

- A document declaring `temporalStance: anchored` SHOULD declare `temporalAnchors`.
- A document declaring `temporalStance: living` MAY omit anchors; a render-time agent uses the consumer's clock as the implicit anchor.
- A document declaring `temporalStance: frozen` MUST NOT declare anchors that move; if a date the prose mentions is genuinely an anchor (likely to move), the stance is not `frozen`.

### 4.2 `temporalAnchors`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 2) when `temporalStance: anchored`; MAY otherwise |

**Definition:** Named date anchors the document's prose depends on. Each entry pairs a stable identifier with the anchor's current value and a short human description of what the anchor is. The identifier is the key by which `temporalComputedFields` and `temporalProseGuidance` reference the anchor.

**Sub-keys** (per anchor entry):

| Sub-key | Type | Definition |
|---------|------|-----------|
| `date` | string (ISO 8601) | Current value of the anchor. MUST be present. |
| `description` | string | One-line explanation of what the anchor is, including the source if external (a law, a contract clause, a release calendar). |
| `source` | string (URL) | Optional canonical URL where the anchor's authoritative value is published. |

```yaml
mx:
  temporalAnchors:
    eu-ai-act-application:
      date: "2026-08-02"
      description: "EU AI Act provisions for general-purpose AI become applicable."
      source: "https://eur-lex.europa.eu/eli/reg/2024/1689"
    contract-renewal:
      date: "2027-04-30"
      description: "Master service agreement renewal date."
```

- Anchor identifiers SHOULD be lowercase kebab-case and stable across versions of the document.
- An anchor whose `date` value changes is a substantive editorial event; the document's `modified` date MUST be bumped, and the steward SHOULD review against `temporalProseGuidance` (§4.4).

### 4.3 `temporalComputedFields`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 2 (mx:) |
| **Conformance** | MAY (Level 3) |

**Definition:** Fields whose values are computed from anchors at render time. Each entry pairs a field name with an expression naming the anchor and the computation. Render-time agents MUST NOT cache the computed value beyond a single render; the value is by definition relative to the moment of fetch.

**Sub-keys** (per computed-field entry):

| Sub-key | Type | Definition |
|---------|------|-----------|
| `from` | string | Anchor identifier (must match a key in `temporalAnchors` or the literal `now`). |
| `compute` | string | Computation: one of `daysUntil`, `daysSince`, `monthsUntil`, `monthsSince`, `quartersUntil`, `quartersSince`, `dateValue` (returns the anchor date verbatim). |
| `format` | string | Optional presentation hint (e.g. `integer`, `iso-date`, `human-readable`). Implementations MAY ignore. |

```yaml
mx:
  temporalComputedFields:
    daysUntilApplication:
      from: eu-ai-act-application
      compute: daysUntil
      format: integer
    contractMonthsRemaining:
      from: contract-renewal
      compute: monthsUntil
      format: integer
```

- Render-time agents MUST treat unknown anchor identifiers as a render failure rather than substituting a default.
- A field name in `temporalComputedFields` SHOULD be referenced in the document's prose using a templating convention agreed with the publishing toolchain (this note does not mandate a template syntax).

### 4.4 `temporalProseGuidance`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 2 (mx:) |
| **Conformance** | SHOULD (Level 3) for documents declaring `temporalStance: anchored`; MAY otherwise |

**Definition:** Author-supplied notes telling future agents (human or machine) how to update the prose when an anchor moves. Each entry pairs an anchor identifier with prose-update instructions. The field is the bridge between the structural temporal-stance vocabulary and the unstructured prose that depends on it.

**Sub-keys** (per anchor entry):

| Sub-key | Type | Definition |
|---------|------|-----------|
| `onMove` | string | What a steward should review or rewrite in the prose if this anchor's date changes. |
| `affectedSections` | array | Optional list of section anchors (URL fragments) that depend on the anchor. |
| `softCutoff` | boolean | When `true`, a small move in the anchor (within a configurable tolerance) requires no prose update; only a material move does. Tools SHOULD surface what "material" means with a one-line description in `onMove`. |

```yaml
mx:
  temporalProseGuidance:
    eu-ai-act-application:
      onMove: "Re-read §3 'What changes on day one'. If the anchor moves more than 30 days, re-write the run-up timetable."
      affectedSections: ["#what-changes-on-day-one", "#run-up-timetable"]
      softCutoff: true
    contract-renewal:
      onMove: "Update the renewal callout in §1; reissue if the new date is more than 90 days away."
      softCutoff: false
```

- A document declaring `temporalProseGuidance` SHOULD list every anchor whose movement could leave the prose factually wrong.
- Anchors whose movement is purely cosmetic (the prose just quotes the date) MAY be omitted from the guidance.

---

## 5. Implementation guidance (Informative)

*This section is informative; it is not a normative part of the note.*

### 5.1 Static-site builders

A static-site builder reading an `anchored` document SHOULD resolve `temporalComputedFields` against the build clock and either:

- Inline the computed values into the rendered HTML at build time (and re-build when an anchor moves), or
- Emit the values as `data-mx-temporal-*` attributes on the relevant elements so a client-side renderer can recompute against the reader's clock without re-fetching the document.

The choice is a presentation decision, not a conformance one. Both approaches are conformant.

### 5.2 Runtime agents

A render-time agent reading a `living` document recomputes against the agent's clock at fetch time. A render-time agent reading an `anchored` document recomputes against the anchor `date` values declared in the document, not the agent's clock — the anchor is authoritative even if the agent's clock is later.

### 5.3 Stewardship loop

A steward editing a document with declared anchors SHOULD:

1. Update the anchor's `date` in `temporalAnchors`.
2. Bump `modified` in Zone 1.
3. Walk `temporalProseGuidance` for the moved anchor and either rewrite the affected sections or, if the move is within `softCutoff`, leave them.
4. If any computed-field value materially changes, bump `version` per the MX Core Metadata note's `version` field and re-sign per the MX Contract Fingerprinting and Signing note if the document is signed.

---

## 6. Security and privacy considerations

- A document whose anchors point to external sources discloses what dates the publisher considers load-bearing. Authors handling commercially sensitive timelines SHOULD consider whether the anchor identifiers and source URLs are appropriate for public exposure.
- A render-time agent that fetches an anchor's `source` URL to verify the current value introduces a network call and a potential privacy leak (the publisher of the source learns who is verifying). Agents SHOULD honour the consumer's privacy expectations and SHOULD NOT issue verification fetches without consent.
- A `living` document's computed values move every fetch. Verifiers signing such a document MUST exclude `temporalComputedFields` values from the contract surface (the anchor itself MAY be in the contract; the values derived from it at render time are by definition outside the signature).

---

## 7. IANA considerations

This note proposes no new IANA registrations.

---

## 8. References

### 8.1 Normative

- [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) — Key words for use in RFCs.
- [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) — Ambiguity of uppercase vs lowercase in RFC 2119 key words.
- [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) — Date and time format.
- [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) — Uniform Resource Identifier generic syntax.

### 8.2 Informative

- **MX Core Metadata note** — Zone 2 frontmatter model and the `version` lifecycle this note builds on.
- **MX Provenance note** — `expires` and `reviewCycle` fields, distinct from temporal stance.
- **MX Contract Fingerprinting and Signing note** — signing model that excludes `temporalComputedFields` values from the contract surface.

---

## 9. Author quickstart (Informative)

A minimum-viable temporal-stance block for a regulatory blog post anchored to the EU AI Act application date.

```yaml
---
title: "What changes on day one of the EU AI Act"
description: "A run-up reading of the EU AI Act, anchored to the application date for general-purpose AI."
originator: "Tom Cranstoun"
created: 2026-05-07
modified: 2026-05-07
version: "1.0"
type: info-doc
mx:
  status: published
  canonicalUri: https://example.org/blog/eu-ai-act-day-one
  summary: "What the EU AI Act changes on day one for general-purpose AI providers and users."
  conformsTo: [https://mx.allabout.network/cog.html]
  trainingDataPolicy: "Permitted with attribution."
  temporalStance: anchored
  temporalAnchors:
    eu-ai-act-application:
      date: "2026-08-02"
      description: "EU AI Act provisions for general-purpose AI become applicable."
      source: "https://eur-lex.europa.eu/eli/reg/2024/1689"
  temporalComputedFields:
    daysUntilApplication:
      from: eu-ai-act-application
      compute: daysUntil
      format: integer
  temporalProseGuidance:
    eu-ai-act-application:
      onMove: "Re-read the run-up timetable in §3. If the anchor moves more than 30 days, rewrite it."
      affectedSections: ["#run-up-timetable"]
      softCutoff: true
---
```

---

## 10. Common authoring mistakes (Informative)

Three shapes a fresh author often produces, each with the fix.

**Mistake 1: declaring `temporalStance: frozen` on a document with anchors.**

```yaml
# WRONG — frozen documents do not have anchors that move
mx:
  temporalStance: frozen
  temporalAnchors:
    contract-renewal: { date: "2027-04-30", description: "..." }
```

If the document depends on a date that could move, the stance is `anchored`, not `frozen` (§4.1). Use `frozen` only for retrospectives where every date is historical record.

**Mistake 2: missing `temporalProseGuidance` on an `anchored` document with prose dependencies.**

```yaml
# WRONG — anchors declared, but no guidance on what to update if they move
mx:
  temporalStance: anchored
  temporalAnchors:
    eu-ai-act-application: { date: "2026-08-02", description: "..." }
```

Without `temporalProseGuidance`, a future steward facing a moved anchor has no instructions and the document drifts silently. Add at minimum an `onMove` line per anchor.

**Mistake 3: signing `temporalComputedFields` values into the contract.**

```yaml
# WRONG — daysUntilApplication moves every render; a signature over it is invalidated immediately
contractFields:
  - title
  - schema
  - daysUntilApplication
```

`temporalComputedFields` values are by definition outside the signature (§6). The anchor itself (`temporalAnchors.eu-ai-act-application`) MAY be in the contract; the rendered value is not.

---

*End of MX Temporal Stance note draft.*

---

## MX Carrier Formats note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-carrier-formats.md
**File:** `draft-carrier-formats.md`

# MX Carrier Formats note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 27 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies how MX metadata is carried across file formats. It covers two layers:

1. **Carrier mechanisms** — the syntactic envelope each file format uses to host MX metadata: YAML frontmatter for markdown, `<meta>` tags for HTML, JSDoc comments for JavaScript, CSS comments, shell comment blocks, XMP for media, sidecar files, and SQL comment blocks.
2. **Code-specific provenance vocabulary** — a minimum viable set of fields specific to source code as a document and not covered by the universal identity vocabulary.

The note also defines the `mx:*` identity fields used by carriers that do not have YAML frontmatter (HTML, JavaScript, CSS).

What the code does — function signatures, API surfaces, test metadata, type systems, invariants, behaviour — is explicitly out of scope. Each language already has its own convention for this (JSDoc, Python docstrings, Doxygen, rustdoc, godoc). MX does not duplicate them.

Database-content vocabulary and media-content vocabulary are also out of scope; this note specifies only how a document of either kind carries the universal MX identity fields. The MX framework reuses existing standards for the content layer:

- **Databases** — defer to [DCAT v3](https://www.w3.org/TR/vocab-dcat-3/) (datasets, distributions, catalogues), [CSVW](https://www.w3.org/TR/tabular-metadata/) (tabular schemas, columns, keys), and [Dublin Core](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/) (dataset identity).
- **Media** — defer to [Schema.org](https://schema.org/) (`ImageObject`, `VideoObject`, `AudioObject`, `CreativeWork`, `license`) and the native embedded-metadata standards (EXIF, IPTC, XMP, ID3).
- **Code behaviour** — defer to the language's own documentation convention.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of this draft set). That pattern governs the structural template for every field — heading, property table, definition prose, example — and is binding on this note. This note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

This note defines three conformance levels (modelled on the [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level A/AA/AAA pattern):

| Level | Name | Requirement |
|-------|------|-------------|
| Level 1 | **MX Core** | Universal identity fields present (`title`, `author`, `created`, `description`); the carrier syntax for the file's format is used correctly. |
| Level 1 / Level 2 | Zone 1b OKF surface MUST be present at all levels: `type`, `tags`, and `resource` (when applicable) are required unconditionally. MX is an OKF implementation; these fields are not optional extras — they are the OKF layer every external tool reads. Zone 2 operational fields (`status`, `license`, etc.) are added per the MX conformance ladder. |
| Level 3 | **MX Complete** | Adds Level 2 plus the code-specific provenance fields in §5 where they apply, and any `MAY`-level identity fields. |

A document claiming conformance at a given level MUST satisfy all requirements at that level and all lower levels.

### 2.2 Selective adoption

An implementation is **carrier-conformant at Level N** if, for every artefact it emits, it satisfies the Level-N requirements for the artefact's carrier format. Implementations MAY claim conformance for a subset of carriers (e.g. markdown and HTML only).

### 2.3 Baseline identity contract

Every MX-aware document, regardless of carrier, carries the universal Level 1 identity contract:

- `title` — REQUIRED
- `author` — REQUIRED
- `created` — REQUIRED (ISO 8601 date format YYYY-MM-DD)
- `description` — RECOMMENDED

The carrier-specific syntax for these fields is defined in §3.

### 2.4 Database and media content conformance

For dataset, table, column, image, video, and audio content metadata, implementations look to the external standards cited in §1. MX makes no conformance claim for content vocabularies beyond the carrier mechanisms in §3.

### 2.5 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the field definitions, conformance requirements, and normative rules in this note are working drafts — stable enough to build against, expected to evolve through review.

---

## 3. Carrier format mappings

This section defines how each supported file format carries MX metadata.

### 3.1 Markdown — YAML frontmatter

| Property | Value |
|----------|-------|
| **File types** | `.md`, `.mx.yaml.md` |
| **Carrier mechanism** | YAML frontmatter between `---` delimiters |
| **Field naming** | camelCase (operational fields under `mx:` object) |
| **Conformance** | MUST (Level 1) for all markdown-based MX documents |

The primary carrier format. All MX-aware markdown documents carry metadata in YAML frontmatter using a three-zone model. MX is an OKF implementation; Zone 1b fields are required unconditionally so any OKF tool reads MX files without adaptation: Zone 1a (top-level) for document identity (`title`, `description`, `author`, `created`, `modified`, `version`); Zone 1b (top-level) for the OKF-reserved surface (`type` MUST, `tags` MUST, `resource` MUST when describing an external asset); Zone 2 (under the `mx:` object) for MX-operational fields. Implementations MUST NOT place Zone 1a or Zone 1b fields inside the `mx:` object, and MUST NOT place Zone 2 fields at the top level.

**Example:**

```yaml
---
title: "Document Title"
description: "Brief summary"
author: "Author Name"
created: 2026-04-02
modified: 2026-04-16
version: "1.0"
type: guide
tags: [metadata, example]

mx:
  status: active
  canonicalUri: https://example.com/docs/title
---
```

Extension fields appear inside the `mx:` object alongside standard operational fields. OKF-reserved fields (`type`, `tags`, `resource`) remain at the top level.

---

### 3.2 HTML — `<meta>` tags

| Property | Value |
|----------|-------|
| **File types** | `.html` |
| **Carrier mechanism** | `<meta name="mx:*">` tags in `<head>`, `data-mx-*` attributes on elements |
| **Field naming** | kebab-case with `mx:` prefix |
| **Conformance** | MUST (Level 2) for HTML documents claiming MX conformance |
| **Required fields** | `description` (standard HTML meta) + `author` (standard HTML meta) + the four MUST-at-Level-2 mx: meta tags listed below |

HTML documents carry MX metadata using `<meta>` tags in the document `<head>`. The `mx:` prefix in the `name` attribute distinguishes MX metadata from standard HTML meta tags.

#### 3.2.1 Naming and conversion (Normative)

The conversion from a YAML field name to its HTML carrier form is binding:

1. Convert the camelCase YAML name to kebab-case.
2. Prepend `mx:` to the kebab-case form.
3. Place the value in a `<meta name="…" content="…">` tag inside the document's `<head>`.

For example, `mx.canonicalUri: https://example.org/x` becomes `<meta name="mx:canonical-uri" content="https://example.org/x">`. This conversion is the same in both directions: a verifier reading an HTML carrier converts `mx:canonical-uri` back to `canonicalUri` to compare with frontmatter equivalents.

The MX Extensions note §7.1 provides the same table as an informative summary; this subsection is the binding form. If a row in that summary disagrees with this subsection, this subsection wins.

#### 3.2.2 Required mx: meta tags at Level 2 (Normative)

An HTML document claiming MX Standard (Level 2) MUST declare the four MUST-at-Level-2 fields from MX Core Metadata note §7a as `mx:` meta tags. Each tag MUST be present in `<head>`; absence of any one places the document at Level 1, not Level 2.

| YAML field | HTML meta tag | Value semantics (cross-reference) |
|------------|---------------|-------------------------------------|
| `mx.canonicalUri` | `<meta name="mx:canonical-uri" content="…">` | URI of the canonical version of this document. MUST agree with `<link rel="canonical">` if both are present (MX Core Metadata §7a.1). |
| `mx.summary` | `<meta name="mx:summary" content="…">` | One-to-two-sentence machine-summary; lets agents decide relevance without reading the body. |
| `mx.conformsTo` | `<meta name="mx:conforms-to" content="…">` | Comma-separated list of standards URIs the document conforms to (`mx.conformsTo` is an array; serialise as comma-separated string). |
| `mx.trainingDataPolicy` | `<meta name="mx:training-data-policy" content="…">` | Whether the document may be included in AI training corpora. |

**Worked example (Normative):**

```html
<head>
  <title>Auth design notes</title>
  <link rel="canonical" href="https://example.org/blog/auth-design">
  <meta name="description" content="Working notes on the authentication redesign.">
  <meta name="author" content="Tom Cranstoun">

  <!-- The four MUST-at-Level-2 mx: tags -->
  <meta name="mx:canonical-uri" content="https://example.org/blog/auth-design">
  <meta name="mx:summary" content="Working notes on the authentication redesign — what we kept, what we replaced, why.">
  <meta name="mx:conforms-to" content="https://mx.allabout.network/cog.html">
  <meta name="mx:training-data-policy" content="Permitted with attribution.">

  <!-- Other operational fields -->
  <meta name="mx:status" content="published">
  <meta name="mx:content-type" content="info-doc">
</head>
```

#### 3.2.3 Other rules

- Standard HTML meta tags (`description`, `author`) MUST use their native HTML names without the `mx:` prefix.
- MX-specific fields MUST use the `mx:` prefix in the `name` attribute.
- Array values MUST be serialised as comma-separated strings.
- `data-mx-*` attributes MAY be used on body elements for element-level MX metadata.
- The values of `<link rel="canonical">` and `<meta name="mx:canonical-uri">` MUST agree when both are present, per MX Core Metadata §7a.1; verifiers MAY treat either as authoritative.

---

### 3.3 JavaScript — JSDoc comments

| Property | Value |
|----------|-------|
| **File types** | `.js`, `.mjs`, `.ts` |
| **Carrier mechanism** | JSDoc `/** */` block with `@mx:` tags |
| **Field naming** | kebab-case with `@mx:` tag prefix |
| **Conformance** | MUST (Level 2) for JavaScript documents claiming MX conformance |
| **Required fields** | `@description` + `@version`/`@author` + at least one `@mx:*` tag |

JavaScript files carry MX metadata in a JSDoc comment block at the top of the file. MX-specific fields use the `@mx:` tag prefix.

**Example:**

```javascript
/**
 * @description MX validation utility
 * @version 1.0
 * @author Tom Cranstoun
 * @mx:status active
 * @mx:content-type utility
 * @mx:runtime node
 * @mx:tags validation, metadata
 */
```

- Standard JSDoc tags (`@description`, `@version`, `@author`) MUST use their native JSDoc names.
- MX-specific fields MUST use the `@mx:` prefix.
- The JSDoc block SHOULD appear at the top of the file, before any code.

---

### 3.4 CSS — comments

| Property | Value |
|----------|-------|
| **File types** | `.css` |
| **Carrier mechanism** | CSS comment `/* */` block with `@mx:` tags |
| **Field naming** | kebab-case with `@mx:` tag prefix |
| **Conformance** | MUST (Level 2) for CSS documents claiming MX conformance |
| **Required fields** | `@description` + `@version`/`@author` + at least one `@mx:*` tag |

CSS files carry MX metadata in a comment block at the top of the file. MX-specific fields use the `@mx:` tag prefix.

**Example:**

```css
/*
 * @description Global layout styles
 * @version 2.0
 * @author Tom Cranstoun
 * @mx:status active
 * @mx:type utility
 * @mx:tags layout, responsive
 */
```

The metadata comment block SHOULD appear at the top of the file, before any rules.

---

### 3.5 Image — EXIF/XMP metadata

| Property | Value |
|----------|-------|
| **File types** | `.png`, `.jpg`, `.webp`, `.svg` |
| **Carrier mechanism** | EXIF/XMP metadata with `mx:` namespace |
| **Field naming** | `mx:` namespace prefix, original case preserved |
| **Conformance** | MAY (Level 3) |

Image files carry MX identity metadata in EXIF/XMP metadata blocks using the `mx:` XML namespace. When XMP embedding is not practical, a sidecar file (`.mx.yaml`) SHOULD be used instead. Image-content vocabulary (subject, alt text, EXIF camera fields) is governed by EXIF/IPTC/XMP/Schema.org and is not redefined here.

**Example (XMP):**

```xml
<rdf:Description xmlns:mx="https://allabout.network/ns/mx/1.0">
  <mx:type>illustration</mx:type>
  <mx:status>active</mx:status>
</rdf:Description>
```

The MX XMP namespace URI is `https://allabout.network/ns/mx/1.0`.

---

### 3.6 Shell scripts — comment block

| Property | Value |
|----------|-------|
| **File types** | `.sh`, `.bash`, `.zsh` |
| **Carrier mechanism** | `# ---` YAML block with `#` prefix on each line |
| **Field naming** | camelCase in `# key: value` lines |
| **Conformance** | MUST (Level 2) for shell scripts claiming MX conformance |
| **Required fields** | `title`, `description`, `status`, `author` |

Shell scripts carry MX metadata in a comment block using `# ---` delimiters, with each YAML line prefixed by `#`.

**Example:**

```bash
#!/bin/bash
# ---
# title: "Build and deploy"
# description: "Builds site artefacts and deploys to Cloudflare"
# author: "Tom Cranstoun"
# type: script
# status: active
# ---
```

- The metadata block MUST start and end with `# ---`.
- Field names use camelCase, matching YAML conventions.
- The metadata block SHOULD appear immediately after the shebang line.

---

### 3.7 `.mx.yaml` — media sidecar

| Property | Value |
|----------|-------|
| **File types** | `.mx.yaml` (placed alongside a media asset) |
| **Carrier mechanism** | Standalone YAML file |
| **Field naming** | camelCase |
| **Conformance** | MAY (Level 3) |

A sidecar metadata file placed alongside a media asset (image, video, audio, binary) that cannot carry embedded metadata. The sidecar file name matches the asset file name with `.mx.yaml` appended.

**Example (for `hero-image.webp`):**

File: `hero-image.webp.mx.yaml`

```yaml
title: "Hero banner image"
description: "Full-width hero image for the landing page"
author: "Tom Cranstoun"
created: 2026-04-02
modified: 2026-04-16
type: image
tags: [hero, banner, landing]

mx:
  status: active
```

The sidecar file MUST use the three-zone model and the file name MUST match the asset file name with `.mx.yaml` appended.

---

### 3.8 `mx.yaml` — code repository root

| Property | Value |
|----------|-------|
| **File types** | `mx.yaml` (at repository root) |
| **Carrier mechanism** | Standalone YAML file |
| **Field naming** | camelCase |
| **Conformance** | MAY (Level 3) |

A repository-level metadata file placed at the root of a code repository. Provides MX metadata for the repository as a whole.

**Example:**

```yaml
title: "MX Hub"
description: "Central hub for Machine Experience development"
author: "Tom Cranstoun"
created: 2026-01-15
modified: 2026-04-16
type: repository
tags: [hub, mx, repository]

mx:
  status: active
  domain: machine-experience
```

---

### 3.9 Database sidecars and inline SQL

| Property | Value |
|----------|-------|
| **File types** | `mx.database.yaml` (sidecar), `.sql` (inline) |
| **Carrier mechanism** | Standalone YAML sidecar or `-- @mx ... -- @mx:end` comment blocks in SQL |
| **Field naming** | camelCase |
| **Conformance** | MAY (Level 3) |

Database schemas carry MX identity metadata either in a standalone sidecar file (`mx.database.yaml`) or in inline SQL comments using the `-- @mx` / `-- @mx:end` delimiters. Database-content vocabulary (table relationships, column types, dataset semantics) is governed by DCAT, CSVW, and Dublin Core and is not redefined here.

**Example (sidecar):**

File: `mx.database.yaml`

```yaml
title: "Customer database schema"
description: "Schema metadata for the customer CRM database"
author: "Tom Cranstoun"

type: database-schema
mx:
  status: active
  domain: crm
```

**Example (inline SQL):**

```sql
-- @mx
-- title: Customer contacts table
-- description: Primary contact records for CRM
-- type: database-table
-- status: active
-- @mx:end
CREATE TABLE contacts (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL
);
```

- Inline SQL metadata blocks MUST start with `-- @mx` and end with `-- @mx:end`.
- Each field line within the block MUST be prefixed with `--`.
- Field names use camelCase.

---

### 3.10 Field-form precedence (Normative)

A single MX field can appear in more than one form on the same artefact: a markdown file with a YAML frontmatter; an HTML page with both YAML frontmatter and `<meta name="mx:*">` tags; a tagged PDF carrying YAML in its document and the same fields in an XMP packet; a cog carrying both a magic-header HTML comment and a `cogHeader` frontmatter object. When multiple forms declare the same field, implementations MUST resolve them using the precedence below:

1. **YAML frontmatter** is highest precedence. When a field is declared in YAML frontmatter, the YAML value is authoritative for that field on that artefact.
2. **Carrier-specific embedded form** is next. This includes XMP for media (§3.5), the magic-header HTML comment for cogs (MX Cogs note §4), and any other format-native packet whose declarations are intended as authoritative within that carrier.
3. **HTML `<meta>` tags** and equivalent declarative tags (JSDoc `@mx:`, CSS `@mx:` comment, SQL `-- @mx`) are next. Their values are authoritative when no higher form declares the same field on the same artefact.
4. **Inferred values** (defaulted by the validator, computed from other fields, derived from external context) are lowest. A higher form always wins over an inferred value.

When a field is declared in two or more forms on the same artefact, the values MUST agree. Disagreement is a conformance failure: tools cannot reconcile two contradictory authoritative declarations and SHOULD surface the conflict rather than silently picking one. The most common collision in practice is `<link rel="canonical">` versus `<meta name="mx:canonical-uri">` on the same HTML page (see §3.2.2 and MX Core Metadata §7a.1) — those two MUST agree.

**Author's checklist when more than one form is in play:**

- Pick the highest-precedence form available for the carrier (YAML if the carrier supports it; otherwise the carrier-specific embedded form; otherwise `<meta>` tags).
- If a second form is declared (perhaps because tooling needed both), copy the value from the higher-precedence form rather than drafting it independently. Drift between forms is a conformance failure waiting to happen.
- Verifiers SHOULD report the resolved precedence path so a downstream consumer can audit which form they relied on.

---

## 4. Non-YAML identity fields

The following fields provide MX identity and classification metadata in carrier formats that do not use YAML frontmatter (HTML, JavaScript, CSS, image XMP). All fields use the `mx:` namespace prefix in their respective carrier contexts.

When a field has a YAML equivalent (e.g. `title`, `type`, `tags`), the YAML form is used in YAML-bearing carriers and the `mx:*` form is used elsewhere. The two are aliases for the same semantic field. OKF-reserved Zone 1b fields (`type`, `tags`, `resource`) use no `mx:` prefix in non-YAML carriers — they are expressed as bare attributes following their OKF names.

### 4.1 `mx:name`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | html, js, css |
| **Conformance** | SHOULD (Level 2) |

Cog name, equivalent to `title` in YAML. Provides a machine-readable identifier in carrier formats that lack YAML frontmatter.

```html
<meta name="mx:name" content="validation-utility">
```

```javascript
/** @mx:name validation-utility */
```

### 4.2 `mx:version`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | html, js, css |
| **Conformance** | SHOULD (Level 2) |

Version string, equivalent to `version` in YAML.

```html
<meta name="mx:version" content="2.0">
```

```css
/* @mx:version 2.0 */
```

### 4.3 `mx:type`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | html |
| **Conformance** | SHOULD (Level 2) |

Document type classification. Carries the same vocabulary as the Zone 1b `type` field in YAML frontmatter. In HTML, OKF-reserved Zone 1b fields use no `mx:` prefix — the bare `type` name is used directly, matching their top-level YAML position.

```html
<meta name="type" content="guide">
```

### 4.4 `mx:purpose`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | js, css |
| **Conformance** | MAY (Level 3) |

Why this file exists. Equivalent to `purpose` in YAML.

```javascript
/** @mx:purpose validation */
```

```css
/* @mx:purpose layout */
```

### 4.5 `mx:audience`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | js, css |
| **Conformance** | MAY (Level 3) |

Intended readership. Equivalent to `audience` in YAML. Array values are expressed as a comma-separated string.

```javascript
/** @mx:audience developers, agents */
```

### 4.6 `mx:stability`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | js, css |
| **Conformance** | MAY (Level 3) |
| **Valid values** | stable, evolving, experimental, deprecated, archived |

Stability level. Communicates how reliable this file's interface is for external consumers.

- `stable` — interface is fixed; breaking changes require a major version bump.
- `evolving` — interface may change; consumers should pin versions.
- `experimental` — interface is subject to significant change without notice.
- `deprecated` — interface is scheduled for removal; consumers should migrate.
- `archived` — interface is no longer maintained.

```javascript
/** @mx:stability stable */
```

### 4.7 `mx:category`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | html, js, css |
| **Conformance** | MAY (Level 3) |

Cog category, equivalent to `category` in YAML. Determines registry grouping in non-YAML carrier formats.

```html
<meta name="mx:category" content="mx-tool">
```

### 4.8 `mx:tags`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | html, js, css |
| **Conformance** | MAY (Level 3) |

Discovery keywords as a comma-separated string. Equivalent to `tags` (array) in YAML. Values SHOULD be lowercase strings.

```html
<meta name="mx:tags" content="validation, metadata, utility">
```

### 4.9 `mx:buildsOn`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | js, css |
| **Conformance** | MAY (Level 3) |

Context dependencies as a comma-separated list of cog names. Equivalent to `buildsOn` (array) in YAML. Field names use camelCase in every carrier (per NDR-02); the carrier syntax determines only how the value is encoded, not how the name is spelled.

```javascript
/** @mx:buildsOn fields, cog-unified-spec */
```

### 4.10 `mx:documentedIn`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | js, css |
| **Conformance** | MAY (Level 3) |

Path to companion documentation. Links a code file to its narrative documentation.

```javascript
/** @mx:documentedIn ../docs/validation-guide.md */
```

### 4.11 `mx:contextProvides`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Profile** | js, css |
| **Conformance** | MAY (Level 3) |

What context this file provides to agents. Declares the knowledge or capability an agent gains by reading this file.

```javascript
/** @mx:contextProvides Field validation rules and error message templates */
```

---

## 5. Code-specific provenance vocabulary

This section adds two fields specific to source code as a document. They are not covered by the universal identity vocabulary or by the language's own documentation convention.

### 5.1 Fields

| Field | Type | Required | Purpose |
|-------|------|----------|---------|
| `sourceRepo` | string | OPTIONAL | URL or path of the source-control repository that holds this code file's authoritative history. Aligns with [Schema.org `codeRepository`](https://schema.org/codeRepository). |
| `derivedFromCommit` | string | OPTIONAL | Version-control commit identifier (typically a git SHA) that this artefact was derived from. Pairs with a generic `derivedFrom` provenance pointer to add commit-level specificity. |

Every other concern that a wider draft might cover — function annotations, API surface, test metadata, class invariants, dependency declarations, runtime config, build conventions — is either out of scope entirely (deferred to the language convention) or handled generically by universal identity fields.

### 5.2 Carrier syntax

Code carriers use the native metadata mechanism of their file format. Field names are identical across all carriers; only the host syntax changes.

| Carrier | Native mechanism | Example |
|---------|------------------|---------|
| JavaScript / TypeScript | JSDoc comments | `@mx:sourceRepo https://github.com/example/repo` |
| CSS | CSS block comments | `/* @mx:sourceRepo https://github.com/example/repo */` |
| Shell | Shell comment block | `# sourceRepo: https://github.com/example/repo` (after shebang) |
| SQL | SQL comment block | `-- @mx sourceRepo: https://github.com/example/repo` |
| Any | YAML frontmatter in markdown files | `sourceRepo: https://github.com/example/repo` |

A JavaScript file declaring `@mx:sourceRepo` and a markdown file with `sourceRepo:` in its YAML frontmatter carry the same semantic value.

### 5.3 Profile

This note declares a single profile for code: `code`. An implementation handling code artefacts applies the `code` profile's fields in addition to the universal identity fields. There are no per-language sub-profiles — the vocabulary is language-agnostic.

---

## 6. Vendor extensions

Carrier formats accept vendor extension fields under a three-level namespace policy:

- **Standard** (no prefix): the universal identity vocabulary plus the fields in this note.
- **Vendor public** (`x-<vendor>-` prefix): vendor-specific carrier-format additions, openly published.
- **Vendor private** (`x-<vendor>-p-` prefix): vendor-specific additions, obfuscated or registry-decoded.

Implementations MUST NOT add a prefix to standard fields, and MUST NOT use `x-` prefixes for fields that already belong to the standard vocabulary.

The detailed namespace policy (governance, prefix-parsing rules, registration process) is specified in a separate note covering MX extensions.

---

## 7. Out of scope

This note is scoped to carrier mechanisms and the small code-specific provenance vocabulary. The following concerns are explicitly out of scope:

- **Function-level annotations** (`pure`, `idempotent`, `complexity`, `throws`, `returns`, `param`) — defer to JSDoc, Python docstring convention, Doxygen, rustdoc, godoc.
- **API surface specification** (HTTP method, path, auth, rate limits, cache semantics) — defer to [OpenAPI](https://www.openapis.org/).
- **Test metadata** (test type, coverage targets, fixtures) — defer to test framework conventions.
- **Class-level annotations** (design pattern, thread-safety, invariants) — defer to language convention and code reviews.
- **Dependency vocabulary** (purpose, criticality, upgrade policy, alternatives considered) — defer to package manifests (`package.json`, `pyproject.toml`, `Cargo.toml`) and Architecture Decision Records.
- **Runtime configuration** (interpreter, language version, framework versions) — defer to native config (`.node-version`, `.tool-versions`, shebang lines, package manifests).
- **Coding conventions** (style, testing conventions, documentation conventions) — defer to linter configs and community style guides.
- **Inline code annotations** (`mx:begin`, `mx:end`, `mx:sensitive`, `mx:intentional`, `mx:todo`, `mx:ai`) — each language already has its own TODO-comment and annotation conventions.
- **Database content vocabulary** (table relationships, column types, dataset semantics) — defer to DCAT v3, CSVW, Dublin Core.
- **Image content vocabulary** (subject, alt text, EXIF camera fields) — defer to EXIF, IPTC, XMP, Schema.org.
- **Audio/video content vocabulary** (duration, bitrate, captions, chapters) — defer to ID3, XMP, Schema.org.
- **Document identity field semantics** (what `title`, `author`, `created`, `description` mean) — governed by the MX Core Metadata note.
- **Cog file format internals** (the `.cog.md` body grammar, content blocks) — governed by the MX Cogs note.

If an implementation needs any of these, it uses the relevant external convention or sibling note. This note does not duplicate them.

---

## 8. Relationship to existing standards

MX is explicit about deferring to established vocabularies:

- **JSDoc / TSDoc / Python docstrings / Doxygen / rustdoc / godoc** — code-level documentation is each language's own convention.
- **OpenAPI** — full API surface specification.
- **Package manifests** (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`) — dependency declarations.
- **Dublin Core / Schema.org** — generic metadata (dates, rights, formats, display names).
- **Test framework conventions** — unit/integration/e2e classification, coverage targets, fixtures.
- **DCAT / CSVW** — dataset and tabular data metadata.
- **EXIF / IPTC / XMP / ID3** — embedded media metadata.
- **HTML `<meta>` standard** — base mechanism for `<meta name="mx:*">` carriers.
- **XMP namespace mechanism** — base mechanism for the `mx:` XMP namespace at `https://allabout.network/ns/mx/1.0`.

---

## 9. References

### 9.1 Normative references

- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) — Key words for use in RFCs to indicate requirement levels

### 9.2 Informative references — external standards MX defers to

- [DCAT v3](https://www.w3.org/TR/vocab-dcat-3/) — datasets and data catalogues
- [CSVW](https://www.w3.org/TR/tabular-metadata/) — tabular data schemas
- [Dublin Core](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/) — generic resource metadata
- [Schema.org](https://schema.org/) — web content vocabulary
- [EXIF](https://www.cipa.jp/std/documents/e/DC-008-Translation-2019-E.pdf) / [IPTC](https://iptc.org/standards/photo-metadata/) / [XMP](https://developer.adobe.com/xmp/docs/XMPSpecifications/) / [ID3](https://id3.org/) — embedded media metadata
- [OpenAPI](https://www.openapis.org/) — API surface specification
- [JSDoc](https://jsdoc.app/) / [Python Docstring (PEP 257)](https://peps.python.org/pep-0257/) / [Doxygen](https://www.doxygen.nl/) / [rustdoc](https://doc.rust-lang.org/rustdoc/) / [godoc](https://pkg.go.dev/cmd/doc) — code behaviour documentation
- [IETF RFC format](https://www.rfc-editor.org/rfc/rfc7322) — standards-document authoring
- [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — Web Content Accessibility Guidelines (conformance level model)
- [Schema.org `codeRepository`](https://schema.org/codeRepository) — alignment for `sourceRepo`

---

*End of MX Carrier Formats note draft.*

---

## MX Workflow Contracts note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-workflow-contracts.md
**File:** `draft-workflow-contracts.md`

# MX Workflow Contracts note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 27 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies a small set of optional public-extension fields used by **workflow contract cogs** — documents that declare an executable approval, review, or procedural workflow.

The fields defined here are top-level (Zone 1) so that they form part of the cog's signed contract surface: their values name the limits, the people, and the procedures that the cog promises to honour. The shape of each field's object is domain-specific; an explicit `schema` reference on the cog (a top-level pointer to a JSON Schema, YAML schema, or Schema.org type) is the authoritative source for the precise structure.

All fields in this note are conformance level MAY. They apply only to documents that explicitly declare a workflow contract.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of this draft set). That pattern governs the structural template for every field — heading, property table, definition prose, example — and is binding on this note. This note adopts the pattern's authoring rules and does not restate them.

A workflow contract cog is **conformant** with this note if every field it declares from §3 satisfies the field's own type and placement requirements (top-level Zone 1 placement, type as declared, value-shape consistent with the cog's `schema` reference where present).

A document that does not declare any of the fields in §3 makes no claim against this note and is unaffected by it.

### 2.1 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the field definitions, conformance requirements, and normative rules in this note are working drafts — stable enough to build against, expected to evolve through review.

---

## 3. Workflow contract fields

All fields in this section appear at the **top level** of the cog's frontmatter, not under `mx:`, so that they form part of the cog's signed contract surface.

### 3.1 `x-mx-thresholds`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 1 (top-level) |
| **Profile** | x-mx-public |
| **Conformance** | MAY |

**Definition:** Domain workflow thresholds attached to a contract cog. Object whose keys are domain-named limits (e.g. `autoApproveBelow`, `requireSecondaryAbove`, `escalateAt`) and whose values are numeric, monetary, or categorical bounds. The cog's referenced `schema` specifies which keys are required and what types they accept.

**Example:**

```yaml
x-mx-thresholds:
  autoApproveBelow: 1000
  requireSecondaryAbove: 10000
```

### 3.2 `x-mx-approvers`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 1 (top-level) |
| **Profile** | x-mx-public |
| **Conformance** | MAY |

**Definition:** Mapping of approver-role names to identities. Keys are role names (`primary`, `secondary`, `finance`, `legal`, ...). Values are user identities, group references, or role descriptors resolved by the cog runtime.

**Example:**

```yaml
x-mx-approvers:
  primary: line-manager
  secondary: finance-director
```

### 3.3 `x-mx-approvalProcedure`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 1 (top-level) |
| **Profile** | x-mx-public |
| **Conformance** | MAY |

**Definition:** Approval procedure declaration. Object with `runner` (the engine that executes the procedure) and `phases` (an ordered array of phase objects, each typically with an `id` and optional inputs).

**Example:**

```yaml
x-mx-approvalProcedure:
  runner: cog-runtime
  phases:
    - id: triage
    - id: review
    - id: sign-off
```

### 3.4 `x-mx-reviewProcedure`

| Property | Value |
|----------|-------|
| **Type** | object |
| **Zone** | 1 (top-level) |
| **Profile** | x-mx-public |
| **Conformance** | MAY |

**Definition:** Review procedure declaration. Same shape as `x-mx-approvalProcedure` (`runner` + `phases`) applied to review rather than approval workflows.

**Example:**

```yaml
x-mx-reviewProcedure:
  runner: cog-runtime
  phases:
    - id: collect-feedback
    - id: revise
    - id: publish
```

### 3.5 `x-mx-targetEnvironment`

| Property | Value |
|----------|-------|
| **Type** | string |
| **Zone** | 1 (top-level) |
| **Profile** | x-mx-public |
| **Conformance** | MAY |

**Definition:** Named deployment or runtime environment a contract cog targets (e.g. `production`, `staging`, `test`). Resolved by the cog runtime to apply environment-specific settings.

**Example:**

```yaml
x-mx-targetEnvironment: production
```

### 3.6 Group rules

The following rules apply across all fields in §3:

- These fields are typically named in a `contractFields` array on the cog so that changes to thresholds, approvers, procedures, or target environment invalidate any signature attached to the cog.
- Implementations MUST resolve the cog's `schema` reference before validating the inner shape of these objects; the schema is authoritative for required keys.
- The `runner` value in `x-mx-approvalProcedure` and `x-mx-reviewProcedure` MUST be a registry-resolvable runtime identifier.

---

## 4. Out of scope

- **Namespace policy** — the `x-mx-` and `x-mx-p-` prefix conventions used by these fields are governed externally.
- **Signing mechanics** — the canonical-JSON, hash, and signature procedure that protects a workflow contract is governed externally. This note specifies only the contract-content fields, not the cryptography.
- **Per-domain schemas** — the precise required keys and value types for `x-mx-thresholds`, `x-mx-approvers`, `x-mx-approvalProcedure`, and `x-mx-reviewProcedure` are domain-specific. They belong in the schema referenced by the cog, not in this note.
- **Runner implementations** — the engines named by `runner` are out of scope. This note does not specify how `cog-runtime` or any other runner executes phases.
- **Identity resolution** — how an approver name (`line-manager`, `finance-director`) resolves to a real user, group, or service is the runtime's responsibility, not the contract format's.

---

## 5. Security and privacy considerations

- Workflow contracts may name individuals by role title or identity. Authors SHOULD consider whether publishing a contract cog exposes identifying information about staff, approval limits, or organisational structure.
- A workflow contract is only as trustworthy as the signature attached to it, if any. A cog declaring `x-mx-thresholds` without a signature carries no integrity guarantee — the threshold values may have been altered after authoring.
- Threshold values can encode commercially sensitive information (auto-approval limits, escalation triggers). Operators SHOULD treat unsigned, unprotected contract cogs as advisory only.

---

## 6. References

### 6.1 Normative references

- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) — Key words for use in RFCs to indicate requirement levels

### 6.2 Informative references

- [JSON Schema](https://json-schema.org/) — schema referenced by `schema` for object shape validation
- [Schema.org](https://schema.org/) — alternative schema vocabulary for `schema` references
- [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — Web Content Accessibility Guidelines (conformance level model)

---

*End of MX Workflow Contracts note draft.*

---

## MX Agent Directory Discovery note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-agent-directory-discovery.md
**File:** `draft-agent-directory-discovery.md`

# MX Agent Directory Discovery note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 28 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies how a host SHOULD expose an *agent-directory file* so that AI training pipelines, search indexers, and agent crawlers can discover and ingest it. An agent-directory file is any well-known, host-rooted resource that describes the host to non-human readers. Examples include `llms.txt` (Jeremy Howard, September 2024), `robots.txt` (RFC 9309), `humans.txt` (humanstxt.org), and `ai.txt` (various proposals).

This note does not define or redefine any specific agent-directory file format. Each format remains owned by its own community. This note specifies a transport, sitemap, and in-page discovery layer that any agent-directory file SHOULD adopt to be reliably reached by the systems it is intended to inform.

The note is motivated by an observable gap: well-formed agent-directory files are routinely invisible to large-scale crawlers because they are served as `text/plain` (which Common Crawl and similar HTML-only pipelines do not ingest), are absent from `sitemap.xml`, and are not linked from any page in the host. The three normative requirements in this note (HTML transport, sitemap inclusion, in-page discovery link) close that gap without modifying the directory file's content.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here.

### 2.1 Conformance levels

A host claiming conformance to this note SHALL satisfy:

- **Level 1 (Transport):** the HTML-serving requirement in §4.
- **Level 2 (Discovery):** Level 1 plus the sitemap requirement in §5.
- **Level 3 (Resilience):** Level 2 plus the in-page link requirement in §6.

A claim of conformance SHALL state the level reached.

### 2.2 Draft status

This is a draft note. Conformance levels and field semantics MAY change in response to community review. Hosts implementing this draft SHOULD note the draft version number they implemented against.

---

## 3. Scope

### 3.1 In scope

- The transport mechanism by which an agent-directory file is delivered to crawlers.
- The discovery mechanism by which crawlers learn the file exists.
- The in-page mechanism by which agents loading any HTML page on the host learn the file's location.
- The relationship between the agent-directory file and the host's `sitemap.xml`.

### 3.2 Out of scope

- The content, schema, or vocabulary of any specific agent-directory file. This note does not specify what `llms.txt` should contain; that is owned by the llms.txt community. The same applies to `robots.txt`, `ai.txt`, `humans.txt`, and any future agent-directory format.
- The behaviour of inference-time agents that retrieve the directory file on demand. This note addresses training-pipeline and bulk-crawler discovery; inference-time retrieval has its own discovery patterns.
- HTTP caching, CDN configuration, geographic routing, and other transport details unrelated to content negotiation and sitemap inclusion.

### 3.3 Relationship to existing standards

This note relies on:

- **[RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110)** for HTTP semantics, including `Content-Type` negotiation.
- **[Sitemaps 0.9 protocol](https://www.sitemaps.org/protocol.html)** for `sitemap.xml`.
- **[HTML Living Standard](https://html.spec.whatwg.org/)** for the `<link>` and `<meta>` element semantics used in §6.
- **[Schema.org WebPage](https://schema.org/WebPage)** as the structured-data vocabulary for the optional JSON-LD block in §4.3.

This note adds nothing to those standards; it specifies how they combine for the agent-directory case.

---

## 4. Transport: serve as text/html

A host conforming to this note SHALL serve every agent-directory file with `Content-Type: text/html; charset=utf-8`. The host MAY additionally serve the file at a separate URL with `Content-Type: text/plain` for legacy clients, but the canonical URL referenced by §5 and §6 SHALL return `text/html`.

### 4.1 Why HTML

The largest training-data crawlers (Common Crawl is the canonical example, ingested by most major LLM training pipelines) only index HTML responses. A file served as `text/plain` is fetched but excluded from the resulting HTML corpus. The agent-directory file therefore does not reach training data, even though the file exists, is well-formed, and is reachable by direct URL.

### 4.2 Wrapper requirements

The HTML wrapper SHALL:

1. Preserve the agent-directory file's text content verbatim. Implementations SHOULD place the text inside a `<pre>` element to preserve whitespace.
2. HTML-escape any `<`, `>`, and `&` characters in the directory text before insertion into the wrapper.
3. Include a `<title>` element. If the directory text begins with a heading recognisable in its own format (e.g. a Markdown `# Heading` line in `llms.txt`), the wrapper SHOULD promote that heading to `<title>`. Otherwise the wrapper SHOULD use a fallback of the form `<directory-filename>, <hostname>`.
4. Include `<meta charset="utf-8">` and `<meta name="viewport" content="width=device-width, initial-scale=1">`.
5. Include `<meta name="robots" content="index, follow">`. The point of the wrapper is to be indexed.
6. Include `<link rel="canonical" href="<bare-resource-url>">` where `<bare-resource-url>` is the agent-directory file's URL with query string and fragment stripped.

### 4.3 Optional structured data

The wrapper MAY include a Schema.org JSON-LD block describing itself as a `WebPage`. When present, the block SHOULD include at minimum:

- `@context: https://schema.org`
- `@type: WebPage`
- `name`: the title computed in §4.2 step 3
- `description`: a short prose description identifying the resource as an agent-directory file
- `url`: the canonical URL from §4.2 step 6

This block is OPTIONAL because Schema.org is an extension; the transport requirement (§4) does not depend on it.

### 4.4 Wrapping at serve time

The wrapper SHOULD be applied at serve time (e.g. by a reverse proxy, edge worker, or CDN function) rather than by modifying the source file. Wrapping at serve time keeps the source agent-directory file in its native plain-text form for tools that parse it directly, while delivering the HTML form to HTTP clients that request it.

---

## 5. Discovery: list in sitemap.xml

If the host publishes a `sitemap.xml` (per the Sitemaps 0.9 protocol), the host SHALL include each agent-directory file as a `<url>` entry in `sitemap.xml`.

### 5.1 Why sitemap inclusion

Crawlers that discover URLs via `sitemap.xml` (the dominant pattern for large-scale crawl) have no reliable signal that an agent-directory file exists if it is absent from the sitemap. Root-directory speculative fetches are not universal and not guaranteed; sitemap inclusion is.

### 5.2 Sitemap entry shape

The sitemap entry SHALL identify the agent-directory file's canonical URL (the `text/html` URL from §4). The entry MAY include `<lastmod>`, `<changefreq>`, and `<priority>` per the Sitemaps protocol.

### 5.3 Hosts without sitemap.xml

A host that does not publish `sitemap.xml` is not in scope for §5. Such hosts SHOULD reach Level 1 (transport) and Level 3 (in-page link) instead; the sitemap requirement of Level 2 is moot when no sitemap exists.

---

## 6. In-page resilience: <link rel="..."> in every page

Every HTML page on the host SHOULD include in its `<head>` a `<link>` element referencing each agent-directory file the host publishes:

```html
<link rel="<directory-name>" href="/<directory-filename>">
```

### 6.1 Why per-page links

Three discovery paths reinforce each other. Sitemap inclusion (§5) covers crawlers that read sitemaps. HTML serving (§4) makes the file ingestible once reached. The in-page link covers everything in between: agents that arrive via a deep link, JS-only single-page applications whose `<body>` is empty until script execution completes, and crawlers that do not read the sitemap.

For headless and JavaScript-rendered sites the per-page link is particularly load-bearing. The `<head>` is delivered before any script runs and is therefore the only part of the response many crawlers and agents see.

### 6.2 The rel attribute

The `rel` attribute value SHALL be the bare directory name without the `.txt` extension. Example values:

- `rel="llms-txt"` for `/llms.txt`
- `rel="ai-txt"` for `/ai.txt`
- `rel="humans-txt"` for `/humans.txt`

Using kebab-case for the rel value matches existing IANA link relation conventions (e.g. `rel="dns-prefetch"`, `rel="alternate-stylesheet"`).

### 6.3 Optional inline description

A host MAY include alongside the link a `<meta>` element carrying a short prose description of the agent-directory file's content:

```html
<meta name="<directory-name>-description" content="<short prose description>">
```

This is a courtesy to agents that can act on a single tag without having to fetch the directory file itself.

### 6.4 Optional inline content

For hosts whose agent-directory file is short enough to embed in every page, a host MAY include the full content as a `<meta>` element:

```html
<meta name="<directory-name>-content" content="<full file content>">
```

This is RECOMMENDED only when the file is short (under approximately 1KB after escaping) and stable. For longer or frequently-updated directory files, prefer the link form (§6) plus sitemap inclusion (§5).

---

## 7. Why not depend on a new crawler standard

A host could reasonably ask why this note specifies HTML transport, sitemap inclusion, and `<link>` discovery instead of asking crawlers to learn one new convention specific to agent-directory files. The answer is the principle on which the rest of the MX framework rests: **do not require new infrastructure when existing infrastructure already handles the problem**.

Crawlers already understand HTML responses. Sitemaps already signal what matters on a host. The `<link>` element already carries arbitrary `rel` values that machine readers can dispatch on. Specifying that agent-directory files SHOULD use those mechanisms costs the host a one-time configuration change and costs the crawler nothing at all. Specifying a new mechanism would require the host to wait for the crawler ecosystem to update before the directory file becomes useful, which (per the inference-time observation in §3.2) it largely is not anyway.

This note is therefore not novel discovery infrastructure. It is a configuration discipline that makes existing discovery infrastructure work for a class of files that has, until now, fallen between the cracks.

---

## 8. Implementation guidance (informative)

This section is informative; it is not a normative part of the standard.

### 8.1 Worker-based wrapping

A reverse-proxy worker (Cloudflare Worker, Fastly Compute, Vercel Edge Function, Akamai EdgeWorker, etc.) is well suited to serve-time wrapping. The worker intercepts the agent-directory URL, fetches the source plain-text file from the origin, applies the wrapper described in §4, and returns the result with `Content-Type: text/html`.

The wrapper logic SHOULD be expressed as a pure function (string in, string out) so that it can be unit-tested independently of the worker runtime.

### 8.2 Sitemap automation

When the host generates `sitemap.xml` from a content tree, the agent-directory entry can be added by a single rule that detects files at the host root matching the directory naming convention.

### 8.3 In-page link injection

For static-site generators, the `<link>` element SHOULD be added to the canonical page template. For server-rendered applications, it SHOULD be added to the layout component that wraps every page. For client-rendered applications (SPAs), it SHOULD be present in the static `index.html` shell, not injected by JavaScript at runtime, since runtime injection is invisible to crawlers that do not execute scripts.

### 8.4 Verification

A host can verify Level 1 conformance by issuing `curl -I` against the directory URL and checking that the `Content-Type` header begins with `text/html`. Level 2 verification is a `grep` against `sitemap.xml`. Level 3 verification is a `grep` against the rendered `<head>` of any sample page.

---

## 9. Security and privacy considerations

The wrapper described in §4 ingests the agent-directory file's text and emits it as part of an HTML document. Implementations MUST HTML-escape the text (§4.2 step 2) to prevent any `<` or `&` character in the directory text from being interpreted as markup.

The agent-directory file is, by design, public. This note adds no fields that carry confidential data. Hosts that wish to restrict access to the directory file should do so via HTTP authentication or IP allowlisting; that is a host policy, not a content-type concern.

The optional inline content form (§6.4) places the full directory content into every page response. Hosts SHOULD consider whether the directory's content is appropriate to repeat across the entire response surface, and SHOULD NOT use the inline form for content that is not safe to expose alongside any page on the host.

---

## 10. IANA considerations

This note requests no new IANA registrations. The `<link rel>` values described in §6 are agent-directory-specific identifiers that do not require IANA registration; they are dispatched on by name within consuming software.

If the agent-directory community wishes to register specific rel values (e.g. `llms-txt`) with the IANA Link Relation Type registry, that registration is owned by the directory's defining community, not by this note.

---

## 11. References

### 11.1 Normative

- [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) — Key words for use in RFCs.
- [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) — Ambiguity of uppercase vs lowercase in RFC 2119 key words.
- [RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110) — HTTP Semantics.
- [Sitemaps XML format 0.9](https://www.sitemaps.org/protocol.html).
- [HTML Living Standard](https://html.spec.whatwg.org/).

### 11.2 Informative

- [llms.txt proposal (Jeremy Howard, 2024)](https://llmstxt.org/) — the agent-directory format that motivated this note.
- [RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309) — Robots Exclusion Protocol; the canonical example of an agent-directory file with established discovery and indexing conventions.
- [Schema.org](https://schema.org/) — structured-data vocabulary used in §4.3.
- [Common Crawl](https://commoncrawl.org/) — the open web crawl ingested by most major LLM training pipelines.

---

## 12. Acknowledgements

The author thanks the llms.txt and Common Crawl communities, whose work and conventions this note builds upon. Earlier prose treatment of the underlying problem appears at <https://mx.allabout.network/blog/llms-txt-guide.html>.

---

## MX Document Accessibility note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-document-accessibility.md
**File:** `draft-document-accessibility.md`

# MX Document Accessibility note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 28 April 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies how a publisher SHOULD declare and demonstrate the accessibility of a non-HTML document carrier so that AI training pipelines, search indexers, agent crawlers, and assistive technologies (screen readers, screen magnifiers, switch interfaces, refreshable braille displays) can reach, parse, and present the document on equal terms with sighted readers using a standard browser.

The note is motivated by a regulatory and demographic gap. Around one in four people in the European Union has some form of disability; the figure is approximately one in six globally. Document carriers other than HTML (PDF being the dominant case, with an installed base of several trillion files and four hundred billion opened in a single vendor's tooling in a single year) are routinely shipped without the structure tags, logical reading order, or language declarations that assistive technologies require. The European Accessibility Act (Directive (EU) 2019/882) entered into force on 28 June 2025 and applies financial penalties of approximately ten thousand euros for minor violations and one hundred thousand euros or more for major or repeated non-compliance, with significantly higher figures available for large enterprises.

The note does not redefine PDF, DOCX, EPUB, or any other carrier format. Each format remains owned by its own standards body (ISO 32000 for PDF, ISO/IEC 29500 for OOXML, IDPF for EPUB). The note does not redefine accessibility either. WCAG 2.1, EN 301 549, and the per-format accessibility standards (ISO 14289 PDF/UA, the WCAG PDF Techniques) remain authoritative. This note specifies a metadata layer that declares which of those standards the artefact claims to satisfy, and a verification discipline that distinguishes a self-declared claim from an independently checked one.

The note is carrier-agnostic. PDF is treated normatively in section 4 because the regulatory pressure and installed base make it the urgent case. DOCX (section 5) and EPUB (section 6) are described informatively with the same conformance levels and a documented migration path so that the same metadata declarations work across all three formats without per-carrier reinvention.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here.

### 2.1 Conformance levels

A publisher claiming conformance to this note for a given artefact SHALL satisfy:

- **Level 1 (Tagged):** the carrier embeds a structure tree and a logical reading order in its format-native way. For PDF that is a `/StructTreeRoot` per ISO 14289-1 with `/MarkInfo /Marked true` and a populated reading-order tree. For DOCX it is the use of paragraph styles for headings (Heading 1, Heading 2, etc.) plus alternative text on every non-decorative inline image. For EPUB it is semantic XHTML5 with `epub:type` attributes on structural elements.
- **Level 2 (Declared):** Level 1 plus the source artefact (or its sidecar metadata) carries the open-standard MX fields `accessibilityConformance`, `accessibilityFeature`, `accessibilityHazard`, `accessibilitySummary`, and `lang`. The carrier's native metadata mirrors the declarations where the carrier supports it (PDF XMP `pdfuaid:part` and `dc:language`; DOCX `core.xml` language; EPUB `dc:language` and `meta property="schema:accessibilityFeature"`).
- **Level 3 (Verified):** Level 2 plus the result of an independent accessibility check is recorded in the artefact's provenance metadata (`provenancePedigree.checks[]` array, with each entry naming the checker, the checker's version, the date of the check, and the outcome). The note does not name specific checkers; verifier categories include PDF/UA validators, WCAG PDF Techniques runners, and equivalent checkers for DOCX and EPUB.

A claim of conformance SHALL state the level reached.

### 2.2 Draft status

This is a draft note. Conformance levels and field semantics MAY change in response to community review. Implementations of this draft SHOULD note the draft version number they implemented against.

---

## 3. Scope

### 3.1 In scope

- The metadata fields a publisher SHOULD attach to a non-HTML document artefact to declare its accessibility characteristics.
- The mapping from those metadata fields to each carrier's native metadata representation (XMP for PDF, core.xml for DOCX, OPF metadata for EPUB).
- The verification discipline that distinguishes a self-declared claim (Level 2) from an independently checked claim (Level 3).
- The relationship between a carrier-format declaration (e.g. `accessibilityConformance: PDF/UA-1`) and the underlying ISO standard the declaration refers to.

### 3.2 Out of scope

- The format-internal mechanics of how to embed a structure tree, alt text, or reading order in PDF, DOCX, or EPUB. Those mechanics are owned by ISO 14289 (PDF/UA), ISO 32000 (PDF), the OOXML accessibility annex, and the EPUB accessibility specification.
- The pedagogical question of what makes good alt text. Each carrier-format community has its own guidance (W3C alt-text decision tree, EPUB accessibility guidelines, Microsoft Office accessibility checker rules); this note defers to them.
- HTML accessibility. WCAG 2.1, the WAI-ARIA specification, and the existing HTML semantics already cover HTML; this note does not duplicate them. The MX Carrier Formats note (the sister Gathering draft for code carriers) and the broader MX accessibility narrative in the published MX manuscripts cover HTML separately.
- Procurement-side compliance language for the European Accessibility Act, the Americans with Disabilities Act, the UK Equality Act, or any other jurisdiction-specific regulation. This note describes the technical metadata; the regulatory question of which artefacts fall under which jurisdiction is owned by the publisher and their legal counsel.

### 3.3 Relationship to existing standards

The accessibility-conformance vocabulary defined here (`accessibilityConformance`, `accessibilityFeature`, `accessibilityHazard`, `accessibilitySummary`) is the detailed disclosure layer for documents whose accessibility is a first-class concern. Cogs that need only a high-level quality signal — "is the cog accessibility-aware?" — declare `quality.accessibility` per **MX Provenance note** §6.5, rather than the full conformance vocabulary here. The two layers are complementary: `quality.accessibility` is the summary signal; the fields in this note are the detailed claim.

This note relies on:

- **[ISO 14289-1](https://www.iso.org/standard/64599.html)** (PDF/UA-1) for PDF accessibility.
- **[ISO 32000-2](https://www.iso.org/standard/75839.html)** (PDF 2.0) for the underlying PDF specification.
- **[ISO 19005](https://www.iso.org/standard/63534.html)** series (PDF/A) for archive-grade PDF, which shares much of the accessibility tagging machinery.
- **[WCAG 2.1](https://www.w3.org/TR/WCAG21/)** and the [W3C PDF Techniques](https://www.w3.org/WAI/WCAG21/Techniques/#pdf) for the cross-format accessibility success criteria.
- **[BCP 47](https://www.rfc-editor.org/info/bcp47)** for the language tags used in the `lang` field and in carrier-native language declarations.
- **[Schema.org accessibility properties](https://www.w3.org/2021/a11y-discov-vocab/latest/)** (`accessibilityFeature`, `accessibilityHazard`, `accessibilitySummary`, `accessibilityAPI`, `accessibilityControl`) as the canonical vocabulary for the MX `accessibilityFeature`, `accessibilityHazard`, and `accessibilitySummary` fields.
- **[Directive (EU) 2019/882](https://eur-lex.europa.eu/eli/dir/2019/882/oj)** (the European Accessibility Act) as the regulatory context that motivates publisher adoption.

This note adds nothing to those standards; it specifies how their metadata combines for the document-format accessibility case.

---

## 4. PDF (normative)

A PDF carrier claiming conformance to this note SHALL satisfy the following requirements at the level claimed.

### 4.1 Level 1: Tagged PDF (normative)

The PDF SHALL embed a `/StructTreeRoot` per ISO 14289-1 §7.1, populated with a tag tree that mirrors the document's logical structure (headings, paragraphs, lists, tables, figures, captions, links). The PDF SHALL declare itself tagged via `/MarkInfo << /Marked true >>` in the document catalog.

The tag tree SHALL define a logical reading order distinct from the visual layout order. Multi-column documents (newspaper layouts, two-column scientific papers, side-by-side translation panels) MUST set the reading order so that screen readers traverse columns in the author's intended sequence rather than across each visual row.

Every non-decorative image, figure, formula, or other non-text content element SHALL carry alternative text via the `/Alt` entry on the structure element. Decorative content (borders, dividers, purely visual ornament) SHALL be marked as artefacts (`/Artifact`) so that assistive technologies skip them.

### 4.2 Level 2: Declared (normative)

The source artefact (or its sidecar metadata, where the PDF is generated from a source carrying MX frontmatter) SHALL declare:

- `accessibilityConformance` set to `PDF/UA-1` or `PDF/UA-2`.
- `accessibilityFeature` listing the Schema.org accessibility features the PDF carries (e.g. `taggedPDF`, `readingOrder`, `alternativeText`, `displayTransformability`).
- `accessibilityHazard` listing any Schema.org accessibility hazards present, or the negative declarations (`noFlashingHazard`, `noSoundHazard`, `noMotionSimulationHazard`) where the publisher knows the PDF is hazard-free.
- `accessibilitySummary` carrying a one-paragraph human-readable description of the PDF's accessibility characteristics.
- `lang` carrying the BCP 47 language tag of the PDF's primary language.

The PDF's XMP packet SHALL mirror the declarations where the XMP namespace supports them: `pdfuaid:part` MUST equal the integer part of the declared `accessibilityConformance` value (1 for `PDF/UA-1`, 2 for `PDF/UA-2`); `dc:language` MUST equal the `lang` value.

A PDF carrying these declarations without satisfying Level 1 is non-conformant. Validators SHALL reject the claim and SHOULD report the missing structure-tree or reading-order element specifically rather than a generic failure.

### 4.3 Level 3: Verified (normative)

An independent accessibility check SHALL have run against the PDF byte-stream, and the check's outcome SHALL be recorded in the artefact's provenance metadata under `provenancePedigree.checks[]`. Each entry in the array SHALL carry at minimum:

- `checker`: the name (and where applicable the version) of the checker that ran.
- `standard`: the standard the checker validated against (e.g. `PDF/UA-1`, `WCAG-2.1-AA`).
- `date`: the ISO 8601 date the check ran.
- `outcome`: `pass`, `pass-with-warnings`, or `fail`.

The note does not name specific checkers; verifier categories include PDF/UA validators, WCAG PDF Techniques runners, and accessibility-checker tools shipped by major office and graphics vendors.

A `fail` or `pass-with-warnings` outcome MAY still be Level 3 conformant if the publisher records the outcome honestly. The point of Level 3 is verifiability, not perfection.

---

## 5. DOCX (informative)

A DOCX carrier conforms to this note at Level 1 by using the document's heading styles consistently for headings (Heading 1, Heading 2, etc. rather than directly-formatted bold text), by carrying alternative text on every non-decorative inline image (the alt-text dialogue in mainstream office authoring tools), and by setting the document's primary language in `core.xml`.

Level 2 declarations are carried in the same way as for PDF: the source artefact (the DOCX itself, since DOCX is its own source) carries the MX accessibility fields in either a sidecar metadata file or in the `core.xml` extended-properties block. The DOCX accessibility checker tools provided by mainstream office suites can serve as Level 3 verifiers when their outcome is recorded in `provenancePedigree.checks[]`.

The OOXML accessibility annex covers the format-internal mechanics. This note does not duplicate it.

---

## 6. EPUB (informative)

An EPUB carrier conforms to this note at Level 1 by using semantic XHTML5 throughout, with `epub:type` attributes on structural elements (chapter, part, glossary, etc.) per the EPUB Structural Semantics Vocabulary, by carrying alternative text on every non-decorative image, and by declaring the language in the OPF `dc:language` element.

Level 2 declarations are carried in the OPF metadata block as `meta` elements with `property="schema:accessibilityFeature"`, `property="schema:accessibilityHazard"`, and `property="schema:accessibilitySummary"`, mirroring the MX field names. The EPUB accessibility specification (EPUB Accessibility 1.1) covers the format-internal mechanics.

---

## 7. Why three reinforcing layers

A publisher could reasonably ask why this note specifies three conformance levels rather than a single binary "is it accessible".

The answer is that accessibility claims fail in three distinct ways and each layer catches a different one. A PDF can be byte-level tagged (Level 1) but carry no machine-readable declaration of what standard it claims, so a downstream consumer has to parse the file to find out (the Level 2 problem). A PDF can carry an explicit `accessibilityConformance: PDF/UA-1` declaration in its source frontmatter and its XMP packet but be untagged at the byte level (the Level 1 problem; the declaration is a lie). A PDF can be tagged and declared but never independently checked, so the publisher's claim is unverified (the Level 3 problem; trust is asserted but not earned).

The three layers reinforce each other: structural truth (Level 1), declared truth (Level 2), and verified truth (Level 3). A publisher claiming Level 3 is making the strongest claim available without requiring new verification infrastructure; the note relies entirely on existing checker tooling and existing standards.

The European Accessibility Act, the Americans with Disabilities Act, the UK Equality Act, and analogous regulations in other jurisdictions create a legal incentive for Level 3 specifically: a self-declaration without independent verification carries less defensive weight than an independently-checked one.

This note is therefore not novel infrastructure. It is a metadata discipline that makes existing accessibility infrastructure auditable.

---

## 8. Implementation guidance (informative)

This section is informative; it is not a normative part of the standard.

### 8.1 Generation pipelines

Most publishers generate PDFs from a higher-level source (Markdown, LaTeX, Word, web-to-PDF). The accessibility-conscious choice is to generate tagged output by default rather than retrofit tagging onto an untagged production file.

For Markdown-to-PDF pipelines, a typesetting engine that supports the `tagpdf` package (lualatex with `\usepackage{tagpdf}`) produces tagged output natively. Alternatives include weasyprint and chromium-headless print-to-PDF, both of which produce tagged output by default for HTML input.

For Word-to-PDF pipelines, the office suite's "Save As PDF" or "Export as PDF" function respects the source document's heading styles and alt text when accessibility is enabled at export time.

### 8.2 Verification

A heuristic Level 1 check on a PDF can be performed with `qpdf --json <pdf>` (qpdf is widely available open-source tooling) and inspecting the output for `/StructTreeRoot`, `/MarkInfo /Marked true`, and `/Lang` entries on the document catalog, plus the XMP `pdfuaid:part` declaration. A heuristic check is not a Level 3 verification; Level 3 requires a checker that validates the tag tree's correctness against the standard, not just the presence of the byte-level structures.

A full Level 3 verifier for PDF/UA-1 is available from several open-source and commercial sources. The verifier identity SHOULD be recorded in `provenancePedigree.checks[]` so a downstream reader can re-run the same verifier and reproduce the outcome.

### 8.3 Authoring-tool alt text

Mainstream authoring tools and several AI-assisted authoring services now suggest alt text automatically. Suggested alt text is often technically correct but lacks document context. A common failure mode: a photograph of a named person is described as "older businessman looking professional" rather than the person's name and role. A bar chart is described as "blue bars on a white background" rather than the dataset and the comparison the chart conveys.

Authors SHOULD review every auto-suggested alt-text value before shipping. Authors SHOULD mark genuinely decorative images with `decorative: true` (the MX field) so that authoring tools and verifiers know to skip them rather than emit alt text the screen reader would then announce as noise.

### 8.4 Scope: which documents need conformance

Not every artefact needs to satisfy this note. Internal-only documents, ephemeral working notes, and machine-generated artefacts that are never read by a human or an assistive technology are out of practical scope.

The artefacts that benefit most from conformance are customer-facing documents published to the open web (white papers, product datasheets, academic preprints, regulatory filings, government forms) and high-touch internal documents that must be readable by every employee regardless of disability (HR policies, company handbooks, training materials, payroll documents, signed contracts).

---

## 9. Security and privacy considerations

The fields described in this note carry no confidential data. Accessibility declarations are by their nature public claims about an artefact intended for public consumption.

The provenance entries recorded at Level 3 (`provenancePedigree.checks[]`) name the checker tool and outcome. Publishers SHOULD consider whether any checker-emitted diagnostic detail (e.g. a list of specific tag-tree errors on a failed check) is appropriate to expose alongside the artefact. The recommended pattern is to record the outcome in the public provenance and keep the diagnostic detail in private build logs.

The declarations described here do not expose any user data, do not require the artefact to track or fingerprint readers, and do not create any new attack surface beyond the carrier format's own.

---

## 10. IANA considerations

This note requests no new IANA registrations. The Schema.org accessibility properties referenced in this note are defined and maintained by Schema.org under their published process; the carrier-format-specific properties (`pdfuaid:part`, `pdfaid:part`, `dc:language`) are defined and maintained by their respective standards bodies.

---

## 11. References

### 11.1 Normative

- [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) — Key words for use in RFCs.
- [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) — Ambiguity of uppercase vs lowercase in RFC 2119 key words.
- [BCP 47](https://www.rfc-editor.org/info/bcp47) — Tags for identifying languages.
- [ISO 14289-1](https://www.iso.org/standard/64599.html) — Document management applications: Electronic document file format enhancement for accessibility (PDF/UA-1).
- [ISO 32000-2](https://www.iso.org/standard/75839.html) — Document management: Portable document format (PDF 2.0).
- [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — Web Content Accessibility Guidelines.

### 11.2 Informative

- [ISO 19005](https://www.iso.org/standard/63534.html) series — PDF/A archive-grade PDF.
- [W3C PDF Techniques](https://www.w3.org/WAI/WCAG21/Techniques/#pdf) — Accessibility techniques for PDF.
- [Schema.org accessibility properties](https://www.w3.org/2021/a11y-discov-vocab/latest/) — Accessibility metadata vocabulary.
- [EPUB Accessibility 1.1](https://www.w3.org/TR/epub-a11y-11/) — Accessibility specification for EPUB publications.
- [Directive (EU) 2019/882](https://eur-lex.europa.eu/eli/dir/2019/882/oj) — European Accessibility Act.
- [EN 301 549](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/) — Accessibility requirements for ICT products and services (the EU public-sector procurement standard).

---

## 12. Acknowledgements

The author thanks the PDF/UA, WCAG, and EPUB accessibility communities, whose decades of work this note builds on. The note's three-level conformance shape is modelled on the WCAG Level A / AA / AAA pattern and on the MX Agent Directory Discovery note's transport / discovery / resilience structure.

---

## MX Contract Fingerprinting and Signing note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-contract-fingerprinting.md
**File:** `draft-contract-fingerprinting.md`

# MX Contract Fingerprinting and Signing note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 8 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

**Signing is optional.** Most cogs ship unsigned. This note specifies the contract a cog satisfies *when it elects to be signed*; it does not require a cog to be signed.

When a cog is signed, two frontmatter fields make the signature scope explicit. `contractFields` lists top-level keys covered by the signature. `metadataFields` lists keys explicitly excluded (timestamps, tags, registry annotations) — values that may change without invalidating the signature.

This note defines only the **fingerprint** — the deterministic byte sequence over which a signature is produced (canonical JSON projection of the contract keys, hashed with SHA-256). Signature algorithm, key management, and transport are out of scope.

The signature attests **provenance and integrity, not truth**: a verifier confirms that the cog's contract surface was last in this exact state when the named signer applied the signature, and nothing more. Section 9 explains why the narrower claim is deliberate.

---

## 2. Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) when, and only when, they appear in all capitals.

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of this draft set). That pattern governs the structural template for every field — heading, property table, definition prose, example — and is binding on this note. This note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

This note defines three conformance levels (modelled on the [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level A/AA/AAA pattern):

- **Level 1 (MUST)** — A cog declaring `contractFields` MUST also declare `metadataFields`. The two arrays MUST be disjoint.
- **Level 2 (SHOULD)** — A signed cog SHOULD declare both arrays. Verifiers SHOULD reject a signed cog whose declared scope cannot be reconciled with the signature.
- **Level 3 (MAY)** — Implementations MAY extend the fingerprint algorithm with additional canonicalisation passes provided they are documented in a `validatesAgainst` declaration on the cog.

### 2.2 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Reference implementations exist in JavaScript and Rust under the `cog-spec` v1.0 codebase; those implementations carry the kebab-case forms (`x-mx-contract-fields`, `x-mx-metadata-fields`), while the camelCase forms in this note are the canonical names.

---

## 3. Scope

### 3.1 What this note covers

- The two fields `contractFields` and `metadataFields` (definitions in §4).
- The deterministic fingerprint algorithm (§5).
- Conformance rules and verifier expectations (§6).

The fingerprint algorithm in §5 is generic over any structured object. Although §4 specifies it for cog frontmatter, sister notes that need to sign other MX payloads adopt §5 unchanged; §5.4 makes that adoption pattern explicit. Verifiers built against this note can therefore verify any MX signature uniformly without per-payload variants.

### 3.2 Out of scope

- Signature algorithms (Ed25519, ECDSA, RSA, post-quantum) — defer to [W3C VC Data Integrity](https://www.w3.org/TR/vc-data-integrity/), [JWS (RFC 7515)](https://datatracker.ietf.org/doc/html/rfc7515), or [COSE (RFC 9052)](https://datatracker.ietf.org/doc/html/rfc9052).
- Key management, distribution, or rotation — defer to organisational PKI.
- Transport encoding (detached vs envelope, PEM vs raw bytes) — defer to the chosen signature standard.
- Multi-signer coordination and revocation — open question (§7).

### 3.3 Relationship to existing standards

| Standard | Relationship |
|----------|--------------|
| [W3C VC Data Integrity](https://www.w3.org/TR/vc-data-integrity/) | Compatible signing model. The MX fingerprint may be wrapped in a VC proof. |
| [JWS RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515) | Compatible signing model. The MX fingerprint may be the JWS payload. |
| [COSE RFC 9052](https://datatracker.ietf.org/doc/html/rfc9052) | Compatible signing model for binary/CBOR transports. |
| [C2PA Content Credentials](https://c2pa.org/) | Compatible model for signing assertions about content provenance. |
| [FIPS 180-4](https://csrc.nist.gov/publications/detail/fips/180/4/final) | SHA-256, the hash function used by the fingerprint algorithm in §5. |
| [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259) | The JSON Data Interchange Format, used as the canonical serialisation in §5. |

---

## 4. Field definitions

### 4.1 `contractFields`

| Property | Value |
|----------|-------|
| **Type** | array of string |
| **Zone** | 1 (top-level) |
| **Conformance** | MUST (Level 1) when a signature is present |
| **Default** | *(none)* |

**Definition:** Frontmatter top-level keys whose values are covered by the cog's signature. Defines the contract fingerprint scope. Each entry MUST be the name of a key that exists at the top level of the cog's frontmatter.

**Example:**

```yaml
contractFields:
  - title
  - schema
  - x-mx-thresholds
  - x-mx-approvers
  - x-mx-approvalProcedure
```

- The array MUST be disjoint from `metadataFields`.
- Every entry SHOULD reference a key that exists in the frontmatter; verifiers MAY treat stray entries as a warning.
- Entries MAY include `x-mx-` and `x-mx-p-` namespaced fields. Private fields included in `contractFields` are still covered by the signature even though their values are obfuscated.

### 4.2 `metadataFields`

| Property | Value |
|----------|-------|
| **Type** | array of string |
| **Zone** | 1 (top-level) |
| **Conformance** | MUST (Level 1) when `contractFields` is declared |
| **Default** | *(none)* |

**Definition:** Frontmatter top-level keys explicitly EXCLUDED from the contract fingerprint. Values of these keys may change without invalidating the signature. Typical members are timestamps, tags, registry annotations, and other non-contract metadata.

**Example:**

```yaml
metadataFields:
  - created
  - modified
  - tags
```

- The array MUST be disjoint from `contractFields`.
- Keys not listed in either array are **implementation-defined** — verifiers MAY default unlisted keys to either category, but MUST document their choice.
- A best-practice declaration lists every top-level frontmatter key in exactly one of the two arrays.

### 4.3 Mandatory fields when signing

When a cog is signed, the following frontmatter MUST be present and well-formed. A signer MUST refuse to sign a cog that fails any of these checks; a verifier MUST refuse a signed cog whose mandatory fields are missing or malformed.

| Field | Requirement | Rationale |
|-------|-------------|-----------|
| `title` | Non-empty string at the top level. | The signed claim records what was signed; without a title there is no human-readable identity to bind to. |
| `validatesAgainst` | Non-empty array of validator names. Every entry MUST be resolvable — that is, registered with the verifying runtime — and MUST pass when executed. | The signature claims the cog passed every named validator at sign time. An unresolvable validator means the claim cannot be interpreted; a failing validator means the claim is false. |
| `schema` | Reference to the schema document that defines the cog's contract structure. If declared in frontmatter, MUST resolve to a real schema. | The schema specifies the contract shape the signed claim covers. |

These three fields together form the *minimum signed surface*. The fingerprint algorithm in §5 covers them automatically because they are top-level frontmatter keys typically named in `contractFields`.

A signer SHOULD perform these checks during a pre-signature review pass (§6.4) before producing a fingerprint. A signer that emits signatures over cogs missing any of the three is not conforming.

### 4.4 Computing the contract scope

Implementations resolve the contract scope (which top-level keys are signed) in the following precedence order:

1. **Explicit `contractFields` array on the cog.** When the cog declares `contractFields`, that array is authoritative. The companion `metadataFields` array names the explicit exclusions. The two arrays MUST be disjoint (§4.1, §4.2).

2. **Schema-derived projection.** When the cog does not declare `contractFields` but does declare `schema:`, implementations MUST resolve the schema and compute the contract scope from per-property annotations:

   - A schema property carrying `x-mx-contract: true` is a contract field; its top-level key (or its dotted path for nested keys) is included in the projection.
   - A schema property carrying `x-mx-contract: false` is metadata; the key is excluded.
   - A schema property with no annotation falls through to step 3.

   When schema-derivation is in effect, the cog SHOULD NOT also declare `contractFields` — declaring both is permitted (the explicit array still wins) but the schema annotations are then redundant.

3. **Default classification.** When neither an explicit array nor a schema annotation resolves a key, the following defaults apply:

| Top-level key | Default classification | Rationale |
|---------------|------------------------|-----------|
| `modified` | metadata | Updated whenever the document content changes; not a contract claim. |
| `created` | metadata | Editorial provenance, not contract surface. |
| `originator` (alias `author`) | metadata | Identity field; provenance signature covers authorship separately. |
| `updateInstructions` | metadata | Operational guidance for stewards; not contract surface. |
| `version` | **contract** | Bumping a version is a substantive editorial act. A signature that survives version bumps lets the same signed bytes be republished as v1, v2, v3 without invalidation; that is undesirable. Re-versioning a signed cog re-invalidates the signature; re-signing is required. |
| (anything else) | implementation-defined | Verifiers MAY default unlisted keys to either category but MUST document their choice and apply it consistently. |

**Schema-derivation example.** A schema declared as:

```yaml
$id: ./schemas/invoice-approval.v1.yaml
type: object
properties:
  title:
    type: string
    x-mx-contract: true
  schema:
    type: string
    x-mx-contract: true
  thresholds:
    type: object
    x-mx-contract: true
  modified:
    type: string
    x-mx-contract: false
  tags:
    type: array
    x-mx-contract: false
```

…allows the cog to omit `contractFields`/`metadataFields` entirely. The validator computes the projection from the schema annotations and produces a fingerprint covering `title`, `schema`, `thresholds`. An author writes the schema once; the contract surface is automatically projected from it.

### 4.5 Pre-signature contract declaration (Normative)

An unsigned cog MAY declare `contractFields` and `metadataFields` even though no signature is being applied. The declaration is a **unilateral commitment** — a statement of what the author would sign over if signing were applied — and serves as a useful authorial signal: it tells future readers (human and machine) which keys are intended to be contract surface and which are intended to be metadata.

When an unsigned cog carries the two arrays, verifiers MUST treat the declarations as **informational**:

- A verifier MUST NOT treat the absence of a signature as a conformance failure when `contractFields` is declared on its own. Signing is optional (§1).
- A verifier MAY compute the would-be fingerprint over the declared `contractFields` and surface it as a "pre-signature digest" — a fixed, citeable hash that lets the unsigned cog be referenced by content without depending on later signing activity.
- A verifier SHOULD record that the declarations are unsigned so a downstream consumer cannot mistake them for an attestation.

The §4.1, §4.2, and §4.3 normative requirements (disjoint arrays; mandatory `title` / `validatesAgainst` / `schema`; well-formed entries) apply to the declarations whether or not a signature is present. The §6.1 signer-conformance and §6.2 verifier-conformance rules attach to the signature itself; they do not preclude the declarations from existing on an unsigned cog.

Authors using schema-derivation (§4.4 step 2) need not duplicate the projection as an explicit `contractFields` array on the cog itself; the schema annotations are the declaration. The same informational treatment applies to a verifier that resolves the contract surface from the schema on an unsigned cog.

---

## 5. The fingerprint algorithm

### 5.1 Overview

The contract fingerprint is a deterministic byte sequence derived from the values of the keys named in `contractFields`. Two implementations applying this algorithm to the same frontmatter MUST produce identical fingerprints.

### 5.2 Steps

1. **Project.** Build an object containing only the keys listed in `contractFields`. Keys absent from the frontmatter are omitted (verifiers MAY warn).
2. **Sort.** Order keys lexicographically by Unicode code point.
3. **Canonicalise values.** For each value:
   - Strings: serialised as UTF-8 with no escaping beyond what JSON requires.
   - Numbers: serialised as their canonical JSON form.
   - Booleans: `true` or `false`.
   - Objects and arrays: recursively canonicalised by the same rules; keys of nested objects are also lexicographically sorted.
   - Null: `null`.
4. **Serialise.** Emit the canonical object as UTF-8 JSON ([RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259)) with no insignificant whitespace.
5. **Hash.** Apply SHA-256 ([FIPS 180-4](https://csrc.nist.gov/publications/detail/fips/180/4/final)) to the canonical byte sequence. The 32-byte digest is the fingerprint.

The signature is then produced by signing the fingerprint bytes with the chosen signature algorithm. The signature MAY be carried in any envelope format (JWS, COSE, detached signature, sidecar file).

### 5.3 Worked example

Given:

```yaml
title: Approve invoices below 1000
schema: ./schemas/invoice-approval.v1.yaml
x-mx-thresholds:
  autoApproveBelow: 1000
contractFields: [title, schema, x-mx-thresholds]
metadataFields: [created, modified, tags]
```

The projection is:

```json
{"schema":"./schemas/invoice-approval.v1.yaml","title":"Approve invoices below 1000","x-mx-thresholds":{"autoApproveBelow":1000}}
```

(Keys sorted lexicographically: `schema`, `title`, `x-mx-thresholds`.)

The fingerprint is `SHA-256` of these bytes.

### 5.4 Application to non-cog payloads

The §5.2 canonicalisation algorithm (project, sort, canonicalise values, serialise as canonical JSON, SHA-256) is generic. It applies unchanged to any structured object an MX sister note specifies for signing, not only to cog frontmatter. A note adopting §5 for a non-cog payload SHOULD declare so explicitly so that signers and verifiers know which canonicalisation to apply.

For non-cog payloads, the §5.2 step 1 "project" step is replaced by an inclusion rule defined by the adopting note. Two patterns recur:

- **Whole-payload canonicalisation.** The adopting note specifies that the entire payload object is canonicalised, with a single named field (typically the signature carrier itself) excluded so that the signature is computed over a payload that does not contain its own signature. The MX Compliance Claims note follows this pattern: the entire claim object is canonicalised excluding the `signature` field.
- **Field-list canonicalisation.** The adopting note specifies a fixed list of payload fields to include, analogous to `contractFields` for cogs. This pattern is appropriate where the payload carries fields the adopting note classifies as metadata that should not affect the signature.

Whichever pattern the adopting note chooses, the adopting note MUST be precise about: the inclusion rule, whether unlisted keys are included or excluded, and how the rule interacts with future schema evolution. The §5.2 canonicalisation steps themselves do not vary across adopters; only the projection rule is note-specific.

A sister note that adopts §5 inherits the conformance properties of the algorithm: deterministic, portable, recoverable from the canonical bytes alone. Verifiers that implement §5 once can therefore verify cog signatures and non-cog signatures uniformly, given the per-note projection rule as input.

Current adopters:

- **MX Compliance Claims note** — specifies whole-payload canonicalisation for compliance claim signatures, with the `signature` field excluded.

A sister note proposing a new adoption SHOULD coordinate with this note's authors so that the adoption pattern is recorded in the list above and any incompatibility surfaces early.

---

## 6. Conformance: signers and verifiers

### 6.1 Signer conformance

A signer:

- MUST refuse to sign a cog that fails the §4.3 mandatory-fields check (missing `title`, missing or unresolvable `validatesAgainst`, missing/invalid `schema`).
- MUST run every validator listed in `validatesAgainst` and refuse to sign if any reports failure.
- MUST treat `contractFields` and `metadataFields` as authoritative when both are declared.
- MUST treat the §4.4 default-excluded metadata field list as the fallback when neither `contractFields` nor `metadataFields` is declared and the schema does not override.

### 6.2 Verifier conformance

A verifier:

- MUST refuse a signed cog whose `contractFields` and `metadataFields` overlap.
- MUST refuse a signed cog whose declared `contractFields` cannot be reconstructed from the frontmatter (missing keys would change the projection).
- MUST refuse a signed cog missing any of the §4.3 mandatory fields, or whose `validatesAgainst` entries cannot be resolved or fail validation at verification time.
- MUST resolve the contract scope using the precedence in §4.4 (explicit array → schema-derived projection → defaults). A verifier presented with a schema-derived projection MUST resolve the schema and apply the `x-mx-contract` annotations exactly as the signer would have done.
- SHOULD warn when frontmatter contains top-level keys not listed in either array and not resolvable from the schema.
- SHOULD log the resolved contract set alongside any verification result for transparency, naming the source (explicit array, schema-derived, or default classification).
- MUST NOT silently substitute a fallback scope when the cog declares neither array AND has no `schema:` reference. In that case, verification falls back to the defaults in §4.4 step 3 and the verifier MUST surface that the projection was defaulted.

### 6.3 Recommended pre-signature review pipeline (Informative)

*This subsection is informative; it describes recommended practice but is not normative.*

A conforming signer SHOULD execute a multi-phase review before producing a signature. A typical pipeline:

1. **Inventory** — enumerate all sections and top-level fields of the cog.
2. **Classify** — assign each section a layer (declarative, executable, narrative).
3. **Lift** — identify the load-bearing body sections that materially affect the contract.
4. **Declare-Contracts** — audit that `schema` and `validatesAgainst` are declared, well-formed, and reference resolvable validators (§4.3 check).
5. **Validate** — run every validator named in `validatesAgainst`. All MUST pass.
6. **Notarise** — only when phases 1–5 succeed, compute the fingerprint per §5 and produce the signature.

Implementations MAY combine, rename, or extend phases. The MUST is that a signer never produces a signature over an artefact that has not passed an equivalent of phases 4 and 5.

---

## 7. Open questions

The following remain open for community discussion:

1. **Key management** — should this note reference a default PKI model, or stay agnostic?
2. **Multi-signer** — when multiple parties sign the same cog, is each signature scoped to the same `contractFields` or may each declare its own scope?
3. **Revocation** — how does a verifier discover that a previously valid signature has been revoked? CRL, OCSP, on-chain registry, an MX registry?
4. **Canonical YAML alternative** — §5 chooses canonical JSON for portability. Should an opt-in canonical-YAML form be standardised for cogs that wish to sign over their authored representation directly?

(The earlier open question on schema-derived contract is closed by §4.4: the contract is derivable from a `schema:` reference whose properties carry `x-mx-contract` annotations, and the explicit `contractFields` array is the override.)

---

## 8. Security and privacy considerations

- A cog whose `contractFields` does not list every load-bearing field is **silently weakly bound** — values not in the contract may be modified after signing without invalidating the signature. Authors SHOULD list every contract-bearing field explicitly.
- Including `x-mx-p-` private fields in `contractFields` makes the signature cover values whose meaning is opaque without the private registry. Verifiers without registry access can still verify the signature but cannot interpret what was signed.
- The fingerprint is NOT encrypted. Anyone with the cog can compute the fingerprint and learn the contract scope. Confidentiality of contract values is the responsibility of the carrier transport.

---

## 9. Rationale: attestation, not verification

*This section is informative.*

A signed cog makes one narrow claim, and the narrowness is what makes it tractable. The signature attests provenance and integrity, not truth:

- The signature confirms that the cog's contract surface (the keys named in `contractFields`) was last in this exact state when the named signer applied the signature.
- It does not assert that the values are factually correct, sound, or current. A cog claiming "WWII did not happen" can be perfectly well-signed; the signature only confirms the cog genuinely came from the named signer and has not been altered downstream. Whether the claim is true is a different problem — one no signing format can solve at web scale, and one this note deliberately does not take on.

The narrower claim is intentional. The signing model in this note attests only *this is what the owner published, unaltered*. That smaller claim is what compounds — it is a question a signature can actually answer, every time, without taking on an editorial truth-curation burden that no human review process could keep current at web scale.

Implementations and downstream consumers SHOULD be precise in user-facing language: the system has *attested* a cog, not *verified* it. "Verified" implies a truth claim that no signer in this model makes.

---

## 10. References

### 10.1 Normative references

- [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) — keywords for use in RFCs to indicate requirement levels
- [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259) — The JSON Data Interchange Format (canonical serialisation in §5)
- [FIPS 180-4](https://csrc.nist.gov/publications/detail/fips/180/4/final) — SHA-256 hash function

### 10.2 Informative references

- [W3C Verifiable Credentials Data Integrity](https://www.w3.org/TR/vc-data-integrity/) — compatible signing model
- [JWS RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515) — JSON Web Signature
- [COSE RFC 9052](https://datatracker.ietf.org/doc/html/rfc9052) — CBOR Object Signing and Encryption
- [C2PA Content Credentials](https://c2pa.org/) — provenance signing model
- [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — conformance level model that inspired the Level 1/2/3 framework in §2.1

---

## 11. Minimum-viable signed cog (Informative)

A complete worked example: schema, cog, projection, fingerprint. An author can copy and adapt this shape for their own contract.

### 11.1 The schema (annotation-driven)

Saved as `./schemas/invoice-approval.v1.yaml`:

```yaml
$id: https://example.org/schemas/invoice-approval.v1.yaml
type: object
properties:
  title:
    type: string
    x-mx-contract: true
  thresholds:
    type: object
    x-mx-contract: true
    properties:
      autoApproveBelow:
        type: number
  approvers:
    type: array
    x-mx-contract: true
  modified:
    type: string
    x-mx-contract: false
  tags:
    type: array
    x-mx-contract: false
```

### 11.2 The cog (no explicit `contractFields` — schema-derived)

Saved as a markdown file with YAML frontmatter (e.g. `approve-invoices.md`):

```yaml
---
title: "Approve invoices below 1000"
originator: "Tom Cranstoun"
created: 2026-05-01
modified: 2026-05-07
version: "1.0"
schema: ./schemas/invoice-approval.v1.yaml
validatesAgainst:
  - cog.meta.v1
  - invoice-approval.v1
thresholds:
  autoApproveBelow: 1000
approvers:
  - finance-lead
  - cfo
type: cog
mx:
  status: published
  canonicalUri: https://example.org/cogs/approve-invoices.v1
  summary: "Approve invoices under 1000 automatically; escalate above."
  conformsTo: [https://mx.allabout.network/cog.html]
  trainingDataPolicy: "Permitted with attribution."
---
```

### 11.3 The resolved projection (computed by signer and verifier)

The signer resolves the schema, applies the `x-mx-contract` annotations, and projects the cog's frontmatter to:

```json
{
  "approvers": ["finance-lead", "cfo"],
  "schema": "./schemas/invoice-approval.v1.yaml",
  "thresholds": {"autoApproveBelow": 1000},
  "title": "Approve invoices below 1000",
  "version": "1.0"
}
```

(Keys sorted lexicographically. `version` is included via the §4.4 default — bumping it requires re-signing.)

### 11.4 The fingerprint

`SHA-256` of the canonical JSON serialisation above. Carry this in any signing envelope (JWS, COSE, VC Data Integrity, or a sidecar `*.sig` file).

---

## 12. Verifier checklist (Informative)

The order a verifier SHOULD process a signed cog:

1. **Read the cog and any signature envelope.** If the envelope is detached, locate the corresponding cog file.
2. **Resolve the contract scope** per §4.4 precedence:
    - Explicit `contractFields` on the cog (authoritative when present).
    - Otherwise, resolve `schema:` and apply `x-mx-contract` annotations.
    - Otherwise, apply defaults in §4.4 step 3.
   Surface the resolved scope and its source in any verification log.
3. **Check §4.3 mandatory fields.** `title`, `validatesAgainst`, `schema` MUST all be present and well-formed.
4. **Run every validator named in `validatesAgainst`.** All MUST pass at verification time. A validator that no longer resolves is a verification failure.
5. **Compute the projection.** Build the canonical JSON object containing only the contract-scope keys, sorted lexicographically, with values canonicalised per §5.3.
6. **Hash the projection with SHA-256.** Compare to the fingerprint the signature was applied over.
7. **Verify the signature** using the appropriate envelope's verification algorithm (JWS, COSE, VC, etc.).
8. **Report.** Use the precise word **attested** for a successful verification. Do not say *verified* — that implies a truth claim no signer makes (§9).
9. **Fail closed.** Any verification failure (validator, fingerprint mismatch, signature failure) MUST surface as an explicit failure. Verifiers MUST NOT downgrade a failed verification to a warning.

---

## 13. Common authoring mistakes (Informative)

Five shapes a fresh author often produces, each with the fix.

**Mistake 1: signing without `validatesAgainst`.**

```yaml
# WRONG — §4.3 mandatory: a signed cog MUST declare validatesAgainst
title: "Approve invoices below 1000"
schema: ./schemas/invoice-approval.v1.yaml
contractFields: [title, schema, thresholds]
```

A signer MUST refuse to sign this cog. Add a non-empty `validatesAgainst` array; every entry MUST resolve to a registered validator and MUST pass at sign time.

**Mistake 2: overlapping arrays.**

```yaml
# WRONG — `tags` appears in both
contractFields: [title, schema, tags]
metadataFields: [created, modified, tags]
```

The two arrays MUST be disjoint (§4.1, §4.2). Move `tags` to one or the other and remove it from the other.

**Mistake 3: bumping version expecting the signature to survive.**

```yaml
# Original (signed)
version: "1.0"

# Edited (signature now invalid)
version: "1.1"
```

`version` is in the default contract scope (§4.4). Bumping it changes the projection and invalidates the signature. The intended workflow is: edit content → bump version → re-sign. Never expect a single signature to survive a version bump.

**Mistake 4: schema-derivation with no annotations.**

```yaml
# Schema with no x-mx-contract annotations
$id: ./schemas/foo.v1.yaml
type: object
properties:
  title: { type: string }
  thresholds: { type: object }
```

Schema-derivation (§4.4 step 2) needs explicit `x-mx-contract: true` or `false` annotations on each property the author intends to classify. A schema with no annotations falls through entirely to step 3 (defaults) — the schema is not actually doing any work.

**Mistake 5: claiming the signature *verifies* the values.**

```text
✓ Cog verified — values are correct.
```

The signature attests provenance and integrity, not truth (§9). The cog came from the named signer unaltered; whether `autoApproveBelow: 1000` is the right policy is not something a signature can answer. User-facing language SHOULD say **attested**, not *verified*.

---

*End of MX Contract Fingerprinting and Signing note draft.*

---

## MX Compliance Claims note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-compliance-claims.md
**File:** `draft-compliance-claims.md`

# MX Compliance Claims note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 8 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies how a digital artefact carries a verifiable claim of conformance to a named external standard. It defines the structure of a compliance claim, the authority model under which a claim is issued, the evidence it must reference, and the rules for expiry and revocation.

A compliance claim is a signed, dated, revocable assertion that a predicate holds true about a subject. The subject is an addressable artefact (a web page, a PDF, a video, an MX cog). The predicate names a published external standard and the conformance level reached. The authority is the party issuing the claim. The evidence is the documented basis on which the claim was made.

The note is deliberately framework-agnostic: it specifies the primitive — a signed, dated, revocable claim about a digital artefact — not any single regulator's rulebook. Mappings from this primitive to specific regimes (WCAG, EU AI Act, sector-specific compliance) are layered on top through predicate vocabularies that the claim references but does not embed.

The note motivates two authority types from the outset: **self-attestation**, where the publisher of the artefact issues a claim about their own work, and **third-party attestation**, where an independent party issues a claim about an artefact they did not produce. Both types use the same claim structure and signature mechanism. The standard specifies what each authority type MUST declare; it does not specify the procedures by which any specific accreditation body admits, monitors, or revokes third-party authorities, leaving that to operators of accreditation programmes built on this standard.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here.

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of this draft set). That pattern governs the structural template for every field and is binding on this note. This note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

A compliance claim claiming conformance to this note SHALL satisfy:

| Level | Name | Claim requirement |
|-------|------|-------------------|
| Level 1 | **Self-Attested** | A signed claim with subject identity and hash, predicate identifier and version, authority of type `self` with verifiable signing identity, issuedAt timestamp |
| Level 2 | **Verified** | Level 1 plus documented evidence (method and report URI with report hash), expiresAt timestamp, and a revocation list URI |
| Level 3 | **Independently Attested** | Level 2 plus an authority of type `third-party` carrying a declared accreditation reference, where the third-party authority is distinct from the subject's publisher |

A claim of conformance SHALL state the level reached. A claim that does not reach Level 1 is not a claim under this standard.

The three levels are strictly nested: a Level 3 claim satisfies all Level 2 and Level 1 requirements. A consumer of claims MAY reject lower-level claims for high-stakes evaluations, and MAY accept Level 1 claims for low-stakes evaluations such as user-facing badges.

### 2.2 Draft status

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the field definitions, conformance requirements, and normative rules in this note are working drafts — stable enough to build against, expected to evolve through review. Implementations of this draft SHOULD note the draft version number they implemented against.

---

## 3. Scope

### 3.1 In scope

- The structure of a compliance claim: required and optional fields, types, and serialisation.
- The authority model: `self` and `third-party` authority types, what each MUST declare, and how a third-party authority's accreditation is referenced.
- The evidence model: how a claim points to a documented basis without embedding it.
- The expiry and revocation model: how a claim becomes inert.
- The signature contract: which fields are covered, in what canonical form.
- The relationship between a claim and the artefact it is about: subject identification and hash binding.
- Predicate vocabulary requirements: what a published predicate vocabulary MUST declare for a claim to reference it.
- A worked example mapping the claim structure to the [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA conformance claim.

### 3.2 Out of scope

- **Predicate vocabulary content.** This note does not enumerate the predicates of any specific regulatory regime. WCAG, EU AI Act, sector-specific frameworks, and similar regimes are referenced as predicate vocabularies but are not specified here.
- **Accreditation programmes for third-party authorities.** Who admits a third-party authority, what bar they must meet, how their accreditation is monitored and revoked — these are operational concerns for accreditation programmes built on this standard, not for the standard itself.
- **Cryptographic mechanics of signing and verification.** Canonicalisation, signature algorithms, and signature verification procedures defer to the **MX Contract Fingerprinting and Signing note**.
- **Provenance of the artefact.** Who created the artefact, when, and on what basis is governed by the **MX Provenance note**. A compliance claim assumes provenance metadata may be present but does not redefine it.
- **Registry mechanics.** How claims are stored, indexed, and looked up by consumers is implementation-defined. This note specifies what a claim contains and how it is verified, not where it lives.
- **Badge presentation.** How a claim is rendered as a user-facing visual badge is implementation-defined.

### 3.3 Relationship to existing standards

This note relies on:

- **[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119)** and **[RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)** for normative key words.
- **[RFC 7515 JSON Web Signature](https://datatracker.ietf.org/doc/html/rfc7515)** for the baseline signature serialisation.
- **[RFC 8032 EdDSA](https://datatracker.ietf.org/doc/html/rfc8032)** as the RECOMMENDED signature algorithm.
- **[RFC 8615 Well-Known URIs](https://datatracker.ietf.org/doc/html/rfc8615)** for revocation list discovery.
- **[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)** for date and time fields.
- **[W3C Decentralized Identifiers (DID) v1.0](https://www.w3.org/TR/did-core/)** for authority identifier syntax (informative; the field accepts URIs more broadly).
- **[C2PA Content Credentials v1.x](https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html)** as the recommended interoperability target for content provenance attestations specifically; a claim about content provenance MAY embed or reference a C2PA manifest.

This note relies on the **MX Field Definition Pattern note** for field-definition discipline, the **MX Contract Fingerprinting and Signing note** for the cryptographic contract over the claim payload, and the **MX Provenance note** for prior-art on the difference between a content origin record and a conformance assertion.

This note adds nothing to the standards above; it specifies how they combine for the verifiable-compliance-claim case.

---

## 4. Claim structure

A compliance claim is a structured object carried alongside or within a digital artefact. Implementations MAY serialise the claim as JSON, YAML, or as a JWS payload over JSON; the field set and semantics in this section are normative across serialisations.

### 4.1 Top-level claim object

A claim object MUST declare the following top-level fields:

| Field | Cardinality | Type | Description |
|-------|-------------|------|-------------|
| `claimId` | required | string | Stable, globally unique identifier for the claim. RECOMMENDED form: a URI under the issuing authority's domain. |
| `subject` | required | object | Identification of the artefact the claim is about. See §4.2. |
| `predicate` | required | object | Identification of the conformance assertion. See §4.3. |
| `evidence` | required at Level 2+ | object | Documented basis for the claim. See §4.4. |
| `authority` | required | object | Identification of the issuing party. See §5. |
| `issuedAt` | required | string (ISO 8601) | Date and time the claim was issued. |
| `expiresAt` | required at Level 2+ | string (ISO 8601) | Date and time the claim ceases to be valid without further action. |
| `revocation` | required at Level 2+ | object | Pointer to the revocation list under which this claim's current status can be checked. See §4.5. |
| `signature` | required | object | The signature over the canonical claim. See §4.6. |

Implementations MAY define additional fields under an extension prefix per the **MX Extensions note**. Implementations MUST NOT redefine or override the fields above.

### 4.2 Subject

The `subject` object identifies the artefact the claim is about. It MUST declare:

| Field | Cardinality | Type | Description |
|-------|-------------|------|-------------|
| `uri` | required | string (URI) | Addressable identifier of the artefact. For web artefacts, the canonical URL. For non-web artefacts, a URI of any scheme that can be resolved by a consumer. |
| `hash` | required | string | Content hash of the artefact at the moment of claim issuance. |
| `hashAlgorithm` | required | string | The hashing algorithm used. RECOMMENDED: `sha-256`. |
| `mediaType` | RECOMMENDED | string | The artefact's media type at the moment of claim issuance. |

Where the artefact is an MX cog with a `schema:` annotation, the `hash` field MAY be the contract fingerprint defined by the **MX Contract Fingerprinting and Signing note**. Where it is not, the `hash` field MUST be the hash of the artefact's full byte sequence.

A claim is bound to a specific byte sequence. If the artefact is modified, the prior claim does not transfer; a new claim against the new hash is required. This is intentional and not an implementation defect.

### 4.3 Predicate

The `predicate` object identifies the conformance assertion: which standard, which level, which version. It MUST declare:

| Field | Cardinality | Type | Description |
|-------|-------------|------|-------------|
| `vocabulary` | required | string (URI) | URI of the published predicate vocabulary the claim references. |
| `vocabularyVersion` | required | string | The version of the predicate vocabulary the claim references. |
| `claim` | required | string | An identifier defined by the predicate vocabulary, naming the specific assertion being made. |
| `parameters` | OPTIONAL | object | Vocabulary-defined parameters that further qualify the claim (for example a conformance level). |

A predicate vocabulary is any document that declares one or more `claim` identifiers, each with a defined meaning. A predicate vocabulary published outside this standard MUST declare:

- A versioned URI under which it is reachable.
- For each `claim` identifier: its name, its meaning, the parameters it accepts, and the evidence requirements that an issuer of this `claim` SHOULD meet.

The standard does not constrain who publishes a predicate vocabulary. A regulatory body, a standards organisation, or a sector consortium MAY publish a vocabulary. Consumers of claims judge a claim's weight partly by the vocabulary's source.

### 4.4 Evidence

The `evidence` object documents the basis for the claim. It is OPTIONAL at Level 1 and REQUIRED at Level 2 and above. Where present, it MUST declare:

| Field | Cardinality | Type | Description |
|-------|-------------|------|-------------|
| `method` | required | string (enum) | One of: `selfTest`, `automatedScan`, `manualReview`, `independentAudit`. The method by which the claim's basis was established. |
| `report` | required | string (URI) | Pointer to the evidence report. The report MUST be retrievable by a consumer authorised to evaluate the claim. |
| `reportHash` | required | string | Content hash of the evidence report at issuance time. |
| `reportHashAlgorithm` | required | string | The hashing algorithm used for `reportHash`. |
| `tooling` | OPTIONAL | array of strings | Identifiers (name and version) of any tools used to produce the evidence. |

The `method` enum is not exhaustive; predicate vocabularies MAY define additional values. Vocabulary-defined values MUST be prefixed with the vocabulary's namespace per the **MX Extensions note** to avoid collision.

### 4.5 Revocation

The `revocation` object provides a mechanism for invalidating a claim before its `expiresAt`. It is REQUIRED at Level 2 and above. Where present, it MUST declare:

| Field | Cardinality | Type | Description |
|-------|-------------|------|-------------|
| `listUri` | required | string (URI) | URI of the revocation list under which this claim's current status is published. |
| `checkInterval` | RECOMMENDED | string (ISO 8601 duration) | Recommended polling interval for high-assurance consumers. |

A revocation list is a signed document published by the issuing authority listing all revoked `claimId` values currently within their `expiresAt` window. The signature on the revocation list MUST be verifiable using the same authority identity declared in the claim's `authority.identity` field.

A consumer treating the claim as authoritative SHOULD check the revocation list before relying on the claim. A consumer that does not check the revocation list accepts the risk that a revoked claim is still being treated as valid.

### 4.6 Signature

The `signature` object carries the cryptographic signature over the canonical claim. It MUST declare:

| Field | Cardinality | Type | Description |
|-------|-------------|------|-------------|
| `algorithm` | required | string | The signature algorithm. RECOMMENDED: `Ed25519`. |
| `value` | required | string | The signature value, base64url-encoded. |
| `publicKey` | RECOMMENDED | string | The public key under which the signature can be verified, in PEM or JWK form. MAY be omitted where the public key is discoverable from `authority.identity`. |

The canonical form of the claim payload over which the signature is computed is defined by the **MX Contract Fingerprinting and Signing note**. The `signature` object itself is not part of the canonical payload.

---

## 5. Authority model

The `authority` object identifies the party issuing the claim. The standard defines two authority types: `self` and `third-party`. Both types use the same `authority` object structure. The semantics of each type, and what each MUST declare, are specified below.

### 5.1 Authority object

The `authority` object MUST declare:

| Field | Cardinality | Type | Description |
|-------|-------------|------|-------------|
| `type` | required | string (enum) | Either `self` or `third-party`. |
| `identity` | required | string (URI) | Identifier of the issuing party. RECOMMENDED forms: a DID, a URI under the issuer's domain, or an https URL serving the issuer's verifiable identity document. |
| `name` | RECOMMENDED | string | Human-readable name of the issuer. |
| `accreditation` | required when `type` is `third-party` | object | See §5.3. |

### 5.2 Self-attestation

An authority of type `self` is the publisher of the subject artefact attesting to a property of their own work. Self-attestation is the simplest authority type and the only one available at Level 1 of conformance.

A self-attesting authority MUST satisfy:

- The `authority.identity` field MUST resolve to an identity verifiably associated with the publisher of the subject artefact. A consumer MUST be able to confirm, by a means defined by the publisher's identity scheme, that the signing identity is the publisher's.
- The signature on the claim MUST be produced by a key controlled by the publisher.

Self-attested claims carry the assurance level of the publisher's identity. They are appropriate for user-facing badges and low-stakes consumer signals. They are not appropriate for evidence-trail use cases where the consumer's interest is in independent confirmation of the publisher's claim.

### 5.3 Third-party attestation

An authority of type `third-party` is a party distinct from the subject artefact's publisher, attesting to a property they have evaluated. Third-party attestation is REQUIRED for Level 3 conformance.

A third-party authority MUST satisfy:

- The `authority.identity` field MUST resolve to an identity verifiably distinct from the publisher of the subject artefact.
- The signature on the claim MUST be produced by a key controlled by the third-party authority and not by the subject's publisher.
- The `authority.accreditation` object MUST be present and MUST declare:

| Field | Cardinality | Type | Description |
|-------|-------------|------|-------------|
| `body` | required | string (URI) | URI of the accrediting body that certifies the third-party authority for the predicate vocabulary in question. |
| `reference` | required | string | Identifier under which the third-party authority's accreditation is recorded by the accrediting body. |
| `validFrom` | required | string (ISO 8601) | Date the accreditation became effective. |
| `validUntil` | required | string (ISO 8601) | Date the accreditation expires. |
| `lookupUri` | RECOMMENDED | string (URI) | URI under which a consumer can verify the accreditation in real time. |

The standard does not specify who runs an accrediting body, what bar a third-party authority MUST meet to be accredited, or how an accrediting body monitors and revokes accreditations. These are operational concerns for accreditation programmes built on this standard. The standard requires only that the claim declare the accreditation reference verifiably, so that a consumer can decide whether to trust the accrediting body.

A consumer evaluating a Level 3 claim SHOULD:

1. Verify the claim's signature against the third-party authority's identity.
2. Resolve the accreditation reference and confirm the accreditation is current (within `validFrom` and `validUntil` and not revoked).
3. Independently judge whether the accrediting body is one whose accreditations the consumer accepts.

The third step is the consumer's own decision and is not constrained by the standard. A consumer MAY accept claims accredited by some bodies and not others.

### 5.4 Authority hash separation

The standard intentionally separates authority verification (the claim is signed by the declared issuer) from accreditation verification (the issuer is accredited to make this kind of claim). Both verifications are independent. A claim MAY be signed by a verifiable identity that is not accredited, in which case it is a malformed Level 3 claim and consumers SHOULD treat it as Level 1 at most.

---

## 6. Predicate vocabularies

A predicate vocabulary defines the meaning of `predicate.claim` identifiers. This note does not constrain the content of any predicate vocabulary; it specifies the structural requirements a vocabulary MUST satisfy to be referenced by a compliant claim.

### 6.1 Vocabulary requirements

A predicate vocabulary that is referenced by a compliance claim MUST:

- Be reachable at a stable, versioned URI.
- Carry an explicit version identifier that distinguishes successive revisions.
- For each defined `claim` identifier, declare:
  - The identifier's exact spelling and case.
  - The conformance condition the identifier asserts.
  - The parameters the identifier accepts (with their types and meanings).
  - The evidence method or methods that are appropriate for the identifier (one or more of the values in §4.4 or vocabulary-defined extensions).

Vocabularies SHOULD additionally declare:

- A normative reference to the external standard the vocabulary describes (the standard whose conformance the claims assert).
- An expiry policy stating the recommended `expiresAt` window for claims using the vocabulary.

A claim MUST cite the vocabulary version it was issued against. Vocabularies SHOULD use semantic-style versioning so consumers can reason about compatibility across versions.

### 6.2 Worked example: WCAG 2.2 Level AA

The following illustrates a Level 2 self-attested claim asserting that a web page meets the [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA conformance requirements as evaluated by an automated scan.

```yaml
claimId: https://example.com/.well-known/mx/claims/2026-05-08-home-wcag22-aa
subject:
  uri: https://example.com/
  hash: 4b5c0a8d3e7f1c9b6a2d4e8f0c1b3a5d7e9f1c3b5a7d9e1f3c5b7a9d1e3f5c7b
  hashAlgorithm: sha-256
  mediaType: text/html
predicate:
  vocabulary: https://example.org/vocabularies/wcag-2.2-mx.v0.1
  vocabularyVersion: "0.1"
  claim: wcagConformance
  parameters:
    level: AA
    wcagVersion: "2.2"
evidence:
  method: automatedScan
  report: https://example.com/.well-known/mx/evidence/2026-05-08-home-wcag22-aa.json
  reportHash: 9a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c
  reportHashAlgorithm: sha-256
  tooling:
    - "axe-core 4.9.1"
authority:
  type: self
  identity: https://example.com/.well-known/mx/identity.json
  name: "Example Publisher Ltd"
issuedAt: 2026-05-08T10:30:00Z
expiresAt: 2027-05-08T10:30:00Z
revocation:
  listUri: https://example.com/.well-known/mx/revocations.json
  checkInterval: P1D
signature:
  algorithm: Ed25519
  value: "qS9PvL7eZ0kTu4yX3fA1nM6dC8bV2lH5gW0rJ4iE7sQ_..."
```

The same claim, issued by an independent third-party authority accredited by an accreditation body, would carry an `authority` object of:

```yaml
authority:
  type: third-party
  identity: did:web:auditor.example.org
  name: "Independent Audit Co"
  accreditation:
    body: https://accreditation-body.example.org/
    reference: "ACR-2026-7842"
    validFrom: 2026-01-01
    validUntil: 2027-12-31
    lookupUri: https://accreditation-body.example.org/registry/ACR-2026-7842
```

This second form satisfies Level 3 of conformance because the `authority.type` is `third-party`, the `authority.identity` is distinct from the subject's publisher, and a verifiable accreditation reference is declared. A consumer who accepts accreditations from `accreditation-body.example.org` would treat this as a stronger evidence trail than the self-attested form.

The standard does not name the WCAG predicate vocabulary's publisher. A vocabulary mapping WCAG 2.2 conformance into the MX claims structure may be published by W3C, by an accessibility consortium, by an accreditation body, or by any party meeting §6.1's requirements. Consumers judge weight by the vocabulary's provenance.

### 6.3 Vocabulary discoverability

A claim MAY include a copy of the predicate vocabulary's metadata (its title, version, and publisher) inline as informational fields under an extension prefix. Inline copies are not normative; the canonical reference is the `predicate.vocabulary` URI. A consumer MUST resolve the URI to determine the binding meaning of the claim.

---

## 7. Why a separate compliance-claims standard

A reader may reasonably ask whether existing standards already cover this ground. They cover adjacent ground; none cover this exactly.

[C2PA Content Credentials](https://c2pa.org/) specify how a content asset carries claims about its origin and modification history. They are tightly bound to media files (images, video, audio) and the C2PA manifest format. The MX Compliance Claims structure is broader: it covers any addressable artefact (a web page, an HTML document, an MX cog, a PDF, a dataset) and any predicate vocabulary (not only provenance assertions). A claim under this standard MAY embed a C2PA manifest as evidence, and a C2PA manifest MAY be the basis for a claim issued under this standard. The two are complementary.

[Verifiable Credentials (W3C VC) v2.0](https://www.w3.org/TR/vc-data-model-2.0/) specify a general model for credentials: an issuer asserts that a subject has properties, and the assertion is signed and verifiable. The VC model is more general than what a compliance claim needs and less specific about the dimensions the compliance use case requires (subject hashing, evidence URIs and report hashes, expiry-and-revocation defaults, predicate vocabularies as a first-class concept). A compliance claim under this note MAY be expressed as a Verifiable Credential by mapping the fields above to the VC model; the standard does not require that mapping but does not prohibit it.

[XAdES](https://www.w3.org/TR/XAdES/) and [PAdES](https://www.etsi.org/deliver/etsi_en/319100_319199/31914201/) specify advanced electronic signature formats for XML and PDF respectively. They describe how a signature is formatted and bound to the carrier. They do not specify the claim being signed. A compliance claim under this note MAY be signed using PAdES inside a PDF, but the claim's structure (subject, predicate, evidence, authority, expiry, revocation) is what this note defines.

Regulatory regimes (the EU AI Act's Article 13 transparency obligations, the European Accessibility Act's conformity assessments, sector-specific compliance) prescribe what evidence a regulated party MUST produce. They do not prescribe a portable, machine-readable, signed envelope for that evidence. The MX Compliance Claims structure is the envelope. A given regulatory regime is one possible predicate vocabulary; the standard supports any.

The combination of these gaps is the reason for a separate note. A reader who needs only one of these capabilities should use the matching existing standard. A reader who needs the combination — a portable, signed, dated, revocable, predicate-flexible claim about an arbitrary digital artefact — has not, until this note, had a single standard to point to.

---

## 8. Implementation guidance (informative)

This section is informative; it is not a normative part of the standard.

### 8.1 Claim discovery

A consumer who has an artefact's URI but not yet a claim about it can discover claims through several patterns:

- **Well-known URI.** The artefact's host serves a `claims.json` (or similar) under `/.well-known/mx/` listing claims about the host's content. RFC 8615 governs the well-known prefix.
- **In-band reference.** The artefact carries a `link rel="mx-compliance-claim"` (HTML), an XMP property (PDF), or an analogous carrier-format mechanism per the **MX Carrier Formats note** pointing at the claim.
- **Registry lookup.** A claim registry indexes claims by subject URI; the consumer queries the registry. This pattern is not part of the standard but is a common implementation.

The standard does not mandate a discovery mechanism; an artefact MAY be served with claims through any combination of the above.

### 8.2 Issuance pipeline

A typical issuance pipeline:

1. The publisher freezes the artefact (commits the bytes, generates the hash).
2. The publisher (for self-attestation) or the third-party authority (for third-party attestation) runs the evidence method against the artefact and produces an evidence report.
3. The issuer composes the claim object: subject, predicate, evidence, authority, issuedAt, expiresAt, revocation pointer.
4. The issuer canonicalises the claim payload per the **MX Contract Fingerprinting and Signing note**, signs it with their key, and attaches the signature.
5. The issuer publishes the claim alongside the artefact (or in a registry pointed at by the artefact).
6. The issuer retains the signing material and is prepared to publish revocations on the declared revocation list.

For high-volume publishers, steps 1 to 4 are commonly automated as part of a build pipeline. For audit-grade third-party claims, steps 2 and 3 are manual and reviewed.

### 8.3 Verification pipeline

A typical verification pipeline:

1. Resolve the claim from the artefact (or from the claim's own URI).
2. Recompute the subject hash from the artefact and confirm it matches `subject.hash`. If it does not, the claim does not apply to the bytes the consumer has.
3. Resolve `authority.identity` and obtain the public key.
4. Verify the signature on the canonical claim payload.
5. For Level 2+: confirm `issuedAt <= now <= expiresAt`.
6. For Level 2+: fetch the revocation list from `revocation.listUri`, verify its signature, and confirm the `claimId` is not present.
7. For Level 3: fetch the accreditation reference from `authority.accreditation.lookupUri` (or `body`) and confirm the accreditation is current.
8. Resolve `predicate.vocabulary` and `predicate.vocabularyVersion` to determine the binding meaning of `predicate.claim`.
9. Decide, based on the consumer's policy, whether to accept the claim.

The verification pipeline is implementation-defined in detail; the steps above are the typical shape.

### 8.4 Revocation policy

A practical revocation policy:

- The revocation list is published at a stable URI and refreshed at a known cadence.
- Each revocation entry carries the `claimId`, the `revokedAt` timestamp, and a `reason` field with a vocabulary-defined value.
- The revocation list is signed by the same authority as the claims it revokes.
- When an artefact is updated, prior claims about the older bytes are not automatically revoked; they remain valid for the bytes they were issued against. New claims are issued against the new bytes. Consumers verifying step 2 of §8.3 will detect that an old claim does not apply to new bytes without needing the revocation list.

---

## 9. Security and privacy considerations

This section is normative.

### 9.1 Signature compromise

If an authority's signing key is compromised, all claims signed by that key are suspect. The authority MUST revoke all outstanding claims and MUST publish a key compromise notice at the same URI as the revocation list. Consumers who have cached claims from the compromised authority SHOULD re-evaluate them on next use.

The standard does not require key rotation on a fixed schedule; it requires that the authority be operationally able to revoke the entire claim set on key compromise.

### 9.2 Subject substitution

A consumer who fails to recompute and compare the subject hash (step 2 of §8.3) accepts the risk that the bytes it has are not the bytes the claim was issued against. This failure mode is the most likely source of false-positive verifications and SHOULD be hard-coded into any compliant verification implementation.

### 9.3 Evidence retrieval

The `evidence.report` URI may be private (auditor-held, regulator-held) or public. A consumer who lacks authorisation to retrieve the evidence MAY still verify the claim's signature and binding to the subject; it cannot independently inspect the basis. This is an intentional two-tier model: signature verification is universal, evidence inspection is conditional.

A consumer that requires evidence inspection (a regulator, an internal compliance team) MUST establish access to the evidence URI through a means out of scope here.

### 9.4 Privacy

A claim necessarily exposes:

- The fact that the subject artefact was claimed against a specific predicate.
- The identity of the authority.
- The hash of the subject at issuance time.

A claim does not necessarily expose:

- The content of the evidence report (governed by `evidence.report` access control).
- The identity of human reviewers within the authority (governed by what the authority chooses to publish).

Where claim publication itself raises privacy concerns (a claim about a private dataset's GDPR conformance, for example), the issuer MAY publish the claim only to authorised consumers via access-controlled distribution, accepting that the claim is then not a public attestation. The standard accommodates both modes.

### 9.5 Replay and reuse

A claim is bound to a specific subject hash and has a specific `claimId` and `issuedAt`. It cannot be replayed against a different subject without breaking the signature. It can, however, be presented to multiple consumers; this is intentional. Consumers MUST NOT treat a claim as freshly issued to them; they MUST evaluate `issuedAt`, `expiresAt`, and revocation against current time.

### 9.6 Vocabulary substitution

A predicate vocabulary's URI is referenced but not embedded. A vocabulary publisher who modifies the meaning of an existing `claim` identifier without bumping `vocabularyVersion` undermines all outstanding claims against that identifier. Vocabulary publishers MUST treat existing identifiers as immutable within a version and MUST bump `vocabularyVersion` on any change to identifier meaning.

Consumers SHOULD pin to specific `vocabularyVersion` values for high-stakes evaluations and re-evaluate on vocabulary upgrade.

---

## 10. IANA considerations

This note proposes no new IANA registrations.

A future revision MAY propose:

- A `mx-compliance-claim` link relation type for in-band claim references.
- A `application/mx-compliance-claim+json` media type for serialised claims.
- A `/.well-known/mx/claims/` URI suffix.

These are deferred to a later revision once implementation experience justifies the registration.

---

## 11. References

### 11.1 Normative

- [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) — Key words for use in RFCs.
- [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) — Ambiguity of uppercase vs lowercase in RFC 2119 key words.
- [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515) — JSON Web Signature (JWS).
- [RFC 8032](https://datatracker.ietf.org/doc/html/rfc8032) — Edwards-Curve Digital Signature Algorithm (EdDSA).
- [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) — Well-Known Uniform Resource Identifiers.
- [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) — Date and time format.

### 11.2 Informative

- [W3C Decentralized Identifiers (DID) v1.0](https://www.w3.org/TR/did-core/) — Identifier syntax for decentralised authorities.
- [W3C Verifiable Credentials Data Model v2.0](https://www.w3.org/TR/vc-data-model-2.0/) — General-purpose credential model that compliance claims MAY be expressed under.
- [C2PA Content Credentials](https://c2pa.org/) — Content provenance manifests; relevant for claims whose predicate concerns content origin.
- [W3C WCAG 2.2](https://www.w3.org/TR/WCAG22/) — Web Content Accessibility Guidelines, used as the worked predicate vocabulary in §6.2.
- MX Field Definition Pattern note — Field-definition discipline this note adopts.
- MX Contract Fingerprinting and Signing note — Canonicalisation and signature mechanics this note defers to.
- MX Provenance note — Content origin and stewardship vocabulary.
- MX Carrier Formats note — Carrier-format mappings for claim references in HTML, PDF, and other formats.

---

## 12. Acknowledgements

This note builds on prior work in C2PA Content Credentials, W3C Verifiable Credentials, and the broader content-attestation community. It is informed by the practical experience of issuing and verifying conformance claims in regulated content programmes over many years, and by the gap-analysis exercise that motivated its drafting in early 2026.

---

## MX Attestation Records and Verification note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-attestation-records.md
**File:** `draft-attestation-records.md`

# MX Attestation Records and Verification note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 15 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies the **attestation record** — a cog produced by an MX trust layer that wraps another cog with cryptographic apparatus. The attestation record references the attested cog by ID and digest; the attested cog is unchanged. A cog can be unattested, attested by one trust layer, or attested independently by several, without any change to its schema or bytes.

The note defines the record's fields, the relationship between the attestation and the cog it covers, and the verification model: trust layers **produce** attestations on submission and **serve** them on retrieval; verification is a client-side operation against existing standards. The registry serves; verifiers verify.

The signing and canonicalisation mechanics referenced here are inherited unchanged from the **MX Contract Fingerprinting and Signing note**; this note specifies only the record format and the lifecycle around it.

---

## 2. Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) when, and only when, they appear in all capitals.

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of the draft set). That pattern governs the structural template for every field; this note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

A trust layer or verifier claiming conformance to this note SHALL satisfy:

- **Level 1 (record format)** — Produced attestation records carry the §4.2 fields, well-formed; absent fields are not silently defaulted.
- **Level 2 (verification correctness)** — Level 1 plus: a verifier resolves the attested cog by ID and digest, recomputes the fingerprint per the MX Contract Fingerprinting and Signing note §5, and surfaces any mismatch as an explicit failure.
- **Level 3 (independent verifiability)** — Level 2 plus: the attestation record can be verified offline given the attested cog, the record, and the public key material referenced by `issuedBy`, with no live call to the issuing trust layer.

A claim of conformance SHALL state the level reached.

### 2.2 Draft status

This is a draft note. Conformance levels and field semantics MAY change in response to community review. Implementations SHOULD note the draft version they implemented against.

---

## 3. Scope

### 3.1 In scope

- The fields of an attestation record (§4.2).
- The reference direction between an attestation and the cog it attests (§4.1).
- The lifecycle around production, retrieval, and verification (§4.3–§4.5).
- The batching mechanism for high-volume attestation (§4.6), inheriting Merkle-tree mechanics from existing publications.

### 3.2 Out of scope

- The fingerprint algorithm itself — defers to the **MX Contract Fingerprinting and Signing note** §5.
- Signature algorithms (Ed25519, ECDSA, RSA, post-quantum) — defer to [W3C VC Data Integrity](https://www.w3.org/TR/vc-data-integrity/), [JWS (RFC 7515)](https://datatracker.ietf.org/doc/html/rfc7515), or [COSE (RFC 9052)](https://datatracker.ietf.org/doc/html/rfc9052).
- DID method specifics for `issuedBy` — defer to [W3C DID Core](https://www.w3.org/TR/did-core/).
- Key management, distribution, rotation, and revocation infrastructure — open questions (§7).
- Compliance claims about external standards — owned by the **MX Compliance Claims note**.

### 3.3 Relationship to existing standards

| Standard | Relationship |
|----------|--------------|
| **MX Contract Fingerprinting and Signing note** | Defines the canonicalisation and signing model this note builds on. The attestation record carries the signature; §5 of the sister note specifies what was signed. |
| **MX Compliance Claims note** | Adjacent: a compliance claim *is* a signed cog and MAY itself be wrapped in an attestation record by a trust layer. |
| [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) | Date and time format used by `issuedAt`. |
| [W3C DID Core](https://www.w3.org/TR/did-core/) | Identifier format used by `issuedBy` and by the key reference inside `signature`. |
| [RFC 6962](https://datatracker.ietf.org/doc/html/rfc6962) | Certificate Transparency Merkle-tree mechanics — referenced by §4.6 batching. |

---

## 4. Attestation records and verification

### 4.1 Position

An attestation record is produced by a trust layer — an MX registry operator — and wraps a cog with cryptographic apparatus. The cog itself is unchanged. The attestation references the cog by ID and digest.

The cog is data. The attestation is the trust wrapper. The two are deliberately separated (§3.1): a cog can be unattested, attested by one registry, or attested by a different registry, without any change to the cog's schema or bytes.

A trust layer does not verify attestations. It produces them on submission and serves them on retrieval. Verification is a client-side operation against existing standards. The registry serves; verifiers verify.

### 4.2 Attestation record fields

An attestation record is itself a cog. It declares `type: attestation` at the top level (Zone 1b, per the **MX Core Metadata note**). It carries `cogUrn` (the universal identifier of the attestation record itself, in the trust layer's namespace) and `schemaVersion` per the **MX Cogs note** §6.5.3 and §6.5.4. This note specifies the attestation-specific top-level fields below.

| Field | Semantics |
|-------|-----------|
| `attests` | Reference to the cog being attested. Object with `cogUrn` (the attested cog's universal identifier) and `digest` (the SHA-256 of the attested cog's JCS-canonicalised bytes). Batch-root attestations replace `cogUrn`/`digest` with `merkleRoot`, `leafCount`, and `hashFunction`; see §4.6. |
| `issuedBy` | DID of the trust-layer operator (the registry instance that produced the attestation). |
| `issuedAt` | [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp of attestation. |
| `mechanism` | One of `individual` or `merkleBatch`; see §4.6 for batching. |
| `signature` | When `mechanism: individual` (and for batch-root attestations under `merkleBatch`): signature over the attested digest, with algorithm identifier and key reference (DID URL). |
| `batch` | When the record is a per-cog leaf under `merkleBatch`: a `rootAttestation` reference, a `leafIndex`, and an inclusion `proof` array (see §4.6). |

The attestation references the cog by `cogUrn` and digest. The cog does not reference the attestation. This direction matters: a cog can exist without any attestation, and multiple independent attestations of the same cog by different trust layers can coexist without any of them being privileged inside the cog itself.

### 4.3 Production

*(To be drafted: the lifecycle of producing an attestation on submission to a trust layer — what the trust layer MUST check, what it MUST refuse, and what it serialises into the attestation record.)*

### 4.4 Retrieval

*(To be drafted: how a verifier discovers attestations for a given cog. Discovery patterns expected to cover: well-known registry endpoints, sidecar files, in-cog hint fields pointing outward to the registry.)*

### 4.5 Verification

*(To be drafted: the verifier's algorithm — fetch attested cog, recompute fingerprint per the MX Contract Fingerprinting and Signing note §5, resolve `issuedBy` key material, verify signature, surface any mismatch as explicit failure.)*

### 4.6 Batching: `merkleBatch`

*(To be drafted: Merkle-tree batching for high-volume issuance — when one signed root covers a batch of attested cogs and each individual attestation carries an inclusion proof. Modelled on [RFC 6962](https://datatracker.ietf.org/doc/html/rfc6962) Certificate Transparency.)*

---

## 5. *(Reserved for §5)*

*(No content yet. Drop this heading before publishing if no §5 is needed.)*

---

## 6. *(Reserved for §6)*

*(No content yet. Drop this heading before publishing if no §6 is needed.)*

---

## 7. Open questions

The following remain open for community discussion:

1. **Key rotation** — when the key material referenced by `issuedBy` rotates, how does a verifier distinguish a rotation from a revocation, and how are historical attestations validated against retired keys?
2. **Revocation** — how does a verifier discover that a previously valid attestation has been revoked? CRL, OCSP, on-chain registry, an MX registry endpoint?
3. **Cross-registry attestation** — when two trust layers independently attest the same cog, MAY a verifier treat them as additively strengthening trust, or are they always independent claims?
4. **Trust-layer discovery** — how does a verifier discover *which* trust layers have attested a given cog without prior knowledge of those trust layers?

---

## 8. Implementation guidance (informative)

*This section is informative; it is not a normative part of the standard.*

### 8.1 Producing an attestation

*(To be drafted.)*

### 8.2 Verifying an attestation offline

*(To be drafted: the canonical verification pipeline — fetch cog, recompute fingerprint, resolve DID, verify signature, surface result.)*

### 8.3 Verification

*(To be drafted: shell-level commands or other independently runnable checks a verifier can use to confirm conformance.)*

---

## 9. Security and privacy considerations

- An attestation record asserts only that the trust-layer operator named in `issuedBy` produced the record at `issuedAt` and that the attested digest matches the cog at that moment. It does not assert that the cog's values are factually correct, sound, or current. The narrowness is intentional and inherits the rationale from the **MX Contract Fingerprinting and Signing note** §9.
- A trust layer that produces attestations without first checking the cog passes the mandatory-fields check in the **MX Contract Fingerprinting and Signing note** §4.3 produces records whose semantics are degraded; verifiers presented with such records cannot tell from the record alone whether the check was performed. Trust layers SHOULD record, and MAY surface in the attestation, evidence that the pre-signature review pipeline ran.
- The attestation record contains the attested cog's digest, the issuer DID, and a timestamp. A verifier in possession of the record alone can learn which cog was attested, by whom, and when, even without access to the cog body. This is a deliberate property of the format — it is also a privacy consideration in contexts where the attested cog is private.
- Batching mechanics (§4.6) trade per-cog signature cost against the risk that compromise of a batch root invalidates every member of the batch. Trust layers using `merkleBatch` SHOULD document their batch size policy and the consequences of a compromised root.

---

## 10. IANA considerations

This note proposes no new IANA registrations.

---

## 11. References

### 11.1 Normative references

- [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) — keywords for use in RFCs to indicate requirement levels.
- [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) — Date and Time on the Internet: Timestamps.
- [W3C DID Core](https://www.w3.org/TR/did-core/) — Decentralised Identifiers (DIDs) v1.0.
- **MX Contract Fingerprinting and Signing note** — canonicalisation, fingerprint, and signing model on which this note builds.
- **MX Core Metadata note** — Zone 1 / Zone 2 frontmatter, `contentType`, `version`.

### 11.2 Informative references

- [W3C Verifiable Credentials Data Integrity](https://www.w3.org/TR/vc-data-integrity/) — compatible signing model.
- [JWS RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515) — JSON Web Signature.
- [COSE RFC 9052](https://datatracker.ietf.org/doc/html/rfc9052) — CBOR Object Signing and Encryption.
- [RFC 6962](https://datatracker.ietf.org/doc/html/rfc6962) — Certificate Transparency, the model behind §4.6 batching.
- [C2PA Content Credentials](https://c2pa.org/) — compatible model for signing assertions about content provenance.

---

*End of MX Attestation Records and Verification note draft.*

---

## MX Decision Records note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-decision-records.md
**File:** `draft-decision-records.md`

# MX Decision Records note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 17 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies the **decision record** — a cog produced by an operator of an automated decision system that records one decision (or one batched group of decisions) against the policy in force at the time. The record carries enough metadata for an auditor to reason about whether the published policy was followed at the moment the decision was made; it does not carry the decision's input data, nor does it assert the correctness of the decision.

The note defines the record's fields, the relationship between a decision record and the policy it cites, and the boundary between what the record claims (an event occurred, against a named policy version, with a named model) and what it does not claim (that the decision was correct, that the model was suitable, or that the policy itself was sound).

Decision records combine with **MX Policy Records note** (the cited policy) and **MX Attestation Records and Verification note** (the cryptographic wrapper around the record) to give regulators, auditors, and subjects of decisions a queryable evidence chain. Each of those three records is a separate cog joined by reference; none of them substitutes for any of the others.

---

## 2. Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) when, and only when, they appear in all capitals.

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of the draft set). That pattern governs the structural template for every field; this note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

An operator or consumer claiming conformance to this note SHALL satisfy:

- **Level 1 (record format)** — Produced decision records carry the §4.2 required fields, well-formed; absent fields are not silently defaulted. Field names follow `camelCase`.
- **Level 2 (referential integrity)** — Level 1 plus: every `policyRef` resolves to an existing policy record at the `policyRef.version` named, and the policy record's `effectiveFrom` is at or before the decision's `issued` timestamp.
- **Level 3 (completeness signalling)** — Level 2 plus: records declare a `sequence` field that monotonically increases per `(model, inputClass)` pair, supporting gap-detection by consumers.

A claim of conformance SHALL state the level reached.

### 2.2 Draft status

This is a draft note. Conformance levels and field semantics MAY change in response to community review. Implementations SHOULD note the draft version they implemented against.

---

## 3. Scope

### 3.1 In scope

- The fields of a decision record (§4.2).
- The reference direction between a decision record and the policy it cites (§4.4).
- The boundary between what the record claims and what it does not (§4.5, §4.6).
- The relationship to the cited policy record (§4.4) and to a wrapping attestation record (§5).

### 3.2 Out of scope

- Cryptographic apparatus over the record — signatures, batch roots, inclusion proofs — defer to the **MX Attestation Records and Verification note**.
- The schema of the cited policy itself — defers to the **MX Policy Records note**.
- Privacy treatment of the record's body content (`outputSummary`, human-readable description) where it contains personal data. Compliance with [GDPR Article 5(1)(c)](https://gdpr-info.eu/art-5-gdpr/) data minimisation is the operator's responsibility, not this note's.
- Subject-counter-signing mechanisms by which a subject corroborates a decision; that lives in a future companion note.
- Sector-specific profiles (financial services, medical devices, employment) — these are downstream specialisations, not core record semantics.

### 3.3 Relationship to existing standards

| Standard | Relationship |
|----------|--------------|
| **MX Cogs note** | Decision records are cogs. The universal cog fields (`cogUrn`, `schemaVersion`, `partOf`) apply per the MX Cogs note. |
| **MX Core Metadata note** | Doc-identity fields (`title`, `description`, `author`, `created`, `modified`) apply per the MX Core Metadata note. |
| **MX Policy Records note** | A decision record's `policyRef` resolves against a policy record. |
| **MX Attestation Records and Verification note** | A trust-layer attestation wraps a decision record by reference; the decision record itself carries no cryptographic apparatus. |
| [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) | Date and time format used by `issued`. |
| [W3C DID Core](https://www.w3.org/TR/did-core/) | Identifier format used by `operator`. |
| [SHA-256](https://datatracker.ietf.org/doc/html/rfc6234) | Hash function used by `inputHash`. |
| [ULID](https://github.com/ulid/spec) | RECOMMENDED form for the local-id portion of `decisionId`. |

---

## 4. Decision records

### 4.1 Position

A decision record is a structured statement of one decision made by an automated system, sufficient to let an auditor reason about whether the published policy was followed at that moment. The record carries identification, the citation of the policy in force, the model that made the decision, an input commitment (a hash, not the input itself), and a short factual description of the output.

A decision record records **what** the system decided. It does not claim that the decision was correct, that the model was suitable, or that the policy itself was sound. It is a faithful record of an event, nothing more.

The record is carrier-neutral. The fields and their semantics are what constitute the record, not the file format. Any carrier that can hold the fields validly is acceptable: a Markdown file with YAML frontmatter, a JSON document, an HTML page with `<meta>` and JSON-LD, a database row's metadata column, or a log line. The Markdown carrier wraps every field below `mx:` per the MX Cogs note; other carriers express the same fields without that envelope.

### 4.2 Required fields

A decision record declares `type: decision` at the top level (Zone 1b). The following fields are REQUIRED for a valid decision record regardless of carrier. Field names follow `camelCase`.

| Field | Type | Semantics |
|-------|------|-----------|
| `type` | string | Fixed value: `decision`. Top-level (Zone 1b). |
| `schemaVersion` | string | Semver of the decision-record schema this record conforms to (per **MX Cogs note** §6.5.4). |
| `cogUrn` | string | Universal identifier in the form `cog:<operator-namespace>:<local-id>` (per **MX Cogs note** §6.5.3). |
| `decisionId` | string | Operator's internal reference to the decision event; time-sortable. ULIDs are RECOMMENDED. Usually equals the `<local-id>` portion of `cogUrn`. |
| `operator` | string | DID or resolvable identifier of the operator (the AI system's deployer or controller). |
| `issued` | string | [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp of the decision. |
| `policyRef` | object | Reference to the policy record in force: registry URI, policy `cogUrn`, version, optional clause fragment. See §4.4. |
| `model` | object | Model identifier, version, and reference to the model card. See §4.3. |
| `inputHash` | string | SHA-256 of the canonicalised input. The input itself stays with the operator. |
| `inputClass` | string | Operator-defined category of input. Supports sequence-based completeness reasoning per §6. |
| `outputSummary` | string | Short factual description of the output. Human-readable. |
| `humanInLoop` | object | Whether human review was required, whether it fired, and an opaque reviewer reference. See §4.5. |

The following field is OPTIONAL but RECOMMENDED:

| Field | Type | Semantics |
|-------|------|-----------|
| `sequence` | integer | Per-`(model, inputClass)` monotonically increasing counter. Enables consumers to detect missing records by inspecting for gaps. See §6. |

A decision record MUST NOT carry trust-wrapper apparatus inline. Signatures, batch roots, and inclusion proofs live in a separate attestation record per the **MX Attestation Records and Verification note**, referencing the decision record by `cogUrn` and content digest. There is no `attestation` field on a decision record; there is no `batchRef` field.

### 4.3 The `model` block

The `model` field is an object with the following sub-fields:

| Sub-field | Type | Semantics |
|-----------|------|-----------|
| `id` | string | Stable identifier for the model (vendor namespace plus model name). |
| `version` | string | Version identifier of the specific model instance that produced the decision. |
| `cardRef` | string | `cogUrn` of the model card record that documents this model. |

The `model.cardRef` MUST resolve to a record describing the model (training data, evaluation, intended use). The decision record cites the model card by reference; it does not embed the model card.

### 4.4 The `policyRef` block

The `policyRef` field is an object with the following sub-fields:

| Sub-field | Type | Semantics |
|-----------|------|-----------|
| `registry` | string | URI of the registry that serves the cited policy record. |
| `cogUrn` | string | `cogUrn` of the policy record being cited. |
| `version` | string | Semver of the policy version in force at decision time. |
| `clause` | string | OPTIONAL. Fragment identifier of the specific clause within the policy. |

A `policyRef` resolves against the policy record as it stood at the decision's `issued` timestamp. Consumers performing time-pinned resolution use the registry's `asOf` query semantics to retrieve the version that was current at that moment, not whichever version is current today. The policy record's schema is specified by the **MX Policy Records note**.

### 4.5 The `humanInLoop` block

The `humanInLoop` field is an object with the following sub-fields:

| Sub-field | Type | Semantics |
|-----------|------|-----------|
| `required` | boolean | Whether the operator's policy required human review for this decision. |
| `fired` | boolean | Whether human review actually took place. |
| `reviewerRef` | string | OPTIONAL. Opaque reference to the reviewer (an internal identifier, not a name). |

When `required` is `true` and `fired` is `false`, the record is honestly signalling that policy-mandated review did not occur. This is a record of fact, not a defence; consumers reasoning about the record draw their own conclusions about whether the policy was followed.

### 4.6 Human-readable description

A decision record MUST include a human-readable description, in whatever way the carrier supports. In Markdown carriers, this is the body of the cog below the frontmatter. In JSON, this is a top-level `description` field. In HTML, this is the visible page content.

The description is part of the canonicalised payload. Where a trust layer attests the record per the **MX Attestation Records and Verification note**, the description is included in the signed bytes.

The description makes the record reviewable by humans — including the subject of the decision, where law requires that — without parsing the structured metadata.

### 4.7 Illustrative expression

The same record in the Markdown carrier:

```yaml
---
title: "Decision: claim-2026-05-15-184729"
description: "Routine insurance claim routed to standard review queue."
author: did:web:example-insurance.com
created: 2026-05-15T10:32:17Z
modified: 2026-05-15T10:32:17Z

type: decision
mx:
  schemaVersion: 1.0
  cogUrn: cog:web:example-insurance.com:01JC8X7K2N4P5Q6R7S8T9V0W1Y
  decisionId: claim-2026-05-15-184729
  operator: did:web:example-insurance.com
  issued: 2026-05-15T10:32:17Z
  policyRef:
    registry: https://registry.example
    cogUrn: cog:web:tg.community:eu-ai-act-art-12
    version: 1.0.0
    clause: para-1
  model:
    id: example-insurance/triage-classifier
    version: 2.3.1
    cardRef: cog:web:example-insurance.com:models-triage-v2-card
  inputHash: sha256:8f3a2b1c
  inputClass: insurance-claim-routine
  outputSummary: Routed to standard review queue
  humanInLoop:
    required: false
    fired: false
  sequence: 184729
---

This decision routed a routine insurance claim to the standard review queue based on the triage classifier's confidence score (above 0.85). No human review was required under the operator's policy for this input class.
```

The same record expressed as JSON carries the same field set flat (without the `mx:` envelope and without the Markdown body); the schema is identical, only the envelope differs.

---

## 5. Relationship to attestation

A decision record carries no signature. Where an operator chooses to attest the record cryptographically, the attestation is a separate cog produced by a trust layer and conforming to the **MX Attestation Records and Verification note**. The attestation references the decision record by `cogUrn` and content digest.

This separation matters: a decision record can be unattested, attested by one registry, or attested by several independent registries, without any change to the record's schema or bytes. Trust mechanisms evolve in the attestation layer; the decision record stays stable.

A decision record that has been superseded (a corrected record replacing an earlier one) is recorded via the supersession mechanism described in the **MX Cogs note**. The superseded record is not deleted; both remain queryable. Consumers reasoning about historical state resolve to either the original or the superseding version per the registry's `asOf` semantics.

---

## 6. Completeness

A single decision record speaks only for itself. Whether all decisions an operator made over a period are present in the registry is a separate question that no individual record can answer.

The `sequence` field supports completeness reasoning: operators assigning a monotonically increasing counter per `(model, inputClass)` enable consumers to detect missing records by inspecting for gaps. A registry serves the records; gap-detection happens at the consumer side.

Completeness reasoning is informative, not normative — the absence of a sequence number is not itself a conformance failure for an individual record. Operators committing to completeness signalling SHOULD declare `sequence`; consumers SHOULD respect operators who do.

Independent corroboration of a decision (a subject acknowledging that a decision was made about them, an auditor sampling against ground truth) is published as separate Verifiable Credentials per the [W3C VC Data Model](https://www.w3.org/TR/vc-data-model/), each referencing the decision record by `cogUrn`. This note does not specify the corroboration mechanism; companion future work will.

---

## 7. Why a separate record class

A decision record is structurally distinct from a content record (a document, a page, an asset). The fields a decision record carries are not optional decoration on a content record; they are the substance of what makes the record a faithful description of a decision.

Three properties motivate the separation:

- **Time-series shape.** Decision records are produced in high volume, time-ordered, by automated systems. Content records are produced in low volume by human or machine authors. The two classes have different operational characteristics that registries handle differently (batched ingest, sequence-based completeness reasoning, time-pinned retrieval).
- **Policy citation discipline.** A decision record's defining property is that it cites the policy it was made under. Content records have no equivalent obligation. Conflating the two would erode the discipline that makes decision records auditable.
- **Privacy posture.** A decision record carries `inputHash` rather than the input itself, by design. Content records typically carry their content. The schemas diverge on what is in the record.

Separating decision records into their own `contentType` keeps each class coherent and avoids leaking decision-specific obligations onto content records that have no use for them.

---

## 8. Implementation guidance (informative)

This section is informative; it is not a normative part of the standard.

### 8.1 Producing decision records at high volume

Operators producing thousands of decisions per hour SHOULD batch the records for submission to a registry rather than submitting each one individually. The batching mechanism is specified by the **MX Attestation Records and Verification note**; a decision record is unchanged by being part of a batch.

### 8.2 Storage at the operator

The raw input that produced a decision stays with the operator. The `inputHash` field is the only thing about the input that reaches the registry. On later demand, an operator can produce the input and demonstrate the hash matches; the registry never holds the input.

### 8.3 Selective disclosure

Where a regulator's question is "how many decisions did this operator make in this category with this output distribution", the operator can publish a signed aggregate statement (a Verifiable Credential) that commits to the underlying decisions without disclosing them. The regulator verifies the credential using standard VC libraries.

### 8.4 Verification

A consumer fetches a decision record, computes its canonical bytes, and resolves the cited `policyRef` against the registry's `asOf` semantics. If the policy version in force at the decision's `issued` timestamp does not match the `policyRef.version`, the record has cited a policy version that was not in force; that is a discrepancy the consumer surfaces.

---

## 9. Security and privacy considerations

- The `outputSummary` and the human-readable description MAY contain personal data describing the subject of the decision. Operators are responsible for data minimisation per [GDPR Article 5(1)(c)](https://gdpr-info.eu/art-5-gdpr/) and equivalent provisions in other jurisdictions. A registry serving the record does not redact or filter content; the record is published as the operator submitted it.
- The `inputHash` commits the input cryptographically without disclosing it. An operator who later produces the input and demonstrates the hash matches has shown the record was not retrospectively edited to fit a different input. The hash itself reveals nothing about the input's contents.
- The `humanInLoop.reviewerRef` field is opaque by intent. A reviewer name in this field would create a personal-data disclosure with no audit benefit; an opaque reference (a UUID or an internal employee identifier with no external mapping) supports traceability without disclosure.
- Decision records are not authenticated by their own schema. Authentication lives in the attestation layer per the **MX Attestation Records and Verification note**. A consumer who needs to verify provenance of a decision record fetches the wrapping attestation, not the record alone.
- Sequence numbers leak operator throughput. An operator who values throughput privacy SHOULD batch its sequence increments at a coarser granularity, or omit `sequence` and accept the reduced completeness-detection capability that follows.

---

## 10. IANA considerations

This note proposes no new IANA registrations.

---

## 11. References

### 11.1 Normative

- [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) — key words for use in RFCs to indicate requirement levels.
- [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) — date and time on the Internet, timestamp format.
- [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234) — US Secure Hash Algorithms (including SHA-256).
- [W3C DID Core 1.0](https://www.w3.org/TR/did-core/) — identifier format for `operator`.
- **MX Cogs note** — universal cog fields (`cogUrn`, `schemaVersion`, `partOf`, supersession).
- **MX Policy Records note** — schema of the record cited by `policyRef`.
- **MX Attestation Records and Verification note** — schema of the trust-layer wrapper.
- **MX Field Definition Pattern note** — structural template for field definitions.

### 11.2 Informative

- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) — used for subject corroboration and selective-disclosure aggregates.
- [GDPR Article 5(1)(c)](https://gdpr-info.eu/art-5-gdpr/) — data minimisation principle.
- [ULID specification](https://github.com/ulid/spec) — recommended form for the local-id portion of `decisionId`.

---

## 12. Acknowledgements

This note draws on the documentation-evidence framing that emerged from internal review of AI governance regimes by Tom Cranstoun and Scott McGregor at Digital Domain Technologies Ltd, and on community feedback at The Gathering's technical sessions.

---

## MX Policy Records note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-policy-records.md
**File:** `draft-policy-records.md`

# MX Policy Records note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 17 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies the **policy record** — a cog that publishes a regulatory code, code of practice, or governance policy in a form that other records can cite by reference. A policy record carries a stable identifier, semver versioning, jurisdictional scope, an effective-from date, and addressable clauses; consumers reasoning about whether a decision followed the policy in force at a given moment resolve the citation deterministically.

Decision records cite policy records by `policyRef` (per the **MX Decision Records note**); the same citation discipline applies to any other record class that asserts a policy was followed (compliance claims, audit reports, attestation extensions). Policies that are *not* published as policy records resolve to moving targets: the regulator's PDF is replaced silently, the clause is renumbered, and the citation chain breaks under audit. Publishing the policy as a record fixes that.

The note is carrier-neutral: a regulator's HTML publication with JSON-LD structured data is a valid policy record; so is a Markdown file with YAML frontmatter; so is a JSON document. The Markdown carrier wraps every field below `mx:` per the **MX Cogs note**; other carriers express the same fields without that envelope.

---

## 2. Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) when, and only when, they appear in all capitals.

Field definitions in this note conform to the **MX Field Definition Pattern note** (the primary note of the draft set). That pattern governs the structural template for every field; this note adopts the pattern's authoring rules and does not restate them.

### 2.1 Conformance levels

A publisher or consumer claiming conformance to this note SHALL satisfy:

- **Level 1 (record format)** — Produced policy records carry the §4.2 required fields, well-formed; absent fields are not silently defaulted. Field names follow `camelCase`. The `clauses` array enumerates every addressable fragment.
- **Level 2 (versioning discipline)** — Level 1 plus: `policyVersion` follows semver; `effectiveFrom` is RFC 3339; supersession of an earlier version uses the `supersedes` mechanism rather than in-place edit.
- **Level 3 (addressable clauses)** — Level 2 plus: every clause carries a stable fragment identifier the body anchor matches, so consumers citing a clause by `policyRef.clause` resolve to the same text the publisher intended.

A claim of conformance SHALL state the level reached.

### 2.2 Draft status

This is a draft note. Conformance levels and field semantics MAY change in response to community review. Implementations SHOULD note the draft version they implemented against.

---

## 3. Scope

### 3.1 In scope

- The fields of a policy record (§4.2).
- The relationship between `cogUrn` (universal identifier) and `policyId` (publisher-internal short reference) (§4.3).
- Clause addressability (§4.4): how a decision record's `policyRef.clause` resolves to a specific fragment.
- Versioning and supersession (§5).
- Third-party publication by The Gathering or other intermediaries when the issuing body has not yet published its own (§6).

### 3.2 Out of scope

- The cryptographic apparatus over the record — signatures, witnesses, batched proofs — defer to the **MX Attestation Records and Verification note**.
- The schema of records that cite a policy — defers to the **MX Decision Records note** and to future companion notes for compliance claims and audit reports.
- Editorial interpretation of any specific regulatory code; this note specifies the record format, not what any policy says.
- Translation handling. A policy record published in one language and translated into another is a separate record citing the original via `derivedFrom`; the translation mechanism is out of scope for this note.

### 3.3 Relationship to existing standards

| Standard | Relationship |
|----------|--------------|
| **MX Cogs note** | Policy records are cogs. The universal cog fields (`cogUrn`, `schemaVersion`, `partOf`, supersession) apply per the MX Cogs note. |
| **MX Core Metadata note** | Doc-identity fields (`title`, `description`, `author`, `created`, `modified`) apply per the MX Core Metadata note. |
| **MX Decision Records note** | Decision records cite policy records via `policyRef`. |
| **MX Attestation Records and Verification note** | A trust-layer attestation MAY wrap a policy record by reference. |
| [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) | Date and time format used by `effectiveFrom`. |
| [W3C DID Core](https://www.w3.org/TR/did-core/) | Identifier format used by `issuingBody`. |
| [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) | Country code format used by `jurisdiction`. |

---

## 4. Policy records

### 4.1 Position

A policy record is the durable referent that every citing record's `policyRef` resolves against. The record fixes three things that an HTML publication or a PDF on a regulator's website does not fix: a stable identifier that survives URL changes, a versioning model that lets consumers reason about which clause text was in force at a given moment, and addressable fragments so a citation like "clause 3.2" resolves deterministically.

A policy record records the **text** and **structure** of a policy. It does not assert that the policy is sound, that the policy is currently in force in any jurisdiction, or that any particular decision did or did not follow it. Those assertions, where needed, live in citing records (decision records, compliance claims, audit reports) and in their attestation wrappers.

### 4.2 Required fields

A policy record declares `type: policy` at the top level (Zone 1b). The following fields are REQUIRED for a valid policy record regardless of carrier. Field names follow `camelCase`.

| Field | Type | Semantics |
|-------|------|-----------|
| `type` | string | Fixed value: `policy`. Top-level (Zone 1b). |
| `schemaVersion` | string | Semver of the policy-record schema this record conforms to (per **MX Cogs note** §6.5.4). |
| `cogUrn` | string | Universal identifier in the form `cog:<publisher-namespace>:<local-id>` (per **MX Cogs note** §6.5.3). For third-party renderings by The Gathering, the publisher namespace is typically `web:tg.community`. |
| `policyId` | string | Publisher's internal reference to the policy; typically the `<local-id>` portion of `cogUrn`. Provides a short stable handle for human reference. |
| `policyVersion` | string | Semver of this policy version. Distinct from `schemaVersion` (which versions the record schema) and from `version` (which versions the document file). |
| `issuingBody` | string | DID or resolvable identifier of the body that issued the policy (the regulator, the standards body, the operator publishing an internal policy). |
| `jurisdiction` | string | [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code; or `EU`; or `international` for policies with no single-jurisdiction scope. |
| `effectiveFrom` | string | [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date the policy version takes effect. |
| `clauses` | array | Addressable fragments. Each entry is an object with `id`, `title`, and `bodyAnchor`. See §4.4. |

The following field is OPTIONAL but RECOMMENDED when applicable:

| Field | Type | Semantics |
|-------|------|-----------|
| `supersedes` | object | Reference to a previous policy version this one replaces. Carries `cogUrn` and `version` of the superseded record. See §5. |

A policy record MUST NOT carry cryptographic apparatus inline. Attestation of a policy record — typically by the issuing body or by The Gathering acting as third-party publisher per §6 — lives in a separate attestation record per the **MX Attestation Records and Verification note**.

### 4.3 `cogUrn` and `policyId`

A policy record carries both a `cogUrn` (the universal identifier per **MX Cogs note** §6.5.3) and a `policyId` (the publisher's short stable handle). They serve different purposes:

- `cogUrn` is the universal long-form identifier used by registries, clients, verifiers, and anything outside the publisher's own systems. It is namespace-qualified and globally unique.
- `policyId` is the publisher's local handle, typically equal to the `<local-id>` portion of `cogUrn`. It exists for human reference and for compactness in citation-heavy prose where the full `cogUrn` would clutter.

In most implementations the `<local-id>` portion of `cogUrn` and `policyId` SHOULD be equal; publishers who want a separation (because their internal IDs leak information they prefer to keep internal) MAY choose distinct values.

### 4.4 The `clauses` array

The `clauses` array makes individual policy fragments addressable. Each entry is an object with the following sub-fields:

| Sub-field | Type | Semantics |
|-----------|------|-----------|
| `id` | string | Fragment identifier. Stable across versions: where a clause is preserved verbatim across a policyVersion bump, its `id` MUST NOT change. |
| `title` | string | Human-readable title of the clause. |
| `bodyAnchor` | string | Anchor name within the record's body that points at the clause text. In a Markdown carrier this is typically a heading slug; in an HTML carrier it is an element `id`. |

A citing record references a specific clause by setting `policyRef.clause` to the clause's `id`. Consumers MUST resolve `policyRef.clause` to the corresponding `clauses[i].bodyAnchor` and retrieve the clause text from the body of the policy record. A `clauses` entry whose `bodyAnchor` does not match a real anchor in the body is a conformance failure.

Where a clause is amended within a major policy version (without renumbering), the publisher SHOULD bump `policyVersion` (minor or patch as appropriate) and preserve the clause `id` so existing citations continue to resolve. Where a clause is removed or renumbered, the publisher MUST bump the major component of `policyVersion`; the previous version remains queryable via supersession (§5) so historical citations still resolve.

### 4.5 Illustrative expression

```yaml
---
title: "EU AI Act, Article 12: event recording"
description: "Policy record rendering of EU AI Act Article 12 on automatic event recording."
author: did:web:digital-strategy.ec.europa.eu
created: 2026-08-02
modified: 2026-08-02

type: policy
mx:
  schemaVersion: 1.0
  cogUrn: cog:web:tg.community:eu-ai-act-art-12
  policyId: eu-ai-act-art-12
  policyVersion: 1.0.0
  issuingBody: did:web:digital-strategy.ec.europa.eu
  jurisdiction: EU
  effectiveFrom: 2026-08-02T00:00:00Z
  clauses:
    - id: para-1
      title: Record-keeping requirement
      bodyAnchor: record-keeping-requirement
    - id: para-2
      title: Automatic event recording
      bodyAnchor: automatic-event-recording
---

## Record-keeping requirement {#record-keeping-requirement}

(Body text for paragraph 1 goes here.)

## Automatic event recording {#automatic-event-recording}

(Body text for paragraph 2 goes here.)
```

The same record expressed as JSON carries the same field set flat; the schema is identical, only the envelope differs.

---

## 5. Versioning and supersession

A policy record is amended through the supersession mechanism described in the **MX Cogs note**. A new policy record carrying `supersedes: { cogUrn: <previous cogUrn>, version: <previous policyVersion> }` replaces the earlier version; both remain queryable, and consumers reasoning about historical state retrieve whichever version was in force at the moment they care about.

The interaction between `policyVersion` and supersession:

- **Patch and minor** versions remain inside the same logical record (`cogUrn` unchanged; new `policyVersion`; `supersedes` references the previous `policyVersion` of the same `cogUrn`). The new version inherits clause ids from the previous version.
- **Major** versions MAY also remain inside the same logical record, but publishers MAY choose to mint a new `cogUrn` when the policy changes scope significantly (e.g. one regulation splitting into two). When a new `cogUrn` is minted, `supersedes` references the predecessor's `cogUrn` and version explicitly.

A consumer performing time-pinned resolution (asking "what was the policy in force on date X") retrieves whichever version's `effectiveFrom` is the latest non-future date relative to X. The registry serves; consumers reason.

A withdrawn policy (a record formally retracted by the issuing body) is recorded by a superseding record carrying `withdrawn: true`. The original is not deleted; consumers reasoning about decisions made before the withdrawal still resolve to the original text.

---

## 6. Third-party publication

Many regulators do not currently publish their codes as policy records. Until they do, an intermediary (The Gathering, a sector body, an academic institution) MAY publish a **third-party rendering** of a policy as a policy record, signed by the intermediary rather than by the issuing body.

A third-party rendering MUST:

- Declare the original issuing body in `issuingBody` (the regulator's DID, not the renderer's).
- Be clearly labelled in its `description` field as a third-party rendering, not source-of-truth.
- Cite the source publication (a URL, a regulatory document number, or both) in the body text.
- Be signed by the rendering intermediary's key per the **MX Attestation Records and Verification note**; the attestation's `issuedBy` is the renderer, not the issuing body.

When the issuing body eventually publishes its own signed version, the third-party rendering is superseded via §5. The new record carries the issuing body's signature; the third-party record remains queryable for historical citation but is no longer the recommended target for new citations.

This is the same pattern Certificate Transparency used: independent monitors started logging first, authorities later participated.

---

## 7. Implementation guidance (informative)

This section is informative; it is not a normative part of the standard.

### 7.1 Choosing `policyId` and `cogUrn`

For a regulatory code, a reasonable convention is `policyId` = the regulator's short reference for the code (e.g. `eu-ai-act-art-12`, `iso-27001`, `nist-800-53-rev5-ac-3`), and `cogUrn` = `cog:<renderer-namespace>:<policyId>`. This keeps citations human-readable while preserving universal uniqueness.

### 7.2 Stable clause ids

A publisher anticipating that consumers will cite specific clauses SHOULD adopt clause ids that match the policy's own internal numbering (e.g. `para-1`, `sub-clause-3-2-a`, `annex-iii-point-5`). Inventing renderer-specific clause ids that diverge from the policy's own numbering creates a translation burden every citing record must handle.

### 7.3 Effective-from versus enacted-on

`effectiveFrom` is when the policy version becomes binding on regulated entities, not when the legal instrument was passed. A policy enacted on date X with a one-year transition period has `effectiveFrom: X + 1 year`. Consumers reasoning about whether a decision followed the policy in force at decision time MUST use `effectiveFrom`, not the enactment date.

### 7.4 Verification

A consumer fetches a policy record and checks: that `clauses[].bodyAnchor` resolves to a real anchor in the body for every clause; that `effectiveFrom` is RFC 3339; that `policyVersion` is semver; and (where the record carries an attestation) that the attestation's signature verifies against the renderer's published key.

---

## 8. Security and privacy considerations

- A third-party rendering signed by an intermediary attests provenance and integrity of the rendering, not the legal correctness of the policy text. Even when the attestation verifies cleanly, downstream consumers MUST NOT treat the text as legally authoritative — it is the renderer's faithful copy, not the issuing body's instrument. User-facing language SHOULD say *attested rendering*, not *official policy*.
- A policy record carrying clause text in its body is plain content with no privacy obligations; policy text is typically public. However, where a policy record is published with internal-policy scope (an operator's own decision-making rules, not a regulator's code), the body content MAY be sensitive. Internal-policy records SHOULD declare `confidential: true` per the **MX Core Metadata note** and be served from access-controlled endpoints.
- The `issuingBody` field is operator-attested, not authority-verified. A record claiming `issuingBody: did:web:fictitious-regulator.example` is conformant by this note's rules even if no such regulator exists. Consumers reasoning about regulatory weight MUST verify the `issuingBody` DID resolves to the genuine regulator through external means (the regulator's known web property, an authoritative directory of regulatory bodies, or a trusted intermediary's vouching).
- Withdrawal of a policy via `withdrawn: true` is published by the same publisher that published the original. A publisher who has lost the operational capability to publish (organisation dissolved, signing key compromised beyond recovery) cannot withdraw their own policies; consumers reasoning about long-superseded policies MAY find them still present in the registry but should treat them as historical, not current.

---

## 9. IANA considerations

This note proposes no new IANA registrations.

---

## 10. References

### 10.1 Normative

- [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)) — key words for use in RFCs to indicate requirement levels.
- [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) — date and time on the Internet, timestamp format.
- [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) — country codes for the `jurisdiction` field.
- [W3C DID Core 1.0](https://www.w3.org/TR/did-core/) — identifier format for `issuingBody`.
- **MX Cogs note** — universal cog fields (`cogUrn`, `schemaVersion`, `partOf`, supersession).
- **MX Decision Records note** — record class that cites policy records via `policyRef`.
- **MX Attestation Records and Verification note** — schema of the trust-layer wrapper.
- **MX Field Definition Pattern note** — structural template for field definitions.

### 10.2 Informative

- [Semantic Versioning 2.0.0](https://semver.org/) — version-number format used by `policyVersion` and `schemaVersion`.
- [Certificate Transparency (RFC 6962)](https://datatracker.ietf.org/doc/html/rfc6962) — analogue for the third-party-publication pattern in §6.

---

## 11. Acknowledgements

This note draws on the documentation-evidence framing that emerged from internal review of AI governance regimes by Tom Cranstoun and Scott McGregor at Digital Domain Technologies Ltd, and on community feedback at The Gathering's technical sessions.

---

## MX AI Usage Declaration note

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-ai-usage-declaration.md
**File:** `draft-ai-usage-declaration.md`

# MX AI Usage Declaration note

**Version:** 1.0
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 17 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note specifies how a publisher declares the role AI played in producing a body of work. The declaration is a signed, scope-bounded, machine-readable statement carrying four facts: what the work is, who is responsible for it, what machines did during its production, and what machines did not do. It is published at a discoverable location on the publisher's host, available in both human-readable and machine-readable carriers, and may be self-attested or third-party-attested.

The note is motivated by a gap in the existing AI-adjacent web conventions. The Spawning Labs `ai.txt` and `robots.txt` carry publisher consent for *training* use of content. The `llms.txt` convention carries navigation aids for *inference-time* agents reading a site. C2PA manifests carry asset-level provenance for individual files. None of these answer the question a regulator, auditor, or attentive reader actually puts to a publisher: how, and to what extent, did AI participate in producing the content you are publishing? An AI Usage Declaration answers that question in a single document, in a form a person can read and a machine can verify.

The note is deliberately framework-agnostic about whether AI involvement is positive, negative, or neutral. It specifies disclosure, not judgement. It does not grant compliance with any AI-governance regime; it provides the kind of structured, machine-readable, tamper-evident record those regimes increasingly expect organisations to produce.

---

## 2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) and [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here.

### 2.1 Conformance levels

A declaration claiming conformance to this note SHALL satisfy:

- **Level 1 (Declared):** the declaration is published at a discoverable location (§5), carries every required field defined in §4, names the work it scopes, and names a responsible author. Self-attestation is the default authority.
- **Level 2 (Signed):** Level 1 plus a cryptographic signature over a canonical serialisation of the declaration payload, using the signature mechanism in §6.
- **Level 3 (Attested):** Level 2 plus a third-party attestation binding the declaration to a verified publisher identity, expressed as a compliance claim per the MX Compliance Claims note's third-party authority pattern.

A claim of conformance SHALL state the level reached.

### 2.2 Draft status

This is a draft note. Conformance levels and field semantics MAY change in response to community review. Implementations of this draft SHOULD note the draft version number they implemented against.

---

## 3. Scope

### 3.1 In scope

- A machine-readable schema for a publisher AI Usage Declaration record.
- A discovery convention by which agents and humans locate the declaration for a given host or work.
- A signature mechanism that lets a verifier confirm the declaration has not been altered since signing.
- The relationship between this declaration and the existing AI-adjacent web conventions covering training opt-out, navigation aid, and asset-level provenance.

### 3.2 Out of scope

- Whether AI involvement in a given work is desirable, acceptable, or otherwise. The note specifies disclosure, not editorial judgement.
- Training data opt-out signalling, which is the territory of `ai.txt` proposals and `robots.txt` directives.
- Inference-time navigation aids for LLM agents reading a site, which is the territory of `llms.txt`.
- Asset-level provenance manifests for individual binary files (images, audio, video), which are the territory of C2PA.
- Model cards and other model-provider disclosures about the AI systems themselves, which are the territory of model documentation standards.
- Legal compliance with any specific AI-governance regime. A declaration is evidence; compliance is a legal duty of the organisation.

### 3.3 Relationship to existing standards

This note relies on:

- **[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119)** and **[RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)** for normative key word interpretation.
- **[RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615)** for the well-known URI mechanism.
- **[RFC 7515 JSON Web Signature](https://datatracker.ietf.org/doc/html/rfc7515)** for the baseline signature serialisation when a declaration is signed.
- **[RFC 8032 EdDSA](https://datatracker.ietf.org/doc/html/rfc8032)** as the RECOMMENDED signature algorithm.
- **[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)** for date and timestamp values.
- **[HTML Living Standard](https://html.spec.whatwg.org/)** for the `<link rel>` discovery mechanism.
- **[Schema.org](https://schema.org/)** for the publisher and author entity vocabulary referenced in §4, and for the `digitalSourceType` property used in the page-level interoperability mapping in §5.6.
- **[WICG AI Content Disclosure proposal](https://github.com/WICG/proposals/issues/261)** for the page-level `<meta name="ai-disclosure">` and element-level `ai-disclosure` attribute that a declaration's `aiUsage` array reduces to. The MX declaration is the publisher-level superset that produces the page-level value (§4.7).
- **[IPTC Digital Source Type vocabulary](https://cv.iptc.org/newscodes/digitalsourcetype/)** for the controlled-vocabulary terms referenced in the same mapping (`digitalCapture`, `compositeWithTrainedAlgorithmicMedia`, `trainedAlgorithmicMedia`).

This note adds nothing to those standards; it specifies how they combine for the publisher AI-usage disclosure case.

---

## 4. The declaration record

A declaration is authored as a markdown file with structured YAML frontmatter, following the long-established convention of YAML as the metadata block and CommonMark as the human-readable body. The markdown source is the source of truth at every conformance level; it is the artefact the author edits and the artefact a publisher commits to version control.

From this source file, three deterministic serialisations are derived:

- A canonical JSON form for machine transmission, interop, and signing (§6). The JSON is the artefact that gets signed at Level 2 because RFC 8785 JCS gives a deterministic canonical byte sequence over JSON, which YAML alone does not.
- A rendered HTML form for in-browser reading by humans.
- A tagged PDF form for accessible archival (optional but RECOMMENDED).

Each derived form MUST reflect the same fields as the source markdown; no field present in a serialisation MAY be absent from, or contradict, the source. A publisher MAY publish the source markdown itself at `/AI-USAGE.md` (§5.1) so any reader can fetch the editable form. The JSON, HTML, and PDF serialisations are siblings derived from the same source, not parallel artefacts edited in parallel.

The fields below are the ones the source markdown's YAML frontmatter MUST carry. They appear verbatim in the derived JSON (with the prose narrative from the markdown body summarised into the `aiBoundary` array). A conformant declaration MUST declare:

| Field | Cardinality | Type | Description |
| --- | --- | --- | --- |
| `id` | required | string (URI) | A stable URI that identifies this declaration. The URI SHOULD be the canonical URL at which the declaration is served. |
| `subject` | required | object | The work the declaration scopes. See §4.1. |
| `publisher` | required | object | The organisation or individual responsible for the work. See §4.2. |
| `author` | required | object | The person signing the declaration. May equal `publisher` when the publisher is an individual. See §4.3. |
| `created` | required | string (ISO 8601) | The date the declaration was first issued. |
| `modified` | RECOMMENDED | string (ISO 8601) | The date the declaration was last materially changed. Omit when equal to `created`. |
| `reviewSchedule` | OPTIONAL | string (ISO 8601 duration) | The interval at which the publisher commits to reviewing and re-confirming or updating the declaration. Example: `P1Y` for annual review. See §9.2. |
| `aiUsage` | required | array of objects | Enumerated tasks AI performed during production. See §4.4. |
| `aiBoundary` | required | array of strings | Tasks AI did not perform, stated as boundary claims. See §4.5. |
| `narrativeUri` | RECOMMENDED | string (URI) | Pointer to the human-readable rendering of the declaration, served on the same host. |
| `authority` | required at Level 2+ | object | Authority type and identity. See §4.6. |
| `signature` | required at Level 2+ | object | Cryptographic signature over the canonical payload. See §6. |

### 4.1 Subject object

The work the declaration scopes. A declaration MAY scope a single work (a book, a paper, a podcast episode, a film, a software release), a serial collection (a book series, a podcast feed, a periodical), or the entire output of a host. The `subject` object carries:

- `type`: one of `work`, `collection`, `host`. Required.
- `name`: human-readable name of the work, collection, or host. Required.
- `identifier`: a stable URI or ISBN, DOI, ISSN, or similar canonical identifier where one exists. RECOMMENDED.

A declaration that scopes a host (`type: host`) covers every publication on that host until superseded by a more specific declaration whose `subject` names a particular work or collection. Specific declarations override host-level declarations for the works they name.

### 4.2 Publisher object

The organisation or individual responsible for the work. The object SHOULD align with the Schema.org `Organization` or `Person` vocabulary, carrying at minimum:

- `type`: `Organization` or `Person`. Required.
- `name`: the publisher's name as it appears on the work. Required.
- `identity`: a URI (web page, DID, or other dereferenceable identifier). RECOMMENDED.

### 4.3 Author object

The person signing the declaration. The same shape as `publisher` but constrained to `Person`. The author signs in a personal capacity; the publisher accepts the signing person's authority to bind the publisher to the declaration.

### 4.4 AI-usage entries

An array of zero or more objects, each describing a category of AI involvement during production. Each object carries:

- `task`: a short noun phrase naming the task. Required. Values are open-ended in this version of the note. Implementations SHOULD use lowercase hyphen-separated phrases (e.g. `spelling-and-grammar`, `code-generation`). The common values listed below are the seed vocabulary; a community registry of task names is expected to emerge from implementation experience. Seed values: `research`, `spelling-and-grammar`, `consistency-checking`, `drafting`, `translation`, `summarisation`, `image-generation`, `code-generation`, `transcription`. Implementations that coin a novel value SHOULD document it in the declaration's `scope` field so that downstream readers can map it back to the closest seed term.
- `scope`: a one-sentence narrative description of how the AI was used for this task in this work. Required.
- `extent`: one of `assisted`, `substantial`, `primary`. Required. `assisted` means the AI's output was treated as a suggestion and reworked by a person; `substantial` means the AI produced a draft a person then directed and edited; `primary` means the AI produced the content with light human direction.

An empty `aiUsage` array is a valid declaration. It states that no AI was used in producing the work.

### 4.5 AI-boundary statements

An array of strings, each stating a boundary the publisher commits to: a task AI did not perform. Each string is a complete sentence in the publisher's voice. Common patterns include:

- "No machine decided what this work is about."
- "No machine wrote the text that carries the ideas."
- "No machine signed off on the published version."

The boundary array is normative for the publisher: a publisher that later relaxes a stated boundary MUST issue a new declaration with a later `modified` date and an updated boundary array.

### 4.6 Authority object

Authority type and identity. The object SHARES vocabulary with the MX Compliance Claims note for interoperability:

- `type`: `self` or `third-party`. Required.
- `identity`: URI or DID that names the signing party. Required.
- `accreditation`: present only when `type` is `third-party`. Object naming the accreditation body, validity dates, and a lookup URI for verification status.

Self-attested declarations carry the assurance level of the publisher's identity. They are appropriate for first-person disclosure by the work's author. They are not appropriate for evidence-trail use cases where the consumer's interest is in independent confirmation of the publisher's claim.

### 4.7 Mapping to WICG and IPTC vocabularies

Page-level and asset-level disclosure standards use finite enumerations. The MX declaration carries a richer per-task record. An MX-conformant implementation MUST derive the single-value WICG `ai-disclosure` and IPTC `digitalSourceType` for the declaration's `subject` from its `aiUsage` and `aiBoundary` by the following rules. The derivation is a function of the declaration record; it adds no new normative content.

A derived `disclosure` object on the declaration record MAY carry:

- `wicg`: one of `none`, `ai-assisted`, `ai-generated`, `autonomous`.
- `iptc`: one of `digitalCapture`, `compositeWithTrainedAlgorithmicMedia`, `trainedAlgorithmicMedia`.
- `derivedFrom`: the literal string `aiUsage+aiBoundary` to mark the value as computed rather than independently asserted.

The derivation rules:

| Condition | wicg | iptc |
| --- | --- | --- |
| `aiUsage` is empty (no AI involvement asserted) | `none` | `digitalCapture` |
| Every `aiUsage` entry has `extent: assisted` | `ai-assisted` | `compositeWithTrainedAlgorithmicMedia` |
| At least one `aiUsage` entry has `extent: substantial`, OR `extent: primary` with `aiBoundary` asserting human decision authority over the published version | `ai-generated` | `trainedAlgorithmicMedia` |
| Every `aiUsage` entry has `extent: primary` AND `aiBoundary` does not assert human decision authority over the published version | `autonomous` | `trainedAlgorithmicMedia` |

A declaration MAY publish the derived `disclosure` object alongside the underlying record. Consumers that only understand the WICG or IPTC vocabularies MAY rely on the derived values. Consumers that understand the MX schema SHOULD prefer the underlying `aiUsage` and `aiBoundary` for any reasoning that requires per-task granularity.

A publisher MUST NOT publish a derived `disclosure` value that contradicts the rules above. Manually overriding the derivation defeats the interoperability the mapping exists to provide.

The WICG value `mixed` is a page-level signal indicating that different elements on the same page carry different `ai-disclosure` attribute values. It does not arise from the publisher-level derivation in this section. A publisher that serves pages with the element-level WICG `ai-disclosure` attribute on individual elements MAY use `mixed` as the page-level meta value on those pages without this altering the publisher-level MX declaration. The MX `disclosure.wicg` field is restricted to the four values in the derivation table above.

### 4.8 Worked example

```json
{
  "id": "https://mx.allabout.network/AI-USAGE.json",
  "subject": {
    "type": "collection",
    "name": "MX book series",
    "identifier": "https://mx.allabout.network/books/"
  },
  "publisher": {
    "type": "Organization",
    "name": "CogNovaMX",
    "identity": "https://mx.allabout.network/about/about.html#organization"
  },
  "author": {
    "type": "Person",
    "name": "Tom Cranstoun",
    "identity": "https://mx.allabout.network/blog/profiles/about.tom.cranstoun.html#person"
  },
  "created": "2026-05-17",
  "aiUsage": [
    {"task": "research", "scope": "Gathering sources and prior work before forming a view.", "extent": "assisted"},
    {"task": "spelling-and-grammar", "scope": "Mechanical checks across long manuscripts.", "extent": "assisted"},
    {"task": "consistency-checking", "scope": "Term usage and structural coherence across chapters.", "extent": "assisted"}
  ],
  "aiBoundary": [
    "No machine decided what the books are about.",
    "No machine set the argument, chose the angle, or judged whether a passage was sound.",
    "No machine wrote the text that carries the ideas."
  ],
  "narrativeUri": "https://mx.allabout.network/AI-USAGE.html",
  "authority": {
    "type": "self",
    "identity": "https://mx.allabout.network/blog/profiles/about.tom.cranstoun.html#person"
  },
  "disclosure": {
    "wicg": "ai-assisted",
    "iptc": "compositeWithTrainedAlgorithmicMedia",
    "derivedFrom": "aiUsage+aiBoundary"
  }
}
```

This example illustrates the schema. It is not a registered declaration.

---

## 5. Discovery and serving

### 5.1 Canonical locations

A host that publishes an AI Usage Declaration SHOULD serve the derived forms at one of these canonical locations, and MAY also serve the source markdown alongside them:

- **Root-level (recommended):**
  - `/AI-USAGE.md` for the source markdown (OPTIONAL but RECOMMENDED for transparency).
  - `/AI-USAGE.json` for the machine-readable derived record (REQUIRED at Level 1).
  - `/AI-USAGE.html` for the human-readable rendering (REQUIRED at Level 1).
  - `/AI-USAGE.pdf` for the paginated archival form (OPTIONAL).
  - This pattern matches the conventional placement of `/llms.txt`, `/robots.txt`, `/humans.txt`, and `/ai.txt`.
- **Well-known prefix:** `/.well-known/ai-usage` (returning the JSON record) with content negotiation or sibling resources at `/.well-known/ai-usage.md`, `/.well-known/ai-usage.html`, and `/.well-known/ai-usage.pdf`. This pattern follows [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) for hosts that prefer to keep root URIs clear.

A host MUST NOT serve different declarations at the root-level and well-known locations for the same `subject`. If both locations are served, they MUST point to identical declaration records (one MAY 301-redirect to the other). When the source markdown is served alongside its derived forms, the JSON, HTML, and PDF MUST be derivable from it with no contradictions; a derived form that contradicts the source is a conformance failure.

### 5.2 Content types

- The source markdown SHOULD be served with `Content-Type: text/markdown; charset=utf-8` per [RFC 7763](https://datatracker.ietf.org/doc/html/rfc7763).
- The JSON record SHOULD be served with `Content-Type: application/json; charset=utf-8`. The media type `application/ai-usage-declaration+json` is reserved for a future revision once implementation experience justifies registration.
- The human-readable HTML rendering SHOULD be served with `Content-Type: text/html; charset=utf-8`.
- A PDF rendering SHOULD be served with `Content-Type: application/pdf` and SHOULD be tagged per [ISO 14289-1](https://www.iso.org/standard/64599.html) (PDF/UA-1, `pdfuaid:part=1`) for accessibility.

### 5.3 In-page discovery

Every page on a host that publishes an AI Usage Declaration SHOULD carry a `<link>` element in `<head>` that points to the declaration:

```html
<link rel="ai-usage" href="/AI-USAGE.json" type="application/json">
```

The same page MAY carry additional `<link rel="alternate" type="...">` entries pointing to the HTML and PDF renderings. The kebab-case `rel` value `ai-usage` is proposed for a future link-relation registration; until registered, implementations MAY use the extension form `https://mx.allabout.network/ns/ai-usage` as an alternative `rel` value.

### 5.4 Sitemap inclusion

Every canonical location at which the declaration is served SHOULD appear in the host's sitemap. The JSON record and the HTML rendering SHOULD both be listed.

### 5.5 Per-work overrides

When the host-level declaration's `subject` is `host` and a specific work has its own narrower declaration, the work's pages SHOULD carry their own `<link rel="ai-usage">` pointing to the specific declaration. Agents MUST resolve to the more specific declaration when one is named for the work currently being read.

### 5.6 Page-level interoperability with WICG ai-disclosure

A page carrying a `<link rel="ai-usage">` to the publisher's MX declaration SHOULD also carry the page-level WICG `<meta name="ai-disclosure">` value derived from that declaration by the rules in §4.7. A page MAY additionally carry the Schema.org `digitalSourceType` property in its JSON-LD using the IPTC value derived by the same rules.

```html
<!-- discovery for the MX publisher-level declaration -->
<link rel="ai-usage" type="application/json" href="/AI-USAGE.json">
<!-- page-level WICG value derived from the MX declaration -->
<meta name="ai-disclosure" content="ai-assisted">
```

```json
{
  "@context": "https://schema.org",
  "@type": "CreativeWork",
  "digitalSourceType": "https://cv.iptc.org/newscodes/digitalsourcetype/compositeWithTrainedAlgorithmicMedia"
}
```

A page MUST NOT carry a WICG or IPTC value that contradicts the derivation from the publisher's MX declaration. Where the two would disagree, the publisher MUST either correct the MX declaration or correct the page-level value; both MUST NOT be served simultaneously with conflicting content.

A consumer that supports only the WICG meta tag or only the Schema.org property gets a useful page-level signal without having to fetch the MX declaration. A consumer that follows `<link rel="ai-usage">` gets the structured, signable, per-task record the page-level signal summarises.

---

## 6. Signature

### 6.1 Mechanism

A signed declaration (Level 2 or above) MUST carry a cryptographic signature over a canonical serialisation of the declaration payload, computed without the `signature` field present.

- The signature serialisation MUST follow [RFC 7515 JSON Web Signature](https://datatracker.ietf.org/doc/html/rfc7515).
- The signature algorithm SHOULD be Ed25519 ([RFC 8032 EdDSA](https://datatracker.ietf.org/doc/html/rfc8032)). Other algorithms MAY be used where the verifier's policy permits.
- The signature value MUST be base64url-encoded as defined in RFC 7515.
- The canonical form of the declaration payload over which the signature is computed MUST follow [RFC 8785 JSON Canonicalization Scheme](https://datatracker.ietf.org/doc/html/rfc8785). Implementations MAY additionally apply the layered fingerprinting approach described in the MX Contract Fingerprinting and Signing note (a sister draft in the MX family) for cross-cog content fingerprinting; the present note does not normatively depend on that approach.

### 6.2 `signature` object

The `signature` field of a signed declaration carries:

- `algorithm`: the JWS algorithm identifier (e.g. `EdDSA`). Required.
- `value`: the base64url-encoded signature. Required.
- `keyId`: a URI dereferenceable to the public key used to verify the signature. Required.
- `signedAt`: ISO 8601 timestamp the signature was produced. Required.

### 6.3 Re-signing

A signature is bound to a specific canonical serialisation. Any change to the declaration payload that affects the canonical form invalidates the signature. The publisher MUST issue a new signature when re-publishing.

---

## 7. Why a separate note

The publisher's AI-usage disclosure sits in a gap between adjacent standards that almost cover the case but do not.

**Why not WICG ai-content-disclosure alone.** The WICG AI Content Disclosure proposal carries a single page-level or element-level enumeration: `none`, `ai-assisted`, `ai-generated`, or `autonomous`. It is the right surface for a browser, a search engine, or a regulator's compliance check that needs a one-token answer for a single page. It does not carry which tasks AI performed, the human-authorship boundary the publisher commits to, or a signature that lets a verifier confirm the disclosure has not been altered. The MX declaration is the publisher-level superset whose summary reduces to the WICG value (§4.7 carries the mapping). A conformant MX implementation publishes both: the structured record at `/AI-USAGE.json` for verifiers, and the derived `<meta name="ai-disclosure">` on every page for consumers that read only the WICG vocabulary.

**Why not Schema.org `digitalSourceType` alone.** The IPTC Digital Source Type vocabulary, exposed in Schema.org as the `digitalSourceType` property, is a three-state controlled vocabulary for indicating how an asset came to exist. It is search-engine readable today and lives in the same JSON-LD block a page already serves. It addresses a strictly narrower question than this note. The MX declaration produces the IPTC value as a derived field (§4.7) so a publisher does not have to choose between the two.

**Why not C2PA.** The Coalition for Content Provenance and Authenticity specifies asset-level provenance manifests for individual binary files. C2PA answers the question "who made and altered this image, audio, or video, and how?" A book series, a website, a podcast feed, or a research programme has no single asset. A publisher-level disclosure of AI involvement across many works is a different layer of the same problem.

**Why not ai.txt.** The Spawning Labs `ai.txt` proposal carries publisher consent for AI *training* use of content. It is a directive to crawlers and dataset builders. It does not describe how the publisher themselves used AI in producing the content. The two declarations are orthogonal and may both be published by the same host.

**Why not robots.txt.** [RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309) governs robots.txt. Its extension forms for AI-related directives are scoped to crawler permission. They do not carry publisher disclosure.

**Why not llms.txt.** The `llms.txt` convention carries navigation aids for inference-time LLM agents reading a site. It tells the agent where to look. It does not tell the agent how the content it is reading came to exist.

**Why not model cards.** Model documentation describes the AI system. An AI Usage Declaration describes a work produced with the help of one or more such systems. Both can be true at once; neither replaces the other.

**Why not a platform-specific AI-content checkbox.** Self-publishing platforms increasingly require authors to declare AI involvement at upload time. These declarations are not interoperable across platforms, not signed, not discoverable from the published work, and not durable beyond the platform's lifetime. A web-native declaration travels with the work.

**Why not EU AI Act Annex IV documentation alone.** Annex IV documentation is a regulatory record an organisation maintains. It is not a web-discoverable, machine-readable declaration attached to the published work. A jurisdiction-neutral declaration format complements the regulatory record without replacing it.

The combination of these gaps is the reason for a separate note.

---

## 8. Implementation guidance (informative)

This section is informative; it is not a normative part of the standard.

### 8.1 Minimum viable implementation

A publisher beginning from scratch can reach Level 1 conformance in a single afternoon:

1. Write the human-readable narrative declaration. Name the subject, the publisher, the author, what AI did, what AI did not do.
2. Serialise the same facts into the JSON form defined in §4.
3. Compute the derived WICG and IPTC values per §4.7 and embed them in the JSON `disclosure` object.
4. Publish both at `/AI-USAGE.html` and `/AI-USAGE.json` on the publisher's host.
5. Add `<link rel="ai-usage" href="/AI-USAGE.json" type="application/json">` to the site template's `<head>`.
6. Add `<meta name="ai-disclosure" content="<derived-wicg-value>">` to the same template, and the Schema.org `digitalSourceType` property to the page's JSON-LD `CreativeWork` block.
7. Add both URLs to the host's sitemap.

Level 2 adds a signing step using any RFC 7515 JWS library that supports Ed25519. Level 3 requires arrangement with a third-party attestation authority operating under the MX Compliance Claims framework; this is a multi-week process and is not necessary for most publishers.

### 8.2 Worked implementation

An existing Level 1 implementation serves the publisher-level declaration for CogNovaMX (subject: the MX book series) at the following URLs:

- Machine-readable JSON record: <https://mx.allabout.network/AI-USAGE.json>
- Human-readable HTML rendering: <https://mx.allabout.network/AI-USAGE.html>
- Tagged PDF archival form (ISO 14289-1 Level 2): <https://mx.allabout.network/AI-USAGE.pdf>

Discovery is wired across the site: every page under `https://mx.allabout.network/` carries `<link rel="ai-usage" type="application/json" href="/AI-USAGE.json">` in `<head>`, along with the page-level `<meta name="ai-disclosure" content="ai-assisted">` derived per §4.7. The Schema.org `digitalSourceType` IRI `https://cv.iptc.org/newscodes/digitalsourcetype/compositeWithTrainedAlgorithmicMedia` is carried in the `WebPage` JSON-LD block on the declaration page itself. All three URLs appear in the host's sitemap.

The signature workflow (Level 2) is the next implementation step on this host. Reviewers can `curl` the JSON record to verify Level 1 conformance against the rules in §8.3.

### 8.3 Deriving the JSON from the source markdown

The JSON form is produced from the source markdown by a mechanical extraction. The recommended algorithm:

1. Parse the file's YAML frontmatter.
2. Drop document-meta fields not relevant to the declaration (`title`, `description`, `version`, and any document-mechanics fields not enumerated in §4). Keep the fields enumerated in §4.
3. If the frontmatter does not carry an explicit `aiBoundary` array, derive one from the boundary statements in the markdown body. The author SHOULD carry `aiBoundary` explicitly in frontmatter to avoid round-trip fragility.
4. Compute the derived `disclosure` object per §4.7 from the resulting `aiUsage` and `aiBoundary` values, and attach it to the JSON.
5. Serialise the resulting object to canonical JSON per [RFC 8785 JCS](https://datatracker.ietf.org/doc/html/rfc8785).

A reference implementation in any scripting language is approximately 30 lines. Implementations SHOULD publish the derivation script alongside the source markdown for reviewer transparency; the markdown is the editable artefact, the script is the contract that makes the JSON reproducible. At Level 2, the canonical JSON output of step 5 is the byte sequence over which the signature is computed (§6).

### 8.4 Verification

A consumer can verify Level 1 conformance with shell-level commands:

```bash
HOST=https://example.com
# 1. The declaration is discoverable
curl -sf "$HOST/AI-USAGE.json" > /tmp/decl.json
# 2. The required fields are present
jq -e '.id, .subject, .publisher, .author, .created, .aiUsage, .aiBoundary' /tmp/decl.json
# 3. The link relation is wired up on the homepage
curl -sf "$HOST/" | grep -E '<link[^>]+rel="ai-usage"'
```

Level 2 verification additionally validates the signature using a JWS library against the public key dereferenced from `signature.keyId`.

---

## 9. Security and privacy considerations

### 9.1 Substitution

An attacker who can replace the JSON declaration on a host can issue a false disclosure. Mitigation: serve Level 2 (signed) declarations whose signature a consumer can verify independently. A consumer that requires high assurance MUST verify the signature against an independently-resolved key, not against a key served from the same host.

### 9.2 Replay and staleness

A signed declaration is bound to its canonical payload, including the `created` and `modified` timestamps. A consumer that requires freshness SHOULD reject declarations whose `modified` is older than the consumer's policy permits. The note does not mandate a freshness window in general.

Publishers that carry a `reviewSchedule` field commit to issuing a new `modified` timestamp at least as frequently as that interval, whether the underlying disclosure has changed or merely been reviewed and re-confirmed. Consumers MAY treat a declaration whose `modified` is older than the stated schedule as stale and request a fresh one before relying on its content. A declaration without `reviewSchedule` makes no such commitment; consumers MUST NOT infer staleness from age alone where the schedule is absent.

### 9.3 Identity exposure

The `author` field names a person. Publishers SHOULD consider whether the named author wishes to be associated with the work in a machine-readable, durable, web-discoverable form. For works published anonymously or pseudonymously, the `author` field carries the pseudonym, and the publisher accepts the disclosure responsibility.

### 9.4 Boundary drift

The `aiBoundary` array states commitments. A publisher who later relaxes a boundary (for example, allowing AI to draft text that earlier declarations said it would not) MUST issue a new declaration with the boundary updated. Silently relaxing a boundary while leaving the old declaration in place is a misrepresentation. The note does not specify enforcement; it specifies the publisher's normative obligation.

### 9.5 Standard scope

These are operational concerns for hosts and consumers implementing the standard, not concerns for the standard itself.

---

## 10. IANA considerations

This note introduces three artefacts that fall within IANA registries:

- The link relation `ai-usage` (§5.3), candidate for the IANA Link Relation Types registry.
- The media type `application/ai-usage-declaration+json` (§5.2), candidate for the IANA Media Types registry.
- The well-known URI suffix `ai-usage` (§5.1), candidate for the IANA Well-Known URIs registry per [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615).

Formal IANA registration for each of these is deferred to a later revision of this note, pending sufficient implementation experience to justify the request. Implementations using the unregistered link relation MAY use the extension URI form `https://mx.allabout.network/ns/ai-usage` as the `rel` value until formal registration is complete. Implementations using the unregistered media type MAY serve `application/json` with a `profile` parameter, or use the vendor-prefixed form `application/vnd.mx.ai-usage-declaration+json`, until the unprefixed registration is granted.

---

## 11. References

### 11.1 Normative

- [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119): Key words for use in RFCs.
- [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174): Ambiguity of uppercase vs lowercase in RFC 2119 key words.
- [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515): JSON Web Signature.
- [RFC 8032](https://datatracker.ietf.org/doc/html/rfc8032): Edwards-Curve Digital Signature Algorithm (EdDSA).
- [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615): Well-Known Uniform Resource Identifiers.
- [RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785): JSON Canonicalization Scheme (JCS), the canonical form used at Level 2 for the declaration payload over which the signature is computed.
- [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html): Date and time format.
- [HTML Living Standard](https://html.spec.whatwg.org/): The HTML specification, for `<link rel>` semantics.

### 11.2 Informative

- [RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309): Robots Exclusion Protocol.
- [Schema.org](https://schema.org/): Person, Organization, and CreativeWork.digitalSourceType vocabularies.
- [C2PA Specifications](https://c2pa.org/specifications/specifications/2.1/index.html): Coalition for Content Provenance and Authenticity, asset-level provenance manifests.
- [ISO 14289-1](https://www.iso.org/standard/64599.html): PDF/UA Universal Accessibility.
- [WICG AI Content Disclosure proposal](https://github.com/WICG/proposals/issues/261): page-level `<meta name="ai-disclosure">` and element-level `ai-disclosure` attribute, four-value enumeration `none` / `ai-assisted` / `ai-generated` / `autonomous`. W3C Community Group formed February 2026.
- [IPTC Digital Source Type vocabulary](https://cv.iptc.org/newscodes/digitalsourcetype/): controlled vocabulary for `CreativeWork.digitalSourceType` covering `digitalCapture`, `compositeWithTrainedAlgorithmicMedia`, `trainedAlgorithmicMedia`.
- [EU AI Act Article 50](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1689): machine-readable marking of AI-generated content, effective August 2026.
- The MX Contract Fingerprinting and Signing note: a sister draft in the MX family that elaborates a layered fingerprinting approach for cross-cog content. Referenced informatively in §6.1; the present note does not normatively depend on it.
- The MX Compliance Claims note: a sister draft in the MX family that defines the third-party authority pattern referenced at Level 3 conformance (§2.1).
- [YAML 1.2.2](https://yaml.org/spec/1.2.2/): authoring format for the frontmatter block.
- [CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/): authoring format for the human-readable body.
- [RFC 7763](https://datatracker.ietf.org/doc/html/rfc7763): media type `text/markdown` for serving the source markdown.
- llms.txt: Howard, J., September 2024, navigation aid convention for LLM agents.
- ai.txt: Spawning Labs proposal, training opt-out signalling.

---

## 12. Acknowledgements

The author thanks the publishers and authors whose first-person AI-usage disclosures, written without a standard to refer to, demonstrated the schema before it was specified. The note formalises the practice; it did not invent it.

---

## MX scope note: machine-readable documents beyond web optimisation (boundary note)

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-mx-not-geo.md
**File:** `draft-mx-not-geo.md`

# MX scope note: machine-readable documents beyond web optimisation

**Version:** 1.1
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 18 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note defines the scope of the Machine Experience (MX) framework in relation to the emerging vendor category called Generative Engine Optimisation (GEO). MX and GEO address different problems. Conflating them produces incorrect claims about what MX does and misleads practitioners about where to invest their effort.

The central MX scope claim is this: MX asks whether any machine can find any document in a corpus, verify it is genuine, and know whether it is current — regardless of which machine, which format, or which access pathway. GEO asks how to increase the probability that a specific class of LLM-powered system cites a specific web page. These are different questions with different answers.

---

## 2. Status of this note

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the scope definitions, claims, and recommendations in this note are working drafts — stable enough to build against, expected to evolve through review.

---

## 3. The GEO claim and why it fails

GEO vendors claim that adding structured markup — primarily Schema.org JSON-LD — increases the probability that LLM-powered systems cite a publisher's web page. This claim fails on its own terms.

Large language models process text as sequences of tokens. The transformer architecture does not inspect structured data tags in the way a classical search crawler does. Schema.org serves legitimate purposes in classical search (rich results, knowledge panels, voice assistant responses). It does not influence how a foundation model represents or retrieves content. The same query submitted to an LLM-powered system produces different answers across sessions, temperature settings, and model versions. No clean causal chain connects "added FAQ schema" to "the model cited my page."

GEO vendors fill this gap with dashboards and reportable metrics. The metrics measure activity, not outcomes. The outputs are defensible expenditure, not proven results.

This note takes no position on whether GEO as a category will develop a defensible evidence base. At the time of writing, it has not.

---

## 4. The MX scope

MX governance addresses a structural problem that GEO does not engage with: a machine reading a document may have no access to the originating website, no knowledge of where the document came from, and no way to verify whether it is current.

This is not a hypothetical. PDFs are downloaded and distributed. Cogs are extracted and used as context in AI pipelines. Contracts are signed and archived. White papers circulate for years after publication. In every case, the document may be encountered by a machine in isolation.

MX governance ensures that an isolated document contains everything a machine needs to:

1. Understand what it is (content type, purpose, audience)
2. Attribute it correctly (author, publisher, origin)
3. Verify it is unaltered (cryptographic signing)
4. Determine whether it is current (version, modified date, canonical location)
5. Find the authoritative source (canonicalUri, master location)

These requirements apply to every document format: web pages, PDFs (via XMP), Word documents, cogs, scripts, and any other format a machine might encounter.

---

## 5. Why the pathway is unknowable

Practitioners cannot know which machine will read a given document, or how. The machines reading content do not identify themselves reliably. User-agent strings are spoofable. Some agents screenshot rendered pages. Some read the DOM via browser automation. Some fetch raw HTML. Some request markdown. Some query structured data endpoints. Some read PDFs. Some are foundation models; some are on-device models with fewer than 100 million parameters that rely far more on explicit structure because they cannot fill gaps from inference.

The web is also architecturally hostile to machine access. Cookie banners, JavaScript-rendered content, accordion toggles, anti-scraping measures, and bot-detection systems block machines before they reach content.

The correct response to an unknowable pathway is not to optimise for one pathway and accept failure on the others. It is to build redundancy: the same facts expressed in multiple formats, across multiple access methods, so that any machine using any access method can reach the content.

---

## 6. The registry layer

MX defines a registry-contract layer that makes file-borne governance scalable at internet scope. The standard defines the contract; multiple registry operators are expected to run conforming implementations.

MX specifies that documents should carry provenance, freshness, and canonical location. A conforming registry is the system that verifies documents meet that specification, makes them discoverable, and answers a machine's questions about them via a queryable API.

A conforming registry typically operates as one or more of:

- A public, DNS-like service any agent can query without permission or payment
- A SaaS service for publishers registering their document corpus
- A private deployment for enterprise document estates

A conforming registry understands both MX YAML frontmatter and JSON-LD (Schema.org). It indexes full document metadata. An agent querying the registry receives: what the document is, who published it, when it was last signed, what version it is, and what it supersedes.

The distinction from GEO markup is architectural. GEO is passive - it adds tags to a page and depends on a crawler's behaviour. A registry is active - it provides a queryable interface an agent explicitly consults. The agent does not hope that metadata was noticed; it asks a registry and receives a verified answer.

A conforming registry attests one thing: this is the content the named publisher signed, unaltered. It makes no claim about whether the content is true, current in its subject matter, or sound in its reasoning. Editorial responsibility remains with the publisher.

---

## 7. Scope of this note

This note covers the following MX scope questions:

- What MX does (machine-readable documents across all formats and access pathways)
- What MX does not do (guarantee LLM citation, influence transformer token processing, promise specific machine behaviours)
- How a conforming registry complements MX governance (discovery, trust, currency)
- The standalone machine readability principle (a document must be interpretable in isolation)

This note does not cover:

- MX field definitions (see the MX Core Metadata note and related draft set)
- The registry-contract specification (a separate note covers the registry protocol)
- Implementation guidance for specific document formats (see Carrier Formats note)

---

## 8. Correct and incorrect claims about MX

### Correct

- "MX keeps content readable across every system that accesses it."
- "A document with full MX governance can be read, trusted, and located by any machine — in isolation."
- "A conforming registry provides explicit metadata that any agent can query directly."
- "Explicit structure reduces the need for inference, improving extraction reliability."
- "MX builds coverage across an unknowable landscape of machines and formats."

### Incorrect

- "MX makes your content AI-ready."
- "MX ensures LLMs cite your page."
- "MX eliminates hallucination."
- "Schema.org markup ensures AI discovery."
- "Future-proof your content for AI."

The distinction: correct claims describe coverage across an unknowable landscape without promising specific machine behaviour. Incorrect claims make promises about specific machine outputs that cannot be verified or guaranteed.

---

## 9. Relationship to other MX notes

This note is a scope clarification. It does not introduce new fields or change existing field definitions. It should be read alongside:

- **MX Core Metadata note** — defines the fields that implement these principles
- **MX Provenance note** — defines the attribution and trust fields that establish standalone readability
- **MX Carrier Formats note** — defines how MX metadata appears across document types
- **MX Contract Fingerprinting and Signing** — defines the cryptographic signing mechanism

---

*This note is offered to The Gathering for review and is not a ratified standard.*

---

## MX scope note: file-borne provenance beyond memory-pool architectures (boundary note)

**URL:** https://github.com/ddttom/mx-shared-gathering/blob/main/draft-mx-not-memory-pool.md
**File:** `draft-mx-not-memory-pool.md`

# MX scope note: file-borne provenance beyond memory-pool architectures

**Version:** 1.1
**Status:** Draft by Tom Cranstoun, offered to The Gathering for review
**Date:** 18 May 2026
**Author:** Tom Cranstoun
**License:** MIT

---

## 1. Abstract

This note defines the scope of the Machine Experience (MX) framework in relation to memory-pool architectures — the design pattern in which an LLM curates a structured knowledge base from raw documents and queries the curated artefact rather than the raw sources. The most cited current example is Andrej Karpathy's LLM-wiki proposal, in which Claude reads source documents and maintains an interconnected wiki of markdown files, viewed in Obsidian. The article describes raw sources as "source code" and the wiki as "the compiled executable" — you do not recompile every time you run the program.

MX and memory-pool architectures address different problems. Conflating them produces incorrect claims about what MX does and misses the complementary fit between the two.

The central MX scope claim relevant here is this: a memory-pool architecture governs how knowledge is organised inside one system. MX governs what a file carries when it leaves any system. The two are orthogonal. An MX-conformant document inside a memory pool is both better-organised by the pool and remains interpretable when an agent extracts it — at which point the pool's structure is no longer accessible and only the file's own metadata can answer the agent's questions.

---

## 2. Status of this note

This note is a draft authored by Tom Cranstoun and offered to The Gathering for review. It is not a ratified standard. Until The Gathering accepts it, the scope definitions, claims, and recommendations in this note are working drafts — stable enough to build against, expected to evolve through review.

---

## 3. The memory-pool architecture and what it does

A memory-pool architecture (LLM-wiki, Karpathy's proposal, similar designs built on top of Obsidian, Notion, or other markdown knowledge bases) treats raw documents as sources to be ingested into a curated knowledge structure. An LLM reads incoming documents, integrates them with existing pages, creates entity pages, builds backlinks, and maintains the structure as new sources arrive.

A user (or an agent) then queries the curated wiki rather than the raw sources. The argument for this pattern is that real-time retrieval against raw sources (the RAG approach) repeats expensive interpretation on every query, whereas a curated wiki accumulates structured knowledge that compounds across queries and supports multi-hop reasoning the raw-sources approach cannot reach.

The pattern is sound. It addresses a real problem. It is not the problem MX addresses.

A memory-pool architecture answers the question: *how should one system organise knowledge for its own retrieval?* That question is internal to the pool. It does not address what happens when a file leaves the pool — when it is exported, attached to an email, archived, sent to a contractor, copied into another agent's context window, or encountered by a third-party machine that has no access to the originating pool's index.

---

## 4. The MX scope

MX governance addresses a problem the memory-pool architecture does not engage with: a machine reading a file may have no access to the originating pool, no knowledge of where the file came from, and no way to verify whether it is current.

This is not a hypothetical. Files are extracted from corpora and travel as standalone objects — PDFs in email, markdown copied into chat, signed contracts archived offline, training datasets bundled and shipped, cogs embedded in agent prompts. In every case, the file is encountered by a downstream agent in isolation. The pool's index, backlinks, and entity-page structure are no longer available to that agent.

MX governance ensures the file itself carries enough metadata to answer the questions the pool would otherwise answer for it:

1. What is this file? (content type, purpose, audience)
2. Who published it? (author, organisation, originator)
3. Has it been altered? (cryptographic signature, integrity attestation)
4. Is it current? (version, modified date, supersedes / supersededBy)
5. Where is the authoritative copy? (canonicalUri, registry entry)

When these are present, an agent meeting the file in the wild reads them directly rather than inferring them from prose context. Inference is the failure mode the memory-pool architecture is itself trying to avoid; MX prevents that failure mode from re-appearing the moment a file crosses the pool's boundary.

---

## 5. The DNA framing

A useful shorthand: when you extract a file from any pool, MX is the DNA the file carries with it.

The pool — whether it is an LLM-wiki, an Obsidian vault, a CMS, a document management system, a training corpus, or a personal note collection — provides organisational context: backlinks, tags, taxonomies, the position of the file in a graph of related files. That context lives in the pool. The moment the file is extracted, the context is gone unless the file itself carries it.

DNA is the right metaphor because the metadata is *embedded in the file*, not declared by the surrounding system. A YAML frontmatter block, an XMP packet in a PDF, a Schema.org JSON-LD script in HTML, a `.mx.yaml` sidecar — these all encode the file's identity in a form that survives extraction. The downstream agent does not have to reconstruct provenance; it reads it.

This framing also clarifies what MX is *not*:

- MX is not a memory-pool design. It does not specify how a pool should organise its files.
- MX is not a retrieval algorithm. It does not specify how an agent should query a corpus.
- MX is not a substitute for RAG, vector search, or compiled-wiki approaches.
- MX does not compete with Karpathy's LLM-wiki proposal. The two are complementary.

A memory pool built from MX-conformant files is a stronger memory pool than one built from raw markdown. The pool's curated structure benefits from explicit metadata (an LLM building backlinks reads `provenanceAuthor` directly rather than inferring authorship from prose); files extracted from such a pool carry their DNA into whatever context they land in next.

---

## 6. Why this matters at LLM scale

At small scale, a memory-pool architecture is closed: one user, one Obsidian vault, one Claude session. Files rarely leave. Provenance can be implicit because the user remembers where things came from.

At LLM scale — the operating context for which Karpathy's proposal is interesting — files leave constantly. An agent extracts a wiki entry to answer a query. Another agent reads that entry and extracts a fragment to feed into a third agent's context. A research pipeline harvests entries to build a training set. A user copies an entry into an email. A regulator subpoenas the corpus. A future maintainer encounters the file three years later, divorced from the wiki it lived in.

In every one of those cases, the agent or human encountering the file has no access to the wiki's structure. The only thing the receiving party can read is the file itself. If the file carries MX metadata, the receiving party knows what it is, who wrote it, when it was published, and whether it is the current version. If the file does not, the receiving party guesses — and guesses become hallucinations at the next inference step.

This is the structural argument for MX in the memory-pool context: the pool's value compounds across queries inside the pool, but a file's value compounds across systems only when it carries its own DNA. A memory pool of MX-conformant files captures both.

---

## 7. The registry layer

MX defines a registry-contract layer that makes file-borne provenance verifiable at internet scope. The standard defines the contract; multiple registry operators are expected to run conforming implementations.

A conforming registry is a queryable service that any agent can consult to verify a document's provenance and currency. An agent encountering a file in the wild - extracted from a memory pool, attached to an email, embedded in a training dataset - can pass the file's canonical identifier to a conforming registry and receive a verified answer: this is the content the named publisher signed, unaltered, this is the current version, this is the master location.

The complementarity to memory-pool architectures is direct. Inside the pool, an LLM curates structured knowledge. Outside the pool, a conforming registry answers the questions the pool's structure would have answered if it were still accessible. The two together cover both the inside-system and outside-system cases that real-world AI deployments routinely span.

A conforming registry attests one thing: this is the content the named publisher signed, unaltered. It makes no claim about whether the content is true, current in its subject matter, or sound in its reasoning. Editorial responsibility remains with the publisher.

---

## 8. Scope of this note

This note covers the following MX scope questions:

- What MX does (file-borne metadata that survives extraction from any pool)
- What MX does not do (specify how a pool organises its files, replace RAG or compiled-wiki retrieval, design a memory architecture)
- How memory-pool architectures and MX combine (orthogonal layers, both useful)
- The DNA principle (metadata embedded in the file, not declared by the pool)

This note does not cover:

- Specific memory-pool implementations (Karpathy's LLM-wiki, Obsidian, Notion, training-corpus designs) — these are reference points, not specifications MX defines
- MX field definitions (see the MX Core Metadata note and related draft set)
- The registry-contract specification (a separate note covers the registry protocol)

---

## 9. Correct and incorrect claims about MX

### Correct

- "MX is the metadata DNA a file carries when it leaves any pool."
- "An MX-conformant file inside a memory pool remains interpretable after extraction; a raw file does not."
- "Memory-pool architectures and MX are complementary, not alternatives."
- "A conforming registry answers the questions a pool's index would have answered, but works on files in the wild."
- "Explicit file-borne metadata reduces the inference burden on every downstream agent."

### Incorrect

- "MX is a competitor to Karpathy's LLM-wiki."
- "MX is a memory-pool design."
- "MX replaces RAG or compiled-wiki retrieval."
- "An Obsidian vault is the same kind of system as MX governance."
- "MX is what Tom calls his version of an LLM-wiki."

The distinction: correct claims describe MX as the layer that makes a file interpretable when it leaves a system. Incorrect claims position MX as a system itself, competing with retrieval architectures it is in fact orthogonal to.

---

## 10. Relationship to other MX notes

This note is a scope clarification. It does not introduce new fields or change existing field definitions. It should be read alongside:

- **MX scope note: machine-readable documents beyond web optimisation** (`draft-mx-not-geo.md`) — the parallel boundary note for GEO
- **MX Core Metadata note** — defines the fields that implement file-borne DNA
- **MX Provenance note** — defines the attribution and trust fields a file needs to remain interpretable in isolation
- **MX Carrier Formats note** — defines how MX metadata is embedded across document formats so the DNA travels with the file
- **MX Contract Fingerprinting and Signing note** — defines the cryptographic signature that lets a downstream agent verify the file is unaltered

---

*This note is offered to The Gathering for review and is not a ratified standard.*

---