ops

type API struct {
	// Raw is the typed endpoint layer the registered Operations call, over the
	// journaled wire client. NewAPI sets it (rawapi.New over the client). Required.
	Raw *rawapi.Client
	// Resync re-measures the server clock once when a single-shot send is
	// rejected with EXCEED_TIME_WINDOW (provably pre-execution) — the place
	// protocol's clock-resync hook (the ONLY user of this field, since that
	// protocol drives single-shot sends through its own reconcile loop rather than
	// the L1 client's retry, which corrects EXCEED_TIME_WINDOW itself). NewAPI
	// seeds it from korbit.Client.Resync — the SAME resync primitive — so the two
	// never diverge. nil disables that one corrective resync.
	Resync func() error
	// ServerNow is the server-clock estimate in unix ms, used to default the
	// history walk's lookback window (a server-relative time filter sent on the
	// wire). NewAPI seeds it from korbit.Client.ServerNowMs — the same clock the
	// client signs against. nil falls back to the local wall clock. (The journal's
	// row times do NOT use this — they are stamped by the frontend's own system
	// clock in internal/callrec.)
	ServerNow func() int64
	// Sleep is the inter-retry delay primitive for the place protocol's budgeted
	// waits; NewAPI seeds it from korbit.Client.Sleep. nil = time.Sleep.
	Sleep func(time.Duration)
	// RetryBudgetMs bounds the place protocol's total reconcile sleep and the
	// default per-call retry budget handed to idempotent passthrough calls.
	RetryBudgetMs int
	// Stderr receives the truncation notes the honesty rule emits. The frontend
	// decides whether to mirror them as structured output; ops only writes the
	// human note here. nil = io.Discard.
	Stderr io.Writer
	// Journal is the operations-ledger seam: every Operation.Run begins an
	// operation here (which makes the persist decision once, pre-send) and threads
	// the returned handle through ctx so the recording doer behind Raw groups the
	// operation's api_calls under it, and the place protocol records its order
	// intent through it. nil disables journaling (a no-op handle is used).
	Journal OpJournal
	// Log is the optional operational logger for the operation-LEVEL decisions the
	// wire layer below cannot see. NewAPI seeds it from the client's own logger
	// (one wiring per surface); set it afterwards only to give ops a distinct
	// logger. It covers: the place reconcile protocol's send/resend/
	// duplicate/lookup trail and final verdict, and the history/candles paging
	// summary. nil = silent (resolved once via logging.Or). Decisions and outcomes
	// (including the final verdict) log at Debug and per-iteration detail at Trace;
	// nothing logs at Warn here, because every money-unsafe verdict
	// (UNKNOWN/placed-but-unreadable/duplicate-placed) ALREADY reaches the user as
	// program output (the returned error + the guidance note), so re-emitting it on
	// the operational log would only duplicate that on the shared stderr sink — the
	// Debug line is the structured copy for the combined --log-file trail. It NEVER
	// logs a secret: only non-sensitive request facts (clientOrderId, symbol, side)
	// and outcomes (price/qty ride the journal, not the log). A single-call
	// passthrough is left to the wire layer's own log, so a routine read adds no
	// ops line.
	Log *slog.Logger
}

type BookLevel struct {
	Price string
	Qty   string
}

type Controls struct {
	SkipReconcile bool   // honored only by the place operation; ignored elsewhere
	Surface       string // the frontend identity for the operations ledger: cli|monitor|mcp
}

type OpHandle interface {
	// OperationID is the operations row id (0 when not recording).
	OperationID() int64
	// ForCall returns a per-api_call recorder bound to this operation, assigning
	// the next 1-based sequence within it. orderedParams overrides the recorded
	// params_json with the spec/insertion order ("" keeps the wire client's). It
	// returns nil when the operation is not recorded; the wire client treats a nil
	// Recorder as "do not record", so the send still proceeds.
	ForCall(orderedParams string) korbit.Recorder
	// StartOrder records the order's mint-time intent BEFORE the placement send
	// (the hard pre-send guarantee) and returns the finish hook. An error aborts
	// the placement with nothing on the wire.
	StartOrder(OrderIntent) (OrderFinishFunc, error)
	// Finish folds the operation result into its ledger row. The api_calls count
	// is the handle's own (it counted every ForCall) and the finish time comes from
	// the frontend's own clock, so callers pass only the outcome. A finish-write
	// failure is diagnostic, not a money-safety signal; it is returned for the
	// caller to surface or warn as its surface dictates.
	Finish(outcome, errorCode string) error
}

type OpJournal interface {
	Begin(OpStart) (OpHandle, error)
}

