pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/tenancy/dial_policy.py

@@ -0,0 +1,405 @@
+"""What an org may dial, when and how often: shape, strangers, the callee's hours, the pace."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Annotated
+from zoneinfo import ZoneInfo
+
+import phonenumbers
+from phonenumbers import timezone
+from pydantic import BaseModel, ConfigDict, Field
+
+from pinecall.domain.country_codes import CALLING_CODES, NEVER_DIALLED, SHORTEST_NATIONAL
+from pinecall.domain.errors import DeclarationRefused, NotAllowed, QuotaExhausted
+from pinecall.domain.names import parse_e164
+from pinecall.domain.scope import Scope
+from pinecall.log.inbox import ever_reached
+from pinecall.postgres.pool import Pool
+from pinecall.tenancy import consents, policy
+from pinecall.tenancy.consents import Given
+from pinecall.wire.rest.numbers import Consent
+
+NOT_A_COUNTRY = "{number} starts with no country calling code E.164 assigns"
+
+
+A_BILL = "{number} is +{code}, a satellite or global-service range this box never dials"
+
+
+TOO_SHORT = "{number} is shorter than a number anybody calls from: {digits} digits after +{code}"
+
+
+# A call-back box, not a call centre: an operator raises them per org.
+DIALS_A_MINUTE = 6
+
+
+DIALS_A_DAY = 200
+
+
+LONGEST_CALL_S = 600
+
+
+# The guard that refused, written in the ledger and said in the sentence.
+SHAPE = "shape"
+
+
+STRANGER = "stranger"
+
+
+TOO_FAST = "too_fast"
+
+
+TOO_MANY = "too_many"
+
+
+QUIET_HOURS = "quiet_hours"
+
+
+TOO_OFTEN = "too_often"
+
+
+DO_NOT_CALL = "do_not_call"
+
+
+NO_CONSENT = "no_consent"
+
+
+# The Telemarketing Sales Rule (16 CFR 310.4(c)): not before 8 a.m. or after 9 p.m. at the called
+# person's location. It binds a call to the US; Canada's rules sit inside the same hours.
+NORTH_AMERICA = "+1"
+
+
+US_HOURS = (8, 21)
+
+
+# Florida's "mini-TCPA" caps three calls in 24 hours to one person on one subject: the default for
+# a +1 number, which the org may change. Elsewhere nothing, unless the org sets one.
+US_PER_NUMBER_DAY = 3
+
+
+NO_ZONE = "Etc/Unknown"
+
+
+# How many of a number's zones a refusal names before it says "…".
+ZONES_SAID = 3
+
+
+OUT_OF_HOURS = (
+    "{number} is outside the hours it may be rung ({window}) in {zones} ({guard}); "
+    "the sandbox and your own phone are not held to them"
+)
+
+
+UNPLACED = "{number} has no zone this box can place it in, so its hours cannot be kept ({guard})"
+
+
+A_NUMBERS_DAY = "{number} was rung {used} times in the last day, of {limit} ({guard})"
+
+
+ON_THE_LIST = (
+    "{number} asked not to be called: it is on this org's do-not-call list ({guard}); only a "
+    "consent recorded at POST /v1/org/consents lifts it, never one sent with a dial"
+)
+
+
+NO_CONSENT_ON_FILE = (
+    "{number} has no consent on file ({guard}): an AI-voice call needs the person's prior express "
+    "consent. Send it as `consent` with the dial, or record it at POST /v1/org/consents"
+)
+
+
+NOT_ONE_OF_OURS = (
+    "{number} never called or wrote to this org in the {env}: a call back goes back to somebody "
+    "({guard}); an operator lifts it with dial_anywhere"
+)
+
+
+A_BURST = "the org dialled {used} numbers in the last minute of its {limit} ({guard})"
+
+
+A_DAYS_WORTH = "the org dialled {used} numbers today of its {limit} ({guard})"
+
+
+POLICY = (
+    "SELECT dial_anywhere, per_minute, per_day, max_duration_s FROM dial_policy WHERE org = %(org)s"
+)
+
+
+PUT_POLICY = """
+INSERT INTO dial_policy (org, dial_anywhere, per_minute, per_day, max_duration_s)
+VALUES (%(org)s, %(dial_anywhere)s, %(per_minute)s, %(per_day)s, %(max_duration_s)s)
+ON CONFLICT (org) DO UPDATE SET dial_anywhere = excluded.dial_anywhere,
+    per_minute = excluded.per_minute, per_day = excluded.per_day,
+    max_duration_s = excluded.max_duration_s, set_at = now()
+"""
+
+
+# Two dials of one org cannot both take the last slot: the lock holds until the row is written.
+LOCKED = "SELECT pg_advisory_xact_lock(hashtext('dials:' || %(org)s))"
+
+
+# A number's own count is of the calls placed to it, not the refusals: a refused dial rang nobody.
+PACED = """
+WITH counted AS (
+    SELECT count(*) FILTER (WHERE at > now() - interval '1 minute') AS minute,
+           count(*) AS day,
+           count(*) FILTER (WHERE dialled = %(dialled)s AND refused IS NULL) AS number_day
+    FROM dials WHERE org = %(org)s AND at > now() - interval '1 day'
+), judged AS (
+    SELECT minute, day, number_day,
+           CASE WHEN minute >= %(per_minute)s THEN 'too_fast'
+                WHEN day >= %(per_day)s THEN 'too_many'
+                WHEN %(per_number_day)s::int IS NOT NULL AND number_day >= %(per_number_day)s::int
+                    THEN 'too_often' END AS refused
+    FROM counted
+)
+INSERT INTO dials (org, env, agent, call, dialled, shown, asked_by, refused)
+SELECT %(org)s, %(env)s, %(agent)s, CASE WHEN judged.refused IS NULL THEN %(call)s END,
+       %(dialled)s, %(shown)s, %(asked_by)s, judged.refused
+FROM judged
+RETURNING refused, (SELECT minute FROM judged) AS minute, (SELECT day FROM judged) AS day,
+          (SELECT number_day FROM judged) AS number_day
+"""
+
+
+REFUSED = """
+INSERT INTO dials (org, env, agent, dialled, shown, asked_by, refused)
+VALUES (%(org)s, %(env)s, %(agent)s, %(dialled)s, %(shown)s, %(asked_by)s, %(refused)s)
+"""
+
+
+# The first leg was judged when it was placed: its ledger row names the call.
+PLACED = """
+SELECT 1 FROM dials WHERE org = %(org)s AND call = %(call)s AND dialled = %(dialled)s
+  AND refused IS NULL
+"""
+
+
+class Guards(BaseModel):
+    """The org's dial guards: what it may dial and how often."""
+
+    model_config = ConfigDict(frozen=True)
+
+    dial_anywhere: bool = False
+    per_minute: Annotated[int, Field(ge=0)] = DIALS_A_MINUTE
+    per_day: Annotated[int, Field(ge=0)] = DIALS_A_DAY
+    max_duration_s: Annotated[int, Field(ge=0)] = LONGEST_CALL_S
+
+
+@dataclass(frozen=True)
+class Dial:
+    """One dial asked for: whose, to whom, shown as what, by whom, as which call, and when."""
+
+    scope: Scope
+    agent: str
+    to: str
+    shown: str | None
+    asked_by: str
+    call: str
+    at: datetime
+    # The number is a phone the person who asked verified as their own: testing, not calling out.
+    own_phone: bool = False
+    # The consent the call runs on, as the dial carried it; written down before anything rings.
+    consent: Consent | None = None
+
+
+@dataclass(frozen=True)
+class Rules:
+    """What the called number's destination and the org's policy hold a dial to."""
+
+    hours: tuple[int, int] | None
+    per_number_day: int | None
+    # Held to the do-not-call list at all: not in the sandbox, not the asker's own phone.
+    listed: bool = False
+    consent_required: bool = False
+
+
+def destination_of(number: str) -> str:
+    """The number a dial may reach, or DeclarationRefused saying why not."""
+    e164 = parse_e164(number)
+    digits = e164.removeprefix("+")
+    code = next((digits[:length] for length in (3, 2, 1) if digits[:length] in CALLING_CODES), None)
+    if code is None:
+        raise DeclarationRefused(NOT_A_COUNTRY.format(number=e164))
+    if code in NEVER_DIALLED:
+        raise DeclarationRefused(A_BILL.format(number=e164, code=code))
+    national = digits[len(code) :]
+    if len(national) < SHORTEST_NATIONAL:
+        raise DeclarationRefused(TOO_SHORT.format(number=e164, digits=len(national), code=code))
+    return e164
+
+
+async def guards_of(pool: Pool, org: str) -> Guards:
+    """The org's guards; a column nobody set is the default."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(POLICY, {"org": org})).fetchone()
+    if row is None:
+        return Guards()
+    return Guards.model_validate({name: value for name, value in row.items() if value is not None})
+
+
+async def put_guards(pool: Pool, org: str, guards: Guards) -> None:
+    """Replace the org's guards whole."""
+    async with pool.connection() as connection:
+        await connection.execute(PUT_POLICY, {"org": org, **guards.model_dump()})
+
+
+async def guard_dial(pool: Pool, dial: Dial) -> Guards:
+    """Every guard on a call placed cold: shape, a stranger, hours, the pace; one ledger row."""
+    destination = await _shaped(pool, dial)
+    guards = await guards_of(pool, dial.scope.org)
+    reached = guards.dial_anywhere or await ever_reached(
+        pool, dial.scope.org, dial.scope.env, destination
+    )
+    if not reached:
+        await _refused(pool, dial, STRANGER)
+        raise NotAllowed(
+            NOT_ONE_OF_OURS.format(number=destination, env=dial.scope.env, guard=STRANGER)
+        )
+    rules = await _rules_for(pool, dial, destination)
+    await _consented(pool, dial, destination, rules)
+    if rules.hours is not None:
+        await _in_hours(pool, dial, destination, rules.hours)
+    await _paced(pool, dial, guards, rules.per_number_day)
+    return guards
+
+
+def zones_of(number: str) -> tuple[str, ...]:
+    """Every time zone the number could be in; empty when none is known."""
+    zones = timezone.time_zones_for_number(phonenumbers.parse(number))
+    return tuple(zone for zone in zones if zone != NO_ZONE)
+
+
+def within(zones: tuple[str, ...], at: datetime, hours: tuple[int, int]) -> bool:
+    """Whether it is inside the hours in every zone: a number in two zones is held to both."""
+    start, end = hours
+    return all(start <= at.astimezone(ZoneInfo(zone)).hour < end for zone in zones)
+
+
+# A transfer target need not have called: the stranger fence stays off, the pace caps a loop.
+async def guard_second_leg(pool: Pool, dial: Dial) -> None:
+    """The shape and the pace on a leg dialled into a live call; the call's own first leg passes."""
+    async with pool.connection() as connection:
+        placed = await (
+            await connection.execute(
+                PLACED, {"org": dial.scope.org, "call": dial.call, "dialled": dial.to}
+            )
+        ).fetchone()
+    if placed is not None:
+        return
+    await _shaped(pool, dial)
+    await _paced(pool, dial, await guards_of(pool, dial.scope.org), None)
+
+
+async def _shaped(pool: Pool, dial: Dial) -> str:
+    try:
+        return destination_of(dial.to)
+    except DeclarationRefused as malformed:
+        await _refused(pool, dial, SHAPE)
+        raise DeclarationRefused(f"{malformed} ({SHAPE})") from None
+
+
+async def _refused(pool: Pool, dial: Dial, guard: str) -> None:
+    async with pool.connection() as connection:
+        await connection.execute(REFUSED, {**_ledger(dial), "refused": guard})
+
+
+# The rules bind a call out to a person. The sandbox is where an org tries its agent, and a
+# person's own verified phone is them testing: neither is held to a caller's hours or count.
+async def _rules_for(pool: Pool, dial: Dial, destination: str) -> Rules:
+    """The list, consent, hours and daily count a dial is held to, by destination and policy."""
+    if dial.scope.env == "sandbox" or dial.own_phone:
+        return Rules(hours=None, per_number_day=None)
+    kept = (await policy.policy_of(pool, dial.scope.org)).policy
+    window = (
+        None if kept.calling_hours is None else (kept.calling_hours.from_, kept.calling_hours.until)
+    )
+    if destination.startswith(NORTH_AMERICA):
+        floor, top = US_HOURS
+        start, end = window if window is not None else US_HOURS
+        return Rules(
+            hours=(max(floor, start), min(top, end)),
+            per_number_day=kept.per_number_day or US_PER_NUMBER_DAY,
+            listed=True,
+            consent_required=True,
+        )
+    return Rules(
+        hours=window,
+        per_number_day=kept.per_number_day,
+        listed=True,
+        consent_required=kept.consent_everywhere,
+    )
+
+
+# An opt-out outranks the consent a dial carries: an app may not lift the list by sending one. A
+# dial the list does not bind (the sandbox, a developer's own phone) rings past it, and writes no
+# consent over it either.
+async def _consented(pool: Pool, dial: Dial, destination: str, rules: Rules) -> None:
+    current = await consents.standing_of(pool, dial.scope, destination)
+    if current == "opted_out" and not rules.listed:
+        return
+    if current == "opted_out":
+        await _refused(pool, dial, DO_NOT_CALL)
+        raise NotAllowed(ON_THE_LIST.format(number=destination, guard=DO_NOT_CALL))
+    if dial.consent is not None:
+        given = Given(
+            kind=dial.consent.kind,
+            source=dial.consent.source,
+            given_by=dial.asked_by,
+            text=dial.consent.text,
+            evidence=dial.consent.evidence,
+            call=dial.call,
+        )
+        await consents.give(pool, dial.scope, destination, given)
+        return
+    if rules.consent_required and current != "consented":
+        await _refused(pool, dial, NO_CONSENT)
+        raise NotAllowed(NO_CONSENT_ON_FILE.format(number=destination, guard=NO_CONSENT))
+
+
+async def _in_hours(pool: Pool, dial: Dial, destination: str, hours: tuple[int, int]) -> None:
+    zones = zones_of(destination)
+    if not zones:
+        await _refused(pool, dial, QUIET_HOURS)
+        raise NotAllowed(UNPLACED.format(number=destination, guard=QUIET_HOURS))
+    if not within(zones, dial.at, hours):
+        await _refused(pool, dial, QUIET_HOURS)
+        window = f"{hours[0]}:00 to {hours[1]}:00"
+        named = ", ".join(zones[:ZONES_SAID]) + ("…" if len(zones) > ZONES_SAID else "")
+        raise NotAllowed(
+            OUT_OF_HOURS.format(number=destination, window=window, zones=named, guard=QUIET_HOURS)
+        )
+
+
+async def _paced(pool: Pool, dial: Dial, guards: Guards, per_number_day: int | None) -> None:
+    params = {
+        **_ledger(dial),
+        "call": dial.call,
+        "per_minute": guards.per_minute,
+        "per_day": guards.per_day,
+        "per_number_day": per_number_day,
+    }
+    async with pool.connection() as connection, connection.transaction():
+        await connection.execute(LOCKED, {"org": dial.scope.org})
+        row = await (await connection.execute(PACED, params)).fetchone()
+    if row is None or row["refused"] is None:
+        return
+    if row["refused"] == TOO_FAST:
+        sentence = A_BURST.format(used=row["minute"], limit=guards.per_minute, guard=TOO_FAST)
+    elif row["refused"] == TOO_OFTEN:
+        sentence = A_NUMBERS_DAY.format(
+            number=dial.to, used=row["number_day"], limit=per_number_day, guard=TOO_OFTEN
+        )
+    else:
+        sentence = A_DAYS_WORTH.format(used=row["day"], limit=guards.per_day, guard=TOO_MANY)
+    raise QuotaExhausted(sentence)
+
+
+def _ledger(dial: Dial) -> dict[str, str | None]:
+    return {
+        "org": dial.scope.org,
+        "env": dial.scope.env,
+        "agent": dial.agent,
+        "dialled": dial.to.strip(),
+        "shown": dial.shown,
+        "asked_by": dial.asked_by,
+    }

