golded-ftn-sqlite 1.0.0__tar.gz

golded_ftn_sqlite-1.0.0/.gitignore

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

golded_ftn_sqlite-1.0.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.0 — 2026-10-25
+
+- Add schema version 1 for single- and multi-area SQLite message bases.
+- Add netmail and echomail reading, transactional append, full update and soft delete.
+- Preserve addresses, ordered controls, routing, reply metadata and import provenance.
+- Add optimistic revisions covering message and related metadata rows.

golded_ftn_sqlite-1.0.0/CONTEXT.md

@@ -0,0 +1,37 @@
+# FTN SQLite message base
+
+This context names the durable things in the SQLite message-base format.
+
+## Language
+
+**Database**:
+One SQLite file containing one or more areas.
+_Avoid_: Base file, container
+
+**Area**:
+A numbered sequence of either netmail or echomail messages. The normal deployment has one area per database, while the format permits several.
+_Avoid_: Board, folder
+
+**Netmail**:
+A point-to-point FTN message with an origin and an explicit destination address.
+_Avoid_: Direct message
+
+**Echomail**:
+An FTN message distributed through a named area with ordered routing metadata.
+_Avoid_: Conference message
+
+**Message number**:
+A positive, monotonic identity local to one area. Deleted numbers remain consumed.
+_Avoid_: Database row ID, MSGID
+
+**External message ID**:
+The network-visible FTN `MSGID`, when present. It is data, not the database identity.
+_Avoid_: Message number, row ID
+
+**Address**:
+A canonical FTN address string (`zone:net/node[.point][@domain]`), stored as TEXT and mapped to a structured DTO in application code. Absent address is SQL NULL.
+_Avoid_: Split zone/net/node columns
+
+**Revision**:
+A token covering one stored message and its ordered metadata, used to reject stale updates and deletes.
+_Avoid_: Version number

