Upgrade age-qualified dependencies and expand Astro incremental-build pilot

[David Pine (IEvangelist)]

Summary

Upgrade age-qualified dependencies/tooling and deliver a qualified opt-in Astro incremental-build pilot for API outputs, owned OG images, and unchanged search bundles. On final head 0f88613c, the real API-data edit is 22.58% faster including measured cache upload and restore versus an ordinary cache-warmed full build. Repeated unchanged-input comparisons save 25.66%-29.23% net. Production remains full-build pending a separate rollout decision.

Measured results against ordinary full builds

Matched comparison	Ordinary full, cache-warm	Incremental	Upload + restore	Build + transfer	Net saving
Unchanged inputs	822.931s	591.759s	15s + 5s	611.759s	211.172s / 25.66%
Unchanged inputs, reversed-order repeat	818.567s	559.332s	15s + 5s	579.332s	239.235s / 29.23%
Real API-data fixture commit	718.429s	547.206s	4s + 5s	556.206s	162.223s / 22.58%

Each pair uses its own runner with matching source/environment and captured public network inputs. Warm controls run full-before-incremental and incremental-before-full. The warm job's single measured 20s transfer probe is applied to both warm comparisons; the repeat is not a second independent transfer measurement. The API mutation has its own 9s probe. These totals exclude qualification-only snapshot/checksum overhead and are not whole-workflow speedups.

The API source changes from ba58d0a9 to ca792a51; both compared builds use the normal PR merge-base identity 12201cf1. A real source change is not necessarily a rendered identity change. A separate real-identity scenario proves current identity/source links and search regeneration; do not extrapolate the API result to every production deployment.

Earlier 8.78% API-only results used forced-clean controls. The current harness separately measures ordinary cache-warm full builds without --force, retaining forced-clean only as the exact-output oracle. Results from different runs/runners are not a controlled old-vs-new comparison.

Implementation

• Twelve owned API HTML/Markdown families use complete package/module keys, including siblings. Warm builds restore 7,362 HTML / 7,321 Markdown outputs; API mutation restores 7,350 / 7,309, rerendering changed routes.
• Both owned OG route families now use native cache keys: 543 of 545 images restored. Renderer code, fonts, local thumbnails/background, topic configuration and locked toolchain remain guarded by the conservative compatibility partition. Emoji-rendered cards stay uncached because their SVG network inputs are mutable; successful rendering and offline behavior are unchanged.
• Reuse the complete Pagefind bundle only when complete eligible HTML, URL inventory and indexing environment match. Retain head metadata, filters, language and identity; do not normalize content or weaken comparison. Pagefind's documented custom-body selection excludes unmarked pages after a parsed real-attribute guard, while raw-marker candidates are conservatively included. Actual run fingerprints cover 7,827 of 15,398 HTML files.
• Wrap Starlight's build-done indexer through the integration object. Misses call the original hook; cache hits still run deterministic manifest finalization. Verify all cached files before restoring, rebuild missing/damaged entries, honor force, and propagate operational failures. Search-cache work, including input hashing and restore, takes roughly 18-24s on warm runners; identity changes correctly miss.
• Preserve exact-content identity-position reuse, equal-width UTF-8 stamping, bounded I/O, and public-prerenderer metadata scoping. Cached/raw output remains separate from deployable output; current footer/source metadata and cross-deployment navigation behavior are retained.
• Normal and pilot artifact uploads require a successful build step and !cancelled(). Later test failures can retain successful-build diagnostics, but failed builds do not upload artifacts. Bounded mismatch counts/paths remain in failure logs. The harness recognizes Astro's slash-terminated OG endpoint log paths without broadening route-family permissions.
• No contributor-guide changes remain in the PR. Internal investigation details live in the session plan.

Scope and limitations

Cold/global-invalidated builds remain slower. The global CSS fixture takes 948.537s forced-clean versus 1,250.094s incremental (+31.79%); the OG-background fixture takes 723.139s versus 1,004.669s (+38.93%), before transfer. Both correctly invalidate and match output. Cold population must be amortized, and caches are larger: 24,807 files, about 2.49 GB raw / 196 MB compressed. Both isolated transport probes restored and verified every byte.

