simple-graph-query 2.3.0 → 2.5.0

package/README.md

@@ -6,3 +6,31 @@ A TypeScript library for evaluating relational + some more expressions with a br
 
 MIT
 
+## Selector synthesis overview
+
+The selector synthesizer infers a relational expression that returns exactly the atoms supplied in a set of training examples (pairs of `Set<IAtom>` and `IDataInstance`). The current implementation uses a bounded, enumerative search over a compact expression grammar (identifiers, unions/intersections/differences, joins, and transitive closure) that mirrors a lightweight Alloy fragment. The search works breadth-first by depth so that the first solution found is the simplest expression within the bound, and it only explores identifiers shared by every example plus Alloy built-ins like `univ` and `iden`.
+
+Although the implementation is enumerative, it follows the same spirit as CEGIS and FOIL-style learners: each candidate expression is validated against every provided example, immediately pruning failures before expanding the search frontier. This tight feedback loop keeps the search space tractable in bounded instances while still allowing compositional operators (e.g., joins composed under closure) to satisfy more relational targets. Raising the `maxDepth` parameter broadens the hypothesis space when more complex solutions are needed, while lower depths keep synthesis fast for simple selectors.
+
+### Synthesis "why" explanations
+
+The `synthesizeSelectorWithWhy` and `synthesizeBinaryRelationWithWhy` helpers return a provenance tree alongside the synthesized expression. Each returned `examples[i].why` value mirrors the final expression: every node records the operator kind, the textual subexpression, and the evaluated result for that subexpression in the corresponding datum. Binary operators (union, intersection, difference, join) list two children, closures list one, and identifiers are leaves.
+
+For example, synthesizing a selector for `{a1, a2}` and `{b1}` produces:
+
+```ts
+const { expression, examples } = synthesizeSelectorWithWhy([
+  { atoms: new Set([a1, a2]), datum: datumA },
+  { atoms: new Set([b1]), datum: datumB },
+]);
+
+// expression === "Thing"
+// examples[0].why === {
+//   kind: "identifier",
+//   expression: "Thing",
+//   result: new Set(["a1", "a2"]),
+// }
+```
+
+Synthesizing a binary relation explanation yields the same structure, but `result` contains normalized tuple identifiers (e.g., `"n1\u0000n3"`) for each subexpression. For a two-hop reachability example, the root `why` node would have `kind: "join"` with two child nodes describing the `edge` relations on the left and right of the join.
+

package/dist/SelectorSynthesizer.d.ts

@@ -0,0 +1,48 @@
+import { IAtom, IDataInstance } from "./types";
+export type AtomSelectionExample = {
+    atoms: Set<IAtom>;
+    datum: IDataInstance;
+};
+export type AtomPair = readonly [IAtom, IAtom];
+export type BinaryRelationExample = {
+    pairs: Set<AtomPair>;
+    datum: IDataInstance;
+};
+type ExpressionNode = {
+    kind: "identifier";
+    name: string;
+} | {
+    kind: "union" | "intersection" | "difference";
+    left: ExpressionNode;
+    right: ExpressionNode;
+} | {
+    kind: "join";
+    left: ExpressionNode;
+    right: ExpressionNode;
+} | {
+    kind: "closure";
+    child: ExpressionNode;
+};
+export type WhyNode = {
+    kind: ExpressionNode["kind"];
+    expression: string;
+    result: Set<string> | null;
+    children?: WhyNode[];
+};
+export declare class SelectorSynthesisError extends Error {
+}
+export declare function synthesizeSelector(examples: AtomSelectionExample[], maxDepth?: number): string;
+export declare function synthesizeBinaryRelation(examples: BinaryRelationExample[], maxDepth?: number): string;
+export type SynthesisWhyExample = {
+    datum: IDataInstance;
+    target: Set<string>;
+    result: Set<string> | null;
+    why: WhyNode;
+};
+export type SynthesisWhy = {
+    expression: string;
+    examples: SynthesisWhyExample[];
+};
+export declare function synthesizeSelectorWithWhy(examples: AtomSelectionExample[], maxDepth?: number): SynthesisWhy;
+export declare function synthesizeBinaryRelationWithWhy(examples: BinaryRelationExample[], maxDepth?: number): SynthesisWhy;
+export {};

package/dist/index.d.ts

@@ -16,3 +16,4 @@ export declare class SimpleGraphQueryEvaluator {
     getExpressionParseTree(forgeExpr: string): import("./forge-antlr/ForgeParser").ParseExprContext;
     evaluateExpression(forgeExpr: string): EvaluationResult;
 }
+export { synthesizeSelector, synthesizeBinaryRelation, synthesizeBinaryRelationWithWhy, synthesizeSelectorWithWhy, AtomSelectionExample, BinaryRelationExample, SelectorSynthesisError, SynthesisWhy, SynthesisWhyExample, WhyNode, } from './SelectorSynthesizer';

package/dist/simple-graph-query.bundle.js

@@ -50931,6 +50931,329 @@ function cartesianProduct(arrays) {
 }
 
 
+/***/ }),
+
+/***/ "./src/SelectorSynthesizer.ts":
+/*!************************************!*\
+  !*** ./src/SelectorSynthesizer.ts ***!
+  \************************************/
+/***/ ((__unused_webpack_module, exports, __webpack_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.SelectorSynthesisError = void 0;
+exports.synthesizeSelector = synthesizeSelector;
+exports.synthesizeBinaryRelation = synthesizeBinaryRelation;
+exports.synthesizeSelectorWithWhy = synthesizeSelectorWithWhy;
+exports.synthesizeBinaryRelationWithWhy = synthesizeBinaryRelationWithWhy;
+const index_1 = __webpack_require__(/*! ./index */ "./src/index.ts");
+class SelectorSynthesisError extends Error {
+}
+exports.SelectorSynthesisError = SelectorSynthesisError;
+function nodeToString(node) {
+    switch (node.kind) {
+        case "identifier":
+            return node.name;
+        case "closure": {
+            const inner = nodeToString(node.child);
+            return `^${wrapForPrefix(inner)}`;
+        }
+        case "join": {
+            const left = wrapForJoin(node.left);
+            const right = wrapForJoin(node.right);
+            return `${left}.${right}`;
+        }
+        case "union":
+            return `(${nodeToString(node.left)} + ${nodeToString(node.right)})`;
+        case "intersection":
+            return `(${nodeToString(node.left)} & ${nodeToString(node.right)})`;
+        case "difference":
+            return `(${nodeToString(node.left)} - ${nodeToString(node.right)})`;
+    }
+}
+function wrapForJoin(node) {
+    if (node.kind === "identifier" || node.kind === "closure") {
+        return nodeToString(node);
+    }
+    return `(${nodeToString(node)})`;
+}
+function wrapForPrefix(expr) {
+    return expr.startsWith("(") && expr.endsWith(")") ? expr : `(${expr})`;
+}
+function normalizeUnaryResult(result) {
+    // We only consider unary tuple results or single string values as valid atom selections
+    if (typeof result === "string") {
+        return new Set([result]);
+    }
+    if (!Array.isArray(result)) {
+        return null;
+    }
+    // Expect an array of tuples
+    const tuples = result;
+    const ids = new Set();
+    for (const tuple of tuples) {
+        if (!Array.isArray(tuple) || tuple.length !== 1) {
+            return null;
+        }
+        const value = tuple[0];
+        if (typeof value !== "string") {
+            return null;
+        }
+        ids.add(value);
+    }
+    return ids;
+}
+function normalizeBinaryResult(result) {
+    if (!Array.isArray(result)) {
+        return null;
+    }
+    const tuples = result;
+    const ids = new Set();
+    for (const tuple of tuples) {
+        if (!Array.isArray(tuple) || tuple.length !== 2) {
+            return null;
+        }
+        const [first, second] = tuple;
+        if (typeof first !== "string" || typeof second !== "string") {
+            return null;
+        }
+        ids.add(`${first}\u0000${second}`);
+    }
+    return ids;
+}
+function evaluateExpression(node, evaluator, normalizer) {
+    const expression = nodeToString(node);
+    const result = evaluator.evaluateExpression(expression);
+    return normalizer(result);
+}
+function intersectNames(datums) {
+    const identifierSets = datums.map((datum) => {
+        const typeIds = datum.getTypes().map((t) => t.id);
+        const relationNames = datum.getRelations().map((r) => r.name);
+        return new Set([...typeIds, ...relationNames]);
+    });
+    if (identifierSets.length === 0) {
+        return new Set();
+    }
+    const [first, ...rest] = identifierSets;
+    const intersection = new Set();
+    for (const id of first) {
+        if (rest.every((set) => set.has(id))) {
+            intersection.add(id);
+        }
+    }
+    return intersection;
+}
+function setsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const item of a) {
+        if (!b.has(item))
+            return false;
+    }
+    return true;
+}
+function classifyIdentifier(name, datums) {
+    if (name === "univ" || name === "iden") {
+        return "builtin";
+    }
+    for (const datum of datums) {
+        if (datum.getRelations().some((relation) => relation.name === name)) {
+            return "relation";
+        }
+        if (datum.getTypes().some((type) => type.id === name)) {
+            return "type";
+        }
+    }
+    return "other";
+}
+function buildBaseNodes(datums) {
+    const baseNames = intersectNames(datums);
+    // Always include standard top-level identifiers when present in the language
+    ["univ", "iden"].forEach((builtin) => baseNames.add(builtin));
+    const orderedNames = Array.from(baseNames).sort((left, right) => {
+        const priority = {
+            relation: 0,
+            type: 1,
+            builtin: 2,
+            other: 3,
+        };
+        const leftPriority = priority[classifyIdentifier(left, datums)];
+        const rightPriority = priority[classifyIdentifier(right, datums)];
+        if (leftPriority !== rightPriority) {
+            return leftPriority - rightPriority;
+        }
+        return left.localeCompare(right);
+    });
+    return orderedNames.map((name) => ({ kind: "identifier", name }));
+}
+function getOrCreateEvaluator(datum, cache) {
+    const existing = cache.get(datum);
+    if (existing) {
+        return existing;
+    }
+    const evaluator = new index_1.SimpleGraphQueryEvaluator(datum);
+    cache.set(datum, evaluator);
+    return evaluator;
+}
+function matchesTargets(node, examples, normalizer) {
+    for (const example of examples) {
+        const result = evaluateExpression(node, example.evaluator, normalizer);
+        if (!result)
+            return false;
+        if (!setsEqual(result, example.target)) {
+            return false;
+        }
+    }
+    return true;
+}
+function synthesizeExpressionNode(examples, normalizer, maxDepth = 3) {
+    // Enumerative, CEGIS-style search: we BFS over the expression grammar (identifiers, set ops, joins, closure),
+    // checking each candidate against *all* examples before allowing it to generate children. Early rejection of
+    // incorrect hypotheses keeps the frontier small (FOIL-esque pruning), while depth-bounding curbs blowup.
+    if (examples.length === 0) {
+        throw new SelectorSynthesisError("No examples provided for synthesis");
+    }
+    const evaluatorCache = new Map();
+    const evaluatedExamples = examples.map((example) => ({
+        ...example,
+        evaluator: getOrCreateEvaluator(example.datum, evaluatorCache),
+    }));
+    const datums = evaluatedExamples.map((example) => example.datum);
+    const baseNodes = buildBaseNodes(datums);
+    if (baseNodes.length === 0) {
+        throw new SelectorSynthesisError("No shared identifiers available across provided data instances");
+    }
+    for (const node of baseNodes) {
+        if (matchesTargets(node, evaluatedExamples, normalizer)) {
+            return node;
+        }
+    }
+    const queue = [];
+    const queued = new Set();
+    const visited = new Set();
+    const combinationPool = [...baseNodes];
+    const enqueue = (node, depth) => {
+        const key = nodeToString(node);
+        if (visited.has(key) || queued.has(key))
+            return;
+        queue.push({ node, depth });
+        queued.add(key);
+    };
+    baseNodes.forEach((node) => enqueue(node, 0));
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const key = nodeToString(current.node);
+        queued.delete(key);
+        if (visited.has(key)) {
+            continue;
+        }
+        visited.add(key);
+        if (matchesTargets(current.node, evaluatedExamples, normalizer)) {
+            return current.node;
+        }
+        if (current.depth >= maxDepth) {
+            continue;
+        }
+        // Unary expansions
+        enqueue({ kind: "closure", child: current.node }, current.depth + 1);
+        for (const other of combinationPool) {
+            const leftKey = nodeToString(current.node);
+            const rightKey = nodeToString(other);
+            const [unionLeft, unionRight] = leftKey < rightKey ? [current.node, other] : [other, current.node];
+            enqueue({ kind: "union", left: unionLeft, right: unionRight }, current.depth + 1);
+            const [interLeft, interRight] = leftKey < rightKey ? [current.node, other] : [other, current.node];
+            enqueue({ kind: "intersection", left: interLeft, right: interRight }, current.depth + 1);
+            enqueue({ kind: "join", left: current.node, right: other }, current.depth + 1);
+            enqueue({ kind: "join", left: other, right: current.node }, current.depth + 1);
+        }
+    }
+    throw new SelectorSynthesisError("Unable to synthesize an expression matching all examples");
+}
+function synthesizeSelector(examples, maxDepth = 3) {
+    const synthesisExamples = examples.map((example) => ({
+        datum: example.datum,
+        target: new Set(Array.from(example.atoms).map((atom) => atom.id)),
+    }));
+    const node = synthesizeExpressionNode(synthesisExamples, normalizeUnaryResult, maxDepth);
+    return nodeToString(node);
+}
+function synthesizeBinaryRelation(examples, maxDepth = 3) {
+    const synthesisExamples = examples.map((example) => {
+        const encodedPairs = new Set(Array.from(example.pairs).map(([left, right]) => `${left.id}\u0000${right.id}`));
+        return { datum: example.datum, target: encodedPairs };
+    });
+    const node = synthesizeExpressionNode(synthesisExamples, normalizeBinaryResult, maxDepth);
+    return nodeToString(node);
+}
+function buildWhyNode(node, evaluator, normalizer) {
+    const result = evaluateExpression(node, evaluator, normalizer);
+    const base = {
+        kind: node.kind,
+        expression: nodeToString(node),
+        result,
+    };
+    switch (node.kind) {
+        case "identifier":
+            return base;
+        case "closure":
+            return { ...base, children: [buildWhyNode(node.child, evaluator, normalizer)] };
+        case "join":
+        case "union":
+        case "intersection":
+        case "difference":
+            return {
+                ...base,
+                children: [
+                    buildWhyNode(node.left, evaluator, normalizer),
+                    buildWhyNode(node.right, evaluator, normalizer),
+                ],
+            };
+        default:
+            return base;
+    }
+}
+function synthesizeSelectorWithWhy(examples, maxDepth = 3) {
+    const synthesisExamples = examples.map((example) => ({
+        datum: example.datum,
+        target: new Set(Array.from(example.atoms).map((atom) => atom.id)),
+    }));
+    const node = synthesizeExpressionNode(synthesisExamples, normalizeUnaryResult, maxDepth);
+    const expression = nodeToString(node);
+    const evaluatorCache = new Map();
+    const explanationExamples = synthesisExamples.map((example) => {
+        const evaluator = getOrCreateEvaluator(example.datum, evaluatorCache);
+        return {
+            datum: example.datum,
+            target: example.target,
+            result: evaluateExpression(node, evaluator, normalizeUnaryResult),
+            why: buildWhyNode(node, evaluator, normalizeUnaryResult),
+        };
+    });
+    return { expression, examples: explanationExamples };
+}
+function synthesizeBinaryRelationWithWhy(examples, maxDepth = 3) {
+    const synthesisExamples = examples.map((example) => {
+        const encodedPairs = new Set(Array.from(example.pairs).map(([left, right]) => `${left.id}\u0000${right.id}`));
+        return { datum: example.datum, target: encodedPairs };
+    });
+    const node = synthesizeExpressionNode(synthesisExamples, normalizeBinaryResult, maxDepth);
+    const expression = nodeToString(node);
+    const evaluatorCache = new Map();
+    const explanationExamples = synthesisExamples.map((example) => {
+        const evaluator = getOrCreateEvaluator(example.datum, evaluatorCache);
+        return {
+            datum: example.datum,
+            target: example.target,
+            result: evaluateExpression(node, evaluator, normalizeBinaryResult),
+            why: buildWhyNode(node, evaluator, normalizeBinaryResult),
+        };
+    });
+    return { expression, examples: explanationExamples };
+}
+
+
 /***/ }),
 
 /***/ "./src/errorListener.ts":
