chore(sync): mirror backend .py + Dockerfile to Space (hf-sync-backend)

Automated backend sync from szl-holdings/a11oy main via hf-sync-backend.
Updated (differed from the Space): a11oy_frontier_page.py
Deleted (gone from the repo + Dockerfile COPY set): (none)

Keeps the Space-built backend (serve.py + the Dockerfile-COPY'd .py
modules) identical to GitHub main so the Space never rebuilds from a
stale backend, new endpoints don't 404 there, and orphaned modules
removed from the repo don't linger in the Space tree.

a11oy_frontier_page.py

@@ -44,10 +44,158 @@ sovereign=false on this path. Doctrine v11 LOCKED.
 """
 from __future__ import annotations
 
+import pathlib
+import re
+
 from fastapi import FastAPI
 from fastapi.responses import HTMLResponse, JSONResponse
 
 DOCTRINE = {"version": "v11", "lambda": "Conjecture 1", "sovereign": False}
+
+# --------------------------------------------------------------------------- #
+# Frontier 3D-surface manifest (GET /api/<ns>/v1/frontier/surfaces)
+#
+# A machine-verifiable roll-up of every 3D holographic frontier surface. The
+# SINGLE SOURCE OF TRUTH for the surface LIST is the `SURFACES` array declared in
+# static/3d/holographic.html (the same array the holographic viewer loads); the
+# SINGLE SOURCE OF TRUTH for each surface's honesty LABEL is the surface's own JS
+# source — the label is PARSED from the file, never hardcoded a second time here.
+#
+# Doctrine v11 honesty (non-negotiable):
+#   * A missing asset at runtime -> UNAVAILABLE with a reason, NEVER a fabricated
+#     present/green tile.
+#   * The label is read from the surface source and reported VERBATIM — never
+#     upgraded. Where a surface declares no doctrine token at all, it is honestly
+#     UNAVAILABLE (undeclared), not padded to a nicer label.
+#   * This is a pure READ (parse files on disk). It signs nothing and appends to
+#     no provenance chain — receipts belong on writes, never on GETs.
+# --------------------------------------------------------------------------- #
+
+# Repo root — this module lives flat at the repo root next to static/3d/.
+_REPO_ROOT = pathlib.Path(__file__).resolve().parent
+_HOLOGRAPHIC_REL = "static/3d/holographic.html"
+
+# Recognized doctrine honesty vocabulary (weakest→strongest claim ordering is not
+# needed here — this is just the accepted set). UNAVAILABLE is reserved for a
+# missing asset or an undeclared label; it is never a "normal" surface label.
+_VALID_LABELS = ("MEASURED", "LIVE", "SAMPLE", "MODELED", "STRUCTURAL-ONLY", "ROADMAP")
+UNAVAILABLE = "UNAVAILABLE"
+
+# `{ id: "grpo", title: "GRPO Reward Dynamics", mod: "/static/3d/surfaces/grpo.js" }`
+_SURFACE_ENTRY_RE = re.compile(
+    r'\{\s*id:\s*"([^"]+)"\s*,\s*title:\s*"([^"]+)"\s*,\s*mod:\s*"([^"]+)"\s*\}')
+# Runtime-default label the surface renders absent live data: `S.label = (j.label || "MODELED")`.
+_LABEL_DEFAULT_RE = re.compile(r'\b\w+\.label\s*=\s*\(\s*[\w.]+\s*\|\|\s*"([A-Z][A-Z-]+)"')
+# Declared honesty chip / billboard token (surfaces without a runtime-default label).
+_LABEL_CHIP_RE = re.compile(r'\.chip\(\s*"([A-Z][A-Z-]+)"')
+_LABEL_BILL_RE = re.compile(r'billboard\([^,]*,\s*"([A-Z][A-Z-]+)"')
+# Any quoted UPPER token (last-resort scan, e.g. the hub surface's ROADMAP literal).
+_TOKEN_RE = re.compile(r'"([A-Z][A-Z-]+)"')
+
+
+def _derive_label(src: str) -> tuple[str | None, str]:
+    """Derive a surface's honesty label from its JS source. Returns (label, source).
+
+    Ordered, deterministic, and never over-claims: the headline label is the
+    surface's own declared token, read verbatim. A surface can never be reported
+    stronger than it declares (none of these first-match rules can yield MEASURED
+    for a surface that only models/samples)."""
+    m = _LABEL_DEFAULT_RE.search(src)
+    if m and m.group(1) in _VALID_LABELS:
+        return m.group(1), "js-runtime-default"
+    for rx, source in ((_LABEL_CHIP_RE, "js-honesty-chip"),
+                       (_LABEL_BILL_RE, "js-honesty-billboard"),
+                       (_TOKEN_RE, "js-doctrine-literal")):
+        for mm in rx.finditer(src):
+            if mm.group(1) in _VALID_LABELS:
+                return mm.group(1), source
+    return None, "none"
+
+
+def _declared_labels(src: str) -> list[str]:
+    """Every recognized doctrine token the surface source declares (audit trail)."""
+    return sorted({t for t in _TOKEN_RE.findall(src) if t in _VALID_LABELS})
+
+
+def _build_surface_entry(sid: str, title: str, mod: str) -> dict:
+    """Build one manifest entry for a surface. Missing asset -> honest UNAVAILABLE."""
+    asset_rel = mod.lstrip("/")
+    asset_path = _REPO_ROOT / asset_rel
+    entry: dict = {"id": sid, "title": title, "asset": mod, "label_verbatim": True}
+    if not asset_path.is_file():
+        entry.update({
+            "label": UNAVAILABLE,
+            "label_source": "missing-asset",
+            "declared_labels": [],
+            "present": False,
+            "reason": f"surface asset not found at {mod}",
+        })
+        return entry
+    src = asset_path.read_text(encoding="utf-8", errors="replace")
+    label, label_source = _derive_label(src)
+    entry["present"] = True
+    entry["declared_labels"] = _declared_labels(src)
+    if label is None:
+        entry.update({
+            "label": UNAVAILABLE,
+            "label_source": "no-declared-label",
+            "reason": "surface source declares no recognized doctrine honesty token",
+        })
+    else:
+        entry.update({"label": label, "label_source": label_source})
+    return entry
+
+
+def build_surfaces_manifest(ns: str = "a11oy") -> dict:
+    """Compose the machine-verifiable 3D-surface manifest from the live registry.
+
+    The surface list is parsed from static/3d/holographic.html's SURFACES array;
+    each label is parsed from the surface's own JS. Never fabricates a surface,
+    a count, or a label. If holographic.html itself is missing the manifest still
+    returns 200 with an honest empty list + error."""
+    endpoint = f"/api/{ns}/v1/frontier/surfaces"
+    holo = _REPO_ROOT / _HOLOGRAPHIC_REL
+    base = {
+        "endpoint": endpoint,
+        "source": _HOLOGRAPHIC_REL,
+        "hub": "frontier",
+        "doctrine": {
+            "version": "v11",
+            "lambda": "Conjecture 1",
+            "note": ("surface list parsed from holographic.html SURFACES; each label "
+                     "parsed from the surface JS source and reported verbatim, never "
+                     "upgraded; missing asset -> UNAVAILABLE, never fabricated"),
+        },
+    }
+    if not holo.is_file():
+        base.update({"ok": False, "count": 0, "surfaces": [],
+                     "error": f"registry not found at {_HOLOGRAPHIC_REL}",
+                     "summary": {"count": 0, "label_counts": {}, "labels_valid": True}})
+        return base
+
+    html = holo.read_text(encoding="utf-8", errors="replace")
+    entries = _SURFACE_ENTRY_RE.findall(html)
+    surfaces = [_build_surface_entry(sid, title, mod) for sid, title, mod in entries]
+
+    label_counts: dict[str, int] = {}
+    for s in surfaces:
+        label_counts[s["label"]] = label_counts.get(s["label"], 0) + 1
+    valid_set = set(_VALID_LABELS) | {UNAVAILABLE}
+    labels_valid = all(s["label"] in valid_set for s in surfaces)
+
+    base.update({
+        "ok": True,
+        "count": len(surfaces),
+        "surfaces": surfaces,
+        "summary": {
+            "count": len(surfaces),
+            "present": sum(1 for s in surfaces if s.get("present")),
+            "unavailable": sum(1 for s in surfaces if s["label"] == UNAVAILABLE),
+            "label_counts": label_counts,
+            "labels_valid": labels_valid,
+        },
+    })
+    return base
 HONEST_BANNER = (
     "HONEST SHOWCASE — every tile carries its own label (MEASURED / MODELED / "
     "ROADMAP / SAMPLE) and a provenance pointer; no label is upgraded, nothing is faked"
@@ -55,6 +203,8 @@ HONEST_BANNER = (
 
 # The LIVE backend roll-up this surface renders (PR #472). Wired client-side.
 _MANIFEST_EP = "/api/{ns}/v1/frontier/manifest"
+# The 3D-surface manifest this page renders its surface list from (one source of truth).
+_SURFACES_EP = "/api/{ns}/v1/frontier/surfaces"
 
 # 0-CDN vendored three.js r160 — the proven, allowlisted, runtime-served hero path
 # (serve.py GET /hero/vendor3d/{fname}; identical to the /orbital page importmap).
@@ -64,6 +214,7 @@ _THREE_ADDONS = "/hero/vendor3d/"
 
 def _page_html(ns: str) -> str:
     manifest_ep = _MANIFEST_EP.format(ns=ns)
+    surfaces_ep = _SURFACES_EP.format(ns=ns)
     return f"""<!doctype html>
 <html lang="en"><head>
 <meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/>
