sqai 0.1.0__tar.gz

sqai-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+node_modules/
+dist/
+.turbo/
+coverage/
+*.log
+.env
+.env.*
+!.env.example
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+build/
+*.egg-info/
+.DS_Store

sqai-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: sqai
+Version: 0.1.0
+Summary: SQAI — the deterministic, read-only structured-data SDK for AI agents, powered by Algenta execution and provenance.
+Project-URL: Homepage, https://sqai.com
+Project-URL: Repository, https://github.com/thyn-ai/sqai
+Author-email: Thyn <eng@thyn.ai>
+License-Expression: Apache-2.0
+Keywords: agents,ai,algenta,deterministic,read-only,sqai,structured-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: algenta-core==1.0.5
+Description-Content-Type: text/markdown
+
+# sqai
+
+SQAI — the deterministic, read-only structured-data SDK for AI agents, powered by
+Algenta execution and provenance. Python twin of [`@thyn-ai/sqai`](https://github.com/thyn-ai/sqai):
+same vocabulary, same error codes, same golden numbers, cross-language-identical hashes.
+
+```python
+from sqai import create_sqai
+
+sq = create_sqai()  # zero-config: SQAI_ENGINE_URL -> self_hosted, SQAI_API_KEY -> api, else local
+sq.connect(orders, name="orders")
+
+outcome = sq.ask({"metric": "revenue", "aggregation": "sum", "group_by": "region",
+                  "source_name": "orders"})
+
+result = sq.compute(module="stats", function="median", args=[[1.0, 2.0, 3.0], 3])
+print(result["value"], result["invocation_hash"], result["computation_hash"])
+```
+
+- **Query plane** — `connect` / `resolve` / `query` / `verify` / `ask`, in-process via Algenta.
+- **Computation plane** — validated against the embedded capability contract, delegated to
+  the managed runtime; results pass through verbatim with a two-hash determinism envelope
+  (`invocation_hash` before execution, `computation_hash` after).
+- **Policy** — allow-lists for sources, fields, and functions; the default surface is
+  read-only deterministic capabilities, and policy can only narrow it.
+- **Errors** — Algenta codes pass through verbatim (`source="algenta"`); SQAI codes share the
+  same snake_case vocabulary (`source="sqai"`). Messages never leak absolute paths.
+
+The unsafe escape hatch (`from sqai.unsafe import get_unsafe_algenta_runtime`) bypasses every
+guarantee above and is deliberately not exported from the package root.
+
+Apache-2.0.

sqai-0.1.0/README.md

@@ -0,0 +1,32 @@
+# sqai
+
+SQAI — the deterministic, read-only structured-data SDK for AI agents, powered by
+Algenta execution and provenance. Python twin of [`@thyn-ai/sqai`](https://github.com/thyn-ai/sqai):
+same vocabulary, same error codes, same golden numbers, cross-language-identical hashes.
+
+```python
+from sqai import create_sqai
+
+sq = create_sqai()  # zero-config: SQAI_ENGINE_URL -> self_hosted, SQAI_API_KEY -> api, else local
+sq.connect(orders, name="orders")
+
+outcome = sq.ask({"metric": "revenue", "aggregation": "sum", "group_by": "region",
+                  "source_name": "orders"})
+
+result = sq.compute(module="stats", function="median", args=[[1.0, 2.0, 3.0], 3])
+print(result["value"], result["invocation_hash"], result["computation_hash"])
+```
+
+- **Query plane** — `connect` / `resolve` / `query` / `verify` / `ask`, in-process via Algenta.
+- **Computation plane** — validated against the embedded capability contract, delegated to
+  the managed runtime; results pass through verbatim with a two-hash determinism envelope
+  (`invocation_hash` before execution, `computation_hash` after).
+- **Policy** — allow-lists for sources, fields, and functions; the default surface is
+  read-only deterministic capabilities, and policy can only narrow it.
+- **Errors** — Algenta codes pass through verbatim (`source="algenta"`); SQAI codes share the
+  same snake_case vocabulary (`source="sqai"`). Messages never leak absolute paths.
+
+The unsafe escape hatch (`from sqai.unsafe import get_unsafe_algenta_runtime`) bypasses every
+guarantee above and is deliberately not exported from the package root.
+
+Apache-2.0.

sqai-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sqai"
+version = "0.1.0"
+description = "SQAI — the deterministic, read-only structured-data SDK for AI agents, powered by Algenta execution and provenance."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Thyn", email = "eng@thyn.ai" }]
+keywords = [
+    "ai",
+    "agents",
+    "structured-data",
+    "deterministic",
+    "read-only",
+    "algenta",
+    "sqai",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["algenta-core==1.0.5"]
+
+[project.scripts]
+sqai = "sqai.cli:main"
+
+[project.urls]
+Homepage = "https://sqai.com"
+Repository = "https://github.com/thyn-ai/sqai"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sqai"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"sqai/_contract_data.json" = "sqai/_contract_data.json"

sqai-0.1.0/sqai/__init__.py

@@ -0,0 +1,52 @@
+"""sqai — the deterministic, read-only structured-data SDK for AI agents.
+
+Python twin of ``@sqai/sdk``: same vocabulary, same error codes, same golden
+numbers, cross-language-identical hashes. Powered by the algenta-core
+substrate; SQAI validates and delegates, it never calculates.
+"""
+
+from __future__ import annotations
+
+from sqai._contract import ContractIndex, is_read_only_eligible
+from sqai._env import infer_mode, read_env
+from sqai._hashes import computation_hash, invocation_hash
+from sqai._policy import check_field_allowed, check_function_allowed, check_source_allowed
+from sqai._provision import RuntimeProvisioner, current_platform_key, runtime_cache_dir
+from sqai._results import ResultStore
+from sqai._validate import (
+    ResolvedBindingValue,
+    ValidatedComputation,
+    lookup_capability,
+    validate_computation,
+)
+from sqai.client import SQAI, create_sqai
+from sqai.errors import SQAI_ERROR_CODES, SqaiError, from_algenta_error, sanitize_message
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SQAI",
+    "create_sqai",
+    "SqaiError",
+    "SQAI_ERROR_CODES",
+    "from_algenta_error",
+    "sanitize_message",
+    "ContractIndex",
+    "is_read_only_eligible",
+    "invocation_hash",
+    "computation_hash",
+    "ResultStore",
+    "RuntimeProvisioner",
+    "current_platform_key",
+    "runtime_cache_dir",
+    "validate_computation",
+    "lookup_capability",
+    "ResolvedBindingValue",
+    "ValidatedComputation",
+    "check_source_allowed",
+    "check_field_allowed",
+    "check_function_allowed",
+    "read_env",
+    "infer_mode",
+    "__version__",
+]

sqai-0.1.0/sqai/_bundle.py

@@ -0,0 +1,468 @@
+"""Signed managed-runtime bundle verification + installation primitives.
+
+Mirrors the upstream reference verifier (decision-engine
+``scripts/verify_runtime_bundle.py``) — verification fails closed at every
+step:
+
+  1. read manifest.json + manifest.sig bytes FROM the archive (hard size caps
+     BEFORE any allocation — the bundle is attacker-controlled until verified)
+  2. verify the RS256 signature over those EXACT manifest bytes against the
+     embedded trust root (never re-serialize before verifying)
+  3. schema-check the manifest (format version, artifact entries, path safety:
+     reject absolute paths, "..", empty segments) + rollback floor
+  4. stream-hash every artifact member against the signed sha256 + size
+     (regular files only — symlinks / hardlinks / devices rejected)
+  5. reject any archive member the signed manifest does not name
+
+Verification reads the archive with :mod:`tarfile` (the reference verifier's
+tool); the final extraction of the fully verified archive uses the system
+``tar`` binary. Parity-locked with the TypeScript SDK's ``runtime/bundle.ts``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import subprocess
+import tarfile
+from pathlib import Path
+from typing import Any
+
+from sqai._trust import (
+    TrustRoot,
+    TrustVerificationError,
+    compare_runtime_versions,
+    verify_manifest_signature_against_trust_root,
+)
+
+MANIFEST_NAME = "manifest.json"
+MANIFEST_SIG_NAME = "manifest.sig"
+BUNDLE_FORMAT_VERSION = 1
+
+# Hard caps enforced BEFORE the signature is checked (anti-OOM: a tiny gzip
+# member can declare a multi-GB size). Artifacts are additionally bounded by
+# the SIGNED manifest size once the signature verifies.
+MAX_MANIFEST_BYTES = 8 * 1024 * 1024  # 8 MB
+MAX_SIG_BYTES = 64 * 1024  # 64 KB
+MAX_ARTIFACT_BYTES = 4 * 1024 * 1024 * 1024  # 4 GB per artifact
+
+
+class BundleVerificationError(Exception):
+    """Any signature / integrity / path-safety check failed. Fail closed."""
+
+    def __init__(self, reason: str, message: str) -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
+# ── Path safety ───────────────────────────────────────────────────────────────
+
+
+def is_safe_relative_path(path: str) -> bool:
+    """True only for a normalized, relative, traversal-free archive path."""
+    if not path or path.startswith("/") or path.startswith("\\"):
+        return False
+    if "\\" in path or "\x00" in path:
+        return False
+    # Stricter than the reference: control characters are rejected so archive
+    # names, listings, and on-disk paths can never diverge across tools.
+    if any(ord(char) < 0x20 or ord(char) == 0x7F for char in path):
+        return False
+    return all(part not in ("", ".", "..") for part in path.split("/"))
+
+
+def _require_safe_member(info: tarfile.TarInfo) -> None:
+    if not is_safe_relative_path(info.name):
+        raise BundleVerificationError(
+            "unsafe_member", f"unsafe path in bundle member: {info.name!r}"
+        )
+    if info.issym() or info.islnk():
+        raise BundleVerificationError("unsafe_member", f"link member rejected: {info.name!r}")
+    if not (info.isfile() or info.isdir()):
+        raise BundleVerificationError(
+            "unsafe_member", f"non-regular member rejected: {info.name!r}"
+        )
+
+
+# ── Capped member reads ───────────────────────────────────────────────────────
+
+
+def _read_member_bytes(tar: tarfile.TarFile, name: str, max_bytes: int) -> bytes:
+    try:
+        info = tar.getmember(name)
+    except KeyError:
+        raise BundleVerificationError(
+            "member_unreadable", f"bundle is missing member {name!r}"
+        ) from None
+    _require_safe_member(info)
+    if not info.isfile():
+        raise BundleVerificationError(
+            "member_unreadable", f"bundle member {name!r} is not a regular file"
+        )
+    if info.size > max_bytes:
+        raise BundleVerificationError(
+            "member_too_large",
+            f"bundle member {name!r} too large ({info.size} > {max_bytes} cap)",
+        )
+    handle = tar.extractfile(info)
+    if handle is None:
+        raise BundleVerificationError(
+            "member_unreadable", f"could not read bundle member {name!r}"
+        )
+    data = handle.read(max_bytes + 1)
+    if len(data) > max_bytes:
+        raise BundleVerificationError(
+            "member_too_large", f"bundle member {name!r} exceeds {max_bytes}-byte cap"
+        )
+    if len(data) != info.size:
+        raise BundleVerificationError(
+            "member_unreadable",
+            f"bundle member {name!r} size mismatch (header {info.size}, read {len(data)})",
+        )
+    return data
+
+
+# ── Hashing helpers ───────────────────────────────────────────────────────────
+
+
+def sha256_file(path: str | Path) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def digests_equal(actual_hex: str, expected_hex: str) -> bool:
+    """Constant-time hex digest comparison (mirrors hmac.compare_digest)."""
+    return hmac.compare_digest(actual_hex.lower(), expected_hex.lower())
+
+
+# ── Manifest schema ───────────────────────────────────────────────────────────
+
+
+def parse_verified_manifest(manifest_bytes: bytes) -> dict[str, Any]:
+    """json.loads AFTER signature verification, then schema + path-safety checks."""
+    try:
+        manifest = json.loads(manifest_bytes)
+    except Exception as exc:  # noqa: BLE001
+        raise BundleVerificationError(
+            "manifest_schema_invalid", f"manifest verified but is not valid JSON: {exc}"
+        ) from exc
+    if not isinstance(manifest, dict):
+        raise BundleVerificationError("manifest_schema_invalid", "manifest is not a JSON object")
+    if manifest.get("bundle_format_version") != BUNDLE_FORMAT_VERSION:
+        raise BundleVerificationError(
+            "manifest_schema_invalid",
+            f"unsupported bundle_format_version: {manifest.get('bundle_format_version')!r}",
+        )
+    for field in ("runtime_bundle_version", "platform", "created_at"):
+        if not isinstance(manifest.get(field), str) or not manifest[field]:
+            raise BundleVerificationError(
+                "manifest_schema_invalid", f"manifest missing string field {field!r}"
+            )
+    if not isinstance(manifest.get("engine_stub"), bool):
+        raise BundleVerificationError(
+            "manifest_schema_invalid", "manifest missing boolean field 'engine_stub'"
+        )
+    artifacts = manifest.get("artifacts")
+    if not isinstance(artifacts, list) or not artifacts:
+        raise BundleVerificationError(
+            "manifest_schema_invalid", "manifest missing a non-empty 'artifacts' list"
+        )
+    seen: set[str] = set()
+    for entry in artifacts:
+        if not (
+            isinstance(entry, dict)
+            and isinstance(entry.get("path"), str)
+            and isinstance(entry.get("sha256"), str)
+            and len(entry["sha256"]) == 64
+            and isinstance(entry.get("size"), int)
+            and not isinstance(entry.get("size"), bool)
+            and entry["size"] >= 0
+        ):
+            raise BundleVerificationError(
+                "manifest_schema_invalid", f"manifest artifact entry malformed: {entry!r}"
+            )
+        path = entry["path"]
+        if not is_safe_relative_path(path) or path in (MANIFEST_NAME, MANIFEST_SIG_NAME):
+            raise BundleVerificationError(
+                "manifest_schema_invalid", f"unsafe artifact path in manifest: {path!r}"
+            )
+        if path in seen:
+            raise BundleVerificationError(
+                "manifest_schema_invalid", f"duplicate artifact path in manifest: {path!r}"
+            )
+        seen.add(path)
+    return manifest
+
+
+# ── Cross-cutting manifest policy (trust root, rollback, pins) ────────────────
+
+
+def _verify_manifest_policy(
+    manifest: dict[str, Any],
+    *,
+    trust_root: TrustRoot,
+    expected_version: str | None,
+    expected_platform: str | None,
+) -> None:
+    version = manifest["runtime_bundle_version"]
+    if compare_runtime_versions(version, trust_root.min_accepted_runtime_version) < 0:
+        raise BundleVerificationError(
+            "rollback_protected",
+            f"bundle version {version} is below the minimum accepted runtime version "
+            f"{trust_root.min_accepted_runtime_version} (rollback protection)",
+        )
+    if expected_version is not None and version != expected_version:
+        raise BundleVerificationError(
+            "version_mismatch",
+            f"bundle manifest carries version {version}, expected {expected_version}",
+        )
+    if expected_platform is not None and manifest["platform"] != expected_platform:
+        raise BundleVerificationError(
+            "bundle_platform_mismatch",
+            f"bundle targets platform '{manifest['platform']}', expected '{expected_platform}'",
+        )
+
+
+def _verify_signature_bytes(
+    manifest_bytes: bytes, signature: bytes, trust_root: TrustRoot
+) -> str:
+    try:
+        return verify_manifest_signature_against_trust_root(manifest_bytes, signature, trust_root)
+    except TrustVerificationError as exc:
+        raise BundleVerificationError(exc.reason, str(exc)) from exc
+
+
+# ── Full tarball verification (reference-verifier mirror) ─────────────────────
+
+
+def _stream_sha256(tar: tarfile.TarFile, info: tarfile.TarInfo, cap: int) -> tuple[str, int]:
+    handle = tar.extractfile(info)
+    if handle is None:
+        raise BundleVerificationError("artifact_missing", f"could not read artifact {info.name!r}")
+    digest = hashlib.sha256()
+    total = 0
+    while True:
+        chunk = handle.read(1 << 20)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > cap:
+            raise BundleVerificationError(
+                "artifact_size_mismatch", f"artifact {info.name!r} exceeds {cap}-byte cap"
+            )
+        digest.update(chunk)
+    return digest.hexdigest(), total
+
+
+def verify_bundle_tarball(
+    tarball: str | Path,
+    *,
+    trust_root: TrustRoot,
+    expected_version: str | None = None,
+    expected_platform: str | None = None,
+) -> dict[str, Any]:
+    """Verify signature, per-artifact integrity, and path safety of a bundle
+    tarball WITHOUT extracting anything. Returns the verified manifest."""
+    tarball = Path(tarball)
+    if not tarball.is_file():
+        raise BundleVerificationError("archive_unreadable", f"bundle not found: {tarball.name}")
+
+    try:
+        tar = tarfile.open(tarball, "r:*")
+    except Exception as exc:  # noqa: BLE001 — corrupt archives fail closed
+        raise BundleVerificationError(
+            "archive_unreadable", f"the bundle archive could not be opened: {exc}"
+        ) from exc
+    with tar:
+        # 1 + 2: signature over the exact manifest bytes, before trusting anything.
+        manifest_bytes = _read_member_bytes(tar, MANIFEST_NAME, MAX_MANIFEST_BYTES)
+        signature = _read_member_bytes(tar, MANIFEST_SIG_NAME, MAX_SIG_BYTES)
+        _verify_signature_bytes(manifest_bytes, signature, trust_root)
+
+        # 3: schema + path safety of the now-trusted manifest, plus rollback
+        #    floor and contract pins.
+        manifest = parse_verified_manifest(manifest_bytes)
+        _verify_manifest_policy(
+            manifest,
+            trust_root=trust_root,
+            expected_version=expected_version,
+            expected_platform=expected_platform,
+        )
+        by_path = {entry["path"]: entry for entry in manifest["artifacts"]}
+
+        # 4 + 5: walk EVERY archive member — safety-check all, hash the listed,
+        # reject unlisted regular files.
+        verified: set[str] = set()
+        for info in tar.getmembers():
+            _require_safe_member(info)
+            if info.isdir():
+                continue
+            if info.name in (MANIFEST_NAME, MANIFEST_SIG_NAME):
+                continue
+            entry = by_path.get(info.name)
+            if entry is None:
+                raise BundleVerificationError(
+                    "unlisted_member",
+                    f"archive member not listed in signed manifest: {info.name!r}",
+                )
+            cap = min(int(entry["size"]), MAX_ARTIFACT_BYTES)
+            actual_sha, actual_size = _stream_sha256(tar, info, cap)
+            if actual_size != entry["size"]:
+                raise BundleVerificationError(
+                    "artifact_size_mismatch",
+                    f"artifact {info.name!r} size mismatch "
+                    f"(manifest {entry['size']}, actual {actual_size})",
+                )
+            if not digests_equal(actual_sha, entry["sha256"]):
+                raise BundleVerificationError(
+                    "artifact_hash_mismatch",
+                    f"artifact integrity check FAILED for {info.name!r}: "
+                    f"expected {entry['sha256'][:12]}…, got {actual_sha[:12]}…",
+                )
+            verified.add(info.name)
+
+        missing = sorted(set(by_path) - verified)
+        if missing:
+            raise BundleVerificationError(
+                "artifact_missing",
+                f"manifest artifacts missing from archive: {', '.join(missing[:5])}",
+            )
+    return manifest
+
+
+# ── Extraction (system tar, only after full verification) ────────────────────
+
+
+def extract_tarball(tarball: str | Path, destination_dir: str | Path) -> None:
+    """Extract the (already fully verified) archive with the system tar."""
+    destination = Path(destination_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run(  # noqa: S603 — fixed argv, no shell
+        ["tar", "-xf", str(tarball), "-C", str(destination)],
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise BundleVerificationError(
+            "extract_failed",
+            f"tar extraction failed (exit {result.returncode}): {result.stderr[:300]}",
+        )
+
+
+# ── Installed-directory verification (same contract, on-disk) ────────────────
+
+
+def _read_installed_bytes(path: Path, max_bytes: int) -> bytes:
+    try:
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > max_bytes:
+            raise BundleVerificationError(
+                "member_unreadable",
+                "installed bundle manifest/signature is not a capped regular file",
+            )
+        return path.read_bytes()
+    except BundleVerificationError:
+        raise
+    except OSError as exc:
+        raise BundleVerificationError(
+            "member_unreadable", "installed bundle is missing manifest.json / manifest.sig"
+        ) from exc
+
+
+def verify_installed_bundle_dir(
+    install_dir: str | Path,
+    *,
+    trust_root: TrustRoot,
+    expected_version: str | None = None,
+    expected_platform: str | None = None,
+) -> dict[str, Any]:
+    """Re-verify an installed bundle directory against the trust root: manifest
+    signature, schema, rollback floor, and every artifact's sha256 + size; any
+    file on disk the signed manifest does not name is rejected."""
+    install_dir = Path(install_dir)
+    manifest_bytes = _read_installed_bytes(install_dir / MANIFEST_NAME, MAX_MANIFEST_BYTES)
+    signature = _read_installed_bytes(install_dir / MANIFEST_SIG_NAME, MAX_SIG_BYTES)
+    _verify_signature_bytes(manifest_bytes, signature, trust_root)
+    manifest = parse_verified_manifest(manifest_bytes)
+    _verify_manifest_policy(
+        manifest,
+        trust_root=trust_root,
+        expected_version=expected_version,
+        expected_platform=expected_platform,
+    )
+    by_path = {entry["path"]: entry for entry in manifest["artifacts"]}
+
+    verified: set[str] = set()
+    for root, _dirs, files in os.walk(install_dir, followlinks=False):
+        for name in files:
+            absolute = Path(root) / name
+            rel_path = absolute.relative_to(install_dir).as_posix()
+            if absolute.is_symlink():
+                raise BundleVerificationError(
+                    "unsafe_member", f"symlink in installed bundle rejected: {rel_path!r}"
+                )
+            if rel_path in (MANIFEST_NAME, MANIFEST_SIG_NAME):
+                continue
+            entry = by_path.get(rel_path)
+            if entry is None:
+                raise BundleVerificationError(
+                    "unlisted_member",
+                    f"installed file not listed in signed manifest: {rel_path!r}",
+                )
+            stat = absolute.lstat()
+            if stat.st_nlink > 1:
+                raise BundleVerificationError(
+                    "unsafe_member", f"hardlinked file in installed bundle rejected: {rel_path!r}"
+                )
+            if stat.st_size != entry["size"]:
+                raise BundleVerificationError(
+                    "artifact_size_mismatch",
+                    f"installed artifact {rel_path!r} size mismatch "
+                    f"(manifest {entry['size']}, actual {stat.st_size})",
+                )
+            if not digests_equal(sha256_file(absolute), entry["sha256"]):
+                raise BundleVerificationError(
+                    "artifact_hash_mismatch",
+                    f"installed artifact integrity check FAILED for {rel_path!r}",
+                )
+            verified.add(rel_path)
+
+    missing = sorted(set(by_path) - verified)
+    if missing:
+        raise BundleVerificationError(
+            "artifact_missing",
+            f"manifest artifacts missing from installed bundle: {', '.join(missing[:5])}",
+        )
+    return manifest
+
+
+# ── Daemon entry derivation ───────────────────────────────────────────────────
+
+
+def daemon_entry_from_manifest(manifest: dict[str, Any]) -> str:
+    """The daemon entry executable, derived from the signed manifest: the
+    single regular file directly under ``daemon/`` (PyInstaller onedir keeps
+    everything else in ``daemon/_internal/``). Returns a bundle-relative path."""
+    candidates = [
+        entry["path"]
+        for entry in manifest["artifacts"]
+        if len(entry["path"].split("/")) == 2 and entry["path"].split("/")[0] == "daemon"
+    ]
+    if not candidates:
+        raise BundleVerificationError(
+            "daemon_entry_not_found",
+            "the signed manifest lists no daemon entry executable under daemon/",
+        )
+    if len(candidates) > 1:
+        raise BundleVerificationError(
+            "daemon_entry_ambiguous",
+            f"the signed manifest lists multiple candidate daemon entries: "
+            f"{', '.join(candidates)}",
+        )
+    return candidates[0]