patchground 0.1.0__py3-none-any.whl

patchground/catalog/csv-import-row-errors/checks/visible/tests/test_import.py

@@ -0,0 +1,34 @@
+import pytest
+
+from stockimport import ImportFailed, ImportResult, Item, RowError, import_inventory
+
+HEADER = "sku,quantity,unit_price"
+
+
+def doc(*lines):
+    return "\n".join((HEADER, *lines)) + "\n"
+
+
+def test_strict_returns_items_in_file_order():
+    items = import_inventory(doc("A-1,5,19.99", "B-1,2,0.29"))
+    assert items == [Item("A-1", 5, 1999), Item("B-1", 2, 29)]
+
+
+def test_strict_default_raises_the_first_error():
+    with pytest.raises(ImportFailed) as caught:
+        import_inventory(doc("A-1,5,19.99", "A-2,1,x", "A-3,y,1.00"))
+    assert (caught.value.error.line, caught.value.error.code) == (3, "invalid_price")
+    assert isinstance(caught.value, ValueError)
+
+
+def test_result_types_have_the_documented_fields():
+    error = RowError(2, "sku", "invalid_sku", "bad")
+    result = ImportResult([Item("A", 1, 100)], [error])
+    assert result.items == [Item("A", 1, 100)]
+    assert (error.line, error.column, error.code) == (2, "sku", "invalid_sku")
+
+
+def test_non_strict_returns_valid_items_and_row_errors():
+    result = import_inventory(doc("A-1,5,19.99", "A-2,x,1.00", "B-1,2,0.29"), strict=False)
+    assert result.items == [Item("A-1", 5, 1999), Item("B-1", 2, 29)]
+    assert [(e.line, e.column, e.code) for e in result.errors] == [(3, "quantity", "invalid_quantity")]

patchground/catalog/csv-import-row-errors/debrief/questions.md

@@ -0,0 +1,5 @@
+- Which rules in the ticket did you decide were already satisfied by the strict code, and which did you have to change? How did you check?
+- Where does an invalid row reserve its sku in the strict code, and why did that not matter before non-strict mode existed?
+- How did you decide what non-strict mode does with a malformed CSV, and what did you leave unchanged?
+- Which of your tests would fail if line numbers counted records instead of physical lines?
+- If an AI assistant wrote part of the change, what did you verify yourself before accepting it?

patchground/catalog/csv-import-row-errors/environment/Dockerfile

@@ -0,0 +1,3 @@
+FROM python:3.12-slim
+ENV PYTHONDONTWRITEBYTECODE=1
+RUN pip install --no-cache-dir pytest==8.3.5

patchground/catalog/csv-import-row-errors/solution/reference.patch

@@ -0,0 +1,74 @@
+diff --git a/src/stockimport/importer.py b/src/stockimport/importer.py
+index 60e061c..3698620 100644
+--- a/src/stockimport/importer.py
++++ b/src/stockimport/importer.py
+@@ -6,8 +6,9 @@ import csv
+ import io
+ import re
+ from collections.abc import Iterator
++from typing import Literal, overload
+
+-from .models import ImportFailed, Item, RowError
++from .models import ImportFailed, ImportResult, Item, RowError
+
+ HEADER = ["sku", "quantity", "unit_price"]
+
+@@ -20,25 +21,40 @@ def _fail(line: int, column: str | None, code: str, message: str) -> ImportFaile
+     return ImportFailed(RowError(line, column, code, message))
+
+
+-def import_inventory(text: str) -> list[Item]:
++@overload
++def import_inventory(text: str) -> list[Item]: ...
++@overload
++def import_inventory(text: str, *, strict: Literal[True]) -> list[Item]: ...
++@overload
++def import_inventory(text: str, *, strict: Literal[False]) -> ImportResult: ...
++def import_inventory(text: str, *, strict: bool = True) -> list[Item] | ImportResult:
+     """Parse ``text`` and return its items in file order.
+
+-    The first problem found stops the import with ``ImportFailed``.
++    Strict (default): the first row problem stops the import with ``ImportFailed``.
++    ``strict=False``: row problems are collected and returned with the accepted items.
++    Header and CSV syntax problems raise ``ImportFailed`` in both modes.
+     """
+     reader = csv.reader(io.StringIO(text, newline=""), strict=True)
+     _read_header(reader)
+     items: list[Item] = []
++    errors: list[RowError] = []
+     seen: set[str] = set()
+     while True:
+         line = reader.line_num + 1  # physical line where the next record starts
+         try:
+             record = next(reader)
+         except StopIteration:
+-            return items
++            return items if strict else ImportResult(items, errors)
+         except csv.Error as exc:
+             raise _fail(line, None, "malformed_csv", str(exc)) from None
+-        if record:  # a physical line with no characters yields []
++        if not record:  # a physical line with no characters yields []
++            continue
++        try:
+             items.append(_parse_record(record, line, seen))
++        except ImportFailed as exc:
++            if strict:
++                raise
++            errors.append(exc.error)
+
+
+ def _read_header(reader: Iterator[list[str]]) -> None:
+@@ -58,7 +74,6 @@ def _parse_record(record: list[str], line: int, seen: set[str]) -> Item:
+         raise _fail(line, "sku", "invalid_sku", f"invalid sku {sku!r}")
+     if sku in seen:
+         raise _fail(line, "sku", "duplicate_sku", f"duplicate sku {sku!r}")
+-    seen.add(sku)
+     if not _QUANTITY.fullmatch(quantity):
+         raise _fail(line, "quantity", "invalid_quantity", f"invalid quantity {quantity!r}")
+     match = _PRICE.fullmatch(price)
+@@ -66,4 +81,5 @@ def _parse_record(record: list[str], line: int, seen: set[str]) -> Item:
+         raise _fail(line, "unit_price", "invalid_price", f"invalid unit_price {price!r}")
+     dollars, fraction = match.groups()
+     cents = int(dollars) * 100 + int((fraction or "").ljust(2, "0"))
++    seen.add(sku)  # only fully valid rows reserve their sku
+     return Item(sku, int(quantity), cents)

patchground/catalog/csv-import-row-errors/workspace/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "stockimport"
+version = "0.3.0"
+requires-python = ">=3.12"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

patchground/catalog/csv-import-row-errors/workspace/src/stockimport/__init__.py

@@ -0,0 +1,4 @@
+from .importer import import_inventory
+from .models import ImportFailed, ImportResult, Item, RowError
+
+__all__ = ["ImportFailed", "ImportResult", "Item", "RowError", "import_inventory"]

patchground/catalog/csv-import-row-errors/workspace/src/stockimport/importer.py

@@ -0,0 +1,69 @@
+"""Strict CSV import for the warehouse stock feed."""
+
+from __future__ import annotations
+
+import csv
+import io
+import re
+from collections.abc import Iterator
+
+from .models import ImportFailed, Item, RowError
+
+HEADER = ["sku", "quantity", "unit_price"]
+
+_SKU = re.compile(r"[A-Z0-9-]+")
+_QUANTITY = re.compile(r"[0-9]+")
+_PRICE = re.compile(r"([0-9]+)(?:\.([0-9]{1,2}))?")
+
+
+def _fail(line: int, column: str | None, code: str, message: str) -> ImportFailed:
+    return ImportFailed(RowError(line, column, code, message))
+
+
+def import_inventory(text: str) -> list[Item]:
+    """Parse ``text`` and return its items in file order.
+
+    The first problem found stops the import with ``ImportFailed``.
+    """
+    reader = csv.reader(io.StringIO(text, newline=""), strict=True)
+    _read_header(reader)
+    items: list[Item] = []
+    seen: set[str] = set()
+    while True:
+        line = reader.line_num + 1  # physical line where the next record starts
+        try:
+            record = next(reader)
+        except StopIteration:
+            return items
+        except csv.Error as exc:
+            raise _fail(line, None, "malformed_csv", str(exc)) from None
+        if record:  # a physical line with no characters yields []
+            items.append(_parse_record(record, line, seen))
+
+
+def _read_header(reader: Iterator[list[str]]) -> None:
+    try:
+        header = next(reader)
+    except (StopIteration, csv.Error):
+        header = None
+    if header != HEADER:
+        raise _fail(1, None, "bad_header", "header must be exactly sku,quantity,unit_price")
+
+
+def _parse_record(record: list[str], line: int, seen: set[str]) -> Item:
+    if len(record) != 3:
+        raise _fail(line, None, "wrong_field_count", f"expected 3 fields, got {len(record)}")
+    sku, quantity, price = record
+    if not _SKU.fullmatch(sku):
+        raise _fail(line, "sku", "invalid_sku", f"invalid sku {sku!r}")
+    if sku in seen:
+        raise _fail(line, "sku", "duplicate_sku", f"duplicate sku {sku!r}")
+    seen.add(sku)
+    if not _QUANTITY.fullmatch(quantity):
+        raise _fail(line, "quantity", "invalid_quantity", f"invalid quantity {quantity!r}")
+    match = _PRICE.fullmatch(price)
+    if match is None:
+        raise _fail(line, "unit_price", "invalid_price", f"invalid unit_price {price!r}")
+    dollars, fraction = match.groups()
+    cents = int(dollars) * 100 + int((fraction or "").ljust(2, "0"))
+    return Item(sku, int(quantity), cents)

