MarketSpec

Turn explicit event-market settlement rules and typed evidence into deterministic, replayable outcomes.

MarketSpec is an experimental open-source toolkit for compiling explicit event contracts into canonical identities, admitting typed evidence, and evaluating the same inputs to the same machine-checkable result.

It is intentionally not a trading bot, exchange, custody system, or oracle that invents missing facts.

v0.1 core

The public core provides:

• a typed event-contract model with explicit market/event identity, source binding, bounded observation window + IANA timezone, sampling/aggregation, revision/finality policy, threshold/tie semantics, fallback behavior, and outcome mapping;
• YAML/JSON compilation into deterministic canonical JSON + SHA-256 content identity;
• typed fail-closed compiler errors, including rejection of naive datetimes and binary floating-point settlement values;
• deterministic evaluation of admitted typed evidence;
• a public JSON Schema at src/marketspec/schema/marketspec.schema.json.

A minimal contract:

schema_version: "0.1"
market_id: example-market
event_id: example-event
predicate: {operator: above, threshold: "100.0"}
window:
  start: 2026-09-19T00:00:00Z
  end: 2026-09-20T00:00:00Z
  timezone: UTC
source: {id: official-feed, field: value}
aggregation: last
sampling: all
revision_policy: final_only
tie_behavior: no
fallback: unknown
outcomes: {yes: YES, no: NO, unknown: UNKNOWN, invalid: INVALID}

CLI

python -m pip install -e .
marketspec compile contract.yaml
marketspec evaluate contract.yaml evidence.json
marketspec conformance

For a fresh clone, follow the 5-minute quickstart. The worked examples reuse the versioned conformance corpus so expected hashes and fail-closed outcomes stay reproducible.

The conformance command runs the bundled, versioned offline golden corpus. See CONFORMANCE.md; the JSON corpus is directly reusable by third-party implementations without ResolveOps.

Evidence records are typed objects with source_id, field, timezone-aware observed_at, decimal-string/integer value, boolean final, and non-negative integer revision.

Design principles

• Fail closed when settlement semantics are incomplete.
• Treat LLM output as untrusted input until typed and validated.
• Use explicit timezone and revision/finality semantics.
• Use decimal/fixed-point values for settlement thresholds.
• Preserve deterministic canonicalization and replay.
• Make missing and conflicting evidence explicit rather than silently producing YES/NO.
• Keep the core useful without a hosted ResolveOps account.

Local verification

PYTHONPATH=src python -m marketspec.cli --version
PYTHONPATH=src python -m unittest discover -s tests -v
PYTHONPATH=src python -m marketspec.cli conformance

See docs/ARCHITECTURE.md for the contract/evidence model and current limitations, and docs/OSS-BOUNDARY.md for the public/private boundary.

Versioning and releases

MarketSpec is pre-1.0. Compatibility expectations, changelog rules, exact-SHA release gates, and tag provenance are documented in docs/RELEASING.md. User-visible changes are recorded in CHANGELOG.md.

No public package availability is implied by this repository alone; publication must be verified separately after a release is actually uploaded.

Contributing and security

Start with CONTRIBUTING.md. External contributors only need this public repository; private maintainer workflow data is not required. Community behavior is covered by CODE_OF_CONDUCT.md, and security reports should follow SECURITY.md.

Maintainers

Internal workflow authority lives in sangtrx/sang-workspace; repository main is source truth. External users do not need the internal workflow to install, run, or evaluate MarketSpec.

License

Apache-2.0.