@dxos/datalog 0.0.1 → 0.13.0

package/src/internal/plan.ts

@@ -0,0 +1,346 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Ast from '../Ast.ts';
+import * as Builtin from '../Builtin.ts';
+
+/** A term resolved against a rule's variable slots; `wild` is an anonymous variable. */
+export type Ref =
+  | { readonly kind: 'const'; readonly value: Ast.Value }
+  | { readonly kind: 'slot'; readonly slot: number }
+  | { readonly kind: 'wild' };
+
+export type ScanStep = {
+  readonly kind: 'scan';
+  readonly literal: number;
+  readonly relation: string;
+  /** Columns whose value is known before the scan, with the value source. */
+  readonly bound: ReadonlyArray<{ readonly column: number; readonly ref: Ref }>;
+  /** Columns that bind a slot, or check it when the variable repeats within the atom. */
+  readonly binds: ReadonlyArray<{ readonly column: number; readonly slot: number }>;
+};
+
+export type NegationStep = {
+  readonly kind: 'negation';
+  readonly relation: string;
+  readonly bound: ReadonlyArray<{ readonly column: number; readonly ref: Ref }>;
+};
+
+export type CompareStep = {
+  readonly kind: 'compare';
+  readonly operator: Ast.ComparisonOperator;
+  readonly left: Ref;
+  readonly right: Ref;
+  /** Set for `X = term` with `X` unbound: assigns instead of comparing. */
+  readonly assign?: { readonly slot: number; readonly from: Ref };
+};
+
+export type BuiltinStep = {
+  readonly kind: 'builtin';
+  readonly builtin: Builtin.Builtin;
+  readonly args: ReadonlyArray<Ref>;
+  /** Arguments unbound at call time, passed as `undefined` and bound from the results. */
+  readonly free: ReadonlyArray<boolean>;
+  readonly negated: boolean;
+};
+
+export type AggregateStep = {
+  readonly kind: 'aggregate';
+  readonly function: Ast.AggregateFunction;
+  readonly steps: ReadonlyArray<Step>;
+  /** Slots local to the aggregate body; distinct assignments of these are aggregated. */
+  readonly local: ReadonlyArray<number>;
+  readonly target?: Ref;
+  readonly result: Ref;
+  readonly assignResult: boolean;
+};
+
+export type Step = ScanStep | NegationStep | CompareStep | BuiltinStep | AggregateStep;
+
+export type Unresolved = { readonly literal: number; readonly reason: string };
+
+export type Plan = {
+  readonly steps: ReadonlyArray<Step>;
+  readonly unresolved: ReadonlyArray<Unresolved>;
+  readonly bound: ReadonlySet<string>;
+};
+
+/** Assigns a slot per named variable of a rule. */
+export class Slots {
+  readonly #slots = new Map<string, number>();
+
+  get size(): number {
+    return this.#slots.size;
+  }
+
+  slot(name: string): number {
+    let slot = this.#slots.get(name);
+    if (slot === undefined) {
+      slot = this.#slots.size;
+      this.#slots.set(name, slot);
+    }
+    return slot;
+  }
+
+  ref(term: Ast.Term): Ref {
+    if (term.type === 'constant') {
+      return { kind: 'const', value: term.value };
+    }
+    return term.anonymous ? { kind: 'wild' } : { kind: 'slot', slot: this.slot(term.name) };
+  }
+}
+
+const isBound = (term: Ast.Term, bound: ReadonlySet<string>) =>
+  term.type === 'constant' || (!term.anonymous && bound.has(term.name));
+
+const unboundNames = (terms: ReadonlyArray<Ast.Term>, bound: ReadonlySet<string>) =>
+  terms.flatMap((term) => (term.type === 'variable' && !term.anonymous && !bound.has(term.name) ? [term.name] : []));
+
+const variableNames = (literal: Ast.Literal): string[] => {
+  switch (literal.type) {
+    case 'atom':
+      return literal.atom.terms.flatMap((term) => (term.type === 'variable' && !term.anonymous ? [term.name] : []));
+    case 'comparison':
+      return [literal.left, literal.right].flatMap((term) =>
+        term.type === 'variable' && !term.anonymous ? [term.name] : [],
+      );
+    case 'aggregate':
+      return [
+        ...[literal.result, ...(literal.target ? [literal.target] : [])].flatMap((term) =>
+          term.type === 'variable' && !term.anonymous ? [term.name] : [],
+        ),
+        ...literal.body.flatMap(variableNames),
+      ];
+  }
+};
+
+/**
+ * Orders a rule body so every literal runs once its inputs are bound: filters as early as
+ * possible, then the relation scan with the most bound columns, then generating built-ins.
+ * @param outer Variables used outside the body (the head, or the enclosing rule of an aggregate).
+ * @param first Literal to scan first (the semi-naive delta).
+ */
+export const planBody = (options: {
+  body: ReadonlyArray<Ast.Literal>;
+  builtins: Builtin.Registry;
+  slots: Slots;
+  outer: ReadonlySet<string>;
+  bound?: ReadonlySet<string>;
+  first?: number;
+}): Plan => {
+  const { body, builtins, slots, outer, first } = options;
+  const bound = new Set(options.bound ?? []);
+  const steps: Step[] = [];
+  const remaining = new Set(body.keys());
+  const unresolved: Unresolved[] = [];
+
+  const scan = (index: number, literal: Ast.AtomLiteral) => {
+    const boundColumns: { column: number; ref: Ref }[] = [];
+    const binds: { column: number; slot: number }[] = [];
+    literal.atom.terms.forEach((term, column) => {
+      if (isBound(term, bound)) {
+        boundColumns.push({ column, ref: slots.ref(term) });
+      } else if (term.type === 'variable' && !term.anonymous) {
+        binds.push({ column, slot: slots.slot(term.name) });
+      }
+    });
+    for (const name of unboundNames(literal.atom.terms, bound)) {
+      bound.add(name);
+    }
+    steps.push({ kind: 'scan', literal: index, relation: literal.atom.predicate, bound: boundColumns, binds });
+  };
+
+  /** Variables any other literal or the outer scope uses, which an aggregate must correlate on. */
+  const correlated = (index: number, literal: Ast.AggregateLiteral): string[] => {
+    const elsewhere = new Set([...outer, ...body.flatMap((other, at) => (at === index ? [] : variableNames(other)))]);
+    const inner = new Set(literal.body.flatMap(variableNames));
+    return [...inner].filter((name) => elsewhere.has(name));
+  };
+
+  /** Schedules `index` if it is a filter (or, with `generate`, a generator) whose inputs are bound. */
+  const trySchedule = (index: number, generate: boolean): boolean => {
+    const literal = body[index];
+    switch (literal.type) {
+      case 'atom': {
+        const builtin = builtins.get(literal.atom.predicate);
+        if (!builtin) {
+          if (!literal.negated) {
+            return false;
+          }
+          if (unboundNames(literal.atom.terms, bound).length > 0) {
+            return false;
+          }
+          steps.push({
+            kind: 'negation',
+            relation: literal.atom.predicate,
+            bound: literal.atom.terms.flatMap((term, column) =>
+              term.type === 'variable' && term.anonymous ? [] : [{ column, ref: slots.ref(term) }],
+            ),
+          });
+          return true;
+        }
+        const boundArgs = literal.atom.terms.map((term) => isBound(term, bound));
+        const allBound = boundArgs.every(Boolean);
+        if (!allBound && (!generate || literal.negated || !Builtin.acceptsBinding(builtin, boundArgs))) {
+          return false;
+        }
+        steps.push({
+          kind: 'builtin',
+          builtin,
+          args: literal.atom.terms.map((term) => slots.ref(term)),
+          free: boundArgs.map((value) => !value),
+          negated: literal.negated,
+        });
+        for (const name of unboundNames(literal.atom.terms, bound)) {
+          bound.add(name);
+        }
+        return true;
+      }
+      case 'comparison': {
+        const left = isBound(literal.left, bound);
+        const right = isBound(literal.right, bound);
+        if (left && right) {
+          steps.push({
+            kind: 'compare',
+            operator: literal.operator,
+            left: slots.ref(literal.left),
+            right: slots.ref(literal.right),
+          });
+          return true;
+        }
+        if (!generate || literal.operator !== '=' || left === right) {
+          return false;
+        }
+        const [target, source] = left ? [literal.right, literal.left] : [literal.left, literal.right];
+        if (target.type !== 'variable' || target.anonymous) {
+          return false;
+        }
+        steps.push({
+          kind: 'compare',
+          operator: '=',
+          left: slots.ref(literal.left),
+          right: slots.ref(literal.right),
+          assign: { slot: slots.slot(target.name), from: slots.ref(source) },
+        });
+        bound.add(target.name);
+        return true;
+      }
+      case 'aggregate': {
+        const correlation = correlated(index, literal);
+        if (correlation.some((name) => !bound.has(name))) {
+          return false;
+        }
+        const resultBound = isBound(literal.result, bound);
+        if (!resultBound && !generate) {
+          return false;
+        }
+        const inner = planBody({
+          body: literal.body,
+          builtins,
+          slots,
+          outer: new Set(correlation),
+          bound: new Set(correlation),
+        });
+        if (inner.unresolved.length > 0) {
+          unresolved.push(...inner.unresolved.map(({ reason }) => ({ literal: index, reason })));
+          return true;
+        }
+        if (literal.target && !isBound(literal.target, inner.bound)) {
+          unresolved.push({ literal: index, reason: `aggregate target is not bound by the aggregate body` });
+          return true;
+        }
+        const local = [...inner.bound].filter((name) => !correlation.includes(name)).map((name) => slots.slot(name));
+        steps.push({
+          kind: 'aggregate',
+          function: literal.function,
+          steps: inner.steps,
+          local,
+          target: literal.target ? slots.ref(literal.target) : undefined,
+          result: slots.ref(literal.result),
+          assignResult: !resultBound,
+        });
+        if (literal.result.type === 'variable' && !literal.result.anonymous) {
+          bound.add(literal.result.name);
+        }
+        return true;
+      }
+    }
+  };
+
+  if (first !== undefined) {
+    const literal = body[first];
+    if (literal.type === 'atom' && !literal.negated && !builtins.has(literal.atom.predicate)) {
+      remaining.delete(first);
+      scan(first, literal);
+    }
+  }
+
+  while (remaining.size > 0) {
+    let progressed = false;
+    for (const index of remaining) {
+      if (trySchedule(index, false)) {
+        remaining.delete(index);
+        progressed = true;
+      }
+    }
+    if (progressed) {
+      continue;
+    }
+
+    let best: number | undefined;
+    let bestBound = -1;
+    for (const index of remaining) {
+      const literal = body[index];
+      if (literal.type === 'atom' && !literal.negated && !builtins.has(literal.atom.predicate)) {
+        const boundCount = literal.atom.terms.filter((term) => isBound(term, bound)).length;
+        if (boundCount > bestBound) {
+          best = index;
+          bestBound = boundCount;
+        }
+      }
+    }
+    if (best !== undefined) {
+      const literal = body[best];
+      if (literal.type === 'atom') {
+        remaining.delete(best);
+        scan(best, literal);
+      }
+      continue;
+    }
+
+    for (const index of remaining) {
+      if (trySchedule(index, true)) {
+        remaining.delete(index);
+        progressed = true;
+        break;
+      }
+    }
+    if (!progressed) {
+      break;
+    }
+  }
+
+  for (const index of remaining) {
+    unresolved.push({ literal: index, reason: describeUnresolved(body[index], bound, builtins) });
+  }
+  return { steps, unresolved, bound };
+};
+
+const describeUnresolved = (literal: Ast.Literal, bound: ReadonlySet<string>, builtins: Builtin.Registry): string => {
+  switch (literal.type) {
+    case 'atom': {
+      const names = unboundNames(literal.atom.terms, bound).join(', ');
+      if (builtins.has(literal.atom.predicate)) {
+        return literal.negated
+          ? `negated built-in ${literal.atom.predicate} needs every argument bound (${names} unbound)`
+          : `no binding mode of built-in ${literal.atom.predicate}/${literal.atom.terms.length} accepts ${names} unbound`;
+      }
+      return `variable ${names} under negation is not bound by a positive literal`;
+    }
+    case 'comparison':
+      return `variable ${unboundNames([literal.left, literal.right], bound).join(', ')} in comparison is not bound`;
+    case 'aggregate':
+      return `aggregate depends on unbound variables`;
+  }
+};

package/src/internal/relation.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Ast from '../Ast.ts';
+
+/** Collision-free key: the type tag keeps `1` and `"1"` apart. */
+export const valueKey = (value: Ast.Value): string => (typeof value === 'number' ? `n${value}` : `s${value}`);
+
+export const tupleKey = (tuple: Ast.Tuple): string => tuple.map(valueKey).join('\u0001');
+
+/** Total order over values: numbers before strings, numbers numerically, strings by code unit. */
+export const compareValues = (left: Ast.Value, right: Ast.Value): number => {
+  if (typeof left === 'number' && typeof right === 'number') {
+    return left - right;
+  }
+  if (typeof left === 'number') {
+    return -1;
+  }
+  if (typeof right === 'number') {
+    return 1;
+  }
+  return left < right ? -1 : left > right ? 1 : 0;
+};
+
+/** A set of tuples with lazily built hash indexes over bound column sets. */
+export class Relation {
+  readonly #tuples = new Map<string, Ast.Tuple>();
+  readonly #indexes = new Map<string, Index>();
+
+  get size(): number {
+    return this.#tuples.size;
+  }
+
+  values(): IterableIterator<Ast.Tuple> {
+    return this.#tuples.values();
+  }
+
+  entries(): IterableIterator<[string, Ast.Tuple]> {
+    return this.#tuples.entries();
+  }
+
+  has(key: string): boolean {
+    return this.#tuples.has(key);
+  }
+
+  /** Adds a tuple; returns false if it was already present. */
+  add(tuple: Ast.Tuple, key = tupleKey(tuple)): boolean {
+    if (this.#tuples.has(key)) {
+      return false;
+    }
+    this.#tuples.set(key, tuple);
+    for (const index of this.#indexes.values()) {
+      insert(index, tuple);
+    }
+    return true;
+  }
+
+  delete(key: string): boolean {
+    const deleted = this.#tuples.delete(key);
+    if (deleted) {
+      this.#indexes.clear();
+    }
+    return deleted;
+  }
+
+  /** Tuples whose `columns` equal `values`; scans everything when no column is bound. */
+  lookup(columns: ReadonlyArray<number>, values: ReadonlyArray<Ast.Value>): Iterable<Ast.Tuple> {
+    if (columns.length === 0) {
+      return this.#tuples.values();
+    }
+    const columnsKey = columns.join(',');
+    let index = this.#indexes.get(columnsKey);
+    if (!index) {
+      index = { columns, buckets: new Map() };
+      for (const tuple of this.#tuples.values()) {
+        insert(index, tuple);
+      }
+      this.#indexes.set(columnsKey, index);
+    }
+    return index.buckets.get(values.map(valueKey).join('\u0001')) ?? [];
+  }
+}
+
+type Index = { readonly columns: ReadonlyArray<number>; readonly buckets: Map<string, Ast.Tuple[]> };
+
+const insert = (index: Index, tuple: Ast.Tuple) => {
+  const key = index.columns.map((column) => valueKey(tuple[column])).join('\u0001');
+  const bucket = index.buckets.get(key);
+  if (bucket) {
+    bucket.push(tuple);
+  } else {
+    index.buckets.set(key, [tuple]);
+  }
+};

