funcd-shim 0.2.0__py3-none-any.whl

funcd_shim/__init__.py

@@ -0,0 +1,20 @@
+"""funcd Python runtime shim + the typed authoring contract.
+
+Function authors import the contract types::
+
+    from funcd_shim import Handler, CloudEvent, FunctionContext
+
+    def handle(context: FunctionContext, event: CloudEvent) -> dict:
+        ...
+
+The shim entrypoint is ``python -m funcd_shim`` (see :mod:`funcd_shim.shim`). It serves the
+runtime-shim HTTP contract and validates ``event.data`` / the result against the optional
+``FuncInput`` / ``FuncOutput`` **pydantic models** an artifact declares (ADR-0058, supersedes the
+ADR-0038 JTD ``event_schema``). Requires pydantic at runtime.
+"""
+
+from __future__ import annotations
+
+from .types import CloudEvent, FunctionContext, Handler, Json
+
+__all__ = ["CloudEvent", "FunctionContext", "Handler", "Json"]

funcd_shim/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m funcd_shim`` entrypoint — runs the runtime shim (ADR-0049)."""
+
+from __future__ import annotations
+
+import sys
+
+from .shim import main
+
+if __name__ == "__main__":
+    sys.exit(main())

funcd_shim/_poolworker.py

@@ -0,0 +1,134 @@
+"""Worker-side logic for the funcd Python pool host (ADR-0050), run INSIDE each subinterpreter by
+``InterpreterPoolExecutor``. ``init`` loads the handler + the optional I/O validators once per worker
+interpreter (state persists across invocations); ``invoke`` runs the contract + handler for one
+request and returns a status-tagged envelope; ``ready`` is a side-effect-free load probe.
+
+No ``concurrent.*`` here — plain per-interpreter Python. ``init``/``invoke``/``ready`` are referenced
+by the executor across the interpreter boundary, so they live in this small importable module (the
+host puts the package dir on ``PYTHONPATH`` so the worker can import ``funcd_shim``)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any
+
+from .runtime import Validators
+from .types import CloudEvent, Handler
+
+if TYPE_CHECKING:
+    from .blob import BlobClient
+    from .kv import KVClient
+
+# Per-interpreter state, set by init() and read by invoke() — isolated to this worker interpreter.
+_handler: Handler | None = None
+_validators: Validators = Validators()
+_channel: Any = None  # the shared telemetry channel (ADR-0101), opened once in init()
+
+
+def init(src: str, artifact: str, handler: str, contract_path: str | None = None) -> None:
+    """Load the handler + I/O validators into this interpreter (the materialization shape-gate,
+    ADR-0058/0123). Runs once per worker; a failure breaks the pool → exit 3.
+
+    ADR-0123: when *contract_path* is given, compile the validators from the delivered schema
+    (``fastjsonschema.compile``) **before** the untrusted handler module is imported — the bounded
+    eval-free reversal + the m3 reorder. A set-but-broken path fails the worker closed. When absent,
+    fall back to the module-baked ``__funcd_validate_*`` (transition back-compat)."""
+    global _handler, _validators, _channel
+    if src not in sys.path:
+        sys.path.insert(0, src)
+    from funcd_shim import contract, runtime
+    from funcd_shim.funclog import install_log_capture, open_channel
+
+    # Path B capture (ADR-0081) + traces (ADR-0101): each pool worker runs in its own subinterpreter
+    # with its own root logger, so open the channel + install capture here (per-interpreter), before
+    # the handler loads. One shared channel per worker. No-op unless FUNCD_LOG_FD/SOCK is set.
+    _channel = open_channel()
+    install_log_capture(_channel)
+
+    # ADR-0123: compile the delivered contract AHEAD of the handler import (m3 reorder).
+    delivered = contract.load_from_path(contract_path) if contract_path else None
+    module = runtime.load_module(artifact)
+    _handler = runtime.resolve_handler(module, handler)
+    _validators = delivered if delivered is not None else runtime.resolve_validators(module)
+
+
+def ready() -> bool:
+    """A load probe: True once init() succeeded (no handler call). The host submits this at startup
+    so a bad member surfaces as a broken pool before serving."""
+    return _handler is not None
+
+
+class _Ctx:
+    def log(self, *args: object) -> None:
+        print(*args, flush=True)
+
+    def invoke(self, alias: str, payload: Any) -> Any:
+        from .invoke import invoke as _invoke
+
+        return _invoke(alias, payload)
+
+    @property
+    def kv(self) -> KVClient:
+        from .kv import KVClient
+
+        return KVClient()
+
+    @property
+    def blob(self) -> BlobClient:
+        from .blob import BlobClient
+
+        return BlobClient()
+
+
+def invoke(
+    body: str,
+    traceparent: str | None = None,
+    fn_name: str = "invoke",
+    span_id: str | None = None,
+    links: list[str] | None = None,
+) -> dict[str, Any]:
+    """Run one request: parse → optional input validation → handler → optional output validation →
+    a status-tagged envelope the host maps to the HTTP response (identical to the solo shim). ADR-0101:
+    a successful-past-input-validation request emits a SERVER span on the worker's channel."""
+    if _handler is None:  # defensive — init() always runs first
+        return {"status": 500, "body": {"error": "handler not loaded"}}
+    try:
+        event: CloudEvent[Any] = json.loads(body) if body else CloudEvent()
+    except (json.JSONDecodeError, ValueError):
+        return {"status": 400, "body": {"error": "request body is not valid JSON"}}
+    if not isinstance(event, dict):
+        # A valid-JSON but non-object body (null / array / scalar) is not a CloudEvent envelope.
+        # Reject it cleanly — never let `event.get("data")` raise AttributeError and crash the pooled
+        # worker (that surfaced as a gateway `proxy error: EOF` / empty-body 502).
+        return {
+            "status": 400,
+            "body": {"error": "request body must be a JSON object (CloudEvent envelope)"},
+        }
+    if _validators.input is not None:
+        errors = _validators.input(event.get("data"))
+        if errors:
+            # ADR-0101: input-mismatch short-circuits before the handler → no invocation, no span.
+            return {
+                "status": 422,
+                "body": {"error": "event data does not match the input contract", "details": errors},
+            }
+    from .tracespan import InvocationSpan
+
+    with InvocationSpan(_channel, fn_name, traceparent, span_id, links) as span:
+        try:
+            result = _handler(_Ctx(), event)
+        except Exception as err:  # noqa: BLE001 - user handler errors become 500
+            span.fail(str(err))
+            return {"status": 500, "body": {"error": str(err)}}
+        if _validators.output is not None:
+            errors = _validators.output(result)
+            if errors:
+                span.fail("handler result does not match the output contract")
+                return {
+                    "status": 500,
+                    "body": {"error": "handler result does not match the output contract", "details": errors},
+                }
+        if result is None:
+            return {"status": 204}
+        return {"status": 200, "body": result}

