Add target-node CPU architecture semantics to SDL

[Brad-Edwards]

Gap

The SDL Node model has no CPU architecture attribute. Resources carries only RAM and CPU count; the existing runtime-package architecture field describes a package artifact, not the architecture required by the target node or guest.

That prevents an authored environment from expressing a realization-relevant node constraint and makes cross-backend equivalence ambiguous.

Current ownership boundary

This issue covers only the architecture semantics of the node described by SDL.

• RAES owns the controlled architecture value, schema placement, validation, normalization, and compatibility semantics between a target node and its runtime packages.
• env-packs, adapters, and backends own physical runner/host capability declarations, selection, negotiation, and realization evidence.
• A backend manifest may say what a host can provide; it must not replace what the SDL says the target node requires.

Outcome

Add a first-class target-node CPU architecture requirement with a governed vocabulary and deterministic compatibility rules.

Acceptance criteria

• The schema distinguishes target-node architecture from runtime-package architecture and backend host architecture.
• Canonical vocabulary, aliases, normalization, and unknown/custom-value behavior are explicit.
• Validation defines compatibility between a target node and each architecture-constrained package.
• Absence has defined semantics and does not silently mean the current host architecture.
• Generated contracts, examples, and semantic-diff behavior cover the field.
• A conformant backend can report whether it can realize the requirement without RAES selecting a runner.

Non-goals

• Modeling a specific cloud instance, runner image, or deployment host.
• Backend scheduling or capability negotiation.
• Assuming target-node and physical-host architectures are always identical.

Refs: #637 and adapters #21.

Requirements

• DSL-438

[Brad-Edwards]

🛠️ Picked up by /implement - driver claude-code, branch 674-node-cpu-architecture, 2026-08-02T05:45:23.850Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #674). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #674). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Plan — Add target-node CPU architecture semantics to SDL (#674)

Requirement-free run; the issue is the delivery contract. Design bound by the architecture-preflight note docs/decisions/issue-674-target-node-cpu-architecture-preflight.md (no new ADR — governed by ADR-001 SDL intent/realization split, ADR-009/061 contract authority + evolution, ADR-012 portable vocabularies, ADR-008/036 processor boundaries, ADR-070 configuration-bound realization).

What ships

A first-class optional Node.architecture VM field: the CPU architecture the target node/guest requires. It is distinct from the runtime-package artifact architecture (RuntimePackage.architecture) and from the backend host/realizer architecture (RealizerConfigurationModel.architecture). It mirrors the existing Node.os / OS-family wiring at every layer (model → schema → concept-authority vocabulary → phase contracts/variables → compiler → planner admission → realization concern → backend manifests → realization envelope), so no new subsystem is introduced.

Binding semantics (from preflight)

• Vocabulary. One governed vocabulary. Initial canonical set is deliberately small: x86_64 (aliases amd64, x64, x86-64) and aarch64 (alias arm64). Normalization is case-insensitive with the existing hyphen→underscore rule applied before alias resolution; canonical serialization always emits the canonical token.

• Unknown/custom. Unknown unqualified strings fail closed. A custom value is admitted only in the existing governed-extension form x-<owner>:<term> (canonical lowercase), matched by the concept-authority extension pattern; custom values compare by exact token, no aliases. Ambiguous family labels (x86, arm) and package-portability classifiers (noarch, any, all) are rejected. No other/unknown sentinel — absence already expresses "no requirement".

• Absence. Absent means no authored architecture requirement. It never means the controller/host/runner/QEMU-default/image/package architecture. Absence stays absent through normalization and semantic comparison.

• Compatibility (deterministic, exact, fail-closed). For each node, across its runtime.packages[]:

  1. node absent + every package arch empty → valid (no requirement);
  2. node present + package arch empty → valid (package not architecture-constrained);
  3. node present + package arch present → valid iff normalized canonical values are exactly equal;
  4. node absent + any package arch present → invalid (package metadata must not become an implicit target-node requirement).

  Rule 4 is a published, fail-closed semantic tightening under ADR-061 (recorded in the schema-publication ledger + regression coverage). Variables defer the comparison to instantiation; finite allowed_values are normalized with the same function and re-checked after binding.

