Polish PrismShare naming, attribution, and conformance

.github/workflows/spec.yml

@@ -0,0 +1,19 @@
+name: Specification
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Validate documents and vectors
+        run: python tools/check_spec.py

APHOTIC.md

@@ -1,19 +1,31 @@
-# Aphotic
+# Aphotic Transfer
 
-Aphotic carries a file across a sequence of [Prism Code](FORMAT.md) symbols. A
+**Aphotic Transfer** is PrismShare's exact-file payload protocol. Shortened to
+**Aphotic** after first use, it carries a file across a sequence of
+[PrismShare Code](FORMAT.md) symbols. A
 sender displays a file as an endless loop of symbols and a reader recovers it by
 watching; the link is one way, and Aphotic is what makes a one-way, lossy,
 camera-to-screen channel deliver an exact file anyway.
 
 It is a payload protocol: every page rides inside a Prism symbol's payload and
 Aphotic changes nothing about the symbol format.
 
-**Status: implemented and in daily use at one bit per channel.** The wire format
-below is what the reference sender emits and the reference reader accepts.
+> **Document status**
+>
+> | field | value |
+> |---|---|
+> | role | normative exact-object payload protocol |
+> | wire discriminator | `PS` (`0x50 0x53`) |
+> | current revision | Aphotic Transfer version 1, identified by its fixed header and allocations |
+> | repair modes | none, fixed parity, and Aphotic Fountain (`0xFF`) |
+> | evidence | implemented and proven through real cameras at one bit per channel |
+
+The wire format below is what the reference sender emits and the reference
+reader accepts.
 
 ---
 
-## 1. What Aphotic is, and what it relies on
+## 1. What Aphotic Transfer is, and what it relies on
 
 A file is split into fixed-size **chunks**. Each chunk, wrapped in a 13-byte
 **page header**, is one **page**, and one page is the payload of one symbol. The
@@ -22,8 +34,8 @@ camera happens to catch, fills each chunk into its place, and has the file once
 every chunk is in hand.
 
 Aphotic delivers one exact object, eventually, taking as many laps as the losses
-demand. That is the opposite of [Prism Stream](STREAM.md), which delivers a live
-stream in real time and conceals what it cannot recover in time. A reader tells
+demand. That is the opposite of [PrismShare Stream](STREAM.md), which delivers
+a live stream in real time and conceals what it cannot recover in time. A reader tells
 the two apart, and both apart from a plain document, by the first two payload
 bytes: `PS` for an Aphotic page, `PV` for a stream frame, neither for a document.
 
@@ -147,7 +159,7 @@ transfer, which nothing downstream would catch.
 > assembled file has no checksum. The bound is normative for exactly that
 > reason.
 
-## 5. Rateless repair (the fountain)
+## 5. Aphotic Fountain rateless repair
 
 Marked by a repair-mode byte of `0xFF`, which the fixed scheme can never emit, so
 the byte disambiguates the two on the receive side.
@@ -333,7 +345,7 @@ does not run past the payload; and the name contains no control character and no
 That sequencing, loss handling and file identity are payload concerns that must
 live outside the optical symbol format, in a document of their own, was argued in
 a format review by **NomNomski**. This specification, and the
-[Prism Stream](STREAM.md) protocol beside it, are that argument carried out.
+[PrismShare Stream](STREAM.md) protocol beside it, are that argument carried out.
 
 ## License
 

BIT-LOADING.md

@@ -1,4 +1,14 @@
-# Per-channel bit loading, a proposal for format version 3
+# PrismShare Code per-channel bit loading
+
+> **Document status**
+>
+> | field | value |
+> |---|---|
+> | role | experimental format-version-3 extension |
+> | stable conformance target | no |
+> | implementation | profiles defined; profile 1 implemented |
+> | camera result | profile 1 falsified; remaining profiles unproven |
+> | wire authority | `FORMAT.md` section 4 controls where the texts overlap |
 
 Status: implemented in the reference codec, and **the premise did not survive
 hardware**. Read the last section before building on any of this. Format

