sqbyl 0.1.0__tar.gz

sqbyl-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Claude Code / local agent workspace (designer-dev only, not part of the project)
+.claude/
+
+# sqbyl local state: runs, traces, usage, caches (per design spec §4)
+.sqbyl/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# uv / virtualenvs
+.venv/
+venv/
+env/
+.python-version
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.coverage
+htmlcov/
+.tox/
+
+# Environment / secrets (never commit ANTHROPIC_API_KEY or DATABASE_URL)
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Private planning doc — kept local, not published
+sqbyl-enhancements.md

sqbyl-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: sqbyl
+Version: 0.1.0
+Summary: The full sqbyl dev toolkit: introspect, profile, annotate, synth, eval, Coach, judges, console, optimizer, release builder.
+Project-URL: Homepage, https://github.com/jackwerner/sqbyl
+Project-URL: Repository, https://github.com/jackwerner/sqbyl
+Project-URL: Issues, https://github.com/jackwerner/sqbyl/issues
+Author: Jack Werner
+License-Expression: MIT
+Keywords: agent,anthropic,claude,evaluation,llm,sql,text-to-sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.139.0
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml>=6
+Requires-Dist: sqbyl-runtime==0.1.0
+Requires-Dist: uvicorn>=0.50.2
+Provides-Extra: anthropic
+Requires-Dist: sqbyl-runtime[anthropic]==0.1.0; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: sqbyl-runtime[openai]==0.1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# sqbyl
+
+The full text-to-SQL dev toolkit. See the [repository root README](../../README.md)
+for the product overview, and `docs/sqbyl-design-spec.md` /
+`docs/sqbyl-implementation-plan.md` for the design and build sequence.
+
+This package contains the dev machinery — introspect, profile, annotate, synth,
+the eval harness, the Coach, LLM judges, the review console, the orchestrator,
+the optimizer, and the release builder. It depends on `sqbyl-runtime`
+(never the reverse).

sqbyl-0.1.0/README.md

@@ -0,0 +1,10 @@
+# sqbyl
+
+The full text-to-SQL dev toolkit. See the [repository root README](../../README.md)
+for the product overview, and `docs/sqbyl-design-spec.md` /
+`docs/sqbyl-implementation-plan.md` for the design and build sequence.
+
+This package contains the dev machinery — introspect, profile, annotate, synth,
+the eval harness, the Coach, LLM judges, the review console, the orchestrator,
+the optimizer, and the release builder. It depends on `sqbyl-runtime`
+(never the reverse).

sqbyl-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "sqbyl"
+version = "0.1.0"
+description = "The full sqbyl dev toolkit: introspect, profile, annotate, synth, eval, Coach, judges, console, optimizer, release builder."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Jack Werner" }]
+keywords = ["text-to-sql", "sql", "llm", "claude", "anthropic", "agent", "evaluation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    # Lockstep: the toolkit and runtime are cut together, so pin the exact runtime
+    # this toolkit was built and tested against.
+    "sqbyl-runtime==0.1.0",
+    "pydantic>=2.7,<3",
+    "pyyaml>=6",
+    # The review console (spec §6.5) is a local FastAPI app with a bundled UI. It lives
+    # in the dev toolkit only — the shipped `sqbyl-runtime` never carries a web stack.
+    "fastapi>=0.139.0",
+    "uvicorn>=0.50.2",
+]
+
+[project.optional-dependencies]
+# Provider SDKs are optional and provider-neutral (see sqbyl-runtime): pick one and install
+# its extra alongside the toolkit, e.g. `pip install sqbyl[openai]`.
+anthropic = ["sqbyl-runtime[anthropic]==0.1.0"]
+openai = ["sqbyl-runtime[openai]==0.1.0"]
+
+[project.scripts]
+sqbyl = "sqbyl.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jackwerner/sqbyl"
+Repository = "https://github.com/jackwerner/sqbyl"
+Issues = "https://github.com/jackwerner/sqbyl/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+sqbyl-runtime = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sqbyl"]

sqbyl-0.1.0/src/sqbyl/__init__.py

@@ -0,0 +1,7 @@
+"""sqbyl — the full text-to-SQL dev toolkit.
+
+Build, evaluate, and iterate on a Claude-powered text-to-SQL agent over your own
+database. Depends on ``sqbyl_runtime`` (never the reverse).
+"""
+
+__version__ = "0.0.0"

