RFC: simplify runtime, smoke and lockfile boundaries

[edbfi]

Current status — completed with accepted runtime scope exclusions (2026-09-19)

The shared implementation and immutable v3.0.1 are shipped. The original design below is retained as historical context; privileged repair expansion remains deferred until a real consumer requires it.

• Frozen Bun root/nested/workspace text/binary installation, runtime-neutral smoke lifecycle and exact isolated Biome repair, including negative fixtures: implementation #38.
• Earlier application coverage: Portaler artifact production, Website/repo-patches assets/pages, Obzorarr setup semantics, Zondarr Chromium hydration, EasyHDR Windows launch and web-presentations browser CI: evidence.
• Wings #40: real Linux service plus local panel and disposable Docker network; authenticated API, rejected unauthenticated access, SFTP, panel reset, malformed-panel startup rejection and teardown. Original platform/quality/CodeQL jobs retained; service is directly aggregated and source-pinned required. This covers rootless initialization, not live VPN/game containers.
• Mover-status #48: real entry point with isolated Unraid-compatible command/filesystem fixtures; idle/running/progress/completion, missing/malformed input, fallback sizing and delivery-error behavior. runtime is directly aggregated and source-pinned required. This is a simulated platform contract, not proof on real Unraid hardware.
• Maintained container channels identified independently: all three use nightly, with real native amd64/arm64 startup/migration/persistence/shutdown fixtures. Cleanup/artifact fixes: Obzorarr Docker #12, Zondarr Docker #5, Otpravkarr Docker #5. Both architectures passed final-PR CI and verified cleanup; uploaded evidence excludes raw logs/databases/keys. Strict Actions-source-pinned protection now requires both image jobs, hygiene and aggregate on each maintained branch. Historical release channels and manual publication controls remain unchanged. Live media/VPN integration is not claimed.
• Accepted scope exclusion: the owner explicitly excluded Guide-capture from this rollout on 2026-09-19. Its pinned encrypted Android image requires a separately prepared synthetic fixture and suitable runner; the personal enrolled image is not a CI fixture. Research and optional future work. No Android capture/encryption round-trip coverage is claimed.
• Accepted scope exclusion: the owner explicitly excluded Replex completely from this rollout on 2026-09-19. The inactive upstream-owned fork is not a remaining runtime acceptance item; decision #49. No runtime coverage is claimed and no fork settings or retained branches were changed.

This RFC is complete within the owner-approved scope. The Guide-capture and Replex exclusions are explicit decisions, not claims of implemented runtime coverage. Generic lock-resolver expansion is not an additional closure condition. TypeScript compiler/native-checker compatibility is separately tracked in #48.

---

Original problem (historical)

Bun validation assumes its install directory is also the validation command directory, and hashes every lockfile in the repository. Biome repair additionally conflates manifest, lock root, install directory and node_modules lookup, rejects workspaces, and installs the whole application before installing its official formatter separately.

Five repositories have a mandatory smoke.yml; several other apps already have stronger embedded browser/native/container checks. Copied smoke shell loops lack early child-exit detection and process-tree cleanup. A common workflow must not assume every app is Bun-based, has a root lockfile, or is an HTTP application.

Parallel interface alternatives

Approach	Interface	Benefit	Cost or risk
Minimalist	App start command + readiness URL; repository owns everything else	Tiny lifecycle interface	HTTP readiness alone can falsely imply that an app renders
Flexible	Explicit package directory, lockfile path, runtime/install/probe options, manager registry	Broad potential compatibility	Too many knobs; privileged repair adapters need independent evidence contracts
Caller-optimized	Separate Bun install-directory and working-directory; smoke start-command/url/required test-command	Supports real layouts and caller-owned assertions with little discovery magic	Consumers still own builds, databases and browser setup
Ports and adapters	Pure lock resolver; concrete GitHub evidence and local-process adapters	Immutable fixtures and side effects test independently	A full framework would add navigation overhead to small actions

Recommendation and initial implementation

Use the caller-optimized interface with small concrete modules:

• Bun install-directory defaults to working-directory; support root/nested/workspace execution with exactly one selected text or binary lock. Scope cache identity to that root and retain frozen installs and tracked-file checks.
• A runtime-neutral smoke action accepts start-command, loopback url, mandatory test-command, directory, startup and assertion deadlines. It owns readiness polling, premature-exit detection, logs, cancellation and whole-process-group cleanup. Callers own frozen installation, build, database and browser assertions. Existing Playwright webServer callers need no wrapper.
• Biome compute uses already-verified immutable lock evidence to install only the exact official formatter in isolation, validates its identity, and never installs the PR dependency tree. Keep publication and token-isolation checks intact.

The smoke action does not merge or change CI policy. Consumers must include smoke directly in their always-running required aggregate before enabling Renovate automerge.

