Perceptions

Sources

Docs: Panes, Plots, Policies, and Preferences. Web App: Select a Pane or Page and open Perception to compare its declaration with the read-only platform base.

Schema

A Perception is a TypeScript .d.ts declaration exporting Perception and conforming to BasePerception. It describes allowed values and references. It does not select another actor’s saved data. A Perception is part of its Page or Pane: it is saved and versioned with the rest of that Page or Pane, and it is not a Piece of its own.

import type { BasePerception } from 'parable/foundation';
import type { Panes } from 'parable/panes';
import type { Generic, Temporal } from '@psgen/scalar-lib';

export interface Scenario {
  readonly id: Generic.Text;
  readonly name: Generic.Text;
  readonly startDate: Temporal.Date;
  readonly departments: readonly Generic.Text[];
}

export interface Perception extends BasePerception<Scenario> {
  readonly panes: {
    categories: Panes['workCategories'];
  };
}

Base field	Meaning
`type`	The Pane’s one type, supplied through `BasePerception<T>` and written in scalar-lib types: what the Pane shows and what people save on it. A type whose items people save is a named interface with an `id` field, `Generic.Text` or `Identity.UUID`, that names each item; its Preferences are rows of the type. `null` means no value; a Page’s type is always `null`. A Pane draws with no value from its parent when its type takes `null` (`T	null`), when it is a saved-data Pane, which shows its own rows, or when it owns Pane data. With no value,` props.primitive` is null, and its type takes null. Any other Pane asks for a value.
`panes`	Named, typed references to other Panes in this Parable. A Page or Pane composes other Panes only through these references. A reference declared with `Bound<Panes["x"], "field">` is a bound Pane that one field of this Pane’s type feeds.
`plots`	The Plots this Pane owns that need a contract of their own, each a `PlotContract<Input, Output>` that the host binds to the Plot’s identity. A Plot the Pane owns and does not declare returns rows of the Pane’s type, picked to the Plot’s columns (Plots). A Pane that declares this Pane can call these Plots through it without rendering it (`PaneComponent.plots`).
`data`	Optional. The Pane’s own data: a list of a named interface with an `id` field, such as `readonly data: readonly Concept[]`.
`preload`	Optional. `"all"` carries every saved item with the Pane’s load, for a bounded set such as categories; `"page"` carries one page, for rows that grow. Without it, rows load when the code reads them.
`fixedDefaults`	Optional, on a Pane whose type has an `id` field. `true` means no Me, team or This Parable row can change a Default row: a save of such a row with a Default row’s id is refused, and every read shows the Default row as it is (Fixed defaults).
`workspaceFiles`	Optional. `true` means the code of this Page or Pane reads the Workspace’s files with `files.list({ from: 'workspace' })` and `files.read`. Only a person who can view the Workspace’s files saves a Perception that declares it (The Workspace’s files).
`Identity.Recipient[]` field	Optional, in the Pane’s type. One top-level list of `Identity.Recipient`, with an `Identity.Signer` field, makes each row a row for the people it names: only its signer and those people read it (Rows for named people).
`overrides`	Optional, on a Plot Pane. `true` lets the Pane take per-actor rows by id that change only the reader’s own view of its Plot’s rows, never a Refresh, a Pipeline or a Report.
`proposes`	Optional. The Piece kinds the Pane’s code may propose, such as `readonly ["plot"]`. A Pane may always propose changes to its own data and to the data of the Panes it declares in `panes`.
`policies`	Fixed resolved Policy decisions supplied by the host.
`providers`	Optional, on the Home Page only. The Providers the Parable reads, as named groups (Providers a Parable reads).
`contributes`	Optional, on the Home Page of a Platform Parable only. The Pieces that the Parable gives to places in the product (What a Platform Parable gives).

type (through BasePerception<T>), panes, plots and policies are required. Extra root fields and index signatures are refused. preferences, primitive, Live<> and Versioned<> are from before Pane types; each is a Warning & Error with what to write instead. A Pane has one type, so a Pane that shows Meetings never keeps a chosen window of its own. The window is a row of a saved-data Pane of its own, which the Meetings Pane declares and reads with panes.window.preferences.get(id):

