branch
fork_at_timestamp
Fork a new branch from a retained source timestamp.
db.branches.fork(source: 'str', name: 'str', *, version: 'Optional[int]' = None, timestamp: 'Optional[int]' = None) -> 'Any'wire branch_fork_at_timestamp
Forks a new branch anchored at a retained source timestamp (microseconds, on Strata's logical commit clock). The engine resolves the timestamp to the covering retained commit; the returned parent lineage records both the fork timestamp and the resolved fork version. A timestamp outside retained history fails with `history_unavailable.engine.persistence_history`.
This command has no dedicated CLI verb: the CLI expresses it as `strata branch fork <SOURCE> <BRANCH> --timestamp <TIMESTAMP>` (one shared `branch fork` verb routes to all three fork commands, so only `branch.fork` owns the CLI path). It remains fully reachable through the generic wire surface - `strata command run`, MCP, and SDKs.
Successful mutations return an acknowledgement of the outcome: for a state-changing write, the affected target with the mutation effect and commit facts; for mutations that produce a domain result (such as a branch or a promotion outcome), that result object.
To see the complete help for this command, run:
help(db.branches.fork)
Example
Fork a branch at an earlier commit timestamp - time-travel into a branch.
_ = db.branches.fork("default", "experiment")sorted(b.name for b in db.branches.list())
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| branch | string | yes | Destination branch name. |
| source | string | yes | Source branch name. |
| timestamp | integer | yes | Source timestamp in microseconds. |
Returns
StatusResponse<BranchItem>
- dataBranchItem
- typestring
Errors
Recover by code. Retry policy and commit outcome come from the shipped error registry.
| Code | Retry | Commit outcome |
|---|---|---|
| failed_precondition.engine.runtime_closed | never | not_started |
| not_found.engine.branch | never | not_applicable |
| invalid_argument.engine.branch_name | never | not_started |
| invalid_argument.engine.branch_name_reserved | never | not_started |
| already_exists.engine.branch | never | not_started |
| history_unavailable.engine.persistence_history | after_state_change | not_applicable |