golded-ftn-tools 1.0.1__tar.gz

golded_ftn_tools-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  checks:
+    strategy:
+      matrix:
+        # Windows is unsupported for now. JAM read --revision reports an
+        # invalid base, and a closed stdout pipe exits 120.
+        os:
+          - ubuntu-latest
+          - macos-latest
+          # - windows-latest
+        python: ['3.12', '3.14']
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+        working-directory: golded-ftn-tools
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          path: golded-ftn-tools
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          repository: golded-dev/golded-ftn-python
+          path: golded-ftn-python
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          repository: golded-dev/golded-ftn-msg-python
+          path: golded-ftn-msg-python
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          repository: golded-dev/golded-ftn-jam-python
+          path: golded-ftn-jam-python
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          repository: golded-dev/golded-ftn-squish-python
+          path: golded-ftn-squish-python
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          repository: golded-dev/golded-ftn-hudson-python
+          path: golded-ftn-hudson-python
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+      - run: uv sync --locked --python ${{ matrix.python }}
+      - run: uv run ruff check . && uv run ruff format --check . && uv run mypy
+      - run: uv run pytest -q
+      - run: uv build && uv run twine check dist/* && uv run python scripts/verify_distribution.py

golded_ftn_tools-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Reviewed GitHub release tag
+        required: true
+        default: v1.0.1
+        type: string
+permissions:
+  contents: read
+concurrency:
+  group: pypi-${{ inputs.tag }}
+  cancel-in-progress: false
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download reviewed release archives
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          gh release download "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --pattern RELEASE-SHA256.txt
+          gh release download "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --pattern '*.whl' --pattern '*.tar.gz' --dir dist
+          sha256sum --check RELEASE-SHA256.txt
+      - name: Publish to PyPI with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

golded_ftn_tools-1.0.1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/

golded_ftn_tools-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GoldED.dev contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

golded_ftn_tools-1.0.1/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: golded-ftn-tools
+Version: 1.0.1
+Summary: FTN message bases and text filters from the command line
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: golded-ftn-hudson<2,>=1.2.0
+Requires-Dist: golded-ftn-jam<2,>=1.2.0
+Requires-Dist: golded-ftn-msg<2,>=1.3.0
+Requires-Dist: golded-ftn-squish<2,>=1.2.0
+Requires-Dist: golded-ftn<2,>=1.2.1
+Description-Content-Type: text/markdown
+
+# FTNT💥
+
+Six command-line tools for FTN message bases, JSON fixtures and text pipes.
+Python 3.12+. MIT licensed.
+
+**Status: implemented locally, not released.** Development uses five sibling
+Python repositories. Opus writing requires the local `golded-ftn-msg` 1.3.0
+extension; a public installation must wait for that dependency release.
+
+```sh
+uv sync --locked
+uv run ftnt create ./fixtures/general --format jam
+uv run ftnt write ./fixtures/general --format jam < examples/message.json
+uv run ftnt export ./fixtures/general --format jam |
+  jq -c 'select(.message.subject | contains("fixture"))'
+```
+
+`create`, `write`, `read` and `export` use an explicit `--format`:
+`msg` (FTSC), `opus`, `jam`, `squish` or `hudson`. Hudson write/read requires
+`--board 1..200`. Bases must be offline: close GoldED and other users first.
+The format packages own validation, encoding, locks and rollback.
+
+`write` accepts one JSON object or a JSONL batch with `--jsonl`. Structural
+validation finishes before opening a writer. Each append commits separately;
+a later failure keeps earlier appends. A broken pipe can hide the receipt of
+an already committed message. Rerunning may create duplicates.
+
+`read --body` emits the reader's `body_text` exactly, including any controls
+present there, without adding a newline. `read --revision` adds the writer's
+identity and revision. `export --archive` reports reader issues as JSONL on
+stderr and exits 7 if any occur. Export is not a byte-identical backup.
+
+```sh
+uv run ftnt decode --charset IBMPC < old-text.txt
+uv run ftnt repair --json < utf8-text.txt
+```
+
+Both filters read the whole input into memory. Decode uses the core charset
+aliases, strict decoding and preserves line endings and trailing nulls.
+Repair uses the core heuristic explicitly; import/export never repair text.
+
+The public manual is the [front page](index.html) and one page per command:
+[create](create.html), [write](write.html), [read](read.html),
+[export](export.html), [decode](decode.html), [repair](repair.html),
+[heads](heads.html) and [catalog](catalog.html).
+Examples are in `examples/`. Maintainer notes stay in `docs/`.
+The pages share [DESIGN.md](DESIGN.md).
+
+Checks:
+
+```sh
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv build
+uv run twine check dist/*
+uv run python scripts/verify_distribution.py
+uv run scripts/build_reading_pages.py
+```
+
+Distribution checks build dependency wheels from sibling checkouts and run both
+CLI wheels in fresh environments outside the checkout. They do not establish
+public-index dependency resolution. The sdist strips checkout-only uv sources.
+The CI matrix targets Linux and macOS with Python 3.12 and 3.14. Windows is
+unsupported for now. GoldED Opus runtime interoperability remains unverified.
+There is no configured remote, published CLI package or Pages deployment.

golded_ftn_tools-1.0.1/README.md

@@ -0,0 +1,67 @@
+# FTNT💥
+
+Six command-line tools for FTN message bases, JSON fixtures and text pipes.
+Python 3.12+. MIT licensed.
+
+**Status: implemented locally, not released.** Development uses five sibling
+Python repositories. Opus writing requires the local `golded-ftn-msg` 1.3.0
+extension; a public installation must wait for that dependency release.
+
+```sh
+uv sync --locked
+uv run ftnt create ./fixtures/general --format jam
+uv run ftnt write ./fixtures/general --format jam < examples/message.json
+uv run ftnt export ./fixtures/general --format jam |
+  jq -c 'select(.message.subject | contains("fixture"))'
+```
+
+`create`, `write`, `read` and `export` use an explicit `--format`:
+`msg` (FTSC), `opus`, `jam`, `squish` or `hudson`. Hudson write/read requires
+`--board 1..200`. Bases must be offline: close GoldED and other users first.
+The format packages own validation, encoding, locks and rollback.
+
+`write` accepts one JSON object or a JSONL batch with `--jsonl`. Structural
+validation finishes before opening a writer. Each append commits separately;
+a later failure keeps earlier appends. A broken pipe can hide the receipt of
+an already committed message. Rerunning may create duplicates.
+
+`read --body` emits the reader's `body_text` exactly, including any controls
+present there, without adding a newline. `read --revision` adds the writer's
+identity and revision. `export --archive` reports reader issues as JSONL on
+stderr and exits 7 if any occur. Export is not a byte-identical backup.
+
+```sh
+uv run ftnt decode --charset IBMPC < old-text.txt
+uv run ftnt repair --json < utf8-text.txt
+```
+
+Both filters read the whole input into memory. Decode uses the core charset
+aliases, strict decoding and preserves line endings and trailing nulls.
+Repair uses the core heuristic explicitly; import/export never repair text.
+
+The public manual is the [front page](index.html) and one page per command:
+[create](create.html), [write](write.html), [read](read.html),
+[export](export.html), [decode](decode.html), [repair](repair.html),
+[heads](heads.html) and [catalog](catalog.html).
+Examples are in `examples/`. Maintainer notes stay in `docs/`.
+The pages share [DESIGN.md](DESIGN.md).
+
+Checks:
+
+```sh
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv build
+uv run twine check dist/*
+uv run python scripts/verify_distribution.py
+uv run scripts/build_reading_pages.py
+```
+
+Distribution checks build dependency wheels from sibling checkouts and run both
+CLI wheels in fresh environments outside the checkout. They do not establish
+public-index dependency resolution. The sdist strips checkout-only uv sources.
+The CI matrix targets Linux and macOS with Python 3.12 and 3.14. Windows is
+unsupported for now. GoldED Opus runtime interoperability remains unverified.
+There is no configured remote, published CLI package or Pages deployment.

golded_ftn_tools-1.0.1/docs/JSON.md

@@ -0,0 +1,152 @@
+# JSON contract
+
+Status: schema version 1 implemented locally. CLI version and schema version
+are distinct. Release verification is recorded in VERIFICATION.md.
+
+## Import
+
+`write` accepts a flat object matching `OutgoingMessage`. Required fields:
+`from_name`, `to_name`, `subject`, `body_text`, all strings. Empty strings are
+structurally valid, but format validation may reject them.
+
+| Optional field | JSON type | Default |
+| --- | --- | --- |
+| `external_id` | string / null | null |
+| `from_address`, `to_address` | FTN address string / null | null |
+| `posted_at` | ISO 8601 datetime string / null | null |
+| `attributes_raw` | integer >= 0 / null | null |
+| `control_lines` | array of control objects | [] |
+| `reply_to_msgno`, `reply1st_msgno`, `reply_next_msgno` | integer >= 0 / null | null |
+| `reply_list` | array of integers >= 0 | [] |
+| `routing_seen_by`, `routing_path` | array of strings | [] |
+
+`posted_at` accepts `YYYY-MM-DDTHH:MM:SS` with optional `Z` or numeric UTC offset,
+without microseconds. Reject invalid calendar dates. Timezone requirements are
+format-specific and checked structurally before writing:
+
+| Format | Date input |
+| --- | --- |
+| MSG / FTSC | Naive datetime; no timezone |
+| MSG / Opus | Naive datetime; 1980–2069, even seconds, no microseconds |
+| JAM | Naive (interpreted as UTC) or timezone-aware datetime |
+| Squish | Timezone-aware datetime; writer converts to UTC |
+| Hudson | Naive datetime; no timezone |
+
+Opus dates use both DOS written words and the textual date. The local MSG 1.3.0
+writer accepts their shared 1980–2069 range and rejects odd seconds. Omitted dates
+write zero written words and an empty textual date; new arrived words are zero
+because the core input model has no arrived field. Updates in the MSG package
+preserve arrived words. Runtime GoldED interoperability remains unverified.
+
+Pass datetime through without converting or removing timezone. Use
+`examples/message.json` for MSG/JAM/Hudson and `examples/message-squish.json`
+for Squish. Date precision and year limits belong to the writer. Omitted/null
+dates become None; this does not guarantee the current time. There is no common
+lossless date contract across formats.
+
+Parse addresses with `FtnAddress.from_string`, e.g. `2:236/77.1@fidonet`. Preserve
+domain and point in the model; formats may impose narrower limits. Do not expand
+abbreviated addresses. Booleans are not integers. Writers validate numeric widths;
+a large JSON integer does not establish a valid header value.
+
+Control objects require string `name` and `value`. Optional string `raw` defaults
+to an empty string and maps directly to `ControlLine.raw`. Preserve unknown
+controls in the input model. Writers decide raw/structured serialization and
+conflicts. Do not invent another raw meaning or CLI-specific kludge escaping.
+Arrays preserve order and duplicates. `external_id` is external MSGID, never a
+base number. Do not conceal contradictory controls, MSGID or charset declarations.
+
+Reject unknown top-level/control keys, duplicate keys, NaN/Infinity, incorrect
+nested types, BOM and invalid UTF-8 with a record number. `provenance`, `msgno`,
+`identity`, `revision` and export envelopes are not write input. Provenance comes
+from the source/read operation, not an imported claim about the new record.
+
+No arbitrary binary header import or requested message number. Append assigns
+the format's number. Fixture authors manage forward reply links; there is no
+automatic link resolver.
+
+## Export and read
+
+Messages use this envelope:
+
+```json
+{
+  "schema_version": 1,
+  "type": "message",
+  "source": {"format": "jam", "base": "/resolved/path/general", "board": null},
+  "message": {
+    "msgno": 1,
+    "from_name": "Alice",
+    "to_name": "Bob",
+    "subject": "Encoding fixture: æøå",
+    "body_text": "First line.\nSecond line.",
+    "attributes_raw": 0
+  }
+}
+```
+
+`message` includes all `ParsedMessage` fields, including nulls. The example shows
+only required fields. Serialize dates with `datetime.isoformat()`; addresses stay
+reader strings. Serialize control metadata and provenance recursively from
+dataclass fields. Tuples become arrays. Do not normalize IDs, routing or text
+beyond existing reader behavior.
+
+`source.base` is the resolved absolute base path. Hudson `source.board` comes
+from the reader's `area_meta_key="hudson:N"`, set from the binary board byte.
+The adapter checks N is in 1..200. A two-board literal fixture protects this
+mapping and lookup; message titles are not inspected.
+Do not invent unavailable fields. Paths can expose local structure; users decide
+whether to share output.
+
+Only `read --revision` adds envelope-level `identity` and `revision`. Normal
+read/export omit them. Treat digest and location as opaque data. They belong to
+a physical base, not a portable export ID.
+
+## Create and write results
+
+```json
+{"schema_version":1,"type":"create_result","format":"jam","base":"/resolved/path/general"}
+```
+
+```json
+{
+  "schema_version": 1,
+  "type": "write_result",
+  "input_record": 1,
+  "identity": {"format": "jam", "base": "/resolved/path/general", "msgno": 1, "board": null},
+  "revision": {
+    "identity": {"format": "jam", "base": "/resolved/path/general", "msgno": 1, "board": null},
+    "location": [1024, 0],
+    "digest": "opaque-sha256-digest"
+  }
+}
+```
+
+Location is illustrative; emit the writer's actual tuple unchanged. Map identity
+and revision from `WriteResult`, never reconstruct them. `input_record` is
+one-based. Do not emit an extra summary line on stdout.
+
+Export can produce new write input with an explicit mapping:
+
+```sh
+ftnt export ./old --format jam |
+  jq -c '.message | {from_name, to_name, subject, body_text, posted_at, external_id}' |
+  ftnt write ./new --format jam --jsonl
+```
+
+This intentionally selects only some fields. It is not a complete clone.
+
+## Repair and issues
+
+`repair --json` emits `schema_version: 1`, `type: "repair_result"`, and the core
+fields `text`, `changed`, `confidence`. Confidence is a heuristic score, not a probability.
+
+Archive issues on stderr contain `schema_version: 1`, `type: "reader_issue"` and
+an `issue` object with every `ReaderIssue` field. Known command errors on stderr
+are human-readable and include record number/commit count for batch failures.
+A stable machine-readable error schema is outside v1.
+
+Schema version 1 may gain documented optional output fields, but existing names,
+types and meanings must not change. Consumers must ignore unknown output fields.
+Write input stays strict. Breaking JSON changes require a new schema version
+and an explicit migration.

golded_ftn_tools-1.0.1/docs/PLAN.md

@@ -0,0 +1,231 @@
+# Implementation plan
+
+Status: implementation started 2026-10-06. The phases below preserve the original
+acceptance plan. Current implementation and verification are recorded here and
+in [VERIFICATION.md](VERIFICATION.md).
+
+## Implementation status
+
+- Six commands and schema v1 are implemented locally using public APIs.
+- Local MSG 1.3.0 adds explicit Opus sessions; dates use the shared DOS/text
+  range 1980–2069 with even seconds. Arrived words default to zero and survive updates.
+- Decode reads whole input in v1 and uses public `detect_charset(b"", charset)`
+  for alias selection. It preserves trailing nulls and line endings.
+- Hudson board mapping uses area_meta_key, protected by an independent two-board fixture.
+- Subprocess tests cover workflows, preflight, partial commits, archive issues,
+  locks, broken receipts, SIGINT and adapter error reporting.
+- Linux/Windows remote CI, GoldED Opus runtime interoperability and public-index
+  resolution remain release gates. Publication has not been authorized.
+- Design files were inventoried. FTNT inherits documentation tokens from
+  golded-ftn-python-docs/DESIGN.md, which uses golded-site's historical palette.
+  This change updates status/copy only; layout and shared visual rules are unchanged.
+
+
+## Chosen approach
+
+A separate CLI repository, thin adapters and standard-library `argparse`.
+`argparse` is sufficient for six commands and keeps the CLI's own runtime
+dependencies small. Reconsider Click/Typer for a concrete need, not colored help.
+
+Proposed dependencies: `golded-ftn>=1.2.1,<2` and the four format packages
+`golded-ftn-msg>=1.3.0,<2` and `golded-ftn-jam`, `golded-ftn-squish`,
+`golded-ftn-hudson` at `>=1.2.0,<2`. Install all formats in v1 so help matches actual capability.
+No local `uv.sources` in public distributions. Core and format packages version
+independently of the CLI. The MSG minimum version must be raised to the release
+that implements and verifies Opus writing; the published MSG 1.2.0 writer rejects it; the local 1.3.0 extension implements it.
+
+The CLI owns arguments, JSON types, text/binary streams and exit codes. Packages
+own FTN rules. Use `json` with explicit field validation rather than another
+runtime model framework. Choose small typed adapters over a plugin system.
+
+## 0. Establish API boundaries — small/medium
+
+Read [SPEC.md](SPEC.md) and [JSON.md](JSON.md), then inspect current installed
+packages again. The original plan used core 1.2.1 and format packages 1.2.0, inspected
+on 2026-10-05. Current local verification uses core 1.2.2 and MSG 1.3.0. Use public exports, not private writer helpers.
+
+Discovery before implementation:
+
+- Find a public codec/alias seam for incremental `decode`. If missing, propose a
+  small core API separately; alternatively document whole-input decoding in v1.
+  Do not duplicate alias tables or import private names.
+- Establish Hudson board mapping on `ParsedMessage` with a literal fixture and
+  verify read lookup across boards. Do not derive board from free text.
+- Check create paths, source_type values, writer date defaults and supported
+  reply fields per format. Document rejections in help.
+- Confirm dependency ranges resolve from PyPI without checkout sources.
+
+Exit: boundaries are settled. Revise the specification explicitly if a seam is missing.
+
+## 0a. Add Opus writing to golded-ftn-msg — medium/large
+
+Opus is a MSG header variant, not a fifth storage engine. Extend the public
+`golded-ftn-msg` writer before wiring CLI writes. Existing `MsgReader("opus")`
+can support reading/export while this work proceeds. No Opus serialization in
+CLI code and no claim that the current writer supports it.
+
+Use original GoldED source as the format reference. Document the public variant
+selection for create/open and implement create, append, consistent read, update
+and delete with the same identity, revision, offline and rollback contracts as
+FTSC. Preserve FTSC behavior. Explicit selection is required; do not guess or
+convert an existing area's header variant implicitly.
+
+- Serialize written/arrived DOS timestamps at bytes 176–183 rather than FTSC
+  zone/point words. Preserve both existing timestamps and unknown header bytes
+  on updates unless explicitly changed.
+- Represent zone/point through INTL/FMPT/TOPT. Specify how explicit addresses
+  and supplied controls agree; reject contradictions before mutation. Address
+  representation belongs to the format package, without adding automatic routing.
+- Settle the date contract before implementation: DOS years 1980–2107,
+  two-second precision, textual-date fallback, omitted written/arrived timestamps,
+  and the limits of the existing core model. Prefer rejecting unrepresentable
+  values over silent rounding. Document any required core API extension separately.
+- Use TDD with independent literal headers: both timestamps, zero/invalid dates,
+  year/precision limits, nonzero zones and points, reply links, unknown metadata,
+  and conflicting controls. Cover every writer operation, revisions, rollback,
+  and unchanged FTSC behavior; reader roundtrips alone are insufficient.
+- Verify GoldED reads and edits Python-written Opus messages and Python reads
+  and updates GoldED-written messages. Record the exact build/platform. This is
+  offline compatibility testing, not authorization for concurrent use.
+
+Exit: the public Opus writer contract is documented and tested, compatibility
+results are recorded, and the CLI's MSG dependency floor names a release with
+this capability. Publication remains a separately authorized step.
+
+## 1. CLI and JSON foundation — medium
+
+Add `pyproject.toml`, `src/golded_ftn_tools`, entry point, test/dependency groups
+and CI. Proposed separation: argument parser, JSON contract, format adapters,
+commands and shared diagnostic/exit-code mapping. Split responsibilities only
+where a real consumer needs it.
+
+Use TDD at the public CLI: one observable behavior at a time. Start with help,
+version, stdout/stderr separation, UTF-8, unknown keys, duplicate keys and
+addresses/dates. Avoid tests that merely mirror private functions.
+
+Exit: schema v1 parses input and serializes results without base I/O.
+
+## 2. Reading and text filters — medium
+
+Implement `decode`, `repair`, `read` and `export`. Add ordinary strict reading
+first, then archive issues and optional consistent revision reads. Use the actual
+readers and helpers, not an alternative parser. Include explicit `--format opus`
+using `MsgReader("opus")`; never interpret its timestamps as address words.
+Opus `read --revision` depends on the writer added in phase 0a.
+
+Tests: JSONL pipes, Unicode, CP850 and multibyte chunk boundaries, degree signs,
+mojibake, unchanged text, LF/CRLF, body without an extra newline, sparse msgno/UID,
+missing records, Hudson boards, corruption and partial exports. Cover archive
+callbacks and exit code 7. Document reader buffering and offline requirements.
+
+Exit: read/filter commands work without writes or automatic repair.
+
+## 3. Create/write, starting with JAM — medium/large
+
+Implement `create` and `write` for JAM, then MSG (FTSC and Opus), Squish and
+Hudson. Opus writes depend on phase 0a. Use
+context-managed sessions and `append`. Reject existing destination files.
+Spool JSONL preflight to a temporary file; format validation stays with writers.
+
+Tests: structural failure on record N causes zero writes; format/encoding failure
+on N preserves previous commits; receipts match actual identity/revision. Cover
+charset/control conflicts, numbers, dates, null input, attribute limits, reply
+fields, auxiliary files and Hudson boards 1/200. No sidecar, overwrite or retry.
+
+Exit: all four storage formats, including both MSG header variants, can create
+bases and read CLI-written messages back.
+Also compare some raw bytes to independent expectations, not only roundtrips.
+
+## 4. Failures, pipes and platforms — medium/large
+
+Add deterministic subprocess tests for lock timeout, broken pipe, SIGINT,
+I/O failure and rollback failure. Use a controlled lock helper and focused
+injection at the adapter boundary, not random timing. Reuse writer packages'
+already-tested rollback and verify CLI reporting of the relevant exception.
+Do not import private I/O layers to reproduce base algorithms.
+
+Run redirected CLI subprocesses on Linux/macOS/Windows. Separate POSIX 141/SIGINT
+from Windows behavior and record the observed contract. Cover failure after
+append commits but before the stdout receipt. Do not describe it as rollback.
+
+Exit: tests support SPEC's exit codes and partial-success semantics.
+
+## 5. Documentation and distribution — medium
+
+Replace planned status in README/HTML only once implementation exists. Keep
+HTML copy, JSON examples, help and specification aligned. Run examples from a
+wheel installed outside the checkout. Build wheel and sdist, inspect metadata
+and entry point, rebuild the sdist, resolve dependencies without local sources
+and run consumer tests.
+
+Update the GoldED design documents together:
+
+- `golded-ftn-tools/DESIGN.md`: FTNT identity, reading-copy generation, code
+  panels, page/section navigation and sidebar scroll behavior.
+- `golded-ftn-python-docs/DESIGN.md`: shared documentation rules and fixes that
+  also apply to the Python library documentation.
+- `golded-site/DESIGN.md`: shared GoldED identity and visual rules that also
+  apply to the main site.
+
+Inventory these files again when implementation begins. Compare shared palette,
+typography, section labels, syntax colors, navigation, mobile and print rules.
+Keep shared rules consistent and document intentional site-specific differences;
+do not copy FTNT branding or CLI-specific rules into every site. Identify the
+canonical source for each shared rule and cross-link it so later changes do not
+drift. Check the affected HTML pages against their updated design documents,
+including Safari sidebar scrolling and access to both ends of the TOC. Record
+which pages and viewport states were actually checked.
+
+Quality gate: pytest, Ruff lint/format, strict mypy, distribution checks,
+README/spec examples and `git diff --check`. CI uses the same gate; local results
+do not replace remote platform results. Run relevant API/format tests if a
+discovery change required changes in a dependency.
+
+Exit: SPEC acceptance criteria are met and documented; the relevant DESIGN.md
+files agree on shared rules, and affected pages have been checked against them.
+Tags, PyPI publication
+and GitHub Pages require a later explicit task. Implementation is local. No publication is automatic.
+
+## Review points
+
+Odinn can focus on:
+
+1. Six commands for the first release; `update/delete` can wait.
+2. Explicit `--format` instead of detection.
+3. Strict import and JSONL preflight with one commit per message.
+4. Export envelopes and separate write input instead of a false lossless roundtrip.
+5. Python packages are the engine; the CLI does not own format algorithms.
+
+These are recommended decisions, not unanswered questions blocking review.
+
+## Risks and accepted limits
+
+| Risk | Response |
+| --- | --- |
+| Reader and writer share a bug | Independent binary expectations in integration tests |
+| Late batch failure or closed pipe | Per-record receipts; no retry/whole-batch rollback |
+| Export omits unknown raw metadata | Describe export as data, not backup |
+| GoldED is using the base | Offline contract; no concurrent flag or new live promises |
+| Helper lacks a public streaming seam | Resolve in phase 0; separate core change if needed |
+| Fixture bytes vary with base time/platform | Fixed input date/MSGID; test content, not promised identical files |
+| Dependencies change API | Version bounds, clean installs and CI integration |
+
+## Source basis
+
+Checked in local source repositories before writing this plan:
+
+- Core `models.py`, `contracts.py` and exports: input model, sessions, revisions and issues.
+- `MsgReader`/`JamReader`/`HudsonReader` and all four writer exports/signatures.
+- Hudson `open(path, board, options, scan_path=...)` and its all-board reader behavior.
+- Core strict encoding/repair and writer format validation.
+
+Public references: [core API](https://golded-dev.github.io/golded-ftn-python-docs/core-api.html),
+[writer guide](https://golded-dev.github.io/golded-ftn-python-docs/writers.html) and
+[format references](https://golded-dev.github.io/golded-ftn-python-docs/).
+These are entry points; inspected source takes precedence over later drift in web copy.
+
+## Findings from example checks
+
+MSG/Hudson require naive dates; Squish requires timezone; JAM accepts both.
+Examples therefore use separate standard and Squish inputs. Preserve this
+difference in JSON validation instead of hiding it with timezone conversion.