mostlyright-data 0.14.0__tar.gz → 0.14.2__tar.gz

{mostlyright_data-0.14.0 → mostlyright_data-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.14.0
+Version: 0.14.2
 Summary: Mostly Right CLI for reproducible, reviewed Parquet datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/

{mostlyright_data-0.14.0 → mostlyright_data-0.14.2}/pyproject.toml

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

{mostlyright_data-0.14.0 → mostlyright_data-0.14.2}/skills/mr-data-build/SKILL.md

@@ -131,10 +131,10 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data open` | Mint a single-use, short-lived address that continues this session in a browser at one dashboard path, and print it. `--open` hands it to the platform opener. The credential decides who mints: a device credential — what `mr-data login` stores — mints at Cloud, and a personal access token mints at Studio. |
 | `mr-data promote` | Ask Studio to publish one table after a person's decision. The Harness worker does not perform the catch-up or scheduled refresh; report those only when another deployed component returns durable evidence that it did. |
 | `mr-data reschedule` | Change how often one live table refreshes, without the demote and promote that would reset its bookkeeping and buy a catch-up run. `--cadence` takes a cron expression or an interval such as `every 6h`; `--why` records the reasoning. It starts no run. `--lock` freezes the schedule so Studio stops adjusting it; `--unlock` lets it follow the source again. |
-| `mr-data table` | Report what one table is serving and how its refresh schedule is going: the state in plain words, the schedule in force, the next refresh, the schedule that was asked for and the reason given for it, and — once Studio has settled on one — the interval it measured and how many source updates that rests on. `table rename TABLE --name NAME` writes a new name, lowercase snake_case and unique within its dataset, fenced on that dataset's version and retried once if somebody else wrote first; nothing is rebuilt, because every run, version and schedule hangs off the identifier, which does not move. `table archive TABLE --confirm-name NAME` retires the table and frees its name; a live table is refused until you `demote` it, and nothing built is deleted. |
+| `mr-data table` | Report what one table is serving and how its refresh schedule is going: the state in plain words, the schedule in force, the next refresh, the schedule that was asked for and the reason given for it, and — once Studio has settled on one — the interval it measured and how many source updates that rests on. `table rename TABLE --name NAME` writes a new name, lowercase snake_case and unique within its dataset, fenced on that dataset's version and retried once if somebody else wrote first; nothing is rebuilt, because every run, version and schedule hangs off the identifier, which does not move. `table archive TABLE --confirm-name NAME` retires one table you name by the name it is called, and frees that name; a live table is refused until you `demote` it, and nothing built is deleted. `table archive TABLE [TABLE ...] --confirm DELETE` retires as many tables as you name at once: `DELETE` is the literal word, typed exactly, and it confirms the identifiers you typed rather than a name, so each table is retired under the name Studio is holding for it. Every table is attempted whatever the one before it answered, one line is printed for each, and the command exits non-zero if any was not retired — so read the outcome of each rather than the exit code alone. `--confirm-name` is refused when you name more than one table. |
 | `mr-data pin` | Ask Studio to freeze one table pointer on an exact version, for a rollback or a hold. |
 | `mr-data unpin` | Ask Studio to resume pointer tracking; read the returned state before claiming it resumed. |
-| `mr-data demote` | Ask Studio to withdraw the pointer and any schedule it owns. |
+| `mr-data demote` | Ask Studio to withdraw the pointer and any schedule it owns, for one table or for as many as you name: `demote TABLE [TABLE ...]` withdraws them one after another, attempts every one of them whatever the one before it answered, prints a line for each, and exits non-zero if any is still live. Pair it with `table archive` when you are retiring a set: a live table cannot be archived, so it is withdraw-then-archive, two commands rather than a loop. |
 
 `auth`, `login`, `whoami` and `clarify` are the same implementation in both profiles, and
 `clarify` alone reaches nothing at all. The other twenty-four answer from Studio. Eight only
@@ -525,6 +525,24 @@ which Studio fixes. Do it once per dataset, silently, and do not repeat it for a
 subject changed. A dataset presented without a cover is a defect, the same as a one-line
 description.
 
+### Say what each source is
+
+Every entry in `sources` takes an optional `description`, and every one you write gets one. It is
+a single sentence saying what that source **is** — `Daily climatological reports, the official
+highs and lows.` — and the dataset page draws it beside the endpoint, under the publisher it came
+from. That line is the only place a reader ever learns what a URL full of query parameters
+actually returned, so it is written for somebody who has never seen the recipe.
+
+Write it about the DATA, never about the run: `Hourly airport surface observations` and not `the
+2024 half of the window`, `fetched as CSV` or `unioned in step one`. Do not restate the address in
+words, and do not repeat the publisher's product code where it says nothing a reader can use. Up
+to 240 characters, which is one sentence rather than two. Where one window is split across several
+sources on the same endpoint, all of them describe the same thing and get the same sentence — the
+years are already in their names.
+
+Leaving it out is a defect in the same way a one-line dataset description is: the source is then
+drawn with its endpoint alone, and a reader is left to guess from a query string.
+
 ### Say what each column shows
 
 Decide, per column, what a reader should see, and write it on the column as `presentation`. This is
@@ -1241,6 +1259,17 @@ or a hold, `mr-data unpin TABLE_ID` resumes tracking, and `mr-data demote TABLE_
 schedule and withdraws the live pointer. Read the resulting table state, but do not infer a
 schedule, catch-up, or current bytes from the command name or from route acceptance.
 
+To retire several tables, do it in two commands rather than a loop: `mr-data demote TABLE_ID
+TABLE_ID ...` withdraws them, then `mr-data table archive TABLE_ID TABLE_ID ... --confirm DELETE`
+retires them. `DELETE` is the literal word and nothing else is accepted; it confirms the
+identifiers you typed, and each table is then retired under the name Studio is holding for it, so
+you do not have to look any name up. Neither command stops at the first refusal: both attempt every
+table, print one outcome line for each, and exit non-zero if any did not move. Read the per-table
+outcomes — `--json` carries them as an array with counts beside it — and report what happened to
+each table rather than what the exit code said about the set. A table that is live is refused by
+`archive` until it is withdrawn, and a table a run is still writing to is refused by both until the
+run has finished; neither refusal deletes anything, and neither ends the command.
+
 ## Autonomous delivery
 
 Own the run until the requested outcome is delivered: a run that succeeded, its declared checks

{mostlyright_data-0.14.0 → mostlyright_data-0.14.2}/src/mostlyright/data_harness/hosted_stream_subscription_worker.py

@@ -17,6 +17,7 @@ its own.
 from __future__ import annotations
 
 import asyncio
+import logging
 import os
 import shutil
 import stat
@@ -281,15 +282,7 @@ def _materialized_claim_connector(
     root = Path(tempfile.mkdtemp(prefix="stream-subscription-feed-", dir=work_root))
     try:
         os.chmod(root, 0o700)
-        registry_root = root / "registry"
-        registry_root.mkdir(mode=0o700)
-        materialize_connector_registry(
-            transport=objects,
-            bucket=_claim_text(claim.stream_venue_bucket, "stream venue bucket"),
-            registry_prefix=_claim_text(claim.connector_registry_prefix, "registry prefix"),
-            registry_digest=_claim_text(claim.connector_registry_digest, "registry digest"),
-            root=registry_root,
-        )
+        registry_root = _materialized_registry_root(claim, objects, root)
         registry = load_stream_connector_registry(registry_root)
         entry = registry.resolve(
             _claim_text(claim.connector_id, "connector id"),
@@ -314,6 +307,33 @@ def _materialized_claim_connector(
         shutil.rmtree(root, ignore_errors=True)
 
 
+def _materialized_registry_root(
+    claim: ClaimedSubscription, objects: GCSObjectTransport, root: Path
+) -> Path:
+    """Materialize the pinned registry under ``root`` and file its series documents.
+
+    ONE MATERIALIZATION SHAPE FOR BOTH LOADERS.  A published registry is one flat name-to-digest
+    table; the connector loader reads the documents directly beneath the root and the series
+    loader reads the ``series`` directory under it.  A subscription that follows a series is
+    pinned to a registry that carries both kinds by construction, so a root left unsorted is not
+    a connector registry at all and the feed is refused before it opens.
+    """
+
+    registry_root = root / "registry"
+    registry_root.mkdir(mode=0o700)
+    series_root = registry_root / SERIES_DIRECTORY_NAME
+    series_root.mkdir(mode=0o700)
+    materialize_connector_registry(
+        transport=objects,
+        bucket=_claim_text(claim.stream_venue_bucket, "stream venue bucket"),
+        registry_prefix=_claim_text(claim.connector_registry_prefix, "registry prefix"),
+        registry_digest=_claim_text(claim.connector_registry_digest, "registry digest"),
+        root=registry_root,
+    )
+    _sort_series_documents(registry_root, series_root)
+    return registry_root
+
+
 def _claim_text(value: str | None, label: str) -> str:
     if not isinstance(value, str) or not value:
         raise StreamSubscriptionError("STREAM_SUBSCRIPTION_CONNECTOR_INVALID", label)
@@ -385,18 +405,7 @@ def _materialized_claim_series(
     root = Path(tempfile.mkdtemp(prefix="stream-subscription-series-", dir=work_root))
     try:
         os.chmod(root, 0o700)
-        registry_root = root / "registry"
-        registry_root.mkdir(mode=0o700)
-        series_root = registry_root / SERIES_DIRECTORY_NAME
-        series_root.mkdir(mode=0o700)
-        materialize_connector_registry(
-            transport=objects,
-            bucket=_claim_text(claim.stream_venue_bucket, "stream venue bucket"),
-            registry_prefix=_claim_text(claim.connector_registry_prefix, "registry prefix"),
-            registry_digest=_claim_text(claim.connector_registry_digest, "registry digest"),
-            root=registry_root,
-        )
-        _sort_series_documents(registry_root, series_root)
+        registry_root = _materialized_registry_root(claim, objects, root)
         documents = load_stream_series_documents(registry_root)
         held = documents.get(series.series_id)
         if held is None:
@@ -625,6 +634,7 @@ async def run_subscription_worker(
 def stream_subscription_worker_main(argv: Sequence[str] | None = None) -> int:
     """Cloud Run Worker Pool executable; it intentionally accepts no mutable CLI authority."""
 
+    _configure_worker_logging()
     arguments = tuple(sys.argv[1:] if argv is None else argv)
     if arguments:
         raise HostedStreamSubscriptionWorkerError(
@@ -636,6 +646,25 @@ def stream_subscription_worker_main(argv: Sequence[str] | None = None) -> int:
     return 0
 
 
+def _configure_worker_logging() -> None:
+    """Configure the root logger for the pool executable, on a stream its host collects.
+
+    A library module configures nothing; an executable must.  Unconfigured, this process fell
+    through to the last-resort handler, which emits a bare message with no level and no logger
+    name, so the pool's own refusals arrived unattributable.
+
+    Plain text on either stream is collected at DEFAULT severity, so the level is carried in the
+    line rather than in the record -- which is why the format names it.  Stdout is chosen over the
+    sibling executables' stderr for the same reason it is chosen anywhere: a stream that carries
+    ordinary progress as well as refusals is not the error stream.  An already-configured root is
+    left alone, which is what lets a smoke or a test harness own it instead.
+    """
+
+    logging.basicConfig(
+        level=logging.INFO, stream=sys.stdout, format="%(levelname)s %(name)s %(message)s"
+    )
+
+
 def _studio_origin(value: str | None) -> str:
     if not isinstance(value, str) or not 1 <= len(value) <= 2048 or value.endswith("/"):
         raise HostedStreamSubscriptionWorkerError(

{mostlyright_data-0.14.0 → mostlyright_data-0.14.2}/src/mostlyright/data_harness/stream_subscription_sealer.py

@@ -27,6 +27,7 @@ from mostlyright.data_harness.canonical import (
     parse_json,
     sha256_bytes,
 )
+from mostlyright.data_harness.hosted_stream_recorder_job import _sort_series_documents
 from mostlyright.data_harness.ingestion.gcs_store import (
     GCSObjectTransport,
     GCSPreconditionFailed,
@@ -40,6 +41,7 @@ from mostlyright.data_harness.sources.stream_registry import (
     load_stream_connector_registry,
 )
 from mostlyright.data_harness.sources.stream_segment_recorder import StreamSegmentRecorder
+from mostlyright.data_harness.sources.stream_series import SERIES_DIRECTORY_NAME
 from mostlyright.data_harness.stream_subscription_worker import (
     MAX_DISCOVERY_EVIDENCE_BYTES,
     CheckpointReservation,
@@ -435,6 +437,18 @@ def _materialize_registry(
         registry_digest=_required_claim_value(claim.connector_registry_digest, "registry digest"),
         root=registry_root,
     )
+    # THE REGISTRY A SERIES SUBSCRIPTION PINS HOLDS TWO GRAMMARS. A published registry is one
+    # flat name-to-digest table, and a subscription that follows a series pins a registry that
+    # carries the series document beside the connector it rotates. The connector loader reads
+    # every document directly beneath the root and refuses one written in the series grammar,
+    # so the series documents are filed under the series directory first -- exactly as the
+    # claim path (`hosted_stream_subscription_worker._materialized_claim_connector`) and the
+    # bounded recorder job already do. Without this, sealing died on the first checkpoint of
+    # every series-following subscription with STREAM_CONNECTOR_DOCUMENT, the lease was lost
+    # before any segment landed, and the subscription terminalized after five lost leases.
+    series_root = root / SERIES_DIRECTORY_NAME
+    series_root.mkdir(mode=0o700, exist_ok=True)
+    _sort_series_documents(root, series_root)
     return load_stream_connector_registry(root)
 
 

{mostlyright_data-0.14.0 → mostlyright_data-0.14.2}/src/mostlyright/data_harness/stream_subscription_worker.py

@@ -132,6 +132,22 @@ class _SubscriptionCancelled(RuntimeError):
         self.desired_state = desired_state
 
 
+#: The largest ``volume_policy.max_bytes`` any worker in this pool can serve.
+#:
+#: A hot subscription gets two bounded buffers: one immutable segment may be sealing while its
+#: successor is being read.  Each is capped at half the per-claim budget so the queue does not
+#: turn a 16 MiB promise into 32 MiB during a slow upload/CAS.
+#:
+#: It is exported because it is a PROTOCOL CONSTANT, not a private detail: the control plane
+#: writes the policy a subscription starts with, so it needs the number to validate against at
+#: start rather than discovering it one lease at a time.
+MAX_VOLUME_POLICY_BYTES = MAX_BUFFERED_BYTES // 2
+
+#: The largest ``volume_policy.max_duration_seconds`` any worker in this pool can serve, equal to
+#: the longest a subscription may sit without data before its lease ends on its own.
+MAX_VOLUME_POLICY_DURATION_SECONDS = DEFAULT_NO_DATA_TIMEOUT_SECONDS
+
+
 @dataclass(frozen=True)
 class VolumePolicy:
     """One subscription's bounded rotation policy, set by Studio rather than a worker flag."""
@@ -140,17 +156,21 @@ class VolumePolicy:
     max_duration_seconds: int
 
     def __post_init__(self) -> None:
-        if (
-            isinstance(self.max_bytes, bool)
-            or isinstance(self.max_duration_seconds, bool)
-            # A hot subscription gets two bounded buffers: one immutable segment may be sealing
-            # while its successor is being read.  Cap each at half the per-claim budget so the
-            # queue does not turn a 16 MiB promise into 32 MiB during a slow upload/CAS.
-            or not 1 <= self.max_bytes <= MAX_BUFFERED_BYTES // 2
-            or not 1 <= self.max_duration_seconds <= DEFAULT_NO_DATA_TIMEOUT_SECONDS
+        # The refusal names the bound and the offered value, because the party that has to change
+        # the policy is the one that wrote it and it cannot act on "outside worker bounds".
+        if isinstance(self.max_bytes, bool) or not 1 <= self.max_bytes <= MAX_VOLUME_POLICY_BYTES:
+            raise StreamSubscriptionError(
+                "STREAM_SUBSCRIPTION_POLICY_INVALID",
+                f"volume policy max_bytes {self.max_bytes} is outside the worker bound "
+                f"1..{MAX_VOLUME_POLICY_BYTES}",
+            )
+        if isinstance(self.max_duration_seconds, bool) or not (
+            1 <= self.max_duration_seconds <= MAX_VOLUME_POLICY_DURATION_SECONDS
         ):
             raise StreamSubscriptionError(
-                "STREAM_SUBSCRIPTION_POLICY_INVALID", "volume policy is outside worker bounds"
+                "STREAM_SUBSCRIPTION_POLICY_INVALID",
+                f"volume policy max_duration_seconds {self.max_duration_seconds} is outside the "
+                f"worker bound 1..{MAX_VOLUME_POLICY_DURATION_SECONDS}",
             )
 
 
@@ -862,9 +882,12 @@ class RecoveryArtifact:
             )
 
     def to_dict(self) -> dict[str, object]:
+        # An object generation is a decimal STRING on the wire, the spelling the control plane's
+        # recovery-artifact schema contracts for.  It stays an int in the dataclass because that
+        # is what compares and orders; only the serialized form is text.
         return {
             "object_name": self.object_name,
-            "generation": self.generation,
+            "generation": str(self.generation),
             "sha256": self.sha256,
             "byte_length": self.byte_length,
             "media_type": self.media_type,
@@ -2083,6 +2106,8 @@ __all__ = [
     "MAX_DISCOVERY_EVIDENCE_BYTES",
     "MAX_ROSTER_MEMBERS",
     "MAX_SEGMENT_GAPS",
+    "MAX_VOLUME_POLICY_BYTES",
+    "MAX_VOLUME_POLICY_DURATION_SECONDS",
     "ROSTER_TICK_SECONDS",
     "ROTATION_SCHEMA_VERSION",
     "SEGMENT_ROTATION_SCHEMA_VERSION",

{mostlyright_data-0.14.0 → mostlyright_data-0.14.2}/src/mostlyright/data_harness/studio_subscription_control.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import logging
+import re
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass, replace
 from typing import Any
@@ -37,7 +39,15 @@ from mostlyright.data_harness.stream_subscription_worker import (
 )
 from mostlyright.data_harness.stream_venue_staging import MAX_EVIDENCE_BYTES
 
+LOGGER = logging.getLogger(__name__)
+
 CLAIM_PATH = "/_internal/stream-subscriptions:claim"
+
+#: The largest object generation either spelling may carry, from the control plane's own
+#: nineteen-digit delivery grammar.  A generation is a storage coordinate, not arithmetic, so a
+#: number outside the grammar is a claim about an object no bucket issued.
+MAX_OBJECT_GENERATION = 10**19 - 1
+_OBJECT_GENERATION_TEXT = re.compile(r"[1-9][0-9]{0,18}")
 CREDENTIAL_RESOLUTION_SCHEMA_VERSION = "mostlyright-stream-subscription-credential-resolution.v1"
 _STAGING_ROLES = ("source_data", "acquisition_receipt", "source_observation")
 _STAGING_MEDIA_TYPES = {
@@ -72,6 +82,18 @@ class StudioSubscriptionControl:
             # The number was already parsed and checked here before it was carried; the only
             # change is that it now reaches the caller instead of being validated and dropped.
             return IdlePoll(poll_after_seconds=_integer(value, "poll_after_seconds", 1))
+        try:
+            return self._claimed(value)
+        except StreamSubscriptionError as error:
+            # A LEASE THIS WORKER CANNOT SERVE IS STILL A LEASE. Studio persists the lease before
+            # it answers, so a refusal that only raised would leave that lease to expire and be
+            # handed back on the next claim, forever, with nothing on the record saying why.
+            self._dispose_of_refused_claim(value, error)
+            raise
+
+    def _claimed(self, value: Mapping[str, Any]) -> ClaimedSubscription:
+        """The full claim, or a refusal naming the first member this worker cannot serve."""
+
         policy = _mapping(value, "volume_policy")
         claim_series = _series_claim(value.get("series"))
         claim = ClaimedSubscription(
@@ -120,6 +142,62 @@ class StudioSubscriptionControl:
             claim = replace(claim, resume_checkpoint=_resume_checkpoint(resume, claim))
         return claim
 
+    def _dispose_of_refused_claim(
+        self, value: Mapping[str, Any], error: StreamSubscriptionError
+    ) -> None:
+        """Dispose of a persisted lease this worker refused, on a best effort, and never raise.
+
+        TWO DISPOSITIONS, BECAUSE TWO DIFFERENT THINGS BOUND THEM.
+
+        A claim carrying no pending checkpoint is COMPLETED as failed. That charges the control
+        plane's failure budget, which spaces the retries and terminalizes the subscription once
+        the budget runs out, and it is the bound on a subscription this fleet cannot serve.
+
+        A claim carrying a ``resume_checkpoint`` is LEFT ALONE, and its lease runs out instead.
+        The control plane exempts a lease with a pending checkpoint from that budget -- a resume
+        is meant to survive a worker dying mid-segment -- and re-leases it as soon as it is free.
+        Completing one would therefore trade a lease expiry for an immediate reclaim, which is a
+        tighter loop than the one this method exists to end. Expiry is the slower of the two, so
+        expiry is what bounds this case.
+
+        The discriminator is the pending checkpoint rather than which member refused, because the
+        exemption is the control plane's and it is keyed on the same fact.
+        """
+
+        resuming = "resume_checkpoint" in value
+        LOGGER.warning(
+            "stream_subscription_claim_refused subscription_id=%s failure_code=%s disposition=%s",
+            _safe_subscription_id(value),
+            error.code,
+            "lease_expiry" if resuming else "completed_failed",
+        )
+        if resuming:
+            return
+        try:
+            url = _callback_url(value.get("complete_url"), origin=self.origin, label="complete")
+            body: dict[str, Any] = {
+                "schema_version": COMPLETE_SCHEMA_VERSION,
+                "lease_generation": _integer(value, "lease_generation", 1),
+                "terminal_reason": "failed",
+            }
+            self._post(url, body)
+        except SubscriptionFenceStale:
+            # The lease is already terminal, which is the outcome this was reaching for. A replay
+            # of a lost 5xx whose first attempt landed arrives here, so it is reported as done
+            # rather than as a completion that failed.
+            return
+        except Exception as unreported:
+            # Broad on purpose: whatever went wrong here, the refusal the caller is waiting on is
+            # the one that must reach it, so a second failure is logged and dropped rather than
+            # raised over the first.
+            LOGGER.warning(
+                "stream_subscription_claim_refusal_unreported subscription_id=%s failure_code=%s",
+                _safe_subscription_id(value),
+                unreported.code
+                if isinstance(unreported, StreamSubscriptionError)
+                else type(unreported).__name__,
+            )
+
     def resolve_credential(
         self, claim: ClaimedSubscription, *, credential_shape: str
     ) -> StreamCredential:
@@ -213,7 +291,8 @@ class StudioSubscriptionControl:
             "next_cursor": next_cursor,
             "segment_stream_id": capture.segment_stream_id,
             "manifest_object_name": capture.manifest_object_name,
-            "manifest_generation": capture.manifest_generation,
+            # Every object generation on the wire is text; the number stays an int in the capture.
+            "manifest_generation": str(capture.manifest_generation),
             "manifest_sha256": capture.manifest_sha256,
             "byte_length": capture.byte_length,
             "capture_digest": capture.capture_digest,
@@ -412,6 +491,42 @@ class StudioSubscriptionControl:
         raise AssertionError("unreachable")
 
 
+def _object_generation(value: Mapping[str, Any], name: str) -> int:
+    """One object generation, read from either spelling of the same bounded number.
+
+    EVERY OBJECT GENERATION ON THE WIRE IS TEXT, and an integer is admitted because a control
+    plane that echoes a stored coordinate back is not the place to relitigate a spelling.
+
+    The grammar is matched BEFORE the text is converted, and it is the control plane's own
+    nineteen-digit one.  An unbounded digit string is a refusal here: converting one crosses the
+    interpreter's own conversion limit and raises an untyped error out of a parser whose whole
+    contract is that it refuses in one vocabulary.
+    """
+
+    item = value.get(name)
+    if isinstance(item, str):
+        if not _OBJECT_GENERATION_TEXT.fullmatch(item):
+            raise StreamSubscriptionError("STREAM_SUBSCRIPTION_CLAIM_INVALID", name)
+        return int(item)
+    generation = _integer(value, name, 1)
+    if generation > MAX_OBJECT_GENERATION:
+        raise StreamSubscriptionError("STREAM_SUBSCRIPTION_CLAIM_INVALID", name)
+    return generation
+
+
+def _safe_subscription_id(value: Mapping[str, Any]) -> str:
+    """The claimed subscription id when it is a canonical UUID, and ``unknown`` otherwise.
+
+    A refusal log line must never repeat an unvalidated control-plane string, because the string
+    that failed to parse is exactly the one nothing has checked the shape of.
+    """
+
+    try:
+        return _uuid_text(value.get("stream_subscription_id"), "stream_subscription_id")
+    except StreamSubscriptionError:
+        return "unknown"
+
+
 def _code(raw: bytes) -> str | None:
     try:
         value = parse_json(raw)
@@ -541,7 +656,7 @@ def _resume_checkpoint(value: object, claim: ClaimedSubscription) -> ResumeCheck
     )
     capture = SealedCapture(
         manifest_object_name=_text(checkpoint, "manifest_object_name"),
-        manifest_generation=_integer(checkpoint, "manifest_generation", 1),
+        manifest_generation=_object_generation(checkpoint, "manifest_generation"),
         manifest_sha256=_digest(checkpoint.get("manifest_sha256"), "manifest sha256"),
         byte_length=_integer(checkpoint, "byte_length", 0),
         capture_digest=capture_digest,
@@ -622,7 +737,7 @@ def _recovery_inventory(
                 )
             artifacts[role] = RecoveryArtifact(
                 object_name=expected,
-                generation=_integer(artifact, "generation", 1),
+                generation=_object_generation(artifact, "generation"),
                 sha256=_digest(artifact.get("sha256"), f"{role} sha256"),
                 byte_length=_integer(artifact, "byte_length", 0),
                 media_type=_text(artifact, "media_type"),

{mostlyright_data-0.14.0 → mostlyright_data-0.14.2}/src/mostlyright/data_harness/thin/router.py

@@ -135,10 +135,10 @@ HOSTED_SUMMARY = dict(
             "ask Studio to publish one table and report only returned continuation evidence",
         ),
         ("reschedule", "change how often one table refreshes, without starting a run"),
-        ("table", "report what one table is serving, rename it, or retire it"),
+        ("table", "report what one table is serving, rename it, or retire one or many"),
         ("pin", "ask Studio to pin the live pointer and report the returned state"),
         ("unpin", "ask Studio to remove a pin and report the returned pointer state"),
-        ("demote", "ask Studio to withdraw the live pointer and report schedule state"),
+        ("demote", "ask Studio to withdraw the live pointer from one table or many"),
         ("watch", "stream one run's live progress, resuming across stream cuts"),
         ("download", "bring one run's artifacts back here, each one's digest checked"),
         ("receipt", "print the record one run sealed about how it was built"),
@@ -439,15 +439,22 @@ def _exit_codes() -> dict[str, Callable[[dict[str, Any]], int]]:
     ``ux.commands.CommandSpec`` gives: an exit code that can disagree with the printed answer is
     an exit code somebody will trust over the answer.
 
-    Six entries, and all six are answers a script acts on rather than reports it reads: a run held
-    at the spend gate has not started, a run that failed is not a build whichever surface it was
-    learned from, a table whose declared checks did not all pass is not one to go on with, a
+    Eight entries, and all eight are answers a script acts on rather than reports it reads: a run
+    held at the spend gate has not started, a run that failed is not a build whichever surface it
+    was learned from, a table whose declared checks did not all pass is not one to go on with, a
     question this command stopped waiting on has not been answered, and a probe that settled
     without an answer is not a yes. Everything else in the lane reports.
+
+    ⚠ THE LAST TWO ARE MOUNTED FOR THE NAME AND NOT FOR THE ACT, which is why one function serves
+    both. ``mr-data table archive`` and ``mr-data demote`` each take a LIST and never stop at the
+    first refusal, so "did it work" is a question about the whole list and only the counts can
+    answer it. ``mr-data table TABLE`` and ``mr-data table rename`` reach the same entry, carry no
+    counts, and exit ``0``: a report is not a gate, and the derivation says so rather than the
+    router keeping a second table of which halves of a name are which.
     """
 
     from mostlyright.data_harness.thin import probe as probe_module
-    from mostlyright.data_harness.thin import v4_artifacts, v4_query, v4_runs, v4_stream
+    from mostlyright.data_harness.thin import v4_artifacts, v4_query, v4_runs, v4_stream, v4_tables
 
     return {
         "run": v4_runs.run_exit_code,
@@ -456,6 +463,8 @@ def _exit_codes() -> dict[str, Callable[[dict[str, Any]], int]]:
         "checks": v4_artifacts.checks_exit_code,
         "query": v4_query.query_exit_code,
         "probe": probe_module.probe_exit_code,
+        "table": v4_tables.lifecycle_exit_code,
+        "demote": v4_tables.lifecycle_exit_code,
     }