refactor(BA-7722): mark unsent request fields with pydantic MISSING

[HyeockJinKim]

Problem

Update-request DTOs mark an unsent field with a hand-rolled Sentinel enum
(common/api_handlers.py). It serializes as the integer 1, so:

• The published spec advertises the placeholder. docs/manager/rest-reference/openapi.json
  carries Sentinel as {"type":"integer","enum":[1]}, referenced by 78 fields across 25
  Update*Input schemas, each with "default": 1.
• The value reaches the wire whenever a caller sets the sentinel explicitly, which the v2 CLI
  does (client/cli/v2/object_storage/commands.py). The server happens to decode 1 back
  into the enum, so this has gone unnoticed.

Change

UNSET is pydantic_core.MISSING. pydantic omits a field holding it from serialization and
from the JSON schema, so an absent field puts nothing on the wire.

                        before                    after
absent            {"time_window": 1}              {}
null              {}  (dropped, see below)        {"time_window": null}
value             {"time_window": "30m"}          {"time_window": "30m"}

JSON schema       anyOf[string, $ref:Sentinel, null], default: 1
                  anyOf[string, null]

Unset aliases typing_extensions.Sentinel rather than the exact MISSING type: mypy merged
PEP 661 support (python/mypy#21647, 2026-08-07) but has not released it. MISSING is a real
instance of that class, so the annotation is wider than needed but never false, and mypy accepts
it with no suppressions. When mypy ships PEP 661, unset.py and the two from_unset bodies
change and nothing else does — common/tristate/KNOWLEDGE.md records the steps.

Conversion

TriState.from_unset / OptionalState.from_unset map the three states onto the target column.
What null means is decided by the column, and the constructor the adapter picks states it.

Column	Constructor	null	unset
nullable	TriState.from_unset	clears it	leaves it
non-nullable	OptionalState.from_unset	leaves it	leaves it

OptionalState.and_optional / and_tri read a nested request model. Nested access is on
OptionalState only: a nested model is a wire-side grouping with no column behind it, so a null
parent must not spread a nullify into its children — a non-nullable child would violate its
constraint and a nullable one would be erased unasked.

The adapter loses its hand-rolled three-way ternaries:

options = OptionalState[ModifyQueryDefinitionOptionsRequest].from_unset(request.options)
return PrometheusQueryPresetUpdater(
    preset_id=PrometheusQueryPresetID(preset_id),
    name=OptionalState.from_unset(request.name),
    time_window=TriState.from_unset(request.time_window),
    filter_labels=options.and_optional(lambda o: o.filter_labels),
    ...
)

Scope

Foundation plus one reference entity (prometheus_query_preset). common/dto/AGENTS.md gains
the create-vs-update schema rules this follows.

Follow-ups, not in this PR:

• Migrate the remaining 25 DTO modules, then delete the old Sentinel.
• Drop exclude_none=True from client/v2/base_client.py, which currently discards an explicit
  null and so leaves a client unable to express NULLIFY at all. It must land after every field is
  migrated — removing it earlier would put the integer 1 on the wire more often, not less.

Verification

• pants check --changed-since=origin/main --changed-dependents=transitive — 7152 source files,
  no issues. This covers the pydantic 2.11.10 → 2.13.5 bump across the repo.
• pants lint clean, including the new /tristate/** visibility rule.
• Exercised against the exported venv: the three states resolve as tabled above, the nested
  reads resolve, CreateQueryDefinitionRequest is untouched, and the time_window field
  validator still rejects a bad duration.
• pants test left to CI per the submit workflow.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UHHR2fFGQNB3NssxHeRKBz

[Copilot]

🟡 Changes recommended

The new serialization and tri-state conversion contracts lack automated regression coverage.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Replaces the legacy update-field sentinel with Pydantic MISSING, using Prometheus query presets as the reference migration.

Changes:

• Adds reusable unset and tri-state conversion helpers.
• Migrates Prometheus update DTOs and adapter logic.
• Upgrades Pydantic and regenerates lockfiles.

File summaries

File	Description
tools/mypy.lock.metadata	Updates Pydantic requirement metadata.
tools/mypy.lock	Refreshes mypy tool dependencies.
tools/mypy-requirements.txt	Requires Pydantic 2.13.5.
src/ai/backend/manager/types.py	Adds unset and nested-state conversions.
src/ai/backend/manager/api/rest/prometheus_query_preset/adapter.py	Uses the new conversion helpers.
src/ai/backend/common/tristate/unset.py	Defines UNSET and Unset.
src/ai/backend/common/tristate/KNOWLEDGE.md	Documents sentinel rationale and migration.
src/ai/backend/common/tristate/AGENTS.md	Adds tri-state usage guardrails.
src/ai/backend/common/tristate/__init__.py	Initializes the package.
src/ai/backend/common/dto/manager/prometheus_query_preset/request.py	Migrates update fields to UNSET.
src/ai/backend/common/dto/AGENTS.md	Documents create/update schema rules.
src/ai/backend/common/BUILD	Adds tristate dependency boundaries.
requirements.txt	Upgrades runtime Pydantic.
python.lock.metadata	Updates lock requirement metadata.
python.lock	Regenerates runtime dependencies.
changes/14312.enhance.md	Adds the changelog entry.

Review details

• Files reviewed: 13/17 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.