alkgen/tasks/implementation/w2-ssr-proof.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
w2-ssr-proof	Wave 2: the ssr-html proof (posture B, consumer-shaped fixture through the public API)	completed		narrow	low	component	implementation

Description

The generality claim re-proven on shipped code for the posture-B shape (emit.md): a full consumer-shaped fixture set, modeled on the alkforge posture, rendered entirely through the public API. Where the wave-1 double proved the machinery minimally, this proof walks the ssr-html target's real shape at fuller scale: if the shipped core serves a consumer-shaped set with no core exceptions, ADR-001's generality claim holds on the real code, not just the POC.

The proof lives in its own test binary (tests/ssr_proof.rs) with its own fixture assets under tests/fixtures/ssr_proof/, following the wave-1 convention that each test binary owns its fixture modules (no module-sharing collisions with the wave-1 doubles; shared assets may be re-included via include_str! of the same files).

• Consumer-supplied registration (ADR-008 machinery equality): every page template and partial registers from the test binary as caller-supplied text through register_template / register_partial, the identical machinery engine-owned sets use. No core source access, no second-class path.
• Pages compose fragments; fragments render directly (core.md render-name rule, emit.md posture B output unit): a full page template composes fragment partials via includes; at least one fragment a consumer would serve directly (header, nav, or card shape) registers as its own template and is rendered by name, never as a bare partial.
• HTML-escape golden pins (ADR-005, convention 7): goldens pin hostile interpolated data entity-escaped, and a deliberate raw-output slot ({{& }}) pinned passing through verbatim.
• Error-page mapping (posture-B error posture, emit.md): a strict-mode render failure returns the typed Error; the proof maps it consumer-side toward an error-page shape (a fallback page built from the error's data) without panics, demonstrating that everything a consumer needs for the mapping is reachable through the public enum.
• Determinism as the caching substrate (ADR-003): repeated renders are byte-identical; this is the property alkforge's content-hash caching rests on.
• Posture-B hygiene rows: no banner, no filesystem, no emit-layer output hygiene beyond what render returns.

The stop-and-book rule applies: if the proof finds the shipped core cannot serve this set without a core change, book it for the gate with written rationale; never silently absorb it and never patch the core invisibly (ADR-001 falsifiability discipline).

Acceptance Criteria

• the full fixture set registers from outside the crate through the public API only (caller-supplied text; ADR-008 equality exercised at posture-B scale)
• a page template composes fragment partials; at least one fragment is a registered template rendered directly by name
• HTML-escape goldens pin: interpolated hostile data escaped, a deliberate raw-output slot verbatim
• a strict-mode render failure maps toward the error-page shape through the typed error, panic-free, using only public API data
• repeated renders produce byte-identical output
• posture-B hygiene rows confirmed: no banner, no filesystem
• cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check pass
• no core changes required; any gap found is booked for the gate in Notes per the stop-and-book rule

References

• docs/plans/implementation.md (wave 2, the ssr-html proof bullet)
• docs/architecture/core.md (registry construction, render entry point, template assets)
• docs/architecture/emit.md (posture B: consumer, output unit, hygiene, errors)
• docs/architecture/decisions/001-one-core-template-set-targets.md (the generality claim being re-proven)
• docs/architecture/decisions/006-ssr-library-posture.md
• docs/architecture/decisions/008-template-set-ownership.md
• tests/ssr_fixtures.rs (the wave-1 double this proof grows beyond; per-binary fixture module convention)

Notes

Filled by implementation (2026-11-06). The shipped core served the full set with no core changes required; the stop-and-book rule found nothing to book. Details:

• ADR-008 machinery equality exercised in three caller-supplied text shapes at once: include_str! fixture files (page, header, nav, footer, settings_page), a runtime-built String (the card fragment template, assembled from String::push_str parts), and an inline literal (the error page). All register through the identical register_template / register_partial machinery; no second-class path exists in the API to even attempt.
• Composition and the render-name rule coexist cleanly: card registers as its own template, is included in the page via {{> card }} inside {{#each}} (posture B: fragments a consumer serves directly are render targets), and renders directly by name; the header partial's name is rejected by render as typed Error::Render.
• Error-page mapping: a strict-mode failure on settings_page (missing account.email) returns Error::Render; the proof maps it to a consumer-built fallback page from err.to_string() and err.source() (the substrate detail, reachable via std::error::Error::source). Substrate detail observed: template name, line/column, and the missing path all survive into the mapped page, entity-escaped. Panic-free by construction.
• Determinism pin: repeated renders byte-identical, byte-identical across registry rebuilds and fresh contexts, and the write sink (render_to_write) agrees byte-for-byte with the string sink (ADR-003; the substrate alkforge caching leans on).
• Hygiene rows: the pinned page output is unadorned served HTML (starts at the doctype, no DO-NOT-EDIT banner, no "Auto-generated" marker); registration is string-only by construction, no filesystem path exists. No emit-layer hygiene beyond what render returns.
• Template whitespace note (observation, not a gap): the substrate consumes the newline around lines whose only content is a block expression ({{#each cards}}{{> card}}{{/each}}) while keeping standalone partial lines' newlines. The goldens pin this behavior, so it is now part of the pinned surface; consumers relying on exact byte layouts have the golden as precedent.
• Goldens follow convention 7 and are exact; the handlebars html-escape posture (including = as = and ' as ' inside interpolated attribute values) is exercised and pinned.

Summary

Implemented tests/ssr_proof.rs plus fixtures under tests/fixtures/ssr_proof/ (page, header, nav, footer, settings_page templates) following the wave-1 per-binary fixture convention. Four tests cover: the full consumer fixture set rendered as an exact golden with escape and raw-slot rows (page), the card fragment registered as a template and rendered directly, the strict-failure to error-page mapping built from the typed error's public data, and determinism across repeats, rebuilds, contexts, and both sinks. All registration flows through the public API from the test binary; no core change was needed (stop-and-book: nothing to book). Verification: cargo test (31 passed), cargo clippy --all-targets -- -D warnings, and cargo fmt --check all pass.