Import UAPF package: lv-civdef-drone-threat-public-address (1).uapf

docs/03-uapf-ip-integration.md

@@ -0,0 +1,114 @@
+# 03 — UAPF-IP Integration
+
+> Non-normative supporting document. Explains how this package binds to a
+> UAPF-IP host/runtime and to an MCP surface. The normative integration
+> contract lives in the manifest (`uapf.yaml`) and `resources/guardrails.yaml`.
+> Reference: UAPF-IP `SPEC.md` v0.1 and `specification/06-mcp-integration.md`.
+
+## 1. How this package plugs into a runtime
+
+UAPF-IP separates the **runtime** (loads this package, orchestrates the flow)
+from the **host** (provides the capabilities the flow needs). At session start
+the runtime reads `requires_capabilities` from the manifest and verifies the
+host can fulfil every one; if not, the session is refused.
+
+### Capabilities this package requires
+
+Declared in `uapf.yaml` under `requires_capabilities`:
+
+| Capability | Namespace | Used for |
+|---|---|---|
+| `task.assign@1+` | reserved | Assigning field-response and case work items |
+| `task.complete@1+` | reserved | Closing assigned work items |
+| `task.escalate@1+` | reserved | Escalating the broadcast request (GAP G2 fallback) |
+| `event.emit@1+` | reserved | Emitting incident domain events for audit |
+| `ai.classify@1+` | reserved | Air-threat severity recommendation; disinfo classification |
+| `ai.complete@1+` | reserved | Origin-attribution analysis assistance |
+| `lv.gov.civdef.air_surveillance_feed@1+` | user-defined | Reading the radar/track feed |
+| `lv.gov.civdef.cell_broadcast@1+` | user-defined | Triggering the public cell broadcast |
+
+`task.*`, `event.*` and `ai.*` are reserved UAPF-IP v0.1 namespaces. The two
+`lv.gov.civdef.*` capabilities are **user-defined** (reverse-DNS root, per the
+UAPF-IP namespace rules) because no reserved namespace covers a national
+cell-broadcast or a military surveillance feed. A host that operates the VUGD
+cell-broadcast platform would publish the `lv.gov.civdef.cell_broadcast` schema
+alongside it. (`notify.*` is reserved for UAPF-IP v0.2 but not yet specified, so
+the cell broadcast cannot use it today.)
+
+### Profiles
+
+`profiles_supported` declares two UAPF-IP v0.1 profiles:
+
+- **`uapf-ip-orchestrated`** — the BPMN flow with human tasks, parallel
+  branches and the field-response case is an orchestrated process.
+- **`uapf-ip-sync-decision`** — each DMN decision (`Decision_AirThreatSeverity`,
+  `Decision_CellBroadcastScope`, `Decision_InterceptionAuthorization`) can be
+  evaluated synchronously in a single round-trip, independent of the flow.
+
+## 2. Guardrails
+
+`resources/guardrails.yaml` is the policy snapshot the runtime attaches to every
+session (immutable for the session lifetime, UAPF-IP SPEC §6/§10). It is
+referenced from the manifest via `guardrails: resources/guardrails.yaml`.
+
+Key constraints, and why:
+
+- `max_confidence_for_autocomplete: 0.0` — the AI may **never** autonomously
+  complete a step. In a national public-warning process every AI output is a
+  recommendation a human confirms. This is reinforced by
+  `metadata/policies.yaml` (`delegation.allowAgentDelegation: false`).
+- `human_oversight.required_for` — cell-broadcast dispatch, interception
+  authorization, public communication and incident closure all require a human
+  (the NBS Joint Staff duty officer).
+- `ai.forbidden_inputs` — classified radar tracks, residents' personal data and
+  source-identifying OSINT must never reach a model; `pii_redactor: required`.
+- `audit.vc_signature_per_step: required`, `retention_years: 10` — every step
+  emits a DID-VC-signed CloudEvents record (UAPF-IP SPEC §7).
+
+## 3. MCP endpoint
+
+Per `specification/06-mcp-integration.md`, a UAPF package is exportable to an
+MCP surface in **Package → MCP** mode. This package declares its MCP exposure in
+the manifest under `exposure.mcp`:
+
+```yaml
+exposure:
+  mcp:
+    enabled: true
+    runnable: true
+    exposedEntrypoints:
+      - { process: Process_DroneThreatPublicAddress, tool: drone_threat_public_address.run }
+      - { decision: Decision_AirThreatSeverity,       tool: air_threat_severity.evaluate }
+      - { decision: Decision_CellBroadcastScope,      tool: cell_broadcast_scope.evaluate }
+      - { decision: Decision_InterceptionAuthorization, tool: interception_authorization.evaluate }
+    exposedArtifacts: [manifest, bpmn, dmn, cmmn, docs]
+```
+
+A conforming UAPF→MCP implementation importing this `.uapf` package MUST expose
+the standard tool set — `uapf.describe`, `uapf.list`, `uapf.run_process`,
+`uapf.evaluate_decision`, `uapf.resolve_resources`, `uapf.get_artifact`,
+`uapf.validate` — and the standard resources `uapf://manifest/...`,
+`uapf://bpmn/...`, `uapf://dmn/...`, `uapf://cmmn/...`, `uapf://policies/...`,
+`uapf://bindings/...`.
+
+The four `exposedEntrypoints` become directly runnable/evaluable tools:
+`uapf.run_process` against `Process_DroneThreatPublicAddress`, and
+`uapf.evaluate_decision` against each of the three decisions.
+
+### MCP-reachable resource targets
+
+Two binding targets in `resources/mappings.yaml` are themselves reached over
+MCP, so the process composes with other MCP services:
+
+- `agent.threat-assessment` — `type: ai_agent`, `endpoint: mcp://agents/civdef-threat-assessment`
+- `mcp.osint-monitor` — `type: mcp_tool`, `endpoint: mcp://lv-civdef/osint-monitor`
+
+All endpoints and `configRef` credential references in the mapping are
+illustrative placeholders for this draft and must be set to real values before
+any non-development use.
+
+## 4. Status
+
+The integration surface is declared but not deployed. `metadata/policies.yaml`
+restricts `allowedEnvironments` to development and staging, and lifecycle status
+is `draft`.