From e5ad3f35cb011f64763f3f83885238e46f67400a Mon Sep 17 00:00:00 2001 From: abrichr Date: Thu, 30 Jul 2026 11:50:27 -0400 Subject: [PATCH 1/2] docs: explain qualification-owned entity language --- .../qualification-owned-entity-language.md | 77 +++++++++++++++++++ docs/guides/qualify-a-workflow.md | 22 ++++++ mkdocs.yml | 1 + 3 files changed, 100 insertions(+) create mode 100644 docs/concepts/qualification-owned-entity-language.md diff --git a/docs/concepts/qualification-owned-entity-language.md b/docs/concepts/qualification-owned-entity-language.md new file mode 100644 index 0000000..5e05209 --- /dev/null +++ b/docs/concepts/qualification-owned-entity-language.md @@ -0,0 +1,77 @@ +--- +description: >- + Define the safe entity language that OpenAdapt can show for one qualified + workflow step without sending live record data outside the runner. +--- + +# Qualification-owned entity language + +An attended decision can name the *kind* of item that OpenAdapt must check. +It must not name the live item itself. + +For example, a decision can say: + +- `patient record`; +- `insurance claim`; or +- `loan application`. + +Those labels make an operator question clear. They do not contain a patient +name, account number, claim number, screen text, or another live identifier. + +## Availability + +The signed V2 decision schema and Cloud receiver now preserve a reviewed entity +class and a neutral fallback. The Flow command and Desktop control that set a +class are part of the coordinated V2 release work. Until that release, do not +edit a signed task or sealed artifact by hand to change its wording. + +## Set the label during qualification + +With the coordinated Flow and Desktop release, select one reviewed entity class +for an exact workflow step that can create an attended decision. The class +belongs to that step in that workflow version. It is not a setting for the +whole organization or for all workflows that use the same application. + +The qualification contract records: + +- the exact workflow bundle and revision; +- the exact step; +- the reviewed entity class; and +- a neutral fallback, normally `record` or `item`. + +For example, an OpenEMR check step can use `patient record`. A lending workflow +can use `loan application`. A generic workflow can use `record`. + +## What happens at run time + +When the exact qualified step halts, Flow copies the approved class into the +signed decision task. Cloud and Desktop show that class only when they can +validate the task and recognize its reviewed remote-safe vocabulary. + +The runner keeps the actual identity evidence in its declared customer +boundary. Before it resumes any action, it checks the live identity, current +workflow state, focus, and target again. The label never approves an action by +itself. + +If the signed class is unavailable, unknown, or not supported by the receiving +surface, the surface shows the signed neutral fallback: `record` or `item`. + +## What OpenAdapt does not do + +OpenAdapt does not derive this label at run time. It does not use a screenshot, +OCR, DOM or UIA content, application name, input parameter, or an LLM to decide +that an item is a patient, claim, loan, or another domain object. + +This rule keeps presentation language stable and prevents a remote decision +surface from receiving live entity information merely to choose its wording. + +## Change control + +The class is part of the qualification contract. A change creates a new +qualification revision and invalidates the previous certification. Review the +change, run the required cases, and certify the new sealed version before +deployment. + +See [Qualify a workflow](../guides/qualify-a-workflow.md) for the full +qualification process and [attended decisions](halt-learn-loop.md) for the +operator path. diff --git a/docs/guides/qualify-a-workflow.md b/docs/guides/qualify-a-workflow.md index af78f96..c909d37 100644 --- a/docs/guides/qualify-a-workflow.md +++ b/docs/guides/qualify-a-workflow.md @@ -58,6 +58,28 @@ Each signal declares its source, exact or normalized comparison, and—when needed—its screen region, parameter binding, or extraction rule. Duplicate or conflicting records remain refusal conditions. +## Safe entity language for attended decisions + +The released signed decision schema and Cloud receiver can preserve an approved +entity class and neutral fallback. The Flow and Desktop controls that set the +class are in the coordinated V2 release work. + +After that release, a qualification author selects a static class for each step +that can halt for an operator. For example, use `patient record`, `insurance +claim`, or `loan application`. This class describes the kind of item. It never +contains the live identity of the item. + +The class and a neutral `record` or `item` fallback become part of the exact +qualification contract. A signed decision task carries the approved class to a +remote operator surface. The receiver renders only reviewed safe classes and +uses the fallback when it cannot validate the class. A class change creates a +new qualification revision and requires recertification. + +OpenAdapt never infers this language from a screen, OCR, parameters, an +application name, or a model. See [qualification-owned entity +language](../concepts/qualification-owned-entity-language.md) for the complete +rule and current release status. + ## Bind the resulting business effect Identity proves OpenAdapt is acting on the intended record. Effect verification diff --git a/mkdocs.yml b/mkdocs.yml index 102aefc..60dfdcc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -139,6 +139,7 @@ nav: - Policy and certify: concepts/policy-and-certify.md - Effect verification: concepts/effect-verification.md - The identity gate: concepts/identity-gate.md + - Qualification-owned entity language: concepts/qualification-owned-entity-language.md - Operate: - Run a deployment: guides/run-a-deployment.md - Read and audit run reports: guides/run-reports.md From 72ff5cb9e3d69eeae7d4e864c8bd061b97716b4e Mon Sep 17 00:00:00 2001 From: abrichr Date: Thu, 30 Jul 2026 11:52:21 -0400 Subject: [PATCH 2/2] docs: clarify entity label release boundary --- docs/concepts/qualification-owned-entity-language.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/concepts/qualification-owned-entity-language.md b/docs/concepts/qualification-owned-entity-language.md index 5e05209..c115e88 100644 --- a/docs/concepts/qualification-owned-entity-language.md +++ b/docs/concepts/qualification-owned-entity-language.md @@ -32,6 +32,9 @@ for an exact workflow step that can create an attended decision. The class belongs to that step in that workflow version. It is not a setting for the whole organization or for all workflows that use the same application. +The qualification author sets the class once while they create or revise that +workflow version. OpenAdapt does not ask for a class during each run. + The qualification contract records: - the exact workflow bundle and revision; @@ -44,9 +47,11 @@ can use `loan application`. A generic workflow can use `record`. ## What happens at run time -When the exact qualified step halts, Flow copies the approved class into the -signed decision task. Cloud and Desktop show that class only when they can -validate the task and recognize its reviewed remote-safe vocabulary. +After the coordinated Flow and Desktop release, when the exact qualified step +halts, Flow copies the approved class into the signed decision task. Cloud and +Desktop show that class only when they can validate the task and recognize its +reviewed remote-safe vocabulary. Desktop does not read this label before that +release. The runner keeps the actual identity evidence in its declared customer boundary. Before it resumes any action, it checks the live identity, current