arbiter-engine 0.2.3__tar.gz → 0.2.6__tar.gz

{arbiter_engine-0.2.3 → arbiter_engine-0.2.6}/.github/workflows/release.yml

@@ -154,9 +154,9 @@ jobs:
   # upload is the one that cannot be taken back, and a version number on this
   # index can never be reused.
   #
-  # That division is the repository's own. `build-engine.sh` says it in as many
-  # words: it builds and verifies, it does not push, because the irreversible
-  # step stays with the operator. Automating the upload would have removed that
+  # That division is the repository's own, and the tooling that derives this
+  # package says it in as many words: it builds and verifies, it does not
+  # push, because the irreversible step stays with the operator. Automating the upload would have removed that
   # division; the approval gate is what puts it back.
   # -------------------------------------------------------------------------
   publish:

arbiter_engine-0.2.6/.github/workflows/tests.yml

@@ -0,0 +1,292 @@
+# The engine's own suite, on every change.
+#
+# The sibling workflow verifies the PUBLISHED package on a schedule; this one
+# is the gate on the way in. Until it existed the package shipped no tests at
+# all, and every regression guard it had lived in a downstream consumer's
+# integration suite -- which meant the engine's protection depended on somebody
+# else's project continuing to exist, and a defect reached six releases and
+# seven issues before anybody upstream could have seen it.
+#
+# THREE LESSONS ARE PRE-APPLIED HERE, each of which cost a real defect in a
+# project that consumes this one. They are the reason this file is longer than
+# `run pytest`.
+#
+# NOTE ON FORMATTING: no hanging indents in these comments. The publication
+# path collapses leading whitespace inside a config-file comment, so an
+# indented continuation would arrive here looking different from how it was
+# written -- and the check that compares the two is worth more than the
+# indent.
+#
+# 1. pytest is installed EXPLICITLY. A CI step that installs nothing runs a
+# bare interpreter. The consuming project's checks job was red on every push
+# for months of subjective time because the runner had no pytest, so no test
+# ever ran server-side -- and nobody reads a job that has never been green.
+#
+# 2. EXIT CODE 5 FAILS. pytest exits 5 when it collects nothing, and a module
+# that skips at import collects nothing. That is the permissive value, and
+# leaving it permissive is how a canary job stayed green for four runs having
+# executed zero tests. "No tests ran" is precisely the hole this workflow
+# exists to close, so it is spelled as a failure below rather than left to a
+# shell's default.
+#
+# 3. THE MATRIX REACHES 3.12. `datetime.utcnow()` gained its DeprecationWarning
+# in 3.12, and `filterwarnings = error::DeprecationWarning` in pyproject.toml
+# is inert below it. A green run on the 3.10 floor proves nothing about that
+# gate; a run that never left 3.10 would report a passing check for a rule that
+# had not been evaluated. 3.10 is here because it is the declared floor, not
+# because it tests the warning.
+
+name: tests
+
+# NO BRANCH FILTER, and that is the fix rather than the shortcut. The first
+# version read `branches: [main]` and this repository publishes on `master`, so
+# the job was registered, valid, and unable to fire on a push -- zero runs,
+# nothing red, nothing to read. This file's own header argues that a job nobody
+# reads is worse than none; a job that cannot run is worse still, because it
+# looks like coverage from every angle except the one that counts.
+#
+# A branch name here would be a second copy of a fact that lives in the
+# publishing procedure, and the two would drift exactly once, silently. There
+# is one branch; matching every push cannot be wrong about which.
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  suite:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # The package, not the working tree. `pytest` resolves `arbiter_engine`
+      # from site-packages, so this exercises what a user installs -- a module
+      # left out of the wheel fails here rather than in their traceback.
+      #
+      # The `mcp` extra is installed deliberately. The transport binding is
+      # skipped without it, and a component whose only test is skipped
+      # everywhere wears the same green as one that is covered. That shim
+      # already shipped once having never been executed.
+      #
+      # `jsonschema` is installed for the same reason, and it took an
+      # outside reader to notice that the paragraph above stopped one line
+      # short of it. TEN tests gate on that import, and until now no lane
+      # installed it: this job ran `.[mcp]` and pytest, and the reproduction
+      # our own documents imply runs numpy, pyyaml and pytest. So the
+      # machine-readable contract that `meta.schema_version` advertises had
+      # never been put in front of a validator here -- including the single
+      # check that `schema/envelope.schema.json` parses as a 2020-12 schema at
+      # all, which has no derivation-based substitute and skipped in silence
+      # through every release. It is a TEST requirement and not a dependency:
+      # the engine still runs on numpy and pyyaml, and the pin below is what
+      # keeps that true.
+      #
+      # `rdf` joined `mcp` on 2026-09-23, for the same reason `jsonschema` is on
+      # the line below it. The extra is ADVERTISED in `pyproject.toml`, so
+      # `pip install arbiter-engine[rdf]` is a supported install -- and no lane
+      # had ever installed it, so the whole RDF path ran nowhere and the one
+      # graph the loader's namespaces refer to was never loaded by anything.
+      # That is the same defect this step already carries a paragraph about:
+      # a dependency a caller is invited to install, exercised on no lane.
+      #
+      # 4. pytest IS RANGE-PINNED, and the range is a claim this lane has
+      # tested. It was unpinned until 2026-09-24, so a fresh runner resolved
+      # whatever was newest that morning. pytest 9.1 deprecated a class-scoped
+      # fixture written as an instance method; `filterwarnings =
+      # error:DeprecationWarning` in pyproject.toml turns that into an ERROR;
+      # and one file in this suite used the pattern. The three together made
+      # the published lane go red with nothing in the tree having changed --
+      # green on a runner with an older cached pytest, red on a fresh one. The
+      # same *true where I stood, false where it is read* shape the release
+      # checks already close on the tree, arriving on the test RUNNER instead.
+      # The floor is where the suite is verified; the ceiling is the next
+      # major, which the canary job below reaches on purpose.
+      - name: Install the package and the suite's requirements
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[mcp,rdf]
+          python -m pip install 'pytest>=8,<10' jsonschema
+
+      # NAMES THE VERSION IT MEASURED. A range says what is allowed; the log
+      # has to say what actually ran, or a reader of a green check cannot tell
+      # which end of the range produced it.
+      - name: Say which pytest this run used
+        run: python -m pytest --version
+
+      # `set +e` is load-bearing, not tidiness. GitHub runs `run:` steps under
+      # `bash -e`, so a failing pytest would end the step at that line and the
+      # exit-5 branch below would never execute -- a handler that reads
+      # correctly and cannot run. Verified by running it, because reading it
+      # was how it looked fine.
+      #
+      # `-rs` prints the reason for every skip, and the output is
+      # TEE'd so the step after can read this run's summary instead of
+      # producing another one. Two reasons, and the second is the real one:
+      # a second run costs twenty seconds per matrix entry, and it grades a
+      # DIFFERENT EXECUTION than the one this job just accepted.
+      #
+      # `${PIPESTATUS[0]}`, not `$?`. Through a pipe, `$?` is tee's status --
+      # tee succeeds when pytest fails, so the naive form turns every red
+      # suite green and the exit-5 branch below never fires.
+      - name: Run the suite, and fail if it ran nothing
+        run: |
+          set +e
+          pytest -q -rs --tb=short | tee "${RUNNER_TEMP:-/tmp}/pytest-summary.txt"
+          rc=${PIPESTATUS[0]}
+          if [ "$rc" -eq 5 ]; then
+            echo "::error::pytest exited 5 -- it collected no tests. A suite that runs nothing reports the same green as one that passes."
+            exit 1
+          fi
+          exit "$rc"
+
+      # Asserts the outcome, not the mechanism. The step above could pass with
+      # a handful of tests if collection silently narrowed, so the count is
+      # read back and held against a floor. A bare count would be a number to
+      # maintain; a floor only ever goes red when coverage SHRINKS.
+      - name: The suite is not quietly shrinking
+        run: |
+          set +e
+          COLLECTED=$(pytest --collect-only -q 2>/dev/null | tail -1 | grep -oE '^[0-9]+')
+          echo "collected: $COLLECTED"
+          if [ -z "$COLLECTED" ] || [ "$COLLECTED" -lt 60 ]; then
+            echo "::error::collected ${COLLECTED:-0} tests; the suite has lost coverage"
+            exit 1
+          fi
+
+      # and the mirror image of the step above. A floor on COLLECTED
+      # catches a suite that shrinks; nothing caught a suite that goes QUIET,
+      # and going quiet is what actually happened -- ten tests turned into
+      # skips when an optional import went missing, and the pass count moved
+      # by ten in a number nobody reads to the digit.
+      #
+      # THE CEILING IS MEASURED, not chosen. With the package installed, the
+      # skips that remain are structural: three axioms declare a floor of one
+      # and have no below-the-floor case to construct, and two parametrized
+      # tests receive an empty axiom set. That is five. Without the package
+      # installed four more appear, which is nine, and nine is the ceiling so
+      # that a job on a runner that resolves the install differently does not
+      # go red for a reason that is not this one.
+      #
+      # WHAT IT CANNOT SEE: one test going quiet. A tier is what this catches
+      # -- losing `jsonschema` again puts the count at fifteen. Losing the
+      # `mcp` binding puts it at six and passes here, which is why that extra
+      # is pinned in the install rather than watched from here.
+      #
+      # It reads the GRADED run's summary rather than running the
+      # suite again. The first version ran it a second time, which measured
+      # twenty seconds per matrix entry and, worse, asked its question of an
+      # execution this job had never accepted.
+      #
+      # AND IT REFUSES WHEN IT CANNOT ANSWER. A missing or unrecognisable
+      # summary used to leave `SKIPPED` defaulting to zero, which is the
+      # failure mode this whole step exists to catch, one level up: a check
+      # that cannot see anything reporting the same green as one that looked.
+      - name: The suite is not quietly going skipped
+        run: |
+          set +e
+          SUMMARY=$(tail -1 "${RUNNER_TEMP:-/tmp}/pytest-summary.txt" 2>/dev/null)
+          if ! echo "$SUMMARY" | grep -qE '[0-9]+ (passed|failed|error)'; then
+            echo "::error::no pytest summary from the graded run, so this check cannot answer -- and a check that cannot answer must not pass."
+            exit 1
+          fi
+          echo "summary: $SUMMARY"
+          SKIPPED=$(echo "$SUMMARY" | grep -oE '[0-9]+ skipped' | grep -oE '^[0-9]+')
+          SKIPPED=${SKIPPED:-0}
+          echo "skipped: $SKIPPED"
+          if [ "$SKIPPED" -gt 9 ]; then
+            echo "::error::$SKIPPED tests skipped; a tier of the suite has gone quiet. The reasons are in the run step above -- an optional import that stops resolving takes its whole tier with it and reports the same green."
+            exit 1
+          fi
+
+      # The step above COUNTS; this one NAMES. A ceiling cannot see a
+      # swap -- one test going quiet while another starts passing leaves the
+      # number exactly where it was -- and the comment above already says what a
+      # single quiet test costs here: losing the `mcp` binding puts the count at
+      # six and passes.
+      #
+      # An outside report then measured exactly six against this commit, on this
+      # install recipe, and nothing this project ships could say which test it
+      # was. The only SINGLE-test optional import in the suite is that binding:
+      # `jsonschema` gates ten and `yaml` gates whole modules, so six is not a
+      # number the other two can produce. The SDK binding had almost certainly
+      # gone unrun again -- and *almost certainly* is the wrong grade for a
+      # component that already shipped once having never been executed.
+      #
+      # KEYED ON THE FILE, not the line. Line numbers move whenever a file is
+      # edited, and a guard going red for an edit above the skip teaches people
+      # to update it without reading it. WHAT THAT COSTS, written down rather
+      # than left to be discovered: two tests trading places inside ONE file are
+      # invisible here. Anything arriving, leaving, or moving between files is
+      # named.
+      #
+      # It reads the GRADED run's summary, for the reason the step above gives.
+      - name: The skips are the ones we expect, by name
+        run: |
+          set +e
+          SUMMARY_FILE="${RUNNER_TEMP:-/tmp}/pytest-summary.txt"
+          if [ ! -s "$SUMMARY_FILE" ]; then
+            echo "::error::no summary from the graded run, so the skip set cannot be read -- and a check that cannot answer must not pass."
+            exit 1
+          fi
+          EXPECTED=$(printf '%s\n' \
+            "3 tests/test_absent_data_regressions.py" \
+            "2 tests/test_threshold_overrides.py")
+          ACTUAL=$(awk '/^SKIPPED \[[0-9]+\]/ {
+                          n = $2; gsub(/[^0-9]/, "", n);
+                          split($3, part, ":"); count[part[1]] += n
+                        }
+                        END { for (f in count) printf "%d %s\n", count[f], f }' \
+                    "$SUMMARY_FILE" | sort -k2)
+          echo "expected skips:"; printf '%s\n' "$EXPECTED"
+          echo "actual skips:";   printf '%s\n' "$ACTUAL"
+          if [ "$EXPECTED" != "$ACTUAL" ]; then
+            echo "::error::the skip set moved. Lines with < are expected and absent; lines with > are skipping and were not expected to. A test that starts skipping stops being evidence while still counting as collected."
+            diff <(printf '%s\n' "$EXPECTED") <(printf '%s\n' "$ACTUAL")
+            exit 1
+          fi
+
+  # THE CEILING, REACHED ON PURPOSE RATHER THAN HIT BY SURPRISE.
+  #
+  # The job above pins pytest below the next major so the gate is a gate. That
+  # alone would reproduce the defect it was written for one major later: a
+  # lane that never sees a new pytest cannot tell you a new pytest breaks it,
+  # and the reason the 9.1 errors arrived unannounced is that nothing here had
+  # ever run anything but whatever was newest.
+  #
+  # So one job installs the newest, on one interpreter, and is ALLOWED TO
+  # FAIL. Its red is a notice, not a gate: it says the range in the job above
+  # is now a claim about the past, and somebody should widen it deliberately
+  # after reading what moved. A gate that goes red for a reason nobody chose
+  # gets switched off; a notice that does is doing its job.
+  newest-pytest:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[mcp,rdf]
+          python -m pip install --upgrade pytest jsonschema
+      - name: Say which pytest this run used
+        run: python -m pytest --version
+      # No exit-5 handling and no skip-set comparison: this lane is not the
+      # grade. It answers one question -- does the suite still pass on a
+      # pytest the pinned range excludes -- and anything more would be a
+      # second copy of the job above, drifting from it.
+      - name: The suite, on a pytest the gate does not admit
+        run: python -m pytest tests/ -q