@@ -61472,71 +61795,18 @@ class ConsistencyAssertionTest extends SyntaxNode {
 exports.ConsistencyAssertionTest = ConsistencyAssertionTest;
 
 
-/***/ })
+/***/ }),
 
-/******/ 	});
-/************************************************************************/
-/******/ 	// The module cache
-/******/ 	var __webpack_module_cache__ = {};
-/******/ 	
-/******/ 	// The require function
-/******/ 	function __webpack_require__(moduleId) {
-/******/ 		// Check if module is in cache
-/******/ 		var cachedModule = __webpack_module_cache__[moduleId];
-/******/ 		if (cachedModule !== undefined) {
-/******/ 			return cachedModule.exports;
-/******/ 		}
-/******/ 		// Create a new module (and put it into the cache)
-/******/ 		var module = __webpack_module_cache__[moduleId] = {
-/******/ 			id: moduleId,
-/******/ 			loaded: false,
-/******/ 			exports: {}
-/******/ 		};
-/******/ 	
-/******/ 		// Execute the module function
-/******/ 		__webpack_modules__[moduleId].call(module.exports, module, module.exports, __webpack_require__);
-/******/ 	
-/******/ 		// Flag the module as loaded
-/******/ 		module.loaded = true;
-/******/ 	
-/******/ 		// Return the exports of the module
-/******/ 		return module.exports;
-/******/ 	}
-/******/ 	
-/************************************************************************/
-/******/ 	/* webpack/runtime/global */
-/******/ 	(() => {
-/******/ 		__webpack_require__.g = (function() {
-/******/ 			if (typeof globalThis === 'object') return globalThis;
-/******/ 			try {
-/******/ 				return this || new Function('return this')();
-/******/ 			} catch (e) {
-/******/ 				if (typeof window === 'object') return window;
-/******/ 			}
-/******/ 		})();
-/******/ 	})();
-/******/ 	
-/******/ 	/* webpack/runtime/node module decorator */
-/******/ 	(() => {
-/******/ 		__webpack_require__.nmd = (module) => {
-/******/ 			module.paths = [];
-/******/ 			if (!module.children) module.children = [];
-/******/ 			return module;
-/******/ 		};
-/******/ 	})();
-/******/ 	
-/************************************************************************/
-var __webpack_exports__ = {};
-// This entry needs to be wrapped in an IIFE because it needs to be in strict mode.
-(() => {
-"use strict";
-var exports = __webpack_exports__;
+/***/ "./src/index.ts":
 /*!**********************!*\
   !*** ./src/index.ts ***!
   \**********************/
+/***/ ((__unused_webpack_module, exports, __webpack_require__) => {
+
+"use strict";
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.SimpleGraphQueryEvaluator = void 0;
+exports.SelectorSynthesisError = exports.synthesizeSelectorWithWhy = exports.synthesizeBinaryRelationWithWhy = exports.synthesizeBinaryRelation = exports.synthesizeSelector = exports.SimpleGraphQueryEvaluator = void 0;
 const antlr4ts_1 = __webpack_require__(/*! antlr4ts */ "./node_modules/antlr4ts/index.js");
 const ForgeParser_1 = __webpack_require__(/*! ./forge-antlr/ForgeParser */ "./src/forge-antlr/ForgeParser.ts");
 const ForgeLexer_1 = __webpack_require__(/*! ./forge-antlr/ForgeLexer */ "./src/forge-antlr/ForgeLexer.ts");
@@ -61619,9 +61889,74 @@ class SimpleGraphQueryEvaluator {
     }
 }
 exports.SimpleGraphQueryEvaluator = SimpleGraphQueryEvaluator;
+var SelectorSynthesizer_1 = __webpack_require__(/*! ./SelectorSynthesizer */ "./src/SelectorSynthesizer.ts");
+Object.defineProperty(exports, "synthesizeSelector", ({ enumerable: true, get: function () { return SelectorSynthesizer_1.synthesizeSelector; } }));
+Object.defineProperty(exports, "synthesizeBinaryRelation", ({ enumerable: true, get: function () { return SelectorSynthesizer_1.synthesizeBinaryRelation; } }));
+Object.defineProperty(exports, "synthesizeBinaryRelationWithWhy", ({ enumerable: true, get: function () { return SelectorSynthesizer_1.synthesizeBinaryRelationWithWhy; } }));
+Object.defineProperty(exports, "synthesizeSelectorWithWhy", ({ enumerable: true, get: function () { return SelectorSynthesizer_1.synthesizeSelectorWithWhy; } }));
+Object.defineProperty(exports, "SelectorSynthesisError", ({ enumerable: true, get: function () { return SelectorSynthesizer_1.SelectorSynthesisError; } }));
 
-})();
 
+/***/ })
+
+/******/ 	});
+/************************************************************************/
+/******/ 	// The module cache
+/******/ 	var __webpack_module_cache__ = {};
+/******/ 	
+/******/ 	// The require function
+/******/ 	function __webpack_require__(moduleId) {
+/******/ 		// Check if module is in cache
+/******/ 		var cachedModule = __webpack_module_cache__[moduleId];
+/******/ 		if (cachedModule !== undefined) {
+/******/ 			return cachedModule.exports;
+/******/ 		}
+/******/ 		// Create a new module (and put it into the cache)
+/******/ 		var module = __webpack_module_cache__[moduleId] = {
+/******/ 			id: moduleId,
+/******/ 			loaded: false,
+/******/ 			exports: {}
+/******/ 		};
+/******/ 	
+/******/ 		// Execute the module function
+/******/ 		__webpack_modules__[moduleId].call(module.exports, module, module.exports, __webpack_require__);
+/******/ 	
+/******/ 		// Flag the module as loaded
+/******/ 		module.loaded = true;
+/******/ 	
+/******/ 		// Return the exports of the module
+/******/ 		return module.exports;
+/******/ 	}
+/******/ 	
+/************************************************************************/
+/******/ 	/* webpack/runtime/global */
+/******/ 	(() => {
+/******/ 		__webpack_require__.g = (function() {
+/******/ 			if (typeof globalThis === 'object') return globalThis;
+/******/ 			try {
+/******/ 				return this || new Function('return this')();
+/******/ 			} catch (e) {
+/******/ 				if (typeof window === 'object') return window;
+/******/ 			}
+/******/ 		})();
+/******/ 	})();
+/******/ 	
+/******/ 	/* webpack/runtime/node module decorator */
+/******/ 	(() => {
+/******/ 		__webpack_require__.nmd = (module) => {
+/******/ 			module.paths = [];
+/******/ 			if (!module.children) module.children = [];
+/******/ 			return module;
+/******/ 		};
+/******/ 	})();
+/******/ 	
+/************************************************************************/
+/******/ 	
+/******/ 	// startup
+/******/ 	// Load entry module and return exports
+/******/ 	// This entry module is referenced by other modules so it can't be inlined
+/******/ 	var __webpack_exports__ = __webpack_require__("./src/index.ts");
+/******/ 	
 /******/ 	return __webpack_exports__;
 /******/ })()
 ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-graph-query",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "TypeScript evaluator for Forge expressions with browser-compatible UMD bundle",
   "main": "dist/simple-graph-query.bundle.js",
   "types": "dist/index.d.ts",