sqbyl-0.1.0/src/sqbyl/annotate.py

@@ -0,0 +1,150 @@
+"""The annotator — ``sqbyl annotate`` (spec §3 #1, plan 2.3).
+
+Claude drafts table/column **descriptions and synonyms**, grounded in the Phase 1.3
+**profile** (ranges, distinct counts, sample values) rather than guessing from
+names — it can see that ``amount_cents`` spans 127..310229 with no nulls and infer
+the cents unit, that ``status`` has three values, that ``created_at`` covers
+2019→today. Each annotation carries a **confidence** the attention router consumes
+later (Phase 6).
+
+This is dev-only authoring, so it lives in ``sqbyl`` and depends on the runtime's
+LLM seam. It is per-table (parallel fan-out is Phase 6; here it is sequential). As
+a paid command it is metered through the cost stub from day one (invariant 5).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from sqbyl_runtime.llm.base import LLMClient, LLMRequest, LLMResponse, Message
+from sqbyl_runtime.models import Column, Profile, TableSemantics
+from sqbyl_runtime.state.traces import TraceWriter, llm_call_span, new_trace_id
+
+_SYSTEM = (
+    "You are a data analyst documenting a SQL table for a text-to-SQL agent. "
+    "Write concise, factual descriptions grounded in the COLUMN PROFILE STATISTICS "
+    "provided (ranges, distinct counts, sample values) — infer units and meaning from "
+    "the data, never invent facts you can't support. Add a few natural-language "
+    "synonyms a user might say. Give each description a confidence in [0,1]: high when "
+    "the data makes the meaning obvious, low when the column is cryptic."
+)
+
+
+class ColumnAnnotation(BaseModel):
+    """A drafted description for one column, with the router's confidence signal."""
+
+    name: str
+    description: str = Field(description="One factual sentence, grounded in the profile.")
+    synonyms: list[str] = Field(default_factory=list)
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class TableAnnotation(BaseModel):
+    """A drafted description for a table and its columns."""
+
+    description: str = Field(description="What one row represents, grounded in the data.")
+    synonyms: list[str] = Field(default_factory=list)
+    confidence: float = Field(ge=0.0, le=1.0)
+    columns: list[ColumnAnnotation] = Field(default_factory=list)
+
+
+def annotate_table(
+    llm: LLMClient,
+    table: TableSemantics,
+    *,
+    model: str,
+    trace_writer: TraceWriter | None = None,
+    trace_id: str | None = None,
+    parent_span_id: str | None = None,
+) -> tuple[TableAnnotation, LLMResponse]:
+    """Draft a description/synonyms for a table and its columns, grounded in the profile.
+
+    Like the agent pipeline, this builds the request explicitly so the token-spending
+    call can be written as an OTel-GenAI span when a ``trace_writer`` is given
+    (invariant 7). ``max_tokens`` matches the seam's structured default so existing
+    cassettes stay valid.
+    """
+    request = LLMRequest(
+        model=model,
+        messages=[Message(role="user", content=_render_for_annotation(table))],
+        system=_SYSTEM,
+        response_schema=TableAnnotation.model_json_schema(),
+        max_tokens=4096,
+        temperature=0.0,
+        cache_system=True,
+    )
+    response = llm.complete(request)
+    if trace_writer is not None:
+        trace_writer.write(
+            llm_call_span(
+                request,
+                response,
+                operation="chat",
+                name=f"annotate {table.table}",
+                trace_id=trace_id or new_trace_id(),
+                parent_span_id=parent_span_id,
+            )
+        )
+    return response.parse(TableAnnotation), response
+
+
+def apply_annotation(table: TableSemantics, annotation: TableAnnotation) -> TableSemantics:
+    """Merge drafted descriptions/synonyms onto a table, preserving its profile.
+
+    Only ``description`` and ``synonyms`` are written (the durable authoring fields);
+    profiling stays as profiled. Columns are matched by name; unknown names are ignored.
+    """
+    by_name = {c.name: c for c in annotation.columns}
+    columns = [
+        col.model_copy(
+            update={
+                "description": by_name[col.name].description,
+                "synonyms": by_name[col.name].synonyms,
+            }
+        )
+        if col.name in by_name
+        else col
+        for col in table.columns
+    ]
+    return table.model_copy(
+        update={
+            "description": annotation.description,
+            "synonyms": annotation.synonyms,
+            "columns": columns,
+        }
+    )
+
+
+def _render_for_annotation(table: TableSemantics) -> str:
+    """Expose the raw profile so the model grounds its descriptions in data."""
+    lines = [f"Table: {table.table}", "", "Columns (name, type, profile):"]
+    for col in table.columns:
+        lines.append(f"- {col.name} ({col.type}){_profile_summary(col)}")
+    if table.joins:
+        lines.append("")
+        lines.append("Joins:")
+        for join in table.joins:
+            lines.append(f"- {join.type} -> {join.to} ON {join.on}")
+    lines.append("")
+    lines.append(
+        "Draft a table description (what one row is) plus a description and synonyms for "
+        "every column, each with a confidence. Return them all."
+    )
+    return "\n".join(lines)
+
+
+def _profile_summary(col: Column) -> str:
+    if col.sample_values:
+        return f"  values: {', '.join(str(v) for v in col.sample_values)}"
+    if isinstance(col.profile, Profile):
+        p = col.profile
+        bits = []
+        if p.nulls is not None:
+            bits.append(f"nulls={p.nulls}")
+        if p.distinct is not None:
+            bits.append(f"distinct={p.distinct}")
+        if p.min is not None and p.max is not None:
+            bits.append(f"range={p.min}..{p.max}")
+        if bits:
+            return "  " + ", ".join(bits)
+    return ""