BRANDING.md

@@ -0,0 +1,96 @@
+# PrismShare naming and brand architecture
+
+> **Document status**
+>
+> | field | value |
+> |---|---|
+> | role | editorial naming authority |
+> | wire effect | none |
+> | suite | PrismShare Protocol Suite |
+> | updated | 2026-08-12 |
+
+Names should make the system memorable without making the protocol obscure.
+Every coined name therefore has a stable descriptive expansion.
+
+## 1. The hierarchy
+
+| name | kind | meaning | preferred first use |
+|---|---|---|---|
+| **PrismShare** | product and project | The applications and complete technology family. | “PrismShare, a one-way camera-to-screen sharing system” |
+| **PrismShare Protocol Suite** | standard | The documents and vectors in this repository. | Use in repository, specification and conformance titles. |
+| **PrismShare Code** | optical format | The colour 2D barcode defined by `FORMAT.md`. | “a PrismShare Code (PS Code) symbol” |
+| **Aphotic Transfer** | payload protocol | Eventual, exact file delivery over `PS` pages. | “Aphotic Transfer, PrismShare's exact-file protocol” |
+| **Aphotic Fountain** | repair mechanism | The deterministic rateless fountain inside Aphotic repair mode `0xFF`. | “the Aphotic Fountain rateless repair mechanism” |
+| **PrismShare Stream** | payload protocol | Bounded-latency live delivery over `PV` frames. | “PrismShare Stream, the live redundancy protocol” |
+| **Twin Window** | presentation technique | The informative two-symbol Stream layout carrying non-overlapping recent and older windows. | “the Twin Window two-symbol presentation” |
+
+## 2. Short forms
+
+After the first descriptive use in one document or screen:
+
+- “PrismShare Code” may become “PS Code” or “the symbol.” Do not shorten it to
+  “Prism Code”; the bare “Prism” form is deliberately avoided.
+- “Aphotic Transfer” may become “Aphotic” or “the transfer.”
+- “Aphotic Fountain” may become “the fountain.”
+- “PrismShare Stream” may become “Stream” when it cannot be confused with a
+  generic byte stream.
+- “Twin Window” retains both words; “twin” alone is not a protocol term.
+
+Source identifiers such as `Fountain`, `Transfer` and `VoiceStream`, and the
+wire magics `PS` and `PV`, are compatibility artefacts. Editorial naming does
+not require changing them. In prose, **PS Code** always means the optical
+symbol; the wire value `PS` remains the Aphotic page magic and must not be
+inferred from the abbreviation.
+
+## 3. Names not used as the umbrella
+
+- **Prism** alone is too crowded and too weakly searchable to be the product
+  identity.
+- **Prism-spec** is a repository slug, not a user-facing name.
+- **PrismAphotic** obscures the useful distinction between product and protocol;
+  use “PrismShare Aphotic Transfer” when the umbrella must be explicit.
+- **Aphotic Fountain** names the repair mechanism, not the complete application
+  or the optical symbol.
+- **Prism Stream** should be avoided in first-use prose because unrelated
+  streaming products use similar wording. Use “PrismShare Stream.”
+
+## 4. Naming new mechanisms
+
+A new coined name belongs in the suite only when it identifies a stable,
+architecturally meaningful mechanism. It must:
+
+1. have a plain technical expansion;
+2. name one thing at one layer;
+3. avoid changing an existing wire meaning;
+4. be added here and to `GLOSSARY.md` in the same change; and
+5. survive a basic collision search before publication.
+
+Ordinary fields, constants and implementation tactics should remain descriptive.
+The standard gains authority from precision; not every clever implementation
+detail needs a brand.
+
+## 5. Repository and package naming
+
+Canonical and compatibility names:
+
+| surface | preferred value |
+|---|---|
+| specification repository | `Mashr-Systems/prismshare-spec` |
+| application repository | `prismshare` |
+| specification title | `PrismShare Protocol Suite` |
+| app-store title | `PrismShare` plus a descriptive subtitle |
+| command | `prism` may remain as a concise compatibility command |
+
+The specification repository moved from
+`Blue-Heeler-Software/prism-spec` to `Mashr-Systems/prismshare-spec` on
+2026-08-11. GitHub preserves the former address as a redirect. Package, signing
+identity and app-store changes remain separate release operations.
+
+## 6. Clearance note
+
+This document is not a trade-mark opinion. “Prism” is crowded, and an unrelated
+public GitHub repository already uses the exact string `PrismShare`. Ordinary
+web and repository searches found no obvious use of “Aphotic Fountain” at the
+time of writing, but absence from those searches is not legal clearance.
+Professional searches should cover the intended jurisdictions and relevant
+software, telecommunications and data-transfer classes before commercial use.

