Schema Design AWS AI

aws-design-ai.json is written by phases/design/design-ai.md only when ai-workload-profile.json exists. It is a SEPARATE artifact from aws-design.json (§19.10): the infra assembler still solely owns aws-design.json; the AI fragment owns this file. When there is no AI workload, this file is not produced and nothing downstream looks for it.

Shape

Accounting invariant. Every entry in the profile’s workloads[] (or models[] when workloads[] is empty) appears in exactly one design_blocks[] row, in input order.

design_blocks[]

One row per confirmed workload. This is the per-workload target decision.

• target_bedrock_model XOR target_aws_service — exactly one is non-null per row. Bedrock-model capabilities (text_generation, structured_output, image_generation, embedding, speech_to_text, text_to_speech, unknown) set target_bedrock_model and leave target_aws_service null. The three traditional-AI capabilities (document_extraction, image_analysis, speech_transcription) set target_aws_service (one of "textract", "rekognition", "transcribe", "comprehend", "translate", "polly", "sagemaker") and leave target_bedrock_model null. This is the same rule gcp enforces; it exists because those three are AWS AI services, not Bedrock model swaps.
• confidence_warning is a non-null string (naming the workload and that manual review is required) when capability_confidence == "low"; null for high/medium.
• Input order preserved: design_blocks[] order matches the profile’s workloads[] order.

capability vocabulary

Bedrock-model capabilities: text_generation, structured_output, image_generation, embedding, speech_to_text, text_to_speech, unknown. Traditional-AI capabilities (AWS AI service, not Bedrock): document_extraction, image_analysis, speech_transcription.

ai_architecture

• honest_assessment — strong_migrate | moderate_migrate | weak_migrate | recommend_stay | not_applicable. Overall value = the weakest across all Bedrock models. not_applicable is a PER-WORKLOAD value for the three traditional-AI capabilities only — never the overall assessment (they are feature swaps, not a cost-driven model decision).
• honest_assessment_reason — REQUIRED (non-null) when honest_assessment == "recommend_stay"; names the specific non-cost blocker (fixed region with no suitable model, a Realtime/streaming dependency, an Assistants-style feature with no Bedrock equivalent, or a confirmed unsupported API surface). Null otherwise. Cost parity alone is never sufficient to recommend staying when the source models are on Bedrock.
• tiered_strategy — object when ai_token_volume == "high" (a 3-tier routing plan); null for low/medium.
• bedrock_models[] — per Bedrock target: source_model_id, aws_model_id, capabilities_matched[], capability_gaps[], honest_assessment, source_provider_price, bedrock_price, price_comparison, migration_complexity, model_change (bool), migration_path (see below), quota_risk (low|medium|high). Traditional-AI capabilities do NOT appear here — they are design_blocks[] rows with target_aws_service.
• capability_mapping — per capability that is true in the profile’s integration.capabilities_summary: { parity: "full|partial|none", notes }.
• code_migration — primary_pattern (matches profile integration.pattern), framework, files_to_modify[], dependency_changes, and — when the source is Azure OpenAI / OpenAI — openrouter_path when a router was detected (same_model_mantle|direct|litellm|keep_openrouter).
• infrastructure[] — Azure AI infra resource → AWS equivalent, with confidence.
• services_to_migrate[] — Azure AI service → AWS service, effort, notes.

migration_path vocabulary

mantle_openai_responses (Azure OpenAI / OpenAI source, model on Bedrock, region carries it — keep the SDK, model_change: false) · converse (Bedrock-native Converse/bedrock-runtime; set model_change: true when a proprietary GPT model must move off mantle for Guardrails / Knowledge Bases / logging / an unsupported region) · gpt-oss (OpenAI-lineage model on the Bedrock-native runtime) · direct (framework-agnostic Bedrock SDK swap). A proprietary openai.gpt-* model ID is NEVER paired with a converse/bedrock-runtime path — those models are mantle-only.

regional_validation

checked (aws___get_regional_availability on the AWS MCP Server confirmed model/region availability) · fallback_static (the call failed; the static table in vendored/ai/ai-migration-guardrails.md was used).

regional_warnings[]

ALWAYS present ([] when clean). Per unavailable service: { service, target_region, nearest_available, impact }. A compliance constraint that forced a region (e.g. fedramp → GovCloud, gdpr → EU eu. profiles) records the models it excluded here. Never blocks the design — it flags the constraint and proceeds.

multi_model_warnings[]

ALWAYS present ([] when a single model / no coordination issue). Per warning: { type, message }, type ∈ embeddings_reindex | cascade_pair | multi_model_tiered | image_separate | speech_separate.

agentic_design

Present ONLY when the profile’s agentic_profile.is_agentic == true; null/absent otherwise. { migration_approach: "retarget|harness|strands|undecided", ...path-specific config }. When migration_approach == "harness" carry harness_config (with source_model_provider, which is "open_ai" for an azure_openai source — see §19.9(b)); when "strands" carry the AgentCore Runtime config from vendored/ai/design-ref-agentic-to-agentcore.md.

halt

Present ONLY when the AI design is failing its gate. { reason, blocking[] } where each blocking[] entry is { kind, identifier, why, action }. The AI design halts when a routed rubric file (ai.md, ai-azure-openai-to-bedrock.md, or a vendored/ai/* ref) named by index.md is not on disk — the same missing-rubric guard the infra design uses.

Validation Checklist

• Not done: metadata.ai_source equals summary.ai_source from ai-workload-profile.json.
• Not done: Every workloads[] entry (or models[] when workloads is empty) has exactly one design_blocks[] row, in input order.
• Not done: Every design_blocks[] row has exactly one of target_bedrock_model / target_aws_service non-null (XOR).
• Not done: Every traditional-AI row (document_extraction/image_analysis/speech_transcription) has target_bedrock_model: null, a non-null target_aws_service, and (in ai_architecture) is not counted in bedrock_models[].
• Not done: Every bedrock_models[] entry has source_provider_price, bedrock_price, price_comparison.
• Not done: honest_assessment overall is the weakest across bedrock_models[]; if recommend_stay, honest_assessment_reason names a non-cost blocker.
• Not done: No bedrock_models[] entry pairs a proprietary openai.gpt-* model ID with a converse/bedrock-runtime migration path (mantle-only).
• Not done: If ai_source is azure_openai or openai: every source model that is available on Bedrock and carried by the target region maps to ITSELF with model_change: false — not to a Claude/Nova substitute.
• Not done: regional_warnings and multi_model_warnings are present ([] when clean).
• Not done: If agentic_profile.is_agentic == true: agentic_design is present with migration_approach matching preferences.json; a harness source with an azure_openai origin sets source_model_provider: "open_ai".
• Not done: All Bedrock model IDs are Active per vendored/ai/ai-model-lifecycle.md (a Legacy ID is used only if no Active alternative exists, with the EOL date noted).
• Not done: "App Runner" appears nowhere in the artifact.

Status — build step 2 (AI design route)

Written alongside design-ai.md. The estimate/generate AI consumers (estimation-ai.json, generation-ai.json) land in step 3 and read this contract.