Gentoo: prepare phase-aware feature packaging

[VirgilMing]

Summary

Prepare the Gentoo feature-packaging foundation on top of current main. This follows the merged local-ebuild implementation in #1553, but does not declare any repository feature supported yet. The supported repository feature selection therefore remains empty, and PACKAGE_WITH_UPDATER=0 continues to leave native updates to Portage.

• Add opt-in gentoo.supported auditing and enabled-only dependency plans, separating regular-user bootstrap prerequisites from EAPI 8 BDEPEND, DEPEND, RDEPEND, and IDEPEND.
• Accept bounded version, slot/subslot, slot-operator, and fixed USE constraints; reject shell expansion, expressions, unknown phases, and malformed atoms. Validate declared atoms again with the Gentoo host's actual Portage parser.
• Feed bootstrap atoms into dependency installation before helper/app/package builds. These tools do not become runtime dependencies or enter the world set, and feature keyword/license/USE policy is not automatically relaxed.
• Extend the shared native package resource/hook engine with ebuild, including packageDependencies.ebuild as an RDEPEND-only declaration. Gentoo package resources stay below usr/ or etc/; staging hooks run with the builder's privileges, never as Portage pkg_* hooks.
• Validate enabled app snapshots and recursively preserve directory/file modes through normalization, archive extraction, and the Portage image copy. Use mode-preserving binary-payload extraction rather than the source-oriented default unpack.
• Retain the dependency helper in the minimal update-builder closure for the existing package formats, and add fixture/regression coverage and English/Chinese usage documentation.

This is groundwork for feature-by-feature follow-ups, not a claim that all Linux features work on Gentoo. It's based and tested on an OpenRC Gentoo installation; thus systemd-related feature are not in this PR's scope.
The existing signed-source verification, transactional repository deployment, bundled CLI default, and package identity are unchanged.

Validation

• Dependency, feature framework, package-common, Gentoo builder, and transactional installer tests: 81 passed. Coverage includes real host EAPI 8 atom parsing, refusal cases, phase isolation, user-space package hooks, resource modes, and the archive-to-image path under umask 022.
• bash tests/scripts_smoke.sh: passed; the broad smoke subset reports 99 passed / 2 intentionally skipped signed-bundle tests, in addition to the Gentoo tests.
• Latest signed stable 26.1002.52244 / amd64: built the default application in scratch, generated a real local ebuild repository/payload, verified Manifest digests, and compared packaged app.asar, ChatGPT, and bundled codex byte-for-byte with the accepted build. No host package merge or GUI replacement was performed.
• Also built a default updater-free deb. RPM/pacman builds are left to upstream CI because their packaging tools are not installed locally.
• nix flake check --no-build --all-systems: passed evaluation for x86_64-linux and aarch64-linux. This is evaluation, not a claim that the full Nix builds or VM tests ran locally.
• Shell/Node syntax, relative documentation links, and git diff --check: passed.

Local environment limitations

./scripts/ci-local.sh all cannot start here because neither Docker nor Podman is installed.

The previously reported all-feature run on local Node 26.10.0 had 18 failures against unchanged upstream main: 17 Watchbound resource-copy failures plus one reaper fixture inheriting the live Wayland session. The reaper fixture passes with session variables cleared.

The Watchbound failures are now confirmed to be a real build-time Node API compatibility defect in the community feature's resource installer. It reserves the package directory with mkdir, then copies to that already-existing directory with force: false, errorOnExist: true. Node 26.10.0 now rejects that directory as documented by Node #64124. Enabling the feature while creating its resources enters this production path; the failure uses the build host's system Node.

The focused fix is tracked separately in PR #1565, an independent sibling based directly on main. Its feature suite passes 126 tests on both Node 24.19.0 and 26.10.0, and a Watchbound-only build from signed stable 26.1002.52244 / amd64 succeeds with packaged inventories and hashes verified. This Gentoo foundation PR does not contain or depend on that fix, and the supported repository feature selection remains empty. The diagnosis does not establish a defect in the Gentoo ebuild, the official GUI's runtime, or the Watchbound native engine.

Upstream CI uses Node 24 for this PR's source tests and supplies the package/build matrix.

The historical stable-only dependency audit is not rerun. Native Gentoo systemd and ARM64 runtime environments have not been tested.

Review gate and draft status

The complete origin/main..HEAD diff was independently reviewed with gpt-6.1-sol at maximum reasoning effort. Initial review found two directory-permission blockers; both were fixed with recursive permission and archive-to-image regression tests. The complete revised diff was reviewed again, and the final result reports no actionable regressions / no remaining blockers relative to 61b1663164e3f141ba1a307cc61a1d4e3c8fb276.

The review model ran read-only checks; the full filesystem-writing packaging tests and official-payload builds listed above were run separately in the writable local validation environment.

Opening as Draft to run upstream PR CI; not requesting maintainer re-review or merge yet.

[ilysenko]

Reviewed the complete shared packaging and Gentoo foundation diff, including two independent reviews. No blocking regressions found; all 22 current-head checks pass. Phase separation, permission preservation, signed-stable verification and update-builder closure are consistent. Full Portage lifecycle validation remains a documented limitation; no repository feature is declared Gentoo-supported yet.