Developer Manual
Troubleshooting
Diagnose common integration failures without unsafe retries.
| Symptom | Inspect | Safe next action | Do not do |
|---|---|---|---|
| Proposal rejected | Input bounds, proposal shape, host validation | Correct the proposal or request clarification | Dispatch an unvalidated proposal |
| Grounding ambiguous | Candidate set, source revision, tenant scope | Refresh authoritative candidates and clarify | Choose the first candidate |
| Authorization denied | Requester, subject, policy revision, decision provenance | Apply host policy or explain denial | Reuse a stale permit |
| Dispatch not attempted | Preparation and admission result | Correct configuration or context | Report provider failure |
| Provider acknowledged but not committed | Verifier observation and finality | Perform the independent read | Tell the user it succeeded |
| Verifier indeterminate | Read availability, freshness, contradictions | Preserve UNKNOWN; use permitted reconciliation | Convert uncertainty to failure or success |
UNKNOWN | Attempt identity, dispatch boundary, verifier evidence | Reconcile the original effect if eligible | Redispatch blindly |
| Reconciliation unavailable | Runtime handle, process lifetime, durable host record | Escalate with preserved evidence | Reconstruct a private handle |
| Tenant mismatch | Host identity and provider/verifier scope | Fail closed and investigate scope binding | Trust transport-supplied tenant fields |
| Process loss | Durable record and attempt identity | Follow host recovery policy | Assume exactly-once execution |
| Duplicate attempt | Admission key, operation/effect identity, provider idempotency | Stop new dispatch and investigate | Retry because the response was lost |
| Package unavailable | Approved release and entitlement status | Follow the approved Private Preview access process | Use an unpublished workspace path |
| Version mismatch | Exact package tuple and lockfile | Align to the tested tuple | Mix provisional package versions |
For support evidence, retain privacy-safe identifiers and bounded lifecycle facts. Do not include credentials, raw provider payloads, customer records, or unredacted traces.