# 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`.