patchground/catalog/csv-import-row-errors/workspace/src/stockimport/models.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Item:
+    sku: str
+    quantity: int
+    unit_price_cents: int
+
+
+@dataclass(frozen=True)
+class RowError:
+    line: int
+    column: str | None
+    code: str
+    message: str
+
+
+@dataclass(frozen=True)
+class ImportResult:
+    items: list[Item]
+    errors: list[RowError]
+
+
+class ImportFailed(ValueError):
+    """Raised when an import stops; ``error`` says why."""
+
+    def __init__(self, error: RowError) -> None:
+        super().__init__(f"line {error.line}: {error.message}")
+        self.error = error

patchground/catalog/duplicate-charges-on-retry/TICKET.md

@@ -0,0 +1,28 @@
+# Duplicate charges after a payment retry
+
+Support reproduced a checkout charging twice when the provider accepted a payment
+but its response timed out. The next transport attempt returned success, so the
+customer saw one successful checkout and two ledger entries.
+
+Fix the payment flow and add a regression check. The public entry point is
+`PaymentService(gateway, max_attempts=3).pay(request_id, amount_cents)` in
+`src/payments/service.py`. Use the offline gateway in `src/payments/gateway.py`;
+its scripted events reproduce outages without network access or sleeps.
+
+Required behavior:
+- One logical request must create at most one charge, including after a lost
+  success response and when submitted again through a new service instance
+  sharing the same gateway. Successful repeats return the same receipt.
+- Different request IDs represent different payments even for equal amounts.
+  Reusing an ID with a different amount raises `RequestConflict`.
+- Retry only `GatewayTimeout`, at most `max_attempts` total calls per invocation.
+  If all attempts time out, expose the final timeout. Propagate `PaymentDeclined`
+  and invalid input immediately. Amounts are positive integer cents.
+- Preserve the `Receipt(charge_id, amount_cents)` API and gateway semantics.
+
+The simulator persists accepted requests only for the lifetime of its gateway
+instance. Cross-process persistence, concurrent workers, real providers, backoff,
+credentials and payment security are outside this exercise. Work in application
+code and conventional pytest checks; keep verification configuration intact.
+
+Run checks using Patchground's container commands. No real payments are made.

patchground/catalog/duplicate-charges-on-retry/challenge.yaml

@@ -0,0 +1,30 @@
+spec_version: "0.1"
+id: duplicate-charges-on-retry
+version: 1.0.1
+title: Duplicate charges after a payment retry
+type: debug
+summary: A successful charge followed by a timeout causes a retry to charge twice.
+languages: [python]
+tags: [idempotency, retries, payments]
+difficulty: intermediate
+timebox_minutes: 45
+ai_policy: allowed
+environment:
+  dockerfile: environment/Dockerfile
+  services: []
+  test_command: pytest -q -p no:cacheprovider --junitxml=$PG_RESULTS/junit.xml
+checks:
+  visible: checks/visible
+  hidden: checks/hidden
+solution: solution/reference.patch
+expected_paths: [src/payments/, tests/]
+hints:
+  - A timeout says nothing about whether the provider committed the charge.
+  - Compare the identity of a logical payment with the identity of a transport attempt.
+debrief:
+  questions: debrief/questions.md
+  focus: [debugging_method, test_quality, scope_judgment]
+author: {name: Patchground contributors}
+content_license: CC-BY-4.0
+provenance: generated
+generated_by: {model: "Codex configured default (model unverified)", prompt_version: launch-payment-v1}

patchground/catalog/duplicate-charges-on-retry/checks/hidden/tests/test_payment_regressions.py

@@ -0,0 +1,87 @@
+import pytest
+from payments.gateway import OfflineGateway
+from payments.models import GatewayTimeout, RequestConflict
+from payments.service import PaymentService
+
+
+def test_ambiguous_acceptance_has_one_ledger_entry():
+    gateway = OfflineGateway(("timeout_before", "timeout_after", "ok"))
+    receipt = PaymentService(gateway).pay("invoice-71", 8317)
+    assert len(gateway.charges) == 1
+    assert list(gateway.charges.values()) == [receipt]
+    assert len(gateway.calls) == 3
+
+
+def test_replay_from_another_service_returns_original_receipt():
+    gateway = OfflineGateway(("timeout_after", "ok"))
+    first = PaymentService(gateway).pay("invoice-72", 1800)
+    second = PaymentService(gateway).pay("invoice-72", 1800)
+    assert first == second
+    assert len(gateway.charges) == 1
+
+
+def test_equal_amounts_with_different_ids_are_distinct():
+    gateway = OfflineGateway()
+    service = PaymentService(gateway)
+    first = service.pay("invoice-73", 999)
+    second = service.pay("invoice-74", 999)
+    assert first.charge_id != second.charge_id
+    assert len(gateway.charges) == 2
+
+
+def test_changed_amount_after_ambiguous_acceptance_is_rejected():
+    gateway = OfflineGateway(("timeout_after", "ok"))
+    service = PaymentService(gateway)
+    service.pay("invoice-75", 4100)
+    before = len(gateway.calls)
+    with pytest.raises(RequestConflict):
+        service.pay("invoice-75", 4200)
+    assert len(gateway.calls) == before + 1
+    assert len(gateway.charges) == 1
+
+
+def test_later_invocation_recovers_accepted_charge_after_exhaustion():
+    gateway = OfflineGateway(("timeout_after",))
+    with pytest.raises(GatewayTimeout):
+        PaymentService(gateway, max_attempts=1).pay("invoice-76", 300)
+    receipt = PaymentService(gateway).pay("invoice-76", 300)
+    assert list(gateway.charges.values()) == [receipt]
+    assert len(gateway.calls) == 2
+
+
+def test_before_acceptance_retry_recovers():
+    gateway = OfflineGateway(("timeout_before", "ok"))
+    receipt = PaymentService(gateway).pay("invoice-77", 700)
+    assert list(gateway.charges.values()) == [receipt]
+    assert len(gateway.calls) == 2
+
+
+def test_final_timeout_is_exposed_without_extra_attempts():
+    gateway = OfflineGateway(("timeout_before",) * 5)
+    with pytest.raises(GatewayTimeout, match="before acceptance"):
+        PaymentService(gateway, max_attempts=3).pay("invoice-78", 2200)
+    assert len(gateway.calls) == 3
+    assert not gateway.charges
+
+
+@pytest.mark.parametrize("amount", [0, -1, True, 1.5, "100"])
+def test_invalid_amount_does_not_create_charge(amount):
+    gateway = OfflineGateway()
+    with pytest.raises(ValueError):
+        PaymentService(gateway).pay("invoice-79", amount)
+    assert not gateway.charges
+    assert not gateway.calls
+
+
+@pytest.mark.parametrize("request_id", ["", "  ", None])
+def test_invalid_request_identity_does_not_reach_provider(request_id):
+    gateway = OfflineGateway()
+    with pytest.raises(ValueError):
+        PaymentService(gateway).pay(request_id, 100)
+    assert not gateway.calls
+
+
+@pytest.mark.parametrize("limit", [0, -2, True, 1.5])
+def test_invalid_retry_limit_is_rejected(limit):
+    with pytest.raises(ValueError):
+        PaymentService(OfflineGateway(), max_attempts=limit)

