core-runtime 0.1.1__py3-none-any.whl

api/v1/census_routes.py

@@ -0,0 +1,207 @@
+# src/api/v1/census_routes.py
+
+"""
+Census API endpoints (ADR-058 Phase 4, D1).
+
+Three endpoint groups:
+
+* Async dispatch — `POST /census/runs` inserts a pending row in
+  `core.census_runs`, schedules a background task on the
+  `will.governance.census_runner` facade, returns 202 with run_id +
+  poll href.
+
+* Resource read — `GET /census/runs/{run_id}` returns the persisted row.
+
+* Synchronous baseline + diff — `POST /census/baselines/{name}`,
+  `GET /census/baselines`, `GET /census/diff` operate against the
+  on-disk baseline registry and snapshot history.
+
+CONSTITUTIONAL:
+- Session access via `api.dependencies.get_api_session` /
+  `open_background_session` only.
+- `CoreContext` read from `request.app.state.core_context`.
+- `body.services.cim.*` reached through the
+  `will.governance.census_runner` facade — no direct imports here
+  (architecture.api.no_body_bypass).
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    Body,
+    Depends,
+    HTTPException,
+    Query,
+    Request,
+    Response,
+)
+from pydantic import BaseModel
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.dependencies import get_api_session, open_background_session
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.governance.census_runner import (
+    create_baseline,
+    get_diff,
+    list_baselines,
+    run_and_persist_census,
+)
+
+
+logger = getLogger(__name__)
+
+
+router = APIRouter(prefix="/census")
+
+
+# ID: 8c5e2d0f-4b9a-4d7e-ecbe-7f8901ab23cd
+class CreateCensusRunRequest(BaseModel):
+    """Body for POST /census/runs."""
+
+    snapshot: bool = False
+    requested_by: str = "api"
+
+
+# ID: 9d6f3e1a-5c0b-4e8f-fdcf-89012ab34d5e
+class CreateBaselineRequest(BaseModel):
+    """Body for POST /census/baselines/{name}.
+
+    `snapshot_file` is optional — when omitted the most recent snapshot
+    is used. The handler maps the missing-snapshot case to 422.
+    """
+
+    snapshot_file: str | None = None
+
+
+@router.post("/runs")
+# ID: 0e7a4f2b-6d1c-4f9a-aedb-90123ab456f7
+async def create_census_run(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: CreateCensusRunRequest = Body(default_factory=CreateCensusRunRequest),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Dispatch a CIM-0 structural census."""
+    core_context: CoreContext = request.app.state.core_context
+
+    result = await session.execute(
+        text(
+            """
+            INSERT INTO core.census_runs
+                (snapshot, status, requested_by)
+            VALUES (:snapshot, 'pending', :requested_by)
+            RETURNING id
+            """
+        ),
+        {
+            "snapshot": payload.snapshot,
+            "requested_by": payload.requested_by,
+        },
+    )
+    run_id: UUID = result.scalar_one()
+    await session.commit()
+
+    # ID: 1f8b5a3c-7e2d-4a0b-bfec-a1234bc567f8
+    async def drive_census() -> None:
+        async for bg_session in open_background_session():
+            await run_and_persist_census(
+                core_context,
+                bg_session,
+                run_id=run_id,
+                snapshot=payload.snapshot,
+            )
+
+    background_tasks.add_task(drive_census)
+
+    response.status_code = 202
+    return {
+        "run_id": str(run_id),
+        "status": "pending",
+        "href": f"/census/runs/{run_id}",
+    }
+
+
+@router.get("/runs/{run_id}")
+# ID: 2a9c6b4d-8f3e-4b1c-c0fd-b2345cd6789a
+async def get_census_run(
+    run_id: UUID,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Return a persisted census run by id, or 404 if unknown."""
+    result = await session.execute(
+        text(
+            """
+            SELECT id, snapshot, baseline_name, status,
+                   requested_by, requested_at, started_at, finished_at,
+                   result, error
+              FROM core.census_runs
+             WHERE id = :rid
+            """
+        ),
+        {"rid": run_id},
+    )
+    row = result.mappings().first()
+    if row is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Census run not found: {run_id}",
+        )
+
+    return {
+        "run_id": str(row["id"]),
+        "snapshot": row["snapshot"],
+        "baseline_name": row["baseline_name"],
+        "status": row["status"],
+        "requested_by": row["requested_by"],
+        "requested_at": (
+            row["requested_at"].isoformat() if row["requested_at"] else None
+        ),
+        "started_at": row["started_at"].isoformat() if row["started_at"] else None,
+        "finished_at": (row["finished_at"].isoformat() if row["finished_at"] else None),
+        "result": row["result"],
+        "error": row["error"],
+    }
+
+
+@router.post("/baselines/{name}")
+# ID: 3b0d7c5e-9a4f-4c2d-d10e-c3456de789ab
+async def create_census_baseline(
+    request: Request,
+    name: str,
+    payload: CreateBaselineRequest = Body(default_factory=CreateBaselineRequest),
+) -> dict:
+    """Create a named baseline from a prior census snapshot."""
+    core_context: CoreContext = request.app.state.core_context
+    try:
+        baseline = create_baseline(
+            core_context, name=name, snapshot_file=payload.snapshot_file
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"baseline": baseline}
+
+
+@router.get("/baselines")
+# ID: 4c1e8d6f-0b5a-4d3e-e21f-d4567ef89abc
+async def list_census_baselines(request: Request) -> dict:
+    """Return all named baselines (newest first)."""
+    core_context: CoreContext = request.app.state.core_context
+    return list_baselines(core_context)
+
+
+@router.get("/diff")
+# ID: 5d2f9e7a-1c6b-4e4f-f320-e5678f0abcde
+async def census_diff(
+    request: Request,
+    baseline: str | None = Query(default=None),
+) -> dict:
+    """Diff the latest snapshot against a baseline (or the previous one)."""
+    core_context: CoreContext = request.app.state.core_context
+    return get_diff(core_context, baseline=baseline)

api/v1/coverage_routes.py

@@ -0,0 +1,352 @@
+# src/api/v1/coverage_routes.py
+
+"""
+Coverage API endpoints (ADR-057 Phase 3, D1).
+
+Three endpoint groups:
+
+* Read-only queries — GET /coverage/check, /coverage/report,
+  /coverage/targets, /coverage/gaps, /coverage/history,
+  /coverage/methods. Each returns a synchronous JSON payload.
+
+* Async dispatch — POST /coverage/generate, POST /coverage/generate:batch.
+  Each inserts a pending row in core.coverage_runs, schedules a
+  background task on the will.governance.coverage_runner facade, and
+  returns 202 with the run_id + poll href.
+
+* Resource read — GET /coverage/runs/{run_id}.
+
+* Synchronous dispatch — POST /tests/interactive. Returns the result
+  inline (200) — no coverage_runs row, no background task.
+
+CONSTITUTIONAL:
+- Session access via api.dependencies.get_api_session /
+  open_background_session only.
+- CoreContext is read from request.app.state.core_context.
+- body.* / mind.* are reached through the
+  will.governance.coverage_runner facade — no direct imports here
+  (architecture.api.no_body_bypass).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    Body,
+    Depends,
+    HTTPException,
+    Query,
+    Request,
+    Response,
+)
+from pydantic import BaseModel
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.dependencies import get_api_session, open_background_session
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.governance.coverage_runner import (
+    get_coverage_check,
+    get_coverage_gaps,
+    get_coverage_history,
+    get_coverage_html_report,
+    get_coverage_methods,
+    get_coverage_report,
+    get_coverage_targets,
+    run_and_persist_coverage_batch,
+    run_and_persist_coverage_generation,
+    run_tests_interactive,
+)
+
+
+logger = getLogger(__name__)
+
+
+router = APIRouter(prefix="/coverage")
+# /tests/interactive lives outside the /coverage namespace per ADR-057
+# D5 (the endpoint produces a one-shot interactive session response).
+tests_router = APIRouter(prefix="/tests")
+
+
+# ID: 8d2e4f0a-1b3c-4d5e-6f7a-8b9c0d1e2f30
+class GenerateRequest(BaseModel):
+    """Body for POST /coverage/generate."""
+
+    target_file: str
+    write: bool = False
+    requested_by: str = "api"
+
+
+# ID: 9e3f5a1b-2c4d-4e6f-7a8b-9c0d1e2f3a41
+class GenerateBatchRequest(BaseModel):
+    """Body for POST /coverage/generate:batch.
+
+    `priority` ∈ {'high', 'all'} per ADR-057 D1. 'high' raises the target
+    coverage; 'all' uses the default constitutional target.
+    """
+
+    priority: str = "all"
+    write: bool = False
+    requested_by: str = "api"
+
+
+# ID: 0f4a6b2c-3d5e-4f7a-8b9c-0d1e2f3a4b52
+class InteractiveTestsRequest(BaseModel):
+    """Body for POST /tests/interactive."""
+
+    target_file: str | None = None
+
+
+# ---------- GET endpoints -------------------------------------------------
+
+
+@router.get("/check")
+# ID: 1a5b7c3d-4e6f-4a8b-9c0d-1e2f3a4b5c63
+async def coverage_check(request: Request) -> dict:
+    """Run the constitutional coverage compliance check."""
+    core_context: CoreContext = request.app.state.core_context
+    return await get_coverage_check(core_context)
+
+
+@router.get("/report")
+# ID: 2b6c8d4e-5f7a-4b9c-0d1e-2f3a4b5c6d74
+async def coverage_report(
+    request: Request,
+    show_missing: bool = Query(default=False),
+    format: Literal["text", "html"] = Query(default="text"),
+) -> dict:
+    """Return the pytest coverage report.
+
+    `format=text` (default) returns the term report in `stdout_tail`.
+    `format=html` runs pytest with the HTML reporter and returns the
+    `htmlcov/` directory path in `html_path` (closes #358).
+    """
+    core_context: CoreContext = request.app.state.core_context
+    if format == "html":
+        return await get_coverage_html_report(core_context)
+    return await get_coverage_report(core_context, show_missing=show_missing)
+
+
+@router.get("/targets")
+# ID: 3c7d9e5f-6a8b-4c0d-1e2f-3a4b5c6d7e85
+async def coverage_targets(request: Request) -> dict:
+    """Return the constitutional coverage targets."""
+    core_context: CoreContext = request.app.state.core_context
+    return get_coverage_targets(core_context)
+
+
+@router.get("/gaps")
+# ID: 4d8e0f6a-7b9c-4d1e-2f3a-4b5c6d7e8f96
+async def coverage_gaps(
+    request: Request,
+    threshold: float = Query(default=75.0, ge=0.0, le=100.0),
+    limit: int = Query(default=20, ge=1, le=200),
+) -> dict:
+    """Return modules ranked by coverage deficit below `threshold`."""
+    core_context: CoreContext = request.app.state.core_context
+    return await get_coverage_gaps(core_context, threshold=threshold, limit=limit)
+
+
+@router.get("/history")
+# ID: 5e9f1a7b-8c0d-4e2f-3a4b-5c6d7e8f9a07
+async def coverage_history(
+    request: Request,
+    limit: int = Query(default=30, ge=1, le=500),
+) -> dict:
+    """Return recent coverage measurements."""
+    core_context: CoreContext = request.app.state.core_context
+    return get_coverage_history(core_context, limit=limit)
+
+
+@router.get("/methods")
+# ID: 6f0a2b8c-9d1e-4f3a-4b5c-6d7e8f9a0b18
+async def coverage_methods(request: Request) -> dict:
+    """Return the legacy-vs-adaptive coverage method comparison."""
+    core_context: CoreContext = request.app.state.core_context
+    return get_coverage_methods(core_context)
+
+
+# ---------- POST async generation ----------------------------------------
+
+
+@router.post("/generate")
+# ID: 7a1b3c9d-0e2f-4a4b-5c6d-7e8f9a0b1c29
+async def generate_coverage(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: GenerateRequest = Body(...),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Dispatch adaptive test generation for a single file.
+
+    Inserts a pending row in core.coverage_runs and queues background
+    execution via will.governance.coverage_runner.
+    """
+    core_context: CoreContext = request.app.state.core_context
+
+    result = await session.execute(
+        text(
+            """
+            INSERT INTO core.coverage_runs
+                (target_file, batch_priority, write, status, requested_by)
+            VALUES (:target_file, NULL, :write, 'pending', :requested_by)
+            RETURNING id
+            """
+        ),
+        {
+            "target_file": payload.target_file,
+            "write": payload.write,
+            "requested_by": payload.requested_by,
+        },
+    )
+    run_id: UUID = result.scalar_one()
+    await session.commit()
+
+    # ID: 8b2c4d0e-1f3a-4b5c-6d7e-8f9a0b1c2d3a
+    async def drive_generate() -> None:
+        async for bg_session in open_background_session():
+            await run_and_persist_coverage_generation(
+                core_context,
+                bg_session,
+                run_id=run_id,
+                target_file=payload.target_file,
+                write=payload.write,
+            )
+
+    background_tasks.add_task(drive_generate)
+
+    response.status_code = 202
+    return {
+        "run_id": str(run_id),
+        "status": "pending",
+        "href": f"/coverage/runs/{run_id}",
+    }
+
+
+@router.post("/generate:batch")
+# ID: 9c3d5e1f-2a4b-4c6d-7e8f-9a0b1c2d3e4b
+async def generate_coverage_batch(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: GenerateBatchRequest = Body(...),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Dispatch prioritised batch adaptive test generation."""
+    if payload.priority not in {"high", "all"}:
+        raise HTTPException(
+            status_code=422,
+            detail={
+                "error": f"Unknown priority: {payload.priority}",
+                "allowed": ["high", "all"],
+            },
+        )
+
+    core_context: CoreContext = request.app.state.core_context
+
+    result = await session.execute(
+        text(
+            """
+            INSERT INTO core.coverage_runs
+                (target_file, batch_priority, write, status, requested_by)
+            VALUES (NULL, :priority, :write, 'pending', :requested_by)
+            RETURNING id
+            """
+        ),
+        {
+            "priority": payload.priority,
+            "write": payload.write,
+            "requested_by": payload.requested_by,
+        },
+    )
+    run_id: UUID = result.scalar_one()
+    await session.commit()
+
+    # ID: 0d4e6f2a-3b5c-4d7e-8f9a-0b1c2d3e4f5c
+    async def drive_batch() -> None:
+        async for bg_session in open_background_session():
+            await run_and_persist_coverage_batch(
+                core_context,
+                bg_session,
+                run_id=run_id,
+                batch_priority=payload.priority,
+                write=payload.write,
+            )
+
+    background_tasks.add_task(drive_batch)
+
+    response.status_code = 202
+    return {
+        "run_id": str(run_id),
+        "status": "pending",
+        "href": f"/coverage/runs/{run_id}",
+    }
+
+
+# ---------- POST sync interactive ----------------------------------------
+
+
+@tests_router.post("/interactive")
+# ID: 1e5f7a3b-4c6d-4e8f-9a0b-1c2d3e4f5a6d
+async def interactive_tests(
+    request: Request,
+    payload: InteractiveTestsRequest = Body(default_factory=InteractiveTestsRequest),
+) -> dict:
+    """Run interactive adaptive test generation synchronously.
+
+    No resource row. Returns the result dict inline with 200.
+    """
+    core_context: CoreContext = request.app.state.core_context
+    return await run_tests_interactive(core_context, target_file=payload.target_file)
+
+
+# ---------- GET resource read --------------------------------------------
+
+
+@router.get("/runs/{run_id}")
+# ID: 2f6a8b4c-5d7e-4f9a-0b1c-2d3e4f5a6b7e
+async def get_coverage_run(
+    run_id: UUID,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Return a persisted coverage run by id, or 404 if unknown."""
+    result = await session.execute(
+        text(
+            """
+            SELECT id, target_file, batch_priority, write, status,
+                   requested_by, requested_at, started_at, finished_at,
+                   result, error
+              FROM core.coverage_runs
+             WHERE id = :rid
+            """
+        ),
+        {"rid": run_id},
+    )
+    row = result.mappings().first()
+    if row is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Coverage run not found: {run_id}",
+        )
+
+    return {
+        "run_id": str(row["id"]),
+        "target_file": row["target_file"],
+        "batch_priority": row["batch_priority"],
+        "write": row["write"],
+        "status": row["status"],
+        "requested_by": row["requested_by"],
+        "requested_at": (
+            row["requested_at"].isoformat() if row["requested_at"] else None
+        ),
+        "started_at": row["started_at"].isoformat() if row["started_at"] else None,
+        "finished_at": (row["finished_at"].isoformat() if row["finished_at"] else None),
+        "result": row["result"],
+        "error": row["error"],
+    }

api/v1/daemon_routes.py

@@ -0,0 +1,86 @@
+# src/api/v1/daemon_routes.py
+
+"""
+Daemon API endpoints (ADR-058 Phase 4, D3).
+
+Three synchronous endpoints; no resource table:
+
+* `GET  /daemon/status` — liveness + per-worker health (ADR-041
+  thresholds via `WorkerRegistryService`).
+* `POST /daemon/start`  — synchronous `systemctl --user start core-daemon`.
+* `POST /daemon/stop`   — returns 200 immediately; the actual
+  `systemctl stop` runs as a FastAPI BackgroundTask after the response
+  is sent (ADR-058 D3 fire-and-forget pattern).
+
+CONSTITUTIONAL:
+- `CoreContext` read from `request.app.state.core_context`.
+- `body.services.worker_registry_service` and the subprocess primitive
+  are reached through the `will.governance.daemon_runner` facade — no
+  direct imports here.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, BackgroundTasks, HTTPException, Request, Response
+
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.governance.daemon_runner import (
+    get_status,
+    start_daemon,
+    stop_daemon_background,
+)
+
+
+logger = getLogger(__name__)
+
+
+router = APIRouter(prefix="/daemon")
+
+
+@router.get("/status")
+# ID: 4a1c8b6d-0f5e-4b3c-8cb9-7ef56789f012
+async def daemon_status(request: Request) -> dict:
+    """Return current daemon liveness and per-worker health."""
+    core_context: CoreContext = request.app.state.core_context
+    return await get_status(core_context)
+
+
+@router.post("/start")
+# ID: 5b2d9c7e-1a6f-4c4d-9dca-8f067890a123
+async def daemon_start(request: Request) -> dict:
+    """Start the core-daemon service via `systemctl --user start`."""
+    _ = request
+    result = await start_daemon()
+    if not result.get("ok", False):
+        raise HTTPException(
+            status_code=500,
+            detail={
+                "error": "daemon_start_failed",
+                "exit_code": result.get("exit_code"),
+                "stderr_tail": result.get("stderr_tail", []),
+                "underlying_error": result.get("error"),
+            },
+        )
+    return {"status": "started", "exit_code": result.get("exit_code", 0)}
+
+
+@router.post("/stop")
+# ID: 6c3e0d8f-2b7a-4d5e-aedb-90178901b234
+async def daemon_stop(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+) -> dict:
+    """Signal the daemon to stop (fire-and-forget after 200).
+
+    The response is sent first; `systemctl stop core-daemon` runs as a
+    FastAPI BackgroundTask after the response completes. Per ADR-058 D3,
+    this preserves correct ordering when the API and daemon share a
+    process — and is harmless on deployments where they run as separate
+    systemd units (the BackgroundTask still completes cleanly).
+    """
+    _ = request
+    background_tasks.add_task(stop_daemon_background)
+    response.status_code = 200
+    return {"status": "stopping"}