Starlight documentation HTML, finer-grained global invalidation and compilation caches are not enabled. Broad docs/shared-source/runtime/configuration changes intentionally invalidate reuse. Astro 7.3.3's image-retention/CSS-preprocessor fixes become seven-day eligible on September 23, 2026 at 19:45 UTC; broader documentation caching remains gated on a separately qualified upgrade. Local incremental commands remain opt-in; local performance was not measured and no local production build ran.

Dependency upgrades and compatibility work retained

• Cohort includes Astro 7.3.2, Starlight 0.42.0, MDX 8.0.1, Expressive Code 0.44.2, Vite 8.3.0, Vitest 5.0.0 and Playwright 1.63.0, Node 24 LTS and compatible NuGet/SDK/MCP tooling. Both npm roots enforce seven-day publication age, transitive checks, missing-time rejection and public-registry lockfiles.
• Compatibility holds: TypeScript 6.0.3, Mermaid 11.16.1, UnoCSS/@unocss/astro 66.9.2, existing Front Door preview, and pnpm 11.26.0 with enterprise-approved action-setup 6.0.10. Unverified/orphaned tooling references remain held. Nested MDX/Twoslash processors remain distinct.
• Fix observed native-popover, API-sidebar breakpoint, modal-detection and homepage-contrast regressions, retaining ClientRouter and interaction/accessibility coverage.
• Fix generation nondeterminism rather than masking differences: preserve icon safelists, remove unused random media attributes, complete syntax/Twoslash highlighting, and deterministically serialize Pagefind language metadata. Qualification replays existing public contributor/icon responses and sets optional RSS fallback timestamps. Every generated file is compared without exclusions or normalization.

Third-party links and affiliations

No new third-party service links in authored site content. Generated gh-aw guidance links upstream GitHub documentation; npm uses its public registry. Qualification uses existing public contributor/icon endpoints without persisting credentials.

Validation

Final head 0f88613cea87a0c21be5073f30fcb84a8a7ecdc3: all 22 checks passed.

• Ordinary CI 35647584985: production build, desktop/tablet/mobile Chromium, AppHost, report merge and CI gate passed. CodeQL, generator tests and other final-head checks passed. Artifact upload followed the successful build.
• Six-scenario matrix 35647584463: warm/repeated reuse, genuinely changed identity, real API add/delete/rename/sibling edits, global CSS invalidation, OG-background invalidation, and partial API/OG/search-cache recovery all passed.
• 28 complete-output parity comparisons, with 33,888-33,896 files per site; zero missing, extra or changed files in every matched comparison. All jobs passed lint, unit tests and the complete built-site browser matrix. Warm/API jobs each report 668 unit tests and 579 browser passes / 75 applicability skips.
• Unit coverage includes both OG route families and emoji exclusions, complete-input search invalidation, missing/changed/extra cache files, malformed manifests, force recovery, hook ownership/delegation, actual Starlight/Pagefind byte parity after excluded API edits, and exact restored-route log parsing.
• Actual opt-in Astro setup/done hook wiring verified locally without bundling/rendering. Full local lint and unit suite passed. Direct tsc has existing repository issues: a compiler-host comparison reports 191 baseline / 191 current diagnostics, zero introduced, not a clean whole-repository type-check claim.
• Fixed dependency cutoff remains September 11, 2026, 14:59:53 UTC: 967 versions / 905 package names / 221 introduced versions audited without introduced prereleases/deprecations or age failures. Performance expansion adds no dependencies.
• Both measured transport probes verified all 24,807 cache files. Their two task-owned diagnostic cache entries were then removed; trusted/dependency caches were untouched. The expensive pilot label is removed after qualification.

Fresh upstream main remains 12201cf1, zero commits behind. No published history rewrite, merge, deployment, production enablement or trusted-cache publication. Diagnostic sites can contain deliberate fixtures and must not be deployed. Browser coverage is the existing Chromium viewport matrix, not Firefox/Safari; no finite suite guarantees every possible behavior.

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1698. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.