Turn comments and DMs into buyers

One raised hand, one durable record

An inbound event can arrive twice, arrive out of order, or arrive while a provider is timing out. A reliable path gives that event one canonical record, plans each outward action once, and leaves enough evidence to recover without guessing.

This is a standalone event-to-record method for one comment or DM source. It covers capture reliability. Qualification, offer design, account operation, and live routing sit outside this edition.

The reliability contract

For every accepted source event, the system creates exactly one canonical event record and at most one reply action for each declared reply purpose. Repeated delivery converges on the same keys.

The contract has six invariants:

1. event_key comes from stable source identifiers. Receipt time and message text never act as the sole key.
2. The event store enforces a unique constraint on event_key.
3. reply_key comes from event_key plus one declared purpose such as public_ack or private_delivery.
4. The reply ledger enforces a unique constraint on reply_key.
5. Every live reply waits for recorded human approval.
6. An uncertain provider result enters SEND_STATUS_UNKNOWN. Reconciliation checks evidence before any retry.

Duplicate delivery must not produce duplicate records or replies. A repeated event updates last_received_at and seen_count on the existing record. It does not create another event row or another reply action.

Raw inputs and tangible outputs

Class	Required material
Raw input	One allowlisted event type, its stable source identifiers, source authenticity rule, field map, reply purposes, approved copy, retention rule, and synthetic fixture
Human-held input	Account access, credentials, buyer payloads, actual field values, trigger meaning, reply judgment, live-send approval, policy judgment, and exception decisions
Tangible output	A canonical event ledger, reply-action ledger, quarantine log, human review queue, reconciliation report, canary report, and transition history

Use placeholders while building. Keep credentials and real buyer content outside agent prompts, fixtures, logs, and screenshots.

Step 1: Declare the event

Choose one source and one event type for the starter. A valid event contract contains:

Field	Rule
source_system	Stable provider or adapter name
source_account_ref	Stable account identifier supplied by the human operator
source_event_id	Provider event identifier when available
event_type	Exact allowlisted type such as comment.created
conversation_ref	Stable post, thread, or conversation identifier
message_ref	Stable comment or message identifier
sender_ref	Opaque source identifier, never a display name used as a key
occurred_at	Source timestamp normalized to UTC
received_at	Ingress timestamp, used for traceability rather than identity
payload_hash	SHA-256 of the canonicalized accepted payload
contract_version	Version of the event and field-map contract
canary	Explicit boolean set by the trusted test adapter

Verify a webhook signature or the equivalent source proof before mapping the payload. Route invalid proof and missing required identifiers to QUARANTINED. Create no reply action from quarantined input.

The quarantine ledger is separate from the canonical event ledger. Give each quarantine receipt a local receipt_id, retain only policy-approved diagnostic metadata, and require human review before correction.

When the provider supplies a stable event identifier, derive:

event_key = source_system + ":" + source_account_ref + ":" + event_type + ":" + source_event_id

When no stable event identifier exists, use a hash of stable source fields:

event_key = SHA-256(
  source_system + "|" +
  source_account_ref + "|" +
  event_type + "|" +
  conversation_ref + "|" +
  message_ref
)

Route the receipt to QUARANTINED when the stable field set is incomplete. Never substitute receipt time, display name, or message text for a missing source identity.

Step 2: Map the event to one record

Freeze the field map before connecting a live source:

Source input	Canonical field	Mapping rule
Provider name	source_system	Normalize to one allowlisted adapter name
Account ID	source_account_ref	Preserve the stable ID and keep its value private
Event ID	source_event_id	Preserve exactly when supplied
Event name	event_type	Reject types outside the allowlist
Post or thread ID	conversation_ref	Preserve exactly
Comment or message ID	message_ref	Preserve exactly
Sender ID	sender_ref	Store an opaque identifier
Source creation time	occurred_at	Convert to UTC and retain the original offset in audit metadata
Accepted payload	payload_hash	Canonicalize, hash, and store only the content needed by the declared method
Human trigger rule	trigger_match	Record the rule version and the resulting boolean