export interface Window {
  readonly id: Generic.Text;
  readonly days: 7 | 30 | 90;
}
export interface Perception extends BasePerception<Window> {
  readonly preload: 'all';
  readonly panes: {};
}

Declare Plots through BasePerception<Type, DeclaredPlots> or a structured plots field. The resolved policies contract cannot be replaced or narrowed.

Kinds of Pane

The type says which kind of Pane a Pane is:

Kind	Example	SQL	Data
Plot Pane	Meetings	its Plots	the rows of its undeclared Plot, of the Pane’s type, and each declared Plot’s rows; per-actor override rows by id only with `overrides`
Bound Pane	Meeting attendees	none	one field of its parent’s row, as `props.value`, under its parent’s Policies
Saved-data Pane	Categories, a date range, audiences, switches	none	its Preferences: rows of its type, for each actor
Layout Pane	a section	none	none

A new kind of thing is a new Pane, and many things of one kind are rows. A field becomes a bound Pane of its own only when it needs its own controls; other fields use the design system’s default control for their type. Any Pane can also own data of its own.

Bound Panes

A bound Pane shows one field of its parent’s row. The parent declares it in panes with Bound, naming the field:

import type { BasePerception, Bound, Ref } from 'parable/foundation';
import type { Panes } from 'parable/panes';
import type { Generic, Temporal } from '@psgen/scalar-lib';
import type { Person } from 'parable/panes/<People Pane ID>/perception';

export interface Meeting {
  readonly id: Generic.Text;
  readonly title: Generic.Text;
  readonly starts: Temporal.DateTime;
  readonly attendees: readonly Ref<Person>[];
}

export interface Perception extends BasePerception<Meeting> {
  readonly panes: { attendees: Bound<Panes['meetingAttendees'], 'attendees'> };
}

The field must be in the parent’s type, with the bound Pane’s type, and a field feeds one Pane; anything else is bound-field. The bound Pane has no SQL. It takes the value from its parent’s row as props.value, so it needs no read of its own, and it resolves once for each Page. It uses its parent’s Policies and cannot narrow them yet, so its own Policies stay at the defaults (bound-policy).

Pane data

A Pane can own typed data that the Parable owns, such as an ontology, the descriptions of Provider tables, or the rules of a mapping. Declare it as a list of a named interface with an id field:

import type { BasePerception, Ref } from 'parable/foundation';
import type { Generic } from '@psgen/scalar-lib';

/** One concept of the ontology. */
export interface Concept {
  readonly id: Generic.Text;
  readonly label: Generic.Text;
  readonly parent: Ref<Concept> | null;
}

export interface Perception extends BasePerception<null> {
  readonly data: readonly Concept[];
  readonly panes: {};
}

Pane data is stored in the Pane, so it travels with each Release, each Delivery and each archive, and it holds no person or Workspace ids. Each item is at most 64 KB. Pane code reads it in id order: data.get(id) reads one item, data.list({ limit, after }) reads one page of limit items after the item after, and data.list() and the data.useItems() hook read every item. The gets of one moment go to the server in one request, and each answer is kept for the Version. A Pane it declares is read as panes.<name>.data.list(); and SQL reads parables.<parable>.<pane>_data. Only a proposal changes Pane data. The Pane’s code calls data.propose({ upsert, remove }), the reader confirms the change in a dialog that the host draws, and the change goes into the reader’s set of Changes. It reaches readers when the set publishes. The code of a Pane also proposes to the data of each Pane that its Perception declares in panes, as panes.<name>.data.propose({ upsert, remove }), typed by that Pane’s items. So a parent edits the data of the Panes it shows. A Pane that it does not declare is refused with PA-AU-071. propose.change(pane, { data }) is the same call by handle or key. The Policy target data of the Pane whose data changes decides who reads the data (view.data) and who may propose a new, changed or removed item (create.data, edit.data, delete.data). A change that also changes the Pane’s Policies needs edit.policies under the Policies the Pane had. Its data is allowed when the Policies before the change or the Policies that the change sets allow it. So one Release can give a Pane its data grants and its first data, or remove both, and a copy takes that Release in one Pull. The proposal also needs the same right for every author of the calling Pane’s code. Edits to different items apply on the newest data, and two edits to the same item get their own refusal, PA-AU-059.

Typed links

