# Tessera

> A declarative, composable, agent-authorable format for market trading strategies,
> plus an open-source engine that backtests them and a runtime that trades them live —
> from the same document, on the user's own machine, against data the user owns.
> Status: design/planning. No engine has shipped yet, and the source repository is not
> public yet — it opens with the v0 licence (open-core: permissive for the format/schema/SDK,
> copyleft for the engine and live runtime). The design itself IS published: see /architecture
> for the layered design, the storage model and the full decision log.

This file is written to be read by machines and language models: stable vocabulary,
scannable structure, precise semantics. The human overview is at /docs.

## What it is

- A **strategy** is a document (JSON/YAML), validated as a whole before anything runs.
- Two layers: a **closed algebra** (operators/predicates/combinators — extended only by
  editing the schema, rare) over an **open vocabulary** (observables like `spot`, `atm`,
  `pnl`, `pin_bar` — extended by registration). Adding a primitive is a registration, not
  a schema change.
- Every expression node carries a **unit** (Money | Count | Ratio | Bool). A selector's
  `target` must agree with its `on`. Unit mismatches are rejected at validation.
- **One document, two runtimes.** A shared evaluation core turns the strategy into
  *intents*; a backtest runtime simulates fills, a live runtime places real orders. They
  never share the execution path.

## Core grammar (v2)

Strategy = { resource: strategy, version, venue, instrument, let?, entry, legs[], exit[] }

- **entry** = { candidates: { every, at }, trigger?: Predicate }
- **Leg** = { ref, instrument: InstrumentRef, side: BUY|SELL, qty, select?: Selector, exit?: [ExitRule] }
- **InstrumentRef** = Equity{symbol} | Future{underlying,expiry} | Option{underlying,expiry,right:CE|PE}
- **ExpiryRef** = W | W2 | W3 | M | M2 | M3 | Y | Absolute(date)   (ordinals over the venue's ladder)
- **Selector** = { over: strike_ladder | universe(name), on: Strike|Premium|OI|Delta|Price, pick: Nearest|Max|Min|AtStep(n), target?: Ref, tolerance?: Ref }
- **Ref (closed algebra)** = Absolute(v) | Obs(name,window?,params?) | Strike(legRef) | Premium(legRef) | Pct(Ref,n) | ScalePct(Ref,n) | Steps(Ref,n) | Offset(Ref,n) | Sum(Ref...)
- **Predicate (closed algebra)** = Compare(Ref,op,Ref) [op: LT|LTE|GT|GTE|EQ|NEQ] | Within(Ref,Ref,tol) | And(..) | Or(..) | Not(..) | Truthy(Ref) | Expiry
- **ExitRule** = { scope: basket|leg, when: Predicate, then: SquareOffAll|SquareOffLeg|MoveSLToCost|Repeat|Trail }
- `let` binds reusable named Ref expressions, usable anywhere a Ref is accepted.

## Observables (open registry, examples)

spot, atm (= Nearest(Strike, Spot)), high, low, close, vwap, resistance, pivot, pin_bar
(unit Bool), oi (unit Count), pnl, credit. Each declares { unit, window?, params }.
Windowed observables end strictly before the entry instant — look-ahead is a validation
Reject, not a convention.

## Errors (closed catalogue, four classes)

- **Reject** — at validation, before any work; nothing runs; diagnostic names the field.
- **Allow** — per unit of work; records a hole with a reason; continues.
- **Warn** — succeeded with a caveat; surfaced in the result.
- **Defect** — uncatalogued; fails loudly. There is no "log and continue".

Coverage is a first-class result field: entered | no_trigger | hole | skipped. Codes are
stable strings (e.g. `strike.out_of_range`, `data.insufficient_history`).

## Data model

- **Ticks are the stored primitive** (ts, ltp, ltq, oi). **Bars** at any resolution are
  derived, cached aggregations (1-minute open/high/low/close/volume/oi). One `Store`
  interface, index-mode files or Postgres.
- **Providers** declare capabilities: InstrumentMaster, HistoricalSource, LiveSource,
  ExecutionVenue. A broker is data + execution over one (or per-surface) credential.
- Money is integer minor units (paise), never float. Reproducibility is exact.

## Sample strategy

/strategy.sample.yaml — a short strangle with hedged wings, inter-leg references, and
PnL/credit/expiry exits. The JSON Schema is /schema.json (draft; the format is v2).

## Links

- Human docs: /docs
- Architecture reference (design, storage model, decision log): /architecture
- Sample strategy: /strategy.sample.yaml
- JSON Schema (draft): /schema.json
- Early access: / (the site) — leave an email to get involved.

## Notes for agents

- Author strategies against /schema.json; on a Reject you receive a field path precise
  enough to correct the offending node and resubmit.
- Nothing here is investment advice; parameters in examples are illustrative, not
  validated values.