mbmerge 1.1.0__tar.gz

mbmerge-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: MIT
+name: Tests and distributions
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+    inputs:
+      release_tag:
+        description: Optional v<VERSION> tag to validate before publishing
+        required: false
+        type: string
+        default: ''
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ['3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            requirements.txt
+      - name: Install project and runtime dependencies
+        run: python -m pip install -e .
+      - name: Run synthetic and SIGKILL recovery tests
+        run: python -m unittest discover -s tests -v
+      - name: Check installed command and module entry points
+        run: |
+          mbmerge --version
+          python -m mbmerge --version
+
+  distributions:
+    name: Build, inspect and install distributions
+    runs-on: ubuntu-latest
+    env:
+      # Treat a release tag as data, never interpolate it directly into shell code.
+      RELEASE_TAG: ${{ inputs.release_tag }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            requirements.txt
+      - name: Install build and metadata validation tools
+        run: python -m pip install '.[release]'
+      - name: Build wheel and source distribution
+        run: python -m build
+      - name: Validate metadata, source version and optional release tag
+        run: |
+          python -m twine check --strict dist/*
+          python tools/check_release.py --dist-dir dist --tag "$RELEASE_TAG"
+      - name: Install the exact wheel being published
+        run: python -m pip install --force-reinstall --no-deps dist/*.whl
+      - name: Exercise installed wheel without checkout imports
+        run: python -I tools/smoke_installed.py
+      - name: Build a wheel from the source distribution too
+        run: python -m pip wheel --no-deps dist/*.tar.gz --wheel-dir rebuilt
+      - name: Exercise the rebuilt wheel
+        run: |
+          python -m pip install --force-reinstall --no-deps rebuilt/*.whl
+          python -I tools/smoke_installed.py
+      - name: Store only the validated release distributions
+        uses: actions/upload-artifact@v7.0.2
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error

mbmerge-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+name: Publish release to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  checks:
+    # Stable releases publish here; prereleases remain available on GitHub.
+    if: ${{ !github.event.release.prerelease }}
+    uses: ./.github/workflows/ci.yml
+    with:
+      release_tag: ${{ github.event.release.tag_name }}
+
+  publish:
+    # Private evaluation never publishes to a public package index.
+    if: ${{ !github.event.repository.private && vars.PYPI_PUBLISH_ENABLED == 'true' }}
+    name: Publish validated artifacts
+    needs: checks
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mbmerge/
+    permissions:
+      id-token: write
+    steps:
+      # Publishing has no source checkout or build commands. It receives the
+      # exact artifacts from this run after all reusable CI jobs have succeeded.
+      - uses: actions/download-artifact@v8.0.2
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish using PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

mbmerge-1.1.0/.github/workflows/testpypi.yml

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+name: Publish manually to TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: testpypi-publish
+  cancel-in-progress: false
+
+jobs:
+  checks:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    # Private evaluation never publishes to a public package index.
+    if: ${{ !github.event.repository.private && vars.TESTPYPI_PUBLISH_ENABLED == 'true' }}
+    needs: checks
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/mbmerge/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.2
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish using TestPyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

mbmerge-1.1.0/.gitignore

@@ -0,0 +1,76 @@
+# Version in Git:
+#   Python source, tests, examples, tools/, requirements.txt, and this .gitignore.
+#   pyproject.toml, MANIFEST.in, and .github/workflows/.
+#   README*.md, TEST_REPORT*.md, ARCHITECTURE*.md, LICENSE*.md, docs/images/, and the demo PNG previews.
+#   The synthetic WebP/PNG MBTiles fixtures explicitly allowed below.
+#   Curated BENCHMARK.json, TEST_RESULTS.txt, and release SHA256SUMS.
+#
+# Keep real datasets, generated outputs, local logs, and credentials out of Git.
+# Ignoring a file does not remove it if it has already been committed.
+
+# Real inputs and generated raster archives. Only bundled synthetic fixtures ship.
+*.mbtiles
+!/demo/source_a.mbtiles
+!/demo/source_b.mbtiles
+!/demo/png/source_a.mbtiles
+!/demo/png/source_b.mbtiles
+*.db
+*.sqlite
+*.sqlite3
+
+# SQLite sidecars and the merger's runtime lock. Never commit or delete live locks.
+*-wal
+*-shm
+*-journal
+*.merge.lock
+
+# Local datasets, scratch files, and generated demo sets.
+/data/
+/inputs/
+/outputs/
+/work/
+/new_demo*/
+
+# Run logs and local benchmark output. Curated reports above remain versioned.
+*.log
+*.jsonl
+/benchmark*.local.json
+
+# Python environments, bytecode, caches, test coverage, and package builds.
+.venv*/
+venv/
+env/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.egg-info/
+/build/
+/dist/
+
+# Local environment settings. A sanitized example can be committed.
+.env
+.env.*
+!.env.example
+
+# Editor and operating-system files.
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Distribute release archives as downloads rather than repository source files.
+*.zip
+*.tar.gz
+
+# Wheel rebuilt from an sdist during release verification.
+/rebuilt/

mbmerge-1.1.0/ARCHITECTURE.cs.md

@@ -0,0 +1,110 @@
+# Architektura a údržba
+
+[English](ARCHITECTURE.md) | **Čeština**
+
+Tento dokument vysvětluje pravidla v [merge_mbtiles.py](merge_mbtiles.py). Podporované vstupy a příkazy popisuje [README](README.cs.md). Komentáře a docstringy ve zdrojovém kódu jsou anglicky.
+
+## Mapa kódu
+
+| Oblast | Vstupní funkce | Odpovědnost |
+|---|---|---|
+| CLI | `parser`, `main` | Ověření limitů, signály, výběr příkazu a návratové kódy. |
+| Řízení běhu | `merge`, `collect_inputs`, `output_lock` | Pořadí zdrojů, vyloučení druhého writeru, kontrola historie a dokončení aktivního zdroje. |
+| Zdrojové snapshoty | `source`, `token`, `assert_static`, `digest`, `preflight` | Čtecí zámky, detekce změn a ověření všech historických příspěvků. |
+| Příprava databáze | `open_output`, `connection_limits` | Schéma, nastavení výstupu a omezení bufferů spojení. |
+| Příprava dávky | `read_batch`, `validate_schema` | Indexované stránkování a výběr podle délek před načtením blobů. |
+| Obrazové workery | `bounded_results`, `process_tile`, `decode`, `encode` | Backpressure, validace, kopírování, převod a skládání dlaždic. |
+| Trvalý stav | `import_source`, `update_metadata`, `_commit`, `checkpoint` | Společný commit pixelů a postupu, potom checkpoint WAL. |
+| Kontroly | `status`, `verify` | Malá evidence nebo výslovný průchod SQLite a obrázků výstupu. |
+
+Úloha má tvar `(z, x, y, new_bytes, old_bytes_or_None)`, výsledek `(z, x, y, output_bytes)`. Souřadnice jsou všude TMS. Pořadí hodnot v Python n-ticích odpovídá sloupcům SQL; při změně je potřeba ověřit všechny producenty i konzumenty.
+
+## Jediný writer a pořadí zdrojů
+
+Hlavní proces vlastní zdrojové i jediné výstupní SQLite spojení. Workery vznikají přes `spawn` a dostávají pouze bajty a parametry. Nepředávej jim SQLite spojení a nepřepínej na `fork` s otevřenými spojeními.
+
+Paralelně běží jen dlaždice aktuálního zdroje. Jejich klíče jsou unikátní, takže pořadí dokončení workerů výsledek nemění. Pořadí zdrojů ho mění: `Image.alpha_composite(existing_output, new_source)` kreslí nový zdroj přes dosavadní obraz. Aktivní zdroj se musí dokončit před novým, i když ho další příkaz neuvede.
+
+Výstupní zámek je kooperativní a drží se po celý běh. Jeho soubor zůstává po uvolnění na disku; smazání drženého zámku by umožnilo druhému procesu zamknout jiný inode. Přímé změny výstupu jinými nástroji nejsou podporované.
+
+## Stav importu a obnova po pádu
+
+```mermaid
+stateDiagram-v2
+    [*] --> active: Registrace cesty a fingerprintu
+    active --> active: Commit dávky a posledního klíče
+    active --> complete: Ověření finálního SHA-256
+    active --> tainted: Změna zdroje během importu
+```
+
+`active` bez posledního klíče znamená, že se nepotvrdila žádná dávka dlaždic. `complete` znamená úspěšnou finální kontrolu hashe. `tainted` blokuje další import a vyžaduje nový výstup; smazání příznaku neopraví pixely načtené z nestabilního zdroje.
+
+Neshoda SHA při preflightu je odlišná: import ještě nezačal, takže výstup neoznačí jako tainted. Obnovení přesných původních bajtů umožní pokračovat.
+
+Dávka má následující průběh:
+
+1. Načíst klíče a délky pomocí `(z,x,y) > last_committed_key`, bez `OFFSET`.
+2. Najít překryvy malou dočasnou tabulkou a indexovaným vyhledáváním ve výstupu.
+3. Vybrat souvislý prefix podle počtu a bajtového rozpočtu; načíst jen jeho bloby.
+4. Zahájit `BEGIN IMMEDIATE`, spustit omezené úlohy a zapisovat výsledky SQL dávkami.
+5. Znovu ověřit stabilitu zdroje. Aktualizovat poslední klíč, počty, zoomy, rozsahy a metadata.
+6. Potvrdit **všechny** tyto změny společně. Potom mimo transakci zavolat `wal_checkpoint(TRUNCATE)`.
+
+Pád před commitem vrátí celou dávku; po commitu se dávka přeskočí. Opakované nanesení potvrzené poloprůhledné vrstvy by změnilo pixely. Retry proto nesmí takovou dávku znovu skládat. Pokud checkpoint blokuje čtečka, předchozí dávka již zůstala potvrzená. Import zastaví a naváže po zavření čtečky.
+
+Registrace a dokončení zdroje jsou samostatné malé transakce. Trvale uložený poslední klíč označuje potvrzené dlaždice, nikoli odeslané nebo právě dokončené úlohy. Chyba SQL/workeru vrátí aktuální dávku a ponechá starší commity.
+
+## Účtování paměti
+
+`read_batch` počítá zdrojové bajty, staré bajty výstupu a rezervu výsledku. Překryv nebo možný převod formátu rezervuje `max_tile_mib`. Jedinečná dlaždice deklarovaná ve formátu výstupu může rezervovat původní velikost: worker deklaraci ověří před kopírováním. Při změně rychlé kopírovací větve toto ověření zachovej.
+
+`batch_size` omezuje režii klíčů a řádků, `batch_mib` kódovaná data. Čtení délek před bloby brání načtení příliš velké dlaždice ještě před odmítnutím. Pevné pořadí joinu brání plnému průchodu výstupu pro každou dávku.
+
+`bounded_results` odešle nejvýše `max_inflight` futures včetně hotových neodebraných výsledků. Výsledky předá před doplněním poolu, takže pomalý SQL writer zpomalí producenty. Nenahrazuj ho načtením všech úloh přes `map`, neomezenou frontou ani seznamem všech výsledků. SQL buffery mají také početní a bajtový limit; před další dávkou se stará uvolní.
+
+Rozpočty nejsou tvrdým limitem RSS. Přidávají se kopie při serializaci, procesy Python/Pillow, dekódované RGBA buffery, metadata PNG a paměť nativních kodeků. Rozměry a bloby jsou omezené, SQLite cache mají limit, mmap je vypnutý a dočasné tabulky mohou přetéct na disk. Absolutní celkový limit nastavuje provozní prostředí.
+
+## Integrita zdrojů a formáty
+
+Čtecí transakce zdroje zahrnuje první hash, import i poslední hash. Po `BEGIN` se čte schéma, aby se skutečně získal sdílený zámek. WAL zdroje se odmítají, protože samotný hlavní soubor nemusí obsahovat celý jejich viditelný stav. `immutable=1` není bezpečná optimalizace: obchází potřebné zamykání.
+
+Stat tokeny zachytí výměnu zařízení/inodu a změnu velikosti, mtime či ctime. ctime se může změnit i při změně metadat, což záměrně vede ke konzervativnímu zastavení. SHA-256 ověřuje obsah i při obnovení velikosti/mtime. Vstupy musí být offline a neměnné; přímé zápisy obcházející SQLite zámky nejsou podporované.
+
+Signatury a hlavičky se ověřují před alokací pixelů v Pillow. WebP kontroluje VP8X i rozměry VP8/VP8L, PNG hlavičku IHDR, hranice/CRC chunků a statický obraz. Pillow potom dekóduje podporovaný 8bitový zobrazovací rastr do RGBA. 16bitové PNG a animace se výslovně odmítají. Merger nemění velikost dlaždic, nespravuje barevné profily, nereprojektuje ani neořezává polygonem.
+
+Jedinečná dlaždice se kopíruje bajtově jen při shodě s formátem výstupu. Ostatní se převádějí; překryvy se skládají a bezztrátově kódují. Již ztracené pixely původního ztrátového vstupu nelze obnovit. Nastavení komprese platí pro nově kódované dlaždice, nikoli původní kopírované bajty.
+
+## Evidence, metadata a kompatibilita
+
+| Tabulka | Význam |
+|---|---|
+| `tiles` | Standardní souřadnice MBTiles a jeden zvolený formát obrázků. |
+| `metadata` | Zobrazovací metadata aktualizovaná s potvrzenými pixely. |
+| `_merge_sources` | Pořadí, cesta/hash/stat token, stav, poslední klíč a průběžné statistiky zdroje. |
+| `_merge_config` | Verze schématu a nastavení výstupu/kodéru. |
+| `_merge_attributions` | Unikátní atribuce s omezenou souhrnnou velikostí. |
+
+`tile_count` počítá příspěvky zdrojů, nikoli unikátní výstupní dlaždice. Zoomy vycházejí z potvrzených klíčů. Bounds používají validní deklaraci nebo celé importované dlaždice, bez ořezu podle alfa kanálu. Celková metadata agregují malou evidenci a neprocházejí stále celou tabulku dlaždic. Deklarovaný rozsah rozpracovaného zdroje může zahrnovat dosud nenačtené části.
+
+`VERSION` programu a `SCHEMA_VERSION` mají odlišný účel. Verze 1.1 interpretuje schéma 1 jako WebP a trvale ho povýší na 2 při nejbližším úspěšném commitu dávky nebo finálních metadat. Verze 1.0 schéma 2 odmítne, aby nepoškodila PNG výstup původním WebP kódem. Formát, velikost dlaždic a aktivní kompresní parametr jsou při resume pevné.
+
+U nekompatibilní změny nejdřív stanov migraci a chování starších klientů. Tato nastavení se během života archivu nesmějí tiše přepnout.
+
+## Testy a bezpečné rozšiřování
+
+- [tests/test_merge.py](tests/test_merge.py) ověřuje pořadí, metadata, zámky, detekci změn, rollback a skutečný SIGKILL kolem commitu pro oba formáty.
+- [tests/test_png.py](tests/test_png.py) ověřuje smíšené formáty, pixely, strukturu/režimy PNG, velikost výsledků, jednotný formát a migraci evidence.
+- [examples/create_demo.py](examples/create_demo.py) vytváří nezávislé 512px vstupy a očekávaný obraz přímo přes Pillow.
+- [tests/benchmark_memory.py](tests/benchmark_memory.py) měří strom procesů CLI, bez přípravy dat a měřicího procesu. Vzorkuje RSS, takže může započítat sdílené stránky vícekrát a minout krátké špičky.
+
+Před změnou dávkování, pořadí, kódování nebo schématu spusť `python -m unittest discover -s tests -v`. Zachovej pixelové porovnání, kontrolu přeskočení potvrzené dávky, rezervu výsledku převodu a crash testy. Změna toku dat či spotřeby prostředků vyžaduje nové měření na reprezentativních datech; samotné komentáře nové výkonnostní měření nepotřebují. Při přípravě release archivu po poslední změně všech souborů přegeneruj `SHA256SUMS`.
+
+Kód i související projektová dokumentace jsou zveřejněny pod [licencí MIT](LICENSE.md).
+
+## Balíčkování a vydávání
+
+[mbmerge.py](mbmerge.py) zpřístupňuje `python -m mbmerge` a `__version__`. Nainstalovaný příkaz používá stejný `main()` v `merge_mbtiles.py`; původní skript zůstává kompatibilní. [pyproject.toml](pyproject.toml) balí výslovně tyto dva moduly, dynamicky načítá VERSION a přebírá závislost Pillow z requirements.txt.
+
+[MANIFEST.in](MANIFEST.in) přidává zdrojové testy/dokumentaci a jen čtyři jmenované syntetické databáze, nikdy obecný glob všech MBTiles. [tools/check_release.py](tools/check_release.py) ověřuje identitu zdrojů, wheelu, sdistu a produkční tag. [tools/smoke_installed.py](tools/smoke_installed.py) záměrně používá nainstalovaný wheel, izolovaný Python a dočasný pracovní adresář CLI.
+
+[RELEASING.cs.md](RELEASING.cs.md) popisuje znovupoužitelné CI a oddělené publikační joby s OIDC. Při změně balíčkování či vstupních bodů znovu sestav a vyzkoušej wheel i wheel ze sdistu; samotné zdrojové testy chybějící soubory distribuce neodhalí.

mbmerge-1.1.0/ARCHITECTURE.md

@@ -0,0 +1,110 @@
+# Architecture and maintenance
+
+**English** | [Čeština](ARCHITECTURE.cs.md)
+
+This guide explains the invariants behind [merge_mbtiles.py](merge_mbtiles.py). Read the [README](README.md) for supported inputs and commands. Source comments and docstrings are in English.
+
+## Code map
+
+| Area | Entry points | Responsibility |
+|---|---|---|
+| CLI | `parser`, `main` | Validate limits, handle signals, dispatch commands and report exit codes. |
+| Run orchestration | `merge`, `collect_inputs`, `output_lock` | Resolve source order, exclude other writers, validate history and finish active sources first. |
+| Source snapshots | `source`, `token`, `assert_static`, `digest`, `preflight` | Keep read locks, detect changes and verify every historical contribution. |
+| Database setup | `open_output`, `connection_limits` | Create the managed schema, resolve encoding settings and constrain connection buffers. |
+| Batch preparation | `read_batch`, `validate_schema` | Use indexed keyset reads and length-based selection before fetching bounded blobs. |
+| Image workers | `bounded_results`, `process_tile`, `decode`, `encode` | Apply backpressure, validate images, copy/transcode or composite tiles. |
+| Durable state | `import_source`, `update_metadata`, `_commit`, `checkpoint` | Commit pixels and progress together, then checkpoint WAL. |
+| Inspection | `status`, `verify` | Inspect the small ledger or explicitly scan SQLite/output images. |
+
+The job tuple is `(z, x, y, new_bytes, old_bytes_or_None)`; the result is `(z, x, y, output_bytes)`. Coordinates are TMS throughout. The Python tuple order mirrors SQL column order; changing one requires checking all producers and consumers.
+
+## One writer and ordered sources
+
+The parent process owns both the source connection and the single output connection. Workers are created with `spawn` and receive bytes/parameters only. Never pass SQLite handles to the pool or switch to `fork` with live connections.
+
+Only tiles from the current source run in parallel. Its keys are unique, so worker completion order does not affect the result. Source order does: `Image.alpha_composite(existing_output, new_source)` puts the new source over the old one. An active source must finish before any new source, including when omitted from the next CLI invocation.
+
+The output lock is cooperative and covers the whole run. Its file remains after release; unlinking a held lock could allow a second process to lock a different inode. Direct output edits by other tools are outside the contract.
+
+## Import state and crash recovery
+
+```mermaid
+stateDiagram-v2
+    [*] --> active: Register path and fingerprint
+    active --> active: Commit a batch and its last key
+    active --> complete: Verify final SHA-256
+    active --> tainted: Source changes during import
+```
+
+`active` with no last key means no tile batch has committed. `complete` means the source passed its final hash check. `tainted` blocks future imports and requires rebuilding to a new output; clearing the flag does not repair pixels already read from an unstable source.
+
+A preflight SHA mismatch is different: importing has not started, so it does not taint the output. Restoring the exact original source bytes permits resume.
+
+Each batch follows this order:
+
+1. Read keys and encoded lengths using `(z,x,y) > last_committed_key`, with no `OFFSET`.
+2. Find output overlaps using the small temporary key table and indexed output lookups.
+3. Choose a contiguous prefix fitting count and byte limits; fetch only that prefix's blobs.
+4. Start `BEGIN IMMEDIATE`, run bounded worker jobs and write their results in SQL batches.
+5. Recheck source stability. Update its last key, counts, zooms, extents and output metadata.
+6. Commit **all** those changes together. Then call `wal_checkpoint(TRUNCATE)` outside the transaction.
+
+Before commit, a crash rolls back the whole batch. After commit, resume skips it. Replaying a committed translucent layer would change the pixels; do not implement a retry that composites it again. If checkpointing fails because a reader pins WAL pages, the preceding batch is still committed. Stop and resume after closing the reader.
+
+Source registration and completion are small separate transactions. The persisted last key always refers to committed source tiles, never submitted or merely completed worker jobs. SQL/worker failure rolls back the current batch and leaves earlier commits intact.
+
+## Memory accounting
+
+`read_batch` computes a budget for encoded source bytes, existing output bytes and reserved result bytes. Overlaps and possible format conversions reserve `max_tile_mib` for the result. A unique tile declared in the selected output format can reserve its original size because the worker checks the declaration before copying bytes. Keep that validation if changing the fast path.
+
+Both `batch_size` and `batch_mib` matter. The former bounds key/row overhead; the latter bounds encoded data. Querying lengths first prevents a single oversized source blob from being loaded before rejection. Fixed join order avoids a full output scan for each batch.
+
+`bounded_results` submits at most `max_inflight` futures, including finished results not yet consumed. It yields results before refilling the pool, so slow SQL writes apply backpressure. Do not replace it with an eager `map`, an unbounded queue, or a list of all results. SQL result buffers also have count/byte limits; previous batches are released before reading the next one.
+
+These budgets are not a hard RSS cap. Serialization copies, Python/Pillow processes, decoded RGBA buffers, PNG metadata handling and native codec workspace add overhead. Image dimensions and blob sizes remain bounded, SQLite caches are limited, mmap is disabled, and temporary tables can spill to disk. A hard total limit belongs to the runtime environment.
+
+## Source integrity and format validation
+
+A source read transaction spans initial hash, importing and final hash. `BEGIN` is followed by a schema read to actually acquire the shared lock. WAL sources are rejected because their visible state may not be represented by the main-file hash. Do not add `immutable=1` as an optimization: it bypasses the locking relied on here.
+
+Stat tokens detect device/inode replacement and size/mtime/ctime changes at boundaries. ctime may also change for metadata-only edits, intentionally causing a conservative stop. SHA-256 checks content, including changes hidden by restoring size/mtime. Inputs must remain offline and immutable; raw writes that bypass SQLite locks are unsupported.
+
+Signature/header checks happen before Pillow allocates pixels. WebP checks both VP8X canvas and VP8/VP8L bitstream dimensions; PNG checks IHDR, chunk boundaries/CRCs and static-image constraints. Pillow then decodes the supported 8-bit display image into RGBA. Sixteen-bit PNG and animations are explicitly rejected. The merger does not resize tiles, manage color profiles, reproject data or perform polygon clipping.
+
+A unique tile is copied byte-for-byte only when its format matches the selected output. Other unique tiles are transcoded; overlaps are composited and encoded losslessly. Original lossy input pixels cannot be recovered. Compression settings affect newly encoded tiles, not copied originals.
+
+## Ledger, metadata and compatibility
+
+| Table | Meaning |
+|---|---|
+| `tiles` | Standard MBTiles coordinates and one selected encoded format. |
+| `metadata` | Standard display metadata, updated with committed pixels. |
+| `_merge_sources` | Source priority, path/hash/stat token, state, last key and incremental statistics. |
+| `_merge_config` | Schema version and output/encoder settings. |
+| `_merge_attributions` | Unique attribution strings with a bounded aggregate size. |
+
+`tile_count` counts source contributions, not distinct output tiles. Zooms come from committed keys. Bounds use valid declared source bounds or full imported tile extents, without alpha-edge cropping. Global metadata aggregates the small ledger instead of repeatedly scanning the tiles table. During a partial import, declared source bounds may include its not-yet-imported area.
+
+Program `VERSION` and `SCHEMA_VERSION` serve different purposes. Version 1.1 reads legacy schema 1 as WebP and durably upgrades it to schema 2 in the next successful batch/final metadata transaction. Version 1.0 refuses schema 2, protecting PNG outputs from old WebP-only code. Output format, tile size and the active encoder setting are fixed on resume.
+
+For an incompatible change, define migration/old-client behavior before writing new data. Never silently change these settings halfway through an archive.
+
+## Tests and safe extension
+
+- [tests/test_merge.py](tests/test_merge.py) covers ordering, metadata, locks, change detection, worker rollback and actual SIGKILL at commit boundaries for both formats.
+- [tests/test_png.py](tests/test_png.py) covers mixed formats, pixel fidelity, PNG structure/modes, encoding limits, format consistency and legacy-ledger migration.
+- [examples/create_demo.py](examples/create_demo.py) builds independent 512px fixtures and an expected image using Pillow directly.
+- [tests/benchmark_memory.py](tests/benchmark_memory.py) measures the CLI process tree, excluding fixture creation and the harness. It samples RSS, which can count shared pages twice and omit brief peaks.
+
+Before changing batching, source order, encoding or schema, run `python -m unittest discover -s tests -v`. Keep exact pixel comparisons, committed-batch replay checks, format-conversion byte reservations and crash tests. If dataflow/resource use changes, rerun the benchmark with representative inputs; comments-only changes do not require new performance measurements. Regenerate `SHA256SUMS` when preparing a release archive after all final file changes.
+
+The code and accompanying project documentation are under the [MIT license](LICENSE.md).
+
+## Packaging and release entry points
+
+[mbmerge.py](mbmerge.py) provides `python -m mbmerge` and `__version__`; the installed command points to the same `main()` in `merge_mbtiles.py`. The original script stays compatible. [pyproject.toml](pyproject.toml) explicitly packages these two modules, reads VERSION dynamically and reads Pillow requirements from requirements.txt.
+
+[MANIFEST.in](MANIFEST.in) includes source tests/docs and only four named synthetic databases; it never glob-includes arbitrary MBTiles. [tools/check_release.py](tools/check_release.py) checks source/wheel/sdist identity and production tags. [tools/smoke_installed.py](tools/smoke_installed.py) deliberately imports from an installed wheel, with isolated Python and a temporary CLI working directory.
+
+See [RELEASING.md](RELEASING.md) for the reusable CI workflow and the separate OIDC-only publishing jobs. Changing packaging or entry points requires rebuilding and exercising both the wheel and a wheel rebuilt from sdist; source tests alone cannot detect missing distribution files.

mbmerge-1.1.0/BENCHMARK.json

@@ -0,0 +1,93 @@
+{
+  "cli_version": "1.1.0",
+  "benchmarks": [
+    {
+      "python": "3.12.14",
+      "sqlite": "3.53.1",
+      "platform": "macOS-27.2-arm64-arm-64bit",
+      "webp": "1.6.0",
+      "workers": 4,
+      "tile_size": 512,
+      "output_format": "webp",
+      "measurement": "sampled simultaneous sum of parent+descendant RSS; shared pages counted multiple times; excludes filesystem page cache",
+      "runs": [
+        {
+          "tiles_per_source": 64,
+          "contributions": 128,
+          "input_bytes": 101228544,
+          "output_bytes": 51412992,
+          "elapsed_seconds": 4.14,
+          "peak_tree_rss_mib": 423.67,
+          "max_processes": 6,
+          "pipeline": {
+            "event": "finished",
+            "seconds": 4.026,
+            "batches": 17,
+            "peak_inflight": 8,
+            "peak_batch_bytes": 33130860
+          }
+        },
+        {
+          "tiles_per_source": 512,
+          "contributions": 1024,
+          "input_bytes": 809558016,
+          "output_bytes": 405577728,
+          "elapsed_seconds": 33.246,
+          "peak_tree_rss_mib": 390.14,
+          "max_processes": 6,
+          "pipeline": {
+            "event": "finished",
+            "seconds": 33.123,
+            "batches": 128,
+            "peak_inflight": 8,
+            "peak_batch_bytes": 33130860
+          }
+        }
+      ]
+    },
+    {
+      "python": "3.12.14",
+      "sqlite": "3.53.1",
+      "platform": "macOS-27.2-arm64-arm-64bit",
+      "webp": "1.6.0",
+      "workers": 4,
+      "tile_size": 512,
+      "output_format": "png",
+      "measurement": "sampled simultaneous sum of parent+descendant RSS; shared pages counted multiple times; excludes filesystem page cache",
+      "runs": [
+        {
+          "tiles_per_source": 64,
+          "contributions": 128,
+          "input_bytes": 101228544,
+          "output_bytes": 58437632,
+          "elapsed_seconds": 5.087,
+          "peak_tree_rss_mib": 313.25,
+          "max_processes": 6,
+          "pipeline": {
+            "event": "finished",
+            "seconds": 4.972,
+            "batches": 24,
+            "peak_inflight": 6,
+            "peak_batch_bytes": 29898804
+          }
+        },
+        {
+          "tiles_per_source": 512,
+          "contributions": 1024,
+          "input_bytes": 809558016,
+          "output_bytes": 460922880,
+          "elapsed_seconds": 30.231,
+          "peak_tree_rss_mib": 321.27,
+          "max_processes": 6,
+          "pipeline": {
+            "event": "finished",
+            "seconds": 30.067,
+            "batches": 189,
+            "peak_inflight": 6,
+            "peak_batch_bytes": 29898804
+          }
+        }
+      ]
+    }
+  ]
+}

mbmerge-1.1.0/LICENSE.cs.md

@@ -0,0 +1,13 @@
+# Licence MIT – český překlad
+
+[English — závazné znění](LICENSE.md) | **Čeština**
+
+Tento překlad slouží pro orientaci. Projekt je zveřejněn pod původním anglickým zněním licence MIT v [LICENSE.md](LICENSE.md).
+
+Copyright (c) 2026 mbmerge contributors
+
+Tímto se bezplatně uděluje každému, kdo získá kopii tohoto softwaru a souvisejících dokumentačních souborů (dále jen „Software“), oprávnění nakládat se Softwarem bez omezení, včetně práv Software používat, kopírovat, upravovat, slučovat, zveřejňovat, distribuovat, poskytovat k němu podlicence a/nebo prodávat jeho kopie a umožnit totéž osobám, jimž je Software poskytnut, za následujících podmínek:
+
+Výše uvedené oznámení o autorských právech a toto oznámení o udělení oprávnění musí být zahrnuty ve všech kopiích nebo podstatných částech Softwaru.
+
+SOFTWARE JE POSKYTOVÁN „TAK, JAK JE“, BEZ JAKÝCHKOLI VÝSLOVNÝCH NEBO PŘEDPOKLÁDANÝCH ZÁRUK, ZEJMÉNA BEZ ZÁRUK PRODEJNOSTI, VHODNOSTI PRO URČITÝ ÚČEL A NEPORUŠOVÁNÍ PRÁV. AUTOŘI ANI DRŽITELÉ AUTORSKÝCH PRÁV V ŽÁDNÉM PŘÍPADĚ NEODPOVÍDAJÍ ZA ŽÁDNÉ NÁROKY, ŠKODY ČI JINOU ODPOVĚDNOST, AŤ JIŽ ZE SMLOUVY, Z OBČANSKOPRÁVNÍHO DELIKTU NEBO JINAK, VZNIKLÉ ZE SOFTWARU, V SOUVISLOSTI S NÍM NEBO S JEHO POUŽÍVÁNÍM ČI JINÝM NAKLÁDÁNÍM S NÍM.

mbmerge-1.1.0/LICENSE.md

@@ -0,0 +1,23 @@
+# MIT License
+
+Copyright (c) 2026 mbmerge 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.
+
+[Informative Czech translation](LICENSE.cs.md).

mbmerge-1.1.0/MANIFEST.in

@@ -0,0 +1,22 @@
+# Source distributions carry reproducible tests/docs, but never arbitrary data.
+include pyproject.toml requirements.txt .gitignore
+include README*.md ARCHITECTURE*.md RELEASING*.md LICENSE*.md TEST_REPORT*.md
+include TEST_RESULTS.txt BENCHMARK.json
+recursive-include tests *.py
+recursive-include examples *.py
+recursive-include tools *.py
+recursive-include docs/images *.png
+recursive-include .github/workflows *.yml
+# Only these named synthetic databases may enter a distribution.
+include demo/source_a.mbtiles demo/source_b.mbtiles
+include demo/png/source_a.mbtiles demo/png/source_b.mbtiles
+include demo/a.png demo/b.png demo/expected_overlap.png
+include demo/png/a.png demo/png/b.png demo/png/expected_overlap.png
+# This checksum file describes the downloadable repository ZIP, not an sdist.
+exclude SHA256SUMS
+prune build
+prune dist
+prune work
+prune .venv
+prune .git
+global-exclude *.py[cod] .DS_Store *.merge.lock *-wal *-shm *-journal