@kortexya/reasoninglayer 1.23.0 → 1.25.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "1.23.0";
+var SDK_VERSION = "1.25.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -1877,6 +1877,23 @@ var Inference = class {
     format: "json",
     ...params
   });
+  /**
+   * @description # The disposition is the caller's `?derivations=refuse` (the default) refuses while the rule still supports materialized conclusions and says how many; `?derivations=retract` withdraws them with it and reports the counts. A delete that silently drops derivations is as wrong as one that silently keeps them, so neither is the unnamed default. # Authorization Requires `X-Tenant-Id`. Runs the same delete guard as `DELETE /api/v1/terms/{id}` — a rule is a policy-relevant object, and withdrawing one changes what the engine will conclude. Honours `If-Match` against the conclusion's content ETag, and requires it under `OSFKB_REQUIRE_IF_MATCH=1`. Every request is captured by the audit middleware.
+   *
+   * @tags inference
+   * @name DeleteRule
+   * @summary Delete a rule.
+   * @request DELETE:/api/v1/inference/rules/{id}
+   * @secure
+   */
+  deleteRule = (id, query, params = {}) => this.http.request({
+    path: `/api/v1/inference/rules/${id}`,
+    method: "DELETE",
+    query,
+    secure: true,
+    format: "json",
+    ...params
+  });
   /**
    * @description Never writes to the KB — returns validated drafts for human review.
    *
@@ -1999,16 +2016,16 @@ var Inference = class {
     ...params
   });
   /**
-   * @description # Authorization Requires X-Tenant-Id header.
+   * @description # Authorization Requires X-Tenant-Id header, and the path tenant must equal it. # The path segment Named `{id}` because `DELETE` and `PUT` on the same path address ONE RULE by term id (#231), and one segment cannot carry two names. Here it is the tenant — and a redundant one, since any value but the authenticated principal is refused.
    *
    * @tags inference
    * @name GetRules
    * @summary Get all rules (clauses with antecedents) for a tenant
-   * @request GET:/api/v1/inference/rules/{tenant_id}
+   * @request GET:/api/v1/inference/rules/{id}
    * @secure
    */
