@parmanasystems/audit-db

PostgreSQL audit database client for persisting governance decisions and verification events

@parmanasystems/audit-db is the PostgreSQL persistence layer for Parmana Systems governance decisions, verification records, and security events. It provides the durable audit trail required for regulatory compliance.

Install

npm install @parmanasystems/audit-db

Requires a PostgreSQL connection. The package uses the pg client.

Setup

import { AuditDb } from "@parmanasystems/audit-db";

const db = new AuditDb({
  connectionString: process.env.DATABASE_URL,
});

// Run migrations (create tables if they don't exist)
await db.migrate();

Recording decisions

Persist an ExecutionAttestation immediately after execution:

const attestation = await executeFromSignals(/* ... */);

await db.recordDecision(attestation);
// Stores: executionId, policyId, policyVersion, decision, execution_state,
//         signalsHash, signature, runtimeHash, runtimeVersion, createdAt

The signature field in the stored row is the cryptographic proof that the record has not been modified since execution. Any modification to the stored decision data would cause signature verification to fail.

Querying

// Retrieve a specific decision by executionId
const record = await db.getDecision(executionId);

// List decisions for a policy
const records = await db.listDecisions({
  policyId:      "claims-approval",
  policyVersion: "v1",
  limit:         100,
});

Recording verification events

Audit verification attempts as well as execution decisions:

await db.recordVerification({
  executionId:   attestation.executionId,
  valid:         true,
  verifiedAt:    new Date(),
  verifierAgent: "compliance-team",
});

Migrations

The package ships migrations that create the required tables. Run them at startup:

await db.migrate();

Or via the migration script:

npm run migrate --workspace=packages/audit-db

Schema

The primary decisions table stores:

Column	Type	Description
execution_id	TEXT PRIMARY KEY	SHA-256 execution identity
policy_id	TEXT	Policy identifier
policy_version	TEXT	Policy version
decision_action	TEXT	"approve" or "reject"
requires_override	BOOLEAN	Escalation required
execution_state	TEXT	"completed" / "blocked" / "pending_override"
signals_hash	TEXT	SHA-256 of canonical input signals
signature	TEXT	Ed25519 attestation signature
runtime_hash	TEXT	Runtime binary state hash
runtime_version	TEXT	Parmana Systems runtime version
created_at	TIMESTAMPTZ	Insertion timestamp

The signature column is the integrity anchor. Always include it when exporting decisions for compliance review — it is what allows independent verification.