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

cd meadows-protocol
uv pip install -e .

Test

uv run pytest -q

Usage

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).