Execution context

Sources

Docs: Panes, Plots, Policies, and Preferences. Web App: Refresh, at the top right of the Parable editor, chooses a data reading: Latest (the API’s Current) or one stored Report run, which the UI calls a Refresh. It lists every stored run; a run that is not complete carries its status and has no rows to read. The choice rides in the address as refresh. Pane code reads the host’s coordinates through getParableContext(). In Publishing mode, View as, beside it, previews the Parable as one member of its Workspace. In Peeking or Pinging mode, a person with Publishing or Primary sees View as turned off, and its hint says “Switch to Publishing mode to view as a colleague.” A person with Pinging or Peeking sees no View as. While a preview runs, the page shows the colleague’s participation and mode, and View as stays on so you can end it. When a read as the colleague fails, the page says what failed and keeps Exit View as, which opens the page as you. When the preview ends, the page opens as you, as a fresh open does. It does not open a Patch, a change item, a Version, a Release or a Problem that the address named for the colleague. This is true for each way out: Exit View as in the page header, Exit View as on the failure page, a reload, and a read that finds that the preview ended. A lost sign-in still shows the sign-in page. A read that fails on the network, before the server answers, still shows the app’s error page with no Exit View as.

Structure

A definition identifies code and schema. A data reading identifies Current data or one Report run. React and SQL use the same context so a page can display an older Report with a newer compatible definition without confusing the two. Only patch is different: Pane code reads it, and SQL reads it as null (The Patch on screen).

import { getParableContext } from '@parable/example/queryBuilder';
const context = getParableContext();

The host supplies the authenticated identity. Selecting another actor’s scenario changes an input; it does not impersonate that actor. A View as preview is the one case where the context names someone else, and the server, not the page, decides it (see View as).

Schema

Field	Meaning
`workspace.workspaceId`	Workspace membership and data boundary.
`parable.parableId`, `parable.handle`	The application being used.
`parable.revision`	A published commit, or a draft ref and its revision.
`data`	`CURRENT`, or `REPORT_RUN` with a specific `reportRunId`.
`principal`	The actor whose authority executes the operation; always present.
`actor`	The initiating actor, when there is one. Scheduled work has no human initiator.
`raci`	Current Parable participation for presentation.
`permissions`	Always an empty array. It does not supply grants.
`mode`	Personal/published presentation state, not permission.
`subject`	On a Platform Parable’s Pages only. In its tab, the Parable on screen beside the tab. On its own page, the Parable that its Page chose (The subject). Null everywhere else.
`patch`	The Patch on screen, and what readers see while it waits (The Patch on screen). Set only for Pane code on a Workspace Parable’s page. Null on a Release, where no Patch is on screen, and in SQL.

A context names either a commit or a ref with revision, never both. props.policies separately supplies resolved Pane decisions; context fields and displayed capability booleans are not credentials.

The Patch on screen

A Pane can say a true draft notice from patch. It is null when the person reads a Release, a Personal Parable or a Parable with no Patch on screen. Only the Workspace Parable page sets patch, for its Pages and its Piece editor. Admin Ponder, a Platform Parable’s tab and a Pane preview in a Ponder reply leave it out. The server builds the context of SQL and of a stored Report run, and it does not set patch. So parable_context()['patch'] is null, also on a Patch. Test the field with if (!patch), as the example below does.

Field	Meaning
`readersRelease`	The Release that readers on Newest see now, as the app labels it, such as `v1.4` or `v1.4+2` on a copy. Null before the first Release.
`seenByOthers`	True when a person other than the reader can open this Patch.

Every participation, Peeking to Primary, can open a Patch that is not Pocketed. A Pocketed Patch opens only for the person who started it. So seenByOthers is false only when the reader started the Patch and either the Patch is Pocketed or the reader holds the only seat. A seat that names the Workspace or a Role counts as other people. The field names who can open the Patch. It grants nothing.

function DraftNotice() {
  const patch = useParableContext().patch;
  if (!patch) return null;
  const who = patch.seenByOthers ? 'you and the people with a participation' : 'only you';
  const readers = patch.readersRelease ?? 'nothing';
  return <p>Draft changes: {who} see these. Readers see {readers} until you publish.</p>;
}

The subject

A Platform Parable shows as a tab in the Ponder header of every Parable. The tab knows the subject: the Parable on screen beside it. Pane code reads it as getParableContext().subject. useParableContext(), from the same module of the Page or Pane, gives the same context as a React hook and renders again when it changes, so the tab follows the Parable beside it:

import { useParableContext } from '@parable/proofs/proofsTab';

export default function ProofsTab() {
  const subject = useParableContext().subject;
  return <p>{subject ? subject.observedRevision.parableId : 'No Parable beside this tab'}</p>;
}

