[roodboi]

Summary

User decision (2026-10-19): in v5, unchanged real Compose projects stay on the supported Compose backend. Native support for these features is post-v5 work (HACK-1270). This PR makes native hack up and hack restart refuse each blocking Compose feature exactly, before any mutation. It also documents the features and adds a hack doctor check that reports them.

The explicit HACK_NATIVE_ADAPTATION path stays supported. A network that a valid adaptation lists in isolatedNetworks is not treated as an external network: the check classifies the Compose file after that adaptation, as native start does.

Root cause

Native image-project up (handleNativeUp → startNativeProject) had no early classification of Compose-only features:

• External networks and non-arm64 platform were not checked on the TypeScript side. They failed only after runtime check-project-share, run-storage preparation, lifecycle before hooks and runtime up (the runtime-core review rejects external_network, and registry admission selects arm64 only).
• Builds and labels were refused, but only as the general NATIVE_CONFIGURATION_REFUSAL. That came after the source preflight and storage preparation, and it did not say the project belongs on the Compose backend.

Rework after verification (adaptation regression)

The first version of this PR (9ce0f3b) read only the original .hack/docker-compose.yml. It ignored the documented HACK_NATIVE_ADAPTATION isolatedNetworks selection, which native start applies to the normalized copy (replaceNetworks sets x-hack-isolated). So "isolatedNetworks": ["hack-dev"] with an external hack-dev network was refused with the Compose-backend line before the adaptation was read. That blocked up, restart and restart --recover, and native doctor warned about it. On next the same project passes native review and reaches runtime check-project-share and runtime up.

Fix (76003b5):

• findComposeBackendFeatures(compose, {isolatedNetworks}) does not count a network named in the set as external. Other features are unaffected.
• readComposeBackendFeatures(composeFile, {adaptationFile}) reads the selection only when the unadapted file has an external network. A project without one keeps its existing refusal order.
• readAdaptedIsolatedNetworks reads the file with native start's own readNativeSelection (absolute path, bounded, unchanged regular file). If the file cannot be read, the selection is not version 1, or isolatedNetworks is not a bounded list of unique strings, it refuses with the same one-line E_CONFIG_INVALID message native start gives, before any runtime request. Native start still validates the whole selection against the normalized Compose file, including that each listed name is an external network.
• handleNativeUp (covers up, restart and restart --recover) passes process.env.HACK_NATIVE_ADAPTATION, the same value it gives startNativeProject. Native doctor passes the same value. Compose doctor does not, because the adaptation is native-only.
• Docs: the "External network" row, the refusal-contract paragraph and the doctor paragraph in docs/guides/native-candidate.md now describe the adaptation. The adaptation section links back to the Compose-backend section, and docs/reference/native-config-import.md qualifies its summary. The two sections no longer contradict each other, and isolatedNetworks is not retired.

Fix (unchanged from the first version)

• src/lib/native-compose-backend-features.ts classifies the project's Compose file into a closed, ordered set: external_network, reserved_label, unsupported_build, foreign_platform.
  • External network: top-level external: true or external: {name}, unless it is x-hack-isolated: true or isolated by the adaptation.
  • Reserved ownership labels: keys starting with com.docker.compose., io.hack-local. or io.hack.native-config., on service, network and volume labels. Routing (caddy*), cache (hack.dependencies.*), one-shot and other ordinary labels keep their native behavior.
  • Build: reuses the import preview's mapLegacyComposeBuild. The result matches what hack config import --dry-run reports as invalid_or_unsupported_build or image_build_exclusive.
  • Platform: anything other than linux/arm64 or linux/arm64/v8.
