@rubytech/create-maxy-code 0.1.62 → 0.1.64

package/payload/premium-plugins/real-agent/plugins/preval/skills/property-preval/references/render.py

@@ -2,10 +2,14 @@
 
 Substitutes <!-- REPLACE: <slot> --> placeholders in template.html with values
 derived from one inputs.json (shape: template-inputs.schema.json), drives
-Chrome headless to produce a 5-page A4 PDF, and asserts page count == 5.
+Chrome headless to produce a 7-page A4 PDF, and asserts page count == 7.
 
 Fails loud on any missing / unverifiable load-bearing input. No silent
-fallback modes — see _assert_inputs.
+fallback modes — see _assert_inputs. Task 157 layers provenance gates
+(agent_listings[].origin, agent_overrides.brand_selected_by_operator) on
+top of 156's load-bearing-input checks. `subject.narrative` and
+`market_summary` are agent-composed from the 12-call fan-out, not
+operator-supplied — only the `paragraphs >= 2` sanity check survives.
 
 Usage:
     python3 render.py inputs.json
@@ -22,8 +26,8 @@ def _money(n: int) -> str:
     return f"£{int(n):,}"
 
 
-def _range_money(low: int, high: int) -> str:
-    return f"£{int(low):,} – £{int(high):,}"
+# _range_money retired with the page-2 valuation panel. The pack no longer
+# quotes a numeric range — the human estate agent values in person.
 
 
 # ---------------- helpers ----------------
@@ -36,11 +40,12 @@ def _short_address(address: str) -> str:
 
 def _sold_comps_rows(rows: list[dict]) -> str:
     if not rows:
-        return '<tr><td colspan="4" class="muted">No sold transactions in the sample.</td></tr>'
+        return '<tr><td colspan="5" class="muted">No sold transactions in the sample.</td></tr>'
     return "".join(
         f"<tr><td>{html.escape(r['date'])}</td>"
         f"<td>{html.escape(r['address'])}</td>"
         f"<td>{html.escape(r['type'])}</td>"
+        f"<td>{r['beds'] if r.get('beds') else '—'}</td>"
         f"<td class=\"num\">{_money(r['price'])}</td></tr>"
         for r in rows[:6]
     )
@@ -127,6 +132,33 @@ def _summary_paragraphs(paras: list[str]) -> str:
     return "".join(out)
 
 
+def _variant_css(inputs: dict) -> str:
+    """Compose CSS override block for the 'on-brand' variant.
+
+    Premium variant keeps the editorial Cormorant/Lora/Inter typography lock
+    — only the brand's colour tokens and logo are applied. On-brand variant
+    overrides --display / --body / --sans with brand.font_display +
+    brand.font_body — pack typography follows the agent's DESIGN.md end-to-end.
+
+    Returns empty string for premium (no overrides applied).
+    """
+    variant = (inputs.get("variant") or "premium").lower()
+    if variant != "on-brand":
+        return ""
+    brand = inputs.get("brand") or {}
+    fd = brand.get("font_display") or ""
+    fb = brand.get("font_body") or fd
+    if not fd:
+        return ""
+    return (
+        '<style>:root{'
+        f'--display:{fd};'
+        f'--body:{fb};'
+        f'--sans:{fd};'
+        '}</style>'
+    )
+
+
 def _wordmark(brand: dict, variant: str, out_dir: Path) -> str:
     """variant ∈ {'light', 'dark'}. Mirrors property-market-report's wordmark."""
     key = "logo_light" if variant == "light" else "logo_dark"
@@ -212,81 +244,45 @@ def _agent_listings_cards(rows: list[dict], out_dir: Path) -> str:
     return "".join(_listing_card(p, i, out_dir) for i, p in enumerate(rows[:6]))
 
 
-# ---------------- valuation maths ----------------
+# ---------------- subject facts ----------------
 
-def _valuation_block(subject: dict, valuation: dict) -> str:
-    """Build the page-2 valuation panel: headline range, adjustments, final range.
+def _notable_features_block(subject: dict) -> str:
+    """Label-only bullet list from subject.adjustments[].label. No numbers.
 
-    sqft is asserted non-null upstream by _assert_inputs — no fallback panel here.
+    The pre-valuation pack does NOT quote an estimate or a range — the
+    human agent values the property in person. Adjustments survive only
+    as a "Notable features" list (operator-supplied facts the agent
+    wants visible on the cover-side of the pitch); delta_pct is held in
+    the schema for backward compat but is no longer rendered.
     """
-    sqft = subject["sqft"]
-    low_psf  = valuation["sold_psf_low"]
-    mid_psf  = valuation["sold_psf"]
-    high_psf = valuation["sold_psf_high"]
-    ask_psf  = valuation["asking_psf"]
-
-    low_raw  = int(sqft * low_psf)
-    mid_raw  = int(sqft * mid_psf)
-    high_raw = int(sqft * high_psf)
-    ask_raw  = int(sqft * ask_psf)
-
-    rows = [
-        ('<div class="val-row headline">'
-         f'<div class="lbl">Headline range<small>{sqft:,} sqft × £{low_psf}–£{high_psf} sold £/sqft (Land Registry 70pc band)</small></div>'
-         f'<div class="num">{_range_money(low_raw, high_raw)}</div></div>'),
-        ('<div class="val-row">'
-         f'<div class="lbl">Cross-check · asking £/sqft<small>{sqft:,} sqft × £{ask_psf} mean asking £/sqft</small></div>'
-         f'<div class="num">{_money(ask_raw)}</div></div>'),
-    ]
-
     adjustments = subject.get("adjustments") or []
-    if adjustments:
-        rows.append('<div class="val-row"><div class="lbl" style="font-family:var(--sans);font-weight:600;font-size:8pt;letter-spacing:2pt;text-transform:uppercase;color:var(--text-accent)">Adjustments</div><div class="num">&nbsp;</div></div>')
-        for adj in adjustments:
-            delta = float(adj["delta_pct"])
-            cls = "pos" if delta > 0 else ("neg" if delta < 0 else "")
-            sign = "+" if delta >= 0 else ""
-            rows.append(
-                '<div class="val-row adj">'
-                f'<div class="lbl">{html.escape(adj["label"])}</div>'
-                f'<div class="num {cls}">{sign}{delta:.1f}%</div>'
-                "</div>"
-            )
-
-    delta_sum = sum(float(a["delta_pct"]) for a in adjustments)
-    factor = 1.0 + delta_sum / 100.0
-    low_final  = int(low_raw  * factor)
-    high_final = int(high_raw * factor)
-
-    final = (
-        '<div class="val-final">'
-        f'<div class="lbl">Final indicative range</div>'
-        f'<div class="num">{_range_money(low_final, high_final)}</div>'
-        "</div>"
+    if not adjustments:
+        return ""
+    items = "".join(
+        f'<li>{html.escape(adj["label"])}</li>' for adj in adjustments
+    )
+    return (
+        '<div class="notable-features" style="margin-top:6mm">'
+        '<div class="eyebrow" style="margin-bottom:2mm">Notable features</div>'
+        f'<ul style="margin:0;padding-left:5mm;line-height:1.5">{items}</ul>'
+        '</div>'
     )
 
-    return '<div class="val-panel">' + "".join(rows) + "</div>" + final
+
+def _derived_sqft(subject: dict) -> int:
+    return round(float(subject["total_floor_area_m2"]) * M2_TO_SQFT)
 
 
 def _kpi_subject_sqft(subject: dict) -> tuple[str, str]:
-    sqft = subject["sqft"]
-    m2 = subject.get("sqft_m2")
-    sub = f"≈ {m2:.0f} m² · from EPC register" if m2 else "Square feet (operator)"
-    return f"{int(sqft):,}", sub
+    sqft = _derived_sqft(subject)
+    m2 = float(subject["total_floor_area_m2"])
+    return f"{sqft:,}", f"≈ {m2:.0f} m² · from EPC certificate"
 
 
 def _kpi_subject_epc(subject: dict) -> tuple[str, str]:
-    current  = subject.get("epc_current")
-    potential = subject.get("epc_potential")
-    lodgement = subject.get("epc_lodgement")
-    if not current:
-        return "—", "No EPC on file"
-    sub_bits = []
-    if potential:
-        sub_bits.append(f"potential {potential}")
-    if lodgement:
-        sub_bits.append(f"lodged {lodgement}")
-    return current, " · ".join(sub_bits) or "EPC register"
+    current  = subject["current_energy_rating"]
+    lodgement = subject["lodgement_date"]
+    return current, f"lodged {lodgement}"
 
 
 # ---------------- input assertions ----------------
@@ -303,6 +299,30 @@ class PrevalAbort(RuntimeError):
         self.hint = hint
 
 
+_STREET_TOKEN_STOPWORDS = {
+    "the", "a", "an", "of", "and",
+    "road", "street", "drive", "lane", "avenue", "close", "court",
+    "place", "way", "gardens", "crescent", "hill", "rise", "grove",
+    "terrace", "mews", "square", "park", "walk", "row",
+    "rd", "st", "dr", "ln", "ave", "cl", "ct", "pl",
+}
+
+
+def _street_token(address: str) -> str | None:
+    """First non-stopword token from the address's street component.
+
+    Used to detect cover_hero photos sourced from a sister property folder.
+    "9 Phoenix Drive, Bishop's Stortford, CM23 2UJ" → "phoenix".
+    """
+    if not address:
+        return None
+    first = address.split(",")[0].strip().lower()
+    for raw in re.split(r"[^a-z]+", first):
+        if raw and not raw.isdigit() and raw not in _STREET_TOKEN_STOPWORDS:
+            return raw
+    return None
+
+
 def _assert_path_image(path_str: str, min_w: int = 1200, min_h: int = 800) -> None:
     """Existence + dimension check. Symlinks pointing into another property's
     folder are rejected (cover-hero cross-contamination guard)."""
@@ -316,12 +336,10 @@ def _assert_path_image(path_str: str, min_w: int = 1200, min_h: int = 800) -> No
         target = p.resolve()
         parts = target.parts
         if "properties" in parts:
-            # symlink → properties/<other-slug>/… is a cross-contamination
             raise PrevalAbort(
                 "subject-cover-hero-symlinked-foreign",
                 f"cover_hero is a symlink into another property's folder: {target}",
             )
-    # Dimensions. Avoid a Pillow dep; read PNG/JPEG headers directly.
     w, h = _image_dimensions(p)
     if w is None or h is None:
         raise PrevalAbort(
@@ -343,7 +361,6 @@ def _image_dimensions(p: Path) -> tuple[int | None, int | None]:
             if len(head) < 24:
                 return None, None
             if head[:8] == b"\x89PNG\r\n\x1a\n":
-                # IHDR width/height at bytes 16..24, big-endian uint32.
                 w = int.from_bytes(head[16:20], "big")
                 h = int.from_bytes(head[20:24], "big")
                 return w, h
@@ -357,7 +374,7 @@ def _image_dimensions(p: Path) -> tuple[int | None, int | None]:
                     if not marker:
                         return None, None
                     if 0xC0 <= marker[0] <= 0xCF and marker[0] not in (0xC4, 0xC8, 0xCC):
-                        f.read(3)  # length(2) + precision(1)
+                        f.read(3)
                         h = int.from_bytes(f.read(2), "big")
                         w = int.from_bytes(f.read(2), "big")
                         return w, h
@@ -371,23 +388,38 @@ def _image_dimensions(p: Path) -> tuple[int | None, int | None]:
 def _assert_inputs(inputs: dict) -> None:
     """Fail loud on any missing or unverifiable load-bearing input.
 
