Repository navigation
Conversation
Expose provider- and consumer-side processing on ports 5007 and 5008 respectively.
BREAKING CHANGE: removes ACA-Py entirely in an effort to switch VC standards and the entire credential handling system
bzp99
changed the title
bzp99
self-requested a review
September 14, 2026 21:21
bzp99
force-pushed
the
docs/dva-failure-model
branch
from
September 14, 2026 21:24
bcdad94 to
1953753
Compare
bzp99
requested changes
Sep 14, 2026
Comment on lines
+25
to
+83
| ```text | ||
| DVA outcome | ||
| ├── Expected negative outcome | ||
| │ └── DATA_REQUIREMENT_NOT_MET | ||
| ├── Evaluation faults | ||
| │ ├── Execution faults | ||
| │ │ ├── EVALUATION_OPERATIONAL_FAULT | ||
| │ │ └── EVALUATION_TRANSIENT_FAULT | ||
| │ └── Requirement-definition faults | ||
| │ ├── EVALUATION_LOGIC_SYNTAX_INVALID | ||
| │ ├── EVALUATION_LOGIC_INCORRECT | ||
| │ └── REQUIREMENT_MISUNDERSTOOD | ||
| ├── AoV issuance faults | ||
| │ └── AOV_ISSUANCE_OPERATIONAL_FAULT | ||
| └── AoV verification faults | ||
| ├── Structural | ||
| │ └── AOV_MALFORMED | ||
| ├── Cryptographic | ||
| │ ├── AOV_SIGNATURE_INVALID | ||
| │ └── SIGNATURE_VERIFICATION_FAILED | ||
| ├── Commitment | ||
| │ ├── DATA_COMMITMENT_MISMATCH | ||
| │ └── VLA_COMMITMENT_MISMATCH | ||
| └── Trust limitation | ||
| └── AOV_CLAIMS_FORGED | ||
| ``` | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| DVA[DVA outcome] | ||
| DVA --> NEG[Expected negative outcome] | ||
| NEG --> DATA[Data does not fulfil requirement] | ||
|
|
||
| DVA --> EVAL[Evaluation faults] | ||
| EVAL --> EXEC[Execution faults] | ||
| EXEC --> OP[Operational or environmental fault] | ||
| EXEC --> TRANSIENT[Transient or probabilistic fault] | ||
| EVAL --> DEF[Requirement definition faults] | ||
| DEF --> SYNTAX[Invalid evaluation syntax] | ||
| DEF --> LOGIC[Incorrect implementation logic] | ||
| DEF --> MEANING[Misunderstood requirement] | ||
|
|
||
| DVA --> ISSUE[AoV issuance faults] | ||
| ISSUE --> ISSUEOP[Operational issuance fault] | ||
|
|
||
| DVA --> VERIFY[AoV verification faults] | ||
| VERIFY --> STRUCT[Structural faults] | ||
| STRUCT --> MALFORMED[Malformed AoV] | ||
| VERIFY --> CRYPTO[Cryptographic faults] | ||
| CRYPTO --> INVALIDSIG[Invalid signature] | ||
| INVALIDSIG -. observed during verification .-> SIGCHECK[Signature verification failed] | ||
| VERIFY --> COMMIT[Commitment faults] | ||
| COMMIT --> DATAHASH[Data commitment mismatch] | ||
| COMMIT --> VLAHASH[VLA version mismatch] | ||
| VERIFY --> TRUST[Trust limitation] | ||
| TRUST --> FORGED[Forged evaluation claims] | ||
|
|
||
| SYNTAX -. may become an execution fault if not caught earlier .-> OP | ||
| ``` |
Collaborator
There was a problem hiding this comment.
Instead of this, I strongly suggest sketching up one or more fault tree(s) as I expect that to help more with communication than a custom representation.
At the top, we have the undesired outcome event like Attestation cannot be generated and we can drill down to the potential causes; eg, there was an error during the AoV VC issuance OR there was some error during the evaluation of some requirement OR there was an error while retrieveing the associated VLA. Most of these intermediate events can be further broken down: for instance, what could cause an error while retrieving the VLA? Perhaps it was that the VLA manager was not reachable. Or that it was reachable but returned a 404 for the sought VLA. And so on.
| SYNTAX -. may become an execution fault if not caught earlier .-> OP | ||
| ``` | ||
|
|
||
| ## Failure Catalog |
Collaborator
There was a problem hiding this comment.
This catalogue is very useful and I think all of the identifiers here should be present in the fault tree(s). Then this can be a more detailed explanation of those events along with annotations on how they can be detected and what feedback can be given where, etc.
Comment on lines
+234
to
+250
| ## Feedback Matrix | ||
|
|
||
| | Failure | Primary interface | Recipient | Recommended response | | ||
| |---|---|---|---| | ||
| | `DATA_REQUIREMENT_NOT_MET` | Provider dashboard | Provider | Correct the data or review the requirement. | | ||
| | `EVALUATION_OPERATIONAL_FAULT` | Dashboard and logs | Operator | Restore the evaluator and retry. | | ||
| | `EVALUATION_TRANSIENT_FAULT` | Evaluation details | Provider, operator | Repeat under controlled conditions and compare attempts. | | ||
| | `EVALUATION_LOGIC_SYNTAX_INVALID` | VLA Manager | VLA author | Block the requirement and correct the implementation. | | ||
| | `EVALUATION_LOGIC_INCORRECT` | VLA Manager tests | VLA author | Review rendered logic and known examples. | | ||
| | `REQUIREMENT_MISUNDERSTOOD` | VLA review | VLA author, participants | Review business meaning and representative examples. | | ||
| | `AOV_ISSUANCE_OPERATIONAL_FAULT` | Provider dashboard and logs | Operator | Restore signing or persistence and issue again safely. | | ||
| | `AOV_MALFORMED` | Consumer dashboard | Consumer | Reject and request a replacement. | | ||
| | `AOV_SIGNATURE_INVALID` | Consumer dashboard | Consumer, operator | Reject and investigate issuer, key, or corruption. | | ||
| | `SIGNATURE_VERIFICATION_FAILED` | Verification history | Consumer, operator | Reject and inspect the specific cryptographic reason. | | ||
| | `DATA_COMMITMENT_MISMATCH` | Consumer dashboard | Consumer, operator | Reject and investigate exchanged data or routing. | | ||
| | `VLA_COMMITMENT_MISMATCH` | Consumer dashboard | Consumer, operator | Reject and retrieve the referenced VLA version. | | ||
| | `AOV_CLAIMS_FORGED` | Optional re-evaluation | Consumer, security operator | Investigate the signer and disputed claims. | |
Collaborator
There was a problem hiding this comment.
I don't see the purpose of this if it can be derived from the data catalogue above.
Comment on lines
+286
to
+312
| ## Proposed Feedback Record | ||
|
|
||
| Components need the same structured information even when they present it differently. The following shape is a proposed contract for implementation work. It is not a claim that every field is already returned by the APIs. | ||
|
|
||
| ```json | ||
| { | ||
| "code": "DATA_COMMITMENT_MISMATCH", | ||
| "outcome": "ERROR", | ||
| "stage": "AOV_VERIFICATION", | ||
| "category": "COMMITMENT_FAULT", | ||
| "parentCode": "AOV_VERIFICATION_FAULT", | ||
| "message": "The attestation refers to different data.", | ||
| "evidence": { | ||
| "algorithm": "sha-256", | ||
| "expected": "...", | ||
| "actual": "..." | ||
| }, | ||
| "detectability": "AUTOMATIC", | ||
| "recipients": ["DATA_CONSUMER", "OPERATOR"], | ||
| "retryable": false, | ||
| "suggestedAction": "Reject the attestation and investigate the exchanged data." | ||
| } | ||
| ``` | ||
|
|
||
| `code`, `outcome`, `stage`, and `category` are stable machine-readable values. `message` and `suggestedAction` are user-facing text. `evidence` contains safe structured details returned by the component that detected the problem. It must not expose private keys, credentials, raw secrets, or unnecessary personal data. | ||
|
|
||
| The backend should provide the most specific code it can justify. If it cannot identify the cause, it should return an explicit unknown code for the stage rather than asking the frontend to infer a cause from exception text. |
Collaborator
There was a problem hiding this comment.
As we discussed in our meeting, I don’t think there should be any specialized feedback record. The individual modules all have their own mechanisms of reporting errors: APIs return error responses, frontends show error messages, etc. We do not have to have a unified error feedback format across the whole of DVA.
Comment on lines
+314
to
+323
| ## Relationships Between Failures | ||
|
|
||
| | Source | Relationship | Target | Meaning | | ||
| |---|---|---|---| | ||
| | `EVALUATION_TRANSIENT_FAULT` | specialization of | `EVALUATION_OPERATIONAL_FAULT` | It is an evaluation execution fault whose result may change across controlled attempts. | | ||
| | `EVALUATION_LOGIC_SYNTAX_INVALID` | may cause | `EVALUATION_OPERATIONAL_FAULT` | Invalid logic becomes a runtime execution fault if VLA creation fails to block it. | | ||
| | `SIGNATURE_VERIFICATION_FAILED` | observes | `AOV_SIGNATURE_INVALID` | The verification event exposes the underlying cryptographic problem. | | ||
| | `DATA_COMMITMENT_MISMATCH` | invalidates use of | AoV for received data | A valid signature cannot make the credential applicable to different data. | | ||
| | `VLA_COMMITMENT_MISMATCH` | invalidates use of | AoV for referenced agreement | The credential cannot prove requirements from another VLA version. | | ||
| | Optional consumer re-evaluation | may reveal | `AOV_CLAIMS_FORGED` | Re-evaluation can expose a disagreement but is not part of normal signature verification. | |
Collaborator
There was a problem hiding this comment.
Frankly, I think fault trees should obsolete these relationships.
The RMQ integration was removed in 4aedc8a, but the compose stack still started three RabbitMQ brokers, passed DVA_RABBITMQ_HOST to services that no longer read it, and handed dva-processing a --no-rmq flag its CLI no longer defines. The stack also never started the VLA Manager API or the VC Manager, so the gateway's vlaManager.url and vcManager.url fell back to localhost:8000 and resolved to nothing inside the container. Both now run, each with its own postgres, and every DVA API is pointed at them. Requirement validation calls DVA Processing from the VLA Manager API, so it is given a processing URL as well. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Whitespace only; `git diff -w` against the parent is empty. Re-applied rather than cherry-picked from the original a595f9f, whose file contents predate the requirement validation added in 481bd90, 674098e and 9e28426 and would have reverted it. The file list is recomputed instead of reused: ReqModal.vue has since been cleaned, and FileSelector.vue and mocks/handlers.js have since acquired trailing whitespace. The original used the type "style", which this repo's type-enum does not allow. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Attestation requests have gone straight to the gateway since 4aedc8a, so nothing is queued. The mock's error text is corrected alongside the banner; the original branch only touched the banner. The dashboard's QUEUE_FAILURE code is deliberately left alone: it is part of the documented failure vocabulary in docs/attestation-verification-failures.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bzp99
added this pull request to stack #93
September 17, 2026 23:08
bzp99
force-pushed
the
docs/dva-failure-model
branch
from
September 20, 2026 21:02
1953753 to
de01a37
Compare
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| def render_template(implementation_template: str, model: dict[str, Any]) -> str: | ||
| """Render a Handlebars ``{{var}}`` template string with a model dict.""" | ||
| try: | ||
| return chevron.render(implementation_template, model) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This documents the failure modes identified across evaluation, AoV issuance, and verification.
It defines stable identifiers, detection points, feedback locations, responsible parties, recovery actions, relationships, and known trust limitations. It also records proposed answers to the open design questions and includes a visual hierarchy.
No runtime behavior is changed.
Review focus
CC @bzp99