Merge-safe writes refuse assignee ids the API really sends

[jorgemanrubia]

A merge-safe update/edit GETs a record, reads every writable field and PUTs the whole representation back — so the id lists it reads are the id lists it writes. Three fields are a list of embedded people projected down to ids: a todo's assignees and completion_subscribers, and a schedule entry's participants. The guard that reads them refused a body the reference accepts, failing an update that only changed the title.

BC3 serializes person ids as JSON strings in some responses — it is why the reference's normalizer exists — and a string id reaches this guard whenever no pre-decode walk converted it first. On main none does, at these fields: #908 narrowed the positional normalizer to the reference's two surfaces (gauges and notifications) and pinned the refusal it reopened here as tests "to flip when #913 lands". How often BC3 actually sends one the fixtures cannot say — none of the person objects in spec/fixtures carries a string id — but they do show the personable_type marker the other pass keys on is often missing, on 3 of 7 assignees people.

Originally tracked in 42 Merge-safe writes refuse assignee ids the reference accepts.

Follows Seven SDKs read a person id seven ways, and Go disagreed with itself, whose shared ParseInt scan every reader here calls.

What the reference actually does here

A person's id is the single field in the generated model the reference decodes flexibly (types.FlexibleInt64, reached through Person.Id), and fieldsFromTodo appends whatever that produced with no filter of any kind — 0 included. Measured through the reference's own Update and EditEntry composites over 39 wire shapes; the three sites answer identically, row for row:

• a string id is the number strconv.ParseInt(s, 10, 64) spells — leading zeros, a leading + and a leading - all included;
• a string that is not a number at all is the system actor 0, and not an error — confirmed with the operator on the card as the behaviour to follow;
• a string whose digits overflow is an error, decided inside the scan: "18446744073709551615x" is 0, "18446744073709551616x" fails the read;
• an absent id is the zero value with no error, while an explicit null id fails the read;
• a null element decodes to the zero Person and contributes 0.

Why the obvious fix is wrong

Not a widened normalizer walk. The reference covers this site with its decoder, and its positional pass reaches creator and participants only — which is exactly the lesson #908 learned when a walk over every response turned plain-int64 people on UpcomingScheduleEntry into the system actor. And not a sweep: TemplateLibraryConfirmationPerson.ID (templates.go:60) is a plain int64 whose string id correctly drops the projection.

So the fix is decoder coverage at exactly these three fields: each port's merge-safe reader reads the id itself, by the shared scan — Python parse_int64, Ruby Ids.person_from_wire, TypeScript scanPersonId/personIdNumber. The guard reads no other schema, so the sentinel's 0 here is the flexible decoder's rule at a flexible field, not the over-reach #908 removed.

It closes the write path only. A plain generated read in Ruby, Python and TypeScript still returns an untagged person's string id as the string where the reference gives the number; SPEC §10 now says that rather than pointing here.

Divergence counts

Rows diverging from the reference over the 39 shapes, identical at all three sites:

SDK	main	with this PR
Python	20	0
Ruby	20	0
TypeScript	23	6

TypeScript's six are the JavaScript number boundary, which nothing at this layer can close. Four are ids past 2^53 — string or number — refused rather than silently rounded into a different person's id, the resolution personIdNumber documents; the reference accepts those, and on main three of the four were already refused. The other two, 1024.0 and 1e3, are accepted where the reference refuses, because JSON.parse has already turned them into integers.

Row by row, todo assignees

