cortexdb-cli 0.7.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

cortexdb_cli/__init__.py

@@ -1,3 +1,3 @@
 """CortexDB CLI - command-line interface for the v1 memory API."""
 
-__version__ = "0.7.1"
+__version__ = "0.8.0"

cortexdb_cli/commands/admin.py

@@ -95,7 +95,7 @@ def admin_layers(ctx: click.Context) -> None:
 
 # -- retention (unified WAL) -------------------------------------------------
 #
-# The operator surface over the D1 retention plane. Every write here is
+# The operator surface over the retention plane. Every write here is
 # irreversible in effect - an applied sweep removes expired captured events,
 # everything about them under an `erase` rule, their raw data under a
 # `keep_learned` one - so reporting is the default on both mutating commands

cortexdb_cli/commands/beliefs.py

@@ -5,12 +5,20 @@ from __future__ import annotations
 import click
 
 from cortexdb_cli.client import get_client
-from cortexdb_cli.common import api_options, at_least_option
+from cortexdb_cli.common import (
+    api_options,
+    at_least_option,
+    derived_by_option,
+    include_option,
+    include_param,
+)
 from cortexdb_cli.errors import handle_errors
 from cortexdb_cli.output import (
     console,
+    derivation_summary,
     escape,
     is_json_mode,
+    note_unreported_derivation,
     print_json,
     spinner,
 )
@@ -40,15 +48,30 @@ def _scope_or_die(cfg: dict, scope: str | None) -> str:
 @beliefs_group.command("list")
 @click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
 @click.option("--limit", "-l", default=50, show_default=True)
+@include_option
 @at_least_option
 @api_options
 @click.pass_context
 @handle_errors
-def beliefs_list(ctx: click.Context, scope: str | None, limit: int, at_least: str | None) -> None:
-    """List active beliefs in a scope."""
+def beliefs_list(
+    ctx: click.Context,
+    scope: str | None,
+    limit: int,
+    include: tuple[str, ...],
+    at_least: str | None,
+) -> None:
+    """List active beliefs in a scope.
+
+    With --include derivation each belief also says how it was made,
+    computed from its supporting facts (the latest one's; unsynced when any
+    of them is). A belief with no fact support, a declared one, has no stamp.
+    """
     cfg = ctx.obj
     s = _scope_or_die(cfg, scope)
     params: dict[str, str | int] = {"scope": s, "limit": limit}
+    included = include_param(include)
+    if included:
+        params["include"] = included
     if at_least:
         params["at_least"] = at_least
     with get_client(cfg) as client:
@@ -79,19 +102,26 @@ def beliefs_list(ctx: click.Context, scope: str | None, limit: int, at_least: st
     table.add_column("Object", style="bold")
     table.add_column("Conf", justify="right", width=6)
     table.add_column("Support", justify="right", width=8)
+    if included:
+        table.add_column("Why", style="dim", max_width=48)
     for b in items:
         # v1 beliefs carry their triple under `claim` ({subject, predicate,
         # object}, each term {type, value|id}); the columns used to read
         # top-level `predicate`/`object`, which no belief has.
         claim = b.get("claim") if isinstance(b.get("claim"), dict) else b
-        table.add_row(
+        row = [
             escape(str(b.get("belief_id") or b.get("id", ""))[:16]),
             escape(_term(claim.get("predicate"))),
             escape(_term(claim.get("object"))),
             f"{(b.get('confidence') or 0):.0%}",
             str(b.get("support_count") or len(b.get("supports") or [])),
-        )
+        ]
+        if included:
+            row.append(escape(derivation_summary(b.get("derivation"))))
+        table.add_row(*row)
     console.print(table)
+    if included:
+        note_unreported_derivation(items)
     if isinstance(data, dict) and data.get("rollups"):
         console.print(
             f"[dim]{len(data['rollups'])} rollup(s) on this page; "
@@ -108,19 +138,30 @@ def beliefs_list(ctx: click.Context, scope: str | None, limit: int, at_least: st
     help="Return the belief only if it lies at or under this scope (?scope=; else 404). It "
     "routes the read on a cluster, and a break-glass read of a private region must name it.",
 )
+@include_option
 @api_options
 @click.pass_context
 @handle_errors
-def beliefs_why(ctx: click.Context, belief_id: str, scope: str | None) -> None:
+def beliefs_why(
+    ctx: click.Context, belief_id: str, scope: str | None, include: tuple[str, ...]
+) -> None:
     """Show the facts + events that ground a belief.
 
+    \b
         cortexdb beliefs why belief_01HX...
         cortexdb beliefs why belief_01HX... --scope org:acme/team:eng
+        cortexdb beliefs why belief_01HX... --include derivation
+
+    With --include derivation the belief also carries its derivation, and
+    the terminal says it on one line under the answer.
     """
     cfg = ctx.obj
     params = {"belief_id": belief_id}
     if scope:
         params["scope"] = scope
+    included = include_param(include)
+    if included:
+        params["include"] = included
     with get_client(cfg) as client:
         if not is_json_mode(cfg):
             with spinner("Tracing provenance..."):
@@ -128,7 +169,13 @@ def beliefs_why(ctx: click.Context, belief_id: str, scope: str | None) -> None:
         else:
             resp = client.get("/v1/beliefs/why", params=params)
         resp.raise_for_status()
-        print_json(resp.json())
+        data = resp.json()
+        print_json(data)
+    if included and not is_json_mode(cfg):
+        belief = data.get("belief") if isinstance(data, dict) else None
+        if isinstance(belief, dict):
+            console.print(f"[dim]why: {escape(derivation_summary(belief.get('derivation')))}[/dim]")
+            note_unreported_derivation([belief])
 
 
 @beliefs_group.command("create")
@@ -165,6 +212,10 @@ def beliefs_why(ctx: click.Context, belief_id: str, scope: str | None) -> None:
     "key is 409 IDEMPOTENCY_CONFLICT).",
 )
 @click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@derived_by_option(
+    "A declared belief carries it in its record (below apply format 10 the server answers 503 "
+    "FORMAT_UPGRADE_PENDING), and include=derivation reads it back."
+)
 @api_options
 @click.pass_context
 @handle_errors
@@ -179,16 +230,20 @@ def beliefs_create(
     provenance: tuple[str, ...],
     idempotency_key: str | None,
     scope: str | None,
+    derived_by: dict[str, str] | None,
 ) -> None:
     """Declare a belief directly (POST /v1/beliefs).
 
     \b
         cortexdb beliefs create "Acme is on the enterprise plan" \\
             --confidence 0.9 --support evt_01HX... --subject Acme --predicate plan
+        cortexdb beliefs create "Bob reads at level B2" --confidence 0.8 \\
+            --subject Bob --predicate level --derived-by acme-level@1.1.0
 
     Declaring a newer belief over the same (subject, predicate) closes the
     previous one. Pass --idempotency-key to retry safely after an outcome
-    you did not learn (WAL_OUTCOME_UNKNOWN, a lost connection).
+    you did not learn (WAL_OUTCOME_UNKNOWN, a lost connection); the same key
+    with another --derived-by stamp, or none, is 409 IDEMPOTENCY_CONFLICT.
     """
     cfg = ctx.obj
     s = _scope_or_die(cfg, scope)
@@ -210,6 +265,8 @@ def beliefs_create(
         if not idempotency_key.strip() or len(idempotency_key.encode("utf-8")) > 256:
             raise click.UsageError("--idempotency-key is 1 to 256 bytes, not blank")
         body["idempotency_key"] = idempotency_key
+    if derived_by:
+        body["derived_by"] = derived_by
     with get_client(cfg) as client:
         resp = client.post("/v1/beliefs", json=body)
         resp.raise_for_status()

cortexdb_cli/commands/changes.py

@@ -19,12 +19,21 @@ applies a structure other than the one previewed (409 PREVIEW_CHANGED).
 - a list of operations `{"path", "op": "put" | "delete", "record"?}`;
 - `{"records": [...]}` (one part), or `{"parts": [{"part", "records"}]}`.
 
+A derivation policy (`derivation_policy_v1`, CortexDB 0.15.0) is a record of
+kind `derive` at `<scope>/attrs:derive`. An entry `{"scope": SCOPE,
+"derive": {...}}` is the put of SCOPE's policy, `{"path":
+"<scope>/attrs:derive", "op": "put", "record": {"tree": {"kind": "derive"},
+"derive": {...}}}`; a record that carries `derive` and no `tree` is given
+`{"tree": {"kind": "derive"}}`. A change set that writes a derive record
+writes nothing else (`cortexdb derivation stage` stages one for you).
+
 `--delete PATH` adds a delete of that path to the part. `--scope` is the
 tenant root and defaults to the root of your default scope.
 """
 
 from __future__ import annotations
 
+import json
 import time
 from typing import Any
 
@@ -33,7 +42,7 @@ import click
 from cortexdb_cli.client import get_client, path_segment
 from cortexdb_cli.common import api_options, body_of, emit, read_json_file, root_or_die, send
 from cortexdb_cli.errors import handle_errors
-from cortexdb_cli.output import console, err_console, escape, is_json_mode, print_json
+from cortexdb_cli.output import console, err_console, escape, is_json_mode, print_json, warning_text
 
 #: The exit status of a change-set command whose --wait ran out while the
 #: server still answered 202 (EX_TEMPFAIL): nothing failed, the evaluation
@@ -49,7 +58,9 @@ def changes_group() -> None:
     """Access change sets - stage, preview, activate, discard."""
 
 
-def _wait_option(fn):
+def wait_option(fn):
+    """`--wait SECONDS`: how long a command sends a request again while the
+    server answers an evaluation's 202."""
     return click.option(
         "--wait", "wait_s", type=click.FloatRange(min=0), default=DEFAULT_WAIT_S, show_default=True,
         help="Seconds to keep sending the request while the server answers 202 (its evaluation runs "
@@ -130,15 +141,51 @@ def _records_options(fn):
     return fn
 
 
+#: The leaf of a derivation policy's record path (`<scope>/attrs:derive`).
+DERIVE_LEAF = "attrs:derive"
+
+
+def derive_path(scope: str) -> str:
+    """The path of SCOPE's derivation policy record."""
+    return f"{scope}/{DERIVE_LEAF}"
+
+
+def derive_record(body: Any) -> dict[str, Any]:
+    """The registry record that carries a derive body."""
+    return {"tree": {"kind": "derive"}, "derive": body}
+
+
+def with_derive_kind(record: Any) -> Any:
+    """`record`, with `{"tree": {"kind": "derive"}}` when it carries a derive
+    body and no `tree` (a derive record is of kind derive, and the server
+    refuses one without it)."""
+    if isinstance(record, dict) and "derive" in record and "tree" not in record:
+        return {"tree": {"kind": "derive"}, **record}
+    return record
+
+
 def _operation(entry: Any) -> dict[str, Any]:
+    if isinstance(entry, dict) and "derive" in entry and "path" not in entry and "op" not in entry:
+        # A derivation policy entry: {"scope": the governed scope, "derive": body}.
+        scope = entry.get("scope")
+        if not isinstance(scope, str) or not scope:
+            raise click.UsageError(
+                "a derivation policy entry in --file names the scope it governs: "
+                '{"scope": SCOPE, "derive": {...}}'
+            )
+        record = {key: value for key, value in entry.items() if key != "scope"}
+        return {"path": derive_path(scope), "op": "put", "record": with_derive_kind(record)}
     if not isinstance(entry, dict) or not entry.get("path"):
-        raise click.UsageError("each record or operation in --file needs a `path`")
+        raise click.UsageError(
+            "each record or operation in --file needs a `path` (a derivation policy entry: "
+            "`scope` and `derive`)"
+        )
     if "op" in entry:
         op = {"path": entry["path"], "op": entry["op"]}
         if "record" in entry:
-            op["record"] = entry["record"]
+            op["record"] = with_derive_kind(entry["record"])
         return op
-    return {"path": entry["path"], "op": "put", "record": entry}
+    return {"path": entry["path"], "op": "put", "record": with_derive_kind(entry)}
 
 
 def build_parts(doc: Any, part: int | None, deletes: tuple[str, ...], default_part: int | None) -> list[dict[str, Any]]:
@@ -170,7 +217,8 @@ def build_parts(doc: Any, part: int | None, deletes: tuple[str, ...], default_pa
     return [{"part": number, "records": records}]
 
 
-def _render_state(data: dict[str, Any]) -> None:
+def render_state(data: dict[str, Any]) -> None:
+    """A change set's status (a staging's, an activation's or `get`'s answer)."""
     state = str(data.get("state", ""))
     style = {"activated": "success", "discarded": "dim", "scheduled": "info"}.get(state, "warning")
     parts = data.get("parts")
@@ -187,11 +235,27 @@ def _render_state(data: dict[str, Any]) -> None:
     if isinstance(refusal, dict) and refusal:
         console.print(f"[error]  refused: {escape(str(refusal.get('code')))}[/error] "
                       f"[dim]{escape(', '.join(refusal.get('paths') or []))}[/dim]")
+    _render_warnings(data)
     if data.get("consistency_token"):
         console.print(f"[dim]  consistency token: {escape(str(data['consistency_token']))}[/dim]")
 
 
-def _render_preview(data: dict[str, Any]) -> None:
+def _render_warnings(data: dict[str, Any]) -> None:
+    """A staging answer's or a preview page's `warnings` (since 0.15.0):
+    each companion put that keeps a stored `enrich` of on or off,
+    `{reason: "enrich_kept", path, kept}`, the first 256; absent when none.
+    Never a refusal: the change set stages and activates as it is."""
+    warnings = data.get("warnings") or []
+    for warning in warnings:
+        console.print(f"[warning]  {escape(warning_text(warning))}[/warning]")
+    if any(isinstance(w, dict) and w.get("reason") == "enrich_kept" for w in warnings):
+        console.print("[dim]  (a companion put that does not name enrich keeps the stored value; "
+                      "only enrich: inherit clears it)[/dim]")
+
+
+def render_preview(data: dict[str, Any]) -> None:
+    """A preview page: its access diff, its hash and, for a derivation change
+    set, its `derivation` section."""
     summary = data.get("summary") or {}
     kind = "widens" if data.get("widens") else ("narrows" if data.get("narrows") else "changes no access")
     console.print(f"[header]Preview[/header] {escape(str(data.get('id', '')))}: {kind}")
@@ -240,6 +304,8 @@ def _render_preview(data: dict[str, Any]) -> None:
     if data.get("stale_paths"):
         console.print(f"[warning]  changed since staging: {escape(', '.join(data['stale_paths']))}[/warning]")
     _render_in_band(data)
+    _render_derivation(data)
+    _render_warnings(data)
     if data.get("has_more"):
         console.print(f"[dim]  more on the next page - rerun with --cursor {escape(str(data.get('next_cursor')))}"
                       "[/dim]")
@@ -279,6 +345,90 @@ def _render_in_band(data: dict[str, Any]) -> None:
         console.print("[dim]  (the first 256 in-band records)[/dim]")
 
 
+def value_text(value: Any) -> str:
+    """A rule's value as text: a list comma-joined, `unset` for null."""
+    if value is None:
+        return "unset"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, list):
+        return ", ".join(value_text(item) for item in value) or "none"
+    if isinstance(value, dict):
+        if set(value) == {"label"}:
+            return f"label {value['label']}"
+        return json.dumps(value, sort_keys=True, default=str)
+    return str(value)
+
+
+def rule_change_text(change: dict[str, Any]) -> str:
+    """One rule a derivation change set moves: a list rule's `added` and
+    `removed` values, a scalar rule's `from` and `to`."""
+    rule = str(change.get("rule", ""))
+    if "added" in change or "removed" in change:
+        moved = []
+        if change.get("added"):
+            moved.append("+ " + value_text(change["added"]))
+        if change.get("removed"):
+            moved.append("- " + value_text(change["removed"]))
+        return f"{rule}: {'; '.join(moved) or 'unchanged'}"
+    return f"{rule}: {value_text(change.get('from'))} -> {value_text(change.get('to'))}"
+
+
+def text_summary(text: dict[str, Any]) -> str:
+    """A policy text a derivation change set names, as its preview lists it
+    (`sources` is a count there) or as `derivation texts` lists it (a list
+    of event ids)."""
+    if text.get("missing"):
+        return f"{text.get('id')}: missing (erased since it was named; resolution skips it)"
+    bits = [str(text.get("role") or "text")]
+    sources = text.get("sources")
+    count = len(sources) if isinstance(sources, list) else sources
+    if text.get("synthetic") is True:
+        bits.append("synthetic")
+    elif isinstance(count, int) and count:
+        bits.append(f"cites {count} event(s)")
+    if text.get("bytes") is not None:
+        bits.append(f"{text['bytes']} bytes")
+    return f"{text.get('id')}: {', '.join(bits)}"
+
+
+def _render_derivation(data: dict[str, Any]) -> None:
+    """A derivation change set's `derivation` section (`derivation_policy_v1`,
+    CortexDB 0.15.0): each derive record's own hash before and after, each
+    governed scope's effective policy hash before and after with the rules
+    that move, whether every record only tightens, the texts the records name
+    and the section's warnings. The approval binds it beside the structural
+    hash. An access change set's page has none."""
+    section = data.get("derivation")
+    if not isinstance(section, dict):
+        return
+    narrowing = ("narrowing: every record only tightens" if section.get("narrowing")
+                 else "not narrowing: a record loosens or steers")
+    console.print(f"[header]Derivation[/header] {narrowing}")
+    for record in section.get("records") or []:
+        before = record.get("before") or "no record"
+        after = record.get("after_hash") or "deleted"
+        console.print(f"  record {escape(str(record.get('path', '')))}: {escape(str(before))} -> "
+                      f"{escape(str(after))}")
+    for effective in section.get("effective") or []:
+        console.print(f"  effective at {escape(str(effective.get('scope', '')))}: "
+                      f"{escape(str(effective.get('before')))} -> {escape(str(effective.get('after')))}")
+        changes = effective.get("changes") or []
+        for change in changes:
+            console.print(f"    {escape(rule_change_text(change))}")
+        if not changes:
+            console.print("[dim]    no rule moves[/dim]")
+    for text in section.get("texts") or []:
+        style = "warning" if text.get("missing") else "dim"
+        console.print(f"[{style}]  text {escape(text_summary(text))}[/{style}]")
+    for warning in section.get("warnings") or []:
+        if isinstance(warning, dict) and warning.get("reason") == "text_missing":
+            console.print(f"[warning]  warning: text {escape(str(warning.get('id')))} is gone: the policy "
+                          "keeps its id and resolution skips it[/warning]")
+        else:
+            console.print(f"[warning]  warning: {escape(warning_text(warning))}[/warning]")
+
+
 def _id_path(change_id: str, suffix: str = "") -> str:
     return f"/v1/access/changes/{path_segment(change_id)}{suffix}"
 
@@ -292,6 +442,40 @@ def _params(proposer: str | None, scope: str | None = None) -> dict[str, str] |
     return params or None
 
 
+#: What a command whose staging's --wait ran out says to do next.
+STAGE_AGAIN = "Send the same `cortexdb changes stage` again for its status, or `cortexdb changes get` it."
+#: ... and one whose activation's --wait ran out.
+ACTIVATE_AGAIN = ("Its activation goes on in the background: `cortexdb changes get` shows its state, and "
+                  "the same `cortexdb changes activate --preview-hash` again answers its status.")
+
+
+def stage_change_set(cfg: dict[str, Any], client: Any, body: dict[str, Any],
+                     wait_s: float = DEFAULT_WAIT_S, again: str = STAGE_AGAIN) -> dict[str, Any]:
+    """POST /v1/access/changes with `body`, sent again while the server
+    answers an evaluation's 202; exits 75 when --wait runs out first."""
+    resp, waited = send_until_evaluated(cfg, "Staging...",
+                                        lambda: client.post("/v1/access/changes", json=body), wait_s)
+    if waited is not None:
+        still_evaluating(cfg, str(body.get("id", "")), "staging", waited, again)
+    return body_of(resp)
+
+
+def activate_change_set(cfg: dict[str, Any], client: Any, change_id: str, root: str, preview_hash: str,
+                        proposer: str | None = None, wait_s: float = DEFAULT_WAIT_S,
+                        again: str = ACTIVATE_AGAIN) -> dict[str, Any]:
+    """POST .../activate with the approved preview's hash, sent again while
+    the server answers an evaluation's 202 with no body (a dated change
+    set's 202 carries its status, and is its answer); exits 75 when --wait
+    runs out first."""
+    body = {"scope": root, "preview_hash": preview_hash}
+    resp, waited = send_until_evaluated(
+        cfg, "Activating...",
+        lambda: client.post(_id_path(change_id, "/activate"), json=body, params=_params(proposer)), wait_s)
+    if waited is not None:
+        still_evaluating(cfg, change_id, "activation", waited, again)
+    return body_of(resp)
+
+
 @changes_group.command("stage")
 @click.argument("change_id", metavar="ID")
 @_records_options
@@ -304,7 +488,7 @@ def _params(proposer: str | None, scope: str | None = None) -> dict[str, str] |
 @click.option("--convert", is_flag=True, help="A version-1 tree conversion: its preview must change no access.")
 @click.option("--resync", is_flag=True, help="A source's resync change set (served during a restore).")
 @click.option("--resync-last", is_flag=True, help="The last resync change set of the restore.")
-@_wait_option
+@wait_option
 @api_options
 @click.pass_context
 @handle_errors
@@ -345,12 +529,8 @@ def changes_stage(ctx, change_id, file, part, deletes, scope, parts_total, activ
     if resync or resync_last:
         body["resync"] = {"last": bool(resync_last)}
     with get_client(cfg) as client:
-        resp, waited = send_until_evaluated(cfg, "Staging...",
-                                            lambda: client.post("/v1/access/changes", json=body), wait_s)
-    if waited is not None:
-        still_evaluating(cfg, change_id, "staging", waited,
-                         "Send the same `cortexdb changes stage` again for its status, or `cortexdb changes get` it.")
-    emit(cfg, body_of(resp), _render_state)
+        data = stage_change_set(cfg, client, body, wait_s)
+    emit(cfg, data, render_state)
 
 
 @changes_group.command("parts")
@@ -358,7 +538,7 @@ def changes_stage(ctx, change_id, file, part, deletes, scope, parts_total, activ
 @_records_options
 @_scope_option
 @_proposer_option
-@_wait_option
+@wait_option
 @api_options
 @click.pass_context
 @handle_errors
@@ -378,11 +558,12 @@ def changes_parts(ctx, change_id, file, part, deletes, scope, proposer, wait_s):
     if waited is not None:
         still_evaluating(cfg, change_id, "staging of its parts", waited,
                          "Send the same `cortexdb changes parts` again for its status, or `cortexdb changes get` it.")
-    emit(cfg, body_of(resp), _render_state)
+    emit(cfg, body_of(resp), render_state)
 
 
 def preview_change_set(cfg, client, change_id, root, proposer=None, people=False, limit=None,
-                       cursor=None, wait_s=DEFAULT_WAIT_S):
+                       cursor=None, wait_s=DEFAULT_WAIT_S,
+                       again="Run the same `cortexdb changes preview` again to collect it."):
     """POST .../preview, sent again while the server answers 202
     `{state: "previewing"}`; exits 75 when --wait runs out first."""
     body: dict[str, Any] = {"scope": root}
@@ -396,8 +577,7 @@ def preview_change_set(cfg, client, change_id, root, proposer=None, people=False
         cfg, "Previewing...",
         lambda: client.post(_id_path(change_id, "/preview"), json=body, params=_params(proposer)), wait_s)
     if waited is not None:
-        still_evaluating(cfg, change_id, "preview", waited,
-                         "Run the same `cortexdb changes preview` again to collect it.")
+        still_evaluating(cfg, change_id, "preview", waited, again)
     return body_of(resp)
 
 
@@ -408,7 +588,7 @@ def preview_change_set(cfg, client, change_id, root, proposer=None, people=False
 @click.option("--people", is_flag=True, help="List each person who gains or loses access, per unit.")
 @click.option("--limit", type=click.IntRange(min=1), default=None, help="Units per page.")
 @click.option("--cursor", default=None, help="The next_cursor of a previous page.")
-@_wait_option
+@wait_option
 @api_options
 @click.pass_context
 @handle_errors
@@ -418,13 +598,17 @@ def changes_preview(ctx, change_id, scope, proposer, people, limit, cursor, wait
     A page holds at most 1 MiB: a unit that does not fit continues on the
     next page (--cursor), and its counts on this page are marked +. While
     the evaluation runs past the server's wait it answers 202
-    {state: previewing}; the CLI asks again until it answers (--wait).
+    {state: previewing}; the CLI asks again until it answers (--wait). A
+    derivation change set's page also has its derivation section: each
+    derive record's hash before and after, each governed scope's effective
+    policy hash before and after with the rules that move, and the texts
+    the records name.
     """
     cfg = ctx.obj
     with get_client(cfg) as client:
         data = preview_change_set(cfg, client, change_id, root_or_die(cfg, scope), proposer,
                                   people, limit, cursor, wait_s)
-    emit(cfg, data, _render_preview)
+    emit(cfg, data, render_preview)
 
 
 @changes_group.command("activate")
@@ -434,7 +618,7 @@ def changes_preview(ctx, change_id, scope, proposer, people, limit, cursor, wait
 @click.option("--preview-hash", metavar="HASH",
               help="The approved preview's hash (sha256:...). Without it the CLI previews first.")
 @click.option("--yes", "-y", is_flag=True, help="Skip the confirmation after the preview.")
-@_wait_option
+@wait_option
 @api_options
 @click.pass_context
 @handle_errors
@@ -465,21 +649,14 @@ def changes_activate(ctx, change_id, scope, proposer, preview_hash, yes, wait_s)
             if not preview_hash:
                 raise click.UsageError("the preview returned no preview_hash; pass --preview-hash")
             if not is_json_mode(cfg):
-                _render_preview(preview)
+                render_preview(preview)
                 if preview.get("in_band") and not cfg.get("break_glass"):
                     console.print("[warning]No --break-glass is set: under deny this activation will be "
                                   "refused (403 BREAK_GLASS_REQUIRED) and nothing activated.[/warning]")
                 if not yes:
                     click.confirm(f"Activate change set {change_id}?", abort=True)
-        body = {"scope": root, "preview_hash": preview_hash}
-        resp, waited = send_until_evaluated(
-            cfg, "Activating...",
-            lambda: client.post(_id_path(change_id, "/activate"), json=body, params=_params(proposer)), wait_s)
-    if waited is not None:
-        still_evaluating(cfg, change_id, "activation", waited,
-                         "Its activation goes on in the background: `cortexdb changes get` shows its state, and "
-                         "the same `cortexdb changes activate --preview-hash` again answers its status.")
-    emit(cfg, body_of(resp), _render_state)
+        data = activate_change_set(cfg, client, change_id, root, preview_hash, proposer, wait_s)
+    emit(cfg, data, render_state)
 
 
 @changes_group.command("get")
@@ -496,7 +673,7 @@ def changes_get(ctx, change_id, scope, proposer):
         data = body_of(send(cfg, "Loading...",
                             lambda: client.get(_id_path(change_id),
                                                params=_params(proposer, root_or_die(cfg, scope)))))
-    emit(cfg, data, _render_state)
+    emit(cfg, data, render_state)
 
 
 @changes_group.command("discard")
@@ -516,4 +693,4 @@ def changes_discard(ctx, change_id, scope, proposer, yes):
     with get_client(cfg) as client:
         data = body_of(send(cfg, "Discarding...",
                             lambda: client.delete(_id_path(change_id), params=_params(proposer, root))))
-    emit(cfg, data, _render_state)
+    emit(cfg, data, render_state)

cortexdb_cli/commands/conflicts.py

@@ -319,3 +319,9 @@ def conflicts_resolve(
     records = data.get("records") or []
     if records:
         console.print(_records_table(records))
+    # corrections_v1 (CortexDB 0.15.0): on a shard armed for format 11 a
+    # resolution is proposed as corrections, replicated to every node.
+    correction_ids = data.get("correction_ids") or []
+    if correction_ids:
+        console.print(f"[dim]Proposed as correction(s) {escape(', '.join(map(str, correction_ids)))}: "
+                      "`cortexdb corrections show SCOPE ID` shows one.[/dim]")