mammoth-cli 2.0.77__tar.gz → 2.0.79__tar.gz

{mammoth_cli-2.0.77 → mammoth_cli-2.0.79}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.77
+Version: 2.0.79
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk

{mammoth_cli-2.0.77 → mammoth_cli-2.0.79}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.0.77"
+__version__ = "2.0.79"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.77 → mammoth_cli-2.0.79}/mammoth_cli/app.py

@@ -43,6 +43,7 @@ from mammoth_cli.output.policy import (
 )
 from mammoth_cli.runtime import executor, validate
 from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.state import with_state
 from mammoth_cli.runtime.strict import validate_extra_args
 from mammoth_cli.runtime.verify import with_verify
 from mammoth_cli.services.positionals import PositionalSpec, resolve_positionals
@@ -825,7 +826,7 @@ def _execute(invocation: Invocation) -> None:
         if invocation.dry_run:
             return _dry_run(handler, invocation)
         data, meta = handler(invocation)
-        return _apply_verify(invocation.command_id, data), meta
+        return _apply_verify(invocation, data), meta
 
     executor.run(
         invocation.command_id,
@@ -837,17 +838,23 @@ def _execute(invocation: Invocation) -> None:
     )
 
 
-def _apply_verify(command_id: str, data: Any) -> Any:
+def _apply_verify(invocation: Invocation, data: Any) -> Any:
     """Add the automatic write read-back to a real, mutating, API-backed result.
 
     A read command and a command with no reviewed ``sdk_symbol`` (a local or
     not-yet-backed command) are returned unchanged; ``--dry-run`` never
     reaches this at all, since it returns before the handler's real call.
+
+    Two independent read-backs are layered on top of the raw result: ``verify``
+    (status/row-count signals derived from the write's own response) and
+    ``state`` (a fresh read of what the write actually produced, per the
+    command's manifest ``readback``/``no_readback`` declaration -- see
+    :mod:`mammoth_cli.runtime.state`).
     """
-    record = command_by_id(command_id) or {}
+    record = command_by_id(invocation.command_id) or {}
     if record.get("mutation_class") == "read" or not record.get("sdk_symbol"):
         return data
-    return with_verify(data)
+    return with_state(invocation, with_verify(data, invocation))
 
 
 def _dry_run(handler: Handler, invocation: Invocation) -> tuple[Any, dict[str, Any]]:

{mammoth_cli-2.0.77 → mammoth_cli-2.0.79}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -42,12 +42,16 @@ never read one from a file/env var, never run `auth login`
 yourself. If any envelope carries `meta.update_available`, run its `command`
 before the next step.
 
+In a shell: piped stdout is compact JSON and prompts are off; in a session
+that is not piped, `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once.
+`project ensure` saves the active project (`--project`, `MAMMOTH_PROFILE`
+and `MAMMOTH_PROJECT` override it). `mammoth skill show --input '{"file":
+"references/recipes/transforms.md"}'` prints any file of this skill;
+`mammoth skill agents-md install` writes a steering block into a
+repository's AGENTS.md so later sessions start here.
+
 ## Defaults you do not repeat
 
