georefine-verify 1.1.1__tar.gz

georefine_verify-1.1.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Alibaba Cloud
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

georefine_verify-1.1.1/NOTICE

@@ -0,0 +1,4 @@
+GeoRefine codec software
+Copyright 2026 Tsotchke Corporation
+
+This package is licensed under the Apache License, Version 2.0.

georefine_verify-1.1.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.1
+Name: georefine-verify
+Version: 1.1.1
+Summary: Prove that a GeoRefine TBE codec bundle decodes bit for bit to the parent model's published safetensors (CPU only)
+Author: Tsotchke Corporation
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Tsotchke-Corporation/GeoRefine
+Project-URL: Model, https://huggingface.co/Tsotchke-Corporation/Qwen3.8-27B-GeoRefine-TBE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.22
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# GeoRefine TBE tools
+
+`georefine-verify` independently compares a GeoRefine TBE bundle with the
+published parent model, byte for byte. `georefine-export` restores a TBE bundle
+to ordinary Hugging Face safetensors without downloading or reading the parent.
+Both tools use NumPy and the Python standard library, and run on CPU.
+
+```sh
+pip install .
+georefine-export --bundle Tsotchke-Corporation/Qwen3.8-27B-GeoRefine-TBE \
+  --output ./Qwen3.8-27B-GeoRefine-BF16 \
+  --expect-manifest-sha256 10028416e07c802b47e4dc93a86e9f0dd35ce6021f0e07b96c70bd9cb7a72bc3
+```
+
+The output has `model.safetensors.index.json`, standard safetensors shards,
+and the original config, tokenizer and vision files. Load it with a current
+Transformers release compatible with the parent model:
+
+```python
+from transformers import AutoModelForMultimodalLM, AutoProcessor
+model = AutoModelForMultimodalLM.from_pretrained("./Qwen3.8-27B-GeoRefine-BF16")
+processor = AutoProcessor.from_pretrained("./Qwen3.8-27B-GeoRefine-BF16")
+```
+
+The export is BF16: plan for about 56 GB of output storage, plus one codec shard
+of scratch space when downloading from the Hub, and enough memory or GPU
+capacity to run Qwen3.8-27B. This path establishes portable model compatibility;
+it does not retain the compressed model's runtime memory or speed advantages.
+The native TBE engine is a separate optimized backend. A full 27B export and
+Transformers load remain release gates, beyond the existing small-fixture tests.

georefine_verify-1.1.1/README.md

@@ -0,0 +1,30 @@
+# GeoRefine TBE tools
+
+`georefine-verify` independently compares a GeoRefine TBE bundle with the
+published parent model, byte for byte. `georefine-export` restores a TBE bundle
+to ordinary Hugging Face safetensors without downloading or reading the parent.
+Both tools use NumPy and the Python standard library, and run on CPU.
+
+```sh
+pip install .
+georefine-export --bundle Tsotchke-Corporation/Qwen3.8-27B-GeoRefine-TBE \
+  --output ./Qwen3.8-27B-GeoRefine-BF16 \
+  --expect-manifest-sha256 10028416e07c802b47e4dc93a86e9f0dd35ce6021f0e07b96c70bd9cb7a72bc3
+```
+
+The output has `model.safetensors.index.json`, standard safetensors shards,
+and the original config, tokenizer and vision files. Load it with a current
+Transformers release compatible with the parent model:
+
+```python
+from transformers import AutoModelForMultimodalLM, AutoProcessor
+model = AutoModelForMultimodalLM.from_pretrained("./Qwen3.8-27B-GeoRefine-BF16")
+processor = AutoProcessor.from_pretrained("./Qwen3.8-27B-GeoRefine-BF16")
+```
+
+The export is BF16: plan for about 56 GB of output storage, plus one codec shard
+of scratch space when downloading from the Hub, and enough memory or GPU
+capacity to run Qwen3.8-27B. This path establishes portable model compatibility;
+it does not retain the compressed model's runtime memory or speed advantages.
+The native TBE engine is a separate optimized backend. A full 27B export and
+Transformers load remain release gates, beyond the existing small-fixture tests.

georefine_verify-1.1.1/georefine_verify/NOTICE

@@ -0,0 +1,4 @@
+GeoRefine codec software
+Copyright 2026 Tsotchke Corporation
+
+This package is licensed under the Apache License, Version 2.0.

georefine_verify-1.1.1/georefine_verify/__init__.py

@@ -0,0 +1,4 @@
+"""georefine-verify: prove that a GeoRefine TBE codec bundle decodes, bit for bit,
+to the parent model's published safetensors.  CPU only; numpy and the standard
+library."""
+__version__ = "1.1.1"

georefine_verify-1.1.1/georefine_verify/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

georefine_verify-1.1.1/georefine_verify/cli.py