CHANGELOG.md

@@ -0,0 +1,55 @@
+# PrismShare Protocol Suite changelog
+
+Normative corrections are listed separately from editorial work so an
+implementer can tell whether accepted bytes changed.
+
+## Unreleased
+
+### Editorial and conformance infrastructure
+
+- Establish **PrismShare** as the umbrella product and project name.
+- Name the suite **PrismShare Protocol Suite**, the optical format
+  **PrismShare Code** with **PS Code** as its short form, the file protocol
+  **Aphotic Transfer**, its rateless
+  mechanism **Aphotic Fountain**, and the two-window presentation **Twin
+  Window**.
+- Replace the ambiguous document-family introduction with an explicit layer
+  table and payload-dispatch table.
+- Add naming, glossary, versioning, conformance, validation, security and worked
+  example companions.
+- Seed machine-readable Aphotic and Stream vectors and document the remaining
+  full-symbol vector work.
+- Remove the unnamed `margin = 6` geometry from the conformance surface while
+  retaining it as an explicitly experimental reader compatibility case.
+
+### Normative wire changes
+
+- None. Names and companion documents do not change any wire byte.
+
+### Normative clarifications
+
+- Define the structural checks possible before ignoring a Stream frame whose
+  codec id is unknown and therefore has no known packet size.
+
+## 2026-08-08
+
+### Normative corrections
+
+- Require exact Aphotic page-count consistency.
+- Require old Twin Window frames to clear Stream hint flags.
+- Record strict unknown version/codec handling and Codec2 padding rules.
+
+### Evidence
+
+- Record PrismShare Stream results through real cameras and the measured link
+  behaviours that define the reference receiver.
+
+## 2026-08-06
+
+- Publish Aphotic Transfer and PrismShare Stream as payload protocols separate
+  from the optical format.
+- Credit the independent review that drove the separation.
+
+## 2026-08-06 (initial publication)
+
+- Publish the initial optical format and informative reference decoder.

CONFORMANCE.md

