field_ios

In-the-field app for Radroots on iOS
git clone https://radroots.dev/git/field_ios.git
Log | Files | Refs | README | LICENSE

package_contract.py (26200B)


      1 #!/usr/bin/env python3
      2 """Structured standalone package-contract verification for the iOS capsule."""
      3 
      4 from __future__ import annotations
      5 
      6 import argparse
      7 import hashlib
      8 import json
      9 import os
     10 import plistlib
     11 import re
     12 import subprocess
     13 import sys
     14 import tempfile
     15 import tomllib
     16 from collections.abc import Mapping
     17 from pathlib import Path
     18 from typing import Any
     19 
     20 import app_dependency_graph
     21 import legacy_identifiers
     22 import package_privacy
     23 
     24 MAX_CONTRACT_BYTES = 2 * 1024 * 1024
     25 # The resolved generator graph exceeds the per-file contract bound.
     26 MAX_CARGO_METADATA_BYTES = 4 * 1024 * 1024
     27 GIT_REVISION = re.compile(r"^[0-9a-f]{40}$")
     28 SHA256 = re.compile(r"^[0-9a-f]{64}$")
     29 APPLE_KIT_REMOTE = "https://github.com/radrootslabs/apple_kit.git"
     30 LIB_REMOTE = "https://github.com/radrootslabs/lib"
     31 SECP256K1_REMOTE = "https://github.com/21-DOT-DEV/swift-secp256k1.git"
     32 SECP256K1_REVISION = "e70a10e036a55fffea31568f0af92d69b6d449cd"
     33 
     34 
     35 class PackageContractError(Exception):
     36     """A stable, source-free package-contract rejection."""
     37 
     38 
     39 def _read_regular(path: Path, *, maximum: int = MAX_CONTRACT_BYTES) -> bytes:
     40     try:
     41         if path.is_symlink() or not path.is_file():
     42             raise PackageContractError("required contract input is not a regular file")
     43         size = path.stat().st_size
     44         if size < 0 or size > maximum:
     45             raise PackageContractError("required contract input exceeds its byte limit")
     46         value = path.read_bytes()
     47     except OSError as error:
     48         raise PackageContractError("required contract input cannot be read") from error
     49     if len(value) != size:
     50         raise PackageContractError("required contract input changed while reading")
     51     return value
     52 
     53 
     54 def _read_text(path: Path) -> str:
     55     try:
     56         return _read_regular(path).decode("utf-8")
     57     except UnicodeDecodeError as error:
     58         raise PackageContractError("required contract input is not UTF-8") from error
     59 
     60 
     61 def _read_toml(path: Path) -> dict[str, Any]:
     62     try:
     63         value = tomllib.loads(_read_text(path))
     64     except tomllib.TOMLDecodeError as error:
     65         raise PackageContractError("required TOML contract is malformed") from error
     66     if not isinstance(value, dict):
     67         raise PackageContractError("required TOML contract is not an object")
     68     return value
     69 
     70 
     71 def validate_source_date_epoch(value: object) -> int:
     72     if type(value) is not int or value <= 0:
     73         raise PackageContractError("producer source epoch is invalid")
     74     return value
     75 
     76 
     77 def producer_source_epoch(root: Path) -> int:
     78     producer = _read_toml(root / "TeraFFI/producer.toml")
     79     build = _mapping(producer.get("build"), "producer build")
     80     return validate_source_date_epoch(build.get("source_date_epoch"))
     81 
     82 
     83 def _read_json(path: Path) -> dict[str, Any]:
     84     try:
     85         value = json.loads(_read_text(path))
     86     except json.JSONDecodeError as error:
     87         raise PackageContractError("required JSON contract is malformed") from error
     88     if not isinstance(value, dict):
     89         raise PackageContractError("required JSON contract is not an object")
     90     return value
     91 
     92 
     93 def _read_plist(path: Path) -> dict[str, Any]:
     94     try:
     95         value = plistlib.loads(_read_regular(path))
     96     except (plistlib.InvalidFileException, ValueError, TypeError) as error:
     97         raise PackageContractError("required plist contract is malformed") from error
     98     if not isinstance(value, dict):
     99         raise PackageContractError("required plist contract is not a dictionary")
    100     return value
    101 
    102 
    103 def _mapping(value: object, key: str) -> Mapping[str, Any]:
    104     if not isinstance(value, Mapping):
    105         raise PackageContractError(f"structured contract field is invalid: {key}")
    106     return value
    107 
    108 
    109 def _exact(value: object, expected: object, key: str) -> None:
    110     if value != expected:
    111         raise PackageContractError(f"structured contract field differs: {key}")
    112 
    113 
    114 def parse_xcconfig_assignments(text: str) -> dict[str, str]:
    115     assignments: dict[str, str] = {}
    116     expression = re.compile(r"^([A-Z][A-Z0-9_]*)\s*=\s*(\S(?:.*\S)?)$")
    117     for raw in text.splitlines():
    118         line = raw.strip()
    119         if not line or line.startswith("//") or line.startswith("#"):
    120             continue
    121         match = expression.fullmatch(line)
    122         if match is None:
    123             raise PackageContractError("xcconfig contains an unsupported statement")
    124         key, value = match.groups()
    125         if key in assignments:
    126             raise PackageContractError("xcconfig assignment is duplicated")
    127         assignments[key] = value
    128     return assignments
    129 
    130 
    131 def parse_project_package(text: str, package_name: str) -> dict[str, str]:
    132     lines = text.splitlines()
    133     packages_line, packages_end = _project_package_bounds(lines)
    134     start = _project_package_start(lines, packages_line, packages_end, package_name)
    135     return _project_package_fields(lines[start + 1 :])
    136 
    137 
    138 def _project_package_bounds(lines: list[str]) -> tuple[int, int]:
    139     start = next(
    140         (index for index, line in enumerate(lines) if line == "packages:"), None
    141     )
    142     if start is None:
    143         raise PackageContractError("project package inventory is absent")
    144     end = next(
    145         (
    146             index
    147             for index in range(start + 1, len(lines))
    148             if lines[index] and not lines[index].startswith((" ", "#"))
    149         ),
    150         len(lines),
    151     )
    152     return start, end
    153 
    154 
    155 def _project_package_start(
    156     lines: list[str], start: int, end: int, package_name: str
    157 ) -> int:
    158     expected = f"  {package_name}:"
    159     result = next(
    160         (index for index in range(start + 1, end) if lines[index] == expected), None
    161     )
    162     if result is None:
    163         raise PackageContractError("project package entry is absent")
    164     return result
    165 
    166 
    167 def _project_package_fields(lines: list[str]) -> dict[str, str]:
    168     values: dict[str, str] = {}
    169     for line in lines:
    170         if line and not line.startswith("    "):
    171             break
    172         match = re.fullmatch(r"    ([a-z_]+): (\S+)", line)
    173         if match is None:
    174             if line.strip():
    175                 raise PackageContractError("project package entry is malformed")
    176             continue
    177         key, value = match.groups()
    178         if key in values:
    179             raise PackageContractError("project package field is duplicated")
    180         values[key] = value
    181     return values
    182 
    183 
    184 def validate_resolved(document: dict[str, Any], apple_revision: str) -> None:
    185     _exact(document.get("version"), 3, "package lock version")
    186     pins = document.get("pins")
    187     if not isinstance(pins, list) or len(pins) != 2:
    188         raise PackageContractError("package lock pin inventory differs")
    189     selected: dict[str, str] = {}
    190     for pin in pins:
    191         item = _mapping(pin, "package lock pin")
    192         _exact(item.get("kind"), "remoteSourceControl", "package lock pin kind")
    193         location = item.get("location")
    194         state = _mapping(item.get("state"), "package lock pin state")
    195         revision = state.get("revision")
    196         if not isinstance(location, str) or not location.startswith("https://"):
    197             raise PackageContractError("package lock location is invalid")
    198         if not isinstance(revision, str) or GIT_REVISION.fullmatch(revision) is None:
    199             raise PackageContractError("package lock revision is invalid")
    200         if location in selected:
    201             raise PackageContractError("package lock location is duplicated")
    202         selected[location] = revision
    203     _exact(selected.get(APPLE_KIT_REMOTE), apple_revision, "AppleKit package pin")
    204     _exact(
    205         selected.get(SECP256K1_REMOTE),
    206         SECP256K1_REVISION,
    207         "secp256k1 package pin",
    208     )
    209 
    210 
    211 def _swift_package(repo_root: Path) -> dict[str, Any]:
    212     with tempfile.TemporaryFile() as stdout, tempfile.TemporaryFile() as stderr:
    213         try:
    214             result = subprocess.run(
    215                 [
    216                     "swift",
    217                     "package",
    218                     "--package-path",
    219                     str(repo_root),
    220                     "dump-package",
    221                 ],
    222                 check=False,
    223                 stdout=stdout,
    224                 stderr=stderr,
    225                 timeout=60,
    226             )
    227         except (OSError, subprocess.TimeoutExpired) as error:
    228             raise PackageContractError(
    229                 "Swift package manifest cannot be evaluated"
    230             ) from error
    231         stdout.seek(0)
    232         output = stdout.read(MAX_CONTRACT_BYTES + 1)
    233     if result.returncode != 0 or len(output) > MAX_CONTRACT_BYTES:
    234         raise PackageContractError("Swift package manifest evaluation failed")
    235     try:
    236         value = json.loads(output)
    237     except (UnicodeDecodeError, json.JSONDecodeError) as error:
    238         raise PackageContractError(
    239             "Swift package manifest output is malformed"
    240         ) from error
    241     if not isinstance(value, dict):
    242         raise PackageContractError("Swift package manifest output is not an object")
    243     return value
    244 
    245 
    246 def _apple_revision(package: dict[str, Any]) -> str:
    247     dependencies = package.get("dependencies")
    248     if not isinstance(dependencies, list):
    249         raise PackageContractError("Swift package dependencies are absent")
    250     matches: list[str] = []
    251     for dependency in dependencies:
    252         candidate = _apple_dependency_revision(dependency)
    253         if candidate is not None:
    254             matches.append(candidate)
    255     if (
    256         len(matches) != 1
    257         or not isinstance(matches[0], str)
    258         or GIT_REVISION.fullmatch(matches[0]) is None
    259     ):
    260         raise PackageContractError("AppleKit dependency is not one exact revision")
    261     return matches[0]
    262 
    263 
    264 def _apple_dependency_revision(dependency: object) -> object | None:
    265     item = _mapping(dependency, "Swift package dependency")
    266     source = item.get("sourceControl")
    267     if not isinstance(source, list) or len(source) != 1:
    268         return None
    269     identity = _mapping(source[0], "Swift package source")
    270     remote = identity.get("location")
    271     requirement = identity.get("requirement")
    272     remote_values = remote.get("remote") if isinstance(remote, dict) else None
    273     if remote_values != [{"urlString": APPLE_KIT_REMOTE}]:
    274         return None
    275     if not isinstance(requirement, dict):
    276         return None
    277     revisions = requirement.get("revision")
    278     if not isinstance(revisions, list) or len(revisions) != 1:
    279         return None
    280     return revisions[0]
    281 
    282 
    283 def _validate_privacy(document: dict[str, Any]) -> None:
    284     try:
    285         package_privacy.validate_manifest(document)
    286     except ValueError as error:
    287         raise PackageContractError(str(error)) from error
    288 
    289 
    290 def _validate_app_plist(document: dict[str, Any]) -> None:
    291     for key in (
    292         "NSCameraUsageDescription",
    293         "NSFaceIDUsageDescription",
    294         "NSLocalNetworkUsageDescription",
    295     ):
    296         value = document.get(key)
    297         if not isinstance(value, str) or not value.strip():
    298             raise PackageContractError(f"required plist purpose is absent: {key}")
    299     try:
    300         package_privacy.validate_purposes(document)
    301     except ValueError as error:
    302         raise PackageContractError(str(error)) from error
    303     _exact(
    304         document.get("NSAppTransportSecurity"),
    305         {"NSAllowsLocalNetworking": True},
    306         "app transport security",
    307     )
    308     for forbidden in ("NSBonjourServices", "NSPhotoLibraryUsageDescription"):
    309         if forbidden in document:
    310             raise PackageContractError(f"forbidden plist field is present: {forbidden}")
    311 
    312     _exact(document.get("CFBundleDisplayName"), "Tera", "app display name")
    313     _exact(document.get("CFBundleName"), "$(PRODUCT_NAME)", "app bundle name")
    314 
    315 
    316 def _validate_ui_test_plist(document: dict[str, Any]) -> None:
    317     required = {
    318         "TERA_IOS_UI_TEST_FIXTURE_CONTROL",
    319         "TERA_IOS_UI_TEST_FIXTURE_EVIDENCE",
    320         "TERA_IOS_UI_TEST_NETWORK_PROFILE",
    321         "TERA_IOS_UI_TEST_SOURCE_COMMIT",
    322         "TERA_IOS_UI_TEST_SOURCE_TREE",
    323         "TERA_IOS_UI_TEST_APP_BUILD_SHA256",
    324         "TERA_IOS_UI_TEST_SIMULATOR_ID",
    325     }
    326     if required.difference(document):
    327         raise PackageContractError("UI test plist inventory is incomplete")
    328 
    329 
    330 def _verify_repository_layout(root: Path) -> None:
    331     for forbidden in ("docs", ".github", ".act"):
    332         path = root / forbidden
    333         if path.exists() or path.is_symlink():
    334             raise PackageContractError("forbidden public repository root exists")
    335 
    336 
    337 def _cargo_workspace(root: Path, *, resolved: bool = False) -> dict[str, Any]:
    338     with tempfile.TemporaryFile() as stdout, tempfile.TemporaryFile() as stderr:
    339         try:
    340             result = subprocess.run(
    341                 [
    342                     "cargo",
    343                     "metadata",
    344                     "--manifest-path",
    345                     str(root / "Cargo.toml"),
    346                     "--locked",
    347                     *([] if resolved else ["--no-deps"]),
    348                     "--offline",
    349                     "--format-version",
    350                     "1",
    351                 ],
    352                 check=False,
    353                 stdin=subprocess.DEVNULL,
    354                 stdout=stdout,
    355                 stderr=stderr,
    356                 timeout=60,
    357             )
    358         except (OSError, subprocess.TimeoutExpired) as error:
    359             raise PackageContractError("Cargo workspace cannot be evaluated") from error
    360         stdout.seek(0)
    361         output = stdout.read(MAX_CARGO_METADATA_BYTES + 1)
    362     if result.returncode != 0 or len(output) > MAX_CARGO_METADATA_BYTES:
    363         raise PackageContractError("Cargo workspace evaluation failed")
    364     try:
    365         value = json.loads(output)
    366     except (UnicodeDecodeError, json.JSONDecodeError) as error:
    367         raise PackageContractError("Cargo workspace output is malformed") from error
    368     if not isinstance(value, dict):
    369         raise PackageContractError("Cargo workspace output is not an object")
    370     return value
    371 
    372 
    373 def _local_cargo_path(value: object, root: Path) -> Path:
    374     if not isinstance(value, str) or not value:
    375         raise PackageContractError("local Cargo path is invalid")
    376     path = Path(value).resolve()
    377     if not path.is_relative_to(root.resolve()):
    378         raise PackageContractError("local Cargo path escapes the standalone repository")
    379     return path.relative_to(root.resolve())
    380 
    381 
    382 def _validate_app_workspace(document: dict[str, Any], root: Path) -> None:
    383     _exact(document.get("workspace_root"), str(root), "Cargo workspace root")
    384     packages = document.get("packages")
    385     members = document.get("workspace_members")
    386     if not isinstance(packages, list) or not packages or not isinstance(members, list):
    387         raise PackageContractError("Cargo workspace members are absent")
    388     identifiers = [
    389         package.get("id") for package in packages if isinstance(package, dict)
    390     ]
    391     if not all(isinstance(item, str) for item in identifiers + members):
    392         raise PackageContractError("Cargo workspace member identity is invalid")
    393     _exact(sorted(identifiers), sorted(members), "Cargo workspace member inventory")
    394     for package in packages:
    395         _validate_app_package(_mapping(package, "Cargo package"), root)
    396     _validate_mobile_defaults(document, packages, root)
    397 
    398 
    399 def _validate_mobile_defaults(
    400     document: Mapping[str, Any], packages: list[Any], root: Path
    401 ) -> None:
    402     owned = {
    403         _local_cargo_path(package.get("manifest_path"), root).parent.name: package["id"]
    404         for package in packages
    405     }
    406     if "tera_wasm" not in owned:
    407         return
    408     defaults = document.get("workspace_default_members")
    409     if not isinstance(defaults, list) or owned["tera_wasm"] in defaults:
    410         raise PackageContractError("non-default WASM package entered mobile defaults")
    411     for name in ("tera_core", "tera_ffi"):
    412         if name in owned and owned[name] not in defaults:
    413             raise PackageContractError("owned runtime is missing from mobile defaults")
    414 
    415 
    416 def _validate_app_package(package: Mapping[str, Any], root: Path) -> None:
    417     manifest = _local_cargo_path(package.get("manifest_path"), root)
    418     directory = manifest.parent
    419     if not directory.is_relative_to("core/crates"):
    420         raise PackageContractError("application Rust package is outside its owned root")
    421     dependencies = package.get("dependencies")
    422     if not isinstance(dependencies, list):
    423         raise PackageContractError("Cargo dependency inventory is absent")
    424     for dependency in dependencies:
    425         item = _mapping(dependency, "Cargo dependency")
    426         if "path" in item:
    427             _local_cargo_path(item["path"], root)
    428 
    429 
    430 def _verify_cargo_and_source(root: Path) -> tuple[str, str]:
    431     cargo = _read_toml(root / "Cargo.toml")
    432     workspace = _mapping(cargo.get("workspace"), "Cargo workspace")
    433     workspace_package = _mapping(workspace.get("package"), "Cargo workspace package")
    434     _exact(
    435         workspace_package.get("repository"),
    436         "https://github.com/radrootslabs/tera",
    437         "Cargo repository",
    438     )
    439     consumer = _read_toml(root / "radroots.lib.source-lock.v1.toml")
    440     _exact(consumer.get("repository"), LIB_REMOTE, "consumer Lib remote")
    441     lib_revision = consumer.get("revision")
    442     if (
    443         not isinstance(lib_revision, str)
    444         or GIT_REVISION.fullmatch(lib_revision) is None
    445     ):
    446         raise PackageContractError("consumer Lib revision is invalid")
    447     release_version = consumer.get("version")
    448     _exact(release_version, "0.1.0-alpha", "consumer Lib version")
    449     try:
    450         app_dependency_graph.validate(_cargo_workspace(root, resolved=True), consumer)
    451     except app_dependency_graph.GraphError as error:
    452         raise PackageContractError(str(error)) from error
    453     _verify_owned_source_lock(root, consumer)
    454     return release_version, lib_revision
    455 
    456 
    457 def _verify_owned_source_lock(root: Path, foundation: dict[str, Any]) -> None:
    458     lock = _read_toml(root / "TeraFFI/source.lock")
    459     _exact(
    460         set(lock),
    461         {
    462             "schema",
    463             "repository",
    464             "source_tree",
    465             "manifest_sha256",
    466             "source_date_epoch",
    467             "foundation",
    468         },
    469         "installed source fields",
    470     )
    471     _exact(lock["schema"], "tera.installed-source.v2", "installed source schema")
    472     _exact(
    473         lock["repository"], "https://github.com/radrootslabs/tera", "installed producer"
    474     )
    475     _exact(
    476         lock["foundation"],
    477         {key: foundation[key] for key in ("repository", "revision", "version")},
    478         "installed foundation",
    479     )
    480     if (
    481         not isinstance(lock["source_tree"], str)
    482         or GIT_REVISION.fullmatch(lock["source_tree"]) is None
    483     ):
    484         raise PackageContractError("installed source tree is invalid")
    485     _exact(
    486         validate_source_date_epoch(lock["source_date_epoch"]),
    487         producer_source_epoch(root),
    488         "installed source epoch",
    489     )
    490     _exact(
    491         lock["manifest_sha256"],
    492         hashlib.sha256(_read_regular(root / "TeraFFI/provenance.json")).hexdigest(),
    493         "installed manifest digest",
    494     )
    495 
    496 
    497 def _verify_apple_dependencies(root: Path) -> str:
    498     package = _swift_package(root)
    499     _exact(package.get("name"), "tera", "Swift package name")
    500     _exact(package.get("defaultLocalization"), "en", "Swift localization")
    501     apple_revision = _apple_revision(package)
    502     project = parse_project_package(_read_text(root / "project.yml"), "RadrootsKit")
    503     if set(project) != {"url", "revision"}:
    504         raise PackageContractError("project AppleKit field inventory differs")
    505     _exact(project.get("url"), APPLE_KIT_REMOTE, "project AppleKit remote")
    506     _exact(project.get("revision"), apple_revision, "project AppleKit revision")
    507     return apple_revision
    508 
    509 
    510 def _verify_apple_configuration(root: Path) -> None:
    511     _validate_privacy(_read_plist(root / "Tera/Resources/PrivacyInfo.xcprivacy"))
    512     _validate_app_plist(_read_plist(root / "Tera/Info.plist"))
    513     _validate_ui_test_plist(_read_plist(root / "TeraUITests/Info.plist"))
    514 
    515     base = parse_xcconfig_assignments(_read_text(root / "Tera/Config/Base.xcconfig"))
    516     debug = parse_xcconfig_assignments(_read_text(root / "Tera/Config/Debug.xcconfig"))
    517     if set(base) != {
    518         "TERA_IOS_RUNTIME_MODE",
    519         "TERA_IOS_NOSTR_RELAY_URLS",
    520         "TERA_IOS_BLOSSOM_ORIGINS",
    521         "TERA_IOS_KEYCHAIN_SERVICE_PREFIX",
    522     }:
    523         raise PackageContractError("base xcconfig field inventory differs")
    524     if set(debug) != {
    525         "TERA_IOS_RUNTIME_MODE",
    526         "PRODUCT_BUNDLE_IDENTIFIER",
    527         "TERA_IOS_NOSTR_RELAY_URLS",
    528         "TERA_IOS_BLOSSOM_ORIGINS",
    529         "TERA_IOS_KEYCHAIN_SERVICE_PREFIX",
    530     }:
    531         raise PackageContractError("debug xcconfig field inventory differs")
    532     _exact(
    533         base.get("TERA_IOS_NOSTR_RELAY_URLS"),
    534         "wss:$(SLASH)$(SLASH)radroots.org$(SLASH)",
    535         "base relay",
    536     )
    537     _exact(
    538         base.get("TERA_IOS_BLOSSOM_ORIGINS"),
    539         "https:$(SLASH)$(SLASH)blossom.radroots.org",
    540         "base Blossom origin",
    541     )
    542     _exact(
    543         debug.get("TERA_IOS_NOSTR_RELAY_URLS"),
    544         "ws:$(SLASH)$(SLASH)127.0.0.1:21000",
    545         "debug relay",
    546     )
    547     _exact(
    548         debug.get("TERA_IOS_BLOSSOM_ORIGINS"),
    549         "http:$(SLASH)$(SLASH)127.0.0.1:21100",
    550         "debug Blossom origin",
    551     )
    552     _verify_installation_compatibility(root, base, debug)
    553 
    554 
    555 def _verify_installation_compatibility(
    556     root: Path, base: dict[str, str], debug: dict[str, str]
    557 ) -> None:
    558     baseline = _read_json(root / "test-fixtures/tera-compatibility.v1.json")
    559     _exact(
    560         baseline.get("schema"), "tera.compatibility-baseline.v1", "compatibility schema"
    561     )
    562     production = parse_xcconfig_assignments(_read_text(root / "Tera/tera.xcconfig"))
    563     actual = {
    564         "production_bundle_identifier": production.get("PRODUCT_BUNDLE_IDENTIFIER"),
    565         "debug_bundle_identifier": debug.get("PRODUCT_BUNDLE_IDENTIFIER"),
    566         "production_keychain_service_prefix": base.get(
    567             "TERA_IOS_KEYCHAIN_SERVICE_PREFIX"
    568         ),
    569         "debug_keychain_service_prefix": debug.get("TERA_IOS_KEYCHAIN_SERVICE_PREFIX"),
    570     }
    571     _exact(actual, baseline.get("installation"), "installed identity compatibility")
    572 
    573 
    574 def _verify_package_locks(root: Path, apple_revision: str) -> None:
    575     resolved_paths = (
    576         root / "Package.resolved",
    577         root
    578         / "Tera.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved",
    579     )
    580     resolved = [_read_json(path) for path in resolved_paths]
    581     for document in resolved:
    582         validate_resolved(document, apple_revision)
    583     if resolved[0].get("pins") != resolved[1].get("pins"):
    584         raise PackageContractError("Swift and Xcode package locks disagree")
    585 
    586 
    587 def _verify_persona_toolchain(root: Path) -> None:
    588     verifier_project = _read_toml(root / "scripts/persona-verifier/pyproject.toml")
    589     verifier_lock = _read_toml(root / "scripts/persona-verifier/uv.lock")
    590     verifier_metadata = _mapping(verifier_project.get("project"), "verifier project")
    591     _exact(
    592         verifier_metadata.get("requires-python"),
    593         "==3.14.7",
    594         "verifier Python",
    595     )
    596     _exact(
    597         verifier_metadata.get("dependencies"),
    598         ["jsonschema==4.26.0"],
    599         "verifier dependencies",
    600     )
    601     dependency_groups = _mapping(
    602         verifier_project.get("dependency-groups"), "verifier dependency groups"
    603     )
    604     _exact(dependency_groups, {"dev": ["ruff==0.12.12"]}, "verifier dev tools")
    605     _exact(verifier_lock.get("requires-python"), "==3.14.7", "verifier lock Python")
    606     package_rows = verifier_lock.get("package")
    607     if not isinstance(package_rows, list):
    608         raise PackageContractError("verifier lock package inventory is invalid")
    609     locked_packages = {
    610         item.get("name"): item.get("version")
    611         for item in package_rows
    612         if isinstance(item, dict)
    613     }
    614     _exact(locked_packages.get("jsonschema"), "4.26.0", "verifier jsonschema lock")
    615     _exact(locked_packages.get("ruff"), "0.12.12", "verifier ruff lock")
    616 
    617 
    618 def _verify_required_files(root: Path) -> None:
    619     required_files = (
    620         ".swiftformat",
    621         ".swiftlint.yml",
    622         "scripts/maintainability_ratchet.py",
    623         "scripts/local-social-fixture.py",
    624         "scripts/swift-quality.sh",
    625         "scripts/linux-shared-rust.sh",
    626         "test-fixtures/maintainability-baseline.v1.json",
    627         "test-fixtures/swiftlint-maintainability-baseline.v1.json",
    628         "test-fixtures/bud11-upload-authorization-mutations.v1.json",
    629         "test-fixtures/bud11-upload-authorization-mutations.v1.schema.json",
    630         "test-fixtures/local-social-personas.v1.json",
    631         "test-fixtures/local-social-personas.v1.schema.json",
    632         "test-fixtures/local-social-persona-results.v1.schema.json",
    633         "test-fixtures/local-social-persona-attempt-evidence.v1.schema.json",
    634         "test-fixtures/local-social-persona-results.v2.schema.json",
    635     )
    636     for relative in required_files:
    637         _read_regular(root / relative)
    638     for relative in ("scripts/swift-quality.sh", "scripts/linux-shared-rust.sh"):
    639         if not os.access(root / relative, os.X_OK):
    640             raise PackageContractError("required package command is not executable")
    641 
    642 
    643 def verify(repo_root: Path) -> tuple[str, str]:
    644     root = repo_root.resolve()
    645     _verify_repository_layout(root)
    646     try:
    647         legacy_identifiers.verify(root)
    648     except legacy_identifiers.LegacyIdentifierError as error:
    649         raise PackageContractError(str(error)) from error
    650     _validate_app_workspace(_cargo_workspace(root), root)
    651     release_version, _ = _verify_cargo_and_source(root)
    652     apple_revision = _verify_apple_dependencies(root)
    653     _verify_apple_configuration(root)
    654     _verify_package_locks(root, apple_revision)
    655     _verify_persona_toolchain(root)
    656     _verify_required_files(root)
    657     return release_version, apple_revision
    658 
    659 
    660 def main(argv: list[str] | None = None) -> int:
    661     parser = argparse.ArgumentParser()
    662     parser.add_argument("--repo-root", type=Path, required=True)
    663     arguments = parser.parse_args(argv)
    664     try:
    665         version, apple_revision = verify(arguments.repo_root)
    666     except PackageContractError as error:
    667         print(f"package_contract: {error}", file=sys.stderr)
    668         return 1
    669     print(f"package contracts agree at {version}; apple_kit@{apple_revision}")
    670     return 0
    671 
    672 
    673 if __name__ == "__main__":
    674     raise SystemExit(main())