pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/process/settings.py

@@ -0,0 +1,534 @@
+"""Settings: every variable the gateway and the worker read, and the three places it comes from."""
+
+import os
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import Literal, Self
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from dotenv import dotenv_values
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+
+from pinecall.domain.errors import SettingsRefused
+from pinecall.domain.names import SANDBOX, Env
+from pinecall.postgres.pool import POOL_SIZE
+
+# Checked in each directory up to the repository root; `runtime/.env` serves a process started
+# from the checkout root. When both exist the later wins.
+ENV_FILES = (".env", "runtime/.env")
+
+# Slug-shaped: it ends up in Twilio usernames and SFU trunk names. Never empty: an empty
+# agent_name makes LiveKit dispatch to every room (livekit worker.py:219).
+A_FLEET_NAME = r"^[a-z0-9][a-z0-9-]{0,62}$"
+
+UNREADABLE_ENV = "cannot read {file}: {why}. A .env that is there is never skipped in silence"
+
+NO_STORE = (
+    "PINECALL_RECORDINGS_BUCKET is a bucket of the object store, which is named by "
+    "PINECALL_S3_ENDPOINT, PINECALL_S3_REGION, PINECALL_S3_ACCESS_KEY_ID and the "
+    "PINECALL_S3_SECRET_ACCESS_KEY credential together; missing: {missing}"
+)
+
+# Spoken by the overflow agent when every worker is full, before hanging up.
+OVERFLOW_SAYS = (
+    "En este momento todas nuestras líneas están ocupadas. Hemos tomado nota de su número "
+    "y le devolveremos la llamada en cuanto se libere una. Gracias por su paciencia."
+)
+
+
+class Settings(BaseModel):
+    """Typed, frozen process settings; `load()` builds them."""
+
+    model_config = ConfigDict(
+        frozen=True, extra="ignore", validate_by_name=True, validate_by_alias=True
+    )
+
+    # ── the media plane ──
+    livekit_url: str = Field(
+        "ws://127.0.0.1:7880",
+        alias="LIVEKIT_URL",
+        description="LiveKit, which both processes talk to. One port serves ws and http.",
+    )
+    # A world's rooms live on its own LiveKit, so a sandbox call never shares a machine with a
+    # production one; a worker is given its world's in LIVEKIT_URL.
+    livekit_sandbox_url: str | None = Field(
+        None,
+        alias="LIVEKIT_SANDBOX_URL",
+        description="The sandbox's own LiveKit, as the gateway reaches it. Unset: LIVEKIT_URL's.",
+    )
+    livekit_api_key: str | None = Field(
+        None, alias="LIVEKIT_API_KEY", description="The LiveKit API key, as its own config says."
+    )
+    # Also signs call tokens, which are LiveKit room tokens. Without the pair, no tokens.
+    livekit_api_secret: str | None = Field(
+        None, alias="LIVEKIT_API_SECRET", repr=False, description="Its secret."
+    )
+    livekit_public_url: str | None = Field(
+        None,
+        alias="LIVEKIT_PUBLIC_URL",
+        description="The LiveKit URL a browser joins when the box has no name. Unset: LIVEKIT_URL.",
+    )
+    # One name serves both worlds: a request's world is its key's or its header's, never the name
+    # it came in by (tenancy/keys.py, world_of).
+    domain: str | None = Field(
+        None,
+        alias="PINECALL_DOMAIN",
+        description="The box's name: where the public, the SDKs and a carrier reach it.",
+    )
+    # Where a carrier sends a world's calls, when that is not the box's name: in a cluster the
+    # name is Google's HTTPS load balancer, which carries no SIP, and each world's SIP node has
+    # an address of its own (infra/README.md).
+    sip_domain: str | None = Field(
+        None,
+        alias="PINECALL_SIP_DOMAIN",
+        description="The name a carrier sends production's calls to. Unset: the box's name.",
+    )
+    sandbox_sip_domain: str | None = Field(
+        None,
+        alias="PINECALL_SANDBOX_SIP_DOMAIN",
+        description="The name a carrier sends the sandbox's calls to. Unset: production's.",
+    )
+
+    # ── Postgres ──
+    database_url: str = Field(
+        "postgresql://pinecall:pinecall@127.0.0.1:5432/pinecall",
+        alias="DATABASE_URL",
+        repr=False,
+        description="Postgres 17 with pgvector and pg_textsearch: the one stateful service.",
+    )
+    # Where the gateway connects as a role that reads and writes rows and changes no table: the
+    # migrations, run as the owner, grant it that and no more each time they run.
+    db_app_role: str | None = Field(
+        None,
+        alias="PINECALL_DB_APP_ROLE",
+        description="The role `migrate up` grants rows to; unset, the owner is the app's role too.",
+    )
+    db_pool: int = Field(
+        POOL_SIZE,
+        alias="PINECALL_DB_POOL",
+        ge=3,
+        description="Connections to Postgres: two its writer holds, the rest the doors share.",
+    )
+
+    # ── the signal between gateways ──
+    # A URL may carry a password. Unset, the gateway is alone on its box and keeps it in memory.
+    redis_url: str | None = Field(
+        None,
+        alias="PINECALL_REDIS_URL",
+        repr=False,
+        description="The Redis the gateways tell each other what just happened on. Unset: one.",
+    )
+
+    # ── recordings ──
+    recordings_root: str = Field(
+        "recordings",
+        alias="PINECALL_RECORDINGS",
+        description="Where a kept recording lands, absolute or relative to the working directory.",
+    )
+    # A bucket of the object store below; never the backup's bucket, whose 35-day lifecycle rule
+    # would forget a recording its org keeps longer.
+    recordings_bucket: str | None = Field(
+        None,
+        alias="PINECALL_RECORDINGS_BUCKET",
+        description="The bucket a finished recording moves to, under its org. Unset: the disk.",
+    )
+
+    # A box's WAL spool: archive_command copied each segment there and a timer shipped it. A
+    # cluster's Postgres archives through its operator, and has no spool to read.
+    wal_spool: str | None = Field(
+        "/var/lib/pinecall/wal",
+        alias="PINECALL_WAL_SPOOL",
+        description="The box's WAL spool doctor reads the backlog of; empty in a cluster.",
+    )
+
+    # ── the object store ──
+    # Any S3-compatible endpoint: AWS, Google Cloud Storage by HMAC key, R2, B2, a MinIO.
+    s3_endpoint: str | None = Field(
+        None,
+        alias="PINECALL_S3_ENDPOINT",
+        description="The S3-compatible object store what leaves the disk goes to.",
+    )
+    s3_region: str | None = Field(
+        None,
+        alias="PINECALL_S3_REGION",
+        description="The region the store's signature names: the buckets' own, or `auto`.",
+    )
+    s3_access_key_id: str | None = Field(
+        None,
+        alias="PINECALL_S3_ACCESS_KEY_ID",
+        description="The key the box reads and writes the store with.",
+    )
+    s3_secret_access_key: str | None = Field(
+        None,
+        alias="PINECALL_S3_SECRET_ACCESS_KEY",
+        repr=False,
+        description="The key's secret: a sealed credential on a box, never a file.",
+    )
+
+    # ── the worker ──
+    # Read from the environment because livekit runs each job in a child process that inherits
+    # only the environment. The gateway also binds this URL's host and port.
+    gateway_url: str = Field(
+        "http://127.0.0.1:8080",
+        alias="PINECALL_GATEWAY_URL",
+        description="The instance's gateway: where it binds, on loopback, and what a worker asks.",
+    )
+    # A box's gateway binds PINECALL_GATEWAY_URL's loopback address, behind Caddy; a pod's binds
+    # its own network, behind the cluster's load balancer, and says so here (infra/charts).
+    gateway_listen: str | None = Field(
+        None,
+        alias="PINECALL_GATEWAY_LISTEN",
+        description="host:port a pod's gateway binds (0.0.0.0:8080); unset, the URL's loopback.",
+    )
+    trusted_proxies: str = Field(
+        "127.0.0.1",
+        alias="PINECALL_TRUSTED_PROXIES",
+        description="Addresses or networks whose X-Forwarded-For the gateway believes.",
+    )
+    metrics_from: str = Field(
+        "127.0.0.1,::1",
+        alias="PINECALL_METRICS_FROM",
+        description="Addresses or networks /metrics answers; never a forwarded request.",
+    )
+    agent: str | None = Field(
+        None, alias="PINECALL_AGENT", description="The agent a job that names none is for."
+    )
+    max_jobs: int | None = Field(
+        None,
+        alias="PINECALL_MAX_JOBS",
+        description="Calls this worker holds at once, measured on its machine. Unset: gate on CPU.",
+    )
+    worker_http_port: int = Field(
+        8082,
+        alias="PINECALL_WORKER_HTTP_PORT",
+        description="Where the worker's own health server binds, on loopback.",
+    )
+    worker_http_host: str = Field(
+        "127.0.0.1",
+        alias="PINECALL_WORKER_HTTP_HOST",
+        description="The health server's address: loopback on a box, 0.0.0.0 for a pod's probes.",
+    )
+    worker_name: str | None = Field(
+        None,
+        alias="PINECALL_WORKER_NAME",
+        description="What this worker is called in its heartbeats. Unset: the short hostname.",
+    )
+    # Per-instance LiveKit agent name, so production and sandbox on one SFU never take each
+    # other's calls. Also prefixes trunk and rule names.
+    fleet: str = Field(
+        "pinecall",
+        alias="PINECALL_FLEET",
+        pattern=A_FLEET_NAME,
+        description="The fleet this worker unit joins: the name it registers under with LiveKit.",
+    )
+    # livekit prewarms one process per CPU, wasting RAM when two instances share a machine.
+    idle_processes: int | None = Field(
+        None,
+        alias="PINECALL_IDLE_PROCESSES",
+        description="Job processes the worker keeps warm. Unset: livekit's, one per CPU.",
+    )
+    # systemd's own, set on a Type=notify unit: a release waits for the worker to say it is ready.
+    notify_socket: str | None = Field(
+        None,
+        alias="NOTIFY_SOCKET",
+        description="Where a worker tells systemd it is registered and heard. Set by systemd.",
+    )
+    overflow_says: str = Field(
+        OVERFLOW_SAYS,
+        alias="PINECALL_OVERFLOW_SAYS",
+        description="What the overflow agent says when the fleet is full, before it hangs up.",
+    )
+    # A developer's worker sets this so calls reach their own app socket.
+    app: str | None = Field(
+        None,
+        alias="PINECALL_APP",
+        description="The app socket a job's call claims. Unset, the call takes the newest holder.",
+    )
+
+    # ── the box ──
+    role: Literal["all", "hub", "worker"] = Field(
+        "all",
+        alias="PINECALL_ROLE",
+        description="What this box runs: all · hub · worker. The doctor asks after what it has.",
+    )
+    # Brute force is limited by argon2id and rate limiting, not length.
+    min_password: int = Field(
+        8,
+        alias="PINECALL_MIN_PASSWORD",
+        ge=0,
+        description="How short a member's password may be. 0 is no rule.",
+    )
+    ops_key: str | None = Field(
+        None,
+        alias="PINECALL_OPS_KEY",
+        repr=False,
+        description="The key /v1/ops/* is authenticated by. Unset, the operator API is closed.",
+    )
+    cloud: bool = Field(
+        default=False, alias="PINECALL_CLOUD", description="Pinecall's hosted gateway: billed."
+    )
+    signup: bool = Field(
+        default=False,
+        alias="PINECALL_SIGNUP",
+        description="Whether a stranger may make an org at this gateway. Off unless you say.",
+    )
+    # A number an org hooks itself proves nothing of whose it is; on, it rings nobody until the
+    # operator approves it (POST /v1/ops/numbers/{number}/approve). Off, it rings at once.
+    approve_hooked: bool = Field(
+        default=False,
+        alias="PINECALL_APPROVE_HOOKED",
+        description="Whether a number an org hooks itself waits for the operator. Off by default.",
+    )
+    billing_url: str | None = Field(
+        None,
+        alias="PINECALL_BILLING_URL",
+        description="Where this box's orgs pay, https://…; unset, the box bills nobody.",
+    )
+    # Restricts sign-up to the bot-protected site in front of it, whose X-Pinecall-Client header
+    # is then trusted as the client address.
+    signup_key: str | None = Field(
+        None,
+        alias="PINECALL_SIGNUP_KEY",
+        repr=False,
+        description="The Bearer key the sign-up doors take; unset, they take anybody.",
+    )
+    # The mobile app's two origins are always allowed. No wildcards.
+    app_origins: str = Field(
+        "",
+        alias="PINECALL_APP_ORIGINS",
+        description="Origins besides the mobile app's two that may call /v1, comma separated.",
+    )
+    # Not PINECALL_API_KEY: the CLI and the SDK read that name, and a stale export once
+    # registered agents into the wrong org.
+    worker_key: str | None = Field(
+        None,
+        alias="PINECALL_WORKER_KEY",
+        repr=False,
+        description="The org key the worker knocks its gateway with, as `keys issue` printed it.",
+    )
+    # ── the runner ──
+    runner_key: str | None = Field(
+        None,
+        alias="PINECALL_RUNNER_KEY",
+        repr=False,
+        description="The key a world's runner knocks with, as `keys runner` printed it.",
+    )
+    runner_image: str = Field(
+        "docker.io/library/node:24-slim",
+        alias="PINECALL_RUNNER_IMAGE",
+        description="The image every hosted app installs and runs in.",
+    )
+    runner_runtime_class: str = Field(
+        "gvisor",
+        alias="PINECALL_RUNNER_RUNTIME_CLASS",
+        description="The runtime class a hosted app's pod runs under: gvisor, GKE Sandbox's.",
+    )
+    runner_namespace: str = Field(
+        "pinecall-apps",
+        alias="PINECALL_RUNNER_NAMESPACE",
+        description="The namespace of the hosting cluster the runner starts every app's pod in.",
+    )
+    runner_sources_url: str = Field(
+        "http://127.0.0.1:8080",
+        alias="PINECALL_RUNNER_SOURCES_URL",
+        description="The runner as an app's pod reaches it, to fetch its release's sources.",
+    )
+    # Loopback unless told: in a pod, its chart says every address, which its Service reaches.
+    runner_listen: str = Field(
+        "127.0.0.1",
+        alias="PINECALL_RUNNER_LISTEN",
+        description="The address the runner serves the releases' sources on.",
+    )
+    runner_port: int = Field(
+        8080,
+        alias="PINECALL_RUNNER_PORT",
+        description="The port the runner serves the releases' sources on, to its world's pods.",
+    )
+    # Kept out of the database so a stolen dump does not expose tenants' secrets. To rotate: a
+    # comma-separated list, the new key first; a secret seals under the first and opens under
+    # whichever sealed it.
+    vault_key: str | None = Field(
+        None,
+        alias="PINECALL_VAULT_KEY",
+        repr=False,
+        description="The Fernet key every sealed secret is under; the gateway needs it.",
+    )
+    # The gateway's own, held by no worker and no LiveKit: a token that reads a log or asks after
+    # a caller code is signed with it, so the LiveKit pair every worker holds mints none.
+    token_key: str | None = Field(
+        None,
+        alias="PINECALL_TOKEN_KEY",
+        repr=False,
+        description="The key the gateway signs its own tokens with; the gateway needs it.",
+    )
+    smtp_url: str | None = Field(
+        None,
+        alias="PINECALL_SMTP_URL",
+        repr=False,
+        description="smtp://user:pass@host:587, or smtps://…:465: what this box posts mail with.",
+    )
+    mail_from: str | None = Field(
+        None,
+        alias="PINECALL_MAIL_FROM",
+        description='Who the box\'s letters are from: "Pinecall <no-reply@example.com>".',
+    )
+    log_level: str = Field(
+        "INFO",
+        alias="PINECALL_LOG_LEVEL",
+        description="How much both processes say: DEBUG, INFO, WARNING or ERROR.",
+    )
+    # json matches the worker's own JSON logs (livekit's JsonFormatter).
+    log_format: Literal["text", "json"] = Field(
+        "text",
+        alias="PINECALL_LOG_FORMAT",
+        description="The gateway's lines: text for a terminal, json for a journal.",
+    )
+    otlp_endpoint: str | None = Field(
+        None,
+        alias="PINECALL_OTLP_ENDPOINT",
+        description="Where the worker sends a call's traces, OTLP over HTTP. Unset: no trace.",
+    )
+    otlp_headers: str | None = Field(
+        None,
+        alias="PINECALL_OTLP_HEADERS",
+        repr=False,
+        description="Headers on every trace export, `name=value` comma-separated: a credential.",
+    )
+    otlp_pii: bool = Field(
+        default=False,
+        alias="PINECALL_OTLP_PII",
+        description="Whether a trace carries what was said and what a tool got.",
+    )
+    # Calls are dated in the caller's zone, not the box's, so "tomorrow" means the right day.
+    timezone: str = Field(
+        "UTC",
+        alias="PINECALL_TIMEZONE",
+        description="The IANA zone a call's `today` is read in (Europe/Madrid). UTC unless set.",
+    )
+    # ── memory and retrieval ──
+    # Unset budgets use the session's defaults.
+    voice_lookup_budget_ms: int | None = Field(
+        None,
+        alias="PINECALL_VOICE_LOOKUP_BUDGET_MS",
+        description="What a spoken turn waits for recall and search, in ms: silence on the line.",
+    )
+    text_lookup_budget_ms: int | None = Field(
+        None,
+        alias="PINECALL_TEXT_LOOKUP_BUDGET_MS",
+        description="What a written turn waits for recall and search, in ms.",
+    )
+    remember_budget_s: float | None = Field(
+        None,
+        alias="PINECALL_REMEMBER_BUDGET_S",
+        description="What a hang-up waits for memory to be written, in s. Past it the call seals.",
+    )
+
+    # Vendor keys keep the vendor's own variable name, so the SDK that reads ANTHROPIC_API_KEY
+    # by itself and this runtime agree; the catalog asks for them by name.
+    variables: Mapping[str, str] = Field(
+        default_factory=dict,
+        repr=False,
+        description="Every variable read, for the vendor keys the catalog names.",
+    )
+
+    @field_validator("timezone")
+    @classmethod
+    def _a_zone_that_exists(cls, zone: str) -> str:
+        try:
+            ZoneInfo(zone)
+        except (ZoneInfoNotFoundError, ValueError):
+            raise ValueError(f"{zone!r} is not an IANA time zone (Europe/Madrid, UTC)") from None
+        return zone
+
+    # Refused where the process starts, not on the first recording a call leaves.
+    @model_validator(mode="after")
+    def _a_recordings_bucket_has_its_store(self) -> Self:
+        named = {
+            "PINECALL_S3_ENDPOINT": self.s3_endpoint,
+            "PINECALL_S3_REGION": self.s3_region,
+            "PINECALL_S3_ACCESS_KEY_ID": self.s3_access_key_id,
+            "PINECALL_S3_SECRET_ACCESS_KEY": self.s3_secret_access_key,
+        }
+        missing = [name for name, value in named.items() if value is None]
+        if self.recordings_bucket is not None and missing:
+            raise ValueError(NO_STORE.format(missing=", ".join(missing)))
+        return self
+
+    def sip_name_of(self, world: Env) -> str | None:
+        """The name a carrier sends that world's calls to: its SIP name, else the box's name."""
+        named = self.sandbox_sip_domain if world == SANDBOX else self.sip_domain
+        return named or self.sip_domain or self.domain
+
+    @property
+    def address(self) -> str | None:
+        """The https address of the box's name, or None where it has none."""
+        return None if self.domain is None else f"https://{self.domain}"
+
+    def livekit_url_of(self, world: Env) -> str:
+        """The LiveKit that world's rooms live on, as this process reaches it."""
+        if world == SANDBOX and self.livekit_sandbox_url:
+            return self.livekit_sandbox_url
+        return self.livekit_url
+
+    # The load balancer sends `/sandbox/rtc…` to the sandbox's own LiveKit, the prefix stripped.
+    def browser_livekit_url(self, world: Env) -> str:
+        """The LiveKit URL a browser is told to join for a call of the world."""
+        own = self.livekit_sandbox_url if world == SANDBOX else None
+        if self.domain:
+            return f"wss://{self.domain}/sandbox" if own else f"wss://{self.domain}"
+        return own or self.livekit_public_url or self.livekit_url
+
+
+def load() -> Settings:
+    """Build Settings from the systemd credentials, the .env files found and the environment."""
+    read: dict[str, str] = {}
+    credentials = os.environ.get("CREDENTIALS_DIRECTORY")
+    if credentials:
+        read.update(_credentials_in(Path(credentials)))
+    for file in env_files():
+        read.update(_env_file(file))
+    read.update(os.environ)
+    # A bare `NAME=` means unset, so a copied example does not hand a vendor an empty value.
+    variables = {name: value for name, value in read.items() if value != ""}
+    try:
+        return Settings.model_validate({**variables, "variables": variables})
+    except ValidationError as refused:
+        raise SettingsRefused(str(refused)) from refused
+
+
+def env_files() -> list[Path]:
+    """Return the .env files of the first directory up to the repository root that has any."""
+    for folder in _up_to_the_repository_root(Path.cwd()):
+        found = [folder / name for name in ENV_FILES if (folder / name).is_file()]
+        if found:
+            return found
+    return []
+
+
+# Bounded at the repository root: a stray .env above the project would silently load wrong keys.
+def _up_to_the_repository_root(start: Path) -> Iterator[Path]:
+    folder = start.resolve()
+    for candidate in (folder, *folder.parents):
+        yield candidate
+        if (candidate / ".git").exists():
+            return
+
+
+# On a box, secrets arrive as systemd credentials: one file per variable name.
+def _credentials_in(directory: Path) -> dict[str, str]:
+    return {
+        file.name: file.read_text(encoding="utf-8").strip()
+        for file in sorted(directory.iterdir())
+        if file.is_file()
+    }
+
+
+# An unreadable .env fails loudly: it may hold the key that selects the right database.
+def _env_file(path: Path) -> dict[str, str]:
+    try:
+        values = dotenv_values(path, encoding="utf-8")
+    except OSError as failed:
+        raise SettingsRefused(
+            UNREADABLE_ENV.format(file=path, why=failed.strerror or failed)
+        ) from failed
+    return {name: value for name, value in values.items() if value is not None}

