@kortexya/reasoninglayer 1.2.1 → 1.4.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.2.1";
+declare const SDK_VERSION = "1.4.0";
 /**
  * Authentication mode for the SDK.
  *
@@ -2058,6 +2058,55 @@ interface BulkRejectRequest$1 {
      */
     reviewed_by: string;
 }
+/**
+ * Request body for bulk-retract: list of term ids to retract.
+ *
+ * Phase 2 v2 entry point for retraction. The supervisor downstream
+ * BFS-retracts every dependent derived fact through
+ * [`DerivedFactsRepository::find_dependents`](osfkb_domain::ports::DerivedFactsRepository::find_dependents)
+ * + [`DerivedFactsRepository::decrement_proof_count`](osfkb_domain::ports::DerivedFactsRepository::decrement_proof_count).
+ *
+ * # Tenant Context
+ * The tenant is determined from the `X-Tenant-Id` header. The
+ * `term_ids` are resolved against that tenant's working memory only.
+ */
+interface BulkRetractTermsRequest {
+    /**
+     * Identifiers of the terms to remove from the working memory.
+     * Phase 2 supervisor downstream BFS-retracts every dependent
+     * derived fact through `find_dependents` + `decrement_proof_count`.
+     */
+    term_ids: string[];
+}
+/**
+ * Response from bulk term retraction.
+ *
+ * Mirrors [`BulkAddTermsResponse`] with retraction-specific semantics.
+ * The endpoint is idempotent: term ids that do not exist in the
+ * working memory are silently skipped (symmetric with how
+ * `bulk_add_terms` ignores duplicate ids when an explicit `id` is
+ * supplied for a term that already exists).
+ */
+interface BulkRetractTermsResponse {
+    /**
+     * Processing time including PG removal + supervisor enqueue.
+     * @min 0
+     */
+    processing_time_ms: number;
+    /**
+     * The subset of `term_ids` actually removed (those that existed).
+     * Order matches the input order, restricted to the ids that were
+     * present in the working memory.
+     */
+    removed_term_ids: string[];
+    /**
+     * Number of terms successfully removed (those not present in the
+     * store are silently skipped — symmetric with `bulk_add_terms`'s
+     * idempotency).
+     * @min 0
+     */
+    terms_removed: number;
+}
 /** Response from bulk review actions */
 interface BulkReviewResponse {
     /** Review IDs that failed with reasons */
@@ -10585,6 +10634,37 @@ interface MatchedEntityDto$1 {
      */
     term_id: string;
 }
+/**
+ * Snapshot of the per-tenant Phase 2 materialization sentinel for the
+ * status endpoint.
+ */
+interface MaterializationStateSnapshot {
+    /**
+     * Tenant `derived_facts` count when the sentinel was written.
+     * @format int64
+     * @min 0
+     */
+    derived_count_at_bootstrap: number;
+    /**
+     * Tenant `terms` count when the sentinel was written.
+     * @format int64
+     * @min 0
+     */
+    fact_count_at_bootstrap: number;
+    /**
+     * Wall-clock instant of the most recent rebuild handler call,
+     * in Unix milliseconds.
+     * @format int64
+     * @min 0
+     */
+    last_bootstrap_at_ms: number;
+    /**
+     * Supervisor LSN observed at the moment the sentinel was written.
+     * @format int64
+     * @min 0
+     */
+    last_bootstrap_lsn: number;
+}
 /** Summary of materialization results. */
 interface MaterializationSummaryDto$1 {
     /**
@@ -13026,6 +13106,27 @@ interface ReExtractResponse {
      */
     pending_review_count: number;
 }
+/** Response payload for `POST /api/v1/admin/derived-facts/rebuild/{tenant_id}`. */
+interface RebuildDerivedFactsResponse {
+    /**
+     * Per-tenant materialization LSN at the moment the response was
+     * produced. Read-side caches consult this value to know whether
+     * they have observed every successfully applied event.
+     * @format int64
+     * @min 0
+     */
+    materialization_lsn: number;
+    /**
+     * Number of rows truncated from `derived_facts` for this tenant.
+     * @min 0
+     */
+    removed: number;
+    /**
+     * Number of `BootstrapRule` events queued to the supervisor.
+     * @min 0
+     */
+    rules_queued: number;
+}
 /** Request to recall similar episodes. */
 interface RecallEpisodesRequest$1 {
     /**
@@ -14744,6 +14845,43 @@ type SearchResponse = {
      */
     variables: Record<string, VariableFeasibilityDto$1>;
 };
+/**
+ * PG-direct name search across the tenant's sorts. Used by the
+ * viewer when the in-memory hierarchy returns 0 hits because the
+ * user is exploring a million-scale tenant where most sorts aren't
+ * hydrated. Returns `{matches: [{id, name, depth}]}` ordered by
+ * exact-match-first, then prefix, then by name length.
+ * One row of [`SearchSortsResponse::matches`] — a single matching sort.
+ */
+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.
+     * @format int32
+     */
+    depth: number;
+    /**
+     * Sort identifier (UUID).
+     * @format uuid
+     */
+    id: string;
+    /** Sort name as stored in PG. */
+    name: string;
+}
+/** Response body for `GET /api/v1/sorts/search`. */
+interface SearchSortsResponse {
+    /**
+     * Number of returned matches (≤ requested limit, ≤ 100).
+     * @min 0
+     */
+    count: number;
+    /**
+     * Matching sorts, ordered exact-match-first, then prefix, then by
+     * shortest name.
+     */
+    matches: SearchSortsMatch[];
+}
 /**
  * Search statistics collected during a search operation.
  *
@@ -16209,6 +16347,117 @@ interface SummaryResponse$1 {
     ts_first?: string | null;
     ts_last?: string | null;
 }
+/**
+ * Snapshot of the most recent handler error observed by the
+ * supervisor's metrics, surfaced through the status endpoint.
+ */
+interface SupervisorErrorSnapshot {
+    /**
+     * Unix-millisecond timestamp at which the failure was recorded.
+     * @format int64
+     * @min 0
+     */
+    at_ms: number;
+    /** Truncated error message (≤ 512 chars). */
+    message: string;
+}
+/**
+ * Response payload for
+ * `GET /api/v1/admin/derived-facts/status/{tenant_id}`.
+ *
+ * Aggregates per-tenant supervisor health (event counters, last
+ * error, materialization LSN, queue depth approximation) and
+ * rebuild-state (sentinel snapshot, lock-held hint).
+ */
+interface SupervisorStatusResponse {
+    /**
+     * Total `derived_facts` rows for this tenant, queried at
+     * response time. Operators compare this against
+     * `materialization_state.derived_count_at_bootstrap` to estimate
+     * derivation growth since the last rebuild.
+     * @min 0
+     */
+    derived_facts_count: number;
+    /**
+     * Cumulative count of events whose handler returned `Err(_)`.
+     * @format int64
+     * @min 0
+     */
+    events_failed: number;
+    /**
+     * Events currently inside the handler closure.
+     * @min 0
+     */
+    events_in_flight: number;
+    /**
+     * Cumulative count of events whose handler returned `Ok(())`.
+     * @format int64
+     * @min 0
+     */
+    events_processed: number;
+    /**
+     * Cumulative count of events accepted by `submit`.
+     * @format int64
+     * @min 0
+     */
+    events_submitted: number;
+    /**
+     * Sum of `elapsed_ms` across all handler invocations.
+     * @format int64
+     * @min 0
+     */
+    handler_millis_total: number;
+    /**
+     * Unix-millisecond timestamp of the most recent handler return.
+     * @format int64
+     * @min 0
+     */
+    last_complete_ms: number;
+    /** Most recently observed handler error, if any. */
+    last_error?: null | SupervisorErrorSnapshot;
+    /**
+     * Unix-millisecond timestamp of the most recent `submit` call.
+     * @format int64
+     * @min 0
+     */
+    last_submit_ms: number;
+    /**
+     * Per-tenant materialization LSN as of the response. Read-side
+     * caches keyed on this value compare against it to detect new
+     * derivations.
+     * @format int64
+     * @min 0
+     */
+    materialization_lsn: number;
+    /**
+     * Per-tenant Phase 2 materialization sentinel, or `None` if the
+     * tenant has never been rebuilt.
+     */
+    materialization_state?: null | MaterializationStateSnapshot;
+    /**
+     * Approximate channel depth: `submitted − processed − failed −
+     * in_flight`. Saturates at zero on the rare race where a handler
+     * returned between two field reads.
+     * @min 0
+     */
+    queue_depth_approx: number;
+    /**
+     * **Racy hint**: `true` if the per-tenant rebuild mutex is
+     * currently held. Computed via `try_lock()` and can briefly
+     * disagree with the actual lock state (the lock may drop
+     * between the probe and the read), so operators must not treat
+     * this as authoritative. Use it as a "rebuild appears to be in
+     * flight" signal only.
+     */
+    rebuild_in_flight: boolean;
+    /**
+     * `true` if a [`DataflowSupervisor`] has been spawned for this
+     * tenant. `false` indicates the tenant has never had an event
+     * submitted on its behalf and the metrics fields are returned
+     * at their initial zero values.
+     */
+    supervisor_active: boolean;
+}
 /** Information about a suspended (incomplete) query */
 interface SuspendedQueryDto$1 {
     /**
@@ -18220,6 +18469,22 @@ declare class Sorts<SecurityDataType = unknown> {
      * @request POST:/api/v1/sorts/learned-similarities/reject
      */
     rejectLearnedSimilarity: (data: RejectLearnedSimilarityRequest$1, params?: RequestParams) => Promise<HttpResponse<RejectLearnedSimilarityResponse$1, any>>;
+    /**
+     * No description
+     *
+     * @tags sorts
+     * @name SearchSortsByName
+     * @request GET:/api/v1/sorts/search
+     */
+    searchSortsByName: (query: {
+        /**
+         * Max results (default 20, capped at 100)
+         * @min 0
+         */
+        limit?: number;
+        /** Search query (sort name substring) */
+        q: string;
+    }, params?: RequestParams) => Promise<HttpResponse<SearchSortsResponse, any>>;
     /**
      * @description Similarity is symmetric: ∼(s₁, s₂) = ∼(s₂, s₁) Degree must be in [0, 1] range.
      *
@@ -18372,6 +18637,17 @@ interface ReferenceValue {
     type: 'Reference';
     value: string;
 }
+/**
+ * A reference to a sort by UUID. Produces `{"type": "SortId", "value": "uuid"}`.
+ *
+ * Used by homoiconic meta-constraints (e.g. `sort_constraint`) whose feature
+ * targets a sort as a first-class value. Maps to the backend `Value::SortId`
+ * variant which the chainer dispatches directly.
+ */
+interface SortIdValue {
+    type: 'SortId';
+    value: string;
+}
 /** A list of values. Produces `{"type": "List", "value": [...]}`. */
 interface ListValue {
     type: 'List';
@@ -18424,7 +18700,7 @@ interface SetValue {
  * (BigInteger, DateTime, Geometry, etc.) to `ValueDto::String` with Rust debug format.
  * You may encounter strings like `"DateTime(2024-01-15T10:30:00Z)"`.
  */
-type ValueDto = StringValue | IntegerValue | RealValue | BooleanValue | UninstantiatedValue | ReferenceValue | ListValue | FuzzyScalarValue | FuzzyNumberValue | SetValue;
+type ValueDto = StringValue | IntegerValue | RealValue | BooleanValue | UninstantiatedValue | ReferenceValue | SortIdValue | ListValue | FuzzyScalarValue | FuzzyNumberValue | SetValue;
 /**
  * Triangular fuzzy membership function.
  *
@@ -18739,6 +19015,7 @@ type values_SetValue = SetValue;
 type values_SigmoidDifferenceShape = SigmoidDifferenceShape;
 type values_SigmoidProductShape = SigmoidProductShape;
 type values_SigmoidShape = SigmoidShape;
+type values_SortIdValue = SortIdValue;
 type values_SpikeShape = SpikeShape;
 type values_StringValue = StringValue;
 type values_TaggedFeatureValueDto = TaggedFeatureValueDto;
@@ -18748,7 +19025,7 @@ type values_UninstantiatedValue = UninstantiatedValue;
 type values_ValueDto = ValueDto;
 type values_ZShapeShape = ZShapeShape;
 declare namespace values {
-  export type { values_BellShape as BellShape, values_BooleanValue as BooleanValue, values_CauchyShape as CauchyShape, values_CosineShape as CosineShape, values_CyclicGaussianShape as CyclicGaussianShape, values_FeatureTargetDto as FeatureTargetDto, values_FeatureValueDto as FeatureValueDto, values_FuzzyNumberValue as FuzzyNumberValue, values_FuzzyScalarValue as FuzzyScalarValue, values_FuzzyShapeDto as FuzzyShapeDto, values_GaussianProductShape as GaussianProductShape, values_GaussianShape as GaussianShape, values_IntegerValue as IntegerValue, values_ListValue as ListValue, values_PiShapeShape as PiShapeShape, values_PiecewiseLinearShape as PiecewiseLinearShape, values_RealValue as RealValue, values_ReferenceValue as ReferenceValue, values_SShapeShape as SShapeShape, values_SetValue as SetValue, values_SigmoidDifferenceShape as SigmoidDifferenceShape, values_SigmoidProductShape as SigmoidProductShape, values_SigmoidShape as SigmoidShape, values_SpikeShape as SpikeShape, values_StringValue as StringValue, values_TaggedFeatureValueDto as TaggedFeatureValueDto, values_TrapezoidalShape as TrapezoidalShape, values_TriangularShape as TriangularShape, values_UninstantiatedValue as UninstantiatedValue, values_ValueDto as ValueDto, values_ZShapeShape as ZShapeShape };
+  export type { values_BellShape as BellShape, values_BooleanValue as BooleanValue, values_CauchyShape as CauchyShape, values_CosineShape as CosineShape, values_CyclicGaussianShape as CyclicGaussianShape, values_FeatureTargetDto as FeatureTargetDto, values_FeatureValueDto as FeatureValueDto, values_FuzzyNumberValue as FuzzyNumberValue, values_FuzzyScalarValue as FuzzyScalarValue, values_FuzzyShapeDto as FuzzyShapeDto, values_GaussianProductShape as GaussianProductShape, values_GaussianShape as GaussianShape, values_IntegerValue as IntegerValue, values_ListValue as ListValue, values_PiShapeShape as PiShapeShape, values_PiecewiseLinearShape as PiecewiseLinearShape, values_RealValue as RealValue, values_ReferenceValue as ReferenceValue, values_SShapeShape as SShapeShape, values_SetValue as SetValue, values_SigmoidDifferenceShape as SigmoidDifferenceShape, values_SigmoidProductShape as SigmoidProductShape, values_SigmoidShape as SigmoidShape, values_SortIdValue as SortIdValue, values_SpikeShape as SpikeShape, values_StringValue as StringValue, values_TaggedFeatureValueDto as TaggedFeatureValueDto, values_TrapezoidalShape as TrapezoidalShape, values_TriangularShape as TriangularShape, values_UninstantiatedValue as UninstantiatedValue, values_ValueDto as ValueDto, values_ZShapeShape as ZShapeShape };
 }
 
 /**
@@ -20409,11 +20686,22 @@ interface TermInputInlineByName {
  * Use `FeatureInput.*` builders to construct these values safely.
  * Do NOT use with term CRUD endpoints — use {@link import('./values.js').ValueDto} instead.
  */
-type FeatureInputValueDto = FeatureInputTermRef | FeatureInputConstrainedVariable | FeatureInputVariable | FeatureInputInlineTerm | FeatureInputInlineTermByName | FeatureInputValueDto[] | string | number | boolean;
+type FeatureInputValueDto = FeatureInputTermRef | FeatureInputSortRef | FeatureInputConstrainedVariable | FeatureInputVariable | FeatureInputInlineTerm | FeatureInputInlineTermByName | FeatureInputValueDto[] | string | number | boolean;
 /** Reference an existing term by UUID. */
 interface FeatureInputTermRef {
     termId: string;
 }
+/**
+ * Reference a sort by UUID — used by homoiconic meta-constraints (e.g.
+ * `sort_constraint`) that name a sort as a first-class value.
+ *
+ * Wire format: `{ "sort_ref": "<uuid>" }` (not `sort_id`, which would
+ * collide with {@link FeatureInputInlineTerm} under serde-untagged
+ * deserialization on the backend).
+ */
+interface FeatureInputSortRef {
+    sortRef: string;
+}
 /**
  * A constrained variable in a feature value position.
  *
@@ -20445,6 +20733,7 @@ interface FeatureInputInlineTermByName {
 type homoiconic_FeatureInputConstrainedVariable = FeatureInputConstrainedVariable;
 type homoiconic_FeatureInputInlineTerm = FeatureInputInlineTerm;
 type homoiconic_FeatureInputInlineTermByName = FeatureInputInlineTermByName;
+type homoiconic_FeatureInputSortRef = FeatureInputSortRef;
 type homoiconic_FeatureInputTermRef = FeatureInputTermRef;
 type homoiconic_FeatureInputValueDto = FeatureInputValueDto;
 type homoiconic_FeatureInputVariable = FeatureInputVariable;
@@ -20454,7 +20743,7 @@ type homoiconic_TermInputInline = TermInputInline;
 type homoiconic_TermInputInlineByName = TermInputInlineByName;
 type homoiconic_TermInputRef = TermInputRef;
 declare namespace homoiconic {
-  export type { homoiconic_FeatureInputConstrainedVariable as FeatureInputConstrainedVariable, homoiconic_FeatureInputInlineTerm as FeatureInputInlineTerm, homoiconic_FeatureInputInlineTermByName as FeatureInputInlineTermByName, homoiconic_FeatureInputTermRef as FeatureInputTermRef, homoiconic_FeatureInputValueDto as FeatureInputValueDto, homoiconic_FeatureInputVariable as FeatureInputVariable, homoiconic_PsiTermDto as PsiTermDto, homoiconic_TermInputDto as TermInputDto, homoiconic_TermInputInline as TermInputInline, homoiconic_TermInputInlineByName as TermInputInlineByName, homoiconic_TermInputRef as TermInputRef };
+  export type { homoiconic_FeatureInputConstrainedVariable as FeatureInputConstrainedVariable, homoiconic_FeatureInputInlineTerm as FeatureInputInlineTerm, homoiconic_FeatureInputInlineTermByName as FeatureInputInlineTermByName, homoiconic_FeatureInputSortRef as FeatureInputSortRef, homoiconic_FeatureInputTermRef as FeatureInputTermRef, homoiconic_FeatureInputValueDto as FeatureInputValueDto, homoiconic_FeatureInputVariable as FeatureInputVariable, homoiconic_PsiTermDto as PsiTermDto, homoiconic_TermInputDto as TermInputDto, homoiconic_TermInputInline as TermInputInline, homoiconic_TermInputInlineByName as TermInputInlineByName, homoiconic_TermInputRef as TermInputRef };
 }
 
 /**
@@ -20825,6 +21114,16 @@ declare class Inference<SecurityDataType = unknown> {
      * @secure
      */
     bulkFuzzyProve: (data: BulkFuzzyProveRequest$1, params?: RequestParams) => Promise<HttpResponse<BulkFuzzyProveResponse$1, void>>;
+    /**
+     * @description Phase 2 v2 entry point for retraction: 1. Removes each term from PG + in-memory stores via [`HomoiconicTermService::remove_term`](osfkb_application::services::HomoiconicTermService::remove_term). 2. When `state.use_plan_engine` is on, submits a single [`DeltaEvent::Retract`](osfkb_application::services::dataflow::DeltaEvent::Retract) to the per-tenant supervisor so the Backward/Forward backward chase decrements every dependent derived fact's `proof_count` (and deletes those whose count reaches zero). Symmetric to [`bulk_add_terms`]; idempotent (term ids absent from the working memory are silently skipped — same shape as [`delete_term`] returning 404, except in the bulk path the missing ids simply don't appear in `removed_term_ids`). Best-effort supervisor enqueue: a supervisor failure does NOT fail the 2xx response — the persist path has succeeded and a future bootstrap can recover any missed retraction. # Mid-batch error handling If `remove_term` fails for a term partway through the batch, the handler **stops accumulating successes**, runs cache invalidation for the prefix that did succeed, submits a single [`DeltaEvent::Retract`](osfkb_application::services::dataflow::DeltaEvent::Retract) covering that prefix, and **then** surfaces the error. This keeps the supervisor and the in-memory caches in sync with the actual store state — a leaked Retract event would orphan derived facts whose only antecedent is now removed, which is a critical correctness violation. # Authorization Requires `X-Tenant-Id` header. The `term_ids` are resolved against that tenant's working memory only — cross-tenant retraction is impossible by construction (the per-tenant `HomoiconicTermService` only sees its own tenant's terms).
+     *
+     * @tags inference
+     * @name BulkRetractTerms
+     * @summary Bulk-retract terms from the working memory.
+     * @request POST:/api/v1/inference/facts/bulk-retract
+     * @secure
+     */
+    bulkRetractTerms: (data: BulkRetractTermsRequest, params?: RequestParams) => Promise<HttpResponse<BulkRetractTermsResponse, any>>;
     /**
      * @description # DEPRECATED This endpoint is deprecated. Use `DELETE /api/v1/terms/{term_id}` for individual terms. # TRUE HOMOICONIC API # Authorization Requires X-Tenant-Id header.
      *
@@ -20877,7 +21176,7 @@ declare class Inference<SecurityDataType = unknown> {
      * @request POST:/api/v1/inference/forward-chain
      * @secure
      */
-    forwardChain: (data: ForwardChainRequest$1, params?: RequestParams) => Promise<HttpResponse<ForwardChainResponse$1, any>>;
+    forwardChain: (data: ForwardChainRequest$1, params?: RequestParams) => Promise<HttpResponse<ForwardChainResponse$1, void>>;
     /**
      * @description Runs forward chaining with probabilistic provenance tags. Each derived fact carries a confidence value computed from the provenance semiring operations (noisy-or for disjunction, product for conjunction). This extends the standard forward chain endpoint by tracking how confidence propagates through rule application, enabling probabilistic reasoning over the knowledge base.
      *
@@ -39372,6 +39671,24 @@ declare class Admin<SecurityDataType = unknown> {
      * @request GET:/api/v1/admin/tenants
      */
     listTenants: (params?: RequestParams) => Promise<HttpResponse<ListTenantsResponse$1, any>>;
+    /**
+     * @description Truncates the derived_facts table for the given tenant and queues a BootstrapAll event covering every analyzed rule. Asynchronous: returns the queue depth and current materialization LSN, not the final state. Concurrent rebuilds for the same tenant are rejected with 409 (per-tenant mutex). Full operational runbook (prerequisites, timings, monitoring, failure recovery, known limitations) lives in .claude/SUB_MS_FORWARD_CHAINING_STATUS.md, section 'Operator runbook — derived-facts rebuild'.
+     *
+     * @tags admin
+     * @name RebuildDerivedFacts
+     * @summary Rebuild derived facts for a tenant
+     * @request POST:/api/v1/admin/derived-facts/rebuild/{tenant_id}
+     */
+    rebuildDerivedFacts: (tenantId: string, params?: RequestParams) => Promise<HttpResponse<RebuildDerivedFactsResponse, void>>;
+    /**
+     * @description Returns event-processing counters (submitted/processed/failed/in-flight), the materialization LSN, the last handler error (if any, truncated to 512 chars), the per-tenant materialization sentinel, the current derived-facts row count, and a racy hint about whether a rebuild is in flight. Intended for operator dashboards; the supervisor itself does not depend on this endpoint.
+     *
+     * @tags admin
+     * @name SupervisorStatus
+     * @summary Get per-tenant supervisor + materialization status
+     * @request GET:/api/v1/admin/derived-facts/status/{tenant_id}
+     */
+    supervisorStatus: (tenantId: string, params?: RequestParams) => Promise<HttpResponse<SupervisorStatusResponse, void>>;
 }
 
 /**
@@ -43688,6 +44005,24 @@ declare const Value: {
      * ```
      */
     readonly reference: (id: string) => ReferenceValue;
+    /**
+     * Create a reference to a sort by UUID.
+     *
+     * @param id - The UUID of the sort.
+     * @returns A tagged `SortIdValue`: `{"type": "SortId", "value": "uuid"}`.
+     *
+     * @remarks
+     * Used by homoiconic meta-constraints — primarily `Constraint.typeOf(...)`
+     * — whose feature targets a sort as a first-class value. The chainer
+     * dispatches this directly via `Value::SortId`.
+     *
+     * @example
+     * ```typescript
+     * Value.sortId("550e8400-e29b-41d4-a716-446655440000")
+     * // { type: 'SortId', value: '550e8400-e29b-41d4-a716-446655440000' }
+     * ```
+     */
+    readonly sortId: (id: string) => SortIdValue;
     /**
      * Create a fuzzy scalar with a value and membership degree.
      *
@@ -44078,6 +44413,127 @@ declare const FuzzyShape: {
     readonly piecewiseLinear: (points: [number, number][]) => PiecewiseLinearShape;
 };
 
+/**
+ * Operators accepted by {@link Constraint.where} — boolean comparisons.
+ * The chainer's `guard_constraint` reads the operator as a string; it
+ * residuates the constraint until both sides are bound (or numerically
+ * evaluable), then evaluates the comparison.
+ */
+type ComparisonOp = '<' | '<=' | '=' | '!=' | '>=' | '>';
+/**
+ * Operators accepted by {@link Constraint.equation} — binary arithmetic.
+ * The op selects the chainer sort: `+` → `plus_constraint`, `-` →
+ * `minus_constraint`, `*` → `times_constraint`, `/` → `div_constraint`.
+ * Each reads `x`, `y`, `z` as `z = x op y`.
+ */
+type ArithmeticOp = '+' | '-' | '*' | '/';
+/** A reference to a variable or term used as a constraint operand. */
+type Operand = string | TermInputArg | number | boolean;
+/**
+ * Builders for the chainer's homoiconic meta-constraints. Each function
+ * returns a single `TermInputArg` representing one constraint term — drop
+ * the result into a clause body or rule antecedents.
+ *
+ * @remarks
+ * These wrap the underlying meta-sort names (`sort_constraint`,
+ * `feature_constraint`, `guard_constraint`, `plus_constraint`, etc.) and
+ * use the exact feature keys the chainer reads. Hand-rolled `psi('...')`
+ * calls with guessed keys silently fail — use these builders instead.
+ *
+ * @example
+ * ```typescript
+ * import { Constraint, psi } from '@kortexya/reasoninglayer';
+ *
+ * // "?E is a term of sort flow_edge_constraint, with edges leaving X"
+ * const body = [
+ *   Constraint.typeOf('?E', flowEdgeSortUuid),
+ *   Constraint.has('?E', 'src', '?X'),
+ *   Constraint.has('?E', 'dst', '?Y'),
+ *   Constraint.has('?E', 'cap', '?C'),
+ *   Constraint.intRange('?Amount', 1, 100),
+ *   Constraint.where('?Amount', '<=', '?C'),
+ *   Constraint.solveFor('?Amount'),
+ * ];
+ * ```
+ */
+declare const Constraint: {
+    /**
+     * State that a variable is a term of a given sort. The chainer enumerates
+     * every persisted term of that sort via backtracking.
+     *
+     * @param variable - Variable name (e.g. `'?E'`) or pre-built variable Ψ-term.
+     * @param sortUuid - UUID of the target sort (resolve from
+     *   `client.inference.getMetaSorts()` or your own `createSort` response).
+     * @returns A `sort_constraint` term.
+     */
+    readonly typeOf: (variable: string, sortUuid: string) => TermInputArg;
+    /**
+     * State that a variable's feature equals a target. The chainer unifies
+     * the variable's feature value with the target.
+     *
+     * **Important**: the chainer's `feature_constraint` only unifies
+     * term-references with term-references. The variable's feature on the
+     * persisted side must itself be a `Value::Reference`. Comparing against
+     * literals (e.g. `has('?N', 'name', 'S')` where `name` is stored as a
+     * plain string) silently returns zero solutions — that's a chainer
+     * design constraint, not a builder bug.
+     *
+     * @param variable - The owning variable (e.g. `'?Edge'`).
+     * @param feature - The feature name (e.g. `'src'`).
+     * @param target - The target — typically another variable (`'?Src'`)
+     *   or an existing term referenced by its UUID via `'!<uuid>'`.
+     * @returns A `feature_constraint` term.
+     */
+    readonly has: (variable: string, feature: string, target: Operand) => TermInputArg;
+    /**
+     * State a boolean comparison between two operands. The chainer
+     * residuates the constraint until both sides are bound; when they are,
+     * the comparison must hold or the proof branch fails.
+     *
+     * @param left - Left operand — variable, literal number, or term ref.
+     * @param op - Comparison operator.
+     * @param right - Right operand.
+     * @returns A `guard_constraint` term.
+     */
+    readonly where: (left: Operand, op: ComparisonOp, right: Operand) => TermInputArg;
+    /**
+     * State that `result = left op right`. Selects the chainer sort by op:
+     * `+` → `plus_constraint`, `-` → `minus_constraint`, `*` →
+     * `times_constraint`, `/` → `div_constraint`. The chainer reads each
+     * operand as either a Reference variable or a numeric literal, and can
+     * run forward, reverse, or verify depending on which operands are
+     * bound.
+     *
+     * @param result - Result variable or value (`z`).
+     * @param op - Arithmetic operator.
+     * @param left - Left operand (`x`).
+     * @param right - Right operand (`y`).
+     * @returns The appropriate arithmetic-constraint term.
+     */
+    readonly equation: (result: Operand, op: ArithmeticOp, left: Operand, right: Operand) => TermInputArg;
+    /**
+     * Constrain a variable to be an integer in the inclusive range
+     * `[min, max]`. Required before the chainer's labeling step can assign
+     * a concrete value via {@link Constraint.solveFor}.
+     *
+     * @param variable - Variable name to constrain.
+     * @param min - Lower bound (inclusive).
+     * @param max - Upper bound (inclusive).
+     * @returns An `fd_domain_constraint` term.
+     */
+    readonly intRange: (variable: string, min: number, max: number) => TermInputArg;
+    /**
+     * Search for concrete integer assignments to the listed variables that
+     * satisfy every other constraint mentioning them. Place this at the END
+     * of a clause body — it's the labeling/search step that turns a
+     * constraint network into solutions.
+     *
+     * @param variables - Variable names to assign.
+     * @returns An `fd_labeling_constraint` term.
+     */
+    readonly solveFor: (...variables: string[]) => TermInputArg;
+};
+
 /**
  * Create a guard constraint as a `TermInputDto`.
  *
@@ -44512,6 +44968,236 @@ declare const LP: {
     readonly bounds: (min?: number, max?: number) => VariableBounds;
 };
 
+/**
+ * Builder namespace for network-flow constraint problems on the
+ * `flow_constraint` family of meta-sorts.
+ *
+ * @remarks
+ * Produces a list of psi-terms that encode an edge set, an objective
+ * (max flow / min cut / min-cost-max-flow / classify edges), and a
+ * `flow_solve_constraint` trigger. The returned `constraints` array
+ * can be used directly as the body of a clause goal, the antecedents
+ * of an inference rule, or spliced alongside other CLP constraints
+ * (e.g., CLP(FD)) inside one query.
+ *
+ * Node identity is encoded via auto-generated psi-variables: every
+ * unique node name maps to one variable (`?N_<sanitized_name>`) so
+ * the backend chainer sees the same TermId every time the same name
+ * appears.
+ *
+ * @example
+ * ```typescript
+ * import { Flow, psi } from '@kortexya/reasoninglayer';
+ *
+ * const { constraints, vars } = Flow.maxFlow({
+ *   source: 's',
+ *   sink: 't',
+ *   edges: [
+ *     ['s', 'a', 10],
+ *     ['s', 'b', 5],
+ *     ['a', 'b', 15],
+ *     ['a', 't', 10],
+ *     ['b', 't', 10],
+ *   ],
+ * });
+ *
+ * const response = await client.inference.backwardChain({
+ *   goal: psi('clause', { antecedents: constraints }),
+ *   max_solutions: 1,
+ * });
+ * // Read `vars.flowValue` from response.solutions[0].substitution.
+ * ```
+ */
+/** Logical node identifier — any string. Used to coordinate identity
+ * across `src` / `dst` / `source` / `sink` references in one problem. */
+type FlowNode = string;
+/** A flow edge declaration. Tuple form `[from, to, cap]` or
+ * `[from, to, cap, options]`, or an explicit object form. */
+type FlowEdgeInput = [FlowNode, FlowNode, number] | [FlowNode, FlowNode, number, FlowEdgeOptions] | (FlowEdgeOptions & {
+    from: FlowNode;
+    to: FlowNode;
+    cap: number;
+});
+/** Optional per-edge attributes. */
+interface FlowEdgeOptions {
+    /** Output variable name (e.g., `?F_sa`). If omitted, an auto-generated
+     * name is used and returned in `vars.edgeFlows`. */
+    flow?: string;
+    /** Per-unit-flow cost. Defaults to 0. Only consulted by
+     * `Flow.minCostMaxFlow`. */
+    cost?: number;
+    /** Optional edge label. Surfaces in min-cut / classification outputs. */
+    label?: string;
+}
+/** Output variables surfaced by `Flow.maxFlow`. */
+interface MaxFlowVars {
+    /** Variable name bound to the total flow source → sink. */
+    flowValue: string;
+    /** Per-edge output variables in declaration order. */
+    edgeFlows: Array<{
+        from: FlowNode;
+        to: FlowNode;
+        var: string;
+    }>;
+}
+/** Output variables surfaced by `Flow.minCut`. */
+interface MinCutVars {
+    cutValue: string;
+    cutEdges: string;
+    sourceSide: string;
+    sinkSide: string;
+    edgeFlows: Array<{
+        from: FlowNode;
+        to: FlowNode;
+        var: string;
+    }>;
+}
+/** Output variables surfaced by `Flow.minCostMaxFlow`. */
+interface MinCostMaxFlowVars {
+    flowValue: string;
+    totalCost: string;
+    edgeFlows: Array<{
+        from: FlowNode;
+        to: FlowNode;
+        var: string;
+    }>;
+}
+/** Output variables surfaced by `Flow.classifyEdges`. */
+interface ClassifyEdgesVars {
+    classifications: string;
+    edgeFlows: Array<{
+        from: FlowNode;
+        to: FlowNode;
+        var: string;
+    }>;
+}
+/** Result returned by each `Flow.*` constructor: the constraint
+ * psi-terms plus the output variable names needed to read results. */
+interface FlowProblem<V> {
+    constraints: TermInputArg[];
+    vars: V;
+}
+/** Common inputs accepted by every objective constructor. */
+interface FlowProblemInputBase {
+    /** Source node identifier. */
+    source: FlowNode;
+    /** Sink node identifier. */
+    sink: FlowNode;
+    /** Edge declarations (tuple or object form). */
+    edges: readonly FlowEdgeInput[];
+}
+/** Inputs for `Flow.maxFlow`. */
+interface MaxFlowInput extends FlowProblemInputBase {
+    /** Optional explicit name for the `flow_value` output variable. */
+    flowValue?: string;
+}
+/** Inputs for `Flow.minCut`. */
+interface MinCutInput extends FlowProblemInputBase {
+    cutValue?: string;
+    cutEdges?: string;
+    sourceSide?: string;
+    sinkSide?: string;
+}
+/** Inputs for `Flow.minCostMaxFlow`. */
+interface MinCostMaxFlowInput extends FlowProblemInputBase {
+    flowValue?: string;
+    totalCost?: string;
+}
+/** Inputs for `Flow.classifyEdges`. */
+interface ClassifyEdgesInput extends FlowProblemInputBase {
+    classifications?: string;
+    /** When true, use min-cost-max-flow as the underlying solution
+     * space (requires edges to carry `cost`). */
+    optimal?: boolean;
+}
+declare const Flow: {
+    /**
+     * Build a max-flow problem.
+     *
+     * Emits one `flow_edge_constraint` per edge, one
+     * `flow_max_constraint` with the requested output binding, and a
+     * `flow_solve_constraint` trigger. Returns the constraint terms
+     * plus the names of every output variable.
+     */
+    maxFlow(input: MaxFlowInput): FlowProblem<MaxFlowVars>;
+    /**
+     * Build a min-cut problem.
+     *
+     * Emits `flow_min_cut_constraint` and binds `cut_value`,
+     * `cut_edges`, `source_side`, `sink_side` to the requested
+     * variable names (auto-generated when omitted).
+     */
+    minCut(input: MinCutInput): FlowProblem<MinCutVars>;
+    /**
+     * Build a min-cost-max-flow problem. Per-edge `cost` is required
+     * for the optimisation to be meaningful (defaults to 0 if absent).
+     */
+    minCostMaxFlow(input: MinCostMaxFlowInput): FlowProblem<MinCostMaxFlowVars>;
+    /**
+     * Build a Dulmage-Mendelsohn edge-classification problem.
+     *
+     * Each edge is classified as `"always"`, `"never"`, or
+     * `"sometimes"` used across the space of all max flows (or all
+     * min-cost max flows when `optimal: true`).
+     */
+    classifyEdges(input: ClassifyEdgesInput): FlowProblem<ClassifyEdgesVars>;
+    /** Low-level: build a single `flow_edge_constraint` psi-term. */
+    edge(from: FlowNode, to: FlowNode, cap: number, options?: FlowEdgeOptions): TermInputArg;
+    /** Low-level: build a single `flow_solve_constraint` psi-term. */
+    solve(source: FlowNode, sink: FlowNode): TermInputArg;
+    /**
+     * Low-level: build a single `flow_max_constraint` psi-term.
+     *
+     * @example
+     * ```typescript
+     * const constraints = [
+     *   Flow.edge('s', 'a', 10),
+     *   Flow.edge('a', 't', 10),
+     *   Flow.maxObjective({ source: 's', sink: 't', flowValue: '?V' }),
+     *   Flow.solve('s', 't'),
+     * ];
+     * ```
+     */
+    maxObjective(opts: {
+        source: FlowNode;
+        sink: FlowNode;
+        flowValue: string;
+    }): TermInputArg;
+    /** Low-level: build a single `flow_min_cut_constraint` psi-term. */
+    minCutObjective(opts: {
+        source: FlowNode;
+        sink: FlowNode;
+        cutValue: string;
+        cutEdges: string;
+        sourceSide: string;
+        sinkSide: string;
+    }): TermInputArg;
+    /** Low-level: build a single `flow_min_cost_max_flow_constraint` psi-term. */
+    minCostMaxFlowObjective(opts: {
+        source: FlowNode;
+        sink: FlowNode;
+        flowValue: string;
+        totalCost: string;
+    }): TermInputArg;
+    /** Low-level: build a single `flow_classify_edges_constraint` psi-term. */
+    classifyEdgesObjective(opts: {
+        source: FlowNode;
+        sink: FlowNode;
+        classifications: string;
+        optimal?: boolean;
+    }): TermInputArg;
+    /**
+     * Low-level: get the node-variable reference used to identify a
+     * node name in goals built by this builder. Exposed so callers
+     * composing constraints by hand can refer to the same logical node
+     * the high-level helpers would produce — e.g., to add a feature
+     * test on the same node term inside the same goal.
+     */
+    node(name: FlowNode): {
+        name: string;
+    };
+};
+
 /**
  * Check if a string matches UUID v4 format.
  *
@@ -44696,4 +45382,4 @@ declare function toUntaggedFeatures(features: PlainFeatureMap): Record<string, F
  */
 declare function toTermInputDto(input: PsiTermInput | TermInputDto): TermInputDto;
 
-export { ANY_ROLE, actionReviews as ActionReviews, type AddFactRequest, type AddFactResponse, type AddRuleRequest, type AddRuleResponse, admin as Admin, type AiGroup, analysis as Analysis, type AnalysisGroup, ApiError, type ApiResponse, type AuthConfig, AuthenticationError, type BackwardChainRequest, type BackwardChainResponse, BadRequestError, type BulkAddTermsRequest, type BulkAddTermsResponse, type BulkCreateSortsRequest, type BulkCreateSortsResponse, cdl as CDL, causal as Causal, type ClearTermsResponse, type ClientConfig, cognitive as Cognitive, collections as Collections, communities as Communities, compliance as Compliance, type ConstrainedPlainVar, ConstraintViolationError, constraints as Constraints, control as Control, conversation as Conversation, type ConversationMessageRequest, type ConversationMessageResponse, type ConversationSummaryDto, type ConversationTurnsResponse, type CoreGroup, type CreateResearchSessionRequest, type CreateResearchSessionResponse, type CreateSortRequest, type CreateTermRequest, type DataGroup, discovery as Discovery, type ErrorResponse$1 as ErrorResponse, execution as Execution, extract as Extract, type FeatureInputValueDto, type FeatureValueDto, flowNetworks as FlowNetworks, ForbiddenError, type ForwardChainRequest, type ForwardChainResponse, functions as Functions, fuzzy as Fuzzy, FuzzyShape, type FuzzyShapeDto, generation as Generation, type GlbRequest, type GlbResponse, health as Health, homoiconic as Homoiconic, ilp as ILP, imageExtraction as ImageExtraction, inference as Inference, type IngestPaperRequest, type IngestPaperResponse, ingestion as Ingestion, IngestionFailedError, IngestionSession, type IngestionSyncOptions, type Interceptor, InternalServerError, type JsonValue$1 as JsonValue, LP, type ListConversationsResponse, type LubRequest, type LubResponse, namespaces as Namespaces, NetworkError, neuroSymbolic as NeuroSymbolic, NotFoundError, ontology as Ontology, operations as Operations, optimize as Optimize, type OsfSearchRequest, type OsfSearchResponse, osfql as Osfql, type OsfqlRequest, type OsfqlResponse, type OsfqlValue, oversight as Oversight, type PaginationParams, type PaperMetadataDto, type PaperSource, type PlainFeatureMap, type PlainFeatureValue, plainValues as PlainValues, preferences as Preferences, proofEngine as ProofEngine, type PsiTermDto, type PsiTermInput, query as Query, rag as RAG, RateLimitError, type RateLimitInfo, reasoning as Reasoning, type ReasoningGroup, ReasoningLayerClient, ReasoningLayerError, type RequestOptions, research as Research, type ResearchContradictionsResponse, type ResearchCycleResponse, type ResearchFindingsResponse, type ResearchGapsResponse, type ResearchReportResponse, type ResearchSessionResponse, reviews as Reviews, row as Row, SDK_VERSION, scenarios as Scenarios, scheduling as Scheduling, type SearchPapersRequest, type SearchPapersResponse, SortBuilder, type SortDto, type SortInfoDto, sorts as Sorts, sources as Sources, spaces as Spaces, statistical as Statistical, synthetic as Synthetic, type SystemGroup, type TermDto, type TermInputArg, type TermInputDto, type TermListResponse, type TermPatternDto, type TermResponse, terms as Terms, TimeoutError, type TurnDto, type UpdateTermRequest, utilities as Utilities, ValidationError, Value, type ValueDto, values as Values, type VerifyClaimRequest, type VerifyClaimResponse, visualization as Visualization, WebSocketClient, WebSocketConnection, webhookActions as WebhookActions, type WorkflowGroup, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };
+export { ANY_ROLE, actionReviews as ActionReviews, type AddFactRequest, type AddFactResponse, type AddRuleRequest, type AddRuleResponse, admin as Admin, type AiGroup, analysis as Analysis, type AnalysisGroup, ApiError, type ApiResponse, type ArithmeticOp, type AuthConfig, AuthenticationError, type BackwardChainRequest, type BackwardChainResponse, BadRequestError, type BulkAddTermsRequest, type BulkAddTermsResponse, type BulkCreateSortsRequest, type BulkCreateSortsResponse, cdl as CDL, causal as Causal, type ClassifyEdgesInput, type ClassifyEdgesVars, type ClearTermsResponse, type ClientConfig, cognitive as Cognitive, collections as Collections, communities as Communities, type ComparisonOp, compliance as Compliance, type ConstrainedPlainVar, Constraint, ConstraintViolationError, constraints as Constraints, control as Control, conversation as Conversation, type ConversationMessageRequest, type ConversationMessageResponse, type ConversationSummaryDto, type ConversationTurnsResponse, type CoreGroup, type CreateResearchSessionRequest, type CreateResearchSessionResponse, type CreateSortRequest, type CreateTermRequest, type DataGroup, discovery as Discovery, type ErrorResponse$1 as ErrorResponse, execution as Execution, extract as Extract, type FeatureInputValueDto, type FeatureValueDto, Flow, type FlowProblem as FlowBuilderProblem, type FlowEdgeInput, type FlowEdgeOptions, flowNetworks as FlowNetworks, type FlowNode, type FlowProblemInputBase, ForbiddenError, type ForwardChainRequest, type ForwardChainResponse, functions as Functions, fuzzy as Fuzzy, FuzzyShape, type FuzzyShapeDto, generation as Generation, type GlbRequest, type GlbResponse, health as Health, homoiconic as Homoiconic, ilp as ILP, imageExtraction as ImageExtraction, inference as Inference, type IngestPaperRequest, type IngestPaperResponse, ingestion as Ingestion, IngestionFailedError, IngestionSession, type IngestionSyncOptions, type Interceptor, InternalServerError, type JsonValue$1 as JsonValue, LP, type ListConversationsResponse, type LubRequest, type LubResponse, type MaxFlowInput, type MaxFlowVars, type MinCostMaxFlowInput, type MinCostMaxFlowVars, type MinCutInput, type MinCutVars, namespaces as Namespaces, NetworkError, neuroSymbolic as NeuroSymbolic, NotFoundError, ontology as Ontology, type Operand, operations as Operations, optimize as Optimize, type OsfSearchRequest, type OsfSearchResponse, osfql as Osfql, type OsfqlRequest, type OsfqlResponse, type OsfqlValue, oversight as Oversight, type PaginationParams, type PaperMetadataDto, type PaperSource, type PlainFeatureMap, type PlainFeatureValue, plainValues as PlainValues, preferences as Preferences, proofEngine as ProofEngine, type PsiTermDto, type PsiTermInput, query as Query, rag as RAG, RateLimitError, type RateLimitInfo, reasoning as Reasoning, type ReasoningGroup, ReasoningLayerClient, ReasoningLayerError, type RequestOptions, research as Research, type ResearchContradictionsResponse, type ResearchCycleResponse, type ResearchFindingsResponse, type ResearchGapsResponse, type ResearchReportResponse, type ResearchSessionResponse, reviews as Reviews, row as Row, SDK_VERSION, scenarios as Scenarios, scheduling as Scheduling, type SearchPapersRequest, type SearchPapersResponse, SortBuilder, type SortDto, type SortInfoDto, sorts as Sorts, sources as Sources, spaces as Spaces, statistical as Statistical, synthetic as Synthetic, type SystemGroup, type TermDto, type TermInputArg, type TermInputDto, type TermListResponse, type TermPatternDto, type TermResponse, terms as Terms, TimeoutError, type TurnDto, type UpdateTermRequest, utilities as Utilities, ValidationError, Value, type ValueDto, values as Values, type VerifyClaimRequest, type VerifyClaimResponse, visualization as Visualization, WebSocketClient, WebSocketConnection, webhookActions as WebhookActions, type WorkflowGroup, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };