Viewing is open to everyone. Downloading and starring need a GitHub sign-in.
Sign in with GitHub
IMPLEMENTATION-STATUS.md
v0.1.0-build.85
Latest
Commit ede38f5
Sign in with GitHub to download. Each download is recorded with your GitHub username.
| 1 | # Implementation status against the Rendering, SDK, Distribution & Telemetry Specification |
| 2 | |
| 3 | This document maps each section of [the specification](SPECIFICATION-rendering-sdk-distribution-telemetry.md) to the repository as of `0.1.0-build.83`, the first published release (`v0.1.0-build.83` on `Stable-Release`). |
| 4 | |
| 5 | **Status key:** |
| 6 | |
| 7 | - **Done:** exists and is tested in this repository's CI. |
| 8 | - **Done, CI-verified only:** written, but the toolchain is not available in the development container, so it is verified only by its GitHub Actions workflow. |
| 9 | - **Partial:** some of it exists. |
| 10 | - **Open:** needs a decision, hardware or data that the repository cannot supply. |
| 11 | |
| 12 | No real-device, real-print or platform claim is made unless it was measured. |
| 13 | |
| 14 | ## Rendering (spec §2–§3) |
| 15 | |
| 16 | | Item | Status | Where / notes | |
| 17 | |---|---|---| |
| 18 | | Canonical mathematical geometry (§2.1) | **Done** | `ckey_scalable_geometry` returns primitives in canonical units, in painter's order. The raster, PDF and SVG backends draw these. SVG agrees with the raster to within 0.01% of pixels (`ckey_native_render`). | |
| 19 | | Exclusions, safe gaps, no dead regions, fixed ray widths (§2.1, §11.3) | **Done** | `tests/layout_tests.cpp`, `tests/scalable_tests.cpp`. | |
| 20 | | Separate encoding / geometry / backends / scan (§2.1) | **Done** | `ckey_codec`, `ckey_scan` (needs only the codec), `ckey_render`, `ckey_certify` and `ckey_telemetry`. CI links a scan-only test against `ckey_scan` alone. See `src/README.md`. | |
| 21 | | Headless raster without an SVG interpreter (§2.2, §11.4) | **Done** | `ckey_render_scalable_raster`. The print path rasterizes the geometry directly, and the core no longer includes the SVG parser. | |
| 22 | | Raster policies: binary / coverage / hybrid (§2.2) | **Done** (policies); **Partial** (choice) | All three are implemented and decode. Which one is best per device is a benchmark question (§12), left open. | |
| 23 | | Native RGBA / gray buffers (§2.5) | **Done** | RGBA8 with straight alpha, and GRAY8. | |
| 24 | | PNG export (§2.5) | **Done** | `ckey_encode_png`: DEFLATE in the core, RGBA8, GRAY8 and 1-bit, with pHYs. | |
| 25 | | SVG export (§2.3) | **Done** | All profiles. | |
| 26 | | PDF vector export (§2.3–§2.4) | **Done** | `ckey_render_scalable_pdf`: exact paths, flat colours, optional transparency. | |
| 27 | | `.ckey` interchange (§2.5) | **Done** (draft v1) | `spec/CKey-Interchange-v1.md`. A strict reader, fuzzed. | |
| 28 | | Transparent output, alpha 0 where unpainted (§2) | **Done** | `transparent = 1` in raster and PDF. | |
| 29 | | Print backend: physical size, minimum features, compensation (§2.4) | **Partial** | Device-grid bitmaps, the Profile 0.1 print layout, PDF and a calibration sheet all exist. **Open:** measured printer/media profiles, which need real prints. | |
| 30 | | Web canvas / WASM (§3) | **Done, CI-verified only** | `sdk/web` (npm `openckey`). Its JS and native bridge tests run here; the wasm build runs in `sdk-web.yml`. | |
| 31 | | Swift package / `CKeyView` (§3) | **Done, CI-verified only** | `Package.swift`, `sdk/swift`. Its C++ shims are verified here. | |
| 32 | | Android (§3) | **Done, CI-verified only** | `sdk/android`. Its JNI bridge is verified on the JVM here. | |
| 33 | | .NET (§3) | **Done, CI-verified only** | `sdk/dotnet`. Its native library and struct layouts are verified here. | |
| 34 | |
| 35 | ## Styling and optical safety (spec §4) |
| 36 | |
| 37 | | Item | Status | Where / notes | |
| 38 | |---|---|---| |
| 39 | | Colours, textures, images, materials (§4) | **Done** | `ckey_style`, with natively rendered materials and caller-supplied logo pixels. | |
| 40 | | Default black on white (§4) | **Done** | Since build 61. The concept look is `CKEY_PRESET_CONCEPT`. | |
| 41 | | Transparent mode needs the host background to certify (§4, §11.5) | **Done** | `ckey_backdrop`. With no backdrop the answer is "background unknown" and the style is never certified. | |
| 42 | | Certification tied to a capture model, not contrast alone (§4) | **Done** | `ckey_certify_scalable_style` renders, composites, degrades and decodes with the real decoder. | |
| 43 | | Policy modes strict / adaptive / override (§4) | **Done** | `ckey_style.policy` (ABI 4), with changes reported as `CKEY_ADJUST_*`. | |
| 44 | |
| 45 | ## Research harness (spec §5) |
| 46 | |
| 47 | | Item | Status | Where / notes | |
| 48 | |---|---|---| |
| 49 | | Generate → degrade → decode → measure | **Done** | `ckey-bench`. | |
| 50 | | Recovery, bit errors, physical size, payload per area | **Done** (synthetic) | `docs/benchmarks/`. | |
| 51 | | False positives, latency percentiles | **Done** (synthetic) | p50, p90 and p99. | |
| 52 | | Comparison with QR and Data Matrix | **Done, CI-verified only** | Through zxing-cpp in the CI `benchmarks` job. | |
| 53 | | The six research directions (§5.1–5.6) | **Partial** | 1 is done. 2 is partly done, via Profile 0.1. 4 is simulated only. 3, 5 and 6 are open research. The harness exists to evaluate them. | |
| 54 | |
| 55 | ## Scanner (spec §6) |
| 56 | |
| 57 | | Item | Status | Where / notes | |
| 58 | |---|---|---| |
| 59 | | Detection separate from decode | **Done** | `ckey_find_borders_gray8` → `ckey_refine_quad_gray8` → `ckey_decode_*_gray8`. | |
| 60 | | Offline; no telemetry or server needed | **Done** | `ckey_scan` has no network code and does not depend on telemetry. | |
| 61 | | Continuous frames, result on first decode | **Done** | iOS reader, and the scanner helpers in every SDK. | |
| 62 | | Optional ML recognition | **Partial** | Only a logistic candidate ranker. | |
| 63 | | Latency target by device, size, profile and percentile | **Open** | The harness reports percentiles. A device target needs real hardware. | |
| 64 | | Conformance vectors | **Done** | `tests/vectors/conformance-v1.json`, checked in CTest and consumable by SDKs. | |
| 65 | | Security review surface | **Partial** | Every parser is bounded: `.ckey`, the telemetry import, the service's JSON. The `.ckey` reader is fuzzed. No external review yet. | |
| 66 | |
| 67 | ## Packaging and governance (spec §7–§8) |
| 68 | |
| 69 | | Item | Status | Where / notes | |
| 70 | |---|---|---| |
| 71 | | SPM / AAR / npm / NuGet / CMake package / Homebrew (§7) | **Done** (manifests and CI); **Open** (publishing) | Publishing needs the maintainer's registry accounts. | |
| 72 | | Signed, checksummed artifacts from tagged commits (§7) | **Done** | `release.yml`: the tag must match `VERSION` and be on `Stable-Release`. It produces `SHA256SUMS`, Sigstore provenance and a draft release. | |
| 73 | | Branch model and community isolation (§8) | **Done** | `docs/BRANCHES-AND-RELEASES.md`, `community.yml` (no secrets). Branch protection is set in GitHub's settings by the maintainer. | |
| 74 | | Immutable tags, deprecation titles (§8.1–8.2) | **Done** (tooling) | `deprecate-release.yml`, `docs/support-matrix.json`. First published release: `v0.1.0-build.83`. | |
| 75 | | Version counter preserves history (§8.1) | **Done** | `0.1.0-build.N`, tags `v0.1.0-build.N`. | |
| 76 | |
| 77 | ## Telemetry (spec §9) |
| 78 | |
| 79 | | Item | Status | Where / notes | |
| 80 | |---|---|---| |
| 81 | | Modes 0 / 1 / 2; invalid values rejected | **Done** | `include/ckey/telemetry.h`, and every SDK. | |
| 82 | | Local aggregate counters, no identifiers | **Done** | `docs/adoption-and-telemetry.md`. | |
| 83 | | Session definition, batching, cadence, switching semantics | **Done** | Same document. | |
| 84 | | Ingestion service with abuse controls, no IP retention | **Done** (code); **Open** (deployment) | Runs on openckey.org, which is a separate, proprietary site, not part of this repository. It must meet the service obligations in `docs/adoption-and-telemetry.md`. | |
| 85 | | Scanner builds without telemetry | **Done** | `-DCKEY_BUILD_TELEMETRY=OFF`, the SwiftPM `CKeyScanner` product, the Android core module, and `CKEY_DOTNET_TELEMETRY=OFF`. | |
| 86 | |
| 87 | ## Acceptance criteria (spec §11) |
| 88 | |
| 89 | | # | Status | Notes | |
| 90 | |---|---|---| |
| 91 | | 1 Deterministic geometry across targets | **Done** | The conformance geometry hash is identical under gcc -O0/-O2 and clang with fast-math. SDKs run the same vectors. | |
| 92 | | 2 Deterministic raster | **Done** | Same size, style and policy give identical bytes on one platform. Across platforms, pixels are checked by decoding. | |
| 93 | | 3 Exclusion, gap and ray-width invariants | **Done** | | |
| 94 | | 4 Headless without an SVG interpreter | **Done** | | |
| 95 | | 5 Transparent compositing, no false certification | **Done** | | |
| 96 | | 6 Scanability checks tied to a modelled acquisition | **Done** (model); **Open** (real cameras) | | |
| 97 | | 7 Native pixels in web, Swift, Android and .NET | **Done, CI-verified only** | | |
| 98 | | 8 Scanner independent of renderer and telemetry | **Done** | | |
| 99 | | 9 Native package ecosystems; releases from trusted commits | **Done** (tooling); **Open** (publishing) | | |
| 100 | | 10 Immutable tags, deprecation metadata | **Done** (tooling) | | |
| 101 | | 11 Telemetry modes identical across SDKs | **Done, CI-verified only** | Every SDK wraps the same C core. | |
| 102 | | 12 No payloads or identifiers transmitted | **Done** | Schema-enforced on both the client and the server. | |
| 103 | | 13 Telemetry does not slow decoding; adoption labelled accurately | **Done** | Recording is a few counter updates, sending is asynchronous, and the summary is labelled "not total usage". | |
| 104 | |
| 105 | ## What only the maintainer can do |
| 106 | |
| 107 | - Deploy openckey.org (separate repository), which hosts telemetry ingestion, short destinations, the renderer and package downloads. |
| 108 | - Create the registry accounts (npm, Maven Central `org.openckey`, NuGet, a Homebrew tap) and publish from tagged releases. |
| 109 | - Protect `Stable-Release` and the tags in GitHub, and create `community`. |
| 110 | - Make real prints and real-camera captures. These are the evidence for print compensation, latency targets, and any comparison with QR. |
| 111 | - Apply the repository settings in `docs/REPOSITORY-SETTINGS.md` (branch and tag protection, private vulnerability reporting). |