viewspec 0.3.0b2__tar.gz → 0.3.0b4__tar.gz

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/.gitignore

@@ -16,4 +16,6 @@ build/
 output/
 viewspec_output/
 .venv/
+.env
+node_modules/
 demos/server.*.log

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: viewspec
-Version: 0.3.0b2
+Version: 0.3.0b4
 Summary: Agent-native UI compiler. Agents describe intent; ViewSpec compiles concrete UI.
 Project-URL: Homepage, https://github.com/nxrobins/viewspec
 Project-URL: Repository, https://github.com/nxrobins/viewspec
@@ -9,7 +9,7 @@ Author: Nigel Robinson
 License-Expression: MIT
 License-File: LICENSE
 Keywords: agents,compiler,composition-ir,declarative,protobuf,semantic,ui,viewspec
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -28,10 +28,12 @@ Requires-Dist: mcp>=1.9.0; extra == 'agents'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: hypothesis<7,>=6.100; extra == 'dev'
 Requires-Dist: jsonschema>=4.18; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: remote
+Requires-Dist: cryptography<49,>=48.0.1; extra == 'remote'
 Requires-Dist: httpx>=0.27.0; extra == 'remote'
 Description-Content-Type: text/markdown
 
@@ -39,7 +41,7 @@ Description-Content-Type: text/markdown
 
 **Stop asking agents to write React, DOM, or State.**
 
-ViewSpec is an agent-native UI compiler. It acts as a universal Intermediate Representation (IR) for AI Software Engineering. Agents describe UI and state intent as `IntentBundle` or `AppBundle` JSON; ViewSpec compiles that intent into deterministic HTML and React surfaces with the free local compiler, and SwiftUI or Flutter surfaces via the hosted compiler.
+ViewSpec is an agent-native UI compiler. It acts as a universal Intermediate Representation (IR) for AI Software Engineering. Agents describe UI and state intent as `IntentBundle` or `AppBundle` JSON; ViewSpec compiles that intent into deterministic HTML and React surfaces with the free local compiler. The paid hosted API adds Level 2 derivation, DESIGN.md context, projections, rules, custom motifs, signed usage receipts, integrity-checked single-screen artifacts, and verified runnable AppBundle projects.
 
 By totally decoupling intent from implementation, ViewSpec eliminates the "visual context window" problem. Agents no longer need to see pixels to build complex, perfectly styled, and deeply interactive applications.
 
@@ -219,7 +221,20 @@ viewspec mcp
 ```
 The MCP server exposes all intent-first local tools without requiring shell commands, including `validate_intent_bundle_file`, `compile_intent_bundle_file`, `verify_host`, `prove`, `validate_app_file`, `diff_app_files`, `compile_app`, and `prove_app`.
 
-For bounded React Tailwind runtime proof, run `viewspec prove --target react-tailwind-tsx --install --out .viewspec-proof --json` or `viewspec verify-host react-tailwind-output/ --target react-tailwind-tsx --install --json`. The host proof checks grid column/span counts, profiled aesthetic marker/layout assertions, and action payload behavior; JSON reports include `assertion_requirements` with `dom_count`, `style_assertion_count`, `aesthetic_layout_assertion_count`, `aesthetic_profile_assertion_count`, and `grid_span_assertion_count`.
+For rendered conformance, compile React/Tailwind TSX and run:
+
+```bash
+viewspec verify react-tailwind-output/ --install --json
+```
+
+The verifier renders canonical mobile, tablet, and desktop viewports and writes integrity-addressed
+screenshots, DOM snapshots, accessibility evidence, `result.json`, and a deterministic `repair.json`.
+Exit codes distinguish conformant (`0`), nonconformant (`1`), and indeterminate (`2`) results.
+`viewspec verify-host` remains the lower-level bounded host assertion proof for
+grid column/span counts, profiled aesthetic markers/layout, and action payload behavior.
+Its JSON `assertion_requirements` records `dom_count`, `style_assertion_count`, and
+`aesthetic_layout_assertion_count` expectations from the checked manifest.
+`viewspec prove` combines compilation checks with that proof.
 
 ## viewspec.dev
 
@@ -300,6 +315,12 @@ ast = compile_auto(builder.build_bundle())
 
 The hosted fallback requires the `remote` extra: `python -m pip install "viewspec[remote]"` (adds `httpx`). Without it, `compile_auto` runs locally and raises `ImportError` only if a hosted fallback is actually needed.
 
+Paid agents can submit a complete AppBundle to `submit_verification_remote(...)` for compiled
+route/state proof plus per-screen browser evidence and a signed receipt. For bounded autonomous
+repair, `compile_until_conformant_remote(...)` repeats that paid compile-and-verify step while a
+caller-owned repair callback edits the semantic AppBundle. ViewSpec enforces lineage, plan
+stability, attempt limits, and no-progress termination.
+
 ### Theming with DESIGN.md
 The local SDK uses a strict YAML-front-matter `DESIGN.md` for offline HTML and IntentBundle compilation. The API requires exact sRGB hex values (e.g., `#FFFFFF`), enforcing strict design token discipline.
 

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/README.md

