Bourse.OptionReadiness (bourse v0.1.0)

Copy Markdown View Source

Executable four-venue option readiness matrix (task 402).

Collects timestamped evidence for Deribit, OKX, Bybit and Derive across option discovery, Greeks, portfolio reads, order lifecycle, preflight and hedge. Emits a durable report that links the captured evidence behind every cell and venue status.

Classification of client_broken versus venue_degraded is an explicit AI judgment over the captured evidence — never an automatic disposition table. Pure mechanical rules still own empty books (market_unavailable), complete fill cycles (fill_ready), and proven create/fetch/cancel with a documented limitation (order_lifecycle_ready).

Short-side sell → margin → buyback readiness is orthogonal to the scalar venue status: inject short_evidence through run(evidence: …) and read capabilities.short_fill_ready / side_status.short. It never becomes another winner in the single-status precedence table, so a venue may be both buy-fill-ready and short-fill-ready.

Summary

Types

cell_name()
judgment()
status()
venue()

Functions

accept_baseline?(report)

Returns whether a report may become an accepted baseline.

apply_judgment(row, judgment)

Applies an explicit AI judgment of client_broken or venue_degraded.

baseline_rejection_reasons(report)

Explains baseline rejection reasons (empty list when acceptable).

cells()

Returns the ordered evidence cells collected per venue row.

classify_status(row)

Derives the mechanical venue status from cell evidence.

collect_venue(venue, opts \\ [])

Collects one venue row. Missing credentials fail with exact setup instructions.

judgment_statuses()

Statuses that may only be assigned by explicit AI judgment.

run(opts \\ [])

Runs the matrix for every venue and returns a durable report.

statuses()

Returns the closed venue-status vocabulary.

venues()

Returns the four option venues covered by the matrix.

write_report(report, path)

Serializes a report to a JSON file and returns the absolute path.

Types

cell_name()

@type cell_name() :: atom()

judgment()

@type judgment() :: %{
  :status => :client_broken | :venue_degraded,
  :rationale => String.t(),
  :judged_at => integer(),
  optional(:judge) => String.t()
}

status()

@type status() :: atom()

venue()

@type venue() :: String.t()

Functions

accept_baseline?(report)

@spec accept_baseline?(Bourse.OptionReadiness.Report.t()) :: boolean()

Returns whether a report may become an accepted baseline.

Any broken or untested cell rejects acceptance. Judgment-pending rows that still lack an assigned status also reject.

apply_judgment(row, judgment)

@spec apply_judgment(Bourse.OptionReadiness.VenueRow.t(), judgment()) ::
  {:ok, Bourse.OptionReadiness.VenueRow.t()} | {:error, Bourse.Error.t()}

Applies an explicit AI judgment of client_broken or venue_degraded.

Mechanical collectors never assign those statuses. The judgment must cite a non-empty rationale and timestamp; empty rationale is rejected.

baseline_rejection_reasons(report)

@spec baseline_rejection_reasons(Bourse.OptionReadiness.Report.t()) :: [String.t()]

Explains baseline rejection reasons (empty list when acceptable).

cells()

@spec cells() :: [cell_name()]

Returns the ordered evidence cells collected per venue row.

classify_status(row)

@spec classify_status(Bourse.OptionReadiness.VenueRow.t() | map()) ::
  {:ok, status()} | {:pending_judgment, String.t()}

Derives the mechanical venue status from cell evidence.

Never returns :client_broken or :venue_degraded — those require apply_judgment/2. Returns {:pending_judgment, reason} when captured evidence needs human/AI classification.

collect_venue(venue, opts \\ [])

@spec collect_venue(
  venue(),
  keyword()
) :: {:ok, Bourse.OptionReadiness.VenueRow.t()} | {:error, Bourse.Error.t()}

Collects one venue row. Missing credentials fail with exact setup instructions.

judgment_statuses()

@spec judgment_statuses() :: [status()]

Statuses that may only be assigned by explicit AI judgment.

run(opts \\ [])

@spec run(keyword()) ::
  {:ok, Bourse.OptionReadiness.Report.t()} | {:error, Bourse.Error.t()}

Runs the matrix for every venue and returns a durable report.

Options:

  • :venues — subset of venues/0 (default: all four)
  • :observed_at — wall-clock override (milliseconds)
  • :report_dir — report directory (default: tmp/option_readiness)
  • :mutate — when true, attempt create/fetch/cancel lifecycle probes
  • :collect — when false, only assemble injected :evidence maps

  • :evidence — %{venue => %{cell => cell_map | Cell.t()}} injection map. Optional top-level keys per venue: fill_evidence, short_evidence, limitation, book, judgment, environment, host.

  • :judgments — %{venue => judgment()} explicit AI judgments
  • :exchanges — %{venue => Exchange.t()} prebuilt exchanges (tests)
  • :request_opts — %{venue => keyword()} per-venue HTTP opts

statuses()

@spec statuses() :: [status()]

Returns the closed venue-status vocabulary.

venues()

@spec venues() :: [venue()]

Returns the four option venues covered by the matrix.

write_report(report, path)

@spec write_report(Bourse.OptionReadiness.Report.t(), Path.t()) ::
  {:ok, Path.t()} | {:error, term()}

Serializes a report to a JSON file and returns the absolute path.