Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

39.3 KB
Raw Blame
"""Canvas source-project validation.

A canvas source project is the multi-file write format for canvases. This
module validates candidate projects against the platform contract (pinned
dependencies, size limits, runtime safety, declared capabilities) and presents
pre-relational single-file canvases as a synthetic project until their next
real publish.

Everything here is pure — no I/O beyond the contract manifest, no ORM — so it
can be exercised without a database and shared with the build worker.
"""

import re
import json
from typing import Any
from urllib.parse import urlsplit

import jsonschema

from products.canvas.backend.actions import CANVAS_ACTIONS
from products.canvas.backend.connectors import (
    MCP_PROVIDER_PREFIX,
    NATIVE_CONNECTORS,
    is_known_provider,
    mcp_provider_host,
    unregistered_native_tools,
)
from products.canvas.backend.contract import (
    MAX_COMPONENT_HEIGHT,
    MAX_COMPONENT_WIDTH,
    allowed_import_specifiers,
    canonical_network_origin,
    canvas_sdk_version,
    contract_limits,
    platform_dependencies,
)
from products.canvas.backend.mcp_tools import CANVAS_MCP_TOOL_ALLOWLIST, canvas_mcp_tool

CANVAS_SOURCE_SCHEMA_VERSION = 1
CANVAS_ENTRY_HTML = "index.html"
# The conventional React entry component (also what the synthetic shell mounts).
CANVAS_COMPONENT_PATH = "src/canvas.tsx"

# Config schemas are author-supplied, so the vocabulary is an allowlist:
# no $ref/$dynamicRef (nothing downstream may be induced to resolve one) and
# no pattern/patternProperties (placement-config validation must not evaluate
# author-supplied regexes). Size-capped so a schema cannot bloat version rows.
MAX_CONFIG_SCHEMA_BYTES = 16 * 1024
# Depth-capped as well: a schema well under the byte cap can still nest deeply
# enough to exhaust the Python recursion limit inside jsonschema's check_schema
# (or our own keyword scan), which would escape as a 500 rather than a validation
# diagnostic. Bounded far below where check_schema starts recursing off the limit.
MAX_CONFIG_SCHEMA_DEPTH = 32
ALLOWED_CONFIG_SCHEMA_KEYWORDS = frozenset(
    {
        "type",
        "title",
        "description",
        "default",
        "properties",
        "required",
        "additionalProperties",
        "items",
        "enum",
        "const",
        "minimum",
        "maximum",
        "minLength",
        "maxLength",
        "minItems",
        "maxItems",
        "format",
    }
)

# File extensions whose content is scanned as source code.
_CODE_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx")
# Files scanned for CSS custom property declarations: stylesheets, the entry
# HTML, and code, because inline <style> blocks and CSS-in-JS carry CSS as
# strings.
_STYLE_EXTENSIONS = (".css", ".html", *_CODE_EXTENSIONS)

# Quill design tokens that the bundled platform stylesheet (@posthog/quill
# color-system.css) declares on the universal selector `*`, not on `:root`.
# Every element then gets Quill's value directly, so an author's `:root` or
# `html.dark` declaration of the same name never reaches any descendant and
# text colored with `var(--muted)` silently becomes Quill's pale surface color.
# Keep in sync with the `* { ... }` rule of the pinned Quill version.
_PLATFORM_ELEMENT_TOKENS = frozenset(
    {
        "background",
        "border",
        "card",
        "chrome",
        "fill-expanded",
        "fill-hover",
        "fill-selected",
        "input",
        "muted",
        "primary",
    }
)
# A declaration sits at the start of a line or right after `{`, `;`, or `,`
# (CSS rule bodies and inline-style object keys). Requiring that context keeps
# a comment such as `// --muted: legacy` or a `var(--muted)` use from matching.
_PLATFORM_TOKEN_DECLARATION_RE = re.compile(
    r"(?:^|[{;,])\s*[\"']?--(" + "|".join(sorted(_PLATFORM_ELEMENT_TOKENS)) + r")[\"']?\s*:",
    re.MULTILINE,
)

# The synthetic entry shell presented for pre-relational canvases whose only
# source is a single stored React component.
SYNTHETIC_INDEX_HTML = """<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/canvas.tsx"></script>
  </body>
</html>
"""

# Matches static module specifiers: `from "spec"` (import-with-bindings and
# export-from) or a bare side-effect `import "spec"`. Regex-based, so a literal
# `from "x"` inside a string can still fool it — the builder parses for real.
_STATIC_IMPORT_RE = re.compile(r"\bfrom\s*[\"']([^\"']+)[\"']|\bimport\s*[\"']([^\"']+)[\"']")

# Out-of-band code loading the sandbox rejects outright.
_FORBIDDEN_PATTERNS: list[tuple[re.Pattern[str], str, str]] = [
    (re.compile(r"\bimport\s*\("), "forbidden_dynamic_import", "dynamic import() is not allowed"),
    (re.compile(r"\brequire\s*\("), "forbidden_require", "require() is not allowed"),
    (re.compile(r"\bimportScripts\s*\("), "forbidden_import_scripts", "importScripts() is not allowed"),
    (re.compile(r"<script\b", re.IGNORECASE), "forbidden_inline_script", "inline <script> is not allowed"),
]

# Direct network calls: the `ph` bridge is the only sanctioned data path. The
# sandbox CSP blocks these at runtime, so surface them as warnings (the regex
# can't tell code from a comment or string).
_NETWORK_PATTERNS: list[tuple[re.Pattern[str], str, str]] = [
    (
        re.compile(r"\bfetch\s*\("),
        "network_fetch",
        "fetch() requires every destination in capabilities.network.origins — prefer the `ph` data bridge for PostHog data",
    ),
    (
        re.compile(r"\bXMLHttpRequest\b"),
        "network_xhr",
        "XMLHttpRequest requires every destination in capabilities.network.origins — prefer the `ph` data bridge for PostHog data",
    ),
]

_FETCH_LITERAL_URL_RE = re.compile(r"\bfetch\s*\(\s*([\"'`])(https://[^\"'`]+)\1")
# `object` and `embed` are left out on purpose: the artifact CSP keeps
# `object-src 'none'`, so a declared origin cannot make them load. Matching
# them would block publish with a remedy that does nothing.
_RESOURCE_TAG_RE = re.compile(
    r"<(?:img|audio|video|source|track|iframe)\b[^>]*?"
    r"\b(?:src|poster)\s*=\s*(?:\{\s*)?([\"'`])(https://[^\"'`]+)\1",
    re.IGNORECASE,
)
_SRCSET_TAG_RE = re.compile(r"<(?:img|source)\b[^>]*?\bsrcset\s*=\s*(?:\{\s*)?([\"'`])([^\"'`]+)\1", re.IGNORECASE)
_SRCSET_URL_RE = re.compile(r"https://[^\s,]+")
_LINK_TAG_RE = re.compile(r"<link\b[^>]*>", re.IGNORECASE)
_REL_STYLESHEET_RE = re.compile(r"\brel\s*=\s*([\"'])stylesheet\1", re.IGNORECASE)
_HREF_LITERAL_URL_RE = re.compile(r"\bhref\s*=\s*(?:\{\s*)?([\"'])(https://[^\"']+)\1", re.IGNORECASE)
_CSS_URL_RE = re.compile(r"\burl\(\s*([\"']?)(https://[^\"')\s]+)\1\s*\)", re.IGNORECASE)
_CSS_IMPORT_RE = re.compile(r"@import\s+([\"'])(https://[^\"']+)\1", re.IGNORECASE)

# `ph` bridge calls checked against the project's declared capabilities. The
# host enforces capabilities at runtime, so an undeclared call would build fine
# and then die in view mode — validating here turns that into a diagnostic the
# publishing agent can self-correct on.
_PH_LOAD_INSIGHT_RE = re.compile(r"\bph\s*\.\s*loadInsight\s*\(\s*(?:[\"']([^\"']+)[\"'])?")
_PH_QUERY_RE = re.compile(r"\bph\s*\.\s*query\s*\(")
_PH_CAPTURE_RE = re.compile(r"\bph\s*\.\s*capture\s*\(\s*(?:[\"']([^\"']+)[\"'])?")
_PH_STATE_RE = re.compile(r"\bph\s*\.\s*state\s*\.")
_PH_STATE_CALL_RE = re.compile(r"\bph\s*\.\s*state\s*\.\s*(get|set|list)\s*\(")
_STATE_SCOPE_LITERAL_RE = re.compile(r"\bscope\s*:\s*[\"']([^\"']+)[\"']")
_PH_ACTIONS_RE = re.compile(r"\bph\s*\.\s*actions\s*\.\s*invoke\s*\(\s*(?:[\"']([^\"']+)[\"'])?")
_PH_TOOLS_RE = re.compile(r"\bph\s*\.\s*tools\s*\.\s*(read|call)\s*\(\s*(?:[\"']([^\"']+)[\"'])?")
_PH_AGENT_REQUEST_RE = re.compile(r"\bph\s*\.\s*agent\s*\.\s*request\s*\(")
_PH_CONNECTORS_CALL_RE = re.compile(
    r"\bph\s*\.\s*connectors\s*\.\s*call\s*\(\s*(?:[\"']([^\"']+)[\"']\s*(?:,\s*[\"']([^\"']+)[\"'])?)?"
)