-- Piped stdout is compact JSON and prompts are off. Only in a session that
-  is not piped, `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once.
-- `project ensure` saves the active project; `--project` only overrides it.
-  `MAMMOTH_PROFILE` / `MAMMOTH_PROJECT` also work as session defaults.
 - The CLI remembers which dataset owns each view from any read (`view list
   DATASET_ID`, `view get VIEW_ID`, an upload). After that, no `dataset_id`
   on transforms, exports or deletes. If a command asks for the parent
@@ -96,10 +100,10 @@ with the command tried.
 Users often upload related files without saying how they relate ("make a
 dashboard from t_a and t_b"). Work it out from the data before building:
 
-1. Upload every file. Each result carries a `view` preview of what Mammoth
-   made of it (`view_id`, column types, sample rows, `column_warnings`,
-   `before_dashboard`). Do not open the local files (`cat`, `head`) — what
-   Mammoth made of them is what counts. Run `view data get VIEW_ID` per view;
+1. Upload every file, or find the ones already uploaded. An upload result
+   carries a `view` preview of what Mammoth made of it (`view_id`, column
+   types, sample rows, `column_warnings`, `before_dashboard`). What Mammoth
+   made of the files is what counts, not the raw files. Run `view data get VIEW_ID` per view;
    warnings list numbers/dates stored as text, and blanks, each with its fix.
 2. Find the keys. A column in one view whose values appear in a column of
    the other (`customer_id` and `id`, `order_ref` and `order_no`) is a
@@ -114,8 +118,8 @@ dashboard from t_a and t_b"). Work it out from the data before building:
    is a miss.
 5. `view transform join` the lookup view into the main view (`LEFT`). The
    result's `join_check` gives `match_rate`, `unmatched_rows` and
-   `unmatched_keys`; put them in your report, and stop to compare the keys
-   if more than a few rows found no match.
+   `unmatched_keys`; put them in your report. When the result's
+   `verify.needs_user` is set, stop and tell the user before building on it.
 6. If the data has money, add it before you make the dashboard: `revenue`
    (`math`, `qty * price`, `new_column`), the `fix` in `before_dashboard`.
    A dashboard sees only the columns the view had when it was made.
@@ -134,9 +138,6 @@ your report. If no column links the files, ask before you combine them.
 
 - Ids are positionals; request fields are one `--input '{...}'` document;
   no per-field flags (`project create NAME`, not `--name`).
-- `mammoth skill show --input '{"file": "references/recipes/transforms.md"}'`
-  prints any file of this skill; `mammoth skill agents-md install` writes a
-  steering block into a repository's AGENTS.md so later sessions start here.
 - `COMMAND --help` lists input fields; `schema find WORDS` inlines
   `accepted_fields`/`agent_example` for top matches, else `mammoth schema
   get COMMAND_ID` (`--input '{"full": true}'` for the schema); `schema
@@ -161,11 +162,10 @@ your report. If no column links the files, ask before you combine them.
 
 ## Verify before you report
 
-- A success envelope proves the call, not the outcome. After a row-scoped
-  change (set-values, filter, replace, join, fill) run `view data get
-  VIEW_ID` (50 rows by default, `limit` to change) and check rows the
-  condition should and should not have touched. Sample the target column
-  before the change.
+- A success envelope proves the call; the write's `state` (the data,
+  object or job status read back after it settled) shows the outcome.
+  Check it against your plan: rows the change should and should not have
+  touched. `unreadable` or a partial sample: read it with `view data get`.
 - A uniform result (every amount 0, every region "Unknown", most join rows
   unmatched) means the previous step went wrong; stop and re-inspect it.
 - `column_warnings` on a data read and `join_check` on a join are findings,

{mammoth_cli-2.0.77 → mammoth_cli-2.0.79}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view-transform.md

@@ -96,9 +96,9 @@ Status on release: ran once on CLI 2.0.40 through `view.task.add` and was read b
 
 Run: `mammoth view transform delete-columns`. Exact input fields: `mammoth schema get view.transform.delete-columns`.
 
-Example: `mammoth view transform delete-columns 123 --input '{"columns": ["Status"], "dataset_id": 456}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth view transform delete-columns 123 --input '{"columns": ["Status"], "dataset_id": 456}'`. Illustrative only: append `--yes` after observing an owned target.
 
-Result: `ViewTransformDeleteColumnsResult`; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`.
+Result: `ViewTransformDeleteColumnsResult`; mutation `reversible_pipeline`, confirmation `prompt_or_yes`, wait policy `always_wait`.
 
 Status on release: ran once on CLI 2.0.40 through `view.task.add` and was read back with `view data get`; other inputs for this transform are untried.
 

{mammoth_cli-2.0.77 → mammoth_cli-2.0.79}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -7,7 +7,7 @@ sentence with `v3 generate`, and change it with `chat edit`; author a canvas by
 hand (`create-blank`, `canvas save`, `pages add`) only when asked to.
 `dashboard source list` is an observed blocker on release (see
 capabilities); verify the view binding with `dashboard get DASHBOARD_ID`
-(`data.dataview_id`) instead.
+(`data.sources`) instead.
 
 ```bash
 mammoth dashboard v3 generate --input '{"body": {"params": {"intent": "Monthly revenue by region, with top customers", "dataview_id": VIEW_ID}}}'