{arbiter_engine-0.2.3 → arbiter_engine-0.2.6}/BRIDGES.md

@@ -265,6 +265,74 @@ one is inferred from an unknown.
 
 ---
 
+## 2a. The discipline vocabularies, which are not that one
+
+Sec. 2 is titled *the decline vocabulary* and there are eight of them. The
+fourteen above are the ones `check` uses to refuse an axiom evaluation. Each
+sub-envelope -- `simulation`, `shadow`, `projection`, `discovery`,
+`entailment`, `inference`, `forecasts` -- refuses out of its OWN closed set.
+`COMPATIBILITY.md` says so, warns that reading a reason from one set against
+another is how a closed enum stops being closed, and grants a patch release
+permission to add a member to any of them.
+
+**Until now no document said what they contain.** A reader told the sets are
+separate, told not to mix them, and told they may grow had no way to see one,
+and this guide -- the one that calls a decline vocabulary a requirements
+document -- named only the fourteen.
+
+What that costs is measurable. An outside comparison written in September 2026
+reproduced every vocabulary this project had published -- the fourteen above,
+the six gap types, the eight raced outcomes, the twenty assumption stamps -- by
+exact membership. Its own table of *the closed vocabularies* then listed five
+sets and none of these seven, and three members of the `simulation` set turned
+up in its prose instead, beside a gap type, in a list read against the
+fourteen. That is precisely the mistake `COMPATIBILITY.md` warns against, made
+by a reader who got everything else exactly right, because what they needed in
+order to avoid it was not published.
+
+Ninety-three names across seven sets. Each row below is complete: what it folds
+in, plus what is its own, is the whole set.
+
+| sub-envelope | members | folds in | its own |
+|---|---:|---|---|
+| `simulation` | 39 | the fourteen, `projection` | `budget_exhausted`, `contradictory_actions`, `counterfactual_not_a_prediction`, `coupling_uninstantiated`, `cycle_unsupported`, `gain_not_adopted`, `malformed_action`, `malformed_request`, `missing_declaration`, `missing_dynamics`, `missing_entity`, `no_candidates`, `no_declared_tolerance`, `no_objective`, `settle_exceeds_step`, `unknown_action`, `unknown_parameter`, `wrong_entity_type` |
+| `shadow` | 18 | the fourteen | `internal_error`, `no_report_probability`, `not_a_producers_submission`, `tail_not_declared` |
+| `projection` | 9 | -- | `covariance_unbounded`, `insufficient_samples`, `internal_error`, `model_inconsistent`, `model_missing`, `no_lookback`, `no_report_probability`, `no_threshold`, `unidentifiable_parameter` |
+| `discovery` | 8 | -- | `faithfulness_unverifiable`, `insufficient_samples`, `internal_error`, `latent_confounding_possible`, `no_significance_level`, `nonstationary_series`, `orientation_undetermined`, `untested_pair` |
+| `entailment` | 7 | -- | `binding_budget_exhausted`, `depth_exceeded`, `internal_error`, `malformed_rule`, `open_world_undecidable`, `recursion_unsupported`, `rule_unreachable` |
+| `inference` | 7 | -- | `cpt_missing`, `cycle_unsupported`, `evidence_conflict`, `internal_error`, `no_report_probability`, `not_identifiable`, `treewidth_exceeded` |
+| `forecasts` | 5 | -- | `forecast_missing`, `internal_error`, `model_unknown`, `stale_forecast`, `ungradeable` |
+
+Read every one of them three-valued, as `COMPATIBILITY.md` says: **a member you
+do not recognise means this engine is newer than your reader**, not that the
+record is malformed. A reader that switches exhaustively and raises on the
+default will break, and the sets have each grown at least once.
+
+Three things the shape of the table is telling you:
+
+* **`simulation` is the large one because it inherits twice.** A rollout runs
+  the eight axioms over every imagined state, so every axiom decline can reach
+  it; and `seed_mode="projected"` runs the declared projector, so every
+  projection decline can too. Its eighteen own members are the ones about
+  actions, couplings and the walk itself.
+* **A member appearing in two sets is the same word, not the same claim.**
+  `cycle_unsupported` in `simulation` is a topology the walk will not step;
+  in `inference` it is a graph the elimination order cannot handle.
+  `internal_error` is in six of the seven and means the same thing in all of
+  them, which is why it is not folded anywhere.
+* **A withdrawn member is recorded, not deleted.** `forecasts` once held
+  `no_tolerance` and `entailment` two more; they were withdrawn when it was
+  shown no input could reach them, and the reasoning stays in
+  `subenvelope.py` beside the sets. A member nobody can construct an input for
+  makes the set a worse instrument.
+
+This table is DERIVED from `subenvelope.py`, not transcribed beside it, and a
+test fails when the two disagree. A table maintained by hand next to a
+frozenset is a second copy of one closed set, which is the drift the module
+itself refuses one level further in.
+
+---
+
 ## 3. The read surface that is not `check`
 
 The vocabulary above is everything the engine refuses to **judge**. It is not