multi-agent-platform 0.1.0__py3-none-any.whl

server/services/inbound_event_service.py

@@ -0,0 +1,111 @@
+"""Service layer for the runtime-waker inbound-event access log.
+
+This module backs the D6 server-side record endpoint
+(``POST /agents/me/inbound-events``), which is the primary dedup gate for the
+runtime-waker: every waker must call this endpoint *before* resuming a session
+so the server's ``UNIQUE(fingerprint)`` constraint enforces A1 (replay rejection)
+and A2 (concurrent dedup) across processes and restarts.
+
+v0.9 (M30A/M31 I2): legacy v1 fingerprints (``inbound:<event_id>``) are
+detected via :func:`notification_service.is_legacy_v1_fingerprint` and routed
+to a separate code path that bumps ``InboundEvent.rejection_count`` instead of
+returning the normal ``UNIQUE(fingerprint)`` 409 — the audit row is preserved
+(matching plan D6 three-layer join) but the waker is told to skip resume.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from server.domain.models import Agent, InboundEvent
+from server.domain.schemas import InboundEventCreate
+from server.services.notification_service import is_legacy_v1_fingerprint
+
+
+def record_inbound_event(
+    db: Session, agent: Agent, payload: InboundEventCreate
+) -> tuple[InboundEvent, str]:
+    """Persist a waker's record of an inbound notification.
+
+    Returns one of:
+
+    - ``(event, "recorded")`` on first time (status code 201 at the API layer).
+    - ``(existing, "duplicate")`` when the ``UNIQUE(fingerprint)`` constraint
+      rejects the insert (replay / concurrent claim); API maps to 409 Conflict
+      (D6 / A1 gate).
+    - ``(event, "rejected_v1")`` when the fingerprint uses the legacy
+      ``inbound:<event_id>`` shape. The row is upserted with
+      ``rejection_count`` bumped, so the audit table still records the
+      sighting; the waker is told to skip resume (API returns 200 OK with the
+      current ``rejection_count`` so the caller can observe it).
+
+    The fetch-after-rollback is a best-effort lookup: in the rare race where
+    the conflicting row is deleted before we look it up we re-raise the
+    original IntegrityError so the caller still sees a 5xx rather than silently
+    lying.
+    """
+    if is_legacy_v1_fingerprint(payload.fingerprint):
+        return _record_or_reject_v1(db, agent, payload)
+
+    event = InboundEvent(
+        agent_id=agent.id,
+        event_id=payload.event_id,
+        event_type=payload.event_type,
+        source=payload.source,
+        fingerprint=payload.fingerprint,
+        payload=payload.payload,
+    )
+    db.add(event)
+    try:
+        db.commit()
+    except IntegrityError:
+        db.rollback()
+        existing = (
+            db.query(InboundEvent)
+            .filter(InboundEvent.fingerprint == payload.fingerprint)
+            .one_or_none()
+        )
+        if existing is None:
+            raise
+        return existing, "duplicate"
+    db.refresh(event)
+    return event, "recorded"
+
+
+def _record_or_reject_v1(
+    db: Session, agent: Agent, payload: InboundEventCreate
+) -> tuple[InboundEvent, str]:
+    """Insert or upsert a legacy v1 fingerprint with ``rejection_count`` bumped.
+
+    v1 fingerprints are pre-v0.9 namespaced (``inbound:<event_id>``) and MUST
+    NOT trigger a session resume. We still persist an ``InboundEvent`` row so
+    the audit table records the sighting — every repeat of the same fingerprint
+    increments ``rejection_count`` so an operator can observe how often the
+    legacy path fires. The waker distinguishes ``"rejected_v1"`` from
+    ``"duplicate"`` and uses it to log a ``[wake:skip] v1 fingerprint rejected``
+    line rather than treating it as a cross-process race.
+    """
+    existing = db.scalar(
+        select(InboundEvent).where(InboundEvent.fingerprint == payload.fingerprint)
+    )
+    if existing is not None:
+        existing.rejection_count = (existing.rejection_count or 0) + 1
+        db.commit()
+        db.refresh(existing)
+        return existing, "rejected_v1"
+
+    event = InboundEvent(
+        agent_id=agent.id,
+        event_id=payload.event_id,
+        event_type=payload.event_type,
+        source=payload.source,
+        fingerprint=payload.fingerprint,
+        payload=payload.payload,
+        rejection_count=1,
+    )
+    db.add(event)
+    db.commit()
+    db.refresh(event)
+    return event, "rejected_v1"

server/services/lock_service.py

@@ -0,0 +1,273 @@
+"""Per-project experiment execution lock service (CP-3 server side).
+
+The lock is **soft**: a row-level lock stored on the ``experiments`` table
+itself (``lock_holder_experiment_id`` + ``lock_acquired_at`` + ``lock_ttl_seconds``)
+is the source of truth. Stale locks self-heal via ``lock_ttl_seconds``. The
+CLI side (``cli/runtime/run_lock.py``) adds a best-effort ``fcntl.flock`` for
+intra-host safety; the server side is authoritative.
+
+Endpoints wired in :mod:`server.api.experiments`:
+
+* ``POST /experiments/{id}/lock/acquire``  → :func:`acquire_experiment_lock`
+* ``POST /experiments/{id}/lock/release``  → :func:`release_experiment_lock`
+* ``POST /experiments/{id}/lock/force-release`` → :func:`force_release_experiment_lock`
+* ``POST /experiments/{id}/lock/skip``     → :func:`record_experiment_lock_skip`
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from server.db.deadlock_retry import commit_with_retry
+from server.domain.models import Agent, Experiment
+from server.services.errors import ConflictError, ForbiddenError, NotFoundError
+
+logger = logging.getLogger("map.experiment_lock")
+
+DEFAULT_LOCK_TTL_SECONDS = 1800
+
+
+@dataclass(frozen=True)
+class LockResult:
+    """Compact representation of a successful lock operation.
+
+    Returned to the API caller and also persisted on the experiment row.
+    """
+
+    experiment_id: uuid.UUID
+    project_id: uuid.UUID
+    holder: uuid.UUID | None
+    acquired_at: datetime | None
+    ttl_seconds: int | None
+    next_attempt_at: datetime | None
+    skip_count: int
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _is_expired(experiment: Experiment, *, now: datetime | None = None) -> bool:
+    if not experiment.lock_holder_experiment_id or not experiment.lock_acquired_at:
+        return True
+    reference = now or _now()
+    acquired = experiment.lock_acquired_at
+    if acquired.tzinfo is None:
+        acquired = acquired.replace(tzinfo=UTC)
+    ttl = experiment.lock_ttl_seconds or DEFAULT_LOCK_TTL_SECONDS
+    return reference >= acquired + __import__("datetime").timedelta(seconds=ttl)
+
+
+def _to_result(experiment: Experiment) -> LockResult:
+    return LockResult(
+        experiment_id=experiment.id,
+        project_id=experiment.project_id,
+        holder=experiment.lock_holder_experiment_id,
+        acquired_at=experiment.lock_acquired_at,
+        ttl_seconds=experiment.lock_ttl_seconds,
+        next_attempt_at=experiment.next_attempt_at,
+        skip_count=int(experiment.lock_skip_count or 0),
+    )
+
+
+def _get(db: Session, experiment_id: uuid.UUID) -> Experiment:
+    stmt = select(Experiment).where(Experiment.id == experiment_id)
+    experiment = db.scalar(stmt)
+    if experiment is None or experiment.deleted_at is not None:
+        raise NotFoundError(f"experiment {experiment_id} not found")
+    return experiment
+
+
+def _ensure_can_modify_lock(actor: Agent, experiment: Experiment) -> None:
+    if experiment.creator_agent_id != actor.id and actor.role.value != "admin":
+        raise ForbiddenError("Only the creator or admin can manage the experiment lock")
+
+
+def _find_project_holder(db: Session, project_id: uuid.UUID, *, exclude_id: uuid.UUID | None = None) -> Experiment | None:
+    """Find an experiment in ``project_id`` that currently holds the lock."""
+
+    stmt = (
+        select(Experiment)
+        .where(
+            Experiment.project_id == project_id,
+            Experiment.lock_holder_experiment_id.is_not(None),
+            Experiment.lock_acquired_at.is_not(None),
+        )
+    )
+    if exclude_id is not None:
+        stmt = stmt.where(Experiment.id != exclude_id)
+    return db.scalar(stmt)
+
+
+def acquire_experiment_lock(
+    db: Session,
+    experiment_id: uuid.UUID,
+    actor: Agent,
+    *,
+    ttl_seconds: int = DEFAULT_LOCK_TTL_SECONDS,
+) -> LockResult:
+    """Acquire the per-project execution lock for ``experiment_id``.
+
+    Raises :class:`ConflictError` when another live experiment in the same
+    project holds the lock. A stale lock (TTL expired) is transparently
+    reclaimed.
+    """
+
+    experiment = _get(db, experiment_id)
+    _ensure_can_modify_lock(actor, experiment)
+
+    other = _find_project_holder(db, experiment.project_id, exclude_id=experiment_id)
+    if other is not None and other.lock_holder_experiment_id != experiment.id and not _is_expired(other):
+        raise ConflictError(
+            f"experiment {other.id} already holds the execution lock for project {experiment.project_id}"
+        )
+
+    experiment.lock_holder_experiment_id = experiment.id
+    experiment.lock_acquired_at = _now()
+    experiment.lock_ttl_seconds = int(ttl_seconds)
+    try:
+        commit_with_retry(db, op_label="acquire_experiment_lock")
+    except IntegrityError:
+        # Lost the race against another acquire that committed first; the
+        # ``uq_experiment_lock_holder_active`` partial unique index
+        # (PG-only; race experiment eca0f522 PR1) caught the conflict at
+        # commit time. Surface as ConflictError so callers see the same
+        # semantics as the in-process ``_find_project_holder`` guard.
+        db.rollback()
+        holder = _find_project_holder(db, experiment.project_id, exclude_id=experiment_id)
+        holder_id = holder.id if holder is not None else None
+        raise ConflictError(
+            f"experiment {holder_id} already holds the execution lock for project {experiment.project_id}"
+        ) from None
+    db.refresh(experiment)
+    logger.info(
+        "acquire_lock experiment=%s project=%s ttl=%s",
+        experiment.id,
+        experiment.project_id,
+        ttl_seconds,
+    )
+    return _to_result(experiment)
+
+
+def release_experiment_lock(
+    db: Session,
+    experiment_id: uuid.UUID,
+    actor: Agent,
+) -> LockResult:
+    """Release the lock if ``experiment_id`` is the current holder."""
+
+    experiment = _get(db, experiment_id)
+    _ensure_can_modify_lock(actor, experiment)
+
+    if experiment.lock_holder_experiment_id == experiment.id:
+        experiment.lock_holder_experiment_id = None
+        experiment.lock_acquired_at = None
+        experiment.lock_ttl_seconds = None
+        commit_with_retry(db, op_label="release_experiment_lock")
+        db.refresh(experiment)
+        logger.info("release_lock experiment=%s", experiment.id)
+    else:
+        logger.info(
+            "release_lock noop experiment=%s current_holder=%s",
+            experiment.id,
+            experiment.lock_holder_experiment_id,
+        )
+    return _to_result(experiment)
+
+
+def force_release_experiment_lock(
+    db: Session,
+    experiment_id: uuid.UUID,
+    actor: Agent,
+    *,
+    reason: str,
+) -> LockResult:
+    """Operator override: clear the lock regardless of holder.
+
+    Clears **all** lock holders on the project (only one should exist, but
+    defensive).
+    """
+
+    experiment = _get(db, experiment_id)
+    if actor.role.value != "admin" and experiment.creator_agent_id != actor.id:
+        raise ForbiddenError("Only the creator or admin can force-release a lock")
+
+    # Clear every holder on the project.
+    holders = (
+        db.scalars(
+            select(Experiment).where(
+                Experiment.project_id == experiment.project_id,
+                Experiment.lock_holder_experiment_id.is_not(None),
+            )
+        ).all()
+    )
+    previous_holders = [str(e.id) for e in holders if e.lock_holder_experiment_id is not None]
+    for holder in holders:
+        holder.lock_holder_experiment_id = None
+        holder.lock_acquired_at = None
+        holder.lock_ttl_seconds = None
+    commit_with_retry(db, op_label="force_release_experiment_lock")
+    logger.warning(
+        "force_release_lock actor=%s reason=%s project=%s previous_holders=%s",
+        actor.id,
+        reason,
+        experiment.project_id,
+        previous_holders,
+    )
+    db.refresh(experiment)
+    return _to_result(experiment)
+
+
+def record_experiment_lock_skip(
+    db: Session,
+    experiment_id: uuid.UUID,
+    actor: Agent,
+    *,
+    next_attempt_at: datetime,
+) -> LockResult:
+    """Bump ``lock_skip_count`` and record ``next_attempt_at`` for closed-loop backoff."""
+
+    experiment = _get(db, experiment_id)
+    _ensure_can_modify_lock(actor, experiment)
+    experiment.lock_skip_count = int(experiment.lock_skip_count or 0) + 1
+    experiment.next_attempt_at = next_attempt_at
+    commit_with_retry(db, op_label="record_experiment_lock_skip")
+    db.refresh(experiment)
+    logger.info(
+        "lock_skip experiment=%s skip_count=%s next_attempt_at=%s",
+        experiment.id,
+        experiment.lock_skip_count,
+        next_attempt_at.isoformat(),
+    )
+    return _to_result(experiment)
+
+
+def serialize_lock_state(experiment: Experiment) -> dict[str, Any]:
+    """Return a JSON-safe snapshot for inclusion in API responses / logs."""
+
+    return {
+        "lock_holder_experiment_id": str(experiment.lock_holder_experiment_id) if experiment.lock_holder_experiment_id else None,
+        "lock_acquired_at": experiment.lock_acquired_at.isoformat() if experiment.lock_acquired_at else None,
+        "lock_ttl_seconds": experiment.lock_ttl_seconds,
+        "next_attempt_at": experiment.next_attempt_at.isoformat() if experiment.next_attempt_at else None,
+        "lock_skip_count": int(experiment.lock_skip_count or 0),
+    }
+
+
+__all__ = [
+    "DEFAULT_LOCK_TTL_SECONDS",
+    "LockResult",
+    "acquire_experiment_lock",
+    "force_release_experiment_lock",
+    "record_experiment_lock_skip",
+    "release_experiment_lock",
+    "serialize_lock_state",
+]

server/services/log_service.py

@@ -0,0 +1,202 @@
+import uuid
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from server.domain.models import (
+    Agent,
+    ExperimentLog,
+    ExperimentPhase,
+    PlanVersion,
+)
+from server.domain.schemas import ExperimentLogCreate
+from server.services import audit_service
+from server.services.errors import StateTransitionError
+from server.services.evidence_service import (
+    EvidenceValidationResult,
+    validate_log_evidence,
+)
+from server.services.project_service import get_experiment
+from server.services.similarity_service import (
+    SimilarityValidationResult,
+    validate_log_similarity,
+)
+
+
+def _validate_log_phase(phase: ExperimentPhase) -> None:
+    if phase not in (
+        ExperimentPhase.running,
+        ExperimentPhase.result_review,
+        ExperimentPhase.done,
+    ):
+        raise StateTransitionError(
+            "Logs can only be added when experiment is running, pending result review, or done"
+        )
+
+
+def _load_current_plan_md(db: Session, experiment_id: uuid.UUID) -> str | None:
+    """Return ``current_plan.content_md`` for the experiment, or None when
+    the experiment has no committed plan version (current_plan_version == 0
+    or the row is missing).
+    """
+    experiment = get_experiment(db, experiment_id)
+    if experiment.current_plan_version <= 0:
+        return None
+    plan = db.scalar(
+        select(PlanVersion).where(
+            PlanVersion.experiment_id == experiment_id,
+            PlanVersion.version == experiment.current_plan_version,
+        )
+    )
+    return plan.content_md if plan is not None else None
+
+
+def append_log(
+    db: Session,
+    experiment_id: uuid.UUID,
+    author: Agent,
+    payload: ExperimentLogCreate,
+) -> tuple[ExperimentLog, EvidenceValidationResult, SimilarityValidationResult, bool]:
+    experiment = get_experiment(db, experiment_id)
+    _validate_log_phase(experiment.phase)
+    next_index = db.scalar(
+        select(func.coalesce(func.max(ExperimentLog.log_index), 0) + 1).where(
+            ExperimentLog.experiment_id == experiment_id
+        )
+    )
+    log = ExperimentLog(
+        experiment_id=experiment_id,
+        author_agent_id=author.id,
+        summary=payload.summary,
+        content_md=payload.content_md,
+        metadata_json=payload.metadata,
+        log_index=next_index or 1,
+    )
+    plan_md = _load_current_plan_md(db, experiment_id)
+    validation = validate_log_evidence(plan_md=plan_md, metadata=payload.metadata)
+    # Compute similarity BEFORE flushing the new log so the comparison
+    # sees the prior log, not the log we're about to save (which would
+    # trivially score 1.0 against itself).
+    similarity = validate_log_similarity(
+        db,
+        experiment_id=experiment_id,
+        content_md=payload.content_md,
+    )
+    db.add(log)
+    db.flush()
+    force_skip_applied = False
+    if similarity.warnings and payload.force_skip_similarity:
+        warning = similarity.warnings[0]
+        audit_service.log_force_skip_no_commit(
+            db,
+            log_id=log.id,
+            ref_log_id=warning.ref_log_id,
+            experiment_id=experiment_id,
+            project_id=experiment.project_id,
+            actor_id=author.id,
+            similarity_score=warning.score,
+            threshold=warning.threshold,
+            embedding_model=warning.model,
+        )
+        force_skip_applied = True
+    return log, validation, similarity, force_skip_applied
+
+
+def create_log(
+    db: Session,
+    experiment_id: uuid.UUID,
+    author: Agent,
+    payload: ExperimentLogCreate,
+) -> tuple[
+    ExperimentLog,
+    EvidenceValidationResult,
+    SimilarityValidationResult,
+    bool,
+]:
+    log, validation, similarity, force_skip_applied = append_log(
+        db, experiment_id, author, payload
+    )
+    db.commit()
+    db.refresh(log)
+    return log, validation, similarity, force_skip_applied
+
+
+def list_logs(
+    db: Session,
+    experiment_id: uuid.UUID,
+    *,
+    limit: int = 50,
+) -> list[ExperimentLog]:
+    get_experiment(db, experiment_id)
+    stmt = (
+        select(ExperimentLog)
+        .where(ExperimentLog.experiment_id == experiment_id)
+        .order_by(ExperimentLog.log_index.asc())
+        .limit(max(1, min(limit, 200)))
+    )
+    return list(db.scalars(stmt))
+
+
+def get_latest_log(db: Session, experiment_id: uuid.UUID) -> ExperimentLog | None:
+    stmt = (
+        select(ExperimentLog)
+        .where(ExperimentLog.experiment_id == experiment_id)
+        .order_by(ExperimentLog.log_index.desc())
+        .limit(1)
+    )
+    return db.scalar(stmt)
+
+
+def log_counts_by_experiment(
+    db: Session, experiment_ids: list[uuid.UUID]
+) -> dict[uuid.UUID, int]:
+    """Per-experiment ExperimentLog row counts in a single GROUP BY query.
+
+    Returns a dict keyed by experiment_id. Experiments with no logs map
+    to 0 (caller can safely ``counts[eid]`` without ``.get``). Empty
+    input → empty dict without hitting the database.
+    """
+    if not experiment_ids:
+        return {}
+    stmt = (
+        select(ExperimentLog.experiment_id, func.count())
+        .where(ExperimentLog.experiment_id.in_(experiment_ids))
+        .group_by(ExperimentLog.experiment_id)
+    )
+    found = {eid: int(count) for eid, count in db.execute(stmt).all()}
+    # Fill in zeros for experiments that have no logs so the caller can
+    # index by experiment_id without a defensive ``.get``/``default``.
+    return {eid: found.get(eid, 0) for eid in experiment_ids}
+
+
+def latest_log_by_experiment(
+    db: Session, experiment_ids: list[uuid.UUID]
+) -> dict[uuid.UUID, ExperimentLog]:
+    """Latest ExperimentLog per experiment in a single window/join query.
+
+    Returns a dict keyed by experiment_id. Experiments with no logs are
+    absent from the dict (``latest.get(eid) is None``). Empty input →
+    empty dict without hitting the database.
+    """
+    if not experiment_ids:
+        return {}
+    # Max + self-join pattern. (experiment_id, log_index) is not UNIQUE
+    # in the schema, but ``append_log`` always allocates via max+1, so
+    # in practice the max row is unique. GROUP BY gives one row per
+    # experiment with the top log_index; the join back returns the
+    # full ExperimentLog rows.
+    max_idx_subq = (
+        select(
+            ExperimentLog.experiment_id.label("eid"),
+            func.max(ExperimentLog.log_index).label("max_idx"),
+        )
+        .where(ExperimentLog.experiment_id.in_(experiment_ids))
+        .group_by(ExperimentLog.experiment_id)
+        .subquery()
+    )
+    stmt = select(ExperimentLog).join(
+        max_idx_subq,
+        (ExperimentLog.experiment_id == max_idx_subq.c.eid)
+        & (ExperimentLog.log_index == max_idx_subq.c.max_idx),
+    )
+    return {log.experiment_id: log for log in db.scalars(stmt)}