@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/schedule/cron.ts

@@ -0,0 +1,150 @@
+/**
+ * Lexical cron and time-zone validation — ports
+ * pkg/domain/schedule/controller/cron.go (DD-009 C-4).
+ *
+ * The platform owns NO cron parsing in either edition — calendar and DST
+ * semantics live in the Temporal server (DD-008 D2). This module restricts
+ * the accepted GRAMMAR to the subset that is safe to store: the classic
+ * 5-field form plus the @daily-family shorthands. Everything rejected here
+ * is something Temporal's wider grammar would accept but that must not
+ * reach a stored spec (timezone prefixes carry a second timezone authority
+ * and fail at artifact-create time; @every bypasses the calendar model;
+ * 6/7-field forms defeat the structural one-minute floor; "#" comments are
+ * noise).
+ *
+ * Both server editions and the cloud Java edition mirror these checks with
+ * byte-identical messages; the shared rejection matrix is pinned by unit
+ * tests on every side. Widening this grammar later is additive; narrowing
+ * it would break stored specs — start narrow.
+ */
+import { invalidArgumentError } from "../../pipeline/errors.js";
+
+/**
+ * The accepted @-shorthands — deliberately only the calendar ones Temporal
+ * documents (no @every, and none of the nonstandard aliases like @annually
+ * or @midnight some cron implementations accept).
+ */
+const CRON_SHORTHANDS = new Set([
+  "@hourly",
+  "@daily",
+  "@weekly",
+  "@monthly",
+  "@yearly",
+]);
+
+/**
+ * Bounds each field to the character set of Temporal's CalendarSpec
+ * ranges: digits, month/day names (Jan, MON), '*', ',', '-', '/'.
+ * Quartz-isms ('?', 'L', 'W', '#') and anything else are rejected —
+ * Temporal does not implement them.
+ */
+const CRON_FIELD_PATTERN = /^[0-9A-Za-z*,/-]+$/;
+
+/**
+ * Enforces the DD-009 C-4 grammar; throws InvalidArgument with the
+ * cross-edition byte-pinned copy. Pure and deterministic.
+ */
+export function validateScheduleCron(cron: string): void {
+  if (cron.startsWith("CRON_TZ=") || cron.startsWith("TZ=")) {
+    throw invalidArgumentError(
+      "spec.cron must not carry a timezone prefix (CRON_TZ=/TZ=) — spec.time_zone is the single timezone authority",
+    );
+  }
+
+  if (cron.includes("#")) {
+    throw invalidArgumentError("spec.cron must not contain a comment (#)");
+  }
+
+  if (cron.startsWith("@")) {
+    if (cron.startsWith("@every")) {
+      throw invalidArgumentError(
+        "spec.cron must be a calendar expression — @every intervals are not supported",
+      );
+    }
+    if (!CRON_SHORTHANDS.has(cron)) {
+      throw invalidArgumentError(
+        `spec.cron shorthand "${cron}" is not supported — use @hourly, @daily, @weekly, @monthly, or @yearly, or a 5-field cron expression`,
+      );
+    }
+    return;
+  }
+
+  // Go strings.Fields: split on any run of whitespace, no empty fields.
+  const fields = cron.split(/\s+/).filter((field) => field !== "");
+  if (fields.length !== 5) {
+    throw invalidArgumentError(
+      `spec.cron must have exactly 5 fields (minute hour day-of-month month day-of-week); got ${fields.length}`,
+    );
+  }
+
+  for (const field of fields) {
+    if (!CRON_FIELD_PATTERN.test(field)) {
+      throw invalidArgumentError(
+        `spec.cron field "${field}" contains unsupported characters — allowed: digits, names, '*', ',', '-', '/'`,
+      );
+    }
+  }
+}
+
+/**
+ * Requires a name the platform tz database resolves — Go
+ * validateScheduleTimeZone (the Temporal server loads the same database
+ * when it evaluates the cron, DD-008 D2).
+ *
+ * "Local" is rejected explicitly: Go resolves it to the host's zone
+ * (nondeterministic across replicas) while Java's ZoneId does not resolve
+ * it at all — accepting it would be a cross-edition divergence on top of a
+ * correctness bug. The EMPTY string is valid, as in Go: time.LoadLocation("")
+ * is UTC (and the artifact's empty TimeZoneName means UTC to Temporal).
+ */
+export function validateScheduleTimeZone(timeZone: string): void {
+  if (timeZone === "Local" || !isLoadableTimeZone(timeZone)) {
+    throw invalidArgumentError(
+      `spec.time_zone "${timeZone}" is not a valid IANA time zone (e.g. "Asia/Kolkata")`,
+    );
+  }
+}
+
+// The canonical IANA zone list ICU ships (exact case), plus its lowered
+// twin for the case-guard below. Built once — the list is immutable for
+// the process lifetime.
+let canonicalZones: Set<string> | undefined;
+let canonicalZonesLowered: Set<string> | undefined;
+function zoneSets(): { exact: Set<string>; lowered: Set<string> } {
+  if (canonicalZones === undefined || canonicalZonesLowered === undefined) {
+    const values = Intl.supportedValuesOf("timeZone");
+    canonicalZones = new Set(values);
+    canonicalZonesLowered = new Set(values.map((zone) => zone.toLowerCase()));
+  }
+  return { exact: canonicalZones, lowered: canonicalZonesLowered };
+}
+
+/**
+ * The TS spelling of Go time.LoadLocation's yes/no answer. ICU (behind
+ * Intl) resolves zone names CASE-INSENSITIVELY (and may canonicalize
+ * through historical aliases, e.g. asia/kolkata → Asia/Calcutta) while
+ * Go's tzdata file lookup is case-sensitive. The guard restores Go's
+ * refusal: an input that is a mere case-variant of a canonical zone is
+ * rejected; genuine links ("US/Pacific") pass through ICU acceptance as
+ * they do in Go. Residual divergence — a case-variant of a LINK name —
+ * is a disclosed parity nuance (PR register), not silently absorbed.
+ */
+export function isLoadableTimeZone(timeZone: string): boolean {
+  if (timeZone === "") {
+    return true; // Go LoadLocation("") — UTC.
+  }
+  const { exact, lowered } = zoneSets();
+  if (exact.has(timeZone)) {
+    return true;
+  }
+  // A case-variant of a canonical zone: ICU would accept it, Go refuses.
+  if (lowered.has(timeZone.toLowerCase())) {
+    return false;
+  }
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/domain/schedule/list-runs.ts

@@ -0,0 +1,245 @@
+/**
+ * The listRuns query steps — port pkg/domain/schedule/controller/list_runs.go:
+ * the fire-ledger surface (DD-017 D-7). Every fire leaves a row, INCLUDING
+ * fires that created no execution (a refused launch gate, a missing target
+ * agent), with the refusing gate's copy verbatim: this is the RPC that
+ * explains status.consecutive_failures.
+ *
+ * Rows carrying an execution id but no terminal outcome are enriched with
+ * the execution's LIVE phase at read time — manual fires are untracked by
+ * design (the caller watches the execution), so their outcome is resolved
+ * here rather than by a tracker, and outcome columns never lie while a run
+ * is in flight.
+ */
+import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ScheduleQueryController } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/query_pb";
+import {
+  ScheduleRunListSchema,
+  ScheduleRunOrigin,
+  ScheduleRunOutcome,
+  ScheduleRunSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/io_pb";
+import type { ScheduleRun } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { internalError, notFoundError } from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { ScheduleRunRecord, Store } from "../../store/interface.js";
+
+type ListRunsInput = typeof ScheduleQueryController.method.listRuns.input;
+
+export const LIST_RUNS_RESULT_KEY = "listRunsResult";
+
+/**
+ * Bounds an unpaginated listRuns read — history can hold a quarter's worth
+ * of daily fires, and "the recent runs" is the question the surface
+ * answers (Go defaultRunsPageSize).
+ */
+export const DEFAULT_RUNS_PAGE_SIZE = 50;
+
+/**
+ * Confirms the schedule exists — a missing schedule answers NOT_FOUND,
+ * never an empty history that reads as "exists but never fired" (Go
+ * loadScheduleForRunsStep).
+ */
+export function newLoadScheduleForRunsStep(store: Store): PipelineStep<ListRunsInput> {
+  return {
+    name: "LoadScheduleForRuns",
+    async execute(ctx: RequestContext<ListRunsInput>): Promise<void> {
+      const scheduleId = ctx.input.scheduleId;
+      try {
+        await store.getResource(
+          ApiResourceKind.schedule,
+          scheduleId,
+          ScheduleSchema,
+        );
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("Schedule", scheduleId);
+        }
+        throw internalError(error, "failed to load schedule");
+      }
+    },
+  };
+}
+
+/**
+ * Pages the fire ledger (newest first) and enriches in-flight rows with
+ * the execution's live phase (Go listRunsFromLedgerStep).
+ */
+export function newListRunsFromLedgerStep(store: Store): PipelineStep<ListRunsInput> {
+  return {
+    name: "ListRunsFromLedger",
+    async execute(ctx: RequestContext<ListRunsInput>): Promise<void> {
+      const req = ctx.input;
+
+      // PageInfo.num is 1-indexed by contract (pagination.proto); a
+      // zero/absent page reads as the first.
+      let size = req.pageInfo?.size ?? 0;
+      if (size <= 0) {
+        size = DEFAULT_RUNS_PAGE_SIZE;
+      }
+      let num = req.pageInfo?.num ?? 0;
+      if (num < 1) {
+        num = 1;
+      }
+      const offset = (num - 1) * size;
+
+      let runs: ScheduleRunRecord[];
+      let total: number;
+      try {
+        ({ runs, total } = await store.listScheduleRuns(
+          req.scheduleId,
+          offset,
+          size,
+        ));
+      } catch (error) {
+        throw internalError(error, "failed to list schedule runs");
+      }
+
+      const items: ScheduleRun[] = [];
+      for (const record of runs) {
+        items.push(await toProtoRun(store, record));
+      }
+
+      ctx.set(
+        LIST_RUNS_RESULT_KEY,
+        create(ScheduleRunListSchema, { totalCount: total, items }),
+      );
+    },
+  };
+}
+
+/**
+ * Maps one ledger row to the wire, enriching a non-terminal row that
+ * carries an execution id with the execution's live phase — the read-time
+ * honesty rule (Go toProtoRun).
+ */
+async function toProtoRun(
+  store: Store,
+  record: ScheduleRunRecord,
+): Promise<ScheduleRun> {
+  const run = create(ScheduleRunSchema, {
+    scheduleId: record.scheduleId,
+    org: record.org,
+    origin: runOriginFromLabel(record.origin),
+    outcome: runOutcomeFromLabel(record.outcome),
+    reason: record.reason,
+    executionId: record.executionId,
+  });
+  const nominal = parseTime(record.nominalFireTime);
+  if (nominal !== undefined) {
+    run.nominalFireTime = timestampFromDate(nominal);
+  }
+  const recordedAt = parseTime(record.recordedAt);
+  if (recordedAt !== undefined) {
+    run.recordedAt = timestampFromDate(recordedAt);
+  }
+  if (record.completedAt !== "") {
+    const completedAt = parseTime(record.completedAt);
+    if (completedAt !== undefined) {
+      run.completedAt = timestampFromDate(completedAt);
+    }
+    return run;
+  }
+
+  // In flight on paper — ask the execution row what actually happened.
+  if (record.executionId === "") {
+    return run;
+  }
+  let phase: ExecutionPhase;
+  try {
+    const execution = await store.getResource(
+      ApiResourceKind.agent_execution,
+      record.executionId,
+      AgentExecutionSchema,
+    );
+    phase = execution.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+  } catch {
+    // Execution deleted (or unreadable): the ledger row stands as
+    // recorded — deleting a run must not rewrite its history.
+    return run;
+  }
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_COMPLETED:
+      run.outcome = ScheduleRunOutcome.COMPLETED;
+      break;
+    case ExecutionPhase.EXECUTION_FAILED:
+    case ExecutionPhase.EXECUTION_CANCELLED:
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      run.outcome = ScheduleRunOutcome.FAILED;
+      run.reason = `run ${record.executionId} ended ${executionPhaseWord(phase)}`;
+      break;
+    default:
+      // Genuinely still running — "started" is the honest answer.
+      break;
+  }
+  return run;
+}
+
+/**
+ * Lowers an ExecutionPhase to the reason vocabulary the tick's verdict
+ * writer uses ("run X ended failed") — Go executionPhaseWord.
+ */
+function executionPhaseWord(phase: ExecutionPhase): string {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_FAILED:
+      return "failed";
+    case ExecutionPhase.EXECUTION_CANCELLED:
+      return "cancelled";
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      return "terminated";
+    default:
+      return "unknown";
+  }
+}
+
+/** Maps the ledger's lowercase origin vocabulary back to the wire enum. */
+function runOriginFromLabel(origin: string): ScheduleRunOrigin {
+  switch (origin) {
+    case "cron":
+      return ScheduleRunOrigin.CRON;
+    case "manual":
+      return ScheduleRunOrigin.MANUAL;
+    default:
+      return ScheduleRunOrigin.UNSPECIFIED;
+  }
+}
+
+/** Maps the ledger's lowercase outcome vocabulary back to the wire enum. */
+function runOutcomeFromLabel(outcome: string): ScheduleRunOutcome {
+  switch (outcome) {
+    case "started":
+      return ScheduleRunOutcome.STARTED;
+    case "refused":
+      return ScheduleRunOutcome.REFUSED;
+    case "target_missing":
+      return ScheduleRunOutcome.TARGET_MISSING;
+    case "skipped":
+      return ScheduleRunOutcome.SKIPPED;
+    case "completed":
+      return ScheduleRunOutcome.COMPLETED;
+    case "failed":
+      return ScheduleRunOutcome.FAILED;
+    case "timed_out":
+      return ScheduleRunOutcome.TIMED_OUT;
+    default:
+      return ScheduleRunOutcome.UNSPECIFIED;
+  }
+}
+
+/** Go's time.Parse(time.RFC3339) tolerance: unparseable leaves the field unset. */
+function parseTime(value: string): Date | undefined {
+  if (value === "") {
+    return undefined;
+  }
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}

