Merge pull request #5 from negillett/hardening

feat(spec): enforce generated models and release hardening

Author: negillett

.github/workflows/ci.yml

@@ -10,23 +10,97 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  no-handwritten-model-types:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/checkout@v6
+        with:
+          repository: IntentProof/intentproof-spec
+          path: intentproof-spec
+
+      - name: No handwritten model/types outside generated schema package
+        env:
+          INTENTPROOF_SPEC_ROOT: ${{ github.workspace }}/intentproof-spec
+        run: bash scripts/check-no-handwritten-model-types.sh
+
+  hardening:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/checkout@v6
+        with:
+          repository: IntentProof/intentproof-spec
+          path: intentproof-spec
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: intentproof-spec/.nvmrc
+          cache: npm
+          cache-dependency-path: intentproof-spec/package-lock.json
+
+      - name: SDK hardening contract audit (spec-only + drift guards)
+        run: bash intentproof-spec/scripts/check-sdk-hardening.sh "${{ github.workspace }}"
+
   intentproof-spec:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+
+      - uses: actions/checkout@v6
         with:
-          repository: intentproof/intentproof-spec
+          repository: IntentProof/intentproof-spec
           path: intentproof-spec
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version-file: intentproof-spec/.nvmrc
           cache: npm
           cache-dependency-path: intentproof-spec/package-lock.json
 
-      - name: Canonical spec conformance (Vitest oracle)
-        run: bash intentproof-spec/scripts/run-conformance.sh intentproof-spec
+      - name: Canonical spec conformance (pin check + oracle + replay)
+        env:
+          INTENTPROOF_SPEC_ROOT: ${{ github.workspace }}/intentproof-spec
+          INTENTPROOF_SDK_ID: python
+          INTENTPROOF_REPLAY_VERIFY: "1"
+          INTENTPROOF_CONFORMANCE_JSON: "1"
+        run: bash scripts/spec-conformance.sh
+
+      - name: Upload conformance report artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: conformance-report-python
+          path: intentproof-spec/conformance-report.json
+          if-no-files-found: error
+
+  spec-golden-parity:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/checkout@v6
+        with:
+          repository: IntentProof/intentproof-spec
+          path: intentproof-spec
+
+      - uses: ./.github/actions/setup-python-pip
+        with:
+          python-version: "3.13"
+          check-latest: false
+
+      - name: Install project (dev extras)
+        run: pip install -e ".[dev]"
+
+      - name: Golden execution_event JSONL parity (schema + semantics)
+        env:
+          INTENTPROOF_SPEC_ROOT: ${{ github.workspace }}/intentproof-spec
+        run: pytest tests/unit/test_spec_golden_conformance.py -v
 
   audit:
     runs-on: ubuntu-latest
@@ -71,6 +145,11 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - uses: actions/checkout@v6
+        with:
+          repository: IntentProof/intentproof-spec
+          path: intentproof-spec
+
       - uses: ./.github/actions/setup-python-pip
         with:
           python-version: ${{ matrix.python-version }}
@@ -80,4 +159,6 @@ jobs:
         run: pip install "tox>=4"
 
       - name: Run tox
+        env:
+          INTENTPROOF_SPEC_ROOT: ${{ github.workspace }}/intentproof-spec
         run: tox run -e ${{ matrix.tox-env }}

.github/workflows/release.yml

@@ -15,20 +15,78 @@ on:
     tags:
       - "v*"
 
+permissions:
+  contents: read
+  checks: read
+
 jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Verify required CI checks passed on release SHA
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const requiredExact = ["no-handwritten-model-types", "hardening", "intentproof-spec", "spec-golden-parity"];
+            const requiredPrefixes = ["tox (static", "tox (cov"];
+            const { owner, repo } = context.repo;
+            const ref = context.sha;
+            const runs = await github.paginate(github.rest.checks.listForRef, {
+              owner,
+              repo,
+              ref,
+              per_page: 100,
+            });
+            const names = runs.map((r) => `${r.name}:${r.conclusion ?? r.status}`);
+            core.info(`check-runs on ${ref}: ${names.join(", ")}`);
+            for (const name of requiredExact) {
+              const matches = runs.filter((r) => r.name === name);
+              if (matches.length === 0) {
+                core.setFailed(`Missing required check-run: ${name}`);
+                continue;
+              }
+              const ok = matches.some((r) => r.conclusion === "success");
+              if (!ok) {
+                core.setFailed(`Required check-run not successful: ${name}`);
+              }
+            }
+            for (const prefix of requiredPrefixes) {
+              const matches = runs.filter((r) => r.name.startsWith(prefix));
+              if (matches.length === 0) {
+                core.setFailed(`Missing required check-run prefix: ${prefix}`);
+                continue;
+              }
+              const ok = matches.some((r) => r.conclusion === "success");
+              if (!ok) {
+                core.setFailed(`Required check-run prefix not successful: ${prefix}`);
+              }
+            }
+
   publish:
+    needs: preflight
     runs-on: ubuntu-latest
     permissions:
       id-token: write
       contents: read
     steps:
       - uses: actions/checkout@v6
 
+      - uses: actions/checkout@v6
+        with:
+          repository: IntentProof/intentproof-spec
+          path: intentproof-spec
+
       - uses: ./.github/actions/setup-python-pip
         with:
           python-version: "3.x"
           check-latest: true
 
+      - name: No handwritten model/types outside generated schema package
+        env:
+          INTENTPROOF_SPEC_ROOT: ${{ github.workspace }}/intentproof-spec
+        run: bash scripts/check-no-handwritten-model-types.sh
+
       - name: Verify tag matches pyproject.toml version
         env:
           TAG_NAME: ${{ github.ref_name }}

CHANGELOG.md

@@ -1,17 +1,28 @@
 # Changelog
 
-Repository: [IntentProof Python SDK (`intentproof-sdk-python`)](https://github.com/intentproof/intentproof-sdk-python).
+Repository: [IntentProof Python SDK (`intentproof-sdk-python`)](https://github.com/IntentProof/intentproof-sdk-python).
 
 All notable changes to this repository are documented here. **PyPI** releases use SemVer for the **`intentproof-sdk`** distribution (`version` in [`pyproject.toml`](pyproject.toml)); tag releases in Git to match published versions.
 
 ## Unreleased
 
+- Add spec-driven generated models package under `src/intentproof/generated` (`execution_event`, `intentproof_config`, `normative_schemas`, and package exports) and switch SDK type aliases/wire paths to these generated schema models.
+- Add schema validation helpers in `src/intentproof/schema_validate.py` for execution events, wrap options, and runtime config; export them from `intentproof.__init__`.
+- Add deterministic codegen pipeline (`scripts/generate_schema_models.py`) that writes embedded normative schemas plus `src/intentproof/generated/spec_fingerprint.json` (spec version + per-schema/aggregate SHA-256 digests).
+- Add generated artifact drift checks (`scripts/verify-generated-types.sh`) and bundled schema guard (`scripts/check-no-bundled-schema.sh`) for release hygiene.
+- Add explicit no-handwritten-model policy enforcement (`scripts/check-no-handwritten-model-types.sh`) by delegating to the shared `intentproof-spec` checker, with a dedicated CI check-run (`no-handwritten-model-types`), the same step in **`tox -e static`** and release publish (parity with Node/Java), and release preflight gating on that check.
+- Strengthen CI/release hardening: add `hardening` job, enforce required check-runs in release preflight, and upload canonical conformance report artifact (`conformance-report-python`).
+- Improve spec-conformance wrapper (`scripts/spec-conformance.sh`) with strict spec pin verification (`scripts/check-sdk-spec-pin.sh`), standardized report metadata (`INTENTPROOF_SDK_NAME`, `INTENTPROOF_SDK_LANGUAGE`, `INTENTPROOF_SDK_VERSION`), and `./intentproof-spec` fallback when the env var and sibling clone are absent.
+- Pin `datamodel-code-generator` in `pyproject.toml` for stable code generation and make generated headers deterministic (no timestamp/random temp filenames).
+- Add/expand tests for spec semantics and generated artifacts: `tests/spec_semantics.py`, `tests/unit/test_spec_golden_conformance.py`, `tests/unit/test_schema_validate.py`, `tests/unit/test_generated_fingerprint.py`, with related SDK/exporter/wire test updates.
+- Update docs (`README.md`) and local quality wiring (`tox.ini`) to reflect spec-first model generation, dedicated policy gating, and deduplicated CI enforcement.
+- CI: **`no-handwritten-model-types`** job only checks out the SDK + spec and runs the delegated script (no **`pip install`**); **push** triggers also include **`master`** (parity with Node/Java).
 ## 0.1.1 — 2026-05-04
 
 - **Security:** upgrade **pip** to **≥26.1** after Python setup in the composite **`.github/actions/setup-python-pip`** action, and in the default **`[testenv]`** via **`commands_pre`**, addressing **CVE-2026-3219** and **CVE-2026-6357**.
-- **CI:** add **`intentproof-spec`** job—checkout [`intentproof-spec`](https://github.com/intentproof/intentproof-spec) and run **`scripts/run-conformance.sh`** (canonical Vitest conformance oracle).
+- **CI:** add **`intentproof-spec`** job—checkout [`intentproof-spec`](https://github.com/IntentProof/intentproof-spec) and run **`scripts/run-conformance.sh`** (canonical Vitest conformance oracle).
 - **Local spec checks:** add **`scripts/spec-conformance.sh`** and **`tox -e spec`** (sibling **`../intentproof-spec`** or **`INTENTPROOF_SPEC_ROOT`**).
-- **Docs:** add this **`CHANGELOG.md`** (aligned with the [spec repo changelog](https://github.com/intentproof/intentproof-spec/blob/main/CHANGELOG.md)); refresh **`README.md`**—positioning, pinned PyPI/GitHub install guidance, reorganized API reference tables, **`intentproof-spec`** section, vulnerability reporting link, and related edits.
+- **Docs:** add this **`CHANGELOG.md`** (aligned with the [spec repo changelog](https://github.com/IntentProof/intentproof-spec/blob/main/CHANGELOG.md)); refresh **`README.md`**—positioning, pinned PyPI/GitHub install guidance, reorganized API reference tables, **`intentproof-spec`** section, vulnerability reporting link, and related edits.
 - **Packaging metadata:** update **`description`** and **`keywords`** in **`pyproject.toml`**.
 - **Repo layout:** remove **`.gitlab-ci.yml`** (GitLab CI mirror).
 

README.md

@@ -342,7 +342,9 @@ Custom **`body`** serializers: if **`body(event)`** raises, **`HttpExporter`** n
 
 Schemas, golden oracles, and the **Vitest conformance oracle** live in the **[IntentProof specification repository (`intentproof-spec`)](https://github.com/intentproof/intentproof-spec)**.
 
-- **CI:** every push/PR runs `scripts/run-conformance.sh` from that repo (see `.github/workflows/ci.yml`).
+- **Version pin:** **`[tool.intentproof].spec-version`** in **`pyproject.toml`** matches **`spec.json`** in that repo; **`scripts/check-sdk-spec-pin.sh`** enforces it before conformance.
+
+- **CI:** every push/PR checks out this SDK plus **`intentproof-spec`** and runs **`scripts/spec-conformance.sh`** (pin check + full oracle; see `.github/workflows/ci.yml`). The **`spec-golden-parity`** job runs **`tests/unit/test_spec_golden_conformance.py`** against the same **`golden/execution_event_cases.jsonl`** using **`jsonschema`** + semantics mirrored from the spec (`tests/spec_semantics.py`).
 - **Local:** clone `intentproof-spec` **next to** this repository (`../intentproof-spec`), then:
 
   ```bash
@@ -351,6 +353,14 @@ Schemas, golden oracles, and the **Vitest conformance oracle** live in the **[In
 
   Or set `INTENTPROOF_SPEC_ROOT` and run `bash scripts/spec-conformance.sh`.
 
+- **Generated fingerprint metadata:** model generation writes **`src/intentproof/generated/spec_fingerprint.json`** (spec version, generator version, per-schema SHA-256, aggregate hash). Validate/update generated artifacts with:
+
+  ```bash
+  bash scripts/verify-generated-types.sh
+  ```
+
+- **No handwritten model types:** **`scripts/check-no-handwritten-model-types.sh`** delegates to the shared **`intentproof-spec`** checker. It runs in CI (dedicated **`no-handwritten-model-types`** job—SDK + spec checkout and **`python3`** only—and **`tox -e static`**), release publish, and release preflight required checks, and fails if schema model class definitions appear outside **`src/intentproof/generated`** or if the bridge aliases in **`src/intentproof/types.py`** stop mapping to generated models.
+
 ---
 
 ## Project development

pyproject.toml

@@ -26,12 +26,16 @@ classifiers = [
   "Typing :: Typed",
 ]
 
-dependencies = []
+dependencies = [
+    "jsonschema>=4.23",
+    "pydantic>=2.10",
+]
 
 [project.optional-dependencies]
 dev = [
-  "build>=1.2",
-  "coverage[toml]>=7.4",
+    "build>=1.2",
+    "coverage[toml]>=7.4",
+    "datamodel-code-generator==0.56.1",
   "pip-audit>=2.7",
   "pytest>=8.0",
   "pytest-asyncio>=0.24",
@@ -40,6 +44,10 @@ dev = [
   "tox>=4",
 ]
 
+[tool.intentproof]
+# Must match https://github.com/intentproof/intentproof-spec/blob/main/spec.json — enforced by scripts/check-sdk-spec-pin.sh
+spec-version = "spec-v1.0.0"
+
 [project.urls]
 Homepage = "https://github.com/intentproof/intentproof-sdk-python"
 Repository = "https://github.com/intentproof/intentproof-sdk-python"
@@ -84,6 +92,7 @@ exclude_lines = [
 target-version = "py311"
 line-length = 100
 src = ["src", "tests"]
+extend-exclude = ["src/intentproof/generated"]
 
 [tool.ruff.format]
 quote-style = "double"

scripts/check-no-bundled-schema.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# SDK repos must not ship duplicate JSON Schema artifacts; intentproof-spec is canonical.
+set -euo pipefail
+repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo"
+
+mapfile -t schema_paths < <(find . \
+  \( -path ./.git -o -path ./.tox -o -path ./.venv -o -path ./dist -o -path ./build \) -prune \
+  -o -name '*.schema.json' -print)
+
+bad=0
+for p in "${schema_paths[@]}"; do
+  case "$p" in
+    ./intentproof-spec/schema/*.schema.json) ;;
+    *)
+      if [[ $bad -eq 0 ]]; then
+        echo "check-no-bundled-schema: only ./intentproof-spec/schema/*.schema.json is allowed." >&2
+      fi
+      echo "$p"
+      bad=1
+      ;;
+  esac
+done
+
+if [[ $bad -ne 0 ]]; then
+  exit 1
+fi
+
+echo "OK: no bundled *.schema.json"

scripts/check-no-handwritten-model-types.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Wrapper: run shared no-handwritten-model/types policy from intentproof-spec.
+set -euo pipefail
+
+sdk_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+spec_root="${INTENTPROOF_SPEC_ROOT:-}"
+
+if [[ -z "${spec_root}" ]]; then
+  sibling="${sdk_root}/../intentproof-spec"
+  if [[ -f "${sibling}/spec.json" ]]; then
+    spec_root="$(cd "${sibling}" && pwd)"
+  fi
+fi
+
+if [[ -z "${spec_root}" ]]; then
+  in_repo="${sdk_root}/intentproof-spec"
+  if [[ -f "${in_repo}/spec.json" ]]; then
+    spec_root="$(cd "${in_repo}" && pwd)"
+  fi
+fi
+
+if [[ -z "${spec_root}" || ! -f "${spec_root}/scripts/check-sdk-no-handwritten-model-types.sh" ]]; then
+  echo "check-no-handwritten-model-types: intentproof-spec checkout not found (set INTENTPROOF_SPEC_ROOT or clone ../intentproof-spec)" >&2
+  exit 1
+fi
+
+exec bash "${spec_root}/scripts/check-sdk-no-handwritten-model-types.sh" "${sdk_root}"

scripts/check-sdk-spec-pin.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Fail if this SDK's declared IntentProof spec version does not match spec.json from the checkout.
+# Usage: check-sdk-spec-pin.sh /absolute/or/relative/path/to/intentproof-spec
+set -euo pipefail
+
+spec_root="$(cd "$1" && pwd)"
+sdk_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if [[ ! -f "${spec_root}/spec.json" ]]; then
+  echo "check-sdk-spec-pin: not a spec checkout (missing spec.json): ${spec_root}" >&2
+  exit 2
+fi
+
+spec_version="$(python3 -c "import json, pathlib, sys; print(json.loads(pathlib.Path(sys.argv[1]).read_text())['version'])" "${spec_root}/spec.json")"
+
+declared="$(cd "$sdk_root" && python3 -c "
+import tomllib
+from pathlib import Path
+p = Path('pyproject.toml')
+data = tomllib.loads(p.read_text(encoding='utf-8'))
+print(data['tool']['intentproof']['spec-version'])
+")"
+
+if [[ "$declared" != "$spec_version" ]]; then
+  echo "check-sdk-spec-pin: pyproject [tool.intentproof] spec-version=${declared} but spec.json version=${spec_version}" >&2
+  exit 1
+fi
+
+echo "SDK spec pin OK (${spec_version})"