patchground/catalog/duplicate-charges-on-retry/checks/visible/tests/test_checkout.py

@@ -0,0 +1,34 @@
+import pytest
+from payments.gateway import OfflineGateway
+from payments.models import GatewayTimeout, PaymentDeclined
+from payments.service import PaymentService
+
+
+def test_successful_checkout():
+    gateway = OfflineGateway()
+    receipt = PaymentService(gateway).pay("order-a", 1250)
+    assert receipt.amount_cents == 1250
+    assert len(gateway.charges) == 1
+
+
+def test_lost_success_response_does_not_charge_twice():
+    gateway = OfflineGateway(("timeout_after", "ok"))
+    receipt = PaymentService(gateway).pay("order-b", 2500)
+    assert receipt.amount_cents == 2500
+    assert len(gateway.charges) == 1
+
+
+def test_decline_is_terminal():
+    gateway = OfflineGateway(("declined", "ok"))
+    with pytest.raises(PaymentDeclined):
+        PaymentService(gateway).pay("order-c", 500)
+    assert len(gateway.calls) == 1
+    assert not gateway.charges
+
+
+def test_transport_retries_are_bounded():
+    gateway = OfflineGateway(("timeout_before",) * 4)
+    with pytest.raises(GatewayTimeout):
+        PaymentService(gateway, max_attempts=2).pay("order-d", 500)
+    assert len(gateway.calls) == 2
+    assert not gateway.charges

patchground/catalog/duplicate-charges-on-retry/debrief/questions.md

@@ -0,0 +1,6 @@
+# Debrief
+
+- Which observation distinguishes a transport failure from a rejected payment?
+- What lifetime should a logical request identity have?
+- Which regression check catches a duplicate even if checkout returns success?
+- What would a real provider need to guarantee for concurrent calls and restarts?

patchground/catalog/duplicate-charges-on-retry/environment/Dockerfile

@@ -0,0 +1,3 @@
+FROM python:3.12-slim
+ENV PYTHONDONTWRITEBYTECODE=1
+RUN pip install --no-cache-dir pytest==8.3.5

patchground/catalog/duplicate-charges-on-retry/solution/reference.patch

@@ -0,0 +1,11 @@
+--- a/src/payments/service.py
++++ b/src/payments/service.py
+@@ -14,7 +14,7 @@
+         if not isinstance(request_id, str) or not request_id.strip():
+             raise ValueError("request_id must be nonempty")
+         for attempt in range(self.max_attempts):
+-            provider_key = f"{request_id}:attempt-{attempt}"
++            provider_key = request_id
+             try:
+                 return self.gateway.charge(provider_key, amount_cents)
+             except GatewayTimeout:

patchground/catalog/duplicate-charges-on-retry/workspace/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "checkout-payments"
+version = "0.1.0"
+requires-python = ">=3.12"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

patchground/catalog/duplicate-charges-on-retry/workspace/src/payments/__init__.py

@@ -0,0 +1 @@
+"""Offline checkout payment example."""

patchground/catalog/duplicate-charges-on-retry/workspace/src/payments/gateway.py