Field	Meaning
`rootRefId`	The subject’s line in this Workspace. It can be a Parable’s own line or a Workspace’s copy.
`observedRevision`	The Release on screen, or the Patch’s working revision.
`versionRef`	The Release, when the person reads one. Null for a Patch or a Personal Parable.
`proposalRef`	The Patch, its observed working revision, and its retained Changes revision when available.
`data`	`CURRENT` for Latest, or `REPORT_RUN` with the chosen Refresh.
`pageRef`	The Page on screen, at the observed revision.
`pieceRef`	The Piece in focus: a Page, Pane, Plot, Palette or Package.

The observed working revision and the retained Changes revision are different. Propose seals the Changes revision. A clean move onto a newer Release keeps that revision, so reviews still refer to the same Changes. Pocket and Restore remove the current review address until the Patch is proposed again. A Pending or Pocketed Patch without retained Changes stays a Patch, but subjectKey() returns null. When Propose succeeds, an open Platform Parable tab receives the retained Changes address without a reload or a replacement Page. A refused or rolled-back Propose gives the Patch no new review address. The server checks the current subject before it selects rows about the Patch. A client-supplied revision never grants access or selects a different review address. A Personal Parable has no Patches, so its subject is the Parable as saved. When the person picks another Release, Patch, Refresh or Piece, the tab gets a new context, and its Plot reads run again. The subject is a coordinate. It never grants access. The tab reads and saves at the person’s own participation on the Platform Parable’s copy. The participation mode that the person picked on the Parable beside it does not narrow the tab. A Plot read and a query from the tab carry the subject, and the server checks it on each request. It refuses the read, as if the Parable did not exist, when the person cannot read the subject:

a Parable where the person has no seat;
a Release that is not on the subject’s line, or a revision that the line does not have;
a Pocketed or closed Patch that another person started. The person who started it reads it, but not under View as. A Pocketed Patch has no review address, so that person reads no row about it until it is proposed again;
a Patch that the viewed person cannot read, under View as.

Every participation, Peeking to Primary, reads the Pages of a subject that it can read and every Patch that is not Pocketed or closed. The tab’s Plots read the subject’s name, its Patch, its Pieces and the Patch’s Changes through the subject.* relations (Read the Parable beside a Platform Parable’s tab). They list what the person’s own participation on the subject lists. Under View as on the Parable beside the tab, the tab sends that preview with its reads, and the server checks the subject and builds the relations as the viewed person. The tab itself still reads as you: its Plots and Panes use your own seat and Policies, never All data access, and its SQL reads only its Plots and the subject.* relations. Ponder’s current view, which a Message records, is the same subject with no Page. On its own page, a Platform Parable reads beside the Parable that its Page chooses (PARABLE-8460). chooseSubject(rootRefId), from the same module, takes that Parable’s line in this Workspace, as workspace.parables.root_ref_id gives it. chooseSubject(null) reads beside none. The subject then names that Parable at the Release that its line runs now, and a Personal Parable as it is saved. The page gets the new context, and its Plot reads run again.

import { chooseSubject } from '@parable/proofs/proofsTabs';

// `row` is one Parable in the Page's list, read from `workspace.parables`.
function choose(row: { root_ref_id: string }) {
  void chooseSubject(row.root_ref_id);
}

The choice stays in page memory: a reload reads beside none. Only a Platform Parable’s own page chooses, because Parable staff write its code. Any other Page, and a tab, whose subject is the Parable on screen, is refused. The server checks a chosen subject on every read, as it checks a tab’s. The tab has an address: platform=<Parable id> opens that Platform Parable’s tab over the lens that focus names. A move to another lens closes the tab. The tab gets live updates of its own Platform Parable, as the Parable on screen does, so a row that another person saves in the tab shows with no reload. A saved Plot’s result.meta identifies the data that actually answered it. For example, Current can resolve to Report R42 produced by definition v6 while meta.context still describes the consuming v7 definition. The returned reading identifies R42; changing the definition label would not make its data compatible.

Services

The Pane SDK binds requests to the host-selected definition and reading. It resolves source identities on the server, so a named SQL read does not require downloading private SQL. It also resolves explicit values and policy decisions; hidden or unavailable items return individual refusals without discarding their permitted siblings. SQL reads the same context:

SELECT
  parable_context()['principal']['actorId'] AS execution_actor,
  parable_context()['parable']['revision']['commitId'] AS definition;

A query without a Parable definition can inspect its verified principal:

SELECT request_principal()['actorId'];

