From 2bc887098946e00cc7e45b77f4f3475e66a3484e Mon Sep 17 00:00:00 2001 From: abrichr Date: Thu, 6 Aug 2026 00:34:28 +0200 Subject: [PATCH 1/2] docs: clarify governed decisions --- docs/concepts/halt-learn-loop.md | 29 +++++++++++++++++++++++++++++ docs/guides/qualify-a-workflow.md | 13 ++++++------- docs/reference/glossary.md | 15 +++++++++++++++ 3 files changed, 50 insertions(+), 7 deletions(-) diff --git a/docs/concepts/halt-learn-loop.md b/docs/concepts/halt-learn-loop.md index 73a4d76c..59c333fc 100644 --- a/docs/concepts/halt-learn-loop.md +++ b/docs/concepts/halt-learn-loop.md @@ -9,6 +9,22 @@ when that person teaches the fix**, which is the halt-learn loop proper. Both halves refuse rather than guess. Neither hands control to a free-form agent, and neither puts a model call on the runtime path. +## Terms used here + +- **BYOC** means bring your own cloud: a customer-owned cloud runner and + storage boundary. It is one form of customer-controlled execution. +- An **effect verifier** independently reads the system of record to confirm a + declared write. It does not treat a screen message as proof. +- **Qualification** is the versioned evidence that one exact workflow behaves + correctly in its named application, environment, and execution surface. +- An **identity gate** checks the intended record before a consequential action + and halts if it cannot verify that record. +- **Reconciliation** rechecks a possible or conflicting effect without + re-dispatching the action. + +See the [full glossary](../reference/glossary.md) for the shared terms and +their contract boundaries. + ## Where a halt goes: the attended decision When a run cannot confirm something, it stops and projects the paused step into @@ -20,6 +36,19 @@ ambiguity, a human-only step, saved-result verification, uncertain delivery, or a required halt. The runner offers only the actions that are safe for that request. +### Operational decisions are bounded; business judgment stays human + +An attended decision manages an **operational halt**. It can ask an authorized +operator to prepare the live state, stop, skip an explicitly permitted step, +escalate, teach a correction, or reconcile a possible effect. The signed task +binds the exact run, pause, permitted actions, and revalidation requirements. + +It does not ask OpenAdapt to make arbitrary business judgment. A workflow that +needs a business choice must either express that choice as a reviewed typed +decision contract with permitted actions and a verifiable outcome, or stop for +a human to complete the action. After either path, the runner rechecks the live +identity, state, and configured effect before it reports `VERIFIED` or resumes. + The question is closed by construction. `openadapt-flow` projects the pause into a signed task carrying typed categories, bounded counts, and digests; the client owns every sentence a person reads. The runner never sends prose and the phone diff --git a/docs/guides/qualify-a-workflow.md b/docs/guides/qualify-a-workflow.md index 7a07e7d1..b355b50a 100644 --- a/docs/guides/qualify-a-workflow.md +++ b/docs/guides/qualify-a-workflow.md @@ -60,18 +60,17 @@ 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. +The released signed decision schema can preserve an approved entity class and +neutral fallback in the qualification contract. The class is optional presentation metadata. It does not require a separate author role, and its absence does not block qualification, certification, or execution. -After that release, the person or tool that prepares the qualification can -select a static class for a 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 person or tool that prepares the qualification can select a static class +for a 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 diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 488ffd7e..11f0ca89 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -50,6 +50,14 @@ document hash, not the pixels — and a non-confirmed verdict halts the run. Reports record them as one-way SHA-256 digests. See [Effect verification](../concepts/effect-verification.md). +## Effect verifier + +An **effect verifier** is the configured independent read that evaluates an +[effect contract](#effect-contract). It reads the system of record, such as an +API, database, audit feed, or document store. A verifier does not infer a +write from screen pixels. Its confirmed, refuted, or indeterminate result +decides whether the run can continue. + ## Halt The runtime's fail-closed refusal to act: when identity, a postcondition, an @@ -68,6 +76,13 @@ wrong-record guard. A conflict or an unreadable identity band halts the run rather than clicking into the wrong record. See [The identity gate](../concepts/identity-gate.md). +## Reconciliation + +**Reconciliation** is a no-re-dispatch check after delivery is uncertain or an +effect conflicts with the requested result. The runner reads the required +postcondition and independent effect again. It reports a reconciled result only +when that read proves the effect; otherwise the run stays halted for review. + ## Policy A reviewable YAML document (or built-in, such as `clinical-write`) stating From 9e7ef60c72dc123e916a5aa5c5d7efee9966d345 Mon Sep 17 00:00:00 2001 From: abrichr Date: Thu, 6 Aug 2026 00:49:27 +0200 Subject: [PATCH 2/2] docs: state entity-label release boundary --- docs/guides/qualify-a-workflow.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/guides/qualify-a-workflow.md b/docs/guides/qualify-a-workflow.md index b355b50a..3747ab4f 100644 --- a/docs/guides/qualify-a-workflow.md +++ b/docs/guides/qualify-a-workflow.md @@ -60,23 +60,28 @@ conflicting records remain refusal conditions. ## Safe entity language for attended decisions -The released signed decision schema can preserve an approved entity class and -neutral fallback in the qualification contract. +The released `HumanDecisionTaskV2` schema and Cloud receiver define the target +contract for an approved entity class and neutral fallback. Flow 1.30.0 emits +only `HumanDecisionTaskV1`: it does not yet store or emit the V2 +qualification-bound entity class. Until the coordinated Flow and Desktop +release, use the neutral `record` or `item` wording and do not edit a signed +task or sealed artifact by hand. The class is optional presentation metadata. It does not require a separate author role, and its absence does not block qualification, certification, or execution. -The person or tool that prepares the qualification can select a static class -for a 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 no class was set or when it cannot validate the class. -A class change creates a new qualification revision and requires +With the coordinated release, the person or tool that prepares the +qualification can select a static class for a 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 target contract binds the class and a neutral `record` or `item` fallback +to the exact qualification. A signed V2 decision task carries the approved +class to a remote operator surface. The receiver renders only reviewed safe +classes and uses the fallback when no class was set or 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