@kortexya/reasoninglayer 2.0.0 → 2.1.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "2.0.0";
+var SDK_VERSION = "2.1.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -15871,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 } : {}
@@ -15906,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 };
   }
@@ -15928,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;
@@ -16497,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
   };
@@ -16514,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) {
@@ -16532,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) {
@@ -16554,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,
@@ -16577,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
   };
@@ -23945,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) {
@@ -23959,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) {
@@ -25550,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) {
@@ -25575,6 +25605,7 @@ function DiscoverableTypeDtoFromApiToFront(dto) {
   return {
     comment: dto.comment,
     estimatedRows: dto.estimated_rows,
+    columnCount: dto.column_count,
     name: dto.name
   };
 }
@@ -25585,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,
@@ -25592,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) {
@@ -31445,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);
@@ -32124,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
@@ -32195,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);
@@ -32220,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;
@@ -32343,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
@@ -32379,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.
@@ -32422,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.
@@ -34361,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,
@@ -34370,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) {
@@ -36596,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,
@@ -36854,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.
    *
@@ -39099,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) {
@@ -39142,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({
@@ -39153,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' }]
    *   }
    * }
    * ```