published-language/envelope/SPEC.md

Assertion Envelope — Specification v0.1

Status: draft until the pull request introducing it is approved; versioned thereafter under the compatibility policy below, never by ADR status (ADR-061 §3.3 as amended by A1: the contract is published, versioned and deprecated — it is not proposed or endorsed). Mandated by: ADR-061 §10.2. The ten-field sketch of ADR-061 §3.3 is the documented origin of this text and is not normative. Where they differ, this specification prevails. Normative language: English. A French companion may exist; it is not normative. The key words MUST, MUST NOT, SHOULD and MAY are to be read as in RFC 2119.

---

1. Purpose

The envelope is the single exchange format for assertions between jurisdictions. A jurisdiction is an authority that asserts — a project, a platform, an organisation; the topology is fractal and the roles are relative. The envelope carries what a jurisdiction states, with its provenance and its confidence, so that another jurisdiction can reference, annotate and aggregate it — never amend it.

One design intent governs every rule below: divergence is exposed, not reconciled. A message that cannot be fully understood is preserved, not rejected; a disagreement between jurisdictions becomes a conflict assertion, not an overwrite.

2. Intangible invariants

No future version of this contract, major versions included, may:

1. rewrite an assertion's identity in transit;
2. alter an assertion's provenance or confidence in transit;
3. introduce any cross-jurisdiction overwrite or amendment operation;
4. abandon the append-only character of exchanges.

These four derive from ADR-061 §3.2 and §2.2. They are constitutive of the federation and are not negotiable by this contract. A version that violated them would not be a new version of the envelope; it would be a different product.

3. Message

An envelope message is a single assertion, encoded as a JSON object or an equivalent YAML mapping, validating against schema/assertion.schema.json.

envelope: "0.1"
id: openathle/PU-001
class: traversal
subject: "Renouvellement de licence athlète, saison N+1"
statement: "Permettre à un athlète de reconduire sa licence sans ressaisir son dossier."
evidence:
  - kind: source
    ref: "docs/parcours/PU-001-renouvellement-licence.md"
provenance: imported
confidence: 0.4
endorsement: null
jurisdiction: openathle
at: "2026-09-04T00:00:00Z"
lifecycle: proposed
relations:
  depends_on: [openathle/ADR-025, openathle/ADR-014]
deadline: null
falsification: null

4. Fields

Fifteen fields. Eleven are required; endorsement, deadline, falsification are required but nullable; relations and evidence may be empty. Producers MUST NOT add fields outside this table except extension fields (§7).

#	Field	Type	Constraint
1	envelope	string	REQUIRED. The version of this contract, e.g. "0.1". A message that does not declare its version is not versioned — it is only dated by its documents (A1 §3). SHOULD be the first key
2	id	string	REQUIRED. <jurisdiction>/<local-id>. The prefix names the asserting authority. Never rewritten in transit (§2.1)
3	class	string	REQUIRED. One of §5
4	subject	string	REQUIRED. What the assertion is about
5	statement	string	REQUIRED. What is asserted, in one sentence or few
6	evidence	list of {kind, ref}	REQUIRED, MAY be empty. A conflict without evidence asks to be believed; evidence names where the fact lives
7	provenance	string	REQUIRED. One of §6. Transported verbatim (§2.2)
8	confidence	number	REQUIRED. 0.0–1.0. Transported verbatim. Interpretation policies — decay, half-life, thresholds — are consumer-local readings and MUST NOT modify the transported value
9	endorsement	object or null	REQUIRED. {by, at, rite}; rite is one of pr_approval, ui, batch. null means: no human has endorsed this — which is a fact, not a defect
10	jurisdiction	string	REQUIRED. MUST equal the prefix of id. Lowercase ASCII, no separators
11	at	string	REQUIRED. RFC 3339 timestamp of the asserted state
12	lifecycle	string	REQUIRED. One of proposed, endorsed, superseded, rejected, under_revision
13	relations	object	REQUIRED, MAY be empty. Keys among amends, supersedes, depends_on, satellite_of; values are lists of prefixed ids
14	deadline	string or null	REQUIRED. RFC 3339. When a falsifiable statement expires into a verdict
15	falsification	string or null	REQUIRED. What observation would make this assertion false. A hypothesis without one is not a hypothesis

lifecycle states what the origin jurisdiction declares about its own assertion; endorsement records the proven event. The two are irreducible: a declared status is not an approval (ADR-070 §3.2).

5. Classes

invariant, step_realized, transition, traversal, stressor, decision, constraint, measure, conflict, hypothesis.

Internal cardinality rules of any jurisdiction do not bind this contract (A1 §2.6, decision 4). Adding a class is a MINOR change under §8, because of the consumer tolerance rule: a consumer that meets an unknown class MUST treat the message as opaque-but-preserved, MUST NOT reject it, and MUST NOT interpret its body.

6. Provenances

human, agent:<name>, inferred, measured, imported.

Axes never mix: inferred is a provenance, not a class. imported marks what crossed a jurisdiction boundary: the importer is not the author, and importing never upgrades confidence.

7. Extensions

A jurisdiction MAY attach fields named x_<jurisdiction>_<field>. Consumers MUST preserve them on relay and MAY ignore them. Promotion of an extension to a standard field is a contract change under §8.

8. Compatibility policy

• Versioning is MAJOR.MINOR. MINOR: additions (fields, classes, relation kinds, rites) that consumers can ignore or treat as opaque. MAJOR: removal, renaming, or semantic change of anything existing.
• At most two published versions per year. Deprecation is announced in this file at least one version before removal.
• Consumers MUST accept any message whose envelope shares their MAJOR and declares an equal or lower MINOR, and SHOULD accept a higher MINOR by ignoring what they do not know.
• Unknown fields: preserved on relay, never silently dropped, never a reason to reject.
• The envelope field itself is the last change that was free to make; from v0.1 onward its removal or renaming is a contract-breaking impossibility (§2 does not list it, but §8 does: it is how every other promise is checked).

9. Conformance

Two profiles. The test set in conformance/ is normative: an implementation that fails it does not conform, whatever its documentation says.

Producer — MUST emit messages that validate against the schema; MUST prefix id with its own jurisdiction and set jurisdiction to that prefix; MUST NOT emit an endorsement it did not witness as a dated event; MUST NOT emit measured provenance for anything a machine did not measure.

Consumer — MUST NOT mutate id, provenance or confidence of a received assertion; MUST NOT reject messages carrying unknown classes or unknown fields (preserve, expose, move on); MUST record received assertions append-only; MAY annotate, reference and aggregate received assertions under its own identity, and MUST NOT present the result as the origin's.

10. What this contract does not do

It does not say how assertions are stored, projected, displayed or decayed — those are jurisdiction-local. It does not transport source documents: sealing and encrypting source payloads is storage, not exchange. It does not decide who is right: it keeps both parties quotable, at their own risk.