From 772fb4a4c704562e17b99eadee701b34b24e7a21 Mon Sep 17 00:00:00 2001 From: abrichr Date: Sat, 29 Aug 2026 14:47:19 -0400 Subject: [PATCH 1/2] docs: publish the Seal as Execute proof The compiler stays MIT. The closed object is ExecuteEvidenceReceiptV1. Partner CLI story is `openadapt-flow replay bundle --seal`. Public verify is https://openadapt.ai/seals/{id} (synthetic only). Oracle tiers 0-1 never mint a production Seal. Attended and unattended are two modes. Skip execute-api.md: openadapt-ops#181 already owns that page. Signed-off-by: abrichr --- docs/commercial/oem-brief.md | 103 +++++++++++++++------- docs/commercial/seal.md | 143 +++++++++++++++++++++++++++++++ docs/get-started/index.md | 21 +++++ docs/get-started/what-you-get.md | 4 + docs/llms.txt | 1 + docs/reference/glossary.md | 15 ++++ mkdocs.yml | 1 + 7 files changed, 255 insertions(+), 33 deletions(-) create mode 100644 docs/commercial/seal.md diff --git a/docs/commercial/oem-brief.md b/docs/commercial/oem-brief.md index 89e06a6a..b0a630ce 100644 --- a/docs/commercial/oem-brief.md +++ b/docs/commercial/oem-brief.md @@ -6,15 +6,27 @@ integrate with. Your product decides the business action. OpenAdapt executes the qualified transaction in the customer-controlled browser, desktop, RDP, Citrix, or API -environment. It then returns a precise outcome and a receipt. +environment. It then returns a Seal: `ExecuteEvidenceReceiptV1`. Unsigned +success is failure. ```text authorized transaction -> qualified local execution -> effect verification - -> verified | a precise non-success outcome + receipt + -> Seal (verified | halt | reconciliation_required) ``` +The one CLI story: + +```bash +openadapt-flow replay bundle --seal +``` + +A sealed verified run prints `VERIFIED`, a seal id, and +`https://openadapt.ai/seals/`. That route is synthetic and non-PHI only. +`--seal` on replay issues the proof. `openadapt flow seal` encrypts a bundle +for deployment. + This is a good fit for a vertical software vendor, an RCM provider, a BPO, or an integration firm. The provider already has structured inputs, business logic, and an exception team. OpenAdapt supplies the verified last action in @@ -132,6 +144,26 @@ does not infer a class or an identity from a screenshot, OCR, an application name, parameters, or a model. If the class is unavailable, it uses `record` or `item`. The runner rechecks the real identity before any resumed action. +## Two modes: attended and unattended + +Pitch these separately. + +**Attended.** A person is in session. The runner uses that session. Consequential +writes pause for a signed phone or console answer, then recheck live identity +and state. This is the mode you can sell now. The human remains the legal +actor. A Seal is not a physician signature. + +**Unattended.** Needs a dedicated agent identity, PAM, and session recording. It +does not type a physician password. + +Halt UX is the commercial product: who gets the push, what they see, how they +teach one step without invalidating the bundle, and how "click continue" is +refused. + +Oracle tiers 0 (visual) and 1 (second-session UI) never mint a production Seal. +Charge 2 (system of record) and 3 (counterparty artifact) only. See +[The Seal](seal.md). + ## Attended decisions and mobile delivery When the runner cannot prove a required condition, it creates one signed, @@ -143,7 +175,7 @@ boundary. An operator answer is not a command to repeat a write. The runner first reacquires focus, a fresh observation, the workflow state, identity evidence, -and the target. It continues only if those checks pass. The resulting receipt +and the target. It continues only if those checks pass. The resulting Seal binds the decision, the runner transition, and the final state to the exact task and authorization. @@ -182,26 +214,28 @@ event stream does not contain raw screenshots or live record data. ## Receipts and partner integration -### ExecuteEvidenceReceiptV1 - -Every terminal execution returns an `ExecuteEvidenceReceiptV1` with exactly -these public fields: +### ExecuteEvidenceReceiptV1 is the Seal -- `schema_version: openadapt.execute-evidence-receipt/v1`; -- `receipt_id`, `execution_id`, and `workflow_digest`; -- the terminal `outcome`; -- `contracts`: `authorization_passed`, `identity_passed`, - `postcondition_passed`, `effect_passed`, `minimum_effect_strength`, optional - `observed_effect_strength`, `model_used`, and `external_network_used`; -- `delivery_uncertain`; -- `compensation_effect_verified`: always present, normally `false`, and `true` - only when the outcome is `rolled_back_verified`; -- `evidence_digest`; and -- `issued_at`. +Every terminal execution returns an `ExecuteEvidenceReceiptV1`. That object is +the Seal. Map the receipt fields 1:1. -The status resource supplies the receipt identifier only when its state is -`terminal`. It also supplies the terminal outcome. This keeps an in-progress -state separate from a final outcome. +| Receipt field | Seal field | +|---|---| +| `receipt_id` | Seal id. Verify at `https://openadapt.ai/seals/{receipt_id}` (synthetic only). | +| `execution_id` | The `POST /v1/executions` that produced this Seal | +| `workflow_digest`, `workflow_version` | Admitted program | +| `qualification_id`, `environment_id`, `runner_id`, `nonce` | Admission, environment, runner, uniqueness | +| `oracle_tier` | 0 visual, 1 second-session, 2 SoR, 3 counterparty | +| `outcome` | `verified` / halt / `reconciliation_required` / the other terminal values | +| `contracts` | Authorization, identity, postcondition, effect | +| `evidence_digest` | Pointer to retained evidence. Bytes stay in the boundary. | +| `issued_at` | When the Seal was issued | + +`verified` requires `oracle_tier` 2 or 3. HTTP `202` is not a Seal. The status +resource supplies `evidence_receipt_id` only when its state is `terminal`. + +Consequential MCP tools advertise `requires_seal: true`. If the tool returns +unsigned success, treat it as failure. ### Local and private evidence @@ -211,14 +245,14 @@ bindings, runner and environment details, report bodies, screenshots, live identity checks, and application observations. The public receipt identifies that evidence by digest. It does not copy it into the partner event stream. -The partner stores the receipt with its own transaction record. This lets the -partner tell an end customer what happened without using a screenshot or a UI -banner as proof. +The partner stores the Seal with its own transaction record. That is what you +show an end customer. A screenshot or a UI banner is not proof. Private-pilot integrations use signed, versioned webhook events and polling. Webhook retry, signature verification, ordering, and event deduplication are part of the Execute contract. The [Execute integration guide](execute-api.md) -shows the request, status, receipt, and webhook flow. +shows the request, status, Seal, and webhook flow. The field map lives on +[The Seal](seal.md). ## Start with one workflow @@ -236,14 +270,17 @@ commercial compatibility pack. | Layer | Availability | Role | |---|---|---| -| OpenAdapt Flow | MIT-licensed | Local compiler, governed runtime, transaction outcomes, qualification tools, and receipt mechanisms. | -| `openadapt-types` 0.9.0 | MIT-licensed and released | Shared async Execute schema and OpenAPI document, plus signed decision-task and decision-receipt contracts. | -| OpenAdapt Cloud foundation | Private and deployed | Tenant control plane, private Execute endpoints, customer-runner coordination, signed decision relay, audit records, and managed operations. | -| OpenAdapt Execute | Private pilot | Versioned transaction submission, status, receipt delivery, and partner integration for approved pilot partners. | -| Compatibility packs and verifier recipes | Commercial | Per-application and per-environment qualification assets, deployment evidence, and support. | - -The open runtime remains inspectable. The commercial value is the qualified -transaction, customer-environment evidence, operational delivery, and support. +| OpenAdapt Flow | MIT-licensed | Local compiler, governed runtime, halt/teach, qualification tools. Compile-once is a cache. | +| `openadapt-types` | MIT-licensed | Shared Execute schema. The evidence receipt is the Seal. | +| OpenAdapt Cloud foundation | Private and deployed | Tenant control plane, customer-runner coordination, signed decision relay. | +| OpenAdapt Execute | Private pilot | `POST /v1/executions` issues Seals. Not a new repository. | +| Compatibility packs and verifier recipes | Commercial | Per-application and per-environment qualification assets. Bundles are not liquid. | + +Embed through Execute and MCP into RCM vendors and agent platforms. Hospital IT +RFPs are not the growth engine. If Copilot or Power Automate already clicked, +OpenAdapt can still emit the Seal. + +The compiler stays inspectable. Settlement is the Seal. ## Next step diff --git a/docs/commercial/seal.md b/docs/commercial/seal.md new file mode 100644 index 00000000..87c1299d --- /dev/null +++ b/docs/commercial/seal.md @@ -0,0 +1,143 @@ +# The Seal + +A Seal is a signed attestation that this program version, this identity, this +environment, and this independent effect produced a terminal outcome. The +portable object is `ExecuteEvidenceReceiptV1`. Execute issues it. Execute is +the invoke path, not a separate product. + +`POST /api/v1/executions` is the partner invoke. The terminal receipt is the +Seal. Local unsigned `openadapt-flow replay` stays free. Unsigned success is +failure: if a consequential tool returns done without a Seal, treat the call as +failed. + +The compiler stays MIT. Record, compile, replay, halt, teach, `openadapt-types`, +local MCP, and Agent Skills stay inspectable. Settlement is the Seal. + +Public verify pages list synthetic and non-PHI Seals. They do not list +healthcare production. Bundles are bound to one app build, one farm, one +resolution, one custom screen. Do not publish a public healthcare procedure +npm. + +## Oracle tiers + +Charge tiers 2 and 3. Tiers 0 and 1 never mint a production Seal. + +| Tier | What it reads | Production Seal | +|---|---|---| +| 0 | Visual / OCR of the same screen that acted | Never. Dev only. | +| 1 | Second session or independent UI read | Never. | +| 2 | System-of-record read (API, database, file, ack) | Yes. | +| 3 | Counterparty artifact (payer status, legal export) | Yes. | + +`oracle_tier` on the receipt must match `contracts.observed_effect_strength`. +`independent_system_of_record` maps to 2. `independent_session` maps to 1. +Screen confirmation and persisted-state reacquisition map to 0. Tier 3 has no +`EffectStrengthV1` member yet; it is a stronger independent artifact, not a +banner on the acting screen. + +`--break-it` on `openadapt-flow qualify` is the fail-closed test. A fake success +banner must halt. The store must stay unchanged. + +A Seal that points at a screenshot hash is a liability. Do not mint production +`verified` below tier 2. + +## Two modes + +Attended and unattended are two products. Pitch them separately. + +**Attended.** A person is already in session. The runner uses that session. A +consequential write pauses at `decision_required`. The operator answers from +the local console or the authenticated phone surface. The runner then +reacquires focus, a fresh observation, identity, and the target before it +continues. Sell this first. The human remains the legal actor. A Seal is not a +physician signature. + +**Unattended.** Needs a dedicated agent identity, PAM, and session recording. It +does not type a physician password and it does not share a service account. + +Halt UX is the commercial product. Who gets the 2 a.m. push, what they see, how +they teach one step without invalidating the bundle, and how "click continue" +is refused: that is renewal. + +## CLI story + +On a qualified synthetic bundle with a tier-2 oracle: + +```bash +openadapt-flow replay bundle --seal +``` + +A sealed verified run prints `VERIFIED`, a seal id, and the public verify URL: + +```text +VERIFIED +seal_id receipt_12345678 +verify https://openadapt.ai/seals/receipt_12345678 +``` + +`--seal` on replay issues that proof. `openadapt flow seal` encrypts a bundle +for deployment. + +The same verb is available as `openadapt flow replay bundle --seal`. Use the +standalone `openadapt-flow` form when you installed the engine package. + +The verify route is `https://openadapt.ai/seals/{id}`. Synthetic fixtures only +on that page. + +## Receipt fields are Seal fields + +`ExecuteEvidenceReceiptV1` is the Seal. Map the receipt 1:1. + +| Receipt field | Seal field | What it binds | +|---|---|---| +| `receipt_id` | Seal id | Public verify at `https://openadapt.ai/seals/{receipt_id}` | +| `execution_id` | execution | The `POST /v1/executions` that produced this Seal | +| `workflow_digest` | program digest | SHA-256 of the admitted compiled program | +| `workflow_version` | program version | Qualified version id | +| `qualification_id` | admission | The qualification pack that authorized the run | +| `environment_id` | environment | The qualified environment | +| `runner_id` | runner | The customer-controlled runner | +| `nonce` | nonce | Per-Seal uniqueness so a consumer does not need the original request | +| `oracle_tier` | oracle | 0 visual, 1 second-session, 2 SoR, 3 counterparty | +| `outcome` | outcome | `verified`, `halted_before_effect`, `reconciliation_required`, `rejected_policy`, `failed_platform`, or `rolled_back_verified` | +| `contracts` | contracts | Authorization, identity, postcondition, effect, required and observed strength, `model_used`, `external_network_used` | +| `delivery_uncertain` | delivery | True when a write may have landed | +| `compensation_effect_verified` | compensation | True only for `rolled_back_verified` | +| `evidence_digest` | evidence | Pointer to retained evidence. Bytes stay in the declared boundary. | +| `issued_at` | issued | When the Seal was issued | +| `schema_version` | schema | Always `openadapt.execute-evidence-receipt/v1` | + +`verified` requires every contract, an observed strength at or above the +minimum, and `oracle_tier` 2 or 3. Store the full object with the partner +transaction. HTTP `202` is not a Seal. + +## `requires_seal` + +Consequential MCP tools advertise `requires_seal: true`. Skill text: if the +tool returns unsigned success, treat it as failure. + +```json +{ + "name": "replay_program", + "requires_seal": true +} +``` + +Emit a local MCP server with `openadapt flow emit-mcp bundle --out server.py`. +The partner still validates the Seal the same way: `receipt_id`, +`workflow_digest`, `oracle_tier`, and `outcome`. + +## How it ships + +Embed through Execute and MCP into RCM vendors and agent platforms. Hospital +IT RFPs are not the growth engine. + +If another actuator already clicked (Power Automate, Copilot, a vendor bot), +OpenAdapt can still issue the Seal. Until a counterparty demands that proof, +distribution stays with the incumbent. Coexist. + +Compile-once is a cache when the job is stable. If a computer-use agent gets +cheap, the run still has to prove identity and effect, or halt. + +Partner API contract: [Integrate OpenAdapt Execute](execute-api.md). +OEM embedding: [OpenAdapt Execute private-pilot guide](oem-brief.md). diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 0c4cc438..fedbc808 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -83,6 +83,26 @@ Open `graph.html` in a browser. That page is the compiled program: the steps it can take, the evidence each one needs, and the paths that stop the run. See [Read a compiled program](../concepts/program-visualizer.md). +The tutorial receipt is local and unsigned. Anyone who has to believe the run +needs a Seal. On a qualified synthetic bundle with a tier-2 oracle: + +```bash +openadapt-flow replay bundle --seal +``` + +A sealed verified run prints `VERIFIED`, a seal id, and a public verify URL: + +```text +VERIFIED +seal_id receipt_12345678 +verify https://openadapt.ai/seals/receipt_12345678 +``` + +`--seal` on replay issues that proof. `openadapt flow seal` encrypts a bundle +for deployment. Public `/seals/` pages list synthetic fixtures. They do not +list healthcare production. Oracle tiers 0 (visual) and 1 (second-session UI) +never mint a production Seal. See [The Seal](../commercial/seal.md). + When you move from the tutorial to your own work, qualification tests the workflow against real failures in its environment before it runs. @@ -92,6 +112,7 @@ After the first run, choose the path that matches your goal: |---|---| | Record one real, read-only browser workflow | [Your first workflow](first-workflow.md) | | See what the compiled program looks like | [Read a compiled program](../concepts/program-visualizer.md) | +| Issue a Seal on a synthetic run | [The Seal](../commercial/seal.md) | | Use the Desktop application | [Install Desktop](../desktop/install.md) | | Use native desktop, RDP, or Citrix | [Install a different execution surface](#install-a-different-execution-surface) | | Prepare a qualified production run | [Move from demo to deployment](#move-from-demo-to-deployment) | diff --git a/docs/get-started/what-you-get.md b/docs/get-started/what-you-get.md index 2b2e240d..500cbc20 100644 --- a/docs/get-started/what-you-get.md +++ b/docs/get-started/what-you-get.md @@ -52,6 +52,10 @@ openadapt flow emit-skill bundle --out skills/ openadapt flow emit-mcp bundle --out server.py ``` +Consequential tools advertise `requires_seal: true`. If the tool returns +unsigned success, treat it as failure. The Seal is `ExecuteEvidenceReceiptV1`. +See [The Seal](../commercial/seal.md). + ## Privacy of the artifacts The `REPORT.md` and console logs can be processed by the PHI/PII sanitizer on the diff --git a/docs/llms.txt b/docs/llms.txt index f29cfc86..d8462283 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -7,6 +7,7 @@ - [Qualification evidence](https://docs.openadapt.ai/get-started/what-works-today/): Accepted substrate results, exact environments, and deployment boundaries - [Your first workflow](https://docs.openadapt.ai/get-started/first-workflow/): Install the base package, then record, compile, lint, replay, and read the report on your own web app - [What you get](https://docs.openadapt.ai/get-started/what-you-get/): The workflow bundle, the run report, and what each artifact is for +- [The Seal](https://docs.openadapt.ai/commercial/seal/): Signed proof of a verified, halted, or reconciling run. `openadapt-flow replay bundle --seal`. Public verify at `https://openadapt.ai/seals/{id}` (synthetic only) ## Desktop app - [Install and first run](https://docs.openadapt.ai/desktop/install/): Desktop cockpit for record, compile, replay, and teach; a first-class front end over the same engine as the openadapt flow CLI diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index c8a9b284..a838f854 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -76,6 +76,13 @@ wrong-record guard). A conflict or an unreadable identity band halts the run instead of clicking into the wrong record. See [The identity gate](../concepts/identity-gate.md). +## Oracle tier + +How a Seal checks the business effect. Tier 0 is visual / OCR. Tier 1 is a +second session or independent UI read. Tier 2 is a system-of-record read (API, +database, file, ack). Tier 3 is a counterparty artifact. Production Seals mint +only at 2 and 3. Charge those two. See [The Seal](../commercial/seal.md). + ## Reconciliation **Reconciliation** is a no-re-dispatch check after delivery is uncertain or an @@ -111,6 +118,14 @@ is the artifact a pilot or deployment reviews. Contrast with [certification](#certification), the policy gate. See [Qualify a workflow](../guides/qualify-a-workflow.md). +## Seal + +A signed attestation that one program version, identity, environment, and +independent effect produced `VERIFIED`, `HALTED`, or +`RECONCILIATION_REQUIRED`. The portable object is `ExecuteEvidenceReceiptV1`. +Execute issues it (`POST /api/v1/executions`). Local unsigned replay stays +free. Unsigned success is failure. See [The Seal](../commercial/seal.md). + ## Substrate The surface a workflow is recorded and executed on: web (browser DOM), native diff --git a/mkdocs.yml b/mkdocs.yml index f76d0ef2..fab44f3f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -183,6 +183,7 @@ nav: - Subprocessors and data retention: commercial/subprocessors.md - Deployment boundaries: commercial/deployment-boundaries.md - External Citrix zero-install brief: commercial/citrix-external-brief.md + - The Seal: commercial/seal.md - OpenAdapt Execute private-pilot guide: commercial/oem-brief.md - Integrate OpenAdapt Execute: commercial/execute-api.md - Procurement FAQ: commercial/procurement-faq.md From 85b146e6850e85d313dcae24fbf69089fbf92b89 Mon Sep 17 00:00:00 2001 From: abrichr Date: Sat, 29 Aug 2026 14:51:52 -0400 Subject: [PATCH 2/2] docs: close Seal sales-motion and oracle-tier gaps Two sales motions, published 0-3 oracle tiers, embed-not-IDN-RFP, Copilot coexistence, and no physician-signature copy now sit on the Seal page, OEM brief, procurement FAQ, sprint, and effect-verification page. --seal remains the intended CLI; Flow does not get a flag while 434-440 are open. Signed-off-by: abrichr --- docs/commercial/oem-brief.md | 43 ++++++++++++------- docs/commercial/procurement-faq.md | 28 ++++++++++++ .../qualification-report-outline.md | 2 +- docs/commercial/qualification-sprint.md | 8 +++- docs/commercial/seal.md | 30 +++++++------ docs/concepts/effect-verification.md | 9 ++++ docs/get-started/index.md | 3 +- 7 files changed, 91 insertions(+), 32 deletions(-) diff --git a/docs/commercial/oem-brief.md b/docs/commercial/oem-brief.md index b0a630ce..80ddf045 100644 --- a/docs/commercial/oem-brief.md +++ b/docs/commercial/oem-brief.md @@ -23,14 +23,15 @@ openadapt-flow replay bundle --seal ``` A sealed verified run prints `VERIFIED`, a seal id, and -`https://openadapt.ai/seals/`. That route is synthetic and non-PHI only. -`--seal` on replay issues the proof. `openadapt flow seal` encrypts a bundle -for deployment. +`https://openadapt.ai/seals/{id}`. That route is synthetic and non-PHI only. +`--seal` on replay is the intended Seal command. `openadapt flow seal` +encrypts a bundle for deployment. -This is a good fit for a vertical software vendor, an RCM provider, a BPO, or -an integration firm. The provider already has structured inputs, business -logic, and an exception team. OpenAdapt supplies the verified last action in -the customer system. +The buyer is the technical owner at a vertical software vendor, an RCM +provider, a BPO, or an agent platform. That company already has structured +inputs, business logic, and an exception team. OpenAdapt supplies the last +action in the customer GUI, then a Seal. Health-system IT is a downstream +environment. Do not staff this motion as an IDN RFP. !!! note "Private pilot. Not a public API." This page describes the private-pilot product contract. It is not an @@ -144,24 +145,34 @@ does not infer a class or an identity from a screenshot, OCR, an application name, parameters, or a model. If the class is unavailable, it uses `record` or `item`. The runner rechecks the real identity before any resumed action. -## Two modes: attended and unattended +## Two sales motions -Pitch these separately. +Do not mix these in one pitch. **Attended.** A person is in session. The runner uses that session. Consequential writes pause for a signed phone or console answer, then recheck live identity -and state. This is the mode you can sell now. The human remains the legal +and state. This is the motion you can sell now. The human remains the legal actor. A Seal is not a physician signature. **Unattended.** Needs a dedicated agent identity, PAM, and session recording. It -does not type a physician password. +does not type a physician password or stuff a physician login. Halt UX is the commercial product: who gets the push, what they see, how they teach one step without invalidating the bundle, and how "click continue" is refused. -Oracle tiers 0 (visual) and 1 (second-session UI) never mint a production Seal. -Charge 2 (system of record) and 3 (counterparty artifact) only. See +## Oracle tiers + +Charge 2 and 3. Tiers 0 and 1 never mint a production Seal. + +| Tier | What it reads | Production Seal | +|---|---|---| +| 0 | Visual / OCR | Never. Dev only. | +| 1 | Second session or independent UI read | Never. | +| 2 | System-of-record read (API, database, file, ack) | Yes. | +| 3 | Counterparty artifact (payer status, legal export) | Yes. | + +The field map, `requires_seal`, and Copilot coexistence live on [The Seal](seal.md). ## Attended decisions and mobile delivery @@ -276,9 +287,9 @@ commercial compatibility pack. | OpenAdapt Execute | Private pilot | `POST /v1/executions` issues Seals. Not a new repository. | | Compatibility packs and verifier recipes | Commercial | Per-application and per-environment qualification assets. Bundles are not liquid. | -Embed through Execute and MCP into RCM vendors and agent platforms. Hospital IT -RFPs are not the growth engine. If Copilot or Power Automate already clicked, -OpenAdapt can still emit the Seal. +Embed through Execute and MCP into RCM vendors and agent platforms. Hospital +IT RFPs are not the growth engine. If Copilot or Power Automate already +clicked, OpenAdapt can still emit the Seal when asked. The compiler stays inspectable. Settlement is the Seal. diff --git a/docs/commercial/procurement-faq.md b/docs/commercial/procurement-faq.md index 87b38fa4..4e006811 100644 --- a/docs/commercial/procurement-faq.md +++ b/docs/commercial/procurement-faq.md @@ -73,6 +73,34 @@ coverage, effect verdicts, heals, model calls, and halt reasons; on-prem adds an append-only hash-chained audit log ([run reports](../guides/run-reports.md)). +## Seal, modes, and embedding + +**What is a Seal?** +`ExecuteEvidenceReceiptV1`. It is the signed proof of one run. Production +`verified` requires oracle tier 2 (system of record) or 3 (counterparty +artifact). Visual/OCR (tier 0) and a second-session UI read (tier 1) never +mint a production Seal. See [The Seal](seal.md). + +**Is a Seal a physician signature?** +No. The human remains the legal actor. A Seal records that the configured +identity, policy, and effect checks passed for that run. + +**Do you sell attended and unattended as one product?** +No. Attended is the motion you can buy now: human session, phone or console +approve consequential writes. Unattended needs a dedicated agent identity, +PAM, and session recording. Do not mix them in one statement of work. Do not +type a physician password. + +**Are we buying a hospital RFP engagement?** +No. Embed through Execute and MCP into an RCM vendor, BPO, vertical SaaS, or +agent platform. Health-system IT is a downstream environment. IDN procurement +is not the growth path. + +**Can Copilot or Power Automate still do the click?** +Yes. OpenAdapt can emit a Seal from another actuator when asked. The +consequential MCP contract is `requires_seal: true`. Unsigned success is +failure. + ## Delivery and risk **What if the software gets it wrong silently?** diff --git a/docs/commercial/qualification-report-outline.md b/docs/commercial/qualification-report-outline.md index 886bfb79..c26809b0 100644 --- a/docs/commercial/qualification-report-outline.md +++ b/docs/commercial/qualification-report-outline.md @@ -51,7 +51,7 @@ Delivered as its own artifact and summarized here. For each step: | Identity armed | Whether a pre-action identity check guards the step, and what evidence it compares ([identity gate](../concepts/identity-gate.md)). | | Identity coverage line | "N of M consequential steps identity-armed", with each unarmed step listed by id and reason. | | Effect contract | For each write: the declared effect (`record_written`, `field_equals`), its selector, and idempotency handling. | -| Verification strength | The strongest available oracle for the effect: independent system interface, independent read-only session, persisted-state reacquisition, or immediate screen confirmation. Screen-only confirmation is labeled as such, never presented as an independent system-of-record check. | +| Verification strength | The strongest available oracle for the effect, named as an oracle tier: 0 visual/OCR, 1 second-session UI, 2 system of record, 3 counterparty artifact. Screen-only confirmation is tier 0 and is labeled as such. Production Seals mint only at 2 or 3. See [The Seal](seal.md). | | Gaps | Every step or write without coverage, and whether policy permits it at this risk class. | ## 5. Representative case results diff --git a/docs/commercial/qualification-sprint.md b/docs/commercial/qualification-sprint.md index 3d85757a..1d7c4ac6 100644 --- a/docs/commercial/qualification-sprint.md +++ b/docs/commercial/qualification-sprint.md @@ -45,8 +45,12 @@ Days on which access is broken or revoked pause the clock. See the customer-controlled production boundary with explicit written approval). - Test data that is representative and safe to modify. - A read path for verification: an API, database, report, or read-only session - through which the business effect can be independently confirmed. See - [effect verification](../concepts/effect-verification.md). + through which the business effect can be independently confirmed. Screen-only + confirmation is oracle tier 0 and never a production Seal. See + [effect verification](../concepts/effect-verification.md) and + [The Seal](seal.md). +- The sales motion: attended (human session, phone approve writes) or + unattended (dedicated agent identity, PAM). Do not mix them in one sprint. - A security contact for boundary and data-handling questions. ## Exclusions diff --git a/docs/commercial/seal.md b/docs/commercial/seal.md index 87c1299d..213a7a8b 100644 --- a/docs/commercial/seal.md +++ b/docs/commercial/seal.md @@ -41,19 +41,20 @@ banner must halt. The store must stay unchanged. A Seal that points at a screenshot hash is a liability. Do not mint production `verified` below tier 2. -## Two modes +## Two sales motions -Attended and unattended are two products. Pitch them separately. +Attended and unattended are two motions. Do not mix them in one pitch. **Attended.** A person is already in session. The runner uses that session. A consequential write pauses at `decision_required`. The operator answers from the local console or the authenticated phone surface. The runner then reacquires focus, a fresh observation, identity, and the target before it -continues. Sell this first. The human remains the legal actor. A Seal is not a -physician signature. +continues. This is the product you can sell now. The human remains the legal +actor. A Seal is not a physician signature. -**Unattended.** Needs a dedicated agent identity, PAM, and session recording. It -does not type a physician password and it does not share a service account. +**Unattended.** Needs a dedicated agent identity, PAM, and session recording. +It does not type a physician password, stuff a physician login, or share a +service account. Treat that as a later motion with its own identity design. Halt UX is the commercial product. Who gets the 2 a.m. push, what they see, how they teach one step without invalidating the bundle, and how "click continue" @@ -61,7 +62,7 @@ is refused: that is renewal. ## CLI story -On a qualified synthetic bundle with a tier-2 oracle: +On a qualified synthetic bundle with a tier-2 oracle, the intended command is: ```bash openadapt-flow replay bundle --seal @@ -129,12 +130,17 @@ The partner still validates the Seal the same way: `receipt_id`, ## How it ships -Embed through Execute and MCP into RCM vendors and agent platforms. Hospital -IT RFPs are not the growth engine. +The buyer is the technical owner at an RCM vendor, BPO, vertical SaaS, or +agent platform that already finishes last-mile work in someone else's GUI. +Health-system IT is a downstream environment. IDN RFPs are not the growth +engine. -If another actuator already clicked (Power Automate, Copilot, a vendor bot), -OpenAdapt can still issue the Seal. Until a counterparty demands that proof, -distribution stays with the incumbent. Coexist. +Embed through Execute and MCP. One partner is many environments. A hospital +procurement cycle is 12 to 18 months. + +If Copilot, Power Automate, or another actuator already clicked, OpenAdapt +can still emit the Seal when asked. We do not need to win the chat box. Until +a counterparty demands the Seal, the incumbent keeps distribution. Coexist. Compile-once is a cache when the job is stable. If a computer-use agent gets cheap, the run still has to prove identity and effect, or halt. diff --git a/docs/concepts/effect-verification.md b/docs/concepts/effect-verification.md index 033a3f77..72453b44 100644 --- a/docs/concepts/effect-verification.md +++ b/docs/concepts/effect-verification.md @@ -105,3 +105,12 @@ A bundle with no declared effects, or a run with no verifier, still has only the screen oracle for the write. The one automatic fail-safe: a step that declares effects while no verifier is configured is a configuration error and halts, so an unverifiable consequential write isn't silently accepted. + +## Oracle tiers and production Seals + +Screen confirmation is oracle tier 0. A second session or independent UI read +is tier 1. Neither mints a production Seal. A system-of-record read (API, +database, file, ack) is tier 2. A counterparty artifact is tier 3. Charge +those two. `--break-it` on `qualify` is the fail-closed test: a fake success +banner must halt and the store must stay unchanged. See +[The Seal](../commercial/seal.md). diff --git a/docs/get-started/index.md b/docs/get-started/index.md index fedbc808..c9b71ccf 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -84,7 +84,8 @@ it can take, the evidence each one needs, and the paths that stop the run. See [Read a compiled program](../concepts/program-visualizer.md). The tutorial receipt is local and unsigned. Anyone who has to believe the run -needs a Seal. On a qualified synthetic bundle with a tier-2 oracle: +needs a Seal. On a qualified synthetic bundle with a tier-2 oracle, the +intended command is: ```bash openadapt-flow replay bundle --seal