Skip to content

Public strategy API and strict TCP/JSON codec (#699) - #707

Merged
rustyeddy merged 2 commits into
mainfrom
strategy-api-codec-699
Nov 20, 2026
Merged

rustyeddy merged 2 commits into
mainfrom
strategy-api-codec-699

Conversation

@rustyeddy

Copy link
Copy Markdown
Owner

Closes #699

Part of the Strategy Protocol milestone (#690, ADR-094). No Account/Broker execution and no TCP listener here.

strategy (imports only marketdata, num, instrument; a test enforces it): Strategy and Warmer; the requested Order (no quantity, id, account, state or fill) with Validate(frameAt) for every static rule of ADR-094 section 6, including mandatory stop on opens, side-of-price rules, amend rules and ref.

strategy/proto: the six messages; 4-byte big-endian length framing with a limit that refuses a hostile length before reading the payload; an explicit encoder with fixed member order (golden bytes in testdata/golden); a strict decoder: exactly one UTF-8 JSON object, duplicate keys refused at any depth (encoding/json accepts them), decimal-string prices (a JSON number or exponent is refused), UTC whole-second timestamps, integers without fraction or exponent, nulls refused; order objects strict (unknown members and host-owned members such as units, accountID, state refused by name, compared ignoring case and underscores) and the register run object strict. Register.Validate and Orders.Validate(frameAt) check meaning. A decoded order without a type is market, so decode then encode is the same bytes.

Verification

  • make check clean; EMAX md5 unchanged (195e457a…).
  • Negative conformance cases N14 to N20, N26 to N28 and the amend cases are table tests; each ADR JSON example decodes and survives decode-encode-decode; the examples without defaults are JSON-equal to what Encode writes.
  • TestExternalModuleCanImportAndBuild builds a throwaway module outside this one that imports strategy, strategy/proto, marketdata, num and instrument, implements Strategy and speaks the protocol (skipped with -short; uses the local module cache, no network).
  • Rule mutations (strict orders, host-owned names, strict run, duplicate keys, UTF-8, timestamp and integer strictness, zero prices, stop side, ref length, frame limits) each fail a test.

Not here: the Go client, the host adapter and the TCP listener (#701), bridging strategy.Order to the engine's order (#703), broker feedback messages (#698). Cases N30a/N30b of the ADR (strict register run) arrive with PR #706; the decoder already implements them and is tested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP

strategy: Strategy and Warmer, the requested Order with its static
validation, boundary test (imports only marketdata, num, instrument).
strategy/proto: the six messages, 4-byte length framing with limits, an
explicit encoder with fixed member order, and a strict decoder: one UTF-8
object, no duplicate keys, decimal-string prices, UTC timestamps, strict
order objects (unknown and host-owned members refused by name) and a
strict register run object. Golden files, the ADR examples as tests and a
build of an external module that imports both packages.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP
Copilot AI balanced review requested due to automatic review settings November 20, 2026 04:26
@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.

Review of b6157af: The architecture aligns well with #699 and ADR-094: separate public requested-order API, strict order/run decoding, duplicate-key checks, decimal-string prices, and substantial negative/golden tests. I found one concrete correctness issue to fix before merge:

strategy/proto/frame.go, WriteFrame: it makes a single w.Write(frame) call and returns only err, ignoring the returned byte count. Under Go's io.Writer contract a writer can return n < len(frame), err == nil (a broken implementation, but one the caller must detect). The current function reports success even though it has emitted only part of the length-prefixed frame, leaving the peer stuck or interpreting the next frame as continuation. Please check n != len(frame) and return io.ErrShortWrite, or use a write-full loop that correctly handles short writes. Add a writer test returning a short count with nil error; the existing tests cover error-only writers, not this case.

A smaller specification consistency check: ADR-094 says register is the one message without run_id; decodeHeader currently allows run_id on register. Consider explicitly rejecting that field for register so the codec enforces the normative handshake exception.

I have not run make check here; the PR reports it passed. Re-review after the short-write fix.

@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-reviewed commit 55fea9c: both previously raised items are fixed. WriteFrame now detects n < len(frame) with no error and returns io.ErrShortWrite, covered by short-writer regression tests. decodeHeader now rejects run_id on register, matching ADR-094. The public requested-order boundary, strict JSON/run validation, golden messages and protocol frame tests remain intact. No remaining blocking findings; I recommend merging #707 after your normal checks. I did not independently execute make check in this environment.

@rustyeddy
rustyeddy merged commit 33e3ef6 into main Nov 20, 2026
1 check passed
@rustyeddy
rustyeddy deleted the strategy-api-codec-699 branch November 20, 2026 04:53
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.

Strategy Protocol: export public Strategy API and TCP/JSON codec

2 participants