Add evidence-backed architecture manifests

data/README.md

@@ -75,6 +75,34 @@ Do not overload values:
 
 Evidence references should identify a source plus the smallest useful locator available: section, table, page, config key, file/line range, release-note heading, or commit.
 
+## Architecture manifests
+
+An `ArchitectureSpec` targets exactly one canonical model release or model variant through `target`. Every populated architecture fact must be covered by at least one field-level evidence entry. Evidence entries identify a canonical `source`, a narrow `locator`, and the exact fact paths supported by that locator.
+
+```yaml
+id: arch:example-model
+type: architecture_spec
+name: Example model architecture
+target: variant:example-model
+status: reviewed
+topology:
+  type: decoder_only
+attention:
+  query_heads: 32
+evidence:
+  - source: source:example-model-report
+    locator: '§2 Model Architecture, Table 1'
+    fields:
+      - topology.type
+      - attention.query_heads
+```
+
+The validator rejects evidence paths that point to absent or `null` values and rejects populated architecture facts that lack evidence. `notes` are editorial context and are not treated as architecture facts requiring field evidence.
+
+Layer-plan ranges in `blocks` are zero-based and inclusive. Ranges must be ordered internally, must not overlap, and must remain within `dimensions.layers` when the layer count is present.
+
+Architecture fields whose values are unestablished or vary by checkpoint packaging within the manifest's target should be omitted rather than guessed, averaged, or selected from one package and presented as intrinsic architecture. Use `null` only when preserving an explicit reviewed-but-unestablished slot is itself useful to the record.
+
 ## Dates and timestamps
 
 Quote ISO dates and timestamps in hand-authored YAML when practical. The shared record loader normalizes YAML-native `date` and `datetime` scalars to ISO strings before schema validation and generation, so equivalent unquoted YAML remains valid.

data/architectures/deepseek-v3.yaml

@@ -0,0 +1,56 @@
+id: arch:deepseek-v3
+type: architecture_spec
+name: DeepSeek-V3 architecture
+target: release:deepseek-v3
+status: reviewed
+topology:
+  type: decoder_only
+dimensions:
+  layers: 61
+  d_model: 7168
+  head_dim: 128
+components:
+  attention: multi_head_latent_attention
+  ffn: dense_then_deepseek_moe
+  routing: auxiliary_loss_free_load_balancing
+attention:
+  query_heads: 128
+  kv_compression_dim: 512
+  query_compression_dim: 1536
+feed_forward:
+  expert_intermediate_dim: 2048
+  shared_experts: 1
+  routed_experts: 256
+  active_routed_experts: 8
+blocks:
+  - range: [0, 2]
+    attention: multi_head_latent_attention
+    ffn: dense
+  - range: [3, 60]
+    attention: multi_head_latent_attention
+    ffn: deepseek_moe
+evidence:
+  - source: source:deepseek-v3-report
+    locator: '§2.1 Basic Architecture and §2.1.1 Multi-Head Latent Attention'
+    fields:
+      - topology.type
+      - components.attention
+  - source: source:deepseek-v3-report
+    locator: '§2.1.2 DeepSeekMoE with Auxiliary-Loss-Free Load Balancing'
+    fields:
+      - components.ffn
+      - components.routing
+  - source: source:deepseek-v3-report
+    locator: '§4.2 Hyper-Parameters > Model Hyper-Parameters'
+    fields:
+      - dimensions.layers
+      - dimensions.d_model
+      - dimensions.head_dim
+      - attention.query_heads
+      - attention.kv_compression_dim
+      - attention.query_compression_dim
+      - feed_forward.expert_intermediate_dim
+      - feed_forward.shared_experts
+      - feed_forward.routed_experts
+      - feed_forward.active_routed_experts
+      - blocks

data/architectures/gemma-2-9b.yaml

@@ -0,0 +1,53 @@
+id: arch:gemma-2-9b
+type: architecture_spec
+name: Gemma 2 9B architecture
+target: variant:gemma-2-9b
+status: reviewed
+topology:
+  type: decoder_only
+  pre_norm: true
+  post_norm: true
+dimensions:
+  layers: 42
+  d_model: 3584
+  head_dim: 256
+tokenization:
+  vocab_size: 256128
+context:
+  pretrained_length: 8192
+components:
+  normalization: rmsnorm
+  position: rope
+  attention: alternating_local_global_grouped_query_attention
+  ffn: geglu
+attention:
+  query_heads: 16
+  kv_heads: 8
+  sliding_window: 4096
+  global_span: 8192
+feed_forward:
+  intermediate_dim: 28672
+evidence:
+  - source: source:gemma-2-report
+    locator: 'Table 1, Overview of the main model parameters and design choices'
+    fields:
+      - topology.pre_norm
+      - topology.post_norm
+      - dimensions.layers
+      - dimensions.d_model
+      - dimensions.head_dim
+      - tokenization.vocab_size
+      - attention.query_heads
+      - attention.kv_heads
+      - attention.sliding_window
+      - attention.global_span
+      - feed_forward.intermediate_dim
+  - source: source:gemma-2-report
+    locator: '§2 Model Architecture'
+    fields:
+      - topology.type
+      - context.pretrained_length
+      - components.normalization
+      - components.position
+      - components.attention
+      - components.ffn

