@kortexya/reasoninglayer 1.2.0 → 1.3.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "1.2.0";
+var SDK_VERSION = "1.3.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
@@ -20664,17 +20724,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
         }
       });
@@ -23785,6 +23845,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) {
@@ -23831,6 +24114,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;