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

@@ -0,0 +1,460 @@
"""Stage 4 migration for the MAF roundtable experiment (R3-Q quality gate).
Idempotent migration that brings a Stage-3 deployment up to Stage-4 schema:
1. Create the ``maf_roundtable_seat_tasks`` table (seat task contracts +
quality state machine rows) with its unique (run_id, task_key) constraint
and closed status CHECK constraint.
2. Extend the ``maf_roundtable_seat_runs.execution_stage`` CHECK constraint to
allow the two new Stage-4 stages ``rework`` and ``manager_review``.
Dialect handling
----------------
- **PostgreSQL / MySQL**: ``CREATE TABLE IF NOT EXISTS`` + ``ALTER TABLE`` to
swap the execution_stage CHECK. Each step is guarded by introspection so
re-runs are no-ops.
- **SQLite**: a CHECK constraint cannot be dropped in place, so the seat_runs
table is rebuilt (same recipe as the Phase-3 migration): a temp table with
the widened CHECK is created, data is copied as-is, the old table is
dropped and the temp renamed. Fully idempotent — the rebuild only runs when
the widened CHECK is absent.
**Deployment order**: run AFTER the Phase-3 migration and BEFORE enabling the
Stage-4 code path.
Usage (from ``offline-backend-20260512/backend/``)::
# Preview (no writes)
PYTHONPATH=. uv run python scripts/migrate_maf_roundtable_stage4.py --dry-run
# Execute
PYTHONPATH=. uv run python scripts/migrate_maf_roundtable_stage4.py
"""
from __future__ import annotations
import argparse
import asyncio
import logging
import sys
from typing import Any
logging.basicConfig(level=logging.INFO, format="%(message)s")
logger = logging.getLogger("migrate_maf_roundtable_stage4")
SEAT_TASKS_TABLE = "maf_roundtable_seat_tasks"
SEAT_RUNS_TABLE = "maf_roundtable_seat_runs"
EXECUTION_STAGE_CHECK_NAME = "ck_maf_seat_runs_execution_stage"
SEAT_TASKS_STATUS_CHECK_NAME = "ck_maf_seat_tasks_status"
STAGE4_STAGES = "'legacy','planner','expert','format_repair'," \
"'cross_review','cross_review_repair','finalizer','group_chat'," \
"'rework','manager_review'"
# The two stages Stage 4 adds on top of the Stage-3 enum. A constraint that
# does not contain BOTH of them is still a Stage-3 constraint, even when it
# carries the same constraint name.
STAGE4_NEW_STAGES = ("rework", "manager_review")
SEAT_TASKS_STATUSES = (
"assigned", "delivering", "submitted", "manager_review",
"accepted", "rework", "reassigned", "exhausted", "controlled_gap",
)
def _dialect_name(conn_or_dialect: Any) -> str:
return str(getattr(getattr(conn_or_dialect, "dialect", conn_or_dialect), "name", "sqlite")).lower()
def _timestamp_sql(dialect: str) -> str:
if dialect == "postgresql":
return "TIMESTAMP WITH TIME ZONE"
if dialect in {"mysql", "mariadb"}:
return "DATETIME(6)"
return "DATETIME"
def _json_sql(dialect: str) -> str:
if dialect == "postgresql":
return "JSONB"
if dialect in {"mysql", "mariadb"}:
return "JSON"
return "TEXT"
def _boolean_default_sql(dialect: str) -> str:
"""Dialect-correct literal for a BOOLEAN column default.
PostgreSQL has a real BOOLEAN type whose literal is ``TRUE`` — ``DEFAULT 1``
is rejected there. SQLite/MySQL store booleans as integers.
"""
if dialect == "postgresql":
return "TRUE"
return "1"
def _seat_tasks_ddl(dialect: str) -> str:
ts = _timestamp_sql(dialect)
js = _json_sql(dialect)
bool_default = _boolean_default_sql(dialect)
return f"""
CREATE TABLE {SEAT_TASKS_TABLE} (
id VARCHAR(64) NOT NULL PRIMARY KEY,
session_id VARCHAR(64) NOT NULL,
run_id VARCHAR(64) NOT NULL,
task_key VARCHAR(128) NOT NULL,
agent_id VARCHAR(64) NOT NULL,
original_agent_id VARCHAR(64) NOT NULL,
status VARCHAR(32) NOT NULL DEFAULT 'assigned',
required BOOLEAN NOT NULL DEFAULT {bool_default},
attempt_count INTEGER NOT NULL DEFAULT 0,
rework_count INTEGER NOT NULL DEFAULT 0,
reassign_count INTEGER NOT NULL DEFAULT 0,
contract_json {js},
delivery_json {js},
deterministic_check_json {js},
review_decision_json {js},
history_json {js},
gap_json {js},
created_at {ts} NOT NULL,
updated_at {ts} NOT NULL,
CONSTRAINT uq_maf_seat_tasks_run_task UNIQUE (run_id, task_key),
CONSTRAINT ck_maf_seat_tasks_status CHECK (
status IN ('assigned','delivering','submitted','manager_review',
'accepted','rework','reassigned','exhausted','controlled_gap')
),
FOREIGN KEY (session_id) REFERENCES maf_roundtable_sessions (id) ON DELETE CASCADE,
FOREIGN KEY (run_id) REFERENCES maf_roundtable_runs (id) ON DELETE CASCADE
)
"""
def _seat_tasks_indexes_ddl(dialect: str) -> list[str]:
return [
f"CREATE INDEX ix_maf_seat_tasks_session ON {SEAT_TASKS_TABLE} (session_id)",
f"CREATE INDEX ix_maf_seat_tasks_run ON {SEAT_TASKS_TABLE} (run_id)",
f"CREATE INDEX ix_maf_seat_tasks_agent ON {SEAT_TASKS_TABLE} (agent_id)",
f"CREATE INDEX ix_maf_seat_tasks_status ON {SEAT_TASKS_TABLE} (status)",
]
def _ddl_add_execution_stage_check(dialect: str) -> str:
if dialect in {"mysql", "mariadb"}:
return (
f"ALTER TABLE {SEAT_RUNS_TABLE} "
f"ADD CONSTRAINT ck_maf_seat_runs_execution_stage "
f"CHECK (execution_stage IN ({STAGE4_STAGES}))"
)
return (
f"ALTER TABLE {SEAT_RUNS_TABLE} "
f"ADD CONSTRAINT ck_maf_seat_runs_execution_stage "
f"CHECK (execution_stage IN ({STAGE4_STAGES}))"
)
def _ddl_drop_execution_stage_check(dialect: str) -> str:
if dialect in {"mysql", "mariadb"}:
return f"ALTER TABLE {SEAT_RUNS_TABLE} DROP CHECK ck_maf_seat_runs_execution_stage"
return f"ALTER TABLE {SEAT_RUNS_TABLE} DROP CONSTRAINT ck_maf_seat_runs_execution_stage"
def _check_constraint_sql(insp: Any, table: str, name: str) -> str | None:
"""Return the SQL text of a CHECK constraint, or ``None`` when absent.
The Stage-3 migration created a constraint with the SAME name
(``ck_maf_seat_runs_execution_stage``) but the old stage list, so the name
alone can never prove a table is already on Stage 4 — only the SQL text can.
"""
getter = getattr(insp, "get_check_constraints", None)
if getter is None:
return None
try:
for ck in getter(table):
if ck.get("name") == name:
return str(ck.get("sqltext") or "")
except Exception: # noqa: BLE001
return None
return None
def _execution_stage_check_sql(insp: Any) -> str | None:
"""SQL text of the seat_runs ``execution_stage`` CHECK, or ``None``."""
return _check_constraint_sql(insp, SEAT_RUNS_TABLE, EXECUTION_STAGE_CHECK_NAME)
def _has_stage4_execution_stage_check(insp: Any) -> bool:
"""True only when the constraint exists AND already allows BOTH Stage-4 stages.
A same-named Stage-3 constraint (no ``rework`` / ``manager_review``) is
treated as the old constraint and must be widened — never reported as
"already widened".
"""
sql = _execution_stage_check_sql(insp)
if sql is None:
return False
return all(stage in sql for stage in STAGE4_NEW_STAGES)
def _widen_check_ddls(dialect: str, *, check_exists: bool, is_stage4: bool) -> list[str]:
"""Pure decision function: DDL needed to widen the execution_stage CHECK.
- already Stage 4 → no-op;
- SQLite → rebuild the table (a CHECK cannot be dropped in place), whether
the old constraint exists or not;
- PostgreSQL / MySQL → drop the old constraint first when it exists, then
add the Stage-4 constraint; when it does not exist, just add it.
Kept free of I/O so the PostgreSQL / MySQL branches are unit-testable
without a live database.
"""
if is_stage4:
return []
if dialect == "sqlite":
return _sqlite_rebuild_seat_runs_with_stage4()
ddls: list[str] = []
if check_exists:
ddls.append(_ddl_drop_execution_stage_check(dialect))
ddls.append(_ddl_add_execution_stage_check(dialect))
return ddls
def _sqlite_rebuild_seat_runs_with_stage4() -> list[str]:
"""Rebuild seat_runs with the widened execution_stage CHECK (SQLite only).
Same recipe as the Phase-3 migration: no column shape changes, only the
CHECK constraint is widened, so the data copy is a straight ``SELECT *``.
"""
return [
f"""
CREATE TABLE {SEAT_RUNS_TABLE}__stage4 (
id VARCHAR(64) NOT NULL PRIMARY KEY,
maf_run_id VARCHAR(64) NOT NULL,
agent_id VARCHAR(64) NOT NULL,
turn_index INTEGER NOT NULL,
execution_stage VARCHAR(32) NOT NULL DEFAULT 'legacy',
deerflow_run_id VARCHAR(64),
deerflow_thread_id VARCHAR(64),
sandbox_id VARCHAR(64),
workflow_checkpoint_id VARCHAR(128),
status VARCHAR(32) DEFAULT 'pending' NOT NULL,
result_snapshot TEXT,
started_at DATETIME,
finished_at DATETIME,
error TEXT,
created_at DATETIME NOT NULL,
updated_at DATETIME NOT NULL,
FOREIGN KEY (maf_run_id) REFERENCES maf_roundtable_runs (id) ON DELETE CASCADE,
CONSTRAINT uq_maf_seat_runs_run_agent_turn_stage
UNIQUE (maf_run_id, agent_id, turn_index, execution_stage),
CONSTRAINT ck_maf_seat_runs_execution_stage CHECK (execution_stage IN ({STAGE4_STAGES}))
)
""",
f"""
INSERT INTO {SEAT_RUNS_TABLE}__stage4 (
id, maf_run_id, agent_id, turn_index, execution_stage,
deerflow_run_id, deerflow_thread_id, sandbox_id, workflow_checkpoint_id,
status, result_snapshot, started_at, finished_at, error, created_at, updated_at
)
SELECT
id, maf_run_id, agent_id, turn_index, execution_stage,
deerflow_run_id, deerflow_thread_id, sandbox_id, workflow_checkpoint_id,
status, result_snapshot, started_at, finished_at, error, created_at, updated_at
FROM {SEAT_RUNS_TABLE}
""",
f"DROP TABLE {SEAT_RUNS_TABLE}",
f"ALTER TABLE {SEAT_RUNS_TABLE}__stage4 RENAME TO {SEAT_RUNS_TABLE}",
f"CREATE INDEX ix_maf_seat_runs_maf_run_id ON {SEAT_RUNS_TABLE} (maf_run_id)",
f"CREATE INDEX ix_maf_seat_runs_agent_id ON {SEAT_RUNS_TABLE} (agent_id)",
f"CREATE INDEX ix_maf_seat_runs_deerflow_run_id ON {SEAT_RUNS_TABLE} (deerflow_run_id)",
f"CREATE INDEX ix_maf_seat_runs_status ON {SEAT_RUNS_TABLE} (status)",
]
def validate_schema(inspector: Any) -> list[str]:
"""Return contract violations found by SQLAlchemy inspector.
Validates constraint CONTENT, not just names: a same-named Stage-3 CHECK is
reported as a violation until it really contains the Stage-4 stages.
"""
issues: list[str] = []
tables = set(inspector.get_table_names())
if SEAT_TASKS_TABLE not in tables:
issues.append(f"missing table: {SEAT_TASKS_TABLE}")
else:
cols = {c["name"] for c in inspector.get_columns(SEAT_TASKS_TABLE)}
for required in (
"id", "session_id", "run_id", "task_key", "agent_id",
"original_agent_id", "status", "required", "attempt_count",
"rework_count", "reassign_count", "created_at", "updated_at",
):
if required not in cols:
issues.append(f"{SEAT_TASKS_TABLE}: missing column {required}")
uq_cols = [
set(u.get("column_names", []))
for u in inspector.get_unique_constraints(SEAT_TASKS_TABLE)
]
idx_cols = [
set(idx.get("column_names", []))
for idx in inspector.get_indexes(SEAT_TASKS_TABLE)
if idx.get("unique")
]
if {"run_id", "task_key"} not in (uq_cols + idx_cols):
issues.append(f"{SEAT_TASKS_TABLE}: missing UNIQUE(run_id, task_key)")
status_sql = _check_constraint_sql(
inspector, SEAT_TASKS_TABLE, SEAT_TASKS_STATUS_CHECK_NAME
)
if status_sql is None:
issues.append(f"{SEAT_TASKS_TABLE}: missing status CHECK constraint")
else:
missing = [s for s in SEAT_TASKS_STATUSES if s not in status_sql]
if missing:
issues.append(
f"{SEAT_TASKS_TABLE}: status CHECK missing statuses: {', '.join(missing)}"
)
fk_targets: dict[str, str] = {}
try:
for fk in inspector.get_foreign_keys(SEAT_TASKS_TABLE):
for local in fk.get("constrained_columns") or []:
fk_targets[local] = fk.get("referred_table") or ""
except Exception: # noqa: BLE001
pass
if fk_targets.get("session_id") != "maf_roundtable_sessions":
issues.append(
f"{SEAT_TASKS_TABLE}: session_id must reference maf_roundtable_sessions"
)
if fk_targets.get("run_id") != "maf_roundtable_runs":
issues.append(
f"{SEAT_TASKS_TABLE}: run_id must reference maf_roundtable_runs"
)
if SEAT_RUNS_TABLE in tables:
if not _has_stage4_execution_stage_check(inspector):
issues.append(
f"{SEAT_RUNS_TABLE}: execution_stage CHECK missing or not widened "
f"to include {', '.join(STAGE4_NEW_STAGES)}"
)
return issues
def _do_migrate_sync(
sync_conn: Any,
*,
dry_run: bool,
logger: logging.Logger,
changes_ref: list[int],
) -> None:
"""Run all migration steps on a sync connection (called via run_sync).
Mirrors the Phase-3 migration's sync entry point so tests can drive the
migration against an arbitrary engine.
"""
from sqlalchemy import inspect, text
insp = inspect(sync_conn)
dialect = _dialect_name(sync_conn)
def _exec(sql: str) -> None:
if dry_run:
logger.info(" [dry-run] would execute: %s", sql.strip()[:300])
return
sync_conn.execute(text(sql))
changes_ref[0] += 1
existing = set(insp.get_table_names())
if SEAT_TASKS_TABLE not in existing:
logger.info("Creating %s", SEAT_TASKS_TABLE)
_exec(_seat_tasks_ddl(dialect))
for index_sql in _seat_tasks_indexes_ddl(dialect):
_exec(index_sql)
else:
logger.info("Already exists: %s", SEAT_TASKS_TABLE)
if SEAT_RUNS_TABLE in existing:
# The Stage-3 constraint carries the SAME name — only the SQL text
# (must contain both new stages) proves the table is already Stage 4.
check_sql = _execution_stage_check_sql(insp)
is_stage4 = _has_stage4_execution_stage_check(insp)
ddls = _widen_check_ddls(
dialect, check_exists=check_sql is not None, is_stage4=is_stage4
)
if not ddls:
logger.info("execution_stage CHECK already widened — no-op.")
elif dialect == "sqlite":
logger.info("SQLite: rebuilding %s to widen execution_stage CHECK", SEAT_RUNS_TABLE)
for stmt in ddls:
_exec(stmt)
else:
if check_sql is not None:
logger.info("Dropping stale execution_stage CHECK on %s", SEAT_RUNS_TABLE)
logger.info("Adding Stage-4 execution_stage CHECK on %s", SEAT_RUNS_TABLE)
for stmt in ddls:
_exec(stmt)
logger.info("Migration steps: %d applied.", changes_ref[0])
async def run_migration(database_url: str, *, dry_run: bool = False) -> None:
from sqlalchemy import inspect
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.pool import NullPool
engine = create_async_engine(database_url, poolclass=NullPool)
try:
async with engine.begin() as conn:
logger.info("Dialect: %s", _dialect_name(conn))
# Single code path: the sync entry point owns all detection / DDL
# decisions (including the Stage-3 same-name constraint case).
changes_ref = [0]
await conn.run_sync(
_do_migrate_sync,
dry_run=dry_run,
logger=logger,
changes_ref=changes_ref,
)
if dry_run:
logger.info("[DRY RUN] No statements were executed.")
return
def _validate(sync_conn: Any) -> list[str]:
return validate_schema(inspect(sync_conn))
issues = await conn.run_sync(_validate)
if issues:
logger.error("Schema validation FAILED:")
for issue in issues:
logger.error(" - %s", issue)
sys.exit(1)
logger.info("Schema validation passed.")
finally:
await engine.dispose()
def main() -> None:
parser = argparse.ArgumentParser(description="MAF roundtable Stage 4 migration")
parser.add_argument("--database-url", default=None, help="Async database URL (default: from config)")
parser.add_argument("--dry-run", action="store_true", help="Print DDL without executing")
args = parser.parse_args()
database_url = args.database_url
if database_url is None:
from pathlib import Path
import yaml
config_path = Path(__file__).resolve().parent.parent / "config.yaml"
if config_path.exists():
with open(config_path) as f:
cfg = yaml.safe_load(f) or {}
db_cfg = cfg.get("database", {})
database_url = db_cfg.get("url", "sqlite+aiosqlite:///./data/deerflow.db")
else:
database_url = "sqlite+aiosqlite:///./data/deerflow.db"
logger.info("Database: %s", database_url.split("?")[0])
asyncio.run(run_migration(database_url, dry_run=args.dry_run))
if __name__ == "__main__":
main()