type OpMeta struct {
	ID          []string // command path segments, e.g. {"order","place"}
	Method      string   // REST method the operation maps to: GET | POST | DELETE
	Path        string   // REST path the operation maps to, e.g. /v2/orders
	Section     cmdmeta.Section
	Summary     string
	Params      []cmdmeta.Param
	Positionals []cmdmeta.Positional
	Notes       []string
	Examples    []string
	// ExperimentalNotes / ExperimentalExamples document an opt-in, not-yet-stable
	// feature; plain `--help` hides them and --enable-experimental reveals them
	// (the machine catalog always includes them). No endpoint operation is
	// experimental today — the fields exist so the unified surface stays symmetric
	// with the builtin spec.
	ExperimentalNotes    []string
	ExperimentalExamples []string
	Response             []cmdmeta.ResponseField
	Auth                 *cmdmeta.Auth // nil = public
	Safety               cmdmeta.Safety
	Destructive          bool // MCP destructive hint (money-movers + cancels)
	// CrossValidate applies cross-field rules after per-value normalization; nil
	// = none. values is keyed by API parameter name (post-normalization).
	CrossValidate func(values map[string]string) error
}

type OpStart struct {
	OpID     string // dotted operation id, e.g. "order.place"
	Surface  string // the frontend that issued it: cli|monitor|mcp|...
	Safety   cmdmeta.Safety
	Auth     bool
	KeyName  string
	APIKeyID string
}

type Operation interface {
	Meta() OpMeta
	Run(ctx context.Context, a *API, in RunInput) (Result, error)
}

type OrderFinishFunc func(status, orderID, errorCode string, attempts int)

type OrderIntent struct {
	ClientOrderID string
	Symbol        string
	Side          string
	OrderType     string
	Price         string
	Qty           string
	Amt           string
	Tif           string
	ParamsJSON    string
}

type PlaceSimulation struct {
	// Disclaimer is always set and states plainly that this is an estimate.
	Disclaimer string `json:"disclaimer"`

	BestBid     string `json:"bestBid"`
	BestAsk     string `json:"bestAsk"`
	Mid         string `json:"mid"`
	NotionalKRW string `json:"notionalKrw,omitempty"`

	// EstPegPrice is the price a best (BBO) order derives from the current book —
	// its --best-nth level on the side its tif selects. Empty for non-best orders
	// and when that level is not visible in the book.
	EstPegPrice string `json:"estPegPrice,omitempty"`

	// Marketable is true when the order (or a limit's crossing portion) would
	// take liquidity immediately. The Est* fields describe that simulated taker
	// fill; they are empty for a non-crossing limit (which rests in full).
	Marketable        bool   `json:"marketable"`
	EstFilledQty      string `json:"estFilledQty,omitempty"`
	EstFilledQuote    string `json:"estFilledQuoteKrw,omitempty"`
	EstAvgFillPrice   string `json:"estAvgFillPrice,omitempty"`
	EstWorstFillPrice string `json:"estWorstFillPrice,omitempty"`
	EstSlippagePct    string `json:"estSlippagePct,omitempty"`

	// FullyFilled reports whether the whole order size is covered by the visible
	// marketable book.
	FullyFilled bool `json:"fullyFilled"`
	// EstRemainingQty is the base quantity that would NOT fill immediately;
	// Disposition says what becomes of it (rests as a maker limit, or is canceled
	// for a market/IOC order). It is omitted only for a market BUY (quote-sized, so
	// a base remainder is undefined — Disposition explains); a best BUY is
	// base-sized (amt is converted to qty at the peg) and does report it.
	EstRemainingQty string `json:"estRemainingQty,omitempty"`
	Disposition     string `json:"remainingDisposition,omitempty"`
}

type PlaceWarning struct {
	// Code is a stable symbolic identifier an agent can branch on.
	Code PlaceWarningCode `json:"code"`
	// Message is the human-readable warning in English, rendered from Format and
	// Args. It is the value shipped in the `--json` contract.
	Message string `json:"message"`
	// Format and Args are the un-rendered message: Format is the English template
	// (printf %s verbs only) and Args its interpolation values, with Message equal
	// to fmt.Sprintf(Format, Args...). They let a consumer re-render the message
	// its own way — fmt.Sprintf for English, or a localizing printer keyed on the
	// Format string for another language — so this layer needs no localization
	// dependency of its own. Not part of the JSON contract (localization is a
	// display concern of the consumer, not the wire shape agents read).
	Format string `json:"-"`
	Args   []any  `json:"-"`
}

type PlaceWarningCode string

type Result struct {
	Data      json.RawMessage
	Truncated bool
	Note      string
	Attempts  int
	// JournalErr is an OUT-OF-BAND operations-ledger write failure (the Finish
	// folding the operation outcome into its ledger row failed). It is never the
	// operation's own success/failure — a frontend surfaces it the way it surfaces
	// the other journal errors (the cli joins it and fails after the result; the
	// warn-policy surfaces have already warned and leave it nil).
	JournalErr error
}

type RunInput struct {
	Values   map[string]string // validated values keyed by API name
	Controls Controls
	// KeyName / APIKeyID identify the signing key for the operations ledger (the
	// public api-key id; never a secret). "" for a public operation. They feed
	// only the journal — signing credentials live on the wire client behind Raw.
	KeyName  string
	APIKeyID string
}

type TickBand struct {
	PriceGte string
	TickSize string
}