@kortexya/reasoninglayer 1.23.0 → 1.24.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.24.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.
    *
@@ -14306,6 +14341,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 +14857,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.
    *