Sparkdo.Scheduler.Abstractions 2.0.0-preview.2

Sparkdo.Scheduler.Abstractions

Sparkdo.Scheduler.Abstractions 是 Scheduler 的公共契约包。当前 public surface 已按 src/scheduler/docs/public-api-freeze-audit.md 做阶段 28 freeze audit：authoring API、稳定 result、descriptor/contribution、payload envelope、schedule/execution 快照、薄 management DTO 和必要 provider SPI 可以作为稳定候选；policy/budget/cost dry-run report 已退回 Sparkdo.Scheduler runtime internal evidence，store schema migration proof 已退回 Sparkdo.Scheduler.Testing conformance，MetricTagPolicy、business calendar provider/governance 类型和 sharding planner/aggregator 已退回 runtime/provider-owned surface。EF provider 或 Dashboard adapter 不应再反向牵引半成型 public 类型进入本包。

后续公共契约只允许承载用户 authoring、公共 API result、job context、descriptor/contribution、payload envelope 和必要 store SPI。runtime、provider、Testing、Dashboard、EF Core、Redis 和 ASP.NET Core adapter 不进入本包；新增 report-only / governance-only 类型前必须先更新 public API freeze audit。

当前入口

• IScheduler
• IJob<TArgs>
• JobContext<TArgs>
• [Job]
• [Concurrency]
• [Retry]
• EnqueueResult
• ScheduleRegistrationResult
• TriggerResult
• CancelResult
• JobDescriptor
• JobContribution
• JobActivator
• PayloadEnvelope
• Execution
• Schedule
• Occurrence
• ExecutionQuery
• ScheduleQuery
• HistoryQuery
• QueryConsistency
• OperatorActor
• CommandResultEnvelope
• ExecutorPlacementPolicy
• ExecutorRegistration
• PlacementDecision
• PlacementDecisionCode
• ExecutorStatus
• EventRetentionPolicy
• MissingEventAction
• HistoryCleanupRequest
• HistoryCleanupResult
• BusinessCalendarContract
• IShardStore
• StoreFeatures
• IExecutionQueue
• IScheduleStore
• IExecutorStore
• IHistoryStore
• ISchedulerStoreDiagnostics

源码目录约束

公共契约按维护原因分类，命名空间仍统一为 Sparkdo.Scheduler：

Store SPI 和 provider-facing seam 固定为异步接口：方法返回 ValueTask / ValueTask<T> 并接收 CancellationToken。内存 provider 可以同步完成，但 provider 契约不能退回同步方法，也不能把 provider 私有 row、EF mapping 或 migration executor 放入本包。History 端口使用 HistoryQuery 做受限查询，不要求 provider 支持无界全量读取；history cleanup 使用 HistoryCleanupRequest / HistoryCleanupResult 做 bounded cleanup，并通过 EventRetentionPolicy 传递 provider 需要共享的 retention 事实。Executor placement contract 只表达 claim/provider 共享事实和 decision evidence，不包含 remote worker service、EF mapping、Dashboard 或 multi-region routing 实现。

Business calendar 目前只提供最小 metadata；默认 runtime 在缺少 provider 时 fail closed，provider 接口、holiday engine、working-time policy 和 missing-calendar strategy 不在本包冻结。Sharding 目前只保留 IShardStore 与 Shard* provider SPI 值对象；planner / aggregator 是 runtime internal proof，不证明多节点正确性。

Direct enqueue 分片请求使用 EnqueueOptions.ShardCount，默认值为 1。ShardCount > 1 只表达应用请求固定数量分片；具体 planner / aggregator、child execution 创建和 parent aggregation 属于 runtime/provider 行为，不进入本包公开 plugin model。

Policy evaluation / budget / cost 只作为 Sparkdo.Scheduler runtime internal dry-run evidence，store schema migration 只作为 Sparkdo.Scheduler.Testing conformance proof。它们不替代真实写入路径的 provider 原子校验，不实现完整 PolicyDsl / tenant quota / rate limiter / billing authority，也不冻结为 Abstractions public API。

Freeze audit 要求

新增或移动 public 类型前先更新 src/scheduler/docs/public-api-freeze-audit.md，并标注为：

• stable authoring API
• stable result
• provider SPI
• adapter DTO
• premature governance/report

当前无优先 premature governance/report 候选可在不设计 provider / adapter 的情况下继续迁移。能留在 runtime report 的不应留在 Abstractions；能留在 Sparkdo.Scheduler.Testing 或 provider package 的不应进入 production runtime public surface。trace metric tag policy 已固定为 runtime report evidence，不再作为 TraceContextPolicy 的 public 配置项；business calendar 已收束为最小 schedule metadata，sharding planner / aggregator 已收束为 runtime internal proof。

新增顶层类型必须一类型一文件，并放入最接近其变更原因的目录；不要把多个公共类型重新聚合回单个大文件，也不要把 .cs 文件平铺在项目根目录。