@kortexya/reasoninglayer 4.0.0 → 4.1.0

package/README.md

@@ -316,7 +316,7 @@ pnpm run docs:build             # Build documentation site
 
 | SDK Version | Min Backend Version | Node | Browser |
 | ----------- | ------------------- | ---- | ------- |
-| 4.0.0       | engine `5cef4fa34`  | 20+  | ES2022+ |
+| 4.1.0       | engine `308ed2a25`  | 20+  | ES2022+ |
 
 ## License
 

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "4.0.0";
+var SDK_VERSION = "4.1.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -2532,7 +2532,7 @@ var Inference = class {
     ...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.
+   * @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 — the tag [`rule_content_tag`] publishes on the rule routes (#473) — and requires it under `OSFKB_REQUIRE_IF_MATCH=1`. Every request is captured by the audit middleware.
    *
    * @tags inference
    * @name DeleteRule
@@ -28616,10 +28616,11 @@ var TermsClient = class {
    * `etag` is optional in every case, not only for `asOf`. A historical read
    * carries none (a past state is not a representation `If-Match` can guard,
    * and a client that could capture one could overwrite the present with the
-   * past), and neither does a rule's conclusion or a term answered straight
-   * from durable storage. A rule's id is its conclusion term's id, so
-   * `getTerm(ruleId).etag` is the tag {@link InferenceClient.deleteRule} and
-   * {@link InferenceClient.replaceRule} take as `ifMatch`.
+   * past), and neither does a term answered straight from durable storage.
+   * A rule's id answers 404 here; read the tag
+   * {@link InferenceClient.deleteRule} and {@link InferenceClient.replaceRule}
+   * take as `ifMatch` from the rule routes ({@link AddRuleResponse.etag},
+   * {@link RuleEntryDto.etag}).
    *
    * @example
    * ```typescript
@@ -29601,6 +29602,7 @@ function RuleEntryDtoFromApiToFront(dto) {
   if (dto.aggregator !== void 0 && dto.aggregator !== null) {
     entry.aggregator = RuleAggregatorDtoFromApiToFront(dto.aggregator);
   }
+  if (dto.etag !== void 0 && dto.etag !== null) entry.etag = dto.etag;
   if (dto.osfql !== void 0 && dto.osfql !== null) entry.osfql = dto.osfql;
   return entry;
 }
@@ -30052,7 +30054,8 @@ var InferenceClient = class {
    *
    * @param request - Rule definition using TermInputDto. Set `aggregator` to declare an
    *   engine-side head aggregator (see {@link RuleAggregatorDto}).
-   * @returns The created rule wrapped in an AddRuleResponse.
+   * @returns The created rule wrapped in an AddRuleResponse, with its
+   *   {@link AddRuleResponse.etag} when the engine sends the `ETag` header.
    * @throws {ApiError} If the rule is rejected or the request fails — 422 when
    *   it is unusable as written: a head or body antecedent naming a sort or
    *   term that does not exist (the message names it and its position — `the
@@ -30075,6 +30078,9 @@ var InferenceClient = class {
    *
    * Ask {@link InferenceClient.validateRule} first to learn every reason the
    * write would refuse, without writing.
+   * The `ETag` response header is the rule's content tag, folded into
+   * `etag`: the `ifMatch` for {@link InferenceClient.deleteRule} and
+   * {@link InferenceClient.replaceRule}.
    * A `{ termId }` reference to a term that is durable but not yet loaded
    * into the engine process resolves: the route loads the terms the request
    * names before it converts them.
@@ -30099,7 +30105,7 @@ var InferenceClient = class {
       AddRuleRequestFromFrontToApi(wireRequest),
       toRequestParams(requestOptions)
     );
-    return decodeResponse(response, AddRuleResponseFromApiToFront);
+    return withRuleEtag(decodeResponse(response, AddRuleResponseFromApiToFront), response.headers);
   }
   /**
    * Run every check {@link InferenceClient.addRule} runs — without writing.
@@ -30321,8 +30327,8 @@ var InferenceClient = class {
    * @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'`); `ifMatch` is the ETag of the
-   *   rule's term, sent as the `If-Match` header.
+   *   rule derived (defaults to `'refuse'`); `ifMatch` is the rule's content
+   *   tag, sent as the `If-Match` header.
    * @param requestOptions - Per-call request options.
    * @returns What the withdrawal removed, tier by tier.
    * @throws {@link ApiError} 400 if the id names a fact rather than a rule, or
@@ -30351,14 +30357,16 @@ var InferenceClient = class {
    * conclusions are resident is refused too; `'retract'` removes them and
    * {@link RuleWithdrawalReport.consequencesInvalidated} counts them.
    *
-   * **Optimistic concurrency.** The rule routes send no ETag of their own.
-   * A rule's id is its conclusion term's id, so read the tag with
-   * `client.terms.getTerm(ruleId)` and pass its `etag` as `ifMatch`; a rule
-   * edited since answers 412.
+   * **Optimistic concurrency.** Read the rule's tag from
+   * {@link AddRuleResponse.etag}, {@link ReplaceRuleResponse.etag} or the
+   * listing's {@link RuleEntryDto.etag} ({@link InferenceClient.getRules}),
+   * and pass it as `ifMatch`; a rule edited since answers 412. The term route
+   * does not serve it: `client.terms.getTerm(ruleId)` answers 404 for a rule.
    *
    * @example
    * ```typescript
-   * const { etag } = await client.terms.getTerm(ruleId);
+   * const { rules } = await client.inference.getRules();
+   * const etag = rules.find((rule) => rule.ruleId === ruleId)?.etag;
    * const report = await client.inference.deleteRule(ruleId, {
    *   derivations: 'retract',
    *   ifMatch: etag,
@@ -30379,11 +30387,12 @@ var InferenceClient = class {
    *
    * @param ruleId - Term id of the rule (its conclusion) to replace.
    * @param request - The replacement rule, in the same shape
-   *   {@link InferenceClient.addRule} takes, plus `ifMatch`: the ETag of the
-   *   outgoing rule's term, sent as the `If-Match` header and never in the body.
+   *   {@link InferenceClient.addRule} takes, plus `ifMatch`: the content tag
+   *   of the outgoing rule, sent as the `If-Match` header and never in the body.
    * @param requestOptions - Per-call request options.
    * @returns The replacement, the id it replaced, what the withdrawal removed,
-   *   and how the rule base's guarantees moved.
+   *   and how the rule base's guarantees moved; `etag` is the replacement's
+   *   content tag when the engine sends the `ETag` header.
    * @throws {@link ApiError} 422 if the replacement is rejected by the
    *   authoring guards — in which case the original rule is left live. An
    *   empty `antecedents` list is one such refusal (`rule rejected: a rule
@@ -30406,16 +30415,23 @@ var InferenceClient = class {
    * addresses a single clause.
    *
    * `ifMatch` guards the edit exactly as it guards
-   * {@link InferenceClient.deleteRule}: read the tag with
-   * `client.terms.getTerm(ruleId)`.
+   * {@link InferenceClient.deleteRule}: read the tag from
+   * {@link AddRuleResponse.etag}, a previous {@link ReplaceRuleResponse.etag}
+   * or the listing's {@link RuleEntryDto.etag}. The response's own `etag` is
+   * the REPLACEMENT's tag, the `ifMatch` for the next edit.
    *
    * **Serialization format**: untagged `TermInputDto` / `FeatureInputValueDto`.
    *
    * @example
    * ```typescript
-   * const result = await client.inference.replaceRule(ruleId, {
+   * const created = await client.inference.addRule({
+   *   term: psi('senior', { name: Var('N') }),
+   *   antecedents: [psi('person', { name: Var('N') })],
+   * });
+   * const result = await client.inference.replaceRule(created.term.termId, {
    *   term: psi('retiree', { name: Var('N') }),
    *   antecedents: [psi('person', { name: Var('N') })],
+   *   ifMatch: created.etag,
    * });
    * console.log(result.previousRuleId, '->', result.term.termId);
    * if (result.certification.regressed) {
@@ -30435,7 +30451,10 @@ var InferenceClient = class {
       AddRuleRequestFromFrontToApi(wireRequest),
       ifMatchParams(request.ifMatch, requestOptions)
     );
-    return decodeResponse(response, ReplaceRuleResponseFromApiToFront);
+    return withRuleEtag(
+      decodeResponse(response, ReplaceRuleResponseFromApiToFront),
+      response.headers
+    );
   }
   /**
    * Query for matching data by searching rules and facts backwards from a goal pattern.
@@ -30933,6 +30952,10 @@ var InferenceClient = class {
 function convertTermArg(input) {
   return isPsiTermInput(input) ? toTermInputDto(input) : input;
 }
+function withRuleEtag(body, headers) {
+  const etag = headers.get("etag");
+  return etag === null ? body : { ...body, etag };
+}
 
 // src/normalizers/query.ts
 function TermPatternDtoFromFrontToApi(model) {
@@ -43048,8 +43071,8 @@ function MaterializeScenarioRequestFromFrontToApi(model) {
   return {
     // The prefix keys are data (`''`, `myOnt`), copied verbatim.
     prefixes: model.prefixes === void 0 ? void 0 : { ...model.prefixes },
-    // Accepted: the scenario is opaque user data sent verbatim (RAW_BODY_HEADER,
-    // #39); the engine validates its shape, so the SDK does not re-type it.
+    // The scenario is user data sent verbatim (RAW_BODY_HEADER, #39): every
+    // key reaches the engine under the spelling the caller wrote.
     scenario: model.scenario
   };
 }