> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mandala.md/llms.txt
> Use this file to discover all available pages before exploring further.

# Data model and security boundaries

> Workspace ownership, major database domains, versioning, RLS, and private workflow records.

Mandala stores durable product state in Supabase Postgres. The schema is migration-owned, tenant-scoped, and designed so that a run can be reconstructed from the versions, evidence, decisions, and receipts that existed at the time.

## Tenant model

`companies` are the workspace boundary. `company_memberships` and related event tables bind users to one of these roles:

* `owner`
* `admin`
* `approver`
* `member`
* `viewer`
* `agent`

Most Mandala records carry `company_id`. Row-Level Security and role-checked database functions enforce tenant isolation. Managed CLI credentials are additionally bound to an authorized user, company, and session.

The original `pages`, `collections`, `collection_fields`, `collection_rows`, and `collection_views` tables remain for the web workspace, but agent workflows use the company-scoped control-plane model below.

## Core domains

### Identity and policy

| Tables                                                     | Purpose                                           |
| ---------------------------------------------------------- | ------------------------------------------------- |
| `companies`, `company_memberships`                         | Workspace identity and user roles                 |
| `company_membership_events`, `company_principals`          | Membership history and non-human principals       |
| `company_approval_policies`, `company_capability_policies` | Approval and capability rules                     |
| `company_policy_decisions`                                 | Auditable policy outcomes                         |
| `company_invitations`, token and event tables              | Invite, inspect, accept, resend, and revoke flows |

### Connectors and capabilities

| Tables                                                          | Purpose                                               |
| --------------------------------------------------------------- | ----------------------------------------------------- |
| `connector_definitions`, `connector_definition_versions`        | Stable connector identity and immutable versions      |
| `capability_definitions`, `capability_definition_versions`      | Versioned read, propose, and execute contracts        |
| `connector_capability_offerings`                                | Capabilities supplied by a connector version          |
| `company_connector_installations`                               | Workspace installations and configuration             |
| `company_connector_capability_grants`                           | Workspace grants                                      |
| `company_connector_health`                                      | Health, freshness, and compatibility                  |
| `external_sources`, `external_records`, `external_record_links` | Normalized provider snapshots and relations           |
| `workspace_data_catalogs` and mapping tables                    | Dataset profiles and versioned skill-to-data mappings |

### Agents and lifecycle

| Tables                                                       | Purpose                                          |
| ------------------------------------------------------------ | ------------------------------------------------ |
| `agent_workflows`                                            | Installed agent identity and source              |
| `workflow_binding_snapshots`, `workflow_capability_bindings` | Immutable compiled capability bindings           |
| `workflow_activations`, `workflow_activation_events`         | Active version history                           |
| `agent_runtime_states`, `agent_lifecycle_events`             | Draft, ready, active, paused, and disabled state |
| `agent_tool_definitions`, `agent_action_definitions`         | Registered tools and controlled action contracts |
| `agent_signal_*` tables                                      | Changed-record triggers and dispatch history     |

### Runs, review, and execution

| Tables                                                 | Purpose                                                                     |
| ------------------------------------------------------ | --------------------------------------------------------------------------- |
| `workflow_runs`, `workflow_events`                     | Durable run identity and event stream                                       |
| `workflow_items`                                       | Inbox records                                                               |
| `workflow_context_packets`                             | Captured sources, facts, freshness, warnings, and Context Engine provenance |
| `workflow_recommendation_runs`                         | Recommendation and confidence output                                        |
| `workflow_evidence_snapshots`                          | Source references, assumptions, and evidence                                |
| `workflow_action_drafts`                               | Proposed payload and edit policy                                            |
| `workflow_decisions` and outcome tables                | Human decisions and outcomes                                                |
| `workflow_execution_tokens`                            | Short-lived authorization for an exact approved draft                       |
| `workflow_action_attempts`, `agent_execution_receipts` | Idempotent execution and provider outcomes                                  |
| `workflow_audit_events`                                | User, agent, and system history                                             |

Sensitive decision receipts, queue snapshots, parser leases, and compiled-persistence receipts live in the `workflow_private` schema rather than the public API surface.

### Context, memory, and operations

Context indexing uses workspace settings, versioned policy, outbox, job, ledger, event, audit, operation-control, and tombstone tables. These separate the source record from the derived external index and support retry, cleanup, and reconciliation.

Additional tables cover governed memory candidates, feedback, follow-ups, escalations, monitoring events, evaluations, promotion checkpoints, provider usage, email delivery, and account deletion.

## Version and hash strategy

Mandala avoids mutable meaning by persisting:

* skill source and compiler digests;
* connector, capability, schema, policy, mapping, and lifecycle versions;
* expected versions on decisions and executions;
* context and evidence snapshots;
* idempotency keys; and
* request and response hashes on execution receipts.

A stale client or changed catalog receives a conflict instead of silently applying an old decision to new data.

## Database boundaries

RLS is necessary but not the only boundary. Security-sensitive transitions use role-checked SQL functions, compare-and-set versions, or RPCs that return safe projections. Anonymous callers cannot read workflow detail through the underlying tables.

Schema changes belong in `supabase/migrations`. After local migrations, regenerate the typed client:

```bash theme={null}
pnpm db:types
```

Database authorization and behavior tests live in `supabase/tests` and run with:

```bash theme={null}
supabase test db
```