• Backend reporting (criterion 6). A node-architecture realization concern is compiled from the authored field; realization_support_diagnostics() reports whether a backend can realize it via supported_constraint_kinds; a new supported_node_architectures provisioner-capability set drives pre-mutation admission. Empty/absent set = no claim, and fails only nodes that explicitly require an architecture. No runner selection or scheduling is added.

Acceptance-criteria mapping

• Schema distinguishes target vs package vs host arch → new Node.architecture (target), unchanged RuntimePackage.architecture (package, now canonical-token normalized), unchanged RealizerConfigurationModel.architecture (host).
• Vocabulary/aliases/normalization/custom explicit → NodeArchitecture enum + raes/architectures.py normalizer/alias map + governed provisioner-node-architectures catalog vocabulary + x-<owner>:<term> extension.
• Compatibility defined → semantic-validator node pass (rules 1–4).
• Absence has defined semantics → normalizer keeps absent absent; documented; rule 4 forbids implicit inference.
• Generated contracts/examples/semantic-diff cover it → all four Node-bearing schemas regenerated + publication ledger; example updated; semantic-comparison tests extended (alias-only equal, presence/canonical-diff = semantic change).
• Backend can report realizability → realization concern + supported_node_architectures + supported_constraint_kinds + support diagnostics.

Changes (TDD, by layer — test-first at each)

1. Vocabulary + model (raes/)

• New raes/architectures.py: NodeArchitecture(str, Enum) = X86_64/AARCH64; ARCHITECTURE_ALIASES; ARCHITECTURE_EXTENSION_PATTERN; normalize_architecture()/parse_architecture_or_var() (var passthrough → extension-token validate → alias→canonical enum → else fail closed); architectures_compatible(node, pkg). Single source of truth (no duplicate alias maps).
• nodes.py: Node.architecture: NodeArchitecture | str | None = None + normalize_architecture field validator; add "architecture" to _populated_vm_only_fields (switch rejects it); export in __all__.
• runtime_configuration.py: RuntimePackage.architecture gains a before-validator normalizing populated values to canonical tokens (empty stays empty = unconstrained).

2. Compatibility validation (raes/validator/_nodes_infra_network.py)

• New pass in _verify_nodes implementing rules 1–4 via self._err(...) (canonical semantic pass; runs again post-binding). No relational logic placed in child models.

3. Phase contracts / variables / composition / SAT

• phase_contracts.py:171-176 and scenario.py:104 allowlists: add ("nodes","architecture"); scenario.py _constraint_node_refs architecture branch.
• instantiate.py _capture_capability_constraints: emit /nodes/<id>/architecture finite-domain constraint from node.architecture.
• models/runtime_model.py:85 CompiledCapabilityConstraint concern allowlist: add "nodes.architecture". (composition._prefixed_constraint is field-agnostic — no change.)
• satisfiability/_translation.py: add ["nodes",_,"architecture"] → {m.value for m in NodeArchitecture} string-domain case.

4. Compiler (raes_processor/)

• models/resources.py NodeRuntime: add architecture: str = "".
• compiler/provisioning.py _record_node_runtime: architecture=node_spec.get("architecture","") or "". (_compile_capability_constraints derives concern nodes.architecture automatically.)

5. Planner admission (raes_processor/planner/)

• capability_domains.py: _validate_node_architecture (+ _architecture_allowed_value(s)) mirroring the os-family finite-domain check against supported_node_architectures.
• manifest_validation.py: call it alongside _validate_node_os_family.

6. Realization concern (raes_processor/semantics/realization_concerns.py)

• New descriptor section="nodes", authored_path=("architecture",), concern_kind="node-architecture", payload_path=("architecture",). Flows through realization_requirements.py and realization_support_diagnostics() automatically (reuses existing RealizationConcern.ARCHITECTURE, ConcernDisposition, ObservationStrength — no new envelope concern).

7. Concept-authority vocabulary

