skynet-graph 1.2.0

package/lib/graph/expr.js

@@ -0,0 +1,307 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * Safe expression evaluator for the concept mini-DSL — replaces the pervasive
+ * `new Function(...)` usage (Concept asserts/ensure, Graph.queryMaps /
+ * getChildMatching, Entity.doEval / test, PathMap queries).
+ *
+ * Why: `new Function` is an `eval` variant — RCE surface (LLM/host text flows
+ * into expressions), CSP-incompatible, and a hard blocker for WASM. This module
+ * parses the *full expression grammar* with `jsep` and interprets the AST with
+ * no code generation, so expressiveness is NOT capped: member access (./[]),
+ * method/function calls, ternary, array/object literals and every operator all
+ * work — only statement-level JS (loops/assignments) is out of reach, which
+ * `return (EXPR)` never meaningfully hosted anyway.
+ *
+ * Reference resolution preserves the engine's exact semantics: a `$ref` token
+ * (including cross-object walks like `$originNode:Position.lat` and the `$$id`
+ * bagRef/literal-id form) is captured *whole* by the original regex and handed
+ * verbatim to the injected resolver — i.e. to `getRef`, which walks the path.
+ * The regex rewrites `$ref` -> `__ref("ref")` (the same transformation the old
+ * code applied to `scope.getRef("ref")`), then jsep parses the rest.
+ *
+ * Security: because member access + calls are allowed, the classic
+ * `"".constructor.constructor("…")()` escape is blocked by refusing access to
+ * `constructor` / `__proto__` / `prototype`. No assert/query legitimately needs
+ * them, so this is not a cap on expressiveness — it is the whole point of
+ * dropping `eval`.
+ *
+ * Runtime errors yield `undefined`, faithful to the original
+ * `try{ … }catch{ return undefined }` wrapping.
+ *
+ * @author Skynet-Graph V1 (Neurosymbolic Reasoning Graph) — Phase 0
+ */
+
+var _jsep = require('jsep');
+var jsep = (_jsep && _jsep.default) ? _jsep.default : _jsep;
+
+var _ternary = require('@jsep-plugin/ternary');
+var _object = require('@jsep-plugin/object');
+jsep.plugins.register(
+	(_ternary && _ternary.default) ? _ternary.default : _ternary,
+	(_object && _object.default) ? _object.default : _object
+);
+
+// $ref / $$ref  ->  __ref("ref")   (identical capture to the original engine regex)
+var REF_RE = /\$(\$?[A-Za-z_][\w.:$]*)/g;
+var REF_FN = '__ref';
+
+// Properties that open a path back to the Function constructor / prototype chain.
+var BLOCKED_PROPS = { constructor: true, __proto__: true, prototype: true };
+
+// Stratified set-aggregation over a value array (roadmap #8) — closes the aggregation gap
+// (getRef walks SINGLE refs; only `.length` worked) WITHOUT lambdas, so it stays inside the
+// safe evaluator. `op`/`val` form a comparison predicate; omit them for a truthiness predicate.
+//   count($votes,'==','yes') >= 2     all($childScores,'>=',0.5)     any($flags)
+// "Stratified" = run it after the collection is complete (the existing cardinality gate,
+// e.g. `$votes.length==$expected && count($votes,'==','yes')>=k`), exactly like `.length`.
+function aggCompare( a, op, b ) {
+	switch ( op ) {
+		case '==':  return a == b;   case '!=':  return a != b;
+		case '===': return a === b;  case '!==': return a !== b;
+		case '<':   return a < b;    case '>':   return a > b;
+		case '<=':  return a <= b;   case '>=':  return a >= b;
+	}
+	return false;                                  // unknown op -> matches nothing
+}
+function aggPredicate( op, val ) {
+	return op === undefined ? function ( e ) { return !!e; } : function ( e ) { return aggCompare(e, op, val); };
+}
+function aggCount( arr, op, val ) {
+	if ( !Array.isArray(arr) ) return 0;
+	var p = aggPredicate(op, val), n = 0;
+	for ( var i = 0; i < arr.length; i++ ) if ( p(arr[i]) ) n++;
+	return n;
+}
+function aggAll( arr, op, val ) {                  // vacuously true on []; false on a non-array (not-yet-present)
+	if ( !Array.isArray(arr) ) return false;
+	var p = aggPredicate(op, val);
+	for ( var i = 0; i < arr.length; i++ ) if ( !p(arr[i]) ) return false;
+	return true;
+}
+function aggAny( arr, op, val ) {
+	if ( !Array.isArray(arr) ) return false;
+	var p = aggPredicate(op, val);
+	for ( var i = 0; i < arr.length; i++ ) if ( p(arr[i]) ) return true;
+	return false;
+}
+
+// Curated, side-effect-free globals reachable by bare identifiers. Deliberately
+// excludes Function/eval/require/process/globalThis etc. (absent -> undefined).
+var GLOBALS = {
+	Math: Math, JSON: JSON,
+	Number: Number, String: String, Boolean: Boolean, Array: Array,
+	parseInt: parseInt, parseFloat: parseFloat,
+	isNaN: isNaN, isFinite: isFinite,
+	count: aggCount, all: aggAll, any: aggAny,   // stratified set-aggregation (#8)
+	undefined: undefined, NaN: NaN, Infinity: Infinity
+};
+
+function hasOwn( o, k ) { return o != null && Object.prototype.hasOwnProperty.call(o, k); }
+
+function safeProp( name ) {
+	if ( BLOCKED_PROPS[name] ) throw new Error('expr: access to "' + name + '" is blocked');
+	return name;
+}
+
+// ----------------------------------------------------------- interpreter
+function evalNode( node, ctx ) {
+	switch ( node.type ) {
+		case 'Literal':
+			return node.value;
+
+		case 'Identifier': {
+			var nm = node.name;
+			if ( hasOwn(ctx.names, nm) ) return ctx.names[nm];
+			if ( hasOwn(GLOBALS, nm) ) return GLOBALS[nm];
+			return undefined;
+		}
+
+		case 'MemberExpression': {
+			var obj = evalNode(node.object, ctx);
+			if ( obj == null ) return undefined;
+			var key = node.computed ? evalNode(node.property, ctx) : node.property.name;
+			return obj[safeProp(key)];
+		}
+
+		case 'CallExpression': {
+			var callee = node.callee;
+
+			// `$ref` marker: callee is the injected __ref(<string literal>)
+			if ( callee.type === 'Identifier' && callee.name === REF_FN ) {
+				return ctx.resolve(node.arguments[0].value);
+			}
+
+			var thisObj, fn;
+			if ( callee.type === 'MemberExpression' ) {
+				thisObj = evalNode(callee.object, ctx);
+				if ( thisObj == null ) return undefined;
+				var mkey = callee.computed ? evalNode(callee.property, ctx) : callee.property.name;
+				fn = thisObj[safeProp(mkey)];
+			} else {
+				thisObj = undefined;
+				fn = evalNode(callee, ctx);
+			}
+			if ( typeof fn !== 'function' ) return undefined;
+			return fn.apply(thisObj, node.arguments.map(function ( a ) { return evalNode(a, ctx); }));
+		}
+
+		case 'BinaryExpression':
+		case 'LogicalExpression':
+			return evalBinary(node, ctx);
+
+		case 'UnaryExpression': {
+			var v = evalNode(node.argument, ctx);
+			switch ( node.operator ) {
+				case '!': return !v;
+				case '-': return -v;
+				case '+': return +v;
+				case '~': return ~v;
+				case 'typeof': return typeof v;
+			}
+			throw new Error('expr: unsupported unary "' + node.operator + '"');
+		}
+
+		case 'ConditionalExpression':
+			return evalNode(node.test, ctx)
+				? evalNode(node.consequent, ctx)
+				: evalNode(node.alternate, ctx);
+
+		case 'ArrayExpression':
+			return node.elements.map(function ( e ) { return evalNode(e, ctx); });
+
+		case 'ObjectExpression': {
+			var o = {};
+			node.properties.forEach(function ( pr ) {
+				var k = pr.computed ? evalNode(pr.key, ctx)
+					: (pr.key.name != null ? pr.key.name : pr.key.value);
+				o[safeProp(String(k))] = evalNode(pr.value, ctx);
+			});
+			return o;
+		}
+
+		case 'Compound': {
+			var last;
+			node.body.forEach(function ( n ) { last = evalNode(n, ctx); });
+			return last;
+		}
+
+		case 'ThisExpression':
+			return undefined;
+	}
+	throw new Error('expr: unsupported node "' + node.type + '"');
+}
+
+function evalBinary( node, ctx ) {
+	var op = node.operator;
+	// logical operators short-circuit and return the operand (like JS / the
+	// original `return (expr)`)
+	if ( op === '&&' ) return evalNode(node.left, ctx) && evalNode(node.right, ctx);
+	if ( op === '||' ) return evalNode(node.left, ctx) || evalNode(node.right, ctx);
+
+	var l = evalNode(node.left, ctx), r = evalNode(node.right, ctx);
+	switch ( op ) {
+		case '==':  return l == r;   // loose, matching original DSL semantics
+		case '!=':  return l != r;
+		case '===': return l === r;
+		case '!==': return l !== r;
+		case '<':   return l < r;
+		case '>':   return l > r;
+		case '<=':  return l <= r;
+		case '>=':  return l >= r;
+		case '+':   return l + r;
+		case '-':   return l - r;
+		case '*':   return l * r;
+		case '/':   return l / r;
+		case '%':   return l % r;
+		case '**':  return Math.pow(l, r);
+		case '&':   return l & r;
+		case '|':   return l | r;
+		case '^':   return l ^ r;
+		case '<<':  return l << r;
+		case '>>':  return l >> r;
+		case '>>>': return l >>> r;
+	}
+	throw new Error('expr: unsupported binary "' + op + '"');
+}
+
+// -------------------------------------------------------------- public API
+function preprocessRefs( src ) {
+	return src.replace(REF_RE, function ( _m, ref ) {
+		return REF_FN + '(' + JSON.stringify(ref) + ')';
+	});
+}
+
+// Join an array of sub-expressions with AND, mirroring the original
+// `query.join(") && (")` wrapped in `(...)`.
+function normalize( source ) {
+	if ( Array.isArray(source) ) {
+		var parts = source.filter(function ( s ) { return s != null && String(s).trim() !== ''; });
+		if ( !parts.length ) return '';
+		return '(' + parts.join(') && (') + ')';
+	}
+	return source == null ? '' : String(source);
+}
+
+/**
+ * Compile a mini-DSL expression into a safe evaluator.
+ *
+ * @param   {string|string[]} source   expression, or array AND-joined together
+ * @param   {{empty?: *}}    [options]  `empty` is returned for an empty source
+ *                                      (default `true`, matching Concept/queryMaps;
+ *                                      pass `false` for getChildMatching/test)
+ * @returns {function(resolve, names=): *}  `resolve(refName)` resolves `$ref`s,
+ *                                      `names` (optional) resolves bare identifiers
+ *                                      (stands in for doEval's `with(refMap)`).
+ *                                      Returns `undefined` on any runtime error.
+ * @throws  {Error} on syntax errors (faithful: `new Function` also threw at compile)
+ */
+function compileExpression( source, options ) {
+	var fallback = ( options && 'empty' in options ) ? options.empty : true;
+	var src = normalize(source).trim();
+
+	if ( !src ) {
+		return function () { return fallback; };
+	}
+
+	var ast = jsep(preprocessRefs(src));
+
+	return function ( resolve, names ) {
+		try {
+			return evalNode(ast, { resolve: resolve, names: names });
+		} catch ( e ) {
+			return undefined;
+		}
+	};
+}
+
+/**
+ * Parse a mini-DSL expression to its jsep AST (refs already rewritten to `__ref("ref")`
+ * CallExpression nodes — identify a ref node by `node.type==='CallExpression' &&
+ * node.callee.name===REF_FN`, its key is `node.arguments[0].value`). For author-time
+ * static analysis (validate.js); the evaluator path stays `compileExpression`.
+ * @returns the AST, or `null` for an empty source. Throws on a syntax error.
+ */
+function parseExpression( source ) {
+	var src = normalize(source).trim();
+	if ( !src ) return null;
+	return jsep(preprocessRefs(src));
+}
+
+module.exports = { compileExpression: compileExpression, parseExpression: parseExpression, REF_FN: REF_FN };

