kestrel.markets
Version:
A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.
177 lines (176 loc) • 9.21 kB
JavaScript
/**
* # series/author-lint — the unknown-series trigger operand, made legible (kestrel unknown-series-legible)
*
* A registry-aware, author-time semantic check that turns a SILENT never-fire into a LOUD,
* repair-guiding rejection. The failure it catches: a trigger operand names a series that PARSES
* as a well-formed {@link SeriesRef} but has **no phonebook record** because the authored name is a
* case-clash of a known key (`VELOCITY` against the lowercase key `velocity`). Such an operand resolves UNKNOWN, so a
* `crosses` never observes its transition and the plan arms then silently expires — 0 orders, and
* the plan reads `armed`, not blocked. That VIOLATES the registry's own fail-closed charter ("the
* phonebook never guesses … a logged reason … never a silent default", `registry.ts` header): here
* the unknown-NAME is a *silent* never-fire the author cannot see.
*
* This check restores legibility at author-time (Option A / iq5-shaped): a document whose trigger
* references an unknown series NAME that is a case-variant of a known market series is rejected
* with a message that names the offending series, the known series it clashes with ("did you mean 'velocity'?"),
* and the whole known vocabulary — a repairable `invalid` outcome the harness feeds back so the
* agent self-corrects next wake (the gxz reason-feedback loop). It is pure (no clock/RNG/IO) and
* off the graded path: a validation rejection is not graded-bus content.
*
* ## Case-variants are ALL flagged (OSS-ADR-0045) — the 0.4.5 forgiveness is reverted
* `registry.lookup` is now EXACT-MATCH: a case-variant of ANY known market series — the seven scalars
* (`VWAP`/`HOD`) OR a windowed metric (`VELOCITY`) — has no phonebook record, so this check's
* `registry.lookup(name) !== undefined` gate does NOT skip it and `nearestKnown` finds the canonical
* lowercase name it clashes with. A scalar case-variant is thus a flaggable author error exactly like
* a windowed one — the same coded `unknown-series` refusal the arm-time guard raises. This reverts the
* kestrel-7tbi case-insensitive forgiveness: forgiving a case-clash at resolution armed a plan on a
* name the author never registered and hid a de-arm they could not see (a silent default, RUNTIME §8).
*
* ## What it flags — and, deliberately, what it does NOT
* The hard part is telling a **market-fact case-clash** (`VELOCITY`) apart from a **legitimate org
* fact** (`pnl`, `plan(chase).state`), a **state literal** (`done`), or a **regime tag** (`chop`) —
* all are `registry.lookup(name) === undefined`, because org facts register implicitly / delegate to
* the book (`series/provider`) and literals/tags resolve symbolically. Structure alone can't
* distinguish them (`VELOCITY` and `pnl` are both bare single-segment identifiers). The discriminator
* is **legibility-only / the phonebook never guesses**: we flag a bare, unregistered operand ONLY when
* it is a case-INSENSITIVE-EXACT match to a known series (a pure case-clash). We do NOT guess at
* arbitrary edit-distance typos — that arm false-positived on first-class operands (`done`, `chop`,
* `gap`, `long`, …). So:
*
* - `VELOCITY` → flagged (case-clash of `velocity`, a windowed metric) — author error
* - `VWAP` / `HOD` → flagged (a scalar case-clash of `vwap`/`hod`; exact-match, OSS-ADR-0045) — author error
* - `vwpa` → NOT flagged (a genuine typo, but no case-exact known match; never guessed at)
* - `vwap` → NOT flagged (it IS registered)
* - `pnl` → NOT flagged (no case-exact market series; a real org fact routed to the book)
* - `plan(x).state` → NOT flagged (has a selector ⇒ never a market read)
* - `armed` / `done`/ `chop` → NOT flagged (a symbolic literal / regime tag, not a known series name)
*
* A series that IS in the phonebook but is currently **dark** (resolves UNKNOWN as a transient data
* state) is never touched here — that stays silently-armed by design (fail-closed on a value, not a
* name). We only ever read the phonebook, never a live value.
*/
/** A bare single-segment operand with no org selector — the only shape that can be a market-fact
* read (a windowed metric like `velocity(1m)` still qualifies; a selector or a dotted path is an org
* path and is never a market series). */
function bareName(ref) {
if (ref.segments.length !== 1)
return undefined;
const seg = ref.segments[0];
if (seg === undefined || seg.selector !== undefined)
return undefined;
return seg.name;
}
/** The known series NAME that `name` is a case-INSENSITIVE-EXACT match of (a pure case-clash like
* `VWAP` against `vwap`), or undefined when there is no such match (⇒ treat as a legitimate org fact
* / state literal / regime tag / genuinely novel name, NOT an author error). Legibility-only: the
* phonebook never *guesses* at arbitrary typos — an edit-distance arm here false-positived on
* first-class operands (`done`, `chop`, `gap`, `long`, …), so we surface ONLY the case-clash idiom.
* Deterministic: at most one known name differs from `name` by case alone. */
function nearestKnown(name, known) {
const lower = name.toLowerCase();
return known.find((k) => k.toLowerCase() === lower);
}
/** The operands a Trigger reads, recursively across the algebra. Only leaf operands are yielded;
* combinators (and/or/not/held/within/until/at/nth) are traversed into. */
function* triggerOperands(t) {
switch (t.kind) {
case "cmp":
case "cross":
yield t.left;
yield t.right;
return;
case "event":
if (t.of !== undefined)
yield t.of;
return;
case "break-hold":
case "within":
case "until":
case "at":
yield* triggerOperands(t.inner);
return;
case "nth":
yield* triggerOperands(t.event);
return;
case "and":
case "or":
for (const term of t.terms)
yield* triggerOperands(term);
return;
case "not":
yield* triggerOperands(t.term);
return;
// phase / time-window / fill carry no series operand.
default:
return;
}
}
/** Every WHEN/EXIT/INVALIDATE/CANCEL-IF/ARM/RELOAD trigger in a Plan, in document order. */
function* planTriggers(p) {
if (p.when !== undefined)
yield p.when;
for (const c of p.clauses) {
switch (c.kind) {
case "exit":
case "invalidate":
case "cancel-if":
yield c.when;
break;
case "arm":
case "reload":
if (c.when !== undefined)
yield c.when;
break;
default:
break; // do / also / tp carry no trigger
}
}
}
/** Every trigger a statement contributes (Plan clauses + the Wake WHEN); other statement kinds
* carry no trigger operand relevant to the never-fire failure. */
function* statementTriggers(s) {
if (s.kind === "plan") {
yield* planTriggers(s);
}
else if (s.kind === "wake") {
yield s.when;
}
}
function* documentTriggers(node) {
if (node.kind === "module") {
for (const s of node.statements)
yield* statementTriggers(s);
}
else {
yield* statementTriggers(node);
}
}
/**
* The FIRST unknown-series trigger operand in a parsed document that near-matches the known market
* vocabulary — a repairable author error — or `undefined` when every trigger operand is either a
* registered series, a legitimate org path, or a symbolic literal too far from any market series to
* be a typo. Reads only the phonebook (never a live value), so a currently-dark registered series is
* never flagged. Pure and deterministic (document-order traversal; deterministic suggestion).
*/
export function unknownSeriesDiagnostic(node, registry) {
const known = registry.dump().map((r) => r.name);
for (const trig of documentTriggers(node)) {
for (const operand of triggerOperands(trig)) {
if (operand.kind !== "series")
continue;
const name = bareName(operand);
if (name === undefined)
continue; // selector / dotted path ⇒ an org read, never a market series
if (registry.lookup(name) !== undefined)
continue; // a registered NAME (dark VALUE is not our concern)
const suggestion = nearestKnown(name, known);
if (suggestion === undefined)
continue; // no near market series ⇒ a real org fact / literal
const message = `WHEN references unknown series '${name}' — did you mean '${suggestion}'? ` +
`Series names are case-sensitive and '${name}' has no phonebook record, so the trigger ` +
`resolves UNKNOWN and the plan arms but never fires. Known market series: ${known.join(", ")}.`;
return { name, suggestion, message };
}
}
return undefined;
}