Two divergent CalibrationMethod vocabularies coexist, and the removal-path saga is still advertised in capabilities

[jpapiez]

Verified against origin/development @ eb75c782dae40a6c5aa59c1d2288d60994adfa0d. Every claim below was read from that ref, not from a working tree.

Two types named CalibrationMethod, different vocabularies

1. Slice pipeline — src/slicer/Farm.Slicer.Module/Models/CalibrationMethod.cs (7 members, what actually slices):

FlowRatePass1, FlowRatePass2, TemperatureTower, FlowRateYoloRecommended, FlowRateYoloPerfectionist, MaximumVolumetricSpeed, PressureAdvanceTower

2. Saga catalogue — src/modules/Farm.Modules.Calibration/Services/Calibration/CalibrationMethodNames.cs (12 canonical wire names, snake_case):

temperature, flow_ratio_coarse, flow_ratio_fine, flow_ratio_high_range, pressure_advance_tower, pressure_advance_line, pressure_advance_pattern, flow_verification, retraction, max_volumetric_speed, shrinkage, final_verification

The sets are not a superset/subset relationship in either direction:

• In the saga, not sliceable: flow_ratio_high_range, pressure_advance_line, pressure_advance_pattern, flow_verification, retraction, shrinkage, final_verification
• Sliceable, no saga wire name: FlowRateYoloRecommended, FlowRateYoloPerfectionist

They are mutually exclusive by explicit design

src/slicer/Farm.Slicer.Module.Api/Controllers/Slicing/SliceJobController.cs rejects any request that combines the two:

Calibration mode is deliberately independent of, and mutually exclusive with, the unrelated printer/toolhead calibration-projects saga (issue #1940 epic). […] Reject the request outright rather than silently dropping one.

returning calibration_mode_conflicts_with_saga_ids when CalibrationProjectId, CalibrationAttemptId, or CalibrationOrchestrationId is present.

So a calibration project created through /api/calibration-projects can never be sliced through the calibration-mode path. That is intentional — but it is not discoverable by a client.

The problem: the removal-path surface is still advertised

CalibrationMethod.cs states the saga "is being removed by a separate epic" (#1940). Meanwhile CalibrationCapabilityService.cs:63 still advertises it:

["calibrationProjects"] = "/api/calibration-projects",

CalibrationProjectsController is fully implemented (9 project actions plus attempts and photos controllers), [Authorize]-gated, and covered by integration tests. Nothing about it signals "slated for deletion, and cannot slice."

Note: an earlier characterisation of this surface as "mounted but broken" was wrong — I checked the controller and it is alive and tested. The issue is divergence and signalling, not breakage.

Why it matters now

A thin client reading routes.calibrationProjects out of capabilities has no way to learn that:

1. the surface is on a removal path,
2. 7 of its 12 method names cannot be executed by any slicing path, and
3. using it is mutually exclusive with the calibration-mode slice pipeline that does work.

PrintFarmer Desktop already built against it and accumulated dead client code as a result — filed separately as a desktop issue.

Suggested resolution

Pick one and make it explicit:

• If the saga is being removed: advertise that. Mark the routes deprecated in capabilities (or stop advertising calibrationProjects), and give Path D: Delete printer-calibration layer, retain and reshape aggregate for server-orchestrated filament calibration #1940 a completion path.
• If it is staying: reconcile the two vocabularies, or document the split as an intentional, permanent boundary in docs/API.md with the executable/non-executable method sets named.

Either way, the two catalogues should have a single documented mapping (or an explicit "no mapping exists, by design" statement) so a client can tell which methods can actually produce a slice.

Verification notes

• Route inventory extracted by parsing [Route]/[Http*] attributes from the controller at the pinned ref.
• Method sets read from the two source files at the same ref.
• The "mutually exclusive" claim is quoted from the server's own source comment and its guard clause, not inferred.

[jpapiez]

Triage: assigned to squad:dallas (architecture/API-contract decision), type:chore, priority:p2.

Architecture gate: This issue requires a binding decision between two paths before any implementer touches it — (a) deprecate/remove the calibration-projects saga surface and give #1940 a completion path, or (b) keep it and reconcile the two CalibrationMethod vocabularies (or document the split as an intentional permanent boundary in docs/API.md). Dallas must pick one, record the decision (and, if (a), a concrete deprecation/removal plan; if (b), the method-name mapping or explicit "no mapping, by design" statement), and hand off child issues or a written sign-off — no implementation code.

Labeled status:needs-analysis. Dispatch to a Dallas session is deferred to the next round — all 5 implementation/analysis slots are currently occupied by in-flight calibration-guide work (#2137–#2142 series).

[github-actions]

📋 Assigned to 🏗️ Dallas (Lead)

Issue: #2151 — Two divergent CalibrationMethod vocabularies coexist, and the removal-path saga is still advertised in capabilities

🏗️ Dallas will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
🏗️ Dallas, work on issue #2151

[jpapiez]

Claimed by Ralph — dispatching a Dallas analysis session this round. No live session was found working this gate (checked list_sessions_and_chats); the prior comment's assignment note was label/automation only. Deliverable: the binding decision between the two CalibrationMethod vocabularies (deprecate/remove the removal-path saga vs. give it a completion path) plus any resulting child issues, recorded as a written sign-off on this issue — no implementation code.

[jpapiez]

Re-claimed by Ralph: the prior round's claim (18:34 UTC) recorded intent to dispatch a Dallas analysis session, but no such session exists in the live session list -- the dispatch did not actually land. Dispatching a fresh Dallas session now for the same deliverable: a binding decision between the two CalibrationMethod vocabularies (deprecate/remove the removal-path saga vs. give it a completion path), plus any resulting child issues, recorded as a written sign-off on this issue. No implementation code.

[jpapiez]

🏗️ Dallas — architecture decision (binding)

Decision: (b) the saga stays. Permanent split, documented boundary, no name mapping.

Why this is (b), not (a)

The issue's premise that the saga "is being removed by a separate epic" (quoting
CalibrationMethod.cs:9, referring to #1940) is stale. I re-read #1940 at its current
state: it was rewritten on 2026-08-24 and closed with the opposite outcome from what that
comment still says. Path D's decision was explicit:

Deleting the aggregate would have been a mistake... Filament calibration becomes a
server-orchestrated feature. PrintFarmer owns the run record, the step machine, the
method catalogue, measurement validation, and slice/print orchestration.

Only the printer-eligibility/hardware-attestation layer and the deterministic generator
subtree were deleted (D1-D3b, D5). The aggregate itself — CalibrationProject,
CalibrationAttempt, CalibrationOrchestration, CalibrationObservation, the catalogue —
was retained and reshaped, and D7 (saga service) and D8 (step sequences + measurement
validation) were subsequently built and closed. Since #1940 closed, the saga's own catalogue
(CalibrationMethodNames in Farm.Modules.Calibration) has grown from the 12 names cited
in this issue to 15 (Cornering, InputShaping, Vfa added by #2138/#2139/#2140,
report-only methods for motion-system diagnostics). That is not the trajectory of a surface on
a removal path. CalibrationProjectsController is alive, [Authorize]-gated, and tested, per
the issue's own finding.

So there is nothing to deprecate. calibrationProjects in CalibrationCapabilityService
correctly advertises a real, actively-developed feature — it should stay exactly as
advertised, with no deprecation signal added.

The two vocabularies are not reconcilable, and that's correct

I checked whether the saga's CalibrationMethod (15 kinds) could be mapped onto the slicer's
CalibrationMethod (now 8 members on current development — Retraction was added by
#2137 since the issue's pinned SHA, so even the "7" in the issue body is already one behind).
They can't be, because they are two different features that happen to share a name:

• /api/slice's CalibrationMethod (Farm.Slicer.Module.Models) is a one-shot, untracked,
  ad-hoc slice for a calibration test object. It is the only surface that actually produces a
  slice for a named calibration method.
• /api/calibration-projects's CalibrationMethod (Farm.Modules.Calibration) is a
  server-orchestrated, multi-step run (setup → print → measure → select) with its own
  per-method step sequence (D8) and measurement-range validation (D8). Its "print" step creates
  an ordinary, untagged ad-hoc slice job as an implementation detail — confirmed by grep:
  Farm.Modules.Calibration has zero references to
  Farm.Slicer.Module.Models.CalibrationMethod. The saga never sets
  CalibrationProjectId/CalibrationAttemptId/CalibrationOrchestrationId on the slice job it
  creates (that's exactly why SlicePrintBridgeController.IsCalibrationSlice() stays false and
  send-to-printer keeps working); it links back only via
  CalibrationAttemptEvent.SliceJobId.
• Mutual exclusivity is enforced today, correctly, by SliceJobController's
  calibration_mode_conflicts_with_saga_ids guard, and that guard should not be relaxed —
  it's protecting a real invariant between two independent features, not papering over a bug.

Given that, forcing a 1:1 mapping between a "one-shot ad-hoc slice" catalogue and a
"multi-step orchestrated run" catalogue would misrepresent the architecture. The explicit
"no mapping exists, by design" statement is the correct one, per the issue's own suggested
resolution for path (b).

What still needs to happen (follow-up, not done by me)

1. Document the CalibrationMethod vocabulary split as a permanent boundary in docs/API.md #2159 — add a documented section to docs/API.md (near "Calibration persistence and
   synchronization") laying out both catalogues side by side, stating plainly there is no name
   mapping and why, and quoting the SliceJobController mutual-exclusivity guard so a thin
   client (including PrintFarmer Desktop) can tell which surface actually produces a slice.
   Labelled squad:ash, type:chore, priority:p2.
2. Fix stale 'saga is being removed' XML doc comment on Farm.Slicer.Module.Models.CalibrationMethod #2160 — fix the now-incorrect CalibrationMethod.cs XML remark that still says the saga
   "is being removed by a separate epic." It should instead describe the two surfaces as
   permanently independent, cross-referencing Document the CalibrationMethod vocabulary split as a permanent boundary in docs/API.md #2159's doc section. Labelled squad:lambert,
   type:chore, priority:p3.

No changes to CalibrationCapabilityService, SliceJobController, or any runtime behavior are
required — the current advertising and the current guard clause are both already correct for
this decision. This is documentation-and-comment debt, not code debt.

Scope note

This session performed analysis only, per the dispatch contract: no implementation code was
written, no source files were modified, no PR was opened. Both follow-ups above are unimplemented
and filed for a separate session to pick up.

[jpapiez]

🏗️ Dallas — amended decision (supersedes my prior comment above)

The user has overridden the prior call: there must be a single canonical CalibrationMethod
vocabulary, because PrintFarmer Desktop needs to drive filament calibration (the saga) end to
end, including the slice it submits. My earlier "(b) permanent split, no mapping" answer is
withdrawn. Closed the two follow-ups that implemented that direction (#2159, #2160) and filed
their replacement.

This upgrades from "documentation debt" to "live bug"

Chasing this down further than my first pass: CalibrationOrchestrationSagaService .BuildSliceSubmissionBody posts calibration.method to POST /api/slice using the saga's
wire name (CalibrationMethodNames.ToName). SliceJobController parses that field against the
slicer's own, separate wire-name dictionary (CalibrationMethods.TryParse,
Farm.Slicer.Module.Models). The two agree only where they happen to coincide
(pressure_advance_tower, retraction, max_volumetric_speed, input_shaping, cornering,
vfa — 6 of 15). For the other 9 — including temperature vs. temperature_tower and
flow_ratio_coarse vs. flow_rate_pass_1 — the real HTTP call
(InternalApiSliceSubmissionGateway.SubmitAsync) 400s with unsupported_calibration_method,
which is correctly classified as a terminal failure. So the saga's slicing step fails
outright today for the majority of its own catalogued methods. No test catches this:
CalibrationOrchestrationSagaServiceTests uses an in-memory fake gateway that accepts any wire
name; there is no integration test through the real SliceJobController.

Amended decision

Single canonical type, owned by Farm.Slicer.Module.Models (CalibrationMethod enum +
CalibrationMethods wire-name/metadata class) — it is the layer that actually executes a slice,
and Farm.Modules.Calibration already carries a ProjectReference to it, so unification needs
no new dependency, only deleting the saga's duplicate CalibrationMethod/
CalibrationMethodNames. Extend the slicer's catalogue with the saga-only methods it's missing
(PressureAdvanceLine, PressureAdvancePattern, FlowVerification, Shrinkage,
FinalVerification), using its existing IsSlicerSupported opt-out mechanism to mark whichever
have no executable implementation yet (already the pattern used for the PA Line/Pattern
licensing hold). Audit FlowRatioHighRange for retirement in favor of the newer
FlowRateYoloRecommended/FlowRateYoloPerfectionist methods, and expose those two to the saga
(currently slicer-only). Full mapping table and step list in the filed issue.

Filed

• Unify the two CalibrationMethod vocabularies into one canonical type owned by the slicer module #2161 (squad:lambert, type:bug, priority:p1) — the unification work, including the
  wire-name mapping table, the persisted-data compatibility audit, and an integration test to
  close the coverage gap that let this ship.
• A docs/API.md update (squad:ash) will follow once the unified type's shape is settled —
  intentionally not filed yet, to avoid documenting a vocabulary before it exists.
• Document the CalibrationMethod vocabulary split as a permanent boundary in docs/API.md #2159, Fix stale 'saga is being removed' XML doc comment on Farm.Slicer.Module.Models.CalibrationMethod #2160 closed as superseded.

Scope note

Still analysis only this session: no source files were modified, no PR opened. #2161 is
unimplemented and filed for a separate session.