• contracts/concept-authority/controlled-vocabularies-v1.json: new provisioner-node-architectures (kind=vocabulary, governed-extension, terms x86_64/aarch64, scope capabilities.provisioner.supported_node_architectures); sync the generated copy under contracts/schemas/concept-authority/.
• raes_contracts/contracts/base.py: add scope to _BACKEND_CONCEPT_BINDING_SCOPES.
• specs/concept-authority/controlled-vocabularies.md: add "node CPU architectures" to the governed-extension list.

8. Backend capability + manifests

• raes_backend_protocols/provisioner_capabilities.py: supported_node_architectures: frozenset[str] = frozenset() (optional — empty = no claim), validated via validate_controlled_vocabulary_scope_values; provisioner_manifest.py serialize/rehydrate.
• raes_contracts/contracts/capabilities.py ProvisionerCapabilitiesModel: optional supported_node_architectures: list[...] = [] + controlled-vocab validation (regenerates backend-manifest-v2 schema).
• raes_reference_backend/manifest.py, raes_backend_stubs/manifest.py: declare supported_node_architectures={"x86_64","aarch64"}, add "node-architecture" to supported_constraint_kinds, add ConceptBinding for the new scope.
• raes_backend_libvirt/: supported_node_architectures from configuration (no hard-coded x86_64); manifest constraint kind + ConceptBinding; add an architecture dimension to capability_envelope.py (mirror os-family row) + _payload._architecture, so out-of-envelope target architecture fails closed.

9. Realization envelope agreement (raes_contracts/realization_envelope_carrier.py)

• Normalize RealizerConfigurationModel.architecture canonically and require agreement with the provisioner supported_node_architectures used for admission. Envelope stays configuration-bound evidence; never overwrites authored intent.

10. Schemas + publication