@@ -2,7 +2,7 @@
 
 **Stop asking agents to write React, DOM, or State.**
 
-ViewSpec is an agent-native UI compiler. It acts as a universal Intermediate Representation (IR) for AI Software Engineering. Agents describe UI and state intent as `IntentBundle` or `AppBundle` JSON; ViewSpec compiles that intent into deterministic HTML and React surfaces with the free local compiler, and SwiftUI or Flutter surfaces via the hosted compiler.
+ViewSpec is an agent-native UI compiler. It acts as a universal Intermediate Representation (IR) for AI Software Engineering. Agents describe UI and state intent as `IntentBundle` or `AppBundle` JSON; ViewSpec compiles that intent into deterministic HTML and React surfaces with the free local compiler. The paid hosted API adds Level 2 derivation, DESIGN.md context, projections, rules, custom motifs, signed usage receipts, integrity-checked single-screen artifacts, and verified runnable AppBundle projects.
 
 By totally decoupling intent from implementation, ViewSpec eliminates the "visual context window" problem. Agents no longer need to see pixels to build complex, perfectly styled, and deeply interactive applications.
 
@@ -182,7 +182,20 @@ viewspec mcp
 ```
 The MCP server exposes all intent-first local tools without requiring shell commands, including `validate_intent_bundle_file`, `compile_intent_bundle_file`, `verify_host`, `prove`, `validate_app_file`, `diff_app_files`, `compile_app`, and `prove_app`.
 
-For bounded React Tailwind runtime proof, run `viewspec prove --target react-tailwind-tsx --install --out .viewspec-proof --json` or `viewspec verify-host react-tailwind-output/ --target react-tailwind-tsx --install --json`. The host proof checks grid column/span counts, profiled aesthetic marker/layout assertions, and action payload behavior; JSON reports include `assertion_requirements` with `dom_count`, `style_assertion_count`, `aesthetic_layout_assertion_count`, `aesthetic_profile_assertion_count`, and `grid_span_assertion_count`.
+For rendered conformance, compile React/Tailwind TSX and run:
+
+```bash
+viewspec verify react-tailwind-output/ --install --json
+```
+
+The verifier renders canonical mobile, tablet, and desktop viewports and writes integrity-addressed
+screenshots, DOM snapshots, accessibility evidence, `result.json`, and a deterministic `repair.json`.
+Exit codes distinguish conformant (`0`), nonconformant (`1`), and indeterminate (`2`) results.
+`viewspec verify-host` remains the lower-level bounded host assertion proof for
+grid column/span counts, profiled aesthetic markers/layout, and action payload behavior.
+Its JSON `assertion_requirements` records `dom_count`, `style_assertion_count`, and
+`aesthetic_layout_assertion_count` expectations from the checked manifest.
+`viewspec prove` combines compilation checks with that proof.
 
 ## viewspec.dev
 
@@ -263,6 +276,12 @@ ast = compile_auto(builder.build_bundle())
 
 The hosted fallback requires the `remote` extra: `python -m pip install "viewspec[remote]"` (adds `httpx`). Without it, `compile_auto` runs locally and raises `ImportError` only if a hosted fallback is actually needed.
 
+Paid agents can submit a complete AppBundle to `submit_verification_remote(...)` for compiled
+route/state proof plus per-screen browser evidence and a signed receipt. For bounded autonomous
+repair, `compile_until_conformant_remote(...)` repeats that paid compile-and-verify step while a
+caller-owned repair callback edits the semantic AppBundle. ViewSpec enforces lineage, plan
+stability, attempt limits, and no-progress termination.
+
 ### Theming with DESIGN.md
 The local SDK uses a strict YAML-front-matter `DESIGN.md` for offline HTML and IntentBundle compilation. The API requires exact sRGB hex values (e.g., `#FFFFFF`), enforcing strict design token discipline.
 

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "viewspec"
-version = "0.3.0b2"
+version = "0.3.0b4"
 description = "Agent-native UI compiler. Agents describe intent; ViewSpec compiles concrete UI."
 readme = "README.md"
 license = "MIT"