package/src/internal/stratify.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Ast from '../Ast.ts';
+import type * as Builtin from '../Builtin.ts';
+
+export type Dependency = { readonly predicate: string; readonly negative: boolean };
+
+export type Stratum = {
+  /** Predicates defined by the stratum's rules (one strongly connected component). */
+  readonly predicates: ReadonlySet<string>;
+  /** Indexes into the program's rules. */
+  readonly rules: ReadonlyArray<number>;
+  readonly recursive: boolean;
+};
+
+export type Stratification =
+  | { readonly ok: true; readonly strata: ReadonlyArray<Stratum> }
+  | { readonly ok: false; readonly cycles: ReadonlyArray<ReadonlyArray<string>> };
+
+/** Relations a literal reads; negation and aggregation read them non-monotonically. */
+export const dependencies = (literal: Ast.Literal, builtins: Builtin.Registry): Dependency[] => {
+  switch (literal.type) {
+    case 'atom':
+      return builtins.has(literal.atom.predicate)
+        ? []
+        : [{ predicate: literal.atom.predicate, negative: literal.negated }];
+    case 'comparison':
+      return [];
+    case 'aggregate':
+      return literal.body.flatMap((inner) =>
+        dependencies(inner, builtins).map(({ predicate }) => ({ predicate, negative: true })),
+      );
+  }
+};
+
+/**
+ * Splits rules into strata: one per strongly connected component of the predicate graph, in
+ * dependency order; fails when negation or aggregation occurs inside a component.
+ */
+export const stratify = (rules: ReadonlyArray<Ast.Rule>, builtins: Builtin.Registry): Stratification => {
+  const defined = new Set(rules.filter((rule) => rule.body.length > 0).map((rule) => rule.head.predicate));
+  const edges = new Map<string, Dependency[]>();
+  for (const predicate of defined) {
+    edges.set(predicate, []);
+  }
+  for (const rule of rules) {
+    for (const literal of rule.body) {
+      for (const dependency of dependencies(literal, builtins)) {
+        if (defined.has(dependency.predicate)) {
+          edges.get(rule.head.predicate)?.push(dependency);
+        }
+      }
+    }
+  }
+
+  // Tarjan's algorithm emits each component after every component it depends on.
+  const components: string[][] = [];
+  const index = new Map<string, number>();
+  const lowLink = new Map<string, number>();
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+  const visit = (predicate: string) => {
+    index.set(predicate, index.size);
+    lowLink.set(predicate, index.get(predicate) ?? 0);
+    stack.push(predicate);
+    onStack.add(predicate);
+    for (const { predicate: next } of edges.get(predicate) ?? []) {
+      if (!index.has(next)) {
+        visit(next);
+        lowLink.set(predicate, Math.min(lowLink.get(predicate) ?? 0, lowLink.get(next) ?? 0));
+      } else if (onStack.has(next)) {
+        lowLink.set(predicate, Math.min(lowLink.get(predicate) ?? 0, index.get(next) ?? 0));
+      }
+    }
+    if (lowLink.get(predicate) === index.get(predicate)) {
+      const component: string[] = [];
+      let member: string | undefined;
+      do {
+        member = stack.pop();
+        if (member !== undefined) {
+          onStack.delete(member);
+          component.push(member);
+        }
+      } while (member !== undefined && member !== predicate);
+      components.push(component);
+    }
+  };
+  for (const predicate of defined) {
+    if (!index.has(predicate)) {
+      visit(predicate);
+    }
+  }
+
+  const cycles: string[][] = [];
+  const strata: Stratum[] = components.map((component) => {
+    const members = new Set(component);
+    const internal = component.flatMap((predicate) =>
+      (edges.get(predicate) ?? []).filter((dependency) => members.has(dependency.predicate)),
+    );
+    if (internal.some((dependency) => dependency.negative)) {
+      cycles.push(component.sort());
+    }
+    return {
+      predicates: members,
+      rules: rules.flatMap((rule, ruleIndex) =>
+        rule.body.length > 0 && members.has(rule.head.predicate) ? [ruleIndex] : [],
+      ),
+      recursive: internal.length > 0,
+    };
+  });
+  return cycles.length > 0 ? { ok: false, cycles } : { ok: true, strata };
+};