sqbyl-0.1.0/src/sqbyl/attention.py

@@ -0,0 +1,209 @@
+"""The attention router + readiness scorer (spec §3 #9, §5.5, plan 6.2).
+
+Given a bag of scored :class:`Decision`s, this:
+
+1. **auto-applies** the high-confidence, machine-decidable ones (confidence ≥
+   :data:`AUTO_APPLY_THRESHOLD` and not ``requires_human``) — the console shows them
+   collapsed/done with one-click undo;
+2. **surfaces the rest** into a single queue **sorted by leverage** (highest first — the
+   fewest decisions that move readiness the most);
+3. computes the **readiness signal**: current accuracy with its interval, and how many queued
+   decisions it takes to reach the project's target.
+
+The adapters turn the artifacts sqbyl already produces — a Coach report, an eval's review
+pile, an orchestrator run's failed units — into decisions, so the queue is populated from
+real work rather than hand-built. Dev-only review machinery, so it lives in ``sqbyl``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sqbyl.models.attention import AttentionQueue, Decision, DecisionKind, ReadinessSignal
+from sqbyl.stats import wilson_interval
+
+if TYPE_CHECKING:
+    from sqbyl.models.coach import CoachReport
+    from sqbyl.models.runs import QuestionResult, ScoredRun
+    from sqbyl.orchestrator import OrchestratorResult
+
+# Default confidence at/above which a machine decision is applied without asking (one-click
+# undo). An unvalidated heuristic, like the judge's DEFAULT_MIN_CONFIDENCE — still needs
+# re-deriving against human accept/reject rates once the console logs them. Overridable per
+# project via ``DefaultsConfig.auto_apply_threshold`` (set 1.0 to require a human on all).
+AUTO_APPLY_THRESHOLD = 0.85
+
+
+def _leverage_sort_key(d: Decision) -> tuple[float, float, str]:
+    """Highest leverage first; ties broken by *lower* confidence (more ambiguous → look sooner),
+    then id for a stable order."""
+    return (-d.leverage, d.confidence, d.id)
+
+
+def route(
+    decisions: list[Decision],
+    *,
+    n_correct: int,
+    n: int,
+    target: float,
+    auto_apply_threshold: float = AUTO_APPLY_THRESHOLD,
+) -> AttentionQueue:
+    """Split ``decisions`` into auto-applied vs. a leverage-sorted queue + a readiness signal.
+
+    ``n_correct``/``n`` are the eval's exact deterministic counts (passed as integers, not a
+    reconstructed float, so the interval is honest); ``target`` is the shippable bar from the
+    manifest; ``auto_apply_threshold`` gates unsighted apply (the manifest's
+    ``auto_apply_threshold`` knob — 1.0 requires a human on everything).
+    """
+
+    def auto(d: Decision) -> bool:
+        return d.auto_applyable and d.confidence >= auto_apply_threshold
+
+    auto_applied = [d for d in decisions if auto(d)]
+    queue = sorted((d for d in decisions if not auto(d)), key=_leverage_sort_key)
+    readiness = _readiness(queue, n_correct=n_correct, n=n, target=target)
+    return AttentionQueue(auto_applied=auto_applied, queue=queue, readiness=readiness)
+
+
+def _readiness(queue: list[Decision], *, n_correct: int, n: int, target: float) -> ReadinessSignal:
+    """Greedy 'fewest decisions to target': walk the queue high-leverage first, accumulating
+    *de-duplicated* estimated leverage until it clears ``target``.
+
+    Leverage is summed across picked decisions, but two decisions that both claim the same
+    question can't fix it twice — so a decision's contribution is capped by the fraction of the
+    eval its *newly-covered* questions represent (union, not naive sum). The result is a
+    projection built on unverified estimates; :class:`ReadinessSignal` labels it as such."""
+    accuracy = n_correct / n if n else 0.0
+    low, high = wilson_interval(n_correct, n)
+    base = ReadinessSignal(
+        accuracy=accuracy, target=target, n=n, accuracy_low=low, accuracy_high=high
+    )
+
+    if accuracy >= target:
+        base.decisions_to_target = 0
+        base.projected = accuracy
+        base.reachable = True
+        return base
+
+    projected = accuracy
+    count = 0
+    covered: set[str] = set()  # questions already claimed — never credited twice
+    for d in queue:
+        if projected >= target:
+            break
+        if d.leverage <= 0.0:
+            # A blocked/judge card (leverage 0) is surfaced but never closes the gap —
+            # it's absence-of-result, not a gain (the 6.1 contract on failed units).
+            continue
+        gain = d.leverage
+        if d.affected_questions:
+            new_q = [q for q in d.affected_questions if q not in covered]
+            if not new_q:
+                continue  # fully overlaps an earlier pick — contributes nothing new
+            gain = min(d.leverage, len(new_q) / n) if n else 0.0
+            covered.update(d.affected_questions)
+        projected = min(1.0, projected + gain)
+        count += 1
+
+    base.decisions_to_target = count
+    base.projected = projected
+    base.reachable = projected >= target
+    return base
+
+
+# ── adapters: real artifacts → decisions ────────────────────────────────────────────────
+
+_LAYER_TO_KIND: dict[str, DecisionKind] = {
+    "example": DecisionKind.example,
+    "measure": DecisionKind.measure,
+    "synonym": DecisionKind.synonym,
+    "named_filter": DecisionKind.named_filter,
+    "column_description": DecisionKind.column_description,
+    "table_description": DecisionKind.table_description,
+    "instruction": DecisionKind.instruction,
+    "trusted_asset": DecisionKind.example,
+}
+
+
+def decisions_from_coach_report(report: CoachReport, *, total: int) -> list[Decision]:
+    """Turn Coach proposals into decisions. Leverage is ``predicted_fixes / total`` (accuracy
+    points), an estimate; prose and memorization-risk proposals are forced to require a human
+    (they never auto-apply), consistent with the Coach's own ranking (spec §8)."""
+    decisions: list[Decision] = []
+    for p in report.proposals:
+        leverage = (p.predicted_fixes / total) if total else 0.0
+        # Prose (the last-resort layer) and single-question memorization-risk examples never
+        # auto-apply — the schema owns "is this prose" via CoachProposal.is_prose (invariant 2).
+        requires_human = p.is_prose or p.memorization_risk
+        decisions.append(
+            Decision(
+                id=f"coach:{p.id}",
+                kind=_LAYER_TO_KIND.get(p.layer.value, DecisionKind.instruction),
+                title=p.title,
+                detail=p.root_cause,
+                suggestion=p.render_diff(),
+                confidence=p.confidence,
+                leverage=leverage,
+                affected_questions=list(p.question_ids),
+                source=f"coach:{p.id}",
+                target_file=p.target_file,
+                requires_human=requires_human,
+            )
+        )
+    return decisions
+
+
+def decisions_from_review_pile(run: ScoredRun) -> list[Decision]:
+    """Turn an eval's ``manual_review`` rows into judge-review cards — always the human's call.
+
+    These never auto-apply (``requires_human``) and carry no leverage: a review ruling resolves
+    a *reported* number, it doesn't teach the agent, so it must not inflate readiness."""
+    decisions: list[Decision] = []
+    for r in run.results:
+        if not r.needs_review:
+            continue
+        suggestion = r.judge_suggestion.value if r.judge_suggestion is not None else ""
+        confidence = _least_judge_confidence(r)
+        decisions.append(
+            Decision(
+                id=f"judge:{run.run_id}:{r.id}",
+                kind=DecisionKind.judge_review,
+                title=f"Review {r.id}",
+                detail=r.question,
+                suggestion=suggestion,
+                confidence=confidence,
+                leverage=0.0,
+                affected_questions=[r.id],
+                source=f"judge:{r.id}",
+                requires_human=True,
+            )
+        )
+    return decisions
+
+
+def decisions_from_outcomes(result: OrchestratorResult[object]) -> list[Decision]:
+    """Turn orchestrator outcomes into cards: a **failed** unit becomes a blocked card the
+    human must retry/handle (spec §3 #8) — never auto-applied and carrying no leverage, so it
+    surfaces without pretending to be a weak result. Skipped (budget) units aren't cards."""
+    decisions: list[Decision] = []
+    for o in result.failures:
+        decisions.append(
+            Decision(
+                id=f"blocked:{o.unit.id}",
+                kind=DecisionKind.blocked,
+                title=o.unit.label or o.unit.id,
+                detail=o.error or "unit failed",
+                confidence=0.0,
+                leverage=0.0,
+                source=o.unit.id,
+                requires_human=True,
+            )
+        )
+    return decisions
+
+
+def _least_judge_confidence(result: QuestionResult) -> float:
+    """The least-sure judge on a row — a rough 'how ambiguous is this' signal for ordering."""
+    if not result.judge_verdicts:
+        return 0.0
+    return min(v.confidence for v in result.judge_verdicts)