@@ -0,0 +1,38 @@
+from collections import deque
+
+from payments.models import GatewayTimeout, PaymentDeclined, Receipt, RequestConflict
+
+
+class OfflineGateway:
+    """Deterministic provider simulator; state lasts for this instance only.
+
+    Events: ok, timeout_before, timeout_after, declined. An already committed
+    key returns its receipt before consuming any event. No network or credentials.
+    """
+
+    def __init__(self, events: tuple[str, ...] = ()) -> None:
+        self._events = deque(events)
+        self.charges: dict[str, Receipt] = {}
+        self.calls: list[tuple[str, int]] = []
+
+    def charge(self, key: str, amount_cents: int) -> Receipt:
+        if not key or type(amount_cents) is not int or amount_cents <= 0:
+            raise ValueError("key and positive integer amount_cents required")
+        self.calls.append((key, amount_cents))
+        if key in self.charges:
+            receipt = self.charges[key]
+            if receipt.amount_cents != amount_cents:
+                raise RequestConflict("request already used for another amount")
+            return receipt
+        event = self._events.popleft() if self._events else "ok"
+        if event == "timeout_before":
+            raise GatewayTimeout("connection lost before acceptance")
+        if event == "declined":
+            raise PaymentDeclined("payment declined")
+        if event not in {"ok", "timeout_after"}:
+            raise ValueError("unknown simulator event")
+        receipt = Receipt(f"charge-{len(self.charges) + 1:04d}", amount_cents)
+        self.charges[key] = receipt
+        if event == "timeout_after":
+            raise GatewayTimeout("response lost after acceptance")
+        return receipt

patchground/catalog/duplicate-charges-on-retry/workspace/src/payments/models.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+
+
+class GatewayTimeout(TimeoutError):
+    """Transport outcome is unknown; retry is allowed."""
+
+
+class PaymentDeclined(Exception):
+    """Terminal rejection; do not retry."""
+
+
+class RequestConflict(Exception):
+    """A request identity was reused with different payment details."""
+
+
+@dataclass(frozen=True)
+class Receipt:
+    charge_id: str
+    amount_cents: int

patchground/catalog/duplicate-charges-on-retry/workspace/src/payments/service.py

@@ -0,0 +1,23 @@
+from payments.gateway import OfflineGateway
+from payments.models import GatewayTimeout, Receipt
+
+
+class PaymentService:
+    def __init__(self, gateway: OfflineGateway, max_attempts: int = 3) -> None:
+        if type(max_attempts) is not int or max_attempts < 1:
+            raise ValueError("max_attempts must be a positive integer")
+        self.gateway = gateway
+        self.max_attempts = max_attempts
+
+    def pay(self, request_id: str, amount_cents: int) -> Receipt:
+        """Return a receipt, retrying only ambiguous transport failures."""
+        if not isinstance(request_id, str) or not request_id.strip():
+            raise ValueError("request_id must be nonempty")
+        for attempt in range(self.max_attempts):
+            provider_key = f"{request_id}:attempt-{attempt}"
+            try:
+                return self.gateway.charge(provider_key, amount_cents)
+            except GatewayTimeout:
+                if attempt + 1 == self.max_attempts:
+                    raise
+        raise AssertionError("unreachable")

patchground/catalog/event-bus-subscriptions/TICKET.md

