core-runtime 0.1.1__py3-none-any.whl

api/v1/inspect_routes.py

@@ -0,0 +1,220 @@
+# src/api/v1/inspect_routes.py
+
+"""
+Inspect API endpoints (ADR-057 Phase 3, D3, D5).
+
+Every endpoint here is read-only — no resource tables, no background
+tasks. Endpoints live under six top-level namespaces (`/status`,
+`/decisions`, `/refusals`, `/analysis`, `/components`, `/search`) so the
+API surface mirrors the CLI command groups one-to-one. All six routers
+are mounted under the `Inspect` OpenAPI tag — `inspect` is the logical
+namespace name, not a URL prefix (per ADR-053 D4 amendment 2026-05-18).
+
+CONSTITUTIONAL:
+- Session access via api.dependencies.get_api_session only.
+- CoreContext is read from request.app.state.core_context.
+- body.* repositories / mind.* engines / will.* services are reached
+  through the will.governance.inspect_runner facade — no direct
+  imports here (architecture.api.no_body_bypass).
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.dependencies import get_api_session
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.governance.inspect_runner import (
+    get_analysis_clusters,
+    get_analysis_command_tree,
+    get_analysis_common_knowledge,
+    get_analysis_duplicates,
+    get_analysis_test_targets,
+    get_components_list,
+    get_db_status,
+    get_decisions,
+    get_decisions_patterns,
+    get_drift_status,
+    get_refusals,
+    get_refusals_stats,
+    get_search_capabilities,
+    get_search_commands,
+)
+
+
+logger = getLogger(__name__)
+
+
+# Each top-level namespace gets its own router. They are mounted together
+# in api/main.py so the URL prefixes are preserved verbatim.
+status_router = APIRouter(prefix="/status")
+decisions_router = APIRouter(prefix="/decisions")
+refusals_router = APIRouter(prefix="/refusals")
+analysis_router = APIRouter(prefix="/analysis")
+components_router = APIRouter(prefix="/components")
+search_router = APIRouter(prefix="/search")
+
+
+# ---------- /status ------------------------------------------------------
+
+
+@status_router.get("/db")
+# ID: 1c5d7e3f-4a6b-4c8d-9e0f-1a2b3c4d5e61
+async def status_db(session: AsyncSession = Depends(get_api_session)) -> dict:
+    """Return DB connection and schema state."""
+    return await get_db_status(session)
+
+
+@status_router.get("/drift")
+# ID: 2d6e8f4a-5b7c-4d9e-0f1a-2b3c4d5e6f72
+async def status_drift(
+    request: Request,
+    scope: str = Query(default="all"),
+) -> dict:
+    """Return consolidated drift snapshot for symbols and/or vectors."""
+    core_context: CoreContext = request.app.state.core_context
+    return await get_drift_status(core_context, scope=scope)
+
+
+# ---------- /decisions ---------------------------------------------------
+
+
+@decisions_router.get("")
+# ID: 3e7f9a5b-6c8d-4e0f-1a2b-3c4d5e6f7a83
+async def decisions_list(
+    session_id: str | None = Query(default=None),
+    agent: str | None = Query(default=None),
+    pattern: str | None = Query(default=None),
+    limit: int = Query(default=50, ge=1, le=500),
+) -> dict:
+    """Return recent decision traces with optional filters."""
+    return await get_decisions(
+        session_id=session_id,
+        agent=agent,
+        pattern=pattern,
+        limit=limit,
+    )
+
+
+@decisions_router.get("/patterns")
+# ID: 4f8a0b6c-7d9e-4f1a-2b3c-4d5e6f7a8b94
+async def decisions_patterns(
+    days: int = Query(default=7, ge=1, le=365),
+) -> dict:
+    """Return pattern classification stats across the lookback window."""
+    return await get_decisions_patterns(days=days)
+
+
+# ---------- /refusals ----------------------------------------------------
+
+
+@refusals_router.get("")
+# ID: 5a9b1c7d-8e0f-4a2b-3c4d-5e6f7a8b9ca5
+async def refusals_list(
+    refusal_type: str | None = Query(default=None, alias="type"),
+    session_id: str | None = Query(default=None, alias="session"),
+    limit: int = Query(default=50, ge=1, le=500),
+) -> dict:
+    """Return recent constitutional refusal records."""
+    return await get_refusals(
+        refusal_type=refusal_type,
+        session_id=session_id,
+        limit=limit,
+    )
+
+
+@refusals_router.get("/stats")
+# ID: 6b0c2d8e-9f1a-4b3c-4d5e-6f7a8b9c0db6
+async def refusals_stats(
+    days: int = Query(default=7, ge=1, le=365),
+) -> dict:
+    """Return refusal statistics grouped by type."""
+    return await get_refusals_stats(days=days)
+
+
+# ---------- /analysis ----------------------------------------------------
+
+
+@analysis_router.get("/clusters")
+# ID: 7c1d3e9f-0a2b-4c4d-5e6f-7a8b9c0d1ec7
+async def analysis_clusters(
+    limit: int = Query(default=25, ge=1, le=200),
+) -> dict:
+    """Return semantic capability clusters."""
+    return await get_analysis_clusters(limit=limit)
+
+
+@analysis_router.get("/duplicates")
+# ID: 8d2e4f0a-1b3c-4d5e-6f7a-8b9c0d1e2fd8
+async def analysis_duplicates(
+    request: Request,
+    threshold: float = Query(default=0.85, ge=0.0, le=1.0),
+) -> dict:
+    """Return semantic code duplication candidates."""
+    core_context: CoreContext = request.app.state.core_context
+    return await get_analysis_duplicates(core_context, threshold=threshold)
+
+
+@analysis_router.get("/common-knowledge")
+# ID: 9e3f5a1b-2c4d-4e6f-7a8b-9c0d1e2f3ae9
+async def analysis_common_knowledge(
+    limit: int = Query(default=25, ge=1, le=200),
+) -> dict:
+    """Return DRY-violation candidates."""
+    return await get_analysis_common_knowledge(limit=limit)
+
+
+@analysis_router.get("/command-tree")
+# ID: 0f4a6b2c-3d5e-4f7a-8b9c-0d1e2f3a4bf0
+async def analysis_command_tree(request: Request) -> dict:
+    """Return the introspected CLI command hierarchy."""
+    core_context: CoreContext = request.app.state.core_context
+    return get_analysis_command_tree(core_context)
+
+
+@analysis_router.get("/test-targets")
+# ID: 1a5b7c3d-4e6f-4a8b-9c0d-1e2f3a4b5ce1
+async def analysis_test_targets(request: Request) -> dict:
+    """Return SIMPLE / COMPLEX classification for in-scope source files."""
+    core_context: CoreContext = request.app.state.core_context
+    return get_analysis_test_targets(core_context)
+
+
+# ---------- /components --------------------------------------------------
+
+
+@components_router.get("")
+# ID: 3b094d1e-e473-4044-9f46-16f6870f3946
+async def components_list(
+    filter_type: str | None = Query(default=None, alias="type"),
+) -> dict:
+    """Return the registered V2 component inventory across Mind/Body/Will."""
+    return get_components_list(filter_type=filter_type)
+
+
+# ---------- /search ------------------------------------------------------
+
+
+@search_router.get("/capabilities")
+# ID: 08ac8c57-ef92-4142-bf90-ba57bb0c6ce4
+async def search_capabilities(
+    request: Request,
+    q: str = Query(..., min_length=1),
+    limit: int = Query(default=10, ge=1, le=200),
+) -> dict:
+    """Semantic capability search via the Will cognitive service."""
+    core_context: CoreContext = request.app.state.core_context
+    return await get_search_capabilities(core_context, q=q, limit=limit)
+
+
+@search_router.get("/commands")
+# ID: 5c26c235-e80d-4da5-a942-f027fa7a087a
+async def search_commands(
+    q: str = Query(..., min_length=1),
+    limit: int = Query(default=25, ge=1, le=200),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Fuzzy substring search over the CLI command registry (ADR-057 D5)."""
+    return await get_search_commands(session, q=q, limit=limit)

api/v1/integration_routes.py

@@ -0,0 +1,56 @@
+# src/api/v1/integration_routes.py
+
+"""
+Integration API endpoint (ADR-054 Phase 1).
+
+POST /v1/integrate stages, formats, lints, and commits the working
+tree via will.lifecycle.integration_runner. Long-running but
+synchronous from the caller's perspective — there is no run-id to
+poll, so the CLI just awaits the response.
+
+CONSTITUTIONAL:
+- mind.* / body.* / shared.infrastructure.* are not imported here.
+  All work is delegated through will.lifecycle.integration_runner.
+- CoreContext comes from request.app.state.core_context.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.lifecycle.integration_runner import run_integration
+
+
+logger = getLogger(__name__)
+
+
+router = APIRouter(prefix="/integrate")
+
+
+# ID: fd724178-3586-48bb-a519-280de29821a3
+class IntegrateRequest(BaseModel):
+    """Body for POST /integrate."""
+
+    commit_message: str
+
+
+@router.post("")
+# ID: 578732cb-c976-4577-a6ef-3024e24d9833
+async def integrate(
+    payload: IntegrateRequest,
+    request: Request,
+) -> dict:
+    """Run the integration workflow (stage → format/lint → commit).
+
+    Returns 200 on success. Translates a failed workflow into a 502
+    so the CLI can render a clear error; the underlying exit_code is
+    surfaced in the detail object.
+    """
+    core_context: CoreContext = request.app.state.core_context
+    result = await run_integration(core_context, payload.commit_message)
+    if not result["ok"]:
+        raise HTTPException(status_code=502, detail=result)
+    return result

api/v1/integrity_routes.py

@@ -0,0 +1,72 @@
+# src/api/v1/integrity_routes.py
+
+"""
+Integrity API endpoints (ADR-055 D6 follow-up — closes #353).
+
+Two synchronous endpoints, both filesystem-only:
+
+* POST /integrity/baseline — SHA256-fingerprint src/ and write a
+  baseline manifest under var/integrity/. Returns the relative
+  manifest path and file count.
+* POST /integrity/verify   — diff current src/ against a saved
+  baseline. Returns ok / errors / checked_at.
+
+No core.integrity_runs persistence, no BackgroundTasks — operations
+are fast (single-digit seconds) and self-contained. Closest precedent
+is POST /fix/ir (also synchronous, also no persistence).
+
+CONSTITUTIONAL:
+- CoreContext is read from request.app.state.core_context.
+- shared.infrastructure.* is reached through the
+  will.governance.integrity_runner facade — no direct imports here.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Body, Request
+from pydantic import BaseModel
+
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.governance.integrity_runner import (
+    create_baseline,
+    verify_integrity,
+)
+
+
+logger = getLogger(__name__)
+
+
+router = APIRouter(prefix="/integrity")
+
+
+# ID: f3564baa-a7fb-4c21-a12d-25e06b416ea6
+class IntegrityRequest(BaseModel):
+    """Body for POST /integrity/baseline and POST /integrity/verify.
+
+    Empty body is valid and equivalent to label='default'.
+    """
+
+    label: str = "default"
+
+
+@router.post("/baseline")
+# ID: d93ed634-a710-4e61-ad28-88a5a35e1a0d
+async def integrity_baseline(
+    request: Request,
+    payload: IntegrityRequest = Body(default_factory=IntegrityRequest),
+) -> dict:
+    """Create a SHA256 baseline of src/ and return path + file count."""
+    core_context: CoreContext = request.app.state.core_context
+    return create_baseline(core_context, payload.label)
+
+
+@router.post("/verify")
+# ID: 804f2a54-a7c5-4900-afe2-f43e6702a6ee
+async def integrity_verify(
+    request: Request,
+    payload: IntegrityRequest = Body(default_factory=IntegrityRequest),
+) -> dict:
+    """Verify src/ against the named baseline and return ok / errors."""
+    core_context: CoreContext = request.app.state.core_context
+    return verify_integrity(core_context, payload.label)

api/v1/knowledge_routes.py

@@ -0,0 +1,36 @@
+# src/api/v1/knowledge_routes.py
+
+"""
+Knowledge API endpoints.
+
+CONSTITUTIONAL FIX (architecture.api.no_direct_database_access):
+Session dependency now routes through api.dependencies — the single
+sanctioned provider for the API layer.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.dependencies import get_api_session
+from shared.infrastructure.knowledge.knowledge_service import KnowledgeService
+
+
+router = APIRouter(prefix="/knowledge")
+
+
+@router.get("/capabilities")
+# ID: 0016df93-d0e5-45b0-b5b8-8f4170de3d9d
+async def list_capabilities(
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """
+    Return known capabilities.
+
+    Tests expect a 200 on GET /v1/knowledge/capabilities and a JSON object
+    with a 'capabilities' key.
+    """
+    service = KnowledgeService(session=session)
+    caps = await service.list_capabilities()
+    return {"capabilities": caps}

api/v1/lint_routes.py

@@ -0,0 +1,40 @@
+# src/api/v1/lint_routes.py
+
+"""
+Lint API endpoint (ADR-054 Phase 1).
+
+POST /v1/lint runs `black --check` + `ruff check` against src/ and
+tests/ via will.governance.lint_runner. The response always carries
+per-tool stdout/stderr so the CLI can render the actual findings
+even when the workflow reports non-zero.
+
+CONSTITUTIONAL: no mind.* / body.* / shared.infrastructure.* imports
+here; the lint subprocess work lives behind a Will facade.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from shared.logger import getLogger
+from will.governance.lint_runner import run_lint
+
+
+logger = getLogger(__name__)
+
+
+router = APIRouter(prefix="/lint")
+
+
+@router.post("")
+# ID: 923355cf-ad6d-446a-865f-539025a11428
+async def lint_endpoint() -> dict:
+    """Run black --check and ruff check on src/ and tests/.
+
+    Returns 200 with the structured result regardless of pass/fail —
+    the response's `ok` field carries the verdict, and `tools.*` carry
+    per-tool returncodes and captured output. This avoids the
+    "lint findings = HTTP error" anti-pattern; a clean lint and a
+    dirty lint are both successful API calls.
+    """
+    return await run_lint()

api/v1/proposals_routes.py

@@ -0,0 +1,267 @@
+# src/api/v1/proposals_routes.py
+
+"""
+Proposals API endpoints (ADR-054 Phase 1).
+
+Surfaces the core.autonomous_proposals state machine over HTTP so the
+CLI (and other governor-direct clients) can migrate off direct
+`will.*` / `shared.*` imports. The semantics — approval authority
+closed-set, claim sentinel, dry-run vs write — are unchanged from the
+CLI path; this module is a thin translation layer over
+ProposalService and ProposalExecutor.
+
+CONSTITUTIONAL:
+- Session access goes through api.dependencies.get_api_session only.
+- ProposalService is the facade; ProposalRepository and
+  ProposalStateManager are not imported here.
+- CoreContext is read from request.app.state.core_context — never
+  constructed in routes.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.dependencies import get_api_session
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.autonomy.proposal import (
+    Proposal,
+    ProposalAction,
+    ProposalScope,
+    ProposalStatus,
+)
+from will.autonomy.proposal_executor import ProposalExecutor
+from will.autonomy.proposal_service import ProposalService
+from will.autonomy.proposal_state_manager import ProposalNotFoundError
+
+
+logger = getLogger(__name__)
+
+
+# API claimer sentinel — distinct from CLI_CLAIMER_UUID
+# (cli/resources/proposals/manage.py uses ...0001). Mirrors the ADR-017
+# D4 pattern: governor-direct execution paths get a stable sentinel so
+# claimed_by lineage is queryable per surface.
+API_CLAIMER_UUID: Final[UUID] = UUID("00000000-0000-0000-0000-000000000002")
+
+
+router = APIRouter(prefix="/proposals")
+
+
+# ID: 5103629b-96d2-4c2c-8217-df99555ed221
+class ApproveRequest(BaseModel):
+    """Body for POST /proposals/{id}/approve."""
+
+    approved_by: str
+    approval_authority: str
+
+
+# ID: 3a74ddce-87c2-4528-a2f4-5ec68d171ea0
+class RejectRequest(BaseModel):
+    """Body for POST /proposals/{id}/reject."""
+
+    reason: str
+
+
+# ID: 57020012-ad90-461f-98d3-50f565b65294
+class ExecuteRequest(BaseModel):
+    """Body for POST /proposals/{id}/execute."""
+
+    write: bool = False
+
+
+# ID: 71caa34a-1661-4178-b982-626bff254539
+class CreateProposalRequest(BaseModel):
+    """Body for POST /proposals.
+
+    `write=False` is a dry-run: server builds the Proposal and computes
+    risk but does not persist. `write=True` persists via
+    ProposalService.create.
+    """
+
+    goal: str
+    actions: list[dict] = []
+    files: list[str] = []
+    created_by: str = "cli_operator"
+    write: bool = True
+
+
+@router.post("", status_code=201)
+# ID: 9704145a-25f5-460c-81a9-fe1fa0b47d68
+async def create_proposal(
+    payload: CreateProposalRequest,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Create a new proposal.
+
+    Validates the action sequence, computes risk, and (when write=True)
+    persists via ProposalService.create. Returns the proposal's
+    `to_dict()` representation either way; in dry-run mode the row
+    is not flushed to the database.
+    """
+    proposal_actions = [
+        ProposalAction(
+            action_id=a.get("action_id"),
+            flow_id=a.get("flow_id"),
+            parameters=a.get("parameters", {}),
+            order=a.get("order", i),
+        )
+        for i, a in enumerate(payload.actions)
+    ]
+    proposal = Proposal(
+        goal=payload.goal,
+        actions=proposal_actions,
+        scope=ProposalScope(files=payload.files),
+        created_by=payload.created_by,
+    )
+    proposal.compute_risk()
+
+    if payload.write:
+        service = ProposalService(session)
+        await service.create(proposal)
+        await session.commit()
+
+    return {
+        "ok": True,
+        "persisted": payload.write,
+        "proposal": proposal.to_dict(),
+    }
+
+
+@router.get("")
+# ID: b6575d68-b902-4071-8497-76b053430fec
+async def list_proposals(
+    status: str | None = Query(None, description="ProposalStatus value to filter by."),
+    limit: int = Query(50, ge=1),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """List proposals, optionally filtered by status.
+
+    When `status` is omitted, returns proposals awaiting approval.
+    """
+    service = ProposalService(session)
+
+    if status is None:
+        proposals = await service.list_pending_approval(limit=limit)
+    else:
+        try:
+            parsed = ProposalStatus(status)
+        except ValueError as exc:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"Invalid status {status!r}; allowed: "
+                    f"{[s.value for s in ProposalStatus]}"
+                ),
+            ) from exc
+        proposals = await service.list_by_status(parsed, limit=limit)
+
+    return {
+        "count": len(proposals),
+        "proposals": [p.to_dict() for p in proposals],
+    }
+
+
+@router.get("/{proposal_id}")
+# ID: f99b7ebf-5664-4642-9ac0-500b2fa56216
+async def get_proposal(
+    proposal_id: str,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Return a single proposal by id."""
+    service = ProposalService(session)
+    proposal = await service.get(proposal_id)
+    if proposal is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Proposal not found: {proposal_id}",
+        )
+    return proposal.to_dict()
+
+
+@router.post("/{proposal_id}/approve")
+# ID: 499722f9-8c4c-4d04-99b2-aed56329c592
+async def approve_proposal(
+    proposal_id: str,
+    payload: ApproveRequest,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Approve a pending proposal.
+
+    `approval_authority` is non-omittable per URS NFR.5 and validated
+    against the proposal_approval_authority closed set inside
+    ProposalStateManager.approve.
+    """
+    service = ProposalService(session)
+    try:
+        await service.approve(
+            proposal_id,
+            approved_by=payload.approved_by,
+            approval_authority=payload.approval_authority,
+        )
+    except ProposalNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {
+        "ok": True,
+        "proposal_id": proposal_id,
+        "status": ProposalStatus.APPROVED.value,
+        "approved_by": payload.approved_by,
+        "approval_authority": payload.approval_authority,
+    }
+
+
+@router.post("/{proposal_id}/reject")
+# ID: 5c3091dd-b88f-4ebf-8de5-285f24f90ef8
+async def reject_proposal(
+    proposal_id: str,
+    payload: RejectRequest,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Reject a proposal with a reason.
+
+    Per ADR-010 §7a, rejection is symmetric with mark_failed: findings
+    parked at deferred_to_proposal must be revived so they reach the
+    audit sensor for re-adjudication, otherwise they strand. Revival
+    flips them to awaiting_reaudit per ADR-045; the AuditViolationSensor
+    decides on the next cycle whether to release to 'open' or resolve.
+    """
+    service = ProposalService(session)
+    try:
+        revived_count = await service.reject(proposal_id, reason=payload.reason)
+    except ProposalNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    return {
+        "ok": True,
+        "proposal_id": proposal_id,
+        "status": ProposalStatus.REJECTED.value,
+        "reason": payload.reason,
+        "revived_count": revived_count,
+    }
+
+
+@router.post("/{proposal_id}/execute")
+# ID: aaa55146-21cc-4945-bb2e-d0e083dfd6ff
+async def execute_proposal(
+    proposal_id: str,
+    payload: ExecuteRequest,
+    request: Request,
+) -> dict:
+    """Execute an approved proposal (governor-direct override).
+
+    Defaults to dry-run; pass `{"write": true}` to apply changes.
+    ProposalExecutor manages its own session via service_registry, so
+    no get_api_session dependency is required here.
+    """
+    core_context: CoreContext = request.app.state.core_context
+    executor = ProposalExecutor(core_context)
+    return await executor.execute(proposal_id, API_CLAIMER_UUID, write=payload.write)