# Query Implementation

## Context

Module: {{MODULE_NAME}}
Query doc: {{QUERY_DOC}}

## Instructions

Implement a read-only query based on the documentation.

1. Read the query doc at the path above
2. Read the generated shell at `{{MODULES_ROOT}}/{{MODULE_NAME}}/query/<name>.generated.ts` (if exists)
3. Read existing queries in `{{MODULES_ROOT}}/{{MODULE_NAME}}/query/` for patterns
4. Implement the query

## Implementation Rules

**Read these references before implementing:**

- [Query patterns](../../erp-kit-shared/references/queries.md) — defineQuery, ReadonlyDB, conventions

### Key Patterns

1. **Generated queries**: Handle simple lookups automatically; write custom for joins/aggregations
2. **ReadonlyDB**: Always use `ReadonlyDB<DB>` type for database access
3. **QueryContext**: Use for dependency injection
4. **Results**: Return `ok(data)` or `err(error)`

### Query Naming Convention

| Pattern             | Name                     |
| ------------------- | ------------------------ |
| Get single entity   | `get{Entity}`            |
| List by status      | `list{Status}{Entities}` |
| List all            | `list{Entities}`         |
| Search with filters | `search{Entities}`       |
| Calculate/convert   | `calculate{Result}`      |

### From Doc to Code

| Doc Element      | Code Element              |
| ---------------- | ------------------------- |
| Input parameters | Query input type          |
| Output shape     | Return type               |
| Filtering logic  | WHERE clauses             |
| Aggregation      | SQL aggregation functions |
| Result checking  | Ok-only queries use `.value` directly; permission-gated queries check `.ok` |
| Business logic   | Post-query transformation |

## Output

Write the query file to `{{MODULES_ROOT}}/{{MODULE_NAME}}/query/<name>.ts`.
Follow existing patterns in the module's `query/` directory.
