Add manual/auto trigger and rework event and action transitions

[jakub-id]

No description provided.

[Copilot]

Pull request overview

This PR refactors the state model schema to improve the clarity and expressiveness of action and event transitions. It changes the transition structure from arrays of possible target states to a more explicit format that distinguishes between success and failure outcomes for actions, and simplifies events to have a single transition target.

Changes:

• Modified state model JSON schema to change Action transitions from an array to an object with success and failure properties, and added a trigger field
• Modified state model JSON schema to change Event transitions from a plural array field to a singular string field
• Updated the returnables YAML data file to conform to the new schema structure

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
misc/state-model.json	Updates Action schema to use object-based transitions with success/failure outcomes and adds trigger field; changes Event schema to use singular transition string
misc/returnables.yaml	Converts all action transitions from array format to object format with success keys; converts all event transitions from plural transitions arrays to singular transition strings

Comments suppressed due to low confidence (1)

misc/state-model.json:177

• The schema changes in this file will break compatibility with the existing codebase. The OpenAPI schema file broker/oapi/open-api.yaml (lines 611-641) defines ModelAction and ModelEvent with the old array-based transitions structure, which is used to generate Go types in broker/patron_request/proapi/pr-openapi_gen.go. Additionally, the embedded JSON state model file broker/patron_request/service/statemodels/returnables.json still uses the old schema format.

These files need to be updated in the same PR to maintain consistency:

1. broker/oapi/open-api.yaml - Update ModelAction and ModelEvent schemas to match the new structure
2. broker/patron_request/service/statemodels/returnables.json - Regenerate from the updated YAML to use the new schema

Without these updates, the code will fail at runtime when trying to unmarshal the state model JSON because the Go struct types won't match the actual JSON structure.

        "Action": {
            "type": "object",
            "additionalProperties": false,
            "description": "Declares an action available while in this state.",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name of the action"
                },
                "desc": {
                    "type": "string",
                    "description": "Description of the action"
                },
                "trigger": {
                    "type": "string",
                    "description": "Trigger for the action",
                    "enum": [
                        "auto",
                        "manual"
                    ],
                    "default": "manual"
                },
                "transitions": {
                    "type": "object",
                    "description": "Action outcome to state transition mapping. When no transition is defined, the action is considered to be non-state-changing.",
                    "additionalProperties": false,
                    "properties": {
                        "success": {
                            "type": "string",
                            "description": "Target state when the action succeeds."
                        },
                        "failure": {
                            "type": "string",
                            "description": "Target state when the action fails."
                        }
                    }
                }
            },
            "required": [
                "name"
            ],
            "title": "Action"
        },
        "Event": {
            "type": "object",
            "additionalProperties": false,
            "description": "Declares an event considered for transition while in this state.",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name of the event"
                },
                "desc": {
                    "type": "string",
                    "description": "Description of the event"
                },
                "transition": {
                    "type": "string",
                    "description": "State transition after event has occurred. When no transition is defined, the event is considered to be non-state-changing."
                }
            },
            "required": [
                "name"
            ],
            "title": "Event"
        }

[Copilot]

The trigger field in the Action schema has a default value of "manual", but JSON Schema's default keyword is only advisory for documentation purposes - it doesn't actually set default values during validation or parsing.

If you want actions to have a default trigger of "manual", you'll need to handle this in the application code that reads the state model. Alternatively, if the trigger field should be required, add it to the required array on line 150.

Suggested change

	],
	"default": "manual"
	]

[Copilot]

All actions in the YAML file only use the success transition, with no actions using the failure transition. This suggests that failure handling might not be fully designed yet. Consider whether:

1. Actions can actually fail and transition to different states (e.g., validation failure, network errors during send-request)
2. If failures should be handled differently (e.g., staying in the same state, transitioning to an error state)
3. Whether the schema should require at least one of success or failure to be present if transitions are defined

This is worth reviewing to ensure the new schema fully supports the intended workflow model.

[Copilot]

The new trigger field is added to the Action schema but is not currently used anywhere in the codebase. The field distinguishes between "auto" (automatically triggered) and "manual" (manually triggered by a user) actions.

Since this field is not currently utilized, consider:

1. Adding documentation or comments explaining the intended use case for this field
2. Ensuring that when this field is eventually used, the default value of "manual" is properly applied in the code that reads the state model (as JSON Schema defaults are not automatically enforced during deserialization)
3. Whether any existing actions should be marked as "auto" to reflect their intended behavior

If this is being added for future functionality, that's fine, but it should be clearly documented.

[adamdickmeiss]

LGTM