Skip to main content

​
Overview

The @parmanasystems/audit-db package manages five PostgreSQL tables. Schema migrations run automatically when the server connects.

​
audit_decisions

One row per executed authority verification outcome.
ColumnTypeDescription
idbigserialAuto-increment primary key
execution_idtext NOT NULLThe executionId from the execute request
execution_fingerprinttext NOT NULLSHA-256 of canonical { policyId, policyVersion, signals }
policy_idtext NOT NULLPolicy identifier
policy_versiontext NOT NULLPolicy version
schema_versiontextPolicy schema version
runtime_versiontextRuntime semver
runtime_hashtextRuntime binary hash
decisiontextDecision action: "approve", "reject", or custom
execution_statetext"completed" or "pending_override"
signals_hashtextSHA-256 of canonical signals
bundle_hashtextPolicy bundle content hash
signaturetextEd25519 signature
attestationjsonbFull ExecutionAttestation JSON
executed_attimestamptzWhen the execution occurred
recorded_attimestamptzWhen the record was inserted
verification_validbooleantrue if verified, false if not, null if unverified
signature_verifiedtext"verified" | "failed" | "unknown"
runtime_verifiedtext"verified" | "failed" | "unknown"
schema_compatibletext"verified" | "failed" | "unknown"
verified_attimestamptzWhen verification was last run
Indexes: execution_id (unique), execution_fingerprint, policy_id, executed_at

​
audit_overrides

One row per override record (pending, approved, or rejected).
ColumnTypeDescription
idbigserialAuto-increment primary key
execution_idtext NOT NULLThe executionId from the original execute request
execution_fingerprinttext NOT NULLLinks to the semantic execution
policy_idtextPolicy identifier
policy_versiontextPolicy version
schema_versiontextPolicy schema version
decisionjsonbThe original decision object
approved_bytextReviewer identifier (from POST /override)
approver_roletextReviewer role
reasontextOverride reason
resolution_statustext"pending" → "approved" or "rejected"
override_signaturetextEd25519 signature of the override authorization
signature_typetextSigning algorithm used
pending_contextjsonbStored execution context for re-execution on approval
created_attimestamptzWhen the override was initiated
resolved_attimestamptzWhen the override was resolved
Indexes: execution_id, execution_fingerprint, resolution_status

​
audit_verifications

One row per verification call.
ColumnTypeDescription
idbigserialAuto-increment primary key
execution_fingerprinttext NOT NULLLinks to the decision
execution_idtextThe executionId from the attestation
validbooleanOverall verification result
signature_verifiedtextEd25519 signature check: "verified" | "failed" | "unknown"
runtime_verifiedtextRuntime identity check: "verified" | "failed" | "unknown"
schema_compatibletextSchema version check: "verified" | "failed" | "unknown"
verified_attimestamptzWhen verification occurred
Indexes: execution_fingerprint, execution_id, verified_at

​
audit_security_events

Security-relevant anomalies.
ColumnTypeDescription
idbigserialAuto-increment primary key
event_typetext NOT NULL"replay_attempt", "signature_failure", "invalid_policy", "rate_limit_exceeded", "unauthorized_access"
severitytext"critical", "high", "medium", "low"
event_countbigintNumber of occurrences
first_occurrencetimestamptzEarliest occurrence
last_occurrencetimestamptzMost recent occurrence
metadatajsonbAdditional event context (execution ID, policy ID, etc.)
Indexes: event_type, last_occurrence

​
audit_api_calls

API call log — every request to every endpoint.
ColumnTypeDescription
idbigserialAuto-increment primary key
endpointtextRequest path and method
status_codeintegerHTTP response status
execution_idtextThe executionId if applicable
policy_idtextThe policyId if applicable
recorded_attimestamptzWhen the call occurred
duration_msintegerRequest duration in milliseconds
Indexes: recorded_at, endpoint, execution_id

​
TypeScript interfaces (from @parmanasystems/audit-db)

interface DecisionRow {
  execution_id: string;
  execution_fingerprint: string;
  policy_id: string;
  policy_version: string;
  decision: string;
  execution_state: string;
  runtimeVersion: string;
  runtimeHash: string;
  executed_at: string;
  recorded_at: string;
  verification_valid: boolean | null;
  signature_verified: "verified" | "failed" | "unknown";
  runtime_verified: "verified" | "failed" | "unknown";
  schema_compatible: "verified" | "failed" | "unknown";
  verified_at: string | null;
}

interface DecisionDetail extends DecisionRow {
  id: number;
  schema_version: string | null;
  signals_hash: string | null;
  bundle_hash: string | null;
  signature: string | null;
  attestation: ExecutionAttestation | null;
}

interface AuditStats {
  total_decisions: string;
  decisions_today: string;
  total_verifications: string;
  valid_verifications: string;
  invalid_verifications: string;
  total_security_events: string;
  total_api_calls: string;
}

interface SecurityEventRow {
  event_type: string;
  severity: string;
  event_count: string;
  last_occurrence: string;
  first_occurrence: string;
}