_PATH_SEGMENT_RE = re.compile(r"^[A-Za-z0-9._@-]+$")


def diagnostic(
    severity: str, code: str, message: str, path: str | None = None, line: int | None = None
) -> dict[str, Any]:
    entry: dict[str, Any] = {"severity": severity, "code": code, "message": message}
    if path is not None:
        entry["path"] = path
    if line is not None:
        entry["line"] = line
    return entry


def has_errors(diagnostics: list[dict[str, Any]]) -> bool:
    return any(entry["severity"] == "error" for entry in diagnostics)


def synthetic_source_project(legacy_code: str | None) -> dict[str, Any]:
    """Present a pre-relational single-file canvas as a source project.

    The component file carries the stored source verbatim (empty string for a
    canvas that has never been published), and the entry HTML is the fixed
    synthetic shell.
    """
    return {
        "schemaVersion": CANVAS_SOURCE_SCHEMA_VERSION,
        "files": {
            CANVAS_ENTRY_HTML: SYNTHETIC_INDEX_HTML,
            CANVAS_COMPONENT_PATH: legacy_code if isinstance(legacy_code, str) else "",
        },
        "entryHtml": CANVAS_ENTRY_HTML,
        "dependencies": platform_dependencies(),
        "canvasSdkVersion": canvas_sdk_version(),
    }


def validate_relative_path(path: str, *, restrict_charset: bool = True) -> str | None:
    """Validate a relative, forward-slash file path; returns the problem or None.

    Source-project paths keep the strict segment charset; artifact paths
    (``restrict_charset=False``) only reject control characters.
    """
    if path == "" or path.startswith("/") or "\\" in path:
        return "file paths must be relative, non-empty, and use forward slashes"
    if any(character in path for character in "\r\n\0"):
        return "file paths must not contain control characters"
    for segment in path.split("/"):
        if segment in ("", ".", ".."):
            return "file paths must not contain empty, '.', or '..' segments"
        if restrict_charset and not _PATH_SEGMENT_RE.match(segment):
            return "file path segments may only contain letters, digits, '.', '_', '@', and '-'"
    return None


def _line_of(code: str, position: int) -> int:
    return code.count("\n", 0, position) + 1


def _validate_network_origin(origin: Any) -> str | None:
    if not isinstance(origin, str):
        return "network origins must be strings"
    canonical = canonical_network_origin(origin)
    if canonical is None:
        return (
            "network origins must be exact HTTPS origins without paths, credentials, queries, fragments, or wildcards"
        )
    if origin.rstrip("/") != canonical:
        return f'network origin must use its canonical form: "{canonical}"'
    return None


def _network_origin_from_url(url: str) -> str | None:
    try:
        parsed = urlsplit(url)
        port = parsed.port
    except ValueError:
        return None
    if parsed.scheme != "https" or not parsed.hostname:
        return None
    hostname = f"[{parsed.hostname}]" if ":" in parsed.hostname else parsed.hostname
    candidate = f"https://{hostname}" + (f":{port}" if port is not None else "")
    return canonical_network_origin(candidate)


def _literal_external_urls(content: str) -> list[tuple[str, int]]:
    urls: list[tuple[str, int]] = []
    for pattern in (_FETCH_LITERAL_URL_RE, _RESOURCE_TAG_RE, _CSS_URL_RE, _CSS_IMPORT_RE):
        urls.extend((match.group(2), match.start(2)) for match in pattern.finditer(content))
    for srcset in _SRCSET_TAG_RE.finditer(content):
        urls.extend(
            (match.group(0), srcset.start(2) + match.start()) for match in _SRCSET_URL_RE.finditer(srcset.group(2))
        )
    for tag in _LINK_TAG_RE.finditer(content):
        if _REL_STYLESHEET_RE.search(tag.group(0)) is None:
            continue
        href = _HREF_LITERAL_URL_RE.search(tag.group(0))
        if href is not None:
            urls.append((href.group(2), tag.start() + href.start(2)))
    return urls


def _validate_network_capabilities(path: str, content: str, declared_origins: set[str]) -> list[dict[str, Any]]:
    diagnostics: list[dict[str, Any]] = []
    seen: set[str] = set()
    for url, position in _literal_external_urls(content):
        origin = _network_origin_from_url(url)
        if origin is None or origin in seen:
            continue
        seen.add(origin)
        if origin not in declared_origins:
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_network_origin",
                    f'External resource requires "{origin}" in capabilities.network.origins — '
                    "the canvas sandbox blocks undeclared origins at runtime",
                    path=path,
                    line=_line_of(content, position),
                )
            )
    return diagnostics


