mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

refactor(harness): route workflow persistence through repositories

Browse Source
This commit is contained in:
User
2026-07-16 18:01:29 +02:00
parent 259f021313
commit c1cddaa667
30 changed files with 925 additions and 348 deletions
Download Patch File Download Diff File Expand all files Collapse all files
harness/tht/cli/session_cmd.py
+114 -92
View File
@@ -10,6 +10,22 @@ from tht.cli.schema_cmd import _load_config_or_exit
session_app = typer.Typer(help="Sessioni (directory artefatti)")
def session_repository(cfg):
"""Configured persistence boundary for every workflow command."""
from tht.session.repository import build_session_repository
return build_session_repository(cfg)
def session_dir(cfg, session_id: str) -> Path:
"""Legacy path bridge for out-of-scope datamart/memory compatibility only.
Workflow session commands in this module use ``session_repository``; this
helper remains until those non-workflow consumers lose their path APIs.
"""
return cfg.paths.sessions / session_id
@session_app.command("migrate")
def migrate_cmd(
database_url: str = typer.Option(
@@ -43,15 +59,21 @@ def migrate_cmd(
)
def session_dir(cfg, session_id: str) -> Path:
return cfg.paths.sessions / session_id
def load_session_or_exit(cfg, session_id: str):
from tht.session.store import SessionError, load_session
from tht.session.store import SessionError
try:
return load_session(session_id, cfg.paths.sessions)
return session_repository(cfg).get(session_id).manifest
except SessionError as e:
typer.secho(f"ERRORE: {e}", fg=typer.colors.RED, err=True)
raise typer.Exit(code=1)
def load_snapshot_or_exit(cfg, session_id: str):
from tht.session.store import SessionError
try:
return session_repository(cfg).get(session_id)
except SessionError as e:
typer.secho(f"ERRORE: {e}", fg=typer.colors.RED, err=True)
raise typer.Exit(code=1)
@@ -93,7 +115,14 @@ def list_cmd(
) -> None:
"""Elenca le sessioni esistenti."""
cfg = _load_config_or_exit(config)
rows = _list_sessions(cfg.paths.sessions)
rows = [
{"id": s.manifest.id, "status": s.manifest.status, "question": s.manifest.question,
"summary": s.manifest.summary, "created_at": s.manifest.created_at.isoformat(),
"updated_at": s.manifest.updated_at.isoformat() if s.manifest.updated_at else None,
"author": s.manifest.author, "name": s.manifest.name, "group": s.manifest.group,
"archived": s.manifest.archived}
for s in session_repository(cfg).list()
]
if json_out:
typer.echo(json.dumps(rows, ensure_ascii=False, indent=2))
return
@@ -112,16 +141,19 @@ def new_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Crea una sessione e stampa il suo id (ultima riga dell'output)."""
from tht.session.store import _extract_name, create_session
from tht.session.store import _extract_name, new_session_manifest, render_question_md
cfg = _load_config_or_exit(config)
manifest = create_session(question, cfg.database, cfg.paths.sessions,
manifest = new_session_manifest(question, cfg.database,
provider=provider, model=model, thinking=thinking,
name=name or _extract_name(question))
repository = session_repository(cfg)
repository.create(manifest)
repository.write_artifact(manifest.id, "question", render_question_md(question))
if json_out:
typer.echo(json.dumps({"id": manifest.id}, ensure_ascii=False))
return
typer.secho(f"OK: sessione creata in {session_dir(cfg, manifest.id)}", fg=typer.colors.GREEN)
typer.secho(f"OK: sessione creata ({manifest.id})", fg=typer.colors.GREEN)
typer.echo(manifest.id)
@@ -136,12 +168,12 @@ def set_question_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Scrive question.md (domanda riscritta + assunzioni) in modo deterministico."""
from tht.session.store import set_question
from tht.session.store import render_question_md
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
path = set_question(session_id, question, assumption or [], cfg.paths.sessions)
typer.secho(f"OK: question.md aggiornato ({path}).", fg=typer.colors.GREEN)
session_repository(cfg).write_artifact(session_id, "question", render_question_md(question, assumption or []))
typer.secho("OK: question.md aggiornato.", fg=typer.colors.GREEN)
@session_app.command("set-schema-linking")
@@ -157,7 +189,7 @@ def set_schema_linking_cmd(
from pydantic import ValidationError
from tht.session.store import set_schema_linking
from tht.session.models import SchemaLinking
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
@@ -168,11 +200,12 @@ def set_schema_linking_cmd(
typer.secho(f"ERRORE: JSON non valido: {e}", fg=typer.colors.RED, err=True)
raise typer.Exit(code=5)
try:
path = set_schema_linking(session_id, data, cfg.paths.sessions)
model = SchemaLinking.model_validate(data)
session_repository(cfg).write_artifact(session_id, "schema_linking", json.dumps(model.model_dump(by_alias=True), indent=2, ensure_ascii=False))
except ValidationError as e:
typer.secho(f"ERRORE: schema_linking non valido:\n{e}", fg=typer.colors.RED, err=True)
raise typer.Exit(code=5)
typer.secho(f"OK: schema_linking.json aggiornato ({path}).", fg=typer.colors.GREEN)
typer.secho("OK: schema_linking.json aggiornato.", fg=typer.colors.GREEN)
@session_app.command("sync-schema-linking")
@@ -183,16 +216,17 @@ def sync_schema_linking_cmd(
"""Riproietta schema_linking.json dalle decisioni F4 del ledger (deterministico)."""
from pydantic import ValidationError
from tht.session.store import sync_schema_linking
from tht.session.store import sync_schema_linking_snapshot
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
try:
path = sync_schema_linking(session_id, cfg.paths.sessions)
content = sync_schema_linking_snapshot(load_snapshot_or_exit(cfg, session_id))
session_repository(cfg).write_artifact(session_id, "schema_linking", content)
except ValidationError as e:
typer.secho(f"ERRORE: schema_linking non valido:\n{e}", fg=typer.colors.RED, err=True)
raise typer.Exit(code=5)
typer.secho(f"OK: schema_linking.json riproiettato ({path}).", fg=typer.colors.GREEN)
typer.secho("OK: schema_linking.json riproiettato.", fg=typer.colors.GREEN)
@session_app.command("show")
@@ -202,28 +236,27 @@ def show_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Stato della sessione: manifest + decisioni registrate (per la ripresa)."""
from tht.decisions import list_decisions
from tht.phase import current_phase
cfg = _load_config_or_exit(config)
manifest = load_session_or_exit(cfg, session_id)
sdir = session_dir(cfg, session_id)
snapshot = load_snapshot_or_exit(cfg, session_id)
if json_out:
has_schema_linking = (sdir / "schema_linking.json").exists()
phase = current_phase(sdir)
has_schema_linking = "schema_linking" in snapshot.artifacts
phase = current_phase(snapshot)
data = manifest.model_dump(mode="json", by_alias=True)
data["phase"] = phase
data["has_schema_linking"] = has_schema_linking
# Ledger integrale: il gate lo usa per costruire deterministicamente il
# recap delle decisioni nei riepiloghi di fase (v2).
data["decisions"] = [
d.model_dump(mode="json") for d in list_decisions(sdir)
d.model_dump(mode="json") for d in snapshot.decisions
]
typer.echo(json.dumps(data, ensure_ascii=False, indent=2))
return
decisions = list_decisions(sdir)
decisions = snapshot.decisions
typer.echo(f"id : {manifest.id}")
typer.echo(f"stato : {manifest.status}")
typer.echo(f"domanda : {manifest.question}")
@@ -231,8 +264,7 @@ def show_cmd(
typer.echo(f"decisioni: {len(decisions)}")
for d in decisions[-10:]:
typer.echo(f" [{d.seq}] {d.type}: {d.subject}" + (f" — {d.detail}" if d.detail else ""))
linking = sdir / "schema_linking.json"
typer.echo(f"schema_linking.json: {'presente' if linking.exists() else 'assente'}")
typer.echo(f"schema_linking.json: {'presente' if 'schema_linking' in snapshot.artifacts else 'assente'}")
@session_app.command("retrieval-pack")
@@ -243,12 +275,10 @@ def retrieval_pack_cmd(
"""Emette su stdout il retrieval pack persistito della sessione."""
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
path = session_dir(cfg, session_id) / "retrieval_pack.md"
try:
content = path.read_text()
except OSError as exc:
content = load_snapshot_or_exit(cfg, session_id).artifacts.get("retrieval_pack")
if content is None:
typer.secho(
f"ERRORE: retrieval pack non disponibile per la sessione {session_id}: {exc}",
f"ERRORE: retrieval pack non disponibile per la sessione {session_id}",
fg=typer.colors.RED,
err=True,
)
@@ -259,32 +289,32 @@ def retrieval_pack_cmd(
@session_app.command("close")
def close_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OPT) -> None:
"""Chiude la sessione (status=closed)."""
from tht.session.store import close_session
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
close_session(session_id, cfg.paths.sessions)
snapshot = load_snapshot_or_exit(cfg, session_id)
snapshot.manifest.status = "closed"
session_repository(cfg).save_manifest(snapshot.manifest)
typer.secho(f"OK: sessione {session_id} chiusa.", fg=typer.colors.GREEN)
@session_app.command("fail")
def fail_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OPT) -> None:
"""Registra un arresto del sistema non recuperabile automaticamente."""
from tht.session.store import fail_session
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
fail_session(session_id, cfg.paths.sessions)
snapshot = load_snapshot_or_exit(cfg, session_id)
snapshot.manifest.status = "failed"
session_repository(cfg).save_manifest(snapshot.manifest)
typer.secho(f"OK: sessione {session_id} marcata failed.", fg=typer.colors.RED)
@session_app.command("reopen")
def reopen_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OPT) -> None:
"""Riapre una sessione per una ripresa manuale."""
from tht.session.store import reopen_session
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
reopen_session(session_id, cfg.paths.sessions)
snapshot = load_snapshot_or_exit(cfg, session_id)
snapshot.manifest.status = "open"
session_repository(cfg).save_manifest(snapshot.manifest)
typer.secho(f"OK: sessione {session_id} riaperta.", fg=typer.colors.GREEN)
@@ -295,11 +325,11 @@ def set_name_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Imposta il nome descrittivo della sessione."""
from tht.session.store import set_name
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
set_name(session_id, name, cfg.paths.sessions)
snapshot = load_snapshot_or_exit(cfg, session_id)
snapshot.manifest.name = name.strip() or None
session_repository(cfg).save_manifest(snapshot.manifest)
typer.secho(f"OK: nome aggiornato per {session_id}.", fg=typer.colors.GREEN)
@@ -310,44 +340,42 @@ def set_group_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Sposta la sessione in un gruppo (o la toglie da ogni gruppo)."""
from tht.session.store import set_group
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
set_group(session_id, group, cfg.paths.sessions)
snapshot = load_snapshot_or_exit(cfg, session_id)
snapshot.manifest.group = group.strip() or None
session_repository(cfg).save_manifest(snapshot.manifest)
typer.secho(f"OK: gruppo aggiornato per {session_id}.", fg=typer.colors.GREEN)
@session_app.command("archive")
def archive_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OPT) -> None:
"""Archivia la sessione (la toglie dalla lista attiva, sola lettura)."""
from tht.session.store import set_archived
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
set_archived(session_id, True, cfg.paths.sessions)
snapshot = load_snapshot_or_exit(cfg, session_id)
snapshot.manifest.archived = True
session_repository(cfg).save_manifest(snapshot.manifest)
typer.secho(f"OK: sessione {session_id} archiviata.", fg=typer.colors.GREEN)
@session_app.command("unarchive")
def unarchive_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OPT) -> None:
"""Ripristina la sessione dall'archivio (non ne cambia la ripristinabilità)."""
from tht.session.store import set_archived
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
set_archived(session_id, False, cfg.paths.sessions)
snapshot = load_snapshot_or_exit(cfg, session_id)
snapshot.manifest.archived = False
session_repository(cfg).save_manifest(snapshot.manifest)
typer.secho(f"OK: sessione {session_id} ripristinata.", fg=typer.colors.GREEN)
@session_app.command("delete")
def delete_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OPT) -> None:
"""Elimina definitivamente la cartella di sessione."""
from tht.session.store import delete_session
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
delete_session(session_id, cfg.paths.sessions)
session_repository(cfg).delete(session_id)
typer.secho(f"OK: sessione {session_id} eliminata.", fg=typer.colors.GREEN)
@@ -358,11 +386,10 @@ def documents_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Documenti di sola lettura della sessione (domanda, rivista, schema, SQL, report, decisioni)."""
from tht.session.store import build_documents
from tht.session.store import build_snapshot_documents
cfg = _load_config_or_exit(config)
manifest = load_session_or_exit(cfg, session_id)
docs = build_documents(manifest, session_dir(cfg, session_id))
docs = build_snapshot_documents(load_snapshot_or_exit(cfg, session_id))
if json_out:
typer.echo(json.dumps(docs, ensure_ascii=False, indent=2))
return
@@ -376,19 +403,18 @@ def session_problems(cfg, session_id: str) -> list[str]:
from pydantic import ValidationError
from tht.decisions import list_decisions
from tht.session.models import SchemaLinking
sdir = session_dir(cfg, session_id)
snapshot = load_snapshot_or_exit(cfg, session_id)
problems: list[str] = []
if not list_decisions(sdir):
if not snapshot.decisions:
problems.append("nessuna decisione registrata (review_decisions.jsonl vuoto o assente)")
linking_path = sdir / "schema_linking.json"
if not linking_path.exists():
raw_linking = snapshot.artifacts.get("schema_linking")
if raw_linking is None:
problems.append("schema_linking.json assente")
else:
try:
SchemaLinking.model_validate(json.loads(linking_path.read_text()))
SchemaLinking.model_validate(json.loads(raw_linking))
except (json.JSONDecodeError, ValidationError) as e:
problems.append(f"schema_linking.json non valido: {e}")
return problems
@@ -402,7 +428,7 @@ def check_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OPT)
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session_id)
cur = current_phase(session_dir(cfg, session_id))
cur = current_phase(load_snapshot_or_exit(cfg, session_id))
wf = load_workflow()
schema_linking_phase = wf.schema_linking_phase()
if cur < schema_linking_phase:
@@ -443,7 +469,7 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
do_run,
promoted_tables_for,
)
from tht.ctetest import CteError, load_cte_tests
from tht.ctetest import CteError, CteTestRecord, _iter_json_objects
from tht.execute import ExecutionError
from tht.execute.warnings import plan_warnings, runtime_warnings, static_warnings
from tht.report import extract_reviewer_notes, render_validation_report
@@ -454,13 +480,13 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
from tht.sqlcheck import validate_sql
cfg = _load_config_or_exit(config)
manifest = load_session_or_exit(cfg, session_id)
sdir = session_dir(cfg, session_id)
repository = session_repository(cfg)
snapshot = load_snapshot_or_exit(cfg, session_id)
from tht.phase import current_phase
from tht.workflow import load_workflow
cur = current_phase(sdir)
cur = current_phase(snapshot)
wf = load_workflow()
if cur <= wf.max_phase:
typer.secho(
@@ -474,9 +500,9 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
# --- gate di ingresso ---
# Vista effective (D15): un sql_approved/cte ritirato o stale post-rollback non conta.
problems = session_problems(cfg, session_id)
decisions = effective_decisions(sdir)
sql_file = sdir / "sql_final.sql"
if not sql_file.exists():
decisions = effective_decisions(snapshot)
sql = snapshot.artifacts.get("sql_final")
if sql is None:
problems.append("sql_final.sql assente")
if not any(d.type == "sql_approved" for d in decisions):
problems.append(
@@ -485,10 +511,11 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
)
# I CTE richiesti sono quelli del PIANO effettivo, non i file glob su disco: un
# ctes/*.sql orfano lasciato da un teardown incompleto non deve bloccare il finalize.
plan = effective_cte_plan(sdir)
plan = effective_cte_plan(snapshot)
if plan:
try:
tested = {r.name for r in load_cte_tests(sdir)}
raw_tests = snapshot.artifacts.get("cte_tests", "")
tested = {r.name for r in map(CteTestRecord.model_validate, _iter_json_objects(raw_tests))}
except CteError as e:
typer.secho(
f"Finalize rifiutato: impossibile leggere cte_tests.json: {e}",
@@ -505,7 +532,7 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
raise typer.Exit(code=3)
# --- batteria di validazione su sql_final.sql ---
sql = sql_file.read_text()
assert sql is not None
check = validate_sql(
sql,
physical=_load_physical_or_exit(cfg),
@@ -527,34 +554,29 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
raise typer.Exit(code=3)
# --- validation_report.md (preservando le note del reviewer) ---
report_path = sdir / "validation_report.md"
existing_notes = (
extract_reviewer_notes(report_path.read_text()) if report_path.exists() else ""
)
report_path.write_text(render_validation_report(
existing_report = snapshot.artifacts.get("validation_report", "")
existing_notes = extract_reviewer_notes(existing_report) if existing_report else ""
report = render_validation_report(
session_id=session_id, check=check, plan=plan,
plan_warnings=plan_warnings(plan, cfg.execution),
result=result, runtime_warnings=runtime_warnings(result, cfg.execution),
static_warnings=static_warnings(check.ast), limit=limit,
reviewer_notes=existing_notes,
))
)
# --- evidence.json ---
linking = SchemaLinking.model_validate(
json.loads((sdir / "schema_linking.json").read_text())
json.loads(snapshot.artifacts["schema_linking"])
)
entries = build_evidence_entries(decisions, linking, cfg.paths.artifacts / "evidence")
(sdir / "evidence.json").write_text(json.dumps(entries, ensure_ascii=False, indent=2))
evidence = json.dumps(entries, ensure_ascii=False, indent=2)
# --- manifest + riepilogo ---
from datetime import UTC, datetime
from tht.session.store import persist_verified_finalization
from tht.session.store import MANIFEST, current_author
manifest.status = "finalized"
manifest.updated_at = datetime.now(UTC)
manifest.updated_by = current_author()
manifest.to_yaml(sdir / MANIFEST)
persist_verified_finalization(
repository, session_id, validation_report=report, evidence=evidence
)
# --- memoria attiva (parte B): indicizza la coppia domanda->SQL, best-effort ---
# Import lazy: memory_cmd importa da session_cmd (un import top-level qui sarebbe
# circolare). Qualunque errore (writer key assente, VPN giu', Ollama spento) NON
@@ -581,5 +603,5 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
)
typer.secho(f"OK: sessione {session_id} finalizzata. Artefatti:", fg=typer.colors.GREEN)
for name in ARTIFACT_FILES:
state = "presente" if (sdir / name).exists() else "assente"
state = "presente" if name not in {"session_manifest.yaml", "review_decisions.jsonl"} else "persistito"
typer.echo(f" - {name}: {state}")