feat: emerge plan mode; document the plan contract; ignore python bytecode

- usm-spm-emerge gains the plan mode the other four helpers already
  ship: one emerge --pretend, the merge list's category/package names
  (the same names its query contract reports) in emerge's transaction
  order; resolution failures exit 3 with the transcript tail on STDERR
- README documents the plan contract (and that version-constrained
  refs never reach helpers — the resolver skips them in the batched
  query)
- .gitignore: __pycache__/ and *.pyc (py_compile checks on the
  python-based helpers kept leaving bytecode behind)

All five helpers verified against their real package managers in
containers: pacman (archlinux), apk (alpine), apt (debian, with the
documented python3/python3-apt/apt-file bootstrap), dnf
(registry.fedoraproject.org/fedora:43 — the deploy default, via the
python3-dnf bootstrap), emerge (stage3 + portage tree): plan/query
contracts checked on all, install contract on pacman and apk.

.gitignore

@@ -1,4 +1,6 @@
 /build
 /build2
 /install-builddir
-/installer/dist
+/installer/dist
+__pycache__/
+*.pyc

README.md

@@ -339,6 +339,18 @@ Both keys or neither (validation error otherwise); argv arrays, no shell.
 
 `dependency-count` = packages the manager would install for this package alone incl. itself. Exit 0 with non-empty `not-found`; non-zero only on query failure.
 
+Version-constrained refs (`lib:…>=…`, `pc:…==…`) never reach the helper — the resolver skips them in the batched query (helpers match names exactly), so they resolve from local presence or USM packages only.
+
+### Plan contract
+
+`<plan> <native-name>…` → STDOUT single JSON object, no side effects: the material install set — the chosen names plus every dependency of a dependency — in the manager's own transaction order:
+
+```json
+{ "packages": ["libgpm2", "libncurses6", "sl"] }
+```
+
+Used to preview and drive progress for the whole native transaction. Any resolution failure exits non-zero with the message on STDERR (the caller degrades to the input names).
+
 ### Install contract
 
 `<install> <native-name>…` → STDOUT JSONL events:

spm/emerge/usm-spm-emerge

@@ -5,6 +5,7 @@ Implements the USM SPM contract (see usm/README.md, "System package manager
 integration") for Gentoo systems:
 
     usm-spm-emerge query <usm-ref>...         -> contract JSON on STDOUT
+    usm-spm-emerge plan <atom>...             -> contract JSON on STDOUT
     usm-spm-emerge install [--test] <atom>... -> contract JSONL events on STDOUT
 
 API choice: a Gentoo stage3 ships Portage and python3, so this helper reads
@@ -564,6 +565,25 @@ def link_unversioned_tools(atoms):
                 pass
 
 
+def cmd_plan(args):
+    """Resolve the material install set without touching the system.
+
+    One emerge --pretend for every atom; the merge list's names (in
+    emerge's own transaction order) print as one contract JSON object,
+    matching the names the query contract reports.
+    """
+    returncode, stdout, stderr = emerge_pretend(args.names)
+    if returncode != 0:
+        fail_plain("dependency resolution failed: %s"
+                   % failure_message((stdout + "\n" + stderr).splitlines()),
+                   EXIT_RESOLVE)
+    _, _, atoms = parse_merge_list(stdout)
+    sys.stdout.write(json.dumps(
+        {"packages": [category_package(atom) for atom in atoms]}) + "\n")
+    sys.stdout.flush()
+    return EXIT_OK
+
+
 def cmd_install(args):
     returncode, stdout, stderr = emerge_pretend(args.names)
     if returncode != 0:
@@ -646,6 +666,13 @@ def main():
         help="resource ref, e.g. bin:valac or pc:glib-2.0.pc")
     query_parser.set_defaults(handler=cmd_query)
 
+    plan_parser = subparsers.add_parser(
+        "plan", help="resolve the material install set for atoms")
+    plan_parser.add_argument(
+        "names", nargs="+", metavar="ATOM",
+        help="native gentoo package atom, e.g. dev-build/meson")
+    plan_parser.set_defaults(handler=cmd_plan)
+
     install_parser = subparsers.add_parser(
         "install", help="install system packages, streaming progress events")
     install_parser.add_argument(