feat(adapter)!: exact compatibility registry, verified adapter store, and contained descriptor execution

.github/workflows/ci.yml

@@ -54,3 +54,6 @@ jobs:
 
       - name: Build release CLI
         run: nix develop -c cargo build -p flutterdec-cli --release
+
+      - name: Release layout smoke
+        run: nix develop -c ./scripts/release-layout-smoke.sh target/release/flutterdec

.github/workflows/release.yml

@@ -69,6 +69,11 @@ jobs:
           fi
           "$bin" --version
 
+      # The archive carries a prefix, not a lone binary. Runtime discovery is
+      # executable-relative: the CLI reads its compatibility registry, runtime
+      # profiles and packaged producer from `<exe dir>/../share/flutterdec`, so
+      # an archive holding only `flutterdec` extracts into a CLI that cannot
+      # resolve any of them without a source checkout.
       - name: Package artifact
         shell: bash
         run: |
@@ -78,9 +83,15 @@ jobs:
           out_dir="dist"
           mkdir -p "$out_dir"
           archive="$out_dir/flutterdec-${{ github.ref_name }}-${os}-${arch}.tar.gz"
-          tar -C "target/${{ matrix.target }}/release" -czf "$archive" flutterdec
+          ./scripts/stage-release-prefix.sh \
+            "target/${{ matrix.target }}/release/flutterdec" stage
+          tar -C stage -czf "$archive" bin share
           echo "archive=$archive" >> "$GITHUB_ENV"
 
+      - name: Verify archive runs off a checkout
+        shell: bash
+        run: ./scripts/release-layout-smoke.sh "${{ env.archive }}"
+
       - name: Upload artifact
         uses: actions/upload-artifact@v7
         with:

.gitignore

@@ -5,7 +5,5 @@
 /out
 /.venv
 *.log
