@kortexya/reasoninglayer 4.0.0 → 4.1.0

package/dist/index.d.cts

@@ -231,7 +231,7 @@ type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | object;
  * This is the single source of truth for the version constant.
  * The `scripts/release.sh` script updates this value alongside `package.json`.
  */
-declare const SDK_VERSION = "4.0.0";
+declare const SDK_VERSION = "4.1.0";
 /**
  * Authentication mode for the SDK.
  *
@@ -22103,16 +22103,24 @@ interface MaterializeScenarioRequest$1 {
      * refused with 409 (#470).
      */
     prefixes?: Partial<Record<string, string>>;
-    /** A GeneratedScenario: the `scenario` payload of POST /api/v1/ontology/generate, or a schema-only scenario built from an imported vocabulary. `sorts`, `beliefs` and `rules` are required (each may be empty). `goal` is optional: a scenario without one materializes no agent_goal term. Every other collection defaults to empty. Keys not listed here are ignored. */
+    /** A GeneratedScenario: the `scenario` payload of POST /api/v1/ontology/generate, or a schema-only scenario built from an imported vocabulary. No key is required: every collection defaults to empty, so a vocabulary import sends `sorts` alone. `goal` is optional: a scenario without one materializes no agent_goal term. Keys not listed here are ignored. */
     scenario: {
-        /** Belief instances (typed facts) to assert. */
-        beliefs: object[];
+        /** OWL 2 class axioms, each `{kind, classes?, class?, property?, n?, filler?}`: `disjoint_classes`, `min_cardinality`, `max_cardinality`, `exact_cardinality` or `all_values_from`. Written as the disjointness rule, feature bound or typed feature the engine enforces; an unknown kind is skipped with a warning. Defaults to empty. */
+        axioms?: object[];
+        /** Belief instances (typed facts) to assert. Defaults to empty. */
+        beliefs?: object[];
+        /** Competency questions, each `{question, use_case?, osfql?, sorts?}`, recorded as `proposed` competency questions. Defaults to empty. */
+        competency_questions?: object[];
+        /** Computed features, each `{sort, feature, function, arguments?, depends_on?, description?}`, declared as feature equations. Defaults to empty. */
+        computed_features?: object[];
         /** Generic constraints, each `{sort, features}`. Defaults to empty. A feature reads the rule feature encoding: a bare "?X" is a variable, as are {"name": "?X"} and {"_var": "?X"}, and one name is one variable across all of `guardConstraints` and `constraints`; a literal that starts with `?` is {"type": "String", "value": "?x"}. A constraint whose feature does not decode is not written and is named in `warnings`. */
         constraints?: object[];
         /** Curriculum stages. Defaults to empty. */
         curriculum_stages?: object[];
         /** Tool registrations. Defaults to empty. */
         discovered_tools?: object[];
+        /** Fluents, each `{name, of_sort, value_values?, event_sort, proposed?, provenance?}`: a fluent sort and its event sort, recorded as append-only state terms. Defaults to empty. */
+        fluents?: object[];
         /** The agent's goal: `{sort, features?, priority?}`. Optional; omit it for a scenario with no agent. `features` reads the rule feature encoding: a bare "?X" is a variable; a literal that starts with `?` is {"type": "String", "value": "?x"}. A feature that does not decode refuses the scenario. */
         goal?: object;
         /** Concept groundings. Defaults to empty. */
@@ -22121,8 +22129,8 @@ interface MaterializeScenarioRequest$1 {
         guardConstraints?: object[];
         /** Engine pipeline stages. Defaults to empty. */
         pipelineStages?: object[];
-        /** Inference rules. Each rule is `{head: {sort, features}, antecedents: [{sort, features, negated?, binding?}], certainty?}`, authored through the rule door of POST /api/v1/inference/rules with its feature encoding and its checks. A bare string that starts with `?` ("?X") is a variable shared across the rule, as are {"name": "?X"} and {"_var": "?X"}; a literal that starts with `?` is written {"type": "String", "value": "?x"}. `negated: true` on an antecedent is negation as failure. A rule the door refuses is not written and is named in `warnings`: a conclusion variable that no antecedent binds, no antecedent, a new cycle through negation, or a feature value the door cannot read. A sort a rule names that `sorts` does not declare is created under `thing` before the rules are authored, so an unknown sort is not refused here (only PATCH /api/v1/scenarios/{id} `add_rules`, which is not normalized, refuses one). */
-        rules: {
+        /** Inference rules. Defaults to empty. Each rule is `{head: {sort, features}, antecedents: [{sort, features, negated?, binding?}], certainty?}`, authored through the rule door of POST /api/v1/inference/rules with its feature encoding and its checks. A bare string that starts with `?` ("?X") is a variable shared across the rule, as are {"name": "?X"} and {"_var": "?X"}; a literal that starts with `?` is written {"type": "String", "value": "?x"}. `negated: true` on an antecedent is negation as failure. A rule the door refuses is not written and is named in `warnings`: a conclusion variable that no antecedent binds, no antecedent, a new cycle through negation, or a feature value the door cannot read. A sort a rule names that `sorts` does not declare is created under `thing` before the rules are authored, so an unknown sort is not refused here (only PATCH /api/v1/scenarios/{id} `add_rules`, which is not normalized, refuses one). */
+        rules?: {
             /** The conditions. Defaults to empty. */
             antecedents?: {
                 /** The antecedent's own identity, named ("?P", with or without the `?`) — OSFQL's `?P: pizza(...)`. On a positive antecedent every "?P" elsewhere in the rule references the term it matches; on a negated one it names the term the negation is about, which a positive antecedent must bind. Meaningless on a head. */
@@ -22148,12 +22156,16 @@ interface MaterializeScenarioRequest$1 {
                 sort: string;
             };
         }[];
+        /** The ontology's scope. Accepted and not written by this route: PUT /api/v1/ontology/scope stores a scope. */
+        scope?: object;
         /** LLM sensor points. Defaults to empty. */
         sensorPoints?: object[];
-        /** Sorts to create or reuse. A sort may carry `provenance`, recorded as its origin: `{"kind": "model", "model"?: …}` (a model proposal, `LlmExtracted`) or `{"kind": "imported", "ontology": …, "original_id": …}` (`Imported`). Without it the sort is `Manual`, credited to the caller; `System` cannot be claimed. */
-        sorts: object[];
+        /** Sorts to create or reuse. A sort may carry `provenance`, recorded as its origin: `{"kind": "model", "model"?: …}` (a model proposal, `LlmExtracted`) or `{"kind": "imported", "ontology": …, "original_id": …}` (`Imported`). Without it the sort is `Manual`, credited to the caller; `System` cannot be claimed. Defaults to empty. */
+        sorts?: object[];
         /** Allen temporal constraints. Defaults to empty. */
         temporalConstraints?: object[];
+        /** Use cases, each `{id, title?, description?}`, recorded as `proposed` competency questions of kind `use_case`. Defaults to empty. */
+        use_cases?: object[];
         /** Webhook actions. Defaults to empty. */
         webhookActions?: object[];
     };
@@ -30369,6 +30381,20 @@ interface RuleEntryDto$1 {
      * @format double
      */
     certainty?: number | null;
+    /**
+     * The rule's content tag (`sha256-<hex>`): send it as `If-Match` on
+     * `DELETE`/`PUT /api/v1/inference/rules/{id}` (#473).
+     *
+     * The same tag those routes judge the precondition against, read from
+     * the same store. `GET /api/v1/terms/{id}` does not serve it, because a
+     * rule's conclusion is the rule's own term and not a fact (#456), so this
+     * listing is the read that publishes it.
+     *
+     * Present on every [`Self::withdrawable`] rule whose conclusion the
+     * tenant's term service holds; absent on a rule no route withdraws,
+     * which has no mutation to precondition.
+     */
+    etag?: string | null;
     /** The head (consequent) of the rule. */
     head: PsiTermDto$1;
     /**
@@ -41803,10 +41829,10 @@ interface TermResponse {
      * - a term answered straight from durable storage because the live store
      *   did not hold it.
      *
-     * A rule's id is its conclusion TERM's id, and `getTerm(ruleId).etag` is the
-     * tag {@link InferenceClient.deleteRule} and
-     * {@link InferenceClient.replaceRule} compare `ifMatch` against — the rule
-     * routes themselves send no ETag.
+     * A rule's tag is not read here: `getTerm(ruleId)` answers 404 for a rule.
+     * The rule routes publish it — {@link AddRuleResponse.etag},
+     * {@link ReplaceRuleResponse.etag} and the listing's
+     * {@link RuleEntryDto.etag}.
      *
      * Not part of the response body: other routes that answer a `TermResponse`
      * never set it.
@@ -43291,6 +43317,17 @@ interface AddFactResponse {
 interface AddRuleResponse {
     /** The created rule as a PsiTerm. */
     term: PsiTermDto;
+    /**
+     * The rule's content tag (`sha256-<hex>`), from the `ETag` response header:
+     * pass it as `ifMatch` to {@link InferenceClient.deleteRule} or
+     * {@link InferenceClient.replaceRule}.
+     *
+     * @remarks
+     * Not part of the response body. Absent when the engine sends no header:
+     * the rule is written, but the read that tags the response failed after the
+     * write committed. Read the tag from {@link RuleEntryDto.etag} then.
+     */
+    etag?: string;
 }
 /** One finding of a rule validation. */
 interface RuleIssue {
@@ -43534,6 +43571,17 @@ interface RuleEntryDto {
     body: PsiTermDto[];
     /** Optional certainty/confidence for the rule. */
     certainty?: number | null;
+    /**
+     * The rule's content tag (`sha256-<hex>`): pass it as `ifMatch` to
+     * {@link InferenceClient.deleteRule} or {@link InferenceClient.replaceRule}.
+     *
+     * @remarks
+     * The same tag those routes judge the precondition against. Present on a
+     * {@link RuleEntryDto.withdrawable} rule; absent on a rule no route
+     * withdraws, which has no mutation to precondition. `getTerm(ruleId)` does
+     * not serve it: a rule's id answers 404 on the term route.
+     */
+    etag?: string;
     /**
      * Where this rule came from, from the reading tenant's point of view.
      *
@@ -43732,6 +43780,17 @@ interface ReplaceRuleResponse {
     previousRuleId: string;
     /** The replacement rule, as created. */
     term: PsiTermDto;
+    /**
+     * The REPLACEMENT rule's content tag (`sha256-<hex>`), from the `ETag`
+     * response header: the `ifMatch` for the next edit or withdrawal.
+     *
+     * @remarks
+     * Not part of the response body. Absent when the engine sends no header:
+     * the replacement is written, but the read that tags the response failed
+     * after the write committed. Read the tag from {@link RuleEntryDto.etag}
+     * then.
+     */
+    etag?: string;
     /** What withdrawing the previous rule removed. */
     withdrawal: RuleWithdrawalReport;
     /** How the edit moved the rule base's guarantees. */
@@ -48353,10 +48412,11 @@ declare class TermsClient {
      * `etag` is optional in every case, not only for `asOf`. A historical read
      * carries none (a past state is not a representation `If-Match` can guard,
      * and a client that could capture one could overwrite the present with the
-     * past), and neither does a rule's conclusion or a term answered straight
-     * from durable storage. A rule's id is its conclusion term's id, so
-     * `getTerm(ruleId).etag` is the tag {@link InferenceClient.deleteRule} and
-     * {@link InferenceClient.replaceRule} take as `ifMatch`.
+     * past), and neither does a term answered straight from durable storage.
+     * A rule's id answers 404 here; read the tag
+     * {@link InferenceClient.deleteRule} and {@link InferenceClient.replaceRule}
+     * take as `ifMatch` from the rule routes ({@link AddRuleResponse.etag},
+     * {@link RuleEntryDto.etag}).
      *
      * @example
      * ```typescript
@@ -48955,7 +49015,7 @@ declare class Inference<SecurityDataType = unknown> {
      */
     deleteGoal: (goalId: string, params?: RequestParams) => Promise<HttpResponse<DeleteGoalResponse$1, void>>;
     /**
-     * @description # The disposition is the caller's `?derivations=refuse` (the default) refuses while the rule still supports materialized conclusions and says how many; `?derivations=retract` withdraws them with it and reports the counts. A delete that silently drops derivations is as wrong as one that silently keeps them, so neither is the unnamed default. # Authorization Requires `X-Tenant-Id`. Runs the same delete guard as `DELETE /api/v1/terms/{id}` — a rule is a policy-relevant object, and withdrawing one changes what the engine will conclude. Honours `If-Match` against the conclusion's content ETag, and requires it under `OSFKB_REQUIRE_IF_MATCH=1`. Every request is captured by the audit middleware.
+     * @description # The disposition is the caller's `?derivations=refuse` (the default) refuses while the rule still supports materialized conclusions and says how many; `?derivations=retract` withdraws them with it and reports the counts. A delete that silently drops derivations is as wrong as one that silently keeps them, so neither is the unnamed default. # Authorization Requires `X-Tenant-Id`. Runs the same delete guard as `DELETE /api/v1/terms/{id}` — a rule is a policy-relevant object, and withdrawing one changes what the engine will conclude. Honours `If-Match` against the conclusion's content ETag — the tag [`rule_content_tag`] publishes on the rule routes (#473) — and requires it under `OSFKB_REQUIRE_IF_MATCH=1`. Every request is captured by the audit middleware.
      *
      * @tags inference
      * @name DeleteRule
@@ -49146,7 +49206,8 @@ declare class InferenceClient {
      *
      * @param request - Rule definition using TermInputDto. Set `aggregator` to declare an
      *   engine-side head aggregator (see {@link RuleAggregatorDto}).
-     * @returns The created rule wrapped in an AddRuleResponse.
+     * @returns The created rule wrapped in an AddRuleResponse, with its
+     *   {@link AddRuleResponse.etag} when the engine sends the `ETag` header.
      * @throws {ApiError} If the rule is rejected or the request fails — 422 when
      *   it is unusable as written: a head or body antecedent naming a sort or
      *   term that does not exist (the message names it and its position — `the
@@ -49169,6 +49230,9 @@ declare class InferenceClient {
      *
      * Ask {@link InferenceClient.validateRule} first to learn every reason the
      * write would refuse, without writing.
+     * The `ETag` response header is the rule's content tag, folded into
+     * `etag`: the `ifMatch` for {@link InferenceClient.deleteRule} and
+     * {@link InferenceClient.replaceRule}.
      * A `{ termId }` reference to a term that is durable but not yet loaded
      * into the engine process resolves: the route loads the terms the request
      * names before it converts them.
@@ -49367,8 +49431,8 @@ declare class InferenceClient {
      * @param ruleId - Term id of the rule (its conclusion), as returned by
      *   {@link InferenceClient.addRule} or {@link InferenceClient.getRules}.
      * @param options - `derivations` decides what happens to the conclusions the
-     *   rule derived (defaults to `'refuse'`); `ifMatch` is the ETag of the
-     *   rule's term, sent as the `If-Match` header.
+     *   rule derived (defaults to `'refuse'`); `ifMatch` is the rule's content
+     *   tag, sent as the `If-Match` header.
      * @param requestOptions - Per-call request options.
      * @returns What the withdrawal removed, tier by tier.
      * @throws {@link ApiError} 400 if the id names a fact rather than a rule, or
@@ -49397,14 +49461,16 @@ declare class InferenceClient {
      * conclusions are resident is refused too; `'retract'` removes them and
      * {@link RuleWithdrawalReport.consequencesInvalidated} counts them.
      *
-     * **Optimistic concurrency.** The rule routes send no ETag of their own.
-     * A rule's id is its conclusion term's id, so read the tag with
-     * `client.terms.getTerm(ruleId)` and pass its `etag` as `ifMatch`; a rule
-     * edited since answers 412.
+     * **Optimistic concurrency.** Read the rule's tag from
+     * {@link AddRuleResponse.etag}, {@link ReplaceRuleResponse.etag} or the
+     * listing's {@link RuleEntryDto.etag} ({@link InferenceClient.getRules}),
+     * and pass it as `ifMatch`; a rule edited since answers 412. The term route
+     * does not serve it: `client.terms.getTerm(ruleId)` answers 404 for a rule.
      *
      * @example
      * ```typescript
-     * const { etag } = await client.terms.getTerm(ruleId);
+     * const { rules } = await client.inference.getRules();
+     * const etag = rules.find((rule) => rule.ruleId === ruleId)?.etag;
      * const report = await client.inference.deleteRule(ruleId, {
      *   derivations: 'retract',
      *   ifMatch: etag,
@@ -49421,11 +49487,12 @@ declare class InferenceClient {
      *
      * @param ruleId - Term id of the rule (its conclusion) to replace.
      * @param request - The replacement rule, in the same shape
-     *   {@link InferenceClient.addRule} takes, plus `ifMatch`: the ETag of the
-     *   outgoing rule's term, sent as the `If-Match` header and never in the body.
+     *   {@link InferenceClient.addRule} takes, plus `ifMatch`: the content tag
+     *   of the outgoing rule, sent as the `If-Match` header and never in the body.
      * @param requestOptions - Per-call request options.
      * @returns The replacement, the id it replaced, what the withdrawal removed,
-     *   and how the rule base's guarantees moved.
+     *   and how the rule base's guarantees moved; `etag` is the replacement's
+     *   content tag when the engine sends the `ETag` header.
      * @throws {@link ApiError} 422 if the replacement is rejected by the
      *   authoring guards — in which case the original rule is left live. An
      *   empty `antecedents` list is one such refusal (`rule rejected: a rule
@@ -49448,16 +49515,23 @@ declare class InferenceClient {
      * addresses a single clause.
      *
      * `ifMatch` guards the edit exactly as it guards
-     * {@link InferenceClient.deleteRule}: read the tag with
-     * `client.terms.getTerm(ruleId)`.
+     * {@link InferenceClient.deleteRule}: read the tag from
+     * {@link AddRuleResponse.etag}, a previous {@link ReplaceRuleResponse.etag}
+     * or the listing's {@link RuleEntryDto.etag}. The response's own `etag` is
+     * the REPLACEMENT's tag, the `ifMatch` for the next edit.
      *
      * **Serialization format**: untagged `TermInputDto` / `FeatureInputValueDto`.
      *
      * @example
      * ```typescript
-     * const result = await client.inference.replaceRule(ruleId, {
+     * const created = await client.inference.addRule({
+     *   term: psi('senior', { name: Var('N') }),
+     *   antecedents: [psi('person', { name: Var('N') })],
+     * });
+     * const result = await client.inference.replaceRule(created.term.termId, {
      *   term: psi('retiree', { name: Var('N') }),
      *   antecedents: [psi('person', { name: Var('N') })],
+     *   ifMatch: created.etag,
      * });
      * console.log(result.previousRuleId, '->', result.term.termId);
      * if (result.certification.regressed) {
@@ -71338,19 +71412,21 @@ type ScenarioSortProvenance = {
  * Sent byte for byte, so every key must be the engine's own spelling — and
  * the spellings are mixed:
  *
- * - camelCase: `webhookActions`, `temporalConstraints`, `guardConstraints`,
- *   `pipelineStages`, `sensorPoints` (the engine also accepts their
- *   snake_case forms);
+ * - camelCase only: `webhookActions`, `temporalConstraints`,
+ *   `guardConstraints`, `pipelineStages`, `sensorPoints`. Since engine #474
+ *   their snake_case forms (`webhook_actions`, …) are IGNORED, without an
+ *   error;
  * - snake_case only: `curriculum_stages`, `discovered_tools`, `use_cases`,
  *   `competency_questions`, `computed_features`. A camelCase
  *   `curriculumStages` or `discoveredTools` is IGNORED, without an error;
  * - one word: `sorts`, `beliefs`, `rules`, `goal`, `groundings`,
  *   `constraints`, `fluents`, `axioms`, `scope`.
  *
- * `sorts`, `beliefs` and `rules` are required, each possibly empty. `goal` is
- * optional: a scenario without one materializes no agent goal
- * ({@link MaterializeScenarioResponse.goalCreated} is `false`). Every other
- * collection defaults to empty, and keys not listed here are ignored.
+ * No key is required: every collection defaults to empty, so a vocabulary
+ * import sends `sorts` alone. `goal` is optional: a scenario without one
+ * materializes no agent goal
+ * ({@link MaterializeScenarioResponse.goalCreated} is `false`). Keys not
+ * listed here are ignored.
  *
  * The same rule holds inside the collections. A curriculum stage is
  * `{stage_number, name, concepts, prerequisites?, mastery_threshold?}`, a
@@ -71372,9 +71448,9 @@ interface GeneratedScenario {
     /**
      * Sorts to create or reuse. A sort may carry `provenance`
      * ({@link ScenarioSortProvenance}); without it the sort is credited to the
-     * caller.
+     * caller. Defaults to empty.
      */
-    sorts: Record<string, unknown>[];
+    sorts?: Record<string, unknown>[];
     /**
      * Belief instances (typed facts) to assert. Omit it for a schema-only
      * scenario: the engine builds sorts alone (a scenario needs at least one
@@ -71418,7 +71494,7 @@ interface GeneratedScenario {
     webhookActions?: Record<string, unknown>[];
     /** OWL-style axioms over sorts and features (staged builder). */
     axioms?: Record<string, unknown>[];
-    /** The model's declared scope (staged builder). */
+    /** The model's declared scope. Accepted and not written by materialization: `ontology.putScope` stores a scope. */
     scope?: Record<string, unknown>;
     /** Use cases the model serves (staged builder). */
     use_cases?: Record<string, unknown>[];