Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/commercial/acceptance-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Three outcomes are acceptable, one is not:
Mechanics behind the outcomes:
[effect verification](../concepts/effect-verification.md),
[the identity gate](../concepts/identity-gate.md),
[fail-closed regulated execution](../concepts/regulated-execution.md).
[regulated execution](../concepts/regulated-execution.md).

## Template

Expand Down
6 changes: 3 additions & 3 deletions docs/commercial/citrix-external-brief.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,16 +30,16 @@ other substrate:
fresh pixels, resolved target, and record identity, then a one-shot input
lease refuses delivery if **anything** changed between resolution and the
first input edge.
- Identity checks run on the pixel tier; ambiguity deliberately over-halts
rather than guessing. A collapsible or unreadable identifier halts the run.
- Identity checks run on the pixel tier; ambiguity over-halts
instead of guessing. A collapsible or unreadable identifier halts the run.
- Business effects are verified out of band where a read path exists (API,
database, report export, or a read-only second session). Screen-only
confirmation is labeled as such, and high-risk workflows may not qualify on
it alone.
- Halts are durable: the run pauses for a human with the violated expectation
named in the report.

## Honest status
## Current qualification status

Two claims, kept separate:

Expand Down
2 changes: 1 addition & 1 deletion docs/commercial/deployment-boundaries.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ flowchart LR
the runner's local sensitive-data policy. Verification prefers an
independent read path; where only the screen is available, that is labeled
same-surface confirmation and high-risk workflows may not qualify on it.
- **Status:** see the honest status statement in the
- **Status:** see the current qualification status in the
[external Citrix brief](citrix-external-brief.md).

## Rules that hold in every lane
Expand Down
2 changes: 1 addition & 1 deletion docs/commercial/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ the evidence supports a "do not automate" decision.
| [OpenAdapt Execute private-pilot guide](oem-brief.md) | A vendor that wants to embed verified execution. The API is available to approved private-pilot partners with scoped credentials. |
| [Procurement FAQ](procurement-faq.md) | Procurement, legal, and vendor-risk questions. |

## Honesty rules for this section
## How claims are bounded

These documents follow the same rules as the public site:

Expand Down
18 changes: 9 additions & 9 deletions docs/commercial/phi-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ engine:
- There is no silent plaintext: in the default mode without the privacy extra,
writing identity-like free text emits an explicit `PlaintextPHIWarning`.

**The honest boundary.** The recorded identity evidence and the identity audit
trail intentionally retain literal identifiers scrubbing them would defeat
**The identity boundary.** The recorded identity evidence and the identity audit
trail intentionally retain literal identifiers; scrubbing them would defeat
the wrong-record check they exist to power. Those artifacts are governed as
PHI-at-rest **inside your boundary** (filesystem controls, retention,
full-disk encryption, opt-in AES-256-GCM sealing), and the published privacy
Expand All @@ -43,12 +43,12 @@ data and the wire:
can the derivative be pushed, and the control plane verifies the manifest,
review state, and exact archive SHA-256 before accepting a byte.

Content the sanitizer cannot fully handle databases, video, audio, nested
archives, symlinks, unknown binaries refuses the **entire** derivative
Content the sanitizer cannot fully handle (databases, video, audio, nested
archives, symlinks, unknown binaries) refuses the **entire** derivative
rather than passing through. Sanitizer success is not treated as proof of
de-identification: the operator review is the gate.

## 3. The receipt: an allow-list, not a redaction
## 3. The receipt is an allow-list

The shareable run receipt is generated **additively from a closed allow-list,
never redacted subtractively** from the rich operator report. Every field is a
Expand All @@ -59,7 +59,7 @@ Structurally unrepresentable in a receipt: screenshots, OCR text, typed
values, parameters, URLs, hostnames, coordinates, application name,
organization name, user name, workflow name, step intents, and halt free text.
The same principle governs the hosted attended-decision envelope (closed
enums, bounded integers, booleans no string field, no image) and the hosted
enums, bounded integers, booleans; no string field, no image) and the hosted
break-report descriptor (hashed, coarse, no free text).

