How does a payment plan map onto environment state and tool actions?

A workable mapping uses five linked record types, each with a stable identifier.

- `plan`: `plan_id`, `account_id`, `status`, `principal`, `start_date`, `end_date`, `policy_version`. - `instalment`: `instalment_id`, `plan_id`, `seq`, `due_date`, `amount`, `status`. - `payment`: `payment_id`, `account_id`, `received_at`, `amount`, `allocated_to`. - `policy`: `policy_id`, `version`, `effective_from`, `rule_type`, `parameters`. - `event`: `event_id`, `plan_id`, `actor`, `action`, `before_ref`, `after_ref`, `at`.

Links run from `instalment.plan_id` to `plan.plan_id`, and from `payment.allocated_to` to one or more instalments. Each `plan.policy_version` points at the rule set in force.

A typical tool surface is `get_plan`, `list_instalments`, `add_payment`, `defer_instalment`, `split_instalment`, `waive_fee`, `cancel_plan` and `request_approval`. Read tools return records; write tools return the new state plus an error code when a rule blocks the action.

The `event` table is the evaluation hook. It lets a grader replay the sequence, compare before and after references, and confirm that approvals were requested before restricted actions. Keep the clock a parameter of the environment so due-date logic is deterministic.

Field names can be mapped to your own schema in a pilot. The records are generated, so check the sample for consistency before you build loaders around it.