# Current receive contract

This document is current contract authority for notify-pull receive behavior. ADRs record decisions; this file describes executable semantics.

## Flow

```text
transport watch notification
  → list envelope(s)
  → persist delivery/injection state
  → harness receives envelope-only context
  → harness calls read(messageId)
  → harness replies or resolves explicit messageId
  → core marks completion and advances queue
```

Notifications never consume mail and never inject bodies.

## Message identity

Every operation targets immutable `messageId`. Reply/resolve must reject unknown, completed, wrong-recipient, or non-actionable targets. History IDs are not implicitly “current.”

## State meanings

- `processedIds`: envelope notification was emitted/deduplicated; not completion.
- `activeStack`: bounded LIFO work stack (depth 8). Top frame is exact reply/resolve target; lower frames are suspended parent/continuation work.
- `activeId`: compatibility mirror of `activeStack` top; survives `read` because read moves mail from `new` to `cur`.
- `completedIds`: reply/resolve/cancel/abandon reached terminal state.
- `retry`: operation failed and remains eligible with recorded error/attempt.

`processedIds` must never hide uncompleted active work during restart or takeover.

## Nested work and urgency

- Same-thread `answer`/`review_response` from a known peer with fresh presence pushes as continuation.
- Trusted urgent actionable work pushes above current work.
- Completing top frame resumes previous frame before ordinary dequeue.
- Completion removes its exact frame atomically, preserving newer urgent frames pushed concurrently.
- Stack overflow remains queued/context-visible and never stops watcher.
- Urgent scheduling occurs at next available harness turn; it does not hard-cancel a provider turn already executing.

## Ownership

One owner exists per `(root, participantId)`. Secondary sessions may inspect/read according to policy but cannot inject or mutate scheduler state. Owner takeover preserves unfinished work and increments an incarnation/epoch.

## Presence

Presence is liveness evidence only. It has an observed timestamp/TTL and may become stale. Presence does not prove message delivery, authorization, or model availability. Urgent trust requires fresh presence plus configured trust policy.

## Reload and failure

Controlled reload preserves participant identity, pending work, active stack, and completion state. Runtime instance identity may rotate. A dead owner may be taken over after lease expiry. Detached notices are advisory; owner/lease/presence state is authoritative.

Scheduler/core upgrades require full Pi process restart. `/reload` may retain cached dependency modules and is not sufficient when active-stack implementation changes.

## Harness boundary

Core emits normalized events. Harness decides how to turn an event into a model turn. A harness without interrupt capability cannot promise hard urgent cancellation; it may only schedule/wake a later turn.

## Guarantees and limits

Guaranteed target:

- explicit-ID operations;
- envelope-only notification;
- no duplicate active owner;
- recoverable unfinished work;
- idempotent reply/resolve intent;
- exact transport/state evidence.

Not guaranteed:

- model compliance;
- hard cancellation of an already running provider turn;
- power-loss durability beyond filesystem guarantees;
- trust/authentication against a malicious shared mailbox.