feat(databases): record why a fork was taken by shefeek-jinnah · Pull Request #315 · hotdata-dev/hotdata-cli

shefeek-jinnah · 2026-09-23T11:20:44Z

Summary

Adds hotdata databases fork --description <text>, which records why a fork was taken. It uses the fork description from runtimedb #1420.

hotdata databases fork --expires-at 24h --description "what-if on Q3 pricing"

Request: the text is sent as given. The server trims it, treats a blank value as absent, and checks the 4096-byte limit and control characters. A rejected value comes back as the server's 400 message.
Output:
- fork and databases <id> print the full description, keeping line breaks.
- databases lineage shows the first line on the fork's row, in quotes, cut at 60 characters with ….
- -o json/yaml carry the full text as description.
Lineage: an ancestor entry's description explains the fork taken from that ancestor. The CLI moves it one generation down, the same way it already moves snapshot_id and forked_at, so each reason lands on the fork it explains.

Depends on

chore(deps): bump hotdata SDK to 0.19.0 #317, the SDK bump to 0.19.0. This PR is stacked on it, so its diff shows only the fork description. Merge chore(deps): bump hotdata SDK to 0.19.0 #317 first; GitHub then retargets this PR to main.
runtimedb #1420, which must be deployed before a release that includes this. Otherwise the server rejects --description.

Test plan

cargo test: 598 passed
cargo clippy --all-targets -- -D warnings and cargo fmt --check
New unit tests: request body with a description; one-line summary (multi-line, long, and multi-byte text); descriptions landing on the right generation when the lineage tree is grafted past a deleted fork
scripts/check-skills.sh fails locally on macOS bash 3.2 (it fails on main too), so CI is the check here
Manual check against a server running #1420

claude · 2026-09-23T11:22:36Z

        .collect()
 }

 /// `databases tables add` — declare a table on an existing instant database.


nit: (not blocking) This doc comment describes add_table, but the new function was inserted below it. table_declaration_body now carries the wrong summary, and add_table at line 1002 carries none. Every other command function in this file opens with its databases ... doc line. Move this line down to add_table.

No longer applies. table_declaration_body moved to its own PR, #316, and this PR no longer touches add_table.

claude · 2026-09-23T11:22:38Z

 /// One `id (name) — root, forked <date>, snapshot <n>, deleted` line of the
 /// lineage tree and the `forked_from:` rows. The id leads: it's the only field
 /// guaranteed present, and the handle every other databases command accepts.
+/// Longest description shown on a one-line lineage row; the full text is in


nit: (not blocking) The lineage_row doc comment sits above this constant, so the two comments merge into one block. DESCRIPTION_SUMMARY_CHARS gets a wrong first sentence, and lineage_row at line 2366 gets no doc comment. Move the constant and its own comment above the lineage_row doc block.

Fixed in 9b1c19c, same change as the later thread.

claude · 2026-09-23T11:22:44Z