mammoth_cli-2.0.79/mammoth_cli/runtime/state.py

@@ -0,0 +1,413 @@
+"""Automatic write read-back: attach the write's new state to its result.
+
+``with_verify`` (see :mod:`mammoth_cli.runtime.verify`) tells the caller
+whether a write succeeded. It does not show what the write actually produced:
+an export can report ``verified: true`` while the dataset it wrote has one of
+four expected columns, and nothing in the result would say so. :func:`with_state`
+closes that gap: every manifest command whose ``mutation_class`` is not
+``read`` declares, in its command record, either a ``readback`` (a read
+command plus how to source its arguments from this write's input/result, plus
+a ``kind``) or a ``no_readback`` reason. After the write settles, the executor
+runs the declared read and attaches a compact ``state`` block built from it --
+never from the request, and never omitted: a read that fails still yields a
+``state`` (``kind: unreadable``) rather than silence.
+
+See ``CONTRACT-write-state.md`` (D-077) for the manifest shape this reads.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mammoth_cli.errors.envelope import CliError
+from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.services.positionals import resolve_positionals
+
+#: Total JSON size a ``state`` block may reach before trimming kicks in.
+STATE_SIZE_CAP_BYTES = 1500
+
+#: Sample rows a ``kind: data`` state keeps, and the char length each cell is
+#: truncated to -- row count and columns are never dropped to make room.
+_SAMPLE_ROW_CAP = 5
+_CELL_CHAR_CAP = 80
+
+_VIEW_GET_COMMAND = "view.get"
+_VIEW_DATA_COMMAND = "view.data.get"
+_VIEW_LIST_COMMAND = "view.list"
+
+#: ``verify.state`` of a write that was accepted but has not finished.
+_UNFINISHED_VERIFY_STATE = "processing"
+
+
+def with_state(invocation: Invocation, data: Any) -> Any:
+    """Return ``data`` with a ``state`` read-back block added, per the manifest.
+
+    A command with no ``readback``/``no_readback`` declared yet (mid-rollout)
+    is returned unchanged, as is a command that declares ``no_readback`` --
+    there is nothing to read back, by the family owner's own account.
+    """
+    if not isinstance(data, dict):
+        return data
+    record = command_by_id(invocation.command_id) or {}
+    readback = record.get("readback")
+    if not isinstance(readback, dict):
+        return data
+    unfinished = _unfinished_state(data)
+    state = unfinished or _enforce_cap(_build_state(invocation, data, readback))
+    return {**data, "state": state}
+
+
+def _unfinished_state(data: dict[str, Any]) -> dict[str, Any] | None:
+    """A write ``verify`` found still processing has no new state to read yet."""
+    verify = data.get("verify")
+    if not isinstance(verify, dict) or verify.get("state") != _UNFINISHED_VERIFY_STATE:
+        return None
+    return {
+        "kind": "delivery",
+        "read_by": "verify",
+        "status": _UNFINISHED_VERIFY_STATE,
+        "detail": verify.get("reason"),
+    }
+
+
+def _build_state(
+    invocation: Invocation, data: dict[str, Any], readback: dict[str, Any]
+) -> dict[str, Any]:
+    read_command_id = str(readback["command"])
+    kind = str(readback["kind"])
+    ids_spec: dict[str, Any] = readback.get("ids") or {}
+    resolved_ids: dict[str, Any] = {}
+    try:
+        resolved_ids = {
+            name: _resolve_source(str(source), data, invocation)
+            for name, source in ids_spec.items()
+        }
+        missing = [name for name, value in resolved_ids.items() if value is None]
+        if missing:
+            raise ValueError(f"could not resolve id(s) {missing} from the write's result/input")
+        if kind == "data":
+            return _data_state(resolved_ids, invocation)
+        read_data = _call_read(read_command_id, resolved_ids, invocation)
+        read_by = _read_by_label(read_command_id, resolved_ids)
+        if kind == "object":
+            return _object_state(read_by, read_data)
+        if kind == "delivery":
+            return _delivery_state(read_by, read_data)
+        raise ValueError(f"unknown readback kind {kind!r}")
+    except Exception as exc:  # noqa: BLE001 -- a read failure must surface, never crash the write
+        read_by = _read_by_label(read_command_id, resolved_ids)
+        reason = exc.message if isinstance(exc, CliError) else str(exc)
+        return {"kind": "unreadable", "read_by": read_by, "reason": reason or type(exc).__name__}
+
+
+def _read_by_label(command_id: str, resolved_ids: dict[str, Any]) -> str:
+    representative = next(iter(resolved_ids.values()), None)
+    return f"{command_id} {representative}" if representative is not None else command_id
+
+
+# ---------------------------------------------------------------------------
+# id resolution
+# ---------------------------------------------------------------------------
+
+
+def _resolve_source(source: str, data: dict[str, Any], invocation: Invocation) -> Any:
+    """Resolve one ``ids`` value; ``a|b`` takes the first alternative that resolves.
+
+    A write whose response comes in more than one shape (an export returns
+    either ``{trigger_id, future_id}`` or ``{"job": {...}}``) names each place
+    its id can be.
+    """
+    for alternative in source.split("|"):
+        value = _resolve_one_source(alternative, data, invocation)
+        if value is not None:
+            return value
+    return None
+
+
+def _resolve_one_source(source: str, data: dict[str, Any], invocation: Invocation) -> Any:
+    """Resolve one ``result.<path>`` | ``input.<field>`` | ``positional.<n>`` source."""
+    if source.startswith("result."):
+        return _get_path(data, source[len("result.") :])
+    if source.startswith("input."):
+        document = invocation.bound_input() or {}
+        return _get_path(document, source[len("input.") :])
+    if source.startswith("positional."):
+        index_text = source[len("positional.") :]
+        try:
+            index = int(index_text)
+        except ValueError:
+            raise ValueError(f"invalid positional index in id source {source!r}") from None
+        return invocation.extra_args[index] if index < len(invocation.extra_args) else None
+    raise ValueError(f"unrecognized id source {source!r}")
+
+
+def _get_path(root: Any, path: str) -> Any:
+    current = root
+    for segment in path.split("."):
+        if isinstance(current, dict):
+            current = current.get(segment)
+        elif isinstance(current, list) and segment.isdigit():
+            index = int(segment)
+            current = current[index] if index < len(current) else None
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# dispatching a read command's handler directly (never through the executor:
+# this is an internal follow-up read, not a fresh command invocation)
+# ---------------------------------------------------------------------------
+
+
+def _read_invocation(command_id: str, resolved_ids: dict[str, Any], base: Invocation) -> Invocation:
+    """Build the :class:`Invocation` a read command's handler expects.
+
+    Ids that name a declared positional of ``command_id`` are supplied in
+    order (matching how handlers read ``extra_args``); any id left over is
+    offered as a pre-admitted ``--input`` document instead.
+    """
+    positional_names = [spec.name for spec in resolve_positionals(command_id)]
+    positionals: dict[str, Any] = {}
+    extra_args: list[str] = []
+    for name in positional_names:
+        if name not in resolved_ids:
+            break
+        value = resolved_ids[name]
+        positionals[name] = value
+        extra_args.append(str(value))
+    document = {name: value for name, value in resolved_ids.items() if name not in positionals}
+    invocation = Invocation(
+        command_id=command_id,
+        output="json",
+        profile=base.profile,
+        project=base.project,
+        timeout=base.timeout,
+        job_timeout=base.job_timeout,
+        pipeline_timeout=base.pipeline_timeout,
+        no_input=True,
+        positionals=positionals,
+        extra_args=extra_args,
+    )
+    object.__setattr__(invocation, "_prepared_input", document or None)
+    return invocation
+
+
+def _call_read(command_id: str, resolved_ids: dict[str, Any], base: Invocation) -> Any:
+    from mammoth_cli.commands.registry import HANDLERS
+
+    handler = HANDLERS.get(command_id)
+    if handler is None:
+        raise LookupError(f"no handler registered for read command {command_id!r}")
+    read_invocation = _read_invocation(command_id, resolved_ids, base)
+    read_data, _meta = handler(read_invocation)
+    return read_data
+
+
+# ---------------------------------------------------------------------------
+# kind: object
+# ---------------------------------------------------------------------------
+
+
+def _object_state(read_by: str, read_data: Any) -> dict[str, Any]:
+    return {"kind": "object", "read_by": read_by, "object": _extract_object(read_data)}
+
+
+def _extract_object(read_data: Any) -> Any:
+    if not isinstance(read_data, dict):
+        return read_data
+    # A single-record read (``view.get``, ``dataset.get``, ...) carries its own
+    # ``id`` at the top level; a listing read (``view.list``, ...) wraps its
+    # items under a plural key instead. Checking for ``id`` first keeps a
+    # record's own nested list fields (e.g. a dataview's ``metadata`` columns)
+    # from being mistaken for the collection.
+    if "id" not in read_data:
+        listing = _first_list(read_data)
+        if listing is not None:
+            return [_scalar_fields(item) for item in listing]
+    return _scalar_fields(read_data)
+
+
+def _first_list(record: dict[str, Any]) -> list[Any] | None:
+    """The first list-of-dicts value in a ``*.list`` read's result, if any."""
+    for value in record.values():
+        if isinstance(value, list) and (not value or isinstance(value[0], dict)):
+            return value
+    return None
+
+
+def _scalar_fields(item: Any) -> Any:
+    """Keep only an object's top-level scalar fields (every id is one)."""
+    if not isinstance(item, dict):
+        return item
+    return {
+        key: value
+        for key, value in item.items()
+        if value is None or isinstance(value, (str, int, float, bool))
+    }
+
+
+# ---------------------------------------------------------------------------
+# kind: delivery
+# ---------------------------------------------------------------------------
+
+
+def _delivery_state(read_by: str, read_data: Any) -> dict[str, Any]:
+    status: Any = None
+    detail: Any = None
+    if isinstance(read_data, dict):
+        status = read_data.get("status")
+        if status is None:
+            job = read_data.get("job")
+            status = job.get("status") if isinstance(job, dict) else None
+        detail = read_data.get("message") or read_data.get("detail") or read_data.get("error")
+    return {
+        "kind": "delivery",
+        "read_by": read_by,
+        "status": status if isinstance(status, str) else None,
+        "detail": str(detail) if detail is not None else None,
+    }
+
+
+# ---------------------------------------------------------------------------
+# kind: data -- the write's output view: real columns, row count, 5 rows.
+#
+# No single read command returns columns+type, row_count and sample rows
+# together, so this always makes two fixed internal reads once it has a
+# view id: ``view.get`` for the typed columns and row count, ``view.data.get``
+# for the sample. When the write's own ids only resolve a dataset id (a
+# dataset/upload write, whose output is that dataset's first view), the
+# view id is discovered with one ``view.list`` read first.
+# ---------------------------------------------------------------------------
+
+
+def _data_state(resolved_ids: dict[str, Any], base: Invocation) -> dict[str, Any]:
+    view_id = _as_int(resolved_ids.get("view_id") or resolved_ids.get("dataview_id"))
+    dataset_id = _as_int(resolved_ids.get("dataset_id"))
+    if view_id is None:
+        if dataset_id is None:
+            raise ValueError("readback kind 'data' needs a resolved view_id or dataset_id")
+        view_id = _discover_view_id(dataset_id, base)
+    view_ids: dict[str, Any] = {"view_id": view_id}
+    if dataset_id is not None:
+        view_ids["dataset_id"] = dataset_id
+    info = _call_read(_VIEW_GET_COMMAND, view_ids, base)
+    page = _call_read(_VIEW_DATA_COMMAND, view_ids, base)
+    rows = page.get("data") if isinstance(page, dict) else None
+    sample = [_trim_row(row) for row in (rows or [])[:_SAMPLE_ROW_CAP]]
+    return {
+        "kind": "data",
+        "read_by": f"{_VIEW_DATA_COMMAND} {view_id}",
+        "columns": _columns(info),
+        "row_count": info.get("row_count") if isinstance(info, dict) else None,
+        "sample": sample,
+    }
+
+
+def _discover_view_id(dataset_id: int, base: Invocation) -> int:
+    listing = _call_read(_VIEW_LIST_COMMAND, {"dataset_id": dataset_id}, base)
+    views = listing.get("dataviews") if isinstance(listing, dict) else None
+    if not isinstance(views, list) or not views or not isinstance(views[0], dict):
+        raise ValueError(f"dataset {dataset_id} has no view to read its new state from")
+    view_id = views[0].get("id")
+    if not isinstance(view_id, int):
+        raise ValueError(f"dataset {dataset_id}'s first view has no usable id")
+    return view_id
+
+
+def _columns(info: Any) -> list[dict[str, str]]:
+    if not isinstance(info, dict):
+        return []
+    metadata = info.get("metadata")
+    if not isinstance(metadata, list):
+        return []
+    columns: list[dict[str, str]] = []
+    for column in metadata:
+        if not isinstance(column, dict):
+            continue
+        name = column.get("display_name") or column.get("internal_name")
+        if name is None:
+            continue
+        columns.append({"name": str(name), "type": str(column.get("type") or "")})
+    return columns
+
+
+def _trim_row(row: Any) -> Any:
+    if not isinstance(row, dict):
+        return row
+    return {key: _trim_cell(value) for key, value in row.items()}
+
+
+def _trim_cell(value: Any) -> Any:
+    if isinstance(value, str) and len(value) > _CELL_CHAR_CAP:
+        return value[:_CELL_CHAR_CAP] + "..."
+    return value
+
+
+def _as_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str) and value.strip().lstrip("-").isdigit():
+        return int(value)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# size cap
+# ---------------------------------------------------------------------------
+
+
+def _enforce_cap(state: dict[str, Any]) -> dict[str, Any]:
+    """Trim ``state`` under :data:`STATE_SIZE_CAP_BYTES`; never drop columns/row_count."""
+    if _size(state) <= STATE_SIZE_CAP_BYTES:
+        return state
+    kind = state.get("kind")
+    if kind == "data":
+        sample = list(state.get("sample") or [])
+        while sample and _size({**state, "sample": sample}) > STATE_SIZE_CAP_BYTES:
+            sample.pop()
+        return {**state, "sample": sample}
+    if kind == "object":
+        capped = {**state, "object": _capped_object(state)}
+        original = state.get("object")
+        if isinstance(original, list) and len(capped["object"]) < len(original):
+            capped["object_total"] = len(original)
+        return capped
+    if kind == "delivery":
+        detail = state.get("detail")
+        if isinstance(detail, str):
+            overflow = _size(state) - STATE_SIZE_CAP_BYTES
+            keep = max(0, len(detail) - overflow - 3)
+            return {**state, "detail": detail[:keep] + "..."}
+    return state
+
+
+def _capped_object(state: dict[str, Any]) -> Any:
+    obj = state.get("object")
+    if isinstance(obj, list):
+        items = list(obj)
+        while items and _size({**state, "object": items}) > STATE_SIZE_CAP_BYTES:
+            items.pop()
+        return items
+    if isinstance(obj, dict):
+        fields = dict(obj)
+        protected = {key for key in fields if key == "id" or key.endswith("_id")}
+        droppable = sorted(
+            (key for key in fields if key not in protected),
+            key=lambda key: len(str(fields[key])),
+            reverse=True,
+        )
+        for key in droppable:
+            if _size({**state, "object": fields}) <= STATE_SIZE_CAP_BYTES:
+                break
+            fields.pop(key, None)
+        return fields
+    return obj
+
+
+def _size(value: Any) -> int:
+    return len(json.dumps(value, default=str))