wire shape of the element	Go reference	Py main	Rb main	TS main	Py 913	Rb 913	TS 913
number	[1049715914]	ok	ok	ok	ok	ok	ok
numeric string, no personable_type	[1049715914]	x	x	x	ok	ok	ok
numeric string, with personable_type	[1049715914]	ok	ok	ok	ok	ok	ok
leading zeros string	[7]	x	x	x	ok	ok	ok
negative string	[-5]	x	x	x	ok	ok	ok
plus-signed string	[5]	x	x	x	ok	ok	ok
non-numeric sentinel	[0]	x	x	x	ok	ok	ok
non-numeric sentinel w/ personable_type	[0]	ok	ok	ok	ok	ok	ok
overflow string	error	ok	ok	ok	ok	ok	ok
int64 max string	[9223372036854775807]	x	x	x	ok	ok	x
empty string	[0]	x	x	x	ok	ok	ok
whitespace string	[0]	x	x	x	ok	ok	ok
hex string	[0]	x	x	x	ok	ok	ok
float-ish string	[0]	x	x	x	ok	ok	ok
underscore string	[0]	x	x	x	ok	ok	ok
fullwidth digit string	[0]	x	x	x	ok	ok	ok
null id	error	ok	ok	ok	ok	ok	ok
missing id	[0]	x	x	x	ok	ok	ok
bool id	error	ok	ok	ok	ok	ok	ok
non-integral number	error	ok	ok	ok	ok	ok	ok
integral float number	error	ok	ok	x	ok	ok	x
number beyond int64	error	x	x	x	ok	ok	ok
object id	error	ok	ok	ok	ok	ok	ok
array id	error	ok	ok	ok	ok	ok	ok
element not an object	error	ok	ok	ok	ok	ok	ok
element null	[0]	x	x	x	ok	ok	ok
two elements, second bad	[7,0]	x	x	x	ok	ok	ok
empty array	[]	ok	ok	ok	ok	ok	ok
int64 min string	[-9223372036854775808]	x	x	x	ok	ok	x
syntax refusal after uint64 max digits	[0]	x	x	x	ok	ok	ok
range refusal before the bad byte	error	ok	ok	ok	ok	ok	ok
uint64-range string (above int64 max)	error	ok	ok	ok	ok	ok	ok
number past 2^53 (inside int64)	[9007199254740993]	ok	ok	x	ok	ok	x
exponent number	error	ok	ok	x	ok	ok	x
exponent string	[0]	x	x	x	ok	ok	ok
string past 2^53 (inside int64)	[9007199254740993]	x	x	x	ok	ok	x
key is null	[]	ok	ok	ok	ok	ok	ok
key is not an array	error	ok	ok	ok	ok	ok	ok
key absent	[]	ok	ok	ok	ok	ok	ok

The SDKs with a decoder

Kotlin, Swift and Rust do not use this reader. Measured through their real composites, they still refuse an absent id and a null element (and Swift reads {"id":1024.0} as 1024) — generated-model optionality, filed as Kotlin, Swift and Rust decoders refuse person shapes the reference writes back.

One structural difference, out of scope

Python's update_entry never reads participants — only edit_entry does — so malformed participants that fail the reference's decode go unnoticed on that path. That is lazy-vs-eager decoding of every unread field, not a person-id question.

Tests

Every test added or flipped fails against main's readers: 49 in Python, 50 in Ruby, 62 in TypeScript. TypeScript also pins writableIdList directly, so the guard is tested on its own whatever a walk covers — that matters, because while #908's walk still named assignees the composite tests passed with a guard that refused every string.

The Go oracle these numbers came from (throwaway, not committed)

package basecamp

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"testing"
)

// Throwaway oracle: measures what the reference SENDS for assignee_ids /
// completion_subscriber_ids given each person-id shape.
func TestCard42Oracle(t *testing.T) {
	var cases [][2]string
	raw, readErr := os.ReadFile("<scratch>/corpus.json")
	if readErr != nil {
		t.Fatal(readErr)
	}
	if err := json.Unmarshal(raw, &cases); err != nil {
		t.Fatal(err)
	}

	out := map[string]map[string]string{}

	for _, key := range []string{"assignees", "completion_subscribers"} {
		out[key] = map[string]string{}
		for _, tc := range cases {
			name, rawBody := tc[0], tc[1]
			body := todoBodyWith(key, rawBody)
			svc, reqs := testTodosCaptureServer(t, body, body, nil)
			_, err := svc.Update(context.Background(), 1, &UpdateTodoRequest{})
			field := "assignee_ids"
			if key == "completion_subscribers" {
				field = "completion_subscriber_ids"
			}
			out[key][name] = describeCard42Outcome(err, reqs, field)
		}
	}

	enc, _ := json.MarshalIndent(out, "", "  ")
	os.WriteFile("<scratch>/go-oracle.json", enc, 0o644)
	fmt.Println(string(enc))
}

