core-runtime 0.1.1__py3-none-any.whl

body/services/blackboard_service/blackboard_proposal_service.py

@@ -0,0 +1,305 @@
+# src/body/services/blackboard_service/blackboard_proposal_service.py
+# blackboard_proposal_service.py
+"""Proposal-lifecycle methods that implement the finding↔proposal contract per CORE-Finding.md §7/§7a"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import text
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: f83444e2-fae1-46f0-a704-d592d62a116e
+class BlackboardProposalService:
+    # ID: 7f2a3c51-b9d0-48e4-9d2b-4a6f1e8c0b52
+    async def defer_entries_to_proposal(
+        self, entry_ids: list[str], proposal_id: str
+    ) -> int:
+        """
+        Transition findings to 'deferred_to_proposal' terminal status and
+        write the proposal_id into each finding's payload.
+
+        Implements CORE-Finding.md §7 row 4:
+          > The rule has an active RemediationMap entry. A Proposal has been
+          > created. The `proposal_id` field in the payload MUST be set to
+          > the created Proposal's ID.
+
+        Only transitions entries currently in 'open' or 'claimed' — matches
+        the predicate used by resolve_entries. Entries in any other status
+        are left untouched and not counted.
+
+        Sets resolved_at because 'deferred_to_proposal' is terminal per
+        the blackboard_entry_status enum declaration in
+        .intent/META/enums.json.
+
+        Payload merge uses the 'payload = payload || jsonb_build_object(...)'
+        idiom already established elsewhere in this service. If an earlier
+        proposal_id was written (e.g. in unusual retry flows), this call
+        overwrites it with the current value — last-writer-wins, which
+        matches the semantic "this finding is now linked to THIS proposal."
+
+        Returns the count of rows actually updated.
+
+        Covers:
+          - ViolationRemediatorWorker._defer_to_proposal
+        """
+        if not entry_ids:
+            return 0
+
+        from body.services.service_registry import ServiceRegistry
+
+        deferred_count = 0
+        async with ServiceRegistry.session() as session:
+            async with session.begin():
+                for entry_id in entry_ids:
+                    result = await session.execute(
+                        text(
+                            """
+                            UPDATE core.blackboard_entries
+                            SET status = 'deferred_to_proposal',
+                                resolved_at = now(),
+                                updated_at = now(),
+                                payload = payload || jsonb_build_object(
+                                    'proposal_id', cast(:proposal_id as text)
+                                )
+                            WHERE id = cast(:entry_id as uuid)
+                              AND status IN ('open', 'claimed')
+                            """
+                        ),
+                        {"entry_id": entry_id, "proposal_id": proposal_id},
+                    )
+                    deferred_count += result.rowcount
+        return deferred_count
+
+    # ID: 5e2d8f1a-94c3-4b07-a8f2-3c7e9b1d6a45
+    async def resolve_entries_for_proposal(
+        self, entry_ids: list[str], proposal_id: str
+    ) -> int:
+        """
+        Mark each entry in *entry_ids* as resolved AND store the subsuming
+        *proposal_id* in its payload. Mirror of defer_entries_to_proposal,
+        but with terminal status 'resolved' instead of 'deferred_to_proposal'.
+
+        Used by ViolationRemediatorWorker's dedup-subsume path: when a
+        finding is subsumed by an already-active proposal, it closes as
+        'resolved' (the subsuming proposal does not track it in its scope,
+        so the §7a revival path does not apply), but the payload pointer
+        to the subsuming proposal_id makes the linkage auditable per URS
+        Q1.F and ADR-015 D4.
+
+        Bare resolve_entries (no proposal_id) remains in use by
+        TestRemediatorWorker and TestRunnerSensor — those callers do not
+        carry a proposal_id at the resolve site and should not be forced
+        to invent one.
+
+        Predicate matches resolve_entries and defer_entries_to_proposal:
+        only entries currently in 'open' or 'claimed' transition; rows
+        already terminalized or missing are not counted. All updates run
+        inside a single transaction. Returns the count of rows actually
+        updated.
+
+        Covers:
+          - ViolationRemediatorWorker._resolve_entries (dedup-subsume path)
+        """
+        if not entry_ids:
+            return 0
+
+        from body.services.service_registry import ServiceRegistry
+
+        resolved_count = 0
+        async with ServiceRegistry.session() as session:
+            async with session.begin():
+                for entry_id in entry_ids:
+                    result = await session.execute(
+                        text(
+                            """
+                            UPDATE core.blackboard_entries
+                            SET status = 'resolved',
+                                resolved_at = now(),
+                                updated_at = now(),
+                                payload = payload || jsonb_build_object(
+                                    'proposal_id', cast(:proposal_id as text)
+                                )
+                            WHERE id = cast(:entry_id as uuid)
+                              AND status IN ('open', 'claimed')
+                            """
+                        ),
+                        {"entry_id": entry_id, "proposal_id": proposal_id},
+                    )
+                    resolved_count += result.rowcount
+        return resolved_count
+
+    # ID: e1c4b8a7-6f03-4d29-b8a2-9c5d7e0f3a14
+    async def revive_findings_for_failed_proposal(
+        self, proposal_id: str, failure_reason: str
+    ) -> dict[str, Any] | None:
+        """
+        Restore findings that were deferred to a now-failed proposal back
+        to active status, and return the revival outcome.
+
+        Implements CORE-Finding.md §7a steps 1-2 (state transition only).
+        §7a step 3 (posting a `report` entry recording the revival) is the
+        calling Worker's responsibility per ADR-011 — this method is
+        UPDATE-only. The Worker consumes this method's return value and
+        posts the revival report via self.post_report() so the entry
+        carries Worker attribution.
+
+        Revival target is 'awaiting_reaudit', not 'open' (ADR-045). The
+        finding's payload was authored when the violation was originally
+        posted; after a proposal failure or rejection the underlying file
+        may have been refactored, the rule's threshold may have moved, or
+        the governor may judge the finding stale. Routing the finding
+        through awaiting_reaudit gates the remediator's claim queue until
+        AuditViolationSensor's next cycle re-evaluates the rule against
+        the current file state and either releases the finding to 'open'
+        (violation still holds) or resolves it (cleared). The previous
+        immediate-revival-to-'open' behaviour produced a temporal race
+        where the remediator could re-claim a stale finding before the
+        audit sensor's next cycle ran.
+
+        The UPDATE filter restricts to status = 'deferred_to_proposal'. This
+        protects against retry races and against findings that drifted to
+        some other status (abandoned, indeterminate) for unrelated reasons
+        — only findings still parked on this proposal's deferral are
+        revived. resolved_at is cleared so the row's terminal-state marker
+        matches its new non-terminal status (ADR-010 hygiene rule, tracking
+        the Option A+ convention from 2026-04-22).
+
+        Returns:
+          None if no findings were revived (revived_count == 0) — nothing
+          to report.
+          dict with keys ``proposal_id``, ``failure_reason``,
+          ``revived_count``, ``revived_finding_ids``, ``revived_subjects``
+          when one or more rows were revived. Both id and subject lists
+          are returned — IDs for precise downstream queries, subjects for
+          human-readable audit trails in the revival report payload.
+
+        The caller MUST NOT rely on this method raising on partial failure.
+        Zero rows revived is a legitimate outcome when the failed proposal
+        had no findings deferred to it (e.g. proposals created by paths
+        other than ViolationRemediatorWorker); the caller receives None
+        and skips posting a revival report.
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            async with session.begin():
+                # §7a steps 1+2: query-and-reset in one UPDATE ... RETURNING.
+                # RETURNING id, subject so the Worker can persist both in
+                # the revival report payload (IDs for queries, subjects for
+                # audit trails).
+                update_result = await session.execute(
+                    text(
+                        """
+                        UPDATE core.blackboard_entries
+                        SET status = 'awaiting_reaudit',
+                            claimed_by = NULL,
+                            claimed_at = NULL,
+                            resolved_at = NULL,
+                            updated_at = now()
+                        WHERE entry_type = 'finding'
+                          AND status = 'deferred_to_proposal'
+                          AND payload->>'proposal_id' = :proposal_id
+                        RETURNING id, subject
+                        """
+                    ),
+                    {"proposal_id": proposal_id},
+                )
+                rows = update_result.fetchall()
+                revived_ids = [str(row[0]) for row in rows]
+                revived_subjects = [str(row[1]) for row in rows]
+
+        logger.info(
+            "Revived %d finding(s) for failed proposal %s (reason: %s)",
+            len(revived_ids),
+            proposal_id,
+            failure_reason,
+        )
+
+        if not revived_ids:
+            return None
+
+        return {
+            "proposal_id": proposal_id,
+            "failure_reason": failure_reason,
+            "revived_count": len(revived_ids),
+            "revived_finding_ids": revived_ids,
+            "revived_subjects": revived_subjects,
+        }
+
+    # ID: 90c7c05a-a380-4d5a-9b1e-a911c3ed5d02
+    async def resolve_deferred_entries_for_completed_proposal(
+        self, proposal_id: str
+    ) -> dict[str, Any] | None:
+        """
+        Mark findings deferred to a now-completed proposal as 'resolved'
+        and return the resolution outcome.
+
+        Success-side mirror of revive_findings_for_failed_proposal: flips
+        every finding whose payload.proposal_id matches *proposal_id* and
+        is still parked in 'deferred_to_proposal' to terminal 'resolved'
+        status, closing the §7-style finding↔proposal lifecycle.
+
+        The UPDATE filter restricts to status = 'deferred_to_proposal' so
+        findings that drifted elsewhere (abandoned, manually overridden)
+        are not retroactively re-terminalized. resolved_at is set per the
+        ADR-010 hygiene rule for terminal-state rows.
+
+        Unlike the failure-revival counterpart this method does not post
+        a downstream report: no new entry is created (only existing rows
+        are flipped), so the ADR-011 Worker-attribution rule does not
+        apply. The caller (ProposalExecutor) is therefore not required
+        to be a Worker subclass.
+
+        Returns:
+          None if no findings were resolved (resolved_count == 0) —
+          nothing to report.
+          dict with keys ``proposal_id``, ``resolved_count``,
+          ``resolved_finding_ids``, ``resolved_subjects`` when one or
+          more rows were resolved. Both id and subject lists are
+          returned — IDs for precise downstream queries, subjects for
+          human-readable audit trails.
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            async with session.begin():
+                update_result = await session.execute(
+                    text(
+                        """
+                        UPDATE core.blackboard_entries
+                        SET status = 'resolved',
+                            resolved_at = now(),
+                            updated_at = now()
+                        WHERE entry_type = 'finding'
+                          AND status = 'deferred_to_proposal'
+                          AND payload->>'proposal_id' = :proposal_id
+                        RETURNING id, subject
+                        """
+                    ),
+                    {"proposal_id": proposal_id},
+                )
+                rows = update_result.fetchall()
+                resolved_ids = [str(row[0]) for row in rows]
+                resolved_subjects = [str(row[1]) for row in rows]
+
+        logger.info(
+            "Resolved %d deferred finding(s) for completed proposal %s",
+            len(resolved_ids),
+            proposal_id,
+        )
+
+        if not resolved_ids:
+            return None
+
+        return {
+            "proposal_id": proposal_id,
+            "resolved_count": len(resolved_ids),
+            "resolved_finding_ids": resolved_ids,
+            "resolved_subjects": resolved_subjects,
+        }

body/services/blackboard_service/blackboard_query_service.py

@@ -0,0 +1,333 @@
+# src/body/services/blackboard_service/blackboard_query_service.py
+"""Pure-read query methods — SELECT only, no mutations."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from sqlalchemy import text
+
+from shared.infrastructure.intent.operational_config import load_operational_config
+
+
+_SLA: dict[str, int] = {
+    "heartbeat": 600,
+    "finding": 3600,
+    "report": 7200,
+    "proposal": 1800,
+}
+
+_CFG = load_operational_config().blackboard
+
+
+# ID: 0f7e0bf6-9fba-44b1-9605-b7dcadf97fac
+class BlackboardQueryService:
+    # ID: b980a1a9-eca8-4268-b8ba-86fbcf94b6ce
+    async def fetch_open_finding_subjects_by_prefix(self, prefix: str) -> set[str]:
+        """
+        Return subjects of non-terminal finding entries whose subject matches
+        *prefix* (SQL LIKE pattern — caller supplies the trailing wildcard).
+
+        'suppressed' is treated as terminal and excluded — suppressed entries
+        are not "open" by any definition. (See #263 for the suppressed/abandoned
+        split: only ``fetch_active_finding_subjects_by_prefix`` keeps suppressed
+        in its result set, because dedup-vs-permanent-skip is its purpose.)
+
+        'awaiting_reaudit' (ADR-045) is NOT excluded — those rows are
+        non-terminal and represent unresolved work that has not yet been
+        adjudicated by the audit sensor's release pass.
+
+        Covers:
+          - AuditViolationSensor._fetch_existing_subjects
+          - BlackboardShopManager._fetch_existing_findings
+          - IntentInspector._fetch_existing_subjects
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            result = await session.execute(
+                text(
+                    """
+                    SELECT subject FROM core.blackboard_entries
+                    WHERE entry_type = 'finding'
+                      AND subject LIKE :prefix
+                      AND status NOT IN (
+                          'resolved',
+                          'abandoned',
+                          'suppressed',
+                          'dry_run_complete',
+                          'deferred_to_proposal',
+                          'indeterminate'
+                      )
+                    """
+                ),
+                {"prefix": prefix},
+            )
+            return {row[0] for row in result.fetchall()}
+
+    # ID: 9c4e1f7a-2b3d-4e85-a6f7-90bc8d1e2f43
+    async def fetch_awaiting_reaudit_subjects_by_prefix(self, prefix: str) -> set[str]:
+        """
+        Return subjects of awaiting_reaudit finding entries matching *prefix*.
+
+        Used by quarantine drainers (ADR-072) to determine the scope of
+        work for the current drain cycle — e.g. TestRunnerSensor uses this
+        to enumerate test_files referenced by quarantined test.failure
+        rows so it can re-run pytest only for what is actually parked.
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            result = await session.execute(
+                text(
+                    """
+                    SELECT subject FROM core.blackboard_entries
+                    WHERE entry_type = 'finding'
+                      AND status = 'awaiting_reaudit'
+                      AND subject LIKE :prefix
+                    """
+                ),
+                {"prefix": prefix},
+            )
+            return {row[0] for row in result.fetchall()}
+
+    # ID: 1b8e7a4c-3f2d-4c5b-9a01-8e6d2f9b0a31
+    async def fetch_active_finding_subjects_by_prefix(self, prefix: str) -> set[str]:
+        """
+        Return subjects of finding entries whose subject matches *prefix*
+        that should be treated as "still on the board" for sensor dedup.
+
+        Sensor-dedup contract (see #263 for the rationale):
+
+        - 'resolved' is excluded: the issue is closed; the sensor MAY re-post
+          if it re-detects the same subject (re-emergence is meaningful).
+        - 'abandoned' is excluded: workers gave up on this entry without
+          resolving the underlying issue, so a fresh detection deserves a
+          fresh entry — re-emit is correct.
+        - 'suppressed' is INTENTIONALLY KEPT in the result set: it is the
+          governor's deliberate "do not surface this again" signal. Its
+          subject must remain in the dedup set so sensors skip it
+          permanently.
+        - All other statuses (open, claimed, deferred_to_proposal,
+          indeterminate, awaiting_reaudit per ADR-045) are included —
+          those subjects are still on the board (active or quarantined)
+          and a sensor must not pile on duplicates.
+
+        Covers:
+          - AuditViolationSensor._fetch_existing_subjects
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            result = await session.execute(
+                text(
+                    """
+                    SELECT subject FROM core.blackboard_entries
+                    WHERE entry_type = 'finding'
+                      AND subject LIKE :prefix
+                      AND status NOT IN ('resolved', 'abandoned')
+                    """
+                ),
+                {"prefix": prefix},
+            )
+            return {row[0] for row in result.fetchall()}
+
+    # ID: d98fae16-259d-4993-9e10-4b18c7ea7a70
+    async def fetch_open_finding_subjects_by_worker(
+        self, worker_uuid: str, prefix: str
+    ) -> set[str]:
+        """
+        Return subjects of non-terminal finding entries posted by *worker_uuid*
+        whose subject matches *prefix*.
+
+        'suppressed' is treated as terminal and excluded — see #263.
+
+        Covers:
+          - AuditIngestWorker._fetch_existing_subjects
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            result = await session.execute(
+                text(
+                    """
+                    SELECT subject FROM core.blackboard_entries
+                    WHERE worker_uuid = :worker_uuid
+                      AND entry_type = 'finding'
+                      AND subject LIKE :prefix
+                      AND status NOT IN (
+                          'resolved',
+                          'abandoned',
+                          'suppressed',
+                          'dry_run_complete',
+                          'deferred_to_proposal',
+                          'indeterminate'
+                      )
+                    """
+                ),
+                {"worker_uuid": worker_uuid, "prefix": prefix},
+            )
+            return {row[0] for row in result.fetchall()}
+
+    # ID: e38d5bb0-ad45-4d45-9350-28ca7d92f8de
+    async def fetch_stale_entries(self) -> list[dict[str, Any]]:
+        """
+        Return blackboard entries whose age exceeds their constitutional SLA tier.
+
+        Stale detection is for non-terminal stuck entries only. Every declared
+        terminal status is excluded because terminal entries cannot be acted
+        on further and must not trigger stale alerts. Per the canonical
+        ``blackboard_entry_status`` enum (.intent/META/enums.json), the
+        terminal set is:
+
+          * resolved
+          * abandoned
+          * suppressed             (#263)
+          * dry_run_complete       (#265 — historical; no new writers)
+          * deferred_to_proposal
+          * indeterminate
+
+        Excludes self-referential stale-finding and silent-worker subjects.
+
+        Covers:
+          - BlackboardShopManager._fetch_stale_entries
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            result = await session.execute(
+                text(
+                    """
+                    SELECT
+                        id,
+                        entry_type,
+                        subject,
+                        worker_uuid,
+                        status,
+                        EXTRACT(EPOCH FROM (now() - created_at))::int AS age_seconds,
+                        CASE entry_type
+                            WHEN 'heartbeat' THEN CAST(:sla_heartbeat AS INT)
+                            WHEN 'finding'   THEN CAST(:sla_finding AS INT)
+                            WHEN 'report'    THEN CAST(:sla_report AS INT)
+                            WHEN 'proposal'  THEN CAST(:sla_proposal AS INT)
+                            ELSE CAST(:sla_default AS INT)
+                        END AS sla_seconds
+                    FROM core.blackboard_entries
+                    WHERE status NOT IN (
+                            'resolved',
+                            'abandoned',
+                            'suppressed',
+                            'dry_run_complete',
+                            'deferred_to_proposal',
+                            'indeterminate'
+                          )
+                      AND entry_type IN ('finding', 'proposal')
+                      AND subject NOT LIKE 'blackboard.entry_stale::%'
+                      AND subject NOT LIKE 'worker.silent::%'
+                      AND EXTRACT(EPOCH FROM (now() - created_at)) >
+                        CASE entry_type
+                            WHEN 'heartbeat' THEN CAST(:sla_heartbeat AS INT)
+                            WHEN 'finding'   THEN CAST(:sla_finding AS INT)
+                            WHEN 'report'    THEN CAST(:sla_report AS INT)
+                            WHEN 'proposal'  THEN CAST(:sla_proposal AS INT)
+                            ELSE CAST(:sla_default AS INT)
+                        END
+                    ORDER BY age_seconds DESC
+                    """
+                ),
+                {
+                    "sla_heartbeat": _SLA["heartbeat"],
+                    "sla_finding": _SLA["finding"],
+                    "sla_report": _SLA["report"],
+                    "sla_proposal": _SLA["proposal"],
+                    "sla_default": _CFG.sla_default_seconds,
+                },
+            )
+            return [
+                {
+                    "id": row[0],
+                    "entry_type": row[1],
+                    "subject": row[2],
+                    "worker_uuid": row[3],
+                    "status": row[4],
+                    "age_seconds": row[5] or 0,
+                    "sla_seconds": row[6],
+                }
+                for row in result.fetchall()
+            ]
+
+    # ID: cdfba0a0-a746-4e3c-97a8-cc0a0eff2c59
+    async def count_active_entries(self) -> int:
+        """
+        Count total non-terminal blackboard entries.
+
+        Covers:
+          - BlackboardShopManager._count_active_entries
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            result = await session.execute(
+                text(
+                    """
+                    SELECT COUNT(*) FROM core.blackboard_entries
+                    WHERE status NOT IN (
+                        'resolved',
+                        'abandoned',
+                        'suppressed',
+                        'dry_run_complete',
+                        'deferred_to_proposal',
+                        'indeterminate'
+                    )
+                    """
+                )
+            )
+            return result.scalar() or 0
+
+    # ID: 7e4f9a1b-2c3d-4e5f-8a6b-7c8d9e0f1a2b
+    async def fetch_open_findings(
+        self, prefix: str, limit: int
+    ) -> list[dict[str, Any]]:
+        """
+        Return up to *limit* open finding entries whose subject matches *prefix*,
+        ordered oldest-first.  Payload is always returned as a dict.
+
+        Covers:
+          - ViolationRemediatorWorker._load_open_findings
+        """
+        from body.services.service_registry import ServiceRegistry
+
+        async with ServiceRegistry.session() as session:
+            result = await session.execute(
+                text(
+                    """
+                    SELECT id, subject, payload
+                    FROM core.blackboard_entries
+                    WHERE entry_type = 'finding'
+                      AND subject LIKE :prefix
+                      AND status = 'open'
+                    ORDER BY created_at ASC
+                    LIMIT :limit
+                    """
+                ),
+                {"prefix": prefix, "limit": limit},
+            )
+            rows = result.fetchall()
+
+        findings = []
+        for row in rows:
+            raw_payload = row[2]
+            payload = (
+                raw_payload
+                if isinstance(raw_payload, dict)
+                else json.loads(raw_payload)
+            )
+            findings.append(
+                {
+                    "id": str(row[0]),
+                    "subject": row[1],
+                    "payload": payload or {},
+                }
+            )
+        return findings