Deferred lock resolver

When actual consumers require privileged repair beyond standalone text Bun, introduce one pure function such as:

resolve_biome(manifest, lockfile_path, lockfile_content, package_directory) -> resolution

The result records version, selected package, lockfile and resolution identity. An explicit lockfile path distinguishes package and lock roots. Publication independently recomputes identical evidence. Add Bun workspaces/npm v2-v3 only with representative fixtures; defer pnpm/Yarn/binary parsing until equivalent evidence is established. Reject ambiguous selection and nonregistry sources rather than executing a package manager to infer trust. No generic plugin registry is currently justified.

Testability and acceptance

• Real frozen Bun installs: root text/binary, nested independent locks, root workspaces with leaf commands; reject missing/conflicting locks and manifest drift.
• Smoke subprocess fixtures: delayed readiness, occupied port, early app exit, HTTP errors/redirects, assertion failure/deadline, cancellation and lingering descendants; include a repository with no package manager.
• Real Biome migration/idempotence with no PR node_modules, sanitized install/formatter environment and wrong isolated package identity rejection.
• Resolver expansion requires immutable base/head fixtures for each format, selected workspace/version ambiguity, manifest agreement and changed evidence rejected before publication.

Consumer rollout

Start with the five copied static probes. Portaler's independent smoke dispatch needs its own artifact producer or must be removed. Obzorarr needs a semantic assertion beyond readiness. Add startup tests for website/repo-patches, EasyHDR and wings-vpn, and establish CI for web-presentations. Keep native and container runtimes in their consuming repositories. Shared action release/adoption and full application reruns remain separate from local fixture validation.

[edbfi]

Shared runtime/install boundaries are released in immutable v3.0.1. Full merged-head validation includes 75 Python tests plus real frozen Bun root, nested and workspace installs with text/binary locks. Privileged Biome repair remains intentionally limited to standalone text Bun locks; no unsupported ecosystem was silently broadened.

Bounded runtime improvements merged through complete required CI:

• Portaler #89 fixes standalone smoke dispatch and retains route assertions; standalone dispatch passed.
• Zondarr #235 adds Chromium hydration/startup assertions while retaining backend/frontend/proxy/SSR checks.
• Obzorarr #198 adds semantic production setup-page assertions.
• Website #28 and repo-patches #37 serve and assert built content/assets.
• Web presentations #1 establishes protected CI for the independent nested project, including production navigation and reduced-motion browser tests.

Browser, HTTP/content, CLI and native/container checks remain distinct coverage levels. Existing checks are preserved in the pending consumer migrations. EasyHDR's real Windows GUI launch check is awaiting hosted completion. Wings service integration, encrypted live capture, and Unraid runtime fixtures still require bounded platform-specific follow-up; this RFC remains open while rollout and repair-publication evidence are completed.

[edbfi]

The shared runtime and lockfile contracts are released in v3.0.1. Final validation includes 75 Python tests, real frozen Bun root/nested/workspace installs with text and binary locks, invalid-input rejection, Renovate/workflow contracts, isolated Biome migration/idempotence and smoke deadline/process cleanup cases. Privileged repair deliberately remains limited to independent standalone text Bun lock roots.

Hosted consumer evidence now includes:

• Portaler #89: independent smoke dispatch has its own artifact producer; normal required smoke and route assertions remain intact.
• Website #28 and repo-patches #37: serve generated output and verify real pages and local assets. This is HTTP/content coverage, not hydration coverage.
• Obzorarr #198: production setup form, token and submit assertions beyond readiness.
• Zondarr #235: nested frontend install root and Chromium startup/hydration/password validation, retaining backend/proxy/SSR checks.
• EasyHDR #149: actual release executable launches on Windows with isolated application data, a responsive window and event-loop evidence; fixed-delay simulated timing is no longer presented as startup proof.
• web-presentations #1: frozen independent nested project install, build/type checks, and browser navigation, overview and reduced-motion assertions.
• Setun repair run: the repair App published the verified formatter change, followed by successful normal PR CI and explicit current-head CI. The dependency PR remains subject to its original release-age gate.

The migration/follow-up PRs and their exact default-branch checks have passed. Existing CLI, native, container and extension checks retain their distinct claims; Firefox packaging is not reported as browser runtime coverage.

This RFC remains open for bounded follow-up coverage rather than treating every application as a web server: wings-vpn needs an isolated panel/Docker/network service fixture; guide-capture needs a representative encrypted browser fixture; mover-status needs an Unraid-compatible runtime harness. Legacy container repositories still need reproducible non-production VPN/media/service fixtures. Their acceptance criteria are documented in the consumer CI notes and fleet review. These gaps do not justify weakening the current required checks.