@kortexya/reasoninglayer 0.20.0 → 0.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 = "0.20.0";
+declare const SDK_VERSION = "0.22.0";
 /**
  * Configuration for the Reasoning Layer client.
  *
@@ -571,6 +571,55 @@ interface AddPendingReviewResponse {
     /** @format uuid */
     review_id: string;
 }
+/**
+ * Request body for `POST /api/v1/scheduling/problems/{id}/pins`.
+ *
+ * Same shape as the `PinInput` used inside a problem-creation
+ * request, but carried alone — the URL identifies the target
+ * problem.
+ */
+interface AddPinRequest$1 {
+    agent_id: string;
+    /** @min 0 */
+    day: number;
+    role?: string | null;
+    /** @min 0 */
+    shift: number;
+}
+/**
+ * Response from `POST /api/v1/scheduling/problems/{id}/pins`.
+ *
+ * `pin_id` is the [`TermId`] of the newly-created pin Ψ-term —
+ * the stable handle for subsequent removal via
+ * `DELETE /api/v1/scheduling/problems/{id}/pins/{pin_id}`.
+ */
+interface AddPinResponse$1 {
+    pin_id: string;
+    /**
+     * Problem version after the mutation.
+     * @format int64
+     */
+    version: number;
+}
+/** Request body for `POST /api/v1/scheduling/problems/{id}/preferences`. */
+interface AddPreferenceRequest$1 {
+    agent_id: string;
+    /** @min 0 */
+    day: number;
+    /** @format int64 */
+    score: number;
+    /** @min 0 */
+    shift: number;
+}
+/** Response from `POST /api/v1/scheduling/problems/{id}/preferences`. */
+interface AddPreferenceResponse$1 {
+    preference_id: string;
+    /**
+     * Problem version after the mutation.
+     * @format int64
+     */
+    version: number;
+}
 /** Request to add a rule (a term with antecedents). */
 interface AddRuleRequest$1 {
     /**
@@ -3417,6 +3466,34 @@ type CreateScenarioResponse$1 = {
     /** @min 0 */
     total_time_ms: number;
 };
+/**
+ * Request body for `POST /api/v1/scheduling/problems`.
+ *
+ * Same inline shape as [`SchedulingOptimizeRequest`].  The endpoint
+ * freezes the inputs into a `scheduling.problem` Ψ-term snapshot
+ * stored in the application-layer scheduling store and returns the
+ * snapshot's `problem_id`.  Re-solving reads only the snapshot,
+ * matching the user's "snapshot mode" decision.
+ */
+interface CreateSchedulingProblemRequest$1 {
+    agents: AgentInput[];
+    /** @min 0 */
+    days: number;
+    demands: ShiftDemandInput[];
+    pins?: PinInput[];
+    preferences?: PreferenceInput[];
+    /** @min 0 */
+    shifts_per_day: number;
+}
+/** Response to `POST /api/v1/scheduling/problems`. */
+interface CreateSchedulingProblemResponse$1 {
+    /**
+     * UUID-formatted ID of the stored `scheduling.problem` snapshot
+     * term.  Use this in subsequent `/scheduling/problems/{id}/...`
+     * calls.
+     */
+    problem_id: string;
+}
 /** Request to create a live oversight session. */
 interface CreateSessionRequest {
     /** Optional pipeline configuration overrides */
@@ -11487,6 +11564,17 @@ interface PendingReviewEntityDto {
     /** Original text span that was extracted */
     source_text?: string | null;
 }
+/** Pin entry in [`SchedulingProblemDto`]. */
+interface PinEntryDto {
+    agent_id: string;
+    /** @min 0 */
+    day: number;
+    /** Stable ID for `DELETE /api/v1/scheduling/problems/{id}/pins/{pin_id}`. */
+    pin_id: string;
+    role?: string | null;
+    /** @min 0 */
+    shift: number;
+}
 /**
  * A pre-assigned `(agent, day, shift)` triple, optionally naming
  * which role the pin covers.
@@ -11812,6 +11900,48 @@ interface PreferenceDto$1 {
     /** Preference value. */
     value: string;
 }
+/** Preference entry in [`SchedulingProblemDto`]. */
+interface PreferenceEntryDto {
+    agent_id: string;
+    /** @min 0 */
+    day: number;
+    /** Stable ID for `DELETE /api/v1/scheduling/problems/{id}/preferences/{preference_id}`. */
+    preference_id: string;
+    /** @format int64 */
+    score: number;
+    /** @min 0 */
+    shift: number;
+}
+/**
+ * A soft preference: bias the optimizer toward (or against) assigning
+ * `agent_id` to cell `(day, shift)`.
+ *
+ * `score` contributes to the objective when the cell is assigned in
+ * the chosen schedule.  Positive values pull the optimizer toward
+ * the cell; negative values push it away.
+ *
+ * Preferences targeting a structurally infeasible cell (the agent
+ * has a day-off on `day`, is restricted to a different shift, or
+ * otherwise cannot occupy the slot) are silently ignored — the
+ * agent cannot fill the cell, so the preference cannot fire.
+ *
+ * Preferences targeting a **pinned** cell *do* contribute to
+ * `total_score`: pins force the agent into the cell, so the
+ * preference is realised in the chosen schedule.
+ */
+interface PreferenceInput {
+    agent_id: string;
+    /** @min 0 */
+    day: number;
+    /**
+     * Score contributed by this assignment to the optimizer's
+     * objective.  Positive = preferred, negative = avoided.
+     * @format int64
+     */
+    score: number;
+    /** @min 0 */
+    shift: number;
+}
 /** Prediction result for a single term */
 interface PreferencePrediction$1 {
     /** @format double */
@@ -13700,6 +13830,22 @@ interface ScenarioSummaryDto$1 {
      */
     sorts_created: number;
 }
+/**
+ * Response to `GET /api/v1/scheduling/problems/{id}/assignments`.
+ *
+ * One entry per `(agent, day, shift)` cell that was lifted from
+ * the optimum's per-cell envelope, including `free` cells (per
+ * the materialise decision so downstream rules can residuate).
+ */
+interface SchedulingAssignmentsResponse$1 {
+    assignments: AssignmentDto[];
+    /**
+     * `total_score` of the most recent solve, or `0` when the
+     * problem has never been solved.
+     * @format int64
+     */
+    total_score: number;
+}
 /**
  * A scheduling feasibility request.
  *
@@ -13741,6 +13887,88 @@ interface SchedulingFeasibilityResponse$1 {
     /** Top-level request status. */
     status: SchedulingStatusDto;
 }
+/**
+ * Request body for `POST /api/v1/scheduling/optimize`.
+ *
+ * Same hard-constraint shape as
+ * [`SchedulingFeasibilityRequest`], plus a list of soft
+ * `preferences`.  The engine returns the per-cell envelope across
+ * the space of **optimal** schedules under the supplied
+ * preferences.
+ */
+interface SchedulingOptimizeRequest$1 {
+    agents: AgentInput[];
+    /** @min 0 */
+    days: number;
+    demands: ShiftDemandInput[];
+    pins?: PinInput[];
+    /**
+     * Soft preferences applied to the objective.  Empty = unweighted
+     * (every feasible schedule is "optimal").
+     */
+    preferences?: PreferenceInput[];
+    /** @min 0 */
+    shifts_per_day: number;
+}
+/**
+ * Response to [`SchedulingOptimizeRequest`].
+ *
+ * The per-cell `assignments` trichotomy classifies each cell over
+ * the space of **optimal** schedules — strictly stronger than the
+ * feasibility-only trichotomy returned by
+ * `/api/v1/scheduling/feasibility`.  When the un-pinned reduced
+ * problem is infeasible, `status = "infeasible"`, `assignments` is
+ * empty, and `total_score` is `0`.
+ */
+interface SchedulingOptimizeResponse$1 {
+    /**
+     * Empty when `status` is `infeasible`; otherwise one entry per
+     * `(agent, day, shift)` triple in the input grid, with
+     * trichotomy taken across the space of optimal schedules.
+     */
+    assignments: AssignmentDto[];
+    /** Top-level request status. */
+    status: SchedulingStatusDto;
+    /**
+     * Sum of [`PreferenceInput::score`] over assigned cells in the
+     * optimum.  `0` when no preferences were supplied or the
+     * problem is infeasible.
+     * @format int64
+     */
+    total_score: number;
+}
+/**
+ * Response from `GET /api/v1/scheduling/problems/{id}`.
+ *
+ * Snapshot of the live problem state — agents and demands as
+ * supplied at creation time, plus the *current* set of pins and
+ * preferences (including their stable child IDs).  Use the IDs
+ * here when building DELETE calls.
+ */
+interface SchedulingProblemDto {
+    /** @min 0 */
+    days: number;
+    /** Status of the most recent solve, or `None` if never solved. */
+    latest_solve_status?: null | SchedulingStatusDto;
+    /** Pins currently on the problem. */
+    pins: PinEntryDto[];
+    /** Preferences currently on the problem. */
+    preferences: PreferenceEntryDto[];
+    problem_id: string;
+    /** @min 0 */
+    shifts_per_day: number;
+    /**
+     * Score of the most recent solve, or `0` if never solved.
+     * @format int64
+     */
+    total_score: number;
+    /**
+     * Bumped on every input mutation (add/remove pin or preference).
+     * Solving does not bump it.
+     * @format int64
+     */
+    version: number;
+}
 /** Top-level request status. */
 type SchedulingStatusDto = "feasible" | "infeasible";
 /** Request to search communities */
@@ -14171,6 +14399,26 @@ interface SolveConstraintResponse$1 {
     success: boolean;
     suspended_constraints: string[];
 }
