PrismDevRelOpen the app
How-to guides: How to build a policy decision app

Build

How to build a decision table appHow to build a policy decision appHow to build a state machine appHow to verify an app before you publish itHow to publish an app on GitHub PagesHow to give an AI agent the prism_prompt tool

// how-to guide · Build

How to build a policy decision app

Write a prompt for a policy decision app, check it, prove it with the gate and publish it.

Choose this pattern when its answer is the one your app gives. The answer is one XACML 3.0 decision: permit, deny, not-applicable, indeterminate. A policy that applies gives permit or deny. If none applies, the answer is not-applicable. If the request cannot be judged, it is indeterminate.

The standard is OASIS XACML 3.0 policy decision point. The guide builds the Emporous admission example; put your own rules in its place.

The steps, in order1. Write the prompt: start from Emporous admission 2. Check the prompt: node builder/cli.mjs check 3. Build it and pass the gate: just vv in the locked SDK 4. Publish it: GitHub Pages01Write the promptstart fromEmporous admission02Check the promptnodebuilder/cli.mjscheck03Build it andpass the gatejust vv in thelocked SDK04Publish itGitHub PagesThe steps, in order1. Write the prompt: start from Emporous admission 2. Check the prompt: node builder/cli.mjs check 3. Build it and pass the gate: just vv in the locked SDK 4. Publish it: GitHub Pages01Write the promptstart from Emporous admission02Check the promptnode builder/cli.mjs check03Build it and pass the gatejust vv in the locked SDK04Publish itGitHub Pages
The steps, in order. 4 steps. Each section below is one of them.
The data in this figure
StepWhat happens
1. Write the promptstart from Emporous admission
2. Check the promptnode builder/cli.mjs check
3. Build it and pass the gatejust vv in the locked SDK
4. Publish itGitHub Pages

1. Write the prompt

Start from the Emporous admission prompt, the policy decision example with the fewest rules (5 rules). Keep pattern set to policyDecision. Replace the fields, answers, rules and examples of its app with your own.

1. Write the prompt 351 lines
{
  "schema": "prism/prompt/1",
  "goal": "Decide if Emporous lets an object into a namespace. Each object must come from someone who is allowed to add it there.",
  "pattern": "policyDecision",
  "repository": "afflom/emporous",
  "app": {
    "name": "emporous-admit-policy",
    "title": "Emporous admission",
    "purpose": "Decide whether one representation is admitted under the scope its namespace names, from the scope, its realization, the principal and the bytes.",
    "fields": [
      {
        "name": "namespace",
        "kind": "choice",
        "values": [
          "scoped",
          "unscoped",
          "conflicted"
        ],
        "means": "whether the namespace names exactly one scope, none, or more than one"
      },
      {
        "name": "realization",
        "kind": "choice",
        "values": [
          "known",
          "unknown"
        ],
        "means": "whether the registry knows the realization the scope names"
      },
      {
        "name": "principal",
        "kind": "choice",
        "values": [
          "authorized",
          "unauthorized"
        ],
        "means": "whether a capability-edge walk reaches the principal from the scope authorization"
      },
      {
        "name": "bytes",
        "kind": "choice",
        "values": [
          "realizable",
          "refused"
        ],
        "means": "whether the realization carries the bytes to a canonical form"
      }
    ],
    "outcomes": [
      "permit",
      "deny",
      "not-applicable",
      "indeterminate"
    ],
    "meanings": {
      "permit": "XACML 3.0 section 7: Permit; the object kappa, the representation kappa and a DerivedFrom edge are written",
      "deny": "XACML 3.0 section 7: Deny; StoreError::Rejected and no DerivedFrom edge is written",
      "not-applicable": "XACML 3.0 section 7: NotApplicable; the namespace names no scope, so no policy governs it",
      "indeterminate": "XACML 3.0 section 7: Indeterminate; the scope cannot be evaluated, because its realization is unknown or the namespace names several scopes"
    },
    "rules": [
      {
        "when": [
          {
            "field": "namespace",
            "op": "is",
            "value": "unscoped"
          }
        ],
        "then": "not-applicable",
        "why": "crates/admission/src/scope.rs scope_of_namespace: the namespace names no scope, StoreError::NotFound"
      },
      {
        "when": [
          {
            "field": "namespace",
            "op": "is",
            "value": "conflicted"
          }
        ],
        "then": "indeterminate",
        "why": "crates/admission/src/scope.rs: a namespace naming more than one scope is StoreError::Conflict"
      },
      {
        "when": [
          {
            "field": "realization",
            "op": "is",
            "value": "unknown"
          }
        ],
        "then": "indeterminate",
        "why": "crates/admission/src/admit.rs: the registry does not know the realization, StoreError::NotFound (EA-03)"
      },
      {
        "when": [
          {
            "field": "principal",
            "op": "is",
            "value": "unauthorized"
          }
        ],
        "then": "deny",
        "why": "crates/admission/src/admit.rs and auth.rs: the principal is not authorized by the scope capability, StoreError::Rejected (EA-05)"
      },
      {
        "when": [
          {
            "field": "bytes",
            "op": "is",
            "value": "refused"
          }
        ],
        "then": "deny",
        "why": "crates/admission/src/realize.rs: the realization refuses the bytes, StoreError::Rejected"
      }
    ],
    "otherwise": "permit",
    "otherwiseWhy": "SPEC.md 5.1: the canonical form is ingested on the scope axis and the received bytes at their own kappa, joined by a DerivedFrom edge",
    "properties": [
      {
        "kind": "never",
        "when": [
          {
            "field": "principal",
            "op": "is",
            "value": "unauthorized"
          }
        ],
        "then": "permit",
        "why": "EA-05: admission into a namespace requires the capability its scope names"
      },
      {
        "kind": "never",
        "when": [
          {
            "field": "realization",
            "op": "is",
            "value": "unknown"
          }
        ],
        "then": "permit",
        "why": "EA-03: a scope naming a realization the registry does not know is reported as not found"
      },
      {
        "kind": "always",
        "when": [
          {
            "field": "namespace",
            "op": "is",
            "value": "scoped"
          },
          {
            "field": "realization",
            "op": "is",
            "value": "known"
          },
          {
            "field": "principal",
            "op": "is",
            "value": "unauthorized"
          }
        ],
        "then": "deny",
        "why": "admit.rs checks authorization before the realization reads the bytes"
      },
      {
        "kind": "always",
        "when": [
          {
            "field": "namespace",
            "op": "is",
            "value": "unscoped"
          }
        ],
        "then": "not-applicable",
        "why": "without a scope there is no realization, axis or authorization to apply"
      }
    ],
    "examples": [
      {
        "request": "scoped known authorized realizable",
        "response": "permit"
      },
      {
        "request": "scoped known unauthorized realizable",
        "response": "deny"
      },
      {
        "request": "scoped unknown authorized realizable",
        "response": "indeterminate"
      },
      {
        "request": "unscoped known authorized realizable",
        "response": "not-applicable"
      },
      {
        "request": "scoped known authorized refused",
        "response": "deny"
      },
      {
        "request": "conflicted known authorized realizable",
        "response": "indeterminate"
      },
      {
        "request": "scoped known unauthorized refused",
        "response": "deny"
      }
    ]
  },
  "stakeholders": [
    {
      "name": "Publisher",
      "text": "Admits artefact representations into a namespace and needs each admission addressed by the canonical form its scope selects.",
      "concerns": [
        "Correct answers"
      ]
    },
    {
      "name": "Supply-chain auditor",
      "text": "Assesses blast radius over ComposedOf and needs every object in a namespace admitted by a principal its capability authorizes.",
      "concerns": [
        "Proved guarantees",
        "Authorized admission"
      ]
    }
  ],
  "concerns": [
    {
      "name": "Authorized admission",
      "text": "No object kappa and no DerivedFrom edge exist for a principal the scope capability does not reach.",
      "model": "security"
    }
  ],
  "components": [
    {
      "name": "kappa-registry",
      "kind": "externalSystem",
      "text": "The pinned upstream registry Emporous imports, whose KappaStore ingests content and resolves edges."
    },
    {
      "name": "KappaStore",
      "kind": "database",
      "text": "The content-addressed store holding objects, representations, scopes and capability edges."
    }
  ],
  "threats": [
    {
      "name": "Unauthorized admission",
      "text": "A principal outside the scope capability admits an object into the namespace.",
      "stride": "elevationOfPrivilege",
      "asset": "request",
      "likelihood": "medium",
      "impact": "critical",
      "control": {
        "name": "Capability-edge walk",
        "text": "Admission is denied unless the walk from the scope authorization reaches the principal.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "EmporousAdmitPolicyProofs::inv001Holds"
          },
          {
            "kind": "gate",
            "reference": "EA-05 features/suites/admission.feature"
          }
        ]
      }
    },
    {
      "name": "Realization chosen in code",
      "text": "The admission path names a realization or axis literal instead of reading it from the scope.",
      "stride": "tampering",
      "asset": "source",
      "likelihood": "low",
      "impact": "major",
      "control": {
        "name": "Read from the scope",
        "text": "The realization and axis are read from the scope and a literal on the admission path fails the gate.",
        "evidence": [
          {
            "kind": "gate",
            "reference": "EA-03 features/suites/admission.feature"
          },
          {
            "kind": "gate",
            "reference": "cargo xtask audit-parametric"
          }
        ]
      }
    },
    {
      "name": "Unknown realization admitted",
      "text": "A scope names a realization the registry does not know and the bytes are admitted unrealized.",
      "stride": "tampering",
      "asset": "answer",
      "likelihood": "low",
      "impact": "major",
      "control": {
        "name": "Not found, not admitted",
        "text": "An unknown realization is indeterminate and never permitted.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "EmporousAdmitPolicyProofs::inv002Holds"
          }
        ]
      }
    }
  ],
  "quality": [
    {
      "characteristic": "Security",
      "subcharacteristic": "Resistance",
      "requirement": "No unauthorized admission",
      "text": "No request from an unauthorized principal is permitted.",
      "measure": "Unauthorized permits",
      "measureText": "Requests with an unauthorized principal that answer permit.",
      "threshold": 0
    },
    {
      "characteristic": "Functional suitability",
      "subcharacteristic": "Functional completeness",
      "requirement": "Every admission condition decided",
      "text": "Each admission condition of SPEC.md 6.3 and the namespace conflict has its own answer.",
      "measure": "Undecided conditions",
      "measureText": "Admission failure conditions no rule decides.",
      "threshold": 0
    }
  ],
  "journeys": [
    {
      "stakeholder": "Publisher",
      "steps": [
        "REQ-001",
        "REQ-003",
        "REQ-005",
        "otherwise"
      ]
    },
    {
      "stakeholder": "Supply-chain auditor",
      "steps": [
        "REQ-002",
        "REQ-004",
        "INV-001",
        "INV-003"
      ]
    }
  ]
}

The prompt as raw JSON · Open it in the builder

It sets these members. Each meaning is quoted from the input schema of prism_prompt.

1. Write the prompt 21 rows
MemberPresenceIn this promptMeaning
goaloptionaltextThe goal the app is built toward, in one sentence a developer would say. It becomes the spec purpose when app.purpose is left out.
patternoptionalpolicyDecisionThe pattern the behavior follows: decisionTable (OMG DMN 1.5, hit policy FIRST, the default), policyDecision (OASIS XACML 3.0: the answers are exactly permit, deny, not-applicable and indeterminate) or stateMachine (OMG UML 2.5.1: the answer is the next state, and machine is required).
repositoryoptionalafflom/emporousowner/name of the repository the app will live in, for its page and links.
apprequiredname, title, purpose, fields, outcomes, meanings, rules, otherwise, otherwiseWhy, properties, examplesThe whole app as a prism/spec/1 spec, the input of prism-code's prism_spec. Its members are below.
app.nameoptionalemporous-admit-policyLower case and hyphens, such as loan-approval.
app.titleoptionalEmporous admission
app.purposerequiredtextWhat the app decides, in one sentence.
app.fieldsrequired4 entriesOne request is these values in order, separated by spaces.
app.outcomesrequired4 entriesLower-case words; invalid is reserved.
app.meaningsoptionalpermit, deny, not-applicable, indeterminateWhat each answer means, such as {"review": "a person must decide"}.
app.rulesrequired5 entriesIn order; the first that matches decides.
app.otherwiserequiredpermitThe answer when no rule matches.
app.otherwiseWhyoptionaltextWhy, in a few words, such as "it enforces INV-001".
app.propertiesoptional4 entriesWhat must never or always happen; each becomes a theorem Lean proves.
app.examplesoptional7 entriesRequests and their expected answers; each becomes an acceptance vector.
stakeholdersoptional2 entriesWho the app is for. A Verifier, anyone who replays the holo before trusting it, is always added.
concernsoptional1 entryWhat the stakeholders care about, each viewed in one model.
componentsoptional2 entriesSystems outside the app that send it requests or read its answers.
threatsoptional3 entriesWhat can go wrong, beyond the threats every app has (an oversized or malformed request, a substituted holo or source, a granted capability, an answer a property rules out).
qualityoptional2 entriesHow good is good enough, as ISO/IEC 25010:2023 requirements with a measure and its threshold.
journeysoptional2 entriesOrdered steps a stakeholder takes. A step is a rule ID (REQ-001), a property ID (INV-001), otherwise or refuse.

2. Check the prompt

In a clone of prism-devrel, run the check on your prompt. It checks the prompt and prints what the app will claim, writing nothing.

git clone https://github.com/afflom/prism-devrel.git && cd prism-devrel
node builder/cli.mjs check examples/emporous-admit-policy.prompt.json

For the Emporous admission prompt it prints this.

Emporous admission: Policy decision (OASIS XACML 3.0 policy decision point), 82 files, 35 acceptance vectors
EA-01: The app never answers permit when principal is unauthorized
EA-02: The app never answers permit when realization is unknown
EA-03: The app always answers deny when namespace is scoped and realization is known and principal is unauthorized
EA-04: The app always answers not-applicable when namespace is unscoped
EA-05: The architecture description declares every stakeholder, concern, component, edge, viewpoint and view it references
EA-06: The ISO/IEC 25010 quality model numbers every characteristic, subcharacteristic, requirement and measure, and every parent it names is declared
EA-07: Every compliance obligation is numbered in order and names its evidence

Exit codes: 0 done, 2 the prompt was refused (the reason is printed), 64 usage.

3. Build it and pass the gate

Save this script as verify.sh in the clone, with PROMPT set to your prompt. It is the pages workflow's own steps for an example.

3. Build it and pass the gate 36 lines
set -euo pipefail
PROMPT=examples/emporous-admit-policy.prompt.json
RUNNER_TEMP=$(mktemp -d)
field() { node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync("frame.lock", "utf8")).source[process.argv[1]])' "$1"; }
instance="$RUNNER_TEMP/instance"
git init -q "$instance"
git -C "$instance" fetch -q --depth 1 "https://github.com/$(field repository)" "$(field commit)"
git -C "$instance" checkout -q --detach FETCH_HEAD
test "$(git -C "$instance" rev-parse HEAD)" = "$(field commit)"
node builder/cli.mjs build "$PROMPT" --out "$instance"
image=$(sed -n 's/.*"sdk_image":"\([^"]*\)".*/\1/p' prismpm.lock)
if [[ ! $image =~ ^[a-z0-9.-]+(:[0-9]{1,5})?/[a-z0-9./_-]+@sha256:[0-9a-f]{64}$ ]]; then
  printf '%s\n' 'prismpm.lock does not select an immutable SDK image' >&2
  exit 64
fi
docker_config=$(mktemp -d)
# The SDK's /tmp is a private directory on the runner's own disk, so the
# build's scratch space is bounded by the disk the runner has, not by a
# fixed size; it is removed with the credentials when the step ends.
scratch=$(mktemp -d)
mkdir -p "$scratch/prismpm-home/.docker"
trap 'rm -rf "$docker_config" "$scratch"' EXIT
printf '{}\n' >"$docker_config/config.json"
docker run --rm \
  --user "$(id -u):$(id -g)" \
  --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  --volume "$scratch:/tmp" \
  --volume "$instance:$instance" \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume "$docker_config:/tmp/prismpm-home/.docker:ro" \
  --workdir "$instance" \
  --env DOCKER_CONFIG=/tmp/prismpm-home/.docker \
  --env BUILDX_CONFIG=/tmp/prismpm-buildx \
  --env HOME=/tmp/prismpm-home \
  --env PRISMPM_EPHEMERAL_HOME=1 \
  "$image" just vv

It calls git, node and docker. Run it, and keep the log.

bash verify.sh 2>&1 | tee verify.log

When it passes, the verified holo is in the instance the script made under RUNNER_TEMP, at "$instance"/app/.prism/build/*/*.holo.

4. Publish it

What the gate proves

The Policy decision obligation of OASIS XACML 3.0 policy decision point names its evidence: EmporousAdmitPolicy::judge, EmporousAdmitPolicy::encodeAnswer.

Each property of the Emporous admission prompt is a theorem the Lean kernel checks for every request.

PropertyStatementTheorem
INV-001It never answers permit when principal is unauthorized.EmporousAdmitPolicyProofs::inv001Holds
INV-002It never answers permit when realization is unknown.EmporousAdmitPolicyProofs::inv002Holds
INV-003It always answers deny when namespace is scoped and realization is known and principal is unauthorized.EmporousAdmitPolicyProofs::inv003Holds
INV-004It always answers not-applicable when namespace is unscoped.EmporousAdmitPolicyProofs::inv004Holds

Every policy decision example

Every policy decision example 6 items
  • Open policy. Decide if Holo Search opens the app an address names. Nothing runs unless its bytes match the address, its model checks and its tests pass.
  • Namespace authorization. Decide if kappa-registry lets someone change a namespace. Only its owner, a key holder or a short chain of trust can write.
  • Axiom policy. Decide if a declaration uses only the axioms its source allows. Then lexlean verify publishes nothing that rests on more.
  • GNAF claim wording. Decide which words a GNAF document may use for a claim. No README or ledger may say more than the Lean kernel checked.
  • Emporous admission. Decide if Emporous lets an object into a namespace. Each object must come from someone who is allowed to add it there.
  • Portal publication. Decide if foundry-web may publish a portal release. Only the exact build that was checked and approved can go live.

Other patterns

how-to guideBuildMarkdown

Words on this page 6
Lean kernel
The small checker at the heart of the Lean prover. It accepts a proof only if every step follows the rules.
theorem
A statement about the model that the Lean kernel has checked, so it holds for every input, not only the ones tested.
holo
The app Prism builds: one signed, verified file that a browser or a device runs.
κ
A content address: a hash of the exact bytes a record was read from, so anyone can check where it came from.
XACML
OASIS eXtensible Access Control Markup Language 3.0: a policy decides permit, deny, not applicable or indeterminate.
prompt
One JSON document that describes an app. The builder turns it into every facet of a Prism model.