@kortexya/reasoninglayer 1.2.1 → 1.4.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "1.2.1";
+var SDK_VERSION = "1.4.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -1064,6 +1064,20 @@ var Sorts = class {
     format: "json",
     ...params
   });
+  /**
+   * No description
+   *
+   * @tags sorts
+   * @name SearchSortsByName
+   * @request GET:/api/v1/sorts/search
+   */
+  searchSortsByName = (query, params = {}) => this.http.request({
+    path: `/api/v1/sorts/search`,
+    method: "GET",
+    query,
+    format: "json",
+    ...params
+  });
   /**
    * @description Similarity is symmetric: ∼(s₁, s₂) = ∼(s₂, s₁) Degree must be in [0, 1] range.
    *
@@ -1503,6 +1517,24 @@ var Inference = class {
     format: "json",
     ...params
   });
+  /**
+   * @description Phase 2 v2 entry point for retraction: 1. Removes each term from PG + in-memory stores via [`HomoiconicTermService::remove_term`](osfkb_application::services::HomoiconicTermService::remove_term). 2. When `state.use_plan_engine` is on, submits a single [`DeltaEvent::Retract`](osfkb_application::services::dataflow::DeltaEvent::Retract) to the per-tenant supervisor so the Backward/Forward backward chase decrements every dependent derived fact's `proof_count` (and deletes those whose count reaches zero). Symmetric to [`bulk_add_terms`]; idempotent (term ids absent from the working memory are silently skipped — same shape as [`delete_term`] returning 404, except in the bulk path the missing ids simply don't appear in `removed_term_ids`). Best-effort supervisor enqueue: a supervisor failure does NOT fail the 2xx response — the persist path has succeeded and a future bootstrap can recover any missed retraction. # Mid-batch error handling If `remove_term` fails for a term partway through the batch, the handler **stops accumulating successes**, runs cache invalidation for the prefix that did succeed, submits a single [`DeltaEvent::Retract`](osfkb_application::services::dataflow::DeltaEvent::Retract) covering that prefix, and **then** surfaces the error. This keeps the supervisor and the in-memory caches in sync with the actual store state — a leaked Retract event would orphan derived facts whose only antecedent is now removed, which is a critical correctness violation. # Authorization Requires `X-Tenant-Id` header. The `term_ids` are resolved against that tenant's working memory only — cross-tenant retraction is impossible by construction (the per-tenant `HomoiconicTermService` only sees its own tenant's terms).
+   *
+   * @tags inference
+   * @name BulkRetractTerms
+   * @summary Bulk-retract terms from the working memory.
+   * @request POST:/api/v1/inference/facts/bulk-retract
+   * @secure
+   */
+  bulkRetractTerms = (data, params = {}) => this.http.request({
+    path: `/api/v1/inference/facts/bulk-retract`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json" /* Json */,
+    format: "json",
+    ...params
+  });
   /**
    * @description # DEPRECATED This endpoint is deprecated. Use `DELETE /api/v1/terms/{term_id}` for individual terms. # TRUE HOMOICONIC API # Authorization Requires X-Tenant-Id header.
    *
@@ -7795,6 +7827,34 @@ var Admin = class {
     format: "json",
     ...params
   });
+  /**
+   * @description Truncates the derived_facts table for the given tenant and queues a BootstrapAll event covering every analyzed rule. Asynchronous: returns the queue depth and current materialization LSN, not the final state. Concurrent rebuilds for the same tenant are rejected with 409 (per-tenant mutex). Full operational runbook (prerequisites, timings, monitoring, failure recovery, known limitations) lives in .claude/SUB_MS_FORWARD_CHAINING_STATUS.md, section 'Operator runbook — derived-facts rebuild'.
+   *
+   * @tags admin
+   * @name RebuildDerivedFacts
+   * @summary Rebuild derived facts for a tenant
+   * @request POST:/api/v1/admin/derived-facts/rebuild/{tenant_id}
+   */
+  rebuildDerivedFacts = (tenantId, params = {}) => this.http.request({
+    path: `/api/v1/admin/derived-facts/rebuild/${tenantId}`,
+    method: "POST",
+    format: "json",
+    ...params
+  });
+  /**
+   * @description Returns event-processing counters (submitted/processed/failed/in-flight), the materialization LSN, the last handler error (if any, truncated to 512 chars), the per-tenant materialization sentinel, the current derived-facts row count, and a racy hint about whether a rebuild is in flight. Intended for operator dashboards; the supervisor itself does not depend on this endpoint.
+   *
+   * @tags admin
+   * @name SupervisorStatus
+   * @summary Get per-tenant supervisor + materialization status
+   * @request GET:/api/v1/admin/derived-facts/status/{tenant_id}
+   */
+  supervisorStatus = (tenantId, params = {}) => this.http.request({
+    path: `/api/v1/admin/derived-facts/status/${tenantId}`,
+    method: "GET",
+    format: "json",
+    ...params
+  });
 };
 
 // src/api-spec/generated/ImageExtraction.ts
