governance-platform

governance-sdk-platform

PostgreSQL storage layer for governance-sdk -- auto-migrating schema, typed queries for org settings and policy tiers.

What it does

Provides persistent storage for governance state that the core SDK evaluates in-memory:

• Auto-migrating schema -- tables created and upgraded automatically on first connection
• Org settings -- plan, preferences, kill switch state, scoring/detection config
• Policy tiers -- org-default rules, level-scoped rules, and agent-specific overrides
• Saved policies -- versioned policy definitions with level and agent assignments
• Typed throughout -- full TypeScript types for all stored structures

Install

npm install governance-sdk-platform

Requires a PostgreSQL client as a peer dependency (pg >= 8.0.0).

Quick Start

import { createPlatformStorage } from 'governance-sdk-platform';
import pg from 'pg';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

// Create storage -- auto-migrates schema on first call
const platform = await createPlatformStorage({ pool });
console.log(`Applied ${platform.migrationsApplied} migrations`);

// Load org settings (returns defaults if no row exists)
const settings = await platform.loadOrgSettings('org_123');
// => { clerkOrgId, plan, settings: { autoRegisterAgents, killSwitch, ... }, ... }

// Save org preferences
await platform.saveOrgSettings('org_123', {
  settings: {
    killSwitch: { reason: 'Security incident', killedAt: new Date().toISOString(), scope: 'fleet' },
  },
});

// Load policy tiers for enforcement
const tiers = await platform.loadPolicyTiers('org_123');
// => { plan, policyRules, levelPolicies, agentOverrides, settings }

// List all saved policies
const policies = await platform.listSavedPolicies('org_123');

API

createPlatformStorage(config)

Creates a platform storage instance. Auto-migrates the schema on first call (idempotent).

interface PlatformStorageConfig {
  pool: PgPoolLike;       // Any pg.Pool-compatible client
  autoMigrate?: boolean;  // Default: true
}

Returns a PlatformStorage object with:

Method	Description
loadOrgSettings(orgId)	Load org settings (returns defaults if no row)
saveOrgSettings(orgId, update)	Upsert org preferences
loadPolicyTiers(orgId)	Load resolved policy tiers for enforcement
listSavedPolicies(orgId)	List all saved policies for an org
migrationsApplied	Number of migrations applied on init

runMigrations(pool)

Run migrations manually (useful if autoMigrate: false).

import { runMigrations } from 'governance-sdk-platform';

const applied = await runMigrations(pool);

Schema

The migrator creates and maintains these tables:

Table	Purpose
org_settings	Per-org plan, preferences, scoring/detection config
saved_policies	Versioned policy definitions with rules, level/agent assignments
_platform_migrations	Migration tracking (internal)

Works with any pg-compatible client

PgPoolLike accepts anything with a .query() method -- pg.Pool, @neondatabase/serverless, connection poolers, etc.

import { Pool } from '@neondatabase/serverless';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const platform = await createPlatformStorage({ pool });

Part of the Governance SDK

Package	Purpose
governance-sdk	Core SDK -- policy engine, scoring, injection detection, and first-class adapters for the major JS agent frameworks
governance-sdk-platform	This package -- PostgreSQL storage layer

License

MIT