refactor(harness): route workflow persistence through repositories

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
+50 -33
View File
@@ -6,7 +6,7 @@ import typer
from tht.cli.config_cmd import CONFIG_OPT
from tht.cli.schema_cmd import _load_config_or_exit
from tht.cli.session_cmd import load_session_or_exit, session_dir
from tht.cli.session_cmd import load_session_or_exit, load_snapshot_or_exit, session_repository
from tht.cli.sql_cmd import promoted_tables_for, require_action
_RULE6_HINT = (
@@ -17,6 +17,27 @@ _RULE6_HINT = (
cte_app = typer.Typer(help="Test controllato dei CTE proposti (Agent View Generation)")
@cte_app.command("save")
def save_cmd(
session: str = typer.Option(..., "--session"),
name: str = typer.Option(..., "--name"),
file: str = typer.Option(..., "--file", help="File SQL, oppure '-' per stdin."),
config: Path = CONFIG_OPT,
) -> None:
"""Persist one CTE SQL block through the configured session repository."""
import sys
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
raw = sys.stdin.read() if file == "-" else Path(file).read_text()
try:
session_repository(cfg).write_artifact(session, f"cte_sql:{name}", raw)
except ValueError as exc:
typer.secho(f"ERRORE: {exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(code=1) from None
typer.secho(f"OK: CTE {name} salvato.", fg=typer.colors.GREEN)
@cte_app.command("test")
def test_cmd(
name: str = typer.Argument(..., help="Nome del CTE (file sessions/<id>/ctes/<nome>.sql)."),
@@ -33,7 +54,7 @@ def test_cmd(
CteError,
CteTestRecord,
_jsonable,
append_cte_test,
append_cte_test_snapshot,
build_test_sql,
has_trailing_select,
)
@@ -43,13 +64,13 @@ def test_cmd(
cfg = _load_config_or_exit(config)
require_action(cfg, "cte_test")
load_session_or_exit(cfg, session)
sdir = session_dir(cfg, session)
snapshot = load_snapshot_or_exit(cfg, session)
from tht.cli.phase_cmd import require_phase_or_exit
from tht.phase import next_cte
require_phase_or_exit(cfg, session, 6)
nxt = next_cte(sdir)
nxt = next_cte(snapshot)
if nxt is not None and name != nxt:
typer.secho(
f"ERRORE: ordine CTE. Ora tocca a '{nxt}' (il primo CTE del piano non "
@@ -60,11 +81,10 @@ def test_cmd(
)
raise typer.Exit(code=5)
cte_file = sdir / "ctes" / f"{name}.sql"
if not cte_file.exists():
typer.secho(f"ERRORE: file CTE non trovato: {cte_file}", fg=typer.colors.RED, err=True)
cte_sql = snapshot.artifacts.get(f"cte_sql:{name}")
if cte_sql is None:
typer.secho(f"ERRORE: file CTE non trovato: {name}", fg=typer.colors.RED, err=True)
raise typer.Exit(code=1)
cte_sql = cte_file.read_text()
sql_hash = hashlib.sha256(cte_sql.encode()).hexdigest()
def _record_error(message: str) -> None:
@@ -72,7 +92,7 @@ def test_cmd(
name=name, ts=datetime.now(UTC), sql_hash=sql_hash,
status="error", error=message,
)
append_cte_test(sdir, record)
append_cte_test_snapshot(session_repository(cfg), snapshot, record)
if json_out:
typer.echo(record.model_dump_json())
else:
@@ -118,7 +138,7 @@ def test_cmd(
execution_ms=result.execution_ms, warnings=warnings,
preview_rows=[[_jsonable(cell) for cell in row] for row in result.rows],
)
append_cte_test(sdir, record)
append_cte_test_snapshot(session_repository(cfg), snapshot, record)
if json_out:
typer.echo(record.model_dump_json())
@@ -133,7 +153,7 @@ def test_cmd(
Console().print(table)
for w in warnings:
typer.secho(f" warning: {w}", fg=typer.colors.YELLOW)
typer.secho(f"OK: esito registrato in {sdir / 'cte_tests.json'}", fg=typer.colors.GREEN)
typer.secho("OK: esito registrato in cte_tests.json", fg=typer.colors.GREEN)
CTE_PLAN_DOC_FILE = "cte_plan_doc.json"
@@ -156,13 +176,10 @@ def plan_cmd(
import json
import sys
from tht.phase import CTE_PLAN_FILE
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
from tht.cli.phase_cmd import require_phase_or_exit
require_phase_or_exit(cfg, session, 6)
sdir = session_dir(cfg, session)
doc_data = None
if doc is not None:
@@ -180,11 +197,11 @@ def plan_cmd(
)
raise typer.Exit(code=1)
sdir.mkdir(parents=True, exist_ok=True)
(sdir / CTE_PLAN_FILE).write_text(json.dumps(name, ensure_ascii=False))
repository = session_repository(cfg)
repository.write_artifact(session, "cte_plan", json.dumps(name, ensure_ascii=False))
if doc_data is not None:
(sdir / CTE_PLAN_DOC_FILE).write_text(json.dumps(doc_data, ensure_ascii=False))
typer.secho(f"OK: piano CTE salvato ({len(name)} CTE) in {sdir / CTE_PLAN_FILE}.",
repository.write_artifact(session, "cte_plan_doc", json.dumps(doc_data, ensure_ascii=False))
typer.secho(f"OK: piano CTE salvato ({len(name)} CTE).",
fg=typer.colors.GREEN)
@@ -201,7 +218,7 @@ def next_cmd(
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
nxt = next_cte(session_dir(cfg, session))
nxt = next_cte(load_snapshot_or_exit(cfg, session))
if nxt:
typer.echo(nxt)
@@ -222,9 +239,9 @@ def info_cmd(
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
sdir = session_dir(cfg, session)
snapshot = load_snapshot_or_exit(cfg, session)
plan = cte_plan(sdir)
plan = cte_plan(snapshot)
if not plan:
typer.secho(f"ERRORE: {CTE_PLAN_FILE} assente o vuoto per la sessione '{session}'.",
fg=typer.colors.RED, err=True)
@@ -234,24 +251,24 @@ def info_cmd(
fg=typer.colors.RED, err=True)
raise typer.Exit(code=1)
cte_file = sdir / "ctes" / f"{name}.sql"
if not cte_file.exists():
typer.secho(f"ERRORE: file CTE non trovato: {cte_file}", fg=typer.colors.RED, err=True)
cte_sql = snapshot.artifacts.get(f"cte_sql:{name}")
if cte_sql is None:
typer.secho(f"ERRORE: file CTE non trovato: {name}", fg=typer.colors.RED, err=True)
raise typer.Exit(code=1)
doc = None
doc_path = sdir / CTE_PLAN_DOC_FILE
if doc_path.exists():
full_doc = _json.loads(doc_path.read_text())
raw_doc = snapshot.artifacts.get("cte_plan_doc")
if raw_doc:
full_doc = _json.loads(raw_doc)
for c in full_doc.get("ctes", []):
if c.get("name") == name:
doc = {k: v for k, v in c.items() if k != "name"}
break
from tht.ctetest import CteError, load_cte_tests
from tht.ctetest import CteError, load_cte_tests_text
try:
records = [r for r in load_cte_tests(sdir) if r.name == name]
records = [r for r in load_cte_tests_text(snapshot.artifacts.get("cte_tests", "")) if r.name == name]
except CteError as e:
typer.secho(f"ERRORE: impossibile leggere cte_tests.json: {e}",
fg=typer.colors.RED, err=True)
@@ -263,8 +280,8 @@ def info_cmd(
"index": plan.index(name) + 1,
"total": len(plan),
"plan": plan,
"sql": cte_file.read_text(),
"approved": name in approved_ctes(sdir),
"sql": cte_sql,
"approved": name in approved_ctes(snapshot),
"doc": doc,
"last_test": last_test,
}
@@ -282,12 +299,12 @@ def list_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Ultimo esito registrato per ogni CTE della sessione."""
from tht.ctetest import CteError, load_cte_tests
from tht.ctetest import CteError, load_cte_tests_text
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
try:
records = load_cte_tests(session_dir(cfg, session))
records = load_cte_tests_text(load_snapshot_or_exit(cfg, session).artifacts.get("cte_tests", ""))
except CteError as e:
typer.secho(f"ERRORE: impossibile leggere cte_tests.json: {e}",
fg=typer.colors.RED, err=True)
+17 -21
View File
@@ -8,7 +8,7 @@ from pydantic import ValidationError
from tht.cli.config_cmd import CONFIG_OPT
from tht.cli.schema_cmd import _load_config_or_exit
from tht.cli.session_cmd import load_session_or_exit, session_dir
from tht.cli.session_cmd import load_session_or_exit, load_snapshot_or_exit, session_repository
decision_app = typer.Typer(help="Decisioni del reviewer (per sessione, append-only)")
@@ -20,7 +20,7 @@ def add_join_set_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Registra un insieme completo di join con un'unica sostituzione atomica del ledger."""
from tht.decisions import DecisionInput, append_decisions
from tht.decisions import DecisionInput
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
@@ -40,7 +40,7 @@ def add_join_set_cmd(
from tht.workflow import load_workflow
require_phase_or_exit(cfg, session, load_workflow().decision_min_phase("join_modified"))
records = append_decisions(session_dir(cfg, session), decisions)
records = session_repository(cfg).append_decisions(session, decisions)
typer.secho(
f"OK: registrato set atomico di {len(records)} join.",
fg=typer.colors.GREEN,
@@ -61,7 +61,7 @@ def add_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Registra una decisione del reviewer nella sessione."""
from tht.decisions import DecisionType, append_decision
from tht.decisions import DecisionType
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
@@ -82,7 +82,7 @@ def add_cmd(
from tht.workflow import load_workflow
require_phase_or_exit(cfg, session, load_workflow().decision_min_phase(type))
sdir = session_dir(cfg, session)
snapshot = load_snapshot_or_exit(cfg, session)
if type == "cte_approved":
# Un CTE si approva solo se appartiene al piano persistito. Senza piano
# (o con subject fuori piano) l'approvazione e' priva di significato:
@@ -90,7 +90,7 @@ def add_cmd(
# dove fu registrato un cte_approved:cte_plan senza alcun cte_plan.json.
from tht.phase import cte_plan
plan = cte_plan(sdir)
plan = cte_plan(snapshot)
if not plan:
typer.secho(
"ERRORE: nessun piano CTE (cte_plan.json) in sessione. Persisti prima "
@@ -105,10 +105,10 @@ def add_cmd(
fg=typer.colors.RED, err=True,
)
raise typer.Exit(code=5)
record = append_decision(
sdir, type=type, subject=subject,
detail=detail, rationale=rationale, retracts=retracts,
)
record = session_repository(cfg).append_decisions(session, [{
"type": type, "subject": subject, "detail": detail,
"rationale": rationale, "retracts": retracts,
}])[0]
typer.secho(f"OK: decisione [{record.seq}] {record.type}: {record.subject}",
fg=typer.colors.GREEN)
@@ -123,19 +123,18 @@ def retract_cmd(
Granularita' (a) del rollback §4.8: 'rispondi di nuovo a questa domanda'. Scrive un
marker decision_retracted (append-only, l'audit resta) che effective_decisions onora;
il widget corrente puo' essere riproposto. Non cambia la fase."""
from tht.decisions import append_decision
from tht.phase import effective_decisions
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
sdir = session_dir(cfg, session)
snapshot = load_snapshot_or_exit(cfg, session)
# Ultima decisione NON-meta della vista effective = quella associata al widget corrente.
meta = {
"phase_approved", "phase_auto_approved", "phase_reopened",
"phase_skipped", "decision_retracted",
}
substantive = [d for d in effective_decisions(sdir) if d.type not in meta]
substantive = [d for d in effective_decisions(snapshot) if d.type not in meta]
if not substantive:
typer.secho(
"Nessuna decisione sostanziale da ritirare nella fase corrente.",
@@ -143,10 +142,10 @@ def retract_cmd(
)
raise typer.Exit(code=6)
target = substantive[-1]
record = append_decision(
sdir, type="decision_retracted", subject=target.subject,
rationale=f"ritira [{target.seq}] {target.type}", retracts=target.seq,
)
record = session_repository(cfg).append_decisions(session, [{
"type": "decision_retracted", "subject": target.subject,
"rationale": f"ritira [{target.seq}] {target.type}", "retracts": target.seq,
}])[0]
typer.secho(
f"OK: ritirata decisione [{target.seq}] {target.type}: {target.subject} "
f"(marker #{record.seq}).",
@@ -160,11 +159,8 @@ def list_cmd(
config: Path = CONFIG_OPT,
) -> None:
"""Elenca le decisioni della sessione."""
from tht.decisions import list_decisions
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
decisions = list_decisions(session_dir(cfg, session))
decisions = load_snapshot_or_exit(cfg, session).decisions
if not decisions:
typer.echo("Nessuna decisione registrata.")
return
+14 -24
View File
@@ -17,7 +17,7 @@ from tht.cli._guards import (
require_server_profile,
require_vector_write_allowed,
)
from tht.cli.session_cmd import load_session_or_exit, session_dir
from tht.cli.session_cmd import load_snapshot_or_exit
from tht.cli.vector_cmd import require_vector_cfg
memory_app = typer.Typer(help="Review memory (registro canonico + indice pgvector)")
@@ -48,18 +48,17 @@ def promote_cmd(
"""Promuove le decisioni SCELTE nel registro globale. Usa --preview per vedere i candidati."""
import json as _json
from tht.memory import promote
from tht.memory import promote_snapshot
cfg = _load_config_or_exit(config)
manifest = load_session_or_exit(cfg, session)
snapshot = load_snapshot_or_exit(cfg, session)
if preview:
from tht.memory import (
MAX_PROMOTION_CANDIDATES, preview_promotions, reusable_promotions,
MAX_PROMOTION_CANDIDATES, preview_promotions_snapshot, reusable_promotions_snapshot,
)
sdir = session_dir(cfg, session)
cand = preview_promotions(sdir, manifest, registry_path(cfg))
extra = len(reusable_promotions(sdir, manifest, registry_path(cfg))) - len(cand)
cand = preview_promotions_snapshot(snapshot, registry_path(cfg))
extra = len(reusable_promotions_snapshot(snapshot, registry_path(cfg))) - len(cand)
payload = [
{"decision_seq": c.decision_seq, "type": c.type, "subject": c.subject,
"detail": c.detail, "rationale": c.rationale,
@@ -89,10 +88,7 @@ def promote_cmd(
require_server_profile(cfg, "memory promote")
require_vector_cfg(cfg)
promoted = promote(
session_dir(cfg, session), manifest,
seqs=list(decision), registry_path=registry_path(cfg),
)
promoted = promote_snapshot(snapshot, seqs=list(decision), registry_path=registry_path(cfg))
if not promoted:
msg = "Nessuna nuova promozione (gia' presenti o seq inesistenti)."
if json_out:
@@ -155,18 +151,17 @@ def save_one_cmd(
from tht.adapters.factory import build_vector_store
from tht.cli.vector_cmd import make_embedder
from tht.memory import load_registry, promote, save_one_memory
from tht.memory import load_registry, promote_snapshot, save_one_memory
cfg = _load_config_or_exit(config)
manifest = load_session_or_exit(cfg, session)
snapshot = load_snapshot_or_exit(cfg, session)
require_vector_write_allowed(cfg, "memory save-one")
store = build_vector_store(cfg, require_write=True)
sdir = session_dir(cfg, session)
# Promuove la decisione scelta nel registro locale (idempotente: salta se gia' presente
# o se stale post-rollback, perche' _compute_promotions usa la vista effective).
promote(sdir, manifest, seqs=[decision], registry_path=registry_path(cfg))
records = [r for r in load_registry(registry_path(cfg)) if r.session_id == manifest.id]
promote_snapshot(snapshot, seqs=[decision], registry_path=registry_path(cfg))
records = [r for r in load_registry(registry_path(cfg)) if r.session_id == snapshot.manifest.id]
embedder = make_embedder(cfg.embeddings)
count = save_one_memory(records, decision, store=store, embedder=embedder)
@@ -388,16 +383,14 @@ def search_cmd(
from rich.console import Console
from rich.table import Table
from tht.cli.session_cmd import session_dir
from tht.cli.vector_cmd import make_embedder, open_searcher, require_vector_cfg
from tht.memory import decided_memory_ids, load_registry
from tht.decisions import list_decisions
cfg = _load_config_or_exit(config)
require_vector_cfg(cfg)
excluded: set[str] = set()
if session is not None:
excluded = decided_memory_ids(list_decisions(session_dir(cfg, session)))
excluded = decided_memory_ids(load_snapshot_or_exit(cfg, session).decisions)
searcher = open_searcher(cfg)
embedder = make_embedder(cfg.embeddings)
hits = searcher.search(embedder.embed_query(question), top_n=top, kinds=["memory"])
@@ -445,7 +438,7 @@ def index_solved_session(cfg, session_id: str) -> int:
from tht.adapters.factory import build_vector_store
from tht.cli.sql_cmd import promoted_tables_for
from tht.cli.vector_cmd import make_embedder
from tht.solved import build_solved_record, save_solved_question
from tht.solved import build_solved_snapshot, save_solved_question
if not has_vector_write_rest(cfg):
raise RuntimeError(
@@ -453,10 +446,7 @@ def index_solved_session(cfg, session_id: str) -> int:
"writer key configurata nel workspace yaml"
)
store = build_vector_store(cfg, require_write=True)
manifest = load_session_or_exit(cfg, session_id)
record = build_solved_record(
session_dir(cfg, session_id), manifest, promoted_tables_for(cfg, session_id)
)
record = build_solved_snapshot(load_snapshot_or_exit(cfg, session_id), promoted_tables_for(cfg, session_id))
return save_solved_question(
record,
store=store,
+27 -24
View File
@@ -8,7 +8,6 @@ commands. All read workflow facts from load_workflow() (no mirrored constants).
from __future__ import annotations
import json
from pathlib import Path
import typer
@@ -22,16 +21,12 @@ from tht.workflow import load_workflow
phase_app = typer.Typer(help="Fase del workflow HITL (gate di avanzamento/ritorno)")
def session_dir(cfg, session_id: str) -> Path:
"""Where a session's artifacts live. Mirror of session_cmd.session_dir (kept
here to avoid a circular import: session_cmd imports phase helpers too)."""
return cfg.paths.sessions / session_id
def require_phase_or_exit(cfg, session: str, min_phase: int) -> None:
"""Refuse with exit 1 if the session hasn't reached min_phase yet. The phase
name in the message comes from workflow.yaml (load_workflow), not a constant."""
cur = current_phase(session_dir(cfg, session))
from tht.cli.session_cmd import load_snapshot_or_exit
cur = current_phase(load_snapshot_or_exit(cfg, session))
if cur < min_phase:
wf = load_workflow()
nome = wf.phase_name(min_phase)
@@ -89,21 +84,24 @@ def advance_cmd(
),
) -> None:
"""Approva la fase corrente e passa alla successiva (persiste phase_approved)."""
from tht.decisions import append_decision
from tht.cli.session_cmd import load_snapshot_or_exit, session_repository
sdir = session_dir(_cfg(), session)
cur = current_phase(sdir)
cfg = _cfg()
snapshot = load_snapshot_or_exit(cfg, session)
cur = current_phase(snapshot)
wf = load_workflow()
if cur > wf.max_phase:
typer.secho("Sessione già alla fase terminale.", fg=typer.colors.YELLOW)
raise typer.Exit(0)
if auto:
if not auto_advance_eligible(sdir):
problems = advance_problems(sdir, cur)
if not auto_advance_eligible(snapshot):
problems = advance_problems(snapshot, cur)
for p in problems:
typer.echo(p)
raise typer.Exit(6) # needs human confirmation (gate contract)
append_decision(sdir, type="phase_approved", subject=f"phase:{cur}")
session_repository(cfg).append_decisions(
session, [{"type": "phase_approved", "subject": f"phase:{cur}"}]
)
typer.echo(f"Fase {cur} ({wf.phase_name(cur)}) approvata → Fase {cur + 1}.")
@@ -113,16 +111,21 @@ def reopen_cmd(
phase: int = typer.Option(..., "--phase", help="Fase a cui tornare (1..fase corrente -1)."),
) -> None:
"""Torna a una fase precedente (persiste phase_reopened + teardown artefatti)."""
from tht.decisions import append_decision
from tht.teardown import teardown_to_phase
from tht.cli.session_cmd import load_snapshot_or_exit, session_repository
sdir = session_dir(_cfg(), session)
cur = current_phase(sdir)
cfg = _cfg()
snapshot = load_snapshot_or_exit(cfg, session)
cur = current_phase(snapshot)
if phase < 1 or phase >= cur:
typer.secho(f"Target non valido (fase corrente {cur}).", fg=typer.colors.RED, err=True)
raise typer.Exit(1)
report = teardown_to_phase(sdir, target_phase=phase)
append_decision(sdir, type="phase_reopened", subject=f"phase:{phase}")
from tht.teardown import teardown_snapshot
repository = session_repository(cfg)
report = teardown_snapshot(repository, snapshot, phase)
repository.append_decisions(
session, [{"type": "phase_reopened", "subject": f"phase:{phase}"}]
)
for f in report.deleted_files:
typer.echo(f" eliminato artefatto: {f}")
typer.echo(f"Tornati alla Fase {phase} ({load_workflow().phase_name(phase)}).")
@@ -133,13 +136,13 @@ def show_cmd(
session: str = typer.Option(..., "--session"),
) -> None:
"""Mostra stato, fase corrente e ultime decisioni della sessione."""
from tht.decisions import list_decisions
from tht.cli.session_cmd import load_snapshot_or_exit
sdir = session_dir(_cfg(), session)
cur = current_phase(sdir)
snapshot = load_snapshot_or_exit(_cfg(), session)
cur = current_phase(snapshot)
wf = load_workflow()
typer.echo(f"Fase corrente: {cur}/{wf.max_phase} ({wf.phase_name(min(cur, wf.max_phase))})")
decisions = list_decisions(sdir)
decisions = snapshot.decisions
if decisions:
typer.echo(f"Decisioni registrate: {len(decisions)}")
for d in decisions[-5:]:
+3 -4
View File
@@ -371,14 +371,13 @@ def pack_cmd(
md = "\n".join(md_lines) + "\n"
if session:
from tht.cli.session_cmd import load_session_or_exit, session_dir
from tht.cli.session_cmd import load_session_or_exit, session_repository
load_session_or_exit(cfg, session)
out = session_dir(cfg, session) / "retrieval_pack.md"
out.write_text(md)
session_repository(cfg).write_artifact(session, "retrieval_pack", md)
if not json_out:
typer.secho(
f"OK: retrieval pack scritto in {out} "
"OK: retrieval pack scritto "
f"({len(tables)} tabelle, {len(evidence)} evidence, {len(solved)} solved).",
fg=typer.colors.GREEN,
)
+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}")
+38 -20
View File
@@ -42,12 +42,14 @@ def require_action(cfg, action: str) -> None:
def promoted_tables_for(cfg, session_id: str | None) -> set[str] | None:
if session_id is None:
return None
linking_path = cfg.paths.sessions / session_id / "schema_linking.json"
if not linking_path.exists():
from tht.cli.session_cmd import load_snapshot_or_exit
raw = load_snapshot_or_exit(cfg, session_id).artifacts.get("schema_linking")
if raw is None:
return None
from tht.session.models import SchemaLinking
linking = SchemaLinking.model_validate(json.loads(linking_path.read_text()))
linking = SchemaLinking.model_validate(json.loads(raw))
return {
c.name for c in linking.candidates
if c.kind == "table" and c.decision == "promoted"
@@ -59,12 +61,14 @@ def promoted_tables_for(cfg, session_id: str | None) -> set[str] | None:
def promoted_columns_for(cfg, session_id: str | None) -> set[str] | None:
if session_id is None:
return None
linking_path = cfg.paths.sessions / session_id / "schema_linking.json"
if not linking_path.exists():
from tht.cli.session_cmd import load_snapshot_or_exit
raw = load_snapshot_or_exit(cfg, session_id).artifacts.get("schema_linking")
if raw is None:
return None
from tht.session.models import SchemaLinking
linking = SchemaLinking.model_validate(json.loads(linking_path.read_text()))
linking = SchemaLinking.model_validate(json.loads(raw))
return {
c.name for c in linking.candidates
if c.kind == "column" and c.decision == "promoted"
@@ -182,7 +186,7 @@ def preview_cmd(
"""Esecuzione controllata con LIMIT iniettato; aggregati mostrati per interi.
Se FILE è omesso e --session è fornito, il file viene risolto automaticamente
come <workspace>/sessions/<session>/sql_final.sql (tramite _session_sql_file).
dall'artefatto `sql_final` del repository della sessione.
"""
from tht.execute import ExecutionError
@@ -195,8 +199,7 @@ def preview_cmd(
fg=typer.colors.RED, err=True,
)
raise typer.Exit(code=1)
resolved = _session_sql_file(cfg, session)
sql = resolved.read_text()
sql = _session_sql(cfg, session)
else:
sql = _read_sql(file)
check = validate_or_exit(cfg, sql, session)
@@ -247,15 +250,32 @@ def preview_cmd(
typer.secho(f" warning: {w}", fg=typer.colors.YELLOW)
def _session_sql_file(cfg, session_id: str) -> Path:
from tht.cli.session_cmd import load_session_or_exit, session_dir
def _session_sql(cfg, session_id: str) -> str:
from tht.cli.session_cmd import load_snapshot_or_exit
load_session_or_exit(cfg, session_id)
sql_file = session_dir(cfg, session_id) / "sql_final.sql"
if not sql_file.exists():
typer.secho(f"ERRORE: {sql_file} non trovato.", fg=typer.colors.RED, err=True)
sql = load_snapshot_or_exit(cfg, session_id).artifacts.get("sql_final")
if sql is None:
typer.secho("ERRORE: sql_final.sql non trovato.", fg=typer.colors.RED, err=True)
raise typer.Exit(code=1)
return sql_file
return sql
@sql_app.command("set-final")
def set_final_cmd(
session: str = typer.Option(..., "--session"),
file: str = typer.Option(..., "--file", help="File SQL, oppure '-' per stdin."),
config: Path = CONFIG_OPT,
) -> None:
"""Persist clean final SQL through the configured session repository."""
import sys
from tht.cli.session_cmd import load_session_or_exit, session_repository
cfg = _load_config_or_exit(config)
load_session_or_exit(cfg, session)
sql = sys.stdin.read() if file == "-" else _read_sql(Path(file))
session_repository(cfg).write_artifact(session, "sql_final", sql)
typer.secho("OK: SQL finale salvato.", fg=typer.colors.GREEN)
@sql_app.command("save")
@@ -266,9 +286,8 @@ def save_cmd(
) -> None:
"""Salva una copia di sql_final.sql nel percorso indicato (su richiesta esplicita)."""
cfg = _load_config_or_exit(config)
sql_file = _session_sql_file(cfg, session)
dest.parent.mkdir(parents=True, exist_ok=True)
dest.write_text(sql_file.read_text())
dest.write_text(_session_sql(cfg, session))
typer.secho(f"OK: SQL salvato in {dest}", fg=typer.colors.GREEN)
@@ -286,8 +305,7 @@ def export_cmd(
cfg = _load_config_or_exit(config)
require_action(cfg, "export")
sql_file = _session_sql_file(cfg, session)
sql = sql_file.read_text()
sql = _session_sql(cfg, session)
validate_or_exit(cfg, sql, session)
try:
result = do_run(cfg, sql, limit=cfg.execution.max_export_rows)