@almadar/std 16.234.0 → 16.236.0

package/dist/registry.d.ts

@@ -1,4 +1,5 @@
-import { S as StdOperatorMeta, a as StdModule, O as OperatorMeta, R as RunsOn } from './types-DwAW4Nni.js';
+import { S as StdOperatorMeta, a as StdModule, O as OperatorMeta, R as RunsOn, b as OperatorVisualForm } from './types-DLx38UFZ.js';
+export { c as OPERATOR_VISUAL_FORMS } from './types-DLx38UFZ.js';
 
 /**
  * Standard Library Registry
@@ -152,5 +153,7 @@ declare function getStdLibStats(): {
     effectOperators: number;
     lambdaOperators: number;
 };
+/** The AVL circuit form of an operator: its declared form, else conveyor (takes a lambda), actuator (side effect) or block. Null when unregistered. */
+declare function operatorVisualForm(operator: string): OperatorVisualForm | null;
 
-export { OPERATOR_NAMES, STD_OPERATORS, STD_OPERATORS_BY_MODULE, assertOperatorArity, getAllStdOperators, getLambdaOperators, getModuleOperators, getOperatorMetaExtended, getOperatorRunsOn, getOperatorsRunningOn, getStdEffectOperators, getStdLibStats, getStdOperatorMeta, getStdOperatorsByModule, getStdPureOperators, isEffectOperatorExtended, isKnownOperatorExtended, isKnownStdOperator, isStdEffectOperator, isStdGuardOperator, validateOperatorArityExtended, validateStdOperatorArity };
+export { OPERATOR_NAMES, OperatorVisualForm, STD_OPERATORS, STD_OPERATORS_BY_MODULE, assertOperatorArity, getAllStdOperators, getLambdaOperators, getModuleOperators, getOperatorMetaExtended, getOperatorRunsOn, getOperatorsRunningOn, getStdEffectOperators, getStdLibStats, getStdOperatorMeta, getStdOperatorsByModule, getStdPureOperators, isEffectOperatorExtended, isKnownOperatorExtended, isKnownStdOperator, isStdEffectOperator, isStdGuardOperator, operatorVisualForm, validateOperatorArityExtended, validateStdOperatorArity };

package/dist/registry.js

@@ -36,6 +36,19 @@ var STD_MODULES = [
   "behavior",
   "integration"
 ];