@@ -14,7 +14,7 @@ authors = [
 ]
 keywords = ["ui", "compiler", "semantic", "viewspec", "composition-ir", "protobuf", "declarative", "agents"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
@@ -38,12 +38,14 @@ viewspec = "viewspec.cli:main"
 dev = [
     "build>=1.2",
     "pytest>=8.0",
+    "hypothesis>=6.100,<7",
     "ruff>=0.4",
     "httpx>=0.27.0",
     "jsonschema>=4.18",
 ]
 remote = [
     "httpx>=0.27.0",
+    "cryptography>=48.0.1,<49",
 ]
 agents = [
     "mcp>=1.9.0",

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/src/viewspec/__init__.py

@@ -46,6 +46,64 @@ from viewspec.compiler import (
     CompilerInputError,
     UnsupportedMotifError,
 )
+from viewspec.conformance import (
+    CONFORMANCE_CORPUS_SCHEMA_VERSION,
+    ConformanceCase,
+    ConformanceCorpus,
+    load_conformance_corpus,
+    run_conformance_corpus,
+)
+from viewspec.convergence import (
+    CONVERGENCE_SCHEMA_VERSION,
+    ConvergenceAttempt,
+    ConvergenceRun,
+    MAX_CONVERGENCE_ATTEMPTS,
+    run_until_conformant,
+)
+from viewspec.hosted_artifacts import (
+    ARTIFACT_SCHEMA_VERSION,
+    ARTIFACT_TARGETS,
+    ArtifactContractError,
+    ArtifactCompilerIdentity,
+    ArtifactFile,
+    ArtifactProvenance,
+    ArtifactResponse,
+    ArtifactUsage,
+    compile_artifact_remote,
+)
+from viewspec.hosted_receipts import RECEIPT_ALGORITHM, ReceiptPublicKey, verify_usage_receipt
+from viewspec.hosted_receipts import verify_signed_receipt
+from viewspec.hosted_app_bundles import (
+    APP_BUILD_MANIFEST,
+    APP_BUILD_SCHEMA_VERSION,
+    APP_BUILD_TARGET,
+    AppBuildFile,
+    AppBuildProvenance,
+    AppBuildUsage,
+    AppBundleBuildContractError,
+    AppBundleBuildResponse,
+    compile_app_remote,
+)
+from viewspec.hosted_verification import (
+    HOSTED_VERIFICATION_SCHEMA_VERSION,
+    HOSTED_VERIFICATION_TARGET,
+    HostedEvidenceArtifact,
+    HostedVerificationContractError,
+    HostedVerificationError,
+    HostedVerificationJob,
+    HostedVerificationUsage,
+    build_verification_job_id,
+    compile_until_conformant_remote,
+    get_verification_remote,
+    submit_verification_remote,
+    verification_request_payload,
+    wait_verification_remote,
+)
+from viewspec.intent_contract import (
+    IntentBundleContractError,
+    normalize_intent_bundle_payload,
+    validate_intent_bundle_schema_version,
+)
 from viewspec.motif_plugins import (
     MOTIF_PLUGIN_ABI_VERSION,
     MotifCompileContext,
@@ -171,6 +229,24 @@ from viewspec.host_verify import (
     verify_host_intent_file,
     verify_host_tool,
 )
+from viewspec.local_verify import BrowserEvidence, BrowserPlanOutcome, verify_local_artifact
+from viewspec.repair import (
+    REPAIR_SCHEMA_VERSION,
+    RepairDirective,
+    SourceNodePath,
+    VerificationRepairPlan,
+)
+from viewspec.verification import (
+    DEFAULT_VIEWPORTS,
+    EvidenceFile,
+    RetryLineage,
+    VERIFICATION_SCHEMA_VERSION,
+    VerificationDiagnostic,
+    VerificationPlan,
+    VerificationResult,
+    VerificationViewport,
+    build_verification_id,
+)
 from viewspec.prove import prove, prove_tool
 
 __all__ = [
@@ -184,6 +260,12 @@ __all__ = [
     "CompileResponseMeta",
     "CompilerDiagnostic",
     "CompilerResult",
+    "CONFORMANCE_CORPUS_SCHEMA_VERSION",
+    "CONVERGENCE_SCHEMA_VERSION",
+    "ConformanceCase",
+    "ConformanceCorpus",
+    "ConvergenceAttempt",
+    "ConvergenceRun",
     "CompositionIR",
     "DesignFinding",
     "DesignMetadata",
@@ -214,6 +296,44 @@ __all__ = [
     "CompilerAPIError",
     "CompilerInputError",
     "UnsupportedMotifError",
+    "ARTIFACT_SCHEMA_VERSION",
+    "ARTIFACT_TARGETS",
+    "ArtifactContractError",
+    "ArtifactCompilerIdentity",
+    "ArtifactFile",
+    "ArtifactProvenance",
+    "ArtifactResponse",
+    "ArtifactUsage",
+    "compile_artifact_remote",
+    "RECEIPT_ALGORITHM",
+    "ReceiptPublicKey",
+    "verify_usage_receipt",
+    "verify_signed_receipt",
+    "APP_BUILD_MANIFEST",
+    "APP_BUILD_SCHEMA_VERSION",
+    "APP_BUILD_TARGET",
+    "AppBuildFile",
+    "AppBuildProvenance",
+    "AppBuildUsage",
+    "AppBundleBuildContractError",
+    "AppBundleBuildResponse",
+    "compile_app_remote",
+    "HOSTED_VERIFICATION_SCHEMA_VERSION",
+    "HOSTED_VERIFICATION_TARGET",
+    "HostedEvidenceArtifact",
+    "HostedVerificationContractError",
+    "HostedVerificationError",
+    "HostedVerificationJob",
+    "HostedVerificationUsage",
+    "build_verification_job_id",
+    "compile_until_conformant_remote",
+    "get_verification_remote",
+    "submit_verification_remote",
+    "verification_request_payload",
+    "wait_verification_remote",
+    "IntentBundleContractError",
+    "normalize_intent_bundle_payload",
+    "validate_intent_bundle_schema_version",
     "MOTIF_PLUGIN_ABI_VERSION",
     "MotifCompileContext",
     "MotifCompileResult",
@@ -325,11 +445,31 @@ __all__ = [
     "verify_host_artifact_dir",
     "verify_host_intent_file",
     "verify_host_tool",
+    "BrowserEvidence",
+    "BrowserPlanOutcome",
+    "verify_local_artifact",
+    "DEFAULT_VIEWPORTS",
+    "EvidenceFile",
+    "RetryLineage",
+    "REPAIR_SCHEMA_VERSION",
+    "RepairDirective",
+    "SourceNodePath",
+    "VERIFICATION_SCHEMA_VERSION",
+    "VerificationDiagnostic",
+    "VerificationPlan",
+    "VerificationResult",
+    "VerificationRepairPlan",
+    "VerificationViewport",
+    "build_verification_id",
     "prove",
     "prove_tool",
     # Utilities
     "build_address_index",
     "normalize_compiler_result",
+    "load_conformance_corpus",
+    "MAX_CONVERGENCE_ATTEMPTS",
     "parse_canonical_address",
     "resolve_address",
+    "run_conformance_corpus",
+    "run_until_conformant",
 ]

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/src/viewspec/_version.py

@@ -1,3 +1,3 @@
 """Package version for local source and installed entrypoints."""
 
-__version__ = "0.3.0b2"
+__version__ = "0.3.0b4"

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/src/viewspec/app_react_verify.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import os
 import shutil
 import subprocess
 import tempfile
@@ -12,6 +13,7 @@ from typing import Any
 
 from viewspec.app_react import REACT_APP_MANIFEST, REACT_APP_TARGET
 from viewspec.local_tools import file_hash
+from viewspec.node_runtime import materialize_prebuilt_node_modules
 
 
 APP_REACT_VERIFY_SCHEMA_VERSION = 1
@@ -43,12 +45,20 @@ def verify_react_app_artifact_dir(
             host_dir = Path(temp_name) / "app"
             _copy_artifact(artifact_path, host_dir)
             if install:
-                install_result = _run_process(
-                    ["npm", "ci", "--ignore-scripts"],
-                    cwd=host_dir,
-                    timeout=APP_REACT_VERIFY_INSTALL_TIMEOUT_SECONDS,
-                )
-                _require_success(install_result, "APP_REACT_VERIFY_INSTALL_FAILED", "npm ci --ignore-scripts")
+                seed = os.environ.get("VIEWSPEC_HOST_VERIFY_NODE_MODULES_DIR")
+                if seed:
+                    _link_prebuilt_node_modules(host_dir, Path(seed))
+                else:
+                    install_result = _run_process(
+                        ["npm", "ci", "--ignore-scripts"],
+                        cwd=host_dir,
+                        timeout=APP_REACT_VERIFY_INSTALL_TIMEOUT_SECONDS,
+                    )
+                    _require_success(
+                        install_result,
+                        "APP_REACT_VERIFY_INSTALL_FAILED",
+                        "npm ci --ignore-scripts",
+                    )
             else:
                 source_modules = artifact_path / "node_modules"
                 if not source_modules.is_dir():
@@ -87,7 +97,13 @@ def verify_react_app_artifact_dir(
             "install": bool(install),
             "assertions": assertions,
             "policy": {
-                "install_command": "npm ci --ignore-scripts" if install else "none",
+                "install_command": (
+                    "prebuilt_node_modules"
+                    if install and os.environ.get("VIEWSPEC_HOST_VERIFY_NODE_MODULES_DIR")
+                    else "npm ci --ignore-scripts"
+                    if install
+                    else "none"
+                ),
                 "build_command": "npm run build",
                 "browser_command": "npm run viewspec:verify",
             },
@@ -122,6 +138,30 @@ class ReactAppVerifyFailure(ValueError):
         self.fix = fix
 
 
+def _link_prebuilt_node_modules(host_dir: Path, configured: Path) -> None:
+    if not configured.is_absolute():
+        raise ReactAppVerifyFailure(
+            "APP_REACT_VERIFY_DEPENDENCIES_MISSING",
+            "VIEWSPEC_HOST_VERIFY_NODE_MODULES_DIR must be an absolute path.",
+            "Configure an absolute prebuilt node_modules path and retry.",
+        )
+    seed = configured.resolve()
+    if not seed.is_dir():
+        raise ReactAppVerifyFailure(
+            "APP_REACT_VERIFY_DEPENDENCIES_MISSING",
+            "Configured prebuilt node_modules directory does not exist.",
+            "Build the configured dependency bundle and retry.",
+        )
+    destination = host_dir / "node_modules"
+    if destination.exists() or destination.is_symlink():
+        raise ReactAppVerifyFailure(
+            "APP_REACT_VERIFY_DEPENDENCIES_MISSING",
+            "Host node_modules destination must be empty before linking dependencies.",
+            "Remove the existing host dependency directory and retry.",
+        )
+    materialize_prebuilt_node_modules(destination, seed)
+
+
 def _preflight(artifact_dir: Path, manifest_path: Path) -> dict[str, Any]:
     if not artifact_dir.is_dir() or not manifest_path.is_file():
         raise ReactAppVerifyFailure(

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/src/viewspec/cli.py

@@ -55,6 +55,8 @@ from viewspec.local_tools import (
     init_design_file,
     source_hash,
 )
+from viewspec.local_verify import verify_local_artifact
+from viewspec.verification import VerificationPlan
 from viewspec.prove import PROVE_DEFAULT_OUT, prove
 from viewspec.mcp_server import MCP_INSTALL_HINT, MissingMCPDependency, mcp_dependency_available, run_mcp_server
 from viewspec.native_agents import NativeAgentError, VALID_TARGETS, init_agent_instructions
@@ -275,6 +277,27 @@ def _build_parser() -> argparse.ArgumentParser:
     verify_host_parser.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
     verify_host_parser.set_defaults(func=_verify_host_command)
 
+    verify_parser = subparsers.add_parser("verify", help="Verify rendered UI conformance across canonical viewports.")
+    verify_parser.add_argument("artifact_dir", help="Checked react-tailwind-tsx artifact directory.")
+    verify_parser.add_argument("--plan", help="Optional verification plan JSON file.")
+    verify_parser.add_argument(
+        "--evidence-out",
+        default=".viewspec-verification/evidence",
+        help="Empty directory where browser evidence will be written.",
+    )
+    verify_parser.add_argument(
+        "--report-out",
+        default=".viewspec-verification/result.json",
+        help="Canonical verification result JSON path.",
+    )
+    verify_parser.add_argument(
+        "--repair-out",
+        help="Repair plan JSON path. Defaults to repair.json beside --report-out.",
+    )
+    verify_parser.add_argument("--install", action="store_true", help="Allow npm ci in the isolated browser host.")
+    verify_parser.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    verify_parser.set_defaults(func=_verify_command)
+
     init_agent_parser = subparsers.add_parser("init-agent", help="Install managed ViewSpec instructions for coding agents.")
     init_agent_parser.add_argument("--target", required=True, choices=VALID_TARGETS, help="Agent instruction target to update.")
     init_agent_parser.add_argument("--root", default=".", help="Repository root for instruction files.")
@@ -1076,6 +1099,47 @@ def _verify_host_command(args: argparse.Namespace) -> int:
     return 0 if result["ok"] else 2
 
 
+def _verify_command(args: argparse.Namespace) -> int:
+    plan = VerificationPlan.default()
+    if args.plan:
+        plan = VerificationPlan.from_json(json.loads(Path(args.plan).read_text(encoding="utf-8")))
+    result = verify_local_artifact(
+        args.artifact_dir,
+        plan=plan,
+        evidence_dir=args.evidence_out,
+        report_out=args.report_out,
+        install=bool(args.install),
+    )
+    from viewspec.repair import VerificationRepairPlan
+
+    repair = VerificationRepairPlan.from_result(result)
+    repair_path = (
+        Path(args.repair_out)
+        if args.repair_out
+        else Path(args.report_out).with_name("repair.json")
+    )
+    atomic_write(
+        repair_path,
+        json.dumps(repair.to_json(), indent=2, sort_keys=True) + "\n",
+    )
+    payload = {**result.to_json(), "repair_plan": repair.to_json()}
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(result.status)
+        print(f"verification_id: {result.verification_id}")
+        print(f"evidence_files: {len(result.evidence)}")
+        print(f"next: {repair.disposition}")
+        for diagnostic in result.diagnostics:
+            location = f" [{diagnostic.viewport}]" if diagnostic.viewport else ""
+            source = f" {diagnostic.source_ref}" if diagnostic.source_ref else ""
+            print(f"{diagnostic.severity}: {diagnostic.code}{location}{source}: {diagnostic.message}")
+        for directive in repair.directives:
+            source = f" {directive.source_path.to_text()}" if directive.source_path else ""
+            print(f"repair: {directive.repair_id}{source}: {directive.instruction}")
+    return {"conformant": 0, "nonconformant": 1, "indeterminate": 2}[result.status]
+
+
 def _host_assertion_summary_lines(assertions: object, requirements: object = None) -> list[str]:
     if not isinstance(assertions, dict):
         return []

{viewspec-0.3.0b2 → viewspec-0.3.0b4}/src/viewspec/compiler.py

@@ -1803,8 +1803,66 @@ VIEWSPEC_API_URL = "https://api.viewspec.dev"
 
 
 class CompilerAPIError(Exception):
-    """Raised when the hosted compiler API returns an error."""
-    pass
+    """Structured failure returned by the hosted compiler API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "remote_error",
+        path: str | None = None,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        retry_after: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.path = path
+        self.status_code = status_code
+        self.request_id = request_id
+        self.retry_after = retry_after
+
+
+def _response_header(response: Any, name: str) -> str | None:
+    headers = getattr(response, "headers", {})
+    value = headers.get(name) if hasattr(headers, "get") else None
+    if value is None and hasattr(headers, "items"):
+        value = next((item for key, item in headers.items() if str(key).lower() == name.lower()), None)
+    return None if value is None else str(value)
+
+
+def _compiler_api_error(response: Any, data: Any = None) -> CompilerAPIError:
+    status_code = int(getattr(response, "status_code", 0)) or None
+    if data is None:
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+    error = data.get("error") if isinstance(data, dict) else None
+    structured = error if isinstance(error, dict) else {}
+    message = str(structured.get("message") or "")
+    code = str(structured.get("code") or "remote_error")
+    path = structured.get("path") if isinstance(structured.get("path"), str) else None
+    if not message and isinstance(data, dict) and isinstance(data.get("message"), str):
+        message = data["message"]
+    if status_code == 401 and not structured:
+        message = "Invalid API key"
+        code = "invalid_api_key"
+    elif status_code == 429 and not structured:
+        message = f"Rate limit exceeded: {message or 'Upgrade at viewspec.dev'}"
+        code = "rate_limit_exceeded"
+    elif not message:
+        message = f"Compilation failed (HTTP {status_code})"
+    request_id = data.get("request_id") if isinstance(data, dict) and isinstance(data.get("request_id"), str) else None
+    request_id = request_id or _response_header(response, "X-Request-ID")
+    return CompilerAPIError(
+        message,
+        code=code,
+        path=path,
+        status_code=status_code,
+        request_id=request_id,
+        retry_after=_response_header(response, "Retry-After"),
+    )
 
 
 def _compile_request_payload(request: IntentBundle | CompileRequestPayload) -> CompileRequestPayload:
@@ -1859,7 +1917,9 @@ def compile_remote_response(
             timeout=30.0,
         )
     except httpx.HTTPError as exc:
-        raise CompilerAPIError(f"Remote compilation request failed: {exc}") from exc
+        raise CompilerAPIError(
+            f"Remote compilation request failed: {exc}", code="network_error"
+        ) from exc
 
     def _response_json() -> dict[str, Any]:
         try:
@@ -1870,17 +1930,8 @@ def compile_remote_response(
             raise CompilerAPIError("Compilation failed: response JSON was not an object")
         return data
 
-    if response.status_code == 429:
-        data = _response_json()
-        raise CompilerAPIError(
-            f"Rate limit exceeded: {data.get('message', 'Upgrade at viewspec.dev')}"
-        )
-    if response.status_code == 401:
-        raise CompilerAPIError("Invalid API key")
     if response.status_code != 200:
-        raise CompilerAPIError(
-            f"Compilation failed (HTTP {response.status_code}): {response.text}"
-        )
+        raise _compiler_api_error(response, _response_json())
 
     data = _response_json()
     if "ast" not in data: