Feat/api migration engine

PROJECT_PLAN.md

@@ -52,7 +52,7 @@ The primary product wedge is `agentdiff api scan/check/migrate` for Self-Maintai
 - One maintained hosted/disposable sandbox integration.
 - Artifact migration and compatibility tooling.
 - Larger external-state benchmark coverage.
-- **Migration Engine: deterministic AST transforms, coding-agent fallback, clean-room verification (V0–V5), Migration Certificate, GitHub PR delivery**
+- **Migration pipeline completion: real ProofEngine execution for migrations, rollback verification, failure evidence, GitHub PR delivery**
 
 An HTTP API, hosted dashboard, Docker backend, bundled sandbox, universal network blocking, and arbitrary external-state rollback are not implemented.
 
@@ -82,12 +82,15 @@ An HTTP API, hosted dashboard, Docker backend, bundled sandbox, universal networ
 
 ### Self-Maintaining APIs (primary wedge)
 
-1. **API Change Manifest** — structured machine-readable upstream change format (YAML/JSON) for provider deprecations, SDK releases, model shutdowns.
-2. **Deterministic AST Transforms** — for known simple migrations (OpenAI Responses API, Stripe PaymentIntents, etc.); registry extensible by providers.
-3. **Hybrid Migration Engine** — simple → AST transform; complex → coding agent; **all patches untrusted until ProofEngine verifies**.
-4. **Verification Levels (V0–V5)** — syntax/type/build → targeted tests → full repo tests → API contract/mock tests → user-defined integration verification.
-5. **Migration Certificate** — machine-readable artifact: provider change, affected usages, files changed, blast radius, policy result, tests executed, verification level, proof digest, capsule ID, rollback info.
-6. **GitHub PR Automation** — `--open-pr` delivers Migration Certificate in PR body; conflict-safe promotion; no auto-merge.
+1. **API Change Manifest** — structured machine-readable upstream change format (YAML/JSON) for provider deprecations, SDK releases, model shutdowns. *(implemented)*
+2. **Deterministic AST Transforms** — for known simple migrations (OpenAI Responses API, Stripe PaymentIntents, etc.); registry extensible by providers. *(implemented)*
+3. **Migration Engine** — scan → match → plan → transform in private workspace → verify → certificate. *(implemented)*
+4. **Provider Intelligence Layer** — parse changelogs, diff OpenAPI specs, analyze SDK releases, and accept AI suggestions as validated manifest candidates. AI output never touches code directly. *(implemented)*
+5. **Provider Plugin System** — `agentdiff provider install/list`; providers ship `manifests/`, `transforms/`, `tests/`, `metadata.yaml` without core changes. *(implemented)*
+6. **Verification Levels (V0–V5)** — syntax/type/build → targeted tests → full repo tests → API contract/mock tests → user-defined integration verification.
+7. **Migration Certificate** — machine-readable artifact: provider change, affected usages, files changed, blast radius, policy result, tests executed, verification level, proof digest, capsule ID, rollback info. *(implemented)*
+8. **GitHub PR Automation** — `--open-pr` delivers Migration Certificate in PR body; conflict-safe promotion; no auto-merge.
+9. **API Knowledge Graph** — track Repository → API usage → SDK version → migration status; design scalable, no extra database yet.
 
 ### Credibility and distribution
 

README.md

@@ -51,17 +51,59 @@ AgentDiff solves this by making **verified migrations** the default:
 
 The coding agent is probabilistic. AgentDiff is the deterministic verifier that decides whether the result is trustworthy.
 
-## Self-Maintaining APIs (MVP)
+## Self-Maintaining APIs
 
