@dxos/datalog 0.0.1 → 0.12.0

package/src/Ast.ts

@@ -0,0 +1,136 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+/** A ground value; symbols (`dima`) and strings (`"dima"`) are the same value. */
+export type Value = string | number;
+
+/** A ground row of a relation. */
+export type Tuple = ReadonlyArray<Value>;
+
+/** Source location (1-based line and column). */
+export type Position = { readonly line: number; readonly column: number };
+
+export type Variable = {
+  readonly type: 'variable';
+  readonly name: string;
+  /** Set for `_`; each occurrence is a distinct, never-joined variable. */
+  readonly anonymous?: boolean;
+};
+
+export type Constant = { readonly type: 'constant'; readonly value: Value };
+
+export type Term = Variable | Constant;
+
+export type Atom = { readonly predicate: string; readonly terms: ReadonlyArray<Term> };
+
+export type ComparisonOperator = '=' | '!=' | '<' | '<=' | '>' | '>=';
+
+export type AggregateFunction = 'count' | 'min' | 'max' | 'sum';
+
+export type AtomLiteral = {
+  readonly type: 'atom';
+  readonly atom: Atom;
+  readonly negated: boolean;
+  readonly position?: Position;
+};
+
+export type ComparisonLiteral = {
+  readonly type: 'comparison';
+  readonly operator: ComparisonOperator;
+  readonly left: Term;
+  readonly right: Term;
+  readonly position?: Position;
+};
+
+/** `Result = fn Target : { body }`; `Target` is absent for `count`. */
+export type AggregateLiteral = {
+  readonly type: 'aggregate';
+  readonly function: AggregateFunction;
+  readonly result: Term;
+  readonly target?: Term;
+  readonly body: ReadonlyArray<Literal>;
+  readonly position?: Position;
+};
+
+export type Literal = AtomLiteral | ComparisonLiteral | AggregateLiteral;
+
+/** A rule; a fact is a rule with an empty body. */
+export type Rule = {
+  readonly head: Atom;
+  readonly body: ReadonlyArray<Literal>;
+  readonly position?: Position;
+};
+
+export type Program = { readonly rules: ReadonlyArray<Rule> };
+
+/** Creates a variable term. */
+export const variable = (name: string): Variable => ({ type: 'variable', name });
+
+/** Creates a constant term. */
+export const constant = (value: Value): Constant => ({ type: 'constant', value });
+
+/** Creates an atom. */
+export const atom = (predicate: string, terms: ReadonlyArray<Term>): Atom => ({ predicate, terms });
+
+/** Named (non-anonymous) variables of a term list, in order of first occurrence. */
+export const variablesOf = (terms: ReadonlyArray<Term>): string[] => {
+  const names: string[] = [];
+  for (const term of terms) {
+    if (term.type === 'variable' && !term.anonymous && !names.includes(term.name)) {
+      names.push(term.name);
+    }
+  }
+  return names;
+};
+
+/** Named variables a literal mentions, including those inside an aggregate body. */
+export const literalVariables = (literal: Literal): string[] => {
+  switch (literal.type) {
+    case 'atom':
+      return variablesOf(literal.atom.terms);
+    case 'comparison':
+      return variablesOf([literal.left, literal.right]);
+    case 'aggregate': {
+      const terms = [literal.result, ...(literal.target ? [literal.target] : [])];
+      return [...new Set([...variablesOf(terms), ...literal.body.flatMap(literalVariables)])];
+    }
+  }
+};
+
+/** Formats a value as dialect source. */
+export const formatValue = (value: Value): string =>
+  typeof value === 'number' ? String(value) : /^[a-z][A-Za-z0-9_]*$/.test(value) ? value : JSON.stringify(value);
+
+/** Formats a term as dialect source. */
+export const formatTerm = (term: Term): string =>
+  term.type === 'constant' ? formatValue(term.value) : term.anonymous ? '_' : term.name;
+
+/** Formats an atom as dialect source. */
+export const formatAtom = (atom: Atom): string =>
+  atom.terms.length === 0 ? atom.predicate : `${atom.predicate}(${atom.terms.map(formatTerm).join(', ')})`;
+
+/** Formats a literal as dialect source. */
+export const formatLiteral = (literal: Literal): string => {
+  switch (literal.type) {
+    case 'atom':
+      return `${literal.negated ? 'not ' : ''}${formatAtom(literal.atom)}`;
+    case 'comparison':
+      return `${formatTerm(literal.left)} ${literal.operator} ${formatTerm(literal.right)}`;
+    case 'aggregate': {
+      const target = literal.target ? ` ${formatTerm(literal.target)}` : '';
+      return `${formatTerm(literal.result)} = ${literal.function}${target} : { ${literal.body.map(formatLiteral).join(', ')} }`;
+    }
+  }
+};
+
+/** Formats a rule as dialect source. */
+export const formatRule = (rule: Rule): string =>
+  rule.body.length === 0
+    ? `${formatAtom(rule.head)}.`
+    : `${formatAtom(rule.head)} :- ${rule.body.map(formatLiteral).join(', ')}.`;
+
+/** Formats a program as dialect source, one rule per line. */
+export const format = (program: Program): string => program.rules.map(formatRule).join('\n');

