api-mcp-compiler 0.1.0__py3-none-any.whl

api_mcp_compiler/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

api_mcp_compiler/benchmarks.py

@@ -0,0 +1,188 @@
+"""Fetching and verifying third-party benchmark documents.
+
+Benchmark specifications are deliberately not stored in this repository. Using material and
+redistributing it are different acts, and only the second carries an obligation this project
+would have to resolve, so fetching sidesteps the question rather than answering it.
+
+What makes that safe is the digest. A recorded source is verified on every fetch and a
+mismatch is refused, so a result stays reconstructible from a manifest and a trace even though
+the bytes live elsewhere. That is the same discipline the compiler already applies to every
+document it loads.
+
+Nothing here is called during ingestion. Ingestion never reaches the network; fetching is a
+separate step a person runs deliberately.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.error import URLError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from api_mcp_compiler.models import BenchmarkManifest, BenchmarkSource
+
+#: Refuse anything larger. A benchmark specification is a document, not an archive.
+MAX_FETCH_BYTES = 16 * 1024 * 1024
+FETCH_TIMEOUT_SECONDS = 30
+
+
+class BenchmarkFetchError(RuntimeError):
+    """Raised when a source cannot be fetched or does not verify."""
+
+
+class DigestMismatchError(BenchmarkFetchError):
+    """Raised when fetched bytes do not match the digest the manifest recorded.
+
+    This is the failure the whole mechanism exists to produce. A silent acceptance here would
+    make every downstream result unreproducible without anyone noticing.
+    """
+
+
+class _SameHostRedirectHandler(HTTPRedirectHandler):
+    """Follows redirects only within the original host.
+
+    A redirect to another host turns a pinned, reviewed source into an arbitrary one, which is
+    precisely what pinning was meant to prevent.
+    """
+
+    def redirect_request(
+        self,
+        req: Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> Request | None:
+        if urlsplit(newurl).hostname != urlsplit(req.full_url).hostname:
+            raise BenchmarkFetchError(
+                f"refusing a redirect from {req.full_url} to another host at {newurl}"
+            )
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+@dataclass(frozen=True)
+class FetchOutcome:
+    """What happened for one source."""
+
+    source_id: str
+    target: Path
+    digest: str
+    recorded: bool
+    skipped: bool = False
+
+
+def digest_of(payload: bytes) -> str:
+    """Return the prefixed sha256 of fetched bytes."""
+    return f"sha256:{hashlib.sha256(payload).hexdigest()}"
+
+
+def resolve_target(source: BenchmarkSource, root: Path) -> Path:
+    """Resolve where a source is written, refusing anything outside the benchmark directory.
+
+    A manifest is a document a person edits, so a target that escapes the directory has to be
+    refused rather than trusted.
+    """
+    candidate = (root / source.target).resolve()
+    base = root.resolve()
+    if not candidate.is_relative_to(base):
+        raise BenchmarkFetchError(
+            f"source {source.source_id!r} targets {source.target!r}, which resolves outside "
+            f"{base}"
+        )
+    return candidate
+
+
+def download(url: str) -> bytes:
+    """Fetch one document over HTTPS, refusing anything unexpected.
+
+    Bytes are returned rather than written, so a caller can verify before anything reaches the
+    filesystem and a failed verification cannot leave a poisoned file behind.
+    """
+    if urlsplit(url).scheme != "https":
+        raise BenchmarkFetchError(f"refusing to fetch {url!r}: only https is permitted")
+    opener = build_opener(_SameHostRedirectHandler)
+    request = Request(url, headers={"Accept": "application/json, text/plain, */*"})
+    try:
+        with opener.open(request, timeout=FETCH_TIMEOUT_SECONDS) as response:
+            payload = response.read(MAX_FETCH_BYTES + 1)
+    except URLError as error:
+        reason = str(getattr(error, "reason", error))
+        hint = ""
+        if "CERTIFICATE_VERIFY_FAILED" in reason:
+            hint = (
+                " This interpreter has no certificate authority bundle. On a python.org "
+                "build, run its 'Install Certificates.command', or set SSL_CERT_FILE to a "
+                "bundle. Certificate verification is never disabled to work around this."
+            )
+        raise BenchmarkFetchError(f"could not fetch {url}: {reason}.{hint}") from error
+    except OSError as error:
+        raise BenchmarkFetchError(f"could not fetch {url}: {error}") from error
+    if not isinstance(payload, bytes):  # pragma: no cover - urllib always yields bytes
+        raise BenchmarkFetchError(f"{url} did not return bytes")
+    if len(payload) > MAX_FETCH_BYTES:
+        raise BenchmarkFetchError(
+            f"{url} exceeded the {MAX_FETCH_BYTES} byte ceiling for a benchmark document"
+        )
+    return payload
+
+
+def fetch_source(
+    source: BenchmarkSource, root: Path, *, record: bool = False
+) -> tuple[FetchOutcome, BenchmarkSource]:
+    """Fetch one source, verify it, and write it only if it verified.
+
+    With no recorded digest the first fetch is trust-on-first-use and `record` must be set,
+    which keeps the moment a source becomes trusted explicit rather than incidental. Every
+    fetch afterwards is verified.
+    """
+    target = resolve_target(source, root)
+    if source.sha256 and target.is_file() and digest_of(target.read_bytes()) == source.sha256:
+        return (
+            FetchOutcome(source.source_id, target, source.sha256, recorded=False, skipped=True),
+            source,
+        )
+
+    if source.sha256 is None and not record:
+        # Refused before any request. Fetching bytes only to reject them would be pointless
+        # traffic, and it would make trusting a source look like something that happens on
+        # its own rather than a deliberate act.
+        raise BenchmarkFetchError(
+            f"source {source.source_id!r} has no recorded digest. Re-run with --record to "
+            "trust it on first use, once you are satisfied the source is the right one."
+        )
+
+    payload = download(source.url)
+    actual = digest_of(payload)
+
+    if source.sha256 is None:
+        source = source.model_copy(update={"sha256": actual})
+    elif actual != source.sha256:
+        raise DigestMismatchError(
+            f"source {source.source_id!r} fetched from {source.url} has digest {actual}, but "
+            f"the manifest records {source.sha256}. Nothing was written."
+        )
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(payload)
+    return (
+        FetchOutcome(source.source_id, target, actual, recorded=source.sha256 == actual),
+        source,
+    )
+
+
+def load_manifest(path: Path) -> BenchmarkManifest:
+    """Read a benchmark manifest."""
+    return BenchmarkManifest.model_validate(json.loads(path.read_text(encoding="utf-8")))
+
+
+def save_manifest(manifest: BenchmarkManifest, path: Path) -> None:
+    """Write a benchmark manifest as canonical JSON."""
+    from api_mcp_compiler.contracts import canonical_json
+
+    path.write_text(canonical_json(manifest.model_dump(mode="json")), encoding="utf-8")

api_mcp_compiler/cli.py

@@ -0,0 +1,392 @@
+"""Command line interface for the API-to-MCP agent-readiness compiler.
+
+Exposes inspection, baseline planning, tool-surface generation and contract validation.
+No command runs an MCP server, binds to an SDK, or performs network access.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from pathlib import Path
+
+import typer
+
+from api_mcp_compiler.codegen.mcp_server import GENERATED_REQUIREMENTS, emit_server
+from api_mcp_compiler.codegen.soap_server import emit_soap_server
+from api_mcp_compiler.codegen.tools import generate_surface
+from api_mcp_compiler.contracts import (
+    ContractViolation,
+    canonical_json,
+    dump_canonical,
+    validate_ir,
+    validate_tool_plan,
+    validate_tool_surface,
+)
+from api_mcp_compiler.evaluation.harness import run_corpus
+from api_mcp_compiler.ingest.openapi import parse_openapi
+from api_mcp_compiler.ingest.refs import RefPolicy
+from api_mcp_compiler.ingest.wsdl import parse_wsdl
+from api_mcp_compiler.models import (
+    ApiSemanticIR,
+    EvalCorpus,
+    PlannerKind,
+    RiskClass,
+    SourceFormat,
+    ToolPlan,
+)
+from api_mcp_compiler.planning.approval import ApprovalSelectionError, approve
+from api_mcp_compiler.planning.baseline import plan_baseline
+from api_mcp_compiler.planning.overlay import load_overlay, restamp, save_overlay
+from api_mcp_compiler.planning.report import review_report
+from api_mcp_compiler.planning.semantic import plan_semantic
+from api_mcp_compiler.policy.synthesis import synthesize_policy
+from api_mcp_compiler.reporting.conversion_report import write_report
+
+app = typer.Typer(no_args_is_help=True, help=__doc__)
+
+_WSDL_SUFFIXES = {".wsdl", ".xml"}
+
+
+class SourceKind(StrEnum):
+    """How to interpret a source document."""
+
+    AUTO = "auto"
+    OPENAPI = "openapi"
+    WSDL = "wsdl"
+
+
+OVERLAY_HELP = (
+    "Path to a reviewed overlay. Its digest must match the specification, so decisions made "
+    "about other bytes are refused rather than silently applied."
+)
+PLANNER_HELP = "Which planner to use. The baseline exists only for controlled comparison."
+ENFORCE_POLICY_HELP = (
+    "Derive a policy manifest and fail closed on any tool whose policy is unresolved. "
+    "Disabling this shows what would be emitted without governance; it is not a safe mode."
+)
+
+ALLOW_DIR_HELP = (
+    "Directory whose files may be loaded by $ref. Repeatable. Omitted by default, so a "
+    "specification cannot pull in files it was not explicitly pointed at."
+)
+
+
+def _parse(source: Path, kind: SourceKind, allow_dir: list[Path] | None = None) -> ApiSemanticIR:
+    """Dispatch a source document to the matching ingestion adapter."""
+    if kind is SourceKind.AUTO:
+        kind = SourceKind.WSDL if source.suffix.lower() in _WSDL_SUFFIXES else SourceKind.OPENAPI
+    if kind is SourceKind.WSDL:
+        return parse_wsdl(source)
+    return parse_openapi(source, policy=RefPolicy(allowed_directories=tuple(allow_dir or ())))
+
+
+def _plan(ir: ApiSemanticIR, planner: PlannerKind, overlay: Path | None) -> ToolPlan:
+    """Build a plan with the requested planner, applying an overlay when one is given."""
+    if planner is PlannerKind.BASELINE:
+        return plan_baseline(ir)
+    return plan_semantic(ir, load_overlay(overlay) if overlay else None)
+
+
+@app.command()
+def inspect(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+    baseline: bool = typer.Option(True, help="Include the baseline tool plan in the output."),
+) -> None:
+    """Parse a source document and print the normalized IR as canonical JSON."""
+    ir = _parse(source, kind, allow_dir)
+    payload: dict[str, object] = {"ir": ir.model_dump(mode="json")}
+    if baseline:
+        payload["baseline_plan"] = plan_baseline(ir).model_dump(mode="json")
+    typer.echo(canonical_json(payload), nl=False)
+
+
+@app.command()
+def plan(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+    planner: PlannerKind = typer.Option(PlannerKind.SEMANTIC, "--planner", help=PLANNER_HELP),
+    overlay: Path | None = typer.Option(None, "--overlay", help=OVERLAY_HELP),
+) -> None:
+    """Print a tool plan as canonical JSON.
+
+    Every artifact is `proposed` until a reviewer records approval in an overlay, and the
+    emission gate refuses to make a write or destructive tool executable before then.
+    """
+    ir = _parse(source, kind, allow_dir)
+    typer.echo(dump_canonical(_plan(ir, planner, overlay)), nl=False)
+
+
+@app.command()
+def generate(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+    planner: PlannerKind = typer.Option(PlannerKind.SEMANTIC, "--planner", help=PLANNER_HELP),
+    overlay: Path | None = typer.Option(None, "--overlay", help=OVERLAY_HELP),
+    enforce_policy: bool = typer.Option(
+        True, "--enforce-policy/--no-enforce-policy", help=ENFORCE_POLICY_HELP
+    ),
+) -> None:
+    """Generate a tool surface and print it as canonical JSON.
+
+    The surface binds to no MCP SDK and performs no I/O. A tool is emitted executable only
+    when its source operation carries no blocking ambiguity, its risk is classified, and any
+    write, destructive or privileged tool has been approved. Refused tools are still emitted,
+    carrying the reason, so the surface stays auditable.
+    """
+    ir = _parse(source, kind, allow_dir)
+    plan = _plan(ir, planner, overlay)
+    manifest = synthesize_policy(ir, plan) if enforce_policy else None
+    typer.echo(dump_canonical(generate_surface(ir, plan, manifest)), nl=False)
+
+
+@app.command()
+def report(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    out_dir: Path = typer.Option(Path("reports"), "--out-dir", help="Directory for reports."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+    planner: PlannerKind = typer.Option(PlannerKind.SEMANTIC, "--planner", help=PLANNER_HELP),
+    overlay: Path | None = typer.Option(None, "--overlay", help=OVERLAY_HELP),
+) -> None:
+    """Write the conversion report a reviewer reads before approving anything.
+
+    One self-contained HTML file: what was read, what is proposed, what the gate is holding,
+    and what needs a decision. Reports are never overwritten, because a decision made against
+    one set of proposals is not evidence about a different set, so each run writes a file named
+    for the source digest it describes.
+    """
+    ir = _parse(source, kind, allow_dir)
+    plan = _plan(ir, planner, overlay)
+    manifest = synthesize_policy(ir, plan)
+    written = write_report(out_dir, ir, plan, generate_surface(ir, plan, manifest), manifest)
+    typer.echo(f"wrote {written.path}")
+    typer.echo(f"  executable now: {len(written.executable)}")
+    typer.echo(f"  held by the gate: {len(written.blocked)}")
+    if written.awaiting_review:
+        typer.echo(f"  awaiting your approval: {len(written.awaiting_review)}")
+        typer.echo("  approve by class, for example:")
+        typer.echo(f"    api-mcp-compiler approve {source} --risk read --overlay <path>")
+
+
+@app.command("approve")
+def approve_surface(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    overlay: Path = typer.Option(..., "--overlay", help="Overlay to create or extend."),
+    risk: RiskClass | None = typer.Option(
+        None, "--risk", help="Approve every tool of a risk class."
+    ),
+    group: str | None = typer.Option(None, "--group", help="Approve every tool in a group."),
+    name: list[str] = typer.Option([], "--name", help="Approve one named tool. Repeatable."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+) -> None:
+    """Record approval for a class of tools, writing the overlay so nobody hand-edits JSON.
+
+    A selection must name what it covers. There is deliberately no flag that approves a whole
+    surface without saying what class of thing it is.
+    """
+    ir = _parse(source, kind, allow_dir)
+    existing = load_overlay(overlay) if overlay.is_file() else None
+    plan = plan_semantic(ir, existing)
+    try:
+        outcome = approve(plan, overlay=existing, risk=risk, group=group, names=name)
+    except ApprovalSelectionError as error:
+        typer.echo(f"refused: {error}", err=True)
+        raise typer.Exit(code=2) from error
+    save_overlay(outcome.overlay, overlay)
+    typer.echo(f"approved {len(outcome.approved)} artifact(s) in {overlay}")
+    for item in outcome.approved:
+        typer.echo(f"    + {item}")
+    if outcome.already_approved:
+        typer.echo(f"  already approved: {', '.join(outcome.already_approved)}")
+    if outcome.untouched:
+        typer.echo(f"  still awaiting a decision: {', '.join(outcome.untouched)}")
+
+
+@app.command()
+def serve(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    out: Path = typer.Option(..., "--out", help="Where to write the generated server module."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+    planner: PlannerKind = typer.Option(PlannerKind.SEMANTIC, "--planner", help=PLANNER_HELP),
+    overlay: Path | None = typer.Option(None, "--overlay", help=OVERLAY_HELP),
+) -> None:
+    """Emit a runnable MCP server for the approved part of a surface.
+
+    Only tools that cleared the emission gate are registered. Tools the gate withheld are
+    named by a `surface://withheld` resource and are deliberately absent, so a deployment
+    cannot pick up the tools and leave the decision behind. Policy travels with them:
+    confirmation, output ceilings and redaction are written into the server rather than
+    documented beside it.
+
+    The generated module needs `mcp` and `httpx`, which this compiler does not depend on.
+    """
+    ir = _parse(source, kind, allow_dir)
+    plan = _plan(ir, planner, overlay)
+    manifest = synthesize_policy(ir, plan)
+    surface = generate_surface(ir, plan, manifest)
+    # A SOAP service has no routes: every operation is a POST to one endpoint and what
+    # distinguishes them is the envelope, so it needs a different emitter rather than a
+    # branch inside the same one.
+    soap = ir.service.source_format is SourceFormat.WSDL
+    if soap:
+        soap_emitted = emit_soap_server(ir, surface, manifest)
+        generated, registered, withheld = (
+            soap_emitted.source,
+            soap_emitted.registered,
+            soap_emitted.withheld,
+        )
+        upstream = soap_emitted.endpoint
+    else:
+        http_emitted = emit_server(ir, surface, manifest)
+        generated, registered, withheld = (
+            http_emitted.source,
+            http_emitted.registered,
+            http_emitted.withheld,
+        )
+        upstream = http_emitted.base_url
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(generated, encoding="utf-8")
+    typer.echo(f"wrote {out} for {ir.service.service_id} ({'SOAP' if soap else 'HTTP'})")
+    typer.echo(f"  registered {len(registered)}: {', '.join(registered)}")
+    if withheld:
+        typer.echo(f"  withheld {len(withheld)}:")
+        for name, reason in sorted(withheld.items()):
+            typer.echo(f"    {name}: {reason}")
+    typer.echo(f"  upstream {upstream}")
+    typer.echo(f"  run it with: pip install {' '.join(GENERATED_REQUIREMENTS)} && python {out}")
+
+
+@app.command()
+def policy(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+    planner: PlannerKind = typer.Option(PlannerKind.SEMANTIC, "--planner", help=PLANNER_HELP),
+    overlay: Path | None = typer.Option(None, "--overlay", help=OVERLAY_HELP),
+) -> None:
+    """Print the governance manifest for a planned surface as canonical JSON.
+
+    Policy is derived separately from code generation. Anything that cannot be derived is
+    named in `unresolved`, and generation then refuses the tool rather than defaulting it.
+    """
+    ir = _parse(source, kind, allow_dir)
+    typer.echo(dump_canonical(synthesize_policy(ir, _plan(ir, planner, overlay))), nl=False)
+
+
+@app.command()
+def review(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+    overlay: Path | None = typer.Option(None, "--overlay", help=OVERLAY_HELP),
+) -> None:
+    """Print the human review report for the semantic plan.
+
+    This is the artifact the approval gate depends on: every proposed rename, omission,
+    grouping, projection and composite, with its rationale and confidence.
+    """
+    ir = _parse(source, kind, allow_dir)
+    typer.echo(review_report(ir, plan_semantic(ir, load_overlay(overlay) if overlay else None)))
+
+
+@app.command("overlay-restamp")
+def overlay_restamp(
+    source: Path = typer.Argument(..., help="Path to the specification the overlay describes."),
+    overlay: Path = typer.Argument(..., help="Overlay to re-stamp in place."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+) -> None:
+    """Bind an overlay to the current specification revision.
+
+    Run this only after re-reading the decisions against the changed specification. The
+    digest is what stops an approval granted for one revision from applying to another, so
+    re-stamping without reviewing defeats the mechanism it exists to provide.
+    """
+    ir = _parse(source, kind, allow_dir)
+    current = load_overlay(overlay)
+    if current.source_digest == ir.service.source_digest:
+        typer.echo(f"{overlay}: already bound to {ir.service.source_digest}.")
+        return
+    save_overlay(restamp(current, ir.service.source_digest), overlay)
+    typer.echo(
+        f"{overlay}: re-stamped from {current.source_digest} to {ir.service.source_digest}. "
+        "Confirm the recorded decisions still hold."
+    )
+
+
+@app.command()
+def evaluate(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    corpus: Path = typer.Argument(..., help="Path to an evaluation corpus."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+    planner: PlannerKind = typer.Option(PlannerKind.SEMANTIC, "--planner", help=PLANNER_HELP),
+    overlay: Path | None = typer.Option(None, "--overlay", help=OVERLAY_HELP),
+    enforce_policy: bool = typer.Option(
+        True, "--enforce-policy/--no-enforce-policy", help=ENFORCE_POLICY_HELP
+    ),
+) -> None:
+    """Run an evaluation corpus against a generated surface and print the result.
+
+    The only driver available replays the reference solution each task records. It is correct
+    by construction and therefore scores every surface identically, which makes it useful for
+    checking that the harness agrees with itself and useless for comparing surfaces. No
+    output of this command is evidence that one planner outperforms another.
+    """
+    ir = _parse(source, kind, allow_dir)
+    plan = _plan(ir, planner, overlay)
+    manifest = synthesize_policy(ir, plan) if enforce_policy else None
+    loaded = EvalCorpus.model_validate(json.loads(corpus.read_text(encoding="utf-8")))
+    run = run_corpus(loaded, ir, generate_surface(ir, plan, manifest), manifest)
+    typer.echo(dump_canonical(run), nl=False)
+
+
+@app.command()
+def validate(
+    source: Path = typer.Argument(..., help="Path to an OpenAPI 3.x or WSDL 1.1 document."),
+    kind: SourceKind = typer.Option(SourceKind.AUTO, "--kind", help="Override format detection."),
+    allow_dir: list[Path] = typer.Option([], "--allow-dir", help=ALLOW_DIR_HELP),
+) -> None:
+    """Validate the IR and baseline plan against their schemas and report ambiguities.
+
+    Exits non-zero when a contract is violated. Blocking ambiguities are reported but do not
+    fail the command: they are the work queue for later phases, not defects in this one.
+    """
+    ir = _parse(source, kind, allow_dir)
+    baseline = plan_baseline(ir)
+    try:
+        validate_ir(ir.model_dump(mode="json"), label=f"IR for {source}")
+        validate_tool_plan(baseline.model_dump(mode="json"), label=f"baseline plan for {source}")
+        manifest = synthesize_policy(ir, baseline)
+        surface = generate_surface(ir, baseline, manifest)
+        validate_tool_surface(
+            surface.model_dump(mode="json"), label=f"tool surface for {source}"
+        )
+    except ContractViolation as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(code=1) from error
+
+    blocking = ir.blocking_ambiguities
+    typer.echo(
+        f"{source}: {len(ir.operations)} operations, {len(baseline.artifacts)} baseline artifacts, "
+        f"{len(surface.executable_tools)}/{len(surface.tools)} executable, "
+        f"{len(ir.ambiguities)} ambiguities ({len(blocking)} blocking). Contracts valid."
+    )
+    for tool in surface.tools:
+        if tool.blockers:
+            reasons = ", ".join(item.value for item in tool.blockers)
+            typer.echo(f"  DISABLED {tool.name}: {reasons}")
+    for item in ir.ambiguities:
+        marker = "BLOCKING" if item.blocking else "note    "
+        typer.echo(f"  {marker} {item.code} at {item.field}: {item.detail}")
+
+
+if __name__ == "__main__":
+    app()

api_mcp_compiler/codegen/__init__.py

@@ -0,0 +1,6 @@
+"""Generation of transport-independent tool surfaces from an IR and a reviewed plan.
+
+Code generation is deliberately separate from planning and from policy. This package turns
+a plan plus the IR it references into tool descriptors, and refuses executable status to
+anything that has not cleared the safety gate. It binds to no SDK and performs no I/O.
+"""

api_mcp_compiler/codegen/composite.py

@@ -0,0 +1,55 @@
+"""Threading a value from one step of a composite into the next.
+
+A composite exists because one of its steps needs a value the goal cannot supply: an
+identifier that only an earlier call returns. Working out which value, and where it goes, is
+what turns a proposal into something executable.
+
+The derivation is the same one the planner used to propose the pair, shared rather than
+reimplemented, so a composite is never executed on a different rule from the one that
+justified it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from api_mcp_compiler.models import OperationIR
+from api_mcp_compiler.routes import thread_binding
+
+
+@dataclass(frozen=True)
+class ThreadedArgument:
+    """One value carried from an earlier step into a later one."""
+
+    step_index: int
+    argument: str
+    from_step: int
+    response_field: str
+
+
+def composite_threading(operations: list[OperationIR]) -> dict[str, ThreadedArgument]:
+    """Resolve every argument a composite fills for itself, keyed by argument name.
+
+    A single operation threads nothing: there is no earlier step to take a value from.
+    """
+    if len(operations) < 2:
+        return {}
+    threaded: dict[str, ThreadedArgument] = {}
+    for index, writer in enumerate(operations):
+        if index == 0:
+            continue
+        for earlier, reader in enumerate(operations[:index]):
+            binding = thread_binding(reader, writer)
+            if binding is None:
+                continue
+            argument, field = binding
+            threaded.setdefault(
+                argument,
+                ThreadedArgument(
+                    step_index=index,
+                    argument=argument,
+                    from_step=earlier,
+                    response_field=field,
+                ),
+            )
+    return threaded