fkyh 0.1.0__tar.gz

fkyh-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,376 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  python:
+    name: Python package and tests
+    runs-on: ubuntu-latest
+    strategy:
+      # The floor `pyproject.toml` declares must be TESTED, not merely
+      # stated. A `requires-python` nobody ever runs is a promise with
+      # no evidence behind it, and this repository's rule is that a
+      # document describing a thing is not the same as a check on the
+      # thing. A matrix is the cheapest way to make the promise real.
+      #
+      # This is also the only job that runs the whole suite
+      # (`python -m pytest tests/`), which is why the declared floor is
+      # tested HERE and nowhere else. Every other job checks a slice of
+      # the repository, and each one says what it checks, and why it
+      # pins a single interpreter, beside its own `setup-python` step.
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The publish gate audits the DEFAULT BRANCH's tree, and the
+          # test suite runs it. A shallow checkout has no origin/main, so
+          # the gate skips everything and the suite fails for a reason that
+          # has nothing to do with the code. Full history, always.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # Two tests in the suite build Go binaries (the attestation consumer
+      # and the executor oracle). They skip when Go is missing, which
+      # silently turned them into no-ops. Install Go here so they really
+      # run in the main job, not just in the Go-specific jobs.
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      # Installing Go is not the same as the Go code building. Both
+      # builders inside the suite call `pytest.skip` when `go build`
+      # fails (tests/test_go_consumer.py:38, tests/test_go_oracle.py:46),
+      # so a Go source change that does not compile turns four
+      # cross-language pins into four SKIPS and leaves this job GREEN --
+      # a gate that inspects less than it governs, which is the exact
+      # failure this repository has already been bitten by. Measured: with
+      # a deliberate syntax error in examples/go-reference/oracle.go the
+      # suite reported "4 skipped" and exited 0. Build both binaries HERE,
+      # where a compile error is a failed step, so the suite's own skip can
+      # never be the only thing that notices.
+      - name: The Go cross-language pins must not degrade into skips
+        run: |
+          set -euo pipefail
+          cd examples/attestation-consumer-go
+          go build -o /tmp/attestation-consumer .
+          go build ./...
+          cd ../go-reference
+          go build -tags oracle -o /tmp/fk-yh-oracle .
+
+      - name: Install dependencies
+        # `.[test]` is the single source of truth for what the suite
+        # needs: the optional `prometheus_client` and `pyyaml` packages
+        # are not decoration, they are what lets the metrics and the
+        # Grafana dashboard tests actually assert. Without them those
+        # tests skip, and a test that skips is a gate that inspects
+        # less than it governs.
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[test]'
+
+      - name: Run the test suite
+        run: python -m pytest tests/ -q
+
+      - name: The hello-world example must actually run
+        run: python examples/hello-world.py
+
+  mDNS:
+    name: Live mDNS round trip
+    # The live discovery tests need the platform's dns-sd tool, which is
+    # macOS only. This job exists because the unit tests could not catch
+    # the TXT format bug -- they passed while the implementation could not
+    # talk to the network at all.
+    # The label matters, and so does the measurement. macos-14 is
+    # DEPRECATED (actions/runner-images), and bare macos-15 also never
+    # acquired a runner: the job queued and was cancelled with
+    # runner_name="" and steps=0, four attempts running, while the six
+    # ubuntu-latest jobs in the SAME run took runners within two seconds.
+    # At the same moment, macos-latest jobs in other repos were landing
+    # on real runners (setup-python 5/5, pypa/pip 4/4, Homebrew
+    # macos-26 2/2) -- so this was never a macOS capacity shortage, it
+    # is this label not being served. macos-latest resolves to the
+    # current GA macOS, which is the version the live suite is verified
+    # against (macOS 26.4.1: 10/10 passing locally).
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The publish gate audits the DEFAULT BRANCH's tree, and the
+          # test suite runs it. A shallow checkout has no origin/main, so
+          # the gate skips everything and the suite fails for a reason that
+          # has nothing to do with the code. Full history, always.
+          fetch-depth: 0
+
+      # One Python version (3.12), deliberately, not a matrix. What this
+      # job checks is a live-network round trip that needs the platform's
+      # dns-sd tool, and dns-sd is macOS only by nature -- so the
+      # interpreter version is incidental to the thing being checked.
+      # The declared floor is still exercised where it can be: the
+      # `python` job's matrix runs the whole suite on the floor,
+      # including the discovery unit tests. The live discovery files
+      # skip there, because dns-sd is missing on that runner -- which is
+      # exactly why this job exists.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest cryptography
+
+      - name: Advertise and resolve over a real network
+        # The glob, not a filename: a new live test file that is not
+        # listed here silently never runs, which is the same failure as
+        # not writing the test at all. The TXT format bug was invisible
+        # because the unit tests could not talk to the network.
+        run: python3 -m pytest tests/test_discovery_live*.py -v
+
+      - name: The audit live pins must run on a runner too
+        # These pins read the wire back -- the TXT record as a conforming
+        # reader sees it, and whether a derived service type really is a
+        # separate registration. They had never executed on a runner,
+        # because the glob above does not match this file AND the pins
+        # are gated behind FKYH_AUDIT_LIVE=1.
+        #
+        # A pin that never runs is a pin that cannot fail, and these
+        # proved it: one of them was found RED the first time it was
+        # actually executed (2026-10-22), still asserting the behaviour
+        # the fix had already removed. The ports are disjoint from the
+        # tests above (19990-19997 against 19873/19880-19884) and the
+        # instance names differ, so the two groups do not collide; this
+        # step runs after the one above rather than beside it.
+        #
+        # The gate is set for this step only. Without it the four live
+        # pins SKIP, and a skip in CI is indistinguishable from a pass.
+        env:
+          FKYH_AUDIT_LIVE: "1"
+        run: python3 -m pytest tests/test_audit_discovery_gossip.py -v
+
+  goAttestation:
+    name: Go attestation consumer (cross-language)
+    # The attestation protocol is implemented twice in Python and once in Go.
+    # The Go one is the interesting one: two Python implementations can share
+    # a misunderstanding and never find it, because they share a language, a
+    # JSON library and a set of habits. This job proves the protocol
+    # interoperates ACROSS languages, not merely across implementations.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The publish gate audits the DEFAULT BRANCH's tree, and the
+          # test suite runs it. A shallow checkout has no origin/main, so
+          # the gate skips everything and the suite fails for a reason that
+          # has nothing to do with the code. Full history, always.
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - name: The Go consumer must satisfy the published manifest
+        run: |
+          cd examples/attestation-consumer-go
+          go build -o /tmp/attestation-consumer .
+          /tmp/attestation-consumer --conformance ../../fixtures/attestations
+
+      - name: The Go test suite must pass
+        run: cd examples/attestation-consumer-go && go test ./...
+
+  conformance:
+    name: Go executor oracle (pinned contract)
+    # The Go oracle implements the same 5-stage guarded executor as the
+    # Python reference. The Python side lives in the LAM repository, which
+    # this repository cannot reach, so what is checked here is the oracle
+    # against the pinned contract in fixtures/executor/conformance.json.
+    #
+    # The previous version of this job parsed the oracle's stdout as a
+    # single JSON array. The oracle emits one JSON object per line, so
+    # `out[0]` raised KeyError and the job failed on every run from the
+    # repository's first commit. The check now lives in a test, which runs
+    # locally as well as here.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The publish gate audits the DEFAULT BRANCH's tree, and the
+          # test suite runs it. A shallow checkout has no origin/main, so
+          # the gate skips everything and the suite fails for a reason that
+          # has nothing to do with the code. Full history, always.
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      # One Python version (3.12), deliberately, not a matrix. What this
+      # job checks is the Go oracle against the pinned contract, and the
+      # Go version is pinned separately at 1.22. The Python step here
+      # only parses a JSON fixture, so the interpreter version cannot
+      # change the oracle's verdict. The declared floor is exercised for
+      # the suite by the `python` job's matrix.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest
+
+      - name: Build the Go oracle
+        run: |
+          chmod +x examples/go-reference/build_oracle.sh
+          ./examples/go-reference/build_oracle.sh /tmp/fk-yh-oracle
+
+      - name: The oracle must agree with the pinned contract
+        run: python -m pytest tests/test_go_oracle.py -v
+
+      - name: The conformance fixture must be internally consistent
+        # The contract is the shared document both implementations are
+        # pinned to. If it is malformed, every check against it is
+        # meaningless, so validate it on its own.
+        run: |
+          python3 - <<'PY'
+          import json, sys
+          with open("fixtures/executor/conformance.json") as fh:
+              doc = json.load(fh)
+          cases = doc["cases"]
+          if not cases:
+              print("the conformance fixture has no cases")
+              sys.exit(1)
+          stages = {c["expect"]["stage"] for c in cases}
+          wanted = {"prepare", "authorize", "execute", "commit"}
+          missing = wanted - stages
+          if missing:
+              print("the conformance fixture never exercises:", sorted(missing))
+              sys.exit(1)
+          print(f"{len(cases)} conformance cases, stages covered: {sorted(stages)}")
+          PY
+
+  attestation:
+    name: Attestation conformance fixtures
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The publish gate audits the DEFAULT BRANCH's tree, and the
+          # test suite runs it. A shallow checkout has no origin/main, so
+          # the gate skips everything and the suite fails for a reason that
+          # has nothing to do with the code. Full history, always.
+          fetch-depth: 0
+
+      # One Python version (3.12), deliberately, not a matrix. What this
+      # job checks is the published conformance consumer, run as a
+      # SCRIPT, so what is under test is the consumer's own output and
+      # not the interpreter underneath it. The floor is covered for the
+      # consumer as well: the suite runs that same script as a
+      # subprocess on the interpreter that runs the suite
+      # (tests/test_independent_consumer.py), so the `python` job's
+      # matrix exercises the consumer on the declared floor too.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest cryptography
+
+      - name: The independent consumer must satisfy the published manifest
+        # examples/independent-consumer/ is a second implementation written
+        # from ATTESTATION.md alone, importing nothing from the package. It is
+        # the artefact that proves the specification is implementable from the
+        # document rather than only by someone who has read the reference
+        # code. If it and the package ever disagree, the specification is
+        # ambiguous and the fixtures are not trustworthy.
+        run: |
+          python3 examples/independent-consumer/run_conformance.py
+
+      - name: The published fixtures must satisfy their own manifest
+        # An independent consumer, implemented from ATTESTATION.md alone,
+        # validates the published fixture set. If the corpus and the spec
+        # ever drift apart, this fails.
+        run: |
+          python3 - <<'PY'
+          import json, os, sys
+          sys.path.insert(0, ".")
+          from fkyh.attestation import Consumer, TrustConfig
+
+          fx = "fixtures/attestations"
+          manifest = json.load(open(os.path.join(fx, "manifest.json")))
+          trust = TrustConfig.load(os.path.join(fx, "trust.json"))
+          # The published evidence directory, so the consumer re-derives
+          # the digests as section 10 instructs. Without it the evidence
+          # codes of section 7 step 9 are never reached.
+          evidence = os.path.join(fx, "evidence")
+          ok = bad = 0
+          for name, expected in sorted(manifest["fixtures"].items()):
+              att = json.load(open(os.path.join(fx, expected["file"])))
+              result = Consumer(trust, evidence_root=evidence).validate(
+                  att, expected_task_id=manifest["task_id"],
+                  expected_attempt_id=manifest["attempt_id"])
+              good = (result.code == expected["expected_code"]
+                      and result.result == expected["expected_result"])
+              ok += good
+              bad += not good
+              if not good:
+                  print(f"FAIL {name}: {result.code}/{result.result} "
+                        f"expected {expected['expected_code']}/"
+                        f"{expected['expected_result']}")
+          for seq in manifest.get("sequences", []):
+              spent = set()
+              for step in seq["steps"]:
+                  att = json.load(open(os.path.join(fx, step["file"])))
+                  result = Consumer(trust, evidence_root=evidence,
+                                    spent=spent).validate(
+                      att, expected_task_id=manifest["task_id"],
+                      expected_attempt_id=manifest["attempt_id"])
+                  good = (result.code == step["expected_code"]
+                          and result.result == step["expected_result"])
+                  ok += good
+                  bad += not good
+          print(f"{ok}/{ok + bad} conformance checks passed")
+          sys.exit(0 if bad == 0 else 1)
+          PY
+
+  soroban-registry:
+    name: Soroban registry contract
+    # The contract is native-testable: cargo test needs no stellar-cli and
+    # no wasm target. The wasm BUILD is deliberately not in CI -- the SDK's
+    # build script requires stellar-cli v25.2.0+ for spec shaking, and
+    # claiming the contract builds in CI without that toolchain would be
+    # the same class of claim this repository keeps deleting.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The publish gate audits the DEFAULT BRANCH's tree, and the
+          # test suite runs it. A shallow checkout has no origin/main, so
+          # the gate skips everything and the suite fails for a reason that
+          # has nothing to do with the code. Full history, always.
+          fetch-depth: 0
+      # Pinned, not `@stable`. The Go job pins 1.22 and the Python job
+      # pins 3.11 and 3.12, because a toolchain that moves under a green
+      # run is a promise nobody tested. `@stable` means this job is
+      # decided by whatever Rust was released that morning: `Cargo.lock`
+      # pins the CRATES, but never the COMPILER that builds them, so a
+      # stranger who clones this repository in six months would be the
+      # first person ever to run the contract against a Rust nobody has
+      # run it against. 1.99.1 is the toolchain this contract is built
+      # and tested against -- it is the current stable today
+      # (rustc 1.99.1, 58cf8f9c3) and `cargo test --locked` passes 21/21
+      # on it from a clean checkout with no `target/` directory.
+      - uses: dtolnay/rust-toolchain@1.99.1
+      - name: Contract tests
+        working-directory: contracts/fkyh-registry
+        run: cargo test --locked