LeadRefinery — How the Platform Works

Opt-outs

Traced at commit 51a6cfa · apps/api/src/app/webhooks/agent-tools.service.ts · libs/contracts/src/lib/{vector-resolution,compliance,canonicalization,scrub}.ts · libs/temporal/src/activities/{call-attempt,dial-gate}.ts

Summary

  1. A person asks the agent to stop the calls.
  2. Three mechanisms record the request. Each mechanism fails in a different way.
  3. Mechanism 1 writes a stop record during the call.
  4. Mechanism 2 reads the transcript after the call. It writes a stop record again.
  5. Mechanism 3 is the safety gate. It reads the stop records before each dial.
  6. Every join is an OR. One detector is sufficient.
  7. Mechanism 1 stops one client. Mechanism 2 stops all clients. This difference is a known conflict.
Three mechanisms honour one opt-out. What the person said sits at the top and splits two ways. On the left, during the call, the agent calls a tool; the system works out which client the call belongs to in three fallback steps, writes an audit record before acting, then writes a stop record covering that client's number only, and emails the client's admin. On the right, after the call, the transcript is read twice — by the voice provider's own analysis and by our own list of sixteen fixed phrases — and either reading alone is enough to raise the flag, which writes three stop records covering the lead, the number, and every client on the platform. A dashed box across the middle records that the two paths deliberately disagree about reach. Both paths feed one append-only stop list, which the safety gate consults second of thirteen checks before every single dial, matching this lead, this client's record, or anyone's platform-wide record, and refusing even without a record if an earlier call raised the flag.
Two detectors and one enforcer.

Mechanism 1 — the agent writes the record

  1. The agent calls the tool submit_dnc_request.
  2. The tool call arrives at POST /v1/callback.
  3. The system identifies the client from the call metadata.
  4. If the metadata is incomplete, the system finds the call id in the database.
  5. If the database has no record, the system accepts a client name from the agent. The system first confirms that this client exists.
  6. If all three steps fail, the system writes no record. The system tells the agent to do the task manually.
  7. The system writes the audit record before it writes the stop record.
  8. The system writes one stop record. The scope is NUMBER. The reach is one client.
  9. The system keeps the words of the person as evidence.
  10. The system sends an email to the administrator of the client.

Note. The audit record comes first. A failure after this point still leaves evidence of the request. The de-duplication key includes the arguments. The platform absorbs a retry from the provider. The platform does not absorb a changed request.

Mechanism 2 — the platform reads the transcript

  1. The call ends. The provider sends the transcript.
  2. The system verifies the signature before it reads the transcript.
  3. Two detectors read the transcript.
  4. Detector A is the analysis of the provider. Detector A understands meaning. Detector A can be wrong.
  5. Detector B is a fixed list of 16 phrases. Detector B cannot infer. Detector B does not change.
  6. One detector is sufficient to set the flag DNC_REQUEST. See D5 — compliance flags.
  7. The flag causes two actions: HALT_CADENCE and SUPPRESS_LEAD.
  8. The system writes three stop records. The scopes are LEAD, NUMBER and GLOBAL.
  9. The scope GLOBAL reaches every client on the platform.

Mechanism 3 — the safety gate

  1. The gate runs 13 checks before each dial.
  2. The stop-list check is number 2. It is the cheapest check and the most decisive check.
  3. The gate stops at the first refusal. A stopped person is never assessed for consent, list freshness or capacity.
  4. The check matches this lead, this client’s record for the number, or any client’s platform-wide record.
  5. If no stop record exists, the gate applies a second rule.
  6. The second rule refuses any lead whose earlier call raised a compliance flag.
  7. The gate evaluates the checks at dial time. The gate does not use the result from schedule time.

Known conflict

  1. Mechanism 1 writes the scope NUMBER. The reach is one client.
  2. Mechanism 2 writes the scope GLOBAL. The reach is all clients.
  3. The reach of one request therefore depends on which detector operates first.
  4. The reason for mechanism 1 is that a platform-wide stop from one machine judgement is a decision for a person.
  5. The reason for mechanism 2 is that the caller does not know that the platform serves several clients.
  6. Both reasons are correct. This is an open decision. It is not a defect. Do not change one side without a decision.

Known history

  1. A database constraint rejected every GLOBAL record. The write never completed in production.
  2. A rehearsal found this defect. An engineer corrected it.
  3. The record counts still show the defect. The database holds approximately 20,100 LEAD records and 1,600 GLOBAL records.
  4. The LEAD count includes all history. The GLOBAL count starts at the correction.

Timing

  1. Mechanism 1 completes during the call.
  2. Mechanism 2 completes after the call and after the provider analysis.
  3. The measured delay for mechanism 2 is approximately 3,566 seconds.
  4. This measurement comes from rehearsal traffic. Use the magnitude, not the value.
  5. This delay is the reason for mechanism 1.

The dial gate — the 13 checks before each dial. The stop-list check is number 2.