Milestone 6: describe parameters for people and for engines

Preview

There are three different kinds of “parameter” in this stack:

Surface	Purpose	Example
Problem records	The actual instance to solve	`staff[]`, `shifts[]`, `max_hours`, `required_staff`
`problem_inputs`	Scalar setup controls rendered by the generic UX	Planning horizon, default shift duration, default coverage
Constraint `parameters`	A mix of engine wiring and explicitly typed, user-configurable values	`load_attribute: duration_hours` is wiring; `value: {type: number, …}` is a control

Do not model employee and shift tables as a handful of scalar problem_inputs. The actual arrays arrive as problem data through manual entry, JSON/CSV upload, a stored dataset, or an explicit demo endpoint.

Problem setup controls#

problem_inputs:
  planning_horizon_days:
    name: "Planning horizon"
    description: "Number of days covered by this schedule."
    category: dimensions
    type: number
    required: true
    default: 7
    min: 1
    max: 28
    step: 1
    unit: days

  default_required_staff:
    name: "Default employees per shift"
    description: "Used only when constructing new shift records in the UX."
    category: coverage
    type: number
    required: true
    default: 1
    min: 1
    max: 20
    step: 1

A user-configurable constraint value#

Use an indirection such as limit_parameter when a contract consumes a user-configurable value. The engine reads the resolved scalar; the UX reads the typed definition:

max_hours_per_employee:
  name: "Maximum hours"
  description: "Limit hours worked in the planning period."
  category: hours
  type: hard
  default_enabled: true
  contract: entity_load_max
  parameters:
    day_attribute: day
    load_attribute: duration_hours
    limit_attribute: max_hours
    limit_parameter: value
    value:
      type: number
      label: "Fallback maximum hours"
      description: "Used when an employee record has no max_hours value."
      default: 40
      min: 0
      max: 168
      step: 0.5
      unit: hours

Never render every entry in parameters as an input. Entries with a typed definition (type, label, default, bounds, options) are controls. Scalar entries such as day_attribute, load_attribute, and limit_attribute are contract wiring and remain hidden.