Support Relay-owned draft previews and AISHL footer context

Start with the transactional template routes and rendering service, then read the existing template, preview, send, and API/OpenAPI tests named by the issue. Trace how template keys, published versions, Markdown rendering, layout context, and message creation flow through those entry points. Done means the acceptance criteria pass, including the byte-for-byte AISHL plaintext fixture and validation before any writes or enqueueing.

Support Relay-owned draft previews and AISL footer context

Status: pending
Tags: transactional, api, email
Depends on: None
Blocks: AI-Shipping-Labs/website#2009

Scope

• Add an explicit draft-preview choice to POST /api/transactional/templates/{key}/preview. draft: true renders the current editable draft even when published versions exist. An omitted or false value keeps today's resolution order: requested version, latest published version, then draft when no version exists. A non-boolean returns draft: must_be_boolean; combining draft: true with template_version returns draft: conflicts_with_template_version.
• Accept periods in template keys on every keyed template endpoint: detail/upsert, publish, versions, preview, and test-send. This unblocks the four existing AISHL coursework.* keys without allowing / or changing client scoping.
• Add markdown_layout_context as a boolean on transactional template drafts and snapshot it into every immutable published version. Expose it in template detail, list, publish, and version payloads. It defaults to false; non-boolean upsert values return markdown_layout_context: must_be_boolean. Existing drafts and versions therefore retain their current HTML and plaintext output.
• For an opted-in Markdown render source, Relay owns both layout footer rendering and the plaintext equivalent. Only footer_note, verify_email_url, and unsubscribe_url may flow from message context into the client layout. Raw HTML/text render sources remain unchanged.
• Validate those three layout values before rendering: empty values are allowed; footer_note must be text no longer than 500 characters; URLs must be text, no longer than 2048 characters, and absolute http or https URLs. Use must_be_string, too_long, and must_be_absolute_http_url as the field error codes. Escape footer text and URL attributes in HTML. No other arbitrary context value reaches the layout.
• For opted-in Markdown, produce the same AISHL plaintext contract as the website renderer: normalized Markdown text, layout brand_name, optional footer note, optional two-line verification action, and optional unsubscribe action, separated in the existing order by blank lines. Add a representative AISHL fixture that covers headings, emphasis, lists, links, footer text, verification, and unsubscribe so parity is byte-for-byte reviewable.
• Keep preview, dry-run send, and durable send on the same render-source function. Invalid layout context must fail before contact/message/event creation or enqueueing.
• Document the new preview field, versioned rendering option, dotted-key grammar, validation errors, and response fields in the API/OpenAPI docs.
• Do not alter campaign-broadcast version 1, publish or edit live templates, call AWS, or send email in this issue. AISHL will opt new template versions into this contract during AI-Shipping-Labs/website#2009 rollout.

Compatibility Boundary

• Real external client: AI Shipping Labs, while AI-Shipping-Labs/website#2009 removes its local email templates and renderer.
• Migration window: the AISHL site remains pinned to existing published versions, including campaign-broadcast v1, until reviewed opt-in versions are published and the website rollout completes.
• Observability: template and version API payloads expose the rendering option; delivered messages already record template_version.
• Removal plan: no compatibility alias or duplicate endpoint is introduced. The opt-in is a first-class Relay rendering contract. The AISHL-local renderer is removed by the blocked website issue after rollout.

Acceptance Criteria

• GET/PUT, publish, versions, preview, and test-send routes resolve a client-owned key containing periods, including all four existing coursework.* key shapes, while keys with / remain outside the route.
• Preview accepts only a boolean draft; invalid values return draft: must_be_boolean, and draft: true with template_version returns draft: conflicts_with_template_version.
• draft: true previews the saved draft after at least one version exists and returns published: false and template_version: null, with no database writes or queue work.
• Preview without draft: true preserves current version resolution and remains byte-for-byte equal to dry-run rendering for the same source and context.
• markdown_layout_context is editable on the draft, defaults to false, rejects non-booleans with must_be_boolean, is copied into each immutable version, and is returned by template and version APIs.
• With the option off, existing clients and all raw HTML/text templates keep their current HTML and plaintext rendering.
• With the option on for a Markdown template, valid footer_note, verify_email_url, and unsubscribe_url render in the client HTML layout in the existing order and are safely escaped.
• The same opted-in render produces AISHL plaintext byte-for-byte equal to the reviewed legacy fixture, including Markdown normalization, brand name, footer note, verification action, and unsubscribe action.
• Non-string, over-length, or non-HTTP(S) layout values return field-level validation errors before any contact, message, event, or queue work; unrelated context keys remain available only to the subject/body template.
• Preview, dry-run, normal send, and recipient-list send use the snapshotted option and produce the same fields for the same template version and context; workers and retries deliver the stored rendered fields unchanged.
• API/OpenAPI documentation describes the new request and response contract and dotted template keys.
• Focused tests and the repository test/lint gates pass without AWS credentials or a live send.

Test Notes

• Unit/service tests: draft versus published source resolution; option snapshot immutability; validated layout allowlist; HTML escaping; URL rejection; exact AISHL plaintext fixture; default-off and raw-template behavior.
• API/view tests: dotted-key detail/upsert, publish, versions, preview, and mocked test-send; draft: true; invalid/non-boolean draft; mutual exclusion with template_version; client isolation; option round trip in list/detail/version payloads.
• Pipeline tests: preview equals dry-run; mocked durable and recipient-list paths render the same published version; retry and worker paths deliver the stored fields unchanged; invalid layout context creates no rows and enqueues nothing.
• LocalStack/mocked AWS tests: no LocalStack or real AWS needed; sender/queue boundaries stay mocked.
• UI/screenshot checks: not applicable; this is an authenticated API and rendering-service change.

Blocked by: None