principal.email, when present, comes from the authenticated account. Neither Provider identity matching nor an application parameter can replace it. Unknown context fields fail planning. parable_context() requires a trusted Parable context; it does not invent a default identity. When definition, reading, or authority changes, the host replaces the relevant bindings and ignores responses from the earlier selection. Draft requests can carry expectedRefRevision; a stale revision conflicts rather than running old code with a new label. Proposing a set of Changes leaves the line’s revision where it is, so a reader of the line is never refused because someone else proposed their set. A Plot read that pins no revision reads the definition as it stands: when a publish or a save moves the ref while it runs, Parable reads it once more at the new revision and answers from that, rather than refusing it. That covers each revision check, including PA-AU-002, and the check that the context of the read still holds. It reads again once only. A Pane resolution (panes.resolve) that is refused with PA-AU-002 does the same: the host fetches its newest context and resolves once more under it. The editor’s Policies decisions fetch the newest context once for each stale context, and ask again when it arrives. Without this, every later resolution sent the same stale revision and was refused until the page reloaded (PARABLE-7840). Separate Current queries remain live and do not promise one atomic snapshot across the whole page. A Plot read answers with the versions of what it read: the Plot, the Plots it reads and the Panes it binds (pieceVersions). The next read of that Plot sends them back (expectedPieceVersions) in place of expectedRefRevision. Parable refuses that read only when one of those Pieces changed or was removed, with PA-AU-077, which names them. A change to any other Piece of the set of Changes refuses no read. After a proposal, a Page reads again only the Plots whose pieceVersions name a changed Piece. When a read cannot name the Panes it binds, because its SQL reads workspace.preferences, it answers with no pieceVersions, and the next read pins expectedRefRevision. Positional SQL parameters remain separate from context. Omitting an override uses saved values; an explicit array replaces them. Existing Report data keeps its captured inputs and refuses a different override. Parameters cannot change the requester, Workspace, definition, or policy decisions. Ponder’s Pane pictures use a captured reading with the requester’s verified context, Pane references, and policy decisions. They can read only the captured settings; they cannot run live SQL or write values. A missing or denied required reference makes the picture unavailable. The picture does not invent an actor, version, or permission to complete a render.

Security

Workspace surfaces check an active membership on a live account, Parable participation, and current Policies on the server. A deleted account keeps no access through a seat it still holds. Definition edits remain governed by the Policies of the Page or Pane they change. Plot planning, including preparation for publication, and live SQL execution require the account’s active Workspace membership. Definition access alone does not authorize those operations. A participation on a Parable cannot replace membership.

View as

A participant who holds Publishing or Primary on a Parable, and Build Parables in its Workspace, can preview it as one active member of that Workspace. A preview never shows anything the previewer could not read themselves:

The person must hold a seat on the Parable, at or below the previewer’s. A member with no seat cannot be chosen.
The preview runs as that person: principal, actor and raci name them, their seat decides every Page’s and Pane’s Policies, and request_principal() and filter Policies read them. Their own settings stay theirs and are not shown; the settings shared for This Parable follow their Policies. A Page’s or Pane’s grant that names them or a Role they hold does not apply in the preview. A filter Policy row that names them or their Role does apply, since it can narrow what they read; your own filter Policies apply beside theirs.
viewAs names the previewer while a preview runs, and is null otherwise. Every change is refused during a preview, so a Pane shows read-only controls when context.viewAs is set.
Provider data must pass both people’s Provider Policies. Parable evaluates the person’s rules and the previewer’s own and keeps only rows both admit, so a preview cannot read a source the previewer could not.
The definition on screen stays the previewer’s: their draft or the Version they chose. There are two exceptions. The page does not open the previewer’s own Pocketed Patch, because the colleague may not open it. And a fresh open does not land on the previewer’s own Patch.
SQL run inside the Parable, from a Lab Page or Ponder’s SQL tool, reads only its Plots, whoever may edit them (Plots).

The menu lists the Workspace’s members who hold a live account: a deleted account is left out even while its membership stays active. Each person is named by their name, or their email when they have none, with their seat. Someone whose seat is above yours, or who holds none, cannot be chosen, and shows Not Permitted when you point at or tap them. A hint on the row gives the reason, for example “Charlie Brown holds no participation on this Parable.” or “Ada Primary holds Primary, above your Publishing.” A screen reader reads the same reason as the row’s description. The menu also lists the people invited to the Workspace who have not joined yet, while their invite is open: not expired and not revoked. They show greyed out and labelled Invited, with the seat they hold when they join, and search finds them. Their reason says that they have not joined this Workspace yet. They cannot be chosen until they accept the invite and become active members. A preview starts for one person you choose, and Parable records who started it. Every read of the Parable then carries the preview, and Parable checks the previewer and the person again on each request. These reads of the previewed Parable answer as the person:

The Parable shows the person’s seat and the actions that the seat allows.
The list of Patches, Past Patches and one Patch show the actions that the person may take. The actions on a Patch shared through a Problem stay off.
The Parable’s contents show the sources that the person’s Policies show, and only the Code files that the person reads.
Each read that first checks that you may see the Parable checks that the person may see it.
Preferences, Panes, Plots and Probes read as the person.

