diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c76e3c4..c01e921 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,13 +2,13 @@ Use Node.js 24 or newer. Install the locked development dependencies with `npm ci`, then run `npm run check` (`npm test` is the standard entry point for the same check). The runtime protocol has no JavaScript dependency; Ajv and ajv-formats are development-only JSON Schema validators. -Make changes through a pull request. Describe the client/server behavior affected and update README, schema, fixtures and changelog together. Keep credentials, customer documents, printer addresses and machine-specific data out of fixtures. Samples must remain synthetic. +Make changes through a pull request to `main` on the [primary Gitea repository](https://git.kof22.com/QRun-IO/qqq-print-protocol). GitHub is a readable shadow; do not open ordinary development PRs or publish releases there. Describe the client/server behavior affected and update README, schema, fixtures and changelog together. Keep credentials, customer documents, printer addresses and machine-specific data out of fixtures. Samples must remain synthetic. Run both the Java and .NET consumers' protocol tests for a contract change. Check out sibling `qbit-printing`, `qqq-print-agent` and this repository; see [integration notes](docs/INTEGRATION.md). Coordinate consumer changes before merging a breaking change. -Keep wire names stable within `/printing/v1`. Optional response fields may be added; clients ignore unknown response fields. Removing/renaming a field, changing its type or changing an existing field's meaning requires a new protocol version. A prerelease package version is not permission to silently break an already deployed connector. +Keep wire-v1 payload names stable for native `/qqq/v1/qbit/printing` and explicit legacy `/printing/v1` routes. Optional response fields may be added; clients ignore unknown response fields. Removing/renaming a field, changing its type or changing an existing field's meaning requires explicit versioned compatibility design. Package, printing extension, wire and WebSocket subprotocol versions are independent; see [the version registry](docs/VERSIONS.md). A package version is not permission to silently break an already deployed connector. -`npm run bundle` produces the release archive and checksum in `dist/`. Do not hand-edit generated checksums. Release tags must match the version in package.json, prefixed with `v`. Commits and releases are made by maintainers after review. +`npm run bundle` produces the release archive and checksum in `dist/`. Do not hand-edit generated checksums. Release tags must match the version in package.json, prefixed with `v`. Maintainers publish reviewed artifacts on [Gitea releases](https://git.kof22.com/QRun-IO/qqq-print-protocol/releases). GitHub Actions for this repository were retired on 2026-11-04; retained `.github/scripts` remain local/shared-CI tooling. See [current release provenance](docs/INTEGRATION.md#stable-printing-release) before updating consumer fixture pins. ## Script quality diff --git a/README.md b/README.md index bbec0a2..3594d7e 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,33 @@ # QQQ Print Protocol v1 -Shared contract for the [QQQ 4.1+ printing QBit](https://github.com/QRun-IO/qbit-printing) and [Windows AppKit connector](https://github.com/QRun-IO/qqq-print-agent). The coordinated [realtime extension 2.0](docs/REALTIME.md) uses a client-initiated authenticated WebSocket for controls, receipts and job notifications, with separate streamed HTTPS documents and no polling fallback. This contract is authoritative for wire names; language types may use their idiomatic naming. +Shared contract for the [QQQ 4.1+ printing QBit](https://git.kof22.com/QRun-IO/qbit-printing) and [Windows AppKit connector](https://git.kof22.com/QRun-IO/qqq-print-agent). The [realtime transport](docs/REALTIME.md) uses a client-initiated authenticated two-way WebSocket for controls, receipts and job notifications, with separate streamed HTTPS documents and no polling fallback. No inbound connection to the facility is required. This contract is authoritative for wire names; language types may use their idiomatic naming. -Distribution version: **1.0.0**. Earlier release candidates: [0.4.0-rc.1](https://github.com/QRun-IO/qqq-print-protocol/releases/tag/v0.4.0-rc.1) and [0.3.0-rc.1](https://github.com/QRun-IO/qqq-print-protocol/releases/tag/v0.3.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. +Published distribution: [**1.0.0**](https://git.kof22.com/QRun-IO/qqq-print-protocol/releases/tag/v1.0.0). Wire protocol: **v1**. The stable cohort pairs [Windows 1.0.1](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1) with [QBit 1.0.0](https://git.kof22.com/QRun-IO/qbit-printing/releases/tag/v1.0.0), printing semantic API **2.3.0**, and QQQ **4.1.0-RC.21**. See [release and fixture provenance](docs/INTEGRATION.md#stable-printing-release). 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. -Version **0.4.0-rc.1** added the [printer media and operator +The stable release includes the [printer media and operator 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), which 1.0.0 -carries unchanged. Media profiles +[extension version registry](docs/VERSIONS.md); 2.2 is rendering only). Media profiles represent configured Windows queue defaults with exact revision binding; operator access uses normal current-user and tenant authorization without -granting device management. The installed 0.3.2 client does not support these -profiles. Wire version 1 and the client-initiated realtime transport stay the same. +granting device management. Use the stable cohort above for these profiles; +older 0.3.2 clients do not support them. Wire version 1 and the client-initiated +realtime transport stay the same. + +## Current connection and delivery + +1. Configure the QQQ server origin in the Windows app. Discover its UI/UX API and sign in using the server's configured authentication method. +2. Enroll the computer under that user and select which local Windows queues to expose. Approve the intended queues in QQQ. +3. The client opens the authenticated WebSocket, synchronizes settings and desired state, then listens for committed job and control events. +4. A job notification starts an authenticated HTTPS claim and streamed document download. Controls remain responsive during large transfers. +5. The client verifies the document, journals submission and sends durable status receipts over the socket. A lost connection automatically reconnects and reconciles pending work without blindly printing it again. + +QQQ user, tenant, table, process and record permissions remain authoritative. +Document limits are configurable: the realtime defaults are 100 MiB for PDF and +20 MiB for ZPL. See [authentication](docs/QQQ-AUTHENTICATION.md), +[operational settings](docs/REALTIME.md#operational-settings-and-client-ceilings), +and [printer media selection](docs/PRINTER-MEDIA.md). + +## Development Use Node.js 24+ to run the development checks: @@ -40,7 +56,7 @@ Use `Content-Type: application/json` except the content-download response. The e The host application authenticates management requests and determines authorized tenant/facility scope. A standalone local test host may use a configured administrative bearer credential. Device ownership, tenant and facility are taken from server records, not trusted request fields. -## Endpoints +## Historical compatibility endpoints | Method/path | Request | Successful response | | --- | --- | --- | @@ -58,14 +74,14 @@ The host application authenticates management requests and determines authorized | GET `/admin/jobs` | none | 200 `{ "jobs": [PrintJob] }` | | GET `/admin/jobs/{jobId}` | none | 200 `PrintJob` | -Device lists and job lists are scoped by host authorization. Listing pagination and destination/profile CRUD are beyond this first wire contract. Native application code may submit through the QBit service rather than the management HTTP API. +Device lists and job lists are scoped by host authorization. Bounded job/printer pagination is described below; destination/profile CRUD is outside this wire contract. Native application code may submit through the QBit service or the authorized [operator API](docs/PRINTER-MEDIA.md). The additive [device-control contract](docs/DEVICE-CONTROLS.md) defines capability discovery, dispatch pause/resume, operational disconnect/reconnect, permanent credential revocation, inventory refresh, queued-job clearing, and exact owned -Windows spool cancellation. It uses durable request identities, bounded command -polling, and explicit receipts. These additions are included in the -`0.2.0-rc.1` distribution, with 42 definitions and 54 validated fixtures. +Windows spool cancellation. It uses durable request identities and explicit +receipts over the realtime channel. Historical command-polling DTOs remain for +explicit compatibility; they are not the stable client's transport. ## DTOs @@ -97,7 +113,7 @@ Formats: `PDF` (`application/pdf`) and `ZPL` (`application/vnd.zebra-zpl`). Cont 6. Connector persists the job locally, reports RECEIVED, downloads `/device/jobs/{jobId}/content`, verifies byte length/hash, and validates the format/printer mapping. 7. Connector records SUBMITTING locally and reports it before invoking Windows. After success it records and reports SPOOLED, including a spooler reference when available. Submission must not be presented as physical print confirmation. -Content downloads derive authorization from the authenticated device and job assignment. They never accept arbitrary URLs. Default decoded document limit is 20 MiB. Copies range from 1 to 100. Reject empty documents, unsupported formats and unsupported printer capabilities before queuing. +Content downloads derive authorization from the authenticated device and job assignment. They never accept arbitrary URLs. The historical HTTP defaults were 20 MiB and 100 copies; current native limits are the configurable policy in [REALTIME.md](docs/REALTIME.md). Reject empty documents, unsupported formats and unsupported printer capabilities before queuing. ## Minimal delivery rules @@ -157,11 +173,11 @@ Error body: `{ "code": "ERROR_CODE", "message": "Human-readable explanation" }`. `npm run check` compiles every JSON Schema 2020-12 definition with Ajv and validates all shared fixtures, then checks ZPL bytes/hash/base64 and representative invalid inputs. The two pinned development dependencies are solely for standards-compliant schema validation; they do not enter either printing implementation's runtime. -`node tools/verify-fixtures.mjs` remains a dependency-free subset check. Java and .NET implementations should consume these exact fixtures in protocol tests, pinned to a reviewed immutable protocol commit. The Java HTTP round trip and .NET fixture compatibility checks passed during initial development. CI configuration is included; a local check does not imply that GitHub CI has run. +`node tools/verify-fixtures.mjs` remains a dependency-free subset check. Java and .NET implementations consume shared fixtures pinned to a reviewed immutable protocol commit. The Java HTTP round trip and .NET fixture compatibility checks passed during initial development. Gitea is the primary CI and release service; the protocol repository's GitHub Actions were retired on 2026-11-04. See [release and fixture provenance](docs/INTEGRATION.md#stable-printing-release) for the retained Windows fixture bridge and the scope of release evidence. ## Branded test-document profiles -`DeviceTestPrintRequest` optionally includes `testProfile`. PDF accepts `LETTER`, `A4`, or a `LABEL_4X6_*`, `LABEL_4X2_*` or `LABEL_4X1_*` profile (all profiles of one height produce the same PDF: 101.6 × 152.4, 50.8 or 25.4 mm). ZPL accepts those label profiles with `_203`, `_300` or `_600`; the suffix selects the printer resolution in dots per inch. For the 4 × 2 and 4 × 1 PDFs the server also submits `options.paperWidthMm`/`paperHeightMm` (101.6 × 50.8 or 25.4) so the client sets actual-size job paper; they are never combined with `mediaProfile`. The 4 × 6 PDF and all ZPL labels carry no job paper. These profiles require an agent and server from the same unreleased 0.4 cohort; older agents reject job paper. Use possible-value selectors in operator interfaces and match the loaded stock and device resolution. The profile defines document layout; it does not reconfigure Windows paper stock. +`DeviceTestPrintRequest` optionally includes `testProfile`. PDF accepts `LETTER`, `A4`, or a `LABEL_4X6_*`, `LABEL_4X2_*` or `LABEL_4X1_*` profile (all profiles of one height produce the same PDF: 101.6 × 152.4, 50.8 or 25.4 mm). ZPL accepts those label profiles with `_203`, `_300` or `_600`; the suffix selects the printer resolution in dots per inch. For the 4 × 2 and 4 × 1 PDFs the server also submits `options.paperWidthMm`/`paperHeightMm` (101.6 × 50.8 or 25.4) so the client sets actual-size job paper; they are never combined with `mediaProfile`. The 4 × 6 PDF and all ZPL labels carry no job paper. These profiles are included in the stable cohort above; older agents may reject job paper. Use possible-value selectors in operator interfaces and match the loaded stock and device resolution. The profile defines document layout; it does not reconfigure Windows paper stock. Requests that omit the field retain compatible defaults: PDF uses Letter, ZPL uses 4 × 6 at 203 dpi. An explicit null, unknown profile, or Letter/A4 with ZPL is invalid. A stable requestId protects transport retries; changing document media is a new operator request. Each action queues one test on each explicitly selected destination, subject to the existing exposure and approval checks. No discovery or connection event automatically prints. diff --git a/SECURITY.md b/SECURITY.md index 076515e..6219126 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,6 +2,6 @@ This repository specifies the QQQ printing wire boundary. Implementations must authenticate every device operation, bind jobs and content to the enrolled device, restrict administration separately, and avoid automatically reprinting uncertain submissions. -Report vulnerabilities privately using [GitHub private vulnerability reporting](https://github.com/QRun-IO/qqq-print-protocol/security/advisories/new). If that channel is unavailable, contact `contact@kingsrook.com`. Do not publish working device tokens, enrollment codes, customer print content or exploit details in a public issue. +Report vulnerabilities privately using [GitHub private vulnerability reporting](https://github.com/QRun-IO/qqq-print-protocol/security/advisories/new). If that channel is unavailable, contact `contact@kingsrook.com`. This private reporting channel remains available while [Gitea](https://git.kof22.com/QRun-IO/qqq-print-protocol) is primary for source, pull requests and releases. Do not publish working device tokens, enrollment codes, customer print content or exploit details in a public issue on either forge. -Fixes target the current prerelease and protocol v1 consumers; there is no separate legacy support branch. TLS, token storage, host permissions and printer-command restrictions are implemented and assessed in the server and Windows repositories. +Fixes target stable protocol 1.0.0 and supported wire-v1 consumers; there is no separate legacy support branch. TLS, token storage, host permissions and printer-command restrictions are implemented and assessed in the [server](https://git.kof22.com/QRun-IO/qbit-printing) and [Windows](https://git.kof22.com/QRun-IO/qqq-print-agent) repositories. Native printing requires the current QQQ user session plus secondary device proof; a transport failure never permits an authentication or polling fallback. diff --git a/docs/CI-COMPATIBILITY.md b/docs/CI-COMPATIBILITY.md index 5d94912..ccfff84 100644 --- a/docs/CI-COMPATIBILITY.md +++ b/docs/CI-COMPATIBILITY.md @@ -1,5 +1,10 @@ # Workflow compatibility — 2026-10-30 +Historical decision retained unchanged below. Protocol GitHub Actions were +retired on 2026-11-04 at 01:11 UTC; Gitea is now the primary CI and release +service. This snapshot does not describe current upstream tool versions or a +new hosted result. See [current publication and fixture provenance](INTEGRATION.md#stable-printing-release). + The `zizmor/self-repository` advisory recommends GitHub's newer `$/` syntax. This repository currently uses `./.github/workflows/...` **only for job-level reusable workflow calls**. GitHub documents that both forms select the same commit as the calling workflow. These are not step-level local actions that resolve from a potentially different workspace checkout. The latest released actionlint, **1.7.12**, rejects `$/` reusable workflow calls. This was reproduced locally with the pinned version; the unchanged `./` calls pass. The upstream compatibility issue is still open. Retaining the supported job-level form preserves full actionlint validation of the called workflow, including its inputs and permissions, without suppressing the syntax rule or disabling any security check. diff --git a/docs/DEVICE-CONTROLS.md b/docs/DEVICE-CONTROLS.md index 79d08d7..7bbf2c1 100644 --- a/docs/DEVICE-CONTROLS.md +++ b/docs/DEVICE-CONTROLS.md @@ -1,6 +1,6 @@ # Device controls — additive wire v1 -For the coordinated printing extension 2.0 implementation, these domain state, +For the stable printing cohort (native extension 2.3.0), these domain state, command and receipt semantics use [direct realtime frames](REALTIME.md). The HTTP polling routes below describe the earlier 1.0/explicit compatibility transport and are never a fallback for a realtime client. @@ -8,13 +8,14 @@ transport and are never a fallback for a realtime client. This extension provides server dispatch controls and two bounded Windows agent commands. Its additive payloads preserve existing print job states and old request bodies. These domain controls were published in package `0.2.0-rc.1`; -their realtime transport is part of release candidate `0.3.0-rc.1`. This contract does -not establish deployment or production readiness. +their realtime transport was introduced in `0.3.0-rc.1` and is included in +[stable protocol 1.0.0](INTEGRATION.md#stable-printing-release). Deployment and physical output evidence +belong to the implementation repositories. ## Discovery and routes The primary transport is the discovered QQQ semantic extension at -`/qqq/v1/qbit/printing`, extension version `1.0.0`, using channel +`/qqq/v1/qbit/printing`, extension version `>=2.0.0 <3.0.0`, using channel `api/qqq-print-agent`. Standard QQQ session authentication and current user, tenant, table, process and record permissions apply. Device calls additionally send `X-QQQ-Device-Id` and `X-QQQ-Device-Token`; that secondary proof does not @@ -51,7 +52,7 @@ a missing capability or 404 is a failure, never permission to bypass saved state Native printing extension `1.0.0` includes these controls; a native-route 404 is always a configuration or compatibility failure, never legacy discovery. -The new poll reports `controlVersion:1`, `agentVersion`, `capabilities`, and +The historical compatibility poll reports `controlVersion:1`, `agentVersion`, `capabilities`, and `lastAppliedRevision`. The two capability names are `REFRESH_INVENTORY` and `CANCEL_SPOOL`; an empty list is valid for a state-only agent. A successful poll establishes state-control support independently of these command capabilities. @@ -73,19 +74,20 @@ and `CONNECTED`. Changes are committed atomically with their action record and advance the revision. Revisions are nonnegative JSON-safe integers, at most 9007199254740991. A device reports a revision only after applying and durably retaining that state; it cannot acknowledge a future server revision. The agent -must not replace newer persisted state with an older poll response. +must not replace newer persisted state with an older received revision. The control loop runs independently of printing. Pausing or disconnecting gates new claims and dispatch. It does not cancel CLAIMED or later work, erase local journals, withdraw exposure selections, or discard in-flight job events. Claims and server state changes are serialized so work claimed before the change remains in flight. Before first synchronization or after restart, the agent retains the -last state and withholds new claims until valid state or explicit legacy support -has been established. +last state and withholds new claims until authenticated realtime synchronization +has completed. Historical clients instead used explicit legacy support discovery. `DISCONNECTED` stops ordinary heartbeat, inventory publication, and new claims. -Authenticated control polling, command receipts, and in-flight job events remain -available, so `RECONNECT` can reach the device. `REFRESH_INVENTORY` waits for +The authenticated socket, command receipts, and in-flight job events remain +available, so `RECONNECT` can reach the device; historical clients used control +polling for this purpose. `REFRESH_INVENTORY` waits for `CONNECTED` or expires; it must not report success without publishing inventory. Explicit `CANCEL_SPOOL` remains available over the control path while disconnected. Reconnecting does not clear `dispatchPaused`; resuming does not change connection @@ -150,10 +152,11 @@ history or document retention. Remote actions initially return `PENDING`. `DeviceCommand` carries stable `commandId`, `requestId`, `action`, `createdAt`, `expiresAt`, and, for spool cancel, -`jobId`. Server-created expiry is 15 minutes after creation. One poll returns at -most 20 commands and `serverTime`, `pollIntervalSeconds` (1–300), and the full -desired state. Pending commands may be delivered repeatedly until a receipt or -expiry; they are not new commands on every poll. Do not deliver expired commands. +`jobId`. Server-created expiry is 15 minutes after creation. The realtime server +delivers `COMMAND` frames and replays unexpired pending commands after reconnect. +The historical poll returns at most 20 commands and `serverTime`, +`pollIntervalSeconds` (1–300), and the full desired state. Repeated delivery does +not create a new command. Do not deliver expired commands. The agent journals command identity and execution state before a side effect. Use the current enrollment/connection scope. It checks expiry before beginning, diff --git a/docs/INTEGRATION.md b/docs/INTEGRATION.md index 8ab1773..7300e24 100644 --- a/docs/INTEGRATION.md +++ b/docs/INTEGRATION.md @@ -1,14 +1,70 @@ # Consumer integration +## Stable printing release + +The primary [protocol 1.0.0 release](https://git.kof22.com/QRun-IO/qqq-print-protocol/releases/tag/v1.0.0) +is published on Gitea (release record 1344). This is the specification and fixture +bundle, not an application installer. + +| Component | Stable cohort | +| --- | --- | +| Protocol distribution | [1.0.0](https://git.kof22.com/QRun-IO/qqq-print-protocol/releases/tag/v1.0.0) | +| Windows Print Agent | [1.0.1](https://git.kof22.com/QRun-IO/qqq-print-agent/releases/tag/v1.0.1) | +| Printing QBit | [1.0.0](https://git.kof22.com/QRun-IO/qbit-printing/releases/tag/v1.0.0) | +| QQQ dependency baseline | 4.1.0-RC.21; printing targets QQQ 4.1+ | +| Native printing semantic API | 2.3.0 | +| Wire payload / WebSocket subprotocol | 1 / `qqq-printing.v1` | + +Upgrade the server before the matching Windows connector. The connector opens an +authenticated two-way WebSocket from the facility to QQQ. Job notifications, +controls and receipts use that channel; documents stream separately over +same-origin HTTPS. Reconnection is automatic and preserves durable job/receipt +identity. There is no job/control polling fallback. Standard QQQ authentication +and current-user permissions apply throughout. + +### Source and fixtures + +The annotated `v1.0.0` tag resolves to protocol source commit +`d652fba1317aec7f25c5a464bac15e97d6094e67`. The release changes distribution +versioning, not the wire schema. + +The existing consumer fixture pin is +`42c0d249f81395f00408ec0f92638dcbbf5deb03`. This reviewed immutable fixture source +is distinct from the stable release source commit. Retain the pin until a reviewed +consumer change updates it; do not substitute a moving branch or imply the two +commits are identical. The readable GitHub shadow retains that immutable commit +for the Windows fixture bridge. + +### Publication and verification scope + +Use [Gitea](https://git.kof22.com/QRun-IO/qqq-print-protocol) for development, pull +requests, CI and releases. Protocol GitHub Actions were retired on 2026-11-04 at +01:11 UTC; the shadow remains readable. Historical workflow files, compatibility +decisions and test evidence are retained as history. Their presence is not an +active GitHub publishing path. + +Download the release archive and `SHA256SUMS` from the primary release and verify +the archive before extracting it. No npm registry publication is performed. +This documentation closeout introduces no new build, hosted attestation or +hardware-acceptance claim. Schema fixtures establish message shape; installation, +authentication deployment and physical output evidence belong to the consumer +repositories. See [authentication](QQQ-AUTHENTICATION.md), +[realtime transport](REALTIME.md), and [media selection](PRINTER-MEDIA.md). + +## Consumer checkout + The coordinated repositories are: -- [qbit-printing](https://github.com/QRun-IO/qbit-printing): QQQ 4.1+ server metadata, durable queue and HTTP endpoints. -- [qqq-print-agent](https://github.com/QRun-IO/qqq-print-agent): Windows AppKit companion, service and printer adapters. -- [qqq-print-protocol](https://github.com/QRun-IO/qqq-print-protocol): this specification and compatibility fixtures. +- [qbit-printing](https://git.kof22.com/QRun-IO/qbit-printing): QQQ 4.1+ server metadata, durable queue, native API and realtime WebSocket endpoint. +- [qqq-print-agent](https://git.kof22.com/QRun-IO/qqq-print-agent): Windows AppKit companion, service and printer adapters. +- [qqq-print-protocol](https://git.kof22.com/QRun-IO/qqq-print-protocol): this specification and compatibility fixtures. + +The [stable cohort](INTEGRATION.md#stable-printing-release) is protocol 1.0.0, Windows 1.0.1 and QBit 1.0.0, +with native printing API 2.3.0 and QQQ 4.1.0-RC.21 as its dependency baseline. For local development, clone them as siblings. The Java HTTP test defaults to `../qqq-print-protocol/fixtures` and accepts `-Dprinting.protocol.fixtures=`. The Windows tests link shared fixtures from the sibling repository. See each consumer README for its build and platform requirements. -CI must check out this repository at an immutable commit reviewed with the consumer change. A checkout path of `qqq-print-protocol` beside `qbit-printing` or `qqq-print-agent` preserves the local layout. Do not pin a moving branch for release qualification. Maintainers update the pinned commit when adopting a new compatible contract release. +CI must check out this repository at an immutable commit reviewed with the consumer change. A checkout path of `qqq-print-protocol` beside `qbit-printing` or `qqq-print-agent` preserves the local layout. Do not pin a moving branch for release qualification. The current consumer fixture pin `42c0d249f81395f00408ec0f92638dcbbf5deb03` is distinct from protocol 1.0.0 release source `d652fba1317aec7f25c5a464bac15e97d6094e67`. Maintainers update the pin through a reviewed consumer change; the readable GitHub shadow retains it for the Windows fixture bridge. If a consumer builds outside a multi-checkout workspace, download the release archive, verify `SHA256SUMS`, extract it and point its tests at `fixtures/`. Consume `schemas/protocol.schema.json#/$defs/` with a JSON Schema 2020-12 validator. @@ -18,7 +74,7 @@ The coordinated realtime client requires printing semantic extension `>=2.0.0 <3.0.0` and the authenticated `qqq-printing.v1` WebSocket subprotocol. Wire payload version remains 1. [REALTIME.md](REALTIME.md) defines the new frames, configurable policy, streaming limits and runtime acceptance expectations. -The release candidate is [0.3.0-rc.1](https://github.com/QRun-IO/qqq-print-protocol/releases/tag/v0.3.0-rc.1). +This transport is included in [stable protocol 1.0.0](INTEGRATION.md#stable-printing-release). Upgrade the server before the Windows connector; fixtures do not establish installed behavior. Historical HTTP wire protocol v1 is selected by the `/printing/v1` path and enrollment response `protocolVersion: 1`. Published distribution version `0.2.0-rc.1` identifies the specification/fixture bundle; it does not change that wire version. The Windows and QBit release numbers are independent of both. Native clients use the discovered printing extension semantic version; the realtime contract above adds its explicit version/capability gate without redefining core discovery. @@ -37,11 +93,11 @@ Claim acknowledgment means local receipt; SPOOLED means Windows accepted the doc ## Checks and artifacts ```sh -npm ci +npm ci --ignore-scripts npm run check npm run bundle ``` The check runs full draft-2020-12 schema compilation and fixture validation with Ajv, plus independent content/hash/base64 and invalid-input checks. `node tools/verify-fixtures.mjs` remains available without installing dependencies for a quick subset check. -The bundle includes specification, schema, fixtures, tools, locked validator dependencies and license metadata, excluding installed dependencies. Consumers do not need Node.js to use the schema or fixture JSON. Maintainers publish the bundle as a GitHub release asset; no npm registry publication is performed. +The bundle includes specification, schema, fixtures, tools, dependency manifests and lockfile, and license metadata, excluding installed dependencies. Consumers do not need Node.js to use the schema or fixture JSON. Maintainers publish the bundle and checksum on [Gitea releases](https://git.kof22.com/QRun-IO/qqq-print-protocol/releases); no npm registry publication is performed. Protocol GitHub Actions were retired on 2026-11-04; retained files and historical results do not imply a new hosted build or attestation. diff --git a/docs/PRINTER-MEDIA.md b/docs/PRINTER-MEDIA.md index cfd7809..e100246 100644 --- a/docs/PRINTER-MEDIA.md +++ b/docs/PRINTER-MEDIA.md @@ -1,10 +1,9 @@ # Printer media contract -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 +This additive contract is included in [protocol 1.0.0, Windows 1.0.1 and QBit 1.0.0](INTEGRATION.md#stable-printing-release). +Older 0.3.2 clients do not advertise it. Existing wire version 1 and the 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 +2.3.0 (see [VERSIONS.md](VERSIONS.md)). 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. @@ -51,7 +50,7 @@ length, initiating actor, request and destination with the durable acceptance receipt. Acceptance means a committed queue entry; it does not prove paper output. Lost responses reconcile the same request key rather than issuing a new request. -The draft native routes below are relative to the discovered printing extension +The native routes below are relative to the discovered printing extension path, behind the standard QQQ authentication and authorization layers: | Operation | Contract | diff --git a/docs/QQQ-AUTHENTICATION.md b/docs/QQQ-AUTHENTICATION.md index 06723b4..2690a1d 100644 --- a/docs/QQQ-AUTHENTICATION.md +++ b/docs/QQQ-AUTHENTICATION.md @@ -1,10 +1,11 @@ # Standard QQQ authentication -The new Windows client uses the QQQ semantic UI/UX API. Package versions, wire +The Windows client uses the QQQ semantic UI/UX API. Package versions, wire payload version `1` and the printing extension semantic version are separate -contracts. The standard-session contract was published in `0.2.0-rc.1`; realtime -transport is part of release candidate `0.3.0-rc.1`. This document does not establish an -accepted Authentik deployment. +contracts. The standard-session contract was introduced in `0.2.0-rc.1` and +realtime transport in `0.3.0-rc.1`; both are included in the [stable cohort](INTEGRATION.md#stable-printing-release). +Provider configuration and server session policy still determine the supported +sign-in and renewal behavior of each deployment. ## Discovery and sign-in @@ -36,11 +37,11 @@ Missing native grants require server configuration, not a fallback local login. The desktop callback must match the shared grant and installer registration. Windows uses the exact private callback -`io.qrun.qqq-print-agent:/oauth/callback`; current central candidate policy rejects +`io.qrun.qqq-print-agent:/oauth/callback`; the shared native grant rejects HTTP callbacks. The installer registers the callback to a non-elevated forwarding helper, which delivers it only to an active sign-in attempt in the same Windows user/session. State and PKCE validation remain mandatory. The implementation, -shared grant and provider deployment must be qualified before Authentik acceptance. +shared grant and provider configuration must agree for Authentik sign-in to work. ## User and device authority diff --git a/docs/REALTIME.md b/docs/REALTIME.md index f2106b3..52f1eed 100644 --- a/docs/REALTIME.md +++ b/docs/REALTIME.md @@ -1,6 +1,7 @@ # Realtime printing — semantic extension 2.0 -This is the contract for the `0.3.0-rc.1` realtime release candidate. +This transport was introduced in `0.3.0-rc.1` and is included in the +[stable 1.0.0 contract](INTEGRATION.md#stable-printing-release), whose paired server advertises printing 2.3.0. Contract publication does not establish installed acceptance. Existing job states, command outcomes, current-user authorization and durable idempotency rules remain authoritative. @@ -8,7 +9,7 @@ Native printing extension **2.0.0** makes an authenticated synchronized WebSocke a prerequisite for claiming jobs. Published extension 1.0 clients could claim over HTTP alone, so this changes existing behavior and requires a major version under [Semantic Versioning](https://semver.org/#spec-item-8). A coordinated upgrade -does not make that change backward compatible. Product `0.3.0-rc.1`, framework +does not make that change backward compatible. Product releases, framework `/qqq/v1`, wire payload v1 and subprotocol `qqq-printing.v1` remain independent. ## Discovery and connection diff --git a/docs/SESSION-STATE.md b/docs/SESSION-STATE.md index 253f23b..972f8c4 100644 --- a/docs/SESSION-STATE.md +++ b/docs/SESSION-STATE.md @@ -1,6 +1,28 @@ -# Session state — 2026-11-01 +# Session state — 2026-11-04 -## Release-cohort integration (branch `release/printing-cohort-20261101`) +## Current stable release + +Protocol [1.0.0](https://git.kof22.com/QRun-IO/qqq-print-protocol/releases/tag/v1.0.0) +is published on primary Gitea (release 1344), from tagged source +`d652fba1317aec7f25c5a464bac15e97d6094e67`. It pairs with Windows 1.0.1 and QBit 1.0.0, +native printing API 2.3.0, wire v1 and QQQ dependency baseline 4.1.0-RC.21. +Consumer fixtures remain pinned to `42c0d249f81395f00408ec0f92638dcbbf5deb03`, +a separate reviewed source commit. See [release details](INTEGRATION.md#stable-printing-release). + +The current transport is client-initiated authenticated two-way WebSocket with +independent streamed HTTPS documents and automatic reconnect; no polling fallback. +Protocol GitHub Actions were retired at 2026-11-04 01:11 UTC. The readable shadow +and immutable fixture commit remain for the Windows fixture bridge. + +This documentation-only closeout updates release guidance, primary links, +authentication/media wording and historical status labels. No schema, fixture, +runtime or workflow changed; no new build, hosted attestation or hardware test is +claimed. Earlier checkpoint statements below retain their original dates and +statuses and are not the current backlog. + +## Historical checkpoints + +### Release-cohort integration — 2026-11-01 (branch `release/printing-cohort-20261101`) Cohort: protocol package `1.0.0` (source prepared, not yet published; `0.4.0-rc.1` is the latest published), wire v1, native printing extension 2.3.0. This branch integrates the script-quality tooling (locked Ruff/Pyright, diff --git a/docs/TODO.md b/docs/TODO.md index b87a1fa..224aa1c 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -1,18 +1,34 @@ # TODO -## Script quality gates +## Current protocol closeout — 2026-11-04 + +- [x] Publish stable protocol 1.0.0 on primary Gitea (release 1344). +- [x] Document the Windows 1.0.1 / QBit 1.0.0 cohort, native API 2.3.0, wire v1, + current realtime/authentication/media behavior and separate immutable fixture pin. +- [x] Retire protocol GitHub Actions; retain the readable shadow and Windows fixture bridge. + +No protocol implementation or publication item remains for this stable release. +Consumer installation and hardware evidence remain in their repositories. +Documentation review and publication are coordinated by the release owner. + +## Historical task ledger + +The original checkpoint statuses below are preserved as history, not as open +tasks for the published stable release. See [current release details](INTEGRATION.md#stable-printing-release). + +### Script quality gates - [x] Pin Ruff, strict Pyright, ESLint/Stylistic and strict checkJs with locked restores; reject untracked-scope Python/JavaScript and zero-file Pyright runs; negative tool probes pass locally. - [ ] Observe the new `verify` job steps pass on hosted CI before relying on them. -## Release cohort integration (0.4.0-rc.1, unreleased) +### Release cohort integration (0.4.0-rc.1, unreleased at this checkpoint) - [x] Integrate short-label (4 × 2 / 4 × 1) test profiles, fixture and job-paper assertions with the strictly typed tools in source. - [x] Pass the merged-tree `npm run check` (76 definitions / 79 fixtures), `npm run typecheck`, `npm run lint` and `npm run bundle`. - [ ] Pin the final protocol commit in both consumers, then observe hosted Gitea CI. - [ ] Complete installed client and physical short-label acceptance separately; schema checks do not establish them. -## Echo media integration +### Echo media integration - [x] Define bounded queue-default profile and exact revision selection schemas. - [x] Validate positive fixtures and reject invalid/ambiguous options. @@ -21,7 +37,7 @@ - [ ] Qualify atomic retained-source acceptance and lost-response reconciliation. - [ ] Publish the reviewed immutable contract and compatible consumer tuple. -## Realtime 0.3.0-rc.1 release candidate +### Realtime 0.3.0-rc.1 release candidate - [x] Freeze printing extension 2.0, authenticated realtime frames and independent streamed HTTPS documents with no polling fallback. @@ -35,7 +51,7 @@ authorization acceptance before release; schema checks do not establish them. - [ ] Complete installed UI and physical output acceptance separately. -## Historical 0.2 and earlier implementation checkpoints +### Historical 0.2 and earlier implementation checkpoints The entries below retain their original checkpoint status. They do not describe the current realtime release's completion or publication. diff --git a/docs/VERSIONS.md b/docs/VERSIONS.md index 6ccf0f8..9e6c81a 100644 --- a/docs/VERSIONS.md +++ b/docs/VERSIONS.md @@ -1,9 +1,11 @@ # Extension version registry -Three version numbers are independent. Do not compare them. +Distribution, native API, wire and subprotocol versions are independent. Do not +compare them as if they were one version sequence. See the [stable cohort](INTEGRATION.md#stable-printing-release). | Number | Meaning | Current | | --- | --- | --- | +| Protocol distribution | Version of the specification and fixture archive | 1.0.0 | | 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 | @@ -18,7 +20,7 @@ additive and keeps the earlier behavior. | 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) | +| 2.3.0 | 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 @@ -36,6 +38,5 @@ additive and keeps the earlier behavior. - 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. +QBit 1.0.0 advertises native printing extension 2.3.0. Windows 1.0.1 is the paired +stable client; their product versions do not replace capability discovery.