@@ -0,0 +1,108 @@
+# Let subscribers unsubscribe and listen once on the event bus
+
+**Reported by:** CLI tooling team
+**Component:** `localbus` (`src/bus.ts`)
+
+## Background
+
+`EventBus` is a small synchronous in-process bus. Today `on(topic, handler)` registers a handler and
+`emit(topic, payload)` calls the registered handlers in order and returns how many it called. There is
+no way to take a subscription back, and no way to listen for a single event. Two stubs exist so callers
+can already import the final API: `on` returns an unsubscribe function that does nothing, and `once`
+throws "not implemented".
+
+## Request
+
+Make `on` return a working unsubscribe function, implement `once`, and make `emit` safe when handlers
+subscribe, unsubscribe, re-enter or throw. All other behavior must stay as it is.
+
+### Public API
+
+```ts
+type Handler = (payload: unknown) => void;
+type Unsubscribe = () => void;
+
+class EventBus {
+  on(topic: string, handler: Handler): Unsubscribe;
+  once(topic: string, handler: Handler): Unsubscribe;
+  emit(topic: string, payload?: unknown): number;
+}
+```
+
+The checks run the code at runtime with Vitest. They do not run the TypeScript compiler, so they make
+no claim about type correctness.
+
+### Scope
+
+Everything is synchronous. There are no wildcards or patterns, no priorities and no compatibility
+with Node's `EventEmitter`. A handler's return value is ignored: if it returns a promise, the bus does
+not wait for it and does not look at it.
+
+### Clauses
+
+**C1 Topics.** A topic is any string, compared exactly and case-sensitively; the empty string is a
+valid topic. `*`, `.` and similar characters have no special meaning, so `emit("user.created")` never
+reaches a handler registered for `"user.*"` or `"*"`. Separate `EventBus` instances share nothing.
+
+**C2 Order and duplicates.** Handlers for a topic run in registration order, whether they were
+registered with `on` or `once`. Registering the same function again, with `on` or `once`, creates an
+independent subscription; it runs once per subscription per emit and has its own unsubscribe function.
+
+**C3 Payload.** Each handler is called with exactly one argument: the `payload` given to `emit`, the
+same value and reference (no copy). If `emit` is called without a payload, handlers receive
+`undefined`. Falsy payloads (`0`, `""`, `false`, `null`) are delivered as they are.
+
+**C4 Return value.** `emit` returns the number of handler invocations it made: `0` if the topic has no
+subscribers. A `once` subscription that was skipped (C7) is not counted. If any handler throws, `emit`
+throws (C8) and returns nothing.
+
+**C5 Unsubscribe.** `on` and `once` return an unsubscribe function for that one subscription. Calling
+it removes that subscription from later emits. Calling it again does nothing, and never removes
+another subscription, even one that uses the same handler function. Unsubscribing a `once`
+subscription that has already run does nothing. Order of the remaining subscriptions is unchanged.
+
+**C6 Snapshot.** When `emit` starts it captures the subscriptions of that topic, in registration
+order, and calls exactly those. Subscriptions added during the emit run from the next emit on.
+Unsubscribing during the emit takes effect for later emits only: a captured subscription still gets its
+turn in the emit that captured it, whether it was registered with `on` or `once`. A nested `emit`
+(called from a handler) captures its own snapshot from the subscriptions that exist at that moment.
+
+**C7 Once.** A `once` subscription runs at most once. It is consumed immediately before its handler
+is called, so it stays consumed if the handler throws, and a handler that emits its own topic is not
+called again. A captured `once` subscription whose turn comes after it was already consumed, for
+example by a nested `emit`, is skipped and not counted. Being unsubscribed does not consume it (C6).
+
+Example:
+
+```ts
+const bus = new EventBus();
+const log: string[] = [];
+let nested = false;
+bus.on("tick", () => {
+  log.push("first");
+  if (!nested) {
+    nested = true;
+    bus.emit("tick"); // returns 3: first, once, last
+  }
+});
+bus.once("tick", () => log.push("once"));
+bus.on("tick", () => log.push("last"));
+bus.emit("tick"); // returns 2: first, last (the once handler was consumed by the nested emit)
+// log: first, first, once, last, last
+```
+
+**C8 Errors.** A handler that throws does not stop later handlers of the same snapshot. After the last
+captured subscription's turn, if any handler threw, `emit` throws an `AggregateError` whose `errors`
+lists the thrown values in invocation order, unchanged (not wrapped, and not only `Error` objects).
+One failure still produces an `AggregateError` with one entry. If a handler's own nested `emit` throws
+an `AggregateError`, that `AggregateError` is a single entry. The message text is not specified. The
+bus stays fully usable: consumed `once` subscriptions stay consumed, other subscriptions stay
+registered, and changes made by handlers before or after a failure still apply.
+
+## Notes
+
+- Keep `src/bus.ts` as the module that exports `EventBus`, `Handler` and `Unsubscribe`.
+- Run `pgnd check` from the session workspace to check your changes in Docker.
+- Add tests for the behavior you implement and keep the existing behavior unchanged.
+- You may use your own editor and AI tools. The goal is to build and explain a precise change, not
+  only to make the listed cases pass.