iptvnator/docs/superpowers/specs/2026-07-25-coverage-integrity-runtime-boundaries-design.md

Coverage Integrity And Electron Runtime Boundaries Design

Status

Approved in the delegated coverage-audit task on 2026-07-25.

Before recording the final ratchets, the implementation branch was rebased onto fresh origin/master commit 7e8c2ccce16b71d72a64c45f1d96dd090dc8e077.

Goal

Increase confidence in security-sensitive and runtime-sensitive Electron behavior while making the merged Tier A coverage report fail closed when Jest cannot instrument executable production source.

This is a risk-weighted first change. It does not try to maximize a global percentage by testing type-only modules, re-export shims, or low-risk code.

Fresh Baseline

An uncached pnpm run coverage:ci on 7e8c2ccce16b71d72a64c45f1d96dd090dc8e077 completed successfully and reported:

Metric	Covered / total	Percent
Statements	24,982 / 36,062	69.27%
Branches	17,465 / 29,637	58.92%
Functions	5,785 / 8,577	67.44%
Lines	24,323 / 34,959	69.57%

The successful command nevertheless printed Failed to collect coverage for libs/m3u-state/src/lib/effects.ts. TypeScript could not resolve @angular/material/snack-bar, inferred the injected snack bar as unknown, and did not see the shared window.electron declaration under the project's spec compiler configuration (TS2307 once, TS2571 twice, and TS2551 once). The file was absent from both the project report and coverage/merged/coverage-final.json.

All 30 Tier A projects produced a coverage-final.json, so 31 report files including the merged report existed. The current merge included all 30 project reports and 709 files while still missing an executable file. This demonstrates that project-level report existence is necessary but not sufficient.

The audit file status on the same baseline is:

File	Statement coverage
apps/electron-backend/src/app/workers/database.worker.ts	0 / 207 (0%)
apps/electron-backend/src/app/events/remote-control.events.ts	0 / 115 (0%)
apps/electron-backend/src/app/server/http-server.ts	0 / 73 (0%)
apps/electron-backend/src/app/events/database/downloads.events.ts	69 / 147 (46.93%)
apps/electron-backend/src/app/events/settings.events.ts	16 / 27 (59.25%)
libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.ts	0 / 206 (0%)
libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.ts	0 / 166 (0%)
libs/m3u-state/src/lib/effects.ts	absent

The original audit is therefore partly stale: downloads.events.ts gained a meaningful regression suite on master, and settings.events.ts already had logging coverage. Both remain in this PR because their uncovered IPC contracts are part of the approved Electron boundary, but new tests must cover missing behavior rather than repeat existing assertions.

Scope

Included

• Add behavioral coverage for HttpServer routing, static serving, traversal containment, MIME responses, and lifecycle.
• Add behavioral coverage for the remote-control HTTP and IPC boundary: method checks, renderer commands, status, channel-number validation, malformed JSON, and the 10 KiB body limit.
• Extend settings IPC coverage for argument normalization, defined-only persistence, frame-copy boolean normalization, remote-control fallback, and runtime server reconciliation while preserving redacted logging.
• Extend downloads IPC coverage around the managed-file authorization boundary before revealing or opening local paths. Preserve the existing destructive cleanup and pause/resume regression tests.
• Fix the m3u-state spec compiler configuration so effects.ts can be instrumented and appears in its report.
• Add a fail-closed integrity gate for instrumentation errors, missing Tier A reports, missing executable source files, merged metric regressions, and regressions in the selected critical Electron files.
• Document the resulting coverage workflow in docs/architecture/validation-map.md.

Deferred

• database.worker.ts: its 950-line worker-thread dispatcher and database operation surface deserve a dedicated worker-contract design and PR.
• workspace-dashboard-rails.component.ts: the existing same-name spec tests extracted helpers but never instantiates the 660-line component. Component coverage belongs in a focused Angular dashboard change.
• stalker-search.component.ts: the 510-line search surface and portal store interactions belong in a focused Stalker search change.
• Broadly raising every current 0% Tier A file.
• Adding tests to type-only/shared interfaces or pure re-export modules to inflate aggregate metrics.
• Unrelated production behavior changes.