pinecall/tenancy/disclosure.py

@@ -0,0 +1,41 @@
+"""What a spoken call says before its greeting: the AI disclosure and the recording notice."""
+
+from pinecall.wire.rest.accounts import OrgPolicy
+
+# The platform's sentences, by the first part of the agent's language; English for any other.
+CALLING_FOR = {
+    "en": "This is an automated assistant calling on behalf of {org}.",
+    "es": "Le habla un asistente automático en nombre de {org}.",
+    "pt": "Aqui fala um assistente automático em nome de {org}.",
+    "fr": "Ici un assistant automatique qui appelle au nom de {org}.",
+    "de": "Hier spricht ein automatischer Assistent im Auftrag von {org}.",
+    "it": "Sono un assistente automatico che chiama per conto di {org}.",
+}
+
+MAY_BE_RECORDED = {
+    "en": "This call may be recorded.",
+    "es": "Esta llamada puede ser grabada.",
+    "pt": "Esta chamada pode ser gravada.",
+    "fr": "Cet appel peut être enregistré.",
+    "de": "Dieser Anruf kann aufgezeichnet werden.",
+    "it": "Questa chiamata può essere registrata.",
+}
+
+FALLBACK = "en"
+
+
+def disclosure_of(policy: OrgPolicy, org: str, language: str | None) -> str | None:
+    """An outbound call's first sentence: the org's own, else the platform's, or None."""
+    if policy.disclosure is not None:
+        return policy.disclosure.strip() or None
+    return CALLING_FOR[_spoken(language)].format(org=org)
+
+
+def notice_of(policy: OrgPolicy, language: str | None) -> str | None:
+    """The sentence a recorded call says, or None when the org turned the notice off."""
+    return MAY_BE_RECORDED[_spoken(language)] if policy.recording_notice else None
+
+
+def _spoken(language: str | None) -> str:
+    first = (language or FALLBACK).replace("_", "-").split("-")[0].lower()
+    return first if first in CALLING_FOR else FALLBACK

