sayfirst-cli 0.2.0__tar.gz → 0.3.1__tar.gz

{sayfirst_cli-0.2.0 → sayfirst_cli-0.3.1}/.github/workflows/ci.yml

@@ -6,9 +6,9 @@
 # run on a machine has to be given. Apart from it, what a contributor runs
 # locally is what decides a merge; a step that exists only here is a step nobody
 # can reproduce, and `tests/test_gate_modes.py` fails if this file grows a
-# second one. The rest of what is written below decides which of the gate's two
-# green outcomes this run reached and renders it, which is a rendering job
-# rather than a check.
+# second one. The rest of what is written below decides which leg of the gate
+# this run is entitled to and renders which of its two green outcomes it
+# reached, which is routing and rendering rather than a check.
 #
 # This workflow publishes nothing. `release.yml` is the only file here that can,
 # and only on a tag; a publish step added here is a constitutional change, not a
@@ -33,17 +33,19 @@
 # text: neither file spells the version, because a version spelled twice is a
 # version that will eventually be spelled two ways.
 #
-# WHY A REDUCED LEG STILL RUNS, AND NOW RUNS ON EVERY RUN. A machine that cannot
-# reach that repository still exists — a fork with no network, a runner behind a
-# proxy, a contributor offline — and what it gets is a contract that is simply
+# WHY A REDUCED LEG STILL EXISTS. A machine that cannot reach that repository
+# still exists — a fork with no network, a runner behind a proxy, a contributor
+# offline — and what it gets is a contract that is simply
 # absent. An absent contract is a fact about the world, not a crash. Article 2
 # says an absence is "never rendered as a negative fact, a zero or a healthy
 # state", so `scripts/gate.sh` has three outcomes and this workflow renders
 # three and not two:
 #
-#   gate (full)                     the contract was built from the control
+#   gate (full, python X.Y)         the contract was built from the control
 #                                   plane's public repository, at the tag this
-#                                   client pins, and every check ran.
+#                                   client pins, and every check ran — once per
+#                                   interpreter `requires-python` admits, since
+#                                   a release installs on any of them.
 #                                   `scripts/gate.sh` exits 0.
 #   gate (reduced — contract        no checkout of the control plane was made,
 #   absent, some checks not run)    so the contract is absent. Format, lint and
@@ -57,16 +59,36 @@
 #                                   gate came back reduced, and a reduced job
 #                                   whose gate came back full.
 #
-# The two legs run side by side now, rather than one of them instead of the
-# other. Which leg ran used to be decided by whether this repository held a
-# credential, and that question no longer exists; what is left is a leg that
-# proves the tree against the contract and a leg that proves the reduced path
-# still renders honestly on a machine that has nothing, which is the machine
-# article 16 is about. A reduced run proves nothing about the contract and
-# nothing about the installed dependency closure of articles 13 and 14, and
-# today nothing about this client against a daemon either — the job lists what
-# it did not run, so that sentence is checkable against the run rather than
-# trusted from here.
+# EXACTLY ONE OF THE TWO LEGS RUNS, AND ONE JOB DECIDES WHICH. The first job
+# below asks the world a single question — can this runner read the control
+# plane's public repository at the tag this client pins — and the two legs carry
+# the two answers as their conditions. It is asked of the remote, with no
+# credential and no checkout, because it is the same question the gate will meet
+# a minute later: a runner that cannot read the tag cannot build the contract,
+# and a runner that can has no business running a leg whose entire claim is that
+# the contract is missing.
+#
+# Running both instead is not a stricter gate, and this file tried it for
+# exactly one run. The reduced leg went red on a runner that could read the tag
+# perfectly well: its step requires the gate to come back reduced, the gate had
+# every reason to come back full, and « the contract is absent » was false on
+# that machine. A leg whose premise does not hold is a check of a machine that
+# is not this one.
+#
+# WHAT THEN PROVES THE REDUCED PATH, since a run of this repository can reach
+# the tag and will therefore always take the full leg. The full leg proves it:
+# `tests/test_contract_absence.py` runs this whole suite again in a child
+# interpreter with the contract's packages made unimportable, and requires that
+# run to come back green with every check it could not run named and counted.
+# That guard is why the reduced path cannot rot unobserved while the leg that
+# renders it sits skipped — which is how the fifteen tests that ask for the
+# contract only when they run came to be discovered by a public runner rather
+# than by this repository.
+#
+# A reduced run proves nothing about the contract and nothing about the
+# installed dependency closure of articles 13 and 14, and today nothing about
+# this client against a daemon either — the job lists what it did not run, so
+# that sentence is checkable against the run rather than trusted from here.
 name: gate
 
 on:
@@ -77,28 +99,38 @@ permissions:
   contents: read
 
 jobs:
-  full:
-    name: gate (full)
+  # Asked once, before either leg, and answered about the world rather than
+  # about this repository: the tag is derived from the pins, the remote is asked
+  # whether it has that tag, and the answer is written out for the two legs to
+  # read. No credential, and no clone — `git ls-remote` reads refs and nothing
+  # else — so a fork gets a truthful answer about its own machine, which is the
+  # only kind of answer article 16 can be held to.
+  #
+  # Why the question is the tag and not the network: a runner that can reach
+  # github.com and finds no such tag is in exactly the position of one that can
+  # reach nothing at all — there is no source to build the contract from — and
+  # the gate's reduced outcome is what honestly describes both.
+  reachability:
+    name: is the contract reachable
     runs-on: ubuntu-latest
+    outputs:
+      contract: ${{ steps.reachable.outputs.contract }}
+      tag: ${{ steps.contract.outputs.tag }}
     steps:
       - uses: actions/checkout@v5
         with:
           path: sayfirst-cli
 
-      - uses: astral-sh/setup-uv@v5
-        with:
-          version: "0.12.5"
-
-      # Read out of the project file, never spelled here: `scripts/gate.sh`
-      # reads the same pin out of the same file, and `release.yml` derives the
-      # same tag with this same script — held as one text by
+      # Read out of the project file, never spelled here: the gate reads the
+      # same pin out of the same file, and `release.yml` derives the
+      # same tag with this same shell — held as one text by
       # `tests/test_gate_modes.py`, because two readings of one rule is how two
       # files stop agreeing about it. Shell rather than an interpreter, so that
-      # the only program of this repository this job runs is the gate.
+      # this job runs no program of this repository at all.
       #
       # THE ASSUMPTION THIS DERIVATION RESTS ON, stated rather than left to be
-      # discovered. One tag of the control plane is checked out here, and this
-      # client pins TWO of the distributions that tag builds. The tag is
+      # discovered. One tag of the control plane is what the full leg reads, and
+      # this client pins TWO of the distributions that tag builds. The tag is
       # derived from the `sayfirst-contract` pin because the control plane moves
       # every distribution it publishes to one version together — its own rule,
       # held by its own guard, and by nothing in this repository. So the step
@@ -126,10 +158,69 @@ jobs:
           echo "tag=v${pinned}" >> "$GITHUB_OUTPUT"
           echo "The contract is read at v${pinned}." >> "$GITHUB_STEP_SUMMARY"
 
