> For the complete documentation index, see [llms.txt](https://light-services.kodkod.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://light-services.kodkod.me/introduction/concepts.md).

# Concepts

This section covers the core concepts of Operandi: **Arguments**, **Steps**, **Outputs**, **Context**, **Errors**, and **Callbacks**.

## Service Execution Flow

When you call `MyService.run(args)`, the following happens:

```
┌──────────────────────────────────────────────────────────────┐
│                      Service.run(args)                       │
├──────────────────────────────────────────────────────────────┤
│  1. Load default values for arguments and outputs            │
│  2. Validate argument types                                  │
│  3. Run before_service_run callbacks                         │
├──────────────────────────────────────────────────────────────┤
│  4. Begin around_service_run callback                        │
│  5. Begin database transaction (if use_transactions: true)   │
│     ┌─────────────────────────────────────────────────────┐  │
│     │  6. Execute steps in order                          │  │
│     │     - Run before_step_run / around_step_run         │  │
│     │     - Execute step method                           │  │
│     │     - Run after_step_run / on_step_success          │  │
│     │     - Skip if condition (if:/unless:) not met       │  │
│     │     - Stop if errors.break? is true                 │  │
│     │     - Stop if stop! was called                      │  │
│     ├─────────────────────────────────────────────────────┤  │
│     │  7. On error → Rollback transaction                 │  │
│     │     On success → Commit transaction                 │  │
│     └─────────────────────────────────────────────────────┘  │
│  8. End around_service_run callback                          │
├──────────────────────────────────────────────────────────────┤
│  9. Run steps marked with always: true (unless stop! called) │
│ 10. Validate output types (if success)                       │
│ 11. Copy errors/warnings to parent service (if in context)   │
│ 12. Run after_service_run callback                           │
│ 13. Run on_service_success or on_service_failure callback    │
├──────────────────────────────────────────────────────────────┤
│ 14. Return service instance                                  │
│     - service.success? / service.failed?                     │
│     - service.outputs / service.errors                       │
└──────────────────────────────────────────────────────────────┘
```

## Arguments

Arguments are the inputs provided to a service when it is invoked. They can be validated by type, assigned default values, and be designated as optional or required.

[Read more about arguments](/deep-dive/arguments.md)

## Steps

Steps are the fundamental units of work within a service, representing each individual task a service performs. They can be executed conditionally or skipped.

[Read more about steps](/deep-dive/steps.md)

## Outputs

Outputs are the results produced by a service upon its completion. They can have default values and be validated by type.

[Read more about outputs](/deep-dive/outputs.md)

## Context

Context refers to the shared state that passes between services in a service chain, enabling the transfer of arguments and error states from one service to another.

[Read more about context](/deep-dive/context.md)

## Errors

Errors occur during service execution and cause execution to halt. When an error occurs, all services in the same context chain stop, and database transactions are rolled back (configurable).

[Read more about errors](/deep-dive/errors.md)

## Callbacks

Callbacks allow you to run custom code at specific points during service and step execution. They're perfect for logging, benchmarking, auditing, and other cross-cutting concerns.

[Read more about callbacks](/deep-dive/callbacks.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://light-services.kodkod.me/introduction/concepts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.