mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/verify/audit.py

@@ -0,0 +1,312 @@
+"""Static audits of a built app's bundle: they read files only, never launch anything and never change the bundle."""
+
+import os
+import plistlib
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = ["Finding", "AUDITS", "run_audit", "bundle_symbols", "USAGE_KEYS", "REQUIRED_REASON"]
+
+
+@dataclass(frozen=True)
+class Finding:
+    id: str            # stable, such as "usage-description-missing"
+    guideline: str     # "5.1.1(i)"
+    level: str         # "fail" | "review"
+    message: str       # what is wrong, then what to do
+    evidence: str      # a path inside the bundle, with the key
+
+    def to_dict(self):
+        return {"id": self.id, "guideline": self.guideline, "level": self.level, "message": self.message,
+                "evidence": self.evidence}
+
+
+MACHO_MAGICS = (b"\xcf\xfa\xed\xfe", b"\xce\xfa\xed\xfe", b"\xca\xfe\xba\xbe", b"\xbe\xba\xfe\xca")
+READ_LIMIT = 200 * 1024 * 1024
+
+
+def _machos(app):
+    """Every Mach-O file in the bundle: the executable, frameworks and plug-ins, as (relative path, path)."""
+    found = []
+    for folder, _, names in os.walk(app):
+        for name in names:
+            path = Path(folder) / name
+            if path.is_symlink() or not path.is_file():
+                continue
+            try:
+                with open(path, "rb") as handle:
+                    head = handle.read(4)
+            except OSError:
+                continue
+            if head in MACHO_MAGICS:
+                found.append((path.relative_to(app).as_posix(), path))
+    return sorted(found)
+
+
+def _present(name, data):
+    # Swift mangles class and constant names inside longer ones; a C function is a whole NUL-delimited string.
+    word = name.encode()
+    if name[:1].isupper():
+        return word in data
+    return b"\0_" + word + b"\0" in data or b"\0" + word + b"\0" in data
+
+
+def bundle_symbols(app, names):
+    """{relative path of a Mach-O file: the set of ``names`` it holds} for the whole bundle."""
+    out = {}
+    for relative, path in _machos(Path(app)):
+        try:
+            if path.stat().st_size > READ_LIMIT:
+                continue
+            data = path.read_bytes()
+        except OSError:
+            continue
+        found = {name for name in names if _present(name, data)}
+        if found:
+            out[relative] = found
+    return out
+
+
+def uses(symbols, names):
+    """{Mach-O file: the first of ``names`` it holds} over the scan ``symbols`` (bundle_symbols)."""
+    hits = {}
+    for relative, found in sorted(symbols.items()):
+        for name in names:
+            if name in found:
+                hits[relative] = name
+                break
+    return hits
+
+
+# The Info.plist key each API needs, and the names whose presence in a binary means the app can reach it.
+USAGE_KEYS = (
+    ("NSCameraUsageDescription", ("AVCaptureDeviceInput", "AVCaptureSession", "VNDocumentCameraViewController")),
+    ("NSMicrophoneUsageDescription", ("AVAudioRecorder", "AVAudioApplication")),
+    ("NSPhotoLibraryUsageDescription", ("PHPhotoLibrary",)),
+    ("NSPhotoLibraryAddUsageDescription", ("UIImageWriteToSavedPhotosAlbum",)),
+    ("NSLocationWhenInUseUsageDescription", ("CLLocationManager",)),
+    ("NSContactsUsageDescription", ("CNContactStore",)),
+    ("NSCalendarsUsageDescription", ("EKEventStore",)),
+    ("NSFaceIDUsageDescription", ("LAContext",)),
+    ("NSBluetoothAlwaysUsageDescription", ("CBCentralManager", "CBPeripheralManager")),
+    ("NSMotionUsageDescription", ("CMMotionActivityManager", "CMPedometer")),
+    ("NSSpeechRecognitionUsageDescription", ("SFSpeechRecognizer",)),
+    ("NSUserTrackingUsageDescription", ("ATTrackingManager",)),
+    ("NSHealthShareUsageDescription", ("HKHealthStore",)),
+)
+ALSO_ACCEPTED = {
+    "NSLocationWhenInUseUsageDescription": ("NSLocationAlwaysAndWhenInUseUsageDescription",
+                                            "NSLocationAlwaysUsageDescription"),
+    "NSCalendarsUsageDescription": ("NSCalendarsFullAccessUsageDescription",
+                                    "NSCalendarsWriteOnlyAccessUsageDescription",
+                                    "NSRemindersUsageDescription", "NSRemindersFullAccessUsageDescription"),
+    "NSPhotoLibraryAddUsageDescription": ("NSPhotoLibraryUsageDescription",),
+    "NSHealthShareUsageDescription": ("NSHealthUpdateUsageDescription",),
+}
+PLACEHOLDER = re.compile(
+    r"lorem ipsum|\btodo\b|\btbd\b|\bfixme\b|placeholder|\bxxx+\b|usage description|your (?:text|description) here|"
+    r"enter (?:a |your )?(?:description|text|reason) here|^(?:test|testing|foo|bar|asdf|description|text|none|n/a|"
+    r"camera|microphone|location|photos|contacts|calendar)\.?$", re.I)
+MIN_WORDS = 3
+
+
+def read_plist(path):
+    """A property list as a dict (None when the file is missing, unreadable or not a dict)."""
+    try:
+        value = plistlib.loads(Path(path).read_bytes())
+    except Exception:
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def placeholder_reason(text):
+    """Why a usage string reads as filler (None when it reads as a real reason)."""
+    value = (text or "").strip()
+    if not value:
+        return "it is empty"
+    if PLACEHOLDER.search(value):
+        return "it reads as placeholder text"
+    if len(value.split()) < MIN_WORDS:
+        return f"it is {len(value.split())} word{'' if len(value.split()) == 1 else 's'}, too short to say why"
+    return None
+
+
+def audit_usage_descriptions(app, ctx):
+    info = read_plist(Path(app) / "Info.plist")
+    if info is None:
+        return [Finding("info-plist-unreadable", "2.1", "review",
+                        "The app's Info.plist can't be read. Build the app again and point the check at it.",
+                        f"{Path(app).name}/Info.plist")]
+    symbols = ctx.symbols()
+    findings, plist = [], f"{Path(app).name}/Info.plist"
+    for key, names in USAGE_KEYS:
+        hits = uses(symbols, names)
+        if not hits:
+            continue
+        accepted = (key, *ALSO_ACCEPTED.get(key, ()))
+        present = [name for name in accepted if name in info]
+        where = next(iter(hits.items()))
+        if not present:
+            findings.append(Finding(
+                "usage-description-missing", "5.1.1", "fail",
+                f"{where[0]} uses {where[1]} and Info.plist has no {key}. Add {key} with the reason you ask.",
+                f"{plist} has no {key}; {where[1]} is in {where[0]}"))
+            continue
+        for name in present:
+            why = placeholder_reason(info.get(name) if isinstance(info.get(name), str) else "")
+            if why:
+                findings.append(Finding(
+                    "usage-description-placeholder", "5.1.1", "fail",
+                    f"{name} is {info.get(name)!r}: {why}. Write the reason a person would accept.",
+                    f"{plist} {name}"))
+    # A key with filler even when no symbol showed the API: a framework may load it at run time.
+    for name, value in sorted(info.items()):
+        if name.endswith("UsageDescription") and isinstance(value, str):
+            why = placeholder_reason(value)
+            if why and not any(f.evidence == f"{plist} {name}" for f in findings):
+                findings.append(Finding(
+                    "usage-description-placeholder", "5.1.1", "fail",
+                    f"{name} is {value!r}: {why}. Write the reason a person would accept.", f"{plist} {name}"))
+    return findings
+
+
+# "weak" names are libc calls a binary can carry for other reasons: an undeclared one needs review, not a failure.
+REQUIRED_REASON = {
+    "NSPrivacyAccessedAPICategoryFileTimestamp": {
+        "sure": ("NSFileCreationDate", "NSFileModificationDate", "NSURLContentModificationDateKey",
+                 "NSURLCreationDateKey", "NSURLContentAccessDateKey", "getattrlist", "getattrlistbulk",
+                 "fgetattrlist"),
+        "weak": ("stat", "fstat", "lstat", "fstatat")},
+    "NSPrivacyAccessedAPICategorySystemBootTime": {
+        "sure": ("systemUptime", "mach_absolute_time"), "weak": ()},
+    "NSPrivacyAccessedAPICategoryDiskSpace": {
+        "sure": ("NSURLVolumeAvailableCapacityKey", "NSURLVolumeAvailableCapacityForImportantUsageKey",
+                 "NSURLVolumeTotalCapacityKey", "NSFileSystemFreeSize", "NSFileSystemSize", "statfs", "statvfs",
+                 "fstatfs", "fstatvfs"), "weak": ()},
+    "NSPrivacyAccessedAPICategoryActiveKeyboards": {"sure": ("activeInputModes",), "weak": ()},
+    "NSPrivacyAccessedAPICategoryUserDefaults": {"sure": ("NSUserDefaults",), "weak": ()},
+}
+MANIFEST = "PrivacyInfo.xcprivacy"
+
+
+def declared_categories(manifest):
+    """({category: [reasons]} the manifest declares, a problem sentence or None)."""
+    types = manifest.get("NSPrivacyAccessedAPITypes")
+    if types is None:
+        return {}, None
+    if not isinstance(types, list):
+        return {}, "NSPrivacyAccessedAPITypes is not a list"
+    out = {}
+    for item in types:
+        if isinstance(item, dict) and isinstance(item.get("NSPrivacyAccessedAPIType"), str):
+            reasons = item.get("NSPrivacyAccessedAPITypeReasons")
+            out[item["NSPrivacyAccessedAPIType"]] = [r for r in reasons if isinstance(r, str)] \
+                if isinstance(reasons, list) else []
+    return out, None
+
+
+def audit_privacy_manifest(app, ctx):
+    app = Path(app)
+    symbols = ctx.symbols()
+    needed = {}
+    for category, groups in REQUIRED_REASON.items():
+        for strength in ("sure", "weak"):
+            hits = uses(symbols, groups[strength])
+            if hits:
+                needed.setdefault(category, {})[strength] = hits
+    top = app / MANIFEST
+    findings = []
+    if not top.is_file():
+        if needed:
+            first = ", ".join(f"{category} ({next(iter((hits.get('sure') or hits['weak']).items()))[1]} in "
+                              f"{next(iter(sorted((hits.get('sure') or hits['weak']))))})"
+                              for category, hits in sorted(needed.items()))
+            findings.append(Finding(
+                "privacy-manifest-missing", "5.1.1", "fail",
+                f"{app.name} has no {MANIFEST} and its binaries use {len(needed)} required-reason API "
+                f"categor{'y' if len(needed) == 1 else 'ies'}. Add the file to the app target and declare each "
+                "with a reason.", f"{app.name}/{MANIFEST} is missing; uses {first}"))
+        else:
+            findings.append(Finding(
+                "privacy-manifest-missing", "5.1.1", "review",
+                f"{app.name} has no {MANIFEST}. No required-reason API shows in the binaries, so App Review "
+                "may accept it; add an empty manifest to be sure.", f"{app.name}/{MANIFEST} is missing"))
+        return findings
+    manifest = read_plist(top)
+    if manifest is None:
+        return [Finding("privacy-manifest-invalid", "5.1.1", "fail",
+                        f"{MANIFEST} is not a valid property list. Open it in Xcode and save it again.",
+                        f"{app.name}/{MANIFEST}")]
+    declared, problem = declared_categories(manifest)
+    if problem:
+        findings.append(Finding("privacy-manifest-invalid", "5.1.1", "fail",
+                                f"{problem}. Open {MANIFEST} in Xcode and fix the key.", f"{app.name}/{MANIFEST}"))
+    for category, reasons in sorted(declared.items()):
+        if not reasons:
+            findings.append(Finding(
+                "privacy-reason-missing", "5.1.1", "fail",
+                f"{category} is declared with no reason code. Add NSPrivacyAccessedAPITypeReasons.",
+                f"{app.name}/{MANIFEST} {category}"))
+    for category, strengths in sorted(needed.items()):
+        if category in declared:
+            continue
+        for strength, level in (("sure", "fail"), ("weak", "review")):
+            hits = strengths.get(strength) or {}
+            own = {f: n for f, n in hits.items() if not f.startswith(("Frameworks/", "PlugIns/"))}
+            if own:
+                file, name = next(iter(sorted(own.items())))
+                findings.append(Finding(
+                    "required-reason-undeclared", "5.1.1", level,
+                    f"{file} uses {name} and {MANIFEST} does not declare {category}. Add it with the reason "
+                    "that fits how the app uses it.", f"{app.name}/{MANIFEST} lacks {category}; {name} is in {file}"))
+                break
+            embedded = {f: n for f, n in hits.items() if f not in own}
+            if embedded:
+                file, name = next(iter(sorted(embedded.items())))
+                folder = "/".join(file.split("/")[:2])
+                own_manifest = read_plist(app / folder / MANIFEST) or {}
+                if category in declared_categories(own_manifest)[0]:
+                    continue
+                state = f"lacks {category}" if own_manifest else "is missing"
+                findings.append(Finding(
+                    "required-reason-sdk", "5.1.1", "review",
+                    f"{file} uses {name} and neither it nor {MANIFEST} declares {category}. Update the SDK "
+                    "to a version with its own privacy manifest, or declare the category yourself.",
+                    f"{folder}/{MANIFEST} {state}; {name} is in {file}"))
+                break
+    return findings
+
+
+class Context:
+    """What the audits of one run share: the bundle's symbols, read once."""
+
+    def __init__(self, app):
+        self.app = Path(app)
+        self._symbols = None
+
+    def symbols(self):
+        if self._symbols is None:
+            names = {name for _, group in USAGE_KEYS for name in group}
+            for groups in REQUIRED_REASON.values():
+                names.update(groups["sure"])
+                names.update(groups["weak"])
+            self._symbols = bundle_symbols(self.app, sorted(names))
+        return self._symbols
+
+
+AUDITS = {
+    "usage-descriptions": audit_usage_descriptions,
+    "privacy-manifest": audit_privacy_manifest,
+}
+
+
+def run_audit(name, app, *, context=None):
+    """The findings of audit ``name`` on the built app ``app``. A bundle that isn't there is one review finding,
+    never a crash."""
+    app = Path(app)
+    if not app.is_dir():
+        return [Finding("app-not-found", "2.1", "review", f"{app} isn't a built app. Build it, then run again.",
+                        str(app))]
+    ctx = context or Context(app)
+    return AUDITS[name](app, ctx)

