> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayerup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Planner, Executor, Verifier & Memory

> Each agent run is a coordinated loop of four components. Planner produces a structured plan; executor dispatches it; verifier rules a candidate Decision; memory holds run-scoped state.

# 11 — Planner, executor, verifier & memory.

Each agent run is a coordinated loop of four components. The planner produces a structured
plan; the executor dispatches it; the verifier rules a candidate Decision; the memory
holds run-scoped state. None of them holds long-lived authority; long-lived state lives
in the Ontology.

## 11.1  Internal data flow

```mermaid theme={null}
flowchart TB
  IN[Typed input<br/>+ ontology pin] --> PL[Planner]
  PL --> PLAN[Structured plan<br/>steps DAG]
  PLAN --> EX[Executor]
  EX --> TC[Tool calls]
  TC --> EX
  EX --> CD[Candidate Decision<br/>+ evidence + lineage]
  CD --> VF[Verifier]
  VF --> OUT[Decision<br/>+ proposed Actions]
  EX <-->|read/write| MEM[(Run memory)]
  PL <-->|read| MEM
  VF -->|write trace| MEM
```

*Fig. 11.1 — Internal dataflow. Memory is the only mutable state in a run; everything that survives is on the Ontology / Audit chain.*

## 11.2  Planner

The planner consumes *(typed input, role, ontology pin, allowed tools)* and emits a
structured **plan**. The plan grammar is fixed; the planner is not a free-text
generator.

```json theme={null}
{
  "version": "1",
  "steps": [
    {
      "id": "s1",
      "kind": "tool",
      "tool": "tool.<ns>.<name>",
      "version": ">=2.0.0,<3",
      "args": { "$ref": "input.attachments[0]" },
      "produces": "evidence.s1",
      "depends": []
    },
    {
      "id": "s2",
      "kind": "tool",
      "tool": "tool.classify.severity",
      "args": { "subject": "$ref:input", "schema": "claim.severity.v3" },
      "produces": "classification.s2",
      "depends": ["s1"]
    },
    { "id": "v1", "kind": "verify", "rulePack": "rules.intake.v3" },
    { "id": "d1", "kind": "decision", "draft": "$ref:classification.s2", "evidence": ["evidence.s1"] }
  ],
  "policy": {
    "abortOn": ["s1.exception.low_confidence", "s2.exception.out_of_distribution"],
    "branch": []
  }
}
```

Plans support sequential and DAG execution. A plan is itself recorded in run lineage; replays
re-execute the plan against the same pinned tools and inputs.

## 11.3  Executor

The executor is the run's scheduler. It is deliberately small. Its responsibilities are:

* Resolve `$ref`s in args at dispatch time, applying ontology-pin reads.
* Dispatch tool calls under the Tool PEP / PDP path.
* Apply retry policy per tool (see §11.6).
* Honour the plan's `abortOn` and `branch` directives.
* Update run memory with each step's typed output.
* Record every step in the run's audit slice.

The executor never produces business decisions and never invokes a model directly; both go
through tools.

## 11.4  Verifier

The verifier is an opinionated guard between candidate Decision and emitted Decision. It is
a deterministic component that runs three rule classes in a fixed order:

1. **Schema** — the candidate matches the typed Decision shape for its kind.
2. **Business rules** — declared rule packs run; verdicts `pass` / `warn` / `block` aggregate per the table below.
3. **Adversarial probes** — defensive checks (prompt-injection signature in evidence; obvious model hallucination patterns; conflicting evidence; out-of-policy verdicts).

| Per-rule verdicts    | Aggregate verdict | Outcome                                                           |
| -------------------- | ----------------- | ----------------------------------------------------------------- |
| all pass             | pass              | emit Decision; proceed to action staging                          |
| any warn, none block | warn              | emit Decision with `warnings`; stage actions; raise advisory Task |
| any block            | block             | do not emit Decision; raise Exception; handoff                    |

<Warning>
  The verifier is deterministic. Its rule packs are versioned; its verdicts are reproducible
  given `(rulePackVersion, candidate)`. The verifier may consult retrieval but
  never invokes a generative model.
</Warning>

## 11.5  Memory model

<CardGroup cols={3}>
  <Card title="Step-scoped" icon="clock">
    **Working memory** — In-process scratch for the current step. Typed values keyed by step id. Discarded at run end.
  </Card>

  <Card title="Run-scoped" icon="database">
    **Run memory** — Survives across steps within a run. Typed key/value, schema-validated. Discarded at run end. Captured in the replay bundle.
  </Card>

  <Card title="Pinned to a subject" icon="thumbtack">
    **Object-pinned memory** — Optional; survives across runs against the same subject Ref. Always projected onto a typed Property on the subject; never opaque.
  </Card>
</CardGroup>

<Warning>
  There is no global agent memory and no cross-tenant memory. "Long-term memory" of the
  business is the Ontology, not an agent.
</Warning>

## 11.6  Retry classifier

The executor classifies every tool / model failure into one of three buckets and applies a fixed policy:

| Class         | Examples                                        | Policy                                                                        |
| ------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- |
| **Transient** | HTTP 5xx · timeout · rate-limit                 | exponential backoff with jitter, up to retry limit; preserves idempotency key |
| **Permanent** | HTTP 4xx · schema mismatch · permission denied  | no retry; emit typed Exception                                                |
| **Policy**    | PDP deny · marking violation · purpose mismatch | no retry; emit typed Exception; abort run if step is mandatory                |

## 11.7  Determinism strategy

* Deterministic tool calls are replayable bit-exactly.
* Model calls capture *(model id, prompt rev, retrieval snapshot, parameters, seed)*; replay uses the exact set.
* The executor's step order is recorded; replay re-executes in the same order even where the DAG would otherwise allow parallelism.
* Time-dependent tools (e.g. now(), exchange-rate) are pinned to the run's `asOf` timestamp at run start.

## 11.8  Handoff conditions

The agent definition declares handoff triggers (§10.2). When a trigger fires, the run
terminates with state `handed_off`; the handoff manager (§10.8) routes the
subject to the configured queue with a typed Task, the cited evidence, and the rationale.

## 11.9  Observability of internals

The runtime emits per-step spans (`plan.step.<id>`) with: tool id and version,
model lineage at this step, PDP verdict, retry count, duration, output type, exceptions
emitted, memory deltas. Verifier verdicts are recorded with the rule pack version and the
per-rule outcome trace.