ctx.provenance

// Most ctx.* calls create provenance records automatically.
// You don't need to call ctx.provenance.log() for every LLM call —
// each ctx.llm.complete() already returns a provenanceId.

const response = await ctx.llm.complete({ prompt: 'Analyze this contract.' });
console.log(response.provenanceId);  // 'prov_a1b2c3d4...'

const dbResult = await ctx.db.insert('invoices', invoiceData);
// The insert is logged automatically with the agentId and delegationChain

// Log custom business events to the audit trail
const provenanceId = await ctx.provenance.log({
  action: 'invoice.validated',
  executionId: ctx.executionId,
  agentId: ctx.agentId,
  timestamp: Date.now(),
  input: {
    invoice_id: invoiceId,
    expected_total: 15000,
    computed_total: 14200,
  },
  output: {
    status: 'mismatch_detected',
    escalation_triggered: true,
  },
  cost: ctx.llm.getTotalCost(),
});

console.log('Logged event:', provenanceId);

// Attest an action — creates a cryptographically signed record
// Use for high-stakes actions that need to be verifiable by third parties
const attestationId = await ctx.provenance.attest(
  'payment.authorized',
  {
    invoice_id: invoiceId,
    amount: 14200,
    currency: 'USD',
    authorized_by: decision.humanId,
    decision_provenance: decision.metadata.provenanceId,
  }
);

// Later, anyone can verify this attestation
const result = await ctx.provenance.verify(attestationId);
console.log(result.valid);     // true
console.log(result.signedBy);  // The agent's DID
console.log(result.verifiedAt); // Timestamp of verification

// Query the audit trail
const events = await ctx.provenance.query({
  action: 'invoice.validated',
  timeRange: {
    start: Date.now() - 7 * 24 * 60 * 60 * 1000,  // last 7 days
    end: Date.now(),
  },
  hasError: false,
  limit: 50,
  sort: 'desc',
});

for (const event of events) {
  console.log(event.action, event.timestamp, event.cost?.usd);
}

// Get the complete audit trail for an execution
const events = await ctx.provenance.trace(ctx.executionId);
// Returns all events in order: llm calls, db ops, agent calls, custom logs

// Get the delegation chain — who authorized what
const chain = await ctx.provenance.delegationChain(ctx.executionId);
console.log(chain);
// ['did:passport:human-alice', 'did:agent:invoice-suite', 'did:agent:invoice-processor']

// Export audit trails for compliance
const csvExport = await ctx.provenance.export(
  {
    timeRange: { start: monthStart, end: monthEnd },
    agentId: ctx.agentId,
  },
  'csv'
);

// Write to file storage for compliance archival
await ctx.files.writeText('/exports/audit-2024-01.csv', csvExport);