> ## 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.

# Tenant Resource Quotas & Usage Tracking — Integration

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

**Status:** 📝 Planned\
**Spec Reference:** [PF-43 Tenant Resource Quotas](../../../specs/pf/specs/PF-43-tenant-resource-quotas.md)\
**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

| Dependency                  | Use                                                                                | Type                  |
| --------------------------- | ---------------------------------------------------------------------------------- | --------------------- |
| PF-01 (Organizations)       | Quotas and usage scoped by `organization_id`; org timezone for day/month reset     | Data / tenant context |
| PF-04 (Audit Logging)       | All quota configuration changes audited                                            | Platform integration  |
| PF-10 (Notifications)       | Violation alerts when soft/hard limits exceeded                                    | Event 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 lands | Event / 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`).

| Field             | Type          | Required | Description                                                                              |
| ----------------- | ------------- | -------- | ---------------------------------------------------------------------------------------- |
| `event_id`        | string (UUID) | Yes      | Unique idempotency key; consumers MUST skip duplicates                                   |
| `occurred_at`     | string        | Yes      | ISO 8601 when the event occurred                                                         |
| `source`          | string        | Yes      | Producer identifier (e.g. `pf-43-quota-enforcement`)                                     |
| `spec_version`    | string        | Yes      | Event contract version (e.g. semver `1.0.0`) for evolution                               |
| `event_version`   | string        | Yes      | Contract version for `pf_quota_violated` (semver or string); required for safe evolution |
| `organization_id` | string (UUID) | Yes      | Organization the quota applies to                                                        |
| `resource_type`   | string        | Yes      | One of: `storage`, `api_calls`, `users`, `custom_objects`, `workflow_executions`         |
| `limit_type`      | string        | Yes      | `soft` or `hard`                                                                         |
| `quota_value`     | number        | Yes      | Configured quota value                                                                   |
| `actual_usage`    | number        | Yes      | Usage that caused the violation                                                          |
| `violated_at`     | string        | Yes      | ISO 8601 timestamp of the violation                                                      |

**TypeScript shape:**

```typescript theme={null}
/** 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

| Consumer | Action                                                                         | Status |
| -------- | ------------------------------------------------------------------------------ | ------ |
| PF-10    | Send notification to platform/org admins per alert threshold and mute settings | 📝     |
| PF-48    | Ingest 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](./CROSS_CORE_INTEGRATIONS.md): PF-43 → PF-10, PF-04, PF-11, PF-42, PF-01 (Event / Platform).