@@ -0,0 +1,80 @@
+# PrismShare conformance
+
+> **Document status:** normative conformance policy. It does not add wire
+> fields or alter the protocol documents.
+
+Conformance is claimed per component and configuration. “PrismShare compatible”
+without a component, version and tested configuration is not a complete claim.
+
+## 1. Claimable components
+
+| component | normative authority | minimum claim |
+|---|---|---|
+| PrismShare Code encoder | `FORMAT.md` | format version, loading/profile, QR version range, correction levels and layouts emitted |
+| PrismShare Code decoder | `FORMAT.md` | format versions, loading profiles, QR version range and layouts accepted |
+| Aphotic sender | `APHOTIC.md` | fixed repair modes and/or Aphotic Fountain mode supported, plus maximum payload and page count |
+| Aphotic receiver | `APHOTIC.md` | accepted repair modes, resource limits and envelope handling |
+| Stream sender | `STREAM.md` | profile version, codec ids, maximum packet count and flag behaviour |
+| Stream receiver | `STREAM.md` | profile version, codec ids and invalid-frame dispositions |
+
+An implementation MAY claim any subset. It MUST NOT imply support for a layer or
+configuration it has not tested.
+
+## 2. Conformance classes
+
+### Optical Core
+
+A conforming optical encoder emits the bytes, planes, geometry, calibration and
+intensities required by `FORMAT.md`. A conforming optical decoder recovers the
+normative payload from every positive vector in its claimed configuration and
+rejects every corresponding negative vector.
+
+### Aphotic Transfer
+
+A conforming sender emits internally consistent headers, an exact systematic
+pass and repair pages for its claimed modes. A conforming receiver reconstructs
+the exact transfer payload from positive vectors and rejects malformed or
+shape-changing pages as required by `VALIDATION.md`.
+
+### PrismShare Stream
+
+A conforming sender emits complete version 1 frames with one to 200 valid codec
+packets. A conforming receiver accepts supported frames, ignores unsupported
+codec frames, rejects malformed frames and applies wrap/session rules without
+mixing incompatible state.
+
+## 3. Proof levels
+
+Conformance and physical usefulness are separate statements:
+
+| proof level | evidence |
+|---|---|
+| wire-conformant | Passes every applicable canonical positive and negative vector. |
+| software-interoperable | Exchanges data with an independent implementation without sharing encoder internals. |
+| camera-proven | Passes through a stated physical camera/display rig. |
+| channel-proven | Survives a stated channel such as a video transcode, with the full configuration and result recorded. |
+
+“Camera-proven” MUST identify the format configuration and device class. It MUST
+NOT be generalized to untested bit depths, versions, layouts or codecs.
+
+## 4. Present matrix
+
+| component | wire implementation | independent implementation | camera evidence | canonical vectors |
+|---|---:|---:|---:|---:|
+| Code v2, one bit/channel | yes | partial JavaScript encoder | yes | pending full symbol set |
+| Code v2, two or three bits/channel | yes | partial | no | pending |
+| Code v3 profile 1 | yes | no | falsified | pending |
+| Aphotic fixed parity | yes | yes | yes | scaffolded |
+| Aphotic Fountain | yes | yes | yes | seeded |
+| Stream v1 AMR | yes | no | yes | seeded |
+| Stream v1 Codec2 1300 | yes | no | yes | seeded |
+| Stream v1 Codec2 700C | yes | no | limited | seeded |
+
+This table describes current evidence, not permanent protocol capability.
+
+## 5. Vector rule
+
+Files under `vectors/` are canonical only when their manifest entry has
+`"status": "canonical"`. A scaffold or draft vector MUST NOT support a
+conformance claim. Every canonical entry requires an origin description,
+expected disposition and SHA-256 digest in `vectors/manifest.json`.

DECODER.md

@@ -1,8 +1,17 @@
-# Prism reference decoder
+# PrismShare Code reference decoder
 
-**Status: informative.** Nothing in this document is required for conformance.
+> **Document status**
+>
+> | field | value |
+> |---|---|
+> | role | informative reference decoder |
+> | conformance authority | `FORMAT.md`, not this document |
+> | measured target | format version 2 at one bit per channel |
+> | wire effect | none |
 
-A Prism Code is defined by the bytes and colours in the symbol, which is
+Nothing in this document is required for conformance.
+
+A PS Code is defined by the bytes and colours in the symbol, which is
 [FORMAT.md](FORMAT.md)'s job. How a reader recovers them is a quality-of-
 implementation question, and pinning one algorithm as normative would freeze
 today's calibration research into a permanent standard and forbid a better
@@ -191,7 +200,7 @@ means the capture cannot carry even `b = 1` reliably, which in practice means th
 symbol is too small in frame, too blurred or too dark.
 
 This measures the channel, not the symbol being read, so a reader can be pointed
-at any Prism Code and answer "how many bits per module will this setup carry".
+at any PS Code and answer "how many bits per module will this setup carry".
 The number is tuned to under-promise: across the simulated capture sweep it never
 claims a depth that then fails to decode, and it frequently claims one less than
 what works.