v0.2

docs/04-uapf-ip-integration.md

@@ -0,0 +1,50 @@
+# 04 — UAPF-IP Integration
+
+How a UAPF-IP (Integration Profile) host runs this package.
+
+## Profiles
+
+The manifest declares `uapf-ip-orchestrated` and `uapf-ip-sync-decision`:
+
+- **orchestrated** — the host executes the BPMN process, calling host
+  capabilities (`task.assign`, `task.complete`, `task.escalate`, `event.emit`,
+  `timer.schedule`) and evaluating DMN decisions at each business-rule task.
+- **sync-decision** — any of the six decisions can be evaluated standalone, as
+  a synchronous request/response, without running the process.
+
+## Exposed entrypoints
+
+`exposure.mcp.exposedEntrypoints` maps the process and each decision to an MCP
+tool name, e.g. `interception_authorization.evaluate`. A UAPF-IP host with MCP
+exposure enabled publishes these as callable tools. `runnable: true` permits
+process execution, not only inspection.
+
+## Required capabilities
+
+`requires_capabilities` lists what the host must provide. Beyond the generic
+task/event capabilities, this package needs:
+
+- `timer.schedule@1+` — to arm the SLA-breach boundary timer.
+- `ai.classify@1+`, `ai.complete@1+` — for the advisory threat-assessment agent.
+- `lv.gov.civdef.air_surveillance_feed@1+`, `lv.gov.civdef.cell_broadcast@1+` —
+  domain capabilities that wrap the NBS surveillance feed and the VUGD
+  cell-broadcast platform.
+
+A host missing a required capability must refuse to load the package rather
+than degrade silently.
+
+## Guardrail enforcement
+
+Every capability call is checked against `resources/guardrails.yaml` before and
+after execution. The load-bearing guardrails: AI is advisory only (GR-1), no
+autonomous use of force (GR-2), the SLA boundary timer may not be disabled
+(GR-3), and public messaging is human-authored from templates (GR-4). A
+violation **blocks** the call and is written to the audit trail.
+
+## Decision/process boundary
+
+The host owns orchestration, capability brokering, audit and guardrail
+enforcement. The package owns **only** the logic — process shape, decision
+tables, case structure and resource bindings. The package contains no
+credentials; the placeholders in `resources/mappings.yaml` are resolved by the
+host from its own secret store.