core-runtime 0.1.1__py3-none-any.whl

body/maintenance/scripts/vector_verify.py

@@ -0,0 +1,73 @@
+# src/body/maintenance/scripts/vector_verify.py
+"""
+Vector verification maintenance script.
+
+Constitutional constraints:
+- No direct instantiation of QdrantService. Must be resolved via DI/registry.
+- This script is orchestration logic; it must use existing services.
+"""
+
+from __future__ import annotations
+
+from shared.context import CoreContext
+from shared.logger import getLogger
+
+logger = getLogger(__name__)
+
+
+# ID: 0d7a1b4f-6d7f-4d5c-a6f6-5f7d2b0a9c2a
+async def run_vector_verify(context: CoreContext) -> dict[str, int]:
+    """
+    Verifies vector store consistency via the sanctioned service layer.
+
+    Returns:
+        A small summary dict with counts (kept intentionally stable for CLI consumption).
+    """
+    if context is None:
+        raise ValueError("CoreContext is required")
+
+    # Resolve QdrantService via DI
+    qdrant_service = getattr(context, "qdrant_service", None)
+    if qdrant_service is None:
+        registry = getattr(context, "registry", None)
+        if registry is None:
+            raise RuntimeError(
+                "No qdrant_service on context and no registry available to resolve it."
+            )
+        qdrant_service = await registry.get_qdrant_service()
+        context.qdrant_service = qdrant_service
+
+    # Delegate to service methods only (no direct qdrant_service.client.* usage here)
+    # NOTE: Adapt these calls to the actual methods you expose (names below are intentionally generic).
+    stats: dict[str, int] = {
+        "points_total": 0,
+        "points_orphaned": 0,
+        "links_total": 0,
+    }
+
+    try:
+        # If your QdrantService exposes collection stats:
+        if hasattr(qdrant_service, "count_points"):
+            stats["points_total"] = int(await qdrant_service.count_points())
+        # If your QdrantService exposes orphan detection:
+        if hasattr(qdrant_service, "count_orphaned_points"):
+            stats["points_orphaned"] = int(await qdrant_service.count_orphaned_points())
+    except Exception as e:
+        logger.warning("Vector verify: unable to read Qdrant counts: %s", e)
+
+    # Postgres link stats should be obtained via your existing DB service layer;
+    # keep this script minimal and constitutional.
+    try:
+        kg = getattr(context, "knowledge_service", None)
+        if kg and hasattr(kg, "count_vector_links"):
+            stats["links_total"] = int(await kg.count_vector_links())
+    except Exception as e:
+        logger.warning("Vector verify: unable to read DB link counts: %s", e)
+
+    logger.info(
+        "Vector verify summary: points_total=%s, points_orphaned=%s, links_total=%s",
+        stats["points_total"],
+        stats["points_orphaned"],
+        stats["links_total"],
+    )
+    return stats

body/maintenance/sync_vectors.py

@@ -0,0 +1,338 @@
+# src/body/maintenance/sync_vectors.py
+
+"""
+Atomic vector synchronization between PostgreSQL and Qdrant.
+
+This tool performs a complete bidirectional sync to ensure consistency:
+1. Prune orphaned vectors from Qdrant (vectors without DB links)
+2. Prune dangling links from PostgreSQL (links to missing vectors)
+
+These operations MUST happen in this order to avoid race conditions.
+Running them together atomically prevents partial sync states.
+
+CONSTITUTIONAL FIX: Uses VectorLinkRepository with proper transaction boundaries.
+Transaction management at controller level, not service level.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from qdrant_client import AsyncQdrantClient
+from qdrant_client.http.models import PointIdsList
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# REFACTORED: Removed direct settings import
+from shared.infrastructure.clients.qdrant_client import QdrantService
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.infrastructure.repositories.vector_link_repository import (
+    VectorLinkRepository,
+)
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG_VEC = load_operational_config().vectors
+
+
+async def _fetch_all_qdrant_ids(
+    client: AsyncQdrantClient, collection_name: str
+) -> set[str]:
+    """
+    Fetch all point IDs from the configured Qdrant collection.
+
+    Uses scroll with pagination to handle large collections robustly.
+
+    Args:
+        client: Qdrant async client.
+        collection_name: Name of the Qdrant collection to scroll.
+    """
+    all_ids: set[str] = set()
+    offset: str | None = None
+    while True:
+        points, offset = await client.scroll(
+            collection_name=collection_name,
+            limit=_CFG_VEC.scan_limit,
+            with_payload=False,
+            with_vectors=False,
+            offset=offset,
+        )
+        if not points:
+            break
+        all_ids.update(str(point.id) for point in points)
+        if offset is None:
+            break
+    return all_ids
+
+
+async def _fetch_db_vector_ids(session: AsyncSession) -> set[str]:
+    """
+    Load all valid vector IDs from core.symbol_vector_links.
+
+    Args:
+        session: Injected database session
+
+    Returns a set of vector_id values cast to text for normalization.
+    """
+    result = await session.execute(
+        text(
+            "SELECT vector_id::text FROM core.symbol_vector_links WHERE vector_id IS NOT NULL"
+        )
+    )
+    return {str(row[0]) for row in result}
+
+
+async def _fetch_db_links(session: AsyncSession) -> list[tuple[str, str]]:
+    """
+    Load all (symbol_id, vector_id) pairs from core.symbol_vector_links.
+
+    Args:
+        session: Injected database session
+
+    Returns list of tuples for deletion operations.
+    """
+    result = await session.execute(
+        text(
+            """
+                SELECT symbol_id::text, vector_id::text
+                FROM core.symbol_vector_links
+                WHERE vector_id IS NOT NULL
+                """
+        )
+    )
+    return [(row[0], row[1]) for row in result]
+
+
+async def _prune_orphaned_vectors(
+    client: AsyncQdrantClient,
+    qdrant_ids: set[str],
+    db_vector_ids: set[str],
+    dry_run: bool,
+    collection_name: str,
+) -> int:
+    """
+    Find and delete vectors in Qdrant that have no corresponding DB link.
+
+    Returns the count of orphaned vectors found (and deleted if not dry_run).
+    """
+    orphaned_ids = list(qdrant_ids - db_vector_ids)
+    if not orphaned_ids:
+        logger.info("No orphaned vectors found in Qdrant.")
+        return 0
+    logger.info("Found %s orphaned vector(s) in Qdrant.", len(orphaned_ids))
+    if dry_run:
+        preview = _CFG_VEC.report_preview_count
+        logger.debug("Would delete from Qdrant")
+        for point_id in orphaned_ids[:preview]:
+            logger.debug("  - %s", point_id)
+        if len(orphaned_ids) > preview:
+            logger.debug("  - ... and %s more.", len(orphaned_ids) - preview)
+        return len(orphaned_ids)
+    logger.info("Deleting %s orphaned vector(s) from Qdrant...", len(orphaned_ids))
+    await client.delete(
+        collection_name=collection_name,
+        points_selector=PointIdsList(points=orphaned_ids),
+    )
+    logger.info("Deleted %s orphaned vector(s).", len(orphaned_ids))
+    return len(orphaned_ids)
+
+
+async def _delete_dangling_links(
+    dangling_links: Iterable[tuple[str, str]], session: AsyncSession
+) -> int:
+    """
+    Delete dangling links from core.symbol_vector_links.
+
+    CONSTITUTIONAL FIX: Uses Repository, no commit (caller manages transaction).
+
+    Args:
+        dangling_links: List of (symbol_id, vector_id) tuples
+        session: Database session (caller manages transaction boundary)
+
+    Returns:
+        Count of deleted links
+    """
+    repo = VectorLinkRepository(session)
+    count = await repo.delete_dangling_links(list(dangling_links))
+
+    # NO COMMIT - caller manages transaction
+    return count
+
+
+async def _prune_dangling_links(
+    db_links: list[tuple[str, str]],
+    qdrant_ids: set[str],
+    session: AsyncSession,
+    dry_run: bool,
+) -> int:
+    """
+    Find and delete DB links pointing to non-existent Qdrant vectors.
+
+    CONSTITUTIONAL: Transaction boundary managed at this controller level.
+
+    Args:
+        db_links: List of (symbol_id, vector_id) tuples from database
+        qdrant_ids: Set of vector IDs currently in Qdrant
+        session: Injected database session
+        dry_run: If True, only report what would be deleted
+
+    Returns the count of dangling links found (and deleted if not dry_run).
+    """
+    dangling_links = [
+        (symbol_id, vector_id)
+        for symbol_id, vector_id in db_links
+        if vector_id not in qdrant_ids
+    ]
+    if not dangling_links:
+        logger.info("No dangling links found in PostgreSQL.")
+        return 0
+    logger.info("Found %s dangling link(s) in PostgreSQL.", len(dangling_links))
+    if dry_run:
+        preview = _CFG_VEC.report_preview_count
+        logger.debug("Would delete from PostgreSQL")
+        for symbol_id, vector_id in dangling_links[:preview]:
+            logger.debug("  - symbol_id=%s, vector_id=%s", symbol_id, vector_id)
+        if len(dangling_links) > preview:
+            logger.debug("  - ... and %s more.", len(dangling_links) - preview)
+        return len(dangling_links)
+
+    logger.info("Deleting %s dangling link(s) from PostgreSQL...", len(dangling_links))
+
+    # CONTROLLER MANAGES TRANSACTION BOUNDARY
+    deleted_count = await _delete_dangling_links(dangling_links, session)
+    await session.commit()  # Transaction boundary at controller level
+
+    logger.info("Deleted %s dangling link(s).", deleted_count)
+    return deleted_count
+
+
+async def _async_sync_vectors(
+    session: AsyncSession,
+    dry_run: bool,
+    qdrant_service: QdrantService | None = None,
+    qdrant_url: str | None = None,
+    collection_name: str | None = None,
+) -> tuple[int, int]:
+    """
+    Core async logic for complete vector synchronization.
+
+    Args:
+        session: Injected database session
+        dry_run: If True, only report what would be changed
+        qdrant_service: Optional injected Qdrant service
+        qdrant_url: Qdrant server URL (required when qdrant_service is None)
+        collection_name: Qdrant collection name
+
+    Returns (orphans_pruned, dangling_pruned) counts.
+    """
+    if collection_name is None:
+        raise ValueError("collection_name is required for vector sync")
+
+    logger.info("Starting vector synchronization...")
+    if dry_run:
+        logger.info("DRY RUN MODE: No changes will be made.")
+    logger.info("Phase 0: Loading current state...")
+    if qdrant_service is None:
+        if qdrant_url is None:
+            raise ValueError(
+                "qdrant_url is required when qdrant_service is not provided"
+            )
+        client = AsyncQdrantClient(url=qdrant_url)
+    else:
+        client = qdrant_service.client
+    logger.info("Fetching vector IDs from Qdrant...")
+    qdrant_ids = await _fetch_all_qdrant_ids(client, collection_name)
+    logger.info("Found %s vectors in Qdrant.", len(qdrant_ids))
+    logger.info("Fetching vector links from PostgreSQL...")
+    db_vector_ids = await _fetch_db_vector_ids(session)
+    db_links = await _fetch_db_links(session)
+    logger.info("Found %s valid vector IDs in PostgreSQL.", len(db_vector_ids))
+    logger.info("Found %s total symbol-vector links.", len(db_links))
+    logger.info("Phase 1: Pruning orphaned vectors from Qdrant...")
+    orphans_pruned = await _prune_orphaned_vectors(
+        client, qdrant_ids, db_vector_ids, dry_run, collection_name
+    )
+    logger.info("Phase 2: Pruning dangling links from PostgreSQL...")
+    dangling_pruned = await _prune_dangling_links(
+        db_links, qdrant_ids, session, dry_run
+    )
+    logger.info("Synchronization Summary")
+    logger.info("  • Orphaned vectors pruned: %s", orphans_pruned)
+    logger.info("  • Dangling links pruned: %s", dangling_pruned)
+    if orphans_pruned == 0 and dangling_pruned == 0:
+        logger.info("Vector store is perfectly synchronized!")
+    elif dry_run:
+        logger.info("Issues found. Run with --write to fix them.")
+    else:
+        logger.info("Synchronization complete!")
+    return (orphans_pruned, dangling_pruned)
+
+
+# ID: 2ba0085c-70d8-4a2f-b3f5-a41479fba562
+async def main_sync(
+    session: AsyncSession,
+    write: bool = False,
+    dry_run: bool = False,
+    qdrant_url: str | None = None,
+    collection_name: str | None = None,
+) -> None:
+    """
+    Synchronize vector database between PostgreSQL and Qdrant.
+
+    This performs atomic bidirectional synchronization:
+    1. Removes orphaned vectors from Qdrant (no DB link)
+    2. Removes dangling links from PostgreSQL (no Qdrant vector)
+
+    Args:
+        session: Injected database session
+        write: If True, apply changes (default: False)
+        dry_run: If True, only report what would change (default: False)
+        qdrant_url: Qdrant server URL
+        collection_name: Qdrant collection name
+
+    Example:
+        poetry run core-admin fix vector-sync --dry-run
+        poetry run core-admin fix vector-sync --write
+    """
+    effective_dry_run = dry_run or not write
+    await _async_sync_vectors(
+        session,
+        dry_run=effective_dry_run,
+        qdrant_url=qdrant_url,
+        collection_name=collection_name,
+    )
+
+
+# ID: 45b243cb-5331-464d-a50d-13a1310e672a
+async def main_async(
+    session: AsyncSession,
+    write: bool = False,
+    dry_run: bool = False,
+    qdrant_service: QdrantService | None = None,
+    qdrant_url: str | None = None,
+    collection_name: str | None = None,
+) -> tuple[int, int]:
+    """
+    Async entry point for orchestrators that own the event loop.
+    Accepts optional qdrant_service for JIT injection.
+
+    Args:
+        session: Injected database session
+        write: If True, apply changes (default: False)
+        dry_run: If True, only report what would change (default: False)
+        qdrant_service: Optional injected Qdrant service
+        qdrant_url: Qdrant server URL (used when qdrant_service is None)
+        collection_name: Qdrant collection name
+
+    Returns (orphans_pruned, dangling_pruned) counts.
+    """
+    effective_dry_run = dry_run or not write
+    return await _async_sync_vectors(
+        session,
+        dry_run=effective_dry_run,
+        qdrant_service=qdrant_service,
+        qdrant_url=qdrant_url,
+        collection_name=collection_name,
+    )

body/models/__init__.py

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

body/project_lifecycle/__init__.py

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

body/project_lifecycle/bootstrap_service.py

@@ -0,0 +1,157 @@
+# src/body/project_lifecycle/bootstrap_service.py
+
+"""
+Provides CLI commands for bootstrapping the project with initial setup tasks,
+such as creating a default set of GitHub issues for a new repository.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from shared.exceptions import CoreError
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: e8db5a13-a0a3-4581-afe2-354656ed8c4b
+class BootstrapError(CoreError):
+    """Raised when project bootstrap fails."""
+
+
+ISSUES_TO_CREATE = [
+    {
+        "title": "Add JSON logging & request IDs",
+        "body": (
+            "**Goal**: Switch logger to support LOG_FORMAT=json and add request-id "
+            "middleware in FastAPI.\n\n"
+            "**Acceptance**\n"
+            "- LOG_FORMAT=json writes structured logs\n"
+            "- x-request-id is set and propagated\n"
+            "- Documentation updated in docs/CONVENTIONS.md"
+        ),
+        "labels": "roadmap,organizational,ci",
+    },
+    {
+        "title": "Pre-commit hooks (Black, Ruff)",
+        "body": (
+            "**Goal**: Add .pre-commit-config.yaml and wire it into Make.\n\n"
+            "**Acceptance**\n"
+            "- pre-commit runs Black and Ruff locally\n"
+            "- CI remains green"
+        ),
+        "labels": "roadmap,organizational,ci",
+    },
+    {
+        "title": "Docs: CONVENTIONS.md & DEPENDENCIES.md",
+        "body": (
+            "**Goal**: Codify folder structure, import rules, capability tags, "
+            "and dependency policy.\n\n"
+            "**Acceptance**\n"
+            "- New contributors can place files without guidance\n"
+            "- Import discipline matrix documented"
+        ),
+        "labels": "roadmap,organizational,docs",
+    },
+    {
+        "title": "Governance: proposal schema & lifecycle validation",
+        "body": (
+            "**Goal**: Define and validate the proposal lifecycle for "
+            "`work/proposals/`.\n\n"
+            "**Acceptance**\n"
+            "- Proposals are treated as operational artefacts (not constitutional files)\n"
+            "- Auditor ignores `work/` for schema enforcement\n"
+            "- Proposal approval flow is exercised end-to-end\n"
+            "- At least one example proposal exists under work/proposals/"
+        ),
+        "labels": "roadmap,organizational,audit",
+    },
+]
+
+LABELS_TO_ENSURE = [
+    {"name": "roadmap", "color": "0366d6", "desc": "Roadmap item"},
+    {"name": "organizational", "color": "a2eeef", "desc": "Project organization"},
+    {"name": "ci", "color": "7057ff", "desc": "CI/CD"},
+    {"name": "audit", "color": "d73a4a", "desc": "Governance & audit"},
+    {"name": "docs", "color": "0e8a16", "desc": "Documentation"},
+]
+
+
+def _run_gh_command(command: list[str], ignore_errors: bool = False):
+    """Helper to run a 'gh' command and handle errors."""
+    if not shutil.which("gh"):
+        logger.error("'gh' (GitHub CLI) not found in PATH.")
+        logger.info("Install GitHub CLI to use bootstrap features.")
+        raise BootstrapError("'gh' (GitHub CLI) not found in PATH.", exit_code=1)
+
+    try:
+        subprocess.run(command, check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as e:
+        if not ignore_errors:
+            logger.error("Error running gh command: %s", e.stderr)
+            raise BootstrapError("Error running gh command.", exit_code=1) from e
+
+
+# ID: 17f7cac0-4134-4885-93fb-0d432c634ed1
+def bootstrap_issues(repo: str | None = None) -> None:
+    """Create a standard set of starter issues for the project on GitHub."""
+    logger.info("Bootstrapping standard GitHub issues...")
+    logger.info("Ensuring required labels exist...")
+
+    for label in LABELS_TO_ENSURE:
+        cmd = [
+            "gh",
+            "label",
+            "create",
+            label["name"],
+            "--color",
+            label["color"],
+            "--description",
+            label["desc"],
+        ]
+        if repo:
+            cmd.extend(["--repo", repo])
+        _run_gh_command(cmd, ignore_errors=True)
+
+    logger.info("Creating %s starter issues...", len(ISSUES_TO_CREATE))
+
+    for issue in ISSUES_TO_CREATE:
+        cmd = [
+            "gh",
+            "issue",
+            "create",
+            "--title",
+            issue["title"],
+            "--body",
+            issue["body"],
+            "--label",
+            issue["labels"],
+        ]
+        if repo:
+            cmd.extend(["--repo", repo])
+        _run_gh_command(cmd)
+
+    logger.info("Successfully created starter issues on GitHub.")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Bootstrap starter GitHub issues and labels."
+    )
+    parser.add_argument(
+        "--repo",
+        help="GitHub repository in 'owner/repo' format.",
+        default=None,
+    )
+
+    args = parser.parse_args()
+
+    try:
+        bootstrap_issues(repo=args.repo)
+    except BootstrapError as exc:
+        raise SystemExit(exc.exit_code) from exc