WeaveKit Docs
GuidesAgents

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 → Evidence

EXECUTION_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 declared ToolJsonSchema (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.

On this page