def _validate_platform_tokens(path: str, content: str) -> list[dict[str, Any]]:
    diagnostics: list[dict[str, Any]] = []
    for match in _PLATFORM_TOKEN_DECLARATION_RE.finditer(content):
        token = match.group(1)
        diagnostics.append(
            diagnostic(
                "error",
                "platform_token_redeclared",
                f"--{token} is a platform design token that the platform stylesheet sets on every element, "
                f"so this declaration is ignored and text colored with var(--{token}) can become unreadable. "
                f"Rename it, for example --canvas-{token}, or use the platform token without redefining it",
                path=path,
                line=_line_of(content, match.start(1)),
            )
        )
    return diagnostics


def _validate_code_file(path: str, code: str) -> list[dict[str, Any]]:
    diagnostics: list[dict[str, Any]] = []

    for pattern, code_name, message in _FORBIDDEN_PATTERNS:
        for match in pattern.finditer(code):
            diagnostics.append(diagnostic("error", code_name, message, path=path, line=_line_of(code, match.start())))

    for pattern, code_name, message in _NETWORK_PATTERNS:
        for match in pattern.finditer(code):
            diagnostics.append(diagnostic("warning", code_name, message, path=path, line=_line_of(code, match.start())))

    allowed = allowed_import_specifiers()
    for match in _STATIC_IMPORT_RE.finditer(code):
        specifier = match.group(1) or match.group(2)
        if not specifier or specifier.startswith(("./", "../", "/")):
            continue
        # Local worker imports carry a ?worker suffix; strip it before checking.
        if specifier not in allowed and specifier.removesuffix("?worker") not in allowed:
            diagnostics.append(
                diagnostic(
                    "error",
                    "import_not_allowed",
                    f'import of module "{specifier}" is not supported — allowed imports: ' + ", ".join(sorted(allowed)),
                    path=path,
                    line=_line_of(code, match.start()),
                )
            )

    return diagnostics


def _validate_connector_declarations(declared: Any) -> list[dict[str, Any]]:
    """Check capabilities.connectors: known providers, registered native tools, public MCP hosts."""
    diagnostics: list[dict[str, Any]] = []
    if not isinstance(declared, list):
        return [diagnostic("error", "invalid_connector_declaration", "capabilities.connectors must be a list")]
    for entry in declared:
        provider = entry.get("provider") if isinstance(entry, dict) else None
        tools = entry.get("tools") if isinstance(entry, dict) else None
        if not isinstance(provider, str) or not isinstance(tools, list) or not tools:
            diagnostics.append(
                diagnostic(
                    "error",
                    "invalid_connector_declaration",
                    "each capabilities.connectors entry needs a provider and a non-empty list of tool names",
                )
            )
            continue
        if not is_known_provider(provider):
            diagnostics.append(
                diagnostic(
                    "error",
                    "connector_provider_unknown",
                    f'capabilities.connectors names unknown provider "{provider}" — use one of '
                    + ", ".join(sorted(NATIVE_CONNECTORS))
                    + f', or "{MCP_PROVIDER_PREFIX}<server host>" for an MCP store server',
                )
            )
            continue
        host = mcp_provider_host(provider)
        if host is not None and canonical_network_origin(f"https://{host}") is None:
            diagnostics.append(
                diagnostic(
                    "error",
                    "connector_provider_unknown",
                    f'connector provider "{provider}" must name a public server host, e.g. "mcp:mcp.example.com"',
                )
            )
            continue
        unregistered = unregistered_native_tools(provider, [tool for tool in tools if isinstance(tool, str)])
        if unregistered:
            diagnostics.append(
                diagnostic(
                    "error",
                    "connector_tool_not_registered",
                    f"capabilities.connectors declares unknown {provider} tools: {', '.join(unregistered)} — "
                    f"registered tools: {', '.join(sorted(NATIVE_CONNECTORS[provider].tools))}",
                )
            )
    return diagnostics


