Run 1 Bug Fixes — Byproducts

Summary

Three customer-reported defects in the print pipeline were resolved with surgical changes in operations (kanban module) and arda-frontend-app. The most consequential side effect was establishing the printEventRoute() route helper, which has since become the default pattern for any future event endpoint that returns a print-lifecycle state change.

Learnings

The notes fallback chain in KanbanCardPrinter was historically permissive — it walked KanbanCard.notes → Item.cardNotesDefault → Item.notes so that, in early single-tenant deployments, “something” always rendered. That logic outlived its usefulness once Item.notes started carrying order-history text. The fix is one expression but the diagnosis required reading two years of git blame.
KanbanCardPrintEventType was not a closed set. The enum already contained values (DEPRECATE, RETIRE, DESTROY) that the documentation never mentioned. Adding UNMARK was easy; the harder part was deciding which of those existing values should also map through _resultPrintState(). We left the existing mappings untouched to preserve current behaviour.
The PlantUML class diagram for KanbanCardPrintStatus was stale by two prior projects — DEPRECATED and UNKNOWN were already in code but missing from the diagram. Caught while updating the doc, fixed inline. See implementation-log § T-1.6.
The frontend’s print dropdown was already conditional on status, so adding an Unmark as printed item gated on PRINTED was a one-line predicate change rather than a new state machine in the UI.

Alternatives considered

Reusing eventRoute() with a generic type parameter for the unmark endpoint — rejected because the operational and print state-change payloads have different shapes and the generalisation would have rippled through every existing caller. See implementation-log § T-1.4.
Returning null from the notes field when card notes are absent — rejected because the Documint template treats absent fields differently from empty strings (the absent case renders the layout placeholder). Empty string is the correct contract per SAC::PRINT::FR-0016.
Unmark as a PUT /kanban-card/{eId}/print-status resource update — rejected during planning in favour of an event-based endpoint, to stay consistent with how every other print transition is recorded (PRINT, REPRINT, LOST, etc.) and to keep the print-event audit trail complete. No PD- decision was logged because the choice was made during plan authoring, not during scoping rounds.
A 410-style error response for UNMARK on cards that are not PRINTED — rejected; current behaviour is a no-op that returns the unchanged card, which matches how LOST and similar event types behave in the existing code.

Suggestions / follow-ups

Add a printEventRoute() reference to the kanban module knowledge base (or to current-system/architecture/) so future agents discover it without grepping. Not done in scope.
Audit other PlantUML class diagrams in current-system/functional/ for the same staleness as the KanbanCardPrintStatus diagram. Not done in scope.
Frontend: surface a tooltip explaining what unmark does. Currently the dropdown item is unlabelled beyond the verb. Not requested by any ticket.

Skipped

B-2 fix — none required. The investigation confirmed ItemPrinter already maps Item.notes to the Documint notes field correctly. Logged as a verification result rather than a code change.
Frontend UI for editing KanbanCard.notes — explicitly out of scope per decision-log § DQ-005. The bug fix only ensures the right field is sent; editing remains backend-only.
Unit tests for UNMARK from non-PRINTED states — T-P1-009 was authored with “behavior defined (no-op or error)” as the spec; the test landed asserting no-op. Edge cases left to future regression coverage.

Specification delta (post)

No deviations from phase-1-bug-fixes/specification.md. The shipped behaviour matches every requirement (REQ-P1-001 through REQ-P1-007). The only addition not in the original specification is the printEventRoute() helper, which is an internal refactoring artefact and does not change the contract.