Coverage Integrity Architecture

Shared integrity module

Create a pure Node module under tools/coverage/ that owns:

• source-file exclusion rules;
• TypeScript AST classification of runtime-owning files;
• coverage path normalization;
• project- and merged-report completeness checks;
• instrumentation-error marker detection;
• merged and critical-file ratchet evaluation; and
• diagnostic formatting.

The runner, merge script, health script, and Node unit tests use this module so the definition of an expected executable file does not drift between stages.

Runtime-owning source classification

For each Tier A sourceRoot, recursively consider production .ts files. Exclude:

• *.spec.ts and *.test.ts;
• *.d.ts;
• test-setup.ts, test stubs, and generated files;
• environment files; and
• index.ts, matching the existing Jest collection exclusions.

Parse each candidate with the TypeScript compiler API. A file is expected in coverage when it has at least one top-level runtime-owning statement. Import declarations, interfaces, type aliases, pure export declarations, empty statements, and ambient declare statements do not make a file runtime-owning by themselves. Classes, functions, variables, enums, expressions, control flow, and other emitted statements do.

This rule intentionally checks executable ownership rather than all TypeScript text. It excludes type-only contracts and re-export shims without maintaining a large hand-authored manifest. A discovery prototype over the fresh baseline classified 591 of 655 Tier A TypeScript source files as runtime-owning and identified exactly one absent file: libs/m3u-state/src/lib/effects.ts.

Coverage keys and expected source paths are normalized to absolute POSIX-style paths before comparison so diagnostics are stable across supported CI platforms.

Runner behavior

run-tier-a-coverage.mjs must continue relaying each child process's stdout and stderr as it arrives. It also scans a bounded rolling text window, with ANSI escapes removed, for Jest's Failed to collect coverage marker.

After each project command finishes, the runner must fail if:

• the Nx/Jest command exits nonzero or terminates by signal;
• the output contains an instrumentation failure marker;
• coverage/<project-root>/coverage-final.json is missing or invalid; or
• a runtime-owning file under that project's source root is absent from the report.

The implementation should use asynchronous child-process streams rather than buffering the full multi-project Jest output in memory.

Merge behavior

merge-coverage.mjs must require exactly one valid report for every configured Tier A project. It must list all missing or invalid reports and exit before deleting or rewriting coverage/merged.

The current .filter(existsSync) behavior is removed because it silently merges partial input.

Health behavior

coverage-health.mjs --require-report independently reruns:

• per-project report existence and JSON validity;
• runtime-owning source completeness;
• merged-report completeness and usable instrumentation for every runtime-owning Tier A file;
• merged metric ratchets; and
• selected critical-file ratchets.

It computes the aggregate summary from that validated merged map before checking the serialized summary and ratchets. This defense in depth catches stale, incomplete, or manually merged reports even when the runner was not the process that generated them. Local health checks without --require-report retain their current warning behavior when report artifacts are not available, but any present invalid report remains an error.

Ratchets

The policy stores four merged minimum percentages and per-file statement minimums for:

• http-server.ts;
• remote-control.events.ts;
• settings.events.ts; and
• downloads.events.ts.

The implementation begins with the fresh master aggregate baseline shown above. After the approved behavioral suites and the effects.ts instrumentation fix are complete, the policy is updated to the reproducible post-change values. Those final values become the ratchet: they may stay level or rise in future changes, but must not be lowered merely to make CI green.

Per-file minimums are likewise recorded from the achieved behavioral suites, not from an arbitrary aspirational percentage. The two currently uncovered files must become nonzero; the existing settings and downloads coverage must not regress. A reviewed production source shrink is the sole exception to the normally monotonic absolute minimumCovered: a PR may lower it only when it identifies the removed executable statements and a fresh full report proves that the file's minimumPercent, all aggregate ratchets, and coverage of the remaining behavior stay level or rise.

Behavioral Test Design

HTTP server

Use a temporary static directory and a real loopback Node HTTP server. Verify:

• / serves index.html;
• known static assets return their content and correct MIME type;
• an unknown client-side route falls back to index.html;
• a missing index.html returns a plain-text 404;
• registered remote-control API routes bypass static serving;
• unknown remote-control API routes return JSON 404;
• normalized traversal input cannot escape the configured static root;
• start, duplicate start, stop, enable/disable, and port-change restart preserve the current lifecycle contract.