def _validate_connector_calls(path: str, code: str, capabilities: dict[str, Any]) -> list[dict[str, Any]]:
    """Check ph.connectors.call sites against capabilities.connectors."""
    diagnostics: list[dict[str, Any]] = []
    declared: dict[str, set[str]] = {}
    for entry in capabilities.get("connectors") or []:
        if isinstance(entry, dict) and isinstance(entry.get("provider"), str):
            declared.setdefault(entry["provider"], set()).update(
                tool for tool in entry.get("tools") or [] if isinstance(tool, str)
            )
    for match in _PH_CONNECTORS_CALL_RE.finditer(code):
        provider, tool = match.group(1), match.group(2)
        line = _line_of(code, match.start())
        if provider is None:
            if not declared:
                diagnostics.append(
                    diagnostic(
                        "warning",
                        "capability_missing_connector",
                        "ph.connectors.call() is called with a dynamic provider but capabilities.connectors is "
                        "empty — declare every provider and tool the canvas calls",
                        path=path,
                        line=line,
                    )
                )
            continue
        if provider not in declared or (tool is not None and tool not in declared[provider]):
            called = f'"{provider}", "{tool}"' if tool is not None else f'"{provider}"'
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_connector",
                    f"ph.connectors.call({called}) requires that provider and tool in capabilities.connectors — "
                    "the host rejects undeclared connector calls at runtime",
                    path=path,
                    line=line,
                )
            )
    return diagnostics


def _validate_capabilities(path: str, code: str, capabilities: dict[str, Any]) -> list[dict[str, Any]]:
    """Check `ph` bridge calls against the project's declared capabilities."""
    diagnostics: list[dict[str, Any]] = []
    posthog_capabilities = capabilities.get("posthog") or {}
    declared_insights = set(posthog_capabilities.get("insights") or [])
    declared_events = set(posthog_capabilities.get("captureEvents") or [])
    inline_queries = bool(posthog_capabilities.get("inlineQueries"))
    agent_requests = bool(posthog_capabilities.get("agentRequests"))

    declared_state = set(posthog_capabilities.get("state") or [])
    if not declared_state:
        state_match = _PH_STATE_RE.search(code)
        if state_match is not None:
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_state",
                    'ph.state requires its scopes in capabilities.posthog.state (["user"] and/or ["shared"]) — '
                    "the host rejects undeclared state access at runtime",
                    path=path,
                    line=_line_of(code, state_match.start()),
                )
            )
    else:
        # Declaring one scope is not declaring the other: check each call
        # site's scope — the explicit literal, or the runtime's "user"
        # default when get/set pass no options — against the declaration.
        for call in _PH_STATE_CALL_RE.finditer(code):
            window_end = min(len(code), call.end() + 200)
            next_call = _PH_STATE_CALL_RE.search(code, call.end())
            if next_call is not None:
                window_end = min(window_end, next_call.start())
            scope_literal = _STATE_SCOPE_LITERAL_RE.search(code, call.end(), window_end)
            used_scope = scope_literal.group(1) if scope_literal else None
            if used_scope is None:
                used_scope = "user" if call.group(1) in ("get", "set") else None
            if used_scope is not None and used_scope not in declared_state:
                line = _line_of(code, call.start())
                detail = (
                    f'ph.state.{call.group(1)} uses scope "{used_scope}"'
                    if scope_literal
                    else f'ph.state.{call.group(1)} defaults to scope "user"'
                )
                diagnostics.append(
                    diagnostic(
                        "error",
                        "capability_missing_state",
                        f"{detail}, which capabilities.posthog.state does not declare — "
                        "the host rejects undeclared state access at runtime",
                        path=path,
                        line=line,
                    )
                )

    declared_action_verbs = set(posthog_capabilities.get("actions") or [])
    for match in _PH_ACTIONS_RE.finditer(code):
        verb = match.group(1)
        line = _line_of(code, match.start())
        if verb is not None and verb not in declared_action_verbs:
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_action",
                    f'ph.actions.invoke("{verb}") requires "{verb}" in capabilities.posthog.actions — '
                    "the host rejects undeclared actions at runtime",
                    path=path,
                    line=line,
                )
            )
        elif verb is None and not declared_action_verbs:
            diagnostics.append(
                diagnostic(
                    "warning",
                    "capability_missing_action",
                    "ph.actions.invoke() is called with a dynamic verb but capabilities.posthog.actions is empty — "
                    "declare every verb the canvas invokes",
                    path=path,
                    line=line,
                )
            )

    declared_tool_names = set(posthog_capabilities.get("tools") or [])
    for match in _PH_TOOLS_RE.finditer(code):
        method, tool = match.group(1), match.group(2)
        line = _line_of(code, match.start())
        if tool is not None and tool not in declared_tool_names:
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_tool",
                    f'ph.tools.{method}("{tool}") requires "{tool}" in capabilities.posthog.tools. '
                    "The host rejects undeclared tools at runtime.",
                    path=path,
                    line=line,
                )
            )
        elif tool is None and not declared_tool_names:
            diagnostics.append(
                diagnostic(
                    "warning",
                    "capability_missing_tool",
                    f"ph.tools.{method}() is called with a dynamic tool name but capabilities.posthog.tools is "
                    "empty. Declare every tool the canvas runs.",
                    path=path,
                    line=line,
                )
            )

    for match in _PH_LOAD_INSIGHT_RE.finditer(code):
        short_id = match.group(1)
        line = _line_of(code, match.start())
        if short_id is not None and short_id not in declared_insights:
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_insight",
                    f'ph.loadInsight("{short_id}") requires "{short_id}" in capabilities.posthog.insights — '
                    "the host rejects undeclared insights at runtime",
                    path=path,
                    line=line,
                )
            )
        elif short_id is None and not declared_insights:
            diagnostics.append(
                diagnostic(
                    "warning",
                    "capability_missing_insight",
                    "ph.loadInsight() is called with a dynamic id but capabilities.posthog.insights is empty — "
                    "declare every insight short id the canvas loads",
                    path=path,
                    line=line,
                )
            )

    if not inline_queries:
        query_match = _PH_QUERY_RE.search(code)
        if query_match is not None:
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_inline_queries",
                    "ph.query() requires capabilities.posthog.inlineQueries: true — "
                    "the host rejects undeclared inline queries at runtime",
                    path=path,
                    line=_line_of(code, query_match.start()),
                )
            )

    for match in _PH_CAPTURE_RE.finditer(code):
        event = match.group(1)
        line = _line_of(code, match.start())
        if event is not None and event not in declared_events:
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_capture_event",
                    f'ph.capture("{event}") requires "{event}" in capabilities.posthog.captureEvents — '
                    "the host rejects undeclared events at runtime",
                    path=path,
                    line=line,
                )
            )
        elif event is None and not declared_events:
            diagnostics.append(
                diagnostic(
                    "warning",
                    "capability_missing_capture_event",
                    "ph.capture() is called with a dynamic event but capabilities.posthog.captureEvents is empty — "
                    "declare every event name the canvas captures",
                    path=path,
                    line=line,
                )
            )

    if not agent_requests:
        request_match = _PH_AGENT_REQUEST_RE.search(code)
        if request_match is not None:
            diagnostics.append(
                diagnostic(
                    "error",
                    "capability_missing_agent_requests",
                    "ph.agent.request() requires capabilities.posthog.agentRequests: true — "
                    "the host rejects undeclared agent requests at runtime",
                    path=path,
                    line=_line_of(code, request_match.start()),
                )
            )

    return diagnostics


