fix(maf): harden stage-4 quality gate (P0/P1)

P0-1 migration: detect the same-named stage-3 execution_stage CHECK by sqltext (must contain rework + manager_review), SQLite rebuild / PG-MySQL drop+add, PG boolean default TRUE, validate_schema checks constraint content + seat_tasks status CHECK/unique/FKs; tests start from a real stage-3 schema.

P0-2: a missing/invalid manager review (timeout/exception/empty/invalid JSON/missing per-seat decision) is never an acceptance - system rework under the cap, contract fallback (reassign/controlled_gap/ask_user) afterwards, source=system events.

P0-3: unaccepted deliveries are isolated from the fact ledger, cross-review and final report (deferred merge, delivery_json envelope, accepted_task_results in checkpoint, accepted-only synthesis, no turn_results fallback).

P0-4: seat-task init is atomic get-or-create over the full expected set; recovery fills missing tasks without overwriting frozen contracts; quality gate blocks missing required tasks.

P1: zero config values honoured; duplicate detection persists SHA-256 conclusion digests in history (survives restarts); findings never satisfy evidence, evidence_refs must resolve to trusted ledger refs (unverified_evidence_ref); conversation SSE projection tests added and manager/finalizer messages are no longer mislabelled as seat.delivery.submitted.
This commit is contained in:
董宏凯 committed 2026-08-07 00:04:55 +08:00
1 parent a786cdcad0
commit 1aeee86984
24 files changed
+4706 -47

No files matched your search

@@ -220,6 +220,39 @@ class MafRoundtableConfig(BaseModel):
le=60,
description="后台自动 reconcile 扫描间隔(秒);补偿投影失败的审计事件。",
)
# Stage 4 (R3-Q): seat task quality contracts + manager acceptance gate.
quality_gate_enabled: bool = Field(
default=True,
description="V2 结构化派活是否启用席位任务合同与总控验收闸门;关闭时退化为 Stage 3 行为。",
)
max_rework_attempts: int = Field(
default=2,
ge=0,
le=8,
description="同一席位任务最多返工次数(初稿之外);到达上限后按 fallback_policy 升级。",
)
max_reassignments: int = Field(
default=1,
ge=0,
le=4,
description="同一席位任务最多改派次数(备用席位接管);到达上限后受控降级为 controlled_gap。",
)
min_delivery_chars: int = Field(
default=40,
ge=0,
le=10000,
description="席位交付结论(summary)的最小有效长度;低于此值触发 below_min_length 确定性失败。",
)
min_delivery_evidence: int = Field(
default=1,
ge=0,
le=16,
description="席位交付必须提供的最少证据/依据条目;低于此值触发 missing_evidence 确定性失败。",
)
default_fallback_policy: Literal["reassign_then_gap", "controlled_gap", "ask_user"] = Field(
default="reassign_then_gap",
description="到达返工/改派上限后的默认降级策略:改派后受控缺口 / 直接受控缺口 / 请求用户澄清。",
)
@field_validator("default_manager_agent_id", mode="before")
@@ -31,6 +31,7 @@ from __future__ import annotations
from datetime import UTC, datetime
from sqlalchemy import (
Boolean,
CheckConstraint,
ForeignKey,
Integer,
@@ -368,7 +369,8 @@ class MafRoundtableSeatRunRow(Base):
# migration / manual SQL honest. Keep in sync with VALID_EXECUTION_STAGES.
CheckConstraint(
"execution_stage IN ('legacy','planner','expert','format_repair',"
"'cross_review','cross_review_repair','finalizer','group_chat')",
"'cross_review','cross_review_repair','finalizer','group_chat',"
"'rework','manager_review')",
name="ck_maf_seat_runs_execution_stage",
),
)
@@ -406,6 +408,64 @@ class MafRoundtableSeatRunRow(Base):
)
# ── 8b. seat tasks (Stage 4 / R3-Q quality state machine) ─────────────────
class MafRoundtableSeatTaskRow(Base):
"""One seat task with its frozen contract and quality lifecycle.
Stage 4 (R3-Q): each manager dispatch assignment becomes one seat task.
The row persists the whole acceptance state machine
(``assigned → delivering → submitted → manager_review →
accepted / rework / reassigned / exhausted / controlled_gap``) together
with the frozen ``contract_json``, the latest ``delivery_json``,
``deterministic_check_json``, ``review_decision_json`` and a per-attempt
``history_json``. When every rework/reassign cap is exhausted the task
ends as ``controlled_gap`` with a ``gap_json`` risk record that the final
report must carry — it is never disguised as an accepted delivery.
``task_key`` is stable per (run, original assignment); reassignment only
changes ``agent_id`` and never creates a new task.
"""
__tablename__ = "maf_roundtable_seat_tasks"
__table_args__ = (
UniqueConstraint("run_id", "task_key", name="uq_maf_seat_tasks_run_task"),
CheckConstraint(
"status IN ('assigned','delivering','submitted','manager_review',"
"'accepted','rework','reassigned','exhausted','controlled_gap')",
name="ck_maf_seat_tasks_status",
),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
session_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_sessions.id", ondelete="CASCADE"), nullable=False, index=True
)
run_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_runs.id", ondelete="CASCADE"), nullable=False, index=True
)
task_key: Mapped[str] = mapped_column(String(128), nullable=False)
# Current owning seat (changes on reassignment).
agent_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
original_agent_id: Mapped[str] = mapped_column(String(64), nullable=False)
status: Mapped[str] = mapped_column(String(32), default="assigned", index=True)
required: Mapped[bool] = mapped_column(Boolean, default=True)
attempt_count: Mapped[int] = mapped_column(Integer, default=0)
rework_count: Mapped[int] = mapped_column(Integer, default=0)
reassign_count: Mapped[int] = mapped_column(Integer, default=0)
contract_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
delivery_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
deterministic_check_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
review_decision_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
history_json: Mapped[list | None] = mapped_column(PortableJSON(), nullable=True)
gap_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
)
# ── 9. action secrets (encrypted actual execution params, server-only) ────
@@ -576,5 +636,6 @@ __all__ = [
"MafRoundtableParticipantRow",
"MafRoundtableRunRow",
"MafRoundtableSeatRunRow",
"MafRoundtableSeatTaskRow",
"MafRoundtableSessionRow",
]
@@ -36,6 +36,11 @@ CROSS_REVIEW = "cross_review"
CROSS_REVIEW_REPAIR = "cross_review_repair"
FINALIZER = "finalizer"
GROUP_CHAT = "group_chat"
# Stage 4 (R3-Q) quality-loop stages. Rework deliveries run at an advanced
# business round (one round per quality iteration), so the four-tuple
# (run, agent, turn, stage) stays unique across attempts.
REWORK = "rework"
MANAGER_REVIEW = "manager_review"
VALID_EXECUTION_STAGES: frozenset[str] = frozenset({
LEGACY,
@@ -46,6 +51,8 @@ VALID_EXECUTION_STAGES: frozenset[str] = frozenset({
CROSS_REVIEW_REPAIR,
FINALIZER,
GROUP_CHAT,
REWORK,
MANAGER_REVIEW,
})
@@ -0,0 +1,232 @@
"""Seat task repository — Stage 4 (R3-Q) quality state machine persistence.
Each manager dispatch assignment becomes one seat task row. The row carries the
frozen ``contract_json`` and the full acceptance lifecycle (delivery, deterministic
check, manager review decision, rework / reassign counts, controlled-gap record).
``task_key`` is stable per (run, original assignment); reassignment only mutates
``agent_id`` and never creates a new row, so the (run_id, task_key) unique
constraint keeps a task single even across backup-seat handovers.
"""
from __future__ import annotations
import logging
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableSeatTaskRow
logger = logging.getLogger(__name__)
def _now() -> datetime:
return datetime.now(UTC)
def _to_dict(row: MafRoundtableSeatTaskRow) -> dict[str, Any]:
return {
"id": row.id,
"session_id": row.session_id,
"run_id": row.run_id,
"task_key": row.task_key,
"agent_id": row.agent_id,
"original_agent_id": row.original_agent_id,
"status": row.status,
"required": bool(row.required),
"attempt_count": row.attempt_count,
"rework_count": row.rework_count,
"reassign_count": row.reassign_count,
"contract": row.contract_json,
"delivery": row.delivery_json,
"deterministic_check": row.deterministic_check_json,
"review_decision": row.review_decision_json,
"history": row.history_json or [],
"gap": row.gap_json,
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
"updated_at": row.updated_at.isoformat() if isinstance(row.updated_at, datetime) else row.updated_at,
}
# Column map for partial updates (public field name → ORM column).
_FIELD_MAP = {
"agent_id": "agent_id",
"status": "status",
"required": "required",
"attempt_count": "attempt_count",
"rework_count": "rework_count",
"reassign_count": "reassign_count",
"contract": "contract_json",
"delivery": "delivery_json",
"deterministic_check": "deterministic_check_json",
"review_decision": "review_decision_json",
"history": "history_json",
"gap": "gap_json",
}
class MafSeatTaskRepository:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def create_task(
self,
*,
session_id: str,
run_id: str,
task_key: str,
agent_id: str,
contract: dict[str, Any],
required: bool = True,
) -> dict[str, Any]:
"""Create a single seat task in ``assigned`` status with its frozen
contract. Prefer :meth:`get_or_create_tasks` for run initialization —
it is atomic across the whole dispatch assignment set."""
row = self._new_row(
session_id=session_id,
run_id=run_id,
task_key=task_key,
agent_id=agent_id,
contract=contract,
required=required,
)
async with self._sf() as session:
session.add(row)
await session.commit()
return _to_dict(row)
def _new_row(
self,
*,
session_id: str,
run_id: str,
task_key: str,
agent_id: str,
contract: dict[str, Any],
required: bool,
) -> MafRoundtableSeatTaskRow:
now = _now()
return MafRoundtableSeatTaskRow(
id=uuid4().hex,
session_id=session_id,
run_id=run_id,
task_key=task_key,
agent_id=agent_id,
original_agent_id=agent_id,
status="assigned",
required=required,
attempt_count=0,
rework_count=0,
reassign_count=0,
contract_json=contract,
history_json=[],
created_at=now,
updated_at=now,
)
async def get_or_create_tasks(
self,
*,
session_id: str,
run_id: str,
expected: list[dict[str, Any]],
) -> list[dict[str, Any]]:
"""Return the COMPLETE task set for a run (P0-4 atomic init/recovery).
``expected`` items: ``{task_key, agent_id, contract, required}`` — the
server-computed task set derived from the dispatch assignments.
Semantics:
- existing rows are preserved untouched (their frozen contract, counts
and status are NEVER overwritten);
- missing ``task_key`` rows are created;
- the full set is returned, ordered by ``task_key``;
- concurrent recovery calls never surface a unique-key violation: on a
(run_id, task_key) race the loser retries and reads the winner's rows.
"""
expected_items = [
item for item in (expected or [])
if str(item.get("task_key") or "") and str(item.get("agent_id") or "")
]
for _attempt in range(3):
try:
async with self._sf() as session:
async with session.begin():
rows = (
await session.execute(
select(MafRoundtableSeatTaskRow).where(
MafRoundtableSeatTaskRow.run_id == run_id
)
)
).scalars().all()
existing_keys = {r.task_key for r in rows}
for item in expected_items:
if item["task_key"] in existing_keys:
continue
session.add(self._new_row(
session_id=session_id,
run_id=run_id,
task_key=str(item["task_key"]),
agent_id=str(item["agent_id"]),
contract=dict(item.get("contract") or {}),
required=bool(item.get("required", True)),
))
break # commit succeeded
except IntegrityError:
# A concurrent recovery created the same task(s) first. Retry:
# the re-read finds them and skips creation.
logger.info(
"seat task init race for run %s — retrying (attempt %d)",
run_id, _attempt + 1,
)
continue
return await self.list_by_run(run_id)
async def get_task(self, task_id: str) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = select(MafRoundtableSeatTaskRow).where(
MafRoundtableSeatTaskRow.id == task_id
).limit(1)
row = (await session.execute(stmt)).scalars().first()
return _to_dict(row) if row is not None else None
async def get_by_run_task(self, run_id: str, task_key: str) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = select(MafRoundtableSeatTaskRow).where(
MafRoundtableSeatTaskRow.run_id == run_id,
MafRoundtableSeatTaskRow.task_key == task_key,
).limit(1)
row = (await session.execute(stmt)).scalars().first()
return _to_dict(row) if row is not None else None
async def list_by_run(self, run_id: str) -> list[dict[str, Any]]:
async with self._sf() as session:
stmt = (
select(MafRoundtableSeatTaskRow)
.where(MafRoundtableSeatTaskRow.run_id == run_id)
.order_by(MafRoundtableSeatTaskRow.task_key.asc())
)
rows = (await session.execute(stmt)).scalars().all()
return [_to_dict(r) for r in rows]
async def update_task(self, task_id: str, fields: dict[str, Any]) -> dict[str, Any] | None:
"""Partial update using the public field names (see ``_FIELD_MAP``)."""
async with self._sf() as session:
stmt = select(MafRoundtableSeatTaskRow).where(
MafRoundtableSeatTaskRow.id == task_id
).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
for key, value in fields.items():
col = _FIELD_MAP.get(key)
if col is not None:
setattr(row, col, value)
row.updated_at = _now()
await session.commit()
return _to_dict(row)
@@ -49,6 +49,7 @@ from deerflow.persistence.maf_roundtable.model import (
from deerflow.persistence.maf_roundtable.participants import MafParticipantRepository
from deerflow.persistence.maf_roundtable.runs import MafRunRepository, run_to_dict
from deerflow.persistence.maf_roundtable.seat_runs import MafSeatRunRepository
from deerflow.persistence.maf_roundtable.seat_tasks import MafSeatTaskRepository
from deerflow.persistence.maf_roundtable.sessions import MafSessionRepository
# Session statuses that mean a run is in flight — the CAS claim refuses these.
@@ -80,6 +81,7 @@ class MafRoundtableStore:
self.actions = MafActionRepository(session_factory)
self.approvals = MafApprovalRepository(session_factory)
self.seat_runs = MafSeatRunRepository(session_factory)
self.seat_tasks = MafSeatTaskRepository(session_factory)
self.action_secrets = MafActionSecretRepository(session_factory)
# V2 conversation aggregation (user-visible layer).
self.conversations = MafConversationRepository(session_factory)