Tests should prefer public behavior over direct calls to private methods. If an ephemeral port or temporary static root is not observable through the current API, introduce only the smallest constructor dependency seam required to use real Node HTTP and filesystem behavior. The production singleton keeps identical defaults.

Remote control events

Capture the HTTP handlers registered during bootstrap and exercise them with real readable request streams plus response-contract assertions. Verify:

• bootstrap registers every documented endpoint and starts the server only when stored settings enable it;
• channel up/down and volume commands accept only their documented HTTP methods and send the expected renderer event;
• channel selection accepts finite positive values, floors fractional input, and rejects missing, non-finite, or sub-one values;
• status updates merge partial IPC state and refresh updatedAt;
• status reads return the latest merged state;
• malformed JSON returns 400 without dispatching a command;
• payloads over 10 KiB return 413, destroy the request, and do not dispatch; and
• missing BrowserWindows are contained without throwing.

The existing Electron E2E remote-control suite remains the end-to-end check for real volume commands and renderer status.

Settings events

Extend the existing same-name spec. Use the real external-player argument normalizer and mocked persistent store/server boundaries to verify:

• MPV and VLC arguments are normalized before persistence;
• undefined values are not written;
• reuse flags preserve explicit false values;
• frame-copy persistence coerces to boolean;
• a partial remote-control update reads the missing half from the store;
• only explicitly supplied remote-control fields are persisted; and
• httpServer.updateSettings receives the resolved enabled/port pair.

Retain the existing assertions that logging redacts TMDB and player-argument credentials.

Downloads events

Extend the current event suite rather than replacing its destructive cleanup coverage. Verify the local-file boundary:

• a path not present in the downloads database is never revealed or opened, even when it exists on disk;
• a database-managed path missing on disk is never revealed or opened;
• only a database-managed path that exists reaches shell.showItemInFolder or shell.openPath; and
• a database lookup failure returns the existing structured not-found response and never reaches the shell.

Folder authorization internals remain covered by download-directory-authorization.spec.ts; this event suite tests only the IPC-to-authorizer and managed-path integration where it adds distinct signal.

TDD Sequence

1. Add failing Node tests for runtime classification, ANSI instrumentation marker detection, missing/invalid reports, partial merge input, aggregate ratchets, and critical-file ratchets.
2. Implement the shared integrity module and wire the runner, merge, and health scripts until those tests pass.
3. Enable the selected critical-file policy; confirm fresh targeted coverage fails because http-server.ts and remote-control.events.ts are 0%.
4. For each Electron boundary, add one contract test at a time, observe the intended failure, and make only the smallest testability refactor needed to pass it.
5. Add a failing integrity assertion for the absent effects.ts, align the m3u-state spec compiler configuration, and confirm the real file appears.
6. If a behavioral test exposes a production defect, add a direct regression assertion first and make a separately justified minimal fix. Otherwise preserve production behavior.
7. Record fresh aggregate and per-file post-change ratchets only after all behavioral suites are green.

Error Handling And Diagnostics

Integrity failures must identify:

• the project;
• the expected report path;
• each missing runtime-owning source path;
• the metric or critical file that fell below its ratchet; and
• the observed and required values.

The runner must preserve the original Nx/Jest output and child exit semantics. Integrity diagnostics are additive and must not hide the underlying instrumentation error.

Tests use temporary directories and deterministic synthetic coverage maps. They must not depend on a previously generated workspace coverage/ tree.

Success Criteria

• Fresh pnpm run coverage:ci exits nonzero for synthetic or real instrumentation collection failures.
• All 30 Tier A project reports are mandatory merge inputs.
• Every runtime-owning Tier A TypeScript source file is present in its project report.
• libs/m3u-state/src/lib/effects.ts is present in coverage.
• The four selected Electron boundary files meet their recorded behavioral statement ratchets; http-server.ts and remote-control.events.ts are no longer 0%.
• Final merged statements, branches, functions, and lines are each at least the fresh master baseline and become the new ratchet.
• Assertions verify observable contracts rather than merely invoking mocks for line execution.
• No untested production behavior change or unrelated source change is included.
• Deferred database worker, dashboard, and Stalker search coverage is listed in the draft PR.

