think
16px
820px
← all files

channel_w/ — CONTRACT (Traceability, horizontal word-gap, screenshot-blind)

WIRE_SPEC §2.1a. Differential inter-word spacing; blind (no starmap), so it is the
traceability carrier a screenshot of the document can decode. Carries the same 64-bit
message as Channel V, wrapped in the RS(15,8) codeword (as Channel K) and whitened.

Public surface

  • encode(pdf_bytes, k_epoch, seq, *, delta_pt=1.4) -> (pdf, gaps_used, applied)
    Renders each page at 150 DPI, detects carrier lines + words from pixels (morphological-close
    segmenter, WIRE_SPEC §2.1a), maps each pixel gap to the space glyph sitting in it, and nudges the
    gap by delta*(sign - line_mean) via surgery.AdjustGap (signed TJ kern). Per-line nudges sum to
    ≈0 so the line stays justified. applied=False (pdf == input) when fewer than a full RS
    codeword's carrier gaps (W_MIN_CARRIER_GAPS = 120) exist.

  • decode_pdf(pdf_bytes, k_epoch, *, dpis=(150, 200)) -> int | None
    Exact/forwarded-PDF path: render internally and run the blind detector at a couple of resolutions;
    first MAC-valid hit wins. Used for the encoder self-check and for a forwarded PDF artifact.

  • decode_blind(gray_images, k_epoch) -> int | None
    Screenshot path: take grayscale page images (a capture), detect carrier lines/gaps, threshold each
    gap against the line mean, line-offset (A) search + RS-erasure decode + MAC gate. Seq or None.

Invariants

  1. Exact self-decode: decode_pdf(encode(pdf,k,s)[0], k) == s on a supported document.
  2. Blind self-decode: a clean screenshot of the encoded pages decodes back to s.
  3. Justification-preserving: per-line gap nudges sum to ≈0 (line width unchanged); edits are
    horizontal only, every glyph preserved (AdjustGap).
  4. Wrong key ⇒ None (MAC gate); pad ≠ 0 or RS failure ⇒ None.
  5. Segmentation stability: the pixel word count of a carrier line is unchanged by the channel's own
    gap edits (the morphological-close property that makes blind decode work).
  6. Capacity: applied=False below 120 carrier gaps — the orchestrator then falls back to Channel V.

Supported document class

Clean, well-separated inter-word spacing with stable segmentation: real embedded-font
business/government PDFs and monospaced/left-aligned renders. reportlab-platypus tight justification
and mixed-layout proportional docs are not supported (fragile pixel↔geometry space mapping) and
fall back to Channel V. Because the encoder keeps W only if its own render self-check passes, an
unsupported document can never ship a bad W mark.