data/architectures/llama-3.1-405b.yaml

@@ -0,0 +1,33 @@
+id: arch:llama-3.1-405b
+type: architecture_spec
+name: Llama 3.1 405B architecture
+target: variant:llama-3.1-405b
+status: reviewed
+topology:
+  type: decoder_only
+dimensions:
+  layers: 126
+  d_model: 16384
+tokenization:
+  vocab_size: 128256
+components:
+  position: scaled_rope
+  attention: grouped_query_attention
+attention:
+  query_heads: 128
+evidence:
+  - source: source:llama-3-paper
+    locator: '§3.2 Model Architecture, Table 3'
+    fields:
+      - topology.type
+      - components.attention
+  - source: source:llama-models-sku-list
+    locator: 'models/sku_list.py: LLAMA3_VOCAB_SIZE and llama3_1_base_models() 405B BF16 MP8/FP8/MP16 entries, commit 0e0b8c519242d5833d8c11bffc1232b77ad7f301'
+    fields:
+      - dimensions.layers
+      - dimensions.d_model
+      - tokenization.vocab_size
+      - components.position
+      - attention.query_heads
+    note: 'The same core model is packaged with n_kv_heads=8 for BF16 MP8/FP8 and n_kv_heads=16 for BF16 MP16.'
+notes: "attention.kv_heads is intentionally omitted at the model-variant level because Meta's first-party checkpoint SKUs expose packaging-dependent KV-head counts for the same 405B core model."

data/architectures/mistral-7b.yaml

@@ -0,0 +1,41 @@
+id: arch:mistral-7b
+type: architecture_spec
+name: Mistral 7B architecture
+target: release:mistral-7b
+status: reviewed
+topology:
+  type: decoder_only
+dimensions:
+  layers: 32
+  d_model: 4096
+  head_dim: 128
+tokenization:
+  vocab_size: 32000
+context:
+  pretrained_length: 8192
+components:
+  attention: grouped_query_attention_with_sliding_window
+attention:
+  query_heads: 32
+  kv_heads: 8
+  sliding_window: 4096
+feed_forward:
+  intermediate_dim: 14336
+evidence:
+  - source: source:mistral-7b-paper
+    locator: '§2 Architectural details, Table 1'
+    fields:
+      - dimensions.layers
+      - dimensions.d_model
+      - dimensions.head_dim
+      - tokenization.vocab_size
+      - context.pretrained_length
+      - attention.query_heads
+      - attention.kv_heads
+      - attention.sliding_window
+      - feed_forward.intermediate_dim
+  - source: source:mistral-7b-paper
+    locator: 'Abstract and §2 Architectural details (GQA/SWA; Figure 3 causal mask)'
+    fields:
+      - topology.type
+      - components.attention

data/sources/llama-models-sku-list.yaml

@@ -0,0 +1,9 @@
+id: source:llama-models-sku-list
+type: source
+title: Meta Llama model SKU registry
+source_type: official_config
+url: https://github.com/meta-llama/llama-models/blob/0e0b8c519242d5833d8c11bffc1232b77ad7f301/models/sku_list.py
+publisher: Meta
+version: 0e0b8c519242d5833d8c11bffc1232b77ad7f301
+retrieved_at: '2026-09-29T21:06:00Z'
+notes: Pinned to the commit used to verify Llama 3.1 405B architecture arguments and packaging-dependent KV-head counts.

data/variants/llama-3.1-405b.yaml

@@ -0,0 +1,4 @@
+id: variant:llama-3.1-405b
+type: model_variant
+name: Llama 3.1 405B
+status: reviewed

docs/ontology.md

@@ -183,19 +183,39 @@ These use different edge types. Conceptual similarity must never imply checkpoin
 
 ## 7. Architecture representation
 
-Architecture records should support heterogeneous layer plans rather than assuming every block is identical.
+An `ArchitectureSpec` targets exactly one `ModelRelease` or `ModelVariant`. Architecture facts are stored as structured fields, and every populated fact must be mapped to evidence at field granularity. This keeps a compact manifest auditable without multiplying every architectural scalar into a separate claim record.
 
 ```yaml
+id: arch:example-model
+type: architecture_spec
+name: Example model architecture
+target: variant:example-model
+status: reviewed
+topology:
+  type: decoder_only
+dimensions:
+  layers: 61
 blocks:
   - range: [0, 2]
-    attention: component:mla
-    ffn: component:dense-swiglu
+    attention: multi_head_latent_attention
+    ffn: dense
   - range: [3, 60]
-    attention: component:mla
-    ffn: component:sparse-moe
+    attention: multi_head_latent_attention
+    ffn: sparse_moe
+evidence:
+  - source: source:example-technical-report
+    locator: '§4.2 Model Hyper-Parameters'
+    fields:
+      - topology.type
+      - dimensions.layers
+      - blocks
 ```
 