def _validate_component_size(size: Any) -> str | None:
    """Validate a component's grid-size contract; returns the problem or None."""
    if not isinstance(size, dict):
        return "component.size must be an object with defaultW, defaultH, minW, and minH"
    for key in ("defaultW", "defaultH", "minW", "minH", "maxW", "maxH"):
        value = size.get(key)
        if value is None:
            if key in ("maxW", "maxH"):
                continue
            return f"component.size.{key} is required"
        if not isinstance(value, int) or isinstance(value, bool) or value < 1:
            return f"component.size.{key} must be a positive integer"
    for axis, cap in (("W", MAX_COMPONENT_WIDTH), ("H", MAX_COMPONENT_HEIGHT)):
        maximum = size.get(f"max{axis}", cap)
        if maximum > cap:
            return f"component.size.max{axis} may not exceed {cap}"
        if not size[f"min{axis}"] <= size[f"default{axis}"] <= maximum:
            return f"component.size must satisfy min{axis} <= default{axis} <= max{axis} (cap {cap})"
    return None


def _unknown_config_schema_keywords(schema: Any) -> set[str]:
    """Every schema keyword used anywhere in the schema tree that is not allowlisted."""
    if not isinstance(schema, dict):
        return set()
    unknown = {key for key in schema if key not in ALLOWED_CONFIG_SCHEMA_KEYWORDS}
    for key, value in schema.items():
        if key == "properties" and isinstance(value, dict):
            for nested in value.values():
                unknown |= _unknown_config_schema_keywords(nested)
        elif key in ("items", "additionalProperties"):
            unknown |= _unknown_config_schema_keywords(value)
    return unknown


def _max_json_depth(value: Any) -> int:
    """Deepest container nesting in a JSON value, walked with an explicit stack.

    Author config schemas are hostile input, so depth is measured without
    recursion — the point is to bound nesting before any recursive processing
    (the keyword scan, jsonschema's check_schema) descends into it.
    """
    max_depth = 0
    stack: list[tuple[Any, int]] = [(value, 1)]
    while stack:
        current, depth = stack.pop()
        if isinstance(current, dict):
            children: Any = current.values()
        elif isinstance(current, list):
            children = current
        else:
            continue
        if depth > max_depth:
            max_depth = depth
        for child in children:
            stack.append((child, depth + 1))
    return max_depth


