kestrel.markets/dist/protocol/index.js

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.

/**
 * kestrel.markets/protocol — the CANONICAL wire-protocol types (v0.1).
 *
 * This module is the open, versioned contract that the managed backend
 * implements (ADR-0010): the platform is the SERVER and imports these SHAPES.
 *
 * HARD CONSTRAINTS (do not violate):
 *  - ZERO runtime dependencies. This file imports NOTHING. It must typecheck
 *    with `chdb` uninstalled and pull in no engine / language / series / fill
 *    code. Keep it that way — it is the core side of the core-vs-local split.
 *  - SHAPES ONLY. No signing keys, no Stripe/commerce logic, no corpus/presence.
 *    Every signed, replayable artifact carries an opaque `*Ref` HANDLE, never a
 *    key or a signing routine (ADR-0010 open/closed seam).
 *  - GENERIC INSTRUMENTS ONLY. Order/Fill/Position/Blotter model instruments
 *    generically (opaque `symbol: string`). No founding-app tickers or strategy
 *    names appear in types, doc comments, or examples. Product tickers ride
 *    INSIDE these fields at runtime; they are not part of the published contract.
 *
 * Scope: v0.1 covered the trial→conversion (M1) surface — authority-continuation,
 * purchase, and grade receipts. v0.2 ADDS, non-breakingly, the content-addressed
 * catalog contract (./catalog.ts), the incremental Session transcript
 * (./session.ts) — both re-exported below — and the M2–M4 receipt roots
 * (input-admission, resource-value, promotion, live-activation), which the
 * CertifiedReceipt umbrella admits as non-breaking additions to AnyReceipt. No
 * existing v0.1 shape changed, so 0.2 stays a purely additive minor. v0.3 ADDS,
 * non-breakingly, the oversight contract (./oversight.ts) — the cross-repo seam
 * between the CLI and Web Renderings of the human PM/Pod oversight surface
 * (ADR-0035), re-exported below. No existing shape changed, so 0.3 stays a purely
 * additive minor.
 *
 * Under 0.3, further ADDITIVE-OPTIONAL shapes have landed without a minor bump —
 * the same rule `inputPin` (kestrel-m9i.27), the OfferTerms vocabulary
 * (PLAT-ADR-0028), the OSS-ADR-0046 wire shapes, and the h314 certified-evidence
 * fields all rode under. The ex-ante catalog PRICING block (kestrel-adge —
 * {@link import("./catalog.ts").CatalogPricing} on the optional
 * {@link import("./catalog.ts").CatalogPage}) is another: it adds an OPTIONAL field
 * to a wrapped catalog body (absent ⇒ today's bare listing) and touches no existing
 * shape, so it rides additive under 0.3. The MINOR moves only for a deliberate
 * milestone surface (as at 0.2 and 0.3), never for each additive-optional field.
 *
 * Version: `major.minor`. Bump the MAJOR on any breaking shape change; bump the
 * MINOR for a purely additive milestone (v0.2 = catalog + Session, additive to
 * every v0.1 shape — no existing field changed).
 */
/* ────────────────────────────── version ────────────────────────────────── */
/**
 * Canonical protocol version (`major.minor`). Bump the major on any breaking
 * shape change; bump the minor for a purely additive milestone. v0.2 adds the
 * catalog + incremental Session surface without touching any v0.1 shape.
 */
export const PROTOCOL_VERSION = "0.4";
/**
 * @deprecated Alias of {@link PROTOCOL_VERSION} kept so existing consumers that
 * import `CONTRACT_VERSION` swap module specifiers without a rename. Remove once
 * all consumers migrate to PROTOCOL_VERSION.
 */
export const CONTRACT_VERSION = PROTOCOL_VERSION;
/* ─────────────────────────────── faces ─────────────────────────────────── */
/** The four faces every operation must project identically (ADR-0004). */
export const FACES = ["http", "sdk", "cli", "mcp"];
/**
 * Every authorization scope as a runtime tuple — the closed wire vocabulary of
 * {@link Scope}, ordered least→most privileged to match the type. The `satisfies`
 * proves the tuple stays a SUBSET of Scope; the paired exhaustiveness guard proves
 * it names EVERY member. Together they fail closed in BOTH directions: a scope
 * added to (or removed from) the union without editing this tuple breaks the
 * build, so the runtime vocabulary can never silently drift from the type.
 */
export const SCOPES = [
    "data",
    "sim",
    "grade",
    "paper",
    "broker",
    "live",
    "fleet-evidence:self",
    "fleet-evidence:subtree",
    "fleet:write",
];
/** Scopes a wallet may sign (reversible, commerce-only). The rest require a human. */
export const WALLET_SIGNABLE_SCOPES = ["data", "sim", "grade", "paper"];
/** True iff `scope` may be authorized by a wallet signature alone. */
export function isWalletSignable(scope) {
    return WALLET_SIGNABLE_SCOPES.includes(scope);
}
/** Runtime tuple of every {@link SignerClass}. Same both-ways closed-vocabulary guard as {@link SCOPES}. */
export const SIGNER_CLASSES = ["wallet", "human"];
/** Runtime tuple of every {@link AttestationRole}. Same both-ways closed-vocabulary guard as {@link SCOPES}. */
export const ATTESTATION_ROLES = ["compute", "executor"];
/** Runtime tuple of every {@link OperationState}. Same both-ways closed-vocabulary guard as {@link SCOPES}. */
export const OPERATION_STATES = [
    "open",
    "awaiting-settlement",
    "awaiting-human",
    "resumed",
    "completed",
    "failed",
];
/** Runtime tuple of every {@link Side}. Same both-ways closed-vocabulary guard as {@link SCOPES}. */
export const SIDES = ["buy", "sell"];
/** Runtime tuple of every {@link AdmissionState}. Same both-ways closed-vocabulary guard as {@link SCOPES}. */
export const ADMISSION_STATES = ["known", "unknown", "omitted"];
/** Runtime tuple of every {@link ActivationState}, in staged-fencing order. Same both-ways closed-vocabulary guard as {@link SCOPES}. */
export const ACTIVATION_STATES = ["preparing", "fence-confirmed", "active", "refused"];
/**
 * Every concrete receipt discriminant as a runtime tuple — the closed `.kind`
 * wire vocabulary of {@link AnyReceipt}. Driven by the union itself (`satisfies
 * readonly AnyReceipt["kind"][]`) so extending {@link AnyReceipt} with a new
 * receipt root (M2–M4) forces this tuple to grow in lockstep. Same both-ways
 * closed-vocabulary guard as {@link SCOPES}: a `.kind` added to (or removed from)
 * the union without editing this tuple breaks the build. Fail-closed, no drift.
 */
export const RECEIPT_KINDS = [
    "authority-continuation",
    "purchase",
    "grade",
    "input-admission",
    "resource-value",
    "promotion",
    "live-activation",
];
/**
 * Runtime tuple of every {@link ArmRefusalCode} — the closed wire vocabulary. Same
 * both-ways closed-vocabulary guard as {@link SCOPES}: a code added to (or removed
 * from) the union without editing this tuple breaks the build, so the runtime
 * vocabulary can never silently drift from the type.
 */
export const ARM_REFUSAL_CODES = ["unknown-series", "plan-name-in-use", "manages-nothing", "opening-short-uncovered"];
/**
 * Runtime tuple of every {@link ArmNoticeCode} — the closed wire vocabulary, guarded
 * both ways exactly like {@link ARM_REFUSAL_CODES}: adding a code to (or removing one
 * from) the union without editing this tuple breaks the build.
 */
export const ARM_NOTICE_CODES = ["regime-unsatisfiable", "adoption-bound-nothing"];
/* ─────────────────────────── v0.2 additive surface ─────────────────────────── */
/**
 * The v0.2 additions, re-exported so the published `kestrel.markets/protocol`
 * entrypoint carries the whole contract. Both modules are intra-protocol and
 * dependency-free (asserted by tests/protocol.boundary.test.ts):
 *  - ./catalog.ts — the content-addressed {@link import("./catalog.ts").CatalogEntry}.
 *  - ./session.ts — the incremental Session transcript + Operation/Session
 *    identity split + the idempotency/fail-closed reconciler.
 */
export * from "./catalog.js";
export * from "./session.js";
/* ─────────────────────────── v0.3 additive surface (oversight) ─────────────────────────── */
/**
 * The v0.3 addition: the OVERSIGHT contract — the cross-repo seam between the CLI
 * (`ascii`/Ink) and Web (`html`) Renderings of the human PM/Pod oversight surface
 * (ADR-0035). Re-exported so the published `kestrel.markets/protocol` entrypoint
 * carries the whole contract. Intra-protocol and dependency-free (asserted by
 * tests/protocol.boundary.test.ts): the acting Kernel is a STRUCTURAL MIRROR of
 * `src/frame/types.ts`, never an import. PURELY ADDITIVE — 0.2 → 0.3 touches no
 * existing shape (same rule catalog.ts and session.ts landed under).
 *  - ./oversight.ts — Caller / OversightIdentity, the acting Kernel as a protocol
 *    shape, the Book/Pod org, OversightFrame, the turn-stream, typed owner acts,
 *    the human-message channel, input resolution, the closed OversightEvent enum,
 *    and the OversightBackend seam.
 */
export * from "./oversight.js";
/* ─────────────────────────── offer terms (PLAT-ADR-0028 A1) ─────────────────────────── */
/**
 * The OfferTerms commercial-terms vocabulary, re-exported so the published
 * `kestrel.markets/protocol` entrypoint carries it (the {@link Offer.terms} field and the
 * plural {@link PaymentRequired.offers} alternatives reference it). Pure nouns/enums,
 * intra-protocol and dependency-free (asserted by tests/protocol.boundary.test.ts).
 */
export * from "./offer.js";
/* ─────────────────────────── wire shapes (OSS-ADR-0046) ─────────────────────────── */
/**
 * The hosted-service HTTP/SSE wire shapes, re-exported so `src/protocol` is the ONE
 * home for every wire shape this repo speaks (OSS-ADR-0046). Pure snake_case types +
 * the SSE `operation.*` const vocabulary + fail-closed decoders; intra-protocol and
 * dependency-free (asserted by tests/protocol.boundary.test.ts). The CLI transport
 * (`src/cli/backend/wire.ts`) re-exports THIS module rather than hand-copying it.
 */
export * from "./wire.js";
/* ─────────────────────────── attestation wire constants (OSS-ADR-0046, kestrel-s67u) ─────────────────────────── */
/**
 * The load-bearing WIRE constants of the signed grade root + receipt attestation label
 * (`GRADE_SIGN_PREFIX`, `JUDGE_ID`, `JUDGE_VERSION`, `FILL_MODEL_VERSION`, `ROOT_HASH_PREFIX`,
 * `VERIFY_KEYS_PATH`), the ONE dependency-free home both the platform signer and the OSS CLI
 * verifier import instead of re-declaring literals (OSS-ADR-0046 §2). Deliberately NOT gated on
 * `PROTOCOL_VERSION` — see the versioning note in `./attestation.ts`. A drift of any copy is a RED
 * conformance run, never a silent cross-repo verify break.
 */
export * from "./attestation.js";
/* ─────────────────────────── certified evidence + Judge (kestrel-h314) ─────────────────────────── */
/**
 * The fill-support partition + banking policy (kestrel-dpy / ADR-0014), PROMOTED onto the protocol
 * surface (kestrel-h314 D5) — `FillSupport`, `SupportPartition`, `partition`, `rawEv`, `bankableEvOf`,
 * `bankableEv`, `isCalibratedSupport`. Pure, intra-protocol, dependency-free. One source: the runtime's
 * `src/support/index.ts` and any self-hosted outsider read the SAME policy from here.
 */
export * from "./support.js";
/**
 * The one OSS-exported deterministic Judge (kestrel-h314 D4, CONTEXT "Judge"):
 * `grade(blotters) → GradeResult` over the PROTOCOL Blotter, emitting BOTH metric families over a shared
 * 1e-8 rounding grid. Fail-closed: a Blotter lacking the certified evidence is REFUSED the risk-honest
 * family (UNKNOWN + logged reason), never a silent zero.
 */
export * from "./grade.js";