Conventions¶

Every tool obeys these rules. A tool contract that disagrees with this page is wrong and should be fixed.

Identifiers¶

Identifier	Form	Notes
`event_id`	integer	Catalogue event
`pick_id`	integer	Catalogue pick
`station_id`	`NET.STA`	SEED network and station. Never a bare station code
`channel_id`	`NET.STA.LOC.CHA`	Empty location code is `""`
`tool_call_id`	`tc-NNNN`	Server-assigned, sequential in the session. The citation key
`group_id`	small integer	A candidate grouping inside one `reassociate` result
`pick_index`	small integer	Position of a pick inside one `guided_repick` result
`snapshot_id`	`<source>-<yyyy-mm-dd>`	Frozen bulletin snapshot

Time and units¶

Instants are ISO-8601 UTC with an explicit Z and millisecond precision: 2024-06-15T08:12:03.417Z. Instant fields end in _utc. Durations and offsets end in _s.

Units live in the field name: _km, _m, _deg, _s, _hz, _db, _nm, _counts, _pct, _ml. Probabilities are in 0..1 and carry no suffix. Filter bands are "lo-hi" in Hz, or "none".

`null` versus absent¶

null means measured or tested, and undetermined (depth unconstrained; magnitude below the two-station minimum). Absent means not applicable, not requested, or withheld by the session's view. 0, -1, "", and "n/a" are not sentinels.

References¶

Catalogue-bearing values are passed by reference, not by free-form numbers.

origin_ref:

{ "kind": "catalog",  "event_id": 1001 }
{ "kind": "solution", "tool_call_id": "tc-0011" }
{ "kind": "solution", "tool_call_id": "tc-0014", "group_id": 2 }
{ "kind": "value",    "origin_time_utc": "…", "latitude_deg": 47.15,
  "longitude_deg": 24.50, "depth_km": 10.0, "magnitude_ml": null }

kind: value is allowed only where a contract says so. It marks the result catalogue_bearing: false and adds warning by_value_origin.

pick_ref:

{ "kind": "catalog", "pick_id": 20001 }
{ "kind": "repick",  "tool_call_id": "tc-0018", "pick_index": 0 }

picks_spec is the phase set a solution tool works on: a base (catalog / solution / none), phase_set all or p_only, optional exclude_pick_ids, and optional add_picks from earlier re-picks. The resolved pick list is always in resolved_request.

Unknown or failed ids return E_UNKNOWN_REF.

Selection bounds¶

event_id, stations, time windows, and areas select what to look at. They are always allowed by the contract and always bounded. Exceeding a bound is E_WINDOW_TOO_LARGE. An event-bound session may only reference its subject (E_POLICY).

Bound	Limit
`get_station_status` window	24 h
`query_external_catalog` window	7 d
`list_events` window	31 d
`stations`	60 (30 for `get_waveform_summary`, 12 for `render_waveforms`, 4 when `channel=all`)
`query_external_catalog` `radius_km`	1000
`list_events` `limit`	1..500
`find_similar_events` `radius_km` / `limit`	1..100 / 1..200
`get_decision_history` `radius_km` / `limit`	1..100 / ≤ 500

Envelope¶

Every result, success or failure, is one JSON object. It is the tool's outputSchema.

Field	Rule
`ok`	`true` or `false`. Nothing else signals failure
`spec`, `server_version`, `tool`, `tool_version`	Always present, including on errors
`tool_call_id`	Always present. Unique in the session, stable in the ledger
`tier`	Highest of F / E / D among parameters actually used
`catalogue_bearing`	`false` if any Tier D parameter, any `value` origin, or a tool declared non-catalogue-bearing was involved
`resolved_request`	Concrete lists and defaults after reference resolution — not an echo of the arguments
`payload`	Tool-specific. Absent on errors
`payload_digest`	SHA-256 of canonical JSON of `payload`
`input_digest`	SHA-256 of raw bytes read, or `null` for a pure catalogue read
`provenance`	Frozen inputs the tool used
`warnings`	`{ code, message, detail }`. `detail` is always present. Empty array, never absent
`budget`	Tool counter, then `total_calls`, when the profile defines budgets
`timing_ms`	Wall-clock of the domain call

hypothesis is a request parameter, not an envelope field. It is stored in the ledger from the arguments as given.

