-
Notifications
You must be signed in to change notification settings - Fork 11
BC5 launch reconciliation: registry refresh for the shipped BC5 API train #325
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
5b368fc
spec(api-gaps): BC5 launch reconciliation — memories regression + sco…
jeremy 06e2d7a
spec(api-gaps): resolve #325 review threads (group count + activity s…
jeremy 287fd85
spec: align memories doc comment with the reconciliation + regenerate
jeremy c30a289
spec(api-gaps): clarify the memories waiver lives in PR #308, not thi…
jeremy f3fc0a8
docs(coordination): attribute the memories canary waiver to PR #308
jeremy e663d8a
spec(api-gaps): refresh everything-aggregates from the live #10947 co…
jeremy b36ca17
spec(api-gaps): reconcile registry with the shipped BC5 API train
jeremy 1d45eec
spec: settle memories doc comment on the documented contract + regene…
jeremy 87f6bae
api-gaps: record why bucket-scoped step aliases stay unmodeled
jeremy File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
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
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
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,70 +1,97 @@ | ||
| --- | ||
| gap: activity-timeline | ||
| status: no-json-contract | ||
| status: addressed-in-bc3-pr-11629 | ||
| detected: 2026-05-01 | ||
| sdk_demand: high | ||
| bc3_pr: 11629 | ||
| bc3_refs: | ||
| introduced_in: five | ||
| bc3_plan_phase: 3d | ||
| routes: | ||
| - GET /:account_id/activity.json | ||
| - GET /:account_id/reports/progress.json | ||
| - GET /:account_id/projects/:project_id/timeline.json | ||
| - GET /:account_id/reports/users/progress/:person_id.json | ||
|
jeremy marked this conversation as resolved.
|
||
| controllers: | ||
| - app/controllers/activity_controller.rb | ||
| - app/controllers/timelines_controller.rb | ||
| related_existing_api: [] | ||
| - app/controllers/users/timelines_controller.rb | ||
| related_existing_api: | ||
| - GetProgressReport | ||
| - GetProjectTimeline | ||
| - GetPersonProgress | ||
| --- | ||
|
|
||
| # Activity Timeline (global + per-project) | ||
| # Activity Timeline (account, project, and person) | ||
|
|
||
| ## What's missing | ||
|
|
||
| BC5 introduces a global activity feed (`/activity.json`) and per-project | ||
| timeline (`/projects/:project_id/timeline.json`) backed by an Activity | ||
| envelope. The BC3 plan Phase 3d ships both routes plus the envelope shape. | ||
| Additive fields only — the routes and base contract are documented and already | ||
| modeled. The merged `doc/api/sections/timeline.md` on `master` documents | ||
| exactly three routes: | ||
|
|
||
| Note: there is **no `/buckets/:id/timeline` route** — earlier drafts of this | ||
| brief used the wrong path. Per-project routes are keyed by `project_id`, not | ||
| `bucket_id`. | ||
| - **Account** — `GET /reports/progress.json`: a paginated bare array of | ||
| timeline events across all projects the authenticated user can access. | ||
| - **Project** — `GET /projects/:project_id/timeline.json`: the same event | ||
| shape, pre-filtered to one project, also a bare array. | ||
| - **Person** — `GET /reports/users/progress/:person_id.json`: a JSON | ||
| **object** `{person, events}` — the person plus a paginated `events` list of | ||
| timeline events they created. | ||
|
jeremy marked this conversation as resolved.
|
||
|
|
||
| These routes **predate the BC5 API train**: they are a BC4-era contract, | ||
| documented since the #9981 docs repatriation, that BC5 kept. The train PR that | ||
| re-verified and regenerated `timeline.md` against live BC5 is BC3 **#11629** | ||
| (the doc-generation tooling PR), which is what `addressed-in-bc3-pr-11629` | ||
| records here. | ||
|
|
||
| Historical corrections retained from earlier drafts: there is no | ||
| `/activity.json` route and no `/buckets/:id/timeline` route; the BC5-new | ||
| `/activity/days/:date` and `/activity/dates` sub-routes were removed in the | ||
| timeline rewrite and were never modeled here. | ||
|
|
||
| ## Why it matters | ||
|
|
||
| Activity feeds are a primary integration surface for dashboards, audit logs, | ||
| and "what's new since I last checked" tooling. Without a JSON API, consumers | ||
| have to poll individual recording endpoints and reconstruct ordering — slow, | ||
| incomplete, and incompatible with the in-app activity stream. | ||
| and "what's new since I last checked" tooling. The SDK already models all | ||
| three routes (`GetProgressReport`, `GetProjectTimeline`, `GetPersonProgress` | ||
| at `spec/basecamp.smithy:7084`, `:7105`, `:7130`, including the person-route | ||
| `{person, events}` object wrapper), so consumers can call them today — but the | ||
| event payload's typed surface lags the merged doc, leaving fields to be | ||
| consumed untyped. | ||
|
|
||
| ## Suggested API shape | ||
|
|
||
| `GET /:account_id/activity.json`: | ||
| - Pagination: Link header, `X-Total-Count`. | ||
| - Response: array of `Activity` envelope objects: | ||
| - `id` (long), `created_at`, `updated_at` | ||
| - `kind` (string — what happened) | ||
| - `recording` (polymorphic: Todo, Card, Message, etc.) | ||
| - `creator` (Person) | ||
| - `bucket` (TodoBucket-shaped, when scoped) | ||
| The remaining absorption is additive fields on the event shape, per the merged | ||
| `doc/api/sections/timeline.md`: | ||
|
|
||
| `GET /:account_id/projects/:project_id/timeline.json`: | ||
| - Same envelope, pre-filtered to the project. | ||
| - Pagination: same as global. | ||
| - `kind` — a 15-value vocabulary: `message_created`, `comment_created`, | ||
| `todo_created`, `todo_completed`, `upload_created`, `document_created`, | ||
| `schedule_entry_created`, `schedule_entry_rescheduled`, `question_created`, | ||
| `question_answer_created`, `chat_transcript_rollup`, `kanban_card_created`, | ||
| `kanban_card_completed`, `inbox_forward_created`, | ||
| `client_correspondence_created`. | ||
| - `data` — event-specific payload; for `schedule_entry_created` / | ||
| `schedule_entry_rescheduled` it carries `{all_day, starts_at, ends_at}`. | ||
| - `avatars_sample` — array of avatar URLs (used by chat rollups to show | ||
| participants). | ||
| - `attachments` — array of attached files, if any. | ||
| - Plus the documented envelope fields (`parent_recording_id`, `action`, | ||
| `target`, `title`, `summary_excerpt`, `bucket`, `creator`, `url`, | ||
| `app_url`). | ||
|
|
||
| ## Implementation notes for BC3 | ||
|
|
||
| - Activity envelope likely already exists in some form (used by web UI). BC3 | ||
| Phase 3d work makes it a documented, JSON-serialisable contract. | ||
| - Per-project timeline action lives on `timelines_controller.rb`, not on | ||
| `projects_controller`. | ||
| - `doc/api/sections/activity.md` covers both the global and per-project | ||
| routes plus the envelope shape. | ||
| Shipped — nothing pending. The account and project routes serve from | ||
| `timelines_controller.rb` and the person route from | ||
| `users/timelines_controller.rb`; `doc/api/sections/timeline.md` is regenerated | ||
| against live BC5 by the doc tooling from #11629. | ||
|
|
||
| ## SDK absorption plan when this lands | ||
|
|
||
| - New `ActivityService` with `getActivity()` (global) and | ||
| `getProjectTimeline(projectId)` (per-project). | ||
| - New shape: `Activity` envelope. | ||
| - The recording field is polymorphic — model as a union of existing recording | ||
| shapes if Smithy supports it, otherwise use a discriminated structure with | ||
| a `type` field. | ||
| - Canary fixture: include `getActivity()` once schema is stable. Pairwise | ||
| check is BC4-absent → BC5-present. | ||
| - No new operations — `GetProgressReport`, `GetProjectTimeline`, and | ||
| `GetPersonProgress` already exist with the correct paths and the | ||
| person-route object wrapper. | ||
| - Extend the timeline event shape with the additive fields above: the `kind` | ||
| vocabulary (model as an open string enum — BC3 says "common values | ||
| include", so treat it as non-exhaustive), the `data` struct for | ||
| schedule-entry events, `avatars_sample`, and `attachments`. | ||
| - Canary fixture: `GetProgressReport` exercises the account feed; pairwise | ||
| check is structural (the routes exist on both BC4 and BC5). | ||
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
Oops, something went wrong.
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.