docpull 6.5.4__tar.gz → 6.6.0__tar.gz

{docpull-6.5.4/src/docpull.egg-info → docpull-6.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docpull
-Version: 6.5.4
+Version: 6.6.0
 Summary: Declare, sync, diff, and lock context dependencies for AI agents
 Author-email: Zachary Roth <support@raintree.technology>
 Maintainer-email: Raintree Technology <support@raintree.technology>
@@ -50,7 +50,7 @@ Requires-Dist: regex>=2024.11.6
 Requires-Dist: rich>=13.0.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: pydantic>=2.0
-Requires-Dist: urllib3>=2.7.0
+Requires-Dist: urllib3>=2.8.0
 Provides-Extra: proxy
 Requires-Dist: aiohttp-socks>=0.11.0; extra == "proxy"
 Provides-Extra: normalize
@@ -63,7 +63,7 @@ Provides-Extra: mcp
 Requires-Dist: cryptography>=50.0.0; extra == "mcp"
 Requires-Dist: mcp<2,>=1.28.1; extra == "mcp"
 Requires-Dist: pydantic-settings>=2.14.2; extra == "mcp"
-Requires-Dist: pyjwt>=2.13.0; extra == "mcp"
+Requires-Dist: pyjwt>=2.15.1; extra == "mcp"
 Requires-Dist: python-multipart>=0.0.27; extra == "mcp"
 Requires-Dist: starlette>=1.3.1; extra == "mcp"
 Provides-Extra: serve
@@ -71,17 +71,17 @@ Requires-Dist: uvicorn>=0.30.0; extra == "serve"
 Provides-Extra: parquet
 Requires-Dist: pyarrow>=16.0.0; extra == "parquet"
 Provides-Extra: markitdown
-Requires-Dist: pypdf>=6.15.0; extra == "markitdown"
+Requires-Dist: pypdf>=6.20.0; extra == "markitdown"
 Requires-Dist: markitdown[docx,pdf]>=0.1.0; extra == "markitdown"
 Provides-Extra: unstructured
-Requires-Dist: pypdf>=6.15.0; extra == "unstructured"
-Requires-Dist: unstructured[all-docs]>=0.16.0; extra == "unstructured"
+Requires-Dist: pypdf>=6.20.0; extra == "unstructured"
+Requires-Dist: unstructured[all-docs]>=0.24.1; (python_version >= "3.11" and python_version < "3.14") and extra == "unstructured"
 Provides-Extra: pdf
-Requires-Dist: pypdf>=6.15.0; extra == "pdf"
+Requires-Dist: pypdf>=6.20.0; extra == "pdf"
 Provides-Extra: parse
-Requires-Dist: pypdf>=6.15.0; extra == "parse"
+Requires-Dist: pypdf>=6.20.0; extra == "parse"
 Requires-Dist: markitdown[docx,pdf]>=0.1.0; extra == "parse"
-Requires-Dist: unstructured[all-docs]>=0.16.0; extra == "parse"
+Requires-Dist: unstructured[all-docs]>=0.24.1; (python_version >= "3.11" and python_version < "3.14") and extra == "parse"
 Provides-Extra: presidio
 Requires-Dist: presidio-analyzer>=2.2.0; extra == "presidio"
 Provides-Extra: provenance
@@ -98,14 +98,14 @@ Requires-Dist: tiktoken>=0.7.0; extra == "all"
 Requires-Dist: cryptography>=50.0.0; extra == "all"
 Requires-Dist: mcp<2,>=1.28.1; extra == "all"
 Requires-Dist: pydantic-settings>=2.14.2; extra == "all"
-Requires-Dist: pyjwt>=2.13.0; extra == "all"
+Requires-Dist: pyjwt>=2.15.1; extra == "all"
 Requires-Dist: python-multipart>=0.0.27; extra == "all"
 Requires-Dist: starlette>=1.3.1; extra == "all"
 Requires-Dist: uvicorn>=0.30.0; extra == "all"
 Requires-Dist: pyarrow>=16.0.0; extra == "all"
-Requires-Dist: pypdf>=6.15.0; extra == "all"
+Requires-Dist: pypdf>=6.20.0; extra == "all"
 Requires-Dist: markitdown[docx,pdf]>=0.1.0; extra == "all"
-Requires-Dist: unstructured[all-docs]>=0.16.0; extra == "all"
+Requires-Dist: unstructured[all-docs]>=0.24.1; (python_version >= "3.11" and python_version < "3.14") and extra == "all"
 Requires-Dist: presidio-analyzer>=2.2.0; extra == "all"
 Requires-Dist: e2b>=2.0.0; extra == "all"
 Provides-Extra: dev
@@ -151,6 +151,7 @@ pip install docpull
 docpull init stripe-docs
 docpull add https://docs.stripe.com
 docpull sync
+docpull query "retry policy" --max-tokens 4000
 docpull diff
 docpull export context-pack --target cursor
 ```
@@ -159,6 +160,11 @@ The project stores declared sources in `docpull.yaml` and resolved inputs in
 `.docpull/context.lock.json`. Later syncs produce a hash-based diff while preserving
 source URLs, content hashes, run IDs, citations, and export metadata.
 
+`docpull query` retrieves deduplicated passages from locked archives with version
+filters, a response budget, and exact source spans. The same query is available
+through the Python SDK and MCP. See [Query locked context](docs/context-dependencies.md#query-locked-context)
+for budget semantics and queries across projects.
+
 ![DocPull project diff showing changed pages, local semantic categories, and zero failed URLs](docs/launch-assets/docpull-project-diff-demo.png)
 
 No account or paid API is required for this path. Direct fetching, discovery,

{docpull-6.5.4 → docpull-6.6.0}/README.md

@@ -25,6 +25,7 @@ pip install docpull
 docpull init stripe-docs
 docpull add https://docs.stripe.com
 docpull sync
+docpull query "retry policy" --max-tokens 4000
 docpull diff
 docpull export context-pack --target cursor
 ```
@@ -33,6 +34,11 @@ The project stores declared sources in `docpull.yaml` and resolved inputs in
 `.docpull/context.lock.json`. Later syncs produce a hash-based diff while preserving
 source URLs, content hashes, run IDs, citations, and export metadata.
 
+`docpull query` retrieves deduplicated passages from locked archives with version
+filters, a response budget, and exact source spans. The same query is available
+through the Python SDK and MCP. See [Query locked context](docs/context-dependencies.md#query-locked-context)
+for budget semantics and queries across projects.
+
 ![DocPull project diff showing changed pages, local semantic categories, and zero failed URLs](docs/launch-assets/docpull-project-diff-demo.png)
 
 No account or paid API is required for this path. Direct fetching, discovery,

{docpull-6.5.4 → docpull-6.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "docpull"
-version = "6.5.4"
+version = "6.6.0"
 dynamic = []
 description = "Declare, sync, diff, and lock context dependencies for AI agents"
 readme = {file = "README.md", content-type = "text/markdown"}
@@ -92,7 +92,7 @@ dependencies = [
     "rich>=13.0.0",
     "pyyaml>=6.0",
     "pydantic>=2.0",
-    "urllib3>=2.7.0",  # Security floor for transitive HTTP clients; Renovate raises as needed
+    "urllib3>=2.8.0",  # Security floor for transitive HTTP clients; Renovate raises as needed
 ]
 
 [project.optional-dependencies]
@@ -112,7 +112,7 @@ mcp = [
     "cryptography>=50.0.0",
     "mcp>=1.28.1,<2",
     "pydantic-settings>=2.14.2",
-    "pyjwt>=2.13.0",
+    "pyjwt>=2.15.1",
     "python-multipart>=0.0.27",
     "starlette>=1.3.1",
 ]
@@ -123,20 +123,20 @@ parquet = [
     "pyarrow>=16.0.0",
 ]
 markitdown = [
-    "pypdf>=6.15.0",
+    "pypdf>=6.20.0",
     "markitdown[docx,pdf]>=0.1.0",
 ]
 unstructured = [
-    "pypdf>=6.15.0",
-    "unstructured[all-docs]>=0.16.0",
+    "pypdf>=6.20.0",
+    "unstructured[all-docs]>=0.24.1; python_version >= '3.11' and python_version < '3.14'",
 ]
 pdf = [
-    "pypdf>=6.15.0",
+    "pypdf>=6.20.0",
 ]
 parse = [
-    "pypdf>=6.15.0",
+    "pypdf>=6.20.0",
     "markitdown[docx,pdf]>=0.1.0",
-    "unstructured[all-docs]>=0.16.0",
+    "unstructured[all-docs]>=0.24.1; python_version >= '3.11' and python_version < '3.14'",
 ]
 presidio = [
     "presidio-analyzer>=2.2.0",
@@ -158,14 +158,14 @@ all = [
     "cryptography>=50.0.0",
     "mcp>=1.28.1,<2",
     "pydantic-settings>=2.14.2",
-    "pyjwt>=2.13.0",
+    "pyjwt>=2.15.1",
     "python-multipart>=0.0.27",
     "starlette>=1.3.1",
     "uvicorn>=0.30.0",
     "pyarrow>=16.0.0",
-    "pypdf>=6.15.0",
+    "pypdf>=6.20.0",
     "markitdown[docx,pdf]>=0.1.0",
-    "unstructured[all-docs]>=0.16.0",
+    "unstructured[all-docs]>=0.24.1; python_version >= '3.11' and python_version < '3.14'",
     "presidio-analyzer>=2.2.0",
     "e2b>=2.0.0",
 ]
@@ -208,7 +208,13 @@ include = ["docpull*"]
 docpull = ["py.typed", "fixtures/*.json", "schemas/*.schema.json"]
 
 [tool.uv]
-constraint-dependencies = ["h2>=4.4.1"]
+constraint-dependencies = [
+    "h2>=4.4.1",
+    "multidict>=6.9.1",
+    "accelerate>=1.15.0",
+    "soupsieve>=2.9",
+    "virtualenv>=21.7.13",
+]
 
 [tool.ruff]
 line-length = 110

{docpull-6.5.4 → docpull-6.6.0}/src/docpull/__init__.py

@@ -15,9 +15,11 @@ from typing import TYPE_CHECKING, Any
 
 from .surface import PUBLIC_SDK_EXPORTS
 
-__version__ = "6.5.4"
+__version__ = "6.6.0"
 
 _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "query_context": (".context_query", "query_context"),
+    "ContextQueryError": (".context_query", "ContextQueryError"),
     **{
         name: (".context_packs", name)
         for name in (
@@ -207,6 +209,7 @@ if TYPE_CHECKING:
         capture_screenshot_pack,
         validate_website_snapshot_pack,
     )
+    from .context_query import ContextQueryError, query_context
     from .contracts import (
         ArtifactManifest,
         ChangeEvent,

{docpull-6.5.4 → docpull-6.6.0}/src/docpull/cli.py

@@ -1623,6 +1623,10 @@ def main(argv: list[str] | None = None) -> int:
         from .project import run_install_cli
 
         return run_install_cli(raw_argv[1:])
+    if raw_argv and raw_argv[0] == "query":
+        from .context_query import run_query_cli
+
+        return run_query_cli(raw_argv[1:])
     if raw_argv and raw_argv[0] == "deps":
         from .project import run_deps_cli
 

docpull-6.6.0/src/docpull/context_query.py

@@ -0,0 +1,305 @@
+"""Offline, budgeted passage retrieval from verified project lock snapshots."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+import tempfile
+from collections.abc import Iterator, Sequence
+from pathlib import Path
+from typing import Any
+
+from .frozen import FrozenArtifactError, stage_run_artifact
+from .pack_tools import _search_score, _term_count
+from .project import (
+    ProjectError,
+    _content_hash_summary,
+    _context_lock_hash,
+    _read_context_lock,
+    _read_json,
+    _read_jsonl,
+    _safe_run_id,
+    _validate_context_lock,
+    find_project_root,
+    load_project_config,
+    project_paths,
+)
+
+_STOPWORDS = frozenset(
+    [
+        "a",
+        "an",
+        "the",
+        "how",
+        "to",
+        "do",
+        "does",
+        "is",
+        "are",
+        "of",
+        "for",
+        "in",
+        "on",
+        "and",
+        "with",
+        "what",
+        "i",
+        "can",
+    ]
+)
+
+
+class ContextQueryError(ValueError):
+    """Invalid query input or unverifiable locked evidence."""
+
+
+def serialize_query_result(payload: dict[str, Any]) -> str:
+    """Return the canonical JSON representation covered by the token budget."""
+    return json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _measure(payload: dict[str, Any]) -> int:
+    # One UTF-8 byte per budget token is a conservative bound for byte tokenizers.
+    # Unlike optional tokenizer initialization, this cannot download model data.
+    while True:
+        size = len(serialize_query_result(payload).encode("utf-8"))
+        if payload["budget"]["used_tokens"] == size:
+            return size
+        payload["budget"]["used_tokens"] = size
+
+
+def _spans(content: str) -> Iterator[tuple[int, int]]:
+    """Keep paragraphs and fenced code blocks whole, with exact character offsets."""
+    start = offset = 0
+    fence = ""
+    for line in content.splitlines(keepends=True):
+        marker = re.match(r"^ {0,3}(`{3,}|~{3,})", line)
+        if fence:
+            if re.fullmatch(r" {0,3}" + re.escape(fence[0]) + "{" + str(len(fence)) + r",}\s*", line):
+                fence = ""
+                yield start, offset + len(line)
+                start = offset + len(line)
+        elif marker:
+            if start < offset:
+                yield start, offset
+            start = offset
+            fence = marker.group(1)
+        elif not line.strip():
+            if start < offset:
+                yield start, offset
+            start = offset + len(line)
+        offset += len(line)
+    if start < offset:
+        yield start, offset
+
+
+def _filters(values: list[str] | None, name: str) -> set[str]:
+    if values is None:
+        return set()
+    if not isinstance(values, list) or not all(isinstance(v, str) and v.strip() for v in values):
+        raise ContextQueryError(f"{name} must be a list of non-empty strings")
+    return {v.strip() for v in values}
+
+
+def _locked_records(
+    root: Path, artifact_dirs: list[Path], pack_versions: set[str]
+) -> Iterator[tuple[dict[str, Any], int, dict[str, Any]]]:
+    config = load_project_config(root)
+    paths = project_paths(root)
+    lock = _read_context_lock(paths.context_lock)
+    if not lock:
+        raise ContextQueryError(f"No context lockfile in {root}; run `docpull sync` first")
+    _validate_context_lock(config, lock)
+    if lock.get("lock_hash") != _context_lock_hash(lock) or lock.get("project") != config.name:
+        raise ContextQueryError(f"Invalid context lockfile in {root}")
+    if not isinstance(lock.get("run_id"), str):
+        raise ContextQueryError(f"No run pinned in {root}; run `docpull sync` first")
+    run_id = _safe_run_id(lock["run_id"])
+    if pack_versions and run_id not in pack_versions:
+        return
+    artifact = lock.get("artifact")
+    if not isinstance(artifact, dict) or not re.fullmatch(r"[0-9a-f]{64}", str(artifact.get("sha256"))):
+        raise ContextQueryError(f"No frozen artifact pinned in {root}; run `docpull sync` first")
+    stores = [paths.state / "artifacts", *artifact_dirs]
+    store = next((p for p in stores if (p / f"{artifact['sha256']}.zip").is_file()), stores[0])
+    with tempfile.TemporaryDirectory(prefix="docpull-query-") as temporary:
+        staged = Path(temporary)
+        stage_run_artifact(artifact, store, staged)
+        run = _read_json(staged / "run.json")
+        if not isinstance(run, dict) or run.get("run_id") != run_id or run.get("project") != config.name:
+            raise ContextQueryError("Frozen artifact does not match the locked run")
+        records = _read_jsonl(staged / "documents.ndjson")
+        if sorted(str(row["content_hash"]) for row in records if row.get("content_hash")) != lock.get(
+            "content_hashes"
+        ) or _content_hash_summary(records) != lock.get("content_hash_summary"):
+            raise ContextQueryError("Frozen artifact content does not match the lockfile")
+        for index, record in enumerate(records, 1):
+            if not isinstance(record.get("url"), str) or not record["url"].strip():
+                raise ContextQueryError(f"Missing source URL in locked record {index}")
+            content = record.get("content")
+            if not isinstance(content, str) or hashlib.sha256(
+                content.encode("utf-8")
+            ).hexdigest() != record.get("content_hash"):
+                raise ContextQueryError(f"Invalid content hash in locked record {index}")
+            yield lock, index, record
+
+
+def query_context(
+    query: str,
+    *,
+    project_roots: Sequence[Path | str] | None = None,
+    max_tokens: int = 4000,
+    versions: list[str] | None = None,
+    pack_versions: list[str] | None = None,
+    sources: list[str] | None = None,
+    limit: int = 10,
+    artifact_dirs: Sequence[Path | str] | None = None,
+) -> dict[str, Any]:
+    """Retrieve cited passages from locked archives without acquiring or changing sources.
+
+    ``versions`` matches explicit document ``metadata.version`` values; unknown
+    versions never match. ``pack_versions`` matches exact locked run IDs.
+    The complete canonical JSON result fits ``max_tokens`` using a conservative
+    UTF-8 byte bound, including citations and budget metadata. Oversized passages
+    are omitted whole, so code blocks and source offsets remain intact.
+    """
+    if not isinstance(query, str) or not query.strip():
+        raise ContextQueryError("query must be a non-empty string")
+    if type(max_tokens) is not int or max_tokens < 256:
+        raise ContextQueryError("max_tokens must be an integer of at least 256")
+    if type(limit) is not int or not 1 <= limit <= 100:
+        raise ContextQueryError("limit must be an integer between 1 and 100")
+    for values, name in ((project_roots, "project_roots"), (artifact_dirs, "artifact_dirs")):
+        if values is not None and (
+            isinstance(values, (str, bytes))
+            or not isinstance(values, Sequence)
+            or not all(isinstance(p, (str, Path)) and str(p).strip() for p in values)
+        ):
+            raise ContextQueryError(f"{name} must be a sequence of non-empty paths")
+    source_versions = _filters(versions, "versions")
+    runs = _filters(pack_versions, "pack_versions")
+    source_names = _filters(sources, "sources")
+    terms = sorted(set(re.findall(r"[^\W_]+(?:[_-][^\W_]+)*", query.casefold())) - _STOPWORDS)
+    if not terms:
+        raise ContextQueryError("query must contain a searchable term")
+    groups: dict[str, dict[str, Any]] = {}
+    try:
+        roots = project_roots if project_roots is not None else [find_project_root(Path.cwd())]
+        if not roots:
+            raise ContextQueryError("project_roots must contain at least one project")
+        stores = [Path(p).expanduser().resolve() for p in artifact_dirs or []]
+        for root in sorted({Path(p).expanduser().resolve() for p in roots}):
+            for lock, record_index, record in _locked_records(root, stores, runs):
+                metadata = record.get("metadata") or {}
+                version = metadata.get("version") if isinstance(metadata, dict) else None
+                source = metadata.get("docpull_project_source") if isinstance(metadata, dict) else None
+                if not isinstance(version, str):
+                    version = None
+                if not isinstance(source, str):
+                    source = None
+                if source_versions and version not in source_versions:
+                    continue
+                if source_names and source not in source_names:
+                    continue
+                content = record["content"]
+                for start, end in _spans(content):
+                    # Trim outside whitespace only; never rewrite captured passage text.
+                    raw = content[start:end]
+                    start += len(raw) - len(raw.lstrip())
+                    end -= len(raw) - len(raw.rstrip())
+                    text = content[start:end]
+                    if not text or not any(_term_count(text, term) for term in terms):
+                        continue
+                    score, _ = _search_score(
+                        query_terms=terms,
+                        phrase=query.strip().lower(),
+                        title=str(record.get("title") or ""),
+                        heading="",
+                        url=str(record.get("url") or ""),
+                        content=text,
+                    )
+                    digest = lock["artifact"]["sha256"]
+                    identity = f"{digest}:{record_index}:{start}:{end}"
+                    citation = {
+                        "id": "ctx_" + hashlib.sha256(identity.encode()).hexdigest()[:24],
+                        "pack": lock["project"],
+                        "pack_version": lock["run_id"],
+                        "artifact_sha256": digest,
+                        "source": source,
+                        "version": version,
+                        "url": record["url"],
+                        "document_id": record.get("document_id"),
+                        "record_index": record_index,
+                        "content_hash": record["content_hash"],
+                        "char_start": start,
+                        "char_end": end,
+                        "line_start": content.count("\n", 0, start) + 1,
+                        "line_end": content.count("\n", 0, end - 1) + 1,
+                    }
+                    group = groups.setdefault(text, {"score": score, "text": text, "citations": {}})
+                    group["score"] = max(group["score"], score)
+                    group["citations"][citation["id"]] = citation
+    except (ProjectError, FrozenArtifactError, OSError, UnicodeError) as err:
+        raise ContextQueryError(str(err)) from err
+    payload: dict[str, Any] = {
+        "schema_version": 1,
+        "status": "ok",
+        "reason": None,
+        "budget": {"max_tokens": max_tokens, "used_tokens": 0, "method": "utf8_bytes_upper_bound"},
+        "results": [],
+        "omitted_passages": 0,
+    }
+    ranked = sorted(groups.values(), key=lambda g: (-g["score"], g["text"]))
+    deferred: list[tuple[dict[str, Any], list[dict[str, Any]]]] = []
+    payload["omitted_passages"] = len(ranked)
+    for group in ranked:
+        citations = sorted(group["citations"].values(), key=lambda c: c["id"])
+        result = {"text": group["text"], "citations": citations[:1], "omitted_citations": len(citations) - 1}
+        if len(payload["results"]) >= limit:
+            break
+        payload["results"].append(result)
+        payload["omitted_passages"] -= 1
+        if _measure(payload) > max_tokens:
+            payload["results"].pop()
+            payload["omitted_passages"] += 1
+        else:
+            deferred.append((result, citations[1:]))
+    # Spend remaining space on duplicate provenance after selecting distinct passages.
+    for result, citations in deferred:
+        for citation in citations:
+            result["citations"].append(citation)
+            result["omitted_citations"] -= 1
+            if _measure(payload) > max_tokens:
+                result["citations"].pop()
+                result["omitted_citations"] += 1
+    if not payload["results"]:
+        payload["status"] = "insufficient_evidence"
+        payload["reason"] = "budget_exhausted" if ranked else "no_matches"
+    if _measure(payload) > max_tokens:
+        raise ContextQueryError("max_tokens is too small for response metadata")
+    return payload
+
+
+def run_query_cli(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="docpull query", description="Query verified locked context offline"
+    )
+    parser.add_argument("query")
+    parser.add_argument("--project", action="append", type=Path, dest="project_roots")
+    parser.add_argument("--max-tokens", type=int, default=4000)
+    parser.add_argument("--version", action="append", dest="versions", help="Exact metadata.version filter")
+    parser.add_argument("--pack-version", action="append", dest="pack_versions", help="Exact locked run ID")
+    parser.add_argument("--source", action="append", dest="sources", help="Configured source name")
+    parser.add_argument("--limit", type=int, default=10)
+    parser.add_argument("--artifact-dir", action="append", type=Path, dest="artifact_dirs")
+    args = parser.parse_args(argv)
+    try:
+        payload = query_context(**vars(args))
+    except ContextQueryError as err:
+        print(f"Context query error: {err}", file=sys.stderr)
+        return 1
+    print(serialize_query_result(payload))
+    return 0

{docpull-6.5.4 → docpull-6.6.0}/src/docpull/document_parse.py

@@ -926,6 +926,11 @@ def _parse_markitdown(path: Path) -> tuple[str, dict[str, Any]]:
 
 
 def _parse_unstructured(path: Path) -> tuple[str, dict[str, Any]]:
+    if not (3, 11) <= sys.version_info[:2] < (3, 14):
+        raise DocumentParseError(
+            "The patched Unstructured backend requires Python 3.11–3.13. "
+            "Use the pypdf, markitdown, or text backend on this interpreter."
+        )
     try:
         module = importlib.import_module("unstructured.partition.auto")
     except ImportError as err:

docpull-6.6.0/src/docpull/frozen.py

@@ -0,0 +1,123 @@
+"""Content-addressed local archives for frozen project installation."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import stat
+import tempfile
+import zipfile
+from pathlib import Path, PurePosixPath
+from typing import Any, BinaryIO
+
+
+class FrozenArtifactError(RuntimeError):
+    """An artifact is missing, invalid, or unsafe to restore."""
+
+
+def _digest(stream: BinaryIO) -> str:
+    digest = hashlib.sha256()
+    for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+        digest.update(chunk)
+    return digest.hexdigest()
+
+
+def run_files(root: Path) -> list[Path]:
+    """List every retained run file without following symbolic links."""
+    files = []
+    for path in sorted(root.rglob("*")):
+        if path.is_symlink():
+            raise FrozenArtifactError(f"Artifact contains a symbolic link: {path}")
+        if path.is_file():
+            files.append(path)
+        elif not path.is_dir():
+            raise FrozenArtifactError(f"Artifact contains a non-regular file: {path}")
+    return files
+
+
+def run_fingerprints(root: Path) -> dict[str, str]:
+    """Hash evidence files without loading the corpus into memory."""
+    result = {}
+    for path in run_files(root):
+        if path.name == "run.json" and path.parent == root:
+            continue
+        with path.open("rb") as stream:
+            result[path.relative_to(root).as_posix()] = _digest(stream)
+    return result
+
+
+def create_run_artifact(run_dir: Path, artifact_dir: Path) -> dict[str, Any]:
+    """Save the completed run as a ZIP addressed by its SHA-256 digest."""
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=".snapshot-", dir=artifact_dir) as temporary:
+        archive = Path(temporary) / "run.zip"
+        with zipfile.ZipFile(archive, "w", compression=zipfile.ZIP_DEFLATED) as bundle:
+            for path in run_files(run_dir):
+                info = zipfile.ZipInfo(path.relative_to(run_dir).as_posix())
+                info.compress_type = zipfile.ZIP_DEFLATED
+                info.external_attr = (stat.S_IFREG | 0o600) << 16
+                with path.open("rb") as source, bundle.open(info, "w", force_zip64=True) as target:
+                    shutil.copyfileobj(source, target)
+        archive.chmod(0o600)
+        with archive.open("rb") as stream:
+            digest = _digest(stream)
+        destination = artifact_dir / f"{digest}.zip"
+        if destination.exists():
+            with destination.open("rb") as stream:
+                if _digest(stream) != digest:
+                    raise FrozenArtifactError(f"Artifact digest mismatch: {destination}")
+        else:
+            os.replace(archive, destination)
+    return {"schema_version": 1, "format": "zip", "sha256": digest}
+
+
+def stage_run_artifact(artifact: Any, artifact_dir: Path, destination: Path) -> None:
+    """Verify pinned bytes before safely unpacking into a private staging directory."""
+    if (
+        not isinstance(artifact, dict)
+        or artifact.get("schema_version") != 1
+        or artifact.get("format") != "zip"
+        or not isinstance(artifact.get("sha256"), str)
+        or not re.fullmatch(r"[0-9a-f]{64}", artifact["sha256"])
+    ):
+        raise FrozenArtifactError(
+            "Lockfile has no supported frozen artifact. Run `docpull sync` on the source machine first."
+        )
+    digest = artifact["sha256"]
+    archive = artifact_dir / f"{digest}.zip"
+    try:
+        with archive.open("rb") as stream:
+            if _digest(stream) != digest:
+                raise FrozenArtifactError(f"Artifact digest mismatch: {archive}")
+            stream.seek(0)
+            with zipfile.ZipFile(stream) as bundle:
+                seen: set[str] = set()
+                for info in bundle.infolist():
+                    name = info.filename
+                    path = PurePosixPath(name)
+                    mode = info.external_attr >> 16
+                    if (
+                        not name
+                        or info.orig_filename != name
+                        or path.is_absolute()
+                        or "\\" in name
+                        or ":" in name
+                        or any(part in {"", ".", ".."} for part in name.split("/"))
+                        or name in seen
+                        or (stat.S_IFMT(mode) not in {0, stat.S_IFREG})
+                    ):
+                        raise FrozenArtifactError(f"Unsafe artifact entry: {name}")
+                    seen.add(name)
+                    target = destination.joinpath(*path.parts)
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    with bundle.open(info) as source, target.open("xb") as output:
+                        shutil.copyfileobj(source, output)
+                    target.chmod(0o600)
+    except FileNotFoundError as err:
+        raise FrozenArtifactError(f"Missing frozen artifact: {archive}") from err
+    except (OSError, ValueError, zipfile.BadZipFile, RuntimeError, NotImplementedError) as err:
+        if isinstance(err, FrozenArtifactError):
+            raise
+        raise FrozenArtifactError(f"Cannot restore frozen artifact {archive}: {err}") from err