@higher.archi/boe 1.0.0

package/src/core/parser/tokenizer/readers/symbol.reader.ts

@@ -0,0 +1,118 @@
+import type { OperatorTable } from '../../types';
+import type { ReaderResult, ScannerState } from '../types';
+import { advanceBy, remainingInput } from '../scanner';
+
+/**
+ * Symbol operators and punctuation that we recognize.
+ *
+ * Order matters! Longer symbols must come first so ">=" is
+ * matched before ">". We sort by length descending.
+ *
+ * Categories:
+ *   - Comparison: ==, !=, >=, <=, >, <
+ *   - Logical: &&, ||
+ *   - Arithmetic: +, -, *, /, %
+ *   - Punctuation: (, ), ,
+ *   - Negation: !
+ */
+const PUNCTUATION = ['(', ')', ','] as const;
+
+const SYMBOL_OPERATORS = [
+  // Two-character (must check first)
+  '==',
+  '!=',
+  '>=',
+  '<=',
+  '&&',
+  '||',
+  // Single-character
+  '>',
+  '<',
+  '+',
+  '-',
+  '*',
+  '/',
+  '%',
+  '!'
+] as const;
+
+/**
+ * Reads symbolic operators and punctuation.
+ *
+ * This reader handles:
+ *   - Comparison symbols: >, >=, <, <=, ==, !=
+ *   - Logical symbols: &&, ||, !
+ *   - Arithmetic symbols: +, -, *, /, %
+ *   - Punctuation: (, ), ,
+ *
+ * Important: Multi-character symbols (>=, <=, ==, !=, &&, ||)
+ * must be checked BEFORE their single-character prefixes.
+ *
+ * Examples:
+ *   >     → OPERATOR('>', canonical: 'greaterThan')
+ *   >=    → OPERATOR('>=', canonical: 'greaterThanOrEquals')
+ *   (     → LPAREN('(')
+ *   ,     → COMMA(',')
+ */
+export function readSymbol(
+  state: ScannerState,
+  operatorTable: OperatorTable
+): ReaderResult | null {
+  const startPosition = state.position;
+  const remaining = remainingInput(state);
+
+  // Check punctuation first (these are not operators)
+  for (const punct of PUNCTUATION) {
+    if (remaining.startsWith(punct)) {
+      const tokenType =
+        punct === '('
+          ? 'LPAREN'
+          : punct === ')'
+            ? 'RPAREN'
+            : 'COMMA';
+
+      return {
+        token: {
+          type: tokenType,
+          value: punct,
+          position: startPosition
+        },
+        newState: advanceBy(state, punct.length)
+      };
+    }
+  }
+
+  // Check symbol operators (longer ones first)
+  for (const symbol of SYMBOL_OPERATORS) {
+    if (remaining.startsWith(symbol)) {
+      // Look up in operator table to get canonical name
+      const operatorInfo = operatorTable.get(symbol);
+
+      if (operatorInfo) {
+        return {
+          token: {
+            type: 'OPERATOR',
+            value: symbol,
+            canonical: operatorInfo.canonical,
+            position: startPosition
+          },
+          newState: advanceBy(state, symbol.length)
+        };
+      }
+
+      // Symbol exists but not in operator table
+      // Still return it as operator, parser will validate
+      return {
+        token: {
+          type: 'OPERATOR',
+          value: symbol,
+          position: startPosition
+        },
+        newState: advanceBy(state, symbol.length)
+      };
+    }
+  }
+
+  // Not a recognized symbol
+  return null;
+}

package/src/core/parser/tokenizer/readers/whitespace.reader.ts

@@ -0,0 +1,18 @@
+import type { ScannerState } from '../types';
+import { advance, isAtEnd, isWhitespace, peek } from '../scanner';
+
+/**
+ * Skips whitespace characters (spaces, tabs, newlines).
+ *
+ * Unlike other readers, this doesn't return a token.
+ * It simply advances the scanner past any whitespace.
+ *
+ * Whitespace is semantically insignificant in expressions,
+ * so we just consume it and move on.
+ */
+export function skipWhitespace(state: ScannerState): ScannerState {
+  while (!isAtEnd(state) && isWhitespace(peek(state))) {
+    state = advance(state);
+  }
+  return state;
+}

package/src/core/parser/tokenizer/scanner.ts

@@ -0,0 +1,137 @@
+import type { ScannerState } from './types';
+
+/**
+ * Low-level character scanning utilities.
+ *
+ * These functions provide the basic operations for moving through
+ * the input string. All functions are pure - they don't mutate
+ * state but instead return new values.
+ *
+ * Usage pattern:
+ *   let state = createScanner("$age > 18");
+ *   while (!isAtEnd(state)) {
+ *     const char = peek(state);
+ *     // process char...
+ *     state = advance(state);
+ *   }
+ */
+
+/**
+ * Creates a new scanner state starting at position 0.
+ */
+export function createScanner(input: string): ScannerState {
+  return {
+    input,
+    position: 0
+  };
+}
+
+/**
+ * Returns the character at the current position without advancing.
+ * Returns empty string if at end of input.
+ */
+export function peek(state: ScannerState): string {
+  if (isAtEnd(state)) {
+    return '';
+  }
+  return state.input[state.position];
+}
+
+/**
+ * Returns the character n positions ahead of current position.
+ * Returns empty string if that position is past end of input.
+ *
+ * Useful for lookahead when deciding between tokens like '>' vs '>='.
+ */
+export function peekAhead(state: ScannerState, n: number): string {
+  const position = state.position + n;
+  if (position >= state.input.length) {
+    return '';
+  }
+  return state.input[position];
+}
+
+/**
+ * Returns a new state with position advanced by 1.
+ * Does not advance past the end of input.
+ */
+export function advance(state: ScannerState): ScannerState {
+  if (isAtEnd(state)) {
+    return state;
+  }
+  return {
+    ...state,
+    position: state.position + 1
+  };
+}
+
+/**
+ * Returns a new state with position advanced by n characters.
+ * Will not advance past the end of input.
+ */
+export function advanceBy(state: ScannerState, n: number): ScannerState {
+  const newPosition = Math.min(state.position + n, state.input.length);
+  return {
+    ...state,
+    position: newPosition
+  };
+}
+
+/**
+ * Checks if we've reached the end of the input.
+ */
+export function isAtEnd(state: ScannerState): boolean {
+  return state.position >= state.input.length;
+}
+
+/**
+ * Returns the current character (same as peek, but more descriptive name).
+ */
+export function currentChar(state: ScannerState): string {
+  return peek(state);
+}
+
+/**
+ * Returns the remaining unprocessed input from current position.
+ * Useful for debugging and lookahead matching.
+ */
+export function remainingInput(state: ScannerState): string {
+  return state.input.slice(state.position);
+}
+
+/**
+ * Helper predicates for character classification.
+ * Used by the individual readers to identify token boundaries.
+ */
+
+export function isWhitespace(char: string): boolean {
+  return char === ' ' || char === '\t' || char === '\n' || char === '\r';
+}
+
+export function isDigit(char: string): boolean {
+  return char >= '0' && char <= '9';
+}
+
+export function isAlpha(char: string): boolean {
+  return (char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z');
+}
+
+export function isAlphaNumeric(char: string): boolean {
+  return isAlpha(char) || isDigit(char);
+}
+
+/**
+ * Checks if a character can start an identifier.
+ * Identifiers start with a letter or underscore.
+ */
+export function isIdentifierStart(char: string): boolean {
+  return isAlpha(char) || char === '_';
+}
+
+/**
+ * Checks if a character can continue an identifier.
+ * Identifiers can contain letters, digits, and underscores.
+ */
+export function isIdentifierPart(char: string): boolean {
+  return isAlphaNumeric(char) || char === '_';
+}

package/src/core/parser/tokenizer/types.ts

@@ -0,0 +1,63 @@
+import type { Token } from '../types';
+
+/**
+ * Represents the current state of the scanner as it moves through input.
+ *
+ * Design Decision: Immutable State
+ * --------------------------------
+ * We use immutable state rather than mutating a scanner object.
+ * Each operation returns a new state instead of modifying the current one.
+ *
+ * Benefits:
+ * - Easier to test: Each function is pure and predictable
+ * - Easier to debug: Can inspect state at any point
+ * - Backtracking is simple: Just use an earlier state
+ * - No hidden side effects between reader calls
+ */
+export interface ScannerState {
+  /** The complete input string being tokenized */
+  readonly input: string;
+
+  /** Current position in the input (0-indexed) */
+  readonly position: number;
+}
+
+/**
+ * Result returned by a token reader when it successfully matches input.
+ *
+ * Each reader is a pure function that:
+ * 1. Takes the current scanner state
+ * 2. Returns null if it doesn't match at this position
+ * 3. Returns { token, newState } if it does match
+ *
+ * The newState has the position advanced past the consumed characters.
+ */
+export interface ReaderResult {
+  /** The token that was read */
+  token: Token;
+
+  /** Scanner state with position advanced past the token */
+  newState: ScannerState;
+}
+
+/**
+ * Type signature for a token reader function.
+ *
+ * Readers are tried in a specific order (see tokenizer/index.ts).
+ * The first reader to return a non-null result "wins" and its
+ * token is added to the output stream.
+ */
+export type TokenReader = (state: ScannerState) => ReaderResult | null;
+
+/**
+ * Type signature for readers that need access to the operator table.
+ *
+ * The identifier reader needs this to determine if a word is:
+ * - A known operator (and, or, contains, etc.)
+ * - A function name (when followed by parentheses)
+ * - An unknown identifier (error)
+ */
+export type TokenReaderWithContext<T> = (
+  state: ScannerState,
+  context: T
+) => ReaderResult | null;

package/src/core/parser/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Token types produced by the tokenizer.
+ * Each token represents a meaningful unit in the expression.
+ *
+ * The tokenizer converts a string like "$age > 18 and $active"
+ * into a stream of tokens that the parser can process.
+ */
+export type TokenType =
+  | 'PROPERTY_REF' // $var, $user.name - variable references starting with $
+  | 'NUMBER' // 42, 3.14, -5 - numeric literals (integers and decimals)
+  | 'STRING' // 'hello', "world" - string literals with single or double quotes
+  | 'BOOLEAN' // true, false - boolean literals
+  | 'NULL' // null - null literal
+  | 'OPERATOR' // >, and, contains - infix/prefix operators
+  | 'FUNCTION' // daysAgo, now - function names (followed by parentheses)
+  | 'LPAREN' // ( - left parenthesis for grouping or function calls
+  | 'RPAREN' // ) - right parenthesis
+  | 'COMMA' // , - argument separator in function calls
+  | 'EOF'; // End of input marker
+
+/**
+ * Represents a single token in the expression.
+ *
+ * The `canonical` field is used for operators to store the
+ * normalized operator name (e.g., '>' becomes 'greaterThan').
+ * This allows the parser to work with consistent operator names
+ * regardless of which alias was used in the input.
+ */
+export interface Token {
+  /** The type of token */
+  type: TokenType;
+
+  /** The raw value as it appeared in the input */
+  value: string;
+
+  /**
+   * For operators: the canonical operator name.
+   * e.g., '>' → 'greaterThan', 'gt' → 'greaterThan'
+   * This ensures consistent handling regardless of alias used.
+   */
+  canonical?: string;
+
+  /**
+   * Character position in the input string where this token starts.
+   * Used for error reporting to show the user where a problem occurred.
+   */
+  position: number;
+}
+
+/**
+ * Information about an operator for parsing purposes.
+ *
+ * This is used by the Pratt parser to determine how to
+ * handle operators with different precedences and associativities.
+ */
+export interface OperatorInfo {
+  /** The canonical operator name (e.g., 'greaterThan', not '>' or 'gt') */
+  canonical: string;
+
+  /**
+   * Operator precedence (1-8 scale, higher binds tighter).
+   *
+   * Precedence levels:
+   * 1 - or, ||
+   * 2 - and, &&
+   * 3 - not, ! (unary prefix)
+   * 4 - comparison: >, >=, <, <=, ==, !=, contains, etc.
+   * 5 - addition: +, -
+   * 6 - multiplication: *, /, %
+   * 7 - unary minus (negation)
+   * 8 - function calls, literals, parentheses
+   */
+  precedence: number;
+
+  /**
+   * Determines how operators of the same precedence group.
+   * - 'left': a op b op c = (a op b) op c (most common)
+   * - 'right': a op b op c = a op (b op c) (e.g., assignment)
+   * - 'none': cannot chain without parentheses
+   */
+  associativity: 'left' | 'right' | 'none';
+
+  /**
+   * The arity of the operator.
+   * - 'unary': single operand (not, !)
+   * - 'binary': two operands (most operators)
+   * - 'ternary': three operands (between...and)
+   * - 'variadic': variable number of operands (and, or)
+   */
+  arity: 'unary' | 'binary' | 'ternary' | 'variadic';
+}
+
+/**
+ * Lookup table mapping operator aliases to their info.
+ * The key can be any alias (symbol, word, or full name).
+ *
+ * Example entries:
+ *   '>' → { canonical: 'greaterThan', precedence: 4, ... }
+ *   'gt' → { canonical: 'greaterThan', precedence: 4, ... }
+ *   'greaterThan' → { canonical: 'greaterThan', precedence: 4, ... }
+ */
+export type OperatorTable = Map<string, OperatorInfo>;

package/src/core/refraction/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Core refraction module - shared across engines
+ */
+
+export { Refraction } from './refraction';

package/src/core/refraction/refraction.ts

@@ -0,0 +1,71 @@
+/**
+ * Core refraction (rule firing tracking) - shared across engines
+ *
+ * Refraction prevents the same rule from firing multiple times
+ * with the same set of facts.
+ */
+
+import { Activation } from '../matching';
+import { CompiledBaseRule } from '../types';
+
+export class Refraction {
+  private fired: Set<string> = new Set();
+
+  private getKey<TRule extends CompiledBaseRule>(activation: Activation<TRule>): string {
+    return `${activation.rule.id}:${activation.factIds.join(',')}`;
+  }
+
+  hasFired<TRule extends CompiledBaseRule>(activation: Activation<TRule>): boolean {
+    return this.fired.has(this.getKey(activation));
+  }
+
+  markFired<TRule extends CompiledBaseRule>(activation: Activation<TRule>): void {
+    this.fired.add(this.getKey(activation));
+  }
+
+  retract<TRule extends CompiledBaseRule>(activation: Activation<TRule>): void {
+    this.fired.delete(this.getKey(activation));
+  }
+
+  retractByFactId(factId: string): void {
+    for (const key of this.fired) {
+      if (key.includes(factId)) {
+        this.fired.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Retract all refraction entries for a fact, except for a specific rule.
+   * This prevents infinite loops when a rule modifies a fact it matched on.
+   * The rule that made the modification should remain in refraction (won't re-fire),
+   * but other rules should be allowed to re-evaluate the modified fact.
+   */
+  retractByFactIdExcludingRule(factId: string, excludeRuleId: string): void {
+    for (const key of this.fired) {
+      if (key.includes(factId) && !key.startsWith(`${excludeRuleId}:`)) {
+        this.fired.delete(key);
+      }
+    }
+  }
+
+  retractByRuleId(ruleId: string): void {
+    for (const key of this.fired) {
+      if (key.startsWith(`${ruleId}:`)) {
+        this.fired.delete(key);
+      }
+    }
+  }
+
+  filter<TRule extends CompiledBaseRule>(activations: Activation<TRule>[]): Activation<TRule>[] {
+    return activations.filter(a => !this.hasFired(a));
+  }
+
+  clear(): void {
+    this.fired.clear();
+  }
+
+  size(): number {
+    return this.fired.size;
+  }
+}

package/src/core/resolution/conflict-resolver.ts

@@ -0,0 +1,87 @@
+/**
+ * Core conflict resolution - shared across engines that need ordering
+ */
+
+import { Activation } from '../matching';
+import { CompiledBaseRule } from '../types';
+
+export type ConflictStrategy =
+  | 'salience'
+  | 'specificity'
+  | 'complexity'
+  | 'simplicity'
+  | 'fifo'
+  | 'lifo'
+  | 'random'
+  | 'ruleOrder';
+
+export const DEFAULT_STRATEGIES: ConflictStrategy[] = [
+  'salience',
+  'complexity',
+  'ruleOrder',
+  'fifo'
+];
+
+function normalize(value: number): number {
+  if (value < 0) return -1;
+  if (value > 0) return 1;
+  return 0;
+}
+
+function compareByStrategy<TRule extends CompiledBaseRule>(
+  a: Activation<TRule>,
+  b: Activation<TRule>,
+  strategy: ConflictStrategy
+): number {
+  switch (strategy) {
+    case 'salience':
+      return normalize(b.rule.salience - a.rule.salience);
+
+    case 'specificity':
+      return normalize(b.rule.inputs.length - a.rule.inputs.length);
+
+    case 'complexity':
+      return normalize(b.rule.complexity - a.rule.complexity);
+
+    case 'simplicity':
+      return normalize(a.rule.complexity - b.rule.complexity);
+
+    case 'fifo':
+      return normalize(a.matchedAt - b.matchedAt);
+
+    case 'lifo':
+      return normalize(b.matchedAt - a.matchedAt);
+
+    case 'random':
+      return normalize(Math.random() - 0.5);
+
+    case 'ruleOrder':
+      return normalize(a.rule.index - b.rule.index);
+
+    default:
+      return 0;
+  }
+}
+
+export type ResolveOptions = {
+  strategies?: ConflictStrategy | ConflictStrategy[];
+};
+
+export function resolveConflicts<TRule extends CompiledBaseRule>(
+  activations: Activation<TRule>[],
+  options: ResolveOptions = {}
+): Activation<TRule>[] {
+  if (activations.length <= 1) return activations;
+
+  const { strategies = DEFAULT_STRATEGIES } = options;
+
+  const strategyList = Array.isArray(strategies) ? strategies : [strategies];
+
+  return [...activations].sort((a, b) => {
+    for (const strategy of strategyList) {
+      const result = compareByStrategy(a, b, strategy);
+      if (result !== 0) return result;
+    }
+    return 0;
+  });
+}

package/src/core/resolution/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Core resolution module - shared across engines
+ */
+
+export {
+  ConflictStrategy,
+  DEFAULT_STRATEGIES,
+  ResolveOptions,
+  resolveConflicts
+} from './conflict-resolver';

package/src/core/shapes/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Core shapes module - shared across engines
+ */
+
+export { normalizeShape } from './shape.normalizer';

package/src/core/shapes/shape.normalizer.ts

@@ -0,0 +1,68 @@
+/**
+ * Core shape normalization - converts shorthand to JSONSchema
+ */
+
+import { Shape, ShapeShorthand, JSONSchema } from '../types';
+
+function isJSONSchema(shape: Shape): shape is JSONSchema {
+  return typeof shape === 'object' && 'type' in shape;
+}
+
+function parseArrayType(str: string): JSONSchema | null {
+  if (str.endsWith('[]')) {
+    const itemType = str.slice(0, -2);
+    return {
+      type: 'array',
+      items: normalizeShape(itemType)
+    };
+  }
+  return null;
+}
+
+function normalizeShorthand(shorthand: ShapeShorthand): JSONSchema {
+  // String shorthand: "string", "number", "string[]"
+  if (typeof shorthand === 'string') {
+    const arrayType = parseArrayType(shorthand);
+    if (arrayType) return arrayType;
+
+    return { type: shorthand as JSONSchema['type'] };
+  }
+
+  // Object shorthand: { age: "number", address: { city: "string" } }
+  const properties: Record<string, JSONSchema> = {};
+
+  for (const [key, value] of Object.entries(shorthand)) {
+    properties[key] = normalizeShape(value);
+  }
+
+  return {
+    type: 'object',
+    properties
+  };
+}
+
+export function normalizeShape(shape: Shape): JSONSchema {
+  if (isJSONSchema(shape)) {
+    // Already JSON Schema, normalize nested
+    const result: JSONSchema = { type: shape.type };
+
+    if (shape.properties) {
+      result.properties = {};
+      for (const [key, value] of Object.entries(shape.properties)) {
+        result.properties[key] = normalizeShape(value);
+      }
+    }
+
+    if (shape.items) {
+      result.items = normalizeShape(shape.items);
+    }
+
+    if (shape.minimum !== undefined) result.minimum = shape.minimum;
+    if (shape.maximum !== undefined) result.maximum = shape.maximum;
+    if (shape['x-unit']) result['x-unit'] = shape['x-unit'];
+
+    return result;
+  }
+
+  return normalizeShorthand(shape);
+}