@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/{db/index.ts → adapter/cloudflare/database.ts}

@@ -1,26 +1,28 @@
 import type { SqlTaggedTemplate } from "agents/chat";
 
 import { initializeSchema } from "./schema";
-import { SubmissionRepository } from "./submission.repo";
-import { ApprovalRepository } from "./approval.repo";
-import { ToolInteractionRepository } from "./interaction.repo";
-import { ToolSettlementRepository } from "./settlement.repo";
-import { RecoveryMilestoneRepository } from "./milestone.repo";
-import { ExtContextRepository } from "./ext-context.repo";
-import { MessageUiRepository } from "./message-ui.repo";
-import { SteerRepository } from "./steer.repo";
-import { RuntimeEventOutboxRepository } from "./runtime-event-outbox.repo";
-import { TelemetryOutboxRepository } from "./telemetry-outbox.repo";
-import { AgentToolRepository } from "./agent-tool.repo";
-import { SubmissionAdmissionRepository } from "./submission-admission.repo";
+import {
+  SubmissionAdmissionRepository,
+  SubmissionRepository,
+  SteerRepository,
+} from "../../submission";
+import {
+  AgentToolRepository,
+  ApprovalRepository,
+  ToolInteractionRepository,
+} from "../../tools";
+import { ExtContextRepository } from "../../context";
+import { MessageUiRepository } from "../../conversation";
+import {
+  RuntimeEventOutboxRepository,
+  TelemetryOutboxRepository,
+} from "../../telemetry";
 
 // 数据库术语以这里为准。
 // Submission 是一次可持久化的用户提交，从排队到终态都用同一个 submissionId 跟踪。
 // Approval 是某次工具调用的持久化审批记录，executionId 是对外决策时的主键。
 // Tool Interaction 是「结果由客户端提供」的工具调用的 park 记录，interactionId 是主键；
-// 它只回答还等不等得到响应，答案的权威副本仍是 Settlement。
-// Settlement 是工具调用的最终结果，同一 Submission 内用 toolCallId 防止重复落盘。
-// Recovery Milestone 是按 seq 重放的恢复事实，milestoneKey 用来去重。
+// 它保存人的回答，Harness Session 保存工具执行位置和最终 ToolResult。
 // Extension Context 是扩展按 label 保存的文本，不随清空聊天记录删除。
 // Message UI 是会话消息的用户界面补充数据，它由 Transcript 而不是 Turn 生命周期管理。
 // Agent Tool Run 是 Agents SDK 派发的子运行，唯一一张不归 Runtime 所有的表：SDK 建它、写它、清它，
@@ -28,26 +30,10 @@ import { SubmissionAdmissionRepository } from "./submission-admission.repo";
 // 是因为 SDK 没有公开父级侧的「还有没有子运行在跑」读法，而复制一份必然产生第二个真相源。
 // Repository 只把 Runtime 语义翻译成参数化 SQL，所有表都位于当前 Agent 实例自己的 Durable Object SQLite 存储中。
 // Transaction 指 Cloudflare transactionSync 包住的同步操作，回调抛错时整体回滚。
