@kortexya/reasoninglayer 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -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.21.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,17 +11900,34 @@ 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
- * pinned cell, an agent with a day-off on `day`, or an agent
- * otherwise blocked from the slot are silently ignored — the
- * corresponding decision edge does not exist in the reduced flow
- * graph.
+ * 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;
@@ -13725,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.
  *
@@ -13816,6 +13937,38 @@ interface SchedulingOptimizeResponse$1 {
      */
     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 */
@@ -14246,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[];
@@ -39369,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.
      *
@@ -39379,7 +39579,25 @@ declare class Scheduling<SecurityDataType = unknown> {
      */
     feasibility: (data: SchedulingFeasibilityRequest$1, params?: RequestParams) => Promise<HttpResponse<SchedulingFeasibilityResponse$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 cells that are 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.
+     * 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
@@ -39387,6 +39605,33 @@ declare class Scheduling<SecurityDataType = unknown> {
      * @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>>;
 }
 
 /**
@@ -39630,21 +39875,194 @@ interface SchedulingOptimizeResponse {
      */
     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_Preference as Preference, type scheduling_SchedulingFeasibilityRequest as SchedulingFeasibilityRequest, type scheduling_SchedulingFeasibilityResponse as SchedulingFeasibilityResponse, type scheduling_SchedulingOptimizeRequest as SchedulingOptimizeRequest, type scheduling_SchedulingOptimizeResponse as SchedulingOptimizeResponse, 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 };
 }
 
 /**
@@ -39775,6 +40193,127 @@ declare class SchedulingClient {
      * ```
      */
     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> {