Perceptions - Parable

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.

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

type Scenario = {
  name: string;
  startDate: Temporal.Date;
  departments: string[];
};

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

Base field	Meaning
`primitive`	The native value type supplied through `BasePerception<T>`. Ordinary data fields belong inside this type.
`panes`	Named, typed references to other Panes in this Parable.
`plots`	Declared `PlotContract<Input, Output>` computations, bound by the host to owned Plot identities.
`policies`	Fixed resolved Policy decisions supplied by the host.

All four fields are required. Extra root fields and index signatures are refused. Declare Plots through BasePerception<Primitive, DeclaredPlots> or a structured plots field. The resolved policies contract cannot be replaced or narrowed. Objects, arrays, maps, unions, native types, and semantic scalars describe the primitive without adding Property entities. A Plot reference is not a Pane reference. SQL and React source use their canonical value contracts without acquiring Pane composition. CSS is attached by the renderer and is not a Palette configuration in the Perception declaration. A Page is a placement Pane with BasePerception<null>. 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 Preferences or runtime API. Runtime Pane imports still require a declared panes reference.

Storage

The declaration is authored source. Saving checks it with the TypeScript compiler and derives value validation and reference bindings. Those derived fields cannot be edited independently to bypass the declaration. A schema edit must also keep existing live application values valid. 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 generated ParableResolvedPolicies decisions. Read settings separately through preferences.readPolicies when permitted. 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. Private declarations are not required merely to render an allowed value; representation metadata tells the renderer how to reconstruct native values. Typed Preference requests carry a compiler-derived fingerprint of the selected primitive contract. A changed imported constraint or native representation requires the SDK to refresh; changing a Preference value does not change this fingerprint. The fingerprint never grants permission.

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. A native Date is restored as a JavaScript Date, while branded Temporal.DateTime remains a string. Native Date wire values require an explicit timezone and an instant representable in milliseconds. More precise values are refused instead of being truncated. SQL output canonicalizes native Dates to UTC, including Dates inside objects and arrays. Branded timestamp strings retain their supported fractional precision. @psgen/scalar-lib supplies the same scalar parsers used by the platform. Private representation metadata omits literal constraints. If several matching union branches would require different native representations, loading refuses with an ambiguous-representation error rather than supplying the wrong value. Use the same representation across those branches or separate Pane types for that case today. An explicit Date | string may remain a string.

Reference

Generated Workspace API reference for this Piece:

​Sources

​Schema

​Storage

​Security

​Stability

​Reference