cortexdb-cli 0.5.3__tar.gz → 0.5.4__tar.gz

{cortexdb_cli-0.5.3 → cortexdb_cli-0.5.4}/.gitignore

@@ -1,101 +1,109 @@
-# Rust
-/target
-**/*.rs.bk
-
-# Environment / secrets
-.env
-.env.local
-.env*.local
-*.pem
-*.key
-.npmrc
-
-# SQLite database
-*.sqlite
-*.sqlite-wal
-*.sqlite-shm
-
-# OS
-.DS_Store
-Thumbs.db
-desktop.ini
-
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo
-
-# Data directories
-cortexdb_data*/
-/data/
-# Per-bench tenant stores (RocksDB + Tantivy + HNSW state; regeneratable per run)
-/data_*/
-# Experimental per-branch stores (not tracked on this branch but left gitignored
-# so checkout from other branches doesn't surface them in git status)
-/event_memory_store/
-/llm_cache/
-
-# Benchmark inputs and per-run outputs (kept local, regenerated each run)
-benchmarks/longmemeval/data/
-benchmarks/longmemeval/server_results/
-benchmarks/longmemeval/fast_results/
-benchmarks/longmemeval/micro_results/
-benchmarks/longmemeval/server_logs/
-benchmarks/longmemeval/*.log
-benchmarks/locomo/locomo_results*.json
-benchmarks/locomo/server_results/
-benchmarks/locomo/*.log
-/answer_out.json
-
-# Local Claude Code state
-.claude/
-.tmp/
-
-# Python
-__pycache__/
-*.pyc
-.venv/
-venv/
-
-# Node
-node_modules/
-dist/
-.next/
-
-# Egg info
-*.egg-info/
-
-# Scratch/debug text files at root
-/*.txt
-/*.log
-
-# Local debug / marketing / private content (not for repo)
-harness/.reports/
-harness_data_*/
-blog/
-sales/
-videos/
-local-instance/
-
-# doc-claims verifier scratch output
-tools/verifier_out*/
-
-# Generated benchmark / runtime data (audit M-10: hundreds of untracked
-# data dirs at the workspace root slow every git status/search and risk
-# being packaged; results JSONs are artifacts, never source)
-benchmarks/data_*/
-benchmarks/**/fast_results/
-data_*/
-*_data/
-*_data_20*/
-cortexdb_data*/
-server_results/
-*.log
-docker_build.log
-
-# local gate/bench data stores
-gate*_data_*/
-
-# Code-plane benchmark local run outputs (official results are committed deliberately)
-benchmarks/codeplane/runs/
+# Rust
+/target
+**/*.rs.bk
+
+# Environment / secrets
+.env
+.env.local
+.env*.local
+*.pem
+*.key
+.npmrc
+
+# SQLite database
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Data directories
+cortexdb_data*/
+/data/
+# Per-bench tenant stores (RocksDB + Tantivy + HNSW state; regeneratable per run)
+/data_*/
+# Experimental per-branch stores (not tracked on this branch but left gitignored
+# so checkout from other branches doesn't surface them in git status)
+/event_memory_store/
+/llm_cache/
+
+# Benchmark inputs and per-run outputs (kept local, regenerated each run)
+benchmarks/longmemeval/data/
+benchmarks/longmemeval/server_results/
+benchmarks/longmemeval/fast_results/
+benchmarks/longmemeval/micro_results/
+benchmarks/longmemeval/server_logs/
+benchmarks/longmemeval/*.log
+benchmarks/locomo/locomo_results*.json
+benchmarks/locomo/server_results/
+benchmarks/locomo/*.log
+/answer_out.json
+
+# Local Claude Code state
+.claude/
+.tmp/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# Node
+node_modules/
+dist/
+.next/
+
+# Egg info
+*.egg-info/
+
+# Scratch/debug text files at root
+/*.txt
+/*.log
+
+# Local debug / marketing / private content (not for repo)
+harness/.reports/
+harness_data_*/
+blog/
+sales/
+videos/
+local-instance/
+
+# doc-claims verifier scratch output
+tools/verifier_out*/
+
+# Generated benchmark / runtime data (audit M-10: hundreds of untracked
+# data dirs at the workspace root slow every git status/search and risk
+# being packaged; results JSONs are artifacts, never source)
+benchmarks/data_*/
+benchmarks/**/fast_results/
+data_*/
+*_data/
+*_data_20*/
+cortexdb_data*/
+server_results/
+*.log
+docker_build.log
+
+# local gate/bench data stores
+gate*_data_*/
+
+# Code-plane benchmark local run outputs (official results are committed deliberately)
+benchmarks/codeplane/runs/
+
+# Deliberately untracked, four times over: `git add docs/` keeps sweeping the
+# investor deck sources and the 2.7 MB OpenClaw design PDF back in (7dda2a51,
+# 3a778b5e, then again in the 2026-09-09 checkpoint). They live on disk; they do
+# not belong in the repo. Stage explicit paths, never a directory.
+docs/investor_deck/
+docs/CORTEX_OPENCLAW_AGENT_OS_DESIGN.md
+docs/CORTEX_OPENCLAW_AGENT_OS_DESIGN.pdf

{cortexdb_cli-0.5.3 → cortexdb_cli-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-cli
-Version: 0.5.3
+Version: 0.5.4
 Summary: Command-line interface for CortexDB — the long-term memory layer for AI.
 Project-URL: Homepage, https://cortexdb.ai
 Project-URL: Documentation, https://cortexdb.ai/docs

{cortexdb_cli-0.5.3 → cortexdb_cli-0.5.4}/cortexdb_cli/__init__.py

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

{cortexdb_cli-0.5.3 → cortexdb_cli-0.5.4}/cortexdb_cli/client.py

@@ -63,6 +63,14 @@ class CortexClient:
     ) -> httpx.Response:
         return self._http.post(path, json=json, params=params)
 
+    def put(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        return self._http.put(path, json=json, params=params)
+
     def delete(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
         return self._http.delete(path, params=params)
 

cortexdb_cli-0.5.4/cortexdb_cli/commands/admin.py

@@ -0,0 +1,612 @@
+"""cortexdb admin - health, usage, layer stats, retention, unified WAL."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import (
+    console,
+    escape,
+    is_json_mode,
+    print_health,
+    print_json,
+    print_ontology,
+    print_success,
+    print_usage,
+    spinner,
+)
+
+
+@click.group("admin")
+def admin_group() -> None:
+    """Diagnostics - reachability, identity, rate-limit, layer status."""
+
+
+@admin_group.command("health")
+@click.pass_context
+@handle_errors
+def admin_health(ctx: click.Context) -> None:
+    """Auth + reachability check (GET /v1/auth/whoami)."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        # Normalise into the shape print_health expects.
+        body.setdefault("status", "ok")
+        print_health(body, cfg)
+
+
+@admin_group.command("usage")
+@click.pass_context
+@handle_errors
+def admin_usage(ctx: click.Context) -> None:
+    """Tier, capabilities, rate-limit headroom, token expiry."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading usage..."):
+                resp = client.get("/v1/auth/whoami")
+        else:
+            resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        # Fold rate-limit + expiry response headers into the body so the
+        # output formatter can render them in one block.
+        for k in (
+            "X-RateLimit-Limit",
+            "X-RateLimit-Reset",
+            "X-RateLimit-Remaining",
+            "X-Cortex-Token-Expires-In",
+            "X-Cortex-Token-Expires-At",
+        ):
+            if k in resp.headers:
+                body[k] = resp.headers[k]
+        print_usage(body, cfg)
+
+
+@admin_group.command("layers")
+@click.pass_context
+@handle_errors
+def admin_layers(ctx: click.Context) -> None:
+    """Per-layer counts and synthesis lag (GET /v1/admin/layers/stats).
+
+    Stability: experimental - the endpoint is gated by the
+    `admin.layers.stats` capability and may not be present on the free tier.
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading layer stats..."):
+                resp = client.get("/v1/admin/layers/stats")
+        else:
+            resp = client.get("/v1/admin/layers/stats")
+        resp.raise_for_status()
+        print_ontology(resp.json(), cfg)
+
+
+# -- retention (unified WAL) -------------------------------------------------
+#
+# The operator surface over the D1 retention plane. Every write here is
+# irreversible in effect - an applied sweep ERASES expired captured events
+# through the ordinary erasure plane - so reporting is the default on both
+# mutating commands and `--apply` is the only thing that sends
+# `dry_run: false`.
+
+
+def _parse_source_days(pairs: tuple[str, ...]) -> dict[str, int]:
+    """Parse repeated ``--source-days KEY=N`` options into the wire map.
+
+    Only the option's own grammar is checked here (KEY=VALUE, N a positive
+    integer). The ``source:`` prefix rule and the 1..=36500 ceiling belong to
+    the server's governance validator, which answers 422
+    INVALID_RETENTION_POLICY - duplicating them here would let the CLI and
+    the server disagree about what a valid rule is.
+    """
+    out: dict[str, int] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise click.UsageError(f"--source-days must be KEY=DAYS, got {pair!r}")
+        key, raw = pair.split("=", 1)
+        key = key.strip()
+        if not key:
+            raise click.UsageError(f"--source-days needs a key, got {pair!r}")
+        try:
+            days = int(raw)
+        except ValueError:
+            raise click.UsageError(
+                f"--source-days value must be a whole number of days, got {raw!r}"
+            ) from None
+        if days < 1:
+            raise click.UsageError(
+                f"--source-days must be at least 1 day, got {days} for {key!r}"
+            )
+        if key in out:
+            raise click.UsageError(f"--source-days {key!r} given twice")
+        out[key] = days
+    return out
+
+
+def _print_retention_status(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render GET /v1/admin/retention."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.table import Table
+
+    config = Table(title="[header]Retention[/header]", border_style="cyan")
+    config.add_column("Setting", style="bold")
+    config.add_column("Value")
+    interval = data.get("sweep_interval_secs", 0)
+    if data.get("enabled"):
+        scheduled = "yes"
+    elif data.get("scheduler_disabled"):
+        scheduled = "[warning]no (CORTEX_SCHEDULER_DISABLE)[/warning]"
+    else:
+        scheduled = "no (operator-triggered only)"
+    config.add_row("scheduled", scheduled)
+    config.add_row("sweep interval", f"{interval}s" if interval else "-")
+    default_days = data.get("deployment_default_days")
+    config.add_row("deployment default", f"{default_days}d" if default_days else "keep")
+    config.add_row("max events/tick", str(data.get("max_events_per_tick", "")))
+    config.add_row("tick budget", str(data.get("tick_budget_secs", "")) + "s")
+    config.add_row(
+        "compact after sweep", "yes" if data.get("compact_after_sweep") else "no"
+    )
+    config.add_row("cursor", str(data.get("cursor", "")))
+    config.add_row("watermark", str(data.get("watermark", "")))
+    config.add_row(
+        "cursor trustworthy",
+        "yes" if data.get("fingerprint_ok") else "no (next applied tick rescans)",
+    )
+    config.add_row("running", "yes" if data.get("running") else "no")
+    if data.get("native_profile_blocked"):
+        config.add_row("native profile", "[warning]retention refused[/warning]")
+    console.print(config)
+
+    policies = data.get("policies") or []
+    if policies:
+        table = Table(title="[header]Policies[/header]", border_style="cyan")
+        table.add_column("Scope", style="bold")
+        table.add_column("Default", justify="right")
+        table.add_column("Per-source", style="dim")
+        for entry in policies:
+            policy = entry.get("policy") or {}
+            days = policy.get("default_retention_days")
+            per_source = policy.get("per_source_days") or {}
+            table.add_row(
+                escape(str(entry.get("scope", ""))),
+                f"{days}d" if days else "keep",
+                escape(", ".join(f"{k}={v}d" for k, v in sorted(per_source.items()))),
+            )
+        console.print(table)
+    else:
+        console.print("[dim]No per-scope retention rules stored.[/dim]")
+
+    last = data.get("last")
+    if isinstance(last, dict):
+        note = " [warning](dry run)[/warning]" if last.get("dry_run") else ""
+        console.print(
+            "[dim]Last tick:[/dim] "
+            f"scanned {last.get('scanned', 0)}, "
+            f"expired {last.get('expired', 0)}, "
+            f"erased {last.get('erased', 0)}, "
+            f"stopped {escape(str(last.get('stopped', '')))}" + note
+        )
+
+
+def _print_sweep_report(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render POST /v1/admin/retention/sweep (or its 202 still-running body)."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.panel import Panel
+
+    if "erased" not in data:
+        # 202: the tick outlived the blocking-lane deadline and is still going.
+        poll = escape(str(data.get("poll", "/v1/admin/retention")))
+        console.print(
+            Panel(
+                f"Sweep still running; poll [bold]{poll}[/bold]",
+                title="[header]Retention sweep[/header]",
+                border_style="yellow",
+            )
+        )
+        return
+
+    dry = data.get("dry_run", True)
+    lines = [
+        f"scanned [bold]{data.get('scanned', 0)}[/bold] captured row(s)",
+        f"expired [bold]{data.get('expired', 0)}[/bold], "
+        f"erased [bold]{data.get('erased', 0)}[/bold], "
+        f"kept forever [bold]{data.get('kept_forever', 0)}[/bold]",
+        f"cursor {data.get('cursor_before', 0)} -> {data.get('cursor_after', 0)} "
+        f"(watermark {data.get('watermark', 0)})",
+        f"stopped: {escape(str(data.get('stopped', '')))} "
+        f"in {data.get('elapsed_ms', 0)}ms",
+    ]
+    held = data.get("held") or {}
+    if isinstance(held, dict) and any(held.values()):
+        lines.append(f"[dim]held: {escape(str(held))}[/dim]")
+    for error in data.get("errors") or []:
+        lines.append(f"[error]{escape(str(error))}[/error]")
+    title = "[header]Retention sweep" + (" (dry run)" if dry else " (APPLIED)")
+    console.print(
+        Panel(
+            "\n".join(lines),
+            title=title + "[/header]",
+            border_style="yellow" if dry else "red",
+        )
+    )
+
+
+def _print_wal_status(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render GET /v1/admin/wal."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.table import Table
+
+    table = Table(title="[header]Unified WAL[/header]", border_style="cyan")
+    table.add_column("Field", style="bold")
+    table.add_column("Value", justify="right")
+    for label, key in (
+        ("live rows", "live_count"),
+        ("next offset", "next_offset"),
+        ("head offset", "head_offset"),
+        ("captured head", "captured_head_offset"),
+        ("partitions", "partitions"),
+        ("retired markers", "retired_marker_count"),
+    ):
+        value = data.get(key)
+        table.add_row(label, "-" if value is None else str(value))
+    if data.get("native_profile_blocked"):
+        table.add_row("native profile", "[warning]mutations refused[/warning]")
+    console.print(table)
+
+    consumers = data.get("consumer_offsets") or {}
+    if consumers:
+        floors = Table(title="[header]Consumer floors[/header]", border_style="cyan")
+        floors.add_column("Consumer", style="bold")
+        floors.add_column("Offset", justify="right")
+        for name, offset in sorted(consumers.items()):
+            floors.add_row(escape(str(name)), str(offset))
+        console.print(floors)
+
+    verify = data.get("verify")
+    if isinstance(verify, dict):
+        ok = verify.get("ok")
+        if ok is None:
+            # Not a verdict: the self-check is bounded and a production-sized
+            # log is past that bound, so nothing was checked. Rendering this
+            # as a failure is how a healthy store gets restored from backup.
+            skipped = escape(
+                str(verify.get("skipped", "log exceeds the bounded self-check"))
+            )
+            console.print(f"[warning]Integrity check not run:[/warning] {skipped}")
+        elif ok:
+            console.print("[success]Integrity check passed.[/success]")
+        else:
+            reason = escape(str(verify.get("reason", "unknown")))
+            console.print(f"[error]Integrity check failed:[/error] {reason}")
+
+
+def _print_compaction(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render POST /v1/admin/wal/compact (or its 202 still-running body)."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.panel import Panel
+
+    if "removed_tombstones" not in data:
+        poll = escape(str(data.get("poll", "/v1/admin/wal")))
+        console.print(
+            Panel(
+                f"Compaction still running; poll [bold]{poll}[/bold]",
+                title="[header]WAL compaction[/header]",
+                border_style="yellow",
+            )
+        )
+        return
+
+    dry = data.get("dry_run", True)
+    lines = [
+        f"scanned [bold]{data.get('scanned', 0)}[/bold] row(s)",
+        f"removed {data.get('removed_tombstones', 0)} tombstone(s), "
+        f"{data.get('removed_orphaned_twins', 0)} orphaned twin(s)",
+        f"skipped {data.get('skipped_in_use', 0)} in use, "
+        f"{data.get('skipped_above_bound', 0)} above the bound",
+        f"live rows {data.get('live_count_before', 0)} -> "
+        f"{data.get('live_count_after', 0)}, "
+        f"{data.get('bytes_removed', 0)} byte(s) reclaimed",
+        f"ranges compacted: {data.get('ranges_compacted', 0)} "
+        f"in {data.get('elapsed_ms', 0)}ms",
+    ]
+    if data.get("truncated_by_budget"):
+        lines.append("[warning]Budget reached - rerun to continue.[/warning]")
+    title = "[header]WAL compaction" + (" (dry run)" if dry else " (APPLIED)")
+    console.print(
+        Panel(
+            "\n".join(lines),
+            title=title + "[/header]",
+            border_style="yellow" if dry else "red",
+        )
+    )
+
+
+@admin_group.group("retention")
+def retention_group() -> None:
+    """Unified-WAL retention - per-scope rules and the expiry sweep.
+
+    Requires trusted-operator access. Reporting needs `diagnostics.read`;
+    storing a rule or applying a sweep needs `admin.compact`.
+    """
+
+
+@retention_group.command("show")
+@click.pass_context
+@handle_errors
+def retention_show(ctx: click.Context) -> None:
+    """Config, stored rules, cursor and last tick (GET /v1/admin/retention).
+
+    503 NOT_AVAILABLE when this process runs no retention sweeper (legacy
+    WAL, no coordinator, or a configuration the sweeper refused).
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading retention status..."):
+                resp = client.get("/v1/admin/retention")
+        else:
+            resp = client.get("/v1/admin/retention")
+        resp.raise_for_status()
+        _print_retention_status(resp.json(), cfg)
+
+
+@retention_group.command("set")
+@click.option("--scope", "-S", required=True, help="Scope path the rule is keyed on.")
+@click.option(
+    "--days",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Expire captured events after this many days. Omit for an explicit KEEP.",
+)
+@click.option(
+    "--source-days",
+    "source_days",
+    multiple=True,
+    metavar="KEY=DAYS",
+    help="Per-source override, e.g. source:slack=30. Repeatable.",
+)
+@click.pass_context
+@handle_errors
+def retention_set(
+    ctx: click.Context,
+    scope: str,
+    days: int | None,
+    source_days: tuple[str, ...],
+) -> None:
+    """Store the retention rule for one scope (PUT /v1/admin/retention/policies).
+
+    Irreversible in effect: an applied sweep under this rule ERASES expired
+    events from the scope and every scope beneath it. Omitting `--days`
+    stores an explicit KEEP, which overrides the deployment default for the
+    subtree but never a shorter rule inherited from an ancestor scope.
+    Storing a rule always resets the durable sweep cursor.
+    """
+    cfg = ctx.obj
+    body: dict[str, Any] = {"scope": scope, "default_retention_days": days}
+    per_source = _parse_source_days(source_days)
+    if per_source:
+        body["per_source_days"] = per_source
+    with get_client(cfg) as client:
+        resp = client.put("/v1/admin/retention/policies", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+    policy = data.get("policy") or {}
+    stored = policy.get("default_retention_days")
+    reset = " (sweep cursor reset)" if data.get("cursor_reset") else ""
+    print_success(
+        f"Retention rule stored for {scope}: "
+        + (f"{stored} day(s)" if stored else "keep")
+        + reset
+    )
+
+
+@retention_group.command("delete")
+@click.option("--scope", "-S", required=True, help="Scope path whose rule to remove.")
+@click.pass_context
+@handle_errors
+def retention_delete(ctx: click.Context, scope: str) -> None:
+    """Remove one scope's rule (DELETE /v1/admin/retention/policies).
+
+    404 when a well-formed store held no rule for exactly this scope -
+    inheritance is resolution, not storage, so a descendant that expires by
+    an ancestor's rule has no rule of its own to delete. Resets the durable
+    sweep cursor, like `set`.
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.delete("/v1/admin/retention/policies", params={"scope": scope})
+        resp.raise_for_status()
+    if is_json_mode(cfg):
+        print_json({"scope": scope, "deleted": True, "cursor_reset": True})
+        return
+    print_success(f"Retention rule removed for {scope} (sweep cursor reset)")
+
+
+@retention_group.command("sweep")
+@click.option(
+    "--apply",
+    "apply_",
+    is_flag=True,
+    default=False,
+    help="ERASE expired events. Without it the tick only reports.",
+)
+@click.option("--scope", "-S", default=None, help="Confine the scan to this subtree.")
+@click.option(
+    "--older-than-secs",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Request-only TTL override for --scope. Never persisted.",
+)
+@click.option(
+    "--max-events",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Override the per-tick expiry budget.",
+)
+@click.option(
+    "--rescan",
+    is_flag=True,
+    default=False,
+    help="Ignore the durable cursor and scan from the start of the log.",
+)
+@click.pass_context
+@handle_errors
+def retention_sweep(
+    ctx: click.Context,
+    apply_: bool,
+    scope: str | None,
+    older_than_secs: int | None,
+    max_events: int | None,
+    rescan: bool,
+) -> None:
+    """Run one retention tick (POST /v1/admin/retention/sweep).
+
+    DRY RUN IS THE DEFAULT - the tick reports what would be erased and
+    writes nothing. `--apply` is what sends `dry_run: false`, which erases
+    expired captured events irreversibly and needs `admin.compact`.
+
+    Single-flight: a second concurrent tick is refused with 409
+    RETENTION_SWEEP_RUNNING rather than queued.
+    """
+    cfg = ctx.obj
+    if older_than_secs is not None and not scope:
+        raise click.UsageError("--older-than-secs requires --scope.")
+    body: dict[str, Any] = {"dry_run": not apply_}
+    if scope:
+        body["scope"] = scope
+    if older_than_secs is not None:
+        body["older_than_secs"] = older_than_secs
+    if max_events is not None:
+        body["max_events"] = max_events
+    if rescan:
+        body["rescan"] = True
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Sweeping..."):
+                resp = client.post("/v1/admin/retention/sweep", json=body)
+        else:
+            resp = client.post("/v1/admin/retention/sweep", json=body)
+        resp.raise_for_status()
+        _print_sweep_report(resp.json(), cfg)
+
+
+@admin_group.group("wal")
+def wal_group() -> None:
+    """Unified write-ahead log - census and dead-row compaction.
+
+    Requires trusted-operator access. A legacy data dir is refused with 409
+    RETENTION_UNSUPPORTED_BACKEND naming the offline migrator.
+    """
+
+
+@wal_group.command("status")
+@click.option(
+    "--verify",
+    is_flag=True,
+    default=False,
+    help=(
+        "Also run the bounded row-level self-check (clamped server-side). "
+        "The check is bounded at 1M rows / 512 MiB, which a production-sized "
+        "log exceeds: it then reports 'not run', which is not a failure."
+    ),
+)
+@click.pass_context
+@handle_errors
+def wal_status(ctx: click.Context, verify: bool) -> None:
+    """Live rows, offsets, consumer floors, markers (GET /v1/admin/wal)."""
+    cfg = ctx.obj
+    params = {"verify": "true"} if verify else None
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading WAL census..."):
+                resp = client.get("/v1/admin/wal", params=params)
+        else:
+            resp = client.get("/v1/admin/wal", params=params)
+        resp.raise_for_status()
+        _print_wal_status(resp.json(), cfg)
+
+
+@wal_group.command("compact")
+@click.option(
+    "--apply",
+    "apply_",
+    is_flag=True,
+    default=False,
+    help="Physically remove the dead rows. Without it the run only reports.",
+)
+@click.option(
+    "--max-rows",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Upper bound on dead rows removed in one sweep.",
+)
+@click.option(
+    "--below-offset",
+    type=click.IntRange(min=0),
+    default=None,
+    help="Exclusive offset bound. Defaults to the indexer watermark.",
+)
+@click.option(
+    "--compaction",
+    type=click.Choice(["none", "touched_ranges", "full"]),
+    default=None,
+    help="Physical reclamation mode. `full` is a whole-CF compaction.",
+)
+@click.pass_context
+@handle_errors
+def wal_compact(
+    ctx: click.Context,
+    apply_: bool,
+    max_rows: int | None,
+    below_offset: int | None,
+    compaction: str | None,
+) -> None:
+    """Reclaim already-dead WAL rows (POST /v1/admin/wal/compact).
+
+    Removes only rows that are ALREADY logically dead - redaction
+    tombstones and orphaned Derived twins. It never removes a live row and
+    never touches derived-artifact history.
+
+    DRY RUN IS THE DEFAULT; `--apply` is what sends `dry_run: false` and
+    needs `admin.compact`. Single-flight: 409 WAL_COMPACTION_RUNNING.
+    """
+    cfg = ctx.obj
+    body: dict[str, Any] = {"dry_run": not apply_}
+    if max_rows is not None:
+        body["max_rows"] = max_rows
+    if below_offset is not None:
+        body["below_offset"] = below_offset
+    if compaction is not None:
+        body["compaction"] = compaction
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Compacting..."):
+                resp = client.post("/v1/admin/wal/compact", json=body)
+        else:
+            resp = client.post("/v1/admin/wal/compact", json=body)
+        resp.raise_for_status()
+        _print_compaction(resp.json(), cfg)

{cortexdb_cli-0.5.3 → cortexdb_cli-0.5.4}/cortexdb_cli/commands/code.py

@@ -36,25 +36,81 @@ def _echo(cfg, payload) -> None:
 @code_group.command("add")
 @click.argument("name")
 @click.argument("path", type=click.Path(exists=True, file_okay=False))
+@click.option(
+    "--scope",
+    default=None,
+    help=(
+        "Parent scope the repository binds under (default: the tenant "
+        "root org:<billing id>). Every later read or mutation is "
+        "authorized against that binding."
+    ),
+)
 @click.pass_context
 @handle_errors
-def code_add(ctx: click.Context, name: str, path: str) -> None:
+def code_add(ctx: click.Context, name: str, path: str, scope: str | None) -> None:
     """Register + index a local repository (POST /v1/code/repos).
 
     NAME is the repo handle used by every other verb; PATH is the local
     checkout. Indexing runs synchronously and reports the fact counts.
+
+    --scope binds the repository under a scope you already own; the
+    server appends a stable ``repo:<dirname>-<digest>`` segment and the
+    response reports the resulting binding. A scope that does not parse,
+    or a ``global:`` one, is refused 422 INVALID_SCOPE; one you may not
+    register under is 403 POLICY_DENIED.
     """
     cfg = ctx.obj
     absolute = str(pathlib.Path(path).resolve())
+    body: dict = {"name": name, "path": absolute}
+    if scope is not None:
+        body["scope"] = scope
     with get_client(cfg) as client:
         with spinner(f"Indexing {name}..."):
-            resp = client.post(
-                "/v1/code/repos", json={"name": name, "path": absolute}
-            )
+            resp = client.post("/v1/code/repos", json=body)
         resp.raise_for_status()
         _echo(cfg, resp.json())
 
 
+@code_group.command("remove")
+@click.argument("name")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.pass_context
+@handle_errors
+def code_remove(ctx: click.Context, name: str, yes: bool) -> None:
+    """De-register a repository AND free its bytes (DELETE
+    /v1/code/repos/NAME).
+
+    Prints the purge report: the directory that was removed, how many
+    bytes it held, and whether the registry journal was compacted (a
+    false there means the bytes are gone but the journal still names the
+    checkout path; removing the same name again retries it).
+
+    503 REPO_PURGE_BUSY means the repository is ALREADY de-registered but
+    readers still hold its stores open - run the same command again to
+    finish freeing the directory.
+    """
+    cfg = ctx.obj
+    if not yes and not is_json_mode(cfg):
+        click.confirm(
+            f"Remove repository {name} and delete its indexed data?", abort=True
+        )
+    with get_client(cfg) as client:
+        with spinner(f"Purging {name}..."):
+            resp = client.delete(f"/v1/code/repos/{name}")
+        resp.raise_for_status()
+        body = resp.json()
+    if is_json_mode(cfg):
+        _echo(cfg, body)
+        return
+    purge = body.get("purge") or {}
+    click.echo(f"Removed {body.get('removed', name)}")
+    click.echo(f"  scope:      {purge.get('scope', '')}")
+    click.echo(f"  directory:  {purge.get('directory', '')}")
+    click.echo(f"  freed:      {purge.get('bytes_freed', 0)} bytes")
+    compacted = "compacted" if purge.get("registry_compacted") else "NOT compacted"
+    click.echo(f"  registry:   {compacted}")
+
+
 @code_group.command("status")
 @click.argument("name", required=False)
 @click.pass_context

{cortexdb_cli-0.5.3 → cortexdb_cli-0.5.4}/pyproject.toml

@@ -1,56 +1,56 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "cortexdb-cli"
-version = "0.5.3"
-description = "Command-line interface for CortexDB — the long-term memory layer for AI."
-readme = "README.md"
-license = "Apache-2.0"
-requires-python = ">=3.10"
-authors = [
-    { name = "CortexDB Team", email = "team@cortexdb.ai" },
-]
-keywords = ["ai", "memory", "cli", "cortexdb", "agents", "llm"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Environment :: Console",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: Apache Software License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Topic :: Scientific/Engineering :: Artificial Intelligence",
-    "Topic :: Database",
-]
-dependencies = [
-    "click>=8.1",
-    "rich>=13.0",
-    "rich-click>=1.7",
-    "httpx>=0.27",
-    "prompt-toolkit>=3.0",
-    "tomli>=2.0; python_version < '3.11'",
-    "tomli-w>=1.0",
-]
-
-[project.scripts]
-cortexdb = "cortexdb_cli.main:cli"
-
-[project.urls]
-Homepage = "https://cortexdb.ai"
-Documentation = "https://cortexdb.ai/docs"
-Repository = "https://github.com/cortexdb/cortexdb"
-Issues = "https://github.com/cortexdb/cortexdb/issues"
-
-[tool.hatch.build.targets.wheel]
-packages = ["cortexdb_cli"]
-
-[tool.hatch.build.targets.sdist]
-include = ["cortexdb_cli", "README.md", "LICENSE"]
-
-[tool.ruff]
-target-version = "py310"
-line-length = 100
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cortexdb-cli"
+version = "0.5.4"
+description = "Command-line interface for CortexDB — the long-term memory layer for AI."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "CortexDB Team", email = "team@cortexdb.ai" },
+]
+keywords = ["ai", "memory", "cli", "cortexdb", "agents", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Database",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "rich-click>=1.7",
+    "httpx>=0.27",
+    "prompt-toolkit>=3.0",
+    "tomli>=2.0; python_version < '3.11'",
+    "tomli-w>=1.0",
+]
+
+[project.scripts]
+cortexdb = "cortexdb_cli.main:cli"
+
+[project.urls]
+Homepage = "https://cortexdb.ai"
+Documentation = "https://cortexdb.ai/docs"
+Repository = "https://github.com/cortexdb/cortexdb"
+Issues = "https://github.com/cortexdb/cortexdb/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cortexdb_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["cortexdb_cli", "README.md", "LICENSE"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100

cortexdb_cli-0.5.3/cortexdb_cli/commands/admin.py

@@ -1,83 +0,0 @@
-"""cortexdb admin - health, usage, layer stats."""
-
-from __future__ import annotations
-
-import click
-
-from cortexdb_cli.client import get_client
-from cortexdb_cli.errors import handle_errors
-from cortexdb_cli.output import (
-    is_json_mode,
-    print_health,
-    print_ontology,
-    print_usage,
-    spinner,
-)
-
-
-@click.group("admin")
-def admin_group() -> None:
-    """Diagnostics - reachability, identity, rate-limit, layer status."""
-
-
-@admin_group.command("health")
-@click.pass_context
-@handle_errors
-def admin_health(ctx: click.Context) -> None:
-    """Auth + reachability check (GET /v1/auth/whoami)."""
-    cfg = ctx.obj
-    with get_client(cfg) as client:
-        resp = client.get("/v1/auth/whoami")
-        resp.raise_for_status()
-        body = resp.json()
-        # Normalise into the shape print_health expects.
-        body.setdefault("status", "ok")
-        print_health(body, cfg)
-
-
-@admin_group.command("usage")
-@click.pass_context
-@handle_errors
-def admin_usage(ctx: click.Context) -> None:
-    """Tier, capabilities, rate-limit headroom, token expiry."""
-    cfg = ctx.obj
-    with get_client(cfg) as client:
-        if not is_json_mode(cfg):
-            with spinner("Loading usage..."):
-                resp = client.get("/v1/auth/whoami")
-        else:
-            resp = client.get("/v1/auth/whoami")
-        resp.raise_for_status()
-        body = resp.json()
-        # Fold rate-limit + expiry response headers into the body so the
-        # output formatter can render them in one block.
-        for k in (
-            "X-RateLimit-Limit",
-            "X-RateLimit-Reset",
-            "X-RateLimit-Remaining",
-            "X-Cortex-Token-Expires-In",
-            "X-Cortex-Token-Expires-At",
-        ):
-            if k in resp.headers:
-                body[k] = resp.headers[k]
-        print_usage(body, cfg)
-
-
-@admin_group.command("layers")
-@click.pass_context
-@handle_errors
-def admin_layers(ctx: click.Context) -> None:
-    """Per-layer counts and synthesis lag (GET /v1/admin/layers/stats).
-
-    Stability: experimental - the endpoint is gated by the
-    `admin.layers.stats` capability and may not be present on the free tier.
-    """
-    cfg = ctx.obj
-    with get_client(cfg) as client:
-        if not is_json_mode(cfg):
-            with spinner("Loading layer stats..."):
-                resp = client.get("/v1/admin/layers/stats")
-        else:
-            resp = client.get("/v1/admin/layers/stats")
-        resp.raise_for_status()
-        print_ontology(resp.json(), cfg)