package/src/Builtin.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as Ast from './Ast.ts';
+
+/**
+ * A binding pattern, one character per argument: `b` must be bound before the call, `f` may be
+ * free and is bound by the call. `"fb"` lets the first argument be generated from the second.
+ */
+export type Mode = string;
+
+/** Arguments as seen by a built-in: `undefined` marks a free position of the selected mode. */
+export type Arguments = ReadonlyArray<Ast.Value | undefined>;
+
+/** A predicate implemented in code rather than by rules. */
+export type Builtin = {
+  readonly name: string;
+  readonly arity: number;
+  /** Accepted binding patterns; the all-bound pattern is always accepted. */
+  readonly modes: ReadonlyArray<Mode>;
+  /**
+   * Set when the result can change with no change to the facts (a clock), so the engine
+   * re-evaluates the rules that use it on `refresh`.
+   */
+  readonly volatile?: boolean;
+  /** Returns every full argument tuple that holds and agrees with the bound arguments. */
+  readonly evaluate: (args: Arguments) => Iterable<Ast.Tuple>;
+};
+
+/** Built-ins by name. */
+export type Registry = ReadonlyMap<string, Builtin>;
+
+/** Defines a built-in. */
+export const make = (builtin: Builtin): Builtin => builtin;
+
+/** Defines a test-only built-in: holds iff `test` returns true for its fully bound arguments. */
+export const predicate = (
+  name: string,
+  arity: number,
+  test: (args: Ast.Tuple) => boolean,
+  options: { volatile?: boolean } = {},
+): Builtin => ({
+  name,
+  arity,
+  modes: ['b'.repeat(arity)],
+  volatile: options.volatile,
+  evaluate: (args) => {
+    const bound = args.filter((arg): arg is Ast.Value => arg !== undefined);
+    return bound.length === arity && test(bound) ? [bound] : [];
+  },
+});
+
+/** Builds a registry, rejecting duplicate names. */
+export const registry = (...builtins: ReadonlyArray<Builtin>): Registry => {
+  const entries = new Map<string, Builtin>();
+  for (const builtin of builtins) {
+    if (entries.has(builtin.name)) {
+      throw new Error(`Duplicate built-in: ${builtin.name}`);
+    }
+    if (builtin.modes.some((mode) => mode.length !== builtin.arity || /[^bf]/.test(mode))) {
+      throw new Error(`Invalid mode for built-in ${builtin.name}/${builtin.arity}`);
+    }
+    entries.set(builtin.name, builtin);
+  }
+  return entries;
+};
+
+/** True if `builtin` can be called with exactly the `bound` argument positions bound. */
+export const acceptsBinding = (builtin: Builtin, bound: ReadonlyArray<boolean>): boolean =>
+  bound.every(Boolean) || builtin.modes.some((mode) => [...mode].every((flag, index) => flag === 'f' || bound[index]));

package/src/Checker.test.ts

@@ -0,0 +1,99 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Builtin from './Builtin.ts';
+import * as Checker from './Checker.ts';
+import * as Parser from './Parser.ts';
+
+const builtins = Builtin.registry(
+  Builtin.make({ name: 'about', arity: 2, modes: ['fb'], evaluate: () => [] }),
+  Builtin.predicate('later', 2, ([left, right]) => String(left) > String(right)),
+);
+
+const check = (source: string, options: Checker.Options = { builtins }) => Checker.check(Parser.parse(source), options);
+
+describe('Checker', () => {
+  test('accepts a safe, stratified program', ({ expect }) => {
+    expect(
+      check(`
+        path(X, Y) :- edge(X, Y).
+        path(X, Z) :- path(X, Y), edge(Y, Z).
+        unreachable(X, Y) :- node(X), node(Y), not path(X, Y).
+        hub(X, N) :- node(X), N = count : { edge(X, _) }, N > 2.
+        topic(F) :- about(F, "release").
+        recent(F) :- said(F, T), later(T, "2027-01-01").
+      `),
+    ).toEqual([]);
+  });
+
+  test('reports arity mismatches with positions', ({ expect }) => {
+    const diagnostics = check('p(X) :- q(X).\nr(X) :- q(X, X).');
+    expect(diagnostics).toEqual([
+      expect.objectContaining({ code: 'arity', rule: 1, position: { line: 2, column: 9 } }),
+    ]);
+  });
+
+  test('reports declared relation and built-in arity mismatches', ({ expect }) => {
+    const diagnostics = check('p(X) :- fact(X), about(X).', { builtins, relations: { fact: 4 } });
+    expect(diagnostics.map(({ code }) => code)).toEqual(['arity', 'arity']);
+  });
+
+  test('reports unsafe rules', ({ expect }) => {
+    const diagnostics = check(`
+      head(X) :- q(Y).
+      negated(X) :- q(X), not r(Y).
+      compared(X) :- q(X), Y > 3.
+      fact(X).
+    `);
+    expect(diagnostics.map(({ code, rule }) => [code, rule])).toEqual([
+      ['unsafe', 0],
+      ['unsafe', 1],
+      ['unsafe', 2],
+      ['unsafe', 3],
+    ]);
+    expect(diagnostics[1].message).toContain('variable Y under negation');
+  });
+
+  test('allows anonymous variables under negation', ({ expect }) => {
+    expect(check('empty :- marker(goal), not waiting(_).')).toEqual([]);
+  });
+
+  test('checks built-in binding modes', ({ expect }) => {
+    expect(check('p(F) :- about(F, T).').map(({ message }) => message)).toEqual([
+      expect.stringContaining('no binding mode of built-in about/2 accepts F, T unbound'),
+      expect.stringContaining('head variable F is not bound'),
+    ]);
+    expect(check('p(T) :- later(T, "x").').map(({ code }) => code)).toEqual(['unsafe', 'unsafe']);
+    expect(check('p(F) :- q(F), not about(F, "x").')).toEqual([]);
+  });
+
+  test('rejects rules that define a built-in', ({ expect }) => {
+    expect(check('about(F, T) :- q(F, T).').map(({ code }) => code)).toEqual(['builtin-head']);
+  });
+
+  test('rejects negation through recursion', ({ expect }) => {
+    const diagnostics = check('p :- not q.\nq :- not p.');
+    expect(diagnostics).toEqual([expect.objectContaining({ code: 'unstratifiable' })]);
+    expect(diagnostics[0].message).toContain('p, q');
+  });
+
+  test('rejects aggregation through recursion', ({ expect }) => {
+    const diagnostics = check('size(N) :- N = count : { member(_) }.\nmember(X) :- size(X).');
+    expect(diagnostics.map(({ code }) => code)).toEqual(['unstratifiable']);
+  });
+
+  test('reports undefined predicates when relations are declared', ({ expect }) => {
+    const diagnostics = check('p(X) :- fact(X), typo(X).', { builtins, relations: { fact: 1 } });
+    expect(diagnostics).toEqual([
+      expect.objectContaining({ code: 'undefined', message: expect.stringContaining('typo/1') }),
+    ]);
+  });
+
+  test('CheckError formats diagnostics', ({ expect }) => {
+    const error = new Checker.CheckError(check('p :- not q.\nq :- not p.'));
+    expect(error.message).toMatch(/^Invalid program:\n1:1 unstratifiable:/);
+  });
+});

package/src/Checker.ts

