# RightOS + RightFlow — Architectural Scope and Boundary Contracts

- date: 2026-07-13
- related: [Decision Guide](./RIGHTOS_RIGHTFLOW_DECISION_GUIDE.md), [Concept Guide](./RIGHTOS_RIGHTFLOW_CONCEPT_GUIDE.md)
- note: Everyday explanation lives in the Concept Guide. This file states the working boundaries.

---

## 1. Working architectural definition

**English**

RightOS and RightFlow provide a **rights-separated coordination architecture** for **asynchronous cooperation** across **independent actors, authorities, and execution systems**.

**日本語**

RightOS + RightFlow は、独立した主体・権威・実行系の間で行われる非同期協調のための、権利と調整を分離したアーキテクチャである。

### Layer meanings (unchanged)

| Layer | Question | Owns |
| --- | --- | --- |
| **RightOS** | What may be done? | Rights, policy, proof, validity, revoke/transfer |
| **RightFlow** | What should happen next? | Tasks, proposals, assignment state, dependencies |
| **Execution** | How is it done? | Motion, tools, local safety, vendor controllers |

### What the claim is — and is not

| Phrase | In scope? |
| --- | --- |
| “always separate rights and coordination” | **No** — too broad |
| “rights-separated coordination for async cross-authority cooperation” | **Yes** — matches the intended cases |
| “use wherever there are tasks/robots/AI” | **No** — too broad; see negative scope below |

The working definition is **scope-bounded**.

---

## 2. Positive applicability domain (structural conditions)

Use RightOS + RightFlow when **several** of the following hold. Industries are irrelevant; **authority structure** is decisive.

### Structural conditions

| Condition | Why separation helps |
| --- | --- |
| **Multiple independent actors** | Assignment among peers without a shared process owner |
| **Multiple authorities** | Rights issuers ≠ coordinators ≠ operators (S18) |
| **Asynchronous coordination** | Tasks outlive a single request/response |
| **Independently changing rights** | Revoke/expire without rewriting the whole plan (S02) |
| **Replaceable / third-party optimizers** | Proposals must not mint authority (S20) |
| **Delegation / reassignment / exchange** | Coordination mutations are first-class |
| **Policy-controlled execution** | Execution systems must re-check MAY before acting |
| **Cross-organization cooperation** | No single workflow may legitimately own all authority |
| **Mixed actor kinds** under one abstract model | Human / AI / robot / vehicle / software as capability bearers |
| **Execution outside the coordinator** | Controllers remain vendor/safety-owned |

### Non-example (to avoid false positives)

The architecture is **not** valuable merely because “a robot is involved.”

It becomes valuable when, for example:

- the **robot operator**,
- the **facility authority**,
- the **task coordinator**, and
- the **execution system**

do **not** share a single authority boundary.

---

## 3. Negative applicability domain

**Do not** use RightOS + RightFlow as the default merely because a system contains tasks, queues, robots, AI agents, or permissions.

| Negative domain | Prefer instead | Falsification ref |
| --- | --- | --- |
| Single-vendor closed fleet (one master owns allow-list + schedule + motion) | FMS / Open-RMF / VDA master | S05 |
| Device-local mutex / exclusion lock | Device firmware | S10 |
| Continuous vehicle / motor / trajectory control | V2V / platoon / control stack | S12 |
| Sub-second safety control | Local safety PLC / e-stop | S04 |
| Clinical / safety immediate interruption path | Clinical/safety controller | S08 |
| Single authority owns permission + coordination + execution | Integrated workflow/auth product | S14, S15 |
| Single-SaaS entitlement + rollout | Unified flag/entitlement service | S15 |
| Simple local schedulers with identical lifecycle for auth and assignment | One process, one store | F1 / S01 single-runtime |
| Continuous control coupling | Out of scope entirely | S12 |

**Negative scope is part of the architecture.** Declining these arenas is success, not embarrassment.

---

## 4. Boundary contracts (normative renaming of L1–L9)

Earlier research notes may still say “leak.”  
**Normative architecture language:** **Boundary Condition** / **Boundary Contract**.