@@ -142,6 +293,16 @@ def _page_html(ns: str) -> str:
   .badge.roadmap   {{ background:rgba(157,122,216,.16); color:var(--violet); border:1px solid rgba(157,122,216,.5); }}
   .badge.sample    {{ background:rgba(77,143,204,.16); color:var(--indigo); border:1px solid rgba(77,143,204,.45); }}
   .badge.unavailable {{ background:rgba(216,98,74,.16); color:var(--red); border:1px solid rgba(216,98,74,.5); }}
+  .badge.structural-only {{ background:rgba(138,151,163,.16); color:#9fb1bf; border:1px solid rgba(138,151,163,.5); }}
+  .badge.live {{ background:rgba(47,208,122,.16); color:var(--green); border:1px solid rgba(47,208,122,.45); }}
+  /* 3D-surface list — compact honest pills, one per surface. */
+  #surfaces-section {{ margin-top:1.6rem; }}
+  #surfaces-section h2 {{ font-size:clamp(1.1rem,2vw,1.4rem); margin:.2rem 0 0; }}
+  #surfaces-list {{ display:flex; flex-wrap:wrap; gap:.5rem; margin-top:1rem; }}
+  .surface-pill {{ display:flex; align-items:center; gap:.5rem; background:rgba(16,26,46,.84);
+    border:1px solid #21304d; border-radius:10px; padding:.4rem .6rem;
+    font-family:ui-monospace,monospace; font-size:.72rem; color:var(--ink); }}
+  .surface-pill .sid {{ color:var(--muted); }}
   /* Per-tile persistent honest banner on non-MEASURED tiles. */
   .tile-banner {{ font-family:ui-monospace,monospace; font-size:.66rem; line-height:1.4;
                   border-radius:8px; padding:.4rem .55rem; letter-spacing:.03em; }}
@@ -187,6 +348,19 @@ def _page_html(ns: str) -> str:
       <span class="lg sample">SAMPLE — illustrative only</span>
     </div>
     <div id="rollup"></div>
+
+    <!-- 3D holographic surfaces — count + honest labels, from the SAME manifest the
+         holographic showcase is built from (one source of truth: /frontier/surfaces). -->
+    <div id="surfaces-section">
+      <h2 id="surfaces-h">3D holographic surfaces</h2>
+      <p class="sub" id="surfaces-sub">The holographic frontier surfaces, listed live from
+        <code>/frontier/surfaces</code> — the same machine-verifiable manifest that names each
+        surface's asset and its honest label (parsed from the surface source, never upgraded).</p>
+      <div id="surfaces-rollup"></div>
+      <div id="surfaces-list"></div>
+      <div class="status-line" id="surfaces-status">fetching /frontier/surfaces…</div>
+    </div>
+
     <div id="grid"></div>
     <div class="status-line" id="status">fetching /frontier/manifest…</div>
     <div class="status-line"><a class="back" href="/">← back to console</a> &nbsp;·&nbsp;
@@ -378,6 +552,52 @@ function fail(msg) {{
     fail('manifest unavailable: ' + e + ' (nothing fabricated — raw data at ' + MANIFEST_EP + ')');
   }}
 }})();
