Archive the authoring component on order events

[outerlook]

Seven separate components place orders on one shared venue account. An archived
order_events row currently cannot say which of them authored the order:
account_selector is derived broker-side from the selected account label, so it is
identical across all of them by construction, and the client order id format is fully
spent at 36 characters.

This adds an optional, caller-declared author identity and archives it as a first-class
read key.

Changes

• orderAuthor is an optional member on both CreateOrderPayloadSchema and
  CallPayloadSchema, so the typed CreateOrder path and the Action.Call
createOrder path (used for funding passive orders) both accept it.
• It threads through the shared OrderTelemetryContext, so both paths and both their
  success and failure archive branches carry it from one insertion point.
• Archived as order_author LowCardinality(String) DEFAULT '' on order_events, via a
  CREATE plus an idempotent ALTER ... ADD COLUMN IF NOT EXISTS, following the
  client_withdrawal_id column added in 0.2.32.
• The dedup keys for order_events and fill_events are now documented as schema
  comments, including that fill_index is not a stable identifier.

Shape notes

The author travels as a declared payload field, matching orderIntent and
passivePlacementOutcome. gRPC metadata was not used: that channel is reserved for
credential and account routing.

It is resolved only from the caller context, deliberately skipping the
firstString(record, info, ...) fallback chain that clientOrderId uses. The author is
caller-declared and never echoed by the venue, so a venue-side fallback could only
introduce noise.

It is archive-only and is never forwarded into the venue order params. There is a test
asserting exactly that.

Reviewer notes

• No producer sets the field yet. It is optional end-to-end and archives as "" when
  absent, so this can land ahead of any caller.
• Rows originating from the WebSocket user stream will carry order_author = '': a
  venue push has no caller context and the broker holds no order-id-to-author map. The
  author is therefore present on the create-time row only, and attribution should join
  back to that row by order_id.
• The ALTER still has to be applied to the target database; merging this does not
  apply it.
• This is a third additive divergence from the published consumer contract; the
  existing comment in rows.ts enumerating those has been updated.

Checks

• bun test — 477 passed, 0 failed
• bun run build:ts (tsc) — clean
• bun run lint (biome) — clean, warnings are pre-existing

Summary by CodeRabbit

• New Features

  • Added optional order author information to order and treasury actions.
  • Order author details are now captured in execution telemetry and archived order events.
  • Existing deployments automatically receive the new archive field.

• Bug Fixes

  • Improved archive deduplication guidance and clarified the 24-hour event lookback behavior.
  • Ensured missing order author values are stored consistently as empty values.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bbdffd3d-5ce1-44c0-9f04-e56f656dc889

📥 Commits

Reviewing files that changed from the base of the PR and between 7b8e0be and 79dcca6.

📒 Files selected for processing (7)

• schema/clickhouse/broker_execution.sql
• src/handlers/execute-action/orders.ts
• src/handlers/execute-action/treasury-call.ts
• src/helpers/broker-execution-archive/rows.ts
• src/helpers/order-telemetry.ts
• src/schemas/action-payloads.ts
• test/broker-execution-archive.test.ts

📜 Recent review details

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2026-04-14T06:47:01.283Z

Learnt from: csmithington
Repo: usherlabs/cex-broker PR: 38
File: src/client.dev.ts:0-0
Timestamp: 2026-04-14T06:47:01.283Z
Learning: In this codebase, gRPC action constants such as `FetchTicker`, `FetchFees`, and `FetchAccountId` should be sourced from `src/helpers/constants.ts` and imported from there (e.g., used by both `src/client.dev.ts` and `src/server.ts`). Do not import or reference generated proto TypeScript artifacts (for example `./proto/cex_broker/Action`), since those generated files are git-ignored and won’t be available/committed consistently.

Applied to files:

• src/handlers/execute-action/treasury-call.ts
• src/handlers/execute-action/orders.ts
• src/helpers/order-telemetry.ts
• src/schemas/action-payloads.ts
• src/helpers/broker-execution-archive/rows.ts

📚 Learning: 2026-07-28T20:08:24.163Z

Learnt from: outerlook
Repo: usherlabs/cex-broker PR: 84
File: schema/clickhouse/broker_execution.sql:102-102
Timestamp: 2026-07-28T20:08:24.163Z
Learning: For this repo’s ClickHouse schema files (under schema/clickhouse), remember that archive-forwarder runs each top-level SQL statement on startup. Make schema changes idempotent: when adding additive columns to tables that may already exist, use an idempotent `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` placed next to the related `CREATE TABLE IF NOT EXISTS` (rather than relying on `CREATE TABLE IF NOT EXISTS`, which does not alter existing tables).

Applied to files:

• schema/clickhouse/broker_execution.sql

🔇 Additional comments (8)

src/schemas/action-payloads.ts (1)

41-48: LGTM!

Also applies to: 79-90

src/helpers/order-telemetry.ts (1)

13-27: LGTM!

Also applies to: 29-57, 171-171

src/handlers/execute-action/orders.ts (1)

149-161: LGTM!

Also applies to: 185-197

src/handlers/execute-action/treasury-call.ts (1)

85-97: LGTM!

src/helpers/broker-execution-archive/rows.ts (1)

282-314: LGTM!

Also applies to: 361-366

schema/clickhouse/broker_execution.sql (2)

18-30: Idempotent migration correctly applied.

The ALTER TABLE ... ADD COLUMN IF NOT EXISTS mirrors the CREATE TABLE column type, default, and position, matching the required pattern for archive-forwarder startup re-runs.

Based on learnings, "when adding additive columns to tables that may already exist, use an idempotent ALTER TABLE ... ADD COLUMN IF NOT EXISTS placed next to the related CREATE TABLE IF NOT EXISTS" — this change complies.

Also applies to: 76-78

Source: Learnings

---

29-30: 🚀 Performance & Scalability | 💤 Low value

Confirm order_author stays low-cardinality by convention, not enforcement.

order_author is caller-declared free text with no upper bound or allow-list, while LowCardinality(String) degrades once a column's distinct-value count grows well past ~10,000 (dictionary bloat, lost compression). Current callers use small labels like "maker-alpha"/"funding-executor", but nothing prevents a future caller from passing high-cardinality values (e.g., per-order identifiers).

test/broker-execution-archive.test.ts (1)

671-780: LGTM!

---

Walkthrough

Changes

The PR adds optional orderAuthor validation and telemetry propagation, archives it as order_author in ClickHouse order events, adds an idempotent migration, and tests order and treasury-call paths including absent values.

Order author archive plumbing

Layer / File(s)	Summary
Author payload and telemetry contracts src/schemas/action-payloads.ts, src/helpers/order-telemetry.ts	Payload schemas and telemetry models accept optional non-empty orderAuthor values and preserve them in generated telemetry.
Handler propagation and archive row src/handlers/execute-action/orders.ts, src/handlers/execute-action/treasury-call.ts, src/helpers/broker-execution-archive/rows.ts	Order and treasury handlers pass orderAuthor into telemetry contexts, and archive rows emit order_author with an empty-string fallback.
Order events schema migration and read contract schema/clickhouse/broker_execution.sql	order_events declares and migrates order_author; ClickHouse documentation records updated deduplication semantics.
Archive row and integration validation test/broker-execution-archive.test.ts	Tests cover populated and absent authors, order and treasury-call plumbing, archived values, and exclusion from venue parameters.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• usherlabs/cex-broker#41: Overlaps with the order telemetry model and builder.
• usherlabs/cex-broker#79: Touches the same create-order handler and payload schema paths.
• usherlabs/cex-broker#81: Overlaps with treasury createOrder telemetry and archive plumbing.

Suggested reviewers: csmithington, xlassix

Poem

A rabbit logs an author’s name,
Through order paths and archive lanes.
Empty fields stay neatly clear,
Treasury trails are captured here.
ClickHouse hops the schema run—
Tests applaud: the work is done! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly points to archiving order authorship on order events, which matches the main change.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/order-archive-authorship

---

_{Comment @coderabbitai help to get the list of available commands.}