--- id: DOM-PFM-QRY-002 title: Query realises: CON-PFM-QRY-002 product_area: platform module: queries revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-QRY-queries readable_by: - SVC-PFM-QRY-explorer lifecycle: - STATE-PFM-QRY-003 - STATE-PFM-QRY-004 - STATE-PFM-QRY-005 custom_fields: none identity: >- An unsaved question is a request held by its caller. Saved queries, Explorer views, navigation sessions and generations receive workspace-scoped system identities. Saved-query names are unique for their owner after normalization; view names have no equivalent database guarantee. Applications assign stable recipe names and release versions. attributes: - name: base dataset kind: reference required: true computed: false notes: The base dataset is fixed after creating a saved query or Explorer view. - name: request kind: collection required: true computed: false notes: >- The language describes columns, filters, dates, sorting, grouping, joins, scope and paging. Its declared limits include 255 columns, five sort keys, one hundred criteria, nesting depth six, two reference hops and pages up to one thousand. - name: ask-when-run values kind: collection required: false computed: false notes: >- Saved queries can declare typed runtime inputs with choices, limits, defaults and required-value checks. - name: 'saved query · name, description and owner' kind: text required: true computed: false notes: >- The creator owns the saved definition; callers do not supply a different owner when creating it. - name: saved query · audience kind: enum required: true computed: false notes: >- A saved query can remain private, name up to one hundred active roles or cover the workspace. Sharing changes an attribute rather than execution state. - name: saved query · origin kind: reference required: false computed: false notes: >- The recipe name and release version are retained together as origin metadata. Recipe retirement does not remove the independent saved query. - name: saved query · version kind: number required: true computed: true notes: Replacements include the version previously read so stale writes can be refused. - name: recipe · release kind: collection required: false computed: false notes: >- Application registration supplies the recipe’s category, labels, parameters and query template; omitted recipes are marked retired. - name: explorer view kind: collection required: false computed: false notes: >- A list view stores a recipe-based arrangement with one to fifty columns, one to five sort keys and page sizes of ten, twenty-five, fifty or one hundred. Names allow one to 120 characters; the workspace and dataset limit is two hundred views. - name: explorer preferences kind: collection required: false computed: false notes: >- Person-specific preferences replace the opening view and up to twenty pinned views under a version check, starting at version zero. - name: navigation session kind: collection required: false computed: true notes: >- The session stores the ordered request and at most two thousand record identities with position, cursor and return state. Navigation lasts twelve hours; retained return state remains available for seven more days. - name: generation kind: collection required: false computed: true notes: >- The generation retains its request, refinement context, requester, outcome or failure code and inference link, then is removed after thirty days. relationships: - to: DOM-PFM-QRY-001 cardinality: many-to-one ownership: The query retains its base dataset and any joined dataset references. cross_service: false - to: DOM-PFM-QRY-003 cardinality: one-to-many ownership: >- Report source rows refer to saved queries and prevent their deletion while dependent presentations remain. cross_service: false - to: DOM-PFM-QRY-004 cardinality: one-to-many ownership: >- A schedule retains a pinned query definition and a restricting source reference; a query file keeps its executed request as origin information. cross_service: false invariants: - id: INV-DOM-PFM-QRY-002-01 statement: >- Running a question uses the runner’s dataset access; sharing the definition does not grant additional data authority. enforced_at: - service provenance: observed source: >- services-platform:modules/queries/services/saved-queries/saved-query-library.ts (header: a run is runQuery with the caller's own context) - id: INV-DOM-PFM-QRY-002-02 statement: >- Private saved queries and views are restricted to their owner or authorized staff workspace access; other readers receive not found. enforced_at: - service provenance: observed source: >- services-platform:modules/queries/services/saved-queries/saved-query-access.ts; modules/explorer/aws/api/explorer-view-access.ts - id: INV-DOM-PFM-QRY-002-03 statement: >- Saved query content is retained without reinterpretation within the 64 KiB limit and must match the saved base dataset. enforced_at: - service - database provenance: observed source: 'services-platform:modules/queries/db/saved-queries.table.ts' - id: INV-DOM-PFM-QRY-002-04 statement: Normalized saved-query names are unique for each owner in a workspace. enforced_at: - service - database provenance: observed source: 'services-platform:modules/queries/services/persistence/saved-queries.ts' - id: INV-DOM-PFM-QRY-002-05 statement: 'Dependent reports, dashboards and schedules prevent deletion of their saved query.' enforced_at: - service - database provenance: observed source: >- services-platform:modules/queries/db/query-schedules.table.ts (saved_query_id without cascade); modules/queries/db/report-sources.table.ts - id: INV-DOM-PFM-QRY-002-06 statement: >- Changing a saved-query audience cannot leave a dependent report or dashboard with a wider audience. enforced_at: - service provenance: documented source: 'services-platform:docs/milestones/plans/RPT-M1-plan.md#D2' - id: INV-DOM-PFM-QRY-002-07 statement: >- Runtime refinement adds restrictions to the stored population while allowing presentation changes; it retains scope, joins and runtime-input definitions. enforced_at: - service provenance: documented source: 'services-platform:docs/milestones/plans/RPT-M1-plan.md#A3' - id: INV-DOM-PFM-QRY-002-08 statement: >- Changed recipe content requires a new release version; a drafted query is independent of subsequent releases. enforced_at: - service provenance: observed source: 'services-platform:modules/queries/services/recipe-registration/register-query-recipes.ts' - id: INV-DOM-PFM-QRY-002-09 statement: >- Recipe-based Explorer views, navigation and selection require joins that preserve a single row per base record. enforced_at: - service provenance: observed source: 'services-platform:modules/explorer/services/definitions/recipe-anchors.ts' - id: INV-DOM-PFM-QRY-002-10 statement: >- Navigation-session reads require the creating person and expose stored identities and return state rather than copied record contents. enforced_at: - service provenance: observed source: >- services-platform:modules/explorer/services/persistence/explorer-navigation-sessions.ts:readNavigationSession - id: INV-DOM-PFM-QRY-002-11 statement: >- Generation settlement conditionally changes working to succeeded or failed, with an outcome for success and a code for failure. enforced_at: - service - database provenance: observed source: >- services-platform:modules/queries/db/query-generations.table.ts (query_generations_settled_check, _outcome_check, _failure_check) - id: INV-DOM-PFM-QRY-002-12 statement: >- Generation reads are requester-only. Query outcomes pass application validation, while assumptions, clarification and unsupported explanations can contain model-authored text. enforced_at: - service provenance: observed source: >- services-platform:modules/queries/services/generate/generated-query-outcome.ts; modules/queries/services/generate/run-generation.ts; modules/queries/services/persistence/query-generations.ts - id: INV-DOM-PFM-QRY-002-13 statement: >- Saved-query, Explorer-view and preference replacements reject missing versions and conflict on stale versions. enforced_at: - api - service provenance: test source: >- services-platform:modules/explorer/tests/e2e/explorer-views-api.e2e.spec.js#refuses a stale version as 409; modules/queries/services/persistence/saved-queries.ts physical: - platform.saved_queries - platform.saved_query_shared_roles - platform.query_recipes - platform.query_generations - platform.explorer_views - platform.explorer_view_preferences - platform.explorer_navigation_sessions evidence: - >- services-platform at ad3f6a6: modules/queries/db/saved-queries.table.ts, saved-query-shared-roles.table.ts, query-recipes.table.ts, query-generations.table.ts; services/saved-queries/*.ts; services/recipes/*.ts; services/recipe-registration/register-query-recipes.ts; services/generate/*.ts; services/execute/run-query.ts - >- services-platform at ad3f6a6: modules/explorer/db/*.table.ts; services/definitions/*.ts; services/navigation/*.ts; services/selection/select-record-ids.ts; docs/explorer.md; docs/queries/saved-queries-and-recipes.md --- # Query ## What It Models The query object covers questions that are transient, saved, supplied as recipes or arranged as Explorer lists. It also includes the temporary sessions used to navigate results and request assisted authoring. ## Identity and Attributes Each facet has its own identity and lifetime. A saved question belongs to its creator; an application owns recipe releases; a person owns navigation and generation sessions. ## Relationships Datasets supply the vocabulary, while presentations and schedules refer to saved definitions. These dependencies are retained separately from the query request itself. ## Invariants The invariant rows distinguish definition sharing, executable access, version conflicts and temporary-session privacy. ## How It Is Stored and Shared The query service stores saved questions, recipes and generations. Explorer owns list views, preferences and navigation; both implement facets of the same planning concept. ## Open Design Questions The recorded navigation finding limits stability to a bounded identity window. The concept’s audience labels are not persisted lifecycle states.