Document failure model

.dockerignore

@@ -0,0 +1,25 @@
+# Docker reads .dockerignore from the build-context root only. The service
+# Dockerfiles reference ./<service>/... paths, so the context is this
+# directory and per-service .dockerignore files have no effect.
+
+# Generic
+.git/
+**/.gitignore
+**/Dockerfile
+
+# JVM projects
+**/.gradle/
+**/.idea/
+**/.kotlin/
+**/build/
+
+
+# Python projects
+**/.venv/
+**/__pycache__/
+**/*.pyc
+**/.pytest_cache/
+**/*.egg-info/
+
+# Node projects
+**/node_modules/

.github/workflows/build-dva-dashboard.yml

@@ -8,6 +8,7 @@ on:
       - dva-dashboard/**/*.js
       - dva-dashboard/**/*.html
       - dva-dashboard/src/**
+      - dva-dashboard/test/**
       - dva-dashboard/package.json
       - dva-dashboard/pnpm-lock.yaml
       - dva-dashboard/public/**
@@ -17,6 +18,7 @@ on:
       - dva-dashboard/**/*.js
       - dva-dashboard/**/*.html
       - dva-dashboard/src/**
+      - dva-dashboard/test/**
       - dva-dashboard/package.json
       - dva-dashboard/pnpm-lock.yaml
       - dva-dashboard/public/**
@@ -53,5 +55,7 @@ jobs:
           cache-dependency-path: dva-dashboard/pnpm-lock.yaml
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
+      - name: Run tests
+        run: pnpm run test
       - name: Build project
         run: pnpm run build

.github/workflows/build-dva-processing.yml

@@ -46,6 +46,10 @@ jobs:
           working-directory: ./dva-processing
       - name: Install dependencies
         run: uv sync --locked
+      - name: Check formatting
+        run: uv run --no-sync ruff format --check src tests
+      - name: Lint
+        run: uv run --no-sync ruff check src tests
       - name: Run Pytest
         run: uv run --no-sync pytest --junitxml=junit.xml
       - name: Upload test artefacts

.github/workflows/build-vla-manager-api.yml

@@ -0,0 +1,60 @@
+---
+name: Build and Test VLA Manager API
+
+
+on:
+  push:
+    paths:
+      - vla-manager-api/src/**
+      - vla-manager-api/tests/**
+      - vla-manager-api/pyproject.toml
+      - vla-manager-api/uv.lock
+      - .github/workflows/build-vla-manager-api.yml
+  pull_request:
+    paths:
+      - vla-manager-api/src/**
+      - vla-manager-api/tests/**
+      - vla-manager-api/pyproject.toml
+      - vla-manager-api/uv.lock
+      - .github/workflows/build-vla-manager-api.yml
+
+
+permissions:
+  contents: read
+
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+
+defaults:
+  run:
+    working-directory: ./vla-manager-api
+
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          working-directory: ./vla-manager-api
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Check formatting
+        run: uv run --no-sync ruff format --check src tests
+      - name: Lint
+        run: uv run --no-sync ruff check src tests
+      - name: Run Pytest
+        run: uv run --no-sync pytest --junitxml=junit.xml
+      - name: Upload test artefacts
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: pytest-results
+          path: vla-manager-api/junit.xml

.github/workflows/build-vla-manager.yml

@@ -8,6 +8,7 @@ on:
       - vla-manager/**/*.js
       - vla-manager/**/*.html
       - vla-manager/src/**
+      - vla-manager/test/**
       - vla-manager/package.json
       - vla-manager/pnpm-lock.yaml
       - vla-manager/public/**
@@ -17,6 +18,7 @@ on:
       - vla-manager/**/*.js
       - vla-manager/**/*.html
       - vla-manager/src/**
+      - vla-manager/test/**
       - vla-manager/package.json
       - vla-manager/pnpm-lock.yaml
       - vla-manager/public/**
@@ -53,5 +55,7 @@ jobs:
           cache-dependency-path: vla-manager/pnpm-lock.yaml
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
+      - name: Run tests
+        run: pnpm run test
       - name: Build project
         run: pnpm run build

.gitignore

@@ -1,2 +1,6 @@
 # commitlint
 node_modules/
+__pycache__/
+*.pyc
+.DS_Store
+*.egg-info/

README.md

@@ -13,8 +13,6 @@ At the moment, DVA has several subcomponents:
 * **API server** in [`dva-api/`](dva-api/) – gateway / entry point / connector integration
 * **Processing** in [`dva-processing/`](dva-processing/) – evaluates veracity requirements
 * **RabbitMQ** from [`rabbitmq`](https://hub.docker.com/_/rabbitmq) – message queue facilitating communication between the API server and the processing module
-* **ACA-Py Controller** in [`dva-acapy-controller/`](dva-acapy-controller/) – contains SSI/VC-related logic
-* **ACA-Py Agent** from [`ghcr.io/hyperledger/aries-cloudagent-python`](https://github.com/orgs/hyperledger/packages/container/package/aries-cloudagent-python) – an SSI cloud agent (~ wallet)
 * **PostgreSQL** from [`postgres`](https://hub.docker.com/_/postgres) – stores application state, events, and _logs_
 * **Dashboard** in [`dva-dashboard/`](dva-dashboard/) – frontend application that displays database contents on a dashboard interface
 * **VLA Manager** in [`vla-manager`](vla-manager/) – frontend application for VLAs management (creation, display, etc)
@@ -28,15 +26,13 @@ You can use the following commands to build / pull the images (from the reposito
 docker buildx build -t dva-api:latest -f dva-api/Dockerfile ./
 docker buildx build -t dva-processing:latest -f dva-processing/Dockerfile ./
 docker pull rabbitmq:4-management-alpine
-docker buildx build -t dva-aca-py-controller:latest -f dva-acapy-controller/Dockerfile ./
-docker pull ghcr.io/hyperledger/aries-cloudagent-python:py3.9-0.12.6
 docker pull postgres:17-alpine
 docker buildx build -t dva-dashboard:latest ./dva-dashboard/
 docker buildx build -t vla-manager:latest ./vla-manager/
 ```
 
 > [!NOTE]
-> Check the currently used RabbitMQ, PostgreSQL, and ACA-Py versions in [`test-env/common-services.yml`](test-env/common-services.yml).
+> Check the currently used RabbitMQ and PostgreSQL versions in [`test-env/common-services.yml`](test-env/common-services.yml).
 
 You normally do not have to do this however as you should be using Docker Compose to set up your DVA instance (see the [_test environment_](test-env/)).
 
@@ -88,7 +84,7 @@ Example requests to test functionality manually (non-exhaustive):
 | `/vla/from-templates`   | `POST`      | *nothing*                                                           | a [VLA request using templates](test-env/test-data/vla-request/request-from-templates.json)                                                                                     | `201 CREATED` and [an ID](test-env/example-outputs/id.json)                                                                                                             |
 | `/vla/{id}`             | `GET`       | `id`: a VLA ID (eg `570b22e0-2e90-4e02-8c7b-1d6d274629f3`)          | *empty*                                                                                                                                                                         | `200 OK` and the VLA template ([example](test-env/example-outputs/vla-id-get.json))                                                                                     |
 | `/attestation`          | `POST`      | *nothing*                                                           | an [AoV request](test-env/test-data/aov/timestamp-in-range/request-good.json)                                                                                                   | `200 OK` and [an ID](test-env/example-outputs/id.json)                                                                                                                  |
-| `/attestation/verify`   | `POST`      | *nothing*                                                           | an [AoV verification request](test-env/test-data/aov/verif-req.json)                                                                                                            | `200 OK` and an AoV JSON object from ACA-Py                                                                                                                            |
+| `/attestation/verify`   | `POST`      | *nothing*                                                           | an [AoV verification request](test-env/test-data/aov/verif-req.json)                                                                                                            | `200 OK` and an AoV JSON object                                                                                                                            |
 
 > [!NOTE]
 > AoV requests (`POST /attestation`) are processed asynchronously.
@@ -172,44 +168,6 @@ In the test output, you should see all PyTest tests passing.
   ```
 </details>
 
-### DVA ACA-Py Controller Module ([`dva-acapy-controller`](dva-acapy-controller/))
-
-> [!NOTE]
-> A nice way to run the tests from the repository root using Docker without having to touch your local environment:
-> ```console
-> docker run --rm -it -v ./dva-acapy-controller:/app ghcr.io/astral-sh/uv:debian-slim uv --directory /app/ run pytest
-> ```
-
-#### Setup test environment
-
-Find a way to run [uv](https://docs.astral.sh/uv) → [installation instructions](https://docs.astral.sh/uv/getting-started/installation/)
-
-#### Run tests
-
-Set your working directory to `dva-acapy-controller/` and execute:
-```console
-uv run pytest
-```
-
-#### Expected results
-
-In the test output, you should see all PyTest tests passing.
-
-<details>
-  <summary>Example output segment (click to open)</summary>
-
-  ```
-  ============================================================ test session starts ============================================================
-  platform linux -- Python 3.12.8, pytest-8.4.1, pluggy-1.6.0
-  rootdir: /projects/uni/edge/data-veracity/dva-processing
-  configfile: pyproject.toml
-  plugins: anyio-4.9.0
-  collected 3 items
-
-  tests/test_controller.py ..                                                                                                           [100%]
-  ```
-</details>
-
 
 ## Component-level testing
 

docs/attestation-verification-failures.md

@@ -0,0 +1,156 @@
+# Attestation and verification failures
+
+This is the short reference for incomplete attestations, failed evaluations, and
+verification results that need attention.
+The dashboard shows the same code and next action on the record card, table, and overview.
+
+## How to read a record
+
+* **Passed** means the evaluation or verification finished successfully.
+* **Pending** means the operation was accepted but has no final result yet.
+* **Failed** means a check finished and did not pass.
+* **Needs correction** means the request is missing valid input.
+* **Unavailable** means the selected service or template could not be reached.
+* **Error** means the service could not complete or save the operation.
+
+Every incomplete record should contain:
+
+* `code` – stable failure identifier
+* `title` – short explanation for the user
+* `summary` – what the result means
+* `evidence` – returned error, failed check, or missing field
+* `next action` – the most useful correction or retry step
+* `retryable` – whether trying again can reasonably help
+
+## Attestation and evaluation failures
+
+### `EVALUATION_PENDING`
+
+The request was accepted, but the processor has not written a result.
+Check the request again after processing.
+Retrying immediately can create a duplicate request.
+
+### `SCHEMA_VALIDATION_FAILED`
+
+The data does not match the selected schema.
+A required field can be absent, or a value can have the wrong type or format.
+Compare the payload with the schema, correct it, then submit again.
+
+### `JQ_CHECK_FAILED`
+
+The JQ expression returned a failed result.
+The referenced property may be missing, empty, or outside the condition in the expression.
+Inspect the expression and the values used by it before retrying.
+
+### `GREAT_EXPECTATIONS_FAILED`
+
+The tabular expectation did not pass.
+Common causes are null values, a bad column name, an invalid type, or a value outside the configured expectation.
+Review the expectation details and the mapping from the payload to columns.
+
+### `TEMPLATE_RENDER_FAILED`
+
+The template could not be turned into an implementation.
+A variable may be missing, incorrectly named, or incompatible with the template.
+Check the template variables and render the requirement again.
+
+### `INVALID_TEMPLATE_INPUT`
+
+The template model is incomplete or has a wrong value type.
+This is an input error, not a failure in the evaluation engine.
+Fill in each required variable using the type shown by the template.
+
+### `UNKNOWN_TEMPLATE`
+
+The selected template is not available in the current gateway.
+It may have been deleted, belong to another environment, or have become unavailable.
+Refresh the template list and choose an available template.
+
+### `MISSING_REQUIRED_DATA`
+
+The request does not contain all data required by the contract.
+Add the missing field or select a contract that matches the data being sent.
+
+### `FRESHNESS_FAILED`
+
+The timestamp is older or newer than the allowed freshness window.
+Send a current observation or review the freshness rule in the contract.
+
+### `RANGE_FAILED`
+
+A measured value is below the minimum or above the maximum allowed value.
+Correct the value or review the configured range before submitting again.
+
+### `GATEWAY_UNAVAILABLE`
+
+The dashboard could not reach the DVA gateway.
+No conclusion about the data should be drawn from this result.
+Check gateway health and try again when the service is available.
+
+### `PROCESSING_TIMEOUT`
+
+The evaluation did not return within the expected time.
+The final state may be unknown, so keep the request ID when contacting support.
+Retry after checking processor health.
+Avoid repeated retries while the first operation may still be running.
+
+### `QUEUE_FAILURE`
+
+The gateway accepted the request but could not hand it to the processing service or message transport.
+Retry when the gateway and transport are healthy.
+
+### `PERSISTENCE_FAILURE`
+
+The evaluation completed, but its result could not be written to storage.
+Do not assume the result was recorded.
+Retry once the storage service is healthy and keep the request ID.
+
+### `UNKNOWN_FAILURE`
+
+The service returned an error without a more specific reason.
+Read the evidence, check gateway health, and retry only when the input is known to be valid.
+
+## Verification failures
+
+### `VERIFICATION_PENDING`
+
+The presentation exchange started but no final verification result exists.
+Wait for the exchange to finish and refresh the record.
+Do not treat pending as verified.
+
+### `VERIFICATION_REJECTED`
+
+The verifier received the presentation but could not accept its claims.
+The requested attribute may be absent, incorrect, expired, or not trusted.
+Compare the requested attributes with the presentation and request a current credential when needed.
+
+### `CREDENTIAL_REVOKED`
+
+The credential was found, but its issuer no longer considers it valid.
+Do not use it for a new verification.
+Request a replacement credential.
+
+## Common check order
+
+1. Confirm that the request reached the gateway.
+2. Confirm that the selected template and variables are available.
+3. Confirm that required data and timestamps are present.
+4. Read the engine evidence for the failed field or expectation.
+5. Correct the data or contract rule before retrying.
+6. For transport, timeout, or storage errors, check service health first.
+7. For verification rejection, inspect the credential status and claims.
+
+## Example evaluation result
+
+```json
+{
+  "engine": "SCHEMA",
+  "timestamp": "2026-08-23T10:15:00Z",
+  "success": false,
+  "details": "required field customer_id is missing",
+  "error": null
+}
+```
+
+The dashboard maps this to `SCHEMA_VALIDATION_FAILED`, keeps the engine detail as evidence,
+and tells the user to add `customer_id` before submitting again.