BC5 launch reconciliation: registry refresh for the shipped BC5 API train#325
Merged
Conversation
github-actions
Bot
added
documentation
Spec Change Impact
Impact on SDKs:
Breaking Change Assessment:
Checklist for SDK updates:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6a6d438ebb
ℹ️ 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".
There was a problem hiding this comment.
Pull request overview
This docs/registry-only PR reconciles the BC5 API-gap registry with launch findings and pending BC3 follow-up work.
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.
Changes:
- Adds a
memories-emptied-regressionbrief for the BC5memories: []regression. - Reclassifies Stacks as web-only / not an API resource.
- Narrows Everything aggregate scope and updates coordination notes around pending merges.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
spec/api-gaps/memories-emptied-regression.md |
Adds the regression brief and SDK/canary absorption notes. |
spec/api-gaps/stack-doc-and-smithy.md |
Reclassifies Stacks as not an API resource. |
spec/api-gaps/everything-aggregates.md |
Updates Everything aggregate endpoint scope from 22 to 17. |
spec/api-gaps/activity-timeline.md |
Adds launch note about activity/timeline routes on master. |
spec/api-gaps/README.md |
Updates registry table and explanatory notes. |
COORDINATION.md |
Reframes contract decisions as pending merges rather than decisions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 6 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
jeremy
added a commit
that referenced
this pull request
May 27, 2026
…tatus) - everything-aggregates.md: the leftover "all 9 groups" consistency bullet now reads "all 8 groups", matching the files-group drop above. - activity-timeline.md: reword the launch FYI so it no longer reads as a shipped, consumable JSON contract (which conflicted with status no-json-contract). The routes were rewritten on master directly (not gated behind #10947) but still lack a documented/SDK-absorbable contract, so the entry stays no-json-contract; absorption pulls from master when that lands.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 37cdb289c4
ℹ️ 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".
jeremy
added a commit
that referenced
this pull request
May 28, 2026
The GetMyNotificationsOutput.memories Smithy doc still framed the BC5 `[]` as an unresolved keep-vs-break decision and told readers to "consume both", which contradicts the reconciliation (PR #325): the decision is made and the fix is written but unmerged in BC3 #10947. Reword to state the confirmed regression, the in-flight fix, and "prefer bubble_ups; don't rely on memories being populated on BC5 until #10947 ships". Points at the regression brief. Regenerated the artifacts that inherit the @documentation trait: openapi.json + openapi-stripped.json, the TS schema.d.ts JSDoc, and the Go client.gen.go comment. Ruby/TS metadata + Ruby types.rb carry only a generated-timestamp bump (their generators don't emit this field description); Python/Kotlin/Swift generated output is unchanged. Drift checks (smithy-check, go-check-drift, behavior-model-check) clean. Addresses the Copilot/cubic doc-consistency thread on PR #325.
github-actions
Bot
added
typescript
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e12fe8f402
ℹ️ 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".
There was a problem hiding this comment.
1 issue found across 8 files (changes from recent commits).
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
Review carefully before merging. Consider a major version bump. |
github-actions
Bot
added
bug
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 37c17655ea
ℹ️ 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".
jeremy
force-pushed
the
bc5-readiness-launch-reconciliation
branch
from
July 22, 2026 03:05
47f7741 to
9a5d72b
Compare
github-actions
Bot
added
the
documentation
jeremy
changed the title
Member
Author
|
Rebased onto #293's refreshed head ( Highlights:
Verification: |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9a5d72b639
ℹ️ 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".
…pe cuts Post-launch (2026-05-27) reconciliation of the API-gap registry to what BC5 master actually shipped vs BC4 (the four branch). - New spec/api-gaps/memories-emptied-regression.md: the confirmed live subtractive regression (BC5 master ships json.memories [] while BC4 four populates it). Not an additive gap; status partial-coverage (closest fit). The fix is written but unmerged in BC3 #10947 (json.memories @bubble_ups); status flips to addressed-in-bc3-pr-10947 on merge. bc3_pr: 10947 set. - stack-doc-and-smithy.md: flipped partial-coverage -> confirmed-not-api-resource. Stacks are web-only on both four and master (layout false, no respond_to :json, no doc section; Stacks::CollectablesController absent on master; the _stack partial only renders nested). No StacksService. Retained as the classification record per the briefs-trump-allowlist rule. - everything-aggregates.md: 22 -> 17 endpoints. The files group was dropped (master consolidated file-type routes into /files/recent?kind= and unions unrenderable attachment recordings). 8 active groups; explicit route list. Files-by-kind noted as a possible future deliverable, not modeled now. - activity-timeline.md: FYI that /activity.json + /projects/:id/timeline.json ship on master directly (not PR #10947); the removed /activity/days + /activity/dates sub-routes were never modeled. - README.md: stack row -> confirmed-not-api-resource; new memories-emptied-regression row; note distinguishing the subtractive regression from the registry's additive gaps. - COORDINATION.md: both contract-decision items reframed as open-pending-merge, not open-pending-decision. The counterfactual "commit 64acf34 aliases memories to bubble_ups" claim is purged (no such commit on four/five/master). BC3 provenance at the finding: five+api @ 716e710ee5 (reconciliation handoff). make validate-api-gaps: clean (12 entries). No spec/generated changes — the smithy doc comment is left as-is (already substantively accurate) so this stays a docs/registry-only change with no cross-language regen.
…tatus) - everything-aggregates.md: the leftover "all 9 groups" consistency bullet now reads "all 8 groups", matching the files-group drop above. - activity-timeline.md: reword the launch FYI so it no longer reads as a shipped, consumable JSON contract (which conflicted with status no-json-contract). The routes were rewritten on master directly (not gated behind #10947) but still lack a documented/SDK-absorbable contract, so the entry stays no-json-contract; absorption pulls from master when that lands.
The GetMyNotificationsOutput.memories Smithy doc still framed the BC5 `[]` as an unresolved keep-vs-break decision and told readers to "consume both", which contradicts the reconciliation (PR #325): the decision is made and the fix is written but unmerged in BC3 #10947. Reword to state the confirmed regression, the in-flight fix, and "prefer bubble_ups; don't rely on memories being populated on BC5 until #10947 ships". Points at the regression brief. Regenerated the artifacts that inherit the @documentation trait: openapi.json + openapi-stripped.json, the TS schema.d.ts JSDoc, and the Go client.gen.go comment. Ruby/TS metadata + Ruby types.rb carry only a generated-timestamp bump (their generators don't emit this field description); Python/Kotlin/Swift generated output is unchanged. Drift checks (smithy-check, go-check-drift, behavior-model-check) clean. Addresses the Copilot/cubic doc-consistency thread on PR #325.
…s branch The brief's SDK-absorption runbook read as if the pairwiseDeltaAllowed waiver and conformance/tests/live-my-surface.json were present here, but those canary files are on PR #308's branch (this branch is the registry record only). Reword to state #308 introduces the waiver and that it gets removed from live-my-surface.json once #308 and BC3 #10947 both land. Also reframe the "no Smithy change" bullet to "no structural change" — this PR does realign the memories doc comment (documentation, not a shape change).
COORDINATION.md said the pairwiseSupersetArray rule "is waived via pairwiseDeltaAllowed", which reads as if the canary surface exists on this branch — it does not (conformance/tests/live-my-surface.json is on PR #308). Reword to attribute the rule + waiver to #308's branch, matching the same fix already made in the memories-emptied-regression brief.
…ntract The brief captured the launch-reconciliation interim state: a 17-operation surface with the files group cut and the feed groups framed as recent-suffixed sub-routes. doc/api/sections/everything.md at #10947's live head 589b1970 (verified 2026-07-13) supersedes that: - 18 documented GET operations across 9 groups: todos x5 and cards x6 via filtered sub-routes, plus 7 root-path feeds (documents, messages, comments, checkins, forwards, files, boosts). - The files group is restored (GET /files.json with kind and people_ids[] filters). - Root collections are the documented contract for the feed groups; only the bare /todos.json and /cards.json roots remain HTML shells. - /<resource>/recent.json paths are internal web Turbo-frame feeds, not API surface — the SDK must not model them. Also repin the #10947 head references in memories-emptied-regression.md and COORDINATION.md from 9dc63e2e to 589b1970.
BC3's BC5 API train merged to master 2026-07-18..21 (8 PRs: #11628 BC4 wire-format compatibility, #12320 cloud files + google documents, #12321 calendars, #12322 My Notes, #12323 docs true-up, #11627 Everything feeds, #11629 doc-generation tooling, #12357 cURL examples). BC3 #10947 closed unmerged, superseded by the train — every "when #10947 merges" trigger is dead. Refresh the registry to how the train actually shipped: - memories-emptied-regression -> addressed-in-bc3-pr-11628: permanently empty by documented contract (my_notifications.md codifies the always-empty placeholder; the @bubble_ups alias never shipped). The #308 canary waiver is now permanent. New bubble-up surface (bubble_ups_count, scheduled_bubble_ups_count, limit_bubble_ups, GET /my/readings/bubble_ups.json) noted as future absorption items. - everything-aggregates -> addressed-in-bc3-pr-11627: re-derived to the exact 17 documented ops (todos x5, cards x6, six flat roots); no /documents.json root; bare /todos.json + /cards.json are HTML shells; /recent.json stays internal-never-model; bucket-grouped vs flat contract families documented. - activity-timeline -> addressed-in-bc3-pr-11629: re-derived to the 3-route surface (account /reports/progress.json, project timeline, person /reports/users/progress/:id.json object wrapper) — a BC4-era contract BC5 kept, re-verified against live BC5 by the #11629 doc tooling; SDK already models all 3 routes, remainder is additive fields (15-value kind vocabulary, schedule-entry data struct, avatars_sample, attachments). - calendar -> addressed-in-bc3-pr-12321; scratchpad -> addressed-in-bc3-pr-12322 (shipped route is /my/notes.json). - step-top-level -> absorbed-in-sdk: all five top-level ops already modeled in spec/basecamp.smithy with due_on + assignee_ids on create/update, matching card_table_steps.md (legacy assignees comma-string deliberately unmodeled). - recordable-subtypes-doc stays partial-coverage: CloudFile + GoogleDocument shipped via #12320; Journal dropped from the train (#11629 "Drop journal doc generation"). - search-filter-additions stays partial-coverage: docs shipped but open #12361 reworks the filter params — not final, don't absorb yet. - todoset-completed-list-visibility stays ambiguous; open #12021 cited as the deciding PR. - stack-doc-and-smithy stays confirmed-not-api-resource: product renamed Stacks -> Folders, API being scoped server-side, wire type still Stack. - rich-text-project-attachable + recording-bubbleupable-field stay no-json-contract (spot-checked merged docs: no Project-attachable contract in rich_text.md, no bubbleupable anywhere in doc/api). - README + COORDINATION: statuses updated; memories settled as permanent-by-contract; app_todoslists_url typo re-verified 2026-07-21 (still only the typo, no alias, no SDK action).
…rate Rewrite GetMyNotificationsOutput.memories' doc comment to the settled contract: permanently [] on BC5 per doc/api/sections/my_notifications.md (codified by BC3 #11628 — an always-empty placeholder superseded by bubble_ups); BC4 still populates it, an accepted BC4->BC5 subtractive delta recorded in spec/api-gaps/memories-emptied-regression.md. New integrations should use bubble_ups / scheduled_bubble_ups. Regenerate every artifact inheriting the doc string (openapi.json, openapi-stripped, TS schema.d.ts + metadata, Go client.gen.go, Ruby types + metadata).
jeremy
force-pushed
the
bc5-readiness-launch-reconciliation
branch
from
July 22, 2026 04:42
9a5d72b to
1d45eec
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1d45eec7e4
ℹ️ 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".
The step-top-level brief flipped to absorbed-in-sdk citing the five flat Smithy operations, but the merged card_table_steps.md also documents bucket-scoped equivalents. Make the exclusion explicit: the doc lists them as cross-references to the same operations, and the SDK follows the card-tables convention of modeling the canonical flat routes only — server-side aliases, not additional surface.
jeremy
added a commit
to robzolkos/basecamp-sdk
that referenced
this pull request
Jul 22, 2026
…reate-bucket-scope-20260601145434 * origin/main: (28 commits) Upstream sync: repin provenance to bc3 ba105ba7 (2026-07-22), register post-train contracts, codify pin semantics (basecamp#390) ci: pin conformance uv sync to the matrix Python; parse the fan-in gate (basecamp#388) BC5 readiness: pairwise BC4↔BC5 + check-bc5-compat orchestrator + scheduled CI (basecamp#308) CI: fold conformance suites into their language test jobs (basecamp#387) Fix TypeScript SDK Content-Type on GET requests (basecamp#384) BC5 launch reconciliation: registry refresh for the shipped BC5 API train (basecamp#325) BC5 readiness: cross-language wire-replay decoders (basecamp#301) BC5 readiness: Go wrapper forward-compat audit + field-level drift check (basecamp#309) BC5 readiness: TypeScript live wire-capture canary (basecamp#294) BC5 readiness: forward-compat spec, briefs, parity lint (basecamp#293) deps(ts): bump brace-expansion from 5.0.2 to 5.0.7 in /typescript (basecamp#386) typescript: bump fast-uri, brace-expansion, js-yaml overrides for fresh advisories (basecamp#385) deps(actions): bump the actions group with 6 updates (basecamp#382) deps(ruby): bump the bundler-dependencies group in /ruby with 2 updates (basecamp#379) deps(kotlin): bump the gradle-dependencies group (basecamp#383) deps(go): bump github.com/oapi-codegen/oapi-codegen/v2 in /go (basecamp#381) deps(ts): bump the npm-dependencies group in /typescript with 2 updates (basecamp#380) deps(smithy): bump the smithy-gradle-dependencies group (basecamp#378) deps(go): bump github.com/oapi-codegen/runtime (basecamp#377) Todos Update/Edit/Replace: merge-safe writes across all 6 SDKs (basecamp#375) ... # Conflicts: # go/pkg/basecamp/api-provenance.json # go/pkg/basecamp/version.go # go/pkg/generated/client.gen.go # kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/BasecampConfig.kt # openapi.json # python/src/basecamp/_version.py # ruby/lib/basecamp/generated/metadata.json # ruby/lib/basecamp/generated/types.rb # ruby/lib/basecamp/version.rb # spec/api-provenance.json # spec/basecamp.smithy # swift/Sources/Basecamp/BasecampConfig.swift # typescript/src/client.ts # typescript/src/generated/metadata.ts # typescript/src/generated/openapi-stripped.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Post-launch reconciliation of the API-gap registry, refreshed for how BC3's BC5 API train actually shipped (8 PRs merged to
master, 2026-07-18..21: #11628 BC4 wire-format compatibility, #12320 cloud files + google documents, #12321 calendars, #12322 My Notes, #12323 docs true-up, #11627 Everything feeds, #11629 doc-generation tooling, #12357 cURL examples). BC3 #10947 closed unmerged, superseded by the train — every "when #10947 merges" trigger in the registry is dead, and this PR retires them all. Companion to #308, which carries the live-canarymemoriesrule and thepairwiseDeltaAllowedwaiver pointing at the brief maintained here.Stacked on
bc5-readiness-spec-foundations(#293) — it needs thespec/api-gaps/registry that #293 creates, so this PR is based on that branch. Retarget tomainonce #293 merges.It also settles one Smithy doc comment:
GetMyNotificationsOutput.memoriesnow states the settled contract — permanently[]on BC5 perdoc/api/sections/my_notifications.md(codified by BC3 #11628: an always-empty placeholder superseded bybubble_ups), with BC4 still populating it as an accepted BC4→BC5 subtractive delta. The artifacts that inherit@documentationare regenerated —openapi.json/openapi-stripped.json, TSschema.d.ts, Goclient.gen.go, Ruby types; Python/Kotlin/Swift output is unchanged.Registry statuses after the train
memories-emptied-regressionaddressed-in-bc3-pr-11628my_notifications.md); the@bubble_upsalias never shipped; #10947 closed unmerged. The #308 canary waiver is now permanent — the machine-readable record of the accepted delta. New bubble-up surface (bubble_ups_count,scheduled_bubble_ups_count,limit_bubble_ups,GET /my/readings/bubble_ups.json) noted as future absorption items.everything-aggregatesaddressed-in-bc3-pr-11627/messages,/comments,/checkins,/forwards,/files,/boosts). No/documents.jsonroot (documents surface via/files.json). Bare/todos.json//cards.jsonare HTML shells;/recent.jsonpaths stay internal-never-model. Bucket-grouped filter feeds vs flat roots documented.activity-timelineaddressed-in-bc3-pr-11629GET /reports/progress.json(bare array), projectGET /projects/:id/timeline.json(bare array), personGET /reports/users/progress/:id.json({person, events}object). A BC4-era contract (documented since #9981) BC5 kept; #11629 re-verified it against live BC5. SDK already models all 3 routes — remainder is additive fields (15-valuekindvocabulary, schedule-entrydatastruct,avatars_sample,attachments).calendaraddressed-in-bc3-pr-12321doc/api/sections/calendars.mdshipped (show + update).scratchpadaddressed-in-bc3-pr-12322/my/notes.json(my_notes.md).step-top-levelabsorbed-in-sdkspec/basecamp.smithy(GetCardStep :4456, CreateCardStep :4479, UpdateCardStep :4511, SetCardStepCompletion :4541, RepositionCardStep :4569) withdue_on+assignee_idson create/update — matchingcard_table_steps.md. Legacyassigneescomma-string deliberately unmodeled.recordable-subtypes-docpartial-coverage(kept)search-filter-additionspartial-coverage(kept)todoset-completed-list-visibilityambiguous(kept)stack-doc-and-smithyconfirmed-not-api-resource(kept)typestaysStack. Still no JSON contract on either branch.rich-text-project-attachableno-json-contract(kept)rich_text.md: no Project-as-attachable contract (only Person-mention prose references projects).recording-bubbleupable-fieldno-json-contract(kept)bubbleupableappears nowhere indoc/api/onmaster.README.mdstatus table + footnote updated to the post-train registry.COORDINATION.mditem 1 (memories) settled as permanent-by-contract; item 2 (app_todoslists_urltypo atapp/views/api/todosets/_todoset.json.jbuilder:28) re-verified 2026-07-21 — still only the typo, no alias shipped, no SDK action needed.Verification
make validate-api-gaps— clean (12 entries).everything-aggregates.mdfrontmatter route set diffed against the 17START GETmarkers in mergeddoc/api/sections/everything.md— exact match; same for the 3timeline.mdroutes.spec/,COORDINATION.md, README: no stale head pins (589b1970/9dc63e2e), no 18-op or/documents.json-root claims, no #10947-as-pending framing, no "temporary" waiver framing outside historical narrative.spec/basecamp.smithymemoriesdoc comment settled + regenerated;make checkgreen (includessmithy-check,go-check-drift,kt-check-drift,behavior-model-check, conformance,validate-api-gaps).