# Publish gate

> Decide if Prism-DevRel may publish its pages, so no reader ever sees a page that gets the model wrong.

Inspired by afflom/prism-devrel (https://github.com/afflom/prism-devrel), live at https://afflom.github.io/prism-devrel/. This site: a Prism model of developer relations, applied to itself. 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 Publish gate 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 | uncovered, undeclared, pin |
| 2. 3 rules | the first that matches wins |
| 3. Answer | publish, regenerate, refuse |
| 4. Proved | 3 theorems, 32 tests |

Verified by prismpm verify in the pinned SDK. Fingerprint: f460b77c6b0e9cc9d9f43b6ce8af772cc3c81131fd5de8f4d9bfe4db44379771. Acceptance vectors: 32. Claims: 6.

## The prompt

```json
{
  "schema": "prism/prompt/1",
  "goal": "Decide if Prism-DevRel may publish its pages, so no reader ever sees a page that gets the model wrong.",
  "pattern": "decisionTable",
  "repository": "afflom/prism-devrel",
  "app": {
    "name": "devrel-gate",
    "title": "Publish gate",
    "purpose": "Decide whether the learning catalog is published, regenerated, or refused, from the records no page covers, the covers that name an undeclared resource, and whether the catalog matches the pinned subject commit.",
    "fields": [
      {
        "name": "uncovered",
        "kind": "number",
        "min": 0,
        "means": "subject records no resource covers"
      },
      {
        "name": "undeclared",
        "kind": "number",
        "min": 0,
        "means": "covers that name an undeclared resource"
      },
      {
        "name": "pin",
        "kind": "choice",
        "values": [
          "current",
          "stale"
        ],
        "means": "whether the committed catalog is the pinned commit's"
      }
    ],
    "outcomes": [
      "publish",
      "regenerate",
      "refuse"
    ],
    "meanings": {
      "publish": "the pages workflow publishes the catalog",
      "regenerate": "not published: the catalog must be regenerated from the pinned commit with devrel-catalog",
      "refuse": "not published: the catalog misstates the subject"
    },
    "rules": [
      {
        "when": [
          {
            "field": "undeclared",
            "op": ">=",
            "value": 1
          }
        ],
        "then": "refuse",
        "why": "README DR-02: a catalog with an undeclared resource is refused (Catalog::undeclaredResourceRefused)"
      },
      {
        "when": [
          {
            "field": "uncovered",
            "op": ">=",
            "value": 1
          }
        ],
        "then": "refuse",
        "why": "README DR-01 and DR-02: every facet record is covered (Catalog::catalogCovered, uncoveredRecordRefused)"
      },
      {
        "when": [
          {
            "field": "pin",
            "op": "is",
            "value": "stale"
          }
        ],
        "then": "regenerate",
        "why": ".github/workflows/pages.yml DR-03: devrel-catalog --check fails when the committed catalog is not the pinned commit's"
      }
    ],
    "otherwise": "publish",
    "otherwiseWhy": "complete, declared and current: the pages workflow publishes",
    "properties": [
      {
        "kind": "never",
        "when": [
          {
            "field": "uncovered",
            "op": ">=",
            "value": 1
          }
        ],
        "then": "publish",
        "why": "no record goes untaught"
      },
      {
        "kind": "never",
        "when": [
          {
            "field": "undeclared",
            "op": ">=",
            "value": 1
          }
        ],
        "then": "publish",
        "why": "no fabricated coverage"
      },
      {
        "kind": "never",
        "when": [
          {
            "field": "pin",
            "op": "is",
            "value": "stale"
          }
        ],
        "then": "publish",
        "why": "no stale catalog"
      }
    ],
    "examples": [
      {
        "request": "0 0 current",
        "response": "publish"
      },
      {
        "request": "0 0 stale",
        "response": "regenerate"
      },
      {
        "request": "3 0 current",
        "response": "refuse"
      },
      {
        "request": "0 2 current",
        "response": "refuse"
      },
      {
        "request": "3 2 stale",
        "response": "refuse"
      }
    ]
  },
  "stakeholders": [
    {
      "name": "Developer",
      "text": "Learns Prism from the catalog and needs every page to state only what the subject declares.",
      "concerns": [
        "Proved guarantees",
        "Correct answers"
      ]
    },
    {
      "name": "DevRel author",
      "text": "Writes the pages and needs a publish to fail while any record is untaught.",
      "concerns": [
        "Proved guarantees",
        "Catalog follows its pin"
      ]
    }
  ],
  "concerns": [
    {
      "name": "Catalog follows its pin",
      "text": "The committed catalog is the catalog of exactly the commit devrel/subjects.json pins, DR-03.",
      "model": "component"
    }
  ],
  "components": [
    {
      "name": "Catalog subject",
      "text": "The catalog subject's model, fetched at the full commit devrel/subjects.json pins.",
      "kind": "externalSystem"
    },
    {
      "name": "devrel-catalog",
      "text": "crates/devrel: reads every .lex.tex module of the subject and writes app/src/Catalog.lex.tex and the learning pages.",
      "kind": "cliAdapter"
    }
  ],
  "threats": [
    {
      "name": "Pin moved without regenerating",
      "text": "devrel/subjects.json is moved to a new commit and the old catalog is published as if it taught the new one.",
      "stride": "tampering",
      "asset": "source",
      "likelihood": "medium",
      "impact": "major",
      "control": {
        "name": "Catalog checked against its pin",
        "text": "pages.yml regenerates the catalog from the pinned commit and fails on any difference; a stale pin is never published, proved for every request.",
        "evidence": [
          {
            "kind": "gate",
            "reference": ".github/workflows/pages.yml devrel-catalog --check"
          },
          {
            "kind": "proof",
            "reference": "DevrelGateProofs::inv003Holds"
          }
        ]
      }
    },
    {
      "name": "Fabricated cover",
      "text": "A page claims to cover a resource the catalog does not declare.",
      "stride": "spoofing",
      "asset": "answer",
      "likelihood": "low",
      "impact": "major",
      "control": {
        "name": "Declared covers only",
        "text": "A cover naming an undeclared resource refuses the catalog, in the Lean catalog and in this app.",
        "evidence": [
          {
            "kind": "gate",
            "reference": "Catalog::undeclaredResourceRefused"
          },
          {
            "kind": "proof",
            "reference": "DevrelGateProofs::inv002Holds"
          }
        ]
      }
    },
    {
      "name": "Subject commit substituted",
      "text": "The fetched subject is not the commit the pin names.",
      "stride": "spoofing",
      "asset": "source",
      "likelihood": "low",
      "impact": "critical",
      "control": {
        "name": "Full commit fetched",
        "text": "pages.yml fetches the pinned full commit and checks rev-parse HEAD equals it before building the catalog.",
        "evidence": [
          {
            "kind": "gate",
            "reference": ".github/workflows/pages.yml subject checkout"
          }
        ]
      }
    }
  ],
  "quality": [
    {
      "characteristic": "Functional suitability",
      "subcharacteristic": "Functional completeness",
      "requirement": "Every record taught",
      "text": "Every facet record of the pinned subject is covered by at least one learning resource before the catalog is published.",
      "measure": "Uncovered records",
      "measureText": "Facet records of the subject no resource covers.",
      "threshold": 0
    }
  ],
  "journeys": [
    {
      "stakeholder": "Developer",
      "steps": [
        "REQ-001",
        "REQ-002",
        "INV-001",
        "INV-002"
      ]
    },
    {
      "stakeholder": "DevRel author",
      "steps": [
        "REQ-003",
        "otherwise",
        "INV-003"
      ]
    }
  ],
  "license": "MIT OR Apache-2.0",
  "axioms": {}
}
```

## Claims

- DG-01: The app never answers publish when uncovered is at least 1
- DG-02: The app never answers publish when undeclared is at least 1
- DG-03: The app never answers publish when pin is stale
- DG-04: The architecture description declares every stakeholder, concern, component, edge, viewpoint and view it references
- DG-05: The ISO/IEC 25010 quality model numbers every characteristic, subcharacteristic, requirement and measure, and every parent it names is declared
- DG-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 | publish, regenerate, refuse |

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

|  | rules |
| --- | --- |
| publish | 0 |
| regenerate | 1 |
| refuse | 2 |

## Behavior

A request is uncovered, undeclared, pin, separated by spaces. The first rule that matches decides. If none matches, the answer is publish. A request over 88 bytes, or in any other form, is answered invalid.

| Rule | When | Answer | Why |
| --- | --- | --- | --- |
| REQ-001 | undeclared is at least 1 | refuse | README DR-02: a catalog with an undeclared resource is refused (Catalog::undeclaredResourceRefused) |
| REQ-002 | uncovered is at least 1 | refuse | README DR-01 and DR-02: every facet record is covered (Catalog::catalogCovered, uncoveredRecordRefused) |
| REQ-003 | pin is stale | regenerate | .github/workflows/pages.yml DR-03: devrel-catalog --check fails when the committed catalog is not the pinned commit's |
| otherwise | no rule matches | publish | complete, declared and current: the pages workflow publishes |

## 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 publish when uncovered is at least 1. | DevrelGateProofs::inv001Holds | no record goes untaught |
| INV-002 | It never answers publish when undeclared is at least 1. | DevrelGateProofs::inv002Holds | no fabricated coverage |
| INV-003 | It never answers publish when pin is stale. | DevrelGateProofs::inv003Holds | no stale catalog |

## Architecture

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

| Stakeholder | Who they are | Concerns |
| --- | --- | --- |
| DevRel author | Writes the pages and needs a publish to fail while any record is untaught. | Proved guarantees, Catalog follows its pin |
| Developer | Learns Prism from the catalog and needs every page to state only what the subject declares. | 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 |
| --- | --- | --- |
| Catalog follows its pin | The committed catalog is the catalog of exactly the commit devrel/subjects.json pins, DR-03. | component |
| Correct answers | Every well-formed request is answered by the first rule that matches it, or publish 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 |
| 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 |
| --- | --- | --- |
| Browser | externalSystem | The visitor's web browser, which loads the page and runs the Publish gate guest. |
| Catalog subject | externalSystem | The catalog subject's model, fetched at the full commit devrel/subjects.json pins. |
| devrel-catalog | cliAdapter | crates/devrel: reads every .lex.tex module of the subject and writes app/src/Catalog.lex.tex and the learning pages. |
| 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. |
| Publish gate 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. |
| Publish gate page | staticSite | The page the template publishes: the holo, its fingerprint, its provenance and its acceptance vectors. |
| Source repository | externalSystem | The repository that holds the prompt, the model and its gate. |

## Design views

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

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

## Features and journeys

8 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 undeclared is at least 1, the answer is refuse. | DevrelGate::rule1, DevrelGate::judge | DevrelGate::application |
| When uncovered is at least 1, the answer is refuse. | DevrelGate::rule2, DevrelGate::judge | DevrelGate::application |
| When pin is stale, the answer is regenerate. | DevrelGate::rule3, DevrelGate::judge | DevrelGate::application |
| When no rule matches, the answer is publish. | DevrelGate::judge | DevrelGate::application |
| A request that is not uncovered, undeclared, pin in order, separated by single spaces, or is over 88 bytes, is answered invalid. | DevrelGate::dispatch, DevrelGate::decodeField1 | DevrelGate::application |
| It never answers publish when uncovered is at least 1. | DevrelGate::judge | DevrelGateProofs::inv001Holds |
| It never answers publish when undeclared is at least 1. | DevrelGate::judge | DevrelGateProofs::inv002Holds |
| It never answers publish when pin is stale. | DevrelGate::judge | DevrelGateProofs::inv003Holds |

## Journeys

The ordered features each stakeholder takes.

| Stakeholder | Steps |
| --- | --- |
| DevRel author | REQ-003 → otherwise → INV-003 |
| Developer | REQ-001 → REQ-002 → INV-001 → INV-002 |
| 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 DevrelGateProofs::inv001Holds |
| Answer that breaks INV-002 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-002: proof DevrelGateProofs::inv002Holds |
| Answer that breaks INV-003 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-003: proof DevrelGateProofs::inv003Holds |
| Fabricated cover | spoofing | Answer | low likelihood, major impact | Declared covers only: gate Catalog::undeclaredResourceRefused; proof DevrelGateProofs::inv002Holds |
| 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 |
| Pin moved without regenerating | tampering | Model source | medium likelihood, major impact | Catalog checked against its pin: gate .github/workflows/pages.yml devrel-catalog --check; proof DevrelGateProofs::inv003Holds |
| Subject commit substituted | spoofing | Model source | low likelihood, critical impact | Full commit fetched: gate .github/workflows/pages.yml subject checkout |
| 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 record taught: Every facet record of the pinned subject is covered by at least one learning resource before the catalog is published. | Functional suitability: Functional completeness | Uncovered records | 0 |
| Every request answered: Every request gets an answer: a rule, publish otherwise, or invalid. | Functional suitability: Functional completeness | Unanswered requests | 0 |
| Every vector replays: All 32 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 5 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 | DevrelGate::judge |
| OpenSpec | Requirements | DevrelGate::application |
| SPDX MIT OR Apache-2.0 | Licensing | DevrelGate::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 Publish gate request
Viewpoint: Architecture::viewpointDeveloperCorrectAnswers
Notation: ISO/PAS 19450:2015 OPM, Prism OPL profile

componentBrowser is an object.
componentPublishGateGuest is an object.
componentPublishGateGuest can be stateDeciding or stateIdle.
processDecide is a process.
processEncodeAnswer is a process.
processJudge is a process.
processParseRequest is a process.
componentPublishGateGuest 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 Publish gate
component "componentBrowser" as c0
component "componentCatalogSubject" as c1
component "componentDevrelCatalog" as c2
component "componentGitHubPages" as c3
component "componentPrismBuild" as c4
component "componentPublishGateGuest" as c5
component "componentPublishGatePage" as c6
component "componentSourceRepository" as c7
c0 --> c5 : edgeBrowserToPublishGateGuest
c1 --> c5 : edgeCatalogSubjectToPublishGateGuest
c2 --> c5 : edgeDevrelCatalogToPublishGateGuest
c3 --> c0 : edgeGitHubPagesToBrowser
c4 --> c5 : edgePrismBuildToPublishGateGuest
c4 --> c6 : edgePrismBuildToPublishGatePage
c5 --> c0 : edgePublishGateGuestToBrowser
c5 --> c1 : edgePublishGateGuestToCatalogSubject
c5 --> c2 : edgePublishGateGuestToDevrelCatalog
c6 --> c3 : edgePublishGatePageToGitHubPages
c7 --> c4 : edgeSourceRepositoryToPrismBuild
@enduml

```

### design/Design.viewUmlRequest.puml

```
@startuml
' UML 2.5.1 sequence diagram
' view: Design::viewUmlRequest
' viewpoint: Architecture::viewpointDeveloperCorrectAnswers
title Answering a Publish gate request
participant "componentBrowser" as p0
participant "componentPublishGateGuest" 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 Publish gate guest
state "stateAnsweredPublish" as s0
state "stateAnsweredRefuse" as s1
state "stateAnsweredRegenerate" 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 --> 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-devrel-gate.zip has them all.

- app/src/Architecture.lex.tex (413 lines)
- app/src/Compliance.lex.tex (56 lines)
- app/src/Design.lex.tex (535 lines)
- app/src/Features.lex.tex (109 lines)
- app/src/Quality.lex.tex (347 lines)
- app/src/Security.lex.tex (565 lines)
- app/src/DevrelGate.lex.tex (199 lines)
- app/src/DevrelGateProofs.lex.tex (93 lines)
- app/lexlean.toml (43 lines)
- app/prompt.json (275 lines)
- model/ids.toml (59 lines)
- features/suites/devrel\_gate.feature (38 lines)
- crates/conformance/tests/devrel\_gate.rs (122 lines)
- site/app.json (102 lines)
- openspec/specs/devrel-gate/spec.md (146 lines)