A field that points at another item is a typed reference, Ref<T>, imported from parable/foundation. On the wire it is the item’s id. TypeScript refuses a link of the wrong type, a save checks that each linked item exists and that the saver can see it, and the row conversion checks the links of each row it converts. Ref<T> names a named interface with an id field, declared in this Perception or imported from another Pane’s Perception. A link that is text, such as parent: "growth", is not checked; Prepare names such a field in Pane data (use-ref). A Pane that only serves other Panes, such as shared state, a kit of helpers or a preview, says so with @plumbing in the doc comment on its Perception. The tag is stored in the Pane’s manifest (plumbing: true), and Plotted Path never offers such a Pane as a part to open (Writing Panes that explain well).

/** Shared state the other Panes read. @plumbing */
export interface Perception extends BasePerception<null> {
  readonly panes: {};
}

@plottedPath publish or @plottedPath report in the same comment asks the platform to write the Pane’s Plotted Path ahead of its first reader, as each Version is published or as each Report run completes. It is stored as plottedPath in the manifest (Write it ahead).

Scalar-lib types

Every field of a Pane’s type and its data is a scalar-lib type, the types of the Provider Pool, imported from @psgen/scalar-lib, a Ref<T>, or a named interface of these:

import type { Generic, Temporal } from "@psgen/scalar-lib";

A value	In code	JSON	A Plot column
Text	`Generic.Text`, or the type it is, such as `Identity.UUID` or `Contact.Email`	string	Utf8, LargeUtf8, Utf8View
A number	`Generic.Float64`	number	Float64, or any number width
A whole number	`Generic.Int64`	number	Int64, or any integer width
Yes or no	`Generic.Boolean`	boolean	Boolean
A calendar day	`Temporal.Date`, such as `"2026-10-09"`	string	Date32 (`DATE`)
An instant	`Temporal.DateTime`, an ISO 8601 string	string	Timestamp (`TIMESTAMP`)
A time of day	`Temporal.Time`, such as `"09:30:00"`	string	Time64 (`TIME`)
A length of time	`Temporal.Duration`, such as `"90s"`	string	text such as `'90s'`
No value	`T \| null`	null	a nullable column
A list	`readonly T[]`	array	List
A link to an item	`Ref<T>`	string, the item’s `id`	Utf8
Several fields	a named interface, `interface Deploy { … }`	object	Struct

A plain string, number or boolean is not a scalar-lib type, and neither is a JavaScript Date: an instant is a Temporal.DateTime, an ISO 8601 string. A literal union such as "7d" | "30d" is text with fixed values. A type the platform declares, such as ParticipantGrant or ProviderRef from parable/foundation, is accepted as it is written. A column that holds a type’s values in another width or encoding is cast to it where the Plot returns: every integer width, REAL and DECIMAL to a number field, DATE64 to a Temporal.Date, a time of day to a Temporal.Time, a TIMESTAMP of any unit or zone to a Temporal.DateTime in UTC, and a dictionary-encoded string to text. Only a value of another kind, such as text in a number field, is PA-AU-047, and a day or an instant held as text needs a CAST in the SQL. A value with several fields is a named interface of these types, declared in the Perception. An array holds one scalar-lib type or one named interface, and an array never holds arrays. There is no inline object type, no tuple and no union of different types. Raw JSON is not a type: Generic.JSON, unknown, any and Readonly<Record<string, T>> are refused (no-raw-json). Items keyed by text are rows of a Pane, or a list of a named interface with an id field. Time is always a Temporal.Date, Temporal.DateTime or Temporal.Time, never Generic.Text or a number: published_at is a Temporal.DateTime and day a Temporal.Date. A span is a named interface with a field for each end, such as started_at and ended_at, or first_day and last_day.

import type { BasePerception, ProviderRef } from "parable/foundation";
import type { Generic, Temporal } from "@psgen/scalar-lib";

export interface Rollout {
  readonly started_at: Temporal.DateTime;
  readonly ended_at: Temporal.DateTime;
}

export interface Deploy {
  readonly repository: Generic.Text;
  readonly tag: Generic.Text;
  readonly published_at: Temporal.DateTime;
  readonly published_on: Temporal.Date;
  readonly rollout: Rollout;
  readonly provider_refs: readonly ProviderRef[];
}

A save, Prepare or Publish that adds a field that is not a scalar-lib type is refused with PA-AU-051, naming the Pane, the field and what to write instead: “The Perception’s type.repository is a plain string. Give it a scalar-lib type: Generic.Text, or the one it is, such as Identity.UUID or Contact.Email.” A time is judged by the field’s name. A text field such as day, week, published_at or starts_on holds a time. A number field holds a time only when its name ends in at, date, timestamp or epoch, such as createdAt or sent_timestamp. A count of days, a duration in minutes, an amount per day (peak_day) and an amount to date (completed_quarter_to_date) stay numbers. A label such as period with values "current" | "previous" is not a time. A refused save stores nothing, so the Pane’s Warnings & Errors cannot show the refused field. A field the published Version already holds is history: it shows as info in the Pane’s Warnings & Errors, and it never stops a read, a draw, or another change from saving and publishing. Do not import Text, Number, YesNo, Empty, List, Day, Moment, Time, Duration or Map from parable/foundation. Write the scalar-lib names instead. Each of these names a Perception imports is a PA-AU-051 finding that says what to write: “The Perception’s import of Empty from parable/foundation is a retired friendly name. Write null, as in X | null.” A failed Preferences save rejects the Pane’s request and shows the reason in the Parable’s window, next to the control that asked. Invalid nested input names the field that could not be sent.

Providers a Parable reads

A Parable names the Providers it reads once, on its Home Page’s Perception, as named groups. Every Parable uses the same structure, and a Provider can be in several groups:

import type { BasePerception } from "parable/foundation";
import type { Panes } from "parable/panes";

export interface Perception extends BasePerception<null> {
  readonly panes: { overview: Panes["overview"] };
  readonly providers: {
    readonly code: {
      readonly title: "Code";
      readonly description: "Pull requests, reviews and commits.";
      readonly role: "populate";
      readonly choice: "atLeastOne";
      readonly providers: readonly ["github", "gitlab"];
    };
    readonly people: {
      readonly title: "People";
      readonly description: "Teams, so delivery reads by team.";
      readonly role: "improve";
      readonly choice: "exactlyOne";
      readonly providers: readonly ["workday", "hibob"];
    };
  };
}

Field	Meaning
`title`	What the group is, in a reader’s words.
`description`	What its Providers add to the Parable, in a sentence.
`role`	`"populate"`: Required to Populate, the Parable shows nothing useful until the choice is met. `"improve"`: Improves the Parable, which reads without it.
`choice`	How many of its Providers a Workspace connects: `"atLeastOne"`, `"atMostOne"` (alternatives that must not be mixed) or `"exactlyOne"`. A `"populate"` group is never `"atMostOne"`.
`providers`	Each Provider’s catalog name, as Plot SQL names it: `github` in `providers.github.commits`.

Write every value in quotes: the compiler reads the declaration from its types. A save refuses a group whose fields it cannot read, a name that is not a catalog name, a Provider listed twice in one group, and providers on any Page or Pane but the Home Page. Prepare refuses a Provider the catalog does not have, naming it and the groups that name it; a Provider the published Version already names is not judged again.

What a Platform Parable gives

A Platform Parable can give its own Pieces to named places in the product, such as a tab beside every Parable. Its Home Page’s Perception declares each gift once, as a named entry in contributes. Each entry names its place and the Pieces that it gives, by handle:

import type { BasePerception } from "parable/foundation";
import type { Panes } from "parable/panes";

export interface Perception extends BasePerception<null> {
  readonly panes: { overview: Panes["overview"] };
  readonly contributes: {
    readonly tab: { readonly place: "ponder.tab"; readonly page: "proofs" };
    readonly checks: {
      readonly place: "publish.checks";
      readonly plot: "checks";
      readonly titles: "proofs";
    };
    readonly review: {
      readonly place: "react";
      readonly report: "reviews";
      readonly on: readonly ["patch.proposed"];
      readonly may: readonly ["read.subject"];
      readonly menu: { readonly in: "parable.actions"; readonly title: "Run Proofs again" };
    };
  };
}

