Metadata-Version: 2.4
Name: meadows-protocol
Version: 0.1.0
Summary: MEADOWS protocol declaration: envelope, event names, JWT claims, permissions, labels. Pure declaration, no behavior.
Author: MEADOWS
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff==0.14.9; extra == 'dev'
Description-Content-Type: text/markdown

# meadows-protocol

> Pure declaration of the MEADOWS protocol: envelope, event names, JWT claims, permissions, labels.
> **No behavior.** See `MEADOWS-migration-intent.md` section 3.1.

## What this package contains

- `envelope.py` — `Message` model, `MessageType` enum, `QuotedMessage`, mention/everyone parsing
- `events.py` — `EventName` constants (the closed set of Socket.IO events)
- `jwt.py` — `JWTClaims` model, `JWTRole`, `build_claims()` helper
- `permissions.py` — `AVAILABLE_PERMISSIONS` (single source of truth)
- `labels.py` — `Label` triplet `(origin, label, semver)`; reserved origins: `meadows`, `system`
- `codec.py` — reference encoder/decoder, **subordinated** to the models (not the source of truth)

## Install

```bash
cd meadows-protocol
uv pip install -e .
```

## Test

```bash
uv run pytest -q
```

## Usage

```python
from meadows.protocol import (
    Message,
    MessageType,
    EventName,
    JWTClaims,
    JWTRole,
    build_claims,
    Label,
    AVAILABLE_PERMISSIONS,
)
```

## The protocol boundary (section 3.2 sort rule)

> The system contracts what it itself must understand. What only bots and humans need to understand stays opaque.

**In protocol:** envelope fields, event names, JWT claims, system-message bodies, the label signaling mechanism.
**Not in protocol:** the `content` payload of ordinary messages (opaque Markdown), domain schemas (SLO results, export formats, todo shapes).

## Labels (section 3.5)

A sender declares a body-sort via a triplet: `Label("meadows", "interactive-form", "1.0.0")`.
- `origin`: who declares this label. Reserved: `meadows`, `system`. Extensible to bot/UI names later.
- `label`: the sort name.
- `semver`: version of this label's contract.

Forms is the first concrete use case (postponed to iteration 4).
