sayfirst-cli 0.2.0__py3-none-any.whl

sayfirst_cli/packs/database/interpose.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Ask before a database is opened. There is nothing afterwards to record.
+
+Governs the one attribute this pack's point names: the call this module's
+`[[point]]` wraps opens a database and hands back a connection, and that call
+is the whole of what this pack governs.
+
+`database` — the database the call is asked to open, rendered as the text it
+names whatever shape the caller passed it in — is the one argument sent to the
+boundary. Nothing else of the call is sent (article 11: what is sent is a
+digest, and which arguments it covers is declared, never implicit).
+
+**As text, whatever the caller's type — the same rule `subprocess`'s pack
+already keeps.** `sqlite3.connect` accepts a plain `str` — a file path, or the
+special name for an in-memory database — a `bytes` path, or an
+`os.PathLike`; all three name one database. Each is decoded to the text it
+names with `os.fsdecode` (the interpreter's own path decoding, and the exact
+function the sibling `subprocess` pack uses for its own `args`) before the
+digest is taken, so `sqlite3.connect("/x/db")` and
+`sqlite3.connect(b"/x/db")` — two spellings that open the same file — arrive
+at the boundary under one digest. Rendering the `bytes` shape with `str()`
+instead would send its `repr` (`"b'/x/db'"`), which is a second, unrelated
+digest for the same database and a policy keyed on `database` could be stepped
+around by spelling the path in bytes — exactly the defect class `subprocess`'s
+own docstring already names for its own argument.
+
+**Bound by position, not by `inspect.signature`.** `subprocess`'s pack and this
+distribution's `http-client` pack both bind the call against
+`inspect.signature(original)`, because `subprocess.Popen` and
+`urllib.request.urlopen` both support it. The real `sqlite3.connect` does not:
+its C implementation's own printed signature carries a default —
+`autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL` — that is not a Python literal,
+so `inspect.signature(sqlite3.connect)` raises on the very interpreter this
+pack ships for. That is a fact about the standard library's own C
+implementation on this Python version, not something fixable from outside it.
+`database` is the DB-API 2.0 shape's first parameter — the rule every driver's
+`connect` follows, this one included — so it is read from the keyword if the
+caller used one and from the first positional argument otherwise: exactly what
+`inspect.signature(...).bind_partial(...)` would have read, had it been able
+to run at all.
+
+**No outcome digest.** A connection is not an outcome: unlike a spawned
+process, which has a pid the moment it exists, or a finished HTTP exchange,
+which has a status, a connection that has just been opened has nothing yet
+worth digesting, and a failed open never reaches the line that would record
+one — the exception propagates out of the call itself, before the ask's `with`
+block would have anything to say. So this pack's point declares no outcome
+digest, and none is recorded here.
+
+The wrapper is a plain function, so what it returns is the real connection
+object, never a stand-in for it.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def wrap(original, capability, boundary):
+    """Ask, open, and hand back the connection. See the module docstring for
+    why `database` is read positionally rather than through `inspect.signature`."""
+
+    def wrapper(*args, **kwargs):
+        database = kwargs.get("database", args[0] if args else None)
+        arguments = {"database": _rendered(database)}
+        with boundary.request(capability, arguments):
+            return original(*args, **kwargs)
+
+    return wrapper
+
+
+def _rendered(value):
+    """`database` as the digest sees it: text, whatever the caller spelled it in.
+
+    `bytearray` is converted to `bytes` first because `os.fsdecode` does not
+    accept it directly (it takes `str`, `bytes` and `os.PathLike`), not because
+    `sqlite3.connect` is known to accept a `bytearray` database — the rendering
+    is defined for whatever `original` is actually called with, the same way
+    `subprocess`'s own `_text` is.
+    """
+    if isinstance(value, bytearray):
+        value = bytes(value)
+    if isinstance(value, str | bytes | os.PathLike):
+        return os.fsdecode(value)
+    return str(value)

