@kortexya/reasoninglayer 3.1.0 → 3.2.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "3.1.0";
+var SDK_VERSION = "3.2.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -1310,7 +1310,7 @@ var Sorts = class {
     ...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; the gateway's `approve_sort` rule additionally refuses the sort's own proposer.
+   * @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
@@ -1463,7 +1463,7 @@ var Sorts = class {
     ...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.
+   * @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
@@ -8844,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
@@ -9449,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
@@ -16234,8 +16234,10 @@ var SortsClient = class {
    * @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 — including the proposer approving their own candidate, which the
-   *   gateway denies.
+   *   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.
    *
@@ -16244,11 +16246,21 @@ var SortsClient = class {
    * 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
-   * const { sort, wokenResiduations } = await client.sorts.approveSort(sortId, {
-   *   reason: 'Matches the order lifecycle use case',
-   * });
+   * 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) {
@@ -18886,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) {
@@ -18961,9 +18974,16 @@ var InferenceClient = class {
    *   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 — 422 when
-   *   it is unusable as written, including 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).
+   *   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`.
@@ -19613,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
@@ -19856,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,
@@ -20161,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
@@ -31378,6 +31406,14 @@ var ScenariosClient = class {
    * 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 });
@@ -34386,6 +34422,14 @@ 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,
@@ -34395,11 +34439,13 @@ function NegativeExampleDtoFromApiToFront(dto) {
     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.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,
@@ -34676,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(