core-runtime 0.1.1__py3-none-any.whl

cli/resources/coherence/check.py

@@ -0,0 +1,111 @@
+# src/cli/resources/coherence/check.py
+"""
+`core-admin coherence check` — trigger a Constitutional Coherence Checker run.
+
+Governing ADR: .specs/decisions/ADR-067-constitutional-coherence-checker.md (D2).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+from rich.console import Console
+
+from body.services.coherence_service import CoherenceService
+from body.services.governance_claims_service import GovernanceClaimsService
+from cli.utils import core_command
+from mind.coherence.checker import CoherenceChecker
+from shared.config import settings
+from shared.context import CoreContext
+from shared.infrastructure.database.session_manager import get_session
+
+from .hub import app
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+@app.command("check")
+@core_command(dangerous=True, requires_context=True)
+# ID: 02507f9f-3bdc-41d8-b9af-982b0411ce37
+async def check_command(
+    ctx: typer.Context,
+    full: bool = typer.Option(
+        False,
+        "--full",
+        help=(
+            "Evaluate the full corpus regardless of prior runs. Required for "
+            "the first run on any installation. Without --full, trigger is "
+            "auto-detected from the previous run's input_manifest."
+        ),
+    ),
+    sample: int = typer.Option(
+        None,
+        "--sample",
+        help=(
+            "Randomly sample N rule files for R2/R3 (R1 still scans all "
+            "ADRs). Use for narrow exploratory runs. Omit to evaluate all "
+            "rule files."
+        ),
+    ),
+) -> None:
+    """Run one Constitutional Coherence Checker pass — 7 check classes per ADR-073."""
+    context: CoreContext = ctx.obj
+    try:
+        cognitive_service = await context.registry.get_cognitive_service()
+    except Exception as exc:
+        logger.exception("Failed to acquire CognitiveService")
+        console.print(f"[red]❌ Cognitive service unavailable: {exc}[/red]")
+        raise typer.Exit(code=1) from exc
+
+    claims_service: GovernanceClaimsService | None = None
+    try:
+        qdrant = await context.registry.get_qdrant_service()
+        claims_service = GovernanceClaimsService(qdrant)
+    except Exception as exc:
+        logger.warning("Qdrant unavailable; SAMECONCERN/R1_SCOPED will skip (%s)", exc)
+
+    async with get_session() as session:
+        coherence_service = CoherenceService(session)
+        checker = CoherenceChecker(
+            cognitive_service=cognitive_service,
+            coherence_service=coherence_service,
+            repo_root=settings.REPO_PATH,
+            claims_service=claims_service,
+        )
+
+        console.print("[cyan]Starting coherence run…[/cyan]")
+        try:
+            run_id = await checker.run(full=full, sample_rules=sample)
+        except Exception as exc:
+            logger.exception("Coherence run failed")
+            console.print(f"[red]❌ Coherence run failed: {exc}[/red]")
+            raise typer.Exit(code=1) from exc
+
+        console.print(f"Run started: {run_id}")
+
+        run = await coherence_service.get_run(run_id)
+
+    if run is None:
+        console.print("[yellow]Run row not found after completion.[/yellow]")
+        raise typer.Exit(code=1)
+
+    manifest = run.get("input_manifest") or []
+    checked = sum(1 for e in manifest if e.get("status") == "checked")
+    skipped = sum(1 for e in manifest if e.get("status") == "skipped")
+    candidates = int(run.get("candidate_count") or 0)
+
+    console.print(
+        f"[green]Coverage:[/green] {checked} checked, {skipped} skipped "
+        f"· [bold]Candidates:[/bold] {candidates} produced"
+    )
+
+    total = checked + skipped
+    if total > 0 and skipped / total > 0.20:
+        console.print(
+            f"[yellow]⚠ WARNING: {skipped}/{total} input items skipped "
+            f"({skipped / total:.0%}). See `core-admin coherence report` for "
+            f"per-item skipped_reason.[/yellow]"
+        )

cli/resources/coherence/hub.py

@@ -0,0 +1,13 @@
+# src/cli/resources/coherence/hub.py
+import typer
+
+
+app = typer.Typer(
+    name="coherence",
+    help=(
+        "Constitutional Coherence Checker — scan ADRs, rule domains, and "
+        "northstar documents for candidate contradictions, gaps, and drift. "
+        "Governing ADR: ADR-067."
+    ),
+    no_args_is_help=True,
+)

cli/resources/coherence/repair_counts.py

@@ -0,0 +1,73 @@
+# src/cli/resources/coherence/repair_counts.py
+"""
+`core-admin coherence repair-counts` — recompute the denormalized
+``unreviewed_count`` on every open coherence run from live candidate state.
+
+Governing ADR: .specs/decisions/ADR-067-constitutional-coherence-checker.md (D6).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from body.services.coherence_service import CoherenceService
+from cli.utils import core_command
+from shared.infrastructure.database.session_manager import get_session
+
+from .hub import app
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+@app.command("repair-counts")
+@core_command(dangerous=True, requires_context=False)
+# ID: a7f3ef25-a40c-46b9-8f6a-029acb69ffab
+async def repair_counts_command() -> None:
+    """Recompute unreviewed_count from live triage state across all open runs."""
+    async with get_session() as session:
+        service = CoherenceService(session)
+        try:
+            deltas = await service.repair_unreviewed_counts()
+        except Exception as exc:
+            logger.exception("repair-counts failed")
+            console.print(f"[red]X repair-counts failed: {exc}[/red]")
+            raise typer.Exit(code=1) from exc
+
+    if not deltas:
+        console.print("[green]No open runs — nothing to repair.[/green]")
+        return
+
+    table = Table(title="Coherence repair-counts — per-run delta")
+    table.add_column("run_id", style="cyan", no_wrap=True)
+    table.add_column("old", justify="right")
+    table.add_column("new", justify="right")
+    table.add_column("delta", justify="right")
+    table.add_column("closed?")
+
+    drift_total = 0
+    closed_total = 0
+    for d in deltas:
+        delta_n = d["new_count"] - d["old_count"]
+        drift_total += abs(delta_n)
+        if d["closed"]:
+            closed_total += 1
+        delta_str = f"{delta_n:+d}" if delta_n != 0 else "0"
+        table.add_row(
+            d["run_id"][:8],
+            str(d["old_count"]),
+            str(d["new_count"]),
+            delta_str,
+            "yes" if d["closed"] else "no",
+        )
+
+    console.print(table)
+    console.print(
+        f"[bold]Drift repaired:[/bold] {drift_total} row(s) across "
+        f"{len(deltas)} run(s); [bold]auto-closed:[/bold] {closed_total}."
+    )

cli/resources/coherence/report.py

@@ -0,0 +1,144 @@
+# src/cli/resources/coherence/report.py
+"""
+`core-admin coherence report` — display a Constitutional Coherence Report.
+
+Governing ADR: .specs/decisions/ADR-067-constitutional-coherence-checker.md (D2).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import Counter
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from body.services.coherence_service import CoherenceService
+from cli.utils import core_command
+from shared.infrastructure.database.session_manager import get_session
+
+from .hub import app
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+_CLAIM_TRUNCATE = 80
+_TRIAGE_COLORS = {
+    "unreviewed": "yellow",
+    "confirmed": "red",
+    "dismissed": "dim",
+    "deferred": "cyan",
+}
+
+
+@app.command("report")
+@core_command(dangerous=False, requires_context=False)
+# ID: ef0a593c-f8b4-4398-ab1e-369086501481
+async def report_command(
+    run_id: str = typer.Argument(
+        None,
+        help="Run id to report on. Omit to use the most recent run.",
+    ),
+) -> None:
+    """Display the Constitutional Coherence Report for a run."""
+    async with get_session() as session:
+        service = CoherenceService(session)
+        try:
+            run = (
+                await service.get_run(run_id)
+                if run_id
+                else await service.get_latest_run()
+            )
+        except Exception as exc:
+            logger.exception("Failed to load coherence run")
+            console.print(f"[red]❌ Failed to load run: {exc}[/red]")
+            raise typer.Exit(code=1) from exc
+
+        if run is None:
+            console.print(
+                "[yellow]No coherence runs recorded. Run "
+                "`core-admin coherence check --full` to create one.[/yellow]"
+            )
+            return
+
+        candidates = await service.get_candidates(run["run_id"])
+
+    _render_metadata(run)
+    _render_manifest(run.get("input_manifest") or [])
+    _render_candidates(candidates)
+    _render_triage_summary(candidates)
+
+
+def _render_metadata(run: dict) -> None:
+    grid = Table.grid(expand=False, padding=(0, 1))
+    grid.add_row("run_id:", run["run_id"])
+    grid.add_row("run_at:", str(run["run_at"]))
+    grid.add_row("trigger:", run["trigger"])
+    status_color = "green" if run["run_status"] == "closed" else "yellow"
+    grid.add_row("status:", f"[{status_color}]{run['run_status']}[/{status_color}]")
+    grid.add_row(
+        "counts:",
+        f"{run['candidate_count']} candidate(s) · {run['unreviewed_count']} unreviewed",
+    )
+    console.print(Panel(grid, title="Coherence Run", expand=False))
+
+
+def _render_manifest(manifest: list[dict]) -> None:
+    if not manifest:
+        console.print("[dim]Manifest is empty.[/dim]")
+        return
+    table = Table(title="Coverage Manifest", expand=True)
+    table.add_column("path", style="cyan", no_wrap=True)
+    table.add_column("domain", style="magenta")
+    table.add_column("status", justify="center")
+    table.add_column("skipped_reason", style="dim")
+    for entry in manifest:
+        status = entry.get("status", "unknown")
+        status_color = "green" if status == "checked" else "yellow"
+        table.add_row(
+            str(entry.get("path", "")),
+            str(entry.get("domain", "")),
+            f"[{status_color}]{status}[/{status_color}]",
+            str(entry.get("skipped_reason") or ""),
+        )
+    console.print(table)
+
+
+def _render_candidates(candidates: list[dict]) -> None:
+    if not candidates:
+        console.print("[dim]No candidates produced.[/dim]")
+        return
+    table = Table(title="Candidates", expand=True)
+    table.add_column("candidate_id", style="cyan", no_wrap=True)
+    table.add_column("relation", justify="center")
+    table.add_column("claim")
+    table.add_column("triage", justify="center")
+    for c in candidates:
+        claim = c.get("claim") or ""
+        if len(claim) > _CLAIM_TRUNCATE:
+            claim = claim[: _CLAIM_TRUNCATE - 1] + "…"
+        decision = c.get("triage_decision", "unreviewed")
+        color = _TRIAGE_COLORS.get(decision, "white")
+        table.add_row(
+            c["candidate_id"],
+            c.get("relation", ""),
+            claim,
+            f"[{color}]{decision}[/{color}]",
+        )
+    console.print(table)
+
+
+def _render_triage_summary(candidates: list[dict]) -> None:
+    counts = Counter(c.get("triage_decision", "unreviewed") for c in candidates)
+    summary = Table.grid(expand=False, padding=(0, 1))
+    summary.add_row(
+        f"[red]{counts.get('confirmed', 0)}[/red] confirmed",
+        f"[dim]{counts.get('dismissed', 0)}[/dim] dismissed",
+        f"[cyan]{counts.get('deferred', 0)}[/cyan] deferred",
+        f"[yellow]{counts.get('unreviewed', 0)}[/yellow] unreviewed",
+    )
+    console.print(Panel(summary, title="Triage Summary", expand=False))

cli/resources/coherence/seed.py

@@ -0,0 +1,297 @@
+# src/cli/resources/coherence/seed.py
+"""`core-admin coherence seed` — governance_claims bootstrap and disaster recovery.
+
+Per ADR-073 D4:
+  - bootstrap : one-shot embed of the full corpus (governor-only; 30-70 min).
+  - export    : dump payloads + vectors to JSONL for disaster recovery.
+  - import    : hydrate the collection from a JSONL fixture.
+
+The daemon worker does NOT auto-bootstrap; this is the explicit governor path.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from cli.utils import core_command
+from shared.config import settings
+from shared.context import CoreContext
+from shared.infrastructure.storage.file_handler import FileHandler
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+seed_app = typer.Typer(
+    name="seed",
+    help=(
+        "Manage the governance_claims Qdrant collection: one-shot bootstrap "
+        "and disaster-recovery export/import. Per ADR-073 D4."
+    ),
+    no_args_is_help=True,
+)
+
+
+# Batch size for the bootstrap embed call. 32 is the #461 D1-confirmed default;
+# larger risks Ollama timeout on slow embed models, smaller loses throughput.
+# Tunable if a future Ollama version or model changes the trade-off.
+_BOOTSTRAP_EMBED_BATCH = 32
+
+
+@seed_app.command("bootstrap")
+@core_command(dangerous=True, requires_context=True)
+# ID: 73ce1ee6-67ce-4806-8a3c-252838cd3212
+async def bootstrap_command(ctx: typer.Context) -> None:
+    """Embed the full governance corpus into the governance_claims collection.
+
+    One-shot operation; wall-clock dominated by embedding throughput.
+    Post-#461 the embed call is batched (~3-10x speedup), so a 1572-claim
+    corpus completes well under 10 min on the current `.40` setup.
+    The daemon worker handles steady-state incremental sync after this
+    completes. Run once on install or after a collection drop.
+    """
+    from body.services.governance_claims_service import (
+        ClaimVector,
+        GovernanceClaimsService,
+    )
+    from shared.governance.coherence_harvester import GovernanceClaimHarvester
+    from shared.infrastructure.vector.cognitive_adapter import (
+        CognitiveEmbedderAdapter,
+    )
+
+    context: CoreContext = ctx.obj
+    try:
+        cognitive_service = await context.registry.get_cognitive_service()
+        qdrant = await context.registry.get_qdrant_service()
+    except Exception as exc:
+        logger.exception("Failed to acquire embedding services")
+        console.print(f"[red]Service unavailable: {exc}[/red]")
+        raise typer.Exit(code=1) from exc
+
+    claims_service = GovernanceClaimsService(qdrant)
+    await claims_service.ensure_collection()
+
+    harvester = GovernanceClaimHarvester(Path(settings.REPO_PATH))
+    claims = list(harvester.harvest())
+    if not claims:
+        console.print("[yellow]No claims harvested — nothing to embed.[/yellow]")
+        return
+
+    console.print(
+        f"[cyan]Bootstrapping[/cyan] governance_claims with [bold]{len(claims)}[/bold] "
+        f"claims (batch={_BOOTSTRAP_EMBED_BATCH}, expect <10 min)."
+    )
+
+    embedder = CognitiveEmbedderAdapter(cognitive_service)
+    items: list[ClaimVector] = []
+    failures = 0
+    upsert_batch = 50
+    embedded = 0
+    started = datetime.now(UTC)
+
+    for window_start in range(0, len(claims), _BOOTSTRAP_EMBED_BATCH):
+        window = claims[window_start : window_start + _BOOTSTRAP_EMBED_BATCH]
+        window_vectors, window_failures = await _embed_window(embedder, window)
+        items.extend(window_vectors)
+        failures += window_failures
+        if len(items) >= upsert_batch:
+            embedded += await claims_service.upsert_claims(items)
+            items = []
+            done = window_start + len(window)
+            console.print(
+                f"  [dim]progress[/dim] {embedded}/{len(claims)} "
+                f"({done / len(claims):.0%})"
+            )
+    if items:
+        embedded += await claims_service.upsert_claims(items)
+
+    elapsed = (datetime.now(UTC) - started).total_seconds()
+    console.print(
+        f"[green]Bootstrap complete[/green] — embedded {embedded}/{len(claims)} "
+        f"claims in {elapsed / 60:.1f} min ({failures} failures)"
+    )
+
+
+# ID: a47b6c39-2e85-4d18-8f06-c5b9e3a7d149
+async def _embed_window(embedder, window):
+    """Embed a window of claims via the batch entry point with single-shot fallback.
+
+    Tries `get_embeddings_batch` first; on batch failure, falls back to
+    per-claim single-input embed so a single bad claim does not abort
+    the whole window. This preserves the original bootstrap's error
+    isolation while still capturing the batch speedup on the common path.
+
+    Returns:
+        (list[ClaimVector] for successfully-embedded claims, failure_count)
+    """
+    from body.services.governance_claims_service import ClaimVector
+
+    texts = [c.text for c in window]
+    try:
+        vectors = await embedder.get_embeddings_batch(texts)
+        return (
+            [ClaimVector(claim=c, vector=v) for c, v in zip(window, vectors)],
+            0,
+        )
+    except Exception as exc:
+        logger.warning(
+            "bootstrap: batch embed failed for window of %d claims (%s); "
+            "falling back to single-shot for this window",
+            len(window),
+            exc,
+        )
+        items: list[ClaimVector] = []
+        failures = 0
+        for claim in window:
+            try:
+                vector = await embedder.get_embedding(claim.text)
+            except Exception as exc2:
+                logger.warning(
+                    "bootstrap: single-shot embed failed for %s (sha=%s): %s",
+                    claim.source_path,
+                    claim.content_sha[:8],
+                    exc2,
+                )
+                failures += 1
+                continue
+            items.append(ClaimVector(claim=claim, vector=vector))
+        return items, failures
+
+
+@seed_app.command("export")
+@core_command(dangerous=False, requires_context=True)
+# ID: 1fefb5ca-3d3d-474c-aed6-06c68f3b0694
+async def export_command(
+    ctx: typer.Context,
+    output: Path = typer.Argument(
+        ...,
+        help="Destination JSONL path. One line per claim: {payload, vector}.",
+    ),
+) -> None:
+    """Dump payloads + vectors from governance_claims to a JSONL fixture.
+
+    The fixture restores via `coherence seed import` without consulting the
+    embedding endpoint — disaster-recovery path per ADR-073 D4.
+    """
+    from body.services.governance_claims_service import GovernanceClaimsService
+
+    context: CoreContext = ctx.obj
+    try:
+        qdrant = await context.registry.get_qdrant_service()
+    except Exception as exc:
+        logger.exception("Failed to acquire Qdrant service")
+        console.print(f"[red]Service unavailable: {exc}[/red]")
+        raise typer.Exit(code=1) from exc
+
+    claims_service = GovernanceClaimsService(qdrant)
+    if not await claims_service.is_seeded():
+        console.print(
+            "[yellow]governance_claims is empty or absent — nothing to export.[/yellow]"
+        )
+        raise typer.Exit(code=1)
+
+    records = await qdrant.scroll_all_points(
+        with_payload=True,
+        with_vectors=True,
+        page_size=1024,
+        collection_name=claims_service.collection_name,
+    )
+
+    repo_root = context.git_service.repo_path
+    file_handler = FileHandler(str(repo_root))
+    file_handler.ensure_dir(str(output.parent.relative_to(repo_root)))
+    written = 0
+    # NOTE: streaming `output.open("w")` below is the #506 variable-receiver
+    # gap (silent in current taxonomy). The mkdir above is routed through
+    # FileHandler so the check no longer fires; the streaming write is
+    # enumerated in #506, not laundered as sanctuary here.
+    with output.open("w", encoding="utf-8") as fh:
+        for record in records:
+            fh.write(
+                json.dumps(
+                    {
+                        "id": str(record.id),
+                        "payload": record.payload,
+                        "vector": list(record.vector)
+                        if record.vector is not None
+                        else None,
+                    },
+                    separators=(",", ":"),
+                )
+            )
+            fh.write("\n")
+            written += 1
+    console.print(f"[green]Exported[/green] {written} claims to [bold]{output}[/bold]")
+
+
+@seed_app.command("import")
+@core_command(dangerous=True, requires_context=True)
+# ID: 0d96f158-176d-4701-9cd9-131b2c2a0f9a
+async def import_command(
+    ctx: typer.Context,
+    source: Path = typer.Argument(
+        ...,
+        help="JSONL fixture produced by `coherence seed export`.",
+    ),
+) -> None:
+    """Hydrate governance_claims from a JSONL fixture (disaster recovery).
+
+    Does not consult the embedding endpoint — vectors come from the fixture.
+    """
+    from qdrant_client.http import models as qm
+
+    from body.services.governance_claims_service import GovernanceClaimsService
+
+    context: CoreContext = ctx.obj
+    if not source.exists():
+        console.print(f"[red]Fixture not found: {source}[/red]")
+        raise typer.Exit(code=1)
+
+    try:
+        qdrant = await context.registry.get_qdrant_service()
+    except Exception as exc:
+        logger.exception("Failed to acquire Qdrant service")
+        console.print(f"[red]Service unavailable: {exc}[/red]")
+        raise typer.Exit(code=1) from exc
+
+    claims_service = GovernanceClaimsService(qdrant)
+    await claims_service.ensure_collection()
+
+    points: list[qm.PointStruct] = []
+    with source.open("r", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            record = json.loads(line)
+            vector = record.get("vector")
+            if not vector:
+                continue
+            points.append(
+                qm.PointStruct(
+                    id=record["id"],
+                    vector=vector,
+                    payload=record.get("payload") or {},
+                )
+            )
+
+    if not points:
+        console.print("[yellow]Fixture contained no usable records.[/yellow]")
+        raise typer.Exit(code=1)
+
+    batch = 200
+    for i in range(0, len(points), batch):
+        await qdrant.upsert_points(
+            claims_service.collection_name, points[i : i + batch], wait=True
+        )
+
+    console.print(
+        f"[green]Imported[/green] {len(points)} claims from [bold]{source}[/bold]"
+    )