A failed call is citable evidence: the tool could not measure this. Hiding a failure contradicts the ledger.

Tiers¶

Tier	Meaning	Enforcement
F — Frozen	Not settable. Velocity model, inventory, grid definitions, magnitude constants, bulletin thresholds	Absent from every input schema. Reported in `provenance`
E — Enumerated	Chosen from a menu, recorded	JSON Schema `enum`. Off-menu → `E_PARAM_NOT_IN_MENU` with the tool's effective menu
D — Diagnostic	Free values; result is evidence only	Profile may forbid (`E_TIER_VIOLATION`). Result is `catalogue_bearing: false` with warning `tier_d_parameter`

Menus in v1 include picker, picker_threshold, filter_band, channel, depth_mode, grid (shallow / deep; floors 65 km and 250 km), associator, phase_set, arrival_model, and the render-axis menus. Menus only grow. A tool may accept a subset of a shared menu; that is not a second vocabulary.

Any number that may enter a catalogue must come from a call whose envelope says catalogue_bearing: true.

Hypothesis rule¶

On profiles that require it, a repeat is a call to the same Tier E tool, on the same target, with a Tier E configuration different from a previous successful call on that target in this session. The target is the subject event for relocate, reassociate and jackknife_location, and the station_id for guided_repick. A repeat needs a non-empty hypothesis in the request; the first call on a target does not. An identical configuration is a re-measurement and needs no hypothesis.

Do not pass hypothesis to predict_arrivals or compute_magnitude as if it were required. Those tools accept an unused optional string.

Shared warning codes¶

Code	Meaning
`depth_at_grid_boundary`	Solution depth within 5 km of 0 or of the grid floor
`few_phases`	Fewer than 6 phases used
`no_s_phases`	No S phase used
`large_gap`	Azimuthal gap greater than 180°
`station_absent`	A requested station is `absent` in the window
`station_silent`	A requested station is configured but has no data in the window
`data_gap`	Requested window only partially covered
`clipped_trace`	Amplitude at digitizer full scale
`low_confidence_fit`	A fitted quantity has poor statistics (the tool states the criterion)
`by_value_origin`	A `value` origin was used; result is not catalogue-bearing
`tier_d_parameter`	A Tier D parameter was used; result is not catalogue-bearing
`snapshot_stale`	Bulletin snapshot older than 30 days relative to the queried window's end
`partial_result`	Some sub-results missing; `detail` lists them
`no_travel_time_grid`	A requested station has no travel-time grid and was skipped
`budget_low`	At most one call left in the tool's budget
`co_detections_present`	Other catalogue rows within the co-detection window of this origin
`availability_stale`	The availability table has no row for the requested UTC day

New codes may be added. Existing codes never change meaning. Per-tool lists are only on a tool page when the specification names them for that tool.

Shared error codes¶

Code	When
`E_SCHEMA`	Input fails JSON Schema, including unknown properties
`E_PARAM_NOT_IN_MENU`	A Tier E value outside its menu
`E_TIER_VIOLATION`	A Tier D parameter on a profile that forbids Tier D
`E_POLICY`	Tool hidden, event not the session subject, or the view forbids the argument
`E_MISSING_HYPOTHESIS`	Repeat Tier E call without a non-empty `hypothesis`
`E_BUDGET_EXHAUSTED`	Tool or total budget spent
`E_UNKNOWN_EVENT`	No such `event_id` in the session's view
`E_UNKNOWN_REF`	Reference not in this session or not successful
`E_WINDOW_TOO_LARGE`	Selection bound exceeded
`E_DATA_UNAVAILABLE`	Station absent, no waveform, no grid, table or model missing, or no baseline
`E_TOOL_FAILED`	Underlying library or binary error
`E_TIMEOUT`	Domain call exceeded `timeout_s`
`E_BUSY`	Queue wait would exceed the configured limit
`E_EVIDENCE_INVALID`	`submit_review` cites an unknown, failed, or foreign id, or a missing path
`E_REVIEW_INVALID`	`submit_review` violates a structural rule
`E_SESSION_CLOSED`	Token expired, review already accepted, or the session is closed

ok: false is the only way a tool reports failure. A failed call still has a tool_call_id and is ledgered.