@kortexya/reasoninglayer 4.0.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.0.0       | engine `5cef4fa34`  | 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.0.0";
+var SDK_VERSION = "4.2.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
@@ -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}",
@@ -28616,10 +28629,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
@@ -29295,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,
@@ -29302,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),
@@ -29355,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,
@@ -29601,6 +29625,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 +30077,10 @@ 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 {@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
@@ -30062,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
@@ -30075,6 +30102,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.
@@ -30091,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
     };
@@ -30099,7 +30129,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.
@@ -30108,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
@@ -30132,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
     };
@@ -30177,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
@@ -30195,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.
    *
@@ -30209,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
       }))
@@ -30321,8 +30355,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 +30385,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 +30415,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
@@ -30394,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
@@ -30406,16 +30444,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) {
@@ -30426,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
     };
@@ -30435,7 +30480,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 +30981,16 @@ 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 };
+}
 
 // src/normalizers/query.ts
 function TermPatternDtoFromFrontToApi(model) {
@@ -37217,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;
 }
@@ -37330,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,
@@ -43048,8 +43108,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
   };
 }
@@ -51179,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,
@@ -51331,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;
@@ -51578,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,
@@ -51591,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,
@@ -51613,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;
@@ -51966,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.
@@ -53513,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.
@@ -53556,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
@@ -53627,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
@@ -60776,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