@@ -0,0 +1,105 @@
+"""georefine-verify command line."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .sources import SourceError, eprint
+from .verify import Options, Verifier
+
+EPILOG = """\
+examples:
+  # full check: download the parent at the pinned commit (sha256-checked against
+  # Hugging Face's LFS digests), decode every bundle tensor on the CPU, compare bytes
+  georefine-verify --bundle ./Qwen3.8-27B-GeoRefine-TBE --reference Qwen/Qwen3.8-27B@1d4bf0f2
+
+  # use a parent copy you already have (its shards are still hashed and checked)
+  georefine-verify --bundle ./bundle --reference Qwen/Qwen3.8-27B@1d4bf0f2 --reference-dir ~/qwen
+
+  # quick spot check: layer 0 only, parent bytes fetched by HTTP range request
+  georefine-verify --bundle ./bundle --reference Qwen/Qwen3.8-27B@1d4bf0f2 \\
+      --reference-mode range --tensors 'layers\\.0\\.'
+
+exit status: 0 = PASS (every parent tensor bit-identical, all digests checked),
+             3 = PASS_PARTIAL (everything checked matched, but the check was not complete),
+             1 = FAIL, 2 = usage or I/O error.  Re-running with the same --work-dir resumes.
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="georefine-verify", epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Check that a GeoRefine TBE bundle decodes to the parent's published tensors "
+                    "bit for bit. CPU only.")
+    ap.add_argument("--bundle", required=True,
+                    help="bundle: local dir, HF repo id[@rev], https:// base URL, or gs://bucket/prefix")
+    ap.add_argument("--reference", required=True,
+                    help="parent as HF_REPO@COMMIT (e.g. Qwen/Qwen3.8-27B@1d4bf0f2), or a local dir")
+    ap.add_argument("--reference-dir", help="local copy of the parent's shards (still hashed and "
+                                            "checked against the published LFS sha256)")
+    ap.add_argument("--reference-mode", choices=("download", "range"), default="download",
+                    help="download: fetch whole shards into WORK_DIR/reference and check their "
+                         "sha256 (default); range: fetch only tensor bytes by HTTP range request "
+                         "(fast spot checks; shard digests are then NOT checked)")
+    ap.add_argument("--bundle-mode", choices=("download", "range"), default="download",
+                    help="for a remote bundle: download shards into WORK_DIR/bundle (sha256-checked "
+                         "against the bundle manifest; default) or read tensors by range request")
+    ap.add_argument("--work-dir", default="georefine-verify-work",
+                    help="progress, downloads and receipt (default ./georefine-verify-work)")
+    ap.add_argument("--receipt", help="receipt path (default WORK_DIR/receipt.json)")
+    ap.add_argument("--tensors", help="only tensors whose name matches this regex")
+    ap.add_argument("--limit", type=int, help="only the first N tensors (sorted by name)")
+    ap.add_argument("--evict-reference", action="store_true",
+                    help="delete each downloaded parent shard once its tensors are verified "
+                         "(peak disk ~4 GB instead of ~56 GB)")
+    ap.add_argument("--max-rate", type=float, metavar="MB_PER_S",
+                    help="cap each download's rate (parent and bundle shards)")
+    ap.add_argument("--skip-bundle-shard-hash", action="store_true",
+                    help="do not sha256 local bundle shards against the bundle manifest")
+    ap.add_argument("--expect-manifest-sha256", help="refuse a bundle whose manifest hash differs "
+                                                     "(prefix allowed)")
+    ap.add_argument("--chunk-tiles", type=int, default=1 << 16,
+                    help="decode granularity in 64-element tiles (memory ~ 60 B/tile)")
+    ap.add_argument("--fresh", action="store_true", help="ignore previous progress in WORK_DIR")
+    ap.add_argument("--version", action="version", version=f"georefine-verify {__version__}")
+    return ap
+
+
+def main(argv=None) -> int:
+    a = build_parser().parse_args(argv)
+    opt = Options(bundle=a.bundle, reference=a.reference, reference_dir=a.reference_dir,
+                  reference_mode=a.reference_mode, bundle_mode=a.bundle_mode,
+                  work_dir=a.work_dir, tensors=a.tensors,
+                  limit=a.limit, evict_reference=a.evict_reference, max_rate_mbps=a.max_rate,
+                  check_bundle_shards=not a.skip_bundle_shard_hash,
+                  expect_manifest_sha256=a.expect_manifest_sha256, chunk_tiles=a.chunk_tiles,
+                  receipt=a.receipt, fresh=a.fresh)
+    try:
+        rec = Verifier(opt).run()
+    except SourceError as exc:
+        eprint(f"error: {exc}")
+        return 2
+    s = rec["summary"]
+    print(f"{rec['verdict']}: {s['bit_identical']}/{s['verified']} tensors bit-identical "
+          f"(parent has {s['parent_tensors']})")
+    for k, v in sorted(s["by_kind"].items()):
+        print(f"  {k:4s} {v['match']}/{v['n']}  {v['bytes'] / 1e9:.2f} GB")
+    print(f"  parent  {rec['parent']['repo']}@{rec['parent']['revision']}  "
+          f"shards checked vs HF LFS sha256: {s['parent_shards_checked_against_hf_lfs']}")
+    print(f"  sidecars (config, tokenizer, templates) identical to the parent's: "
+          f"{s['sidecars_identical']}/{s['sidecars']}")
+    print(f"  bundle  manifest sha256 {rec['bundle']['manifest_sha256']}  "
+          f"shards checked: {s['bundle_shards_checked_against_manifest']}")
+    for c in rec.get("caveats", []):
+        print(f"  caveat: {c}")
+    bad = [t for t in rec["tensors"] if not t.get("match")]
+    for t in bad[:20]:
+        print(f"  MISMATCH {t['name']}: {t.get('problems')} mismatched={t.get('mismatched')} "
+              f"first={t.get('first_mismatch')}")
+    print(f"  receipt {rec['receipt_path']}")
+    return {"PASS": 0, "PASS_PARTIAL": 3}.get(rec["verdict"], 1)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

