zenmemes

New post

Stale Fingerprinted Asset Recovery Step 3 Development Plan

Stage 1

  • Goal: Reproduce the stale HTML/asset mismatch and establish regression coverage before changing request handling.

  • Dependencies: Approved Step 2; current static artifact and fingerprinting behavior.

  • Expected changes: Add focused tests that distinguish a current fingerprint, an obsolete fingerprint for a known source asset, and an invalid/unknown asset path.

  • Verification approach: Run the focused asset and front-controller tests; confirm the current mismatch is represented without changing runtime behavior.

  • Risks or open questions:

    • Existing generated files may be stale or untracked in local environments.

  • Canonical components/API contracts touched: AssetFingerprint, FrontController, tests/LocalAppSmokeTest.php.

Stage 2

  • Goal: Recover obsolete fingerprinted asset requests safely at runtime.

  • Dependencies: Stage 1 coverage.

  • Expected changes: Extend the canonical fingerprint resolver and front-controller asset path to identify a stale hash only when its known source asset exists, then direct the browser to the current fingerprinted URL with safe cache semantics. Preserve rejection of unknown paths and arbitrary files.

  • Verification approach: Test CSS and JavaScript stale requests, current requests, unknown hashes, unsupported methods, and content-type/cache behavior.

  • Risks or open questions:

    • Redirect handling must not create loops or make obsolete URLs permanently immutable.

    • Recovery must remain limited to public assets and recognized fingerprint syntax.

  • Canonical components/API contracts touched: src/ForumRewrite/Host/AssetFingerprint.php, src/ForumRewrite/Host/FrontController.php.

Stage 3

  • Goal: Keep static HTML and fingerprinted assets consistent when artifacts are generated or published.

  • Dependencies: Stage 2 committed.

  • Expected changes: Adjust the static artifact workflow so generated pages and their referenced assets are published as one consistent artifact set, with replacement ordering that cannot expose a new HTML reference before its asset exists.

  • Verification approach: Build a temporary artifact set after changing an asset; verify generated HTML references available files and that replacement leaves the previous set usable until the new set is ready.

  • Risks or open questions:

    • The hosting environment may determine whether atomic directory/symlink publication is available; retain the runtime fallback if it is not.

  • Canonical components/API contracts touched: src/ForumRewrite/Host/StaticArtifactBuilder.php, static artifact layout, deployment-facing build flow.

Stage 4

  • Goal: Add a release-time asset-reference health check and complete end-to-end verification.

  • Dependencies: Stages 1–3 committed.

  • Expected changes: Validate fingerprinted CSS/JavaScript references emitted by generated HTML, fail or report missing assets clearly, and document the recovery and publication guarantees in the Step 4 summary.

  • Verification approach: Run focused tests, the full suite, a generated-artifact check, and a private-style request flow that loads HTML followed by every referenced asset.

  • Risks or open questions:

    • Existing unrelated full-suite failures must remain separately identified rather than obscuring asset regressions.

  • Canonical components/API contracts touched: tests/LocalAppSmokeTest.php, StaticArtifactBuilder, AssetFingerprint, FrontController, Step 4 implementation summary.

Approval Gate

  • Create the Step 4 feature branch only after explicit Approved Step 3.

  • Commit the approved Step 1–3 planning documents first, then commit each implementation stage with its Step 4 summary update.