{mammoth_cli-2.0.77 → mammoth_cli-2.0.79}/mammoth_cli/runtime/verify.py

@@ -10,7 +10,10 @@ what it should" instead of re-deriving it per command.
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mammoth_cli.runtime.invocation import Invocation
 
 #: Below this share of matched rows, a join has enough misses to flag before
 #: the caller builds anything further on it.
@@ -19,6 +22,10 @@ JOIN_MATCH_RATE_THRESHOLD = 0.8
 _FAILURE_STATUSES = frozenset({"error", "failed", "failure"})
 _FAILURE_PIPELINE_STATES = frozenset({"error", "ref_error"})
 
+#: HTTP status codes that mean "accepted, not finished" when a write's own
+#: response carries no other completion signal at all.
+_ACCEPTED_STATUS_CODES = frozenset({202})
+
 
 #: Surfaced in ``warnings`` (and drives ``verified: false``) when a
 #: ``row_check``/``join_check`` was attempted but ``rows_after`` never came
@@ -39,14 +46,19 @@ _UNSETTLED_REASON = (
 )
 
 
-def with_verify(data: Any) -> Any:
+def with_verify(data: Any, invocation: Invocation | None = None) -> Any:
     """Return ``data`` with a ``verify`` read-back block added.
 
     ``data`` that is not a dict (a dry-run report, a bare list, ...) is
-    returned unchanged.
+    returned unchanged. When ``invocation`` is given, a write whose own
+    response is nothing but an unsettled async job (a bare ``job_id``/
+    ``future_id``, or an HTTP 202 with no job reference at all) is settled
+    first -- see :func:`_settle_unfinished_write` -- so it is never reported
+    ``verified: true`` before it has actually finished.
     """
     if not isinstance(data, dict):
         return data
