@hyperscale0/hsx 2.4.1 → 3.0.0

package/src/parse.ts

@@ -1,1277 +1,471 @@
-import { udlClauseVocabulary } from "@hyperscale0/udl";
-
-const compoundClauseHeads = new Set(
-  udlClauseVocabulary
-    .filter((clause) => clause.spelling.includes(" "))
-    .map((clause) => clause.spelling.split(" ")[0]),
-);
-
-/**
- * The HSX parser. Recursive descent over the lexer's token stream, total:
- * it always returns a best-effort `Program` plus diagnostics, recovering at
- * the next top-level keyword after an error so one mistake never hides the
- * rest of the file. Diagnostics speak the author's language and point at
- * source spans.
- */
-
+import { lex, type Token } from "./lex.ts";
 import type {
-  ApplyExpr,
-  AssetDecl,
   BlockExpr,
-  ConstDecl,
-  Decl,
   Diagnostic,
   Entry,
   Expr,
-  ExposeDecl,
-  IdentExpr,
-  ImportDecl,
-  InstrumentApplyDecl,
-  InstrumentDecl,
-  ModuleDecl,
-  Parameter,
-  PartyDecl,
-  PortDecl,
   Program,
-  ProgramDecl,
   Span,
-  StringExpr,
-  SubjectDecl,
-  TypeDecl,
-  TypeParameter,
-  UseDecl,
 } from "./ast.ts";
-import { lex, type Token } from "./lex.ts";
-import { HSX_LIMITS } from "./limits.ts";
 
-export interface ParseResult {
-  readonly diagnostics: readonly Diagnostic[];
-  readonly program: Program;
+class ParseFailure extends Error {
+  constructor(readonly diagnostic: Diagnostic) {
+    super(diagnostic.message);
+  }
 }
-
-type BlockContext = "general" | "lifecycle";
-
-export function parseProgram(source: string): ParseResult {
-  // Measured before lexing. The ceiling counts UTF-8 bytes, so the encode is
-  // the measurement rather than an extra step: `source.length` counts UTF-16
-  // code units, which is a third of the size for CJK text.
-  const sourceBytes = new TextEncoder().encode(source).byteLength;
-  if (sourceBytes > HSX_LIMITS.maxSourceBytes) {
+export function parseProgram(source: string): {
+  program: Program;
+  diagnostics: Diagnostic[];
+} {
+  const empty: Program = {
+    name: "",
+    title: "",
+    currency: "SAR",
+    header: false,
+    decls: [],
+    span: { start: 0, end: source.length },
+  };
+  if (new TextEncoder().encode(source).length > 262144)
     return {
+      program: empty,
       diagnostics: [
         {
-          message: `this file is ${sourceBytes} bytes; HSX reads at most ${HSX_LIMITS.maxSourceBytes}`,
-          span: { end: 0, start: 0 },
+          code: "HSX1004",
+          message: "source exceeds 256 KiB",
+          fix: "split the program into headers",
+          span: empty.span,
         },
       ],
-      program: { decls: [], span: { end: 0, start: 0 } },
     };
-  }
-
-  const first = source.search(/\S/);
-  if (first >= 0 && source[first] === "{") {
+  const result = lex(source);
+  if (result.diagnostics.length)
+    return { program: empty, diagnostics: result.diagnostics };
+  try {
     return {
-      diagnostics: [
-        {
-          code: "HSX1014",
-          fix: "replace the JSON object with HSX declarations",
-          message: "JSON is not HSX",
-          span: { end: first + 1, start: first },
-        },
-      ],
-      program: { decls: [], span: { end: source.length, start: 0 } },
+      program: new Parser(result.tokens).program(empty),
+      diagnostics: [],
     };
+  } catch (error) {
+    if (error instanceof ParseFailure)
+      return { program: empty, diagnostics: [error.diagnostic] };
+    throw error;
   }
-
-  const lexed = lex(source);
-  const parser = new Parser(lexed.tokens, [...lexed.diagnostics]);
-  const program = parser.parseProgram(source.length);
-  return { diagnostics: parser.diagnostics, program };
 }
-
 class Parser {
-  readonly diagnostics: Diagnostic[];
-  private readonly tokens: readonly Token[];
   private index = 0;
   private depth = 0;
-
-  constructor(tokens: readonly Token[], diagnostics: Diagnostic[]) {
-    this.tokens = tokens;
-    this.diagnostics = diagnostics;
-  }
-
-  parseProgram(sourceLength: number): Program {
-    const decls: Decl[] = [];
-    while (!this.at("eof")) {
-      if (this.atPunct(";")) {
-        this.advance();
-        continue;
-      }
-      const decl = this.parseDecl();
-      if (decl) {
-        decls.push(decl);
-        continue;
-      }
-      this.recoverToDecl();
-    }
-    return { decls, span: { end: sourceLength, start: 0 } };
+  constructor(private readonly tokens: Token[]) {}
+  private peek(): Token {
+    return this.tokens[this.index]!;
   }
-
-  // --- Declarations --------------------------------------------------------
-
-  private parseDecl(exported = false): Decl | undefined {
+  private take(): Token {
     const token = this.peek();
-    if (token.kind !== "keyword" || token.text === "from") {
-      this.error(
-        token.span,
-        token.kind === "eof"
-          ? "the program ends unexpectedly"
-          : `expected a declaration (module, program, use, expose, import, party, asset, subject, instrument, settlement, type, const, or port), found "${token.text}"`,
-      );
-      return undefined;
-    }
-    switch (token.text) {
-      case "export":
-        this.advance();
-        return this.parseDecl(true);
-      case "module":
-        return this.parseModuleDecl(exported);
-      case "program":
-        return this.parseProgramDecl();
-      case "use":
-        return this.parseUseDecl();
-      case "expose":
-        return this.parseExposeDecl();
-      case "import":
-        return this.parseImportDecl();
-      case "party":
-        return this.parsePartyDecl();
-      case "asset":
-        return this.parseAssetDecl();
-      case "subject":
-        return this.parseSubjectDecl(exported);
-      case "instrument":
-        return this.parseInstrumentDecl(exported);
-      case "settlement":
-        return this.parseSettlementDecl();
-      case "port":
-        return this.parsePortDecl();
-      case "type":
-        return this.parseTypeDecl(exported);
-      case "const":
-        return this.parseConstDecl(exported);
-      default:
-        this.error(token.span, `"${token.text}" cannot start a declaration`);
-        this.advance();
-        return undefined;
-    }
-  }
-
-  private parseModuleDecl(exported: boolean): ModuleDecl | undefined {
-    const start = this.advance();
-    if (exported) {
-      this.error(start.span, "a module declaration cannot be exported");
-    }
-    const name = this.parsePath("the module needs a dotted name");
-    return name
-      ? { kind: "module", name, span: this.spanFrom(start.span) }
-      : undefined;
-  }
-
-  private parseInstrumentDecl(
-    exported: boolean,
-  ): InstrumentDecl | InstrumentApplyDecl | undefined {
-    const start = this.advance();
-    const name = this.expectIdent("the instrument needs a snake_case name");
-    if (!name) return undefined;
-    const typeParameters = this.parseTypeParameters();
-    if (!typeParameters) return undefined;
-    const hasParameterList = this.atPunct("(");
-    const parameters = hasParameterList ? this.parseParameters() : [];
-    if (!parameters) return undefined;
-    if (this.atPunct("=")) {
-      this.advance();
-      const application = this.parseApplication();
-      if (!application) return undefined;
-      const metadata = this.atPunct("{") ? this.parseBlock() : undefined;
-      return {
-        application,
-        exported,
-        kind: "instrument_apply",
-        ...(metadata ? { metadata } : {}),
-        name,
-        span: this.spanFrom(start.span),
-      };
-    }
-    if (!this.atPunct("{")) {
-      this.error(
-        this.peek().span,
-        `instrument ${name.name} needs a body or an exported instrument application`,
-      );
-      return undefined;
-    }
-    const body = this.parseBlock();
-    if (!body) return undefined;
-    return {
-      body,
-      exported,
-      hasParameterList,
-      kind: "instrument",
-      name,
-      parameters,
-      span: this.spanFrom(start.span),
-      typeParameters,
-    };
-  }
-
-  private parseTypeDecl(exported: boolean): TypeDecl | undefined {
-    const start = this.advance();
-    const name = this.expectIdent("the type needs a name");
-    if (!name) return undefined;
-    if (
-      !this.expectPunct("=", `type ${name.name} needs = before its definition`)
-    ) {
-      return undefined;
-    }
-    const value = this.parseExpr();
-    return value
-      ? { exported, kind: "type", name, span: this.spanFrom(start.span), value }
-      : undefined;
-  }
-
-  private parseConstDecl(exported: boolean): ConstDecl | undefined {
-    const start = this.advance();
-    const name = this.expectIdent("the constant needs a name");
-    if (!name) return undefined;
-    let type: Expr | undefined;
-    if (this.atPunct(":")) {
-      this.advance();
-      type = this.parseExpr();
-      if (!type) return undefined;
-    }
-    if (!this.expectPunct("=", `const ${name.name} needs = before its value`)) {
-      return undefined;
-    }
-    const value = this.parseExpr();
-    return value
-      ? {
-          exported,
-          kind: "const",
-          name,
-          span: this.spanFrom(start.span),
-          ...(type ? { type } : {}),
-          value,
-        }
-      : undefined;
-  }
-
-  private parseTypeParameters(): TypeParameter[] | undefined {
-    if (!this.atPunct("<")) return [];
-    this.advance();
-    const parameters: TypeParameter[] = [];
-    while (!this.atPunct(">") && !this.at("eof")) {
-      const name = this.expectIdent("expected a type parameter");
-      if (!name) return undefined;
-      parameters.push({ name, span: name.span });
-      if (this.atPunct(",")) this.advance();
-    }
-    return this.expectPunct(">", "the type parameter list never closes")
-      ? parameters
-      : undefined;
-  }
-
-  private parseParameters(): Parameter[] | undefined {
-    this.advance();
-    const parameters: Parameter[] = [];
-    while (!this.atPunct(")") && !this.at("eof")) {
-      const name = this.expectIdent("expected a parameter name");
-      if (!name) return undefined;
-      if (!this.expectPunct(":", `parameter ${name.name} needs a type`)) {
-        return undefined;
-      }
-      const type = this.parseExpr();
-      if (!type) return undefined;
-      parameters.push({
-        name,
-        span: { start: name.span.start, end: type.span.end },
-        type,
-      });
-      if (this.atPunct(",")) this.advance();
-    }
-    return this.expectPunct(")", "the parameter list never closes")
-      ? parameters
-      : undefined;
-  }
-
-  private parseProgramDecl(): ProgramDecl | undefined {
-    const start = this.advance();
-    const name = this.expectIdent("the program needs a snake_case name");
-    if (!name) return undefined;
-    let title: StringExpr | undefined;
-    if (this.at("string")) {
-      const token = this.advance();
-      title = { kind: "string", span: token.span, value: token.value };
-    }
-    return {
-      kind: "program",
-      name,
-      span: this.spanFrom(start.span),
-      ...(title ? { title } : {}),
-    };
-  }
-
-  private parseUseDecl(): UseDecl | undefined {
-    const start = this.advance();
-    const instrument = this.expectIdent(
-      "use needs a published instrument id, like: use held_settlement",
-    );
-    return instrument
-      ? { instrument, kind: "use", span: this.spanFrom(start.span) }
-      : undefined;
-  }
-
-  private parseExposeDecl(): ExposeDecl | undefined {
-    const start = this.advance();
-    const instrument = this.expectIdent(
-      "expose needs an instrument action, like: expose held_settlement.release as releaseFunds",
-    );
-    if (!instrument) return undefined;
-    if (
-      !this.expectPunct(
-        ".",
-        "expose separates the instrument and action with .",
-      )
-    ) {
-      return undefined;
-    }
-    const action = this.expectName(
-      "expose needs an action after the instrument id",
-    );
-    if (!action) return undefined;
-    if (!this.at("keyword") || this.peek().text !== "as") {
-      this.error(
-        this.peek().span,
-        "expose needs as before its public action name",
-      );
-      return undefined;
-    }
-    this.advance();
-    const publicName = this.expectIdent(
-      "expose needs a camelCase public action name",
-    );
-    return publicName
-      ? {
-          action,
-          instrument,
-          kind: "expose",
-          publicName,
-          span: this.spanFrom(start.span),
-        }
-      : undefined;
-  }
-
-  private parseImportDecl(): ImportDecl | undefined {
-    const start = this.advance();
-    if (
-      !this.expectPunct(
-        "{",
-        'import lists its names in braces: import { held_payment } from "std/money_flows"',
-      )
-    ) {
-      return undefined;
-    }
-    const names: IdentExpr[] = [];
-    while (!this.atPunct("}") && !this.at("eof")) {
-      const name = this.expectIdent("expected an imported name");
-      if (!name) return undefined;
-      names.push(name);
-      if (this.atPunct(",")) this.advance();
-    }
-    if (!this.expectPunct("}", "the import name list never closes")) {
-      return undefined;
-    }
-    if (!this.at("keyword") || this.peek().text !== "from") {
-      this.error(
-        this.peek().span,
-        'import needs from: import { held_payment } from "std/money_flows"',
-      );
-      return undefined;
-    }
-    this.advance();
-    if (!this.at("string")) {
-      this.error(
-        this.peek().span,
-        'the import source must be a quoted module name like "std/money_flows"',
-      );
-      return undefined;
-    }
-    const sourceToken = this.advance();
-    if (names.length === 0) {
-      this.error(start.span, "import brings in at least one name");
-    }
-    return {
-      from: {
-        kind: "string",
-        span: sourceToken.span,
-        value: sourceToken.value,
-      },
-      kind: "import",
-      names,
-      span: this.spanFrom(start.span),
-    };
-  }
-
-  private parsePartyDecl(): PartyDecl | undefined {
-    const start = this.advance();
-    const name = this.expectIdent(
-      "the party needs a name, like: party buyer: person",
-    );
-    if (!name) return undefined;
-    if (
-      !this.expectPunct(
-        ":",
-        `party ${name.name} needs a kind, like: party ${name.name}: person`,
-      )
-    ) {
-      return undefined;
-    }
-    const partyKind = this.expectIdent(
-      `expected a kind for party ${name.name}`,
-    );
-    if (!partyKind) return undefined;
-    const attrs = this.atPunct("{") ? this.parseBlock() : undefined;
-    return {
-      ...(attrs ? { attrs } : {}),
-      kind: "party",
-      name,
-      partyKind,
-      span: this.spanFrom(start.span),
-    };
-  }
-
-  private parseAssetDecl(): AssetDecl | undefined {
-    const start = this.advance();
-    const name = this.expectIdent(
-      "the asset needs a name, like: asset vehicle: good",
-    );
-    if (!name) return undefined;
-    if (
-      !this.expectPunct(
-        ":",
-        `asset ${name.name} needs a kind, like: asset ${name.name}: good`,
-      )
-    ) {
-      return undefined;
-    }
-    const assetKind = this.expectIdent(
-      `expected a kind for asset ${name.name}`,
-    );
-    if (!assetKind) return undefined;
-    const attrs = this.atPunct("{") ? this.parseBlock() : undefined;
-    return {
-      assetKind,
-      ...(attrs ? { attrs } : {}),
-      kind: "asset",
-      name,
-      span: this.spanFrom(start.span),
-    };
-  }
-
-  private parseSubjectDecl(exported: boolean): SubjectDecl | undefined {
-    const start = this.advance();
-    if (exported) {
-      this.error(start.span, "a subject declaration cannot be exported");
-    }
-    const name = this.expectIdent("the subject needs a snake_case kind name");
-    if (!name) return undefined;
-    if (!this.atPunct("{")) {
-      this.error(this.peek().span, `subject ${name.name} needs a body`);
-      return undefined;
-    }
-    const body = this.parseBlock();
-    return body
-      ? { body, kind: "subject", name, span: this.spanFrom(start.span) }
-      : undefined;
-  }
-
-  private parseSettlementDecl(): InstrumentApplyDecl | undefined {
-    const start = this.advance();
-    const name = this.expectIdent(
-      "the settlement needs a name, like: settlement sale = held_payment { ... }",
-    );
-    if (!name) return undefined;
-    if (
-      !this.expectPunct(
-        "=",
-        `settlement ${name.name} instantiates a module: settlement ${name.name} = held_payment { ... }`,
-      )
-    ) {
-      return undefined;
-    }
-    const moduleName = this.expectIdent(
-      `expected a module name for settlement ${name.name}`,
-    );
-    if (!moduleName) return undefined;
-    if (!this.atPunct("{")) {
-      this.error(
-        this.peek().span,
-        `settlement ${name.name} needs a body in braces`,
-      );
-      return undefined;
-    }
-    const body = this.parseBlock();
-    if (!body) return undefined;
-    return {
-      application: {
-        args: body.entries.map((row) => ({
-          kind: "binding" as const,
-          name: row.key,
-          span: row.value.span,
-          type: row.value,
-        })),
-        callee: { kind: "path", parts: [moduleName], span: moduleName.span },
-        kind: "apply",
-        span: { start: moduleName.span.start, end: body.span.end },
-        typeArgs: [],
-      },
-      exported: false,
-      kind: "instrument_apply",
-      name,
-      span: this.spanFrom(start.span),
-    };
+    if (token.kind !== "eof") this.index++;
+    return token;
   }
-
-  private parsePortDecl(): PortDecl | undefined {
-    const start = this.advance();
-    const name = this.expectIdent(
-      "the port needs a name, like: port confirm_handover { ... }",
-    );
-    if (!name) return undefined;
-    if (!this.atPunct("{")) {
-      this.error(this.peek().span, `port ${name.name} needs a body in braces`);
-      return undefined;
-    }
-    const body = this.parseBlock();
-    if (!body) return undefined;
-    return { body, kind: "port", name, span: this.spanFrom(start.span) };
+  private at(text: string): boolean {
+    return this.peek().text === text;
   }
-
-  // --- Entries and expressions ---------------------------------------------
-
-  /**
-   * Every recursive edge in the grammar passes through `parseExpr` or
-   * `parseBlock`: the list, block, call-argument, and binding-type branches of
-   * one, and the block to entry to block cycle of the other. Guarding those
-   * two entry points is therefore the whole ceiling, and the guard lives in
-   * one place instead of five.
-   *
-   * The budget counts those entries, not source levels, and the two are not
-   * the same number: `k { ... }` spends one per level, while `k: { ... }`
-   * spends two because the colon branch enters `parseExpr` and `parseExpr`
-   * then enters `parseBlock`. So the message names a budget rather than a
-   * depth. A builder told they exceeded "64 levels" would count 32 braces and
-   * have nothing to act on.
-   */
-  private enterNesting(span: Span): boolean {
-    if (this.depth >= HSX_LIMITS.maxNestingDepth) {
-      this.error(
-        span,
-        `this nests past the parser's depth budget of ${HSX_LIMITS.maxNestingDepth}; flatten it`,
-      );
-      return false;
-    }
-    this.depth += 1;
+  private eat(text: string): boolean {
+    if (!this.at(text)) return false;
+    this.take();
     return true;
   }
-
-  private parseBlock(context: BlockContext = "general"): BlockExpr | undefined {
-    if (!this.enterNesting(this.peek().span)) return undefined;
-    const block = this.parseBlockUnguarded(context);
-    this.depth -= 1;
-    return block;
+  private fail(message: string, fix: string): never {
+    throw new ParseFailure({
+      code: "HSX1000",
+      message,
+      fix,
+      span: this.peek().span,
+    });
+  }
+  private expect(text: string): void {
+    if (!this.eat(text))
+      this.fail(
+        `expected ${text}, found ${this.peek().text || "end of file"}`,
+        `write ${text} here`,
+      );
   }
-
-  private parseBlockUnguarded(context: BlockContext): BlockExpr | undefined {
-    const open = this.advance();
-    const entries: Entry[] = [];
-    while (!this.atPunct("}") && !this.at("eof")) {
-      if (this.atPunct(";") || this.atPunct(",")) {
-        this.advance();
+  private identifier(): string {
+    if (this.peek().kind !== "name")
+      this.fail("expected a name", "write a name starting with a letter");
+    return this.take().text;
+  }
+  private path(): string {
+    let name = this.identifier();
+    while (this.eat(".")) name += "." + this.identifier();
+    return name;
+  }
+  private separators(): void {
+    while (this.eat(",") || this.eat(";")) {}
+  }
+  private span(start: number): Span {
+    return { start, end: this.tokens[Math.max(0, this.index - 1)]!.span.end };
+  }
+  program(program: Program): Program {
+    if (this.eat("header")) program.header = true;
+    else this.expect("program");
+    program.name = this.identifier();
+    if (!program.header) {
+      if (this.peek().kind !== "string")
+        this.fail(
+          "program needs a title",
+          "write a quoted title after its name",
+        );
+      program.title = JSON.parse(this.take().text) as string;
+    }
+    while (this.peek().kind !== "eof") {
+      this.separators();
+      if (this.peek().kind === "eof") break;
+      const start = this.peek().span.start;
+      if (this.eat("currency")) {
+        program.currency = this.identifier();
         continue;
       }
-      const before = this.index;
-      const entry = this.parseEntry(context);
-      if (!entry) {
-        this.recoverInBlock();
-        // recoverInBlock bails without consuming when it lands on a depth-0
-        // keyword (e.g. `from` used as an entry key), and a failed
-        // parseEntry may not have consumed either. Without forced progress
-        // this loop never terminates.
-        if (this.index === before) this.advance();
+      if (this.eat("use")) {
+        program.decls.push({
+          kind: "use",
+          name: this.identifier(),
+          span: this.span(start),
+        });
         continue;
       }
-      entries.push(entry);
-      if (this.atPunct(",") || this.atPunct(";")) this.advance();
-    }
-    if (!this.expectPunct("}", "this block never closes; add the matching }")) {
-      return { entries, kind: "block", span: this.spanFrom(open.span) };
-    }
-    return { entries, kind: "block", span: this.spanFrom(open.span) };
-  }
-
-  private parseEntry(context: BlockContext): Entry | undefined {
-    const token = this.peek();
-    const key =
-      token.kind === "string"
-        ? (() => {
-            this.advance();
-            return {
-              kind: "ident" as const,
-              name: token.value,
-              quoted: !token.value.includes("["),
-              span: token.span,
-            };
-          })()
-        : this.isName(token) && (token.text === "action" || token.text === "on")
-          ? this.parseIdent()
-          : this.parseTemplatedName("expected an entry name here");
-    if (!key) return undefined;
-
-    const qualifiers: IdentExpr[] = [];
-    if (key.name === "for") {
-      const binding = this.expectIdent("for needs a compile-time binding name");
-      const inWord = binding
-        ? this.expectName("for needs in before its finite bound")
-        : undefined;
-      if (!binding || inWord?.name !== "in") {
-        this.error(
-          this.peek().span,
-          "write `for item in <finite bound> { ... }`",
-        );
-        return undefined;
+      if (this.eat("party")) {
+        const name = this.identifier();
+        this.expect(":");
+        const partyKind = this.identifier();
+        const role = this.eat("role") ? this.identifier() : undefined;
+        program.decls.push({
+          kind: "party",
+          name,
+          partyKind,
+          ...(role ? { role } : {}),
+          span: this.span(start),
+        });
+        continue;
       }
-      const bound = this.parseExpr();
-      if (!bound || !this.atPunct("{")) {
-        this.error(
-          this.peek().span,
-          "a bounded comprehension needs a body in braces",
+      if (this.at("expose") || this.at("hide")) {
+        const kind = this.take().text as "expose" | "hide";
+        const target = this.path();
+        let name: string | undefined;
+        if (kind === "expose") {
+          this.expect("as");
+          name = this.identifier();
+        }
+        program.decls.push(
+          kind === "expose"
+            ? { kind, target, name: name!, span: this.span(start) }
+            : { kind, target, span: this.span(start) },
         );
-        return undefined;
+        continue;
       }
-      const value = this.parseBlock(context);
-      return value
-        ? {
-            iteration: { binding, bound },
-            key,
-            qualifiers,
-            span: { start: key.span.start, end: value.span.end },
-            value,
-          }
-        : undefined;
-    }
-    if (
-      key.name === "action" &&
-      (this.isName(this.peek()) || this.atPunct("["))
-    ) {
-      const action = this.parseTemplatedName("action needs a name");
-      if (!action) return undefined;
-      qualifiers.push(action);
-      if (!this.atPunct("{")) {
-        this.error(
-          this.peek().span,
-          `action ${qualifiers[0]?.name ?? ""} needs a body`,
-        );
-        return undefined;
+      if (this.eat("instrument")) {
+        const name = this.identifier();
+        const parameters = this.eat("(") ? this.entries(")") : [];
+        const body = this.block();
+        program.decls.push({
+          kind: "instrument",
+          name,
+          parameters,
+          body,
+          span: this.span(start),
+        });
+        continue;
       }
-      const value = this.parseBlock();
-      return value
-        ? {
-            key,
-            qualifiers,
-            span: { start: key.span.start, end: value.span.end },
-            value,
-          }
-        : undefined;
+      const name = this.identifier();
+      this.expect("=");
+      const object = this.path();
+      const body = this.block();
+      program.decls.push({
+        kind: "object",
+        name,
+        object,
+        body,
+        span: this.span(start),
+      });
     }
-    if (context === "lifecycle" && key.name === "states") {
-      const items: Expr[] = [];
-      while (!this.atPunct(";") && !this.atPunct("}") && !this.at("eof")) {
-        const state = this.parseTemplatedName("expected a lifecycle state");
-        if (!state) return undefined;
-        items.push(state);
+    return program;
+  }
+  private entries(end: string): Entry[] {
+    const entries: Entry[] = [];
+    while (!this.eat(end)) {
+      this.separators();
+      if (this.eat(end)) break;
+      if (this.peek().kind === "eof")
+        this.fail(`unclosed block, expected ${end}`, `add ${end}`);
+      const start = this.peek().span.start;
+      let key = this.path();
+      if (key === "action" && !this.at(":")) key += " " + this.identifier();
+      if (key === "when") {
+        const tunable = this.identifier();
+        this.expect("is");
+        const choice = this.identifier();
+        entries.push({
+          key: `when ${tunable} is ${choice}`,
+          value: this.block(),
+          span: this.span(start),
+        });
+        continue;
       }
-      const end = items.at(-1)?.span.end ?? key.span.end;
-      return {
+      const clause = ["requires", "invariants", "moves"].includes(key);
+      const value =
+        clause && !this.at(":") && !this.at("{")
+          ? {
+              kind: "list" as const,
+              items: [key === "moves" ? this.move() : this.requirement()],
+              span: this.span(start),
+            }
+          : this.at("{")
+            ? this.block()
+            : (this.expect(":"), this.expression());
+      entries.push({ key, value, span: this.span(start) });
+      this.separators();
+    }
+    return entries;
+  }
+  private node(value: string): Expr {
+    return { kind: "text", value, span: this.peek().span };
+  }
+  private record(values: Record<string, Expr>): BlockExpr {
+    const span = this.peek().span;
+    return {
+      kind: "block",
+      entries: Object.entries(values).map(([key, value]) => ({
         key,
-        qualifiers,
-        span: { start: key.span.start, end },
-        value: { items, kind: "list", span: { start: key.span.end, end } },
+        value,
+        span: value.span,
+      })),
+      span,
+    };
+  }
+  private operand(): BlockExpr {
+    const value = this.atom();
+    return this.record({
+      [value.kind === "name" && /^(self|input|party)\./.test(value.value)
+        ? "field"
+        : "literal"]: value,
+    });
+  }
+  private operator(): Expr {
+    const operator = this.take();
+    if (!["==", "!=", "<", "<=", ">", ">="].includes(operator.text))
+      this.fail("expected a comparison", "write ==, !=, <, <=, >, or >=");
+    return this.node(operator.text);
+  }
+  private requirement(): BlockExpr {
+    if (this.eat("approval")) {
+      this.expect("by");
+      const party = this.atom();
+      const values: Record<string, Expr> = {
+        kind: this.node("approval"),
+        party,
+        decision: this.node("approved"),
       };
+      if (this.eat("for")) values.action = this.atom();
+      if (this.eat("is")) values.decision = this.atom();
+      return this.record(values);
+    }
+    if (this.eat("unique")) {
+      const namespace = this.atom();
+      this.expect("on");
+      return this.record({
+        kind: this.node("unique"),
+        namespace,
+        fields: this.atom(),
+      });
     }
-    if (context === "lifecycle" && key.name === "initial") {
-      const value = this.parseTemplatedName(
-        "initial needs one declared lifecycle state",
-      );
-      return value
-        ? {
-            key,
-            qualifiers,
-            span: { start: key.span.start, end: value.span.end },
-            value,
-          }
-        : undefined;
-    }
-    if (context === "lifecycle" && key.name === "parked") {
-      const state = this.parseTemplatedName("parked needs a lifecycle state");
-      if (!state) return undefined;
-      qualifiers.push(state);
-      const reasonWord = this.expectName('parked needs reason "..."');
-      if (!reasonWord || reasonWord.name !== "reason" || !this.at("string")) {
-        this.error(this.peek().span, 'parked needs reason "..."');
-        return undefined;
-      }
-      const token = this.advance();
-      const value: StringExpr = {
-        kind: "string",
-        span: token.span,
-        value: token.value,
-      };
-      return {
-        key,
-        qualifiers,
-        span: { start: key.span.start, end: value.span.end },
+    if (this.at("count") || this.at("sum")) {
+      const measure = this.eat("count")
+        ? this.node("count")
+        : (this.expect("sum"), this.record({ sum: this.atom() }));
+      this.expect("of");
+      const selection = this.block();
+      const operator = this.operator();
+      const value = this.operand();
+      return this.record({
+        kind: this.node("aggregate"),
+        selection,
+        measure,
+        operator,
         value,
-      };
+      });
     }
-    if (context === "lifecycle" && key.name === "on") {
-      const action = this.parseTemplatedName("on needs an action name");
-      if (!action) return undefined;
-      qualifiers.push(action);
-      if (
-        !this.expectPunct(
-          ":",
-          `on ${action.name} needs : before its source states`,
-        )
-      ) {
-        return undefined;
-      }
-      while (!this.atPunct("->") && !this.at("eof")) {
-        const state = this.parseTemplatedName(
-          "expected a source lifecycle state",
-        );
-        if (!state) return undefined;
-        qualifiers.push(state);
-        if (this.atPunct("|")) this.advance();
-      }
-      if (
-        !this.expectPunct(
-          "->",
-          `on ${action.name} needs -> before its target state`,
-        )
-      ) {
-        return undefined;
-      }
-      const value = this.parseTemplatedName(
-        "expected a target lifecycle state",
-      );
-      return value
-        ? {
-            key,
-            qualifiers,
-            span: { start: key.span.start, end: value.span.end },
-            value,
-          }
-        : undefined;
+    if (this.eat("hours")) {
+      const at = this.atom();
+      this.expect("between");
+      const start = this.atom();
+      this.expect("and");
+      const end = this.atom();
+      this.expect("timezone");
+      return this.record({
+        kind: this.node("hours"),
+        at,
+        start,
+        end,
+        timezone: this.atom(),
+      });
     }
-    if (key.name === "notify") {
-      const role = this.expectName("notify needs a declared role");
-      const via = role
-        ? this.expectName("notify needs via before its channel")
-        : undefined;
-      const channel = via
-        ? this.expectName("notify needs a channel")
-        : undefined;
-      if (!role || via?.name !== "via" || !channel) return undefined;
-      qualifiers.push(role, channel);
-      return {
-        key,
-        qualifiers,
-        span: { start: key.span.start, end: channel.span.end },
-        value: { kind: "boolean", span: channel.span, value: true },
+    if (this.eat("evidence")) {
+      const subject = this.atom();
+      const values: Record<string, Expr> = {
+        kind: this.node("evidence"),
+        subject,
       };
-    }
-    if (this.atPunct("(")) {
-      this.advance();
-      while (!this.atPunct(")") && !this.at("eof")) {
-        const qualifier = this.at("number")
-          ? this.parseIdent()
-          : this.expectIdent(`expected a qualifier inside ${key.name}( ... )`);
-        if (!qualifier) return undefined;
-        qualifiers.push(qualifier);
-        if (this.atPunct(",")) this.advance();
+      for (const key of ["family", "check", "result", "maxAge"]) {
+        this.expect(key);
+        values[key] = this.atom();
       }
-      if (!this.expectPunct(")", `${key.name}( ... ) never closes`)) {
-        return undefined;
-      }
-    }
-
-    if (compoundClauseHeads.has(key.name) && this.isName(this.peek())) {
-      while (this.isName(this.peek())) qualifiers.push(this.parseIdent());
+      return this.record(values);
+    }
+    const left = this.operand();
+    if (this.eat("in")) {
+      const reference = left.entries.find(
+        (entry) => entry.key === "field",
+      )?.value;
+      if (!reference)
+        this.fail(
+          "state requirement needs a reference",
+          "write requires self.record in [state]",
+        );
+      return this.record({
+        kind: this.node("state"),
+        reference,
+        states: this.atom(),
+      });
     }
-
-    let value: Expr | undefined;
-    if (this.atPunct("{")) {
-      value = this.parseBlock(
-        key.name === "lifecycle" || context === "lifecycle"
-          ? "lifecycle"
-          : "general",
-      );
-    } else if (this.atPunct(":")) {
-      this.advance();
-      value = this.atPunct("{")
-        ? this.parseBlock(
-            key.name === "lifecycle" || context === "lifecycle"
-              ? "lifecycle"
-              : "general",
-          )
-        : this.parseExpr();
-    } else if (this.canStartExpr(this.peek())) {
-      value = this.parseExpr();
+    const operator = this.operator();
+    return this.record({
+      kind: this.node("compare"),
+      left,
+      operator,
+      right: this.operand(),
+    });
+  }
+  private move(): BlockExpr {
+    const values: Record<string, Expr> = {};
+    if (this.at("post") || this.at("void")) {
+      values.operation = this.node("internal_transfer." + this.take().text);
+      values.transfer = this.atom();
     } else {
-      this.error(
-        this.peek().span,
-        `entry ${key.name} needs a value: either "${key.name}: <value>" or "${key.name} { ... }"`,
-      );
-      return undefined;
+      if (this.eat("reserve"))
+        values.operation = this.node("internal_transfer.reserve");
+      values.amount = this.atom();
+      this.expect("from");
+      values.from = this.atom();
+      if (this.eat("to")) values.to = this.atom();
+      else {
+        this.expect("shares");
+        values.shares = this.atom();
+      }
     }
-    if (!value) return undefined;
-    return {
-      key,
-      qualifiers,
-      span: { end: value.span.end, start: key.span.start },
-      value,
-    };
-  }
-
-  private parseExpr(): Expr | undefined {
-    if (!this.enterNesting(this.peek().span)) return undefined;
-    const expr = this.parseExprUnguarded();
-    this.depth -= 1;
-    return expr;
+    for (const key of ["fee", "capture", "key"])
+      if (this.eat(key)) values[key] = this.atom();
+    return this.record(values);
+  }
+  private block(): BlockExpr {
+    const start = this.peek().span.start;
+    this.expect("{");
+    if (++this.depth > 32)
+      this.fail("block nesting exceeds 32", "reduce nested blocks");
+    const entries = this.entries("}");
+    this.depth--;
+    return { kind: "block", entries, span: this.span(start) };
+  }
+  private expression(): Expr {
+    if (++this.depth > 32)
+      this.fail("expression nesting exceeds 32", "reduce nested values");
+    const start = this.peek().span.start;
+    let value = this.atom();
+    if (this.eat("cap"))
+      value = {
+        kind: "capped",
+        rate: value,
+        cap: this.atom(),
+        span: this.span(start),
+      };
+    if (this.eat("="))
+      value = {
+        kind: "default",
+        type: value,
+        value: this.expression(),
+        span: this.span(start),
+      };
+    this.depth--;
+    return value;
   }
-
-  private parseExprUnguarded(): Expr | undefined {
+  private atom(): Expr {
     const token = this.peek();
-
-    if (token.kind === "string") {
-      this.advance();
-      return { kind: "string", span: token.span, value: token.value };
-    }
-    if (token.kind === "number") {
-      this.advance();
-      return { kind: "number", raw: token.value, span: token.span };
-    }
-    if (token.kind === "percent") {
-      this.advance();
-      const bps = percentToBps(token.value);
-      if (bps === undefined) {
-        this.error(
-          token.span,
-          `${token.text} is finer than the money system can settle; percents go down to a hundredth (basis point), like 99.75%`,
-        );
-        return { bps: 0, kind: "percent", raw: token.value, span: token.span };
-      }
-      return { bps, kind: "percent", raw: token.value, span: token.span };
-    }
-    if (this.atPunct("[")) {
-      const open = this.advance();
+    const start = token.span.start;
+    if (this.at("{")) return this.block();
+    if (this.eat("[")) {
       const items: Expr[] = [];
-      while (!this.atPunct("]") && !this.at("eof")) {
-        const item = this.parseExpr();
-        if (!item) return undefined;
-        items.push(item);
-        if (this.atPunct(",")) this.advance();
+      while (!this.eat("]")) {
+        if (this.peek().kind === "eof") this.fail("unclosed list", "add ]");
+        items.push(this.expression());
+        this.separators();
       }
-      if (
-        !this.expectPunct("]", "this list never closes; add the matching ]")
-      ) {
-        return undefined;
-      }
-      return { items, kind: "list", span: this.spanFrom(open.span) };
-    }
-    if (this.atPunct("{")) {
-      return this.parseBlock();
+      return { kind: "list", items, span: this.span(start) };
     }
-    if (token.kind === "keyword" && token.text === "port") {
-      const start = this.advance();
-      const name = this.expectIdent(
-        "expected a port name after the port keyword",
-      );
-      if (!name) return undefined;
-      let within: IdentExpr | undefined;
-      if (this.at("ident") && this.peek().text === "within") {
-        this.advance();
-        within = this.expectIdent(
-          "expected a fixed duration after within, like P14D",
-        );
-        if (!within) return undefined;
-      }
-      let deadline: IdentExpr | undefined;
-      if (this.atPunct("|")) {
-        this.advance();
-        if (!this.at("ident") || this.peek().text !== "at") {
-          this.error(
-            this.peek().span,
-            "after | comes the date the platform decides on, like: | at(releaseDueAt)",
-          );
-          return undefined;
-        }
-        this.advance();
-        if (
-          !this.expectPunct(
-            "(",
-            "at names its date field in parentheses: at(releaseDueAt)",
-          )
-        ) {
-          return undefined;
-        }
-        deadline = this.expectIdent(
-          "expected a stored date field inside at( ... ), like at(releaseDueAt)",
-        );
-        if (!deadline) return undefined;
-        if (!this.expectPunct(")", "at( ... ) never closes")) return undefined;
-      }
-      return {
-        ...(deadline ? { deadline } : {}),
-        kind: "port_ref",
-        name,
-        span: this.spanFrom(start.span),
-        ...(within ? { within } : {}),
-      };
-    }
-    if (token.kind === "keyword") {
-      return this.parseIdent();
-    }
-    if (
-      token.kind === "ident" &&
-      /^[A-Z]{3}$/.test(token.text) &&
-      this.peekAt(1).kind === "number"
-    ) {
-      const currency = this.parseIdent();
-      const amount = this.advance();
-      return {
-        currency,
-        kind: "money",
-        raw: amount.value,
-        span: { start: currency.span.start, end: amount.span.end },
-      };
-    }
-    if (token.kind === "ident") {
-      const ident = this.parseIdent();
-      if (ident.name === "true" || ident.name === "false") {
-        return {
-          kind: "boolean",
-          span: ident.span,
-          value: ident.name === "true",
-        };
-      }
-      if (ident.name === "decided" && this.atPunct("{")) {
-        const body = this.parseBlock();
-        if (!body) return undefined;
-        return {
-          body,
-          kind: "decided_amount",
-          span: { end: body.span.end, start: ident.span.start },
-        };
-      }
-      if (this.atPunct(".")) {
-        this.advance();
-        const member = this.expectIdent(
-          `expected the exit after ${ident.name}., like ${ident.name}.release`,
-        );
-        if (!member) return undefined;
-        return {
-          kind: "settlement_ref",
-          member,
-          owner: ident,
-          span: { end: member.span.end, start: ident.span.start },
-        };
-      }
-      if (this.atPunct("<")) {
-        const args = this.parseAngleArguments();
-        if (!args) return undefined;
-        return {
-          args,
-          callee: ident,
-          kind: "type_apply",
-          span: this.spanFrom(ident.span),
-        };
-      }
-      if (this.atPunct("(")) {
-        this.advance();
-        const args: Expr[] = [];
-        while (!this.atPunct(")") && !this.at("eof")) {
-          const arg = this.parseExpr();
-          if (!arg) return undefined;
-          args.push(arg);
-          if (this.atPunct(",")) this.advance();
-        }
-        if (!this.expectPunct(")", `${ident.name}( ... ) never closes`)) {
-          return undefined;
-        }
+    if (token.kind === "number") {
+      this.take();
+      if (token.text.endsWith("%"))
         return {
-          args,
-          callee: ident,
-          kind: "call",
-          span: this.spanFrom(ident.span),
+          kind: "percent",
+          value: token.text.slice(0, -1),
+          span: token.span,
         };
-      }
-      if (this.atPunct(":")) {
-        this.advance();
-        const type = this.parseExpr();
-        if (!type) return undefined;
+      if (/[a-z]$/.test(token.text))
+        return { kind: "duration", value: token.text, span: token.span };
+      if (/^[A-Z]{3}$/.test(this.peek().text)) {
+        const currency = this.take().text;
         return {
-          kind: "binding",
-          name: ident,
-          span: { end: type.span.end, start: ident.span.start },
-          type,
+          kind: "money",
+          value: token.text + " " + currency,
+          span: this.span(start),
         };
       }
-      return ident;
-    }
-
-    this.error(
-      token.span,
-      token.kind === "eof"
-        ? "the program ends where a value was expected"
-        : `"${token.text}" is not a value HSX understands here`,
-    );
-    return undefined;
-  }
-
-  // --- Recovery ------------------------------------------------------------
-
-  private recoverToDecl(): void {
-    while (!this.at("eof")) {
-      const token = this.peek();
-      if (token.kind === "keyword" && token.text !== "from") return;
-      this.advance();
+      return { kind: "number", value: token.text, span: token.span };
     }
-  }
-
-  /** Skip to the next plausible entry start or the end of the block. */
-  private recoverInBlock(): void {
-    let depth = 0;
-    while (!this.at("eof")) {
-      const token = this.peek();
-      if (token.kind === "punct") {
-        if (token.text === "{" || token.text === "[" || token.text === "(")
-          depth += 1;
-        if (token.text === "}" || token.text === "]" || token.text === ")") {
-          if (depth === 0) return;
-          depth -= 1;
-        }
-        if (token.text === "," && depth === 0) {
-          this.advance();
-          return;
-        }
-      }
-      if (token.kind === "keyword" && depth === 0) return;
-      this.advance();
+    if (token.kind === "string" || token.kind === "date") {
+      this.take();
+      return {
+        kind: token.kind === "string" ? "text" : "date",
+        value:
+          token.kind === "string"
+            ? (JSON.parse(token.text) as string)
+            : token.text,
+        span: token.span,
+      };
     }
-  }
-
-  // --- Token helpers -------------------------------------------------------
-
-  private peek(): Token {
-    return this.tokens[this.index] as Token;
-  }
-
-  private peekAt(offset: number): Token {
-    return this.tokens[
-      Math.min(this.index + offset, this.tokens.length - 1)
-    ] as Token;
-  }
-
-  private previous(): Token {
-    return this.tokens[Math.max(0, this.index - 1)] as Token;
-  }
-
-  private advance(): Token {
-    const token = this.peek();
-    if (token.kind !== "eof") this.index += 1;
-    return token;
-  }
-
-  private at(kind: Token["kind"]): boolean {
-    return this.peek().kind === kind;
-  }
-
-  private atPunct(glyph: string): boolean {
-    const token = this.peek();
-    return token.kind === "punct" && token.text === glyph;
-  }
-
-  private parseIdent(): IdentExpr {
-    const token = this.advance();
-    return { kind: "ident", name: token.text, span: token.span };
-  }
-
-  private isName(token: Token): boolean {
-    return token.kind === "ident" || token.kind === "keyword";
-  }
-
-  private expectName(message: string): IdentExpr | undefined {
-    if (this.isName(this.peek())) return this.parseIdent();
-    this.error(this.peek().span, message);
-    return undefined;
-  }
-
-  private parseTemplatedName(message: string): IdentExpr | undefined {
-    if (this.atPunct("[")) {
-      const open = this.advance();
-      const binding = this.expectIdent(
-        "an indexed name needs its loop binding",
-      );
-      if (!binding || !this.expectPunct("]", "an indexed name needs ]")) {
-        return undefined;
+    const name = this.path();
+    if (this.eat("(")) {
+      const args: Expr[] = [];
+      while (!this.eat(")")) {
+        args.push(this.expression());
+        this.separators();
       }
-      const suffix = this.isName(this.peek()) ? this.parseIdent() : undefined;
+      return { kind: "call", name, args, span: this.span(start) };
+    }
+    let target: string | undefined;
+    let owner: string | undefined;
+    if (["ref", "list"].includes(name) && this.eat("<")) {
+      target = this.path();
+      this.expect(">");
+    }
+    const many = name === "ref" && this.eat("[");
+    if (many) this.expect("]");
+    if (this.eat("of")) owner = this.path();
+    const optional = this.eat("?");
+    if (target || owner || optional || many)
       return {
-        kind: "ident",
-        name: `[${binding.name}]${suffix?.name ?? ""}`,
-        span: {
-          start: open.span.start,
-          end: suffix?.span.end ?? this.previous().span.end,
-        },
+        kind: "type",
+        name,
+        ...(target ? { target } : {}),
+        ...(owner ? { owner } : {}),
+        optional,
+        ...(many ? { many: true } : {}),
+        span: this.span(start),
       };
-    }
-    const base = this.expectName(message);
-    if (!base || !this.atPunct("[")) return base;
-    this.advance();
-    const binding = this.expectIdent("an indexed name needs its loop binding");
-    if (!binding || !this.expectPunct("]", "an indexed name needs ]")) {
-      return undefined;
-    }
-    const suffix = this.isName(this.peek()) ? this.parseIdent() : undefined;
-    return {
-      kind: "ident",
-      name: `${base.name}[${binding.name}]${suffix?.name ?? ""}`,
-      span: {
-        start: base.span.start,
-        end: suffix?.span.end ?? this.previous().span.end,
-      },
-    };
-  }
-
-  private canStartExpr(token: Token): boolean {
-    return (
-      token.kind === "ident" ||
-      token.kind === "keyword" ||
-      token.kind === "number" ||
-      token.kind === "percent" ||
-      token.kind === "string" ||
-      (token.kind === "punct" && (token.text === "{" || token.text === "["))
-    );
-  }
-
-  private parsePath(message: string): import("./ast.ts").PathExpr | undefined {
-    const first = this.expectName(message);
-    if (!first) return undefined;
-    const parts = [first];
-    while (this.atPunct(".")) {
-      this.advance();
-      const part = this.expectName("expected a name after .");
-      if (!part) return undefined;
-      parts.push(part);
-    }
-    return {
-      kind: "path",
-      parts,
-      span: {
-        start: first.span.start,
-        end: parts.at(-1)?.span.end ?? first.span.end,
-      },
-    };
-  }
-
-  private parseAngleArguments(): Expr[] | undefined {
-    this.advance();
-    const args: Expr[] = [];
-    while (!this.atPunct(">") && !this.at("eof")) {
-      const arg = this.parseExpr();
-      if (!arg) return undefined;
-      args.push(arg);
-      if (this.atPunct(",")) this.advance();
-    }
-    return this.expectPunct(">", "the type argument list never closes")
-      ? args
-      : undefined;
+    return { kind: "name", value: name, span: this.span(start) };
   }
-
-  private parseApplication(): ApplyExpr | undefined {
-    const callee = this.parsePath("expected an instrument function name");
-    if (!callee) return undefined;
-    const typeArgs = this.atPunct("<") ? this.parseAngleArguments() : [];
-    if (!typeArgs) return undefined;
-    if (
-      !this.expectPunct(
-        "(",
-        "an instrument application needs arguments in parentheses",
-      )
-    ) {
-      return undefined;
-    }
-    const args: Expr[] = [];
-    while (!this.atPunct(")") && !this.at("eof")) {
-      const arg = this.parseExpr();
-      if (!arg) return undefined;
-      args.push(arg);
-      if (this.atPunct(",")) this.advance();
-    }
-    if (!this.expectPunct(")", "the instrument argument list never closes")) {
-      return undefined;
-    }
-    return {
-      args,
-      callee,
-      kind: "apply",
-      span: { start: callee.span.start, end: this.previous().span.end },
-      typeArgs,
-    };
-  }
-
-  private expectIdent(message: string): IdentExpr | undefined {
-    if (this.at("ident")) return this.parseIdent();
-    this.error(this.peek().span, message);
-    return undefined;
-  }
-
-  private expectPunct(glyph: string, message: string): boolean {
-    if (this.atPunct(glyph)) {
-      this.advance();
-      return true;
-    }
-    this.error(this.peek().span, message);
-    return false;
-  }
-
-  private spanFrom(start: Span): Span {
-    return { end: this.previous().span.end, start: start.start };
-  }
-
-  private error(span: Span, message: string): void {
-    this.diagnostics.push({ message, span });
-  }
-}
-
-/**
- * Convert a percent literal's raw digits to exact basis points, or refuse
- * when the literal is finer than a basis point. "99.5" -> 9950; "0.05" -> 5.
- */
-export function percentToBps(raw: string): number | undefined {
-  const [whole = "0", fraction = ""] = raw.split(".");
-  if (fraction.length > 2) return undefined;
-  const scaled = fraction.padEnd(2, "0");
-  return Number(whole) * 100 + Number(scaled === "" ? "0" : scaled);
 }