• Regenerate the four Node-bearing schemas (sdl-authoring-input-v1, instantiated-scenario-v1, instantiated-scenario-snapshot-v1, scenario-satisfiability-evidence-v1) + backend-manifest-v2 via tools/generate_contract_schemas.py; update each contracts/schema-publication/entries/*.json (content_hash + last_change summary via schema_content_hash()); keep schema_bundle() parity so check_generated_schemas.py passes. Record rule-4 tightening in the SDL entry's last_change (ADR-061).

11. Examples + specs

• Add architecture: x86_64 to a representative VM node in examples/scenarios/techvault.sdl.yaml (verify example-library + conformance gates).
• Document the field in specs/sdl/sections.md (+ runtime-inventory where package arch is described).

Tests (mirroring the os-family suite)

Model/normalizer/compat (test_sdl_models.py, new normalizer tests, test_runtime_models.py), switch-rejection parametrize, phase-contract/instantiate finite-domain (test_runtime_planner.py), compiler NodeRuntime, realization concern (test_sem_218_realization*.py), provisioner capability + backend manifests (test_backend_manifest.py, reference/stub/libvirt manifest + realization tests, test_out_of_envelope analog), controlled-vocab catalog (test_controlled_vocabularies.py id set), semantic comparison / envelope contract, schema conformance/publication, example conformance. Security-enforcing behavior (compat fail-closed, out-of-envelope rejection) gets behavioral tests that go red if the enforcement is removed.

Whole-repo / security / maintainability / extensibility

• Security: architecture is bounded non-secret declarative tokens; no host names, argv, env, subprocess, or probe output crosses raes_runtime.backend_calls; guest uname -m remains realization evidence, never intent. One normalizer/vocabulary across SDL, package, variable-domain, capability, envelope, and schema surfaces (single validation seam).
• Maintainability/reuse: builds on incumbents (SDLModel, _populated_vm_only_fields, normalize_enum_value, parse_enum_or_var, the collect-all SemanticValidator, NodeRuntime, the realization-concern registry, validate_controlled_vocabulary_scope_values, schema_bundle()); no parallel DTOs/alias maps/diff code.
• Extensibility: the seam is the governed term/alias table + finite-domain path + supported_node_architectures. Adding an architecture is a concept-authority/parity edit, not planner/backend conditionals. Field stays singular; ABI/endianness/CPU-features are out of scope, reserved for separately-typed future companions.
• Whole-repo view: all four Node-bearing schemas, publication metadata, controlled vocabulary, generated parity, examples, semantic diff, phase, planner, backend manifests, envelope, and conformance treated as one compatibility surface.

Mandatory plan rules

Run check_repo_policy.py, check_requirement_governance.py, verify_all.py before completion. No CHANGELOG.md/changelog.d edits and no _version.py bump (Release Please owns them). Schema-publication ledger updated for every changed published schema (ADR-009 §7). No authority-bearing artifacts outside specs/, contracts/, docs/, implementations/. PR title will be a feat: Conventional Commit that passes check_pr_title.py.

Risk

Broad blast radius (~30 files, ~10 packages) but each touchpoint is a mechanical mirror of the audited os-family wiring. The one behavioral change beyond additions is compatibility rule 4 (fail-closed) — no existing example/fixture sets a package architecture, so nothing currently breaks; it is published under ADR-061 with regression coverage.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #674 (branch 674-node-cpu-architecture)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: ship-with-fixes

The change has the right overall seam: it introduces a single portable architecture vocabulary, carries it through SDL normalization, semantic compatibility, compilation, capability admission, backend declarations, and published artifacts rather than inferring from host state. The cross-cutting propagation is disciplined and leaves the obvious extension path—governed custom tokens and capability declarations—open. However, the generated normative schemas do not preserve the fail-closed vocabulary boundary that the runtime implementation establishes.

Blocking findings (1):

1. [class] Published Node schemas accept arbitrary architecture tokens — contracts/schemas/sdl/sdl-authoring-input-v1.json:5019
   Each Node.architecture schema unions NodeArchitecture with an unrestricted string branch, so published-contract consumers accept values such as sparc, arm, or arbitrary text despite the SDL parser and stated contract requiring canonical values, aliases, or governed x-<owner>:<term> extensions. This makes the external schema boundary materially broader than the portable vocabulary and permits invalid documents to pass schema validation before reaching a different validator. Encode the permitted extension/variable forms in the schemas (with the authoring aliases where applicable) so all Node-bearing normative contracts enforce the same boundary.

Security review

Verdict: ship

This change introduces target-node architecture as a governed declarative constraint and carries it through parsing, semantic package compatibility, compilation, capability admission, backend manifests, and published schemas. The design seam is coherent: normalization is centralized, package/node agreement is enforced before planning, and backend support is declared rather than inferred from host state. I found no concrete, exploitable security regression in the supplied diff.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #674 on branch '674-node-cpu-architecture'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #674)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: The change has the right overall seam: it introduces a single portable architecture vocabulary, carries it through SDL normalization, semantic compatibility, compilation, capability admission, backend declarations, and published artifacts rather than inferring from host state. The cross-cutting propagation is disciplined and leaves the obvious extension path—governed custom tokens and capability declarations—open. However, the generated normative schemas do not preserve the fail-closed vocabulary boundary that the runtime implementation establishes.

Security reviewer: This change introduces target-node architecture as a governed declarative constraint and carries it through parsing, semantic package compatibility, compilation, capability admission, backend manifests, and published schemas. The design seam is coherent: normalization is centralized, package/node agreement is enforced before planning, and backend support is declared rather than inferred from host state. I found no concrete, exploitable security regression in the supplied diff.

Blocking findings: 1

Finding 1 — class (4 instances)

• ID: F1
• Title: [core] Published Node schemas accept arbitrary architecture tokens
• Location: contracts/schemas/sdl/sdl-authoring-input-v1.json:5019
• Decision: fix
• Rationale: Each Node.architecture schema unions NodeArchitecture with an unrestricted string branch, so published-contract consumers accept values such as sparc, arm, or arbitrary text despite the SDL parser and stated contract requiring canonica…
• Instances:
  • contracts/schemas/sdl/sdl-authoring-input-v1.json:5019
  • contracts/schemas/sdl/instantiated-scenario-v1.json:5824
  • contracts/schemas/sdl/instantiated-scenario-snapshot-v1.json:6467
  • contracts/schemas/satisfiability/scenario-satisfiability-evidence-v1.json:5315

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #674

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 674-node-cpu-architecture
Cycle: 1 / 1
Findings: 0 (clean run)