georefine_verify-1.1.1/georefine_verify/export.py

@@ -0,0 +1,188 @@
+"""Export a TBE bundle to ordinary Hugging Face safetensors, without the parent.
+
+This is a portable compatibility path. It restores BF16 storage and does not
+provide compressed inference or the GeoRefine native engine's speed.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import struct
+from pathlib import Path
+
+import numpy as np
+
+from .sources import LocalFile, SourceError, download, parse_location, read_safetensors_header, sha256_source
+from .tbe import TBEParams, iter_decode
+from .verify import _dtype_tag
+
+
+def _digest_file(path: Path) -> str:
+    src = LocalFile(path)
+    try:
+        return sha256_source(src)
+    finally:
+        src.close()
+
+
+def _bytes_for(entry: dict) -> int:
+    return int(entry["original_bytes"])
+
+
+def _header(entries: list[dict]) -> bytes:
+    hdr, offset = {}, 0
+    for entry in entries:
+        name = entry["name"]
+        size = _bytes_for(entry)
+        hdr[name] = {"dtype": _dtype_tag(entry["dtype"]), "shape": entry["shape"],
+                     "data_offsets": [offset, offset + size]}
+        offset += size
+    data = json.dumps(hdr, separators=(",", ":"), ensure_ascii=False).encode()
+    return data + b" " * (-len(data) % 8)
+
+
+def _write_tensor(out, entry: dict, src: LocalFile, header: dict) -> None:
+    name = entry["name"]
+    digest = hashlib.blake2b()
+
+    def write(data: bytes) -> None:
+        out.write(data)
+        digest.update(data)
+
+    if entry["kind"] == "raw":
+        stored = header.get(name)
+        if stored is None or stored.dtype != _dtype_tag(entry["dtype"]) or \
+                list(stored.shape) != entry["shape"] or stored.nbytes != _bytes_for(entry):
+            raise SourceError(f"raw tensor metadata differs: {name}")
+        for off in range(0, stored.nbytes, 1 << 26):
+            write(src.read(stored.offset + off, min(1 << 26, stored.nbytes - off)))
+    elif entry["kind"] == "tbe":
+        if _dtype_tag(entry["dtype"]) != "BF16":
+            raise SourceError(f"TBE tensor is not BF16: {name}")
+        n, k = (int(x) for x in (entry.get("coded_shape") or entry["shape"]))
+        if n * k * 2 != _bytes_for(entry):
+            raise SourceError(f"TBE coded shape disagrees with byte count: {name}")
+        params = TBEParams(n=n, k=k, layout=entry["layout"], mode=int(entry["mode"]),
+                           base=int(entry["base"]), superblock=int(entry.get("superblock", 32)))
+        parts = {}
+        for part in ("planes", "smb", "esc", "sbbase"):
+            parts[part] = header.get(f"{name}.{part}")
+            if parts[part] is None:
+                raise SourceError(f"TBE part absent: {name}.{part}")
+        if parts["planes"].nbytes != params.tiles * 24 or \
+                parts["smb"].nbytes != params.tiles * 64 or \
+                parts["esc"].nbytes != int(entry["escapes"]):
+            raise SourceError(f"TBE part sizes disagree: {name}")
+        sb = parts["sbbase"]
+        if sb.nbytes != params.n_superblocks * 4:
+            raise SourceError(f"TBE superblock index size disagrees: {name}")
+        sbbase = np.frombuffer(src.read(sb.offset, sb.nbytes), dtype="<i4")
+
+        def reader(part):
+            a = parts[part]
+            return lambda off, size: src.read(a.offset + off, size)
+
+        for _, words in iter_decode(params, reader("planes"), reader("smb"),
+                                    reader("esc"), sbbase, parts["esc"].nbytes):
+            write(words.astype("<u2", copy=False).tobytes())
+    else:
+        raise SourceError(f"unknown tensor kind: {name}")
+    if entry.get("blake2b_source") and digest.hexdigest() != entry["blake2b_source"]:
+        raise SourceError(f"decoded tensor digest differs: {name}")
+
+
+def export(bundle: str, output: Path, expected_manifest_sha256: str | None = None,
+           work_dir: Path | None = None) -> dict:
+    loc = parse_location(bundle)
+    raw = loc.read_small("serve_manifest.json")
+    manifest_sha = hashlib.sha256(raw).hexdigest()
+    if expected_manifest_sha256 and manifest_sha != expected_manifest_sha256:
+        raise SourceError("manifest SHA-256 differs from the expected value")
+    manifest = json.loads(raw)
+    if manifest.get("format") != "georefine.tbe.serve.v1":
+        raise SourceError("unsupported bundle format")
+    shards = manifest["shards"]
+    entries = manifest["tensors"]
+    by_shard: dict[int, list[dict]] = {i: [] for i in range(len(shards))}
+    if len({e["name"] for e in entries}) != len(entries):
+        raise SourceError("duplicate tensor name")
+    for e in entries:
+        by_shard[int(e["shard"])].append(e)
+    output.mkdir(parents=True, exist_ok=True)
+    scratch = work_dir or (output.parent / ".scratch" / f"{output.name}-georefine-export")
+    scratch.mkdir(parents=True, exist_ok=True)
+    receipt_path = scratch / "receipt.json"
+    receipt = json.loads(receipt_path.read_text()) if receipt_path.exists() else {"shards": {}}
+    if receipt.get("manifest_sha256") not in (None, manifest_sha):
+        raise SourceError("output was started from another bundle manifest")
+    receipt["manifest_sha256"] = manifest_sha
+    weight_map = {}
+    total_size = 0
+    for i, shard in enumerate(shards):
+        name = f"model-{i + 1:05d}-of-{len(shards):05d}.safetensors"
+        target = output / name
+        expected = receipt["shards"].get(name)
+        if expected and target.is_file() and _digest_file(target) == expected:
+            pass
+        else:
+            source_file = scratch / f"codec-{i:05d}.safetensors"
+            if not source_file.is_file() or _digest_file(source_file) != shard["sha256"]:
+                if loc.kind == "local":
+                    source_file = Path(loc.base) / shard["file"]
+                else:
+                    download(loc.url(shard["file"]), source_file, size=shard["bytes"],
+                             sha256=shard["sha256"])
+            if _digest_file(source_file) != shard["sha256"]:
+                raise SourceError(f"codec shard hash differs: {shard['file']}")
+            src = LocalFile(source_file)
+            try:
+                codec_header = read_safetensors_header(src)[0]
+                ordered = sorted(by_shard[i], key=lambda e: e["name"])
+                header = _header(ordered)
+                part = scratch / f"{name}.partial"
+                with part.open("wb") as out:
+                    out.write(struct.pack("<Q", len(header)))
+                    out.write(header)
+                    for entry in ordered:
+                        _write_tensor(out, entry, src, codec_header)
+                os.replace(part, target)
+                receipt["shards"][name] = _digest_file(target)
+                receipt_path.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n")
+            finally:
+                src.close()
+                if loc.kind != "local":
+                    source_file.unlink(missing_ok=True)
+        for entry in by_shard[i]:
+            weight_map[entry["name"]] = name
+            total_size += _bytes_for(entry)
+    for sidecar in manifest["sidecars"]:
+        rel = sidecar["file"]
+        target = output / rel
+        data = loc.read_small(rel)
+        if len(data) != sidecar["bytes"] or hashlib.sha256(data).hexdigest() != sidecar["sha256"]:
+            raise SourceError(f"sidecar hash differs: {rel}")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+    index = {"metadata": {"total_size": total_size}, "weight_map": weight_map}
+    (output / "model.safetensors.index.json").write_text(
+        json.dumps(index, indent=2, sort_keys=True) + "\n")
+    return {"manifest_sha256": manifest_sha, "tensors": len(weight_map),
+            "shards": len(shards), "bf16_bytes": total_size, "output": str(output)}
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--bundle", required=True, help="local dir, HF repo[@revision], or gs://")
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--work-dir", type=Path, help="durable scratch and resume state")
+    parser.add_argument("--expect-manifest-sha256")
+    args = parser.parse_args(argv)
+    result = export(args.bundle, args.output, args.expect_manifest_sha256, args.work_dir)
+    print(json.dumps(result, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())