Sparkdo.Scheduler 2.0.0-preview.2

Sparkdo.Scheduler

Sparkdo.Scheduler 是默认 runtime 包。当前已包含 SchedulerJobCatalog runtime catalog seam、DefaultScheduler direct enqueue / direct enqueue sharding / schedule once / schedule cron / manual trigger / cancel 路径、显式单轮 ExecutionRunner、descriptor-aware payload serializer seam、默认 JSON payload codec、默认 in-memory provider、异步 store 端口实现、executor placement claim evaluator、event retention cleanup、trace context snapshot、occurrence 去重、lease renew / stale recovery、startup gate、trigger runner 单轮执行、health/report/diagnostic snapshot、report schema compatibility、options provenance report、clock drift / SLO / runbook report evidence、默认 redaction、Sparkdo.Runtime.Instrumentation bridge、management query/command 最小面和 package asset handoff 的最小闭环。

Instrumentation/ 只保存 Scheduler signal taxonomy 和 runtime adapter bridge；Scheduler 只负责发 signal 和 metadata，不拥有观测后端。真正的 Activity、Meter、recorder、OpenTelemetry exporter、source filter 和 no-op 路径都属于 src/instrumentation，Scheduler 只通过 Sparkdo.Runtime.Instrumentation 把信号接过去。

默认 runtime DI 由 SparkdoSchedulerManifest 声明：默认 in-memory store 端口、SchedulerJobCatalog、JsonJobPayloadSerializer、SchedulerRuntimeState、IScheduler、显式 ExecutionRunner、SchedulerWorkerOptions、singleton SchedulerWorker，以及 SchedulerWorkerStartupTask / SchedulerWorkerShutdownTask lifecycle entry。Sparkdo.Scheduler.Compiler 在 Application role 生成 SparkdoSchedulerGeneratedContributions 与 SparkdoSchedulerBootstrapContribution；Polaris generated bootstrap 根据 Manifest 的 application-bootstrap-contribution extension 应用该 contribution，并以 TryAddEnumerable(...) 注册 IJobContributionProvider。默认 in-memory store 端口保持 scoped，但共享 singleton InMemorySchedulerState，因此不同 DI scope 中的 enqueue、runner 和 worker 能看到同一份单进程状态。Generic Host 入口是 Host.CreateDefaultBuilder(args).AddSparkdo()；应用可通过 Configure<SchedulerWorkerOptions>(options => options.Enabled = false) 关闭后台循环。后续 provider 包应替换 IExecutionQueue、IScheduleStore、IExecutorStore、IHistoryStore、IShardStore 和 ISchedulerStoreDiagnostics，不替换整个 Scheduler runtime。

内部结构

阶段 07 / 15 / 17 / 18 / 19 / 20 / 26 / 28 新增目录按 src/scheduler/docs/observability-management-map.md 执行。当前 07B 已实现 Health/、Reports/ 和 Diagnostics/ 的只读 runtime snapshot；07C 已实现 Instrumentation/ taxonomy 和默认 diagnostic redaction；15 已将 runtime signal 通过 Sparkdo.Runtime.Instrumentation 接入 src/instrumentation，Activity/Meter/recorder dispatcher 与 OpenTelemetry 注册仍属于 src/instrumentation；18 已补边界测试，防止 Scheduler 生产代码重写 Activity/Meter/OpenTelemetry/recorder/source filter；20 已将 Scheduler runtime signal 收束为调用 SparkdoInstrumentationMetadata.RuntimeAdapter(...) 通用 factory，不手写 RuntimeAdapter metadata。Scheduler 不维护任何自有 observability sink、recorder dispatcher 或 exporter。07D 已实现 Management/Queries、Management/Commands 和 Management/Results 的最小 runtime surface。阶段 13 在 Reports/ 中补齐 OptionsValidationReport 和 ConfigurationProvenance，阶段 16 在 Reports/ 中补齐 EventRetentionReport，阶段 17 在 Reports/ 中补齐 TraceContextReport，阶段 19 在 Reports/ 中补齐 ReportSchemaCompatibility，阶段 26 在 Reports/ / Health/ 中补齐 ClockDriftAudit、OperationalSloBurnRate 和 RunbookCatalog，阶段 28 在 Reports/ 中补齐 SchedulerEcosystemEvidence，用于把 package onboarding、generated contribution、runtime catalog、runtime state 和 worker activation 边界汇成一个审计入口。它们都用于 report evidence，不是 job authoring API。后续仍必须分开维护，不把 health/report/instrumentation signal/management/tracing 类型合并到一个大文件。

Cron occurrence 由 Sparkdo.Crontab 计算，当前只支持 fixed-offset / UTC 语义；CronOptionsSnapshot.TimeZoneId 显式传入时会 fail closed，后续再接入 time zone provider。

Abstractions/Stores 中的 store port 是正式 provider SPI，所有端口必须异步并接收 CancellationToken。IHistoryStore.CleanupAsync(...) 使用 bounded request/result 表达 retention cleanup，不要求 provider 一次删除全部 history，也不暴露 provider row。Abstractions/Placement 中的 placement contract 进入 IExecutionQueue.ClaimAsync(...) 边界，用于解释 accepted / rejected placement decision。Sparkdo.Scheduler 中的 InMemory* 类型是默认 provider implementation：它们可以被 generated DI 构造，也可以被外部 provider 通过 tryAdd 覆盖；其内部状态、row 和同步锁不是公共契约。SchedulerRuntimeSnapshotProvider、management service、trigger runner 和 DefaultScheduler 都通过 store 端口工作，不再直接穿透到内存 state。

Package Assets

Sparkdo.Scheduler nupkg 预期携带：

• lib/net10.0/Sparkdo.Scheduler.dll
• analyzers/dotnet/cs/Sparkdo.Scheduler.Compiler.dll

Runtime defaults 与 lifecycle 来自包内 typed Manifest；job provider 来自 consumer 编译期生成的 application bootstrap contribution。Compiler 同时生成 JobActivator 和 JobPayloadCodec delegate，让 ExecutionRunner 在显式 DI job service 缺失时仍能 AOT-safe 创建 job 实例，并通过应用声明的 JsonSerializerContext 做 JSON payload roundtrip；这不是 runtime assembly scanning 或完整 service auto-registration。

SchedulerEcosystemEvidence 使用 typed-manifest-generated-bootstrap 表示 package onboarding，使用 typed-manifest-runtime-defaults 表示默认注册来源。显式 worker lifecycle state 可记录上一轮低敏 outcome、trigger 数、lease recovery 数、cleanup code、executor registration 和 draining evidence。Package smoke 应断言 typed Manifest、generated bootstrap、Host lifecycle 与 runtime defaults 的真实 consumer 行为；未执行的 gate 不写成已通过。

阶段 28 的 public API freeze audit 见 src/scheduler/docs/public-api-freeze-audit.md。Sparkdo.Scheduler runtime 后续不能通过新增 report-only / governance-only Abstractions 类型来补设计缺口；policy/budget/cost 已降为 runtime internal evidence，store schema migration proof 已迁到 Sparkdo.Scheduler.Testing conformance，MetricTagPolicy 已降为 runtime-only 固定 report evidence，business calendar 已收束为最小 schedule metadata。sharding planner/aggregator 已迁出 public surface；阶段 31 只用 EnqueueOptions.ShardCount 支持 direct enqueue 的 in-memory single-process sharding execution，不公开 planner / aggregator plugin model。