+      # The two words this whole file routes on. `--exit-code` is what makes a
+      # tag that is not there a status rather than empty output silently read as
+      # success, and the tag is passed in as an environment variable rather than
+      # interpolated into the shell, which is this repository's rule for every
+      # value a runner computes.
+      - name: Whether that tag can be read with nothing but this repository
+        id: reachable
+        env:
+          tag: ${{ steps.contract.outputs.tag }}
+        run: |
+          if git ls-remote --exit-code --tags \
+               https://github.com/fredaime/sayfirst-control-plane.git "refs/tags/${tag}" \
+               >/dev/null 2>&1; then
+            echo "contract=reachable" >> "$GITHUB_OUTPUT"
+            {
+              echo "### the contract is reachable at ${tag}"
+              echo ""
+              echo "The full gate runs, and the reduced leg does not: on this runner the"
+              echo "contract is not absent, so a leg whose name says it is would be reporting"
+              echo "about a machine other than this one."
+            } >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "contract=absent" >> "$GITHUB_OUTPUT"
+            {
+              echo "### the contract cannot be read at ${tag}"
+              echo ""
+              echo "Nothing here holds a credential, so this is a fact about the runner and"
+              echo "the tag, not about permission: either the tag is not published yet or"
+              echo "this machine cannot reach the repository that carries it. The reduced"
+              echo "leg runs instead of the full one and says, in its own name, what it did"
+              echo "not prove."
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+  full:
+    name: gate (full, python ${{ matrix.python }})
+    needs: reachability
+    if: needs.reachability.outputs.contract == 'reachable'
+    runs-on: ubuntu-latest
+    # Every interpreter `requires-python` admits. Python 3.14 changed what
+    # `Path.exists` answers and gave `json` a `__main__`, and a gate that ran one
+    # interpreter found neither: a range this client installs on is a range
+    # this gate runs.
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          path: sayfirst-cli
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.12.5"
+
+      # The tag is the one the job above derived, read as its output rather than
+      # derived a second time here: this job runs because that job answered, and
+      # a second derivation could answer differently.
       - uses: actions/checkout@v5
         with:
           repository: fredaime/sayfirst-control-plane
-          ref: ${{ steps.contract.outputs.tag }}
+          ref: ${{ needs.reachability.outputs.tag }}
           path: sayfirst-control-plane
           fetch-depth: 0
 
@@ -137,13 +228,14 @@ jobs:
         working-directory: sayfirst-cli
         env:
           SAYFIRST_CONTRACT_SOURCE: ${{ github.workspace }}/sayfirst-control-plane
-          SAYFIRST_CONTRACT_REF: ${{ steps.contract.outputs.tag }}
+          SAYFIRST_CONTRACT_REF: ${{ needs.reachability.outputs.tag }}
+          SAYFIRST_PYTHON: ${{ matrix.python }}
         run: |
           status=0
           ./scripts/gate.sh || status=$?
           case "$status" in
             0)
-              echo "### gate: full green" >> "$GITHUB_STEP_SUMMARY"
+              echo "### gate: full green (python ${{ matrix.python }})" >> "$GITHUB_STEP_SUMMARY"
               echo "" >> "$GITHUB_STEP_SUMMARY"
               echo "Format, lint, every test and the dependency-closure guard of articles 13" >> "$GITHUB_STEP_SUMMARY"
               echo "and 14 ran against a contract built from the control plane's public" >> "$GITHUB_STEP_SUMMARY"
@@ -158,8 +250,15 @@ jobs:
               ;;
           esac
 
+  # The other answer. This leg runs when the tag could not be read, which is
+  # the only condition under which its name is true — and skipping it otherwise
+  # is not a gap: the full leg re-runs this whole suite with the contract's
+  # packages hidden, so the reduced path is proven on every run of this
+  # repository even though this job is where it is rendered.
   reduced:
     name: gate (reduced — contract absent, some checks not run)
+    needs: reachability
+    if: needs.reachability.outputs.contract == 'absent'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5

sayfirst_cli-0.3.1/CHANGELOG.md

