@bramas/simulant-lang 0.0.0-stage → 0.1.1

package/src/ir.ts

@@ -0,0 +1,223 @@
+/**
+ * The Simulant intermediate representation (plan, Sections 3 and 6.1).
+ *
+ * Everything here is plain JSON data: the builder (and later the parser)
+ * produce it, the engine interprets it, and the Lean generator translates it.
+ * Topologies and rounds are not written in the IR: they belong to the
+ * semantic core, and the IR only names them.
+ */
+
+export const IR_VERSION = 1;
+
+// ---------------------------------------------------------------------------
+// Types
+
+export type Type =
+  | { k: 'unit' }
+  | { k: 'bool' }
+  | { k: 'nat' }
+  | { k: 'int' }
+  | { k: 'string' }                          // labels only
+  | { k: 'node' }                            // a node of the topology
+  | { k: 'move' }                            // stay | cw | ccw
+  | { k: 'frame' }                           // an agent's frame (on a ring: mirrored or not)
+  | { k: 'agent' }                           // an agent of the configuration in scope
+  | { k: 'config' }                          // the configuration in scope
+  | { k: 'effect' }                          // what a hook returns
+  | { k: 'decision' }                        // a decision, as seen by `beforeMove` hooks
+  | { k: 'verdict' }                         // success | failure | inProgress
+  | { k: 'pub' }                             // the algorithm's public state, in library pieces
+  | { k: 'infer' }                           // a literal's type before checking (front end only)
+  | { k: 'enum'; name: string; ctors: string[] }
+  | { k: 'option'; of: Type }
+  | { k: 'record'; fields: Field[] }
+  | { k: 'list'; of: Type }
+  | { k: 'multiset'; of: Type }              // unordered: no order of anonymous agents leaks
+  | { k: 'fn'; params: Type[]; ret: Type };  // only as arguments of builtins
+
+export type Field = { name: string; type: Type };
+
+/** JSON encoding of literal values: numbers, booleans, strings (enum
+ * constructors, moves), `null` (unit, `none`), arrays, and objects (records). */
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+// ---------------------------------------------------------------------------
+// Expressions
+
+/**
+ * `at` (display only, like `Algorithm.source`): the source line of the expression, set on the
+ * algorithm's step and definitions of `.sim` programs, for the explanation of a step. It has no
+ * meaning for the semantics and is ignored by the checker and the Lean generator.
+ */
+export type Expr = ExprNode & { at?: number };
+
+type ExprNode =
+  | { e: 'lit'; type: Type; value: Json }
+  | { e: 'var'; name: string }
+  | { e: 'let'; name: string; value: Expr; body: Expr }
+  | { e: 'if'; cond: Expr; then: Expr; else: Expr }
+  /** Case analysis on an enum, a move or a verdict. */
+  | { e: 'match'; on: Expr; cases: Record<string, Expr>; else?: Expr }
+  /** A lambda, only as an argument of a builtin; parameter types are inferred from it. */
+  | { e: 'fn'; params: { name: string; type?: Type }[]; body: Expr }
+  /** A builtin (see builtins.ts) or a definition of the model. */
+  | { e: 'call'; fn: string; args: Expr[] }
+  | { e: 'record'; fields: Record<string, Expr> }
+  | { e: 'with'; on: Expr; fields: Record<string, Expr> }
+  | { e: 'get'; on: Expr; field: string }
+  /**
+   * An adversary choice among the elements of `from` (a list or a multiset),
+   * restricted to those satisfying `such`. `site` names the choice in
+   * witnesses; `label` describes the chosen element.
+   */
+  | { e: 'choose'; site: string; from: Expr; such?: Expr; label?: Expr }
+  /** A value supplied by the experiment. Only allowed in initialisation. */
+  | { e: 'param'; name: string }
+  /** What a hook does: new values of its component's world fields, and flags to raise. */
+  | { e: 'effect'; world?: Record<string, Expr>; raise?: Record<string, Expr> };
+
+/** A named function. Definitions are not recursive. */
+export type Def = { name: string; params: Field[]; ret: Type; body: Expr };
+
+// ---------------------------------------------------------------------------
+// Model pieces
+
+export type Flag = {
+  name: string;
+  /** A hidden agent disappears from every sensor. */
+  visibility: 'visible' | 'hidden';
+  /** `never`: no longer decides or moves; `adversary`: the adversary decides for it. */
+  acts: 'never' | 'adversary';
+};
+
+/**
+ * A sensor: a function of the configuration `C`, the observing agent `me`
+ * and its frame `frame`. The sensors of a model are exactly what its
+ * algorithms can know.
+ */
+export type Sensor = { name: string; type: Type; body: Expr; equivariance?: Equivariance };
+
+/** Which automorphisms of the topology a piece commutes with (Section 3.11). */
+export type Equivariance = { rotations: boolean; reflections: boolean };
+
+/** An action other than a move: a field of every decision, with a default. */
+export type Action = { name: string; type: Type; default: Json };
+
+export type Component = {
+  name: string;
+  /** Parameters of the component family (`BlackHole policy`), in scope in all its expressions. */
+  params?: Field[];
+  /** Their values in this instance. */
+  args?: Record<string, Json>;
+  /** World fields owned by the component. */
+  world?: Field[];
+  /** Agent fields owned by the component. */
+  agent?: Field[];
+  flags?: Flag[];
+  sensors?: Sensor[];
+  actions?: Action[];
+  /** Initial values: world fields may use `param`; agent fields may use the agent index `i`. */
+  init?: { world?: Record<string, Expr>; agent?: Record<string, Expr> };
+  /** Hook bodies: `C` is in scope; they return an effect. */
+  beforeLook?: Expr;
+  /** Also sees the decisions, through `decisionOf(a)`. */
+  beforeMove?: Expr;
+  afterMove?: Expr;
+  defs?: Def[];
+  equivariance?: Equivariance;
+};
+
+/** Topologies are part of the semantic core; the IR names one and its parameters. */
+export type Topology =
+  | { kind: 'ring'; size: Expr }
+  /** A ring where the adversary removes up to `k` edges at the start of every round. */
+  | { kind: 'dynamicRing'; size: Expr; k: number };
+
+export type FrameModel =
+  | { kind: 'common' }
+  | { kind: 'dynamicReflection' }
+  /** The frame is stored in an agent field of type `frame`, owned by a component. */
+  | { kind: 'persistent'; field: string };
+
+export type Model = {
+  name: string;
+  topology: Topology;
+  sensors: Sensor[];
+  memory: 'persistent' | 'oblivious';
+  frame: FrameModel;
+  /** `ssync`: a nonempty eligible subset; `sequential`: one eligible agent. Both require scheduler fairness. */
+  round: 'fsync' | 'ssync' | 'sequential';
+  movement: 'rigid';
+  components: Component[];
+  symmetries: 'derived' | 'none';
+  defs?: Def[];
+};
+
+// ---------------------------------------------------------------------------
+// Algorithms, tasks, experiments
+
+/**
+ * An algorithm as an explicit state machine. `step` sees `mem`, `pub` and
+ * `view` (a record with one field per sensor in `uses`), and returns a
+ * record `{ move, pub, mem, ...actions }`. Moves are local to the agent's frame.
+ */
+export type Algorithm = {
+  name: string;
+  uses: string[];
+  pub: Type;
+  mem: Type;
+  /** Initial public state and memory; the agent index `i` is in scope. */
+  init: { pub: Expr; mem: Expr };
+  step: Expr;
+  /** The line to highlight, from the memory. */
+  line?: Expr;
+  /** Interpreter-only escape hatch: a TypeScript step function registered under this name. */
+  native?: string;
+  /**
+   * Where the algorithm is written, for display (the line table refers to this file), and, for
+   * each program-counter value inside procedure calls, the lines of those calls (outermost first).
+   */
+  source?: {
+    file: string; line: number; endLine: number; calls?: Record<string, number[]>;
+    /** Where the definitions of `defs` are written. */
+    defs?: { name: string; file: string; line: number; endLine: number }[];
+  };
+  defs?: Def[];
+};
+
+export type Goal =
+  /** No reachable `failure` verdict, and every execution reaches `success`. */
+  | 'eventually'
+  /** No reachable `failure` verdict, and every execution ends in `success` forever. */
+  | 'eventuallyAlways'
+  /** Only: no reachable `failure` verdict. */
+  | 'safety';
+
+/** A verdict on configurations (`C` in scope) and a goal over executions. */
+export type Task = { name: string; verdict: Expr; goal: Goal; equivariance?: Equivariance; defs?: Def[] };
+
+/** A parameter, with the list of its values for `check-all` (earlier parameters in scope). */
+export type Param = { name: string; type: Type; domain?: Expr };
+
+/** Where a declaration is written (display only). */
+export type DeclSource = {
+  kind: 'experiment' | 'model' | 'component' | 'sensor' | 'algorithm' | 'task' | 'goal' | 'definition';
+  name: string; file: string; line: number; endLine: number;
+};
+
+export type Experiment = {
+  irVersion: number;
+  name: string;
+  model: Model;
+  algorithm: Algorithm;
+  task: Task;
+  params: Param[];
+  /** Agents: their number and positions (index `i` in scope); parameters in scope. */
+  agents: { count: Expr; pos: Expr };
+  limits?: { depth?: number; states?: number };
+  /**
+   * Display only, like `Algorithm.source`: where the experiment is written, and every declaration
+   * it is built from (the experiment first, then in order of use), for the page's model view.
+   */
+  source?: { file: string; line: number; endLine: number; uses: DeclSource[] };
+};

