Core Concepts

System views

Query Synapsor catalog, workflow, security, and storage metadata without scraping logs.

Overview

System views expose the versioned state Synapsor records for contexts, capabilities, runs, resources, proposals, settlement, RBAC, policies, migrations, and storage lifecycle.

Use these views for debugging, audits, developer dashboards, and support investigations. They are read surfaces; write workflow state through the reviewed SQL/API commands that own each lifecycle.

Use synapsor_agent_activity as the normalized search surface for runs, evidence bundles, proposals, replay ids, business object ids, query fingerprints, tenant/principal, workflow, capability, and time windows. Use synapsor_evidence_bundles and synapsor_evidence_resources to inspect bundle headers and row/chunk resources. Use synapsor_replay_records to find replay handles, branch_kind, proposal_target_kind, and writeback status. Use synapsor_query_audit to find evidence-backed query fingerprints by tenant, capability, business object, source table, and time. Use synapsor_agent_workflow_runs and synapsor_agent_run_steps to inspect durable workflow-run graphs. Use synapsor_agent_eval_runs and synapsor_agent_eval_results for regression replay. Use synapsor_memory_policies and synapsor_memory_events for governed memory evolution. Use synapsor_agent_adapters and synapsor_agent_adapter_tools for framework tool contracts. Use synapsor_observability_sinks for trace export configuration. Use synapsor_agent_runs to find capability invocation ids, branch_kind, proposal_count, and external_writeback_count. Use synapsor_agent_write_proposals or its shorter alias synapsor_write_proposals to find wrp:// proposal lookup ids, target_kind, branch_kind, branch_name, source_database_mutated, writeback_status, and trusted_worker_required values. Use synapsor_external_action_events to inspect worker outbox state, and synapsor_agent_resources to find evidence/context/resource ids.

Access is still governed by RBAC and redaction policy. A reader may see handles or metadata while sensitive payloads remain hidden.

Developer notes

Prefer system views over log scraping for user-visible diagnostics.
Keep redacted payloads redacted unless a caller has explicit audit permission.
Join proposal events, settlement events, and run resources when explaining a write decision.
Use storage lifecycle views before changing retention or archive settings.

Common catalog queries

SQL

-- Activity search: use business object, workflow, capability, tenant, principal,
-- evidence/proposal/replay ids, query fingerprint, and time window.
SELECT activity_kind, run_id, evidence_bundle_id, proposal_id, replay_id,
       workflow, capability, business_object_id, state, created_at
FROM AGENT ACTIVITY
WHERE tenant_id = 'acme'
  AND business_object_id = 'T-1042'
ORDER BY created_at DESC
LIMIT 50;

-- Evidence-focused lookup: only returns activity rows with evidence handles.
-- TIME is shorthand for the durable created_at lookup column.
INSPECT AGENT EVIDENCE
WHERE tenant_id = 'acme'
  AND business_object_id = 'T-1042'
  AND workflow = 'support.ticket_refund_flow'
  AND TIME BETWEEN 100 AND 200
ORDER BY TIME DESC
LIMIT 50;

-- Evidence resources: inspect the rows/chunks that supported a run.
SELECT source_uri, source_table, source_column, business_object_id, query_fingerprint
FROM synapsor_evidence_resources
WHERE evidence_bundle_id = 'evidence://bundle/1'
ORDER BY rank;

-- Query audit: find source reads/fingerprints by business object.
SELECT query_fingerprint, source_table, source_rid, evidence_bundle_id, created_at
FROM synapsor_query_audit
WHERE tenant_id = 'acme'
  AND business_object_id = 'T-1042'
ORDER BY created_at DESC;

-- Replay records: find the replay handle and branch/writeback semantics.
SELECT replay_id, run_id, workflow, capability, evidence_bundle_id,
       branch_kind, proposal_target_kind, writeback_status, state
FROM synapsor_replay_records
WHERE tenant_id = 'acme'
ORDER BY created_at DESC;

-- Agent runs: distinguish read-only runs from native proposal runs.
SELECT id, capability_full_name, branch_kind, proposal_count,
       external_writeback_count
FROM synapsor_agent_runs
ORDER BY id DESC;

-- Agent capability catalog: use this to debug versioned public surfaces.
SELECT full_name, kind, version, has_plan, has_write_proposal
FROM synapsor_agent_capabilities
WHERE full_name LIKE 'support.%';

-- Proposal view: use this to find wrp:// handles and target semantics.
SELECT handle_uri, capability_full_name, state, target_kind, branch_kind,
       branch_name, source_database_mutated, writeback_status,
       trusted_worker_required
FROM synapsor_agent_write_proposals
ORDER BY id DESC;

-- Workflow run graph views: use run_id returned by BEGIN AGENT RUN / SDK.
SELECT run_id, workflow_name, status, branch_name
FROM synapsor_agent_workflow_runs
ORDER BY started_at DESC;

SELECT step_key, step_kind, capability_name, evidence_id, proposal_id
FROM synapsor_agent_run_steps
WHERE run_id = 'run_...'
ORDER BY ordinal;

-- External action outbox: use this to debug worker claim/confirm status.
SELECT action_instance_id, action_name, status, queue, attempts
FROM synapsor_external_action_events
WHERE run_id = 'run_...'
ORDER BY created_at;

-- Agent evals: use eval_run_id returned by RUN AGENT EVAL or SDK.
SELECT eval_run_id, eval_name, status, total_cases, failed_cases
FROM synapsor_agent_eval_runs
ORDER BY started_at DESC;

-- Governed memory evolution and adapter contracts.
SELECT name, scope_type, subject_type, require_evidence
FROM synapsor_memory_policies;

SELECT name, type, tool_count, deny_raw_sql
FROM synapsor_agent_adapters;

SELECT adapter_name, tool_name, capability_full_name
FROM synapsor_agent_adapter_tools;

SELECT name, type, endpoint, active
FROM synapsor_observability_sinks;

-- Workflow contract inspection: shows the actual trusted session requirements,
-- allowed capabilities, and allowed external actions persisted for a workflow.
SELECT full_name, version, session_requirements, allowed_capabilities, allowed_actions
FROM synapsor_agent_workflows;

-- Storage profile view: use this before changing retention/archive settings.
SELECT table_name, profile, physical_layout, retention_status
FROM synapsor_table_storage_profiles
ORDER BY table_name;

Examples

text

synapsor_agent_contexts
synapsor_agent_context_versions
synapsor_agent_context_output_slots
synapsor_agent_capabilities
synapsor_agent_capability_versions
synapsor_agent_capability_args
synapsor_agent_searches
synapsor_agent_workflows
synapsor_agent_workflow_runs
synapsor_agent_run_steps
synapsor_agent_run_edges
synapsor_agent_runs
synapsor_agent_activity
synapsor_evidence_bundles
synapsor_evidence_resources
synapsor_agent_resources
synapsor_external_actions
synapsor_external_action_events
synapsor_agent_eval_suites
synapsor_agent_eval_runs
synapsor_agent_eval_results
synapsor_memory_policies
synapsor_memory_events
synapsor_agent_adapters
synapsor_agent_adapter_tools
synapsor_observability_sinks