-  getRules = (tenantId, params = {}) => this.http.request({
-    path: `/api/v1/inference/rules/${tenantId}`,
+  getRules = (id, params = {}) => this.http.request({
+    path: `/api/v1/inference/rules/${id}`,
     method: "GET",
     secure: true,
     format: "json",
@@ -2066,6 +2083,24 @@ var Inference = class {
     format: "json",
     ...params
   });
+  /**
+   * @description # An edit addresses ONE clause "Edit the rule for X" is ambiguous, because the authoring UI's "add clause" writes a *second* rule with the same conclusion, OR-unioned with the first. The path names a single rule term — one disjunct — so a client cannot silently edit the wrong one. # The old rule is withdrawn, not amended Everything `DELETE` does happens, always with the retract disposition: an edit that leaves the pre-edit clause's conclusions standing is exactly the defect this route exists to fix. The replacement is created through the same code `POST /api/v1/inference/rules` runs, so creation's guards — #227's guard canonicalisation, #219's range restriction, #217's certainty distinction — hold for an edit too, and a rejected replacement leaves the rule base untouched because the build runs BEFORE the clause is de-indexed. The response carries `previous_rule_id` alongside the new rule: a rule's id is its conclusion term id, so an edit changes it by construction. When the replacement is content-addressed to the same id (identical conclusion under `OSFKB_RULE_STABLE_IDS=1`), the two are equal and the edit was applied in place — the outgoing clause's now-unused antecedents are still collected and deleted. # Authorization Identical to `DELETE`: the delete guard on the outgoing rule, `If-Match` against its conclusion, and audit capture.
+   *
+   * @tags inference
+   * @name ReplaceRule
+   * @summary Replace a rule.
+   * @request PUT:/api/v1/inference/rules/{id}
+   * @secure
+   */
+  replaceRule = (id, data, params = {}) => this.http.request({
+    path: `/api/v1/inference/rules/${id}`,
+    method: "PUT",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
   /**
    * @description In OSF/LIFE terms, the orchestrator pushes the conclusion gate and each antecedent gate toward the dual-weighted satisfaction objective `1 − ( w_D · K_D + w_K · K_K )` (paper eq. 4). Each call performs exactly one epoch over the supplied batch — the response carries the per-epoch metrics for that single epoch (multi-epoch aggregation is the caller's responsibility). # Authorization Requires `X-Tenant-Id` header.
    *
@@ -8405,6 +8440,23 @@ var Functions = class {
   constructor(http) {
     this.http = http;
   }
+  /**
+   * @description # The disposition is the caller's `?callers=refuse` (the default) refuses while anything calls the function and names every caller; `?callers=orphan` withdraws it anyway and reports the callers left naming something that no longer resolves. A withdrawal that silently orphans its callers is the state the missing route already produced. # Authorization Requires `X-Tenant-Id`. The function store is tenant-keyed, so another tenant's function is `404` rather than forbidden. Every request is captured by the audit middleware.
+   *
+   * @tags functions
+   * @name DeleteFunction
+   * @summary Withdraw a registered function.
+   * @request DELETE:/api/v1/functions/{name}
+   * @secure
+   */
+  deleteFunction = (name, query, params = {}) => this.http.request({
+    path: `/api/v1/functions/${name}`,
+    method: "DELETE",
+    query,
+    secure: true,
+    format: "json",
+    ...params
+  });
   /**
    * @description Never writes to the KB — returns a validated draft for human review.
    *
@@ -8475,6 +8527,24 @@ var Functions = class {
     format: "json",
     ...params
   });
+  /**
+   * @description # Why this is not `POST /functions/register` Registration already replaces by name — silently, reporting nothing about what it displaced. `PUT` is the operation that says so: it refuses when nothing is registered under the name (that is registration's job), and answers with the previous signature, the new one, whether the arity moved, and everything that calls the function. # The arity is the hazard A function's identity is its NAME, so a replacement keeps every caller's reference valid — nothing dangles. That is exactly why an arity change is dangerous rather than merely breaking: every call still resolves, and one passing the old number of arguments starts failing at evaluation time. Reported, not refused: the caller may be replacing the function precisely because its signature was wrong. # Authorization Identical to `DELETE`: tenant-keyed, plugin-owned functions refused, audited.
+   *
+   * @tags functions
+   * @name ReplaceFunction
+   * @summary Replace a registered function's definition.
+   * @request PUT:/api/v1/functions/{name}
+   * @secure
+   */
+  replaceFunction = (name, data, params = {}) => this.http.request({
+    path: `/api/v1/functions/${name}`,
+    method: "PUT",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
 };
 
 // src/api-spec/generated/WebhookActions.ts
@@ -14297,7 +14367,13 @@ function RuleEntryDtoFromApiToFront(dto) {
     ruleId: dto.rule_id,
     head: PsiTermDtoFromApiToFront(dto.head),
     body: dto.body.map(PsiTermDtoFromApiToFront),
-    certainty: dto.certainty ?? void 0
+    certainty: dto.certainty ?? void 0,
+    origin: dto.origin,
+    withdrawable: dto.withdrawable,
+    notWithdrawable: dto.not_withdrawable ? {
+      code: dto.not_withdrawable.code,
+      reason: dto.not_withdrawable.reason
+    } : void 0
   };
 }
 function GetRulesResponseFromApiToFront(dto) {
@@ -14306,6 +14382,35 @@ function GetRulesResponseFromApiToFront(dto) {
     rules: dto.rules.map(RuleEntryDtoFromApiToFront)
   };
 }
+function RuleWithdrawalReportFromApiToFront(dto) {
+  return {
+    ruleId: dto.rule_id,
+    termsDeleted: dto.terms_deleted,
+    termsRetainedShared: dto.terms_retained_shared,
+    derivationsRemoved: dto.derivations_removed,
+    derivationsWeakened: dto.derivations_weakened,
+    derivationsTruncated: dto.derivations_truncated,
+    consequencesInvalidated: dto.consequences_invalidated,
+    queuedEventsCancelled: dto.queued_events_cancelled
+  };
+}
+function RuleCertificationDeltaFromApiToFront(dto) {
+  return {
+    terminatedBefore: dto.terminated_before,
+    terminatesAfter: dto.terminates_after,
+    orderIndependentBefore: dto.order_independent_before,
+    orderIndependentAfter: dto.order_independent_after,
+    regressed: dto.regressed
+  };
+}
+function ReplaceRuleResponseFromApiToFront(dto) {
+  return {
+    previousRuleId: dto.previous_rule_id,
+    term: PsiTermDtoFromApiToFront(dto.term),
+    withdrawal: RuleWithdrawalReportFromApiToFront(dto.withdrawal),
+    certification: RuleCertificationDeltaFromApiToFront(dto.certification)
+  };
+}
 function MetaSortsResponseFromApiToFront(dto) {
   return {
     absConstraint: dto.abs_constraint,
@@ -14793,6 +14898,89 @@ var InferenceClient = class {
     const response = await this.api.getRules(this.tenantId);
     return GetRulesResponseFromApiToFront(response.data);
   }
+  /**
+   * Withdraw one rule from the knowledge base.
+   *
+   * @param ruleId - Term id of the rule (its conclusion), as returned by
+   *   {@link InferenceClient.addRule} or {@link InferenceClient.getRules}.
+   * @param options - `derivations` decides what happens to the conclusions the
+   *   rule derived. Defaults to `'refuse'`.
+   * @returns What the withdrawal removed, tier by tier.
+   * @throws {ApiError} 400 if the id names a fact rather than a rule, or if the
+   *   rule still supports derivations under the default `'refuse'`; 403 for a
+   *   system, plugin-owned or bootstrap rule; 404 if no such rule exists.
+   *
+   * @remarks
+   * A rule is not a row. Withdrawing one deletes its conclusion AND the
+   * antecedent pattern, guard and variable terms it exclusively owns — a
+   * conclusion-only delete would leave those patterns readable as ordinary
+   * facts — while keeping every term the rest of the knowledge base still
+   * holds.
+   *
+   * `'refuse'` (the default) refuses while the rule still proves materialized
+   * conclusions and says how many; `'retract'` withdraws them with it. A delete
+   * that silently drops derivations is as wrong as one that silently keeps
+   * them, so neither is the unnamed default.
+   *
+   * @example
+   * ```typescript
+   * const report = await client.inference.deleteRule(ruleId, { derivations: 'retract' });
+   * console.log(report.termsDeleted, report.derivationsRemoved);
+   * ```
+   */
+  async deleteRule(ruleId, options) {
+    const response = await this.api.deleteRule(
+      ruleId,
+      options?.derivations === void 0 ? void 0 : { derivations: options.derivations }
+    );
+    return RuleWithdrawalReportFromApiToFront(response.data);
+  }
+  /**
+   * Replace one rule with a new one.
+   *
+   * @param ruleId - Term id of the rule (its conclusion) to replace.
+   * @param request - The replacement rule, in the same shape
+   *   {@link InferenceClient.addRule} takes.
+   * @returns The replacement, the id it replaced, what the withdrawal removed,
+   *   and how the rule base's guarantees moved.
+   * @throws {ApiError} 422 if the replacement is rejected by the authoring
+   *   guards — in which case the original rule is left live; 400/403/404 as for
+   *   {@link InferenceClient.deleteRule}.
+   *
+   * @remarks
+   * A rule's id IS its conclusion term id, so an edit changes it by
+   * construction. The response carries `previousRuleId` alongside the new
+   * rule; a client holding the old id must adopt the new one.
+   *
+   * The path names ONE rule term — one disjunct. Two rules with the same
+   * conclusion are OR-unioned, so "edit the rule for X" is ambiguous and this
+   * addresses a single clause.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.inference.replaceRule(ruleId, {
+   *   term: psi('retiree', { name: Var('N') }),
+   *   antecedents: [psi('person', { name: Var('N') })],
+   * });
+   * console.log(result.previousRuleId, '->', result.term.termId);
+   * if (result.certification.regressed) {
+   *   console.warn('the edit weakened the rule base guarantees');
+   * }
+   * ```
+   */
+  async replaceRule(ruleId, request) {
+    const wireRequest = {
+      term: convertTermArg(request.term),
+      antecedents: request.antecedents?.map(convertTermArg),
+      certainty: request.certainty,
+      aggregator: request.aggregator
+    };
+    const response = await this.api.replaceRule(
+      ruleId,
+      AddRuleRequestFromFrontToApi(wireRequest)
+    );
+    return ReplaceRuleResponseFromApiToFront(response.data);
+  }
   /**
    * Query for matching data by searching rules and facts backwards from a goal pattern.
    *
@@ -15084,7 +15272,8 @@ function FindBySortRequestFromFrontToApi(model) {
   return {
     sort_id: model.sortId ?? void 0,
     sort_name: model.sortName ?? void 0,
-    filter: model.filter ?? void 0
+    filter: model.filter ?? void 0,
+    limit: model.limit ?? void 0
   };
 }
 function OsfSearchRequestFromFrontToApi(model) {
@@ -17256,7 +17445,7 @@ var ConstraintsClient = class {
       type: "application/json",
       format: "json"
     });
-    return response.data;
+    return ConstraintGraphResponseFromApiToFront(response.data);
   }
   // --- Session Management ---
   /**
@@ -23331,9 +23520,11 @@ function StructuredIngestionStatsDtoFromApiToFront(dto) {
     elapsedMs: dto.elapsed_ms,
     entitiesCreated: dto.entities_created,
     entitiesExtracted: dto.entities_extracted,
+    recordsAvailable: dto.records_available,
     recordsProcessed: dto.records_processed,
     relationsCreated: dto.relations_created,
     relationsDiscovered: dto.relations_discovered,
+    rowsCollapsed: dto.rows_collapsed,
     sortsCreated: dto.sorts_created,
     tablesDiscovered: dto.tables_discovered,
     termsCreated: dto.terms_created,
@@ -26190,6 +26381,34 @@ function DraftFunctionResponseFromApiToFront(dto) {
     warnings: dto.warnings
   };
 }
+function FunctionCallerFromApiToFront(dto) {
+  return {
+    kind: dto.kind,
+    name: dto.name,
+    termId: dto.term_id ?? void 0
+  };
+}
+function FunctionWithdrawalReportFromApiToFront(dto) {
+  return {
+    name: dto.name,
+    functionId: dto.function_id,
+    carrierDeleted: dto.carrier_deleted,
+    deregistered: dto.deregistered,
+    // The wire omits the field when nothing was orphaned; the SDK always
+    // hands back an array, so a caller never has to guard the read.
+    callersOrphaned: (dto.callers_orphaned ?? []).map(FunctionCallerFromApiToFront)
+  };
+}
+function ReplaceFunctionResponseFromApiToFront(dto) {
+  return {
+    name: dto.name,
+    functionId: dto.function_id,
+    previous: FunctionSummaryDtoFromApiToFront(dto.previous),
+    current: FunctionSummaryDtoFromApiToFront(dto.current),
+    arityChanged: dto.arity_changed,
+    callers: (dto.callers ?? []).map(FunctionCallerFromApiToFront)
+  };
+}
 
 // src/resources/functions.ts
 var FunctionsClient = class {
@@ -26334,6 +26553,85 @@ var FunctionsClient = class {
     const response = await this.api.listFunctions();
     return ListFunctionsResponseFromApiToFront(response.data);
   }
+  /**
+   * Withdraw a registered function.
+   *
+   * @param name - The registered function's name — its identity.
+   * @param options - `callers` decides what happens to the things that call
+   *   it. Defaults to `'refuse'`.
+   * @returns What the withdrawal removed, in each representation that held it.
+   * @throws {ApiError} 400 if something still calls the function under the
+   *   default `'refuse'` (the body carries `code: 'function_has_callers'` and
+   *   the caller list); 403 for a plugin-contributed function; 404 if nothing
+   *   is registered under that name.
+   *
+   * @remarks
+   * A function is carried twice — the durable `meta.function` carrier that is
+   * the source of truth, and the evaluator's own registry used for dispatch
+   * and recursive cross-calls — and the report names both, because forgetting
+   * either leaves it half-alive: still evaluable, or back after a restart.
+   *
+   * `'refuse'` names every caller; `'orphan'` withdraws anyway and reports the
+   * callers left naming something that no longer resolves.
+   *
+   * @example
+   * ```typescript
+   * const report = await client.functions.deleteFunction('scale', { callers: 'orphan' });
+   * for (const orphan of report.callersOrphaned) {
+   *   console.warn(`${orphan.kind} ${orphan.name} now calls a function that is gone`);
+   * }
+   * ```
+   */
+  async deleteFunction(name, options) {
+    const response = await this.api.deleteFunction(
+      name,
+      options?.callers === void 0 ? void 0 : { callers: options.callers }
+    );
+    return FunctionWithdrawalReportFromApiToFront(response.data);
+  }
+  /**
+   * Replace a registered function's definition.
+   *
+   * @param name - The registered function's name. Unchanged by the
+   *   replacement — the name IS the identity.
+   * @param request - The replacement's arity and clauses.
+   * @returns Both signatures, whether the arity moved, and everything that
+   *   calls the function.
+   * @throws {ApiError} 400 if the replacement's clauses are rejected — in
+   *   which case the registration is left exactly as it was; 403 for a
+   *   plugin-contributed function; 404 if nothing is registered under that
+   *   name (creating one is {@link FunctionsClient.registerFunction}'s job).
+   *
+   * @remarks
+   * `registerFunction` already replaces by name — silently, reporting nothing
+   * about what it displaced. This is the operation that says so.
+   *
+   * A function's identity is its NAME, so a replacement keeps every caller's
+   * reference valid: nothing dangles. That is exactly why an arity change is
+   * the dangerous edit — every call still resolves, and one passing the old
+   * argument count starts failing at evaluation time. `arityChanged` is
+   * reported rather than refused, because a caller may be replacing the
+   * function precisely because its signature was wrong.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.functions.replaceFunction('scale', {
+   *   arity: 2,
+   *   clauses: [multiplyClause],
+   * });
+   * if (result.arityChanged) {
+   *   console.warn(`arity ${result.previous.arity} -> ${result.current.arity};`,
+   *     `${result.callers.length} caller(s) were written against the old one`);
+   * }
+   * ```
+   */
+  async replaceFunction(name, request) {
+    const response = await this.api.replaceFunction(name, {
+      arity: request.arity,
+      clauses: request.clauses.map(FunctionClauseDtoFromFrontToApi)
+    });
+    return ReplaceFunctionResponseFromApiToFront(response.data);
+  }
   /**
    * Draft a user-defined function from a natural-language description.
    *
@@ -27587,6 +27885,7 @@ function ClearTenantResponseFromApiToFront(dto) {
     sortsDeleted: dto.sorts_deleted,
     inferenceStateCleared: dto.inference_state_cleared,
     cacheInvalidated: dto.cache_invalidated,
+    vectorsDeleted: dto.vectors_deleted,
     pluginInstallsDeleted: dto.plugin_installs_deleted
   };
 }
@@ -32751,7 +33050,14 @@ function BindingSummaryDtoFromApiToFront(dto) {
     keyColumns: dto.key_columns,
     sortId: dto.sort_id,
     sourceId: dto.source_id,
-    tableName: dto.table_name
+    tableName: dto.table_name,
+    keyProvenance: {
+      source: dto.key_provenance.source,
+      chosenBy: dto.key_provenance.chosen_by,
+      explanation: dto.key_provenance.explanation,
+      guaranteedUnique: dto.key_provenance.guaranteed_unique,
+      durability: dto.key_provenance.durability
+    }
   };
 }
 function ListBindingsResponseFromApiToFront(dto) {