Class DslValidator

java.lang.Object

cloud.opencode.base.flow.dsl.DslValidator

public final class DslValidator
extends Object

Semantic / quota validator for parsed FlowDsl documents. 已解析 FlowDsl 文档的语义与配额校验器。

This validator runs after DslParser has produced a FlowDsl record from the raw JSON. It enforces the rules that are either too expressive for static JSON Schema (cross-references, uniqueness, reserved words) or that depend on host-tunable quotas (v4 §4.7).

校验器在 DslParser 把 JSON 反序列化为 FlowDsl 之后运行， 负责执行那些静态 JSON Schema 表达力不足（跨字段引用、唯一性、保留字）或 依赖宿主可调配额（v4 §4.7）的规则。

Quota knobs are read from System.getProperty(String) once at construction time and frozen on the instance, matching v4 D22 (ClassLoader-isolated configuration). Hosts that need to re-tune quotas at runtime must build a new validator instance.

配额参数在构造时一次性从 System.getProperty(String) 读取并固化在 实例上（v4 D22 ClassLoader 隔离配置）。需要运行时调整配额的宿主必须重建 校验器实例。

Validation order is fixed so the most fundamental error is surfaced first: structural / id format / quota / per-step semantic / references / depth.

校验顺序固定，按"结构 / id 格式 / 配额 / 节点语义 / 引用 / 深度"递进， 便于宿主先看到最根本的问题。

Zero third-party dependencies. No JSON Schema engine is pulled in; the flow-dsl-v1.schema.json file ships as documentation + tooling aid only, and the runtime rules are encoded directly here.

零第三方依赖。不引入 JSON Schema 引擎； flow-dsl-v1.schema.json 仅作为文档和工具辅助发布，运行期规则全部 在本类中以代码形式表达。

Since:

JDK 25, opencode-base-flow V1.0.5

Author:

Leon Soo

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_MAX_ASSIGNEES_PER_STEP	Default per-step assignees quota (v4 §4.7).
static final int	DEFAULT_MAX_DEPTH	Default JSON nesting depth quota (v4 §4.7).
static final int	DEFAULT_MAX_STEPS	Default steps quota (v4 §4.7). steps 默认配额。
static final int	DEFAULT_MAX_TRANSITIONS	Default transitions quota (v4 §4.7). transitions 默认配额。
static final String	PROP_MAX_ASSIGNEES_PER_STEP	Property key for the per-step assignees quota (v4 §4.7).
static final String	PROP_MAX_DEPTH	Property key for the JSON nesting depth quota (v4 §4.7).
static final String	PROP_MAX_STEPS	Property key for the steps quota (v4 §4.7). steps 配额属性键（v4 §4.7）。
static final String	PROP_MAX_TRANSITIONS	Property key for the transitions quota (v4 §4.7). transitions 配额属性键。
static final String	RESERVED_STEP_ID_INITIATOR	Reserved step id used by the reject action's targetStepId parameter (v4 §4.7 / §8.4).
static final Pattern	STEP_ID_PATTERN	Step id pattern (v4 §4.7).

Constructor Summary

Constructors

Constructor	Description
DslValidator()	Creates a validator with quotas frozen from current System.getProperty(String) values, defaulting only when a property is missing or blank.
DslValidator(int maxSteps, int maxTransitions, int maxAssigneesPerStep, int maxDepth)	Creates a validator with explicit quotas; primarily for unit tests and advanced hosts that wire quotas from their own config system.

Method Summary

Modifier and Type	Method	Description
void	validate(FlowDsl dsl, String originalJson)	Validates an already-parsed DSL document and its original JSON text.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

PROP_MAX_STEPS

public static final String PROP_MAX_STEPS

Property key for the steps quota (v4 §4.7). steps 配额属性键（v4 §4.7）。

See Also:

• Constant Field Values

PROP_MAX_TRANSITIONS

public static final String PROP_MAX_TRANSITIONS

Property key for the transitions quota (v4 §4.7). transitions 配额属性键。

See Also:

• Constant Field Values

PROP_MAX_ASSIGNEES_PER_STEP

public static final String PROP_MAX_ASSIGNEES_PER_STEP

Property key for the per-step assignees quota (v4 §4.7). 单 step assignees 配额属性键。

See Also:

• Constant Field Values

PROP_MAX_DEPTH

public static final String PROP_MAX_DEPTH

Property key for the JSON nesting depth quota (v4 §4.7). JSON 嵌套深度配额属性键。

See Also:

• Constant Field Values

DEFAULT_MAX_STEPS

public static final int DEFAULT_MAX_STEPS

Default steps quota (v4 §4.7). steps 默认配额。

See Also:

• Constant Field Values

DEFAULT_MAX_TRANSITIONS

public static final int DEFAULT_MAX_TRANSITIONS

Default transitions quota (v4 §4.7). transitions 默认配额。

See Also:

• Constant Field Values

DEFAULT_MAX_ASSIGNEES_PER_STEP

public static final int DEFAULT_MAX_ASSIGNEES_PER_STEP

Default per-step assignees quota (v4 §4.7). 单 step assignees 默认配额。

See Also:

• Constant Field Values

DEFAULT_MAX_DEPTH

public static final int DEFAULT_MAX_DEPTH

Default JSON nesting depth quota (v4 §4.7). JSON 默认嵌套深度配额。

See Also:

• Constant Field Values

RESERVED_STEP_ID_INITIATOR

public static final String RESERVED_STEP_ID_INITIATOR

Reserved step id used by the reject action's targetStepId parameter (v4 §4.7 / §8.4). It must never appear in user-authored DSL. 保留 step id；reject 操作的 targetStepId 入参专用 （v4 §4.7 / §8.4），不允许出现在用户编写的 DSL 中。

See Also:

• Constant Field Values

STEP_ID_PATTERN

public static final Pattern STEP_ID_PATTERN

Step id pattern (v4 §4.7). Leading letter, then alphanumerics/underscores, total length 1-64. Underscore prefix is forbidden so that RESERVED_STEP_ID_INITIATOR cannot be impersonated. Step id 正则（v4 §4.7）。以字母打头，后跟字母数字下划线，长度 1-64； 禁止下划线前缀，避免冒充 RESERVED_STEP_ID_INITIATOR。

Constructor Details

DslValidator

public DslValidator()

Creates a validator with quotas frozen from current System.getProperty(String) values, defaulting only when a property is missing or blank. 使用当前 System.getProperty(String) 值固化配额（仅当属性缺失或空白时 回退默认值）创建校验器。

Post-R2 CR-4: a non-blank but unparsable or non-positive value is surfaced as FlowException with FlowErrorCode.CFG_INVALID_VALUE rather than silently falling back, matching D22 fail-fast semantics shared with AddSignOperation / WithdrawOperation.

Post-R2 CR-4：非空但解析失败或非正数时直接抛 FlowException （FlowErrorCode.CFG_INVALID_VALUE），与 AddSignOperation / WithdrawOperation 共用的 D22 fail-fast 语义保持一致。

Since:

JDK 25, opencode-base-flow V1.0.5

DslValidator

public DslValidator(int maxSteps,
 int maxTransitions,
 int maxAssigneesPerStep,
 int maxDepth)

Creates a validator with explicit quotas; primarily for unit tests and advanced hosts that wire quotas from their own config system. 通过显式配额构造校验器；主要供单元测试和从自有配置系统注入配额的高级 宿主使用。

Parameters:

maxSteps - max steps array length | steps 数组最大长度

maxTransitions - max transitions array length | transitions 数组最大长度

maxAssigneesPerStep - max assignees per step | 单 step 最多 assignee 数

maxDepth - max JSON nesting depth | JSON 最大嵌套深度

Since:

JDK 25, opencode-base-flow V1.0.5

Method Details

validate

public void validate(FlowDsl dsl,
 String originalJson)

Validates an already-parsed DSL document and its original JSON text. 校验已解析的 DSL 文档及其原始 JSON 文本。

Throws on the first violation; the exception's errorCode matches the closest FlowErrorCode (DSL_INVALID / DSL_DUP_STEP_ID / DSL_INVALID_REFERENCE / DSL_INVALID_ENUM / DSL_QUOTA_EXCEEDED).

遇到首个违规即抛出；异常的 errorCode 对应最贴近的 FlowErrorCode。

Parameters:

dsl - parsed DSL record | 已解析的 DSL 记录

originalJson - the original JSON text (used for depth scanning) | 原始 JSON 文本（用于深度扫描）

Throws:

DslParseException - if any rule is violated | 任一规则违反时抛出

NullPointerException - if dsl or originalJson is null | dsl 或 originalJson 为 null

Since:

JDK 25, opencode-base-flow V1.0.5