Place	Fields	What it gives
`ponder.tab`	`page`	The Page that the Parable’s tab shows beside every Parable. A Parable has one tab.
`publish.checks`	`plot`, `titles`	The Plot whose rows are the checks that Publish waits for, and the Pane whose rows name the checks. A Parable gives one check Plot.
`react`	`report`, `on`, `may`, and `menu` (optional)	The Report that runs for each subject of the kinds in `on`. Only `"patch.proposed"` is a kind now. `may` lists what the Report may do beyond its own Parable: only `"read.subject"` now, or `readonly []` for nothing. `menu` puts an item in the Parable actions menu (`"parable.actions"`) that runs the Report again.

Write every value in quotes: the compiler reads the declaration from its types. A save refuses each of these, with a sentence that names the entry:

a place that is not in the table, or a field that its place does not take;
a field that its place needs and that the entry leaves out;
a Page, Plot, Pane or Report that the Parable does not have, by its handle;
a second ponder.tab or publish.checks entry;
contributes on any Page or Pane but the Home Page.

A save or an archive import that declares contributes on a Parable that is not a Platform Parable is refused (PA-AU-085). A save that deletes or renames a Piece that the declaration names is refused too, so a Release never names a Piece that it does not have. The declaration is stored with each Release, and the product reads it from the Release that each Deployment runs, never from a Patch. A Platform Parable is never forked, so every copy runs the Releases that Parable staff publish (Forking). The Parable’s tab shows the ponder.tab Page, and that Page knows the Parable on screen beside it (The subject). A Parable that declares no ponder.tab keeps its Home Page as its tab. Later releases wait for the publish.checks Plot at Publish and run the react Report.

Named types and their Providers

A named type is vendor neutral: a Document is a Document whether it comes from Google Docs or Confluence. No type is one Provider’s version of another. A Provider feeds a type through a mapping Pane: its Perception imports the type from its own Pane and uses it as its type, names the Provider with @provider, and its undeclared Plot returns that Provider’s rows of the type. The type’s Pane owns an undeclared Plot that combines its mapping Panes by name.

import type { BasePerception } from "parable/foundation";
import type { Deploy } from "parable/panes/<Deploy Pane ID>/perception";

/** GitHub's deploys. @provider github */
export interface Perception extends BasePerception<Deploy> {
  readonly panes: {};
}

Every such type points back to the records it came from with provider_refs, a list of ProviderRef from parable/foundation: provider, the Provider’s catalog name as in Plot SQL, and provider_id, the record’s ID in that Provider, as text. A record from one Provider has one entry; a record merged from several, such as one Meeting from Google Calendar and Zoom, has one per source record. A type does not name Providers in its own fields, so it has no zoom_id. A reference to a thing that can be one of several types is two fields: its ID and its kind, such as subject_id and subject_kind, with the kind a literal union of the type names. Any Plot can then resolve the reference by joining on both: the kind picks the table and the ID the row. A Pane’s _by_actor rows do the same with actor_kind and actor_id. A link to items of one type is a Ref<T>. A Plot reference is not a Pane reference. CSS is attached by the renderer and is not a Palette configuration in the Perception declaration. A Page’s Perception is BasePerception<null>, and every Page is composition only: its code may import only the Panes its Perception declares and the runtime layout modules. The compiler refuses any other import, such as a chart or control library, and names the import it refused. The rule is the Page’s alone: a Pane whose type is null holds no value and owns no Plot, but can still import the shared controls and read the Plots of the Panes it declares. Export interfaces and type aliases from a Perception to reuse them in another Pane’s React source. Use import type from the host declaration module parable/panes/<Pane ID>/perception, using its stable Pane identity. Type-only imports do not mount the target Pane or grant access to its settings or runtime API. Runtime Pane imports still require a declared panes reference.

Read a named type at runtime

TypeScript types disappear when a Pane’s code compiles, so a type-only import types the code but cannot show what a named type is. To draw one on screen, such as a Parable’s ontology page listing each type’s fields, read it at runtime. The compiler emits it from the declarations themselves, so it cannot drift from the types the Plots are checked against.

A Pane reads the named type it shows, its type’s, as namedType from its module: import { namedType } from '@parable/<parable>/<pane>'.
It reads the one a Pane it declares shows as panes.<name>.namedType, from the panes prop or the module’s panes.
It follows a key to any other named type through the module’s namedTypes: the types a named type extends, the named type a field holds, and the type that declares a field.

namedTypes holds each named type once, by key, so a parent many types extend is not repeated for each. A key is the declaring Pane’s key, or the platform module, then # and the name: <Pane key>#Meeting, parable/foundation#ProviderRef. namedType is null when the type is null or is not one named type: an inline object, a scalar, a list, or a union of several. It is also null when the reader may not view the Perception that declares the type: a named type is part of its Perception, so a reader without view permission on that Perception receives neither the type nor the fields it gives another type. Otherwise a named type is:

Field	What it holds
`key`	Its key in `namedTypes`.
`name`	Its declared name, such as `Meeting`.
`paneKey`	The Pane whose Perception declares it; absent for a platform type such as `ProviderRef`.
`description`	Its doc comment as written, tags such as `@grouping` included; absent when it has none.
`extends`	The keys of the interfaces its declaration extends, in order: `interface Meeting extends Arc, Artifact` gives Arc’s key, then Artifact’s.
`fields`	The fields that no type it extends gives it: the fields it declares, and the fields it takes from a type it does not extend, such as a type that a type alias combines. A field that a parent gives is listed once, on the parent. To get every field, read these, then the fields of each `extends` key in turn.
`fields[].type`	The scalar-lib type, such as `Generic.Text`; the name of the named type the field holds, such as `ProviderRef`; or any other type as TypeScript prints it, such as `"estimate" \| "correction"`. A list names its item’s type.
`fields[].namedType`	The key of the named type the field, or its list, holds; absent when it holds none.
`fields[].list`	`true` for `readonly T[]`.
`fields[].nullable`	`true` when the field may hold `null` or may be left out.
`fields[].description`	The field’s doc comment; absent when it has none.
`fields[].declaredIn`	The key of the type whose declaration holds the field, when that type is not this type and is not a type it extends, such as a type that a type alias combines; absent for a field the type declares.

import type { PaneNamedType } from 'parable/foundation';
import { panes, namedTypes } from '@parable/demo/perceptions';

type FieldFrom = { field: PaneNamedType['fields'][number]; from: PaneNamedType };

// A type's own fields, then the fields of each type it extends, in order.
function allFields(type: PaneNamedType, seen = new Set<string>()): FieldFrom[] {
  if (seen.has(type.key)) return [];
  seen.add(type.key);
  const own = type.fields.map(field => ({ field, from: type }));
  const inherited = type.extends.flatMap(key => {
    const parent = namedTypes[key];
    return parent ? allFields(parent, seen) : [];
  });
  return [...own, ...inherited];
}

export default function MeetingFields() {
  const meeting = panes.meeting.namedType;
  if (!meeting) return null;
  return (
    <ul>
      {allFields(meeting).map(({ field, from }) => (
        <li key={`${from.key}.${field.name}`}>
          {field.name}: {field.type}
          {field.list ? ', a list' : ''}
          {from.key === meeting.key ? '' : `, from ${from.name}`}
        </li>
      ))}
    </ul>
  );
}

A named type describes the declarations and validates nothing. Editing a doc comment changes what namedType shows and never makes a stored Refresh unreadable.

Declare a Plot

A Plot Pane’s type is its kind: a named interface, in scalar-lib types, of the rows its undeclared Plot returns. The one Plot that the Pane owns and does not declare returns rows of that type, picked to the columns its SQL returns, with no parameters. A Pane may own several Plots, and each other Plot is declared. A Plot that takes parameters, or returns rows of another shape, is declared: pass it as the second type argument of BasePerception, under the handle of the Plot the Pane owns, with an array of the kind as its rows:

import type { BasePerception, PlotContract } from 'parable/foundation';
import type { Generic } from '@psgen/scalar-lib';

export interface OpenIssues {
  readonly priority: Generic.Text | null;
  readonly open_issues: Generic.Int64;
}

export interface Perception extends BasePerception<OpenIssues | null, {
  openIssuesByPriority: PlotContract<readonly [], readonly OpenIssues[]>;
}> {
  readonly panes: {};
}

With this saved, the Pane’s React code receives plots.openIssuesByPriority() and the Plot editor’s Preview runs. Without it the Pane has no such function and Preview reports that the Plot’s contract is unavailable.

