test(fresh): no capability to assert the deferred coordinator reaches the client bundle

[rickylabs]

Summary

#1459 fixes the deferred-refresh coordinator so a partial-miss region actually issues its configured partial request. Its acceptance also asked for a regression test that builds the Fresh client bundle, navigates into a page with a cache-miss deferred layer, asserts the partial endpoint is requested, and asserts the named boundary swaps exactly once.

That test needs capability this repo does not have. It is tracked here rather than ticked on weaker evidence.

What is missing today

• No browser driver in repo test infrastructure. Playwright appears only in documentation and in the CLI scaffolding that generates a Playwright config for consumer projects (packages/cli/src/public/features/agent/init/init-agent.ts); nothing in this repo's own gates drives a browser.
• No gate builds or inspects a client bundle. Nothing under packages/cli/e2e/src or packages/cli/e2e/suites runs a Vite build or asserts on _fresh output.
• The closest existing capability is a live Fresh dev server over HTTP (packages/cli/e2e/src/application/gates/scaffold/probe-project-boundary-dev.ts:43 with FetchHttpAdapter) — it can assert on responses, but cannot trigger a client navigation, which is what this defect depends on.

Why it was split out

#1459 is a p1 0.0.6 blocker: a documented withLayer({ partial, fallback }) pattern paints a skeleton that never resolves. Landing that runtime fix should not wait on net-new browser-test infrastructure, which is its own piece of work with its own design questions (which level to test at, what to add to CI, and what it costs per run).

Per the harness honesty rule, the criterion moves with a written reason rather than being ticked from unit tests that do not prove it. #1459's PR states plainly which of its criteria are proven and which is this one.

Acceptance criteria

• A regression test builds the Fresh client bundle for a scaffolded app using a deferred layer and asserts the deferred coordinator island is present in the client bundle
• The test navigates into a page whose deferred layer misses cache and asserts a request to the configured /partials/** endpoint is made
• The test asserts the named boundary swaps exactly once
• The chosen level (bundle-content assertion vs browser-driven navigation) is recorded with its CI cost, since this is net-new capability rather than an extension of an existing gate

Provenance

0.0.6 runtime lane reopen, 2026-08-12. Research: .llm/runs/release-0.0.6-features--orchestration/slices/research-1459.md; scope decision recorded in slices/plan-1459.md.

Refs #1459.

[rickylabs]

Scope addition: pin the two decideDeferClientAction partial-request branches directly.

Carrying this here rather than reopening #1550 (invalid) or broadening an active PR.

Why it belongs in this issue

EIS Chat PR #191 proved the forbidden pattern: never suppress a cache read or seed merely because ctx.isPartial is true. Fresh client navigation is a page partial, so NetScript intentionally treats component + authoritative cachedAt as partial-hit → skip, and only genuine absence as partial-miss → submit.

Current main is semantically correct — packages/fresh/src/application/defer/policy.ts:178-182:

if (input.isPartialRequest) {
  return input.hasCachedData
    ? { action: 'skip',   reason: 'partial-hit' }
    : { action: 'submit', reason: 'partial-miss' };
}

and #1558 already covers island registration and the f-client-nav combinations. But those two branches are not pinned by any direct assertion.

Verified against origin/main:

• decideDeferClientAction has zero occurrences in any test file.
• partial-miss appears in exactly one test — packages/fresh/tests/defer-island-client-bundle_test.ts:58 — and that is a client-bundle content check, not a policy assertion.

The consequence is what makes this worth pinning: if the two branches were inverted, that bundle test would still pass, because the string would still be present in the bundle. The regression would be invisible to the suite while producing exactly the EIS Chat #191 symptom — a cached region refusing to settle, or a fetch fired on every client navigation.

Added acceptance criteria

• decideDeferClientAction({ isPartialRequest: true, hasCachedData: true }) is directly asserted to return action: 'skip', reason: 'partial-hit'
• decideDeferClientAction({ isPartialRequest: true, hasCachedData: false }) is directly asserted to return action: 'submit', reason: 'partial-miss'
• Both assertions fail if the branches are inverted — i.e. they assert the action/reason pair, not merely that the function returns a decision
• The assertions live in a policy-level test, independent of the client-bundle content check, so bundle changes cannot mask a policy regression

These are cheap, pure-function assertions with no browser or bundle dependency — deliberately unlike this issue's existing client-bundle work, so they can land whenever this issue is picked up.

Related guard, recorded for whoever implements

isPartial is legitimately referenced on the defer path — DeferPage.tsx:182-190 gates outbound prewarm and a fallback-visible metric, not cache reads. Those lines look like the forbidden pattern and are its opposite. Do not remove them, and do not add a cache-read suppression alongside them by analogy.