patchground 0.1.0__py3-none-any.whl

patchground/catalog/event-bus-subscriptions/environment/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "patchground-vitest-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "vitest": "5.0.5",
+    "vite": "8.3.5"
+  },
+  "scripts": {
+    "test": "node --check vitest-runner.mjs"
+  }
+}

patchground/catalog/event-bus-subscriptions/environment/vitest-runner.mjs

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, writeFile, rename, rm, lstat, realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = '/workspace';
+const final = '/results/junit.xml';
+const self = fileURLToPath(import.meta.url);
+
+async function child(destination, files) {
+  const { startVitest } = await import('vitest/node');
+  let completed;
+  const reporter = {
+    onTestModuleCollected(module) {
+      for (const test of module.children.allTests()) {
+        const retry = test.options.retry;
+        const count = typeof retry === 'number' ? retry : retry?.count ?? 0;
+        if (count > 0 || (test.options.repeats ?? 0) > 0) {
+          throw Error('Retries and repeats are unsupported');
+        }
+      }
+    },
+    onTestRunEnd(modules, errors, reason) {
+      const cases = [];
+      let trustworthy = errors.length === 0 && reason !== 'interrupted';
+      for (const module of modules) {
+        if (module.errors().length) trustworthy = false;
+        for (const suite of module.children.allSuites()) {
+          if (suite.errors().length) trustworthy = false;
+        }
+        for (const test of module.children.allTests()) {
+          const state = test.result().state;
+          if (!['passed', 'failed', 'skipped'].includes(state)) trustworthy = false;
+          cases.push({ file: module.relativeModuleId, name: test.fullName, state });
+        }
+      }
+      completed = { trustworthy, cases };
+    },
+  };
+  const ctx = await startVitest([], {
+    root, config: false, watch: false, run: true,
+    include: files.length ? files : ['**/*.test.ts'], exclude: ['**/node_modules/**', '**/.git/**'],
+    reporters: [reporter], environment: 'node', pool: 'forks', maxWorkers: 1,
+    fileParallelism: false, isolate: true, retry: 0, allowOnly: false, maxConcurrency: 1,
+    passWithNoTests: false, testTimeout: 5000, hookTimeout: 5000,
+    sequence: { shuffle: false },
+  }, {
+    configFile: false, envDir: false, cacheDir: '/tmp/patchground-vite',
+    resolve: { alias: { vitest: '/opt/patchground/node_modules/vitest/dist/index.js' } },
+  });
+  await ctx.close();
+  if (!completed || ctx.state.getUnhandledErrors().length) return;
+  await writeFile(destination, JSON.stringify(completed), { flag: 'wx' });
+}
+
+function escape(value) {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;').replaceAll("'", '&apos;').replaceAll("\n", "&#10;")
+    .replaceAll("\r", "&#13;").replaceAll("\t", "&#9;");
+}
+
+async function parent() {
+  await rm(final, { force: true });
+  const temporary = await mkdtemp(path.join(tmpdir(), 'patchground-vitest-'));
+  try {
+    const receipt = path.join(temporary, 'receipt.json');
+    const args = process.argv.slice(2);
+    const files = args.length ? args.slice(1) : [];
+    if (args.length && (args[0] !== '--files' || !files.length)) return;
+    for (const file of files) {
+      const parts = file.split('/');
+      if (!file.endsWith('.test.ts') || parts.some(part =>
+        !/^[\p{L}\p{N}_. -]+$/u.test(part) || ['.', '..', '.git', 'node_modules'].includes(part))) return;
+    }
+    if (new Set(files).size !== files.length) return;
+    for (const file of files) {
+      const full = path.join(root, file);
+      if (!(await lstat(full)).isFile() || !(await realpath(full)).startsWith(root + '/')) return;
+    }
+    const code = await new Promise((resolve, reject) => {
+      const process = spawn(globalThis.process.execPath, [self, '--child', receipt, ...files], {
+        stdio: 'ignore', env: { ...globalThis.process.env, CI: 'true' },
+      });
+      process.once('error', reject);
+      process.once('exit', (code, signal) => resolve(signal ? null : code));
+    });
+    const result = JSON.parse(await readFile(receipt, 'utf8'));
+    if (!result.trustworthy || !result.cases.length) return;
+    const failed = result.cases.some(test => test.state === 'failed');
+    if (code !== (failed ? 1 : 0)) return;
+    const seen = new Set();
+    result.cases.sort((a, b) => {
+      const left = `${a.file}::${a.name}`;
+      const right = `${b.file}::${b.name}`;
+      return left < right ? -1 : left > right ? 1 : 0;
+    });
+    const cases = result.cases.map(test => {
+      if (!test.file || path.posix.isAbsolute(test.file) || test.file.split('/').includes('..')
+          || test.file.includes('\\') || !test.file.endsWith('.test.ts') || !test.name
+          || !test.file.isWellFormed() || !test.name.isWellFormed()
+          || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/u.test(test.file + test.name)) throw Error('unsafe identity');
+      const id = `${test.file}::${test.name}`;
+      if (seen.has(id)) throw Error('duplicate identity');
+      seen.add(id);
+      const status = test.state === 'failed' ? '<failure message="test failed"/>'
+        : test.state === 'skipped' ? '<skipped/>' : '';
+      return `<testcase classname="${escape(test.file)}" name="${escape(test.name)}">${status}</testcase>`;
+    });
+    const staging = '/results/.patchground-junit.xml';
+    await writeFile(staging, `<?xml version="1.0" encoding="UTF-8"?><testsuites><testsuite name="vitest">${cases.join('')}</testsuite></testsuites>`);
+    await rename(staging, final);
+    process.exitCode = failed ? 1 : 0;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+
+try {
+  if (process.argv[2] === '--child') await child(process.argv[3], process.argv.slice(4));
+  else { process.exitCode = 1; await parent(); }
+} catch {
+  process.exitCode = 1;
+}

patchground/catalog/event-bus-subscriptions/solution/reference.patch

@@ -0,0 +1,82 @@
+diff --git a/src/bus.ts b/src/bus.ts
+index 60d54f7..86d7dec 100644
+--- a/src/bus.ts
++++ b/src/bus.ts
+@@ -3,30 +3,65 @@
+ export type Handler = (payload: unknown) => void;
+ export type Unsubscribe = () => void;
+
++interface Subscription {
++  readonly handler: Handler;
++  readonly once: boolean;
++  consumed: boolean;
++}
++
+ export class EventBus {
+-  private readonly handlers = new Map<string, Handler[]>();
++  private readonly subscriptions = new Map<string, Subscription[]>();
+
+   /** Register `handler` for exactly `topic`. Handlers run in registration order. */
+   on(topic: string, handler: Handler): Unsubscribe {
+-    const list = this.handlers.get(topic) ?? [];
+-    list.push(handler);
+-    this.handlers.set(topic, list);
+-    // Not implemented yet: there is no way to take a subscription back.
+-    return () => {};
++    return this.subscribe(topic, handler, false);
+   }
+
+-  /** Not implemented yet. */
+-  once(_topic: string, _handler: Handler): Unsubscribe {
+-    throw new Error("EventBus.once is not implemented");
++  /** Like `on`, but the handler is consumed immediately before its first call. */
++  once(topic: string, handler: Handler): Unsubscribe {
++    return this.subscribe(topic, handler, true);
+   }
+
+-  /** Call every handler registered for `topic` and return how many were called. */
++  /**
++   * Call the subscriptions that exist when the emit starts and return how many handlers were called.
++   * Throws an AggregateError after the last turn if any handler threw.
++   */
+   emit(topic: string, payload?: unknown): number {
++    const captured = [...(this.subscriptions.get(topic) ?? [])];
++    const errors: unknown[] = [];
+     let called = 0;
+-    for (const handler of this.handlers.get(topic) ?? []) {
+-      handler(payload);
++    for (const subscription of captured) {
++      if (subscription.once) {
++        if (subscription.consumed) continue;
++        subscription.consumed = true;
++        this.remove(topic, subscription);
++      }
+       called += 1;
++      try {
++        subscription.handler(payload);
++      } catch (error) {
++        errors.push(error);
++      }
++    }
++    if (errors.length > 0) {
++      throw new AggregateError(errors, `${errors.length} handler(s) threw while emitting "${topic}"`);
+     }
+     return called;
+   }
++
++  private subscribe(topic: string, handler: Handler, once: boolean): Unsubscribe {
++    const subscription: Subscription = { handler, once, consumed: false };
++    const list = this.subscriptions.get(topic) ?? [];
++    list.push(subscription);
++    this.subscriptions.set(topic, list);
++    return () => this.remove(topic, subscription);
++  }
++
++  private remove(topic: string, subscription: Subscription): void {
++    const list = this.subscriptions.get(topic);
++    const index = list === undefined ? -1 : list.indexOf(subscription);
++    if (list === undefined || index === -1) return;
++    list.splice(index, 1);
++    if (list.length === 0) this.subscriptions.delete(topic);
++  }
+ }

patchground/catalog/event-bus-subscriptions/workspace/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "localbus",
+  "version": "0.2.0",
+  "private": true,
+  "type": "module"
+}

patchground/catalog/event-bus-subscriptions/workspace/src/bus.ts

@@ -0,0 +1,32 @@
+/** A small synchronous in-process event bus used by a command-line tool. */
+
+export type Handler = (payload: unknown) => void;
+export type Unsubscribe = () => void;
+
+export class EventBus {
+  private readonly handlers = new Map<string, Handler[]>();
+
+  /** Register `handler` for exactly `topic`. Handlers run in registration order. */
+  on(topic: string, handler: Handler): Unsubscribe {
+    const list = this.handlers.get(topic) ?? [];
+    list.push(handler);
+    this.handlers.set(topic, list);
+    // Not implemented yet: there is no way to take a subscription back.
+    return () => {};
+  }
+
+  /** Not implemented yet. */
+  once(_topic: string, _handler: Handler): Unsubscribe {
+    throw new Error("EventBus.once is not implemented");
+  }
+
+  /** Call every handler registered for `topic` and return how many were called. */
+  emit(topic: string, payload?: unknown): number {
+    let called = 0;
+    for (const handler of this.handlers.get(topic) ?? []) {
+      handler(payload);
+      called += 1;
+    }
+    return called;
+  }
+}

patchground/catalog/order-notifications-boundary/TICKET.md

@@ -0,0 +1,51 @@
+# Order confirmations can't get an SMS channel or a fast test suite
+
+**Reported by:** the notifications team and the storefront on-call rota
+**Component:** `orders`
+
+## Symptom
+
+Two pieces of work are stuck on the same module:
+
+1. Marketing wants confirmations by SMS as well as email. The SMS provider's client is ready, but
+   there is nowhere to plug it in: `orders/service.py` imports `SmtpNotifier` and constructs it
+   inside `confirm`.
+2. The checkout team's tests take minutes because every `OrderService` test writes a SQLite file
+   and an outbox file. They asked for an in-memory setup and were told "the service builds its own
+   store, there's nothing to swap".
+
+Both teams have proposed copy-pasting `OrderService`. We would rather fix the shape of the module.
+
+## Reproduction
+
+```python
+from orders.service import OrderService
+
+OrderService("orders.db", "outbox.jsonl")   # the only way to build one
+```
+
+Open `src/orders/service.py`: it imports `orders.sqlite_store` and `orders.smtp_gateway` directly
+and instantiates both on every call.
+
+## Expected
+
+- `src/orders/ports.py` defines two `typing.Protocol`s, decorated `@runtime_checkable`:
+  `OrderRepository` (`save_confirmed(order)`, `get(order_id)`) and `Notifier`
+  (`send(to, subject, body)`).
+- `OrderService` takes its collaborators by keyword: `OrderService(repository=..., notifier=...)`.
+  It no longer accepts paths and no longer imports `orders.sqlite_store`, `orders.smtp_gateway`,
+  `sqlite3` or `smtplib`.
+- `SqliteOrderRepository` and `SmtpNotifier` keep their names and behaviour and satisfy the ports.
+- `orders.app.build_service(db_path, outbox)` is the one place that wires the real adapters, so
+  the existing end-to-end tests keep passing unchanged.
+- The confirmation message format, the empty-order rejection and `find` behave exactly as before.
+
+## Notes
+
+- This is a refactor: no behaviour change is wanted. Visible tests go through `build_service` and
+  must stay green throughout.
+- Add a test that builds `OrderService` with in-memory fakes and checks a confirmation end to end,
+  without touching the filesystem.
+- Run `pgnd check` from the session workspace to check your changes in Docker.
+- You may use your own editor and AI tools. The goal is a module whose boundaries are explicit,
+  not merely tests that pass.

patchground/catalog/order-notifications-boundary/challenge.yaml

@@ -0,0 +1,32 @@
+spec_version: "0.1"
+id: order-notifications-boundary
+version: 1.0.0
+title: Put a port between the order service and its storage and email
+type: refactor
+summary: >-
+  OrderService imports and constructs SQLite and SMTP adapters itself, so nothing can be swapped
+  for SMS or for fast tests. Introduce ports, inject the adapters and keep behaviour identical.
+languages: [python]
+tags: [architecture, ports-and-adapters, dependency-inversion, refactoring]
+difficulty: intermediate
+timebox_minutes: 40
+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/orders/, tests/]
+hints:
+  - Draw the arrows. Today service -> sqlite_store and service -> smtp_gateway. Which module should own the interface the service calls, so that the arrows point towards the service instead?
+  - A Protocol describes what the service needs; the adapters already have those methods. Make the service receive them instead of building them, and move the construction to app.build_service.
+debrief:
+  questions: debrief/questions.md
+  focus: [design_judgment, test_quality, scope_judgment]
+author: {name: Fran Delicado, github: franndeli}
+content_license: CC-BY-4.0
+provenance: generated
+generated_by: {model: "Claude (Anthropic) via pi coding agent, model id unverified", prompt_version: launch-boundary-v1}

patchground/catalog/order-notifications-boundary/checks/hidden/tests/test_boundary_hidden.py

@@ -0,0 +1,87 @@
+"""Architecture checks: the service depends on ports, not on SQLite or SMTP."""
+
+import ast
+import importlib
+import inspect
+from pathlib import Path
+
+import pytest
+
+from orders import Order, OrderLine
+
+SRC = Path(__file__).resolve().parents[1] / "src" / "orders"
+INFRASTRUCTURE = {"orders.sqlite_store", "orders.smtp_gateway", "sqlite3", "smtplib"}
+
+
+def imported_modules(path: Path) -> set[str]:
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    found: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            found.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            found.add(node.module)
+    return found
+
+
+def test_service_module_has_no_infrastructure_imports():
+    assert not imported_modules(SRC / "service.py") & INFRASTRUCTURE
+
+
+def test_ports_module_defines_runtime_checkable_protocols():
+    ports = importlib.import_module("orders.ports")
+    for name in ("OrderRepository", "Notifier"):
+        port = getattr(ports, name)
+        assert getattr(port, "_is_protocol", False), f"{name} must be a typing.Protocol"
+        assert getattr(port, "_is_runtime_protocol", False), f"{name} must be @runtime_checkable"
+
+
+def test_adapters_satisfy_their_ports(tmp_path):
+    ports = importlib.import_module("orders.ports")
+    from orders.smtp_gateway import SmtpNotifier
+    from orders.sqlite_store import SqliteOrderRepository
+
+    assert isinstance(SqliteOrderRepository(tmp_path / "db"), ports.OrderRepository)
+    assert isinstance(SmtpNotifier(tmp_path / "out"), ports.Notifier)
+
+
+class MemoryRepository:
+    def __init__(self):
+        self.saved = {}
+
+    def save_confirmed(self, order):
+        self.saved[order.order_id] = order
+
+    def get(self, order_id):
+        return self.saved.get(order_id)
+
+
+class MemoryNotifier:
+    def __init__(self):
+        self.sent = []
+
+    def send(self, to, subject, body):
+        self.sent.append((to, subject, body))
+
+
+def test_service_takes_injected_ports_by_keyword():
+    from orders.service import OrderService
+
+    parameters = inspect.signature(OrderService).parameters
+    assert {"repository", "notifier"} <= set(parameters)
+    repository, notifier = MemoryRepository(), MemoryNotifier()
+    service = OrderService(repository=repository, notifier=notifier)
+    order = Order("o-9", "grace@example.test", (OrderLine("desk", 1, 20000),))
+    service.confirm(order)
+    assert repository.saved == {"o-9": order}
+    assert notifier.sent == [
+        ("grace@example.test", "Order o-9 confirmed", "Thanks for your order.\n- 1 x desk @ 200.00\nTotal: 200.00")
+    ]
+    assert service.find("o-9") == order
+
+
+def test_service_does_not_construct_adapters_itself():
+    from orders.service import OrderService
+
+    with pytest.raises(TypeError):
+        OrderService("orders.db", "outbox.jsonl")

patchground/catalog/order-notifications-boundary/checks/visible/tests/test_confirmation.py

@@ -0,0 +1,41 @@
+import json
+
+from orders import Order, OrderLine
+from orders.app import build_service
+
+
+def order(order_id="o-1"):
+    return Order(order_id, "ada@example.test", (OrderLine("chair", 2, 4999), OrderLine("lamp", 1, 1500)))
+
+
+def test_confirm_persists_and_emails(tmp_path):
+    outbox = tmp_path / "outbox.jsonl"
+    service = build_service(str(tmp_path / "orders.db"), str(outbox))
+    service.confirm(order())
+    assert service.find("o-1") == order()
+    sent = [json.loads(line) for line in outbox.read_text().splitlines()]
+    assert sent == [
+        {
+            "to": "ada@example.test",
+            "subject": "Order o-1 confirmed",
+            "body": "Thanks for your order.\n- 2 x chair @ 49.99\n- 1 x lamp @ 15.00\nTotal: 114.98",
+        }
+    ]
+
+
+def test_empty_order_is_rejected_before_any_side_effect(tmp_path):
+    outbox = tmp_path / "outbox.jsonl"
+    service = build_service(str(tmp_path / "orders.db"), str(outbox))
+    try:
+        service.confirm(Order("o-2", "ada@example.test", ()))
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("expected ValueError")
+    assert service.find("o-2") is None
+    assert not outbox.exists()
+
+
+def test_unknown_order_is_none(tmp_path):
+    service = build_service(str(tmp_path / "orders.db"), str(tmp_path / "outbox.jsonl"))
+    assert service.find("missing") is None

patchground/catalog/order-notifications-boundary/debrief/questions.md

@@ -0,0 +1,5 @@
+- Which dependency direction did you reverse, and what now knows about SQLite and SMTP?
+- Why do the protocols belong to the service's side of the boundary rather than next to the adapters?
+- What did you keep unchanged on purpose, and how did the visible tests help you prove it?
+- Where would an SMS notifier go, and what, if anything, in `service.py` would have to change?
+- If an AI assistant proposed the refactor, what did you verify yourself before accepting it?

patchground/catalog/order-notifications-boundary/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/order-notifications-boundary/solution/reference.patch

@@ -0,0 +1,77 @@
+diff --git a/src/orders/app.py b/src/orders/app.py
+index 5ffe407..f814423 100644
+--- a/src/orders/app.py
++++ b/src/orders/app.py
+@@ -3,7 +3,9 @@
+ from __future__ import annotations
+ 
+ from orders.service import OrderService
++from orders.smtp_gateway import SmtpNotifier
++from orders.sqlite_store import SqliteOrderRepository
+ 
+ 
+ def build_service(db_path: str, outbox: str) -> OrderService:
+-    return OrderService(db_path, outbox)
++    return OrderService(repository=SqliteOrderRepository(db_path), notifier=SmtpNotifier(outbox))
+diff --git a/src/orders/ports.py b/src/orders/ports.py
+new file mode 100644
+index 0000000..437915e
+--- /dev/null
++++ b/src/orders/ports.py
+@@ -0,0 +1,19 @@
++"""What the order service needs from the outside world, as protocols."""
++
++from __future__ import annotations
++
++from typing import Protocol, runtime_checkable
++
++from orders.models import Order
++
++
++@runtime_checkable
++class OrderRepository(Protocol):
++    def save_confirmed(self, order: Order) -> None: ...
++
++    def get(self, order_id: str) -> Order | None: ...
++
++
++@runtime_checkable
++class Notifier(Protocol):
++    def send(self, to: str, subject: str, body: str) -> None: ...
+diff --git a/src/orders/service.py b/src/orders/service.py
+index 91267c6..d5446de 100644
+--- a/src/orders/service.py
++++ b/src/orders/service.py
+@@ -3,8 +3,7 @@
+ from __future__ import annotations
+ 
+ from orders.models import Order
+-from orders.smtp_gateway import SmtpNotifier
+-from orders.sqlite_store import SqliteOrderRepository
++from orders.ports import Notifier, OrderRepository
+ 
+ 
+ def format_confirmation(order: Order) -> tuple[str, str]:
+@@ -16,16 +15,16 @@ def format_confirmation(order: Order) -> tuple[str, str]:
+ 
+ 
+ class OrderService:
+-    def __init__(self, db_path: str, outbox: str) -> None:
+-        self._db_path = db_path
+-        self._outbox = outbox
++    def __init__(self, *, repository: OrderRepository, notifier: Notifier) -> None:
++        self._repository = repository
++        self._notifier = notifier
+ 
+     def confirm(self, order: Order) -> None:
+         if not order.lines:
+             raise ValueError("an order needs at least one line")
+-        SqliteOrderRepository(self._db_path).save_confirmed(order)
++        self._repository.save_confirmed(order)
+         subject, body = format_confirmation(order)
+-        SmtpNotifier(self._outbox).send(order.customer_email, subject, body)
++        self._notifier.send(order.customer_email, subject, body)
+ 
+     def find(self, order_id: str) -> Order | None:
+-        return SqliteOrderRepository(self._db_path).get(order_id)
++        return self._repository.get(order_id)

patchground/catalog/order-notifications-boundary/workspace/pyproject.toml

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

patchground/catalog/order-notifications-boundary/workspace/src/orders/__init__.py

@@ -0,0 +1,6 @@
+"""Order confirmation for the storefront."""
+
+from orders.models import Order, OrderLine
+from orders.service import OrderService
+
+__all__ = ["Order", "OrderLine", "OrderService"]

patchground/catalog/order-notifications-boundary/workspace/src/orders/app.py

@@ -0,0 +1,9 @@
+"""Composition root used by the CLI and the tests."""
+
+from __future__ import annotations
+
+from orders.service import OrderService
+
+
+def build_service(db_path: str, outbox: str) -> OrderService:
+    return OrderService(db_path, outbox)

patchground/catalog/order-notifications-boundary/workspace/src/orders/models.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class OrderLine:
+    sku: str
+    quantity: int
+    unit_price_cents: int
+
+    @property
+    def total_cents(self) -> int:
+        return self.quantity * self.unit_price_cents
+
+
+@dataclass(frozen=True)
+class Order:
+    order_id: str
+    customer_email: str
+    lines: tuple[OrderLine, ...] = field(default_factory=tuple)
+
+    @property
+    def total_cents(self) -> int:
+        return sum(line.total_cents for line in self.lines)

patchground/catalog/order-notifications-boundary/workspace/src/orders/service.py

@@ -0,0 +1,31 @@
+"""Confirm orders: persist them and tell the customer."""
+
+from __future__ import annotations
+
+from orders.models import Order
+from orders.smtp_gateway import SmtpNotifier
+from orders.sqlite_store import SqliteOrderRepository
+
+
+def format_confirmation(order: Order) -> tuple[str, str]:
+    """Subject and body of the confirmation message. Shared by every channel."""
+    subject = f"Order {order.order_id} confirmed"
+    lines = [f"- {line.quantity} x {line.sku} @ {line.unit_price_cents / 100:.2f}" for line in order.lines]
+    body = "\n".join(["Thanks for your order.", *lines, f"Total: {order.total_cents / 100:.2f}"])
+    return subject, body
+
+
+class OrderService:
+    def __init__(self, db_path: str, outbox: str) -> None:
+        self._db_path = db_path
+        self._outbox = outbox
+
+    def confirm(self, order: Order) -> None:
+        if not order.lines:
+            raise ValueError("an order needs at least one line")
+        SqliteOrderRepository(self._db_path).save_confirmed(order)
+        subject, body = format_confirmation(order)
+        SmtpNotifier(self._outbox).send(order.customer_email, subject, body)
+
+    def find(self, order_id: str) -> Order | None:
+        return SqliteOrderRepository(self._db_path).get(order_id)

patchground/catalog/order-notifications-boundary/workspace/src/orders/smtp_gateway.py

@@ -0,0 +1,19 @@
+"""Email delivery through the storefront's SMTP relay.
+
+The relay is not reachable from developer machines, so this gateway writes each message to an
+outbox file; production swaps in the real transport by configuration.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+class SmtpNotifier:
+    def __init__(self, outbox: str | Path) -> None:
+        self._outbox = Path(outbox)
+
+    def send(self, to: str, subject: str, body: str) -> None:
+        with self._outbox.open("a", encoding="utf-8") as stream:
+            stream.write(json.dumps({"to": to, "subject": subject, "body": body}) + "\n")