sayfirst_cli/packs/database/pack.toml

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+
+[pack]
+name = "database"
+classification = "convenience"
+classified_on = "2026-09-15"
+
+[[point]]
+module = "sqlite3"
+attribute = "connect"
+capability = "database.open"
+digest = ["database"]
+audit_event = "sqlite3.connect"

sayfirst_cli/packs/http-client/NOTE.md

@@ -0,0 +1,4 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+This is a convenience pack (article 9). A competent engineer would rebuild it in
+a day from `urllib.request`'s public documentation: one attribute, one call shape,
+one argument that names the effect. Classified on 2026-09-15.

sayfirst_cli/packs/http-client/interpose.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Ask before an HTTP request leaves the process, and record what came back.
+
+Governs `urllib.request.urlopen` — the one attribute this pack's point names.
+It is the one function every scheme `urllib.request` handles goes through —
+`http`, `https`, `file` and `data` alike, and every higher-level call the
+standard library builds on top of it too — so a `file:` or `data:` read is
+asked under this pack's capability as well, since the interpreter offers no
+narrower seam than this one function; the URL in the digest is what
+distinguishes them.
+
+`url` — the address the call is asked to open, rendered as the text it names
+whatever shape the caller passed it in — is the one argument sent to the
+boundary. Nothing else of the call is sent (article 11: what is sent is a
+digest, and which arguments it covers is declared, never implicit).
+
+**As text, whatever the caller's type.** The call accepts a plain string, or a
+`Request` object built up with headers and a method of its own; a `Request`
+carries the address it will open under `full_url`, so that is read out rather
+than rendering the object itself, which would give its `repr` and not the
+address.
+
+The wrapper is a plain function, so what it returns is the real response
+object, never a stand-in for it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+
+
+def wrap(original, capability, boundary):
+    """Bind the call to `original`'s own signature, ask, open, and record the status.
+
+    The ask carries `url` rendered as text — a `Request`'s own address, or
+    `str()` of whatever else was passed — so the digest is computable
+    whichever shape the caller called with.
+    """
+    signature = inspect.signature(original)
+
+    def wrapper(*args, **kwargs):
+        bound = signature.bind_partial(*args, **kwargs)
+        arguments = {"url": _rendered(bound.arguments.get("url"))}
+        with boundary.request(capability, arguments) as handle:
+            response = original(*args, **kwargs)
+            status = getattr(response, "status", None)
+            if status is not None:
+                # Nothing more of the response is worth an outcome: the status
+                # is what the digest names, and nothing else of the response
+                # is sent anywhere. `hasattr` alone is not enough: a `file:`
+                # or `data:` read returns `urllib.response.addinfourl`, which
+                # HAS a `status` attribute that is always `None` — recording a
+                # digest for it would claim an outcome the response does not
+                # have (`sha256("status:None")` looks like a real status to
+                # anything reading the chain back).
+                handle.record_outcome(_status_digest(status))
+            return response
+
+    return wrapper
+
+
+def _rendered(value):
+    """`url` as the digest sees it: a `Request`'s own address, or text of whatever else."""
+    if hasattr(value, "full_url"):
+        return value.full_url
+    return str(value)
+
+
+def _status_digest(status):
+    """`sha256("status:" + str(status))`, as the manifest's `audit_event` expects to see it."""
+    return hashlib.sha256(f"status:{status}".encode()).hexdigest()

sayfirst_cli/packs/http-client/pack.toml

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+
+[pack]
+name = "http-client"
+classification = "convenience"
+classified_on = "2026-09-15"
+
+[[point]]
+module = "urllib.request"
+attribute = "urlopen"
+capability = "net.egress"
+digest = ["url"]
+audit_event = "urllib.Request"

sayfirst_cli/packs/subprocess/NOTE.md

@@ -0,0 +1,4 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+This is a convenience pack (article 9). A competent engineer would rebuild it in
+a day from the `subprocess` module's public documentation: one attribute, one call shape,
+one argument that names the effect. Classified on 2026-09-15.

