sediment-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{sediment_cli-0.1.0 → sediment_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sediment-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: The sediment command: login, install, server, facts, exports
 Project-URL: Source, https://github.com/sediment-ai/sediment
 Project-URL: Documentation, https://github.com/sediment-ai/sediment/tree/main/docs
@@ -10,7 +10,7 @@ License-Expression: AGPL-3.0-or-later
 License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.27
-Requires-Dist: sediment-api==0.1.0
-Requires-Dist: sediment-core==0.1.0
-Requires-Dist: sediment-derive==0.1.0
-Requires-Dist: sediment-export==0.1.0
+Requires-Dist: sediment-api==0.2.0
+Requires-Dist: sediment-core==0.2.0
+Requires-Dist: sediment-derive==0.2.0
+Requires-Dist: sediment-export==0.2.0

{sediment_cli-0.1.0 → sediment_cli-0.2.0}/pyproject.toml

@@ -5,7 +5,7 @@
 # Depends on sediment-api deliberately: the operator verbs are DB-local by
 # design (ADR 0001) and `server`/reports/mirror-gc forward into it.
 name = "sediment-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "The sediment command: login, install, server, facts, exports"
 requires-python = ">=3.12"
 license = "AGPL-3.0-or-later"
@@ -14,10 +14,10 @@ license-files = ["LICENSE"]
 # so an install never mixes member versions (the release workflow asserts
 # the versions agree before publishing).
 dependencies = [
-    "sediment-core==0.1.0",
-    "sediment-derive==0.1.0",
-    "sediment-export==0.1.0",
-    "sediment-api==0.1.0",
+    "sediment-core==0.2.0",
+    "sediment-derive==0.2.0",
+    "sediment-export==0.2.0",
+    "sediment-api==0.2.0",
     "httpx>=0.27",
 ]
 

{sediment_cli-0.1.0 → sediment_cli-0.2.0}/sediment_cli/cli.py

@@ -1506,6 +1506,46 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_facts.set_defaults(func=cmd_facts)
 
+    from .evidence import command as evidence_command
+
+    p_evidence = sub.add_parser(
+        "evidence", help="read selected Session evidence with operator authority"
+    )
+    evidence_sub = p_evidence.add_subparsers(
+        dest="evidence_operation",
+        required=True,
+        title="operations",
+        metavar="<operation>",
+        prog=p_evidence.prog,
+    )
+    for operation, help_text in (
+        ("inventory", "print a complete bounded Session inventory as JSON"),
+        ("inspect", "print one Inference call's part manifest as JSON"),
+        ("fetch", "write exact selected parts to a private local packet"),
+    ):
+        command = evidence_sub.add_parser(operation, help=help_text)
+        command.add_argument("session_id", metavar="SESSION", help="source Session ID")
+        if operation == "inspect":
+            command.add_argument(
+                "inference_call_id",
+                metavar="INFERENCE_CALL",
+                help="Inference call Fact ID",
+            )
+        elif operation == "fetch":
+            command.add_argument(
+                "--references",
+                required=True,
+                metavar="PATH",
+                help="version 1 selection JSON (64 KiB; 1–32 distinct references)",
+            )
+            command.add_argument(
+                "--output",
+                required=True,
+                metavar="PATH",
+                help="packet destination (0600; must not exist)",
+            )
+        command.set_defaults(func=evidence_command)
+
     p_demo = sub.add_parser(
         "demo", help="plant one synthetic session so facts is non-zero"
     )
@@ -1795,7 +1835,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 # Remote verbs speak HTTP through the client seam; they never open the fact
 # store and never construct Settings.
-_REMOTE_VERBS = {"login", "logout", "commit", "facts", "demo"}
+_REMOTE_VERBS = {"login", "logout", "commit", "facts", "demo", "evidence"}
 
 # Dispatched pre-argparse to the stdlib-only attribution module.
 # install/uninstall/doctor get help stubs; the hook-plumbing verbs are

{sediment_cli-0.1.0 → sediment_cli-0.2.0}/sediment_cli/client.py

@@ -21,6 +21,7 @@ from typing import Any
 from urllib.parse import urlsplit
 
 import httpx
+from sediment_core import EVIDENCE_REQUEST_BYTES_LIMIT, EVIDENCE_RESPONSE_BYTES_LIMIT
 
 from . import __version__, ui
 
@@ -241,7 +242,7 @@ def probe_me(base_url: str, token: str) -> dict[str, Any]:
         identity = resp.json()
         if (
             not isinstance(identity, dict)
-            or identity.get("authority") not in {"operator", "ingest"}
+            or identity.get("authority") not in {"operator", "ingest", "retrieval"}
             or not isinstance(identity.get("client_id"), str)
             or not identity["client_id"]
             or not isinstance(identity.get("org_id"), str)
@@ -290,6 +291,54 @@ def post_json(path: str, body: Any) -> Any:
     return resp.json()
 
 
+def read_evidence(
+    path: str, *, params: dict[str, str] | None = None, body: bytes | None = None
+) -> bytes:
+    """Read one complete bounded evidence response with operator credentials."""
+    if body is not None and len(body) > EVIDENCE_REQUEST_BYTES_LIMIT:
+        raise ClientError("evidence request exceeds the 64 KiB limit")
+    base_url, token = _resolve()
+    try:
+        with (
+            _http() as http,
+            http.stream(
+                "GET" if body is None else "POST",
+                _url(base_url, path),
+                params=params,
+                content=body,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "Content-Type": "application/json",
+                    "Accept-Encoding": "identity",
+                },
+                timeout=httpx.Timeout(_TIMEOUT_SECONDS, read=40.0),
+            ) as response,
+        ):
+            if response.status_code == 401:
+                raise ClientError("not logged in / token rejected — run sediment login")
+            if response.status_code == 403:
+                raise ClientError(
+                    "operator authority required — run sediment login with an operator token"
+                )
+            if response.status_code != 200:
+                raise ClientError(f"evidence server error ({response.status_code})")
+            if (
+                response.headers.get("Content-Encoding", "identity").lower()
+                != "identity"
+            ):
+                raise ClientError("evidence response must use identity encoding")
+            content = bytearray()
+            for chunk in response.iter_bytes():
+                if len(content) + len(chunk) > EVIDENCE_RESPONSE_BYTES_LIMIT:
+                    raise ClientError("evidence response exceeds the 1 MiB limit")
+                content.extend(chunk)
+            return bytes(content)
+    except httpx.HTTPError:
+        raise ClientError(
+            "evidence request failed; check the server connection"
+        ) from None
+
+
 def current_url() -> str:
     """The resolved server URL, for a verb that has to reason about *which*
     server it is about to write to."""

sediment_cli-0.2.0/sediment_cli/evidence.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Operator-selected evidence reads and private packet publication."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import TypeAdapter
+from sediment_core import (
+    EVIDENCE_INVENTORY_LIMIT,
+    EVIDENCE_REQUEST_BYTES_LIMIT,
+    EvidenceInventory,
+    EvidenceManifest,
+    EvidenceRead,
+    EvidenceReference,
+    EvidenceSchemaVersion,
+    NonEmptyId,
+    validate_evidence_references,
+)
+
+from .client import ClientError, read_evidence
+
+
+def _object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def _finite_float(value):
+    result = float(value)
+    if not math.isfinite(result):
+        raise ValueError("non-finite JSON number")
+    return result
+
+
+def _reject_constant(value):
+    raise ValueError("non-finite JSON number")
+
+
+def _decode(content: bytes):
+    return json.loads(
+        content.decode("utf-8"),
+        object_pairs_hook=_object,
+        parse_float=_finite_float,
+        parse_constant=_reject_constant,
+    )
+
+
+def _selection(path: Path) -> tuple[EvidenceReference, ...]:
+    with path.open("rb") as source:
+        content = source.read(EVIDENCE_REQUEST_BYTES_LIMIT + 1)
+    if len(content) > EVIDENCE_REQUEST_BYTES_LIMIT:
+        raise ClientError("evidence selection exceeds the 64 KiB limit")
+    value = _decode(content)
+    if not isinstance(value, dict) or set(value) != {"schema_version", "references"}:
+        raise ValueError("invalid selection envelope")
+    TypeAdapter(EvidenceSchemaVersion).validate_python(value["schema_version"])
+    references = TypeAdapter(tuple[EvidenceReference, ...]).validate_python(
+        value["references"]
+    )
+    return validate_evidence_references(references)
+
+
+def _unchanged(source, canonical) -> bool:
+    """Reject default-filled or normalized wire data without another part schema."""
+    if isinstance(canonical, datetime):
+        return isinstance(source, str) and datetime.fromisoformat(source) == canonical
+    if isinstance(canonical, dict):
+        return (
+            isinstance(source, dict)
+            and source.keys() == canonical.keys()
+            and all(_unchanged(source[key], value) for key, value in canonical.items())
+        )
+    if isinstance(canonical, (list, tuple)):
+        return (
+            isinstance(source, list)
+            and len(source) == len(canonical)
+            and all(_unchanged(a, b) for a, b in zip(source, canonical, strict=True))
+        )
+    return type(source) is type(canonical) and source == canonical
+
+
+def _response(content: bytes, shape):
+    adapter = TypeAdapter(shape)
+    source = _decode(content)
+    result = adapter.validate_python(source)
+    if not _unchanged(source, adapter.dump_python(result)):
+        raise ValueError("noncanonical evidence response")
+    return result
+
+
+def _inventory(result: EvidenceInventory) -> None:
+    calls = result.calls
+    if (
+        result.visible_inference_calls != len(calls)
+        or len(calls) > EVIDENCE_INVENTORY_LIMIT
+        or len({call.inference_call_id for call in calls}) != len(calls)
+        or (not result.found and (calls or result.quarantined_inference_calls))
+        or tuple(sorted(calls, key=lambda c: (c.observed_at, c.inference_call_id)))
+        != calls
+    ):
+        raise ValueError("inconsistent evidence inventory")
+
+
+def _manifest(result: EvidenceManifest, inference_call_id: NonEmptyId) -> None:
+    if result.call.inference_call_id != inference_call_id:
+        raise ValueError("Inference call mismatch")
+    indices = {"input": 0, "output": 0}
+    for message in result.messages:
+        if message.message_index != indices[message.side] or (
+            message.side == "input" and indices["output"]
+        ):
+            raise ValueError("inconsistent message order")
+        indices[message.side] += 1
+        for index, part in enumerate(message.parts):
+            if part.reference != EvidenceReference(
+                inference_call_id, message.side, message.message_index, index
+            ):
+                raise ValueError("inconsistent part reference")
+
+
+def _publish(destination: Path, content: bytes) -> None:
+    """Hard-link a complete private sibling file without replacing a destination."""
+    fd, name = tempfile.mkstemp(prefix=".sediment-evidence-", dir=destination.parent)
+    temporary = Path(name)
+    try:
+        with os.fdopen(fd, "wb") as output:
+            os.fchmod(output.fileno(), 0o600)
+            output.write(content)
+            output.flush()
+            os.fsync(output.fileno())
+        os.link(temporary, destination)
+    finally:
+        temporary.unlink()
+
+
+def command(args: argparse.Namespace) -> int:
+    """Run a remote evidence operation without opening the FactStore."""
+    try:
+        session_id = TypeAdapter(NonEmptyId).validate_python(args.session_id)
+        params = {"session_id": session_id}
+        if args.evidence_operation == "inventory":
+            content = read_evidence("/query/evidence", params=params)
+            result = _response(content, EvidenceInventory)
+            _inventory(result)
+        elif args.evidence_operation == "inspect":
+            params["inference_call_id"] = TypeAdapter(NonEmptyId).validate_python(
+                args.inference_call_id
+            )
+            content = read_evidence("/query/evidence/manifest", params=params)
+            result = _response(content, EvidenceManifest)
+            _manifest(result, params["inference_call_id"])
+        else:
+            destination = Path(args.output)
+            if os.path.lexists(destination):
+                raise ClientError("evidence output already exists")
+            references = _selection(Path(args.references))
+            body = json.dumps(
+                {
+                    "schema_version": 1,
+                    "session_id": session_id,
+                    "references": TypeAdapter(
+                        tuple[EvidenceReference, ...]
+                    ).dump_python(references),
+                },
+                ensure_ascii=True,
+                allow_nan=False,
+                separators=(",", ":"),
+            ).encode("ascii")
+            content = read_evidence("/query/evidence/read", body=body)
+            result = _response(content, EvidenceRead)
+            if tuple(item.reference for item in result.items) != references:
+                raise ValueError("incomplete selection")
+        if result.session_id != session_id:
+            raise ValueError("Session mismatch")
+        if args.evidence_operation == "fetch":
+            _publish(destination, content)
+            print(f"{destination}: {len(result.items)} items")
+        else:
+            print(content.decode("ascii"))
+        return 0
+    except ClientError:
+        raise
+    except (OSError, ValueError, TypeError, RecursionError):
+        raise ClientError("evidence input, response, or output is invalid") from None

{sediment_cli-0.1.0 → sediment_cli-0.2.0}/tests/test_cli_capture_authority.py

@@ -132,7 +132,7 @@ def test_install_uses_only_proven_ingest_in_shell_fish_and_codex(tmp_path, monke
         assert path.stat().st_mode & 0o777 == 0o600
 
 
-@pytest.mark.parametrize("authority", ["ingest", "operator", None])
+@pytest.mark.parametrize("authority", ["ingest", "operator", "retrieval", None])
 def test_explicit_capture_override_requires_live_ingest_authority(
     tmp_path, monkeypatch, authority
 ):
@@ -281,3 +281,33 @@ def test_doctor_rejects_unreadable_identity_without_reproducing_response(
     attribution._doctor_server(findings)
     assert findings[0][0] == attribution.DOCTOR_FAIL
     assert "private-response" not in str(findings)
+
+
+@pytest.mark.parametrize("capture", [False, True])
+@pytest.mark.parametrize("plural", [False, True])
+def test_retrieval_credential_cannot_enroll_or_replace_operator_login(
+    app_transport, monkeypatch, capsys, capture, plural
+):
+    from pydantic import SecretStr
+    from sediment_api.config import settings
+
+    token = "retrieval-test-token-long-enough"
+    monkeypatch.setattr(settings, "retrieval_token", SecretStr(token))
+    monkeypatch.setattr(
+        settings, "retrieval_session_id", None if plural else "source-session"
+    )
+    monkeypatch.setattr(
+        settings, "retrieval_session_ids", ("source-session",) if plural else None
+    )
+    original = {
+        "current": "https://testserver",
+        "servers": {"https://testserver": {"token": OPERATOR}},
+    }
+    api_client.write_config(original)
+    monkeypatch.setattr(sys, "stdin", io.StringIO(token + "\n"))
+    args = ["login", "https://testserver", "--with-token"]
+    if capture:
+        args.append("--capture")
+    assert cli.main(args) == 1
+    assert "authority required" in capsys.readouterr().err
+    assert api_client.read_config() == original

{sediment_cli-0.1.0 → sediment_cli-0.2.0}/tests/test_cli_db.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 from datetime import UTC, datetime
+import json
 from pathlib import Path
 from uuid import uuid4
 
 from psycopg import sql
-from sqlalchemy import create_engine, text
+from sqlalchemy import MetaData, Table, create_engine, text
 from sqlalchemy.engine import make_url
 
 import pytest
@@ -255,7 +256,7 @@ def test_db_upgrade_permission_failure_exits_nonzero_without_credentials(
 
 
 def _behind_database_url(postgres_database_factory) -> str:
-    """Create a database migrated to 0008 (one revision below head).
+    """Create a database migrated to 0008 (before descriptive-text encoding).
 
     The CLI one-shot quarantine verbs write ``fact_quarantine.reason`` through
     ``_SerializedText``; against a pre-0009 database the 0009 migration would
@@ -377,9 +378,13 @@ def test_preupgrade_facts_preserve_real_counts_and_show_missing_tables(
     engine = create_engine(database_url)
     try:
         store = FactStore(engine)
-        for fact_id in ("visible", "hidden"):
-            store.store_inference_call(
-                InferenceCall(
+        # Seed the historical physical shape, without the current alias writer.
+        with engine.begin() as connection:
+            legacy = MetaData()
+            calls = Table("inference_calls", legacy, autoload_with=connection)
+            sessions = Table("sessions", legacy, autoload_with=connection)
+            for fact_id in ("visible", "hidden"):
+                call = InferenceCall(
                     inference_call_id=fact_id,
                     org_id="testorg",
                     session_id="old-session",
@@ -388,6 +393,17 @@ def test_preupgrade_facts_preserve_real_counts_and_show_missing_tables(
                     output_messages=[],
                     observed_at=datetime(2026, 9, 1, tzinfo=UTC),
                 )
+                values = call.model_dump(mode="python")
+                for name in ("input_messages", "output_messages", "raw"):
+                    values[name] = json.dumps(values[name], ensure_ascii=True)
+                connection.execute(calls.insert().values(**values))
+            connection.execute(
+                sessions.insert().values(
+                    org_id=call.org_id,
+                    session_id=call.session_id,
+                    first_observed_at=call.observed_at,
+                    last_observed_at=call.observed_at,
+                )
             )
         # Seed the pre-0009 representation directly, as the prior writer did.
         with engine.begin() as connection: