Tenant Resource Quotas & Usage Tracking — Integration

​

Purpose

​

PF Dependencies

​

Event Contract: pf_quota_violated

​

Purpose

​

Trigger Conditions

• After hard limit exceeded (operation blocked) or soft limit exceeded (warning; optional alert threshold).

​

Payload Schema

/** Canonical payload for pf_quota_violated event (PF-43). eventVersion required for contract evolution. */
export interface QuotaViolatedEvent {
  event_id: string;
  occurred_at: string;
  source: string;
  spec_version: string;
  event_version: string; // Required; contract version for pf_quota_violated (e.g. semver "1.0.0")
  organization_id: string;
  resource_type: 'storage' | 'api_calls' | 'users' | 'custom_objects' | 'workflow_executions';
  limit_type: 'soft' | 'hard';
  quota_value: number;
  actual_usage: number;
  violated_at: string; // ISO 8601
}

​

Consumer Actions

​

Platform Layer Usage

• Client: useResourceQuota hook for client-side quota checks (calls backend/edge that uses pf_check_resource_quota()).
• Server/Edge: pf_check_resource_quota(p_organization_id, p_resource_type, p_requested_amount) for server-side checks; writes to pf_resource_usage and pf_quota_violations via SECURITY DEFINER. Implementations MUST pin search_path in the function declaration (e.g. SET search_path = public or a tighter scope such as SET search_path = admin, pg_catalog) so untrusted schemas cannot shadow objects; this is required for security review.
• Storage usage: PF-11 integration for total storage per org (implementation detail in PF-43 tasks).
• API call usage: PF-42 integration when available; until then, temporary interfaces/stubs per spec Clarifications.

​

API Contracts

• Quota check (DB): pf_check_resource_quota(organization_id, resource_type, requested_amount) returns (allowed, remaining, reset_at, quota_id, limit_type) — reset_at is timestamptz for quota window reset.
• Frontend hook: useResourceQuota({ organizationId, resourceType, requestedAmount? }) returns state and checkQuota(amount?); see spec API Design.

​

Integration Matrix