@@ -9010,6 +9070,7 @@ var TAGGED_VALUE_TYPES = /* @__PURE__ */ new Set([
   "Boolean",
   "Uninstantiated",
   "Reference",
+  "SortId",
   "List",
   "FuzzyScalar",
   "FuzzyNumber",
@@ -9105,6 +9166,12 @@ function toUntaggedValue(value) {
     };
   }
   if (isTaggedValueDto(value)) {
+    if (value.type === "Reference") {
+      return { termId: value.value };
+    }
+    if (value.type === "SortId") {
+      return { sortRef: value.value };
+    }
     return value;
   }
   return value;
@@ -9517,6 +9584,9 @@ function FeatureInputValueDtoFromFrontToApi(value) {
       ...features ? { features } : {}
     };
   }
+  if ("sortRef" in value) {
+    return { sort_ref: value.sortRef };
+  }
   return { term_id: value.termId };
 }
 function featuresInputFromFrontToApi(features) {
@@ -20664,17 +20734,17 @@ function compileLinearExpression(expression, varRefs, nextVar) {
   const termResults = [];
   for (const [varName, coefficient] of Object.entries(expression)) {
     if (coefficient === 0) continue;
-    const varRef = varRefs[varName];
-    if (!varRef) continue;
+    const varRef2 = varRefs[varName];
+    if (!varRef2) continue;
     if (coefficient === 1) {
-      termResults.push(varRef);
+      termResults.push(varRef2);
     } else {
       const resultVar = { name: nextVar() };
       antecedents.push({
         sortName: "real_times_constraint",
         features: {
           coefficient: numericTerm(coefficient),
-          variable: varRef,
+          variable: varRef2,
           result: resultVar
         }
       });
@@ -20777,7 +20847,12 @@ var OptimizeClient = class {
         sorts: [{ name: solutionSortName, parents: ["thing"] }]
       });
       const sortIdsMap = sortResponse.data.sort_ids;
-      sortId = Object.values(sortIdsMap)[0];
+      sortId = sortIdsMap[solutionSortName];
+      if (!sortId) {
+        throw new Error(
+          `bulkCreateSorts did not return an id for '${solutionSortName}' (returned: ${Object.keys(sortIdsMap).join(", ")})`
+        );
+      }
       const ruleResponse = await this.inferenceApi.addRule({
         term: TermInputDtoFromFrontToApi(compiled.solutionTerm),
         antecedents: compiled.antecedents.map(TermInputDtoFromFrontToApi),
@@ -23156,6 +23231,26 @@ var Value = {
   reference(id) {
     return { type: "Reference", value: id };
   },
+  /**
+   * Create a reference to a sort by UUID.
+   *
+   * @param id - The UUID of the sort.
+   * @returns A tagged `SortIdValue`: `{"type": "SortId", "value": "uuid"}`.
+   *
+   * @remarks
+   * Used by homoiconic meta-constraints — primarily `Constraint.typeOf(...)`
+   * — whose feature targets a sort as a first-class value. The chainer
+   * dispatches this directly via `Value::SortId`.
+   *
+   * @example
+   * ```typescript
+   * Value.sortId("550e8400-e29b-41d4-a716-446655440000")
+   * // { type: 'SortId', value: '550e8400-e29b-41d4-a716-446655440000' }
+   * ```
+   */
+  sortId(id) {
+    return { type: "SortId", value: id };
+  },
   /**
    * Create a fuzzy scalar with a value and membership degree.
    *
@@ -23573,6 +23668,145 @@ var FuzzyShape = {
   }
 };
 
+// src/builders/psi.ts
+function psi(sortOrName, features) {
+  if (typeof sortOrName === "string") {
+    if (!features) {
+      return { __psiTerm: true, sortName: sortOrName };
+    }
+    return {
+      __psiTerm: true,
+      sortName: sortOrName,
+      features
+    };
+  }
+  if (!features) {
+    return { __psiTerm: true, sortId: sortOrName.sortId };
+  }
+  return {
+    __psiTerm: true,
+    sortId: sortOrName.sortId,
+    features
+  };
+}
+function constrained(name, constraint) {
+  return { __constrainedVar: true, name, constraint };
+}
+
+// src/builders/constraint.ts
+var ARITHMETIC_SORT = {
+  "+": "plus_constraint",
+  "-": "minus_constraint",
+  "*": "times_constraint",
+  "/": "div_constraint"
+};
+var Constraint = {
+  /**
+   * State that a variable is a term of a given sort. The chainer enumerates
+   * every persisted term of that sort via backtracking.
+   *
+   * @param variable - Variable name (e.g. `'?E'`) or pre-built variable Ψ-term.
+   * @param sortUuid - UUID of the target sort (resolve from
+   *   `client.inference.getMetaSorts()` or your own `createSort` response).
+   * @returns A `sort_constraint` term.
+   */
+  typeOf(variable, sortUuid) {
+    return psi("sort_constraint", {
+      var: variable,
+      sort: { sortRef: sortUuid }
+    });
+  },
+  /**
+   * State that a variable's feature equals a target. The chainer unifies
+   * the variable's feature value with the target.
+   *
+   * **Important**: the chainer's `feature_constraint` only unifies
+   * term-references with term-references. The variable's feature on the
+   * persisted side must itself be a `Value::Reference`. Comparing against
+   * literals (e.g. `has('?N', 'name', 'S')` where `name` is stored as a
+   * plain string) silently returns zero solutions — that's a chainer
+   * design constraint, not a builder bug.
+   *
+   * @param variable - The owning variable (e.g. `'?Edge'`).
+   * @param feature - The feature name (e.g. `'src'`).
+   * @param target - The target — typically another variable (`'?Src'`)
+   *   or an existing term referenced by its UUID via `'!<uuid>'`.
+   * @returns A `feature_constraint` term.
+   */
+  has(variable, feature, target) {
+    return psi("feature_constraint", {
+      var: variable,
+      feature,
+      target
+    });
+  },
+  /**
+   * State a boolean comparison between two operands. The chainer
+   * residuates the constraint until both sides are bound; when they are,
+   * the comparison must hold or the proof branch fails.
+   *
+   * @param left - Left operand — variable, literal number, or term ref.
+   * @param op - Comparison operator.
+   * @param right - Right operand.
+   * @returns A `guard_constraint` term.
+   */
+  where(left, op, right) {
+    return psi("guard_constraint", {
+      left,
+      operator: op,
+      right
+    });
+  },
+  /**
+   * State that `result = left op right`. Selects the chainer sort by op:
+   * `+` → `plus_constraint`, `-` → `minus_constraint`, `*` →
+   * `times_constraint`, `/` → `div_constraint`. The chainer reads each
+   * operand as either a Reference variable or a numeric literal, and can
+   * run forward, reverse, or verify depending on which operands are
+   * bound.
+   *
+   * @param result - Result variable or value (`z`).
+   * @param op - Arithmetic operator.
+   * @param left - Left operand (`x`).
+   * @param right - Right operand (`y`).
+   * @returns The appropriate arithmetic-constraint term.
+   */
+  equation(result, op, left, right) {
+    return psi(ARITHMETIC_SORT[op], { x: left, y: right, z: result });
+  },
+  /**
+   * Constrain a variable to be an integer in the inclusive range
+   * `[min, max]`. Required before the chainer's labeling step can assign
+   * a concrete value via {@link Constraint.solveFor}.
+   *
+   * @param variable - Variable name to constrain.
+   * @param min - Lower bound (inclusive).
+   * @param max - Upper bound (inclusive).
+   * @returns An `fd_domain_constraint` term.
+   */
+  intRange(variable, min, max) {
+    return psi("fd_domain_constraint", {
+      var: variable,
+      min,
+      max
+    });
+  },
+  /**
+   * Search for concrete integer assignments to the listed variables that
+   * satisfy every other constraint mentioning them. Place this at the END
+   * of a clause body — it's the labeling/search step that turns a
+   * constraint network into solutions.
+   *
+   * @param variables - Variable names to assign.
+   * @returns An `fd_labeling_constraint` term.
+   */
+  solveFor(...variables) {
+    return psi("fd_labeling_constraint", {
+      vars: variables
+    });
+  }
+};
+
 // src/builders/guard.ts
 function guard(op, right) {
   return {
@@ -23750,31 +23984,6 @@ var SortBuilder = class _SortBuilder {
   }
 };
 
-// src/builders/psi.ts
-function psi(sortOrName, features) {
-  if (typeof sortOrName === "string") {
-    if (!features) {
-      return { __psiTerm: true, sortName: sortOrName };
-    }
-    return {
-      __psiTerm: true,
-      sortName: sortOrName,
-      features
-    };
-  }
-  if (!features) {
-    return { __psiTerm: true, sortId: sortOrName.sortId };
-  }
-  return {
-    __psiTerm: true,
-    sortId: sortOrName.sortId,
-    features
-  };
-}
-function constrained(name, constraint) {
-  return { __constrainedVar: true, name, constraint };
-}
-
 // src/builders/allen.ts
 function allen(relation, intervalA, intervalBTermId) {
   return {
@@ -23785,6 +23994,229 @@ function allen(relation, intervalA, intervalBTermId) {
   };
 }
 
+// src/builders/flow.ts
+function nodeVar(name) {
+  const sanitized = name.replace(/[^A-Za-z0-9_]/g, "_");
+  return { name: `?N_${sanitized}` };
+}
+function varRef(name) {
+  return { name };
+}
+function freshVar(prefix, counter) {
+  const name = `?${prefix}${counter.n}`;
+  counter.n += 1;
+  return name;
+}
+function normaliseEdge(e) {
+  if (Array.isArray(e)) {
+    const [from, to, cap, options] = e;
+    return { from, to, cap, ...options ?? {} };
+  }
+  return e;
+}
+function buildEdges(edges, counter) {
+  const edgeTerms = [];
+  const edgeFlows = [];
+  for (const raw of edges) {
+    const e = normaliseEdge(raw);
+    const flowVar = e.flow ?? freshVar("F", counter);
+    edgeFlows.push({ from: e.from, to: e.to, var: flowVar });
+    const features = {
+      src: nodeVar(e.from),
+      dst: nodeVar(e.to),
+      cap: e.cap,
+      flow: varRef(flowVar)
+    };
+    if (e.cost != null) features.cost = e.cost;
+    if (e.label != null) features.label = e.label;
+    edgeTerms.push(psi("flow_edge_constraint", features));
+  }
+  return { edgeTerms, edgeFlows };
+}
+function solveTerm(source, sink) {
+  return psi("flow_solve_constraint", {
+    source: nodeVar(source),
+    sink: nodeVar(sink)
+  });
+}
+var Flow = {
+  /**
+   * Build a max-flow problem.
+   *
+   * Emits one `flow_edge_constraint` per edge, one
+   * `flow_max_constraint` with the requested output binding, and a
+   * `flow_solve_constraint` trigger. Returns the constraint terms
+   * plus the names of every output variable.
+   */
+  maxFlow(input) {
+    const counter = { n: 0 };
+    const { edgeTerms, edgeFlows } = buildEdges(input.edges, counter);
+    const flowValue = input.flowValue ?? freshVar("V_flow", counter);
+    const constraints = [
+      ...edgeTerms,
+      psi("flow_max_constraint", {
+        source: nodeVar(input.source),
+        sink: nodeVar(input.sink),
+        flow_value: varRef(flowValue)
+      }),
+      solveTerm(input.source, input.sink)
+    ];
+    return { constraints, vars: { flowValue, edgeFlows } };
+  },
+  /**
+   * Build a min-cut problem.
+   *
+   * Emits `flow_min_cut_constraint` and binds `cut_value`,
+   * `cut_edges`, `source_side`, `sink_side` to the requested
+   * variable names (auto-generated when omitted).
+   */
+  minCut(input) {
+    const counter = { n: 0 };
+    const { edgeTerms, edgeFlows } = buildEdges(input.edges, counter);
+    const cutValue = input.cutValue ?? freshVar("CutValue", counter);
+    const cutEdges = input.cutEdges ?? freshVar("CutEdges", counter);
+    const sourceSide = input.sourceSide ?? freshVar("SrcSide", counter);
+    const sinkSide = input.sinkSide ?? freshVar("SnkSide", counter);
+    const constraints = [
+      ...edgeTerms,
+      psi("flow_min_cut_constraint", {
+        source: nodeVar(input.source),
+        sink: nodeVar(input.sink),
+        cut_value: varRef(cutValue),
+        cut_edges: varRef(cutEdges),
+        source_side: varRef(sourceSide),
+        sink_side: varRef(sinkSide)
+      }),
+      solveTerm(input.source, input.sink)
+    ];
+    return {
+      constraints,
+      vars: { cutValue, cutEdges, sourceSide, sinkSide, edgeFlows }
+    };
+  },
+  /**
+   * Build a min-cost-max-flow problem. Per-edge `cost` is required
+   * for the optimisation to be meaningful (defaults to 0 if absent).
+   */
+  minCostMaxFlow(input) {
+    const counter = { n: 0 };
+    const { edgeTerms, edgeFlows } = buildEdges(input.edges, counter);
+    const flowValue = input.flowValue ?? freshVar("V_flow", counter);
+    const totalCost = input.totalCost ?? freshVar("Cost", counter);
+    const constraints = [
+      ...edgeTerms,
+      psi("flow_min_cost_max_flow_constraint", {
+        source: nodeVar(input.source),
+        sink: nodeVar(input.sink),
+        flow_value: varRef(flowValue),
+        total_cost: varRef(totalCost)
+      }),
+      solveTerm(input.source, input.sink)
+    ];
+    return { constraints, vars: { flowValue, totalCost, edgeFlows } };
+  },
+  /**
+   * Build a Dulmage-Mendelsohn edge-classification problem.
+   *
+   * Each edge is classified as `"always"`, `"never"`, or
+   * `"sometimes"` used across the space of all max flows (or all
+   * min-cost max flows when `optimal: true`).
+   */
+  classifyEdges(input) {
+    const counter = { n: 0 };
+    const { edgeTerms, edgeFlows } = buildEdges(input.edges, counter);
+    const classifications = input.classifications ?? freshVar("Classes", counter);
+    const objectiveFeatures = {
+      source: nodeVar(input.source),
+      sink: nodeVar(input.sink),
+      classifications: varRef(classifications)
+    };
+    if (input.optimal) objectiveFeatures.optimal = true;
+    const constraints = [
+      ...edgeTerms,
+      psi("flow_classify_edges_constraint", objectiveFeatures),
+      solveTerm(input.source, input.sink)
+    ];
+    return { constraints, vars: { classifications, edgeFlows } };
+  },
+  /** Low-level: build a single `flow_edge_constraint` psi-term. */
+  edge(from, to, cap, options = {}) {
+    const features = {
+      src: nodeVar(from),
+      dst: nodeVar(to),
+      cap
+    };
+    if (options.flow) features.flow = varRef(options.flow);
+    if (options.cost != null) features.cost = options.cost;
+    if (options.label != null) features.label = options.label;
+    return psi("flow_edge_constraint", features);
+  },
+  /** Low-level: build a single `flow_solve_constraint` psi-term. */
+  solve(source, sink) {
+    return solveTerm(source, sink);
+  },
+  /**
+   * Low-level: build a single `flow_max_constraint` psi-term.
+   *
+   * @example
+   * ```typescript
+   * const constraints = [
+   *   Flow.edge('s', 'a', 10),
+   *   Flow.edge('a', 't', 10),
+   *   Flow.maxObjective({ source: 's', sink: 't', flowValue: '?V' }),
+   *   Flow.solve('s', 't'),
+   * ];
+   * ```
+   */
+  maxObjective(opts) {
+    return psi("flow_max_constraint", {
+      source: nodeVar(opts.source),
+      sink: nodeVar(opts.sink),
+      flow_value: varRef(opts.flowValue)
+    });
+  },
+  /** Low-level: build a single `flow_min_cut_constraint` psi-term. */
+  minCutObjective(opts) {
+    return psi("flow_min_cut_constraint", {
+      source: nodeVar(opts.source),
+      sink: nodeVar(opts.sink),
+      cut_value: varRef(opts.cutValue),
+      cut_edges: varRef(opts.cutEdges),
+      source_side: varRef(opts.sourceSide),
+      sink_side: varRef(opts.sinkSide)
+    });
+  },
+  /** Low-level: build a single `flow_min_cost_max_flow_constraint` psi-term. */
+  minCostMaxFlowObjective(opts) {
+    return psi("flow_min_cost_max_flow_constraint", {
+      source: nodeVar(opts.source),
+      sink: nodeVar(opts.sink),
+      flow_value: varRef(opts.flowValue),
+      total_cost: varRef(opts.totalCost)
+    });
+  },
+  /** Low-level: build a single `flow_classify_edges_constraint` psi-term. */
+  classifyEdgesObjective(opts) {
+    const features = {
+      source: nodeVar(opts.source),
+      sink: nodeVar(opts.sink),
+      classifications: varRef(opts.classifications)
+    };
+    if (opts.optimal) features.optimal = true;
+    return psi("flow_classify_edges_constraint", features);
+  },
+  /**
+   * Low-level: get the node-variable reference used to identify a
+   * node name in goals built by this builder. Exposed so callers
+   * composing constraints by hand can refer to the same logical node
+   * the high-level helpers would produce — e.g., to add a feature
+   * test on the same node term inside the same goal.
+   */
+  node(name) {
+    return nodeVar(name);
+  }
+};
+
 // src/utils/discrimination.ts
 var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function isUuid(s) {
@@ -23824,6 +24256,7 @@ exports.Cognitive = cognitive_exports;
 exports.Collections = collections_exports;
 exports.Communities = communities_exports;
 exports.Compliance = compliance_exports;
+exports.Constraint = Constraint;
 exports.ConstraintViolationError = ConstraintViolationError;
 exports.Constraints = constraints_exports;
 exports.Control = control_exports;
@@ -23831,6 +24264,7 @@ exports.Conversation = conversation_exports;
 exports.Discovery = discovery_exports;
 exports.Execution = execution_exports;
 exports.Extract = extract_exports;
+exports.Flow = Flow;
 exports.FlowNetworks = flow_networks_exports;
 exports.ForbiddenError = ForbiddenError;
 exports.Functions = functions_exports;