Skip to content

docs: ADR-094 external strategy wire protocol v1 (proposed) (#694) - #697

Merged
rustyeddy merged 4 commits into
mainfrom
spec-strategy-protocol-v1-694
Nov 20, 2026
Merged

rustyeddy merged 4 commits into
mainfrom
spec-strategy-protocol-v1-694

Conversation

@rustyeddy

Copy link
Copy Markdown
Owner

Part of #690. Does not close it.

Freezes the v1 wire contract for external strategies as a Proposed ADR: packages (strategy, strategy/proto, strategy/client), length-prefixed JSON over loopback TCP, envelope, messages with golden JSON examples, state machine, requested-order rules (including amend), static versus stateful rejection, timeouts, versioning, 34 negative and 7 stateful conformance cases. Closes #694 on acceptance by the owner.

Open questions for the owner are listed at the end of the ADR (paper authorization, broker feedback design, target removal, strict order objects, defaults). The amend action is implemented in #695.

Spec only; no code. make check clean.

🤖 Generated with [Claude Code](https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP

https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP

Copilot AI balanced review requested due to automatic review settings November 20, 2026 02:45
@rustyeddy rustyeddy linked an issue Nov 20, 2026 that may be closed by this pull request

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.

@rustyeddy rustyeddy left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

ADR-094 is a substantial, useful first draft, but please fix this v1 scope contradiction before acceptance:

  1. The normative protocol and section 9 say bars only; fills/positions deferred, while the final 'Open questions' preamble says 'fills and positions are in v1' and proposes mandatory fills/rejections/positions in each bars frame. These contradict each other. Per the settled #690 decisions, keep feedback out of the first vertical slice, track its design as a later increment, and don't label it owner-approved.
  2. The amend order action and section 6 make #695 look like a prerequisite for the first worker. Rusty says stop management is fundamental but not required in the first iteration; engine and external protocol should evolve together when we tackle that feature. Separate the minimal initial subset from later amendment support rather than making it a gate.
  3. Please do not front-load all the 'Open questions' into this spec PR. Raise only the next blocking question, offer a recommended default, and follow the requested build → test → decide loop.

The framing, RunID handshake exception and validation examples are moving in the right direction. I recommend finalizing a compact base contract first.

Copy link
Copy Markdown
Owner Author

Correction to my review: I conflated the first development increment with protocol v1. Rusty's definition is that v1 is a complete milestone for real external strategy backtests, reached through multiple build/test/evaluate increments. It is therefore valid for ADR-094 to describe capabilities (such as amendments and feedback) intended to be in v1 even if not implemented by the very first PR. Please retain that distinction and show implementation staging separately.

The internal contradiction still needs resolving: the draft both defers fills/positions and says they are included in v1. Choose a consistent v1 target after the owner decides the next relevant question. Do not infer 'deferred from increment 1' means 'excluded from v1'. My prior scope objection is superseded by this clarification.

@rustyeddy rustyeddy left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Re-review at b3d9bd4: the prior v1/increment confusion and fills/positions inconsistency are now resolved. ADR-094 explicitly targets complete v1 with incremental issues, and stages feedback at #698. The protocol's envelope, registration exception, order restrictions, failure modes and conformance examples are substantially ready.

One remaining owner decision before accepting this as the normative ADR: section 6 currently says other unknown order members are ignored, while the final 'Next, for #699' question recommends rejecting every unknown order member (strict orders, tolerant envelope). Since a misspelled stop_loss or take_profit silently changes risk behavior, I recommend strict order objects and permissive additive envelope/message fields. Once Rusty confirms and the body/golden negative cases are consistent, merge recommendation: yes. No CI statuses were returned for this SHA; PR reports make check passed.

Copy link
Copy Markdown
Owner Author

Owner decision: strict order-object validation. Any unknown member in an orders[].orders[] object MUST fail the run with invalid_order; e.g. typo take_profitt must not be silently ignored. Envelope/message members outside the order object MAY remain tolerant for additive compatibility. Update ADR-094's normative section 6, negative conformance cases, and related golden examples consistently before merging. The owner reports this PR merged, but GitHub currently still returns state: open, merged: false for #697; please verify merge status.

@rustyeddy
rustyeddy merged commit 778f467 into main Nov 20, 2026
1 check passed
@rustyeddy
rustyeddy deleted the spec-strategy-protocol-v1-694 branch November 20, 2026 04:15
rustyeddy added a commit that referenced this pull request Nov 20, 2026
Reverts PRs #697, #706, #707 and #708 while preserving PR #696 engine stop amendments and ADR-093. Document historical external strategy ADR scope.
rustyeddy added a commit that referenced this pull request Nov 20, 2026
…709)

Reverts PRs #697, #706, #707 and #708 while preserving PR #696 engine stop amendments and ADR-093. Document historical external strategy ADR scope.
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.

Spec: external strategy protocol v1 wire contract (ADR-094)

2 participants