+var OPERATOR_VISUAL_FORMS = [
+  "block",
+  "series",
+  "parallel",
+  "invert",
+  "branch",
+  "scope",
+  "template",
+  "conveyor",
+  "ladder",
+  "actuator",
+  "delay"
+];
 function getModuleFromOperator(operator) {
   const parts = operator.split("/");
   if (parts.length !== 2) return null;
@@ -253,6 +266,7 @@ var CORE_OPERATORS = {
   },
   // --- logic ------------------------------------------------------------------
   and: {
+    visual: { form: "series" },
     module: "core",
     category: "logic",
     minArity: 2,
@@ -265,6 +279,7 @@ var CORE_OPERATORS = {
     example: '["and", ["=", "active", "active"], [">", 5, 0]]'
   },
   or: {
+    visual: { form: "parallel" },
     module: "core",
     category: "logic",
     minArity: 2,
@@ -277,6 +292,7 @@ var CORE_OPERATORS = {
     example: '["or", ["=", "admin", "user"], ["=", "admin", "owner"]]'
   },
   not: {
+    visual: { form: "invert" },
     module: "core",
     category: "logic",
     minArity: 1,
@@ -288,6 +304,7 @@ var CORE_OPERATORS = {
     example: '["not", false]'
   },
   if: {
+    visual: { form: "branch" },
     module: "core",
     category: "logic",
     minArity: 3,
@@ -305,6 +322,7 @@ var CORE_OPERATORS = {
   },
   // --- control ----------------------------------------------------------------
   let: {
+    visual: { form: "scope" },
     module: "core",
     category: "control",
     minArity: 2,
@@ -312,6 +330,7 @@ var CORE_OPERATORS = {
     description: "Bind local variables for a body expression",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "identity-of-arg<1>",
     params: [
       {
         name: "bindings",
@@ -323,6 +342,7 @@ var CORE_OPERATORS = {
     example: '["let", [["x", 10]], ["+", "x", 1]]'
   },
   do: {
+    visual: { form: "ladder" },
     module: "core",
     category: "control",
     minArity: 1,
@@ -330,6 +350,7 @@ var CORE_OPERATORS = {
     description: "Sequential execution of multiple effects/expressions",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "last-of-args",
     params: [{ name: "...exprs", type: SEXPR, description: "Effects/expressions to run in order" }],
     example: '["do", ["set", "@entity.x", 0], ["set", "@entity.y", 0]]'
   },
@@ -345,6 +366,7 @@ var CORE_OPERATORS = {
     example: '["list", "path", "method", "status"] // => ["path", "method", "status"]'
   },
   when: {
+    visual: { form: "branch" },
     module: "core",
     category: "control",
     minArity: 2,
@@ -359,6 +381,7 @@ var CORE_OPERATORS = {
     example: '["when", [">", "@entity.health", 0], ["emit", "ALIVE"]]'
   },
   fn: {
+    visual: { form: "template" },
     module: "core",
     category: "control",
     minArity: 2,
@@ -1671,6 +1694,7 @@ var ARRAY_OPERATORS = {
     description: "Extract subarray",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "start", type: "number", description: "Start index" },
@@ -1686,6 +1710,7 @@ var ARRAY_OPERATORS = {
     description: "Concatenate arrays",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "union-of-args",
     params: [{ name: "...arrs", type: "array[]", description: "Arrays to concatenate" }],
     example: '["array/concat", [1, 2], [3, 4]] // => [1, 2, 3, 4]'
   },
@@ -1697,6 +1722,7 @@ var ARRAY_OPERATORS = {
     description: "Add item to end (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "union-of-args<0,1>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "item", type: "any", description: "Item to add" }
@@ -1711,6 +1737,7 @@ var ARRAY_OPERATORS = {
     description: "Add item to start (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "union-of-args<0,1>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "item", type: "any", description: "Item to add" }
@@ -1725,6 +1752,7 @@ var ARRAY_OPERATORS = {
     description: "Insert item at index (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "union-of-args<0,2>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "index", type: "number", description: "Index to insert at" },
@@ -1740,6 +1768,7 @@ var ARRAY_OPERATORS = {
     description: "Remove item at index (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "index", type: "number", description: "Index to remove" }
@@ -1754,6 +1783,7 @@ var ARRAY_OPERATORS = {
     description: "Remove first matching item (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "item", type: "any", description: "Item to remove" }
@@ -1768,6 +1798,7 @@ var ARRAY_OPERATORS = {
     description: "Reverse array order (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [{ name: "arr", type: "array", description: "The array" }],
     example: '["array/reverse", [1, 2, 3]] // => [3, 2, 1]'
   },
@@ -1779,6 +1810,7 @@ var ARRAY_OPERATORS = {
     description: "Sort array (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "key", type: "string", description: "Field to sort by (for objects)", optional: true },
@@ -1794,6 +1826,7 @@ var ARRAY_OPERATORS = {
     description: "Randomly shuffle array (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [{ name: "arr", type: "array", description: "The array" }],
     example: '["array/shuffle", [1, 2, 3, 4, 5]]'
   },
@@ -1805,6 +1838,7 @@ var ARRAY_OPERATORS = {
     description: "Remove duplicates (returns new array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [{ name: "arr", type: "array", description: "The array" }],
     example: '["array/unique", [1, 2, 2, 3, 1]] // => [1, 2, 3]'
   },
@@ -2105,6 +2139,7 @@ var ARRAY_OPERATORS = {
     description: "Take first n elements",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "n", type: "number", description: "Number of elements" }
@@ -2119,6 +2154,7 @@ var ARRAY_OPERATORS = {
     description: "Skip first n elements",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "n", type: "number", description: "Number of elements to skip" }
@@ -2133,6 +2169,7 @@ var ARRAY_OPERATORS = {
     description: "Take last n elements",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "n", type: "number", description: "Number of elements" }
@@ -2147,6 +2184,7 @@ var ARRAY_OPERATORS = {
     description: "Skip last n elements",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "n", type: "number", description: "Number of elements to skip" }
@@ -3185,6 +3223,7 @@ var FORMAT_OPERATORS = {
 // modules/async.ts
 var ASYNC_OPERATORS = {
   "async/delay": {
+    visual: { form: "delay" },
     module: "async",
     category: "std-async",
     minArity: 1,
@@ -3200,6 +3239,7 @@ var ASYNC_OPERATORS = {
     example: '["async/delay", 2000, ["emit", "RETRY"]] // Wait 2s then emit'
   },
   "async/interval": {
+    visual: { form: "delay" },
     module: "async",
     category: "std-async",
     minArity: 2,
@@ -3215,6 +3255,7 @@ var ASYNC_OPERATORS = {
     example: '["async/interval", 5000, ["emit", "POLL_TICK"]] // Emit every 5s'
   },
   "async/timeout": {
+    visual: { form: "delay" },
     module: "async",
     category: "std-async",
     minArity: 2,
@@ -3230,6 +3271,7 @@ var ASYNC_OPERATORS = {
     example: '["async/timeout", ["call", "api", "fetchData"], 5000]'
   },
   "async/debounce": {
+    visual: { form: "delay" },
     module: "async",
     category: "std-async",
     minArity: 2,
@@ -3245,6 +3287,7 @@ var ASYNC_OPERATORS = {
     example: '["async/debounce", "SEARCH", 300]'
   },
   "async/throttle": {
+    visual: { form: "delay" },
     module: "async",
     category: "std-async",
     minArity: 2,
@@ -3260,6 +3303,7 @@ var ASYNC_OPERATORS = {
     example: '["async/throttle", "SCROLL", 100]'
   },
   "async/retry": {
+    visual: { form: "delay" },
     module: "async",
     category: "std-async",
     minArity: 2,
@@ -3277,6 +3321,7 @@ var ASYNC_OPERATORS = {
   { "attempts": 3, "backoff": "exponential", "baseDelay": 1000 }]`
   },
   "async/race": {
+    visual: { form: "parallel" },
     module: "async",
     category: "std-async",
     minArity: 2,
@@ -3289,6 +3334,7 @@ var ASYNC_OPERATORS = {
     example: '["async/race", ["call", "api1"], ["call", "api2"]]'
   },
   "async/all": {
+    visual: { form: "parallel" },
     module: "async",
     category: "std-async",
     minArity: 2,
@@ -3301,6 +3347,7 @@ var ASYNC_OPERATORS = {
     example: '["async/all", ["call", "api1"], ["call", "api2"]]'
   },
   "async/sequence": {
+    visual: { form: "ladder" },
     module: "async",
     category: "std-async",
     minArity: 2,
@@ -6729,5 +6776,12 @@ function getStdLibStats() {
     lambdaOperators: getLambdaOperators().length
   };
 }
+function operatorVisualForm(operator) {
+  const meta = getStdOperatorMeta(operator);
+  if (!meta) return null;
+  if (meta.visual) return meta.visual.form;
+  if (meta.acceptsLambda) return "conveyor";
+  return meta.hasSideEffects ? "actuator" : "block";
+}
 
-export { OPERATOR_NAMES, STD_OPERATORS, STD_OPERATORS_BY_MODULE, assertOperatorArity, getAllStdOperators, getLambdaOperators, getModuleOperators, getOperatorMetaExtended, getOperatorRunsOn, getOperatorsRunningOn, getStdEffectOperators, getStdLibStats, getStdOperatorMeta, getStdOperatorsByModule, getStdPureOperators, isEffectOperatorExtended, isKnownOperatorExtended, isKnownStdOperator, isStdEffectOperator, isStdGuardOperator, validateOperatorArityExtended, validateStdOperatorArity };
+export { OPERATOR_NAMES, OPERATOR_VISUAL_FORMS, STD_OPERATORS, STD_OPERATORS_BY_MODULE, assertOperatorArity, getAllStdOperators, getLambdaOperators, getModuleOperators, getOperatorMetaExtended, getOperatorRunsOn, getOperatorsRunningOn, getStdEffectOperators, getStdLibStats, getStdOperatorMeta, getStdOperatorsByModule, getStdPureOperators, isEffectOperatorExtended, isKnownOperatorExtended, isKnownStdOperator, isStdEffectOperator, isStdGuardOperator, operatorVisualForm, validateOperatorArityExtended, validateStdOperatorArity };

package/dist/{types-DwAW4Nni.d.ts → types-DLx38UFZ.d.ts}

@@ -44,14 +44,34 @@ type BasicReturnType = 'number' | 'boolean' | 'string' | 'any' | 'void' | 'array
  *   `ReturnTypeOf<lambda>` / type of `init`).
  * - `'object-key-lookup'` — return type depends on the input object
  *   shape and the literal key (`object/get`, `object/pick`).
- * - `'identity-of-arg<N>'` — return type matches the input arg at index N
- *   (`tap`, `pipe-through`).
+ * - `'identity-of-arg<N>'` — the result IS arg N, narrowed or reordered:
+ *   its type matches arg N's, and every value/element it can carry is drawn
+ *   from arg N (`array/filter`, `array/slice`, `array/sort`, `array/take`,
+ *   `array/unique`, …; `let` is `identity-of-arg<1>`, its body).
+ * - `'union-of-args'` — the result carries values drawn from EVERY arg
+ *   (`array/concat`). `'union-of-args<i,j>'` restricts that to the listed arg
+ *   indices: arg 0 is the list, the other listed index is the single element
+ *   the operator adds (`array/append`/`array/prepend` are `<0,1>`,
+ *   `array/insert` is `<0,2>`). A listed arg is either a list (contributes
+ *   its elements) or one element (contributes itself).
+ * - `'last-of-args'` — the result is the last arg's value (`do`).
+ *
+ * Provenance kinds (`identity-of-arg<N>`, `union-of-args[<..>]`,
+ * `last-of-args`, `branch-union`, `lambda-result`) are what the validator's
+ * one generic value-source walk reads (`orbital-core`
+ * `SExpression::value_leaves`) to trace which leaf values an expression can
+ * yield — e.g. which events a render-bound `itemActions` list can fire.
+ * `branch-union` = every arg after the condition; `lambda-result` = the body
+ * of the lambda arg (the arg whose operator declares `returnType:
+ * 'function'`). An operator whose result elements are NOT provably drawn from
+ * its inputs (`array/range`, `array/zip`, `array/groupBy`, `array/partition`,
+ * `array/flatten`) declares nothing and the walk treats it as opaque.
  *
  * Operators NOT listed here keep the fixed `returnType` semantics —
  * arithmetic, math, comparisons, aggregations (`array/sum`/`avg`/`len`),
  * type coercions, all effects.
  */
-type ReturnSemantics = 'first-truthy-of-args' | 'last-truthy-of-args' | 'first-non-null-of-args' | 'branch-union' | 'element-of-arg<0>' | 'element-of-arg<0>?' | 'element-of-arg<1>' | 'lambda-result' | 'object-key-lookup' | 'identity-of-arg<0>';
+type ReturnSemantics = 'first-truthy-of-args' | 'last-truthy-of-args' | 'first-non-null-of-args' | 'branch-union' | 'element-of-arg<0>' | 'element-of-arg<0>?' | 'element-of-arg<1>' | 'lambda-result' | 'object-key-lookup' | 'identity-of-arg<0>' | 'identity-of-arg<1>' | 'union-of-args' | 'union-of-args<0,1>' | 'union-of-args<0,2>' | 'last-of-args';
 /** Where an effect executes: a client host delegates `server` effects, a server ships `client` effects back, `any` runs wherever it is dispatched. */
 type RunsOn = 'client' | 'server' | 'any';
 interface OperatorMeta {
@@ -149,6 +169,9 @@ interface OperatorEffectMeta {
  * Extended operator metadata for std library operators.
  * Adds parameter descriptions and examples.
  */
+/** How an operator is drawn in the AVL circuit notation (evaluation as signal flow). */
+declare const OPERATOR_VISUAL_FORMS: readonly ["block", "series", "parallel", "invert", "branch", "scope", "template", "conveyor", "ladder", "actuator", "delay"];
+type OperatorVisualForm = (typeof OPERATOR_VISUAL_FORMS)[number];
 interface StdOperatorMeta extends OperatorMeta {
     /** The std module this operator belongs to */
     module: StdModule;
@@ -170,6 +193,10 @@ interface StdOperatorMeta extends OperatorMeta {
     compileTime?: boolean;
     /** Schema v2: structured metadata for effect operators */
     effect?: OperatorEffectMeta;
+    /** Circuit form, declared only where it is not derivable (lambda → conveyor, side effect → actuator, else block). */
+    visual?: {
+        form: OperatorVisualForm;
+    };
 }
 /**
  * Type guard to check if an operator category is a std category.
@@ -196,4 +223,4 @@ declare function isStdOperator(operator: string): boolean;
  */
 declare function makeStdOperator(module: StdModule, fn: string): string;
 
-export { type BasicReturnType as B, type OperatorMeta as O, type RunsOn as R, type StdOperatorMeta as S, type StdModule as a, OPERATOR_CATEGORIES as b, type OperatorCategory as c, type OperatorEffectMeta as d, type OperatorTypeRef as e, STD_MODULES as f, STD_OPERATOR_CATEGORIES as g, type StdOperatorCategory as h, getFunctionFromOperator as i, getModuleFromOperator as j, isStdCategory as k, isStdOperator as l, makeStdOperator as m };
+export { type BasicReturnType as B, type OperatorMeta as O, type RunsOn as R, type StdOperatorMeta as S, type StdModule as a, type OperatorVisualForm as b, OPERATOR_VISUAL_FORMS as c, OPERATOR_CATEGORIES as d, type OperatorCategory as e, type OperatorEffectMeta as f, type OperatorTypeRef as g, STD_MODULES as h, STD_OPERATOR_CATEGORIES as i, type StdOperatorCategory as j, getFunctionFromOperator as k, getModuleFromOperator as l, isStdCategory as m, isStdOperator as n, makeStdOperator as o };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/std",
-  "version": "16.234.0",
+  "version": "16.236.0",
   "description": "Standard library operators for Almadar (math, string, array, etc.)",
   "type": "module",
   "main": "./dist/index.js",
@@ -87,7 +87,7 @@
     "compiler": ">=4.10.0"
   },
   "dependencies": {
-    "@almadar/core": "^10.109.0"
+    "@almadar/core": "^10.112.0"
   },
   "devDependencies": {
     "@almadar/eslint-plugin": "^2.20.0",