Audit

Every decision, execution, rollback, and actor action produces an immutable audit entry. You cannot modify or delete audit entries.

queryAuditLog()

const result = await hdb.queryAuditLog(params: AuditQueryParams): Promise<PaginatedResponse<AuditEntry>>

Parameters

interface AuditQueryParams {
  actorId?:    string;   // filter by actor
  action?:     string;   // filter by action type
  outcome?:    string;   // 'success' | 'failure' | 'blocked'
  decisionId?: string;   // filter by linked decision
  sessionId?:  string;   // filter by session
  from?:       string;   // ISO 8601 start date
  to?:         string;   // ISO 8601 end date
  page?:       number;   // default 1
  limit?:      number;   // default 50, max 200
}

Response

interface AuditEntry {
  id:          string;
  actorId:     string;
  action:      string;
  outcome:     'success' | 'failure' | 'blocked';
  resourceType: string | null;
  resourceId:   string | null;
  decisionId:   string | null;
  sessionId:    string | null;
  metadata:     Record<string, unknown>;
  createdAt:    string;  // ISO 8601
}

interface PaginatedResponse<T> {
  data:       T[];
  total:      number;
  page:       number;
  limit:      number;
  hasMore:    boolean;
}

Examples

// All actions by a specific actor
const log = await hdb.queryAuditLog({
  actorId: 'user:alice',
  limit:   100,
});

// All blocked decisions in the last 24 hours
const blocked = await hdb.queryAuditLog({
  outcome: 'blocked',
  from:    new Date(Date.now() - 86_400_000).toISOString(),
});

// Trace everything related to a specific decision
const trace = await hdb.queryAuditLog({
  decisionId: 'dec_abc123',
});

// Paginate through large results
let page = 1;
while (true) {
  const result = await hdb.queryAuditLog({ page, limit: 200 });
  process(result.data);
  if (!result.hasMore) break;
  page++;
}

---

What gets logged automatically

You do not need to write audit entries manually. The following are logged by the runtime:

Event	Logged automatically
Decision requested	✓
Decision outcome (allow/block/escalate)	✓
Pipeline triggered	✓
Each pipeline step start/complete/fail	✓
Checkpoint written	✓
Rollback initiated	✓
Rollback complete	✓
Replay initiated	✓
Actor created / suspended	✓
API key created / revoked	✓
Policy activated / deactivated	✓

Custom events published via hdb.publishEvent() also appear in the audit trail.