Class HistoryWriter

java.lang.Object

cloud.opencode.base.flow.internal.HistoryWriter

public final class HistoryWriter
extends Object

Internal append-only writer for HistoryRecords. 内部追加写工具，专门用于 HistoryRecord。

By contract (v4 §6.4 / D19), history rows are never updated or deleted; this class only ever calls FlowRepository.appendHistory(HistoryRecord). Any future compliance correction MUST be expressed as a NEW row in a separate flow_history_correction table.

按 v4 约定，history 表为仅追加；本类只调用 FlowRepository.appendHistory(HistoryRecord)。未来若有合规修订需求， 必须新增 flow_history_correction 表追加记录，而不是修改原行。

Since:

JDK 25, opencode-base-flow V1.0.5

Author:

Leon Soo

Field Summary

Fields

Modifier and Type	Field	Description
static final int	MAX_COMMENT_LEN	Hard cap on the history comment column size (4 KiB chars).
static final int	MAX_EXTRA_JSON_LEN	Hard cap on the history extra_json column size (16 KiB chars).

Constructor Summary

Constructors

Constructor	Description
HistoryWriter(FlowRepository repo)	Constructs a writer backed by the supplied repository and the default snowflake id provider.

Method Summary

Modifier and Type	Method	Description
void	write(String instanceId, String taskId, String stepId, Action action, String operatorId, String comment, String extraJson)	Appends a new history row.

Methods inherited from class Object

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

Field Details

MAX_COMMENT_LEN

public static final int MAX_COMMENT_LEN

Hard cap on the history comment column size (4 KiB chars). Callers normally route comments through InputSanitizer which caps them at 2000 chars, but this is a defence-in-depth check for non-comment call sites (e.g. operations that synthesise comments internally). history.comment 列字符上限（4 KiB）—— InputSanitizer 已限制 2000，这里是 防御深度（覆盖非用户输入路径）。

See Also:

• Constant Field Values

MAX_EXTRA_JSON_LEN

public static final int MAX_EXTRA_JSON_LEN

Hard cap on the history extra_json column size (16 KiB chars). Designed to fit MySQL TEXT (64 KiB) comfortably even with utf8mb4. history.extra_json 列字符上限（16 KiB）—— 充分容纳 utf8mb4 下的 MySQL TEXT。

See Also:

• Constant Field Values

Constructor Details

HistoryWriter

public HistoryWriter(FlowRepository repo)

Constructs a writer backed by the supplied repository and the default snowflake id provider. 使用默认 snowflake id 提供者构造 writer。

Parameters:

repo - persistence facade — 持久化门面

Since:

JDK 25, opencode-base-flow V1.0.5

Method Details

write

public void write(String instanceId,
 String taskId,
 String stepId,
 Action action,
 String operatorId,
 String comment,
 String extraJson)

Appends a new history row. 追加一条历史。

Parameters:

instanceId - owning instance id — 所属实例

taskId - related task id (nullable) — 关联任务（可空）

stepId - step id (nullable) — 节点（可空）

action - action type — 动作

operatorId - operator user id — 操作人

comment - human comment (nullable) — 文本意见（可空）

extraJson - action-specific extra JSON (nullable) — 附带 JSON（可空）

Since:

JDK 25, opencode-base-flow V1.0.5