UW Markdown 1.1+ machine-interchange release plan

Status: RFC 0014 accepted; Phases A–E implemented

Release line: first public 1.1.x release

Owner: jaredmaxey

Last updated: 2026-07-26

Outcome

Ship stable machine representations of the existing UW Markdown record without changing the .uw.md authoring format or weakening its audit and byte-preserving edit guarantees. The release line promotes the existing .uw.json sibling, adds a secure XML codec and a normalized CSV bundle, and exposes the same representations through library, CLI, HTTP-profile, and MCP-profile surfaces.

The design authority is RFC 0014. This document coordinates releases; it does not accept the RFC or create normative behavior by itself.

Version map

UW Markdown versions each surface independently. “1.1+” is a release train, not a single version applied everywhere.

Surface	Current	Planned	Reason
.uw.md format	1.1	1.1 unchanged	No Markdown syntax or section semantics change.
UW Protocol	1.2.0 RC	1.2.0	Representation discovery, negotiation, and HTTP/MCP companion profiles implemented.
@uwmd/core	1.1.0 RC	1.1.0	Envelope, JSON/XML/CSV codecs, registry, and negotiation implemented.
uwmd CLI	1.1.0 RC	1.1.0	Digested export, representation discovery, and JSON/XML/CSV conversion implemented.
UW Document Envelope	pre-publication prototype	1.0 stable	First supported neutral envelope; _meta and prose each have one authoritative location.
UW JSON mapping	implicit	1.0.0	First independently specified encoding of the envelope.
UW XML mapping	1.0.0 RC implemented	1.0.0	Deterministic mapping, XSD, secure codec, and conversion tests complete.
UW CSV bundle	1.0.0 RC implemented	1.0.0	Normalized model codec, safe deterministic ZIP, and six views complete.

The first public package release may be v1.1.0; no unpublished v1.0.0 compatibility step is required.

Governance

RFC 0014 was accepted by the project owner on 2026-07-26 under the owner-led mode defined in GOVERNANCE.md. There is no waiting-period waiver: owner-authored normative work may proceed immediately while the project has no outside contributors. The collaborative review and comment rules activate when external contributions begin.

Each phase still updates its specification, schema, implementation, tests, version matrix, and changelog together before it is described as conformant or shipped.

Architecture review findings

Resolved in the draft

• No Markdown version bump: the proposal is encoding/protocol work, not a change to .uw.md syntax.
• Transport scope: HTTP and MCP are companion binding profiles. Protocol 1.2 standardizes representation descriptors and fidelity; it does not require a network server for any conformance tier.
• Source fidelity: byte-preserving Markdown editing remains a distinct UWSourceAdapter contract. A codec that only receives an envelope cannot recreate the original Markdown bytes.
• Views versus interchange: existing renderer JSON and one-row CSV remain named, lossy views and cannot advertise model fidelity.
• HTTP negotiation: standard Accept wildcard rules govern negotiation; structured suffixes aid content-type dispatch, not suffix-wildcard matching.
• Digest input: volatile generator fields and the digest field itself are excluded from the semantic digest.
• XML extension keys: invalid or unknown XML names use an explicit <uw:member name="…"> mapping instead of being converted into unsafe element names.

Decisions recorded 2026-07-26

• The normalized bundle is the authoritative, model-fidelity CSV representation.
• Canonical envelope 1.0 emits only content._meta and per-block prose. The unpublished experimental JSON shape is intentionally unsupported.
• The first reference exporter ships all six approved view profiles: deal_summary, rent_roll, operating_statement, debt, valuation, and sources_uses.

Transport decision recorded 2026-07-26

• Canonical deal resources use https://uwmd.org/deals/{deal_id}. Encoding and view variants use query parameters; deployment API origins remain configurable.
• A future uwmd: scheme may be proposed additively but is not required for 1.1.

Phase D fixes the ZIP media type as application/vnd.uwmd.csv-bundle+zip, keeps envelope_version for Envelope 1.0, and publishes reference limits of 50 MiB compressed, 200 MiB expanded, 100 files, and a 100:1 compression ratio.

Candidate CSV bundle

The recommended v1 bundle separates structural joins from arbitrary values and keeps business-friendly exports optional:

File	Cardinality	Required	Purpose
manifest.json	1	yes	Versions, digest, file inventory, hashes, view profiles, safety policy.
document.csv	1 row	yes	Deal identity, envelope/format version, generator metadata.
frontmatter.csv	N rows	yes	JSON-Pointer path, JSON type, canonical JSON value.
blocks.csv	1 row/block	yes	block_ref, collection, section, variant, ordinal, current/superseded state.
block_values.csv	N rows	yes	block_ref, scope (annotation, meta, content), JSON Pointer, type, canonical JSON value.
prose.csv	1 row/prose region	yes	prose_ref, scope, section/block reference, exact Markdown text.
views/*.csv	varies	no	Named, explicitly lossy business/analytics tables.

The normalized files are the model-fidelity contract. The first reference release ships deal_summary, rent_roll, operating_statement, debt, valuation, and sources_uses as optional view-fidelity files. They are included when their source sections are present and are never round-trip inputs.

ZIP is the default interchange artifact; an unpacked directory is the debugging and source-control form. Ordering, quoting, null handling, path grammar, and formula-safety policy must be pinned by golden fixtures.

Implementation phases

Phase A — Envelope and JSON ✅

• Publish uw-document-envelope.schema.json.
• Introduce envelope 1.0 with one authoritative content._meta and per-block prose location.
• Add semantic canonicalization, digest, and equivalence helpers.
• Register uw-json and distinguish it from the deal-summary JSON view.
• Add round-trip, malformed-input, semantic-digest, codec-registry, schema, and CLI tests.

Status: complete in the implementation branch. Model round-trip, digest, registry, schema, core, and CLI tests pass; .uw.md behavior is unchanged.

Phase B — Registry and discovery ✅

• [x] Add representation descriptors to ImplementationManifest and its schema.
• [x] Implement registry lookup and HTTP-compatible negotiation.
• [x] Add uwmd formats; codec conversion lands with each representation phase.

Status: complete. Protocol 1.2 changes, schema, TypeScript mirror, documentation, and negotiation tests agree; existing v1.1 implementations remain conforming. Informational HTTP and MCP binding profiles are Phase E.

Phase C — XML ✅

• [x] Specify deterministic XML mapping and namespace.
• [x] Implement a DTD/external-entity-disabled parser with resource limits.
• [x] Add structural XSD tooling support and cross-format digest tests.
• [x] Add uwmd convert for Markdown, verified UW JSON, and verified UW XML.

Status: complete in the implementation branch. JSON and XML use the same Envelope 1.0 semantic digest. Round-trip, deterministic encoding, unsafe member names, DTD/entity declarations, duplicate members, tampering, size limits, depth limits, registry discovery, and CLI conversion are tested.

Phase D — CSV bundle ✅

• [x] Finalize the normalized tables and manifest.
• [x] Implement directory and deterministic ZIP codecs with bounded safe extraction.
• [x] Add normalized round-trip, long-array, unsafe-key, tampering, traversal, decompression-bomb, file-limit, registry, and CLI fixtures.
• [x] Ship all six named views with apostrophe-prefix spreadsheet safety.

Status: complete in the implementation branch. JSON, XML, and CSV bundles share the same Envelope 1.0 semantic digest. Normalized CSV is reconstruction data; views are explicitly lossy and never used as round-trip inputs.

Phase E — API/MCP reference adapters ✅

• [x] Publish HTTP Binding 1.0, MCP Binding 1.0, and an OpenAPI 3.1 contract.
• [x] Return compact JSON in structured tool results and complete/binary artifacts as text/blob resources or resource links.
• [x] Reuse the same core registry, validator, semantic ETags, and Tier-2 editor.
• [x] Add a runnable SDK-neutral reference adapter for all five MCP tools.

Status: complete in the implementation branch. Transport examples contain no independent serialization logic and the core integration tests pin negotiation, ETags, preconditions, MCP result placement, resources, and source-preserving edits.

Release checklist

• [ ] v1.1.0 packages published and install smoke-tested.
• [x] RFC 0014 PR opened.
• [x] Project-owner acceptance recorded on 2026-07-26.
• [x] Phase A implementation prepared and linked from RFC 0014.
• [x] Phase implementation PRs #3–#6 linked from RFC 0014.
• [x] Build, tests, lint, schema validation, and conformance pass on Windows and Linux.
• [x] Security fixtures pass for JSON, XML, CSV, and ZIP inputs.
• [ ] VERSIONS.md current matrix changed only when each release actually ships.
• [x] CHANGELOG.md has per-phase release-candidate entries.
• [ ] Documentation site publishes accepted specs and representation guides.
• [ ] Packages published with provenance and install smoke-tested.

Non-goals for the first 1.1+ delivery

• Changing .uw.md syntax or its Tier-2 byte-preserving edit behavior.
• Requiring HTTP or MCP support for existing conformance tiers.
• Standardizing every asset-class-specific wide CSV.
• Durable collaborative block IDs.
• Protobuf field-number governance, Arrow/Parquet model fidelity, or streaming event semantics.