# Capability route

> Decide how UORust records a Rust target by the effect it reaches. Every effect becomes a threat in the model, and nothing hides as pure.

Inspired by afflom/uorust (https://github.com/afflom/uorust), live at https://afflom.github.io/UORust/. Any Cargo workspace to a complete Prism model, every facet. Pattern: Decision table, OMG DMN 1.5, hit policy FIRST. To write one of your own, follow How to build a decision table app (../../guides/decision-table/index.md). The prompt below is data, quoted from the example.

**Figure: What the Capability route app does.** A request goes in, the rules decide, and the Lean kernel has already proved what the rules promise.

| Step | What happens |
| --- | --- |
| 1. Request | effect, forbid |
| 2. 4 rules | the first that matches wins |
| 3. Answer | pure, gated, capability, threat |
| 4. Proved | 3 theorems, 19 tests |

Verified by prismpm verify in the pinned SDK. Fingerprint: 9c78a45419df55fb79415590ee0998f8509fb66f3184ed1b09836701c8eeea3d. Acceptance vectors: 19. Claims: 6.

## The prompt

```json
{
  "schema": "prism/prompt/1",
  "goal": "Decide how UORust records a Rust target by the effect it reaches. Every effect becomes a threat in the model, and nothing hides as pure.",
  "pattern": "decisionTable",
  "repository": "afflom/uorust",
  "app": {
    "name": "capability-route",
    "title": "Capability route",
    "purpose": "Decide whether a Rust target is recorded as pure, as pure under the compiler gate, as a capability, or as a threat, from the first effect it reaches and whether its crate forbids unsafe code.",
    "fields": [
      {
        "name": "effect",
        "kind": "choice",
        "values": [
          "none",
          "fs",
          "net",
          "process",
          "env",
          "unsafe",
          "ffi"
        ],
        "means": "the first operating-system effect the target reaches"
      },
      {
        "name": "forbid",
        "kind": "choice",
        "values": [
          "yes",
          "no"
        ],
        "means": "whether the crate has forbid(unsafe_code)"
      }
    ],
    "outcomes": [
      "pure",
      "gated",
      "capability",
      "threat"
    ],
    "meanings": {
      "pure": "no effect: lifted as pure behavior, its memory threat controlled by review",
      "gated": "no effect: pure, its memory threat controlled by the forbid(unsafe_code) compiler gate",
      "capability": "an fs, net, process or env asset with a threat and reviewed sites",
      "threat": "an unsafe or foreign effect: a memory-safety threat, elevation of privilege"
    },
    "rules": [
      {
        "when": [
          {
            "field": "effect",
            "op": "is",
            "value": "unsafe"
          }
        ],
        "then": "threat",
        "why": "model/routes.toml UR-R14: an unsafe block is a memory-safety threat"
      },
      {
        "when": [
          {
            "field": "effect",
            "op": "is",
            "value": "ffi"
          }
        ],
        "then": "threat",
        "why": "model/routes.toml UR-R15: an extern block crosses the language boundary, a threat"
      },
      {
        "when": [
          {
            "field": "effect",
            "op": "is",
            "value": "none"
          },
          {
            "field": "forbid",
            "op": "is",
            "value": "yes"
          }
        ],
        "then": "gated",
        "why": "crates/uorust/src/project.rs threats: with forbid(unsafe_code) the memory threat is controlled by a gate (UR-R20)"
      },
      {
        "when": [
          {
            "field": "effect",
            "op": "is",
            "value": "none"
          }
        ],
        "then": "pure",
        "why": "crates/uorust/src/project.rs threats: without forbid the control is Safe Rust only, a review"
      }
    ],
    "otherwise": "capability",
    "otherwiseWhy": "model/routes.toml UR-R16 to UR-R19: fs, net, process and env uses are assets, each with a capability threat (project.rs capability_threat)",
    "properties": [
      {
        "kind": "never",
        "when": [
          {
            "field": "effect",
            "op": "is not",
            "value": "none"
          }
        ],
        "then": "pure",
        "why": "an effect is never routed as pure"
      },
      {
        "kind": "always",
        "when": [
          {
            "field": "effect",
            "op": "is",
            "value": "unsafe"
          }
        ],
        "then": "threat",
        "why": "unsafe is always a threat"
      },
      {
        "kind": "never",
        "when": [
          {
            "field": "forbid",
            "op": "is",
            "value": "no"
          }
        ],
        "then": "gated",
        "why": "the compiler gate is evidence only where the crate forbids unsafe code"
      }
    ],
    "examples": [
      {
        "request": "none yes",
        "response": "gated"
      },
      {
        "request": "none no",
        "response": "pure"
      },
      {
        "request": "fs yes",
        "response": "capability"
      },
      {
        "request": "env no",
        "response": "capability"
      },
      {
        "request": "unsafe no",
        "response": "threat"
      },
      {
        "request": "ffi yes",
        "response": "threat"
      }
    ]
  },
  "stakeholders": [
    {
      "name": "Rust developer",
      "text": "Models a Cargo workspace with UORust and needs every effect in it to show up as a capability or a threat.",
      "concerns": [
        "Correct answers",
        "Proved guarantees"
      ]
    },
    {
      "name": "Security reviewer",
      "text": "Reads the threat model UORust writes and needs every unsafe or foreign call to arrive as a threat, with gate evidence only where the compiler enforces it.",
      "concerns": [
        "Honest evidence"
      ]
    }
  ],
  "concerns": [
    {
      "name": "Honest evidence",
      "text": "A control cites a gate only where the compiler enforces it; otherwise it cites a review.",
      "model": "security"
    }
  ],
  "components": [
    {
      "name": "Cargo workspace",
      "text": "The workspace UORust reads through cargo metadata, Cargo.lock and syn, with source spans.",
      "kind": "externalSystem"
    },
    {
      "name": "uorust CLI",
      "text": "crates/uorust, which ingests facts, routes them through model/routes.toml and writes the Prism model.",
      "kind": "cliAdapter"
    }
  ],
  "threats": [
    {
      "name": "Unsafe routed as pure",
      "text": "A target that reaches unsafe code is recorded as pure, so its memory threat is missing.",
      "stride": "elevationOfPrivilege",
      "asset": "answer",
      "likelihood": "low",
      "impact": "critical",
      "control": {
        "name": "Effects never pure",
        "text": "An effect is never answered pure, proved for every request, and the Rust router replays the same vectors.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "CapabilityRouteProofs::inv001Holds"
          },
          {
            "kind": "gate",
            "reference": "crates/conformance/tests/routes.rs"
          }
        ]
      }
    },
    {
      "name": "Gate claimed without forbid",
      "text": "A memory control cites the compiler gate for a crate that does not forbid unsafe code.",
      "stride": "repudiation",
      "asset": "answer",
      "likelihood": "low",
      "impact": "major",
      "control": {
        "name": "Gate only with forbid",
        "text": "Gated is never answered without forbid, proved for every request.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "CapabilityRouteProofs::inv003Holds"
          },
          {
            "kind": "review",
            "reference": "crates/uorust/src/project.rs threats"
          }
        ]
      }
    },
    {
      "name": "Effect hidden by a macro",
      "text": "A procedural macro or build script reaches an effect the source scan does not see.",
      "stride": "spoofing",
      "asset": "request",
      "likelihood": "medium",
      "impact": "major",
      "accepted": "UORust reads source spans with syn; what it cannot lift is recorded as residue in frontier.toml rather than routed."
    }
  ],
  "quality": [
    {
      "characteristic": "Functional suitability",
      "subcharacteristic": "Functional completeness",
      "requirement": "Every effect kind routed",
      "text": "Each of the seven effect kinds has a route, with and without forbid.",
      "measure": "Effect kinds without a route",
      "measureText": "Of the seven effect kinds, those no rule or otherwise routes.",
      "threshold": 0
    }
  ],
  "journeys": [
    {
      "stakeholder": "Rust developer",
      "steps": [
        "REQ-001",
        "REQ-002",
        "REQ-003",
        "REQ-004",
        "otherwise"
      ]
    },
    {
      "stakeholder": "Security reviewer",
      "steps": [
        "INV-001",
        "INV-002",
        "INV-003"
      ]
    }
  ],
  "axioms": {
    "inv002Holds": [
      "Classical.choice",
      "Quot.sound",
      "propext"
    ]
  },
  "license": "MIT OR Apache-2.0"
}
```

## Claims

- CR-01: The app never answers pure when effect is not none
- CR-02: The app always answers threat when effect is unsafe
- CR-03: The app never answers gated when forbid is no
- CR-04: The architecture description declares every stakeholder, concern, component, edge, viewpoint and view it references
- CR-05: The ISO/IEC 25010 quality model numbers every characteristic, subcharacteristic, requirement and measure, and every parent it names is declared
- CR-06: Every compliance obligation is numbered in order and names its evidence

## Pattern

Decision table: OMG DMN 1.5, hit policy FIRST. The rules are tried in order, and the first one that matches gives the answer. If none matches, the default answer applies. This is a DMN decision table with the FIRST hit policy.

| Pattern | Standard | Answers |
| --- | --- | --- |
| Decision table | OMG DMN 1.5, hit policy FIRST | pure, gated, capability, threat |

**Figure: Rules for each answer.** Each bar counts the rules that give one answer. When no rule matches, the answer is capability.

|  | rules |
| --- | --- |
| pure | 1 |
| gated | 1 |
| capability | 0 |
| threat | 2 |

## Behavior

A request is effect, forbid, separated by spaces. The first rule that matches decides. If none matches, the answer is capability. A request over 64 bytes, or in any other form, is answered invalid.

| Rule | When | Answer | Why |
| --- | --- | --- | --- |
| REQ-001 | effect is unsafe | threat | model/routes.toml UR-R14: an unsafe block is a memory-safety threat |
| REQ-002 | effect is ffi | threat | model/routes.toml UR-R15: an extern block crosses the language boundary, a threat |
| REQ-003 | effect is none and forbid is yes | gated | crates/uorust/src/project.rs threats: with forbid(unsafe\_code) the memory threat is controlled by a gate (UR-R20) |
| REQ-004 | effect is none | pure | crates/uorust/src/project.rs threats: without forbid the control is Safe Rust only, a review |
| otherwise | no rule matches | capability | model/routes.toml UR-R16 to UR-R19: fs, net, process and env uses are assets, each with a capability threat (project.rs capability\_threat) |

## Properties Lean proves

Each property is a theorem about the same definitions the app is built from. It is proved for every request, not only the tested ones.

| Property | Statement | Theorem | Why |
| --- | --- | --- | --- |
| INV-001 | It never answers pure when effect is not none. | CapabilityRouteProofs::inv001Holds | an effect is never routed as pure |
| INV-002 | It always answers threat when effect is unsafe. | CapabilityRouteProofs::inv002Holds | unsafe is always a threat |
| INV-003 | It never answers gated when forbid is no. | CapabilityRouteProofs::inv003Holds | the compiler gate is evidence only where the crate forbids unsafe code |

## Architecture

Stakeholders and the concerns each one views the app through (ISO/IEC/IEEE 42010).

| Stakeholder | Who they are | Concerns |
| --- | --- | --- |
| Rust developer | Models a Cargo workspace with UORust and needs every effect in it to show up as a capability or a threat. | Correct answers, Proved guarantees |
| Security reviewer | Reads the threat model UORust writes and needs every unsafe or foreign call to arrive as a threat, with gate evidence only where the compiler enforces it. | Honest evidence |
| Verifier | Anyone who loads the holo, checks its fingerprint and replays its acceptance vectors before trusting an answer. | Integrity of the published app, Refused malformed requests, Proved guarantees |

## Concerns

What the stakeholders care about, and the model each is viewed in.

| Concern | What it means | Model |
| --- | --- | --- |
| Correct answers | Every well-formed request is answered by the first rule that matches it, or capability when none does, as the spec states. | quality |
| Honest evidence | A control cites a gate only where the compiler enforces it; otherwise it cites a review. | security |
| Integrity of the published app | What a visitor runs is the holo the build verified, with its fingerprint and signed provenance beside it. | security |
| Proved guarantees | Each of the 3 properties of the spec holds for every request, proved by the Lean kernel. | quality |
| Refused malformed requests | A request that is not the 2 fields in order, or is longer than 64 bytes, is answered invalid and never guessed. | security |

## Components

8 components and 11 edges between them.

| Component | Kind | What it is |
| --- | --- | --- |
| Browser | externalSystem | The visitor's web browser, which loads the page and runs the Capability route guest. |
| Capability route guest | service | The Core-Wasm guest built from the model: it answers one request of at most 64 bytes with one answer of at most 64. |
| Capability route page | staticSite | The page the template publishes: the holo, its fingerprint, its provenance and its acceptance vectors. |
| Cargo workspace | externalSystem | The workspace UORust reads through cargo metadata, Cargo.lock and syn, with source spans. |
| GitHub Pages | externalSystem | Serves the page and the holo from the repository Pages workflow. |
| Prism build | cliAdapter | prismpm verify in the SDK image prismpm.lock pins: it checks every theorem, builds the guest and replays every vector. |
| Source repository | externalSystem | The repository that holds the prompt, the model and its gate. |
| uorust CLI | cliAdapter | crates/uorust, which ingests facts, routes them through model/routes.toml and writes the Prism model. |

## Design views

The SDK checks each view against the system model and draws it as OPL and PlantUML.

| View | Diagram | Viewpoint |
| --- | --- | --- |
| Deciding a Capability route request | opmObjectProcess | Rust developer: Correct answers |
| Components of Capability route | umlComponent | Verifier: Integrity of the published app |
| Answering a Capability route request | umlSequence | Rust developer: Correct answers |
| States of the Capability route guest | umlStateMachine | Verifier: Refused malformed requests |

## Features and journeys

9 features. Each names the definitions that do the work and the tests that accept it. Each stakeholder has one journey.

| Feature | Calls | Accepted by |
| --- | --- | --- |
| When effect is unsafe, the answer is threat. | CapabilityRoute::rule1, CapabilityRoute::judge | CapabilityRoute::application |
| When effect is ffi, the answer is threat. | CapabilityRoute::rule2, CapabilityRoute::judge | CapabilityRoute::application |
| When effect is none and forbid is yes, the answer is gated. | CapabilityRoute::rule3, CapabilityRoute::judge | CapabilityRoute::application |
| When effect is none, the answer is pure. | CapabilityRoute::rule4, CapabilityRoute::judge | CapabilityRoute::application |
| When no rule matches, the answer is capability. | CapabilityRoute::judge | CapabilityRoute::application |
| A request that is not effect, forbid in order, separated by single spaces, or is over 64 bytes, is answered invalid. | CapabilityRoute::dispatch, CapabilityRoute::decodeField1 | CapabilityRoute::application |
| It never answers pure when effect is not none. | CapabilityRoute::judge | CapabilityRouteProofs::inv001Holds |
| It always answers threat when effect is unsafe. | CapabilityRoute::judge | CapabilityRouteProofs::inv002Holds |
| It never answers gated when forbid is no. | CapabilityRoute::judge | CapabilityRouteProofs::inv003Holds |

## Journeys

The ordered features each stakeholder takes.

| Stakeholder | Steps |
| --- | --- |
| Rust developer | REQ-001 → REQ-002 → REQ-003 → REQ-004 → otherwise |
| Security reviewer | INV-001 → INV-002 → INV-003 |
| Verifier | refuse → INV-001 → INV-002 → INV-003 |

## Security and threat model

12 threats against 4 assets. Each has a STRIDE category, and either a control with evidence or a risk that is accepted on purpose.

| Threat | STRIDE | Asset | Risk | Answered by |
| --- | --- | --- | --- | --- |
| Answer that breaks INV-001 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-001: proof CapabilityRouteProofs::inv001Holds |
| Answer that breaks INV-002 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-002: proof CapabilityRouteProofs::inv002Holds |
| Answer that breaks INV-003 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-003: proof CapabilityRouteProofs::inv003Holds |
| Effect hidden by a macro | spoofing | Request bytes | medium likelihood, major impact | accepted: UORust reads source spans with syn; what it cannot lift is recorded as residue in frontier.toml rather than routed. |
| Gate claimed without forbid | repudiation | Answer | low likelihood, major impact | Gate only with forbid: proof CapabilityRouteProofs::inv003Holds; review crates/uorust/src/project.rs threats |
| Granted capability | informationDisclosure | Answer | low likelihood, major impact | No capability granted: gate prism-code check refuses an ungranted guest import |
| Malformed request | tampering | Request bytes | high likelihood, major impact | Strict decoder: gate malformed-request acceptance vectors, replayed in the compiled guest by prismpm verify |
| Oversized request | denialOfService | Request bytes | medium likelihood, minor impact | Bounded request: gate acceptance vectors at the request bound, one byte over it, and at the guest allocation bound, replayed by prismpm verify |
| Substituted holo | spoofing | Published holo | low likelihood, critical impact | Fingerprint and provenance: gate actions/attest-build-provenance in the pages workflow; gate prism-code check of the holo identities in the page |
| Substituted host | spoofing | Published holo | low likelihood, critical impact | accepted: A page cannot defend against its own host. The holo carries signed build provenance a visitor can check, and the app can be rebuilt from its prompt. |
| Tampered model | tampering | Model source | low likelihood, major impact | Regenerated from the prompt: gate prismpm verify in the SDK image prismpm.lock pins; review app/prompt.json |
| Unsafe routed as pure | elevationOfPrivilege | Answer | low likelihood, critical impact | Effects never pure: proof CapabilityRouteProofs::inv001Holds; gate crates/conformance/tests/routes.rs |

## Quality

ISO/IEC 25010:2023 requirements. Each has a measure and a threshold that a theorem pins.

| Requirement | Characteristic | Measure | Threshold |
| --- | --- | --- | --- |
| Bounded allocation: The guest allocates at most 128 bytes for one request. | Performance efficiency: Resource utilization | Guest allocation bytes | 128 |
| Bounded request: A request over 64 bytes is refused before any field is read. | Performance efficiency: Time behaviour | Request bytes read | 64 |
| Every effect kind routed: Each of the seven effect kinds has a route, with and without forbid. | Functional suitability: Functional completeness | Effect kinds without a route | 0 |
| Every property proved: All 3 properties are theorems the Lean kernel checks. | Security: Integrity | Unproved properties | 0 |
| Every request answered: Every request gets an answer: a rule, capability otherwise, or invalid. | Functional suitability: Functional completeness | Unanswered requests | 0 |
| Every vector replays: All 19 acceptance vectors replay in the compiled guest, the shortest 0 bytes long. | Reliability: Faultlessness | Failed vectors | 0 |
| Examples answered as stated: Every one of the 6 examples of the spec is answered as it states. | Functional suitability: Functional correctness | Example mismatches | 0 |

## Compliance

One obligation per standard, each naming its evidence.

| Standard | Subject | Evidence |
| --- | --- | --- |
| ISO/IEC/IEEE 42010:2022 | Architecture description | Architecture::architectureDescriptionHolds |
| ISO/PAS 19450:2015 and OMG UML 2.5.1 | Design views | Design::viewOpmDecide, Design::viewUmlComponents, Design::viewUmlRequest, Design::viewUmlStates |
| ISO/IEC 25010:2023 | Product quality | Quality::qualityModelHolds |
| ISO/IEC 27034-1:2011 and ISO/IEC 27005:2022 | Application security and risk | Security::controlSet |
| OMG DMN 1.5, hit policy FIRST | Decision table | CapabilityRoute::judge |
| OpenSpec | Requirements | CapabilityRoute::application |
| SPDX MIT OR Apache-2.0 | Licensing | CapabilityRoute::application |

## Rendered design views

Written by the SDK from the design records when it verified the app.

### design/Design.viewOpmDecide.opl

```
View: Design::viewOpmDecide
Title: Deciding a Capability route request
Viewpoint: Architecture::viewpointRustDeveloperCorrectAnswers
Notation: ISO/PAS 19450:2015 OPM, Prism OPL profile

componentBrowser is an object.
componentCapabilityRouteGuest is an object.
componentCapabilityRouteGuest can be stateDeciding or stateIdle.
processDecide is a process.
processEncodeAnswer is a process.
processJudge is a process.
processParseRequest is a process.
componentCapabilityRouteGuest handles processDecide.
processParseRequest requires componentBrowser.
processEncodeAnswer affects componentBrowser.
processJudge invokes processEncodeAnswer.
processParseRequest invokes processJudge.
processDecide zooms into processParseRequest, processJudge, and processEncodeAnswer, in that sequence.

```

### design/Design.viewUmlComponents.puml

```
@startuml
' UML 2.5.1 component diagram
' view: Design::viewUmlComponents
' viewpoint: Architecture::viewpointVerifierIntegrityOfThePublishedApp
title Components of Capability route
component "componentBrowser" as c0
component "componentCapabilityRouteGuest" as c1
component "componentCapabilityRoutePage" as c2
component "componentCargoWorkspace" as c3
component "componentGitHubPages" as c4
component "componentPrismBuild" as c5
component "componentSourceRepository" as c6
component "componentUorustCLI" as c7
c0 --> c1 : edgeBrowserToCapabilityRouteGuest
c1 --> c0 : edgeCapabilityRouteGuestToBrowser
c1 --> c3 : edgeCapabilityRouteGuestToCargoWorkspace
c1 --> c7 : edgeCapabilityRouteGuestToUorustCLI
c2 --> c4 : edgeCapabilityRoutePageToGitHubPages
c3 --> c1 : edgeCargoWorkspaceToCapabilityRouteGuest
c4 --> c0 : edgeGitHubPagesToBrowser
c5 --> c1 : edgePrismBuildToCapabilityRouteGuest
c5 --> c2 : edgePrismBuildToCapabilityRoutePage
c6 --> c5 : edgeSourceRepositoryToPrismBuild
c7 --> c1 : edgeUorustCLIToCapabilityRouteGuest
@enduml

```

### design/Design.viewUmlRequest.puml

```
@startuml
' UML 2.5.1 sequence diagram
' view: Design::viewUmlRequest
' viewpoint: Architecture::viewpointRustDeveloperCorrectAnswers
title Answering a Capability route request
participant "componentBrowser" as p0
participant "componentCapabilityRouteGuest" as p1
p0 -> p1 : processDecide
p1 --> p0 : processDecide
@enduml

```

### design/Design.viewUmlStates.puml

```
@startuml
' UML 2.5.1 state machine diagram
' view: Design::viewUmlStates
' viewpoint: Architecture::viewpointVerifierRefusedMalformedRequests
title States of the Capability route guest
state "stateAnsweredCapability" as s0
state "stateAnsweredGated" as s1
state "stateAnsweredPure" as s2
state "stateAnsweredThreat" as s3
state "stateDeciding" as s4
state "stateIdle" as s5
state "stateRefused" as s6
[*] --> s5
s5 --> s4 : processParseRequest
s5 --> s6 : processParseRequest
s4 --> s3 : processRule1
s4 --> s3 : processRule2
s4 --> s1 : processRule3
s4 --> s2 : processRule4
s4 --> s0 : processOtherwise
s2 --> s5 : processEncodeAnswer
s1 --> s5 : processEncodeAnswer
s0 --> s5 : processEncodeAnswer
s3 --> s5 : processEncodeAnswer
s6 --> s5 : processEncodeAnswer
@enduml

```

## Prism source

Every file the builder wrote, laid out as a repository created from UOR-Foundation/template; the download prism-capability-route.zip has them all.

- app/src/Architecture.lex.tex (399 lines)
- app/src/Compliance.lex.tex (56 lines)
- app/src/Design.lex.tex (570 lines)
- app/src/Features.lex.tex (116 lines)
- app/src/Quality.lex.tex (347 lines)
- app/src/Security.lex.tex (551 lines)
- app/src/CapabilityRoute.lex.tex (199 lines)
- app/src/CapabilityRouteProofs.lex.tex (120 lines)
- app/lexlean.toml (43 lines)
- app/prompt.json (296 lines)
- model/ids.toml (59 lines)
- features/suites/capability\_route.feature (38 lines)
- crates/conformance/tests/capability\_route.rs (122 lines)
- site/app.json (103 lines)
- openspec/specs/capability-route/spec.md (158 lines)