golded_ftn_sqlite-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Use Python 3.12+ and uv. Work through the public database, reader and writer seams;
+the SQLite schema is also a public format seam and may be checked with an independent
+`sqlite3` connection.
+
+Run:
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run python -m mypy.stubtest golded_ftn_sqlite
+uv build
+uv run twine check dist/*
+uv run python scripts/verify_distribution.py
+```
+
+Use synthetic messages. Keep private archives, credentials and access material out
+of tests and distributions. Schema changes require a migration and a new documented
+`user_version`; editing version 1 in place after release is not compatibility.

golded_ftn_sqlite-1.0.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_sqlite-1.0.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: golded-ftn-sqlite
+Version: 1.0.0
+Summary: Transactional SQLite message bases for FTN netmail and echomail
+Project-URL: Repository, https://github.com/golded-dev/golded-ftn-sqlite-python
+Project-URL: Issues, https://github.com/golded-dev/golded-ftn-sqlite-python/issues
+Project-URL: Changelog, https://github.com/golded-dev/golded-ftn-sqlite-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.4.0
+Description-Content-Type: text/markdown
+
+# golded-ftn-sqlite
+
+Repository: [`golded-ftn-sqlite-python`](https://github.com/golded-dev/golded-ftn-sqlite-python).
+Install version 1.0.0 with Python 3.12 or newer:
+
+```sh
+python -m pip install golded-ftn-sqlite==1.0.0
+```
+
+`golded-ftn-sqlite` stores FTN netmail and echomail in SQLite through the
+[`golded-ftn`](https://github.com/golded-dev/golded-ftn-python) message models.
+It requires Python 3.12 or newer.
+
+The format supports several areas in one database. The ordinary layout is still
+one database file per area: it maps cleanly to GoldED configuration, keeps backup
+and recovery local, and limits the blast radius when a disk has opinions.
+
+## Pipe with ftnt
+
+`ftnt` treats export envelopes as write input for every format, including SQLite:
+
+```sh
+ftnt create ./general.sqlite3 --format sqlite --area-code FIDO.GENERAL
+ftnt export ./general --format jam |
+  ftnt write ./general.sqlite3 --format sqlite --jsonl
+```
+
+## Use it
+
+```python
+from golded_ftn import FtnAddress, OutgoingMessage
+from golded_ftn_sqlite import (
+    AreaDefinition,
+    AreaKind,
+    SqliteDatabase,
+    SqliteReader,
+    SqliteWriter,
+)
+
+path = "fido-general.sqlite3"
+SqliteDatabase.create(
+    path,
+    area=AreaDefinition(
+        code="FIDO.GENERAL",
+        name="FidoNet General",
+        kind=AreaKind.ECHOMAIL,
+        default_origin=FtnAddress(zone=2, net=230, node=0),
+    ),
+)
+
+with SqliteWriter().open(path) as session:
+    result = session.append(
+        OutgoingMessage(
+            from_name="Alice",
+            to_name="All",
+            subject="Hello",
+            body_text="Stored transactionally.",
+        )
+    )
+    stored = session.read(result.identity.msgno)
+
+messages = tuple(SqliteReader().read(path))
+```
+
+When a database contains several areas, pass the area code to `SqliteReader` and
+`SqliteWriter`. Omitting it is allowed only for a single-area database. Message
+numbers are monotonic and local to each area.
+
+Netmail requires origin and destination addresses. The origin may come from the
+area's `default_origin`; the destination is always explicit. Echomail keeps ordered
+control lines, repeated unknown kludges, `SEEN-BY`, `PATH`, reply links and import
+provenance.
+
+Writer sessions provide `read`, `append`, `update` and soft `delete`. Updates and
+deletes require a revision token. The token covers the message row and its ordered
+control, routing and reply-list rows, including changes made by another SQLite
+client.
+
+## SQLite format
+
+Schema version 1 uses SQLite application ID `0x47465453` (`GFTS`), strict tables,
+foreign keys and WAL journaling. The schema is a public format contract:
+[docs/schema.md](docs/schema.md) documents identification, DDL, column semantics,
+allocation, soft delete, concurrency and backup so other packages or applications
+can implement the same database without this Python code.
+
+Do not copy an open WAL database as a lone `.sqlite3` file. Use SQLite's backup API
+or close/checkpoint it first.
+
+## Development
+
+```sh
+uv sync --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_sqlite
+uv build
+uv run twine check dist/*
+uv run python scripts/verify_distribution.py
+```
+

golded_ftn_sqlite-1.0.0/README.md

@@ -0,0 +1,103 @@
+# golded-ftn-sqlite
+
+Repository: [`golded-ftn-sqlite-python`](https://github.com/golded-dev/golded-ftn-sqlite-python).
+Install version 1.0.0 with Python 3.12 or newer:
+
+```sh
+python -m pip install golded-ftn-sqlite==1.0.0
+```
+
+`golded-ftn-sqlite` stores FTN netmail and echomail in SQLite through the
+[`golded-ftn`](https://github.com/golded-dev/golded-ftn-python) message models.
+It requires Python 3.12 or newer.
+
+The format supports several areas in one database. The ordinary layout is still
+one database file per area: it maps cleanly to GoldED configuration, keeps backup
+and recovery local, and limits the blast radius when a disk has opinions.
+
+## Pipe with ftnt
+
+`ftnt` treats export envelopes as write input for every format, including SQLite:
+
+```sh
+ftnt create ./general.sqlite3 --format sqlite --area-code FIDO.GENERAL
+ftnt export ./general --format jam |
+  ftnt write ./general.sqlite3 --format sqlite --jsonl
+```
+
+## Use it
+
+```python
+from golded_ftn import FtnAddress, OutgoingMessage
+from golded_ftn_sqlite import (
+    AreaDefinition,
+    AreaKind,
+    SqliteDatabase,
+    SqliteReader,
+    SqliteWriter,
+)
+
+path = "fido-general.sqlite3"
+SqliteDatabase.create(
+    path,
+    area=AreaDefinition(
+        code="FIDO.GENERAL",
+        name="FidoNet General",
+        kind=AreaKind.ECHOMAIL,
+        default_origin=FtnAddress(zone=2, net=230, node=0),
+    ),
+)
+
+with SqliteWriter().open(path) as session:
+    result = session.append(
+        OutgoingMessage(
+            from_name="Alice",
+            to_name="All",
+            subject="Hello",
+            body_text="Stored transactionally.",
+        )
+    )
+    stored = session.read(result.identity.msgno)
+
+messages = tuple(SqliteReader().read(path))
+```
+
+When a database contains several areas, pass the area code to `SqliteReader` and
+`SqliteWriter`. Omitting it is allowed only for a single-area database. Message
+numbers are monotonic and local to each area.
+
+Netmail requires origin and destination addresses. The origin may come from the
+area's `default_origin`; the destination is always explicit. Echomail keeps ordered
+control lines, repeated unknown kludges, `SEEN-BY`, `PATH`, reply links and import
+provenance.
+
+Writer sessions provide `read`, `append`, `update` and soft `delete`. Updates and
+deletes require a revision token. The token covers the message row and its ordered
+control, routing and reply-list rows, including changes made by another SQLite
+client.
+
+## SQLite format
+
+Schema version 1 uses SQLite application ID `0x47465453` (`GFTS`), strict tables,
+foreign keys and WAL journaling. The schema is a public format contract:
+[docs/schema.md](docs/schema.md) documents identification, DDL, column semantics,
+allocation, soft delete, concurrency and backup so other packages or applications
+can implement the same database without this Python code.
+
+Do not copy an open WAL database as a lone `.sqlite3` file. Use SQLite's backup API
+or close/checkpoint it first.
+
+## Development
+
+```sh
+uv sync --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_sqlite
+uv build
+uv run twine check dist/*
+uv run python scripts/verify_distribution.py
+```
+

golded_ftn_sqlite-1.0.0/SECURITY.md

@@ -0,0 +1,11 @@
+# Security
+
+Treat SQLite message bases as untrusted input. Open only databases with the expected
+application ID and schema version, and keep foreign-key validation enabled for writes.
+
+Report vulnerabilities privately through GitHub security advisories once the public
+repository exists. Do not attach private message bases, message contents, credentials
+or access material to public reports.
+
+WAL databases may have live `-wal` and `-shm` sidecars. Use SQLite's backup API for
+a consistent copy while writers are active.

golded_ftn_sqlite-1.0.0/docs/adr/0001-single-area-default-multi-area-format.md

@@ -0,0 +1,3 @@
+# Single-area default, multi-area format
+
+Schema version 1 permits several areas in one SQLite database, while documentation and automatic area selection treat one area per file as the normal layout. This keeps GoldED-style configuration, backup and failure isolation simple without baking that operational choice into the format; servers and tossers can group areas later without a migration.