package/lib/graph/index.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+// `__SERVER__` is a host/build flag (true = node/server, false = browser/client) read as
+// a bare global by the engine. Default it to server when undefined so the lib loads
+// standalone without a ReferenceError; a browser host can set globalThis.__SERVER__ =
+// false before requiring the engine. (Previously injected by webpack DefinePlugin / _boot.)
+if ( typeof globalThis.__SERVER__ === 'undefined' ) globalThis.__SERVER__ = true;
+
+module.exports = require('./Graph.js');

package/lib/graph/log.js

@@ -0,0 +1,134 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * Skynet-Graph logger — fs-free core.
+ *
+ * Lives in the engine (lib/graph/) so every engine file can require it without
+ * pulling node:fs; all file/TTY sinks live in lib/sg/. This replaces the old
+ * `var debug = console` indirection: same console-compatible call shape, but now
+ * leveled, sinked, context-aware and per-graph.
+ *
+ * Levels (severity descending) — a record reaches sinks iff
+ *   rank(record.level) <= rank(threshold):
+ *     error(0) > warn(1) > log(2) > info(3) > verbose(4)
+ *
+ * A LogRecord { level, ts, label, ctx, msg, args } is JSON-serializable (Errors
+ * in args are reduced to {name,message,stack}), so it crosses a worker_threads
+ * boundary unchanged.
+ *
+ * child(ctx) returns a logger that shares the root's sinks / ring buffer / level
+ * but merges ctx into every record. A concept-apply tags its logs with
+ * { concept, target, applyId } this way, so they can be retrieved afterwards via
+ * tail(n,{concept|applyId}) WITHOUT ever being stored on the graph objects.
+ */
+
+var LEVELS      = { error: 0, warn: 1, log: 2, info: 3, verbose: 4 };
+var LEVEL_NAMES = ['error', 'warn', 'log', 'info', 'verbose'];
+
+function rankOf ( name ) { return LEVELS[name] == null ? LEVELS.info : LEVELS[name]; }
+
+// Reduce args to something JSON-serializable (Errors -> plain object, functions
+// -> tag), so a record survives structured-clone across a worker boundary.
+function sanitizeArgs ( args ) {
+	return args.map(function ( a ) {
+		if ( a instanceof Error ) return { name: a.name, message: a.message, stack: a.stack };
+		if ( typeof a === 'function' ) return '[function ' + (a.name || 'anonymous') + ']';
+		return a;
+	});
+}
+
+function recordMatches ( rec, f ) {
+	if ( !f ) return true;
+	var c = rec.ctx || {};
+	if ( f.level   != null && rec.level !== f.level )   return false;
+	if ( f.concept != null && c.concept !== f.concept ) return false;
+	if ( f.target  != null && c.target  !== f.target )  return false;
+	if ( f.applyId != null && c.applyId !== f.applyId ) return false;
+	return true;
+}
+
+// Default sink: format the record back into a console.<level>(...) call so the
+// out-of-the-box behavior matches the old `debug = console` — but level-gated.
+function consoleSink ( rec ) {
+	var fn   = console[rec.level] || console.log;
+	var head = '[' + rec.label + (rec.ctx && rec.ctx.concept ? '·' + rec.ctx.concept : '') + ']';
+	fn.apply(console, [head, rec.msg].concat(rec.args || []));
+}
+
+/**
+ * @param {object}   [opts]
+ * @param {string}   [opts.label='graph']
+ * @param {string}   [opts.level]        threshold; default env SG_LOG_LEVEL or 'warn'
+ * @param {function} [opts.onRecord]     convenience sink fn(record)
+ * @param {number}   [opts.capacity=500] ring-buffer size for tail()
+ * @param {boolean}  [opts.console=true] install the default console sink
+ * @returns {object} logger
+ */
+function createLogger ( opts ) {
+	opts = opts || {};
+	// shared mutable state — a child closes over the SAME state object as its root
+	var state = {
+		label: opts.label || 'graph',
+		level: opts.level || (typeof process !== 'undefined' && process.env.SG_LOG_LEVEL) || 'warn',
+		sinks: [],
+		buf  : [],
+		cap  : opts.capacity || 500
+	};
+	if ( opts.console !== false ) state.sinks.push(consoleSink);
+	if ( opts.onRecord )          state.sinks.push(opts.onRecord);
+
+	function make ( ctx ) {
+		var logger = {};
+
+		function emit ( level, msg, args ) {
+			if ( rankOf(level) > rankOf(state.level) ) return;       // below threshold -> drop
+			var rec = { level: level, ts: Date.now(), label: state.label, ctx: ctx, msg: msg, args: sanitizeArgs(args) };
+			state.buf.push(rec);
+			if ( state.buf.length > state.cap ) state.buf.shift();
+			for ( var i = 0 ; i < state.sinks.length ; i++ ) {
+				try { state.sinks[i](rec); } catch ( e ) { /* a broken sink must never break the engine */ }
+			}
+		}
+
+		LEVEL_NAMES.forEach(function ( lvl ) {
+			logger[lvl] = function ( msg ) { emit(lvl, msg, Array.prototype.slice.call(arguments, 1)); };
+		});
+
+		logger.child      = function ( extra ) { return make(Object.assign({}, ctx, extra)); };
+		logger.addSink    = function ( fn ) { state.sinks.push(fn); return fn; };
+		logger.removeSink = function ( fn ) { var i = state.sinks.indexOf(fn); if ( i >= 0 ) state.sinks.splice(i, 1); };
+		logger.setLevel   = function ( name ) { if ( LEVELS[name] != null ) state.level = name; return state.level; };
+		logger.tail       = function ( n, filter ) {
+			var out = filter ? state.buf.filter(function ( r ) { return recordMatches(r, filter); }) : state.buf.slice();
+			return n ? out.slice(-n) : out;
+		};
+		Object.defineProperty(logger, 'level',   { get: function () { return state.level; } });
+		Object.defineProperty(logger, 'records', { get: function () { return state.buf.slice(); } });
+		Object.defineProperty(logger, 'ctx',     { get: function () { return ctx; } });
+		Object.defineProperty(logger, 'label',   { get: function () { return state.label; } });
+		return logger;
+	}
+
+	return make(null);
+}
+
+// process-wide fallback for the rare engine spots with no graph in scope.
+var defaultLogger = createLogger({ label: 'sg' });
+
+module.exports = { createLogger: createLogger, defaultLogger: defaultLogger, LEVELS: LEVELS, LEVEL_NAMES: LEVEL_NAMES };