@kortexya/reasoninglayer 4.1.0 → 4.2.0

package/README.md

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

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "4.1.0";
+var SDK_VERSION = "4.2.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -11007,7 +11007,7 @@ var Ui = class {
     ...params
   });
   /**
-   * @description Events: - `layout_ready` — LayoutSurface JSON - `component_ready` — {slot_id, descriptor} JSON - `data_chunk` — {slot_id, data} JSON (if data was loaded) - `complete` — {} POST /api/v1/ui/describe/stream
+   * @description Events: - `layout_ready` — LayoutSurface JSON - `component_ready` — {slot_id, descriptor} JSON - `data_chunk` — {slot_id, data} JSON (if data was loaded) - `data_load_error` — {slot_id, error} JSON (if the data load failed; the error carries the typed `code`, `message` and `query`, #475) - `complete` — {} POST /api/v1/ui/describe/stream
    *
    * @tags ui
    * @name DescribeUiStream
@@ -17786,6 +17786,7 @@ var RESPONSE_COMPONENTS = {
       injection: [2, "InjectionSummaryDto"],
       intent: [1, 0],
       matched_templates: [2, { array: "QueryTemplateDto" }],
+      notices: [1, { array: 0 }],
       produced_term_ids: [1, { array: 0 }],
       prompt_trace: [2, "PromptTraceDto"],
       proof_trace: [2, "ProofTraceNodeDto"],
@@ -17969,6 +17970,7 @@ var RESPONSE_COMPONENTS = {
       explanation: [1, 0]
     }
   },
+  DataLoadErrorDto: { object: { code: [1, 0], message: [1, 0], query: [1, 0] } },
   DataMixingStatsDto: {
     object: {
       negative_count: [1, 0],
@@ -18438,6 +18440,7 @@ var RESPONSE_COMPONENTS = {
       chunks_processed: [1, 0],
       document_id: [1, 0],
       entities_extracted: [1, 0],
+      entities_refused: [1, { array: "RefusedEntityDto" }],
       processing_time_ms: [1, 0],
       relations_extracted: [1, 0],
       relations_integrated: [1, 0],
@@ -21269,9 +21272,11 @@ var RESPONSE_COMPONENTS = {
     }
   },
   PromptTraceDto: { object: { llm_context: [1, "LlmContextTraceDto"], system_prompt: [1, 0] } },
+  ProofConclusionDto: { object: { features: [1, { object: {} }], sort_id: [1, 0] } },
   ProofDto: {
     object: {
       certainty: [1, 0],
+      conclusion: [0, "ProofConclusionDto"],
       kind: [1, 0],
       subproofs: [0, { array: "ProofDto" }],
       substitution: [1, "HomoiconicSubstitutionDto"]
@@ -22340,6 +22345,7 @@ var RESPONSE_COMPONENTS = {
   SolutionDto: {
     object: {
       certainty: [1, 0],
+      conclusion: [2, "ProofConclusionDto"],
       matched_sorts: [0, { array: 0 }],
       proof: [2, "ProofDto"],
       residuated_sorts: [0, { array: 0 }],
@@ -23062,6 +23068,7 @@ var RESPONSE_COMPONENTS = {
   UIAssemblyStatsDto: {
     object: {
       component_count: [1, 0],
+      data_load_error: [2, "DataLoadErrorDto"],
       included_features: [1, 0],
       sort_name: [1, 0],
       total_features: [1, 0],
@@ -23100,6 +23107,7 @@ var RESPONSE_COMPONENTS = {
   UIGenerateResponse: {
     object: {
       data: [2, "DataPayloadDto"],
+      data_load_errors: [0, { array: "DataLoadErrorDto" }],
       data_sources: [0, { array: "DataSourcePayloadDto" }],
       descriptor: [2, "UIDescriptorDto"],
       diagnostics: [0, { array: 0 }],
@@ -24788,6 +24796,11 @@ var RESPONSE_OPERATIONS = {
     path: "/api/v1/constraint-sessions/{session_id}",
     responses: { 200: "ConstraintSessionStatusResponse" }
   },
+  getConversation: {
+    method: "GET",
+    path: "/api/v1/conversation/{id}",
+    responses: { 200: "ConversationSummaryDto" }
+  },
   getConversationEntries: {
     method: "GET",
     path: "/api/v1/audit/entries/{conversation_id}",
@@ -29296,6 +29309,14 @@ function HomoiconicSubstitutionDtoFromApiToFront(dto) {
     bindings: dto.bindings.map(BindingDtoFromApiToFront)
   };
 }
+function ProofConclusionDtoFromApiToFront(dto) {
+  return {
+    features: featuresFromApiToFront(dto.features),
+    sortId: dto.sort_id,
+    sortName: dto.sort_name ?? void 0,
+    termId: dto.term_id ?? void 0
+  };
+}
 function ProofDtoFromApiToFront(dto) {
   return {
     kind: dto.kind,
@@ -29303,6 +29324,7 @@ function ProofDtoFromApiToFront(dto) {
     ruleTermId: dto.rule_term_id,
     ruleHeadTermId: dto.rule_head_term_id,
     goalDisplay: dto.goal_display,
+    conclusion: dto.conclusion ? ProofConclusionDtoFromApiToFront(dto.conclusion) : void 0,
     ruleLabel: dto.rule_label,
     substitution: HomoiconicSubstitutionDtoFromApiToFront(dto.substitution),
     subproofs: dto.subproofs?.map(ProofDtoFromApiToFront),
@@ -29356,6 +29378,7 @@ function SolutionDtoFromApiToFront(dto) {
   const solution = {
     substitution: HomoiconicSubstitutionDtoFromApiToFront(dto.substitution),
     proof: dto.proof ? ProofDtoFromApiToFront(dto.proof) : void 0,
+    conclusion: dto.conclusion ? ProofConclusionDtoFromApiToFront(dto.conclusion) : void 0,
     certainty: dto.certainty,
     evidenceMatched: dto.evidence_matched ?? void 0,
     evidenceRatio: dto.evidence_ratio ?? void 0,
@@ -30056,6 +30079,8 @@ var InferenceClient = class {
    *   engine-side head aggregator (see {@link RuleAggregatorDto}).
    * @returns The created rule wrapped in an AddRuleResponse, with its
    *   {@link AddRuleResponse.etag} when the engine sends the `ETag` header.
+   * @throws {@link ValidationError} before the request is sent, when `antecedents` is
+   *   not an array (a request built from untyped data) — `field` is `antecedents`.
    * @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
@@ -30065,9 +30090,8 @@ var InferenceClient = class {
    *   cycle the program already had is not blamed on it), or a rule with no
    *   antecedents (`rule rejected: a rule needs at least one antecedent; a
    *   term with no antecedents is a fact — write it through POST
-   *   /api/v1/terms` — write a fact with `client.terms.createTerm`). A body
-   *   with no `antecedents` key at all is refused by the body decoder with a
-   *   plain-text 422. The refusal is a
+   *   /api/v1/terms` — write a fact with `client.terms.createTerm`). The
+   *   refusal is a
    *   plain {@link ApiError} with `status` 422 — not a `BadRequestError`
    *   (earlier engines answered an unknown head sort with 400), and not a
    *   `NamedConstraintViolationError`, which is reserved for a feature
@@ -30097,7 +30121,7 @@ var InferenceClient = class {
   async addRule(request, requestOptions) {
     const wireRequest = {
       term: convertTermArg(request.term),
-      antecedents: request.antecedents.map(convertTermArg),
+      antecedents: convertAntecedents(request.antecedents, "antecedents"),
       certainty: request.certainty,
       aggregator: request.aggregator
     };
@@ -30114,6 +30138,8 @@ var InferenceClient = class {
    * @returns Whether the write would accept it (`ok`), every refusal with the
    *   status the write would answer, the NAF-safety warnings, and the rule as
    *   the write would build it.
+   * @throws {@link ValidationError} before the request is sent, when `antecedents` is
+   *   not an array (a request built from untyped data) — `field` is `antecedents`.
    * @throws {ApiError} If the request itself fails.
    *
    * @remarks
@@ -30138,7 +30164,7 @@ var InferenceClient = class {
   async validateRule(request, requestOptions) {
     const wireRequest = {
       term: convertTermArg(request.term),
-      antecedents: request.antecedents.map(convertTermArg),
+      antecedents: convertAntecedents(request.antecedents, "antecedents"),
       certainty: request.certainty,
       aggregator: request.aggregator
     };
@@ -30183,10 +30209,11 @@ var InferenceClient = class {
    * @param requestOptions - Per-call request options.
    * @returns What was written, and what was refused: `ruleTermIds` and
    *   `rulesAdded` for the accepted rules, `rejected` naming each refused one.
-   * @throws {@link ApiError} 422 when the body is malformed (for example a row
-   *   with no `antecedents` key) — a 422 never means a refused row.
+   * @throws {@link ApiError} 422 when the body is malformed — a 422 never
+   *   means a refused row.
    * @throws {@link ValidationError} before the request is sent, when a rule's
-   *   term cannot be encoded — `field` names it as `rules[k].term` or
+   *   term cannot be encoded, or a row has no `antecedents` array — `field`
+   *   names it as `rules[k].term`, `rules[k].antecedents` or
    *   `rules[k].antecedents[i]`.
    *
    * @remarks
@@ -30201,7 +30228,8 @@ var InferenceClient = class {
    * number submitted. A row with an empty `antecedents` list is refused per
    * row this way (`rule rejected: a rule needs at least one antecedent; …`)
    * and is not counted in `rulesAdded` or `ruleTermIds`; a row with no
-   * `antecedents` key fails the whole batch with a 422. A rule that closes a
+   * `antecedents` array is refused before the request is sent, with a
+   * `ValidationError` whose `field` is `rules[k].antecedents`. A rule that closes a
    * NEW cycle through negation is refused the same way (the reason names the
    * cycle's sorts), decided for every row before any row is written.
    *
@@ -30215,9 +30243,9 @@ var InferenceClient = class {
    */
   async bulkAddRules(request, requestOptions) {
     const wireRequest = {
-      rules: request.rules.map((r) => ({
+      rules: request.rules.map((r, k) => ({
         term: convertTermArg(r.term),
-        antecedents: r.antecedents.map(convertTermArg),
+        antecedents: convertAntecedents(r.antecedents, `rules[${k}].antecedents`),
         certainty: r.certainty,
         aggregator: r.aggregator
       }))
@@ -30403,7 +30431,8 @@ var InferenceClient = class {
    * @throws {@link PreconditionRequiredError} 428 when `ifMatch` is omitted
    *   and the engine runs with `OSFKB_REQUIRE_IF_MATCH=1`.
    * @throws {@link ValidationError} before the request is sent, when a term
-   *   cannot be encoded — `field` names it (`term`, `antecedents[i]`).
+   *   cannot be encoded, or `antecedents` is not an array — `field` names it
+   *   (`term`, `antecedents`, `antecedents[i]`).
    *
    * @remarks
    * A rule's id IS its conclusion term id, so an edit changes it by
@@ -30442,7 +30471,7 @@ var InferenceClient = class {
   async replaceRule(ruleId, request, requestOptions) {
     const wireRequest = {
       term: convertTermArg(request.term),
-      antecedents: request.antecedents.map(convertTermArg),
+      antecedents: convertAntecedents(request.antecedents, "antecedents"),
       certainty: request.certainty,
       aggregator: request.aggregator
     };
@@ -30952,6 +30981,12 @@ var InferenceClient = class {
 function convertTermArg(input) {
   return isPsiTermInput(input) ? toTermInputDto(input) : input;
 }
+function convertAntecedents(antecedents, field) {
+  if (!Array.isArray(antecedents)) {
+    throw new ValidationError(`${field} must be an array of terms`, field);
+  }
+  return antecedents.map(convertTermArg);
+}
 function withRuleEtag(body, headers) {
   const etag = headers.get("etag");
   return etag === null ? body : { ...body, etag };
@@ -37240,6 +37275,7 @@ function DocumentReceiptFromApiToFront(dto) {
 function SessionDocumentFromApiToFront(dto) {
   const out = { documentId: dto.document_id, status: dto.status };
   if (dto.error != null) out.error = dto.error;
+  if (dto.error_code != null) out.errorCode = dto.error_code;
   if (dto.receipt != null) out.receipt = DocumentReceiptFromApiToFront(dto.receipt);
   return out;
 }
@@ -37353,6 +37389,7 @@ function DocumentStatsDtoFromApiToFront(dto) {
     documentId: dto.document_id,
     documentTermId: dto.document_term_id ?? void 0,
     entitiesExtracted: dto.entities_extracted,
+    entitiesRefused: dto.entities_refused.map(RefusedEntityDtoFromApiToFront),
     processingTimeMs: dto.processing_time_ms,
     relationsExtracted: dto.relations_extracted,
     relationsIntegrated: dto.relations_integrated,
@@ -51202,10 +51239,14 @@ function LayoutSurfaceDtoFromApiToFront(dto) {
     slots: dto.slots
   };
 }
+function DataLoadErrorFromApiToFront(dto) {
+  return { code: dto.code, message: dto.message, query: dto.query };
+}
 function UIAssemblyStatsDtoFromApiToFront(dto) {
   return {
     componentCount: dto.component_count,
     dataRows: dto.data_rows ?? void 0,
+    dataLoadError: dto.data_load_error ? DataLoadErrorFromApiToFront(dto.data_load_error) : void 0,
     includedFeatures: dto.included_features,
     osfqlExecuted: dto.osfql_executed ?? void 0,
     sortName: dto.sort_name,
@@ -51354,6 +51395,9 @@ function UIGenerateResponseFromApiToFront(dto) {
   if (dto.data_sources !== void 0) {
     result.dataSources = dto.data_sources.map(UIDataSourcePayloadFromApiToFront);
   }
+  if (dto.data_load_errors !== void 0) {
+    result.dataLoadErrors = dto.data_load_errors.map(DataLoadErrorFromApiToFront);
+  }
   if (dto.intents !== void 0) result.intents = dto.intents.map(UIGenerateIntentFromApiToFront);
   if (dto.trace != null) result.trace = dto.trace.map(UIPipelineStageTraceFromApiToFront);
   return result;
@@ -51601,6 +51645,34 @@ function ReasoningTraceDtoFromApiToFront(dto) {
     llmCalls: dto.llm_calls
   };
 }
+function ConversationNoticeFromApiToFront(dto) {
+  switch (dto.kind) {
+    case "pruned_features":
+      return {
+        kind: dto.kind,
+        message: dto.message,
+        skipped: dto.skipped.map((s) => ({ feature: s.feature, sort: s.sort }))
+      };
+    case "value_grounding":
+      return {
+        kind: dto.kind,
+        message: dto.message,
+        substitutions: dto.substitutions.map((s) => ({
+          feature: s.feature,
+          from: s.from,
+          sort: s.sort,
+          to: s.to
+        }))
+      };
+    case "retrieval_rescue":
+      return {
+        kind: dto.kind,
+        message: dto.message,
+        recordCount: dto.record_count,
+        sorts: [...dto.sorts]
+      };
+  }
+}
 function ConversationMessageResponseFromApiToFront(dto) {
   return {
     assistantMessage: dto.assistant_message,
@@ -51614,6 +51686,7 @@ function ConversationMessageResponseFromApiToFront(dto) {
     producedTermIds: dto.produced_term_ids,
     uiSortId: dto.ui_sort_id ?? void 0,
     suggestions: dto.suggestions,
+    notices: dto.notices.map(ConversationNoticeFromApiToFront),
     claimAnnotations: dto.claim_annotations?.map(ClaimAnnotationDtoFromApiToFront) ?? void 0,
     proofTrace: dto.proof_trace ? ProofTraceNodeDtoFromApiToFront(dto.proof_trace) : void 0,
     uiCustomizations: dto.ui_customizations?.map(UICustomizationDtoFromApiToFront) ?? void 0,
@@ -51636,7 +51709,7 @@ function isJsonObject2(value) {
 }
 function isConversationMessageResponseDto(value) {
   if (!isJsonObject2(value)) return false;
-  return typeof Reflect.get(value, "assistant_message") === "string" && typeof Reflect.get(value, "conversation_id") === "string" && typeof Reflect.get(value, "intent") === "string" && typeof Reflect.get(value, "turn_id") === "string" && Array.isArray(Reflect.get(value, "produced_term_ids")) && Array.isArray(Reflect.get(value, "suggestions"));
+  return typeof Reflect.get(value, "assistant_message") === "string" && typeof Reflect.get(value, "conversation_id") === "string" && typeof Reflect.get(value, "intent") === "string" && typeof Reflect.get(value, "turn_id") === "string" && Array.isArray(Reflect.get(value, "produced_term_ids")) && Array.isArray(Reflect.get(value, "suggestions")) && Array.isArray(Reflect.get(value, "notices"));
 }
 function decodeConversationMessage(payload) {
   return isConversationMessageResponseDto(payload) ? ConversationMessageResponseFromApiToFront(payload) : null;
@@ -51989,6 +52062,37 @@ var ConversationClient = class {
     });
     return decodeResponse(response, ListConversationsResponseFromApiToFront);
   }
+  /**
+   * Read one conversation's summary: the row {@link listConversations}
+   * returns for it.
+   *
+   * @param conversationId - The conversation ID.
+   * @param requestOptions - Per-call transport overrides.
+   * @returns The summary, with its `kind` and `title`.
+   * @throws {BadRequestError} `400` if the ID is malformed.
+   * @throws {NotFoundError} `404` if the conversation is not the caller's.
+   * @throws {ApiError} If the request fails.
+   *
+   * @remarks
+   * Uses GET `/api/v1/conversation/{id}`. A caller that resumes a conversation
+   * by ID learns its `kind` and `title` here without reading the whole listing.
+   *
+   * @example
+   * ```typescript
+   * const summary = await client.conversation.getConversation('conv-uuid');
+   * console.log(`${summary.kind}: ${summary.title ?? '(untitled)'}`);
+   * ```
+   */
+  async getConversation(conversationId, requestOptions) {
+    const response = await this.http.request({
+      ...toRequestParams(requestOptions),
+      path: `/api/v1/conversation/${encodeURIComponent(conversationId)}`,
+      method: "GET",
+      secure: true,
+      format: "json"
+    });
+    return decodeResponse(response, ConversationSummaryDtoFromApiToFront);
+  }
   /**
    * List the registered comparison models so the UI can populate a
    * selector / compare panel.
@@ -53536,10 +53640,12 @@ var UiClient = class {
    * keys inside them — `params`, `props_override`, a `component`'s `props`
    * (`dataKey`) and `initial_values` — reach the engine exactly as written.
    *
-   * The data load runs read-only OSFQL. A query that writes the store is
-   * refused without an exception: the answer's `stats.osfqlExecuted` starts
-   * with `FAILED:` (`FAILED: <query> — a data load runs read-only OSFQL, and this query writes the store; run it through POST /api/v1/ui/action or POST /api/v1/osfql`) and no rows load. Read a `FAILED:` value as a refused
-   * load, not as an empty result.
+   * The data load runs read-only OSFQL. A load that fails, including a query
+   * that writes the store, does not throw: the view renders without rows,
+   * `stats.dataLoadError` carries the typed `code`, the `message` and the
+   * `query`, and `stats.osfqlExecuted` is absent. Branch on `code`
+   * (`data_load_writes`, `osfql_parse_error`, `osfql_compile_error`,
+   * `osfql_execution_failed`), not on the message.
    *
    * A data view (table, graph, chart, map, timeline, matrix) names in
    * `props.rowKey` the column in which each loaded row carries its term's id.
@@ -53579,8 +53685,8 @@ var UiClient = class {
    *   `delete_record` template, is not a UUID; if a `"sort_ref"` field's sort
    *   declares no entity range; if `sortName` names no sort of the tenant or
    *   contains a backtick; if `values` names a feature the sort does not
-   *   declare; if an `update_form`'s term is held under another sort than
-   *   `sortName`; or if the request is malformed otherwise.
+   *   declare; if an `update_form` names a term the tenant does not hold, or a
+   *   term whose own sort `sortName` does not subsume; or if the request is malformed otherwise.
    * @throws {ApiError} If the request fails otherwise.
    *
    * @remarks
@@ -53650,8 +53756,8 @@ var UiClient = class {
    * endpoint abstains with live-schema suggestions. Data rows always come from OSFQL
    * execution after certification — never from the model. The data source runs
    * read-only OSFQL: a load query that writes the store is refused without an
-   * exception, and the load reports `FAILED: <query> — a data load runs read-only
-   * OSFQL, …` instead of rows.
+   * exception, and the failure is a `dataLoadErrors` entry (typed `code`,
+   * `message`, `query`) instead of rows.
    *
    * A certified single-pattern data query is bound to its rows' term ids: the
    * engine adds the identity binding to its root pattern (a note in
@@ -60799,8 +60905,9 @@ var AguiClient = class {
    *
    * A data load the run performs executes read-only OSFQL. A load query that
    * writes the store is refused without an exception or a `RUN_ERROR`: the
-   * load reports `FAILED: <query> — a data load runs read-only OSFQL, …` in
-   * place of rows.
+   * run emits a `CUSTOM` event named `osfkb.data_load_error` whose `value` is
+   * `{ code, message, query }`, and the `STATE_SNAPSHOT` carries the same
+   * object at `osfkb.dataLoadError`; branch on `code`. No rows are loaded.
    *
    * @example
    * ```typescript