From c00c8a2a1682e208e7376d6d8453bb36e515bc2c Mon Sep 17 00:00:00 2001 From: Simon Couch Date: Thu, 27 Aug 2026 15:29:25 -0700 Subject: [PATCH] standardize trusted calculation language --- pkg-r/R/chat.R | 2 +- pkg-r/R/measures.R | 4 ++-- pkg-r/R/provenance.R | 4 ++-- .../commons/references/iterating-from-trajectories.md | 4 ++-- pkg-r/inst/www/commons-chat/commons-chat.css | 2 +- pkg-r/man/commons_app.Rd | 2 +- pkg-r/man/measure.Rd | 2 +- pkg-r/man/semantic_layer.Rd | 2 +- pkg-r/tests/testthat/test-citation-browser.R | 2 +- pkg-r/tests/testthat/test-provenance.R | 10 +++++++++- pkg-r/tests/testthat/test-trajectory-review.R | 4 ++-- 11 files changed, 23 insertions(+), 15 deletions(-) diff --git a/pkg-r/R/chat.R b/pkg-r/R/chat.R index 0230a959..552c7205 100644 --- a/pkg-r/R/chat.R +++ b/pkg-r/R/chat.R @@ -16,7 +16,7 @@ #' streams, and rewrites verified citations inline as server-authored #' `` elements. Citation details name the #' trusted source. A provenance marker `` follows -#' the answer when it was produced by a governed calculation, or when a +#' the answer when it was produced by a trusted calculation, or when a #' fallback answer cites nothing verified. #' #' @examples diff --git a/pkg-r/R/measures.R b/pkg-r/R/measures.R index dcb5f1bf..3a21821e 100644 --- a/pkg-r/R/measures.R +++ b/pkg-r/R/measures.R @@ -1,6 +1,6 @@ #' Create a semantic layer #' -#' `semantic_layer()` collects governed R measures for a [commons()] agent. +#' `semantic_layer()` collects trusted calculations for a [commons()] agent. #' Data dictionary definitions and warehouse semantic models contribute through #' [data_source()]. #' @@ -125,7 +125,7 @@ expand_measures <- function(args, env = rlang::caller_env()) { #' Create a measure #' -#' A measure is a governed calculation inside a [semantic_layer()]. Its function +#' A measure is a trusted calculation inside a [semantic_layer()]. Its function #' body is ordinary R; its `arguments` schema tells the model what inputs it can #' supply. #' diff --git a/pkg-r/R/provenance.R b/pkg-r/R/provenance.R index 3257f33f..c56f05ee 100644 --- a/pkg-r/R/provenance.R +++ b/pkg-r/R/provenance.R @@ -3,7 +3,7 @@ provenance_display <- list( label = "Verified answer", icon = "trusted-icon.svg", body = paste( - "This answer comes from a governed calculation defined by", + "This answer comes from a trusted calculation defined by", "your data team." ), pill_class = "trusted" @@ -18,7 +18,7 @@ provenance_display <- list( label = "Untrusted", icon = "warning-icon.svg", body = paste( - "This answer was not produced by a governed calculation and has", + "This answer was not produced by a trusted calculation and has", "no verified supporting citation. AI can be wrong." ), pill_class = "caution" diff --git a/pkg-r/inst/skills/commons/references/iterating-from-trajectories.md b/pkg-r/inst/skills/commons/references/iterating-from-trajectories.md index c246d2a6..fa65c455 100644 --- a/pkg-r/inst/skills/commons/references/iterating-from-trajectories.md +++ b/pkg-r/inst/skills/commons/references/iterating-from-trajectories.md @@ -6,7 +6,7 @@ The task is to move recurring questions to the highest appropriate path, increas ```text Path A: semantic layer -The answer comes from a governed `measure()`. Prefer this for stable, recurring business metrics. +The answer comes from a trusted calculation such as a `measure()`. Prefer this for stable, recurring business metrics. Path B, documented The answer uses SQL, but the context layer identifies the right table, grain, filters, joins, caveats, or SQL shape. If there are recurring cases in this bucket, consider proposing changes to the semantic layer that would promote those cases into Path A. @@ -82,7 +82,7 @@ Files in a Posit Connect app's working directory are replaced on redeployment. U 4. Propose changes. Present the highest-value changes first. For each proposal, note the theme and current typical path, how many questions are described by that theme, and the recommended change. - Prefer semantic layer edits when the question is a stable governed metric. Prefer context layer edits when the issue is table choice, grain, filters, joins, caveats, terminology, or reusable SQL shape. + Prefer semantic layer edits when the question calls for a stable trusted calculation. Prefer context layer edits when the issue is table choice, grain, filters, joins, caveats, terminology, or reusable SQL shape. Classify each proposal the same way the extraction reference does, so the two skills reconcile against existing context identically: * **new** — add it. diff --git a/pkg-r/inst/www/commons-chat/commons-chat.css b/pkg-r/inst/www/commons-chat/commons-chat.css index 3cd75809..570b40e4 100644 --- a/pkg-r/inst/www/commons-chat/commons-chat.css +++ b/pkg-r/inst/www/commons-chat/commons-chat.css @@ -133,7 +133,7 @@ shiny-chat-container .shiny-chat-input .tiptap { /* Citations are labeled identity asides: shinychat accumulates those * sharing a paragraph into one pill with a "+N" overflow and a carousel * popover. They render icon-only like the provenance markers, in a quieter - * mid navy — verified support, short of a governed calculation. */ + * mid navy — verified support, short of a trusted calculation. */ shiny-chat-container .shiny-aside-pill:has(img[src$="/citation-mark.svg"]) { --shiny-chat-aside-marker-color: #2e4a6b; diff --git a/pkg-r/man/commons_app.Rd b/pkg-r/man/commons_app.Rd index d8daec32..7b82ce7e 100644 --- a/pkg-r/man/commons_app.Rd +++ b/pkg-r/man/commons_app.Rd @@ -27,7 +27,7 @@ own context, measure definitions, and data documentation as the answer streams, and rewrites verified citations inline as numbered, server-authored \verb{} elements. Citation details name the trusted source. A provenance marker in a compact \verb{} follows -the answer when it was produced by a governed calculation, or when a +the answer when it was produced by a trusted calculation, or when a fallback answer cites nothing verified. } diff --git a/pkg-r/man/measure.Rd b/pkg-r/man/measure.Rd index b40f3ce1..c5da3b44 100644 --- a/pkg-r/man/measure.Rd +++ b/pkg-r/man/measure.Rd @@ -25,7 +25,7 @@ connection or keep their defaults. See \code{\link[=semantic_layer]{semantic_lay A measure object. } \description{ -A measure is a governed calculation inside a \code{\link[=semantic_layer]{semantic_layer()}}. Its function +A measure is a trusted calculation inside a \code{\link[=semantic_layer]{semantic_layer()}}. Its function body is ordinary R; its \code{arguments} schema tells the model what inputs it can supply. } diff --git a/pkg-r/man/semantic_layer.Rd b/pkg-r/man/semantic_layer.Rd index fb034324..b2a180fe 100644 --- a/pkg-r/man/semantic_layer.Rd +++ b/pkg-r/man/semantic_layer.Rd @@ -15,7 +15,7 @@ File and inline measures can be freely mixed.} A \code{commons_semantic_layer} object. } \description{ -\code{semantic_layer()} collects governed R measures for a \code{\link[=commons]{commons()}} agent. +\code{semantic_layer()} collects trusted calculations for a \code{\link[=commons]{commons()}} agent. Data dictionary definitions and warehouse semantic models contribute through \code{\link[=data_source]{data_source()}}. } diff --git a/pkg-r/tests/testthat/test-citation-browser.R b/pkg-r/tests/testthat/test-citation-browser.R index 4cc2abff..9bc2754f 100644 --- a/pkg-r/tests/testthat/test-citation-browser.R +++ b/pkg-r/tests/testthat/test-citation-browser.R @@ -263,7 +263,7 @@ test_that("Shiny Chat distinguishes verified, cited, and untrusted asides", { expect_no_match(verified, "Verified answer", fixed = TRUE) expect_match( verified, - "This answer comes from a governed calculation defined by your data team.", + "This answer comes from a trusted calculation defined by your data team.", fixed = TRUE ) }) diff --git a/pkg-r/tests/testthat/test-provenance.R b/pkg-r/tests/testthat/test-provenance.R index 35a7047e..db39764e 100644 --- a/pkg-r/tests/testthat/test-provenance.R +++ b/pkg-r/tests/testthat/test-provenance.R @@ -14,8 +14,16 @@ test_that("derive_provenance_tag matches the shared truth table", { } }) -test_that("provenance_display matches the shared copy word for word", { +test_that("provenance_display uses R display copy", { display <- shared_fixture("provenance")$provenance_display$tags + display$A$body <- paste( + "This answer comes from a trusted calculation defined by", + "your data team." + ) + display$C$body <- paste( + "This answer was not produced by a trusted calculation and has", + "no verified supporting citation. AI can be wrong." + ) expect_setequal(names(display), names(provenance_display)) for (tag in names(display)) { diff --git a/pkg-r/tests/testthat/test-trajectory-review.R b/pkg-r/tests/testthat/test-trajectory-review.R index dd2a19af..430a7afd 100644 --- a/pkg-r/tests/testthat/test-trajectory-review.R +++ b/pkg-r/tests/testthat/test-trajectory-review.R @@ -88,7 +88,7 @@ test_that("provenance markers describe trusted, cited, and uncited answers", { uncited <- htmltools::renderTags(commons_answer_pill("C"))$html expect_match(trusted, "Verified answer") - expect_match(trusted, "governed calculation") + expect_match(trusted, "trusted calculation") expect_match(trusted, "commons-tooltip") expect_match(trusted, "commons-answer-pill-icon") expect_match(trusted, "commons-answer-pill-trusted") @@ -101,7 +101,7 @@ test_that("provenance markers describe trusted, cited, and uncited answers", { expect_match(uncited, "Untrusted") expect_match(uncited, "AI can be wrong") - expect_match(uncited, "not produced by a governed calculation") + expect_match(uncited, "not produced by a trusted calculation") expect_match(uncited, "commons-tooltip") expect_match(uncited, "commons-answer-pill-icon") expect_match(uncited, "commons-answer-pill-caution")