The event record also carries event_state, first_received_at, last_received_at, seen_count, reconcile_status, canary, and a transition history with actor and timestamp.

Ingest in one durable transaction:

verify source proof
normalize the event
derive event_key
begin transaction
upsert event by event_key
increment seen_count on conflict
if trigger_match is true, create each declared reply action by reply_key on first insert
if trigger_match is false, set event_state to CLOSED_NO_REPLY
append event and reply-action transitions to their owning ledgers
commit
acknowledge receipt

An unavailable durable store produces a retryable ingress failure. Acknowledgment follows the commit so a provider retry can safely converge on the same record.

Step 3: Plan and deliver each reply once

Each outward action gets its own ledger row:

Field	Rule
reply_key	Unique key derived from the event and declared purpose
event_key	Foreign key to the canonical event
purpose	Allowlisted value such as public_ack or private_delivery
channel	Human-approved destination channel
copy_version	Identifier for human-approved reply copy
approval_state	REVIEW_PENDING or APPROVED with actor and timestamp
delivery_state	Current state from the state model below
provider_reply_id	Provider receipt when a send is confirmed
attempt_count	Count of transport attempts under the same key
last_error_code	Structured failure code without credentials or buyer content

Derive the action key once:

reply_key = SHA-256("reply|" + event_key + "|" + purpose)

The starter requires a human to supply the trigger rule, field values, destination, and reply copy. The same human approves every outward action. Account connection, credential entry, and live-send enablement remain human-only steps.

The sender claims an approved row with one atomic transition from APPROVED to SENDING. A row already in SENDING, SENT, SUPPRESSED_TEST, or CLOSED_NO_REPLY cannot be claimed again.

Pass reply_key to a provider idempotency field when the provider supports one. Record the provider receipt before marking SENT. A timeout after the external request creates SEND_STATUS_UNKNOWN.

Provider support determines the safe recovery path:

Provider capability	Recovery rule
Idempotency key plus receipt lookup	Reconcile first. A human may authorize a retry under the same reply_key after the lookup
Receipt lookup without idempotent send	Reconcile first. Retry only after evidence shows no send and a human approves
Neither capability	Keep the action in SEND_STATUS_UNKNOWN until a human verifies the conversation. Do not retry automatically

This rule closes the crash window where a provider accepts a reply but the local process loses the receipt.

Step 4: Keep failure states owned

Event and reply states belong to separate ledgers. A recovery routine must update the state in the named owner.

Event state	Owner	Meaning	Allowed next action
RECEIVED	Canonical event ledger	Source proof passed and the event reached durable handling	Normalize and map
RECORD_READY	Canonical event ledger	The canonical record exists and any applicable reply plan was created	Retain the event and queue reply review
CLOSED_NO_REPLY	Canonical event ledger	The trigger did not match or a human chose no outward action	Retain the decision
QUARANTINED	Quarantine ledger	Source proof or required identity failed	Correct through a reviewed path

Reply state	Owner	Meaning	Allowed next action
REVIEW_PENDING	Reply-action ledger	A human decision or required value is missing	Approve, correct, or close
APPROVED	Reply-action ledger	Human approval is recorded	Atomic sender claim
SENDING	Reply-action ledger	One worker owns the transport attempt	Record receipt or uncertainty
SENT	Reply-action ledger	Provider receipt is stored	Close or reconcile
FAILED_BEFORE_SEND	Reply-action ledger	Failure occurred before an external effect	Retry under the same keys
SEND_STATUS_UNKNOWN	Reply-action ledger	The provider may have accepted the action	Reconcile and require human judgment
SUPPRESSED_TEST	Reply-action ledger	Canary created the action and blocked transport	Include in the canary report

Every transition records its owning ledger, prior state, next state, timestamp, actor, and reason code. Reject and log any transition outside the declared state model. Absence of an error never counts as proof of a send.

