feat: establish Orbit models, migrations and development baseline

weave/model/activation.go

@@ -0,0 +1,32 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Activation 表示步骤的一次具体激活，人工恢复通过新激活保留历史。
+// 对应表 weave_activations；这是服务端持久化模型，不直接作为 API 响应。
+type Activation struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// WorkflowID 所属流程实例标识。
+	WorkflowID core.ID `db:"workflow_id"`
+	// StepID 所属逻辑步骤标识。
+	StepID core.ID `db:"step_id"`
+	// Sequence 同一步骤的激活序号，人工恢复递增并保留旧记录。
+	Sequence uint32 `db:"sequence"`
+	// State 当前状态；只允许定义的状态转换并配合事务校验。
+	State StepState `db:"state"`
+	// TaskID 关联的 Pulse 任务标识；可为空，表示尚未设置该关联或值。
+	TaskID *core.ID `db:"task_id"`
+	// Input 本次实例或步骤激活的输入快照 JSON。
+	Input core.JSON `db:"input"`
+	// Output 已保存的输出 JSON；未完成时可以为空。
+	Output core.JSON `db:"output"`
+	// CompletedAt 终结时间；非终态为空，进入终态时必须写入。
+	CompletedAt *time.Time `db:"completed_at"`
+}
+
+func (Activation) TableName() string { return "weave_activations" }

weave/model/definition.go

@@ -0,0 +1,18 @@
+package model
+
+import (
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Definition 表示流程定义的稳定身份，不保存可直接执行的业务代码。
+// 对应表 weave_definitions；这是服务端持久化模型，不直接作为 API 响应。
+type Definition struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// Name 可读名称，唯一性范围由对应数据表约束。
+	Name string `db:"name"`
+	// Description 定义用途说明，不承载运行状态。
+	Description string `db:"description"`
+}
+
+func (Definition) TableName() string { return "weave_definitions" }

weave/model/definition_version.go

@@ -0,0 +1,26 @@
+package model
+
+import (
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// DefinitionVersion 表示已发布的不可变流程定义版本。
+// 对应表 weave_definition_versions；这是服务端持久化模型，不直接作为 API 响应。
+type DefinitionVersion struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// DefinitionID 稳定流程定义标识。
+	DefinitionID core.ID `db:"definition_id"`
+	// Version 不可变发布版本；同版本不同内容必须拒绝。
+	Version string `db:"version"`
+	// SchemaVersion 流程定义文档的结构版本。
+	SchemaVersion uint32 `db:"schema_version"`
+	// Specification 版本化规则定义 JSON；发布后禁止原地修改。
+	Specification core.JSON `db:"specification"`
+	// ContentDigest 不可变定义内容的 SHA-256 摘要。
+	ContentDigest core.Digest `db:"content_digest"`
+	// PublishedBy 发布版本的认证主体，用于追溯发布来源。
+	PublishedBy string `db:"published_by"`
+}
+
+func (DefinitionVersion) TableName() string { return "weave_definition_versions" }

weave/model/inbox_event.go

@@ -0,0 +1,34 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// InboxEvent 表示Weave 内部事件消费记录，和流程推进一起确认消费。
+// 对应表 weave_inbox；这是服务端持久化模型，不直接作为 API 响应。
+type InboxEvent struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// WorkflowID 所属流程实例标识。
+	WorkflowID core.ID `db:"workflow_id"`
+	// EventID 来源持久化事件标识，用于消费去重。
+	EventID core.ID `db:"event_id"`
+	// State 当前状态；只允许定义的状态转换并配合事务校验。
+	State InboxState `db:"state"`
+	// AvailableAt 最早可被领取或处理的时间，统一 UTC。
+	AvailableAt time.Time `db:"available_at"`
+	// LeaseOwner 租约持有者标识；未持有租约时为空。
+	LeaseOwner *core.ID `db:"lease_owner"`
+	// LeaseEpoch 递增的执行或消费代次，用于隔离旧授权。
+	LeaseEpoch uint64 `db:"lease_epoch"`
+	// LeaseUntil 内部消费租约截止时间；没有消费租约时为空。
+	LeaseUntil *time.Time `db:"lease_until"`
+	// ProcessedAt 内部事件完成消费的时间；尚未消费时为空。
+	ProcessedAt *time.Time `db:"processed_at"`
+	// ErrorCode 稳定错误分类，供恢复策略判断；不得写入敏感原始错误；可为空，表示尚未设置该关联或值。
+	ErrorCode *string `db:"error_code"`
+}
+
+func (InboxEvent) TableName() string { return "weave_inbox" }

weave/model/instance.go

@@ -0,0 +1,44 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Instance 表示流程运行实例，固定定义版本，暂停与执行状态分别保存。
+// 对应表 weave_instances；这是服务端持久化模型，不直接作为 API 响应。
+type Instance struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// DefinitionID 稳定流程定义标识。
+	DefinitionID core.ID `db:"definition_id"`
+	// DefinitionVersionID 实例固定使用的定义版本记录，不能随新版本发布而变化。
+	DefinitionVersionID core.ID `db:"definition_version_id"`
+	// GateID 执行门控标识，用于检查是否允许新的领取与开始。
+	GateID core.ID `db:"gate_id"`
+	// State 流程执行状态，与独立的暂停标记同时展示。
+	State InstanceState `db:"state"`
+	// Paused 暂停标记；停止新的受控工作，不表示在途请求已停止。
+	Paused bool `db:"paused"`
+	// ControlRevision 暂停、继续等控制操作的版本，避免旧操作覆盖新决定。
+	ControlRevision uint64 `db:"control_revision"`
+	// Input 本次实例或步骤激活的输入快照 JSON。
+	Input core.JSON `db:"input"`
+	// Output 已保存的输出 JSON；未完成时可以为空。
+	Output core.JSON `db:"output"`
+	// PolicySnapshot 受理时冻结的实际生效策略 JSON。
+	PolicySnapshot core.JSON `db:"policy_snapshot"`
+	// BusinessKey 业务侧关联键，用于检索追踪，不自动提供业务幂等；可为空，表示尚未设置该关联或值。
+	BusinessKey *string `db:"business_key"`
+	// DeadlineAt 流程总截止时间，暂停默认不延长此业务边界。
+	DeadlineAt time.Time `db:"deadline_at"`
+	// CancelRequestedAt 取消意图的持久化时间；不等于取消已完成；可为空，表示尚未设置该关联或值。
+	CancelRequestedAt *time.Time `db:"cancel_requested_at"`
+	// CompletedAt 终结时间；非终态为空，进入终态时必须写入。
+	CompletedAt *time.Time `db:"completed_at"`
+	// RetryOf 来源记录标识，人工重新发起时用于保留历史关联；可为空，表示尚未设置该关联或值。
+	RetryOf *core.ID `db:"retry_of"`
+}
+
+func (Instance) TableName() string { return "weave_instances" }

weave/model/pending_advance.go

@@ -0,0 +1,26 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// PendingAdvance 表示暂停或分批推进后的续接检查点，避免仅依赖内存唤醒。
+// 对应表 weave_pending_advances；这是服务端持久化模型，不直接作为 API 响应。
+type PendingAdvance struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// WorkflowID 所属流程实例标识。
+	WorkflowID core.ID `db:"workflow_id"`
+	// StepID 所属逻辑步骤标识。
+	StepID core.ID `db:"step_id"`
+	// ExpectedStepRevision 恢复推进时要求的步骤版本，避免使用过期检查点。
+	ExpectedStepRevision uint64 `db:"expected_step_revision"`
+	// Checkpoint 分批或暂停后继续推进所需的持久化 JSON 检查点。
+	Checkpoint core.JSON `db:"checkpoint"`
+	// AvailableAt 最早可被领取或处理的时间，统一 UTC。
+	AvailableAt time.Time `db:"available_at"`
+}
+
+func (PendingAdvance) TableName() string { return "weave_pending_advances" }

weave/model/poll_policy.go

