Execution & evidence
Every write and tool call runs through one pipeline — and can leave a correlatable evidence record.
Writes and tool calls used to be guarded in different places. Now they share one protocol-agnostic pipeline so guardrails and approvals apply identically to REST, MCP, GraphQL, script and custom tools — and each execution can leave a single evidence record.
Stages
Plan → Validate → Authorize → Guardrail → Approval → Execute → Commit → EvidenceEXECUTION_STAGES is the single-source list. runPipeline(plan, ctx, deps) runs one execution and
records every stage outcome; a deny/pending short-circuits execute.
- Plan / Validate — a
ExecutionPlan(action,objectName?,objectId?,args,intent?); tool arguments are validated against the declaredToolJsonSchema(validateToolArgs). - Authorize / Guardrail / Approval — RBAC plus the guardrail policy set; a policy may require approval (enqueued in the approvals queue).
- Execute / Commit — the work, owning its own transaction.
- Evidence — the recorded record (below).
The pipeline drives two choke points: the data-access write path (create/update/delete /
workflow transition, action object.<obj>.<op> / workflow.transition.<obj>.<action>) and the
custom-tool executor (action mcp.tool.<name>). Because every protocol ends at data-access,
guardrails/approvals/evidence cover all of them from one place.
Evidence
Enable it to record one weavekit_evidence row per execution — every data-access
create/update/delete, every workflow transition and every custom-tool call, whether or not a
guardrail policy is configured:
// weavekit.config.ts
export default { /* ... */ evidence: { enabled: true } };The row is written after the execution, with its real outcome: a successful write records
plan → [guardrail → approval →] execute → commit → evidence; a write that fails (validation, a
unique violation, a missing record) records execute: error with the error code; a deny/pending gate
stops at guardrail/approval. RBAC denials are rejected before the pipeline and stay in the audit
trail. Evidence is best-effort: a failed evidence write never blocks the execution (a transactional
mode is planned separately). When the caller supplies its own transaction, commit means the step
completed inside that transaction.
An Evidence (core/tools/pipeline.ts) carries the correlation ids (requestId, traceId,
schemaRevision), the actor, subjectId, the plan, the per-stage stages timeline, plus
approvalKey / isError / errorCode and the timestamp. EvidenceSink.record is the seam; the
engine ships the PG sink (subsystems/evidence).
Read it back with the same stable pagination contract as the audit trail:
import { queryEvidence } from '@weave-kit/engine';
const page1 = await queryEvidence(pool, { action: 'mcp.tool.search_records', limit: 50 });
const page2 = await queryEvidence(pool, { limit: 50, cursor: page1.nextCursor! });EvidenceQuery filters by action / objectName / subjectId / actorKey / isError / from /
to and pages by limit + offset or a keyset cursor over (ts DESC, id DESC); a malformed
cursor is a http.param.invalid (400). Rows are newest-first.
Correlation
requestId (HTTP request id), traceId (parsed W3C traceparent) and schemaRevision link one
execution to the request, the audit trail and the applied schema
revision — so an agent action is traceable across API, audit and evidence. See
Observability.
Scope boundary
The engine only captures evidence. Export, retention policy and compliance reporting are the enterprise E2 layer.
Related
- Custom tools & guardrails — the open contract the pipeline drives
- Approvals — the human-in-the-loop step
- Audit · Observability
- Public API —
runPipeline/Evidence/queryEvidence