def _validate_config_schema(config_schema: Any) -> str | None:
    """Validate a component's placement-config schema; returns the problem or None."""
    if not isinstance(config_schema, dict) or config_schema.get("type") != "object":
        return 'component.configSchema must be a JSON Schema object with "type": "object"'
    if len(json.dumps(config_schema, separators=(",", ":")).encode("utf-8")) > MAX_CONFIG_SCHEMA_BYTES:
        return f"component.configSchema may not exceed {MAX_CONFIG_SCHEMA_BYTES // 1024} KB serialized"
    if _max_json_depth(config_schema) > MAX_CONFIG_SCHEMA_DEPTH:
        return f"component.configSchema may not nest deeper than {MAX_CONFIG_SCHEMA_DEPTH} levels"
    unknown = _unknown_config_schema_keywords(config_schema)
    if unknown:
        return (
            "component.configSchema uses unsupported keywords: "
            + ", ".join(sorted(unknown))
            + " — supported: "
            + ", ".join(sorted(ALLOWED_CONFIG_SCHEMA_KEYWORDS))
        )
    try:
        jsonschema.Draft202012Validator.check_schema(config_schema)
    except jsonschema.SchemaError as error:
        return f"component.configSchema is not a valid JSON Schema: {error.message}"
    return None


def validate_component_meta(project: dict[str, Any], kind: str) -> list[dict[str, Any]]:
    """Validate a project's component placement contract for its canvas kind.

    Components must declare how grids may place them (size, optional config
    schema); every other kind must not carry a contract, so an author cannot
    believe a freeform canvas is placeable.
    """
    meta = project.get("component")
    if kind != "component":
        if meta:
            return [
                diagnostic(
                    "error",
                    "component_meta_not_allowed",
                    "only component-kind canvases may declare a `component` placement contract",
                )
            ]
        return []
    if not isinstance(meta, dict):
        return [
            diagnostic(
                "error",
                "component_meta_missing",
                "a component project must declare `component` with a `size` contract "
                '(e.g. {"size": {"defaultW": 2, "defaultH": 1, "minW": 1, "minH": 1}})',
            )
        ]
    diagnostics: list[dict[str, Any]] = []
    size_problem = _validate_component_size(meta.get("size"))
    if size_problem is not None:
        diagnostics.append(diagnostic("error", "component_size_invalid", size_problem))
    if meta.get("configSchema") is not None:
        schema_problem = _validate_config_schema(meta["configSchema"])
        if schema_problem is not None:
            diagnostics.append(diagnostic("error", "component_config_schema_invalid", schema_problem))
    return diagnostics