@@ -0,0 +1,184 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Changelog
+
+Every release of this client carries a section here, named for the version the project file
+declares; a release with no section fails the gate.
+
+## Unreleased
+
+## 0.3.1
+
+- **`instrument verify` says how a run ended when the program raised, too.** The harness said
+  its own ending only for a program that returned, so a program that ended on an exception before
+  a line of it was seen — a script that does not compile, a module whose bytecode another Python
+  wrote — left no ending behind, and the command answered `4` and « the verification did not run
+  to a conclusion »: « the control plane could not be asked », about a plane that had answered.
+  It now answers `7`, « the verifier never saw the program's own code start », naming the
+  exception the program ended on; the program's own traceback is still printed. For the same
+  reason, a program that caught the abort of an unreadable chain and then raised an exception of
+  its own now gets the chain's ending (`4`, the transport's own problem code and sentence) rather
+  than the generic one.
+- The contract and the boundary move to 0.3.1, released with this client.
+- A `python` the shell cannot find is refused as before (64), and the refusal now names
+  the `python3` on the same PATH.
+- Every program the README and the quickstart run is spelled `python3 …`; the
+  quickstart starts the daemon again before section 7, shows a closed epoch verified,
+  and says how long a rejection stands.
+
+## 0.3.0
+
+- **`--socket` is optional for a per-user profile**, on every verb that opens a connection. Given
+  none, the client looks at the per-user default address — the contract's own rule, the one a
+  per-user daemon given no address binds by — and at nothing else: nothing is searched for, and
+  whoever answers is still verified to be the expected account's process before a byte is sent. A
+  `--socket` somebody typed is the address. A system profile is never given one and still names
+  it (`64` otherwise). **What changes for a caller:** an invocation with no `--socket` used to end
+  as a usage error (`2`); it now asks, and with nobody at the default address it answers « could
+  not ask » (`4`), naming the address it looked at. `evidence audit` with neither `--file` nor
+  `--socket` is an online audit at that address rather than a usage error. Needs the contract
+  distribution that publishes the rule, which is the one after 0.2.0.
+- **`--pack` takes the name of a pack this distribution ships** (`--pack subprocess`), as well as
+  a directory. The spelling alone decides: a designation with a path separator in it, or `.` or
+  `..`, is a directory; a bare word is a shipped pack's name and is never read as a directory of
+  the working directory. **What changes for a caller:** a pack directory designated by a bare
+  relative word (`--pack own-pack`) is now refused (`64`) with the spelling that names it
+  (`--pack ./own-pack`). Absolute paths and paths with a separator are read exactly as before.
+  `packs check` takes the same two spellings. `docs/PACKS.md` says why this is a designation and
+  not a registry.
+- **A target whose first word is `python`, `python3` or `python3.N` is run by that interpreter.**
+  The whole command is handed to it, the boundary is installed in that process, and the client,
+  the boundary and the contract are lent to it by name — three packages and their metadata, and
+  nothing else of this environment. A program in a project's own environment therefore keeps its
+  dependencies when this client is installed as a tool. The interpreter has to be Python 3.12 or
+  later, and interpreter options are not carried. Before this, such a target was refused (`64`) as
+  a script that does not exist; a target with no interpreter word runs as it always did.
+- **An executable script hands over by its shebang.** An agent started as a console script
+  (`-- ./myagent`) rather than as `python …` is run by the interpreter its shebang names —
+  including `#!/usr/bin/env python3` — so a console-script agent in a project's environment keeps
+  its dependencies too. A shebang naming this same interpreter, and a non-executable file, are
+  unchanged. **What changes for a caller:** an executable whose shebang names another Python used
+  to run in this command's interpreter and fail to import the project's packages; it now runs in
+  the interpreter the shebang names.
+- **A runner in the first position is refused** (`64`): `-- uv run app.py`, `-- poetry run app.py`
+  and their kind start an interpreter the boundary is not in, so handing the runner over would
+  govern nothing. The refusal names the two spellings that work — name the interpreter, or ask the
+  runner for it once. Before, `uv` was reported as a script that does not exist.
+- **`instrument verify` matches a run's records by a correlation it stamps, not by their
+  connection.** A program that makes two effects of different kinds is two asks, and the shipped
+  boundary holds one connection per grant, so its records span two connections. They are still one
+  run's, told so by a per-run token the verifier stamps on every ask and the plane records on the
+  effect (`correlation_source: boundary_supplied`). **The defect this fixes:** such a run reported
+  the second effect `unjudged` and exited `7`; it now verifies clean. The token also tells a
+  concurrent same-account run's records apart, which the connection check could not, and it holds
+  the first record as well as the rest. Needs the boundary distribution that stamps it, the one
+  after 0.2.0.
+- **The `unjudged:` line names the reason the run actually recorded**, one per distinct cause,
+  rather than always saying an effect named a start file. A count made of a damaged range, an
+  interrupted walk, another execution's record or an uninterposed path now reads as what it was.
+- `docs/PACKS.md` records, with the evidence, why no convenience pack for `requests`, `httpx`,
+  `os.system` or a Postgres driver is shipped — a limit of the verifier, not of the classification.
+  The verifier confirms an effect from a distinct CPython audit event and shares no state with the
+  engine; `requests`/`httpx`/Postgres emit nothing distinct from `socket.connect`, and `os.system`'s
+  module is `os`, which the engine imports throughout, so a pack for it would make the engine-
+  agnosticism guard read every `import os` as a special case. Each could be governed by hand against
+  `sayfirst-boundary`; none can be shipped as a verifiable pack without weakening a guard.
+- **`instrument run --follow-children`** installs the boundary in the Python children the program
+  spawns with its environment, before the child's code runs, so a program that starts workers or
+  tools of its own has their effects governed too — and a grandchild started the same way. It works
+  by a `sitecustomize` on the child's import path (`src/sayfirst_cli/instrument/follow.py`), needs
+  this client installed in the interpreter the children run, and fails a child **closed** once the
+  bootstrap runs: a child that cannot install the boundary raises before its program runs, and a
+  child whose daemon is unreachable fails at the ask exactly as the parent does. A child the
+  bootstrap never reaches is not followed and runs as it would without the flag: one started with
+  `-S`, `-I` or `-E`, or given a `PYTHONPATH` of its own. It is `run`'s flag, not `verify`'s: a spawned
+  child is a separate process the single-process proof cannot see (`harness.py` counts such a child
+  as coverage it could not judge), so following would govern what the proof misses.
+- With no `--socket` and nothing at the default address, `instrument run` says which address it
+  looked at before the program starts. Nothing else about that run changes: a program that asks
+  nothing still runs, and an effect a pack names still fails closed, as the program's own
+  exception.
+- The quickstart is three commands, and the page is a transcript of them.
+- **`instrument run` ends with the outcome's own status when the program does not handle it.** A
+  boundary outcome the program lets escape — denied, suspended, refused, could not ask — used to
+  end the run as any uncaught exception does, with the interpreter's `1`, which is this client's
+  « deny » for all four. The traceback is still the program's; the status is now `1`, `5`, `3` or
+  `4`. A program that catches the outcome and exits on its own still ends with its own status.
+- **`instrument verify` asks for every effect.** The boundary in front of a verified program holds
+  no grant, so an identical effect repeated while a grant lived — answered with nothing asked and
+  nothing recorded — is no longer reported `ungoverned` and stopped (`6`). `instrument run` still
+  holds its grants (article 10).
+- **`instrument verify` counts one spawn once.** `subprocess.Popen` creates its process through
+  `os.posix_spawn` or, from Python 3.14, `_posixsubprocess.fork_exec`, both paths the subprocess
+  pack names as not interposed, so one governed spawn was reported with an unjudged effect and
+  `7`. A point may now name, among its `uninterposed_events`, the `inner_events` its own call
+  raises; such an event is paired with the call it judged when it is that thread's very next event
+  and carries the same argument vector, and is counted otherwise. The subprocess pack also names
+  `_posixsubprocess.fork_exec`, which is how `multiprocessing` starts a process by default on Linux
+  from 3.14, so such a start is counted instead of passing unseen.
+- **`instrument verify` answers `3` for a chain read the plane refused**, as every other command
+  does, rather than `4`; and `7` rather than `4` when it never saw the program's own code start,
+  since the plane had been asked. `docs/PACKS.md` lists the statuses.
+- **Every connection is bounded.** `ask`, every read and the verifier's chain walk wait at most
+  five seconds for an answer; a far end that accepts and never answers is « could not ask » (`4`)
+  instead of a command that hangs. A named `--socket` is made absolute once, so a program that
+  changes directory asks the daemon it was pointed at (with the contract distribution of this
+  release).
+- **Smaller corrections.** A uid with no account name is spelled `user:<uid>`, as the daemon names
+  it, instead of ending `instrument run` in a traceback; an `ask` answer nested past the reads'
+  depth bound is an answer this client could not read (`4`), not a traceback; `evidence export`
+  that cannot write its bundle says « could not save » (`7`); on Python 3.14, an `--out` path this
+  client cannot look at is still refused (`64`) before anything is asked, and an entry
+  `evidence exports` cannot look at is still « could not check » (`7`); `approvals` names the
+  person who acted; `packs check` refuses a pack whose `uninterposed_events` or `inner_events` the
+  verifier would refuse.
+- **Interpreter hand-over.** A script whose shebang names a Python that is not there is refused
+  (`64`) instead of being run by this client's own interpreter; an interpreter newer than the lent
+  packages declare (3.15 and later) is refused; `--follow-children` under a named interpreter that
+  does not have this client installed is refused, where every Python child used to die at
+  start-up; and under `PYTHONSAFEPATH` the head of the import path is left as the interpreter gave
+  it, where the launcher used to replace an entry of the person's own.
+- The full gate runs on Python 3.12, 3.13 and 3.14, the interpreters `requires-python` admits.
+
+- Every commit of a change is read for its sign-off on every pull request, and one that carries
+  none is refused by name. A range that cannot be read is refused too, rather than reported as
+  passing.
+- The publication checklist carries every act the constitution names, in the order they are
+  performed, and a guard fails when one of them stops being a line of it. The security policy says
+  which of article 0's two paths this repository is published by: a fresh repository, never a
+  change of visibility.
+- The gate reduces on a machine with no contract instead of failing there. A test that asks for a
+  command only when it runs — this client imports a verb when it dispatches it — is now stood
+  down by name and counted, the way a module that could not be imported already was, and a run
+  with the contract hidden is required to come back green rather than merely to collect.
+- One of the two gate legs runs, decided by whether the control plane's public repository can be
+  read at the tag this client pins. The question is asked once, of the remote, with no credential;
+  a leg reporting that the contract is absent no longer runs on a machine where it is not.
+
+## 0.2.0
+
+- The evidence surface reads and verifies: `history` pages a scope, `audit` puts the served
+  verdict beside a local check and names a finding wherever the two disagree, `export` saves a
+  bundle a third party verifies offline with the contract distribution alone, and `exports`
+  checks a directory of saved bundles without opening a socket.
+- `instrument run` puts the boundary in front of somebody else's program, reversibly and writing
+  nothing; `instrument verify` runs it again under the interpreter's own audit hook and proves,
+  from that and the scope's evidence chain alone, that every effect of a named kind was preceded
+  by a decision; `instrument apply` is reserved and refuses, saying so.
+- `trace` reads back the record of one decision and follows it into the evidence that holds it:
+  the record itself, and where it sits in the chain, bounded to the pages the read walks. Like
+  every read from a daemon it names its scope explicitly, and it exits `0` on a read whatever the
+  decision it read said.
+- `explain` renders the reason the control plane gave for a decision — the rule it applied and
+  the policy version it ran under — in the plane's own words, and composes none of its own. A
+  client explains and invokes control semantics; it never derives them, and a command that
+  reasoned here would be a second control plane with no evidence behind it.
+- `packs list` prints the convenience packs this distribution ships, one line each with the path
+  `--pack` accepts, and `packs check` reads one the way the engine will.
+- `approvals` shows a suspended ask and ends the wait, so the next ask runs the body once.
+- A verdict the verifier could not reach is rendered as it was given rather than as a negative
+  fact about the chain.
+- The release itself: this distribution moves to `0.2.0`, and installing it pins
+  `sayfirst-contract==0.2.0` and `sayfirst-boundary==0.2.0` — the contract this client speaks and
+  the runtime a governed program holds its grant in — at that version and no other. An
+  installation of this version therefore carries exactly those two, and upgrading it moves all
+  three together.