Stop the sparse schedule-entry PUT from erasing the join link, highlight and participants (#546, #547)

[jeremy]

Closes #546. Closes #547. Third child of #374, and the one that completes it.

PUT /{accountId}/schedule_entries/{entryId} is a full replace, and every SDK shipped a sparse update over it. UpdateScheduleEntry becomes ReplaceScheduleEntry — breaking, no deprecated alias, the ReplaceTodo/ReplaceDocument precedent — and a merge-safe updateEntry / editEntry triad lands in all six SDKs.

What makes this one different from #601 is that the server contract is not uniform across the writable fields. Three of them are carved out of the replacement, and the composites must therefore not resend them. That distinction is the whole PR.

The upstream half is already merged and deployed

bc3 #12502 (4dd2926f8af0) does two things, and both are load-bearing:

PRESERVED_ON_OMISSION = %i[ url highlighted ].freeze

def update_schedule_entry_params
  super.tap do |entry_params|
    PRESERVED_ON_OMISSION.each do |attribute|
      next if params[:schedule_entry]&.key?(attribute)
      entry_params[attribute] = @recording.recordable.public_send(attribute)
    end
  end
end

and it starts emitting them — highlighted, plus the join link as join_url, in api/schedules/entries/_entry.json.jbuilder and api/schedules/entries/occurrences/show.json.jbuilder. participant_ids was already guarded separately by update_participants? since #12425.

The occurrence view matters: ensure_non_recurring_event 302-redirects a recurring entry's show/update to its occurrence, so for a recurring entry the occurrence payload is the only place these fields are reachable. This route serves non-recurring entries only.

preservedOnOmission, and why it needed a gate

@basecampWriteSemantics gains preservedOnOmission, and ReplaceScheduleEntry declares:

@basecampWriteSemantics(mode: "replace", clearsOmitted: true, preservedOnOmission: ["participant_ids", "url", "highlighted"])

Behavior-model plumbing is not automatic. scripts/generate-behavior-model builds its write clause key by key, so a trait field nobody teaches it about is dropped silently: the OpenAPI extension is right, the behavior model is quietly short, and every SDK reads the behavior model. That is exactly how this would have shipped as a no-op.

scripts/check-write-semantics-parity compares the two artifacts in both directions and is wired into make check. Red proof — the generator change excised in a scratch copy, never in the tracked tree:

=== write clause produced ===
{
  "mode": "replace",
  "clearsOmitted": true
}
=== running the parity gate against it ===
ERROR: x-basecamp-write-semantics and behavior-model.json disagree.

This is usually scripts/generate-behavior-model not carrying a trait field
through. Diff (< openapi.json, > behavior-model.json):

8,13c8
<     "mode": "replace",
<     "preservedOnOmission": [
<       "participant_ids",
<       "url",
<       "highlighted"
<     ]
---
>     "mode": "replace"
REDPROOF_PARITY_EXIT_IS 1

Restored, the gate names every carve-out set so a reviewer sees them without opening either artifact:

write semantics parity holds for 4 operation(s)
  ReplaceDocument: mode=replace clearsOmitted=true
  ReplaceScheduleEntry: mode=replace clearsOmitted=true preservedOnOmission=participant_ids,url,highlighted
  ReplaceTodo: mode=replace clearsOmitted=true
  UpdateTodolistOrGroup: mode=replace clearsOmitted=true

SPEC §18: the bound that keeps this a Replace*

Replace* survives declared carve-outs only while the preserved set is limited to fields a client could not safely resend from a read-back — write-only, system-managed, or identity-colliding. Every readable-and-writable field still clears on omission; that is what distinguishes it from a merge, and why Cards stays Update*. Widen the set past that bound and the operation has become a merge wearing a replace's name.

Each of the three earns its place:

field	why a client cannot resend it
url	identity-colliding. On write it is the join link; on read, url is the entry's own Basecamp API URL — recordings/_recording.json.jbuilder writes that key first and the entry partial renders after it, so BC3 emits the join link as join_url. Echoing the response's url back writes the API URL into the join link.
highlighted	was write-only. Accepted on write but never emitted until #12502, so no caller had a value to resend.
participant_ids	system-managed on read-back. The response carries participants (objects, not IDs), and BC3 re-screens a submitted list through the bucket's reachable people, so a resent projection can silently drop a participant who has since become unreachable.

Request optionality and response requiredness are separate facts

#601's lesson, re-derived here from bc3 at the pinned revision rather than assumed:

field	request	response	consequence
summary	optional	@required	Schedule::Entry#summary is super.presence || "Untitled", so a healthy server can never render it blank. An absent/null/blank summary in a 2xx body is a malformed response — coalescing it to "" and PUTting it back would blank a real summary on a call that only moved the entry. Read with required_writable_string.
starts_at, ends_at	@required	@required	Schedule::Entry presence-validates both and Recording validates the associated recordable on update, so omitting either is a 422, not a clear.
all_day	optional, not carved out	@required	schedule_entries.all_day is NOT NULL default false. Omitting it on a replace converts an all-day entry into a midnight-to-midnight timed one, which is why the composites resend it. Its guard is the one that cannot be a truthiness test: false is the value it most needs to admit.
description	optional	optional	absent/null is a genuinely empty description.
join_url, highlighted	— / optional	optional	emitted unconditionally by the entry partial, absent from the reduced calendar partial GetUpcomingSchedule renders through the same schema.

starts_at/ends_at read back as a bare date ("2016-06-01") for an all-day entry and a full timestamp otherwise, because BC3 renders starts_at_date_or_time. ISO8601Timestamp is a plain string in this model — Kotlin/Swift map it to String, Go to date-tolerant FlexibleTime — so both shapes decode. Every composite round-trips the value verbatim rather than parsing and re-rendering it, which would rewrite an all-day entry's bounds. Swift pins this with testUpdateEntry_roundTripsAnAllDayBareDateVerbatim.

Migration

The rename moves the verbatim path to replaceEntry and reuses the updateEntry name for the merge-safe composite. Callers keep the name and get the safe behaviour plus one extra request; callers who genuinely wanted the sparse PUT must move to replaceEntry.

SDK	was (sparse PUT)	now: verbatim	now: merge-safe	now: read-modify-write
Go	schedules.UpdateEntry(ctx, id, *UpdateScheduleEntryRequest)	ReplaceEntry(ctx, id, *ReplaceScheduleEntryRequest)	UpdateEntry(ctx, id, *UpdateScheduleEntryRequest)	EditEntry(ctx, id, func(*ScheduleEntryFields) error)
Python	schedules.update_entry(...)	replace_entry(...)	update_entry(...)	edit_entry(...) (context manager)
Ruby	schedules.update_entry(...)	replace_entry(...)	update_entry(...)	edit_entry(...) { |e| ... }
TypeScript	schedules.updateEntry(id, req)	replaceEntry(id, req)	updateEntry(id, req)	editEntry(id, (e) => ...)
Kotlin	schedules.updateEntry(...)	replaceEntry(...)	updateEntry(...)	editEntry(...) { ... }
Swift	schedules.updateEntry(...)	replaceEntry(...)	updateEntry(...)	editEntry(...) { ... }

Wire-level: UpdateScheduleEntry → ReplaceScheduleEntry, no alias. ScheduleEntry gains join_url and highlighted; all_day/starts_at/ends_at become @required. ReplaceScheduleEntryInput gains url and highlighted and marks starts_at/ends_at @required.

Caller-addressedness is language-native, and an explicitly empty value is an address, not an absence: participant_ids: [] clears participants, url: "" clears the join link, highlighted: false removes the highlight. All three survive body compaction.

edit uses setter-invocation dirty tracking, not value comparison

Value comparison cannot express intent, so snapshot/diff is structurally rejected: conformance case edit-touched-carve-outs assigns exactly the values the GET returned and still requires them on the wire.

Per SDK: Python overrides __setattr__; Ruby's writers record into a touched set; TypeScript uses a Proxy; Kotlin uses custom property setters; Swift uses didSet observers, which do not fire during initialization — so seeding leaves every dirty bit clean without a separate seeding-mode flag a later refactor could forget to clear.

Conformance

conformance/tests/schedule_entries_write.json goes from 2 cases to 9, dispatched in all six runners. The two originals are rekeyed and subsumed, not dropped (update-omits-participant-ids → replace-omission-clears, update-empty-participant-ids → replace-clears-carve-outs).

replace-omission-clears · replace-clears-carve-outs · replace-single-request · update-merge · update-addresses-carve-outs · update-clears-carve-outs · edit-clear · edit-untouched-carve-outs · edit-touched-carve-outs

Shared guards

writable_boolean / writableBoolean joins the merge-safe helpers in the three languages that have no runtime decoder on any route (TypeScript's schema.d.ts is erased at build, Python returns dict[str, Any], Ruby raw Hash). Python and TypeScript had each written a byte-equivalent private adapter for the optional highlighted read; Ruby had none at all and seeded the value unguarded, so a wrong-typed highlighted would ride into the PUT if a block assigned it back. One helper, three call sites; the wrong-type branch delegates to required_writable_boolean so an optional boolean and a required one report a non-boolean identically.

Documents' private required_writable_string copies are deleted in favour of the shared helper in all three; the Documents suites pass unchanged.

Go, Kotlin and Swift get most of their guards from their decoders (json.Unmarshal, kotlinx.serialization, Codable) — making the other three structurally safe is #578, deferred past v0.13.0. But "it has a decoder" turned out to be too coarse a rule, in two ways:

• Go's decoder is silent about a missing key. all_day, starts_at and ends_at are now non-pointer values on the generated model, so an absent or null key decodes to the zero value and encoding/json says nothing — exactly the hole required_writable_boolean fills in the dynamic SDKs. A response missing all_day would have un-all-dayed the entry on the next composite write. Go therefore carries a raw-body presence probe alongside the two-stage gen.GetScheduleEntry + ParseGetScheduleEntryResponse split, following the established todolists.go requireDescription/getWithBody precedent.
• No decoder catches blankness. Kotlin and Swift add an isBlank() guard on summary, starts_at and ends_at, matching what required_writable_string does in the dynamic three. Swift goes one field wider than its decoder covers: Codable catches absence, null and wrong type but not blankness, so ScheduleEntryFields.init refuses ""/whitespace on summary, starts_at and ends_at, matching required_writable_string.

Red proofs

Every new test was run against deliberately un-fixed source, in a scratch copy of the tree rather than by mutating the tracked file. Counts are literal, from the capture files.

SDK	carve-out echoed from read-back	all_day via truthiness	edit by value comparison	guards removed / other
Python	2 failed, 104 passed	9 failed, 97 passed	3 failed, 103 passed	summary optional guard: 7 failed, 99 passed
Ruby	7 failures (+3 conformance)	8 failures	3 failures (+1 conformance)	summary optional guard: 6 failures
TypeScript	5 failed, 111 passed	9 failed, 107 passed	2 failed, 114 passed	guards removed: 78 failed, 38 passed
Swift	4 failures	— (decoder)	3 failures	non-optional carve-outs: 7 failures
Go	3 tests failed	— (decoder)	1 test failed	zero-value carve-outs: 3 tests failed
Kotlin	20 tests, 4 failures	— (decoder)	20 tests, 2 failures (+1 conformance)	non-null carve-out defaults: 20 tests, 3 failures

The sharpest ones:

The API URL landing in the join-link member (Ruby, conformance):

  FAIL: update-merge: a summary-only update preserves the times, description and all-day flag
        Expected request body key "url" absent on request index 1, got "https://3.basecampapi.com/999/buckets/1/schedule_entries/1069479523.json"

The all-day → timed corruption (Ruby probe, mutated vs shipped):

=== probe_all_day.rb against the MUTATED (truthiness) read ===
NO ERROR RAISED — the PUT went out.
PUT bodies: [{"summary" => "Company Offsite 2026", "starts_at" => "2026-06-05", "ends_at" => "2026-06-05", "description" => "<div>All day.</div>", "all_day" => false}]
all_day on the wire: false

=== same probe against the SHIPPED (required_writable_boolean) read ===
REFUSED: Basecamp::ApiError: Schedule entry field "all_day" is required but the response carried NilClass nil
PUT bodies: []
all_day on the wire: (no PUT)

Value comparison silently dropping a deliberate write (Swift) — note this breaks update, not just edit: a caller who sets highlighted: true on an entry the GET already reported as highlighted gets silently dropped.

…:214: error: -[…testUpdateEntry_addressedJoinLinkUsesTheRequestSpelling] : XCTAssertEqual failed: ("nil") is not equal to ("Optional(true)")

Four things this PR found and did not fix

Each is pre-existing, out of scope here, and reported rather than absorbed.

1. GetUpcomingSchedule cannot decode strictly. It renders the reduced api/schedules/calendar/_entry.json.jbuilder but shares the ScheduleEntry schema, and that partial omits six members already marked @required on main: created_at, updated_at, title, inherits_status, parent, description_attachments. Kotlin's non-null val and Swift's non-optional let would throw on a real upcoming-schedule response. This PR does not widen the hole — the three members it newly marks @required (all_day, starts_at, ends_at) are emitted by both partials.
2. types.FlexibleTime is asymmetric. It accepts a bare date on decode but MarshalJSON re-renders through time.Time, so "2016-06-01" marshals back as "2016-06-01T00:00:00Z"; BC3 re-parses that in the account's zone, which west of UTC lands on the previous day and moves an all-day entry's bounds. Go's composites sidestep it by sourcing starts_at/ends_at from the raw response bytes, and TestFlexibleTimeMarshalRewritesABareDate pins the asymmetry (skipping itself if FlexibleTime ever learns to preserve source text, so the claim cannot rot). Any other caller that marshals a decoded schedule entry is still exposed.
3. CreateScheduleEntry cannot express an all-day bare date. CreateScheduleEntryRequestContent.StartsAt is time.Time and the Go wrapper parses RFC3339 into it, so create and replace disagree about what an all-day entry's bounds look like.
4. The branch was already red in three SDKs before this work, all from the same root cause — the rename deleted symbols that hand-written tests and wrappers still referenced. Go's schedules.go failed to compile, Swift's test target failed to compile (ScheduleEntryParticipantsTests), Ruby's suite errored (NoMethodError: undefined method 'update_entry'), and TypeScript's tsc --noEmit failed on a stale UpdateEntryScheduleRequest export. The conformance runners' UpdateScheduleEntry cases were likewise already broken rather than merely stale. All fixed here.

Recurrence is deliberately out of scope

recurrence_schedule is entirely unmodeled (0 occurrences in spec/basecamp.smithy and openapi.json) and its absorption stays deferred — tracked in spec/api-gaps/schedule-recurrence-writes.md, which this PR only renames the operation inside. time_zone_name and recurs_until likewise: BC3 forces all three to nil for a non-recurring entry, which is the only kind this route serves.

Provenance

Repin 2c0dafba13 → 4dd2926f8af0 (2026-08-03), with the range triage the api-gaps README's pin sentence requires. Six commits; #12502 is the only API-contract change, and the only one touching doc/api (8 lines in schedule_entries.md) or config/routes.rb (none), so spec/bc3-routes.json regenerates with no route delta. The other five are one mail-infrastructure map, two CSS-only, one account-calendar authorization reassessment, and one authentication-cache crash fix.

spec/doc-constants.json: the SPEC.md and folders-api.md unmarked-citation grants are dropped rather than renumbered — both described citations of 2c0dafba13, which is no longer the pin in force, so those sentences are now historical, exactly as their own reasons predicted.

Operation count

241, unchanged. Re-derived from behavior-model.json and cross-checked against openapi.json; never hand-incremented. The triad is a rename plus composites — it changes shape, not inventory.

Verification

make check green end to end, run detached and read back from its own marker file:

TRIAD_FULLCHECK_EXIT_IS 0
==> All checks passed

HEAD pinned either side of the run: PRE_SHA == POST_SHA == b7c3b8db5863a6bb52fb30dd4eb2a5493caaac0f. Zero FAIL/ERROR markers anywhere in the 5,900-line log.

suite	result
Go conformance	Passed: 177, Failed: 0, Skipped: 2
Kotlin conformance	Passed: 178, Failed: 0, Skipped: 1
TypeScript conformance	221 passed, 2 skipped
Swift conformance	Passed: 178, Failed: 0, Skipped: 1
Ruby unit	1358 runs, 30434 assertions, 0 failures, 0 errors
TypeScript unit	1393 passed (80 files)
Python unit	1170 passed, 4 skipped
Swift unit	Executed 41 tests, with 0 failures (0 unexpected) — genuinely executed on macOS, not the SKIP line

The check: target is now 37 entries: main's 36 plus check-write-semantics-parity, resolved additively so no merged gate lost its wiring.

Kotlin is cited from CI (Kotlin Tests) rather than the local Gradle run, since UP-TO-DATE/FROM-CACHE is not execution evidence.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b7c3b8db58

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🟡 Human review recommended

It is a breaking wire-level rename spanning the Smithy spec, generated artifacts, hand-written composites, a new CI parity gate, and conformance across all six SDKs, whose pipeline/gate invariants cannot be validated without running the generation and test toolchain, so it warrants final human review.

Pull request overview

This PR closes the sparse-PUT data-loss defect for schedule entries — the third and final child of the #374 replace-semantics wave. PUT /schedule_entries/{entryId} is a full replace, yet every SDK shipped a sparse update over it that erased the join link, highlight, and participants on any call that omitted them. The wire operation UpdateScheduleEntry is renamed to ReplaceScheduleEntry (breaking, no deprecated alias, following the ReplaceTodo/ReplaceDocument precedent), and a carve-out-aware merge-safe updateEntry/editEntry/replaceEntry triad lands in all six SDKs.

What distinguishes this from the documents/todolists children is that the server contract is not uniform across writable fields: participant_ids, url, and highlighted are preserved on omission (so the composites must not resend them unless caller-addressed), while all_day/starts_at/ends_at must always be resent. This is expressed via a new preservedOnOmission extension to the @basecampWriteSemantics trait, protected by a new bidirectional parity gate.

Changes:

• Renames UpdateScheduleEntry → ReplaceScheduleEntry; adds join_url/highlighted reads and marks all_day/starts_at/ends_at @required on ScheduleEntry; lands the merge-safe updateEntry/editEntry + verbatim replaceEntry triad across all six SDKs, using setter-invocation dirty tracking (not value comparison) for edit.
• Adds the preservedOnOmission write-semantics trait field plus scripts/check-write-semantics-parity (wired into make check) and teaches scripts/generate-behavior-model to carry the field through the pipeline.
• Expands conformance/tests/schedule_entries_write.json from 2 to 9 cases dispatched in all six runners; repins provenance 2c0dafba13 → 4dd2926f8af0 (2026-08-03) with range triage.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

File summaries

File	Description
spec/basecamp.smithy, spec/overlays/*.smithy	Rename operation, add preservedOnOmission trait field, model join_url/highlighted, tighten required fields
openapi.json, behavior-model.json	Regenerated artifacts reflecting the spec change and the new write-semantics clause
scripts/check-write-semantics-parity	New bidirectional gate asserting OpenAPI extension ↔ behavior-model parity
scripts/generate-behavior-model	Carries preservedOnOmission through the jq write clause
go/pkg/basecamp/schedules.go	ReplaceEntry/UpdateEntry/EditEntry + ScheduleEntryFields with raw-body presence probe for zero-value carve-outs
typescript/src/services/schedules-extensions.ts	Merge-safe composites with Proxy/hasOwnProperty dirty tracking; seeds url from join_url
kotlin/.../services/SchedulesService.kt	updateEntry/editEntry with custom-setter dirty tracking over ReplaceScheduleEntryBody
swift/Sources/Basecamp/SchedulesServiceExtensions.swift	didSet-based dirty tracking; isBlank() guards on summary/starts_at/ends_at
ruby/.../services/schedules_extensions.rb, python/.../services/schedules.py	Merge-safe composites with writable_boolean/__setattr__ dirty tracking
*/services/merge-safe.*	Shared writableBoolean/writable_boolean guard added; Documents' private required_writable_string copies removed in favor of the shared helper
conformance/tests/schedule_entries_write.json + 6 runners	9 conformance cases dispatched across Go/TS/Ruby/Swift/Kotlin/Python
spec/api-provenance.json, spec/doc-constants.json, spec/api-gaps/*, docs	Provenance repin, dropped stale unmarked-pin grants, range triage

Review details

• Files reviewed: 62/83 changed files
• Comments generated: 0
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Human review recommended

It is a breaking, no-alias wire rename spanning all six SDKs whose correctness depends on server-contract claims (preserved-on-omission fields, calendar-partial field emission) and a provenance repin that warrant final human verification.

Review details

Suppressed comments (1)

ruby/lib/basecamp/services/schedules_extensions.rb:276

• This docstring says highlighted has "nothing to refuse a malformed value on behalf of," but fields_from_entry reads it through MergeSafe.writable_boolean (line 289), which does refuse a wrong-typed value (it delegates any non-nil value to required_writable_boolean). The rationale here is also the opposite of the one in writable_boolean's own docstring (merge_safe.rb:186-190): because a block can assign the seeded value straight back, a wrong-typed seed must be refused rather than coerced. As written, this comment contradicts the code and could mislead a maintainer into dropping the guard that this PR deliberately added for Ruby.

• Files reviewed: 63/84 changed files
• Comments generated: 0 new
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Human review recommended

It is a breaking wire-operation rename with no deprecated alias across all six SDKs, combined with new @required response fields and a provenance repin, which warrants final human verification despite passing make check.

Review details

• Files reviewed: 63/84 changed files
• Comments generated: 0 new
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.