package/src/layout.ts

@@ -0,0 +1,77 @@
+/**
+ * The composed state of an experiment: which fields, flags, sensors and
+ * actions exist, and which component owns each of them.
+ */
+import type { Action, Def, Experiment, Field, Flag, Sensor, Type } from './ir';
+import { resolvePub, T } from './types';
+
+export type Owned<X> = X & { owner: string };
+
+export type Layout = {
+  world: Owned<Field>[];
+  agentFields: Owned<Field>[];
+  flags: Owned<Flag>[];
+  sensors: Owned<Sensor>[];
+  actions: Owned<Action>[];
+  worldType: Type;
+  pub: Type;
+  mem: Type;
+  /** What `step` receives as `view`: one field per sensor the algorithm uses. */
+  view: Type;
+  /** What `step` returns. */
+  decision: Type;
+  /** Definitions visible from every piece: the model's. */
+  defs: Def[];
+  errors: string[];
+};
+
+export const MODEL = 'model';
+
+export function layout(exp: Experiment): Layout {
+  const errors: string[] = [];
+  const unique = <X extends { name: string }>(what: string, items: Owned<X>[]) => {
+    const seen = new Map<string, string>();
+    for (const item of items) {
+      const other = seen.get(item.name);
+      if (other !== undefined) errors.push(`${what} '${item.name}' is declared by both ${other} and ${item.owner}`);
+      seen.set(item.name, item.owner);
+    }
+    return items;
+  };
+  const owned = <X>(owner: string, items: X[] | undefined) => (items ?? []).map(x => ({ ...x, owner }));
+  const { model, algorithm } = exp;
+  const world = unique('world field', model.components.flatMap(c => owned(c.name, c.world)));
+  const agentFields = unique('agent field', model.components.flatMap(c => owned(c.name, c.agent)));
+  const flags = unique('flag', model.components.flatMap(c => owned(c.name, c.flags)));
+  const sensors = unique('sensor', [...owned(MODEL, model.sensors), ...model.components.flatMap(c => owned(c.name, c.sensors))])
+    .map(s => ({ ...s, type: resolvePub(s.type, algorithm.pub) }));
+  const actions = unique('action', model.components.flatMap(c => owned(c.name, c.actions)));
+  const reserved = new Set(['pos', 'pub', 'mem']);
+  for (const f of [...agentFields, ...flags]) {
+    if (reserved.has(f.name)) errors.push(`agent field '${f.name}' of ${f.owner} is reserved`);
+  }
+  for (const f of agentFields) {
+    if (flags.some(g => g.name === f.name)) errors.push(`'${f.name}' is both an agent field and a flag`);
+  }
+  for (const a of actions) {
+    if (['move', 'pub', 'mem'].includes(a.name)) errors.push(`action '${a.name}' of ${a.owner} is reserved`);
+  }
+  const view: Field[] = [];
+  for (const name of algorithm.uses) {
+    const sensor = sensors.find(s => s.name === name);
+    if (sensor) view.push({ name, type: sensor.type });
+    else errors.push(`algorithm ${algorithm.name} uses sensor '${name}', which the model does not provide`);
+  }
+  return {
+    world, agentFields, flags, sensors, actions, errors,
+    worldType: T.record(world.map(({ name, type }) => ({ name, type }))),
+    pub: algorithm.pub,
+    mem: algorithm.mem,
+    view: T.record(view),
+    decision: T.record([
+      { name: 'move', type: T.move }, { name: 'pub', type: algorithm.pub }, { name: 'mem', type: algorithm.mem },
+      ...actions.map(({ name, type }) => ({ name, type })),
+    ]),
+    defs: model.defs ?? [],
+  };
+}

