Skip to content

Port RunID from the archive; add internal/clock (part of #702) - #714

Merged
rustyeddy merged 2 commits into
mainfrom
feat/702-runid
Nov 21, 2026
Merged

rustyeddy merged 2 commits into
mainfrom
feat/702-runid

Conversation

@rustyeddy

@rustyeddy rustyeddy commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

Part of #702. First step only: the RunID the journal will use. #702 stays open for the run directories, events, EMAX example and parity.

What

internal/id is copied from _archive/internal/id and trimmed, as agreed on #702. _archive itself is untouched (it stays the reference):

  • internal/id/internal/ulid: the ULID encoding, unchanged.
  • RunID: text form run_<26-char ULID>; ParseRunID, MustParseRunID, String, IsZero, Equal, Time (the creation instant), text and JSON marshaling. The zero value is unset and refuses to marshal; the all-zero ULID is refused on parse.
  • Generator: monotonic within a millisecond, safe for concurrent use, reports ErrEntropyExhausted. If the clock steps backwards it carries on from the last millisecond it used instead of failing (an NTP correction must not stop a run getting an ID; uniqueness and order matter more than an exact timestamp during an adjustment). The archived ErrClockMovedBackward is gone. Random (crypto/rand) and the seeded Deterministic are the entropy sources.
  • internal/clock: Clock() time.Time is the one place Trader reads the time. NewGenerator takes a func() time.Time (clock.Clock in production, a fixed function in tests), so a Trader clock of its own can replace Clock's body later without touching callers. The archived clock.Clock interface (real and simulated, about 1,700 lines with tests) is not ported.

Not ported

The other six ID kinds, Metadata / Source and the Parse* / Generate* wrappers for them, and the archived third-party-library architecture test (replaced by a small import test). Order ids stay the broker's (sim-1); more kinds can come when something needs a generated identity for them. _archive/internal/id still holds all of it as the donor for those kinds.

Tests

Parse round trip and every rejection (wrong prefix, bad body, all-zero, trailing text); zero value; Equal; Time to the millisecond; text and JSON round trips as a string; generator monotonic order (same and advancing milliseconds), entropy error, exhaustion, a clock stepping back (still increasing, stamped with the last millisecond, follows the clock again once it passes), concurrent uniqueness; the seeded sequence reproduces; Clock is UTC without a monotonic reading; the package imports only the standard library and its ULID. make check passes. Nothing calls it yet.

🤖 Generated with Claude Code

internal/id keeps the ULID encoding, the monotonic Generator, Random and the seeded
Deterministic entropy source, and RunID with its text and JSON forms. The other
six kinds, Metadata and the clock.Clock interface are not ported. The Generator
takes a func() time.Time; internal/clock.Clock is the one place that reads the
time.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 21, 2026 20:11

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

Copy link
Copy Markdown
Owner Author

Review of PR #714 (RunID + clock only): overall this is a reasonable, contained first increment. It reuses the archived ULID code and avoids bringing back the seven-ID framework or simulated-clock machinery. I see no reason to block it on the rest of journaling, but please address the following.

Must fix — PR description will close #702 prematurely. The body includes Closes #702 even though it explicitly says this is only Part 1 and nothing uses RunID yet. Remove Closes #702; retain only Part of #702. #702 must remain open for run directories, events, EMAX, and parity.

Should simplify — archive preservation. The diff deletes several files in _archive/internal/id while saying this was a git mv port. Since _archive is our reference implementation, consider copying just the required pieces into internal/id and leaving the archive untouched. Avoid rewriting the archive in a feature whose purpose is to reuse it.

One correctness/design question — wall clock moving backwards. Generator.RunID returns ErrClockMovedBackward when the system clock steps backwards. With internal/clock.Clock using time.Now(), an NTP correction could make an otherwise valid run fail to acquire an ID. For a journal directory identifier, uniqueness is more important than refusing a temporary backward time adjustment. Please either justify this as deliberate operational policy or minimally handle rollback by continuing from the last millisecond. No elaborate clock subsystem.

Minor — deterministic entropy in production package. Deterministic and NewDeterministic are only used by tests for now. They're inherited from the archive; acceptable, but avoid adding more public test scaffolding until actual callers need it. The Clock() time.Time function is appropriately small.

Tests: Good coverage of text/JSON encoding, concurrency, monotonic IDs, bad inputs, clock normalization. After the PR description fix and clock-policy decision, I am comfortable merging this as a standalone first step. The next PR still needs to prove that a service-initiated backtest uses it and journals every run.

…millisecond (#702)

The port copies instead of moving, so _archive/internal/id is as it was. The
Generator no longer fails when the clock steps back: it carries on from the last
millisecond it used, so a run can always get an ID and IDs still sort in order.
ErrClockMovedBackward is gone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@rustyeddy

Copy link
Copy Markdown
Owner Author

Addressed in d511c26 (not merged).

  • Closing keyword: removed. The PR closing keyword workflow appends Closes #702 on open because the branch is feat/702-…; I removed it from the body, which only the opened event re-checks. Trader: journal every run with durable RunID results (first increment) #702 stays open. (Worth a thought: that workflow has no opt-out for a partial PR.)
  • Archive: copied, not moved. _archive/internal/id is restored; git diff origin/main -- _archive is empty.
  • Clock stepping back: no longer an error. The generator continues from the last millisecond it used, so a run can always get an ID and IDs still sort in order; once the clock passes that millisecond it follows it again. ErrClockMovedBackward is removed, and a test covers 5 ms → 2 ms → 9 ms.
  • Deterministic: kept; the journal tests in the next PR use it (fixed time plus seeded entropy), and I won't add more test scaffolding until a caller needs it.

make check passes.

Copy link
Copy Markdown
Owner Author

Re-review at d511c26: ready to merge from my review. All three requested changes are addressed: the closing keyword is removed (so #702 remains open), _archive/internal/id is preserved, and the generator handles backward wall-clock adjustments while retaining monotonic ULIDs. The rollback test covers the expected behavior. Scope remains limited to RunID and internal/clock, with no journaling framework added prematurely. Claude reports make check passing; I verified the updated diff and tests but did not independently execute the suite. No further changes requested on #714. Next: wire this into a Trader-owned journal in the following PR.

@rustyeddy
rustyeddy merged commit a2d1475 into main Nov 21, 2026
1 check passed
@rustyeddy
rustyeddy deleted the feat/702-runid branch November 21, 2026 20:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Trader: journal every run with durable RunID results (first increment)

2 participants