-export * from "./schema";
-export * from "./submission.repo";
-export * from "./approval.repo";
-export * from "./interaction.repo";
-export * from "./settlement.repo";
-export * from "./milestone.repo";
-export * from "./ext-context.repo";
-export * from "./message-ui.repo";
-export * from "./steer.repo";
-export * from "./runtime-event-outbox.repo";
-export * from "./telemetry-outbox.repo";
-export * from "./agent-tool.repo";
-export * from "./submission-admission.repo";
-
 export class RuntimeDatabase {
   readonly submissions: SubmissionRepository;
   readonly approvals: ApprovalRepository;
   readonly interactions: ToolInteractionRepository;
-  readonly settlements: ToolSettlementRepository;
-  readonly milestones: RecoveryMilestoneRepository;
   readonly extContext: ExtContextRepository;
   readonly messageUi: MessageUiRepository;
   readonly steers: SteerRepository;
@@ -63,11 +49,9 @@ export class RuntimeDatabase {
     private readonly sql: SqlTaggedTemplate,
     private readonly transact: <T>(fn: () => T) => T,
   ) {
-    this.submissions = new SubmissionRepository(sql);
+    this.submissions = new SubmissionRepository(sql, transact);
     this.approvals = new ApprovalRepository(sql);
     this.interactions = new ToolInteractionRepository(sql);
-    this.settlements = new ToolSettlementRepository(sql);
-    this.milestones = new RecoveryMilestoneRepository(sql);
     this.extContext = new ExtContextRepository(sql);
     this.messageUi = new MessageUiRepository(sql);
     this.steers = new SteerRepository(sql);
@@ -77,25 +61,6 @@ export class RuntimeDatabase {
     this.submissionAdmissions = new SubmissionAdmissionRepository(sql);
   }
 
-  /**
-   * 有未完成 Submission，且每一条都停在人机等待上。
-   *
-   * 换装配的忙碌闸门调用它。「停在等人」有两种形态：待决审批，和等客户端
-   * 投递结果的 Tool Interaction —— 两者都意味着没有模型请求在飞、没有工具
-   * 在执行，因此换掉能力语义是安全的。
-   *
-   * 注意它不是「存在待处理的人机等待」：只要有一条 Submission 正在真的执行，
-   * 整个判断就必须为假，否则会把执行中的 Turn 切成两套能力语义。
-   */
-  everyUnfinishedSubmissionParked(): boolean {
-    const unfinished = this.submissions.listUnfinishedIds();
-    if (unfinished.length === 0) return false;
-    return unfinished.every((submissionId) =>
-      this.approvals.listPendingForSubmission(submissionId).length > 0 ||
-      this.interactions.listPendingForSubmission(submissionId).length > 0
-    );
-  }
-
   // 在一个同步 SQLite 事务里运行一组读写。
   // Submission、Approval、Transcript 等需要一起成功或一起回滚时调用，回调不得返回 Promise。
   // 这里直接保留 transactionSync 的抛错回滚语义；待确认：当前泛型签名无法在类型层阻止 async 回调。
@@ -118,8 +83,6 @@ export class RuntimeDatabase {
     this.sql`DELETE FROM pi_submissions`;
     this.sql`DELETE FROM pi_approvals`;
     this.sql`DELETE FROM pi_tool_interactions`;
-    this.sql`DELETE FROM pi_tool_settlements`;
-    this.sql`DELETE FROM pi_recovery_milestones`;
     this.sql`DELETE FROM pi_telemetry_outbox`;
   }
 }

package/src/{runtime-agent.ts → adapter/cloudflare/define-agent.ts}

@@ -5,53 +5,53 @@ import {
   type ChatCapableAgentClass,
 } from "agents";
 import type { UIMessage } from "ai";
-import type { PiCanonicalTranscriptSnapshot } from "./pi/runtime-adapter";
+import type { PiCanonicalTranscriptSnapshot } from "../../conversation";
 import type {
   ApprovalDecision,
   ApprovalReceipt,
   MessageDelivery,
   MessageDispatchReceipt,
   SubmissionReceipt,
-} from "./kernel/receipts";
-import type { RuntimeState } from "./kernel/state";
+} from "../../submission";
+import type { RuntimeState } from "../../conversation";
 import type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
   TemporaryAgentLaunch,