package/src/domain/schedule/persist-update.ts

@@ -0,0 +1,76 @@
+/**
+ * The update pipeline's persist step — ports persistScheduleUpdateStep of
+ * pkg/domain/schedule/controller/update.go.
+ *
+ * Persists an update as a graft of exactly what the request path owns —
+ * apiVersion/kind/metadata/spec plus the audit bump BuildUpdateState
+ * stamped — onto the LIVE row, inside one store.updateResource closure.
+ * NOT the generic Persist step: schedule status has a concurrent writer
+ * (the tick), and a full-row save of the load-time snapshot could silently
+ * revert a fire record, a streak write, or a PAUSE — breaking the "resume
+ * is the one clearing path" pin. The OSS twin of the cloud's targeted
+ * metadata+spec+status.audit patch, shaped for a store whose unit of write
+ * is the whole protobuf blob (DD-015 D-C).
+ *
+ * Unlike a save, the graft never resurrects a concurrently deleted row:
+ * updateResource answers not-found, relayed as NOT_FOUND — the delete won,
+ * honestly.
+ */
+import { create } from "@bufbuild/protobuf";
+
+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 { ScheduleStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/status_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { internalError, notFoundError } from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+
+export function newPersistScheduleUpdateStep(
+  store: Store,
+): PipelineStep<typeof ScheduleSchema> {
+  return {
+    name: "PersistScheduleUpdate",
+    async execute(ctx: RequestContext<typeof ScheduleSchema>): Promise<void> {
+      const newState = ctx.newState;
+      const scheduleId = newState.metadata?.id ?? "";
+
+      let live: Schedule;
+      try {
+        live = await store.updateResource(
+          ApiResourceKind.schedule,
+          scheduleId,
+          ScheduleSchema,
+          (row) => {
+            row.apiVersion = newState.apiVersion;
+            row.kind = newState.kind;
+            row.metadata = newState.metadata;
+            row.spec = newState.spec;
+            // The one status subtree the request path owns: its own audit
+            // bump. Every other status leaf stays exactly as the
+            // concurrent runtime last wrote it.
+            if (newState.status?.audit !== undefined) {
+              if (row.status === undefined) {
+                row.status = create(ScheduleStatusSchema);
+              }
+              row.status.audit = newState.status.audit;
+            }
+          },
+        );
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("Schedule", scheduleId);
+        }
+        throw internalError(error, "failed to persist schedule update");
+      }
+
+      // Answer with the persisted post-image: the new spec plus the LIVE
+      // status — fresher than the load-time snapshot, and honest about
+      // anything the runtime wrote mid-request.
+      ctx.setNewState(live);
+    },
+  };
+}

