{
  "schema_version": "1.0.0",
  "model_id": "alphaswarm-portable-orchestration-v1",
  "title": "AlphaSwarm portable Dagster and Prefect orchestration",
  "generated_on": "2026-07-15",
  "status": "rollout-target",
  "description": "Renderer-neutral architecture model for documentation exports and the hosted orchestration graph. Coordinates are deliberately absent; renderers own layout while stable IDs, groups, relationships, and source provenance remain authoritative.",
  "sources": [
    {"id": "src-context", "kind": "code", "path": "alphaswarm_core/src/alphaswarm_core/execution/context.py"},
    {"id": "src-contracts", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/contracts.py"},
    {"id": "src-adapter", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/adapter.py"},
    {"id": "src-dagster-adapter", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/dagster/adapter.py"},
    {"id": "src-dagster-graphql", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/dagster/graphql.py"},
    {"id": "src-prefect-adapter", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/adapter.py"},
    {"id": "src-prefect-client", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/client.py"},
    {"id": "src-prefect-worker", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/worker.py"},
    {"id": "src-worker-submission", "kind": "code", "path": "alphaswarm_worker/src/alphaswarm_worker/submission.py"},
    {"id": "src-control-plane", "kind": "code", "path": "alphaswarm/alphaswarm/orchestration/control_plane.py"},
    {"id": "src-repository", "kind": "code", "path": "alphaswarm/alphaswarm/orchestration/repository.py"},
    {"id": "src-models", "kind": "code", "path": "alphaswarm/alphaswarm/persistence/models_orchestration.py"},
    {"id": "src-migration", "kind": "code", "path": "alphaswarm/alembic/versions/0123_portable_orchestration_ledger.py"},
    {"id": "src-api", "kind": "code", "path": "alphaswarm/alphaswarm/api/routes/orchestration.py"},
    {"id": "src-compatibility", "kind": "code", "path": "alphaswarm/alphaswarm/orchestration/compatibility.py"},
    {"id": "src-config", "kind": "code", "path": "alphaswarm_config/src/alphaswarm_config/models/orchestration.py"},
    {"id": "src-compose", "kind": "manifest", "path": "alphaswarm_platform/deployments/compose/docker-compose.orchestration.yml"},
    {"id": "src-prefect-k8s", "kind": "manifest", "path": "alphaswarm_platform/deployments/kubernetes/mlops/prefect/"},
    {"id": "src-dagster-k8s", "kind": "manifest", "path": "alphaswarm_platform/deployments/kubernetes/mlops/dagster/"},
    {"id": "src-session-runtime-k8s", "kind": "manifest", "path": "alphaswarm_platform/deployments/kubernetes/mlops/session-runtime/"},
    {"id": "src-airbyte", "kind": "code", "path": "alphaswarm/alphaswarm/data/airbyte/orchestrator.py"},
    {"id": "src-dbt", "kind": "code", "path": "alphaswarm/alphaswarm/dagster/assets/dbt_assets.py"},
    {"id": "src-iceberg", "kind": "code", "path": "alphaswarm/alphaswarm/data/iceberg_catalog.py"},
    {"id": "src-polaris", "kind": "code", "path": "alphaswarm/alphaswarm/services/polaris_client.py"},
    {"id": "src-datahub", "kind": "code", "path": "alphaswarm/alphaswarm/data/datahub/emitter.py"},
    {"id": "src-dagster-docs", "kind": "external", "path": "https://docs.dagster.io/"},
    {"id": "src-prefect-docs", "kind": "external", "path": "https://docs.prefect.io/v3/advanced"},
    {"id": "src-session-contracts", "kind": "code", "path": "alphaswarm_core/src/alphaswarm_core/execution/session.py"},
    {"id": "src-session-coordinator", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/session_resources.py"},
    {"id": "src-session-http-provider", "kind": "code", "path": "alphaswarm_orchestration/src/alphaswarm_orchestration/http_session_provider.py"},
    {"id": "src-session-control", "kind": "code", "path": "alphaswarm/alphaswarm/orchestration/session_control.py"},
    {"id": "src-session-repository", "kind": "code", "path": "alphaswarm/alphaswarm/orchestration/session_resource_repository.py"},
    {"id": "src-session-operations", "kind": "code", "path": "alphaswarm/alphaswarm/orchestration/session_operation_repository.py"},
    {"id": "src-session-wiring", "kind": "code", "path": "alphaswarm/alphaswarm/orchestration/wiring.py"},
    {"id": "src-session-models", "kind": "code", "path": "alphaswarm/alphaswarm/persistence/models_session_execution.py"},
    {"id": "src-controller-session-api", "kind": "code", "path": "alphaswarm_controller/src/alphaswarm_controller/api/routers/session_resources.py"},
    {"id": "src-session-provider", "kind": "code", "path": "alphaswarm_controller/src/alphaswarm_controller/providers/session_resources.py"},
    {"id": "src-worker-context", "kind": "code", "path": "alphaswarm_worker/src/alphaswarm_worker/execution/context.py"},
    {"id": "src-worker-remote", "kind": "code", "path": "alphaswarm_worker/src/alphaswarm_worker/execution/remote.py"},
    {"id": "src-session-migration", "kind": "code", "path": "alphaswarm/alembic/versions/0130_session_distributed_execution.py"},
    {"id": "src-session-operation-migration", "kind": "code", "path": "alphaswarm/alembic/versions/0131_session_resource_operations.py"}
  ],
  "groups": [
    {"id": "grp-people", "label": "People and clients", "kind": "actor-boundary"},
    {"id": "grp-gateway", "label": "AlphaSwarm authorized control plane", "kind": "trust-boundary"},
    {"id": "grp-native", "label": "Internal native control planes", "kind": "trust-boundary"},
    {"id": "grp-controller", "label": "Authenticated controller infrastructure boundary", "kind": "trust-boundary"},
    {"id": "grp-execution", "label": "Execution plane", "kind": "runtime-boundary"},
    {"id": "grp-data", "label": "Data and metadata plane", "kind": "data-boundary"},
    {"id": "grp-lifecycle", "label": "Portable run lifecycle", "kind": "state-model"},
    {"id": "grp-ledger", "label": "Normalized orchestration ledger", "kind": "schema-boundary"},
    {"id": "grp-session-ledger", "label": "Durable session-execution projection", "kind": "schema-boundary"},
    {"id": "grp-session-lifecycle", "label": "Session resource lifecycle", "kind": "state-model"}
  ],
  "nodes": [
    {"id": "operator", "label": "Operator", "kind": "person", "group_id": "grp-people", "source_refs": ["src-api"]},
    {"id": "hosted-ui", "label": "Hosted orchestration workspace", "kind": "web-application", "group_id": "grp-people", "source_refs": ["src-api"]},
    {"id": "cli-mcp", "label": "CLI and DataMCP clients", "kind": "client", "group_id": "grp-people", "source_refs": ["src-api"]},
    {"id": "gateway-api", "label": "AlphaSwarm gateway / orchestration API", "kind": "api", "group_id": "grp-gateway", "source_refs": ["src-api"]},
    {"id": "control-plane", "label": "OrchestrationControlPlane", "kind": "application-service", "group_id": "grp-gateway", "source_refs": ["src-control-plane"]},
    {"id": "portable-package", "label": "alphaswarm_orchestration", "kind": "library", "group_id": "grp-gateway", "source_refs": ["src-contracts", "src-adapter"]},
    {"id": "execution-context", "label": "ExecutionContextV1 envelope", "kind": "security-contract", "group_id": "grp-gateway", "source_refs": ["src-context"]},
    {"id": "normalized-ledger", "label": "Normalized orchestration ledger", "kind": "database", "group_id": "grp-gateway", "source_refs": ["src-models", "src-migration"]},
    {"id": "minio", "label": "MinIO raw native payloads and artifacts", "kind": "object-store", "group_id": "grp-data", "source_refs": ["src-models", "src-compose"]},
    {"id": "dagster-webserver", "label": "Dagster webserver / GraphQL", "kind": "control-plane", "group_id": "grp-native", "source_refs": ["src-dagster-graphql", "src-dagster-k8s"]},
    {"id": "dagster-daemon", "label": "Dagster daemon", "kind": "scheduler", "group_id": "grp-native", "source_refs": ["src-dagster-k8s"]},
    {"id": "dagster-code-location", "label": "Dagster code location", "kind": "runtime", "group_id": "grp-native", "source_refs": ["src-dagster-adapter", "src-dagster-k8s"]},
    {"id": "dagster-db", "label": "Dagster native PostgreSQL", "kind": "database", "group_id": "grp-native", "source_refs": ["src-compose", "src-dagster-k8s"]},
    {"id": "prefect-api", "label": "Prefect API / internal UI", "kind": "control-plane", "group_id": "grp-native", "source_refs": ["src-prefect-client", "src-prefect-k8s"]},
    {"id": "prefect-background", "label": "Prefect background services", "kind": "scheduler", "group_id": "grp-native", "source_refs": ["src-prefect-k8s"]},
    {"id": "prefect-worker", "label": "AlphaSwarm Kubernetes worker", "kind": "worker", "group_id": "grp-native", "source_refs": ["src-prefect-worker", "src-prefect-k8s"]},
    {"id": "prefect-db", "label": "Prefect native PostgreSQL", "kind": "database", "group_id": "grp-native", "source_refs": ["src-prefect-k8s"]},
    {"id": "redis", "label": "Prefect coordination Redis", "kind": "database", "group_id": "grp-native", "source_refs": ["src-compose", "src-prefect-k8s"]},
    {"id": "kubernetes", "label": "Kubernetes jobs and pods", "kind": "compute-platform", "group_id": "grp-execution", "source_refs": ["src-prefect-worker", "src-dagster-k8s"]},
    {"id": "worker-plane", "label": "alphaswarm_worker submission plane", "kind": "execution-service", "group_id": "grp-execution", "source_refs": ["src-worker-submission"]},
    {"id": "workflow-runtime", "label": "agents.WorkflowRuntime", "kind": "semantic-runtime", "group_id": "grp-execution", "source_refs": ["src-contracts"]},
    {"id": "celery", "label": "Celery compatibility transport", "kind": "legacy-runtime", "group_id": "grp-execution", "source_refs": ["src-compatibility"]},
    {"id": "airbyte", "label": "Airbyte", "kind": "data-ingestion", "group_id": "grp-data", "source_refs": ["src-airbyte"]},
    {"id": "dbt", "label": "dbt", "kind": "data-transform", "group_id": "grp-data", "source_refs": ["src-dbt"]},
    {"id": "iceberg", "label": "Apache Iceberg", "kind": "data-lake", "group_id": "grp-data", "source_refs": ["src-iceberg"]},
    {"id": "polaris", "label": "Apache Polaris catalog", "kind": "catalog", "group_id": "grp-data", "source_refs": ["src-polaris"]},
    {"id": "datahub", "label": "DataHub metadata graph", "kind": "metadata-catalog", "group_id": "grp-data", "source_refs": ["src-datahub"]},
    {"id": "otel", "label": "OpenTelemetry observability", "kind": "observability", "group_id": "grp-data", "source_refs": ["src-compose", "src-prefect-k8s", "src-dagster-k8s"]},
    {"id": "legacy-workflows", "label": "/workflows and stable task-name facade", "kind": "compatibility-api", "group_id": "grp-gateway", "source_refs": ["src-compatibility", "src-api"]},
    {"id": "scheduler-owner", "label": "Single active schedule owner", "kind": "invariant", "group_id": "grp-gateway", "source_refs": ["src-contracts", "src-models"]},
    {"id": "state-scheduled", "label": "SCHEDULED", "kind": "state", "group_id": "grp-lifecycle", "source_refs": ["src-contracts"]},
    {"id": "state-pending", "label": "PENDING", "kind": "state", "group_id": "grp-lifecycle", "source_refs": ["src-contracts"]},
    {"id": "state-running", "label": "RUNNING", "kind": "state", "group_id": "grp-lifecycle", "source_refs": ["src-contracts"]},
    {"id": "state-succeeded", "label": "SUCCEEDED", "kind": "state", "group_id": "grp-lifecycle", "source_refs": ["src-contracts"]},
    {"id": "state-failed", "label": "FAILED", "kind": "state", "group_id": "grp-lifecycle", "source_refs": ["src-contracts"]},
    {"id": "state-cancelled", "label": "CANCELLED", "kind": "state", "group_id": "grp-lifecycle", "source_refs": ["src-contracts"]},
    {"id": "state-crashed", "label": "CRASHED", "kind": "state", "group_id": "grp-lifecycle", "source_refs": ["src-contracts"]},
    {"id": "orchestration-definitions", "label": "orchestration_definitions", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-definition-versions", "label": "orchestration_definition_versions", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-engine-registrations", "label": "orchestration_engine_registrations", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-trigger-bindings", "label": "orchestration_trigger_bindings", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-runs", "label": "orchestration_runs", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-run-attempts", "label": "orchestration_run_attempts", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-events", "label": "orchestration_events", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-artifacts", "label": "orchestration_artifacts", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-engine-bindings", "label": "orchestration_engine_bindings", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "orchestration-reconciliation-cursors", "label": "orchestration_reconciliation_cursors", "kind": "table", "group_id": "grp-ledger", "source_refs": ["src-models", "src-migration"]},
    {"id": "session-idempotency", "label": "Durable session operation outcomes", "kind": "idempotency-store", "group_id": "grp-gateway", "source_refs": ["src-session-operations", "src-session-operation-migration"]},
    {"id": "session-manager", "label": "Embedded durable session resource manager", "kind": "application-service", "group_id": "grp-gateway", "source_refs": ["src-session-wiring", "src-session-control", "src-session-repository"]},
    {"id": "session-coordinator", "label": "SessionResourceCoordinator", "kind": "application-service", "group_id": "grp-gateway", "source_refs": ["src-session-coordinator"]},
    {"id": "session-repository", "label": "Forced-RLS session resource repository", "kind": "database", "group_id": "grp-gateway", "source_refs": ["src-session-repository", "src-session-models", "src-session-migration"]},
    {"id": "session-http-provider", "label": "HttpSessionResourceProvider", "kind": "infrastructure-port", "group_id": "grp-gateway", "source_refs": ["src-session-http-provider"]},
    {"id": "controller-session-api", "label": "Authenticated session lifecycle API", "kind": "internal-api", "group_id": "grp-controller", "source_refs": ["src-controller-session-api"]},
    {"id": "session-provider", "label": "KubernetesSessionResourceProvider", "kind": "infrastructure-adapter", "group_id": "grp-controller", "source_refs": ["src-session-provider"]},
    {"id": "distributed-resource", "label": "RayCluster / DaskCluster / SparkConnect", "kind": "compute-resource", "group_id": "grp-execution", "source_refs": ["src-session-provider"]},
    {"id": "session-runtime-identity", "label": "alphaswarm-session-runtime service account", "kind": "runtime-identity", "group_id": "grp-execution", "source_refs": ["src-session-runtime-k8s"]},
    {"id": "remote-worker", "label": "Authenticated remote engine process", "kind": "execution-runtime", "group_id": "grp-execution", "source_refs": ["src-worker-context", "src-worker-remote"]},
    {"id": "execution-sessions", "label": "execution_sessions", "kind": "table", "group_id": "grp-session-ledger", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "session-resources", "label": "session_resources", "kind": "table", "group_id": "grp-session-ledger", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "session-resource-reservations", "label": "session_resource_reservations", "kind": "table", "group_id": "grp-session-ledger", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "session-resource-leases", "label": "session_resource_leases", "kind": "table", "group_id": "grp-session-ledger", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "session-resource-consumers", "label": "session_resource_consumers", "kind": "table", "group_id": "grp-session-ledger", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "session-resource-events", "label": "session_resource_events", "kind": "table", "group_id": "grp-session-ledger", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "session-resource-operations", "label": "session_resource_operations", "kind": "table", "group_id": "grp-session-ledger", "source_refs": ["src-session-models", "src-session-operation-migration"]},
    {"id": "session-cache-entries", "label": "session_cache_entries", "kind": "table", "group_id": "grp-session-ledger", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "resource-requested", "label": "REQUESTED", "kind": "state", "group_id": "grp-session-lifecycle", "source_refs": ["src-session-contracts"]},
    {"id": "resource-provisioning", "label": "PROVISIONING", "kind": "state", "group_id": "grp-session-lifecycle", "source_refs": ["src-session-contracts", "src-session-coordinator"]},
    {"id": "resource-ready", "label": "READY", "kind": "state", "group_id": "grp-session-lifecycle", "source_refs": ["src-session-contracts", "src-session-coordinator"]},
    {"id": "resource-degraded", "label": "DEGRADED", "kind": "state", "group_id": "grp-session-lifecycle", "source_refs": ["src-session-contracts"]},
    {"id": "resource-releasing", "label": "RELEASING", "kind": "state", "group_id": "grp-session-lifecycle", "source_refs": ["src-session-contracts", "src-session-provider"]},
    {"id": "resource-released", "label": "RELEASED", "kind": "state", "group_id": "grp-session-lifecycle", "source_refs": ["src-session-contracts"]},
    {"id": "resource-failed", "label": "FAILED", "kind": "state", "group_id": "grp-session-lifecycle", "source_refs": ["src-session-contracts"]},
    {"id": "resource-expired", "label": "EXPIRED", "kind": "state", "group_id": "grp-session-lifecycle", "source_refs": ["src-session-contracts"]}
  ],
  "edges": [
    {"id": "edge-ui-api", "source": "hosted-ui", "target": "gateway-api", "label": "uses authenticated REST and SSE", "kind": "request", "source_refs": ["src-api"]},
    {"id": "edge-cli-api", "source": "cli-mcp", "target": "gateway-api", "label": "uses scoped orchestration API", "kind": "request", "source_refs": ["src-api"]},
    {"id": "edge-api-control", "source": "gateway-api", "target": "control-plane", "label": "authorizes and commands", "kind": "call", "source_refs": ["src-api", "src-control-plane"]},
    {"id": "edge-control-portable", "source": "control-plane", "target": "portable-package", "label": "validates, compiles, and dispatches", "kind": "call", "source_refs": ["src-control-plane", "src-adapter"]},
    {"id": "edge-control-context", "source": "control-plane", "target": "execution-context", "label": "verifies signed envelope", "kind": "security", "source_refs": ["src-control-plane", "src-context"]},
    {"id": "edge-control-ledger", "source": "control-plane", "target": "normalized-ledger", "label": "projects normalized metadata", "kind": "write", "source_refs": ["src-control-plane", "src-repository"]},
    {"id": "edge-control-minio", "source": "control-plane", "target": "minio", "label": "externalizes large native payloads", "kind": "write", "source_refs": ["src-contracts", "src-models"]},
    {"id": "edge-portable-dagster", "source": "portable-package", "target": "dagster-webserver", "label": "uses version-gated public GraphQL and client APIs", "kind": "adapter", "source_refs": ["src-dagster-adapter", "src-dagster-graphql"]},
    {"id": "edge-portable-prefect", "source": "portable-package", "target": "prefect-api", "label": "uses PrefectClient", "kind": "adapter", "source_refs": ["src-prefect-adapter", "src-prefect-client"]},
    {"id": "edge-dagster-code", "source": "dagster-webserver", "target": "dagster-code-location", "label": "loads jobs, assets, schedules, and sensors", "kind": "control", "source_refs": ["src-dagster-k8s", "src-dagster-adapter"]},
    {"id": "edge-dagster-db", "source": "dagster-webserver", "target": "dagster-db", "label": "owns native run and event metadata", "kind": "native-storage", "source_refs": ["src-compose", "src-dagster-k8s"]},
    {"id": "edge-dagster-daemon", "source": "dagster-daemon", "target": "dagster-webserver", "label": "evaluates native automation", "kind": "control", "source_refs": ["src-dagster-k8s"]},
    {"id": "edge-prefect-background", "source": "prefect-background", "target": "prefect-api", "label": "runs scheduler and background services", "kind": "control", "source_refs": ["src-prefect-k8s"]},
    {"id": "edge-prefect-worker", "source": "prefect-worker", "target": "prefect-api", "label": "polls environment and workload queues", "kind": "control", "source_refs": ["src-prefect-worker", "src-prefect-k8s"]},
    {"id": "edge-prefect-db", "source": "prefect-api", "target": "prefect-db", "label": "owns native flow, state, log, and artifact metadata", "kind": "native-storage", "source_refs": ["src-prefect-k8s"]},
    {"id": "edge-prefect-redis", "source": "prefect-api", "target": "redis", "label": "coordinates events, leases, and messaging", "kind": "coordination", "source_refs": ["src-compose", "src-prefect-k8s"]},
    {"id": "edge-prefect-kubernetes", "source": "prefect-worker", "target": "kubernetes", "label": "creates context-labeled flow-run jobs", "kind": "execution", "source_refs": ["src-prefect-worker"]},
    {"id": "edge-dagster-worker", "source": "dagster-code-location", "target": "worker-plane", "label": "submits heavy WorkRequest operations", "kind": "execution", "source_refs": ["src-worker-submission", "src-dagster-adapter"]},
    {"id": "edge-prefect-worker-plane", "source": "kubernetes", "target": "worker-plane", "label": "submits heavy WorkRequest operations", "kind": "execution", "source_refs": ["src-worker-submission", "src-prefect-worker"]},
    {"id": "edge-workflow-runtime", "source": "portable-package", "target": "workflow-runtime", "label": "wraps agent workflow semantics", "kind": "execution", "source_refs": ["src-contracts"]},
    {"id": "edge-celery-compat", "source": "legacy-workflows", "target": "celery", "label": "keeps legacy transport when flags are off", "kind": "compatibility", "source_refs": ["src-compatibility"]},
    {"id": "edge-legacy-api", "source": "legacy-workflows", "target": "gateway-api", "label": "delegates through normalized runs when enabled", "kind": "compatibility", "source_refs": ["src-compatibility", "src-api"]},
    {"id": "edge-schedule-celery", "source": "scheduler-owner", "target": "celery", "label": "owns legacy schedule before cutover", "kind": "ownership", "source_refs": ["src-compatibility"]},
    {"id": "edge-schedule-engine", "source": "scheduler-owner", "target": "portable-package", "label": "owns exactly one native engine trigger after cutover", "kind": "ownership", "source_refs": ["src-contracts", "src-models"]},
    {"id": "edge-engine-events", "source": "dagster-webserver", "target": "control-plane", "label": "reconciles runs, events, and artifacts", "kind": "projection", "source_refs": ["src-dagster-adapter", "src-control-plane"]},
    {"id": "edge-prefect-events", "source": "prefect-api", "target": "control-plane", "label": "reconciles runs, events, logs, and artifacts", "kind": "projection", "source_refs": ["src-prefect-adapter", "src-control-plane"]},
    {"id": "edge-context-dagster", "source": "execution-context", "target": "dagster-code-location", "label": "passes reference, digest, config, tags, and Pipes metadata", "kind": "context", "source_refs": ["src-context", "src-dagster-adapter"]},
    {"id": "edge-context-prefect", "source": "execution-context", "target": "prefect-worker", "label": "passes hidden flow parameters, labels, env, and OTel carrier", "kind": "context", "source_refs": ["src-context", "src-prefect-worker"]},
    {"id": "edge-context-worker", "source": "execution-context", "target": "worker-plane", "label": "links identity and trace without granting authorization", "kind": "context", "source_refs": ["src-context", "src-worker-submission"]},
    {"id": "edge-airbyte-iceberg", "source": "airbyte", "target": "iceberg", "label": "lands source data", "kind": "data", "source_refs": ["src-airbyte", "src-iceberg"]},
    {"id": "edge-airbyte-dagster", "source": "airbyte", "target": "dagster-webserver", "label": "emits sync and asset signals", "kind": "event", "source_refs": ["src-airbyte", "src-dagster-adapter"]},
    {"id": "edge-dbt-iceberg", "source": "dbt", "target": "iceberg", "label": "transforms governed tables", "kind": "data", "source_refs": ["src-dbt", "src-iceberg"]},
    {"id": "edge-dagster-dbt", "source": "dagster-code-location", "target": "dbt", "label": "materializes dbt assets", "kind": "control", "source_refs": ["src-dbt", "src-dagster-adapter"]},
    {"id": "edge-iceberg-polaris", "source": "iceberg", "target": "polaris", "label": "registers namespaces and tables", "kind": "catalog", "source_refs": ["src-iceberg", "src-polaris"]},
    {"id": "edge-datahub-airbyte", "source": "airbyte", "target": "datahub", "label": "publishes ingestion lineage", "kind": "metadata", "source_refs": ["src-airbyte", "src-datahub"]},
    {"id": "edge-datahub-dbt", "source": "dbt", "target": "datahub", "label": "publishes transform lineage", "kind": "metadata", "source_refs": ["src-dbt", "src-datahub"]},
    {"id": "edge-datahub-iceberg", "source": "iceberg", "target": "datahub", "label": "publishes dataset metadata", "kind": "metadata", "source_refs": ["src-iceberg", "src-datahub"]},
    {"id": "edge-control-otel", "source": "control-plane", "target": "otel", "label": "emits API and reconciliation telemetry", "kind": "telemetry", "source_refs": ["src-control-plane", "src-compose"]},
    {"id": "edge-dagster-otel", "source": "dagster-webserver", "target": "otel", "label": "emits native control-plane telemetry", "kind": "telemetry", "source_refs": ["src-dagster-k8s"]},
    {"id": "edge-prefect-otel", "source": "prefect-api", "target": "otel", "label": "emits native control-plane telemetry", "kind": "telemetry", "source_refs": ["src-prefect-k8s"]},
    {"id": "edge-worker-otel", "source": "worker-plane", "target": "otel", "label": "continues W3C traces", "kind": "telemetry", "source_refs": ["src-context", "src-worker-submission"]},
    {"id": "edge-state-scheduled-pending", "source": "state-scheduled", "target": "state-pending", "label": "trigger accepted", "kind": "transition", "source_refs": ["src-contracts"]},
    {"id": "edge-state-pending-running", "source": "state-pending", "target": "state-running", "label": "native execution starts", "kind": "transition", "source_refs": ["src-contracts"]},
    {"id": "edge-state-running-succeeded", "source": "state-running", "target": "state-succeeded", "label": "all required work succeeds", "kind": "transition", "source_refs": ["src-contracts"]},
    {"id": "edge-state-running-failed", "source": "state-running", "target": "state-failed", "label": "engine reports failure", "kind": "transition", "source_refs": ["src-contracts"]},
    {"id": "edge-state-running-cancelled", "source": "state-running", "target": "state-cancelled", "label": "authorized cancellation completes", "kind": "transition", "source_refs": ["src-contracts"]},
    {"id": "edge-state-running-crashed", "source": "state-running", "target": "state-crashed", "label": "infrastructure terminates unexpectedly", "kind": "transition", "source_refs": ["src-contracts"]},
    {"id": "edge-state-failed-pending", "source": "state-failed", "target": "state-pending", "label": "sole engine owns retry", "kind": "transition", "source_refs": ["src-contracts"]},
    {"id": "edge-state-crashed-pending", "source": "state-crashed", "target": "state-pending", "label": "sole engine owns retry", "kind": "transition", "source_refs": ["src-contracts"]},
    {"id": "edge-definition-version", "source": "orchestration-definitions", "target": "orchestration-definition-versions", "label": "has immutable versions", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-version-registration", "source": "orchestration-definition-versions", "target": "orchestration-engine-registrations", "label": "compiles into registrations", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-registration-trigger", "source": "orchestration-engine-registrations", "target": "orchestration-trigger-bindings", "label": "owns trigger bindings", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-version-run", "source": "orchestration-definition-versions", "target": "orchestration-runs", "label": "pins logical runs", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-registration-run", "source": "orchestration-engine-registrations", "target": "orchestration-runs", "label": "owns native run", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-run-attempt", "source": "orchestration-runs", "target": "orchestration-run-attempts", "label": "has attempts", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-run-event", "source": "orchestration-runs", "target": "orchestration-events", "label": "has append-only events", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-attempt-event", "source": "orchestration-run-attempts", "target": "orchestration-events", "label": "optionally scopes events", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-run-artifact", "source": "orchestration-runs", "target": "orchestration-artifacts", "label": "references checksummed artifacts", "kind": "foreign-key", "source_refs": ["src-models", "src-migration"]},
    {"id": "edge-binding-run", "source": "orchestration-engine-bindings", "target": "orchestration-runs", "label": "maps logical and native IDs", "kind": "projection", "source_refs": ["src-models"]},
    {"id": "edge-cursor-run", "source": "orchestration-reconciliation-cursors", "target": "orchestration-runs", "label": "checkpoints native streams", "kind": "projection", "source_refs": ["src-models", "src-control-plane"]},
    {"id": "edge-api-session-idempotency", "source": "session-manager", "target": "session-idempotency", "label": "durably binds operation key to request and redacted outcome", "kind": "idempotency", "source_refs": ["src-session-control", "src-session-operations"]},
    {"id": "edge-api-session-manager", "source": "gateway-api", "target": "session-manager", "label": "authorizes and invokes the embedded durable manager", "kind": "call", "source_refs": ["src-api", "src-session-control", "src-session-wiring"]},
    {"id": "edge-session-manager-repository", "source": "session-manager", "target": "session-repository", "label": "owns durable coordinator and operation state", "kind": "transaction", "source_refs": ["src-session-wiring", "src-session-repository", "src-session-operations"]},
    {"id": "edge-session-manager-http-provider", "source": "session-manager", "target": "session-http-provider", "label": "invokes infrastructure through a dependency-light port", "kind": "provider", "source_refs": ["src-session-wiring", "src-session-http-provider"]},
    {"id": "edge-api-session-coordinator", "source": "session-manager", "target": "session-coordinator", "label": "coordinates acquire, renew, release, lookup, and reconciliation", "kind": "call", "source_refs": ["src-session-control", "src-session-coordinator"]},
    {"id": "edge-session-coordinator-repository", "source": "session-coordinator", "target": "session-repository", "label": "reserves, fences, reference-counts, and reconciles", "kind": "transaction", "source_refs": ["src-session-coordinator", "src-session-repository", "src-session-migration"]},
    {"id": "edge-session-coordinator-provider", "source": "session-coordinator", "target": "session-http-provider", "label": "uses a dependency-light lifecycle port", "kind": "provider", "source_refs": ["src-session-coordinator", "src-session-http-provider"]},
    {"id": "edge-session-http-controller", "source": "session-http-provider", "target": "controller-session-api", "label": "calls versioned lifecycle operations with machine bearer authentication", "kind": "authenticated-http", "source_refs": ["src-session-http-provider", "src-controller-session-api"]},
    {"id": "edge-controller-session-provider", "source": "controller-session-api", "target": "session-provider", "label": "validates contract then dispatches fenced native mutation", "kind": "call", "source_refs": ["src-controller-session-api", "src-session-provider"]},
    {"id": "edge-session-provider-resource", "source": "session-provider", "target": "distributed-resource", "label": "creates fenced CR, NetworkPolicy, and tombstone", "kind": "native-mutation", "source_refs": ["src-session-provider"]},
    {"id": "edge-provider-runtime-identity", "source": "session-provider", "target": "session-runtime-identity", "label": "assigns namespace-scoped runtime identity", "kind": "security", "source_refs": ["src-session-provider", "src-session-runtime-k8s"]},
    {"id": "edge-runtime-identity-resource", "source": "session-runtime-identity", "target": "distributed-resource", "label": "permits Spark executor lifecycle; Ray and Dask disable token automount", "kind": "security", "source_refs": ["src-session-provider", "src-session-runtime-k8s"]},
    {"id": "edge-worker-remote-context", "source": "worker-plane", "target": "remote-worker", "label": "re-verifies signed context and runtime inventory", "kind": "execution", "source_refs": ["src-worker-context", "src-worker-remote"]},
    {"id": "edge-remote-resource", "source": "remote-worker", "target": "distributed-resource", "label": "uses authorized symbolic endpoint", "kind": "execution", "source_refs": ["src-session-contracts", "src-worker-remote"]},
    {"id": "edge-resource-requested-provisioning", "source": "resource-requested", "target": "resource-provisioning", "label": "durable reservation won", "kind": "transition", "source_refs": ["src-session-coordinator"]},
    {"id": "edge-resource-provisioning-ready", "source": "resource-provisioning", "target": "resource-ready", "label": "provider ready and consumer CAS commits", "kind": "transition", "source_refs": ["src-session-coordinator", "src-session-provider"]},
    {"id": "edge-resource-provisioning-failed", "source": "resource-provisioning", "target": "resource-failed", "label": "compensated failure or cancellation", "kind": "transition", "source_refs": ["src-session-coordinator", "src-session-provider"]},
    {"id": "edge-resource-ready-degraded", "source": "resource-ready", "target": "resource-degraded", "label": "readiness or health loss", "kind": "transition", "source_refs": ["src-session-contracts"]},
    {"id": "edge-resource-degraded-ready", "source": "resource-degraded", "target": "resource-ready", "label": "current authority recovers", "kind": "transition", "source_refs": ["src-session-contracts", "src-session-provider"]},
    {"id": "edge-resource-ready-expired", "source": "resource-ready", "target": "resource-expired", "label": "idle or maximum TTL reached", "kind": "transition", "source_refs": ["src-session-contracts", "src-session-coordinator"]},
    {"id": "edge-resource-degraded-expired", "source": "resource-degraded", "target": "resource-expired", "label": "TTL reached", "kind": "transition", "source_refs": ["src-session-contracts", "src-session-coordinator"]},
    {"id": "edge-resource-ready-releasing", "source": "resource-ready", "target": "resource-releasing", "label": "final consumer detaches", "kind": "transition", "source_refs": ["src-session-coordinator"]},
    {"id": "edge-resource-degraded-releasing", "source": "resource-degraded", "target": "resource-releasing", "label": "final consumer detaches", "kind": "transition", "source_refs": ["src-session-coordinator"]},
    {"id": "edge-resource-expired-releasing", "source": "resource-expired", "target": "resource-releasing", "label": "reconciler claims cleanup", "kind": "transition", "source_refs": ["src-session-coordinator"]},
    {"id": "edge-resource-releasing-released", "source": "resource-releasing", "target": "resource-released", "label": "tombstone and native deletion confirmed", "kind": "transition", "source_refs": ["src-session-coordinator", "src-session-provider"]},
    {"id": "edge-session-parent", "source": "execution-sessions", "target": "execution-sessions", "label": "optionally has parent session", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-execution-session-resource", "source": "execution-sessions", "target": "session-resources", "label": "owns resource specifications", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-resource-reservation", "source": "session-resources", "target": "session-resource-reservations", "label": "has fenced reservations", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-resource-lease", "source": "session-resources", "target": "session-resource-leases", "label": "has current lease authority", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-reservation-lease", "source": "session-resource-reservations", "target": "session-resource-leases", "label": "creates immutable lease authority", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-resource-consumer", "source": "session-resources", "target": "session-resource-consumers", "label": "derives reference count from consumers", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-execution-session-event", "source": "execution-sessions", "target": "session-resource-events", "label": "has append-only events", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-resource-event", "source": "session-resources", "target": "session-resource-events", "label": "projects lifecycle events", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-reservation-event", "source": "session-resource-reservations", "target": "session-resource-events", "label": "optionally scopes reservation events", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-lease-event", "source": "session-resource-leases", "target": "session-resource-events", "label": "optionally scopes lease events", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-operation-resource", "source": "session-resource-operations", "target": "session-resources", "label": "stores redacted outcomes by logical operation without a foreign key", "kind": "logical-projection", "source_refs": ["src-session-operations", "src-session-operation-migration"]},
    {"id": "edge-execution-session-cache", "source": "execution-sessions", "target": "session-cache-entries", "label": "optionally scopes cache entries", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-resource-cache", "source": "session-resources", "target": "session-cache-entries", "label": "optionally backs resource cache entries", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]},
    {"id": "edge-session-lease-cache", "source": "session-resource-leases", "target": "session-cache-entries", "label": "optionally binds cache to lease authority", "kind": "foreign-key", "source_refs": ["src-session-models", "src-session-migration"]}
  ],
  "views": [
    {
      "id": "portable-orchestration-c4-context-v1",
      "title": "Portable orchestration C4 context",
      "diagram_type": "C4 context",
      "audience": "executives, architects, security reviewers",
      "abstraction_level": "C4 level 1 — system context",
      "question": "Who uses portable orchestration and which external systems does it coordinate?",
      "source_paths": ["alphaswarm/alphaswarm/api/routes/orchestration.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapter.py", "alphaswarm_worker/src/alphaswarm_worker/submission.py"],
      "text_alternative": "Operators, the hosted UI, CLI, and DataMCP enter through the authenticated AlphaSwarm gateway. The portable authority selects exactly one Dagster or Prefect control plane per run, delegates heavy compute to alphaswarm_worker, and projects normalized metadata without reading native databases.",
      "mermaid_source": "static/architecture/orchestration/mermaid/c4-context.mmd",
      "svg_export": "static/img/architecture/orchestration/c4-context.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-c4-context-v1",
      "node_ids": ["operator", "hosted-ui", "cli-mcp", "gateway-api", "portable-package", "dagster-webserver", "prefect-api", "worker-plane", "workflow-runtime"],
      "edge_ids": ["edge-ui-api", "edge-cli-api", "edge-api-control", "edge-control-portable", "edge-portable-dagster", "edge-portable-prefect", "edge-dagster-worker", "edge-prefect-worker-plane", "edge-workflow-runtime"],
      "layout": {"algorithm": "layered", "direction": "LR", "routing": "orthogonal", "stability": "source-order"}
    },
    {
      "id": "portable-orchestration-c4-container-v1",
      "title": "Portable orchestration C4 containers",
      "diagram_type": "C4 container",
      "audience": "architects, platform engineers, operators",
      "abstraction_level": "C4 level 2 — containers",
      "question": "Which deployable containers own authorization, execution, native state, and projections?",
      "source_paths": ["alphaswarm/alphaswarm/orchestration/control_plane.py", "alphaswarm/alphaswarm/orchestration/wiring.py", "alphaswarm/alphaswarm/orchestration/session_resource_repository.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/http_session_provider.py", "alphaswarm_controller/src/alphaswarm_controller/api/routers/session_resources.py", "alphaswarm_controller/src/alphaswarm_controller/providers/session_resources.py", "alphaswarm_platform/deployments/compose/docker-compose.orchestration.yml", "alphaswarm_platform/deployments/kubernetes/mlops/prefect/", "alphaswarm_platform/deployments/kubernetes/mlops/dagster/"],
      "text_alternative": "The gateway and monolith control service own customer authorization, the normalized ledger, and the durable session-resource manager. The portable package calls supported Dagster and Prefect APIs and uses a dependency-light HTTP provider for session resources. An authenticated controller API exclusively dispatches fenced Kubernetes mutations. Each engine keeps a separate native database authority, while native UIs remain internal.",
      "mermaid_source": "static/architecture/orchestration/mermaid/c4-container.mmd",
      "svg_export": "static/img/architecture/orchestration/c4-container.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-c4-container-v1",
      "node_ids": ["hosted-ui", "gateway-api", "control-plane", "portable-package", "normalized-ledger", "minio", "session-manager", "session-repository", "session-http-provider", "controller-session-api", "session-provider", "distributed-resource", "dagster-webserver", "dagster-daemon", "dagster-code-location", "dagster-db", "prefect-api", "prefect-background", "prefect-worker", "prefect-db", "redis", "kubernetes", "worker-plane", "otel"],
      "edge_ids": ["edge-ui-api", "edge-api-control", "edge-control-portable", "edge-control-ledger", "edge-control-minio", "edge-api-session-manager", "edge-session-manager-repository", "edge-session-manager-http-provider", "edge-session-http-controller", "edge-controller-session-provider", "edge-session-provider-resource", "edge-portable-dagster", "edge-portable-prefect", "edge-dagster-code", "edge-dagster-db", "edge-dagster-daemon", "edge-prefect-background", "edge-prefect-worker", "edge-prefect-db", "edge-prefect-redis", "edge-prefect-kubernetes", "edge-dagster-worker", "edge-control-otel"],
      "layout": {"algorithm": "layered", "direction": "LR", "routing": "orthogonal", "stability": "source-order"}
    },
    {
      "id": "portable-orchestration-c4-component-v1",
      "title": "Portable orchestration C4 components",
      "diagram_type": "C4 component",
      "audience": "backend developers and maintainers",
      "abstraction_level": "C4 level 3 — control-plane components",
      "question": "How do run control, durable session management, dependency-light provider ports, and controller-owned mutations collaborate?",
      "source_paths": ["alphaswarm/alphaswarm/api/routes/orchestration.py", "alphaswarm/alphaswarm/orchestration/control_plane.py", "alphaswarm/alphaswarm/orchestration/repository.py", "alphaswarm/alphaswarm/orchestration/session_control.py", "alphaswarm/alphaswarm/orchestration/session_resource_repository.py", "alphaswarm/alphaswarm/orchestration/wiring.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/contracts.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapter.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/http_session_provider.py", "alphaswarm_controller/src/alphaswarm_controller/api/routers/session_resources.py", "alphaswarm_controller/src/alphaswarm_controller/providers/session_resources.py", "alphaswarm_core/src/alphaswarm_core/execution/context.py"],
      "text_alternative": "The route layer applies identity, scope, step-up, audit, and idempotency policy before calling the run control plane or embedded durable session manager. Run reconciliation mirrors native engine metadata. Session coordination persists forced-RLS reservations, leases, consumers, operations, and events, then uses a dependency-light HTTP provider to call the authenticated controller lifecycle API. The controller validates the machine caller and versioned contract before its Kubernetes provider performs fenced native mutations.",
      "mermaid_source": "static/architecture/orchestration/mermaid/c4-component.mmd",
      "svg_export": "static/img/architecture/orchestration/c4-component.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-c4-component-v1",
      "node_ids": ["gateway-api", "control-plane", "execution-context", "portable-package", "normalized-ledger", "minio", "session-manager", "session-coordinator", "session-repository", "session-http-provider", "controller-session-api", "session-provider", "distributed-resource", "dagster-webserver", "prefect-api"],
      "edge_ids": ["edge-api-control", "edge-control-context", "edge-control-portable", "edge-control-ledger", "edge-control-minio", "edge-portable-dagster", "edge-portable-prefect", "edge-engine-events", "edge-prefect-events", "edge-api-session-manager", "edge-api-session-coordinator", "edge-session-coordinator-repository", "edge-session-coordinator-provider", "edge-session-http-controller", "edge-controller-session-provider", "edge-session-provider-resource"],
      "layout": {"algorithm": "layered", "direction": "LR", "routing": "orthogonal", "stability": "source-order"}
    },
    {
      "id": "portable-orchestration-dagster-sequence-v1",
      "title": "Dagster launch, execution, and reconciliation",
      "diagram_type": "sequence",
      "audience": "backend developers, SREs, incident responders",
      "abstraction_level": "runtime interaction — one Dagster-owned logical run",
      "question": "How does a Dagster-owned run cross launch, compute, and repair boundaries?",
      "source_paths": ["alphaswarm/alphaswarm/orchestration/control_plane.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/dagster/adapter.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/dagster/graphql.py", "alphaswarm_worker/src/alphaswarm_worker/submission.py"],
      "text_alternative": "After authorization and context verification, the control service rehydrates a compiled registration and launches a Dagster job through the version-gated GraphQL gateway. Dagster executes portable ops and delegates heavy work through WorkRequest. The reconciler pages native status, event logs, assets, and checks, externalizes large payloads, and idempotently advances the normalized cursor.",
      "mermaid_source": "static/architecture/orchestration/mermaid/dagster-sequence.mmd",
      "svg_export": "static/img/architecture/orchestration/dagster-sequence.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-dagster-sequence-v1",
      "node_ids": ["operator", "gateway-api", "control-plane", "execution-context", "portable-package", "dagster-webserver", "dagster-code-location", "worker-plane", "normalized-ledger", "minio"],
      "edge_ids": ["edge-api-control", "edge-control-context", "edge-control-portable", "edge-portable-dagster", "edge-dagster-code", "edge-dagster-worker", "edge-engine-events", "edge-control-ledger", "edge-control-minio"],
      "layout": {"algorithm": "sequence", "direction": "LR", "routing": "message-lines", "stability": "participant-order"}
    },
    {
      "id": "portable-orchestration-prefect-sequence-v1",
      "title": "Prefect launch, execution, and reconciliation",
      "diagram_type": "sequence",
      "audience": "backend developers, SREs, incident responders",
      "abstraction_level": "runtime interaction — one Prefect-owned logical run",
      "question": "How does a Prefect-owned run cross launch, Kubernetes, and repair boundaries?",
      "source_paths": ["alphaswarm/alphaswarm/orchestration/control_plane.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/adapter.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/client.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/worker.py", "alphaswarm_worker/src/alphaswarm_worker/submission.py"],
      "text_alternative": "After authorization and signed-context verification, the control service rehydrates a Prefect deployment and creates a flow run through PrefectClient with hidden context parameters. The custom Kubernetes worker verifies context again, applies safe labels, environment, service account, resources, and trace carrier, then runs portable tasks or submits heavy WorkRequest operations. Reconciliation mirrors flow state, events, logs, and artifacts.",
      "mermaid_source": "static/architecture/orchestration/mermaid/prefect-sequence.mmd",
      "svg_export": "static/img/architecture/orchestration/prefect-sequence.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-prefect-sequence-v1",
      "node_ids": ["operator", "gateway-api", "control-plane", "execution-context", "portable-package", "prefect-api", "prefect-worker", "kubernetes", "worker-plane", "normalized-ledger", "minio"],
      "edge_ids": ["edge-api-control", "edge-control-context", "edge-control-portable", "edge-portable-prefect", "edge-prefect-worker", "edge-prefect-kubernetes", "edge-prefect-worker-plane", "edge-prefect-events", "edge-control-ledger", "edge-control-minio"],
      "layout": {"algorithm": "sequence", "direction": "LR", "routing": "message-lines", "stability": "participant-order"}
    },
    {
      "id": "portable-orchestration-lifecycle-v1",
      "title": "Portable run lifecycle",
      "diagram_type": "state machine",
      "audience": "developers, operators, auditors",
      "abstraction_level": "logical run lifecycle",
      "question": "Which canonical states and retry transitions are valid across engines?",
      "source_paths": ["alphaswarm_orchestration/src/alphaswarm_orchestration/contracts.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/dagster/state.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/state.py"],
      "text_alternative": "A logical run may be scheduled or directly pending, becomes running when the owning engine starts execution, and terminates as succeeded, failed, cancelled, or crashed. Only failed and crashed runs may return to pending through a retry owned by the same engine; native states remain preserved separately.",
      "mermaid_source": "static/architecture/orchestration/mermaid/run-lifecycle.mmd",
      "svg_export": "static/img/architecture/orchestration/run-lifecycle.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-lifecycle-v1",
      "node_ids": ["state-scheduled", "state-pending", "state-running", "state-succeeded", "state-failed", "state-cancelled", "state-crashed"],
      "edge_ids": ["edge-state-scheduled-pending", "edge-state-pending-running", "edge-state-running-succeeded", "edge-state-running-failed", "edge-state-running-cancelled", "edge-state-running-crashed", "edge-state-failed-pending", "edge-state-crashed-pending"],
      "layout": {"algorithm": "layered", "direction": "TB", "routing": "orthogonal", "stability": "state-order"}
    },
    {
      "id": "portable-orchestration-metadata-erd-v1",
      "title": "Normalized orchestration and session-execution metadata ERD",
      "diagram_type": "entity relationship",
      "audience": "backend developers, database engineers, auditors",
      "abstraction_level": "tenant-scoped relational projection",
      "question": "How are portable-run metadata and durable session-resource authority related inside the tenant-scoped projection?",
      "source_paths": ["alphaswarm/alphaswarm/persistence/models_orchestration.py", "alphaswarm/alembic/versions/0123_portable_orchestration_ledger.py", "alphaswarm/alphaswarm/orchestration/repository.py", "alphaswarm/alphaswarm/persistence/models_session_execution.py", "alphaswarm/alembic/versions/0130_session_distributed_execution.py", "alphaswarm/alembic/versions/0131_session_resource_operations.py", "alphaswarm/alphaswarm/orchestration/session_resource_repository.py", "alphaswarm/alphaswarm/orchestration/session_operation_repository.py"],
      "text_alternative": "Definitions have immutable versions, registrations, single-owner triggers, runs, attempts, append-only events, artifacts, native bindings, and reconciliation cursors. The separate session-execution projection links verified execution sessions to resource specs, fenced reservations, immutable lease authority, reference-counted consumers, append-only lifecycle events, durable operation outcomes, and scoped cache references. Every table is tenant scoped and forced through RLS; operation outcomes intentionally use a logical association rather than a resource foreign key.",
      "mermaid_source": "static/architecture/orchestration/mermaid/metadata-erd.mmd",
      "svg_export": "static/img/architecture/orchestration/metadata-erd.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-metadata-erd-v1",
      "node_ids": ["orchestration-definitions", "orchestration-definition-versions", "orchestration-engine-registrations", "orchestration-trigger-bindings", "orchestration-runs", "orchestration-run-attempts", "orchestration-events", "orchestration-artifacts", "orchestration-engine-bindings", "orchestration-reconciliation-cursors", "execution-sessions", "session-resources", "session-resource-reservations", "session-resource-leases", "session-resource-consumers", "session-resource-events", "session-resource-operations", "session-cache-entries"],
      "edge_ids": ["edge-definition-version", "edge-version-registration", "edge-registration-trigger", "edge-version-run", "edge-registration-run", "edge-run-attempt", "edge-run-event", "edge-attempt-event", "edge-run-artifact", "edge-binding-run", "edge-cursor-run", "edge-session-parent", "edge-execution-session-resource", "edge-session-resource-reservation", "edge-session-resource-lease", "edge-session-reservation-lease", "edge-session-resource-consumer", "edge-execution-session-event", "edge-session-resource-event", "edge-session-reservation-event", "edge-session-lease-event", "edge-session-operation-resource", "edge-execution-session-cache", "edge-session-resource-cache", "edge-session-lease-cache"],
      "layout": {"algorithm": "layered", "direction": "LR", "routing": "orthogonal-gutters", "stability": "schema-order"}
    },
    {
      "id": "portable-orchestration-context-security-v1",
      "title": "Execution context propagation and security boundaries",
      "diagram_type": "trust-boundary data flow",
      "audience": "security reviewers, backend developers, operators",
      "abstraction_level": "cross-process identity and trace propagation",
      "question": "What context crosses each boundary, and where is authorization decided?",
      "source_paths": ["alphaswarm_core/src/alphaswarm_core/execution/context.py", "alphaswarm/alphaswarm/api/routes/orchestration.py", "alphaswarm/alphaswarm/orchestration/control_plane.py", "alphaswarm/alphaswarm/orchestration/wiring.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/http_session_provider.py", "alphaswarm_controller/src/alphaswarm_controller/api/routers/session_resources.py", "alphaswarm_controller/src/alphaswarm_controller/providers/session_resources.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/dagster/context.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/context.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/adapters/prefect/worker.py"],
      "text_alternative": "The gateway derives customer authorization from authenticated identity, scopes, ownership, step-up state, and database RLS, then signs an expiring ExecutionContextV1. Framework tags carry only searchable IDs, a reference, and digest. The monolith's durable manager resolves a separate machine credential for its dependency-light HTTP provider. The controller authenticates that caller before dispatching fenced Kubernetes mutations; request context, leases, labels, and native metadata never grant authorization. Dagster, Prefect, jobs, and workers independently verify context integrity.",
      "mermaid_source": "static/architecture/orchestration/mermaid/context-security.mmd",
      "svg_export": "static/img/architecture/orchestration/context-security.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-context-security-v1",
      "node_ids": ["operator", "gateway-api", "control-plane", "execution-context", "normalized-ledger", "session-manager", "session-http-provider", "controller-session-api", "session-provider", "distributed-resource", "dagster-code-location", "prefect-worker", "kubernetes", "worker-plane"],
      "edge_ids": ["edge-api-control", "edge-control-context", "edge-control-ledger", "edge-context-dagster", "edge-context-prefect", "edge-prefect-kubernetes", "edge-context-worker", "edge-api-session-manager", "edge-session-manager-http-provider", "edge-session-http-controller", "edge-controller-session-provider", "edge-session-provider-resource"],
      "layout": {"algorithm": "layered", "direction": "LR", "routing": "orthogonal", "stability": "trust-boundary-order"}
    },
    {
      "id": "portable-orchestration-data-flow-v1",
      "title": "Orchestration and governed data flow",
      "diagram_type": "data flow",
      "audience": "data engineers, platform architects, governance teams",
      "abstraction_level": "logical data and metadata flow",
      "question": "How do ingestion, transformation, orchestration, storage, catalog, execution, and observability connect?",
      "source_paths": ["alphaswarm/alphaswarm/data/airbyte/orchestrator.py", "alphaswarm/alphaswarm/dagster/assets/dbt_assets.py", "alphaswarm/alphaswarm/data/iceberg_catalog.py", "alphaswarm/alphaswarm/services/polaris_client.py", "alphaswarm/alphaswarm/data/datahub/emitter.py", "alphaswarm_worker/src/alphaswarm_worker/submission.py"],
      "text_alternative": "Airbyte lands source data in Iceberg and emits sync metadata. Dagster or Prefect controls portable definitions, with Dagster retaining native asset and dbt semantics. dbt transforms governed Iceberg tables registered through Polaris. Airbyte, dbt, and Iceberg publish lineage to DataHub. Heavy computation delegates to alphaswarm_worker, while every control and execution path emits OpenTelemetry signals.",
      "mermaid_source": "static/architecture/orchestration/mermaid/data-flow.mmd",
      "svg_export": "static/img/architecture/orchestration/data-flow.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-data-flow-v1",
      "node_ids": ["airbyte", "dbt", "dagster-webserver", "prefect-api", "portable-package", "iceberg", "polaris", "datahub", "worker-plane", "otel"],
      "edge_ids": ["edge-airbyte-iceberg", "edge-airbyte-dagster", "edge-dbt-iceberg", "edge-dagster-dbt", "edge-iceberg-polaris", "edge-datahub-airbyte", "edge-datahub-dbt", "edge-datahub-iceberg", "edge-dagster-worker", "edge-prefect-worker-plane", "edge-dagster-otel", "edge-prefect-otel", "edge-worker-otel"],
      "layout": {"algorithm": "layered", "direction": "LR", "routing": "orthogonal", "stability": "data-stage-order"}
    },
    {
      "id": "portable-orchestration-deployment-topology-v1",
      "title": "Compose and Kubernetes deployment topology",
      "diagram_type": "deployment topology",
      "audience": "SREs, platform engineers, security reviewers",
      "abstraction_level": "self-hosted runtime deployment",
      "question": "How do local Compose and production Kubernetes instances differ?",
      "source_paths": ["alphaswarm_platform/deployments/compose/docker-compose.orchestration.yml", "alphaswarm_platform/deployments/kubernetes/mlops/prefect/", "alphaswarm_platform/deployments/kubernetes/mlops/dagster/", "alphaswarm_platform/deployments/kubernetes/mlops/session-runtime/", "alphaswarm_platform/configs/deployment/topology.yaml"],
      "text_alternative": "The smoke Compose profile runs single Dagster and Prefect control-plane processes with PostgreSQL 16, Redis, MinIO access, and an OTel gateway. Production Kubernetes runs two Prefect API replicas, one background replica, two workers, two Dagster webservers, and single Dagster daemon and code-location replicas. The controller assigns a namespace-scoped alphaswarm-session-runtime identity: Spark may manage executor pods, Services, ConfigMaps, and PVCs, while Ray and Dask disable token automount. Native UIs remain internal and secrets come from External Secrets.",
      "mermaid_source": "static/architecture/orchestration/mermaid/deployment-topology.mmd",
      "svg_export": "static/img/architecture/orchestration/deployment-topology.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-deployment-topology-v1",
      "node_ids": ["gateway-api", "session-manager", "session-http-provider", "controller-session-api", "session-provider", "session-runtime-identity", "distributed-resource", "dagster-webserver", "dagster-daemon", "dagster-code-location", "dagster-db", "prefect-api", "prefect-background", "prefect-worker", "prefect-db", "redis", "kubernetes", "minio", "otel"],
      "edge_ids": ["edge-api-session-manager", "edge-session-manager-http-provider", "edge-session-http-controller", "edge-controller-session-provider", "edge-session-provider-resource", "edge-provider-runtime-identity", "edge-runtime-identity-resource", "edge-portable-dagster", "edge-portable-prefect", "edge-dagster-code", "edge-dagster-db", "edge-dagster-daemon", "edge-prefect-background", "edge-prefect-worker", "edge-prefect-db", "edge-prefect-redis", "edge-prefect-kubernetes", "edge-dagster-otel", "edge-prefect-otel"],
      "layout": {"algorithm": "layered", "direction": "TB", "routing": "orthogonal", "stability": "deployment-zone-order"}
    },
    {
      "id": "portable-orchestration-celery-migration-v1",
      "title": "Celery to dual-engine migration and rollback",
      "diagram_type": "swimlane flow",
      "audience": "release managers, SREs, service owners",
      "abstraction_level": "rollout and rollback control flow",
      "question": "How is a schedule moved without duplicate ownership and restored safely?",
      "source_paths": ["alphaswarm/alphaswarm/orchestration/compatibility.py", "alphaswarm/alphaswarm/orchestration/control_plane.py", "alphaswarm_config/src/alphaswarm_config/models/orchestration.py", "alphaswarm/alphaswarm/persistence/models_orchestration.py"],
      "text_alternative": "Start with compatibility flags off and Celery Beat as the only schedule owner. Compile the representative definition for both engines, register one selected engine, keep its trigger disabled, and shadow-verify parity, cancellation, restart reconciliation, and rollback. Transfer ownership atomically by disabling Celery before enabling one native trigger. On failure, stop new registrations, disable the native trigger, restore Celery ownership, and allow or cancel active native runs while retaining additive ledger data.",
      "mermaid_source": "static/architecture/orchestration/mermaid/celery-migration.mmd",
      "svg_export": "static/img/architecture/orchestration/celery-migration.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-celery-migration-v1",
      "node_ids": ["celery", "legacy-workflows", "scheduler-owner", "portable-package", "dagster-webserver", "prefect-api", "normalized-ledger"],
      "edge_ids": ["edge-celery-compat", "edge-legacy-api", "edge-schedule-celery", "edge-schedule-engine", "edge-portable-dagster", "edge-portable-prefect", "edge-control-ledger"],
      "layout": {"algorithm": "layered", "direction": "TB", "routing": "orthogonal", "stability": "rollout-step-order"}
    },
    {
      "id": "portable-orchestration-session-resource-sequence-v1",
      "title": "Session resource acquisition, execution, and cleanup",
      "diagram_type": "runtime sequence",
      "audience": "backend developers, platform engineers, SREs, security reviewers",
      "abstraction_level": "runtime interaction — session resource acquire, use, and cleanup",
      "question": "How is one session capability acquired, safely used across remote process boundaries, and released without stale authority?",
      "source_paths": ["alphaswarm_core/src/alphaswarm_core/execution/session.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/session_resources.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/http_session_provider.py", "alphaswarm/alphaswarm/api/routes/orchestration.py", "alphaswarm/alphaswarm/orchestration/session_control.py", "alphaswarm/alphaswarm/orchestration/session_resource_repository.py", "alphaswarm/alphaswarm/orchestration/session_operation_repository.py", "alphaswarm/alphaswarm/orchestration/wiring.py", "alphaswarm_controller/src/alphaswarm_controller/api/routers/session_resources.py", "alphaswarm_controller/src/alphaswarm_controller/providers/session_resources.py", "alphaswarm_worker/src/alphaswarm_worker/execution/context.py", "alphaswarm_worker/src/alphaswarm_worker/execution/remote.py", "alphaswarm/alembic/versions/0130_session_distributed_execution.py", "alphaswarm/alembic/versions/0131_session_resource_operations.py"],
      "text_alternative": "An authenticated client submits an immutable session resource specification and idempotency key. The gateway rebinds signed tenant and session context and calls the monolith's embedded durable manager, which claims the operation and coordinates forced-RLS reservations, leases, consumers, and events. A dependency-light HTTP provider crosses a bearer-authenticated, versioned controller API; only the controller's fenced Kubernetes provider mutates Ray, Dask, or Spark resources. A worker re-verifies context and lease authority before remote execution. Final release, cancellation, or reconciliation cleans native resources before terminal commit and rejects late ready outcomes.",
      "mermaid_source": "static/architecture/orchestration/mermaid/session-resource-sequence.mmd",
      "svg_export": "static/img/architecture/orchestration/session-resource-sequence.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-session-resource-sequence-v1",
      "node_ids": ["hosted-ui", "gateway-api", "execution-context", "session-idempotency", "session-manager", "session-coordinator", "session-repository", "session-http-provider", "controller-session-api", "session-provider", "distributed-resource", "worker-plane", "remote-worker"],
      "edge_ids": ["edge-api-session-manager", "edge-api-session-idempotency", "edge-api-session-coordinator", "edge-session-coordinator-repository", "edge-session-coordinator-provider", "edge-session-http-controller", "edge-controller-session-provider", "edge-session-provider-resource", "edge-context-worker", "edge-worker-remote-context", "edge-remote-resource"],
      "layout": {"algorithm": "sequence", "direction": "LR", "routing": "message-lines", "stability": "participant-order"}
    },
    {
      "id": "portable-orchestration-session-resource-lifecycle-v1",
      "title": "Session resource lifecycle and fencing",
      "diagram_type": "state model",
      "audience": "backend developers, platform engineers, SREs, auditors",
      "abstraction_level": "session resource state, fencing, and cleanup model",
      "question": "Which resource transitions are valid, and how do fencing, consumer CAS, tombstones, and reconciliation prevent stale mutation?",
      "source_paths": ["alphaswarm_core/src/alphaswarm_core/execution/session.py", "alphaswarm_orchestration/src/alphaswarm_orchestration/session_resources.py", "alphaswarm_controller/src/alphaswarm_controller/providers/session_resources.py", "alphaswarm/alembic/versions/0130_session_distributed_execution.py"],
      "text_alternative": "A session resource starts requested, becomes provisioning under one durable reservation, and may become ready only if the original reservation and consumer compare-and-swap token still own the operation. Ready resources can degrade, renew in place with a newer fence, expire, or enter releasing after the final consumer detaches. Release and abandoned-cleanup paths tombstone and delete the current native authority before reaching released. Provision failures reach failed only after compensating ambiguous native creation, and stale leases cannot mutate newer resources.",
      "mermaid_source": "static/architecture/orchestration/mermaid/session-resource-lifecycle.mmd",
      "svg_export": "static/img/architecture/orchestration/session-resource-lifecycle.svg",
      "regeneration_command": "pnpm diagrams:render --diagram portable-orchestration-session-resource-lifecycle-v1",
      "node_ids": ["resource-requested", "resource-provisioning", "resource-ready", "resource-degraded", "resource-releasing", "resource-released", "resource-failed", "resource-expired"],
      "edge_ids": ["edge-resource-requested-provisioning", "edge-resource-provisioning-ready", "edge-resource-provisioning-failed", "edge-resource-ready-degraded", "edge-resource-degraded-ready", "edge-resource-ready-expired", "edge-resource-degraded-expired", "edge-resource-ready-releasing", "edge-resource-degraded-releasing", "edge-resource-expired-releasing", "edge-resource-releasing-released"],
      "layout": {"algorithm": "layered", "direction": "LR", "routing": "orthogonal", "stability": "state-order"}
    }
  ],
  "known_omissions": [
    "Native Dagster and Prefect internal database schemas are intentionally excluded because integrations use supported SDK and HTTP APIs only.",
    "Renderer coordinates are intentionally excluded; Mermaid owns static layout and the hosted React Flow surface owns interactive ELK layout.",
    "Argo remains cluster-batch infrastructure and is outside the two-engine logical-run authority model."
  ]
}