pinecall/tenancy/erasure.py

@@ -0,0 +1,204 @@
+"""An erasure: a call's, a contact's or an org's rows and recordings gone, and its trail row."""
+
+from dataclasses import asdict, dataclass
+
+from psycopg import AsyncConnection
+from psycopg.rows import DictRow
+
+from pinecall.domain.errors import Conflict, StoreUnreachable
+from pinecall.domain.names import Env
+from pinecall.domain.scope import Scope
+from pinecall.postgres.pool import Pool, unbounded
+from pinecall.process.recordings import Recordings
+from pinecall.wire.rest.calls import Erasure, ErasureSubject
+
+# The trigger on call_log lets a DELETE through in this transaction alone (0011_erasure.sql). An
+# erasure is unbounded: an org's logs are long to delete, and its recordings go inside the
+# transaction.
+ERASING = "SET LOCAL pinecall.erasing = 'on'"
+
+CALLS_OF_CONTACT = """
+SELECT head.call, head.sealed
+FROM call_log_head head JOIN call_facts facts ON facts.call = head.call
+WHERE head.org = %(org)s AND head.env = %(env)s AND facts.contact = %(contact)s
+"""
+
+# Every log of the org: its calls, and its agents' own logs ("@<agent>"), which carry no call.
+LOGS_OF_ORG = "SELECT log, call, agent FROM call_log_head WHERE org = %(org)s"
+
+# What a call left besides its entries: the private values sealed beside them, its head, facts,
+# tokens, the memories it taught, its recording's key, the verdicts its day's drift counted (the
+# day's sums keep its numbers, which name nobody), the case of the org's dataset made of it
+# (evals/dataset.py), the labels people gave its judges (evals/calibration.py) and what it was
+# when it opened (log/openings.py). A phone call's numbers, times and end stay in call_records,
+# and the dials ledger stays: they name numbers and times, never what was said, and a traceback
+# asks for them (0016_call_records.sql). Every statement of the WITH reads the rows as they were
+# before it, so the record reads the facts.
+ERASE_LOGS = """
+WITH recorded AS (
+    INSERT INTO call_records (call, org, env, direction, from_number, to_number, started_at,
+                              ended_at, end_reason)
+    SELECT facts.call, head.org, head.env, facts.direction, facts.from_number, facts.to_number,
+           head.started_at, facts.ended_at, facts.end_reason
+    FROM call_facts facts JOIN call_log_head head ON head.call = facts.call
+    WHERE facts.call = ANY(%(calls)s) AND facts.channel = 'phone'
+    ON CONFLICT (call) DO NOTHING
+),
+     private AS (DELETE FROM call_private WHERE log = ANY(%(logs)s)),
+     keys AS (DELETE FROM recording_keys WHERE call = ANY(%(calls)s)),
+     heads AS (DELETE FROM call_log_head WHERE log = ANY(%(logs)s) RETURNING 1),
+     facts AS (DELETE FROM call_facts WHERE call = ANY(%(calls)s) RETURNING 1),
+     spent AS (DELETE FROM tokens WHERE call = ANY(%(calls)s) RETURNING 1),
+     taught AS (DELETE FROM contact_memories WHERE source_call = ANY(%(calls)s) RETURNING 1),
+     drifted AS (DELETE FROM drift_calls WHERE call = ANY(%(calls)s)),
+     promoted AS (DELETE FROM eval_cases WHERE source_call = ANY(%(calls)s)),
+     labels AS (DELETE FROM judge_labels WHERE call = ANY(%(calls)s)),
+     openings AS (DELETE FROM call_openings WHERE call = ANY(%(calls)s))
+SELECT (SELECT count(*) FROM taught) AS memories
+"""
+
+# Before ERASE_LOGS takes the heads: call_log's trigger reads each summary's org off its head, to
+# take its usage out of the org's totals (0023_usage_totals.sql).
+ERASE_ENTRIES = "DELETE FROM call_log WHERE log = ANY(%(logs)s)"
+
+# A contact's memories no erased call taught (written by hand, or by a call erased before), and
+# what each reader had read of their thread.
+ERASE_CONTACT = """
+WITH kept AS (
+    DELETE FROM contact_memories WHERE org = %(org)s AND env = %(env)s AND contact = %(contact)s
+    RETURNING 1
+), reads AS (
+    DELETE FROM thread_reads WHERE org = %(org)s AND env = %(env)s AND contact = %(contact)s
+)
+SELECT count(*) AS memories FROM kept
+"""
+
+# What has no foreign key to the org: its eval runs (by the org they carry, or by its agents for a
+# run written before runs carried one) and hold melodies, what each reader read of a thread, and
+# its keys, revoked ones included. Then the org, and the quotas, carriers, settings and memories
+# cascade.
+ERASE_ORG = """
+WITH runs AS (
+    DELETE FROM eval_runs
+    WHERE org = %(org)s OR (org IS NULL AND agent = ANY(%(agents)s))
+),
+     melodies AS (DELETE FROM hold_audio WHERE org = %(org)s),
+     reads AS (DELETE FROM thread_reads WHERE org = %(org)s),
+     keys AS (DELETE FROM api_keys WHERE org = %(org)s)
+DELETE FROM orgs WHERE id = %(org)s
+"""
+
+TRAIL = """
+INSERT INTO erasures (org, env, what, subject, asked_by, calls, entries, memories, recordings)
+VALUES (%(org)s, %(env)s, %(what)s, %(subject)s, %(asked_by)s, %(calls)s, %(entries)s,
+        %(memories)s, %(recordings)s)
+RETURNING id, env, what, subject, asked_by, calls, entries, memories, recordings, at
+"""
+
+TRAIL_OF_ORG = """
+SELECT id, env, what, subject, asked_by, calls, entries, memories, recordings, at
+FROM erasures WHERE org = %(org)s ORDER BY at DESC, id DESC LIMIT %(limit)s
+"""
+
+NO_TRAIL = "the erasure of {subject} was not written down, so it was undone"
+
+STILL_ON_A_CALL = "{contact} is on call {call} right now: erase them once it has ended"
+
+
+@dataclass(frozen=True)
+class Erased:
+    """An erasure done: its trail row, and the calls it took, for a process that holds them."""
+
+    trail: Erasure
+    calls: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class _Taking:
+    """An erasure on its way: whose, what, who asked, and the rows gone so far."""
+
+    org: str
+    env: Env | None
+    what: ErasureSubject
+    subject: str
+    asked_by: str
+    calls: list[str]
+    entries: int
+    memories: int
+
+
+async def call(
+    pool: Pool, recordings: Recordings, scope: Scope, call_id: str, *, by: str
+) -> Erased:
+    """Erase one call: its log, facts, tokens, the memories it taught, and its recording."""
+    async with unbounded(pool) as connection:
+        await connection.execute(ERASING)
+        entries, memories = await _logs(connection, [call_id], [call_id])
+        taking = _Taking(scope.org, scope.env, "call", call_id, by, [call_id], entries, memories)
+        return await _written(connection, recordings, taking)
+
+
+async def contact(
+    pool: Pool, recordings: Recordings, scope: Scope, contact_id: str, *, by: str
+) -> Erased:
+    """Erase a contact in the world: every call they were on and every fact kept of them."""
+    params = {"org": scope.org, "env": scope.env, "contact": contact_id}
+    async with unbounded(pool) as connection:
+        await connection.execute(ERASING)
+        rows = await (await connection.execute(CALLS_OF_CONTACT, params)).fetchall()
+        live = next((str(row["call"]) for row in rows if not row["sealed"]), None)
+        if live is not None:
+            raise Conflict(STILL_ON_A_CALL.format(contact=contact_id, call=live))
+        calls = [str(row["call"]) for row in rows]
+        entries, taught = await _logs(connection, calls, calls)
+        kept = await (await connection.execute(ERASE_CONTACT, params)).fetchone()
+        memories = taught + (0 if kept is None else int(kept["memories"]))
+        taking = _Taking(scope.org, scope.env, "contact", contact_id, by, calls, entries, memories)
+        return await _written(connection, recordings, taking)
+
+
+async def org(pool: Pool, recordings: Recordings, org_id: str, *, by: str) -> Erased:
+    """Erase an org whole: every log it owns, every recording, then the org and what cascades."""
+    async with unbounded(pool) as connection:
+        await connection.execute(ERASING)
+        rows = await (await connection.execute(LOGS_OF_ORG, {"org": org_id})).fetchall()
+        logs = [str(row["log"]) for row in rows]
+        calls = [str(row["call"]) for row in rows if row["call"] is not None]
+        agents = sorted({str(row["agent"]) for row in rows if row["agent"] is not None})
+        entries, memories = await _logs(connection, logs, calls)
+        await connection.execute(ERASE_ORG, {"org": org_id, "agents": agents})
+        taking = _Taking(org_id, None, "org", org_id, by, calls, entries, memories)
+        return await _written(connection, recordings, taking)
+
+
+async def trail(pool: Pool, org_id: str, *, limit: int = 100) -> list[Erasure]:
+    """The org's erasures, newest first."""
+    params = {"org": org_id, "limit": limit}
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(TRAIL_OF_ORG, params)).fetchall()
+    return [_trail_row(row) for row in rows]
+
+
+async def _logs(
+    connection: AsyncConnection[DictRow], logs: list[str], calls: list[str]
+) -> tuple[int, int]:
+    entries = (await connection.execute(ERASE_ENTRIES, {"logs": logs})).rowcount
+    row = await (await connection.execute(ERASE_LOGS, {"logs": logs, "calls": calls})).fetchone()
+    return entries, 0 if row is None else int(row["memories"])
+
+
+# The recordings go inside the transaction, before its trail is written: a disk or a bucket
+# that refuses leaves the rows in place and the erasure failed, not a trail that lies.
+async def _written(
+    connection: AsyncConnection[DictRow], recordings: Recordings, taking: _Taking
+) -> Erased:
+    removed = await recordings.erase(taking.org, taking.calls)
+    params = {**asdict(taking), "calls": len(taking.calls), "recordings": removed}
+    row = await (await connection.execute(TRAIL, params)).fetchone()
+    if row is None:
+        raise StoreUnreachable(NO_TRAIL.format(subject=taking.subject))
+    return Erased(trail=_trail_row(row), calls=tuple(taking.calls))
+
+
+def _trail_row(row: DictRow) -> Erasure:
+    return Erasure.model_validate({**row, "at": row["at"].timestamp()})