golded-ftn-jam 1.2.0__tar.gz

golded_ftn_jam-1.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.agent-compose-backup-*/

golded_ftn_jam-1.2.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 1.2.0 — 2026-10-05
+
+- Add offline create/read/append/update/delete sessions, message revisions, record locks and rollback.
+- Preserve raw subfields and maintain JAM indices, CRCs and counters.
+- GoldED coexistence remains disabled pending build-specific integration tests.
+
+- Replace controls and MSGID across JHR/JDT placements; preserve omitted structured fields and reject conflicting controls.
+
+## 1.1.0 — Unreleased
+
+Add reported archive reading: keep bounded oversized subfields and malformed
+TZUTC metadata, retain distinct PID/FLAGS/TZUTC controls, try configured fallback
+for mislabeled ASCII, and skip failed indexed records. Ambiguous structure stops
+with a report. Strict reading remains the default.
+
+## 1.0.0
+
+- Read indexed JAM revision 1 areas with strict binary and decoding checks.
+- Preserve message text, supported subfields, reply links and provenance.
+- Ship typed public exports and independent synthetic fixtures.
+- Report charset conflict offsets against stored subfield bytes.
+- Keep development-only uv sources out of source distributions.

golded_ftn_jam-1.2.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Use Python 3.12+ and uv with the sibling `golded-ftn` checkout. Run the checks in
+README before proposing a change. Keep runtime dependencies limited to core.
+
+Build fixtures from the JAM specification, independently of reader helpers.
+Use synthetic messages; keep private archives out of tests and distributions.
+Verify changed behavior through `JamReader.read`, including failures and offsets.
+
+Keep this package focused on JAM reading and editing. Area discovery, databases,
+packing and repair belong outside this package. Generated AGENTS.md comes from agent-compose.toml and the
+local project fragment; edit those sources and preview, build, check.
+
+Protect writer behavior through the public create/open/read/append/update/delete
+API and independent raw records. Check omitted patch fields, explicit clearing,
+controls in each supported physical placement, reply structures and unrelated
+message revisions. Use controlled helper processes for lock conflicts and the
+internal I/O seam for write, truncate, flush and rollback failures. Never reopen
+the lock file while its operation lock is held. Preserve existing lastread data.
+
+Keep GoldED closed during editing. A matching write lock alone does not prove
+safe concurrent reads or refresh; build interoperability remains deferred.

