# selectors

Each example is a complete workflow spec.

## field projection selector

`{PHASE.results[].FIELD}` projects one field from each object in a phase's results array.
It always returns an array, preserving result order.
Null, missing, and non-record values are skipped; false, zero, empty strings, objects, and arrays are retained.

```json
{
  "name": "project-reports",
  "schemas": {
    "Work": {
      "type": "object",
      "properties": {
        "report": { "type": "object", "additionalProperties": true }
      },
      "required": ["report"]
    }
  },
  "phases": [
    {
      "id": "work",
      "kind": "fanout",
      "over": ["one", "two"],
      "step": { "summary": "Work {item}", "prompt": "Return a report for {item}; do not mutate anything.", "schema": "Work" }
    }
  ],
  "report": "{work.results[].report}",
  "return": "{work.results}"
}
```

### flatten selector

```json
{
  "name": "flatten-findings",
  "schemas": {
    "Review": {
      "type": "object",
      "properties": {
        "findings": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
      },
      "required": ["findings"]
    }
  },
  "phases": [
    {
      "id": "review",
      "kind": "fanout",
      "over": ["correctness", "security"],
      "step": { "summary": "Review {item}", "prompt": "Review the {item} dimension; do not mutate anything.", "schema": "Review" }
    },
    {
      "id": "verify",
      "kind": "fanout",
      "over": "{review.results[].findings[]}",
      "step": { "summary": "Verify {item}", "prompt": "Verify finding {item}; do not mutate anything." }
    }
  ],
  "return": "{verify.results}"
}
```

### where selector

```json
{
  "name": "truthy-filter",
  "schemas": {
    "Candidate": {
      "type": "object",
      "properties": { "valid": { "type": "boolean" } },
      "required": ["valid"]
    }
  },
  "phases": [
    {
      "id": "candidates",
      "kind": "fanout",
      "over": ["a", "b", "c"],
      "step": { "summary": "Inspect {item}", "prompt": "Inspect candidate {item}; do not mutate anything.", "schema": "Candidate" }
    },
    {
      "id": "selected",
      "kind": "single",
      "step": { "summary": "Select candidates", "prompt": "Select from {candidates.results | where valid}." }
    }
  ],
  "return": "{selected.results}"
}
```

### exact string filter

```json
{
  "name": "source-filter",
  "schemas": {
    "Evidence": {
      "type": "object",
      "properties": { "source_type": { "type": "string" } },
      "required": ["source_type"]
    }
  },
  "phases": [
    {
      "id": "evidence",
      "kind": "fanout",
      "over": ["sessions", "repository", "web"],
      "step": { "summary": "Collect {item} evidence", "prompt": "Collect evidence from {item}; do not mutate anything.", "schema": "Evidence" }
    },
    {
      "id": "sessions",
      "kind": "fanout",
      "when": "{evidence.results | where source_type == \"sessions\"}",
      "over": "{evidence.results | where source_type == \"sessions\"}",
      "step": { "summary": "Inspect session evidence {item}", "prompt": "Inspect session evidence {item}; do not mutate anything.", "schema": "Evidence" }
    }
  ],
  "return": "{sessions.results}"
}
```

### dynamic grouping

```json
{
  "name": "source-groups",
  "schemas": {
    "Evidence": {
      "type": "object",
      "properties": { "source_type": { "type": "string" } },
      "required": ["source_type"]
    }
  },
  "phases": [
    {
      "id": "evidence",
      "kind": "fanout",
      "over": ["one", "two", "three"],
      "step": { "summary": "Collect evidence for {item}", "prompt": "Collect evidence for {item}; do not mutate anything.", "schema": "Evidence" }
    },
    {
      "id": "groups",
      "kind": "fanout",
      "over": "{evidence.results | groupBy source_type}",
      "step": { "summary": "Process source group {item}", "prompt": "Process this source group: {item}; do not mutate anything." }
    }
  ],
  "return": "{groups.results}"
}
```