Tracking: Update/Edit/Replace triad wave for the replace-semantic recordables (documents #543, todolists #544/#545, schedule entries #546/#547)

[jeremy]

SCOPE REVISED 2026-07-27 — see the BC3 contract audit.

The premise below ("sibling recordable endpoints share the same server contract") does not hold uniformly, verified against bc3 c308693171:

• Messages is merge, not replace (Recordable#changing, plus an explicit key-guard on category_id) — dropped from scope.
• Cards is hybrid (merge for title/content, key-guarded for assignee_ids, forced-replace for due_on) — moved to Cards.update silently erases due_on on every sparse update (BC3 forced-replace) #467, and must not get a Replace* rename.
• Documents, Todolists, Schedule entries are genuine replace — these three keep the triad.

Blocked on five contract/modeling questions documented in that comment (see also the follow-up correction: blockers 4 and 5 are read-modeling gaps, not blockers). One is a live SDK-reachable data-loss bug — ScheduleEntry's unconditional replace_participants wipes every participant on any update omitting participant_ids — and one is an active corruption trap: ScheduleEntry's writable :url collides with the recording's API url on read-back.

---

🤖 Drafted with agent assistance; filed by @jeremy.

Context

#372 fixed the partial-PUT-against-replace-semantics data-loss bug for todos: the spec operation was renamed to ReplaceTodo (content required, x-basecamp-write-semantics: {mode: replace, clearsOmitted: true}), and every SDK gained the three-method surface — merge-safe update (GET → overlay set fields → full PUT), edit (read-modify-write closure), and verbatim replace.

Sibling recordable endpoints share the same server contract (full replace, omission clears) and today have the same defect shape: typed partial-update surfaces transmitting sparse PUTs.

Scope

Audit and convert, using todos as the template (spec rename + @basecampWriteSemantics + generator grouping + per-language extension + conformance fixtures):

• Messages (UpdateMessage)
• Documents (UpdateDocument)
• Cards (UpdateCard)
• Todolists (UpdateTodolistOrGroup)
• Schedule entries (UpdateScheduleEntry)

Each one needs the same verification as todos: confirm the server contract from BC3 controllers/docs (which fields are writable, which are required), then encode it in the behavior model and update-merge / edit-clear / replace-omission-clears conformance cases.

Template

The todos implementation to copy from:

• Spec: ReplaceTodo in spec/basecamp.smithy + basecampWriteSemantics trait
• Per-language: Go todos.go (shared replace transport + full-state vs sparse builders), TS services/todos-extensions.ts, Python services/todos.py (context-manager edit), Ruby services/todos_extensions.rb (prepend via zeitwerk on_load), Kotlin services/TodosService.kt (open generated class + accessor override), Swift TodosServiceExtensions.swift
• Conformance: conformance/tests/todos_write.json + requestMethod/requestBody/requestBodyAbsent assertions

Related

• Todos.Update silently wipes omitted fields (partial PUT against replace-semantics endpoint) — all 6 SDKs; add Edit/Replace, make Update merge-safe #372 (todos; the template)

[jeremy]

BC3 contract audit — revised scope (verified against c308693171, the SHA spec/api-provenance.json pins)

The issue's premise — "Sibling recordable endpoints share the same server contract (full replace, omission clears)" — does not hold uniformly. Auditing all five controllers changes the scope: one comes out, one moves to its own issue, and three are genuine.

Revised per-recordable contract

Op	BC3 contract	Evidence	Action
UpdateDocument	replace	documents_controller.rb: Document.new params.require(:document).permit(:title, :content) — fresh object	triad
UpdateTodolistOrGroup	replace	todolists_controller.rb: Todolist.new params.require(:todolist).permit(:name, :description, :track_todolist) — fresh object	triad
UpdateScheduleEntry	replace + unconditional replace_participants	schedules/entries_controller.rb: Schedule::Entry.new(update_schedule_entry_params); @recording.replace_participants schedule_entry_participants, track: true outside any key guard	triad
UpdateMessage	merge	messages_controller.rb: @recording.message.changing(message_params); Recordable#changing is dup.tap { |copy| copy.assign_attributes(attributes) }	drop from scope
UpdateCard	hybrid	kanban/cards_controller.rb: merge for title/content, key-guarded merge for assignee_ids, forced replace for due_on	#467, and explicitly no Replace* rename

Messages is merge-safe by design, and BC3 says so. find_category carries this comment:

# We remove a message's category when the supplied category_id is blank.
# Checking the existence of the category_id key in the params hash makes sure
# an API update doesn't inadvertently remove a message's category.
if params.key?(:category_id)

BC3 deliberately key-guards exactly the field that would otherwise be clobbered. Wrapping UpdateMessage in a GET→PUT composite would add a lost-update window and buy nothing. Unchecking Messages.

Cards is hybrid, so it must not be renamed ReplaceCard. Only due_on replaces. Tracked separately in #467, which also documents the two design gates blocking it (the generated update already owns the method name; intentional-clear is currently unrepresentable in the Go request type).

Revised checklist

• Messages (UpdateMessage) — merge in BC3; out of scope
• Documents (UpdateDocument)
• Cards (UpdateCard) — hybrid; moved to Cards.update silently erases due_on on every sparse update (BC3 forced-replace) #467
• Todolists (UpdateTodolistOrGroup)
• Schedule entries (UpdateScheduleEntry)

---

Blocked — five contract/modeling questions

A GET→PUT composite cannot honestly claim merge safety until each of these is answered. All five are verified below.

1. Draft subscriber replacement. Both documents_controller.rb and schedules/entries_controller.rb set subscribers when the recording is drafted:

# documents_controller.rb
attributes[:subscribers] = find_subscribers.including(@recording.creator, Current.person).uniq if @recording.drafted?

# schedules/entries_controller.rb
attributes[:subscribers] = (find_subscribers + [ @recording.creator ]).uniq if @recording.drafted?

The GET exposes only subscription_url — never subscriber IDs. So the composite cannot read back what it is about to replace. Either scope drafts out explicitly, or resolve subscriber read-back.

2. Recurring schedule entries. before_action :ensure_non_recurring_event, only: %i[ show edit update ] — the guard covers update, not just the read actions, and it redirect_tos rather than erroring. So the PUT itself redirects for a recurring entry. Needs an explicit recurring-entry rejection or a supported occurrence workflow (schedules/entries/occurrences_controller.rb exists and takes update_schedule_entry_params).

3. ScheduleEntry write-only fields — with a name-collision trap. base_schedule_entry_params permits:

:summary, :description, :url, :all_day, :highlighted,
:starts_at, :ends_at, :time_zone_name, :recurs_until, recurrence_schedule: [...]

_entry.json.jbuilder emits only summary, all_day, starts_at, ends_at, description (via the rich-text partial), conditional recurrence_schedule, and participants. So :url, :highlighted, :time_zone_name are writable but unreadable — a merge-safe PUT silently clears them.

:url is worse than merely unreadable. recordings/_recording.json.jbuilder:4 emits json.url recordable_url(recording, api_url_options) — the recording's API URL, under the same key. A composite that naively echoes the GET's url back into the PUT would write the API URL into the event's user-supplied link field. This one actively corrupts data rather than clearing it.

4. TodolistGroup color — a live unconditional clobber, plus a read-back trap. todolists/groups_controller.rb#update:

def update
  attrs = { color: params[:color] }              # unconditional
  attrs[:recordable] = new_group if params[:todolist].present?   # key-guarded
  @recording.update! attrs
end

color is assigned unguarded, so any group update omitting color sets it to nil — the same bug class as Cards due_on (#467). BC3 does emit it (app/views/api/todolists/_todolist.json.jbuilder), so no upstream change is needed; it is unmodeled SDK-side only (TodolistGroup has no color member in spec/basecamp.smithy, and UpdateTodolistOrGroupInput carries only name and description).

Read-back trap: the same jbuilder emits a different color for non-groups —

if todolist_group?(recording)
  json.color recording.color
else
  json.color recording.parent.hill_chart&.color_for(recording) || recording.color
end

so a naive read-back on a non-group todolist can persist a hill-chart-derived color into recording.color. Model it and read it back from the group branch specifically.

5. Todolist track_todolist — the "runs on every update" claim is wrong. It is permitted (permit(:name, :description, :track_todolist)) and unmodeled (zero occurrences in spec/basecamp.smithy) — both true. But toggle_hill_chart_tracking is key-guarded:

def toggle_hill_chart_tracking
  return unless params.key?(:track_todolist)
  return if Todolist.group?(@recording)
  ...
end

It does not run on every update. This is therefore a modeling gap, not a data-loss risk — the weakest of the five, and it should not block the Todolists triad. (It does still mean SDK callers have no typed way to toggle hill-chart tracking.)

---

Sequencing

One PR per recordable, sequenced — do not parallelize. #456's freshness gates (ts-check-drift, rb-check-drift, go-check-generated-drift) force regeneration, so concurrent branches conflict in openapi.json and typescript/src/generated/* on every merge. Batch the finished set into a single breaking release.

Per recordable, the one-time infrastructure from #375 already exists (the Replace verb pattern, Kotlin extensibility hooks, conformance vocabulary, SPEC §18 sanction — line 1244 currently names only Todos update/edit). Each still needs: a SERVICE_SPLITS rename in 5 generators, one client.tmpl branch, 2 Kotlin map entries, 6 extension files, 6 test files, a conformance fixture + 5 runner cases + Swift mirror, and update-merge / edit-clear / replace-omission-clears cases.

Kotlin regeneration is not covered by the default gate — check-kotlin-service-drift.sh compares operationIds only ("operation set mismatch"), so it cannot catch altered generated bodies, openness, or method naming. That is load-bearing for every generator change here. Use make kt-check-generated-drift once #460 lands; until then, regenerate Kotlin and require a clean generated-tree diff by hand.

[jeremy]

Correction to the audit above — blocker 4 is a read-only gap, not a clobber

I overstated blocker 4. The unconditional color assignment in Todolists::GroupsController#update is real, but that action has no API route, so it is not reachable from any SDK.

config/routes.rb in the API namespace:

resources :todolists, only: %i[ show edit update destroy ] do
  resources :todos,  only: %i[ index create ]
  resources :groups, only: %i[ index create ], controller: "todolists/groups"   # <- index/create only
end

Todolists::GroupsController#update is only mounted in the app namespace (resources :groups, controller: "todolists/groups" under resources :todolists, line ~1077). The SDK's UpdateTodolistOrGroup is PUT /{accountId}/todolists/{id} → TodolistsController#update, which is:

def update
  @recording.update! recordable: new_todolist    # Todolist.new(permit(:name, :description, :track_todolist))
  toggle_hill_chart_tracking                     # key-guarded
end

No color assignment on the path the SDK actually calls.

Revised blocker 4: color is emitted on reads (_todolist.json.jbuilder) but unmodeled in TodolistGroup, and there is no API write path for it at all. That makes it a pure read-modeling gap — same category as blocker 5 (track_todolist). Neither should block the Todolists triad. The read-back trap I noted (non-groups emit a hill-chart-derived color) still applies to modeling it correctly, but carries no data-loss risk.

Confirmed still live: ScheduleEntry participants

Route-checked, and this one is SDK-reachable — resources :schedule_entries, only: %i[ show update ], controller: "schedules/entries" is in the API namespace. Combined with:

Recording.transaction do
  @recording.update! recording_attributes.merge(recordable: new_schedule_entry_for_update)
  @recording.replace_participants schedule_entry_participants, track: true   # no key guard
end

and schedule_entry_participants falling back to params[:participants].to_s.split(",") (empty when absent), any SDK schedule-entry update that omits participant_ids removes every participant. UpdateScheduleEntryInput does expose participant_ids, so callers can send it — but omission is silently destructive, exactly like Cards due_on (#467).

Net blocker status

#	Blocker	Status
1	Draft subscriber replacement (Documents, ScheduleEntries)	blocking — no subscriber read-back exists
2	Recurring schedule entries (ensure_non_recurring_event covers update)	blocking
3	ScheduleEntry write-only :url / :highlighted / :time_zone_name, incl. the url API-URL collision	blocking
4	TodolistGroup color	blocking → read-modeling gap, non-blocking
5	Todolist track_todolist	modeling gap, non-blocking (key-guarded)

Plus the ScheduleEntry participants wipe above, which the triad must fix rather than merely avoid.

[jeremy]

Restructured as the tracking issue for the triad wave (2026-07-31), with the audit re-verified against current bc3 master. Corrections to the 2026-07-27 scope note above:

• The participants-wipe data-loss bug is FIXED upstream — bc3 dffa7e11b3 (#12425, 2026-07-28) guards replace_participants … if update_participants?. The SDK spec already documents omission-preserves and schedule_entries_write.json covers omit-absent + explicit-empty. Not a blocker anymore.
• TodolistGroup color clobber is not SDK-reachable: Todolists::GroupsController#update is only routable at the unpublished bucket-scoped route; the flat PUT /todolists/{id} the SDK models lands in TodolistsController#update, which never touches color. Filed upstream against bc3 instead.
• Groups accept description too (the flat controller permits+persists it for both variants) — the group branch is NOT name-only.
• ScheduleEntries is a replace with declared carve-outs, not a pure replace: post-#12425 participants are preserved on omission, and the remaining always-cleared invisible fields on the reachable path are exactly url (join link) + highlighted — fixed via the contract-design child below.

Children, in landing order (after the Go pointer policy PR that opens the v0.13.0 wave):

1. Documents triad: ReplaceDocument + merge-safe composites (gates on bc3 draft-subscriber fix) #543 — Documents triad (template PR; gates on the bc3 draft-subscriber fix in BOTH controllers; repin + full pin..HEAD triage lands here)
2. Todolist polymorphic read repair: one truthful flat shape replaces Todolist/TodolistGroup/TodolistOrGroup #544 — Todolist polymorphic read repair (flat shape replaces all three shapes)
3. Todolists triad: ReplaceTodolistOrGroup + merge-safe composites for both variants #545 — Todolists triad (builds on Todolist polymorphic read repair: one truthful flat shape replaces Todolist/TodolistGroup/TodolistOrGroup #544)
4. ScheduleEntry write contract: preservedOnOmission trait extension + bc3 url/highlighted guard-and-emit #546 — ScheduleEntry contract design (preservedOnOmission trait + behavior-model generator + bc3 guard/emit)
5. ScheduleEntries triad: ReplaceScheduleEntry + carve-out-aware composites #547 — ScheduleEntries triad (gates on ScheduleEntry write contract: preservedOnOmission trait extension + bc3 url/highlighted guard-and-emit #546)

Split out, not in the wave: #548 (recurrence_schedule read modeling). Messages stays dropped (merge semantics); Cards stays #467-lineage (hybrid, no rename — since fixed by #489).

[jeremy]

Sequencing record — C2 (#545/#574) is landing before C1 (#544)

The wave's stated order is C1 read repair → C2 triad, on the rationale that the generated oneOf envelope is a lie and you shouldn't build a merge-safe composite on top of a read you can't trust. #574 is open against main and closes #545 (C2) while #544 (C1) is still unstarted. Recording the decision rather than leaving it implicit.

#574 did not absorb C1. Verified on the PR head (0f11fff196) — spec/basecamp.smithy:1166 still reads:

union TodolistOrGroup {
  todolist: Todolist
  group: TodolistGroup
}

and all three shapes (Todolist, TodolistGroup, TodolistOrGroup) survive. #544 is specified to replace all three with one truthful flat structure. So the union is intact and C1 remains entirely necessary.

What #574 did instead was harden the union's decoders in every language that lacked one: a Swift emitter that resolves each arm's $ref and gates later arms on the keys exclusive to earlier arms (in both snake and camel spellings), plus wrong-type guards in Kotlin's JsonElement reads and the new Python/Ruby/TypeScript composites. Its own root-cause table says it plainly — every one of the six defects traces to GetTodolistOrGroup being modelled as a oneOf.

Revising the sequence rather than holding

Recommendation: let #574 land, and formally revise the order to C2 → C1.

• Stop the sparse todolist PUT from erasing the description #574 fixes defects that are already shipped to users — Swift's todolists.get() returning todolist == nil, group == nil with no error, and composites in four languages coercing a non-string field into a full-replace PUT. Blocking a live data-loss fix on a design refactor is the wrong trade.
• C1's safety intent is met by another route (runtime guards that provably fail closed, each red-proofed). Its design intent — delete the lie — is not, and still needs doing.

The alternative is a hold on #574 until #544 lands, which delays the shipped-bug fix and would force much of #574 to be rewritten against the flat shape. I don't think that's worth it, but it's a reversible call — say the word and I'll convert this to a hold.

The debt this creates, and where it's booked

Landing C2 first means C1 must now also remove machinery C574 just added, not merely change a shape. When the union goes:

• Swift's arm-gating emitter logic and the union-masking guard become dead code (a single flat structure has no arms to disambiguate), along with testUnionMaskingGuardMatchesMultiWordKeys.
• Kotlin stops receiving JsonElement and gets a real model, so its contentOrNull coercion guard loses its reason to exist.
• The Python/Ruby/TypeScript guards stay useful — those languages have no decoder regardless — and are the same class tracked in Python, Ruby and TypeScript merge-safe composites forward a non-string GET field into the full-replace PUT #576.

#544 must be updated to state this before it's picked up, or that machinery becomes permanent complexity with no surviving explanation. I'll make that edit unless you'd rather it read differently.

Deferred ledger

Adding #576 (Python/Ruby/TypeScript merge-safe composites forward a non-string GET field into the full-replace PUT — affects shipped Todos and Cards composites on main) to the wave's deferred set, alongside #562, #553 and #548. It is not gated on the triad: it's the same defect class in code that already shipped, and it should be scheduled on its own merits rather than riding the wave.

PR B (Documents, #543) status

Unblocked work is done; the gate is open upstream. The companion bc3 PR is basecamp/bc3#12494 (mirror basecamp/bc-api#429), which turned out to span five controllers rather than two — documents, messages, schedule entries, cloud files and Google documents all collapse a draft's subscriber list on any sparse update. #543 has been resynced to that scope, and its open title question is now settled by measurement: omitting title returns 200 and it silently becomes "Untitled", so it stays optional with no @required. The SDK half opens once #12494 merges.