• handleNativeUp calls refuseNativeComposeBackendFeatures after option refusal and project selection, before branch, config, env-fingerprint, lifecycle, shared-source, storage and runtime work. --detach still gets its one-line E_USAGE first (fix(cli): pass child flags through and print closed native refusals #359). down is not affected. Authored and adopted native-config projects go through tryNativeComposeCommand first and never reach this check.
• Each refusal is a HackCliError with the stable code E_NATIVE_PROJECT_UNSUPPORTED and one value-free line that names every feature found and the HACK_RUNTIME_BACKEND=compose selection. detail is {backend: "compose", features: [...]}.
• Unreadable, oversized (over 256 KiB), symlinked or unparseable Compose files produce no features. Native input review still refuses them as before.
• hack doctor has a compose backend features check, in both native and Compose doctor. On native, a feature found is a warn. On Compose it is informational (ok). With --json, the check carries composeBackend.features (closed names only).

The CLI surface (options and help) is unchanged, so docs/reference/cli.md was not regenerated.

Tests

• tests/native-compose-backend-features.test.ts (unit, 13 tests). The original cases are kept. New in the rework:

  • An adaptation-isolated network is not external. A parity check runs the real adaptNativeProject on the same selection and classifies its normalized output the same way. A network that is not listed is still external, and isolation never hides another feature.
  • A file classified with a valid isolating selection has no features, while a selection that lists another network or has no isolatedNetworks leaves the external network.
  • Five invalid selections refuse with E_CONFIG_INVALID and the exact message. For each one, the real adaptNativeProject throws the same message. Without an external network the selection is not read. Missing and relative paths refuse.

• tests/native-compose-backend-features-cli.test.ts (real CLI through privateCliEnv, stub runtime, 15 tests). The original cases are kept. New in the rework:

  • The verifier's repro: external hack-dev + {"version":1,"isolatedNetworks":["hack-dev"]} + HACK_NATIVE_SHARED_SOURCE=1. hack up passes the check and reaches runtime check-project-share and then runtime up, as on next.
  • hack restart with the same selection reaches restart preflight's own Native restart has no existing run line.
  • A selection that isolates a different network still gets the Compose-backend line, with 0 runtime calls and an unchanged tree.
  • An invalid selection (version 2) gets one E_CONFIG_INVALID line, with 0 runtime calls and an unchanged tree.
  • Native doctor --json with the selection reports ok and features: [].

• Mutation proof for the rework. Each mutation was applied, both files run, and the change reverted with git checkout:

  Mutation	Failing tests
  handleNativeUp does not pass the adaptation	3 (up, restart, invalid selection)
  Classifier ignores the isolated set	5
  Selection read even without an external network	1
  isolatedNetworks shape not validated	1
  version not validated	2
  Native doctor does not pass the adaptation	1

  The first version's mutation results (removing the call, each rule, doctor wiring) still apply to the unchanged cases.

Evidence

• Bun 1.4.2 (mise x bun@1.4.2), macOS arm64 host. Load average was between 30 and 95 during these runs.

• bun run --cwd packages/cli typecheck: 0 errors. bun run --cwd packages/cli check: 0 errors and 34 existing warnings. biome check on the changed files is clean.

• Focused and required: the two PR test files, tests/cli-spawn-env-isolation.test.ts, tests/cli-reference-docs.test.ts, tests/integration-ownership.test.ts and tests/native-refusal-cli.test.ts: 63 pass, 0 fail.

• tests/doctor-*.test.ts, tests/native-project-adaptation.test.ts and tests/native-config-import*.test.ts: 539 pass, 3 fail. The 3 failures are the capture process-group tests in tests/native-config-import-build.test.ts (about 505 ms each). The verifier found the same failures with origin/next source, so they come from this host, not this PR.

• After bun run build and bun run build:config-compiler, all six scripts/check-native-*-plan-cli.ts exit 0. No native refusal code or message changed. The E_CONFIG_INVALID adaptation message is native start's existing one.

• gitleaks 8.30.1: no leaks. The scan ran as gitleaks dir on a git log -p origin/next..HEAD export, because the worktree sandbox blocks gitleaks git.

• Full bun run test: exit 1 after 1 h 27 min on the loaded host. 114 files had failures in the parallel run. A serial rerun of each with --timeout 60000 left 20 files failing. 19 are authored/adopted native-compose suites, which never reach handleNativeUp's check, and their failures are fixture timeouts and unsettled children. The 20th, native-env-metadata, passed 32/32 on a later rerun with this PR's code. As a baseline, src/commands/project.ts and src/commands/doctor.ts were swapped to the merge base ec223cdb. native-compose-down-command (1/13), native-compose-storage-fence-cost (0/4), native-compose-retained-storage-command (0/5) and native-authored-process-incarnation (9/1) failed the same way, so these failures are inherited under this load.

• The adaptation CLI case also accepts a timed-out or unreadable stub reply (94e12a9). Under load, both appeared in the parallel run, and each is reachable only after the check passed. The original control: ordinary labels… case is sensitive to the same load in the parallel run and passes serially.

• Hosted CI on 76003b5: every job passed except docker-e2e shards 3 and 4, which hit the same inherited failures as on 9ce0f3b:

  • Shard 3: the pattern-p01-dependency-bootstrap docker inspect … No such object race.
  • Shard 4: native-config-build and native-config-down-hooks (also failing on the next base run 39663080763).

  The run on 94e12a9 was in progress when this was written. Shards 1–3 and all other completed jobs passed.

Remaining gaps

• The Compose-doctor variant is covered by a unit test of its result, not a CLI run, because the private CLI harness does not stub its Docker-era checks.
• Only the explicit platform field is classified. An image with no platform that publishes only amd64 is still refused later, at native image admission, with the existing image refusal.
• Only .hack/docker-compose.yml is classified. Compose override files and env-overlay interpolation are not evaluated. An interpolated platform such as ${PLATFORM} is treated as non-native.
• The check validates only the version and isolatedNetworks parts of the adaptation. Native start still validates the rest of the selection, and that each listed name is an external network, in its existing order. A listed network declared in the legacy external: {name} form passes this check. Native start's adaptation then decides it as before, because replaceNetworks accepts only external: true in the normalized file.
• Native support for these features stays in HACK-1270. Real-project acceptance has not been run here.

Refs HACK-1291

🤖 Generated with Claude Code

[linear-code]

HACK-1291

[blacksmith-sh]

Found 1 test failure on Blacksmith runners:

Failure

Test	View Logs
native-config-build (125.6s) — Native --profile must succeed/ native-config-build (125.6s) — Native --profile must succeed	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}