Step 5: Reconcile source evidence against local state

Reconciliation compares a bounded source window or cursor with both local ledgers. The human operator selects the account, window, and source access.

1. Read source event identifiers through an approved export or provider query.
2. Normalize them with the same contract used at ingress.
3. Derive the same event_key values.
4. Compare the source set with the event ledger.
5. Compare provider reply receipts with the reply-action ledger.
6. Write a report before applying any repair.

Use these repair rules:

Evidence condition	Repair
Source event exists and local event is missing	Replay it through the normal idempotent ingest path. Hold any reply at human review
Source and local event both exist	Update reconciliation evidence. Create no new action
Local event has no matching source evidence	Set reconcile_status to SOURCE_UNVERIFIED. Preserve the record for review
Provider receipt exists for SENDING or SEND_STATUS_UNKNOWN	Attach the receipt and mark SENT
Local action says SENT and provider receipt is missing	Mark SEND_STATUS_UNKNOWN. Preserve the action and stop
No receipt exists and a retry may be safe	Create a RETRY_CANDIDATE finding. A human decides whether the same reply_key may run again

The reconciliation report records the source cursor, contract version, events compared, missing records recovered, duplicates converged, replies confirmed, unknown sends, quarantined inputs, and every human decision. It never creates a fresh reply key or resends solely because a receipt is absent.

Step 6: Prove the path with a non-delivery canary

The canary uses a signed synthetic fixture and the same normalizer, key derivation, storage constraints, state rules, and reconciliation logic as the real path. Its adapter sets canary: true before ingress.

The transport boundary has one hard guard:

if canary is true:
  write the planned action to the canary sink
  set delivery_state to SUPPRESSED_TEST
  make no external send

Run the fixture twice. The expected canary evidence is one event row, one row per declared reply purpose, seen_count equal to two, every reply action in SUPPRESSED_TEST, and zero calls to an external transport.

The canary proves parsing, normalization, unique constraints, mapping, action planning, state transitions, reconciliation, and transport suppression. It does not prove production credentials, platform permission, or a live send. Those remain separate human checks.

Any canary path aimed at a live adapter must fail closed before a network call. Use reserved synthetic identifiers and a non-delivery sink. Never use a real buyer record as a canary.

The smallest useful starter

Build one bounded path with:

1. One adapter for one allowlisted event type.
2. One inbound_events store with a unique event_key.
3. One reply_actions store with a unique reply_key.
4. One review view for REVIEW_PENDING and SEND_STATUS_UNKNOWN.
5. One reconciliation routine that writes a report before repair.
6. One signed synthetic fixture and non-delivery canary sink.

Leave the live transport disabled until the acceptance contract passes and a human authorizes the account connection.

Worked example: synthetic only

This structural example uses a fictional organization called Northstar Workshop Co. All identifiers and reply copy are invented. It contains no customer evidence, live account, spend, send, or outcome. External transport stays disabled.

The fixture contains:

Field	Synthetic value
source_system	sandbox-social
source_account_ref	acct_test_01
source_event_id	evt_test_0042
event_type	comment.created
conversation_ref	post_test_07
message_ref	msg_test_0042
sender_ref	person_test_09
occurred_at	2026-01-15T14:30:00Z
contract_version	event-v1
canary	true
Message text	CHECKLIST

The canonical key is:

sandbox-social:acct_test_01:comment.created:evt_test_0042

The declared reply purposes are public_ack and private_delivery. Their structural copy is The sample checklist is ready in the test fixture. Each action receives a stable key from the canonical event key and its purpose.

Expected fixture sequence:

1. First delivery creates one event record and two reply-action rows.
2. The canary guard puts both actions in SUPPRESSED_TEST.
3. Second delivery finds the existing event, changes seen_count from one to two, and creates no rows.
4. Reconciliation compares the fixture source with local state and reports one matched event, two suppressed actions, one converged duplicate delivery, and zero external calls.

