@stigmer/server 3.14.0-dev.20260910084630

package/src/temporal/schedule/syncer.ts

@@ -0,0 +1,208 @@
+/**
+ * The Syncer — ports pkg/domain/schedule/temporal/syncer.go: converges one
+ * Schedule resource's Temporal artifact to its desired state and records
+ * the result on the resource's status. The ONE arming/teardown authority,
+ * shared by the write-path steps, the reconciliation pass, and the tick's
+ * next-fire refresh.
+ *
+ * The client arrives through a provider, not a field: the server hot-swaps
+ * its Temporal client on reconnect (src/temporal/manager.ts), and a
+ * component holding a stale client silently dies after the first blip.
+ * Reading through the provider on every call makes that entire bug class
+ * unrepresentable here.
+ *
+ * Status writes go through store.updateResource — the OSS equivalent of
+ * the cloud's targeted leaf patches (DD-015 D-C): SQLite stores one
+ * protobuf blob, so the atomic read-modify-write under the store's write
+ * lock is what keeps a concurrent `stigmer apply` from clobbering the
+ * stamp (and vice versa). status.next_fire_at is the contract's arming
+ * witness: stamped from Temporal's own answer when armed, cleared when the
+ * artifact is paused, absent while nothing has converged.
+ *
+ * Go's Clock/Syncer also carries a Trigger method (the DD-014
+ * artifact-trigger lane); DD-017 D-5 rewired the trigger RPC to the
+ * direct-run path and left it with zero production callers, so this port
+ * deliberately omits it (sub-project decision 2, owner-ratified at the
+ * plan gate; disclosed in the PR register).
+ */
+import type { Client, ScheduleDescription } from "@temporalio/client";
+import { ScheduleAlreadyRunning, ScheduleNotFoundError } from "@temporalio/client";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+import type { ScheduleArtifact } from "./artifact.js";
+import { desiredPaused, note } from "./artifact.js";
+import { artifactId } from "./names.js";
+import { bumpStatusAudit, ensureStatus } from "./status-writes.js";
+
+/**
+ * The syncer's answer when no Temporal client exists right now (Go
+ * ErrTemporalUnavailable). Callers on the write path treat it as "converge
+ * later" (arming is best-effort — DD-015 D-A).
+ */
+export class TemporalUnavailableError extends Error {
+  constructor() {
+    super("temporal is not connected");
+    this.name = "TemporalUnavailableError";
+  }
+}
+
+export class ScheduleSyncer {
+  constructor(
+    /** May return undefined (Temporal down or never connected). */
+    private readonly clientProvider: () => Client | undefined,
+    private readonly store: Store,
+    private readonly artifact: ScheduleArtifact,
+    private readonly logger: Logger,
+  ) {}
+
+  /**
+   * Creates or updates the resource's artifact to the desired state, then
+   * stamps status.next_fire_at from Temporal's answer. Returns the stamped
+   * time (undefined when the artifact is paused) so write paths can mirror
+   * it into their response state (Go EnsureAndRecord).
+   */
+  async ensureAndRecord(schedule: Schedule): Promise<Date | undefined> {
+    const client = this.clientProvider();
+    if (client === undefined) {
+      throw new TemporalUnavailableError();
+    }
+
+    const resourceId = schedule.metadata?.id ?? "";
+    const id = artifactId(resourceId);
+
+    try {
+      await client.schedule.create(this.artifact.createOptions(schedule));
+      this.logger.info("Created schedule artifact", {
+        artifact_id: id,
+        note: note(schedule),
+        paused: desiredPaused(schedule),
+      });
+    } catch (error) {
+      if (!(error instanceof ScheduleAlreadyRunning)) {
+        throw new Error(`create schedule artifact ${id}: ${message(error)}`, {
+          cause: error,
+        });
+      }
+      // Create-or-update convergence: rewrite the existing artifact to the
+      // complete desired state. A lost race between two writers is benign —
+      // both write the same desired state.
+      try {
+        await client.schedule
+          .getHandle(id)
+          .update((previous: ScheduleDescription) =>
+            this.artifact.applyDesiredState(previous, schedule),
+          );
+      } catch (updateError) {
+        throw new Error(
+          `update schedule artifact ${id}: ${message(updateError)}`,
+          { cause: updateError },
+        );
+      }
+      this.logger.info("Updated schedule artifact", {
+        artifact_id: id,
+        note: note(schedule),
+        paused: desiredPaused(schedule),
+      });
+    }
+
+    return this.recordNextFireAt(schedule);
+  }
+
+  /**
+   * Reads the next fire time from the LIVE artifact — Temporal's answer is
+   * authoritative (it accounts for the catch-up window; the platform
+   * computes nothing). Undefined while paused, per status.next_fire_at's
+   * contract (Go PeekNextFireAt).
+   */
+  async peekNextFireAt(schedule: Schedule): Promise<Date | undefined> {
+    if (desiredPaused(schedule)) {
+      return undefined;
+    }
+    const client = this.clientProvider();
+    if (client === undefined) {
+      throw new TemporalUnavailableError();
+    }
+    let description: ScheduleDescription;
+    try {
+      description = await client.schedule
+        .getHandle(artifactId(schedule.metadata?.id ?? ""))
+        .describe();
+    } catch (error) {
+      throw new Error(`describe schedule artifact: ${message(error)}`, {
+        cause: error,
+      });
+    }
+    return description.info.nextActionTimes[0];
+  }
+
+  /**
+   * Deletes the resource's artifact. Not-found is success — delete is
+   * idempotent from the platform's point of view even though Temporal's is
+   * not (Go Teardown).
+   */
+  async teardown(resourceId: string): Promise<void> {
+    const client = this.clientProvider();
+    if (client === undefined) {
+      throw new TemporalUnavailableError();
+    }
+    const id = artifactId(resourceId);
+    try {
+      await client.schedule.getHandle(id).delete();
+    } catch (error) {
+      if (error instanceof ScheduleNotFoundError) {
+        this.logger.info("Schedule artifact already gone", { artifact_id: id });
+        return;
+      }
+      throw new Error(`delete schedule artifact ${id}: ${message(error)}`, {
+        cause: error,
+      });
+    }
+    this.logger.info("Deleted schedule artifact", { artifact_id: id });
+  }
+
+  /**
+   * Stamps status.next_fire_at from peekNextFireAt onto the LIVE row
+   * (updateResource re-reads inside the lock — the stamp can never
+   * resurrect a stale snapshot of the rest of status). Go recordNextFireAt.
+   */
+  private async recordNextFireAt(schedule: Schedule): Promise<Date | undefined> {
+    const nextFireAt = await this.peekNextFireAt(schedule);
+
+    try {
+      await this.store.updateResource(
+        ApiResourceKind.schedule,
+        schedule.metadata?.id ?? "",
+        ScheduleSchema,
+        (live) => {
+          const status = ensureStatus(live);
+          status.nextFireAt =
+            nextFireAt === undefined ? undefined : timestampFromDate(nextFireAt);
+          bumpStatusAudit(status);
+        },
+      );
+    } catch (error) {
+      if (error instanceof ResourceNotFoundError) {
+        // Deleted between arm and stamp: the orphaned artifact is harmless
+        // (revalidation no-ops it) and the reconciliation pass reaps it.
+        this.logger.info(
+          "Schedule row gone before next_fire_at stamp — skipping",
+          { schedule_id: schedule.metadata?.id ?? "" },
+        );
+        return nextFireAt;
+      }
+      throw new Error(`stamp next_fire_at: ${message(error)}`, { cause: error });
+    }
+    return nextFireAt;
+  }
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/temporal/schedule/worker.ts

@@ -0,0 +1,81 @@
+/**
+ * The schedule-clock worker factory — ports the registration half of
+ * pkg/domain/schedule/temporal/worker_config.go.
+ *
+ * The tick runs on its own queue (schedule_stigmer): since a tick SPANS
+ * its run, a burst of long-tracking ticks must never starve the
+ * agent-execution queue's workers — and vice versa.
+ *
+ * The worker is created by the Temporal manager's factory list, which also
+ * RE-creates it on every reconnect. Components that merely call Temporal
+ * (the syncer, the reconciler) survive reconnects by reading the client
+ * through a provider; the worker is the one piece that must genuinely be
+ * rebuilt, because a worker is bound to the connection it was created
+ * with.
+ *
+ * The tick workflow registers under its byte-pinned slash type via the
+ * barrel's arbitrary export name (workflows/index.ts — Go's explicit
+ * RegisterWorkflowWithOptions{Name: TickWorkflowType} twin); the five
+ * activities register under their slash names as the activities object's
+ * keys.
+ */
+import type { Logger } from "../../boot/logger.js";
+import type { Store } from "../../store/interface.js";
+import type { WorkerFactory } from "../manager.js";
+import { resolveWorkflowSource } from "../workflow-source.js";
+import { createScheduleTickActivities } from "./activities.js";
+import type { ScheduleTemporalConfig } from "./config.js";
+import type { RunStarter } from "./run-starter.js";
+import type { ScheduleSyncer } from "./syncer.js";
+
+export interface ScheduleWorkerDeps {
+  readonly store: Store;
+  readonly config: ScheduleTemporalConfig;
+  readonly syncer: ScheduleSyncer;
+  readonly runStarter: RunStarter;
+  readonly logger: Logger;
+}
+
+export function newScheduleWorkerFactory(
+  deps: ScheduleWorkerDeps,
+): WorkerFactory {
+  return async ({ createWorker }) => {
+    const activities = createScheduleTickActivities({
+      store: deps.store,
+      config: deps.config,
+      syncer: deps.syncer,
+      runStarter: deps.runStarter,
+      logger: deps.logger,
+    });
+
+    const workflowSource = resolveWorkflowSource({
+      workflowsEntryCandidates: [
+        // Compiled dist (how conformance and the CLI boot the server).
+        new URL("./workflows/index.js", import.meta.url),
+        // The tsx dev loop runs from src/ — the SDK bundler compiles TS.
+        new URL("./workflows/index.ts", import.meta.url),
+      ],
+      prebuiltSibling: new URL(
+        "./workflow-bundle-schedule.js",
+        import.meta.url,
+      ),
+    });
+
+    deps.logger.info("Creating schedule-clock Temporal worker", {
+      queue: deps.config.stigmerQueue,
+      workflow_source: workflowSource.kind,
+    });
+
+    // Connection, namespace, and the decode-only codec chain are the
+    // capability's concern (manager.ts's choke-point note) — the factory
+    // decides only queue, activities, and workflow source.
+    return createWorker({
+      taskQueue: deps.config.stigmerQueue,
+      activities,
+      workflows:
+        workflowSource.kind === "prebuilt"
+          ? { workflowBundle: { codePath: workflowSource.codePath } }
+          : { workflowsPath: workflowSource.workflowsPath },
+    });
+  };
+}

package/src/temporal/schedule/workflows/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Workflow barrel — the entry point for Temporal's workflow bundler (the
+ * agentexecution precedent). ES2022 arbitrary module export names map the
+ * TypeScript function to the slash-delimited, byte-pinned workflow type
+ * the artifact's baked action starts ("schedule/tick", ../names.ts).
+ *
+ * WORKFLOW-BUNDLE IMPORT DISCIPLINE: everything reachable from this module
+ * runs in the deterministic sandbox — no node built-ins, no
+ * store/transport imports (see tick.ts's header).
+ */
+export { tick as "schedule/tick" } from "./tick.js";

package/src/temporal/schedule/workflows/tick.ts

@@ -0,0 +1,394 @@
+/**
+ * The tick workflow — ports pkg/domain/schedule/temporal/tick_workflow.go:
+ * one schedule fire, spanning its run (DD-013 via DD-015): record the
+ * fire, start the run, poll it to a terminal phase, record the verdict.
+ * Spanning is what makes the artifact's overlap SKIP genuinely mean "never
+ * start a run while the last is active", and the verdict is what feeds the
+ * failure streak behind the platform auto-pause.
+ *
+ * WHY A TIMER-DRIVEN POLL AND NOT THE CALLBACK TOKEN — read before
+ * "fixing" this. The platform already uses async activity completion for
+ * call:agent, so the token is the tempting shape here too. It loses on
+ * grounds that are edition-neutral (DD-015 D-E): the token cannot be
+ * re-armed after a create-then-crash, and its completion fire is
+ * best-effort — two silent-hang modes on a surface where a hang is a
+ * silenced reminder. The poll holds no worker thread (the workflow is
+ * dormant between polls; each poll is a millisecond activity), is bounded
+ * twice (budget + MAX_TRACKING_CYCLES), and keeps ONE verdict matrix
+ * across both editions.
+ *
+ * FORWARD CONSTRAINT: ticks live for minutes-to-an-hour once tracking is
+ * real, and OSS releases cut every 1-3 days — an in-flight tick WILL
+ * straddle a binary upgrade. Any behavioral change to this workflow body
+ * must be gated with patched()/deprecatePatch() (OD-6 discipline), and the
+ * replay gate (__tests__/replay.test.ts) must stay green against the
+ * committed histories.
+ *
+ * ERROR POSTURE (the #18 panel lesson, applied from day one): Go's
+ * `return err` fails the WORKFLOW EXECUTION; a plain thrown Error in the
+ * TS sandbox fails only the workflow TASK and retries forever. Every Go
+ * error return is therefore an ApplicationFailure here. Cancellation
+ * (sleep throwing CancelledFailure) propagates untouched — Go's
+ * workflow.Sleep error return, same terminal outcome.
+ *
+ * WORKFLOW-BUNDLE IMPORT DISCIPLINE: this module runs in the deterministic
+ * sandbox — imports are limited to @temporalio/workflow, @temporalio/common,
+ * and the pure names module.
+ */
+import {
+  ApplicationFailure,
+  isCancellation,
+  proxyActivities,
+  sleep,
+  workflowInfo,
+  log,
+} from "@temporalio/workflow";
+import {
+  SearchAttributeType,
+  defineSearchAttributeKey,
+} from "@temporalio/common";
+
+import {
+  FAILURE_RUN_FAILED,
+  FAILURE_RUN_TIMED_OUT,
+  FAILURE_START_FAILED,
+  PHASE_COMPLETED,
+  PHASE_GONE,
+  PHASE_RUNNING,
+  RECORD_FAILED_RUN_ACTIVITY_NAME,
+  RECORD_SUCCESSFUL_RUN_ACTIVITY_NAME,
+  RECORD_TICK_ACTIVITY_NAME,
+  POLL_EXECUTION_PHASE_ACTIVITY_NAME,
+  RUN_ALREADY_STARTED,
+  RUN_REFUSED,
+  RUN_SKIPPED,
+  RUN_STARTED,
+  RUN_TARGET_MISSING,
+  START_SCHEDULED_RUN_ACTIVITY_NAME,
+  TICK_FIRED,
+  artifactId,
+  type FailureRecorded,
+  type RunPhase,
+  type RunStart,
+  type ScheduleTickActivities,
+} from "../names.js";
+
+/**
+ * The tracking loop's code-level backstop, on top of the per-fire budget:
+ * 240 polls at the capped backoff is ~3.9 hours and ~1,200 history
+ * events — the loop can never outgrow a workflow history even if a budget
+ * is misconfigured (Go MaxTrackingCycles; exported so the bound test can
+ * assert it).
+ */
+export const MAX_TRACKING_CYCLES = 240;
+
+/**
+ * The nominal fire time Temporal stamps on every schedule-started
+ * workflow — tier one of the nominal-time derivation (present on cron
+ * fires AND manual triggers alike; Go scheduledStartTimeKey).
+ */
+const SCHEDULED_START_TIME_KEY = defineSearchAttributeKey(
+  "TemporalScheduledStartTime",
+  SearchAttributeType.DATETIME,
+);
+
+// The three activity-option contexts (Go tick_workflow.go). Record stub:
+// short idempotent status writes, retried freely.
+const recordActivities = proxyActivities<ScheduleTickActivities>({
+  startToCloseTimeout: "30 seconds",
+  retry: {
+    maximumAttempts: 3,
+    initialInterval: "5 seconds",
+    backoffCoefficient: 2.0,
+  },
+});
+// Run-start stub: enters the full create pipeline (session, context,
+// workflow start) — minutes-scale timeout, still retried (the
+// deterministic execution name absorbs retries).
+const startActivities = proxyActivities<ScheduleTickActivities>({
+  startToCloseTimeout: "3 minutes",
+  retry: {
+    maximumAttempts: 3,
+    initialInterval: "5 seconds",
+    backoffCoefficient: 2.0,
+  },
+});
+// Failure-record stub: EXACTLY ONE attempt — the streak increment is the
+// clock's single non-idempotent write. A retry after a successful write
+// over-counts and pauses a healthy schedule early; a lost write
+// under-counts, which fails safe.
+const failureActivities = proxyActivities<ScheduleTickActivities>({
+  startToCloseTimeout: "30 seconds",
+  retry: { maximumAttempts: 1 },
+});
+
+/**
+ * Executes one tick (Go TickWorkflow.Run; registered as "schedule/tick"
+ * via the barrel). The single argument is the schedule resource id
+ * (Temporal bakes action args once — the nominal fire time is derived,
+ * never carried).
+ */
+export async function tick(scheduleResourceId: string): Promise<void> {
+  const nominal = nominalFireTime(scheduleResourceId);
+  const nominalRfc3339 = rfc3339Seconds(nominal);
+
+  const tickOutcome = await failing(
+    "record tick",
+    recordActivities[RECORD_TICK_ACTIVITY_NAME](
+      scheduleResourceId,
+      nominalRfc3339,
+    ),
+  );
+  if (tickOutcome !== TICK_FIRED) {
+    log.info("Schedule tick complete", {
+      schedule_id: scheduleResourceId,
+      nominal_fire_time: nominalRfc3339,
+      outcome: tickOutcome,
+    });
+    return;
+  }
+
+  const runStart = await failing(
+    "start scheduled run",
+    startActivities[START_SCHEDULED_RUN_ACTIVITY_NAME](
+      scheduleResourceId,
+      nominalRfc3339,
+    ),
+  );
+
+  switch (runStart.outcome) {
+    case RUN_SKIPPED:
+      log.info("Schedule tick complete", {
+        schedule_id: scheduleResourceId,
+        nominal_fire_time: nominalRfc3339,
+        run_outcome: runStart.outcome,
+      });
+      return;
+    case RUN_TARGET_MISSING:
+    case RUN_REFUSED: {
+      // The run never existed: the streak counts the fire, the completion
+      // verdicts do not.
+      const recorded = await failing(
+        "record start failure",
+        failureActivities[RECORD_FAILED_RUN_ACTIVITY_NAME](
+          scheduleResourceId,
+          runStart.failureReason,
+          FAILURE_START_FAILED,
+        ),
+      );
+      log.info("Schedule tick complete", {
+        schedule_id: scheduleResourceId,
+        nominal_fire_time: nominalRfc3339,
+        run_outcome: runStart.outcome,
+        verdict: "start_failed",
+        consecutive_failures: recorded.consecutiveFailures,
+        paused: recorded.paused,
+      });
+      return;
+    }
+    case RUN_STARTED:
+    case RUN_ALREADY_STARTED:
+      await trackRun(scheduleResourceId, nominalRfc3339, runStart);
+      return;
+    default: {
+      // Compile-time exhaustiveness; the runtime throw stands for
+      // deserialized history data outside the union.
+      const exhaustive: never = runStart.outcome;
+      throw ApplicationFailure.nonRetryable(
+        `unknown run outcome "${String(exhaustive)}"`,
+      );
+    }
+  }
+}
+
+/**
+ * Polls the run to a terminal phase within this fire's budget and records
+ * the verdict (Go trackRun).
+ */
+async function trackRun(
+  scheduleResourceId: string,
+  nominalRfc3339: string,
+  runStart: RunStart,
+): Promise<void> {
+  const deadline = Date.now() + runStart.trackingTimeoutMinutes * 60_000;
+
+  let phase: RunPhase = PHASE_RUNNING;
+  let budgetExhausted = false;
+  // Poll-first, deadline checked after each poll and before each sleep: an
+  // ALREADY_STARTED retry may already be terminal, and the loop must never
+  // sleep past its own deadline.
+  for (let cycle = 1; ; cycle++) {
+    if (cycle > MAX_TRACKING_CYCLES) {
+      budgetExhausted = true;
+      break;
+    }
+    // DB unreachable past the activity's own retries: fail the tick with
+    // NO verdict — guessing "failed" during an outage could pause a
+    // healthy schedule. The artifact stays armed (PauseOnFailure=false);
+    // the next fire is unaffected.
+    phase = await failing(
+      "poll execution phase",
+      recordActivities[POLL_EXECUTION_PHASE_ACTIVITY_NAME](runStart.executionId),
+    );
+    if (phase !== PHASE_RUNNING) {
+      break;
+    }
+    if (Date.now() >= deadline) {
+      budgetExhausted = true;
+      break;
+    }
+    await sleep(trackingBackoffMs(cycle));
+  }
+
+  if (budgetExhausted) {
+    // The run is NOT cancelled: its own execution profile bounds spend,
+    // and a destructive act buys nothing. Under SKIP this budget is
+    // literally the maximum time one hung run may silence the schedule.
+    const reason = `run ${runStart.executionId} did not finish within ${runStart.trackingTimeoutMinutes} minutes`;
+    const recorded = await failing(
+      "record tracking timeout",
+      failureActivities[RECORD_FAILED_RUN_ACTIVITY_NAME](
+        scheduleResourceId,
+        reason,
+        FAILURE_RUN_TIMED_OUT,
+      ),
+    );
+    logVerdict(scheduleResourceId, nominalRfc3339, runStart, "timed_out", recorded);
+    return;
+  }
+  if (phase === PHASE_COMPLETED) {
+    await failing(
+      "record successful run",
+      recordActivities[RECORD_SUCCESSFUL_RUN_ACTIVITY_NAME](scheduleResourceId),
+    );
+    logVerdict(scheduleResourceId, nominalRfc3339, runStart, "completed");
+    return;
+  }
+  if (phase === PHASE_GONE) {
+    // Deleting a run must not brick its schedule: no verdict.
+    logVerdict(scheduleResourceId, nominalRfc3339, runStart, "gone");
+    return;
+  }
+  // FAILED, CANCELLED, TERMINATED.
+  const reason = `run ${runStart.executionId} ended ${phase.toLowerCase()}`;
+  const recorded = await failing(
+    "record failed run",
+    failureActivities[RECORD_FAILED_RUN_ACTIVITY_NAME](
+      scheduleResourceId,
+      reason,
+      FAILURE_RUN_FAILED,
+    ),
+  );
+  logVerdict(
+    scheduleResourceId,
+    nominalRfc3339,
+    runStart,
+    phase.toLowerCase(),
+    recorded,
+  );
+}
+
+/**
+ * The delay before the next phase poll: linear cycle×5s capped at 60s —
+ * recoveryBackoff's exact shape, the only backoff curve this platform runs
+ * in production workflow code. It notices a 30-120s run (the common case)
+ * within seconds and reaches its cap by cycle twelve, bounding poll volume
+ * on long runs (Go trackingBackoff). Exported for the curve's unit pin.
+ */
+export function trackingBackoffMs(cycle: number): number {
+  const ms = cycle * 5_000;
+  return ms > 60_000 ? 60_000 : ms;
+}
+
+/**
+ * Derives THE fire's nominal time, three tiers (Go nominalFireTime):
+ *  1. The TemporalScheduledStartTime search attribute (cron fires and
+ *     manual triggers both carry it — spike-verified on the Go side).
+ *  2. The workflow-id suffix Temporal appends to the artifact's base id.
+ *  3. Workflow time truncated to whole seconds (a hand-started tick).
+ *
+ * The nominal time is the fire's identity: last_fire_at records it and the
+ * execution name derives from it, so both idempotency keys agree on every
+ * retry.
+ */
+function nominalFireTime(scheduleResourceId: string): Date {
+  const attribute = workflowInfo().typedSearchAttributes.get(
+    SCHEDULED_START_TIME_KEY,
+  );
+  if (attribute !== undefined) {
+    return attribute;
+  }
+  const base = `${artifactId(scheduleResourceId)}-`;
+  const workflowId = workflowInfo().workflowId;
+  if (workflowId.startsWith(base)) {
+    const suffix = workflowId.slice(base.length);
+    // Go time.Parse(time.RFC3339) is strict; Date() is lenient — the
+    // pattern guard keeps a non-RFC3339 suffix falling to tier 3 exactly
+    // as Go's parse error does.
+    if (RFC3339_PATTERN.test(suffix)) {
+      const parsed = new Date(suffix);
+      if (!Number.isNaN(parsed.getTime())) {
+        return parsed;
+      }
+    }
+  }
+  // Date.now() is deterministic workflow time inside the sandbox — Go's
+  // workflow.Now twin.
+  return new Date(Math.floor(Date.now() / 1000) * 1000);
+}
+
+/**
+ * Maps a failed activity to Go's `return fmt.Errorf("<label>: %w", err)` —
+ * a WORKFLOW failure (see the module header's error posture). Cancellation
+ * failures propagate untouched.
+ */
+async function failing<T>(label: string, promise: Promise<T>): Promise<T> {
+  try {
+    return await promise;
+  } catch (error) {
+    if (error instanceof ApplicationFailure || isCancellation(error)) {
+      throw error;
+    }
+    throw ApplicationFailure.create({
+      message: `${label}: ${error instanceof Error ? error.message : String(error)}`,
+      cause: error instanceof Error ? error : undefined,
+    });
+  }
+}
+
+/** Anchored RFC-3339 shape (Z or numeric offset, optional fraction). */
+const RFC3339_PATTERN =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+/** Go time.RFC3339, UTC whole seconds (the wire shape the activities pin). */
+function rfc3339Seconds(date: Date): string {
+  return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function logVerdict(
+  scheduleResourceId: string,
+  nominalRfc3339: string,
+  runStart: RunStart,
+  verdict: string,
+  recorded?: FailureRecorded,
+): void {
+  if (recorded === undefined) {
+    log.info("Schedule tick complete", {
+      schedule_id: scheduleResourceId,
+      nominal_fire_time: nominalRfc3339,
+      run_outcome: runStart.outcome,
+      execution_id: runStart.executionId,
+      verdict,
+    });
+    return;
+  }
+  log.info("Schedule tick complete", {
+    schedule_id: scheduleResourceId,
+    nominal_fire_time: nominalRfc3339,
+    run_outcome: runStart.outcome,
+    execution_id: runStart.executionId,
+    verdict,
+    consecutive_failures: recorded.consecutiveFailures,
+    paused: recorded.paused,
+  });
+}