funcd_shim/blob.py

@@ -0,0 +1,117 @@
+"""Function-facing blob over the worker-node local API (HTTP-over-UDS, ADR-0127).
+
+Dials the same per-sandbox socket as ``context.kv``/``context.invoke`` (``FUNCD_INVOKE_SOCKET``); the
+platform routes ``/blob/…`` to the binding-gated, PDP-authorized Facade with the sandbox's function
+identity (bind-as-grant on ``spec.blob``). Stdlib-only — no boto3, no keypair. The blob twin of
+``context.kv``; v1 is bytes-in-memory (streaming is a v2 follow-up).
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import socket
+from urllib.parse import quote
+
+
+class _UnixHTTPConnection(http.client.HTTPConnection):
+    """An HTTPConnection that dials a Unix domain socket instead of TCP."""
+
+    def __init__(self, socket_path: str) -> None:
+        super().__init__("localhost")
+        self._socket_path = socket_path
+
+    def connect(self) -> None:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.connect(self._socket_path)
+        self.sock = sock
+
+
+def _conn() -> _UnixHTTPConnection:
+    socket_path = os.environ.get("FUNCD_INVOKE_SOCKET")
+    if not socket_path:
+        raise RuntimeError(
+            "context.blob: worker-node local API socket unavailable (FUNCD_INVOKE_SOCKET unset)"
+        )
+    return _UnixHTTPConnection(socket_path)
+
+
+def _key_path(binding: str, key: str) -> str:
+    # key may be hierarchical ("a/b"); keep the "/" separators (the server's {key...} captures them).
+    segs = "/".join(quote(s, safe="") for s in key.split("/"))
+    return f"/blob/{quote(binding, safe='')}/{segs}"
+
+
+class BlobClient:
+    """A function's binding-scoped blob storage (ADR-0127): get/put/delete/list a bound prefix's objects,
+    or mint a presigned URL — the blob twin of :class:`KVClient`."""
+
+    def get(self, binding: str, key: str) -> bytes | None:
+        conn = _conn()
+        try:
+            conn.request("GET", _key_path(binding, key))
+            resp = conn.getresponse()
+            data = resp.read()
+            if resp.status == 404:
+                return None
+            if not 200 <= resp.status < 300:
+                text = data.decode("utf-8", "replace")
+                raise RuntimeError(f"context.blob.get failed: {resp.status} {text}")
+            return data
+        finally:
+            conn.close()
+
+    def put(self, binding: str, key: str, data: bytes) -> None:
+        conn = _conn()
+        try:
+            conn.request("PUT", _key_path(binding, key), body=data)
+            resp = conn.getresponse()
+            text = resp.read().decode("utf-8", "replace")
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(f"context.blob.put failed: {resp.status} {text}")
+        finally:
+            conn.close()
+
+    def delete(self, binding: str, key: str) -> None:
+        conn = _conn()
+        try:
+            conn.request("DELETE", _key_path(binding, key))
+            resp = conn.getresponse()
+            text = resp.read().decode("utf-8", "replace")
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(f"context.blob.delete failed: {resp.status} {text}")
+        finally:
+            conn.close()
+
+    def list(self, binding: str, prefix: str = "") -> list[str]:
+        path = f"/blob/{quote(binding, safe='')}"
+        if prefix:
+            path += f"?prefix={quote(prefix, safe='')}"
+        conn = _conn()
+        try:
+            conn.request("GET", path)
+            resp = conn.getresponse()
+            text = resp.read().decode("utf-8")
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(f"context.blob.list failed: {resp.status} {text}")
+            return json.loads(text) if text else []
+        finally:
+            conn.close()
+
+    def signed_url(self, binding: str, key: str, method: str = "GET", expiry: float | None = None) -> str:
+        """Return a presigned external URL for the object. ``method`` is GET (read) / PUT / DELETE (write);
+        ``expiry`` is in seconds (the driver's default when ``None``). A PUT/DELETE URL requires s3::write."""
+        path = f"{_key_path(binding, key)}?sign=1&method={quote(method, safe='')}"
+        if expiry is not None:
+            path += f"&expiry={expiry}s"
+        conn = _conn()
+        try:
+            conn.request("GET", path)
+            resp = conn.getresponse()
+            text = resp.read().decode("utf-8", "replace")
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(f"context.blob.signed_url failed: {resp.status} {text}")
+            return text
+        finally:
+            conn.close()

funcd_shim/build.py

@@ -0,0 +1,318 @@
+"""funcd_build — the BUILD-TIME contract compiler for Python artifacts (ADR-0058/0060).
+
+Runs on the push box (pydantic available), **never** in the worker. For an author source declaring
+``FuncInput`` / ``FuncOutput`` pydantic models, it:
+
+  1. loads the module, reads the models → **JSON Schema** (``pydantic.model_json_schema``);
+  2. compiles a precompiled validator from each schema (``fastjsonschema.compile_to_code``);
+  3. **AST-transforms** the source into the RUNTIME artifact: the ``pydantic`` imports + the
+     ``FuncInput``/``FuncOutput`` classes are stripped, ``from __future__ import annotations`` is
+     ensured (so any leftover annotation referencing a removed class is a string, never evaluated),
+     and the precompiled ``__funcd_validate_*`` are injected.
+
+Returns the runtime source + the schemas. The schemas feed ``funcdctl push --contract`` → the Go
+profile gate (``internal/contract``); funcd compiled the validator FROM the gated schema, so the
+runtime enforcement and the advertised schema share one source (the ADR-0060 integrity invariant).
+This module is NOT embedded into the binary (see ``embed.go``) — it never reaches a worker.
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+import types
+from dataclasses import dataclass
+from typing import Any, cast
+
+import fastjsonschema
+from pydantic import TypeAdapter
+
+_CONTRACT = ("FuncInput", "FuncOutput")
+
+_build_seq = 0  # makes each synthetic contract module's name unique (avoids pydantic's type cache)
+
+# The canonical void side (ADR-0090): "takes/returns nothing" is the explicit JSON Schema
+# {"type":"null"}, not an omission. Its validator is compiled FROM this schema through the same
+# fastjsonschema path as every other side (a null-only check), so ADR-0060's "validator ≡ advertised
+# schema" invariant holds uniformly — there is no hand-baked void validator.
+_VOID_SCHEMA: dict[str, Any] = {"type": "null"}
+
+
+@dataclass
+class BuildResult:
+    """The runtime artifact source + the generated schemas (for the gate / OCI metadata).
+
+    Contracts are mandatory (ADR-0090): both ``input_schema`` and ``output_schema`` are always
+    present — a void side is ``{"type": "null"}``, never ``None``."""
+
+    runtime_source: str
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any]
+
+
+def build(source: str) -> BuildResult:
+    """Compile an author source into its runtime artifact + I/O JSON Schemas (ADR-0058/0060)."""
+    global _build_seq
+    _build_seq += 1
+    # Exec into a REAL, sys.modules-registered module (not a bare dict) so the contract classes get a
+    # resolvable __module__ — pydantic then resolves string annotations (the project's default
+    # `from __future__ import annotations`, or any forward ref like `Json`/`Literal`) against this
+    # module's globals. A bare-dict exec leaves __module__ == "builtins", where those don't resolve.
+    name = f"_funcd_contract_{_build_seq}"
+    module = types.ModuleType(name)
+    sys.modules[name] = module
+    try:
+        exec(compile(source, "<funcd_function>", "exec"), module.__dict__)  # noqa: S102 - trusted author source, build-time only
+        ns = module.__dict__
+        in_schema = _side_schema(ns, "FuncInput")
+        out_schema = _side_schema(ns, "FuncOutput")
+    finally:
+        sys.modules.pop(name, None)
+
+    # Every side — void included — is compiled to its validator FROM its emitted schema through the
+    # SAME fastjsonschema path (ADR-0090/0060 invariant): {"type": "null"} compiles to a null-only
+    # check, so there is no place where the advertised schema and the enforced validator diverge.
+    baked = [
+        _validator_source(in_schema, "__funcd_validate_input", "i"),
+        _validator_source(out_schema, "__funcd_validate_output", "o"),
+    ]
+
+    runtime = _strip_and_bake(source, "\n".join(baked))
+    return BuildResult(runtime, in_schema, out_schema)
+
+
+def _side_schema(ns: dict[str, Any], marker: str) -> dict[str, Any]:
+    """Resolve one contract side (``FuncInput`` / ``FuncOutput``) to its mandatory JSON Schema
+    (ADR-0090). ``None`` is the explicit void marker → ``{"type": "null"}``; a declared type derives
+    its schema; an **undeclared** side is a build error (the "unchecked" path is gone — the author
+    must declare the type, ``None`` for void)."""
+    if marker not in ns:
+        raise ValueError(
+            f"{marker} is not declared — every function must declare an I/O contract "
+            f"(ADR-0090); use `{marker} = None` for a void side."
+        )
+    value = ns[marker]
+    if value is None:
+        return dict(_VOID_SCHEMA)  # explicit void: {"type": "null"}
+    schema = _schema_of(value)
+    if schema is None:
+        raise ValueError(
+            f"{marker} does not resolve to a JSON Schema — declare a pydantic model, a TypedDict, "
+            f"a discriminated union, `Json`, or `None` for a void side."
+        )
+    return schema
+
+
+def _schema_of(obj: Any) -> dict[str, Any] | None:
+    """Generate the JSON Schema for any contract type — a pydantic ``BaseModel``, a ``TypedDict``
+    (the type-honest ``CloudEvent[FuncInput]`` DX), a discriminated/plain **union** of those, or the
+    ``Json`` (any) form — via a single ``TypeAdapter``, then normalize it to the funcd profile:
+    inline ``$ref``/``$defs`` (the profile forbids ``$ref``), rewrite a tagged ``anyOf`` into the
+    gate's discriminated ``oneOf``, and close every record (pydantic emits them open). Returns None
+    when *obj* yields no schema (e.g. ``None``, the void marker)."""
+    if obj is None:
+        return None
+    try:
+        schema = TypeAdapter(obj).json_schema()
+    except Exception:  # noqa: BLE001 - any un-adaptable type ⇒ "no schema" (treated as unvalidated)
+        return None
+    schema = _inline_refs(schema)
+    _discriminate(schema)
+    return _close_records(schema)
+
+
+def _inline_refs(schema: dict[str, Any]) -> dict[str, Any]:
+    """Replace every ``{"$ref": "#/$defs/Name"}`` with the referenced definition inlined (the profile
+    forbids ``$ref``; pydantic emits one per nested model/union variant), then drop ``$defs``. A
+    reference cycle (a recursive type — forbidden by the profile) is left as-is so the gate rejects
+    it with a clear ``$ref`` error rather than looping here."""
+    defs: dict[str, Any] = {}
+    for key in ("$defs", "definitions"):
+        node = schema.get(key)
+        if isinstance(node, dict):
+            defs.update(node)
+
+    def resolve(node: Any, stack: frozenset[str]) -> Any:
+        if isinstance(node, list):
+            return [resolve(item, stack) for item in node]
+        if not isinstance(node, dict):
+            return node
+        ref = node.get("$ref")
+        if isinstance(ref, str) and ref.startswith("#/") and ref.split("/")[-1] in defs:
+            name = ref.split("/")[-1]
+            if name in stack:
+                return node  # cycle ⇒ recursive type; leave the $ref for the gate to reject
+            target = resolve(defs[name], stack | {name})
+            siblings = {k: resolve(v, stack) for k, v in node.items() if k != "$ref"}
+            return {**target, **siblings} if siblings else target
+        return {k: resolve(v, stack) for k, v in node.items()}
+
+    body = {k: v for k, v in schema.items() if k not in ("$defs", "definitions")}
+    return cast("dict[str, Any]", resolve(body, frozenset()))
+
+
+def _discriminate(node: Any) -> None:
+    """Rewrite every tagged ``anyOf`` into the profile's discriminated ``oneOf`` + ``discriminator``
+    (the gate accepts a union only as a tagged ``oneOf``; a plain ``A | B`` union is ``anyOf``).
+    Also drops pydantic's discriminator ``mapping`` (stale ``$ref`` strings the gate ignores)."""
+    if isinstance(node, list):
+        for item in node:
+            _discriminate(item)
+        return
+    if not isinstance(node, dict):
+        return
+    for value in node.values():
+        _discriminate(value)
+    branches = node.get("anyOf")
+    if isinstance(branches, list):
+        tag = _discriminator_tag(branches)
+        if tag:
+            node["oneOf"] = node.pop("anyOf")
+            node["discriminator"] = {"propertyName": tag}
+    disc = node.get("discriminator")
+    if isinstance(disc, dict):
+        disc.pop("mapping", None)
+
+
+def _discriminator_tag(branches: list[Any]) -> str | None:
+    """The property that discriminates an ``anyOf``'s branches: present + required + single-valued
+    (``const`` or one-element ``enum``) in every branch, with distinct values. Else None."""
+
+    def is_record(b: Any) -> bool:
+        return isinstance(b, dict) and isinstance(b.get("properties"), dict)
+
+    if not branches or not all(is_record(b) for b in branches):
+        return None
+
+    def literal(field: Any) -> tuple[bool, Any]:
+        if isinstance(field, dict):
+            if "const" in field:
+                return True, field["const"]
+            enum = field.get("enum")
+            if isinstance(enum, list) and len(enum) == 1:
+                return True, enum[0]
+        return False, None
+
+    for name in branches[0]["properties"]:
+        values: list[Any] = []
+        ok = True
+        for b in branches:
+            required = b.get("required")
+            single, value = literal(b["properties"].get(name))
+            if not single or not isinstance(required, list) or name not in required:
+                ok = False
+                break
+            values.append(value)
+        if ok and len({repr(v) for v in values}) == len(values):
+            return str(name)
+    return None
+
+
+def _close_records(node: dict[str, Any]) -> dict[str, Any]:
+    """Set ``additionalProperties: false`` on every record (an object with ``properties`` that does
+    not already pin it) — the funcd profile forbids open records, but pydantic emits them open. A
+    typed map (``additionalProperties`` is a schema) and an already-closed record are left as-is.
+    Recurses through ``$defs``, ``properties``, ``items``, ``additionalProperties``, and unions."""
+    for defs in (node.get("$defs"), node.get("definitions")):
+        if isinstance(defs, dict):
+            for sub in defs.values():
+                if isinstance(sub, dict):
+                    _close_records(sub)
+    for sub in (node.get("properties") or {}).values():
+        if isinstance(sub, dict):
+            _close_records(sub)
+    if isinstance(node.get("items"), dict):
+        _close_records(node["items"])
+    if isinstance(node.get("additionalProperties"), dict):
+        _close_records(node["additionalProperties"])
+    for key in ("oneOf", "anyOf", "allOf"):
+        for sub in node.get(key, []):
+            if isinstance(sub, dict):
+                _close_records(sub)
+    if node.get("type") == "object" and "properties" in node and "additionalProperties" not in node:
+        node["additionalProperties"] = False
+    return node
+
+
+def _validator_source(schema: dict[str, Any], export: str, prefix: str) -> str:
+    """fastjsonschema-compile *schema* and wrap it as ``export(d) -> list`` ([] ⇒ valid). The
+    generated functions are AST-renamed with a per-side prefix so baking input AND output never
+    collide on fastjsonschema's fixed ``validate`` name."""
+    tree = ast.parse(fastjsonschema.compile_to_code(schema))
+    names = {n.name for n in tree.body if isinstance(n, ast.FunctionDef)}
+    _Prefixer(names, f"_funcd_{prefix}_").visit(tree)
+    renamed = ast.unparse(ast.fix_missing_locations(tree))
+    wrapper = (
+        f"def {export}(d):\n"
+        f"    try:\n"
+        f"        _funcd_{prefix}_validate(d)\n"
+        f"        return []\n"
+        f"    except JsonSchemaValueException as e:\n"
+        f"        return [str(e)]\n"
+    )
+    return renamed + "\n" + wrapper
+
+
+class _Prefixer(ast.NodeTransformer):
+    """Renames a fixed set of top-level function names (and their references) with a prefix."""
+
+    def __init__(self, names: set[str], prefix: str) -> None:
+        self._names = names
+        self._prefix = prefix
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef:
+        if node.name in self._names:
+            node.name = self._prefix + node.name
+        self.generic_visit(node)
+        return node
+
+    def visit_Name(self, node: ast.Name) -> ast.Name:
+        if node.id in self._names:
+            node.id = self._prefix + node.id
+        return node
+
+
+def _strip_and_bake(source: str, baked: str) -> str:
+    """Remove the pydantic imports + the FuncInput/FuncOutput contract decls from *source*, ensure
+    `from __future__ import annotations` at the top, and inject the baked validators ahead of the
+    handler — producing a runtime artifact a subinterpreter can load with no pydantic."""
+    tree = ast.parse(source)
+    body: list[ast.stmt] = []
+    for i, node in enumerate(tree.body):
+        if isinstance(node, ast.ImportFrom) and node.module == "__future__":
+            continue  # re-added at the very top
+        if _is_pydantic_import(node):
+            continue
+        if isinstance(node, ast.ClassDef) and node.name in _CONTRACT:
+            continue  # contract declaration — build-time only
+        if isinstance(node, ast.Assign) and _targets_contract_only(node):
+            continue  # e.g. `FuncOutput = None` (void marker)
+        if i == 0 and _is_module_docstring(node):
+            continue  # drop the module docstring (a string after __future__ is harmless but pointless)
+        body.append(node)
+
+    future = ast.ImportFrom(module="__future__", names=[ast.alias(name="annotations")], level=0)
+    baked_nodes = ast.parse(baked).body if baked.strip() else []
+    final = ast.Module(body=[future, *baked_nodes, *body], type_ignores=[])
+    return ast.unparse(ast.fix_missing_locations(final))
+
+
+def _is_pydantic_import(node: ast.stmt) -> bool:
+    if isinstance(node, ast.Import):
+        return any(a.name.split(".")[0] == "pydantic" for a in node.names)
+    if isinstance(node, ast.ImportFrom):
+        return (node.module or "").split(".")[0] == "pydantic"
+    return False
+
+
+def _targets_contract_only(node: ast.Assign) -> bool:
+    return all(isinstance(t, ast.Name) and t.id in _CONTRACT for t in node.targets)
+
+
+def _is_module_docstring(node: ast.stmt) -> bool:
+    if not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Constant):
+        return False
+    return isinstance(node.value.value, str)
+
+
+__all__ = ["BuildResult", "build"]