+                .as_ref()
+                .and_then(|f| f.description.as_deref())
+            {
+                println!("description: {}", indent_continuation(d, 13));


nit: (not blocking) fork --output table prints the description twice. LineageEntry::from(ForkedFrom) copies description, so lineage_row already appends the quoted summary to the forked_from: row above. The databases <id> view duplicates it the same way at line 1814. Set description: None on the entry passed to lineage_row at both call sites, so the summary stays exclusive to databases lineage.

Fixed in 9b1c19c, same change as the thread below.

codecov · 2026-09-23T11:24:24Z

Codecov Report

❌ Patch coverage is 75.92593% with 26 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/commands/databases.rs	77.35%	24 Missing ⚠️
src/main.rs	0.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

claude · 2026-09-23T11:26:13Z

+                .as_ref()
+                .and_then(|f| f.description.as_deref())
+            {
+                println!("description: {}", indent_continuation(d, 13));


nit: (not blocking) fork --output table prints the fork description twice.

LineageEntry::from(ForkedFrom) at line 2272 copies description, so lineage_row already appends the quoted summary to the forked_from: row at line 2175. The databases <id> view duplicates the same way at line 1799.

Set description: None on the entry passed to lineage_row at both call sites. The quoted summary then stays exclusive to databases lineage.

Raised in the prior review as thread #4081864125 and still present.

Fixed in 9b1c19c. The forked_from: row in both views now goes through forked_from_row, which leaves the description off, so it's printed once, on its own line. A new test covers it.

claude · 2026-09-23T11:26:21Z

 /// guaranteed present, and the handle every other databases command accepts.
+/// Longest description shown on a one-line lineage row; the full text is in
+/// `-o json`/`yaml` and on `databases <id>`.
+const DESCRIPTION_SUMMARY_CHARS: usize = 60;


nit: (not blocking) The lineage_row doc comment at lines 2324-2326 sits directly above this constant, so the two comments merge into one rustdoc block.

DESCRIPTION_SUMMARY_CHARS documents itself with a first sentence about lineage rows. lineage_row at line 2351 ends up with no doc comment, unlike every other rendering helper in this file.

Move the constant and the constant's own comment above the lineage_row doc block.

Raised in the prior review as thread #4081863422 and still present.

Fixed in 9b1c19c. The lineage_row doc comment is back on lineage_row, and DESCRIPTION_SUMMARY_CHARS keeps only its own comment.

claude

Review

Blocking Issues

src/commands/databases.rs:1023 — the constant_per_key fix described in the PR summary is absent from this head SHA.

(Posted in the summary because line 1023 is not part of the diff, so an inline comment cannot anchor to it.)

add_table still sets body["key_determines"]. table_declaration_body does not exist anywhere in src/ — rg table_declaration_body src/ returns no match. The claimed unit test asserting constant_per_key in the request body is also absent; constant_per_key appears only in the updated table-listing fixtures.

Failure scenario: a user runs hotdata databases tables add orders --key id --key-determines region. The request body carries key_determines. The add-table endpoint rejects unknown fields after runtimedb 1300, so the command prints the server 400 and exits 1. That is exactly the bug the PR summary says is fixed.

The branch was force-pushed, and the comparison against the prior review SHA reports diverged. The prior review saw table_declaration_body at line 974, so the commit carrying the rename was most likely lost in the rebase.

The SDK bump to 0.19.0 and the fixture updates did survive the rebase. Those cover response decoding only, not the request-side field name.

Action Required

Restore the key_determines to constant_per_key rename and the table_declaration_body extraction, together with the unit test named in the test plan. If the rename is intentionally deferred to another PR, remove the bug-fix section from the PR description instead.
Address or decline the two inline nits: the duplicated fork description in fork --output table and databases <id>, and the merged doc comment above DESCRIPTION_SUMMARY_CHARS. Both were raised in cycle 1 and are unchanged.

The fork-description feature itself reads correctly. description_summary cuts on character boundaries, and the generation shift in build_lineage_tree puts each reason on the fork the reason explains.

CI checks test, skills, and integration were still queued or running at review time, so those results are unknown here.

shefeek-jinnah · 2026-09-23T11:35:02Z

On the blocking item: the key_determines rename was deferred on purpose. It moved to its own PR, #316, so this PR covers only the fork description. The bug-fix section was removed from this PR's description, so the summary now matches the diff.

claude

Prior nits are fixed. forked_from_row strips the description, so both table views print it once. DESCRIPTION_SUMMARY_CHARS and lineage_row each carry their own doc comment. The description shift in build_lineage_tree follows the existing snapshot_id/forked_at rule and has a test. No blocking issues found.

CI checks other than CI / changelog had not reported at review time.

The base branch was changed.

Add `databases fork --description <text>`, backed by the fork description added in runtimedb #1420. - The description is sent as given. The server trims it, treats blank as absent, and checks length and control characters. - `fork` and `databases <id>` print the full text on its own line. `lineage` rows show the first line, cut at 60 characters. `-o json`/`yaml` carry the full text. - Lineage moves the description one generation down with `snapshot_id` and `forked_at`, since an ancestor entry describes the fork taken from it.

shefeek-jinnah requested a review from a team as a code owner September 23, 2026 11:20

shefeek-jinnah requested review from eddietejeda and removed request for a team September 23, 2026 11:20

claude Bot reviewed Sep 23, 2026

View reviewed changes

claude Bot previously approved these changes Sep 23, 2026

View reviewed changes

shefeek-jinnah dismissed claude[bot]’s stale review via 7b273a4 September 23, 2026 11:24

shefeek-jinnah force-pushed the feat/fork-description branch from c5a8bd6 to 7b273a4 Compare September 23, 2026 11:24

shefeek-jinnah mentioned this pull request Sep 23, 2026

fix(tables): send --key-determines as constant_per_key #316

Merged

3 tasks

claude Bot reviewed Sep 23, 2026

View reviewed changes

claude Bot requested changes Sep 23, 2026

View reviewed changes

claude Bot approved these changes Sep 23, 2026

View reviewed changes

shefeek-jinnah mentioned this pull request Sep 23, 2026

chore(deps): bump hotdata SDK to 0.19.0 #317

Merged

2 tasks

shefeek-jinnah force-pushed the feat/fork-description branch from 9b1c19c to a2d2974 Compare September 23, 2026 11:43

shefeek-jinnah changed the base branch from main to chore/sdk-0.19 September 23, 2026 11:43

claude Bot previously approved these changes Sep 23, 2026

View reviewed changes

Base automatically changed from chore/sdk-0.19 to main September 23, 2026 11:52

shefeek-jinnah force-pushed the feat/fork-description branch from a2d2974 to 1868e57 Compare September 23, 2026 11:58

claude Bot approved these changes Sep 23, 2026

View reviewed changes

shefeek-jinnah merged commit ab64f57 into main Sep 23, 2026
15 checks passed

shefeek-jinnah deleted the feat/fork-description branch September 23, 2026 12:05

shefeek-jinnah mentioned this pull request Sep 23, 2026

chore: Release hotdata-cli version 0.37.0 #318

Merged

Conversation

shefeek-jinnah commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Depends on

Test plan

Uh oh!

claude Bot Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

shefeek-jinnah Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

shefeek-jinnah Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

shefeek-jinnah Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

claude Bot Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

shefeek-jinnah Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

shefeek-jinnah Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Review

Uh oh!

shefeek-jinnah commented Sep 23, 2026

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

shefeek-jinnah commented Sep 23, 2026 •

edited

Loading

codecov Bot commented Sep 23, 2026 •

edited

Loading