Implementation Outcome

The fresh uncached implementation run merged all 30 required Tier A reports into the 31st coverage-final.json and included 710 files, with no collection-failure marker or missing runtime-owning source. The achieved ratchets are:

Metric	Covered / total	Percent
Statements	25,204 / 36,241	69.54%
Branches	17,573 / 29,748	59.07%
Functions	5,824 / 8,635	67.44%
Lines	24,543 / 35,136	69.85%

The selected Electron boundary statement coverage changed as follows:

File	Baseline	After
http-server.ts	0 / 73 (0%)	83 / 92 (90.21%)
remote-control.events.ts	0 / 115 (0%)	112 / 116 (96.55%)
settings.events.ts	16 / 27 (59.25%)	26 / 27 (96.29%)
downloads.events.ts	69 / 147 (46.93%)	86 / 147 (58.50%)

The integrity correction makes the denominator honest: libs/m3u-state/src/lib/effects.ts is now present at 0 / 159 statements instead of silently disappearing. The aggregate improvement therefore holds even after surfacing those 159 previously unreported uncovered statements. Strict health validation also rechecks the merged map itself, so a runtime-owning file cannot disappear between valid project reports and the merged artifact while permissive percentages still pass.

Two production seams were sufficient for isolated contract tests: HttpServer accepts an optional server factory and static distribution path, and RemoteControlEvents is a named export while the production singleton is unchanged. Real loopback HTTP tests also exposed a Windows double-leading-slash traversal escape in the prior static-path normalization. A direct failing regression preceded the narrow fix: production now uses the pure, platform-testable resolveStaticFilePath resolver to decode once, reject malformed or NUL paths, strip leading separators, resolve against the static root, and enforce containment. This is a tested behavior and security fix, not a behavior-preserving refactor.

The release decision follows that observable fix: .changes/electron-remote-static-paths.md records it as an Electron bug fix, so the draft PR must not carry no-release-note. The canonical coverage workflow is documented in docs/architecture/validation-map.md; AGENTS.md and CLAUDE.md do not describe the changed coverage contract or HTTP path logic and require no update.

The deferred production files remain uncovered in this change: database.worker.ts at 0 / 207, workspace-dashboard-rails.component.ts at 0 / 206, and stalker-search.component.ts at 0 / 166. They retain the separate follow-up scopes described above.

Validation Ladder

Run fresh, uncached validation in this order:

node --test tools/coverage/*.test.mjs
pnpm nx test electron-backend --skip-nx-cache --runInBand
pnpm nx test m3u-state --skip-nx-cache --runInBand
pnpm run coverage:unit:ci -- --projects=electron-backend,m3u-state
pnpm nx lint electron-backend --skip-nx-cache
pnpm nx lint m3u-state --skip-nx-cache
pnpm run typecheck:backend
pnpm nx run electron-backend-e2e:e2e-ci--src/downloads.e2e.ts
pnpm nx run electron-backend-e2e:e2e-ci--src/remote-control.e2e.ts
pnpm nx run electron-backend-e2e:e2e-ci--src/settings.e2e.ts
pnpm nx build electron-backend --configuration=production --skip-nx-cache
pnpm run coverage:ci

The final report records exact command results, aggregate before/after metrics, and before/after metrics for the selected critical files. If an environment prevents an Electron E2E or production build, report the exact blocker and run the strongest available lower-level contract validation; do not silently omit it.

Documentation Impact

Update docs/architecture/validation-map.md to make the fail-closed coverage contract and ratchet maintenance workflow canonical.

AGENTS.md and CLAUDE.md do not currently describe coverage commands or integrity behavior, so no update is expected unless implementation changes a process they do describe.

Draft PR Handoff

The draft PR body will include:

• fresh master baseline and post-change aggregate metrics;
• selected-file before/after metrics;
• behavioral contracts added;
• any production-only testability refactor and why it preserves behavior;
• coverage integrity and ratchet changes;
• all validation commands and results;
• the documentation decision; and
• deferred 0%-coverage follow-ups.