-    Raises PrevalAbort with a named cause. No silent fallback paths.
+    Task 156 causes (load-bearing inputs):
+      subject-cover-hero-*, brand-unresolved,
+      agent-listings-empty, market-summary-too-thin.
+
+    Task 157 causes (provenance — agent didn't invent the input):
+      cover-hero-not-subject, agent-listings-invented, brand-invented.
+      (`market-summary-invented` retired: market_summary is agent-composed
+      from the fan-out, not operator-supplied; only the paragraphs>=2
+      sanity check remains, surfaced as `market-summary-too-thin`.)
+
+    Task 163 cause (EPC certificate paste-in completes 157's mandate):
+      epc-certificate-not-supplied — any of total_floor_area_m2,
+      current_energy_rating, lodgement_date is null/missing.
     """
     subject = inputs.get("subject") or {}
+    address = inputs.get("address") or ""
+    overrides = inputs.get("agent_overrides") or {}
 
-    # subject.sqft / sqft_m2 — required, non-null integers.
-    if not subject.get("sqft"):
-        raise PrevalAbort(
-            "subject-sqft-missing",
-            "subject.sqft is null — run epc-key-register and re-derive, or paste subject.sqft as an operator override before invocation.",
-        )
-    if not subject.get("sqft_m2"):
+    # --- 163: EPC certificate fields are operator paste-in ---
+    missing_epc = [
+        f for f in ("total_floor_area_m2", "current_energy_rating", "lodgement_date")
+        if not subject.get(f)
+    ]
+    if missing_epc:
         raise PrevalAbort(
-            "subject-sqft-m2-missing",
-            "subject.sqft_m2 is null — the EPC m² figure must be supplied alongside sqft.",
+            "epc-certificate-not-supplied",
+            f"subject is missing EPC certificate field(s) {missing_epc}. "
+            "Paste total_floor_area_m2, current_energy_rating, and lodgement_date "
+            "from the EPC certificate into subject before re-invoking. "
+            "No mid-run prompt — the operator supplies the certificate before invocation.",
         )
 
-    # subject.cover_hero — required, exists, ≥ 1200×800, not symlinked into another property's folder.
     hero = subject.get("cover_hero")
     if not hero:
         raise PrevalAbort(
@@ -397,7 +429,6 @@ def _assert_inputs(inputs: dict) -> None:
     if not hero.startswith(("http://", "https://", "data:")):
         _assert_path_image(hero)
 
-    # brand — must be the resolved DESIGN.md object, not a stub.
     brand = inputs.get("brand") or {}
     required_brand = ("name", "tagline", "primary", "primary_dark", "accent", "paper", "paper_banded", "rule")
     missing_brand = [k for k in required_brand if not brand.get(k)]
@@ -407,21 +438,65 @@ def _assert_inputs(inputs: dict) -> None:
             f"brand is missing required token(s) {missing_brand} — resolve from the agent's on-disk DESIGN.md before invocation.",
         )
 
-    # agent_listings — non-empty.
     if not inputs.get("agent_listings"):
         raise PrevalAbort(
             "agent-listings-empty",
             "agent_listings is empty — paste at least one recent listing for the closing page.",
         )
 
-    # market_summary.paragraphs — at least 2.
-    paras = (inputs.get("market_summary") or {}).get("paragraphs") or []
+    ms = inputs.get("market_summary") or {}
+    paras = ms.get("paragraphs") or []
     if len(paras) < 2:
         raise PrevalAbort(
             "market-summary-too-thin",
             f"market_summary.paragraphs has {len(paras)} entries — minimum 2.",
         )
 
+    # --- 157: provenance gates ---
+    if hero and not hero.startswith(("http://", "https://", "data:")):
+        hero_lc = hero.lower()
+        match = re.search(r"/properties?/([^/]+)/", hero_lc)
+        if match:
+            slug = match.group(1)
+            street = _street_token(address)
+            if street and street not in slug:
+                raise PrevalAbort(
+                    "cover-hero-not-subject",
+                    f"subject.cover_hero ({hero}) sits in a property folder whose "
+                    f"slug ({slug}) does not contain the subject street token "
+                    f"({street}). Prompt the operator for the subject's own photo.",
+                )
+
+    if not overrides.get("listings_status_curated"):
+        for listing in inputs.get("agent_listings") or []:
+            origin = (listing or {}).get("origin")
+            if not origin or origin == "operator":
+                continue
+            src = Path(str(origin)).expanduser()
+            if not src.exists():
+                continue
+            try:
+                source = json.loads(src.read_text())
+            except (OSError, json.JSONDecodeError):
+                continue
+            if source.get("status") in (None, "") and listing.get("status"):
+                raise PrevalAbort(
+                    "agent-listings-invented",
+                    f"agent_listings entry {listing.get('slug')} has status "
+                    f"'{listing['status']}' but source {src} carries status:null. "
+                    "Prompt the operator to confirm each status, then set "
+                    "agent_overrides.listings_status_curated: true.",
+                )
+
+    if brand.get("name") and not overrides.get("brand_selected_by_operator"):
+        raise PrevalAbort(
+            "brand-invented",
+            f"brand.name ('{brand['name']}') was set without "
+            "agent_overrides.brand_selected_by_operator: true. Ask the operator "
+            "which estate agent is pitching for this instruction; the presence "
+            "of a DESIGN.md on disk does not authorise selection.",
+        )
+
 
 # ---------------- render ----------------
 
@@ -452,12 +527,13 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
 
     psf = d.get("sales_per_month")
     if psf is None:
-        psf = max(1, round(d["for_sale"] / 7))  # crude fallback only when not provided
+        psf = max(1, round(d["for_sale"] / 7))
 
     slots = {
-        # branding
+        "variant_css":        _variant_css(inputs),
         "brand_name":         brand["name"],
         "brand_tagline":      brand["tagline"],
+        "prepared_by":        brand.get("agent_name") or brand["name"],
         "brand_primary":      brand["primary"],
         "brand_primary_dark": brand["primary_dark"],
         "brand_accent":       brand["accent"],
@@ -467,14 +543,12 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
         "wordmark_light":     _wordmark(brand, "light", out_dir),
         "wordmark_dark":      _wordmark(brand, "dark",  out_dir),
 
-        # cover + header
         "subject_hero_path":  _hero_asset(subject, out_dir),
         "address":            inputs["address"],
         "address_short":      _short_address(inputs["address"]),
         "postcode":           inputs["postcode"],
         "generated":          inputs["generated"],
 
-        # page 2 — subject valuation
         "kpi_subject_sqft":     subject_sqft,
         "kpi_subject_sqft_sub": subject_sqft_sub,
         "kpi_subject_beds":     str(subject.get("beds") or "—"),
@@ -482,10 +556,9 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
         "kpi_subject_epc_sub":  subject_epc_sub,
         "kpi_subject_type":     subject.get("type") or "—",
         "kpi_subject_tenure":   subject.get("tenure") or "Tenure unknown",
-        "valuation_block":      _valuation_block(subject, v),
+        "notable_features":     _notable_features_block(subject),
         "subject_narrative":    subject.get("narrative") or "",
 
-        # page 3 — market context
         "summary_headline":     ms["headline"],
         "summary_paragraphs":   _summary_paragraphs(ms["paragraphs"]),
         "kpi_avg_asking":       _money(v["avg_asking"]),
@@ -497,24 +570,27 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
         "price_growth_note":    ms["price_growth_note"],
         "demand_note":          ms["demand_note"],
         "spark_svg":            _spark_svg(d.get("growth_series", []), d.get("growth_psf_series", [])),
+        "type_dist_rows":       _type_dist_rows(d.get("type_dist", [])),
+        "rental_rating":        r["demand_rating"],
+        "rental_for_rent":      str(r["for_rent"]),
+        "rental_dom":           str(r["dom"]),
+        "rental_turnover":      f"{r['turnover_pct']}%",
 
-        # page 4 — comparables
         "sold_comps_rows":      _sold_comps_rows(v.get("sold_comps", [])),
         "asking_comps_tiles":   _asking_comps_tiles(v.get("asking_comps", [])),
 
-        # page 5 — agent listings + sources
         "agent_listings_cards": _agent_listings_cards(inputs["agent_listings"], out_dir),
     }
 
-    # Escape only the plain-text slots; HTML fragments pass through untouched.
     text_slots = {
         "address", "address_short", "postcode", "generated",
-        "brand_name", "brand_tagline",
+        "brand_name", "brand_tagline", "prepared_by",
         "kpi_subject_beds", "kpi_subject_epc", "kpi_subject_epc_sub",
         "kpi_subject_sqft", "kpi_subject_sqft_sub",
         "kpi_subject_type", "kpi_subject_tenure",
         "summary_headline", "demand_rating",
         "price_growth_note", "demand_note", "subject_narrative",
+        "rental_rating", "rental_for_rent", "rental_dom", "rental_turnover",
     }
     for k in text_slots:
         slots[k] = html.escape(str(slots[k]))
@@ -553,11 +629,6 @@ _PAGE_OBJ_RE = re.compile(rb"/Type\s*/Page(?![sA-Za-z])")
 
 
 def _count_pages(pdf_path: Path) -> int:
-    """pdfinfo first (handles /ObjStm-compressed page-object streams), with a
-    raw /Type /Page byte scan as fallback. The fallback is correct for current
-    Chrome --print-to-pdf output but would undercount if Chrome ever switches
-    to compressed page-object streams — hence pdfinfo first when present.
-    """
     pdfinfo = shutil.which("pdfinfo")
     if pdfinfo:
         result = subprocess.run(
@@ -580,20 +651,113 @@ def assert_page_count(pdf_path: Path, expected: int) -> int:
     return n
 
 
-def _abort(cause: str, hint: str, *, address: str, postcode: str, t0: float, out_dir: Path | None) -> None:
-    """Emit the abort log line, scrub any partial output, exit non-zero."""
+# The 12 PropertyData fan-out tools the preval skill is contracted to call.
+# Each tool the MCP server runs emits a `[property-data] tool=<name> ...` line
+# (see propertydata-api.ts:92). The watchdog asserts every one of these names
+# appears in the log within the 60s budget after `[preval] start`; a missing
+# line means the fan-out silently dropped a call and the agent was about to
+# render against an incomplete payload.
+EXPECTED_PROPERTY_DATA_TOOLS = (
+    "property-data-prices",
+    "property-data-prices-per-sqf",
+    "property-data-sold-prices",
+    "property-data-sold-prices-per-sqf",
+    "property-data-growth",
+    "property-data-growth-psf",
+    "property-data-demand",
+    "property-data-demand-rent",
+    "property-data-property-types",
+    "property-data-crime",
+    "property-data-flood-risk",
+    "property-data-council-tax",
+)
+
+
+def _missing_property_data_tools(log_text: str) -> list[str]:
+    """Return EXPECTED_PROPERTY_DATA_TOOLS that have no `[property-data] tool=<name>` line in log_text."""
+    return [
+        name for name in EXPECTED_PROPERTY_DATA_TOOLS
+        if f"[property-data] tool={name} " not in log_text
+        and not log_text.endswith(f"[property-data] tool={name}")
+        and f"[property-data] tool={name}\n" not in log_text
+    ]
+
+
+def _assert_observability_logs(log_path: Path, *, deadline_s: float = 60.0,
+                               poll_s: float = 2.0, _now=time.monotonic,
+                               _sleep=time.sleep) -> None:
+    """Poll the log until every PropertyData fan-out tool emitted its line.
+
+    Aborts with cause `observability-missing tool=<name>` once deadline_s
+    elapses if any expected name is still missing. `_now` and `_sleep` are
+    injectable for tests so the 60s budget can be exercised without
+    wall-clock waits.
+    """
+    deadline = _now() + deadline_s
+    while True:
+        try:
+            text = log_path.read_text()
+        except OSError:
+            text = ""
+        missing = _missing_property_data_tools(text)
+        if not missing:
+            return
+        if _now() >= deadline:
+            raise PrevalAbort(
+                f"observability-missing tool={missing[0]}",
+                f"PropertyData tool {missing[0]} did not emit "
+                f"`[property-data] tool={missing[0]} ...` within {int(deadline_s)}s "
+                "of [preval] start. The fan-out silently dropped one or more calls; "
+                "re-invoke and confirm every PropertyData tool returned before render. "
+                f"Other missing tool(s): {missing[1:] or 'none'}.",
+            )
+        _sleep(poll_s)
+
+
+def _pick_log_path(out_dir: Path) -> Path:
+    """~/.maxy/logs/server.log if writable, else <out_dir>/preval.log.
+
+    Aborts with `log-destination-unavailable` if neither is writable —
+    silent runs are a contract violation.
+    """
+    primary = Path("~/.maxy/logs/server.log").expanduser()
+    for candidate in (primary, out_dir / "preval.log"):
+        try:
+            candidate.parent.mkdir(parents=True, exist_ok=True)
+            with candidate.open("a"):
+                pass
+            return candidate
+        except OSError:
+            continue
+    raise PrevalAbort(
+        "log-destination-unavailable",
+        "Neither ~/.maxy/logs/server.log nor <out_dir>/preval.log is writable. "
+        "Fix filesystem permissions before re-running.",
+    )
+
+
+def _log_line(log_path: Path | None, line: str) -> None:
+    if log_path is not None:
+        try:
+            with log_path.open("a") as f:
+                f.write(line + "\n")
+        except OSError:
+            pass
+    print(line, file=sys.stderr)
+
+
+def _abort(cause: str, hint: str, *, address: str, postcode: str, t0: float,
+           out_dir: Path | None, log_path: Path | None) -> None:
     ms = int((time.monotonic() - t0) * 1000)
-    print(
+    _log_line(
+        log_path,
         f'[preval] aborted reason={cause} address="{address}" postcode={postcode} ms={ms}',
-        file=sys.stderr,
     )
     print(hint, file=sys.stderr)
     if out_dir is not None:
-        for name in ("index.html",):
-            p = out_dir / name
-            if p.exists():
-                p.unlink()
-        # Any PDF whose stem matches filename_stem would be a partial — caller passes the stem.
+        p = out_dir / "index.html"
+        if p.exists():
+            p.unlink()
     sys.exit(2)
 
 
@@ -604,24 +768,44 @@ def main():
         sys.exit(2)
     inputs = json.loads(Path(sys.argv[1]).read_text())
     out_dir = Path(inputs["out_dir"]).expanduser()
+    out_dir.mkdir(parents=True, exist_ok=True)
     base = inputs["filename_stem"]
     address = inputs.get("address", "")
     postcode = inputs.get("postcode", "")
+
+    try:
+        log_path = _pick_log_path(out_dir)
+    except PrevalAbort as e:
+        _abort(e.cause, e.hint, address=address, postcode=postcode, t0=t0,
+               out_dir=out_dir, log_path=None)
+
+    _log_line(log_path, f'[preval] start address="{address}" postcode={postcode}')
+
+    try:
+        _assert_observability_logs(log_path)
+    except PrevalAbort as e:
+        _abort(e.cause, e.hint, address=address, postcode=postcode, t0=t0,
+               out_dir=out_dir, log_path=log_path)
+
     try:
         render(inputs, out_dir)
         pdf = render_pdf(out_dir, f"{base}.pdf")
-        pages = assert_page_count(pdf, 5)
+        pages = assert_page_count(pdf, 7)
     except PrevalAbort as e:
-        # Scrub partial PDF too, if rendered before page-count failure.
         pdf_path = out_dir / f"{base}.pdf"
         if pdf_path.exists():
             pdf_path.unlink()
-        _abort(e.cause, e.hint, address=address, postcode=postcode, t0=t0, out_dir=out_dir)
+        _abort(e.cause, e.hint, address=address, postcode=postcode, t0=t0,
+               out_dir=out_dir, log_path=log_path)
     except RuntimeError as e:
         pdf_path = out_dir / f"{base}.pdf"
         if pdf_path.exists():
             pdf_path.unlink()
-        _abort("render-error", str(e), address=address, postcode=postcode, t0=t0, out_dir=out_dir)
+        _abort("render-error", str(e), address=address, postcode=postcode, t0=t0,
+               out_dir=out_dir, log_path=log_path)
+
+    ms = int((time.monotonic() - t0) * 1000)
+    _log_line(log_path, f"[preval] done pdf={pdf} pages={pages} ms={ms}")
     print(f"HTML  → {out_dir/'index.html'}")
     print(f"PDF   → {pdf} ({pages} pages)")