mgf-livepush 0.1.2__tar.gz

mgf_livepush-0.1.2/.claude/commands/sync.md

@@ -0,0 +1,24 @@
+---
+description: Sync THIS project with the MGF federation (mgf-common + standards) and bring it into conformance
+---
+
+Sync THIS project with the MGF federation. Read the canonical recipe at
+`../mgf-common/docs/recipes/federation-sync-prompt.md` — fall back to the
+installed `mgf-common` package, else its latest PyPI release, if no sibling
+checkout is present — and execute it end-to-end against THIS repo:
+
+1. Confirm context (project identity/role/layer/version, mgf-common pin vs
+   latest PyPI, stability posture), then proceed autonomously.
+2. Sync + catch updates (pin drift, sibling extractions, new/changed
+   standards, open FEEDBACK papers).
+3. Audit conformance against the LIVE `docs/standards/` corpus and the
+   federation artifacts — don't work from a remembered rule list.
+4. Apply fixes on a branch with the federation commit trailers, with tests.
+5. Run the full gate (ruff · mypy --strict · lint-imports · tests · gitleaks)
+   and report honestly.
+
+Read-only on mgf-common and the other siblings; no push/merge/version-bump
+unless I explicitly ask. "Already conformant — no change needed" is a valid
+result.
+
+$ARGUMENTS

mgf_livepush-0.1.2/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ruff *)",
+      "Bash(mypy *)",
+      "Bash(pytest *)",
+      "Bash(lint-imports *)",
+      "Bash(uv *)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(mgf-common *)",
+      "Read",
+      "Edit",
+      "Write"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(git push --force *)",
+      "Bash(git reset --hard *)"
+    ],
+    "defaultMode": "default"
+  }
+}

mgf_livepush-0.1.2/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.gates/

mgf_livepush-0.1.2/.import_linter_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by Grimp.
+*

mgf_livepush-0.1.2/.import_linter_cache/42b0730c78206e85c00287a310dd9a845ebf6600.data.json

@@ -0,0 +1 @@
+{"mgf.livepush._sse":[["asyncio",19,"import asyncio"],["contextlib",20,"import contextlib"],["__future__",17,"from __future__ import annotations"],["mgf.livepush._broker",30,"from mgf.livepush._broker import Broker, Subscription"],["mgf.livepush._errors",25,"from mgf.livepush._errors import CapExceededError"],["mgf.livepush._slotcap",31,"from mgf.livepush._slotcap import SlotCap"],["dataclasses",22,"from dataclasses import dataclass"],["typing",23,"from typing import TYPE_CHECKING"],["collections",28,"from collections.abc import AsyncIterator, Awaitable, Callable"],["logging",21,"import logging"]],"mgf.livepush._slotcap":[["collections",18,"from collections.abc import Callable"],["__future__",12,"from __future__ import annotations"],["logging",14,"import logging"],["typing",15,"from typing import TYPE_CHECKING, Any"]],"mgf.livepush._broker":[["typing",13,"from typing import Any, Protocol, runtime_checkable"],["contextlib",12,"import contextlib"],["__future__",9,"from __future__ import annotations"],["asyncio",11,"import asyncio"]],"mgf.livepush.fastapi":[["__future__",8,"from __future__ import annotations"],["mgf.livepush._sse",18,"from mgf.livepush._sse import SSEStreamService"],["fastapi",36,"from fastapi.responses import StreamingResponse"],["fastapi",15,"from fastapi import Request"],["fastapi",35,"from fastapi import HTTPException"],["typing",10,"from typing import TYPE_CHECKING"],["fastapi",16,"from fastapi.responses import StreamingResponse"],["mgf.livepush._errors",12,"from mgf.livepush._errors import CapExceededError"]],"mgf.livepush":[["mgf.livepush._sse",23,"from mgf.livepush._sse import SSEStream, SSEStreamService, sse_headers"],["__future__",18,"from __future__ import annotations"],["mgf.livepush._broker",20,"from mgf.livepush._broker import Broker, MockBroker, RedisBroker, Subscription"],["mgf.livepush._slotcap",22,"from mgf.livepush._slotcap import SlotCap"],["mgf.livepush._errors",21,"from mgf.livepush._errors import CapExceededError, LivePushError"]],"mgf.livepush._errors":[["__future__",7,"from __future__ import annotations"],["mgf.common",9,"from mgf.common.exceptions import AppError"]]}

mgf_livepush-0.1.2/.import_linter_cache/81fbf6185bfae13a05470e6b0cf08e7a80149eb8.data.json

@@ -0,0 +1 @@
+{"mgf.livepush.fastapi":[["mgf.livepush._sse",18,"from mgf.livepush._sse import SSEStreamService"],["mgf.livepush._errors",12,"from mgf.livepush._errors import CapExceededError"]],"mgf.livepush._errors":[],"mgf.livepush._slotcap":[],"mgf.livepush":[["mgf.livepush._slotcap",22,"from mgf.livepush._slotcap import SlotCap"],["mgf.livepush._errors",21,"from mgf.livepush._errors import CapExceededError, LivePushError"],["mgf.livepush._broker",20,"from mgf.livepush._broker import Broker, MockBroker, RedisBroker, Subscription"],["mgf.livepush._sse",23,"from mgf.livepush._sse import SSEStream, SSEStreamService, sse_headers"]],"mgf.livepush._sse":[["mgf.livepush._slotcap",31,"from mgf.livepush._slotcap import SlotCap"],["mgf.livepush._broker",30,"from mgf.livepush._broker import Broker, Subscription"],["mgf.livepush._errors",25,"from mgf.livepush._errors import CapExceededError"]],"mgf.livepush._broker":[]}

mgf_livepush-0.1.2/.import_linter_cache/CACHEDIR.TAG

@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag automatically created by Grimp.
+# For information about cache directory tags see https://bford.info/cachedir/

mgf_livepush-0.1.2/.import_linter_cache/mgf.livepush.meta.json

@@ -0,0 +1 @@
+{"mgf.livepush._broker": 1779951917.1567435, "mgf.livepush._errors": 1779951628.1901445, "mgf.livepush._sse": 1779951917.1567435, "mgf.livepush": 1779951692.2036455, "mgf.livepush.fastapi": 1779951683.8657117, "mgf.livepush._slotcap": 1779951917.1577435}

mgf_livepush-0.1.2/.woodpecker.yml

@@ -0,0 +1,79 @@
+# Codeberg / Woodpecker CI for mgf-livepush.
+#
+# Federation CI shape (WORKFLOWS.md WF-*): lint, typecheck, a per-version
+# pytest matrix, and dependency + secret scans. Runs on every push / PR.
+# No publish flow yet — when a release is cut, copy the tag-coherence ->
+# smoke -> publish -> verify-pypi chain from mgf-common.
+#
+# Installs [redis] + [fastapi] so the SlotCap / SSE code imports resolve;
+# the suite drives an in-process FakeRedis (tests/conftest.py), so no real
+# Redis service is needed. Each step runs in a fresh python:X-slim container.
+# Validate locally before pushing:  CI_LOCAL_REPO=$PWD scripts/ci-local.sh ci
+# (from a mgf-common checkout — see docs/recipes/local-ci-pipeline.md).
+
+when:
+  - event: push
+  - event: pull_request
+  - event: manual
+
+steps:
+  # Lint — ruff + import-linter (layering contract in pyproject, rule DP-01).
+  - name: lint
+    image: python:3.12-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet -e ".[dev,redis,fastapi]"
+      - ruff check src tests
+      - lint-imports
+
+  # Typecheck — mypy (config-driven: [tool.mypy] packages = ["mgf.livepush"]).
+  - name: typecheck
+    image: python:3.12-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet -e ".[dev,redis,fastapi]"
+      - mypy
+
+  # Per-version test steps — explicit, NOT a step-level `matrix:` (Woodpecker
+  # silently ignores that → ${PYTHON_VERSION} never expands → python:-slim).
+  # Coverage gate (config fail_under=80) on the 3.12 job only.
+  - name: test-3.11
+    image: python:3.11-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet -e ".[dev,redis,fastapi]"
+      - pytest --tb=short -q
+
+  - name: test-3.12
+    image: python:3.12-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet -e ".[dev,redis,fastapi]"
+      - pytest --tb=short -q --cov=src/mgf --cov-report=term-missing
+
+  - name: test-3.13
+    image: python:3.13-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet -e ".[dev,redis,fastapi]"
+      - pytest --tb=short -q
+
+  # Dependency CVE scan (rule SC-10).
+  - name: vuln-scan
+    image: python:3.12-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet pip-audit
+      - pip install --quiet -e ".[dev,redis,fastapi]"
+      # Audit the DEPENDENCIES; skip mgf-livepush's own editable install
+      # (its current version isn't on PyPI yet). `--strict` is dropped
+      # because it conflicts with --skip-editable (strict treats the
+      # skipped editable as an un-auditable dep). pip-audit still exits
+      # non-zero on any real CVE in the dependency set.
+      - pip-audit --skip-editable
+
+  # Secret scan (rule SC-01) — gitleaks over the working tree + history.
+  - name: secret-scan
+    image: zricethezav/gitleaks:v8.30.1
+    commands:
+      - gitleaks detect --source . --no-banner --redact

mgf_livepush-0.1.2/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md — AI agent instructions
+
+This file follows the cross-tool `AGENTS.md` convention. It is a
+**thin pointer** managed by `mgf-common catch-up` — do not edit it;
+project-specific agent notes belong in this project's `CLAUDE.md`.
+
+**AI agents working in this project — get the canonical briefing:**
+
+> Run **`mgf-common agents`** and do exactly what it prints.
+
+`mgf-common` is a dependency of this project, so that command is
+always installed — it prints the single, federation-wide agent
+briefing with no setup and no assumptions. It covers the federation
+shape, using the library + its siblings instead of reinventing
+them, the standards + the docs layout, keeping this project in sync
+with `mgf-common catch-up`, and filing feedback in the relevant
+library's `FEEDBACK.md` when you hit friction so the library itself
+can improve.
+
+Then read this project's own `CLAUDE.md` (`docs/claude/CLAUDE.md`,
+or `docs/CLAUDE.md` on older layouts) — its auto-managed block
+carries the project-specific lookup.
+
+**Fallback if `mgf-common agents` fails to run** (PAPER-78 — usually
+a stale editable install pointing at a renamed source tree): read
+the same text from `mgf-common`'s `STARTHERE.md`, section *"For the
+AI agent in any Magogi project"*. The CLI's output and that
+section are kept identical by `tests/unit/cli/test_agents.py`. Open
+either:
+
+- The published source on Codeberg:
+  [`mgf-common/STARTHERE.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/STARTHERE.md)
+- The same file in your local mgf-common checkout if you have one
+  (typically `~/PycharmProjects/mgf-common/STARTHERE.md`).
+
+One message for the whole federation; no per-project variant.

mgf_livepush-0.1.2/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to `mgf-livepush` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+the project follows [SemVer](https://semver.org/spec/v2.0.0.html). Per
+the 0.x window ([SemVer 0.x](https://semver.org/#spec-item-4) and rule
+**AP-03** from `mgf-common/docs/standards/API_DESIGN.md`), MINOR
+releases MAY break the public API. Pin tightly:
+
+```toml
+mgf-livepush = ">=0.X.0,<0.Y"   # one minor at a time
+```
+
+The release-engineering discipline that produces this changelog is in
+[`mgf-common/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/RELEASING.md).
+
+---
+
+## [Unreleased]
+
+Nothing yet.
+
+---
+
+## [0.1.2] — 2026-05-28 — federation cohort publish (mgf-common 0.42.x)
+
+Federation cohort wave: mgf-livepush accepts **mgf-common 0.42.x** (pin widened to
+`>=0.41,<0.43`) and ships to PyPI, carrying the previously-unpublished 0.1.1 work.
+
+---
+
+## [0.1.1] — 2026-05-28 — test hardening + reliability tests
+
+### Added
+
+- Adopt `mgf-test-supervisor` + TS-04 `filterwarnings=["error"]` + a coverage
+  gate + the full federation marker taxonomy + a tier-0 smoke set.
+- Reliability tests: SlotCap no-oversell under concurrency (atomic-INCR
+  guarantee pinned), fail-open contract, SSE slot-release on cancel.
+- `USERS.md` (DOC-16).
+
+### Notes
+
+- Test + dev-config only; no public API or runtime-behaviour change.
+
+---
+
+## [0.1.0] — 2026-05-28
+
+> **Maiden voyage** — extracted from PlasmaMapper's Phase-4 push
+> surface after the pre-release core re-design hardened it
+> (heartbeat cadence, slot lifecycle, disconnect cleanup, and the
+> dev/prod-proxy buffering recipe). PlasmaMapper is consumer #1.
+> A `mgf-common` federation sibling under the `mgf.*` namespace.
+
+### Added
+
+- **`mgf.livepush.SSEStreamService`** — the SSE streaming
+  primitive. `open_stream(...)` acquires a connection slot,
+  subscribes to a broker channel, and returns an `SSEStream`
+  (`.headers` + `.body`, an async byte iterator) with proxy-safe
+  headers already set. Framework-agnostic core — wrap `.body` in
+  whatever streaming response your framework provides.
+- **`SSEStream` / `sse_headers`** — the `(headers, body)` result
+  plus the proxy-safe response headers (`Cache-Control: no-cache,
+  no-transform`, `X-Accel-Buffering: no`) that keep live push
+  flowing through buffering proxies.
+- **`Broker` / `Subscription`** — the pluggable pub/sub **broker
+  seam** (Protocols). A consumer can swap the backing transport
+  (Redis pub/sub for Redis Streams / NATS) without touching the
+  SSE machinery.
+- **`RedisBroker`** — the Redis pub/sub broker adapter, behind the
+  opt-in `[redis]` extra. Consumers on another broker don't pay
+  the `redis` dependency.
+- **`MockBroker`** — an in-process broker adapter for tests; no
+  Redis required.
+- **`SlotCap`** — per-key connection-**slot cap** via Redis
+  INCR/DECR with a TTL. Fail-open by design; returns
+  `429 (Retry-After: 5)` automatically when a per-key cap is full.
+- **`CapExceededError` / `LivePushError`** — typed errors
+  (subclasses of `mgf-common`'s `AppError`).
+- **`mgf.livepush.fastapi.sse_streaming_response`** — a one-line
+  FastAPI `StreamingResponse` wrapper, behind the opt-in
+  `[fastapi]` extra. The core stays framework-agnostic; FastAPI
+  lives only inside this adapter (enforced by import-linter).
+
+### Engineering
+
+- **`mgf-common>=0.41,<0.42`** runtime dependency. AP-03 0.x
+  window pin discipline applies — bump in lock-step with
+  mgf-common's next minor.
+- PEP 420 namespace package (no top-level `mgf/__init__.py`); the
+  wheel ships `src/mgf/` as-is so `mgf.livepush` coexists as a
+  SIBLING (not a subpackage) of `mgf.common` and the other
+  federation siblings.
+- import-linter contract keeps the core
+  (`_sse` / `_broker` / `_slotcap` / `_errors`) free of any
+  FastAPI import — framework code is confined to the
+  `mgf.livepush.fastapi` adapter.

mgf_livepush-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing — mgf-livepush
+
+`mgf-livepush` is a Magogi Foundation sibling and **inherits the
+cross-project engineering standards** from
+[`mgf-common`](https://codeberg.org/magogi-admin/mgf-common).
+This file is short on purpose; the canonical contributor guide
+is the federation contract.
+
+## First read
+
+1. [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEDERATION.md) — the contract.
+2. [mgf-common/docs/standards/](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/) — the rule corpus (currently v2.10).
+
+## Rule families (quick reference)
+
+| Family | Covers                                                |
+|--------|-------------------------------------------------------|
+| AP-*   | API stability tiers, deprecation cycle                 |
+| CF-*   | Layered config + env-var precedence                    |
+| DEP-*  | Pin discipline, transitive caps                        |
+| DOC-*  | Docs layout (universal-5 + sibling MUSTs)              |
+| DP-*   | Design principles (frozen types, TZ-aware, …)          |
+| EH-*   | Typed exception hierarchy                              |
+| FB-*   | Feedback discipline (PAPER-NN flow)                    |
+| LG-*   | Structured logging, redaction, audit emission          |
+| REL-*  | Build → test → tag → push → upload order               |
+| SC-*   | Atomic writes, redaction, secret handling              |
+| TS-*   | Test discipline, four-gate CI                          |
+
+## Process
+
+1. **Bug / feature:** file in [FEEDBACK.md](FEEDBACK.md)
+   (sibling-scoped) — or in
+   [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md)
+   if cross-cutting (per DOC-13 / FB-04).
+2. **PR:** branch from main; run four-gate CI locally:
+   ```sh
+   .venv/bin/python -m ruff check src/ tests/
+   .venv/bin/python -m mypy --strict src/
+   .venv/bin/python -m pytest
+   .venv/bin/python -m coverage report
+   ```
+3. **CHANGELOG.md:** add an `[Unreleased]` entry per
+   [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+4. **Public-API delta:** update [PUBLIC_API.md](PUBLIC_API.md)
+   in the same PR; the pinned test gate will catch a missed entry.
+5. **Reviewer:** the federation owner (mgf-common maintainer).
+
+## Release flow
+
+See [REL-* in mgf-common standards](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/RELEASING.md).
+Short version: bump → regen PUBLIC_API.json → build → test →
+`twine check` → commit → tag → push tag → upload.
+
+## See also
+
+- [STARTHERE.md](STARTHERE.md) — entry point
+- [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEDERATION.md) §7 — feedback discipline
+- [mgf-common/CONTRIBUTING.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/CONTRIBUTING.md) — the canonical contributor guide

mgf_livepush-0.1.2/DEPS.md

@@ -0,0 +1,54 @@
+# DEPS — mgf-livepush's bidirectional dependency manifest
+
+> **§1** — what mgf-livepush depends on. **§2** — who depends on
+> mgf-livepush. Knowing both directions makes deprecation,
+> breaking-change blast-radius, and feature-prioritisation tractable.
+>
+> **Per standard DOC-16** (v2.12): every project ships a `DEPS.md`.
+> Replaces the former `USERS.md`.
+
+Last verified: 2026-05-28.
+
+---
+
+## §1 What mgf-livepush depends on
+
+| Dependency   | Window         | Why                                                       | Tier             |
+|--------------|----------------|-----------------------------------------------------------|------------------|
+| `mgf-common` | `>=0.41,<0.42` | `AppError` (SSE/broker error base) + observability + standards CLI | runtime |
+| `redis`      | `>=5.0`        | the Redis pub/sub broker adapter (`RedisBroker`)          | `[redis]` extra (lazy) |
+| `fastapi`    | `>=0.110`      | the `StreamingResponse` wrapper (`mgf.livepush.fastapi`)  | `[fastapi]` extra (lazy) |
+
+*Federation siblings depended on: `mgf-common` — the cornerstone
+(typed exceptions / bootstrap / observability). No other `mgf-*`
+sibling is depended on.*
+
+Runtime core is kept tight: only `mgf-common` ships transitively into
+every consumer. The Redis and FastAPI adapters live behind extras with
+lazy imports, and the import-linter contract forbids `fastapi` from the
+framework-agnostic core (`_sse` / `_broker` / `_slotcap` / `_errors`).
+
+---
+
+## §2 Who depends on mgf-livepush
+
+Consumer projects + federation siblings that import this project.
+(Inverse of each consumer's `MGF_ADOPTION.md`.)
+
+| Project / sibling | Location                                    | Import sites | Status                              | Surfaces used                                                  |
+|-------------------|---------------------------------------------|-------------:|-------------------------------------|----------------------------------------------------------------|
+| **PlasmaMapper**  | `/home/bassam/PycharmProjects/PlasmaMapper` | 5            | Active — consumer #1 (`mgf-livepush[redis,fastapi]`); newly extracted 2026-05-28 | `SSEStreamService` / `RedisBroker` / `SlotCap` / `CapExceededError` |
+
+No federation siblings depend on mgf-livepush.
+
+---
+
+## §3 Maintenance
+
+Updated every MINOR release + when a dependency or consumer changes.
+Import-survey methodology:
+
+```sh
+grep -rE "(from|import) +mgf\.livepush" /path/to/each/consumer \
+  --include='*.py' | wc -l
+```

mgf_livepush-0.1.2/FEDERATION.md

@@ -0,0 +1,18 @@
+# FEDERATION — pointer
+
+> This project is a member of the **Magogi Foundation**. The federation
+> contract is **not** maintained here — there is one canonical copy.
+>
+> **Read the contract at:**
+> [`mgf-common/FEDERATION.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEDERATION.md)
+>
+> It is the single source of truth for: required docs layout,
+> conformance levels (L1 / L2 / L3), the federation-first principle,
+> catch-up cadence, and feedback discipline. Per **DOC-17**, siblings
+> and consumers link here rather than copy it.
+>
+> **This project's specifics** live in its own root docs:
+> `README.md` (what it is), `DEPS.md` (what it depends on + who depends
+> on it), `CHANGELOG.md`, `FEEDBACK.md`, and
+> `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md` (declared conformance
+> level + per-rule audit).

mgf_livepush-0.1.2/FEEDBACK.md

@@ -0,0 +1,90 @@
+# FEEDBACK — mgf-livepush
+
+> Paper-tracking file for issues, friction, and requests against
+> this project. Consumer projects (and any future adopter) file
+> PAPER-NN entries here.
+>
+> **Where to file what:**
+>
+> - **mgf-livepush-specific** → file HERE.
+> - **Federation-wide** (cross-sibling patterns, standards
+>   proposals) → file in
+>   [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md).
+>
+> **Numbering convention:** paper numbers (`PAPER-NN`) are local
+> to this repo (FB-01). When a paper cross-references a
+> federation-wide paper, the federation number appears in the
+> metadata table as a cross-reference row.
+>
+> **Discipline:** see
+> [mgf-common/docs/standards/DOCUMENTATION.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/DOCUMENTATION.md)
+> §FEEDBACK (rules FB-01..FB-04, DOC-13).
+
+---
+
+## §1 Process
+
+1. **File freely.** Any consumer hitting friction MUST file a
+   PAPER-NN under §2. Don't wait for permission; the maintainer
+   triages.
+2. **Status flips** through `OPEN` → `SHIPPED` / `DEFERRED` /
+   `WONTFIX` / `MOVED` as the paper resolves. A `SHIPPED` row
+   carries a commit-SHA reference + release-version reference.
+3. **Renumbering** never happens within this repo — papers keep
+   their PAPER-NN forever (FB-01).
+
+---
+
+## §2 Open feedback (active)
+
+*No papers filed yet. The first paper goes here with the shape:*
+
+```
+#### `PAPER-01` — <one-line title>
+
+| Field | Value |
+|---|---|
+| Status | OPEN |
+| Severity | 🟢 Low / 🟡 High / 🔴 Critical |
+| Submitter | <consumer-name> (commit [`<sha>`](<url>)) |
+| Submitted | YYYY-MM-DD |
+| Federation paper | [PAPER-NN in mgf-common](...) (if cross-referenced) |
+
+**Concern.** ...
+
+**Why it matters.** ...
+
+**Concrete evidence.** ...
+
+**Suggested shape.** ...
+```
+
+---
+
+## §3 Reviewer's meta-feedback
+
+(none yet — placeholder for cross-cutting observations about
+the FEEDBACK process itself.)
+
+---
+
+## §4 How consumers submit feedback
+
+1. **Open a Codeberg issue** at
+   <https://codeberg.org/magogi-admin/mgf-livepush/issues> if you have a
+   quick question. Maintainer triages.
+2. **For a structured pain point**: file a PAPER-NN here as a PR
+   that adds the entry to §2.
+3. **For AI-agent-driven consumer sessions**: see your project's
+   `docs/CLAUDE.md` auto-block (managed by `mgf-common catch-up`)
+   — the `feedback-discipline` section spells out where to file
+   what.
+
+---
+
+## §5 Cross-references
+
+- [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md)
+  — federation-wide PAPERs.
+- [mgf-common/docs/standards/DOCUMENTATION.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/DOCUMENTATION.md)
+  — FEEDBACK discipline rules (FB-01..FB-04, DOC-13).

mgf_livepush-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bassam Alsanie and mgf-livepush contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mgf_livepush-0.1.2/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: mgf-livepush
+Version: 0.1.2
+Summary: Realtime push pipeline for mgf-common consumers — SSE streaming, a pluggable pub/sub broker seam (Redis + mock), and per-key connection-slot caps. Sibling of mgf-common under the mgf.* namespace.
+Author: Bassam Alsanie, mgf-livepush contributors
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,pubsub,realtime,redis,sse,streaming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mgf-common<0.43,>=0.41
+Provides-Extra: dev
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mgf-test-supervisor<0.2,>=0.1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: test
+Requires-Dist: fastapi>=0.110; extra == 'test'
+Requires-Dist: redis>=5.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mgf-livepush
+
+Realtime push pipeline for `mgf-common` consumers: an SSE streaming
+primitive, a pluggable pub/sub **broker seam** (Redis adapter + an
+in-process mock), and a per-key connection-**slot cap**. A sibling of
+`mgf-common` under the `mgf.*` namespace.
+
+Extracted from PlasmaMapper's Phase-4 push surface after the
+pre-release core re-design hardened it (heartbeat cadence, slot
+lifecycle, disconnect cleanup, and the dev/prod-proxy buffering recipe
+below). The broker seam means a consumer can swap Redis pub/sub for
+Redis Streams / NATS without touching the SSE machinery.
+
+## Install
+
+```bash
+pip install "mgf-livepush[redis,fastapi]"   # adapters are opt-in extras
+```
+
+## Quickstart (FastAPI)
+
+```python
+from redis.asyncio import Redis
+from mgf.livepush import SSEStreamService, RedisBroker, SlotCap
+from mgf.livepush.fastapi import sse_streaming_response
+
+redis = Redis.from_url("redis://localhost:6379/0")
+sse = SSEStreamService(RedisBroker(redis), SlotCap(redis, cap=20))
+
+@router.get("/events/stream")
+async def stream(request: Request):
+    # 429 (Retry-After: 5) automatically when the per-key cap is full.
+    return await sse_streaming_response(
+        sse, request, channel=f"events:{tenant_id}", slot_key=str(tenant_id)
+    )
+```
+
+Publisher side, anywhere:
+
+```python
+await RedisBroker(redis).publish(f"events:{tenant_id}", json.dumps(event))
+```
+
+Framework-agnostic core: `open_stream(...)` returns an `SSEStream`
+(`.headers` + `.body` async byte iterator) — wrap `.body` in whatever
+streaming response your framework uses. Tests use `MockBroker` (no
+Redis).
+
+## The dev/prod-proxy SSE recipe (read this — it's the tarpit)
+
+A FastAPI `text/event-stream` endpoint behind a proxy (SvelteKit `vite`,
+a `+server.ts` `[...path]` forward, nginx, AWS ALB) will silently
+**buffer** the body and break your latency budget even though the API
+side is correct. To get live push through a proxy:
+
+1. **Response headers (set by this lib):** `Cache-Control: no-cache,
+   no-transform` + `X-Accel-Buffering: no`. If your proxy gzips, also
+   force `Content-Encoding: identity` on the proxied response.
+2. **Node `fetch` forwarding** of a streamed body needs `duplex: 'half'`.
+3. **Playwright:** `waitForLoadState('networkidle')` *never fires* with
+   an open `EventSource` (the long-lived connection counts as in-flight)
+   — wait on a concrete readiness signal instead.
+4. **Playwright:** `webServer` spawns *before* `globalSetup`, so any env
+   the proxy needs must be declared statically in `webServer.env`, not
+   threaded from `globalSetup`.
+
+## Public surface
+
+| Name | What |
+|---|---|
+| `SSEStreamService` | acquire slot → subscribe → stream (`open_stream`) |
+| `SSEStream` / `sse_headers` | the `(headers, body)` result + the proxy-safe headers |
+| `Broker` / `Subscription` | the pub/sub port (Protocols) |
+| `RedisBroker` / `MockBroker` | adapters (`[redis]` extra / in-process) |
+| `SlotCap` | per-key INCR/DECR connection cap, fail-open, TTL |
+| `CapExceededError` / `LivePushError` | typed errors (subclass `AppError`) |
+| `mgf.livepush.fastapi.sse_streaming_response` | one-line FastAPI wrapper (`[fastapi]` extra) |