@kortexya/reasoninglayer 1.20.0 → 1.22.0

package/dist/index.d.cts

@@ -109,7 +109,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 = "1.20.0";
+declare const SDK_VERSION = "1.22.0";
 /**
  * Authentication mode for the SDK.
  *
@@ -4217,6 +4217,17 @@ interface ClearTenantResponse$1 {
      * @min 0
      */
     meta_records_deleted: number;
+    /**
+     * Number of plugin-marketplace install records forgotten for this tenant.
+     *
+     * The durable `plugin_installs` rows are counted by the table sweep; this is
+     * the IN-MEMORY registry's count, reported separately because the two used
+     * to disagree — the sweep deleted the rows while the registry kept serving
+     * the records, so the install listing reported plugins enabled over a
+     * knowledge base that had just been wiped.
+     * @min 0
+     */
+    plugin_installs_deleted?: number;
     /**
      * Number of residuation records deleted
      * @min 0
@@ -13467,6 +13478,12 @@ interface IngestDocumentRequest$1 {
 }
 /** Response from document ingestion */
 interface IngestDocumentResponse$1 {
+    /**
+     * Document ID within the session — the handle that session progress and
+     * corpus reads key on. Clients previously had to recover it from listings.
+     * @format uuid
+     */
+    document_id?: string | null;
     /** Error message if parsing failed */
     error?: string | null;
     /** Markdown ingestion statistics (from the markdown pipeline) */
@@ -14160,6 +14177,15 @@ interface InstallRequest {
 }
 /** Response for `POST /install` (201). */
 interface InstallResponse {
+    /** What is missing from the live contribution, when `degraded`. */
+    degradation?: string | null;
+    /**
+     * Whether the contribution is only PARTIALLY applied to the live view
+     * (issue #154 D). `state` alone cannot say this: a plugin whose sorts the
+     * live lattice rejected, or whose startup replay failed, still reads
+     * `Enabled` while contributing less than it reports — or nothing at all.
+     */
+    degraded?: boolean;
     /** The new install's id. */
     install_id: string;
     /**
@@ -14177,6 +14203,13 @@ interface InstallResponse {
 }
 /** Response for enable/disable (the new lifecycle state). */
 interface InstallStateDto {
+    /** What is missing from the live contribution, when `degraded`. */
+    degradation?: string | null;
+    /**
+     * Whether the contribution is only PARTIALLY applied to the live view
+     * (issue #154 D).
+     */
+    degraded?: boolean;
     /** The install's id. */
     install_id: string;
     /** The lifecycle state after the transition. */
@@ -14184,6 +14217,15 @@ interface InstallStateDto {
 }
 /** One install row in the install-list response. */
 interface InstallSummaryDto {
+    /** What is missing from the live contribution, when `degraded`. */
+    degradation?: string | null;
+    /**
+     * Whether the contribution is only PARTIALLY applied to the live view
+     * (issue #154 B/D) — a sort the live lattice rejected, or a startup replay
+     * that failed. `state` cannot express this: such an install still reads
+     * `Enabled`.
+     */
+    degraded?: boolean;
     /** The install's id. */
     install_id: string;
     /** The installed plugin's id. */
@@ -22787,7 +22829,8 @@ interface SearchSortsMatch {
     /**
      * Hierarchy depth — `0` is a root sort. Always populated: the
      * upstream port (`SortVisualizationPort::search_sorts_by_name`)
-     * returns an `i32` directly, with no nullable code path.
+     * returns an `i32` directly, with no nullable code path. A
+     * plugin-contributed match reports its depth in the live tenant lattice.
      * @format int32
      */
     depth: number;
@@ -22796,8 +22839,22 @@ interface SearchSortsMatch {
      * @format uuid
      */
     id: string;
-    /** Sort name as stored in PG. */
+    /**
+     * Sort name as stored in PG, or the committed (namespaced) name for a
+     * plugin-contributed sort.
+     */
     name: string;
+    /**
+     * The plugin that contributed this sort (UUID), when the match came from a
+     * marketplace install rather than PG (issue #154 A).
+     * @format uuid
+     */
+    plugin_id?: string | null;
+    /**
+     * The name the plugin author wrote, before namespacing (issue #154 A) —
+     * the form the query matched.
+     */
+    plugin_local_name?: string | null;
 }
 /** Response body for `GET /api/v1/sorts/search`. */
 interface SearchSortsResponse {
@@ -23838,6 +23895,24 @@ interface SortDto$1 {
     origin?: null | SortOriginDto$1;
     /** Parent sort IDs */
     parents: string[];
+    /**
+     * The plugin that contributed this sort (UUID), when a marketplace install
+     * created it (issue #154 A). `None` for every ordinary sort.
+     *
+     * A plugin's sorts are committed under a namespaced `name`
+     * (`plugin:<plugin-uuid>:<local>`) so two plugins never collide. This field
+     * and [`plugin_local_name`](Self::plugin_local_name) are what tie that name
+     * back to its author: without them a reader of a full listing cannot tell
+     * which plugin owns `plugin:642156b2…:signal`, nor what it was called.
+     * @format uuid
+     */
+    plugin_id?: string | null;
+    /**
+     * The name the plugin author wrote, before namespacing (issue #154 A).
+     * `GET /api/v1/sorts/tenant/{id}?name_prefix=…` matches this form as well as
+     * the committed `name`.
+     */
+    plugin_local_name?: string | null;
     /** Lifecycle status */
     status?: null | SortStatusDto$1;
     /**
@@ -24825,6 +24900,14 @@ interface StructuredIngestionStatsDto$1 {
      * @min 0
      */
     entities_extracted: number;
+    /**
+     * Number of records the source reported as available for the ingested
+     * tables, before any cap or collapse (#177). Compared with
+     * `records_processed`, a cap hit is visible; compared with `terms_created`,
+     * a partial ingest is visible.
+     * @min 0
+     */
+    records_available: number;
     /**
      * Number of source records processed
      * @min 0
@@ -24840,6 +24923,14 @@ interface StructuredIngestionStatsDto$1 {
      * @min 0
      */
     relations_discovered: number;
+    /**
+     * Number of rows that collapsed onto a key value another row already
+     * produced in the same run — the bound-key upsert merged them into one
+     * term (#177). Zero when the bound key identifies rows uniquely. Named in
+     * `warnings` when non-zero.
+     * @min 0
+     */
+    rows_collapsed: number;
     /**
      * Number of sorts created (from pipeline)
      * @min 0
@@ -28968,6 +29059,25 @@ interface SortDto {
     status?: SortStatusDto | null;
     /** Whether this sort needs human review. */
     needsReview?: boolean;
+    /**
+     * The plugin that contributed this sort, when a marketplace install created
+     * it. `undefined` for every ordinary sort.
+     *
+     * @remarks
+     * A plugin's sorts are committed under a namespaced `name`
+     * (`plugin:<plugin-name>:<local>`) so two plugins never collide on the same
+     * local name. This field and {@link SortDto.pluginLocalName} are what tie
+     * that name back to its author.
+     */
+    pluginId?: string | null;
+    /**
+     * The name the plugin author wrote, before namespacing.
+     *
+     * @remarks
+     * `GET /api/v1/sorts/tenant/{id}?name_prefix=…` matches this form as well as
+     * the committed {@link SortDto.name}.
+     */
+    pluginLocalName?: string | null;
 }
 /**
  * Response wrapper for sort endpoints.
@@ -29821,6 +29931,8 @@ declare class Terms<SecurityDataType = unknown> {
          * @min 0
          */
         offset?: number;
+        /** Only terms of this exact sort; omit for every sort */
+        sort_name?: string;
     }, params?: RequestParams) => Promise<HttpResponse<TermListResponse$1, any>>;
     /**
      * No description
@@ -30768,8 +30880,9 @@ declare class TermsClient {
         }>;
     }): Promise<BulkAddTermsResponse>;
     /**
-     * List all terms for the authenticated tenant.
+     * List terms for the authenticated tenant.
      *
+     * @param query - Optional paging and sort filter. Omit for every term.
      * @returns The list of terms with total count.
      * @throws {ApiError} If the request fails.
      *
@@ -30778,16 +30891,28 @@ declare class TermsClient {
      * Requires X-Tenant-Id header (set via client configuration).
      * Uses the tagged {@link ValueDto} serialization format.
      *
+     * `sortName` filters on the sort's committed name. For a plugin-contributed
+     * sort that is the namespaced form (`plugin:<plugin-name>:<local>`), which
+     * {@link SortDto.name} carries and {@link SortDto.pluginLocalName} maps back
+     * to the name its author wrote.
+     *
      * @example
      * ```typescript
      * const result = await client.terms.listTerms();
      * console.log(`Found ${result.count} terms`);
-     * for (const term of result.terms) {
-     *   console.log(term.id, term.sortName);
-     * }
+     *
+     * // Only the first page of one sort's terms.
+     * const page = await client.terms.listTerms({ sortName: 'person', limit: 50 });
      * ```
      */
-    listTerms(): Promise<TermListResponse>;
+    listTerms(query?: {
+        /** Max terms to return; omit for all, hard-capped at 10000. */
+        limit?: number;
+        /** Zero-based index of the first term (default 0). */
+        offset?: number;
+        /** Only terms of this exact sort; omit for every sort. */
+        sortName?: string;
+    }): Promise<TermListResponse>;
     /**
      * Clear all terms for the authenticated tenant.
      *
@@ -41527,7 +41652,10 @@ declare class Ingestion<SecurityDataType = unknown> {
      * @request POST:/api/v1/ingest/document
      * @secure
      */
-    ingestDocument: (data: IngestDocumentRequest$1, params?: RequestParams) => Promise<HttpResponse<IngestDocumentResponse$1, void>>;
+    ingestDocument: (data: IngestDocumentRequest$1, query?: {
+        /** When true or absent, process synchronously (legacy behavior, returns 201 with full stats). When false, return 202 after parsing and ingest in the background — poll the session endpoints. */
+        sync?: boolean;
+    }, params?: RequestParams) => Promise<HttpResponse<IngestDocumentResponse$1, void>>;
     /**
      * @description POST /api/v1/ingest/document/batch This endpoint accepts multiple documents and processes them sequentially, sharing deduplication context across documents. # Headers - `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)
      *
@@ -41557,10 +41685,10 @@ declare class Ingestion<SecurityDataType = unknown> {
      * @request POST:/api/v1/ingest/markdown
      * @secure
      */
-    ingestMarkdown: (query: {
+    ingestMarkdown: (data: IngestMarkdownRequest$1, query?: {
         /** When true, process synchronously (returns 201). When false/absent, process asynchronously (returns 202). */
-        sync: boolean;
-    }, data: IngestMarkdownRequest$1, params?: RequestParams) => Promise<HttpResponse<void, void>>;
+        sync?: boolean;
+    }, params?: RequestParams) => Promise<HttpResponse<void, void>>;
     /**
      * @description POST /api/v1/ingest/markdown/batch This endpoint accepts multiple markdown documents and enqueues them for background processing. Each document is processed independently by background workers, tracked under a single session. When a task queue is available (default), returns 202 Accepted immediately. Falls back to synchronous processing (201 Created) only when no queue is configured. # Headers - `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required) # Request Body - `documents`: List of markdown documents with IDs and content - `owner_id`: User ID who owns the ingested data - `config`: Optional configuration overrides # Response - Async (202): Session ID + document IDs for tracking - Sync fallback (201): Full ingestion result with stats
      *
@@ -41580,10 +41708,10 @@ declare class Ingestion<SecurityDataType = unknown> {
      * @request POST:/api/v1/ingest/rdf
      * @secure
      */
-    ingestRdf: (query: {
+    ingestRdf: (data: IngestRdfRequest$1, query?: {
         /** When true, run synchronously (returns 201). Default false: returns 202 with a session id. */
-        sync: boolean;
-    }, data: IngestRdfRequest$1, params?: RequestParams) => Promise<HttpResponse<IngestRdfResponse$1, void>>;
+        sync?: boolean;
+    }, params?: RequestParams) => Promise<HttpResponse<IngestRdfResponse$1, void>>;
     /**
      * @description The read-only mirror of `POST /api/v1/sparql/translate`. Runs the exact same conversion the ingest pipeline runs (`parse_rdf_with_prefixes` → `convert_rdf_to_terms`), renders each produced term as text, and returns it. No term, sort, or `@prefix` is persisted: the sort-name and prefix resolution both run against owned copies of the tenant's hierarchy state, never the shared hierarchy itself.
      *
@@ -54976,6 +55104,15 @@ interface ClearTenantResponse {
     inferenceStateCleared: boolean;
     /** Whether the cache was invalidated. */
     cacheInvalidated: boolean;
+    /**
+     * Number of plugin-marketplace install records forgotten for this tenant.
+     *
+     * @remarks
+     * Reported separately from the persistent table sweep's row count: the
+     * durable rows and the in-memory registry are two stores, and this is the
+     * one the install listing reads.
+     */
+    pluginInstallsDeleted?: number;
 }
 /**
  * Response for the list-tenants endpoint.
@@ -57653,6 +57790,21 @@ interface SourceExcerptDto$1 {
     /** Source document, if applicable. */
     sourceDocument?: string | null;
 }
+/**
+ * A sort from the tenant's catalog that a claim names.
+ *
+ * @remarks
+ * The schema counterpart of {@link SourceExcerptDto}: it carries no `termId`,
+ * because there is no record to point at. An answer *about* the knowledge base
+ * — "what sorts exist here" — is built from the sort catalog, runs no query and
+ * produces no binding, so this is the only evidence it can carry.
+ */
+interface SchemaExcerptDto {
+    /** The sort as the tenant's lattice names it. */
+    sortName: string;
+    /** The features the sort declares. */
+    featureNames?: string[];
+}
 /**
  * A claim annotation with provenance information.
  */
@@ -57661,7 +57813,13 @@ interface ClaimAnnotationDto {
     text: string;
     /** Character offsets (start, end) in the assistant_message. */
     span: unknown[];
-    /** Claim classification: "kb_grounded", "derived", "llm_framing", "proven", "contradicted". */
+    /**
+     * Claim classification: "kb_grounded", "schema_grounded", "derived",
+     * "llm_framing", "proven", "contradicted".
+     *
+     * `schema_grounded` is backed by the tenant's sort catalog rather than by
+     * records — see {@link ClaimAnnotationDto.schemaExcerpts}.
+     */
     claimType: string;
     /** Confidence score (0.0-1.0). */
     confidence: number;
@@ -57669,6 +57827,11 @@ interface ClaimAnnotationDto {
     sourceTermIds?: string[];
     /** Source data excerpts from the KB. */
     sourceExcerpts?: SourceExcerptDto$1[];
+    /**
+     * Sorts from the tenant's catalog that this claim names — the evidence for a
+     * `schema_grounded` claim, and additional context on any other.
+     */
+    schemaExcerpts?: SchemaExcerptDto[];
     /** OSFQL query that produced the grounding data. */
     osfqlQuery?: string | null;
     /** Derivation chain summary. */
@@ -57997,10 +58160,11 @@ type conversation_ReasoningTraceDto = ReasoningTraceDto;
 type conversation_RecordTurnRequest = RecordTurnRequest;
 type conversation_RecordTurnResponse = RecordTurnResponse;
 type conversation_ResolvedCoreferenceDto = ResolvedCoreferenceDto;
+type conversation_SchemaExcerptDto = SchemaExcerptDto;
 type conversation_SessionGraphDto = SessionGraphDto;
 type conversation_TurnDto = TurnDto;
 declare namespace conversation {
-  export type { conversation_ClaimAnnotationDto as ClaimAnnotationDto, conversation_CognitiveStrategyDto as CognitiveStrategyDto, conversation_CompareModelDto as CompareModelDto, conversation_ConversationMessageRequest as ConversationMessageRequest, conversation_ConversationMessageResponse as ConversationMessageResponse, conversation_ConversationSummaryDto as ConversationSummaryDto, conversation_ConversationTurnsResponse as ConversationTurnsResponse, conversation_DerivationSummaryDto as DerivationSummaryDto, conversation_FocusEntryDto as FocusEntryDto, conversation_ListConversationsResponse as ListConversationsResponse, conversation_MatchedEntityDto as MatchedEntityDto, conversation_ProofTraceNodeDto as ProofTraceNodeDto, conversation_ReasoningStageDto as ReasoningStageDto, conversation_ReasoningTraceDto as ReasoningTraceDto, conversation_RecordTurnRequest as RecordTurnRequest, conversation_RecordTurnResponse as RecordTurnResponse, conversation_ResolvedCoreferenceDto as ResolvedCoreferenceDto, conversation_SessionGraphDto as SessionGraphDto, SourceExcerptDto$1 as SourceExcerptDto, conversation_TurnDto as TurnDto, UICustomizationDto$1 as UICustomizationDto };
+  export type { conversation_ClaimAnnotationDto as ClaimAnnotationDto, conversation_CognitiveStrategyDto as CognitiveStrategyDto, conversation_CompareModelDto as CompareModelDto, conversation_ConversationMessageRequest as ConversationMessageRequest, conversation_ConversationMessageResponse as ConversationMessageResponse, conversation_ConversationSummaryDto as ConversationSummaryDto, conversation_ConversationTurnsResponse as ConversationTurnsResponse, conversation_DerivationSummaryDto as DerivationSummaryDto, conversation_FocusEntryDto as FocusEntryDto, conversation_ListConversationsResponse as ListConversationsResponse, conversation_MatchedEntityDto as MatchedEntityDto, conversation_ProofTraceNodeDto as ProofTraceNodeDto, conversation_ReasoningStageDto as ReasoningStageDto, conversation_ReasoningTraceDto as ReasoningTraceDto, conversation_RecordTurnRequest as RecordTurnRequest, conversation_RecordTurnResponse as RecordTurnResponse, conversation_ResolvedCoreferenceDto as ResolvedCoreferenceDto, conversation_SchemaExcerptDto as SchemaExcerptDto, conversation_SessionGraphDto as SessionGraphDto, SourceExcerptDto$1 as SourceExcerptDto, conversation_TurnDto as TurnDto, UICustomizationDto$1 as UICustomizationDto };
 }
 
 /**
@@ -63637,6 +63801,17 @@ interface InstallPluginResponse {
     rulesAdded: number;
     /** The resulting lifecycle state (`"Enabled"` after a successful install). */
     state: string;
+    /**
+     * Whether the contribution is only PARTIALLY applied to the live view.
+     *
+     * @remarks
+     * {@link InstallPluginResponse.state} cannot express this: a plugin whose sorts the live lattice
+     * rejected, or whose startup replay failed, still reads `"Enabled"` while
+     * contributing less than it reports — or nothing at all.
+     */
+    degraded?: boolean;
+    /** What is missing from the live contribution, when {@link InstallPluginResponse.degraded}. */
+    degradation?: string | null;
 }
 /**
  * An install's lifecycle state after an enable/disable transition.
@@ -63652,6 +63827,17 @@ interface InstallState {
     installId: string;
     /** The lifecycle state after the transition. */
     state: string;
+    /**
+     * Whether the contribution is only PARTIALLY applied to the live view.
+     *
+     * @remarks
+     * {@link InstallState.state} cannot express this: a plugin whose sorts the live lattice
+     * rejected, or whose startup replay failed, still reads `"Enabled"` while
+     * contributing less than it reports — or nothing at all.
+     */
+    degraded?: boolean;
+    /** What is missing from the live contribution, when {@link InstallState.degraded}. */
+    degradation?: string | null;
 }
 /**
  * Request to upgrade an install to another published version.
@@ -63711,6 +63897,17 @@ interface InstallSummary {
     state: string;
     /** Whether the install is system-wide (rather than per-tenant). */
     systemWide: boolean;
+    /**
+     * Whether the contribution is only PARTIALLY applied to the live view.
+     *
+     * @remarks
+     * {@link InstallSummary.state} cannot express this: a plugin whose sorts the live lattice
+     * rejected, or whose startup replay failed, still reads `"Enabled"` while
+     * contributing less than it reports — or nothing at all.
+     */
+    degraded?: boolean;
+    /** What is missing from the live contribution, when {@link InstallSummary.degraded}. */
+    degradation?: string | null;
 }
 /**
  * The installs visible in the requested scope.