From 1916324e6d2c0dac0fd48f2401b654303ab228f9 Mon Sep 17 00:00:00 2001 From: James Maes Date: Sun, 1 Nov 2026 14:38:41 -0600 Subject: [PATCH] fix(protocol): reserve printing 2.3 for media contracts Keep printing 2.2 assigned to rendering and require 2.3 for media, operator and retained-source support. Document capability negotiation without changing the wire version, schemas or fixtures. Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: James Maes --- CHANGELOG.md | 7 +++++-- README.md | 3 ++- docs/PRINTER-MEDIA.md | 9 ++++++--- docs/SESSION-STATE.md | 2 +- docs/VERSIONS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 55 insertions(+), 7 deletions(-) create mode 100644 docs/VERSIONS.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f06454e..1946377 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,9 +8,12 @@ recovery contracts, including stable actor-scoped request keys. - Add `printer-media-v1` capability negotiation; selected-profile jobs require a supporting current client, including after capability downgrade/reconnect. -- Retain wire version 1 and the realtime transport. Printing extension 2.2.0 - advertises the additive native routes. Consumer runtime, installed and physical +- Retain wire version 1 and the realtime transport. Printing extension 2.3.0 + advertises the additive native routes; 2.2.0 is the separate rendering extension + and carries no media negotiation. Consumer runtime, installed and physical acceptance remain required before a coordinated release. +- Add the [extension version registry](docs/VERSIONS.md). No schema or fixture shape + changed for the 2.2 to 2.3 reservation. ## 0.3.0-rc.1 — 2026-10-31 diff --git a/README.md b/README.md index bdc946d..a7f80de 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@ Shared contract for the [QQQ 4.1+ printing QBit](https://github.com/QRun-IO/qbit Current release candidate: [**0.3.0-rc.1**](https://github.com/QRun-IO/qqq-print-protocol/releases/tag/v0.3.0-rc.1). Previous distribution: [**0.2.0-rc.1**](https://github.com/QRun-IO/qqq-print-protocol/releases/tag/v0.2.0-rc.1). Wire protocol: **v1**. This repository supplies specification, JSON Schema and synthetic compatibility fixtures; install the Windows connector and integrate the QBit from their own repositories to print documents. The next candidate, **0.4.0-rc.1**, adds the [printer media and operator -contract](docs/PRINTER-MEDIA.md) for printing semantic extension **2.2.0**. It is +contract](docs/PRINTER-MEDIA.md) for printing semantic extension **2.3.0** (see the +[extension version registry](docs/VERSIONS.md); 2.2 is rendering only). It is under consumer qualification and is not a published release. Media profiles represent configured Windows queue defaults with exact revision binding; operator access uses normal current-user and tenant authorization without diff --git a/docs/PRINTER-MEDIA.md b/docs/PRINTER-MEDIA.md index 6fe5fcf..cfd7809 100644 --- a/docs/PRINTER-MEDIA.md +++ b/docs/PRINTER-MEDIA.md @@ -2,9 +2,12 @@ This additive contract is under implementation for the Echo integration. It is not advertised by the installed 0.3.2 client. Existing wire version 1 and the -WebSocket subprotocol remain unchanged. The server extension is 2.2.0 in the -implementation branch; immutable consumer artifacts must be qualified together -before publication. Older 2.x deployments do not promise the operator routes. +WebSocket subprotocol remain unchanged. The feature minimum is printing extension +2.3.0 (see [VERSIONS.md](VERSIONS.md)); immutable consumer artifacts must be +qualified together before publication. A client must offer `printer-media-v1` only +after discovering a stable 2.3+ extension within major two, so a 2.2 (rendering) +server keeps it a three-capability peer. Older 2.x deployments do not promise the +operator routes. A client advertising `printer-media-v1` reports optional `mediaProfiles` in each exposed printer's inventory. The initial implementation reports at most one diff --git a/docs/SESSION-STATE.md b/docs/SESSION-STATE.md index d2be63d..02c894f 100644 --- a/docs/SESSION-STATE.md +++ b/docs/SESSION-STATE.md @@ -10,7 +10,7 @@ dimension options. These tests establish the draft wire shape only. Matching Windows discovery/revalidation, least-privilege operator catalog and submission, and atomic retained-source adoption are active in separate consumer -branches. The server source targets extension 2.2.0; no compatible published +branches. The server source targets extension 2.3.0 (2.2.0 is rendering on protected main); no compatible published consumer tuple is qualified yet. The installed 0.3.2 client does not advertise this capability. No physical output was submitted. diff --git a/docs/VERSIONS.md b/docs/VERSIONS.md new file mode 100644 index 0000000..6ccf0f8 --- /dev/null +++ b/docs/VERSIONS.md @@ -0,0 +1,41 @@ +# Extension version registry + +Three version numbers are independent. Do not compare them. + +| Number | Meaning | Current | +| --- | --- | --- | +| Wire payload version | Shape of the JSON messages in this repository | 1 | +| WebSocket subprotocol | Framing and message envelope | `qqq-printing.v1` | +| Printing semantic extension | Server feature level discovered at `/qqq/v1/version` | see below | + +## Printing semantic extension + +Extension versions are discovered, never assumed. Within major 2 each minor is +additive and keeps the earlier behavior. + +| Extension | Adds | Contract | +| --- | --- | --- | +| 2.0.0 | Authenticated realtime channel is required for native claims; no polling fallback | [REALTIME.md](REALTIME.md) | +| 2.1.0 | Record, table-list and text print processes | server documentation | +| 2.2.0 | Render-to-PDF process, header and footer values, content sections. No media negotiation | server documentation | +| 2.3.0 (unreleased, reserved) | Least-privilege operator catalog, submission and request lookup; reported queue-default media and `printer-media-v1`; opt-in retained-source facade | [PRINTER-MEDIA.md](PRINTER-MEDIA.md) | + +## Negotiation rules + +- A client advertises a capability only when it supports it **and** the discovered + extension is a stable `major.minor.patch` version in major 2 at or above the + feature minimum. `printer-media-v1` has minimum 2.3.0. +- A client facing 2.0, 2.1 or 2.2 stays a three-capability peer (`realtime-v1`, + `REFRESH_INVENTORY`, `CANCEL_SPOOL`) and sends no media inventory. +- A server must not let a client that did not advertise `printer-media-v1` claim a + job that carries a media selection, whatever extension version that client + discovered. +- Capabilities are re-evaluated on each new socket, so a server upgrade from 2.0 + to 2.3, or a downgrade from 2.3 to 2.2, takes effect at the next reconnect + without a polling schedule. +- Pre-release, ambiguous or malformed versions (`2.3.0-rc.1`, `2.3`, `02.3.0`, + four-part values) never enable a feature. + +The 2.3.0 number is reserved for the unreleased operator, media and retained-source +feature set. It is not a published release until consumer artifacts are qualified +together. -- 2.54.0