-Unknown values are represented as `null`; `null` does not mean zero or not applicable.
+`blocks.range` is zero-based and inclusive. Ranges must not overlap and must stay within the declared layer count when `dimensions.layers` is present. Heterogeneous plans may leave gaps when the source only establishes a subset of the layer plan.
+
+Evidence entries name the canonical source, the smallest useful locator, and the exact populated fact paths supported by that locator. Editorial `notes` are not treated as architecture facts. A populated field with no valid evidence is a validation error, as is evidence that points to an absent or `null` field.
+
+For architecture manifests, values that are not established at the target's granularity should normally be omitted. This is especially important when first-party checkpoint packaging exposes different values for what appears to be the same broader model variant; choosing one packaging value would overstate it as intrinsic architecture. `null` remains available when explicitly preserving a reviewed-but-unestablished slot is useful, and never means zero or not applicable.
 
 ## 8. Evaluation ontology
 

schemas/architecture.schema.json

@@ -3,11 +3,22 @@
   "$id": "https://modelmap.dev/schemas/architecture.schema.json",
   "title": "ModelMap ArchitectureSpec",
   "type": "object",
-  "required": ["id", "type", "name", "topology"],
+  "$defs": {
+    "evidenceField": {
+      "type": "string",
+      "pattern": "^(?:blocks|(?:topology|dimensions|tokenization|context|components|attention|feed_forward|modalities)\\.[a-z][a-z0-9_]*)$"
+    }
+  },
+  "required": ["id", "type", "name", "target", "status", "topology", "evidence"],
   "properties": {
     "id": {"type": "string", "pattern": "^arch:[a-z0-9][a-z0-9._-]*$"},
     "type": {"const": "architecture_spec"},
     "name": {"type": "string", "minLength": 1},
+    "target": {"type": "string", "pattern": "^(?:release|variant):[a-z0-9][a-z0-9._-]*$"},
+    "status": {
+      "type": "string",
+      "enum": ["draft", "reviewed", "canonical", "deprecated"]
+    },
     "topology": {
       "type": "object",
       "required": ["type"],
@@ -16,7 +27,8 @@
           "type": "string",
           "enum": ["decoder_only", "encoder_decoder", "encoder_only", "hybrid", "multimodal_hybrid", "unknown"]
         },
-        "pre_norm": {"type": ["boolean", "null"]}
+        "pre_norm": {"type": ["boolean", "null"]},
+        "post_norm": {"type": ["boolean", "null"]}
       },
       "additionalProperties": false
     },
@@ -63,6 +75,29 @@
       },
       "additionalProperties": false
     },
+    "attention": {
+      "type": "object",
+      "properties": {
+        "query_heads": {"type": ["integer", "null"], "minimum": 1},
+        "kv_heads": {"type": ["integer", "null"], "minimum": 1},
+        "sliding_window": {"type": ["integer", "null"], "minimum": 1},
+        "global_span": {"type": ["integer", "null"], "minimum": 1},
+        "kv_compression_dim": {"type": ["integer", "null"], "minimum": 1},
+        "query_compression_dim": {"type": ["integer", "null"], "minimum": 1}
+      },
+      "additionalProperties": false
+    },
+    "feed_forward": {
+      "type": "object",
+      "properties": {
+        "intermediate_dim": {"type": ["integer", "null"], "minimum": 1},
+        "expert_intermediate_dim": {"type": ["integer", "null"], "minimum": 1},
+        "shared_experts": {"type": ["integer", "null"], "minimum": 1},
+        "routed_experts": {"type": ["integer", "null"], "minimum": 1},
+        "active_routed_experts": {"type": ["integer", "null"], "minimum": 1}
+      },
+      "additionalProperties": false
+    },
     "blocks": {
       "type": "array",
       "items": {
@@ -91,6 +126,26 @@
       },
       "additionalProperties": false
     },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["source", "locator", "fields"],
+        "properties": {
+          "source": {"type": "string", "pattern": "^source:[a-z0-9][a-z0-9._-]*$"},
+          "locator": {"type": "string", "minLength": 1},
+          "fields": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {"$ref": "#/$defs/evidenceField"}
+          },
+          "note": {"type": ["string", "null"]}
+        },
+        "additionalProperties": false
+      }
+    },
     "notes": {"type": ["string", "null"]}
   },
   "additionalProperties": false