Synapsor
Log inGet access
All docs
Docs
Core Concepts

Find evidence later

How humans find the exact run, evidence bundle, proposal, approval, settlement, and replay record after many agent reads or writes.

Overview

A human should not need to scroll chat logs, model traces, browser session history, or a giant run list to find evidence later. Every customer-visible answer, proposal, approval, rejection, auto-settlement, or writeback should produce a compact audit receipt stored beside the business event in your app.

The fastest lookup path is the returned Synapsor id: run_id or replay_id, evidence_bundle_id, proposal_id, settlement_id, branch name, and request_id. Store those ids with the ticket, invoice, order, refund, CRM event, support decision, or background job that your user can recognize.

In UI terms: show or store a receipt on the same screen where the human sees the agent result. A support lead should open the ticket timeline, invoice adjustment, order note, or CRM event and see the Synapsor run/evidence/proposal/replay ids there. They should not need to know what an evidence:// handle means before they can audit the decision.

The fallback lookup path is indexed search. If a reviewer only knows 'the Acme invoice run from yesterday', use FROM AGENT ACTIVITY, INSPECT AGENT EVIDENCE, or the Proposal views by project, database, workflow, capability, tenant/principal, business object id, request id, query fingerprint, proposal or settlement id, and time window.

For read-only capabilities, the receipt points to run -> evidence bundle -> query audit -> replay. For write proposals, the receipt points to proposal -> branch/diff -> evidence bundle -> run -> approval/settlement -> replay. For automatic approvals or merges, start from the settlement record and follow the same links backward.

This is the difference between a handle and an operational audit trail. The handle opens one record. The audit receipt plus indexed Activity search lets humans find the right record among millions or billions of agent reads.

Agent ActivityEvidence bundlesReplayWrite proposalsExisting DB quickstart

What your app stores

Store one receipt row whenever your app shows an agent answer, proposed change, approval decision, settlement decision, or writeback status to a human.

This row belongs next to your app's normal business object. For example, a support ticket timeline item can store the Synapsor run id and evidence id; a billing adjustment record can store the proposal id, settlement id, and replay id.

The receipt is not a model log. It is a small product artifact your app can render as 'Evidence for this agent action' or 'Audit trail for this change.' The human starts from the app object, then opens Synapsor only for deeper inspection.

app-agent-audit-receipt.sql
CREATE TABLE app_agent_audit_receipts (
  id BIGSERIAL PRIMARY KEY,
  business_object_type TEXT NOT NULL,       -- ticket, invoice, order, refund, CRM event
  business_object_id TEXT NOT NULL,         -- app id the reviewer already knows
  app_request_id TEXT,                      -- request/job id from your app
  synapsor_request_id TEXT,                 -- request_id returned by Synapsor/API gateway
  synapsor_run_id TEXT,                     -- run/replay id returned by Synapsor
  evidence_bundle_id TEXT,                  -- evidence bundle returned by the capability
  proposal_id TEXT,                         -- proposal id when a write was staged
  settlement_id TEXT,                       -- settlement id when policy/human review decided
  branch_name TEXT,                         -- branch used for staged writes, when present
  workflow_name TEXT NOT NULL,              -- governed workflow
  capability_name TEXT NOT NULL,            -- reviewed capability
  tenant_id TEXT NOT NULL,                  -- trusted backend session scope
  principal TEXT NOT NULL,                  -- authenticated user/service identity
  query_fingerprint TEXT,                   -- external/source query audit fingerprint
  decision TEXT NOT NULL,                   -- answered, proposed, approved, rejected, settled
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

How a reviewer finds the record

Best path: open the business object in your app, read the stored receipt row, then open the linked Evidence, Proposal, Activity, or Replay page in Synapsor.

Fallback path: query Synapsor Activity when the app receipt is incomplete. Use FROM AGENT ACTIVITY or INSPECT AGENT EVIDENCE with stable indexed fields: tenant, principal, workflow, capability, business object id, query fingerprint, proposal id, replay id, evidence bundle id, and time window.

lookup-flow.sql
-- Start from the app object the human knows.
SELECT *
FROM app_agent_audit_receipts
WHERE business_object_type = 'invoice'
  AND business_object_id = 'INV-3001'
ORDER BY created_at DESC
LIMIT 20;

-- Then open exact Synapsor records by returned ids, or query Activity.
SELECT activity_kind, run_id, evidence_bundle_id, proposal_id, replay_id,
       workflow, capability, state, created_at
FROM AGENT ACTIVITY
WHERE tenant_id = 'acme'
  AND business_object_id = 'INV-3001'
ORDER BY created_at DESC
LIMIT 50;

SELECT source_uri, source_table, source_column, query_fingerprint
FROM synapsor_evidence_resources
WHERE evidence_bundle_id = 'evidence://bundle/1'
ORDER BY rank;

SELECT query_fingerprint, source_table, source_rid, evidence_bundle_id
FROM synapsor_query_audit
WHERE business_object_id = 'INV-3001'
ORDER BY created_at DESC;

How auto-approvals are audited

An automatic approval or auto-merge is still findable because it is not just a model answer. Synapsor records the structured settlement decision, policy version, reason codes, proposal id, branch/diff, evidence bundle, run id, and replay checkpoint.

Start from the settlement or proposal id when your app stored it. If not, search by the business object, workflow, capability, tenant/principal, decision, and time window, then open the proposal and follow its links back to evidence and replay.

auto-settlement-chain.txt
business object in your app
  -> app_agent_audit_receipts row
  -> settlement decision / policy version
  -> proposal id + branch diff
  -> evidence bundle + query audit
  -> run/replay id
  -> readable rows, policy chunks, approval reason, and final state

Developer notes

  • Store an audit receipt beside the business object for every customer-visible agent result.
  • Include run/replay id, evidence id, proposal/settlement ids when present, workflow, capability, tenant/principal, request id, business object id, query fingerprint, and timestamp.
  • Make your reviewer UI start from business objects, not raw model logs.
  • Use FROM AGENT ACTIVITY, INSPECT AGENT EVIDENCE, or the Proposal views when the exact handle is missing.
  • For automatic approvals or merges, keep the settlement id and policy version in the receipt.
  • Use replay to inspect the stored run without rerunning external reads, writes, or side effects.