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

# Policies

> Control viewing, creating, editing, and deleting each kind of Pane content.

## Sources

Docs: [Panes](/ponder/parables/pieces/panes), [Perceptions](/ponder/parables/pieces/perceptions), and [Preferences](/ponder/parables/pieces/preferences).

Web App: Select a Pane and open **Policies**. For a SQL Plot, choose **Source** or **Data**.

## Structure

Policies answer two questions: **which action** and **on which content**.
A Pane has a versioned Policies document. Its React code receives resolved
decisions separately. Saved Preferences cannot replace the rules or their
app-owned attachments.

| Target        | What it governs                                                                        |
| ------------- | -------------------------------------------------------------------------------------- |
| `preferences` | Application values and permission to use the Pane. On a SQL output, the returned data. |
| `pane`        | Saved React source.                                                                    |
| `perception`  | The Pane's native declaration.                                                         |
| `plots`       | Saved SQL source and Report schedules.                                                 |
| `palette`     | CSS definitions and saved CSS instances.                                               |
| `policies`    | The policy settings and their attachments.                                             |

`view` and `edit` can name all six targets. `create` and `delete` name
`preferences`, `pane`, `plots`, or `palette` for their saved instances. Required Perception, Policies, and Palette parts are
created with their Pane; replace their contents through `edit` rather than
removing and recreating them independently.

## Schema

All four action objects and `filters` are required. Each target is independent:
a missing or null target grants nobody access. An empty permission array also
grants nobody access, including a Primary participant. Nothing inherits from
another action or target.

```yaml theme={null}
view:
  preferences: { participantsWith: { participantPermission: [peeping] } }
  pane: { participantsWith: { participantPermission: [primary] } }
  perception: { participantsWith: { participantPermission: [primary] } }
  plots: { participantsWith: { participantPermission: [primary] } }
  palette: { participantsWith: { participantPermission: [primary] } }
  policies: { participantsWith: { participantPermission: [primary] } }
create:
  preferences: { participantsWith: { participantPermission: [publishing] } }
  pane: { participantsWith: { participantPermission: [publishing] } }
  plots: { participantsWith: { participantPermission: [publishing] } }
  palette: { participantsWith: { participantPermission: [publishing] } }
edit:
  preferences: { participantsWith: { participantPermission: [publishing] } }
  pane: { participantsWith: { participantPermission: [publishing] } }
  perception: { participantsWith: { participantPermission: [primary] } }
  plots: { participantsWith: { participantPermission: [publishing] } }
  palette: { participantsWith: { participantPermission: [publishing] } }
  policies: { participantsWith: { participantPermission: [primary] } }
delete:
  preferences: { participantsWith: { participantPermission: [primary] } }
  pane: { participantsWith: { participantPermission: [primary] } }
  plots: { participantsWith: { participantPermission: [primary] } }
  palette: { participantsWith: { participantPermission: [primary] } }
filters: []
```

`participantPermission` is an array of existing Parable permissions:
`peeping`, `pinging`, `publishing`, and `primary`. Matching any listed permission
allows that action. Broader participation includes its subordinate permissions.
Unknown fields, targets, permissions, and repeated permissions are refused.

## Services

To read settings, the Pane SDK provides `preferences.readPolicies`; the
generated Workspace API names this operation `readParablePolicies`.
Select a Pane, optionally a saved source, and whether you want its SQL output
settings. You do not need to inspect private source or binding configuration
just to discover the governing Policies.

```ts theme={null}
import { key, preferences } from '@parable/example/scenarios';

const state = await preferences.readPolicies({
  paneKey: key,
  sourcePreferenceId: null,
  data: false,
});
```

The result identifies the selected definition with `policyKey` and
`policyRowId` and `policyVersion`, with visible settings in `value` and decisions
in `resolved`.
`value` is null when `view.policies` is denied. `edit.policies` does not grant
permission to view settings. If you can edit hidden settings, enter a complete
replacement; saving does not require access to the old rules.

Save in the **Policies** editor. Publishing mode saves the definition to
**Changes**; publishing activates the reviewed rules. Personal mode saves to
the working definition directly. A changed definition refuses a stale save.
Keep the draft, reload the target, and review it before saving again.
YAML comments and formatting are not part of the stored settings. Switching between Current and a Report preserves unsaved Policies edits.

## Security

Creation is authorized by the existing destination. Submitted Policies cannot
approve their own installation. Replacing settings or changing their attachment
uses the previously saved `edit.policies` authority and revision checks.
Before a new Pane first activates, its source and Policies can be edited within the
authorized draft using the current enclosing `edit.perception` permission.
An additional draft Policy on an existing Pane needs that Pane's current
`edit.policies` permission. Draft settings cannot grant or revoke those authoring
rights, and publishing a revocation takes effect for subsequent draft edits.
An existing or retired Policy identity always retains its current authority.
Before a new Plot activates, its SQL and source/output Policy references can be
changed using the current enclosing `create.plots` permission. Once activated,
changing either reference needs its prior `edit.policies` permission.
An active Plot's declared source Policy applies before its first SQL
implementation, including when an internal source lookup needs repair.
Publishing an unchanged Personal definition as its first Version preserves its
existing rules without asking for permission to replace them. A Delivery that
changes rules still needs the receiving app's current Policy-edit permission;
the incoming Version cannot supply that permission.
Live membership, ownership, or sharing data can affect access when the
published rules explicitly use it. Arbitrary Preference JSON is not a Policy.

`view.plots` governs SQL source inspection; `view.pane` governs React source
inspection. A permitted Pane can render without
granting source-editor access. Rendering React or CSS delivers executable code
or styles to the browser, so this distinction does not promise secrecy for those
assets. SQL can remain on the server while permitted readers consume its output.

SQL **Data** settings use `view.preferences` and row filters. SQL output stays
read-only even if its settings contain create, edit, or delete grants. Its
source inspection settings are independent.

Filters further restrict values or rows; they never grant an action. For example,
a SQL output can retain only rows belonging to the authenticated email:

```yaml theme={null}
filters:
  - "original_user_email = request_principal()['email']"
```

Preference filters receive `record` metadata and a typed `value`; SQL-output
filters receive result columns. Conditions do not authorize replacement of the
Policies document itself. Unsupported or invalid conditions refuse execution.
See [Execution context](/ponder/parables/execution-context) for current filter
and Report limits.

## Reference

Generated Workspace API reference for this Piece:

* [Read the Policies in force](/protocols/reference/web-api/parable-authoring-read-parable-policies)
* [Edit a Piece in Personal mode](/protocols/reference/web-api/parable-authoring-save-workspace-parable-primary)
* [Edit a Piece in Publishing mode](/protocols/reference/web-api/parable-authoring-save-workspace-parable-proposal)