-/adapters/installed/*
-!/adapters/installed/.gitkeep
 __pycache__/
 *.pyc

Cargo.toml

@@ -25,6 +25,7 @@ regex = "1"
 goblin = "0.10"
 zip = { version = "8", default-features = false, features = ["deflate"] }
 tempfile = "3"
+libc = "0.2"
 sha2 = "0.10"
 walkdir = "2"
 capstone = "0.14"

README.md

@@ -81,21 +81,28 @@ nix profile upgrade flutterdec
 
 Current prerelease: [`v0.1.0-alpha.4`](https://github.com/caverav/flutterdec/releases/tag/v0.1.0-alpha.4)
 
+The archive is a prefix, not a lone binary: it holds `bin/flutterdec` plus the compatibility
+registry, the runtime profiles and the packaged producer under `share/flutterdec`. The CLI finds
+that data relative to its own executable, so copy `bin` and `share` to the same prefix and keep
+them together. A binary moved out on its own reports which directories it looked in and stops.
+
 Linux x64:
 
 ```bash
 curl -fLO https://github.com/caverav/flutterdec/releases/download/v0.1.0-alpha.4/flutterdec-v0.1.0-alpha.4-Linux-X64.tar.gz
-tar -xzf flutterdec-v0.1.0-alpha.4-Linux-X64.tar.gz
-sudo install -m 0755 flutterdec /usr/local/bin/flutterdec
+mkdir -p flutterdec-v0.1.0-alpha.4
+tar -xzf flutterdec-v0.1.0-alpha.4-Linux-X64.tar.gz -C flutterdec-v0.1.0-alpha.4
+sudo cp -R flutterdec-v0.1.0-alpha.4/bin flutterdec-v0.1.0-alpha.4/share /usr/local/
 flutterdec --help
 ```
 
 macOS arm64:
 
 ```bash
 curl -fLO https://github.com/caverav/flutterdec/releases/download/v0.1.0-alpha.4/flutterdec-v0.1.0-alpha.4-macOS-ARM64.tar.gz
-tar -xzf flutterdec-v0.1.0-alpha.4-macOS-ARM64.tar.gz
-sudo install -m 0755 flutterdec /usr/local/bin/flutterdec
+mkdir -p flutterdec-v0.1.0-alpha.4
+tar -xzf flutterdec-v0.1.0-alpha.4-macOS-ARM64.tar.gz -C flutterdec-v0.1.0-alpha.4
+sudo cp -R flutterdec-v0.1.0-alpha.4/bin flutterdec-v0.1.0-alpha.4/share /usr/local/
 flutterdec --help
 ```
 
@@ -137,13 +144,36 @@ If this is your first run, this is the shortest useful path.
 flutterdec info ./sample.apk --json
 ```
 
-`info` resolves the Dart SDK version straight from the snapshot hash, with no adapter
-installed and no disassembly:
+`info` reads the snapshot identity out of the header with no adapter installed and no
+disassembly: `snapshot_hash`, `arch`, `snapshot_features`, `compressed_pointers`, and
+`registry_record_present`.
+
+The Dart profile fields come from the host registry record that the identity matched,
+and appear only once that record's adapter is installed, because the profile is
+SHA-256 verified as part of authorizing the run:
 
-- `dart_version` (for example `3.9.2`)
+- `dart_aliases`: zero or more SDK labels, each with its own `ecosystem`, `version`,
+  and `provenance`. They are provenance only and never select a parser or a profile.
+- `dart_version`: a display value, never an exact SDK claim. It is `unverified` when
+  the record carries aliases and `unavailable` when it carries none.
 - `dart_tag_style` (`CID_INT32`, `CID_SHIFT1`, or `OBJECT_HEADER`)
 
-Both are `null` for snapshot hashes not in the bundled table (`data/dart-profiles.json`).
+```json
+"dart_aliases": [
+  {"ecosystem": "dart", "version": "3.5.0", "provenance": "r2flutter-offsets"},
+  {"ecosystem": "flutter", "version": "3.24.0", "provenance": "sample-build-metadata"}
+],
+"dart_version": "unverified",
+"dart_tag_style": "OBJECT_HEADER"
+```
+
+All three are `null` when no registry record matches the snapshot identity, and when a
+matching record's adapter is not installed.
+
+The registry record is the only authority for SDK labels, so a snapshot with no record
+reports no alias at all — including hashes that an earlier version labelled from the
+bundled profile table. That is the accepted cost of keeping one authority: there is no
+second, weaker path that names a version from a hash.
 
 For APK inputs, `info` reports Android startup summary fields such as:
 
@@ -161,6 +191,10 @@ If adapter metadata is available, `info` also reports package and compatibility
 - `identity_rejection` (why no adapter could be selected, when none could)
 - `model_capabilities`
 - `compatibility_warnings`
+- `provider` (one block: requested and resolved backend, whether an adapter was
+  executed at all and why not, host and target architectures, the producer and
+  its artifact digest, the parser family, profile and artifact the registry
+  named, and the containment the child reported)
 
 2. Install the adapter for the detected Dart hash:
 
@@ -216,6 +250,14 @@ flutterdec adapter install --dart-hash <HASH>
 flutterdec adapter list
 ```
 
+Adapters install into a writable store outside any checkout: `FLUTTERDEC_ADAPTER_STORE` when set,
+otherwise `$XDG_DATA_HOME/flutterdec/adapters` or `$HOME/.local/share/flutterdec/adapters`. The
+compatibility registry and the runtime profiles are read-only package data, found next to the binary at
+`share/flutterdec` (or wherever `FLUTTERDEC_DATA_DIR` points). Neither location depends on your current
+directory, so a release binary behaves the same everywhere. `adapter list` reports `verified`,
+`missing`, `corrupt`, `incompatible`, or `unavailable` per record and exits 2 if the store holds an
+install it cannot back. See [docs/user-guide.md](docs/user-guide.md) for the full rules.
+
 Decompile with the default app-focused scope:
 
 ```bash
@@ -358,16 +400,26 @@ flutterdec decompile ./sample.apk -o ./out --analysis-profile light
 
 Adapter backend selection:
 
-- `--adapter-backend auto` (default): try r2flutter, then Blutter, then fall back to the internal adapter
-- `--adapter-backend internal`: force the internal adapter only
+- `--adapter-backend auto` (default): try r2flutter, then Blutter, then the producer's internal path
+- `--adapter-backend internal`: recover in core; select nothing, read no registry, execute nothing
 - `--adapter-backend blutter`: require the Blutter backend and fail if unavailable
 - `--adapter-backend r2-flutter`: require the r2flutter backend and fail if unavailable
+- `--adapter-timeout <SECONDS>`: bound one adapter invocation
 - `--require-snapshot-hash-match`: fail unless the snapshot identity came from a real header
 
+A snapshot nothing is authorized to parse does not end the run. Core recovers
+ARM64 code candidates from the instruction bytes, marks every one of them
+heuristic and unnamed, and leaves libraries, classes, function names, the
+original entry function and the ObjectPool unavailable with a diagnostic each.
+`core_fallback_reason` says which condition it was. A pinned external backend is
+refused by name instead, and an adapter that was authorized, ran, and failed is
+still a failure. See [Core recovery](docs/cli-reference.md#core-recovery).
+
 What the backends actually recover:
 
 | Backend | Function names | Classes | ObjectPool |
 | --- | --- | --- | --- |
+| core recovery | none at all; code ranges are unnamed | none | unavailable |
 | `internal` | none at all; code ranges are unnamed | none | carved strings, ordinal index space |
 | `blutter` | scraped from Blutter's rendered source, heuristic | yes | Blutter `pp.txt` entries, ordinal index space |
 | `r2flutter` | exact, from the AOT instruction table | yes, library attribution unavailable | real slots, resolvable from `x27` displacements |
@@ -579,7 +631,7 @@ Recover readable behavior from Flutter AOT ARM64 binaries with enough semantic s
 
 ## Third-Party Credits
 
-- `data/dart-profiles.json`: Dart snapshot hash-to-version and layout table imported from
+- `data/dart-profiles.json`: Dart AOT snapshot layout profiles imported from
   [radareorg/r2flutter](https://github.com/radareorg/r2flutter) (MIT). Rationale in
   [docs/research-decisions.md](docs/research-decisions.md).
 - `--adapter-backend r2-flutter` drives the same project as an external tool; it is not

adapters/python/adapter_template.py

@@ -55,10 +55,11 @@
 DERIVED = "derived"
 HEURISTIC = "heuristic"
 
-# Mirrors `validate::PLACEHOLDER_NAMES`. A carved string that is one of these is
-# an admission of ignorance wearing a value's clothes, and the host rejects the
-# whole model over one of them, so they are filtered at the source.
-PLACEHOLDER_NAMES = frozenset(
+# Mirrors `validate::CASE_INSENSITIVE_PLACEHOLDERS` and `EXACT_LOWERCASE_PLACEHOLDERS`.
+# A carved string that is one of these is an admission of ignorance wearing a
+# value's clothes, and the host rejects the whole model over one of them, so
+# they are filtered at the source.
+CASE_INSENSITIVE_PLACEHOLDERS = frozenset(
     [
         "",
         "-",
@@ -67,9 +68,6 @@
         "???",
         "n/a",
         "na",
-        "none",
-        "null",
-        "nil",
         "todo",
         "tbd",
         "unknown",
@@ -81,6 +79,8 @@
     ]
 )
 
+EXACT_LOWERCASE_PLACEHOLDERS = frozenset(["none", "null", "nil"])
+
 
 class BackendUnavailable(Exception):
     """The backend's tooling is not installed. Distinct from it failing."""
@@ -91,8 +91,8 @@ class BackendFailed(Exception):
 
 
 def _is_placeholder(text: str) -> bool:
-    return text.strip().lower() in PLACEHOLDER_NAMES
-
+    t = text.strip()
+    return t in EXACT_LOWERCASE_PLACEHOLDERS or t.lower() in CASE_INSENSITIVE_PLACEHOLDERS
 
 def _usable_value(text: str) -> bool:
     return bool(text) and not _is_placeholder(text)
@@ -761,7 +761,12 @@ def _run_blutter_dump(input_path: Optional[str], libapp_path: Optional[str]) ->
             raise BackendFailed("custom blutter backend needs --input-path")
         cmd = runner + [input_path, str(out_dir)]
 
-    lock_dir = Path.home() / ".cache" / "flutterdec"
+    # The lock has to live beside the cache it protects. The adapter host gives
+    # every invocation a private HOME, so a lock under it would be private too
+    # and would serialize nothing; XDG_CACHE_HOME is the variable the blutter
+    # wrapper itself keys its source cache on.
+    cache_root = os.getenv("XDG_CACHE_HOME", "").strip()
+    lock_dir = Path(cache_root) / "flutterdec" if cache_root else Path.home() / ".cache" / "flutterdec"
     lock_dir.mkdir(parents=True, exist_ok=True)
     lock_file = lock_dir / "blutter-run.lock"
     with lock_file.open("w") as lock_fp: