# Address admission

> Decide if a value gets a UOR-ADDR address. Two values that mean the same thing share one label, and a broken value gets none.

Inspired by UOR-Foundation/uor-addr (https://github.com/UOR-Foundation/uor-addr), live at https://uor-foundation.github.io/uor-addr/. Typed content addressing: one label for one meaning. 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 Address admission 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 | format, canonical, schema |
| 2. 4 rules | the first that matches wins |
| 3. Answer | labeled, schema, refused |
| 4. Proved | 3 theorems, 26 tests |

Verified by prismpm verify in the pinned SDK. Fingerprint: 189e3db8b2831fb0084c2e6fcfd740cf1251c64f44adb850b28d38fe788b807e. Acceptance vectors: 26. Claims: 6.

## The prompt

```json
{
  "schema": "prism/prompt/1",
  "goal": "Decide if a value gets a UOR-ADDR address. Two values that mean the same thing share one label, and a broken value gets none.",
  "pattern": "decisionTable",
  "repository": "UOR-Foundation/uor-addr",
  "license": "Apache-2.0",
  "app": {
    "name": "addr-admission",
    "title": "Address admission",
    "purpose": "Decide whether a value is labeled, refused, or labeled under its schema, from its format, whether it reached a canonical form and whether a pinned schema admits it.",
    "fields": [
      {
        "name": "format",
        "kind": "choice",
        "values": [
          "json",
          "sexp",
          "xml",
          "asn1"
        ],
        "means": "the value's format"
      },
      {
        "name": "canonical",
        "kind": "choice",
        "values": [
          "yes",
          "no"
        ],
        "means": "whether the value reached its published canonical form"
      },
      {
        "name": "schema",
        "kind": "choice",
        "values": [
          "none",
          "admits",
          "rejects"
        ],
        "means": "what a pinned schema says, if one is pinned"
      }
    ],
    "outcomes": [
      "labeled",
      "schema",
      "refused"
    ],
    "meanings": {
      "labeled": "a sha256 label of the canonical bytes",
      "schema": "the same label, admitted by the pinned schema",
      "refused": "no label"
    },
    "rules": [
      {
        "when": [
          {
            "field": "canonical",
            "op": "is",
            "value": "no"
          }
        ],
        "then": "refused",
        "why": "README: each format is routed through its canonical form, JCS, canonical S-expressions, XML-C14N 1.1 or DER, and only canonical bytes are hashed"
      },
      {
        "when": [
          {
            "field": "schema",
            "op": "is",
            "value": "rejects"
          }
        ],
        "then": "refused",
        "why": "crates/uor-addr/src/schema: a failed admission predicate is AddressFailure::SchemaViolation"
      },
      {
        "when": [
          {
            "field": "schema",
            "op": "is",
            "value": "admits"
          },
          {
            "field": "format",
            "op": "is",
            "value": "json"
          }
        ],
        "then": "schema",
        "why": "README: schema.org Photograph and Article and in-toto Statement v1 add admission without changing the label"
      },
      {
        "when": [
          {
            "field": "schema",
            "op": "is",
            "value": "admits"
          }
        ],
        "then": "refused",
        "why": "crates/uor-addr/src/schema: the schema wrappers are JSON descendants, so no schema is pinned to another format"
      }
    ],
    "otherwise": "labeled",
    "otherwiseWhy": "canonical with no schema pinned: the sha256 label of the canonical bytes",
    "properties": [
      {
        "kind": "never",
        "when": [
          {
            "field": "canonical",
            "op": "is",
            "value": "no"
          }
        ],
        "then": "labeled",
        "why": "a label always names canonical bytes"
      },
      {
        "kind": "never",
        "when": [
          {
            "field": "schema",
            "op": "is",
            "value": "rejects"
          }
        ],
        "then": "schema",
        "why": "a rejecting schema never admits"
      },
      {
        "kind": "never",
        "when": [
          {
            "field": "format",
            "op": "is not",
            "value": "json"
          }
        ],
        "then": "schema",
        "why": "schema admission exists only for JSON values"
      }
    ],
    "examples": [
      {
        "request": "json yes none",
        "response": "labeled"
      },
      {
        "request": "xml yes none",
        "response": "labeled"
      },
      {
        "request": "json yes admits",
        "response": "schema"
      },
      {
        "request": "xml yes admits",
        "response": "refused"
      },
      {
        "request": "sexp no none",
        "response": "refused"
      },
      {
        "request": "asn1 yes rejects",
        "response": "refused"
      }
    ]
  },
  "stakeholders": [
    {
      "name": "Integrator",
      "text": "Passes data across system boundaries and needs a label only for canonical, admitted values.",
      "concerns": [
        "Proved guarantees",
        "Correct answers"
      ]
    },
    {
      "name": "Binding maintainer",
      "text": "Ships the npm, PyPI, C and WebAssembly bindings and needs each to produce the same label byte for byte.",
      "concerns": [
        "One label in every language"
      ]
    }
  ],
  "concerns": [
    {
      "name": "One label in every language",
      "text": "Every binding produces the same 71-byte sha256 label for the same value.",
      "model": "component"
    }
  ],
  "components": [
    {
      "name": "Language bindings",
      "text": "uor-addr-c, uor-addr-wasm and the npm and PyPI packages, which wrap the same Rust core.",
      "kind": "releaseBinary"
    },
    {
      "name": "Value producers",
      "text": "The systems on each side of a boundary that produce JSON, S-expression, XML and ASN.1 values.",
      "kind": "externalSystem"
    }
  ],
  "threats": [
    {
      "name": "Non-canonical bytes labeled",
      "text": "A value is hashed before reaching its canonical form, so two values with one meaning get two labels.",
      "stride": "tampering",
      "asset": "answer",
      "likelihood": "low",
      "impact": "major",
      "control": {
        "name": "Canonical first",
        "text": "A value that did not reach its canonical form is never labeled, proved for every request.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "AddrAdmissionProofs::inv001Holds"
          }
        ]
      }
    },
    {
      "name": "Schema pinned to the wrong format",
      "text": "A schema admission is claimed for an XML or ASN.1 value, which no schema wrapper reads.",
      "stride": "spoofing",
      "asset": "answer",
      "likelihood": "low",
      "impact": "minor",
      "control": {
        "name": "JSON schemas only",
        "text": "Only a JSON value is answered schema, proved for every request.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "AddrAdmissionProofs::inv003Holds"
          }
        ]
      }
    },
    {
      "name": "Label collision",
      "text": "Two values with different meanings get the same label.",
      "stride": "spoofing",
      "asset": "answer",
      "likelihood": "low",
      "impact": "critical",
      "accepted": "Different canonical bytes give different labels up to the SHA-256 sensitivity bound, which the README states as the guarantee."
    }
  ],
  "quality": [
    {
      "characteristic": "Compatibility",
      "subcharacteristic": "Interoperability",
      "requirement": "Same label in every binding",
      "text": "The Rust, C, WebAssembly, npm and PyPI surfaces produce the same label byte for byte.",
      "measure": "Disagreeing bindings",
      "measureText": "Bindings whose label for an example differs from the Rust core.",
      "threshold": 0
    }
  ],
  "journeys": [
    {
      "stakeholder": "Integrator",
      "steps": [
        "REQ-001",
        "REQ-002",
        "REQ-003",
        "otherwise"
      ]
    },
    {
      "stakeholder": "Binding maintainer",
      "steps": [
        "REQ-004",
        "INV-001",
        "INV-003"
      ]
    }
  ],
  "axioms": {
    "inv001Holds": [
      "Classical.choice",
      "Quot.sound",
      "propext"
    ]
  }
}
```

## Claims

- AA-01: The app never answers labeled when canonical is no
- AA-02: The app never answers schema when schema is rejects
- AA-03: The app never answers schema when format is not json
- AA-04: The architecture description declares every stakeholder, concern, component, edge, viewpoint and view it references
- AA-05: The ISO/IEC 25010 quality model numbers every characteristic, subcharacteristic, requirement and measure, and every parent it names is declared
- AA-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 | labeled, schema, refused |

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

|  | rules |
| --- | --- |
| labeled | 0 |
| schema | 1 |
| refused | 3 |

## Behavior

A request is format, canonical, schema, separated by spaces. The first rule that matches decides. If none matches, the answer is labeled. A request over 88 bytes, or in any other form, is answered invalid.

| Rule | When | Answer | Why |
| --- | --- | --- | --- |
| REQ-001 | canonical is no | refused | README: each format is routed through its canonical form, JCS, canonical S-expressions, XML-C14N 1.1 or DER, and only canonical bytes are hashed |
| REQ-002 | schema is rejects | refused | crates/uor-addr/src/schema: a failed admission predicate is AddressFailure::SchemaViolation |
| REQ-003 | schema is admits and format is json | schema | README: schema.org Photograph and Article and in-toto Statement v1 add admission without changing the label |
| REQ-004 | schema is admits | refused | crates/uor-addr/src/schema: the schema wrappers are JSON descendants, so no schema is pinned to another format |
| otherwise | no rule matches | labeled | canonical with no schema pinned: the sha256 label of the canonical bytes |

## 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 labeled when canonical is no. | AddrAdmissionProofs::inv001Holds | a label always names canonical bytes |
| INV-002 | It never answers schema when schema is rejects. | AddrAdmissionProofs::inv002Holds | a rejecting schema never admits |
| INV-003 | It never answers schema when format is not json. | AddrAdmissionProofs::inv003Holds | schema admission exists only for JSON values |

## Architecture

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

| Stakeholder | Who they are | Concerns |
| --- | --- | --- |
| Binding maintainer | Ships the npm, PyPI, C and WebAssembly bindings and needs each to produce the same label byte for byte. | One label in every language |
| Integrator | Passes data across system boundaries and needs a label only for canonical, admitted values. | Proved guarantees, Correct answers |
| 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 labeled when none does, as the spec states. | quality |
| Integrity of the published app | What a visitor runs is the holo the build verified, with its fingerprint and signed provenance beside it. | security |
| One label in every language | Every binding produces the same 71-byte sha256 label for the same value. | component |
| 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 3 fields in order, or is longer than 88 bytes, is answered invalid and never guessed. | security |

## Components

8 components and 11 edges between them.

| Component | Kind | What it is |
| --- | --- | --- |
| Address admission guest | service | The Core-Wasm guest built from the model: it answers one request of at most 88 bytes with one answer of at most 64. |
| Address admission page | staticSite | The page the template publishes: the holo, its fingerprint, its provenance and its acceptance vectors. |
| Browser | externalSystem | The visitor's web browser, which loads the page and runs the Address admission guest. |
| GitHub Pages | externalSystem | Serves the page and the holo from the repository Pages workflow. |
| Language bindings | releaseBinary | uor-addr-c, uor-addr-wasm and the npm and PyPI packages, which wrap the same Rust core. |
| 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. |
| Value producers | externalSystem | The systems on each side of a boundary that produce JSON, S-expression, XML and ASN.1 values. |

## Design views

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

| View | Diagram | Viewpoint |
| --- | --- | --- |
| Deciding a Address admission request | opmObjectProcess | Integrator: Correct answers |
| Components of Address admission | umlComponent | Verifier: Integrity of the published app |
| Answering a Address admission request | umlSequence | Integrator: Correct answers |
| States of the Address admission 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 canonical is no, the answer is refused. | AddrAdmission::rule1, AddrAdmission::judge | AddrAdmission::application |
| When schema is rejects, the answer is refused. | AddrAdmission::rule2, AddrAdmission::judge | AddrAdmission::application |
| When schema is admits and format is json, the answer is schema. | AddrAdmission::rule3, AddrAdmission::judge | AddrAdmission::application |
| When schema is admits, the answer is refused. | AddrAdmission::rule4, AddrAdmission::judge | AddrAdmission::application |
| When no rule matches, the answer is labeled. | AddrAdmission::judge | AddrAdmission::application |
| A request that is not format, canonical, schema in order, separated by single spaces, or is over 88 bytes, is answered invalid. | AddrAdmission::dispatch, AddrAdmission::decodeField1 | AddrAdmission::application |
| It never answers labeled when canonical is no. | AddrAdmission::judge | AddrAdmissionProofs::inv001Holds |
| It never answers schema when schema is rejects. | AddrAdmission::judge | AddrAdmissionProofs::inv002Holds |
| It never answers schema when format is not json. | AddrAdmission::judge | AddrAdmissionProofs::inv003Holds |

## Journeys

The ordered features each stakeholder takes.

| Stakeholder | Steps |
| --- | --- |
| Binding maintainer | REQ-004 → INV-001 → INV-003 |
| Integrator | REQ-001 → REQ-002 → REQ-003 → otherwise |
| 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 AddrAdmissionProofs::inv001Holds |
| Answer that breaks INV-002 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-002: proof AddrAdmissionProofs::inv002Holds |
| Answer that breaks INV-003 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-003: proof AddrAdmissionProofs::inv003Holds |
| Granted capability | informationDisclosure | Answer | low likelihood, major impact | No capability granted: gate prism-code check refuses an ungranted guest import |
| Label collision | spoofing | Answer | low likelihood, critical impact | accepted: Different canonical bytes give different labels up to the SHA-256 sensitivity bound, which the README states as the guarantee. |
| Malformed request | tampering | Request bytes | high likelihood, major impact | Strict decoder: gate malformed-request acceptance vectors, replayed in the compiled guest by prismpm verify |
| Non-canonical bytes labeled | tampering | Answer | low likelihood, major impact | Canonical first: proof AddrAdmissionProofs::inv001Holds |
| 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 |
| Schema pinned to the wrong format | spoofing | Answer | low likelihood, minor impact | JSON schemas only: proof AddrAdmissionProofs::inv003Holds |
| 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 |

## 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 176 bytes for one request. | Performance efficiency: Resource utilization | Guest allocation bytes | 176 |
| Bounded request: A request over 88 bytes is refused before any field is read. | Performance efficiency: Time behaviour | Request bytes read | 88 |
| 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, labeled otherwise, or invalid. | Functional suitability: Functional completeness | Unanswered requests | 0 |
| Every vector replays: All 26 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 |
| Same label in every binding: The Rust, C, WebAssembly, npm and PyPI surfaces produce the same label byte for byte. | Compatibility: Interoperability | Disagreeing bindings | 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 | AddrAdmission::judge |
| OpenSpec | Requirements | AddrAdmission::application |
| SPDX Apache-2.0 | Licensing | AddrAdmission::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 Address admission request
Viewpoint: Architecture::viewpointIntegratorCorrectAnswers
Notation: ISO/PAS 19450:2015 OPM, Prism OPL profile

componentAddressAdmissionGuest is an object.
componentAddressAdmissionGuest can be stateDeciding or stateIdle.
componentBrowser is an object.
processDecide is a process.
processEncodeAnswer is a process.
processJudge is a process.
processParseRequest is a process.
componentAddressAdmissionGuest 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 Address admission
component "componentAddressAdmissionGuest" as c0
component "componentAddressAdmissionPage" as c1
component "componentBrowser" as c2
component "componentGitHubPages" as c3
component "componentLanguageBindings" as c4
component "componentPrismBuild" as c5
component "componentSourceRepository" as c6
component "componentValueProducers" as c7
c0 --> c2 : edgeAddressAdmissionGuestToBrowser
c0 --> c4 : edgeAddressAdmissionGuestToLanguageBindings
c0 --> c7 : edgeAddressAdmissionGuestToValueProducers
c1 --> c3 : edgeAddressAdmissionPageToGitHubPages
c2 --> c0 : edgeBrowserToAddressAdmissionGuest
c3 --> c2 : edgeGitHubPagesToBrowser
c4 --> c0 : edgeLanguageBindingsToAddressAdmissionGuest
c5 --> c0 : edgePrismBuildToAddressAdmissionGuest
c5 --> c1 : edgePrismBuildToAddressAdmissionPage
c6 --> c5 : edgeSourceRepositoryToPrismBuild
c7 --> c0 : edgeValueProducersToAddressAdmissionGuest
@enduml

```

### design/Design.viewUmlRequest.puml

```
@startuml
' UML 2.5.1 sequence diagram
' view: Design::viewUmlRequest
' viewpoint: Architecture::viewpointIntegratorCorrectAnswers
title Answering a Address admission request
participant "componentBrowser" as p0
participant "componentAddressAdmissionGuest" 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 Address admission guest
state "stateAnsweredLabeled" as s0
state "stateAnsweredRefused" as s1
state "stateAnsweredSchema" as s2
state "stateDeciding" as s3
state "stateIdle" as s4
state "stateRefused" as s5
[*] --> s4
s4 --> s3 : processParseRequest
s4 --> s5 : processParseRequest
s3 --> s1 : processRule1
s3 --> s1 : processRule2
s3 --> s2 : processRule3
s3 --> s1 : processRule4
s3 --> s0 : processOtherwise
s0 --> s4 : processEncodeAnswer
s2 --> s4 : processEncodeAnswer
s1 --> s4 : processEncodeAnswer
s5 --> s4 : processEncodeAnswer
@enduml

```

## Prism source

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

- app/src/Architecture.lex.tex (399 lines)
- app/src/Compliance.lex.tex (56 lines)
- app/src/Design.lex.tex (549 lines)
- app/src/Features.lex.tex (116 lines)
- app/src/Quality.lex.tex (361 lines)
- app/src/Security.lex.tex (551 lines)
- app/src/AddrAdmission.lex.tex (214 lines)
- app/src/AddrAdmissionProofs.lex.tex (117 lines)
- app/lexlean.toml (43 lines)
- app/prompt.json (292 lines)
- model/ids.toml (59 lines)
- features/suites/addr\_admission.feature (38 lines)
- crates/conformance/tests/addr\_admission.rs (122 lines)
- site/app.json (102 lines)
- openspec/specs/addr-admission/spec.md (158 lines)