These are acceptance expectations for the synthetic fixture. They are not reported operating results.

Paste-ready agent contract

Use this contract with a coding agent in a blank local test project. Keep production accounts disconnected.

ROLE
You are the reliability architect for one generic inbound event-to-record path.

READ FIRST
Use the event contract, field map, reply-action contract, state model,
reconciliation rules, canary guard, and acceptance checks in this page.

INPUTS
Use placeholders for the target adapter, account reference, trigger rule,
reply copy, retention rule, and policy choices.
Use only the synthetic fixture supplied in this page.

HUMAN-CONTROLLED
The human owns credentials, account access, actual field values, buyer data,
trigger meaning, reply copy, policy judgment, live-send approval, and every
decision involving SEND_STATUS_UNKNOWN.
Do not request, print, store, or infer those values.

WORK
1. Write an event contract and frozen field map.
2. Create an inbound event store with a unique event_key.
3. Create a reply-action store with a unique reply_key.
4. Implement atomic ingest and state transitions.
5. Implement a review queue with live transport disabled.
6. Implement reconciliation as compare, report, then reviewed repair.
7. Implement the synthetic canary with a non-delivery sink.
8. Add acceptance checks and mutation checks.

OUTPUTS
Return the event contract, field map, storage schema, state transition table,
synthetic fixture, canary result, reconciliation report, acceptance report,
and a human-held checklist.

STOP CONDITIONS
Stop before connecting an account, adding credentials, inserting real buyer
data, enabling a live send, choosing actual field values, or resolving a
judgment call. Report the exact held input required.

ACCEPTANCE
A duplicate fixture delivery leaves exactly one event row.
Each declared reply purpose leaves exactly one reply-action row.
An unapproved action cannot reach transport.
An ambiguous provider result cannot retry automatically.
Reconciliation cannot create a fresh reply_key.
The canary makes zero external calls.
Every check must fail when its guarded behavior is deliberately broken.

For ongoing help, give the agent one failed state, its transition history, and the expected invariant. Keep credentials and buyer content outside the prompt.

Acceptance checks

The starter is ready for human review when all checks produce exact evidence:

Check	Required evidence
Event identity	Two deliveries of the same fixture leave exactly one event row and seen_count of two
Reply identity	Reprocessing leaves exactly one row for each declared reply_key
Source proof	A fixture with invalid proof enters QUARANTINED and creates zero reply actions
Required fields	Removing one stable identity field routes the receipt to QUARANTINED and creates zero reply actions
Approval gate	An action in REVIEW_PENDING produces zero transport calls
Safe retry	A failure before transport retries under the same keys
Ambiguous send	A simulated lost receipt enters SEND_STATUS_UNKNOWN and produces no automatic retry
Reconciliation	A missing local event re-enters through normal ingest and creates no duplicate action
Canary	Two canary deliveries produce the exact expected rows and zero external calls
State model	An undeclared transition is rejected and recorded in its owning ledger
Data boundary	Logs and reports contain no credential, real buyer payload, or actual field value
Instrument integrity	Mutation tests prove the duplicate, approval, reconcile, and canary assertions can fail

Plant positive controls before trusting a clean report. Disable the event uniqueness rule and confirm the duplicate assertion fails. Change reconciliation to mint a new reply key and confirm the reply assertion fails. Point a canary action at the live adapter and confirm the guard blocks execution before transport. A check that stays green after its guarded behavior is broken has failed as an instrument.

Human-controlled boundary

This edition supplies the generic method and synthetic contract. The recipient controls:

1. Credentials and account access.
2. Buyer data and every actual field value.
3. Trigger policy, reply copy, consent, retention, and platform judgment.
4. Approval of every live outward action.
5. Reconciliation decisions for uncertain sends.
6. Production routing, qualification, and later commercial decisions.

The records prove processing state. They do not prove buyer fit, buying intent, revenue, or campaign performance. This page does not connect an account, send a message, or operate a live path.