-} from "./layers/orchestration/temporary-agent/core";
-import { TEMPORARY_AGENT_LAUNCH_KEY } from "./layers/orchestration/temporary-agent/core";
+} from "../../tools";
+import { TEMPORARY_AGENT_LAUNCH_KEY } from "../../tools";
 import {
   temporaryAgentExtensionIsSafe,
   temporaryAgentToolAllowed,
-} from "./layers/orchestration/temporary-agent/runner";
+} from "../../tools";
 import {
   EXECUTION_LEVELS,
   requiresExecutionApproval,
   type ExecutionLevel,
-} from "./lib/execution-level";
+} from "../../lib/execution-level";
 import {
   assembleRuntimeSnapshot,
   type RuntimeCandidate,
-} from "./runtime-assembler";
+} from "../../config";
 import type {
   ResolvedResources,
   ToolAssemblyResult,
-} from "./runtime-definition";
-import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
-import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
+} from "../../config";
+import type { RuntimeAssemblyView } from "../../config";
+import type { RuntimeConfigUpdateResult } from "../../config";
 import {
   logRuntimeLoadFailure,
   RUNTIME_LOAD_TIMEOUT_MS,
   withRuntimeLoadTimeout,
-} from "./kernel/runtime-load";
-import { AgentToolRuntimeKernel } from "./agent-tool-runtime";
+} from "../../config";
+import { AgentToolRuntimeKernel } from "./agent-tool";
 import type {
   RuntimeAgentConfigContext,
   RuntimeAgentPlanningContext,
   RuntimeAgentRole,
   RuntimeAgentToolResult,
-} from "./runtime-agent-context";
-import type { AgentTelemetryBinding } from "./telemetry/contract";
+} from "../../config";
+import type { AgentTelemetryBinding } from "../../telemetry";
 
 /**
  * 本文件把应用提供的 Config Definition 与 Planner 接到 Cloudflare Agent 生命周期。
@@ -70,7 +70,7 @@ export type {
   RuntimeAgentRole,
   RuntimeAgentToolResult,
   RuntimeAssemblyContext,
-} from "./runtime-agent-context";
+} from "../../config";
 
 /** Host 一次性准备的完整 Runtime 加载结果。 */
 export interface LoadedRuntime<Config> {
@@ -114,7 +114,7 @@ interface RuntimeAgentDefinitionBase<
   /** Prepare the optional telemetry consumer for this concrete Agent facet. */
   readonly telemetry?: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ) => AgentTelemetryBinding | undefined;
+  ) => AgentTelemetryBinding | undefined | Promise<AgentTelemetryBinding | undefined>;
 }
 
 export interface ReadonlyRuntimeAgentDefinition<
@@ -163,15 +163,6 @@ export interface RuntimeAgentControls {
     runtimeKey?: string,
     options?: { force?: boolean },
   ): Promise<void>;
-  /**
-   * 确保 Runtime 已加载，再请求 Kernel 刷新当前 Session Context。
-   *
-   * @remarks
-   * 业务侧在外部 Context 变更后调用，例如 Inbox 需要让已存在的聊天立即重读内容。
-   *
-   * 待确认：当前 `refreshContext` 只检查 Snapshot 已安装，没有重新读取 Context 或刷新缓存。
-   */
-  refreshMemoryContext(): Promise<void>;
   /**
    * Read the Runtime Snapshot currently installed on this Session facet.
    *
@@ -271,7 +262,12 @@ export interface RuntimeAgentControls {
    */
   submitScheduledPrompt(
     prompt: string,
-    opts?: { idempotencyKey?: string },
+    opts?: {
+      idempotencyKey?: string;
+      scheduledMaxExecutionLevel?: import("../../lib/execution-level").ExecutionLevel;
+      /** @deprecated Retained for rolling upgrades; ignored by Runtime. */
+      unattendedExecutionGrant?: import("../../submission").RuntimeUnattendedExecutionGrant;
+    },
   ): Promise<SubmissionReceipt>;
   /**
    * 按提交编号查询当前处理状态。
@@ -318,7 +314,7 @@ export interface RuntimeAgentConfigControls<Command, Change> {
 /** Type-only Host extension seam implemented by AgentRuntimeKernel. */
 declare class RuntimeAgentHostSeam {
   protected prepareToolInteractionResponse(
-    input: import("./runtime").ToolInteractionResponsePreparation,
+    input: import("./agent").ToolInteractionResponsePreparation,
   ): Promise<unknown | null>;
 }
 
@@ -415,14 +411,14 @@ export function defineRuntimeAgent<
     | MutableRuntimeAgentDefinition<Env, Config, Command, Change>
     | ReadonlyRuntimeAgentDefinition<Env, Config>,
 ): RuntimeAgentClass<Env, Command, Change> {
-  const resolveDefinitionTelemetry = (
+  const resolveDefinitionTelemetry = async (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ): AgentTelemetryBinding | undefined => {
+  ): Promise<AgentTelemetryBinding | undefined> => {
     const telemetry = definition.telemetry;
     if (!telemetry) return undefined;
-    return (telemetry as (
+    return await (telemetry as (
       context: RuntimeAgentPlanningContext<Env, Command, Change>,
-    ) => AgentTelemetryBinding | undefined)(context);
+    ) => AgentTelemetryBinding | undefined | Promise<AgentTelemetryBinding | undefined>)(context);
   };
 
   const GeneratedRuntimeAgent = {
@@ -449,6 +445,10 @@ export function defineRuntimeAgent<
         return this.ensureConfig();
       }
 
+      protected override ensureRuntimeVersion(runtimeKey: string): Promise<void> {
+        return this.ensureConfig(runtimeKey);
+      }
+
       protected async prepareRuntimeForSubmission(submissionId: string): Promise<void> {
         const beforeSubmission = definition.beforeSubmission as RuntimeAgentDefinitionBase<Env, Config, Command, Change>["beforeSubmission"];
         try {
@@ -502,14 +502,6 @@ export function defineRuntimeAgent<
         }
       }
 
-      // 作用：确保 Runtime 可用后请求 Kernel 刷新 Session Context。
-      // 调用：Inbox 等 RPC 调用方在外部 Context 变更后调用。
-      // 待确认：当前 Kernel 的 `refreshContext` 只检查 Snapshot，并未执行实际刷新。
-      async refreshMemoryContext(): Promise<void> {
-        await this.ensureRuntimeReady();
-        await this.refreshContext();
-      }
-
       async getRuntimeAssembly(): Promise<RuntimeAssemblyView> {
         await this.ensureRuntimeReady();
         return this.readRuntimeAssembly();
@@ -648,7 +640,7 @@ export function defineRuntimeAgent<
             let resources = loaded.resources;
             let commitGuard = loaded.commitGuard;
             if (!this.telemetryResolved) {
-              this.resolvedTelemetry = resolveDefinitionTelemetry(context);
+              this.resolvedTelemetry = await resolveDefinitionTelemetry(context);
               this.telemetryResolved = true;
             }
             const telemetry = this.resolvedTelemetry;
@@ -666,7 +658,10 @@ export function defineRuntimeAgent<
               ...(telemetry ? { telemetry } : {}),
             });
 
-            await this.initCandidate(candidate);
+            await this.initCandidate({
+              ...candidate,
+              runtimeKey: resolvedRuntimeKey,
+            });
             this.hasLoadedRuntime = true;
             this.loadedRuntimeKey = resolvedRuntimeKey;
             this.runtimeLoad.complete();

package/src/adapter/cloudflare/dynamic-worker-observability.ts

@@ -1,4 +1,4 @@
-import type { RuntimePlatformPort } from "../../kernel/bindings";
+import type { RuntimePlatformPort } from "../../config/ports";
 import { WorkerEntrypoint } from "cloudflare:workers";
 
 export type DynamicWorkerObservation = {

package/src/adapter/cloudflare/index.ts

@@ -23,8 +23,26 @@ export {
 export {
   isValidTimeZone,
   nextCronOccurrence,
+  wallTimeInstants,
   zoneOffsetMs,
 } from "./scheduling/zoned-cron";
+export {
+  DEFAULT_LATENESS_WINDOW_MS,
+  isWithinLatenessWindow,
+  nextScheduledOccurrence,
+  resolveScheduleOccurrences,
+  toScheduleRuleSpec,
+  validateScheduleRuleSpec,
+  type LocalScheduleTrigger,
+  type ScheduledOccurrence,
+  type ScheduleOccurrence,
+  type ScheduleOccurrenceResolution,
+  type ScheduleRuleError,
+  type ScheduleRuleErrorCode,
+  type ScheduleRuleSpec,
+  type ScheduleSkipReason,
+  type SkippedOccurrence,
+} from "./scheduling/schedule-rule";
 
 export {
   CloudflareSandboxAdapter,

package/src/adapter/cloudflare/resources/runtime-resources.ts

@@ -1,7 +1,7 @@
-import type { RuntimeDegradation } from "../../../kernel/degradation";
-import type { RuntimeExtensionConfig } from "../../../kernel/extensions";
-import { withRuntimeLoadTimeout } from "../../../kernel/runtime-load";
-import type { RuntimeExtensionContribution } from "../../../runtime-definition";
+import type { RuntimeDegradation } from "../../../config/degradation";
+import type { RuntimeExtensionConfig } from "../../../context/extension/contracts";
+import { withRuntimeLoadTimeout } from "../../../config/runtime-load";
+import type { RuntimeExtensionContribution } from "../../../config/definition";
 export { createR2SkillSource } from "./r2-skill-source";
 
 export interface CloudflareRuntimeExtensionSource {

package/src/adapter/cloudflare/sandbox/adapter.ts

@@ -24,7 +24,7 @@ import {
   type SandboxSyncFailure,
   type SandboxSyncResult,
   type WorkspacePort,
-} from "../../../kernel/bindings";
+} from "../../../config/ports";
 import type {
   WorkspaceFileVersion,
   WorkspacePublishPort,

package/src/adapter/cloudflare/scheduling/schedule-rule.ts

@@ -0,0 +1,322 @@
+import type {
+  LocalScheduleRule,
+  ScheduleSpec,
+} from "../../../submission/contracts";
+import { isValidTimeZone, wallTimeInstants, zoneOffsetMs } from "./zoned-cron";
+
+const DAY_MS = 86_400_000;
+const HOUR_MS = 3_600_000;
+const MINUTE_MS = 60_000;
+/** 扫描上限:每日/每周规则一定在 7 天内出现,这里只兜底防止坏输入空转。 */
+const MAX_SCAN_DAYS = 366 * 5;
+
+/**
+ * 宿主允许在计划时点之后多久仍可启动该轮次。宿主可覆盖,
+ * 通用模块只把它当作可参数化的迟到窗口,不承载套餐或任务策略。
+ */
+export const DEFAULT_LATENESS_WINDOW_MS = 5 * MINUTE_MS;
+
+export type ScheduleSkipReason = "dst_missing_local_time";
+
+/** 一个真实可执行的本地时间轮次。 */
+export interface ScheduledOccurrence {
+  kind: "scheduled";
+  /** 跨重算、重启都稳定的轮次身份,供宿主做幂等键。 */
+  occurrenceId: string;
+  /** 计划执行的 UTC 瞬时。 */
+  scheduledAt: number;
+  /** 任务时区下的本地日期 `YYYY-MM-DD`。 */
+  localDate: string;
+  /** 任务时区下的本地钟点 `HH:mm`。 */
+  localTime: string;
+  /** 含边界的最迟可启动瞬时 = `scheduledAt + latenessWindowMs`。 */
+  latestStartAt: number;
+}
+
+/** 因夏令时缺失钟点而被跳过的轮次;没有可执行瞬时,只留身份与原因。 */
+export interface SkippedOccurrence {
+  kind: "skipped";
+  occurrenceId: string;
+  localDate: string;
+  localTime: string;
+  reason: ScheduleSkipReason;
+}
+
+export type ScheduleOccurrence = ScheduledOccurrence | SkippedOccurrence;
+
+/** 一条按任务时区解释的当地时间规则及其生效窗口。 */
+export interface ScheduleRuleSpec {
+  rule: LocalScheduleRule;
+  /** IANA 时区名,如 `Asia/Shanghai`;绝不退化成固定 UTC offset。 */
+  timeZone: string;
+  /** 含当天的最早生效本地日期 `YYYY-MM-DD`。 */
+  startDate?: string;
+  /** 含当天的最后生效本地日期 `YYYY-MM-DD`。 */
+  endDate?: string;
+  /** 覆盖默认迟到窗口。 */
+  latenessWindowMs?: number;
+}
+
+/** `ScheduleSpec.trigger` 里 `local` 变体的形状。 */
+export type LocalScheduleTrigger = Extract<
+  ScheduleSpec["trigger"],
+  { kind: "local" }
+>;
+
+/**
+ * 把合同的 `local` 触发条件投影成时间规则计算规格。
+ *
+ * 宿主与路由共用同一映射,避免各自拼一份 `startDate`/`endDate`,改合同字段时漏改。
+ */
+export function toScheduleRuleSpec(
+  trigger: LocalScheduleTrigger,
+  timeZone: string,
+): ScheduleRuleSpec {
+  return {
+    rule: trigger.rule,
+    timeZone,
+    ...(trigger.startDate ? { startDate: trigger.startDate } : {}),
+    ...(trigger.endDate ? { endDate: trigger.endDate } : {}),
+  };
+}
+
+export type ScheduleRuleErrorCode =
+  | "invalid_rule"
+  | "invalid_time_zone"
+  | "invalid_date"
+  | "invalid_time"
+  | "empty_weekdays"
+  | "invalid_weekday"
+  | "invalid_window"
+  | "invalid_limit"
+  | "no_future_occurrence";
+
+export interface ScheduleRuleError {
+  code: ScheduleRuleErrorCode;
+  message: string;
+}
+
+export type ScheduleOccurrenceResolution =
+  | { ok: true; occurrences: ScheduleOccurrence[] }
+  | { ok: false; error: ScheduleRuleError };
+
+interface LocalClock {
+  hour: number;
+  minute: number;
+}
+
+/** 校验规则形状与时区,不判断是否存在未来时点。 */
+export function validateScheduleRuleSpec(
+  spec: ScheduleRuleSpec,
+): ScheduleRuleError | null {
+  if (typeof spec.timeZone !== "string" || !isValidTimeZone(spec.timeZone)) {
+    return { code: "invalid_time_zone", message: `未知时区:${spec.timeZone}` };
+  }
+  const rule = spec.rule as unknown;
+  if (!isRecord(rule) ||
+    (rule.kind !== "once" && rule.kind !== "daily" && rule.kind !== "weekly")) {
+    return { code: "invalid_rule", message: "不支持的当地时间规则" };
+  }
+  const time = typeof rule.time === "string" ? parseTime(rule.time) : null;
+  if (!time) {
+    return { code: "invalid_time", message: `非法钟点:${String(rule.time ?? "")}` };
+  }
+  if (rule.kind === "once" &&
+    (typeof rule.date !== "string" || parseDate(rule.date) === null)) {
+    return { code: "invalid_date", message: `非法日期:${String(rule.date ?? "")}` };
+  }
+  if (rule.kind === "weekly") {
+    if (!Array.isArray(rule.weekdays) || rule.weekdays.length === 0) {
+      if (Array.isArray(rule.weekdays)) {
+        return { code: "empty_weekdays", message: "每周规则至少需要一个星期" };
+      }
+      return { code: "invalid_weekday", message: "星期必须是数字数组" };
+    }
+    if (
+      rule.weekdays.some(
+        (weekday) => !Number.isInteger(weekday) || weekday < 0 || weekday > 6,
+      )
+    ) {
+      return {
+        code: "invalid_weekday",
+        message: `非法星期:${rule.weekdays.join(",")}`,
+      };
+    }
+  }
+  const start = optionalDate(spec.startDate);
+  if (spec.startDate !== undefined && start === null) {
+    return { code: "invalid_date", message: `非法开始日期:${spec.startDate}` };
+  }
+  const end = optionalDate(spec.endDate);
+  if (spec.endDate !== undefined && end === null) {
+    return { code: "invalid_date", message: `非法结束日期:${spec.endDate}` };
+  }
+  if (start !== null && end !== null && end < start) {
+    return { code: "invalid_window", message: "结束日期不能早于开始日期" };
+  }
+  return null;
+}
+
+/**
+ * 从 `after`(UTC 瞬时,不含)起枚举轮次,含被跳过的缺失钟点。
+ *
+ * 预览、下一轮计算和恢复枚举都走这里,保证三者语义一致;输出为空时返回可识别的
+ * `no_future_occurrence`,而不是伪造一个执行时间。
+ */
+export function resolveScheduleOccurrences(
+  spec: ScheduleRuleSpec,
+  options: { after: number; limit: number },
+): ScheduleOccurrenceResolution {
+  const error = validateScheduleRuleSpec(spec);
+  if (error) return { ok: false, error };
+  if (!Number.isSafeInteger(options.limit) || options.limit <= 0) {
+    return {
+      ok: false,
+      error: { code: "invalid_limit", message: "轮次数量必须是正整数" },
+    };
+  }
+  const occurrences = enumerate(spec, options.after, options.limit);
+  if (occurrences.length === 0) {
+    return {
+      ok: false,
+      error: {
+        code: "no_future_occurrence",
+        message: "该规则在给定时间之后没有有效执行时点",
+      },
+    };
+  }
+  return { ok: true, occurrences };
+}
+
+/** 下一个可执行瞬时;缺失钟点被跳过,不伪造、不顺延补跑。 */
+export function nextScheduledOccurrence(
+  spec: ScheduleRuleSpec,
+  after: number,
+): ScheduledOccurrence | null {
+  if (validateScheduleRuleSpec(spec) !== null) return null;
+  for (let limit = 1; limit <= 512; limit *= 2) {
+    const occurrences = enumerate(spec, after, limit);
+    const scheduled = occurrences.find(
+      (occurrence): occurrence is ScheduledOccurrence =>
+        occurrence.kind === "scheduled",
+    );
+    if (scheduled) return scheduled;
+    if (occurrences.length < limit) return null;
+  }
+  return null;
+}
+
+/** 含边界判断某个已计划轮次是否仍在迟到窗口内。 */
+export function isWithinLatenessWindow(
+  occurrence: ScheduledOccurrence,
+  now: number,
+): boolean {
+  return now >= occurrence.scheduledAt && now <= occurrence.latestStartAt;
+}
+
+function enumerate(
+  spec: ScheduleRuleSpec,
+  after: number,
+  limit: number,
+): ScheduleOccurrence[] {
+  const time = parseTime(spec.rule.time);
+  if (!time) return [];
+  const windowMs = spec.latenessWindowMs ?? DEFAULT_LATENESS_WINDOW_MS;
+  const wallAfter = after + zoneOffsetMs(after, spec.timeZone);
+  const dayOfAfter = Math.floor(wallAfter / DAY_MS) * DAY_MS;
+  const startDay = optionalDate(spec.startDate) ?? dayOfAfter;
+  const endDay = optionalDate(spec.endDate);
+  const occurrences: ScheduleOccurrence[] = [];
+
+  const onceDay = spec.rule.kind === "once" ? parseDate(spec.rule.date) : null;
+  // 一次性规则直接跳到目标日期，不能让重复规则的扫描保险上限拒绝远期任务。
+  let day = Math.max(startDay, dayOfAfter, onceDay ?? Number.NEGATIVE_INFINITY);
+  const maxScanDays = onceDay === null ? MAX_SCAN_DAYS : 0;
+  for (let scanned = 0; scanned <= maxScanDays; scanned += 1, day += DAY_MS) {
+    if (endDay !== null && day > endDay) break;
+    if (!matchesRule(spec.rule, day)) continue;
+
+    const wall = day + time.hour * HOUR_MS + time.minute * MINUTE_MS;
+    const localDate = formatDate(day);
+    const localTime = formatTime(time);
+    const occurrenceId = `${localDate}T${localTime}`;
+    const instants = wallTimeInstants(wall, spec.timeZone);
+    if (instants.length === 0) {
+      // 拨快抹掉的钟点:没有可执行瞬时,只在游标之后才作为跳过轮次报告。
+      if (wall <= wallAfter) continue;
+      occurrences.push({
+        kind: "skipped",
+        occurrenceId,
+        localDate,
+        localTime,
+        reason: "dst_missing_local_time",
+      });
+    } else {
+      const scheduledAt = instants[0];
+      if (scheduledAt <= after) continue;
+      occurrences.push({
+        kind: "scheduled",
+        occurrenceId,
+        scheduledAt,
+        localDate,
+        localTime,
+        latestStartAt: scheduledAt + windowMs,
+      });
+    }
+    if (occurrences.length >= limit) break;
+  }
+  return occurrences;
+}
+
+function matchesRule(rule: LocalScheduleRule, day: number): boolean {
+  switch (rule.kind) {
+    case "once":
+      return day === parseDate(rule.date);
+    case "daily":
+      return true;
+    case "weekly":
+      return rule.weekdays.includes(new Date(day).getUTCDay());
+  }
+}
+
+function parseTime(value: string): LocalClock | null {
+  const match = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(value);
+  if (!match) return null;
+  return { hour: Number(match[1]), minute: Number(match[2]) };
+}
+
+function formatTime({ hour, minute }: LocalClock): string {
+  return `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
+}
+
+/** `YYYY-MM-DD` → UTC 零点毫秒;非法日历日期返回 null。 */
+function parseDate(value: string): number | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const ms = Date.UTC(year, month - 1, day);
+  const date = new Date(ms);
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    return null;
+  }
+  return ms;
+}
+
+function optionalDate(value: string | undefined): number | null {
+  if (value === undefined) return null;
+  return parseDate(value);
+}
+
+function formatDate(day: number): string {
+  return new Date(day).toISOString().slice(0, 10);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}