golded_ftn_jam-1.2.0/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_jam-1.2.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: golded-ftn-jam
+Version: 1.2.0
+Summary: Strict reader and offline writer for JAM revision 1 message areas
+Project-URL: Repository, https://github.com/golded-dev/golded-ftn-jam-python
+Project-URL: Issues, https://github.com/golded-dev/golded-ftn-jam-python/issues
+Project-URL: Changelog, https://github.com/golded-dev/golded-ftn-jam-python/blob/main/CHANGELOG.md
+Author: GoldED.dev contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: golded-ftn<2,>=1.2.0
+Description-Content-Type: text/markdown
+
+# golded-ftn-jam
+
+Repository: [`golded-ftn-jam-python`](https://github.com/golded-dev/golded-ftn-jam-python).
+The distribution remains `golded-ftn-jam`; imports use `golded_ftn_jam`.
+The source is public on GitHub. This package has not been released on PyPI.
+
+Read and edit JAM revision 1 areas through the `golded-ftn` models. Python 3.12+.
+Version 1.2.0 is prepared locally; these writer changes are unreleased.
+
+```sh
+git clone https://github.com/golded-dev/golded-ftn-python.git
+git clone https://github.com/golded-dev/golded-ftn-jam-python.git
+cd golded-ftn-jam-python
+uv sync --locked
+```
+
+```python
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from golded_ftn import MessageBaseReader, ReaderOptions
+from golded_ftn_jam import JamReader
+
+# A minimal empty area. Real callers pass the area basename, without an extension.
+with TemporaryDirectory() as directory:
+    base = Path(directory) / "example"
+    header = bytearray(1024)
+    header[:4] = b"JAM\0"
+    header[20:24] = (1).to_bytes(4, "little")
+    base.with_suffix(".JHR").write_bytes(header)
+    base.with_suffix(".JDT").write_bytes(b"")
+    base.with_suffix(".JDX").write_bytes(b"")
+    reader: MessageBaseReader = JamReader()
+    messages = list(reader.read(base, ReaderOptions(fallback_charset="CP850")))
+    assert messages == []
+```
+
+The basename is exact; `.JHR`, `.JDT` and `.JDX` extensions are matched without
+regard to case. Each must identify one regular file; symlinks and ambiguous
+extension variants are rejected. The standalone reader ignores `.JLR`; editing
+preserves it and creation initializes an empty file.
+
+The index determines message numbers and which headers are live. Index holes and
+deleted messages are skipped. Old unindexed headers are ignored. The reader
+validates signatures, revision, record boundaries, offsets, subfield lengths,
+message numbers and reused header offsets. It reads the whole area into memory
+and validates all indexed records before returning a tuple. A malformed later
+record cannot leave a caller with a partial result. Filesystem errors remain
+filesystem errors; damaged data and decoding errors raise `ParserException` with
+source path, byte offset and a chained cause.
+
+The standalone `JamReader` requires a stable area with no concurrent writes. It
+does not lock the area or produce a snapshot across the three files. Stop the
+writer or use a consistent copy before reading.
+
+Decoding is strict, with core charset detection and CP850 fallback. Header
+FTSKLUDGE declarations are considered before body declarations. Conflicting
+charset declarations and IDs fail. Unknown charset names use the configured
+fallback. Mojibake repair is the caller's choice.
+
+`body_text` contains only normalized `.JDT` text. Header control and routing
+subfields go into `control_lines`, ahead of body metadata. Repeated controls and
+routing entries keep their order within the core model's kludges, seen_by and
+path sequences. Unknown subfields and nonzero HiID fields are bounds-checked
+and skipped. The first originating/destination address is preserved as decoded
+text, including node 0, point and domain. Other single-value subfields must agree
+when repeated. Header MSGID/REPLYID take precedence over matching body IDs;
+missing MSGID uses the core synthetic ID over decoded, normalized fields.
+
+Dates are naive `1970-01-01 + DateWritten seconds`, independent of the machine's
+timezone; zero means `None`. TZUTC is retained as a control line. Raw attributes,
+all three reply links and `.JHR` provenance are retained; zero reply links become
+`None`. Unknown area metadata stays `None`.
+
+Compressed, encrypted and escaped active messages are unsupported. Area
+discovery, databases, packing and repair are outside this package.
+
+## Development
+
+```sh
+uv sync --locked --python 3.14
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run python -m mypy.stubtest golded_ftn_jam
+uv build
+uv run twine check dist/*
+uv run python scripts/verify_distribution.py
+```
+
+uv uses the sibling `../golded-ftn-python` checkout during development. Published metadata
+contains only `golded-ftn>=1.2.0,<2`. The sdist build hook removes `tool.uv.sources`
+from the packed `pyproject.toml`; the development lock is also excluded.
+Unpacked sources use the public dependency constraint.
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [release checks](docs/release.md).
+
+## Format references and credits
+
+- [JAM-001 revision 1](https://raw.githubusercontent.com/Mithgol/node-fidonet-jam/master/JAM.txt)
+- [GoldED JAM structures](https://github.com/golded-dev/golded-linux-macos/blob/main/goldlib/gmb3/gmojamm.h)
+- The sibling `laravel-ftn-jam/src/JamReader.php` and its reader tests informed
+  model mapping. Its sequential scan and permissive truncation are not used.
+
+JAM(mbp) - Copyright 1993 Joaquim Homrighausen, Andrew Milner, Mats Birch, Mats Wallin. ALL RIGHTS RESERVED.
+
+The package code is MIT licensed; the JAM specification has its own terms.
+
+## Archive mode
+
+Strict reading remains the default. Archive mode requires a report callback:
+
+```python
+from golded_ftn import ReaderIssue, ReaderOptions
+
+issues: list[ReaderIssue] = []
+options = ReaderOptions(archive_mode=True, on_issue=issues.append)
+# Pass options to JamReader().read(source, options).
+```
+
+Issues carry `recovered`, `skipped` or `stopped`, the actual filename, record
+identity and physical offset. Their detail contains no message contents. A stop
+means the traversal is incomplete; a validated prefix may still be returned.
+Multiple issues can describe one record, including recovery followed by a skip.
+Filesystem errors and callback exceptions propagate. Files must remain stable.
+
+Bounded fields exceeding JAM's specification limits are retained and reported.
+Malformed TZUTC metadata is retained without interpretation. Distinct PID, FLAGS
+and TZUTC subfields stay in source order. Conflicting names, subjects, IDs or
+charset declarations are skipped rather than guessed. Failed records are skipped
+using the next fixed index slot; reused header offsets stop traversal.
+
+If declared ASCII cannot decode a payload, the configured fallback is tried
+strictly and reported. The original charset control stays unchanged. Other
+decoding failures are skipped; there is no lossy decoding or mojibake repair.
+
+## Writing
+
+`JamWriter.create(base)` creates `.JHR`, `.JDT`, `.JDX` and an empty `.JLR`.
+Existing files are refused. The initial message number is 1.
+
+```python
+from golded_ftn import MessagePatch, OutgoingMessage
+from golded_ftn_jam import JamWriter
+
+writer = JamWriter()
+writer.create("new-area")
+with writer.open("new-area") as session:
+    result = session.append(
+        OutgoingMessage(
+            from_name="Alice",
+            to_name="Bob",
+            subject="Hello",
+            body_text="Hello Bob",
+        )
+    )
+    result = session.update(
+        result.identity, MessagePatch(subject="Changed"), result.revision
+    )
+    session.delete(result.identity, result.revision)
+```
+
+Every operation rereads and validates the index, referenced headers, text ranges
+and active-message count under the byte-0 `.JHR` record lock. A session read returns
+`SessionMessage` with a raw-byte SHA-256 revision. Changes to other messages do not
+invalidate it. The revision includes identity, physical index/header/text locations
+and SHA-256 over raw header, subfield and text bytes. An omitted patch field
+retains its raw metadata; explicit `None` clears optional metadata. Names, subject, text and attributes reject `None`.
+
+`control_lines` replaces general controls in both header subfields and inline
+text. MSGID, address controls and routing retain their separate fields when
+omitted; conflicting explicit controls are rejected. `external_id` and routing
+patches remove obsolete inline copies as well as replacing their header metadata.
+Body-only changes retain existing inline controls and routing. Unknown subfields
+and nonzero HiID values survive unless their supported field is explicitly changed.
+
+Content updates append a header, subfields and text, then redirect the index.
+Header-only changes retain the text bytes and record position. Unknown subfields,
+reserved words, timestamps and reply links remain intact. Delete marks the header,
+sets the recipient index CRC to FFFFFFFF, and decrements the active count. Message
+numbers and lastread data remain unchanged.
+
+CP850 is the default. Encoding is strict; conflicting charset declarations,
+truncation, unsupported compression flags and arbitrary reply lists are refused.
+No MSGID, routing or duplicate detection is generated. Full-file snapshots support
+in-place rollback during ordinary I/O failures; rollback failure poisons the session.
+This provides no process-kill or power-loss transaction guarantee.
+
+GoldED coexistence is disabled on every platform (`concurrent=True` is refused).
+macOS/Linux use POSIX record locking. Core provides Windows offline record locks
+and I/O, but this checkout has only been tested on macOS. Windows and Linux
+execution and GoldED interoperability remain unverified. Keep GoldED closed and
+avoid direct file access while these sessions operate. GoldED builds and
+integration tests are deferred.
+
+### Original-source evidence
+
+The reference checkout is `golded-open-source`, commit
+`600266252b73174ff5116cee697ef9a97aeb1859`. It contains
+`goldlib/gmb3/gmojamm.h` (`JamHdrInfo`,
+`JamHdr`, `JamIndex`, subfield IDs), `gmojamm2.cpp` (`open_area` initialization,
+`scan` indexing), and `gmojamm4.cpp` (`lock`, `unlock`, `save_message`).
+`lock` takes byte 0 length 1 in `.JHR`; `save_message` maintains recipient/MSGID/
+REPLY CRCs, active count and modification counter. Its CRC seed and missing final
+complement are confirmed by `goldlib/gall/gcrcs32.cpp::strCrc32`.
+These source checks establish layout and write semantics. They do not establish
+that a running GoldED reader refreshes safely after external changes.

golded_ftn_jam-1.2.0/README.md

@@ -0,0 +1,207 @@
+# golded-ftn-jam
+
+Repository: [`golded-ftn-jam-python`](https://github.com/golded-dev/golded-ftn-jam-python).
+The distribution remains `golded-ftn-jam`; imports use `golded_ftn_jam`.
+The source is public on GitHub. This package has not been released on PyPI.
+
+Read and edit JAM revision 1 areas through the `golded-ftn` models. Python 3.12+.
+Version 1.2.0 is prepared locally; these writer changes are unreleased.
+
+```sh
+git clone https://github.com/golded-dev/golded-ftn-python.git
+git clone https://github.com/golded-dev/golded-ftn-jam-python.git
+cd golded-ftn-jam-python
+uv sync --locked
+```
+
+```python
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from golded_ftn import MessageBaseReader, ReaderOptions
+from golded_ftn_jam import JamReader
+
+# A minimal empty area. Real callers pass the area basename, without an extension.
+with TemporaryDirectory() as directory:
+    base = Path(directory) / "example"
+    header = bytearray(1024)
+    header[:4] = b"JAM\0"
+    header[20:24] = (1).to_bytes(4, "little")
+    base.with_suffix(".JHR").write_bytes(header)
+    base.with_suffix(".JDT").write_bytes(b"")
+    base.with_suffix(".JDX").write_bytes(b"")
+    reader: MessageBaseReader = JamReader()
+    messages = list(reader.read(base, ReaderOptions(fallback_charset="CP850")))
+    assert messages == []
+```
+
+The basename is exact; `.JHR`, `.JDT` and `.JDX` extensions are matched without
+regard to case. Each must identify one regular file; symlinks and ambiguous
+extension variants are rejected. The standalone reader ignores `.JLR`; editing
+preserves it and creation initializes an empty file.
+
+The index determines message numbers and which headers are live. Index holes and
+deleted messages are skipped. Old unindexed headers are ignored. The reader
+validates signatures, revision, record boundaries, offsets, subfield lengths,
+message numbers and reused header offsets. It reads the whole area into memory
+and validates all indexed records before returning a tuple. A malformed later
+record cannot leave a caller with a partial result. Filesystem errors remain
+filesystem errors; damaged data and decoding errors raise `ParserException` with
+source path, byte offset and a chained cause.
+
+The standalone `JamReader` requires a stable area with no concurrent writes. It
+does not lock the area or produce a snapshot across the three files. Stop the
+writer or use a consistent copy before reading.
+
+Decoding is strict, with core charset detection and CP850 fallback. Header
+FTSKLUDGE declarations are considered before body declarations. Conflicting
+charset declarations and IDs fail. Unknown charset names use the configured
+fallback. Mojibake repair is the caller's choice.
+
+`body_text` contains only normalized `.JDT` text. Header control and routing
+subfields go into `control_lines`, ahead of body metadata. Repeated controls and
+routing entries keep their order within the core model's kludges, seen_by and
+path sequences. Unknown subfields and nonzero HiID fields are bounds-checked
+and skipped. The first originating/destination address is preserved as decoded
+text, including node 0, point and domain. Other single-value subfields must agree
+when repeated. Header MSGID/REPLYID take precedence over matching body IDs;
+missing MSGID uses the core synthetic ID over decoded, normalized fields.
+
+Dates are naive `1970-01-01 + DateWritten seconds`, independent of the machine's
+timezone; zero means `None`. TZUTC is retained as a control line. Raw attributes,
+all three reply links and `.JHR` provenance are retained; zero reply links become
+`None`. Unknown area metadata stays `None`.
+
+Compressed, encrypted and escaped active messages are unsupported. Area
+discovery, databases, packing and repair are outside this package.
+
+## Development
+
+```sh
+uv sync --locked --python 3.14
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run python -m mypy.stubtest golded_ftn_jam
+uv build
+uv run twine check dist/*
+uv run python scripts/verify_distribution.py
+```
+
+uv uses the sibling `../golded-ftn-python` checkout during development. Published metadata
+contains only `golded-ftn>=1.2.0,<2`. The sdist build hook removes `tool.uv.sources`
+from the packed `pyproject.toml`; the development lock is also excluded.
+Unpacked sources use the public dependency constraint.
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [release checks](docs/release.md).
+
+## Format references and credits
+
+- [JAM-001 revision 1](https://raw.githubusercontent.com/Mithgol/node-fidonet-jam/master/JAM.txt)
+- [GoldED JAM structures](https://github.com/golded-dev/golded-linux-macos/blob/main/goldlib/gmb3/gmojamm.h)
+- The sibling `laravel-ftn-jam/src/JamReader.php` and its reader tests informed
+  model mapping. Its sequential scan and permissive truncation are not used.
+
+JAM(mbp) - Copyright 1993 Joaquim Homrighausen, Andrew Milner, Mats Birch, Mats Wallin. ALL RIGHTS RESERVED.
+
+The package code is MIT licensed; the JAM specification has its own terms.
+
+## Archive mode
+
+Strict reading remains the default. Archive mode requires a report callback:
+
+```python
+from golded_ftn import ReaderIssue, ReaderOptions
+
+issues: list[ReaderIssue] = []
+options = ReaderOptions(archive_mode=True, on_issue=issues.append)
+# Pass options to JamReader().read(source, options).
+```
+
+Issues carry `recovered`, `skipped` or `stopped`, the actual filename, record
+identity and physical offset. Their detail contains no message contents. A stop
+means the traversal is incomplete; a validated prefix may still be returned.
+Multiple issues can describe one record, including recovery followed by a skip.
+Filesystem errors and callback exceptions propagate. Files must remain stable.
+
+Bounded fields exceeding JAM's specification limits are retained and reported.
+Malformed TZUTC metadata is retained without interpretation. Distinct PID, FLAGS
+and TZUTC subfields stay in source order. Conflicting names, subjects, IDs or
+charset declarations are skipped rather than guessed. Failed records are skipped
+using the next fixed index slot; reused header offsets stop traversal.
+
+If declared ASCII cannot decode a payload, the configured fallback is tried
+strictly and reported. The original charset control stays unchanged. Other
+decoding failures are skipped; there is no lossy decoding or mojibake repair.
+
+## Writing
+
+`JamWriter.create(base)` creates `.JHR`, `.JDT`, `.JDX` and an empty `.JLR`.
+Existing files are refused. The initial message number is 1.
+
+```python
+from golded_ftn import MessagePatch, OutgoingMessage
+from golded_ftn_jam import JamWriter
+
+writer = JamWriter()
+writer.create("new-area")
+with writer.open("new-area") as session:
+    result = session.append(
+        OutgoingMessage(
+            from_name="Alice",
+            to_name="Bob",
+            subject="Hello",
+            body_text="Hello Bob",
+        )
+    )
+    result = session.update(
+        result.identity, MessagePatch(subject="Changed"), result.revision
+    )
+    session.delete(result.identity, result.revision)
+```
+
+Every operation rereads and validates the index, referenced headers, text ranges
+and active-message count under the byte-0 `.JHR` record lock. A session read returns
+`SessionMessage` with a raw-byte SHA-256 revision. Changes to other messages do not
+invalidate it. The revision includes identity, physical index/header/text locations
+and SHA-256 over raw header, subfield and text bytes. An omitted patch field
+retains its raw metadata; explicit `None` clears optional metadata. Names, subject, text and attributes reject `None`.
+
+`control_lines` replaces general controls in both header subfields and inline
+text. MSGID, address controls and routing retain their separate fields when
+omitted; conflicting explicit controls are rejected. `external_id` and routing
+patches remove obsolete inline copies as well as replacing their header metadata.
+Body-only changes retain existing inline controls and routing. Unknown subfields
+and nonzero HiID values survive unless their supported field is explicitly changed.
+
+Content updates append a header, subfields and text, then redirect the index.
+Header-only changes retain the text bytes and record position. Unknown subfields,
+reserved words, timestamps and reply links remain intact. Delete marks the header,
+sets the recipient index CRC to FFFFFFFF, and decrements the active count. Message
+numbers and lastread data remain unchanged.
+
+CP850 is the default. Encoding is strict; conflicting charset declarations,
+truncation, unsupported compression flags and arbitrary reply lists are refused.
+No MSGID, routing or duplicate detection is generated. Full-file snapshots support
+in-place rollback during ordinary I/O failures; rollback failure poisons the session.
+This provides no process-kill or power-loss transaction guarantee.
+
+GoldED coexistence is disabled on every platform (`concurrent=True` is refused).
+macOS/Linux use POSIX record locking. Core provides Windows offline record locks
+and I/O, but this checkout has only been tested on macOS. Windows and Linux
+execution and GoldED interoperability remain unverified. Keep GoldED closed and
+avoid direct file access while these sessions operate. GoldED builds and
+integration tests are deferred.
+
+### Original-source evidence
+
+The reference checkout is `golded-open-source`, commit
+`600266252b73174ff5116cee697ef9a97aeb1859`. It contains
+`goldlib/gmb3/gmojamm.h` (`JamHdrInfo`,
+`JamHdr`, `JamIndex`, subfield IDs), `gmojamm2.cpp` (`open_area` initialization,
+`scan` indexing), and `gmojamm4.cpp` (`lock`, `unlock`, `save_message`).
+`lock` takes byte 0 length 1 in `.JHR`; `save_message` maintains recipient/MSGID/
+REPLY CRCs, active count and modification counter. Its CRC seed and missing final
+complement are confirmed by `goldlib/gall/gcrcs32.cpp::strCrc32`.
+These source checks establish layout and write semantics. They do not establish
+that a running GoldED reader refreshes safely after external changes.

golded_ftn_jam-1.2.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security
+
+Treat message archives as untrusted input. Readers validate record boundaries,
+offsets and decoding, but archives must remain stable while being read.
+
+Report vulnerabilities privately through [GitHub security advisories](https://github.com/golded-dev/golded-ftn-jam-python/security/advisories/new).
+Do not put private archives, message contents or credentials in public issues.
+Security review targets the current 1.2.x development line. The writer changes
+are prepared locally and have not been published on PyPI.
+
+Writer sessions validate the base under their operation lock and roll back
+handled I/O failures. Keep GoldED closed; direct file access bypasses this lock.
+No recovery guarantee covers process termination or power loss. Archive mode is
+for reading damaged records, never for editing them.

golded_ftn_jam-1.2.0/docs/release.md

@@ -0,0 +1,86 @@
+# Release checks
+
+Run every README development check from a clean checkout with sibling core.
+`scripts/verify_distribution.py` inspects wheel/sdist contents and metadata,
+rebuilds the wheel from sdist, compares archive bytes, builds a local core wheel,
+and tests both JAM wheels in separate environments outside the repositories.
+It also checks runtime imports, README execution, strict test typing and stubtest.
+
+CI runs full checks on Linux Python 3.12, 3.13 and 3.14, with pytest on Windows
+and macOS Python 3.14. Local checks do not establish that CI passed.
+
+Inspect CHANGELOG and license notices. Commit only when requested. A local
+1.2.0 build does not publish a release. Remote creation, push, tagging and package
+publication each require explicit authorization.
+
+For writer changes, check create/read/append/update/delete through public sessions,
+independent binary fixtures, stale revisions, controlled lock contention and
+handled write/flush failures. Run examples against the installed wheel. Record
+platform results separately: local macOS tests do not establish Linux or Windows
+execution, or GoldED compatibility. Keep `concurrent=True` disabled until both
+competing writes and GoldED read/cache/refresh checks pass against a pinned build.
+The current GoldED build and integration tests are deferred.
+
+## Local 1.2.0 release candidate — 2026-10-05
+
+Verified on macOS 27.0 arm64 with CPython 3.14.6. The checkout contains
+uncommitted changes; these checks cover the working tree, not a tagged release.
+
+- `uv sync --locked`: passed.
+- Ruff lint and format checks, strict mypy: passed.
+- `uv run pytest -q`: 127 passed, 1 skipped.
+- `uv build` and `uv run twine check dist/*`: passed for wheel and sdist.
+- `scripts/verify_distribution.py`: passed metadata and package-content checks,
+  byte comparison against a wheel rebuilt from sdist, isolated installed-package
+  tests and strict consumer typing. Format packages also pass installed stubtest.
+- `agent-compose check`: passed using the local mostly-agents tool.
+- `git diff --check`: passed (whitespace only).
+
+GitHub's API reports the repository as public and private vulnerability reporting
+as enabled. PyPI's project JSON endpoint returned HTTP 404 on this date. No package
+was uploaded. Local checks do not establish Linux/Windows or remote CI results.
+GoldED build interoperability remains deferred; concurrent use stays disabled.
+
+Release order: publish `golded-ftn==1.2.0` first, then the four format packages.
+Each format package requires `golded-ftn>=1.2.0,<2`. Before publication, commit
+and review CI for these exact sources, create the intended release tag, and
+confirm the package-index destination and publishing authority. After core is
+available, verify resolution from that index without local uv sources. Publish
+only the reviewed archives, then check public installation and update the shared
+guide's commit pins to the released commits. These remote actions are not part
+of this local preparation.
+
+Archive checksums are recorded separately in `RELEASE-SHA256.txt` at the
+repository root, outside the archives, after the final build.
+
+## PyPI Trusted Publishing
+
+Create a PyPI account, verify its email and configure two-factor authentication.
+For a first publication, add a pending publisher at
+<https://pypi.org/manage/account/publishing/> with these exact fields:
+
+- PyPI project: `golded-ftn-jam`
+- GitHub owner: `golded-dev`
+- GitHub repository: `golded-ftn-jam-python`
+- Workflow filename: `publish.yml`
+- Environment: `pypi`
+
+See [PyPI's pending-publisher instructions](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+No API token or password is required by the workflow. The account setup is a
+manual prerequisite; a GitHub release does not create the PyPI project.
+
+After this tag's CI succeeds and the GitHub release contains both archives and
+`RELEASE-SHA256.txt`, run:
+
+```sh
+gh workflow run publish.yml --repo golded-dev/golded-ftn-jam-python -f tag=v1.2.0
+```
+
+The workflow verifies SHA-256 and uploads those exact release assets. Publish
+core first, verify installation from PyPI, then dispatch the format workflows.
+Confirm the workflow result, PyPI version and hashes, and installation in a fresh
+environment. Do not store publishing credentials in this repository.
+
+The deterministic process-lock helper uses native `msvcrt` byte locks on
+Windows and `fcntl` record locks on POSIX. Both coordinate through an explicit
+ready signal and release request; the test does not depend on random timing.

golded_ftn_jam-1.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "golded-ftn-jam"
+version = "1.2.0"
+description = "Strict reader and offline writer for JAM revision 1 message areas"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "GoldED.dev contributors"}]
+dependencies = ["golded-ftn>=1.2.0,<2"]
+classifiers = ["Programming Language :: Python :: 3", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.14", "Typing :: Typed", "Operating System :: OS Independent"]
+
+[project.urls]
+Repository = "https://github.com/golded-dev/golded-ftn-jam-python"
+Issues = "https://github.com/golded-dev/golded-ftn-jam-python/issues"
+Changelog = "https://github.com/golded-dev/golded-ftn-jam-python/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.11", "mypy>=1.15", "build>=1.2", "twine>=6", "hatchling>=1.26"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/golded_ftn_jam"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "scripts", "docs", "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.sdist.hooks.custom]
+path = "scripts/sdist_hook.py"
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests", "scripts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+