## Where each artifact can live
Expand All @@ -74,8 +74,8 @@ break-report descriptor (hashed, coarse, no free text).

## Related pages

- [Security packet](security-packet.md) the reviewer summary.
- [Security packet](security-packet.md): the reviewer summary.
- [Subprocessors and hosted data retention](subprocessors.md)
- [Fail-closed regulated execution](../concepts/regulated-execution.md)
- Engine [PRIVACY.md](https://github.com/OpenAdaptAI/openadapt-flow/blob/main/docs/PRIVACY.md)
- [Regulated execution](../concepts/regulated-execution.md)
- Engine [PRIVACY.md](https://github.com/OpenAdaptAI/openadapt-flow/blob/main/docs/PRIVACY.md):
the complete path-by-path PHI map.
4 changes: 2 additions & 2 deletions docs/commercial/security-packet.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Security packet

The honest current state of OpenAdapt's security posture, written for a
Current OpenAdapt security posture, written for a
security or vendor-risk reviewer. Deeper technical detail:
[Security and data handling](../guides/security-and-data-handling.md) and the
reviewer-oriented
Expand Down Expand Up @@ -29,7 +29,7 @@ add an append-only, hash-chained audit log.
read of the system of record. REFUTED and INDETERMINATE verdicts both halt;
an unreachable verifier is never treated as success
([effect verification](../concepts/effect-verification.md)).
- **Fail-closed regulated path.** The `run` verb refuses to start without
- **Regulated `run` path.** The `run` verb refuses to start without
certification, identity coverage, effect contracts or explicit approval, and
encrypted, integrity-sealed bundles
([regulated execution](../concepts/regulated-execution.md)).
Expand Down
14 changes: 7 additions & 7 deletions docs/commercial/subprocessors.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ As read from the hosted control plane's deployment configuration:
|---|---|---|
| Netlify | Hosting for the `app.openadapt.ai` control plane | Application traffic to the control plane: account and session data in transit, and the metadata/digest surfaces described in the [security packet](security-packet.md). |
| Supabase | Database, authentication, and object storage for the control plane | Accounts, organizations, workflow versions, run metadata, sanitized artifact derivatives, retention/erasure receipts. |
| Modal | Compute for the managed browser runner | Managed browser execution for explicitly initiated, public-HTTPS, non-regulated workloads only not a lane for PHI/PII. |
| Modal | Compute for the managed browser runner | Managed browser execution for explicitly initiated, public-HTTPS, non-regulated workloads only; not a lane for PHI/PII. |
| Stripe | Payments and billing | Payment and subscription data. Card data is entered on Stripe's surfaces, not OpenAdapt's. |
| Resend | Transactional email (organization invites, purchase alerts) | Recipient email addresses and the fixed-template message content. Purchase alerts carry purchase metadata only, never workflow evidence. |
| GitHub | Source hosting, CI, release distribution | Public source, build artifacts, and CI logs. No customer workload data. |
Expand All @@ -35,7 +35,7 @@ not to your workflows.
## Hosted retention and deletion

The hosted service applies a **versioned, explicitly configured retention
policy** there is no implicit retention duration. The policy names its
policy**; there is no implicit retention duration. The policy names its
version and sets explicit windows for recordings, reports, and run metadata
(run metadata is never retained shorter than reports), plus a backup recovery
window and a maximum restore-drill age.
Expand All @@ -47,7 +47,7 @@ Current behavior:
private object storage restore into an isolated scratch environment.
- **Legal holds pause eligible deletion** for the held organization.
- **Tenant erasure is organization-scoped** and produces an append-only,
PHI/PII-free receipt with identifiers, counts, and digests never deleted
PHI/PII-free receipt with identifiers, counts, and digests, never deleted
payloads.
- The public [readiness endpoint](https://app.openadapt.ai/api/health/ready)
reports the configured retention component separately from the
Expand Down Expand Up @@ -86,8 +86,8 @@ flowchart TB

## Related pages

- [Security packet](security-packet.md) posture summary for reviewers.
- [Vulnerability disclosure](vulnerability-disclosure.md) how to report.
- [PHI handling](phi-handling.md) the end-to-end PHI narrative.
- [Security and data handling](../guides/security-and-data-handling.md) the
- [Security packet](security-packet.md): posture summary for reviewers.
- [Vulnerability disclosure](vulnerability-disclosure.md): how to report.
- [PHI handling](phi-handling.md): the end-to-end PHI narrative.
- [Security and data handling](../guides/security-and-data-handling.md): the
full technical dossier, including hosted retention detail.
4 changes: 2 additions & 2 deletions docs/concepts/backends.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ substrate; nothing about the safety model is specific to it.
The public `WindowsBackend` now narrows the in-session boundary to typed
`/input` and `/uia/*` operations, disables arbitrary legacy execution by
default, screenshots the desktop, and reads the **UI Automation** tree for
identity. Crucially, an
identity. An
element usually exposes `Name` / `Value` text **even when it has no stable
`AutomationId`**, so UIA-based identity is viable on most native apps even where
a durable selector is not.
Expand Down Expand Up @@ -135,7 +135,7 @@ swappable `RDPTransport` protocol (so the adapter is CI-testable without a live
server) and a real transport over the pure-Python async `aardwolf` client,
behind the optional `rdp` extra. On a pure-pixel substrate the ladder runs on
its visual floor and the identity gate falls back to its pixel/OCR tiers, which
is why a look-alike identifier can force a [halt rather than a verify](identity-gate.md)
is why a look-alike identifier can force a [halt instead of a verify](identity-gate.md)
there.

For every consequential remote action, the runtime uses a two-phase actuation
Expand Down
10 changes: 5 additions & 5 deletions docs/concepts/capability-ladder.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,12 +39,12 @@ The rung you land on changes what the system can guarantee. Identity is the
clearest example. Two different records with the same name and date of birth,
distinguished only by an identifier differing by a single `O` versus
`0` glyph, render to a byte-identical OCR band. On the **visual** rung, OCR
cannot separate them, so OpenAdapt refuses rather than guesses. On the
**structural** rung, the two rows are different strings in the tree, so the same
case verifies with no availability cost.
can't separate them, so OpenAdapt stops. On the **structural** rung, the two
rows are different strings in the tree, so the same case verifies with no
availability cost.

The principle: push each decision to the highest rung the app supports, and fail
safe below it. See [The identity gate](identity-gate.md) for how this plays out.
Push each decision to the highest rung the app supports, and stop below it. See
[The identity gate](identity-gate.md) for how that plays out.

## Capability-adaptive compilation

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/demonstration-compiler.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ OpenAdapt uses that higher-fidelity signal via
UIA, native macOS, native Linux AT-SPI, RDP, and Citrix/VDI
[backends](backends.md) are all adapters to the same protocol, not rewrites.

## An API compiler for the API-less long tail
## When the app has no usable API

Most enterprise software has no usable API for the workflow you actually run.
The demonstration is the only interface that always exists: if a person can do
Expand Down
33 changes: 16 additions & 17 deletions docs/concepts/durable-runtime.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Durable runtime: checkpoint, attended decision, resume

A halt is the safety design working: the run stopped rather than guessing. But a
halt mid-workflow should not mean starting over, and must never re-perform a
write that already landed. The durable runtime turns a halt into a **durable
pause**. An authorized operator can make a bounded attended decision, and the
runtime resumes only from the last verified checkpoint.
A halt means the run stopped instead of guessing. A halt mid-workflow should
not mean starting over, and must never re-perform a write that already landed.
The durable runtime turns a halt into a **durable pause**. An authorized
operator can make a bounded attended decision, and the runtime resumes only
from the last verified checkpoint.

!!! note "Off by default"
The durable runtime is Tier-3 and opt-in. Enable it with `runtime.durable`
Expand Down Expand Up @@ -32,9 +32,9 @@ from the system of record. **A halt is not a rollback.**
What the halting step may already have done is stated in the run's terminal
`transaction_outcome`, and is never inferred from the checkpoint:

- **`HALTED_BEFORE_EFFECT`** absence was positively established for every
- **`HALTED_BEFORE_EFFECT`**: absence was positively established for every
consequential step. There is nothing to reconcile.
- **`RECONCILIATION_REQUIRED`** delivery or persistence is uncertain,
- **`RECONCILIATION_REQUIRED`**: delivery or persistence is uncertain,
conflicting, or unverifiable. Reconcile the current state before resuming; the
runtime will not blind-retry.

Expand Down Expand Up @@ -91,24 +91,23 @@ notification. It projects a closed context only; screenshots, OCR, values, and
free-text application data stay on the customer-controlled runner. See
[Attended decisions and the halt-learn loop](halt-learn-loop.md).

## The bounded-recovery posture
## Bounded recovery

Durable resume is the third tier of a deliberately bounded runtime:
Durable resume is the third tier of a bounded runtime:

1. a **deterministic fast path** (the resolution ladder, $0);
2. a **bounded model recovery** of at most one local transition, when
configured and permitted;
3. a **durable pause, approve, resume** from the last verified checkpoint.

It is explicitly **not** "hand the rest of the workflow to a free-form agent
after a halt." Recovery is scoped; the checkpoint is where a human takes over
when it cannot be. Same posture as the
[identity gate](identity-gate.md) and [effect verification](effect-verification.md):
when the right action is not determined, stop, and here, stop *resumably*.
Recovery is scoped. After a halt, OpenAdapt does not hand the rest of the
workflow to a free-form agent. The checkpoint is where a human takes over when
the next action is not determined. [Identity](identity-gate.md) and
[effect verification](effect-verification.md) stop the same way; here the stop
is resumable.

How that handover actually reaches a person — the bounded question, what an
answer does and does not authorize, and why the engine re-verifies rather than
trusting it — is the
How that handover reaches a person, what an answer authorizes, and why the
engine re-verifies live state, is the
[attended decision path](halt-learn-loop.md#where-a-halt-goes-the-attended-decision).

See the [Run a deployment](../guides/run-a-deployment.md) guide for a worked
Expand Down
28 changes: 13 additions & 15 deletions docs/concepts/effect-verification.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# Effect verification

The screen is not the system of record: a "Saved" banner can paint over an empty
database. Effect verification confirms a write actually landed in the real
record, exactly once, with the right values, by reading the record instead of
the pixels.
A "Saved" banner can paint over an empty database. Effect verification confirms
a write actually landed in the real record, exactly once, with the right values,
by reading the record instead of the pixels.

## The problem: five silent write faults
## Five silent write faults

A vision postcondition asks a weak question: "do the pixels look like a save
happened?" A fault-model study drove 90 replays through a real persistence
Expand All @@ -24,7 +23,7 @@ help) and the screen shows success (so the screen oracle cannot help):
None is render drift: the screen genuinely showed success, so only the record
knows the truth.

## The mechanism: read the record, not the screen
## Read the record, not the screen

A step can declare typed **effects** against the system of record. Given an
`EffectVerifier`, the replayer snapshots the record before the action and, after
Expand All @@ -38,10 +37,10 @@ verdict:
non-2xx, expired token, unparseable body). **Halt.** An expired token is never
mistaken for "record absent."

No "probably fine": both non-confirmed verdicts halt the run, mirroring the
[identity gate](identity-gate.md)'s refuse-rather-than-guess posture. The
verifier reads an API or a database, never the pixels, and makes **zero model
calls**, so the $0 runtime guarantee holds.
Both non-confirmed verdicts halt the run, the same way the
[identity gate](identity-gate.md) stops an unresolvable target. The verifier
reads an API or a database, never the pixels, and makes **zero model calls**, so
the $0 runtime guarantee holds.

```mermaid
flowchart TD
Expand Down Expand Up @@ -93,7 +92,7 @@ approach is not tied to one backend.
For the five classes the screen silently mishandles, effect verification
REFUTES and halts.

## The honest preconditions
## What has to be declared

Two conditions are required, and both are real:

Expand All @@ -103,7 +102,6 @@ Two conditions are required, and both are real:
2. A verifier must be **configured** for the deployment.

A bundle with no declared effects, or a run with no verifier, still has only the
screen oracle for the write and is as silent as before. 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 is never
silently accepted.
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.
Loading