mobile_agent/verify/business.py

@@ -0,0 +1,221 @@
+"""A bounded, locally enrolled app-state oracle for simulator checks.
+
+The check names an adapter and fixture; only a project-owned manifest can define
+their fields and seed values. This is persisted app state, not a backend oracle.
+"""
+
+import hashlib
+import json
+import math
+import os
+import re
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..state import validate_bundle_id
+from .assertions import CheckError
+
+CONTRACT = "mobster.business/1"
+FILENAME = "mobster-business.json"
+MANIFEST = ".mobster/fixtures.json"
+_ID = re.compile(r"[a-z][a-z0-9_-]{0,63}\Z")
+_FIELD = re.compile(r"[a-z][a-z0-9_.-]{0,79}\Z")
+_MAX_BYTES = 64_000
+
+
+@dataclass(frozen=True)
+class BusinessExpectation:
+    field: str
+    equals: object
+
+    def to_dict(self):
+        return {"field": self.field, "equals": self.equals}
+
+
+@dataclass(frozen=True)
+class BusinessSpec:
+    adapter: str
+    fixture: str
+    expect: tuple[BusinessExpectation, ...]
+
+    def to_dict(self):
+        return {"adapter": self.adapter, "fixture": self.fixture,
+                "expect": [item.to_dict() for item in self.expect]}
+
+
+@dataclass(frozen=True)
+class BusinessBinding:
+    spec: BusinessSpec
+    bundle: str
+    fields: tuple[str, ...]
+    seed: tuple[tuple[str, object], ...]
+    digest: str
+
+    def seed_state(self):
+        return dict(self.seed)
+
+    @property
+    def action_digest(self):
+        """Replay starting state; expected assertions do not change the action path."""
+        encoded = json.dumps({"contract": CONTRACT, "adapter": self.spec.adapter, "fixture": self.spec.fixture,
+                              "bundle": self.bundle, "fields": self.fields, "seed": self.seed_state()},
+                             sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        return hashlib.sha256(encoded).hexdigest()
+
+
+def _id(value, where, pattern=_ID):
+    if not isinstance(value, str) or not pattern.fullmatch(value):
+        raise CheckError(f"{where} must be a lowercase symbolic ID")
+    return value
+
+
+def _scalar(value, where):
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, str) and len(value) <= 256 and all(
+            ord(c) >= 32 and not 127 <= ord(c) <= 159 and not 0xD800 <= ord(c) <= 0xDFFF
+            and not 0xFDD0 <= ord(c) <= 0xFDEF and ord(c) & 0xFFFF not in (0xFFFE, 0xFFFF)
+            for c in value):
+        return value
+    if isinstance(value, int) and abs(value) <= 1_000_000_000:
+        return value
+    if isinstance(value, float) and math.isfinite(value) and abs(value) <= 1_000_000_000:
+        return value
+    raise CheckError(f"{where} must be a bounded JSON scalar")
+
+
+def valid_scalar(value):
+    try:
+        _scalar(value, "app-state value")
+    except CheckError:
+        return False
+    return True
+
+
+def parse_business(value):
+    if value is None:
+        return None
+    if not isinstance(value, dict) or set(value) != {"adapter", "fixture", "expect"}:
+        raise CheckError("business needs adapter, fixture and expect; no other keys")
+    adapter = _id(value["adapter"], "business.adapter")
+    fixture = _id(value["fixture"], "business.fixture")
+    items = value["expect"]
+    if not isinstance(items, list) or len(items) > 20:
+        raise CheckError("business.expect must be a list of at most 20 field comparisons")
+    seen = set()
+    parsed = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict) or set(item) != {"field", "equals"}:
+            raise CheckError(f"business.expect[{index}] needs field and equals")
+        field = _id(item["field"], f"business.expect[{index}].field", _FIELD)
+        if field in seen:
+            raise CheckError(f"business.expect repeats field {field!r}")
+        seen.add(field)
+        parsed.append(BusinessExpectation(field, _scalar(item["equals"], f"business.expect[{index}].equals")))
+    return BusinessSpec(adapter, fixture, tuple(parsed))
+
+
+def _pairs(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise CheckError(f"duplicate registration key {key!r}")
+        result[key] = value
+    return result
+
+
+def _invalid_constant(value):
+    raise CheckError(f"non-finite JSON value {value!r}")
+
+
+def strict_json(raw):
+    return json.loads(raw, object_pairs_hook=_pairs, parse_constant=_invalid_constant)
+
+
+def _manifest_bytes(project_root):
+    root = os.open(Path(project_root).resolve(), os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        folder = os.open(".mobster", os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=root)
+        try:
+            descriptor = os.open("fixtures.json", os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW, dir_fd=folder)
+            with os.fdopen(descriptor, "rb") as source:
+                info = os.fstat(source.fileno())
+                if not stat.S_ISREG(info.st_mode) or info.st_size > _MAX_BYTES:
+                    raise CheckError(f"{MANIFEST} must be a regular file of at most {_MAX_BYTES:,} bytes")
+                raw = source.read(_MAX_BYTES + 1)
+            if len(raw) > _MAX_BYTES:
+                raise CheckError(f"{MANIFEST} is larger than {_MAX_BYTES:,} bytes")
+            return raw
+        finally:
+            os.close(folder)
+    finally:
+        os.close(root)
+
+
+def load_business_binding(check, project_root):
+    """Resolve a check against the project-owned, versioned local registration."""
+    spec = check.business
+    if spec is None:
+        raise CheckError("the check has no business binding")
+    try:
+        data = strict_json(_manifest_bytes(project_root))
+    except CheckError:
+        raise
+    except (OSError, UnicodeError, ValueError, RecursionError) as error:
+        raise CheckError(f"{MANIFEST} is missing or invalid ({type(error).__name__})") from None
+    if not isinstance(data, dict) or set(data) != {"version", "adapters"} or type(data["version"]) is not int \
+            or data["version"] != 1 or not isinstance(data["adapters"], dict) \
+            or len(data["adapters"]) > 16:
+        raise CheckError(f"{MANIFEST} needs version 1 and at most 16 adapters")
+    for adapter_id in data["adapters"]:
+        _id(adapter_id, "adapter registration")
+    registration = data["adapters"].get(spec.adapter)
+    if not isinstance(registration, dict) or set(registration) != {"kind", "bundle", "fields", "fixtures"} \
+            or registration["kind"] != "app_container_json":
+        raise CheckError(f"business adapter {spec.adapter!r} is not locally registered for app_container_json")
+    bundle = registration["bundle"]
+    try:
+        bundle = validate_bundle_id(bundle)
+    except (TypeError, ValueError):
+        raise CheckError("the registered app-state bundle is not a bundle ID") from None
+    if check.bundle_id and bundle != check.bundle_id:
+        raise CheckError("the registered app-state bundle does not match the check")
+    fields = registration["fields"]
+    if not isinstance(fields, list) or not 1 <= len(fields) <= 20:
+        raise CheckError("business adapter fields must be 1–20 distinct keys")
+    for field in fields:
+        _id(field, "business adapter field", _FIELD)
+    if len(set(fields)) != len(fields):
+        raise CheckError("business adapter fields must be 1–20 distinct keys")
+    fixtures = registration["fixtures"]
+    if not isinstance(fixtures, dict) or not 1 <= len(fixtures) <= 20:
+        raise CheckError("business adapter needs 1–20 named fixtures")
+    for fixture_id in fixtures:
+        _id(fixture_id, "business fixture")
+    seed = fixtures.get(spec.fixture)
+    if not isinstance(seed, dict) or set(seed) != set(fields):
+        raise CheckError(f"business fixture {spec.fixture!r} is missing or has unregistered fields")
+    seed = tuple((field, _scalar(seed[field], f"business fixture {spec.fixture}.{field}")) for field in fields)
+    if any(item.field not in fields for item in spec.expect):
+        raise CheckError("business.expect names a field this adapter did not register")
+    canonical = json.dumps({"contract": CONTRACT, "adapter": spec.adapter, "fixture": spec.fixture,
+                            "registration": registration, "expect": [item.to_dict() for item in spec.expect]},
+                           sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    return BusinessBinding(spec, bundle, tuple(fields), seed, hashlib.sha256(canonical).hexdigest())
+
+
+def evaluate_business(binding, state):
+    """All comparisons use one app-produced snapshot; JSON types must match exactly."""
+    def equal(actual, expected):
+        if type(actual) is bool or type(expected) is bool:
+            return type(actual) is type(expected) and actual == expected
+        if type(actual) in (int, float) and type(expected) in (int, float):
+            return actual == expected
+        return type(actual) is type(expected) and actual == expected
+
+    return [{"field": item.field, "ok": item.field in state and equal(state[item.field], item.equals),
+             "observed": (state[item.field] if type(state[item.field]) is bool or state[item.field] is None
+                          else f"[{type(state[item.field]).__name__} redacted]") if item.field in state else None,
+             "present": item.field in state}
+            for item in binding.spec.expect]

mobile_agent/verify/business_run.py

@@ -0,0 +1,131 @@
+"""One VerifyRun's registered app-state fixture and evidence lifecycle."""
+
+import secrets
+from pathlib import Path
+
+from .assertions import CheckError
+from .business import FILENAME, evaluate_business, load_business_binding
+from .checks import project_root
+from .verdict import CouldntRun
+
+
+def _seeds_reserved_file(seed):
+    reserved = ("documents", FILENAME.casefold())
+    for source, destination in seed.files:
+        parts = tuple(part.casefold() for part in Path(destination).parts)
+        if parts[:2] == reserved:
+            return True
+        if not source.is_dir() or parts != reserved[:len(parts)]:
+            continue
+        current = source
+        for component in reserved[len(parts):]:
+            current = next((child for child in current.iterdir() if child.name.casefold() == component), None)
+            if current is None:
+                break
+        if current is not None:
+            return True
+    return False
+
+
+class BusinessRun:
+    def _load_business(self):
+        if self.check.business is None:
+            return
+        if self.check.reset_level() == "none":
+            raise CouldntRun("business", "App-state fixtures need reset: data or reinstall.",
+                             "Set reset: data or reset: reinstall in the saved check.")
+        if self.check.source is None:
+            raise CouldntRun("business", "An app-state check must be a saved project check file.",
+                             "Save the check under a project with .mobster/fixtures.json, then run again.")
+        try:
+            collision = _seeds_reserved_file(self.check.seed)
+        except OSError:
+            raise CouldntRun("business", "A YAML fixture's seed files could not be inspected before reset.",
+                             "Fix the YAML fixture, then run the check again.") from None
+        if collision:
+            raise CouldntRun("business", "A YAML fixture seeds the reserved app-state file.",
+                             "Remove that file from the YAML fixture before running this check.")
+        try:
+            current = load_business_binding(self.check, project_root(self.check.source))
+        except CheckError as error:
+            raise CouldntRun("business", str(error), "Fix .mobster/fixtures.json, then run again.") from None
+        if self.business_binding is not None and current.digest != self.business_binding.digest:
+            raise CouldntRun("business", "The enrolled app-state fixture changed before the run.",
+                             "Re-enroll the project fixture, then run again.")
+        self.business_binding = current
+        self.business_result = {"adapter": current.spec.adapter, "fixture": current.spec.fixture,
+                                "status": "unavailable", "schemaVersion": "mobster.business/1",
+                                "bindingSha256": current.digest, "assertions": [],
+                                "setup": "not_started", "cleanup": "not_needed"}
+
+    def _setup_business(self, manager):
+        if self.business_binding is None:
+            return
+        from .business_state import AppContainerFixture, FixtureError
+        self.business_fixture = AppContainerFixture(self.business_binding, manager, self.target, self.actions,
+                                                    self.run_id, secrets.token_hex(16))
+        with self.actions.action("BUSINESS_QUIESCE", operation_id=f"{self.run_id}:business:preseed"):
+            self.business_fixture.quiesce()
+        self.business_result["setup"] = "pending"
+        try:
+            self.business_fixture.setup()
+        except (FixtureError, OSError) as error:
+            self.business_result["setup"] = "needs_reconciliation" if self.actions.blocked else "failed"
+            raise CouldntRun("business", f"The app-state fixture could not be seeded ({type(error).__name__}).",
+                             "Inspect the fixture file and simulator, then start a new run.") from None
+        self.business_result["setup"] = "seeded"
+
+    def _take_business_baseline(self):
+        if self.business_fixture is None:
+            return
+        from .business_state import FixtureError
+        try:
+            state, generation, digest = self.business_fixture.observe()
+        except (FixtureError, OSError) as error:
+            raise CouldntRun("business_evidence", f"The app-state baseline is unavailable ({type(error).__name__}).",
+                             "Check that the app publishes its persisted state after launch.") from None
+        self._business_baseline = (generation, digest)
+        self.baseline["businessHeld"] = [item["ok"] for item in evaluate_business(self.business_binding, state)]
+
+    def _observe_business(self, decided):
+        if self.business_fixture is None:
+            return None
+        from .business_state import FixtureError
+        try:
+            state, generation, digest = self.business_fixture.observe()
+        except (FixtureError, OSError) as error:
+            self.business_result["error"] = "App-produced state was missing, stale or malformed"
+            return {**decided, "verdict": "couldnt_run", "klass": "business_evidence",
+                    "message": f"The app-state observation is unavailable ({type(error).__name__}).",
+                    "fix": "Check the app's fixture producer and run a new check."}
+        if self._business_baseline is not None:
+            before_generation, before_digest = self._business_baseline
+            if generation < before_generation or generation == before_generation and digest != before_digest:
+                self.business_result["error"] = "The app-state generation moved backward or changed in place"
+                return {**decided, "verdict": "couldnt_run", "klass": "business_evidence",
+                        "message": "The app-state observation has a stale generation.",
+                        "fix": "Make the app increment generation for every persisted snapshot."}
+        self.business_result.update(status="observed", generation=generation, sourceSha256=digest,
+                                    assertions=evaluate_business(self.business_binding, state))
+        return None
+
+    def _cleanup_business(self):
+        if self.business_fixture is None or self._business_cleanup_done:
+            return None
+        self._business_cleanup_done = True
+        if self.actions.blocked or self.error is not None and self.error["klass"] == "unknown_outcome":
+            self.business_result["cleanup"] = "needs_reconciliation"
+            return None
+        try:
+            status = self.business_fixture.remove()
+        except BaseException as error:
+            self.business_result["cleanup"] = "needs_reconciliation"
+            failure = self._action_failure()
+            return failure or CouldntRun("business_cleanup",
+                                         f"The app-state fixture was not confirmed removed ({type(error).__name__}).",
+                                         "Inspect the simulator before another run.")
+        self.business_result["cleanup"] = status
+        if status == "needs_reconciliation":
+            return CouldntRun("business_cleanup", "The app-state fixture was not confirmed removed.",
+                             "Inspect the simulator before another run.")
+        return None