Transformer surface (intended)

This repository is a tooling-contract repository for specifications: it encodes how specs are written so they are enforceable (versioned, canonicalizable, test-mapped, and deterministic).

It is not generic “how to write specs”. It exists to make specs usable as contracts in the emsemioverse: readable by humans, actionable by agents, and checkable by tools.

Transformer surface (intended)

In the “contract as transformer” framing:

• inputs: a spec artifact (Markdown/plaintext) and its declared versioning/stability metadata
• constraints: normative language and hygiene rules; canonicalization; determinism; conformance mapping
• outputs: a conformance matrix; executable tests/fixtures; machine-readable diagnostics for violations

Enforcement surface (current):

• a drop-in normative scaffold checklist (Appendix A below)

(Future) a validator that checks for required metadata, normative statements, and test mapping.

Appendix A — Normative Scaffold (Drop‑In Checklist)

A.1 Versioning (MUST)

• Version identifiers MUST follow MAJOR.MINOR.PATCH where:
  • MAJOR: backward‑incompatible changes.
  • MINOR: backward‑compatible feature additions.
  • PATCH: backward‑compatible fixes and clarifications.
• Each spec artifact MUST declare spec-id, version, release-date (UTC, YYYY‑MM‑DD), and stability ∈ {draft, candidate, stable, deprecated}.
• Wire formats and behavior linked to a MAJOR version MUST remain stable within that MAJOR series.

A.2 Canonicalization (MUST)

• Define a single canonical byte sequence for all serializable artifacts.
• Rules MUST specify:
  • Field ordering and omission rules.
  • String normalization (Unicode NFC), whitespace policy, and number formatting.
  • Deterministic map/dict ordering.
  • Binary encoding and endianness.
• A reference function CANON(x) → bytes MUST be specified and testable (golden vectors).

A.3 Error Semantics (MUST)

• Errors MUST use a stable schema with fields:
  • code (stable, machine‑readable), name, severity ∈ {info, warn, error, fatal},
  • where (component/module), when (UTC timestamp), correlation-id,
  • fault (producer/consumer), retryable (bool), data (opaque).
• Define error classes:
  • Input/validation, Canonicalization, Version/feature, State/consistency, I/O/transport, Security/authz.
• Each algorithm step MUST specify which errors it can emit and under what preconditions.
• Ambiguities MUST be errors (not “unspecified behavior”).

A.4 Conformance (MUST/SHOULD)

• Provide a conformance matrix listing each normative “MUST/SHOULD/MAY” and the actor(s) it binds (producer, consumer, intermediary, validator).
• Publish an executable conformance suite with:
  • Golden inputs/outputs, negative cases, fuzz corpus seeds, and determinism checks.
• Implementations MUST declare a conformance-profile referencing matrix rows and test IDs.

A.5 Upgrade Path (SHOULD)

• Specify negotiated capabilities:
  • Feature flags, version ranges, and fallback behavior.
• Define deprecation windows:
  • Announcement → availability of dual‑stack behavior → removal.
• Specify migration tools/artifacts:
  • Translators, shims, and data backfills with idempotency guarantees.

A.6 Security & Privacy Notes (MUST)

• Enumerate attacker models and trust boundaries.
• State confidentiality/integrity expectations for canonical bytes on the wire and at rest.
• Specify required mitigations (authn/authz, replay protection, input limits, timing channels).
• Define data retention and minimization requirements.

A.7 Interop & Determinism (MUST)

• All observable outputs for the same canonical inputs MUST be bit‑for‑bit identical across conforming implementations.
• Randomness MUST be explicitly parameterized and seeded via inputs; otherwise it is forbidden in normative algorithms.

A.8 Registries & IANA‑like Tables (MAY/SHOULD)

• If extension points exist, define:
  • Registration policy, review process, collision handling, and permanence.
• Each registry entry MUST include: identifier, status, spec reference, and security notes.

A.9 Formal Artifacts (SHOULD)

• Provide machine‑readable schemas (e.g., JSON Schema/ASN.1/IDL) and reference TCK hooks.
• Include pseudo‑code that is executable or trivially transpilable.

A.10 Document Hygiene (MUST)

• Each “MUST/SHOULD/MAY” statement is normative and test‑mapped (link to conformance ID).
• All examples MUST indicate whether they are normative (golden) or informative (illustrative).
• The spec MUST include a glossary and an explicit non‑normative “Rationale” annex.