func todoBodyWith(key, raw string) []byte {
	base := map[string]any{
		"id":                     int64(1),
		"content":                "Task",
		"description":            "<div>d</div>",
		"assignees":              []any{},
		"completion_subscribers": []any{},
	}
	enc, _ := json.Marshal(base)
	var m map[string]json.RawMessage
	json.Unmarshal(enc, &m)
	if raw == "ABSENT" {
		delete(m, key)
	} else {
		m[key] = json.RawMessage(raw)
	}
	b, _ := json.Marshal(m)
	return b
}

func describeCard42Outcome(err error, reqs *[]capturedTodoRequest, field string) string {
	if err != nil {
		return "ERROR: " + err.Error()
	}
	for _, r := range *reqs {
		if r.method == "PUT" {
			v, ok := r.body[field]
			if !ok {
				return "SENT: <key absent>"
			}
			j, _ := json.Marshal(v)
			return "SENT: " + string(j)
		}
	}
	return "NO PUT"
}

// Second oracle: the schedule-entry composite's participants key.
func TestCard42OracleSchedules(t *testing.T) {
	var cases [][2]string
	raw, readErr := os.ReadFile("<scratch>/corpus.json")
	if readErr != nil {
		t.Fatal(readErr)
	}
	if err := json.Unmarshal(raw, &cases); err != nil {
		t.Fatal(err)
	}

	out := map[string]string{}
	for _, tc := range cases {
		name, rawBody := tc[0], tc[1]
		body := entryBodyWith(rawBody)
		svc, reqs := testSchedulesCaptureServer(t, body, body, nil)
		_, err := svc.UpdateEntry(context.Background(), 1, &UpdateScheduleEntryRequest{})
		out[name] = describeCard42Schedule(err, reqs, "participant_ids")
	}

	enc, _ := json.MarshalIndent(out, "", "  ")
	os.WriteFile("<scratch>/go-oracle-schedules.json", enc, 0o644)
	fmt.Println(string(enc))
}

func entryBodyWith(raw string) []byte {
	base := map[string]any{
		"id":           int64(1),
		"summary":      "Event",
		"description":  "<div>d</div>",
		"all_day":      false,
		"starts_at":    "2026-01-01T09:00:00Z",
		"ends_at":      "2026-01-01T10:00:00Z",
		"participants": []any{},
	}
	enc, _ := json.Marshal(base)
	var m map[string]json.RawMessage
	json.Unmarshal(enc, &m)
	if raw == "ABSENT" {
		delete(m, "participants")
	} else {
		m["participants"] = json.RawMessage(raw)
	}
	b, _ := json.Marshal(m)
	return b
}

func describeCard42Schedule(err error, reqs *[]capturedScheduleRequest, field string) string {
	if err != nil {
		return "ERROR: " + err.Error()
	}
	for _, r := range *reqs {
		if r.method == "PUT" {
			v, ok := r.body[field]
			if !ok {
				return "SENT: <key absent>"
			}
			j, _ := json.Marshal(v)
			return "SENT: " + string(j)
		}
	}
	return "NO PUT"
}

// Third oracle: the schedule-entry EDIT composite, where the callback reads the
// seeded participant ids back and re-sets them, so the projection reaches the wire.
func TestCard42OracleSchedulesEdit(t *testing.T) {
	var cases [][2]string
	raw, _ := os.ReadFile("<scratch>/corpus.json")
	json.Unmarshal(raw, &cases)

	out := map[string]string{}
	for _, tc := range cases {
		name, rawBody := tc[0], tc[1]
		body := entryBodyWith(rawBody)
		svc, reqs := testSchedulesCaptureServer(t, body, body, nil)
		_, err := svc.EditEntry(context.Background(), 1, func(f *ScheduleEntryFields) error {
			f.SetParticipantIDs(f.ParticipantIDs())
			return nil
		})
		out[name] = describeCard42Schedule(err, reqs, "participant_ids")
	}

	enc, _ := json.MarshalIndent(out, "", "  ")
	os.WriteFile("<scratch>/go-oracle-schedules-edit.json", enc, 0o644)
	fmt.Println(string(enc))
}

[Copilot]

🟡 Changes recommended

The Ruby path can silently convert an overflow-before-junk ID to 0 until the parser fix from #908 is incorporated.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Aligns merge-safe person-ID projections with the Go reference across Python, Ruby, and TypeScript.

Changes:

• Accepts missing IDs and null person elements as ID 0.
• Adds flexible person-ID parsing for Python and Ruby.
• Expands regression coverage for todos and schedules.

[!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
typescript/src/services/merge-safe.ts	Handles absent IDs and null elements.
typescript/tests/services/todos.test.ts	Tests todo ID-list write-back.
typescript/tests/services/schedules.test.ts	Tests participant projection behavior.
ruby/lib/basecamp/services/merge_safe.rb	Uses flexible person-ID decoding.
ruby/test/basecamp/services/todos_service_test.rb	Expands todo ID corpus coverage.
ruby/test/basecamp/services/schedules_service_test.rb	Expands participant guard coverage.
python/src/basecamp/services/_merge_safe.py	Implements reference-compatible ID parsing.
python/tests/services/test_todos.py	Covers flexible and malformed todo IDs.
python/tests/services/test_schedules.py	Covers participant ID behavior.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Balanced (auto)

Note

Copilot is running an experiment and ran this review at Balanced.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jorgemanrubia]

🤖 New head on #908: f2c8af044733e204eed58e8e14e1caa25f8c5de6 (person-id-grammar, your base). Four commits on top of 32ce521f, and two of them change ground you are standing on.

The Ruby parser fix you depend on is unchanged. Ids.parse_int and Http.coerce_person_id are byte-for-byte what they were at 32ce521f; nothing in this round touches the grammar.

What does change for you — the positional pass is narrowed (55c68a2f), decided by Jorge on card 35. Go runs normalizeEmbeddedPersonIds only from decodeGaugePayload and the notification decoders, so Ruby, Python and TypeScript now run it only there — gated on request path in Ruby (Http::EMBEDDED_PEOPLE_PATHS) and Python (basecamp._person_id.EMBEDDED_PEOPLE_PATHS), on OperationInfo.service in TypeScript. Running it everywhere had turned a string id at UpcomingSchedulePerson / MyAssignmentAssignee / OutOfOfficePerson into the system actor, where Go refuses the body.

The consequence lands squarely in your scope: with no decoder, those three ports now refuse a string id in assignees, subscribers, completion_subscribers and schedule participants, where Go's FlexibleInt64 reads the number. TypeScript had closed assignees by widening the key set to twelve; that is walked back too. The refusal is the safe direction — every merge-safe composite refuses before the PUT — and I handed it to you rather than keep it in 908.

The tests to flip when your work lands, each commented as such:

• TS todos.test.ts — refuses a string ${field} id that the reference accepts, and PR #913 owns (assignees, completion_subscribers), plus "string" back on the refused-id row
• Ruby schedules_service_test.rb — test_update_entry_refuses_string_participant_ids_the_reference_accepts, test_edit_entry_refuses_a_sentinel_participant_rather_than_inventing_the_system_actor
• Python test_schedules.py — test_a_participant_with_a_string_id_is_refused_where_the_reference_accepts_it

One constraint worth carrying into your design: close these at the reader, field by field, not by re-widening the normalizer. Each port now has a negative test that fails if a strict site stops refusing a string id (TS person-id-normalization.test.ts, Ruby normalize_person_ids_test.rb, Python test_person_id.py TestThePositionalPassRunsOnlyWhereTheReferenceRunsIt), so a re-widening will go red on purpose. The site inventory is in my earlier comment on #908. TemplateLibraryConfirmationPerson is untouched by 908 either way: it sits under people, which no walk here reaches.

Heads-up on the merge mechanics. 908 squash-merges, and this repo has delete_branch_on_merge=true, so GitHub will delete person-id-grammar and retarget #913 to main. Your branch will then still carry 908's 23 pre-squash commits in its ancestry, which main will not have, so expect the diff to balloon and conflict until you rebase onto the squash — something like git rebase --onto origin/main f2c8af04 from your branch. I will not touch card42-merge-safe-person-ids; flagging it so it is not a surprise.

908 is not merged yet: a fresh adversarial review is running on f2c8af04. I'll post here again if that review moves the head.

[jorgemanrubia]

🤖 #908 moved again, and this one is a force-push: new head cd982a0791e69ef6c82ddacfd6f537b5197ec0fe (replaces f2c8af04, which I gave you earlier).

Why it was rewritten. main moved twice under 908 — #912 (event feed) and #911 (nested identity typing) — so I rebased person-id-grammar onto 8ad161b7. Your base branch's history is therefore not the one you branched from. If you rebase now, use git rebase --onto origin/person-id-grammar f2c8af04 from your branch; if you are waiting for 908 to land on main, the earlier note stands (retarget to main, then rebase onto the squash).

The Ruby parser you depend on is still unchanged. ruby/lib/basecamp/ids.rb and Http.coerce_person_id are untouched by every commit since 32ce521f.

What changed on top, relevant to your scope:

• The gate is now anchored to the END of the URL path in Ruby and Python, per surface: /my/readings.json, /my/readings/bubble_ups.json, /gauge_needles/<id>, /projects/<id>/gauge/needles.json, /reports/gauges.json. Previously it matched unanchored over the whole URL. If your decoder-coverage work routes anything through Http.embedded_people_url? or basecamp._person_id.embedded_people_url, it now answers false for any path that merely contains a surface's spelling.
• The Merge-safe writes refuse assignee ids the API really sends #913 gap list in SPEC §10 is now complete, and you may want to check it against your audit. Besides assignees, subscribers, completion_subscribers and schedule participants, it now names an untagged creator on every recording read in all three decoder-less ports, plus TypeScript's further seven keys (approver, booster, completer, performed_by, granted, revoked, person).
• Measured, after rebasing onto Type every field of a nested identity, not only the ones the projection reads #911 — this corrects something the SPEC briefly said: the gap is visible on a plain generated read (comments.get returns an untagged creator.id of "7" as the string "7" in TypeScript, Ruby and Python) and is not visible on recordings.summarize(). Since Type every field of a nested identity, not only the ones the projection reads #911, all three summary composites decode a nested person's id as a FlexibleInt64, so summarize gives 7 everywhere. So your worklist is the generated reads, not the summary.

One #911 interaction you might meet: #911's summarize test expected a personable_type-tagged creator id "9223372036854775807" to come back as person 0, because main's normalizer collapsed ids past 2^53 into the system actor. That collapse is one of 908's fixes, so on this head that input is refused ("exactly") instead, in agreement with the untagged spelling. The assertion is updated in cd982a07.

A final adversarial Opus review is running on cd982a07. 908 merges only if it converges and CI is green. I will not delete person-id-grammar on merge — no --delete-branch — but the repo has delete_branch_on_merge=true, so I'll check straight after merging whether GitHub removed it anyway, and post here either way.

[jorgemanrubia]

🤖 #908 is merged: squash commit a5bc3ac7d3cf2e42531ab990e7b88f6e218a950c on main. You're clear to rebase and land.

Where your base went, exactly:

• The head that merged is efaaa58bd3593b45d1558e1f96815221c1dac895, not cd982a07. main moved twice more before 908 could land (The retryable regression sweep passes while the invariant leaks #909, then The event feed's paging is declared as an absence #914), so I rebased twice more. Both were mechanical: excluding those two PRs' own files, efaaa58b is tree-identical to cd982a07 apart from one comment. An Opus reviewer confirmed that on each head.
• The repo's delete_branch_on_merge=true deleted person-id-grammar anyway, even though I passed no --delete-branch. GitHub then retargeted Merge-safe writes refuse assignee ids the API really sends #913 to main, which it now shows.
• I restored person-id-grammar at efaaa58b, the exact pre-squash head, so you have a stable ref to rebase from. It is frozen: I won't push to it again.

To rebase onto the squash, from card42-merge-safe-person-ids:

git fetch origin
git rebase --onto origin/main efaaa58bd3593b45d1558e1f96815221c1dac895

That replays only your own commits. If your branch still sits on an older 908 head (f2c8af04 or cd982a07), use that SHA as the --onto upstream instead: whichever 908 commit your first own commit is parented on.

What is on main for you, unchanged from what I described earlier:

• The Ruby parser you depend on, Ids.parse_int and Http.coerce_person_id, is exactly as it was.
• The positional pass runs only on gauges and notifications. It is gated on an end-anchored URL path in Ruby and Python, and on OperationInfo.service in TypeScript.
• The full decoder-coverage gap you own is in SPEC §10. It is visible on plain generated reads, not on recordings.summarize().
• The refusal tests to flip are the ones I listed, and each negative test goes red if a strict site stops refusing a string id.