package/src/domain/schedule/resume.ts

@@ -0,0 +1,122 @@
+/**
+ * The resume command's clearing step — ports
+ * pkg/domain/schedule/controller/resume.go.
+ *
+ * "Paused" is the platform's latch (status.paused_reason, written by the
+ * failure-streak auto-pause), distinct from "disabled", the owner's switch
+ * (spec.enabled) — DD-013 D-E. Resume clears the latch and resets
+ * status.consecutive_failures, and is deliberately the ONLY path that does
+ * either (DD-013 D-D): update and apply preserve status verbatim, so a
+ * routine manifest apply can never silently un-pause a failing schedule.
+ *
+ * Resuming a schedule that is not paused (and has no failure streak)
+ * succeeds and changes nothing — no write, no audit bump. A disabled
+ * schedule stays disabled: the latch and the switch are independent.
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+
+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 { internalError, notFoundError } from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import { setAuditFieldsForUpdate } from "../../pipeline/steps/defaults.js";
+import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+
+/**
+ * Aborts the atomic write on the idempotent no-op path — the fresh row has
+ * no latch and no streak, so nothing is written and no audit bumps (Go
+ * errResumeNothingToClear).
+ */
+class NothingToClearError extends Error {
+  constructor() {
+    super("nothing to clear");
+    this.name = "NothingToClearError";
+  }
+}
+
+/**
+ * Clears status.paused_reason and resets status.consecutive_failures in
+ * ONE store.updateResource closure on the freshly-read row, preserving
+ * every other status leaf as the concurrent runtime last wrote it (Go
+ * clearSchedulePauseStep).
+ *
+ * This is the revisit DD-013 D-D reserved for the clock slice: a previous
+ * load-mutate-save across step boundaries was safe only while nothing else
+ * wrote schedule status. The clock ended that — a fire recorded (or a
+ * streak advanced) between the load and the save would have been silently
+ * reverted. The agent-execution domain adopted this exact primitive after
+ * losing user approvals to the same race class.
+ */
+export function newClearSchedulePauseStep<Desc extends DescMessage>(
+  store: Store,
+): PipelineStep<Desc> {
+  return {
+    name: "ClearSchedulePause",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const loaded = ctx.get(EXISTING_RESOURCE_KEY) as Schedule;
+      const scheduleId = loaded.metadata?.id ?? "";
+
+      let live: Schedule;
+      try {
+        live = await store.updateResource(
+          ApiResourceKind.schedule,
+          scheduleId,
+          ScheduleSchema,
+          (row) => {
+            const status = row.status;
+            if (
+              (status?.pausedReason ?? "") === "" &&
+              (status?.consecutiveFailures ?? 0) === 0
+            ) {
+              throw new NothingToClearError();
+            }
+            // status is defined here: a latch or streak exists only on a
+            // materialized status message.
+            row.status!.pausedReason = "";
+            // Resuming with strikes left would re-pause on the next
+            // failure — a lie; both clear together, always.
+            row.status!.consecutiveFailures = 0;
+            setAuditFieldsForUpdate(
+              ScheduleSchema,
+              row,
+              "status_audit",
+              ctx.callerIdentity,
+            );
+          },
+        );
+      } catch (error) {
+        if (error instanceof NothingToClearError) {
+          // The untouched fresh row is the honest response on the no-op
+          // path; updateResource skipped the write, so re-read the live
+          // row (Go's out-param `live` holds it either way).
+          try {
+            live = await store.getResource(
+              ApiResourceKind.schedule,
+              scheduleId,
+              ScheduleSchema,
+            );
+          } catch (readError) {
+            if (readError instanceof ResourceNotFoundError) {
+              throw notFoundError("Schedule", scheduleId);
+            }
+            throw internalError(readError, "failed to resume schedule");
+          }
+          ctx.set(EXISTING_RESOURCE_KEY, live);
+          return;
+        }
+        if (error instanceof ResourceNotFoundError) {
+          // Deleted between load and clear: the delete won.
+          throw notFoundError("Schedule", scheduleId);
+        }
+        throw internalError(error, "failed to resume schedule");
+      }
+      // live holds the post-image (cleared) — the honest response.
+      ctx.set(EXISTING_RESOURCE_KEY, live);
+    },
+  };
+}