package/src/parse/ast.ts

@@ -0,0 +1,89 @@
+/** The surface syntax of `.sim` files, with source spans. */
+import type { Span } from './lexer';
+
+export type SType =
+  | { t: 'name'; name: string; args: SType[]; span: Span }
+  | { t: 'record'; fields: SFieldType[]; span: Span };
+
+export type SFieldType = { name: string; type: SType; default?: SExpr; span: Span };
+
+export type SArg = { name?: string; value: SExpr };
+
+export type SPat =
+  | { t: 'ctor'; name: string; span: Span }   // .cw or Move.cw
+  | { t: 'wild'; span: Span }
+  | { t: 'none'; span: Span }
+  | { t: 'some'; name: string; span: Span }
+  | { t: 'bool'; value: boolean; span: Span };
+
+export type SRecordItem =
+  | { t: 'field'; name: string; value?: SExpr; span: Span }   // `f := e`, or `f` (punning)
+  | { t: 'raise'; flag: string; value: SExpr; span: Span };  // `raise dead := S`, in effects
+
+export type SExpr = { span: Span } & (
+  | { t: 'num'; value: number }
+  | { t: 'str'; value: string }
+  | { t: 'bool'; value: boolean }
+  | { t: 'name'; name: string }                       // possibly dotted: C.world.site
+  | { t: 'ctor'; name: string }                       // .cw
+  | { t: 'proj'; on: SExpr; field: string }           // (e).f
+  | { t: 'app'; fn: SExpr; args: SArg[] }
+  | { t: 'binop'; op: string; l: SExpr; r: SExpr }
+  | { t: 'unop'; op: string; e: SExpr }
+  | { t: 'if'; cond: SExpr; then: SExpr; else: SExpr }
+  | { t: 'let'; name: string; type?: SType; value: SExpr; body: SExpr }
+  | { t: 'match'; on: SExpr; cases: { pat: SPat; body: SExpr }[] }
+  | { t: 'fun'; params: { name: string; type?: SType }[]; body: SExpr }
+  | { t: 'list'; items: SExpr[] }
+  | { t: 'record'; base?: SExpr; items: SRecordItem[] }
+  | { t: 'choose'; from: SExpr; such?: SExpr; labels?: SExpr }
+  | { t: 'param'; name: string }
+  | { t: 'ascribe'; e: SExpr; type: SType }
+  | { t: 'nothing' }
+  | { t: 'unit' }                                     // ()
+  | { t: 'hole' }                                     // `·` in a section, before desugaring
+  | { t: 'flag'; name: string; visibility: 'visible' | 'hidden'; acts: 'never' | 'adversary' }
+  | { t: 'action'; name: string; type: SType; default: SExpr }
+  | { t: 'typeValue'; type: SType }                   // a type in a `where` block: `World := { site : Node }`
+);
+
+export type SBinder = { name: string; type: SType; default?: SExpr; span: Span };
+
+/** Statements of structured algorithms (plan 3.8). `move`, `stay` and `halt` end the activation. */
+export type SStmt = { span: Span } & (
+  | { s: 'move'; dir: SExpr; actions?: SRecordItem[] }   // `move d with { pebble := .drop }`
+  | { s: 'stay'; actions?: SRecordItem[] }
+  | { s: 'halt'; actions?: SRecordItem[] }
+  | { s: 'wait'; count: SExpr }                          // `wait n`: stay n activations
+  | { s: 'repeat'; body: SStmt[] }
+  | { s: 'while'; cond: SExpr; body: SStmt[] }
+  | { s: 'if'; cond: SExpr; then: SStmt[]; else?: SStmt[] }
+  | { s: 'let'; name: string; type?: SType; value: SExpr }
+  | { s: 'assign'; name: string; value: SExpr }
+  | { s: 'call'; name: string; args: SExpr[] }
+);
+
+/** An item of a `where` block: `name args := value`, or `param N : T := domain` in experiments. */
+export type SWhereItem = {
+  name: string; args: string[]; value: SExpr; span: Span;
+  /** `param N : T := domain`, in experiments. */
+  param?: { type: SType };
+  /** `def p (x : T) := statements` and `main := statements`, in algorithms. */
+  proc?: { params: SBinder[]; body: SStmt[] };
+};
+
+export type SAttribute = { name: string; args: string[] };
+
+export type SDecl = { span: Span; doc?: string; attrs: SAttribute[] } & (
+  | { d: 'import'; path: string }
+  | { d: 'inductive'; name: string; ctors: string[] }
+  | { d: 'structure'; name: string; fields: SFieldType[] }
+  | { d: 'def'; name: string; params: SBinder[]; type?: SType; body?: SExpr; items?: SWhereItem[] }
+  | { d: 'sensor'; name: string; params: SBinder[]; type: SType; body: SExpr }
+  | { d: 'task'; name: string; params: SBinder[]; type: SType; body: SExpr }
+  | { d: 'goal'; name: string; goal: 'eventually' | 'eventuallyAlways' | 'safety' }
+  | { d: 'algorithm'; name: string; uses: string[]; items: SWhereItem[] }
+  | { d: 'experiment'; name: string; items: SWhereItem[] }
+);
+
+export type SFile = { file: string; decls: SDecl[] };

package/src/parse/lexer.ts

@@ -0,0 +1,146 @@
+/**
+ * Lexer of `.sim` sources. Tokens keep their position and whether they start
+ * a line: the parser uses columns for layout, as Lean does.
+ */
+
+export type Pos = { line: number; col: number; offset: number };
+export type Span = { file: string; start: Pos; end: Pos };
+
+export type TokenKind =
+  | 'ident'      // name, possibly qualified: Hazards.BlackHole
+  | 'dotIdent'   // .cw, a constructor whose type is inferred
+  | 'field'      // .pos right after an expression: a projection
+  | 'number'
+  | 'string'
+  | 'op'         // punctuation and operators
+  | 'keyword'
+  | 'eof';
+
+export type Token = {
+  kind: TokenKind;
+  text: string;
+  start: Pos;
+  end: Pos;
+  /** First token of its line. */
+  lineStart: boolean;
+  /** Preceded by whitespace or a comment. */
+  spaced: boolean;
+};
+
+export const KEYWORDS = new Set([
+  'import', 'def', 'structure', 'inductive', 'sensor', 'task', 'goal', 'algorithm', 'experiment', 'where', 'let',
+  'if', 'then', 'else', 'match', 'with', 'fun', 'choose', 'such', 'that', 'labels', 'param', 'flag', 'uses',
+  'true', 'false', 'raise', 'nothing', 'action',
+]);
+
+/** Operators, longest first. Unicode and ASCII spellings are both accepted. */
+const OPERATORS = [
+  ':=', '=>', '->', '<-', '++', '==', '!=', '<=', '>=', '&&', '||',
+  '→', '←', '≠', '≤', '≥', '∧', '∨', '¬', '·', '×',
+  '=', '<', '>', '+', '-', '*', '/', '%', '!', '|', ',', ':', ';', '(', ')', '[', ']', '{', '}', '@',
+];
+
+const NORMALIZE: Record<string, string> = {
+  '->': '→', '<-': '←', '!=': '≠', '<=': '≤', '>=': '≥', '&&': '∧', '||': '∨', '==': '=',
+};
+
+export class LexError extends Error {
+  constructor(message: string, readonly span: Span) {
+    super(message);
+  }
+}
+
+const identStart = /[A-Za-z_À-ɏͰ-Ͽ]/;
+const identPart = /[A-Za-z0-9_'À-ɏͰ-Ͽ₀-₉]/;
+
+export function lex(source: string, file = '<input>'): Token[] {
+  const tokens: Token[] = [];
+  let i = 0, line = 1, col = 1;
+  let lineStart = true, spaced = true;
+  const pos = (): Pos => ({ line, col, offset: i });
+  const advance = (n = 1) => {
+    for (let j = 0; j < n; j++) {
+      if (source[i] === '\n') { line++; col = 1; } else col++;
+      i++;
+    }
+  };
+  const fail = (msg: string, start: Pos): never => { throw new LexError(msg, { file, start, end: pos() }); };
+
+  while (i < source.length) {
+    const c = source[i];
+    if (c === '\n') { advance(); lineStart = true; spaced = true; continue; }
+    if (c === ' ' || c === '\t' || c === '\r') { advance(); spaced = true; continue; }
+    if (source.startsWith('--', i)) {
+      while (i < source.length && source[i] !== '\n') advance();
+      spaced = true;
+      continue;
+    }
+    if (source.startsWith('/-', i)) {
+      const start = pos();
+      let depth = 0;
+      do {
+        if (source.startsWith('/-', i)) { depth++; advance(2); }
+        else if (source.startsWith('-/', i)) { depth--; advance(2); }
+        else if (i >= source.length) fail('unterminated comment', start);
+        else advance();
+      } while (depth > 0);
+      spaced = true;
+      continue;
+    }
+    const start = pos();
+    const push = (kind: TokenKind, text: string) => {
+      tokens.push({ kind, text, start, end: pos(), lineStart, spaced });
+      lineStart = false;
+      spaced = false;
+    };
+    const prev = tokens[tokens.length - 1];
+    const afterTerm = !!prev && !spaced && (prev.kind === 'ident' || prev.kind === 'field' || prev.kind === 'dotIdent'
+      || prev.kind === 'number' || prev.kind === 'string' || [')', ']', '}'].includes(prev.text) || prev.text === '·');
+    if (c === '.' && identStart.test(source[i + 1] ?? '')) {
+      // `.x` right after a term is a projection; otherwise a constructor.
+      advance();
+      const s = i;
+      while (i < source.length && identPart.test(source[i])) advance();
+      push(afterTerm ? 'field' : 'dotIdent', source.slice(s, i));
+      continue;
+    }
+    if (identStart.test(c)) {
+      const s = i;
+      while (i < source.length && identPart.test(source[i])) advance();
+      // A dotted name, as in Lean: `Hazards.BlackHole` or `C.world.site`; name resolution
+      // decides which parts are namespaces and which are projections.
+      while (source[i] === '.' && identStart.test(source[i + 1] ?? '')) {
+        advance();
+        while (i < source.length && identPart.test(source[i])) advance();
+      }
+      const text = source.slice(s, i);
+      push(KEYWORDS.has(text) ? 'keyword' : 'ident', text);
+      continue;
+    }
+    if (/[0-9]/.test(c)) {
+      const s = i;
+      while (i < source.length && /[0-9]/.test(source[i])) advance();
+      push('number', source.slice(s, i));
+      continue;
+    }
+    if (c === '"') {
+      advance();
+      let text = '';
+      while (source[i] !== '"') {
+        if (i >= source.length || source[i] === '\n') fail('unterminated string', start);
+        if (source[i] === '\\') { advance(); text += source[i] === 'n' ? '\n' : source[i]; advance(); continue; }
+        text += source[i];
+        advance();
+      }
+      advance();
+      push('string', text);
+      continue;
+    }
+    const op = OPERATORS.find(o => source.startsWith(o, i));
+    if (!op) fail(`unexpected character '${c}'`, start);
+    advance(op!.length);
+    push('op', NORMALIZE[op!] ?? op!);
+  }
+  tokens.push({ kind: 'eof', text: '', start: pos(), end: pos(), lineStart: true, spaced: true });
+  return tokens;
+}