Files, Imports, and Graph Boundaries

BLOGE DSL files can describe more than one isolated graph. Current source supports imports, sub-graph references, and graph-level streaming boundaries so larger workflows can be split into reviewable files without hiding runtime behavior.

Imports

Use import before the graph block to make another .bloge graph visible as a sub-graph.

import "./payment.bloge" as payment
import "./inventory.bloge"

graph checkout {
  node charge : subgraph("payment") {
    input {
      orderId = ctx.orderId
    }
  }
}

If as <alias> is omitted, the compiler derives the alias from the imported path stem. Import resolution is handled through GraphResolver implementations such as file-system and classpath resolvers.

Import Safety

The compiler treats imports as part of the graph contract:

Case	Behavior
Duplicate alias	Compilation error
Unresolved path	Compilation diagnostic or error, depending on mode
Circular import	Compilation error with the detected chain
Imported graph compile failure	Root compilation reports imported diagnostics

This makes imported graphs suitable for build-time validation instead of weak textual inclusion.

Sub-Graph Nodes

Imported graphs can be executed through sub-graph nodes. The outer graph still owns the visible dependency edge, timeout, retry, fallback, and input contract.

node riskReview : subgraph("risk-scoring") {
  depends_on = [fetchApplication]
  input {
    application = fetchApplication.output
  }
  timeout = 10s
}

Sub-graph composition is useful when a workflow is large enough to need decomposition but still belongs inside one runtime execution model.

Graph Inputs and Outputs

Ordinary graph inputs are read through ctx.<field> and ordinary graph outputs are node outputs visible in GraphResult.

For schema-aware graphs, declare input and output schemas so tooling and validation can reason about graph boundaries:

schema OrderRequest {
  orderId: String
}

schema OrderDecision {
  approved: Boolean
  reason: String?
}

graph orderDecision {
  input: OrderRequest
  output: OrderDecision

  node decide : DecisionOperator {
    input {
      orderId = ctx.orderId
    }
  }
}

Schema contracts are especially important when a graph is imported and reused as a sub-graph.

Graph-Level Streaming Boundaries

Streaming graph inputs and outputs are covered in detail in Streaming I/O. Use them when callers need live chunks rather than only a final materialized result.

Design Guidance

• Use imports to split stable sub-graphs, not to hide accidental complexity.
• Keep imported graph aliases stable; they become part of the caller's source contract.
• Prefer explicit input/output schemas for imported graphs.
• Avoid circular workflow decomposition; if two graphs need each other, the boundary is probably wrong.
• Validate imports in CI through the same compiler path used in production.