Core Functions

API reference for createGovernance, register, enforce, recordOutcome, audit, integrityChain, score, and scoreFleet.

The primary API surface of governance-sdk — create an instance, register agents, enforce policies, record outcomes, and inspect state.

createGovernance(config)

import { createGovernance } from 'governance-sdk'

Creates a governance instance that holds your policy rules, registered agents, and audit trail. Export as a singleton so all agents share the same policy set.

createGovernance(config?: GovernanceConfig) => GovernanceInstance

GovernanceConfig fields (all optional):

Field	Type	Default	Description
`rules`	`PolicyRule[]`	`[]`	Policy rules evaluated on every `enforce()`. User priorities are clamped to ≤998.
`storage`	`GovernanceStorage`	in-memory	Storage adapter — swap for `createPostgresStorage(pool)` in production.
`defaultOutcome`	`"allow" \| "block"`	`"allow"`	Returned when no rule matches.
`serverUrl`	`string`	—	When set, `enforce()` / `register()` POST to this URL instead of running locally.
`apiKey`	`string`	—	Bearer token for remote calls. Required when `serverUrl` is set.
`timeout`	`number`	`30000`	Remote call timeout (ms).
`maxRetries`	`number`	`3`	Remote retry attempts on transient failure.
`fallbackMode`	`"allow" \| "block"`	`"allow"`	What to do when the remote API is unreachable after retries.
`onAuditError`	`(err) => void`	noop	Called when a fire-and-forget audit write fails.
`integrityAudit`	`{ signingKey; onFailure? }`	off	Enables HMAC-SHA256 hash chaining of EVERY audit event. See Audit Trail.

import { createGovernance, blockTools, requireApproval } from 'governance-sdk';

const gov = createGovernance({
  rules: [
    blockTools(['shell_exec', 'db_drop', 'fs_write']),
    requireApproval(['payment', 'data_access']),
  ],
  integrityAudit: {
    signingKey: process.env.AUDIT_SIGNING_KEY!,
    onFailure: 'allow',
  },
});

Note: Rules are evaluated in priority order (descending). User rules with priority >= 999 are clamped to 998 so the kill switch wins unconditionally.

gov.register(agent)

Registers an agent with the governance instance. Computes a 7-dimension governance score instantly and assigns a level (L0 through L4).

gov.register({
  name, framework?, owner, version?, description?,
  tools?, permissions?, channels?,
  hasAuth?, hasGuardrails?, hasObservability?, hasAuditLog?,
  metadata?, id?,
}) => { id, score, level, status, assessment }

const result = await gov.register({
  name: 'sales-agent',
  framework: 'mastra',
  owner: 'sales-team',
  tools: ['email_draft', 'crm_update', 'calendar_book'],
  hasAuth: true,
  hasGuardrails: true,
  hasAuditLog: true,
});

// result.id         → "agent_a1b2c3..."
// result.score      → 68
// result.level      → 3
// result.status     → "approved"

Warning: Self-reported booleans (hasAuth, etc.) are accepted at face value. Cross-check callers' claims against scanRepoContents() from governance-sdk/repo-patterns. See Governance Scoring for the pattern.

gov.enforce(ctx)

Evaluates all matching policy rules before a tool call executes. Returns an EnforcementDecision. Every call is automatically recorded in the audit trail (and HMAC-chained when integrityAudit is set).

gov.enforce(ctx: EnforcementContext)
  => EnforcementDecision { blocked, outcome, reason, ruleId, maskedText?, evaluatedAt, rulesEvaluated }

Notable EnforcementContext fields:

Field	Populated by	Read by
`agentId`, `action`, `tool`, `input`	always	every condition
`recentActionCount`	host	`rateLimit`
`sessionTokensUsed`	host	`tokenBudget`
`identityVerified`, `identityCapabilityMatch`	host (after Ed25519 verify)	`requireSignedIdentity`
`mlInjectionScore`, `mlInjectionCategories`	host (after ML classifier)	`mlInjectionGuard`
`outputText`, `outputTokenCount`, `executionDurationMs`	host (postprocess)	output rules

const d1 = await gov.enforce({
  agentId: result.id,
  action: 'tool_call',
  tool: 'shell_exec',
});
// d1.blocked  → true
// d1.outcome  → "block"

Also available: gov.enforcePreprocess(ctx) and gov.enforcePostprocess(ctx) for stage-scoped evaluation.

gov.recordOutcome(outcome)

Closes the decision → outcome loop. Call after the tool / LLM returns so the audit chain covers what actually happened, not just the permission check.

gov.recordOutcome(outcome: ActionOutcome) => Promise<AuditEvent>

interface ActionOutcome {
  agentId: string;
  tool?: string;
  action?: string;
  success: boolean;
  durationMs?: number;
  output?: unknown;
  error?: string;
  tokensUsed?: number;
  policyRuleId?: string;
  detail?: Record<string, unknown>;
}

For most callers, the one-line helper is easier:

import { runWithOutcome } from 'governance-sdk';

const result = await runWithOutcome(
  gov,
  { agentId, tool: 'search' },
  async () => await searchApi.query(q),
);

gov.audit

gov.audit.log(event)     // writes an audit event (chained when integrityAudit is on)
gov.audit.query(filters) // queries the audit trail
gov.audit.count(filters) // counts matching events

gov.integrityChain (opt-in)

Populated only when integrityAudit: { signingKey } was passed. Exports the HMAC-chained events for offline verification.

gov.integrityChain?.export(filters?) // Promise<IntegrityAuditEvent[]>
gov.integrityChain?.stats()          // { latestSequence, latestHash, algorithm }

import { verifyAuditIntegrity } from 'governance-sdk/audit-integrity-verify';

const chain = await gov.integrityChain!.export();
const { valid, brokenAt, breakDetail } = await verifyAuditIntegrity(
  chain,
  process.env.AUDIT_SIGNING_KEY!,
);

gov.score / gov.scoreFleet

await gov.score(agentId)  // GovernanceAssessment | null
await gov.scoreFleet()    // { assessments, summary }

gov.addRule / gov.removeRule

Mutate the policy set at runtime. User rules with priority >= 999 are clamped to 998 to preserve the kill-switch invariant.

gov.eval (in-memory)

Submit results from your adversarial harness (inspect-ai, PyRIT, Garak). Durable eval storage lives in Lua Governance Cloud.

gov.eval.submit(result: EvalResult)
gov.eval.getResults(agentId: string)
gov.eval.traces // TraceCollector

Remote mode (when serverUrl is set)

gov.connect()                              // { connected, mode, latencyMs }
gov.status()                               // cached last status
gov.waitForApproval(id, { timeoutMs })     // "approved" | "denied" | "expired" | "timeout"