sayfirst_cli/packs/subprocess/interpose.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Ask before a process is spawned, and record which one answered.
+
+Governs `subprocess.Popen` — the one attribute this pack's point names. It
+governs `subprocess.run`, `subprocess.call` and `subprocess.check_output` too,
+without a point of their own, because all three call the module's own global
+`Popen` to do their spawning: wrapping the name they call is wrapping them,
+and a second point for `run` would be asking about one spawn twice.
+
+`args` — a command line as text, or the sequence `Popen` accepts rendered as a
+list of text; anything else (there should be none: `Popen`'s first argument is
+required) is rendered with `str()`, so the digest `pack.toml` declares
+(`digest = ["args"]`) is always computable — is the one argument sent to the
+boundary. Nothing else of the call is sent (article 11: what is sent is a
+digest, and which arguments it covers is declared, never implicit).
+
+**As text, whatever the caller's type.** `Popen` accepts a command line as
+`str`, as `bytes`, as a `os.PathLike`, or as a sequence of any of those, and
+they all spawn the same process. So each is decoded to the text it names
+(`os.fsdecode`, the interpreter's own path decoding) before the digest is
+taken: two calls that spawn one process have one digest, and a policy keyed on
+the command line — which is all `digest = ["args"]` gives the plane — cannot be
+stepped around by spelling the same command in bytes.
+
+The wrapper is a plain function, not a class, so `subprocess.run`'s own
+`with Popen(...) as process:` still works: what this returns is the real
+`Popen` instance, never a stand-in for it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+import os
+from collections.abc import Sequence
+
+
+def wrap(original, capability, boundary):
+    """Bind the call to `original`'s own signature, ask, spawn, and record the pid.
+
+    The ask carries the command line as text — a `bytes` command line is
+    decoded rather than digested as bytes — so the same spawn has the same
+    digest whatever type the caller spelled it in.
+    """
+    signature = inspect.signature(original)
+
+    def wrapper(*args, **kwargs):
+        bound = signature.bind_partial(*args, **kwargs)
+        arguments = {"args": _rendered(bound.arguments.get("args"))}
+        with boundary.request(capability, arguments) as handle:
+            process = original(*args, **kwargs)
+            if hasattr(process, "pid"):
+                # A process that has just been spawned has a pid and nothing
+                # else to report yet; that is the whole of the outcome here.
+                handle.record_outcome(_pid_digest(process.pid))
+            return process
+
+    return wrapper
+
+
+def _rendered(value):
+    """`args` as the digest sees it: text, a list of text, or `str()` of whatever else.
+
+    The one command line a caller may spell four ways — `str`, `bytes`,
+    `bytearray`, `os.PathLike` — is one command line, and `bytes` is decoded
+    before the sequence branch is even considered: it IS a sequence, of
+    integers, and rendering it as one would send the plane a list of byte codes
+    for a command a second caller sends as a string.
+    """
+    if isinstance(value, str | bytes | bytearray | os.PathLike):
+        return _text(value)
+    if isinstance(value, Sequence):
+        return [_text(item) for item in value]
+    return str(value)
+
+
+def _text(value):
+    """One command line, or one element of one, as the text it names."""
+    if isinstance(value, bytearray):
+        # `os.fsdecode` takes `str`, `bytes` and `os.PathLike`, and a
+        # `bytearray` is none of the three.
+        value = bytes(value)
+    if isinstance(value, str | bytes | os.PathLike):
+        return os.fsdecode(value)
+    return str(value)
+
+
+def _pid_digest(pid):
+    """`sha256("pid:" + str(pid))`, as the manifest's `audit_event` expects to see it."""
+    return hashlib.sha256(f"pid:{pid}".encode()).hexdigest()

sayfirst_cli/packs/subprocess/pack.toml

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+
+[pack]
+name = "subprocess"
+classification = "convenience"
+classified_on = "2026-09-15"
+
+[[point]]
+module = "subprocess"
+attribute = "Popen"
+capability = "process.spawn"
+digest = ["args"]
+audit_event = "subprocess.Popen"

sayfirst_cli/packs_cmd.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sayfirst packs`: list and check the convenience packs this distribution ships.
+
+Article 9's packs are designated by path, never by name — `instrument run
+--pack` reads only the directory a person types, and consults no registry, no
+default set and no name resolution of its own (`docs/PACKS.md`). This command
+does not change that: `list` prints, for each pack this distribution ships
+beside itself, the one path `--pack` would accept for it, so a person has
+something to copy rather than something to guess; `check` reads a path the
+same way the engine will, before a program is ever run with it.
+
+Neither verb ends in a traceback. A pack that does not read is named with the
+member and the rule it broke, and the exit code says so — for `list` as much as
+for `check`, since the command a person uses to discover what is shipped is the
+one that has to be able to say that something shipped is broken.
+
+Read from the *installed* package with `importlib.resources`, never from a
+path built off this file's own location: the packs this prints are the ones
+this distribution actually carries, wherever it was installed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.resources
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TextIO
+
+from . import exit_codes
+from .instrument import manifest
+
+
+def shipped_packs() -> list[Path]:
+    """Every pack directory this installed distribution carries, sorted by path.
+
+    A directory counts as a pack candidate here by carrying a manifest, not by
+    its name — `__pycache__` and anything else beside the packs is silently
+    not a pack rather than a reason this call fails; `manifest.read_pack`
+    still refuses one that names a manifest but is not, in fact, complete.
+    """
+    root = importlib.resources.files("sayfirst_cli.packs")
+    if not root.is_dir():
+        return []
+    return sorted(
+        Path(str(item))
+        for item in root.iterdir()
+        if item.is_dir() and (item / manifest.MANIFEST_FILE).is_file()
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sayfirst packs",
+        description="List and check the convenience packs this distribution ships (article 9).",
+    )
+    verbs = parser.add_subparsers(dest="verb", required=True)
+    verbs.add_parser("list", help="one line per shipped pack: name, capabilities, path")
+    checking = verbs.add_parser("check", help="read one pack directory the way the engine will")
+    checking.add_argument("path", metavar="PATH", help="the pack directory to read")
+    return parser
+
+
+def main(
+    argv: Sequence[str] | None = None, *, out: TextIO | None = None, err: TextIO | None = None
+) -> int:
+    stdout = out or sys.stdout
+    stderr = err or sys.stderr
+    forwarded = list(sys.argv[1:] if argv is None else argv)
+    arguments = build_parser().parse_args(forwarded)
+    if arguments.verb == "list":
+        return _list(stdout, stderr)
+    return _check(Path(arguments.path), stdout, stderr)
+
+
+def _list(stdout: TextIO, stderr: TextIO) -> int:
+    """One line per shipped pack: its name, every capability it declares, its path.
+
+    A pack whose manifest will not read is named on stderr with the rule it
+    broke — what `check` does with the one pack it is given — and the listing
+    goes on, so the packs after it in sort order are still printed. The exit
+    code is the misuse `check` uses, because a listing that omitted a broken
+    pack and exited 0 would render an absence as a healthy state (article 2),
+    and because a traceback out of this client is never how a pack's problem is
+    reported.
+
+    64 for a pack the *distribution* ships is the honest half of the answer
+    rather than a perfect fit — the caller typed nothing wrong, and something
+    this command named cannot be read. `exit_codes.py` states the widened
+    reading beside the number, and says why a code of its own would cost more
+    than it bought: no caller can act differently on the two.
+    """
+    unread = 0
+    for directory in shipped_packs():
+        try:
+            pack = manifest.read_pack(directory)
+        except manifest.PackInvalid as invalid:
+            stderr.write(f"invalid {directory}: {invalid}\n")
+            unread += 1
+            continue
+        capabilities = " ".join(dict.fromkeys(point.capability for point in pack.points))
+        stdout.write(f"{pack.name} {capabilities} {directory}\n")
+    return exit_codes.EXIT_MISUSE if unread else 0
+
+
+def _check(path: Path, stdout: TextIO, stderr: TextIO) -> int:
+    """Read one pack, the way `instrument run` will, before anything is run with it."""
+    try:
+        pack = manifest.read_pack(path)
+    except manifest.PackInvalid as invalid:
+        stderr.write(f"{invalid}\n")
+        return exit_codes.EXIT_MISUSE
+    stdout.write(f"ok {pack.name}\n")
+    return 0

sayfirst_cli/pages.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+"""One evidence page, validated once for every command that walks one.
+
+`trace` and `evidence` both page through scoped evidence, and each carried its
+own copy of this. The two copies had already drifted: one refused a `next_from`
+that did not advance and the other accepted it, one checked an effect entry's
+`decision_id` and the other did not — so one broken daemon reply got two
+different answers from two commands of the same commit. The union of both sets
+of checks lives here, and both commands now ask the same question of the same
+shape.
+
+Only what the commands themselves consume before they claim a match, a position
+or an absence is checked. The chain is verified by the contract alone; nothing
+here is a second verifier.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from . import reads
+
+
+class UnreadablePage(ValueError):
+    """An evidence page lacks a member the command that walks it consumes."""
+
+
+def _checked[T](value: object, expected: type[T], member: str) -> T:
+    if not isinstance(value, expected) or (
+        expected is int and (isinstance(value, bool) or value < 1)
+    ):
+        raise UnreadablePage(f"evidence page member {member} is missing or invalid")
+    return value
+
+
+def members(
+    page: Mapping[str, object], from_sequence: int
+) -> tuple[list[Mapping[str, object]], Mapping[str, object], int | None]:
+    """The page's entries, its served verdict and its continuation.
+
+    `next_from` has to be there and it has to advance. A page that answers a
+    read from sequence 5 with `next_from: 5` is not a continuation, and walking
+    it again until a page budget runs out ends in « not found » — an absence
+    stated as a fact the read never established (article 2).
+    """
+    if reads.too_deep(page, reads.PAGE_DEPTH_LIMIT):
+        # One page, bounded two levels shallower than a whole answer, because a
+        # page is carried inside one: `reads.PAGE_DEPTH_LIMIT` says why, and the
+        # subtraction lives there so this file cannot hold a second copy of it.
+        raise UnreadablePage(
+            f"evidence page nests deeper than {reads.PAGE_DEPTH_LIMIT} levels; "
+            "not a page this client reads"
+        )
+    entries = _checked(page.get("entries"), list, "entries")
+    for index, value in enumerate(entries):
+        prefix = f"entries[{index}]"
+        entry = _checked(value, Mapping, prefix)
+        _checked(entry.get("sequence"), int, f"{prefix}.sequence")
+        for name in ("kind", "connection_id", "entry_hash"):
+            _checked(entry.get(name), str, f"{prefix}.{name}")
+        body = _checked(entry.get("body"), Mapping, f"{prefix}.body")
+        if entry["kind"] == "effect":
+            # The member `trace` reads to decide whether an entry is the one it
+            # was asked about: a page that lacks it cannot answer the question.
+            _checked(body.get("decision_id"), str, f"{prefix}.body.decision_id")
+    served = _checked(page.get("verification"), Mapping, "verification")
+    for name, fields in (
+        ("grades", (("connection_id", str), ("grade", str))),
+        ("declared_gaps", (("sequence", int), ("reason", str), ("count", int))),
+    ):
+        items = _checked(served.get(name), list, f"verification.{name}")
+        for index, value in enumerate(items):
+            prefix = f"verification.{name}[{index}]"
+            item = _checked(value, Mapping, prefix)
+            for field, expected in fields:
+                _checked(item.get(field), expected, f"{prefix}.{field}")
+    _checked(served.get("condition"), str, "verification.condition")
+    if served.get("sequence") is not None:
+        _checked(served["sequence"], int, "verification.sequence")
+    if "next_from" not in page:
+        raise UnreadablePage("evidence page member next_from is missing")
+    next_from = page["next_from"]
+    if next_from is not None:
+        _checked(next_from, int, "next_from")
+        if next_from <= from_sequence:
+            raise UnreadablePage("evidence page member next_from does not advance the read")
+    return entries, served, next_from