@kortexya/reasoninglayer 3.0.1 → 3.2.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "3.0.1";
+var SDK_VERSION = "3.2.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -167,6 +167,21 @@ var OsfqlError = class extends ApiError {
     this.sortDeleteRefusal = failure.sortDeleteRefusal;
   }
 };
+var NamedConstraintViolationError = class extends ApiError {
+  name = "NamedConstraintViolationError";
+  /** The feature whose constraint refused the write, when the engine names it. */
+  feature;
+  /** The constraint's name, when its author gave one. */
+  constraintName;
+  /** The constraint's message, when its author gave one. */
+  constraintMessage;
+  constructor(message, body, headers, refusal, errorCode) {
+    super(message, 422, body, headers, errorCode);
+    this.feature = refusal.feature;
+    this.constraintName = refusal.constraintName;
+    this.constraintMessage = refusal.constraintMessage;
+  }
+};
 var RateLimitError = class extends ApiError {
   name = "RateLimitError";
   /** Seconds to wait before retrying, or null if not specified. */
@@ -290,6 +305,10 @@ function createApiError(status, body, headers) {
       if (rows !== null) {
         return new BulkRefusedError(message, body, headers, rows, errorCode);
       }
+      const named = namedConstraintRefusal(body);
+      if (named !== null) {
+        return new NamedConstraintViolationError(message, body, headers, named, errorCode);
+      }
       return new ApiError(message, status, body, headers, errorCode);
     }
     case 429: {
@@ -341,7 +360,9 @@ function bulkRefusalRows(body) {
     rows.push({
       index: row.index,
       message: row.message,
-      ...typeof row.feature === "string" ? { feature: row.feature } : {}
+      ...typeof row.feature === "string" ? { feature: row.feature } : {},
+      ...typeof row.constraint_name === "string" ? { constraintName: row.constraint_name } : {},
+      ...typeof row.constraint_message === "string" ? { constraintMessage: row.constraint_message } : {}
     });
   }
   return rows.length > 0 ? rows : null;
@@ -369,6 +390,18 @@ function derivedFactRefusal(body) {
     repairs
   };
 }
+function namedConstraintRefusal(body) {
+  if (typeof body !== "object" || body === null) return null;
+  const obj = body;
+  const constraintName = typeof obj.constraint_name === "string" ? obj.constraint_name : void 0;
+  const constraintMessage = typeof obj.constraint_message === "string" ? obj.constraint_message : void 0;
+  if (constraintName === void 0 && constraintMessage === void 0) return null;
+  return {
+    ...typeof obj.feature === "string" ? { feature: obj.feature } : {},
+    ...constraintName !== void 0 ? { constraintName } : {},
+    ...constraintMessage !== void 0 ? { constraintMessage } : {}
+  };
+}
 function isConstraintViolationBody(body) {
   if (!isErrorBody(body)) return false;
   if (!("details" in body)) return false;
@@ -1276,6 +1309,24 @@ var Sorts = class {
     format: "json",
     ...params
   });
+  /**
+   * @description A `Proposed` sort becomes `Active`; a sort only flagged `needs_review` has the flag cleared. Anything else is not awaiting approval (409). Requires `Manage` on the sort under a gateway policy. Separation of duties is enforced here, by the engine that holds the proposal record: the acting user (`X-Authenticated-User`) who is the sort's recorded proposer (`SortStatus::Proposed { submitted_by }`) is refused with a coded 403 (`code: "separation_of_duties"`) naming the sort, and the refusal is recorded in the oversight ledger as a `rejected` decision on the action `sort.approve.refused` (#398). The gateway checks the steward permission at the project, where the roles live.
+   *
+   * @tags sorts
+   * @name ApproveSort
+   * @summary Approve a candidate sort
+   * @request POST:/api/v1/sorts/{id}/approve
+   * @secure
+   */
+  approveSort = (id, data, params = {}) => this.http.request({
+    path: `/api/v1/sorts/${id}/approve`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
   /**
    * @description POST /api/v1/sorts/bulk Creates multiple sorts in a single request, automatically resolving parent references by name. Sorts are topologically sorted to ensure parents are created before children. This is much faster than individual requests for large hierarchies. # Authorization Requires X-Tenant-Id header. The tenant_id field in the request body is ignored.
    *
@@ -1375,6 +1426,60 @@ var Sorts = class {
     format: "json",
     ...params
   });
+  /**
+   * @description Retires the sort, optionally in favour of a replacement (whose id or name is given), with a mandatory reason. Used both to reject a candidate after materialize and to retire an established concept.
+   *
+   * @tags sorts
+   * @name DeprecateSort
+   * @summary Deprecate (reject) a sort
+   * @request POST:/api/v1/sorts/{id}/deprecate
+   * @secure
+   */
+  deprecateSort = (id, data, params = {}) => this.http.request({
+    path: `/api/v1/sorts/${id}/deprecate`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
+  /**
+   * @description The steward's edit of where a concept sits: `add` and `remove` name parents by id or by name, and the sort keeps every other parent in its current order (added ones go last). The move itself is the one `PUT /api/v1/sorts/{id}/parents` runs (#292): the sort keeps its id and record, its subtree moves with it, the inherited declarations and the subsumption caches (GLB/LUB included) are repaired, and a refused move changes nothing. Requires `Manage` on the sort and on every parent added or removed under a gateway policy: a move changes who inherits access to the sort through a descendant grant. A change appends an `OversightDecision{modified}` to the audit ledger naming the reviewer. # Refused (422), with nothing changed An unknown parent, a parent to remove that is not one, an empty edit, the sort itself, a parent below the sort (a cycle), and every state the move would make contradictory (⊥): two cells of one disjoint facet, an inherited declaration no value satisfies, an own declaration weaker than a new ancestor's, a bound constraint left without its feature.
+   *
+   * @tags sorts
+   * @name EditSortParents
+   * @summary Add and remove parents of a sort
+   * @request POST:/api/v1/sorts/{id}/parents
+   * @secure
+   */
+  editSortParents = (id, data, params = {}) => this.http.request({
+    path: `/api/v1/sorts/${id}/parents`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
+  /**
+   * @description Formal Concept Analysis over sort × feature declaration, each declaration taken whole (name, range or type, constraint, requiredness, bound): every set of at least `min_sorts` sorts sharing at least two identical declarations is a candidate mixin. Deterministic; never writes. Accepting a proposal is creating the mixin (as a `proposed` sort) and re-parenting the members — the caller's decision: `POST /api/v1/scenarios/materialize` with the mixin and each member naming it as a parent does both, the moves going through the governed door of `POST /api/v1/sorts/{id}/parents`. A declaration a sort restates identically to an ancestor's is factored already and is never proposed again.
+   *
+   * @tags sorts
+   * @name FactorSortShapes
+   * @summary Propose mixin parents for shapes several sorts repeat unchanged
+   * @request POST:/api/v1/sorts/discovery/factor
+   * @secure
+   */
+  factorSortShapes = (data, params = {}) => this.http.request({
+    path: `/api/v1/sorts/discovery/factor`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
   /**
    * No description
    *
@@ -1723,7 +1828,7 @@ var Sorts = class {
     ...params
   });
   /**
-   * @description The body's `parents` REPLACES the sort's parent set; an empty list makes it a root. The sort keeps its id and its whole record — features, bounds, SKOS fields, annotations, status, provenance — and its subtree moves with it. Nothing is deleted and nothing is re-created. What depends on the ancestors is repaired for the sort and every subsort: the subsumption encoding, and the INHERITED feature declarations (a feature inherited from an old ancestor goes, one from a new ancestor comes; a declaration the sort makes itself is never touched). The response reports those changes, the terms whose sort now has different ancestors, and the rules naming a moved sort. The OSFQL spelling is `ALTER SORT <name> PARENTS (<parent>, …);` — the same move. # Refused, with nothing changed An unknown parent (or another tenant's), the sort itself, a parent below the sort (a cycle), a move past the depth cap, a facet violation, an own declaration weaker than a new ancestor's, a bound constraint left naming a feature a sort would stop inheriting, a declaration contradiction inherited from two new ancestors, a shared or authorization-schema sort, and a sort with more than 512 persisted subsorts. # Errors - 400 Bad Request: the move was refused; the message names the cause - 404 Not Found: no such sort for this tenant
+   * @description The body's `parents` REPLACES the sort's parent set; an empty list makes it a root. The sort keeps its id and its whole record — features, bounds, SKOS fields, annotations, status, provenance — and its subtree moves with it. Nothing is deleted and nothing is re-created. What depends on the ancestors is repaired for the sort and every subsort: the subsumption encoding, and the INHERITED feature declarations (a feature inherited from an old ancestor goes, one from a new ancestor comes; a declaration the sort makes itself is never touched). The response reports those changes, the terms whose sort now has different ancestors, and the rules naming a moved sort. The OSFQL spelling is `ALTER SORT <name> PARENTS (<parent>, …);` — the same move. # Governed Requires `Manage` on the sort and on every parent the move adds or removes, and a move that changes anything appends an `OversightDecision{modified}` naming the reviewer — the same door `POST /sorts/{id}/parents` and OSFQL go through. # Refused, with nothing changed An unknown parent (or another tenant's), the sort itself, a parent below the sort (a cycle), a move past the depth cap, a facet violation, an own declaration weaker than a new ancestor's, a bound constraint left naming a feature a sort would stop inheriting, a declaration contradiction inherited from two new ancestors, a shared or authorization-schema sort, and a sort with more than 512 persisted subsorts. # Errors - 400 Bad Request: the move was refused; the message names the cause - 404 Not Found: no such sort for this tenant
    *
    * @tags sorts
    * @name ReparentSort
@@ -2593,6 +2698,24 @@ var Inference = class {
     format: "json",
     ...params
   });
+  /**
+   * @description Takes the body `POST /api/v1/inference/rules` takes and runs every check that write runs — sorts and referenced terms resolve, guard bounds compare with their declared types, nested negation, binders, range restriction (every conclusion variable bound by a POSITIVE antecedent), aggregator, and the homoiconic encoding itself — by building the rule into a scratch copy of the tenant's store. Nothing is written, persisted, or propagated. Stratification included: a rule that closes a NEW cycle through negation against the existing program is refused by both (a cycle the program already had is not blamed on it). `ok` is exactly whether the write would accept the rule; `refusals` names why not, with the status the write would answer. `warnings` adds what the write accepts but the program may not mean: variables only a `NOT` mentions (NAF safety).
+   *
+   * @tags inference
+   * @name ValidateRule
+   * @summary Validate a rule without writing it
+   * @request POST:/api/v1/inference/rules/validate
+   * @secure
+   */
+  validateRule = (data, params = {}) => this.http.request({
+    path: `/api/v1/inference/rules/validate`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
 };
 
 // src/api-spec/generated/Cognitive.ts
@@ -3202,11 +3325,11 @@ var CognitiveAgentsMessaging = class {
    * No description
    *
    * @tags Cognitive Agents - Messaging
-   * @name GetInbox
+   * @name GetAgentInbox
    * @summary Get an agent's inbox.
    * @request POST:/api/v1/cognitive/agents/messages/inbox
    */
-  getInbox = (data, params = {}) => this.http.request({
+  getAgentInbox = (data, params = {}) => this.http.request({
     path: `/api/v1/cognitive/agents/messages/inbox`,
     method: "POST",
     body: data,
@@ -8721,7 +8844,7 @@ var Scenarios = class {
     ...params
   });
   /**
-   * @description Materializes an already-generated GeneratedScenario verbatim (no LLM call): sorts, belief instances, rules, goal, and the ontology-declared engine pipeline. Used by the studio's build wizard to persist exactly what was reviewed so it is immediately queryable in chat.
+   * @description Materializes an already-generated GeneratedScenario verbatim (no LLM call): sorts, belief instances, rules, goal, and the ontology-declared engine pipeline. Used by the studio's build wizard to persist exactly what was reviewed so it is immediately queryable in chat. An existing sort is reused and moved under any parent the scenario newly names for it, through the governed move of POST /sorts/{id}/parents; a refused move is reported in `warnings` and leaves the sort where it was.
    *
    * @tags scenarios
    * @name MaterializeScenario
@@ -9326,7 +9449,7 @@ var Synthetic = class {
     ...params
   });
   /**
-   * @description Uses principled strategies to create training examples that are negative (invalid) for specific, documented reasons: sort incompatibility, feature perturbation, cross-sort confusion, missing required features, and feature type mismatch. # Authorization Requires X-Tenant-Id header for tenant-scoped operations.
+   * @description Uses principled strategies to create training examples that are negative (invalid) for specific, documented reasons: a violation of each declared feature constraint (named in `violated_constraint`), sort incompatibility, feature perturbation, cross-sort confusion, missing required features, and feature type mismatch. Proposed sorts are included — negatives exist to test a model before it is approved; deprecated sorts are not. # Authorization Requires X-Tenant-Id header for tenant-scoped operations.
    *
    * @tags synthetic
    * @name GenerateNegatives
@@ -10225,6 +10348,23 @@ var Ontology = class {
     format: "json",
     ...params
   });
+  /**
+   * @description The fluent term about `of` with the latest `valid_from` not after `at` (default: now). 404 when the sort is unknown or no state is recorded by then.
+   *
+   * @tags ontology
+   * @name CurrentFluentValue
+   * @summary Current value of a fluent
+   * @request GET:/api/v1/fluents/current
+   * @secure
+   */
+  currentFluentValue = (query, params = {}) => this.http.request({
+    path: `/api/v1/fluents/current`,
+    method: "GET",
+    query,
+    secure: true,
+    format: "json",
+    ...params
+  });
   /**
    * No description
    *
@@ -10277,6 +10417,22 @@ var Ontology = class {
     format: "json",
     ...params
   });
+  /**
+   * No description
+   *
+   * @tags ontology
+   * @name GetOntologyScope
+   * @summary Read the ontology's scope.
+   * @request GET:/api/v1/ontology/scope
+   * @secure
+   */
+  getOntologyScope = (params = {}) => this.http.request({
+    path: `/api/v1/ontology/scope`,
+    method: "GET",
+    secure: true,
+    format: "json",
+    ...params
+  });
   /**
    * No description
    *
@@ -10325,6 +10481,24 @@ var Ontology = class {
     format: "json",
     ...params
   });
+  /**
+   * No description
+   *
+   * @tags ontology
+   * @name PutOntologyScope
+   * @summary Set the ontology's scope (replaces it).
+   * @request PUT:/api/v1/ontology/scope
+   * @secure
+   */
+  putOntologyScope = (data, params = {}) => this.http.request({
+    path: `/api/v1/ontology/scope`,
+    method: "PUT",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
   /**
    * No description
    *
@@ -10343,6 +10517,19 @@ var Ontology = class {
     format: "json",
     ...params
   });
+  /**
+   * No description
+   *
+   * @tags ontology
+   * @name UpperOntology
+   * @summary Serve an embedded upper-ontology seed (`bfo-2020` or `cco-facility`) — the same OWL the lattice-grounding aligner uses, offered to the guided builder's vocabulary stage as an anchor to reuse rather than reinvent.
+   * @request GET:/api/v1/ontology/upper/{name}
+   */
+  upperOntology = (name, params = {}) => this.http.request({
+    path: `/api/v1/ontology/upper/${name}`,
+    method: "GET",
+    ...params
+  });
 };
 
 // src/api-spec/generated/Generation.ts
@@ -13632,6 +13819,31 @@ var OntologyExport = class {
   });
 };
 
+// src/api-spec/generated/Argumentation.ts
+var Argumentation = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * No description
+   *
+   * @tags argumentation
+   * @name EvaluateArgumentation
+   * @request POST:/api/v1/argumentation/evaluate
+   * @secure
+   */
+  evaluateArgumentation = (data, params = {}) => this.http.request({
+    path: `/api/v1/argumentation/evaluate`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
+};
+
 // src/api-spec/generated/Embeddings.ts
 var Embeddings = class {
   http;
@@ -15088,7 +15300,9 @@ function BulkRowRefusalFromApiToFront(dto) {
   return {
     index: dto.index,
     message: dto.message,
-    ...dto.feature ? { feature: dto.feature } : {}
+    ...dto.feature ? { feature: dto.feature } : {},
+    ...dto.constraint_name != null ? { constraintName: dto.constraint_name } : {},
+    ...dto.constraint_message != null ? { constraintMessage: dto.constraint_message } : {}
   };
 }
 function ClearTermsResponseFromApiToFront(dto) {
@@ -15204,6 +15418,7 @@ function TermVersionDtoFromApiToFront(dto) {
   if (dto.diff != null) out.diff = VersionDiffDtoFromApiToFront(dto.diff);
   if (dto.follows_a_gap !== void 0) out.followsAGap = dto.follows_a_gap;
   if (dto.forked_to != null) out.forkedTo = dto.forked_to;
+  if (dto.seeded !== void 0) out.seeded = dto.seeded;
   return out;
 }
 function TermVersionsResponseFromApiToFront(dto) {
@@ -15244,6 +15459,8 @@ function ConstraintDtoFromFrontToApi(model) {
 function FeatureDescriptorDtoFromApiToFront(dto) {
   return {
     name: dto.name,
+    description: dto.description ?? void 0,
+    index: dto.index ?? void 0,
     expectedSort: dto.expected_sort ?? void 0,
     expectedTypeHint: dto.expected_type_hint ?? void 0,
     // The spec made this optional and documents the default explicitly:
@@ -15254,31 +15471,33 @@ function FeatureDescriptorDtoFromApiToFront(dto) {
     // `undefined` for a question the wire already answers.
     required: dto.required ?? false,
     constraint: dto.constraint ? ConstraintDtoFromApiToFront(dto.constraint) : void 0,
+    constraintName: dto.constraint_name ?? void 0,
+    constraintMessage: dto.constraint_message ?? void 0,
     key: dto.key,
     expectedSortName: dto.expected_sort_name ?? void 0,
     minCount: dto.min_count ?? void 0,
     maxCount: dto.max_count ?? void 0,
     cardinalityOrigin: dto.cardinality_origin ?? void 0,
-    annotations: definedRecord2(dto.annotations),
-    description: dto.description ?? void 0,
-    index: dto.index ?? void 0
+    annotations: definedRecord2(dto.annotations)
   };
 }
 function FeatureDescriptorDtoFromFrontToApi(model) {
   return {
     name: model.name,
+    description: model.description ?? void 0,
+    index: model.index ?? void 0,
     expected_sort: model.expectedSort ?? void 0,
     expected_type_hint: model.expectedTypeHint ?? void 0,
     required: model.required,
     constraint: model.constraint ? ConstraintDtoFromFrontToApi(model.constraint) : void 0,
+    constraint_name: model.constraintName ?? void 0,
+    constraint_message: model.constraintMessage ?? void 0,
     key: model.key,
     expected_sort_name: model.expectedSortName ?? void 0,
     min_count: model.minCount ?? void 0,
     max_count: model.maxCount ?? void 0,
     cardinality_origin: model.cardinalityOrigin ?? void 0,
-    annotations: model.annotations,
-    description: model.description ?? void 0,
-    index: model.index ?? void 0
+    annotations: model.annotations
   };
 }
 function CoextensiveDefinitionDtoFromApiToFront(dto) {
@@ -15385,6 +15604,12 @@ function SortInfoDtoFromApiToFront(dto) {
     name: dto.name ?? void 0
   };
 }
+function SortResponseFromApiToFront(dto) {
+  return {
+    sort: SortDtoFromApiToFront(dto.sort),
+    wokenResiduations: dto.woken_residuations ?? void 0
+  };
+}
 function SortListResponseFromApiToFront(dto) {
   return {
     sorts: dto.sorts.map(SortDtoFromApiToFront),
@@ -15723,11 +15948,38 @@ function SortIndexStatusResponseFromApiToFront(dto) {
   if (dto.last_indexed_count != null) out.lastIndexedCount = dto.last_indexed_count;
   return out;
 }
-function DeprecateSortRequestFromFrontToApi(model) {
-  const out = { replacement: model.replacement };
+function ApproveSortRequestFromFrontToApi(model) {
+  const out = {};
   if (model.reason !== void 0) out.reason = model.reason;
   return out;
 }
+function DeprecateSortRequestFromFrontToApi(model) {
+  const out = { reason: model.reason };
+  if (model.replacement !== void 0) out.replacement = model.replacement;
+  return out;
+}
+function FactorSortsRequestFromFrontToApi(model) {
+  const out = {};
+  if (model.sortIds !== void 0) out.sort_ids = model.sortIds;
+  if (model.minSorts !== void 0) out.min_sorts = model.minSorts;
+  return out;
+}
+function FactorSharedFeatureFromApiToFront(dto) {
+  const out = { name: dto.name, required: dto.required };
+  if (dto.expected_sort != null) out.expectedSort = dto.expected_sort;
+  if (dto.expected_type_hint != null) out.expectedTypeHint = dto.expected_type_hint;
+  if (dto.constraint != null) out.constraint = ConstraintDtoFromApiToFront(dto.constraint);
+  return out;
+}
+function FactorSortsResponseFromApiToFront(dto) {
+  return {
+    proposals: dto.proposals.map((p) => ({
+      memberSorts: p.member_sorts.map((m) => ({ id: m.id, name: m.name })),
+      sharedFeatures: p.shared_features.map(FactorSharedFeatureFromApiToFront),
+      suggestedName: p.suggested_name
+    }))
+  };
+}
 function PatchSortRequestFromFrontToApi(model) {
   const out = {};
   if (model.name !== void 0) out.name = model.name;
@@ -15739,10 +15991,6 @@ function PatchSortRequestFromFrontToApi(model) {
   if (model.scopeNote !== void 0) out.scope_note = model.scopeNote;
   if (model.annotations !== void 0) out.annotations = model.annotations;
   if (model.worldMode !== void 0) out.world_mode = model.worldMode;
-  if (model.approveProposed !== void 0) out.approve_proposed = model.approveProposed;
-  if (model.deprecate !== void 0) {
-    out.deprecate = model.deprecate === null ? null : DeprecateSortRequestFromFrontToApi(model.deprecate);
-  }
   return out;
 }
 function DeleteSortOptionsFromFrontToApi(options) {
@@ -15765,6 +16013,14 @@ function DeleteSortResponseFromApiToFront(dto) {
   if (dto.rules_orphaned !== void 0) {
     out.rulesOrphaned = dto.rules_orphaned.map(SortReferencingRuleDtoFromApiToFront);
   }
+  if (dto.sorts_deleted !== void 0) out.sortsDeleted = dto.sorts_deleted;
+  return out;
+}
+function EditSortParentsRequestFromFrontToApi(model) {
+  const out = {};
+  if (model.add !== void 0) out.add = model.add;
+  if (model.remove !== void 0) out.remove = model.remove;
+  if (model.reason !== void 0) out.reason = model.reason;
   return out;
 }
 function SortReferencingRuleDtoFromApiToFront(dto) {
@@ -15932,8 +16188,8 @@ var SortsClient = class {
     return SortDtoFromApiToFront(response.data.sort);
   }
   /**
-   * Curate a sort's vocabulary and lifecycle: rename, describe, label,
-   * relate, annotate, approve or deprecate it.
+   * Curate a sort's vocabulary: rename, describe, label, relate, annotate it,
+   * or change its world mode.
    *
    * @param sortId - Sort UUID.
    * @param request - The fields to change. Only present fields mutate.
@@ -15970,6 +16226,109 @@ var SortsClient = class {
     );
     return SortDtoFromApiToFront(response.data.sort);
   }
+  /**
+   * Approve a candidate sort: promote it from `Proposed` to `Active`.
+   *
+   * @param sortId - Sort UUID.
+   * @param request - Optionally, why the steward accepted it.
+   * @returns The approved sort, and how much suspended work its declaration
+   *   released (`wokenResiduations`).
+   * @throws {ForbiddenError} 403 when the caller holds no Manage grant on the
+   *   sort, or — with `code: "separation_of_duties"` in the body (see
+   *   `SortApprovalErrorCode`; read it with `errorBodyCode`) — when the
+   *   acting user (`authenticatedUser`) is the sort's recorded proposer.
+   *   Another steward can approve it.
+   * @throws {NotFoundError} 404 when the sort does not exist.
+   * @throws {ApiError} 409 when the sort is not awaiting approval.
+   *
+   * @remarks
+   * Appends an approval decision to the compliance ledger, with the
+   * authenticated user as reviewer. This replaced `approveProposed` on
+   * {@link SortsClient.patchSort}, which the engine now refuses.
+   *
+   * Separation of duties is enforced by the engine: the proposer's own
+   * approval is refused with the coded 403 and recorded in the oversight
+   * ledger as a `rejected` decision on `sort.approve.refused`.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const { sort, wokenResiduations } = await client.sorts.approveSort(sortId, {
+   *     reason: 'Matches the order lifecycle use case',
+   *   });
+   * } catch (error) {
+   *   if (errorBodyCode(error) === 'separation_of_duties') {
+   *     // The acting user proposed this sort: ask another steward to approve it.
+   *   }
+   * }
+   * ```
+   */
+  async approveSort(sortId, request = {}, requestOptions) {
+    const response = await this.sorts.approveSort(
+      sortId,
+      ApproveSortRequestFromFrontToApi(request),
+      toRequestParams(requestOptions)
+    );
+    return SortResponseFromApiToFront(response.data);
+  }
+  /**
+   * Deprecate a sort: reject a candidate, or retire an active concept,
+   * optionally in favour of a replacement.
+   *
+   * @param sortId - Sort UUID.
+   * @param request - Why (required), and the replacement's id or name.
+   * @returns The deprecated sort.
+   * @throws {BadRequestError} 400 when `reason` is empty or the replacement does not exist.
+   * @throws {ForbiddenError} 403 when the caller holds no Manage grant on the sort.
+   * @throws {NotFoundError} 404 when the sort does not exist.
+   *
+   * @remarks
+   * Appends a rejection decision to the compliance ledger. `replacement`
+   * accepts a sort id or a sort name in this tenant. This replaced the
+   * `deprecate` arm of {@link SortsClient.patchSort}, which the engine now
+   * refuses.
+   *
+   * @example
+   * ```typescript
+   * await client.sorts.deprecateSort(sortId, {
+   *   reason: 'Duplicate of customer',
+   *   replacement: 'customer',
+   * });
+   * ```
+   */
+  async deprecateSort(sortId, request, requestOptions) {
+    const response = await this.sorts.deprecateSort(
+      sortId,
+      DeprecateSortRequestFromFrontToApi(request),
+      toRequestParams(requestOptions)
+    );
+    return SortResponseFromApiToFront(response.data);
+  }
+  /**
+   * Propose mixin parents for feature shapes several sorts repeat unchanged.
+   *
+   * @param request - Which sorts to analyse (default: all), and the least
+   *   number of sorts a proposal must cover (default and floor: 2).
+   * @returns Candidate parents, most shared declarations first.
+   * @throws {ApiError} If the request fails.
+   *
+   * @remarks
+   * Deterministic and read-only: it groups sorts over identical feature +
+   * constraint declarations. `suggestedName` is a placeholder to rename
+   * before creating the parent.
+   *
+   * @example
+   * ```typescript
+   * const { proposals } = await client.sorts.factorSorts({ minSorts: 3 });
+   * ```
+   */
+  async factorSorts(request = {}, requestOptions) {
+    const response = await this.sorts.factorSortShapes(
+      FactorSortsRequestFromFrontToApi(request),
+      toRequestParams(requestOptions)
+    );
+    return FactorSortsResponseFromApiToFront(response.data);
+  }
   /**
    * Delete a sort by ID.
    *
@@ -16081,6 +16440,47 @@ var SortsClient = class {
     );
     return SortDeletePreviewResponseFromApiToFront(response.data);
   }
+  /**
+   * Add and remove parents of a sort — a steward's governed move in the lattice.
+   *
+   * @param sortId - Sort UUID.
+   * @param request - Parents to add and to remove (by id or by name), and why.
+   * @returns The move's report — what moved, what each sort's inheritance
+   *   gained and lost, the terms and rules concerned — with the sort as it now
+   *   stands.
+   * @throws {ForbiddenError} 403 without `Manage` on the sort and on every
+   *   parent added or removed.
+   * @throws {NotFoundError} 404 when the sort does not exist.
+   * @throws {ApiError} 422, with nothing changed, for an unknown parent, a
+   *   parent to remove that is not one, an empty edit, the sort itself, a
+   *   parent below the sort (a cycle), or any state the move would make
+   *   contradictory (⊥).
+   *
+   * @remarks
+   * The sort keeps every other parent in its current order; added ones go last.
+   * The move is the one {@link SortsClient.reparentSort} runs: the sort keeps
+   * its id and record, its subtree moves with it, inherited declarations and
+   * the subsumption caches are repaired. A change appends an oversight
+   * decision to the audit ledger naming the reviewer.
+   *
+   * @example
+   * ```typescript
+   * const moved = await client.sorts.editSortParents(sortId, {
+   *   add: ['vehicle'],
+   *   remove: ['thing'],
+   *   reason: 'A truck is a vehicle',
+   * });
+   * console.log(moved.inheritanceChanges);
+   * ```
+   */
+  async editSortParents(sortId, request, requestOptions) {
+    const response = await this.sorts.editSortParents(
+      sortId,
+      EditSortParentsRequestFromFrontToApi(request),
+      toRequestParams(requestOptions)
+    );
+    return SortReparentResponseFromApiToFront(response.data);
+  }
   /**
    * Move a sort in the lattice: replace its parent set.
    *
@@ -17938,6 +18338,21 @@ function ResidualDerivationDtoFromApiToFront(dto) {
 function AddRuleResponseFromApiToFront(dto) {
   return { term: PsiTermDtoFromApiToFront(dto.term) };
 }
+function RuleValidationResponseFromApiToFront(dto) {
+  const issue = (i) => ({
+    kind: i.kind,
+    message: i.message,
+    ...i.status != null ? { status: i.status } : {}
+  });
+  const out = {
+    ok: dto.ok,
+    refusals: dto.refusals.map(issue),
+    warnings: dto.warnings.map(issue)
+  };
+  if (dto.rule !== void 0)
+    out.rule = dto.rule === null ? null : PsiTermDtoFromApiToFront(dto.rule);
+  return out;
+}
 function AddFactResponseFromApiToFront(dto) {
   return { term: PsiTermDtoFromApiToFront(dto.term) };
 }
@@ -18483,7 +18898,8 @@ function RuleTermDraftDtoFromApiToFront(dto) {
     // The engine types each value as a scalar (`RuleDraftFeatureValueDto`) and
     // refuses a draft carrying anything else, so the map passes through; only
     // the generated `Partial` is narrowed to a total record.
-    features: definedRecordOrNullish(dto.features)
+    features: definedRecordOrNullish(dto.features),
+    ...dto.negated === true ? { negated: true } : {}
   };
 }
 function RuleDraftDtoFromApiToFront(dto) {
@@ -18557,11 +18973,23 @@ 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.
-   * @throws {ApiError} If the rule is rejected or the request fails.
+   * @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
+   *   head (conclusion)` or `body antecedent N`), a guard bound the declared
+   *   type cannot compare, a binder on the conclusion, or a rule that closes a
+   *   NEW cycle through negation (no stratification would order the program; a
+   *   cycle the program already had is not blamed on it). 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
+   *   constraint's refusal.
    *
    * @remarks
    * **Serialization format**: untagged `TermInputDto` / `FeatureInputValueDto`.
    *
+   * Ask {@link InferenceClient.validateRule} first to learn every reason the
+   * write would refuse, without writing.
    * 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.
@@ -18588,6 +19016,45 @@ var InferenceClient = class {
     );
     return AddRuleResponseFromApiToFront(response.data);
   }
+  /**
+   * Run every check {@link InferenceClient.addRule} runs — without writing.
+   *
+   * @param request - The same rule `addRule` takes.
+   * @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 {ApiError} If the request itself fails.
+   *
+   * @remarks
+   * The rule is built into a scratch copy of the tenant's store: sorts and
+   * referenced terms resolve, guard bounds compare with their declared types,
+   * nested negation, binders, range restriction, the aggregator, the
+   * homoiconic encoding, and stratification (a NEW cycle through negation is
+   * an `unstratifiable` refusal). Nothing is written, persisted or propagated.
+   * **Serialization format**: untagged `TermInputDto` / `FeatureInputValueDto`.
+   *
+   * @example
+   * ```typescript
+   * const check = await client.inference.validateRule({
+   *   term: psi('adult', { name: Var('N') }),
+   *   antecedents: [psi('person', { name: Var('N') })],
+   * });
+   * if (!check.ok) for (const r of check.refusals) console.warn(r.kind, r.message);
+   * ```
+   */
+  async validateRule(request, requestOptions) {
+    const wireRequest = {
+      term: convertTermArg(request.term),
+      antecedents: request.antecedents?.map(convertTermArg),
+      certainty: request.certainty,
+      aggregator: request.aggregator
+    };
+    const response = await this.api.validateRule(
+      AddRuleRequestFromFrontToApi(wireRequest),
+      toRequestParams(requestOptions)
+    );
+    return RuleValidationResponseFromApiToFront(response.data);
+  }
   /**
    * Add a fact.
    *
@@ -18624,7 +19091,9 @@ var InferenceClient = class {
    * its index in `request.rules`, with the engine's reason (for example
    * `rule head term did not resolve: it names sort \`x\`, which this
    * tenant's sort hierarchy does not define`). `rulesAdded` plus
-   * `rejected.length` equals the number submitted.
+   * `rejected.length` equals the number submitted. 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.
    *
    * @example
    * ```typescript
@@ -19164,7 +19633,10 @@ var InferenceClient = class {
    * `{"type": "String", "value": "..."}` envelope. The engine refuses a model answer that
    * carries one, re-prompts, and answers 422 when the model keeps producing it. Each
    * {@link RuleTermDraftDto} maps directly onto a `TermInputDto` inline-by-sort-name
-   * term, so an approved draft can be handed straight to {@link addRule}.
+   * term, so an approved draft can be handed straight to {@link addRule} — except an
+   * antecedent with `negated: true`, which must be wrapped in the `negation` carrier
+   * (`not(psi(sortName, features))`); sent bare, it would assert the positive
+   * condition.
    *
    * Drafting is multi-turn: if `status` is `'needs_clarification'`, answer each question
    * and call again with the echoed `sessionId` and an `answers` map keyed by the question's
@@ -19407,6 +19879,7 @@ function NlQueryRequestFromFrontToApi(model) {
     mode: model.mode,
     tenant_id: model.tenantId,
     conversation_history: model.conversationHistory ?? void 0,
+    focus_sorts: model.focusSorts ?? void 0,
     session_id: model.sessionId ?? void 0,
     exclude_domains: model.excludeDomains ?? void 0,
     focus_proposal: model.focusProposal ?? void 0,
@@ -19712,6 +20185,10 @@ var QueryClient = class {
    * @remarks
    * Plain JSON, no tagged/untagged value serialization.
    *
+   * In llm mode, `focusSorts` names the sorts the question is about: each is
+   * always in the schema the translator sees, even a sort built a moment ago
+   * with no records, which the record-count ranking would otherwise cut.
+   *
    * TRIZ mode (`mode: "triz"`) is multi-turn:
    * 1. A request with no `sessionId` opens a session, structures the problem
    *    (reading any `images` first) and solves it. The response names the
@@ -21113,13 +21590,23 @@ var CognitiveClient = class {
    * Uses POST `/api/v1/cognitive/agents/messages/inbox`. The inbox is per-agent;
    * aggregate across a roster by calling this for each agent.
    */
-  async getInbox(request, requestOptions) {
-    const response = await this.messaging.getInbox(
+  async getAgentInbox(request, requestOptions) {
+    const response = await this.messaging.getAgentInbox(
       GetInboxRequestFromFrontToApi({ ...request, tenantId: this.tenantId }),
       toRequestParams(requestOptions)
     );
     return GetInboxResponseFromApiToFront(response.data);
   }
+  /**
+   * Get an agent's inbox.
+   *
+   * @deprecated Renamed to {@link CognitiveClient.getAgentInbox} when the engine
+   * renamed the operation (`get_inbox` → `get_agent_inbox`); kept so existing
+   * callers keep compiling. Same request, same response.
+   */
+  async getInbox(request, requestOptions) {
+    return this.getAgentInbox(request, requestOptions);
+  }
   // --- Feedback ---
   /**
    * Provide feedback on an agent result.
@@ -30775,6 +31262,8 @@ function GetScenarioResponseFromApiToFront(dto) {
 }
 function MaterializeScenarioRequestFromFrontToApi(model) {
   return {
+    // 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.
     scenario: model.scenario
   };
 }
@@ -30788,7 +31277,11 @@ function MaterializeScenarioResponseFromApiToFront(dto) {
     rulesCreated: dto.rules_created,
     sensorPointsCreated: dto.sensor_points_created,
     sortsCreated: dto.sorts_created,
-    warnings: dto.warnings
+    warnings: dto.warnings,
+    ...dto.competency_questions_created !== void 0 ? { competencyQuestionsCreated: dto.competency_questions_created } : {},
+    ...dto.computed_features_created !== void 0 ? { computedFeaturesCreated: dto.computed_features_created } : {},
+    ...dto.fluents_created !== void 0 ? { fluentsCreated: dto.fluents_created } : {},
+    ...dto.proposed_sort_ids !== void 0 ? { proposedSortIds: dto.proposed_sort_ids } : {}
   };
 }
 function UpdateScenarioRequestFromFrontToApi(model) {
@@ -30908,6 +31401,19 @@ var ScenariosClient = class {
    * written. No value-level serialization split applies. Response fields are
    * normalized from snake_case to camelCase.
    *
+   * Staged builder: sorts marked `proposed: true` land as `Proposed` candidates
+   * (their ids in `proposedSortIds`, awaiting a steward's approval), and the
+   * scenario's use cases and competency questions are recorded as `proposed`
+   * competency questions.
+   *
+   * A sort (or fluent) may carry `provenance` — see {@link ScenarioSortProvenance} —
+   * recorded as its origin; without it the sort is credited to the caller.
+   *
+   * An existing sort is reused, and moved under any parent the scenario newly names
+   * for it through the same governed move as `SortsClient.editSortParents`. A move the
+   * engine refuses leaves the sort where it was and is reported in `warnings`, not
+   * as an error — read `warnings` after every call.
+   *
    * @example
    * ```typescript
    * const result = await client.scenarios.materializeScenario({ scenario: generated });
@@ -32633,7 +33139,8 @@ function StartExplorationRequestFromFrontToApi(model) {
     max_concepts: model.maxConcepts,
     min_extent_size: model.minExtentSize,
     min_intent_size: model.minIntentSize,
-    max_terms: model.maxTerms
+    max_terms: model.maxTerms,
+    ...model.sortNames !== void 0 ? { sort_names: model.sortNames } : {}
   };
 }
 function StartExplorationResponseFromApiToFront(dto) {
@@ -33915,17 +34422,30 @@ function CheckDiversityResponseFromApiToFront(dto) {
     termsCompared: dto.terms_compared
   };
 }
+function ViolatedConstraintDtoFromApiToFront(dto) {
+  return {
+    feature: dto.feature,
+    kind: dto.kind,
+    ...dto.constraint_name != null ? { constraintName: dto.constraint_name } : {},
+    ...dto.constraint_message != null ? { constraintMessage: dto.constraint_message } : {}
+  };
+}
 function NegativeExampleDtoFromApiToFront(dto) {
   return {
     explanation: dto.explanation,
     rejectionReason: dto.rejection_reason,
     sortId: dto.sort_id,
     strategy: dto.strategy,
-    termId: dto.term_id
+    termId: dto.term_id,
+    ...dto.sort != null ? { sort: dto.sort } : {},
+    ...dto.features != null ? { features: Object.fromEntries(Object.entries(dto.features)) } : {},
+    ...dto.world_mode != null ? { worldMode: dto.world_mode } : {},
+    ...dto.violated_constraint != null ? { violatedConstraint: ViolatedConstraintDtoFromApiToFront(dto.violated_constraint) } : {}
   };
 }
 function GenerateNegativesRequestFromFrontToApi(model) {
   return {
+    enable_constraint_violation: model.enableConstraintViolation,
     enable_cross_sort_confusion: model.enableCrossSortConfusion,
     enable_feature_perturbation: model.enableFeaturePerturbation,
     enable_sort_incompatibility: model.enableSortIncompatibility,
@@ -34202,6 +34722,30 @@ var SyntheticClient = class {
    * @param request - Negative generation parameters including target sorts and strategy flags.
    * @returns Generated negative examples with provenance.
    * @throws {ApiError} If the request fails.
+   *
+   * @remarks
+   * Each negative is invalid for a documented reason, named by its
+   * `strategy`: a violation of each declared feature constraint
+   * (`ConstraintViolation`, one negative per enum / range / pattern /
+   * maximum-cardinality constraint, with the constraint in
+   * `violatedConstraint`), sort incompatibility, feature perturbation,
+   * cross-sort confusion, a missing required feature, or a feature type
+   * mismatch. Set `enableConstraintViolation: false` to skip the first.
+   *
+   * Proposed sorts are included — negatives exist to test a model before it
+   * is approved; deprecated sorts are not.
+   *
+   * @example
+   * ```typescript
+   * const { negatives } = await client.synthetic.generateNegatives({
+   *   targetSorts: [pizzaSortId],
+   * });
+   * for (const n of negatives) {
+   *   if (n.violatedConstraint) {
+   *     console.log(n.violatedConstraint.feature, n.violatedConstraint.constraintMessage);
+   *   }
+   * }
+   * ```
    */
   async generateNegatives(request, requestOptions) {
     const response = await this.api.generateNegatives(
@@ -35442,12 +35986,15 @@ var ImageExtractionClient = class {
 
 // src/normalizers/ontology.ts
 function GenerateOntologyRequestFromFrontToApi(model) {
-  return {
+  const out = {
     answers: model.answers,
     prompt: model.prompt,
     session_id: model.sessionId,
     tenant_id: model.tenantId
   };
+  if (model.stage !== void 0) out.stage = model.stage;
+  if (model.draft !== void 0) out.draft = model.draft;
+  return out;
 }
 function GenerateOntologyResponseFromApiToFront(dto) {
   if (dto.status === "needs_clarification") {
@@ -35458,6 +36005,15 @@ function GenerateOntologyResponseFromApiToFront(dto) {
       understood: dto.understood
     };
   }
+  if (dto.status === "patch") {
+    const out = {
+      stage: dto.stage,
+      patch: dto.patch,
+      status: dto.status
+    };
+    if (dto.notes != null) out.notes = dto.notes;
+    return out;
+  }
   return {
     existingSortsCount: dto.existing_sorts_count,
     generationTimeMs: dto.generation_time_ms,
@@ -35519,18 +36075,28 @@ function PipelineStatusResponseFromApiToFront(dto) {
   };
 }
 function CompetencyQuestionFromApiToFront(dto) {
-  return {
+  const out = {
     key: dto.key,
     question: dto.question,
-    osfql: dto.osfql,
     kind: dto.kind,
     origin: dto.origin,
-    status: dto.status,
-    expected: dto.expected
+    osfql: dto.osfql,
+    expected: dto.expected,
+    status: dto.status
   };
+  if (dto.description != null) out.description = dto.description;
+  if (dto.use_case != null) out.useCase = dto.use_case;
+  if (dto.sorts !== void 0) out.sorts = dto.sorts;
+  return out;
 }
 function CreateCompetencyQuestionRequestFromFrontToApi(model) {
-  return { question: model.question, osfql: model.osfql, kind: model.kind };
+  const out = { question: model.question };
+  if (model.kind !== void 0) out.kind = model.kind;
+  if (model.osfql !== void 0) out.osfql = model.osfql;
+  if (model.description !== void 0) out.description = model.description;
+  if (model.useCase !== void 0) out.use_case = model.useCase;
+  if (model.sorts !== void 0) out.sorts = model.sorts;
+  return out;
 }
 function ListCompetencyQuestionsResponseFromApiToFront(dto) {
   return {
@@ -35644,6 +36210,44 @@ function EnrichOntologyResponseFromApiToFront(dto) {
     applied: dto.applied
   };
 }
+function OntologyScopeFromFrontToApi(model) {
+  const out = {
+    purpose: model.purpose,
+    dynamics: model.dynamics,
+    write_mode: model.writeMode
+  };
+  if (model.inScope !== void 0) out.in_scope = model.inScope;
+  if (model.outOfScope !== void 0) out.out_of_scope = model.outOfScope;
+  if (model.deferred !== void 0) out.deferred = model.deferred;
+  if (model.notes !== void 0) out.notes = model.notes;
+  return out;
+}
+function OntologyScopeResponseFromApiToFront(dto) {
+  const out = {
+    purpose: dto.purpose,
+    inScope: dto.in_scope ?? [],
+    outOfScope: dto.out_of_scope ?? [],
+    deferred: dto.deferred ?? [],
+    dynamics: dto.dynamics,
+    writeMode: dto.write_mode,
+    updatedAt: dto.updated_at
+  };
+  if (dto.notes != null) out.notes = dto.notes;
+  if (dto.updated_by != null) out.updatedBy = dto.updated_by;
+  return out;
+}
+function CurrentFluentResponseFromApiToFront(dto) {
+  const out = {
+    sort: dto.sort,
+    of: dto.of,
+    at: dto.at,
+    termId: dto.term_id,
+    value: dto.value,
+    validFrom: dto.valid_from
+  };
+  if (dto.generated_by != null) out.generatedBy = dto.generated_by;
+  return out;
+}
 
 // src/resources/ontology.ts
 var OntologyClient = class {
@@ -35665,6 +36269,13 @@ var OntologyClient = class {
    * If the response status is `"needs_clarification"`, supply `sessionId`
    * and `answers` on the next call to complete the generation.
    *
+   * Staged builder: with `stage` (and the current `draft`), the response is
+   * `{ status: 'patch', stage, patch, notes? }` — that stage's scenario keys
+   * alone, to merge into the draft.
+   *
+   * The body is sent verbatim (no key re-casing): `draft` is scenario JSON
+   * whose nested keys include the user's own feature names.
+   *
    * @example
    * ```typescript
    * // First call -- may need clarification
@@ -35680,12 +36291,20 @@ var OntologyClient = class {
    *     answers: { priority_levels: '3' },
    *   });
    * }
+   *
+   * // Staged: one stage's patch over the current draft
+   * const step = await client.ontology.generate({
+   *   prompt: 'Build a customer support ticket system',
+   *   stage: 'sorts',
+   *   draft,
+   * });
+   * if (step.status === 'patch') Object.assign(draft, step.patch);
    * ```
    */
   async generate(request, requestOptions) {
     const response = await this.api.generate(
       GenerateOntologyRequestFromFrontToApi(request),
-      toRequestParams(requestOptions)
+      mergeRequestParams({ headers: { [RAW_BODY_HEADER]: "1" } }, requestOptions)
     );
     return GenerateOntologyResponseFromApiToFront(response.data);
   }
@@ -35885,6 +36504,118 @@ var OntologyClient = class {
     );
     return EnrichOntologyResponseFromApiToFront(response.data);
   }
+  /**
+   * Read the ontology's scope.
+   *
+   * @returns The stored scope, or `null` when none has been set.
+   * @throws {ApiError} If the request fails for a reason other than "no scope".
+   *
+   * @remarks
+   * One scope per tenant, or per namespace when `X-Namespace-Id` is sent. The
+   * engine answers 404 when none was set; that is an expected state for a new
+   * ontology, so it reads as `null` rather than an error.
+   *
+   * @example
+   * ```typescript
+   * const scope = await client.ontology.getScope();
+   * if (scope === null) {
+   *   // first visit: ask the user what the ontology is for
+   * }
+   * ```
+   */
+  async getScope(requestOptions) {
+    try {
+      const response = await this.api.getOntologyScope(toRequestParams(requestOptions));
+      return OntologyScopeResponseFromApiToFront(response.data);
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Set the ontology's scope, replacing the stored one.
+   *
+   * @param scope - Purpose, coverage, dynamics and write mode.
+   * @returns The stored scope with its provenance.
+   * @throws {BadRequestError} If `purpose` is empty.
+   *
+   * @example
+   * ```typescript
+   * await client.ontology.putScope({
+   *   purpose: 'Answer questions about late deliveries',
+   *   inScope: ['orders', 'shipments'],
+   *   dynamics: 'dynamic',
+   *   writeMode: 'append',
+   * });
+   * ```
+   */
+  async putScope(scope, requestOptions) {
+    const response = await this.api.putOntologyScope(
+      OntologyScopeFromFrontToApi(scope),
+      toRequestParams(requestOptions)
+    );
+    return OntologyScopeResponseFromApiToFront(response.data);
+  }
+  /**
+   * Fetch an embedded upper-ontology seed as OWL RDF/XML.
+   *
+   * @param name - `bfo-2020` or `cco-facility`.
+   * @returns The OWL document, as text.
+   * @throws {NotFoundError} If the name is not an embedded upper ontology.
+   *
+   * @remarks
+   * The same OWL the lattice-grounding aligner uses, offered as an anchor to
+   * reuse rather than reinvent. The response is `application/rdf+xml`, not JSON.
+   *
+   * @example
+   * ```typescript
+   * const owl = await client.ontology.getUpperOntology('bfo-2020');
+   * ```
+   */
+  async getUpperOntology(name, requestOptions) {
+    const response = await this.api.http.request({
+      ...toRequestParams(requestOptions),
+      path: `/api/v1/ontology/upper/${encodeURIComponent(name)}`,
+      method: "GET",
+      format: "text"
+    });
+    return response.data;
+  }
+  /**
+   * Read the state a fluent holds for an entity at an instant.
+   *
+   * @param query - The fluent sort, the entity's term id, and the instant (default now).
+   * @returns The latest fluent term with `validFrom <= at`.
+   * @throws {NotFoundError} If the fluent sort is unknown, or no state was recorded by `at`.
+   * @throws {BadRequestError} If `at` is not RFC 3339.
+   *
+   * @remarks
+   * The engine answers the same 404 for an unknown fluent sort and for an
+   * entity with no state yet, so this throws rather than returning `null`:
+   * the two cannot be told apart.
+   *
+   * @example
+   * ```typescript
+   * const status = await client.ontology.getCurrentFluent({
+   *   sort: 'order_status',
+   *   of: orderId,
+   * });
+   * console.log(status.value, status.validFrom);
+   * ```
+   */
+  async getCurrentFluent(query, requestOptions) {
+    const response = await this.api.currentFluentValue(
+      {
+        sort: query.sort,
+        of: query.of,
+        ...query.at !== void 0 ? { at: query.at } : {}
+      },
+      toRequestParams(requestOptions)
+    );
+    return CurrentFluentResponseFromApiToFront(response.data);
+  }
 };
 
 // src/normalizers/generation.ts
@@ -38104,6 +38835,7 @@ function UIActionResponseFromApiToFront(dto) {
     error: dto.error ?? void 0,
     pendingReviewId: dto.pending_review_id ?? void 0,
     producedTermIds: dto.produced_term_ids,
+    ...dto.retracted_term_ids !== void 0 ? { retractedTermIds: dto.retracted_term_ids } : {},
     requiresApproval: dto.requires_approval,
     requiresConfirmation: dto.requires_confirmation,
     retractedTermIds: dto.retracted_term_ids,
@@ -38481,15 +39213,20 @@ function TurnDtoFromApiToFront(dto) {
     claimAnnotations: dto.claim_annotations?.map(ClaimAnnotationDtoFromApiToFront),
     // Rows go through the same narrowing as the message response, so a reloaded
     // turn keeps its table with the same value types a live turn has.
-    queryResults: dto.query_results?.map(osfqlRowFromApiToFront) ?? void 0
+    queryResults: dto.query_results?.map(osfqlRowFromApiToFront) ?? void 0,
+    ...dto.payload !== void 0 && dto.payload !== null ? { payload: dto.payload } : {}
   };
 }
 function RecordTurnRequestFromFrontToApi(model) {
-  return {
+  const out = {
     role: model.role,
     content: model.content,
     osfql: model.osfql
   };
+  if (model.payload !== void 0) out.payload = model.payload;
+  if (model.conversationKind !== void 0) out.conversation_kind = model.conversationKind;
+  if (model.title !== void 0) out.title = model.title;
+  return out;
 }
 function RecordTurnResponseFromApiToFront(dto) {
   return {
@@ -38502,7 +39239,9 @@ function ConversationSummaryDtoFromApiToFront(dto) {
     id: dto.id,
     sessionId: dto.session_id ?? void 0,
     createdAt: dto.created_at,
-    turnCount: dto.turn_count
+    turnCount: dto.turn_count,
+    ...dto.kind != null ? { kind: dto.kind } : {},
+    ...dto.title != null ? { title: dto.title } : {}
   };
 }
 function ListConversationsResponseFromApiToFront(dto) {
@@ -38788,6 +39527,11 @@ var ConversationClient = class {
    * Request and response bodies use plain JSON scalars; no tagged/untagged value
    * serialization is involved. Turns recorded here are returned by {@link getTurns}.
    *
+   * `payload` is opaque structured card state (drafts, questions, findings…),
+   * stored verbatim and returned on the turn — so the body is sent without key
+   * re-casing. `conversationKind` and `title` apply when the conversation is
+   * created (`title` also later, while it has none); a surface uses
+   * `conversationKind` to partition the shared history list.
    * The engine also offers each turn to the tenant's long-term memory. A turn the
    * memory policy refuses (for example text over 500 characters) is still
    * recorded and still answers `200`; it only does not enter memory.
@@ -38806,11 +39550,21 @@ var ConversationClient = class {
    *   content: 'Done — split it into `auth/session.rs` and `auth/token.rs`.',
    *   osfql: 'MATCH module(name: ?N);',
    * });
+   *
+   * // A surface with richer turns: its own history partition and card state.
+   * await client.conversation.recordTurn('new', {
+   *   role: 'assistant',
+   *   content: 'Here is a draft scope.',
+   *   conversationKind: 'guided_ontology',
+   *   title: 'Pizza ontology',
+   *   payload: { card: 'scope_draft', draft: { purpose: 'Take pizza orders' } },
+   * });
    * ```
    */
   async recordTurn(conversationId, request, requestOptions) {
     const response = await this.http.request({
       ...toRequestParams(requestOptions),
+      headers: mergeRequestHeaders({ [RAW_BODY_HEADER]: "1" }, requestOptions),
       path: `/api/v1/conversation/${encodeURIComponent(conversationId)}/turns`,
       method: "POST",
       body: RecordTurnRequestFromFrontToApi(request),
@@ -47366,6 +48120,96 @@ var OntologyExportClient = class {
   }
 };
 
+// src/normalizers/argumentation.ts
+function ArgumentationEvaluateRequestFromFrontToApi(model) {
+  const out = {
+    claims: model.claims.map((c) => ({
+      term_id: c.termId,
+      ...c.id !== void 0 ? { id: c.id } : {}
+    }))
+  };
+  if (model.preferences !== void 0) {
+    out.preferences = model.preferences.map((p) => ({ preferred: p.preferred, over: p.over }));
+  }
+  if (model.retracted !== void 0) out.retracted = model.retracted;
+  if (model.enableDerivation !== void 0) out.enable_derivation = model.enableDerivation;
+  if (model.useTenantRules !== void 0) out.use_tenant_rules = model.useTenantRules;
+  if (model.rulesOsfql !== void 0) out.rules_osfql = model.rulesOsfql;
+  if (model.matchThreshold !== void 0) out.match_threshold = model.matchThreshold;
+  return out;
+}
+function ArgumentationEvaluateResponseFromApiToFront(dto) {
+  return {
+    arguments: dto.arguments.map((a) => ({
+      id: a.id,
+      index: a.index,
+      termId: a.term_id,
+      text: a.text,
+      label: a.label
+    })),
+    attacks: dto.attacks.map((a) => ({
+      from: a.from,
+      to: a.to,
+      kind: a.kind,
+      reason: a.reason,
+      proved: a.proved
+    })),
+    grounded: {
+      accepted: dto.grounded.accepted,
+      rejected: dto.grounded.rejected,
+      undecided: dto.grounded.undecided
+    },
+    questions: dto.questions.map((q) => ({ a: q.a, b: q.b, prompt: q.prompt })),
+    warnings: dto.warnings ?? []
+  };
+}
+
+// src/resources/argumentation.ts
+var ArgumentationClient = class {
+  /** @internal */
+  api;
+  /** @internal */
+  constructor(api) {
+    this.api = api;
+  }
+  /**
+   * Evaluate a set of claims: label each argument and surface the conflicts
+   * only the user can resolve.
+   *
+   * @param request - The claims, and the resolutions and retractions so far.
+   * @returns Labelled arguments, evidence-carrying attacks, the grounded
+   *   extension, and one question per unresolved conflict.
+   * @throws {BadRequestError} 400 when there are no claims, or a term or
+   *   preference id is unknown.
+   * @throws {ApiError} 422 when `rulesOsfql` fails to parse, compile, or execute.
+   *
+   * @remarks
+   * Multi-turn: answer a question by adding a {@link ArgumentPreference} and
+   * evaluate again with the same argument ids; each preference deletes one
+   * attack. Plain JSON on the wire — no tagged/untagged value split applies.
+   *
+   * @example
+   * ```typescript
+   * const turn = await client.argumentation.evaluate({
+   *   claims: [{ termId: a, id: 'a' }, { termId: b, id: 'b' }],
+   * });
+   * for (const q of turn.questions) console.log(q.prompt);
+   *
+   * const settled = await client.argumentation.evaluate({
+   *   claims: [{ termId: a, id: 'a' }, { termId: b, id: 'b' }],
+   *   preferences: [{ preferred: 'a', over: 'b' }],
+   * });
+   * ```
+   */
+  async evaluate(request, requestOptions) {
+    const response = await this.api.evaluateArgumentation(
+      ArgumentationEvaluateRequestFromFrontToApi(request),
+      toRequestParams(requestOptions)
+    );
+    return ArgumentationEvaluateResponseFromApiToFront(response.data);
+  }
+};
+
 // src/normalizers/demo.ts
 function DemoSeedRequestFromFrontToApi(model) {
   const dto = {};
@@ -50397,6 +51241,8 @@ var ReasoningLayerClient = class {
   agui;
   /** Ontology export — OWL ontology and SHACL shapes projected from the sort lattice. */
   ontologyExport;
+  /** Grounded argumentation — label conflicting claims and surface the questions only the user can settle. */
+  argumentation;
   /** Demo substrate seeding — full SUMO + demo scenarios into the tenant substrate. */
   demo;
   /** Execution-free reward scoring for candidate queries (recall / precision). */
@@ -50538,7 +51384,8 @@ var ReasoningLayerClient = class {
       forecast: this.forecast,
       corpus: this.corpus,
       osfDiff: this.osfDiff,
-      conformance: this.conformance
+      conformance: this.conformance,
+      argumentation: this.argumentation
     };
   }
   /** Data ingestion and extraction operations — documents, sources, collections, images. */
@@ -50671,6 +51518,7 @@ var ReasoningLayerClient = class {
     const generatedGuardrail = encodePathParams(new Guardrail(generatedHttp));
     const generatedAgui = encodePathParams(new Agui(generatedHttp));
     const generatedOntologyExport = encodePathParams(new OntologyExport(generatedHttp));
+    const generatedArgumentation = encodePathParams(new Argumentation(generatedHttp));
     this.sorts = new SortsClient(generatedSorts, generatedTypes, resolved.tenantId);
     this.terms = new TermsClient(generatedTerms);
     this.inference = new InferenceClient(generatedInference, resolved.tenantId);
@@ -50802,6 +51650,7 @@ var ReasoningLayerClient = class {
     this.guardrail = new GuardrailClient(generatedGuardrail);
     this.agui = new AguiClient(generatedAgui);
     this.ontologyExport = new OntologyExportClient(generatedOntologyExport);
+    this.argumentation = new ArgumentationClient(generatedArgumentation);
     this.demo = new DemoClient(encodePathParams(new Demo(generatedHttp)));
     this.reward = new RewardClient(encodePathParams(new Reward(generatedHttp)));
     this.translation = new TranslationClient(
@@ -51133,6 +51982,9 @@ var speech_exports = {};
 // src/types/connectors.ts
 var connectors_exports = {};
 
+// src/types/argumentation.ts
+var argumentation_exports = {};
+
 // src/types/cron.ts
 var cron_exports = {};
 
@@ -52743,6 +53595,7 @@ exports.Agui = agui_exports;
 exports.Analysis = analysis_exports;
 exports.Anonymization = anonymization_exports;
 exports.ApiError = ApiError;
+exports.Argumentation = argumentation_exports;
 exports.Audit = audit_exports;
 exports.AuthenticationError = AuthenticationError;
 exports.Authz = authz_exports;
@@ -52808,6 +53661,7 @@ exports.LTN = ltn_exports;
 exports.Marketplace = marketplace_exports;
 exports.Memory = memory_exports;
 exports.Metrics = metrics_exports;
+exports.NamedConstraintViolationError = NamedConstraintViolationError;
 exports.Namespaces = namespaces_exports;
 exports.NetworkError = NetworkError;
 exports.NeuroSymbolic = neuro_symbolic_exports;