def validate_source_project(project: dict[str, Any], *, kind: str = "freeform") -> list[dict[str, Any]]:
    """Validate a candidate source project against the platform contract.

    Returns structured diagnostics; an empty list (or warnings only) means the
    project is publishable. Mirrors the build pipeline's stage-1 validation
    (schema, paths, file count, total size) plus dependency, runtime-safety,
    and capability constraints. The authoritative builder performs
    module-graph validation. ``kind`` is the owning canvas's kind — it gates
    the component placement contract, which only component projects carry.
    """
    diagnostics: list[dict[str, Any]] = list(validate_component_meta(project, kind))
    limits = contract_limits()

    if project.get("schemaVersion") != CANVAS_SOURCE_SCHEMA_VERSION:
        diagnostics.append(
            diagnostic(
                "error",
                "unsupported_schema_version",
                f"schemaVersion must be {CANVAS_SOURCE_SCHEMA_VERSION}",
            )
        )

    if project.get("entryHtml") != CANVAS_ENTRY_HTML:
        diagnostics.append(diagnostic("error", "invalid_entry", f'entryHtml must be "{CANVAS_ENTRY_HTML}"'))

    files = project.get("files") or {}
    assets = project.get("assets") or {}
    if project.get("entryHtml") not in files:
        diagnostics.append(diagnostic("error", "missing_entry", "entryHtml must name a file present in files"))
    capabilities = project.get("capabilities") or {}
    network_origins = (capabilities.get("network") or {}).get("origins") or []
    for origin in network_origins:
        problem = _validate_network_origin(origin)
        if problem is not None:
            diagnostics.append(diagnostic("error", "invalid_network_origin", problem))
    declared_verbs = ((project.get("capabilities") or {}).get("posthog") or {}).get("actions") or []
    unregistered = sorted(set(declared_verbs) - set(CANVAS_ACTIONS))
    if unregistered:
        diagnostics.append(
            diagnostic(
                "error",
                "action_not_registered",
                "capabilities.posthog.actions declares unknown verbs: "
                + ", ".join(unregistered)
                + " — registered verbs: "
                + ", ".join(sorted(CANVAS_ACTIONS)),
            )
        )
    declared_tools = (capabilities.get("posthog") or {}).get("tools") or []
    disallowed_tools = sorted(
        {str(tool) for tool in declared_tools if not isinstance(tool, str) or canvas_mcp_tool(tool) is None}
    )
    if disallowed_tools:
        diagnostics.append(
            diagnostic(
                "error",
                "tool_not_allowed",
                "capabilities.posthog.tools declares tools canvases cannot run: "
                + ", ".join(disallowed_tools)
                + ". Allowed tools: "
                + ", ".join(sorted(CANVAS_MCP_TOOL_ALLOWLIST)),
            )
        )
    diagnostics.extend(_validate_connector_declarations(capabilities.get("connectors") or []))
    if capabilities.get("connectors") and "shared" in (capabilities.get("posthog") or {}).get("state", []):
        diagnostics.append(
            diagnostic(
                "error",
                "connector_results_in_shared_state",
                "Canvases with connectors cannot declare shared state. Use user-scoped state for connector data.",
            )
        )
    if len(files) + len(assets) > limits["maxSourceFiles"]:
        diagnostics.append(
            diagnostic(
                "error",
                "too_many_files",
                f"a source project may contain at most {limits['maxSourceFiles']} files",
            )
        )

    total_bytes = 0
    for path, content in files.items():
        path_problem = validate_relative_path(path)
        if path_problem is not None:
            diagnostics.append(diagnostic("error", "invalid_path", path_problem, path=path))
            continue
        size = len(content.encode("utf-8"))
        total_bytes += size
        if size > limits["maxSourceFileBytes"]:
            diagnostics.append(
                diagnostic(
                    "error",
                    "file_too_large",
                    f"file exceeds the {limits['maxSourceFileBytes'] // 1024} KB per-file limit",
                    path=path,
                )
            )
    for path, asset in assets.items():
        path_problem = validate_relative_path(path)
        if path_problem is not None:
            diagnostics.append(diagnostic("error", "invalid_path", path_problem, path=path))
            continue
        size = (len(asset.get("content", "")) * 3) // 4
        total_bytes += size
        if size > limits["maxSourceTotalBytes"]:
            diagnostics.append(
                diagnostic(
                    "error",
                    "file_too_large",
                    f"asset exceeds the {limits['maxSourceTotalBytes'] // 1024} KB per-file limit",
                    path=path,
                )
            )
    canonical_size = len(json.dumps(project, separators=(",", ":"), sort_keys=True).encode("utf-8"))
    if total_bytes > limits["maxSourceTotalBytes"] or canonical_size > limits["maxSourceTotalBytes"]:
        diagnostics.append(
            diagnostic(
                "error",
                "project_too_large",
                f"the source project exceeds the {limits['maxSourceTotalBytes'] // 1024} KB total size limit",
            )
        )

    pinned_dependencies = platform_dependencies()
    for name, version in (project.get("dependencies") or {}).items():
        pinned = pinned_dependencies.get(name)
        if pinned is None:
            diagnostics.append(
                diagnostic(
                    "error",
                    "dependency_not_admitted",
                    f'dependency "{name}" is not platform-supported — supported: '
                    + ", ".join(sorted(pinned_dependencies)),
                )
            )
        elif version != pinned:
            diagnostics.append(
                diagnostic(
                    "error",
                    "dependency_version_mismatch",
                    f'dependency "{name}" must be the platform-pinned version {pinned}, got {version}',
                )
            )

    declared_network_origins = {
        canonical for origin in network_origins if (canonical := canonical_network_origin(origin)) is not None
    }
    for path, content in files.items():
        if not isinstance(content, str):
            continue
        diagnostics.extend(_validate_network_capabilities(path, content, declared_network_origins))
        if path.endswith(_STYLE_EXTENSIONS):
            diagnostics.extend(_validate_platform_tokens(path, content))
        if path.endswith(_CODE_EXTENSIONS):
            diagnostics.extend(_validate_code_file(path, content))
            diagnostics.extend(_validate_capabilities(path, content, capabilities))
            diagnostics.extend(_validate_connector_calls(path, content, capabilities))

    return diagnostics