+    data = _settle_unfinished_write(data, invocation)
     check = _check_dict(data)
     row_count_attempted = _row_count_attempted(check)
     rows_before, rows_after = _row_counts(check) if row_count_attempted else (None, None)
@@ -80,6 +92,42 @@ def _job_status(data: dict[str, Any]) -> str | None:
     return status if isinstance(status, str) else None
 
 
+def _settle_unfinished_write(data: dict[str, Any], invocation: Invocation | None) -> dict[str, Any]:
+    """Settle a write whose immediate response is an unfinished async job.
+
+    ``wait_if_job`` (every ``MammothService``) already recognizes a bare
+    ``{"job_id": N}``/``{"future_id": N}`` job reference and polls it to
+    completion -- raising on failure or timeout, exactly like every other
+    settle in this codebase -- but only a write handler that explicitly calls
+    it gets that settle. A write whose result carries no other completion
+    signal (no ``status``/``pipeline_state``/nested ``job.status``) must not
+    be reported ``verified: true`` on the strength of an unpolled job
+    reference, or of an HTTP 202 with no reference to poll at all.
+    """
+    if invocation is None or _job_status(data) is not None:
+        return data
+    if isinstance(data.get("status"), str) or isinstance(data.get("pipeline_state"), str):
+        return data
+    if _has_bare_job_reference(data):
+        from mammoth_cli.runtime.session import open_service
+
+        with open_service(invocation) as (service, _auth):
+            settled = service.wait_if_job(data)
+        return settled if isinstance(settled, dict) else data
+    if data.get("status_code") in _ACCEPTED_STATUS_CODES:
+        # Accepted, with nothing at all to poll: still not finished.
+        return {**data, "status": "processing"}
+    return data
+
+
+def _has_bare_job_reference(data: dict[str, Any]) -> bool:
+    for key in ("job_id", "future_id"):
+        value = data.get(key)
+        if isinstance(value, int) and not isinstance(value, bool):
+            return True
+    return False
+
+
 def _check_dict(data: dict[str, Any]) -> dict[str, Any] | None:
     """The ``row_check``/``join_check`` dict a command attached, if any."""
     for key in ("row_check", "join_check"):