diff --git a/docs/commercial/oem-brief.md b/docs/commercial/oem-brief.md index 89e06a6..80ddf04 100644 --- a/docs/commercial/oem-brief.md +++ b/docs/commercial/oem-brief.md @@ -6,19 +6,32 @@ 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) ``` -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 one CLI story: + +```bash +openadapt-flow replay bundle --seal +``` + +A sealed verified run prints `VERIFIED`, a seal id, and +`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. + +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 @@ -132,6 +145,36 @@ 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 sales motions + +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 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 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 + +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 When the runner cannot prove a required condition, it creates one signed, @@ -143,7 +186,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 +225,28 @@ event stream does not contain raw screenshots or live record data. ## Receipts and partner integration -### ExecuteEvidenceReceiptV1 +### ExecuteEvidenceReceiptV1 is the Seal -Every terminal execution returns an `ExecuteEvidenceReceiptV1` with exactly -these public fields: +Every terminal execution returns an `ExecuteEvidenceReceiptV1`. That object is +the Seal. Map the receipt fields 1:1. -- `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`. - -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 +256,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 +281,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 when asked. + +The compiler stays inspectable. Settlement is the Seal. ## Next step diff --git a/docs/commercial/procurement-faq.md b/docs/commercial/procurement-faq.md index 87b38fa..4e00681 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 886bfb7..c26809b 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 3d85757..1d7c4ac 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 new file mode 100644 index 0000000..213a7a8 --- /dev/null +++ b/docs/commercial/seal.md @@ -0,0 +1,149 @@ +# 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 sales motions + +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. 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, 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" +is refused: that is renewal. + +## CLI story + +On a qualified synthetic bundle with a tier-2 oracle, the intended command is: + +```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 + +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. + +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. + +Partner API contract: [Integrate OpenAdapt Execute](execute-api.md). +OEM embedding: [OpenAdapt Execute private-pilot guide](oem-brief.md). diff --git a/docs/concepts/effect-verification.md b/docs/concepts/effect-verification.md index 033a3f7..72453b4 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 0c4cc43..c9b71cc 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -83,6 +83,27 @@ 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, the +intended command is: + +```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 +113,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 2b2e240..500cbc2 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 f29cfc8..d846228 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 c8a9b28..a838f85 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 f76d0ef..fab44f3 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