@kortexya/reasoninglayer 1.28.0 → 2.0.0

package/README.md

@@ -186,16 +186,31 @@ browser code that has already gone through the platform's login flow.
 
 ## Response Metadata
 
+A resource method resolves to the parsed body alone. To see a **successful**
+response's status, headers or rate-limit budget, register an interceptor — it
+wraps every request the client makes.
+
 ```typescript
-// Default: returns data directly
-const sort = await client.sorts.createSort({ name: 'person' });
+const client = new ReasoningLayerClient({
+  baseUrl: 'https://platform.ovh.reasoninglayer.ai',
+  tenantId: 'your-tenant-uuid',
+  auth: { mode: 'cookie' },
+  interceptors: [
+    async (request, next) => {
+      const response = await next(request);
+      console.log(response.status);                              // 201
+      console.log(response.headers.get('x-ratelimit-remaining')); // '99'
+      return response;
+    },
+  ],
+});
 
-// With metadata: returns { data, status, headers, rateLimit }
-const result = await client.sorts.withMetadata().createSort({ name: 'person' });
-console.log(result.status);    // 201
-console.log(result.rateLimit); // { limit, remaining, retryAfter }
+const sort = await client.sorts.createSort({ name: 'person' });
 ```
 
+On a **failure**, the thrown `ApiError` carries `status` and `headers`
+directly — see Error Handling below.
+
 ## Error Handling
 
 ```typescript
@@ -227,23 +242,28 @@ try {
 The SDK provides builder functions for constructing API request values with full type safety:
 
 ```typescript
-import { Value, FeatureInput, TermInput, guard, allen, SortBuilder, psi, LP } from '@kortexya/reasoninglayer';
+import { Value, FuzzyShape, guard, constrained, allen, SortBuilder, psi, LP } from '@kortexya/reasoninglayer';
 
-// Tagged values (term CRUD)
-Value.string('hello')           // { type: 'String', value: 'hello' }
-Value.integer(42)               // { type: 'Integer', value: 42 }
-Value.fuzzyNumber('triangular', { a: 20, b: 22, c: 24 })
+// Tagged values (term CRUD). A plain scalar needs no builder — the resource
+// methods tag it for you. `Value.*` is for the shapes a scalar cannot express.
+const features = { name: 'hello', age: 42 };       // tagged on the way to the wire
+Value.reference('550e8400-e29b-41d4-a716-446655440000')
+                                // { type: 'Reference', value: '550e8400-…' }
+Value.fuzzyNumber(FuzzyShape.triangular(20, 22, 24))
+                                // { type: 'FuzzyNumber', value: { kind: 'Triangular', … } }
 
-// Untagged values (inference)
-FeatureInput.string('hello')    // 'hello'
-FeatureInput.variable('X')      // { name: 'X' }
-FeatureInput.constrainedVar('S', { op: 'gt', value: 80000 })
+// Untagged values (inference). `psi()` writes them: a scalar stays a scalar,
+// and a '?Name' string becomes a logic variable.
+psi('employee', { name: '?Name', department: 'Engineering' })
+                                // { sortName: 'employee', features: { name: { name: '?Name' }, … } }
 
-// Guard constraints
-guard('gt', 100)                // { guard: { op: 'gt', value: 100 } }
+// Guard constraints — a guard is itself a Ψ-term
+guard('gt', 100)                // { sortName: 'guard_constraint', features: { op: 'gt', right: 100 } }
+constrained('?Salary', guard('gt', 80000))
 
 // Allen temporal relations
-allen('before')                 // { allen: 'before' }
+allen('before', '?Employment', intervalTermId)
+                                // { type: 'Allen', intervalA: '?Employment', … }
 
 // LP optimization
 LP.maximize({ x: 3, y: 5 })    // objective function

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "1.28.0";
+var SDK_VERSION = "2.0.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -1164,11 +1164,11 @@ var Sorts = class {
     ...params
   });
   /**
-   * @description Per Definition IV.5 (Milanese & Pasi, IEEE TFS 2024 — CC-BY manuscript in reasoninglayer-sources/pdf_sources/), verbatim: ≺∼· ≝ ((≺∼ .− ∼) ⊍ ⪯)⊕ The combined chain preorder ≺∼ of Definition IV.1 with every DIRECTLY-similar pair deleted (`.−` zeroes the pair — it is not an arithmetic difference), the crisp order unioned back, and the result re-closed. A chain survives when its ENDPOINTS are not directly similar: slasher ⪯ horror ∼₀.₅ thriller keeps 0.5 while (horror, thriller) itself answers 0 — two similar sorts meet through their GLB instead (Fig. 4c: horror ⩏ thriller = slasher). The combined ≺∼ — where a direct ∼ edge IS a step; the coarse retrieval mode of Example V.4 — backs equivalence classes and term substitutability internally. (History: the differencing form here is ORIGINAL and faithful; #203 swapped in the combined semantics, and a 2026-08-23 pass re-documented that as correct from secondary sources. The accepted manuscript settled it the other way.)
+   * @description Omitted, the answer is Def. IV.5 `≾̇` — the default because that is the relation the graded GLB and term substitutability are computed from. `granularity: "combined"` answers Def. IV.1 `≺∼`, where a similarity edge IS a step, so a directly-similar pair reads its similarity degree instead of the `0` the pair deletion gives it. A caller asking "how close are these two sorts" wants the second; a caller asking "does this sort substitute for that one" wants the first (#282). Per Definition IV.5 (Milanese & Pasi, IEEE TFS 2024 — CC-BY manuscript in reasoninglayer-sources/pdf_sources/), verbatim: ≺∼· ≝ ((≺∼ .− ∼) ⊍ ⪯)⊕ The combined chain preorder ≺∼ of Definition IV.1 with every DIRECTLY-similar pair deleted (`.−` zeroes the pair — it is not an arithmetic difference), the crisp order unioned back, and the result re-closed. A chain survives when its ENDPOINTS are not directly similar: slasher ⪯ horror ∼₀.₅ thriller keeps 0.5 while (horror, thriller) itself answers 0 — two similar sorts meet through their GLB instead (Fig. 4c: horror ⩏ thriller = slasher). The combined ≺∼ — where a direct ∼ edge IS a step; the coarse retrieval mode of Example V.4 — backs equivalence classes and term substitutability internally. (History: the differencing form here is ORIGINAL and faithful; #203 swapped in the combined semantics, and a 2026-08-23 pass re-documented that as correct from secondary sources. The accepted manuscript settled it the other way.)
    *
    * @tags sorts
    * @name GetPreorderDegree
-   * @summary Get preorder degree ≾̇(s₁, s₂) between two sorts
+   * @summary Get the preorder degree between two sorts, in either of the paper's two readings — `granularity` selects which, exactly as `GET /api/v1/sorts/quotient-order` does, and the answer echoes it back.
    * @request POST:/api/v1/sorts/preorder-degree
    */
   getPreorderDegree = (data, params = {}) => this.http.request({
@@ -1869,7 +1869,7 @@ var Inference = class {
     ...params
   });
   /**
-   * @description # TRUE HOMOICONIC API Request contains a goal term and optional constraints. Response returns solutions with term-based substitutions. ## Temporal Reasoning Use constraints to filter by temporal relations: ```json { "goal": {"sort_name": "Employment", "features": {"valid_to": {"name": "?EndTime"}}}, "constraints": [{"type": "Guard", "left": "?EndTime", "op": "lt", "right": "1583020800000"}] } ``` ## Reading a solution `solutions[].proof.kind` says how the goal was established, and is always present: `proved` (a rule was applied — either it fired in this search, or the goal was a conclusion a forward chain had materialised and the engine recovered the rule from its recorded derivation, so `rule_term_id` and `rule_label` are filled), `fact` (a stored fact with no recorded derivation), `residuated` (an open-world leaf: unknown, never false), `unattributed` (a sound answer whose derivation the engine could not report). A client never has to infer this from the node's shape. A goal that carries `constraints` is a CONJUNCTION: its root node holds one subproof per clause and reports the strongest kind the clauses carry — `proved` when any clause was proved by a rule, else `fact`. `solutions[].substitution.bindings` carries one entry per query variable the engine resolved. A variable left unresolved is ABSENT; it is never bound to itself. # Authorization Requires X-Tenant-Id header. Traced: this is the path the zanzibar gateway hits for every permission check, so it is where an end-to-end trace either explains a slow request or does not. `skip_all` because the request body can be large and has no business in a span attribute.
+   * @description # TRUE HOMOICONIC API Request contains a goal term and optional constraints. Response returns solutions with term-based substitutions. ## Temporal Reasoning Use constraints to filter by temporal relations: ```json { "goal": {"sort_name": "Employment", "features": {"valid_to": {"name": "?EndTime"}}}, "constraints": [{"type": "Guard", "left": "?EndTime", "op": "lt", "right": "1583020800000"}] } ``` ## Reading a solution `solutions[].proof.kind` says how the goal was established, and is always present: `proved` (a rule was applied — either it fired in this search, or the goal was a conclusion a forward chain had materialised and the engine recovered the rule from its recorded derivation, so `rule_term_id` and `rule_label` are filled), `fact` (a stored fact with no recorded derivation), `residuated` (an open-world leaf: unknown, never false), `unattributed` (a sound answer whose derivation the engine could not report). A client never has to infer this from the node's shape. A goal that carries `constraints` is a CONJUNCTION: its root node holds one subproof per clause and reports the strongest kind the clauses carry — `proved` when any clause was proved by a rule, else `fact`. `solutions[].substitution.bindings` carries one entry per query variable the engine resolved. A variable left unresolved is ABSENT; it is never bound to itself. ## Joining a proof to the thing it proves `proof.goal_term_id` is the TermId of the CONCLUSION the node proved. It joins to `POST /api/v1/query/by-sort` and `GET /api/v1/terms/{id}`, and two solutions of one goal share it only when they prove the same conclusion. It is ABSENT when there is no such id — a goal proved without a preceding `CHAIN` materialised no conclusion, and a derivation replayed from a persistent store cannot be attributed to one. A client falls back deliberately there rather than by accident. `proof.rule_head_term_id` names the rule's instantiated HEAD on a rule application, when it differs from the conclusion. ⛔ It is rule scaffolding: `GET /api/v1/terms/{id}` refuses it deliberately (#192). It is a grouping key, not a fetchable id. # Authorization Requires X-Tenant-Id header. Traced: this is the path the zanzibar gateway hits for every permission check, so it is where an end-to-end trace either explains a slow request or does not. `skip_all` because the request body can be large and has no business in a span attribute.
    *
    * @tags inference
    * @name BackwardChain
@@ -13670,19 +13670,56 @@ function BulkSetSimilaritiesResponseFromApiToFront(dto) {
     errors: dto.errors
   };
 }
+var SORT_PREORDER_GRANULARITIES = [
+  "similarity_deleted",
+  "combined"
+];
+function toSortPreorderGranularity(value) {
+  const known = SORT_PREORDER_GRANULARITIES.find((candidate) => candidate === value);
+  if (known === void 0) {
+    throw new ValidationError(
+      `Unknown preorder granularity "${value}" \u2014 expected ${SORT_PREORDER_GRANULARITIES.join(" or ")}.`
+    );
+  }
+  return known;
+}
 function GetPreorderDegreeRequestFromFrontToApi(model) {
   return {
     sort1_id: model.sort1Id,
-    sort2_id: model.sort2Id
+    sort2_id: model.sort2Id,
+    granularity: model.granularity
   };
 }
 function GetPreorderDegreeResponseFromApiToFront(dto) {
   return {
     sort1Id: dto.sort1_id,
     sort2Id: dto.sort2_id,
+    degree: dto.degree,
+    granularity: toSortPreorderGranularity(dto.granularity)
+  };
+}
+function QuotientClassFromApiToFront(dto) {
+  return {
+    sortIds: dto.sort_ids,
+    size: dto.size,
+    alpha: dto.alpha
+  };
+}
+function QuotientOrderEdgeFromApiToFront(dto) {
+  return {
+    from: dto.from,
+    to: dto.to,
     degree: dto.degree
   };
 }
+function GetQuotientOrderResponseFromApiToFront(dto) {
+  return {
+    granularity: toSortPreorderGranularity(dto.granularity),
+    classes: dto.classes.map(QuotientClassFromApiToFront),
+    count: dto.count,
+    orderEdges: dto.order_edges.map(QuotientOrderEdgeFromApiToFront)
+  };
+}
 function EquivalenceClassFromApiToFront(dto) {
   return {
     sortIds: dto.sort_ids,
@@ -14529,13 +14566,32 @@ var SortsClient = class {
   /**
    * Compute the preorder degree between two sorts.
    *
-   * @param request - Sort pair to compute preorder degree for.
-   * @returns The preorder degree response including sort IDs and degree.
-   * @throws {@link ApiError} If the sorts do not exist.
-   *
-   * @remarks
-   * Per Definition IV.5 (Milanese and Pasi 2024), the combined preorder is:
-   * `preorder_dot = ((similarity - subsumption) union subsumption)^+`
+   * @param request - Sort pair to compute preorder degree for, and optionally
+   * which of the two preorders to read it from.
+   * @returns The preorder degree response including sort IDs, degree, and the
+   * granularity the degree was read from.
+   * @throws {@link ApiError} If the sorts do not exist, or if `granularity`
+   * carries a spelling the engine does not accept.
+   * @throws {@link ValidationError} If the engine answers a granularity this
+   * SDK version does not know.
+   *
+   * @remarks
+   * Per Definition IV.5 (Milanese and Pasi, IEEE TFS 2024), the dotted preorder
+   * is `preorder_dot = ((combined_preorder .- similarity) union subsumption)^+`,
+   * where `.-` DELETES each directly-similar pair — it is NOT an arithmetic
+   * difference. So a directly-similar pair answers `0` under the default
+   * granularity: two similar sorts meet through their GLB, not through each
+   * other.
+   *
+   * `granularity` selects the reading, with the same two spellings
+   * `GET /api/v1/sorts/quotient-order` uses:
+   * - omitted or `similarity_deleted` — Definition IV.5, the default, and the
+   *   relation the graded GLB and term substitutability are computed from.
+   * - `combined` — Definition IV.1, where a similarity edge IS a step, so a
+   *   directly-similar pair answers its similarity degree.
+   *
+   * The response always echoes the granularity back, so a `0.0` is never
+   * ambiguous between "no path" and "the pair deletion zeroed it".
    *
    * Degree interpretation:
    * - 1.0 = subsumption (sort1 <= sort2)
@@ -14546,17 +14602,78 @@ var SortsClient = class {
    *
    * @example
    * ```typescript
-   * const result = await client.sorts.getPreorderDegree({
+   * const strict = await client.sorts.getPreorderDegree({
    *   sort1Id: 'uuid-1',
    *   sort2Id: 'uuid-2',
    * });
-   * console.log(result.degree); // 0.72
+   * console.log(strict.degree, strict.granularity); // 0 'similarity_deleted'
+   *
+   * const coarse = await client.sorts.getPreorderDegree({
+   *   sort1Id: 'uuid-1',
+   *   sort2Id: 'uuid-2',
+   *   granularity: 'combined',
+   * });
+   * console.log(coarse.degree, coarse.granularity); // 0.5 'combined'
    * ```
    */
   async getPreorderDegree(request, requestOptions) {
     const response = await this.sorts.getPreorderDegree(GetPreorderDegreeRequestFromFrontToApi(request), toRequestParams(requestOptions));
     return GetPreorderDegreeResponseFromApiToFront(response.data);
   }
+  /**
+   * Get the Definition IV.9 quotient order over the caller's own lattice.
+   *
+   * @param options - Which of the two fuzzy preorders to quotient. Omitted
+   * means `combined`, the engine's default HERE.
+   * @returns The equivalence classes with their degrees, and the fuzzy partial
+   * order between them.
+   * @throws {@link ApiError} 400 when `granularity` carries a spelling the
+   * engine does not accept.
+   * @throws {@link ValidationError} If the engine answers a granularity this
+   * SDK version does not know.
+   *
+   * @remarks
+   * This is the tenant-scoped companion of
+   * {@link SortsClient.getEquivalenceClasses}: the classes, degrees and order
+   * describe exactly the sorts the caller can see, where the older
+   * equivalence-classes route computes process-wide and then filters. Prefer
+   * this one.
+   *
+   * ⚠️ The default granularity here is `combined`, NOT the
+   * `similarity_deleted` default of {@link SortsClient.getPreorderDegree}. The
+   * two routes take the same two spellings and disagree on which is the
+   * default, so state it when it matters. The response echoes it back either
+   * way.
+   *
+   * `orderEdges` is SPARSE and indexes into `classes`: a pair with no edge has
+   * degree `0`. The order is a partial order — antisymmetric, unlike either
+   * preorder it is built from.
+   *
+   * Uses tagged serialization format.
+   *
+   * @example
+   * ```typescript
+   * const quotient = await client.sorts.getQuotientOrder({
+   *   granularity: 'similarity_deleted',
+   * });
+   *
+   * for (const cls of quotient.classes) {
+   *   console.log(`class of ${cls.size} sorts, degree ${cls.alpha}`);
+   * }
+   * for (const edge of quotient.orderEdges) {
+   *   const lower = quotient.classes[edge.from];
+   *   const upper = quotient.classes[edge.to];
+   *   console.log(`${lower.sortIds} <= ${upper.sortIds} at ${edge.degree}`);
+   * }
+   * ```
+   */
+  async getQuotientOrder(options, requestOptions) {
+    const response = await this.sorts.getQuotientOrder(
+      { granularity: options?.granularity },
+      toRequestParams(requestOptions)
+    );
+    return GetQuotientOrderResponseFromApiToFront(response.data);
+  }
   /**
    * Get equivalence classes based on the combined preorder.
    *
@@ -14564,8 +14681,16 @@ var SortsClient = class {
    * @throws {@link ApiError} If the lattice cannot be computed.
    *
    * @remarks
-   * Per Definition IV.9 (Milanese and Pasi 2024):
-   * s1 ~ s2 iff preorder_dot(s1, s2) > 0 AND preorder_dot(s2, s1) > 0.
+   * Per Definition IV.9 (Milanese and Pasi 2024), two sorts are equivalent when
+   * each reaches the other: `s1 ~ s2` iff `preorder(s1, s2) > 0` AND
+   * `preorder(s2, s1) > 0`. The preorder here is the COMBINED one, where a
+   * similarity edge is itself a step — not the `similarity_deleted` default of
+   * {@link SortsClient.getPreorderDegree}.
+   *
+   * ⚠️ This route computes PROCESS-WIDE and then filters, so its classes can
+   * be shaped by sorts the caller cannot see. {@link SortsClient.getQuotientOrder}
+   * computes on the tenant-visible hierarchy instead, returns the same classes
+   * with their degrees, and adds the partial order between them. Prefer it.
    *
    * Uses tagged serialization format.
    *
@@ -15872,6 +15997,7 @@ function ProofDtoFromApiToFront(dto) {
     kind: dto.kind,
     goalTermId: dto.goal_term_id,
     ruleTermId: dto.rule_term_id,
+    ruleHeadTermId: dto.rule_head_term_id,
     goalDisplay: dto.goal_display,
     ruleLabel: dto.rule_label,
     substitution: HomoiconicSubstitutionDtoFromApiToFront(dto.substitution),
@@ -16751,6 +16877,14 @@ var InferenceClient = class {
    *
    * The `timeout_ms` field on the request is a wall-clock timeout for the search.
    * When it fires, the backend returns whatever solutions have been found so far.
+   *
+   * To join a proof node to the thing it proves, read `proof.goalTermId` — the
+   * conclusion's term ID, which `client.terms.getTerm()` and
+   * `client.query.findBySort()` both answer for. It is OPTIONAL: a goal proved
+   * without a preceding forward chain materialises no conclusion, so the node
+   * carries no id and `proof.goalDisplay` renders it instead. Do not read
+   * `proof.ruleHeadTermId` as a fetchable id — it names the rule's instantiated
+   * head, which the term routes refuse.
    */
   async backwardChain(request, requestOptions) {
     const wireRequest = {
@@ -16854,13 +16988,37 @@ var InferenceClient = class {
   /**
    * Run negation-as-failure (NAF) proof search.
    *
-   * @param request - NAF prove request.
+   * @param request - NAF prove request. Each literal's `term` takes a
+   * {@link psi} term or a wire {@link TermInputDto}, like every other
+   * term-carrying method.
    * @returns NAF proof result.
    *
+   * @remarks
+   * Uses the untagged (homoiconic) serialization format: a literal's features
+   * are plain scalars and `"?Var"` strings.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.inference.nafProve({
+   *   literals: [
+   *     { term: psi('employee', { name: '?Name' }) },
+   *     { term: psi('senior_engineer', { name: '?Name' }), negated: true },
+   *   ],
+   *   maxSolutions: 10,
+   * });
+   * ```
+   *
    * @see proveWithNegation — friendlier alias for this method.
    */
   async nafProve(request, requestOptions) {
-    const response = await this.api.nafProve(NafProveRequestFromFrontToApi(request), toRequestParams(requestOptions));
+    const wireRequest = {
+      ...request,
+      literals: request.literals?.map((literal) => ({
+        ...literal,
+        term: convertTermArg(literal.term)
+      }))
+    };
+    const response = await this.api.nafProve(NafProveRequestFromFrontToApi(wireRequest), toRequestParams(requestOptions));
     return NafProveResponseFromApiToFront(response.data);
   }
   /**