rickardvh · rickardvh · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026
diff --git a/README.md b/README.md
@@ -32,6 +32,7 @@ Generated runtimes should be self-contained with respect to this package. If a g
 - `generate_command_packages(..., check=True|False)` checks or writes generated files.
 - `CommandGenerationHostManifest` declares host roots, custom primitive registry entries, target bindings, and optional host-owned runtime support.
 - `PrimitiveRegistry` and `PrimitiveDefinition` describe portable or host-owned primitives with target support.
+- `TargetExtensionContract`, `validate_target_extension_contract(...)`, and `target_support_matrix_entries(...)` define how new generated targets declare projection rules, runtime dependencies, callable/wrapper shape, packaging, conformance execution, and matrix support without owning product semantics.
 - `process_case_from_contract(...)`, `CliConformanceTarget`, and `run_cli_conformance_case(...)` provide the generic black-box runner for contract-owned CLI/process conformance cases.
 - `operation_case_from_contract(...)`, `FunctionConformanceTarget`, and `run_function_conformance_case(...)` provide the generic JSON-shaped operation conformance runner for direct implementation adapters.
 - `contract_conformance_cases_manifest()` and `load_contract_conformance_case(...)` expose package-owned reusable conformance cases.
@@ -53,6 +54,12 @@ That split matters for conformance:
 - use process conformance for parser behavior, stdout/stderr, exit codes, and wrapper state;
 - do not let a CLI flag name become the semantic contract unless the operation input is intentionally named the same way.
 
+## Target Extension Contract
+
+Target implementations are declared with `command-generation/target-extension/v1`. The contract records target identity, projection rules, runtime dependency boundaries, direct operation callable shape, wrapper/adapter responsibilities, packaging layout, conformance execution, and support-declaration rules for matrix inclusion.
+
+Targets must not own product operation semantics or require per-operation feature maintenance. Ordinary behavior remains in host-owned operation IR, primitive refs, schemas, and input/output/error cases. Target maintenance is limited to runtime dependency updates, target compatibility work, and projection/runtime-adapter bugs.
+
 ## Conformance Strategy
 
 - Store behavior examples in host-owned contract resources as stable input/expected-output cases.

diff --git a/schemas/target_extension.schema.json b/schemas/target_extension.schema.json
@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://command-generation.local/schemas/target_extension.schema.json",
+  "title": "Command-generation target extension contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "target_id",
+    "implementation_status",
+    "projection_rules",
+    "runtime_dependencies",
+    "operation_callable_surface",
+    "wrapper_adapter_shape",
+    "packaging_output_layout",
+    "conformance_execution",
+    "support_declaration",
+    "product_semantics_boundary",
+    "maintenance_boundary"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "command-generation/target-extension/v1"
+    },
+    "target_id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_.-]*$"
+    },
+    "implementation_status": {
+      "enum": ["planned", "implemented"]
+    },
+    "projection_rules": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["source", "target_owns"],
+      "properties": {
+        "source": {
+          "const": "operation-ir"
+        },
+        "target_owns": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "runtime_dependencies": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["boundary"],
+      "properties": {
+        "boundary": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "operation_callable_surface": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["adapter_id", "input_model"],
+      "properties": {
+        "adapter_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "input_model": {
+          "const": "operation-values"
+        }
+      }
+    },
+    "wrapper_adapter_shape": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["owns"],
+      "properties": {
+        "owns": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "packaging_output_layout": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["owns"],
+      "properties": {
+        "owns": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "conformance_execution": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["runner", "case_model"],
+      "properties": {
+        "runner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "case_model": {
+          "const": "input-output-error"
+        }
+      }
+    },
+    "support_declaration": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["matrix_inclusion", "adapter_ids"],
+      "properties": {
+        "matrix_inclusion": {
+          "enum": ["automatic-when-target-implemented", "manual"]
+        },
+        "adapter_ids": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "product_semantics_boundary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["target_owns_product_semantics", "rule"],
+      "properties": {
+        "target_owns_product_semantics": {
+          "const": false
+        },
+        "rule": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "maintenance_boundary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["per_operation_feature_maintenance", "allowed"],
+      "properties": {
+        "per_operation_feature_maintenance": {
+          "const": false
+        },
+        "allowed": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}
diff --git a/src/command_generation/__init__.py b/src/command_generation/__init__.py
@@ -29,6 +29,13 @@
 from command_generation.ir import command_package_schema_path, load_command_package_ir
 from command_generation.primitive_registry import BUILTIN_PORTABLE_PRIMITIVES, PrimitiveDefinition, PrimitiveRegistry
 from command_generation.primitive_executor import PrimitiveContext, PrimitiveExecutionError, execute_primitive, run_operation_steps
+from command_generation.target_extension import (
+    TargetExtensionContract,
+    TargetExtensionContractError,
+    target_extension_schema_path,
+    target_support_matrix_entries,
+    validate_target_extension_contract,
+)
 
 __all__ = [
     "BUILTIN_PORTABLE_PRIMITIVES",
@@ -47,6 +54,8 @@
     "PrimitiveExecutionError",
     "ProcessConformanceCase",
     "PrimitiveRegistry",
+    "TargetExtensionContract",
+    "TargetExtensionContractError",
     "canonical_command_artifacts",
     "command_package_schema_path",
     "contract_conformance_cases_manifest",
@@ -66,4 +75,7 @@
     "run_operation_steps",
     "selected_contract_fields",
     "selected_result_fields",
+    "target_extension_schema_path",
+    "target_support_matrix_entries",
+    "validate_target_extension_contract",
 ]
diff --git a/src/command_generation/schemas/target_extension.schema.json b/src/command_generation/schemas/target_extension.schema.json
@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://command-generation.local/schemas/target_extension.schema.json",
+  "title": "Command-generation target extension contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "target_id",
+    "implementation_status",
+    "projection_rules",
+    "runtime_dependencies",
+    "operation_callable_surface",
+    "wrapper_adapter_shape",
+    "packaging_output_layout",
+    "conformance_execution",
+    "support_declaration",
+    "product_semantics_boundary",
+    "maintenance_boundary"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "command-generation/target-extension/v1"
+    },
+    "target_id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_.-]*$"
+    },
+    "implementation_status": {
+      "enum": ["planned", "implemented"]
+    },
+    "projection_rules": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["source", "target_owns"],
+      "properties": {
+        "source": {
+          "const": "operation-ir"
+        },
+        "target_owns": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "runtime_dependencies": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["boundary"],
+      "properties": {
+        "boundary": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "operation_callable_surface": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["adapter_id", "input_model"],
+      "properties": {
+        "adapter_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "input_model": {
+          "const": "operation-values"
+        }
+      }
+    },
+    "wrapper_adapter_shape": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["owns"],
+      "properties": {
+        "owns": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "packaging_output_layout": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["owns"],
+      "properties": {
+        "owns": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "conformance_execution": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["runner", "case_model"],
+      "properties": {
+        "runner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "case_model": {
+          "const": "input-output-error"
+        }
+      }
+    },
+    "support_declaration": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["matrix_inclusion", "adapter_ids"],
+      "properties": {
+        "matrix_inclusion": {
+          "enum": ["automatic-when-target-implemented", "manual"]
+        },
+        "adapter_ids": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "product_semantics_boundary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["target_owns_product_semantics", "rule"],
+      "properties": {
+        "target_owns_product_semantics": {
+          "const": false
+        },
+        "rule": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "maintenance_boundary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["per_operation_feature_maintenance", "allowed"],
+      "properties": {
+        "per_operation_feature_maintenance": {
+          "const": false
+        },
+        "allowed": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}