--- id: CAP-PFM-QRY-008 title: Begin a question from an application recipe feature: FEAT-PFM-QRY-02 product_area: platform module: queries revision: 1 status: draft product_intent: confirmed implementation_evidence: observed supersedes: - CAP-RPT-QRY-010 source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) purpose: Offer application-maintained starting points that staff can turn into independent queries. outcomes: - Staff begin with application-maintained questions. - Recipe registration checks released starting points. - Saved drafts remain independent of later recipes. concepts: - CON-PFM-QRY-002 actors: - ACT-PFM-013 - ACT-PFM-016 surfaces: - console - api - job preconditions: [] postconditions: [] permissions: - key: platform.queries.read where_checked: api scope: tenant - key: ..query (the owner's key) where_checked: service scope: tenant rules: - id: BR-CAP-PFM-QRY-008-01 proved_by: [ATS-PFM-QRY-008-01, TST-PFM-QRY-229] statement: >- The recipe catalog orders active recipes by category and name, includes parameters and authorization flags, excludes retired recipes, and allows catalog reads without dataset permissions. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/e2e/query-recipes.e2e.spec.js#marks a recipe of a dataset this caller may query as authorized, and one it may not as not origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) - id: BR-CAP-PFM-QRY-008-02 proved_by: [ATS-PFM-QRY-001-14, ATS-PFM-QRY-008-02, TST-PFM-QRY-229] statement: Creating or running a recipe draft requires access to its base dataset and every joined dataset. kind: permission enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/e2e/query-recipes.e2e.spec.js#refuses a draft of a dataset this caller may not query as 403 origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) - id: BR-CAP-PFM-QRY-008-03 proved_by: [ATS-PFM-QRY-008-03, TST-PFM-QRY-229] statement: >- Recipe drafting checks existence and retirement before dataset access, then reports all unsatisfied values with labels before checking the completed query. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/e2e/query-recipes.e2e.spec.js#refuses a missing required parameter as 400, naming it and the label its form shows origin: none - id: BR-CAP-PFM-QRY-008-04 proved_by: [ATS-PFM-QRY-008-04, ATS-PFM-QRY-008-11, TST-PFM-QRY-229] statement: >- A recipe draft becomes an independent concrete query whose saved origin records the recipe version, and later recipe releases do not change it. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/e2e/query-recipes.e2e.spec.js#leaves the saved query untouched when the recipe is registered again at version 2 origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) - id: BR-CAP-PFM-QRY-008-05 proved_by: [ATS-PFM-QRY-008-05, TST-PFM-QRY-229] statement: >- Saved recipe provenance must name a recipe registered at least once, while a subsequently retired recipe remains a valid origin. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/e2e/query-recipes.e2e.spec.js#refuses a save naming a recipe nobody ever registered as 400 origin: none - id: BR-CAP-PFM-QRY-008-06 proved_by: [ATS-PFM-QRY-008-06, TST-PFM-QRY-229] statement: >- Recipe execution immediately runs the drafted query as the person, using the same narrowing refinement rules as saved queries. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/e2e/query-recipes.e2e.spec.js#keeps the recipe’s own criteria under a refinement, so a run never widens it origin: none - id: BR-CAP-PFM-QRY-008-07 proved_by: [ATS-PFM-QRY-008-07, TST-PFM-QRY-326] statement: >- Recipe registration validates the whole release before writing, requires live datasets owned by that application, and rejects fields specific to a workspace’s custom or configured metadata. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/integration/services/recipe-registration/register-query-recipes.integration.spec.js#refuses a recipe naming the field a tenant’s configuration row defines, saying only that tenant has it origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) - id: BR-CAP-PFM-QRY-008-08 proved_by: [ATS-PFM-QRY-008-08, TST-PFM-QRY-326] statement: A recipe content change requires a changed version. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/integration/services/recipe-registration/register-query-recipes.integration.spec.js#refuses a recipe whose content changed but whose version did not origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) - id: BR-CAP-PFM-QRY-008-09 proved_by: [ATS-PFM-QRY-008-09, ATS-PFM-QRY-008-12, ATS-PFM-QRY-009-12, TST-PFM-QRY-326] statement: >- Registration retires recipes omitted from a release, restores reintroduced recipes and avoids writes for unchanged declarations. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/integration/services/recipe-registration/register-query-recipes.integration.spec.js#retires a recipe the manifest no longer declares, and leaves the rest alone origin: none - id: BR-CAP-PFM-QRY-008-10 proved_by: [] statement: >- Custom-object activation creates recipes whose availability follows that object independently in each workspace. kind: policy enforced_at: - service must_prove: false provenance: documented source: >- services-platform:docs/queries/saved-queries-and-recipes.md#3.3a Custom object recipes [Built, 2026-10-18] origin: 'services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 18' - id: BR-CAP-PFM-QRY-008-11 proved_by: [ATS-PFM-QRY-008-10, TST-PFM-QRY-270] statement: >- A recipe’s current-person value is valid only on a user-bearing field and is rejected elsewhere during registration. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/integration/services/execute/current-user-criterion.integration.spec.js#refuses at registration the same recipe written on a field that holds no user, naming the field origin: none scenarios: - id: SC-CAP-PFM-QRY-008-01 given: A recipe declares a recent-date input. when: The person supplies a value different from its default. then: The resulting draft uses the supplied value. provenance: test source: >- services-platform:modules/queries/tests/e2e/query-recipes.e2e.spec.js#substitutes the values the caller sends in place of the defaults edge_cases: [] constraints: [] depends_on: - CAP-PFM-QRY-001 related: - CAP-PFM-QRY-006 - CAP-PFM-QRY-009 journeys: [] open_questions: [] operations: - listQueryRecipes - getQueryRecipe - createQueryRecipeDraft - runQueryRecipe tables: - query-recipes.table.ts evidence: - 'Pinned reference: services-platform:docs/queries/saved-queries-and-recipes.md' - 'Pinned reference: services-platform:docs/queries/semantic-query-layer.md' - 'Pinned reference: services-platform:modules/queries/tests/e2e/query-recipes.e2e.spec.js' - >- Pinned reference: services-platform:modules/queries/tests/integration/services/execute/current-user-criterion.integration.spec.js - >- Pinned reference: services-platform:modules/queries/tests/integration/services/recipe-registration/register-query-recipes.integration.spec.js controls: [TC-AVL-001, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-DAT-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-003, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-PFM-QRY-02-01, FAS-PFM-QRY-02-03, FAS-PFM-QRY-02-04] suites: [TST-PFM-QRY-229, TST-PFM-QRY-270, TST-PFM-QRY-326] --- # Begin a question from an application recipe ## Purpose Offer application-maintained starting points that staff can turn into independent queries. ## How It Works Staff choose an application recipe as a starting point. The catalog explains its inputs and whether it is available to them. Supplying the requested values produces a concrete draft. The person can run, alter or save that draft independently. Later application releases can revise the recipe without rewriting saved questions derived from it. Registration checks the released library and reports invalid declarations. Removed recipes stop being offered, while their earlier use can remain recorded as provenance. ## Relationships Published recipes provide starting questions that a person can retain in the saved-question library.