# GovOPlaN Forms Runtime

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

`govoplan-forms-runtime` owns definition-aware runtime form submissions,
including validation, permitted drafts, attachment/signature references, status
history, receipts, and handoff evidence.

Its runtime module ID is `forms_runtime`; the repository and Python distribution retain the hyphenated `govoplan-forms-runtime` name.

The module persists tenant-bound immutable revisions and events, exposes bounded
owner/manager APIs and WebUI routes, and provides both
`forms_runtime.registry` and `forms_runtime.service_launcher`.

Portal invokes the launcher only after re-fetching and re-evaluating an exact
published Service revision. A Form binding uses `<form-id>/<revision>`; the
runtime resolves that exact immutable definition through `forms.definitions`,
validates launch values, and retains both Service and binding provenance.

## Ownership

- form submissions
- draft state
- runtime validation results
- attachment references
- signature state
- handoff status

Submitted instances can create a native Case or start a Workflow through the
owning module capability. Runtime persists the exact handoff intent before the
external action, commits that intent, uses a stable provider idempotency key,
and stores `succeeded`, `rejected`, or `outcome_unknown` evidence. Unknown
outcomes are reconciled against the owner rather than retried as a new action.

## Boundaries

This module does not own:

- form definition authoring
- document storage
- domain-specific adjudication

Detailed boundary notes are in [docs/FORMS_RUNTIME_DOMAIN_BOUNDARY.md](docs/FORMS_RUNTIME_DOMAIN_BOUNDARY.md).

## Integrations

Required integrations:

- access
- forms

Optional integrations:

- files
- approvals
- workflow engine
- portal
- cases
- policy
- audit

## Development Install

From the core checkout:

```bash
cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m pip install -e ../govoplan-forms-runtime
```

Focused verification:

```bash
cd /mnt/DATA/git/govoplan-forms-runtime
PYTHONPATH=src:/mnt/DATA/git/govoplan-forms/src:/mnt/DATA/git/govoplan-core/src \
  /mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
```

## Gitea Workflow

Issue templates are installed under `.gitea/`, and the shared label taxonomy is copied to `docs/gitea-labels.json` with the module label `module/forms-runtime`.

From the core checkout, labels can be synced once a local `GITEA_TOKEN` is available:

```bash
cd /mnt/DATA/git/govoplan-core
/mnt/DATA/git/govoplan/tools/gitea/gitea-sync-labels.py --root /mnt/DATA/git/govoplan-forms-runtime --apply
```