@@ -0,0 +1,156 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { BaseError } from '@dxos/errors';
+
+import * as Ast from './Ast.ts';
+import type * as Builtin from './Builtin.ts';
+import { Slots, planBody } from './internal/plan.ts';
+import { stratify } from './internal/stratify.ts';
+
+export type DiagnosticCode = 'arity' | 'builtin-head' | 'undefined' | 'unsafe' | 'unstratifiable';
+
+/** A static error in a program. */
+export type Diagnostic = {
+  readonly code: DiagnosticCode;
+  readonly message: string;
+  /** Index of the offending rule. */
+  readonly rule?: number;
+  readonly position?: Ast.Position;
+};
+
+export type Options = {
+  readonly builtins?: Builtin.Registry;
+  /**
+   * Base relations and their arities. When given, a body predicate that is neither defined by a
+   * rule, declared here nor a built-in is reported as `undefined`.
+   */
+  readonly relations?: Readonly<Record<string, number>>;
+};
+
+/** Thrown when a program with diagnostics is evaluated. */
+export class CheckError extends BaseError.extend('CheckError', 'Invalid program') {
+  // A typed field rather than `context`, which would repeat every diagnostic in the message as JSON.
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+
+  constructor(diagnostics: ReadonlyArray<Diagnostic>) {
+    super({ message: `Invalid program:\n${diagnostics.map(formatDiagnostic).join('\n')}` });
+    this.diagnostics = diagnostics;
+  }
+}
+
+/** Formats a diagnostic as `line:column code: message`. */
+export const formatDiagnostic = (diagnostic: Diagnostic): string => {
+  const at = diagnostic.position ? `${diagnostic.position.line}:${diagnostic.position.column} ` : '';
+  return `${at}${diagnostic.code}: ${diagnostic.message}`;
+};
+
+/**
+ * Checks arity consistency, built-in heads, undefined predicates, range restriction (safety) and
+ * stratification; an empty result means the program can be evaluated.
+ */
+export const check = (program: Ast.Program, options: Options = {}): Diagnostic[] => {
+  const builtins = options.builtins ?? new Map();
+  const diagnostics: Diagnostic[] = [];
+  const arities = new Map<string, number>();
+  for (const builtin of builtins.values()) {
+    arities.set(builtin.name, builtin.arity);
+  }
+  for (const [name, arity] of Object.entries(options.relations ?? {})) {
+    arities.set(name, arity);
+  }
+  const defined = new Set(program.rules.map((rule) => rule.head.predicate));
+
+  const visitAtom = (atom: Ast.Atom, rule: number, position: Ast.Position | undefined) => {
+    const expected = arities.get(atom.predicate);
+    if (expected === undefined) {
+      arities.set(atom.predicate, atom.terms.length);
+    } else if (expected !== atom.terms.length) {
+      diagnostics.push({
+        code: 'arity',
+        message: `${atom.predicate}/${atom.terms.length} used where ${atom.predicate}/${expected} is expected`,
+        rule,
+        position,
+      });
+    }
+  };
+  const visitLiteral = (literal: Ast.Literal, rule: number, fallback: Ast.Position | undefined) => {
+    const position = literal.position ?? fallback;
+    if (literal.type === 'atom') {
+      visitAtom(literal.atom, rule, position);
+      const predicate = literal.atom.predicate;
+      if (
+        options.relations &&
+        !defined.has(predicate) &&
+        !builtins.has(predicate) &&
+        !(predicate in options.relations)
+      ) {
+        diagnostics.push({
+          code: 'undefined',
+          message: `${predicate}/${literal.atom.terms.length} is not a relation, rule or built-in`,
+          rule,
+          position,
+        });
+      }
+    } else if (literal.type === 'aggregate') {
+      literal.body.forEach((inner) => visitLiteral(inner, rule, position));
+    }
+  };
+
+  program.rules.forEach((rule, index) => {
+    if (builtins.has(rule.head.predicate)) {
+      diagnostics.push({
+        code: 'builtin-head',
+        message: `rule defines built-in ${rule.head.predicate}`,
+        rule: index,
+        position: rule.position,
+      });
+    }
+    visitAtom(rule.head, index, rule.position);
+    rule.body.forEach((literal) => visitLiteral(literal, index, rule.position));
+
+    const head = new Set(Ast.variablesOf(rule.head.terms));
+    const plan = planBody({ body: rule.body, builtins, slots: new Slots(), outer: head });
+    for (const { literal, reason } of plan.unresolved) {
+      diagnostics.push({
+        code: 'unsafe',
+        message: `${reason} in: ${Ast.formatRule(rule)}`,
+        rule: index,
+        position: rule.body[literal].position ?? rule.position,
+      });
+    }
+    const unboundHead = [...head].filter((name) => !plan.bound.has(name));
+    if (unboundHead.length > 0) {
+      diagnostics.push({
+        code: 'unsafe',
+        message: `head variable ${unboundHead.join(', ')} is not bound by the body in: ${Ast.formatRule(rule)}`,
+        rule: index,
+        position: rule.position,
+      });
+    }
+    if (rule.head.terms.some((term) => term.type === 'variable' && term.anonymous)) {
+      diagnostics.push({
+        code: 'unsafe',
+        message: `anonymous variable in head of: ${Ast.formatRule(rule)}`,
+        rule: index,
+        position: rule.position,
+      });
+    }
+  });
+
+  const stratification = stratify(program.rules, builtins);
+  if (!stratification.ok) {
+    for (const cycle of stratification.cycles) {
+      diagnostics.push({
+        code: 'unstratifiable',
+        message: `negation or aggregation through recursion among: ${cycle.join(', ')}`,
+        rule: program.rules.findIndex((rule) => cycle.includes(rule.head.predicate)),
+        position: program.rules.find((rule) => cycle.includes(rule.head.predicate))?.position,
+      });
+    }
+  }
+  return diagnostics;
+};