Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Status: 📝 Planned
Spec Reference: PF-43 Tenant Resource Quotas
Last Updated: 2026-03-14

​
Purpose

PF-43 provides tenant resource quotas and usage tracking (storage, API calls, users, custom objects, workflow executions). This document captures integration points: PF dependencies (PF-01, PF-04, PF-10, PF-11, PF-42), the event published on quota violation, and the platform layer consumed by clients and edge functions.

​
PF Dependencies

DependencyUseType
PF-01 (Organizations)Quotas and usage scoped by organization_id; org timezone for day/month resetData / tenant context
PF-04 (Audit Logging)All quota configuration changes auditedPlatform integration
PF-10 (Notifications)Violation alerts when soft/hard limits exceededEvent consumer
PF-11 (Document Management)Storage quota tracking (total storage per org)Platform / data
PF-42 (Rate Limiting)API call quota tracking (when implemented); temporary interfaces until PF-42 landsEvent / platform

​
Event Contract: pf_quota_violated

Event: pf_quota_violated (canonical identifier)
Publisher: PF-43 (Quota enforcement framework)
Subscribers: PF-10 (Notifications), PF-48 (Security Event Monitoring — future)
Status: 📝 Planned

​
Purpose

Notify platform and organization admins when a quota soft or hard limit is exceeded so they can respond and adjust usage or quotas.

​
Trigger Conditions

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

​
Payload Schema

Canonical payload uses snake_case. Envelope fields (event_id, occurred_at, source, spec_version) are required for idempotency and routing. eventVersion is required and represents the contract version for this event so producers and consumers can evolve safely (e.g. QuotaViolatedEvent.eventVersion).
FieldTypeRequiredDescription
event_idstring (UUID)YesUnique idempotency key; consumers MUST skip duplicates
occurred_atstringYesISO 8601 when the event occurred
sourcestringYesProducer identifier (e.g. pf-43-quota-enforcement)
spec_versionstringYesEvent contract version (e.g. semver 1.0.0) for evolution
event_versionstringYesContract version for pf_quota_violated (semver or string); required for safe evolution
organization_idstring (UUID)YesOrganization the quota applies to
resource_typestringYesOne of: storage, api_calls, users, custom_objects, workflow_executions
limit_typestringYessoft or hard
quota_valuenumberYesConfigured quota value
actual_usagenumberYesUsage that caused the violation
violated_atstringYesISO 8601 timestamp of the violation
TypeScript shape: 
/** 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

ConsumerActionStatus
PF-10Send notification to platform/org admins per alert threshold and mute settings📝
PF-48Ingest security event for monitoring/analytics📝

​
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

Entry added in CROSS_CORE_INTEGRATIONS.md: PF-43 → PF-10, PF-04, PF-11, PF-42, PF-01 (Event / Platform).