+/**
+ * Response to `POST /api/v1/scheduling/problems/{id}/solve`.
+ *
+ * Re-solving an already-solved problem replaces the previously
+ * derived `scheduling.assignment` Ψ-terms.  Per-cell trichotomy
+ * must be fetched separately via
+ * `GET /scheduling/problems/{id}/assignments` (so a successful
+ * re-solve carries minimal payload).
+ */
+interface SolveSchedulingProblemResponse$1 {
+    /** Top-level request status. */
+    status: SchedulingStatusDto;
+    /**
+     * Sum of [`PreferenceInput::score`] over assigned cells in the
+     * optimum.  `0` when no preferences were supplied or the
+     * problem is infeasible.
+     * @format int64
+     */
+    total_score: number;
+}
 /** Response with ancestor sorts */
 interface SortAncestorsResponse {
     ancestors: SortInfoDto$1[];
@@ -16927,11 +17175,10 @@ declare class Sorts<SecurityDataType = unknown> {
      */
     getSortSimilarity: (data: GetSortSimilarityRequest$1, params?: RequestParams) => Promise<HttpResponse<GetSortSimilarityResponse$1, any>>;
     /**
-     * @description This enables semantic search over sort names for NER label pre-filtering. Must be called after bulk sort creation (e.g., after ontology hydration) to make sorts searchable via embedding similarity. Returns the number of sorts indexed.
+     * No description
      *
      * @tags sorts
      * @name IndexSorts
-     * @summary Index all sorts for a tenant into the vector store (Qdrant).
      * @request POST:/api/v1/sorts/index
      * @secure
      */
@@ -16988,6 +17235,12 @@ declare class Sorts<SecurityDataType = unknown> {
         limit?: number | null;
         /** Filter to only show LLM-extracted sorts */
         llm_extracted?: boolean | null;
+        /**
+         * Filter to sorts whose name starts with this prefix.
+         * Supports comma-separated multiple prefixes (e.g. "drug_,target_,pathway_,disease_").
+         * Server-side filtering avoids transferring millions of irrelevant sorts.
+         */
+        name_prefix?: string | null;
         /** Filter to only show sorts needing review */
         needs_review?: boolean | null;
         /**
@@ -39289,6 +39542,33 @@ declare class OptimizeClient {
 declare class Scheduling<SecurityDataType = unknown> {
     http: HttpClient<SecurityDataType>;
     constructor(http: HttpClient<SecurityDataType>);
+    /**
+     * No description
+     *
+     * @tags scheduling
+     * @name AddPin
+     * @summary `POST /api/v1/scheduling/problems/{id}/pins`
+     * @request POST:/api/v1/scheduling/problems/{problem_id}/pins
+     */
+    addPin: (problemId: string, data: AddPinRequest$1, params?: RequestParams) => Promise<HttpResponse<AddPinResponse$1, void>>;
+    /**
+     * No description
+     *
+     * @tags scheduling
+     * @name AddPreference
+     * @summary `POST /api/v1/scheduling/problems/{id}/preferences`
+     * @request POST:/api/v1/scheduling/problems/{problem_id}/preferences
+     */
+    addPreference: (problemId: string, data: AddPreferenceRequest$1, params?: RequestParams) => Promise<HttpResponse<AddPreferenceResponse$1, void>>;
+    /**
+     * @description Freeze the inline scheduling inputs into a `scheduling.problem` Ψ-term snapshot stored in the application-layer scheduling store, and return its ID.  The endpoint does NOT solve — call `POST /api/v1/scheduling/problems/{id}/solve` to compute the optimum, then `GET /api/v1/scheduling/problems/{id}/assignments` to retrieve the per-cell trichotomy. Snapshot mode: subsequent re-solves read only the snapshot, not any source terms in the KB.  This keeps the optimum reproducible and auditable from the moment the problem is created.
+     *
+     * @tags scheduling
+     * @name CreateProblem
+     * @summary `POST /api/v1/scheduling/problems`
+     * @request POST:/api/v1/scheduling/problems
+     */
+    createProblem: (data: CreateSchedulingProblemRequest$1, params?: RequestParams) => Promise<HttpResponse<CreateSchedulingProblemResponse$1, void>>;
     /**
      * @description Classify every `(agent, day, shift)` cell in the input grid as confirmed-true, confirmed-false, or free, and list the role(s) each cell could cover. Input validation errors (duplicate agent IDs, out-of-range pins, role minima exceeding total demand, pin role the agent doesn't have, pin on a multi-role agent where the role is ambiguous, etc.) return HTTP 400. Infeasibility of a well-formed problem is a valid answer and returns HTTP 200 with `status = "infeasible"` and an empty `assignments` list.
      *
@@ -39298,6 +39578,60 @@ declare class Scheduling<SecurityDataType = unknown> {
      * @request POST:/api/v1/scheduling/feasibility
      */
     feasibility: (data: SchedulingFeasibilityRequest$1, params?: RequestParams) => Promise<HttpResponse<SchedulingFeasibilityResponse$1, void>>;
+    /**
+     * No description
+     *
+     * @tags scheduling
+     * @name GetProblem
+     * @summary `GET /api/v1/scheduling/problems/{id}` — read the current state.
+     * @request GET:/api/v1/scheduling/problems/{problem_id}
+     */
+    getProblem: (problemId: string, params?: RequestParams) => Promise<HttpResponse<SchedulingProblemDto, void>>;
+    /**
+     * @description Retrieve the derived `scheduling.assignment` Ψ-terms produced by the most recent solve.  Returns an empty list when the problem has never been solved, or when the problem ID isn't known for this tenant.  Includes `free` cells (per the materialise decision) so consumers can residuate on them.
+     *
+     * @tags scheduling
+     * @name ListAssignments
+     * @summary `GET /api/v1/scheduling/problems/{id}/assignments`
+     * @request GET:/api/v1/scheduling/problems/{problem_id}/assignments
+     */
+    listAssignments: (problemId: string, params?: RequestParams) => Promise<HttpResponse<SchedulingAssignmentsResponse$1, void>>;
+    /**
+     * @description Same hard constraints as `/scheduling/feasibility` plus a list of soft `preferences` (each a per-cell score added to the optimizer's objective).  Returns the per-cell trichotomy across the space of **optimal** schedules, plus `total_score` (sum of preference scores at chosen cells in the optimum). `confirmed_true` / `confirmed_false` here are stronger than in `/feasibility`: they hold across every optimum, not every feasible schedule.  Cells with status `free` indicate ties — multiple optima exist and the cell varies between them. Preferences targeting structurally infeasible cells (agent has a day-off on the day, is restricted to a different shift, or otherwise cannot occupy the slot) are silently ignored — the preference cannot fire when the agent cannot be there.  Preferences targeting **pinned** cells DO contribute to `total_score`: pins force the agent into the cell, so the preference is realised by the chosen schedule.
+     *
+     * @tags scheduling
+     * @name Optimize
+     * @summary `POST /api/v1/scheduling/optimize`
+     * @request POST:/api/v1/scheduling/optimize
+     */
+    optimize: (data: SchedulingOptimizeRequest$1, params?: RequestParams) => Promise<HttpResponse<SchedulingOptimizeResponse$1, void>>;
+    /**
+     * No description
+     *
+     * @tags scheduling
+     * @name RemovePin
+     * @summary `DELETE /api/v1/scheduling/problems/{id}/pins/{pin_id}`
+     * @request DELETE:/api/v1/scheduling/problems/{problem_id}/pins/{pin_id}
+     */
+    removePin: (problemId: string, pinId: string, params?: RequestParams) => Promise<HttpResponse<void, void>>;
+    /**
+     * No description
+     *
+     * @tags scheduling
+     * @name RemovePreference
+     * @summary `DELETE /api/v1/scheduling/problems/{id}/preferences/{preference_id}`
+     * @request DELETE:/api/v1/scheduling/problems/{problem_id}/preferences/{preference_id}
+     */
+    removePreference: (problemId: string, preferenceId: string, params?: RequestParams) => Promise<HttpResponse<void, void>>;
+    /**
+     * @description Re-solve the stored snapshot: project it back into a domain `SchedulingProblem`, run the optimizer, and lift the per-cell trichotomy into `scheduling.assignment` Ψ-terms (idempotent — previous derived assignments for this problem are replaced). Returns only `status` and `total_score`; fetch the per-cell trichotomy via `/assignments`.
+     *
+     * @tags scheduling
+     * @name SolveProblem
+     * @summary `POST /api/v1/scheduling/problems/{id}/solve`
+     * @request POST:/api/v1/scheduling/problems/{problem_id}/solve
+     */
+    solveProblem: (problemId: string, params?: RequestParams) => Promise<HttpResponse<SolveSchedulingProblemResponse$1, void>>;
 }
 
 /**
@@ -39456,18 +39790,279 @@ interface SchedulingFeasibilityResponse {
     status: SchedulingStatus;
     assignments: Assignment[];
 }
+/**
+ * A soft preference: bias the optimizer toward (or against) assigning
+ * `agentId` to cell `(day, shift)`.
+ *
+ * @remarks
+ * `score` contributes to the optimizer's objective when the cell is
+ * assigned in the chosen schedule.  Positive values pull the optimizer
+ * toward the cell; negative values push it away.
+ *
+ * Preferences targeting a cell that is already pinned, blocked by a
+ * day-off, restricted-to-shift, or otherwise structurally fixed are
+ * silently ignored — those cells are not the optimizer's choice to
+ * make.
+ *
+ * Common encodings:
+ *   - "Aisha prefers morning shifts" → `score = +5` on every
+ *     `(aisha, day, morning)` pair
+ *   - "Avoid weekend assignments" → `score = -3` on every
+ *     `(*, sat|sun, *)` pair
+ *   - "Honor day-off requests" → `score = -100` on
+ *     `(agent, requested_off_day, *)` (large negative penalty —
+ *     respects the request when feasible, lets the engine decide
+ *     when not)
+ */
+interface Preference {
+    agentId: string;
+    day: number;
+    shift: number;
+    /**
+     * Score added to the objective when this cell is assigned in the
+     * chosen schedule.  Positive = preferred, negative = avoided.
+     */
+    score: number;
+}
+/**
+ * Input to {@link SchedulingClient.optimize}.
+ *
+ * @remarks
+ * Same hard-constraint shape as {@link SchedulingFeasibilityRequest}
+ * plus a list of soft `preferences`.  The engine returns the per-cell
+ * envelope across the space of **optimal** schedules under the
+ * supplied preferences.
+ */
+interface SchedulingOptimizeRequest {
+    agents: AgentSpec[];
+    days: number;
+    shiftsPerDay: number;
+    demands: ShiftDemand[];
+    /** Pre-assigned `(agent, day, shift)` triples.  Defaults to empty. */
+    pins?: Pin[];
+    /**
+     * Soft preferences applied to the objective.  Empty (or omitted) =
+     * unweighted: every feasible schedule is "optimal" and the result
+     * coincides with {@link SchedulingClient.feasibility}.
+     */
+    preferences?: Preference[];
+}
+/**
+ * Response from {@link SchedulingClient.optimize}.
+ *
+ * @remarks
+ * The per-cell `assignments` trichotomy classifies each cell over the
+ * space of **optimal** schedules — strictly stronger than the
+ * feasibility-only trichotomy from
+ * {@link SchedulingClient.feasibility}:
+ *
+ *   - `"confirmed_true"` — assigned in *every* optimal schedule.
+ *   - `"confirmed_false"` — assigned in *no* optimal schedule.
+ *   - `"free"` — varies across the (possibly multiple) optimal
+ *     schedules; the optimizer is indifferent.
+ *
+ * `totalScore` is the sum of {@link Preference.score} over assigned
+ * cells in the optimum.  It is `0` when no preferences were supplied
+ * or the problem is infeasible.
+ */
+interface SchedulingOptimizeResponse {
+    status: SchedulingStatus;
+    /** Sum of preference scores at chosen cells in the optimum. */
+    totalScore: number;
+    /**
+     * Empty when `status === "infeasible"`; otherwise one entry per
+     * `(agent, day, shift)` triple in the input grid.
+     */
+    assignments: Assignment[];
+}
+/**
+ * Input to {@link SchedulingClient.createProblem}.
+ *
+ * @remarks
+ * Same inline shape as {@link SchedulingOptimizeRequest}.  The
+ * server freezes the inputs into a `scheduling.problem` Ψ-term
+ * snapshot, stores it under the caller's tenant, and returns the
+ * snapshot's `problemId`.  Subsequent re-solves
+ * ({@link SchedulingClient.solveProblem}) read only the snapshot —
+ * mutations to the source data after creation do not affect the
+ * stored problem, keeping every solve reproducible and auditable.
+ */
+interface CreateSchedulingProblemRequest {
+    agents: AgentSpec[];
+    days: number;
+    shiftsPerDay: number;
+    demands: ShiftDemand[];
+    /** Pre-assigned `(agent, day, shift)` triples.  Defaults to empty. */
+    pins?: Pin[];
+    /** Soft preferences applied to the optimum's objective.  Defaults to empty. */
+    preferences?: Preference[];
+}
+/**
+ * Response from {@link SchedulingClient.createProblem}.
+ */
+interface CreateSchedulingProblemResponse {
+    /**
+     * UUID of the stored `scheduling.problem` snapshot term.  Use it
+     * in subsequent `solveProblem` / `listAssignments` calls.
+     */
+    problemId: string;
+}
+/**
+ * Response from {@link SchedulingClient.solveProblem}.
+ *
+ * @remarks
+ * Re-solving an already-solved problem replaces the previously
+ * lifted `scheduling.assignment` Ψ-terms (idempotent).  Per-cell
+ * trichotomy must be fetched separately via
+ * {@link SchedulingClient.listAssignments} so a successful
+ * re-solve carries minimal payload.
+ */
+interface SolveSchedulingProblemResponse {
+    status: SchedulingStatus;
+    /**
+     * Sum of {@link Preference.score} over chosen cells in the
+     * optimum.  `0` when no preferences were supplied or the problem
+     * is infeasible.
+     */
+    totalScore: number;
+}
+/**
+ * Response from {@link SchedulingClient.listAssignments}.
+ *
+ * @remarks
+ * One entry per `(agent, day, shift)` cell that was lifted from
+ * the optimum — including `free` cells, so consumers can residuate
+ * on cells the optimizer is indifferent about.  Empty when the
+ * problem has never been solved.
+ *
+ * `totalScore` mirrors the most recent solve's optimum value, or
+ * `0` when the problem hasn't been solved yet.
+ */
+interface SchedulingAssignmentsResponse {
+    totalScore: number;
+    assignments: Assignment[];
+}
+/**
+ * Input to {@link SchedulingClient.addPin}.
+ *
+ * @remarks
+ * Same field set as {@link Pin}; the URL identifies the target
+ * problem.  Returns a `pinId` that callers retain for subsequent
+ * removal.
+ */
+interface AddPinRequest {
+    agentId: string;
+    day: number;
+    shift: number;
+    role?: string;
+}
+interface AddPinResponse {
+    /**
+     * Stable handle for `removePin(problemId, pinId)`.  UUID-formatted.
+     */
+    pinId: string;
+    /** Problem version after this mutation. */
+    version: number;
+}
+/**
+ * Input to {@link SchedulingClient.addPreference}.
+ */
+interface AddPreferenceRequest {
+    agentId: string;
+    day: number;
+    shift: number;
+    score: number;
+}
+interface AddPreferenceResponse {
+    /**
+     * Stable handle for
+     * `removePreference(problemId, preferenceId)`.  UUID-formatted.
+     */
+    preferenceId: string;
+    /** Problem version after this mutation. */
+    version: number;
+}
+/**
+ * One pin currently on the problem, as returned by
+ * {@link SchedulingClient.getProblem}.  Carries the stable
+ * `pinId` to use when calling
+ * {@link SchedulingClient.removePin}.
+ */
+interface PinEntry {
+    pinId: string;
+    agentId: string;
+    day: number;
+    shift: number;
+    role?: string;
+}
+/**
+ * One preference currently on the problem, as returned by
+ * {@link SchedulingClient.getProblem}.  Carries the stable
+ * `preferenceId` to use when calling
+ * {@link SchedulingClient.removePreference}.
+ */
+interface PreferenceEntry {
+    preferenceId: string;
+    agentId: string;
+    day: number;
+    shift: number;
+    score: number;
+}
+/**
+ * Current state of a stored problem returned by
+ * {@link SchedulingClient.getProblem}.
+ *
+ * @remarks
+ * `pins` and `preferences` carry the stable IDs needed for
+ * subsequent removal.  `version` is bumped on every input edit
+ * (add/remove pin or preference); solving does NOT bump it —
+ * solves are derivations, not edits.  `latestSolveStatus` is
+ * `undefined` until the first successful solve.
+ */
+interface SchedulingProblem {
+    problemId: string;
+    days: number;
+    shiftsPerDay: number;
+    version: number;
+    pins: PinEntry[];
+    preferences: PreferenceEntry[];
+    /**
+     * Score of the most recent solve, or `0` if the problem has
+     * never been solved.
+     */
+    totalScore: number;
+    /**
+     * Status of the most recent solve, or `undefined` if the
+     * problem has never been solved.
+     */
+    latestSolveStatus?: SchedulingStatus;
+}
 
 declare const scheduling_ANY_ROLE: typeof ANY_ROLE;
+type scheduling_AddPinRequest = AddPinRequest;
+type scheduling_AddPinResponse = AddPinResponse;
+type scheduling_AddPreferenceRequest = AddPreferenceRequest;
+type scheduling_AddPreferenceResponse = AddPreferenceResponse;
 type scheduling_AgentSpec = AgentSpec;
 type scheduling_Assignment = Assignment;
 type scheduling_AssignmentStatus = AssignmentStatus;
+type scheduling_CreateSchedulingProblemRequest = CreateSchedulingProblemRequest;
+type scheduling_CreateSchedulingProblemResponse = CreateSchedulingProblemResponse;
 type scheduling_Pin = Pin;
+type scheduling_PinEntry = PinEntry;
+type scheduling_Preference = Preference;
+type scheduling_PreferenceEntry = PreferenceEntry;
+type scheduling_SchedulingAssignmentsResponse = SchedulingAssignmentsResponse;
 type scheduling_SchedulingFeasibilityRequest = SchedulingFeasibilityRequest;
 type scheduling_SchedulingFeasibilityResponse = SchedulingFeasibilityResponse;
+type scheduling_SchedulingOptimizeRequest = SchedulingOptimizeRequest;
+type scheduling_SchedulingOptimizeResponse = SchedulingOptimizeResponse;
+type scheduling_SchedulingProblem = SchedulingProblem;
 type scheduling_SchedulingStatus = SchedulingStatus;
 type scheduling_ShiftDemand = ShiftDemand;
+type scheduling_SolveSchedulingProblemResponse = SolveSchedulingProblemResponse;
 declare namespace scheduling {
-  export { scheduling_ANY_ROLE as ANY_ROLE, type scheduling_AgentSpec as AgentSpec, type scheduling_Assignment as Assignment, type scheduling_AssignmentStatus as AssignmentStatus, type scheduling_Pin as Pin, type scheduling_SchedulingFeasibilityRequest as SchedulingFeasibilityRequest, type scheduling_SchedulingFeasibilityResponse as SchedulingFeasibilityResponse, type scheduling_SchedulingStatus as SchedulingStatus, type scheduling_ShiftDemand as ShiftDemand };
+  export { scheduling_ANY_ROLE as ANY_ROLE, type scheduling_AddPinRequest as AddPinRequest, type scheduling_AddPinResponse as AddPinResponse, type scheduling_AddPreferenceRequest as AddPreferenceRequest, type scheduling_AddPreferenceResponse as AddPreferenceResponse, type scheduling_AgentSpec as AgentSpec, type scheduling_Assignment as Assignment, type scheduling_AssignmentStatus as AssignmentStatus, type scheduling_CreateSchedulingProblemRequest as CreateSchedulingProblemRequest, type scheduling_CreateSchedulingProblemResponse as CreateSchedulingProblemResponse, type scheduling_Pin as Pin, type scheduling_PinEntry as PinEntry, type scheduling_Preference as Preference, type scheduling_PreferenceEntry as PreferenceEntry, type scheduling_SchedulingAssignmentsResponse as SchedulingAssignmentsResponse, type scheduling_SchedulingFeasibilityRequest as SchedulingFeasibilityRequest, type scheduling_SchedulingFeasibilityResponse as SchedulingFeasibilityResponse, type scheduling_SchedulingOptimizeRequest as SchedulingOptimizeRequest, type scheduling_SchedulingOptimizeResponse as SchedulingOptimizeResponse, type scheduling_SchedulingProblem as SchedulingProblem, type scheduling_SchedulingStatus as SchedulingStatus, type scheduling_ShiftDemand as ShiftDemand, type scheduling_SolveSchedulingProblemResponse as SolveSchedulingProblemResponse };
 }
 
 /**
@@ -39539,6 +40134,186 @@ declare class SchedulingClient {
      * raises.
      */
     feasibility(request: SchedulingFeasibilityRequest): Promise<SchedulingFeasibilityResponse>;
+    /**
+     * Solve the scheduling problem with **soft preferences** and
+     * return the per-cell envelope across the space of *optimal*
+     * schedules.
+     *
+     * @param request - the scheduling problem plus optional
+     *   `preferences` (per-cell scores added to the optimizer's
+     *   objective).  Same hard-constraint shape as
+     *   {@link SchedulingClient.feasibility}.
+     * @returns a {@link SchedulingOptimizeResponse} with `totalScore`
+     *   and per-cell trichotomy across optimal schedules.
+     *
+     * @throws HTTP 400 errors are surfaced when the input is malformed
+     *   (duplicate agent IDs, pins or preferences referencing unknown
+     *   agents, ambiguous pin role on multi-role agents, role minima
+     *   exceeding total demand, etc.).
+     *
+     * @remarks
+     * The trichotomy returned here is **strictly stronger** than the
+     * one from {@link SchedulingClient.feasibility}:
+     *
+     *   - `"confirmed_true"` — assigned in *every* optimum.
+     *   - `"confirmed_false"` — assigned in *no* optimum.
+     *   - `"free"` — varies across the optima; the optimizer is indifferent
+     *     between equally-good choices.
+     *
+     * `totalScore` is the sum of {@link Preference.score} over assigned
+     * cells in the optimum (`0` when no preferences are supplied or
+     * the problem is infeasible).
+     *
+     * Preferences targeting structurally-fixed cells (pinned cells,
+     * day-off / shift-only restricted cells, agents not in the grid)
+     * are silently ignored — the optimizer has no choice to make there.
+     *
+     * Empty `preferences` is equivalent to calling
+     * {@link SchedulingClient.feasibility} (every feasible schedule
+     * is optimal under a zero objective), but slower; prefer
+     * `feasibility()` when you only need the feasibility envelope.
+     *
+     * @example Score Aisha as a strong preference for emergency cover
+     * ```typescript
+     * const report = await client.scheduling.optimize({
+     *   agents: [
+     *     { id: 'aisha', roles: ['icu', 'emergency'], maxAssignments: 5 },
+     *     { id: 'bob',   roles: ['general'],          maxAssignments: 5 },
+     *   ],
+     *   days: 7,
+     *   shiftsPerDay: 3,
+     *   demands: [{ day: 0, shift: 0, total: 2, roleMinimums: { icu: 1 } }],
+     *   preferences: [
+     *     { agentId: 'aisha', day: 0, shift: 0, score: 10 },
+     *   ],
+     * });
+     *
+     * console.log(report.totalScore);   // 10 if Aisha is in the optimum
+     * console.log(report.status);       // 'feasible' | 'infeasible'
+     * ```
+     */
+    optimize(request: SchedulingOptimizeRequest): Promise<SchedulingOptimizeResponse>;
+    /**
+     * Freeze the inline scheduling inputs into a `scheduling.problem`
+     * Ψ-term snapshot stored under the caller's tenant, and return the
+     * snapshot's `problemId`.  The endpoint does NOT solve — call
+     * {@link SchedulingClient.solveProblem} afterwards to compute the
+     * optimum, then {@link SchedulingClient.listAssignments} to fetch
+     * the per-cell trichotomy.
+     *
+     * @param request - same inline shape as
+     *   {@link SchedulingClient.optimize}.
+     * @returns the snapshot ID, useful for subsequent re-solves and
+     *   provenance lookups.
+     * @throws HTTP 400 on malformed input (duplicate agent IDs,
+     *   ambiguous pin role, unknown pin or preference agent ID,
+     *   role minima exceeding total demand, etc.).
+     *
+     * @remarks
+     * Re-solves read only the snapshot, so the optimum is reproducible
+     * and auditable from the moment the problem is created.  The
+     * snapshot persists across solves — pin a problem once, re-solve
+     * many times.
+     *
+     * @example
+     * ```typescript
+     * const { problemId } = await client.scheduling.createProblem({
+     *   agents: [{ id: 'alice', roles: ['icu'], maxAssignments: 3 }],
+     *   days: 7,
+     *   shiftsPerDay: 3,
+     *   demands: [{ day: 0, shift: 0, total: 1, roleMinimums: { icu: 1 } }],
+     *   preferences: [{ agentId: 'alice', day: 0, shift: 0, score: 5 }],
+     * });
+     * await client.scheduling.solveProblem(problemId);
+     * const { totalScore, assignments } =
+     *   await client.scheduling.listAssignments(problemId);
+     * ```
+     */
+    createProblem(request: CreateSchedulingProblemRequest): Promise<CreateSchedulingProblemResponse>;
+    /**
+     * Re-solve a previously-stored snapshot, lift the per-cell
+     * trichotomy into `scheduling.assignment` Ψ-terms (idempotent —
+     * previously lifted assignments are replaced), and return the
+     * optimum's `totalScore`.
+     *
+     * @param problemId - the ID returned by
+     *   {@link SchedulingClient.createProblem}.
+     * @throws HTTP 404 when the problem doesn't exist for the caller's
+     *   tenant.  HTTP 400 for malformed problem IDs.
+     *
+     * @remarks
+     * Returns only `status` and `totalScore`; fetch the per-cell
+     * trichotomy with {@link SchedulingClient.listAssignments}.
+     * Re-running this method on the same `problemId` is safe — the
+     * lifted assignment terms are replaced atomically.
+     */
+    solveProblem(problemId: string): Promise<SolveSchedulingProblemResponse>;
+    /**
+     * Retrieve the lifted `scheduling.assignment` Ψ-terms produced by
+     * the most recent solve.
+     *
+     * @param problemId - the ID returned by
+     *   {@link SchedulingClient.createProblem}.
+     * @throws HTTP 404 when the problem doesn't exist for the caller's
+     *   tenant.  HTTP 400 for malformed problem IDs.
+     *
+     * @remarks
+     * Returns one entry per `(agent, day, shift)` cell — including
+     * `free` cells, so consumers can residuate on cells the optimizer
+     * is indifferent about.  `assignments` is empty when the problem
+     * exists but hasn't been solved yet.
+     *
+     * `totalScore` mirrors the most recent solve's optimum value, or
+     * `0` when the problem hasn't been solved.
+     */
+    listAssignments(problemId: string): Promise<SchedulingAssignmentsResponse>;
+    /**
+     * Read the current state of a stored problem — its pins,
+     * preferences, version counter, and latest-solve metadata.
+     *
+     * @remarks
+     * Pin and preference entries carry stable IDs (`pinId`,
+     * `preferenceId`) — pass those to {@link SchedulingClient.removePin}
+     * / {@link SchedulingClient.removePreference} to delete them.
+     *
+     * @throws HTTP 404 when the problem doesn't exist for the
+     *   caller's tenant.
+     */
+    getProblem(problemId: string): Promise<SchedulingProblem>;
+    /**
+     * Append a pin to a stored problem.  Returns the pin's stable
+     * ID and the problem's new version.  Multiple pins on the same
+     * `(agent, day, shift)` are not deduplicated server-side; if you
+     * want at-most-one-pin-per-cell semantics, enforce it on the
+     * client by checking the pin entries from
+     * {@link SchedulingClient.getProblem} first.
+     *
+     * @throws HTTP 400 when the agent isn't on the problem's roster
+     *   or the (day, shift) is outside the grid.  HTTP 404 when the
+     *   problem doesn't exist for the caller's tenant.
+     */
+    addPin(problemId: string, request: AddPinRequest): Promise<AddPinResponse>;
+    /**
+     * Remove a pin previously added via
+     * {@link SchedulingClient.addPin}.
+     *
+     * @throws HTTP 404 when the problem doesn't exist for the
+     *   tenant or the `pinId` doesn't match any current pin
+     *   (already removed, stale ID).
+     */
+    removePin(problemId: string, pinId: string): Promise<void>;
+    /**
+     * Append a preference to a stored problem.  Same return shape as
+     * {@link SchedulingClient.addPin} — `preferenceId` is the stable
+     * handle for removal.  Multiple preferences targeting the same
+     * cell sum on the next solve.
+     */
+    addPreference(problemId: string, request: AddPreferenceRequest): Promise<AddPreferenceResponse>;
+    /**
+     * Remove a preference previously added via
+     * {@link SchedulingClient.addPreference}.
+     */
+    removePreference(problemId: string, preferenceId: string): Promise<void>;
 }
 
 declare class Osfql<SecurityDataType = unknown> {