core-runtime 0.1.1__py3-none-any.whl

api/cli/sync_client.py

@@ -0,0 +1,106 @@
+# src/api/cli/sync_client.py
+
+"""Sync namespace sub-client for CoreApiClient (issue #360).
+
+Covers /v1/sync/* (ADR-058 D2). Accessed via the facade as
+`core_api_client.sync`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from api.cli.client import CoreApiClient
+
+
+# ID: b2c87630-4860-495e-83d2-03349d072479
+class SyncClient:
+    """Sub-client for /sync/* endpoints.
+
+    Constructed by and bound to a CoreApiClient facade; uses
+    `self._facade._request` for HTTP and `self._facade._poll_at_path`
+    for polling.
+    """
+
+    def __init__(self, facade: CoreApiClient) -> None:
+        self._facade = facade
+
+    # ID: 0d65500c-229f-4fc0-9575-7cfafdb51968
+    async def sync_knowledge_graph(
+        self,
+        write: bool = False,
+        target: str | None = None,
+        requested_by: str = "api",
+    ) -> dict:
+        """POST /v1/sync/knowledge-graph — CLI command tree -> PostgreSQL."""
+        return await self._facade._request(
+            "POST",
+            "/v1/sync/knowledge-graph",
+            json={"write": write, "target": target, "requested_by": requested_by},
+        )
+
+    # ID: 2a470e64-e22c-4dc1-bc12-0ca7c5efda9c
+    async def sync_vectors(
+        self,
+        write: bool = False,
+        target: str | None = None,
+        requested_by: str = "api",
+    ) -> dict:
+        """POST /v1/sync/vectors — constitutional vector sync."""
+        return await self._facade._request(
+            "POST",
+            "/v1/sync/vectors",
+            json={"write": write, "target": target, "requested_by": requested_by},
+        )
+
+    # ID: a4868645-b7af-4f55-835b-e17860e1c50e
+    async def sync_code_vectors(
+        self,
+        write: bool = False,
+        target: str | None = None,
+        requested_by: str = "api",
+        force: bool = False,
+    ) -> dict:
+        """POST /v1/sync/code-vectors — codebase symbol embedding.
+
+        `force=True` resets chunk_count on already-embedded artifacts so the
+        embed loop re-processes them. No-op when `write` is False.
+        """
+        return await self._facade._request(
+            "POST",
+            "/v1/sync/code-vectors",
+            json={
+                "write": write,
+                "target": target,
+                "requested_by": requested_by,
+                "force": force,
+            },
+        )
+
+    # ID: d78efc87-ac06-4f1e-b89b-31dc6baf00d2
+    async def sync_dev_sync(
+        self,
+        write: bool = False,
+        target: str | None = None,
+        requested_by: str = "api",
+    ) -> dict:
+        """POST /v1/sync/dev-sync — composite fix + knowledge-graph + vectors."""
+        return await self._facade._request(
+            "POST",
+            "/v1/sync/dev-sync",
+            json={"write": write, "target": target, "requested_by": requested_by},
+        )
+
+    # ID: 7d4494ca-fd4d-4847-9b79-742809263c6f
+    async def get_sync_run(self, run_id: str) -> dict:
+        """GET /v1/sync/runs/{run_id} — fetch a sync_runs row."""
+        return await self._facade._request("GET", f"/v1/sync/runs/{run_id}")
+
+    # ID: 51369913-2fe9-447d-9069-b3cd163ceda2
+    async def poll_sync_run(self, run_id: str, timeout_seconds: float = 1800.0) -> dict:
+        """Poll a sync run until terminal."""
+        return await self._facade._poll_at_path(
+            f"/v1/sync/runs/{run_id}", timeout_seconds=timeout_seconds
+        )

api/dependencies.py

@@ -0,0 +1,37 @@
+# src/api/dependencies.py
+
+"""
+API Layer Dependency Providers.
+
+CONSTITUTIONAL NOTE: This file is explicitly excluded from
+architecture.api.no_direct_database_access enforcement. It is the
+ONLY sanctioned location in the API layer that may import database
+session primitives directly. All routes must acquire sessions through
+these providers — never by importing session_manager themselves.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from shared.infrastructure.database.session_manager import get_db_session, get_session
+
+
+# ID: 5b9f734c-5a1c-4278-9853-b0b841b08510
+async def get_api_session() -> AsyncGenerator[AsyncSession, None]:
+    """
+    FastAPI dependency that yields an async database session for route handlers.
+    """
+    async for session in get_db_session():
+        yield session
+
+
+# ID: 4b37e11c-2859-4e76-9d1b-e68c3050eed1
+async def open_background_session() -> AsyncGenerator[AsyncSession, None]:
+    """
+    Open and yield an async database session for use outside the request lifecycle.
+    """
+    async with get_session() as session:
+        yield session

api/errors.py

@@ -0,0 +1,74 @@
+# src/api/errors.py
+
+"""
+Centralizes HTTP exception handling to prevent sensitive stack trace leaks and ensure consistent error responses.
+"""
+
+from __future__ import annotations
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from starlette import status
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: 69085115-da2d-4649-948c-690b61eb1751
+def register_exception_handlers(app):
+    """Registers custom exception handlers with the FastAPI application."""
+
+    @app.exception_handler(StarletteHTTPException)
+    # ID: 12d85f80-7154-4bbc-a209-5bcf64b1455f
+    async def http_exception_handler(request: Request, exc: StarletteHTTPException):
+        """
+        Handles FastAPI's built-in HTTP exceptions to ensure consistent
+        JSON error responses.
+        """
+        logger.warning(
+            "HTTP Exception: %s %s for request: %s %s",
+            exc.status_code,
+            exc.detail,
+            request.method,
+            request.url.path,
+        )
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={"error": "request_error", "detail": exc.detail},
+        )
+
+    @app.exception_handler(Exception)
+    # ID: cd3d5242-3238-4f47-9224-6b7fd4365503
+    async def unhandled_exception_handler(request: Request, exc: Exception):
+        """
+        Catches any unhandled exception, logs the full traceback internally,
+        and returns a generic 500 Internal Server Error to the client.
+        This is a critical security measure to prevent leaking stack traces.
+
+        The traceback is formatted into the log message itself (not just
+        the structured `exc_info`) so it survives any downstream log
+        formatter that drops `exc_info`. Tagged `UNHANDLED_500_TRACE` so
+        operators can grep the journal.
+        """
+        import traceback
+
+        trace = traceback.format_exc()
+        logger.error(
+            "UNHANDLED_500_TRACE method=%s path=%s exc=%s\n%s",
+            request.method,
+            request.url.path,
+            f"{type(exc).__name__}: {exc}",
+            trace,
+        )
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "error": "internal_server_error",
+                "detail": "An unexpected internal error occurred.",
+            },
+        )
+
+    logger.info("Registered global exception handlers.")

api/main.py

@@ -0,0 +1,88 @@
+# src/api/main.py
+
+"""
+API Main Entry Point — composition root.
+
+FastAPI requires `lifespan` to be declared at app creation, so this file
+imports `core_lifespan` from Body to wire the startup/shutdown sequence.
+Composition roots wire layers together by design and are not layer bypasses.
+
+CONSTITUTIONAL STATUS:
+- Exempted from `architecture.api.no_body_bypass` via the composition-root
+  sanctuary in `.intent/enforcement/mappings/architecture/layer_separation.yaml`
+  (added 2026-04-19). Analogous to the bootstrap sanctuary granted under
+  `architecture.shared.no_layer_imports` for shared-layer composition files.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from api.errors import register_exception_handlers
+from api.v1 import (
+    audit_routes,
+    census_routes,
+    coverage_routes,
+    daemon_routes,
+    development_routes,
+    fix_routes,
+    inspect_routes,
+    integration_routes,
+    integrity_routes,
+    knowledge_routes,
+    lint_routes,
+    proposals_routes,
+    quality_routes,
+    refactor_routes,
+    sync_routes,
+)
+from body.infrastructure.lifespan import core_lifespan
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: 2751f337-a513-4f6d-8f35-b9d7055faac0
+def create_app() -> FastAPI:
+    """
+    This function creates a FastAPI application with two routers, registers exception handlers, includes health check endpoint, and returns the configured application instance.
+    """
+    app = FastAPI(
+        title="CORE - Self-Improving System Architect",
+        version="1.0.0",
+        lifespan=core_lifespan,
+    )
+    app.include_router(knowledge_routes.router, prefix="/v1", tags=["Knowledge"])
+    app.include_router(development_routes.router, prefix="/v1", tags=["Development"])
+    app.include_router(proposals_routes.router, prefix="/v1", tags=["Proposals"])
+    app.include_router(audit_routes.router, prefix="/v1", tags=["Audit"])
+    app.include_router(integration_routes.router, prefix="/v1", tags=["Integration"])
+    app.include_router(lint_routes.router, prefix="/v1", tags=["Lint"])
+    app.include_router(fix_routes.router, prefix="/v1", tags=["Fix"])
+    app.include_router(fix_routes.actions_router, prefix="/v1", tags=["Actions"])
+    app.include_router(quality_routes.router, prefix="/v1", tags=["quality"])
+    app.include_router(coverage_routes.router, prefix="/v1", tags=["Coverage"])
+    app.include_router(coverage_routes.tests_router, prefix="/v1", tags=["Coverage"])
+    app.include_router(refactor_routes.router, prefix="/v1", tags=["Refactor"])
+    app.include_router(inspect_routes.status_router, prefix="/v1", tags=["Inspect"])
+    app.include_router(inspect_routes.decisions_router, prefix="/v1", tags=["Inspect"])
+    app.include_router(inspect_routes.refusals_router, prefix="/v1", tags=["Inspect"])
+    app.include_router(inspect_routes.analysis_router, prefix="/v1", tags=["Inspect"])
+    app.include_router(inspect_routes.components_router, prefix="/v1", tags=["Inspect"])
+    app.include_router(inspect_routes.search_router, prefix="/v1", tags=["Inspect"])
+    app.include_router(census_routes.router, prefix="/v1", tags=["Census"])
+    app.include_router(sync_routes.router, prefix="/v1", tags=["Sync"])
+    app.include_router(integrity_routes.router, prefix="/v1", tags=["Integrity"])
+    app.include_router(daemon_routes.router, prefix="/v1", tags=["Daemon"])
+    register_exception_handlers(app)
+
+    @app.get("/health")
+    # ID: 7e958d32-1b47-43a5-836b-f6df51d6b803
+    def health_check():
+        return {"status": "ok"}
+
+    return app
+
+
+app = create_app()

api/v1/__init__.py

@@ -0,0 +1,4 @@
+# src/api/v1/__init__.py
+"""Provides functionality for the __init__ module."""
+
+from __future__ import annotations

api/v1/audit_routes.py

@@ -0,0 +1,302 @@
+# src/api/v1/audit_routes.py
+
+"""
+Audit API endpoints (ADR-054 Phase 1, D1).
+
+`POST /audit/runs` has two modes:
+
+* `wait=false` (default) — fire-and-forget; inserts a pending row in
+  core.audit_runs, returns the run_id with status 202, and drives the
+  audit on a background task. Used by programmatic callers that don't
+  need to block on the result.
+
+* `wait=true` — synchronous; runs the audit inside the request
+  handler and returns the full result (verdict, findings, stats,
+  executed_rule_ids, auto_ignored) with status 200. Used by
+  `core-admin code audit`. Audit duration is ~60s — clients must set
+  a long HTTP timeout.
+
+`GET /audit/runs/{id}` reads back the audit_runs row (verdict,
+counts, timestamps, status, findings list). Findings are denormalized
+on `core.audit_runs.findings` (jsonb) — see the ADR-054 amendment.
+
+CONSTITUTIONAL:
+- Session access via api.dependencies.get_api_session /
+  open_background_session only.
+- CoreContext is read from request.app.state.core_context.
+- mind.* / shared.infrastructure.* are reached through the
+  will.governance.audit_runner facade — no direct imports here.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    Body,
+    Depends,
+    HTTPException,
+    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.audit_remediation_runner import (
+    MODE_ALIASES,
+    run_and_persist_audit_remediation,
+)
+from will.governance.audit_runner import run_and_persist_audit, run_sync_audit
+
+
+logger = getLogger(__name__)
+
+
+router = APIRouter(prefix="/audit")
+
+
+# ID: b8443c8a-97ea-4011-8b99-f20e8d19e4eb
+class CreateAuditRunRequest(BaseModel):
+    """Body for POST /audit/runs.
+
+    Empty body is valid and equivalent to a default-constructed model
+    (full audit, async, no LLM-cache bypass).
+    """
+
+    rule_ids: list[str] = []
+    policy_ids: list[str] = []
+    files: list[str] = []
+    force_llm: bool = False
+    wait: bool = False
+    source: str = "api"
+
+
+@router.post("/runs")
+# ID: 26d3745c-b1a3-419f-a521-06691b8a2c75
+async def create_audit_run(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: CreateAuditRunRequest = Body(default_factory=CreateAuditRunRequest),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Start a new audit run.
+
+    See module docstring for the wait=true vs wait=false split.
+    """
+    core_context: CoreContext = request.app.state.core_context
+
+    if payload.wait:
+        # Synchronous — full result returned in-band (status 200).
+        return await run_sync_audit(
+            core_context,
+            session,
+            rule_ids=payload.rule_ids,
+            policy_ids=payload.policy_ids,
+            files=payload.files,
+            force_llm=payload.force_llm,
+            source=payload.source,
+        )
+
+    # Async — fire and forget (status 202). The pending row gives the
+    # caller a run_id to poll GET /audit/runs/{id} for. See the
+    # ADR-054 gap note on GET.
+    response.status_code = 202
+    result = await session.execute(
+        text(
+            """
+            INSERT INTO core.audit_runs
+                (source, verdict, finding_count, blocking_count, status)
+            VALUES ('api', 'pending', 0, 0, 'pending')
+            RETURNING run_id
+            """
+        )
+    )
+    run_id: UUID = result.scalar_one()
+    await session.commit()
+
+    # ID: 3042f075-2d01-4950-bae2-3a599b416c30
+    async def drive_audit() -> None:
+        """Background task — owns its own session per ADR-053 lifecycle."""
+        async for bg_session in open_background_session():
+            await run_and_persist_audit(core_context, bg_session, run_id=run_id)
+
+    background_tasks.add_task(drive_audit)
+
+    return {"run_id": str(run_id), "status": "pending"}
+
+
+@router.get("/runs/{run_id}")
+# ID: 7c4903f0-e174-4e52-915d-54988fe40d22
+async def get_audit_run(
+    run_id: UUID,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Return a persisted audit run by id, or 404 if unknown.
+
+    Returns the full resource record: verdict + counts + timestamps +
+    status + findings list. Findings are denormalized on
+    `core.audit_runs.findings` (jsonb) per the ADR-054 amendment;
+    pre-amendment rows return an empty list. Closes #340.
+    """
+    result = await session.execute(
+        text(
+            """
+            SELECT run_id, verdict, finding_count, blocking_count,
+                   started_at, finished_at, status, findings
+              FROM core.audit_runs
+             WHERE run_id = :rid
+            """
+        ),
+        {"rid": run_id},
+    )
+    row = result.mappings().first()
+    if row is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Audit run not found: {run_id}",
+        )
+
+    return {
+        "run_id": str(row["run_id"]),
+        "verdict": row["verdict"],
+        "finding_count": row["finding_count"],
+        "blocking_count": row["blocking_count"],
+        "started_at": row["started_at"].isoformat() if row["started_at"] else None,
+        "finished_at": (row["finished_at"].isoformat() if row["finished_at"] else None),
+        "status": row["status"],
+        "findings": row["findings"] or [],
+    }
+
+
+# ID: 4b7c8d9e-0f1a-4b2c-3d4e-5f6a7b8c9d0e
+class CreateRemediationRequest(BaseModel):
+    """Body for POST /audit/remediations (ADR-057 D4).
+
+    `audit_run_id` is the prior `core.audit_runs` row whose findings are
+    to be remediated. `mode` is the aggressiveness selector — wire
+    vocabulary 'safe' | 'medium' | 'all' (mapped onto RemediationMode at
+    the facade). `write=false` is the dry-run default (ADR-014).
+    """
+
+    audit_run_id: UUID
+    mode: str = "safe"
+    write: bool = False
+    requested_by: str = "api"
+
+
+@router.post("/remediations")
+# ID: 5c8d9e0f-1a2b-4c3d-4e5f-6a7b8c9d0e1f
+async def create_remediation_run(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: CreateRemediationRequest = Body(...),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Dispatch autonomous remediation of audit findings (ADR-057 D4).
+
+    Validates `mode` against the wire vocabulary, INSERTs a pending row
+    in core.audit_remediation_runs, and schedules background execution
+    via will.governance.audit_remediation_runner. The audit_run_id FK
+    is enforced at the DB layer — a missing-audit_run_id 404 surfaces
+    only on read, not at dispatch.
+    """
+    if payload.mode not in MODE_ALIASES:
+        raise HTTPException(
+            status_code=422,
+            detail={
+                "error": f"Unknown remediation mode: {payload.mode}",
+                "allowed": sorted(MODE_ALIASES.keys()),
+            },
+        )
+
+    core_context: CoreContext = request.app.state.core_context
+
+    result = await session.execute(
+        text(
+            """
+            INSERT INTO core.audit_remediation_runs
+                (audit_run_id, mode, write, status, requested_by)
+            VALUES (:audit_run_id, :mode, :write, 'pending', :requested_by)
+            RETURNING id
+            """
+        ),
+        {
+            "audit_run_id": payload.audit_run_id,
+            "mode": payload.mode,
+            "write": payload.write,
+            "requested_by": payload.requested_by,
+        },
+    )
+    run_id: UUID = result.scalar_one()
+    await session.commit()
+
+    # ID: 6d9e0f1a-2b3c-4d4e-5f6a-7b8c9d0e1f2a
+    async def drive_remediation() -> None:
+        async for bg_session in open_background_session():
+            await run_and_persist_audit_remediation(
+                core_context,
+                bg_session,
+                run_id=run_id,
+                mode=payload.mode,
+                write=payload.write,
+            )
+
+    background_tasks.add_task(drive_remediation)
+
+    response.status_code = 202
+    return {
+        "run_id": str(run_id),
+        "status": "pending",
+        "href": f"/audit/remediations/{run_id}",
+    }
+
+
+@router.get("/remediations/{run_id}")
+# ID: 7e0f1a2b-3c4d-4e5f-6a7b-8c9d0e1f2a3b
+async def get_remediation_run(
+    run_id: UUID,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Return a persisted remediation run by id, or 404 if unknown."""
+    result = await session.execute(
+        text(
+            """
+            SELECT id, audit_run_id, mode, write, status,
+                   requested_by, requested_at, started_at, finished_at,
+                   result, error
+              FROM core.audit_remediation_runs
+             WHERE id = :rid
+            """
+        ),
+        {"rid": run_id},
+    )
+    row = result.mappings().first()
+    if row is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Audit remediation run not found: {run_id}",
+        )
+
+    return {
+        "run_id": str(row["id"]),
+        "audit_run_id": (str(row["audit_run_id"]) if row["audit_run_id"] else None),
+        "mode": row["mode"],
+        "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"],
+    }