@kortexya/reasoninglayer 1.28.0 → 2.1.0

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.1.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(strict.degree, strict.granularity); // 0 'similarity_deleted'
+   *
+   * const coarse = await client.sorts.getPreorderDegree({
    *   sort1Id: 'uuid-1',
    *   sort2Id: 'uuid-2',
+   *   granularity: 'combined',
    * });
-   * console.log(result.degree); // 0.72
+   * 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.
    *
@@ -15746,31 +15871,42 @@ function convertFeatures(features) {
 }
 
 // src/normalizers/homoiconic.ts
-function FeatureInputValueDtoFromFrontToApi(value) {
+function assertPresent(value, what) {
+  if (value === null || value === void 0) {
+    throw new ValidationError(
+      `${what} is required \u2014 received ${value === null ? "null" : "undefined"}.`,
+      what
+    );
+  }
+}
+function FeatureInputValueDtoFromFrontToApi(value, path = "feature value") {
+  assertPresent(value, path);
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
     return value;
   }
   if (Array.isArray(value)) {
-    return value.map(FeatureInputValueDtoFromFrontToApi);
+    return value.map(
+      (element, index) => FeatureInputValueDtoFromFrontToApi(element, `${path}[${index}]`)
+    );
   }
   if ("name" in value && "constraint" in value) {
     return {
       name: value.name,
-      constraint: TermInputDtoFromFrontToApi(value.constraint)
+      constraint: TermInputDtoFromFrontToApi(value.constraint, `${path}.constraint`)
     };
   }
   if ("name" in value) {
     return { name: value.name };
   }
   if ("sortId" in value) {
-    const features = value.features ? featuresInputFromFrontToApi(value.features) : void 0;
+    const features = value.features ? featuresInputFromFrontToApi(value.features, `${path}.features`) : void 0;
     return {
       sort_id: value.sortId,
       ...features ? { features } : {}
     };
   }
   if ("sortName" in value) {
-    const features = value.features ? featuresInputFromFrontToApi(value.features) : void 0;
+    const features = value.features ? featuresInputFromFrontToApi(value.features, `${path}.features`) : void 0;
     return {
       sort_name: value.sortName,
       ...features ? { features } : {}
@@ -15781,14 +15917,15 @@ function FeatureInputValueDtoFromFrontToApi(value) {
   }
   return { term_id: value.termId };
 }
-function featuresInputFromFrontToApi(features) {
+function featuresInputFromFrontToApi(features, path = "features") {
   const result = {};
   for (const [key, val] of Object.entries(features)) {
-    result[key] = FeatureInputValueDtoFromFrontToApi(val);
+    result[key] = FeatureInputValueDtoFromFrontToApi(val, `${path}.${key}`);
   }
   return result;
 }
-function TermInputDtoFromFrontToApi(model) {
+function TermInputDtoFromFrontToApi(model, path = "term") {
+  assertPresent(model, path);
   if ("termId" in model) {
     return { term_id: model.termId };
   }
@@ -15803,14 +15940,14 @@ function TermInputDtoFromFrontToApi(model) {
   if ("sortId" in model) {
     const inline = {
       sort_id: model.sortId,
-      features: featuresInputFromFrontToApi(model.features)
+      features: featuresInputFromFrontToApi(model.features, `${path}.features`)
     };
     if (model.binding !== void 0) inline.binding = model.binding;
     return inline;
   }
   const byName = {
     sort_name: model.sortName,
-    features: model.features ? featuresInputFromFrontToApi(model.features) : void 0
+    features: model.features ? featuresInputFromFrontToApi(model.features, `${path}.features`) : void 0
   };
   if (model.binding !== void 0) byName.binding = model.binding;
   return byName;
@@ -15872,6 +16009,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),
@@ -16371,7 +16509,9 @@ function RuleAggregatorDtoFromFrontToApi(model) {
 function AddRuleRequestFromFrontToApi(model) {
   return {
     term: TermInputDtoFromFrontToApi(model.term),
-    antecedents: model.antecedents?.map(TermInputDtoFromFrontToApi),
+    antecedents: model.antecedents?.map(
+      (t, i) => TermInputDtoFromFrontToApi(t, `antecedents[${i}]`)
+    ),
     certainty: model.certainty,
     aggregator: model.aggregator ? RuleAggregatorDtoFromFrontToApi(model.aggregator) : model.aggregator
   };
@@ -16388,7 +16528,7 @@ function BulkAddRulesRequestFromFrontToApi(model) {
 }
 function BulkAddFactsRequestFromFrontToApi(model) {
   return {
-    facts: model.facts.map(TermInputDtoFromFrontToApi)
+    facts: model.facts.map((t, i) => TermInputDtoFromFrontToApi(t, `facts[${i}]`))
   };
 }
 function BackwardChainRequestFromFrontToApi(model) {
@@ -16406,12 +16546,15 @@ function BackwardChainRequestFromFrontToApi(model) {
 }
 function ForwardChainRequestFromFrontToApi(model) {
   return {
-    initial_facts: model.initialFacts?.map(TermInputDtoFromFrontToApi),
+    initial_facts: model.initialFacts?.map(
+      (t, i) => TermInputDtoFromFrontToApi(t, `initialFacts[${i}]`)
+    ),
     keep_derived: model.keepDerived,
     enable_provenance_tags: model.enableProvenanceTags,
     max_iterations: model.maxIterations,
     max_facts: model.maxFacts,
-    emit_provenance: model.emitProvenance
+    emit_provenance: model.emitProvenance,
+    timeout_ms: model.timeoutMs ?? void 0
   };
 }
 function FuzzyProveRequestFromFrontToApi(model) {
@@ -16428,7 +16571,7 @@ function FuzzyProveRequestFromFrontToApi(model) {
 }
 function BulkFuzzyProveRequestFromFrontToApi(model) {
   return {
-    goals: model.goals?.map(TermInputDtoFromFrontToApi),
+    goals: model.goals?.map((t, i) => TermInputDtoFromFrontToApi(t, `goals[${i}]`)),
     goal_ids: model.goalIds ?? void 0,
     max_depth: model.maxDepth,
     min_degree: model.minDegree,
@@ -16451,7 +16594,7 @@ function BayesianPredictRequestFromFrontToApi(model) {
 }
 function CreateGoalRequestFromFrontToApi(model) {
   return {
-    clauses: model.clauses.map(TermInputDtoFromFrontToApi),
+    clauses: model.clauses.map((t, i) => TermInputDtoFromFrontToApi(t, `clauses[${i}]`)),
     constraints: model.constraints?.map(ConstraintInputDtoFromFrontToApi),
     min_degree: model.minDegree ?? void 0
   };
@@ -16751,6 +16894,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 +17005,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);
   }
   /**
@@ -23787,7 +23962,7 @@ function EntailmentRequestFromFrontToApi(model) {
   return {
     antecedent: TermInputDtoFromFrontToApi(model.antecedent),
     consequent: TermInputDtoFromFrontToApi(model.consequent),
-    facts: model.facts?.map(TermInputDtoFromFrontToApi)
+    facts: model.facts?.map((t, i) => TermInputDtoFromFrontToApi(t, `facts[${i}]`))
   };
 }
 function EntailmentResponseFromApiToFront(dto) {
@@ -23801,7 +23976,7 @@ function DisentailmentRequestFromFrontToApi(model) {
   return {
     antecedent: TermInputDtoFromFrontToApi(model.antecedent),
     consequent: TermInputDtoFromFrontToApi(model.consequent),
-    facts: model.facts?.map(TermInputDtoFromFrontToApi)
+    facts: model.facts?.map((t, i) => TermInputDtoFromFrontToApi(t, `facts[${i}]`))
   };
 }
 function DisentailmentResponseFromApiToFront(dto) {
@@ -25392,12 +25567,25 @@ function SourceDetailResponseFromApiToFront(dto) {
     supportedModes: dto.supported_modes
   };
 }
+function ConfigFieldDtoFromApiToFront(dto) {
+  return {
+    // `name` is the factory's own JSON key and goes back on the wire
+    // verbatim — never camelCased, in either direction (#14).
+    name: dto.name,
+    type: dto.type,
+    required: dto.required
+  };
+}
 function SourceTypeDtoFromApiToFront(dto) {
   return {
     sourceType: dto.source_type,
     aliases: dto.aliases,
     available: dto.available,
-    supportedModes: dto.supported_modes
+    supportedModes: dto.supported_modes,
+    // Defaulted rather than left absent: the field is required on the current
+    // engine, and an empty list reads correctly on an older one — a form built
+    // from no fields is visibly empty, where an absent list is a crash.
+    configFields: (dto.config_fields ?? []).map(ConfigFieldDtoFromApiToFront)
   };
 }
 function ListSourceTypesResponseFromApiToFront(dto) {
@@ -25417,6 +25605,7 @@ function DiscoverableTypeDtoFromApiToFront(dto) {
   return {
     comment: dto.comment,
     estimatedRows: dto.estimated_rows,
+    columnCount: dto.column_count,
     name: dto.name
   };
 }
@@ -25427,6 +25616,15 @@ function ListTablesResponseFromApiToFront(dto) {
     total: dto.total
   };
 }
+function KeyProvenanceDtoFromApiToFront(dto) {
+  return {
+    source: dto.source,
+    chosenBy: dto.chosen_by,
+    explanation: dto.explanation,
+    guaranteedUnique: dto.guaranteed_unique,
+    durability: dto.durability
+  };
+}
 function DiscoveredFeatureDtoFromApiToFront(dto) {
   return {
     constraints: dto.constraints,
@@ -25434,10 +25632,16 @@ function DiscoveredFeatureDtoFromApiToFront(dto) {
     isIdentifier: dto.is_identifier,
     isRelation: dto.is_relation,
     name: dto.name,
+    // The engine's own OSFQL-readable spelling. Defaulted to `name`, which it
+    // is identical to, so an older engine that predates it stays usable.
+    featureName: dto.feature_name ?? dto.name,
     relationTarget: dto.relation_target,
     required: dto.required,
     sourceName: dto.source_name,
-    typeHint: dto.type_hint
+    typeHint: dto.type_hint,
+    // The difference between a declared primary key and a guess. Carried
+    // through so a mapping wizard can present the guess as a guess (#14).
+    identifierProvenance: dto.identifier_provenance ? KeyProvenanceDtoFromApiToFront(dto.identifier_provenance) : dto.identifier_provenance
   };
 }
 function DiscoveredSortDtoFromApiToFront(dto) {
@@ -31287,7 +31491,9 @@ var OptimizeClient = class {
       }
       const ruleResponse = await this.inferenceApi.addRule({
         term: TermInputDtoFromFrontToApi(compiled.solutionTerm),
-        antecedents: compiled.antecedents.map(TermInputDtoFromFrontToApi),
+        antecedents: compiled.antecedents.map(
+          (t, i) => TermInputDtoFromFrontToApi(t, `antecedents[${i}]`)
+        ),
         certainty: 1
       }, toRequestParams(requestOptions));
       ruleTermId = extractRuleTermId(ruleResponse.data);
@@ -31966,6 +32172,7 @@ function OsfqlResponseFromApiToFront(dto) {
     bindings,
     fetched,
     producedTermIds: dto.produced_term_ids,
+    updatedTermIds: dto.updated_term_ids,
     definedSortIds: dto.defined_sort_ids,
     diagnostics: dto.diagnostics,
     statementCount: dto.statement_count
@@ -32037,11 +32244,25 @@ function OsfqlPreviewAffectedFromApiToFront(dto) {
     affected.exact = dto.exact;
   }
   if (dto.sample_rows !== void 0) {
-    const rows = OsfqlBindingsFromApiToFront(dto.sample_rows);
-    if (rows === void 0) {
-      return void 0;
+    const rows = [];
+    let unparsed = 0;
+    const wireRows = dto.sample_rows;
+    if (Array.isArray(wireRows)) {
+      for (const row of wireRows) {
+        const parsed = OsfqlBindingFromApiToFront(row);
+        if (parsed === void 0) {
+          unparsed += 1;
+        } else {
+          rows.push(parsed);
+        }
+      }
+    } else {
+      unparsed = 1;
     }
     affected.sampleRows = rows;
+    if (unparsed > 0) {
+      affected.unparsedSampleRows = unparsed;
+    }
   }
   if (dto.by_sort !== void 0) {
     affected.bySort = dto.by_sort.map(OsfqlPreviewSortCountFromApiToFront);
@@ -32062,34 +32283,15 @@ function OsfqlPreviewStatementFromApiToFront(dto) {
     source: dto.source
   };
   if (dto.affected !== void 0) {
-    const affected = OsfqlPreviewAffectedFromApiToFront(dto.affected);
-    if (affected === void 0) {
-      return void 0;
-    }
-    statement.affected = affected;
+    statement.affected = OsfqlPreviewAffectedFromApiToFront(dto.affected);
   }
   if (dto.nested !== void 0) {
-    const nested = [];
-    for (const child of dto.nested) {
-      const parsed = OsfqlPreviewStatementFromApiToFront(child);
-      if (parsed === void 0) {
-        return void 0;
-      }
-      nested.push(parsed);
-    }
-    statement.nested = nested;
+    statement.nested = dto.nested.map(OsfqlPreviewStatementFromApiToFront);
   }
   return statement;
 }
 function OsfqlPreviewResponseFromApiToFront(dto) {
-  const statements = [];
-  for (const entry of dto.statements) {
-    const parsed = OsfqlPreviewStatementFromApiToFront(entry);
-    if (parsed === void 0) {
-      return void 0;
-    }
-    statements.push(parsed);
-  }
+  const statements = dto.statements.map(OsfqlPreviewStatementFromApiToFront);
   const response = { mutates: dto.mutates, statements };
   if (dto.atomic_refusal !== void 0) {
     response.atomicRefusal = dto.atomic_refusal ? OsfqlAtomicRefusalFromApiToFront(dto.atomic_refusal) : dto.atomic_refusal;
@@ -32185,8 +32387,6 @@ var OsfqlClient = class {
    *   atomic refusal when there is one.
    * @throws {ApiError} If the program does not parse (HTTP 400, `OsfqlErrorResponse`),
    *   or the request otherwise fails.
-   * @throws {ReasoningLayerError} If a sample row carries a value that does not satisfy
-   *   the published {@link OsfqlValue} contract.
    *
    * @remarks
    * **Why call this instead of classifying the program client-side.** Three
@@ -32221,9 +32421,16 @@ var OsfqlClient = class {
    * Two further measured facts. The top-level `mutates` DOES fold nested
    * statements now: the `IF` program above answers `true`, and so does an `IF`
    * whose only writing branch is the `ELSE` — the earlier defect where an `IF`
-   * with a writing branch answered `false` is fixed. And `affected` being absent
-   * is ambiguous: `RETRACT customer(tier: "bronze")` matching zero rows omits
-   * the field entirely rather than answering `count: 0`, exactly as a read does.
+   * with a writing branch answered `false` is fixed. And `affected` is NOT
+   * ambiguous: a destructive statement that matches zero rows answers
+   * `{count: 0, exact: true}` rather than omitting the block. Measured
+   * 2026-09-21 — `preview('RETRACT widget(name: "nobody");')` against an empty
+   * `widget` answers `affected: {"count":0,"exact":true}`, while
+   * `preview('MATCH widget(name: ?N);')` carries no `affected` key at all. So
+   * an ABSENT block means the statement has no affected-row set; `count: 0`
+   * means the rows were counted and there are none. A confirm dialog can tell
+   * the two apart, which is what the block was separated for. See
+   * {@link OsfqlPreviewAffected.count}.
    *
    * `statement.index` is a single counter over the whole program: an `IF` at
    * index 1 carries nested entries at index 2 and 3.
@@ -32264,13 +32471,7 @@ var OsfqlClient = class {
       OsfqlRequestFromFrontToApi({ ...options, query }),
       toRequestParams(requestOptions)
     );
-    const parsed = OsfqlPreviewResponseFromApiToFront(response.data);
-    if (parsed === void 0) {
-      throw new ReasoningLayerError(
-        "osfql/preview returned an affected sample row that does not match the published OsfqlValue contract (expected tagged values with a lowercase `type` discriminator)"
-      );
-    }
-    return parsed;
+    return OsfqlPreviewResponseFromApiToFront(response.data);
   }
   /**
    * Diagnose an OSFQL program for contradictions and inconsistencies.
@@ -34203,6 +34404,27 @@ function AuditPageFromApiToFront(dto) {
     offset: dto.offset
   };
 }
+function RiskTotalsDtoFromApiToFront(dto) {
+  return {
+    nSafe: dto.n_safe,
+    nWarning: dto.n_warning,
+    nUnsafe: dto.n_unsafe,
+    nUngraded: dto.n_ungraded,
+    nGradedByVerification: dto.n_graded_by_verification,
+    nVerified: dto.n_verified,
+    nRefuted: dto.n_refuted,
+    nAbstained: dto.n_abstained,
+    nFabricationDetected: dto.n_fabrication_detected,
+    nFabricationClean: dto.n_fabrication_clean,
+    nFabricationUnknown: dto.n_fabrication_unknown,
+    nClaimsTotal: dto.n_claims_total,
+    nClaimsRefuted: dto.n_claims_refuted,
+    // Carried through as `null`, never folded to `0`. `null` is "not
+    // measured" — the denominator is checked responses only — and `0` would
+    // report a clean fabrication rate for a ledger nobody checked (#11).
+    fabricationRate: dto.fabrication_rate
+  };
+}
 function SummaryResponseFromApiToFront(dto) {
   const out = {
     nRecords: dto.n_records,
@@ -34212,6 +34434,12 @@ function SummaryResponseFromApiToFront(dto) {
   };
   if (dto.ts_first) out.tsFirst = dto.ts_first;
   if (dto.ts_last) out.tsLast = dto.ts_last;
+  if (dto.risk !== void 0 && dto.risk !== null) {
+    out.risk = RiskTotalsDtoFromApiToFront(dto.risk);
+  }
+  if (dto.n_oversight_decisions !== void 0 && dto.n_oversight_decisions !== null) {
+    out.nOversightDecisions = dto.n_oversight_decisions;
+  }
   return out;
 }
 function VerifyResponseFromApiToFront(dto) {
@@ -36438,6 +36666,23 @@ function ImportOwlResponseFromApiToFront(dto) {
     sortsCreated: dto.sorts_created
   };
 }
+function ExecuteTranspiledRequestFromFrontToApi(model) {
+  return {
+    osfql: model.osfql
+  };
+}
+function ExecuteTranspiledResponseFromApiToFront(dto) {
+  return {
+    // `rows` are the source's OWN records; their keys are its column names and
+    // are data, carried verbatim. The generated type erases them to `any[]`,
+    // so the shipped surface narrows them to one object per row (#12).
+    rows: dto.rows,
+    rowCount: dto.row_count,
+    query: dto.query,
+    dialect: dto.dialect,
+    sourceId: dto.source_id
+  };
+}
 function TranspileRequestFromFrontToApi(model) {
   return {
     dialect: model.dialect,
@@ -36696,6 +36941,46 @@ var OntologyBridgeClient = class {
     );
     return TranspileResponseFromApiToFront(response.data);
   }
+  /**
+   * Transpile an OSFQL query AND run it on the source it is bound to.
+   *
+   * @param request - The OSFQL query. No dialect: the binding names the
+   *   source, and the source's type decides the dialect.
+   * @param requestOptions - Per-call request options.
+   * @returns The rows the source returned, the native query that fetched them,
+   *   its dialect, and the source id.
+   * @throws {ApiError} If the request fails.
+   *
+   * @remarks
+   * Sent to `POST /api/v1/ontology/query`. The response uses the snake_case
+   * wire format (`row_count`, `source_id`); this client normalizes at the
+   * boundary. `rows` are the source's own records, one object per row, and
+   * their KEYS are the source's column names — data, carried verbatim.
+   *
+   * **This is the second half of {@link OntologyBridgeClient.transpile}, and
+   * for a `transpile`-mode source it is the only route that answers.** Such a
+   * source deliberately ingests nothing: its bound sorts are live views over
+   * the operator's own database, so every KB query over them reports no
+   * results. `transpile` emits the native query and stops; this runs it.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.ontologyBridge.executeTranspiled({
+   *   osfql: 'MATCH person(name: ?N);',
+   * });
+   * console.log(result.dialect);   // "postgres"
+   * console.log(result.query);     // the SQL that ran
+   * console.log(result.rowCount);  // 12
+   * for (const row of result.rows) console.log(row['name']);
+   * ```
+   */
+  async executeTranspiled(request, requestOptions) {
+    const response = await this.api.executeTranspiled(
+      ExecuteTranspiledRequestFromFrontToApi(request),
+      toRequestParams(requestOptions)
+    );
+    return ExecuteTranspiledResponseFromApiToFront(response.data);
+  }
   /**
    * Remove a sort-table binding.
    *
@@ -38941,12 +39226,46 @@ function ConformanceRequestFromFrontToApi(model) {
     ontology: model.ontology
   };
 }
+function stringAt(source, key) {
+  const value = Reflect.get(source, key);
+  return typeof value === "string" ? value : void 0;
+}
+function suggestedFixesAt(source) {
+  const value = Reflect.get(source, "suggested_fixes");
+  if (!Array.isArray(value)) return void 0;
+  const fixes = [];
+  for (const entry of value) {
+    if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
+      fixes.push({ ...entry });
+    }
+  }
+  return fixes;
+}
+function ConformanceViolationDtoFromApiToFront(dto) {
+  if (typeof dto !== "object" || dto === null) return {};
+  const violation = {};
+  const subject = stringAt(dto, "subject");
+  if (subject !== void 0) violation.subject = subject;
+  const object = stringAt(dto, "object");
+  if (object !== void 0) violation.object = object;
+  const feature = stringAt(dto, "feature");
+  if (feature !== void 0) violation.feature = feature;
+  const subjectSort = stringAt(dto, "subject_sort");
+  if (subjectSort !== void 0) violation.subjectSort = subjectSort;
+  const objectSort = stringAt(dto, "object_sort");
+  if (objectSort !== void 0) violation.objectSort = objectSort;
+  const kind = stringAt(dto, "kind");
+  if (kind !== void 0) violation.kind = kind;
+  const suggestedFixes = suggestedFixesAt(dto);
+  if (suggestedFixes !== void 0) violation.suggestedFixes = suggestedFixes;
+  return violation;
+}
 function ConformanceCheckResponseFromApiToFront(dto) {
   return {
     conformant: dto.conformant,
     totalViolations: dto.total_violations,
     byKind: ViolationCountsDtoFromApiToFront(dto.by_kind),
-    violations: dto.violations.map(ViolationDtoFromApiToFront)
+    violations: dto.violations.map(ConformanceViolationDtoFromApiToFront)
   };
 }
 function ConformanceRepairResponseFromApiToFront(dto) {
@@ -38984,6 +39303,11 @@ var ConformanceClient = class {
    * The ontology travels as an opaque string in the declared RDF format; no
    * value serialization is applied to it.
    *
+   * Each violation is a {@link ConformanceViolationDto}, NOT the shared
+   * `ViolationDto`. The two share no key, and the route's OpenAPI slot holds
+   * the wrong one — which is why the fields are narrowed from the wire in the
+   * normalizer and why every one of them is optional (#13).
+   *
    * @example
    * ```typescript
    * const result = await client.conformance.check({
@@ -38995,7 +39319,8 @@ var ConformanceClient = class {
    *   console.log(result.totalViolations, 'violations');
    *   console.log(result.byKind.v1Inversion, 'subject/object inversions');
    *   for (const violation of result.violations) {
-   *     console.log(violation.severity, violation.description);
+   *     console.log(violation.kind, violation.subject, violation.feature, violation.object);
+   *     console.log(violation.suggestedFixes); // [{ action: 'swap' }]
    *   }
    * }
    * ```