pinecall/process/shared.py

@@ -0,0 +1,158 @@
+"""State each gateway holds a share of, told to the others on the signal and merged by each."""
+
+import asyncio
+import contextlib
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from uuid import uuid4
+
+from pydantic import BaseModel, TypeAdapter
+
+from pinecall.domain.errors import NotAvailable
+from pinecall.postgres.pool import box_task
+from pinecall.process.signal import Signal
+
+# Each process says its whole share this often, and forgets another's share once it has been
+# silent this long: a gateway that died takes its share with it within half a minute.
+TOLD_EVERY_S = 10.0
+SILENT_AT_MOST_S = 30.0
+
+# A share said changes nothing past the next beat: a lost message is repaired by it.
+RETRY_S = 1.0
+
+# A key set to nobody is kept this long, so an older setting said by another process does not
+# come back while that process still says it.
+FORGOTTEN_AFTER_S = 60.0
+
+
+class Said(BaseModel):
+    """One message on a share's channel: which process said it, and its share whole."""
+
+    sender: str
+    share: object
+
+
+@dataclass(frozen=True)
+class Assigned:
+    """A key of a world as one process last set it: to a holder, or to nobody, and when."""
+
+    env: str
+    key: str
+    holder: str | None
+    at: float
+
+
+@dataclass
+class Heard[T]:
+    """Another process's share, and when it last said it."""
+
+    share: T
+    at: float
+
+
+# Lossy by design, as the signal is: every share is said whole, again and again, so a message lost
+# or a Redis that restarted costs at most one beat. What a share holds must be small (sockets,
+# lines, phones): it travels whole every TOLD_EVERY_S.
+class Shared[T]:
+    """One share of this process, the others' as last heard, and a callback when either moves."""
+
+    def __init__(
+        self,
+        signal: Signal,
+        channel: str,
+        adapter: TypeAdapter[T],
+        empty: T,
+        changed: Callable[[], None],
+    ) -> None:
+        """Nothing heard yet; `changed` is called whenever the merged view must be rebuilt."""
+        self.signal = signal
+        # How often the share is said whole: TOLD_EVERY_S unless its owner says sooner.
+        self.every_s = TOLD_EVERY_S
+        # Set by an owner whose share changes too often to put: read as it is said.
+        self.gathered: Callable[[], T] | None = None
+        self.channel = channel
+        self.id = uuid4().hex
+        self.mine = empty
+        self.theirs: dict[str, Heard[T]] = {}
+        self._adapter = adapter
+        self._changed = changed
+        self._tasks: list[asyncio.Task[None]] = []
+
+    def put(self, share: T) -> None:
+        """This process's share changed: keep it, and say it at once."""
+        self.mine = share
+        self._say()
+
+    async def start(self) -> None:
+        """Listen to the others and say this share every beat."""
+        self._tasks = [box_task(self._listened()), box_task(self._beating())]
+
+    async def close(self) -> None:
+        """Stop listening and saying."""
+        for task in self._tasks:
+            task.cancel()
+        await asyncio.gather(*self._tasks, return_exceptions=True)
+
+    def _say(self) -> None:
+        mine = self.mine if self.gathered is None else self.gathered()
+        message = Said(sender=self.id, share=self._adapter.dump_python(mine, mode="json"))
+        self.signal.publish(self.channel, message.model_dump_json().encode())
+
+    async def _beating(self) -> None:
+        while True:
+            self._say()
+            await asyncio.sleep(self.every_s)
+            now = time.monotonic()
+            silent = [gw for gw, heard in self.theirs.items() if now - heard.at > SILENT_AT_MOST_S]
+            for gateway in silent:
+                del self.theirs[gateway]
+            if silent:
+                self._changed()
+
+    async def _listened(self) -> None:
+        while True:
+            try:
+                listening = await self.signal.subscribe(self.channel)
+            except NotAvailable:
+                await asyncio.sleep(RETRY_S)
+                continue
+            # Said again once subscribed: a process that just started is told everyone's share.
+            self._say()
+            try:
+                async for data in listening:
+                    self._heard(data)
+            finally:
+                listening.close()
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(self.signal.connected(), RETRY_S)
+
+    def _heard(self, data: bytes) -> None:
+        message = Said.model_validate_json(data)
+        if message.sender == self.id:
+            return
+        new = message.sender not in self.theirs
+        share = self._adapter.validate_python(message.share)
+        self.theirs[message.sender] = Heard(share, time.monotonic())
+        self._changed()
+        if new:
+            self._say()
+
+
+# The newest setting of each key stands, whichever process said it. A setting of ours another
+# overruled is dropped, and one to nobody is kept only a while: what is said every beat stays the
+# size of what is set.
+def newest(
+    mine: dict[tuple[str, str], Assigned], theirs: Iterable[Assigned]
+) -> dict[tuple[str, str], str]:
+    """Each key's holder by its newest setting, ours and theirs; ours pruned of what is spent."""
+    latest = dict(mine)
+    for assigned in theirs:
+        key = (assigned.env, assigned.key)
+        if key not in latest or latest[key].at < assigned.at:
+            latest[key] = assigned
+    now = time.time()
+    for key, kept in list(mine.items()):
+        if latest[key] is not kept or (kept.holder is None and now - kept.at > FORGOTTEN_AFTER_S):
+            del mine[key]
+    return {key: setting.holder for key, setting in latest.items() if setting.holder is not None}