@@ -0,0 +1,32 @@
+package model
+
+import (
+	"errors"
+	"time"
+)
+
+var (
+	ErrPollExhausted = errors.New("poll budget exhausted; reconciliation required")
+	ErrPollInFlight  = errors.New("a poll round is still in flight")
+	ErrPollResolved  = errors.New("poll already resolved")
+	ErrPollNotDue    = errors.New("poll interval has not elapsed")
+)
+
+// NextRound 用数据库时间检查已锁定的查询快照。调用方还必须核验执行门控，
+// 并在同一事务中写入计数、唯一轮次及对应的 Pulse 任务。
+// 下一查询时间为空表示持久化暂挂，不能视为允许立即发起查询。
+func (p PollState) NextRound(now time.Time) (uint32, error) {
+	if p.ResolvedAt != nil {
+		return 0, ErrPollResolved
+	}
+	if p.MaxRounds == 0 || p.UsedRounds >= p.MaxRounds || !now.Before(p.DeadlineAt) {
+		return 0, ErrPollExhausted
+	}
+	if p.CurrentTaskID != nil {
+		return 0, ErrPollInFlight
+	}
+	if p.NextPollAt == nil || now.Before(*p.NextPollAt) {
+		return 0, ErrPollNotDue
+	}
+	return p.UsedRounds + 1, nil
+}

weave/model/poll_policy_test.go

@@ -0,0 +1,38 @@
+package model
+
+import (
+	"errors"
+	core "git.yuntuo.hk/k2safe/orbit/model"
+	"testing"
+	"time"
+)
+
+func TestPollRecoveryPreservesBudgetAndDeadline(t *testing.T) {
+	now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+	p := PollState{MaxRounds: 3, UsedRounds: 2, DeadlineAt: now.Add(time.Minute), NextPollAt: &now}
+	n, err := p.NextRound(now)
+	if err != nil || n != 3 {
+		t.Fatalf("next round: %d %v", n, err)
+	}
+	p.UsedRounds = 3
+	if _, err := p.NextRound(now); !errors.Is(err, ErrPollExhausted) {
+		t.Fatal("counter reset or limit bypass")
+	}
+	p.UsedRounds = 2
+	if _, err := p.NextRound(p.DeadlineAt); !errors.Is(err, ErrPollExhausted) {
+		t.Fatal("deadline equality permitted new round")
+	}
+	task := core.ID("00000000000000000000000000000001")
+	p.CurrentTaskID = &task
+	if _, err := p.NextRound(now); !errors.Is(err, ErrPollInFlight) {
+		t.Fatal("overlapping poll round permitted")
+	}
+}
+func TestResumeDoesNotClearReviewOrCancellation(t *testing.T) {
+	now := time.Now()
+	for _, i := range []Instance{{State: InstanceRunning, Paused: true}, {State: InstanceNeedsReview}, {State: InstanceCancelling}, {State: InstanceRunning, CancelRequestedAt: &now}, {State: InstanceSucceeded}, {State: InstanceState("future")}} {
+		if i.AllowsNewWork() {
+			t.Fatalf("allowed new work: %+v", i)
+		}
+	}
+}

weave/model/poll_round.go

@@ -0,0 +1,22 @@
+package model
+
+import (
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// PollRound 表示一次业务查询轮次，一轮对应一个 Pulse 任务。
+// 对应表 weave_poll_rounds；这是服务端持久化模型，不直接作为 API 响应。
+type PollRound struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// WorkflowID 所属流程实例标识。
+	WorkflowID core.ID `db:"workflow_id"`
+	// ActivationID 所属步骤激活，区分旧轮次和人工恢复后的新轮次。
+	ActivationID core.ID `db:"activation_id"`
+	// Round 本次激活内的查询轮次编号，从 1 开始。
+	Round uint32 `db:"round"`
+	// TaskID 关联的 Pulse 任务标识。
+	TaskID core.ID `db:"task_id"`
+}
+
+func (PollRound) TableName() string { return "weave_poll_rounds" }

weave/model/poll_state.go

@@ -0,0 +1,36 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// PollState 表示有界查询节点的持久化预算与恢复检查点。
+// 对应表 weave_poll_states；这是服务端持久化模型，不直接作为 API 响应。
+type PollState struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// WorkflowID 所属流程实例标识。
+	WorkflowID core.ID `db:"workflow_id"`
+	// ActivationID 所属步骤激活，区分旧轮次和人工恢复后的新轮次。
+	ActivationID core.ID `db:"activation_id"`
+	// MaxRounds 业务查询最多轮次，不等于单轮请求重试次数。
+	MaxRounds uint32 `db:"max_rounds"`
+	// UsedRounds 已创建的查询轮次，重启或暂停继续不得重置。
+	UsedRounds uint32 `db:"used_rounds"`
+	// MaxAttemptsPerRound 每轮 Pulse 任务最多尝试数，包含该轮首次请求。
+	MaxAttemptsPerRound uint32 `db:"max_attempts_per_round"`
+	// IntervalMS 相邻业务查询轮次的等待间隔，单位毫秒。
+	IntervalMS uint64 `db:"interval_ms"`
+	// DeadlineAt 查询节点总截止时间，轮次和单轮重试都受此边界限制。
+	DeadlineAt time.Time `db:"deadline_at"`
+	// NextPollAt 最早允许下一轮查询的时间；为空表示当前不能直接推进。
+	NextPollAt *time.Time `db:"next_poll_at"`
+	// CurrentTaskID 当前在途查询任务；非空时禁止重叠开启下一轮；可为空，表示尚未设置该关联或值。
+	CurrentTaskID *core.ID `db:"current_task_id"`
+	// ResolvedAt 等待或查询节点结清的时间；尚未结清时为空。
+	ResolvedAt *time.Time `db:"resolved_at"`
+}
+
+func (PollState) TableName() string { return "weave_poll_states" }

weave/model/signal.go

@@ -0,0 +1,40 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Signal 表示已可靠受理的外部信号，受理与消费是两个阶段。
+// 对应表 weave_signals；这是服务端持久化模型，不直接作为 API 响应。
+type Signal struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// WorkflowID 所属流程实例标识。
+	WorkflowID core.ID `db:"workflow_id"`
+	// KeyDigest 稳定幂等键或资源键的 SHA-256 摘要。
+	KeyDigest core.Digest `db:"key_digest"`
+	// RequestDigest 规范化请求语义的 SHA-256 摘要，用于识别同键不同内容。
+	RequestDigest core.Digest `db:"request_digest"`
+	// Type 事件或信号的稳定类型标识。
+	Type string `db:"type"`
+	// TargetStepKey 信号目标步骤键，用于早到信号的后续匹配。
+	TargetStepKey string `db:"target_step_key"`
+	// CorrelationKey 外部业务操作关联键，防止旧信号误用于新工作。
+	CorrelationKey string `db:"correlation_key"`
+	// Payload 版本化输入或事件内容；仅承载通用 JSON，不解释行业规则。
+	Payload core.JSON `db:"payload"`
+	// ActorID 经认证的操作主体标识，不能直接信任请求自报值。
+	ActorID string `db:"actor_id"`
+	// State 当前状态；只允许定义的状态转换并配合事务校验。
+	State SignalState `db:"state"`
+	// AcceptedAt 信号可靠受理时间，不能用稍后的消费时间替代。
+	AcceptedAt time.Time `db:"accepted_at"`
+	// ExpiresAt 过期时间，统一 UTC；到期后的行为由对应资源策略决定。
+	ExpiresAt time.Time `db:"expires_at"`
+	// ConsumedWaitID 消费该信号的等待记录；尚未消费时为空。
+	ConsumedWaitID *core.ID `db:"consumed_wait_id"`
+}
+
+func (Signal) TableName() string { return "weave_signals" }

weave/model/state.go

@@ -0,0 +1,74 @@
+package model
+
+// InstanceState 描述流程执行状态，独立的 Paused 标记控制是否允许新工作。
+type InstanceState string
+
+const (
+	InstanceRunning     InstanceState = "RUNNING"
+	InstanceWaiting     InstanceState = "WAITING"
+	InstanceCancelling  InstanceState = "CANCELLING"
+	InstanceNeedsReview InstanceState = "NEEDS_REVIEW"
+	InstanceSucceeded   InstanceState = "SUCCEEDED"
+	InstanceFailed      InstanceState = "FAILED"
+	InstanceCancelled   InstanceState = "CANCELLED"
+)
+
+func (s InstanceState) Terminal() bool {
+	return s == InstanceSucceeded || s == InstanceFailed || s == InstanceCancelled
+}
+func (i Instance) AllowsNewWork() bool {
+	return !i.Paused && i.CancelRequestedAt == nil && (i.State == InstanceRunning || i.State == InstanceWaiting)
+}
+
+type NodeKind string
+
+const (
+	NodeTask     NodeKind = "TASK"     // 通过 Pulse 执行业务处理器。
+	NodeBranch   NodeKind = "BRANCH"   // 按已保存结果选择条件路径。
+	NodeParallel NodeKind = "PARALLEL" // 展开有界并行分支。
+	NodeJoin     NodeKind = "JOIN"     // 按规则汇合并行结果。
+	NodeSignal   NodeKind = "SIGNAL"   // 等待业务信号。
+	NodeTimer    NodeKind = "TIMER"    // 等待指定时间。
+	NodePoll     NodeKind = "POLL"     // 有界重复查询节点。
+)
+
+type StepState string
+
+const (
+	StepBlocked     StepState = "BLOCKED"
+	StepReady       StepState = "READY"
+	StepActive      StepState = "ACTIVE"
+	StepWaiting     StepState = "WAITING"
+	StepNeedsReview StepState = "NEEDS_REVIEW"
+	StepSucceeded   StepState = "SUCCEEDED"
+	StepFailed      StepState = "FAILED"
+	StepCancelled   StepState = "CANCELLED"
+	StepSkipped     StepState = "SKIPPED"
+)
+
+type WaitState string
+
+const (
+	WaitWaiting   WaitState = "WAITING"
+	WaitSatisfied WaitState = "SATISFIED"
+	WaitExpired   WaitState = "EXPIRED"
+	WaitCancelled WaitState = "CANCELLED"
+)
+
+type SignalState string
+
+const (
+	SignalPending  SignalState = "PENDING"
+	SignalConsumed SignalState = "CONSUMED"
+	SignalExpired  SignalState = "EXPIRED"
+	SignalRejected SignalState = "REJECTED"
+)
+
+type InboxState string
+
+const (
+	InboxPending     InboxState = "PENDING"
+	InboxLeased      InboxState = "LEASED"
+	InboxProcessed   InboxState = "PROCESSED"
+	InboxQuarantined InboxState = "QUARANTINED"
+)

weave/model/step.go

@@ -0,0 +1,24 @@
+package model
+
+import (
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Step 表示实例中的逻辑步骤，指向该步骤当前的激活记录。
+// 对应表 weave_steps；这是服务端持久化模型，不直接作为 API 响应。
+type Step struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// WorkflowID 所属流程实例标识。
+	WorkflowID core.ID `db:"workflow_id"`
+	// Key 定义中的稳定步骤键，在同一流程实例内唯一。
+	Key string `db:"key"`
+	// Kind 节点或等待类型，决定由哪类推进规则处理。
+	Kind NodeKind `db:"kind"`
+	// State 当前状态；只允许定义的状态转换并配合事务校验。
+	State StepState `db:"state"`
+	// CurrentActivationID 当前激活记录，必须属于本实例的本步骤；可为空，表示尚未设置该关联或值。
+	CurrentActivationID *core.ID `db:"current_activation_id"`
+}
+
+func (Step) TableName() string { return "weave_steps" }

weave/model/wait.go

@@ -0,0 +1,32 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Wait 表示可恢复的信号或时间等待，不长期占用业务 Worker。
+// 对应表 weave_waits；这是服务端持久化模型，不直接作为 API 响应。
+type Wait struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// WorkflowID 所属流程实例标识。
+	WorkflowID core.ID `db:"workflow_id"`
+	// ActivationID 所属步骤激活，区分旧轮次和人工恢复后的新轮次。
+	ActivationID core.ID `db:"activation_id"`
+	// Kind 节点或等待类型，决定由哪类推进规则处理。
+	Kind string `db:"kind"`
+	// State 当前状态；只允许定义的状态转换并配合事务校验。
+	State WaitState `db:"state"`
+	// CorrelationKey 外部业务操作关联键，防止旧信号误用于新工作。
+	CorrelationKey string `db:"correlation_key"`
+	// DeadlineAt 等待截止时间，用可靠受理时间判断信号是否按时到达。
+	DeadlineAt time.Time `db:"deadline_at"`
+	// WakeTaskID 内部定时唤醒任务；无需定时唤醒时为空。
+	WakeTaskID *core.ID `db:"wake_task_id"`
+	// ResolvedAt 等待或查询节点结清的时间；尚未结清时为空。
+	ResolvedAt *time.Time `db:"resolved_at"`
+}
+
+func (Wait) TableName() string { return "weave_waits" }