-AgentDiff analyzes Python AST to detect third-party API usages (starting with **OpenAI** and **Stripe**), matches usages against known breaking changes, and calculates migration blast radius and test proof requirements:
+AgentDiff turns API changes into verified migrations. The pipeline is:
+
+**Detect → Plan → Execute → Verify → Certify → Deliver**
 
 ```bash
 # Scan repository for all external API calls
 agentdiff api scan --root .
 
 # Check for breaking changes, calculate impact, and report remediation
 agentdiff api check --root . --fail-on high
+
+# Generate + verify a migration in a private workspace, emit a certificate
+agentdiff api migrate --provider openai --change chat_to_responses
+
+# Turn upstream signals into validated manifest candidates
+agentdiff api intel --provider openai --changelog CHANGELOG.md
+
+# Install provider migration plugins
+agentdiff provider install stripe ./providers/stripe
+agentdiff provider list
+```
+
+### Provider Intelligence Layer
+
+AgentDiff can ingest upstream signals and produce validated `APIChangeManifest`
+candidates — **suggestion only, never applied directly**:
+
+- `--changelog` — parse markdown changelogs for removals/deprecations/renames
+- `--openapi-before/--openapi-after` — diff two OpenAPI specs for breaking changes
+- `--release` — analyze SDK release notes
+- AI-assisted suggestions are accepted as candidates that must still pass
+  deterministic validation before they can drive a migration
+
+### Provider Plugin System
+
+Providers and community members ship migrations without touching core code:
+
 ```
+providers/<name>/
+    metadata.yaml     # name, library, version
+    manifests/        # *.yaml APIChangeManifest files
+    transforms/       # python modules registering AST transforms
+    tests/            # optional plugin tests
+```
+
+### Trust model
+
+The coding agent (or AST transform) generates the migration. AgentDiff decides
+whether it is trustworthy — deterministic policy, blast radius, clean-room proof,
+and a MigrationCertificate recording exactly what was verified. **The AI is
+probabilistic; the trust decision is deterministic.**
 
 ## Zero-Touch Trust Engine (Foundation)
 
@@ -161,6 +203,9 @@ There is no hosted dashboard or hosted service: the sidecar is a local daemon, a
 | `agentdiff workspace status/warm/prune` | Trusted warm workspace snapshots |
 | `agentdiff policy init/validate/explain` | Create and inspect versioned policy |
 | `agentdiff api scan` / `check` | Self-maintaining API usage scanner and breaking change checker |
+| `agentdiff api migrate` | Generate and verify an API migration in a private workspace |
+| `agentdiff api intel` | Analyze changelog/OpenAPI/release signals into manifest candidates |
+| `agentdiff provider list` / `install` | Manage provider migration plugins |
 | `agentdiff cortex ...` | Open the optional evidence-memory, skill-card, and provider tool namespace |
 
 The earlier `snapshot`, `diff`, and `eval` implementation remains importable for compatibility testing but is no longer exposed as a public CLI path.

src/agentdiff/api/__init__.py

@@ -1,5 +1,17 @@
 """Self-Maintaining APIs: AST scanning, breaking change matching, and migration impact."""
 
+from agentdiff.api.intel import (
+    ChangelogChange,
+    ChangelogParser,
+    IntelArtifact,
+    ManifestCandidate,
+    OpenAPIBreakingChange,
+    OpenAPIDiffAnalyzer,
+    ProviderIntelEngine,
+    SDKReleaseAnalyzer,
+    SDKReleaseChange,
+)
+
 from agentdiff.api.manifest import (
     AffectedSymbols,
     APIChangeManifest,
@@ -30,6 +42,13 @@
     VerificationLevel,
     assess_migration_confidence,
 )
+from agentdiff.api.plugins import (
+    ProviderPlugin,
+    discover_plugins,
+    install_plugin,
+    list_plugins,
+    load_plugin,
+)
 from agentdiff.api.providers import (
     APIProvider,
     OpenAIProvider,
@@ -63,6 +82,10 @@
     "AffectedSymbols",
     "ChangeSeverity",
     "ChangeType",
+    "ChangelogChange",
+    "ChangelogParser",
+    "IntelArtifact",
+    "ManifestCandidate",
     "ManifestSource",
     "MatchedChange",
     "MigrationAssessment",
@@ -79,19 +102,34 @@
     "OpenAIChatToResponsesTransform",
     "OpenAILegacyChatCompletionTransform",
     "OpenAIProvider",
+    "OpenAPIBreakingChange",
+    "OpenAPIDiffAnalyzer",
+    "ProviderIntelEngine",
+    "ProviderPlugin",
+    "ReplacementSymbols",
+    "SDKReleaseAnalyzer",
+    "SDKReleaseChange",
     "ReplacementSymbols",
     "SDKVersionInfo",
     "SourceType",
     "StripeProvider",
     "VerificationLevel",
     "assess_migration_confidence",
     "detect_installed_sdk_versions",
+    "discover_plugins",
     "get_all_providers",
     "get_builtin_manifest",
     "get_provider",
     "get_providers_for_selection",
     "get_transform",
     "get_transforms_for_usage",
+    "install_plugin",
+    "is_version_affected",
+    "list_builtin_manifests",
+    "list_plugins",
+    "list_providers",
+    "list_transforms",
+    "load_plugin",
     "is_version_affected",
     "list_builtin_manifests",
     "list_providers",

src/agentdiff/api/certificate.py

@@ -0,0 +1,73 @@
+"""Migration certificate output and storage."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from agentdiff.api.models import MigrationCertificate
+
+CERTIFICATE_DIR = ".agentdiff/certificates"
+
+
+def write_certificate(certificate: "MigrationCertificate", root: str | Path) -> Path:
+    """Write certificate to .agentdiff/certificates/ directory."""
+    root_path = Path(root).expanduser().resolve(strict=True)
+    cert_dir = root_path / CERTIFICATE_DIR
+    cert_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+
+    filename = f"{certificate.certificate_id}.json"
+    cert_path = cert_dir / filename
+
+    data = certificate.to_dict()
+    data["schema_version"] = 1
+    data["written_at"] = datetime.now(timezone.utc).isoformat()
+
+    cert_path.write_text(
+        json.dumps(data, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+    return cert_path
+
+
+def write_certificate_legacy(certificate: "MigrationCertificate", path: str | Path) -> Path:
+    """Write certificate to a specific path."""
+    path = Path(path).expanduser().resolve()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+
+    data = certificate.to_dict()
+    data["schema_version"] = 1
+    data["written_at"] = datetime.now(timezone.utc).isoformat()
+
+    path.write_text(
+        json.dumps(data, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+    return path
+
+
+def read_certificate(path: str | Path) -> dict[str, Any]:
+    """Read a certificate from disk."""
+    path = Path(path).expanduser().resolve()
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def list_certificates(root: str | Path) -> list[Path]:
+    """List all certificates in the repository."""
+    root_path = Path(root).expanduser().resolve(strict=True)
+    cert_dir = root_path / CERTIFICATE_DIR
+    if not cert_dir.exists():
+        return []
+    return sorted(cert_dir.glob("*.json"))
+
+
+def get_latest_certificate(root: str | Path, provider: str, change_id: str) -> Path | None:
+    """Get the most recent certificate for a provider/change."""
+    certs = list_certificates(root)
+    matching = [c for c in certs if provider in c.name and change_id in c.name]
+    return matching[-1] if matching else None

src/agentdiff/api/intel/__init__.py

@@ -0,0 +1,28 @@
+"""Provider Intelligence Layer.
+
+Turns upstream provider signals (changelogs, OpenAPI diffs, SDK releases)
+into validated APIChangeManifest candidates. AI-assisted generation is
+suggestion-only: the output is a manifest candidate that still requires
+deterministic validation before it can drive migrations.
+"""
+
+from agentdiff.api.intel.changelog import ChangelogChange, ChangelogParser
+from agentdiff.api.intel.engine import (
+    IntelArtifact,
+    ManifestCandidate,
+    ProviderIntelEngine,
+)
+from agentdiff.api.intel.openapi import OpenAPIBreakingChange, OpenAPIDiffAnalyzer
+from agentdiff.api.intel.release import SDKReleaseAnalyzer, SDKReleaseChange
+
+__all__ = [
+    "ChangelogChange",
+    "ChangelogParser",
+    "IntelArtifact",
+    "ManifestCandidate",
+    "OpenAPIBreakingChange",
+    "OpenAPIDiffAnalyzer",
+    "ProviderIntelEngine",
+    "SDKReleaseAnalyzer",
+    "SDKReleaseChange",
+]