An action shows only when you and the person both hold the Workspace permission it needs, and each read stays read-only. Other reads still read as you. Most of them first check that the person may see the Parable: the list of Releases, a Release’s contents and its modules, the index of the Pieces that other Patches changed, the participations, the catalog, the live sources, the Parable’s export, Piece diagnostics, Refreshes and Deliveries. A Patch’s contents read as you with no such check. These reads show no more than you may see. They can show more than the person may see. While the preview runs, the first four reads in that list answer as you when they read another Parable, such as a Platform Parable’s tab beside it. A preview ends after eight hours. Parable refuses a read that carries the preview when you lack Publishing or Primary, or Build Parables. It also refuses the read when the person holds no seat, or holds one above yours. Parable checks Build Parables from your permissions on that request, the same way it checks them to start a preview and to list the people. A request that carries the preview and changes anything is refused with PA-AU-044. A preview that is refused or over answers PA-AU-048. A read of Preferences, Panes, Plots or Probes that carries a preview for another Parable also answers PA-AU-048. Parable limits the person’s rank on the Parable to the previewed seat. Ponder, the model, never acts as the previewed person, and during a preview the editor turns Ponder off: the composer, and a running reply’s Stop, Steer and tool approvals, are disabled and say why. Those controls carry the preview and would be refused, while a new Message would run as the previewer with tools that edit. Messages you queued before the preview, and words you steered that the reply did not take, are held: they stay in the stack marked held, nothing is sent when the running reply ends, and you can still remove one. Exit View as to use Ponder again; the held Messages then go out in order. The host resolves request coordinates and strips untrusted context metadata before forwarding queries. A prepared query or page cursor cannot be reused under another actor, definition, or reading. Returned policy authorityKey values invalidate stale presentation; they do not authorize writes. A preview is governed by its actual inputs. A named Plot read also applies its Pane’s Policies. Source restrictions run before projection, joins, aggregation, and limits. A SQL alias cannot remove an attached rule. For example:

original_user_email = request_principal()['email']

An absent email does not match. A missing governing policy, unsupported evaluator, or invalid condition refuses access. A Provider Policy’s conditions receive that table’s columns; a filter Policy’s receive the result columns of the Plots it covers. The filter language accepts scalar conditions and ANDs them together; volatile functions, placeholders, aliases, and subqueries are refused. A scheduled Report executes as the Workspace’s explicit principal. It does not borrow the credentials of the person who made the schedule, and no Provider Policy narrows it. The Workspace usually holds no participation on the line, so the run takes its participation from Primary: it starts only while the person who holds Primary, or an active member of the role that holds it, may run the Report, and it computes with the rank of Primary. When the Workspace itself holds Primary, the run starts on the Workspace’s own Primary. Parable checks this when it captures each occurrence. Every participation check for the run reads the participation again, including the check of each Plot’s Pane Policies. Outside a run, the Workspace has only its own seats. Parable does not check permission to edit Parables again during a run: participation does not need that permission, and the check at each occurrence decides whether the next run starts. A manual Report uses the authenticated requester, whose authority is checked when execution starts. A requester whose Provider Policies narrow a Provider table the Report reads is refused, because the run would store only their rows for everyone who opens it.

Stability

Pipeline Current, which the Refresh menu calls Latest, reads the latest completed compatible Report. Selecting a Refresh keeps that exact run, and missing or incompatible data is refused. So is a stored Refresh that read a Provider table the reader’s Provider Policies narrow: it holds rows they can’t read. Report provenance stays separate from the selected code version and from current access. A historical result with a request_principal() Provider filter requires its captured principal, including email. A Provider filter using full parable_context() refuses Report materialization. Deleting or hiding a captured input can make the result unavailable. A Pipeline can read another Pipeline of the same Report. The run is a graph: a member runs after the members it reads and reads what they wrote in this run, under the same execution context. Members that read each other in a cycle are refused. A Pipeline can also read a Plot nothing stores, which the run reads as a view of its SQL (Plots read as views). A Pipeline of a Platform Parable is read from the Refresh of that Parable the run pinned when it was captured: the newest complete one that completed by the run’s AS OF time and fits the Release the run’s Version pinned (Reports). Only a Platform Parable can be read by other Parables (Parable Pool). Publish refuses a Plot that reads the Plot of any other Parable with PV_REF_002. A read in a Parable’s context binds a view of a Platform Parable at that Parable’s pinned Release, and a Pipeline of it from its newest Refresh with the columns of that Release, which a later Release can have made. It admits the rows as that Parable’s reader: the reader needs a seat on it and its Pane Policies. Ordinary SQL and previews can query completed Pipeline results with either Current or an explicit Report selection; an explicit Report selection reads what that run stored and never a view’s live rows.

Parables

Popular

​Sources

​Structure

​Schema

​The Patch on screen

​The subject

​Services

​Security

​View as

​Stability