sqbyl-0.1.0/src/sqbyl/calibration_io.py

@@ -0,0 +1,87 @@
+"""The judge calibration set — ``.sqbyl/calibration.jsonl`` (spec §7, plan 5.2).
+
+Every time a human confirms or overrides a judged row in the review console, we append a
+:class:`CalibrationRecord` here: what the judge suggested, what the human decided, and
+whether they agreed. Accumulated, these give the live **judge↔human agreement** score —
+the number that tells a curator how far to trust the judge on rows nobody has reviewed
+(standard inter-rater agreement between the LLM judge and human reviewers).
+
+Append-only JSONL: the calibration set is an audit trail, not mutable state, so a review
+is never silently rewritten. This is dev-loop data (it only exists because a human is
+reviewing benchmarks), so the path is derived here rather than in the runtime layout.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqbyl.models import CalibrationRecord, JudgeAgreement
+from sqbyl.project import Project
+from sqbyl_runtime.state.layout import SqbylPaths
+
+
+def calibration_path(project: Project) -> Path:
+    return SqbylPaths(project.root).root / "calibration.jsonl"
+
+
+def load_calibration(project: Project) -> list[CalibrationRecord]:
+    """Every recorded review, oldest first. Empty when nothing has been reviewed yet."""
+    path = calibration_path(project)
+    if not path.exists():
+        return []
+    records = [
+        CalibrationRecord.model_validate_json(line)
+        for line in path.read_text().splitlines()
+        if line.strip()
+    ]
+    return records
+
+
+def append_calibration(project: Project, record: CalibrationRecord) -> None:
+    """Append one review to the calibration trail (creates the file/dir on first write)."""
+    path = calibration_path(project)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a") as fh:
+        fh.write(record.model_dump_json() + "\n")
+
+
+def _latest_per_row(records: list[CalibrationRecord]) -> list[CalibrationRecord]:
+    """Keep only the last ruling for each ``(run_id, question_id)``, in first-seen order.
+
+    A human who re-opens and re-resolves a row appends a fresh record (the JSONL stays an
+    append-only audit trail), but only their latest call should count — otherwise a repeated
+    click would double-count in the agreement rate and duplicate a few-shot anchor."""
+    latest: dict[tuple[str, str], CalibrationRecord] = {}
+    for r in records:
+        latest[(r.run_id, r.question_id)] = r  # later write wins
+    return list(latest.values())
+
+
+def judge_agreement(project: Project, *, split: str | None = None) -> JudgeAgreement:
+    """The live judge↔human agreement, deduped to each row's latest ruling (spec §7).
+
+    Optionally scoped to one split. Selection-biased by construction — see
+    :class:`~sqbyl.models.JudgeAgreement`."""
+    records = load_calibration(project)
+    if split is not None:
+        records = [r for r in records if r.split == split]
+    return JudgeAgreement.from_records(_latest_per_row(records))
+
+
+# How many prior human rulings to replay to the judge as few-shot examples. Small: a few
+# concrete anchors coach without ballooning every judge prompt (and cost).
+FEW_SHOT_LIMIT = 3
+
+
+def few_shot_examples(
+    project: Project, *, split: str, limit: int = FEW_SHOT_LIMIT
+) -> list[CalibrationRecord]:
+    """The most recent human rulings **for one split**, to coach that split's judge (spec §7).
+
+    Split-scoped so dev rulings never coach the held-out test judge (invariant 3), and deduped
+    to each row's latest ruling. Recency, not cherry-picking: the last ``limit`` reviews (both
+    agreements and overrides) so the judge sees honest ground-truth anchors, not a
+    disagreement-biased sample. Empty until a human has reviewed something on this split — so
+    an un-reviewed project's judge prompts, and the CI cassettes, are unchanged."""
+    records = [r for r in load_calibration(project) if r.split == split]
+    return _latest_per_row(records)[-limit:]

sqbyl-0.1.0/src/sqbyl/candidates_io.py

@@ -0,0 +1,66 @@
+"""The synth → review candidate queue on disk (``.sqbyl/candidates.yaml``).
+
+``sqbyl synth`` writes survivors here; the review console reads them, shows the executed
+evidence, and on accept promotes a candidate into ``benchmarks/dev.yaml`` (via
+:func:`sqbyl.eval.benchmarks_io.append_to_dev_set`) and marks it accepted. The queue is
+``.sqbyl/`` scratch state — regenerable, gitignored — never a source of truth for the
+golden set itself.
+
+This module is deliberately **dev-safe**: it reads and writes only the candidate queue and
+never touches ``test.yaml`` (invariant 3).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqbyl.models import Candidate
+from sqbyl.project import Project
+from sqbyl.yamlio import dump_yaml, load_yaml
+from sqbyl_runtime.state.layout import SqbylPaths
+
+
+def candidates_path(project: Project) -> Path:
+    return SqbylPaths(project.root).root / "candidates.yaml"
+
+
+def load_candidates(project: Project) -> list[Candidate]:
+    path = candidates_path(project)
+    if not path.exists():
+        return []
+    raw = load_yaml(path.read_text()) or []
+    return [Candidate.model_validate(item) for item in raw]
+
+
+def save_candidates(project: Project, candidates: list[Candidate]) -> Path:
+    """Overwrite the queue with ``candidates`` (JSON-native scalars for portability)."""
+    path = candidates_path(project)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = [c.model_dump(mode="json") for c in candidates]
+    path.write_text(dump_yaml(data))
+    return path
+
+
+def add_candidates(project: Project, new: list[Candidate]) -> list[Candidate]:
+    """Append newly synthesized candidates to the queue, replacing any with the same id.
+
+    Returns the full queue after the merge. New candidates win on an id collision so a
+    re-synth refreshes stale pending items rather than duplicating them.
+    """
+    by_id = {c.id: c for c in load_candidates(project)}
+    for candidate in new:
+        by_id[candidate.id] = candidate
+    merged = list(by_id.values())
+    save_candidates(project, merged)
+    return merged
+
+
+def get_candidate(project: Project, candidate_id: str) -> Candidate | None:
+    return next((c for c in load_candidates(project) if c.id == candidate_id), None)
+
+
+def update_candidate(project: Project, candidate: Candidate) -> None:
+    """Persist an updated candidate (matched by id) back into the queue."""
+    candidates = load_candidates(project)
+    replaced = [candidate if c.id == candidate.id else c for c in candidates]
+    save_candidates(project, replaced)