+
+// ---- 3D-surface list: rendered FROM /frontier/surfaces (one source of truth) ---
+const SURFACES_EP = {surfaces_ep!r};
+const SURF_CLASS = {{
+  MEASURED:'measured', LIVE:'live', SAMPLE:'sample', MODELED:'modeled',
+  'STRUCTURAL-ONLY':'structural-only', ROADMAP:'roadmap', UNAVAILABLE:'unavailable',
+}};
+function surfCls(label) {{ return SURF_CLASS[label] || 'unavailable'; }}
+
+(async function loadSurfaces() {{
+  const statusEl = document.getElementById('surfaces-status');
+  try {{
+    const r = await fetch(SURFACES_EP, {{ headers:{{Accept:'application/json'}} }});
+    const m = await r.json();
+    const surfaces = m.surfaces || [];
+    const s = m.summary || {{}};
+    const lc = s.label_counts || {{}};
+
+    // honest roll-up: true count + per-label counts, straight from the manifest
+    const chips = [`<span class="chip"><b>${{esc(m.count ?? surfaces.length)}}</b> surfaces</span>`];
+    for (const [label, n] of Object.entries(lc)) {{
+      chips.push(`<span class="chip">${{esc(label)}} <b>${{esc(n)}}</b></span>`);
+    }}
+    if (s.unavailable) chips.push(`<span class="chip">unavailable <b>${{esc(s.unavailable)}}</b></span>`);
+    chips.push(`<span class="chip">labels valid: <b>${{esc(String(s.labels_valid))}}</b></span>`);
+    document.getElementById('surfaces-rollup').innerHTML = chips.join('');
+
+    // one honest pill per surface: id · title · label badge
+    document.getElementById('surfaces-list').innerHTML = surfaces.map(su => {{
+      const label = su.label || 'UNAVAILABLE';
+      return `<span class="surface-pill" title="${{esc(su.asset || '')}}">`
+        + `<span class="sid">${{esc(su.id)}}</span>`
+        + `<span>${{esc(su.title || '')}}</span>`
+        + `<span class="badge ${{surfCls(label)}}">${{esc(label)}}</span></span>`;
+    }}).join('');
+
+    statusEl.className = 'status-line';
+    statusEl.textContent = (m.ok === false)
+      ? ('surface registry unavailable: ' + esc(m.error || 'unknown') + ' (nothing fabricated)')
+      : ('live · ' + esc(m.count ?? surfaces.length) + ' surfaces from ' + esc(SURFACES_EP)
+         + ' · labels_valid=' + esc(String(s.labels_valid)));
+  }} catch (e) {{
+    statusEl.className = 'status-line err';
+    statusEl.textContent = 'surfaces unavailable: ' + e + ' (nothing fabricated — raw data at ' + SURFACES_EP + ')';
+  }}
+}})();
 </script>
 </body></html>"""
 
@@ -390,6 +610,14 @@ def register(app: FastAPI, ns: str = "a11oy") -> str:
     async def frontier_page() -> HTMLResponse:  # noqa: ANN202
         return HTMLResponse(_page_html(ns))
 
+    @app.get(f"/api/{ns}/v1/frontier/surfaces")
+    async def frontier_surfaces() -> JSONResponse:  # noqa: ANN202
+        """Machine-verifiable manifest of every 3D frontier surface.
+
+        id + title + honesty label (parsed from the surface source, verbatim) +
+        asset path. Missing asset -> UNAVAILABLE with reason. Pure read; no sign."""
+        return JSONResponse(build_surfaces_manifest(ns))
+
     @app.get(f"/api/{ns}/v1/frontier/page-manifest", include_in_schema=False)
     async def frontier_page_manifest() -> JSONResponse:  # noqa: ANN202
         return JSONResponse({
@@ -398,8 +626,9 @@ def register(app: FastAPI, ns: str = "a11oy") -> str:
             "kind": "unified-ecosystem-showcase",
             "banner": HONEST_BANNER,
             "doctrine": DOCTRINE,
-            "renders_endpoints": [_MANIFEST_EP.format(ns=ns)],
-            "links": {"orbital_page": "/orbital", "manifest": _MANIFEST_EP.format(ns=ns)},
+            "renders_endpoints": [_MANIFEST_EP.format(ns=ns), _SURFACES_EP.format(ns=ns)],
+            "links": {"orbital_page": "/orbital", "manifest": _MANIFEST_EP.format(ns=ns),
+                      "surfaces": _SURFACES_EP.format(ns=ns)},
             "vendored_3d": {"three": _THREE_MAIN, "addons": _THREE_ADDONS,
                             "revision": "r160", "runtime_cdn": 0},
             "note": ("Unified frontier showcase — renders the live /frontier/manifest "
@@ -408,7 +637,9 @@ def register(app: FastAPI, ns: str = "a11oy") -> str:
                      "no label is upgraded, nothing is fabricated."),
         })
 
-    return "frontier-page mounted: GET /frontier + page-manifest (renders /frontier/manifest roll-up, 0 CDN)"
+    return ("frontier-page mounted: GET /frontier + page-manifest + "
+            f"/api/{ns}/v1/frontier/surfaces (3D-surface manifest, parsed from "
+            "holographic.html; renders /frontier/manifest roll-up + surface list, 0 CDN)")
 
 
 def _selftest() -> None:
@@ -429,8 +660,26 @@ def _selftest() -> None:
     # 6) links to the orbital MODELED tier are present
     assert 'href="/orbital"' in html, "orbital tier link missing"
     assert "Conjecture 1" in html, "Λ label missing"
+    # 7) the 3D-surface manifest is wired into the page (one source of truth)
+    assert "/api/a11oy/v1/frontier/surfaces" in html, "surfaces endpoint not wired"
+    assert 'id="surfaces-list"' in html and 'id="surfaces-rollup"' in html, \
+        "surfaces section markers missing"
+    assert "loadSurfaces" in html, "surfaces client loader missing"
+
+    # 8) the manifest builder parses the live registry honestly
+    man = build_surfaces_manifest("a11oy")
+    assert man["ok"] is True, f"surfaces manifest not ok: {man.get('error')}"
+    assert man["count"] == len(man["surfaces"]) and man["count"] > 0, "surface count mismatch"
+    valid = set(_VALID_LABELS) | {UNAVAILABLE}
+    assert all(su["label"] in valid for su in man["surfaces"]), "invalid honesty label found"
+    assert man["summary"]["labels_valid"] is True, "labels_valid should be True"
+    # missing asset -> honest UNAVAILABLE, never fabricated present/green
+    miss = _build_surface_entry("nope", "Nope", "/static/3d/surfaces/__does_not_exist__.js")
+    assert miss["label"] == UNAVAILABLE and miss["present"] is False and "reason" in miss, \
+        "missing asset must be UNAVAILABLE with a reason"
     print("a11oy_frontier_page: ALL OK (honest banner, manifest wired, 0 CDN, render marker, "
-          "per-tile honest banners, orbital link)")
+          "per-tile honest banners, orbital link, "
+          f"{man['count']} surfaces parsed, labels {man['summary']['label_counts']})")
 
 
 if __name__ == "__main__":