Schema Design AWS

Shape

Every inventory resource appears in exactly one of services, deferred, pending_rubric, or warnings. That is the accounting invariant, and it is the only thing that makes a silently dropped resource detectable — a dropped resource still parses, still satisfies every other assertion, and simply produces no cost line.

services[]

A resource with an AWS target.

• fast_path_row is mandatory on every deterministic entry and must be a key in knowledge/design/fast-path-services.json → direct_mappings. It is what makes the label auditable: without it, “this came from a table” is an unverifiable claim, and an improvised target labelled deterministic is indistinguishable from a real one.
• rationale is customer-facing. State why this target, not what the table says.
• A measured entry must cite the utilization evidence inside rationale or aws_config.

clusters[]

One entry per cluster in azure-resource-clusters.json. Cluster-level fields come FIRST in the artifact and first in the report, because that is the holistic payoff — a 40-row per-resource table is an appendix.

pattern_status exists so that “no pattern could be recognized” has a defined home. Three states, and they are not the same fact:

Without this field, the phase’s postcondition demanding target_architecture is unsatisfiable while patterns.md is absent, and the honest response — leaving it undetermined — looks identical to a defect. The dangerous alternative is what an agent optimising for a green gate does instead: write a plausible architecture string. Nothing downstream could catch that, which is exactly why the honest state needs to be expressible.

target_architecture MUST be null when pattern_status is not recognized. A non-null value with catalog_absent is a contradiction and must fail validation.

deferred[]

A specialist gate fired. See design-refs/specialist-gates.md.

No confidence field. A deferral did not come from a rubric, so labelling it inferred would claim reasoning that did not happen. This is the one entry shape that carries no confidence value.

A gate is not a failure and not a halt: design continues, the rest of the estate maps normally, and the estimate carries no line item for the deferred workload. Say that in the report, so a missing cost does not read as a free service.

pending_rubric[]

A resource whose category file, named by design-refs/index.md, is not on disk. The halt guard’s record. Never a place to put a resource you could have mapped.

sizing_source and hosted_app_azure_ids are required, not optional, and they are required on a services[] compute entry too once the rubric exists. They are the audit trail for the App Service Plan fan-in: hosted_app_azure_ids records WHICH apps folded into this plan, and sizing_source records that capacity came from the plan’s SKU rather than from the app count. Without them, “five apps correctly fanned in to one plan” and “four apps fanned in and one silently dropped” produce identical artifacts.

Every azure_id in hosted_app_azure_ids must exist in the inventory.

service_id

Derived, not invented. <aws-service-slug>-<azure-resource-local-name>:

• aws-service-slug — the aws_service value lowercased, non-alphanumerics collapsed to a single -, leading aws- / amazon- dropped. Never abbreviate, because an abbreviation is a choice and choices are what made this unreproducible: Elastic Beanstalk → elastic-beanstalk (not eb), RDS PostgreSQL → rds-postgresql, FSx for Windows File Server → fsx-for-windows-file-server, Systems Manager Session Manager → systems-manager-session-manager.
• azure-resource-local-name — the source resource’s config.tf_resource_name, or the last segment of azure_id when there is no Terraform provenance. Strip any tf: prefix.
• Collision → append -2, -3. Collisions should be rare, because one Azure resource produces at most one entry.

Why a rule and not “any stable slug”. The previous wording was <stable slug, unique within the artifact>, which let two runs of the same estate produce entirely different ids — capability run 4 produced 8 different ids out of 14, every one of them a valid stable slug. An identifier nobody can reproduce cannot be referenced from a report, cross-checked between artifacts, or asserted by a fixture, and its instability is invisible because each run is internally consistent.

Nothing may key on service_id across artifacts. Use azure_id for that — it is constructed by a stated rule, it is unique, and it is the same string in every artifact that mentions the resource. service_id is for human reference within one artifact only.

routing_provenance

REQUIRED on every services[] entry. How this resource’s disposition was reached:

confidence: "deterministic" requires routing_provenance: "table". No derived route — child_type_rule, namespace_rule or model_category — can ever earn that tier — it has no fast_path_row to name, and the rubric made the decision. An entry claiming deterministic with a derived provenance is the specific failure this field detects.

The two derived values exist so coverage can grow without an authored row per type, while staying visible: a reviewer can see at a glance which mappings came from curated judgement and which from a structural rule. Without the field they are indistinguishable in the artifact, which is how 53 orphans and a confidently-wrong category both hide.

sizing_provenance

REQUIRED on every services[] entry whose aws_config carries a size — an instance type, instance class, node count, shard count, capacity unit, or volume type. One of:

model_prior is a legal value and must be used honestly. It exists because the alternative is what this skill did until 2026-09-07: every size in the committed golden was a pretrained association, sizing_source recorded only the Azure input so the output looked sourced, and the oracle pinned no sizes, so two runs could disagree on every number and both stay green. Writing table when no row was consulted is the failure this field is here to prevent — and it is the one failure a reviewer cannot detect from the artifact alone.

Two corollaries:

• sizing_source records the Azure input ({"sku_name": "S1", "worker_count": 2}). sizing_provenance records where the output came from. They are different claims and neither substitutes for the other.
• A model_prior entry SHOULD carry a warnings[] entry naming the type that has no sizing row, so the gap is visible in the report and fixable in one place.

warnings[]

Same entry shape as Discover’s (schema-discover-azure.md § Warnings: code, an azure_id or identifier, and a detail naming the consequence), with a separate closed vocabulary — Discover’s codes say what could not be READ, Design’s say what was DECIDED. The vocabulary is in phases/design/design-infra.md § Warning codes.

Optional extra keys: severity (blocker | cost_optimization), report_note (e.g. cloudwatch_fallback), plan_azure_id (on app_consumed_by_plan).

halt

Present only when the phase is failing its gate. Absent on a clean design.

Every pending_rubric[] entry’s ref_file must have a matching missing_rubric_file entry in halt.blocking. pending_rubric[] records which resources are affected; halt records that the phase is not finished. A design carrying pending_rubric[] and no halt reads as complete to anything that only looks at services[], which is most report code.

Write the artifact even when halting. Everything determined stays in, and the gate fails on its own merits. Discarding the work makes the user re-run the phase to learn one missing table row and hides which resources were already fine — and it makes the halt untestable by an external asserter.

Validation Checklist

• Not done: Every inventory resource appears in exactly one of services, deferred, pending_rubric, or warnings.
• Not done: Every services[] entry has service_id, azure_id, azure_type, aws_service, aws_config, confidence, rationale.
• Not done: Every deterministic entry has a fast_path_row that is a key in fast-path-services.json → direct_mappings, and an aws_service that row allows.
• Not done: No deferred[] entry has a confidence field; every one has aws_service: "Deferred — specialist engagement" and a reason.
• Not done: No Microsoft.Web/sites resource has an entry in services[], deferred[], or pending_rubric[] — it is always folded into its plan.
• Not done: Every Microsoft.Web/serverfarms entry has hosted_app_azure_ids and sizing_source, and every id in the former exists in the inventory.
• Not done: Every cluster has pattern_status, and target_architecture is null unless pattern_status is recognized.
• Not done: Every pending_rubric[] entry has a ref_file, and every distinct ref_file has a missing_rubric_file entry in halt.blocking.
• Not done: warnings[] is present, and every entry has a code from the design vocabulary, a detail, and an azure_id or identifier.
• Not done: halt is present iff the phase is failing its gate.
• Not done: Every services[] entry has routing_provenance from {table, index_md, child_type_rule, namespace_rule}, and no entry with a derived provenance claims confidence: "deterministic".
• Not done: Every services[] entry whose aws_config carries a size has sizing_provenance set to one of table, measured, user_stated, model_prior — and table only when a knowledge/ row actually covered it.
• Not done: “App Runner” appears nowhere in the artifact.

Status — build step 3

services[], pending_rubric[], warnings[], and halt are exercised by the azure-iac-terraform fixture’s Design asserter. deferred[] is shape-bound but untested — the corpus fires no specialist gate. clusters[] carries pattern_status: "catalog_absent" until build step 4 lands patterns.md.