Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Current model-key correction — 8 November 2026. The preserved examples below contain historical camelCase record-type/field keys. Do not copy those keys into the current editor or API: use record type leave_request and the lowercase field keys in the current model worksheet, including request_id, employee_id, manager_id, start_date, end_date, requested_days and decision_comment. Form, rule and case input names are separate declarations; map them explicitly rather than mechanically renaming every input. The preserved body remains historical source material, not a current executable model payload.
Current server-paged source contract — 11 November 2026. A V2 screen source may declare
paging.sizeOptions; each offered size must be a unique positive integer within the source's maximum and the list must include its default (descriptor validation, parser). Remote and complete-local result controls use that authored list (remote, complete-local). A legacy descriptor without the list continues to offer its configured default and maximum. The list can keep the size control available for an authoritative empty remote result; it does not create records or broaden the source's authorization. Empty runtime collections are identified as empty and carry a field-inspection warning because there are no records from which to infer columns (inspector, test). These are source/UI contracts, not a claim that every connector or screen exposes the same choices.
Governed data-source catalog and preview
Choose a source, then prove the selected control can use it
The Connect data catalog is an authoring aid for a saved screen. It describes source identity, shape, capabilities, inference and availability. Its display category is not a promise that every control can execute that source. After discovery, choose the exact collection path and fields, inspect bounded preview, then use the selected control’s native adapter and published-runtime contract.
Nadia can author a screen only under its current scoped capabilities. Sara’s published view uses a separate SCREEN_VIEW/runtime boundary and the source’s current authorization. A preview from Nadia’s editor must never be shipped as an unguarded row cache for Sara. Human readability of fields and AI/provider-disclosure permission are distinct; catalog sensitivity and inference do not grant either.
| Descriptor/input | Reader decision |
|---|---|
sourceRef |
Preserve exact kind/key/version/path and supported publication pin, not the visible label. |
returnShape |
Pick the actual collection and stable row identity; a scalar is not a grid. |
capabilities |
Enable only the selected adapter’s supported paging/search/filter/sort behavior. |
inference |
Resolve ambiguity explicitly; do not choose the first candidate silently. |
available, disabledReason |
State availability; distinguish unsupported/state blocks from denied elements that should not be requested or rendered. |
Preview fields, limit, parameters |
Explicit bounded projection/input selection; parameters are not arbitrary new authority. |
screenVersion, nodeId |
Published context where the native runtime path requires immutable attestation. |
Authoring preview caps selected fields and rows; the shared preview request allows at most20fields. Individual contributors may be more restrictive. The control runtime can have a different request/response shape and lower/different limits. See grid runtime and the query-driven tutorial before wiring a published control.
Worked examples
Example DATA-SOURCE-01 — Discover a leave collection from the saved screen context
Scenario and inputs. Nadia has saved an editable leave-overview screen in the permitted workspace and wants a published record source. The model has an applied publication, but its label may appear alongside other versions or destinations. She needs the catalog’s exact identity rather than assuming all rows named Leave requests point at the same table.
Procedure. 1. Open Connect data from the supported control in the saved draft. 2. Search or filter the screen’s catalog using the published-record category where supported. 3. Inspect the owning group name, version, sourceRef, collection shape, stable key and current availability. 4. Choose the specific admitted physical publication when the source has several destinations. 5. Retain the complete sourceRef through preview and save; do not parse a legacy source label into model/version coordinates.
Expected result. The designer can identify one coherent source and its declared shape before fetching a preview. An unavailable or ambiguous entry remains unresolved until the actual contributor/control path can support it; category discovery alone is not execution evidence.
Failure and recovery. If nothing appears, verify the selected screen/workspace, saved state, model publication and Nadia’s current scoped capabilities. A denied catalog is not a reason to retry as a different actor or manually guess hidden model IDs. Ask the model/screen owner to repair only the intended access or publication state.
Sources. DataSourceCatalogController.java, PublishedRecordDataSourceContributor.java.
Example DATA-SOURCE-02 — Preview a minimal projection and distinguish its outcomes
Scenario and inputs. Nadia selected an exact sourceRef from the saved screen’s catalog and only needs requestId and status for an authoring check. The JSON is a complete preview body with illustrative identity strings; every sourceRef coordinate must be replaced by the returned descriptor, not copied into a different environment unchanged.
Procedure. 1. Copy the selected descriptor’s sourceRef intact, including its supported publicationId when present. 2. Choose only the fields needed to assess the control and send POST /api/screens/leave-overview/data-sources/preview. 3. Check the returned availability/shape and bounded rows before applying the binding. 4. Keep a successful zero-row result distinct from a disabled source or failed request. 5. Save the control’s selected source/projection through the designer’s actual contract and validate the containing screen.
{
"sourceRef": {
"kind": "published-record",
"key": "actual-model-id",
"version": "1",
"path": [
"leaveRequest"
],
"publicationId": "actual-publication-id"
},
"fields": [
"requestId",
"status"
],
"limit": 10,
"parameters": {}
}
Expected result. A supported preview returns a bounded, explicitly projected view under Nadia’s authorization. It does not persist the rows, grant Sara the same source visibility, make every category runtime-executable, or establish that an external provider can be called repeatedly.
Failure and recovery. An unknown field, stale source identity, excessive projection or unavailable dependency requires correcting the source/selection or resolving the actual owner dependency. Do not replace a refusal with invented demo rows. If ambiguity is reported, make a deliberate collection choice and preserve the matching fingerprint/provenance expected by that contributor.
Sources. DataSourcePreview.java, DataSourceDescriptor.java.
Example DATA-SOURCE-03 — Select current-actor task data without impersonating a manager
Scenario and inputs. Sara wants an application view of work available to her. Nadia can choose supported process-task catalog sources, but a user ID typed in a form must not redefine whose tasks the runtime reveals. The task source exposes a deliberately bounded field set rather than full process variables, comments and form content.
Procedure. 1. In a compatible control, choose the actual My assigned tasks, Available to claim or My task history source required by the business view. 2. Inspect its declared fields and supported paging/filter behavior, choosing only task identifiers and summary information needed for navigation. 3. Save and publish the screen with its exact source. 4. Open it as Sara through the real published application admission. 5. Compare the resulting task summaries with Sara’s actual native task permissions; view or claim actions keep their own separate authorization.
Expected result. The source uses the current authorized actor’s secured task service and can expose only its declared summary projection. It is not a general endpoint for reading another employee’s task form or comments by supplying their username.
Failure and recovery. If a manager needs a different admitted team/report view, design that supported scope explicitly instead of adding an assignee parameter to a current-user source. If an expected task is missing, inspect assignment/candidate/state/permissions through the owning task path; absence alone does not prove a query bug.
Sources. CurrentTaskDataSourceContributor.java, DataSourceCatalogController.java.
Example DATA-SOURCE-04 — Move an Integration preview into only its supported published adapter
Scenario and inputs. Nadia has a published nonmutating employee READ Integration with an authoritative collection output and all required inputs satisfied by admitted defaults. Its catalog entry supports a bounded preview. She wants a DataGrid/Table view, but must not infer support for Chart, Metric, paging or arbitrary caller parameters from that preview capability.
Procedure. 1. Inspect the Integration descriptor’s exact published version, collection path, selected fields and shape fingerprint. 2. Use the one-attempt preview only under the contributor’s current actor/deadline/row limits. 3. Confirm the selected control has an implemented native adapter for that exact source and shape. 4. Save the source and projection, publish the screen, and let the runtime rebuild its authority from the immutable node. 5. Keep any runtime request’s allowed source/fields identical to that saved node where the attestation requires it.
Expected result. A supported published adapter reads the intended nonmutating Integration contract under current authorization. The preview’s existence does not enable all data controls or permit a client to replace the source with another draft/version.
Failure and recovery. Required unsatisfied inputs, missing output shape or unsupported control capability must remain unavailable. Resolve the admitted contract/defaults or choose a supported presentation. Do not add a hidden live call, client-supplied credential or fabricated pagination to bypass the source’s bounded one-attempt contract.
Sources. IntegrationApiDataSourceContributor.java, DataSourceCatalogController.java.
Detailed reference
The screen designer uses one normalized catalog contract for data controls. The catalog is an authoring aid, not an execution bypass: every concrete descriptor is resolved in the current workspace and filtered by the current actor before it is returned.
Endpoints
GET /api/screens/{screenKey}/data-sources accepts optional query, optional category,
and limit (default 100, range 1-200). It returns:
{"items": [], "total": 0, "limit": 100}
POST /api/screens/{screenKey}/data-sources/preview accepts a maximum 32 KiB JSON body:
{
"sourceRef": {
"kind": "published-record",
"key": "model-id",
"version": "7",
"path": ["order"]
},
"fields": ["number", "amount"],
"limit": 10
}
version is always a string on the wire. path is always a structured array
of stable segments; clients must not join it and later parse it. Numeric JSON
versions, duplicate JSON keys, unknown request properties, duplicate fields,
and prototype-risk path segments are rejected.
Categories and current availability
The stable category set is published-record, report, rule-query,
process-task, process-model, process-instance, integration-api,
interface-value, design-sample, fabric, and lifecycle-data.
Every category remains visible so authors can understand the product model.
Published records are the first concrete contributor. It lists exact applied publication versions and record types only when the current actor can view the canonical data model. Preview uses the existing governed record-read service.
Reusable published QUERY result schemas that return a reusable MANY record
collection can be discovered and previewed, up to 25 records. Execution remains
control-specific. Repeater uses the bounded collection adapter described below.
DataGrid and Table can also use supported rule-query collection or grid bindings;
the paged grid path requires the contributor's serverPaged, search, filter and
sort capabilities. That capability is limited to the supported native-model query
subset, not every QUERY rule. Required inputs, scalar results and unsupported
control/adapter combinations remain unavailable. Discovery does not create a
generic QUERY binding for Chart, Metric or every other data control.
My assigned tasks, Available to claim and My task history are current-actor
sources using the secured task service. Their bounded declared fields include
id, name, status, priority, due time and creation time. Process variables, comments,
assignment history and forms are
not disclosed. Interface input schemas and prototype design samples are derived
only from the authorized server-owned draft/latest screen document; design
samples can be previewed, while caller-supplied interface inputs are schema-only.
Integration discovery and preview support exact published nonmutating READ/SEARCH operations with an authoritative collection shape and required inputs satisfied by defaults. Preview makes one attempt with the current actor, a four-second deadline, at most 25 rows, selected fields and a matching schema fingerprint. It advertises preview/field selection, not server paging, search, filter or sort. This contributor does not establish a published runtime adapter for every control. The presence of a Reports card likewise does not mean Reports can execute. Use the exact contributor capabilities and the control's native adapter; unavailable entries stay unavailable and no simulated preview rows are produced.
Lifecycle data
The lifecycle-data category (Studio label Lifecycle data) holds exactly one
source, owned by LifecycleDataSourceContributor (spec 022). The consultant
manual is lifecycle-reporting.md.
| Descriptor field | Value |
|---|---|
sourceRef |
{kind: "lifecycle-data", key: "lifecycle-data", version: "1", path: []} |
| Label / description | "Lifecycle data" / "Lifecycle models, their instances and variable history, with typed variables." |
| Owner | Platform |
| Catalog visibility | Listed to an actor with PROCESS_DEFINITION_VIEW, PROCESS_INSTANCE_VIEW or TASK_VIEW (the descriptor's permission is PROCESS_INSTANCE_VIEW). Listing only lets an author pick the source; rows and values are decided on every read. |
| Return shape | collection, MANY, record type ref lifecycle-data:instances; a connected chart plan names the chosen level, lifecycle-data:<level> |
| Capabilities | preview, serverPaged, search, filter, sort, selectFields |
| Inference | exact, 1.0, lifecycle-data:v1 |
| Allowed controls | DataGrid and Chart, at every level. Metric lists it as unavailable ("Lifecycle data can be shown in a data grid or a chart."); other controls do not offer it. |
The source has four levels, chosen in a Lifecycle data settings step that
replaces the generic Preview step of Connect data for this source only:
Lifecycle instances (one row per lifecycle instance, the default), Lifecycle
instance (the changes or the current values of one lifecycle instance), Variable
history (changes across all lifecycle instances) and Lifecycle model (one row per
declared variable). The settings are persisted on the node as
dataConnection.lifecycleData and are validated on the server at save and
publish. The level, model mode and instance mode are URL-addressable while the
step is open (ldNode, ldLevel, ldModel, ldInstance).
No 200-row cap. Unlike the process-activity sources (process-model,
process-instance, process-task), which are not server-paged and whose
preview and chart reads stop at 200 rows, Lifecycle data is server-paged:
- DataGrid reads use
POST /api/screens/{screenKey}/lifecycle-data-query, which takes the existing DataGrid query envelope (page sizes 10, 25, 50 and 100) and returns an exacttotalItems, a stable keyset order, and the additivecolumns,noticesandemptyReasonfields. Sorting, filtering and search run on the server over every lifecycle instance the reader can see. - Chart reads use the existing
POST /api/screens/{screenKey}/chart-querycontract, which dispatches by source kind. Aggregation runs on the server over every visible lifecycle instance: Count, Count distinct, Sum, Average, Min and Max, with an optional date bucket (day,week,month,quarter,year, in the workspace time zone) on a Date or Date and time category. Count distinct and date buckets are accepted for this source only. Rows without a category or series value form theld:notSetgroup ("Not set"), so a chart's total equals the grid's total. At most 500 groups are returned; the 500 largest are kept, with the noticeld.notice.groupCap("Showing the 500 largest groups."). - The designer preview still goes through
POST .../data-sources/preview(at most 25 rows,truncatedset correctly) with the level settings inparameters.lifecycleData(at most 16 KiB) and an optional free-textparameters.search(at most 512 characters) that the server applies over every visible row. The response adds the exacttotalItems.
A page or chart read uses a bounded number of statements, independent of the
number of lifecycle instances. Each statement carries a 19 s JDBC timeout, below
the read's 20 s time limit; a cancelled or busy read is LIFECYCLE_DATA_CAPACITY
(503). At most 100 variable columns are allowed per control.
Access. Published reads require SCREEN_VIEW and a published version, and
the server attests the request against the stored node: level, lifecycle model
input, fields and authored settings come only from the node, and the caller may
supply only paging, search, its own sort and filters on attested fields, and the
node's declared bindings. Draft and preview reads require SCREEN_MANAGE, and
run under the caller's API-key scope ceiling. Rows follow the platform's
per-instance visibility rule (ProcessInstanceAccessGuard, including the
2026-10-02 map-up from an open state process task to its lifecycle instance);
values follow the lifecycle-view rule (sensitive values only for lifecycle
viewers, Protected for others); sensitive variable history is never stored or
shown. Credential-like record fields (marked secret in the data model, or a
credential-like name) and credential-named variables are Protected for every
reader (SCRUM-3812). Refusals do not reveal whether
instances exist. See the dated 2026-10-02 entry in
docs/compliance-readiness.md.
Unchanged neighbours. The process-* contributors, their 200-row behaviour,
LifecycleReportContract and the "Insert lifecycle report" wizard are not
changed by this source.
Multi-destination published records
A single data-model version may be APPLIED on more than one physical database (connector + schema). That is intentional multi-destination make-live.
- Catalog lists one executable row per current live destination, each
with a
publicationIdpin onsourceRefso identities never collide. - Connect / DataGrid / Chart (version-only or pinned screen identity) must
not silently pick a preferred database. With multiple current destinations
and no pin, runtime fails closed with
DATA_MODEL_PUBLICATION_AMBIGUOUS. - Workspace Records may still use preferred newest APPLIED for unpinned list APIs; that exception does not apply to screen controls.
- Metric scalar aggregates may still prefer PostgreSQL when multi-destination (documented load-bearing preference); prefer pinning for new authoring.
- A historical APPLIED row that is no longer that destination's current
latestAppliedis not an executable catalog target (avoids phantom multi-target after version promotion).
A live destination can be retired (POST /api/data-models/publications/{id}/retire).
Retire is catalog un-apply: status becomes RETIRED, applied_at is kept, and
physical tables are not dropped. After retire, Connect, query-rule authoring,
form data controls, published-record lookup, and workspace Records stop offering
that destination because they only execute APPLIED rows. A screen or query
rule still pinned to the retired publication fails closed with
DATA_MODEL_PUBLICATION_SUPERSEDED (reconnect). Pending PLANNED /
AWAITING_APPROVAL publications still block model delete; once every
publication is RETIRED or FAILED, the model can be deleted.
Stable identity
Descriptor id is derived only from the structural source reference. The
encoding starts with ds: and length-prefixes kind, key, and version, then
adds the path-segment count and length-prefixes each segment. When
publicationId is present it is also length-prefixed after a fixed pub
marker so multi-destination rows cannot share one id. Lengths are UTF-16
code units, matching JavaScript String.length. This distinguishes delimiter-
bearing keys and distinguishes one segment containing / from two segments.
Labels and list positions are never identity.
Permission-disclosure policy
- Authentication is required before request parsing or catalog work.
- The screen-specific endpoints require
SCREEN_MANAGE, then load the screen draft (or latest published version) through the workspace-scoped repository. - Only authorized concrete descriptors are disclosed. An unauthorized data model is omitted; its business name, owner, version, and shape are not exposed.
- Generic category placeholders remain visible and contain no tenant asset identity.
- The descriptor
permissionvalue is explanatory metadata. It never grants access and must never replace a current server authorization decision. - For a published-record preview, missing source, denied permission, wrong workspace, wrong version, and wrong record type return the same disabled response and HTTP status. This avoids a source-existence oracle.
- Preview dispatch first resolves the exact complete
SourceReffrom the same actor/screen catalog. Category membership and the informational permission label can never authorize an undisclosed source. - The exact contributor that enumerated that exact reference owns preview. Registration order is irrelevant; a generic disabled category contributor cannot intercept a concrete task, query, record, or sample preview.
Governed member metadata and relationships
Preview columns carry bounded field id, cardinality, format, semantic role,
execution state, and disabled reason. Relationship metadata includes the stable
target type reference, ONE/MANY cardinality, and a structured traversal path.
Direct published-record fields are executable. The PostgreSQL published-record
adapter also executes scalar paths through declared ONE_TO_ONE relationships,
for example order.customer.region.name. Projection, search, filter, and sort
share the same case-sensitive resolver and immutable source version. A preview
uses bounded LEFT JOIN push-down in one SQL statement, returns missing targets
as nested null values, and never performs a per-row relationship query.
Relationship execution is deliberately bounded to three hops, 20 distinct
dotted paths, eight joins, and eight mapped column pairs per relationship. The
resolver rejects cycles, path/output-prefix collisions such as requesting both
customer and customer.name, unknown or unsafe segments, cross-source hops,
and schema/version/workspace mismatches. A ONE_TO_MANY relationship remains
visible but non-executable in a scalar DataGrid plan; the author must choose a
governed collection or aggregation plan instead. Secret-shaped and
PII/confidential target members are omitted from the executable catalog.
returnShape.candidates is reserved for alternative collection paths. It never
contains ordinary fields. Exact inference has at most one viable collection-path
candidate and a nonblank fingerprint. Unknown inference has an unknown shape,
zero confidence, no fingerprint, and no candidates. Field metadata is returned
through governed preview columns.
Preview safety contract
Preview is read-only and is never persisted. The shared service uses two daemon workers, a queue of four, one attempt, and a five-second wait. Timeout and caller interruption cancel the submitted work. Workspace and authenticated security contexts are explicitly propagated into the worker and restored afterward. The published JDBC record service retains its independent 15-second statement timeout as a final adapter bound if cancellation is not immediately honored.
The adapter fetches the requested row limit plus one to determine truncation, then returns at most 25 rows. Other limits are 20 requested/returned fields, nested value depth 8, 64 KiB per serialized cell, 10,000 recursively visited values, and 256 KiB for the complete serialized response. Exceeding a result bound rejects the result atomically; partial oversized rows are not returned.
Secret-shaped members are removed recursively from columns, maps, and arrays. The denylist covers password, client secret, access/refresh token, API key, authorization, cookie/set-cookie, credential, connection string/JDBC URL, private key, and session identifier variants. Cyclic or unsupported object values are rejected. Controllers and services use fixed error text and do not log request bodies, source identities, preview rows, or provider failures. Contributor disabled reasons and nested column/relationship reasons pass through the same boundary; bearer/basic credentials, connection/JDBC URIs, private-key markers, and session/cookie/access/refresh token forms collapse to a fixed safe message.
String limits use UTF-16 code units on both Java and browser clients. Source
reference version permits exactly 128 units. Preview fieldId is nullable for
legacy/derived columns; clients must accept validated null and must not invent an
identity from the label.
Published query rules in a Repeater
This is a deliberately narrow execution path, not a generic query endpoint.
The published interface requests POST /api/screens/{screenKey}/rule-query-collection
with { "version": number, "nodeId": string } and an optional opaque cursor
returned by the original query. The service requires
SCREEN_VIEW, rejects drafts, arbitrary fields, altered rule references,
non-Repeater targets, non-record rows, and oversized results. It also preserves
both screen and governed-rule authorization denials as 403 without returning
rule execution details. The authored marker is internal to the screen document;
clients cannot submit a rule key, filter, projection, or input values.
Chart and Metric Connect data adapters
Chart and Metric use the shared screen-scoped catalog and preview wizard, then
translate the reviewed schema into their existing closed governed plans. Authors
may choose an available published-record, Fabric or process KPI (Process instance
KPIs, Process model KPIs, Process tasks) source that returns an authoritative
collection (MANY) and identifies its record type. A published-record source also
needs a canonical positive publication version; a process KPI source needs a
matching source version and no publication pin. Lifecycle data is offered to
Chart, not to Metric.
QUERY rule sources are not offered to Chart or Metric (SCRUM-4475). Connect data
lists them disabled with the reason "Charts and metrics can't use query rules yet.
Show a query rule in a data grid or a repeater." To show a QUERY rule's results,
use a DataGrid or a Repeater (see "Published query rules in a Repeater" above).
Publish refuses a Chart or Metric that still names a QUERY rule source, for example
in an older draft or a document written through the API, with
SCREEN_QUERY_RULE_SOURCE_UNSUPPORTED. The problem names the control and opens its
data source; reconnect it to another source or replace it with a DataGrid or
Repeater.
Other catalog categories and incompatible shapes remain visible but disabled; the
designer does not turn them into expressions or sample data.
Process model KPIs without a lifecycle (SCRUM-4593). Connect data asks which
lifecycle a Process model KPIs control reads and saves it on the connection
(SCRUM-3672). A grid, repeater, chart or metric connected to Process model KPIs
before that has no lifecycle, so the published interface reads nothing for it and
the control stays empty. In the designer its Properties show Choose a lifecycle
("This table reads Process model KPIs, but no lifecycle is chosen, so it stays
empty when people open it.") with a Choose a lifecycle button that opens
Connect data, whose first step asks for the lifecycle. Validate and Publish list
the control with the warning SCREEN_PROCESS_MODEL_LIFECYCLE_MISSING; it never
blocks publishing. A lifecycle counts as chosen exactly where the published
interface reads it: for a grid or list, a saved lifecycleKey,
processDefinitionKey or lifecycleExpression; for a chart or metric, a saved
lifecycleKey or processDefinitionKey, or a plan filter that fixes one of them.
Lifecycle reports (Insert lifecycle report, for example "All Lifecycles") keep
their lifecycle in the report and are never flagged. People using the published
interface never see a reason sentence; the fix is made in the designer.
A Metric on a process KPI source publishes (SCRUM-4362). Publish accepts it on
the same rule the published interface uses to compute it: the plan names
process-activity:<kind>:<key>, matches the saved connection's source kind, key,
path and version (no publication pin), and reads only connected, executable,
single-valued fields. The value is computed when the published interface is
rendered, from the catalog preview under the viewer's own access; a Metric whose
plan and connection disagree is refused with "Metric is not connected to a
runtime data source." Reconnect it with Connect data to repair it.
Fields are selectable only when they are executable scalar values with
cardinality ONE and one authoritative record-field path segment. Many-valued,
structured, and relationship paths remain disabled until a bounded aggregate or
relationship push-down contract exists. Finish rechecks these invariants before
constructing the plan, so manipulated preview metadata cannot bypass them.
Chart infers a category, an optional text/boolean series, and an optional numeric
measure from governed semantic metadata. It creates a strict ChartPlanV1 with
SUM when a measure is available or COUNT otherwise. Metric creates a strict
MetricPlanV1 with SUM over the best governed numeric measure or COUNT when
there is no numeric measure. Both use the existing source/item/member reference
formats and strict parsers; these adapters do not add permissive plan variants.
Replacing a source uses stable SourceRef and connected field identities.
Cross-source replacement requires explicit confirmation. Compatible source
version changes preserve plan settings only while all referenced stable field
ids remain resolvable. A removed field or changed governed field identity causes
fresh semantic mapping; label or same-path coincidence never preserves a stale
binding.
Preview data is authoring-only. Rows remain in transient dialog state and are
cleared when the wizard closes or finishes. The one Finish callback contains
only ConnectedDataConfiguration, the strict Chart/Metric plan, and explicit
legacy-property removals. Preview rows and cell values are never persisted in
the interface document, plan, legacy sample properties, logs, or telemetry.
Adding a contributor
Implement DataSourceCatalogContributor under
com.inflowai.platform.screen.datasource. A contributor must return only safe
normalized metadata, declare the exact categories it owns, re-authorize preview
against canonical resource identities, and fail closed when its adapter cannot
honor the shared bounds. Registering a catalog card without a real execution
port is insufficient; use an honest disabled placeholder instead.