Skip to main content

Troubleshooting

BDL troubleshooting is evidence-driven.

When an operation fails or produces an unexpected result, classify the incident before changing the definition or runtime.

Incident classes​

The current troubleshooting model uses six primary incident classes:

ClassMeaning
BDL_AUTHORING_DEFECTThe authored BDL is incorrect or invalid.
PREEXEC_DETECTION_GAPThe BDL is invalid, but pre-execution validation should have detected it before execution.
RT_RUNTIME_BUGThe governed runtime behaves incorrectly despite valid supported input.
ENVIRONMENT_OR_BASELINEThe failure is caused by environment, installation, version baseline, dependency or configuration differences.
KNOWN_GAP_OR_UNSUPPORTEDThe requested behavior is a documented gap, limitation or unsupported operation.
INSUFFICIENT_EVIDENCEThere is not enough reliable evidence to classify or close the incident.

Do not collapse incident classes​

Fixing an authoring error does not automatically close a validation defect.

For example, if an invalid BDL document reaches execution even though Preflight or ValidateOnly should have rejected it, there are two separate issues:

  1. The authoring defect
  2. The pre-execution detection gap

Both should be tracked independently.

Mandatory incident evidence​

A useful runtime incident should preserve evidence from the same execution whenever possible.

Collect:

  • The exact BDL file used
  • A hash or stable identity for that file
  • The execution log from the same run
  • Runtime and package baseline
  • Compile or ValidateOnly result when available
  • Execution plan
  • Structured execution result
  • Post-verification or export result
  • Expected behavior
  • Actual behavior

Without this evidence, a failure may need to remain classified as INSUFFICIENT_EVIDENCE.

Triage workflow​

Use this order when investigating a problem:

  1. Preserve the exact input and execution evidence.
  2. Confirm the BDL, runtime and contract versions.
  3. Re-run parsing and validation without mutation.
  4. Check capability availability and known gaps.
  5. Confirm that required native metadata was resolved rather than guessed.
  6. Review the execution plan and diagnostics.
  7. Determine whether mutation actually occurred.
  8. Reload native metadata independently.
  9. Export or round-trip the result when supported.
  10. Assign the incident class based on evidence.

Mutation may succeed before an exception​

An exception does not always prove that a mutation failed.

For some native operations, an exception can occur after the underlying change has already taken effect.

Therefore, determine the actual outcome through an independent reload or post-verification rather than relying only on the exception.

Do not invent missing native state​

Exporter and authoring logic must not fabricate values that cannot be recovered reliably from Native Barsa.

If native state cannot be read losslessly, report the limitation or diagnostic instead of inventing a value.

Build success is not runtime proof​

A successful build or compile confirms only the layer that was actually tested.

It does not by itself prove:

  • Native persistence
  • Runtime execution
  • Browser behavior
  • Export parity
  • Round-trip correctness
  • Production authoring availability

Close each claim only with evidence for that layer.

Current diagnostic examples​

The active troubleshooting baseline includes diagnostics and documented limitations such as:

  • Conditional workflow binding gaps when the native condition binding is genuinely incomplete
  • Lossless export limitations where required native form state cannot be recovered
  • Native delete operations that may require independent reload verification
  • Business rules that cannot be exported without a supported event and must not receive fabricated events

These are version-sensitive. Always consult the active diagnostic and known-gap catalogs.

Escalation principle​

Escalate an incident when the available evidence demonstrates a runtime or validation problem that cannot be resolved by correcting the authored BDL or environment.

Do not escalate an unsupported or documented known-gap operation as a runtime defect unless new evidence contradicts the active contract.

Next​

Continue to Known Gaps for documented limitations, deferred surfaces and version-specific restrictions.