--- id: SVC-PFM-QRY-queries title: Queries service module product_area: platform module: queries repository: services-platform source_module: modules/queries revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: - IOP-PFM-QRY-001 source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-QRY-001 - DOM-PFM-QRY-002 - DOM-PFM-QRY-003 - DOM-PFM-QRY-004 does_not_own: - 'Metadata retains ownership of object shape, labels and custom-field declarations.' - 'Security provides grants, person contexts and the route authorizer.' - >- The LLM foundation owns invocation, provider access, usage and allowance; Queries validates its drafting outcomes. - 'Communications owns template interpretation, message delivery and resulting delivery state.' - >- Operations supplies recently viewed audit history and the common queue and scheduling infrastructure. - >- Explorer implements list-state facets; Data Exports implements complete workspace package foundations. - >- Applications own source records, while legacy storage controls physical retention of the query and report files. operations: - operation_id: createCustomQueryTable intent: Reserve a permanent custom-table identity and create its initial draft. method: POST /queries/system/custom_tables access: system permission: hq.custom-query-tables.author realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:createCustomQueryTable' - operation_id: listCustomQueryTables intent: Page through staff custom-table definitions ordered by identity. method: GET /queries/system/custom_tables access: system permission: hq.custom-query-tables.read realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:listCustomQueryTables' - operation_id: revalidateCustomQueryTables intent: >- Run current validation checks on released and pinned versions when a validation workspace exists. method: POST /queries/system/custom_tables/revalidate access: system permission: hq.custom-query-tables.publish realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:revalidateCustomQueryTables' - operation_id: getCustomQueryTable intent: 'Read the definition with draft, release, assignments and health.' method: 'GET /queries/system/custom_tables/{tableId}' access: system permission: hq.custom-query-tables.read realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:getCustomQueryTable' - operation_id: updateCustomQueryTable intent: 'Version-check changes to the table’s name, description and category.' method: 'PUT /queries/system/custom_tables/{tableId}' access: system permission: hq.custom-query-tables.author realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:updateCustomQueryTable' - operation_id: saveCustomQueryTableDraft intent: 'Save reviewed draft SQL, columns and defaults together with its analysis.' method: 'PUT /queries/system/custom_tables/{tableId}/draft' access: system permission: hq.custom-query-tables.author realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:saveCustomQueryTableDraft' - operation_id: analyzeCustomQueryTableDraft intent: 'Analyze the stored SQL for source access, output shape and release problems.' method: 'POST /queries/system/custom_tables/{tableId}/draft/analyze' access: system permission: hq.custom-query-tables.author realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:analyzeCustomQueryTableDraft' - operation_id: previewCustomQueryTable intent: Execute a chosen version only in the configured validation workspace. method: 'POST /queries/system/custom_tables/{tableId}/preview' access: system permission: hq.custom-query-tables.author realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:previewCustomQueryTable' - operation_id: publishCustomQueryTable intent: Promote the validated draft after acknowledging every affected breaking dependency. method: 'POST /queries/system/custom_tables/{tableId}/publish' access: system permission: hq.custom-query-tables.publish realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:publishCustomQueryTable' - operation_id: listCustomQueryTableVersions intent: Return released and draft version history newest first. method: 'GET /queries/system/custom_tables/{tableId}/versions' access: system permission: hq.custom-query-tables.read realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:listCustomQueryTableVersions' - operation_id: getCustomQueryTableVersion intent: Read one retained version and its reviewed output fields. method: 'GET /queries/system/custom_tables/{tableId}/versions/{version}' access: system permission: hq.custom-query-tables.read realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:getCustomQueryTableVersion' - operation_id: listCustomQueryTableAssignments intent: 'Return inclusion, exclusion and pin assignments with scope counts.' method: 'GET /queries/system/custom_tables/{tableId}/assignments' access: system permission: hq.custom-query-tables.read realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: >- services-platform:modules/queries/aws/api/custom-tables.routes.ts:listCustomQueryTableAssignments - operation_id: assignCustomQueryTable intent: 'Add a global, customer or workspace inclusion, or an individual workspace exclusion.' method: 'POST /queries/system/custom_tables/{tableId}/assignments' access: system permission: hq.custom-query-tables.assign realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:assignCustomQueryTable' - operation_id: pinCustomQueryTableAssignment intent: Select a published version for an assignment or clear its pin. method: 'PUT /queries/system/custom_tables/{tableId}/assignments/{assignmentId}' access: system permission: hq.custom-query-tables.assign realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: >- services-platform:modules/queries/aws/api/custom-tables.routes.ts:pinCustomQueryTableAssignment - operation_id: unassignCustomQueryTable intent: Remove the assignment and its resulting workspace visibility. method: 'DELETE /queries/system/custom_tables/{tableId}/assignments/{assignmentId}' access: system permission: hq.custom-query-tables.assign realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:unassignCustomQueryTable' - operation_id: getCustomQueryTableUsage intent: Inspect saved-query dependencies grouped by workspace. method: 'GET /queries/system/custom_tables/{tableId}/usage' access: system permission: hq.custom-query-tables.read realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:getCustomQueryTableUsage' - operation_id: listCustomQueryTableEvents intent: Read retained authoring and lifecycle history in reverse time order. method: 'GET /queries/system/custom_tables/{tableId}/events' access: system permission: hq.custom-query-tables.read realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:listCustomQueryTableEvents' - operation_id: deprecateCustomQueryTable intent: >- Set deprecated availability so pickers omit the table while existing questions remain executable. method: 'POST /queries/system/custom_tables/{tableId}/deprecate' access: system permission: hq.custom-query-tables.publish realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:lifecycleRoutes' - operation_id: disableCustomQueryTable intent: Set disabled availability and refuse execution of the dataset. method: 'POST /queries/system/custom_tables/{tableId}/disable' access: system permission: hq.custom-query-tables.publish realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:lifecycleRoutes' - operation_id: restoreCustomQueryTable intent: 'Set active availability, including an already-active definition, with lifecycle history.' method: 'POST /queries/system/custom_tables/{tableId}/restore' access: system permission: hq.custom-query-tables.publish realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/custom-tables.routes.ts:lifecycleRoutes' - operation_id: getQueriesHealth intent: Return this API’s health and deployed service identity. method: GET /queries/health access: public permission: 'none: public route' realises: [] published_to_submissions: 'not published: diagnostic health read' provenance: observed source: 'services-platform:modules/queries/aws/api/queries.routes.ts:healthRoute' - operation_id: listQueryDatasets intent: Return registered workspace datasets and their current usability for the caller. method: 'GET /queries/{tenantId}/datasets' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-001 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/queries.routes.ts:listQueryDatasets' - operation_id: describeQueryDataset intent: 'Resolve the workspace dataset vocabulary, labels and supported query operations.' method: 'GET /queries/{tenantId}/datasets/{datasetId}' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-001 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/queries.routes.ts:describeQueryDataset' - operation_id: runDatasetQuery intent: Execute one authorized page of a structured dataset query. method: 'POST /queries/{tenantId}/datasets/{datasetId}/query' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-002 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/queries.routes.ts:runDatasetQuery' - operation_id: generateDatasetQuery intent: Admit a plain-language drafting request and return the generation to poll. method: 'POST /queries/{tenantId}/datasets/{datasetId}/generate' access: console permission: platform.queries.generate realises: - CAP-PFM-QRY-003 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/queries.routes.ts:generateDatasetQuery' - operation_id: getQueryGeneration intent: Read the requesting person’s generation status and settled outcome. method: 'GET /queries/{tenantId}/generations/{generationId}' access: console permission: platform.queries.generate realises: - CAP-PFM-QRY-003 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/queries.routes.ts:getQueryGeneration' - operation_id: validateDatasetQuery intent: Check query structure and compilation without producing result records. method: 'POST /queries/{tenantId}/datasets/{datasetId}/validate' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-002 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/queries.routes.ts:validateDatasetQuery' - operation_id: resolveDateExpressions intent: Resolve supplied date expressions using the workspace calendar context. method: 'POST /queries/{tenantId}/date_expressions/resolve' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-002 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/queries.routes.ts:resolveDateExpressions' - operation_id: listSystemQueryDatasets intent: Return staff system datasets and their usability. method: GET /queries/system/datasets access: system permission: hq.queries.read realises: - CAP-PFM-QRY-004 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/system-queries.routes.ts:listSystemQueryDatasets' - operation_id: describeSystemQueryDataset intent: Resolve the field and operation vocabulary for a staff system dataset. method: 'GET /queries/system/datasets/{datasetId}' access: system permission: hq.queries.read realises: - CAP-PFM-QRY-004 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/system-queries.routes.ts:describeSystemQueryDataset' - operation_id: runSystemDatasetQuery intent: Execute a paged query on the system dataset under staff access. method: 'POST /queries/system/datasets/{datasetId}/query' access: system permission: hq.queries.read realises: - CAP-PFM-QRY-004 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/system-queries.routes.ts:runSystemDatasetQuery' - operation_id: validateSystemDatasetQuery intent: Validate a system-dataset query without returning result records. method: 'POST /queries/system/datasets/{datasetId}/validate' access: system permission: hq.queries.read realises: - CAP-PFM-QRY-004 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/system-queries.routes.ts:validateSystemDatasetQuery' - operation_id: listSystemQueryRecipes intent: Return active staff query recipes with dataset usability. method: GET /queries/system/recipes access: system permission: hq.queries.read realises: - CAP-PFM-QRY-004 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/system-queries.routes.ts:listSystemQueryRecipes' - operation_id: getSystemQueryRecipe intent: Read a registered system recipe and its template. method: 'GET /queries/system/recipes/{recipeId}' access: system permission: hq.queries.read realises: - CAP-PFM-QRY-004 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/queries/aws/api/system-queries.routes.ts:getSystemQueryRecipe' - operation_id: createSystemQueryRecipeDraft intent: Substitute recipe values into an independent system query request without saving it. method: 'POST /queries/system/recipes/{recipeId}/draft' access: system permission: hq.queries.read realises: - CAP-PFM-QRY-004 published_to_submissions: 'not published: internal staff administration' provenance: observed source: >- services-platform:modules/queries/aws/api/system-queries.routes.ts:createSystemQueryRecipeDraft - operation_id: listQueryRecipes intent: Return active workspace query recipes grouped by their declared category and name. method: 'GET /queries/{tenantId}/recipes' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-008 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-recipes.routes.ts:listQueryRecipes' - operation_id: getQueryRecipe intent: 'Read a recipe’s template, parameters and origin metadata.' method: 'GET /queries/{tenantId}/recipes/{recipeId}' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-008 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-recipes.routes.ts:getQueryRecipe' - operation_id: createQueryRecipeDraft intent: Produce an authorized query request from a recipe and supplied parameter values. method: 'POST /queries/{tenantId}/recipes/{recipeId}/draft' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-008 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-recipes.routes.ts:createQueryRecipeDraft' - operation_id: runQueryRecipe intent: Execute a recipe with runtime values and any permitted narrowing refinement. method: 'POST /queries/{tenantId}/recipes/{recipeId}/run' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-008 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-recipes.routes.ts:runQueryRecipe' - operation_id: createSavedQuery intent: Create the caller’s named reusable question with its requested audience. method: 'POST /queries/{tenantId}/saved_queries' access: console permission: platform.saved-queries.use realises: - CAP-PFM-QRY-006 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/saved-queries.routes.ts:createSavedQuery' - operation_id: listSavedQueries intent: 'Browse visible saved questions, including numbered library paging where requested.' method: 'GET /queries/{tenantId}/saved_queries' access: console permission: platform.saved-queries.read realises: - CAP-PFM-QRY-006 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/saved-queries.routes.ts:listSavedQueries' - operation_id: getSavedQuery intent: Read a visible saved question with available actions and current execution problems. method: 'GET /queries/{tenantId}/saved_queries/{savedQueryId}' access: console permission: platform.saved-queries.read realises: - CAP-PFM-QRY-006 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/saved-queries.routes.ts:getSavedQuery' - operation_id: updateSavedQuery intent: >- Replace the saved definition at its read version without changing its base dataset or recipe origin. method: 'PUT /queries/{tenantId}/saved_queries/{savedQueryId}' access: console permission: platform.saved-queries.use realises: - CAP-PFM-QRY-006 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/saved-queries.routes.ts:updateSavedQuery' - operation_id: deleteSavedQuery intent: Remove an editable saved question after version and dependency checks. method: 'DELETE /queries/{tenantId}/saved_queries/{savedQueryId}' access: console permission: platform.saved-queries.use realises: - CAP-PFM-QRY-006 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/saved-queries.routes.ts:deleteSavedQuery' - operation_id: runSavedQuery intent: Execute the visible saved question as the caller with runtime values and optional refinement. method: 'POST /queries/{tenantId}/saved_queries/{savedQueryId}/run' access: console permission: platform.saved-queries.read realises: - CAP-PFM-QRY-007 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/saved-queries.routes.ts:runSavedQuery' - operation_id: createReport intent: Create an owned report or dashboard from visible saved-query sources. method: 'POST /queries/{tenantId}/reports' access: console permission: platform.reports.use realises: - CAP-PFM-QRY-011 - CAP-PFM-QRY-012 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/reports.routes.ts:createReport' - operation_id: listReports intent: 'Browse permitted report and dashboard summaries under scope, kind and search filters.' method: 'GET /queries/{tenantId}/reports' access: console permission: platform.reports.read realises: - CAP-PFM-QRY-011 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/reports.routes.ts:listReports' - operation_id: getReport intent: 'Read the presentation definition, powers and recorded source-change indicators.' method: 'GET /queries/{tenantId}/reports/{reportId}' access: console permission: platform.reports.read realises: - CAP-PFM-QRY-011 - CAP-PFM-QRY-012 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/reports.routes.ts:getReport' - operation_id: updateReport intent: Replace the presentation and its sources with version and audience checks. method: 'PUT /queries/{tenantId}/reports/{reportId}' access: console permission: platform.reports.use realises: - CAP-PFM-QRY-011 - CAP-PFM-QRY-012 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/reports.routes.ts:updateReport' - operation_id: deleteReport intent: Remove the editable presentation at its read version and pause its dependent schedules. method: 'DELETE /queries/{tenantId}/reports/{reportId}' access: console permission: platform.reports.use realises: - CAP-PFM-QRY-011 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/reports.routes.ts:deleteReport' - operation_id: startReportExport intent: Admit background PDF or supported Excel rendering of the visible presentation. method: 'POST /queries/{tenantId}/reports/{reportId}/exports' access: console permission: platform.reports.use realises: - CAP-PFM-QRY-013 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/reports.routes.ts:startReportExport' - operation_id: startQueryExport intent: Admit a CSV or Excel file for the complete executed query result. method: 'POST /queries/{tenantId}/exports' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-014 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-exports.routes.ts:startQueryExport' - operation_id: getQueryExport intent: 'Read file-production status, progress and final result metadata.' method: 'GET /queries/{tenantId}/exports/{exportId}' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-014 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-exports.routes.ts:getQueryExport' - operation_id: downloadQueryExport intent: Authorize the ready file and return its short-lived storage download redirect. method: 'GET /queries/{tenantId}/exports/{exportId}/download' access: console permission: platform.queries.read realises: - CAP-PFM-QRY-014 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-exports.routes.ts:downloadQueryExport' - operation_id: downloadQueryExportByLink intent: Validate the personal delivery token and recipient membership before a storage redirect. method: 'GET /queries/public/downloads/{token}' access: public permission: 'none: public route' realises: - CAP-PFM-QRY-014 published_to_submissions: 'not published: recipient file retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-exports.routes.ts:downloadQueryExportByLink' - operation_id: listQuerySchedules intent: 'Browse the caller’s schedules, or workspace schedules for a manager.' method: 'GET /queries/{tenantId}/schedules' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:listQuerySchedules' - operation_id: createQuerySchedule intent: Create recurring file delivery for an executable query or eligible report. method: 'POST /queries/{tenantId}/schedules' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:createQuerySchedule' - operation_id: getQuerySchedule intent: 'Read an accessible schedule with its recurrence, source and recipient details.' method: 'GET /queries/{tenantId}/schedules/{scheduleId}' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:getQuerySchedule' - operation_id: replaceQuerySchedule intent: Replace editable schedule fields using the read version. method: 'PUT /queries/{tenantId}/schedules/{scheduleId}' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:replaceQuerySchedule' - operation_id: deleteQuerySchedule intent: Remove the schedule and dependent history while retaining existing file lifetimes. method: 'DELETE /queries/{tenantId}/schedules/{scheduleId}' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:deleteQuerySchedule' - operation_id: duplicateQuerySchedule intent: Create a paused copy owned by the caller. method: 'POST /queries/{tenantId}/schedules/{scheduleId}/duplicate' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:duplicateQuerySchedule' - operation_id: pauseQuerySchedule intent: Disable future automatic occurrences through the scheduling library. method: 'POST /queries/{tenantId}/schedules/{scheduleId}/pause' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:pauseQuerySchedule' - operation_id: resumeQuerySchedule intent: Check resume eligibility and calculate the next occurrence from the current time. method: 'POST /queries/{tenantId}/schedules/{scheduleId}/resume' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:resumeQuerySchedule' - operation_id: runQueryScheduleNow intent: Admit an immediate recipient delivery executed as the clicking person. method: 'POST /queries/{tenantId}/schedules/{scheduleId}/run' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:runQueryScheduleNow' - operation_id: takeQueryScheduleOwnership intent: Make the schedule manager its owner for subsequent automatic execution. method: 'POST /queries/{tenantId}/schedules/{scheduleId}/take_ownership' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:takeQueryScheduleOwnership' - operation_id: useLatestScheduleQuery intent: Refresh the schedule’s query snapshot from the current saved definition. method: 'POST /queries/{tenantId}/schedules/{scheduleId}/use_latest_query' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:useLatestScheduleQuery' - operation_id: getScheduleQueryChanges intent: Compare the pinned question with the latest saved query definition. method: 'GET /queries/{tenantId}/schedules/{scheduleId}/query_changes' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:getScheduleQueryChanges' - operation_id: listQueryScheduleRuns intent: Return occurrence history with file and recipient delivery outcomes. method: 'GET /queries/{tenantId}/schedules/{scheduleId}/runs' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:listQueryScheduleRuns' - operation_id: previewQuerySchedule intent: Validate the proposed recurrence and return its description and next five times. method: 'POST /queries/{tenantId}/schedule_preview' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:previewQuerySchedule' - operation_id: listDeliveryTemplates intent: Return templates registered for scheduled-report delivery. method: 'GET /queries/{tenantId}/delivery_templates' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:listDeliveryTemplates' - operation_id: getDeliveryTemplateStarter intent: Return the initial subject and body content for a delivery template. method: 'GET /queries/{tenantId}/delivery_templates/starter' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:getDeliveryTemplateStarter' - operation_id: findRecipientUsers intent: Find up to twenty active organization users by name or address. method: 'GET /queries/{tenantId}/recipient_users' access: console permission: platform.queries.read AND (platform.query-schedules.use OR platform.query-schedules.manage) realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:findRecipientUsers' - operation_id: registerQueryApplication intent: 'Validate and persist an application dataset manifest, retaining retired declarations.' method: Lambda invoke platform_queries_registration (owner's deploy role) access: internal permission: 'none: IAM invoke grant platform-queries-registration-invoke' realises: - CAP-PFM-QRY-001 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: registerQueryRecipes intent: Apply validated recipe releases after the application’s dataset registration. method: Lambda invoke platform_query_recipes_registration (owner's deploy role) access: internal permission: 'none: IAM invoke grant platform-query-recipes-registration-invoke' realises: - CAP-PFM-QRY-008 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: runQueryGeneration intent: Execute the admitted drafting conversation and conditionally settle its outcome. method: 'Lambda async invoke platform_queries_generation {tenantId, generationId}' access: internal permission: 'none: invoked only by the queries API after the generation row commits' realises: - CAP-PFM-QRY-003 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: reconcileQueryGenerations intent: Fail abandoned drafting requests and remove generations beyond retention. method: 'EventBridge rule (rate 5 minutes) on platform_queries_generation {operation reconcile}' access: internal permission: 'none: scheduled' realises: - CAP-PFM-QRY-003 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: dispatchQueryExports intent: Publish durable file requests to their generator or renderer queue. method: EventBridge rule (rate 1 minute) and async nudge on platform_query_exports_dispatcher access: internal permission: 'none: scheduled' realises: - CAP-PFM-QRY-014 - CAP-PFM-QRY-013 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: runQueryExport intent: Produce and settle one query file using requester-scoped paged execution. method: SQS platform-query-exports consumer platform_query_exports_worker access: internal permission: 'none: queue consumer' realises: - CAP-PFM-QRY-014 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: renderReportExport intent: Render an admitted presentation through intercepted requester-authorized print reads. method: SQS platform-report-renders consumer platform_report_renderer access: internal permission: 'none: queue consumer' realises: - CAP-PFM-QRY-013 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: dispatchSchedules intent: Claim due occurrence work and submit it to the delivery queue. method: EventBridge rule (rate 1 minute) on platform_schedules_dispatcher access: internal permission: 'none: scheduled' realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: runScheduledDelivery intent: Produce or render the occurrence file and record each recipient’s communication outcome. method: SQS platform-schedules consumer platform_schedules_consumer access: internal permission: 'none: queue consumer' realises: - CAP-PFM-QRY-015 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: revalidateCustomQueryTablesNightly intent: Perform the scheduled bounded health check in the configured validation workspace. method: 'EventBridge rule (04:20 UTC) on platform_queries_revalidation' access: internal permission: 'none: scheduled' realises: - CAP-PFM-QRY-005 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: pageSavedQueryRecordIds intent: Read Accounting’s ordered population page or count as its named person. method: Lambda invoke platform_queries_record_ids (Accounting service role only) access: internal permission: 'none: IAM invoke grant to the accounting role' realises: - CAP-PFM-QRY-007 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: marketingRecordIds intent: 'Read Marketing’s population pages, counts or requested record fields as its named person.' method: Lambda invoke platform_queries_marketing_record_ids (Marketing service role only) access: internal permission: 'none: IAM invoke grant to the marketing role' realises: - CAP-PFM-QRY-007 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: evaluateSubjectPredicates intent: Evaluate bounded dated record conditions for an authorized system caller. method: 'in-process (Eligibility, Extensions)' access: internal permission: 'none: system execution only' realises: - CAP-PFM-QRY-020 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - operation_id: queryLayerInProcess intent: >- Provide query execution, projections and ordered identities to other Platform modules under their execution context. method: >- in-process (runQuery, projectRecords, findRecordIds, orderedRecordIds, countOrderedRecords, enumerateRecords) access: internal permission: 'none: the execution context''s own grants decide' realises: - CAP-PFM-QRY-002 - CAP-PFM-QRY-010 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) events: - name: 'description table change (database trigger, no event bus)' direction: consumed when: A participating description table is written. payload_summary: >- The database trigger advances a workspace or global stamp; this is a database signal without an event-bus payload. - name: communication request (purpose platform.queries.scheduled-report) direction: produced when: A run submits delivery for one recipient. payload_summary: >- The request includes template, current recipient address, message, file summary and signed personal link under the recipient submission key. - name: schedule run message direction: produced when: Automatic dispatch or a manual run submits an occurrence. payload_summary: >- The scheduling queue message identifies workspace, schedule, occurrence and supported work kind. - name: export queue message direction: produced when: Export dispatch publishes accepted queued work. payload_summary: 'The message names workspace, export and file kind without embedding query values.' - name: CRM configuration change (description stamp) direction: consumed when: Participating CRM configuration changes commit. payload_summary: The shared trigger advances the relevant workspace description stamp. jobs: - >- Query exports and report renders use separate queues with dead-letter and age monitoring; report rendering permits three receives. - >- The delivery queue has three consumers with fifteen-minute processing time and six-times-timeout visibility. - >- Periodic export and occurrence dispatch, generation cleanup and custom-table validation use their declared schedules and alarms. - This service module deploys no Step Functions job. integrations: - system: LLM foundation (Platform) direction: outbound contract: >- The worker uses the foundation operation runner for the sole drafting task; provider secrets and usage accounting stay there. - system: Communications (Platform) direction: outbound contract: >- Scheduled runs submit keyed recipient requests and read communication outcome state for history. - system: Security (Platform) direction: outbound contract: Routes use evaluated grants; background person work reconstructs the named execution context. - system: Accounting and Marketing direction: inbound contract: >- Dedicated population functions admit only their configured remote principal while the lifecycle integration is enabled. - system: Owning applications' deploys direction: inbound contract: >- Application deployments submit validated dataset and recipe manifests through registration invocations. - system: React console print route direction: outbound contract: >- The print renderer intercepts a fixed allowlist of Platform calls under requester access without a browser login. - system: Rhythm 1.0 export bucket direction: outbound contract: >- Legacy storage holds workspace-prefixed files and supplies signed download redirects and its independent retention lifecycle. consistency: - rule: File admission commits export and queued-work rows together. kind: transactional compensation: Unaccepted publication stays dispatchable; post-publication interruption can redeliver work. - rule: >- Report writes check audience width against locked sources and commit the complete source set with the version change. kind: transactional compensation: Rejected writes leave the previous definition and sources. - rule: Report removal and its schedule pauses share one transaction. kind: transactional compensation: Rollback restores the pre-delete state; no report restore operation exists. - rule: Generation settlement accepts only working status. kind: transactional compensation: The abandonment pass can settle a worker that never completed. - rule: 'Files, renders and scheduled deliveries finish asynchronously after admission.' kind: eventual compensation: >- Handled multipart work is aborted and infrastructure faults retry; completed messages are not recalled. - rule: >- Description keys use transactionally changed stamps, while resolution reads stamps and metadata separately. kind: transactional compensation: Cache failure falls back to reads; the snapshot-isolation gap has no implemented repair check. - rule: >- Custom-table release replaces selected publication, retains superseded history and creates the next draft atomically. kind: transactional compensation: Rejected publication preserves the previous release. evidence: - >- services-platform at ad3f6a6: modules/queries/aws/api/*.routes.ts (route declarations, extracted by importing the route arrays), aws/logic/*.lambda.ts, aws/resources/*.ts, services/**, db/*.table.ts; aws/platform.service.ts (permission groups) - >- services-platform at ad3f6a6: docs/queries/*.md, docs/queued-work.md, docs/jobs.md, docs/migrations/query-scheduling-exports/README.md, docs/compliance/control-coverage.md controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-005, TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Queries service module ## What This Service Is For Queries supplies the common dataset vocabulary, execution engine, reusable questions and presentations, person-requested files and recurring delivery. It also implements assisted drafting and staff custom-table authoring. ## Boundary Source records, metadata, authorization, model invocation, communication delivery and physical storage have distinct owners. Explorer and workspace packages belong to separate service modules even where the planning concepts group them together. ## Operations in Words Dataset discovery and execution support interactive questions and recipes. Saved definitions support sharing and dependent presentations. File and schedule operations admit asynchronous work; staff operations manage system queries and custom tables. ## Events and Jobs The contract lists queue messages, database stamp signals and the communication-request integration explicitly. The periodic and queue workers are separate from durable search and snapshot jobs. ## Consistency Guarantees Transactional admission and definition writes are separated from eventual file and delivery effects. Description stamps do not establish a common read snapshot, and terminal status conditions do not establish an exclusive running-worker lease.