|
| 1 | +# Packaged release adapters |
| 2 | + |
| 3 | +TASK-199 provides two bounded families for TASK-185 to call after updating from |
| 4 | +`v3`: `public-capabilities` and `native-throughput-latency`. The adapters do not |
| 5 | +import TASK-185, discover another checkout, select a fallback installation, or |
| 6 | +replace its release inventories. TASK-185 owns its final runner wiring and full |
| 7 | +release acceptance. |
| 8 | + |
| 9 | +## Python interface |
| 10 | + |
| 11 | +Import `scripts/lib/v3_release_package_adapters.py` from the extracted archive: |
| 12 | + |
| 13 | +```python |
| 14 | +run_public_capabilities(inputs, output, run_id) |
| 15 | +run_native_benchmarks(inputs, output, run_id, workload) |
| 16 | +validate_public_receipt(path, expected_identity, expected_run_id) |
| 17 | +validate_benchmark_receipt(path, expected_identity, expected_run_id, |
| 18 | + require_full_workload=False) |
| 19 | +identity(inputs, workload=None) |
| 20 | +``` |
| 21 | + |
| 22 | +`inputs` is a mapping or argparse namespace with `archive`, `archive_sha256`, |
| 23 | +`source`, `build`, `prefix`, `provider_prefix`, `tls`, `compiler`, `client_python`, |
| 24 | +`node`, and `quic_go`. Paths identify the selected archive, its unchanged |
| 25 | +extraction, out-of-source build, staged installation and provider. `tls` is |
| 26 | +`yes` or `no`. Every execution uses a caller-selected new 32-character lowercase |
| 27 | +hexadecimal run ID and a previously nonexistent output directory. Existing |
| 28 | +outputs, including failed attempts, are preserved. |
| 29 | + |
| 30 | +The supported clients are hyper-h2 4.4.1, aioquic 1.3.0, Node 24.15.0, and the |
| 31 | +quic-go v0.55.0 public client built from the distributed Go sources. The compiler |
| 32 | +must support C++20. TLS-on requires the explicitly selected OpenSSL 3.5 LTS |
| 33 | +provider. Public TLS ACME tests bind authentic TCP port 443; use the established |
| 34 | +isolated network namespace on hosts that cannot provide that port. Altering the |
| 35 | +port or trusting injected local-port metadata is not an alternative witness. |
| 36 | + |
| 37 | +## CLI and independent validation |
| 38 | + |
| 39 | +```sh |
| 40 | +CLIENT_PYTHON scripts/run-v3-packaged-adapters.py \ |
| 41 | + --family public-capabilities \ |
| 42 | + --archive ARCHIVE --archive-sha256 EXPECTED_SHA256 \ |
| 43 | + --source EXTRACTED_SOURCE --build BUILD --prefix PREFIX \ |
| 44 | + --provider-prefix PROVIDER --tls yes \ |
| 45 | + --compiler COMPILER --client-python CLIENT_PYTHON \ |
| 46 | + --node NODE --quic-go QUIC_GO --run-id RUN_ID --output NEW_OUTPUT |
| 47 | +``` |
| 48 | + |
| 49 | +Repeat with a distinct installation/build/output for TLS-off. Each public lane |
| 50 | +contains four shared/static × managed/external cells for H1, RFC6455, TLS, H2 |
| 51 | +and H3. Encrypted protocols have typed pre-bind rejection witnesses in TLS-off. |
| 52 | +Supported credentials-backed TLS, H2 and explicit UDP H3 configurations bind |
| 53 | +and complete independent protocol exchanges in TLS-on; missing credentials, |
| 54 | +invalid configuration and mixed rollback remain separate negative cases. |
| 55 | + |
| 56 | +Select `--family native-throughput-latency` for benchmarking. Defaults remain |
| 57 | +4096 measured requests, 256 warmup requests (protocol epochs may increase |
| 58 | +warmup), 1024-byte payloads, four workers, H1/H2 concurrency eight, H3 concurrency |
| 59 | +four, and a 300-second client deadline. `--requests 16 --warmup 4` is reduced |
| 60 | +integration evidence. It cannot satisfy `--require-full-workload`. |
| 61 | + |
| 62 | +To validate in a new process, use the same selected inputs, workload and run ID |
| 63 | +with `--validate NEW_OUTPUT/receipt.json`. Validation rehashes the archive, |
| 64 | +extraction, build, installation, provider, tools and Python client modules. It |
| 65 | +reads evidence without modifying it. For full benchmark release proof add |
| 66 | +`--require-full-workload`; TASK-185 must also apply its existing release gates. |
| 67 | + |
| 68 | +## Receipt schema and retained artifacts |
| 69 | + |
| 70 | +The outer JSON receipt has `schema_version=1`, `family`, `status`, `run_id`, |
| 71 | +`identity`, `inventory`, `inventory_sha256`, `children`, `full_workload`, |
| 72 | +`artifact_roots`, `artifact_extras`, `artifacts` and `nonlocal_checks`. Failed |
| 73 | +attempts retain `status=failed` and `error` and cannot pass validation. |
| 74 | + |
| 75 | +`identity` binds the archive digest and every regular distributed source member, |
| 76 | +source/build/install paths, installed header/library/pkg-config hashes, |
| 77 | +configuration hashes, provider files, executable hashes, pinned client versions |
| 78 | +and module hashes, and workload. Archive paths must be safe, consistent, |
| 79 | +unique and regular files/directories; symlink/hardlink members are rejected. |
| 80 | +A genuine extraction needs no `.git` directory. |
| 81 | + |
| 82 | +`children` maps the exact family members to receipt artifact records. Every |
| 83 | +artifact record contains absolute `path`, `bytes` and `sha256`. The complete |
| 84 | +catalog covers child receipts, command outputs, process receipts, copied |
| 85 | +consumers/fixtures/client code, objects, depfiles, link maps, executable files |
| 86 | +and benchmark raw samples. Compilation must use installed public headers, |
| 87 | +C++20, and archive-distributed copied sources. Private headers, source/build |
| 88 | +includes and `HTTPSERVER_COMPILATION` cannot supply public proof. Every cell must retain its family's compile and dependency records, including |
| 89 | +H1 WebSocket, TLS profile/rotation, and H2/H3 example consumers where applicable. |
| 90 | +Static link maps must show contributing members from the selected installed |
| 91 | +archive and no foreign libhttpserver archive contribution; an unused LOAD entry |
| 92 | +cannot supply proof. Shared runtime inspection must resolve the selected |
| 93 | +installation. The first readiness line must contain at least one valid bound |
| 94 | +port. Readiness alone cannot |
| 95 | +supply response proof. Child inventories and decoded lifecycle/semantic |
| 96 | +observations remain subject to their original validators. |
| 97 | + |
| 98 | +H1 validation requires exact HTTP/1.0 or HTTP/1.1 response prefixes and exactly |
| 99 | +two recorded persistent and pipelined responses. WebSocket peer-close evidence |
| 100 | +records actual pending receive entry, completion with the public |
| 101 | +`connection_closed` outcome, and handler retirement before server stop. The |
| 102 | +legacy `cancelled_receive` count represents this observed transport termination; |
| 103 | +it does not assert an `outcome_code::cancelled` result. TLS profile rows retain |
| 104 | +and validate positive and negative authentication, handler deltas, decoded |
| 105 | +responses, callback cancellation/retirement, SNI generations, session rotation, |
| 106 | +and applicable ACME observations independently of their scenario names. |
| 107 | + |
| 108 | +TLS authentication rejection controls retain the independent provider client's |
| 109 | +exit 2 only with a decoded `connected=false` handshake and the exact bounded |
| 110 | +client argument shape. The explicit peer-close cancellation control retains its |
| 111 | +intentional killed-client terminal. These controls cannot supply a successful |
| 112 | +protocol exchange; positive clients and server cleanup must exit zero. |
| 113 | + |
| 114 | +Keep the archive, extraction, builds, installs, provider, clients, output roots |
| 115 | +and recorded external consumer directories available for revalidation. Catalog |
| 116 | +pruning, deleted provenance, changed process output, altered samples/statistics, |
| 117 | +reused run IDs and different expected package/archive identities fail. Do not |
| 118 | +copy historical receipts into a new execution. Nonlocal BSD/macOS/Windows |
| 119 | +checks are explicitly unexecuted locally and belong to CI and the v3 PR. |
| 120 | + |
| 121 | +## Contract checks |
| 122 | + |
| 123 | +```sh |
| 124 | +python3 scripts/test-v3-packaged-adapters.py |
| 125 | +python3 scripts/test-v3-installed-consumer.py |
| 126 | +python3 scripts/test-v3-public-http2.py |
| 127 | +python3 scripts/test-v3-public-http3.py |
| 128 | +python3 scripts/test-v3-native-benchmark.py |
| 129 | +``` |
| 130 | + |
| 131 | +These dependency-free tests use temporary real artifacts and deterministic |
| 132 | +failure injection. Synthetic parsing fixtures are not live integration proof. |
| 133 | +Ordinary `make check` runs contracts, never the live network matrix or full |
| 134 | +benchmark. Fresh execution identities and outcomes are recorded separately in |
| 135 | +TASK-199 evidence, preserving historical TASK-179 classifications. |
0 commit comments