| ID | Falsification finding | Normative name | Boundary type | Trigger | Required behavior | Responsible layer | Failure if ignored | Mandate |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| L1 | Stale assignment after revoke | **Execution-time authorization** | Contract | Execution attempt after assignment; right may have changed | Assignment MUST NOT be treated as permanent proof of authorization; re-evaluate rights where policy requires | Execution (+ RightOS read); RightFlow may expose helpers | Unauthorized action executes under obsolete assignment | **Mandatory** |
| L2 | E-stop / collision avoidance | **Safety-path exclusion** | Condition | Immediate physical/clinical safety event | Safety MUST NOT require synchronous RightFlow/RightOS in the critical path | Execution / safety system | Unsafe latency or blocked stop | **Mandatory** |
| L3 | Incident commander override | **Break-glass override** | Contract | Declared emergency / incident authority | May mass-invalidate coordination and freeze/revoke right classes; MUST be audited | Admin / safety authority → reconcile into RightFlow/RightOS | God-mode without audit, or stuck obsolete tasks | **Mandatory** (when product exposes override) |
| L4 | Cabinet/device mutex | **Device-local exclusion** | Condition | Resource exclusion owned by one device | Do not model as RightOS objects by default | Device | Over-architecture / false centralization | **Deployment-specific** |
| L5 | Platoon / continuous control | **Continuous-control exclusion** | Condition | Sub-cycle / continuous control coupling | Out of RightFlow scope | Execution | Category error / false safety claims | **Mandatory** |
| L6 | EHR credentials / city permits | **External authority sources** | Condition | Right issuer is outside I-S3 | RightOS may mirror/consume; MUST NOT silently invent consensus across issuers | RightOS + external issuers | Fake single source of truth | **Mandatory** in multi-authority deployments |
| L7 | Optimizer wants embedded rights | **Read-only rights snapshots** | Contract | Planner needs constraints | Snapshots OK; writable rights inside optimizer FORBIDDEN | Optimizer / RightFlow / RightOS | Optimizer mints authority | **Mandatory** |
| L8 | Closed FMS | **Optional thin wrap** | Condition | Single controller already owns all three layers | Skip or thinly wrap; do not force split | Deployment architecture | Cosplay overhead | **Deployment-specific** |
| L9 | Paid reservation vs live queue | **Dual-truth reconciliation** | Contract | Monetary/permit system coexists with live order | Keep money outside RightFlow; reconcile via explicit policy, not schema merge | External payment + RightOS + RightFlow | Hidden marketplace / corrupted authority | **Mandatory** under monetary neutrality |

### Critical invariants (summary)

1. **Optimization does not create authority.**  
2. **Authorization at assignment time ≠ authorization at execution time.**  
3. **Safety may bypass coordination; bypass SHOULD reconcile afterward.**  
4. **Disagreement among authorities MUST be visible; silent consensus is forbidden.**

---

## 5. Execution-time authorization contract

### Normative statement

> A valid coordination assignment **SHALL NOT** be treated as permanent proof that execution remains authorized.  
> **Authorization at assignment time does not imply authorization at execution time.**

### Conceptual sequence

```
assign-time:  Proposal → RightFlow → RightOS gate → commit assignment
time passes:  rights may revoke / expire / window-window end
exec-time:    Execution intends to act → RightOS re-evaluate (policy) → allow / deny
```

### Topics

| Topic | Contract |
| --- | --- |
| Assignment-time verification | RightFlow MUST gate accepts via RightOS read checks for `requiredRights` (+ capabilities) |
| Execution-time verification | Execution (or RightFlow `start` when used as exec signal) MUST re-check where policy requires |
| Stale assignment | Task MAY remain `assigned` after right loss; that state means coordination memory, not permission |
| Revocation / expiration | RightOS status/time wins; coordination does not resurrect rights |
| Cached authorization | Caches MUST be treated as hints; policy decides TTL; must not become writeable authority |
| Degraded connectivity | Deployment policy chooses fail-closed vs fail-open for **execution**; product MUST document the choice — no universal safety claim |
| Fail-open vs fail-closed | Not decided globally by this architecture; high-risk domains SHOULD fail-closed |

### Implementation note (2026-07-13)

- Assignment-time gate: **implemented** (`acceptProposal` → `assertRequiredRightsAvailable`).
- `start` transition: **must re-gate** rights (contract test); see ADR-0027 / selftest.
- Full execution adapters / safety reconcile APIs: **gap** (documented, not faked).

