mostlyright-data 0.9.5__tar.gz → 0.9.6__tar.gz

{mostlyright_data-0.9.5 → mostlyright_data-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.9.5
+Version: 0.9.6
 Summary: Mostly Right CLI for reproducible, reviewed Parquet datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/
@@ -81,12 +81,11 @@ Description-Content-Type: text/markdown
 
 # mostlyright-data
 
-Mostly Right turns historical and live public data—weather, economic releases, financial reports,
-and satellite data—into consistent datasets for analysis and prediction. Each dataset includes
-source links, timestamps, and check results.
+Browse datasets built by our community or create your own with agents that find the sources and
+configure the pipeline. Mostly Right keeps the dataset live.
 
-`mostlyright-data` is the command-line client. It starts hosted research and build work, follows
-run status, and downloads completed Parquet datasets.
+`mostlyright-data` is the command-line client. It opens hosted research sessions, starts and
+follows hosted dataset runs, and downloads verified datasets after they finish.
 
 ## Requirements
 
@@ -119,20 +118,20 @@ mr-data --help
 Use `mr-data research-open`, `mr-data research-status`, and `mr-data research-close` for hosted
 research sessions. `research-status` shows the current state.
 
-## Local tools
+## Local execution
 
-The optional local tools require Linux:
+The local execution lane runs only on Linux:
 
 ```bash
 python -m pip install "mostlyright-data[local]"
 ```
 
-They build and check worker inputs. They are not required for the hosted client.
+It builds and checks worker inputs. It is not required for the hosted client.
 
 ## Documentation
 
 - [CLI guide](https://mostlyright.md/docs/guides/cli/)
-- [Research sessions](https://mostlyright.md/docs/guides/research/)
+- [Hosted research sessions](https://mostlyright.md/docs/guides/hosted-research/)
 - [Credentials](https://mostlyright.md/docs/guides/credentials/)
 - [Public datasets](https://mostlyright.md/docs/guides/use-public-datasets/)
 
@@ -141,11 +140,11 @@ Use `mr-data --help` for the full command list and options. Commands that suppor
 
 For local builds, `--input-root` and `--output` may use relative paths.
 
-## Limits and behavior
+## Behavior and limits
 
 - `mr-data review --local RUN_DIR` exits 1 when a check fails.
-- The weather Reader accepts one extracted GRIB2 record. It refuses a multi-record GFS or HRRR file.
-- Hosted credential-free acquisition is limited to one single-address public HTTPS object. Bounded collections require both local attestations.
+- The weather reader accepts one extracted GRIB2 record. It refuses a multi-record GFS or HRRR file.
+- Hosted credential-free acquisition supports one single-address public HTTPS object. Bounded collections require both local attestations.
 
 ## Verification
 

{mostlyright_data-0.9.5 → mostlyright_data-0.9.6}/README.md

@@ -1,11 +1,10 @@
 # mostlyright-data
 
-Mostly Right turns historical and live public data—weather, economic releases, financial reports,
-and satellite data—into consistent datasets for analysis and prediction. Each dataset includes
-source links, timestamps, and check results.
+Browse datasets built by our community or create your own with agents that find the sources and
+configure the pipeline. Mostly Right keeps the dataset live.
 
-`mostlyright-data` is the command-line client. It starts hosted research and build work, follows
-run status, and downloads completed Parquet datasets.
+`mostlyright-data` is the command-line client. It opens hosted research sessions, starts and
+follows hosted dataset runs, and downloads verified datasets after they finish.
 
 ## Requirements
 
@@ -38,20 +37,20 @@ mr-data --help
 Use `mr-data research-open`, `mr-data research-status`, and `mr-data research-close` for hosted
 research sessions. `research-status` shows the current state.
 
-## Local tools
+## Local execution
 
-The optional local tools require Linux:
+The local execution lane runs only on Linux:
 
 ```bash
 python -m pip install "mostlyright-data[local]"
 ```
 
-They build and check worker inputs. They are not required for the hosted client.
+It builds and checks worker inputs. It is not required for the hosted client.
 
 ## Documentation
 
 - [CLI guide](https://mostlyright.md/docs/guides/cli/)
-- [Research sessions](https://mostlyright.md/docs/guides/research/)
+- [Hosted research sessions](https://mostlyright.md/docs/guides/hosted-research/)
 - [Credentials](https://mostlyright.md/docs/guides/credentials/)
 - [Public datasets](https://mostlyright.md/docs/guides/use-public-datasets/)
 
@@ -60,11 +59,11 @@ Use `mr-data --help` for the full command list and options. Commands that suppor
 
 For local builds, `--input-root` and `--output` may use relative paths.
 
-## Limits and behavior
+## Behavior and limits
 
 - `mr-data review --local RUN_DIR` exits 1 when a check fails.
-- The weather Reader accepts one extracted GRIB2 record. It refuses a multi-record GFS or HRRR file.
-- Hosted credential-free acquisition is limited to one single-address public HTTPS object. Bounded collections require both local attestations.
+- The weather reader accepts one extracted GRIB2 record. It refuses a multi-record GFS or HRRR file.
+- Hosted credential-free acquisition supports one single-address public HTTPS object. Bounded collections require both local attestations.
 
 ## Verification
 

{mostlyright_data-0.9.5 → mostlyright_data-0.9.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyright-data"
-version = "0.9.5"
+version = "0.9.6"
 description = "Mostly Right CLI for reproducible, reviewed Parquet datasets"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{mostlyright_data-0.9.5 → mostlyright_data-0.9.6}/src/mostlyright/data_harness/cli.py

@@ -96,7 +96,6 @@ from mostlyright.data_harness.offline import (
 )
 from mostlyright.data_harness.pipeline import (
     _VERIFY_ALLOWLISTED_ENGINES,
-    MAX_ROWS,
     SOURCE_PROPOSAL_SET_VERSION,
     BuildError,
     ResourceLimits,
@@ -106,7 +105,10 @@ from mostlyright.data_harness.pipeline import (
     verify_candidate,  # noqa: F401 - retained for compatibility/security-route monkeypatch tests
 )
 from mostlyright.data_harness.plan_graph import (
+    HARD_MAX_INTERMEDIATE_ROWS,
+    HARD_MAX_OUTPUT_ROWS,
     HARD_MAX_RETAINED_BYTES,
+    HARD_MAX_SOURCE_ROWS,
     GraphResourcePolicy,
 )
 from mostlyright.data_harness.readers.contracts import ReaderError
@@ -393,17 +395,44 @@ def _selected_graph_limits(
     max_intermediate_rows: int | None,
     max_retained_bytes: int | None,
 ) -> ResourceLimits | None:
-    """Select only explicitly raised graph dimensions; keep every other row cap at 100k."""
+    """Narrow the trusted graph policy by exactly the dimensions the operator named.
+
+    These flags are a NARROWING instrument and nothing else. The baseline is what a build with no
+    flags at all already runs under -- ``GraphResourcePolicy()``, whose defaults are the engine's
+    own hard ceilings -- so an unnamed dimension keeps that ceiling and a named one lowers only
+    itself. The invariant is worth stating because it is what makes the flags safe to reach for:
+    for every dimension, the policy this returns is at most the no-flag default, and equals it
+    unless the flag naming that dimension was supplied.
+
+    It used to default every row dimension to ``pipeline.MAX_ROWS`` instead. That is the v1 plan's
+    row policy, not the graph engine's, and it is 1/100th of ``HARD_MAX_SOURCE_ROWS``: naming a
+    byte budget alone silently cut a v2 build's row ceiling to 100k, which is the opposite of what
+    an operator raising a budget is asking for. ``build`` only reaches this function for a v2 plan
+    -- a graph flag on a v1 plan is refused as ``GRAPH_POLICY_V1`` before the build starts -- so
+    there is no v1 caller whose 100k cap this could be speaking for.
+
+    ``--graph-max-rows`` sets the source AND output ceilings, as its help says: one number for
+    "how many rows this build may read and release". The intermediate ceiling is separate because
+    the engine's own contract separates them (``HARD_MAX_INTERMEDIATE_ROWS`` is four times
+    ``HARD_MAX_SOURCE_ROWS``, sized for a union of several year-scale sources), so an operator who
+    wants a narrower working set says so with the flag that means it.
+    """
 
     if max_rows is None and max_intermediate_rows is None and max_retained_bytes is None:
         return None
-    selected_rows = max_rows or MAX_ROWS
+    selected_rows = max_rows or HARD_MAX_SOURCE_ROWS
     return ResourceLimits(
+        # The v1 field, carried for a v2 build so `_replay_graph_derivations` streams sources under
+        # the policy rather than under the 100k default. It re-derives the same value from
+        # `graph_policy` anyway; agreeing here keeps the two from reading differently.
         max_rows=selected_rows,
         graph_policy=GraphResourcePolicy(
             max_source_rows=selected_rows,
-            max_intermediate_rows=max_intermediate_rows or selected_rows,
-            max_output_rows=selected_rows,
+            max_intermediate_rows=max_intermediate_rows or HARD_MAX_INTERMEDIATE_ROWS,
+            # `min` because the two ceilings are equal today and are not the same contract: a
+            # source ceiling that ever rose above the output one must not raise the output one
+            # with it.
+            max_output_rows=min(selected_rows, HARD_MAX_OUTPUT_ROWS),
             max_retained_bytes=max_retained_bytes or HARD_MAX_RETAINED_BYTES,
         ),
     )
@@ -1834,22 +1863,29 @@ def _parser(
     build.add_argument("--producer-principal", required=True, help=_BUILT_BY)
     build.add_argument("--producer-attempt", required=True, help=_BUILD_ATTEMPT)
     build.add_argument("--research-dir", type=Path, help="existing visual research directory")
+    # ⚠ THE ARGPARSE MAXIMA ARE THE ENGINE'S OWN HARD CEILINGS, and deliberately not a second,
+    # smaller policy. `GraphResourcePolicy.__post_init__` is the single enforcement point -- it
+    # refuses anything above a ceiling whatever route the value arrived by -- so a smaller number
+    # here would not be a safety property, only a cap the CLI applies and the library does not.
+    # The previous maxima (1M rows, 2M intermediate, 256 MiB retained) were 1/10th, 1/20th and
+    # 1/64th of the ceilings they front, with nothing written down deriving them, and they made
+    # the year-scale capacity the graph engine documents unreachable from the command line.
     build.add_argument(
         "--graph-max-rows",
-        type=_integer_between(1, 1_000_000),
-        metavar="1..1000000",
+        type=_integer_between(1, HARD_MAX_SOURCE_ROWS),
+        metavar=f"1..{HARD_MAX_SOURCE_ROWS}",
         help="trusted graph source/output row ceiling (v2 plans only)",
     )
     build.add_argument(
         "--graph-max-intermediate-rows",
-        type=_integer_between(1, 2_000_000),
+        type=_integer_between(1, HARD_MAX_INTERMEDIATE_ROWS),
         default=None,
-        metavar="1..2000000",
+        metavar=f"1..{HARD_MAX_INTERMEDIATE_ROWS}",
         help="trusted graph intermediate row ceiling",
     )
     build.add_argument(
         "--graph-max-retained-bytes",
-        type=_integer_between(1, 256 * 1024 * 1024),
+        type=_integer_between(1, HARD_MAX_RETAINED_BYTES),
         default=None,
         metavar="BYTES",
         help="trusted graph retained-byte ceiling",

{mostlyright_data-0.9.5 → mostlyright_data-0.9.6}/src/mostlyright/data_harness/hosted_session_worker.py

@@ -233,6 +233,50 @@ MAX_SESSION_CAPABILITY_REMAINING_SECONDS = 30 * 60
 #: parent-side parser a fixed-memory boundary if a child is compromised.
 MAX_SESSION_SUPERVISOR_MESSAGE_BYTES = 128 * 1024
 
+# **THE SESSION'S OWN PROGRESS BUDGET, and why it is not the producer's.**
+#
+# ``progress_events.MAX_PROGRESS_EVENTS_PER_ATTEMPT = 512`` bounds a stream whose shape a RECIPE
+# fixes: one record per source, per artifact and per stage. A correct producer cannot approach it,
+# so reaching it means a caller is looping -- which is exactly what that paragraph says, and none
+# of it is edited here.
+#
+# A session has no such shape. Its stream is TWO records per probe (`source_probe_started` and
+# `source_probe_settled`) over a conversation whose length nobody knows when it opens, so the
+# producer's number bought 255 probes and then went dark -- silently, and taking `attempt_finished`
+# with it, which left every watcher holding a start that never ends (#334). Both halves of that are
+# fixed below: the budget is derived from what actually bounds a session, and the terminal record
+# is not spendable by probe traffic.
+#
+# The derivation. ``MAX_SESSION_CAPABILITY_REMAINING_SECONDS`` is the hard ceiling on how long a
+# session may run at all, and the interactive follow-up budget a warm sandbox pool exists to meet
+# is 100 ms at its fastest (see ``DEFAULT_WARM_POOL_SIZE``). Half an hour of back-to-back probes at
+# that floor is the most probes a session can physically raise; a session that emits more records
+# than that is looping, and costs Studio nothing when it does.
+MIN_PROBE_ROUND_TRIP_SECONDS = 0.1
+MAX_SESSION_PROBES = int(MAX_SESSION_CAPABILITY_REMAINING_SECONDS / MIN_PROBE_ROUND_TRIP_SECONDS)
+#: Never spent by probe traffic: the terminal `attempt_finished` a watcher pairs with
+#: `attempt_started`, and the one `attempt_failed` diagnostic that reports how many records the
+#: budget dropped. Reserving them is what makes "the stream always ends, and says why it thinned"
+#: a property of the emitter rather than of the session being short enough.
+RESERVED_SESSION_PROGRESS_EVENTS = 2
+#: Two records per probe, plus the opening `attempt_started`, plus the two reserved above.
+MAX_SESSION_PROGRESS_EVENTS_PER_ATTEMPT = (
+    2 * MAX_SESSION_PROBES + 1 + RESERVED_SESSION_PROGRESS_EVENTS
+)
+#: The names the reserved slots are for. Both are terminal narration and neither is emitted by the
+#: probe loop, so no amount of probe traffic can consume the slot the other one needs.
+TERMINAL_SESSION_PROGRESS_EVENTS = frozenset({"attempt_finished", "attempt_failed"})
+#: THE PAIR, which the budget spends as one thing. A watcher's whole use for this stream is that a
+#: start it sees will be followed by an end -- `_answer_probe` already emits both halves under one
+#: condition for that reason -- so a budget that could admit a start and then refuse its settlement
+#: would reintroduce the dangling start by the back door. A start therefore costs TWO slots, its own
+#: and the settlement it promises, and a settlement whose start was admitted is never refused.
+PROBE_PROGRESS_STARTED = "source_probe_started"
+PROBE_PROGRESS_SETTLED = "source_probe_settled"
+#: The code the disarm diagnostic settles under. A token, because it reaches a timeline as a
+#: progress fact and `progress_events` drops a record whose fact is prose.
+PROGRESS_BUDGET_EXHAUSTED_CODE = "SESSION_PROGRESS_BUDGET_EXHAUSTED"
+
 _UTC_TIMESTAMP = re.compile(
     r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,6})?Z$"
 )
@@ -1407,7 +1451,9 @@ class StudioSessionAcquisitionReader:
             filename=filename,
             # The bytes are whole or they are refused. Studio clamps the source to the session
             # ceiling before it crawls, and a truncated table would make every count a probe
-            # reports quietly wrong, so there is no partial answer to flag here.
+            # reports quietly wrong, so there is no partial answer to flag here. This is the
+            # STARTING value of the probe envelope's `truncated`, not the whole of it: an answer
+            # that drops columns or rows of its own raises the flag where it drops them.
             truncated=False,
             origin="studio.session-acquisition",
         )
@@ -1540,6 +1586,12 @@ class ProbeExecutor:
             "content_bytes": len(source.content),
             "data_format": parsed.data_format,
             "sandbox_policy_digest": result.policy_digest,
+            # The parse's own width, before any answer narrows it. Set here rather than in each
+            # per-kind answer so it is the SOURCE's number in every one of them, and so an answer
+            # that returns fewer columns has its denominator beside it rather than nowhere.
+            "column_count": len(parsed.columns),
+            # The source's own flag is the starting value and not the final one: the per-kind
+            # answers below raise it when they drop columns or rows of their own.
             "truncated": bool(source.truncated),
         }
         body = self._answer(probe_kind, normalized, parsed, envelope)
@@ -1576,6 +1628,12 @@ class ProbeExecutor:
         # Deliberately no cell values. `source_inspect` answers "what shape is this", and a client
         # that wants values asks `sample_rows` -- which is a separate probe, separately visible on
         # the session's event stream, so "who looked at the data" stays answerable.
+        described = columns[: session_probes.MAX_PROFILE_COLUMNS]
+        # The probe whose ONE job is to report a source's shape must not misreport it. A source
+        # wider than `MAX_PROFILE_COLUMNS` is still answered -- the first 256 columns are the useful
+        # answer -- but `truncated` says the list is a prefix and `column_count` says of what.
+        if len(described) < len(columns):
+            envelope["truncated"] = True
         return {
             **envelope,
             "schema_digest": parsed.schema_digest,
@@ -1584,7 +1642,7 @@ class ProbeExecutor:
                     "name": name,
                     "inferred_type": session_probes.inferred_type([row[index] for row in scanned]),
                 }
-                for index, name in enumerate(columns[: session_probes.MAX_PROFILE_COLUMNS])
+                for index, name in enumerate(described)
             ],
         }
 
@@ -1595,7 +1653,9 @@ class ProbeExecutor:
         rows: Sequence[Sequence[Any]],
         envelope: dict[str, Any],
     ) -> dict[str, Any]:
-        selected = self._selected_columns(request, columns)
+        selected, columns_dropped = self._selected_columns(request, columns)
+        if columns_dropped:
+            envelope["truncated"] = True
         indices = [columns.index(name) for name in selected]
         window = rows[request["offset"] : request["offset"] + request["limit"]]
         envelope["rows_scanned"] = request["offset"] + len(window)
@@ -1617,9 +1677,10 @@ class ProbeExecutor:
         # monotone predicate, and the search returns the same maximal prefix the popping loop
         # walked down to. Two details of the old loop are semantics rather than mechanics, and are
         # preserved exactly: a body that fits whole is returned with `truncated` UNTOUCHED (the
-        # envelope's own value, from the source), and the flag is set BEFORE the fitting is
-        # measured, because `true` and `false` are not the same width and the byte count has to be
-        # the one the answer will actually be sent as.
+        # envelope's own value -- the source's flag, and now also the projection's, raised above
+        # when it dropped columns), and the flag is set BEFORE the fitting is measured, because
+        # `true` and `false` are not the same width and the byte count has to be the one the answer
+        # will actually be sent as.
         rows = body["rows"]
         if not rows or len(canonical_json_bytes(body)) <= session_probes.PROBE_RESULT_MAX_BYTES:
             return body
@@ -1642,7 +1703,9 @@ class ProbeExecutor:
         scanned: Sequence[Sequence[Any]],
         envelope: dict[str, Any],
     ) -> dict[str, Any]:
-        selected = self._selected_columns(request, columns)
+        selected, columns_dropped = self._selected_columns(request, columns)
+        if columns_dropped:
+            envelope["truncated"] = True
         profiles: list[dict[str, Any]] = []
         for name in selected:
             index = columns.index(name)
@@ -1733,16 +1796,27 @@ class ProbeExecutor:
 
     def _selected_columns(
         self, request: Mapping[str, Any], columns: Sequence[str]
-    ) -> tuple[str, ...]:
+    ) -> tuple[tuple[str, ...], bool]:
+        """Return the projection and whether choosing it DROPPED columns from the source.
+
+        A caller who names columns gets exactly those and nothing was dropped: that is a
+        projection, and reporting it as truncation would make `truncated` mean "you did not ask
+        for every column", which is true of almost every probe and tells nobody anything. A caller
+        who names none is offered the source's columns and gets at most `MAX_PROFILE_COLUMNS` of
+        them -- and that IS a drop, because the answer is a prefix of what was offered and used to
+        say `truncated: false` while being one.
+        """
+
         requested = request.get("columns")
         if requested is None:
-            return tuple(columns[: session_probes.MAX_PROFILE_COLUMNS])
+            selected = tuple(columns[: session_probes.MAX_PROFILE_COLUMNS])
+            return selected, len(selected) < len(columns)
         unknown = [name for name in requested if name not in columns]
         if unknown:
             raise SessionWorkerError(
                 "PROBE_COLUMN_UNKNOWN", f"source has no column named {unknown[0]!r}"
             )
-        return tuple(requested)
+        return tuple(requested), False
 
 
 def _probe_failure_code(error: BaseException) -> str:
@@ -2648,11 +2722,7 @@ class SessionSupervisor:
             self._claim_loop(authority, models, lease, executor, progress, deadline)
         finally:
             self._stop.set()
-            progress.emit(
-                "attempt_finished",
-                {"outcome": self.outcome.terminal_state or "stopped"},
-            )
-            progress.close()
+            progress.finish(self.outcome.terminal_state or "stopped")
             try:
                 sandbox.close_warm_pool()
             except Exception:
@@ -2947,6 +3017,13 @@ class _SessionProgress:
     append was refused has lost the thing it exists for. Records go out one at a time rather than
     batched, because a session's whole product claim is that a probe is visible immediately, and a
     250 ms coalescing window is a quarter of the follow-up budget.
+
+    THE BUDGET IS THE SESSION'S OWN (``MAX_SESSION_PROGRESS_EVENTS_PER_ATTEMPT``), and running out
+    of it thins the stream rather than ending it: ordinary records past the budget are counted and
+    dropped, the probe pair is dropped whole rather than half, and the two reserved slots still
+    carry the terminal `attempt_finished` and one `attempt_failed` diagnostic naming the exact
+    number dropped. Silently disarming the whole sink at the producer's 512 was the shape this
+    replaces, and it took the terminal record with it. See :meth:`_claim_budget`.
     """
 
     def __init__(
@@ -2965,21 +3042,61 @@ class _SessionProgress:
         self._batch = 0
         self._pending: list[Any] = []
         self._armed = True
+        self._dropped = 0
+        self._unsettled_starts = 0
 
     @property
     def armed(self) -> bool:
         return self._armed
 
+    @property
+    def dropped(self) -> int:
+        """How many records the budget refused. Reported on the timeline by :meth:`finish`."""
+
+        return self._dropped
+
+    def _claim_budget(self, name: str) -> bool:
+        """Decide whether one record fits, SPENDING its slots when it does.
+
+        Three rules, in the order they are read:
+
+        * Terminal narration draws on the whole budget, so a probe loop can never spend the record
+          that ends the stream or the one that explains why it thinned.
+        * A settlement whose start was admitted is never refused. The pair is what a watcher reads
+          this stream for; a start with no end is indistinguishable from a probe still running,
+          forever, which is precisely the failure the budget must not reintroduce.
+        * Everything else stops short of the reserved slots -- and a probe START costs two of them,
+          its own and the settlement it has just promised, so the pair is admitted whole or not at
+          all.
+        """
+
+        if name in TERMINAL_SESSION_PROGRESS_EVENTS:
+            return self._sequence < MAX_SESSION_PROGRESS_EVENTS_PER_ATTEMPT
+        if name == PROBE_PROGRESS_SETTLED:
+            if self._unsettled_starts <= 0:
+                return False
+            self._unsettled_starts -= 1
+            return True
+        ordinary = MAX_SESSION_PROGRESS_EVENTS_PER_ATTEMPT - RESERVED_SESSION_PROGRESS_EVENTS
+        cost = 2 if name == PROBE_PROGRESS_STARTED else 1
+        if self._sequence + cost > ordinary:
+            return False
+        if name == PROBE_PROGRESS_STARTED:
+            self._unsettled_starts += 1
+        return True
+
     def emit(self, name: str, facts: Mapping[str, Any]) -> None:
         if self._deadline is not None and self._deadline.expired():
+            # A different reason from the budget, and it really is a disarm: the lease is gone, so
+            # an append would be refused rather than merely unwanted, and there is no terminal
+            # record left to reserve a slot for.
             self._armed = False
             self._pending.clear()
             return
         if not self._armed:
             return
-        if self._sequence >= progress_events.MAX_PROGRESS_EVENTS_PER_ATTEMPT:
-            self._armed = False
-            self._pending.clear()
+        if not self._claim_budget(name):
+            self._dropped += 1
             return
         try:
             self._sequence += 1
@@ -3035,6 +3152,34 @@ class _SessionProgress:
         except Exception:
             LOGGER.debug("session progress append failed", exc_info=True)
 
+    def finish(self, outcome: str) -> None:
+        """Spend the reserved slots, in the one order that reads correctly, and close.
+
+        The drop diagnostic goes out BEFORE `attempt_finished` so the terminal record stays the
+        last thing on the timeline, and it is emitted here rather than at the moment the budget ran
+        out because only here is the number final: a diagnostic sent on the first refusal could
+        only have said "one".
+
+        It travels as `attempt_failed` -> `diagnostic_emitted`, which is the vocabulary's narration
+        ABOUT a failure and not a claim that the session failed -- the session's own outcome is the
+        `attempt_finished` record immediately after it, unchanged.
+        """
+
+        if self._dropped:
+            self.emit(
+                "attempt_failed",
+                {
+                    "code": PROGRESS_BUDGET_EXHAUSTED_CODE,
+                    "detail": (
+                        f"{self._dropped} progress records were dropped after this session "
+                        f"reached its budget of {MAX_SESSION_PROGRESS_EVENTS_PER_ATTEMPT} "
+                        "records; every probe was still answered and reported"
+                    ),
+                },
+            )
+        self.emit("attempt_finished", {"outcome": outcome})
+        self.close()
+
     def close(self) -> None:
         try:
             self.flush()