Dev

.github/workflows/ci.yml

@@ -20,14 +20,14 @@ jobs:
   verify:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
       - name: Install uv
-        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8
       - name: Resolve policy base revision
         id: base
         run: |
@@ -58,20 +58,20 @@ jobs:
           uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify -- "${verify_args[@]}"
       - name: Upload coverage report
         if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: coverage-report
           path: implementations/python/coverage.xml
 
   fuzz:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
       - name: Install uv
-        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8
       - name: Run fuzz session
         run: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s fuzz
 
@@ -82,12 +82,12 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
       - name: Install uv
-        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8
       - name: Probe for a container runtime
         id: runtime
         run: |
@@ -110,17 +110,17 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
       - name: Install uv
-        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8
       - name: Run OSV-scanner (advisory)
         run: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s osv_scan
       - name: Upload OSV-scanner report
         if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: osv-scanner-report
           path: implementations/python/osv-scanner-report.json
@@ -131,14 +131,14 @@ jobs:
     needs: [verify]
     if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:
           fetch-depth: 0
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: coverage-report
           path: implementations/python/
       - name: SonarCloud Scan
-        uses: SonarSource/sonarqube-scan-action@299e4b793aaa83bf2aba7c9c14bedbb485688ec4 # v7
+        uses: SonarSource/sonarqube-scan-action@713881670b6b3676cda39549040e2d88c70d582e # v8
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+# Build the Sphinx documentation on every PR (as a breakage check) and publish it
+# to GitHub Pages on pushes to the default branch. Pages must be enabled with the
+# "GitHub Actions" build source (Settings -> Pages) for the deploy job to succeed.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main, dev]
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8
+      - name: Build Sphinx docs
+        run: |
+          uv sync --extra docs --directory implementations/python
+          implementations/python/.venv/bin/sphinx-build -W --keep-going -b html docs docs/_build/html
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.github/workflows/pr-title-lint.yml

@@ -34,10 +34,10 @@ jobs:
       # tools/check_pr_title.py must not be able to weaken its own required
       # check (codex review finding, issue #567). The shared validator is still
       # exercised against the PR's own code by the test suite in ci.yml.
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:
           ref: ${{ github.event.pull_request.base.sha }}
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
       - name: Validate PR title

.github/workflows/release-please.yml

@@ -36,7 +36,7 @@ jobs:
       release_created: ${{ steps.rp.outputs.release_created }}
       tag_name: ${{ steps.rp.outputs.tag_name }}
     steps:
-      - uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
         id: rp
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -52,16 +52,16 @@ jobs:
       contents: write   # upload the built distributions to the Release
       id-token: write   # OIDC trusted publishing to PyPI (no stored token)
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8
 
       - name: Build the corpus-bundled wheel + sdist
         run: uv build --out-dir dist implementations/python
@@ -114,7 +114,7 @@ jobs:
       contents: read
       pull-requests: write
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:
           fetch-depth: 0
       - name: Open the back-merge PR (main -> dev)

contracts/README.md

@@ -7,6 +7,8 @@ The goal of this bucket is organizational clarity:
 - `schemas/` contains published contract schemas
 - `fixtures/` contains valid and invalid payload corpora for those contracts
 - `profiles/` contains capability profile declarations
+- `realization-envelopes/` contains configuration-bound backend realization
+  declarations whose identity is carried through manifests, plans, and snapshots
 
 `schema-publication-manifest.json` is the authoritative publication inventory
 for the current machine-readable schema set. The contracts verification gate

contracts/fixtures/asset-trust/reusable-asset-trust-policy-v1/invalid/authenticity-without-threshold.json

@@ -2,6 +2,30 @@
   "schema_version": "reusable-asset-trust-policy/v1",
   "policy_id": "aces-reusable-asset-trust-policy",
   "families": [
+    {
+      "asset_family": "associated_artifact_set",
+      "identity_basis": "associated-artifact-manifest-v1 canonical parent-plus-reference-set digest",
+      "evidence_requirements": [
+        {
+          "evidence_class": "integrity_digest",
+          "enforcement": "required",
+          "mechanism_ref": "associated-artifact-set/v1 derived set_digest",
+          "description": "The set digest binds the exact parent reference and keyed artifact-reference set without changing parent identity."
+        },
+        {
+          "evidence_class": "artifact_checksum",
+          "enforcement": "required",
+          "mechanism_ref": "validate_associated_artifact_manifest bounded concrete-byte validation",
+          "description": "Every referenced payload checksum and size is recomputed from an explicitly supplied bounded byte stream."
+        },
+        {
+          "evidence_class": "authenticity_signature",
+          "enforcement": "optional",
+          "mechanism_ref": "downstream signature over the derived associated-artifact set digest",
+          "description": "A signature may authenticate the set digest, but neither the digest nor payload checksums establish authenticity alone."
+        }
+      ]
+    },
     {
       "asset_family": "reusable_scenario",
       "identity_basis": "identity-basis-for-reusable_scenario",

contracts/fixtures/asset-trust/reusable-asset-trust-policy-v1/invalid/duplicate-evidence-class.json

@@ -2,6 +2,30 @@
   "schema_version": "reusable-asset-trust-policy/v1",
   "policy_id": "aces-reusable-asset-trust-policy",
   "families": [
+    {
+      "asset_family": "associated_artifact_set",
+      "identity_basis": "associated-artifact-manifest-v1 canonical parent-plus-reference-set digest",
+      "evidence_requirements": [
+        {
+          "evidence_class": "integrity_digest",
+          "enforcement": "required",
+          "mechanism_ref": "associated-artifact-set/v1 derived set_digest",
+          "description": "The set digest binds the exact parent reference and keyed artifact-reference set without changing parent identity."
+        },
+        {
+          "evidence_class": "artifact_checksum",
+          "enforcement": "required",
+          "mechanism_ref": "validate_associated_artifact_manifest bounded concrete-byte validation",
+          "description": "Every referenced payload checksum and size is recomputed from an explicitly supplied bounded byte stream."
+        },
+        {
+          "evidence_class": "authenticity_signature",
+          "enforcement": "optional",
+          "mechanism_ref": "downstream signature over the derived associated-artifact set digest",
+          "description": "A signature may authenticate the set digest, but neither the digest nor payload checksums establish authenticity alone."
+        }
+      ]
+    },
     {
       "asset_family": "reusable_scenario",
       "identity_basis": "identity-basis-for-reusable_scenario",

contracts/fixtures/asset-trust/reusable-asset-trust-policy-v1/invalid/missing-family.json

@@ -2,6 +2,30 @@
   "schema_version": "reusable-asset-trust-policy/v1",
   "policy_id": "aces-reusable-asset-trust-policy",
   "families": [
+    {
+      "asset_family": "associated_artifact_set",
+      "identity_basis": "associated-artifact-manifest-v1 canonical parent-plus-reference-set digest",
+      "evidence_requirements": [
+        {
+          "evidence_class": "integrity_digest",
+          "enforcement": "required",
+          "mechanism_ref": "associated-artifact-set/v1 derived set_digest",
+          "description": "The set digest binds the exact parent reference and keyed artifact-reference set without changing parent identity."
+        },
+        {
+          "evidence_class": "artifact_checksum",
+          "enforcement": "required",
+          "mechanism_ref": "validate_associated_artifact_manifest bounded concrete-byte validation",
+          "description": "Every referenced payload checksum and size is recomputed from an explicitly supplied bounded byte stream."
+        },
+        {
+          "evidence_class": "authenticity_signature",
+          "enforcement": "optional",
+          "mechanism_ref": "downstream signature over the derived associated-artifact set digest",
+          "description": "A signature may authenticate the set digest, but neither the digest nor payload checksums establish authenticity alone."
+        }
+      ]
+    },
     {
       "asset_family": "reusable_scenario",
       "identity_basis": "identity-basis-for-reusable_scenario",

contracts/fixtures/asset-trust/reusable-asset-trust-policy-v1/invalid/missing-integrity.json

@@ -2,6 +2,30 @@
   "schema_version": "reusable-asset-trust-policy/v1",
   "policy_id": "aces-reusable-asset-trust-policy",
   "families": [
+    {
+      "asset_family": "associated_artifact_set",
+      "identity_basis": "associated-artifact-manifest-v1 canonical parent-plus-reference-set digest",
+      "evidence_requirements": [
+        {
+          "evidence_class": "integrity_digest",
+          "enforcement": "required",
+          "mechanism_ref": "associated-artifact-set/v1 derived set_digest",
+          "description": "The set digest binds the exact parent reference and keyed artifact-reference set without changing parent identity."
+        },
+        {
+          "evidence_class": "artifact_checksum",
+          "enforcement": "required",
+          "mechanism_ref": "validate_associated_artifact_manifest bounded concrete-byte validation",
+          "description": "Every referenced payload checksum and size is recomputed from an explicitly supplied bounded byte stream."
+        },
+        {
+          "evidence_class": "authenticity_signature",
+          "enforcement": "optional",
+          "mechanism_ref": "downstream signature over the derived associated-artifact set digest",
+          "description": "A signature may authenticate the set digest, but neither the digest nor payload checksums establish authenticity alone."
+        }
+      ]
+    },
     {
       "asset_family": "reusable_scenario",
       "identity_basis": "identity-basis-for-reusable_scenario",

contracts/fixtures/asset-trust/reusable-asset-trust-policy-v1/invalid/secret-bearing.json

@@ -2,6 +2,30 @@
   "schema_version": "reusable-asset-trust-policy/v1",
   "policy_id": "aces-reusable-asset-trust-policy",
   "families": [
+    {
+      "asset_family": "associated_artifact_set",
+      "identity_basis": "associated-artifact-manifest-v1 canonical parent-plus-reference-set digest",
+      "evidence_requirements": [
+        {
+          "evidence_class": "integrity_digest",
+          "enforcement": "required",
+          "mechanism_ref": "associated-artifact-set/v1 derived set_digest",
+          "description": "The set digest binds the exact parent reference and keyed artifact-reference set without changing parent identity."
+        },
+        {
+          "evidence_class": "artifact_checksum",
+          "enforcement": "required",
+          "mechanism_ref": "validate_associated_artifact_manifest bounded concrete-byte validation",
+          "description": "Every referenced payload checksum and size is recomputed from an explicitly supplied bounded byte stream."
+        },
+        {
+          "evidence_class": "authenticity_signature",
+          "enforcement": "optional",
+          "mechanism_ref": "downstream signature over the derived associated-artifact set digest",
+          "description": "A signature may authenticate the set digest, but neither the digest nor payload checksums establish authenticity alone."
+        }
+      ]
+    },
     {
       "asset_family": "reusable_scenario",
       "identity_basis": "identity-basis-for-reusable_scenario",

contracts/fixtures/asset-trust/reusable-asset-trust-policy-v1/invalid/unknown-family.json

@@ -2,6 +2,30 @@
   "schema_version": "reusable-asset-trust-policy/v1",
   "policy_id": "aces-reusable-asset-trust-policy",
   "families": [
+    {
+      "asset_family": "associated_artifact_set",
+      "identity_basis": "associated-artifact-manifest-v1 canonical parent-plus-reference-set digest",
+      "evidence_requirements": [
+        {
+          "evidence_class": "integrity_digest",
+          "enforcement": "required",
+          "mechanism_ref": "associated-artifact-set/v1 derived set_digest",
+          "description": "The set digest binds the exact parent reference and keyed artifact-reference set without changing parent identity."
+        },
+        {
+          "evidence_class": "artifact_checksum",
+          "enforcement": "required",
+          "mechanism_ref": "validate_associated_artifact_manifest bounded concrete-byte validation",
+          "description": "Every referenced payload checksum and size is recomputed from an explicitly supplied bounded byte stream."
+        },
+        {
+          "evidence_class": "authenticity_signature",
+          "enforcement": "optional",
+          "mechanism_ref": "downstream signature over the derived associated-artifact set digest",
+          "description": "A signature may authenticate the set digest, but neither the digest nor payload checksums establish authenticity alone."
+        }
+      ]
+    },
     {
       "asset_family": "reusable_scenario",
       "identity_basis": "identity-basis-for-reusable_scenario",