---

## 6. Multi-authority contract (S18)

### Problem

Facility Authority, Robot Operator, Delivery Organization, Task Coordinator, and Safety System may each hold **different** authority. No single workflow engine is assumed to own all of it.

### Behaviors

| Situation | Required architectural behavior |
| --- | --- |
| Multiple rights required | All required rights evaluated; missing any → not authorized |
| Different issuers | Represent as distinct right objects/sources; do not collapse issuers |
| One authority revokes | Affected right invalid → execution deny; assignment may go stale |
| Authorities disagree | Surface indeterminate / partial failure; do not simulate consensus |
| Authority unavailable | Result MAY be `indeterminate`; deployment policy decides retry vs fail-closed |
| Assigned but one right invalid | Coordination state retained until cancelled/reassigned; execution blocked |

RightFlow coordinates; it does **not** adjudicate political disputes between authorities.

---

## 7. Third-party optimizer contract (S20)

### Invariant

> **Optimization does not create authority.**

### Sequence

```
Optimizer → Proposal → RightFlow
                → Required rights evaluation → RightOS
                → Authorized | Rejected | Indeterminate
                → RightFlow coordination update | proposal invalidation
```

### Terms

| Term | Meaning |
| --- | --- |
| Proposal | Non-authoritative coordination suggestion |
| Authorized | Rights available for the proposed actors/tasks at evaluation time |
| Rejected | Rights unavailable / capability mismatch / precondition fail |
| Indeterminate | Evaluator could not decide (e.g. authority unreachable) — not a silent accept |
| Stale proposal | Preconditions changed before accept |
| Partial authorization | Some legs OK, some not — MUST NOT commit the whole as if fully authorized |
| Invalidation | Proposal marked non-actionable after failed gate or conflict |

---

## 8. Safety and break-glass contract

```
Safety Action → Immediate Local Execution → Safety Event
                    → RightFlow / RightOS reconciliation (audit, invalidate, review)
```

| Rule | Statement |
| --- | --- |
| Bypass allowed | Safety systems MAY bypass normal coordination paths |
| Not invisible | Where technically possible, events SHOULD reconcile afterward |
| Not a PLC | RightOS is not a safety PLC |
| Not a motion controller | RightFlow is not a real-time motion controller |

---

## 9. Device-local and continuous-control exclusion

| RightFlow MAY coordinate | RightFlow MUST NOT coordinate |
| --- | --- |
| “Actor A may use Resource X during Window Y” (as task + rights) | “Motor torque changes by Z next cycle” |
| Discrete handoffs, queues, dependencies | Servo loops, trajectory correction, collision avoidance inner loop |
| Async multi-actor plans | Deterministic sub-second control |

Different latency, determinism, ownership, failure, and safety regimes.

---

## 10. Public language restraint

Allowed factual product language:

- RightOS verifies what an actor may do.
- RightFlow coordinates what should happen next.
- Execution remains with the connected system.

Avoid in marketing: novel / unique / first / revolutionary.

Research claims stay in `docs/research/`.

---

## 11. Stronger defensible statement (tested)

> When independent authorities, coordinators, and execution systems must cooperate asynchronously, **rights authority and coordination state have different lifecycles and failure modes**. Treating them as separate architectural concerns can preserve authority integrity while allowing flexible coordination.

That statement — not universal separation — is the architectural claim.

---

## 12. Implementation contract status (2026-07-13)

| Contract | Status |
| --- | --- |
| Assignment-time RightOS gate | Implemented |
| Execution-time revalidation on RightFlow `start` | Implemented |
| Reference external execution adapter (L1) | Implemented (`executionAdapter.ts` + selftest) |
| Safety-event reconcile API (L2) | Implemented (`POST /api/rightflow/safety-events`) |
| Break-glass API (L3) | Implemented (`POST /api/rightos/admin/break-glass`) |
| File-backed `safetyEvents` audit log | Implemented (ADR-0028; not EventBridge) |
| Explicit `indeterminate` multi-authority result | **Gap** — document only |
| Production vendor adapters (Open-RMF / VDA / A2A) | **Gap** — reference pattern only |
| Firestore / EventBridge migration | **Not started** — ADR-0019 triggers unmet |
Rows marked incomplete stay incomplete until a real contract ships.