Add bounded cross-platform comparison and interoperability planning

.github/workflows/ci.yml

@@ -91,7 +91,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest, macos-latest]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -134,8 +134,77 @@ jobs:
         with:
           name: release-integrity-windows-latest
           path: dist/windows
-      - name: Require byte-identical Linux and Windows release artifacts
-        run: python scripts/release_artifacts.py compare dist/ubuntu dist/windows
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-integrity-macos-latest
+          path: dist/macos
+      - name: Require byte-identical Linux, Windows, and macOS release artifacts
+        run: |
+          python scripts/release_artifacts.py compare dist/ubuntu dist/windows
+          python scripts/release_artifacts.py compare dist/ubuntu dist/macos
+
+  platform-comparability-observation:
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-latest
+            platform: Linux
+          - runner: windows-latest
+            platform: Windows
+          - runner: macos-15-intel
+            platform: Darwin
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12.10"
+      - run: python -m pip install .
+      - name: Require the runner's native operating-system view
+        env:
+          EXPECTED_PLATFORM: ${{ matrix.platform }}
+        run: python -c "import os, platform; observed = platform.system(); expected = os.environ['EXPECTED_PLATFORM']; assert observed == expected, (observed, expected)"
+      - name: Capture, validate, and rerun the portable example
+        run: |
+          vstd run examples/generic_run/manifest.json --output dist/platform-comparability/${{ matrix.platform }}
+          vstd validate dist/platform-comparability/${{ matrix.platform }}
+          vstd reproduce dist/platform-comparability/${{ matrix.platform }} --rerun
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: platform-comparability-${{ matrix.platform }}
+          path: dist/platform-comparability/${{ matrix.platform }}
+          if-no-files-found: error
+          retention-days: 14
+
+  platform-comparability:
+    needs: [platform-comparability-observation]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12.10"
+      - run: python -m pip install .
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: platform-comparability-*
+          path: dist/platforms
+          merge-multiple: false
+      - name: Require comparable recorded results across all declared platforms
+        run: |
+          vstd compare-platforms \
+            dist/platforms/platform-comparability-Linux \
+            dist/platforms/platform-comparability-Windows \
+            dist/platforms/platform-comparability-Darwin \
+            --json > platform-comparison.json
+          python -c 'import json; from pathlib import Path; report=json.loads(Path("platform-comparison.json").read_text(encoding="utf-8")); assert report.get("status") == "PASS" and report.get("exit_code") == 0, report'
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: platform-comparison-${{ github.sha }}
+          path: platform-comparison.json
+          if-no-files-found: error
+          retention-days: 14
 
   installed-wheel-smoke:
     runs-on: ubuntu-latest
@@ -196,7 +265,7 @@ jobs:
   # This identifier remains stable because main branch protection requires it.
   conformance-gate:
     if: always()
-    needs: [base, coverage, stdlib-smoke, scitt-crypto, artifact-seal, release-integrity, release-reproducibility, installed-wheel-smoke, presentation, codeql]
+    needs: [base, coverage, stdlib-smoke, scitt-crypto, artifact-seal, release-integrity, release-reproducibility, platform-comparability-observation, platform-comparability, installed-wheel-smoke, presentation, codeql]
     runs-on: ubuntu-latest
     steps:
       - name: Require every declared support and artifact check
@@ -208,6 +277,8 @@ jobs:
           ARTIFACT_SEAL: ${{ needs.artifact-seal.result }}
           RELEASE: ${{ needs.release-integrity.result }}
           REPRODUCIBLE: ${{ needs.release-reproducibility.result }}
+          PLATFORM_OBSERVATIONS: ${{ needs.platform-comparability-observation.result }}
+          PLATFORM_COMPARISON: ${{ needs.platform-comparability.result }}
           WHEEL: ${{ needs.installed-wheel-smoke.result }}
           PRESENTATION: ${{ needs.presentation.result }}
           CODEQL: ${{ needs.codeql.result }}
@@ -219,6 +290,8 @@ jobs:
           test "$ARTIFACT_SEAL" = success
           test "$RELEASE" = success
           test "$REPRODUCIBLE" = success
+          test "$PLATFORM_OBSERVATIONS" = success
+          test "$PLATFORM_COMPARISON" = success
           test "$WHEEL" = success
           test "$PRESENTATION" = success
           test "$CODEQL" = success

CHANGELOG.md

@@ -11,6 +11,36 @@
 > Coordinated Universal Time (UTC); Verifier Standard (VSTD); ZIP archive format (ZIP);
 > zero-identity/zero-knowledge (ZIZK).
 
+## Unreleased
+
+### Experimental interoperability planning
+
+- Add an explicitly experimental `verifier.interoperability` facade for immutable,
+  domain-neutral component descriptors and registries plus typed VSTD-2 surface-hole
+  analysis and deterministic, registry-digest-bound candidate plans. Keep these names
+  outside the supported top-level `verifier.__all__` boundary.
+- Add a runnable non-critical sorted-grocery-list example that produces two exact
+  candidates and leaves three self-closure holes unmatched without invoking its checker.
+  Planning is not validation execution: strict VSTD-2 wire loading, component execution,
+  evidence collection, post-execution reanalysis, closure, safety, and critical-domain
+  readiness remain unsupported or unestablished.
+
+### Cross-platform comparison
+
+- Add a supported bounded comparator and `vstd compare-platforms` command for VSTD-1
+  generic-run receipts. A declaration alone earns no result: `PASS` requires one
+  canonically intact receipt per declared operating system, matching non-platform
+  bindings, and matching declared result projections. Preserve comparable disagreement
+  as `CONFLICTED`, incomplete or non-comparable evidence as `NOT_ESTABLISHED`, and
+  malformed or contradictory evidence as `INVALID`.
+- Add native GitHub-hosted Linux, Windows, and Intel macOS observation jobs for the
+  portable generic example and require their aggregate diagnostic in the protected
+  repository-check gate. Make the example's declared JavaScript Object Notation outputs
+  use explicit line-feed bytes so Windows text translation cannot create a false portable
+  surface. Extend release-artifact byte comparison to macOS. These checks
+  do not establish universal portability, native-execution attestation within the
+  receipt, semantic correctness, or actor independence.
+
 ## 1.2.0 - 2026-09-01
 
 ### Public surface and integrations

README.md

@@ -147,7 +147,7 @@ Use this summary before opening the exact matrix:
 | Usable reference paths | Receipts, generic run capture and reproduction, Graph recording, grounded-certificate checks, evidence-bound assessment, and artifact freeze/seal/thaw mechanisms are implemented within their documented bounds. |
 | Mechanism-dependent paths | VSTD-4, VSTD-5, and Graph profiles above recorded lineage establish results only when their exact registered mechanisms rerun successfully over bound evidence. |
 | Compatibility candidates | Candidate depth/profile calculations remain `NOT_ESTABLISHED`; caller-supplied references or ratings cannot create conformance. |
-| Experimental integrations | The workflow and Supply Chain Integrity, Transparency, and Trust (SCITT) profiles remain non-normative and grant no VSTD verdict from platform state alone. |
+| Experimental integrations | The workflow and Supply Chain Integrity, Transparency, and Trust (SCITT) profiles plus interoperability catalog and surface-planning path remain non-normative. Catalog matching and planning grant no VSTD verdict and execute no checker. |
 | Not claimed | Accreditation, consensus-standard status, external adoption, a second implementation, a real independent witness, or third-party security review. |
 
 <details>
@@ -160,6 +160,7 @@ external interoperability, certification, or a second implementation.
 |---|---|---|---|---|---|
 | VSTD-1 | Project specification with implemented reference subset | Claim receipts, checker reports, strict generic-run profile, inspection, and current-profile reads | Claim coordinates, stable digests, mechanism descriptors, and declared provenance; actor separation is not inferred | Implemented reference subset | External implementation and a validator binding distinct producer/checker actors and execution seams |
 | VSTD-2 | Additive experimental project specification | Typed verification geometry, residuals, closure checks, schema, and tests | Geometry and declared reconstruction evidence inside the receipt | Implemented vertical slice | Independent implementation and broader geometry interoperability |
+| Interoperability catalog and surface planning | Experimental implementation; not a receipt or numbered profile | Frozen component descriptors and registry, modeled-hole analysis over typed VSTD-2 geometry, exact candidate matching, and deterministic nonexecuting plans | Binds the typed geometry digest, registry version and digest, match coordinates, prerequisites, blockers, and fixed claim boundary | Plan-only candidate associations; no validation result or closure | Strict full-parity VSTD-2 wire loader, authorized component execution, bound evidence, post-execution reanalysis, and independent interoperability results |
 | VSTD-3 | Implemented project specification | Typed accelerator model, strict validator, emulator, offline adapters, continuity, fleet, and claim evaluation | Conditional on source-specific signatures, nonces, reference values, topology, events, and trust roots; host inventory remains weak evidence | Implemented reference surface | Vendor firmware integration, production trust roots, and complete-mediation evidence outside the emulator boundary |
 | VSTD-4 | Project specification with implemented reference paths | grounded decision certificate (GDC) parser/kernel, compatibility candidate depth, and evidence-bound establishment/recheck | Exact VSTD-1/2/3 and fourteen-rung propositions, content-addressed evidence bytes, mechanism implementation digests, trust roots, and bounds | Candidate path `NOT_ESTABLISHED`; evidence-bound path can establish conformance | Independent implementation, external interoperability, and deployment-specific rung mechanisms/evidence |
 | VSTD-5 | Project specification with implemented reference mechanism | Evidence-bound entry gate, seven separation dimensions, exact admitted-certificate binding, corroboration checks, duplicate refusal, disagreement preservation, receipt build/recheck | Witness coordinate, exact negative separation propositions, VSTD-4 commitment/certificate, checker, observations, mechanisms, trust roots, bounds, and embedded evidence | Mechanism can establish a bounded result; a positive observation with unresolved independence remains overall `UNKNOWN`; no repository claim of a real independent witness | Real independent witnesses, second implementation, external attack, and operational interoperability |
@@ -168,7 +169,7 @@ external interoperability, certification, or a second implementation.
 | VSTD-Graph-3 | Project specification with implemented reference paths | Compatibility candidate plus evidence-bound Accountable Provenance Closure computation/recheck | Same complete closure binding, including VSTD-3 rating propositions | Candidate `NOT_ESTABLISHED`; evidence-bound path can establish | Production VSTD-3 rating evidence across a real collection |
 | VSTD-Graph-4 | Project specification with implemented reference paths | Compatibility candidate plus evidence-bound Refutable Transformation Closure computation/recheck | Same complete closure binding; an edge mechanism must actually check its refutability closure | Candidate `NOT_ESTABLISHED`; evidence-bound path can establish | External closure mechanisms and independent replay |
 | VSTD-Graph-5 | Project specification with implemented reference paths | Compatibility candidate plus evidence-bound Corroborated Verification Network computation/recheck | Exact VSTD-5 object and transformation rating mechanisms across the complete closure | Candidate `NOT_ESTABLISHED`; evidence-bound path can establish | Real independently corroborated collection, second implementation, and interoperability |
-| Generic run | VSTD-1 generic-computation profile | Plan, execute, capture, inspect, strict shape/digest validation, and declared-output rerun | Captures command, source state, outputs, environment, and manifest declarations; generic validation is not native claim verification or VSTD-4 conformance | Implemented VSTD-1 profile | Sandbox, generic external-evidence resolver, and actor/execution binder |
+| Generic run | VSTD-1 generic-computation profile | Plan, execute, capture, inspect, strict shape/digest validation, declared-output rerun, and bounded cross-platform result comparison | Captures command, source state, outputs, environment, and manifest declarations; platform comparison requires complete declared coverage and matching non-platform bindings; generic validation is not native claim verification or VSTD-4 conformance | Implemented VSTD-1 profile plus an additive diagnostic comparator | Sandbox, generic external-evidence resolver, native-execution attestation, and actor/execution binder |
 | Artifact freeze, seal, and thaw | Normative artifact-control mechanism; not a numbered VSTD or receipt profile | Exact regular-file byte preservation, dual-digest artifact identity, read-only guards, finite self-closing Ed25519 seals, external anchor checks, and copy-on-write thaw status | Binds artifact bytes, paths, media type, freeze manifest, carried key, signature, and optional expected artifact/key coordinates | Implemented mechanism version 1 | Durable external archive, privileged-write prevention, trusted time, encryption, semantic correctness, and realm/continuity verification |
 | Experimental workflow | Non-normative experimental profile 0.1 | Strict validator, verdict-neutral GitHub event projector, allocation records, and command-line interface (CLI) | Preserves native platform results and explicit horizons with `verification_effect = NONE` | No VSTD conformance claim | Independent consumer, additional platform adapter, and evidence for allocation optimality |
 | Supply Chain Integrity, Transparency, and Trust (SCITT) interoperability | Experimental, non-normative application profile and crosswalk | Real local Concise Binary Object Representation (CBOR) plus CBOR Object Signing and Encryption (COSE) signatures/receipt, loss-declared adapter, and adjacent native-result composition | Binds the exact payload under emitted test keys and local policy; registration never establishes payload truth | VSTD-4 remains `NOT_ESTABLISHED` | Public Transparency Service, external implementation/interoperability result, and Internet Engineering Task Force (IETF) review |
@@ -336,8 +337,24 @@ Generic `validate` checks the strict profile shape and stable-payload digest. It
 not rehash external artifacts, resolve evidence references, rerun the command, or verify
 the recorded declaration as a native domain claim. `reproduce --rerun` separately
 executes the recorded command and compares declared output paths, digests, and execution
-outcome. Matching outputs do not establish actor independence, environment equivalence,
-semantic equivalence, or truth outside that scope.
+outcome.
+
+When a manifest's open refutation surface declares compatible platforms and explicit
+result surfaces, compare one receipt from each declared operating system:
+
+```bash
+vstd compare-platforms receipts/Linux receipts/Windows receipts/Darwin --json
+```
+
+Python reports macOS as `Darwin`. The comparator returns `PASS` only when every declared
+platform appears exactly once, canonical receipt integrity passes, non-platform claim,
+source, command, Python, machine-family, and mechanism bindings agree, and every declared
+result projection agrees. Comparable result disagreement is `CONFLICTED`; missing or
+non-comparable evidence is `NOT_ESTABLISHED`; malformed or internally contradictory
+evidence is `INVALID`. This is a comparison of supplied recorded results—not proof of
+universal portability, semantic correctness, native execution, or independent actors.
+Matching outputs alone do not establish environment equivalence or truth outside that
+scope.
 
 ### Use the Python application programming interface (API)
 
@@ -385,6 +402,33 @@ native object ──native verifier──> native result
                                            └──> VSTD claim boundary
 ```
 
+The experimental interoperability-planning path connects a domain-neutral component
+catalog to detection and planning:
+
+```text
+typed VSTD-2 geometry
+  -> modeled-hole analysis
+  -> exact catalog candidates
+  -> nonexecuting validation plan
+```
+
+Run its harmless sorted-grocery-list example:
+
+```bash
+python examples/interoperability_planning/demo.py
+```
+
+The example reports two exact candidates and three unmatched self-closure holes while
+keeping `plan_only = true`, `execution_performed = false`, and the checker invocation
+count at zero. Here, **validation** names the future process of attempting to discharge
+verification-surface holes with bound execution evidence and then reassessing the
+geometry. This example only detects and plans: it cannot establish checker availability
+at execution time, a native result, ordinary or self-closure, safety, authority to act,
+critical-domain readiness, or VSTD conformance. Its registry version and digest are bound
+into the plan. Strict VSTD-2 wire loading, automatic execution, and a command-line
+interface remain unsupported. See the
+[example boundary and output](examples/interoperability_planning/).
+
 The experimental SCITT profile uses
 real Concise Binary Object Representation (CBOR) and COSE
 signatures and a local inclusion receipt. It demonstrates exact payload carriage and
@@ -423,8 +467,11 @@ Additional entry points:
 
 A release contains a canonical artifact set: ZIP archive format (ZIP), wheel, source
 distribution, and external manifest bound to the exact public Git commit and file
-members. The continuous integration (CI) workflow builds on Windows and Linux and rejects
-cross-platform byte differences. GitHub
+members. At the current unreleased source coordinate, the continuous integration (CI)
+workflow builds the artifact set on Linux, Windows, and macOS and rejects cross-platform
+byte differences. It also captures and reruns the portable generic example on three
+GitHub-hosted operating-system virtual machines, then requires a bounded `PASS` over the
+three receipts. GitHub
 artifact attestations bind uploaded bytes to the workflow; they do not establish source
 correctness, tag identity, or adoption.
 

RELEASING.md

@@ -55,7 +55,7 @@ release-candidate Zenodo metadata.
    itself, avoiding self-reference.
 
    The protected repository-check aggregate separately builds this complete artifact set
-   on Windows and Linux and compares every byte. Do not prepare a tag unless that
+   on Linux, Windows, and macOS and compares every byte. Do not prepare a tag unless that
    cross-platform comparison passed on the exact candidate commit.
 
 4. Run `twine check` on the candidate wheel and source distribution. Install the