Build deterministic Jester earnings research engine

.github/workflows/quality.yml

@@ -0,0 +1,36 @@
+name: Quality
+
+on:
+  push:
+    branches: ["main", "agent/**"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --frozen --extra dev
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy
+      - run: uv run pytest
+      - run: uv build
+      - name: Public safety scan
+        shell: bash
+        run: |
+          uv run python scripts/validate_public_release.py
+          ! git grep -n -E '(BEGIN (RSA|OPENSSH|EC) PRIVATE KEY|sk-[A-Za-z0-9]{20,}|account[_-]?id.*[0-9]{6,})'
+          test ! -d runtime
+          test ! -d data/private

AGENTS.md

@@ -0,0 +1,21 @@
+# Jester Engineering Rules
+
+- Preserve deterministic replay: identical versions, inputs, and semantic seed labels must
+  produce identical event and result hashes.
+- Keep evidence, simulation, evaluation, and presentation as separate layers.
+- No broker, account, credential, order, cancellation, transfer, or live-submit dependency
+  may enter this repository.
+- Every governor candidate must remain `paper_only=true`, `live_blocked=true`, and
+  `order_construction_allowed=false`.
+- Synthetic, reconstructed, model-priced, shadow, paper, and realized outcomes must never be
+  relabeled.
+- No observation may be used before its mode-specific availability time.
+- Keep source permissions, revisions, duplicate clusters, contradictions, and failed trials.
+- Autonomous improvement may mutate hypothesis and calibrated research state only. Source,
+  evaluators, test data, proof gates, and authority rules are protected.
+- Use typed, functional, single-purpose code. Connector classes are allowed only at external
+  boundaries.
+- Raise explicit actionable errors. Do not silently fall back to another provider, source, or
+  simulator.
+- Prefer replay, integration, property, and end-to-end tests over mock-heavy unit tests.
+- Never weaken a quality gate because a candidate, model family, or market pack fails it.

ARCHITECTURE.md

@@ -0,0 +1,38 @@
+# Jester Architecture
+
+Jester is an event-sourced causal market-imagination engine. Its fixed pipeline is:
+
+```text
+INGEST -> NORMALIZE -> PERCEIVE -> BELIEF -> INTERVENE -> SIMULATE
+       -> PRICE -> STRATEGIZE -> EVOLVE -> PROVE -> EXPORT
+```
+
+The first release implements an Earnings Pack vertical slice across all stages. The core is
+deterministic and CPU-first. Learned generative models are optional model-family adapters and may
+activate only after accepted point-in-time training evidence and calibration exist.
+
+## Layers
+
+```text
+Read-only API / CLI / governor bundle exporter
+Proof Court / Holdability Gate / signature verifier
+Idea Forge / Belief Exchange / quality-diversity archive
+Game Arena / Market Society / option outcome field
+Causal scenario lattice / market and volatility twins
+Scuttlebutt claim graph / point-in-time world-state graph
+Immutable evidence vault / event log / clocks / semantic RNG
+```
+
+The runtime stores content-addressed evidence and append-only indexes outside the source tree.
+Repository fixtures prove mechanics only and never certify market fidelity or predictive edge.
+The ordinary option lane rejects 0DTE contracts whose lifecycle crosses the permitted exit.
+A dedicated jump- and expiry-aware 0DTE pricer remains fail-closed and is not implemented in
+the first public vertical slice.
+
+## External boundaries
+
+- Credential-free official sources may be fetched by reviewed connector classes.
+- Market, options, transcript, and social evidence arrive through operator-staged manifests.
+- Intelligence providers receive only records whose permission allows external processing.
+- Governor export is a signed file protocol. No downstream repository is imported.
+- Read-only observability is exposed over localhost. Mutation remains CLI/config controlled.

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing
+
+Changes must preserve deterministic replay, point-in-time evidence law, immutable
+artifacts, explicit failure, and the paper-only authority boundary.
+
+Before proposing a change, run the full release gate documented in the README. New model
+families must report their own outputs and disagreement; they must not be silently
+averaged into an incumbent result. Synthetic evidence must remain clearly labeled.

DATA_NOTICE.md

@@ -0,0 +1,9 @@
+# Data Notice
+
+The source code is MIT licensed. Market, options, transcript, news, and social-media data are not
+included. Every operator must bring data through reviewed manifests that record permission,
+retention, redistribution, provenance, point-in-time timestamps, and SHA-256 identities.
+
+Runtime evidence, provider transcripts, model weights, checkpoints, signatures, and private keys
+must remain outside Git. Public fixtures are synthetic mechanics tests and cannot certify market
+fidelity, calibration, predictive edge, or state-of-the-art performance.

JESTER_CONSTITUTION.md

@@ -0,0 +1,40 @@
+# Jester Constitution
+
+Version: `jester-constitution-v1`
+
+## Authority
+
+Jester is a causal market-world research engine. It may ingest permitted evidence, construct
+counterfactual scenarios, simulate markets and options, evolve research hypotheses, settle
+beliefs, and export signed research candidates.
+
+Jester has no authority to connect to a broker, inspect an account, size against buying power,
+construct an executable order, cancel an order, or submit capital. A downstream human-owned
+governor independently decides whether a signed research candidate may enter its own proof and
+paper lifecycle.
+
+## Evidence law
+
+1. Event time, publication time, market availability time, ingestion time, revision time, and
+   market reaction windows remain distinct.
+2. Historical reconstruction may use evidence at recorded market availability, but is never
+   forward evidence. Forward shadow evaluation may use evidence only after actual ingestion.
+3. Raw and normalized content are content-addressed. Revisions append; they never overwrite.
+4. Source permission, retention, contradictions, duplicates, and failures remain inspectable.
+5. Synthetic, reconstructed, model-priced, shadow, paper, and realized outcomes remain separate.
+
+## Simulation law
+
+1. Identical versioned inputs and semantic seed labels reproduce exactly.
+2. Model-family disagreement is surfaced and penalized; it is not hidden by silent averaging.
+3. Repaired volatility surfaces remain labeled as repaired.
+4. Missing executable quotes cannot become observed fills.
+5. A candidate fails the Holdability Gate when its edge decays before the earliest permitted exit.
+6. 0DTE uses a separate jump-, liquidity-, expiry-, and policy-aware lifecycle.
+
+## Autonomous-improvement law
+
+Jester may autonomously evolve hypothesis genomes, belief calibration, bounded numerical model
+parameters, archive occupancy, and research scheduling. It may emit source-code mutation
+proposals, but it may not apply or merge them. Source code, evaluators, sealed test data, proof
+gates, signing policy, and authority rules are protected mutation targets.

QUALITY_GATES.yaml

@@ -0,0 +1,33 @@
+version: 1
+authority:
+  broker_dependency_allowed: false
+  credential_storage_allowed: false
+  order_construction_allowed: false
+  paper_only_required: true
+  live_blocked_required: true
+evidence:
+  content_addressing_required: true
+  revision_append_only_required: true
+  point_in_time_cutoff_required: true
+  source_permission_required: true
+  duplicate_cluster_required: true
+kernel:
+  exact_replay_required: true
+  event_hash_chain_required: true
+  semantic_rng_required: true
+  atomic_non_overwriting_artifacts_required: true
+options:
+  quote_origin_label_required: true
+  static_arbitrage_validation_required: true
+  holdability_gate_required: true
+  zero_dte_blocked_until_separate_lane_validated: true
+autonomy:
+  bounded_research_state_only: true
+  evaluator_mutation_allowed: false
+  source_auto_apply_allowed: false
+  failed_trial_ledger_required: true
+  quarantine_and_rollback_required: true
+claims:
+  synthetic_mechanics_may_certify_forward_edge: false
+  reconstructed_results_may_certify_forward_performance: false
+  state_of_the_art_claim_requires_forward_ab_win: true

README.md

@@ -0,0 +1,178 @@
+# Jester
+
+**A causal market-world, narrative-intelligence, game-theory, and long-option
+research engine.**
+
+Jester asks a narrower and harder question than a stock predictor:
+
+> Given only the information available at this exact moment, which market worlds
+> are plausible—and can a real long call or long put survive volatility, liquidity,
+> timing, and a downstream governor's holding constraints?
+
+The first public release is a deterministic Earnings Pack vertical slice. It turns
+point-in-time evidence into a signed, replayable candidate bundle without possessing
+broker credentials, order authority, or a live-submit path.
+
+## The research chain
+
+```mermaid
+flowchart LR
+    A["Immutable Evidence Vault"] --> B["Scuttlebutt claim graph"]
+    A --> C["Point-in-time world state"]
+    B --> D["Competing causal worlds"]
+    C --> D
+    D --> E["Numerical market society"]
+    E --> F["Strategic game arena"]
+    F --> G["Evolutionary idea forge"]
+    G --> H["Option outcome field"]
+    H --> I["Independent proof court"]
+    I --> J["Signed governor candidate"]
+    J --> K["Downstream governor decides"]
+```
+
+Every candidate traverses the complete chain. Social activity can generate or
+reweight hypotheses, but it cannot authorize a candidate. A directionally correct
+stock thesis can still be rejected when the option loses through IV crush, decay,
+spread, fill risk, or an earliest-exit mismatch.
+
+## What exists today
+
+- Immutable evidence identities with distinct event, publication, market-availability,
+  ingestion, and revision clocks.
+- Claim graphs that preserve originality, propagation, incentives, contradiction,
+  saturation, manipulation risk, and price-leading versus price-following behavior.
+- Multiple causal graphs and explicit observed, candidate-causal, supported-intervention,
+  and stress-only edges.
+- A six-world Earnings Pack lattice spanning guidance conflict, IV crush, narrative
+  reflexivity, catalyst delay, and adversarial liquidity.
+- Thirteen numerical participant classes and Bayesian, signaling, congestion,
+  adverse-selection, and repeated-session games.
+- Correlation-clustered specialist beliefs with Brier and log-loss settlement.
+- A lineage-preserving hypothesis genome and quality-diversity archive primitive.
+- Joint underlying/IV/liquidity option paths, Black–Scholes baseline repricing,
+  static-arbitrage checks, fill modeling, P&L attribution, and a hard Holdability Gate.
+- An independent proof manifest and canonical Ed25519 candidate signing.
+- A bounded inbox supervisor and local read-only observatory API.
+
+Advanced stochastic-volatility, rough-volatility, generative order-book, and calibrated
+full-surface models are extension interfaces—not claimed as implemented or validated in
+this release.
+
+## Authority boundary
+
+Jester is structurally research-only:
+
+| Capability | Status |
+|---|---|
+| Generate market-world hypotheses | Allowed |
+| Simulate long calls and long puts | Allowed |
+| Produce paper candidate artifacts | Allowed |
+| Sign replayable research bundles | Allowed |
+| Read broker credentials | Absent |
+| Construct or submit orders | Prohibited |
+| Decide downstream acceptance | Prohibited |
+| Auto-apply self-written code | Prohibited |
+
+Candidate bundles carry `paper_only=true`, `live_blocked=true`,
+`order_construction_allowed=false`, and `execution_authority=none`. The schema is in
+[`schemas/governor_candidate_bundle_v1.schema.json`](schemas/governor_candidate_bundle_v1.schema.json).
+
+## Quick start
+
+Requirements: Python 3.12 or 3.13 and
+[`uv`](https://docs.astral.sh/uv/).
+
+```powershell
+uv sync --extra dev
+uv run jester run `
+  --input fixtures/earnings/synthetic_candidate.json `
+  --output artifacts/synthetic-candidate.json
+uv run jester inspect --artifact artifacts/synthetic-candidate.json
+```
+
+The included fixture is deliberately synthetic and redistributable. It proves replay,
+economics, rejection, and authority behavior; it is not evidence of market performance.
+
+Run the complete release gate:
+
+```powershell
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+uv run python scripts/validate_public_release.py
+```
+
+## Signed handoff
+
+Jester never creates or stores a signing key. Supply a 32-byte Ed25519 seed owned by
+the operator:
+
+```powershell
+uv run jester sign `
+  --input artifacts/unsigned-bundle.json `
+  --output artifacts/signed-bundle.json `
+  --key .operator/jester-ed25519.key `
+  --key-id operator-research-key
+
+uv run jester verify --bundle artifacts/signed-bundle.json
+```
+
+The synthetic pipeline result contains its unsigned bundle under `unsigned_bundle`.
+Extract and sign it outside the evidence plane:
+
+```powershell
+uv run jester export-bundle `
+  --result artifacts/synthetic-candidate.json `
+  --output artifacts/unsigned-bundle.json
+```
+
+Production integrations should pass the signed artifact to a downstream governor through
+a file or equivalent one-way transport.
+
+## Bounded autonomy
+
+The supervisor processes immutable JSON manifests. It never deletes or moves source
+inputs, never retries a failed item silently, and emits an explicit blocked artifact:
+
+```powershell
+uv run jester supervise `
+  --inbox .operator/inbox `
+  --outbox .operator/outbox `
+  --errors .operator/errors `
+  --max-cycles 10 `
+  --max-items 100 `
+  --poll-seconds 5
+```
+
+Evolution is also bounded. Jester may mutate research genomes, measure niche diversity,
+and write code-change proposals. `auto_apply` is always false; independent evaluation
+and an operator-controlled software workflow remain required.
+
+## Optional narrative model
+
+`OpenRouterClient` is a permission-gated connector for claim interpretation and
+behavioral variation. It is not used for pricing, proof, calibration, or authority
+decisions. Inputs may be sent only when the evidence record permits external-model
+processing. Provider failure is explicit after the configured retry budget; there is
+no hidden model fallback.
+
+## Evidence and data
+
+No proprietary, licensed, scraped, or historical market dataset is distributed here.
+See [`DATA_NOTICE.md`](DATA_NOTICE.md). Real research intake must preserve permissions,
+retention, content hashes, and all point-in-time clocks. A repaired volatility surface
+must be labeled repaired and cannot be represented as an observed simulator output.
+
+## Status standard
+
+Jester is **state-of-the-art-inspired**, not proven state of the art. Promotion requires
+a frozen forward-paper A/B comparison against the same universe, cutoff, capital,
+contracts, execution simulator, holding rules, and costs—and independent replication
+of improved executable P&L, calibration, downside control, holdability, fill realism,
+false-positive rejection, and simulation-to-forward agreement.
+
+Architecture and invariants are detailed in
+[`ARCHITECTURE.md`](ARCHITECTURE.md) and
+[`JESTER_CONSTITUTION.md`](JESTER_CONSTITUTION.md).

SECURITY.md

@@ -0,0 +1,8 @@
+# Security
+
+Report security issues privately to the repository maintainers. Do not open a public
+issue for a vulnerability.
+
+Jester's security boundary excludes broker credentials, broker sessions, live orders,
+and order submission. A finding that introduces any of those paths is severity-critical.
+Candidate signing keys are operator-owned and must never be committed to this repository.

fixtures/earnings/README.md

@@ -0,0 +1,5 @@
+# Earnings Pack fixtures
+
+`synthetic_candidate.json` is redistributable synthetic data. It proves deterministic
+pipeline behavior and boundary enforcement; it is not historical market evidence and
+must not be cited as strategy performance.