Skip to main content

AI Authoring Guidance

BDL is designed to support governed AI-assisted system authoring.

AI systems must generate BDL from explicit evidence, active contracts and validated capability information rather than guessing unsupported Barsa behavior.

Core rule​

Never invent native state.

If a required Barsa identifier, capability, property or runtime behavior cannot be proven from the active metadata and documentation, the AI should stop, request resolution or emit a diagnostic rather than fabricate a value.

Required authoring context​

Before generating production BDL, an AI system should know the relevant:

  • BDL language version
  • Knowledge baseline
  • Native Barsa contract version
  • Runtime baseline
  • Authoring surface
  • Target system identity
  • Required live metadata
  • Capability status
  • Known gaps and limitations
  • Approval requirements

Authoring workflow​

A governed AI authoring workflow should follow this sequence:

  1. Understand the requested system change.
  2. Identify the host artifacts involved.
  3. Check capability documentation.
  4. Check known gaps and restrictions.
  5. Resolve native Barsa metadata and identifiers.
  6. Generate the smallest valid BDL definition.
  7. Parse and preflight.
  8. Run non-mutating validation where supported.
  9. Review execution plan and blocking diagnostics.
  10. Request approval when required.
  11. Execute through governed runtime services.
  12. Reload and verify the result.
  13. Export or round-trip where supported.
  14. Record evidence and reconcile differences.

Do not guess native IDs​

AI systems must not infer native Barsa identifiers from:

  • Names
  • Captions
  • Ordering
  • Similar systems
  • Previous environments
  • Example files

Identifiers must be resolved from the active target environment when required.

Do not infer capability​

The presence of a feature in Native Barsa does not automatically mean BDL production authoring is available.

Check all four capability layers:

  1. Native Barsa
  2. Runtime Support
  3. BDL Expressibility
  4. BDL Authoring Availability

Prefer the smallest valid definition​

AI should avoid generating unnecessary properties.

Minimal definitions are easier to validate, review, diagnose and round-trip.

Add optional metadata only when it is required by the user request or supported contract.

Preserve explicit user intent​

AI-generated BDL should reflect the requested behavior without silently expanding scope.

Do not add:

  • Unrequested entities
  • Unrequested permissions
  • Unrequested workflows
  • Guessed defaults
  • Guessed relations
  • Arbitrary system code
  • Unsupported automation

Diagnostics over fabrication​

When required evidence is missing, produce a clear diagnostic rather than generating plausible but unverified BDL.

Examples include:

  • Missing system ID
  • Missing entity reference
  • Unsupported artifact property
  • Authoring surface restriction
  • Known native limitation
  • Runtime capability gap

System code​

AI must treat systemCode as a governed surface.

It is not permission for arbitrary code injection.

Only documented code slots and approved operations should be generated.

Validation is mandatory​

Generated BDL should not proceed directly from generation to mutation.

Use the validation pipeline:

Parse -> Preflight -> ValidateOnly -> Execution Plan -> Diagnostics -> Approval -> Execute -> Verify

where each stage is supported by the active runtime.

Round-trip awareness​

When BDL is exported back from Barsa, AI systems should distinguish:

  • Exact round-trip values
  • Values that can be recovered only partially
  • Values that cannot be recovered losslessly
  • Values intentionally omitted because native evidence is unavailable

Never reconstruct missing native values through speculation.

Version discipline​

AI must not mix rules from different BDL baselines unless the relationship between those versions is documented.

Always bind generated guidance and BDL to the active version context.

Evidence discipline​

When diagnosing or confirming success, distinguish evidence types.

A successful build does not prove runtime persistence.

A successful runtime call does not by itself prove export parity.

A successful export does not prove every authoring surface is production-ready.

Close each claim only with evidence for that layer.

Safe failure​

When the active contract does not support a requested operation, AI should say that the operation is unavailable or unresolved.

Safe refusal to fabricate is preferable to producing invalid or unsafe BDL.

Next​

Continue to Releases and Downloads for versioned BDL knowledge packs, contracts and supporting artifacts.