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 |
For live recovery, the exact Runtime handle is private and process-local; it cannot itself survive restart. For durable verifier-only recovery after process loss, inspect the host-owned closed DurableRecoveryRecordV2, source record and its stored digest, lease, fence, and CAS result. Runtime durable recovery rehydrates through accepted recovery authority, stable verifier registration, and a record-blind Actions facade, then performs authoritative read-back with zero provider redispatch. A stale lease, fence mismatch, source-record mismatch, or CAS rejection is evidence to preserve and investigate; a recovery record is not permission to dispatch, execute, or redispatch. COMMITTED, DISPROVED, and UNKNOWN remain evidence-bound outcomes, and UNKNOWN may remain UNKNOWN in a related version-2 record. The host owns persistence, routing, authority controls, retry scheduling, monitoring, and bounded delivery; this does not provide automatic or hosted recovery, exactly-once execution, or universal production durability.
| 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 current access status | Check Packages and access; use the current package set from a trusted preview handoff | Use an unpublished workspace path or claim public availability |
| Version mismatch | Exact package tuple and lockfile | Align to the current package set | 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.