txstore 0.1.0__tar.gz

txstore-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env

txstore-0.1.0/AGENTS.md

@@ -0,0 +1,80 @@
+# AI coding agent guide
+
+Root contracts decide behavior; the implementation shows current state. Keep one canonical owner per
+fact; link instead of copying.
+
+## Source priority
+
+1. The root contract that owns the domain below; `STYLE.md` prevails on style.
+2. Implementation under `src/txstore/` when checking current behavior.
+3. `docs/guides/` for user how-tos, `docs/development/` for contributor explanations and diagrams,
+   `docs/reference/` for reference artifacts, and `ROADMAP.md` for planned work and known
+   deviations. All are non-canonical.
+
+Resolve drift by updating the owning contract and implementation together, not by adding a second
+definition.
+
+## Canonical sources
+
+| File | Owns |
+| -- | -- |
+| `STYLE.md` | Coding conventions, logging rules, performance rules; prevails on style |
+| `STRUCTURE.md` | Layout, module ownership, public façade, internal import directions |
+| `STORAGE.md` | Storage ABI, backends, construction, transactions, footmarks and their wire format, timestamps, history, S3 ACL and metadata rules, digests |
+| `VALIDATION.md` | Input constraints at the URL, path, configuration, and retention boundaries |
+| `EXCEPTIONS.md` | Exception classes, raising conditions, chaining rules |
+| `CONFIG.md` | `make_storage` and retention settings, `TX_STORE_*` variables, defaults, secrets |
+| `TESTING.md` | Required coverage, harness rules, gates |
+| `SETUP.md` | Install, test, quality gates, diagrams, dependency policy, release, upgrade notes |
+
+## Task routing
+
+Read only the relevant sections; locate code from [STRUCTURE.md](STRUCTURE.md#layout).
+
+| Task | Primary | Also check |
+| -- | -- | -- |
+| Backend / primitive | `STORAGE.md` backends and primitives | `STRUCTURE.md` layout, `VALIDATION.md` URLs, `TESTING.md` |
+| Transaction / history / lock | `STORAGE.md` transactions and history | `EXCEPTIONS.md`, `TESTING.md` |
+| Footmark wire / timestamp | `STORAGE.md` footmarks and timestamps | `docs/reference/footmark.proto`, `TESTING.md` golden vectors |
+| S3 ACL / metadata | `STORAGE.md` S3 sections | `VALIDATION.md` canned ACLs, `CONFIG.md` |
+| URL / path rule | `VALIDATION.md` | `EXCEPTIONS.md`, `TESTING.md` |
+| Exception | `EXCEPTIONS.md` | Owning contract of the condition |
+| Argument / `TX_STORE_*` variable | `CONFIG.md` | `VALIDATION.md` environment values, `src/txstore/_env.py` |
+| Digest | `STORAGE.md` digests | `src/txstore/hexdigest.py` |
+| Import boundary | `STRUCTURE.md` dependencies | `tests/test_package.py`, `STYLE.md` |
+| Dependency change | `SETUP.md` dependency policy | `STRUCTURE.md` dependencies, `tests/test_package.py`, `.github/debian-test.sh` |
+| Bug fix | Owning contract + `EXCEPTIONS.md` | `TESTING.md` |
+| Tests | `TESTING.md` | Contract for the behavior under test |
+| Contract / doc edit | Writing rules below → owning contract | `scripts/check_docs.py`, `SETUP.md` quality gates |
+| Release | `SETUP.md` release | `.github/workflows/release.yml`, `ROADMAP.md` phases |
+| Quality gate / CI change | `SETUP.md` quality gates | `.github/workflows/ci.yml` |
+| Developer explanation / diagram | `docs/development/` | Owning root contract, `SETUP.md` diagrams |
+| User how-to / future behavior | `docs/guides/` / `ROADMAP.md` | Owning root contract before implementing |
+
+## Agent workflow
+
+1. Read only the owning contract sections from the routing table; open the module named in
+   [STRUCTURE.md](STRUCTURE.md#layout).
+2. Implement within the import directions of [STRUCTURE.md](STRUCTURE.md#dependencies). Write errors
+   as `condition → ExceptionClass` and link `EXCEPTIONS.md` instead of copying its table. A new
+   setting → [CONFIG.md](CONFIG.md#maintenance); a new public name →
+   [STRUCTURE.md](STRUCTURE.md#maintenance).
+3. Add the narrowest test that falsifies the change per [TESTING.md](TESTING.md#maintenance).
+4. Run the [SETUP.md quality gates](SETUP.md#quality-gates); contract and `docs/` edits also run
+   `uv run python scripts/check_docs.py`. CI runs the gates again.
+
+## Contract writing rules
+
+- One owner per fact. Link it as `→ FILE.md#anchor`; never copy its table or values.
+- Preamble opens with `Owns: <domain>. Routing → AGENTS.md.`, optionally followed by one short
+  orienting paragraph. No cross-document pointer chains.
+- Errors: `condition → ExceptionClass`; the class must be in `EXCEPTIONS.md` or be `ValueError` or
+  `NotImplementedError`.
+- Prefer tables; one fact per row. Narrative cells stay under ~300 characters: split rows rather
+  than pad. Enumerations (method lists, value lists) are exempt.
+- Tables use `| -- |` separator rows and unpadded cells; do not run a table aligner.
+- Bare imperative rules; no RFC 2119 keywords. Headings are sentence case and unique per file.
+- No TODOs or "current exception" notes in contracts; record them in
+  [ROADMAP.md known deviations](ROADMAP.md#known-deviations) and link.
+- Wrap prose at 100 columns; table rows are exempt. Prefer `→` shortcuts to sentences.
+- After any contract or `docs/` edit run `uv run python scripts/check_docs.py`.

txstore-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

txstore-0.1.0/CONFIG.md

@@ -0,0 +1,90 @@
+# Configuration contract
+
+Owns: `make_storage` and `HistoryRetention.from_env` settings, their `TX_STORE_*` environment
+variables, resolution order, defaults, and secrets. Routing →
+[AGENTS.md](AGENTS.md#canonical-sources).
+
+txstore's own configuration is keyword arguments and `TX_STORE_*` variables only; an application
+that exposes its own flags maps them to the keyword arguments below. The HTTP and S3 clients also
+honour their libraries' standard environment → [Secrets](#secrets).
+
+## Resolution
+
+| Rule | Behavior |
+| -- | -- |
+| Order | Explicit keyword argument, then the `TX_STORE_*` variable, then the default. A `None` argument counts as not given. |
+| Lazy read | A variable is read only when its argument is `None`, so an invalid value fails only a call that falls back to it. |
+| Readers | Only `make_storage` and `HistoryRetention.from_env` read variables; backend constructors and `HistoryRetention(...)` take explicit values only. |
+| Timing | Variables are read on each call, never at import. |
+| Values | Grammar and failures → [VALIDATION.md](VALIDATION.md#environment-values). |
+
+## Storage construction
+
+```python
+make_storage(url, *, create_path=False, verify_ssl=None, s3_access=None, s3_secret=None,
+             s3_default_acl=None, s3_bucket_acl=None)
+```
+
+→ [STORAGE.md](STORAGE.md#construction).
+
+| Argument | Variable | Default | Notes |
+| -- | -- | -- | -- |
+| `create_path` | none | `False` | Create the S3 bucket or FS root when missing. |
+| `verify_ssl` | `TX_STORE_VERIFY_SSL` | `True` | TLS verification for HTTP and S3; resolving to `False` logs a warning. |
+| `s3_access` | `TX_STORE_S3_ACCESS` | none | Secret; required for `s3://`. |
+| `s3_secret` | `TX_STORE_S3_SECRET` | none | Secret; required for `s3://`. |
+| `s3_default_acl` | `TX_STORE_S3_DEFAULT_ACL` | `none` (`NO_ACL`) | Object ACL for writes that pass none → [STORAGE.md](STORAGE.md#s3-acl-rules); values → [VALIDATION.md](VALIDATION.md#s3-canned-acls). |
+| `s3_bucket_acl` | `TX_STORE_S3_BUCKET_ACL` | `None` | Bucket ACL at creation → [STORAGE.md](STORAGE.md#construction). |
+
+## History retention
+
+`HistoryRetention.from_env(*, keep=None, max_age_days=None)` → [STORAGE.md](STORAGE.md#retention);
+values → [VALIDATION.md](VALIDATION.md#history-retention).
+
+| Argument | Variable | Default | Notes |
+| -- | -- | -- | -- |
+| `keep` | `TX_STORE_HISTORY_KEEP` | `20` (`HISTORY_KEEP_DEFAULT`) | Floor of protected ids → [STORAGE.md](STORAGE.md#retention). |
+| `max_age_days` | `TX_STORE_HISTORY_MAX_AGE_DAYS` | `90` (`HISTORY_MAX_AGE_DAYS_DEFAULT`) | Expiry age → [STORAGE.md](STORAGE.md#retention). |
+
+## Environment variables
+
+| Variable | Read by | Type |
+| -- | -- | -- |
+| `TX_STORE_VERIFY_SSL` | `make_storage` | Boolean |
+| `TX_STORE_S3_ACCESS` | `make_storage` | String, secret |
+| `TX_STORE_S3_SECRET` | `make_storage` | String, secret |
+| `TX_STORE_S3_DEFAULT_ACL` | `make_storage` | Object canned ACL or `none` |
+| `TX_STORE_S3_BUCKET_ACL` | `make_storage` | Bucket canned ACL |
+| `TX_STORE_HISTORY_KEEP` | `HistoryRetention.from_env` | Integer |
+| `TX_STORE_HISTORY_MAX_AGE_DAYS` | `HistoryRetention.from_env` | Integer |
+
+## Secrets
+
+- `TX_STORE_S3_ACCESS` and `TX_STORE_S3_SECRET`, and the matching arguments, are secrets: never
+  logged, never part of `repr`, never written to storage.
+- Credentials in a URL's userinfo (`user:password@host`) and its query string are replaced by `***`
+  in logs, `repr`, and exception messages; which URLs are accepted →
+  [VALIDATION.md](VALIDATION.md#storage-urls).
+- Percent-encode non-ASCII characters and `/`, `?`, `#`, and `@` in URL credentials; how an
+  unencoded one parses → [VALIDATION.md](VALIDATION.md#storage-urls). A URL whose authority does not
+  parse appears as `<unparseable URL>`; a password that parses as a host, port, and path is kept out
+  of logs only by the encoding.
+- Object keys are names, not secrets: backends name them in logs and exception messages, `;params`
+  included; HTTP join refusals that name only the base →
+  [VALIDATION.md](VALIDATION.md#http-url-join-safety). Carry credentials in URL userinfo, netrc, or
+  the S3 settings, never in a key.
+- Prefer the variables, or a caller's secret store, to literals in code.
+- The HTTP backend sends URL userinfo as Basic auth on URLs stripped of it, so no `requests` error
+  or chained cause quotes the credentials.
+- The HTTP backend sends `~/.netrc` (or `$NETRC`) credentials for the URL's host, overriding URL
+  userinfo, and routes through `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`; `REQUESTS_CA_BUNDLE`
+  replaces the CA store but never turns verification off. boto3 reads its own variables for S3.
+- Over plain `http://`, URL userinfo and netrc credentials travel as cleartext Basic auth; the HTTP
+  backend warns at construction when such a URL carries userinfo, and once per instance when it
+  sends netrc credentials. Use `https://` for an authenticated server.
+
+## Maintenance
+
+A new setting adds its keyword argument, its `_env` read with a `TX_STORE_` literal, and its row
+here in the same change; `scripts/check_docs.py` fails when a read variable has no
+[Environment variables](#environment-variables) row or a row names no read variable.

txstore-0.1.0/EXCEPTIONS.md

@@ -0,0 +1,46 @@
+# Exception contract
+
+Owns: exception classes, the conditions that raise them, and raising and chaining rules. Routing →
+[AGENTS.md](AGENTS.md#canonical-sources).
+
+## Rules
+
+- Contracts write a failure as `condition → ExceptionClass`.
+- Backend and storage-format failures raise `StorageException` or its subclass; a caller handling
+  `StorageException` handles every storage failure.
+- Wrap a library error (`ClientError`, `BotoCoreError`, `OSError`, `requests` errors) in
+  `StorageException` with `raise ... from exc`; never let it escape a public `Storage` method.
+  Errors from a `put_stream` source stream → [STORAGE.md](STORAGE.md#storage-abi).
+- Invalid arguments and configuration raise `ValueError`, except a URL that parses but cannot name a
+  storage (empty, HTTP or S3 without host, `s3://` without resolved keys): `make_storage` or the
+  backend constructor raises `StorageException` → [STORAGE.md](STORAGE.md#construction); a malformed
+  `s3://` path stays `ValueError` → [Other errors](#other-errors).
+- Unsupported backend operations → [Other errors](#other-errors).
+- Messages state the condition and the object; secrets never appear →
+  [CONFIG.md](CONFIG.md#secrets).
+
+## Storage exceptions
+
+| Exception | Module | Raised when |
+| -- | -- | -- |
+| `StorageException` | `txstore/base.py` | A backend operation, transaction, history, or lock step fails → [STORAGE.md](STORAGE.md#failure-semantics). |
+| `StorageNotFoundException` | `txstore/base.py` | The named object is missing → [STORAGE.md](STORAGE.md#storage-abi); subclass of `StorageException`. |
+
+## Other errors
+
+| Error | Raised when |
+| -- | -- |
+| `ValueError` | Unsupported URL scheme, an authority that does not parse, an `s3://` URL holding `@`, an `fs://` URL with an authority or a path that is not absolute, or a storage URL holding `?` or `#` → [VALIDATION.md](VALIDATION.md#storage-urls). |
+| `ValueError` | Empty S3 bucket, or an S3 prefix with an empty segment → [VALIDATION.md](VALIDATION.md#s3-url-path-split). |
+| `ValueError` | Unsafe HTTP join passed to `join_url`; `StorageHTTP` raises `StorageException` instead → [VALIDATION.md](VALIDATION.md#http-url-join-safety). |
+| `ValueError` | Invalid canned ACL → [VALIDATION.md](VALIDATION.md#s3-canned-acls). |
+| `ValueError` | Invalid environment value → [VALIDATION.md](VALIDATION.md#environment-values). |
+| `ValueError` | Out-of-range retention → [VALIDATION.md](VALIDATION.md#history-retention). |
+| `ValueError` | Out-of-range timestamp passed to `Timestamp`; one in a history record raises `StorageException` instead → [STORAGE.md](STORAGE.md#timestamps). |
+| `ValueError` | Out-of-range transaction id → [STORAGE.md](STORAGE.md#lifecycle). |
+| `NotImplementedError` | A read-only, write-only, or non-transactional backend is asked for an operation it lacks → [STORAGE.md](STORAGE.md#backends); not a `StorageException` → [ROADMAP.md](ROADMAP.md#known-deviations). |
+
+## Maintenance
+
+A new exception class adds a row to [Storage exceptions](#storage-exceptions) in the same change;
+`scripts/check_docs.py` fails when the table and the `class *Exception` definitions differ.

txstore-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Václav Vinklát
+
+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.

txstore-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: txstore
+Version: 0.1.0
+Summary: Unified object storage for Python: one interface over filesystem, S3, and HTTP, with transactions.
+Project-URL: Homepage, https://github.com/vinklat/txstore
+Project-URL: Source, https://github.com/vinklat/txstore
+Project-URL: Issues, https://github.com/vinklat/txstore/issues
+Project-URL: Documentation, https://github.com/vinklat/txstore/blob/main/docs/guides/README.md
+Project-URL: Changelog, https://github.com/vinklat/txstore/blob/main/SETUP.md#upgrade-notes
+Author: Václav Vinklát
+License-Expression: MIT
+License-File: LICENSE
+Keywords: atomic,digest,filesystem,object-storage,s3,storage,transaction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: System :: Filesystems
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: boto3<2,>=1.40
+Requires-Dist: botocore<2,>=1.40
+Requires-Dist: pyxattr<0.9,>=0.8.1
+Requires-Dist: requests<3,>=2.32
+Description-Content-Type: text/markdown
+
+# txstore
+
+Unified object storage for Python: one `Storage` interface over a local filesystem, S3-compatible
+buckets, and HTTP servers, selected by URL. Read, write, list, and stream objects between backends
+with the same calls, and on the filesystem and S3, optionally group writes into a transaction you
+commit, discard, or revert as one unit.
+
+Current version: **0.1.0**. Planned work → [ROADMAP.md](https://github.com/vinklat/txstore/blob/v0.1.0/ROADMAP.md).
+
+## Capabilities
+
+- One `Storage` interface over the filesystem (`fs://`), S3-compatible object stores (`s3://`),
+  read-only HTTP (`http://`, `https://`), and a write-only digest sink; `make_storage(url)` picks
+  the backend, so code switches storage by changing a URL.
+- Get, put, list, copy, move, and metadata calls that behave the same on every backend that supports
+  them.
+- Transactions on filesystem and S3: writes are staged as hidden footmark objects and committed,
+  discarded, or reverted together.
+- A transaction history at the storage root with age and count retention, revert of the latest
+  transaction, and cleanup of orphaned footmarks.
+- A cross-process writer lock: `flock` on the filesystem, conditional writes on S3.
+- Streamed transfers between storages that return MD5, SHA-1, SHA-256, and SHA-512 digests in one
+  pass.
+- S3 canned-ACL preservation across transactional copies and metadata rewrites.
+- Configuration by keyword arguments or `TX_STORE_*` environment variables; no CLI coupling.
+
+## Quick start
+
+### Install
+
+Released versions are published to [PyPI](https://pypi.org/project/txstore/):
+
+```bash
+pip install txstore
+```
+
+Settings → [CONFIG.md](https://github.com/vinklat/txstore/blob/v0.1.0/CONFIG.md); behavior → [STORAGE.md](https://github.com/vinklat/txstore/blob/v0.1.0/STORAGE.md).
+
+### Stream between backends
+
+Every backend is a `Storage` built from a URL, so moving data between technologies is one call.
+Download a web page and save it to disk, streamed in chunks rather than loaded into memory:
+
+```python
+from txstore import make_storage
+
+web = make_storage("https://docs.python.org/3")
+disk = make_storage("fs:///srv/data", create_path=True)
+
+digests = web.transfer("library/io.html", disk, "pages/io.html")
+print(digests)
+# {'MD5Sum': '...', 'SHA1': '...', 'SHA256': '...', 'SHA512': '...', 'Size': '180750'}
+```
+
+Swap either URL for `s3://...` and the same call uploads to or downloads from a bucket. HTTP storage
+is read-only and does not follow redirects; point the base URL at the final location.
+
+### Group writes into a transaction
+
+Writes to the filesystem or S3 can be grouped into a transaction:
+
+```python
+from txstore import HistoryRetention, TransactionHistory, make_storage, maybe_transaction
+
+storage = make_storage("fs:///srv/data", create_path=True)
+retention = HistoryRetention.from_env()
+
+# Write a data file and the manifest that points to it: both are applied together on commit.
+with maybe_transaction(storage, retention):
+    storage.put("reports/october.csv", b"day,orders\n1,42\n2,57\n")
+    storage.put("manifest.json", b'{"latest": "reports/october.csv"}')
+
+# A failure inside the block discards every staged write.
+try:
+    with maybe_transaction(storage, retention):
+        storage.put("reports/november.csv", b"day,orders\n1,???\n")
+        raise ValueError("validation failed")
+except ValueError:
+    assert not storage.exists("reports/november.csv")
+
+# Changed your mind later? Revert the last transaction as one unit.
+history = TransactionHistory(storage)
+print(
+    [(t.id, t.timestamp.to_json()) for t in history.load()]
+)  # [(1, '2026-10-23T19:08:36.024119Z')]
+history.revert_last()
+assert not storage.exists("manifest.json")
+```
+
+### Connect to S3
+
+On S3, pass the endpoint and bucket in the URL and the credentials as arguments or variables:
+
+```bash
+export TX_STORE_S3_ACCESS=... TX_STORE_S3_SECRET=...
+```
+
+```python
+storage = make_storage("s3://s3.example.com/bucket/prefix", s3_default_acl="private")
+```
+
+## Documentation
+
+| Location | Audience | Authority |
+| -- | -- | -- |
+| `/` root contract documents | Contributors and AI agents | Canonical |
+| [docs/guides/](https://github.com/vinklat/txstore/blob/v0.1.0/docs/guides/README.md) | Library users | Non-canonical guides and examples |
+| [docs/development/](https://github.com/vinklat/txstore/blob/v0.1.0/docs/development/README.md) | Contributors | Non-canonical code maps, flow diagrams, explanations |
+| [docs/reference/](https://github.com/vinklat/txstore/blob/v0.1.0/docs/reference/README.md) | Contributors and tooling | Non-canonical reference artifacts |
+
+## Canonical ownership
+
+Domain owners and agent navigation → [AGENTS.md](https://github.com/vinklat/txstore/blob/v0.1.0/AGENTS.md#canonical-sources).
+
+## Technology
+
+Python 3.13+, boto3, requests, pyxattr; pytest, moto, Ruff, mypy, and uv for development.
+
+## License
+
+MIT → [LICENSE](https://github.com/vinklat/txstore/blob/v0.1.0/LICENSE).

txstore-0.1.0/README.md

@@ -0,0 +1,121 @@
+# txstore
+
+Unified object storage for Python: one `Storage` interface over a local filesystem, S3-compatible
+buckets, and HTTP servers, selected by URL. Read, write, list, and stream objects between backends
+with the same calls, and on the filesystem and S3, optionally group writes into a transaction you
+commit, discard, or revert as one unit.
+
+Current version: **0.1.0**. Planned work → [ROADMAP.md](https://github.com/vinklat/txstore/blob/v0.1.0/ROADMAP.md).
+
+## Capabilities
+
+- One `Storage` interface over the filesystem (`fs://`), S3-compatible object stores (`s3://`),
+  read-only HTTP (`http://`, `https://`), and a write-only digest sink; `make_storage(url)` picks
+  the backend, so code switches storage by changing a URL.
+- Get, put, list, copy, move, and metadata calls that behave the same on every backend that supports
+  them.
+- Transactions on filesystem and S3: writes are staged as hidden footmark objects and committed,
+  discarded, or reverted together.
+- A transaction history at the storage root with age and count retention, revert of the latest
+  transaction, and cleanup of orphaned footmarks.
+- A cross-process writer lock: `flock` on the filesystem, conditional writes on S3.
+- Streamed transfers between storages that return MD5, SHA-1, SHA-256, and SHA-512 digests in one
+  pass.
+- S3 canned-ACL preservation across transactional copies and metadata rewrites.
+- Configuration by keyword arguments or `TX_STORE_*` environment variables; no CLI coupling.
+
+## Quick start
+
+### Install
+
+Released versions are published to [PyPI](https://pypi.org/project/txstore/):
+
+```bash
+pip install txstore
+```
+
+Settings → [CONFIG.md](https://github.com/vinklat/txstore/blob/v0.1.0/CONFIG.md); behavior → [STORAGE.md](https://github.com/vinklat/txstore/blob/v0.1.0/STORAGE.md).
+
+### Stream between backends
+
+Every backend is a `Storage` built from a URL, so moving data between technologies is one call.
+Download a web page and save it to disk, streamed in chunks rather than loaded into memory:
+
+```python
+from txstore import make_storage
+
+web = make_storage("https://docs.python.org/3")
+disk = make_storage("fs:///srv/data", create_path=True)
+
+digests = web.transfer("library/io.html", disk, "pages/io.html")
+print(digests)
+# {'MD5Sum': '...', 'SHA1': '...', 'SHA256': '...', 'SHA512': '...', 'Size': '180750'}
+```
+
+Swap either URL for `s3://...` and the same call uploads to or downloads from a bucket. HTTP storage
+is read-only and does not follow redirects; point the base URL at the final location.
+
+### Group writes into a transaction
+
+Writes to the filesystem or S3 can be grouped into a transaction:
+
+```python
+from txstore import HistoryRetention, TransactionHistory, make_storage, maybe_transaction
+
+storage = make_storage("fs:///srv/data", create_path=True)
+retention = HistoryRetention.from_env()
+
+# Write a data file and the manifest that points to it: both are applied together on commit.
+with maybe_transaction(storage, retention):
+    storage.put("reports/october.csv", b"day,orders\n1,42\n2,57\n")
+    storage.put("manifest.json", b'{"latest": "reports/october.csv"}')
+
+# A failure inside the block discards every staged write.
+try:
+    with maybe_transaction(storage, retention):
+        storage.put("reports/november.csv", b"day,orders\n1,???\n")
+        raise ValueError("validation failed")
+except ValueError:
+    assert not storage.exists("reports/november.csv")
+
+# Changed your mind later? Revert the last transaction as one unit.
+history = TransactionHistory(storage)
+print(
+    [(t.id, t.timestamp.to_json()) for t in history.load()]
+)  # [(1, '2026-10-23T19:08:36.024119Z')]
+history.revert_last()
+assert not storage.exists("manifest.json")
+```
+
+### Connect to S3
+
+On S3, pass the endpoint and bucket in the URL and the credentials as arguments or variables:
+
+```bash
+export TX_STORE_S3_ACCESS=... TX_STORE_S3_SECRET=...
+```
+
+```python
+storage = make_storage("s3://s3.example.com/bucket/prefix", s3_default_acl="private")
+```
+
+## Documentation
+
+| Location | Audience | Authority |
+| -- | -- | -- |
+| `/` root contract documents | Contributors and AI agents | Canonical |
+| [docs/guides/](https://github.com/vinklat/txstore/blob/v0.1.0/docs/guides/README.md) | Library users | Non-canonical guides and examples |
+| [docs/development/](https://github.com/vinklat/txstore/blob/v0.1.0/docs/development/README.md) | Contributors | Non-canonical code maps, flow diagrams, explanations |
+| [docs/reference/](https://github.com/vinklat/txstore/blob/v0.1.0/docs/reference/README.md) | Contributors and tooling | Non-canonical reference artifacts |
+
+## Canonical ownership
+
+Domain owners and agent navigation → [AGENTS.md](https://github.com/vinklat/txstore/blob/v0.1.0/AGENTS.md#canonical-sources).
+
+## Technology
+
+Python 3.13+, boto3, requests, pyxattr; pytest, moto, Ruff, mypy, and uv for development.
+
+## License
+
+MIT → [LICENSE](https://github.com/vinklat/txstore/blob/v0.1.0/LICENSE).

txstore-0.1.0/ROADMAP.md

@@ -0,0 +1,66 @@
+# txstore Roadmap
+
+## Phases
+
+| Phase | Status | Feature | Notes |
+| -- | -- | -- | -- |
+| 0.1.0 | ✅ | Initial public release | fs, S3, HTTP, and null backends; transactions, history, and retention; protobuf-free footmark codec; configuration by arguments or `TX_STORE_*` variables; Debian testing floors |
+| 0.2.0 | ⏳ | Debian package for forky | `python3-txstore` built with `dh-python` and `pybuild-plugin-pyproject`, autopkgtest running pytest, DEP-14 `debian/latest` branch, `debian/watch` on GitHub `vX.Y.Z` tags, `uversionmangle` mapping a PEP 440 suffix to `~` (`0.2.0rc1` → `0.2.0~rc1`) so a pre-release sorts before its final; ITP, sponsor or Debian Python Team, upload to unstable, migrate to testing before the forky freeze |
+| 1.0.0 | ⏳ | Stable API | Freeze the façade before the forky freeze so forky ships an API maintained for the whole release |
+
+## Ideas
+
+Unscheduled improvements, each waiting on a trigger. Promote a row to a phase when its trigger fires
+or the work is planned; drop it when it no longer applies.
+
+| Idea | Revisit when | Area |
+| -- | -- | -- |
+| Generated API reference in `docs/reference/` | The façade stabilizes (1.0.0) | [STRUCTURE.md](STRUCTURE.md#layout) |
+| GCS and Azure Blob backends | A user needs transactions on another object store | [STORAGE.md](STORAGE.md#backends) |
+| Async API; the per-thread writer-lock claim in `history_lock` then becomes per task (a `ContextVar` of a `frozenset`) | A caller needs concurrent transfers without threads | [STORAGE.md](STORAGE.md#storage-abi) |
+| Size cap or total deadline on `get` | A caller reads objects from an untrusted mirror: `get` holds the whole decoded body in memory on every backend, so a hostile HTTP origin can send an endless or gzip-bombed body; large reads use `get_stream` or `transfer` | [STORAGE.md](STORAGE.md#storage-abi) |
+| Renewable S3 lock | Critical sections approach the S3 lock TTL | [STORAGE.md](STORAGE.md#locking) |
+| Transactional writes as one manifest object | Partial commits on unreachable backends cost real data | [STORAGE.md](STORAGE.md#failure-semantics) |
+| Split `Storage` into readable, writable, and transactional interfaces | Before freezing the façade (1.0.0): the read-only and write-only mixins exist mainly to stub half of a 17-method ABC, and `TransactionNotSupportedMixin` only stubs transaction names on non-transactional backends; the split also adds the public transactional type that `is_transactional` narrows to, leaving `FootmarkMixin` an implementation mixin | [STORAGE.md](STORAGE.md#storage-abi) |
+| Inject `S3Client` into `StorageS3`; no network I/O in the constructor | A caller needs a fake client or lazy bucket creation; `create_bucket` runs in `__init__` today | [STORAGE.md](STORAGE.md#construction) |
+| Bind the bucket inside `S3Client` | The `S3Client` surface is next refactored: every call passes the same bucket, and `_LockObject` and `is_public` carry it too; `_LockObject` and its eight helpers then become one `_S3Lock` class | [STRUCTURE.md](STRUCTURE.md#layout) |
+| Move the canned-ACL choice sets, parsers, and public-ACL set beside the `S3Client` literals, behind an `AclPolicy` holding the default, bucket, reserved, and verify-public settings | The row above lands: ACL rules span `_s3_client`, `storage_s3`, `_s3_acl`, and `factory`, the four settings always travel together, and `acl: str \| None` means an octal mode on `fs` and a canned ACL on `s3` | [STORAGE.md](STORAGE.md#s3-acl-rules) |
+| Public commit hook: `maybe_transaction` calls `transaction_commit()`, which keeps its `bool` result, and `_commit_listed` goes away | A subclass needs a commit hook, or before freezing the façade (1.0.0): today the hook is the private `_commit_listed`. Lands with or after the row below, which retires the `hidden` listing `_commit_listed` hands the prune, so that listing never becomes public; a result tuple would also be truthy whatever `changed` is | [STORAGE.md](STORAGE.md#backend-primitives) |
+| Commit and discard from the transaction's own footmarks, not a full listing; auto-prune lists only when a record expires | Roots reach ~100k keys: every recorded write lists every key under the root while holding `history_lock`; this also retires the commit listing the prune reuses | [STORAGE.md](STORAGE.md#backend-primitives) |
+| Footmarks under a dedicated namespace prefix, so commit, revert, prune, and sweeps list only footmarks | The row above is not enough: a footmark layout change, cheapest before 1.0.0 | [STORAGE.md](STORAGE.md#footmarks) |
+| Mixin-owned public read, write, delete, and metadata pipeline; backends supply primitives only | With the interface split (1.0.0): backends still sequence path validation, overlay call, ACL sidecar, and metrics by hand; `StorageFS` calls `_validate_path` in every verb, `_obj_full` does not confine, three resolve-under-root checks differ (`validate_path`, `_obj_check_reserved`, `_obj_checked_footmark`), and `url.join_path` keeps an unused `no_root=True` branch | [STORAGE.md](STORAGE.md#backend-primitives) |
+| Reclaim as pure classifiers plus one path delete, with a separate prune-plan type | With the interface split (1.0.0): each `find_*` / forget pair re-classifies the paths it is handed, and `PruneResult` is both the plan and the outcome; `_prune_locked` / `_apply_prune` then move from `TransactionHistory` onto the plan type | [STORAGE.md](STORAGE.md#lifecycle) |
+| `TransactionHistory` takes a typed transactional port instead of any `Storage` | With the interface split (1.0.0): every history entry point (`history_lock`, `maybe_transaction`, and `TransactionHistory.load` / `save` / `revert_last` / `pop_last` / `prune`) re-checks `is_transactional`, `append` / `save` rely on the caller holding `history_lock`, and history reaches the private `_commit_listed`, `_transaction_abandon`, `_obj_lock`, `_obj_get_reserved`, and `_obj_put_reserved`; a raw `transaction_begin` auto-increments the instance id, which ignores history, while `maybe_transaction` takes `next_id` | [STORAGE.md](STORAGE.md#operations) |
+| Per-transaction object attributes owned by `FootmarkMixin` | The pipeline above lands: `StorageS3` keeps the ACL sidecar and three `in_transaction()` branches itself | [STORAGE.md](STORAGE.md#s3-acl-rules) |
+| Transaction overlay as an object `transaction_begin` installs and commit, discard, or revert remove, over a typed primitives port | The rows above land (1.0.0): seven overlay helpers branch on `in_transaction()`, `transaction_begin` resets the staged-footmark ledger by hand, and `FootmarkMixin` holds the lifecycle, overlay, and primitives in one class | [STORAGE.md](STORAGE.md#backend-primitives) |
+| The overlay records which of its own footmarks exist, so a staged write probes only the original | S3 syncs of thousands of puts: a staged put of a new key costs three HEAD requests (BACKUP, original, DELETE marker) under `history_lock` | [STORAGE.md](STORAGE.md#footmarks) |
+| A parsed storage-URL value type that renders redacted in `str`, `repr`, and messages, and owns the per-scheme host and userinfo rules | Before freezing the façade (1.0.0), a URL secret leaking at a new site, a third URL backend, or a new authority check outside `url.py`: `parse_storage_url` returns a public tuple, so redaction is applied per call site, `make_storage` and both URL backends re-parse the authority from strings, and each backend constructor repeats the query, host, and userinfo-stripping steps | [VALIDATION.md](VALIDATION.md#storage-urls) |
+| A `Footmarks` object on `TransactionModel` with `path_for(operation, path)` and `operation_of(token)`, still a `Sequence[str]` | With the overlay object above: two sites index or enumerate the token tuple by `ObjectOperation` value | [STORAGE.md](STORAGE.md#footmarks) |
+| A pooled `requests.Session` per `StorageHTTP` instance, closed through a backend `close()` lifecycle | A caller syncs many small objects from an https mirror: every request opens a new connection and TLS handshake, since `requests.request` builds a throwaway session; netrc stays read per request, so an edit takes effect at once | [STORAGE.md](STORAGE.md#backends) |
+| Lazy probe that the S3 endpoint enforces conditional writes | A user reports lost writes on a non-AWS endpoint; one probe on first lock, never in the constructor | [STORAGE.md](STORAGE.md#locking) |
+| `StorageFS` without symlink resolution on mutation or read | A shared root with untrusted writers: a directory swapped for a link between `validate_path` and a write, read, or unlink is followed; closing it needs one root object that opens, unlinks, renames, and stats by relative path through `openat`-style descriptors, replacing per-call-site checks | [VALIDATION.md](VALIDATION.md#filename-safety) |
+| `StorageFS` refuses a hard-linked object, footmark, or `.transactions.lock` | A shared root with untrusted writers where `fs.protected_hardlinks` is off or absent (macOS, the BSDs): a hard link to a file outside the root is read as an object and copied by commit and revert, and a linked `.transactions.lock` puts the history `flock` on the outside file, a lock denial of service but no write; refusing `st_nlink > 1` would also refuse roots backed up with hard-link snapshots | [VALIDATION.md](VALIDATION.md#filename-safety) |
+| `StorageFS` commit pre-flight that refuses a staged file whose path became a directory, and staged `mkdir` / `rmdir` | A caller stages a file at `d` and then `d/child` or `mkdir("d")` in one transaction: commit fails part-way in set order, and `mkdir` / `rmdir` act immediately | [STORAGE.md](STORAGE.md#failure-semantics) |
+| Reclaim `StorageFS` write temp files left by a crash | Leftovers accumulate; they are hidden from `list()` but never deleted | [STORAGE.md](STORAGE.md#backend-primitives) |
+| Fixed `0600` mode for `StorageFS` history and lock files | A root is shared with users who must not read the audit log; today the umask applies as for objects | [VALIDATION.md](VALIDATION.md#filename-safety) |
+| Maintenance CLI for transactional roots: retention prune, orphan check and sweep, temp-file cleanup, history inspection | Operators run these from ad-hoc scripts; the CLI needs its own entry point and a layout decision | [STORAGE.md](STORAGE.md#retention) |
+
+## Known deviations
+
+Implementation that does not yet meet a root contract. Contracts link here instead of carrying
+TODOs; remove a row when the code meets the rule.
+
+| Contract | Deviation | Source |
+| -- | -- | -- |
+| [STORAGE.md](STORAGE.md#recording-rules) | History append after commit, `save` after revert, and a prune's forget-then-rewrite are not atomic with the footmark lifecycle; a crash between them leaves committed objects without a record, or a record whose footmarks are gone. | `txstore/history.py` `maybe_transaction`, `revert_last`, `prune` |
+| [STORAGE.md](STORAGE.md#lifecycle) | Revert infers a created object from a PUT footmark without its BACKUP, so a BACKUP removed outside txstore (by hand, an S3 lifecycle rule, a peer's orphan sweep during a raw transaction) makes revert delete the original; an explicit created marker in the footmark set would close it. | `txstore/transaction.py` `transaction_revert` |
+| [STORAGE.md](STORAGE.md#lifecycle) | Off `fs`, commit checks a staged BACKUP footmark only against its listing, so one removed outside txstore after the listing goes unnoticed and commit overwrites the only other copy of its original. | `txstore/transaction.py` `_commit_listed`, `_obj_checked_footmark` |
+| [STORAGE.md](STORAGE.md#lifecycle) | Commit takes a staged footmark the listing lacks for an alias once `_obj_exists` finds it, so on `fs` one replaced outside txstore by a directory of its name is skipped instead of refused. | `txstore/transaction.py` `_commit_listed` |
+| [STORAGE.md](STORAGE.md#failure-semantics) | Transaction atomicity is best-effort when the backend fails mid-commit or mid-discard; remote state may be left partially updated. | `txstore/transaction.py` `FootmarkMixin` |
+| [STORAGE.md](STORAGE.md#failure-semantics) | `maybe_transaction` reads the history before beginning, so a malformed `.transactions.json` blocks every transactional write; nothing bypasses history recording. | `txstore/history.py` `maybe_transaction` |
+| [STORAGE.md](STORAGE.md#s3-acl-rules) | A copy without a sidecar entry carries only a group canned ACL; `private`, `bucket-owner-*`, or `aws-exec-read` on a key not written in the transaction is reset by a revert, which always copies outside a transaction, or by any other copy outside a transaction. | `txstore/storage_s3.py` `_obj_copy` |
+| [STORAGE.md](STORAGE.md#locking) | `history_lock` spans the whole `maybe_transaction` body, including bulk transfers, and the whole `prune` run; a peer writer that waits past the S3 acquire timeout fails instead of queueing. | `txstore/history.py` `maybe_transaction`, `prune` |
+| [STORAGE.md](STORAGE.md#locking) | Expiry is judged by the breaker's clock against the holder's stamp, so a clock skew approaching the 12 h TTL breaks a live lock early or keeps an expired one. | `txstore/_s3_lock.py` `_body_is_breakable` |
+| [STORAGE.md](STORAGE.md#locking) | The S3 lock stamps `expires_at` once at acquire and never renews it, so a critical section outliving the TTL can be taken over while its holder still runs; a crashed holder must be cleared by deleting `.transactions.lock`. | `txstore/_s3_lock.py` `s3_lock` |
+| [STORAGE.md](STORAGE.md#locking) | A lock write that commits while every botocore attempt fails in transport aborts the acquire with the body left inside its TTL; peers wait for it to expire. | `txstore/_s3_lock.py` `_try_create`, `_try_take_over` |
+| [EXCEPTIONS.md](EXCEPTIONS.md#rules) | `NotImplementedError` from a capability stub is not a `StorageException`, so a caller handling only `StorageException` does not catch it. | `txstore/_capabilities.py` |