# Messaging mention contract

Only humans recorded after a successful GitHub-backed Chi login are addressable. The authorized backend endpoint exposes this deployment-local registry; a current-repository authorization check gates discovery. The UI uses GitHub handles such as
`@gszep` and `@SteffenPL`; identity comparison uses lowercase keys such as
`github:gszep` and `github:steffenpl`. Agents have no addressable identity and
act on behalf of the locally authenticated human.

Pi's built-in `@filepath` path uses the autocomplete provider, not an agent
tool. Messaging wraps that provider and delegates back to file completion when
no authenticated participant matches. On prompt submission it resolves tokens
again, so manually typed and edited handles behave like completed handles.

## z=0 evidence

After Pi persists the submitted user message, the extension appends a valid v3
custom entry through `pi.appendEntry("chi.messaging.mentions", data)`. It points
to, but never modifies, the message:

```json
{
  "schemaVersion": 1,
  "actor": { "id": "github:gszep", "handle": "gszep" },
  "recipients": [{ "id": "github:steffenpl", "handle": "SteffenPL" }],
  "target": { "sessionId": "...", "entryId": "..." }
}
```

The target message remains the only source of free text. Unknown `@tokens`,
emails, and file attachments do not create mention evidence.

## z=-1 projection

`jsonl-reduce` emits one exact, content-free reference per target and recipient
in `ReductionMetadata.mentions`. Reduction is deterministic set union keyed by
`(source.sessionId, source.entryId, recipientId)`. Conflicts fail; references
are never truncated or semantically summarized. A query first filters sparse
z=-1 metadata by recipient and timestamp, fetches the referenced z=0 message,
and only then invokes a model to classify tasks/questions or request adjacent
parent/child context.

A backend search index may project this metadata for scale, but is rebuildable
and never authoritative.

## Validity and trust

Both source markers and reduced artifacts are ordinary valid portable Pi v3.
Custom entries do not enter model context. Incoming session text remains
untrusted and is fetched or imported only through explicit local actions.