PlotContract comes from parable/foundation. A bare row type, a function type, or an import from any other module is refused.
The type takes null, OpenIssues | null, so the Pane draws on a Page, which hands it no value. T | null is not a null type.
A Plot that the Perception does not declare returns rows of the Pane’s type, so a Pane has at most one such Plot, and then its type is not null. A save, Prepare or Publish that adds a second undeclared Plot, or an undeclared Plot on BasePerception<null, { ... }>, is refused with PA-AU-049, which names the Pane and those Plots. A Pane whose Plots are all declared may have a null type.
The name must match the handle of a Plot this Pane owns when the declaration is first saved. Save the Plot before the Perception or in the same save; a name with no owned Plot is refused as “does not bind to an owned Plot”. Renaming the Plot later keeps the binding. A Page cannot declare Plots.
The first argument is the tuple of positional SQL parameters: readonly [] for none, or named members such as readonly [since: Generic.Text, limit: Generic.Int64].
The second argument is the array of rows of the kind, which has one field for every column the SQL selects, under the exact column name, and no others.

The kind is the Pane’s type, so each field is a scalar-lib type, and a plain string, number or boolean is PA-AU-051:

SQL column	Declared type
Text	`Generic.Text`
Whole number, including `COUNT`	`Generic.Int64`
Any other number, such as `AVG`	`Generic.Float64`
Boolean	`Generic.Boolean`
Date	`Temporal.Date`
Timestamp	`Temporal.DateTime`
Any column that can be `NULL`	Add `\| null`

Cast a decimal, or an identifier wider than a safe integer, to DOUBLE or VARCHAR in the SQL so the planned type stays fixed. Plots lists the row shapes SQL output supports. When a save is refused, the response names the Pane and the line the compiler rejected. Ponder receives the same lines for the declarations it submitted and corrects them in its next step.

Storage

The declaration is authored source. Its Page or Pane stores it together with its compiled manifest, and versions both with the rest of its definition. Saving checks the declaration with the TypeScript compiler and derives value validation, typed links and reference bindings. The manifest records a hash of the type; each saved row records the hash it was checked against, and a Release may only grow the type of a Pane that holds rows: add optional fields or widen a union (shape-grow). The manifest cannot be edited on its own to bypass the declaration: a save may omit it or send back the stored value, and the server compiles it from the source. The editor presents readable handles. Stored references use stable identities, so renaming a Pane does not redirect existing references to a new Pane that later takes the old name.

Security

Types describe what a value can contain; Policies decide which actions the requester may perform. BasePerception.policies and React’s props.policies contain the resolved Policy decisions (ResolvedPolicies in parable/foundation). The Policies themselves are a field of the Page or Pane, shown in its Policies tab. The host always supplies the required props. A component may ignore props it does not use, but that does not remove the Pane’s schema or access checks. A reader does not need view permission on the Perception to render an allowed value.

Stability

Invalid references, missing base fields, and attempts to replace the fixed contract are refused. Repair the declaration before saving; a preview error does not itself grant or remove source-inspection permission. Temporal.Date is a validated calendar-day string. Temporal.DateTime is an ISO 8601 string. Branded timestamp strings retain their supported fractional precision. @psgen/scalar-lib supplies the same scalar parsers used by the platform. A published Version can stop compiling without changing, when a platform release narrows the types a Perception may use. Its published Plots then cannot be read until the Parable publishes a Version that compiles, or is pocketed. The published Plots of every other Parable in the Workspace stay readable. Each compile type-checks the declaration against the ES2023, DOM and DOM.Iterable libraries.

Parables

Popular

Sources

Schema

Kinds of Pane

Bound Panes

Pane data

Typed links

Scalar-lib types

Providers a Parable reads

What a Platform Parable gives

Named types and their Providers

Read a named type at runtime

Declare a Plot

Storage

Security

Stability

Parables

Popular

​Sources

​Schema

​Kinds of Pane

​Bound Panes

​Pane data

​Typed links

​Scalar-lib types

​Providers a Parable reads

​What a Platform Parable gives

​Named types and their Providers

​Read a named type at runtime

​Declare a Plot

​Storage

​Security

​Stability

Sources

Schema

Kinds of Pane

Bound Panes

Pane data

Typed links

Scalar-lib types

Providers a Parable reads

What a Platform Parable gives

Named types and their Providers

Read a named type at runtime

Declare a Plot

Storage

Security

Stability